@polymorphism-tech/morph-spec 4.7.2 → 4.8.1

package/src/lib/generators/recap-generator.js

@@ -1,225 +1,232 @@
-/**
- * Recap Generator
- *
- * Auto-generates recap.md from real project data: state.json, contract compliance,
- * validation results, and decisions. Replaces manual template filling.
- *
- * MORPH-SPEC 3.0 - Phase B: Spec-Driven Pipeline
- */
-
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
-import { join, dirname } from 'path';
-import chalk from 'chalk';
-import { loadState } from '../../core/state/state-manager.js';
-import { runValidation } from '../validators/validation-runner.js';
-
-/**
- * Generate recap.md for a feature
- *
- * @param {string} projectPath - Project root path
- * @param {string} featureName - Feature name
- * @param {Object} options - Options
- * @returns {string} Generated recap content
- */
-export async function generateRecap(projectPath, featureName, options = {}) {
-  const state = loadState(false);
-  if (!state || !state.features[featureName]) {
-    throw new Error(`Feature '${featureName}' not found in state.json`);
-  }
-
-  const feature = state.features[featureName];
-  const outputsPath = join(projectPath, '.morph/features', featureName);
-
-  // Gather data
-  const tasksSummary = getTasksSummary(feature);
-  const agentsSummary = getAgentsSummary(feature);
-  const checkpointsSummary = getCheckpointsSummary(feature);
-  // Decision constraints support (stub - decision-constraint-loader removed as orphaned code)
-  const decisions = { decisions: [] };
-  const validationResult = await runValidation(projectPath, featureName, { verbose: false });
-
-  // Contract coverage
-  let contractCoverage = null;
-  if (validationResult.issues) {
-    const contractIssues = validationResult.issues.filter(i => i.message?.includes('Interface') || i.message?.includes('contracts'));
-    if (contractIssues.length > 0 || existsSync(join(outputsPath, 'contracts.cs'))) {
-      // Extract coverage from validation result
-      contractCoverage = extractContractCoverage(validationResult);
-    }
-  }
-
-  // Generate markdown
-  const recap = buildRecapMarkdown({
-    featureName,
-    feature,
-    tasksSummary,
-    agentsSummary,
-    checkpointsSummary,
-    decisions: decisions.decisions,
-    validationResult,
-    contractCoverage
-  });
-
-  // Write to file
-  const recapPath = join(outputsPath, 'recap.md');
-  if (!existsSync(dirname(recapPath))) {
-    mkdirSync(dirname(recapPath), { recursive: true });
-  }
-  writeFileSync(recapPath, recap, 'utf-8');
-
-  if (!options.quiet) {
-    console.log(chalk.green(`\n✅ Recap generated: ${recapPath}`));
-  }
-
-  return recap;
-}
-
-function getTasksSummary(feature) {
-  // v2: feature.tasks is an array of task objects
-  if (Array.isArray(feature.tasks)) {
-    const tasks = feature.tasks;
-    const completed = tasks.filter(t => t.status === 'completed');
-    const pending = tasks.filter(t => t.status === 'pending');
-    const inProgress = tasks.filter(t => t.status === 'in_progress');
-    return {
-      total: tasks.length,
-      completed: completed.length,
-      pending: pending.length,
-      inProgress: inProgress.length,
-      percentage: tasks.length > 0 ? Math.round((completed.length / tasks.length) * 100) : 0,
-      items: tasks
-    };
-  }
-
-  // v3: feature.tasks is a counter object {total, completed, inProgress, pending}
-  // Use feature.taskList for individual items if available
-  const counters = feature.tasks || {};
-  const items = feature.taskList || [];
-  const total = counters.total || items.length || 0;
-  const completedCount = counters.completed ?? items.filter(t => t.status === 'completed').length;
-  const pendingCount = counters.pending ?? items.filter(t => t.status === 'pending').length;
-  const inProgressCount = counters.inProgress ?? items.filter(t => t.status === 'in_progress').length;
-
-  return {
-    total,
-    completed: completedCount,
-    pending: pendingCount,
-    inProgress: inProgressCount,
-    percentage: total > 0 ? Math.round((completedCount / total) * 100) : 0,
-    items
-  };
-}
-
-function getAgentsSummary(feature) {
-  return feature.activeAgents || [];
-}
-
-function getCheckpointsSummary(feature) {
-  return (feature.checkpoints || []).map(cp => ({
-    timestamp: cp.timestamp,
-    note: cp.note,
-    tasks: cp.tasksCompleted || []
-  }));
-}
-
-function extractContractCoverage(validationResult) {
-  // Look for contract compliance data in validation issues
-  const interfaceErrors = validationResult.issues.filter(i =>
-    i.message?.includes('Interface') && i.level === 'error'
-  );
-  const methodErrors = validationResult.issues.filter(i =>
-    i.message?.includes('Method') && i.message?.includes('missing') && i.level === 'error'
-  );
-
-  return {
-    missingInterfaces: interfaceErrors.length,
-    missingMethods: methodErrors.length,
-    hasIssues: interfaceErrors.length > 0 || methodErrors.length > 0
-  };
-}
-
-function buildRecapMarkdown(data) {
-  const { featureName, feature, tasksSummary, agentsSummary, checkpointsSummary, decisions, validationResult, contractCoverage } = data;
-  const now = new Date().toISOString().split('T')[0];
-
-  let md = `# Recap: ${featureName}\n\n`;
-  md += `> Generated: ${now} | Phase: ${feature.phase} | Status: ${feature.status}\n\n`;
-  md += `---\n\n`;
-
-  // Progress
-  md += `## Progress\n\n`;
-  md += `| Metric | Value |\n|--------|-------|\n`;
-  md += `| Tasks completed | ${tasksSummary.completed}/${tasksSummary.total} (${tasksSummary.percentage}%) |\n`;
-  md += `| Tasks pending | ${tasksSummary.pending} |\n`;
-  md += `| Tasks in progress | ${tasksSummary.inProgress} |\n`;
-  md += `| Active agents | ${agentsSummary.length} |\n`;
-  md += `| Checkpoints | ${checkpointsSummary.length} |\n\n`;
-
-  // Validation Results
-  md += `## Validation Results\n\n`;
-  if (validationResult.passed) {
-    md += `**Status: PASSED** (${validationResult.warnings} warnings)\n\n`;
-  } else {
-    md += `**Status: FAILED** (${validationResult.errors} errors, ${validationResult.warnings} warnings)\n\n`;
-    if (validationResult.issues.length > 0) {
-      md += `| Level | Issue |\n|-------|-------|\n`;
-      for (const issue of validationResult.issues.slice(0, 15)) {
-        md += `| ${issue.level} | ${issue.message} |\n`;
-      }
-      md += `\n`;
-    }
-  }
-
-  // Contract Coverage
-  if (contractCoverage) {
-    md += `## Contract Compliance\n\n`;
-    if (contractCoverage.hasIssues) {
-      md += `- Missing interfaces: ${contractCoverage.missingInterfaces}\n`;
-      md += `- Missing methods: ${contractCoverage.missingMethods}\n\n`;
-    } else {
-      md += `All contracts implemented.\n\n`;
-    }
-  }
-
-  // Decisions
-  if (decisions.length > 0) {
-    md += `## Decisions Applied\n\n`;
-    for (const d of decisions) {
-      if (d.title) {
-        md += `- **${d.title}**: ${d.decision.slice(0, 100)}${d.decision.length > 100 ? '...' : ''}\n`;
-      }
-    }
-    md += `\n`;
-  }
-
-  // Agents
-  if (agentsSummary.length > 0) {
-    md += `## Active Agents\n\n`;
-    md += agentsSummary.map(a => `- ${a}`).join('\n');
-    md += `\n\n`;
-  }
-
-  // Checkpoints
-  if (checkpointsSummary.length > 0) {
-    md += `## Checkpoints\n\n`;
-    for (const cp of checkpointsSummary) {
-      md += `- ${cp.timestamp}: ${cp.note}\n`;
-    }
-    md += `\n`;
-  }
-
-  // Tasks Detail
-  if (tasksSummary.items.length > 0) {
-    md += `## Tasks\n\n`;
-    md += `| ID | Title | Status |\n|----|-------|--------|\n`;
-    for (const task of tasksSummary.items) {
-      const statusIcon = task.status === 'completed' ? '✅' : task.status === 'in_progress' ? '🔄' : '⏳';
-      md += `| ${task.id} | ${task.title || '-'} | ${statusIcon} ${task.status} |\n`;
-    }
-    md += `\n`;
-  }
-
-  md += `---\n\n*Generated by MORPH-SPEC Recap Generator*\n`;
-
-  return md;
-}
+/**
+ * Recap Generator
+ *
+ * Auto-generates recap.md from real project data: state.json, contract compliance,
+ * validation results, and decisions. Replaces manual template filling.
+ *
+ * MORPH-SPEC 3.0 - Phase B: Spec-Driven Pipeline
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, dirname } from 'path';
+import chalk from 'chalk';
+import { loadState, markOutput } from '../../core/state/state-manager.js';
+import { runValidation } from '../validators/validation-runner.js';
+
+/**
+ * Generate recap.md for a feature
+ *
+ * @param {string} projectPath - Project root path
+ * @param {string} featureName - Feature name
+ * @param {Object} options - Options
+ * @returns {string} Generated recap content
+ */
+export async function generateRecap(projectPath, featureName, options = {}) {
+  const state = loadState(false);
+  if (!state || !state.features[featureName]) {
+    throw new Error(`Feature '${featureName}' not found in state.json`);
+  }
+
+  const feature = state.features[featureName];
+  const outputsPath = join(projectPath, '.morph/features', featureName);
+
+  // Gather data
+  const tasksSummary = getTasksSummary(feature);
+  const agentsSummary = getAgentsSummary(feature);
+  const checkpointsSummary = getCheckpointsSummary(feature);
+  // Decision constraints support (stub - decision-constraint-loader removed as orphaned code)
+  const decisions = { decisions: [] };
+  const validationResult = await runValidation(projectPath, featureName, { verbose: false });
+
+  // Contract coverage
+  let contractCoverage = null;
+  if (validationResult.issues) {
+    const contractIssues = validationResult.issues.filter(i => i.message?.includes('Interface') || i.message?.includes('contracts'));
+    if (contractIssues.length > 0 || existsSync(join(outputsPath, 'contracts.cs'))) {
+      // Extract coverage from validation result
+      contractCoverage = extractContractCoverage(validationResult);
+    }
+  }
+
+  // Generate markdown
+  const recap = buildRecapMarkdown({
+    featureName,
+    feature,
+    tasksSummary,
+    agentsSummary,
+    checkpointsSummary,
+    decisions: decisions.decisions,
+    validationResult,
+    contractCoverage
+  });
+
+  // Write to file
+  const recapPath = join(outputsPath, 'recap.md');
+  if (!existsSync(dirname(recapPath))) {
+    mkdirSync(dirname(recapPath), { recursive: true });
+  }
+  writeFileSync(recapPath, recap, 'utf-8');
+
+  // Auto-mark recap output as created in state
+  try {
+    await markOutput(featureName, 'recap');
+  } catch {
+    // Non-fatal: state may not exist in all contexts
+  }
+
+  if (!options.quiet) {
+    console.log(chalk.green(`\n✅ Recap generated: ${recapPath}`));
+  }
+
+  return recap;
+}
+
+function getTasksSummary(feature) {
+  // v2: feature.tasks is an array of task objects
+  if (Array.isArray(feature.tasks)) {
+    const tasks = feature.tasks;
+    const completed = tasks.filter(t => t.status === 'completed');
+    const pending = tasks.filter(t => t.status === 'pending');
+    const inProgress = tasks.filter(t => t.status === 'in_progress');
+    return {
+      total: tasks.length,
+      completed: completed.length,
+      pending: pending.length,
+      inProgress: inProgress.length,
+      percentage: tasks.length > 0 ? Math.round((completed.length / tasks.length) * 100) : 0,
+      items: tasks
+    };
+  }
+
+  // v3: feature.tasks is a counter object {total, completed, inProgress, pending}
+  // Use feature.taskList for individual items if available
+  const counters = feature.tasks || {};
+  const items = feature.taskList || [];
+  const total = counters.total || items.length || 0;
+  const completedCount = counters.completed ?? items.filter(t => t.status === 'completed').length;
+  const pendingCount = counters.pending ?? items.filter(t => t.status === 'pending').length;
+  const inProgressCount = counters.inProgress ?? items.filter(t => t.status === 'in_progress').length;
+
+  return {
+    total,
+    completed: completedCount,
+    pending: pendingCount,
+    inProgress: inProgressCount,
+    percentage: total > 0 ? Math.round((completedCount / total) * 100) : 0,
+    items
+  };
+}
+
+function getAgentsSummary(feature) {
+  return feature.activeAgents || [];
+}
+
+function getCheckpointsSummary(feature) {
+  return (feature.checkpoints || []).map(cp => ({
+    timestamp: cp.timestamp,
+    note: cp.note,
+    tasks: cp.tasksCompleted || []
+  }));
+}
+
+function extractContractCoverage(validationResult) {
+  // Look for contract compliance data in validation issues
+  const interfaceErrors = validationResult.issues.filter(i =>
+    i.message?.includes('Interface') && i.level === 'error'
+  );
+  const methodErrors = validationResult.issues.filter(i =>
+    i.message?.includes('Method') && i.message?.includes('missing') && i.level === 'error'
+  );
+
+  return {
+    missingInterfaces: interfaceErrors.length,
+    missingMethods: methodErrors.length,
+    hasIssues: interfaceErrors.length > 0 || methodErrors.length > 0
+  };
+}
+
+function buildRecapMarkdown(data) {
+  const { featureName, feature, tasksSummary, agentsSummary, checkpointsSummary, decisions, validationResult, contractCoverage } = data;
+  const now = new Date().toISOString().split('T')[0];
+
+  let md = `# Recap: ${featureName}\n\n`;
+  md += `> Generated: ${now} | Phase: ${feature.phase} | Status: ${feature.status}\n\n`;
+  md += `---\n\n`;
+
+  // Progress
+  md += `## Progress\n\n`;
+  md += `| Metric | Value |\n|--------|-------|\n`;
+  md += `| Tasks completed | ${tasksSummary.completed}/${tasksSummary.total} (${tasksSummary.percentage}%) |\n`;
+  md += `| Tasks pending | ${tasksSummary.pending} |\n`;
+  md += `| Tasks in progress | ${tasksSummary.inProgress} |\n`;
+  md += `| Active agents | ${agentsSummary.length} |\n`;
+  md += `| Checkpoints | ${checkpointsSummary.length} |\n\n`;
+
+  // Validation Results
+  md += `## Validation Results\n\n`;
+  if (validationResult.passed) {
+    md += `**Status: PASSED** (${validationResult.warnings} warnings)\n\n`;
+  } else {
+    md += `**Status: FAILED** (${validationResult.errors} errors, ${validationResult.warnings} warnings)\n\n`;
+    if (validationResult.issues.length > 0) {
+      md += `| Level | Issue |\n|-------|-------|\n`;
+      for (const issue of validationResult.issues.slice(0, 15)) {
+        md += `| ${issue.level} | ${issue.message} |\n`;
+      }
+      md += `\n`;
+    }
+  }
+
+  // Contract Coverage
+  if (contractCoverage) {
+    md += `## Contract Compliance\n\n`;
+    if (contractCoverage.hasIssues) {
+      md += `- Missing interfaces: ${contractCoverage.missingInterfaces}\n`;
+      md += `- Missing methods: ${contractCoverage.missingMethods}\n\n`;
+    } else {
+      md += `All contracts implemented.\n\n`;
+    }
+  }
+
+  // Decisions
+  if (decisions.length > 0) {
+    md += `## Decisions Applied\n\n`;
+    for (const d of decisions) {
+      if (d.title) {
+        md += `- **${d.title}**: ${d.decision.slice(0, 100)}${d.decision.length > 100 ? '...' : ''}\n`;
+      }
+    }
+    md += `\n`;
+  }
+
+  // Agents
+  if (agentsSummary.length > 0) {
+    md += `## Active Agents\n\n`;
+    md += agentsSummary.map(a => `- ${a}`).join('\n');
+    md += `\n\n`;
+  }
+
+  // Checkpoints
+  if (checkpointsSummary.length > 0) {
+    md += `## Checkpoints\n\n`;
+    for (const cp of checkpointsSummary) {
+      md += `- ${cp.timestamp}: ${cp.note}\n`;
+    }
+    md += `\n`;
+  }
+
+  // Tasks Detail
+  if (tasksSummary.items.length > 0) {
+    md += `## Tasks\n\n`;
+    md += `| ID | Title | Status |\n|----|-------|--------|\n`;
+    for (const task of tasksSummary.items) {
+      const statusIcon = task.status === 'completed' ? '✅' : task.status === 'in_progress' ? '🔄' : '⏳';
+      md += `| ${task.id} | ${task.title || '-'} | ${statusIcon} ${task.status} |\n`;
+    }
+    md += `\n`;
+  }
+
+  md += `---\n\n*Generated by MORPH-SPEC Recap Generator*\n`;
+
+  return md;
+}

