@haposoft/cafekit 0.14.2 → 0.15.1

package/src/codex/hooks/state.cjs

@@ -0,0 +1,157 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getHookContext,
+  logCrash,
+  readPayload
+} = require('./lib/hook-context.cjs');
+const {
+  archive,
+  readData,
+  refreshGit,
+  stateDir,
+  withStateLock,
+  writeData
+} = require('./lib/state-store.cjs');
+
+const EXPIRY_MS = 7 * 24 * 60 * 60 * 1000;
+
+function summary(value, limit = 600) {
+  if (value === null || value === undefined) return '';
+  let text = '';
+  if (typeof value === 'string') {
+    text = value;
+  } else if (typeof value === 'object') {
+    const preferred = value.message ?? value.output ?? value.result ?? value.content;
+    text = typeof preferred === 'string' ? preferred : JSON.stringify(value);
+  } else {
+    text = String(value);
+  }
+  const clean = text.replace(/\0/g, '').trim();
+  return clean.length > limit ? `${clean.slice(0, limit)}…` : clean;
+}
+
+function normalizeTodos(items) {
+  if (!Array.isArray(items)) return [];
+  return items.map((item, index) => ({
+    id: String(item?.id ?? item?.task_id ?? item?.taskId ?? index),
+    content: summary(item?.step ?? item?.content ?? item?.subject ?? item?.title, 240),
+    status: String(item?.status || 'pending')
+  })).filter((item) => item.content);
+}
+
+function updateTaskState(data, input, response) {
+  const completeList = input.plan ?? input.todos ?? input.tasks
+    ?? response?.plan ?? response?.todos ?? response?.tasks;
+  if (Array.isArray(completeList)) {
+    data.todos = normalizeTodos(completeList);
+    return;
+  }
+
+  const id = input.task_id ?? input.taskId ?? input.id;
+  const content = summary(input.step ?? input.content ?? input.subject ?? input.title, 240);
+  const status = input.status;
+  if (!id && !content) return;
+  const todos = Array.isArray(data.todos) ? data.todos : [];
+  const index = todos.findIndex((todo) => (
+    (id !== undefined && String(todo.id) === String(id))
+    || (content && todo.content === content)
+  ));
+  const next = {
+    id: String(id ?? content),
+    content: content || todos[index]?.content || `Task ${id}`,
+    status: String(status || todos[index]?.status || 'pending')
+  };
+  if (index >= 0) todos[index] = next;
+  else todos.push(next);
+  data.todos = todos;
+}
+
+function isTrackedTool(toolName) {
+  const name = String(toolName || '').toLowerCase();
+  return name === 'agent'
+    || name === 'spawn_agent'
+    || name === 'update_plan'
+    || name.includes('task')
+    || name.includes('todo');
+}
+
+function loadPrevious(projectRoot, sessionId) {
+  try {
+    const dir = stateDir(projectRoot, sessionId);
+    if (!dir) return '';
+    const file = path.join(dir, 'latest.md');
+    if (!fs.existsSync(file)) return '';
+    const text = fs.readFileSync(file, 'utf8');
+    const generated = text.match(/<!-- Generated: (.+?) -->/)?.[1];
+    if (!generated || Date.now() - Date.parse(generated) > EXPIRY_MS) return '';
+    return text;
+  } catch {
+    return '';
+  }
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { projectRoot } = getHookContext(payload);
+  const event = payload.hook_event_name || '';
+  const sessionId = payload.session_id;
+
+  if (event === 'SessionStart') {
+    const previous = loadPrevious(projectRoot, sessionId);
+    if (previous) {
+      process.stdout.write(
+        `=== Prior Execution Context ===\n${previous.trim()}\n=== End of Prior Context ===\n`
+      );
+    }
+    process.exit(0);
+  }
+
+  if (event === 'PostToolUse') {
+    const toolName = payload.tool_name || '';
+    if (!isTrackedTool(toolName)) process.exit(0);
+    withStateLock(projectRoot, sessionId, (dir) => {
+      const data = readData(dir);
+      const input = payload.tool_input || {};
+      const response = payload.tool_response;
+      updateTaskState(data, input, response);
+      data.lastToolEvent = `${toolName}: ${summary(response) || summary(input)}`.slice(0, 700);
+      refreshGit(data, projectRoot);
+      writeData(dir, data);
+    });
+    process.exit(0);
+  }
+
+  if (event === 'SubagentStop') {
+    withStateLock(projectRoot, sessionId, (dir) => {
+      const data = readData(dir);
+      const id = String(payload.agent_id || 'unknown');
+      data.agentResults = (data.agentResults || [])
+        .filter((agent) => String(agent.id) !== id);
+      data.agentResults.push({
+        id,
+        type: String(payload.agent_type || 'unknown'),
+        message: summary(payload.last_assistant_message)
+      });
+      refreshGit(data, projectRoot);
+      writeData(dir, data);
+    });
+    process.exit(0);
+  }
+
+  if (event === 'Stop') {
+    withStateLock(projectRoot, sessionId, (dir) => {
+      const data = readData(dir);
+      data.lastAssistant = summary(payload.last_assistant_message);
+      refreshGit(data, projectRoot);
+      writeData(dir, data);
+      archive(dir);
+    });
+  }
+} catch (error) {
+  logCrash('state', error);
+}

