@haposoft/cafekit 0.18.2 → 0.18.3

package/bin/install.js

@@ -17,7 +17,7 @@
 
 const { spawnSync } = require('child_process');
 const fs = require('fs');
-const { buildContext, PLATFORMS, packageJson } = require('./lib/context');
+const { buildContext, parseInstallerArgs, PLATFORMS, packageJson } = require('./lib/context');
 const lock = require('./lib/lock');
 const backup = require('./lib/backup');
 const manifestLib = require('./lib/manifest');
@@ -120,6 +120,7 @@ function printHelp() {
   console.log(`CafeKit installer (cafekit) v${packageJson.version}
 
 Usage: npx @haposoft/cafekit [options]
+       npx @haposoft/cafekit@latest migrate [--apply]
 
 Installs CafeKit skills, agents, rules and runtime into the current project
 for Claude Code and/or Codex CLI. Re-runs are selective: managed files are updated,
@@ -139,12 +140,22 @@ Options:
   -h, --help           Show this help
   -v, --version        Print version
 
+Commands:
+  migrate              Preview removing this repository's npx install so the
+                       CafeKit Claude Code and Codex plugins take over; edited
+                       files and runtime.json stay. Writes nothing.
+  migrate --apply      Remove it, with a backup in .cafekit-backup/ that is
+                       restored if anything fails.
+
 Docs: https://github.com/haposoft/cafekit`);
 }
 
 async function main() {
   // Info flags short-circuit before any side effects.
   const argv = process.argv.slice(2);
+  if (argv[0] === 'migrate') {
+    process.exit(await runMigrate(argv.slice(1)));
+  }
   if (argv.includes('--help') || argv.includes('-h')) {
     printHelp();
     process.exit(0);
@@ -154,6 +165,15 @@ async function main() {
     process.exit(0);
   }
 
+  // Reject a mistyped argument before the lock and before anything is written.
+  try {
+    parseInstallerArgs(process.argv);
+  } catch (error) {
+    console.error(`✗ ${error.message}`);
+    console.error('  Run npx @haposoft/cafekit --help for the options.');
+    process.exit(error.exitCode || 1);
+  }
+
   // ── Concurrency guard (before context; plain output) ────
   const got = lock.acquire();
   if (!got.acquired) {
@@ -251,4 +271,82 @@ async function main() {
   process.exit(exitCode);
 }
 
+function printMigrateHelp(stream = console.log) {
+  stream(`Usage: npx @haposoft/cafekit@latest migrate [--apply]
+
+Removes this repository's CafeKit npx install so the Claude Code and Codex
+plugins take over. Without --apply it only prints the plan.
+
+Removed: installed files that still match their install hash and have a plugin
+equivalent, CafeKit hook entries, and the CafeKit instruction blocks.
+Kept: edited files, runtime.json, files you added, skills no plugin ships yet,
+and every user entry in settings.json, hooks.json, AGENTS.md and CLAUDE.md.
+A repository with an .omp/ install is refused.`);
+}
+
+/** `migrate [--apply]`: returns the exit code (0 done or nothing to do, 1 failed or refused, 2 bad usage). */
+async function runMigrate(args) {
+  let apply = false;
+  for (const arg of args) {
+    if (arg === '--apply') apply = true;
+    else if (arg === '--help' || arg === '-h') {
+      printMigrateHelp();
+      return 0;
+    } else {
+      console.error(`✗ Unknown argument for migrate: ${arg}`);
+      printMigrateHelp(console.error);
+      return 2;
+    }
+  }
+
+  const { planMigration, planSteps, applyMigration } = require('./lib/migrate-apply');
+  const { renderManifestPlan } = require('./lib/migrate-plan');
+  const { renderMergedPlan } = require('./lib/migrate-merged');
+  const root = process.cwd();
+  let plan;
+  try {
+    plan = planMigration(root);
+  } catch (error) {
+    console.error(`✗ migrate could not read this repository: ${error.message}`);
+    return 1;
+  }
+  const steps = planSteps(plan);
+  console.log(`CafeKit migrate — ${apply ? 'apply' : 'dry run (nothing is written)'}\n`);
+  // The merged-file planner may mark hook scripts kept, so the manifest plan renders after it.
+  const manifestText = renderManifestPlan(plan.manifest);
+  if (manifestText) console.log(manifestText);
+  const mergedText = renderMergedPlan(plan.merged);
+  if (mergedText) console.log(`\nMerged files:\n${mergedText}`);
+
+  // An install migrate cannot read (refused) or does not manage (unmanaged) would be left
+  // behind while the rest goes, so nothing is changed until it is fixed.
+  const blocked = Object.values(plan.manifest.platforms).filter((platform) => ['refused', 'unmanaged'].includes(platform.status));
+  if (plan.merged.refused || blocked.length > 0) {
+    if (plan.merged.refused) console.error(`\n✗ Refused: ${plan.merged.refused}`);
+    for (const platform of blocked) console.error(`\n✗ ${platform.name} cannot be migrated: ${platform.reason}`);
+    console.error('  Nothing was changed. Fix or remove that install by hand, then run migrate again.');
+    return 1;
+  }
+  if (steps.length === 0) {
+    console.log('\nNothing to migrate: no CafeKit npx file here is planned for removal.');
+    return 0;
+  }
+  if (!apply) {
+    console.log(`\n${steps.length} changes planned. Folders left empty are removed too.`);
+    console.log('Run `npx @haposoft/cafekit@latest migrate --apply` to apply them, with a backup.');
+    return 0;
+  }
+
+  const result = await applyMigration(root, { plan });
+  if (result.ok) {
+    console.log(`\n✓ Removed ${result.removed} files and rewrote ${result.written}. Backup: ${result.backupDir}`);
+    console.log('  Install the plugins if you have not: see the CafeKit README.');
+    return 0;
+  }
+  console.error(`\n✗ migrate stopped (${result.reason}): ${result.message}`);
+  if (result.backupDir) console.error(`  Backup: ${result.backupDir}`);
+  for (const step of result.manualSteps || []) console.error(`  ${step}`);
+  return 1;
+}
+
 main();

package/bin/lib/backup.js

@@ -47,30 +47,30 @@ function validateRunId(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) {
+function copyTree(src, dest, io = fs) {
   let stat;
   try {
-    stat = fs.lstatSync(src);
+    stat = io.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);
+    io.mkdirSync(path.dirname(dest), { recursive: true });
+    io.symlinkSync(io.readlinkSync(src), dest);
     return;
   }
   if (stat.isDirectory()) {
-    fs.mkdirSync(dest, { recursive: true });
-    for (const entry of fs.readdirSync(src)) {
-      copyTree(path.join(src, entry), path.join(dest, entry));
+    io.mkdirSync(dest, { recursive: true });
+    for (const entry of io.readdirSync(src)) {
+      copyTree(path.join(src, entry), path.join(dest, entry), io);
     }
   } else {
-    fs.mkdirSync(path.dirname(dest), { recursive: true });
-    fs.copyFileSync(src, dest);
+    io.mkdirSync(path.dirname(dest), { recursive: true });
+    io.copyFileSync(src, dest);
     // Preserve restrictive perms (e.g. .env at 0o600) on the backup copy.
     try {
-      fs.chmodSync(dest, stat.mode);
+      io.chmodSync(dest, stat.mode);
     } catch {
       /* best-effort: chmod may fail on some filesystems */
     }
@@ -111,35 +111,54 @@ function snapshot(folders, runId) {
  * Restore every explicit target to its pre-run state. Existing targets are
  * replaced from backup; targets absent before the run are removed.
  *
+ * A target that fails does not stop the others: every target is attempted, and
+ * the failures are thrown together at the end as `error.restoreErrors`
+ * ([{ target, message }]) so the caller can name what to put back by hand.
+ *
  * @param {string} backupDir  path returned by snapshot()
+ * @param {{fs?: object}} options  file-system implementation (tests inject failures)
  */
-function restore(backupDir) {
-  if (!backupDir || !fs.existsSync(backupDir)) return;
+function restore(backupDir, options = {}) {
+  const io = options.fs || fs;
+  if (!backupDir || !io.existsSync(backupDir)) return;
 
   const metadataPath = path.join(backupDir, SNAPSHOT_METADATA);
-  const metadata = JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
+  const metadata = JSON.parse(io.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}`);
     }
+    validateTarget(record.target);
+  }
+
+  const restoreErrors = [];
+  for (const record of metadata.targets) {
     const target = validateTarget(record.target);
-    const source = path.join(backupDir, SNAPSHOT_DATA, target);
-    let sourceExists = true;
     try {
-      fs.lstatSync(source);
+      const source = path.join(backupDir, SNAPSHOT_DATA, target);
+      let sourceExists = true;
+      try {
+        io.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}`);
+      }
+      io.rmSync(target, { recursive: true, force: true });
+      if (record.existed) copyTree(source, target, io);
     } catch (error) {
-      if (error.code === 'ENOENT') sourceExists = false;
-      else throw error;
-    }
-    if (record.existed && !sourceExists) {
-      throw new Error(`Backup data missing for target: ${target}`);
+      restoreErrors.push({ target, message: error.message });
     }
-    fs.rmSync(target, { recursive: true, force: true });
-    if (record.existed) copyTree(source, target);
+  }
+  if (restoreErrors.length > 0) {
+    const error = new Error(`Could not restore ${restoreErrors.map((item) => item.target).join(', ')} from ${backupDir}`);
+    error.restoreErrors = restoreErrors;
+    throw error;
   }
 }
 

package/bin/lib/codex-install.js

@@ -285,6 +285,10 @@ function normalizeRuntimePaths(content, sourcePath = '') {
   return next;
 }
 
+// Matches the vibe invocation list across a hard line wrap.
+const VIBE_INVOCATION_CLAUDE = new RegExp(
+  '\\(`/cf:vibe` from the plugin, `/vibe` from a project install, `\\$cf-vibe` on Codex\\)'.replace(/ /g, '\\s+'), 'g');
+
 function normalizeSkillNames(content) {
   return content
     .replace(/\/cf:([a-z0-9-]+)/gi, (_match, name) => `$cf-${name}`)
@@ -349,6 +353,9 @@ function normalizeCodexBody(content, sourcePath = '') {
         'It runs autonomously with high reasoning effort on the session model unless configuration selects another');
   }
 
+  // The vibe-run exception lists every way to invoke vibe; on Codex only the `$cf-vibe` mention exists, and the
+  // generic rename below would turn the Claude names into the false "`$cf-vibe` from the plugin".
+  next = next.replace(VIBE_INVOCATION_CLAUDE, () => '(`$cf-vibe`)');
   next = normalizeAgentInvocations(normalizeAgentNames(normalizeSkillNames(next)));
   next = next.replace(/`?CLAUDE_CODE_SUBAGENT_MODEL`?/g,
     'the configured agent model (`model` in `.codex/agents/<agent>.toml`, or `[agents].default_subagent_model` in native Codex configuration)');

package/bin/lib/context.js

@@ -245,6 +245,7 @@ function getCopyOptions(platformKey, baseOptions = {}) {
  *  --upgrade / -u / --force / -f / --force-overwrite → forceOverwrite:true
  *      (overwrite user-modified managed files, backing up the user copy first)
  *  --dry-run                                         → dryRun:true
+ *  an unknown positional argument                    → throws with exitCode 2
  *
  * `upgrade` is kept as an alias of `forceOverwrite` for backward compatibility
  * with existing docs and muscle memory.
@@ -283,6 +284,10 @@ function parseInstallerArgs(argv) {
       args.lang = argv[++i];
     } else if (arg.startsWith('--lang=')) {
       args.lang = arg.slice('--lang='.length);
+    } else if (!arg.startsWith('-')) {
+      // A typo of a subcommand must not run an install.
+      const hint = arg === 'migrate' ? ' (migrate must be the first argument)' : '';
+      throw Object.assign(new Error(`Unknown argument: ${JSON.stringify(arg)}${hint}`), { exitCode: 2 });
     }
   }
 

package/bin/lib/lock.js

@@ -10,6 +10,7 @@
  * results; the orchestrator decides what to log and whether to exit.
  */
 
+const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 
@@ -30,36 +31,115 @@ function isProcessAlive(pid) {
   }
 }
 
+/** Lock file text for this process. */
+function lockPayload() {
+  return `${JSON.stringify({ pid: process.pid, since: new Date().toISOString() }, null, 2)}\n`;
+}
+
+/**
+ * Create `file` holding `data` only if it does not exist; false when another process got
+ * there first. The data is written to a private temp file and hard-linked into place, so
+ * the file never exists empty: a `wx` write opens it before writing, and a reader in that
+ * gap would see no pid and take a live lock for a stale one.
+ */
+function createExclusive(file, data) {
+  const temp = `${file}.${process.pid}.${crypto.randomBytes(6).toString('hex')}`;
+  let written = false;
+  try {
+    fs.writeFileSync(temp, data, { encoding: 'utf8', flag: 'wx' });
+    written = true;
+    fs.linkSync(temp, file);
+    return true;
+  } catch (err) {
+    // A failed temp write (a full disk) is a real error; never create the lock after it.
+    if (!written) throw err;
+    if (err.code === 'EEXIST') return false;
+    // exFAT, FAT32 and some network or VM shares have no hard links, and the error a
+    // failed link reports differs by platform. The temp write succeeded, so the folder is
+    // writable: fall back to a plain `wx` create, which still lets only one run win (with
+    // the brief empty-file gap back) and raises any real error itself.
+    return createWithoutLink(file, data);
+  } finally {
+    fs.rmSync(temp, { force: true });
+  }
+}
+
+function createWithoutLink(file, data) {
+  try {
+    fs.writeFileSync(file, data, { encoding: 'utf8', flag: 'wx' });
+    return true;
+  } catch (err) {
+    if (err.code === 'EEXIST') return false;
+    throw err;
+  }
+}
+
+function readOrNull(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function parseLock(raw) {
+  try {
+    const info = JSON.parse(raw);
+    return info && typeof info === 'object' ? info : {};
+  } catch {
+    return {};
+  }
+}
+
 /**
  * Attempt to acquire the lock.
  *
+ * The lock file is created with `wx`, so of two racing runs exactly one wins. A stale
+ * lock (its pid is dead) is reclaimed only by the run that also creates the
+ * `.cafekit.lock.reclaim` guard with `wx`: it re-reads the lock, and only when the
+ * bytes are still the stale ones it read does it delete the lock and create its own,
+ * again with `wx`. Checking and replacing cannot be one atomic step, so without the
+ * guard two reclaimers could each see the stale bytes and each believe it won.
+ *
  * @param {string} cwd  project root (defaults to process.cwd())
  * @returns {{acquired: boolean, reason?: string, pid?: number, since?: string, reclaimed?: boolean}}
  *   acquired:false + reason:'held' → another live process owns it (pid/since set)
+ *   acquired:false + reason:'reclaiming' → another run is reclaiming a stale lock, or died doing so
  *   acquired:true, reclaimed:true  → a stale lock was taken over
  */
-function acquire(cwd = process.cwd()) {
+function acquire(cwd = process.cwd(), attempt = 0) {
   const lockPath = path.join(cwd, LOCK_FILE);
-  let reclaimed = false;
-
-  if (fs.existsSync(lockPath)) {
-    let info = {};
-    try {
-      info = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
-    } catch {
-      info = {};
-    }
+  if (createExclusive(lockPath, lockPayload())) return { acquired: true, reclaimed: false };
 
-    if (isProcessAlive(info.pid)) {
-      return { acquired: false, reason: 'held', pid: info.pid, since: info.since };
-    }
-    // Stale lock from a dead process — safe to reclaim.
-    reclaimed = true;
+  const raw = readOrNull(lockPath);
+  // The owner released it between our create and our read: try once more.
+  if (raw === null) return attempt < 1 ? acquire(cwd, attempt + 1) : { acquired: false, reason: 'held', pid: undefined };
+  const info = parseLock(raw);
+  if (isProcessAlive(info.pid)) {
+    return { acquired: false, reason: 'held', pid: info.pid, since: info.since };
   }
 
-  const payload = { pid: process.pid, since: new Date().toISOString() };
-  fs.writeFileSync(lockPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
-  return { acquired: true, reclaimed };
+  const guardPath = `${lockPath}.reclaim`;
+  // The current owner, for a refusal that names who holds the lock.
+  const held = () => {
+    const owner = parseLock(readOrNull(lockPath) || '');
+    return { acquired: false, reason: 'held', pid: owner.pid, since: owner.since };
+  };
+  if (!createExclusive(guardPath, lockPayload())) {
+    // A guard left by a run that died while reclaiming blocks every later reclaim until
+    // it is deleted by hand; removing it here would reopen the race it closes.
+    const guard = parseLock(readOrNull(guardPath) || '');
+    return { acquired: false, reason: 'reclaiming', pid: guard.pid, since: guard.since, guard: guardPath };
+  }
+  try {
+    if (readOrNull(lockPath) !== raw) return held();
+    fs.rmSync(lockPath, { force: true });
+    if (!createExclusive(lockPath, lockPayload())) return held();
+    return { acquired: true, reclaimed: true };
+  } finally {
+    fs.rmSync(guardPath, { force: true });
+  }
 }
 
 /**

package/bin/lib/managed-writer.js

@@ -39,23 +39,29 @@ function readPayload(src, transform) {
 /**
  * Plan and (unless dry-run) perform the write for a single managed file.
  *
+ * `content` (a string) replaces `src` for a file the installer generates rather than copies; it is
+ * written as UTF-8 without an executable bit and goes through the same ownership decision.
+ *
  * @returns {{action: string, state: string}}
  *   action: 'created' | 'updated' | 'unchanged' | 'preserved' | 'missing'
  */
 function writeManagedFile(opts) {
-  const { src, dest, platformFolder, ctx, tracker, transform, sourceRoot } = opts;
+  const { src, dest, platformFolder, ctx, tracker, transform, sourceRoot, content } = opts;
+  const generated = typeof content === 'string';
 
-  if (!fs.existsSync(src)) {
-    return { action: 'missing', state: 'absent' };
-  }
-  const sourceStat = fs.lstatSync(src);
-  if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
-    throw new Error(`Managed source must be a non-symlink regular file: ${src}`);
+  if (!generated) {
+    if (!fs.existsSync(src)) {
+      return { action: 'missing', state: 'absent' };
+    }
+    const sourceStat = fs.lstatSync(src);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+      throw new Error(`Managed source must be a non-symlink regular file: ${src}`);
+    }
+    if (sourceRoot) assertNoSymlinkPath(src, sourceRoot);
   }
-  if (sourceRoot) assertNoSymlinkPath(src, sourceRoot);
   assertNoSymlinkPath(dest);
 
-  const { data, utf8 } = readPayload(src, transform);
+  const { data, utf8 } = generated ? { data: content, utf8: true } : readPayload(src, transform);
   const payloadHash = manifest.sha256(data);
   // Ownership manifest for this platform (read at run start), NOT the migration manifest.
   const ownership = (ctx.ownership && ctx.ownership[platformFolder]) || { files: {} };
@@ -116,7 +122,7 @@ function writeManagedFile(opts) {
     } else {
       fs.writeFileSync(dest, data);
     }
-    if (process.platform !== 'win32') {
+    if (process.platform !== 'win32' && !generated) {
       const sourceMode = fs.statSync(src).mode;
       const destinationMode = fs.statSync(dest).mode;
       fs.chmodSync(dest, (destinationMode & ~0o111) | (sourceMode & 0o111));