@haposoft/cafekit 0.9.7 → 0.10.2

package/bin/phases/select-platform.js

@@ -0,0 +1,94 @@
+/**
+ * Phase: platform detection + selection.
+ *
+ * Resolves which platforms to install for: auto-detect existing folders, or
+ * prompt (clack) when interactive. In non-interactive mode it uses detection
+ * only and defaults to Claude when nothing is found — never blocks on input.
+ * Sets ctx.platforms, or ctx.cancelled if the user backs out.
+ */
+
+const {
+  PLATFORMS,
+  detectPlatforms,
+  getPlatformKeys,
+  warnLegacyClaudeFolder
+} = require('../lib/context');
+
+/** clack select: which platform(s) to install for. */
+async function promptPlatformSelection(ctx) {
+  const options = [
+    ...getPlatformKeys().map((key) => ({
+      value: [key],
+      label: PLATFORMS[key].name,
+      hint: `${PLATFORMS[key].folder}/`
+    })),
+    { value: getPlatformKeys(), label: 'All platforms' }
+  ];
+  const r = await ctx.ui.select(
+    { message: 'Select which platform(s) to install for', options },
+    []
+  );
+  if (ctx.ui.isCancel(r)) return [];
+  return r;
+}
+
+/** clack confirm: install for all detected platforms? */
+async function confirmAllDetected(ctx, detected) {
+  const names = detected.map((key) => PLATFORMS[key].name).join(', ');
+  const r = await ctx.ui.confirm(
+    { message: `Install for all detected platforms? (${names})`, initialValue: true },
+    true
+  );
+  if (ctx.ui.isCancel(r)) return false;
+  return r;
+}
+
+/**
+ * Resolve ctx.platforms via detection + prompts. Sets ctx.cancelled on backout.
+ */
+async function resolvePlatforms(ctx) {
+  let platforms = detectPlatforms();
+
+  if (platforms.length === 0) {
+    if (ctx.interactive) {
+      platforms = await promptPlatformSelection(ctx);
+      if (platforms.length === 0) {
+        ctx.ui.outro('Installation cancelled.');
+        ctx.cancelled = true;
+        return ctx;
+      }
+    } else {
+      // Non-interactive with nothing detected → sensible default, never block.
+      platforms = ['claude'];
+      ctx.ui.info('No platform detected; defaulting to Claude Code (.claude/).');
+    }
+  } else if (platforms.length > 1 && ctx.interactive) {
+    const proceed = await confirmAllDetected(ctx, platforms);
+    if (!proceed) {
+      platforms = await promptPlatformSelection(ctx);
+      if (platforms.length === 0) {
+        ctx.ui.outro('Installation cancelled.');
+        ctx.cancelled = true;
+        return ctx;
+      }
+    }
+  }
+
+  ctx.platforms = platforms;
+
+  const platformNames = platforms.map((key) => PLATFORMS[key].name).join(', ');
+  ctx.ui.info(`Installing for: ${platformNames}`);
+  warnLegacyClaudeFolder(platforms);
+
+  if (ctx.options.forceOverwrite) {
+    ctx.ui.info('Mode: force-overwrite (replace user-modified files; backup kept)');
+  } else if (ctx.dryRun) {
+    ctx.ui.info('Mode: dry-run (preview only, no changes written)');
+  } else {
+    ctx.ui.info('Mode: install/update (selective; preserves user-modified files)');
+  }
+
+  return ctx;
+}
+
+module.exports = { promptPlatformSelection, resolvePlatforms };

package/bin/phases/skills-setup.js

