@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

package/src/commands/project/revert.js

@@ -0,0 +1,173 @@
+/**
+ * MORPH-SPEC Revert Command
+ *
+ * Revert a feature to a previous phase, optionally deleting later-phase outputs.
+ *
+ * Usage:
+ *   morph-spec revert <feature-name> --to <phase>
+ *   morph-spec revert <feature-name> --to design
+ *   morph-spec revert <feature-name> --to design --delete-outputs
+ */
+
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+import { loadState, saveState, getFeature } from '../../core/state/state-manager.js';
+
+/**
+ * Phase order for revert logic
+ */
+const PHASE_ORDER = [
+  { key: 'proposal', order: 0, outputs: ['proposal.md'] },
+  { key: 'setup', order: 1, outputs: [] },
+  { key: 'uiux', order: 2, outputs: ['ui-design-system.md', 'ui-mockups.md', 'ui-components.md', 'ui-flows.md'] },
+  { key: 'design', order: 3, outputs: ['spec.md', 'schema-analysis.md', 'contracts.cs', 'decisions.md'] },
+  { key: 'clarify', order: 4, outputs: ['clarifications.md'] },
+  { key: 'tasks', order: 5, outputs: ['tasks.md', 'tasks.json'] },
+  { key: 'implement', order: 6, outputs: ['recap.md'] },
+  { key: 'sync', order: 7, outputs: [] }
+];
+
+/**
+ * Get outputs that would be affected by reverting to a phase
+ */
+function getAffectedOutputs(targetPhase) {
+  const targetOrder = PHASE_ORDER.find(p => p.key === targetPhase)?.order ?? -1;
+  const affected = [];
+
+  for (const phase of PHASE_ORDER) {
+    if (phase.order > targetOrder) {
+      affected.push(...phase.outputs.map(o => ({ phase: phase.key, file: o })));
+    }
+  }
+
+  return affected;
+}
+
+/**
+ * Main revert command
+ */
+export async function revertCommand(featureName, options = {}) {
+  if (!featureName) {
+    console.error(chalk.red('Error: Feature name required'));
+    console.error(chalk.gray('Usage: morph-spec revert <feature-name> --to <phase>'));
+    process.exit(1);
+  }
+
+  const targetPhase = options.to;
+  if (!targetPhase) {
+    console.error(chalk.red('Error: Target phase required (--to <phase>)'));
+    console.error(chalk.gray(`Valid phases: ${PHASE_ORDER.map(p => p.key).join(', ')}`));
+    process.exit(1);
+  }
+
+  const targetDef = PHASE_ORDER.find(p => p.key === targetPhase);
+  if (!targetDef) {
+    console.error(chalk.red(`Error: Unknown phase: ${targetPhase}`));
+    console.error(chalk.gray(`Valid phases: ${PHASE_ORDER.map(p => p.key).join(', ')}`));
+    process.exit(1);
+  }
+
+  const feature = getFeature(featureName);
+  if (!feature) {
+    console.error(chalk.red(`Error: Feature '${featureName}' not found`));
+    process.exit(1);
+  }
+
+  const currentDef = PHASE_ORDER.find(p => p.key === feature.phase);
+  if (currentDef && targetDef.order >= currentDef.order) {
+    console.error(chalk.red(`Error: Cannot revert forward. Current phase: ${feature.phase}, target: ${targetPhase}`));
+    process.exit(1);
+  }
+
+  // Get affected outputs
+  const affected = getAffectedOutputs(targetPhase);
+  const outputDir = path.join(process.cwd(), '.morph/features', featureName);
+  const existingAffected = affected.filter(a =>
+    fs.existsSync(path.join(outputDir, a.file))
+  );
+
+  // Show what will happen
+  console.log(chalk.cyan('\n┌────────────────────────────────────────────────────────────┐'));
+  console.log(chalk.cyan('│                   MORPH-SPEC REVERT                        │'));
+  console.log(chalk.cyan('└────────────────────────────────────────────────────────────┘\n'));
+
+  console.log(chalk.white.bold(`Feature: ${featureName}`));
+  console.log(chalk.gray(`Current phase: ${feature.phase} → Reverting to: ${targetPhase}\n`));
+
+  if (existingAffected.length > 0) {
+    if (options.deleteOutputs) {
+      console.log(chalk.yellow('The following files will be DELETED:'));
+    } else {
+      console.log(chalk.yellow('The following outputs will be marked as draft (files preserved):'));
+    }
+    for (const item of existingAffected) {
+      console.log(chalk.gray(`  - ${item.file} (from ${item.phase} phase)`));
+    }
+    console.log('');
+  }
+
+  // Update state
+  const state = loadState();
+  const stateFeature = state.features[featureName];
+
+  // Revert phase
+  stateFeature.phase = targetPhase;
+  stateFeature.updatedAt = new Date().toISOString();
+
+  // Mark affected outputs as not created in state
+  const outputKeyMap = {
+    'proposal.md': 'proposal',
+    'spec.md': 'spec',
+    'schema-analysis.md': 'schemaAnalysis',
+    'contracts.cs': 'contracts',
+    'decisions.md': 'decisions',
+    'clarifications.md': 'clarifications',
+    'tasks.md': 'tasks',
+    'tasks.json': 'tasks',
+    'ui-design-system.md': 'uiDesignSystem',
+    'ui-mockups.md': 'uiMockups',
+    'ui-components.md': 'uiComponents',
+    'ui-flows.md': 'uiFlows',
+    'recap.md': 'recap'
+  };
+
+  for (const item of affected) {
+    const key = outputKeyMap[item.file];
+    if (key && stateFeature.outputs[key]) {
+      stateFeature.outputs[key].created = false;
+    }
+  }
+
+  // Reset approval gates for later phases
+  for (const phase of PHASE_ORDER) {
+    if (phase.order > targetDef.order && stateFeature.approvalGates?.[phase.key]) {
+      stateFeature.approvalGates[phase.key].approved = false;
+      stateFeature.approvalGates[phase.key].timestamp = null;
+      stateFeature.approvalGates[phase.key].approvedBy = null;
+    }
+  }
+
+  // Reset tasks if reverting before tasks phase
+  if (targetDef.order < 5) {
+    stateFeature.tasks = { total: 0, completed: 0, inProgress: 0, pending: 0 };
+  }
+
+  saveState(state);
+
+  // Delete files if requested
+  if (options.deleteOutputs && existingAffected.length > 0) {
+    for (const item of existingAffected) {
+      const filePath = path.join(outputDir, item.file);
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+      }
+    }
+    console.log(chalk.yellow(`Deleted ${existingAffected.length} file(s).`));
+  }
+
+  console.log(chalk.green(`✓ Feature '${featureName}' reverted to phase: ${targetPhase}`));
+  console.log(chalk.gray(`  State updated. Run 'morph-spec status ${featureName}' to see current status.\n`));
+}
+
+export default revertCommand;

