@polymorphism-tech/morph-spec 2.3.0 → 3.0.0

package/package.json

@@ -1,80 +1,80 @@
-{
-  "name": "@polymorphism-tech/morph-spec",
-  "version": "2.3.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": "3.0.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/src/commands/advance-phase.js

@@ -0,0 +1,266 @@
+/**
+ * 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';
+import { detectDesignSystem, hasUIAgentsActive } from '../lib/design-system-detector.js';
+import { validateSpec } from '../lib/spec-validator.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}`));
+  }
+
+  // Gate: Validate spec.md and contracts.cs when advancing from design phase
+  if (currentPhase === 'design' && (nextPhase === 'clarify' || nextPhase === 'tasks')) {
+    const specValidation = await validateSpec('.', feature);
+
+    if (specValidation.errors > 0) {
+      console.log(chalk.red('\n✗ Spec validation failed — fix errors before advancing:'));
+      specValidation.issues.filter(i => i.level === 'error').forEach(issue => {
+        console.log(chalk.red(`  - ${issue.message}`));
+        console.log(chalk.yellow(`    → ${issue.solution}`));
+      });
+      console.log('');
+      process.exit(1);
+    }
+
+    if (specValidation.warnings > 0 && !options.skipWarnings) {
+      console.log(chalk.yellow('\n⚠️  Spec validation warnings:'));
+      specValidation.issues.filter(i => i.level === 'warning').forEach(issue => {
+        console.log(chalk.yellow(`  - ${issue.message}`));
+      });
+      console.log(chalk.gray('\n  (Use --skip-warnings to ignore warnings)\n'));
+    }
+  }
+
+  // Gate: Check design system when advancing to implement with UI agents
+  if (nextPhase === 'implement') {
+    const gateResult = designSystemGate(feature);
+
+    if (gateResult.blocked) {
+      console.log(chalk.red(`\n✗ ${gateResult.message}`));
+      console.log('');
+      gateResult.solution.forEach(line => {
+        if (line === '') {
+          console.log('');
+        } else {
+          console.log(chalk.yellow(`  ${line}`));
+        }
+      });
+      console.log('');
+      process.exit(1);
+    }
+  }
+
+  // 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;
+}
+
+/**
+ * Gate: Check design system exists when advancing to implement with UI agents
+ * @param {string} feature - Feature name
+ * @param {string} projectPath - Project root path
+ * @returns {Object} { blocked: boolean, message?: string, solution?: string[] }
+ */
+function designSystemGate(feature, projectPath = '.') {
+  // Check if UI agents are active
+  const hasUIAgents = hasUIAgentsActive(projectPath, feature);
+
+  if (!hasUIAgents) {
+    return { blocked: false }; // No UI agents, gate doesn't apply
+  }
+
+  // Check if design system exists
+  const dsDetection = detectDesignSystem(projectPath, feature);
+
+  if (dsDetection.hasDesignSystem) {
+    return { blocked: false }; // Design system exists, gate passed
+  }
+
+  // Block advancement - no design system found with UI agents active
+  return {
+    blocked: true,
+    message: 'Cannot advance to implementation — UI agents are active but no design system found',
+    solution: [
+      'Design system is required when UI agents (blazor-builder, ui-designer, css-specialist) are active',
+      '',
+      'Create a design system with one of these options:',
+      '  1. Project-level: .morph/project/design-system.md (shared across features)',
+      `  2. Feature-level: .morph/project/outputs/${feature}/ui-design-system.md (feature-specific)`,
+      '  3. Auto-generate: morph-spec generate design-system (scans existing CSS)',
+      '',
+      'Or remove UI agents if they are not needed:',
+      `  morph-spec state remove-agent ${feature} blazor-builder`
+    ]
+  };
+}

package/src/commands/analyze-blazor-concurrency.js

@@ -0,0 +1,193 @@
+/**
+ * analyze-blazor-concurrency command
+ *
+ * Analyzes Blazor Server code for DbContext concurrency issues.
+ *
+ * Usage:
+ *   morph-spec analyze-blazor-concurrency [path]
+ *   morph-spec analyze-blazor-concurrency src/Services --verbose
+ */
+
+import { glob } from 'glob';
+import { readFileSync, existsSync, statSync } from 'fs';
+import { join, resolve } from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+
+import {
+  analyzeConcurrency,
+  countIssues,
+} from '../lib/blazor-concurrency-analyzer.js';
+
+/**
+ * Main command handler for analyze-blazor-concurrency.
+ *
+ * @param {string} [targetPath] - Path to analyze (file or directory)
+ * @param {Object} options - Command options
+ * @param {boolean} [options.verbose] - Show detailed output
+ */
+export async function analyzeBlazorConcurrencyCommand(targetPath, options = {}) {
+  const { verbose = false } = options;
+
+  console.log('');
+  console.log(
+    chalk.cyan('\uD83D\uDD0D Analisando concorrencia DbContext em Blazor Server...')
+  );
+  console.log('');
+
+  // Determine target path
+  const basePath = targetPath ? resolve(targetPath) : process.cwd();
+
+  if (!existsSync(basePath)) {
+    console.log(chalk.red(`\u274C Path not found: ${basePath}`));
+    process.exit(1);
+  }
+
+  const spinner = ora('Scanning for C# files...').start();
+
+  let files = [];
+
+  try {
+    const stats = statSync(basePath);
+
+    if (stats.isFile()) {
+      if (basePath.endsWith('.cs')) {
+        files = [basePath];
+      } else {
+        spinner.fail('File must be .cs');
+        process.exit(1);
+      }
+    } else {
+      // Find all C# files (services, repositories, handlers)
+      const pattern = join(basePath, '**/*.cs');
+      files = await glob(pattern, {
+        ignore: [
+          '**/node_modules/**',
+          '**/bin/**',
+          '**/obj/**',
+          '**/Migrations/**',
+        ],
+        windowsPathsNoEscape: true,
+      });
+    }
+
+    spinner.succeed(`Found ${files.length} C# file(s)`);
+  } catch (error) {
+    spinner.fail(`Error scanning files: ${error.message}`);
+    process.exit(1);
+  }
+
+  if (files.length === 0) {
+    console.log(chalk.yellow('\n\u26A0\uFE0F No C# files found to analyze'));
+    return;
+  }
+
+  // Analyze each file
+  const allIssues = [];
+  const fileResults = [];
+
+  for (const file of files) {
+    try {
+      const content = readFileSync(file, 'utf-8');
+      const issues = analyzeConcurrency(content, file);
+
+      if (issues.length > 0) {
+        allIssues.push(...issues);
+        fileResults.push({ file, issues });
+      }
+    } catch (error) {
+      if (verbose) {
+        console.log(chalk.red(`\u274C Error reading ${file}: ${error.message}`));
+      }
+    }
+  }
+
+  // Output results
+  console.log('');
+
+  if (allIssues.length === 0) {
+    console.log(
+      chalk.green(
+        '\u2705 Nenhum problema de concorrencia detectado!'
+      )
+    );
+    console.log(
+      chalk.gray(
+        '   Dica: Certifique-se de usar IDbContextFactory para operacoes background.'
+      )
+    );
+    console.log('');
+    return;
+  }
+
+  // Display issues
+  if (verbose) {
+    fileResults.forEach(({ file, issues }) => {
+      console.log(chalk.white.bold(`\n${file}`));
+      console.log(chalk.gray('-'.repeat(60)));
+
+      issues.forEach((issue) => {
+        const icon =
+          issue.type === 'error'
+            ? '\u274C'
+            : issue.type === 'warning'
+            ? '\u26A0\uFE0F'
+            : '\u2139\uFE0F';
+
+        console.log(`${icon} ${issue.message}`);
+        if (issue.suggestion) {
+          console.log(chalk.gray(`   \u2192 ${issue.suggestion}`));
+        }
+        if (issue.line) {
+          console.log(chalk.dim(`   Linha: ${issue.line}`));
+        }
+        if (issue.code) {
+          console.log(chalk.dim(`   Codigo: ${issue.code}`));
+        }
+        console.log('');
+      });
+    });
+  } else {
+    allIssues.forEach((issue) => {
+      const icon =
+        issue.type === 'error'
+          ? '\u274C'
+          : issue.type === 'warning'
+          ? '\u26A0\uFE0F'
+          : '\u2139\uFE0F';
+
+      const location = issue.line ? `${issue.file}:${issue.line}` : issue.file;
+
+      console.log(`${icon} ${issue.message}`);
+      if (issue.suggestion) {
+        console.log(chalk.gray(`   \u2192 ${issue.suggestion}`));
+      }
+      console.log(chalk.dim(`   ${location}`));
+      console.log('');
+    });
+  }
+
+  // Summary
+  const { errors, warnings, infos } = countIssues(allIssues);
+  const summaryColor = errors > 0 ? chalk.red : chalk.yellow;
+
+  console.log(chalk.gray('-'.repeat(60)));
+  console.log(
+    summaryColor(
+      `\n${files.length} arquivo(s) analisado(s) | ${errors} erro(s) | ${warnings} warning(s) | ${infos} info(s)\n`
+    )
+  );
+
+  // Recommendation
+  if (errors > 0) {
+    console.log(
+      chalk.cyan(
+        '\uD83D\uDCD6 Consulte: framework/standards/blazor-efcore.md para padroes corretos'
+      )
+    );
+    console.log('');
+    process.exit(1);
+  }
+}
+
+export default analyzeBlazorConcurrencyCommand;