@dsh-cc/plugin-cc-grok-bridge 0.8.1

package/scripts/lib/argv.mjs

@@ -0,0 +1,380 @@
+/**
+ * §3.2-d pinned argv grammar for the cc-grok-bridge (one shared parser
+ * source for matcher and launcher; the exported FIXTURES table is the
+ * single fixture suite the hook tests reuse).
+ *
+ *   invocation := NODE LAUNCHER [--last] prompt
+ *   prompt     := '--prompt-file' PATH | '--' SINGLE_LINE_NONEMPTY_PROMPT
+ *
+ * Rules:
+ *   - NODE and LAUNCHER are expansion-free literal tokens byte-equal to the
+ *     registration-time canonical paths (a symlink literal, a tilde/glob/$VAR
+ *     expansion, or a PATH-resolved name never byte-equals a canonical
+ *     absolute literal — indirection dies here).
+ *   - `--last` appears at most once, only in the slot shown.
+ *   - the positional prompt is a single literal token, never empty, contains
+ *     no `\n` or `\r`, and its FIRST CHARACTER MUST NOT BE `-`: the prompt
+ *     rides the child argv as the `-p` value, so a dash-leading word would be
+ *     re-parsed as a flag by the Grok CLI (probed: clap misparse, exit 2) —
+ *     dash-leading prompts must use the `--prompt-file` form instead.
+ *   - PATH for --prompt-file is non-empty; containment is checked at match
+ *     time by the hook, not here.
+ *   - unknown shapes fail closed with a machine-readable `reason`.
+ */
+import { lexCommand } from './lexer.mjs'
+
+/** Example canonical anchor pair used by the shared fixture table. */
+export const CANONICAL_NODE = '/usr/local/bin/node'
+export const CANONICAL_LAUNCHER = '/opt/dsh-cc/cc-grok-bridge/scripts/grok-review-run.mjs'
+
+const fail = (reason) => ({ ok: false, layer: 'argv', reason })
+const ok = (value) => ({ ok: true, layer: 'argv', value })
+
+/**
+ * Parse a lexer-resolved argv (words with { text, expansion }) against the
+ * pinned grammar. `node`/`launcher` are the byte-pinned canonical anchors.
+ */
+export function parseArgv(argv, { node, launcher }) {
+  if (argv.length < 2) return fail('missing-anchor')
+  if (argv[0].expansion) return fail('expansion-in-argv0')
+  if (argv[1].expansion) return fail('expansion-in-argv1')
+  if (argv[0].text !== node) return fail('argv0-byte-mismatch')
+  if (argv[1].text !== launcher) return fail('argv1-byte-mismatch')
+  let i = 2
+  let last = false
+  if (argv[i] !== undefined && argv[i].text === '--last') {
+    last = true
+    i++
+  }
+  const rest = argv.slice(i)
+  if (rest.length === 0) return fail('missing-prompt')
+  if (rest[0].text === '--prompt-file') {
+    if (rest.length < 2 || rest[1].text === '') return fail('missing-prompt-file-path')
+    if (rest.length > 2) return fail('trailing-arguments')
+    return ok({ last, prompt: { kind: 'prompt-file', path: rest[1].text } })
+  }
+  if (rest[0].text !== '--') return fail('unexpected-token')
+  if (rest.length < 2) return fail('missing-prompt')
+  if (rest.length > 2) return fail('trailing-arguments')
+  const prompt = rest[1].text
+  if (prompt === '') return fail('empty-prompt')
+  if (prompt.includes('\n') || prompt.includes('\r')) return fail('control-char-in-prompt')
+  if (prompt.startsWith('-')) return fail('dash-leading-inline-prompt')
+  return ok({ last, prompt: { kind: 'inline', text: prompt } })
+}
+
+/**
+ * Full matcher pipeline: lex the raw bash command to exactly one simple
+ * command, then pin its argv to the grammar.
+ */
+export function matchInvocation(raw, { node = CANONICAL_NODE, launcher = CANONICAL_LAUNCHER } = {}) {
+  const lex = lexCommand(raw)
+  if (!lex.ok) return lex
+  return parseArgv(lex.argv, { node, launcher })
+}
+
+/**
+ * Shared fixture table (one-shared-parser-source rule). Every row runs
+ * through matchInvocation; positive rows pin the normalized parse, negative
+ * rows carry `reason` = the violated rule. `layer` documents which layer
+ * rejects (or accepts) the row; lexer-layer rows fail regardless of anchors.
+ */
+export const FIXTURES = [
+  // ---- positive: pinned normalized shapes ----
+  {
+    name: 'inline prompt',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- "review the failing spec"`,
+    ok: true,
+    value: { last: false, prompt: { kind: 'inline', text: 'review the failing spec' } },
+  },
+  {
+    name: 'inline prompt with --last in its only slot',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --last -- "continue the review"`,
+    ok: true,
+    value: { last: true, prompt: { kind: 'inline', text: 'continue the review' } },
+  },
+  {
+    name: 'prompt-file form',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --prompt-file /tmp/prompts/p.txt`,
+    ok: true,
+    value: { last: false, prompt: { kind: 'prompt-file', path: '/tmp/prompts/p.txt' } },
+  },
+  {
+    name: 'prompt-file form with --last',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --last --prompt-file /tmp/prompts/p.txt`,
+    ok: true,
+    value: { last: true, prompt: { kind: 'prompt-file', path: '/tmp/prompts/p.txt' } },
+  },
+  {
+    name: 'positional prompt may itself be --last (data after --)',
+    layer: 'argv',
+    // D9: `--last` after `--` starts with `-`, so the dash-leading rule
+    // rejects it as an inline prompt (it rides the `-p` argv value).
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- --last`,
+    ok: false,
+    reason: 'dash-leading-inline-prompt',
+  },
+  {
+    name: 'quoted multi-word prompt is one token',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- 'multi word prompt'`,
+    ok: true,
+    value: { last: false, prompt: { kind: 'inline', text: 'multi word prompt' } },
+  },
+  {
+    name: 'expansion-flagged prompt word is accepted as data (never executed)',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- '$(rm -rf /)'`,
+    ok: true,
+    value: { last: false, prompt: { kind: 'inline', text: '$(rm -rf /)' } },
+  },
+  {
+    name: 'hostile install path survives as concatenated quoted word',
+    layer: 'argv',
+    // The POSIX single-quote escape `'\''` needs `\\''` in a JS template
+    // literal: a lone `\` is swallowed (collapses to `''`, an empty quoted
+    // segment), which would lex the path to "quotes", not "quote's".
+    input: `${CANONICAL_NODE} '/opt/dsh space/quote'\\''s/cc-grok-bridge/scripts/grok-review-run.mjs' -- p`,
+    launcher: '/opt/dsh space/quote\'s/cc-grok-bridge/scripts/grok-review-run.mjs',
+    ok: true,
+    value: { last: false, prompt: { kind: 'inline', text: 'p' } },
+  },
+  // ---- negative: lexer layer ----
+  {
+    name: 'unquoted semicolon (compound command)',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p; rm -rf /`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted && (compound command)',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p && echo owned`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted || (compound command)',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p || echo fallback`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted pipe',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p | tee /tmp/leak`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted redirect out',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p > /tmp/out`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted redirect in',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p < /etc/passwd`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'unquoted newline (second command on next line)',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p\ncurl evil.example`,
+    ok: false,
+    reason: 'unquoted-operator',
+  },
+  {
+    name: 'env-assignment prefix',
+    layer: 'lexer',
+    input: `BASH_ENV=/tmp/x ${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p`,
+    ok: false,
+    reason: 'env-assignment-prefix',
+  },
+  {
+    name: 'unquoted $() command substitution',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- $(echo p)`,
+    ok: false,
+    reason: 'command-substitution-unquoted',
+  },
+  {
+    name: 'unquoted backtick command substitution',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- \`echo p\``,
+    ok: false,
+    reason: 'command-substitution-unquoted',
+  },
+  {
+    name: '$() inside double quotes (bash evaluates it)',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- "$(echo p)"`,
+    ok: false,
+    reason: 'command-substitution-double-quoted',
+  },
+  {
+    name: 'backticks inside double quotes',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- "\`echo p\`"`,
+    ok: false,
+    reason: 'command-substitution-double-quoted',
+  },
+  {
+    name: 'unclosed quote',
+    layer: 'lexer',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- 'p`,
+    ok: false,
+    reason: 'unclosed-quote',
+  },
+  // ---- negative: expansion-bearing anchor tokens ----
+  {
+    name: 'tilde expansion in argv[0]',
+    layer: 'argv',
+    input: `~/bin/node ${CANONICAL_LAUNCHER} -- p`,
+    ok: false,
+    reason: 'expansion-in-argv0',
+  },
+  {
+    name: 'glob expansion in launcher path',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} /opt/dsh-cc/*/scripts/grok-review-run.mjs -- p`,
+    ok: false,
+    reason: 'expansion-in-argv1',
+  },
+  {
+    name: '$VAR expansion in argv[0]',
+    layer: 'argv',
+    input: `$NODE_BIN ${CANONICAL_LAUNCHER} -- p`,
+    ok: false,
+    reason: 'expansion-in-argv0',
+  },
+  // ---- negative: argv layer ----
+  {
+    name: 'forged launcher path (absolute but not the anchor)',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} /tmp/evil/scripts/grok-review-run.mjs -- p`,
+    ok: false,
+    reason: 'argv1-byte-mismatch',
+  },
+  {
+    name: 'PATH-trampoline interpreter bare name',
+    layer: 'argv',
+    input: `node ${CANONICAL_LAUNCHER} -- p`,
+    ok: false,
+    reason: 'argv0-byte-mismatch',
+  },
+  {
+    name: 'symlink-literal anchor (bytes differ from the canonical launcher)',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} /tmp/link-to-grok-review-run.mjs -- p`,
+    ok: false,
+    reason: 'argv1-byte-mismatch',
+  },
+  {
+    name: 'duplicate --last',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --last --last -- p`,
+    ok: false,
+    reason: 'unexpected-token',
+  },
+  {
+    name: 'misplaced --last after the prompt',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p --last`,
+    ok: false,
+    reason: 'trailing-arguments',
+  },
+  {
+    name: 'misplaced --last alone (no prompt)',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --last`,
+    ok: false,
+    reason: 'missing-prompt',
+  },
+  {
+    name: 'no prompt at all',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER}`,
+    ok: false,
+    reason: 'missing-prompt',
+  },
+  {
+    name: 'empty positional prompt',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- ""`,
+    ok: false,
+    reason: 'empty-prompt',
+  },
+  {
+    name: '-- with no prompt token',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --`,
+    ok: false,
+    reason: 'missing-prompt',
+  },
+  {
+    name: 'dash-leading inline prompt is rejected (the -p argv value would be re-parsed as a flag)',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- -restart-from-scratch`,
+    ok: false,
+    reason: 'dash-leading-inline-prompt',
+  },
+  {
+    name: 'newline-bearing positional prompt',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- "line one\nline two"`,
+    ok: false,
+    reason: 'control-char-in-prompt',
+  },
+  {
+    name: 'carriage-return-bearing positional prompt',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- "line one\rline two"`,
+    ok: false,
+    reason: 'control-char-in-prompt',
+  },
+  {
+    name: 'unknown flag before the prompt',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --json -- p`,
+    ok: false,
+    reason: 'unexpected-token',
+  },
+  {
+    name: '--prompt-file without a path',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --prompt-file`,
+    ok: false,
+    reason: 'missing-prompt-file-path',
+  },
+  {
+    name: '--prompt-file with empty path',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --prompt-file ""`,
+    ok: false,
+    reason: 'missing-prompt-file-path',
+  },
+  {
+    name: '--prompt-file with trailing arguments',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} --prompt-file /tmp/p.txt -- q`,
+    ok: false,
+    reason: 'trailing-arguments',
+  },
+  {
+    name: 'positional prompt with trailing extra argument',
+    layer: 'argv',
+    input: `${CANONICAL_NODE} ${CANONICAL_LAUNCHER} -- p extra`,
+    ok: false,
+    reason: 'trailing-arguments',
+  },
+]

package/scripts/lib/canonical.mjs

@@ -0,0 +1,103 @@
+/**
+ * canonical.mjs — the single arming/derivation source for the
+ * cc-grok-bridge hooks.
+ *
+ * Every hook (PreToolUse allow, SessionStart context) derives the canonical
+ * anchor pair and the refusal/arming verdict through THIS module only; the
+ * specs pin that no hook re-implements the derivation.
+ *
+ * Canonical anchors: `realpath(process.execPath)` of the calling hook
+ * process plus the realpath of the sibling `scripts/grok-review-run.mjs`
+ * resolved from the hook's own `import.meta.url`. Refusal set: the
+ * canonicalized session cwd plus the canonical tmp roots, unrealpathable
+ * entries skipped. The Grok review lane also refuses win32 (the launcher
+ * refuses it too).
+ */
+import { realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+
+export const safeReal = (p) => {
+  try {
+    return realpathSync(p)
+  } catch {
+    return null
+  }
+}
+
+/** Containment against canonicalized roots (path-boundary aware). */
+export const inside = (p, roots) => p !== null && roots.some((root) => p === root || p.startsWith(root + '/'))
+
+/** POSIX single-quote escape: bytes inside the quotes are pure data. */
+export const posixSingleQuote = (s) => `'` + String(s).replaceAll(`'`, `'\\''`) + `'`
+
+/**
+ * Derive the canonical anchor pair from the CALLING hook's own location
+ * (pass that hook's `import.meta.url`). Returns null when either anchor is
+ * unrealpathable.
+ */
+export function deriveAnchors(hookUrl) {
+  const node = safeReal(process.execPath)
+  const launcher = safeReal(fileURLToPath(new URL('../scripts/grok-review-run.mjs', hookUrl)))
+  if (node === null || launcher === null) return null
+  return { node, launcher }
+}
+
+/** Refusal set: session cwd plus canonical tmp roots. */
+export function refusalRoots(cwdRaw) {
+  return [safeReal(cwdRaw), safeReal(tmpdir()), safeReal('/tmp')].filter((p) => p !== null)
+}
+
+/**
+ * Arming predicate with machine-readable reasons. `hookUrl` is the calling
+ * hook's `import.meta.url`; `env` defaults to `process.env` and `platform`
+ * to `process.platform` (the hooks pass nothing and inherit both).
+ */
+export function arming(cwdRaw, { hookUrl, env = process.env, platform = process.platform } = {}) {
+  const anchors = deriveAnchors(hookUrl)
+  if (anchors === null) return { armed: false, reason: 'anchor-unrealpathable' }
+  if (platform === 'win32') return { armed: false, reason: 'platform-win32' }
+  const cwd = safeReal(typeof cwdRaw === 'string' && cwdRaw !== '' ? cwdRaw : process.cwd())
+  if (cwd === null) return { armed: false, reason: 'anchor-unrealpathable' }
+  const roots = refusalRoots(cwd)
+  if (inside(anchors.node, roots) || inside(anchors.launcher, roots)) {
+    return { armed: false, reason: 'anchor-under-writable-root' }
+  }
+  if (env.BASH_ENV) return { armed: false, reason: 'bash-env-set' }
+  if (env.ENV) return { armed: false, reason: 'env-set' }
+  return { armed: true, node: anchors.node, launcher: anchors.launcher, cwd }
+}
+
+/**
+ * The ARMED additionalContext block: the exact canonical invocation to type,
+ * both anchor paths POSIX single-quote-escaped so hostile install paths
+ * survive as pure data.
+ */
+export function armedText({ node, launcher }) {
+  const q = posixSingleQuote
+  return [
+    'cc-grok-bridge: the Grok review lane is ARMED. Use EXACTLY this canonical invocation for a Grok review:',
+    `${q(node)} ${q(launcher)} -- 'the review request, single line'`,
+    'For a multi-line prompt (or any request whose first character is `-` — dash-leading inline prompts are rejected by the launcher), write the text to a file inside this workspace (or the canonical tmpdir), then run:',
+    `${q(node)} ${q(launcher)} --prompt-file 'the prompt file path'`,
+    'Add --last ONLY when the user explicitly asks to continue the previous review (it resumes the most recent review thread for this workspace).',
+  ].join('\n')
+}
+
+/** The REFUSED additionalContext block: machine reason in plain words. */
+export function refusedText(reason) {
+  const words =
+    reason === 'anchor-under-writable-root'
+      ? "the plugin's launcher sits under this session's workspace, expected in dsh-cc repo dev sessions"
+      : reason === 'bash-env-set'
+        ? 'the ambient BASH_ENV variable is non-empty (shell-function takeover defense)'
+        : reason === 'env-set'
+          ? 'the ambient ENV variable is non-empty (shell-function takeover defense)'
+          : reason === 'platform-win32'
+            ? 'platform win32 is unsupported — the launcher refuses it too'
+            : 'the plugin\'s canonical anchors could not be resolved in this environment'
+  return [
+    `cc-grok-bridge: the Grok review lane is NOT armed (reason: ${reason} — ${words}).`,
+    'Grok review today goes through the normal, approval-requiring path; do NOT guess or construct the bridge\'s canonical bash invocation manually.',
+  ].join('\n')
+}