agent-scaffold-cli 0.1.1__tar.gz → 0.2.255__tar.gz

{agent_scaffold_cli-0.1.1 → agent_scaffold_cli-0.2.255}/.github/workflows/ci.yml

@@ -22,6 +22,9 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
 
+      - name: Sync bundled deployments
+        run: bash scripts/sync_deployments.sh
+
       - name: Install dependencies
         run: uv sync --dev
 

agent_scaffold_cli-0.2.255/CHANGELOG.md

@@ -0,0 +1,90 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+## 0.2.255 — 2026-05-28
+
+The first minor since `0.1.1`. Headline change: the new **`agent-scaffold scaffold` REPL** — a persistent shell with a guided wizard, slash commands, LLM-interpreted refinements, pre-flight cost estimates, and a tab-completing prompt — replaces the one-shot prompt-for-each-input flow that `agent-scaffold new` used to drive. `new` still works for scripted / non-interactive runs. Also: deployments + blueprints now auto-fetch from GitHub (cached by SHA, ETag-conditional), and the CLI itself has been pulled apart into smaller focused modules (`cli_auth`, `cli_doctor`, `cli_secrets`, plus shared leafs `effort` + `language_hints` + `_scaffold_dir`).
+
+### Highlights
+
+- **Interactive REPL: `agent-scaffold scaffold`.** Persistent shell with the orange→red figlet banner, a `/new` wizard, free-text refinements ("swap to sonnet, add postgres, skip the smoke test"), pre-flight cost estimates, and tab-completion. Stays open until `/exit` so multiple projects can be scaffolded in one session.
+- **Auto-fetched deployments + blueprints.** `agent-scaffold new` no longer prompts for a path. The CLI pulls the latest `main` commit from `jagguvarma15/agent-deployments` and `jagguvarma15/agent-blueprints`, caches each by SHA under `~/.cache/agent-scaffold/`, and uses ETag-conditional GETs so unchanged refs don't consume GitHub rate-limit quota. Falls back to the bundled deployments copy when offline.
+- **Live bug fix:** REPL free-text refinements actually reach the generator now. Earlier preview builds collected them into `SessionState` and rendered them in the delta panel but never threaded them into `PipelineInputs` — so prose like `"add postgres, swap to sonnet"` was a silent no-op.
+
+### Added
+
+- **`agent-scaffold scaffold` — interactive REPL.** Persistent shell with the orange→red figlet banner, slash commands (`/help`, `/recipe`, `/language`, `/framework`, `/name`, `/dest`, `/model`, `/effort`, `/plan`, `/cost`, `/reset`, `/go`, `/exit`), tab-completion for commands + recipe slugs, history at `~/.cache/agent-scaffold/repl_history`, Ctrl-D / Ctrl-L key bindings.
+- **`/new` guided wizard with arrow-key selection.** Steps through recipe → language → framework → name → dest via questionary picks; each step has a `pause wizard` option that preserves selections so a follow-up `/new` resumes from the first unset field with a keep/change gate.
+- **`/generate` (alias `/gen`)** — user-facing verb for the final confirm step; both route through the existing `cmd_go` validator.
+- **`agent_scaffold.branding`** — shared figlet+gradient logo used by both the top-level `agent-scaffold` banner and the REPL welcome screen so they stay visually consistent.
+- **`prompt-toolkit>=3.0,<4`** pinned as an explicit dependency (previously transitive via questionary; the shell drives `PromptSession`, `FileHistory`, and `patch_stdout` directly).
+- **REPL slash-command dispatcher.** `agent_scaffold.repl.commands.CommandHandler` introspects its own `cmd_*` methods to register slash commands with bare-recipe-slug shortcuts and fuzzy "did you mean" matching on typos.
+- **LLM-interpreted free-text refinements in the REPL.** Anything that isn't a slash command or a bare recipe slug goes through a Haiku-only `interpret_refinement` call that turns prose like `"swap to sonnet and skip the smoke test"` into a typed `StatePatch`. ~$0.002/call. Network failures, malformed JSON, and schema-mismatched values surface a yellow warning and leave state intact rather than crashing the loop.
+- **Pre-flight cost estimate in the plan panel.** The plan-confirm panel now shows `Est. cost: $X (input $Y, output ~$Z ±$W)` before any LLM call, so you see what a run will cost before paying. Input cost is exact (from the assembled context size); output is a range bracketed by the configured `--max-tokens`.
+- **Auto-fetch deployments + blueprints from GitHub.** `agent-scaffold new` no longer prompts for the deployments path. By default the CLI pulls the latest `main` commit from both `jagguvarma15/agent-deployments` and `jagguvarma15/agent-blueprints`, caches each by SHA under `~/.cache/agent-scaffold/`, and uses ETag-conditional GETs so unchanged refs don't consume GitHub rate-limit quota. Falls back to the bundled deployments copy when offline.
+- **Blueprint URL rewriting in context assembly.** `https://github.com/jagguvarma15/agent-blueprints/(tree|blob|raw)/main/<path>` links in deployments docs now resolve to local files in the fetched blueprints tree, so the LLM actually reads the canonical pattern content the deployments docs point to (subject to the existing context budget).
+- New flags on `agent-scaffold new`: `--blueprints-path`, `--deployments-source [auto|bundled]`, `--blueprints-source [auto|skip]`.
+- New env vars: `AGENT_SCAFFOLD_BLUEPRINTS_PATH`, `AGENT_SCAFFOLD_DEPLOYMENTS_SOURCE`, `AGENT_SCAFFOLD_BLUEPRINTS_SOURCE`.
+- New module `agent_scaffold.sources` with safe-extract tarball handling (rejects `..`, absolute paths, symlink escapes — Python 3.11 floor, no `tarfile.data_filter` dependency).
+
+### Changed
+
+- `Config.deployments_path` is now `Path | None` — empty means "use the resolver default" (auto-fetch). `load_config` no longer raises when no path is set; resolution is deferred to `sources.resolve_*`.
+- Removed the "Path to agent-deployments repo:" interactive prompt from `agent-scaffold new`.
+- **New leaf modules `agent_scaffold.effort` and `agent_scaffold.language_hints`** carry the shared effort-preset table and language-YAML loader respectively. `cli.py` and `repl/*.py` now import from them instead of each carrying a near-copy.
+- **New `topology.resolve(recipe, ctx_body)` helper** returns the `(Topology, list[Role])` pair so `cmd_new`, `cmd_plan`, and `_build_pipeline_inputs` no longer duplicate the explicit-frontmatter / inference / `SINGLE` fallback dance verbatim.
+- **Split `cli.py` (2615 LOC → 1883 LOC) into focused sibling modules.** `cli_auth.py` owns the `auth` sub-app + credentials commands; `cli_secrets.py` owns the `secrets list` / `secrets purge` survey + flow; `cli_doctor.py` owns the `doctor` sub-app, the `--explain` lookup, and the auth/service `Check` adapters. A new `cli_shared.py` holds the single `console = Console()` singleton imported by every sibling. `cli.py` keeps the project-generation pipeline (`cmd_new`, `cmd_update`, `cmd_regenerate`, `cmd_scaffold`, `cmd_up`, `cmd_validate`, `cmd_config`) and registers the sub-apps via `app.add_typer(...)`.
+
+### Fixed
+
+- **REPL free-text refinements now reach the generator.** `SessionState.extra_dependencies`, `extra_steps`, `removed_steps`, `removed_roles`, and `refinement_notes` were collected and rendered in the delta panel but never threaded into `PipelineInputs` or the LLM prompt — so prose like `"add postgres, swap to sonnet, skip docker_up"` was a silent no-op. Added the five fields to `PipelineInputs`, `GenerationRequest`, and the `cache_inputs` fingerprint; rendered them as a `# User refinements` block in the user-message tail (per-run, never cached); `_build_pipeline_inputs` now passes them through from `SessionState`.
+- **`/effort high` in the REPL now matches `--effort high` on the CLI.** The two surfaces each carried their own `EFFORT_PRESETS` dict; the REPL's was missing `max_context_tokens`/`max_link_depth`/`max_tokens_per_doc`, so the same keyword silently produced different context budgets. Unified into a single `agent_scaffold.effort.EFFORT_PRESETS` mapping typed as `EffortPreset` frozen dataclasses.
+- **REPL `/language` validation now picks up new language YAMLs automatically.** Replaced the `_VALID_LANGUAGES = ("python", "typescript")` constant with a call to `agent_scaffold.language_hints.available_languages()`, so dropping in `rust.yaml` is picked up by both `/language` validation and the wizard list without code changes.
+
+### Performance
+
+- **Cached the bundled prompt reads.** `generator._load_prompt` and `prompts_signature` are now wrapped in `functools.lru_cache` — the wheel-bundled prompt files don't change at runtime, so the prior behaviour of re-reading and re-hashing them on every `run_generation` was pure waste.
+- **Per-state assemble cache in the REPL.** `repl/commands._assemble_for_state` wraps `context.assemble` with a small LRU keyed on every input that could change the output (recipe + paths + budgets). The `/plan` → `/cost` flow used to walk the blueprint tree twice; it now walks it once per state change.
+
+### Typing
+
+- **`pipeline._run_post_gen_formatter` renamed to `pipeline.run_post_gen_formatter`.** Drops the leading underscore on a function that was both re-exported via `__all__` and imported by `cli.cmd_regenerate` — the underscore was misleading public-vs-private signalling.
+- **`pipeline.RunReport.report` is now typed `WriteReport | None`** instead of `Any | None`. The comment claiming the cycle ("typed Any to avoid an import cycle in writer") was incorrect — `writer.py` is a leaf module. `mypy --strict` still passes.
+
+### Internal
+
+- **New `agent_scaffold._scaffold_dir.SCAFFOLD_DIR = ".scaffold"`** centralises the per-project metadata directory name. Updated `manifest.py`, `orchestrator.py`, `template_snapshot.py`, `writer.py`, `cli.py`, and `steps/commit_push.py` to import it instead of spelling the literal six times.
+- **REPL wizard step table.** `repl/shell._run_new_wizard` now drives its five steps (recipe / language / framework / name / dest) from a `_WIZARD_STEPS` tuple of `_WizardStep` dataclasses instead of five copy-pasted 7-line blocks. Adding a sixth step is now a single table row.
+- **Dropped the `agent_scaffold.repl` package re-exports.** Every existing caller (in-tree and tests) already imports from the symbol's owning submodule; the `__init__.py` re-exports were pure noise.
+
+### Versioning note
+
+Patch number is the count of commits to `main` since `21dcbfa` (the `0.1.1` PyPI-rename commit). Future releases on the `0.2.x` line will keep this scheme until a breaking change moves to `0.3`.
+
+## 0.1.1 — 2026-05-06
+
+### Fixed
+- Source `__version__` from installed package metadata so `agent-scaffold --version` matches the published wheel.
+
+### Changed
+- Renamed PyPI distribution to `agent-scaffold-cli` (CLI command remains `agent-scaffold`).
+- Aligned `.gitignore` and wheel build with the `agent-scaffold` rename.
+
+## 0.1.0 — 2026-05-03
+
+### Added
+- Initial public release on PyPI.
+- `agent-scaffold new` interactive flow: pick a recipe, language, framework, project name, and destination.
+- `agent-scaffold validate --tier {static,build,smoke}` reruns post-generation tiers without re-invoking the LLM.
+- `agent-scaffold config` prints the resolved configuration with the API key masked.
+- Pipeline: `config → discovery → context → generator → contract → writer → validator`.
+- Bundled `agent-deployments` docs shipped inside the wheel; override with `AGENT_SCAFFOLD_DEPLOYMENTS_PATH` or `--deployments-path`.
+- Pluggable language targets via YAML (`src/agent_scaffold/languages/`), with `python.yaml` and `typescript.yaml` shipped.
+- Atomic writes via temp dir + `os.replace`; `--write-mode` choices: `abort` (default), `skip`, `diff`, `overwrite`.
+- Path-safety validation in the contract layer (rejects absolute paths, parent traversal, symlink escapes).
+- Failure capture: malformed contracts written to `~/.cache/agent-scaffold/failures/<timestamp>.json` with automatic repair-attempt round-trip.

