anvil-state 0.1.1__tar.gz

anvil_state-0.1.1/.gitignore

@@ -0,0 +1,25 @@
+# Python virtualenv (uv sync materializes this under bin/)
+.venv/
+bin/.venv/
+
+# Python bytecode / build artifacts
+__pycache__/
+*.pyc
+dist/
+*.egg-info/
+
+# Test / tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+bin/.coverage
+
+# anvil runtime state (created when running the CLI, tests, or benchmarks)
+.anvil/
+bin/.anvil/
+packets/
+
+# Agent build scratch space — never commit
+.anvil-build/
+docs/plans/agent-*-status.md

anvil_state-0.1.1/PKG-INFO

@@ -0,0 +1,46 @@
+Metadata-Version: 2.4
+Name: anvil-state
+Version: 0.1.1
+Summary: Local-first project state engine: turn rough ideas and PRDs into reviewed, lockable, evidence-backed work packets that humans and AI agents can coordinate on without conflicts.
+Author: Sekou Doumbouya
+License: MIT
+Keywords: agent-coordination,claims,evidence-based,llm-work-packets,local-first,mcp,project-state,runtime-neutral,sqlite,terraform-for-work
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.30
+Requires-Dist: cryptography>=42
+Requires-Dist: fastmcp
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.6
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: typer>=0.12
+Provides-Extra: all-providers
+Requires-Dist: anthropic[bedrock]>=0.30; extra == 'all-providers'
+Requires-Dist: openai>=1.0; extra == 'all-providers'
+Provides-Extra: bedrock
+Requires-Dist: anthropic[bedrock]>=0.30; extra == 'bedrock'
+Provides-Extra: custom
+Requires-Dist: openai>=1.0; extra == 'custom'
+Provides-Extra: s3
+Requires-Dist: boto3>=1.26; extra == 's3'
+Description-Content-Type: text/markdown
+
+# anvil-state
+
+Local-first project state engine: turn rough ideas and PRDs into reviewed,
+lockable, evidence-backed work packets that humans and AI coding agents can
+coordinate on without conflicts.
+
+`anvil-state` installs the `anvil` CLI and the `anvil-mcp` MCP server.
+
+```bash
+uv tool install anvil-state      # or: pipx install anvil-state
+anvil --help
+anvil install <harness>          # wire anvil into Codex, Cursor, VS Code, ...
+```
+
+The MCP server (`anvil-mcp`) exposes anvil's tool surface to any MCP-capable
+harness. `anvil install <harness>` writes the MCP config and instruction file for
+a target harness (idempotent, backed up, reversible with `--rollback`).
+
+Full documentation, the cross-harness install guide, and the Claude Code plugin
+live in the repository: https://github.com/fakoli/anvil

anvil_state-0.1.1/README.md

@@ -0,0 +1,20 @@
+# anvil-state
+
+Local-first project state engine: turn rough ideas and PRDs into reviewed,
+lockable, evidence-backed work packets that humans and AI coding agents can
+coordinate on without conflicts.
+
+`anvil-state` installs the `anvil` CLI and the `anvil-mcp` MCP server.
+
+```bash
+uv tool install anvil-state      # or: pipx install anvil-state
+anvil --help
+anvil install <harness>          # wire anvil into Codex, Cursor, VS Code, ...
+```
+
+The MCP server (`anvil-mcp`) exposes anvil's tool surface to any MCP-capable
+harness. `anvil install <harness>` writes the MCP config and instruction file for
+a target harness (idempotent, backed up, reversible with `--rollback`).
+
+Full documentation, the cross-harness install guide, and the Claude Code plugin
+live in the repository: https://github.com/fakoli/anvil

anvil_state-0.1.1/anvil

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# anvil — shell wrapper that bridges bin/src/ Python source to Claude Code
+# skills, hooks, and the shell. Ensures uv is synced (idempotent) then execs the
+# CLI module so signals propagate cleanly to the Python process.
+
+# Preserve caller's cwd so the CLI sees the directory the user actually invoked
+# from. Without this, `anvil init` would scaffold .anvil/ inside
+# the plugin's bin/ instead of the user's project.
+ORIGINAL_PWD="$PWD"
+BIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if ! command -v uv > /dev/null 2>&1; then
+    printf 'anvil: uv is required: https://docs.astral.sh/uv/getting-started/installation/\n' >&2
+    exit 127
+fi
+
+# Sync only when uv.lock is missing, pyproject.toml is newer than .venv,
+# or uv.lock is newer than .venv (covers the `git pull` case where only the
+# lock file moves). File-age based, fully idempotent — no cat/grep involved.
+(cd "$BIN_DIR" && {
+    if [ ! -f uv.lock ] || [ pyproject.toml -nt .venv ] || [ uv.lock -nt .venv ]; then
+        uv sync --quiet
+    fi
+})
+
+cd "$ORIGINAL_PWD" || exit 1
+exec uv run --quiet --project "$BIN_DIR" python -m anvil.cli "$@"

