@polymorphism-tech/morph-spec 9.0.0 → 9.2.0

package/src/utils/claude-md-injector.js

@@ -1,13 +1,3 @@
-/**
- * claude-md-injector.js
- *
- * Manages the root CLAUDE.md file in client projects.
- * Instead of overwriting the user's CLAUDE.md, injects an @import line
- * that references the morph-spec managed .claude/CLAUDE.md.
- *
- * The root CLAUDE.md belongs to the USER — morph-spec only adds its import.
- */
-
 import { pathExists, readFile } from './file-copier.js';
 import { realEffects } from '../lib/installers/effects.js';
 
@@ -15,20 +5,7 @@ const MORPH_IMPORT = '@.claude/CLAUDE.md';
 const MORPH_MARKER = 'MORPH-SPEC';
 
 /**
- * Injects the morph-spec @import into the root CLAUDE.md.
- *
- * Three scenarios:
- * 1. No CLAUDE.md exists → create minimal file with the import
- * 2. Existing morph-only CLAUDE.md (old overwrite) → replace with minimal + import
- * 3. Existing user CLAUDE.md → append import section at the end
- *
- * Idempotent — does nothing if the import already exists.
- *
- * @param {string} claudeMdPath - Absolute path to root CLAUDE.md
- * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [fx]
- *   Coletor de efeitos; o default executa e registra numa lista descartada.
- *   A DECISÃO (criar / migrar / anexar / nada) sai de uma LEITURA, que
- *   acontece igual nos dois modos — por isso previsão e execução concordam.
+ * Leaves the user's root CLAUDE.md in place and only adds the morph-spec @import.
  * @returns {Promise<'created'|'migrated'|'injected'|'already-present'>}
  */
 export async function injectMorphImport(claudeMdPath, fx = realEffects()) {
@@ -48,20 +25,14 @@ export async function injectMorphImport(claudeMdPath, fx = realEffects()) {
     return 'migrated';
   }
 
-  // User has their own content — append the import section
   const separator = content.endsWith('\n') ? '\n' : '\n\n';
   fx.writeFile(claudeMdPath, `${content}${separator}## MORPH-SPEC\n\n${MORPH_IMPORT}\n`);
   return 'injected';
 }
 
