dsh-graft-plugin 0.2.1 → 0.3.1

package/scripts/test-guidance.mjs

@@ -0,0 +1,160 @@
+/**
+ * The standing instruction must reach the model on CURRENT dsh.
+ *
+ * dsh `0.1.7-rc.2` removed the `agent/session-start` event the guidance used to
+ * ride: the listener stayed registered and the suite stayed green, while no
+ * agent ever fired it, so `graft-status:usage` silently vanished from every
+ * prompt. This suite runs `apply()` against a REAL Cordis context and drives
+ * the event dsh actually emits now (`agent/created`, the same seam dsh's own
+ * file-reference plugin uses), so an upstream rename fails here instead of
+ * disappearing into a prompt nobody diffs.
+ *
+ * Cordis resolves injects asynchronously, so every check after a trigger
+ * waits a tick first — the assertions test what a live session would see,
+ * not what a synchronous read-back would flatter.
+ *
+ * Run:  node scripts/test-guidance.mjs      (part of `npm test`)
+ */
+import { readFile } from 'node:fs/promises'
+import { Context, Service } from '@deepseek-ai/cordis'
+
+import { apply } from '../src/index.js'
+
+let failures = 0
+const check = (label, ok, extra = '') => {
+  console.log((ok ? 'PASS  ' : 'FAIL  ') + label + (extra ? '  -> ' + extra : ''))
+  if (!ok) failures += 1
+}
+/** Let pending Cordis inject fibers and disposals settle. */
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0))
+
+/** The whole prompt section this plugin registers, as the tests see it. */
+const SECTION_NAME = 'graft-status:usage'
+const GUIDANCE_ORDER = 950
+
+/**
+ * A prompt-registry stand-in that behaves like the real `systemPrompt`
+ * service where it matters. It is a Cordis Service, so the traceable-context
+ * overlay applies, and `section()` creates its undo effect on the CALLER's
+ * context — the same ownership `SystemPrompt.section()` gets through
+ * `ScopedLayers`, and the reason an agent's section can die with the agent.
+ */
+function fakePromptRegistry(sections, removed) {
+  return class FakePromptRegistry extends Service {
+    constructor(ctx) {
+      super(ctx, 'systemPrompt')
+    }
+
+    section(section) {
+      sections.push(section)
+      return this.ctx.effect(() => () => {
+        removed.push(section.name)
+      }, `fake.section(${section.name})`)
+    }
+  }
+}
+
+/** Mount the stand-in on a context as the `systemPrompt` service. */
+function providePromptRegistry(ctx, sections, removed) {
+  ctx.plugin(fakePromptRegistry(sections, removed))
+}
+
+console.log('--- apply() against a real Cordis context ---')
+const root = new Context()
+const registeredTools = []
+const sections = []
+const removed = []
+root.plugin(fakePromptRegistry(sections, removed))
+root.reflect.provide('tools', {
+  register(tool) {
+    registeredTools.push(tool)
+    return () => {}
+  },
+})
+
+let threw
+try {
+  await apply(root, {})
+} catch (error) {
+  threw = error
+}
+check('apply() mounts without throwing', threw === undefined, threw ? String(threw) : '')
+check('the five graft tools register', registeredTools.length === 5, registeredTools.map((t) => t.name).join(', '))
+
+console.log('\n--- the guidance rides agent/created, not the removed agent/session-start ---')
+check(
+  'the source never names the removed event',
+  !(await readFile(new URL('../src/index.js', import.meta.url), 'utf8')).includes('agent/session-start'),
+)
+check('no guidance before any agent exists', sections.length === 0, JSON.stringify(sections))
+
+console.log('\n--- an agent with the prompt registry gets the section ---')
+const agent = { ctx: new Context() }
+providePromptRegistry(agent.ctx, sections, removed)
+root.emit('agent/created', { agent })
+await settle()
+check('the section registered on the agent scope', sections.length === 1, JSON.stringify(sections[0]?.name))
+check('under its own name', sections[0]?.name === SECTION_NAME, sections[0]?.name)
+check('at the documented order', sections[0]?.order === GUIDANCE_ORDER, String(sections[0]?.order))
+check('with the graft guidance text', /graft_ask/.test(sections[0]?.text ?? ''), (sections[0]?.text ?? '').split('\n')[0])
+
+console.log('\n--- a second announce does not duplicate it ---')
+root.emit('agent/created', { agent })
+await settle()
+check('the section registered exactly once', sections.length === 1, String(sections.length))
+
+console.log('\n--- agent disposal takes the section down ---')
+root.emit('agent/disposed', { agent })
+await settle()
+check('the section was disposed with the agent', removed.length === 1, JSON.stringify(removed))
+
+console.log('\n--- an agent WITHOUT the prompt registry only loses the sentence ---')
+const bare = { ctx: new Context() }
+let bareThrew
+try {
+  root.emit('agent/created', { agent: bare })
+  await settle()
+} catch (error) {
+  bareThrew = error
+}
+check('a registry-less agent is survived, not crashed', bareThrew === undefined, bareThrew ? String(bareThrew) : '')
+check('and it adds no section', sections.length === 1, String(sections.length))
+
+console.log('\n--- agents that already exist when the row mounts are briefed too ---')
+const lateRoot = new Context()
+lateRoot.reflect.provide('tools', { register: () => () => {} })
+providePromptRegistry(lateRoot, sections, removed)
+lateRoot.reflect.provide('agents', { list: () => [agent, bare] })
+const before = sections.length
+let lateThrew
+try {
+  await apply(lateRoot, {})
+  await settle()
+} catch (error) {
+  lateThrew = error
+}
+check('apply() with an agents service does not throw', lateThrew === undefined, lateThrew ? String(lateThrew) : '')
+check('pre-existing agents got the section at mount', sections.length === before + 1, `${sections.length - before} added`)
+check('and the registry-less one stayed silent', sections.every((s) => s.name === SECTION_NAME))
+
+console.log('\n--- promptSection: false registers nothing ---')
+const quietRoot = new Context()
+quietRoot.reflect.provide('tools', { register: () => () => {} })
+providePromptRegistry(quietRoot, sections, removed)
+quietRoot.reflect.provide('agents', { list: () => [agent] })
+await apply(quietRoot, { promptSection: false })
+quietRoot.emit('agent/created', { agent })
+await settle()
+check('no guidance section from a suppressed row', sections.length === before + 1, `${sections.length - before - 1} added`)
+
+console.log('\n--- teardown ---')
+for (const ctx of [root, agent.ctx, lateRoot, quietRoot]) {
+  try {
+    await ctx.fiber?.dispose?.()
+  } catch {
+    // A test context holds only fake services; nothing here may block exit.
+  }
+}
+
+console.log(failures === 0 ? '\nALL CHECKS PASSED' : `\n${failures} CHECK(S) FAILED`)
+process.exit(failures === 0 ? 0 : 1)

