@haposoft/cafekit 0.9.7 → 0.10.2

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

package/bin/phases/copy-payload.js

@@ -0,0 +1,220 @@
+/**
+ * Phase: copy payload (skills, agents, references, scripts, commands).
+ *
+ * Ported from the original copyPlatformFiles(), but every write goes through
+ * the ownership-aware writer so re-runs update pristine files and preserve
+ * user-modified ones instead of blindly skipping/overwriting.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  PLATFORMS,
+  DEPENDENCY_TEMPLATES,
+  isClaudeCompatibleRuntime,
+  getRuntimeSupportTargetDir,
+  getCopyOptions
+} = require('../lib/context');
+const { writeManagedFile, copyManagedTree } = require('../lib/managed-writer');
+const { report, treeAction } = require('./report');
+const {
+  convertOpenCodeAgentContent,
+  convertOpenCodeCommandContent
+} = require('../lib/opencode-install');
+
+const SRC = path.join(__dirname, '../../src');
+
+/**
+ * Spec command files installed for a platform. Claude ships spec-* commands;
+ * OpenCode generates its own command wrappers elsewhere.
+ */
+function getPlatformSpecFiles(platformKey, ctx) {
+  if (platformKey === 'claude') {
+    const manifestCommands = ctx.manifest?.commands?.core;
+    if (Array.isArray(manifestCommands)) {
+      return manifestCommands;
+    }
+    return [
+      'spec-init.md',
+      'spec-requirements.md',
+      'spec-design.md',
+      'spec-validate.md',
+      'spec-tasks.md',
+      'spec-status.md',
+      'code.md',
+      'test.md',
+      'docs.md'
+    ];
+  }
+  return [];
+}
+
+/** DEPENDENCY_TEMPLATES is empty by default; kept for parity/extensibility. */
+function ensureWorkflowDependencies(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const tracker = ctx.trackers[platformKey];
+  const commandTemplates = DEPENDENCY_TEMPLATES.commands[platformKey] || {};
+  Object.entries(commandTemplates).forEach(([fileName, content]) => {
+    if (!content) return;
+    const dest = path.join(platform.commandsDir, fileName);
+    if (!ctx.dryRun) {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, content, 'utf8');
+      tracker.record(dest);
+    }
+    report(ctx, 'created', `dependency: ${fileName}`);
+  });
+}
+
+function copyPlatformFiles(ctx, platformKey) {
+  const platform = PLATFORMS[platformKey];
+  const tracker = ctx.trackers[platformKey];
+  const platformFolder = platform.folder;
+
+  // For OpenCode, text bodies are path-normalized (.claude → .opencode, etc.).
+  const bodyTransform = platformKey === 'opencode'
+    ? getCopyOptions('opencode', {}).transform
+    : undefined;
+
+  const skillsSourceDir = path.join(SRC, 'claude/skills');
+  const agentsSourceDir = path.join(SRC, platform.sourceDir, 'agents');
+
+  if (!ctx.dryRun) {
+    fs.mkdirSync(platform.skillsDir, { recursive: true });
+    fs.mkdirSync(platform.agentsDir, { recursive: true });
+  }
+
+  // ── Skills ──────────────────────────────────────────────
+  if (fs.existsSync(skillsSourceDir)) {
+    const specSkillSource = path.join(skillsSourceDir, 'specs');
+    const specSkillDest = path.join(platform.skillsDir, 'specs');
+
+    if (fs.existsSync(specSkillSource)) {
+      const agg = copyManagedTree({
+        src: specSkillSource, dest: specSkillDest, platformFolder, ctx, tracker, transform: bodyTransform
+      });
+      ctx.results.installedSkills++;
+      report(ctx, treeAction(agg), 'Skill: specs');
+    }
+
+    // Keep spec templates in sync (Claude command runtime reads these).
+    if (platformKey === 'claude') {
+      const legacyInitTemplate = path.join(platform.skillsDir, 'specs', 'templates', 'init.json');
+      if (fs.existsSync(legacyInitTemplate)) {
+        if (!ctx.dryRun) fs.rmSync(legacyInitTemplate, { force: true });
+        ctx.ui.detail(`  ↻ ${ctx.dryRun ? '[dry-run] ' : ''}Removed legacy template: ${legacyInitTemplate}`);
+        ctx.results.updated++;
+      }
+
+      const specTemplates = [
+        'spec-state.json',
+        'requirements-init.md',
+        'requirements.md',
+        'design.md',
+        'research.md',
+        'task.md'
+      ];
+
+      specTemplates.forEach((fileName) => {
+        const src = path.join(specSkillSource, 'templates', fileName);
+        const dest = path.join(platform.skillsDir, 'specs', 'templates', fileName);
+        const { action } = writeManagedFile({ src, dest, platformFolder, ctx, tracker });
+        report(ctx, action, `template: ${fileName}`);
+      });
+    }
+
+    // Additional required skills.
+    let requiredSkills = [];
+    if (isClaudeCompatibleRuntime(platformKey)) {
+      requiredSkills = ctx.manifest?.skills?.required || [];
+    }
+    requiredSkills
+      .filter((skillName) => skillName !== 'specs')
+      .forEach((skillName) => {
+        const skillSource = path.join(skillsSourceDir, skillName);
+        const skillDest = path.join(platform.skillsDir, skillName);
+        if (fs.existsSync(skillSource)) {
+          const agg = copyManagedTree({
+            src: skillSource, dest: skillDest, platformFolder, ctx, tracker, transform: bodyTransform
+          });
+          ctx.results.installedSkills++;
+          report(ctx, treeAction(agg), `Skill: ${skillName}`);
+        } else {
+          report(ctx, 'missing', `skill: ${skillName}`);
+        }
+      });
+  }
+
+  // ── Agents + references + scripts ───────────────────────
+  if (isClaudeCompatibleRuntime(platformKey)) {
+    if (fs.existsSync(agentsSourceDir)) {
+      const requiredAgents = ctx.manifest?.agents?.required || [
+        'tester.md', 'code-reviewer.md', 'fullstack-developer.md', 'debugger.md'
+      ];
+      const agentTransform = platformKey === 'opencode'
+        ? (content, src) => convertOpenCodeAgentContent(content, path.basename(src))
+        : undefined;
+
+      requiredAgents.forEach((fileName) => {
+        const src = path.join(agentsSourceDir, fileName);
+        const dest = path.join(platform.agentsDir, fileName);
+        const { action } = writeManagedFile({
+          src, dest, platformFolder, ctx, tracker, transform: agentTransform
+        });
+        report(ctx, action, `agent: ${fileName}`);
+      });
+
+      const refsSource = path.join(SRC, platform.sourceDir, 'references');
+      if (fs.existsSync(refsSource)) {
+        const refsDest = getRuntimeSupportTargetDir(platformKey, 'references');
+        const agg = copyManagedTree({
+          src: refsSource, dest: refsDest, platformFolder, ctx, tracker, transform: bodyTransform
+        });
+        report(ctx, treeAction(agg), 'Agent reference manuals');
+      }
+    } else {
+      report(ctx, 'missing', `agents: ${platform.agentsDir}`);
+    }
+
+    const scriptsSourceDir = path.join(SRC, 'claude/scripts');
+    if (fs.existsSync(scriptsSourceDir)) {
+      const scriptsDest = getRuntimeSupportTargetDir(platformKey, 'scripts');
+      const agg = copyManagedTree({
+        src: scriptsSourceDir, dest: scriptsDest, platformFolder, ctx, tracker, transform: bodyTransform
+      });
+      report(ctx, treeAction(agg), 'Native scripts');
+    }
+  }
+
+  ensureWorkflowDependencies(ctx, platformKey);
+
+  // ── Commands ────────────────────────────────────────────
+  const sourceSubdir = platform.sourceSubdir || 'commands';
+  const commandsSourceDir = path.join(SRC, platform.sourceDir, sourceSubdir);
+  const specFiles = getPlatformSpecFiles(platformKey, ctx);
+
+  specFiles.forEach((file) => {
+    const src = path.join(commandsSourceDir, file);
+    const dest = path.join(platform.commandsDir, file);
+    if (!fs.existsSync(src)) {
+      ctx.ui.error(`Source file not found: ${file}`);
+      ctx.results.errors++;
+      return;
+    }
+    const cmdTransform = (content, s) => {
+      let c = content.replace(/\{\{SKILLS_DIR\}\}/g, platform.skillsRef);
+      if (platformKey === 'opencode') {
+        c = convertOpenCodeCommandContent(c, path.basename(s));
+      }
+      return c;
+    };
+    const { action } = writeManagedFile({
+      src, dest, platformFolder, ctx, tracker, transform: cmdTransform
+    });
+    report(ctx, action, file);
+  });
+
+  return ctx;
+}
+
+module.exports = { copyPlatformFiles, getPlatformSpecFiles };

