specpipe 1.0.0

package/src/commands/init.js

@@ -0,0 +1,311 @@
+import { resolve, dirname } from 'node:path';
+import { existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { log } from '../lib/logger.js';
+import { detectProject } from '../lib/detector.js';
+import { writeManifest, createManifest, setFileEntry, readManifest, mergeAgents } from '../lib/manifest.js';
+import { hashFile, hashContent } from '../lib/hasher.js';
+import { readFile } from 'node:fs/promises';
+import { computeDesired } from '../lib/reconcile.js';
+import {
+  getAllFiles, getFilesForComponents, installFile,
+  ensurePlaceholderDir, setPermissions, fillTemplate,
+  verifySettingsJson, PLACEHOLDER_DIRS, COMPONENTS,
+  getTemplateDir, installSkillForAgent,
+} from '../lib/installer.js';
+import { AGENTS, parseSkillPath } from '../lib/agents.js';
+import { initMultiAgent } from './init-agents.js';
+import { adoptExisting } from './init-adopt.js';
+import { readGlobalManifest, writeGlobalManifest, initGlobal } from './init-global.js';
+
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
+
+export async function initCommand(path, opts) {
+  const targetDir = resolve(path);
+
+  if (!existsSync(targetDir)) {
+    log.fail(`Directory not found: ${targetDir}`);
+    process.exit(1);
+  }
+
+  log.info(`specpipe v${pkg.version}`);
+  log.info(`Target: ${targetDir}`);
+  log.blank();
+
+  // --- Global mode ---
+  if (opts.global) {
+    await initGlobal({ force: opts.force, hooks: true });
+    return;
+  }
+
+  // --- Adopt mode ---
+  if (opts.adopt) {
+    await adoptExisting(targetDir);
+    return;
+  }
+
+  // --- Prerequisites ---
+  let warnings = 0;
+
+  if (!commandExists('git')) {
+    log.fail('Git not found — required');
+    process.exit(1);
+  }
+
+  if (!commandExists('node')) {
+    log.warn('Node.js not found — file-guard.js hook requires it');
+    warnings++;
+  }
+
+  if (!existsSync(resolve(targetDir, '.git'))) {
+    log.warn('Not a git repository. Some features need git.');
+    warnings++;
+  }
+
+  // --- Multi-agent install (opt-in via --agents) ---
+  if (opts.agents) {
+    await initMultiAgent(targetDir, opts, warnings);
+    return;
+  }
+
+  // --- Determine files to install ---
+  let components = Object.keys(COMPONENTS);
+  if (opts.only) {
+    components = opts.only.split(',').map((c) => c.trim());
+    const valid = Object.keys(COMPONENTS);
+    for (const c of components) {
+      if (!valid.includes(c)) {
+        log.fail(`Unknown component: ${c}. Valid: ${valid.join(', ')}`);
+        process.exit(1);
+      }
+    }
+  }
+
+  const files = opts.only ? getFilesForComponents(components) : getAllFiles();
+
+  // --- Dry run ---
+  if (opts.dryRun) {
+    log.info('Dry run — no changes will be made');
+    log.blank();
+    for (const file of files) {
+      const sk = parseSkillPath(file);
+      const rel = sk ? AGENTS.claude.skillTarget(sk.skill, sk.inner) : file;
+      const dst = resolve(targetDir, rel);
+      if (existsSync(dst) && !opts.force) {
+        log.skip(`${rel} (exists)`);
+      } else {
+        log.copy(`${rel} (would copy)`);
+      }
+    }
+    return;
+  }
+
+  // --- Install files ---
+  console.log('--- Installing ---');
+
+  const manifest = createManifest(pkg.version, null, components);
+  let copied = 0;
+  let skipped = 0;
+  let identical = 0;
+
+  for (const file of files) {
+    // Skills are emitted through the Claude target (canonical skills/ → .claude/skills/);
+    // hooks/config/docs are copied verbatim at their own path.
+    const isSkill = !!parseSkillPath(file);
+    let outPath = file;
+    if (isSkill) {
+      const { result, path } = await installSkillForAgent('claude', file, targetDir, { force: opts.force });
+      outPath = path || file;
+      if (result === 'copied') copied++;
+      else if (result === 'identical') identical++;
+      else skipped++;
+    } else {
+      const result = await installFile(file, targetDir, { force: opts.force });
+      if (result === 'copied') copied++;
+      else if (result === 'identical') identical++;
+      else skipped++;
+    }
+
+    // Record in manifest (keyed by on-disk path; Claude emit is byte-identical to source).
+    const kitHash = await hashFile(resolve(getTemplateDir(), file));
+    let installedHash = kitHash;
+    try {
+      installedHash = await hashFile(resolve(targetDir, outPath));
+    } catch { /* file might not exist if skipped */ }
+    setFileEntry(manifest, outPath, kitHash, installedHash, { agent: 'claude', templateRel: file });
+  }
+
+  // Accumulate: keep agents installed by an earlier run so a plain `init` doesn't
+  // orphan files from a prior `init --agents …`. Record their on-disk files too.
+  const prior = await readManifest(targetDir);
+  manifest.agents = mergeAgents(prior?.agents, ['claude']);
+  for (const [relPath, d] of await computeDesired(manifest.agents.filter((a) => a !== 'claude'))) {
+    if (manifest.files[relPath]) continue;
+    try {
+      const installedHash = hashContent(await readFile(resolve(targetDir, relPath), 'utf-8'));
+      setFileEntry(manifest, relPath, d.kitHash, installedHash, { agent: d.agent, templateRel: d.templateRel });
+    } catch { /* prior agent's file not on disk — don't record a phantom */ }
+  }
+
+  // Placeholder directories
+  for (const dir of PLACEHOLDER_DIRS) {
+    await ensurePlaceholderDir(dir, targetDir);
+  }
+
+  // --- Permissions ---
+  await setPermissions(targetDir);
+
+  // --- Project detection ---
+  log.blank();
+  console.log('--- Detecting project ---');
+
+  const projectInfo = detectProject(targetDir);
+  if (projectInfo) {
+    log.info(`Detected: ${projectInfo.lang} (${projectInfo.framework})`);
+    log.info(`Source: ${projectInfo.srcDir} | Tests: ${projectInfo.testDir}`);
+    manifest.projectType = { lang: projectInfo.lang, framework: projectInfo.framework };
+
+    await fillTemplate(targetDir, projectInfo);
+    log.info('Updated CLAUDE.md with project info');
+
+    // Re-hash CLAUDE.md after template fill
+    try {
+      const claudeHash = await hashFile(resolve(targetDir, '.claude/CLAUDE.md'));
+      if (manifest.files['.claude/CLAUDE.md']) {
+        manifest.files['.claude/CLAUDE.md'].installedHash = claudeHash;
+        manifest.files['.claude/CLAUDE.md'].customized = false; // Template fill is not "customization"
+      }
+    } catch { /* */ }
+  } else {
+    log.warn('Could not detect project type. Fill in CLAUDE.md manually.');
+    warnings++;
+  }
+
+  // --- Write manifest ---
+  await writeManifest(targetDir, manifest);
+
+  // --- Verification ---
+  log.blank();
+  console.log('--- Verification ---');
+
+  if (await verifySettingsJson(targetDir)) {
+    log.pass('settings.json is valid JSON');
+  } else {
+    log.fail('settings.json is invalid JSON');
+  }
+
+  // --- Summary ---
+  log.blank();
+  console.log('=== Setup Complete ===');
+  log.blank();
+  console.log('Installed:');
+  console.log('  .claude/CLAUDE.md          — Project rules (review and customize)');
+  console.log('  .claude/settings.json      — Hook configuration');
+  console.log('  .claude/hooks/             — 6 guards (file, path, glob, comment, sensitive, self-review)');
+  console.log('  .claude/skills/            — /sp-plan, /sp-challenge, /sp-build, /sp-fix, /sp-review, /sp-commit, /sp-voices');
+  console.log('  docs/WORKFLOW.md           — Workflow reference');
+  log.blank();
+  const parts = [`${copied} copied`];
+  if (identical > 0) parts.push(`${identical} identical`);
+  if (skipped > 0) parts.push(`${skipped} conflicted (use --force to overwrite)`);
+  console.log(`  ${parts.join(', ')}`);
+  log.blank();
+  console.log('Next steps:');
+  console.log('  1. Review .claude/CLAUDE.md — ensure project info is correct');
+  console.log('  2. Write your first spec:   docs/specs/<feature>.md');
+  console.log('  3. Generate test plan:      /sp-plan docs/specs/<feature>.md');
+  console.log('  4. Start coding + testing:  /sp-build');
+  log.blank();
+
+  if (warnings > 0) {
+    console.log(`⚠ ${warnings} warning(s) above — review before proceeding.`);
+  }
+
+  // --- Global install prompt (first-time only) ---
+  if (!opts.global) {
+    const globalMeta = await readGlobalManifest();
+    if (globalMeta?.globalInstalled === undefined) {
+      await promptGlobalInstall(opts);
+    } else if (globalMeta?.globalInstalled === true) {
+      // Auto-upgrade global on init if previously installed
+      await initGlobal({ force: opts.force });
+    }
+  }
+}
+
+async function promptGlobalInstall(opts) {
+  log.blank();
+  console.log('─── Global Install ───');
+  console.log('');
+  console.log('Skills and hooks are installed per-project by default.');
+  console.log('You can install them globally so every project is covered without running init again.');
+  console.log('');
+  console.log('  ~/.claude/skills/   ← global skills (fallback when no per-project skills)');
+  console.log('  ~/.claude/hooks/    ← global hooks  (active in all projects)');
+  console.log('  .claude/skills/     ← per-project skills (takes precedence over global)');
+  console.log('  .claude/hooks/      ← per-project hooks  (takes precedence over global)');
+  console.log('');
+  console.log('To revert global hooks back to per-project later:');
+  console.log('  specpipe remove --global');
+  console.log('  then: specpipe init  (in each project)');
+  console.log('');
+  console.log('RECOMMENDATION: Choose A if you work across many projects.');
+  console.log('');
+
+  const answer = await askGlobalInstall();
+
+  if (answer === 'skills+hooks') {
+    await initGlobal({ force: opts.force, hooks: true });
+    await trackProjectPath(process.cwd());
+  } else if (answer === 'skills') {
+    await initGlobal({ force: opts.force, hooks: false });
+    await trackProjectPath(process.cwd());
+  } else if (answer === 'no') {
+    await writeGlobalManifest({ globalInstalled: false, updatedAt: new Date().toISOString() });
+    log.info('Skipping global install. Run `specpipe init --global` anytime.');
+  }
+  // 'later' = don't write anything, prompt again next time
+}
+
+async function askGlobalInstall() {
+  const { createInterface } = await import('node:readline');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    console.log('A) Skills + Hooks globally  (recommended)');
+    console.log('B) Skills only              (hooks stay per-project)');
+    console.log('C) No — keep everything per-project');
+    console.log('D) Ask me next time');
+    console.log('');
+    rl.question('Choice [A/B/C/D]: ', (answer) => {
+      rl.close();
+      const a = answer.trim().toUpperCase();
+      if (a === 'A') resolve('skills+hooks');
+      else if (a === 'B') resolve('skills');
+      else if (a === 'C') resolve('no');
+      else resolve('later');
+    });
+  });
+}
+
+async function trackProjectPath(projectPath) {
+  const meta = await readGlobalManifest() || {};
+  const projects = new Set(meta.projects || []);
+  projects.add(projectPath);
+  await writeGlobalManifest({ ...meta, projects: [...projects] });
+}
+
+function commandExists(cmd) {
+  // `command -v` is a POSIX shell builtin and is unavailable under Windows
+  // cmd.exe, where execSync runs. Use `where` on Windows, `command -v` elsewhere.
+  const probe = process.platform === 'win32' ? `where ${cmd}` : `command -v ${cmd}`;
+  try {
+    execSync(probe, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,54 @@
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { log } from '../lib/logger.js';
+import { readManifest, refreshCustomizationStatus, getAgents } from '../lib/manifest.js';
+import { AGENTS } from '../lib/agents.js';
+
+export async function listCommand(path) {
+  const targetDir = resolve(path);
+  const manifest = await readManifest(targetDir);
+
+  if (!manifest) {
+    log.fail('No manifest found. Run `specpipe init` first.');
+    process.exit(1);
+  }
+
+  // Refresh hashes to get accurate customization status
+  await refreshCustomizationStatus(targetDir, manifest);
+
+  const agents = getAgents(manifest);
+  log.info(`specpipe v${manifest.version} — installed ${manifest.installedAt.split('T')[0]}`);
+  if (manifest.projectType) {
+    log.info(`Project: ${manifest.projectType.lang} (${manifest.projectType.framework})`);
+  }
+  log.info(`Agents: ${agents.map((a) => AGENTS[a]?.label || a).join(', ')}`);
+  log.blank();
+
+  // Group files by the agent that produced them.
+  const byAgent = {};
+  for (const [file, entry] of Object.entries(manifest.files)) {
+    const a = entry.agent || 'claude';
+    (byAgent[a] ||= []).push([file, entry]);
+  }
+
+  const fileCol = 44;
+  let totalFiles = 0;
+  let customized = 0;
+
+  for (const agent of Object.keys(byAgent)) {
+    const meta = AGENTS[agent];
+    const hookNote = meta && meta.hooks !== 'native' ? chalk.gray(' (guards as advisory rules)') : '';
+    console.log(chalk.bold(`${meta?.label || agent}`) + hookNote);
+    for (const [file, entry] of byAgent[agent].sort((a, b) => a[0].localeCompare(b[0]))) {
+      totalFiles++;
+      let status;
+      if (entry.installedHash === null) status = chalk.red('deleted');
+      else if (entry.customized) { status = chalk.yellow('customized'); customized++; }
+      else status = chalk.green('up-to-date');
+      console.log('  ' + file.padEnd(fileCol) + status);
+    }
+    log.blank();
+  }
+
+  console.log(`${totalFiles} files | ${customized} customized | ${agents.length} agent(s)`);
+}

package/src/commands/remove.js

@@ -0,0 +1,133 @@
+import { resolve, join, dirname } from 'node:path';
+import { unlink, rmdir, rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { log } from '../lib/logger.js';
+import { readManifest, getAgents, MANIFEST_FILE, LEGACY_MANIFEST_FILE } from '../lib/manifest.js';
+import { removeGlobalHooksFromSettings, stripAgentsMdGuards, removeAgentHooks } from '../lib/installer.js';
+import { agentHasHooks } from '../lib/agents.js';
+
+const PRESERVE = [
+  '.claude/CLAUDE.md',
+];
+
+const PRESERVE_DIRS = [
+  'docs/',
+];
+
+export async function removeGlobal() {
+  log.info('Removing global specpipe install...');
+  log.blank();
+
+  // Remove ~/.claude/skills/
+  const globalSkillsDir = join(homedir(), '.claude', 'skills');
+  if (existsSync(globalSkillsDir)) {
+    await rm(globalSkillsDir, { recursive: true, force: true });
+    log.del('~/.claude/skills/');
+  } else {
+    log.skip('~/.claude/skills/ (not found)');
+  }
+
+  // Remove ~/.claude/hooks/
+  const globalHooksDir = join(homedir(), '.claude', 'hooks');
+  if (existsSync(globalHooksDir)) {
+    await rm(globalHooksDir, { recursive: true, force: true });
+    log.del('~/.claude/hooks/');
+  } else {
+    log.skip('~/.claude/hooks/ (not found)');
+  }
+
+  // Legacy cleanup: older installs shipped ~/.claude/scripts/build-test.sh.
+  // The script is no longer part of the kit — sweep up the orphan if present.
+  const legacyScript = join(homedir(), '.claude', 'scripts', 'build-test.sh');
+  if (existsSync(legacyScript)) {
+    await unlink(legacyScript);
+    log.del('~/.claude/scripts/build-test.sh (legacy)');
+    try {
+      await rmdir(join(homedir(), '.claude', 'scripts'));
+    } catch { /* keep dir if user has other scripts in it */ }
+  }
+
+  // Remove devkit hook entries from ~/.claude/settings.json
+  await removeGlobalHooksFromSettings();
+  log.del('hook entries from ~/.claude/settings.json');
+
+  // Remove global manifest
+  const globalManifest = join(homedir(), '.claude', '.devkit-manifest.json');
+  if (existsSync(globalManifest)) {
+    await unlink(globalManifest);
+    log.del('~/.claude/.devkit-manifest.json');
+  }
+
+  log.blank();
+  log.pass('Global install removed. Per-project installs are unaffected.');
+  log.info('Run `specpipe init` in each project to restore per-project hooks.');
+}
+
+export async function removeCommand(path, opts = {}) {
+  if (opts.global) {
+    await removeGlobal();
+    return;
+  }
+
+  const targetDir = resolve(path);
+  const manifest = await readManifest(targetDir);
+
+  if (!manifest) {
+    log.fail('No manifest found. Nothing to remove.');
+    process.exit(1);
+  }
+
+  log.info('Removing specpipe files...');
+  log.blank();
+
+  const removedDirs = new Set();
+
+  // Remove tracked files (except preserved), across every agent's layout.
+  for (const file of Object.keys(manifest.files)) {
+    if (PRESERVE.includes(file) || PRESERVE_DIRS.some((dir) => file.startsWith(dir))) {
+      log.keep(file);
+      continue;
+    }
+    const fullPath = join(targetDir, file);
+    if (existsSync(fullPath)) {
+      await unlink(fullPath);
+      log.del(file);
+      // Track ancestor dirs (within the project) for empty-dir cleanup.
+      let d = dirname(file);
+      while (d && d !== '.' && d !== '/') { removedDirs.add(d); d = dirname(d); }
+    }
+  }
+
+  // Remove the manifest (new + legacy locations).
+  for (const rel of [MANIFEST_FILE, LEGACY_MANIFEST_FILE]) {
+    const p = join(targetDir, rel);
+    if (existsSync(p)) {
+      await unlink(p);
+      log.del(rel);
+      let d = dirname(rel);
+      while (d && d !== '.' && d !== '/') { removedDirs.add(d); d = dirname(d); }
+    }
+  }
+
+  // Codex guards live as a section in a shared AGENTS.md — strip just that section.
+  if (manifest.agentsMdGuards) {
+    if (await stripAgentsMdGuards(targetDir)) log.del('AGENTS.md (specpipe guards section)');
+  }
+
+  // Enforced hooks (Codex/Cursor) live outside the tracked file set — clean per agent.
+  for (const agent of getAgents(manifest)) {
+    if (agentHasHooks(agent)) await removeAgentHooks(agent, targetDir);
+  }
+
+  // Legacy: older installs placed build-test.sh under scripts/.
+  removedDirs.add('scripts');
+
+  // Remove now-empty directories, deepest first (preserves dirs with user content).
+  for (const dir of [...removedDirs].sort((a, b) => b.split('/').length - a.split('/').length)) {
+    try { await rmdir(join(targetDir, dir)); } catch { /* not empty or missing */ }
+  }
+
+  log.blank();
+  log.pass('Removed. CLAUDE.md and docs/ preserved.');
+}