@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

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

@@ -1,299 +0,0 @@
-/**
- * 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

@@ -1,257 +0,0 @@
-/**
- * @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';
-import { resolveAgentsConfigPath } from './stack-resolver.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 = resolveAgentsConfigPath(projectPath);
-  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');
-}