package/bin/phases/opencode-runtime.js

@@ -0,0 +1,38 @@
+/**
+ * Phase: OpenCode runtime installation.
+ *
+ * Delegates to the existing opencode-install.js module (kept as-is) in the
+ * exact original order. These writers manage their own files (plugins, command
+ * templates, AGENTS.md, opencode.json) and honor the legacy `upgrade` option.
+ * In dry-run we skip them and report intent, since they are not dry-run aware.
+ */
+
+const {
+  copyOpenCodeSharedRuntimeFiles,
+  copyOpenCodePlugins,
+  copyOpenCodeCommandTemplates,
+  copyOpenCodeAgentsMdFile,
+  mergeOpenCodeConfig
+} = require('../lib/opencode-install');
+const { copyRulesDirectory } = require('./claude-runtime');
+
+function installOpenCodeRuntime(ctx, platformKey) {
+  if (platformKey !== 'opencode') return;
+
+  if (ctx.dryRun) {
+    ctx.ui.detail('  → [dry-run] OpenCode runtime (plugins, command templates, AGENTS.md, opencode.json) would be installed');
+    // rules/ is dry-run aware; still preview it.
+    copyRulesDirectory(ctx, platformKey);
+    return;
+  }
+
+  const { results, options } = ctx;
+  copyOpenCodeSharedRuntimeFiles(platformKey, results, options);
+  copyOpenCodePlugins(platformKey, results, options);
+  copyOpenCodeCommandTemplates(platformKey, results, options);
+  copyOpenCodeAgentsMdFile(platformKey, results, options);
+  copyRulesDirectory(ctx, platformKey);
+  mergeOpenCodeConfig(platformKey, results);
+}
+
+module.exports = { installOpenCodeRuntime };

