specpipe 1.0.0

package/src/commands/upgrade.js

@@ -0,0 +1,215 @@
+import { resolve, dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { log } from '../lib/logger.js';
+import { readManifest, writeManifest, setFileEntry, refreshCustomizationStatus, getAgents } from '../lib/manifest.js';
+import { setPermissions, COMPONENTS, installSkillGlobal, getGlobalSkillsDir, installHookGlobal, getGlobalHooksDir, mergeGlobalSettings, installAgentRules, installAgentHooks } from '../lib/installer.js';
+import { agentRulesMode, agentHasHooks } from '../lib/agents.js';
+import { computeDesired } from '../lib/reconcile.js';
+import { unlink } from 'node:fs/promises';
+
+const GLOBAL_MANIFEST = join(homedir(), '.claude', '.devkit-manifest.json');
+
+async function readGlobalManifest() {
+  try { return JSON.parse(await readFile(GLOBAL_MANIFEST, 'utf-8')); } catch { return null; }
+}
+async function writeGlobalManifest(data) {
+  await mkdir(join(homedir(), '.claude'), { recursive: true });
+  await writeFile(GLOBAL_MANIFEST, JSON.stringify(data, null, 2) + '\n');
+}
+
+export async function upgradeGlobal({ force = false } = {}) {
+  const globalSkillsDir = getGlobalSkillsDir();
+  await mkdir(globalSkillsDir, { recursive: true });
+
+  const meta = await readGlobalManifest() || {};
+  const globalFiles = meta.files || {};
+  const updatedFiles = { ...globalFiles };
+
+  log.blank();
+  console.log('--- Upgrading global skills ---');
+  let updated = 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') updated++;
+    else if (result === 'identical') identical++;
+    else skipped++;
+    if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
+  }
+
+  let skillParts = [`${updated} updated`, `${identical} unchanged`];
+  if (skipped > 0) skillParts.push(`${skipped} customized (use --force to overwrite)`);
+  log.pass(`Global skills: ${skillParts.join(', ')}`);
+
+  // Upgrade hooks if previously installed globally
+  if (meta.globalHooksInstalled) {
+    const globalHooksDir = getGlobalHooksDir();
+    await mkdir(globalHooksDir, { recursive: true });
+
+    log.blank();
+    console.log('--- Upgrading global hooks ---');
+    let hUpdated = 0; let hSkipped = 0; let hIdentical = 0;
+
+    for (const relPath of COMPONENTS.hooks) {
+      const { result, kitHash } = await installHookGlobal(relPath, globalHooksDir, { force, globalFiles });
+      if (result === 'copied') hUpdated++;
+      else if (result === 'identical') hIdentical++;
+      else hSkipped++;
+      if (result !== 'skipped') updatedFiles[relPath] = { kitHash };
+    }
+
+    await mergeGlobalSettings(globalHooksDir);
+
+    let hookParts = [`${hUpdated} updated`, `${hIdentical} unchanged`];
+    if (hSkipped > 0) hookParts.push(`${hSkipped} customized (use --force to overwrite)`);
+    log.pass(`Global hooks: ${hookParts.join(', ')}`);
+  }
+
+  await writeGlobalManifest({ ...meta, globalInstalled: true, files: updatedFiles, updatedAt: new Date().toISOString() });
+
+  // Warn about per-project skills that shadow global
+  const projects = meta.projects || [];
+  const projectsWithSkills = projects.filter((p) => existsSync(join(p, '.claude/skills')));
+  if (projectsWithSkills.length > 0) {
+    log.blank();
+    log.info(`Found per-project skills in ${projectsWithSkills.length} project(s):`);
+    for (const p of projectsWithSkills) log.info(`  ${p}`);
+    log.info('Per-project skills take precedence over global. Remove them to use global instead.');
+    log.info('Run `specpipe remove <path>` in each project to remove per-project install.');
+  }
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(resolve(__dirname, '../../package.json'), 'utf-8'));
+
+export async function upgradeCommand(path, opts) {
+  // --- Global mode ---
+  if (opts.global) {
+    await upgradeGlobal({ force: opts.force });
+    return;
+  }
+
+  const targetDir = resolve(path);
+  const manifest = await readManifest(targetDir);
+
+  if (!manifest) {
+    log.fail('No manifest found. Run `specpipe init` first, or `specpipe init --adopt` to adopt existing files.');
+    process.exit(1);
+  }
+
+  // Refresh customization status by re-hashing installed files
+  await refreshCustomizationStatus(targetDir, manifest);
+
+  log.info(`specpipe upgrade: ${manifest.version} → ${pkg.version}`);
+  log.blank();
+
+  if (opts.dryRun) {
+    log.info('Dry run — no changes will be made');
+    log.blank();
+  }
+
+  // Desired installed state for every agent this project targets.
+  const agents = getAgents(manifest);
+  const desired = await computeDesired(agents);
+
+  let updated = 0;
+  let skippedCustomized = 0;
+  let added = 0;
+  let unchanged = 0;
+
+  for (const [relPath, d] of desired) {
+    const installedPath = resolve(targetDir, relPath);
+    const entry = manifest.files[relPath];
+
+    if (!entry) {
+      // New file (new kit file, or an agent added since install) — install it.
+      if (!opts.dryRun) {
+        await mkdir(dirname(installedPath), { recursive: true });
+        await writeFile(installedPath, d.content);
+        setFileEntry(manifest, relPath, d.kitHash, d.kitHash, { agent: d.agent, templateRel: d.templateRel });
+      }
+      log.copy(`${relPath} (new)`);
+      added++;
+      continue;
+    }
+
+    if (d.kitHash === entry.kitHash) {
+      log.same(relPath);
+      unchanged++;
+      continue;
+    }
+
+    if (entry.customized && !opts.force) {
+      log.skip(`${relPath} (customized — use --force to overwrite)`);
+      skippedCustomized++;
+      continue;
+    }
+
+    // Kit changed, user hasn't customized (or --force) → update.
+    if (!opts.dryRun) {
+      await mkdir(dirname(installedPath), { recursive: true });
+      await writeFile(installedPath, d.content);
+      setFileEntry(manifest, relPath, d.kitHash, d.kitHash, { agent: d.agent, templateRel: d.templateRel });
+    }
+    log.copy(relPath);
+    updated++;
+  }
+
+  // Remove files in manifest that are no longer desired (dropped kit file or agent).
+  let removed = 0;
+  for (const relPath of Object.keys(manifest.files)) {
+    if (desired.has(relPath)) continue;
+    const filePath = resolve(targetDir, relPath);
+    if (!opts.dryRun) {
+      try {
+        await unlink(filePath);
+        delete manifest.files[relPath];
+        removed++;
+        log.del(relPath);
+      } catch {
+        log.warn(`${relPath} — no longer in kit (could not delete)`);
+      }
+    } else {
+      log.del(`${relPath} (would remove)`);
+      removed++;
+    }
+  }
+
+  // Refresh guardrails that aren't owned files: Codex's shared AGENTS.md section is
+  // merged (not reconciled via computeDesired), so re-merge it here to pick up kit
+  // changes. Owned rule files were already handled by the reconcile loop above.
+  if (!opts.dryRun) {
+    for (const agent of agents) {
+      if (agentRulesMode(agent) === 'agents-md') await installAgentRules(agent, targetDir, { force: opts.force });
+      if (agentHasHooks(agent)) await installAgentHooks(agent, targetDir, { force: opts.force });
+    }
+  }
+
+  // Update manifest
+  if (!opts.dryRun) {
+    manifest.version = pkg.version;
+    manifest.updatedAt = new Date().toISOString();
+    await setPermissions(targetDir);
+    await writeManifest(targetDir, manifest);
+  }
+
+  // Summary
+  log.blank();
+  const parts = [`Updated ${updated}`, `added ${added}`, `removed ${removed}`, `unchanged ${unchanged}`];
+  if (skippedCustomized > 0) parts.push(`skipped ${skippedCustomized} customized`);
+  log.pass(parts.join(', ') + '.');
+
+  if (skippedCustomized > 0) {
+    log.warn(`${skippedCustomized} customized file(s) skipped. Run with --force to overwrite.`);
+  }
+
+  // --- Auto-upgrade global if previously installed ---
+  const globalMeta = await readGlobalManifest();
+  if (globalMeta?.globalInstalled === true) {
+    await upgradeGlobal({ force: opts.force });
+  }
+}