{agent_scaffold_cli-0.1.1 → agent_scaffold_cli-0.2.255}/CLAUDE.md

@@ -15,18 +15,21 @@ uv run agent-scaffold --help      # CLI usage
 
 ## Architecture
 
-Pipeline: `config → discovery → context → generator → contract → writer → validator`
+Pipeline: `config → sources → discovery → context → pipeline.run_generation → cli`
 
 | Module | Responsibility |
 |--------|---------------|
-| `config.py` | Load env vars + TOML config, resolve `Config` |
+| `config.py` | Load env vars + TOML config, resolve `Config`. Deployments / blueprints paths are optional hints. |
+| `sources.py` | Resolve where deployments + blueprints come from: GitHub auto-fetch (cached by SHA, ETag-conditional) with bundled / skip fallback. |
 | `discovery.py` | Scan `agent-deployments/docs/recipes/` for markdown recipe specs |
-| `context.py` | Assemble recipe + linked docs into a single prompt context |
+| `context.py` | Assemble recipe + linked docs into a single prompt context. Rewrites `github.com/.../agent-blueprints/...` URLs in deployments docs to local files in the fetched blueprints tree. |
 | `generator.py` | Call Anthropic API with system/user prompts, retry on transient errors |
 | `contract.py` | Parse + validate JSON response (path safety, required files) |
 | `writer.py` | Atomic file writing with skip/diff/overwrite modes |
 | `validator.py` | Post-generation validation: static lint, build, smoke check |