@@ -0,0 +1,119 @@
+/**
+ * Phase: skill dependency setup (opt-in, safe cross-platform).
+ *
+ * Provisions the parts a file-copy install can't:
+ *  - Python venv at <skillsDir>/.venv + pip install each skill's requirements
+ *  - skill-local `npm install` (scripts/package.json without node_modules)
+ *  - Puppeteer Chromium binary (chrome-devtools)
+ *
+ * System binaries (ffmpeg, poppler, librsvg, tesseract) and global npm CLIs are
+ * NOT auto-installed — they are detected and printed as guidance. All steps are
+ * non-fatal: a failure never breaks the install.
+ *
+ * Runs only when opted in: `--with-skills-deps`, or an interactive confirm.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+const dep = require('../lib/skill-deps');
+
+async function shouldRun(ctx) {
+  if (ctx.dryRun) return false;
+  if (ctx.options.withSkillsDeps) return true;
+  if (!ctx.interactive) return false;
+  const yes = await ctx.ui.confirm(
+    { message: 'Install skill dependencies now? (Python venv + pip + Chromium — slower)', initialValue: false },
+    false
+  );
+  return yes === true;
+}
+
+/** Provision Python venv + pip requirements for a platform's skills. */
+function setupPython(ctx, skillsDir) {
+  const reqs = dep.collectRequirements(skillsDir);
+  if (reqs.length === 0) return;
+
+  const py = dep.findPython();
+  if (!py) {
+    ctx.ui.warn('Python 3 not found — skipped venv. Install Python 3, then re-run with --with-skills-deps.');
+    return;
+  }
+
+  ctx.ui.startSpinner('Creating Python venv...');
+  if (!dep.createVenv(skillsDir, py)) {
+    ctx.ui.stopSpinner('Could not create Python venv');
+    ctx.ui.warn(`venv creation failed at ${dep.venvDir(skillsDir)} — check your Python install.`);
+    return;
+  }
+  dep.pipUpgrade(skillsDir);
+  ctx.ui.stopSpinner(`Python venv ready (${dep.venvDir(skillsDir)})`);
+
+  for (const { skill, file } of reqs) {
+    ctx.ui.startSpinner(`Installing Python deps: ${skill}...`);
+    const ok = dep.pipInstall(skillsDir, file);
+    ctx.ui.stopSpinner(ok ? `${skill}: Python deps installed` : `${skill}: some Python deps failed`);
+    if (!ok) {
+      ctx.ui.warn(`pip failed for ${skill}. Retry: "${dep.venvPython(skillsDir)}" -m pip install -r "${file}"`);
+    }
+  }
+}
+
+/** Run skill-local npm installs + Chromium for a platform's skills. */
+function setupNode(ctx, skillsDir) {
+  for (const { skill, dir } of dep.collectSkillPackages(skillsDir)) {
+    ctx.ui.startSpinner(`Installing npm deps: ${skill}...`);
+    const ok = dep.npmInstall(dir);
+    ctx.ui.stopSpinner(ok ? `${skill}: npm deps installed` : `${skill}: npm install failed`);
+    if (!ok) {
+      ctx.ui.warn(`npm install failed in ${dir} — retry manually.`);
+      continue;
+    }
+    // Skills using Playwright (e.g. pptx html2pptx) need a browser binary too.
+    if (dep.pkgHasDep(dir, 'playwright')) {
+      ctx.ui.startSpinner(`Downloading Playwright browser for ${skill}...`);
+      const pw = dep.installPlaywrightBrowser(dir);
+      ctx.ui.stopSpinner(pw ? `${skill}: Playwright browser ready` : `${skill}: Playwright browser skipped`);
+    }
+  }
+
+  const chromeScripts = path.join(skillsDir, 'chrome-devtools', 'scripts');
+  if (fs.existsSync(path.join(chromeScripts, 'package.json'))) {
+    ctx.ui.startSpinner('Downloading Chromium for chrome-devtools...');
+    const ok = dep.installChromium(chromeScripts);
+    ctx.ui.stopSpinner(ok ? 'Chromium ready' : 'Chromium download skipped/failed');
+    if (!ok) ctx.ui.warn('Chromium not downloaded — chrome-devtools may prompt on first use.');
+  }
+}
+
+/** Detect (don't install) system binaries + global npm CLIs and print guidance. */
+function guideManual(ctx) {
+  const missingTools = dep.SYSTEM_TOOLS.filter((t) => !dep.hasCmd(t.cmd));
+  const missingNpm = dep.GLOBAL_NPM.filter((g) => !dep.hasCmd(g.cmd));
+  if (missingTools.length === 0 && missingNpm.length === 0) return;
+
+  const lines = [];
+  for (const t of missingTools) lines.push(`${t.cmd}  — ${t.why}\n   ${dep.systemHint(t)}`);
+  for (const g of missingNpm) lines.push(`${g.cmd}  — ${g.why}\n   npm install -g ${g.pkg}`);
+  ctx.ui.note(lines.join('\n'), 'Optional tools to install manually');
+}
+
+async function setupSkillDeps(ctx) {
+  if (!(await shouldRun(ctx))) {
+    if (!ctx.dryRun) {
+      ctx.ui.info('Skill dependencies skipped — run later with: npx @haposoft/cafekit --with-skills-deps');
+    }
+    return ctx;
+  }
+
+  for (const key of ctx.platforms) {
+    const skillsDir = PLATFORMS[key].skillsDir;
+    setupPython(ctx, skillsDir);
+    setupNode(ctx, skillsDir);
+  }
+
+  guideManual(ctx);
+  return ctx;
+}
+
+module.exports = { setupSkillDeps };

