csrd-utils 0.5.0__tar.gz → 0.5.2__tar.gz

csrd_utils-0.5.2/PKG-INFO

@@ -0,0 +1,177 @@
+Metadata-Version: 2.4
+Name: csrd-utils
+Version: 0.5.2
+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
+```

csrd_utils-0.5.2/README.md

@@ -0,0 +1,162 @@
+# 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
+```

{csrd_utils-0.5.0 → csrd_utils-0.5.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "csrd-utils"
-version = "0.5.0"
+version = "0.5.2"
 description = "CLI utilities for csrd service generation and feature augmentation"
 license = { text = "MIT" }
 requires-python = ">=3.12"

{csrd_utils-0.5.0 → csrd_utils-0.5.2}/src/csrd_utils/__main__.py

@@ -86,6 +86,43 @@ def _render_bash_completion(parser: argparse.ArgumentParser) -> str:
     return "\n".join(lines) + "\n"
 
 
+# ---------------------------------------------------------------------------
+# Completion install/uninstall
+# ---------------------------------------------------------------------------
+
+_COMPLETION_DIR = Path.home() / ".local" / "share" / "bash-completion" / "completions"
+_COMPLETION_FILE = _COMPLETION_DIR / "csrd"
+
+
+def _install_completion(parser: argparse.ArgumentParser) -> int:
+    """Write the bash completion script to the user completions directory.
+
+    bash-completion auto-loads files from ``~/.local/share/bash-completion/completions/``
+    so no ``.bashrc`` edit is needed.
+    """
+
+    _COMPLETION_DIR.mkdir(parents=True, exist_ok=True)
+    already = _COMPLETION_FILE.is_file()
+    _COMPLETION_FILE.write_text(_render_bash_completion(parser), encoding="utf-8")
+    if already:
+        print(f"Updated bash completion at {_COMPLETION_FILE}")
+    else:
+        print(f"Installed bash completion to {_COMPLETION_FILE}")
+        print("Open a new shell to activate.")
+    return 0
+
+
+def _uninstall_completion() -> int:
+    """Remove the installed bash completion file."""
+
+    if _COMPLETION_FILE.is_file():
+        _COMPLETION_FILE.unlink()
+        print(f"Removed {_COMPLETION_FILE}")
+    else:
+        print("No completion file installed.")
+    return 0
+
+
 # ---------------------------------------------------------------------------
 # Parser
 # ---------------------------------------------------------------------------
@@ -115,6 +152,7 @@ def _build_parser() -> argparse.ArgumentParser:
             "remove-infra",
             "add-augment",
             "remove-service",
+            "rename-service",
             "list-augments",
             "empty",
         ],
@@ -146,7 +184,13 @@ def _build_parser() -> argparse.ArgumentParser:
         "--service-name",
         dest="service_name",
         default=None,
-        help="Service name (for remove-service)",
+        help="Service name (for remove-service / rename-service)",
+    )
+    gen.add_argument(
+        "--new-name",
+        dest="new_name",
+        default=None,
+        help="New service name (for rename-service)",
     )
 
     # ── compose ───────────────────────────────────────────────────────
@@ -189,6 +233,8 @@ def _build_parser() -> argparse.ArgumentParser:
     completion = sub.add_parser("completion", help="Shell completion helpers")
     completion_sub = completion.add_subparsers(dest="completion_shell", required=True)
     completion_sub.add_parser("bash", help="Print bash completion script")
+    completion_sub.add_parser("install", help="Install bash completion to ~/.local/share")
+    completion_sub.add_parser("uninstall", help="Remove installed bash completion")
 
     return parser
 
@@ -232,6 +278,7 @@ def main() -> int:
             port=getattr(args, "port", None),
             infra_type=getattr(args, "infra_type", None),
             service_name=getattr(args, "service_name", None),
+            new_name=getattr(args, "new_name", None),
         )
 
     # ── compose ───────────────────────────────────────────────────────
@@ -329,9 +376,15 @@ def main() -> int:
                 print(f"  fix: {finding.remediation}")
         return 0 if audit_report.ok else 1
 
-    if args.command == "completion" and getattr(args, "completion_shell", None) == "bash":
-        print(_render_bash_completion(parser), end="")
-        return 0
+    if args.command == "completion":
+        shell = getattr(args, "completion_shell", None)
+        if shell == "bash":
+            print(_render_bash_completion(parser), end="")
+            return 0
+        if shell == "install":
+            return _install_completion(parser)
+        if shell == "uninstall":
+            return _uninstall_completion()
 
     parser.print_help()
     return 0