package/src/lib/agent-guards.js

@@ -0,0 +1,100 @@
+// Guardrails (advisory rules) + enforced (blocking) hooks per agent.
+// Claude enforces guards via its native .claude/hooks; every other agent gets the
+// same intent as an always-on RULE. Codex/Cursor additionally support blocking
+// hooks (verified payloads), so they also get enforced guard scripts.
+
+const RULES = {
+  cursor: {
+    mode: 'file',
+    path: '.cursor/rules/specpipe-guards.mdc',
+    frontmatter: 'description: specpipe operating rules — spec-first cycle, guardrails, testing, conventions\nglobs:\nalwaysApply: true',
+  },
+  // Antigravity rules are plain markdown (no documented trigger/glob frontmatter);
+  // official Google DevRel uses the singular `.agent/rules/` path.
+  antigravity: { mode: 'doc', path: '.agent/rules/specpipe-guards.md' },
+  codex: { mode: 'agents-md', path: 'AGENTS.md' },
+  openclaw: { mode: 'doc', path: 'SPECPIPE-GUARDS.md' },
+  hermes: { mode: 'doc', path: 'SPECPIPE-GUARDS.md' },
+};
+
+export const GUARDS_BEGIN = '<!-- specpipe:guards:begin -->';
+export const GUARDS_END = '<!-- specpipe:guards:end -->';
+
+/** How an agent carries guardrails: 'file' | 'doc' | 'agents-md' | null (native hooks). */
+export function agentRulesMode(agentId) {
+  return RULES[agentId]?.mode || null;
+}
+
+/**
+ * Emit the guardrails artifact for an agent from the canonical guards body.
+ * @returns {{ mode, path, content } | null} null for Claude (native hooks).
+ */
+export function emitRules(agentId, body) {
+  const r = RULES[agentId];
+  if (!r) return null;
+  if (r.mode === 'file') return { mode: 'file', path: r.path, content: `---\n${r.frontmatter}\n---\n${body}` };
+  if (r.mode === 'doc') return { mode: 'doc', path: r.path, content: `# specpipe — operating rules\n\n${body}` };
+  // agents-md: a marked section merged into a shared AGENTS.md
+  return { mode: 'agents-md', path: r.path, content: `${GUARDS_BEGIN}\n## specpipe — operating rules\n\n${body}${GUARDS_END}\n` };
+}
+
+// ── Enforced hooks (block tool calls, not just advise) ──────────────────────
+// Agents whose hook payloads + block primitive (exit 2) are verified compatible
+// with the shared guard scripts (kit/hooks/specpipe-*.sh). Claude has its own
+// .claude/hooks; Antigravity/Hermes lack a usable blocking-hook surface → omitted.
+const SHELL_GUARD = 'specpipe-shell-guard.sh';
+const READ_GUARD = 'specpipe-read-guard.sh';
+
+const EHOOKS = {
+  // Codex PreToolUse payload == Claude's (.tool_input.command); exit 2 blocks.
+  // Verified matcher: "Bash". Read/Edit tool names unverified → shell guard only.
+  codex: {
+    dir: '.codex/hooks',
+    scripts: [SHELL_GUARD],
+    configPath: '.codex/hooks.json',
+    config: {
+      hooks: {
+        PreToolUse: [
+          { matcher: 'Bash', hooks: [{ type: 'command', command: `bash .codex/hooks/${SHELL_GUARD}` }] },
+        ],
+      },
+    },
+  },
+  // Cursor: beforeShellExecution (.command) + beforeReadFile (.file_path) verified;
+  // fail-open by default, so failClosed: true to actually enforce.
+  cursor: {
+    dir: '.cursor/hooks',
+    scripts: [SHELL_GUARD, READ_GUARD],
+    configPath: '.cursor/hooks.json',
+    config: {
+      version: 1,
+      hooks: {
+        beforeShellExecution: [{ command: `./.cursor/hooks/${SHELL_GUARD}`, failClosed: true }],
+        beforeReadFile: [{ command: `./.cursor/hooks/${READ_GUARD}`, failClosed: true }],
+      },
+    },
+  },
+};
+
+/** Kit-relative source path for a guard script. */
+export const HOOKS_SRC_DIR = 'hooks';
+
+/** Whether an agent gets enforced (blocking) hooks beyond advisory rules. */
+export function agentHasHooks(agentId) {
+  return !!EHOOKS[agentId];
+}
+
+/**
+ * Emit an agent's enforced-hook artifacts (Codex/Cursor). Returns the scripts to
+ * copy (kit-relative src + on-disk dst) and the hook config file to write, or null.
+ */
+export function emitHooks(agentId) {
+  const h = EHOOKS[agentId];
+  if (!h) return null;
+  return {
+    hooksDir: h.dir,
+    scripts: h.scripts.map((name) => ({ src: `${HOOKS_SRC_DIR}/${name}`, dst: `${h.dir}/${name}` })),
+    configPath: h.configPath,
+    configContent: JSON.stringify(h.config, null, 2) + '\n',
+  };
+}

