scaffold-guard 0.1.0__tar.gz

scaffold_guard-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  test:
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7.0.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --all-groups --frozen
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check with mypy
+        run: uv run mypy src tests
+
+      - name: Type check with Pyright
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest tests --cov=scaffold_guard --cov-report=term-missing --cov-fail-under=95
+
+      - name: Build docs
+        run: uv run mkdocs build --strict

scaffold_guard-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,76 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' || github.ref == 'refs/heads/main'
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7.0.0
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6.3.0
+        with:
+          python-version: "3.14"
+
+      - name: Install dependencies
+        run: uv sync --all-groups --frozen
+
+      - name: Check formatting
+        run: uv run ruff format --check .
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check with mypy
+        run: uv run mypy src tests
+
+      - name: Type check with Pyright
+        run: uv run pyright
+
+      - name: Test
+        run: uv run pytest tests --cov=scaffold_guard --cov-report=term-missing --cov-fail-under=95
+
+      - name: Build docs
+        run: uv run mkdocs build --strict
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

scaffold_guard-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+.DS_Store
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+htmlcov/
+site/
+*.egg-info/
+__pycache__/

scaffold_guard-0.1.0/AGENTS.md

@@ -0,0 +1,222 @@
+# Agent Instructions
+
+These rules apply to every code, test, documentation, template, and
+configuration change in this repository.
+
+## Product Orientation
+
+- Build `scaffold-guard`: a PyPI-installable Python CLI that generates strict
+  Python starter repositories designed for safe coding-agent collaboration.
+- Preserve the V1 promise: generate a Python project with clear agent
+  instructions, strict local tooling, GitHub Actions CI, and policy checks that
+  catch common agent mistakes.
+- Treat `scaffold_guard_v1_implementation_plan.md` as the source of current
+  product scope and acceptance criteria until the plan is moved into formal docs.
+- Keep V1 focused on a developer CLI. Do not add a SaaS dashboard, telemetry,
+  external AI calls, complex YAML DSL, plugin ecosystem, publish automation, or
+  automatic mutation of mature existing repositories.
+- Always generate `AGENTS.md` for scaffolded projects. Treat it as the shared
+  cross-agent instruction source.
+- Keep adapter behavior explicit:
+  - Codex uses `AGENTS.md`.
+  - Claude Code uses `CLAUDE.md` as a wrapper that imports `AGENTS.md`, with
+    optional `.claude/rules/`.
+  - Cursor uses `.cursor/rules/*.mdc` plus `AGENTS.md`.
+- Prefer small, shippable V1 behavior over speculative framework design.
+
+## Continuous Instruction Feedback Loop
+
+- Treat this `AGENTS.md` as the operating manual for agents working in this
+  repository.
+- When the user gives durable repo-wide feedback about how agents should work,
+  update this file in the same task unless the feedback is clearly one-off or is
+  already covered.
+- Keep this file focused on operating rules, ownership boundaries, and completion
+  standards. Do not use it as a roadmap, milestone tracker, or implementation
+  plan.
+- Keep rules general and actionable. Do not add task-specific history,
+  timestamps, workaround diaries, or feature requirements.
+- Final responses for implementation tasks must state whether `AGENTS.md` was
+  updated. If explicit feedback or a notable failure did not require an update,
+  explain why the existing rules were sufficient.
+
+## Working Style and Completion Bar
+
+- Start non-trivial tasks by checking the current plan, existing files, package
+  boundaries, tests, and repository state.
+- State assumptions, constraints, intended scope, and validation steps before
+  substantial implementation.
+- Make the smallest safe change that fully satisfies the request. Avoid
+  speculative rewrites and unrelated refactors.
+- Implement work in phases that can be validated independently. Do not treat the
+  entire V1 plan as one undifferentiated change.
+- Finish the accepted scope. Do not silently skip requested details or stop after
+  a partial implementation.
+- Never claim completion until the relevant checks have run, or until a blocker
+  is stated with concrete evidence and the next action.
+- If a bug is found in touched behavior, fix the root cause before calling the
+  task complete unless the fix is unsafe or clearly out of scope.
+- Do not lower lint, typing, docs, test, or coverage gates to force a green
+  result.
+
+## Python Tooling
+
+- Use `uv` for dependency management, lockfile updates, virtual environment work,
+  and command execution.
+- The CLI package should support Python `>=3.11`.
+- Test the CLI package on every supported Python feature release in CI. Do not
+  leave a current supported Python release out of the matrix without an explicit
+  compatibility reason.
+- Generated projects should target Python `>=3.13` unless the implementation
+  plan changes.
+- Keep CLI runtime dependencies minimal. V1 should use `typer`, `rich`,
+  `jinja2`, and `packaging` only when they are genuinely needed.
+- Prefer Hatchling for package builds and make sure generated templates are
+  included in wheels.
+- Use `importlib.resources.files()` to load packaged templates.
+- Use `subprocess.run` without `shell=True` for command execution.
+- Keep Ruff, mypy, Pyright, pytest, coverage, and MkDocs gates strict once the
+  scaffold exists.
+- Write clear docstrings for public modules, classes, functions, and methods
+  when the behavior is not obvious from the name and types.
+
+## Types and Data Modeling
+
+- Type every public function, method, class attribute, constant, and public
+  module export.
+- Avoid `Any`. If it is truly unavoidable, isolate it at a boundary, explain why,
+  and add tests around the narrowing.
+- Do not introduce `dict[str, Any]`. Use explicit typed structures for stable
+  shapes.
+- Avoid `# type: ignore`, `# pyright: ignore`, `# noqa`, broad exclusions, and
+  lint suppressions to hide failures. Fix the type flow or rule violation.
+- Use lightweight dataclasses or typed structures for CLI internals in V1. Do not
+  add Pydantic unless the benefit clearly outweighs the dependency cost.
+- Keep filesystem and rendering models explicit enough to test dry-run,
+  overwrite, generated-marker, and adapter behavior deterministically.
+
+## Scaffold and Adapter Rules
+
+- Keep `AGENTS.md` generation in the base scaffold because it is shared by every
+  adapter.
+- `CLAUDE.md` must not duplicate the full `AGENTS.md`; it should import or
+  reference it and add only Claude-specific notes.
+- Cursor `.mdc` files must include valid frontmatter with `description`,
+  `alwaysApply`, and `globs` where appropriate.
+- Generated agent instruction files should be concise, serious, and enforceable
+  through `scaffold-guard check` and CI where possible.
+- Use generated markers and checksums or clearly documented overwrite rules for
+  files managed by `compile-rules`.
+- Keep template rendering deterministic. Tests should not depend on wall-clock
+  time, network access, local credentials, or machine-specific paths.
+
+## Filesystem Safety
+
+- Validate project names before writing. Reject path traversal, empty names,
+  unsafe package identifiers, and unexpected absolute paths.
+- Refuse to overwrite existing directories or manually edited generated files
+  unless `--force` or a documented generated-file mechanism applies.
+- Write only inside the requested target project root.
+- Implement `--dry-run` paths so they produce the same planned file list without
+  touching the filesystem.
+- Prefer structured path handling with `pathlib` over ad hoc string operations.
+
+## Testing Rules
+
+- Add or update tests with every behavior change.
+- Unit tests should cover CLI argument handling, rendering, scaffold planning,
+  filesystem safety, adapter selection, unsafe-pattern checks, diff
+  requirements, generated-file checks, and config consistency.
+- Integration tests should cover generated package profiles, adapter file sets,
+  `compile-rules` idempotence, `validate --quick`, JSON modes, and import smoke
+  behavior.
+- Tests must verify behavior and regressions, not duplicate implementation
+  details or mocked call order.
+- For bug fixes, add a regression test that fails before the fix and passes
+  after it.
+- Keep tests deterministic: no real network calls, sleeps, wall-clock coupling,
+  or undeclared external services.
+- Maintain the V1 package coverage floor at or above `95` unless the user
+  explicitly approves a change.
+
+## Documentation and Examples
+
+- Keep `README.md`, docs, examples, generated templates, tests, and package
+  behavior synchronized in the same change.
+- Update docs when public commands, package layout, configuration, validation
+  behavior, generated output, adapter support, or developer workflows change.
+- Never document aspirational behavior as if it works today. Future behavior
+  must be marked as future, planned, or unsupported.
+- Examples should be small, deterministic, realistic, and runnable enough to
+  become integration fixtures later.
+- Document Codex, Claude Code, and Cursor behavior as adapter facts, not vague
+  compatibility claims.
+
+## Security and Secret Handling
+
+- Never commit secrets, local credentials, provider payloads, private
+  transcripts, `.env`, `.venv`, or generated runtime artifacts.
+- Keep policy checks conservative and explainable. Regex-based scanning is fine
+  for V1 when it is documented and tested.
+- Do not add external AI calls, telemetry, or network-dependent tests in V1.
+- Treat suspicious credential literals, `shell=True`, unsafe writes outside the
+  project root, and committed environment files as policy failures.
+
+## Validation Commands
+
+Match validation to the actual change and the scaffold that exists.
+
+- For markdown-only edits, run `git diff --check` when the repository is
+  initialized. If there is no `.git` directory yet, state that the whitespace
+  check could not be run for that reason.
+- For documentation pages, README changes, or docs navigation changes, run
+  `git diff --check` and `uv run mkdocs build --strict` once the docs toolchain
+  exists.
+- For code, package metadata, lockfile, tests, examples, templates, or generated
+  assets, run focused checks plus the full gate below when the change is
+  substantial.
+
+Target full gate once the scaffold exists:
+
+```bash
+uv sync --all-groups
+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
+```
+
+Generated projects should be validated with their configured commands:
+
+```bash
+uv run scaffold-guard check
+uv run scaffold-guard inspect-diff
+uv run scaffold-guard validate
+```
+
+Do not report completion if a required check fails. Fix the failure or clearly
+explain why it is blocked.
+
+## Git and Change Hygiene
+
+- Keep diffs focused and reviewable.
+- Preserve user changes. Do not revert unrelated work.
+- Keep `uv.lock` synchronized with `pyproject.toml` changes once the lockfile
+  exists.
+- Do not commit generated runtime artifacts unless the repository intentionally
+  tracks them.
+- Treat this checkout as the workspace boundary unless the user explicitly asks
+  to touch another checkout.
+- When a task explicitly includes pushing or publishing, watch the relevant
+  GitHub Actions runs after pushing and report the final status.
+
+## Final Response Requirements
+
+- Summarize the user-visible change and name the main files touched.
+- List the validation commands run and their results. If a relevant check could
+  not run, explain why.
+- State whether `AGENTS.md` was updated for implementation tasks.
+- Call out any remaining blocker, risk, or follow-up needed to finish the
+  accepted scope.

scaffold_guard-0.1.0/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+- Added the `scaffold-guard` CLI with `init`, `check`, `inspect-diff`, `validate`,
+  `compile-rules`, `doctor`, and `version`.
+- Added package-profile project generation with Codex, Claude Code, and Cursor
+  adapter files.
+- Added local policy checks, diff guidance, generated-project validation,
+  diagnostics, and rule regeneration.
+- Added release-readiness documentation and wheel template inclusion checks.
+- Added Python 3.14 CI coverage and PyPI Trusted Publishing release automation.
+- Updated repository and generated-project GitHub Actions to current action
+  releases.
+- Renamed the project, PyPI distribution, module, CLI, and generated config to
+  ScaffoldGuard / `scaffold-guard`.

scaffold_guard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damien Benveniste
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

scaffold_guard-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+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.