package/src/codex/hooks/task-scaffold-guard.cjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getHookContext,
+  logCrash,
+  readPayload
+} = require('./lib/hook-context.cjs');
+
+function addedFiles(toolName, input) {
+  if (toolName === 'Write') {
+    return [input.file_path || input.filePath || input.path || ''].filter(Boolean);
+  }
+  if (toolName !== 'apply_patch') return [];
+  const patch = typeof input.command === 'string'
+    ? input.command
+    : typeof input.patch === 'string' ? input.patch : '';
+  return [...patch.matchAll(/^\*\*\* Add File:\s+(.+)$/gm)]
+    .map((match) => match[1].trim());
+}
+
+function projectRelative(filePath, projectRoot, sessionCwd) {
+  const absolute = path.isAbsolute(filePath)
+    ? path.normalize(filePath)
+    : path.resolve(sessionCwd, filePath);
+  return path.relative(projectRoot, absolute).replace(/\\/g, '/');
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { projectRoot, runtime, sessionCwd } = getHookContext(payload);
+  const candidates = addedFiles(payload.tool_name || '', payload.tool_input || {});
+  const taskFile = candidates
+    .map((requested) => ({
+      requested,
+      relative: projectRelative(requested, projectRoot, sessionCwd)
+    }))
+    .find(({ relative }) => (
+      /^specs\/[^/]+\/tasks\/task-[^/]+\.md$/.test(relative)
+    ));
+  if (!taskFile) process.exit(0);
+  if (runtime.spec?.scaffold_guard === false) process.exit(0);
+
+  const scaffold = path.join(projectRoot, '.codex', 'scripts', 'spec-scaffold.cjs');
+  if (!fs.existsSync(scaffold)) process.exit(0);
+
+  const feature = taskFile.relative.split('/')[1];
+  const command = sessionCwd === projectRoot
+    ? `node .codex/scripts/spec-scaffold.cjs ${feature}`
+    : `node ${JSON.stringify(scaffold)} ${feature}`;
+  process.stderr.write(
+    'TASK SCAFFOLD REQUIRED: task files must be generated, not hand-written.\n'
+    + `Blocked Write: ${taskFile.requested}\n\n`
+    + 'Generate the stubs, then fill their {{...}} placeholders with apply_patch:\n'
+    + `  ${command} --tasks "R0-01-slug,R1-01-slug,..." --tasks-only\n`
+  );
+  process.exit(2);
+} catch (error) {
+  logCrash('task-scaffold-guard', error);
+}

package/src/codex/hooks.json

