Metadata-Version: 2.4
Name: scaffold-guard
Version: 0.1.0
Summary: Generate guarded Python project starters for Codex, Claude Code, and Cursor.
Project-URL: Homepage, https://github.com/damienbenveniste/ScaffoldGuard
Project-URL: Repository, https://github.com/damienbenveniste/ScaffoldGuard
Project-URL: Issues, https://github.com/damienbenveniste/ScaffoldGuard/issues
Project-URL: Documentation, https://github.com/damienbenveniste/ScaffoldGuard#readme
Author: Damien Benveniste
License-Expression: MIT
License-File: LICENSE
Keywords: agents,claude,codex,cursor,scaffold,scaffold-guard
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: jinja2>=3.1.0
Requires-Dist: packaging>=24.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Description-Content-Type: text/markdown

# ScaffoldGuard

`scaffold-guard` generates strict Python starter repositories for teams using
coding agents. It creates a typed package layout, local validation commands,
GitHub Actions workflows, and agent instructions for Codex, Claude Code, and
Cursor.

The PyPI package and `uvx` entrypoint are `scaffold-guard`; the canonical
installed command is `scaffold-guard`.

## Install

After the package is published to PyPI:

```bash
uvx scaffold-guard version
```

From a local checkout or built wheel:

```bash
uv sync --all-groups
uv run scaffold-guard version
uv build
uvx --from dist/scaffold_guard-0.1.0-py3-none-any.whl scaffold-guard version
```

## Publishing

PyPI publishing is prepared through GitHub Actions Trusted Publishing. Before
the first release, configure a PyPI pending publisher for:

```text
Project name: scaffold-guard
Owner: damienbenveniste
Repository: ScaffoldGuard
Workflow: publish.yml
Environment: pypi
```

No PyPI API token is required. After the pending publisher exists, publish a
GitHub Release or manually run the `Publish` workflow from `main`.

## Quickstart

Generate a project with every supported adapter:

```bash
uvx scaffold-guard init my_project --agent all
cd my_project
uv sync --all-groups
uv run scaffold-guard check
uv run scaffold-guard validate --quick
```

Generate for one agent surface:

```bash
uvx scaffold-guard init codex_demo --agent codex
uvx scaffold-guard init claude_demo --agent claude
uvx scaffold-guard init cursor_demo --agent cursor
```

Use `--dry-run` to preview files and `--force` to overwrite known generated
files.

## Generated Project

The default `package` profile creates:

```text
my_project/
  AGENTS.md
  README.md
  LICENSE
  pyproject.toml
  pyrightconfig.json
  scaffold-guard.toml
  .github/workflows/
  docs/
  examples/
  src/my_project/
  tests/unit/
  tests/integration/
```

Adapter files are added according to `--agent`:

| Agent | Generated instruction files |
|---|---|
| `codex` | `AGENTS.md` |
| `claude` | `AGENTS.md`, `CLAUDE.md`, `.claude/rules/*.md` |
| `cursor` | `AGENTS.md`, `.cursor/rules/*.mdc` |
| `all` | all of the above |

## Commands

```bash
scaffold-guard init NAME [--agent codex|claude|cursor|all]
scaffold-guard check [--path .] [--json]
scaffold-guard inspect-diff [--path .] [--base main] [--json]
scaffold-guard validate [--path .] [--quick] [--json]
scaffold-guard compile-rules [--path .] [--agent codex|claude|cursor|all] [--dry-run] [--force]
scaffold-guard doctor [--path .] [--json]
scaffold-guard version
```

`check` runs fast policy checks. `inspect-diff` explains validation obligations
for changed files in a git repository. `validate` runs the generated project's
configured validation gate. `compile-rules` regenerates managed agent
instruction files from templates. `doctor` reports local tool and generated
project health.

## Local Development

Run the package gate from this repository:

```bash
uv sync --all-groups --frozen
uv run ruff format --check .
uv run ruff check .
uv run mypy src tests
uv run pyright
uv run pytest tests --cov=scaffold_guard --cov-report=term-missing --cov-fail-under=95
uv run mkdocs build --strict
uv build
```

## Limitations

V1 is a developer CLI, not a SaaS product or policy server. It does not include
telemetry, external AI calls, Codex or Claude hooks, a plugin system, Homebrew
automation, or automatic upgrades for mature existing repositories.

Homebrew distribution, hook starter templates, more project profiles, and richer
policy configuration are intentionally deferred until after the PyPI package is
stable.
