@haposoft/cafekit 0.9.7 → 0.10.0

package/bin/lib/backup.js

@@ -0,0 +1,111 @@
+/**
+ * CafeKit install backup / rollback (P2)
+ *
+ * Snapshots platform folders before any writes so a mid-install crash can be
+ * rolled back to the pre-run state. Snapshots live under
+ * `.cafekit-backup/<runId>/` at the project root and are pruned to the most
+ * recent few on success.
+ *
+ * Pure module: no console output, no process control. The orchestrator decides
+ * when to snapshot, restore, and prune, and what to log.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const BACKUP_ROOT = '.cafekit-backup';
+
+/**
+ * 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);
+  if (stat.isDirectory()) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const entry of fs.readdirSync(src)) {
+      copyTree(path.join(src, entry), path.join(dest, entry));
+    }
+  } else {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    // Preserve restrictive perms (e.g. .env at 0o600) on the backup copy.
+    try {
+      fs.chmodSync(dest, stat.mode);
+    } catch {
+      /* best-effort: chmod may fail on some filesystems */
+    }
+  }
+}
+
+/**
+ * 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).
+ *
+ * @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);
+  fs.mkdirSync(backupDir, { recursive: true });
+
+  for (const folder of existing) {
+    copyTree(folder, path.join(backupDir, folder));
+  }
+
+  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.
+ *
+ * @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);
+    fs.rmSync(target, { recursive: true, force: true });
+    copyTree(source, target);
+  }
+}
+
+/**
+ * Keep only the most recent `keepN` backups; delete older ones. Backups sort
+ * lexicographically by runId, which is timestamp-prefixed so newest sorts last.
+ */
+function prune(keepN = 3) {
+  if (!fs.existsSync(BACKUP_ROOT)) return;
+
+  const dirs = fs
+    .readdirSync(BACKUP_ROOT)
+    .filter((name) => {
+      try {
+        return fs.statSync(path.join(BACKUP_ROOT, name)).isDirectory();
+      } catch {
+        return false;
+      }
+    })
+    .sort();
+
+  const toRemove = dirs.slice(0, Math.max(0, dirs.length - keepN));
+  for (const name of toRemove) {
+    fs.rmSync(path.join(BACKUP_ROOT, name), { recursive: true, force: true });
+  }
+}
+
+module.exports = {
+  BACKUP_ROOT,
+  snapshot,
+  restore,
+  prune
+};

package/bin/lib/context.js

