@haposoft/cafekit 0.16.0 → 0.16.1

package/README.md

@@ -2,7 +2,7 @@
 
 > Native spec-driven workflow and runtime bundle for Claude Code and Codex CLI.
 
-[![Version](https://img.shields.io/badge/version-0.16.0-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.16.1-blue.svg)](https://github.com/haposoft/cafekit)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Claude%20Code](https://img.shields.io/badge/Claude%20Code-Native-orange.svg)](https://claude.ai/code)
 [![Codex%20CLI](https://img.shields.io/badge/Codex%20CLI-Native-111111.svg)](https://developers.openai.com/codex)

package/bin/__tests__/codex-hooks.test.js

@@ -1746,3 +1746,128 @@ test('Claude and Codex fail closed consistently for malformed cwd payloads', ()
     assert.equal(JSON.parse(codex.stdout).hookSpecificOutput.permissionDecision, 'deny');
   });
 });
+
+test('Codex emits the required decision for all six receipt states', () => {
+  // Codex owns no checker of its own: both wrappers in .codex/hooks/lib forward to
+  // the shared module, so the two receipt modes arrive by inheritance. This case is
+  // the regression lock on that inheritance. Each state asserts the decision Codex
+  // must emit on its own terms; parity with Claude is checked in addition, never
+  // instead, because both runtimes execute the same module and a broken
+  // implementation would agree with itself.
+  //
+  // The dirty-tree state runs the hook from a directory below the project root with
+  // the uncommitted change outside that directory's subtree. Without that, an
+  // implementation resolving the repository root from the working directory returns
+  // the same decision as a correct one and the case cannot fail.
+  inHookFixture((root, hooks) => {
+    const nested = path.join(root, 'packages', 'app');
+    const feature = path.join(root, 'specs', 'auth');
+    const taskFile = path.join(feature, 'task-01-auth.md');
+    const outsideDirt = path.join(root, 'src', 'outside.txt');
+    fs.mkdirSync(nested, { recursive: true });
+    fs.mkdirSync(feature, { recursive: true });
+    fs.mkdirSync(path.dirname(outsideDirt), { recursive: true });
+    fs.writeFileSync(path.join(feature, 'plan.md'), '# Auth plan\n');
+    fs.writeFileSync(outsideDirt, 'committed\n');
+
+    const staleBase = 'f'.repeat(40);
+    const staleHead = 'e'.repeat(40);
+    const taskBody = [
+      '# Task 01: auth', '', 'Status: done', '',
+      '## Dependencies', '', '- none', '',
+      '## Verification Plan', '', '- Command: node --test', '',
+      '## Receipt', '',
+      'Verification: PASS', 'Command: node --test', 'Exit: 0',
+      `Base: ${staleBase}`, `Head: ${staleHead}`,
+      '```text', '$ node --test', 'pass: 1', '```', '',
+    ].join('\n');
+    fs.writeFileSync(taskFile, taskBody);
+
+    const gate = path.join(hooks, 'spec-gate.cjs');
+    const payload = {
+      cwd: nested,
+      featureName: 'auth',
+      session_id: 'session-a',
+      hook_event_name: 'Stop',
+      stop_hook_active: false,
+    };
+    const git = (...args) => {
+      const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+      return result;
+    };
+    const decide = () => {
+      const result = runHook(gate, nested, payload);
+      assert.equal(result.status, 0, result.stderr);
+      return result.stdout.trim() === '' ? 'accept' : 'block';
+    };
+    // Use the same module instance that minted the context: a trusted runtime
+    // context is tracked per module, so mixing the package copy with the fixture
+    // copy would report a spurious binding failure.
+    const RECEIPT = require(path.join(PACKAGE_ROOT, 'src/claude/scripts/spec-receipt.cjs'));
+    const sharedDecides = () => {
+      const failures = RECEIPT.checkWorkflowTaskReceipt(
+        feature, 'task-01-auth.md', workflowRuntimeContext(root), POLICY,
+      ).failures;
+      return failures.length === 0 ? 'accept' : 'block';
+    };
+
+    // 1. untracked task file — never committed, so the binding stays.
+    assert.equal(decide(), 'block', 'an untracked task file must keep full binding');
+
+    // 2. staged but not committed — `git add` alone must not read as committed.
+    git('add', '-A');
+    assert.equal(decide(), 'block', 'a staged-only task file must keep full binding');
+
+    // 3. committed on a clean tree — the one accepting state.
+    git('commit', '-qm', 'receipt and source');
+    // Generated runtime state is excluded by design, so assert cleanliness the way
+    // the selector sees it: nothing dirty outside the specs root and the runtime
+    // state roots. The gate's own cache write must not read as a dirty worktree.
+    const cleanStatus = spawnSync('git', ['-C', root, 'status', '--porcelain', '--untracked-files=all',
+      '--', '.', ':(exclude,literal)specs', ':(exclude,literal).codex/hooks/.logs',
+      ':(exclude,literal).claude/hooks/.logs', ':(exclude,literal).codex/runtime.json'], { encoding: 'utf8' });
+    assert.equal(cleanStatus.stdout.trim(), '', 'nothing outside specs and runtime state may be dirty for this state to mean anything');
+    assert.equal(decide(), 'accept', 'a committed, unchanged receipt on a clean tree must be accepted');
+    assert.equal(sharedDecides(), 'accept', 'the shared checker must agree');
+
+    // 4. dirty tree outside the specs root, hook run from a nested directory with
+    //    the change outside that directory's subtree.
+    fs.writeFileSync(outsideDirt, 'uncommitted\n');
+    assert.ok(!path.relative(nested, outsideDirt).startsWith('..') === false,
+      'the dirt must lie outside the working directory used for the run');
+    assert.equal(decide(), 'block', 'an uncommitted change outside the specs root must rebind');
+    assert.equal(sharedDecides(), 'block', 'the shared checker must agree');
+    git('checkout', '--', 'src/outside.txt');
+
+    // 5. work confined to the specs root does not reopen a committed receipt.
+    fs.writeFileSync(path.join(feature, 'plan.md'), '# Auth plan\n\nEdited after the receipt landed.\n');
+    assert.equal(decide(), 'accept', 'edits inside the specs root must not rebind');
+    git('checkout', '--', 'specs/auth/plan.md');
+
+    // 6. committed then modified — the receipt itself changed after the commit.
+    fs.writeFileSync(taskFile, taskBody.replace(`Head: ${staleHead}`, `Head: ${'d'.repeat(40)}`));
+    assert.equal(decide(), 'block', 'a receipt edited after commit must be rebound');
+    assert.equal(sharedDecides(), 'block', 'the shared checker must agree');
+  });
+});
+
+test('Codex wrappers stay pass-through and carry no receipt-mode logic', () => {
+  // The mode selector must exist in exactly one place. If it is ever duplicated
+  // into the Codex wrapper, the two runtimes can drift apart silently.
+  const wrapper = fs.readFileSync(
+    path.join(PACKAGE_ROOT, 'src/codex/hooks/lib/spec-receipt.cjs'),
+    'utf8',
+  );
+  for (const marker of ['receiptBindingMode', 'skip-worktree', 'ls-files', 'cat-file', 'structure']) {
+    assert.ok(
+      !wrapper.includes(marker),
+      `the Codex wrapper must not reimplement receipt-mode logic; found ${marker}`,
+    );
+  }
+  assert.match(wrapper, /checkWorkflowTaskReceipt\(featureDir, taskPath, runtimeContext, policy\)/);
+  assert.match(
+    fs.readFileSync(path.join(PACKAGE_ROOT, 'src/codex/hooks/spec-state.cjs'), 'utf8'),
+    /Stop re-checks every done receipt/,
+  );
+});

package/bin/__tests__/develop-contract.test.js

@@ -89,7 +89,7 @@ function installClaudeRuntimeClosure(fixtureRoot, entry = 'hooks/spec-gate.cjs')
     fs.copyFileSync(path.join(hooksRoot, hook), target);
   }
   // Hook helpers the raw-copied hooks require at runtime.
