@haposoft/cafekit 0.14.2 → 0.15.1

package/src/codex/hooks/privacy-approval.cjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+'use strict';
+
+const {
+  APPROVAL_PREFIX,
+  approvePending,
+  cleanup
+} = require('./lib/privacy-state.cjs');
+const {
+  getHookContext,
+  readPayload
+} = require('./lib/hook-context.cjs');
+
+function context(message) {
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'UserPromptSubmit',
+      additionalContext: message
+    }
+  })}\n`);
+}
+
+try {
+  const data = readPayload();
+  if (!data) process.exit(0);
+  const { projectRoot } = getHookContext(data);
+  const prompt = String(data.prompt || '').trim();
+  cleanup(projectRoot);
+
+  if (!prompt.startsWith(APPROVAL_PREFIX)) process.exit(0);
+  if (!data.session_id) {
+    context('CafeKit privacy approval rejected: this hook invocation had no Codex session ID.');
+    process.exit(0);
+  }
+  const requestId = prompt.slice(APPROVAL_PREFIX.length);
+  if (`${APPROVAL_PREFIX}${requestId}` !== prompt || !/^[a-f0-9]{24}$/.test(requestId)) {
+    context('CafeKit privacy approval rejected: the prompt did not exactly match a pending request.');
+    process.exit(0);
+  }
+
+  const result = approvePending({
+    projectRoot,
+    sessionId: data.session_id,
+    requestId
+  });
+  if (!result.ok) {
+    context('CafeKit privacy approval rejected: request missing, expired, consumed, or from another session.');
+    process.exit(0);
+  }
+
+  context(
+    `User approved one retry for the pending sensitive access (${result.displayName}). ` +
+    `The token is session-bound, path-bound, tool-bound, time-limited, and consumed atomically.`
+  );
+  process.exit(0);
+} catch {
+  context('CafeKit privacy approval failed safely; no token was issued.');
+  process.exit(0);
+}

package/src/codex/hooks/privacy-block.cjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  APPROVAL_PREFIX,
+  createPending,
+  consumeToken
+} = require('./lib/privacy-state.cjs');
+const {
+  getHookContext,
+  readPayload
+} = require('./lib/hook-context.cjs');
+
+const RESTRICTED = [
+  /^\.env(?:[.\[*?{]|$)/i,
+  /^credentials/i,
+  /secrets?\.(ya?ml|json)$/i,
+  /\.pem$/i,
+  /\.key$/i,
+  /\.p12$/i,
+  /\.pfx$/i,
+  /^id_(rsa|ed25519|ecdsa|dsa)$/i,
+  /\.netrc$/i,
+  /\.pgpass$/i,
+  /kubeconfig/i,
+  /\.keystore$/i,
+  /\.jks$/i,
+  /auth\.json$/i,
+  /token(s)?\.json$/i
+];
+
+const EXEMPT = [/\.env\.(example|sample|template|test)$/i];
+
+function isPathKey(key) {
+  return /^(?:file_?paths?|paths?|search_?paths?|director(?:y|ies)|cwd|root|locations?)$/i
+    .test(key);
+}
+
+function matchesAny(filePath, rules) {
+  const base = path.basename(filePath);
+  return rules.some((rule) => rule.test(base) || rule.test(filePath));
+}
+
+function isSafe(filePath) {
+  return matchesAny(filePath, EXEMPT);
+}
+
+function isSensitive(filePath) {
+  return matchesAny(filePath, RESTRICTED);
+}
+
+function resolveTarget(filePath, cwd) {
+  try {
+    const requested = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+    return fs.realpathSync(requested);
+  } catch {
+    return null;
+  }
+}
+
+function extractCommandPaths(command) {
+  const paths = new Set();
+  for (const token of String(command).split(/[\s|;&<>"']+/).filter(Boolean)) {
+    const cleaned = token.replace(/^["'()`]+|["'(),:]+$/g, '');
+    for (const candidate of cleaned.split('=')) {
+      const value = candidate.replace(/^["'()`]+|["'(),:]+$/g, '');
+      if (value && (isSensitive(value) || isSafe(value))) paths.add(value);
+    }
+  }
+  return [...paths];
+}
+
+function extractPatchPaths(patch) {
+  return [...String(patch).matchAll(
+    /^\*\*\* (?:(?:Add|Update|Delete) File:|Move to:)\s+(.+)$/gm
+  )]
+    .map((match) => match[1].trim())
+    .filter(Boolean);
+}
+
+function shellInput(input) {
+  if (typeof input?.command === 'string') return input.command;
+  if (typeof input?.cmd === 'string') return input.cmd;
+  return '';
+}
+
+function patchInput(input) {
+  if (typeof input === 'string') return input;
+  for (const key of ['command', 'patch', 'input']) {
+    if (typeof input?.[key] === 'string') return input[key];
+  }
+  return '';
+}
+
+function collectPathValues(value, key, out) {
+  if (typeof value === 'string' && isPathKey(key)) {
+    out.push(value);
+    return;
+  }
+  if (Array.isArray(value)) {
+    if (isPathKey(key)) out.push(...value.filter((item) => typeof item === 'string'));
+    return;
+  }
+  if (!value || typeof value !== 'object') return;
+  for (const [childKey, childValue] of Object.entries(value)) {
+    collectPathValues(childValue, childKey, out);
+  }
+}
+
+function extractPaths(toolName, input) {
+  const paths = [];
+  collectPathValues(input, '', paths);
+  const normalizedTool = String(toolName).toLowerCase();
+  if (['bash', 'exec_command', 'shell'].includes(normalizedTool)) {
+    paths.push(...extractCommandPaths(shellInput(input)));
+  } else if (['apply_patch', 'edit', 'write'].includes(normalizedTool)) {
+    paths.push(...extractPatchPaths(patchInput(input)));
+  }
+  return [...new Set(paths.filter(Boolean))];
+}
+
+function sensitiveRequest(filePath, cwd) {
+  const target = resolveTarget(filePath, cwd);
+  if (target) {
+    if (isSensitive(target) && !isSafe(target)) return true;
+    if (isSafe(target)) return false;
+  }
+  return !isSafe(filePath) && isSensitive(filePath);
+}
+
+function sensitivePaths(toolName, input, cwd) {
+  return extractPaths(toolName, input)
+    .filter((filePath) => sensitiveRequest(filePath, cwd));
+}
+
+function deny(reason) {
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason
+    }
+  })}\n`);
+}
+
+try {
+  const data = readPayload();
+  if (!data) process.exit(0);
+  const { projectRoot, sessionCwd, runtime } = getHookContext(data);
+  if (runtime.privacyBlock === false) process.exit(0);
+
+  const filePaths = sensitivePaths(data.tool_name || '', data.tool_input || {}, sessionCwd);
+  if (filePaths.length === 0) process.exit(0);
+  if (!data.session_id) {
+    deny(
+      'Sensitive file access denied because this hook invocation had no Codex session ID. ' +
+      'No approval request or token was created.'
+    );
+    process.exit(0);
+  }
+  const tokenInput = {
+    projectRoot,
+    sessionCwd,
+    sessionId: data.session_id,
+    filePaths,
+    toolName: data.tool_name
+  };
+  if (consumeToken(tokenInput)) process.exit(0);
+
+  const pending = createPending(tokenInput);
+  deny(
+    `Sensitive file access denied: ${pending.displayName}. ` +
+    `If you approve exactly one retry in this Codex session, send this exact user prompt: ` +
+    `${APPROVAL_PREFIX}${pending.requestId}`
+  );
+  process.exit(0);
+} catch {
+  deny('Sensitive access could not be evaluated safely. No file content was read or logged.');
+  process.exit(0);
+}

package/src/codex/hooks/rules.cjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const {
+  atomicWrite,
+  getHookContext,
+  logCrash,
+  readPayload,
+  resolveProjectPath
+} = require('./lib/hook-context.cjs');
+
+const COOLDOWN_MS = 5 * 60 * 1000;
+
+function cooldownFile(projectRoot, sessionId) {
+  const key = crypto.createHash('sha256')
+    .update(String(sessionId || 'unknown'))
+    .digest('hex')
+    .slice(0, 16);
+  return path.join(projectRoot, '.codex', 'hooks', '.logs', `rules-${key}.json`);
+}
+
+function recentlyInjected(file) {
+  try {
+    const state = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return Date.now() - Number(state.ts || 0) < COOLDOWN_MS;
+  } catch {
+    return false;
+  }
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { projectRoot, runtime } = getHookContext(payload);
+  const cache = cooldownFile(projectRoot, payload.session_id);
+  if (recentlyInjected(cache)) process.exit(0);
+
+  const respondLang = runtime.locale?.responseLanguage || '';
+  const thinkLang = runtime.locale?.thinkingLanguage || (respondLang ? 'en' : '');
+  const plansPath = resolveProjectPath(projectRoot, runtime.paths?.plans, 'plans');
+  const docsPath = resolveProjectPath(projectRoot, runtime.paths?.docs, 'docs');
+  const lines = [];
+
+  if ((thinkLang && thinkLang !== respondLang) || respondLang) {
+    lines.push('## Language');
+    if (thinkLang && thinkLang !== respondLang) {
+      lines.push(`- Thinking: Use ${thinkLang} for reasoning.`);
+    }
+    if (respondLang) lines.push(`- Response: Respond in ${respondLang}.`);
+    lines.push('');
+  }
+
+  lines.push(
+    '## Rules',
+    `- Markdown: Plans → "${plansPath}/" | Docs → "${docsPath}/"`,
+    '- Do not create markdown outside those directories unless explicitly asked.',
+    `- docs.maxLoc: ${runtime.docs?.maxLoc || 800} lines per doc file`,
+    '- Follow YAGNI · KISS · DRY.',
+    '- Reports: concise; unresolved questions last.',
+    '',
+    '## Skill Routing',
+    '- Choose skills using `.codex/rules/skill-workflow-routing.md` and `.codex/rules/skill-domain-routing.md`.',
+    '- Inspect installed skills with `node .codex/scripts/generate-skill-catalog.cjs --skills` when needed.',
+    '- Explicit user requests override routing suggestions.',
+    '',
+    '## Modularization',
+    '- Consider splitting code files over 200 lines at real concern boundaries.',
+    '- Check existing modules first; use descriptive names and comments.',
+    '- Skip modularization for markdown, plain text, shell, config, and env files.'
+  );
+
+  process.stdout.write(`${lines.join('\n')}\n`);
+  atomicWrite(cache, `${JSON.stringify({ ts: Date.now() })}\n`);
+} catch (error) {
+  logCrash('rules', error);
+}

package/src/codex/hooks/session.cjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const {
+  getHookContext,
+  logCrash,
+  readPayload
+} = require('./lib/hook-context.cjs');
+const { clearState } = require('./lib/privacy-state.cjs');
+
+function readPackage(projectRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function detectProjectType(projectRoot, pkg) {
+  if (
+    fs.existsSync(path.join(projectRoot, 'pnpm-workspace.yaml'))
+    || fs.existsSync(path.join(projectRoot, 'lerna.json'))
+    || pkg.workspaces
+  ) return 'monorepo';
+  if (pkg.main || pkg.exports || pkg.module) return 'library';
+  return 'app';
+}
+
+function detectPackageManager(projectRoot) {
+  const locks = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['yarn.lock', 'yarn'],
+    ['bun.lockb', 'bun'],
+    ['bun.lock', 'bun'],
+    ['package-lock.json', 'npm']
+  ];
+  return locks.find(([file]) => fs.existsSync(path.join(projectRoot, file)))?.[1] || '';
+}
+
+function detectFramework(pkg) {
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const candidates = [
+    ['next', 'next'],
+    ['nuxt', 'nuxt'],
+    ['@sveltejs/kit', 'sveltekit'],
+    ['react', 'react'],
+    ['vue', 'vue'],
+    ['svelte', 'svelte'],
+    ['express', 'express'],
+    ['fastify', 'fastify'],
+    ['hono', 'hono']
+  ];
+  return candidates.find(([dependency]) => deps[dependency])?.[1] || '';
+}
+
+function gitBranch(projectRoot) {
+  try {
+    return execFileSync('git', ['branch', '--show-current'], {
+      cwd: projectRoot,
+      encoding: 'utf8',
+      timeout: 3000,
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { projectRoot, runtime, sessionCwd } = getHookContext(payload);
+  const pkg = readPackage(projectRoot);
+  const configured = runtime.project || {};
+  const projectType = configured.type && configured.type !== 'auto'
+    ? configured.type
+    : detectProjectType(projectRoot, pkg);
+  const packageManager = configured.packageManager && configured.packageManager !== 'auto'
+    ? configured.packageManager
+    : detectPackageManager(projectRoot);
+  const framework = configured.framework && configured.framework !== 'auto'
+    ? configured.framework
+    : detectFramework(pkg);
+  const branch = gitBranch(projectRoot);
+
+  // Approval tokens never survive a session boundary or compaction.
+  clearState(projectRoot);
+
+  const parts = [
+    projectType && `Type: ${projectType}`,
+    packageManager && `PM: ${packageManager}`,
+    framework && `Framework: ${framework}`,
+    branch && `Branch: ${branch}`
+  ].filter(Boolean);
+  process.stdout.write(
+    `Session ${payload.source || 'unknown'}. ${parts.join(' | ') || 'No project info detected.'}\n`
+  );
+
+  if (sessionCwd !== projectRoot) {
+    process.stdout.write(
+      `CafeKit project root: ${projectRoot} (session working directory: ${sessionCwd}).\n`
+    );
+  }
+  if (payload.source === 'compact') {
+    process.stdout.write(
+      'Session compacted. Pending CafeKit privacy approvals were invalidated; request fresh user approval if needed.\n'
+    );
+  }
+} catch (error) {
+  logCrash('session', error);
+}

package/src/codex/hooks/spec-gate.cjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  atomicWrite,
+  getHookContext,
+  logCrash,
+  readPayload
+} = require('./lib/hook-context.cjs');
+const { checkReceipt } = require('./lib/spec-receipt.cjs');
+const { findActiveSpec, taskStatusMap } = require('./lib/spec-utils.cjs');
+
+try {
+  const payload = readPayload();
+  if (!payload || payload.stop_hook_active === true) process.exit(0);
+  const { projectRoot, runtime } = getHookContext(payload);
+  if (runtime.spec?.completion_gate === false) process.exit(0);
+  const active = findActiveSpec(projectRoot, runtime);
+  if (!active) process.exit(0);
+
+  const registry = active.spec.task_registry || {};
+  const currentStatuses = taskStatusMap(active.spec);
+  const cacheFile = path.join(
+    projectRoot,
+    '.codex',
+    'hooks',
+    '.logs',
+    'spec-gate-last.json'
+  );
+  const cacheExists = fs.existsSync(cacheFile);
+  let cache = {};
+  if (cacheExists) {
+    try { cache = JSON.parse(fs.readFileSync(cacheFile, 'utf8')); } catch { cache = {}; }
+  }
+
+  if (!cacheExists) {
+    cache[active.featureName] = currentStatuses;
+    atomicWrite(cacheFile, `${JSON.stringify(cache)}\n`);
+    process.exit(0);
+  }
+
+  const previous = cache[active.featureName] || {};
+  const newlyDone = Object.keys(registry).filter((taskPath) => (
+    currentStatuses[taskPath] === 'done' && previous[taskPath] !== 'done'
+  ));
+  const featureDir = path.join(active.specsDir, active.featureName);
+  const failures = newlyDone
+    .map((taskPath) => ({
+      taskPath,
+      failures: checkReceipt(featureDir, taskPath, registry[taskPath])
+    }))
+    .filter((result) => result.failures.length);
+
+  const next = { ...previous, ...currentStatuses };
+  for (const result of failures) {
+    if (previous[result.taskPath] === undefined) delete next[result.taskPath];
+    else next[result.taskPath] = previous[result.taskPath];
+  }
+  cache[active.featureName] = next;
+  atomicWrite(cacheFile, `${JSON.stringify(cache)}\n`);
+
+  if (!failures.length) process.exit(0);
+  const lines = [
+    `Completion gate: ${failures.length} newly-done task(s) lack a verification receipt.`
+  ];
+  for (const result of failures) {
+    lines.push(
+      `- \`${result.taskPath}\`: failed check(s) ${result.failures.join(', ')}`,
+      `  Add \`Verification: PASS\`, commands, and successful outcomes under \`## Evidence\` in \`specs/${active.featureName}/${result.taskPath}\`, then re-sync spec.json.`
+    );
+  }
+  process.stdout.write(`${JSON.stringify({
+    decision: 'block',
+    reason: lines.slice(0, 8).join('\n')
+  })}\n`);
+} catch (error) {
+  logCrash('spec-gate', error);
+}