@@ -0,0 +1,273 @@
+/**
+ * CafeKit installer shared context + constants.
+ *
+ * Holds the platform registry, version constants, migration-manifest loader,
+ * platform helper functions, CLI arg parsing, and the run-context factory.
+ * Phase handlers import what they need from here so each phase stays focused.
+ *
+ * The context object (`ctx`) is threaded through every phase: `(ctx) => ctx`.
+ * Phases mutate `ctx.results` counters and may set `ctx.cancelled` to stop the
+ * pipeline early.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const packageJson = require('../../package.json');
+const { getOpenCodeCopyOptions } = require('./opencode-install');
+const { isInteractive, createUI } = require('./ui');
+
+const INSTALL_COMMAND = `npx ${packageJson.name}@${packageJson.version}`;
+
+// ═══════════════════════════════════════════════════════════
+// MIGRATION MANIFEST
+// ═══════════════════════════════════════════════════════════
+
+function validateManifestV2(manifest) {
+  if (!manifest || manifest.version !== 2) return false;
+  if (!manifest.runtime?.files || !Array.isArray(manifest.runtime.files)) return false;
+  if (!manifest.settings?.template) return false;
+  return true;
+}
+
+function loadClaudeMigrationManifest() {
+  const manifestPath = path.join(__dirname, '../../src/claude/migration-manifest.json');
+
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+
+    if (!validateManifestV2(manifest)) {
+      console.error('✗ Invalid manifest v2 schema - missing required fields');
+      console.error('  Expected: version=2, runtime.files[], settings.template');
+      process.exit(1);
+    }
+
+    return manifest;
+  } catch (error) {
+    console.warn(`⚠ Failed to parse Claude migration manifest: ${error.message}`);
+    return null;
+  }
+}
+
+const DEPENDENCY_TEMPLATES = {
+  commands: {
+    claude: {},
+    opencode: {}
+  },
+  agents: {
+    claude: {},
+    opencode: {}
+  }
+};
+
+// ═══════════════════════════════════════════════════════════
+// PLATFORM REGISTRY - Add new platforms here
+// ═══════════════════════════════════════════════════════════
+const PLATFORMS = {
+  claude: {
+    id: 'claude',
+    name: 'Claude Code',
+    description: 'Anthropic\'s Claude Code CLI',
+    folder: '.claude',
+    commandsDir: '.claude/commands',
+    skillsDir: '.claude/skills',
+    agentsDir: '.claude/agents',
+    skillsRef: '.claude/skills',
+    commandPrefix: '/',
+    sourceDir: 'claude',       // Maps to src/claude/
+    sourceSubdir: 'commands'   // Source subfolder within src/claude/
+  },
+  opencode: {
+    id: 'opencode',
+    name: 'OpenCode',
+    description: 'OpenCode terminal AI coding agent',
+    folder: '.opencode',
+    detectFiles: ['.opencode', 'opencode.json', 'opencode.jsonc'],
+    commandsDir: '.opencode/commands',
+    skillsDir: '.opencode/skills',
+    agentsDir: '.opencode/agents',
+    skillsRef: '.opencode/skills',
+    commandPrefix: '/',
+    sourceDir: 'claude',
+    sourceSubdir: 'archive-command'
+  }
+  // Add new platforms here:
+  // cursor: {
+  //   id: 'cursor',
+  //   name: 'Cursor',
+  //   description: 'Cursor IDE',
+  //   folder: '.cursor',
+  //   commandsDir: '.cursor/commands',
+  //   sourceDir: 'cursor',
+  //   sourceSubdir: 'commands'
+  // }
+};
+
+// ═══════════════════════════════════════════════════════════
+// DETECTION + PLATFORM HELPERS
+// ═══════════════════════════════════════════════════════════
+
+function detectPlatforms() {
+  const detected = [];
+
+  for (const [key, config] of Object.entries(PLATFORMS)) {
+    const markers = Array.isArray(config.detectFiles) ? config.detectFiles : [config.folder];
+    if (markers.some(marker => fs.existsSync(marker))) {
+      detected.push(key);
+    }
+  }
+
+  return detected;
+}
+
+function formatPlatformList() {
+  return Object.entries(PLATFORMS)
+    .map(([key, config], index) => {
+      return `${index + 1}) ${config.name} (${config.folder}/)\n   ${config.description}`;
+    })
+    .join('\n');
+}
+
+function getPlatformKeys() {
+  return Object.keys(PLATFORMS);
+}
+
+function isClaudeCompatibleRuntime(platformKey) {
+  return platformKey === 'claude' || platformKey === 'opencode';
+}
+
+function getRuntimeSupportTargetDir(platformKey, subdir) {
+  return path.join(PLATFORMS[platformKey].folder, subdir);
+}
+
+// Warn opencode-only installs when a legacy .claude/ folder remains from
+// pre-0.9.0 installs (when OpenCode shared the .claude/ runtime). We do not
+// delete anything; user must remove it explicitly to opt in.
+function warnLegacyClaudeFolder(platforms) {
+  if (!platforms.includes('opencode')) return;
+  if (platforms.includes('claude')) return;
+  if (!fs.existsSync('.claude')) return;
+
+  console.log('');
+  console.log('⚠ Legacy .claude/ folder detected.');
+  console.log('  As of CafeKit 0.9.0, OpenCode installs are self-contained under .opencode/.');
+  console.log('  The .claude/ folder from older installs is no longer used by OpenCode.');
+  console.log('  After this install finishes you can remove it: rm -rf .claude');
+  console.log('');
+}
+
+function getCopyOptions(platformKey, baseOptions = {}) {
+  if (platformKey === 'opencode') {
+    return getOpenCodeCopyOptions(baseOptions);
+  }
+  return baseOptions;
+}
+
+// ═══════════════════════════════════════════════════════════
+// CLI ARGS + RUN CONTEXT
+// ═══════════════════════════════════════════════════════════
+
+/**
+ * Parse installer CLI flags.
+ *  --upgrade / -u / --force / -f / --force-overwrite → forceOverwrite:true
+ *      (overwrite user-modified managed files, backing up the user copy first)
+ *  --dry-run                                         → dryRun:true
+ *
+ * `upgrade` is kept as an alias of `forceOverwrite` for backward compatibility
+ * with existing docs and muscle memory.
+ */
+function parseInstallerArgs(argv) {
+  const args = {
+    forceOverwrite: false,
+    dryRun: false,
+    yes: false
+  };
+
+  for (let i = 2; i < argv.length; i++) {
+    const arg = argv[i];
+
+    if (arg === '--upgrade' || arg === '-u' || arg === '--force' || arg === '-f' || arg === '--force-overwrite') {
+      args.forceOverwrite = true;
+    } else if (arg === '--dry-run') {
+      args.dryRun = true;
+    } else if (arg === '--yes' || arg === '-y') {
+      args.yes = true;
+    }
+  }
+
+  // Back-compat alias used throughout the phases.
+  args.upgrade = args.forceOverwrite;
+  return args;
+}
+
+/**
+ * Fresh results counters for a run.
+ *  copied/updated/skipped/...: legacy counters (preserved for summary parity)
+ *  preserved: user-modified/user-created files left untouched
+ *  unchanged: files identical to payload, skipped by selective merge
+ *  preservedFiles: paths reported in the summary
+ */
+function createResults() {
+  return {
+    copied: 0,
+    updated: 0,
+    skipped: 0,
+    unchanged: 0,
+    preserved: 0,
+    installedSkills: 0,
+    dependencyChecks: 0,
+    installedDependencies: 0,
+    missingDependencies: 0,
+    errors: 0,
+    targets: [],
+    preservedFiles: []
+  };
+}
+
+/**
+ * Build the run context threaded through all phases.
+ *
+ * @param {string[]} argv     process.argv
+ * @param {string}   runId    unique id for this run (timestamp-based)
+ */
+function buildContext(argv, runId) {
+  const options = parseInstallerArgs(argv);
+  // Interactive only on a real TTY and not when --yes/CI forces non-interactive.
+  const interactive = isInteractive() && !options.yes;
+  return {
+    argv,
+    runId,
+    options,
+    dryRun: options.dryRun,
+    interactive,
+    ui: createUI(interactive),
+    manifest: loadClaudeMigrationManifest(),  // migration manifest (skills/agents/runtime lists)
+    platforms: [],
+    results: createResults(),
+    trackers: {},    // platformKey → ownership tracker, set per platform
+    ownership: {},   // platformFolder → ownership manifest read at run start
+    cancelled: false
+  };
+}
+
+module.exports = {
+  packageJson,
+  INSTALL_COMMAND,
+  DEPENDENCY_TEMPLATES,
+  PLATFORMS,
+  validateManifestV2,
+  loadClaudeMigrationManifest,
+  detectPlatforms,
+  formatPlatformList,
+  getPlatformKeys,
+  isClaudeCompatibleRuntime,
+  getRuntimeSupportTargetDir,
+  warnLegacyClaudeFolder,
+  getCopyOptions,
+  parseInstallerArgs,
+  createResults,
+  buildContext
+};

