@flyingrobots/graft 0.5.0 → 0.6.1

package/GUIDE.md

@@ -0,0 +1,53 @@
+# Guide — Graft
+
+This is the developer-level operator guide for Graft. Use it for orientation, the productive-fast path, and to understand how the context governor orchestrates agentic reads.
+
+For deep-track doctrine, worldline internals, and repository-wide engineering standards, use [ADVANCED_GUIDE.md](./ADVANCED_GUIDE.md).
+
+## Choose Your Lane
+
+### 1. Initialize a Repository
+Bootstrap a new repo with read policies, git hooks, and agent instructions.
+- **Run**: `npx @flyingrobots/graft init`
+- **Read**: [Setup Guide](./docs/SETUP.md) (Detailed per-editor steps)
+
+### 2. Standalone CLI Usage
+Manually enforce policies or inspect structural history from your terminal.
+- **Read**: [CLI Signpost](./docs/CLI.md)
+
+### 3. Shared Daemon Mode
+Run the central execution authority for multi-repo work and persistent monitors.
+- **Run**: `npx @flyingrobots/graft daemon`
+- **Read**: [docs/SETUP.md](./docs/SETUP.md) (Daemon bootstrap and `workspace_authorize` / `workspace_bind`)
+- **Read**: [Architecture](./ARCHITECTURE.md) (Daemon section)
+
+## Big Picture: System Orchestration
+
+Graft is a tiered governor. It manages the context burden across three layers:
+
+1. **Graft Core (Policy)**: Pure TypeScript logic that evaluates file size, language support, and session budgets to decide *what* an agent should see.
+2. **Parser (Meaning)**: Uses Tree-Sitter WASM to extract structural outlines and compute diffs, turning raw files into actionable meaning.
+3. **WARP (Memory)**: The Structural Worldline Memory that tracks AST evolution across commits, providing a provenance-aware history of the repository.
+
+## Orientation Checklist
+
+- [ ] **I am setting up a new project**: Start with `README.md` Quick Start.
+- [ ] **I am configuring Claude Code**: Use `npx graft init --write-claude-hooks`.
+- [ ] **I am using daemon mode in a generic MCP client**: Read [docs/SETUP.md](./docs/SETUP.md) and expect explicit `workspace_authorize` then `workspace_bind`.
+- [ ] **I am debugging a structural diff**: Use `npx graft struct diff --json`.
+- [ ] **I am contributing to Graft**: Read `METHOD.md` and `docs/BEARING.md`.
+
+## Rule of Thumb
+
+If you need a comprehensive tool reference, use the [MCP Signpost](./docs/MCP.md).
+
+If you need the daemon trust boundary or handoff model, use
+[docs/strategy/security-model.md](./docs/strategy/security-model.md) and
+[docs/strategy/causal-provenance.md](./docs/strategy/causal-provenance.md).
+
+If you need to know "what's true right now," use [docs/BEARING.md](./docs/BEARING.md).
+
+If you are just starting, use the [README.md](./README.md) and the setup instructions in [docs/SETUP.md](./docs/SETUP.md).
+
+---
+**The goal is inevitably. Every feature is defined by its tests.**

package/README.md

@@ -1,306 +1,144 @@
-<div align="center">
-    <img src="./docs/assets/graft.svg" />
-    <h3>Context governor for coding agents</h3>
-</div>
+# Graft
 
-Graft enforces read policy so coding agents consume the smallest
-structurally correct view of a codebase instead of dumping entire
-files into their context window. Agent-first, but the structural
-tools (outlines, diffs, symbol history) are useful to anyone.
+An industrial-grade context governor for coding agents. Graft enforces read policy so agents consume the smallest structurally correct view of a codebase instead of dumping raw files into their context window.
 
-**v0.5.0** — bounded between-commit activity for humans and agents.
+Graft is designed for the operator who demands precision and the architect who needs a stable foundation for agentic work. It scales from simple policy-aware reads to high-fidelity causal provenance tracking across multi-session worktrees.
 
