claude-code-superkit 0.0.0-stage → 1.5.3

package/lib/installer.js

@@ -0,0 +1,499 @@
+import { existsSync, mkdirSync, renameSync, rmSync, writeFileSync, readFileSync, chmodSync, readdirSync, statSync } from 'node:fs';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { info, warn, fail, bold, copyFile, copyDir, copySkills, countFiles, countSkills, isInsideGitRepo, getGitRoot, commandExists } from './utils.js';
+import { confirm, select, multiConfirm, closeRL } from './prompts.js';
+import { writeSettings } from './settings-builder.js';
+import { checkAndInstallSuperpowers } from './superpowers.js';
+import { scaffoldDocs } from './docs-scaffold.js';
+import { installCodex } from './codex.js';
+import { validate } from './validator.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGES_DIR = join(__dirname, '..', 'packages');
+
+// ── Internal-file manifest (single source of truth) ──────────────────────
+// packages/core/INTERNAL-FILES lists repo-only files that must NEVER ship into
+// a consumer's .claude/. We derive the per-category skip lists from it so this
+// installer, superkit-counts-verify.sh, and superkit-update.sh can never drift.
+// Returns { hooks: [...basenames], rules: [...basenames] } keyed by each entry's
+// dirname. FALLBACK: if the manifest is missing/unreadable/empty we return the
+// previous hard-coded values — a broken installer is worse than a stale list.
+// The literals below live ONLY inside this clearly-marked fallback.
+function readInternalManifest() {
+  const FALLBACK = { hooks: ['superkit-counts-verify.sh', 'verify-hooks.sh'], rules: ['superkit-integrity.md'] }; // FALLBACK — sole hard-coded copy
+  try {
+    const raw = readFileSync(join(PACKAGES_DIR, 'core', 'INTERNAL-FILES'), 'utf8');
+    const hooks = [];
+    const rules = [];
+    for (const line of raw.split('\n')) {
+      const entry = line.trim();
+      if (!entry || entry.startsWith('#')) continue;
+      const dir = dirname(entry);
+      const base = basename(entry);
+      if (dir === 'hooks') hooks.push(base);
+      else if (dir === 'rules') rules.push(base);
+    }
+    if (hooks.length === 0 && rules.length === 0) return FALLBACK; // FALLBACK — empty/garbled manifest
+    return { hooks, rules };
+  } catch {
+    return FALLBACK; // FALLBACK — manifest missing/unreadable
+  }
+}
+
+export async function install(opts) {
+  const version = opts.version;
+  const useDefaults = opts.defaults;
+
+  console.log('');
+  console.log(`🚀 claude-code-superkit v${version}`);
+  console.log('');
+
+  // ── Prerequisites ────────────────────────────────────────
+  if (!commandExists('git')) {
+    fail('git is required but not found. Install git first.');
+  }
+
+  if (!isInsideGitRepo()) {
+    fail('Not inside a git repository. Run from your project root: cd /path/to/your-project && git init');
+  }
+
+  const projectDir = getGitRoot();
+  if (opts.codexOnly) {
+    installCodex(projectDir, PACKAGES_DIR);
+    info('Codex installation complete!');
+    console.log('  Start Codex in your project and review AGENTS.md and .codex/config.toml.');
+    console.log('  Re-run this command to update pristine Superkit skills; review any preserved conflicts.');
+    closeRL();
+    return;
+  }
+
+  if (!commandExists('claude')) {
+    warn('Claude Code CLI not found. Install: npm install -g @anthropic-ai/claude-code');
+    warn('Superkit requires Claude Code to function. Continuing setup anyway...');
+  }
+
+  const claudeDir = join(projectDir, '.claude');
+
+  // ── Superpowers ──────────────────────────────────────────
+  if (!opts.noSuperpowers) {
+    await checkAndInstallSuperpowers(useDefaults);
+  }
+
+  // ── Handle existing .claude/ ─────────────────────────────
+  let mode;
+  if (existsSync(claudeDir)) {
+    if (useDefaults) {
+      mode = 'merge';
+    } else {
+      console.log('');
+      warn('Existing .claude/ directory found.');
+      mode = await select('', [
+        { key: 'm', label: 'Merge — add new files, skip existing', value: 'merge' },
+        { key: 'o', label: 'Overwrite — backup to .claude.bak/ and replace', value: 'overwrite' },
+        { key: 'a', label: 'Abort', value: 'abort' }
+      ], 'merge', false);
+    }
+
+    if (mode === 'abort') {
+      console.log('Aborted.');
+      closeRL();
+      return;
+    }
+
+    if (mode === 'overwrite') {
+      const bakDir = claudeDir + '.bak';
+      if (existsSync(bakDir)) rmSync(bakDir, { recursive: true });
+      renameSync(claudeDir, bakDir);
+      info('Backed up to .claude.bak/');
+    }
+  } else {
+    mode = 'fresh';
+  }
+
+  // ── [1/4] Stack Selection ────────────────────────────────
+  let stacks;
+  if (opts.stacks) {
+    stacks = opts.stacks;
+  } else {
+    stacks = await multiConfirm('[1/4] Select your stacks:', [
+      { label: 'Go?         [y/N]', value: 'go' },
+      { label: 'TypeScript?  [y/N]', value: 'typescript' },
+      { label: 'Python?      [y/N]', value: 'python' },
+      { label: 'Rust?        [y/N]', value: 'rust' },
+      { label: 'Frontend 3D? [y/N]', value: 'frontend-3d' },
+      { label: 'Frontend UI? [y/N]', value: 'frontend-ui' }
+    ], useDefaults);
+  }
+
+  // ── [2/4] Extras Selection ───────────────────────────────
+  let extras;
+  if (opts.extras) {
+    extras = opts.extras;
+  } else {
+    extras = await multiConfirm('[2/4] Select extras:', [
+      { label: 'Bot reviewer (Telegram/Discord/Slack)?  [y/N]', value: 'bot-reviewer' },
+      { label: 'Design system reviewer?                  [y/N]', value: 'design-system-reviewer' }
+    ], useDefaults);
+  }
+
+  // ── [3/4] Profile Selection ──────────────────────────────
+  let profile;
+  if (opts.profile) {
+    profile = opts.profile;
+  } else {
+    profile = await select('[3/4] Select hook profile:', [
+      { key: 'f', label: 'fast     — minimal checks, maximum speed', value: 'fast' },
+      { key: 's', label: 'standard — balanced (default)', value: 'standard' },
+      { key: 'x', label: 'strict   — everything including vet/check on each edit', value: 'strict' }
+    ], 'standard', useDefaults);
+  }
+
+  // ── [4/4] Plugin Selection ───────────────────────────────
+  console.log('');
+  console.log('[4/4] Claude Code plugins:');
+  console.log('');
+  console.log('  Base plugins (always enabled):');
+  console.log('    ✓ superpowers  — TDD, brainstorming, debugging, verification');
+  console.log('    ✓ github       — PR comments, issue tracking (/review --comment)');
+  console.log('    ✓ context7     — library documentation lookup');
+  console.log('    ✓ code-review  — enhanced code review workflows');
+  console.log('');
+  console.log('  Optional plugins:');
+
+  let optionalPlugins;
+  if (opts.plugins) {
+    optionalPlugins = opts.plugins;
+  } else {
+    const pluginItems = [
+      { label: 'code-simplifier (code cleanup/refactoring)?    [y/N]', value: 'code-simplifier' },
+      { label: 'playwright (browser automation, e2e tests)?    [y/N]', value: 'playwright' }
+    ];
+
+    if (stacks.includes('typescript')) {
+      pluginItems.push({
+        label: 'frontend-design (UI/design assistance)?       [Y/n]',
+        value: 'frontend-design',
+        defaultYes: true
+      });
+    } else {
+      pluginItems.push({
+        label: 'frontend-design (UI/design assistance)?       [y/N]',
+        value: 'frontend-design'
+      });
+    }
+
+    optionalPlugins = await multiConfirm('', pluginItems, useDefaults);
+  }
+
+  // ── Install ──────────────────────────────────────────────
+  console.log('');
+  console.log('Installing...');
+
+  // Core agents
+  const agentCount = copyDir(
+    join(PACKAGES_DIR, 'core', 'agents'),
+    join(claudeDir, 'agents'),
+    mode, '.md'
+  );
+  info(`Copied ${agentCount} agents → .claude/agents/`);
+
+  // Core commands
+  const cmdCount = copyDir(
+    join(PACKAGES_DIR, 'core', 'commands'),
+    join(claudeDir, 'commands'),
+    mode, '.md'
+  );
+  info(`Copied ${cmdCount} commands → .claude/commands/`);
+
+  // Core hooks + rules: exclude superkit-internal files (repo-only tooling that
+  // never ships). Both skip lists derive from the packages/core/INTERNAL-FILES
+  // manifest so this installer stays in sync with the other two consumers.
+  const { hooks: SUPERKIT_INTERNAL_HOOKS, rules: SUPERKIT_INTERNAL_RULES } = readInternalManifest();
+  const hooksDir = join(claudeDir, 'scripts', 'hooks');
+  mkdirSync(hooksDir, { recursive: true });
+  let hookCount = 0;
+  const coreHooksDir = join(PACKAGES_DIR, 'core', 'hooks');
+  if (existsSync(coreHooksDir)) {
+    for (const file of readdirSync(coreHooksDir)) {
+      if (!file.endsWith('.sh') && !file.endsWith('.py')) continue;
+      if (SUPERKIT_INTERNAL_HOOKS.includes(file)) continue;
+      if (copyFile(join(coreHooksDir, file), join(hooksDir, file), mode)) hookCount++;
+    }
+  }
+
+  // Shared hook library (profile.sh — unified profile + disable helper)
+  const coreHookLibDir = join(coreHooksDir, 'lib');
+  if (existsSync(coreHookLibDir)) {
+    const destLibDir = join(hooksDir, 'lib');
+    mkdirSync(destLibDir, { recursive: true });
+    for (const file of readdirSync(coreHookLibDir)) {
+      if (!file.endsWith('.sh')) continue;
+      copyFile(join(coreHookLibDir, file), join(destLibDir, file), mode);
+    }
+  }
+
+  // Core rules (exclude superkit-internal rules that reference packages/core/;
+  // SUPERKIT_INTERNAL_RULES was derived from the manifest above)
+  const coreRuleCount = copyDir(join(PACKAGES_DIR, 'core', 'rules'), join(claudeDir, 'rules'), mode, '.md', SUPERKIT_INTERNAL_RULES);
+
+  // Core skills
+  const coreSkillCount = copySkills(join(PACKAGES_DIR, 'core', 'skills'), join(claudeDir, 'skills'), mode);
+
+  // Stack agents
+  let stackAgentCount = 0;
+  for (const stack of stacks) {
+    const stackAgentDir = join(PACKAGES_DIR, 'stack-agents', stack);
+    if (existsSync(stackAgentDir)) {
+      stackAgentCount += copyDir(stackAgentDir, join(claudeDir, 'agents'), mode, '.md');
+      // Copy references/ subdirectory if present (on-demand knowledge docs for agents)
+      const refsDir = join(stackAgentDir, 'references');
+      if (existsSync(refsDir)) {
+        const destRefsDir = join(claudeDir, 'agents', 'references');
+        mkdirSync(destRefsDir, { recursive: true });
+        let refCount = 0;
+        for (const refFile of readdirSync(refsDir)) {
+          if (!refFile.endsWith('.md')) continue;
+          if (copyFile(join(refsDir, refFile), join(destRefsDir, refFile), mode)) refCount++;
+        }
+        if (refCount > 0) info(`  Copied ${refCount} reference docs → .claude/agents/references/`);
+      }
+    }
+  }
+
+  // Stack hooks
+  let stackHookCount = 0;
+  for (const stack of stacks) {
+    const stackHookDir = join(PACKAGES_DIR, 'stack-hooks', stack);
+    if (existsSync(stackHookDir)) {
+      for (const file of readdirSync(stackHookDir)) {
+        if (!file.endsWith('.sh')) continue;
+        if (copyFile(join(stackHookDir, file), join(hooksDir, file), mode)) stackHookCount++;
+      }
+    }
+  }
+
+  // Note: totalHooks computed after self-contained packages to include all hooks
+
+  // Stack rules
+  let stackRuleCount = 0;
+  for (const stack of stacks) {
+    const stackRuleDir = join(PACKAGES_DIR, 'stack-rules', stack);
+    if (existsSync(stackRuleDir)) {
+      stackRuleCount += copyDir(stackRuleDir, join(claudeDir, 'rules'), mode, '.md');
+    }
+  }
+  if (stackRuleCount > 0) info(`Copied ${stackRuleCount} stack rules → .claude/rules/`);
+
+  // Self-contained packages (frontend-3d / frontend-ui have agents, hooks, skills, rules, commands in one dir)
+  const SELF_CONTAINED_PACKAGES = ['frontend-3d', 'frontend-ui'];
+  let packageSkillCount = 0;
+  let packageCmdCount = 0;
+  for (const stack of stacks) {
+    if (!SELF_CONTAINED_PACKAGES.includes(stack)) continue;
+    const pkgDir = join(PACKAGES_DIR, stack);
+    if (!existsSync(pkgDir)) continue;
+
+    // Package agents
+    const pkgAgentDir = join(pkgDir, 'agents');
+    if (existsSync(pkgAgentDir)) {
+      stackAgentCount += copyDir(pkgAgentDir, join(claudeDir, 'agents'), mode, '.md');
+    }
+
+    // Package hooks
+    const pkgHookDir = join(pkgDir, 'hooks');
+    if (existsSync(pkgHookDir)) {
+      for (const file of readdirSync(pkgHookDir)) {
+        if (!file.endsWith('.sh')) continue;
+        if (copyFile(join(pkgHookDir, file), join(hooksDir, file), mode)) stackHookCount++;
+      }
+    }
+
+    // Package skills
+    const pkgSkillDir = join(pkgDir, 'skills');
+    if (existsSync(pkgSkillDir)) {
+      packageSkillCount += copySkills(pkgSkillDir, join(claudeDir, 'skills'), mode);
+    }
+
+    // Package rules
+    const pkgRuleDir = join(pkgDir, 'rules');
+    if (existsSync(pkgRuleDir)) {
+      stackRuleCount += copyDir(pkgRuleDir, join(claudeDir, 'rules'), mode, '.md');
+    }
+
+    // Package commands
+    const pkgCmdDir = join(pkgDir, 'commands');
+    if (existsSync(pkgCmdDir)) {
+      packageCmdCount += copyDir(pkgCmdDir, join(claudeDir, 'commands'), mode, '.md');
+    }
+  }
+  if (packageSkillCount > 0) info(`Copied ${packageSkillCount} package skills → .claude/skills/`);
+  if (packageCmdCount > 0) info(`Copied ${packageCmdCount} package commands → .claude/commands/`);
+
+  // Hook count summary (after all sources: core + stack + self-contained)
+  const totalHooks = hookCount + stackHookCount;
+  info(`Copied ${totalHooks} hooks → .claude/scripts/hooks/ (${hookCount} core + ${stackHookCount} stack)`);
+
+  // Extras
+  let extraCount = 0;
+  for (const extra of extras) {
+    const extraFile = join(PACKAGES_DIR, 'extras', `${extra}.md`);
+    if (existsSync(extraFile)) {
+      if (copyFile(extraFile, join(claudeDir, 'agents', `${extra}.md`), mode)) extraCount++;
+    }
+  }
+  if (extraCount > 0) info(`Copied ${extraCount} extras → .claude/agents/`);
+  if (stackAgentCount > 0) info(`Copied ${stackAgentCount} stack agents → .claude/agents/`);
+
+  // Make hooks executable (Unix only)
+  if (process.platform !== 'win32' && existsSync(hooksDir)) {
+    for (const file of readdirSync(hooksDir)) {
+      if (!file.endsWith('.sh') && !file.endsWith('.py')) continue;
+      try {
+        chmodSync(join(hooksDir, file), 0o755);
+      } catch { /* skip */ }
+    }
+    // Shared library helpers under .claude/scripts/hooks/lib/
+    const libDir = join(hooksDir, 'lib');
+    if (existsSync(libDir)) {
+      for (const file of readdirSync(libDir)) {
+        if (!file.endsWith('.sh')) continue;
+        try {
+          chmodSync(join(libDir, file), 0o755);
+        } catch { /* skip */ }
+      }
+    }
+  }
+
+  // Statusline helper
+  const statuslineSrc = join(PACKAGES_DIR, 'core', 'helpers', 'statusline.cjs');
+  const scriptsDir = join(claudeDir, 'scripts');
+  mkdirSync(scriptsDir, { recursive: true });
+  if (existsSync(statuslineSrc)) {
+    copyFile(statuslineSrc, join(scriptsDir, 'statusline.cjs'), mode);
+    info('Copied statusline → .claude/scripts/statusline.cjs');
+  }
+
+  // ── Build settings.json ──────────────────────────────────
+  const settingsResult = writeSettings(
+    join(PACKAGES_DIR, 'core', 'settings.json'),
+    join(claudeDir, 'settings.json'),
+    PACKAGES_DIR,
+    stacks,
+    optionalPlugins
+  );
+  info(`Built settings.json with ${profile} profile hooks + ${settingsResult.pluginCount} plugins`);
+
+  // ── CLAUDE.md template ──────────────────────────────────
+  const claudeMdDst = join(projectDir, 'CLAUDE.md');
+  if (!existsSync(claudeMdDst) || mode !== 'merge') {
+    copyFile(join(PACKAGES_DIR, 'core', 'CLAUDE.md'), claudeMdDst, 'fresh');
+    info('Created CLAUDE.md template');
+  } else {
+    warn('CLAUDE.md already exists — skipped (merge mode)');
+  }
+
+  // ── ADR template (unconditional, idempotent) ─────────────
+  // dev.md Phase 2 and superkit-init.md reference docs-templates/adr-template.md
+  // at the PROJECT root. Install it always — even when the docs scaffold below is
+  // declined — so the nudge never dangles. NEVER overwrite an existing copy:
+  // it's a doc template consumers legitimately edit.
+  const adrSrc = join(PACKAGES_DIR, 'core', 'docs-templates', 'adr-template.md');
+  const adrDst = join(projectDir, 'docs-templates', 'adr-template.md');
+  if (existsSync(adrSrc) && !existsSync(adrDst)) {
+    copyFile(adrSrc, adrDst, 'fresh');
+    info('Copied ADR template → docs-templates/adr-template.md');
+  }
+
+  // ── Documentation scaffolding ────────────────────────────
+  if (!opts.noDocs) {
+    console.log('');
+    console.log('  All agents use Phase 0 — they read docs/architecture/ before reviewing.');
+    console.log('  Without these docs, agents work blind and produce less accurate reviews.');
+    console.log('  This step creates architecture templates (fill TODOs later) and a project tree.');
+    console.log('');
+
+    const createDocs = await confirm('Initialize documentation structure? (recommended)', true, useDefaults);
+    if (createDocs) {
+      scaffoldDocs(projectDir, PACKAGES_DIR, mode);
+    }
+  }
+
+  // ── Codex CLI ────────────────────────────────────────────
+  let codexInstalled = false;
+  let codexSkillCount = 0;
+  console.log('');
+  const installCodexFlag = opts.codex ?? await confirm('Also install for Codex CLI?', false, useDefaults);
+  if (installCodexFlag) {
+    codexSkillCount = installCodex(projectDir, PACKAGES_DIR);
+    codexInstalled = true;
+  }
+
+  // ── Validation ───────────────────────────────────────────
+  console.log('');
+  const validationOk = validate(claudeDir, projectDir);
+  console.log('');
+  if (validationOk) {
+    info('All validation checks passed');
+  } else {
+    warn('Some validation checks failed — review warnings above');
+  }
+
+  // ── Save superkit meta ───────────────────────────────────
+  const metaPath = join(claudeDir, '.superkit-meta');
+  const scriptDir = join(__dirname, '..');
+  const metaContent = [
+    `SUPERKIT_SOURCE="${scriptDir}"`,
+    `SUPERKIT_VERSION="${version}"`,
+    `SUPERKIT_STACKS="${stacks.join(' ')}"`,
+    `SUPERKIT_EXTRAS="${extras.join(' ')}"`,
+    `SUPERKIT_PROFILE="${profile}"`,
+    `SUPERKIT_INSTALLED="${new Date().toISOString()}"`,
+    ''
+  ].join('\n');
+  writeFileSync(metaPath, metaContent);
+  info('Saved superkit source path for auto-updates → .claude/.superkit-meta');
+
+  // ── Summary ──────────────────────────────────────────────
+  const totalAgents = agentCount + stackAgentCount + extraCount;
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  info('Installation complete!');
+  console.log('');
+  console.log('  Claude Code:');
+  console.log(`    Agents:   ${totalAgents} (${agentCount} core + ${stackAgentCount} stack + ${extraCount} extras)`);
+  console.log(`    Commands: ${cmdCount + packageCmdCount}`);
+  console.log(`    Hooks:    ${totalHooks} + Stop prompt`);
+  console.log(`    Rules:    ${coreRuleCount + stackRuleCount}`);
+  console.log(`    Skills:   ${coreSkillCount + packageSkillCount}`);
+  console.log(`    Plugins:  ${settingsResult.pluginCount}`);
+  console.log(`    Profile:  ${profile}`);
+
+  if (codexInstalled) {
+    console.log('');
+    console.log('  Codex CLI:');
+    console.log(`    Skills:   ${codexSkillCount} (copied to .codex/skills/)`);
+    console.log('    Template defaults: gpt-6-astra/high; subagent gpt-5.6-sol/medium');
+    console.log('    Config:   .codex/config.toml');
+    console.log('    Docs:     AGENTS.md');
+  }
+
+  console.log('');
+  console.log('  Next steps:');
+  console.log('    1. Run: claude');
+  console.log('    2. Run: /superkit-init  ← intelligent project setup (auto-fills docs!)');
+  console.log('    3. Install plugins: /plugins → install missing');
+  console.log('    4. Try: /review or /audit');
+  console.log('');
+  console.log('  💡 /superkit-init scans your code and generates FILLED docs —');
+  console.log('     no more manual TODO filling! Use --non-interactive for quick setup.');
+  console.log('');
+  console.log('  ⚠ Plugins are ENABLED in settings.json but may need to be');
+  console.log('    installed first. Open Claude Code → /plugins → install:');
+
+  const allPlugins = ['superpowers', 'github', 'context7', 'code-review', ...optionalPlugins];
+  console.log(`    ${allPlugins.join(', ')}`);
+  console.log('');
+
+  closeRL();
+}

