@haposoft/cafekit 0.9.6 → 0.10.0

package/bin/lib/manifest.js

@@ -0,0 +1,182 @@
+/**
+ * CafeKit install manifest (P1 — ownership tracking)
+ *
+ * Records every managed file the installer wrote, keyed by SHA-256 of the
+ * payload at install time. On a later run we compare three hashes — the file
+ * on disk, the hash recorded here, and the new payload — to classify each
+ * file as pristine / user-modified / user-created. This is what lets update
+ * skip unchanged files and preserve user edits instead of blindly overwriting.
+ *
+ * The manifest lives at `<platformFolder>/cafekit-manifest.json`, a sibling of
+ * the existing `cafekit.json` metadata (which stays pure version metadata).
+ *
+ * Pure module: no console output, no process control. Side effects limited to
+ * reading/writing the manifest file itself.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const MANIFEST_FILE = 'cafekit-manifest.json';
+const SCHEMA_VERSION = 1;
+
+/**
+ * SHA-256 of a buffer or string. Returns hex digest.
+ */
+function sha256(data) {
+  return crypto.createHash('sha256').update(data).digest('hex');
+}
+
+/**
+ * SHA-256 of a file on disk, or null if it does not exist / cannot be read.
+ */
+function hashFile(filePath) {
+  try {
+    return sha256(fs.readFileSync(filePath));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Absolute path to a platform's manifest file.
+ */
+function manifestPath(platformFolder) {
+  return path.join(platformFolder, MANIFEST_FILE);
+}
+
+/**
+ * Read a platform manifest. Returns a normalized object even when the file is
+ * absent or corrupt, so callers never have to null-check.
+ *
+ * Shape: { schemaVersion, version, files: { <relPath>: { sha256, version } } }
+ */
+function read(platformFolder) {
+  const empty = { schemaVersion: SCHEMA_VERSION, version: null, files: {} };
+  try {
+    const raw = fs.readFileSync(manifestPath(platformFolder), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || typeof parsed.files !== 'object') {
+      return empty;
+    }
+    return {
+      schemaVersion: parsed.schemaVersion || SCHEMA_VERSION,
+      version: parsed.version || null,
+      files: parsed.files || {}
+    };
+  } catch {
+    return empty;
+  }
+}
+
+/**
+ * Create a tracker that accumulates installed-file records during a run and
+ * writes them back as the new baseline. relPath keys are normalized to forward
+ * slashes and are relative to the platform folder.
+ */
+function createTracker(platformFolder, version) {
+  const files = {};
+
+  return {
+    /**
+     * Record a managed file by its on-disk path. Hashes the file as written.
+     * Skips silently if the file is missing (e.g. dry-run).
+     */
+    record(absPath) {
+      const hash = hashFile(absPath);
+      if (hash === null) return;
+      const rel = path.relative(platformFolder, absPath).replace(/\\/g, '/');
+      files[rel] = { sha256: hash, version };
+    },
+
+    /** Number of files recorded so far. */
+    count() {
+      return Object.keys(files).length;
+    },
+
+    /** Recorded hash for a relPath written earlier this run, or null. */
+    recorded(rel) {
+      const key = rel.replace(/\\/g, '/');
+      return files[key] ? files[key].sha256 : null;
+    },
+
+    /**
+     * Write the manifest to disk. Merges onto any prior manifest so files
+     * touched by a partial/selective run are not dropped from the baseline.
+     */
+    write() {
+      const prior = read(platformFolder);
+      const merged = { ...prior.files, ...files };
+      const out = {
+        schemaVersion: SCHEMA_VERSION,
+        version,
+        files: merged
+      };
+      const target = manifestPath(platformFolder);
+      fs.mkdirSync(path.dirname(target), { recursive: true });
+      fs.writeFileSync(target, `${JSON.stringify(out, null, 2)}\n`, 'utf8');
+    }
+  };
+}
+
+/**
+ * Classify a managed file against the recorded baseline + the incoming payload.
+ *
+ * @param {string} absPath      destination path on disk
+ * @param {string} platformFolder root of the platform install (.claude/.opencode)
+ * @param {object} manifest     result of read(platformFolder)
+ * @param {string} payloadHash  sha256 of the content about to be written
+ * @returns {{state: string, diskHash: string|null, recordedHash: string|null, changed: boolean}}
+ *   state: 'absent' | 'pristine' | 'user-modified' | 'user-created'
+ *   changed: whether the payload differs from what's on disk (false → skip copy)
+ */
+function classify(absPath, platformFolder, manifest, payloadHash) {
+  const rel = path.relative(platformFolder, absPath).replace(/\\/g, '/');
+  const recorded = manifest.files[rel];
+  const recordedHash = recorded ? recorded.sha256 : null;
+  const diskHash = hashFile(absPath);
+
+  if (diskHash === null) {
+    return { state: 'absent', diskHash: null, recordedHash, changed: true };
+  }
+
+  // File exists but we never recorded installing it → user created it.
+  if (!recordedHash) {
+    return {
+      state: 'user-created',
+      diskHash,
+      recordedHash: null,
+      changed: diskHash !== payloadHash
+    };
+  }
+
+  // On disk matches our last install → safe to update from payload.
+  if (diskHash === recordedHash) {
+    return {
+      state: 'pristine',
+      diskHash,
+      recordedHash,
+      changed: diskHash !== payloadHash
+    };
+  }
+
+  // On disk diverged from our baseline → user edited a managed file.
+  return {
+    state: 'user-modified',
+    diskHash,
+    recordedHash,
+    changed: diskHash !== payloadHash
+  };
+}
+
+module.exports = {
+  MANIFEST_FILE,
+  SCHEMA_VERSION,
+  sha256,
+  hashFile,
+  manifestPath,
+  read,
+  createTracker,
+  classify
+};

package/bin/lib/ui.js

@@ -0,0 +1,108 @@
+/**
+ * Terminal UI layer for the installer.
+ *
+ * In an interactive TTY it renders the @clack/prompts experience (framed
+ * intro/outro, spinner, ◆/│/└ prompts). In a non-interactive context (piped
+ * stdin, CI, --yes) it degrades to plain console output and returns provided
+ * fallbacks for any input prompt — so spawned/CI runs never hang and the
+ * self-test fixtures keep working unchanged.
+ *
+ * All @clack/prompts usage is funneled through here and gated by `interactive`.
+ */
+
+const p = require('@clack/prompts');
+const pc = require('picocolors');
+
+/** Cancel sentinel returned by input prompts when the user aborts (Ctrl+C). */
+const CANCEL = Symbol('cafekit.cancel');
+
+/** True only when we can drive an interactive terminal. */
+function isInteractive() {
+  return Boolean(process.stdin.isTTY)
+    && process.env.CI !== 'true'
+    && process.env.NON_INTERACTIVE !== 'true';
+}
+
+/**
+ * Build a UI logger bound to an interactive flag.
+ *
+ * Interactive methods route to clack; non-interactive ones to console so output
+ * stays greppable/plain. `detail()` is for high-frequency per-file progress: it
+ * updates the active spinner line (interactive) or prints (non-interactive).
+ */
+function createUI(interactive) {
+  let spinner = null;
+
+  return {
+    interactive,
+    pc,
+
+    intro(msg) {
+      if (interactive) p.intro(msg);
+      else console.log(`\n${msg}\n`);
+    },
+    outro(msg) {
+      if (interactive) p.outro(msg);
+      else console.log(`\n${msg}`);
+    },
+    note(msg, title) {
+      if (interactive) p.note(msg, title);
+      else console.log(`\n${title ? `${title}\n` : ''}${msg}`);
+    },
+
+    startSpinner(msg) {
+      if (interactive) {
+        spinner = p.spinner();
+        spinner.start(msg);
+      } else {
+        console.log(msg);
+      }
+    },
+    stopSpinner(msg) {
+      if (interactive && spinner) {
+        spinner.stop(msg);
+        spinner = null;
+      } else if (msg) {
+        console.log(msg);
+      }
+    },
+    /** Ephemeral per-file progress (does not scroll the screen when interactive). */
+    detail(msg) {
+      if (interactive) {
+        if (spinner) spinner.message(msg.replace(/^\s+/, ''));
+      } else {
+        console.log(msg);
+      }
+    },
+
+    success(msg) { interactive ? p.log.success(msg) : console.log(msg); },
+    info(msg) { interactive ? p.log.info(msg) : console.log(msg); },
+    warn(msg) { interactive ? p.log.warn(msg) : console.log(msg); },
+    error(msg) { interactive ? p.log.error(msg) : console.error(msg); },
+
+    async select(opts, fallback) {
+      if (!interactive) return fallback;
+      const r = await p.select(opts);
+      return p.isCancel(r) ? CANCEL : r;
+    },
+    async multiselect(opts, fallback) {
+      if (!interactive) return fallback;
+      const r = await p.multiselect(opts);
+      return p.isCancel(r) ? CANCEL : r;
+    },
+    async text(opts, fallback = '') {
+      if (!interactive) return fallback;
+      const r = await p.text(opts);
+      return p.isCancel(r) ? CANCEL : r;
+    },
+    async confirm(opts, fallback = false) {
+      if (!interactive) return fallback;
+      const r = await p.confirm(opts);
+      return p.isCancel(r) ? CANCEL : r;
+    },
+
+    isCancel(v) { return v === CANCEL; }
+  };
+}
+
+module.exports = { isInteractive, createUI, CANCEL };

package/bin/phases/claude-runtime.js

@@ -0,0 +1,132 @@
+/**
+ * Phase: Claude/runtime file installation.
+ *
+ * ROUTING.md, runtime files (hooks/status/gitignore/runtime.json), obsolete
+ * runtime cleanup, CLAUDE.md, and the rules/ tree. All copies are
+ * ownership-aware — notably CLAUDE.md and rules/ no longer force-overwrite, so
+ * user edits survive re-installs (the latent wipe is fixed).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  PLATFORMS,
+  isClaudeCompatibleRuntime,
+  getRuntimeSupportTargetDir,
+  getCopyOptions
+} = require('../lib/context');
+const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
+const { report, treeAction } = require('./report');
+const { normalizeOpenCodeBody } = require('../lib/opencode-install');
+
+const SRC = path.join(__dirname, '../../src');
+
+/** Copy ROUTING.md (SKILLS_DIR substituted; OpenCode body normalized). */
+function copyRoutingFile(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const src = path.join(SRC, platform.sourceDir, 'ROUTING.md');
+  const dest = path.join(platform.folder, 'ROUTING.md');
+  if (!fs.existsSync(src)) return;
+
+  const transform = (content) => {
+    let c = content.replace(/\{\{SKILLS_DIR\}\}/g, platform.skillsRef);
+    if (platformKey === 'opencode') c = normalizeOpenCodeBody(c);
+    return c;
+  };
+  const { action } = writeManagedFile({
+    src, dest, platformFolder: platform.folder, ctx, tracker: ctx.trackers[platformKey], transform
+  });
+  report(ctx, action, 'ROUTING.md');
+}
+
+/** Copy Claude runtime files declared in the migration manifest. Claude only. */
+function copyClaudeRuntimeFiles(ctx, platformKey) {
+  if (platformKey !== 'claude') return;
+  const manifest = ctx.manifest;
+  if (!manifest?.runtime?.files) return;
+
+  const srcBase = path.join(SRC, 'claude');
+  const targetBase = PLATFORMS.claude.folder;
+  const tracker = ctx.trackers.claude;
+
+  manifest.runtime.files.forEach((relPath) => {
+    const srcPath = path.join(srcBase, relPath);
+    const targetRelPath = relPath === 'gitignore' ? '.gitignore' : relPath;
+    const targetPath = path.join(targetBase, targetRelPath);
+
+    if (!fs.existsSync(srcPath)) {
+      ctx.ui.warn(`Runtime file not found: ${relPath}`);
+      ctx.results.missingDependencies++;
+      return;
+    }
+
+    const { action } = writeManagedFile({
+      src: srcPath, dest: targetPath, platformFolder: targetBase, ctx, tracker
+    });
+    report(ctx, action, `Runtime: ${targetRelPath}`);
+  });
+}
+
+/** Delete runtime files marked obsolete by the manifest. Claude only. */
+function removeObsoleteClaudeRuntimeFiles(ctx, platformKey) {
+  if (platformKey !== 'claude') return;
+
+  const obsoleteFiles = ctx.manifest?.obsolete?.runtimeFiles || [];
+  const targetBase = PLATFORMS.claude.folder;
+
+  obsoleteFiles.forEach((relPath) => {
+    const targetPath = path.join(targetBase, relPath);
+    if (!fs.existsSync(targetPath)) return;
+
+    if (!ctx.dryRun) fs.rmSync(targetPath, { force: true });
+    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed obsolete runtime: ${relPath}`);
+    ctx.results.updated++;
+  });
+}
+
+/** Install CLAUDE.md at the project root (ownership-aware). Claude only. */
+function copyClaudeMdFile(ctx, platformKey) {
+  if (platformKey !== 'claude') return;
+
+  const src = path.join(SRC, 'claude/CLAUDE.md');
+  const dest = 'CLAUDE.md'; // project root
+  if (!fs.existsSync(src)) {
+    ctx.ui.warn('CLAUDE.md template not found');
+    ctx.results.missingDependencies++;
+    return;
+  }
+
+  const { action } = writeManagedFile({
+    src, dest, platformFolder: PLATFORMS.claude.folder, ctx, tracker: ctx.trackers.claude
+  });
+  report(ctx, action, 'CLAUDE.md');
+}
+
+/** Copy the rules/ tree (ownership-aware; no longer force-overwrites). */
+function copyRulesDirectory(ctx, platformKey) {
+  if (!isClaudeCompatibleRuntime(platformKey)) return;
+
+  const src = path.join(SRC, 'claude/rules');
+  const dest = getRuntimeSupportTargetDir(platformKey, 'rules');
+  if (!fs.existsSync(src)) {
+    ctx.ui.warn('rules/ directory not found');
+    ctx.results.missingDependencies++;
+    return;
+  }
+
+  const transform = platformKey === 'opencode'
+    ? getCopyOptions('opencode', {}).transform
+    : undefined;
+  const agg = copyManagedTree({
+    src, dest, platformFolder: PLATFORMS[platformKey].folder, ctx, tracker: ctx.trackers[platformKey], transform
+  });
+  report(ctx, treeAction(agg), 'rules/ directory');
+}
+
+module.exports = {
+  copyRoutingFile,
+  copyClaudeRuntimeFiles,
+  removeObsoleteClaudeRuntimeFiles,
+  copyClaudeMdFile,
+  copyRulesDirectory
+};

package/bin/phases/claude-settings.js

@@ -0,0 +1,130 @@
+/**
+ * Phase helper: Claude settings.json merge + obsolete-hook pruning.
+ *
+ * settings.json is merged (not a verbatim payload copy), so it stays outside
+ * the ownership model: managed statusLine/hooks are merged into the user's
+ * existing settings, and obsolete hook registrations are pruned. Honors dry-run.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+
+const SRC_CLAUDE = path.join(__dirname, '../../src/claude');
+
+/**
+ * Remove obsolete hook entries from a settings object whose command matches any
+ * manifest-listed substring (e.g. a retired router hook). Returns a possibly
+ * new settings object.
+ */
+function pruneObsoleteSettingsHooks(settings, ctx) {
+  const obsoleteSubstrings = ctx.manifest?.obsolete?.settingsHookCommandSubstrings || [];
+
+  if (!settings.hooks || obsoleteSubstrings.length === 0) {
+    return settings;
+  }
+
+  let removedCount = 0;
+  const prunedHooks = {};
+
+  Object.entries(settings.hooks).forEach(([eventName, matcherEntries]) => {
+    if (!Array.isArray(matcherEntries)) {
+      prunedHooks[eventName] = matcherEntries;
+      return;
+    }
+
+    const prunedEntries = [];
+    matcherEntries.forEach((entry) => {
+      if (!Array.isArray(entry?.hooks)) {
+        prunedEntries.push(entry);
+        return;
+      }
+      const remainingHooks = entry.hooks.filter((hook) => {
+        const command = hook?.command || '';
+        const isObsolete = obsoleteSubstrings.some((substring) => command.includes(substring));
+        if (isObsolete) removedCount++;
+        return !isObsolete;
+      });
+      if (remainingHooks.length > 0) {
+        prunedEntries.push({ ...entry, hooks: remainingHooks });
+      }
+    });
+
+    if (prunedEntries.length > 0) {
+      prunedHooks[eventName] = prunedEntries;
+    }
+  });
+
+  if (removedCount > 0) {
+    ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Settings: removed ${removedCount} obsolete hook(s)`);
+    ctx.results.updated++;
+    return { ...settings, hooks: prunedHooks };
+  }
+
+  return settings;
+}
+
+/**
+ * Merge CafeKit-managed statusLine + hooks into .claude/settings.json,
+ * preserving user-owned entries. Claude only.
+ */
+function mergeClaudeSettings(ctx, platformKey) {
+  if (platformKey !== 'claude') return;
+
+  const manifest = ctx.manifest;
+  if (!manifest?.settings?.template) return;
+
+  const templatePath = path.join(SRC_CLAUDE, manifest.settings.template);
+  const targetPath = path.join(PLATFORMS.claude.folder, 'settings.json');
+
+  if (!fs.existsSync(templatePath)) {
+    ctx.ui.warn(`Settings template not found: ${manifest.settings.template}`);
+    return;
+  }
+
+  const managedSettings = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+  let existingSettings = {};
+  if (fs.existsSync(targetPath)) {
+    existingSettings = JSON.parse(fs.readFileSync(targetPath, 'utf8'));
+  }
+
+  const mergedSettings = pruneObsoleteSettingsHooks({ ...existingSettings }, ctx);
+
+  // statusLine: adopt managed value if upgrading, missing, or CafeKit-owned.
+  if (managedSettings.statusLine) {
+    const existingCommand = existingSettings.statusLine?.command || '';
+    const isCafeKitOwned = existingCommand.includes('status.cjs') || existingCommand.includes('statusline.cjs');
+    if (ctx.options.forceOverwrite || !existingSettings.statusLine || isCafeKitOwned) {
+      mergedSettings.statusLine = managedSettings.statusLine;
+      ctx.ui.detail(`  ✓ ${ctx.dryRun ? '[dry-run] ' : ''}Settings: statusLine merged`);
+    }
+  }
+
+  // hooks: append managed hooks that aren't already present (dedupe by command).
+  if (managedSettings.hooks) {
+    mergedSettings.hooks = mergedSettings.hooks || {};
+    Object.keys(managedSettings.hooks).forEach((eventName) => {
+      const managedHooks = managedSettings.hooks[eventName];
+      const existingHooks = mergedSettings.hooks[eventName] || [];
+      const mergedHooks = [...existingHooks];
+
+      managedHooks.forEach((managedHook) => {
+        const managedCommand = managedHook.hooks?.[0]?.command || '';
+        const isDuplicate = mergedHooks.some((existingHook) =>
+          existingHook.hooks?.some((h) => h.command === managedCommand));
+        if (!isDuplicate) {
+          mergedHooks.push(managedHook);
+          ctx.ui.detail(`  ✓ ${ctx.dryRun ? '[dry-run] ' : ''}Settings: hook ${eventName} merged`);
+        }
+      });
+
+      mergedSettings.hooks[eventName] = mergedHooks;
+    });
+  }
+
+  if (!ctx.dryRun) {
+    fs.writeFileSync(targetPath, JSON.stringify(mergedSettings, null, 2), 'utf8');
+  }
+}
+
+module.exports = { pruneObsoleteSettingsHooks, mergeClaudeSettings };