package/src/codex/hooks/spec-state.cjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const {
+  atomicWrite,
+  getHookContext,
+  logCrash,
+  readPayload
+} = require('./lib/hook-context.cjs');
+const { findActiveSpec } = require('./lib/spec-utils.cjs');
+
+function cacheFile(projectRoot, sessionId) {
+  const key = crypto.createHash('sha256')
+    .update(String(sessionId || 'unknown'))
+    .digest('hex')
+    .slice(0, 16);
+  return path.join(projectRoot, '.codex', 'hooks', '.logs', `tollgate-${key}.txt`);
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { projectRoot, runtime } = getHookContext(payload);
+  if (runtime.spec?.tollgate === false) process.exit(0);
+  const active = findActiveSpec(projectRoot, runtime);
+  if (!active) process.exit(0);
+
+  const phase = active.spec.current_phase || active.spec.phase || 'unknown';
+  const tasks = Object.entries(active.spec.task_registry || {});
+  const counts = tasks.reduce((result, [, task]) => {
+    const status = task?.status || 'pending';
+    result[status] = (result[status] || 0) + 1;
+    return result;
+  }, {});
+  const statuses = new Map(tasks.map(([taskPath, task]) => [
+    taskPath,
+    task?.status || 'pending'
+  ]));
+  const next = tasks.find(([, task]) => (
+    (task?.status || 'pending') === 'pending'
+    && (task?.dependencies || []).every((dependency) => statuses.get(dependency) === 'done')
+  ));
+  const stateKey = `${active.featureName}|${phase}|${counts.done || 0}/${tasks.length}`;
+  const cache = cacheFile(projectRoot, payload.session_id);
+  let previous = '';
+  try { previous = fs.readFileSync(cache, 'utf8').trim(); } catch { /* first run */ }
+
+  if (previous === stateKey) {
+    process.stdout.write(
+      `> Spec \`${active.featureName}\` @ \`${phase}\` `
+      + `(${counts.done || 0}/${tasks.length} tasks done). Tollgate active.\n`
+    );
+    process.exit(0);
+  }
+
+  atomicWrite(cache, `${stateKey}\n`);
+  const lines = [
+    `### Spec state changed: \`${active.featureName}\``,
+    `- Phase: \`${phase}\` | Tasks: ${counts.done || 0} done / ${tasks.length} total`
+  ];
+  if (next) lines.push(`- Next unblocked: \`${next[0]}\``);
+  lines.push(
+    '- Sync `spec.json` and the task file only after verified work.',
+    `- Validate with \`node .codex/scripts/validate-spec-output.cjs specs/${active.featureName}\`.`,
+    '- The Stop completion gate checks receipts for newly-done tasks.'
+  );
+  process.stdout.write(`${lines.join('\n')}\n`);
+} catch (error) {
+  logCrash('spec-state', error);
+}