package/lib/prompts.js

@@ -0,0 +1,51 @@
+import * as readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+
+let rl = null;
+
+function getRL() {
+  if (!rl) {
+    rl = readline.createInterface({ input, output });
+  }
+  return rl;
+}
+
+export function closeRL() {
+  if (rl) {
+    rl.close();
+    rl = null;
+  }
+}
+
+export async function confirm(question, defaultYes = false, useDefaults = false) {
+  if (useDefaults) return defaultYes;
+  const hint = defaultYes ? '[Y/n]' : '[y/N]';
+  const answer = await getRL().question(`${question} ${hint} `);
+  if (!answer.trim()) return defaultYes;
+  return /^y(es)?$/i.test(answer.trim());
+}
+
+export async function select(prompt, options, defaultValue, useDefaults = false) {
+  if (useDefaults) return defaultValue;
+
+  console.log(`\n${prompt}`);
+  for (const opt of options) {
+    const marker = opt.value === defaultValue ? ' (default)' : '';
+    console.log(`  [${opt.key}] ${opt.label}${marker}`);
+  }
+
+  const answer = await getRL().question('  Choice: ');
+  const trimmed = answer.trim().toLowerCase();
+  const match = options.find(o => o.key.toLowerCase() === trimmed);
+  return match ? match.value : defaultValue;
+}
+
+export async function multiConfirm(header, items, useDefaults = false) {
+  if (header) console.log(`\n${header}`);
+  const selected = [];
+  for (const item of items) {
+    const yes = await confirm(`  ${item.label}`, item.defaultYes || false, useDefaults);
+    if (yes) selected.push(item.value);
+  }
+  return selected;
+}

