@haposoft/cafekit 0.14.2 → 0.15.1

package/bin/phases/root-config.js

@@ -4,7 +4,7 @@
  * Ensures the root .gitignore carries CafeKit-managed patterns:
  *  - workflow dirs (plans, shared research)
  *  - install safety artifacts (backup, lock)
- *  - runtime folders (.claude/, .opencode/) — reinstall via
+ *  - runtime folders (.claude/, .opencode/, .codex/, .agents/) — reinstall via
  *    `npx @haposoft/cafekit`; do not commit the local payload
  *
  * Layered with the in-folder `.claude/.gitignore` /
@@ -35,7 +35,9 @@ function ensureGitignore(ctx) {
     '.cafekit.lock',
     // Local runtime payload — reinstall with npx; keep out of git
     '.claude/',
-    '.opencode/'
+    '.opencode/',
+    '.codex/',
+    '.agents/'
   ];
   const prefix = ctx.dryRun ? '[dry-run] ' : '';
 

package/bin/phases/select-platform.js

@@ -22,15 +22,18 @@ const OTHER = '__other__';
  * Read saved locale label from .claude/runtime.json (written by post-install).
  * Returns the freeform label string (e.g. "Tiếng Việt") or null.
  */
-function getInstalledLocale() {
-  const runtimeJson = path.join(process.cwd(), '.claude', 'runtime.json');
-  if (!fs.existsSync(runtimeJson)) return null;
-  try {
-    const data = JSON.parse(fs.readFileSync(runtimeJson, 'utf8'));
-    return (data && data.locale && typeof data.locale.responseLanguage === 'string')
-      ? data.locale.responseLanguage
-      : null;
-  } catch { return null; }
+function getInstalledLocale(platformKeys = getPlatformKeys()) {
+  for (const key of platformKeys) {
+    const runtimeJson = path.join(process.cwd(), PLATFORMS[key].folder, 'runtime.json');
+    if (!fs.existsSync(runtimeJson)) continue;
+    try {
+      const data = JSON.parse(fs.readFileSync(runtimeJson, 'utf8'));
+      if (data && data.locale && typeof data.locale.responseLanguage === 'string') {
+        return data.locale.responseLanguage;
+      }
+    } catch { /* try the next installed runtime */ }
+  }
+  return null;
 }
 
 /** First step: pick the installer/UI language (interactive only). */
@@ -40,7 +43,8 @@ async function selectLanguage(ctx) {
   // ctx at the 'en' default, and patchRuntimeLocale then clobbered the user's
   // responseLanguage on every upgrade.
   if (!ctx.options.lang) {
-    const savedLocale = getInstalledLocale();
+    const requested = (ctx.options.platforms || []).filter((key) => PLATFORMS[key]);
+    const savedLocale = getInstalledLocale(requested.length ? requested : getPlatformKeys());
     if (savedLocale) {
       const code = Object.keys(LANGUAGE_LABELS).find((k) => LANGUAGE_LABELS[k] === savedLocale) || 'en';
       ctx.setLang(code, savedLocale); // updates ctx.t to the saved language
@@ -104,26 +108,67 @@ async function confirmAllDetected(ctx, detected) {
   return r;
 }
 
+function platformNames(platforms) {
+  return platforms.map((key) => PLATFORMS[key].name).join(', ');
+}
+
+function reportInstallMode(ctx) {
+  if (ctx.options.forceOverwrite) {
+    ctx.ui.info(ctx.t('modeForce'));
+  } else if (ctx.dryRun) {
+    ctx.ui.info(ctx.t('modeDryRun'));
+  } else {
+    ctx.ui.info(ctx.t('modeInstall'));
+  }
+}
+
+function cancelSelection(ctx) {
+  ctx.ui.outro(ctx.t('cancelled'));
+  ctx.cancelled = true;
+  return [];
+}
+
+async function promptPlatforms(ctx) {
+  const platforms = await promptPlatformSelection(ctx);
+  return platforms.length > 0 ? platforms : cancelSelection(ctx);
+}
+
 /**
  * Resolve ctx.platforms via detection + prompts. Sets ctx.cancelled on backout.
  * If cafekit.json exists (prior install), reads platform from it to skip prompt.
  * Note: ctx.isUpdate is set later by checkVersions and cannot be used here.
  */
 async function resolvePlatforms(ctx) {
+  const requested = [...new Set((ctx.options.platforms || []).map((key) => key.trim()).filter(Boolean))];
+  if (requested.length > 0) {
+    const unknown = requested.filter((key) => !PLATFORMS[key]);
+    if (unknown.length > 0) {
+      throw new Error(`Unknown platform: ${unknown.join(', ')}. Expected: ${getPlatformKeys().join(', ')}`);
+    }
+    ctx.platforms = requested;
+    ctx.ui.info(ctx.t('installingFor', {
+      names: platformNames(requested)
+    }));
+    warnLegacyClaudeFolder(requested);
+    reportInstallMode(ctx);
+    return ctx;
+  }
+
   // Skip platform prompt when a prior install is detected via cafekit.json
-  const savedPlatform = getInstalledPlatform();
-  if (savedPlatform) {
-    ctx.platforms = [savedPlatform];
-    const platformNames = PLATFORMS[savedPlatform].name;
-    ctx.ui.info(ctx.t('platformKept', { names: platformNames }));
-
-    if (ctx.options.forceOverwrite) {
-      ctx.ui.info(ctx.t('modeForce'));
-    } else if (ctx.dryRun) {
-      ctx.ui.info(ctx.t('modeDryRun'));
-    } else {
-      ctx.ui.info(ctx.t('modeInstall'));
+  const savedPlatforms = getInstalledPlatforms();
+  if (savedPlatforms.length > 0) {
+    let platforms = [...new Set([...savedPlatforms, ...detectPlatforms()])];
+    if (ctx.interactive && platforms.some((key) => !savedPlatforms.includes(key))) {
+      const proceed = await confirmAllDetected(ctx, platforms);
+      if (!proceed) {
+        platforms = await promptPlatforms(ctx);
+        if (ctx.cancelled) return ctx;
+      }
     }
+    ctx.platforms = platforms;
+    ctx.ui.info(ctx.t('platformKept', { names: platformNames(platforms) }));
+
+    reportInstallMode(ctx);
     return ctx;
   }
 
@@ -131,12 +176,8 @@ async function resolvePlatforms(ctx) {
 
   if (platforms.length === 0) {
     if (ctx.interactive) {
-      platforms = await promptPlatformSelection(ctx);
-      if (platforms.length === 0) {
-        ctx.ui.outro(ctx.t('cancelled'));
-        ctx.cancelled = true;
-        return ctx;
-      }
+      platforms = await promptPlatforms(ctx);
+      if (ctx.cancelled) return ctx;
     } else {
       platforms = ['claude'];
       ctx.ui.info('No platform detected; defaulting to Claude Code (.claude/).');
@@ -144,28 +185,17 @@ async function resolvePlatforms(ctx) {
   } else if (platforms.length > 1 && ctx.interactive) {
     const proceed = await confirmAllDetected(ctx, platforms);
     if (!proceed) {
-      platforms = await promptPlatformSelection(ctx);
-      if (platforms.length === 0) {
-        ctx.ui.outro(ctx.t('cancelled'));
-        ctx.cancelled = true;
-        return ctx;
-      }
+      platforms = await promptPlatforms(ctx);
+      if (ctx.cancelled) return ctx;
     }
   }
 
   ctx.platforms = platforms;
 
-  const platformNames = platforms.map((key) => PLATFORMS[key].name).join(', ');
-  ctx.ui.info(ctx.t('installingFor', { names: platformNames }));
+  ctx.ui.info(ctx.t('installingFor', { names: platformNames(platforms) }));
   warnLegacyClaudeFolder(platforms);
 
-  if (ctx.options.forceOverwrite) {
-    ctx.ui.info(ctx.t('modeForce'));
-  } else if (ctx.dryRun) {
-    ctx.ui.info(ctx.t('modeDryRun'));
-  } else {
-    ctx.ui.info(ctx.t('modeInstall'));
-  }
+  reportInstallMode(ctx);
 
   return ctx;
 }
@@ -174,24 +204,28 @@ async function resolvePlatforms(ctx) {
  * Get the installed platform from cafekit.json files.
  * Returns the platform key (e.g. 'claude', 'opencode') or null.
  */
-function getInstalledPlatform() {
-  const claudeJson = path.join(process.cwd(), '.claude', 'cafekit.json');
-  if (fs.existsSync(claudeJson)) {
-    try {
-      const data = JSON.parse(fs.readFileSync(claudeJson, 'utf8'));
-      if (data.platform) return data.platform;
-    } catch { /* ignore */ }
-  }
-
-  const opencodeJson = path.join(process.cwd(), '.opencode', 'cafekit.json');
-  if (fs.existsSync(opencodeJson)) {
+function getInstalledPlatforms() {
+  const installed = [];
+  for (const key of getPlatformKeys()) {
+    const metadataPath = path.join(process.cwd(), PLATFORMS[key].folder, 'cafekit.json');
+    if (!fs.existsSync(metadataPath)) continue;
     try {
-      const data = JSON.parse(fs.readFileSync(opencodeJson, 'utf8'));
-      if (data.platform) return data.platform;
+      const data = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+      const platformKey = data.platform && PLATFORMS[data.platform] ? data.platform : key;
+      if (!installed.includes(platformKey)) installed.push(platformKey);
     } catch { /* ignore */ }
   }
+  return installed;
+}
 
-  return null;
+function getInstalledPlatform() {
+  return getInstalledPlatforms()[0] || null;
 }
 
-module.exports = { selectLanguage, promptPlatformSelection, resolvePlatforms };
+module.exports = {
+  selectLanguage,
+  promptPlatformSelection,
+  resolvePlatforms,
+  getInstalledPlatform,
+  getInstalledPlatforms
+};

package/bin/phases/summary.js

@@ -53,7 +53,12 @@ function printSummary(ctx) {
 
   const lines = [];
   for (const key of platforms) {
-    lines.push(key === 'claude' ? t('nsClaude') : t('nsOpencode'));
+    const messageKey = {
+      claude: 'nsClaude',
+      opencode: 'nsOpencode',
+      codex: 'nsCodex'
+    }[key];
+    if (messageKey) lines.push(t(messageKey));
   }
   // rtk token-saver result (set by phases/setup-rtk.js when setup completed).
   if (ctx.rtkSetupRan) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.14.2",
-  "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
+  "version": "0.15.1",
+  "description": "Native spec-driven workflows for Claude Code, Codex CLI, and OpenCode. Bundles CafeKit skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",
   "private": false,
@@ -34,6 +34,7 @@
     "spec-driven",
     "workflow",
     "claude-code",
+    "codex-cli",
     "ai-coding",
     "specification",
     "requirements",

package/src/claude/scripts/generate-skill-catalog.cjs

@@ -37,9 +37,14 @@ function parseArgs(argv) {
 }
 
 function defaultSkillsRoot() {
-  const installed = path.resolve(process.cwd(), '.claude', 'skills');
-  if (fs.existsSync(installed)) return installed;
-  return path.resolve(__dirname, '..', 'skills');
+  const candidates = [
+    path.resolve(process.cwd(), '.claude', 'skills'),
+    path.resolve(process.cwd(), '.agents', 'skills'),
+    path.resolve(process.cwd(), '.opencode', 'skills'),
+    path.resolve(__dirname, '..', 'skills'),
+    path.resolve(__dirname, '..', '..', '.agents', 'skills')
+  ];
+  return candidates.find((candidate) => fs.existsSync(candidate)) || candidates[0];
 }
 
 function readText(filePath) {

package/src/codex/AGENTS.md

@@ -0,0 +1,30 @@
+# CafeKit for Codex CLI
+
+## Native runtime mapping
+
+- Repository instructions: `AGENTS.md`.
+- CafeKit skills: `.agents/skills/`; invoke explicitly as `$hapo-<name>` or browse with `/skills`.
+- CafeKit agents: native auto-discovered definitions in `.codex/agents/*.toml`.
+- Runtime support: `.codex/rules/`, `.codex/scripts/`, `.codex/references/`, and `.codex/runtime.json`.
+- Lifecycle enforcement: `.codex/hooks.json`. Project hooks run only after the repository and hook definitions are trusted; review them with `/hooks`.
+- Do not create deprecated custom prompts or assume Claude/OpenCode command wrappers exist.
+
+## Operating contract
+
+- Read `README.md` and relevant project instructions before non-trivial work.
+- Choose the matching CafeKit skill before improvising a workflow.
+- Read `.codex/rules/workflow.md`, `.codex/rules/ai-dev-rules.md`, and
+  `.codex/rules/skill-workflow-routing.md` for non-trivial work. Load the other
+  `.codex/rules/*.md` files when their topic applies.
+- Keep scope surgical; prefer YAGNI, KISS, then DRY.
+- Do not claim completion without fresh build, test, runtime, or artifact evidence.
+- For spec tasks, keep `spec.json`, task status, `Completion Criteria`, and `Evidence` synchronized only after verification.
+- Privacy approvals are one request, one session, one retry. Only the user may submit the exact approval phrase emitted by the privacy hook.
+
+## Runtime caveats
+
+- Codex custom agents use snake_case names.
+- When selecting a CafeKit custom role explicitly, call `spawn_agent` with `agent_type`, a unique snake_case `task_name`, `message`, and `fork_turns: "none"`. A full-history fork cannot change agent type.
+- Use Codex-native subagent delegation and task-state tools; do not rely on Claude-only tool labels.
+- The project `.codex/` layer—agents, config, rules, and hooks—loads only after the repository is trusted. Never edit the user's global trust configuration on their behalf.
+- Hooks are guardrails, not a complete security boundary. Hosted tools and untrusted project hooks may not enter the local hook path.

package/src/codex/agents-gitignore

@@ -0,0 +1,11 @@
+# CafeKit skill-local secrets and generated dependencies
+skills/**/.env
+skills/**/.env.*
+!skills/**/.env.example
+!skills/**/.env.sample
+!skills/**/.env.template
+
+skills/**/.venv/
+skills/**/node_modules/
+skills/**/__pycache__/
+skills/**/*.pyc

package/src/codex/gitignore

@@ -0,0 +1,12 @@
+# CafeKit local Codex runtime
+.env
+.env.*
+!.env.example
+!.env.sample
+!.env.template
+
+hooks/.logs/
+hooks/.privacy/
+session-state/
+.cafekit-update-cache.json
+*.tmp

package/src/codex/hooks/agent.cjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getHookContext,
+  logCrash,
+  readPayload,
+  resolveProjectPath
+} = require('./lib/hook-context.cjs');
+
+function resolveVenv(projectRoot) {
+  const base = path.join(projectRoot, '.agents', 'skills', '.venv');
+  return [
+    path.join(base, 'bin', 'python3'),
+    path.join(base, 'Scripts', 'python.exe')
+  ].find((candidate) => fs.existsSync(candidate)) || null;
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { projectRoot, runtime, sessionCwd } = getHookContext(payload);
+  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 venv = resolveVenv(projectRoot);
+  const lines = [
+    `## Subagent: ${payload.agent_type || 'unknown'}`,
+    `ID: ${payload.agent_id || 'unknown'} | CWD: ${sessionCwd}`,
+    ''
+  ];
+
+  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',
+    `- Plans → ${plansPath}/ | Docs → ${docsPath}/`,
+    '- YAGNI · KISS · DRY',
+    '- Be concise. List unresolved questions at end.'
+  );
+  if (venv) {
+    lines.push(
+      `- Python in .agents/skills/: use \`${venv}\``,
+      '- Never use global pip install.'
+    );
+  }
+
+  process.stdout.write(`${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SubagentStart',
+      additionalContext: lines.join('\n')
+    }
+  })}\n`);
+} catch (error) {
+  logCrash('agent', error);
+}

package/src/codex/hooks/docs-sync.cjs

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const {
+  getHookContext,
+  logCrash,
+  readPayload,
+  resolveProjectPath
+} = require('./lib/hook-context.cjs');
+
+function latestSourceHash(projectRoot, docsRelative) {
+  try {
+    return execFileSync(
+      'git',
+      ['log', '-1', '--format=%H', '--', '.', `:(exclude)${docsRelative}`],
+      {
+        cwd: projectRoot,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore']
+      }
+    ).trim();
+  } catch {
+    return '';
+  }
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { projectRoot, runtime } = getHookContext(payload);
+  const docsDir = resolveProjectPath(projectRoot, runtime.paths?.docs, 'docs');
+  const docsRelative = path.relative(projectRoot, docsDir).replace(/\\/g, '/');
+  const hasCode = [
+    'src', 'app', 'lib', 'package.json', 'index.js', 'main.py'
+  ].some((candidate) => fs.existsSync(path.join(projectRoot, candidate)));
+  if (!hasCode) process.exit(0);
+
+  const lines = [];
+  if (!fs.existsSync(docsDir)) {
+    lines.push(
+      '### Missing docs/',
+      '> Source exists but the configured docs directory does not.',
+      '> Create baseline architecture and project-overview docs, then record the source Git hash in `docs/.sync_hash`.'
+    );
+  } else {
+    const currentHash = latestSourceHash(projectRoot, docsRelative);
+    const trackingFile = path.join(docsDir, '.sync_hash');
+    const previousHash = fs.existsSync(trackingFile)
+      ? fs.readFileSync(trackingFile, 'utf8').trim()
+      : '';
+    if (currentHash && currentHash !== previousHash) {
+      lines.push(
+        '### Docs sync needed',
+        `> Source changed (\`${currentHash}\`) since last docs sync (\`${previousHash || 'none'}\`).`,
+        '> Review the source changes, update affected docs, then refresh `docs/.sync_hash`.'
+      );
+    }
+  }
+
+  if (lines.length) process.stdout.write(`${lines.join('\n')}\n`);
+} catch (error) {
+  logCrash('docs-sync', error);
+}

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

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+'use strict';
+
+const {
+  getHookContext,
+  logCrash,
+  readPayload
+} = require('./lib/hook-context.cjs');
+const { BLOCKED_DIRS, inspectInput } = require('./lib/inspect-paths.cjs');
+
+function denyPath(requested, blocked) {
+  process.stderr.write(
+    `SCOPE LIMIT EXCEEDED: Directory "${blocked}/" is explicitly forbidden\n`
+    + `Requested Path: ${requested}\n`
+    + `Restricted zones: ${[...BLOCKED_DIRS].join(', ')}\n`
+  );
+  process.exit(2);
+}
+
+try {
+  const payload = readPayload();
+  if (!payload) process.exit(0);
+  const { runtime } = getHookContext(payload);
+  if (runtime.scout?.enabled === false || runtime.inspect?.enabled === false) process.exit(0);
+
+  const result = inspectInput(payload.tool_input || {});
+  if (result.broadGlob) {
+    process.stderr.write(
+      `SCOPE LIMIT EXCEEDED: Glob pattern is excessively broad\n`
+      + `Requested Pattern: ${result.broadGlob}\n`
+      + 'Please narrow the scope (for example, src/**/*.ts).\n'
+    );
+    process.exit(2);
+  }
+  if (result.blockedPath) {
+    denyPath(result.blockedPath.requested, result.blockedPath.blocked);
+  }
+} catch (error) {
+  logCrash('inspect-block', error);
+}

package/src/codex/hooks/lib/hook-context.cjs

@@ -0,0 +1,93 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+// Installed layout: <project>/.codex/hooks/lib/hook-context.cjs
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+function readPayload() {
+  const raw = fs.readFileSync(0, 'utf8').trim();
+  return raw ? JSON.parse(raw) : null;
+}
+
+function resolveSessionCwd(payload) {
+  const value = typeof payload?.cwd === 'string' ? payload.cwd.trim() : '';
+  const resolved = value
+    ? path.resolve(process.cwd(), value)
+    : process.cwd();
+  try {
+    return fs.realpathSync(resolved);
+  } catch {
+    return resolved;
+  }
+}
+
+function readRuntime(projectRoot = PROJECT_ROOT) {
+  try {
+    const file = path.join(projectRoot, '.codex', 'runtime.json');
+    return fs.existsSync(file)
+      ? JSON.parse(fs.readFileSync(file, 'utf8'))
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+function getHookContext(payload) {
+  return {
+    projectRoot: PROJECT_ROOT,
+    sessionCwd: resolveSessionCwd(payload),
+    runtime: readRuntime(PROJECT_ROOT)
+  };
+}
+
+function resolveProjectPath(projectRoot, configuredPath, fallback) {
+  const requested = typeof configuredPath === 'string' && configuredPath.trim()
+    ? configuredPath.trim()
+    : fallback;
+  const resolved = path.resolve(projectRoot, requested);
+  const relative = path.relative(projectRoot, resolved);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
+    ? resolved
+    : path.resolve(projectRoot, fallback);
+}
+
+function atomicWrite(file, content, mode = 0o600) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true });
+  const suffix = `${process.pid}-${crypto.randomBytes(6).toString('hex')}`;
+  const temp = `${file}.${suffix}.tmp`;
+  fs.writeFileSync(temp, content, { encoding: 'utf8', mode });
+  fs.renameSync(temp, file);
+}
+
+function logCrash(hook, error) {
+  try {
+    const dir = path.join(PROJECT_ROOT, '.codex', 'hooks', '.logs');
+    fs.mkdirSync(dir, { recursive: true });
+    fs.appendFileSync(
+      path.join(dir, 'hook-log.jsonl'),
+      `${JSON.stringify({
+        ts: new Date().toISOString(),
+        hook,
+        status: 'crash',
+        error: String(error?.message || error)
+      })}\n`
+    );
+  } catch {
+    // Hook failures remain fail-open unless the hook explicitly denies.
+  }
+}
+
+module.exports = {
+  PROJECT_ROOT,
+  atomicWrite,
+  getHookContext,
+  logCrash,
+  readPayload,
+  readRuntime,
+  resolveProjectPath,
+  resolveSessionCwd
+};