{csrd_utils-0.5.0 → csrd_utils-0.5.2}/src/csrd_utils/compose/__init__.py

@@ -32,7 +32,6 @@ from .infra import (
     descriptor_for,
     descriptors_for_feature,
     detect_configured_db,
-    render_infra,
 )
 from .loader import (
     SPEC_FILENAME,
@@ -55,6 +54,7 @@ from .operations import (
     remove_infra,
     remove_service,
     remove_service_augment,
+    rename_service,
     render_workspace,
     validate,
 )
@@ -123,7 +123,7 @@ __all__ = [
     "remove_infra",
     "remove_service",
     "remove_service_augment",
-    "render_infra",
+    "rename_service",
     "render_workspace",
     "save_spec",
     "save_yaml",

{csrd_utils-0.5.0 → csrd_utils-0.5.2}/src/csrd_utils/compose/operations.py

@@ -451,6 +451,45 @@ def remove_service(output_dir: Path, service_name: str) -> ComposeSpec:
     return spec
 
 
+def rename_service(output_dir: Path, old_name: str, new_name: str) -> ComposeSpec:
+    """Rename a service in the workspace spec.
+
+    Updates the service name and any cross-service augment ``targets``
+    options that reference the old name.  Only updates the spec —
+    filesystem renames are the caller's responsibility.
+
+    Raises ``ValueError`` if *old_name* is not found or *new_name*
+    already exists.
+    """
+
+    spec_path = spec_file_path(output_dir)
+    spec = load_spec(spec_path)
+
+    existing_names = {s.name for s in spec.services}
+    if old_name not in existing_names:
+        raise ValueError(f"Service '{old_name}' not found in workspace spec.")
+    if new_name in existing_names:
+        raise ValueError(f"Service '{new_name}' already exists in workspace spec.")
+
+    # Rename the service itself
+    svc = next(s for s in spec.services if s.name == old_name)
+    svc.name = new_name
+
+    # Update cross-service augment target references
+    for other_svc in spec.services:
+        for aug in other_svc.augments:
+            targets = aug.options.get("targets")
+            if targets is None:
+                continue
+            if isinstance(targets, str) and targets == old_name:
+                aug.options["targets"] = new_name
+            elif isinstance(targets, list):
+                aug.options["targets"] = [new_name if t == old_name else t for t in targets]
+
+    save_spec(spec, spec_path)
+    return spec
+
+
 def next_available_port(spec: ComposeSpec, default: int = 8080) -> int:
     """Return the next unused port for a new service.
 

{csrd_utils-0.5.0 → csrd_utils-0.5.2}/src/csrd_utils/compose/renderer.py

@@ -307,14 +307,29 @@ def _render_env_example(spec: ComposeSpec) -> str:
 def _render_readme(spec: ComposeSpec) -> str:
     """Build a starter ``README.md`` for the workspace."""
 
+    svc_lines = ""
+    if spec.services:
+        svc_list = ", ".join(f"`{s.name}` (:{s.port})" for s in spec.services)
+        svc_lines = f"\n## Services\n\n{svc_list}\n"
+
     return (
         f"# {spec.workspace.name}\n\n"
-        "Generated by csrd compose.\n\n"
-        "## Next steps\n\n"
+        "Generated by [csrd](https://github.com/csrd-api/fastapi-common).\n"
+        f"{svc_lines}\n"
+        "## Quick start\n\n"
+        "```bash\n"
+        "docker compose up --build\n"
+        "```\n\n"
+        "## Workspace commands\n\n"
         "```bash\n"
-        "csrd compose validate\n"
-        "csrd compose plan\n"
-        "```\n"
+        "csrd generate                # interactive menu\n"
+        "csrd generate add-service    # add a service\n"
+        "csrd generate rename-service # rename a service\n"
+        "csrd doctor                  # validate service layout\n"
+        "csrd audit                   # scan for insecure defaults\n"
+        "csrd compose validate        # validate csrd-compose.yaml\n"
+        "```\n\n"
+        "Edit `csrd-compose.yaml` then run `csrd compose apply` to re-render.\n"
     )
 
 
@@ -553,11 +568,20 @@ csrd compose apply
 
 # Or use the interactive menu:
 csrd generate
+
+# Rename a service (updates spec, directories, code references):
+csrd generate rename-service
+
+# Install tab completion (one-time):
+csrd completion install
 ```
 
 Rendered files are regenerated from the spec.  Scaffolded files (views,
 repositories, services, dependencies) are never overwritten — your
 custom code is safe.
+
+Set `CSRD_NO_TTY=1` to force numbered-fallback prompts instead of the
+arrow-key TUI (useful for scripting or CI).
 """