package/scripts/test-harness.mjs

@@ -14,7 +14,8 @@
 import { access, mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import { computeStatus, countWiring, findGraftRoot, freshnessOf } from '../src/index.js'
+import { computeStatus, countWiring, createToolPulse, findGraftRoot, freshnessOf } from '../src/index.js'
+import { graftTools } from '../src/graft-tools.js'
 
 let failures = 0
 const check = (label, ok, extra = '') => {
@@ -113,6 +114,44 @@ check('and a space in the path does not break it', OTHER.includes(' '))
 const nowhere = await findGraftRoot(BARE, exists)
 check('an unindexed tree resolves to nothing', nowhere === undefined, String(nowhere))
 
+console.log('\n--- git worktrees are their own graft root ---')
+// A linked worktree's .git is a FILE pointing at its admin dir, whose
+// commondir names the shared .git. The one that matters is NESTED inside the
+// main checkout: without the boundary, resolution walked straight past it and
+// the tools answered from the main checkout's graph — wrong paths for this
+// branch's files.
+await mkdir(join(REPO, '.git'), { recursive: true })
+const wt = join(REPO, 'wt')
+const gitDir = join(fixture, 'main.git', 'worktrees', 'wt')
+await mkdir(join(wt, 'src'), { recursive: true })
+await mkdir(gitDir, { recursive: true })
+await writeFile(join(wt, '.git'), `gitdir: ${gitDir}\n`, 'utf8')
+await writeFile(join(gitDir, 'commondir'), '../..\n', 'utf8')
+
+const fromWt = await findGraftRoot(join(wt, 'src'), exists)
+check('a nested worktree never answers from the main graph above it', fromWt === undefined, String(fromWt))
+
+const mainAgain = await findGraftRoot(REPO, exists)
+check('the main checkout itself still resolves', samePath(mainAgain, REPO), String(mainAgain))
+
+const mainStatus = await computeStatus(REPO, io)
+check('a main checkout is not reported as a worktree', mainStatus.worktreeOf === undefined, String(mainStatus.worktreeOf))
+
+// Once the worktree has its own index (graft seeds it from main on build),
+// resolution stays inside the worktree and the status names its repo.
+await mkdir(join(wt, 'graft', '.cache'), { recursive: true })
+await writeFile(join(wt, 'graft', 'INDEX.md'), '# graft repo map\n')
+await writeFile(
+  join(wt, 'graft', '.cache', 'stats.json'),
+  JSON.stringify({ nodeCount: 12, edgeCount: 7, dirty: false, staleCount: 0, syncedAt: '2026-09-11T09:00:00.000Z' }),
+)
+const wtIndexed = await findGraftRoot(join(wt, 'src'), exists)
+check('a worktree with its own index resolves to itself', samePath(wtIndexed, wt), String(wtIndexed))
+
+const wtStatus = await computeStatus(wt, io)
+check('status names the main checkout the worktree belongs to', samePath(wtStatus.worktreeOf, fixture), String(wtStatus.worktreeOf))
+check('and still serves the worktree graph', wtStatus.nodeCount === 12, String(wtStatus.nodeCount))
+
 console.log('\n--- status from the cache ---')
 const status = await computeStatus(REPO, io)
 check('reports the cache node count', status.nodeCount === 1284, String(status.nodeCount))
@@ -199,6 +238,53 @@ const cannotSpawn = await startViz('C:/x', 4400, {
 })
 check('an unspawnable graft is a reason, not a throw', cannotSpawn.ok === false && /not on PATH/.test(cannotSpawn.reason))
 
+/* ========================================================================== *
+ * Tool-use pulses: any graft_* call must reach the chip's dot
+ * ========================================================================== */
+
+console.log('\n--- tool use is recorded against its repo ---')
+const pulse = createToolPulse()
+check('an unused repo has no pulse', pulse.get(REPO) === undefined)
+pulse.note(REPO)
+const first = pulse.get(REPO)
+pulse.note(REPO)
+const second = pulse.get(REPO)
+check('repeated uses count up per root', first.count === 1 && second.count === 2, JSON.stringify(first) + ' vs ' + JSON.stringify(second))
+check('the pulse carries when it last happened', typeof first.at === 'number' && second.at >= first.at)
+check('another repo pulses independently', pulse.get(OTHER) === undefined)
+pulse.note('')
+check('an empty root is ignored', pulse.get('') === undefined)
+
+console.log('\n--- every graft tool announces its own use ---')
+const pulsed = []
+const spawnedArgv = []
+const fakeSpawn = (command, argv) => {
+  spawnedArgv.push([command, argv])
+  return {
+    stdout: { on() {} },
+    stderr: { on() {} },
+    on(event, fn) { if (event === 'close') fn() },
+    kill() {},
+  }
+}
+const pulseTools = graftTools({
+  fallbackCwd: BARE,
+  // BARE has no index: the no-graph branch. Everything else resolves to REPO.
+  findRoot: async (start) => (start === BARE ? undefined : REPO),
+  noteUse: (root) => pulsed.push(root),
+  command: { command: 'graft-fake', prefix: [], shell: false },
+  spawn: fakeSpawn,
+})
+const ask = pulseTools.find((t) => t.name === 'graft_ask')
+const answered = await ask.execute({ query: 'anything' }, { agent: { session: { header: { cwd: OTHER } } } })
+check('the call still answers', typeof answered.text === 'string' && answered.text !== '', answered.text.slice(0, 60))
+check('rooted at the session repo, not the process cwd', samePath(spawnedArgv[0]?.[1]?.at(-1), REPO), String(spawnedArgv[0]?.[1]?.at(-1)))
+check('one call, one pulse, for the right root', pulsed.length === 1 && samePath(pulsed[0], REPO), JSON.stringify(pulsed))
+
+const noGraph = await ask.execute({ query: 'anything' }, { agent: { session: { header: { cwd: BARE } } } })
+check('a workspace with no graph explains itself', /No graft index/.test(noGraph.text))
+check('and does not pulse — there is no green dot to light', pulsed.length === 1, JSON.stringify(pulsed))
+
 /* ========================================================================== *
  * The new-tab handle (a source-level guard)
  * ========================================================================== */
@@ -255,6 +341,102 @@ check('the type and its body register under the same id', clientSource.includes(
 check('that dependency is soft too', clientSource.includes('ctx.inject(["sidebarRightTabs", "slots"]') && !/const inject = [[]/.test('') && clientSource.indexOf('const inject = ["slots", "remote"]') !== -1)
 check('the body reads the session from either host', clientSource.includes('props?.sessionId ?? props?.scope?.sessionId'))
 check('the browser tab survives only as the last resort', clientSource.includes('neither sidebar'))
+// The viz panel bar shows which checkout a worktree graph belongs to.
+check('the viz panel names the worktree when the graph serves one', clientSource.includes('"worktree of " + wt') && clientSource.includes('status.worktreeOf'))
+
+console.log('\n--- the dot flickers blue while a graft tool runs ---')
+// The pulse rides the status poll, so it must bypass the five-second status
+// cache: a blink that waited out `cacheMs` would land after the call ended.
+const indexSource = await readFile(new URL('../src/index.js', import.meta.url), 'utf8')
+check('the status payload carries the pulse', /toolUse: pulses\.get\(root\)/.test(indexSource))
+check('on the cache-hit path too', (indexSource.match(/toolUse: pulses\.get\(root\)/g) ?? []).length === 2)
+check('the flicker style exists and sits on the dot', clientSource.includes('.gs-chip.gs-live .gs-dot{color:#8b5cf6}'))
+check('the client counts incoming pulses', clientSource.includes('toolUse?.count'))
+check('a fresh pulse blinks, on and off, not solid', /for \(const ms of \[0, 175, 350, 525, 700, 875, 1050, 1225, 1400, 1575, 1750, 1925\]\)/.test(clientSource))
+// Toggles alternate on/off, so an ODD number of marks ends ON — which shipped
+// once as a dot stuck purple after every blink. An even count ends off.
+const marks = clientSource.match(/for \(const ms of \[((?:\d+)(?:, \d+)*)\]\)/)?.[1]?.split(', ').map(Number) ?? []
+check('the blink ends off, back at the resting colour', marks.length > 0 && marks.length % 2 === 0, JSON.stringify(marks))
+check('polling speeds up while graft tools are active', clientSource.includes('settled && !recent ? 4000 : 2000'))
+check('a pulse keeps the fast poll for a tail, not just the blink', clientSource.includes('window.setTimeout(() => setRecent(false), 20000)'))
+check('the flicker timers are cleaned up on unmount', clientSource.includes('for (const t of flickTimers.current) window.clearTimeout(t)'))
+
+console.log('\n--- the chip label truncates, the popup builds ---')
+// A long workspace name must collapse to an ellipsis in the trailing-row
+// chip, not stretch the composer. The popup keeps the full path.
+check(
+  'the chip label carries its own ellipsis rule',
+  clientSource.includes('.gs-chip .gs-label{overflow:hidden;text-overflow:ellipsis'),
+)
+check('and the chip renders the label under that class', clientSource.includes('h("span", { className: "gs-label" }'))
+// The popup's Build button calls a `build` remote method — the same plain
+// offline `graft build` the bare /graft runs — with a busy state while it
+// is in flight, then a status re-read so the card shows the fresh graph.
+check('the client declares a build descriptor', clientSource.includes('descriptor("build", ["sessionId"])'))
+check('the host serves a build method', indexSource.includes('markRemoteMethod(GraftStatusRemote.prototype, \'build\')'))
+// The button rebuilds through the SAME sync-run.js the automatic hooks run —
+// never a bare `graft build`, which writes the graph but NOT stats.json, so
+// the pill kept reading the old `dirty` flag and never flipped to IN SYNC.
+// That shipped once as a press that changed nothing.
+check('the build goes through the shared rebuild engine', /build[\s\S]{0,600}autoSync\.rebuild\(root\)/.test(indexSource))
+check('a finished build drops the stale cache', /build[\s\S]*?cache\.delete\(root\)/.test(indexSource))
+check('the popup has a Build button', clientSource.includes('"Build"'))
+check('it disables while the build runs', clientSource.includes('disabled: building'))
+// The rebuild button sits IN the header row, right of the status pill — not
+// in a footer row of its own.
+check('no footer row survives the move', !clientSource.includes('gs-pop-buildrow'))
+check(
+  'one header group, rendered in both heads',
+  (clientSource.match(/headGroup\(h\(/g) ?? []).length === 2,
+  String((clientSource.match(/headGroup\(h\(/g) ?? []).length),
+)
+// Pill and Build travel as one group pinned right: a wrapper carries the
+// row's only auto margin, so the flex gap is the only thing between the
+// pair and nothing can split them — either apart or across the header.
+check('the header pills travel in one right-pinned group', clientSource.includes('.gs-pop-group{margin-left:auto'))
+check('the pill no longer spaces itself away from the button', !clientSource.includes('.gs-pill{margin-left:auto'))
+// The card itself is click-through (pointer-events:none), which was fine
+// while it was pure text — but any button inside it is dead unless it
+// re-enables events on itself. That shipped once as a button that could
+// never be pressed; this guard is the reason it will not ship again.
+check('the Build button re-enables pointer events on itself', clientSource.includes('.gs-build{') && /\.gs-build\{[^}]*pointer-events:auto/.test(clientSource))
+// The button holds Building… until OBSERVED freshness flips to synced, not
+// until the build promise lands: a build that exits while stats.json still
+// reads dirty (plain `graft build` never patches it) must not re-enable the
+// button against a pill that still says STALE. That shipped once as a press
+// that changed nothing; this guard is the reason it will not ship again.
+check('the button waits for observed sync, not the promise', clientSource.includes('waitForSynced'))
+check('with a bounded wait, not forever', clientSource.includes('SYNC_WAIT_MS'))
+check('the seat hands the waiter to the card', clientSource.includes('onSynced: waitForSynced'))
+check('a build that never reports sync re-enables with an error', clientSource.includes('did not report in sync'))
+
+console.log('\n--- Build in a workspace with no index confirms first ---')
+// The prompt is dsh's own themed Modal, not the browser's ugly box: the card
+// requires the primitives package permission-presets already proves a client
+// bundle can require. Guarded — if the package is ever absent the prompt
+// falls back to window.confirm, so the gate can never go missing silently.
+check('the card prefers dsh\'s own Modal', clientSource.includes('Primitives.Modal') && clientSource.includes('dsh-client-ui-primitives'))
+check('the Modal carries the confirm copy', clientSource.includes('Build graft index?'))
+check('its footer holds both accept and decline', clientSource.includes('Build index') && clientSource.includes('"Cancel"'))
+// Guarded require: if primitives is ever unresolvable the gate falls back to
+// the ugly box rather than going missing silently. The fallback is the ONLY
+// window.confirm in the file.
+check('only the fallback uses the browser box', (clientSource.match(/window\.confirm\(/g) ?? []).length === 1)
+// The modal accept must START the build while the modal is still open: it may
+// only close the modal after the build promise is underway. Closing first
+// (unmounting the card's modal subtree in the same tick) shipped once as an
+// accept that dismissed the dialog and built nothing.
+check('the accept starts the build while the modal is open', /startBuild[\s\S]{0,300}setConfirming\(false\)/.test(clientSource))
+check('the modal never closes before the build promise exists', !/setConfirming\(false\)[\s\S]{0,60}Promise\.resolve\(runBuild/.test(clientSource))
+// The confirm modal portals to document.body — OUTSIDE the card's wrap — so
+// the seat's capture-phase click-away closer would unmount the card (modal
+// included) before the accept's own click dispatches. That shipped once as an
+// accept that hid the dialog and built nothing; the closer must let modal
+// clicks through.
+check('the click-away closer lets modal clicks through', /closest\(['"]\[role="dialog"\]/.test(clientSource))
+check('the accept runs the plain offline initialise', /runGraft\(\['build', from\], from/.test(indexSource))
+check('a failed initialise reports graft\'s own message', /produced no index/.test(indexSource))
+check('a fresh initialise resolves as initialising', /initialising: true/.test(indexSource))
 
 // The remote descriptors must survive dsh 0.2's typert codec validation, which
 // runs inside `ctx.remote.$mount`: a strict codec needs a typeSymbol and a
@@ -280,7 +462,7 @@ function codecProblem(codec, { parameter }) {
   if (typeof codec.schema?.parse !== 'function') return 'no 0.1 schema fallback'
   return undefined
 }
-check('declares the status and viz descriptors', CONTRIBUTION.descriptors.map((d) => d.method).join() === 'status,viz')
+check('declares the status, viz and build descriptors', CONTRIBUTION.descriptors.map((d) => d.method).join() === 'status,viz,build')
 for (const d of CONTRIBUTION.descriptors) {
   for (const p of d.parameters) {
     const problem = codecProblem(p.codec, { parameter: true })

package/src/auto-sync.js

@@ -71,6 +71,10 @@ const DEFAULT_WRITE_TOOLS = ['write', 'edit', 'str_replace_editor', 'pwsh', 'bas
 
 /** Graft's own state helpers, loaded from wherever graft is installed. */
 async function loadGraftState(cliPath) {
+  // A cli we cannot locate (bare shim on PATH) must degrade to "unavailable",
+  // never throw: this runs inside fire-and-forget middleware and a rejection
+  // here is fatal to dsh.
+  if (typeof cliPath !== 'string' || cliPath === '') return undefined
   const claudeDir = join(dirname(cliPath), 'claude')
   const statePath = join(claudeDir, 'state.js')
   const syncRun = join(claudeDir, 'sync-run.js')
@@ -132,7 +136,11 @@ export function createAutoSync(deps = {}) {
   let loaded
   const graft = async () => {
     if (loaded === undefined) {
-      loaded = deps.graft !== undefined ? deps.graft : await loadGraftState(deps.cliPath)
+      try {
+        loaded = deps.graft !== undefined ? await deps.graft : await loadGraftState(deps.cliPath)
+      } catch {
+        loaded = null // any loader failure counts as "graft unavailable"
+      }
       if (loaded === undefined) loaded = null
     }
     return loaded
@@ -161,7 +169,7 @@ export function createAutoSync(deps = {}) {
           root,
           setTimer(() => {
             timers.delete(root)
-            void api.syncIfDirty(root)
+            void api.syncIfDirty(root).catch(() => {})
           }, debounceMs),
         )
       }
@@ -201,6 +209,30 @@ export function createAutoSync(deps = {}) {
       }
       if (stats?.dirty !== true && !pending.has(root)) return 'clean'
 
+      return api.rebuild(root)
+    },
+
+    /**
+     * Rebuild one repo NOW, whether or not it looks dirty.
+     *
+     * The popup's Build button lands here, not in syncIfDirty: its gate reads
+     * graft's `dirty` flag, and a repo rebuilt by a plain `graft build` — which
+     * never patches stats.json — can read clean while being stale, answering
+     * 'clean' and spawning nothing. A pressed button that changes nothing is
+     * the failure this exists to prevent. The lock and the interval floor
+     * still apply: forced means "skip the dirt check", not "race a running
+     * build".
+     *
+     * @returns why it did or did not run, for the harness and the log.
+     */
+    rebuild: async (root) => {
+      if (typeof root !== 'string' || root === '') return 'no-root'
+      const g = await graft()
+      if (g === null) return 'graft-unavailable'
+
+      const since = now() - (lastRun.get(root) ?? -Infinity)
+      if (since < minIntervalMs) return 'too-soon'
+
       // The lock is graft's, so a rebuild already running — started here, or by
       // Claude Code in the same repo — is left alone rather than raced.
       try {