@flyingrobots/graft 0.3.1 → 0.3.5

package/CHANGELOG.md

@@ -5,6 +5,51 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.5] - 2026-04-05
+
+### Fixed
+
+- **CI**: use `npx npm@latest` for OIDC trusted publishing — avoids
+  self-upgrade breakage on Node 22's bundled npm.
+
+## [0.3.4] - 2026-04-05
+
+### Fixed
+
+- **CI**: upgrade npm CLI to >=11.5.1 for OIDC trusted publishing.
+
+## [0.3.3] - 2026-04-05
+
+### Fixed
+
+- **CI**: use `npm publish` instead of `pnpm publish` for OIDC
+  provenance.
+
+## [0.3.2] - 2026-04-05
+
+### Added
+
+- **`graft init`**: zero-friction project onboarding. Scaffolds
+  `.graftignore`, adds `.graft/` to `.gitignore`, generates
+  `CLAUDE.md` snippet instructing agents to prefer graft tools,
+  and prints Claude Code hook config. Idempotent.
+- **CI**: release workflow attaches npm tarball + SHA256SUMS to
+  GitHub releases as downloadable assets.
+- **CI**: npm publish via OIDC provenance (no secret needed).
+
+### Changed
+
+- **CLI bootstrap**: `bin/graft.js` resolves tsx from the package's
+  own `node_modules`, so `graft init` works from any directory.
+- **Docs**: regenerated README, GUIDE, BEARING, and VISION signposts.
+- **package.json**: added `publishConfig`, `homepage`, `bugs`,
+  `packageManager`, upgraded keywords for MCP/agent discovery.
+
+### Fixed
+
+- **CI**: removed pnpm version override that conflicted with
+  `packageManager` field.
+
 ## [0.3.1] - 2026-04-05
 
 ### Changed

package/README.md

@@ -10,7 +10,7 @@ tools (outlines, diffs, symbol history) are useful to anyone.
 
 ## Why
 
-Empirical analysis of 1,091 real coding sessions (Blacklight) found
+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
@@ -36,6 +36,16 @@ docker run -i --rm -v "$PWD:/workspace" flyingrobots/graft
 
 ## Quick start
 
+```bash
+npx @flyingrobots/graft init
+```
+
+Scaffolds `.graftignore`, adds `.graft/` to `.gitignore`, generates
+a `CLAUDE.md` snippet telling agents to prefer graft tools, and
+prints Claude Code hook config.
+
+Then add graft to your MCP config:
+
 ```json
 {
   "mcpServers": {
@@ -96,6 +106,47 @@ is structured JSON.
 | `doctor` | Runtime health check |
 | `stats` | Decision metrics summary |
 
+## 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:
+
+```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"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Add to `.claude/settings.json` in your project root.
+**PreToolUse** blocks banned files before the read.
+**PostToolUse** shows the agent what `safe_read` would have saved.
+
+See the **[Setup Guide](docs/GUIDE.md)** for full details on hooks,
+per-editor MCP config, `.graftignore`, and troubleshooting.
+
 ## Reason codes
 
 Every refusal or policy decision includes a machine-readable reason

package/bin/graft.js

@@ -1,11 +1,39 @@
-#!/usr/bin/env -S node --import tsx
+#!/usr/bin/env node
 
-// Graft MCP server — stdio transport
-// Usage: npx @flyingrobots/graft
+// Graft — context governor for coding agents
+// Bootstrap: re-exec with tsx loader resolved from the package's own deps.
 
-import { createGraftServer } from "../src/mcp/server.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
 
-const graft = createGraftServer();
-const transport = new StdioServerTransport();
-await graft.getMcpServer().connect(transport);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require = createRequire(import.meta.url);
+
+// If already running under tsx, proceed directly
+if (process.env.__GRAFT_TSX_LOADED === "1") {
+  const command = process.argv[2];
+  if (command === "init") {
+    const { runInit } = await import("../src/cli/init.js");
+    runInit();
+  } else {
+    const { createGraftServer } = await import("../src/mcp/server.js");
+    const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+    const graft = createGraftServer();
+    const transport = new StdioServerTransport();
+    await graft.getMcpServer().connect(transport);
+  }
+} else {
+  // Re-exec with tsx loader from our own node_modules
+  const tsxPath = require.resolve("tsx/esm");
+  const script = join(__dirname, "graft.js");
+  try {
+    execFileSync(process.execPath, ["--import", tsxPath, script, ...process.argv.slice(2)], {
+      stdio: "inherit",
+      env: { ...process.env, __GRAFT_TSX_LOADED: "1" },
+    });
+  } catch (err) {
+    process.exit(err?.status ?? 1);
+  }
+}

package/docs/GUIDE.md