anvil_state-0.1.1/anvil-mcp

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# anvil-mcp — shell wrapper for the MCP server entry point.
+# anvil.mcp_server landed in Phase 6 and registers 13 tools via FastMCP.
+
+# Preserve caller's cwd; see bin/anvil for the rationale.
+ORIGINAL_PWD="$PWD"
+BIN_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if ! command -v uv > /dev/null 2>&1; then
+    printf 'anvil-mcp: uv is required: https://docs.astral.sh/uv/getting-started/installation/\n' >&2
+    exit 127
+fi
+
+# Sync only when uv.lock is missing, pyproject.toml is newer than .venv,
+# or uv.lock is newer than .venv (covers the `git pull` case where only the
+# lock file moves). File-age based, fully idempotent — no cat/grep involved.
+(cd "$BIN_DIR" && {
+    if [ ! -f uv.lock ] || [ pyproject.toml -nt .venv ] || [ uv.lock -nt .venv ]; then
+        uv sync --quiet
+    fi
+})
+
+cd "$ORIGINAL_PWD" || exit 1
+exec uv run --quiet --project "$BIN_DIR" python -m anvil.mcp_server "$@"

anvil_state-0.1.1/pyproject.toml

@@ -0,0 +1,124 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "anvil-state"
+version = "0.1.1"
+description = "Local-first project state engine: turn rough ideas and PRDs into reviewed, lockable, evidence-backed work packets that humans and AI agents can coordinate on without conflicts."
+# Build-root-local README. `../README.md` escaped the bin/ build root and broke
+# `uv build` (sdist->wheel: "Readme file does not exist: ../README.md"). This is
+# the package-focused PyPI long description; the full repo README stays at root.
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [
+    { name = "Sekou Doumbouya" },
+]
+keywords = [
+    "agent-coordination",
+    "claims",
+    "evidence-based",
+    "llm-work-packets",
+    "local-first",
+    "mcp",
+    "project-state",
+    "runtime-neutral",
+    "sqlite",
+    "terraform-for-work",
+]
+dependencies = [
+    "typer>=0.12",
+    "pydantic>=2.6",
+    "fastmcp",
+    "anthropic>=0.30",
+    "PyYAML>=6.0",
+    "httpx>=0.27",
+    # Ed25519 signing for portable ProofArtifacts (B48 part 2). Already resolved
+    # transitively (authlib/joserfc); pinned explicitly so a transitive bump
+    # can't silently remove the signing primitive the trust layer depends on.
+    "cryptography>=42",
+]
+
+# Optional extras enable additional LLM providers (v1.17.0). The default
+# install only depends on `anthropic` for the direct API path. Users who
+# want Amazon Bedrock or an OpenAI-compatible custom endpoint opt in by
+# installing the corresponding extra:
+#
+#     pip install 'anvil-state[bedrock]'   # adds anthropic[bedrock] (boto3)
+#     pip install 'anvil-state[custom]'    # adds openai for /v1/chat/completions
+#     pip install 'anvil-state[bedrock,custom]'  # both
+#     pip install 'anvil-state[all-providers]'   # convenience alias
+#
+# Keeping these optional avoids pulling boto3 (~70MB of transitive deps)
+# and the openai SDK onto every install — most users only need direct API.
+[project.optional-dependencies]
+bedrock = ["anthropic[bedrock]>=0.30"]
+custom = ["openai>=1.0"]
+s3 = ["boto3>=1.26"]
+all-providers = [
+    "anthropic[bedrock]>=0.30",
+    "openai>=1.0",
+]
+
+[project.scripts]
+anvil = "anvil.cli:app"
+# The MCP server as a real console script so a wheel install (uv tool/pipx/pip)
+# exposes a launchable `anvil-mcp` on PATH. Without this, every emitted MCP config
+# pointed at the bin/anvil-mcp bash wrapper, which a wheel does not ship.
+anvil-mcp = "anvil.mcp_server:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "types-pyyaml>=6.0.12.20260518",
+    # HTTP mocker: respx mocks httpx (the transport our GitHub HTTP client uses).
+    "respx>=0.21",
+]
+
+[tool.hatch.build.targets.wheel]
+# Ships src/anvil with its non-.py package data (py.typed + _data/AGENTS.md +
+# _data/packaging/codex/automations). The installer reads _data via
+# importlib.resources, so a wheel MUST carry it — do not add an exclude that drops
+# _data. Guarded by tests/test_install_manifests.py::test_built_wheel_is_self_sufficient.
+packages = ["src/anvil"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests routinely embed long SQL strings, assertion messages, and snapshot
+# literals where readability beats wrapping.
+"../tests/**" = ["E501"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+
+[[tool.mypy.overrides]]
+# Tests intentionally use **dict factory patterns, assert against frozen
+# dataclasses, and pass deliberately-wrong types to verify error paths.
+# pytest's own conventions (fixtures, monkeypatch, parameterize) further
+# undermine static typing. Keep strict on src; relax on tests.
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+disallow_untyped_calls = false
+disallow_any_generics = false
+warn_return_any = false
+no_implicit_reexport = false
+ignore_errors = true
+
+[tool.pytest.ini_options]
+testpaths = ["../tests"]
+addopts = "-m 'not live_github'"
+markers = [
+    "live_github: tests that hit the real GitHub API (require ANVIL_TEST_GH_TOKEN env)",
+]

anvil_state-0.1.1/src/anvil/__init__.py

@@ -0,0 +1,7 @@
+"""anvil — local-first project state engine for humans and AI agents."""
+
+from __future__ import annotations
+
+__version__ = "0.1.1"
+
+__all__ = ["__version__"]

anvil_state-0.1.1/src/anvil/_data/AGENTS.md

@@ -0,0 +1,85 @@
+# AGENTS.md — Anvil
+
+Anvil is a local-first, backend-neutral **project-state engine**: it turns PRDs
+into reviewed, lockable, evidence-backed work packets that humans and AI agents
+can coordinate on without conflicts. State lives in SQLite under
+`.anvil/` (event-sourced; `events.jsonl` is the log). Two equivalent surfaces:
+
+- **CLI** — `bin/anvil <command>` (single mutator, no harness dependency).
+- **MCP** — `bin/anvil-mcp` (24 FastMCP stdio tools). Run
+  `anvil mcp-config <your-client>` to print client-specific config.
+
+Both resolve the project via `ANVIL_ROOT` env var, else the current directory.
+Every read command supports `--json` for a `{"ok":…,"command":…,"data":…}`
+envelope. **Prefer the MCP tool if your harness has MCP; otherwise use the CLI
+command in the same row — they are equivalent.**
+
+## The standalone loop
+
+init → author/parse PRD → review → plan + score → claim → work packet →
+submit evidence → apply review verdict.
+
+```bash
+anvil init                 # scaffold .anvil/
+# author .anvil/prd.md (see docs/prd-template.md), then:
+anvil prd parse && anvil review prd approve
+anvil plan && anvil score
+anvil next                 # pick a ready task
+anvil claim T001           # lease it, get a branch
+anvil packet T001          # work packet; do the work
+anvil submit T001 --evidence …
+anvil apply T001           # apply the review verdict
+```
+
+## Capabilities (MCP tool ⇄ CLI command)
+
+| Capability | MCP tool | CLI command |
+|---|---|---|
+| Init project | `init_project` | `anvil init` |
+| Project status | `get_project_status` | `anvil status` |
+| Project summary | `get_project_summary` | `anvil status --json` |
+| Parse PRD | `parse_prd` | `anvil prd parse` |
+| Review PRD | `review_prd` | `anvil review prd …` |
+| Plan tasks | `plan_tasks` | `anvil plan` |
+| Score tasks | `score_tasks` | `anvil score` |
+| Review tasks | `review_tasks` | `anvil review tasks …` |
+| Apply review decision | `apply_review_decision` | `anvil apply` |
+| Find open decisions | `find_decisions` | `anvil prd find-decisions` |
+| List tasks | `list_tasks` | `anvil list` |
+| Show one task | `get_task` | `anvil show <id>` |
+| Next ready task | `get_next_task` | `anvil next` |
+| Claim task | `claim_task` | `anvil claim <id>` |
+| Release claim | `release_task` | `anvil release <id>` |
+| Renew claim lease | `renew_claim` | `anvil renew <id>` |
+| Work packet | `generate_work_packet` | `anvil packet <id>` |
+| Submit progress | `submit_progress` | `anvil submit <id> --progress …` |
+| Submit evidence | `submit_completion_evidence` | `anvil submit <id> --evidence …` |
+| Update task status | `update_task_status` | (via claim/submit/apply flow) |
+| File-conflict check | `check_conflicts` | `anvil conflicts` |
+| Dependency graph | `get_dependency_graph` | `anvil graph` / `anvil deps` |
+| Edit dependencies | `edit_dependencies` | `anvil deps --add/--remove` |
+| Describe surface | `describe_surface` | `anvil describe` |
+
+(Exact tool names mirror `bin/src/anvil/mcp_server.py`; CLI commands mirror
+`bin/src/anvil/cli/__init__.py`. Run `anvil describe --json` for the live list.)
+
+### Execution vs planning surface (MCP)
+
+To keep the per-turn context lean, the MCP server exposes only the **14
+execution tools** by default — the turn-to-turn loop (next/claim/packet/submit/
+status/conflicts/deps). The **10 one-shot planning tools** (`init_project`,
+`parse_prd`, `review_prd`, `plan_tasks`, `score_tasks`, `review_tasks`,
+`apply_review_decision`, `edit_dependencies`, `find_decisions`,
+`describe_surface`) are **hidden by default** and re-appear when the server is
+started with **`ANVIL_MCP_PLANNING=1`** (or `true`/`yes`/`on`). Nothing is
+removed — every capability stays reachable via the CLI command in the same row,
+and the full 24-tool surface returns the moment the env flag is set. Use it for
+the planning phase; the steady-state execution loop needs none of the 10.
+
+## Notes
+- Claude Code adds SessionStart/PreToolUse/PostToolUse **hooks**; these are
+  Claude-Code-only and have no cross-harness equivalent. Every capability is
+  still reachable via the CLI/MCP rows above without them.
+- `uv` is the only prerequisite; the wrappers self-sync on first run.
+- Distribution: `anvil install <harness> --write` writes the MCP config and
+  drops this `AGENTS.md` where the harness reads it (dry-run by default).

anvil_state-0.1.1/src/anvil/_data/packaging/codex/automations/README.md

@@ -0,0 +1,21 @@
+# Anvil automations for Codex
+
+Codex [automations](https://developers.openai.com/codex) are scheduled agent runs
+defined by `~/.codex/automations/<id>/automation.toml` (cron `rrule`, a `model`,
+an `execution_environment`, and a `prompt`). They are how anvil delivers
+**longer-running, recurring work** — the same project state, worked on a schedule.
+
+These are **templates**. `anvil install codex --write --automations` materializes
+them into `~/.codex/automations/<template>-<project-basename>-<hash8>/` (e.g.
+`anvil-work-queue-myrepo-3f9a1c20`) with the project path and timestamps filled in,
+**`status = "PAUSED"`** so nothing runs until you review and activate it in the
+Codex app (Automations). Without `--write` the command is a dry-run that only
+previews what it would create. Remove them with `anvil install codex --rollback`.
+
+| Template | What it does |
+|---|---|
+| `anvil-work-queue` | Claim + execute the next ready anvil task to passing evidence, one PR per task. |
+| `anvil-sync-reconcile` | Run `anvil sync` to detect (and, when safe, fix) state drift. |
+
+Placeholders substituted at install: `{{ID}}` (dir name), `{{CWDS}}` (JSON-quoted
+project root), `{{TS}}` (epoch-ms timestamp).

anvil_state-0.1.1/src/anvil/_data/packaging/codex/automations/anvil-sync-reconcile/automation.toml

@@ -0,0 +1,13 @@
+version = 1
+id = "{{ID}}"
+kind = "cron"
+name = "Anvil — reconcile state"
+prompt = "Run anvil's state reconciliation for this project. Run `anvil sync` (read-only) to detect drift between the SQLite state, the filesystem (packets/, evidence buffer, worktrees), and git (branches, claims). Report any orphan branches, stale claims, orphan packets, or missing sync mappings. Only apply fixes with `anvil sync --fix --yes` when the drift is clearly safe to remediate; otherwise summarize the drift and recommend next actions."
+status = "PAUSED"
+rrule = "FREQ=WEEKLY;BYDAY=MO;BYHOUR=8;BYMINUTE=0"
+model = "gpt-5-codex"
+reasoning_effort = "high"
+execution_environment = "worktree"
+cwds = [{{CWDS}}]
+created_at = {{TS}}
+updated_at = {{TS}}

anvil_state-0.1.1/src/anvil/_data/packaging/codex/automations/anvil-work-queue/automation.toml

@@ -0,0 +1,13 @@
+version = 1
+id = "{{ID}}"
+kind = "cron"
+name = "Anvil — work the task queue"
+prompt = "Work the anvil task queue for this project. Use the anvil MCP tools (or the `anvil` CLI): find the next ready task (get_next_task / `anvil next`), claim it, fetch its work packet, implement it to satisfy the acceptance criteria, run the verification commands, then submit completion evidence — never mark work complete without passing evidence. If no task is ready, say so and stop. Work in the provided worktree; open one PR per task and do not merge."
+status = "PAUSED"
+rrule = "FREQ=WEEKLY;BYDAY=MO,WE,FR;BYHOUR=9;BYMINUTE=0"
+model = "gpt-5-codex"
+reasoning_effort = "high"
+execution_environment = "worktree"
+cwds = [{{CWDS}}]
+created_at = {{TS}}
+updated_at = {{TS}}