@haposoft/cafekit 0.14.1 → 0.15.0

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

@@ -0,0 +1,259 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+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, patchRuntimeLocale } = require('../phases/post-install');
+
+const START = '<!-- CAFEKIT CLAUDE START -->';
+const END = '<!-- CAFEKIT CLAUDE END -->';
+const TEMPLATE = fs.readFileSync(path.join(__dirname, '../../src/claude/CLAUDE.md'), 'utf8');
+
+function inTempProject(run) {
+  const originalCwd = process.cwd();
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'cafekit-installer-safety-'));
+  process.chdir(root);
+  try {
+    return run(root);
+  } finally {
+    process.chdir(originalCwd);
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function installContext(pruned) {
+  return {
+    dryRun: false,
+    options: { forceOverwrite: true },
+    ownership: { '.claude': { files: {} } },
+    trackers: {
+      claude: {
+        recorded: () => null,
+        record: () => assert.fail('root CLAUDE.md must not be recorded'),
+        prune: (target) => pruned.push(target)
+      }
+    },
+    ui: { detail() {}, warn() {}, success() {} },
+    results: {
+      copied: 0,
+      updated: 0,
+      unchanged: 0,
+      preserved: 0,
+      missingDependencies: 0,
+      preservedFiles: []
+    }
+  };
+}
+
+test('managed CLAUDE block replacement preserves user bytes under force overwrite', () => {
+  inTempProject(() => {
+    const before = '# User preface\n\n';
+    const after = '\n\n## User tail\nKeep this exactly.\n';
+    fs.writeFileSync('CLAUDE.md', `${before}${START}\nold managed text\n${END}${after}`);
+
+    const pruned = [];
+    copyClaudeMdFile(installContext(pruned), 'claude');
+
+    const content = fs.readFileSync('CLAUDE.md', 'utf8');
+    assert.ok(content.startsWith(before));
+    assert.ok(content.endsWith(after));
+    assert.ok(content.includes(TEMPLATE.trimEnd()));
+    assert.equal(content.match(new RegExp(START, 'g')).length, 1);
+    assert.deepEqual(pruned, ['../CLAUDE.md']);
+  });
+});
+
+test('legacy pristine CLAUDE template migrates to one managed block', () => {
+  inTempProject(() => {
+    fs.writeFileSync('CLAUDE.md', TEMPLATE);
+    const pruned = [];
+
+    copyClaudeMdFile(installContext(pruned), 'claude');
+
+    const content = fs.readFileSync('CLAUDE.md', 'utf8');
+    assert.equal(content, `${START}\n${TEMPLATE.trimEnd()}\n${END}\n`);
+    assert.equal(content.match(new RegExp(START, 'g')).length, 1);
+    assert.deepEqual(pruned, ['../CLAUDE.md']);
+  });
+});
+
+test('addressing changes remain inside the managed CLAUDE block', () => {
+  inTempProject(() => {
+    const userSection = '## Addressing (Context Overflow Indicator)\n\nUser-owned wording.';
+    const managedSection = '## Addressing (Context Overflow Indicator)\n\nOld managed wording.';
+    fs.writeFileSync(
+      'CLAUDE.md',
+      `${userSection}\n\n${START}\n${managedSection}\n${END}\n`
+    );
+    const ctx = {
+      platforms: ['claude'],
+      ui: { success() {}, warn() {} },
+      t: () => 'updated'
+    };
+
+    configureAddressing(ctx, 'anh');
+
+    const content = fs.readFileSync('CLAUDE.md', 'utf8');
+    assert.ok(content.startsWith(`${userSection}\n\n${START}`));
+    assert.ok(content.includes('Claude Code always addresses the user as "anh"'));
+  });
+});
+
+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 });
+    fs.writeFileSync('.claude/nested/runtime.txt', 'before\n');
+    fs.writeFileSync('CLAUDE.md', 'user instructions\n');
+
+    const backupDir = backup.snapshot(
+      ['.claude', 'CLAUDE.md', '.gitignore'],
+      '20260729-test'
+    );
+    const metadata = JSON.parse(
+      fs.readFileSync(path.join(backupDir, 'snapshot.json'), 'utf8')
+    );
+    assert.deepEqual(metadata.targets, [
+      { target: '.claude', existed: true },
+      { target: 'CLAUDE.md', existed: true },
+      { target: '.gitignore', existed: false }
+    ]);
+
+    fs.writeFileSync('.claude/nested/runtime.txt', 'after\n');
+    fs.writeFileSync('CLAUDE.md', 'overwritten\n');
+    fs.writeFileSync('.gitignore', 'generated\n');
+    backup.restore(backupDir);
+
+    assert.equal(fs.readFileSync('.claude/nested/runtime.txt', 'utf8'), 'before\n');
+    assert.equal(fs.readFileSync('CLAUDE.md', 'utf8'), 'user instructions\n');
+    assert.equal(fs.existsSync('.gitignore'), false);
+    assert.equal(fs.existsSync(path.join(backupDir, 'snapshot.json')), true);
+  });
+});
+
+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(
+      () => backup.snapshot(['../outside'], '20260729-test'),
+      /Unsafe backup target/
+    );
+  });
+});
+
+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,12 +181,22 @@ 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
+    // is restored before any success summary or backup pruning occurs.
+    if (ctx.results.errors > 0) {
+      throw new Error(`Installer reported ${ctx.results.errors} error${ctx.results.errors === 1 ? '' : 's'}`);
+    }
+
     printSummary(ctx);
 
     if (!ctx.dryRun) backup.prune(3);
 