@@ -12,6 +12,20 @@ Or run without installing:
 npx @flyingrobots/graft
 ```
 
+## Quick setup
+
+```bash
+npx @flyingrobots/graft init
+```
+
+Scaffolds your project for graft in one command:
+- Creates `.graftignore` (template with examples)
+- Adds `.graft/` to `.gitignore`
+- Generates a `CLAUDE.md` snippet instructing agents to prefer graft tools
+- Prints Claude Code hook config for manual setup
+
+Idempotent — safe to run again without duplicating entries.
+
 ## MCP Configuration
 
 Graft runs as an MCP server over stdio. Add it to your editor or

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@flyingrobots/graft",
-  "version": "0.3.1",
+  "version": "0.3.5",
   "description": "Context governor for coding agents — MCP server with policy-enforced reads, structural outlines, and session tracking",
   "type": "module",
+  "packageManager": "pnpm@10.30.0",
   "bin": {
     "graft": "./bin/graft.js",
     "git-graft": "./bin/graft.js"
@@ -16,6 +17,14 @@
     "README.md",
     "CHANGELOG.md"
   ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "pack:check": "pnpm pack --dry-run"
+  },
   "engines": {
     "node": ">=20.11.0"
   },
@@ -65,12 +74,7 @@
     "typescript-eslint": "^8.58.0",
     "vitest": "^4.1.2"
   },
-  "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "lint": "eslint .",
-    "typecheck": "tsc --noEmit",
-    "pack:check": "pnpm pack --dry-run"
+  "pnpm": {
+    "onlyBuiltDependencies": []
   }
-}
+}

package/src/cli/init.ts

@@ -0,0 +1,112 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const GRAFTIGNORE_TEMPLATE = `# Graft ignore patterns — files matching these are refused by safe_read.
+# Syntax: same as .gitignore (glob matching via picomatch).
+
+# Examples:
+# *.generated.ts
+# vendor/**
+# data/**/*.json
+`;
+
+const AGENT_SNIPPET = `## File reads
+
+This project uses [graft](https://github.com/flyingrobots/graft) as
+a context governor. Prefer graft's MCP tools over native file reads:
+
+- Use \`safe_read\` instead of \`Read\` for file contents
+- Use \`file_outline\` to see structure before reading
+- Use \`read_range\` with jump table entries for targeted reads
+- Use \`graft_diff\` instead of \`git diff\` for structural changes
+- Use \`explain\` if you get an unfamiliar reason code
+- Call \`set_budget\` at session start if context is tight
+
+These tools enforce read policy, cache observations, and track
+session metrics. Native reads bypass all of that.
+`;
+
+const GITIGNORE_ENTRY = "\n# Graft runtime data\n.graft/\n";
+
+const HOOKS_CONFIG = `
+Add to .claude/settings.json for Claude Code hook integration:
+
+{
+  "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"
+          }
+        ]
+      }
+    ]
+  }
+}
+`;
+
+function writeIfMissing(filePath: string, content: string, label: string): void {
+  if (fs.existsSync(filePath)) {
+    console.log(`  exists  ${label}`);
+  } else {
+    fs.writeFileSync(filePath, content);
+    console.log(`  create  ${label}`);
+  }
+}
+
+function appendIfMissing(filePath: string, marker: string, content: string, label: string): void {
+  if (fs.existsSync(filePath)) {
+    const existing = fs.readFileSync(filePath, "utf-8");
+    if (existing.includes(marker)) {
+      console.log(`  exists  ${label} (already has graft entry)`);
+      return;
+    }
+    fs.appendFileSync(filePath, content);
+    console.log(`  append  ${label}`);
+  } else {
+    fs.writeFileSync(filePath, content.trimStart());
+    console.log(`  create  ${label}`);
+  }
+}
+
+export function runInit(): void {
+  const cwd = process.cwd();
+  console.log(`\nInitializing graft in ${cwd}\n`);
+
+  // 1. .graftignore
+  writeIfMissing(path.join(cwd, ".graftignore"), GRAFTIGNORE_TEMPLATE, ".graftignore");
+
+  // 2. .gitignore — append .graft/
+  appendIfMissing(path.join(cwd, ".gitignore"), ".graft/", GITIGNORE_ENTRY, ".gitignore");
+
+  // 3. CLAUDE.md — append agent instructions snippet
+  appendIfMissing(path.join(cwd, "CLAUDE.md"), "safe_read", "\n" + AGENT_SNIPPET, "CLAUDE.md");
+
+  // 4. Print hooks config for manual setup
+  console.log(HOOKS_CONFIG);
+
+  console.log("Done. Add graft to your MCP config:\n");
+  console.log(`  {
+    "mcpServers": {
+      "graft": {
+        "command": "npx",
+        "args": ["-y", "@flyingrobots/graft"]
+      }
+    }
+  }
+`);
+}