@polymorphism-tech/morph-spec 7.8.1 → 7.9.0

package/src/utils/claude-settings-manager.js

@@ -1,300 +1,300 @@
-/**
- * Claude Settings Manager
- *
- * Extends the original hooks-installer with broader settings management:
- * permissions, env vars, and managed entry tracking.
- *
- * Re-exports installClaudeHooks for backward compatibility.
- */
-
-import { join } from 'path';
-import { readFile, writeFile, mkdir, copyFile } from 'fs/promises';
-import { existsSync } from 'fs';
-
-const MORPH_MANAGED_KEY = '_morph_managed';
-
-// ============================================================================
-// Re-export from hooks-installer (v2 registry-based)
-// ============================================================================
-
-export { installClaudeHooks, installGlobalStatusline, getHooksVersion } from './hooks-installer.js';
-export { installAgents } from './agents-installer.js';
-
-// ============================================================================
-// Extended settings management
-// ============================================================================
-
-/**
- * Install permission rules into .claude/settings.local.json
- * @param {string} targetPath - Project root directory
- * @param {Array<string>} permissions - Permission patterns to add
- * @returns {Promise<Object>} Summary of changes
- */
-export async function installPermissions(targetPath, permissions) {
-  const settings = await loadSettings(targetPath);
-
-  settings.permissions = settings.permissions || [];
-
-  const added = [];
-  for (const perm of permissions) {
-    if (!settings.permissions.includes(perm)) {
-      settings.permissions.push(perm);
-      added.push(perm);
-    }
-  }
-
-  // Track in _morph_managed
-  settings[MORPH_MANAGED_KEY] = settings[MORPH_MANAGED_KEY] || {};
-  settings[MORPH_MANAGED_KEY].permissions_added =
-    settings[MORPH_MANAGED_KEY].permissions_added || [];
-  for (const perm of added) {
-    if (!settings[MORPH_MANAGED_KEY].permissions_added.includes(perm)) {
-      settings[MORPH_MANAGED_KEY].permissions_added.push(perm);
-    }
-  }
-  settings[MORPH_MANAGED_KEY].generated_at = new Date().toISOString();
-
-  await saveSettings(targetPath, settings);
-
-  return { added, total: settings.permissions.length };
-}
-
-/**
- * Install environment variables into .claude/settings.local.json
- * @param {string} targetPath - Project root directory
- * @param {Object} envVars - Key-value pairs to add to env
- * @returns {Promise<Object>} Summary of changes
- */
-export async function installEnvVars(targetPath, envVars) {
-  const settings = await loadSettings(targetPath);
-
-  settings.env = settings.env || {};
-
-  const added = [];
-  for (const [key, value] of Object.entries(envVars)) {
-    if (!(key in settings.env)) {
-      settings.env[key] = value;
-      added.push(key);
-    }
-  }
-
-  // Track in _morph_managed
-  settings[MORPH_MANAGED_KEY] = settings[MORPH_MANAGED_KEY] || {};
-  settings[MORPH_MANAGED_KEY].env_added =
-    settings[MORPH_MANAGED_KEY].env_added || [];
-  for (const key of added) {
-    if (!settings[MORPH_MANAGED_KEY].env_added.includes(key)) {
-      settings[MORPH_MANAGED_KEY].env_added.push(key);
-    }
-  }
-  settings[MORPH_MANAGED_KEY].generated_at = new Date().toISOString();
-
-  await saveSettings(targetPath, settings);
-
-  return { added, total: Object.keys(settings.env).length };
-}
-
-/**
- * Remove only morph-spec managed entries from settings.
- * Creates backup before modifying.
- * @param {string} targetPath - Project root directory
- * @returns {Promise<Object>} Summary of what was removed
- */
-export async function resetMorphSettings(targetPath) {
-  const claudeDir = join(targetPath, '.claude');
-  const settingsPath = join(claudeDir, 'settings.local.json');
-
-  if (!existsSync(settingsPath)) {
-    return { removed: false, reason: 'file not found' };
-  }
-
-  const settings = await loadSettings(targetPath);
-  const managed = settings[MORPH_MANAGED_KEY];
-
-  if (!managed) {
-    return { removed: false, reason: 'no _morph_managed section found' };
-  }
-
-  // Backup before modifying
-  const backupPath = settingsPath + '.backup';
-  await copyFile(settingsPath, backupPath);
-
-  // 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 managed env vars
-  if (managed.env_added && settings.env) {
-    for (const key of managed.env_added) {
-      delete settings.env[key];
-    }
-    if (Object.keys(settings.env).length === 0) {
-      delete settings.env;
-    }
-  }
-
-  // Remove managed hooks (v2 format: identified by path pattern)
-  if (settings.hooks) {
-    const morphPattern = /framework\/hooks\/claude-code\//;
-    const oldPattern = /agent-teams\/dispatch\.js/;
-
-    for (const [event, entries] of Object.entries(settings.hooks)) {
-      if (!Array.isArray(entries)) continue;
-
-      settings.hooks[event] = entries.filter(entry => {
-        if (!Array.isArray(entry.hooks)) return true;
-        const nonMorphHooks = entry.hooks.filter(h =>
-          typeof h.command !== 'string' ||
-          (!morphPattern.test(h.command) && !oldPattern.test(h.command))
-        );
-        return nonMorphHooks.length > 0;
-      });
-
-      if (settings.hooks[event].length === 0) {
-        delete settings.hooks[event];
-      }
-    }
-    if (Object.keys(settings.hooks).length === 0) {
-      delete settings.hooks;
-    }
-  }
-
-  // Remove managed MCP servers from .mcp.json (primary location)
-  if (managed.mcps_installed) {
-    const mcpJson = await loadMcpJson(targetPath);
-    if (mcpJson.mcpServers) {
-      for (const mcpName of managed.mcps_installed) {
-        delete mcpJson.mcpServers[mcpName];
-      }
-      if (Object.keys(mcpJson.mcpServers).length === 0) {
-        delete mcpJson.mcpServers;
-      }
-      // Write back (or remove file if empty)
-      if (Object.keys(mcpJson).length === 0) {
-        const mcpJsonPath = join(targetPath, '.mcp.json');
-        if (existsSync(mcpJsonPath)) {
-          const { unlink } = await import('fs/promises');
-          await unlink(mcpJsonPath);
-        }
-      } else {
-        await saveMcpJson(targetPath, mcpJson);
-      }
-    }
-
-    // Also clean legacy entries from settings.local.json
-    if (settings.mcpServers) {
-      for (const mcpName of managed.mcps_installed) {
-        delete settings.mcpServers[mcpName];
-      }
-      if (Object.keys(settings.mcpServers).length === 0) {
-        delete settings.mcpServers;
-      }
-    }
-  }
-
-  // Remove the managed marker
-  delete settings[MORPH_MANAGED_KEY];
-
-  await saveSettings(targetPath, settings);
-
-  return {
-    removed: true,
-    backupPath,
-    permissionsRemoved: managed.permissions_added || [],
-    envRemoved: managed.env_added || [],
-    hooksRemoved: managed.hooks_added || [],
-    mcpsRemoved: managed.mcps_installed || [],
-    previouslyGenerated: managed.generated_at
-  };
-}
-
-/**
- * Install MCP server entries into .mcp.json at the project root.
- * Claude Code reads MCP servers from .mcp.json (not settings.local.json).
- * Tracks installed names in settings.local.json _morph_managed.mcps_installed for safe reset.
- *
- * @param {string} targetPath - Project root directory
- * @param {Object} servers - Map of server name → config { type?, command, args, env? }
- * @returns {Promise<Object>} Summary of changes { added, skipped, total }
- */
-export async function installMcpServers(targetPath, servers) {
-  const mcpJson = await loadMcpJson(targetPath);
-
-  mcpJson.mcpServers = mcpJson.mcpServers || {};
-
-  const added = [];
-  const skipped = [];
-
-  for (const [name, config] of Object.entries(servers)) {
-    if (mcpJson.mcpServers[name]) {
-      skipped.push(name);
-    } else {
-      mcpJson.mcpServers[name] = config;
-      added.push(name);
-    }
-  }
-
-  await saveMcpJson(targetPath, mcpJson);
-
-  // Track in settings.local.json _morph_managed
-  const settings = await loadSettings(targetPath);
-  settings[MORPH_MANAGED_KEY] = settings[MORPH_MANAGED_KEY] || {};
-  settings[MORPH_MANAGED_KEY].mcps_installed =
-    settings[MORPH_MANAGED_KEY].mcps_installed || [];
-  for (const name of added) {
-    if (!settings[MORPH_MANAGED_KEY].mcps_installed.includes(name)) {
-      settings[MORPH_MANAGED_KEY].mcps_installed.push(name);
-    }
-  }
-  settings[MORPH_MANAGED_KEY].generated_at = new Date().toISOString();
-
-  await saveSettings(targetPath, settings);
-
-  return { added, skipped, total: Object.keys(mcpJson.mcpServers).length };
-}
-
-// ============================================================================
-// Helpers
-// ============================================================================
-
-async function loadMcpJson(targetPath) {
-  const mcpJsonPath = join(targetPath, '.mcp.json');
-  try {
-    if (!existsSync(mcpJsonPath)) return {};
-    return JSON.parse(await readFile(mcpJsonPath, 'utf-8'));
-  } catch {
-    return {};
-  }
-}
-
-async function saveMcpJson(targetPath, data) {
-  const mcpJsonPath = join(targetPath, '.mcp.json');
-  await writeFile(mcpJsonPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
-}
-
-async function loadSettings(targetPath) {
-  const settingsPath = join(targetPath, '.claude', 'settings.local.json');
-  try {
-    if (!existsSync(settingsPath)) return {};
-    return JSON.parse(await readFile(settingsPath, 'utf-8'));
-  } catch {
-    return {};
-  }
-}
-
-async function saveSettings(targetPath, settings) {
-  const claudeDir = join(targetPath, '.claude');
-  const settingsPath = join(claudeDir, 'settings.local.json');
-
-  if (!existsSync(claudeDir)) {
-    await mkdir(claudeDir, { recursive: true });
-  }
-
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-}
+/**
+ * Claude Settings Manager
+ *
+ * Extends the original hooks-installer with broader settings management:
+ * permissions, env vars, and managed entry tracking.
+ *
+ * Re-exports installClaudeHooks for backward compatibility.
+ */
+
+import { join } from 'path';
+import { readFile, writeFile, mkdir, copyFile } from 'fs/promises';
+import { existsSync } from 'fs';
+
+const MORPH_MANAGED_KEY = '_morph_managed';
+
+// ============================================================================
+// Re-export from hooks-installer (v2 registry-based)
+// ============================================================================
+
+export { installClaudeHooks, installGlobalStatusline, getHooksVersion } from './hooks-installer.js';
+export { installAgents } from './agents-installer.js';
+
+// ============================================================================
+// Extended settings management
+// ============================================================================
+
+/**
+ * Install permission rules into .claude/settings.local.json
+ * @param {string} targetPath - Project root directory
+ * @param {Array<string>} permissions - Permission patterns to add
+ * @returns {Promise<Object>} Summary of changes
+ */
+export async function installPermissions(targetPath, permissions) {
+  const settings = await loadSettings(targetPath);
+
+  settings.permissions = settings.permissions || [];
+
+  const added = [];
+  for (const perm of permissions) {
+    if (!settings.permissions.includes(perm)) {
+      settings.permissions.push(perm);
+      added.push(perm);
+    }
+  }
+
+  // Track in _morph_managed
+  settings[MORPH_MANAGED_KEY] = settings[MORPH_MANAGED_KEY] || {};
+  settings[MORPH_MANAGED_KEY].permissions_added =
+    settings[MORPH_MANAGED_KEY].permissions_added || [];
+  for (const perm of added) {
+    if (!settings[MORPH_MANAGED_KEY].permissions_added.includes(perm)) {
+      settings[MORPH_MANAGED_KEY].permissions_added.push(perm);
+    }
+  }
+  settings[MORPH_MANAGED_KEY].generated_at = new Date().toISOString();
+
+  await saveSettings(targetPath, settings);
+
+  return { added, total: settings.permissions.length };
+}
+
+/**
+ * Install environment variables into .claude/settings.local.json
+ * @param {string} targetPath - Project root directory
+ * @param {Object} envVars - Key-value pairs to add to env
+ * @returns {Promise<Object>} Summary of changes
+ */
+export async function installEnvVars(targetPath, envVars) {
+  const settings = await loadSettings(targetPath);
+
+  settings.env = settings.env || {};
+
+  const added = [];
+  for (const [key, value] of Object.entries(envVars)) {
+    if (!(key in settings.env)) {
+      settings.env[key] = value;
+      added.push(key);
+    }
+  }
+
+  // Track in _morph_managed
+  settings[MORPH_MANAGED_KEY] = settings[MORPH_MANAGED_KEY] || {};
+  settings[MORPH_MANAGED_KEY].env_added =
+    settings[MORPH_MANAGED_KEY].env_added || [];
+  for (const key of added) {
+    if (!settings[MORPH_MANAGED_KEY].env_added.includes(key)) {
+      settings[MORPH_MANAGED_KEY].env_added.push(key);
+    }
+  }
+  settings[MORPH_MANAGED_KEY].generated_at = new Date().toISOString();
+
+  await saveSettings(targetPath, settings);
+
+  return { added, total: Object.keys(settings.env).length };
+}
+
+/**
+ * Remove only morph-spec managed entries from settings.
+ * Creates backup before modifying.
+ * @param {string} targetPath - Project root directory
+ * @returns {Promise<Object>} Summary of what was removed
+ */
+export async function resetMorphSettings(targetPath) {
+  const claudeDir = join(targetPath, '.claude');
+  const settingsPath = join(claudeDir, 'settings.local.json');
+
+  if (!existsSync(settingsPath)) {
+    return { removed: false, reason: 'file not found' };
+  }
+
+  const settings = await loadSettings(targetPath);
+  const managed = settings[MORPH_MANAGED_KEY];
+
+  if (!managed) {
+    return { removed: false, reason: 'no _morph_managed section found' };
+  }
+
+  // Backup before modifying
+  const backupPath = settingsPath + '.backup';
+  await copyFile(settingsPath, backupPath);
+
+  // 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 managed env vars
+  if (managed.env_added && settings.env) {
+    for (const key of managed.env_added) {
+      delete settings.env[key];
+    }
+    if (Object.keys(settings.env).length === 0) {
+      delete settings.env;
+    }
+  }
+
+  // Remove managed hooks (v2 format: identified by path pattern)
+  if (settings.hooks) {
+    const morphPattern = /framework\/hooks\/claude-code\//;
+    const oldPattern = /agent-teams\/dispatch\.js/;
+
+    for (const [event, entries] of Object.entries(settings.hooks)) {
+      if (!Array.isArray(entries)) continue;
+
+      settings.hooks[event] = entries.filter(entry => {
+        if (!Array.isArray(entry.hooks)) return true;
+        const nonMorphHooks = entry.hooks.filter(h =>
+          typeof h.command !== 'string' ||
+          (!morphPattern.test(h.command) && !oldPattern.test(h.command))
+        );
+        return nonMorphHooks.length > 0;
+      });
+
+      if (settings.hooks[event].length === 0) {
+        delete settings.hooks[event];
+      }
+    }
+    if (Object.keys(settings.hooks).length === 0) {
+      delete settings.hooks;
+    }
+  }
+
+  // Remove managed MCP servers from .mcp.json (primary location)
+  if (managed.mcps_installed) {
+    const mcpJson = await loadMcpJson(targetPath);
+    if (mcpJson.mcpServers) {
+      for (const mcpName of managed.mcps_installed) {
+        delete mcpJson.mcpServers[mcpName];
+      }
+      if (Object.keys(mcpJson.mcpServers).length === 0) {
+        delete mcpJson.mcpServers;
+      }
+      // Write back (or remove file if empty)
+      if (Object.keys(mcpJson).length === 0) {
+        const mcpJsonPath = join(targetPath, '.mcp.json');
+        if (existsSync(mcpJsonPath)) {
+          const { unlink } = await import('fs/promises');
+          await unlink(mcpJsonPath);
+        }
+      } else {
+        await saveMcpJson(targetPath, mcpJson);
+      }
+    }
+
+    // Also clean legacy entries from settings.local.json
+    if (settings.mcpServers) {
+      for (const mcpName of managed.mcps_installed) {
+        delete settings.mcpServers[mcpName];
+      }
+      if (Object.keys(settings.mcpServers).length === 0) {
+        delete settings.mcpServers;
+      }
+    }
+  }
+
+  // Remove the managed marker
+  delete settings[MORPH_MANAGED_KEY];
+
+  await saveSettings(targetPath, settings);
+
+  return {
+    removed: true,
+    backupPath,
+    permissionsRemoved: managed.permissions_added || [],
+    envRemoved: managed.env_added || [],
+    hooksRemoved: managed.hooks_added || [],
+    mcpsRemoved: managed.mcps_installed || [],
+    previouslyGenerated: managed.generated_at
+  };
+}
+
+/**
+ * Install MCP server entries into .mcp.json at the project root.
+ * Claude Code reads MCP servers from .mcp.json (not settings.local.json).
+ * Tracks installed names in settings.local.json _morph_managed.mcps_installed for safe reset.
+ *
+ * @param {string} targetPath - Project root directory
+ * @param {Object} servers - Map of server name → config { type?, command, args, env? }
+ * @returns {Promise<Object>} Summary of changes { added, skipped, total }
+ */
+export async function installMcpServers(targetPath, servers) {
+  const mcpJson = await loadMcpJson(targetPath);
+
+  mcpJson.mcpServers = mcpJson.mcpServers || {};
+
+  const added = [];
+  const skipped = [];
+
+  for (const [name, config] of Object.entries(servers)) {
+    if (mcpJson.mcpServers[name]) {
+      skipped.push(name);
+    } else {
+      mcpJson.mcpServers[name] = config;
+      added.push(name);
+    }
+  }
+
+  await saveMcpJson(targetPath, mcpJson);
+
+  // Track in settings.local.json _morph_managed
+  const settings = await loadSettings(targetPath);
+  settings[MORPH_MANAGED_KEY] = settings[MORPH_MANAGED_KEY] || {};
+  settings[MORPH_MANAGED_KEY].mcps_installed =
+    settings[MORPH_MANAGED_KEY].mcps_installed || [];
+  for (const name of added) {
+    if (!settings[MORPH_MANAGED_KEY].mcps_installed.includes(name)) {
+      settings[MORPH_MANAGED_KEY].mcps_installed.push(name);
+    }
+  }
+  settings[MORPH_MANAGED_KEY].generated_at = new Date().toISOString();
+
+  await saveSettings(targetPath, settings);
+
+  return { added, skipped, total: Object.keys(mcpJson.mcpServers).length };
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+async function loadMcpJson(targetPath) {
+  const mcpJsonPath = join(targetPath, '.mcp.json');
+  try {
+    if (!existsSync(mcpJsonPath)) return {};
+    return JSON.parse(await readFile(mcpJsonPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+async function saveMcpJson(targetPath, data) {
+  const mcpJsonPath = join(targetPath, '.mcp.json');
+  await writeFile(mcpJsonPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+async function loadSettings(targetPath) {
+  const settingsPath = join(targetPath, '.claude', 'settings.local.json');
+  try {
+    if (!existsSync(settingsPath)) return {};
+    return JSON.parse(await readFile(settingsPath, 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+async function saveSettings(targetPath, settings) {
+  const claudeDir = join(targetPath, '.claude');
+  const settingsPath = join(claudeDir, 'settings.local.json');
+
+  if (!existsSync(claudeDir)) {
+    await mkdir(claudeDir, { recursive: true });
+  }
+
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+}

package/src/utils/hooks-installer.js

@@ -15,7 +15,7 @@ import { homedir } from 'os';
 import { execSync } from 'child_process';
 
 /** Current hooks schema version — bump when hook definitions change */
-const HOOKS_VERSION = '3.0.0';
+const HOOKS_VERSION = '3.1.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -103,7 +103,9 @@ const MORPH_HOOKS = [
   },
 
   // === PostToolUse: Write|Edit — typecheck (debounced, silent on success) +
-  // tasks.json schema guard (validate-and-warn; status enum, effort enum) ===
+  // tasks.json schema guard (validate-and-warn; status enum, effort enum) +
+  // trace auto-generation (tasks.json write → .morph/traces/, replaces the
+  // manual trace-writing step the skills used to carry) ===
   {
     event: 'PostToolUse',
     matcher: 'Write|Edit',
@@ -116,6 +118,11 @@ const MORPH_HOOKS = [
         type: 'command',
         command: 'node framework/hooks/claude-code/core/tasks-json-guard.js',
         timeout: 3000
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/trace-autogen.js',
+        timeout: 3000
       }
     ]
   },
@@ -153,13 +160,34 @@ const MORPH_HOOKS = [
     }]
   },
 
-  // === Stop — build check + session snapshot ===
+  // === Stop — build check + session snapshot + dispatch-report guard ===
+  // subagent-report-guard blocks (once) a dispatched sub-agent stopping
+  // without SendMessage — clause 1 of the dispatch protocol. In the
+  // orchestrator's session it is inert (marker never in a user message).
   {
     event: 'Stop',
     matcher: null,
+    hooks: [
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/validate-completion.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/core/subagent-report-guard.js',
+        timeout: 5000
+      }
+    ]
+  },
+
+  // === SubagentStop — dispatch-report guard for Task-tool subagents ===
+  {
+    event: 'SubagentStop',
+    matcher: null,
     hooks: [{
       type: 'command',
-      command: 'node framework/hooks/claude-code/core/validate-completion.js'
+      command: 'node framework/hooks/claude-code/core/subagent-report-guard.js',
+      timeout: 5000
     }]
   }
 ];