-## Why
+[![npm version](https://img.shields.io/npm/v/@flyingrobots/graft)](https://www.npmjs.com/package/@flyingrobots/graft)
+[![License](https://img.shields.io/github/license/graft)](./LICENSE)
 
-Empirical analysis of 1,091 real coding sessions ([Blacklight](https://github.com/flyingrobots/blacklight)) found
-that **Read accounts for 96.2 GB of context burden** — 6.6x all
-other tools combined. 58% of reads are full-file. The fattest 2.4%
-of reads produce 24% of raw bytes. Dynamic read caps + session
-management reduce this by **75.1%**.
+![Graft demo](./docs/assets/graft.svg)
 
-## Install
+## Why Graft?
 
-```bash
-npm install -g @flyingrobots/graft
-```
+Unlike simple file-scraping tools, Graft treats the repository as a layered worldline of code structure and causal activity.
 
-Or use directly:
+- **Policy-Enforced Reads**: Automatically degrades large files to structural outlines and jump tables. Refuses binaries, secrets, and lockfiles with machine-readable reasons.
+- **Machine-Readable Contracts**: Responses carry versioned `_schema` metadata and decision receipts so agents can reason about outcomes without scraping prose.
+- **Structural Memory**: Uses WARP (Structural Worldline Memory) to track AST evolution across Git commits. Query what changed structurally without reading a single byte of source code.
+- **Causal Provenance**: Tracks the *why* behind structural changes by logging read, stage, and transition activity into strand-scoped causal workspaces.
+- **Industrial-Grade Daemon**: A same-user local runtime that manages multi-repo authorization, background indexing, and shared-machine worker pools.
 
-```bash
-npx @flyingrobots/graft
-```
+## Quick Start
+
+Graft has three official entry points:
 
-Or run in Docker (no Node required):
+- **API** for direct in-process integration
+- **CLI** for operator and debugging workflows
+- **MCP** for agent transport integration
 
+### 1. Bootstrap a Repo
+Scaffold `.graftignore`, setup git hooks, and seed agent instructions.
 ```bash
-docker run -i --rm -v "$PWD:/workspace" flyingrobots/graft
+npx @flyingrobots/graft init --write-claude-hooks --write-codex-mcp
 ```
 
-## Quick start
-
+### 2. Repo-Local Stdio MCP
+This is the simplest per-repo path for most clients. The current
+checkout is the authority, and there is no separate workspace binding
+step.
 ```bash
-npx @flyingrobots/graft init
+npx @flyingrobots/graft serve
 ```
 
-Scaffolds `.graftignore`, adds `.graft/` to `.gitignore`, generates
-a `CLAUDE.md` snippet telling agents to prefer graft tools, and
-prints Claude Code hook / MCP config for manual setup.
-
-If you use Codex, the explicit `--write-codex-mcp` path also seeds
-`AGENTS.md` so the repo has both the MCP wiring and the instruction
-layer that tells Codex to prefer graft reads. It also writes a larger
-Codex `startup_timeout_sec` because cold `npx` startup can exceed the
-default 30 second MCP budget.
-
-For a project-local one-step bootstrap, use explicit write flags:
-
+### 3. Standalone CLI
+Enforce policy on a single read or inspect structural history.
 ```bash
-npx @flyingrobots/graft init --write-claude-mcp --write-claude-hooks
-npx @flyingrobots/graft init --write-cursor-mcp
-npx @flyingrobots/graft init --write-windsurf-mcp
-npx @flyingrobots/graft init --write-continue-mcp
-npx @flyingrobots/graft init --write-cline-mcp
-npx @flyingrobots/graft init --write-codex-mcp
+npx @flyingrobots/graft read safe src/app.ts
+npx @flyingrobots/graft struct since HEAD~3
 ```
 
-These writes are idempotent. Existing JSON / TOML config is merged
-without duplicating graft entries.
-
-Then add graft to your MCP config:
+### 4. Direct Library API
+Embed Graft in-process when you want direct access without MCP transport
+or CLI process orchestration.
+```ts
+import { createRepoLocalGraft, callGraftTool } from "@flyingrobots/graft";
 
-```json
-{
-  "mcpServers": {
-    "graft": {
-      "command": "npx",
-      "args": ["-y", "@flyingrobots/graft", "serve"]
-    }
-  }
-}
+const graft = createRepoLocalGraft({ cwd: process.cwd() });
+const outline = await callGraftTool(graft, "file_outline", { path: "src/app.ts" });
 ```
 
-The MCP server works with Codex, Claude Code, Cursor, Windsurf,
-Continue, Cline, and any MCP-compatible client. Governed native-read
-behavior differs by client: Claude has hook guardrails, Codex now has
-repo-local `AGENTS.md` bootstrap guidance, and the other clients remain
-MCP-plus-instructions rather than true default-governed reads.
-
-Supported deployment posture today is local-user:
-
-- repo-local `serve` remains the standard editor bootstrap path
-- `graft daemon` now exists as a separate same-user local runtime on a
-  Unix socket or Windows named pipe
-
-The daemon still follows a stricter contract than repo-local stdio:
-daemon sessions start unbound, workspace binding is the authorization
-event, `/healthz` is the liveness surface, and escape hatches like
-`run_capture` stay default-denied there unless a workspace is
-explicitly authorized for that posture through the daemon control
-plane. Daemon-wide inspection now exists through MCP tools such as
-`daemon_status`, `daemon_repos`, `daemon_sessions`,
-`workspace_authorizations`, and `daemon_monitors`. Repo-scoped
-background WARP indexing can now be controlled there too through
-`monitor_start`, `monitor_pause`, `monitor_resume`, and `monitor_stop`.
-
-See the **[Setup decision table](docs/GUIDE.md#choose-your-setup-path)**
-for the fastest path by client and mode, and the full
-**[Setup Guide](docs/GUIDE.md)** for per-editor instructions, Claude
-Code hooks, `.graftignore` configuration, troubleshooting, and
-details on what the agent experiences. For release-facing operator
-surfaces, see **[CLI Guide](docs/CLI.md)**,
-**[MCP Guide](docs/MCP.md)**, and **[Advanced Guide](docs/ADVANCED_GUIDE.md)**.
-Contributors should also read **[Architecture](ARCHITECTURE.md)** for
-the runtime systems map and **[Code of Conduct](CODE_OF_CONDUCT.md)**
-for project participation expectations.
-
-## What it does
+This uses the same repo-local core as the CLI and MCP server, but it
+lets host tools call Graft directly inside the same process.
 
-When an agent asks to read a file, Graft applies policy:
-
-- **Small files** are returned as-is.
-- **Large files** are returned as a structural outline with a jump
-  table so the agent can request specific ranges.
-- **Banned files** (binaries, lockfiles, minified bundles, secrets)
-  are refused with a machine-readable reason code and suggested next
-  steps.
-- **Re-reads** of unchanged files return a cached outline (no wasted
-  context). Changed files return a structural diff (added/removed/
-  changed symbols).
-- **Ranges** are bounded — no stealth `cat` of a 10,000-line file.
-- **Session depth** tightens caps as the context window fills.
-- **Budget governor** — agent declares a byte budget, thresholds
-  tighten as it drains. No single read may consume more than 5% of
-  remaining budget.
-- **Structural memory** — WARP-backed structural history across git
-  commits. Query what changed structurally without reading files.
-- **Tripwires** signal when the session is going off the rails.
-- **Receipts** on every response with session/trace correlation,
-  latency, and compression ratio for usage analysis.
-- **MCP runtime observability** — metadata-only session and tool-call
-  logs under `.graft/logs/mcp-runtime.ndjson`.
-- **Versioned schemas** on every machine-readable MCP / CLI payload.
-- **Between-commit activity view** — bounded local `artifact_history`
-  over recent continuity, transitions, staging, and reads, anchored
-  to the current commit when possible.
-
-Every decision is logged. Every refusal is explainable. All output
-is structured JSON with versioned `_schema` metadata.
-
-## Tools
-
-| Tool | Purpose |
-|---|---|
-| `safe_read` | Policy-enforced file read (content, outline, refusal, or diff) |
-| `file_outline` | Structural skeleton with jump table |
-| `read_range` | Bounded range read (max 250 lines), policy-gated |
-| `graft_diff` | Structural diff between git refs with per-file summary lines and explicit denied-file reporting |
-| `graft_since` | Structural changes since a git ref — symbols added/removed/changed with explicit denied-file reporting |
-| `graft_map` | Structural map of a directory — all files and symbols in one call, with explicit denied-file reporting |
-| `code_show` | Focus on a symbol by name — get its source code in one call |
-| `code_find` | Search symbols across the project by approximate name or glob, with optional kind/path filters |
-| `code_refs` | Search import sites, callsites, property access, or literal text references with explicit text-fallback provenance |
-| `changed_since` | Check if a file changed since last read (peek or consume) |
-| `run_capture` | Diagnostic shell-output escape hatch — tail to agent, optional redacted log persistence, explicit enable/disable posture, outside bounded-read policy, with explicit `policyBoundary` marker |
-| `state_save` | Save session working state (max 8 KB) |
-| `state_load` | Restore session working state |
-| `set_budget` | Declare session byte budget — governor tightens as it drains |
-| `activity_view` | Recent bounded local `artifact_history` for the active workspace, with current commit anchor, grouped activity, and degraded posture |
-| `explain` | Human-readable help for any reason code |
-| `doctor` | Runtime health check with burden summary and layered-worldline state |
-| `stats` | Decision metrics summary with cumulative burden-by-kind totals |
-
-## Claude Code hooks
-
-Two hooks work alongside the MCP server to govern native `Read`
-calls — a safety net for when agents bypass graft's tools:
+When you want a direct repo-local read surface instead of tool receipts,
+use the workspace API:
+```ts
+import { createRepoWorkspace } from "@flyingrobots/graft";
 
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Read",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/pretooluse-read.ts"
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Read",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node --import tsx node_modules/@flyingrobots/graft/src/hooks/posttooluse-read.ts"
-          }
-        ]
-      }
-    ]
-  }
-}
+const workspace = await createRepoWorkspace({ cwd: process.cwd() });
+const first = await workspace.safeRead({ path: "src/app.ts" });
+const second = await workspace.safeRead({ path: "src/app.ts" });
+const outline = await workspace.fileOutline({ path: "src/app.ts" });
 ```
 
-Add to `.claude/settings.json` in your project root.
-**PreToolUse** blocks banned files and redirects large JS/TS reads to
-`safe_read` before native `Read` can dump them into context.
-**PostToolUse** is the backstop: it reports what `safe_read` would have
-saved when an oversized code read still slips through.
+This exposes the same governed repo-local read behavior that the MCP
+surface uses for `safe_read`, `file_outline`, `read_range`, and
+`changed_since`, but without going through MCP receipts at all.
 
-See the **[Setup Guide](docs/GUIDE.md)** for full details on hooks,
-per-editor MCP config, `.graftignore`, and troubleshooting.
-
-## CLI
+For close editor integration, use the buffer-native surface directly:
+```ts
+import { createProjectionBundle, createStructuredBuffer } from "@flyingrobots/graft";
+
+const buffer = createStructuredBuffer("src/app.tsx", liveEditorText, {
+  basis: { kind: "editor_head", headId: "head-42", tick: 17 },
+});
+const spans = buffer.syntaxSpans({
+  viewport: {
+    start: { row: 0, column: 0 },
+    end: { row: 80, column: 0 },
+  },
+});
+const context = buffer.nodeAt({ row: 24, column: 12 });
+const rename = buffer.renamePreview({
+  position: { row: 24, column: 12 },
+  nextName: "nextValue",
+});
+
+// Every warm result now carries the basis it was derived from.
+console.log(spans.basis);
+
+const bundle = createProjectionBundle("src/app.tsx", liveEditorText, {
+  basis: { kind: "editor_head", headId: "head-42", tick: 17 },
+  viewport: {
+    start: { row: 0, column: 0 },
+    end: { row: 80, column: 0 },
+  },
+});
+
+console.log(bundle.parseStatus.status);
+```
 
+### 5. Shared Daemon Runtime
+Start the same-user execution authority for multi-session or multi-repo
+work.
 ```bash
