Metadata-Version: 2.4
Name: csrd-utils
Version: 0.5.24
Summary: CLI utilities for csrd service generation and feature augmentation
Project-URL: Repository, https://github.com/csrd-api/fastapi-common
Project-URL: Documentation, https://github.com/csrd-api/fastapi-common/tree/main/packages/utils
Project-URL: Changelog, https://github.com/csrd-api/fastapi-common/blob/main/CHANGELOG.md
License: MIT
Requires-Python: >=3.12
Requires-Dist: cookiecutter<3,>=2.6
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: pyyaml<7,>=6
Requires-Dist: ruamel-yaml<1,>=0.18
Description-Content-Type: text/markdown

# csrd-utils

CLI and runtime helpers for generating csrd services and augmenting existing services with optional features.

## Install

```bash
pip install "csrd-utils @ git+https://github.com/csrd-api/fastapi-common.git#subdirectory=packages/utils"
```

## CLI

```bash
csrd --help
csrd --version

# Workspace-level generation (compose-based)
csrd generate                                     # interactive menu (context-aware)
csrd generate workspace --name my-ws              # create empty workspace
csrd generate preset --name my-ws                 # create workspace from preset
csrd generate add-service --name inventory        # add service to current workspace
csrd generate rename-service --service-name old-service --new-name new-service
csrd generate remove-service --service-name old   # remove service from spec
csrd generate add-infra --infra-type postgres     # add infra to workspace
csrd generate remove-infra --infra-type postgres  # remove infra from workspace
csrd generate add-augment                         # interactive augment selection
csrd generate list-augments                       # list available augments

# Feature augmentation
csrd feature list
csrd feature plan workers --service .
csrd feature plan workers --service . --json
csrd feature add workers --service .

# Diagnostics
csrd doctor --service .
csrd audit                                        # workspace-aware: scans all services
csrd audit --service .                            # explicitly audit one service path

# Shell completion
csrd completion bash                              # print bash completion script
csrd completion install                           # install to ~/.local/share/bash-completion/
csrd completion uninstall                         # remove installed completion
```

`feature plan --json` is useful for CI or tooling wrappers.

### Bash tab completion

Install completion (one-time, persists across shells):

```bash
csrd completion install
```

This writes a completion script to `~/.local/share/bash-completion/completions/csrd`,
which bash auto-loads — no `.bashrc` edit needed. To remove: `csrd completion uninstall`.

Manual alternative:

```bash
source <(csrd completion bash)
```

### Non-TTY mode

Set `CSRD_NO_TTY=1` to force numbered-fallback prompts instead of the
arrow-key TUI. Useful for manual testing or piping input:

```bash
CSRD_NO_TTY=1 csrd generate
```

### Interactive generation behavior

- `csrd generate` shows a context-aware menu (workspace actions when inside a workspace, workspace creation otherwise).
- Services, augments, and infra are managed via `csrd-compose.yaml` (the workspace spec).
- `csrd generate rename-service` renames the service in the spec, renames `src/`, `tests/`, and `Dockerfile.*`, and rewrites Python imports and string references.
- All yes/no prompts default to `No` (`y/N`).

## Typical workflow

```bash
# 0) Create a workspace and add services
csrd generate workspace --name local-dev
cd local-dev
csrd generate add-service --name inventory --features database --port 8081
csrd generate add-service --name pricing --port 8082

# 1) Verify service compatibility
csrd doctor --service .

# 1b) Audit for weak/insecure defaults
csrd audit

# 2) Inspect available bundled features
csrd feature list

# 3) Dry-run a feature
csrd feature plan workers --service .

# 4) Apply feature files/merges
csrd feature add workers --service .

# 5) Rename a service
csrd generate rename-service --service-name pricing-service --new-name billing-service
```

## Bundled assets

- `features/workers/` feature manifests and fragments
- `templates/service/` template starter

## Python API

```python
from pathlib import Path
from csrd_utils import ServiceAugmentor
from csrd_utils.resources import features_path

with features_path() as feature_lib:
    augmentor = ServiceAugmentor(Path("."), feature_lib)
    ok, changes = augmentor.add_feature("workers", plan=True)
```

## Documentation

- `docs/CLI_REFERENCE.md` - full command/flag reference
- `docs/FEATURES.md` - bundled feature catalog and behavior
- `docs/FUTURE_WORK.md` - remaining provider-specific CI wiring work (Phase 5B)
- `docs/AGENT_SMOKE_TESTS.md` - copy/paste validation flow for clean workspaces
- `docs/COMMAND_MATRIX.yaml` - machine-readable command matrix for automation
- `AGENTS.md` - package-local rules for autonomous agents

## CLI-only agent mode

If an agent can only see the installed CLI (not source files), use this exploration sequence:

```bash
csrd --help
csrd generate --help
csrd feature --help
csrd doctor --help
csrd audit --help
csrd completion --help
csrd feature list
csrd generate list-augments
```

Then run a clean smoke flow:

```bash
mkdir -p /tmp/csrd-smoke && cd /tmp/csrd-smoke
csrd generate workspace --name ws
cd ws
csrd generate add-service --name demo-svc --port 8080
csrd doctor --service .
csrd audit
csrd feature plan workers --service .
csrd feature add workers --service .
csrd generate rename-service --service-name demo-svc-service --new-name renamed-svc
```
