@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

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

@@ -28,7 +28,7 @@ export async function generateRecap(projectPath, featureName, options = {}) {
   }
 
   const feature = state.features[featureName];
-  const outputsPath = join(projectPath, '.morph/project/outputs', featureName);
+  const outputsPath = join(projectPath, '.morph/features', featureName);
 
   // Gather data
   const tasksSummary = getTasksSummary(feature);

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

@@ -0,0 +1,210 @@
+/**
+ * Settings Generator
+ *
+ * Generates .claude/settings.local.json for projects based on detected
+ * stack, MCPs, and morph-spec configuration. Uses _morph_managed marker
+ * to track managed entries for safe reset.
+ */
+
+import { join } from 'path';
+import { existsSync } from 'fs';
+import { readFile, writeFile, mkdir } from 'fs/promises';
+
+const MORPH_MANAGED_KEY = '_morph_managed';
+
+/**
+ * Generate and merge settings for a project
+ * @param {string} targetPath - Project root directory
+ * @param {Object} detectedConfig - Output from detectClaudeConfig()
+ * @param {Object} morphConfig - morph-spec config (from .morph/config/config.json)
+ * @returns {Promise<Object>} Generated settings summary
+ */
+export async function generateSettings(targetPath, detectedConfig, morphConfig = {}) {
+  const claudeDir = join(targetPath, '.claude');
+  const settingsPath = join(claudeDir, 'settings.local.json');
+
+  // Read existing settings
+  const existing = await readSettingsSafe(settingsPath);
+
+  // Build stack-based permissions
+  const stack = morphConfig?.project?.architecture || 'unknown';
+  const permissions = buildPermissions(stack, detectedConfig);
+
+  // Build generated settings
+  const generated = {};
+
+  if (permissions.length > 0) {
+    generated.permissions = permissions;
+  }
+
+  // Track what we manage
+  const managed = {
+    permissions_added: permissions,
+    mcps_detected: detectedConfig.mcpServers.map(s => s.name),
+    plugins_detected: detectedConfig.plugins.map(p => p.name),
+    generated_at: new Date().toISOString()
+  };
+
+  // Merge without overwriting user config
+  const merged = mergeSettings(existing, generated);
+  merged[MORPH_MANAGED_KEY] = managed;
+
+  // Ensure directory exists
+  if (!existsSync(claudeDir)) {
+    await mkdir(claudeDir, { recursive: true });
+  }
+
+  await writeFile(settingsPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+
+  return {
+    settingsPath,
+    permissionsAdded: permissions.length,
+    managed
+  };
+}
+
+/**
+ * Build permission rules based on detected stack
+ * @param {string} stack - Detected project stack
+ * @param {Object} detectedConfig - Detected Claude config
+ * @returns {Array<string>} Permission patterns
+ */
+export function buildPermissions(stack, detectedConfig = {}) {
+  const permissions = [];
+
+  // Stack-based permissions
+  const stackPermissions = {
+    nodejs: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    typescript: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)', 'Bash(tsc:*)'],
+    nextjs: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    react: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    vue: ['Bash(node:*)', 'Bash(npm:*)', 'Bash(npx:*)'],
+    dotnet: ['Bash(dotnet:*)', 'Bash(nuget:*)'],
+    blazor: ['Bash(dotnet:*)', 'Bash(nuget:*)'],
+    python: ['Bash(python:*)', 'Bash(pip:*)', 'Bash(pytest:*)'],
+    go: ['Bash(go:*)']
+  };
+
+  if (stackPermissions[stack]) {
+    permissions.push(...stackPermissions[stack]);
+  }
+
+  // morph-spec CLI always needs node/npx
+  if (!permissions.includes('Bash(npx:*)')) {
+    permissions.push('Bash(npx:*)');
+  }
+
+  return permissions;
+}
+
+/**
+ * Deep merge settings without overwriting user entries
+ * @param {Object} existing - Current settings.local.json
+ * @param {Object} generated - Generated settings to merge
+ * @returns {Object} Merged settings
+ */
+export function mergeSettings(existing, generated) {
+  const result = { ...existing };
+
+  for (const [key, value] of Object.entries(generated)) {
+    if (key === MORPH_MANAGED_KEY) continue;
+
+    if (Array.isArray(value) && Array.isArray(result[key])) {
+      // Merge arrays without duplicates
+      const set = new Set(result[key]);
+      for (const item of value) {
+        set.add(item);
+      }
+      result[key] = [...set];
+    } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+      // Recursively merge objects
+      result[key] = mergeSettings(result[key] || {}, value);
+    } else if (!(key in result)) {
+      // Only add new keys, never overwrite existing
+      result[key] = value;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Remove only morph-spec managed entries from settings
+ * @param {string} settingsPath - Path to settings.local.json
+ * @returns {Promise<Object>} Summary of what was removed
+ */
+export async function resetMorphSettings(settingsPath) {
+  if (!existsSync(settingsPath)) {
+    return { removed: false, reason: 'file not found' };
+  }
+
+  const settings = await readSettingsSafe(settingsPath);
+  const managed = settings[MORPH_MANAGED_KEY];
+
+  if (!managed) {
+    return { removed: false, reason: 'no _morph_managed section found' };
+  }
+
+  // Remove managed permissions
+  if (managed.permissions_added && Array.isArray(settings.permissions)) {
+    settings.permissions = settings.permissions.filter(
+      p => !managed.permissions_added.includes(p)
+    );
+    if (settings.permissions.length === 0) {
+      delete settings.permissions;
+    }
+  }
+
+  // Remove the managed marker itself
+  delete settings[MORPH_MANAGED_KEY];
+
+  // Write back
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+
+  return {
+    removed: true,
+    permissionsRemoved: managed.permissions_added || [],
+    previouslyGenerated: managed.generated_at
+  };
+}
+
+/**
+ * Save integrations.json with detected config
+ * @param {string} targetPath - Project root directory
+ * @param {Object} detectedConfig - Output from detectClaudeConfig()
+ */
+export async function saveIntegrations(targetPath, detectedConfig) {
+  const integrationsPath = join(targetPath, '.morph', 'config', 'integrations.json');
+  const integrationsDir = join(targetPath, '.morph', 'config');
+
+  if (!existsSync(integrationsDir)) {
+    await mkdir(integrationsDir, { recursive: true });
+  }
+
+  const integrations = {
+    version: '1.0.0',
+    detectedAt: new Date().toISOString(),
+    plugins: detectedConfig.plugins,
+    mcpServers: detectedConfig.mcpServers,
+    superpowers: detectedConfig.superpowers,
+    customSkills: detectedConfig.customSkills.length,
+    customCommands: detectedConfig.customCommands.length,
+    hooks: detectedConfig.hooks.length
+  };
+
+  await writeFile(integrationsPath, JSON.stringify(integrations, null, 2) + '\n', 'utf-8');
+  return integrationsPath;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+async function readSettingsSafe(settingsPath) {
+  try {
+    if (!existsSync(settingsPath)) return {};
+    return JSON.parse(await readFile(settingsPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}

package/src/lib/hooks/hook-executor.js

@@ -19,7 +19,7 @@ import { join } from 'path';
 
 function loadAgents(projectPath) {
   const agentPaths = [
-    join(projectPath, '.morph/config/agents.json'),
+    join(projectPath, '.morph/framework/agents.json'),
   ];
 
   const allAgents = {};

package/src/lib/installers/mcp-installer.js

@@ -0,0 +1,299 @@
+/**
+ * MCP Installer
+ *
+ * Core logic for installing and configuring MCP servers during morph-spec init
+ * and via `morph-spec mcp setup`. Handles auto-installable (credential-free)
+ * MCPs, prerequisite checking, credential collection, and setup guidance.
+ */
+
+import { join } from 'path';
+import { readFileSync, existsSync } from 'fs';
+import { execSync } from 'child_process';
+import { installMcpServers } from '../../utils/claude-settings-manager.js';
+
+/**
+ * Load the enhanced MCP registry (v2.0.0)
+ * @returns {Object} Registry with install blocks
+ */
+export function loadMcpRegistry() {
+  const registryPath = join(
+    import.meta.dirname, '..', '..', '..', 'framework', 'skills', 'level-0-meta', 'mcp-registry.json'
+  );
+  const raw = readFileSync(registryPath, 'utf-8');
+  return JSON.parse(raw);
+}
+
+/**
+ * Filter MCPs by stack relevance
+ * @param {Object} registry - Full MCP registry
+ * @param {string} stack - Detected project stack (e.g., 'nextjs-supabase', 'blazor')
+ * @returns {Object} Filtered map of mcpName → mcpEntry
+ */
+export function filterByStack(registry, stack) {
+  const result = {};
+  const normalizedStack = (stack || '').toLowerCase();
+
+  for (const [name, entry] of Object.entries(registry.mcps)) {
+    if (!entry.install) continue;
+    const relevance = entry.install.stackRelevance || [];
+
+    if (relevance.includes('*')) {
+      result[name] = entry;
+    } else if (normalizedStack && relevance.some(s => normalizedStack.includes(s))) {
+      result[name] = entry;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Match detected MCP servers against the registry
+ * @param {Array} existingServers - From detectClaudeConfig().mcpServers
+ * @param {Object} registry - MCP registry
+ * @returns {Object} Map of mcpName → { installed: true, source }
+ */
+export function getInstalledMcps(existingServers, registry) {
+  const installed = {};
+  const registryNames = Object.keys(registry.mcps);
+
+  for (const server of existingServers) {
+    const serverName = server.name.toLowerCase();
+    for (const regName of registryNames) {
+      if (serverName.includes(regName)) {
+        installed[regName] = { installed: true, source: server.source };
+      }
+    }
+  }
+
+  return installed;
+}
+
+/**
+ * Check if prerequisites are met for an MCP entry
+ * @param {Object} mcpEntry - MCP entry from registry
+ * @returns {Array} Array of { name, met, installUrl } for each prerequisite
+ */
+export function checkPrerequisites(mcpEntry) {
+  const prereqs = mcpEntry.install?.prerequisites || [];
+  const results = [];
+
+  for (const prereq of prereqs) {
+    let met = false;
+    try {
+      execSync(prereq.checkCommand, { stdio: 'ignore', timeout: 5000 });
+      met = true;
+    } catch {
+      // Command failed or not found
+    }
+    results.push({
+      name: prereq.name,
+      met,
+      installUrl: prereq.installUrl
+    });
+  }
+
+  return results;
+}
+
+/**
+ * Install auto-installable MCPs (no credentials, no prerequisites)
+ * @param {string} targetPath - Project root directory
+ * @param {Object} mcpsToInstall - Map of mcpName → mcpEntry
+ * @returns {Promise<Object>} Result from installMcpServers
+ */
+export async function installAutoMcps(targetPath, mcpsToInstall) {
+  const servers = {};
+
+  for (const [name, entry] of Object.entries(mcpsToInstall)) {
+    const config = { ...entry.install.config };
+    // Only include env if it has actual values
+    if (config.env && Object.values(config.env).every(v => !v)) {
+      delete config.env;
+    }
+    servers[name] = config;
+  }
+
+  return installMcpServers(targetPath, servers);
+}
+
+/**
+ * Install a single MCP with provided credentials
+ * @param {string} targetPath - Project root directory
+ * @param {string} name - MCP name
+ * @param {Object} mcpEntry - MCP entry from registry
+ * @param {Object} credentialValues - Map of envVar → value
+ * @returns {Promise<Object>} Result from installMcpServers
+ */
+export async function installMcpWithCredentials(targetPath, name, mcpEntry, credentialValues) {
+  const config = { ...mcpEntry.install.config };
+  config.env = { ...config.env, ...credentialValues };
+  return installMcpServers(targetPath, { [name]: config });
+}
+
+/**
+ * Generate setup instructions for a credential-requiring MCP
+ * @param {string} name - MCP name
+ * @param {Object} mcpEntry - MCP entry from registry
+ * @returns {Object} { configSnippet, credentialUrls, cliCommand }
+ */
+export function generateSetupInstructions(name, mcpEntry) {
+  const config = mcpEntry.install.config;
+  const credentials = mcpEntry.install.credentials || [];
+
+  // Build the config snippet with placeholder values
+  const snippetConfig = { ...config };
+  if (credentials.length > 0) {
+    snippetConfig.env = {};
+    for (const cred of credentials) {
+      snippetConfig.env[cred.envVar] = cred.secret ? 'YOUR_KEY' : 'YOUR_VALUE';
+    }
+  }
+
+  const configSnippet = JSON.stringify({ [name]: snippetConfig }, null, 2);
+
+  const credentialUrls = credentials.map(c => ({
+    name: c.name,
+    envVar: c.envVar,
+    helpUrl: c.helpUrl
+  }));
+
+  return {
+    configSnippet,
+    credentialUrls,
+    cliCommand: `morph-spec mcp setup ${name}`
+  };
+}
+
+/**
+ * Full orchestrator for MCP setup during init or `mcp setup`
+ * @param {string} targetPath - Project root directory
+ * @param {string} stack - Detected project stack
+ * @param {Array} existingMcps - From detectClaudeConfig().mcpServers
+ * @param {Object} options
+ * @param {boolean} options.autoOnly - Only handle auto-installable MCPs
+ * @returns {Object} { autoInstallable, alreadyInstalled, needsManualSetup, notRelevant, prerequisitesMissing }
+ */
+export function orchestrateMcpSetup(targetPath, stack, existingMcps, options = {}) {
+  const registry = loadMcpRegistry();
+  const relevant = filterByStack(registry, stack);
+  const installed = getInstalledMcps(existingMcps || [], registry);
+
+  const autoInstallable = {};
+  const alreadyInstalled = {};
+  const needsManualSetup = {};
+  const notRelevant = {};
+  const prerequisitesMissing = {};
+
+  // Categorize all MCPs
+  for (const [name, entry] of Object.entries(registry.mcps)) {
+    if (!entry.install) continue;
+
+    // Check if already installed
+    if (installed[name]) {
+      alreadyInstalled[name] = { entry, source: installed[name].source };
+      continue;
+    }
+
+    // Check if relevant to stack
+    if (!relevant[name]) {
+      notRelevant[name] = entry;
+      continue;
+    }
+
+    // Check prerequisites
+    const prereqResults = checkPrerequisites(entry);
+    const unmetPrereqs = prereqResults.filter(p => !p.met);
+    if (unmetPrereqs.length > 0) {
+      prerequisitesMissing[name] = { entry, unmet: unmetPrereqs };
+      continue;
+    }
+
+    // Categorize by install type
+    if (entry.install.autoInstall) {
+      autoInstallable[name] = entry;
+    } else if (!options.autoOnly) {
+      needsManualSetup[name] = entry;
+    }
+  }
+
+  return {
+    registry,
+    autoInstallable,
+    alreadyInstalled,
+    needsManualSetup,
+    notRelevant,
+    prerequisitesMissing
+  };
+}
+
+/**
+ * Format MCP status table for display
+ * @param {Object} orchestration - Result from orchestrateMcpSetup
+ * @param {Object} justInstalled - Map of names just installed during this run
+ * @returns {Array<Object>} Array of { name, status, detail }
+ */
+export function formatMcpStatusTable(orchestration, justInstalled = {}) {
+  const rows = [];
+
+  const { autoInstallable, alreadyInstalled, needsManualSetup, notRelevant, prerequisitesMissing, registry } = orchestration;
+
+  // Installed during this run
+  for (const [name, entry] of Object.entries(justInstalled)) {
+    const mcpEntry = registry.mcps[name];
+    rows.push({
+      name,
+      status: 'installed',
+      detail: mcpEntry ? mcpEntry.usage : ''
+    });
+  }
+
+  // Auto-installable but not yet installed (and not just-installed)
+  for (const [name, entry] of Object.entries(autoInstallable)) {
+    if (justInstalled[name]) continue;
+    rows.push({
+      name,
+      status: 'available',
+      detail: `Run: morph-spec mcp setup --auto`
+    });
+  }
+
+  // Already installed
+  for (const [name, { source }] of Object.entries(alreadyInstalled)) {
+    rows.push({
+      name,
+      status: 'already_configured',
+      detail: `(${source})`
+    });
+  }
+
+  // Needs manual setup
+  for (const [name, entry] of Object.entries(needsManualSetup)) {
+    rows.push({
+      name,
+      status: 'needs_setup',
+      detail: `Run: morph-spec mcp setup ${name}`
+    });
+  }
+
+  // Prerequisites missing
+  for (const [name, { unmet }] of Object.entries(prerequisitesMissing)) {
+    const missing = unmet.map(p => p.name).join(', ');
+    rows.push({
+      name,
+      status: 'prereq_missing',
+      detail: `Missing: ${missing}`
+    });
+  }
+
+  // Not relevant
+  for (const [name] of Object.entries(notRelevant)) {
+    rows.push({
+      name,
+      status: 'not_relevant',
+      detail: 'not relevant to stack'
+    });
+  }
+
+  return rows;
+}

package/src/lib/learning/learning-system.js

@@ -6,7 +6,7 @@
  *
  * Learns from:
  * - decisions.md files (ADRs from each feature)
- * - .morph/project/standards/*.md (project standards)
+ * - .morph/context/*.md (project standards)
  * - state.json (feature outcomes and complexity)
  *
  * MORPH-SPEC 3.0 - Sprint 4
@@ -118,7 +118,7 @@ export class LearningSystem {
     console.log(chalk.cyan('🧠 Learning from project history...\n'));
 
     // Find all decisions.md files
-    const decisionFiles = await glob('.morph/project/outputs/*/decisions.md', {
+    const decisionFiles = await glob('.morph/features/*/decisions.md', {
       cwd: this.projectPath
     });
 
@@ -130,7 +130,7 @@ export class LearningSystem {
     let newDecisions = 0;
 
     for (const file of decisionFiles) {
-      const featureName = file.split('/')[3]; // Extract feature name from path
+      const featureName = file.split('/')[2]; // Extract feature name from path
       const learned = await this.learnFromDecisionFile(file, featureName);
       newDecisions += learned;
     }

package/src/lib/orchestration/team-orchestrator.js

@@ -23,7 +23,7 @@ const __dirname = path.dirname(__filename);
  * @returns {Promise<Object>} Parsed agents configuration
  */
 async function loadAgentsConfig(projectPath) {
-  const agentsPath = path.join(projectPath, '.morph/config/agents.json');
+  const agentsPath = path.join(projectPath, '.morph/framework/agents.json');
   const content = await fs.readFile(agentsPath, 'utf8');
   return JSON.parse(content);
 }

package/src/lib/standards/standards-context-injector.js

@@ -19,7 +19,7 @@ const AGENT_STANDARDS_MAP = {
   'standards-architect': [
     'core/architecture',
     'core/coding',
-    'infrastructure/azure/azure', // Stack-specific (kept in .morph/standards/)
+    'infrastructure/azure/azure', // Stack-specific (kept in .morph/framework/standards/)
     'backend/dotnet/core',
     'backend/dotnet/program-cs-checklist'
   ],
@@ -200,9 +200,9 @@ const AGENT_STANDARDS_MAP = {
 function loadStandard(standardName, projectPath) {
   const locations = [
     // 1. Project override
-    join(projectPath, '.morph/project/standards', `${standardName}.md`),
-    // 2. Project-level standards (.morph/standards/)
-    join(projectPath, '.morph/standards', `${standardName}.md`),
+    join(projectPath, '.morph/context', `${standardName}.md`),
+    // 2. Project-level standards (.morph/framework/standards/)
+    join(projectPath, '.morph/framework/standards', `${standardName}.md`),
     // 3. Framework standards (hierarchical structure: core/, backend/, frontend/, infrastructure/)
     join(projectPath, 'framework/standards', `${standardName}.md`)
   ];
@@ -232,7 +232,7 @@ export function loadStandardsForAgent(agentId, projectPath = '.') {
   const contentParts = [];
 
   // Load inferred standards if exists (project-specific learnings)
-  const inferredPath = join(projectPath, '.morph/project/standards/inferred.md');
+  const inferredPath = join(projectPath, '.morph/context/inferred.md');
   if (existsSync(inferredPath)) {
     try {
       const inferredContent = readFileSync(inferredPath, 'utf8');
@@ -282,8 +282,8 @@ export function getStandardsListForAgent(agentId) {
  */
 export function checkStandardExists(standardName, projectPath = '.') {
   const locations = [
-    { type: 'project', path: join(projectPath, '.morph/project/standards', `${standardName}.md`) },
-    { type: 'morph', path: join(projectPath, '.morph/standards', `${standardName}.md`) },
+    { type: 'project', path: join(projectPath, '.morph/context', `${standardName}.md`) },
+    { type: 'morph', path: join(projectPath, '.morph/framework/standards', `${standardName}.md`) },
     { type: 'framework', path: join(projectPath, 'framework/standards', `${standardName}.md`) }
   ];
 

package/src/lib/threads/thread-coordinator.js

@@ -44,7 +44,7 @@ export function buildGraph(tasks) {
  * @returns {Object} { nodes: Map<id, task>, edges: Map<id, Set<depId>> }
  */
 export function analyzeDependencies(feature) {
-  const tasksPath = join(process.cwd(), `.morph/project/outputs/${feature}/tasks.json`);
+  const tasksPath = join(process.cwd(), `.morph/features/${feature}/tasks.json`);
 
   if (!existsSync(tasksPath)) {
     throw new Error(`tasks.json not found for feature: ${feature}`);

package/src/lib/troubleshooting/troubleshoot-grep.js

@@ -13,7 +13,7 @@ const __dirname = dirname(__filename);
 // Directories to search
 const SEARCH_PATHS = [
   'framework/standards',
-  '.morph/standards',
+  '.morph/framework/standards',
   '.wiki'
 ];