package/bin/phases/summary.js

@@ -0,0 +1,54 @@
+/**
+ * Phase: final summary report.
+ *
+ * Renders install stats (incl. selective-merge counters) + next steps through
+ * ctx.ui, so it appears as a framed clack note/outro when interactive and as
+ * plain text otherwise.
+ */
+
+const { PLATFORMS, packageJson } = require('../lib/context');
+
+function printSummary(ctx) {
+  const { results, platforms, options, ui } = ctx;
+
+  const stats = [
+    `Copied:      ${results.copied}`,
+    `Updated:     ${results.updated}`,
+    `Unchanged:   ${results.unchanged}`,
+    `Preserved:   ${results.preserved}`,
+    `Skills:      ${results.installedSkills > 0 ? 'yes' : 'no'}`,
+    `CafeKit Version: ${packageJson.version}`,
+    results.missingDependencies > 0 ? `Missing:     ${results.missingDependencies}` : null,
+    results.errors > 0 ? `Errors:      ${results.errors}` : null
+  ].filter(Boolean).join('\n');
+
+  ui.note(stats, ctx.dryRun ? 'Dry-run preview' : 'Installation complete');
+
+  if (results.preserved > 0) {
+    const list = results.preservedFiles.slice(0, 8).map((f) => `  ⊘ ${f}`).join('\n');
+    const more = results.preservedFiles.length > 8 ? `\n  ... and ${results.preservedFiles.length - 8} more` : '';
+    ui.warn(`${results.preserved} user-modified file(s) preserved:\n${list}${more}\n`
+      + 'Re-run with --force-overwrite to replace them (a backup is kept under .cafekit-backup/).');
+  }
+
+  if (ctx.dryRun) {
+    ui.outro('Dry-run only — re-run without --dry-run to apply.');
+    return;
+  }
+
+  const lines = [];
+  for (const key of platforms) {
+    if (key === 'claude') lines.push('Claude: use /hapo:specs <feature-description>');
+    else lines.push('OpenCode: ask the agent to start a feature or brainstorm');
+  }
+  const envHosts = platforms.map((key) => `${PLATFORMS[key].folder}/.env`).join(' and ');
+  lines.push(`API keys isolated in ${envHosts}`);
+  if (!options.forceOverwrite) {
+    lines.push('Use --force-overwrite to refresh user-modified files');
+  }
+  ui.note(lines.join('\n'), 'Next steps');
+
+  ui.outro(`Done — docs: https://github.com/haposoft/cafekit`);
+}
+
+module.exports = { printSummary };

package/bin/phases/write-metadata.js

