@polymorphism-tech/morph-spec 2.2.0 → 2.4.0

package/package.json

@@ -1,80 +1,80 @@
-{
-  "name": "@polymorphism-tech/morph-spec",
-  "version": "2.2.0",
-  "description": "MORPH-SPEC v2.0: AI-First development framework with .NET 10, Microsoft Agent Framework, and Fluent UI Blazor",
-  "keywords": [
-    "claude-code",
-    "claude",
-    "ai-coding",
-    "ai-first",
-    "spec-driven",
-    "dotnet",
-    "dotnet10",
-    "blazor",
-    "agent-framework",
-    "fluent-ui",
-    "framework",
-    "developer-tools",
-    "morph",
-    "polymorphism",
-    "micro-saas"
-  ],
-  "main": "src/index.js",
-  "bin": {
-    "morph-spec": "bin/morph-spec.js"
-  },
-  "files": [
-    "bin/",
-    "src/",
-    "scripts/",
-    "detectors/",
-    "content/",
-    "docs/",
-    "README.md",
-    "LICENSE",
-    "CLAUDE.md"
-  ],
-  "type": "module",
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "scripts": {
-    "postinstall": "node scripts/postinstall.js",
-    "start": "node bin/morph-spec.js",
-    "test": "node --test",
-    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov node --test",
-    "test:coverage:summary": "c8 --reporter=text-summary node --test",
-    "docs": "jsdoc -c jsdoc.json",
-    "docs:watch": "jsdoc -c jsdoc.json --watch",
-    "docs:serve": "npx http-server docs/api -p 8080 -o"
-  },
-  "dependencies": {
-    "ajv": "^8.12.0",
-    "ajv-formats": "^3.0.1",
-    "chalk": "^5.3.0",
-    "commander": "^12.0.0",
-    "fs-extra": "^11.2.0",
-    "glob": "^10.3.0",
-    "ora": "^8.0.0",
-    "yaml": "^2.3.4"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lucasPolymorphism/morph-spec-framework.git"
-  },
-  "author": "Polymorphism Tech <contact@polymorphism.com.br>",
-  "license": "SEE LICENSE IN LICENSE",
-  "homepage": "https://polymorphism.com.br/morph-spec",
-  "bugs": {
-    "email": "support@polymorphism.com.br"
-  },
-  "private": false,
-  "publishConfig": {
-    "access": "public"
-  },
-  "devDependencies": {
-    "c8": "^10.1.3",
-    "docdash": "^2.0.2",
-    "jsdoc": "^4.0.5"
-  }
-}
+{
+  "name": "@polymorphism-tech/morph-spec",
+  "version": "2.4.0",
+  "description": "MORPH-SPEC v2.0: AI-First development framework with .NET 10, Microsoft Agent Framework, and Fluent UI Blazor",
+  "keywords": [
+    "claude-code",
+    "claude",
+    "ai-coding",
+    "ai-first",
+    "spec-driven",
+    "dotnet",
+    "dotnet10",
+    "blazor",
+    "agent-framework",
+    "fluent-ui",
+    "framework",
+    "developer-tools",
+    "morph",
+    "polymorphism",
+    "micro-saas"
+  ],
+  "main": "src/index.js",
+  "bin": {
+    "morph-spec": "bin/morph-spec.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "scripts/",
+    "detectors/",
+    "content/",
+    "docs/",
+    "README.md",
+    "LICENSE",
+    "CLAUDE.md"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "start": "node bin/morph-spec.js",
+    "test": "node --test",
+    "test:coverage": "c8 --reporter=text --reporter=html --reporter=lcov node --test",
+    "test:coverage:summary": "c8 --reporter=text-summary node --test",
+    "docs": "jsdoc -c jsdoc.json",
+    "docs:watch": "jsdoc -c jsdoc.json --watch",
+    "docs:serve": "npx http-server docs/api -p 8080 -o"
+  },
+  "dependencies": {
+    "ajv": "^8.12.0",
+    "ajv-formats": "^3.0.1",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "fs-extra": "^11.2.0",
+    "glob": "^10.3.0",
+    "ora": "^8.0.0",
+    "yaml": "^2.3.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucasPolymorphism/morph-spec-framework.git"
+  },
+  "author": "Polymorphism Tech <contact@polymorphism.com.br>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://polymorphism.com.br/morph-spec",
+  "bugs": {
+    "email": "support@polymorphism.com.br"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "c8": "^10.1.3",
+    "docdash": "^2.0.2",
+    "jsdoc": "^4.0.5"
+  }
+}

package/scripts/postinstall.js

