@seanmars/tospec 0.23.0 → 0.24.0

package/assets/claude-mod/tospec-dashboard/tests/register.test.ts

@@ -0,0 +1,448 @@
+import { describe, expect, mock, test } from 'claude-code/testing'
+import type { Engine } from 'claude-code/testing'
+import type { HttpResponse, On, ProcessRunResult } from 'claude-code'
+
+// Run with `claude plugin test assets/claude-mod/tospec-dashboard`: the engine
+// itself, with the hub and the tospec CLI answered beneath the mod. Not shipped
+// into projects (init/update copy everything but this folder).
+
+const ROOT = '/work/project'
+const HUB = 'http://hub.test'
+const KEY = 'abcdef012345'
+const SNAPSHOT = { protocol: 1, root: ROOT, capturedAt: '', entries: {} }
+
+// What a hook beneath the mod answers for a `$` call: `{ value }`.
+function ok(body: unknown): { value: HttpResponse } {
+  return { value: { status: 200, ok: true, headers: {}, text: JSON.stringify(body) } }
+}
+
+function cli(payload: unknown): { value: ProcessRunResult } {
+  return {
+    value: {
+      exitCode: 0,
+      stdout: JSON.stringify({ version: '1.0', root: { path: ROOT, source: 'nearest' }, ...(payload as object) }),
+      stderr: '',
+      isStdoutTruncated: false,
+      isStderrTruncated: false,
+    },
+  }
+}
+
+/** The session the mod runs in, answered beneath it. */
+function session(on: On): void {
+  mock.env(on, { TOSPEC_DASHBOARD_URL: HUB })
+  on('session.start', (_$, e) => ({ cwd: e.cwd }))
+  on('session.end', (_$, e) => ({ sessionId: e.sessionId }))
+  on('session.root', () => ({ value: ROOT }))
+  on('session.id', () => ({ value: 'session-1' }))
+  on('command.register', (_$, e) => ({ value: { command: e.name } }))
+  on('turn.complete', (_$, e) => ({ text: e.answer }))
+  on('ui.log', () => ({ value: undefined }))
+}
+
+/** `tospec dashboard snapshot` / `query`, counted. */
+function tospecCli(on: On): { snapshots: () => number; runs: Array<{ argv: readonly string[]; stdin?: string }> } {
+  const runs: Array<{ argv: readonly string[]; stdin?: string }> = []
+  on('process.run', (_$, e) => {
+    runs.push({ argv: e.argv, stdin: e.init?.stdin })
+    if (e.argv.includes('snapshot')) return cli({ snapshot: SNAPSHOT })
+    return cli({ response: { status: 200, body: { done: true } } })
+  })
+  return { runs, snapshots: () => runs.filter((r) => r.argv.includes('snapshot')).length }
+}
+
+type Answer = { value: HttpResponse } | Promise<{ value: HttpResponse }>
+
+/**
+ * A hub that accepts every push and holds every poll, releasing a session's
+ * held poll when it leaves, as the real one does. `route` answers a path first
+ * when it returns anything.
+ */
+function fakeHub(on: On, route?: (path: string, body: Record<string, unknown>) => Answer | undefined) {
+  const hub = {
+    up: true,
+    posted: [] as Array<{ path: string; body: Record<string, unknown> }>,
+    polls: 0,
+    held: [] as Array<(answer: { value: HttpResponse }) => void>,
+    of: (path: string) => hub.posted.filter((p) => p.path === path),
+  }
+  on('http.fetch', (_$, e) => {
+    if (!hub.up) throw new Error('connect ECONNREFUSED')
+    const path = e.url.slice(HUB.length)
+    if (path === '/api/health') return ok({ protocol: 2 })
+    const body = JSON.parse(e.init?.body ?? '{}') as Record<string, unknown>
+    hub.posted.push({ path, body })
+    const routed = route?.(path, body)
+    if (routed) return routed
+    if (path === '/api/mod/snapshot') return ok({ project: KEY })
+    if (path === '/api/mod/poll') {
+      hub.polls++
+      return new Promise<{ value: HttpResponse }>((resolve) => hub.held.push(resolve))
+    }
+    if (path === '/api/mod/leave') for (const release of hub.held.splice(0)) release(ok({ commands: [] }))
+    return ok({ ok: true })
+  })
+  return hub
+}
+
+/**
+ * Reads the footer's right-side labels as the engine would draw them. Its hook
+ * stands for the engine beneath the mod, so it is registered before the
+ * test's first call on `$`.
+ */
+function footerProbe(on: On): ($: Engine) => Promise<readonly string[]> {
+  let modes: readonly string[] = []
+  on('ui.render', { component: 'SessionMode' }, (_$, e) => {
+    modes = e.props.modes
+    return { type: 'engine', ref: 0 }
+  })
+  return async ($) => {
+    await $.ui.render({ surface: 'terminal', component: 'SessionMode', requestId: 'modes', props: { modes: ['focus'] } })
+    return modes
+  }
+}
+
+async function start($: Engine): Promise<void> {
+  await $.session.start({ cwd: ROOT, surface: 'terminal', isInteractive: true })
+}
+
+/** `/tospec-dashboard <args>` as the person types it at the prompt. */
+async function slash($: Engine, args = ''): Promise<string | undefined> {
+  const answer = await $.command.run({
+    command: 'tospec-dashboard',
+    args,
+    origin: { kind: 'composer' },
+    presentation: { isFullscreen: false, columns: 80 },
+  })
+  return answer.text
+}
+
+describe('tospec-dashboard', () => {
+  test('registers with a snapshot, then relays a task write and pushes again', async ($, on) => {
+    const clock = mock.clock(on)
+    session(on)
+    const tospec = tospecCli(on)
+    const posted: Array<{ path: string; body: Record<string, unknown> }> = []
+    let replied!: (body: Record<string, unknown>) => void
+    const reply = new Promise<Record<string, unknown>>((resolve) => {
+      replied = resolve
+    })
+    let polls = 0
+
+    on('http.fetch', (_$, e) => {
+      const path = e.url.slice(HUB.length)
+      if (path === '/api/health') return ok({ protocol: 1 })
+      const body = JSON.parse(e.init?.body ?? '{}') as Record<string, unknown>
+      posted.push({ path, body })
+      if (path === '/api/mod/snapshot') return ok({ project: KEY })
+      if (path === '/api/mod/reply') {
+        replied(body)
+        return ok({ ok: true })
+      }
+      if (path === '/api/mod/poll' && polls++ === 0) {
+        return ok({
+          commands: [
+            {
+              id: 'cmd-1',
+              kind: 'query',
+              request: { method: 'POST', path: '/api/task', body: { file: 't.md', line: 1, done: true } },
+            },
+          ],
+        })
+      }
+      // Later polls are held, as the hub holds them.
+      return new Promise<{ value: HttpResponse }>(() => {})
+    })
+
+    await start($)
+    expect(await reply).toEqual({ id: 'cmd-1', status: 200, body: { done: true } })
+
+    // The snapshot ran in the project and was pushed under this session.
+    expect(tospec.runs[0]?.argv.slice(-2)).toEqual(['dashboard', 'snapshot'])
+    expect(posted[0]).toEqual({ path: '/api/mod/snapshot', body: { session: 'session-1', snapshot: SNAPSHOT } })
+    expect(posted[1]).toEqual({ path: '/api/mod/poll', body: { project: KEY, session: 'session-1' } })
+    // The relayed request reached `tospec dashboard query` on stdin.
+    expect(tospec.runs[1]?.argv.slice(-2)).toEqual(['dashboard', 'query'])
+    expect(JSON.parse(tospec.runs[1]?.stdin ?? '{}')).toMatchObject({ method: 'POST', path: '/api/task' })
+
+    // A successful write pushes a fresh snapshot once the debounce passes.
+    await clock.advance(1_500)
+    expect(tospec.snapshots()).toBe(2)
+  })
+
+  test('starts no tospec process while the hub is down, and probes again later', async ($, on) => {
+    const clock = mock.clock(on)
+    session(on)
+    const tospec = tospecCli(on)
+    let probes = 0
+    on('http.fetch', () => {
+      probes++
+      throw new Error('connect ECONNREFUSED')
+    })
+
+    await start($)
+    await clock.advance(0)
+    expect(probes).toBe(1)
+    await clock.advance(20_000)
+    expect(probes).toBe(2)
+    expect(tospec.runs).toHaveLength(0)
+  })
+
+  test('pushes after an edit under the tospec root, but not after one elsewhere', async ($, on) => {
+    const clock = mock.clock(on)
+    session(on)
+    const tospec = tospecCli(on)
+    fakeHub(on)
+    on('tool.call', () => ({ result: {} as never }))
+
+    await start($)
+    await clock.advance(0)
+    expect(tospec.snapshots()).toBe(1)
+
+    await $.tool.call({ tool: 'Edit', file_path: `${ROOT}/src/index.ts`, old_string: 'a', new_string: 'b' })
+    await clock.advance(1_500)
+    expect(tospec.snapshots()).toBe(1)
+
+    await $.tool.call({
+      tool: 'Edit',
+      file_path: `${ROOT}/tospec/changes/x/tasks.md`,
+      old_string: '- [ ]',
+      new_string: '- [x]',
+    })
+    await clock.advance(1_500)
+    expect(tospec.snapshots()).toBe(2)
+  })
+
+  test('leaves the hub when the session ends', async ($, on) => {
+    const clock = mock.clock(on)
+    session(on)
+    tospecCli(on)
+    const hub = fakeHub(on)
+
+    await start($)
+    await clock.advance(0)
+    await $.session.end({ reason: 'prompt_input_exit', sessionId: 'session-1', resume: { id: 'session-1' } })
+    expect(hub.of('/api/mod/leave').map((p) => p.body)).toEqual([{ project: KEY, session: 'session-1' }])
+  })
+
+  describe('footer', () => {
+    test('shows the hub status after the engine\'s own modes', async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      tospecCli(on)
+      fakeHub(on)
+      const footer = footerProbe(on)
+
+      await start($)
+      await clock.advance(0)
+      expect(await footer($)).toEqual(['focus', 'tospec hub: connected'])
+    })
+
+    test('says offline while no hub answers', async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      tospecCli(on)
+      const hub = fakeHub(on)
+      hub.up = false
+      const footer = footerProbe(on)
+
+      await start($)
+      await clock.advance(0)
+      expect(await footer($)).toEqual(['focus', 'tospec hub: offline'])
+    })
+  })
+
+  describe('activity', () => {
+    test('reports a turn as working, its tool as the action and a log line, and its end as idle', async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      tospecCli(on)
+      const hub = fakeHub(on)
+      on('turn.start', (_$, e) => ({ turnId: e.turnId }))
+      on('tool.call', () => ({ result: {} as never }))
+
+      await start($)
+      await clock.advance(0)
+
+      await $.turn.start({ text: 'fix it', turnId: 't1' })
+      await $.tool.call({ tool: 'Bash', command: 'pnpm test\necho done' })
+      await clock.advance(250)
+      const [working] = hub.of('/api/mod/activity').map((p) => p.body)
+      expect(working).toMatchObject({ project: KEY, session: 'session-1', status: 'working', action: null })
+      expect(working?.events).toEqual([{ kind: 'tool', tool: 'Bash', target: 'pnpm test', ok: true }])
+
+      await $.turn.complete({ answer: '', durationMs: 1, isAborted: false, turnId: 't1' } as never)
+      await clock.advance(250)
+      expect(hub.of('/api/mod/activity').at(-1)?.body).toMatchObject({ status: 'idle', action: null, events: [] })
+    })
+
+    test('names a file the tool touches relative to the project', async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      tospecCli(on)
+      const hub = fakeHub(on)
+      on('tool.call', () => ({ result: {} as never }))
+
+      await start($)
+      await clock.advance(0)
+      await $.tool.call({ tool: 'Edit', file_path: `${ROOT}/src/index.ts`, old_string: 'a', new_string: 'b' })
+      await clock.advance(250)
+      expect(hub.of('/api/mod/activity').at(-1)?.body.events).toEqual([{ kind: 'tool', tool: 'Edit', target: 'src/index.ts', ok: true }])
+    })
+  })
+
+  describe('answering from the dashboard', () => {
+    const QUESTIONS = [{ question: 'Which plan?', header: 'Plan', multiSelect: false, options: [{ label: 'A', description: '' }, { label: 'B', description: '' }] }]
+
+    /** A hub that opens asks and holds each wait until the test answers it. */
+    function askingHub(on: On, hold = true) {
+      const waits: Array<(answer: { value: HttpResponse }) => void> = []
+      const hub = fakeHub(on, (path) => {
+        if (path === '/api/mod/ask') return ok({ id: 'ask-1', hold })
+        if (path === '/api/mod/ask/wait') return new Promise<{ value: HttpResponse }>((resolve) => waits.push(resolve))
+        return undefined
+      })
+      return { hub, answer: (result: unknown) => waits.shift()?.(ok(result)) }
+    }
+
+    test('an AskUserQuestion the dashboard answers first is answered with its choice', async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      tospecCli(on)
+      on('tool.call', () => new Promise(() => {})) // the terminal dialog, never answered
+      const { hub, answer } = askingHub(on)
+
+      await start($)
+      await clock.advance(0)
+      const call = $.tool.call({ tool: 'AskUserQuestion', questions: QUESTIONS } as never)
+      await clock.advance(0)
+      expect(hub.of('/api/mod/ask').at(0)?.body).toMatchObject({ project: KEY, ask: { kind: 'question', questions: QUESTIONS } })
+      answer({ answer: { kind: 'question', answers: { 'Which plan?': 'B' } } })
+      expect(await call).toMatchObject({ result: { questions: QUESTIONS, answers: { 'Which plan?': 'B' } } })
+    })
+
+    test('an AskUserQuestion answered in the terminal first is withdrawn from the dashboard', async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      tospecCli(on)
+      on('tool.call', () => ({ result: { questions: QUESTIONS, answers: { 'Which plan?': 'A' } } as never }))
+      const { hub } = askingHub(on)
+
+      await start($)
+      await clock.advance(0)
+      const result = await $.tool.call({ tool: 'AskUserQuestion', questions: QUESTIONS } as never)
+      expect(result).toMatchObject({ result: { answers: { 'Which plan?': 'A' } } })
+      await clock.advance(0)
+      expect(hub.of('/api/mod/ask/close').map((p) => p.body)).toEqual([{ id: 'ask-1' }])
+    })
+
+    test('a permission the dashboard allows is allowed', async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      tospecCli(on)
+      on('classic.PermissionRequest', () => ({}))
+      on('ui.status', () => ({ value: undefined }))
+      const { hub, answer } = askingHub(on)
+
+      await start($)
+      await clock.advance(0)
+      const decided = $.classic.PermissionRequest({ tool_name: 'Bash', tool_input: { command: 'rm -rf build' } } as never)
+      await clock.advance(0)
+      expect(hub.of('/api/mod/ask').at(0)?.body).toMatchObject({ ask: { kind: 'permission', tool: 'Bash', target: 'rm -rf build' } })
+      answer({ pending: true })
+      await clock.advance(0)
+      answer({ answer: { kind: 'permission', allow: true } })
+      expect(await decided).toMatchObject({ decision: { behavior: 'allow' } })
+    })
+
+    test('a read-only dashboard leaves the permission to the terminal at once', async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      tospecCli(on)
+      on('classic.PermissionRequest', () => ({}))
+      askingHub(on, false)
+
+      await start($)
+      await clock.advance(0)
+      const decided = await $.classic.PermissionRequest({ tool_name: 'Bash', tool_input: { command: 'ls' } } as never)
+      expect(decided.decision).toBeUndefined()
+    })
+
+    // The terminal's dialog is open alongside the dashboard's: once the person
+    // answers there and the call goes on, the dashboard must not offer a second answer.
+    test("withdraws the dashboard's permission once the terminal settled the call", async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      tospecCli(on)
+      on('classic.PermissionRequest', () => ({}))
+      on('tool.call', () => ({ result: {} as never }))
+      const { hub } = askingHub(on)
+
+      await start($)
+      await clock.advance(0)
+      void $.classic.PermissionRequest({ tool_name: 'Bash', tool_input: { command: 'rm -rf build' } } as never)
+      await clock.advance(0)
+      expect(hub.of('/api/mod/ask/close')).toEqual([])
+
+      await $.tool.call({ tool: 'Bash', command: 'rm -rf build' })
+      await clock.advance(0)
+      expect(hub.of('/api/mod/ask/close').map((p) => p.body)).toEqual([{ id: 'ask-1' }])
+    })
+  })
+
+  describe('/tospec-dashboard', () => {
+    test('unregister leaves the hub and stops pushing; register comes back', async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      const tospec = tospecCli(on)
+      const hub = fakeHub(on)
+      const footer = footerProbe(on)
+
+      await start($)
+      await clock.advance(0)
+      expect(hub.polls).toBe(1)
+
+      expect(await slash($, 'unregister')).toContain('Unregistered from the tospec dashboard')
+      expect(hub.of('/api/mod/leave').at(0)?.body).toEqual({ project: KEY, session: 'session-1' })
+      expect(await footer($)).toEqual(['focus', 'tospec hub: unregistered'])
+
+      // Unregistered: a finished turn pushes nothing and nothing polls.
+      await $.turn.complete({ answer: '', durationMs: 1, isAborted: false, turnId: 't1' } as never)
+      await clock.advance(30_000)
+      expect(tospec.snapshots()).toBe(1)
+      expect(hub.polls).toBe(1)
+
+      expect(await slash($, 'register')).toBe(`Registered with the tospec dashboard at ${HUB} (project ${KEY}).`)
+      expect(tospec.snapshots()).toBe(2)
+      await clock.advance(0)
+      expect(hub.polls).toBe(2)
+      expect(await footer($)).toEqual(['focus', 'tospec hub: connected'])
+    })
+
+    test('register says so when no hub answers', async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      tospecCli(on)
+      const hub = fakeHub(on)
+      hub.up = false
+
+      await start($)
+      await clock.advance(0)
+      const answer = await slash($, 'register')
+      expect(answer).toContain(`No tospec dashboard answered at ${HUB}`)
+      expect(answer).toContain('tospec dashboard start')
+    })
+
+    test('with no argument reports the status, and rejects an unknown one', async ($, on) => {
+      const clock = mock.clock(on)
+      session(on)
+      tospecCli(on)
+      fakeHub(on)
+
+      await start($)
+      await clock.advance(0)
+      expect(await slash($)).toBe(`Registered with the tospec dashboard at ${HUB} (project ${KEY}).`)
+      expect(await slash($, 'nope')).toContain('Usage:')
+    })
+  })
+})

package/assets/claude-mod/tospec-dashboard/types/index.d.ts

@@ -0,0 +1,8 @@
+/** Where this session stands with the dashboard hub, as the footer shows it. */
+export type HubStatus = 'connecting' | 'connected' | 'hub-offline' | 'unregistered' | 'error'
+
+declare module 'claude-code' {
+  interface PluginState {
+    'tospec-dashboard': { status: HubStatus }
+  }
+}