package/bin/lib/lock.js

@@ -0,0 +1,86 @@
+/**
+ * CafeKit install process lock (P5)
+ *
+ * Prevents two installer runs (or a run racing another writer) from clobbering
+ * the same project. A lock file at the project root holds the owning PID and a
+ * timestamp. If a live process owns it, a second run refuses; if the owner is
+ * dead (stale lock), it is reclaimed.
+ *
+ * Pure module: no console output, no process control. Returns structured
+ * results; the orchestrator decides what to log and whether to exit.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const LOCK_FILE = '.cafekit.lock';
+
+/**
+ * Check whether a PID belongs to a live process. `process.kill(pid, 0)` sends
+ * no signal but throws ESRCH if the process does not exist.
+ */
+function isProcessAlive(pid) {
+  if (!pid || typeof pid !== 'number') return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM → process exists but we can't signal it → still alive.
+    return err.code === 'EPERM';
+  }
+}
+
+/**
+ * Attempt to acquire the lock.
+ *
+ * @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:true, reclaimed:true  → a stale lock was taken over
+ */
+function acquire(cwd = process.cwd()) {
+  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 (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 payload = { pid: process.pid, since: new Date().toISOString() };
+  fs.writeFileSync(lockPath, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  return { acquired: true, reclaimed };
+}
+
+/**
+ * Release the lock if (and only if) this process owns it. Safe to call in a
+ * finally block even when acquire() failed.
+ */
+function release(cwd = process.cwd()) {
+  const lockPath = path.join(cwd, LOCK_FILE);
+  if (!fs.existsSync(lockPath)) return;
+  try {
+    const info = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+    if (info.pid && info.pid !== process.pid) return; // not ours, leave it
+  } catch {
+    // Unreadable lock — fall through and remove it.
+  }
+  fs.rmSync(lockPath, { force: true });
+}
+
+module.exports = {
+  LOCK_FILE,
+  isProcessAlive,
+  acquire,
+  release
+};

package/bin/lib/managed-writer.js

@@ -0,0 +1,167 @@
+/**
+ * Ownership-aware file writer (P1 + P4 + P6).
+ *
+ * Central decision point for every managed file the installer writes. Instead
+ * of "exists? skip : overwrite", it hashes the incoming payload, classifies the
+ * destination against the recorded manifest, and decides:
+ *
+ *   absent        → write (created)
+ *   pristine      → write if payload differs (updated), else skip (unchanged)
+ *   user-modified → keep by default (preserved); overwrite only with
+ *   user-created    forceOverwrite (the pre-run snapshot already holds the
+ *                   user's copy for rollback/recovery)
+ *
+ * Honors dry-run (classify + report, no writes). Records written/unchanged
+ * files into the run's manifest tracker so the baseline stays accurate.
+ *
+ * Pure-ish: performs the actual file write, but logging/counters are left to
+ * callers via the returned action so each call site keeps its own message flavor.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { isTextAsset } = require('./copy-utils');
+const manifest = require('./manifest');
+
+/**
+ * Resolve the payload bytes for a source file, applying a text transform when
+ * provided and the file is a text asset (mirrors copy-utils.copyRecursive).
+ * Returns { data, utf8 } where data is a string (utf8) or Buffer.
+ */
+function readPayload(src, transform) {
+  if (typeof transform === 'function' && isTextAsset(src)) {
+    return { data: transform(fs.readFileSync(src, 'utf8'), src), utf8: true };
+  }
+  return { data: fs.readFileSync(src), utf8: false };
+}
+
+/**
+ * Plan and (unless dry-run) perform the write for a single managed file.
+ *
+ * @returns {{action: string, state: string}}
+ *   action: 'created' | 'updated' | 'unchanged' | 'preserved' | 'missing'
+ */
+function writeManagedFile(opts) {
+  const { src, dest, platformFolder, ctx, tracker, transform } = opts;
+
+  if (!fs.existsSync(src)) {
+    return { action: 'missing', state: 'absent' };
+  }
+
+  const { data, utf8 } = 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: {} };
+
+  // A file already written earlier THIS run (e.g. a spec template copied as part
+  // of the specs/ tree, then revisited by the template-sync loop) is ours — treat
+  // it as pristine against what we just wrote, not as a user-created file.
+  const relForRun = path.relative(platformFolder, dest).replace(/\\/g, '/');
+  const writtenThisRun = tracker ? tracker.recorded(relForRun) : null;
+
+  let cls;
+  if (writtenThisRun !== null) {
+    cls = {
+      state: 'pristine',
+      diskHash: writtenThisRun,
+      recordedHash: writtenThisRun,
+      changed: writtenThisRun !== payloadHash
+    };
+  } else {
+    cls = manifest.classify(dest, platformFolder, ownership, payloadHash);
+  }
+  const forced = Boolean(ctx.options.forceOverwrite);
+
+  let action;
+  if (cls.state === 'absent') {
+    action = 'created';
+  } else if (cls.state === 'pristine') {
+    action = cls.changed ? 'updated' : 'unchanged';
+  } else {
+    // user-modified or user-created
+    if (forced) {
+      action = cls.changed ? 'updated' : 'unchanged';
+    } else {
+      action = 'preserved';
+    }
+  }
+
+  if (action === 'preserved') {
+    ctx.results.preservedFiles.push(dest);
+    // Do not record: leave the prior baseline entry so the file stays
+    // classified as user-modified on the next run too.
+    return { action, state: cls.state };
+  }
+
+  const willWrite = action === 'created' || action === 'updated';
+
+  if (willWrite && !ctx.dryRun) {
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    if (utf8) {
+      fs.writeFileSync(dest, data, 'utf8');
+    } else {
+      fs.writeFileSync(dest, data);
+    }
+  }
+
+  // Record created/updated/unchanged files so the manifest reflects reality.
+  // Skip recording in dry-run (nothing was written).
+  if (tracker && !ctx.dryRun) {
+    if (willWrite) {
+      tracker.record(dest);
+    } else {
+      // unchanged pristine — record current (== payload) hash to keep baseline fresh
+      tracker.record(dest);
+    }
+  }
+
+  return { action, state: cls.state };
+}
+
+/**
+ * Walk a source directory tree and apply writeManagedFile to each file,
+ * mirroring copy-utils.copyRecursive's traversal (incl. gitignore → .gitignore).
+ *
+ * @returns {{created, updated, unchanged, preserved, missing}} aggregate counts
+ */
+function copyManagedTree(opts) {
+  const { src, dest, platformFolder, ctx, tracker, transform } = opts;
+  const agg = { created: 0, updated: 0, unchanged: 0, preserved: 0, missing: 0 };
+
+  if (!fs.existsSync(src)) {
+    agg.missing++;
+    return agg;
+  }
+
+  const stats = fs.statSync(src);
+  if (stats.isDirectory()) {
+    for (const childName of fs.readdirSync(src)) {
+      const destName = childName === 'gitignore' ? '.gitignore' : childName;
+      const childAgg = copyManagedTree({
+        ...opts,
+        src: path.join(src, childName),
+        dest: path.join(dest, destName)
+      });
+      for (const k of Object.keys(agg)) agg[k] += childAgg[k];
+    }
+    return agg;
+  }
+
+  const { action } = writeManagedFile({ src, dest, platformFolder, ctx, tracker, transform });
+  if (agg[action] !== undefined) agg[action]++;
+  return agg;
+}
+
+/**
+ * Did a tree-copy aggregate touch the filesystem (created/updated anything)?
+ */
+function treeChanged(agg) {
+  return agg.created > 0 || agg.updated > 0;
+}
+
+module.exports = {
+  readPayload,
+  writeManagedFile,
+  copyManagedTree,
+  treeChanged
+};