-/**
- * Checks if CLAUDE.md contains ONLY morph-spec content (old overwrite pattern).
- * Heuristic: contains MORPH-SPEC marker AND no substantial user content.
- */
 function isMorphOnly(content) {
   if (!content.includes(MORPH_MARKER)) return false;
 
-  // Strip morph-spec boilerplate markers and check if anything meaningful remains
   const stripped = content
     .replace(/# MORPH-SPEC Runtime Instructions/g, '')
     .replace(/by Polymorphism Tech[^\n]*/g, '')
@@ -80,13 +51,6 @@ function isMorphOnly(content) {
   return stripped.length < 50;
 }
 
-/**
- * Checks if the root CLAUDE.md has the morph-spec import.
- * Used by doctor.js for health checks.
- *
- * @param {string} claudeMdPath - Absolute path to root CLAUDE.md
- * @returns {Promise<'ok'|'missing'|'missing-import'>}
- */
 export async function checkClaudeMdImport(claudeMdPath) {
   if (!await pathExists(claudeMdPath)) return 'missing';
   const content = await readFile(claudeMdPath);

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

@@ -1,35 +1,12 @@
-/**
- * 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 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);
 
@@ -43,7 +20,6 @@ export async function installEnvVars(targetPath, envVars) {
     }
   }
 
-  // Track in _morph_managed
   settings[MORPH_MANAGED_KEY] = settings[MORPH_MANAGED_KEY] || {};
   settings[MORPH_MANAGED_KEY].env_added =
     settings[MORPH_MANAGED_KEY].env_added || [];
@@ -59,12 +35,6 @@ export async function installEnvVars(targetPath, envVars) {
   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');
@@ -80,11 +50,9 @@ export async function resetMorphSettings(targetPath) {
     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)
@@ -94,7 +62,6 @@ export async function resetMorphSettings(targetPath) {
     }
   }
 
-  // Remove managed env vars
   if (managed.env_added && settings.env) {
     for (const key of managed.env_added) {
       delete settings.env[key];
@@ -104,7 +71,6 @@ export async function resetMorphSettings(targetPath) {
     }
   }
 
-  // Remove managed hooks (v2 format: identified by path pattern)
   if (settings.hooks) {
     const morphPattern = /framework\/hooks\/claude-code\//;
     const oldPattern = /agent-teams\/dispatch\.js/;
@@ -130,7 +96,6 @@ export async function resetMorphSettings(targetPath) {
     }
   }
 
-  // Remove managed MCP servers from .mcp.json (primary location)
   if (managed.mcps_installed) {
     const mcpJson = await loadMcpJson(targetPath);
     if (mcpJson.mcpServers) {
@@ -140,7 +105,6 @@ export async function resetMorphSettings(targetPath) {
       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)) {
@@ -152,7 +116,6 @@ export async function resetMorphSettings(targetPath) {
       }
     }
 
-    // Also clean legacy entries from settings.local.json
     if (settings.mcpServers) {
       for (const mcpName of managed.mcps_installed) {
         delete settings.mcpServers[mcpName];
@@ -163,7 +126,6 @@ export async function resetMorphSettings(targetPath) {
     }
   }
 
-  // Remove the managed marker
   delete settings[MORPH_MANAGED_KEY];
 
   await saveSettings(targetPath, settings);
@@ -179,15 +141,7 @@ export async function resetMorphSettings(targetPath) {
   };
 }
 
-/**
- * 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 }
- */
+// Claude Code reads MCP servers from .mcp.json, not settings.local.json.
 export async function installMcpServers(targetPath, servers) {
   const mcpJson = await loadMcpJson(targetPath);
 
@@ -207,7 +161,6 @@ export async function installMcpServers(targetPath, servers) {
 
   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 =
@@ -224,10 +177,6 @@ export async function installMcpServers(targetPath, servers) {
   return { added, skipped, total: Object.keys(mcpJson.mcpServers).length };
 }
 
-// ============================================================================
-// Helpers
-// ============================================================================
-
 async function loadMcpJson(targetPath) {
   const mcpJsonPath = join(targetPath, '.mcp.json');
   try {

package/src/utils/file-copier.js

@@ -39,10 +39,7 @@ export async function pathExists(path) {
 }
 
 export async function readJson(path) {
-  // BOM-tolerant: PowerShell 5.1's `Out-File -Encoding utf8` writes UTF-8
-  // WITH BOM, and JSON.parse rejects it. A hand-edited config.json on Windows
-  // would then silently fall back to empty project tags (fail-open reads),
-  // installing only universal personas. Strip the BOM before parsing.
+  // PowerShell 5.1's `Out-File -Encoding utf8` writes a BOM that JSON.parse rejects.
   const raw = await fs.readFile(path, 'utf-8');
   return JSON.parse(raw.replace(/^/, ''));
 }
@@ -69,18 +66,7 @@ export async function readFile(path) {
   return fs.readFile(path, 'utf8');
 }
 
-/**
- * Create a link to a file or directory with platform-aware fallbacks.
- *
- * For files: hard link → symlink → copy
- *   Hard links work on Windows without admin (same NTFS volume).
- * For dirs: delegates to createDirectoryLink (junction on Windows).
- *
- * @param {string} target - Path to the original file/folder
- * @param {string} link - Path where the link should be created
- * @param {string} type - 'file' or 'dir'
- * @returns {Promise<'hardlink' | 'symlink' | 'junction' | 'copy'>}
- */
+// Hard link first: it needs no admin on Windows (same NTFS volume).
 export async function createSymlink(target, link, type = 'file') {
   await fs.ensureDir(dirname(link));
 
@@ -88,7 +74,6 @@ export async function createSymlink(target, link, type = 'file') {
     return createDirectoryLink(target, link);
   }
 
-  // File linking: hard link first (no admin on Windows), then symlink, then copy
   try {
     await fs.link(target, link);
     return 'hardlink';
@@ -103,24 +88,15 @@ export async function createSymlink(target, link, type = 'file') {
   }
 }
 
-/**
- * Create a directory link (junction on Windows, symlink on other platforms)
- * with fallback to directory copy if linking fails.
- * @param {string} target - Path to the original directory
- * @param {string} link - Path where the link should be created
- * @returns {Promise<'junction' | 'symlink' | 'copy'>} - How the link was created
- */
 export async function createDirectoryLink(target, link) {
   await fs.ensureDir(dirname(link));
 
-  // Remove existing link/directory before recreating
   if (await pathExists(link)) {
     await fs.remove(link);
   }
 
   if (process.platform === 'win32') {
-    // Junction on Windows — does NOT require admin privileges.
-    // Skip ensureSymlink('dir') fallback: it also needs admin on Windows.
+    // A junction needs no admin; ensureSymlink('dir') would.
     try {
       await fs.symlink(target, link, 'junction');
       return 'junction';
@@ -139,16 +115,8 @@ export async function createDirectoryLink(target, link) {
   }
 }
 
-/**
- * The morph-owned block of the installed .gitignore. Exported so the worktree
- * container canary (test/lib/worktree/dirs.test.js) can prove both names are
- * covered without rendering a file.
- */
 export const MORPH_GITIGNORE_ENTRIES = [
-    // Derivable, per-machine state index — rebuilt from the committed
-    // .morph/features/{feature}/feature.json files. Never commit it: doing so
-    // sweeps every feature's accumulated diffs into one commit. The feature
-    // state that matters travels inside each feature folder (which IS committed).
+    // Rebuilt from the committed feature.json files; committing it sweeps every feature into one commit.
     '.morph/state.json',
     '.morph/state.json.tmp.*',
     '.morph/state.json.lock/',
@@ -156,9 +124,6 @@ export const MORPH_GITIGNORE_ENTRIES = [
     '.morph/memory/',
     '.morph/plans/',
     '.morph/analytics/',
-    // Per-instance activity/session logs (activity-logger.js). Each worktree
-    // writes its own — committing this guarantees a merge conflict between
-    // feature branches.
     '.morph/logs/',
     '.claude/commands/',
     '.claude/rules/',
@@ -166,25 +131,13 @@ export const MORPH_GITIGNORE_ENTRIES = [
     '.claude/agents/',
     '.claude/CLAUDE.md',
     '.claude/settings.local.json',
-    // Both container names, anchored at the root. The legacy name (pre-C1) is
-    // kept so a project that already has `.worktrees/` on disk does not
-    // suddenly see it as untracked dirt — which would also make `finish`'s
-    // clean-root check refuse.
+    // The legacy name stays so an existing `.worktrees/` is not dirt that makes `finish` refuse.
     ...WORKTREE_DIR_NAMES.map((d) => `/${d}/`),
     '.playwright-mcp/',
     'docs/superpowers/',
-    // Grafo de codebase — artefato derivado, reconstruído pelo hook do
-    // graphify a cada commit. Committá-lo faria de todo commit um diff de
-    // megabytes de JSON gerado.
     'graphify-out/',
 ];
 
-/**
- * @param {string} projectPath
- * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [fx]
- *   Coletor de efeitos. O default executa e registra numa lista descartada, de
- *   modo que todo chamador antigo (`setup-infra`, `init`) siga idêntico.
- */
 export async function updateGitignore(projectPath, fx = realEffects()) {
   const gitignorePath = join(projectPath, '.gitignore');
 
@@ -193,7 +146,6 @@ export async function updateGitignore(projectPath, fx = realEffects()) {
   let content = '';
   let hasMorphSection = false;
 
-  // Read existing .gitignore if it exists
   if (await pathExists(gitignorePath)) {
     content = await readFile(gitignorePath);
     hasMorphSection = content.includes('# MORPH-SPEC');
@@ -201,12 +153,10 @@ export async function updateGitignore(projectPath, fx = realEffects()) {
   const original = content;
   const eol = content.includes('\r\n') ? '\r\n' : '\n';
 
-  // If MORPH section already exists, check if rules are up to date
   if (hasMorphSection) {
     const lines = content.split(/\r?\n/);
     const morphStartIndex = lines.findIndex(line => line.trim() === '# MORPH-SPEC');
 
-    // Find the end of MORPH section (next empty line or section header)
     let morphEndIndex = morphStartIndex + 1;
     while (morphEndIndex < lines.length &&
            lines[morphEndIndex].trim() !== '' &&
@@ -214,22 +164,18 @@ export async function updateGitignore(projectPath, fx = realEffects()) {
       morphEndIndex++;
     }
 
-    // Extract current MORPH rules
     const currentMorphRules = lines.slice(morphStartIndex, morphEndIndex + 1);
-    const expectedMorphRules = morphRules.slice(1, -1); // Remove empty lines from comparison
+    const expectedMorphRules = morphRules.slice(1, -1);
 
-    // Check if all expected rules are present
     const missingRules = expectedMorphRules.filter(rule =>
       rule.startsWith('#') || !currentMorphRules.some(line => line.trim() === rule)
     );
 
     if (missingRules.length > 0) {
-      // Update the section with all rules
       lines.splice(morphStartIndex, morphEndIndex - morphStartIndex, ...morphRules.slice(1, -1));
       content = lines.join(eol);
     }
   } else {
-    // Add MORPH section
     if (content && !content.endsWith('\n')) {
       content += eol;
     }
@@ -247,12 +193,7 @@ const ignoredDir = (line) => line.trim()
   .replace(/^\[(\w)(\w)\]/, (_, a, b) => (a.toLowerCase() === b.toLowerCase() ? a : `[${a}${b}]`))
   .toLowerCase();
 
-/**
- * Appends `bin/` and `obj/` to the project `.gitignore` when no line already
- * ignores them. Never rewrites an existing line.
- *
- * @returns {string[]} the entries added
- */
+/** Never rewrites an existing line. @returns {string[]} the entries added */
 export function ensureDotnetBuildIgnores(projectPath) {
   const gitignorePath = join(projectPath, '.gitignore');
   const content = fs.existsSync(gitignorePath) ? fs.readFileSync(gitignorePath, 'utf8') : '';
@@ -266,23 +207,8 @@ export function ensureDotnetBuildIgnores(projectPath) {
   return missing;
 }
 
-/**
- * Install a MORPH-SPEC .gitattributes section pinning morph state files to LF.
- *
- * Rationale: `saveState`/`atomicWriteJson` write `.morph` JSON with LF. On
- * Windows with `core.autocrlf=true` (the Git-for-Windows default) and no
- * attribute pinning EOL, Git flags EVERY rewritten feature.json as modified
- * even when the content is byte-identical. That silently breaks the whole-root
- * clean-check in `morph-spec finish` as soon as a project has more
- * than one feature — precisely the multi-instance / parallel-worktree flow,
- * where one `saveState` touches sibling feature.json files and marks them dirty.
- * This mirrors the .gitattributes this framework repo already carries for its
- * own generated files. Scoped to `.morph/**` so it never imposes an EOL policy
- * on the user's own source. Idempotent and non-destructive: appends a marked
- * block, leaving any pre-existing .gitattributes rules untouched.
- *
- * @param {string} projectPath
- */
+// Without the LF pin, Windows autocrlf marks every rewritten feature.json dirty
+// and breaks the clean-root check of `finish`. Scoped to `.morph/**` only.
 export async function ensureGitattributes(projectPath, fx = realEffects()) {
   const gitattributesPath = join(projectPath, '.gitattributes');
   const MARKER = '# MORPH-SPEC';
@@ -297,7 +223,7 @@ export async function ensureGitattributes(projectPath, fx = realEffects()) {
   let content = '';
   if (await pathExists(gitattributesPath)) {
     content = await readFile(gitattributesPath);
-    if (content.includes(MARKER)) return; // already installed — idempotent
+    if (content.includes(MARKER)) return;
     if (content && !content.endsWith('\n')) content += '\n';
     content += '\n';
   }
@@ -305,17 +231,7 @@ export async function ensureGitattributes(projectPath, fx = realEffects()) {
   fx.writeFile(gitattributesPath, content);
 }
 
-/**
- * Garante entradas no .claudeignore, criando o arquivo se preciso.
- *
- * Existe por causa do grafo: um `graph.json` de 12 MB reescrito a cada commit
- * invalidaria o prompt cache do Claude Code em toda sessão. Append idempotente
- * por linha — o que o usuário já tem nunca é reescrito.
- *
- * @param {string} projectPath
- * @param {string[]} entries
- * @returns {Promise<{added: string[], path: string}>}
- */
+/** Idempotent per-line append; never rewrites what the user already has. */
 export async function ensureClaudeignore(projectPath, entries) {
   const claudeignorePath = join(projectPath, '.claudeignore');
   const MARKER = '# MORPH-SPEC';