specpipe 1.0.0

package/bin/devkit.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { cli } from '../src/cli.js';
+cli(process.argv);

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "specpipe",
+  "version": "1.0.0",
+  "description": "Spec-first development toolkit for agentic AI coding agents — installs skills + guardrails for Claude Code, Codex, Cursor, Antigravity, and more.",
+  "bin": {
+    "specpipe": "./bin/devkit.js",
+    "sp": "./bin/devkit.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.17.0",
+    "eslint": "^9.17.0",
+    "globals": "^15.14.0",
+    "prettier": "^3.4.2"
+  },
+  "keywords": [
+    "ai",
+    "ai-agents",
+    "coding-agent",
+    "claude-code",
+    "codex",
+    "cursor",
+    "antigravity",
+    "spec-first",
+    "tdd",
+    "skills",
+    "guardrails",
+    "developer-tools"
+  ],
+  "scripts": {
+    "test": "node ../test/agents.mjs && bash ../test/cli.sh && bash ../test/hooks.sh && bash ../test/coverage-gate.sh",
+    "lint": "eslint src bin",
+    "format": "prettier --write \"src/**/*.js\" \"bin/**/*.js\"",
+    "prepublishOnly": "rm -rf templates && cp -r ../kit templates && cp ../README.md README.md",
+    "postpublish": "rm -rf templates README.md",
+    "dev": "node bin/devkit.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/microvn/specpipe.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/microvn/specpipe#readme",
+  "bugs": {
+    "url": "https://github.com/microvn/specpipe/issues"
+  },
+  "author": "Microvn <microvn.gm@gmail.com>",
+  "license": "MIT",
+  "type": "module"
+}

package/src/cli.js

@@ -0,0 +1,76 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../package.json'), 'utf-8'));
+
+export function cli(argv) {
+  const program = new Command();
+
+  program
+    .name('specpipe')
+    .description('CLI toolkit for spec-first development with agentic AI coding agents')
+    .version(pkg.version);
+
+  program
+    .command('init [path]')
+    .description('Initialize a project with the dev-kit')
+    .option('-f, --force', 'Overwrite existing files')
+    .option('-g, --global', 'Install skills globally to ~/.claude/skills/ (available in all projects)')
+    .option('--agents <list>', 'Target agent(s): claude,codex,cursor,antigravity,openclaw,hermes or "all" (default: claude)')
+    .option('--only <components>', 'Install only specific components (comma-separated: hooks,skills,scripts,docs,config)')
+    .option('--adopt', 'Adopt existing kit files without overwriting (migration from setup.sh)')
+    .option('--dry-run', 'Show what would be done without making changes')
+    .action(async (path, opts) => {
+      const { initCommand } = await import('./commands/init.js');
+      await initCommand(path || '.', opts);
+    });
+
+  program
+    .command('upgrade [path]')
+    .description('Smart upgrade — preserves customized files')
+    .option('-f, --force', 'Overwrite even customized files')
+    .option('-g, --global', 'Upgrade skills globally in ~/.claude/skills/')
+    .option('--dry-run', 'Show what would be done without making changes')
+    .action(async (path, opts) => {
+      const { upgradeCommand } = await import('./commands/upgrade.js');
+      await upgradeCommand(path || '.', opts);
+    });
+
+  program
+    .command('check [path]')
+    .description('Check if an update is available')
+    .action(async (path) => {
+      const { checkCommand } = await import('./commands/check.js');
+      await checkCommand(path || '.');
+    });
+
+  program
+    .command('list [path]')
+    .description('List installed components and their status')
+    .action(async (path) => {
+      const { listCommand } = await import('./commands/list.js');
+      await listCommand(path || '.');
+    });
+
+  program
+    .command('diff [path]')
+    .description('Show differences between installed and latest kit files')
+    .action(async (path) => {
+      const { diffCommand } = await import('./commands/diff.js');
+      await diffCommand(path || '.');
+    });
+
+  program
+    .command('remove [path]')
+    .description('Uninstall dev-kit (preserves CLAUDE.md and docs/)')
+    .option('-g, --global', 'Remove global install (~/.claude/skills/, ~/.claude/hooks/, hook entries from ~/.claude/settings.json)')
+    .action(async (path, opts) => {
+      const { removeCommand } = await import('./commands/remove.js');
+      await removeCommand(path || '.', opts);
+    });
+
+  program.parse(argv);
+}