package/lib/settings-builder.js

@@ -0,0 +1,51 @@
+import { readFileSync, writeFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function buildSettings(baseSettings, stackHookFiles, optionalPlugins) {
+  const settings = JSON.parse(JSON.stringify(baseSettings));
+
+  const existingCommands = new Set(
+    settings.hooks.PostToolUse[0].hooks.map(h => h.command)
+  );
+  for (const hookFile of [...new Set(stackHookFiles)]) {
+    const command = `"$CLAUDE_PROJECT_DIR"/.claude/scripts/hooks/${hookFile}`;
+    if (existingCommands.has(command)) continue;
+    existingCommands.add(command);
+    settings.hooks.PostToolUse[0].hooks.push({ type: 'command', command });
+  }
+
+  for (const plugin of optionalPlugins) {
+    settings.enabledPlugins[`${plugin}@claude-plugins-official`] = true;
+  }
+
+  return settings;
+}
+
+export function collectStackHooks(packagesDir, stacks) {
+  const hooks = [];
+  for (const stack of stacks) {
+    // Standard pattern: packages/stack-hooks/{stack}/
+    const standardDir = join(packagesDir, 'stack-hooks', stack);
+    // Self-contained pattern: packages/{stack}/hooks/
+    const packageDir = join(packagesDir, stack, 'hooks');
+
+    for (const hookDir of [standardDir, packageDir]) {
+      if (!existsSync(hookDir)) continue;
+      for (const file of readdirSync(hookDir)) {
+        if (file.endsWith('.sh')) hooks.push(file);
+      }
+    }
+  }
+  return hooks;
+}
+
+export function writeSettings(baseSettingsPath, destPath, packagesDir, stacks, optionalPlugins) {
+  const base = JSON.parse(readFileSync(baseSettingsPath, 'utf8'));
+  const stackHooks = collectStackHooks(packagesDir, stacks);
+  const settings = buildSettings(base, stackHooks, optionalPlugins);
+  writeFileSync(destPath, JSON.stringify(settings, null, 2) + '\n');
+  return {
+    pluginCount: Object.keys(settings.enabledPlugins).length,
+    stackHookCount: stackHooks.length
+  };
+}