Metadata-Version: 2.4
Name: csrd-utils
Version: 0.3.8
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 service                                  # compact interactive mode (prompts 1-6, then advanced gate)
csrd new service --interactive --name items       # pre-fills name prompt with 'items'
csrd new service --name inventory --no-interactive --output .
csrd feature list
csrd feature plan workers --service .
csrd feature plan workers --service . --json
csrd feature add workers --service .
csrd doctor --service .
```

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

### Interactive generation behavior

- `csrd new service` runs a compact interactive flow by default (core prompts 1-6), then asks whether to show advanced options.
- 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) Generate a new service from bundled template
csrd new service --name inventory --output . --database postgres --workers

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

# 2) Inspect available bundled features
csrd feature list

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

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

## 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/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 feature --help
csrd doctor --help
csrd feature list
```

Then run a clean smoke flow:

```bash
mkdir -p /tmp/csrd-smoke
cd /tmp/csrd-smoke
csrd new service --name demo-svc --output . --no-interactive
cd demo-svc
csrd doctor
csrd feature plan workers
csrd feature add workers
```