@@ -0,0 +1,60 @@
+/**
+ * Phase: write platform version metadata + install manifest.
+ *
+ * cafekit.json keeps pure version metadata (schemaVersion, version, platform,
+ * timestamps, previousVersion). The ownership baseline is written separately by
+ * the run's manifest tracker. Both are skipped in dry-run.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS, INSTALL_COMMAND, packageJson } = require('../lib/context');
+const { readJsonFile } = require('../lib/copy-utils');
+
+function writePlatformVersionMetadata(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const targetPath = path.join(platform.folder, 'cafekit.json');
+  const targetExists = fs.existsSync(targetPath);
+  const existingMetadata = readJsonFile(targetPath);
+  const now = new Date().toISOString();
+  const previousVersion = typeof existingMetadata.version === 'string'
+    ? existingMetadata.version
+    : null;
+
+  const metadata = {
+    schemaVersion: 1,
+    packageName: packageJson.name,
+    version: packageJson.version,
+    platform: platform.id,
+    platformName: platform.name,
+    installedAt: existingMetadata.installedAt || now,
+    lastInstalledAt: now,
+    installCommand: INSTALL_COMMAND
+  };
+
+  if (previousVersion && previousVersion !== packageJson.version) {
+    metadata.previousVersion = previousVersion;
+  }
+
+  if (!ctx.dryRun) {
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, `${JSON.stringify(metadata, null, 2)}\n`, 'utf8');
+  }
+
+  const prefix = ctx.dryRun ? '[dry-run] ' : '';
+  if (targetExists) {
+    ctx.ui.detail(`  ↻ ${prefix}Version metadata updated: ${targetPath}`);
+    ctx.results.updated++;
+  } else {
+    ctx.ui.detail(`  ✓ ${prefix}Version metadata installed: ${targetPath}`);
+    ctx.results.copied++;
+  }
+
+  // Persist the ownership baseline of everything installed this run.
+  const tracker = ctx.trackers[platformKey];
+  if (tracker && !ctx.dryRun) {
+    tracker.write();
+  }
+}
+
+module.exports = { writePlatformVersionMetadata };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.9.7",
+  "version": "0.10.2",
   "description": "Claude Code-first spec-driven workflow for AI coding assistants. Bundles CafeKit hapo: skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",
@@ -46,5 +46,9 @@
   },
   "devDependencies": {
     "@opencode-ai/plugin": "1.15.11"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.5.0",
+    "picocolors": "^1.1.1"
   }
 }

package/src/claude/skills/docx/scripts/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "cafekit-skill-docx",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Node dependencies for the CafeKit docx skill (docx-js authoring).",
+  "dependencies": {
+    "docx": "^9.0.0"
+  }
+}

package/src/claude/skills/docx/scripts/requirements.txt

@@ -0,0 +1,5 @@
+# DOCX skill Python dependencies (installed by `cafekit --with-skills-deps`)
+# Used by the OOXML editing path (document.py / utilities.py).
+
+# Secure XML parsing for existing .docx files
+defusedxml>=0.7.1

package/src/claude/skills/pdf/scripts/requirements.txt

@@ -0,0 +1,17 @@
+# PDF skill dependencies (installed by `cafekit --with-skills-deps`)
+# System tools also needed: poppler (pdftotext/pdf2image), tesseract (OCR).
+
+# Read / write / split / merge
+pypdf>=4.0.0
+
+# Text + table extraction
+pdfplumber>=0.11.0
+pandas>=2.0.0
+
+# Create PDFs
+reportlab>=4.0.0
+
+# OCR for scanned PDFs (needs system poppler + tesseract)
+pytesseract>=0.3.10
+pdf2image>=1.17.0
+Pillow>=10.0.0

package/src/claude/skills/pptx/scripts/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "cafekit-skill-pptx",
+  "version": "1.0.0",
+  "private": true,
+  "description": "Node dependencies for the CafeKit pptx skill (html2pptx workflow).",
+  "dependencies": {
+    "pptxgenjs": "^3.12.0",
+    "playwright": "^1.40.0",
+    "sharp": "^0.33.0",
+    "react-icons": "^5.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
+  }
+}

package/src/claude/skills/pptx/scripts/requirements.txt

@@ -0,0 +1,4 @@
+# PPTX skill Python dependencies (installed by `cafekit --with-skills-deps`)
+
+# Extract text from presentations
+markitdown[pptx]>=0.0.1