@haposoft/cafekit 0.10.0 → 0.10.3

package/bin/install.js

@@ -34,6 +34,7 @@ const { installOpenCodeRuntime } = require('./phases/opencode-runtime');
 const { writePlatformVersionMetadata } = require('./phases/write-metadata');
 const { ensureGitignore } = require('./phases/root-config');
 const { runPostInstall } = require('./phases/post-install');
+const { setupSkillDeps } = require('./phases/skills-setup');
 const { printSummary } = require('./phases/summary');
 
 /** Install a single platform: payload + runtime + metadata, under one spinner. */
@@ -85,7 +86,7 @@ async function main() {
 
   try {
     ctx = buildContext(process.argv, `${Date.now()}`);
-    ctx.ui.intro(`${ctx.ui.pc.bgCyan(ctx.ui.pc.black(' CafeKit '))} Installer v${packageJson.version} · Multi-platform SDD`);
+    ctx.ui.intro(`${ctx.ui.pc.bgCyan(ctx.ui.pc.black(' CafeKit '))}Installer v${packageJson.version} · Multi-platform SDD`);
     if (got.reclaimed) ctx.ui.info('Reclaimed a stale install lock from a dead process.');
 
     await resolvePlatforms(ctx);
@@ -108,6 +109,7 @@ async function main() {
 
     ensureGitignore(ctx);
     await runPostInstall(ctx);
+    await setupSkillDeps(ctx);
     printSummary(ctx);
 
     if (!ctx.dryRun) backup.prune(3);

package/bin/lib/context.js

@@ -183,7 +183,8 @@ function parseInstallerArgs(argv) {
   const args = {
     forceOverwrite: false,
     dryRun: false,
-    yes: false
+    yes: false,
+    withSkillsDeps: false
   };
 
   for (let i = 2; i < argv.length; i++) {
@@ -195,6 +196,8 @@ function parseInstallerArgs(argv) {
       args.dryRun = true;
     } else if (arg === '--yes' || arg === '-y') {
       args.yes = true;
+    } else if (arg === '--with-skills-deps') {
+      args.withSkillsDeps = true;
     }
   }
 

package/bin/lib/skill-deps.js

@@ -0,0 +1,184 @@
+/**
+ * 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.
+ * Prefer puppeteer's own install script (cache-aware, same as its postinstall);
+ * fall back to the bundled @puppeteer/browsers CLI. `npx puppeteer ...` is
+ * avoided — puppeteer ships no `puppeteer` bin under that invocation and `--yes`
+ * would refetch from the registry.
+ */
+function installChromium(scriptsDir) {
+  // Absolute path so it resolves regardless of the child process cwd.
+  const installMjs = path.resolve(scriptsDir, 'node_modules', 'puppeteer', 'install.mjs');
+  if (fs.existsSync(installMjs)) {
+    return run('node', [installMjs], { cwd: scriptsDir }).ok;
+  }
+  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/phases/post-install.js

@@ -1,75 +1,23 @@
 /**
  * Phase: post-install runtime configuration.
  *
- * OpenCode model, optional Gemini CLI install + API key, and addressing config.
- * Interactive prompts use ctx.ui (clack); in non-interactive/dry-run they are
- * skipped via fallbacks so spawned/CI runs never hang. Writes (.env, CLAUDE.md,
- * opencode.json) happen only when a value is actually provided.
+ * OpenCode model + addressing config. Interactive prompts use ctx.ui (clack);
+ * in non-interactive/dry-run they are skipped via fallbacks so spawned/CI runs
+ * never hang.
+ *
+ * Note: CafeKit no longer prompts for a Gemini API key. The upstream gemini-cli
+ * was removed, and the key now serves only the ai-multimodal skill — which
+ * documents it in its own `.env.example`. Users set GEMINI_API_KEY there when
+ * (and only if) they use that skill.
  */
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
-const { PLATFORMS } = require('../lib/context');
 const { setupOpenCodeModel } = require('../lib/opencode-install');
 
-function checkGeminiCLI() {
-  try {
-    execSync('which gemini', { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function installGeminiCLI(ctx) {
-  ctx.ui.startSpinner('Installing gemini-cli...');
-  try {
-    execSync('npm install -g @google/gemini-cli', { stdio: 'ignore' });
-    ctx.ui.stopSpinner('gemini-cli installed');
-    return true;
-  } catch {
-    ctx.ui.stopSpinner('Could not install gemini-cli automatically');
-    ctx.ui.warn('Run manually: npm install -g @google/gemini-cli');
-    return false;
-  }
-}
-
-function configureGeminiKey(ctx, apiKey, platforms) {
-  const envBody = `GEMINI_API_KEY=${apiKey}\nVISUAL_MODEL=gemma-4-31b-it\nSEARCH_MODEL=gemini-2.5-pro\n`;
-  const targets = platforms.filter((key) => PLATFORMS[key]).map((key) => PLATFORMS[key].folder);
-  if (targets.length === 0) targets.push('.claude');
-
-  for (const folder of targets) {
-    try {
-      const targetDir = path.join(process.cwd(), folder);
-      if (!fs.existsSync(targetDir)) fs.mkdirSync(targetDir, { recursive: true });
-      fs.writeFileSync(path.join(targetDir, '.env'), envBody, { mode: 0o600 });
-      ctx.ui.success(`Gemini API key stored in ${folder}/.env (0600)`);
-    } catch (error) {
-      ctx.ui.error(`Failed to configure Gemini API key: ${error.message}`);
-    }
-  }
-}
-
-async function setupGemini(ctx) {
-  if (checkGeminiCLI()) {
-    ctx.ui.info('gemini-cli already installed');
-  } else if (ctx.interactive) {
-    const yes = await ctx.ui.confirm(
-      { message: 'Install gemini-cli? (enables hapo:inspect ext mode)', initialValue: false },
-      false
-    );
-    if (yes === true) installGeminiCLI(ctx);
-  }
-
-  const apiKey = await ctx.ui.text(
-    { message: 'Gemini API key (Enter to skip)', placeholder: 'aistudio.google.com/apikey' },
-    ''
-  );
-  if (apiKey && typeof apiKey === 'string' && apiKey.trim()) {
-    configureGeminiKey(ctx, apiKey.trim(), ctx.platforms);
-  }
+/** Human assistant name for the active platform(s). */
+function assistantName(ctx) {
+  return ctx.platforms.includes('claude') ? 'Claude Code' : 'OpenCode';
 }
 
 function configureAddressing(ctx, userAddress) {
@@ -79,10 +27,11 @@ function configureAddressing(ctx, userAddress) {
     return;
   }
 
+  const name = assistantName(ctx);
   let content = fs.readFileSync(claudeMdFile, 'utf8');
   const addressingSection = `## Addressing (Context Overflow Indicator)
 
-The AI always addresses the user as "${userAddress}" throughout the conversation. If the AI stops doing so, it is a sign the context has been compacted/truncated — tell the user to consider \`/clear\`.`;
+${name} always addresses the user as "${userAddress}" throughout the conversation. If it stops doing so, it is a sign the context has been compacted/truncated — tell the user to consider \`/clear\`.`;
 
   // Idempotent: replace existing section (shared marker) or append.
   const regex = /##[^\n]*Context Overflow Indicator[^\n]*[\s\S]*?(?=\n##|\n*$)/;
@@ -91,14 +40,14 @@ The AI always addresses the user as "${userAddress}" throughout the conversation
     : `${content.endsWith('\n') ? content : `${content}\n`}\n${addressingSection}\n`;
 
   fs.writeFileSync(claudeMdFile, content, 'utf8');
-  ctx.ui.success(`Addressing set: AI will call you "${userAddress}"`);
+  ctx.ui.success(`${name} will call you "${userAddress}"`);
 }
 
 async function setupAddressing(ctx) {
   if (!ctx.platforms.includes('claude')) return;
 
   const answer = await ctx.ui.text(
-    { message: 'How should the AI address you? (e.g. boss, sir — Enter to skip)', placeholder: 'Enter to skip' },
+    { message: 'How should the AI address you?', placeholder: 'e.g. boss, sir — Enter to skip' },
     ''
   );
   if (ctx.ui.isCancel(answer)) return;
@@ -115,7 +64,7 @@ async function setupAddressing(ctx) {
 /** Run the post-install configuration sequence. */
 async function runPostInstall(ctx) {
   if (ctx.dryRun) {
-    ctx.ui.info('[dry-run] Skipping OpenCode model / Gemini / addressing setup');
+    ctx.ui.info('[dry-run] Skipping OpenCode model / addressing setup');
     return ctx;
   }
 
@@ -126,7 +75,6 @@ async function runPostInstall(ctx) {
     await setupOpenCodeModel(ctx.platforms, ctx.results);
   }
 
-  await setupGemini(ctx);
   await setupAddressing(ctx);
 
   // Re-record CLAUDE.md baseline so the installer-managed file (template +
@@ -138,4 +86,4 @@ async function runPostInstall(ctx) {
   return ctx;
 }
 
-module.exports = { checkGeminiCLI, configureGeminiKey, configureAddressing, runPostInstall };
+module.exports = { configureAddressing, runPostInstall };

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.10.0",
+  "version": "0.10.3",
   "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",

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