@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

package/src/utils/agents-installer.js

@@ -0,0 +1,206 @@
+/**
+ * Agents Installer
+ *
+ * Converts MORPH-SPEC tier-1 and tier-2 agents from agents.json into
+ * native Claude Code subagent markdown files in .claude/agents/.
+ *
+ * Each file has YAML frontmatter (name, description, model, tools,
+ * maxTurns, skills, memory) followed by the agent's spawn prompt as the body.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'path';
+
+/**
+ * Installs tier-1 and tier-2 morph agents as native Claude Code subagents
+ * in .claude/agents/ with YAML frontmatter.
+ *
+ * @param {string} projectDir - Target project directory
+ * @param {string} frameworkDir - Path to morph-spec framework/ directory
+ */
+export async function installAgents(projectDir, frameworkDir = 'framework') {
+  const agentsJsonPath = join(frameworkDir, 'agents.json');
+  const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
+
+  // Support both object map and array formats
+  const agentsRaw = agentsJson.agents ?? agentsJson;
+  const agents = Array.isArray(agentsRaw)
+    ? agentsRaw
+    : Object.entries(agentsRaw)
+        .filter(([key]) => !key.startsWith('_comment'))
+        .map(([id, data]) => ({ id, ...data }));
+
+  const targetDir = join(projectDir, '.claude', 'agents');
+  mkdirSync(targetDir, { recursive: true });
+
+  const eligible = agents.filter(a => a.tier === 1 || a.tier === 2);
+
+  for (const agent of eligible) {
+    const slug = agent.id ?? agent.name?.toLowerCase().replace(/\s+/g, '-');
+    const filename = `morph-${slug}.md`;
+    const targetPath = join(targetDir, filename);
+
+    const description = buildDescription(agent);
+    const body = buildBody(agent);
+
+    const frontmatter = buildFrontmatter(agent, description);
+    const content = `---\n${frontmatter}---\n\n${body}\n`;
+    writeFileSync(targetPath, content, 'utf-8');
+  }
+}
+
+/**
+ * Tier-based defaults for Claude Code subagent frontmatter fields.
+ *
+ * Tier 1 (Orchestrators): can spawn subagents via Task tool, 30 turns, project memory.
+ * Tier 2 (Domain Leaders): coordinate specialists but do not spawn subagents, 20 turns, local memory.
+ */
+const TIER_DEFAULTS = {
+  1: {
+    model: 'inherit',
+    tools: 'Read, Grep, Glob, Bash, Task',
+    maxTurns: 30,
+    skills: ['morph-checklist'],
+    memory: 'project',
+  },
+  2: {
+    model: 'inherit',
+    tools: 'Read, Grep, Glob, Bash',
+    maxTurns: 20,
+    skills: ['morph-checklist'],
+    memory: 'local',
+  },
+};
+
+/**
+ * Builds the YAML frontmatter content (without --- delimiters) for an agent file.
+ * Returns a string ending with a blank line.
+ *
+ * @param {object} agent - Agent definition from agents.json
+ * @param {string} description - Pre-built description string
+ * @returns {string}
+ */
+function buildFrontmatter(agent, description) {
+  const defaults = TIER_DEFAULTS[agent.tier] ?? TIER_DEFAULTS[2];
+  const name = agent.title ?? agent.name;
+  const skillsList = defaults.skills.map(s => `  - ${s}`).join('\n');
+
+  return [
+    `name: ${name}`,
+    `description: ${description}`,
+    `model: ${defaults.model}`,
+    `tools: ${defaults.tools}`,
+    `maxTurns: ${defaults.maxTurns}`,
+    `skills:`,
+    skillsList,
+    `memory: ${defaults.memory}`,
+    '',
+  ].join('\n');
+}
+
+function buildDescription(agent) {
+  const base = agent.teammate?.role ?? `Handles ${(agent.domains ?? []).join(', ')}`;
+  // Truncate to 200 chars for settings display
+  return base.length > 200 ? base.slice(0, 197) + '...' : base;
+}
+
+function buildBody(agent) {
+  const lines = [];
+  if (agent.teammate?.spawn_prompt) {
+    lines.push(agent.teammate.spawn_prompt);
+  } else {
+    lines.push(`You are the ${agent.title} agent in the MORPH-SPEC framework.`);
+    if (agent.domains?.length) {
+      lines.push(`\n## Domains\n${agent.domains.map(d => `- ${d}`).join('\n')}`);
+    }
+  }
+  if (agent.standards?.length) {
+    lines.push(`\n## Standards to Reference\n${agent.standards.map(s => `- ${s}`).join('\n')}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Parses YAML frontmatter from a skill markdown file.
+ * Handles both inline values and YAML block scalars (>).
+ *
+ * @param {string} rawContent - Raw file content
+ * @returns {{ name: string|null, description: string|null, allowedTools: string, body: string }}
+ */
+export function parseSkillFile(rawContent) {
+  // Normalize CRLF to LF for consistent parsing on Windows
+  const content = rawContent.replace(/\r\n/g, '\n');
+  const match = content.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) return { name: null, description: null, allowedTools: 'Read, Write, Edit, Bash, Glob, Grep', body: rawContent };
+
+  const fm = match[1];
+  const body = match[2];
+
+  const name = (fm.match(/^name:\s*(.+)$/m) ?? [])[1]?.trim() ?? null;
+  const allowedTools = (fm.match(/^allowed-tools:\s*(.+)$/m) ?? [])[1]?.trim() ?? 'Read, Write, Edit, Bash, Glob, Grep';
+
+  let description = null;
+  const blockMatch = fm.match(/^description:\s*>\s*\n((?:[ \t]+.*\n?)*)/m);
+  if (blockMatch) {
+    description = blockMatch[1].trim().replace(/\s+/g, ' ');
+  } else {
+    const inlineMatch = fm.match(/^description:\s*(.+)$/m);
+    if (inlineMatch) description = inlineMatch[1].trim();
+  }
+
+  return { name, description, allowedTools, body };
+}
+
+/**
+ * Recursively collects all .md skill files from a directory, excluding README.md.
+ *
+ * @param {string} dir - Directory to walk
+ * @returns {string[]} Absolute paths to skill .md files
+ */
+export function collectSkillFiles(dir) {
+  const results = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...collectSkillFiles(fullPath));
+    } else if (entry.name.endsWith('.md') && entry.name !== 'README.md') {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+/**
+ * Installs domain agent files as native Claude Code subagents
+ * in .claude/agents/ with memory:project, model:sonnet, maxTurns:20.
+ *
+ * @param {string} projectDir - Target project directory
+ * @param {string} frameworkDir - Path to morph-spec framework/ directory
+ */
+export async function installDomainAgents(projectDir, frameworkDir = 'framework') {
+  const domainsDir = join(frameworkDir, 'agents');
+  if (!existsSync(domainsDir)) return;
+
+  const targetDir = join(projectDir, '.claude', 'agents');
+  mkdirSync(targetDir, { recursive: true });
+
+  for (const filePath of collectSkillFiles(domainsDir)) {
+    const raw = readFileSync(filePath, 'utf-8');
+    const { name, description, allowedTools, body } = parseSkillFile(raw);
+    if (!name) continue;
+
+    const desc = description ?? `MORPH-SPEC domain agent: ${name}`;
+    const frontmatter = [
+      `name: ${name}`,
+      `description: ${desc}`,
+      `model: sonnet`,
+      `tools: ${allowedTools}`,
+      `maxTurns: 20`,
+      `memory: project`,
+      '',
+    ].join('\n');
+
+    const targetPath = join(targetDir, `morph-domain-${name}.md`);
+    writeFileSync(targetPath, `---\n${frontmatter}---\n\n${body.trimStart()}`, 'utf-8');
+  }
+}

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

@@ -0,0 +1,258 @@
+/**
+ * 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
+  if (managed.mcps_installed && 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 .claude/settings.local.json
+ * Tracks installed MCPs in _morph_managed.mcps_installed for safe reset.
+ *
+ * @param {string} targetPath - Project root directory
+ * @param {Object} servers - Map of server name → config { command, args, env? }
+ * @returns {Promise<Object>} Summary of changes { added, skipped, total }
+ */
+export async function installMcpServers(targetPath, servers) {
+  const settings = await loadSettings(targetPath);
+
+  settings.mcpServers = settings.mcpServers || {};
+
+  const added = [];
+  const skipped = [];
+
+  for (const [name, config] of Object.entries(servers)) {
+    if (settings.mcpServers[name]) {
+      skipped.push(name);
+    } else {
+      settings.mcpServers[name] = config;
+      added.push(name);
+    }
+  }
+
+  // Track in _morph_managed
+  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(settings.mcpServers).length };
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+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/file-copier.js

@@ -134,7 +134,7 @@ export async function updateGitignore(projectPath) {
   const morphRules = [
     '',
     '# MORPH-SPEC',
-    '.morph/templates/',
+    '.morph/framework/templates/',
     '.claude/settings.local.json',
     ''
   ];