package/src/lib/agent-install.js

@@ -0,0 +1,161 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile, unlink, chmod, rmdir } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { log } from './logger.js';
+import { getTemplateDir, COMPONENTS } from './installer.js';
+import { emitSkillFile, emitRules, emitHooks, AGENTS, GUARDS_BEGIN, GUARDS_END } from './agents.js';
+
+/**
+ * Emit one canonical skill file for a target agent and write it to targetDir.
+ * Transforms path + frontmatter per the agent's convention (see agents.js).
+ * @returns {{ result: 'copied'|'skipped'|'identical', path?: string }}
+ */
+export async function installSkillForAgent(agentId, canonicalRel, targetDir, { force = false } = {}) {
+  const src = join(getTemplateDir(), canonicalRel);
+  const content = await readFile(src, 'utf-8');
+  const emitted = emitSkillFile(agentId, canonicalRel, content);
+  if (!emitted) return { result: 'skipped' };
+
+  const dst = join(targetDir, emitted.path);
+  if (existsSync(dst) && !force) {
+    try {
+      if ((await readFile(dst, 'utf-8')) === emitted.content) {
+        log.same(`${emitted.path} (identical)`);
+        return { result: 'identical', path: emitted.path };
+      }
+    } catch { /* unreadable — treat as conflict */ }
+    log.warn(`${emitted.path} (exists with different content — use --force to overwrite)`);
+    return { result: 'skipped', path: emitted.path };
+  }
+
+  await mkdir(dirname(dst), { recursive: true });
+  await writeFile(dst, emitted.content);
+  log.copy(emitted.path);
+  return { result: 'copied', path: emitted.path };
+}
+
+/**
+ * Install the full skill set for one agent into targetDir.
+ * @returns {{ agent: string, copied: number, skipped: number, identical: number, paths: string[] }}
+ */
+export async function installAgentSkills(agentId, targetDir, { force = false } = {}) {
+  let copied = 0, skipped = 0, identical = 0;
+  const paths = [];
+  for (const relPath of COMPONENTS.skills) {
+    const { result, path } = await installSkillForAgent(agentId, relPath, targetDir, { force });
+    if (result === 'copied') copied++;
+    else if (result === 'identical') identical++;
+    else skipped++;
+    if (path) paths.push(path);
+  }
+  return { agent: agentId, label: AGENTS[agentId].label, copied, skipped, identical, paths };
+}
+
+const GUARDS_TEMPLATE_REL = 'rules/specpipe-guards.md';
+
+function guardsSectionRegex() {
+  const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(esc(GUARDS_BEGIN) + '[\\s\\S]*?' + esc(GUARDS_END) + '\\n?', '');
+}
+
+/** Merge (or replace) the specpipe guards section in a shared AGENTS.md. */
+export async function mergeAgentsMdGuards(targetDir, section) {
+  const p = join(targetDir, 'AGENTS.md');
+  let existing = '';
+  try { existing = await readFile(p, 'utf-8'); } catch { /* new file */ }
+  const re = guardsSectionRegex();
+  existing = re.test(existing)
+    ? existing.replace(re, section)
+    : (existing.trim() ? existing.trimEnd() + '\n\n' : '') + section;
+  await writeFile(p, existing);
+}
+
+/** Remove the specpipe guards section from AGENTS.md (deletes file if now empty). */
+export async function stripAgentsMdGuards(targetDir) {
+  const p = join(targetDir, 'AGENTS.md');
+  let existing;
+  try { existing = await readFile(p, 'utf-8'); } catch { return false; }
+  const stripped = existing.replace(guardsSectionRegex(), '').trim();
+  if (stripped === existing.trim()) return false;
+  if (stripped) await writeFile(p, stripped + '\n');
+  else await unlink(p);
+  return true;
+}
+
+/**
+ * Install an agent's guardrails: an owned rules file (Cursor/Antigravity/
+ * OpenClaw/Hermes) or a merged section in a shared AGENTS.md (Codex).
+ * Claude returns null — it uses native hooks instead.
+ */
+export async function installAgentRules(agentId, targetDir, { force = false } = {}) {
+  const body = await readFile(join(getTemplateDir(), GUARDS_TEMPLATE_REL), 'utf-8');
+  const r = emitRules(agentId, body);
+  if (!r) return null;
+
+  if (r.mode === 'agents-md') {
+    await mergeAgentsMdGuards(targetDir, r.content);
+    log.copy(`${r.path} (specpipe operating-rules section)`);
+    return { mode: 'agents-md', path: r.path };
+  }
+
+  const dst = join(targetDir, r.path);
+  if (existsSync(dst) && !force) {
+    try {
+      if ((await readFile(dst, 'utf-8')) === r.content) {
+        log.same(`${r.path} (identical)`);
+        return { mode: r.mode, path: r.path };
+      }
+    } catch { /* unreadable — treat as conflict */ }
+    log.warn(`${r.path} (exists with different content — use --force to overwrite)`);
+    return { mode: r.mode, path: r.path };
+  }
+  await mkdir(dirname(dst), { recursive: true });
+  await writeFile(dst, r.content);
+  log.copy(r.path);
+  return { mode: r.mode, path: r.path };
+}
+
+/**
+ * Install an agent's ENFORCED (blocking) hooks: the guard scripts + the agent's
+ * hook config file. Codex/Cursor only (verified payloads). Returns null otherwise.
+ * The hook config is specpipe-owned; if a different one already exists, we skip
+ * unless --force (don't clobber a user's hooks).
+ */
+export async function installAgentHooks(agentId, targetDir, { force = false } = {}) {
+  const h = emitHooks(agentId);
+  if (!h) return null;
+
+  for (const { src, dst } of h.scripts) {
+    const content = await readFile(join(getTemplateDir(), src), 'utf-8');
+    const dstAbs = join(targetDir, dst);
+    await mkdir(dirname(dstAbs), { recursive: true });
+    await writeFile(dstAbs, content);
+    await chmod(dstAbs, 0o755);
+    log.copy(dst);
+  }
+
+  const cfgAbs = join(targetDir, h.configPath);
+  if (existsSync(cfgAbs) && !force) {
+    try {
+      if ((await readFile(cfgAbs, 'utf-8')) === h.configContent) {
+        log.same(`${h.configPath} (identical)`);
+        return { configPath: h.configPath };
+      }
+    } catch { /* unreadable */ }
+    log.warn(`${h.configPath} (exists — use --force to install specpipe enforced hooks)`);
+    return { configPath: h.configPath };
+  }
+  await mkdir(dirname(cfgAbs), { recursive: true });
+  await writeFile(cfgAbs, h.configContent);
+  log.copy(h.configPath);
+  return { configPath: h.configPath };
+}
+
+/** Remove an agent's enforced-hook scripts + config (+ empty hooks dir). */
+export async function removeAgentHooks(agentId, targetDir) {
+  const h = emitHooks(agentId);
+  if (!h) return;
+  for (const { dst } of h.scripts) { try { await unlink(join(targetDir, dst)); } catch { /* */ } }
+  try { await unlink(join(targetDir, h.configPath)); } catch { /* */ }
+  try { await rmdir(join(targetDir, h.hooksDir)); } catch { /* not empty / missing */ }
+}