@polymorphism-tech/morph-spec 4.21.0 → 5.0.1

package/src/commands/agents/manage-agents.js

@@ -1,352 +0,0 @@
-/**
- * manage-agents.js — CLI command handlers for agent management
- *
- * Thin wrappers around agents-manager.js core functions.
- * Each handler: parses args -> calls core -> formats output via logger.
- *
- * @module manage-agents
- */
-
-import { join, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createInterface } from 'node:readline';
-import { existsSync, readFileSync } from 'node:fs';
-import chalk from 'chalk';
-import { logger } from '../../utils/logger.js';
-import {
-  loadAgentsFile,
-  saveAgentsFile,
-  listAgents,
-  showAgent,
-  addAgent,
-  editAgent,
-  removeAgent,
-  TIER_LABELS,
-  KNOWN_PHASES,
-} from '../../lib/agents/agents-manager.js';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const AGENTS_PATH = join(__dirname, '../../../framework/agents.json');
-
-/**
- * Resolve the agents.json path.
- * Uses the canonical framework/agents.json (v4 schema).
- * If running inside a client project (not the framework repo), falls back
- * to .morph/framework/agents.json.
- */
-function getAgentsPath() {
-  // Prefer the framework source file (always v4 schema)
-  if (existsSync(AGENTS_PATH)) return AGENTS_PATH;
-  // Fallback for client projects
-  const clientPath = join(process.cwd(), '.morph', 'framework', 'agents.json');
-  if (existsSync(clientPath)) return clientPath;
-  return AGENTS_PATH;
-}
-
-// ── List ────────────────────────────────────────────────────────────────────────
-
-export async function agentListCommand(options) {
-  const agentsData = loadAgentsFile(getAgentsPath());
-  const filters = {};
-  if (options.group) filters.group = options.group;
-  if (options.tier) filters.tier = parseInt(options.tier, 10);
-
-  const result = listAgents(agentsData, filters);
-
-  if (options.json) {
-    console.log(JSON.stringify(result.agents, null, 2));
-    return;
-  }
-
-  if (result.total === 0) {
-    logger.info('No agents found matching filters.');
-    return;
-  }
-
-  logger.header(`Agents (${result.total} total)`);
-
-  // Table header
-  const header = `  ${'ID'.padEnd(28)} ${'Tier'.padEnd(6)} ${'Group'.padEnd(18)} ${'Phases'.padEnd(16)} Keywords`;
-  console.log(chalk.dim(header));
-  console.log(chalk.dim('  ' + '\u2500'.repeat(90)));
-
-  for (const a of result.agents) {
-    const tierLabel = `T${a.tier}`;
-    const group = (a.group || '\u2014').padEnd(18);
-    const phases = (a.phases || '*').padEnd(16);
-    console.log(`  ${a.id.padEnd(28)} ${tierLabel.padEnd(6)} ${group} ${phases} ${a.keywords || '\u2014'}`);
-  }
-
-  logger.blank();
-  const groups = Object.entries(result.groupCounts).map(([g, c]) => `${g}(${c})`).join(' ');
-  logger.dim(`Groups: ${groups}`);
-}
-
-// ── Show ────────────────────────────────────────────────────────────────────────
-
-export async function agentShowCommand(id, options) {
-  const agentsData = loadAgentsFile(getAgentsPath());
-  const agent = showAgent(agentsData, id);
-
-  if (!agent) {
-    const ids = Object.keys(agentsData.agents || {});
-    const similar = ids.filter(aid => levenshtein(aid, id) <= 3);
-    logger.error(`Agent '${id}' not found.`);
-    if (similar.length > 0) {
-      logger.dim(`Did you mean: ${similar.join(', ')}?`);
-    }
-    process.exitCode = 1;
-    return;
-  }
-
-  if (options.json) {
-    console.log(JSON.stringify({ [id]: agent }, null, 2));
-    return;
-  }
-
-  logger.header(`Agent: ${id}`);
-  logger.info(`Title:        ${agent.title}`);
-  logger.info(`Tier:         ${agent.tier} (${TIER_LABELS[agent.tier] || '?'})`);
-  logger.info(`Group:        ${agent.group}`);
-  logger.info(`Phases:       ${(agent.active_phases || []).join(', ')}`);
-  logger.info(`Reports to:   ${agent.reports_to}`);
-  logger.info(`Domains:      ${(agent.domains || []).join(', ') || '\u2014'}`);
-  logger.info(`Keywords:     ${(agent.keywords || []).join(', ') || '\u2014'}`);
-  logger.info(`Validators:   ${(agent.validators || []).join(', ') || '\u2014'}`);
-
-  if (agent.stacks?.length > 0) {
-    logger.info(`Stacks:       ${agent.stacks.join(', ')}`);
-  }
-
-  if (agent.standards?.length > 0) {
-    logger.blank();
-    logger.info('Standards:');
-    for (const s of agent.standards) {
-      logger.dim(`  ${s.id} (scope: ${s.scope}, priority: ${s.priority})`);
-    }
-  }
-
-  if (agent.teammate) {
-    logger.blank();
-    logger.info('Teammate:');
-    logger.dim(`  Role: ${agent.teammate.role}`);
-    logger.dim(`  Icon: ${agent.teammate.icon}`);
-    const prompt = agent.teammate.spawn_prompt || '';
-    const truncated = options.full ? prompt : (prompt.length > 200 ? prompt.slice(0, 200) + '...' : prompt);
-    logger.dim(`  Prompt: ${truncated}`);
-  } else {
-    logger.blank();
-    logger.dim('No teammate configured.');
-  }
-}
-
-// ── Add ─────────────────────────────────────────────────────────────────────────
-
-export async function agentAddCommand(id, options) {
-  const agentsData = loadAgentsFile(getAgentsPath());
-
-  let fields;
-  if (options.nonInteractive) {
-    fields = parseNonInteractiveFlags(options);
-  } else {
-    fields = await runAddWizard(id, agentsData);
-  }
-
-  const result = addAgent(agentsData, id, fields);
-
-  if (!result.success) {
-    for (const e of result.errors) logger.error(e);
-    process.exitCode = 1;
-    return;
-  }
-
-  if (result.warnings?.length > 0) {
-    for (const w of result.warnings) logger.warn(w);
-  }
-
-  saveAgentsFile(getAgentsPath(), result.data);
-  logger.success(`Created agent '${id}' in agents.json`);
-  logger.dim(`Run 'morph-spec setup-infra' to install the .claude/agents/ file`);
-}
-
-// ── Edit ────────────────────────────────────────────────────────────────────────
-
-export async function agentEditCommand(id, options) {
-  const agentsData = loadAgentsFile(getAgentsPath());
-  const changes = {};
-
-  if (options.tier) changes.tier = parseInt(options.tier, 10);
-  if (options.title) changes.title = options.title;
-  if (options.group) changes.group = options.group;
-  if (options.activePhases) changes.active_phases = options.activePhases.split(',').map(s => s.trim());
-  if (options.reportsTo) changes.reports_to = options.reportsTo;
-  if (options.keywords) changes.keywords = options.keywords.split(',').map(s => s.trim());
-  if (options.domains) changes.domains = options.domains.split(',').map(s => s.trim());
-  if (options.spawnPrompt) changes.spawn_prompt = options.spawnPrompt;
-
-  if (Object.keys(changes).length === 0) {
-    logger.error('No changes specified. Use flags like --title, --tier, --keywords, etc.');
-    process.exitCode = 1;
-    return;
-  }
-
-  const result = editAgent(agentsData, id, changes);
-
-  if (!result.success) {
-    for (const e of result.errors) logger.error(e);
-    process.exitCode = 1;
-    return;
-  }
-
-  saveAgentsFile(getAgentsPath(), result.data);
-  logger.success(`Updated agent '${id}'`);
-  for (const c of result.changes) logger.dim(`  ${c}`);
-}
-
-// ── Remove ──────────────────────────────────────────────────────────────────────
-
-export async function agentRemoveCommand(id, options) {
-  const agentsData = loadAgentsFile(getAgentsPath());
-  const agent = showAgent(agentsData, id);
-
-  if (!agent) {
-    logger.error(`Agent '${id}' not found.`);
-    process.exitCode = 1;
-    return;
-  }
-
-  // Show summary
-  logger.info(`Agent: ${id} (T${agent.tier} ${agent.group})`);
-
-  // Check for dependents
-  const dependents = Object.entries(agentsData.agents)
-    .filter(([aid, a]) => aid !== id && a.reports_to === id)
-    .map(([aid]) => aid);
-
-  if (dependents.length > 0) {
-    logger.warn(`These agents report to '${id}': ${dependents.join(', ')}`);
-  }
-
-  // Check state.json for active references (advisory)
-  checkActiveFeatures(id);
-
-  if (!options.force) {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    const answer = await new Promise(resolve => {
-      rl.question(chalk.yellow('  Remove this agent? (y/N) '), resolve);
-    });
-    rl.close();
-    if (answer.toLowerCase() !== 'y') {
-      logger.info('Cancelled.');
-      return;
-    }
-  }
-
-  const result = removeAgent(agentsData, id);
-  saveAgentsFile(getAgentsPath(), result.data);
-  logger.success(`Removed agent '${id}' from agents.json`);
-  logger.dim(`Run 'morph-spec setup-infra' to clean up .claude/agents/ files`);
-}
-
-// ── Helpers ─────────────────────────────────────────────────────────────────────
-
-/**
- * Levenshtein distance between two strings.
- * Used for "did you mean?" suggestions on typos.
- */
-export function levenshtein(a, b) {
-  const m = a.length;
-  const n = b.length;
-  const dp = Array.from({ length: m + 1 }, (_, i) => Array(n + 1).fill(0));
-  for (let i = 0; i <= m; i++) dp[i][0] = i;
-  for (let j = 0; j <= n; j++) dp[0][j] = j;
-  for (let i = 1; i <= m; i++) {
-    for (let j = 1; j <= n; j++) {
-      dp[i][j] = a[i - 1] === b[j - 1]
-        ? dp[i - 1][j - 1]
-        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
-    }
-  }
-  return dp[m][n];
-}
-
-/**
- * Interactive wizard for adding an agent.
- */
-async function runAddWizard(id, agentsData) {
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const ask = (q) => new Promise(resolve => rl.question(q, resolve));
-
-  console.log(chalk.bold(`\n  Adding agent: ${id}\n`));
-
-  const knownGroups = [...new Set(Object.values(agentsData.agents || {}).map(a => a.group))];
-
-  const tier = parseInt(await ask(`  ? Tier (1=${TIER_LABELS[1]}, 2=${TIER_LABELS[2]}, 3=${TIER_LABELS[3]}, 4=${TIER_LABELS[4]}): `), 10);
-  const title = await ask('  ? Title: ');
-  console.log(chalk.dim(`    Known groups: ${knownGroups.join(', ')}`));
-  const group = await ask('  ? Group: ');
-  const phasesRaw = await ask('  ? Active phases (comma-sep, or * for all): ');
-  const active_phases = phasesRaw.trim() === '*' ? ['*'] : phasesRaw.split(',').map(s => s.trim());
-
-  const existingIds = Object.keys(agentsData.agents || {});
-  console.log(chalk.dim(`    Valid: ${existingIds.slice(0, 5).join(', ')}... or "user"`));
-  const reports_to = await ask('  ? Reports to: ');
-
-  const domainsRaw = await ask('  ? Domains (comma-sep): ');
-  const domains = domainsRaw.split(',').map(s => s.trim()).filter(Boolean);
-  const keywordsRaw = await ask('  ? Keywords (comma-sep): ');
-  const keywords = keywordsRaw.split(',').map(s => s.trim()).filter(Boolean);
-
-  let teammate = null;
-  if (tier >= 3) {
-    const role = await ask('  ? Teammate role: ');
-    const icon = await ask('  ? Teammate icon (emoji): ');
-    const spawn_prompt = await ask('  ? Spawn prompt: ');
-    teammate = { role, icon, spawn_prompt };
-  }
-
-  rl.close();
-
-  return { tier, title, group, active_phases, reports_to, domains, keywords, teammate };
-}
-
-/**
- * Parse --non-interactive flags into fields object.
- */
-function parseNonInteractiveFlags(options) {
-  return {
-    tier: options.tier ? parseInt(options.tier, 10) : undefined,
-    title: options.title,
-    group: options.group,
-    active_phases: options.activePhases ? options.activePhases.split(',').map(s => s.trim()) : ['implement'],
-    reports_to: options.reportsTo || 'user',
-    domains: options.domains ? options.domains.split(',').map(s => s.trim()) : [],
-    keywords: options.keywords ? options.keywords.split(',').map(s => s.trim()) : [],
-    teammate: options.spawnPrompt ? {
-      role: options.role || 'specialist',
-      icon: options.icon || '\u{1F527}',
-      spawn_prompt: options.spawnPrompt,
-    } : null,
-  };
-}
-
-/**
- * Advisory check: is this agent referenced in active features?
- * Fail-open — any errors are silently ignored.
- */
-function checkActiveFeatures(agentId) {
-  try {
-    const statePath = join(process.cwd(), '.morph', 'state.json');
-    if (!existsSync(statePath)) return;
-    const state = JSON.parse(readFileSync(statePath, 'utf8'));
-    const activeIn = [];
-    for (const [fname, fdata] of Object.entries(state.features || {})) {
-      if (fdata.activeAgents?.includes(agentId)) activeIn.push(fname);
-    }
-    if (activeIn.length > 0) {
-      logger.warn(`Agent '${agentId}' is active in features: ${activeIn.join(', ')}. Removing from agents.json does not affect state.`);
-    }
-  } catch {
-    /* ignore — state check is advisory */
-  }
-}

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

