@polymorphism-tech/morph-spec 4.10.10 → 4.11.1

package/src/lib/build/build-runner.js

@@ -0,0 +1,99 @@
+/**
+ * Build Runner — Resolves and executes the project's build command.
+ *
+ * Resolution order for build command:
+ *   1. .morph/config/config.json → project.buildCommand
+ *   2. Stack profile → profile.buildCommand
+ *   3. package.json → scripts.build → "npm run build"
+ *   4. tsconfig.json at root → "npx tsc --noEmit"
+ *   5. null (no build command detected)
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { getStackProfile } from '../stack/stack-profile.js';
+
+/**
+ * Resolve the build command for a project.
+ *
+ * @param {string} [projectPath] - Project root directory (defaults to '.')
+ * @returns {string | null} The build command to run, or null if none found
+ */
+export function resolveBuildCommand(projectPath = '.') {
+  // 1. Explicit override from .morph/config/config.json
+  const configPath = join(projectPath, '.morph', 'config', 'config.json');
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, 'utf8'));
+      const cmd = config?.project?.buildCommand;
+      if (cmd && typeof cmd === 'string') {
+        return cmd;
+      }
+    } catch {
+      // Malformed config — fall through to detection
+    }
+  }
+
+  // 2. Stack profile default (only when an actual stack is configured)
+  const profile = getStackProfile(projectPath);
+  if (profile.stack !== 'unknown' && profile.buildCommand) {
+    return profile.buildCommand;
+  }
+
+  // 3. package.json with a build script
+  const packageJsonPath = join(projectPath, 'package.json');
+  if (existsSync(packageJsonPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+      if (pkg?.scripts?.build) {
+        return 'npm run build';
+      }
+    } catch {
+      // Malformed package.json — fall through
+    }
+  }
+
+  // 4. tsconfig.json at root → generic type-check
+  if (existsSync(join(projectPath, 'tsconfig.json'))) {
+    return 'npx tsc --noEmit';
+  }
+
+  // 5. Nothing found
+  return null;
+}
+
+/**
+ * Run the project's build check.
+ *
+ * @param {string} [projectPath] - Project root directory (defaults to '.')
+ * @param {object} [opts] - Optional overrides for testing
+ * @param {Function} [opts._execSync] - Override execSync for unit testing
+ * @returns {{ passed?: boolean, output?: string, exitCode?: number, command?: string, skipped?: boolean, reason?: string }}
+ */
+export function runBuildCheck(projectPath = '.', opts = {}) {
+  const cmd = resolveBuildCommand(projectPath);
+
+  if (!cmd) {
+    return { skipped: true, reason: 'No buildCommand configured and no known project file detected' };
+  }
+
+  const exec = opts._execSync ?? execSync;
+
+  try {
+    const output = exec(cmd, {
+      cwd: projectPath,
+      timeout: 120_000,
+      encoding: 'utf8',
+      stdio: 'pipe'
+    });
+    return { passed: true, output: output ?? '', exitCode: 0, command: cmd };
+  } catch (err) {
+    return {
+      passed: false,
+      output: (err.stdout || '') + (err.stderr || ''),
+      exitCode: err.status ?? 1,
+      command: cmd
+    };
+  }
+}

package/src/lib/checkpoints/checkpoint-hooks.js