@@ -1,132 +1,132 @@
-#!/usr/bin/env node
-
-/**
- * Postinstall script for @polymorphism-tech/morph-spec
- *
- * Checks if morph-spec is accessible in PATH and warns users
- * if it's not (common issue with nvm-windows).
- */
-
-import { execSync } from 'child_process';
-import { platform } from 'os';
-import chalk from 'chalk';
-
-const isWindows = platform() === 'win32';
-
-/**
- * Check if morph-spec command is in PATH
- */
-function isMorphSpecInPath() {
-  try {
-    const command = isWindows ? 'where morph-spec' : 'which morph-spec';
-    execSync(command, { stdio: 'ignore' });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Detect if nvm-windows is installed
- */
-function isUsingNvmWindows() {
-  if (!isWindows) return false;
-
-  try {
-    const path = process.env.PATH || '';
-    return path.includes('nvm4w') || path.includes('\\nvm\\');
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Get npm global prefix
- */
-function getNpmGlobalPrefix() {
-  try {
-    const prefix = execSync('npm config get prefix', { encoding: 'utf8' }).trim();
-    return prefix;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Show installation success message
- */
-function showSuccessMessage() {
-  console.log('');
-  console.log(chalk.green('✓ @polymorphism-tech/morph-spec installed successfully!'));
-  console.log('');
-  console.log(chalk.cyan('Quick start:'));
-  console.log(chalk.white('  morph-spec init'));
-  console.log(chalk.white('  morph-spec --help'));
-  console.log('');
-}
-
-/**
- * Show PATH warning for nvm-windows users
- */
-function showPathWarning() {
-  console.log('');
-  console.log(chalk.yellow('⚠ Warning: morph-spec command not found in PATH'));
-  console.log('');
-
-  if (isUsingNvmWindows()) {
-    console.log(chalk.white('You are using nvm-windows, which does not automatically add'));
-    console.log(chalk.white('npm global packages to your PATH.'));
-    console.log('');
-    console.log(chalk.cyan('Solution 1: Add npm global directory to PATH'));
-
-    const prefix = getNpmGlobalPrefix();
-    if (prefix) {
-      console.log(chalk.white(`  Add this to your PATH: ${chalk.yellow(prefix)}`));
-      console.log('');
-      console.log(chalk.gray('  PowerShell (as Administrator):'));
-      console.log(chalk.white(`    [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";${prefix}", "User")`));
-      console.log('');
-      console.log(chalk.gray('  Or manually via System Properties > Environment Variables'));
-    }
-
-    console.log('');
-    console.log(chalk.cyan('Solution 2: Use npx (recommended)'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec init'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec --help'));
-  } else {
-    console.log(chalk.white('The morph-spec command was not found in your PATH.'));
-    console.log('');
-    console.log(chalk.cyan('Solution: Use npx instead'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec init'));
-    console.log(chalk.white('  npx @polymorphism-tech/morph-spec --help'));
-  }
-
-  console.log('');
-  console.log(chalk.gray('For more help, see: https://github.com/lucasPolymorphism/morph-spec-framework#troubleshooting'));
-  console.log('');
-}
-
-/**
- * Main postinstall check
- */
-function main() {
-  // Only show messages for global installs
-  // Skip for local installs (when used as dependency)
-  const isGlobalInstall = process.env.npm_config_global === 'true';
-
-  if (!isGlobalInstall) {
-    // Silent exit for local installs
-    return;
-  }
-
-  // Give npm a moment to set up the symlinks
-  setTimeout(() => {
-    if (isMorphSpecInPath()) {
-      showSuccessMessage();
-    } else {
-      showPathWarning();
-    }
-  }, 100);
-}
-
-main();
+#!/usr/bin/env node
+
+/**
+ * Postinstall script for @polymorphism-tech/morph-spec
+ *
+ * Checks if morph-spec is accessible in PATH and warns users
+ * if it's not (common issue with nvm-windows).
+ */
+
+import { execSync } from 'child_process';
+import { platform } from 'os';
+import chalk from 'chalk';
+
+const isWindows = platform() === 'win32';
+
+/**
+ * Check if morph-spec command is in PATH
+ */
+function isMorphSpecInPath() {
+  try {
+    const command = isWindows ? 'where morph-spec' : 'which morph-spec';
+    execSync(command, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Detect if nvm-windows is installed
+ */
+function isUsingNvmWindows() {
+  if (!isWindows) return false;
+
+  try {
+    const path = process.env.PATH || '';
+    return path.includes('nvm4w') || path.includes('\\nvm\\');
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get npm global prefix
+ */
+function getNpmGlobalPrefix() {
+  try {
+    const prefix = execSync('npm config get prefix', { encoding: 'utf8' }).trim();
+    return prefix;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Show installation success message
+ */
+function showSuccessMessage() {
+  console.log('');
+  console.log(chalk.green('✓ @polymorphism-tech/morph-spec installed successfully!'));
+  console.log('');
+  console.log(chalk.cyan('Quick start:'));
+  console.log(chalk.white('  morph-spec init'));
+  console.log(chalk.white('  morph-spec --help'));
+  console.log('');
+}
+
+/**
+ * Show PATH warning for nvm-windows users
+ */
+function showPathWarning() {
+  console.log('');
+  console.log(chalk.yellow('⚠ Warning: morph-spec command not found in PATH'));
+  console.log('');
+
+  if (isUsingNvmWindows()) {
+    console.log(chalk.white('You are using nvm-windows, which does not automatically add'));
+    console.log(chalk.white('npm global packages to your PATH.'));
+    console.log('');
+    console.log(chalk.cyan('Solution 1: Add npm global directory to PATH'));
+
+    const prefix = getNpmGlobalPrefix();
+    if (prefix) {
+      console.log(chalk.white(`  Add this to your PATH: ${chalk.yellow(prefix)}`));
+      console.log('');
+      console.log(chalk.gray('  PowerShell (as Administrator):'));
+      console.log(chalk.white(`    [Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";${prefix}", "User")`));
+      console.log('');
+      console.log(chalk.gray('  Or manually via System Properties > Environment Variables'));
+    }
+
+    console.log('');
+    console.log(chalk.cyan('Solution 2: Use npx (recommended)'));
+    console.log(chalk.white('  npx @polymorphism-tech/morph-spec init'));
+    console.log(chalk.white('  npx @polymorphism-tech/morph-spec --help'));
+  } else {
+    console.log(chalk.white('The morph-spec command was not found in your PATH.'));
+    console.log('');
+    console.log(chalk.cyan('Solution: Use npx instead'));
+    console.log(chalk.white('  npx @polymorphism-tech/morph-spec init'));
+    console.log(chalk.white('  npx @polymorphism-tech/morph-spec --help'));
+  }
+
+  console.log('');
+  console.log(chalk.gray('For more help, see: https://github.com/lucasPolymorphism/morph-spec-framework#troubleshooting'));
+  console.log('');
+}
+
+/**
+ * Main postinstall check
+ */
+function main() {
+  // Only show messages for global installs
+  // Skip for local installs (when used as dependency)
+  const isGlobalInstall = process.env.npm_config_global === 'true';
+
+  if (!isGlobalInstall) {
+    // Silent exit for local installs
+    return;
+  }
+
+  // Give npm a moment to set up the symlinks
+  setTimeout(() => {
+    if (isMorphSpecInPath()) {
+      showSuccessMessage();
+    } else {
+      showPathWarning();
+    }
+  }, 100);
+}
+
+main();

package/src/commands/advance-phase.js

@@ -0,0 +1,183 @@
+/**
+ * MORPH-SPEC Phase Advance Command
+ *
+ * Validates current phase → advances to next → shows requirements.
+ * Replaces the two-step `state set` + `validate-phase` dance.
+ *
+ * Usage:
+ *   morph-spec phase advance <feature>
+ *   morph-spec phase advance <feature> --skip-optional
+ */
+
+import chalk from 'chalk';
+import { loadState, saveState, getFeature } from '../lib/state-manager.js';
+import { PHASES, validatePhase } from './validate-phase.js';
+
+// Phase order for advancing (skips optional phases unless active)
+const PHASE_ORDER = ['proposal', 'setup', 'uiux', 'design', 'clarify', 'tasks', 'implement', 'sync'];
+
+/**
+ * Get the next phase after the current one
+ */
+function getNextPhase(currentPhase, feature, skipOptional) {
+  const currentIndex = PHASE_ORDER.indexOf(currentPhase);
+  if (currentIndex === -1 || currentIndex >= PHASE_ORDER.length - 1) {
+    return null;
+  }
+
+  for (let i = currentIndex + 1; i < PHASE_ORDER.length; i++) {
+    const candidate = PHASE_ORDER[i];
+    const phaseDef = PHASES[candidate];
+
+    // Skip optional phases if flag set or no relevant agents/outputs
+    if (phaseDef?.optional && skipOptional) {
+      continue;
+    }
+
+    // Skip uiux if no UI agents are active
+    if (candidate === 'uiux') {
+      const uiAgents = ['blazor-builder', 'uiux-designer'];
+      const hasUiAgent = feature.activeAgents?.some(a => uiAgents.includes(a));
+      if (!hasUiAgent && skipOptional !== false) {
+        continue;
+      }
+    }
+
+    // Skip sync for simple workflows
+    if (candidate === 'sync') {
+      const isSimple = feature.workflow === 'fast-track';
+      if (isSimple && skipOptional !== false) {
+        continue;
+      }
+    }
+
+    return candidate;
+  }
+
+  return null;
+}
+
+/**
+ * Main command handler
+ */
+export async function advancePhaseCommand(feature, options = {}) {
+  console.log(chalk.cyan('\n╔════════════════════════════════════════════════╗'));
+  console.log(chalk.cyan('║     MORPH-SPEC PHASE ADVANCE                   ║'));
+  console.log(chalk.cyan('╚════════════════════════════════════════════════╝\n'));
+
+  // Get current feature state
+  const featureData = getFeature(feature);
+  if (!featureData) {
+    console.log(chalk.red(`✗ Feature not found: ${feature}`));
+    console.log(chalk.yellow(`  Run: morph-spec state set ${feature} phase proposal`));
+    process.exit(1);
+  }
+
+  const currentPhase = featureData.phase;
+  const currentPhaseDef = PHASES[currentPhase];
+
+  console.log(chalk.gray('Feature:'), feature);
+  console.log(chalk.gray('Current Phase:'), currentPhaseDef?.name || currentPhase);
+  console.log(chalk.gray('Workflow:'), featureData.workflow || 'auto');
+
+  // Determine next phase
+  const nextPhase = getNextPhase(currentPhase, featureData, options.skipOptional);
+
+  if (!nextPhase) {
+    console.log(chalk.green('\n✓ Feature is at the final phase!'));
+    if (currentPhase === 'implement' || currentPhase === 'sync') {
+      console.log(chalk.green('  Consider running: morph-spec generate recap ' + feature));
+    }
+    return;
+  }
+
+  const nextPhaseDef = PHASES[nextPhase];
+  console.log(chalk.gray('Next Phase:'), nextPhaseDef.name);
+
+  // Validate that current phase requirements are met before advancing
+  const validation = validatePhase(feature, nextPhase);
+
+  if (!validation.valid) {
+    console.log(chalk.red('\n✗ Cannot advance — missing requirements:'));
+    validation.missingOutputs.forEach(output => {
+      console.log(chalk.red(`  - ${output}`));
+    });
+    console.log(chalk.yellow(`\n  Complete these before advancing to ${nextPhaseDef.name}`));
+    process.exit(1);
+  }
+
+  if (validation.stateWarning) {
+    console.log(chalk.yellow(`\n⚠️  ${validation.stateWarning}`));
+  }
+
+  // Advance the phase
+  const state = loadState();
+  state.features[feature].phase = nextPhase;
+  state.features[feature].updatedAt = new Date().toISOString();
+  saveState(state);
+
+  console.log(chalk.green(`\n✓ Advanced to ${nextPhaseDef.name}`));
+
+  // Show what's needed in the new phase
+  console.log(chalk.cyan('\n📋 Phase requirements:'));
+  console.log(chalk.gray(`   ${nextPhaseDef.description}`));
+
+  if (nextPhaseDef.requiredOutputs?.length > 0) {
+    console.log(chalk.cyan('\n   Required outputs:'));
+    nextPhaseDef.requiredOutputs.forEach(output => {
+      const exists = validation.phase ? true : false; // Already validated
+      console.log(chalk.gray(`   ✓ ${output} (exists)`));
+    });
+  }
+
+  // Show phase-specific guidance
+  const guidance = getPhaseGuidance(nextPhase, feature);
+  if (guidance) {
+    console.log(chalk.cyan('\n   Next steps:'));
+    guidance.forEach(step => console.log(chalk.white(`   → ${step}`)));
+  }
+
+  console.log('');
+}
+
+/**
+ * Get guidance for what to do in a phase
+ */
+function getPhaseGuidance(phase, feature) {
+  const guides = {
+    'setup': [
+      `Resume spec pipeline: /morph-proposal ${feature}`,
+      'Auto-continues from setup phase'
+    ],
+    'uiux': [
+      `Resume spec pipeline: /morph-proposal ${feature}`,
+      'Provide layout references and preferences',
+      'Review wireframes before proceeding'
+    ],
+    'design': [
+      `Resume spec pipeline: /morph-proposal ${feature}`,
+      'Review DECISION POINTS carefully',
+      'Approve spec.md and contracts.cs'
+    ],
+    'clarify': [
+      `Resume spec pipeline: /morph-proposal ${feature}`,
+      'Resolve edge cases and unknowns'
+    ],
+    'tasks': [
+      `Resume spec pipeline: /morph-proposal ${feature}`,
+      'Review task order and dependencies',
+      'Approve task list before implementing'
+    ],
+    'implement': [
+      `Start implementing: /morph-apply ${feature}`,
+      'Complete tasks one by one with: morph-spec task done',
+      'Validators run automatically on task completion'
+    ],
+    'sync': [
+      'Review decisions.md for standards to promote',
+      `Sync: morph-spec sync --path .morph/project/outputs/${feature}/decisions.md`
+    ]
+  };
+
+  return guides[phase] || null;
+}