-  for (const helper of ['hook-state-dir.cjs']) {
+  for (const helper of ['hook-state-dir.cjs', 'runtime-dir.cjs', 'hook-payload.cjs']) {
     const target = path.join(destinationRoot, 'hooks', 'lib', helper);
     fs.mkdirSync(path.dirname(target), { recursive: true });
     fs.copyFileSync(path.join(hooksRoot, 'lib', helper), target);
@@ -3338,3 +3338,45 @@ test('P0 canonical phantom vectors - zero, cancellation, suite, FAIL, error, col
   assert.equal(POLICY.isTapMetadataHeading('# Notes'), false);
   assert.equal(POLICY.isTapMetadataHeading('# pass 1 explanation'), false);
 });
+
+test('generated runtime state under every platform folder stays out of the worktree digest', () => {
+  // The gate writes its cache and the installer writes runtime.json under the platform
+  // folder on every run. If those writes moved Head, a project tracking its runtime
+  // directory could never hold a stable receipt. The exclusion list must name each
+  // shipped platform, and a real source change must still move Head.
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-state-roots-'));
+  try {
+    for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'], ['config', 'user.name', 'CafeKit Test'], ['commit', '--allow-empty', '-qm', 'fixture']]) {
+      const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+      assert.equal(result.status, 0, result.stderr);
+    }
+    fs.mkdirSync(path.join(root, 'specs', 'demo'), { recursive: true });
+    fs.writeFileSync(path.join(root, 'specs', 'demo', 'plan.md'), '# Demo plan\n');
+    const derive = () => PROVENANCE_HELPER.deriveRuntimeContext({
+      projectRoot: root,
+      specsRoot: path.join(root, 'specs'),
+      specFile: path.join(root, 'specs', 'demo', 'plan.md'),
+      featureName: 'demo',
+      runtimeSession: 'state-roots',
+    });
+    const before = derive();
+
+    for (const folder of ['.claude', '.codex', '.omp']) {
+      fs.mkdirSync(path.join(root, folder, 'hooks', '.logs'), { recursive: true });
+      fs.mkdirSync(path.join(root, folder, '.logs'), { recursive: true });
+      fs.writeFileSync(path.join(root, folder, 'hooks', '.logs', 'spec-gate-last.json'), '{"demo":{}}\n');
+      fs.writeFileSync(path.join(root, folder, '.logs', 'hook-log.jsonl'), '{}\n');
+      fs.writeFileSync(path.join(root, folder, 'runtime.json'), '{"spec":{"completion_gate":true}}\n');
+    }
+    const afterState = derive();
+    assert.equal(afterState.head, before.head, 'runtime state under .claude, .codex, and .omp must not move Head');
+    assert.equal(afterState.base, before.base);
+
+    // Anything else under the platform folder is source: a hook edit must move Head.
+    fs.mkdirSync(path.join(root, '.omp', 'hooks'), { recursive: true });
+    fs.writeFileSync(path.join(root, '.omp', 'hooks', 'rules.cjs'), '// edited\n');
+    assert.notEqual(derive().head, before.head, 'a real file under the platform folder must still move Head');
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});

package/bin/__tests__/grok-envelope.test.js

@@ -0,0 +1,271 @@
+'use strict';
+
+// Grok CLI runs these hooks through its Claude-compatibility layer, so the scripts must
+// answer the same way whether the envelope came from Claude Code or from grok. Each case
+// runs a real hook as a child process from a tree shaped like an install, with grok's
+// camelCase envelope on stdin and CLAUDE_PROJECT_DIR set the way grok sets it.
+//
+// Every case names the gate it protects. Before the payload reader existed, each of them
+// answered nothing: the hook read an undefined key, found no tool and no path, and let
+// the call through while looking installed.
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { test } = require('node:test');
+
+const PACKAGE_ROOT = path.join(__dirname, '../..');
+const MANIFEST = require(path.join(PACKAGE_ROOT, 'src/claude/migration-manifest.json'));
+
+/**
+ * A `.claude` tree holding exactly what an install ships, inside a git repository.
+ * The repository matters because the Stop gate derives provenance with git before it
+ * reads anything else.
+ */
+function withInstall(run, { git = false } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-grok-envelope-'));
+  try {
+    for (const rel of MANIFEST.runtime.files.filter((f) => f.startsWith('hooks/'))) {
+      const target = path.join(root, '.claude', rel);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.copyFileSync(path.join(PACKAGE_ROOT, 'src/claude', rel), target);
+    }
+    fs.cpSync(path.join(PACKAGE_ROOT, 'src/claude/scripts'), path.join(root, '.claude', 'scripts'),
+      { recursive: true });
+    if (git) {
+      for (const args of [['init', '-q'], ['config', 'user.email', 'cafekit@example.invalid'],
+        ['config', 'user.name', 'CafeKit Test'], ['commit', '--allow-empty', '-qm', 'fixture']]) {
+        const r = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+        assert.equal(r.status, 0, r.stderr);
+      }
+    }
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+/** Run one installed hook the way grok runs it. */
+function runHook(root, name, payload, args = []) {
+  const r = spawnSync(process.execPath, [path.join(root, '.claude', 'hooks', name), ...args], {
+    cwd: root,
+    input: JSON.stringify(payload),
+    encoding: 'utf8',
+    // grok sets CLAUDE_PROJECT_DIR as an alias of GROK_WORKSPACE_ROOT on every hook.
+    env: { ...process.env, CLAUDE_PROJECT_DIR: root, PROJECT_ROOT: '', GROK_SESSION_ID: 'grok-1' },
+  });
+  return { code: r.status, stdout: r.stdout || '', stderr: r.stderr || '' };
+}
+
+function decisionOf(stdout) {
+  for (const line of stdout.trim().split('\n').filter(Boolean)) {
+    try {
+      const parsed = JSON.parse(line);
+      const d = parsed?.hookSpecificOutput?.permissionDecision ?? parsed?.decision;
+      if (d) return { decision: d, reason: parsed?.hookSpecificOutput?.permissionDecisionReason ?? parsed?.reason };
+    } catch { /* not JSON, keep looking */ }
+  }
+  return { decision: null, reason: null };
+}
+
+test('the privacy gate asks on a grok run_terminal_command', () => {
+  withInstall((root) => {
+    fs.writeFileSync(path.join(root, '.env'), 'TOKEN=redacted\n');
+    // grok's shell tool under grok's key names. Reading `data.tool_name` here yields
+    // undefined, so the command is never scanned and the secret is handed over.
+    const r = runHook(root, 'privacy-block.cjs', {
+      hookEventName: 'pre_tool_use',
+      sessionId: 'grok-1',
+      cwd: root,
+      toolName: 'run_terminal_command',
+      toolInput: { command: `cat ${path.join(root, '.env')}` },
+    });
+    const { decision, reason } = decisionOf(r.stdout);
+    assert.equal(decision, 'ask', 'a grok shell call touching .env must reach the approval prompt');
+    assert.match(reason, /\.env/, 'the prompt must name what it is protecting');
+  });
+});
+
+test('the privacy gate asks on a grok read_file path', () => {
+  withInstall((root) => {
+    fs.writeFileSync(path.join(root, '.env'), 'TOKEN=redacted\n');
+    // grok's read tool carries its argument as `path`, not `file_path`.
+    const r = runHook(root, 'privacy-block.cjs', {
+      hookEventName: 'pre_tool_use',
+      cwd: root,
+      toolName: 'read_file',
+      toolInput: { path: path.join(root, '.env') },
+    });
+    assert.equal(decisionOf(r.stdout).decision, 'ask');
+  });
+});
+
+test('an ordinary grok read is not disturbed', () => {
+  withInstall((root) => {
+    fs.writeFileSync(path.join(root, 'README.md'), '# hello\n');
+    const r = runHook(root, 'privacy-block.cjs', {
+      hookEventName: 'pre_tool_use',
+      cwd: root,
+      toolName: 'read_file',
+      toolInput: { path: path.join(root, 'README.md') },
+    });
+    assert.equal(decisionOf(r.stdout).decision, null, 'the gate must not ask about an ordinary file');
+    assert.equal(r.code, 0);
+  });
+});
+
+test('a broad glob is denied with its full reason in JSON', () => {
+  withInstall((root) => {
+    const r = runHook(root, 'inspect-block.cjs', {
+      hookEventName: 'pre_tool_use',
+      cwd: root,
+      toolName: 'Glob',
+      toolInput: { pattern: '**/*.ts' },
+    });
+    const { decision, reason } = decisionOf(r.stdout);
+    assert.equal(decision, 'deny');
+    // grok reads only the first stderr line, so the actionable half of the message has to
+    // travel in the JSON reason or the model is blocked without being told what to do.
+    assert.match(reason, /SCOPE LIMIT EXCEEDED/);
+    assert.match(reason, /Please narrow your scope/, 'the whole message must survive, not just its first line');
+    assert.equal(r.code, 2, 'exit 2 stays for a host that reads neither channel');
+  });
+});
+
+test('a nested task write is denied under the grok write tool', () => {
+  withInstall((root) => {
+    const target = path.join(root, 'specs', 'demo', 'tasks', 'task-R0-01-x.md');
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    // grok creates files with `write`; `search_replace` edits an existing one. The guard
+    // fires on Write only, so the alias has to keep those two apart.
+    const r = runHook(root, 'task-scaffold-guard.cjs', {
+      hookEventName: 'pre_tool_use',
+      cwd: root,
+      toolName: 'write',
+      toolInput: { path: target, content: '# x' },
+    });
+    const { decision, reason } = decisionOf(r.stdout);
+    assert.equal(decision, 'deny');
+    assert.match(reason, /TASK SCAFFOLD REQUIRED/);
+    assert.match(reason, /spec-scaffold\.cjs/, 'the command the model must run has to reach it');
+    assert.equal(r.code, 2);
+
+    // The escape route the message names must stay open: an edit is not a create.
+    const edit = runHook(root, 'task-scaffold-guard.cjs', {
+      hookEventName: 'pre_tool_use',
+      cwd: root,
+      toolName: 'search_replace',
+      toolInput: { path: target, old_string: 'a', new_string: 'b' },
+    });
+    assert.equal(decisionOf(edit.stdout).decision, null, 'search_replace must not be treated as a create');
+    assert.equal(edit.code, 0);
+  });
+});
+
+/** A packet the Stop gate will block: one done task with no receipt. */
+function unprovenPacket(root) {
+  const feature = path.join(root, 'specs', 'demo');
+  fs.mkdirSync(feature, { recursive: true });
+  fs.writeFileSync(path.join(feature, 'plan.md'), '# Demo plan\n');
+  fs.writeFileSync(path.join(feature, 'task-01-demo.md'), [
+    '# Task 01: demo', '', 'Status: done', '', '## Dependencies', '', '- none', '',
+    '## Verification Plan', '', '- Command: node --test', '',
+  ].join('\n'));
+}
+
+test('the Stop gate honours stopHookActive', () => {
+  withInstall((root) => {
+    // The fixture must be one the gate would otherwise block, or silence proves nothing:
+    // an empty specs directory makes the gate exit quietly for a different reason.
+    unprovenPacket(root);
+    // Without the guard the gate re-blocks its own continuation until grok's cap ends
+    // the turn eight rounds later.
+    const r = runHook(root, 'spec-gate.cjs', {
+      hookEventName: 'stop',
+      sessionId: 'grok-1',
+      cwd: root,
+      stopHookActive: true,
+    });
+    assert.equal(r.stdout.trim(), '', 'a continuation round must pass silently');
+    assert.equal(r.code, 0);
+  }, { git: true });
+});
+
+test('the Stop gate still blocks an unproven done task', () => {
+  withInstall((root) => {
+    unprovenPacket(root);
+    // The guard must not become a way through: a Stop with no continuation flag still
+    // faces the receipt check.
+    const r = runHook(root, 'spec-gate.cjs', {
+      hookEventName: 'stop', sessionId: 'grok-1', cwd: root, stopHookActive: false,
+    });
+    const body = decisionOf(r.stdout);
+    assert.equal(body.decision, 'block', 'a done task without a receipt must still be blocked');
+  }, { git: true });
+});
+
+test('the approval hook takes its approve path on a grok prompt', () => {
+  withInstall((root) => {
+    // Registered without an argv mode, this hook picks its mode from the event name, and
+    // approve() returns immediately unless that name is exactly 'UserPromptSubmit'. An
+    // approval phrase with no pending request is therefore the oracle: only the approve
+    // path can print a rejection line, so the line proves the event name was translated.
+    // Under an unreadable envelope the mode fell back to the stop path on every prompt.
+    const nonce = 'a'.repeat(24);
+    const r = runHook(root, 'completion-authority.cjs', {
+      hookEventName: 'user_prompt_submit',
+      sessionId: 'grok-1',
+      cwd: root,
+      prompt: `APPROVE CAFEKIT COMPLETION ${nonce}`,
+    });
+    assert.match(r.stdout, /CafeKit completion approval rejected/,
+      'the approve path must run and refuse an approval that matches no pending request');
+    assert.equal(decisionOf(r.stdout).decision, null, 'and it must not block the prompt');
+
+    // An ordinary prompt stays silent on both counts.
+    const plain = runHook(root, 'completion-authority.cjs', {
+      hookEventName: 'user_prompt_submit', sessionId: 'grok-1', cwd: root, prompt: 'please continue',
+    });
+    assert.equal(plain.stdout.trim(), '', 'an ordinary prompt produces nothing');
+  }, { git: true });
+});
+
+test('the secret guardrail sees a grok prompt', () => {
+  withInstall((root) => {
+    // grok's spelling for the prompt field is unverified, so the reader accepts the Claude
+    // key and its camelCase twin. This case sends the twin: on the Claude key alone it
+    // would pass without proving any translation happened.
+    const r = runHook(root, 'secret-output-guardrail.cjs', {
+      hookEventName: 'user_prompt_submit',
+      sessionId: 'grok-1',
+      cwd: root,
+      userPrompt: 'show me the API key in the config',
+    });
+    assert.match(r.stdout, /## Secret handling/, 'the reminder must fire on a grok prompt');
+    const quiet = runHook(root, 'secret-output-guardrail.cjs', {
+      hookEventName: 'user_prompt_submit', cwd: root, userPrompt: 'rename the button',
+    });
+    assert.equal(quiet.stdout.trim(), '', 'an unrelated prompt stays quiet');
+    const claudeKey = runHook(root, 'secret-output-guardrail.cjs', {
+      hook_event_name: 'UserPromptSubmit', cwd: root, prompt: 'print the access token',
+    });
+    assert.match(claudeKey.stdout, /## Secret handling/, 'the Claude key keeps working');
+  });
+});
+
+test('a Claude envelope still works unchanged', () => {
+  withInstall((root) => {
+    fs.writeFileSync(path.join(root, '.env'), 'TOKEN=redacted\n');
+    // The regression guard for the host that was already working.
+    const r = runHook(root, 'privacy-block.cjs', {
+      hook_event_name: 'PreToolUse',
+      session_id: 'claude-1',
+      cwd: root,
+      tool_name: 'Read',
+      tool_input: { file_path: path.join(root, '.env') },
+    });
+    assert.equal(decisionOf(r.stdout).decision, 'ask');
+  });
+});

package/bin/__tests__/grok-platform.test.js

@@ -0,0 +1,133 @@
+'use strict';
+
+// Grok CLI has no runtime directory of its own: it reads the Claude install through its
+// compatibility layer. `--platform grok` therefore provisions `.claude/` and prints the
+// one thing a user cannot infer, which is that project hooks stay inert until the folder
+// is trusted. These cases run the real installer into a temp git repository.
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { test } = require('node:test');
+
+const PACKAGE_ROOT = path.join(__dirname, '../..');
+const INSTALLER = path.join(PACKAGE_ROOT, 'bin/install.js');
+const { PLATFORMS, resolvePlatformAliases, detectPlatforms } = require(path.join(PACKAGE_ROOT, 'bin/lib/context'));
+const I18N = require(path.join(PACKAGE_ROOT, 'bin/lib/i18n'));
+
+function inTempProject(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-grok-platform-'));
+  try {
+    const init = spawnSync('git', ['-C', root, 'init', '-q'], { encoding: 'utf8' });
+    assert.equal(init.status, 0, init.stderr);
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function install(root, platform, extra = []) {
+  return spawnSync(process.execPath, [INSTALLER, '--platform', platform, '--yes', ...extra],
+    { cwd: root, encoding: 'utf8', env: { ...process.env, HOME: path.join(root, 'home'), PATH: '/usr/bin:/bin' } });
+}
+
+test('grok is an alias, not a platform of its own', () => {
+  assert.equal(PLATFORMS.grok, undefined, 'a registry entry would create a .grok payload');
+  assert.deepEqual(resolvePlatformAliases(['grok']).platforms, ['claude']);
+  assert.equal(resolvePlatformAliases(['grok']).aliased, true);
+  assert.equal(resolvePlatformAliases(['claude']).aliased, false);
+});
+
+test('--platform grok installs the Claude runtime and no .grok directory', () => {
+  inTempProject((root) => {
+    const result = install(root, 'grok');
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+
+    assert.equal(fs.existsSync(path.join(root, '.claude', 'hooks', 'privacy-block.cjs')), true,
+      'grok runs the Claude gate scripts, so they have to be installed');
+    assert.equal(fs.existsSync(path.join(root, '.claude', 'settings.json')), true,
+      'grok discovers the hooks through this file');
+    assert.equal(fs.existsSync(path.join(root, '.grok')), false, 'CafeKit ships nothing under .grok');
+
+    const metadata = JSON.parse(fs.readFileSync(path.join(root, '.claude', 'cafekit.json'), 'utf8'));
+    assert.equal(metadata.platform, 'claude', 'the install is a Claude install and must record itself as one');
+  });
+});
+
+test('the trust reminder is printed once in the selected language', () => {
+  inTempProject((root) => {
+    const en = install(root, 'grok', ['--lang', 'en']);
+    assert.equal(en.status, 0, en.stderr);
+    const occurrences = en.stdout.split('grok --trust').length - 1;
+    assert.equal(occurrences, 1, 'the notice must appear exactly once');
+    assert.match(en.stdout, /\/hooks-trust/, 'both ways to grant trust are named');
+  });
+
+  inTempProject((root) => {
+    const vi = install(root, 'grok', ['--lang', 'vi']);
+    assert.equal(vi.status, 0, vi.stderr);
+    // The Vietnamese string, not the English one: the notice follows --lang like every
+    // other installer line.
+    assert.match(vi.stdout, /lớp tương thích Claude/);
+  });
+});
+
+test('grok and claude together install once', () => {
+  inTempProject((root) => {
+    const result = install(root, 'grok,claude');
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    const lines = result.stdout.split('\n').filter((l) => l.includes('Claude Code'));
+    assert.ok(lines.length > 0, 'the Claude install must be reported');
+    const metadata = JSON.parse(fs.readFileSync(path.join(root, '.claude', 'cafekit.json'), 'utf8'));
+    assert.equal(metadata.platform, 'claude');
+    assert.equal(fs.existsSync(path.join(root, '.grok')), false);
+  });
+});
+
+test('a plain claude install prints no grok notice', () => {
+  inTempProject((root) => {
+    const result = install(root, 'claude');
+    assert.equal(result.status, 0, result.stderr);
+    assert.doesNotMatch(result.stdout, /grok --trust/, 'the alias must leave the Claude path unchanged');
+  });
+});
+
+test('.grok is not a detection marker', () => {
+  // A repository that merely holds `.grok/` has not asked for CafeKit. Adding `.grok` to
+  // Claude's detection markers would make a reinstall in a Codex project silently grow a
+  // `.claude/` tree beside it, because detected platforms are unioned with saved ones.
+  // (An install with no platform at all still defaults to Claude; that is separate, and
+  // predates this alias.)
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-grok-detect-'));
+  const cwd = process.cwd();
+  try {
+    fs.mkdirSync(path.join(root, '.grok', 'agents'), { recursive: true });
+    fs.mkdirSync(path.join(root, '.codex'), { recursive: true });
+    process.chdir(root);
+    const detected = detectPlatforms();
+    assert.deepEqual(detected, ['codex'], 'only the platform with a real payload may be detected');
+  } finally {
+    process.chdir(cwd);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('an unknown platform is still rejected', () => {
+  inTempProject((root) => {
+    const result = install(root, 'nonesuch');
+    assert.notEqual(result.status, 0, 'the alias table must not swallow a typo');
+    assert.match(`${result.stdout}${result.stderr}`, /Unknown platform/);
+  });
+});
+
+test('the notice exists in every shipped locale', () => {
+  // A missing key renders as the key name, which is how a translation gap ships silently.
+  for (const code of I18N.SUPPORTED) {
+    const text = I18N.MESSAGES?.[code]?.grokCompatNotice ?? I18N[code]?.grokCompatNotice;
+    assert.ok(typeof text === 'string' && text.length > 0, `missing grokCompatNotice for ${code}`);
+    assert.match(text, /grok --trust/, `${code} must name the command`);
+    assert.match(text, /hooks-trust/, `${code} must name the slash command`);
+  }
+});