@@ -0,0 +1,110 @@
+/**
+ * Checkpoint Hooks — Orchestrates validation, build, and test phases at checkpoints.
+ *
+ * This is the module that task-manager.js imports at:
+ *   import('../src/lib/checkpoints/checkpoint-hooks.js')
+ *
+ * All three phases run independently (failures don't short-circuit) so the user
+ * gets a complete picture of all issues in a single checkpoint report.
+ */
+
+import chalk from 'chalk';
+import { runValidation } from '../validators/validation-runner.js';
+import { runBuildCheck } from '../build/build-runner.js';
+import { runTestSuite } from '../tasks/test-runner.js';
+import { persistCheckpointValidation } from '../validators/checkpoint-persistence.js';
+
+/**
+ * Determine whether a checkpoint should run based on task count and frequency.
+ *
+ * @param {number} tasksCompleted - Number of tasks completed so far
+ * @param {number} frequency - Run every N tasks (default: 3)
+ * @returns {boolean}
+ */
+export function shouldRunCheckpoint(tasksCompleted, frequency = 3) {
+  return tasksCompleted > 0 && tasksCompleted % frequency === 0;
+}
+
+/**
+ * Run all checkpoint hooks: static validation, build check, and test suite.
+ *
+ * @param {string} featureName - The feature being worked on
+ * @param {number} checkpointNum - Checkpoint sequence number
+ * @param {object} [opts] - Options
+ * @param {string} [opts.projectPath] - Project root (defaults to cwd)
+ * @returns {Promise<{ passed: boolean, summary: { errors: number, warnings: number }, results: object }>}
+ */
+export async function runCheckpointHooks(featureName, checkpointNum, opts = {}) {
+  const projectPath = opts.projectPath ?? process.cwd();
+  const results = {};
+  let totalErrors = 0;
+  let totalWarnings = 0;
+
+  // Phase 1: Static validators
+  console.log(chalk.gray('\n  Phase 1/3: Running static validators...'));
+  try {
+    const valResult = await runValidation(projectPath, featureName, { verbose: false, mode: 'full' });
+    results.validators = {
+      passed: valResult.passed,
+      errors: valResult.errors,
+      warnings: valResult.warnings,
+      details: valResult.results
+    };
+    totalErrors += valResult.errors;
+    totalWarnings += valResult.warnings;
+  } catch (err) {
+    results.validators = { passed: false, errors: 1, warnings: 0, details: {}, error: err.message };
+    totalErrors += 1;
+  }
+
+  // Phase 2: Build check
+  console.log(chalk.gray('  Phase 2/3: Running build check...'));
+  const buildResult = runBuildCheck(projectPath);
+  results.build = buildResult;
+  if (buildResult.skipped) {
+    console.log(chalk.gray(`    Skipped: ${buildResult.reason}`));
+  } else if (buildResult.passed) {
+    console.log(chalk.green(`    ✓ Build passed (${buildResult.command})`));
+  } else {
+    console.log(chalk.red(`    ✗ Build failed (${buildResult.command})`));
+    totalErrors += 1;
+  }
+
+  // Phase 3: Test suite
+  console.log(chalk.gray('  Phase 3/3: Running test suite...'));
+  const testResult = runTestSuite(projectPath);
+  results.tests = testResult;
+  if (testResult.skipped) {
+    console.log(chalk.gray(`    Skipped: ${testResult.reason}`));
+  } else if (testResult.passed) {
+    console.log(chalk.green('    ✓ Tests passed'));
+  } else {
+    console.log(chalk.red('    ✗ Tests failed'));
+    totalErrors += 1;
+  }
+
+  // Persist results
+  const summaryText = [
+    `Validators: ${results.validators?.errors || 0} errors, ${results.validators?.warnings || 0} warnings`,
+    buildResult.skipped ? 'Build: skipped' : `Build: ${buildResult.passed ? 'passed' : 'FAILED'}`,
+    testResult.skipped ? 'Tests: skipped' : `Tests: ${testResult.passed ? 'passed' : 'FAILED'}`
+  ].join(' | ');
+
+  try {
+    persistCheckpointValidation(projectPath, featureName, {
+      checkpointNum,
+      timestamp: new Date().toISOString(),
+      passed: totalErrors === 0,
+      validators: results,
+      summary: summaryText
+    });
+  } catch {
+    // Non-blocking — persistence failure shouldn't break the checkpoint
+  }
+
+  return {
+    passed: totalErrors === 0,
+    summary: { errors: totalErrors, warnings: totalWarnings },
+    results
+  };
+}

package/src/lib/generators/recap-generator.js