-| `cli.py` | Typer CLI orchestrating the full pipeline |
+| `pipeline.py` | Post-plan orchestration (`run_generation`): generate → write → gitignore → verify → format → validate → manifest. Reusable by `cmd_new` and the `scaffold` REPL. Recoverable failures raise `PipelineError`. |
+| `repl/` | Interactive shell (`agent-scaffold scaffold`). `session.py` (state + StatePatch), `commands.py` (slash dispatcher), `refine.py` (Haiku-interpreted free text), `render.py` (Rich panels), `shell.py` (PromptSession loop). |
+| `cli.py` | Typer CLI: prompt collection + plan-confirm + delegate to `pipeline.run_generation`. `cmd_scaffold` opens the REPL. |
 
 ## Conventions
 

agent_scaffold_cli-0.2.255/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+**Positive behaviour includes:**
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experience levels
+- Giving and gracefully accepting constructive feedback
+- Focusing on what is best for the community
+- Showing empathy toward other contributors
+
+**Unacceptable behaviour includes:**
+- Harassment, insults, or derogatory comments in any form
+- Personal or political attacks
+- Publishing others' private information without consent
+- Trolling or deliberately disruptive behaviour
+
+## Scope
+
+This code of conduct applies in all project spaces — GitHub issues, pull requests, discussions, and any other forums used by the community.
+
+## Enforcement
+
+Instances of unacceptable behaviour may be reported by opening a GitHub issue or contacting the maintainers directly. All reports will be reviewed and investigated. Maintainers are obligated to maintain confidentiality with regard to the reporter.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