package/bin/phases/post-install.js

@@ -0,0 +1,118 @@
+/**
+ * Phase: post-install runtime configuration.
+ *
+ * OpenCode model, optional Gemini 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.
+ *
+ * Note: CafeKit no longer installs the `gemini-cli` (the upstream package was
+ * removed). We only configure GEMINI_API_KEY, which the SDK-based skills
+ * (e.g. hapo:ai-multimodal) read directly.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { PLATFORMS } = require('../lib/context');
+const { setupOpenCodeModel } = require('../lib/opencode-install');
+
+/** Human assistant name for the active platform(s). */
+function assistantName(ctx) {
+  return ctx.platforms.includes('claude') ? 'Claude Code' : 'OpenCode';
+}
+
+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 setupGeminiKey(ctx) {
+  const apiKey = await ctx.ui.text(
+    { message: 'Gemini API key for AI skills (Enter to skip)', placeholder: 'aistudio.google.com/apikey' },
+    ''
+  );
+  if (apiKey && typeof apiKey === 'string' && apiKey.trim()) {
+    configureGeminiKey(ctx, apiKey.trim(), ctx.platforms);
+  }
+}
+
+function configureAddressing(ctx, userAddress) {
+  const claudeMdFile = path.join(process.cwd(), 'CLAUDE.md');
+  if (!fs.existsSync(claudeMdFile)) {
+    ctx.ui.warn('CLAUDE.md not found at project root; skipped addressing');
+    return;
+  }
+
+  const name = assistantName(ctx);
+  let content = fs.readFileSync(claudeMdFile, 'utf8');
+  const addressingSection = `## Addressing (Context Overflow Indicator)
+
+${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*$)/;
+  content = regex.test(content)
+    ? content.replace(regex, addressingSection)
+    : `${content.endsWith('\n') ? content : `${content}\n`}\n${addressingSection}\n`;
+
+  fs.writeFileSync(claudeMdFile, content, 'utf8');
+  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?', placeholder: 'e.g. boss, sir — Enter to skip' },
+    ''
+  );
+  if (ctx.ui.isCancel(answer)) return;
+  const userAddress = (answer || '').trim();
+  if (!userAddress) return;
+
+  if (/[^a-zA-ZÀ-ỹ\s]/.test(userAddress)) {
+    ctx.ui.warn('Invalid input (letters only); skipped addressing');
+    return;
+  }
+  configureAddressing(ctx, userAddress);
+}
+
+/** Run the post-install configuration sequence. */
+async function runPostInstall(ctx) {
+  if (ctx.dryRun) {
+    ctx.ui.info('[dry-run] Skipping OpenCode model / Gemini / addressing setup');
+    return ctx;
+  }
+
+  // OpenCode model uses its own readline; only run it when it won't block:
+  // interactive, or an env override is present (which it reads without prompting).
+  const hasModelEnv = Boolean(process.env.OPENCODE_MODEL || process.env.OPENCODE_DEFAULT_MODEL);
+  if (ctx.platforms.includes('opencode') && (ctx.interactive || hasModelEnv)) {
+    await setupOpenCodeModel(ctx.platforms, ctx.results);
+  }
+
+  await setupGeminiKey(ctx);
+  await setupAddressing(ctx);
+
+  // Re-record CLAUDE.md baseline so the installer-managed file (template +
+  // addressing) stays "pristine" and keeps receiving upstream updates.
+  if (ctx.platforms.includes('claude') && ctx.trackers.claude && fs.existsSync('CLAUDE.md')) {
+    ctx.trackers.claude.record('CLAUDE.md');
+    ctx.trackers.claude.write();
+  }
+  return ctx;
+}
+
+module.exports = { configureGeminiKey, configureAddressing, runPostInstall };

package/bin/phases/report.js

@@ -0,0 +1,66 @@
+/**
+ * Shared reporting helper for install phases.
+ *
+ * Maps an ownership-writer action to a UI update + results counter so every
+ * phase reports outcomes consistently. Routine create/update lines go to
+ * ctx.ui.detail (ephemeral spinner progress when interactive; plain log when
+ * not). Preserved/missing are surfaced more prominently.
+ */
+
+const SYMBOL = {
+  created: '✓',
+  updated: '↻',
+  unchanged: '→',
+  preserved: '⊘',
+  missing: '⚠'
+};
+
+/**
+ * Report a single file/group outcome.
+ *
+ * @param {object} ctx     run context (ui + results + dryRun)
+ * @param {string} action  'created'|'updated'|'unchanged'|'preserved'|'missing'
+ * @param {string} label   human label, e.g. "Skill: specs"
+ */
+function report(ctx, action, label) {
+  const prefix = ctx.dryRun ? '[dry-run] ' : '';
+  const sym = SYMBOL[action] || ' ';
+  const r = ctx.results;
+
+  switch (action) {
+    case 'created':
+      ctx.ui.detail(`  ${sym} ${prefix}${label}`);
+      r.copied++;
+      break;
+    case 'updated':
+      ctx.ui.detail(`  ${sym} ${prefix}${label}`);
+      r.updated++;
+      break;
+    case 'unchanged':
+      r.unchanged++;
+      break;
+    case 'preserved':
+      ctx.ui.detail(`  ${sym} ${prefix}preserved (user-modified): ${label}`);
+      r.preserved++;
+      break;
+    case 'missing':
+      ctx.ui.warn(`${prefix}Missing: ${label}`);
+      r.missingDependencies++;
+      break;
+    default:
+      break;
+  }
+}
+
+/**
+ * Pick the dominant action for a tree-copy aggregate, for a single summary line.
+ * created wins over updated wins over preserved wins over unchanged.
+ */
+function treeAction(agg) {
+  if (agg.created > 0) return 'created';
+  if (agg.updated > 0) return 'updated';
+  if (agg.preserved > 0) return 'preserved';
+  return 'unchanged';
+}
+
+module.exports = { SYMBOL, report, treeAction };

package/bin/phases/root-config.js

@@ -0,0 +1,49 @@
+/**
+ * Phase: root project configuration (.gitignore).
+ *
+ * Ensures the root .gitignore carries CafeKit-managed patterns, including the
+ * new install backup dir and lock file so they never get committed. Honors dry-run.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function ensureGitignore(ctx) {
+  const gitignorePath = path.join(process.cwd(), '.gitignore');
+  const header = '# CafeKit / Ecosystem';
+  const patterns = [
+    'specs/_shared/',
+    'plans/',
+    '!plans/templates/',
+    '.cafekit-backup/',
+    '.cafekit.lock'
+  ];
+  const prefix = ctx.dryRun ? '[dry-run] ' : '';
+
+  if (!fs.existsSync(gitignorePath)) {
+    const content = ['# Git Ignore', '', header, ...patterns, ''].join('\n');
+    if (!ctx.dryRun) fs.writeFileSync(gitignorePath, content, 'utf8');
+    ctx.ui.detail(`  ✓ ${prefix}.gitignore created at root`);
+    ctx.results.copied++;
+    return;
+  }
+
+  const content = fs.readFileSync(gitignorePath, 'utf8');
+  const lines = content.split('\n').map((l) => l.trim());
+  const missing = patterns.filter((p) => !lines.includes(p));
+
+  if (missing.length > 0) {
+    let newContent = content;
+    if (!newContent.endsWith('\n')) newContent += '\n';
+    if (!content.includes(header)) newContent += `\n${header}\n`;
+    newContent += missing.join('\n') + '\n';
+    if (!ctx.dryRun) fs.writeFileSync(gitignorePath, newContent, 'utf8');
+    ctx.ui.detail(`  ↻ ${prefix}.gitignore updated: added ${missing.join(', ')}`);
+    ctx.results.updated++;
+  } else {
+    ctx.ui.detail(`  → ${prefix}.gitignore already up to date`);
+    ctx.results.skipped++;
+  }
+}
+
+module.exports = { ensureGitignore };