@haposoft/cafekit 0.14.2 → 0.15.0

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

@@ -0,0 +1,458 @@
+'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 {
+  normalizeCodexBody,
+  transformManagedCodexContent,
+  upsertManagedCodexBlock
+} = require('../lib/codex-install');
+const { createTracker } = require('../lib/manifest');
+const { checkVersions } = require('../lib/version-check');
+const {
+  resolvePlatforms,
+  selectLanguage
+} = require('../phases/select-platform');
+
+const PACKAGE_ROOT = path.join(__dirname, '../..');
+const PACKAGE_VERSION = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')
+).version;
+const INSTALLER = path.join(PACKAGE_ROOT, 'bin/install.js');
+const MANIFEST = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_ROOT, 'src/claude/migration-manifest.json'), 'utf8')
+);
+
+function inTempProject(run) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-native-'));
+  try {
+    return run(root);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function install(root, extraArgs = []) {
+  return spawnSync(
+    process.execPath,
+    [INSTALLER, '--platform', 'codex', '--yes', ...extraArgs],
+    {
+      cwd: root,
+      encoding: 'utf8',
+      env: { ...process.env, PATH: '/usr/bin:/bin' }
+    }
+  );
+}
+
+function allFiles(root, predicate) {
+  const found = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const target = path.join(root, entry.name);
+    if (entry.isDirectory()) found.push(...allFiles(target, predicate));
+    else if (predicate(target)) found.push(target);
+  }
+  return found;
+}
+
+function parseGeneratedTomlString(content, key) {
+  const match = content.match(new RegExp(`^${key} = (.+)$`, 'm'));
+  assert.ok(match, `missing TOML key: ${key}`);
+  return JSON.parse(match[1]);
+}
+
+test('Codex payload transform emits native skill and subagent syntax', () => {
+  const transformed = normalizeCodexBody(
+    'Agent(subagent_type="god-developer", prompt="Implement it", description="Code Feature")\n' +
+    'Use `/specs auth`, `SendMessage`, `Bash`, `Read`, and `Edit`.'
+  );
+
+  assert.match(
+    transformed,
+    /spawn_agent\(agent_type="god_developer", fork_turns="none", message="Implement it", task_name="code_feature"\)/
+  );
+  assert.match(transformed, /\$hapo-specs auth/);
+  assert.match(transformed, /`send_message`/);
+  assert.match(transformed, /`exec_command`/);
+  assert.match(transformed, /`apply_patch`/);
+  assert.doesNotMatch(transformed, /Agent\(|subagent_type|\/specs\b|Claude Code/);
+});
+
+test('Codex payload transform preserves executable keyword arguments', () => {
+  const transformed = normalizeCodexBody(
+    'parser = ArgumentParser(description="Analyze it")\n' +
+    'result = client.generate(prompt=prompt)\n' +
+    'skills = ".claude/skills"\n',
+    '/fixture/tool.py'
+  );
+
+  assert.match(transformed, /description="Analyze it"/);
+  assert.match(transformed, /prompt=prompt/);
+  assert.match(transformed, /skills = "\.agents\/skills"/);
+  assert.doesNotMatch(transformed, /task_name=|message=prompt/);
+});
+
+test('Codex managed AGENTS block preserves malformed marker topologies', () => {
+  const malformed = [
+    'user before\n<!-- CAFEKIT CODEX START -->\nuser tail\n',
+    'user before\n<!-- CAFEKIT CODEX END -->\nuser tail\n',
+    '<!-- CAFEKIT CODEX END -->\nuser\n<!-- CAFEKIT CODEX START -->\n',
+    '<!-- CAFEKIT CODEX START -->\na\n<!-- CAFEKIT CODEX START -->\nb\n<!-- CAFEKIT CODEX END -->\n',
+    '<!-- CAFEKIT CODEX START -->\na\n<!-- CAFEKIT CODEX END -->\nb\n<!-- CAFEKIT CODEX END -->\n'
+  ];
+  for (const content of malformed) {
+    assert.equal(upsertManagedCodexBlock(content, 'replacement'), content);
+    assert.equal(transformManagedCodexContent(content, () => 'replacement'), content);
+  }
+});
+
+test('platform resolver keeps saved runtimes and newly detected Codex', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-detect-'));
+  const originalCwd = process.cwd();
+  try {
+    for (const folder of ['.claude', '.opencode', '.codex']) {
+      fs.mkdirSync(path.join(root, folder), { recursive: true });
+    }
+    fs.writeFileSync(
+      path.join(root, '.claude', 'cafekit.json'),
+      `${JSON.stringify({ version: PACKAGE_VERSION, platform: 'claude' })}\n`
+    );
+    process.chdir(root);
+    const ctx = {
+      options: { platforms: [], forceOverwrite: false },
+      interactive: false,
+      dryRun: false,
+      ui: { info() {} },
+      t: (key) => key
+    };
+    await resolvePlatforms(ctx);
+    assert.deepEqual(ctx.platforms, ['claude', 'opencode', 'codex']);
+  } finally {
+    process.chdir(originalCwd);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('explicit Codex install restores the Codex locale first', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-locale-'));
+  const originalCwd = process.cwd();
+  try {
+    for (const [folder, responseLanguage] of [
+      ['.claude', '日本語'],
+      ['.codex', 'Tiếng Việt']
+    ]) {
+      fs.mkdirSync(path.join(root, folder), { recursive: true });
+      fs.writeFileSync(
+        path.join(root, folder, 'runtime.json'),
+        `${JSON.stringify({ locale: { responseLanguage } })}\n`
+      );
+    }
+    process.chdir(root);
+    const ctx = {
+      options: { platforms: ['codex'] },
+      interactive: false,
+      lang: 'en',
+      setLang(code, locale) {
+        this.lang = code;
+        this.locale = locale;
+      },
+      ui: { info() {} },
+      t: (key) => key
+    };
+    await selectLanguage(ctx);
+    assert.equal(ctx.locale, 'Tiếng Việt');
+  } finally {
+    process.chdir(originalCwd);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('same-version install can add Codex beside an existing runtime', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-version-'));
+  const originalCwd = process.cwd();
+  try {
+    fs.mkdirSync(path.join(root, '.claude'), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, '.claude', 'cafekit.json'),
+      `${JSON.stringify({ version: PACKAGE_VERSION, platform: 'claude' })}\n`
+    );
+    process.chdir(root);
+    const ctx = {
+      platforms: ['claude', 'codex'],
+      dryRun: false,
+      interactive: false,
+      options: { forceOverwrite: false },
+      ui: { info() {}, warn() {} }
+    };
+    await checkVersions(ctx);
+    assert.notEqual(ctx.cancelled, true);
+  } finally {
+    process.chdir(originalCwd);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('same-version non-interactive install performs a selective refresh', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-version-'));
+  const originalCwd = process.cwd();
+  try {
+    fs.mkdirSync(path.join(root, '.codex'), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, '.codex', 'cafekit.json'),
+      `${JSON.stringify({ version: PACKAGE_VERSION, platform: 'codex' })}\n`
+    );
+    process.chdir(root);
+    const messages = [];
+    const ctx = {
+      platforms: ['codex'],
+      dryRun: false,
+      interactive: false,
+      options: { forceOverwrite: false },
+      ui: { info(message) { messages.push(message); }, warn() {} },
+      t: (key) => key
+    };
+    await checkVersions(ctx);
+    assert.notEqual(ctx.cancelled, true);
+    assert.equal(ctx.options.forceOverwrite, false);
+    assert.deepEqual(messages, ['versionRefreshing']);
+  } finally {
+    process.chdir(originalCwd);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('same-version interactive refresh does not enable force overwrite', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-version-'));
+  const originalCwd = process.cwd();
+  try {
+    fs.mkdirSync(path.join(root, '.codex'), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, '.codex', 'cafekit.json'),
+      `${JSON.stringify({ version: PACKAGE_VERSION, platform: 'codex' })}\n`
+    );
+    process.chdir(root);
+    const ctx = {
+      platforms: ['codex'],
+      dryRun: false,
+      interactive: true,
+      options: { forceOverwrite: false },
+      ui: {
+        info() {},
+        warn() {},
+        select: async () => 'refresh',
+        isCancel: () => false
+      },
+      t: (key) => key
+    };
+    await checkVersions(ctx);
+    assert.notEqual(ctx.cancelled, true);
+    assert.equal(ctx.options.forceOverwrite, false);
+  } finally {
+    process.chdir(originalCwd);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('mixed runtime versions update the stale Codex install', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-codex-version-'));
+  const originalCwd = process.cwd();
+  try {
+    for (const [folder, platform, version] of [
+      ['.claude', 'claude', PACKAGE_VERSION],
+      ['.codex', 'codex', '0.14.1']
+    ]) {
+      fs.mkdirSync(path.join(root, folder), { recursive: true });
+      fs.writeFileSync(
+        path.join(root, folder, 'cafekit.json'),
+        `${JSON.stringify({ version, platform })}\n`
+      );
+    }
+    process.chdir(root);
+    const ctx = {
+      platforms: ['claude', 'codex'],
+      dryRun: false,
+      interactive: false,
+      options: { forceOverwrite: false },
+      ui: { info() {}, warn() {} }
+    };
+    await checkVersions(ctx);
+    assert.notEqual(ctx.cancelled, true);
+    assert.equal(ctx.isUpdate, true);
+  } finally {
+    process.chdir(originalCwd);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('Codex ownership rejects files outside its split managed roots', () => {
+  inTempProject((root) => {
+    const originalCwd = process.cwd();
+    process.chdir(root);
+    try {
+      const tracker = createTracker('.codex', PACKAGE_VERSION, {
+        recordRoot: '.',
+        allowedRoots: ['.codex', '.agents']
+      });
+      assert.throws(() => tracker.keyFor('AGENTS.md'), /outside allowed roots/);
+      assert.equal(tracker.keyFor('.agents/skills/specs/SKILL.md'), '.agents/skills/specs/SKILL.md');
+    } finally {
+      process.chdir(originalCwd);
+    }
+  });
+});
+
+test('Codex dry-run leaves both managed roots untouched', () => {
+  inTempProject((root) => {
+    const result = install(root, ['--dry-run']);
+    assert.equal(result.status, 0, `${result.stdout}\n${result.stderr}`);
+    assert.equal(fs.existsSync(path.join(root, '.codex')), false);
+    assert.equal(fs.existsSync(path.join(root, '.agents')), false);
+    assert.equal(fs.existsSync(path.join(root, 'AGENTS.md')), false);
+    assert.equal(fs.existsSync(path.join(root, '.gitignore')), false);
+  });
+});
+
+test('Codex install is project-local, native, and upgrade-safe', () => {
+  inTempProject((root) => {
+    const userInstructions = '# User rules\n\nKeep this exact.\n';
+    fs.writeFileSync(path.join(root, 'AGENTS.md'), userInstructions);
+
+    const first = install(root);
+    assert.equal(first.status, 0, `${first.stdout}\n${first.stderr}`);
+    assert.equal(fs.existsSync(path.join(root, '.claude')), false);
+    assert.equal(fs.existsSync(path.join(root, '.opencode')), false);
+    assert.equal(fs.existsSync(path.join(root, '.codex', 'config.toml')), false);
+
+    for (const relative of [
+      '.codex/hooks.json',
+      '.codex/runtime.json',
+      '.codex/hooks/privacy-block.cjs',
+      '.codex/rules/workflow.md',
+      '.codex/rules/hook-protocols.md',
+      '.codex/scripts/validate-spec-output.cjs',
+      '.agents/.gitignore',
+      '.agents/skills/specs/SKILL.md'
+    ]) {
+      assert.equal(fs.existsSync(path.join(root, relative)), true, `missing ${relative}`);
+    }
+
+    const agentsGitignore = fs.readFileSync(
+      path.join(root, '.agents', '.gitignore'),
+      'utf8'
+    );
+    assert.match(agentsGitignore, /skills\/\*\*\/\.venv\//);
+    assert.match(agentsGitignore, /skills\/\*\*\/node_modules\//);
+    assert.match(agentsGitignore, /!skills\/\*\*\/\.env\.example/);
+
+    if (process.platform !== 'win32') {
+      for (const [sourceRelative, installedRelative] of [
+        ['src/claude/scripts/validate-spec-output.cjs', '.codex/scripts/validate-spec-output.cjs'],
+        ['src/claude/skills/chrome-devtools/scripts/install.sh', '.agents/skills/chrome-devtools/scripts/install.sh'],
+        ['src/claude/skills/ai-multimodal/scripts/check_setup.py', '.agents/skills/ai-multimodal/scripts/check_setup.py']
+      ]) {
+        const sourceMode = fs.statSync(path.join(PACKAGE_ROOT, sourceRelative)).mode & 0o111;
+        const installedMode = fs.statSync(path.join(root, installedRelative)).mode & 0o111;
+        assert.notEqual(sourceMode, 0, `fixture should be executable: ${sourceRelative}`);
+        assert.equal(installedMode, sourceMode, `execute bits differ: ${installedRelative}`);
+      }
+    }
+
+    for (const fileName of MANIFEST.agents.required) {
+      const name = path.basename(fileName, '.md').replace(/-/g, '_');
+      const agentPath = path.join(root, '.codex', 'agents', `${name}.toml`);
+      const content = fs.readFileSync(agentPath, 'utf8');
+      assert.equal(parseGeneratedTomlString(content, 'name'), name);
+      assert.ok(parseGeneratedTomlString(content, 'description').length > 8);
+      assert.ok(parseGeneratedTomlString(content, 'developer_instructions').length > 20);
+    }
+
+    const skillFiles = allFiles(
+      path.join(root, '.agents', 'skills'),
+      (file) => path.basename(file) === 'SKILL.md'
+    );
+    const skillNames = skillFiles.map((file) => {
+      const match = fs.readFileSync(file, 'utf8').match(/^name:\s*(.+)$/m);
+      assert.ok(match, `missing skill name in ${file}`);
+      return match[1].trim();
+    });
+    assert.ok(skillNames.length >= 20);
+    assert.equal(new Set(skillNames).size, skillNames.length);
+    assert.ok(skillNames.every((name) => /^[a-z0-9-]+$/.test(name)));
+
+    const catalog = spawnSync(
+      process.execPath,
+      [path.join(root, '.codex', 'scripts', 'generate-skill-catalog.cjs'), '--json'],
+      { cwd: root, encoding: 'utf8' }
+    );
+    assert.equal(catalog.status, 0, catalog.stderr);
+    const catalogData = JSON.parse(catalog.stdout);
+    assert.equal(catalogData.total, skillNames.length);
+    assert.equal(
+      catalogData.root,
+      fs.realpathSync(path.join(root, '.agents', 'skills'))
+    );
+
+    const dockerScript = fs.readFileSync(
+      path.join(root, '.agents', 'skills', 'devops', 'scripts', 'docker_optimize.py'),
+      'utf8'
+    );
+    assert.match(dockerScript, /description="Analyze Dockerfile for optimization opportunities"/);
+    assert.doesNotMatch(dockerScript, /task_name="analyze_dockerfile/);
+
+    const multimodalScript = fs.readFileSync(
+      path.join(root, '.agents', 'skills', 'ai-multimodal', 'scripts', 'gemini_batch_process.py'),
+      'utf8'
+    );
+    assert.match(multimodalScript, /prompt=prompt/);
+    assert.doesNotMatch(multimodalScript, /message=prompt/);
+
+    const modelVisibleFiles = [
+      path.join(root, 'AGENTS.md'),
+      ...allFiles(path.join(root, '.codex', 'agents'), (file) => file.endsWith('.toml')),
+      ...allFiles(path.join(root, '.codex', 'rules'), (file) => file.endsWith('.md')),
+      ...allFiles(path.join(root, '.agents', 'skills'), (file) => file.endsWith('.md'))
+    ];
+    const visible = modelVisibleFiles.map((file) => fs.readFileSync(file, 'utf8')).join('\n');
+    assert.doesNotMatch(visible, /\bAgent\(|subagent_type|`Agent`|\bSendMessage\b|\/hapo:|\bhapo:|Claude Code/);
+    assert.doesNotMatch(visible, /@@PRIVACY_PROMPT_START@@|Claude Tasks/);
+    assert.match(visible, /\$hapo-specs/);
+
+    const agentsMd = fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8');
+    assert.ok(agentsMd.startsWith(userInstructions));
+    assert.equal((agentsMd.match(/<!-- CAFEKIT CODEX START -->/g) || []).length, 1);
+    assert.match(agentsMd, /fork_turns: "none"/);
+    assert.match(agentsMd, /repository is trusted/);
+
+    const ownership = JSON.parse(
+      fs.readFileSync(path.join(root, '.codex', 'cafekit-manifest.json'), 'utf8')
+    );
+    assert.ok(Object.keys(ownership.files).every((key) => (
+      (key.startsWith('.codex/') || key.startsWith('.agents/')) && !key.includes('../')
+    )));
+
+    const questionSkill = path.join(root, '.agents', 'skills', 'question', 'SKILL.md');
+    fs.appendFileSync(questionSkill, '\nUSER-CODEX-SENTINEL\n');
+
+    const sameVersion = install(root);
+    assert.equal(sameVersion.status, 0, `${sameVersion.stdout}\n${sameVersion.stderr}`);
+    assert.match(fs.readFileSync(questionSkill, 'utf8'), /USER-CODEX-SENTINEL/);
+
+    const metadataPath = path.join(root, '.codex', 'cafekit.json');
+    const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+    metadata.version = '0.14.1';
+    fs.writeFileSync(metadataPath, `${JSON.stringify(metadata, null, 2)}\n`);
+
+    const upgrade = install(root);
+    assert.equal(upgrade.status, 0, `${upgrade.stdout}\n${upgrade.stderr}`);
+    assert.match(fs.readFileSync(questionSkill, 'utf8'), /USER-CODEX-SENTINEL/);
+    assert.ok(fs.readFileSync(path.join(root, 'AGENTS.md'), 'utf8').startsWith(userInstructions));
+
+    const forced = install(root, ['--force-overwrite']);
+    assert.equal(forced.status, 0, `${forced.stdout}\n${forced.stderr}`);
+    assert.doesNotMatch(fs.readFileSync(questionSkill, 'utf8'), /USER-CODEX-SENTINEL/);
+  });
+});

package/bin/__tests__/installer-safety.test.js

@@ -7,8 +7,12 @@ const path = require('node:path');
 const { test } = require('node:test');
 
 const backup = require('../lib/backup');
+const {
+  copyOpenCodeAgentsMdFile,
+  normalizeOpenCodeBody
+} = require('../lib/opencode-install');
 const { copyClaudeMdFile } = require('../phases/claude-runtime');
-const { configureAddressing } = require('../phases/post-install');
+const { configureAddressing, patchRuntimeLocale } = require('../phases/post-install');
 
 const START = '<!-- CAFEKIT CLAUDE START -->';
 const END = '<!-- CAFEKIT CLAUDE END -->';
@@ -104,6 +108,68 @@ test('addressing changes remain inside the managed CLAUDE block', () => {
   });
 });
 
+test('OpenCode force refresh preserves user and Codex AGENTS blocks', () => {
+  inTempProject(() => {
+    const userContent = '# User instructions\n\nKeep this exact.\n';
+    const codexBlock = '<!-- CAFEKIT CODEX START -->\nCodex managed\n<!-- CAFEKIT CODEX END -->\n';
+    fs.writeFileSync('AGENTS.md', `${userContent}\n${codexBlock}`);
+    const results = { copied: 0, updated: 0, skipped: 0, missingDependencies: 0 };
+
+    copyOpenCodeAgentsMdFile('opencode', results, { upgrade: true });
+
+    const content = fs.readFileSync('AGENTS.md', 'utf8');
+    assert.ok(content.startsWith(userContent));
+    assert.ok(content.includes(codexBlock.trim()));
+    assert.equal((content.match(/<!-- CAFEKIT OPENCODE START -->/g) || []).length, 1);
+    assert.equal(results.updated, 1);
+  });
+});
+
+test('legacy unmarked OpenCode AGENTS content is wrapped without duplication', () => {
+  inTempProject(() => {
+    const source = path.join(__dirname, '../../src/opencode/AGENTS.md');
+    const legacy = normalizeOpenCodeBody(fs.readFileSync(source, 'utf8'));
+    const codexBlock = '<!-- CAFEKIT CODEX START -->\nCodex managed\n<!-- CAFEKIT CODEX END -->\n';
+    fs.writeFileSync('AGENTS.md', `${legacy}\n${codexBlock}`);
+    const results = { copied: 0, updated: 0, skipped: 0, missingDependencies: 0 };
+
+    copyOpenCodeAgentsMdFile('opencode', results, { upgrade: true });
+
+    const content = fs.readFileSync('AGENTS.md', 'utf8');
+    assert.equal((content.match(/<!-- CAFEKIT OPENCODE START -->/g) || []).length, 1);
+    assert.equal((content.match(/^# AGENTS\.md$/gm) || []).length, 1);
+    assert.ok(content.includes(codexBlock.trim()));
+  });
+});
+
+test('locale patch does not claim ownership of a preserved user runtime', () => {
+  inTempProject(() => {
+    fs.mkdirSync('.codex', { recursive: true });
+    fs.writeFileSync(
+      '.codex/runtime.json',
+      `${JSON.stringify({ custom: true, locale: { responseLanguage: 'English' } })}\n`
+    );
+    const ctx = {
+      platforms: ['codex'],
+      locale: 'Tiếng Việt',
+      lang: 'vi',
+      trackers: {
+        codex: {
+          keyFor: () => '.codex/runtime.json',
+          recorded: () => null,
+          record: () => assert.fail('preserved runtime must not become installer-owned')
+        }
+      }
+    };
+
+    patchRuntimeLocale(ctx);
+
+    const runtime = JSON.parse(fs.readFileSync('.codex/runtime.json', 'utf8'));
+    assert.equal(runtime.custom, true);
+    assert.equal(runtime.locale.responseLanguage, 'Tiếng Việt');
+  });
+});
+
 test('backup restores existing targets and removes targets absent before the run', () => {
   inTempProject(() => {
     fs.mkdirSync('.claude/nested', { recursive: true });
@@ -135,6 +201,29 @@ test('backup restores existing targets and removes targets absent before the run
   });
 });
 
+test('backup preserves nested dependency symlinks without following them', () => {
+  inTempProject(() => {
+    fs.mkdirSync('.agents/skills/demo/.venv/bin', { recursive: true });
+    fs.mkdirSync('toolchain', { recursive: true });
+    fs.writeFileSync('toolchain/python3', 'project-owned target\n');
+    const linkPath = '.agents/skills/demo/.venv/bin/python3';
+    const linkTarget = '../../../../../toolchain/python3';
+    fs.symlinkSync(linkTarget, linkPath);
+
+    const backupDir = backup.snapshot(['.agents'], '20260729-nested-symlink');
+    const backupLink = path.join(backupDir, 'data', linkPath);
+    assert.equal(fs.lstatSync(backupLink).isSymbolicLink(), true);
+    assert.equal(fs.readlinkSync(backupLink), linkTarget);
+
+    fs.rmSync('.agents', { recursive: true, force: true });
+    backup.restore(backupDir);
+
+    assert.equal(fs.lstatSync(linkPath).isSymbolicLink(), true);
+    assert.equal(fs.readlinkSync(linkPath), linkTarget);
+    assert.equal(fs.readFileSync(linkPath, 'utf8'), 'project-owned target\n');
+  });
+});
+
 test('backup rejects traversal targets before snapshot or restore deletion', () => {
   inTempProject(() => {
     assert.throws(
@@ -143,3 +232,28 @@ test('backup rejects traversal targets before snapshot or restore deletion', ()
     );
   });
 });
+
+test('managed targets and snapshots reject project symlink traversal', () => {
+  inTempProject((root) => {
+    fs.mkdirSync('external', { recursive: true });
+    fs.symlinkSync(
+      path.join(root, 'external'),
+      '.agents',
+      process.platform === 'win32' ? 'junction' : 'dir'
+    );
+
+    const { createTracker } = require('../lib/manifest');
+    const tracker = createTracker('.codex', 'test', {
+      recordRoot: '.',
+      allowedRoots: ['.codex', '.agents']
+    });
+    assert.throws(
+      () => tracker.keyFor('.agents/skills/specs/SKILL.md'),
+      /Refusing to follow symlinked managed path/
+    );
+    assert.throws(
+      () => backup.snapshot(['.agents'], '20260729-symlink-test'),
+      /Refusing to follow symlinked managed path/
+    );
+  });
+});

package/bin/install.js

@@ -32,6 +32,7 @@ const {
 } = require('./phases/claude-runtime');
 const { mergeClaudeSettings } = require('./phases/claude-settings');
 const { installOpenCodeRuntime } = require('./phases/opencode-runtime');
+const { installCodexRuntime } = require('./phases/codex-runtime');
 const { writePlatformVersionMetadata } = require('./phases/write-metadata');
 const { checkVersions } = require('./lib/version-check');
 const { ensureGitignore } = require('./phases/root-config');
@@ -46,7 +47,11 @@ function installPlatform(ctx, platformKey) {
 
   // Read ownership baseline + start a fresh tracker for this platform.
   ctx.ownership[platform.folder] = manifestLib.read(platform.folder);
-  ctx.trackers[platformKey] = manifestLib.createTracker(platform.folder, packageJson.version);
+  ctx.trackers[platformKey] = manifestLib.createTracker(
+    platform.folder,
+    packageJson.version,
+    platform.ownership
+  );
 
   const before = { copied: ctx.results.copied, updated: ctx.results.updated, skills: ctx.results.installedSkills };
   ctx.ui.startSpinner(ctx.t('installingPlatform', { name: platform.name }));
@@ -66,6 +71,10 @@ function installPlatform(ctx, platformKey) {
     installOpenCodeRuntime(ctx, platformKey);
   }
 
+  if (platformKey === 'codex') {
+    installCodexRuntime(ctx, platformKey);
+  }
+
   writePlatformVersionMetadata(ctx, platformKey);
 
   const wrote = (ctx.results.copied - before.copied) + (ctx.results.updated - before.updated);
@@ -74,7 +83,7 @@ function installPlatform(ctx, platformKey) {
     name: platform.name, files: wrote, skills
   }));
 
-  ctx.results.targets.push(platform.commandsDir);
+  ctx.results.targets.push(platform.commandsDir || platform.skillsDir || platform.folder);
 }
 
 function printHelp() {
@@ -83,10 +92,11 @@ function printHelp() {
 Usage: npx @haposoft/cafekit [options]
 
 Installs CafeKit skills, agents, rules and runtime into the current project
-(.claude/ and/or .opencode/). Re-runs are selective: managed files are updated,
+for Claude Code, OpenCode, and/or Codex CLI. Re-runs are selective: managed files are updated,
 your edits are preserved.
 
 Options:
+  --platform <id[,id]> Select claude, opencode, or codex explicitly
   --dry-run            Preview changes; write nothing
   --force-overwrite    Overwrite user-modified managed files (backup kept)
   -u, --upgrade, -f, --force   Alias of --force-overwrite
@@ -133,7 +143,7 @@ async function main() {
     await resolvePlatforms(ctx);
     if (ctx.cancelled) { lock.release(); process.exit(0); }
 
-    // Version check: same → exit, downgrade → confirm, upgrade → version picker
+    // Version check: same → selective refresh, downgrade → confirm, upgrade → picker
     await checkVersions(ctx);
     if (ctx.cancelled) { lock.release(); process.exit(0); }
 
@@ -158,8 +168,10 @@ async function main() {
     // Capture platform folders AND the root files the pipeline mutates
     // (CLAUDE.md, .gitignore) so a mid-run failure rolls back cleanly.
     if (!ctx.dryRun) {
-      const folders = ctx.platforms.map((key) => PLATFORMS[key].folder);
-      ctx.backupDir = backup.snapshot([...folders, 'CLAUDE.md', '.gitignore'], ctx.runId);
+      const targets = ctx.platforms.flatMap((key) => (
+        PLATFORMS[key].backupTargets || [PLATFORMS[key].folder]
+      ));
+      ctx.backupDir = backup.snapshot([...targets, '.gitignore'], ctx.runId);
     }
 
     for (const platformKey of ctx.platforms) {
@@ -169,7 +181,9 @@ async function main() {
     ensureGitignore(ctx);
     await runPostInstall(ctx);
     await setupSkillDeps(ctx);
-    await setupRtk(ctx);
+    if (ctx.platforms.includes('claude')) {
+      await setupRtk(ctx);
+    }
 
     // Phase handlers may report recoverable-looking errors through counters
     // instead of throwing. Treat them as transactional failure so the snapshot