@@ -1,74 +0,0 @@
-/**
- * project-metrics — Project-level metrics aggregation CLI
- *
- * Aggregates feature data from state.json into a project-wide summary.
- *
- * Usage:
- *   morph-spec project-metrics [--json] [--save]
- */
-
-import { writeFileSync, existsSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { loadState, stateExists } from '../../core/state/state-manager.js';
-import { aggregateProjectMetrics } from '../../lib/agents/metrics-aggregator.js';
-import chalk from 'chalk';
-
-/**
- * CLI command: morph-spec project-metrics [--json] [--save]
- */
-export async function projectMetricsCommand(options = {}) {
-  if (!stateExists()) {
-    console.error(chalk.red('No state.json found. Run morph-spec state init first.'));
-    process.exit(1);
-  }
-
-  try {
-    const state = loadState(false);
-    if (!state) {
-      console.error(chalk.red('Failed to load state.json.'));
-      process.exit(1);
-    }
-
-    const metrics = aggregateProjectMetrics(state);
-
-    if (options.save) {
-      const morphDir = join(process.cwd(), '.morph');
-      if (!existsSync(morphDir)) {
-        mkdirSync(morphDir, { recursive: true });
-      }
-      const outPath = join(morphDir, 'metrics.json');
-      writeFileSync(outPath, JSON.stringify(metrics, null, 2) + '\n', 'utf8');
-      console.log(chalk.green(`Metrics saved to ${outPath}`));
-    }
-
-    if (options.json) {
-      console.log(JSON.stringify(metrics, null, 2));
-      return;
-    }
-
-    // Human-readable table
-    const s = metrics.summary;
-    console.log(chalk.bold('\n  Project Metrics'));
-    console.log('  ' + '─'.repeat(50));
-    console.log(`  Features:      ${s.totalFeatures} (${s.completedFeatures} completed)`);
-    console.log(`  Tasks:         ${s.completedTasks}/${s.totalTasks} (${s.completionRate}%)`);
-    console.log(`  Avg tasks/feat: ${s.avgTasksPerFeature}`);
-    console.log(`  Dispatches:    ${s.totalDispatches}`);
-
-    if (metrics.features.length > 0) {
-      console.log(chalk.bold('\n  Features:'));
-      console.log(`  ${'Name'.padEnd(24)} ${'Phase'.padEnd(14)} ${'Tasks'.padEnd(10)} Dispatches`);
-      console.log('  ' + '─'.repeat(60));
-      for (const f of metrics.features) {
-        const taskStr = `${f.completedTasks}/${f.taskCount}`;
-        console.log(
-          `  ${f.name.padEnd(24)} ${chalk.cyan(f.phase.padEnd(14))} ${taskStr.padEnd(10)} ${f.dispatchCount}`
-        );
-      }
-    }
-    console.log();
-  } catch (err) {
-    console.error(chalk.red(`Error: ${err.message}`));
-    process.exit(1);
-  }
-}

package/src/commands/phase/phase-reset.js

@@ -1,74 +0,0 @@
-/**
- * MORPH-SPEC Phase Reset Command
- *
- * Recovery tool for corrupted phase state.
- * Sets the phase directly without approval gate checks.
- *
- * Usage:
- *   morph-spec phase reset <feature> <phase>
- */
-
-import chalk from 'chalk';
-import { loadState, saveState, derivePhase } from '../../core/state/state-manager.js';
-import { join } from 'path';
-
-const VALID_PHASES = ['proposal', 'uiux', 'design', 'plan', 'tasks', 'implement', 'sync'];
-
-/**
- * Core reset logic — exported for testing.
- * @param {string} featureName
- * @param {string} targetPhase
- * @returns {{ success: boolean, error?: string, derivedPhase?: string }}
- */
-export function resetPhase(featureName, targetPhase) {
-  if (!VALID_PHASES.includes(targetPhase)) {
-    return {
-      success: false,
-      error: `Unknown phase: "${targetPhase}". Valid phases: ${VALID_PHASES.join(', ')}`
-    };
-  }
-
-  const state = loadState();
-  if (!state?.features?.[featureName]) {
-    return {
-      success: false,
-      error: `Feature "${featureName}" not found in state.json`
-    };
-  }
-
-  // Get filesystem-derived phase for comparison
-  const featureFolderPath = join(process.cwd(), '.morph', 'features', featureName);
-  const derivedPhase = derivePhase(featureFolderPath);
-
-  // Set phase directly — no approval gate checks
-  state.features[featureName].phase = targetPhase;
-  state.features[featureName].updatedAt = new Date().toISOString();
-  saveState(state);
-
-  return { success: true, derivedPhase };
-}
-
-/**
- * CLI command handler
- */
-export async function phaseResetCommand(feature, phase) {
-  console.log(chalk.cyan('\n╔════════════════════════════════════════════════╗'));
-  console.log(chalk.cyan('║     MORPH-SPEC PHASE RESET                     ║'));
-  console.log(chalk.cyan('╚════════════════════════════════════════════════╝\n'));
-
-  const result = resetPhase(feature, phase);
-
-  if (!result.success) {
-    console.log(chalk.red(`\n✗ ${result.error}`));
-    process.exit(1);
-  }
-
-  console.log(chalk.green(`✓ Phase reset to "${phase}" for feature "${feature}"`));
-
-  if (result.derivedPhase !== phase) {
-    console.log(chalk.yellow(`\n⚠ Filesystem-derived phase is "${result.derivedPhase}" (folders on disk differ from state)`));
-    console.log(chalk.gray(`  This is expected during recovery. The state.json value takes priority.`));
-  }
-
-  console.log('');
-}