package/src/commands/check.js

@@ -0,0 +1,33 @@
+import { resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { log } from '../lib/logger.js';
+import { readManifest } from '../lib/manifest.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
+
+export async function checkCommand(path) {
+  const targetDir = resolve(path);
+  const manifest = await readManifest(targetDir);
+
+  if (!manifest) {
+    log.fail('No manifest found. Run `specpipe init` first.');
+    process.exit(1);
+  }
+
+  const installed = manifest.version;
+  const latest = pkg.version;
+
+  log.info(`Installed: ${installed}`);
+  log.info(`Latest:    ${latest}`);
+  log.blank();
+
+  if (installed === latest) {
+    log.pass('Up to date.');
+  } else {
+    log.warn(`Update available: ${installed} → ${latest}`);
+    console.log('Run: npx specpipe upgrade');
+  }
+}

package/src/commands/diff.js

@@ -0,0 +1,84 @@
+import { resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import chalk from 'chalk';
+import { log } from '../lib/logger.js';
+import { readManifest, getAgents } from '../lib/manifest.js';
+import { hashContent } from '../lib/hasher.js';
+import { computeDesired } from '../lib/reconcile.js';
+
+export async function diffCommand(path) {
+  const targetDir = resolve(path);
+  const manifest = await readManifest(targetDir);
+
+  if (!manifest) {
+    log.fail('No manifest found. Run `specpipe init` first.');
+    process.exit(1);
+  }
+
+  const desired = await computeDesired(getAgents(manifest));
+  let hasDiffs = false;
+
+  for (const [file, d] of desired) {
+    const installedPath = resolve(targetDir, file);
+
+    if (!existsSync(installedPath)) {
+      // File in kit but not installed
+      console.log(chalk.cyan(`\n${file} (new in kit — not installed)`));
+      hasDiffs = true;
+      continue;
+    }
+
+    const installedContent = await readFile(installedPath, 'utf-8');
+    if (hashContent(installedContent) === d.kitHash) continue;
+
+    hasDiffs = true;
+
+    // Check if kit changed or user changed
+    const entry = manifest.files[file];
+    const kitChanged = entry && d.kitHash !== entry.kitHash;
+    const userChanged = entry && entry.customized;
+
+    let label = '';
+    if (kitChanged && userChanged) label = 'both kit and local changed';
+    else if (kitChanged) label = 'kit updated';
+    else if (userChanged) label = 'locally customized';
+    else label = 'differs';
+
+    console.log(chalk.bold(`\n${file}`) + chalk.gray(` (${label})`));
+    console.log('─'.repeat(60));
+
+    // Simple line-by-line diff (desired kit content vs installed)
+    const kitLines = d.content.split('\n');
+    const installedLines = installedContent.split('\n');
+
+    // Show a simplified diff: lines only in kit (green +), only in installed (red -)
+    const kitSet = new Set(kitLines);
+    const installedSet = new Set(installedLines);
+
+    const removed = installedLines.filter((l) => !kitSet.has(l) && l.trim());
+    const added = kitLines.filter((l) => !installedSet.has(l) && l.trim());
+
+    for (const line of removed.slice(0, 10)) {
+      console.log(chalk.red(`  - ${line}`));
+    }
+    for (const line of added.slice(0, 10)) {
+      console.log(chalk.green(`  + ${line}`));
+    }
+    if (removed.length > 10 || added.length > 10) {
+      console.log(chalk.gray(`  ... and ${Math.max(removed.length - 10, 0) + Math.max(added.length - 10, 0)} more lines`));
+    }
+  }
+
+  // Check for files in manifest no longer desired (removed from kit / agent)
+  for (const file of Object.keys(manifest.files)) {
+    if (!desired.has(file)) {
+      console.log(chalk.yellow(`\n${file} (removed from kit)`));
+      hasDiffs = true;
+    }
+  }
+
+  if (!hasDiffs) {
+    log.pass('All files match the kit. No differences.');
+  }
+}

package/src/commands/init-adopt.js

@@ -0,0 +1,54 @@
+import { resolve, dirname } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { log } from '../lib/logger.js';
+import { detectProject } from '../lib/detector.js';
+import { createManifest, writeManifest, setFileEntry } from '../lib/manifest.js';
+import { hashFile } from '../lib/hasher.js';
+import { getAllFiles, COMPONENTS, getTemplateDir } from '../lib/installer.js';
+import { AGENTS, parseSkillPath } from '../lib/agents.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
+
+/**
+ * Adopt existing kit files (migration from setup.sh).
+ * Scans for existing files and generates a manifest without overwriting.
+ */
+export async function adoptExisting(targetDir) {
+  log.info('Adopting existing kit files...');
+  log.blank();
+
+  const manifest = createManifest(pkg.version, null, Object.keys(COMPONENTS));
+  let adopted = 0;
+
+  for (const file of getAllFiles()) {
+    // Skills live at the Claude output path (.claude/skills/) on disk; map from canonical skills/.
+    const sk = parseSkillPath(file);
+    const outRel = sk ? AGENTS.claude.skillTarget(sk.skill, sk.inner) : file;
+    const installedPath = resolve(targetDir, outRel);
+
+    if (!existsSync(installedPath)) continue;
+
+    const installedHash = await hashFile(installedPath);
+    let kitHash;
+    try {
+      kitHash = await hashFile(resolve(getTemplateDir(), file));
+    } catch {
+      kitHash = installedHash; // Template doesn't exist, treat as matching
+    }
+    setFileEntry(manifest, outRel, kitHash, installedHash, { agent: 'claude', templateRel: file });
+    log.adopt(outRel);
+    adopted++;
+  }
+
+  const projectInfo = detectProject(targetDir);
+  if (projectInfo) {
+    manifest.projectType = { lang: projectInfo.lang, framework: projectInfo.framework };
+    log.info(`Detected: ${projectInfo.lang} (${projectInfo.framework})`);
+  }
+
+  await writeManifest(targetDir, manifest);
+  log.blank();
+  log.pass(`Manifest created for ${adopted} existing files. Future upgrades will work.`);
+}

package/src/commands/init-agents.js

@@ -0,0 +1,118 @@
+import { resolve, dirname } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { log } from '../lib/logger.js';
+import { detectProject } from '../lib/detector.js';
+import { createManifest, writeManifest, setFileEntry, readManifest, mergeAgents } from '../lib/manifest.js';
+import { hashContent } from '../lib/hasher.js';
+import {
+  COMPONENTS, PLACEHOLDER_DIRS, installFile, ensurePlaceholderDir,
+  setPermissions, fillTemplate, installAgentSkills, installAgentRules, installAgentHooks,
+} from '../lib/installer.js';
+import { resolveAgents, AGENTS } from '../lib/agents.js';
+import { computeDesired } from '../lib/reconcile.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
+
+/**
+ * Multi-agent install. Each selected agent gets its skill set emitted to its
+ * native path + frontmatter. Claude additionally gets the full base
+ * (hooks, config, docs) since it's the only agent with a native hook system.
+ */
+export async function initMultiAgent(targetDir, opts, warnings = 0) {
+  let requested;
+  try {
+    requested = resolveAgents(opts.agents);
+  } catch (e) {
+    log.fail(e.message);
+    process.exit(1);
+  }
+  // Accumulate: keep agents already installed (per the existing manifest) and add the
+  // requested ones, so `init --agents X` then `--agents Y` ends up with both, not just Y.
+  const existing = await readManifest(targetDir);
+  const agents = mergeAgents(existing?.agents, requested);
+  const claudeSelected = agents.includes('claude');
+  const labels = agents.map((a) => AGENTS[a].label).join(', ');
+
+  if (opts.dryRun) {
+    log.info('Dry run — no changes will be made');
+    log.info(`Target agents: ${labels}`);
+    return;
+  }
+
+  log.blank();
+  console.log(`--- Installing for: ${labels} ---`);
+
+  const manifest = createManifest(pkg.version, null, Object.keys(COMPONENTS));
+  manifest.agents = agents;
+
+  // Claude base: hooks + config + docs (only Claude has a native hook system).
+  if (claudeSelected) {
+    log.blank();
+    console.log('  Claude base (hooks, config, docs):');
+    for (const file of [...COMPONENTS.hooks, ...COMPONENTS.config, ...COMPONENTS.docs]) {
+      await installFile(file, targetDir, { force: opts.force });
+    }
+    for (const dir of PLACEHOLDER_DIRS) await ensurePlaceholderDir(dir, targetDir);
+    await setPermissions(targetDir);
+  }
+
+  // Skills + guardrails, emitted per agent into each agent's native location.
+  const results = [];
+  for (const agent of agents) {
+    log.blank();
+    console.log(`  ${AGENTS[agent].label} skills:`);
+    results.push(await installAgentSkills(agent, targetDir, { force: opts.force }));
+    const rules = await installAgentRules(agent, targetDir, { force: opts.force });
+    if (rules?.mode === 'agents-md') manifest.agentsMdGuards = true;
+    await installAgentHooks(agent, targetDir, { force: opts.force }); // enforced hooks (Codex/Cursor)
+  }
+
+  // Project detection only fills Claude's CLAUDE.md template.
+  if (claudeSelected) {
+    const projectInfo = detectProject(targetDir);
+    if (projectInfo) {
+      manifest.projectType = { lang: projectInfo.lang, framework: projectInfo.framework };
+      await fillTemplate(targetDir, projectInfo);
+    } else {
+      warnings++;
+    }
+  }
+
+  // Record every installed file (all agents) keyed by on-disk path, with the
+  // hash of what's actually on disk so customization/skip is detected later.
+  const desired = await computeDesired(agents);
+  for (const [relPath, d] of desired) {
+    let installedHash = d.kitHash;
+    try { installedHash = hashContent(await readFile(resolve(targetDir, relPath), 'utf-8')); } catch { /* skipped/missing */ }
+    setFileEntry(manifest, relPath, d.kitHash, installedHash, { agent: d.agent, templateRel: d.templateRel });
+  }
+
+  await writeManifest(targetDir, manifest);
+
+  // Summary
+  log.blank();
+  console.log('=== Setup Complete ===');
+  log.blank();
+  for (const r of results) {
+    const parts = [`${r.copied} copied`];
+    if (r.identical > 0) parts.push(`${r.identical} identical`);
+    if (r.skipped > 0) parts.push(`${r.skipped} conflicted`);
+    console.log(`  ${r.label}: ${parts.join(', ')}`);
+  }
+  if (claudeSelected) {
+    log.blank();
+    console.log('  Claude hooks active via .claude/settings.json.');
+  }
+  const noHook = agents.filter((a) => AGENTS[a].hooks !== 'native');
+  if (noHook.length) {
+    log.blank();
+    log.warn(`${noHook.map((a) => AGENTS[a].label).join(', ')}: guards installed as always-on rules (advisory — not hook-enforced like Claude).`);
+  }
+  if (warnings > 0) {
+    log.blank();
+    console.log(`⚠ ${warnings} warning(s) above — review before proceeding.`);
+  }
+}

package/src/commands/init-global.js

@@ -0,0 +1,102 @@
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { log } from '../lib/logger.js';
+import {
+  COMPONENTS, installSkillGlobal, getGlobalSkillsDir,
+  installHookGlobal, getGlobalHooksDir, mergeGlobalSettings,
+} from '../lib/installer.js';
+
+// Global Claude install (~/.claude/skills + hooks) and its manifest.
+
+const GLOBAL_MANIFEST = join(homedir(), '.claude', '.devkit-manifest.json');
+
+export async function readGlobalManifest() {
+  try {
+    return JSON.parse(await readFile(GLOBAL_MANIFEST, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+export async function writeGlobalManifest(data) {
+  await mkdir(join(homedir(), '.claude'), { recursive: true });
+  await writeFile(GLOBAL_MANIFEST, JSON.stringify(data, null, 2) + '\n');
+}
+
+export async function initGlobal({ force = false, hooks = false } = {}) {
+  const globalSkillsDir = getGlobalSkillsDir();
+  await mkdir(globalSkillsDir, { recursive: true });
+
+  const existing = await readGlobalManifest() || {};
+  const globalFiles = existing.files || {};
+  const updatedFiles = { ...globalFiles };
+
+  log.blank();
+  console.log('--- Installing global skills ---');
+
+  let copied = 0; let skipped = 0; let identical = 0;
+  for (const relPath of COMPONENTS.skills) {
+    const { result, kitHash } = await installSkillGlobal(relPath, globalSkillsDir, { force, globalFiles });
+    if (result === 'copied') copied++;
+    else if (result === 'identical') identical++;
+    else skipped++;
+    if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
+  }
+
+  const parts = [`${copied} copied`];
+  if (identical > 0) parts.push(`${identical} identical`);
+  if (skipped > 0) parts.push(`${skipped} customized (use --force to overwrite)`);
+  log.pass(`Global skills: ${parts.join(', ')}`);
+  log.info('Skills available in all projects via ~/.claude/skills/');
+
+  if (hooks) {
+    await initGlobalHooks({ force, _globalFiles: updatedFiles, _skipManifestWrite: true });
+  }
+
+  await writeGlobalManifest({
+    ...existing,
+    globalInstalled: true,
+    globalHooksInstalled: hooks || existing.globalHooksInstalled || false,
+    files: updatedFiles,
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+export async function initGlobalHooks({ force = false, _globalFiles, _skipManifestWrite = false } = {}) {
+  const globalHooksDir = getGlobalHooksDir();
+  await mkdir(globalHooksDir, { recursive: true });
+
+  const existing = _skipManifestWrite ? null : (await readGlobalManifest() || {});
+  const globalFiles = _globalFiles || existing?.files || {};
+  const updatedFiles = { ...globalFiles };
+
+  log.blank();
+  console.log('--- Installing global hooks ---');
+
+  let copied = 0; let skipped = 0; let identical = 0;
+  for (const relPath of COMPONENTS.hooks) {
+    const { result, kitHash } = await installHookGlobal(relPath, globalHooksDir, { force, globalFiles });
+    if (result === 'copied') copied++;
+    else if (result === 'identical') identical++;
+    else skipped++;
+    if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
+  }
+
+  await mergeGlobalSettings(globalHooksDir);
+
+  const parts = [`${copied} copied`];
+  if (identical > 0) parts.push(`${identical} identical`);
+  if (skipped > 0) parts.push(`${skipped} customized (use --force to overwrite)`);
+  log.pass(`Global hooks: ${parts.join(', ')}`);
+  log.info('Hooks registered in ~/.claude/settings.json — active in all projects');
+
+  if (!_skipManifestWrite) {
+    await writeGlobalManifest({
+      ...existing,
+      globalHooksInstalled: true,
+      files: updatedFiles,
+      updatedAt: new Date().toISOString(),
+    });
+  }
+}