@@ -233,11 +233,34 @@ function buildRecapMarkdown(data) {
 
   // Tasks Detail
   if (tasksSummary.items.length > 0) {
+    const anyNotes = tasksSummary.items.some(t => t.notes?.length > 0);
     md += `## Tasks\n\n`;
-    md += `| ID | Title | Status |\n|----|-------|--------|\n`;
-    for (const task of tasksSummary.items) {
-      const statusIcon = task.status === 'completed' ? '✅' : task.status === 'in_progress' ? '🔄' : '⏳';
-      md += `| ${task.id} | ${task.title || '-'} | ${statusIcon} ${task.status} |\n`;
+    if (anyNotes) {
+      md += `| ID | Title | Status | Notes |\n|----|-------|--------|-------|\n`;
+      for (const task of tasksSummary.items) {
+        const statusIcon = task.status === 'completed' ? '✅' : task.status === 'in_progress' ? '🔄' : '⏳';
+        const noteCount = task.notes?.length || 0;
+        const notesCell = noteCount > 0 ? `${noteCount} note${noteCount > 1 ? 's' : ''}` : '-';
+        md += `| ${task.id} | ${task.title || '-'} | ${statusIcon} ${task.status} | ${notesCell} |\n`;
+      }
+    } else {
+      md += `| ID | Title | Status |\n|----|-------|--------|\n`;
+      for (const task of tasksSummary.items) {
+        const statusIcon = task.status === 'completed' ? '✅' : task.status === 'in_progress' ? '🔄' : '⏳';
+        md += `| ${task.id} | ${task.title || '-'} | ${statusIcon} ${task.status} |\n`;
+      }
+    }
+    md += `\n`;
+  }
+
+  // Deviations from Plan
+  const deviations = tasksSummary.items
+    .filter(t => t.notes?.some(n => n.type === 'deviation'))
+    .flatMap(t => t.notes.filter(n => n.type === 'deviation').map(n => ({ taskId: t.id, text: n.text })));
+  if (deviations.length > 0) {
+    md += `## Deviations from Plan\n\n`;
+    for (const d of deviations) {
+      md += `- **${d.taskId}**: ${d.text}\n`;
     }
     md += `\n`;
   }

package/src/lib/stack/stack-profile.js

@@ -24,6 +24,7 @@ const PROFILES = {
     isDotnet: true, isNextjs: false,
     defaultValidators: ['architecture', 'packages'],
     checkpointValidators: ['architecture', 'packages', 'design-system', 'security'],
+    buildCommand: 'dotnet build --no-restore',
     contractsOutputType: 'contracts',
     contractsFilename: 'contracts.cs',
     contractsLanguage: 'csharp',
@@ -32,6 +33,7 @@ const PROFILES = {
     isDotnet: false, isNextjs: true,
     defaultValidators: ['nextjs-component'],
     checkpointValidators: ['nextjs-component', 'css'],
+    buildCommand: 'npx tsc --noEmit',
     contractsOutputType: 'contractsTs',
     contractsFilename: 'contracts.ts',
     contractsLanguage: 'typescript',
@@ -40,6 +42,7 @@ const PROFILES = {
     isDotnet: false, isNextjs: false,
     defaultValidators: [],
     checkpointValidators: [],
+    buildCommand: null,
     contractsOutputType: 'contracts',
     contractsFilename: 'contracts.cs',
     contractsLanguage: 'csharp',

package/src/lib/tasks/task-parser.js

@@ -122,18 +122,32 @@ export async function parseTasksMd(featureName, cwd = process.cwd()) {
     return [];
   }
 
-  const tasks = [];
+  // Phase 1: collect heading positions
   const headingRe = /^###\s+(T\d+)\s*[—–:\-]\s*(.+)$/gm;
+  const depRe = /\*\*Dependenc(?:y|ies):\*\*\s*(.+)/i;
+  const positions = [];
   let match;
   while ((match = headingRe.exec(content)) !== null) {
-    tasks.push({
-      id: match[1],
-      title: match[2].trim(),
-      status: 'pending',
-      dependencies: [],
-      files: [],
-      checkpoint: null,
-    });
+    positions.push({ id: match[1], title: match[2].trim(), pos: match.index });
+  }
+
+  // Phase 2: extract body and parse dependencies
+  const tasks = [];
+  for (let i = 0; i < positions.length; i++) {
+    const { id, title, pos } = positions[i];
+    const end = i + 1 < positions.length ? positions[i + 1].pos : content.length;
+    const block = content.slice(pos, end);
+
+    let dependencies = [];
+    const depMatch = depRe.exec(block);
+    if (depMatch) {
+      const val = depMatch[1].trim();
+      if (val.toLowerCase() !== 'none') {
+        dependencies = val.split(/[,\s]+/).filter(s => /^T\d+$/.test(s));
+      }
+    }
+
+    tasks.push({ id, title, status: 'pending', dependencies, files: [], checkpoint: null });
   }
   return tasks;
 }

package/src/scripts/global-install.js

@@ -1,9 +1,10 @@
 // src/scripts/global-install.js
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { homedir } from 'os';
-import { mkdir, copyFile } from 'fs/promises';
+import { homedir, platform } from 'os';
+import { mkdir, copyFile, readFile, writeFile } from 'fs/promises';
 import { existsSync } from 'fs';
+import { execSync } from 'child_process';
 import { installGlobalStatusline } from '../utils/hooks-installer.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -27,15 +28,62 @@ export async function installGlobalSkill(claudeDir = join(homedir(), '.claude'))
   await copyFile(src, dest);
 }
 
+/**
+ * Ensure the npm global bin directory is in the user's PATH on Windows.
+ * Adds it to the PowerShell $PROFILE so new terminals find `morph-spec`.
+ */
+export async function ensureNpmGlobalInPath() {
+  if (platform() !== 'win32') return;
+
+  let npmGlobalDir;
+  try {
+    npmGlobalDir = execSync('npm prefix -g', { encoding: 'utf8' }).trim();
+  } catch {
+    return; // can't determine npm global dir
+  }
+
+  if (!npmGlobalDir || !existsSync(npmGlobalDir)) return;
+
+  // --- PowerShell $PROFILE ---
+  const psProfile = join(homedir(), 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1');
+  const psProfileLegacy = join(homedir(), 'Documents', 'WindowsPowerShell', 'Microsoft.PowerShell_profile.ps1');
+
+  const marker = '# morph-spec: ensure npm global in PATH';
+  const snippet = [
+    marker,
+    `if ($env:PATH -notlike "*${npmGlobalDir.replace(/\\/g, '\\\\')}*") {`,
+    `  $env:PATH += ";${npmGlobalDir}"`,
+    '}',
+    '# end morph-spec PATH',
+  ].join('\n');
+
+  for (const profilePath of [psProfile, psProfileLegacy]) {
+    try {
+      let content = '';
+      if (existsSync(profilePath)) {
+        content = await readFile(profilePath, 'utf8');
+        if (content.includes(marker)) continue; // already patched
+      } else {
+        await mkdir(dirname(profilePath), { recursive: true });
+      }
+      const newContent = content ? `${content}\n\n${snippet}\n` : `${snippet}\n`;
+      await writeFile(profilePath, newContent, 'utf8');
+    } catch {
+      // non-critical — skip silently
+    }
+  }
+}
+
 // Run as postinstall script
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
   const HOOKS_SRC = join(FRAMEWORK_DIR, 'hooks', 'claude-code');
   const { readFileSync } = await import('fs');
   const pkg = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
 
-  const [skillResult, statuslineResult] = await Promise.allSettled([
+  const [skillResult, statuslineResult, pathResult] = await Promise.allSettled([
     installGlobalSkill(),
     installGlobalStatusline(HOOKS_SRC),
+    ensureNpmGlobalInPath(),
   ]);
 
   const results = [
@@ -51,6 +99,12 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
       path: '~/.claude/',
       error: statuslineResult.reason?.message,
     },
+    {
+      ok: pathResult.status === 'fulfilled',
+      label: 'PATH (npm global)',
+      path: '$PROFILE',
+      error: pathResult.reason?.message,
+    },
   ];
 
   const { printInstallBanner } = await import('../utils/banner.js');

package/src/utils/file-copier.js

@@ -149,6 +149,7 @@ export async function updateGitignore(projectPath) {
     '.claude/CLAUDE.md',
     '.claude/settings.local.json',
     '.worktrees/',
+    'docs/superpowers/',
     ''
   ];
 

package/src/utils/version-checker.js

@@ -125,16 +125,10 @@ export function getUpdateInstructions(method) {
         'morph-spec update'
       ];
     case 'npx':
-      return [
-        'npx @polymorphism-tech/morph-spec@latest update'
-      ];
     default:
       return [
         'npm install -g @polymorphism-tech/morph-spec@latest',
-        'morph-spec update',
-        '',
-        'Or use npx:',
-        'npx @polymorphism-tech/morph-spec@latest update'
+        'morph-spec update'
       ];
   }
 }

package/framework/hooks/claude-code/pre-tool-use/protect-readonly-files.js

@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-/**
- * DEPRECATED — This hook has been replaced by native permissions.deny in settings.local.json.
- * The file is kept as an empty stub. It is NOT registered in hooks-installer.js.
- * Safe to delete.
- */
-process.exit(0);