@@ -0,0 +1,122 @@
+{
+  "description": "CafeKit project-local lifecycle hooks for Codex CLI. Review and trust with /hooks.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/session.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/session.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/docs-sync.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/docs-sync.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\""
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/agent.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/agent.cjs\""
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/privacy-approval.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/privacy-approval.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/rules.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/rules.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/spec-state.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/spec-state.cjs\""
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|apply_patch|Edit|Write|Read|Glob|Grep|mcp__.*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/privacy-block.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/privacy-block.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/inspect-block.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/inspect-block.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/task-scaffold-guard.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/task-scaffold-guard.cjs\""
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Agent|spawn_agent|update_plan|task|Task|TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\""
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/spec-gate.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/spec-gate.cjs\""
+          },
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\""
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\"",
+            "commandWindows": "node \"$(git rev-parse --show-toplevel)/.codex/hooks/state.cjs\""
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/codex/rules/hook-protocols.md

@@ -0,0 +1,32 @@
+# Hook Protocols
+
+Hooks are instruction boundaries. Do not bypass or work around them.
+
+## Privacy Block Hook
+
+Codex cannot pause a blocked tool call for an interactive permission question.
+CafeKit therefore denies the sensitive access and emits one exact approval
+phrase tied to the current session, requested path, tool, and expiry.
+
+Required flow:
+
+1. Stop the blocked access and show the user the hook's reason.
+2. Ask the user to send the exact approval phrase if they want one retry.
+3. Do not write, repeat as a user message, or otherwise simulate that phrase.
+4. Retry only after a later real user prompt exactly matches it.
+5. Use the resulting token once, only for the originally blocked operation.
+
+Never use another command, path, encoding, subprocess, or side channel to read a
+privacy-blocked file without that explicit approval.
+
+## State And Spec Hooks
+
+- If a hook reports state drift, run the appropriate sync or audit flow before continuing.
+- If a hook rejects task completion, keep the task `in_progress` or `blocked` until proof exists.
+- Do not mark a task `done` unless the matching task file contains a valid verification receipt.
+
+## Hook Failure Handling
+
+- Treat hook errors as blockers when they affect safety, privacy, or task state.
+- Record the blocker in the task or spec state when relevant.
+- If hook output is malformed, stop and report the exact failure instead of guessing.

package/src/codex/rules/state-sync.md

@@ -0,0 +1,41 @@
+# Tollgate Protocol (State Sync)
+
+## Sources Of Truth
+
+Spec-driven work persists state in two synchronized layers:
+
+1. `spec.json` tracks phase, overall status, and `task_registry`.
+2. `tasks/task-*.md` tracks the human-readable checklist and verification receipt.
+
+## Sync-back Rule
+
+Before reporting a task completed or blocked:
+
+### On success
+
+1. Update `spec.json` only after verification. Keep `current_phase`,
+   `task_files`, status, timestamps, and the matching `task_registry` entry accurate.
+2. Update the matching task Markdown status, checkboxes, completion criteria,
+   and `## Evidence` receipt from the current verification run.
+3. Update native plan or task state when the active Codex session provides it,
+   but never use chat-only state as a substitute for the files above.
+
+### On block after repeated attempts
+
+1. Set the spec and matching registry entry to `blocked`, with the root cause and timestamp.
+2. Mark the task Markdown `blocked` and record the evidence.
+3. Tell the user or orchestrator exactly what external input or state change is required.
+
+New specs use `in_progress`; legacy `in-progress` may be read but not emitted.
+Never let `task_registry` disagree with its task Markdown file.
+
+## Completion Gate
+
+The Stop hook checks newly completed tasks. Each requires:
+
+- `Status: done`;
+- a non-placeholder `## Evidence` section with a command block or PASS/FAIL result;
+- a non-empty `task_registry[path].completed_at`.
+
+The first run seeds completion history without blocking. Humans can disable the
+gate with `"spec": { "completion_gate": false }` in `.codex/runtime.json`.

package/src/codex/runtime.json

@@ -0,0 +1,28 @@
+{
+  "privacyBlock": true,
+  "inspect": {
+    "enabled": true
+  },
+  "docs": {
+    "maxLoc": 800
+  },
+  "paths": {
+    "docs": "docs",
+    "specs": "specs",
+    "plans": "plans"
+  },
+  "spec": {
+    "scaffold_guard": true,
+    "completion_gate": true,
+    "tollgate": true
+  },
+  "develop": {
+    "parallel": true
+  },
+  "locale": {
+    "thinkingLanguage": null,
+    "responseLanguage": null
+  },
+  "hooks": {},
+  "assertions": []
+}