cockpit-shared

1import type { EngineInterface, Register } from 'claude-code'
2
3import { DEFAULT_TIMEOUT_MS, guard } from './run'
4
5// cockpit-shared is never installed. It exists so `claude plugin test mods/_shared` runs
6// the *.test.ts beside it (the engine skips a folder with no hooks module: exit 0, no tests
7// run — t-3446) and so the canonical adapter line below is exercised through the real
8// engine. The files here are the source of truth, vendored into mods/<mod>/hooks/_shared/.
9//
10// The adapter line, byte-for-byte what every mod carries at its top level (run.ts explains
11// why it cannot live in a shared file; Check 77a allows `$.process.run(` nowhere else):
12const run = ($: EngineInterface, argv: readonly string[]) => guard(argv, () => $.process.run(argv, { timeoutMs: DEFAULT_TIMEOUT_MS }))
13
14const COMMAND = 'cockpit-shared-run'
15
16export const register: Register = on => {
17  on('session.start', async ($, e, next) => {
18    // Dev aid when loaded with --plugin-dir mods/_shared: `/cockpit-shared-run brana backlog get t-1`
19    // prints the guard's verdict and result as JSON. In tests it is the handle that drives run().
20    await $.command.register({ name: COMMAND, description: 'cockpit-shared dev aid: run an argv through the allowlist guard; prints the RunResult as JSON' })
21    return next(e)
22  })
23
24  on('command.run', { command: COMMAND }, async ($, e) => {
25    const argv = (e.args ?? '').split(/\s+/).filter(Boolean)
26    return { text: JSON.stringify(await run($, argv)) }
27  })
28}
29

1import type { ProcessRunResult } from 'claude-code'
2
3import { check } from './allowlist'
4
5// The one gate every host command passes through (ADR-096 Law 3).
6//
7// Why guard(argv, exec) and not run($, argv): the engine's scanner refuses a hooks module
8// that passes `$` to a function it did not declare at its own top level ("$ is passed to
9// "run", which is not a function declared at the top of this file"), so a shared
10// $-taking run() is impossible by construction. Instead every mod's hooks module carries
11// exactly this one adapter line at its top level — validate Check 77a allows
12// `$.process.run(` nowhere else in mods/**:
13//
14//   const run = ($: EngineInterface, argv: readonly string[]) => guard(argv, () => $.process.run(argv, { timeoutMs: DEFAULT_TIMEOUT_MS }))
15//
16// `plugin validate` then reports the call as `$.process.run (via run)`, which Check 77b
17// parses against the allowed set.
18export type RunResult =
19  | { denied: true; reason: string }
20  | { denied: false; failed: boolean; exitCode: number; stdout: string; stderr: string }
21
22export const DEFAULT_TIMEOUT_MS = 15000
23
24export async function guard(argv: readonly string[], exec: () => Promise<ProcessRunResult>): Promise<RunResult> {
25  const verdict = check(argv)
26  if (!verdict.allowed) return { denied: true, reason: verdict.reason }
27  try {
28    const r = await exec()
29    return { denied: false, failed: false, exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr }
30  } catch (err) {
31    // Cannot start (brana not on PATH), timed out, or the host refused: a result, never a
32    // throw — a hook that throws is skipped and the band draws nothing.
33    return { denied: false, failed: true, exitCode: -1, stdout: '', stderr: String(err instanceof Error ? err.message : err) }
34  }
35}
36

1// The only place verbs are named (ADR-096 Law 3; cockpit.md §_shared/allowlist.ts).
2// Prefix match on argv: every token of a listed prefix must equal the argv token at the
3// same position; extra args are allowed only after a listed prefix. No shell is ever
4// involved ($.process.run takes argv), so a metacharacter inside one token is just text.
5//
6// READ changes only by spec: the valves verb joins in t-3021's landing commit, nowhere
7// else. allowlist.test.ts asserts both lists by exact equality.
8export const READ: readonly (readonly string[])[] = [
9  ['brana', 'cockpit', 'snapshot', '--json'],
10  ['brana', 'backlog', 'get'],
11  ['brana', 'backlog', 'query'],
12  ['brana', 'backlog', 'next'],
13  ['brana', 'backlog', 'search'],
14  ['brana', 'backlog', 'blocked'],
15]
16
17// Automatic-and-logged; the only write without a confirm button (cockpit.md).
18export const WRITE: readonly (readonly string[])[] = [['brana', 'cockpit', 'log-event']]
19
20export type Verdict = { allowed: true; kind: 'read' | 'write' } | { allowed: false; reason: string }
21
22const startsWith = (argv: readonly string[], prefix: readonly string[]): boolean =>
23  argv.length >= prefix.length && prefix.every((tok, i) => argv[i] === tok)
24
25export function check(argv: readonly string[]): Verdict {
26  if (READ.some(p => startsWith(argv, p))) return { allowed: true, kind: 'read' }
27  if (WRITE.some(p => startsWith(argv, p))) return { allowed: true, kind: 'write' }
28  return { allowed: false, reason: `argv not on the READ or WRITE allowlist: ${argv.join(' ')}` }
29}
30