Metadata-Version: 2.4
Name: csrd-utils
Version: 0.3.34
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: pyyaml<7,>=6
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
csrd new workspace                                # create workspace, then choose none/service/cluster
csrd new service                                  # requires workspace; prompts to create one if missing
csrd new service --interactive --name items       # pre-fills name prompt with 'items'
csrd new service --name inventory --no-interactive --output ./my-workspace
csrd new service --name pricing --output ./my-workspace --no-interactive
csrd new cluster --spec ./cluster.yaml --output ./my-workspace
csrd new cluster                                  # requires workspace; interactive mode can offer to create one
csrd feature list
csrd feature plan workers --service .
csrd feature plan workers --service . --json
csrd feature add workers --service .
csrd doctor --service .
csrd audit                                          # if cwd is workspace, audits all services
csrd audit --service .                              # explicitly audit one service path
csrd completion bash                                # print bash completion script
```

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

### Bash tab completion

Enable command/subcommand completion in bash:

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

Then examples like `csrd ne<TAB>` and `csrd new wor<TAB>` complete to `new` and `workspace`.

### Workspace extraction command

Service extraction into a sibling workspace is supported:

```bash
csrd workspace extract-service --service ./source-ws/src/pricing --target-workspace ../pricing-ws --mode copy
csrd workspace extract-service --service ./source-ws/src/pricing --target-workspace ../pricing-ws --mode move
csrd workspace extract-service --service ./source-ws/src/pricing --target-workspace ../pricing-ws --dry-run --json
```

Use extraction when service ownership diverges, release cadence becomes independent,
or workspace orchestration starts coupling unrelated deployments.

Manual fallback remains available if needed:

```bash
csrd new workspace --name pricing-ws --output .. --generate none
cp -a ./source-ws/src/pricing ../pricing-ws/src/pricing
cd ../pricing-ws
csrd new cluster --spec ./.csrd/cluster.yaml --output . --force
```

### Interactive generation behavior

- `csrd new service` and `csrd new cluster` are workspace-first commands.
- If a workspace marker is missing in the selected output path, interactive flows ask to create one and continue.
- Non-interactive generation errors when no workspace marker is present.
- Workspace cluster source of truth is persisted at `.csrd/cluster.yaml`.
- If `.csrd/cluster.yaml` already exists, `csrd new service` appends the generated service and refreshes scaffold files (`docker-compose.yml`, `.env.example`, `README.md`, `smoke.sh`). Service source directories and running containers are never touched.
- If `.csrd/cluster.yaml` is missing, `csrd new service` bootstraps `.csrd/cluster.yaml` and writes initial cluster scaffold files.
- `csrd new service` runs a compact interactive flow by default (core prompts 1-6), then asks whether to show advanced options.
- `csrd new workspace` creates a workspace directory and prompts whether to generate `none`, `service`, or `cluster` immediately.
- In compact mode, advanced options are hidden by default.
- `csrd new service --interactive` runs the full verbose interactive flow.
- Passing `--name <value>` in interactive mode uses that value as the name prompt default.
- You can still overwrite the default by entering a different value at the prompt.
- Use `--no-interactive` for fully flag-driven generation.
- Database default is `none`.
- All yes/no prompts default to `No` (`y/N`).

## Typical workflow

```bash
# 0) Create a workspace and generate a service inside it
csrd new workspace --name local-dev --output . --generate none
csrd new service --name inventory --output ./local-dev --database postgres --workers

# 1) Verify service compatibility
csrd doctor --service ./local-dev/src/inventory

# 1b) Audit for weak/insecure defaults
csrd audit --service ./local-dev/src/inventory

# 2) Inspect available bundled features
csrd feature list

# 3) Dry-run a feature
csrd feature plan workers --service ./local-dev/src/inventory

# 4) Apply feature files/merges
csrd feature add workers --service ./local-dev/src/inventory

# 5) Add a second service — workspace auto-upgrades to cluster
csrd new service --name pricing --output ./local-dev --database postgres
```

## Bundled assets

- `features/workers/` feature manifests and fragments
- `templates/cookiecutter-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 new --help
csrd new workspace --help
csrd new service --help
csrd new cluster --help
csrd feature --help
csrd doctor --help
csrd audit --help
csrd feature list
```

Then run a clean smoke flow:

```bash
mkdir -p /tmp/csrd-smoke
csrd new workspace --name ws --output /tmp/csrd-smoke --generate none
csrd new service --name demo-svc --output /tmp/csrd-smoke/ws --no-interactive
csrd doctor --service /tmp/csrd-smoke/ws/src/demo-svc
csrd audit --service /tmp/csrd-smoke/ws/src/demo-svc
csrd feature plan workers --service /tmp/csrd-smoke/ws/src/demo-svc
csrd feature add workers --service /tmp/csrd-smoke/ws/src/demo-svc
```