package/src/scripts/global-install.js

@@ -0,0 +1,34 @@
+// src/scripts/global-install.js
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { homedir } from 'os';
+import { mkdir, copyFile } from 'fs/promises';
+import { existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FRAMEWORK_DIR = join(__dirname, '..', '..', 'framework');
+
+/**
+ * Install morph-init skill to a Claude global skills directory.
+ * @param {string} claudeDir - target ~/.claude dir (defaults to real ~/.claude)
+ */
+export async function installGlobalSkill(claudeDir = join(homedir(), '.claude')) {
+  const src = join(FRAMEWORK_DIR, 'skills', 'level-0-meta', 'morph-init', 'SKILL.md');
+  const destDir = join(claudeDir, 'skills', 'morph-init');
+  const dest = join(destDir, 'SKILL.md');
+
+  if (!existsSync(src)) {
+    console.warn(`morph-init skill not found at ${src} — skipping global install`);
+    return;
+  }
+
+  await mkdir(destDir, { recursive: true });
+  await copyFile(src, dest);
+}
+
+// Run as postinstall script
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  installGlobalSkill()
+    .then(() => console.log('✓ morph-init skill installed to ~/.claude/skills/'))
+    .catch(e => console.warn('Could not install morph-init skill globally:', e.message));
+}

