@haposoft/cafekit 0.9.7 → 0.10.2

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/skill-deps.js

@@ -0,0 +1,173 @@
+/**
+ * Skill dependency setup primitives (cross-platform, no sudo).
+ *
+ * Provides the building blocks the skills-setup phase uses to provision the
+ * parts that a plain file-copy install can't: a Python venv + pip requirements,
+ * skill-local npm installs, and the Puppeteer Chromium binary. System binaries
+ * and global npm tools are NOT auto-installed here — they are detected and the
+ * phase prints guidance.
+ *
+ * All commands run via spawnSync (blocking is fine for a CLI). Detection is
+ * silent; install callers decide how to surface progress/failures.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const isWindows = process.platform === 'win32';
+
+/** Run a command, return { ok, stdout, stderr, status }. Never throws. */
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { encoding: 'utf8', ...opts });
+  return {
+    ok: !r.error && r.status === 0,
+    status: r.status,
+    stdout: r.stdout || '',
+    stderr: r.stderr || ''
+  };
+}
+
+/** Is a command available on PATH? */
+function hasCmd(name) {
+  const probe = isWindows ? run('where', [name]) : run('which', [name]);
+  return probe.ok;
+}
+
+/** Find a usable Python launcher ('python3' or 'python'), or null. */
+function findPython() {
+  for (const cmd of ['python3', 'python']) {
+    if (hasCmd(cmd) && run(cmd, ['--version']).ok) return cmd;
+  }
+  return null;
+}
+
+function venvDir(skillsDir) {
+  return path.join(skillsDir, '.venv');
+}
+
+/** Path to the venv's python interpreter (OS-specific). */
+function venvPython(skillsDir) {
+  return isWindows
+    ? path.join(venvDir(skillsDir), 'Scripts', 'python.exe')
+    : path.join(venvDir(skillsDir), 'bin', 'python3');
+}
+
+function venvValid(skillsDir) {
+  return fs.existsSync(venvPython(skillsDir));
+}
+
+/** Create the venv (idempotent: skips if already valid). Returns true on success. */
+function createVenv(skillsDir, py) {
+  if (venvValid(skillsDir)) return true;
+  fs.mkdirSync(skillsDir, { recursive: true });
+  return run(py, ['-m', 'venv', venvDir(skillsDir)]).ok;
+}
+
+/** Upgrade pip inside the venv (best-effort). */
+function pipUpgrade(skillsDir) {
+  return run(venvPython(skillsDir), ['-m', 'pip', 'install', '--upgrade', 'pip', '--prefer-binary']).ok;
+}
+
+/** Install a requirements.txt into the venv (wheels first). Returns true on success. */
+function pipInstall(skillsDir, requirementsPath) {
+  return run(venvPython(skillsDir), [
+    '-m', 'pip', 'install', '-r', requirementsPath, '--prefer-binary'
+  ]).ok;
+}
+
+/** `npm install` in a skill scripts dir. Returns true on success. */
+function npmInstall(dir) {
+  return run('npm', ['install', '--no-audit', '--no-fund'], { cwd: dir }).ok;
+}
+
+/** Download the Puppeteer Chromium browser for chrome-devtools. */
+function installChromium(scriptsDir) {
+  return run('npx', ['--yes', 'puppeteer', 'browsers', 'install', 'chrome'], { cwd: scriptsDir }).ok;
+}
+
+/** Does a skill scripts dir declare a given npm dependency? */
+function pkgHasDep(scriptsDir, name) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(scriptsDir, 'package.json'), 'utf8'));
+    return Boolean((pkg.dependencies && pkg.dependencies[name]) || (pkg.devDependencies && pkg.devDependencies[name]));
+  } catch {
+    return false;
+  }
+}
+
+/** Download the Playwright Chromium browser (for the pptx html2pptx workflow). */
+function installPlaywrightBrowser(scriptsDir) {
+  return run('npx', ['--yes', 'playwright', 'install', 'chromium'], { cwd: scriptsDir }).ok;
+}
+
+/**
+ * List installed skills that ship a runnable scripts/requirements.txt
+ * (excludes the tests/ requirements). Returns [{ skill, file }].
+ */
+function collectRequirements(skillsDir) {
+  const out = [];
+  if (!fs.existsSync(skillsDir)) return out;
+  for (const skill of fs.readdirSync(skillsDir)) {
+    const file = path.join(skillsDir, skill, 'scripts', 'requirements.txt');
+    if (fs.existsSync(file)) out.push({ skill, file });
+  }
+  return out;
+}
+
+/**
+ * List installed skills with a scripts/package.json that still needs installing
+ * (no node_modules present). Returns [{ skill, dir }].
+ */
+function collectSkillPackages(skillsDir) {
+  const out = [];
+  if (!fs.existsSync(skillsDir)) return out;
+  for (const skill of fs.readdirSync(skillsDir)) {
+    const dir = path.join(skillsDir, skill, 'scripts');
+    if (fs.existsSync(path.join(dir, 'package.json')) && !fs.existsSync(path.join(dir, 'node_modules'))) {
+      out.push({ skill, dir });
+    }
+  }
+  return out;
+}
+
+/** External binaries some skills shell out to — detected, never auto-installed. */
+const SYSTEM_TOOLS = [
+  { cmd: 'ffmpeg', why: 'ai-multimodal (audio/video)', brew: 'brew install ffmpeg', apt: 'sudo apt install ffmpeg', win: 'winget install ffmpeg' },
+  { cmd: 'pdftotext', why: 'pdf (text extraction, poppler)', brew: 'brew install poppler', apt: 'sudo apt install poppler-utils', win: 'choco install poppler' },
+  { cmd: 'rsvg-convert', why: 'generate-graph (PNG export, librsvg)', brew: 'brew install librsvg', apt: 'sudo apt install librsvg2-bin', win: 'choco install rsvg-convert' },
+  { cmd: 'tesseract', why: 'pdf/ai-multimodal (OCR)', brew: 'brew install tesseract', apt: 'sudo apt install tesseract-ocr', win: 'choco install tesseract' }
+];
+
+/** Global npm CLIs some skills expect — detected, never auto-installed. */
+const GLOBAL_NPM = [
+  { cmd: 'agent-browser', pkg: 'agent-browser', why: 'agent-browser skill' }
+];
+
+/** Per-OS install hint for a SYSTEM_TOOLS entry. */
+function systemHint(tool) {
+  if (process.platform === 'darwin') return tool.brew;
+  if (process.platform === 'win32') return tool.win;
+  return tool.apt;
+}
+
+module.exports = {
+  isWindows,
+  hasCmd,
+  findPython,
+  venvDir,
+  venvPython,
+  venvValid,
+  createVenv,
+  pipUpgrade,
+  pipInstall,
+  npmInstall,
+  installChromium,
+  collectRequirements,
+  collectSkillPackages,
+  pkgHasDep,
+  installPlaywrightBrowser,
+  SYSTEM_TOOLS,
+  GLOBAL_NPM,
+  systemHint
+};

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
+};