package/src/commands/project/standards.js

@@ -0,0 +1,80 @@
+/**
+ * Standards CLI Commands
+ *
+ * Provides browsable access to the framework standards registry.
+ * Usage:
+ *   morph-spec standards --list
+ *   morph-spec standards --search <query>
+ *   morph-spec standards --show <id>
+ *   morph-spec standards --category <cat>
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+import { logger } from '../../utils/logger.js';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const REGISTRY_PATH = join(__dirname, '..', '..', '..', 'framework', 'standards', 'STANDARDS.json');
+
+function loadRegistry() {
+  return JSON.parse(readFileSync(REGISTRY_PATH, 'utf8')).standards;
+}
+
+/**
+ * List all standards, optionally filtered by category.
+ * @param {{ json?: boolean, category?: string }} opts
+ * @returns {Promise<Array>}
+ */
+export async function listStandards({ json, category } = {}) {
+  let standards = loadRegistry();
+  if (category) {
+    standards = standards.filter(s => s.category === category);
+  }
+  if (json) return standards;
+  standards.forEach(s =>
+    logger.info(`${s.id.padEnd(55)} ${s.category}`)
+  );
+  return standards;
+}
+
+/**
+ * Search standards by query string (matches id, name, or tags).
+ * @param {string} query
+ * @param {{ json?: boolean }} opts
+ * @returns {Promise<Array>}
+ */
+export async function searchStandards(query, { json } = {}) {
+  const q = query.toLowerCase();
+  const results = loadRegistry().filter(s =>
+    s.name.toLowerCase().includes(q) ||
+    s.id.toLowerCase().includes(q) ||
+    s.tags.some(t => t.toLowerCase().includes(q))
+  );
+  if (json) return results;
+  if (results.length === 0) {
+    logger.warn(`No standards found matching "${query}"`);
+  } else {
+    results.forEach(s => logger.info(`${s.id}: ${s.name}  [${s.category}]`));
+  }
+  return results;
+}
+
+/**
+ * Show the full content of a standard by its id.
+ * @param {string} id
+ * @returns {Promise<string|null>}
+ */
+export async function showStandard(id) {
+  const standard = loadRegistry().find(s => s.id === id);
+  if (!standard) {
+    logger.error(`Standard '${id}' not found. Use --list to see available standards.`);
+    return null;
+  }
+  const content = readFileSync(
+    join(__dirname, '..', '..', '..', 'framework', 'standards', standard.path),
+    'utf8'
+  );
+  logger.info(content);
+  return content;
+}