agent_scaffold_cli-0.2.255/CONTRIBUTING.md

@@ -0,0 +1,108 @@
+# Contributing to agent-scaffold
+
+Thanks for your interest! This guide covers bug reports, feature requests, language-target additions, and code contributions.
+
+## Getting started
+
+```bash
+git clone https://github.com/jagguvarma15/agent-scaffold
+cd agent-scaffold
+uv sync
+uv run pytest
+```
+
+The full toolchain (matches CI):
+
+```bash
+uv run ruff check src/ tests/
+uv run ruff format src/ tests/
+uv run mypy src/
+uv run pytest
+uv run pytest -m integration   # requires ANTHROPIC_API_KEY
+```
+
+## Project layout
+
+`agent-scaffold` is structured as a pipeline:
+
+```
+config → discovery → context → generator → contract → writer → validator
+```
+
+Each module owns one stage; please keep contributions scoped to the stage they belong to. See [`CLAUDE.md`](CLAUDE.md) for the responsibility table.
+
+## Types of contributions
+
+### Bug reports
+
+Open an issue with:
+- The `agent-scaffold --version` output
+- The exact command you ran and what you expected
+- The generated output or error (redact API keys)
+- If the LLM produced a malformed contract, attach the file from `~/.cache/agent-scaffold/failures/`
+
+### Adding a target language
+
+Drop a YAML file into `src/agent_scaffold/languages/` modeled after [`python.yaml`](src/agent_scaffold/languages/python.yaml) or [`typescript.yaml`](src/agent_scaffold/languages/typescript.yaml). Required keys are listed in the README. Add a fixture under `tests/fixtures/` and a discovery test.
+
+### Pipeline changes
+
+Changes to `contract.py` or `writer.py` are security-sensitive (path validation, atomic writes). Please include:
+- Tests covering the new behaviour
+- Tests covering adversarial inputs (escaping paths, symlinks, absolute paths)
+- A short note in the PR explaining why the new behaviour is safe
+
+### Documentation
+
+Improvements to `README.md`, `CLAUDE.md`, or inline docstrings are always welcome.
+
+## Code style
+
+- Python 3.11+, strict mypy, ruff for lint + format (see `pyproject.toml` for config)
+- Pydantic models for all data structures
+- Custom exceptions carry context (e.g. `ContractParseError.raw`, `.reason`)
+- Tests use monkeypatching for the Anthropic client; fixtures live in `tests/fixtures/`
+- src layout under `src/agent_scaffold/`
+
+## Commit messages
+
+Use concise, descriptive messages following the existing style:
+- `feat: add support for <language>`
+- `fix: reject parent-relative paths in writer`
+- `chore: bump version to 0.1.2`
+- `docs: clarify --write-mode semantics`
+
+## PR checklist
+
+- [ ] `uv run ruff check src/ tests/` passes
+- [ ] `uv run mypy src/` passes
+- [ ] `uv run pytest` passes
+- [ ] Added or updated tests for the changed behaviour
+- [ ] Updated `CHANGELOG.md` under `## Unreleased` if user-visible
+- [ ] No secrets, API keys, or `.env` files committed
+
+## Security rules (the nine-point checklist)
+
+If your change touches credential handling — auth, wire_credentials, file
+writes near secrets, subprocess output that might echo a key — read
+[`docs/design/security.md`](docs/design/security.md) first. The summary:
+
+1. Never accept secrets as positional/flag args (use env vars or stdin/getpass).
+2. Use `getpass.getpass()` for interactive paste; never `input()` for secrets.
+3. Wrap credentials in `pydantic.SecretStr` immediately after capture.
+4. `subprocess.run([...], shell=False)` always; list-form arguments only.
+5. Use `agent_scaffold._filesec.secure_write` for any file holding a secret.
+6. Never trust a plaintext keyring backend — refuse and surface the error.
+7. Run any user-visible string that might contain a credential through
+   `agent_scaffold._redact.redact` before logging or persisting.
+8. Use `agent_scaffold.writer.ensure_gitignore_defaults` to guarantee the
+   secret-safety block lands in every project's `.gitignore`.
+9. Anything storable must be revocable via `agent-scaffold secrets purge`.
+
+Each rule has an audit test under `tests/security/`. If your change needs
+to bend one of them, add the exception to the corresponding allow-list with
+a one-line justification — don't disable the test.
+
+## Questions?
+
+Open a discussion or issue. Happy to help scope a contribution before you invest time building.