@polymorphism-tech/morph-spec 2.4.0 → 3.0.0

package/src/lib/design-system-scaffolder.js

@@ -0,0 +1,299 @@
+/**
+ * Design System Scaffolder
+ *
+ * Automatically scaffolds design system files when needed.
+ * Called internally by advance-phase.js gate and phase-uiux skill.
+ *
+ * NOT a user-facing CLI command - internal automation only.
+ *
+ * MORPH-SPEC 3.0 - Phase 3.5: Design System Enforcement
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { parseColors, parseTypography, parseSpacing } from './design-system-generator.js';
+
+/**
+ * Scaffold a design system by scanning existing CSS or using template
+ * @param {string} projectPath - Root path of the project
+ * @param {string|null} featureName - Feature name (optional, for feature-level)
+ * @param {Object} options - Scaffolding options
+ * @param {boolean} options.featureLevel - Create feature-level design system
+ * @param {boolean} options.scanExisting - Scan existing CSS files
+ * @returns {Object} { created: boolean, path: string, source: 'scanned'|'template' }
+ */
+export function scaffoldDesignSystem(projectPath, featureName = null, options = {}) {
+  const { featureLevel = false, scanExisting = true } = options;
+
+  // Determine output path
+  const outputPath = featureLevel && featureName
+    ? join(projectPath, '.morph/project/outputs', featureName, 'ui-design-system.md')
+    : join(projectPath, '.morph/project/design-system.md');
+
+  // Don't overwrite existing design system
+  if (existsSync(outputPath)) {
+    return {
+      created: false,
+      path: outputPath,
+      source: 'existing',
+      message: 'Design system already exists'
+    };
+  }
+
+  let designSystemContent;
+  let source;
+
+  // Try to scan existing CSS files for design tokens
+  if (scanExisting) {
+    const scannedTokens = scanExistingCSSForTokens(projectPath);
+
+    if (scannedTokens.hasTokens) {
+      designSystemContent = generateFromScannedTokens(scannedTokens);
+      source = 'scanned';
+    } else {
+      designSystemContent = generateFromTemplate();
+      source = 'template';
+    }
+  } else {
+    designSystemContent = generateFromTemplate();
+    source = 'template';
+  }
+
+  // Ensure directory exists
+  mkdirSync(dirname(outputPath), { recursive: true });
+
+  // Write design system
+  writeFileSync(outputPath, designSystemContent, 'utf8');
+
+  return {
+    created: true,
+    path: outputPath,
+    source,
+    message: source === 'scanned'
+      ? 'Design system created from existing CSS variables'
+      : 'Design system created from template with sensible defaults'
+  };
+}
+
+/**
+ * Scan existing CSS files for design tokens
+ * @param {string} projectPath - Root path of the project
+ * @returns {Object} { hasTokens: boolean, colors: Object, typography: Object, spacing: Object }
+ */
+function scanExistingCSSForTokens(projectPath) {
+  const result = {
+    hasTokens: false,
+    colors: { primary: {}, secondary: {}, neutral: {}, semantic: {} },
+    typography: { fontFamily: {}, fontSize: {}, fontWeight: {}, lineHeight: {} },
+    spacing: {}
+  };
+
+  // Common CSS locations to scan
+  const cssLocations = [
+    'wwwroot/css/site.css',
+    'wwwroot/css/app.css',
+    'styles/globals.css',
+    'src/styles/globals.css'
+  ];
+
+  for (const cssPath of cssLocations) {
+    const fullPath = join(projectPath, cssPath);
+    if (!existsSync(fullPath)) continue;
+
+    try {
+      const content = readFileSync(fullPath, 'utf8');
+
+      // Check if file has CSS custom properties
+      const hasCustomProps = /:root\s*\{[\s\S]*?--/.test(content);
+      if (!hasCustomProps) continue;
+
+      result.hasTokens = true;
+
+      // Extract CSS variables
+      const varRegex = /--([\w-]+)\s*:\s*([^;]+);/g;
+      let match;
+
+      while ((match = varRegex.exec(content)) !== null) {
+        const [, varName, varValue] = match;
+        const cleanValue = varValue.trim();
+
+        // Categorize by variable name
+        if (varName.includes('color') || varName.includes('primary') || varName.includes('secondary')) {
+          if (varName.includes('primary')) {
+            result.colors.primary[varName] = cleanValue;
+          } else if (varName.includes('secondary')) {
+            result.colors.secondary[varName] = cleanValue;
+          } else if (varName.includes('neutral') || varName.includes('gray')) {
+            result.colors.neutral[varName] = cleanValue;
+          } else if (varName.includes('success') || varName.includes('error') || varName.includes('warning') || varName.includes('info')) {
+            result.colors.semantic[varName] = cleanValue;
+          }
+        } else if (varName.includes('font')) {
+          if (varName.includes('family')) {
+            result.typography.fontFamily[varName] = cleanValue;
+          } else if (varName.includes('size')) {
+            result.typography.fontSize[varName] = cleanValue;
+          }
+        } else if (varName.includes('spacing') || varName.includes('gap') || varName.includes('margin') || varName.includes('padding')) {
+          result.spacing[varName] = cleanValue;
+        }
+      }
+    } catch (err) {
+      // Continue scanning other files
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Generate design system content from scanned tokens
+ * @param {Object} tokens - Scanned tokens
+ * @returns {string} Markdown content
+ */
+function generateFromScannedTokens(tokens) {
+  let md = '# Design System\n\n';
+  md += '> Auto-generated from existing CSS variables by MORPH-SPEC\n\n';
+
+  // Colors
+  if (Object.keys(tokens.colors.primary).length > 0 ||
+      Object.keys(tokens.colors.secondary).length > 0 ||
+      Object.keys(tokens.colors.neutral).length > 0 ||
+      Object.keys(tokens.colors.semantic).length > 0) {
+    md += '## Colors\n\n';
+
+    if (Object.keys(tokens.colors.primary).length > 0) {
+      md += '### Primary Colors\n\n';
+      Object.entries(tokens.colors.primary).forEach(([name, value]) => {
+        md += `- **${formatVariableName(name)}** (\`${value}\`)\n`;
+      });
+      md += '\n';
+    }
+
+    if (Object.keys(tokens.colors.secondary).length > 0) {
+      md += '### Secondary Colors\n\n';
+      Object.entries(tokens.colors.secondary).forEach(([name, value]) => {
+        md += `- **${formatVariableName(name)}** (\`${value}\`)\n`;
+      });
+      md += '\n';
+    }
+
+    if (Object.keys(tokens.colors.neutral).length > 0) {
+      md += '### Neutral Colors\n\n';
+      Object.entries(tokens.colors.neutral).forEach(([name, value]) => {
+        md += `- **${formatVariableName(name)}** (\`${value}\`)\n`;
+      });
+      md += '\n';
+    }
+
+    if (Object.keys(tokens.colors.semantic).length > 0) {
+      md += '### Semantic Colors\n\n';
+      Object.entries(tokens.colors.semantic).forEach(([name, value]) => {
+        md += `- **${formatVariableName(name)}** (\`${value}\`)\n`;
+      });
+      md += '\n';
+    }
+  }
+
+  // Typography
+  if (Object.keys(tokens.typography.fontFamily).length > 0 || Object.keys(tokens.typography.fontSize).length > 0) {
+    md += '## Typography\n\n';
+
+    Object.entries(tokens.typography.fontFamily).forEach(([name, value]) => {
+      md += `- **${formatVariableName(name)}**: ${value}\n`;
+    });
+
+    Object.entries(tokens.typography.fontSize).forEach(([name, value]) => {
+      md += `- **${formatVariableName(name)}**: ${value}\n`;
+    });
+
+    md += '\n';
+  }
+
+  // Spacing
+  if (Object.keys(tokens.spacing).length > 0) {
+    md += '## Spacing\n\n';
+
+    Object.entries(tokens.spacing).forEach(([name, value]) => {
+      md += `- **${formatVariableName(name)}**: ${value}\n`;
+    });
+
+    md += '\n';
+  }
+
+  return md;
+}
+
+/**
+ * Generate design system content from template
+ * @returns {string} Markdown content
+ */
+function generateFromTemplate() {
+  return `# Design System
+
+> Created by MORPH-SPEC with sensible defaults
+
+## Colors
+
+### Primary Colors
+- **Primary 500** (\`#007bff\`) - Main brand color
+- **Primary 600** (\`#0056b3\`) - Darker variant
+- **Primary 700** (\`#004085\`) - Darkest variant
+
+### Secondary Colors
+- **Secondary 500** (\`#6c757d\`) - Secondary color
+- **Secondary 600** (\`#545b62\`) - Darker variant
+
+### Neutral Colors
+- **Neutral 100** (\`#f8f9fa\`) - Lightest gray
+- **Neutral 200** (\`#e9ecef\`) - Light gray
+- **Neutral 500** (\`#adb5bd\`) - Medium gray
+- **Neutral 900** (\`#212529\`) - Almost black
+
+### Semantic Colors
+- **Success** (\`#28a745\`) - Success state
+- **Error** (\`#dc3545\`) - Error state
+- **Warning** (\`#ffc107\`) - Warning state
+- **Info** (\`#17a2b8\`) - Info state
+
+## Typography
+
+- **Font Family**: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif
+- **Base Size**: 16px
+- **H1**: 2.5rem
+- **H2**: 2rem
+- **H3**: 1.75rem
+- **Body**: 1rem
+- **Small**: 0.875rem
+
+## Spacing
+
+- **Spacing XS**: 0.25rem
+- **Spacing SM**: 0.5rem
+- **Spacing MD**: 1rem
+- **Spacing LG**: 1.5rem
+- **Spacing XL**: 2rem
+- **Spacing 2XL**: 3rem
+
+## Usage
+
+This design system should be used for all UI components in this project.
+
+- Use CSS variables: \`var(--color-primary-500)\`
+- Avoid hardcoded hex colors
+- Use spacing tokens for consistent layout
+- Follow typography scale for text sizes
+`;
+}
+
+/**
+ * Format CSS variable name to readable title
+ * @param {string} varName - CSS variable name (e.g., 'color-primary-500')
+ * @returns {string} Formatted name (e.g., 'Color Primary 500')
+ */
+function formatVariableName(varName) {
+  return varName
+    .split('-')
+    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(' ');
+}

package/src/lib/hook-executor.js

@@ -0,0 +1,256 @@
+/**
+ * @fileoverview Hook Executor for Claude Code Agent Teams
+ *
+ * Executes validators in response to Claude Code hook events:
+ * - TeammateIdle: When a teammate is waiting (validate their work before proceeding)
+ * - TaskCompleted: When a task is marked complete (validate deliverables)
+ *
+ * Validators can be configured to block on failure (severity: "error") or
+ * warn without blocking (severity: "warning").
+ *
+ * @module hook-executor
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import { runValidation } from './validation-runner.js';
+
+/**
+ * Load agents.json to get hook configuration
+ * @param {string} projectPath - Root path of the project
+ * @returns {Promise<Object>} Parsed agents configuration
+ */
+async function loadAgentsConfig(projectPath) {
+  const agentsPath = path.join(projectPath, 'content/.morph/config/agents.json');
+  const content = await fs.readFile(agentsPath, 'utf8');
+  return JSON.parse(content);
+}
+
+/**
+ * Load feature state to get active agents
+ * @param {string} projectPath - Root path of the project
+ * @param {string} featureName - Feature name
+ * @returns {Promise<Object|null>} Feature state or null if not found
+ */
+async function loadFeatureState(projectPath, featureName) {
+  const statePath = path.join(projectPath, '.morph/state.json');
+  try {
+    const content = await fs.readFile(statePath, 'utf8');
+    const state = JSON.parse(content);
+
+    // Handle both array and object format
+    if (Array.isArray(state.features)) {
+      return state.features.find(f => f.name === featureName);
+    } else if (state.features && typeof state.features === 'object') {
+      const feature = state.features[featureName];
+      return feature ? { name: featureName, ...feature } : null;
+    }
+  } catch (err) {
+    return null;
+  }
+
+  return null;
+}
+
+/**
+ * Get validators that should run for a given hook event
+ * @param {Object} agentsConfig - Loaded agents.json
+ * @param {string[]} activeAgentIds - Active agent IDs for the feature
+ * @param {string} hookEvent - Hook event name (e.g., "TeammateIdle", "TaskCompleted")
+ * @returns {Array} Validators to run: [{ agentId, hookBehavior, validators }]
+ */
+function getHookValidators(agentsConfig, activeAgentIds, hookEvent) {
+  const hookValidators = [];
+
+  for (const agentId of activeAgentIds) {
+    const agent = agentsConfig.agents[agentId];
+    if (!agent) continue;
+
+    // Check if this is a Tier 4 validator agent with hook configuration
+    if (agent.tier === 4 && agent.role === 'validator' && agent.relationships?.runs_in === 'hooks') {
+      const hookTriggers = agent.relationships.hook_triggers || [];
+
+      // Check if this hook event triggers this validator
+      if (hookTriggers.includes(hookEvent)) {
+        hookValidators.push({
+          agentId,
+          hookBehavior: agent.hook_behavior || {},
+          validators: agent.validators || []
+        });
+      }
+    }
+  }
+
+  return hookValidators;
+}
+
+/**
+ * Execute hook validators
+ * @param {string} projectPath - Root path of the project
+ * @param {string} featureName - Feature name
+ * @param {string} hookEvent - Hook event name
+ * @param {Object} options - Execution options
+ * @param {boolean} options.dryRun - If true, only show what would run without executing
+ * @param {boolean} options.verbose - Show detailed output
+ * @returns {Promise<Object>} Execution result: { passed, blocked, warnings, errors }
+ */
+export async function executeHook(projectPath, featureName, hookEvent, options = {}) {
+  const { dryRun = false, verbose = false } = options;
+
+  // Load configuration
+  const agentsConfig = await loadAgentsConfig(projectPath);
+  const feature = await loadFeatureState(projectPath, featureName);
+
+  if (!feature) {
+    return {
+      passed: false,
+      blocked: true,
+      errors: [`Feature "${featureName}" not found in state.json`],
+      warnings: []
+    };
+  }
+
+  // Get validators for this hook event
+  const activeAgentIds = feature.activeAgents || [];
+  const hookValidators = getHookValidators(agentsConfig, activeAgentIds, hookEvent);
+
+  if (hookValidators.length === 0) {
+    if (verbose) {
+      console.log(`ℹ️  No validators configured for hook event: ${hookEvent}`);
+    }
+    return {
+      passed: true,
+      blocked: false,
+      errors: [],
+      warnings: []
+    };
+  }
+
+  if (verbose) {
+    console.log(`\n🎯 Executing ${hookEvent} hook for feature: ${featureName}`);
+    console.log(`   Validators: ${hookValidators.map(v => v.agentId).join(', ')}\n`);
+  }
+
+  if (dryRun) {
+    console.log('🔍 DRY RUN - Would execute:');
+    hookValidators.forEach(v => {
+      console.log(`   - ${v.agentId} (severity: ${v.hookBehavior.severity || 'warning'})`);
+      if (v.hookBehavior.validates) {
+        v.hookBehavior.validates.forEach(check => {
+          console.log(`     • ${check}`);
+        });
+      }
+    });
+    return {
+      passed: true,
+      blocked: false,
+      errors: [],
+      warnings: []
+    };
+  }
+
+  // Execute validators
+  const results = {
+    passed: true,
+    blocked: false,
+    errors: [],
+    warnings: []
+  };
+
+  for (const hookValidator of hookValidators) {
+    const { agentId, hookBehavior, validators } = hookValidator;
+
+    if (verbose) {
+      console.log(`\n🔍 Running ${agentId} validators...`);
+    }
+
+    // Run all validators for this agent
+    for (const validatorId of validators) {
+      try {
+        const validationResult = await runValidation(
+          projectPath,
+          featureName,
+          [validatorId],
+          { quiet: !verbose }
+        );
+
+        if (!validationResult.passed) {
+          const severity = hookBehavior.severity || 'warning';
+          const blocksOnFail = hookBehavior.blocks_on_fail !== false; // Default true
+
+          if (severity === 'error' && blocksOnFail) {
+            results.passed = false;
+            results.blocked = true;
+            results.errors.push({
+              agentId,
+              validatorId,
+              issues: validationResult.results[validatorId]?.issues || []
+            });
+          } else {
+            results.warnings.push({
+              agentId,
+              validatorId,
+              issues: validationResult.results[validatorId]?.issues || []
+            });
+          }
+        }
+      } catch (err) {
+        results.errors.push({
+          agentId,
+          validatorId,
+          error: err.message
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Format hook execution results for display
+ * @param {Object} results - Results from executeHook
+ * @param {string} hookEvent - Hook event name
+ * @returns {string} Formatted output
+ */
+export function formatHookResults(results, hookEvent) {
+  const lines = [];
+
+  if (results.passed) {
+    lines.push(`✅ ${hookEvent} hook: All validators passed`);
+  } else {
+    lines.push(`❌ ${hookEvent} hook: Validation FAILED`);
+  }
+
+  if (results.errors.length > 0) {
+    lines.push('\n🚫 ERRORS (blocking):');
+    results.errors.forEach(error => {
+      lines.push(`   ${error.agentId} → ${error.validatorId}`);
+      if (error.error) {
+        lines.push(`      Error: ${error.error}`);
+      } else if (error.issues) {
+        error.issues.forEach(issue => {
+          lines.push(`      • ${issue.message} (${issue.file}:${issue.line})`);
+        });
+      }
+    });
+  }
+
+  if (results.warnings.length > 0) {
+    lines.push('\n⚠️  WARNINGS (non-blocking):');
+    results.warnings.forEach(warning => {
+      lines.push(`   ${warning.agentId} → ${warning.validatorId}`);
+      if (warning.issues) {
+        warning.issues.forEach(issue => {
+          lines.push(`      • ${issue.message} (${issue.file}:${issue.line})`);
+        });
+      }
+    });
+  }
+
+  if (results.blocked) {
+    lines.push('\n⛔ Hook execution BLOCKED - fix errors before proceeding');
+  }
+
+  return lines.join('\n');
+}