-    exitCode = ctx.results.errors > 0 ? 1 : 0;
+    exitCode = 0;
   } catch (error) {
     const log = ctx && ctx.ui ? ctx.ui : { error: (m) => console.error(m) };
     const t = ctx ? ctx.t : (k) => k;

package/bin/lib/backup.js

@@ -12,16 +12,54 @@
 
 const fs = require('fs');
 const path = require('path');
+const { assertNoSymlinkPath } = require('./path-safety');
 
 const BACKUP_ROOT = '.cafekit-backup';
+const SNAPSHOT_METADATA = 'snapshot.json';
+const SNAPSHOT_DATA = 'data';
+
+function validateTarget(target) {
+  if (typeof target !== 'string' || !target || target.includes('\0')) {
+    throw new Error('Backup target must be a non-empty relative path');
+  }
+
+  // Validate both separator styles so a snapshot created on one platform
+  // cannot become unsafe when restored on another.
+  const portable = target.replace(/\\/g, '/');
+  const parts = portable.split('/');
+  if (path.isAbsolute(target) || portable.startsWith('/') || parts.includes('..') || parts.includes('')) {
+    throw new Error(`Unsafe backup target: ${target}`);
+  }
+  if (portable === '.' || portable === BACKUP_ROOT || portable.startsWith(`${BACKUP_ROOT}/`)) {
+    throw new Error(`Unsafe backup target: ${target}`);
+  }
+  return parts.join(path.sep);
+}
+
+function validateRunId(runId) {
+  if (typeof runId !== 'string' || !runId || runId === '.' || runId === '..' || /[\\/]/.test(runId)) {
+    throw new Error('Backup runId must be a single path segment');
+  }
+  return runId;
+}
 
 /**
  * Recursively copy a directory tree (verbatim, no transforms). Used for
  * snapshot and restore. Skips if the source does not exist.
  */
 function copyTree(src, dest) {
-  if (!fs.existsSync(src)) return;
-  const stat = fs.statSync(src);
+  let stat;
+  try {
+    stat = fs.lstatSync(src);
+  } catch (error) {
+    if (error.code === 'ENOENT') return;
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.symlinkSync(fs.readlinkSync(src), dest);
+    return;
+  }
   if (stat.isDirectory()) {
     fs.mkdirSync(dest, { recursive: true });
     for (const entry of fs.readdirSync(src)) {
@@ -40,42 +78,68 @@ function copyTree(src, dest) {
 }
 
 /**
- * Snapshot the given platform folders (relative to cwd, e.g. ['.claude']).
- * Only existing folders are captured. Returns the backup directory path, or
- * null if nothing existed to back up (fresh install → no rollback target).
+ * Snapshot explicit targets (relative to cwd, e.g. ['.claude', 'CLAUDE.md']).
+ * Every target is recorded, including targets absent before the run.
  *
  * @param {string[]} folders
  * @param {string} runId  unique id for this run (timestamp-based)
  */
 function snapshot(folders, runId) {
-  const existing = folders.filter((f) => fs.existsSync(f));
-  if (existing.length === 0) return null;
-
-  const backupDir = path.join(BACKUP_ROOT, runId);
+  const targets = [...new Set(folders.map(validateTarget))];
+  const backupDir = path.join(BACKUP_ROOT, validateRunId(runId));
+  const dataDir = path.join(backupDir, SNAPSHOT_DATA);
+  assertNoSymlinkPath(BACKUP_ROOT);
   fs.mkdirSync(backupDir, { recursive: true });
 
-  for (const folder of existing) {
-    copyTree(folder, path.join(backupDir, folder));
+  const records = [];
+  for (const target of targets) {
+    assertNoSymlinkPath(target);
+    const existed = fs.existsSync(target);
+    records.push({ target, existed });
+    if (existed) copyTree(target, path.join(dataDir, target));
   }
+  fs.writeFileSync(
+    path.join(backupDir, SNAPSHOT_METADATA),
+    `${JSON.stringify({ schemaVersion: 1, targets: records }, null, 2)}\n`,
+    'utf8'
+  );
 
   return backupDir;
 }
 
 /**
- * Restore a snapshot back over the working tree. For each captured folder we
- * remove the current (possibly half-written) copy and replace it with the
- * snapshot, returning the tree to its pre-run state.
+ * Restore every explicit target to its pre-run state. Existing targets are
+ * replaced from backup; targets absent before the run are removed.
  *
  * @param {string} backupDir  path returned by snapshot()
  */
 function restore(backupDir) {
   if (!backupDir || !fs.existsSync(backupDir)) return;
 
-  for (const folder of fs.readdirSync(backupDir)) {
-    const target = folder; // backup mirrors cwd-relative folder names
-    const source = path.join(backupDir, folder);
+  const metadataPath = path.join(backupDir, SNAPSHOT_METADATA);
+  const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+  if (metadata?.schemaVersion !== 1 || !Array.isArray(metadata.targets)) {
+    throw new Error(`Invalid backup metadata: ${metadataPath}`);
+  }
+
+  for (const record of metadata.targets) {
+    if (!record || typeof record.existed !== 'boolean') {
+      throw new Error(`Invalid backup target metadata: ${metadataPath}`);
+    }
+    const target = validateTarget(record.target);
+    const source = path.join(backupDir, SNAPSHOT_DATA, target);
+    let sourceExists = true;
+    try {
+      fs.lstatSync(source);
+    } catch (error) {
+      if (error.code === 'ENOENT') sourceExists = false;
+      else throw error;
+    }
+    if (record.existed && !sourceExists) {
+      throw new Error(`Backup data missing for target: ${target}`);
+    }
     fs.rmSync(target, { recursive: true, force: true });
-    copyTree(source, target);
+    if (record.existed) copyTree(source, target);
   }
 }
 

package/bin/lib/codex-frontmatter.js

@@ -0,0 +1,56 @@
+'use strict';
+
+function unquote(value) {
+  if (
+    (value.startsWith('"') && value.endsWith('"')) ||
+    (value.startsWith("'") && value.endsWith("'"))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function foldedScalar(lines, literal) {
+  const nonBlank = lines.filter((line) => line.trim());
+  const indent = nonBlank.length
+    ? Math.min(...nonBlank.map((line) => line.match(/^\s*/)[0].length))
+    : 0;
+  const normalized = lines.map((line) => line.slice(Math.min(indent, line.length)).trimEnd());
+  if (literal) return normalized.join('\n').trim();
+  return normalized.join('\n').replace(/\n(?=\S)/g, ' ').replace(/\n{3,}/g, '\n\n').trim();
+}
+
+function parseHeader(header) {
+  const frontmatter = {};
+  const lines = header.split(/\r?\n/);
+
+  for (let index = 0; index < lines.length; index++) {
+    const match = lines[index].match(/^([a-zA-Z0-9_-]+):(?:\s*(.*))?$/);
+    if (!match) continue;
+    const [, key, raw = ''] = match;
+
+    if (/^[>|][+-]?$/.test(raw)) {
+      const continuation = [];
+      while (index + 1 < lines.length && (/^\s/.test(lines[index + 1]) || !lines[index + 1])) {
+        continuation.push(lines[++index]);
+      }
+      frontmatter[key] = foldedScalar(continuation, raw.startsWith('|'));
+    } else {
+      frontmatter[key] = unquote(raw.trim());
+    }
+  }
+
+  return frontmatter;
+}
+
+function splitFrontmatter(content) {
+  const source = String(content);
+  const match = source.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return { frontmatter: {}, body: source };
+  return {
+    frontmatter: parseHeader(match[1]),
+    body: source.slice(match[0].length)
+  };
+}
+
+module.exports = { splitFrontmatter };