dsh-graft-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adithyan Raj
+
+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.

package/README.md

@@ -0,0 +1,129 @@
+# dsh-graft-plugin
+
+![language](https://img.shields.io/badge/language-javascript-f7dc6f) ![style](https://img.shields.io/badge/style-vanilla-gray) ![license](https://img.shields.io/badge/license-MIT-blue) ![node](https://img.shields.io/badge/node-%E2%89%A5%2022-brightgreen) ![dsh](https://img.shields.io/badge/dsh-web%20profile-orange) ![runtime](https://img.shields.io/badge/runtime-offline_%C2%B7_100%25_local-brightgreen) ![tests](https://img.shields.io/badge/tests-91_passing-brightgreen)
+
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that puts [graft](https://github.com/trailhq/Graft) — a prebuilt graph of every symbol, its `file:line` span, and who calls what — in front of both you and the model.
+
+It does four things:
+
+- **A chip in the composer** naming the graft index the current session is actually serving, whether it still matches the code, and how many tokens graft has saved in that repo.
+- **Five tools for the model** — `graft_ask`, `graft_grep`, `graft_callers`, `graft_skeleton`, `graft_map` — resolved per session, so one dsh can serve several workspaces at once.
+- **`/graft`** to build or rebuild the index, and **auto-rebuild** after the model edits files.
+- **A `graft viz` button** that opens the graph as a tab in [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar).
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-graft-plugin
+dsh --profile web
+```
+
+The install also puts the graft CLI (`@nanonets/graft`) on your PATH — every tool here shells out to it, so a plugin without it can do nothing. If your global npm prefix needs elevation the postinstall says so and prints the one command to run by hand:
+
+```sh
+npm install -g @nanonets/graft
+```
+
+Then index a repo once:
+
+```sh
+cd <your repo>
+graft build
+```
+
+### The sidebar tab
+
+The `graft viz` button needs `dsh-better-sidebar` **mounted**. It ships as a dependency of this plugin, so it is already downloaded — but dsh only mounts what the profile lists:
+
+```sh
+dsh plugin --profile web add dsh-better-sidebar
+```
+
+Skip it if you do not want the tab. The chip, the tools, `/graft` and the auto-rebuild all work without it; the button just reports that the sidebar is unavailable.
+
+> This plugin does **not** insert a `dsh-better-sidebar` row itself, on purpose. That package's own bundle row carries a guard that disables it when another enabled row already mounts the same package. A second row with a different id makes that guard circular, and the losing outcome is *your existing sidebar silently disabling itself*. One explicit command is worth more than that risk.
+
+## What you get
+
+### The chip
+
+Sits in the composer next to the model name:
+
+```
+● graft · my-repo          in sync
+◐ graft · my-repo          syncing
+▲ graft · my-repo          stale
+```
+
+Hovering (or clicking) opens a card with the resolved root, node and edge counts, freshness, the running saved-token tally, and the `graft viz` button.
+
+![The chip in the composer, with its hover card](assets/chip.png)
+
+The root is resolved from **the session's own workspace**, not from wherever dsh was launched. That is the whole reason this exists rather than the `graft mcp` server: `graft mcp` resolves its repo once, from its own working directory at startup, and nothing can re-point it afterwards. Launched from a home directory it answers *"no graph found"* for every workspace you open.
+
+### The visualiser
+
+The `graft viz` button opens the graph as a tab in [dsh-better-sidebar](https://github.com/omdsh-dev/DSH-better-sidebar). The context view lays out the whole graph:
+
+![The graph in the sidebar — context view](assets/viz-context.png)
+
+The code view drills into a single file — what it contains, what it depends on, what depends on it:
+
+![The graph in the sidebar — code view](assets/viz-code.png)
+
+### The tools
+
+| tool | what it answers |
+|---|---|
+| `graft_ask` | "how does X work" / "where is Y" — ranked hits with code inlined at exact `file:line` |
+| `graft_grep` | every occurrence, grouped by enclosing symbol (`graft_ask` is top-N and misses some) |
+| `graft_callers` | who calls a symbol, what it calls, or the full blast radius before a rename |
+| `graft_skeleton` | a file's whole API in ~200 tokens |
+| `graft_map` | orientation in an unfamiliar tree |
+
+None of them take a boolean parameter. They take string enums instead — `detail: "full"` rather than `full: true` — which reads better to a model and sidesteps a real failure mode on some OpenAI-compatible servers, where a tool call that *sets* a boolean is emitted as literal `<tool_call>` text and never runs.
+
+### `/graft`
+
+- `/graft` — build the index, or rebuild it if one exists
+- `/graft status` — what the chip knows, as text
+- `/graft deep` — a full rebuild
+
+### Auto-rebuild
+
+After the model writes or edits files, the index is rebuilt in the background, debounced so a long turn does not rebuild on every keystroke. This reuses graft's own sync runner rather than reimplementing it, so it cannot drift from what `graft build` does.
+
+## Configuration
+
+All optional, all on the plugin's row in your profile's `cordis.patch.yml`:
+
+```yaml
+- id: graft-status
+  name: 'dsh-graft-plugin'
+  config:
+    cwd: 'C:/path/to/repo'   # pin to one repo instead of resolving per session
+    tools: false             # drop the graft_* tools, keep the chip
+    command: false           # drop /graft
+    promptSection: false     # stop telling the model to prefer graft
+    autoBuild: false         # stop rebuilding after edits
+```
+
+## Requirements
+
+- dsh `0.1.2-rc.1` or newer, web profile
+- Node 22+
+- the `graft` CLI on PATH (installed for you; see above)
+
+## Development
+
+```sh
+npm install
+npm test           # portable: builds a synthetic graft index in a temp dir
+npm run test:live  # drives the real graft CLI against a real repo
+```
+
+`npm test` needs no graft index and no graft install anywhere on the machine. The one suite that does build a real index skips itself, loudly, when graft is absent — a missing CLI is a setup state, not a defect.
+
+## Licence
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,24 @@
+# dsh-graft-plugin bundle patch: mount the host half, which reads the graft index files
+# and answers the browser's questions about them. The browser half — the chip,
+# the viz button and the sidebar tab — is mounted by the `dsh.client` entry in
+# package.json, not from here.
+#
+# `name` MUST be the published package name, because the loader imports this
+# exact specifier. `id` is this row's handle and is deliberately NOT renamed
+# alongside the package: it is the key the storage file (graft-status.json), the
+# prompt section (graft-status:usage) and every effect label already use, and
+# churning it would orphan a user's saved token tally for no gain.
+#
+# Config (all optional, all set on this row):
+#   cwd                    pin the lookup to one repo. Left unset it resolves
+#                          from the session's own workspace, then dsh's working
+#                          directory — the same rule `graft mcp` applies, so the
+#                          chip and the tools cannot disagree about which graph
+#                          is in play.
+#   tools: false           drop the graft_* tools, keep the chip
+#   command: false         drop the /graft command
+#   promptSection: false   stop telling the model to prefer graft
+#   autoBuild: false       stop rebuilding the index after edits
+- insert:
+    - id: graft-status
+      name: 'dsh-graft-plugin'

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "dsh-graft-plugin",
+  "version": "0.1.0",
+  "description": "Shows which graft index a dsh session is serving and whether it still matches the code, and gives the model graft_ask, graft_grep, graft_callers, graft_skeleton and graft_map as native tools.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./client": "./src/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json",
+    "./graft-tools": "./src/graft-tools.js",
+    "./auto-sync": "./src/auto-sync.js",
+    "./command": "./src/command.js"
+  },
+  "files": [
+    "src/index.js",
+    "src/graft-tools.js",
+    "src/auto-sync.js",
+    "src/command.js",
+    "src/client.js",
+    "cordis.patch.yml",
+    "scripts/postinstall.mjs",
+    "scripts/test-harness.mjs",
+    "scripts/test-tools.mjs",
+    "scripts/test-autosync.mjs",
+    "scripts/test-command.mjs",
+    "README.md",
+    "LICENSE",
+    "screenshots.json"
+  ],
+  "scripts": {
+    "test": "node scripts/test-harness.mjs && node scripts/test-autosync.mjs && node scripts/test-command.mjs",
+    "test:live": "node scripts/test-tools.mjs",
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-api-remotes"
+      ]
+    }
+  },
+  "dependencies": {
+    "dsh-better-sidebar": "^0.18.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "0.1.2-rc.1"
+  },
+  "keywords": [
+    "dsh-plugin",
+    "dsh",
+    "graft",
+    "code-graph",
+    "context",
+    "tools"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adithyanraj03/dsh-graft-plugin.git"
+  },
+  "homepage": "https://adithyanraj03.github.io/dsh-graft-plugin/",
+  "bugs": {
+    "url": "https://github.com/adithyanraj03/dsh-graft-plugin/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT"
+}

package/screenshots.json

@@ -0,0 +1,5 @@
+[
+  "assets/chip.png",
+  "assets/viz-context.png",
+  "assets/viz-code.png"
+]

package/scripts/postinstall.mjs

@@ -0,0 +1,109 @@
+/**
+ * Put the graft CLI on the machine, and say what is still left to do.
+ *
+ * WHY A POSTINSTALL AT ALL
+ *
+ * This plugin is a front end. Every tool it registers shells out to `graft`,
+ * and the chip reads an index `graft build` writes — so a correct install of
+ * the plugin with no `graft` on PATH is a plugin that can do nothing, and says
+ * so only at the first tool call. Installing it here turns that into one
+ * install step instead of two.
+ *
+ * WHY IT NEVER FAILS THE INSTALL
+ *
+ * A global npm install is exactly the kind of thing that is refused: no write
+ * permission on the prefix, an offline machine, a locked-down CI image, or
+ * `--ignore-scripts` (which skips this file entirely and is a perfectly
+ * reasonable thing for a careful user to do). None of those mean the PLUGIN
+ * failed to install, so none of them exit non-zero. They print the one command
+ * to run by hand and get out of the way.
+ *
+ * Set DSH_GRAFT_SKIP_POSTINSTALL=1 to skip it outright.
+ */
+
+import { spawn } from 'node:child_process'
+import { delimiter, join } from 'node:path'
+import { existsSync } from 'node:fs'
+
+/** The package behind the `graft` command. The GitHub home is trailhq/Graft. */
+const PACKAGE = '@nanonets/graft'
+
+const BOLD = ''
+const DIM = ''
+const OFF = ''
+
+const say = (line = '') => process.stdout.write(`${line}\n`)
+
+/** Is `graft` already reachable? Checked before installing, so a re-install is a no-op. */
+function graftOnPath(env = process.env, exists = existsSync) {
+  const path = String(env.PATH ?? env.Path ?? '')
+  for (const dir of path.split(delimiter)) {
+    if (dir === '') continue
+    for (const name of ['graft.cmd', 'graft.exe', 'graft']) {
+      if (exists(join(dir, name))) return true
+    }
+  }
+  return false
+}
+
+/** Run a command to completion. Resolves with the exit code; never rejects. */
+function run(command, args) {
+  return new Promise((resolve) => {
+    let child
+    try {
+      // `shell: true` on Windows, because npm is a `.cmd` shim that cannot be
+      // exec'd directly. No argument here contains a space, so the unquoted
+      // argv join that makes `shell: true` dangerous cannot bite.
+      child = spawn(command, args, { stdio: 'inherit', shell: process.platform === 'win32' })
+    } catch {
+      resolve(null)
+      return
+    }
+    child.on('error', () => resolve(null))
+    child.on('close', (code) => resolve(code))
+  })
+}
+
+async function main() {
+  if (process.env.DSH_GRAFT_SKIP_POSTINSTALL === '1') return
+
+  say()
+  say(`${BOLD}dsh-graft-plugin${OFF}`)
+
+  if (graftOnPath()) {
+    say(`  ${DIM}graft is already on PATH - nothing to install.${OFF}`)
+  } else {
+    say(`  installing the graft CLI (${PACKAGE}) globally...`)
+    const code = await run('npm', ['install', '-g', PACKAGE])
+    if (code === 0) {
+      say(`  ${BOLD}done.${OFF} graft is on PATH.`)
+    } else {
+      say()
+      say(`  ${BOLD}graft was not installed${OFF} (npm exited ${code === null ? 'without running' : code}).`)
+      say('  This plugin needs it. Install it by hand:')
+      say()
+      say(`      npm install -g ${PACKAGE}`)
+      say()
+      say('  On a machine where the global prefix needs elevation, run that in an')
+      say('  administrator shell, or point npm at a writable prefix first.')
+    }
+  }
+
+  say()
+  say(`  ${BOLD}Next:${OFF}`)
+  say('    1. Index a repo:   cd <your repo> && graft build')
+  say('    2. The sidebar tab for `graft viz` needs dsh-better-sidebar mounted.')
+  say('       It ships as a dependency of this plugin, so it is already downloaded,')
+  say('       but dsh only mounts what the profile lists:')
+  say()
+  say('           dsh plugin --profile web add dsh-better-sidebar')
+  say()
+  say('       Skip it if you do not want the tab - the chip, the tools, the')
+  say('       /graft command and the auto-rebuild all work without it.')
+  say()
+}
+
+main().catch(() => {
+  // A postinstall that throws fails the install of a plugin that is, itself,
+  // perfectly fine. Never do that.
+})

package/scripts/test-autosync.mjs

@@ -0,0 +1,117 @@
+import { savedTokensIn } from '../src/graft-tools.js'
+import { createAutoSync } from '../src/auto-sync.js'
+import { totalSaved } from '../src/index.js'
+
+let failures = 0
+const check = (l, ok, extra = '') => { console.log((ok ? 'PASS  ' : 'FAIL  ') + l + (extra ? '  -> ' + extra : '')); if (!ok) failures += 1 }
+
+console.log('--- reading graft\'s own savings line ---')
+check('plain grouping', savedTokensIn('[graft] tokens saved ≈ 26,730 (99%) — this output ≈ 308 tok') === 26730)
+// This machine renders lakh grouping; a locale-naive parse would read 150.
+check('Indian grouping (as this host prints it)', savedTokensIn('[graft] tokens saved ≈ 1,50,427 (100%) — x') === 150427)
+check('no separators', savedTokensIn('tokens saved ≈ 42 (10%) — x') === 42)
+check('absent line is zero, not NaN', savedTokensIn('no such line here') === 0)
+check('undefined is zero', savedTokensIn(undefined) === 0)
+
+console.log('\n--- the two tallies are summed, not merged ---')
+check('graft + ours', totalSaved(663783, 26730) === 690513)
+check('missing ours', totalSaved(663783, undefined) === 663783)
+check('neither', totalSaved(undefined, undefined) === 0)
+
+console.log('\n--- auto-rebuild gating ---')
+let now = 1_000_000
+let spawned = []
+const state = {
+  stats: { dirty: false },
+  readStats: () => state.stats,
+  patchStats: (_d, patch) => Object.assign(state.stats, patch),
+  acquireLock: () => state.lock !== false,
+}
+const make = (over = {}) => createAutoSync({
+  graft: { state, syncRun: 'C:/fake/sync-run.js' },
+  now: () => now,
+  spawn: (...a) => { spawned.push(a); return { on() {}, unref() {} } },
+  ...over,
+})
+
+let sync = make()
+// dsh's REAL wire names, from the packages that register them: dsh-tool-fs
+// (write, edit), dsh-tool-str-replace-editor, dsh-tool-bash, dsh-tool-pwsh.
+// This check previously asserted `write_file`, which dsh does not register — so
+// it passed while the most common write path in a new repo triggered nothing.
+check('write is watched', sync.touches('write'))
+check('edit is watched', sync.touches('edit'))
+check('so is the editor tool', sync.touches('str_replace_editor'))
+check('shells too (scripts write files here)', sync.touches('pwsh') && sync.touches('bash'))
+check('reads are not', sync.touches('read') === false)
+// The regression, named so it cannot come back quietly.
+check('the name dsh does NOT register is not relied on', sync.touches('write_file') === false)
+check('a custom list replaces the defaults', make({ writeTools: ['only_this'] }).touches('only_this') && make({ writeTools: ['only_this'] }).touches('write') === false)
+
+check('a clean repo is not rebuilt', (await sync.syncIfDirty('C:/x')) === 'clean')
+await sync.markDirty('C:/x')
+check('marking dirty writes graft\'s own flag', state.stats.dirty === true)
+check('a dirty repo rebuilds', (await sync.syncIfDirty('C:/x')) === 'started')
+check('and it spawned graft\'s sync-run', spawned.length === 1 && spawned[0][1][0] === 'C:/fake/sync-run.js')
+// Windows: sync-run's own execFileSync passes no windowsHide, so it inherits
+// whatever console this child has. `detached` would leave it with NONE, and the
+// grandchild would then be given a new VISIBLE console — a terminal that
+// flashes on every rebuild and takes foreground off a fullscreen game.
+check('hidden, so the rebuild cannot flash a console', spawned[0][2].windowsHide === true)
+check('and NOT detached, or the grandchild gets a visible one', spawned[0][2].detached !== true)
+check('it set syncing so the chip can show it', state.stats.syncing === true)
+
+check('a second rebuild inside the interval is refused', (await sync.syncIfDirty('C:/x')) === 'too-soon')
+now += 6_000
+state.stats.dirty = true
+check('and allowed once the interval passes', (await sync.syncIfDirty('C:/x')) === 'started')
+
+console.log('\n--- it never races another rebuild ---')
+state.lock = false
+state.stats.dirty = true
+now += 6_000
+check('a held lock defers instead of racing', (await sync.syncIfDirty('C:/x')) === 'locked')
+
+console.log('\n--- graft missing is not an error ---')
+const none = createAutoSync({ graft: null, now: () => now, spawn: () => { throw new Error('should not spawn') } })
+check('no graft, no rebuild, no throw', (await none.syncIfDirty('C:/x')) === 'graft-unavailable')
+
+console.log('\n--- mid-turn rebuild: a long turn must not sit on a stale graph ---')
+// The turn boundary alone left a graph dirty for 36 minutes of one agentic
+// turn while the model kept querying it. A write now also arms a debounce.
+let fired = []
+let timerId = 0
+const pendingTimers = new Map()
+const debounced = createAutoSync({
+  graft: { state, syncRun: 'C:/fake/sync-run.js' },
+  now: () => now,
+  spawn: (...a) => { fired.push(a); return { on() {}, unref() {} } },
+  debounceMs: 20000,
+  setTimeout: (fn) => { const id = ++timerId; pendingTimers.set(id, fn); return id },
+  clearTimeout: (id) => { pendingTimers.delete(id) },
+})
+state.stats = { dirty: false }
+state.lock = true
+now += 60_000
+
+await debounced.markDirty('C:/x')
+check('a write arms a timer', pendingTimers.size === 1, String(pendingTimers.size))
+check('and does not rebuild immediately', fired.length === 0)
+
+// A second write inside the window replaces the first timer, so a burst of
+// edits collapses into ONE rebuild rather than one per file.
+await debounced.markDirty('C:/x')
+check('a second write replaces the timer, not adds one', pendingTimers.size === 1, String(pendingTimers.size))
+
+const fire = [...pendingTimers.values()][0]
+pendingTimers.clear()
+await fire()
+check('the quiet period rebuilds without waiting for the turn', fired.length === 1, String(fired.length))
+
+const off = createAutoSync({ graft: { state, syncRun: 'x' }, now: () => now, spawn: () => ({ on() {}, unref() {} }), debounceMs: 0, setTimeout: () => { throw new Error('should not arm') } })
+let armed = true
+try { await off.markDirty('C:/y') } catch { armed = false }
+check('debounceMs 0 restores turn-end-only', armed === true)
+
+console.log(failures === 0 ? '\nALL CHECKS PASSED' : `\n${failures} CHECK(S) FAILED`)
+process.exit(failures === 0 ? 0 : 1)

package/scripts/test-command.mjs

@@ -0,0 +1,104 @@
+/**
+ * `/graft`, end to end against a real index.
+ *
+ * This suite BUILDS a graft index with the real CLI, because the thing it is
+ * checking is the difference between initialising and rebuilding one, and a
+ * stub cannot be wrong about that. That makes graft a hard requirement, so it
+ * skips rather than fails when graft is absent: a missing CLI is a setup state,
+ * not a defect in this plugin, and a red suite would say the wrong thing.
+ *
+ * Run:  npm test
+ */
+import { createGraftCommand, parseArgs, workspaceOf } from '../src/command.js'
+import { findGraftRoot } from '../src/index.js'
+import { access, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { delimiter, join } from 'node:path'
+import { existsSync } from 'node:fs'
+
+/** Is the graft CLI reachable? Mirrors what graft-tools.js resolves against. */
+const graftInstalled = String(process.env.PATH ?? process.env.Path ?? '')
+  .split(delimiter)
+  .some((dir) => dir !== '' && ['graft.cmd', 'graft.exe', 'graft'].some((n) => existsSync(join(dir, n))))
+
+if (!graftInstalled) {
+  console.log('SKIP  /graft end-to-end: the graft CLI is not on PATH.')
+  console.log('      Install it with:  npm install -g @nanonets/graft')
+  console.log('\nSKIPPED (not a failure)')
+  process.exit(0)
+}
+
+let failures = 0
+const check = (l, ok, extra = '') => { console.log((ok ? 'PASS  ' : 'FAIL  ') + l + (extra ? '  -> ' + extra : '')); if (!ok) failures += 1 }
+const exists = async (p) => { try { await access(p); return true } catch { return false } }
+const readJson = async (p) => { try { return JSON.parse(await readFile(p, 'utf8')) } catch { return undefined } }
+
+/**
+ * A repo built from scratch on every run.
+ *
+ * The suite asserts the difference between INITIALISING and REBUILDING, so it
+ * cannot reuse an index a previous run left behind — that is exactly the state
+ * the first two checks are supposed to prove is absent.
+ */
+const FRESH = process.argv[2] ?? join(tmpdir(), 'graft-status-fixture')
+await rm(FRESH, { recursive: true, force: true })
+await mkdir(join(FRESH, 'src'), { recursive: true })
+await writeFile(
+  join(FRESH, 'src', 'shapes.py'),
+  [
+    'def area(w, h):',
+    '    return w * h',
+    '',
+    'class Rect:',
+    '    def __init__(self, w, h):',
+    '        self.w, self.h = w, h',
+    '    def area(self):',
+    '        return area(self.w, self.h)',
+    '',
+  ].join('\n'),
+)
+await writeFile(
+  join(FRESH, 'src', 'main.py'),
+  ['from shapes import Rect', '', 'def run():', '    return Rect(3, 4).area()', ''].join('\n'),
+)
+
+const { countWiring } = await import('../src/index.js')
+const cmd = createGraftCommand({ fallbackCwd: 'C:/nowhere', findRoot: (s) => findGraftRoot(s, exists), readJson, countWiring })
+const invoke = (cwd, rawInput = '') => cmd.handler({ agent: { session: { header: { cwd } } }, rawInput, signal: undefined })
+
+console.log('--- argument parsing ---')
+check('bare builds', parseArgs('').mode === 'build')
+check('status', parseArgs(' status ').mode === 'status')
+check('deep', parseArgs('deep').mode === 'deep')
+check('a typo is refused, not silently built', parseArgs('rebiuld').mode === 'unknown')
+
+console.log('\n--- workspace resolution ---')
+check('takes the session cwd', workspaceOf({ agent: { session: { header: { cwd: 'B:/x' } } } }, 'C:/f') === 'B:/x')
+check('falls back', workspaceOf({}, 'C:/f') === 'C:/f')
+
+console.log('\n--- status BEFORE any index exists ---')
+const before = await invoke(FRESH, 'status')
+check('says there is none, and how to fix it', /No graft index/.test(before.text) && /\/graft/.test(before.text), before.text)
+
+console.log('\n--- /graft initialises a fresh repo ---')
+const built = await invoke(FRESH)
+check('reports success', built.kind === 'success', built.kind)
+check('says it INITIALISED (not rebuilt)', /initialised/.test(built.text), built.text.split('\n')[0])
+check('reports real counts', /\d+ nodes \/ \d+ edges/.test(built.text), built.text.split('\n')[1])
+check('names the language it found', /python/i.test(built.text), built.text.split('\n')[1])
+check('the index is really on disk', (await findGraftRoot(FRESH, exists)) !== undefined)
+
+console.log('\n--- a second /graft REBUILDS rather than re-initialising ---')
+const again = await invoke(FRESH)
+check('wording changes to rebuilt', /rebuilt/.test(again.text), again.text.split('\n')[0])
+
+console.log('\n--- status AFTER ---')
+const after = await invoke(FRESH, 'status')
+check('reports the graph and its freshness', /nodes \/ /.test(after.text) && /in sync|stale/.test(after.text), after.text.replace(/\n/g, ' | '))
+
+console.log('\n--- an unknown option ---')
+const bad = await invoke(FRESH, 'rebiuld')
+check('is an error naming the valid forms', bad.kind === 'error' && /\/graft status/.test(bad.text), bad.text)
+
+console.log(failures === 0 ? '\nALL CHECKS PASSED' : `\n${failures} CHECK(S) FAILED`)
+process.exit(failures === 0 ? 0 : 1)