package/src/commands/project/status.js

@@ -0,0 +1,376 @@
+/**
+ * MORPH-SPEC Feature Status Command
+ *
+ * Displays a comprehensive dashboard showing feature progress, phase status,
+ * outputs, tasks, approvals, and next steps.
+ *
+ * Usage:
+ *   morph-spec status <feature-name>
+ *   morph-spec status <feature-name> --json
+ *
+ * Example:
+ *   morph-spec status user-portal
+ */
+
+import chalk from 'chalk';
+import { loadState, getFeature, derivePhase, deriveOutputs } from '../../core/state/state-manager.js';
+import { PHASES } from '../state/validate-phase.js';
+
+/**
+ * Phase symbols for visual representation
+ */
+const PHASE_SYMBOLS = {
+  completed: '✅',
+  current: '⏸️',
+  pending: '⬜',
+  skipped: '⊘'
+};
+
+/**
+ * Phase definitions with order
+ */
+const PHASE_ORDER = [
+  { key: 'proposal', name: 'FASE 0: PROPOSAL', order: 0 },
+  { key: 'setup', name: 'FASE 1: SETUP', order: 1 },
+  { key: 'uiux', name: 'FASE 1.5: UI/UX', order: 2, optional: true },
+  { key: 'design', name: 'FASE 2: DESIGN', order: 3 },
+  { key: 'clarify', name: 'FASE 3: CLARIFY', order: 4 },
+  { key: 'tasks', name: 'FASE 4: TASKS', order: 5 },
+  { key: 'implement', name: 'FASE 5: IMPLEMENT', order: 6 },
+  { key: 'sync', name: 'FASE 6: SYNC', order: 7, optional: true }
+];
+
+/**
+ * Calculate phase status (completed, current, pending, skipped)
+ */
+function getPhaseStatus(phaseKey, currentPhase, feature) {
+  const phase = PHASE_ORDER.find(p => p.key === phaseKey);
+  const current = PHASE_ORDER.find(p => p.key === currentPhase);
+
+  if (!phase || !current) return 'pending';
+
+  // Check if phase was skipped (optional phases)
+  if (phase.optional && phase.order < current.order) {
+    // Check if any outputs were created for this phase
+    const hasOutputs = checkPhaseOutputs(phaseKey, feature);
+    if (!hasOutputs) return 'skipped';
+  }
+
+  if (phase.order < current.order) return 'completed';
+  if (phase.order === current.order) return 'current';
+  return 'pending';
+}
+
+/**
+ * Check if phase has any outputs created
+ */
+function checkPhaseOutputs(phaseKey, feature) {
+  const phaseOutputMap = {
+    proposal: ['proposal'],
+    uiux: ['uiDesignSystem', 'uiMockups', 'uiComponents', 'uiFlows'],
+    design: ['spec', 'contracts', 'schemaAnalysis', 'decisions'],
+    clarify: ['clarifications'],
+    tasks: ['tasks']
+  };
+
+  const outputs = phaseOutputMap[phaseKey] || [];
+  return outputs.some(output => feature.outputs[output]?.created);
+}
+
+/**
+ * Format phase display with symbol and status
+ */
+function formatPhase(phaseKey, currentPhase, feature, options = {}) {
+  const phase = PHASE_ORDER.find(p => p.key === phaseKey);
+  const status = getPhaseStatus(phaseKey, currentPhase, feature);
+  const symbol = PHASE_SYMBOLS[status];
+
+  let display = `${symbol} ${phase.name}`;
+
+  if (phase.optional) {
+    display += ` ${chalk.gray('(optional)')}`;
+  }
+
+  if (status === 'current') {
+    display = chalk.cyan(display) + chalk.cyan(' ← CURRENT');
+  } else if (status === 'completed') {
+    display = chalk.green(display);
+  } else if (status === 'skipped') {
+    display = chalk.gray(display + ' (skipped)');
+  } else {
+    display = chalk.gray(display);
+  }
+
+  // Add output files if verbose
+  if (options.verbose && status !== 'pending' && status !== 'skipped') {
+    const phaseOutputMap = {
+      proposal: ['proposal'],
+      uiux: ['uiDesignSystem', 'uiMockups', 'uiComponents', 'uiFlows'],
+      design: ['spec', 'contracts', 'schemaAnalysis', 'decisions'],
+      clarify: ['clarifications'],
+      tasks: ['tasks'],
+      implement: ['recap']
+    };
+
+    const outputs = phaseOutputMap[phaseKey] || [];
+    const created = outputs.filter(o => feature.outputs[o]?.created);
+    if (created.length > 0) {
+      display += chalk.gray(`\n     Files: ${created.length}/${outputs.length}`);
+    }
+  }
+
+  return display;
+}
+
+/**
+ * Calculate completion percentage
+ */
+function calculateCompletionPercentage(feature) {
+  const totalPhases = PHASE_ORDER.filter(p => !p.optional).length; // 6 required phases
+  const completedPhases = PHASE_ORDER.filter(p => {
+    if (p.optional) return false;
+    const status = getPhaseStatus(p.key, feature.phase, feature);
+    return status === 'completed';
+  }).length;
+
+  return Math.round((completedPhases / totalPhases) * 100);
+}
+
+/**
+ * Get next steps based on current phase
+ */
+function getNextSteps(feature) {
+  const steps = [];
+
+  // Check for pending approvals relevant to current phase
+  const phaseApprovalMap = {
+    proposal: 'proposal',
+    setup: 'proposal',
+    uiux: 'uiux',
+    design: 'design',
+    clarify: 'design',
+    tasks: 'tasks',
+    implement: 'tasks'
+  };
+
+  const relevantGate = phaseApprovalMap[feature.phase];
+  const approvalGates = feature.approvalGates || {};
+
+  if (relevantGate && approvalGates[relevantGate] && !approvalGates[relevantGate].approved) {
+    steps.push({
+      type: 'approval',
+      message: `Approve ${relevantGate} to advance`,
+      command: `morph-spec approve ${feature.name || 'feature'} ${relevantGate}`
+    });
+  }
+
+  // Check for missing outputs in current phase
+  const phaseOutputMap = {
+    proposal: ['proposal'],
+    design: ['spec', 'contracts'],
+    clarify: ['clarifications'],
+    tasks: ['tasks'],
+    implement: ['recap']
+  };
+
+  const requiredOutputs = phaseOutputMap[feature.phase] || [];
+  const missingOutputs = requiredOutputs.filter(o => !feature.outputs[o]?.created);
+
+  if (missingOutputs.length > 0) {
+    steps.push({
+      type: 'output',
+      message: `Create missing outputs: ${missingOutputs.join(', ')}`,
+      command: null
+    });
+  }
+
+  // Suggest next phase if current is complete
+  const hasApprovalPending = relevantGate && approvalGates[relevantGate] && !approvalGates[relevantGate].approved;
+  if (missingOutputs.length === 0 && !hasApprovalPending) {
+    const currentPhaseIndex = PHASE_ORDER.findIndex(p => p.key === feature.phase);
+    if (currentPhaseIndex >= 0 && currentPhaseIndex < PHASE_ORDER.length - 1) {
+      const nextPhase = PHASE_ORDER[currentPhaseIndex + 1];
+      steps.push({
+        type: 'advance',
+        message: `Advance to ${nextPhase.name}`,
+        command: `morph-spec phase advance ${feature.name || 'feature'}`
+      });
+    } else if (currentPhaseIndex === PHASE_ORDER.length - 1) {
+      steps.push({
+        type: 'complete',
+        message: 'Feature complete! Consider archiving.',
+        command: null
+      });
+    }
+  }
+
+  return steps;
+}
+
+/**
+ * Estimate remaining time based on tasks
+ */
+function estimateRemainingTime(feature) {
+  if (!feature.tasks || feature.tasks.total === 0) {
+    return 'Not estimated';
+  }
+
+  const remaining = feature.tasks.total - feature.tasks.completed;
+  const avgHoursPerTask = 2; // Configurable estimate
+  const hours = remaining * avgHoursPerTask;
+
+  if (hours < 1) return '< 1 hour';
+  if (hours === 1) return '1 hour';
+  if (hours < 8) return `${hours} hours`;
+  const days = Math.ceil(hours / 8);
+  return `~${days} day${days > 1 ? 's' : ''} (${hours}h)`;
+}
+
+/**
+ * Main status command
+ */
+export async function statusCommand(featureName, options = {}) {
+  if (!featureName) {
+    console.error(chalk.red('✗ Error: Feature name required'));
+    console.error(chalk.gray('Usage: morph-spec status <feature-name>'));
+    process.exit(1);
+  }
+
+  const feature = getFeature(featureName);
+  if (!feature) {
+    console.error(chalk.red(`✗ Error: Feature '${featureName}' not found`));
+    console.error(chalk.gray(`Run 'morph-spec state get ${featureName}' to check if feature exists`));
+    process.exit(1);
+  }
+
+  // Derive phase and outputs from filesystem if not stored in state (v5.0.0+)
+  const { join } = await import('path');
+  const featurePath = join(process.cwd(), '.morph', 'features', featureName);
+  if (!feature.phase) {
+    feature.phase = derivePhase(featurePath);
+  }
+  if (!feature.outputs) {
+    feature.outputs = deriveOutputs(featureName, process.cwd());
+  }
+
+  // JSON output mode
+  if (options.json) {
+    const status = {
+      feature: featureName,
+      phase: feature.phase,
+      status: feature.status,
+      workflow: feature.workflow,
+      completion: calculateCompletionPercentage(feature),
+      phases: PHASE_ORDER.map(p => ({
+        key: p.key,
+        name: p.name,
+        status: getPhaseStatus(p.key, feature.phase, feature),
+        optional: p.optional || false
+      })),
+      outputs: Object.entries(feature.outputs).map(([key, output]) => ({
+        type: key,
+        created: output.created,
+        path: output.path
+      })),
+      tasks: feature.tasks || { total: 0, completed: 0, inProgress: 0, pending: 0 },
+      approvals: feature.approvalGates || {},
+      nextSteps: getNextSteps(feature),
+      estimatedTimeRemaining: estimateRemainingTime(feature)
+    };
+
+    console.log(JSON.stringify(status, null, 2));
+    return;
+  }
+
+  // Visual dashboard output
+  console.log(chalk.cyan('\n┌────────────────────────────────────────────────────────────┐'));
+  console.log(chalk.cyan('│                   MORPH-SPEC STATUS                       │'));
+  console.log(chalk.cyan('└────────────────────────────────────────────────────────────┘\n'));
+
+  // Feature info
+  console.log(chalk.white.bold(`Feature: ${featureName}`));
+  console.log(chalk.gray(`Status: ${feature.status || 'unknown'}`));
+  console.log(chalk.gray(`Workflow: ${feature.workflow || 'auto'}`));
+  console.log(chalk.gray(`Completion: ${calculateCompletionPercentage(feature)}%`));
+  console.log('');
+
+  // Phase progression
+  console.log(chalk.white.bold('Phases:'));
+  console.log(chalk.cyan('├─────────────────────────────────────────────────────────────┤'));
+  PHASE_ORDER.forEach(phase => {
+    console.log(`│ ${formatPhase(phase.key, feature.phase, feature, options)}`);
+  });
+  console.log(chalk.cyan('└─────────────────────────────────────────────────────────────┘'));
+  console.log('');
+
+  // Outputs summary
+  const totalOutputs = Object.keys(feature.outputs).length;
+  const createdOutputs = Object.values(feature.outputs).filter(o => o.created).length;
+  console.log(chalk.white.bold(`Outputs: ${createdOutputs}/${totalOutputs} complete`));
+
+  if (options.verbose) {
+    console.log(chalk.gray('Output files:'));
+    Object.entries(feature.outputs).forEach(([key, output]) => {
+      const symbol = output.created ? '✅' : '⬜';
+      const display = output.created ? chalk.green(key) : chalk.gray(key);
+      console.log(`  ${symbol} ${display}`);
+    });
+  }
+  console.log('');
+
+  // Tasks progress
+  if (feature.tasks && feature.tasks.total > 0) {
+    console.log(chalk.white.bold('Tasks Progress:'));
+    const { total, completed, inProgress, pending } = feature.tasks;
+    const percentage = total > 0 ? Math.round((completed / total) * 100) : 0;
+
+    console.log(`  Total: ${total}`);
+    console.log(chalk.green(`  ✓ Completed: ${completed} (${percentage}%)`));
+    if (inProgress > 0) console.log(chalk.cyan(`  ▶ In Progress: ${inProgress}`));
+    if (pending > 0) console.log(chalk.gray(`  ⬜ Pending: ${pending}`));
+    console.log(`  Estimated time remaining: ${estimateRemainingTime(feature)}`);
+    console.log('');
+  }
+
+  // Approval gates
+  if (feature.approvalGates) {
+    const gates = Object.entries(feature.approvalGates);
+    const approved = gates.filter(([_, g]) => g.approved).length;
+    console.log(chalk.white.bold(`Approval Gates: ${approved}/${gates.length} approved`));
+
+    if (options.verbose) {
+      gates.forEach(([gate, info]) => {
+        const symbol = info.approved ? '✅' : '⬜';
+        const display = info.approved ? chalk.green(gate) : chalk.gray(gate);
+        let extra = '';
+        if (info.approved && info.approvedBy) {
+          extra = chalk.gray(` (by ${info.approvedBy})`);
+        }
+        console.log(`  ${symbol} ${display}${extra}`);
+      });
+    }
+    console.log('');
+  }
+
+  // Next steps
+  const nextSteps = getNextSteps(feature);
+  if (nextSteps.length > 0) {
+    console.log(chalk.white.bold('Next Steps:'));
+    nextSteps.forEach((step, index) => {
+      console.log(chalk.yellow(`  ${index + 1}. ${step.message}`));
+      if (step.command) {
+        console.log(chalk.gray(`     → ${step.command}`));
+      }
+    });
+    console.log('');
+  } else {
+    console.log(chalk.green('✓ All tasks complete!\n'));
+  }
+
+  // Footer
+  console.log(chalk.gray('─'.repeat(60)));
+  console.log(chalk.gray('Run with --verbose for detailed output'));
+  console.log(chalk.gray('Run with --json for JSON output\n'));
+}
+
+export default statusCommand;

package/src/commands/project/update-agents.js

@@ -0,0 +1,23 @@
+/**
+ * update-agents command
+ *
+ * Refreshes .claude/agents/ with the latest tier-1 and tier-2 MORPH agents
+ * from the framework. Useful after upgrading morph-spec to pick up new or
+ * updated agent definitions without re-running full init.
+ */
+
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { installAgents } from '../../utils/agents-installer.js';
+import { logger } from '../../utils/logger.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FRAMEWORK_DIR = join(__dirname, '..', '..', '..', 'framework');
+
+export async function updateAgentsCommand(args, options) {
+  const projectDir = process.cwd();
+
+  logger.info('Updating native subagents in .claude/agents/...');
+  await installAgents(projectDir, FRAMEWORK_DIR);
+  logger.success('Native subagents updated. Claude Code will discover them on next session start.');
+}