-npx @flyingrobots/graft init
-npx @flyingrobots/graft init --write-claude-mcp --write-claude-hooks
-npx @flyingrobots/graft init --write-cursor-mcp
-npx @flyingrobots/graft init --write-windsurf-mcp
-npx @flyingrobots/graft init --write-continue-mcp
-npx @flyingrobots/graft init --write-cline-mcp
-npx @flyingrobots/graft init --write-codex-mcp
-npx @flyingrobots/graft serve
-npx @flyingrobots/graft index
-npx @flyingrobots/graft read safe src/app.ts --json
-npx @flyingrobots/graft read outline README.md --json
-npx @flyingrobots/graft read range src/app.ts --start 10 --end 40 --json
-npx @flyingrobots/graft read changed src/app.ts --json
-npx @flyingrobots/graft struct diff --json
-npx @flyingrobots/graft struct since HEAD~3 --json
-npx @flyingrobots/graft struct map src --json
-npx @flyingrobots/graft symbol show createServer --path src/mcp/server.ts --json
-npx @flyingrobots/graft symbol find 'create*' --json
-npx @flyingrobots/graft diag activity --json
-npx @flyingrobots/graft diag doctor --json
-npx @flyingrobots/graft diag explain CONTENT --json
-npx @flyingrobots/graft diag stats --json
-npx @flyingrobots/graft diag capture --tail 20 -- pnpm test --json
+npx @flyingrobots/graft daemon
 ```
 
-The CLI now mirrors the core MCP product surface through grouped
-namespaces:
-- `read` for bounded reads
-- `struct` for structural navigation
-- `symbol` for precision lookup
-- `diag` for diagnostics
-
-`init` and `index` remain explicit CLI-only commands. MCP responses and
-CLI peer commands both carry versioned `_schema` metadata, and declared
-output contracts live in `src/contracts/output-schemas.ts`.
-
-`run_capture` remains an explicit shell escape hatch. For shared or
-release-sensitive environments, you can disable it with
-`GRAFT_ENABLE_RUN_CAPTURE=0`. Persisted capture logs can be disabled
-with `GRAFT_RUN_CAPTURE_PERSIST=0`, and persisted output is redacted for
-obvious secret-shaped values by default. In the local daemon runtime,
-`run_capture` remains opt-in rather than ambiently available.
+Daemon sessions start `unbound`. If your client connects through the
+daemon instead of repo-local stdio, the first repo-scoped flow is:
 
-## Reason codes
+1. `workspace_authorize` for the target repo/worktree
+2. `workspace_bind` for the active daemon session
+3. then use repository-scoped tools such as `safe_read`
 
-Every refusal or policy decision includes a machine-readable reason
-code. Use `explain(code)` to get meaning and recommended action.
+Use [docs/SETUP.md](./docs/SETUP.md) for the exact client bootstrap and
+daemon control-plane posture.
 
-| Code | Meaning |
-|------|---------|
-| `CONTENT` | File within thresholds — full content returned |
-| `OUTLINE` | File exceeds thresholds — structural outline returned |
-| `SESSION_CAP` | Session-depth byte cap triggered |
-| `BUDGET_CAP` | Budget-proportional cap triggered |
-| `UNSUPPORTED_LANGUAGE` | No parser-backed outline for this file type |
-| `BINARY` | Binary file refused |
-| `LOCKFILE` | Machine-generated lockfile refused |
-| `MINIFIED` | Minified file refused |
-| `BUILD_OUTPUT` | Build output directory refused |
-| `SECRET` | Potential secrets file refused |
-| `GRAFTIGNORE` | Matches .graftignore pattern |
+## Documentation
 
-## License
-
-Apache 2.0 — see [LICENSE](LICENSE).
+- **[Guide](./GUIDE.md)**: Orientation, the fast path, and agent bootstrap.
+- **[Setup Guide](./docs/SETUP.md)**: Client-specific MCP setup, daemon posture, and workspace binding.
+- **[Advanced Guide](./ADVANCED_GUIDE.md)**: Deep dives into the pipeline, worldlines, and daemon mechanics.
+- **[Architecture](./ARCHITECTURE.md)**: The authoritative structural reference (Ports, Adapters, WARP).
+- **[Public API Contract](./docs/public-api.md)**: The semver-public root import surface and stability policy.
+- **[Repo Topology](./docs/repo-topology.md)**: Where API, CLI, MCP, and the core live in the source tree.
+- **[Three-Surface Capability Matrix](./docs/three-surface-capability-matrix.md)**: Current API / CLI / MCP baseline and peer posture.
+- **[Security Model](./docs/strategy/security-model.md)**: Same-user daemon trust boundaries, authz, and observability posture.
+- **[Causal Provenance](./docs/strategy/causal-provenance.md)**: Transport sessions, causal workspaces, strands, and handoff truth.
+- **[Vision](./docs/VISION.md)**: Core tenets and the provenance-aware mission.
+- **[Method](./METHOD.md)**: Repo work doctrine and the cycle loop.
 
 ---
-
-```ts
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⣾⣿⣿⣿⣿⣷⣄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣿⣿⣿⣿⣿⣿⣿⣿⠿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣶⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⠁⠀⠀⠀⠀⠀⠀⠀⠀⢀⣴⣆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⢀⣤⣴⣶⣶⣶⣶⣦⣤⣼⣿⣿⣿⣿⣿⠀⢠⣶⣶⣦⡀⠀⢀⣴⣶⣶⣤⠀⠀⠀⠀⣀⣤⣴⣶⣶⣶⣶⣦⣄⠀⠀⠀⠀⠀⠀⠀⠈⣿⣿⡄⠀⣀⣀⣠⣤⠀⠀⢀⣾⣿⣿⣀⣀⣀⣤⣤⣄⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⣴⣿⣿⠛⠉⠉⠉⠛⠿⣿⣿⣿⡿⠉⠉⠀⠀⢻⣿⣿⣿⣇⠀⣾⣿⣿⣿⣿⡇⠀⢠⣾⣿⣿⣿⡿⠟⠛⢻⣿⣿⣷⠀⠀⠀⠀⠀⣠⣾⣿⣿⣿⣿⣿⣿⣿⣿⠀⢠⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⢸⣿⣿⣇⠀⠀⠀⠀⠀⠀⠘⣿⣿⡇⠀⠀⠀⠀⠈⢿⣿⣿⣿⢠⡿⠛⠛⠿⠟⠁⠀⢺⣿⣿⡿⠋⠀⠀⠀⣸⣿⣿⣿⡀⠀⠀⠀⠀⠛⠿⢿⣿⣿⠟⠛⠛⠛⠛⠀⠘⠻⠿⢿⣿⣿⠛⠛⠛⠛⠋⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠸⣿⣿⣿⣆⠀⠀⠀⠀⠀⠀⣿⣿⡇⠀⠀⠀⠀⠀⠀⢻⣿⣿⣿⠁⠀⠀⠀⠀⠀⠀⠀⠉⠉⠀⠀⠀⣠⣾⠟⢻⣿⣿⡇⠀⠀⠀⠀⠀⠀⠈⣿⣿⡆⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠙⢿⣿⣿⣿⣶⣤⣤⣤⣾⣿⠟⠀⠀⠀⠀⠀⠀⠀⠀⢻⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣠⣾⡿⠋⠀⢸⣿⣿⡇⠀⢀⣤⡀⠀⠀⠀⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⡆⠀⠀⠀⢀⣀⡀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⣨⣿⡿⠟⠛⠛⠛⠋⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿⣿⡆⠀⠀⠀⠀⠀⠀⠀⠀⢠⣾⣿⡏⠀⠀⠀⢸⣿⣿⡇⠀⢸⣿⡇⠀⠀⠀⢻⣿⣿⣇⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣇⠀⠀⠀⢸⣿⣿⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⣼⣿⣿⡀⠀⢀⣀⣀⣤⣤⣤⣴⣦⣤⣄⠀⠀⠀⠀⢰⣿⣿⣷⠀⠀⠀⠀⠀⠀⠀⠀⢾⣿⣿⣇⠀⠀⣠⣿⢻⣿⣿⡀⣸⣿⡇⠀⠀⠀⠸⣿⣿⣿⡄⠀⠀⠀⠀⠀⠀⠀⣿⣿⣿⣦⣀⣠⣾⣿⡟⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠹⢿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣿⣇⠀⠀⠀⢸⣿⣿⣿⡆⠀⠀⠀⠀⠀⠀⠀⠘⣿⣿⣿⣿⣿⣿⠏⠀⢿⣿⣿⣿⣿⠇⠀⠀⠀⠀⣿⣿⣿⣧⠀⠀⠀⠀⠀⠀⠀⠘⢿⣿⣿⣿⣿⣿⣿⠃⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⢀⣼⣿⠟⠉⠁⠀⠀⠀⠀⠀⢻⣿⣿⡟⠀⠀⠀⠈⠉⠉⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠈⠙⠛⠛⠛⠁⠀⠀⠀⠙⠛⠛⠁⠀⠀⠀⠀⠀⣿⣿⣿⣿⡆⠀⠀⠀⠀⠀⠀⠀⠀⠙⠛⠛⠛⠋⠁⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⢠⣿⣿⣿⠀⠀⠀⠀⠀⠀⠀⢀⣾⣿⡿⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⣿⣿⣿⣷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠈⢿⣿⣿⣷⣤⣤⣤⣤⣤⣾⣿⡿⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⣿⣿⣿⣿⠆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠙⠛⠻⠿⠿⠿⠛⠛⠋⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠙⠿⠿⠋⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀
-```
+Built with precision by [FLYING ROBOTS](https://github.com/flyingrobots)

package/bin/graft.js

@@ -13,9 +13,11 @@ const require = createRequire(import.meta.url);
 
 // If already running under tsx, proceed directly
 if (process.env.__GRAFT_TSX_LOADED === "1") {
-  const { resolveEntrypointArgs, runCli } = await import("../src/cli/main.js");
-  await runCli({
-    args: resolveEntrypointArgs(process.argv.slice(2), process.stdin.isTTY, process.stdout.isTTY),
+  const { runCliEntrypoint } = await import("../src/cli/entrypoint.js");
+  await runCliEntrypoint({
+    argv: process.argv.slice(2),
+    stdinIsTTY: process.stdin.isTTY,
+    stdoutIsTTY: process.stdout.isTTY,
   });
 } else {
   // Re-exec with tsx loader from our own node_modules

package/dist/adapters/canonical-json.d.ts

@@ -0,0 +1,6 @@
+import type { JsonCodec } from "../ports/codec.js";
+export declare class CanonicalJsonCodec implements JsonCodec {
+    encode(value: unknown): string;
+    decode(data: string): unknown;
+}
+//# sourceMappingURL=canonical-json.d.ts.map

package/dist/adapters/canonical-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.d.ts","sourceRoot":"","sources":["../../src/adapters/canonical-json.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAmCnD,qBAAa,kBAAmB,YAAW,SAAS;IAClD,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;IAI9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAG9B"}

package/dist/adapters/canonical-json.js

@@ -0,0 +1,52 @@
+// ---------------------------------------------------------------------------
+// CanonicalJsonCodec — deterministic JSON with sorted keys
+// ---------------------------------------------------------------------------
+//
+// Subset of RFC 8785 (JSON Canonicalization Scheme):
+//   - Object keys sorted lexicographically at every nesting level
+//   - Compact output (no whitespace)
+//   - Deterministic: same data always produces the same string
+//
+// Enables stable hashes, diffable logs, reproducible receipts.
+// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function sortDeep(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    if (!isPlainObject(value) && !Array.isArray(value)) {
+        return value;
+    }
+    if (seen.has(value)) {
+        throw new TypeError("Converting circular structure to JSON");
+    }
+    seen.add(value);
+    try {
+        if (Array.isArray(value)) {
+            return value.map((v) => sortDeep(v, seen));
+        }
+        const sorted = {};
+        for (const key of Object.keys(value).sort()) {
+            sorted[key] = sortDeep(value[key], seen);
+        }
+        return sorted;
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+export class CanonicalJsonCodec {
+    encode(value) {
+        return JSON.stringify(sortDeep(value));
+    }
+    decode(data) {
+        return JSON.parse(data);
+    }
+}
+//# sourceMappingURL=canonical-json.js.map

package/dist/adapters/canonical-json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.js","sourceRoot":"","sources":["../../src/adapters/canonical-json.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,2DAA2D;AAC3D,8EAA8E;AAC9E,EAAE;AACF,qDAAqD;AACrD,kEAAkE;AAClE,qCAAqC;AACrC,+DAA+D;AAC/D,EAAE;AACF,+DAA+D;AAC/D,8EAA8E;AAI9E,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAY,CAAC;IACtD,OAAO,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,CAAC;AACtD,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc,EAAE,IAAI,GAAG,IAAI,OAAO,EAAE;IACpD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACnD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CAAC,uCAAuC,CAAC,CAAC;IAC/D,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IAChB,IAAI,CAAC;QACH,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;QAC7C,CAAC;QACD,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC5C,MAAM,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,OAAO,kBAAkB;IAC7B,MAAM,CAAC,KAAc;QACnB,OAAO,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,CAAC,IAAY;QACjB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IACrC,CAAC;CACF"}

package/dist/adapters/node-fs.d.ts

@@ -0,0 +1,3 @@
+import type { FileSystem } from "../ports/filesystem.js";
+export declare const nodeFs: FileSystem;
+//# sourceMappingURL=node-fs.d.ts.map

package/dist/adapters/node-fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs.d.ts","sourceRoot":"","sources":["../../src/adapters/node-fs.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAoCzD,eAAO,MAAM,MAAM,EAAE,UAAiC,CAAC"}

package/dist/adapters/node-fs.js

@@ -0,0 +1,33 @@
+// ---------------------------------------------------------------------------
+// Node.js filesystem adapter — implements the FileSystem port
+// ---------------------------------------------------------------------------
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+class NodeFileSystem {
+    readFile(path, encoding) {
+        if (encoding !== undefined)
+            return fsp.readFile(path, encoding);
+        return fsp.readFile(path);
+    }
+    readdir(path) {
+        return fsp.readdir(path);
+    }
+    writeFile(path, data, encoding) {
+        return fsp.writeFile(path, data, encoding);
+    }
+    appendFile(path, data, encoding) {
+        return fsp.appendFile(path, data, encoding);
+    }
+    async mkdir(path, options) {
+        await fsp.mkdir(path, options);
+    }
+    async stat(path) {
+        const s = await fsp.stat(path);
+        return { size: s.size };
+    }
+    readFileSync(path, encoding) {
+        return fs.readFileSync(path, encoding);
+    }
+}
+export const nodeFs = new NodeFileSystem();
+//# sourceMappingURL=node-fs.js.map

package/dist/adapters/node-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs.js","sourceRoot":"","sources":["../../src/adapters/node-fs.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,8DAA8D;AAC9D,8EAA8E;AAE9E,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAC;AAGxC,MAAM,cAAc;IAGlB,QAAQ,CAAC,IAAY,EAAE,QAAkB;QACvC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAChE,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,SAAS,CAAC,IAAY,EAAE,IAAY,EAAE,QAAiB;QACrD,OAAO,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED,UAAU,CAAC,IAAY,EAAE,IAAY,EAAE,QAAiB;QACtD,OAAO,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED,KAAK,CAAC,KAAK,CAAC,IAAY,EAAE,OAA4B;QACpD,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED,YAAY,CAAC,IAAY,EAAE,QAAiB;QAC1C,OAAO,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;CACF;AAED,MAAM,CAAC,MAAM,MAAM,GAAe,IAAI,cAAc,EAAE,CAAC"}

package/dist/adapters/node-git.d.ts

@@ -0,0 +1,3 @@
+import type { GitClient } from "../ports/git.js";
+export declare const nodeGit: GitClient;
+//# sourceMappingURL=node-git.d.ts.map

package/dist/adapters/node-git.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-git.d.ts","sourceRoot":"","sources":["../../src/adapters/node-git.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAiB,MAAM,iBAAiB,CAAC;AAyChE,eAAO,MAAM,OAAO,EAAE,SAA+B,CAAC"}