package/src/scripts/install-plugin.js

@@ -0,0 +1,126 @@
+// src/scripts/install-plugin.js
+import { join } from 'path';
+import { homedir } from 'os';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { mkdir, writeFile } from 'fs/promises';
+import https from 'node:https';
+
+const PLUGINS_DIR = join(homedir(), '.claude', 'plugins');
+const CACHE_DIR = join(PLUGINS_DIR, 'cache', 'claude-plugins-official');
+const INSTALLED_FILE = join(PLUGINS_DIR, 'installed_plugins.json');
+const GH_REPO = 'anthropics/claude-plugins-official';
+
+/** Fetch JSON from GitHub API (no auth — public repo) */
+async function fetchGitHub(path) {
+  return new Promise((resolve, reject) => {
+    const opts = {
+      hostname: 'api.github.com',
+      path,
+      headers: { 'User-Agent': 'morph-spec', 'Accept': 'application/vnd.github.v3+json' }
+    };
+    https.get(opts, (res) => {
+      let data = '';
+      res.on('data', c => data += c);
+      res.on('end', () => {
+        try { resolve(JSON.parse(data)); }
+        catch (e) { reject(new Error(`GitHub API parse error: ${data.slice(0, 200)}`)); }
+      });
+    }).on('error', reject);
+  });
+}
+
+/** Download raw file content from a URL, following one redirect */
+async function downloadFile(rawUrl) {
+  return new Promise((resolve, reject) => {
+    const doGet = (url) => {
+      const parsed = new URL(url);
+      https.get({
+        hostname: parsed.hostname,
+        path: parsed.pathname + parsed.search,
+        headers: { 'User-Agent': 'morph-spec' }
+      }, (res) => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          return doGet(res.headers.location);
+        }
+        const chunks = [];
+        res.on('data', c => chunks.push(c));
+        res.on('end', () => resolve(Buffer.concat(chunks)));
+      }).on('error', reject);
+    };
+    doGet(rawUrl);
+  });
+}
+
+/** Read installed_plugins.json safely */
+export function readInstalledPlugins() {
+  if (!existsSync(INSTALLED_FILE)) return { version: 2, plugins: {} };
+  try { return JSON.parse(readFileSync(INSTALLED_FILE, 'utf8')); }
+  catch { return { version: 2, plugins: {} }; }
+}
+
+/** Check if plugin key exists in the plugins map */
+export function isPluginInstalled(plugins, name) {
+  return `${name}@claude-plugins-official` in plugins;
+}
+
+/** Build an installed_plugins.json entry */
+export function buildInstallEntry(pluginName, installPath, gitCommitSha, version) {
+  const now = new Date().toISOString();
+  return { scope: 'user', installPath, version, installedAt: now, lastUpdated: now, gitCommitSha };
+}
+
+/** Resolve latest commit SHA for a plugin path in the repo */
+export async function resolvePluginVersion(pluginName) {
+  const commits = await fetchGitHub(`/repos/${GH_REPO}/commits?path=${pluginName}&per_page=1`);
+  if (!Array.isArray(commits) || commits.length === 0) {
+    throw new Error(`Could not resolve version for plugin: ${pluginName}`);
+  }
+  const sha = commits[0].sha;
+  return { sha, shortSha: sha.slice(0, 12) };
+}
+
+/** Download all files for a plugin from the repo tree */
+async function downloadPluginFiles(pluginName, sha, destDir) {
+  const tree = await fetchGitHub(`/repos/${GH_REPO}/git/trees/${sha}?recursive=1`);
+  if (!tree.tree) throw new Error('GitHub tree API returned unexpected shape');
+
+  const pluginFiles = tree.tree.filter(f => f.path.startsWith(`${pluginName}/`) && f.type === 'blob');
+  if (pluginFiles.length === 0) throw new Error(`Plugin "${pluginName}" not found in repository`);
+
+  for (const file of pluginFiles) {
+    const relativePath = file.path.slice(pluginName.length + 1);
+    const destPath = join(destDir, relativePath);
+    await mkdir(join(destPath, '..'), { recursive: true });
+    const content = await downloadFile(
+      `https://raw.githubusercontent.com/${GH_REPO}/${sha}/${file.path}`
+    );
+    await writeFile(destPath, content);
+  }
+}
+
+/**
+ * Install a Claude Code plugin from GitHub.
+ * @param {string} pluginName - e.g. "superpowers"
+ * @returns {{ installed: boolean, version: string, alreadyInstalled: boolean }}
+ */
+export async function installPlugin(pluginName) {
+  const data = readInstalledPlugins();
+  if (isPluginInstalled(data.plugins, pluginName)) {
+    const existing = data.plugins[`${pluginName}@claude-plugins-official`];
+    const version = Array.isArray(existing) ? existing[0]?.version : 'unknown';
+    return { installed: true, alreadyInstalled: true, version };
+  }
+
+  const { sha, shortSha } = await resolvePluginVersion(pluginName);
+  const installPath = join(CACHE_DIR, pluginName, shortSha);
+
+  await mkdir(installPath, { recursive: true });
+  await downloadPluginFiles(pluginName, sha, installPath);
+
+  const entry = buildInstallEntry(pluginName, installPath, sha, shortSha);
+  data.plugins[`${pluginName}@claude-plugins-official`] = [entry];
+  mkdirSync(PLUGINS_DIR, { recursive: true });
+  writeFileSync(INSTALLED_FILE, JSON.stringify(data, null, 2));
+
+  return { installed: true, alreadyInstalled: false, version: shortSha };
+}