@haposoft/cafekit 0.14.2 → 0.15.1

package/README.md

@@ -1,10 +1,11 @@
 # @haposoft/cafekit
 
-> Claude Code-first spec-driven workflow and runtime bundle for AI coding assistants.
+> Native spec-driven workflow and runtime bundle for Claude Code, Codex CLI, and OpenCode.
 
-[![Version](https://img.shields.io/badge/version-0.14.2-blue.svg)](https://github.com/haposoft/cafekit)
+[![Version](https://img.shields.io/badge/version-0.15.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-Primary-orange.svg)](https://claude.ai/code)
+[![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)
 
 ## Overview
 
@@ -20,6 +21,13 @@ Claude Code install support:
 - installs runtime hooks, statusline, and managed settings
 - merges Claude settings safely on re-run
 
+Codex CLI install support:
+- installs native skills under `.agents/skills/`
+- installs auto-discovered custom agents under `.codex/agents/*.toml`
+- installs native lifecycle hooks, rules, scripts, references, and runtime config under `.codex/`
+- merges a CafeKit-owned block into root `AGENTS.md`
+- requires no generated `.codex/config.toml` and never changes global trust config
+
 OpenCode install support:
 - installs command wrappers under `.opencode/commands/`
 - installs converted OpenCode agents under `.opencode/agents/`
@@ -36,15 +44,22 @@ Run in your project root:
 npx @haposoft/cafekit
 ```
 
-Refresh managed files:
+Install Codex explicitly:
 
 ```bash
-npx @haposoft/cafekit --upgrade
+npx @haposoft/cafekit --platform codex
+```
+
+Re-running the same version selectively refreshes pristine managed files while
+preserving edits. To reset user-modified managed files from a saved backup:
+
+```bash
+npx @haposoft/cafekit --platform codex --force-overwrite
 ```
 
 Requirements:
 - Node.js 18+
-- Claude Code project with `.claude/`, OpenCode project with `.opencode/` or `opencode.json`, or choose a runtime when prompted
+- Claude Code, Codex CLI, or OpenCode; choose a runtime when prompted or use `--platform`
 
 ## Git ignore policy
 
@@ -59,12 +74,17 @@ plans/
 .cafekit.lock
 .claude/
 .opencode/
+.codex/
+.agents/
 ```
 
 Runtime folders are local — reinstall with `npx @haposoft/cafekit` rather than
-committing them. Inside the runtime, CafeKit also installs `.claude/.gitignore`
-(or `.opencode/.gitignore`) so secrets, skill dependencies, session state, and
-hook logs stay out of git even if someone force-adds the folder.
+committing them. Inside the runtime, CafeKit also installs `.claude/.gitignore`,
+`.opencode/.gitignore`, or the Codex pair `.codex/.gitignore` +
+`.agents/.gitignore`. These keep secrets, skill dependencies, session state,
+and hook logs out of git even if someone partially un-ignores a runtime.
+Teams may deliberately commit runtime files, but should also commit the
+ownership manifest so selective updates share the same baseline.
 
 ## What Gets Installed
 
@@ -90,6 +110,33 @@ CLAUDE.md
 CafeKit owns only its marked block inside the project-root `CLAUDE.md`; project
 instructions outside that block are preserved across installs and upgrades.
 
+Codex CLI targets:
+
+```text
+.agents/
+├── .gitignore
+└── skills/
+
+.codex/
+├── .gitignore
+├── agents/*.toml
+├── hooks.json
+├── hooks/
+├── rules/
+├── scripts/
+├── references/
+├── cafekit.json
+└── runtime.json
+
+AGENTS.md
+```
+
+CafeKit owns only its marked block in root `AGENTS.md`. Codex discovers skills
+and custom agents natively after the repository is trusted; no project
+`config.toml` is generated. Review and trust project hooks with `/hooks`.
+CafeKit uses Codex's native status and usage UI instead of installing the
+Claude statusline.
+
 OpenCode targets:
 
 ```text
@@ -119,6 +166,7 @@ To check the installed CafeKit package version:
 
 ```bash
 cat .claude/cafekit.json
+cat .codex/cafekit.json
 cat .opencode/cafekit.json
 ```
 
@@ -144,6 +192,10 @@ CafeKit uses rule-based skill routing guidance instead of an automatic prompt-sc
 node .claude/scripts/generate-skill-catalog.cjs --skills
 ```
 
+On Codex, invoke the transformed native skill names as `$hapo-<name>` or browse
+them with `/skills`. Explicit custom-agent delegation uses snake_case agent
+names and `fork_turns: "none"`.
+
 ## Quick Start
 
 Claude Code:
@@ -157,6 +209,17 @@ Claude Code:
 /hapo:code-review meet-transcript-mvp --pending
 ```
 
+Codex CLI:
+
+```text
+$hapo-question "Which files define the current CafeKit runtime?" --repo
+$hapo-brainstorm Explore approaches for a Google Meet transcript extension
+$hapo-specs Build a Google Meet transcript extension with AI summaries
+$hapo-develop meet-transcript-mvp
+$hapo-test meet-transcript-mvp --full
+$hapo-code-review meet-transcript-mvp --pending
+```
+
 OpenCode uses the generated command names without the Claude `hapo:` prefix:
 
 ```bash
@@ -176,6 +239,14 @@ Reconstruct as-is docs from a legacy codebase:
 
 The reconstruct bundle includes as-is markdown/JSON evidence and a self-contained `overview.html` review dashboard before the approved docs are handed to `/hapo:specs`.
 
+## Codex hook safety
+
+Codex project hooks cover session/prompt/tool/subagent/stop lifecycle events,
+spec and task guardrails, per-session state, and privacy blocking. Sensitive
+access approval is one-time and bound to the session, tool, and exact canonical
+path set. Hooks are guardrails rather than a complete security boundary:
+hosted or specialized tools may not enter the local hook path.
+
 ## Spec Output
 
 Specs are stored under:

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

@@ -0,0 +1,331 @@
+'use strict';
+
+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 CODEX_HOOKS = path.join(PACKAGE_ROOT, 'src/codex/hooks');
+const { stateDir: codexStateDir } = require(
+  path.join(CODEX_HOOKS, 'lib', 'state-store.cjs')
+);
+
+function runHook(file, cwd, payload) {
+  return spawnSync(process.execPath, [file], {
+    cwd,
+    input: JSON.stringify(payload),
+    encoding: 'utf8'
+  });
+}
+
+function inHookFixture(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-hooks-'));
+  const hooks = path.join(root, '.codex', 'hooks');
+  try {
+    fs.cpSync(CODEX_HOOKS, hooks, { recursive: true });
+    fs.mkdirSync(path.join(root, '.codex', 'scripts'), { recursive: true });
+    fs.writeFileSync(path.join(root, '.codex', 'scripts', 'spec-scaffold.cjs'), '');
+    return run(root, hooks);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+test('Codex privacy approval is exact, session-bound, and one-time', () => {
+  inHookFixture((root, hooks) => {
+    const nested = path.join(root, 'packages', 'app');
+    fs.mkdirSync(nested, { recursive: true });
+    fs.writeFileSync(path.join(nested, '.env'), 'SECRET=value\n');
+    const block = path.join(hooks, 'privacy-block.cjs');
+    const approve = path.join(hooks, 'privacy-approval.cjs');
+    const harmlessPatch = runHook(block, nested, {
+      cwd: nested,
+      session_id: 'session-a',
+      hook_event_name: 'PreToolUse',
+      tool_name: 'apply_patch',
+      tool_input: {
+        command: '*** Begin Patch\n*** Update File: README.md\n+Document `.env` setup.\n*** End Patch\n'
+      }
+    });
+    assert.equal(harmlessPatch.stdout, '');
+
+    const request = {
+      cwd: nested,
+      session_id: 'session-a',
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Bash',
+      tool_input: { command: 'cat .env' }
+    };
+
+    const denied = runHook(block, nested, request);
+    assert.equal(denied.status, 0);
+    const decision = JSON.parse(denied.stdout);
+    assert.equal(decision.hookSpecificOutput.permissionDecision, 'deny');
+    const prompt = decision.hookSpecificOutput.permissionDecisionReason.match(
+      /APPROVE CAFEKIT PRIVACY [a-f0-9]{24}/
+    )?.[0];
+    assert.ok(prompt);
+    assert.equal(fs.existsSync(path.join(nested, '.codex')), false);
+    assert.equal(fs.existsSync(path.join(hooks, '.privacy')), true);
+
+    const wrongSession = runHook(approve, nested, {
+      cwd: nested,
+      session_id: 'session-b',
+      hook_event_name: 'UserPromptSubmit',
+      prompt
+    });
+    assert.match(wrongSession.stdout, /rejected/);
+
+    const approved = runHook(approve, nested, {
+      cwd: nested,
+      session_id: 'session-a',
+      hook_event_name: 'UserPromptSubmit',
+      prompt
+    });
+    assert.match(approved.stdout, /approved one retry/);
+
+    const allowedOnce = runHook(block, nested, request);
+    assert.equal(allowedOnce.stdout, '');
+
+    const deniedAgain = runHook(block, nested, request);
+    assert.equal(JSON.parse(deniedAgain.stdout).hookSpecificOutput.permissionDecision, 'deny');
+
+    fs.writeFileSync(path.join(nested, 'credentials.json'), '{"token":"test"}\n');
+    const multiRequest = {
+      ...request,
+      tool_input: { command: 'cat .env credentials.json' }
+    };
+    const multiDenied = runHook(block, nested, multiRequest);
+    const multiDecision = JSON.parse(multiDenied.stdout);
+    assert.match(multiDecision.hookSpecificOutput.permissionDecisionReason, /\.env, credentials\.json/);
+    const multiPrompt = multiDecision.hookSpecificOutput.permissionDecisionReason.match(
+      /APPROVE CAFEKIT PRIVACY [a-f0-9]{24}/
+    )?.[0];
+    assert.ok(multiPrompt);
+
+    const multiApproved = runHook(approve, nested, {
+      cwd: nested,
+      session_id: 'session-a',
+      hook_event_name: 'UserPromptSubmit',
+      prompt: multiPrompt
+    });
+    assert.match(multiApproved.stdout, /approved one retry/);
+
+    // A token for two paths cannot authorize a subset, and the failed subset
+    // attempt must not consume the exact-set token.
+    const subsetDenied = runHook(block, nested, request);
+    assert.equal(JSON.parse(subsetDenied.stdout).hookSpecificOutput.permissionDecision, 'deny');
+    fs.writeFileSync(path.join(nested, 'tokens.json'), '{"token":"test"}\n');
+    const supersetDenied = runHook(block, nested, {
+      ...request,
+      tool_input: { command: 'cat .env credentials.json tokens.json' }
+    });
+    assert.equal(JSON.parse(supersetDenied.stdout).hookSpecificOutput.permissionDecision, 'deny');
+    const reordered = {
+      ...request,
+      tool_input: { command: 'cat credentials.json .env' }
+    };
+    assert.equal(runHook(block, nested, reordered).stdout, '');
+    assert.equal(
+      JSON.parse(runHook(block, nested, multiRequest).stdout).hookSpecificOutput.permissionDecision,
+      'deny'
+    );
+  });
+});
+
+test('Codex privacy hook parses native patch fields and move destinations', () => {
+  inHookFixture((root, hooks) => {
+    const block = path.join(hooks, 'privacy-block.cjs');
+    const payload = (patch) => ({
+      cwd: root,
+      session_id: 'session-a',
+      hook_event_name: 'PreToolUse',
+      tool_name: 'apply_patch',
+      tool_input: { patch }
+    });
+
+    const harmless = runHook(
+      block,
+      root,
+      payload('*** Begin Patch\n*** Update File: README.md\n+Document `.env` setup.\n*** End Patch\n')
+    );
+    assert.equal(harmless.stdout, '');
+
+    for (const patch of [
+      '*** Begin Patch\n*** Update File: .env\n+SECRET=x\n*** End Patch\n',
+      '*** Begin Patch\n*** Update File: README.md\n*** Move to: credentials.json\n*** End Patch\n'
+    ]) {
+      const denied = runHook(block, root, payload(patch));
+      assert.equal(JSON.parse(denied.stdout).hookSpecificOutput.permissionDecision, 'deny');
+    }
+  });
+});
+
+test('Codex inspect hook scans native shell commands and structured paths', () => {
+  inHookFixture((root, hooks) => {
+    const inspect = path.join(hooks, 'inspect-block.cjs');
+    const payload = (command) => ({
+      cwd: root,
+      session_id: 'session-a',
+      hook_event_name: 'PreToolUse',
+      tool_name: 'Bash',
+      tool_input: { command }
+    });
+
+    for (const command of [
+      'rg secret node_modules',
+      "sed -n '1,20p' dist/bundle.js",
+      "rg --glob '**/*' symbol src"
+    ]) {
+      const result = runHook(inspect, root, payload(command));
+      assert.equal(result.status, 2, command);
+      assert.match(result.stderr, /SCOPE LIMIT EXCEEDED/);
+    }
+
+    const normal = runHook(inspect, root, payload('rg symbol src packages'));
+    assert.equal(normal.status, 0);
+
+    const structured = runHook(inspect, root, {
+      ...payload(''),
+      tool_name: 'mcp__filesystem__read_file',
+      tool_input: { path: 'coverage/index.html' }
+    });
+    assert.equal(structured.status, 2);
+  });
+});
+
+test('Codex task scaffold hook blocks apply_patch Add File with stderr guidance', () => {
+  inHookFixture((root, hooks) => {
+    const result = runHook(path.join(hooks, 'task-scaffold-guard.cjs'), root, {
+      cwd: root,
+      session_id: 'session-a',
+      hook_event_name: 'PreToolUse',
+      tool_name: 'apply_patch',
+      tool_input: {
+        command: '*** Begin Patch\n*** Add File: specs/auth/tasks/task-R0-01-auth.md\n+x\n*** End Patch\n'
+      }
+    });
+
+    assert.equal(result.status, 2);
+    assert.match(result.stderr, /TASK SCAFFOLD REQUIRED/);
+    assert.match(result.stderr, /node \.codex\/scripts\/spec-scaffold\.cjs auth/);
+  });
+});
+
+test('Codex completion gate cannot be bypassed from a nested cwd', () => {
+  inHookFixture((root, hooks) => {
+    const nested = path.join(root, 'packages', 'app');
+    const feature = path.join(root, 'specs', 'auth');
+    const taskPath = 'tasks/task-R0-01-auth.md';
+    fs.mkdirSync(path.join(feature, 'tasks'), { recursive: true });
+    fs.mkdirSync(nested, { recursive: true });
+    const spec = {
+      status: 'in_progress',
+      task_registry: {
+        [taskPath]: { status: 'pending', completed_at: null }
+      }
+    };
+    fs.writeFileSync(path.join(feature, 'spec.json'), `${JSON.stringify(spec)}\n`);
+    fs.writeFileSync(path.join(feature, taskPath), 'Status: pending\n');
+    const gate = path.join(hooks, 'spec-gate.cjs');
+    const payload = {
+      cwd: nested,
+      session_id: 'session-a',
+      hook_event_name: 'Stop',
+      stop_hook_active: false,
+      last_assistant_message: 'done'
+    };
+
+    const seeded = runHook(gate, nested, payload);
+    assert.equal(seeded.status, 0);
+    assert.equal(seeded.stdout, '');
+
+    spec.task_registry[taskPath] = {
+      status: 'done',
+      completed_at: '2026-07-29T10:00:00.000Z'
+    };
+    fs.writeFileSync(path.join(feature, 'spec.json'), `${JSON.stringify(spec)}\n`);
+    fs.writeFileSync(path.join(feature, taskPath), 'Status: done\n');
+
+    const blocked = runHook(gate, nested, payload);
+    assert.equal(blocked.status, 0);
+    assert.equal(JSON.parse(blocked.stdout).decision, 'block');
+    assert.match(JSON.parse(blocked.stdout).reason, /verification receipt/);
+  });
+});
+
+test('Codex state hook persists direct native event fields at project root', () => {
+  inHookFixture((root, hooks) => {
+    const nested = path.join(root, 'packages', 'app');
+    fs.mkdirSync(nested, { recursive: true });
+    const state = path.join(hooks, 'state.cjs');
+    const planResult = runHook(state, nested, {
+      cwd: nested,
+      session_id: 'session-a',
+      hook_event_name: 'PostToolUse',
+      tool_name: 'update_plan',
+      tool_input: {
+        plan: [
+          { step: 'Implement native hooks', status: 'completed' },
+          { step: 'Run sandbox smoke', status: 'in_progress' }
+        ]
+      },
+      tool_response: { ok: true }
+    });
+    assert.equal(planResult.status, 0);
+
+    const agentResult = runHook(state, nested, {
+      cwd: nested,
+      session_id: 'session-a',
+      hook_event_name: 'SubagentStop',
+      agent_id: 'agent-1',
+      agent_type: 'test_runner',
+      last_assistant_message: 'Native hook tests passed.'
+    });
+    assert.equal(agentResult.status, 0);
+
+    const sessionAState = codexStateDir(root, 'session-a');
+    const data = JSON.parse(fs.readFileSync(path.join(sessionAState, 'data.json'), 'utf8'));
+    assert.deepEqual(data.todos.map(({ content, status }) => ({ content, status })), [
+      { content: 'Implement native hooks', status: 'completed' },
+      { content: 'Run sandbox smoke', status: 'in_progress' }
+    ]);
+    assert.equal(data.agentResults[0].message, 'Native hook tests passed.');
+    assert.equal(fs.existsSync(path.join(nested, '.codex')), false);
+
+    const sessionB = runHook(state, nested, {
+      cwd: nested,
+      session_id: 'session-b',
+      hook_event_name: 'PostToolUse',
+      tool_name: 'update_plan',
+      tool_input: { plan: [{ step: 'Independent task', status: 'in_progress' }] },
+      tool_response: { ok: true }
+    });
+    assert.equal(sessionB.status, 0);
+    const sessionBState = codexStateDir(root, 'session-b');
+    const dataB = JSON.parse(fs.readFileSync(path.join(sessionBState, 'data.json'), 'utf8'));
+    assert.deepEqual(dataB.todos.map(({ content }) => content), ['Independent task']);
+    assert.notEqual(sessionAState, sessionBState);
+
+    const resumeA = runHook(state, nested, {
+      cwd: nested,
+      session_id: 'session-a',
+      hook_event_name: 'SessionStart',
+      source: 'resume'
+    });
+    assert.match(resumeA.stdout, /Implement native hooks/);
+    assert.doesNotMatch(resumeA.stdout, /Independent task/);
+
+    const missingSession = runHook(state, nested, {
+      cwd: nested,
+      hook_event_name: 'PostToolUse',
+      tool_name: 'update_plan',
+      tool_input: { plan: [{ step: 'Must not persist', status: 'in_progress' }] }
+    });
+    assert.equal(missingSession.status, 0);
+    assert.equal(codexStateDir(root, ''), null);
+  });
+});