@polymorphism-tech/morph-spec 7.4.0 → 7.5.0

package/src/commands/project/worktree.js

@@ -1,210 +1,212 @@
-/**
- * MORPH-SPEC Worktree Setup Command
- *
- * Creates a git worktree at .worktrees/{feature}/ on branch morph/{feature}.
- * Used by SessionStart hook to isolate feature work from the main branch.
- *
- * Usage:
- *   morph-spec worktree setup <feature>
- *   morph-spec worktree setup <feature> --fresh
- *
- * Exit codes:
- *   0  — success (created) or fail-open (not a git repo, git error)
- *   2  — worktree already exists (signals resume scenario to hook caller)
- */
-
-import { execSync } from 'child_process';
-import { existsSync, mkdirSync, symlinkSync, linkSync, copyFileSync } from 'fs';
-import { join, resolve, dirname } from 'path';
-
-// ── Pure helpers (exported for tests) ──────────────────────────────────────
-
-/**
- * Check if a directory is inside a git repository.
- * @param {string} cwd
- * @returns {boolean}
- */
-export function isGitRepo(cwd = process.cwd()) {
-  try {
-    execSync('git rev-parse --git-dir', { cwd, stdio: 'pipe' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check if a branch exists locally.
- * @param {string} branch
- * @param {string} cwd
- * @returns {boolean}
- */
-export function branchExists(branch, cwd = process.cwd()) {
-  try {
-    execSync(`git show-ref --verify --quiet refs/heads/${branch}`, { cwd, stdio: 'pipe' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Check if a worktree path is already registered with git.
- * @param {string} worktreePath  Relative or absolute path
- * @param {string} cwd
- * @returns {boolean}
- */
-export function worktreeExists(worktreePath, cwd = process.cwd()) {
-  try {
-    const output = execSync('git worktree list --porcelain', { cwd, stdio: 'pipe' }).toString();
-    const normalizedPath = worktreePath.replace(/\\/g, '/');
-    const absPath = normalizedPath.startsWith('/') ? normalizedPath : `${cwd.replace(/\\/g, '/')}/${normalizedPath}`;
-    return output.replace(/\\/g, '/').includes(absPath);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Build the worktree directory path (always forward slashes).
- * @param {string} feature
- * @param {string} cwd
- * @param {{ fresh?: boolean }} options
- * @returns {string}
- */
-export function buildWorktreePath(feature, cwd = process.cwd(), options = {}) {
-  const suffix = options.fresh ? `-${getDateSuffix()}` : '';
-  const normalizedCwd = cwd.replace(/\\/g, '/');
-  return `${normalizedCwd}/.worktrees/${feature}${suffix}`;
-}
-
-/**
- * Build the branch name for a feature worktree.
- * @param {string} feature
- * @param {{ fresh?: boolean }} options
- * @returns {string}
- */
-export function buildBranchName(feature, options = {}) {
-  const suffix = options.fresh ? `-${getDateSuffix()}` : '';
-  return `morph/${feature}${suffix}`;
-}
-
-function getDateSuffix() {
-  return new Date().toISOString().slice(0, 10).replace(/-/g, '');
-}
-
-// ── Infrastructure linking ───────────────────────────────────────────────────
-
-/**
- * Create symlinks/junctions in the worktree for shared infrastructure files
- * that are gitignored (state.json, .claude/, .morph/framework/, node_modules/).
- *
- * Uses junctions for directories (no admin required on Windows).
- * File symlinks fall back to copy if symlink fails.
- * Fail-open: any error is silently ignored.
- *
- * @param {string} worktreePath - Absolute path to the worktree
- * @param {string} mainCwd - Absolute path to the main project root
- */
-export function setupInfraLinks(worktreePath, mainCwd) {
-  const mainAbs = resolve(mainCwd);
-  const wtAbs = resolve(worktreePath);
-
-  // Directory junctions — shared across worktrees
-  const dirLinks = ['node_modules', '.claude'];
-
-  // .morph/framework/ — client projects (in framework repo, framework/ is tracked)
-  if (existsSync(join(mainAbs, '.morph', 'framework'))) {
-    dirLinks.push(join('.morph', 'framework'));
-  }
-
-  for (const rel of dirLinks) {
-    const target = join(mainAbs, rel);
-    const linkPath = join(wtAbs, rel);
-    if (!existsSync(target) || existsSync(linkPath)) continue;
-    try {
-      const parent = dirname(linkPath);
-      if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
-      symlinkSync(target, linkPath, 'junction');
-    } catch { /* fail-open */ }
-  }
-
-  // state.json — shared state via hard link (works on Windows without admin,
-  // same NTFS volume). Falls back to symlink, then copy.
-  const stateTarget = join(mainAbs, '.morph', 'state.json');
-  const stateLink = join(wtAbs, '.morph', 'state.json');
-  if (existsSync(stateTarget) && !existsSync(stateLink)) {
-    const morphDir = join(wtAbs, '.morph');
-    if (!existsSync(morphDir)) {
-      try { mkdirSync(morphDir, { recursive: true }); } catch { /* */ }
-    }
-    try {
-      linkSync(stateTarget, stateLink); // hard link — no admin, shared data
-    } catch {
-      try { copyFileSync(stateTarget, stateLink); } catch { /* fail-open */ }
-    }
-  }
-}
-
-// ── Command handler ─────────────────────────────────────────────────────────
-
-/**
- * Main command handler for `morph-spec worktree setup <feature>`
- * @param {string} feature
- * @param {{ fresh?: boolean, cwd?: string }} options
- */
-export async function worktreeSetupCommand(feature, options = {}) {
-  const cwd = options.cwd || process.cwd();
-
-  // Gate 1: Must be a git repo
-  if (!isGitRepo(cwd)) {
-    console.log(JSON.stringify({ created: false, error: 'not-a-git-repo', feature }));
-    process.exit(0); // Fail-open
-  }
-
-  const branch = buildBranchName(feature, options);
-  const worktreePath = buildWorktreePath(feature, cwd, options);
-
-  // Gate 2: If worktree already registered and not --fresh, signal resume
-  if (!options.fresh && worktreeExists(worktreePath, cwd)) {
-    console.log(JSON.stringify({ created: false, alreadyExists: true, path: worktreePath, branch, feature }));
-    process.exit(2); // Convention: 2 = already exists
-  }
-
-  try {
-    // Create branch if needed (based off current HEAD)
-    if (!branchExists(branch, cwd)) {
-      execSync(`git branch ${branch}`, { cwd, stdio: 'pipe' });
-    }
-
-    // Create worktree directory parent if needed
-    const parentDir = join(cwd, '.worktrees');
-    if (!existsSync(parentDir)) {
-      mkdirSync(parentDir, { recursive: true });
-    }
-
-    // Add worktree
-    execSync(`git worktree add "${worktreePath}" ${branch}`, { cwd, stdio: 'pipe' });
-
-    // Set up infrastructure symlinks so the worktree has state.json, .claude/, etc.
-    setupInfraLinks(worktreePath, cwd);
-
-    // Persist in state (non-blocking — feature may not be in state yet)
-    try {
-      const { loadState, saveState } = await import('../../lib/state/state-manager.js');
-      const state = loadState(cwd);
-      if (state?.features?.[feature]) {
-        state.features[feature].worktree = { path: worktreePath, branch, createdAt: new Date().toISOString() };
-        saveState(state, cwd);
-      }
-    } catch {
-      // Non-blocking
-    }
-
-    console.log(JSON.stringify({ created: true, path: worktreePath, branch, feature }));
-    process.exit(0);
-  } catch (err) {
-    console.log(JSON.stringify({ created: false, error: (err.message || 'unknown').slice(0, 200), feature }));
-    process.exit(0); // Fail-open
-  }
-}
+/**
+ * MORPH-SPEC Worktree Setup Command
+ *
+ * Creates a git worktree at .worktrees/{feature}/ on branch morph/{feature}.
+ * Used by SessionStart hook to isolate feature work from the main branch.
+ *
+ * Usage:
+ *   morph-spec worktree setup <feature>
+ *   morph-spec worktree setup <feature> --fresh
+ *
+ * Exit codes:
+ *   0  — success (created) or fail-open (not a git repo, git error)
+ *   2  — worktree already exists (signals resume scenario to hook caller)
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync, symlinkSync, linkSync, copyFileSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+
+// ── Pure helpers (exported for tests) ──────────────────────────────────────
+
+/**
+ * Check if a directory is inside a git repository.
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function isGitRepo(cwd = process.cwd()) {
+  try {
+    execSync('git rev-parse --git-dir', { cwd, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a branch exists locally.
+ * @param {string} branch
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function branchExists(branch, cwd = process.cwd()) {
+  try {
+    execSync(`git show-ref --verify --quiet refs/heads/${branch}`, { cwd, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Check if a worktree path is already registered with git.
+ * @param {string} worktreePath  Relative or absolute path
+ * @param {string} cwd
+ * @returns {boolean}
+ */
+export function worktreeExists(worktreePath, cwd = process.cwd()) {
+  try {
+    const output = execSync('git worktree list --porcelain', { cwd, stdio: 'pipe' }).toString();
+    const normalizedPath = worktreePath.replace(/\\/g, '/');
+    const absPath = normalizedPath.startsWith('/') ? normalizedPath : `${cwd.replace(/\\/g, '/')}/${normalizedPath}`;
+    return output.replace(/\\/g, '/').includes(absPath);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Build the worktree directory path (always forward slashes).
+ * @param {string} feature
+ * @param {string} cwd
+ * @param {{ fresh?: boolean }} options
+ * @returns {string}
+ */
+export function buildWorktreePath(feature, cwd = process.cwd(), options = {}) {
+  const suffix = options.fresh ? `-${getDateSuffix()}` : '';
+  const normalizedCwd = cwd.replace(/\\/g, '/');
+  return `${normalizedCwd}/.worktrees/${feature}${suffix}`;
+}
+
+/**
+ * Build the branch name for a feature worktree.
+ * @param {string} feature
+ * @param {{ fresh?: boolean }} options
+ * @returns {string}
+ */
+export function buildBranchName(feature, options = {}) {
+  const suffix = options.fresh ? `-${getDateSuffix()}` : '';
+  return `morph/${feature}${suffix}`;
+}
+
+function getDateSuffix() {
+  return new Date().toISOString().slice(0, 10).replace(/-/g, '');
+}
+
+// ── Infrastructure linking ───────────────────────────────────────────────────
+
+/**
+ * Create symlinks/junctions in the worktree for shared infrastructure files
+ * that are gitignored (state.json, .claude/, .morph/framework/, node_modules/).
+ *
+ * Uses junctions for directories (no admin required on Windows).
+ * File symlinks fall back to copy if symlink fails.
+ * Fail-open: any error is silently ignored.
+ *
+ * @param {string} worktreePath - Absolute path to the worktree
+ * @param {string} mainCwd - Absolute path to the main project root
+ */
+export function setupInfraLinks(worktreePath, mainCwd) {
+  const mainAbs = resolve(mainCwd);
+  const wtAbs = resolve(worktreePath);
+
+  // Directory junctions — shared across worktrees
+  const dirLinks = ['node_modules', '.claude'];
+
+  // .morph/framework/ — client projects (in framework repo, framework/ is tracked)
+  if (existsSync(join(mainAbs, '.morph', 'framework'))) {
+    dirLinks.push(join('.morph', 'framework'));
+  }
+
+  for (const rel of dirLinks) {
+    const target = join(mainAbs, rel);
+    const linkPath = join(wtAbs, rel);
+    if (!existsSync(target) || existsSync(linkPath)) continue;
+    try {
+      const parent = dirname(linkPath);
+      if (!existsSync(parent)) mkdirSync(parent, { recursive: true });
+      symlinkSync(target, linkPath, 'junction');
+    } catch { /* fail-open */ }
+  }
+
+  // state.json — shared state via hard link (works on Windows without admin,
+  // same NTFS volume). Falls back to symlink, then copy.
+  const stateTarget = join(mainAbs, '.morph', 'state.json');
+  const stateLink = join(wtAbs, '.morph', 'state.json');
+  if (existsSync(stateTarget) && !existsSync(stateLink)) {
+    const morphDir = join(wtAbs, '.morph');
+    if (!existsSync(morphDir)) {
+      try { mkdirSync(morphDir, { recursive: true }); } catch { /* */ }
+    }
+    try {
+      linkSync(stateTarget, stateLink); // hard link — no admin, shared data
+    } catch {
+      try { copyFileSync(stateTarget, stateLink); } catch { /* fail-open */ }
+    }
+  }
+}
+
+// ── Command handler ─────────────────────────────────────────────────────────
+
+/**
+ * Main command handler for `morph-spec worktree setup <feature>`
+ * @param {string} feature
+ * @param {{ fresh?: boolean, cwd?: string }} options
+ */
+export async function worktreeSetupCommand(feature, options = {}) {
+  const cwd = options.cwd || process.cwd();
+
+  // Gate 1: Must be a git repo
+  if (!isGitRepo(cwd)) {
+    console.log(JSON.stringify({ created: false, error: 'not-a-git-repo', feature }));
+    process.exit(0); // Fail-open
+  }
+
+  const branch = buildBranchName(feature, options);
+  const worktreePath = buildWorktreePath(feature, cwd, options);
+
+  // Gate 2: If worktree already registered and not --fresh, signal resume
+  if (!options.fresh && worktreeExists(worktreePath, cwd)) {
+    console.log(JSON.stringify({ created: false, alreadyExists: true, path: worktreePath, branch, feature }));
+    process.exit(2); // Convention: 2 = already exists
+  }
+
+  try {
+    // Create branch if needed (based off current HEAD)
+    if (!branchExists(branch, cwd)) {
+      execSync(`git branch ${branch}`, { cwd, stdio: 'pipe' });
+    }
+
+    // Create worktree directory parent if needed
+    const parentDir = join(cwd, '.worktrees');
+    if (!existsSync(parentDir)) {
+      mkdirSync(parentDir, { recursive: true });
+    }
+
+    // Add worktree
+    execSync(`git worktree add "${worktreePath}" ${branch}`, { cwd, stdio: 'pipe' });
+
+    // Set up infrastructure symlinks so the worktree has state.json, .claude/, etc.
+    setupInfraLinks(worktreePath, cwd);
+
+    // Persist in state (non-blocking — feature may not be in state yet).
+    // NOTE: imports from core/ (the lib/ path was a latent bug that silently
+    // no-op'd this whole block); loadState/saveState operate on the cwd's state.
+    try {
+      const { loadState, saveState } = await import('../../core/state/state-manager.js');
+      const state = loadState(false);
+      if (state?.features?.[feature]) {
+        state.features[feature].worktree = { path: worktreePath, branch, createdAt: new Date().toISOString() };
+        saveState(state);
+      }
+    } catch {
+      // Non-blocking
+    }
+
+    console.log(JSON.stringify({ created: true, path: worktreePath, branch, feature }));
+    process.exit(0);
+  } catch (err) {
+    console.log(JSON.stringify({ created: false, error: (err.message || 'unknown').slice(0, 200), feature }));
+    process.exit(0); // Fail-open
+  }
+}

package/src/commands/state/advance.js

@@ -0,0 +1,82 @@
+import chalk from 'chalk';
+import { existsSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { getFeature, setApprovalGate, derivePhase } from '../../core/state/state-manager.js';
+
+/**
+ * `morph-spec advance <feature>` — approve the current phase's gate AND scaffold
+ * the next phase's folder in one step. This is the sanctioned, one-command way
+ * to move a feature forward: it removes the need to hand-edit state.json (gate)
+ * AND the need to `mkdir` the next phase folder by hand. Once the gate is
+ * approved, the enforce-phase-writes hook permits writing the next phase's first
+ * canonical artifact (which then advances the derived phase).
+ */
+
+// The gate approved when *completing* a given phase. `implement` has no gate
+// (it ends when all tasks are done), so advancing from implement just scaffolds
+// the review folder.
+const PHASE_GATE = { proposal: 'proposal', uiux: 'uiux', plan: 'plan', review: 'review' };
+
+// The next phase folder to scaffold when advancing FROM a given phase. The
+// default forward path skips the optional design phase (proposal → plan); pass
+// --design to take the uiux branch (proposal → 1-design).
+const NEXT_PHASE_DIR = {
+  proposal: '2-plan',
+  uiux: '2-plan',
+  plan: '3-implement',
+  implement: '4-review',
+};
+
+/** Resolve who approved, honestly (mirrors approve.js — no fake human signatures). */
+function resolveApprovedBy(options) {
+  if (options.approver) return options.approver;
+  if (options.mode === 'auto') return 'auto';
+  if (process.stdin.isTTY) return process.env.USER || process.env.USERNAME || 'user';
+  return 'auto';
+}
+
+export async function advanceCommand(featureName, options = {}) {
+  try {
+    const feature = getFeature(featureName);
+    if (!feature) {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+      process.exit(1);
+    }
+
+    const featurePath = join(process.cwd(), '.morph', 'features', featureName);
+    const phase = derivePhase(featurePath);
+
+    if (phase === 'review') {
+      console.log(chalk.yellow(`\n⚠️  Feature "${featureName}" is already at the final phase (review).`));
+      console.log(chalk.gray(`Approve Gate 3 with: morph-spec approve ${featureName} review`));
+      console.log(chalk.gray(`Then archive with:   morph-spec archive ${featureName}\n`));
+      return;
+    }
+
+    // 1) Approve the gate that completes the current phase.
+    const gate = PHASE_GATE[phase];
+    if (gate) {
+      await setApprovalGate(featureName, gate, true, {
+        approvedBy: resolveApprovedBy(options),
+        approvedAt: new Date().toISOString(),
+        notes: options.notes,
+      });
+    }
+
+    // 2) Scaffold the next phase folder so the agent can write its first artifact.
+    let nextDir = NEXT_PHASE_DIR[phase];
+    if (phase === 'proposal' && options.design) nextDir = '1-design';
+    if (nextDir) {
+      const nextPath = join(featurePath, nextDir);
+      if (!existsSync(nextPath)) mkdirSync(nextPath, { recursive: true });
+    }
+
+    console.log(chalk.green(`\n✅ Advanced "${featureName}" past the ${phase} phase.`));
+    if (gate) console.log(chalk.gray(`   Gate "${gate}" approved (${resolveApprovedBy(options)}).`));
+    if (nextDir) console.log(chalk.gray(`   Scaffolded ${nextDir}/ — ready for the next phase's first artifact.\n`));
+    else console.log('');
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error advancing feature: ${error.message}\n`));
+    process.exit(1);
+  }
+}

package/src/commands/state/archive.js

@@ -0,0 +1,111 @@
+import chalk from 'chalk';
+import { existsSync, renameSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import { execSync } from 'child_process';
+import { getFeature, getApprovalGate } from '../../core/state/state-manager.js';
+
+/**
+ * `morph-spec archive <feature>` — atomic, git-aware archive of a completed
+ * feature. Replaces the manual `/morph-archive` mv: it stamps the feature
+ * completed, moves `.morph/features/{name}/` → `.morph/archive/{name}/`
+ * (staging the move in git when possible), and cleans the thin root index.
+ *
+ * Taxonomy: archived = `status: "completed"` + `archivedAt` (per the project
+ * decision — no separate "archived" status value).
+ */
+
+function isGitRepo(cwd) {
+  try {
+    execSync('git rev-parse --is-inside-work-tree', { cwd, stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function archiveCommand(featureName, options = {}) {
+  try {
+    const feature = getFeature(featureName);
+    if (!feature) {
+      console.error(chalk.red(`\n❌ Feature not found: ${featureName}\n`));
+      process.exit(1);
+    }
+
+    // Precondition: Gate 3 (review) approved — archiving is for completed work.
+    const reviewGate = getApprovalGate(featureName, 'review');
+    if (!reviewGate?.approved && !options.force) {
+      console.error(chalk.red(`\n❌ Gate 3 (review) is not approved for "${featureName}".`));
+      console.log(chalk.gray(`Approve it first (morph-spec approve ${featureName} review) or pass --force.\n`));
+      process.exit(1);
+    }
+
+    const cwd = process.cwd();
+    const featuresPath = join(cwd, '.morph', 'features', featureName);
+    if (!existsSync(featuresPath)) {
+      console.error(chalk.red(`\n❌ Feature folder not found: .morph/features/${featureName}\n`));
+      process.exit(1);
+    }
+    const archiveDir = join(cwd, '.morph', 'archive');
+    const archivePath = join(archiveDir, featureName);
+    if (existsSync(archivePath)) {
+      console.error(chalk.red(`\n❌ Already archived: .morph/archive/${featureName}\n`));
+      process.exit(1);
+    }
+
+    // 1) Stamp the authoritative feature.json (in place) as completed + archived.
+    const fjPath = join(featuresPath, 'feature.json');
+    if (existsSync(fjPath)) {
+      const fj = JSON.parse(readFileSync(fjPath, 'utf8'));
+      fj.status = 'completed';
+      fj.archivedAt = new Date().toISOString();
+      fj.updatedAt = fj.archivedAt;
+      writeFileSync(fjPath, JSON.stringify(fj, null, 2), 'utf8');
+    }
+
+    // 2) Move the folder. Prefer `git mv` (keeps history + stages in one step);
+    //    fall back to a filesystem rename (+ git add) when the folder isn't
+    //    tracked yet or git mv fails.
+    mkdirSync(archiveDir, { recursive: true });
+    const useGit = isGitRepo(cwd) && options.git !== false;
+    let staged = false;
+    if (useGit) {
+      try {
+        execSync(`git mv "${featuresPath}" "${archivePath}"`, { cwd, stdio: 'pipe' });
+        staged = true;
+      } catch {
+        renameSync(featuresPath, archivePath);
+        try {
+          execSync(`git add -A "${featuresPath}" "${archivePath}"`, { cwd, stdio: 'pipe' });
+          staged = true;
+        } catch { /* not fatal — the move succeeded */ }
+      }
+    } else {
+      renameSync(featuresPath, archivePath);
+    }
+
+    // 3) Drop the feature from the thin root index. We edit the index file
+    //    directly rather than calling saveState — saveState would re-create
+    //    .morph/features/{name}/feature.json and undo the archive.
+    const rootPath = join(cwd, '.morph', 'state.json');
+    if (existsSync(rootPath)) {
+      try {
+        const root = JSON.parse(readFileSync(rootPath, 'utf8'));
+        if (root.features && root.features[featureName]) {
+          delete root.features[featureName];
+          root.metadata = root.metadata || {};
+          root.metadata.totalFeatures = Object.keys(root.features).length;
+          writeFileSync(rootPath, JSON.stringify(root, null, 2), 'utf8');
+        }
+      } catch { /* index is derivable — non-fatal */ }
+    }
+
+    console.log(chalk.green(`\n📦 Archived "${featureName}" → .morph/archive/${featureName}/`));
+    console.log(chalk.gray(`   status: completed, archivedAt stamped in feature.json.`));
+    if (staged) console.log(chalk.gray(`   Move staged in git.\n`));
+    else if (useGit) console.log(chalk.gray(`   Move complete; stage it manually if needed.\n`));
+    else console.log('');
+  } catch (error) {
+    console.error(chalk.red(`\n❌ Error archiving feature: ${error.message}\n`));
+    process.exit(1);
+  }
+}