@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/src/utils/agents-installer.js

@@ -21,9 +21,10 @@
  * Evaluator) are assumed by Claude itself per MORPH.md, not as separate agents.
  */
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, unlinkSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'path';
 import { shouldInstall } from '../lib/stack-filter.js';
+import { realEffects } from '../lib/installers/effects.js';
 
 /** Default tool scope for domain personas (override per agent via agents.json `tools`). */
 export const DEFAULT_AGENT_TOOLS = 'Read, Write, Edit, Bash, Glob, Grep';
@@ -79,10 +80,12 @@ const MANAGED_HEADER =
  * @param {string} frameworkDir - Path to morph-spec framework/ directory
  * @param {object} options
  * @param {string[]} [options.projectTags=[]] - Stack tags from config (e.g. ['dotnet', 'nextjs'])
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
+ *   Coletor de efeitos; o default executa e registra numa lista descartada.
  * @returns {Promise<{ installed: number }>}
  */
 export async function installAgents(projectDir, frameworkDir = 'framework', options = {}) {
-  const { projectTags = [] } = options;
+  const { projectTags = [], fx = realEffects() } = options;
 
   const agentsJsonPath = join(frameworkDir, 'agents.json');
   const agentsJson = JSON.parse(readFileSync(agentsJsonPath, 'utf-8'));
@@ -93,7 +96,7 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     .map(([id, data]) => ({ id, ...data }));
 
   const targetDir = join(projectDir, '.claude', 'agents');
-  mkdirSync(targetDir, { recursive: true });
+  fx.ensureDir(targetDir);
 
   const knownMcpIds = loadKnownMcpIds(frameworkDir);
 
@@ -111,7 +114,7 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     const filename = `morph-${agent.id}.md`;
     const targetPath = join(targetDir, filename);
 
-    writeFileSync(targetPath, renderAgentMd(agent, knownMcpIds), 'utf-8');
+    fx.writeFile(targetPath, renderAgentMd(agent, knownMcpIds));
     installedFilenames.add(filename);
     installedAgents.push({
       id: agent.id,
@@ -122,10 +125,17 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     installed++;
   }
 
-  // Cleanup orphan morph-* files filtered out by stack
-  for (const file of readdirSync(targetDir)) {
-    if (allPossible.has(file) && !installedFilenames.has(file)) {
-      unlinkSync(join(targetDir, file));
+  // Cleanup orphan morph-* files filtered out by stack.
+  //
+  // Calado em `dryRun` pelo mesmo motivo do laço gêmeo em skills-installer.js
+  // (D6): numa execução real do `update` este diretório acabou de ser apagado
+  // inteiro por `cleanFrameworkDirs()`, então o laço nunca remove nada. Num
+  // dry ingênuo ele veria o diretório antigo e preveria remoções inexistentes.
+  if (!fx.dryRun) {
+    for (const file of readdirSync(targetDir)) {
+      if (allPossible.has(file) && !installedFilenames.has(file)) {
+        fx.remove(join(targetDir, file));
+      }
     }
   }
 

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

@@ -8,7 +8,8 @@
  * The root CLAUDE.md belongs to the USER — morph-spec only adds its import.
  */
 
-import { pathExists, readFile, writeFile } from './file-copier.js';
+import { pathExists, readFile } from './file-copier.js';
+import { realEffects } from '../lib/installers/effects.js';
 
 const MORPH_IMPORT = '@.claude/CLAUDE.md';
 const MORPH_MARKER = 'MORPH-SPEC';
@@ -24,11 +25,15 @@ const MORPH_MARKER = 'MORPH-SPEC';
  * 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.
  * @returns {Promise<'created'|'migrated'|'injected'|'already-present'>}
  */
-export async function injectMorphImport(claudeMdPath) {
+export async function injectMorphImport(claudeMdPath, fx = realEffects()) {
   if (!await pathExists(claudeMdPath)) {
-    await writeFile(claudeMdPath, `# Project\n\n${MORPH_IMPORT}\n`);
+    fx.writeFile(claudeMdPath, `# Project\n\n${MORPH_IMPORT}\n`);
     return 'created';
   }
 
@@ -39,13 +44,13 @@ export async function injectMorphImport(claudeMdPath) {
   }
 
   if (isMorphOnly(content)) {
-    await writeFile(claudeMdPath, `# Project\n\n${MORPH_IMPORT}\n`);
+    fx.writeFile(claudeMdPath, `# Project\n\n${MORPH_IMPORT}\n`);
     return 'migrated';
   }
 
   // User has their own content — append the import section
   const separator = content.endsWith('\n') ? '\n' : '\n\n';
-  await writeFile(claudeMdPath, `${content}${separator}## MORPH-SPEC\n\n${MORPH_IMPORT}\n`);
+  fx.writeFile(claudeMdPath, `${content}${separator}## MORPH-SPEC\n\n${MORPH_IMPORT}\n`);
   return 'injected';
 }
 

package/src/utils/file-copier.js

@@ -1,6 +1,8 @@
 import fs from 'fs-extra';
 import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import { WORKTREE_DIR_NAMES } from '../lib/worktree/dirs.js';
+import { realEffects } from '../lib/installers/effects.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const frameworkRoot = join(__dirname, '..', '..');
@@ -137,12 +139,12 @@ export async function createDirectoryLink(target, link) {
   }
 }
 
-export async function updateGitignore(projectPath) {
-  const gitignorePath = join(projectPath, '.gitignore');
-
-  const morphRules = [
-    '',
-    '# MORPH-SPEC',
+/**
+ * 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
@@ -165,19 +167,29 @@ export async function updateGitignore(projectPath) {
     '.claude/agents/',
     '.claude/CLAUDE.md',
     '.claude/settings.local.json',
-    '/worktrees/',
-    // Legacy name (pre-C1). 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.
-    '/.worktrees/',
+    // 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.
+    ...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');
+
+  const morphRules = ['', '# MORPH-SPEC', ...MORPH_GITIGNORE_ENTRIES, ''];
 
   let content = '';
   let hasMorphSection = false;
@@ -223,7 +235,7 @@ export async function updateGitignore(projectPath) {
     content += morphRules.join('\n');
   }
 
-  await writeFile(gitignorePath, content);
+  fx.writeFile(gitignorePath, content);
 }
 
 /**
@@ -243,7 +255,7 @@ export async function updateGitignore(projectPath) {
  *
  * @param {string} projectPath
  */
-export async function ensureGitattributes(projectPath) {
+export async function ensureGitattributes(projectPath, fx = realEffects()) {
   const gitattributesPath = join(projectPath, '.gitattributes');
   const MARKER = '# MORPH-SPEC';
   const morphBlock = [
@@ -262,7 +274,7 @@ export async function ensureGitattributes(projectPath) {
     content += '\n';
   }
   content += `${morphBlock.join('\n')}\n`;
-  await writeFile(gitattributesPath, content);
+  fx.writeFile(gitattributesPath, content);
 }
 
 /**

package/src/utils/hooks-installer.js

@@ -9,10 +9,11 @@
  */
 
 import { join, dirname } from 'path';
-import { readFile, writeFile, mkdir, copyFile } from 'fs/promises';
+import { readFile } from 'fs/promises';
 import { existsSync, chmodSync, readdirSync } from 'fs';
 import { homedir } from 'os';
 import { execSync } from 'child_process';
+import { realEffects } from '../lib/installers/effects.js';
 
 /**
  * Current hooks schema version — bump when hook definitions change.
@@ -27,8 +28,15 @@ import { execSync } from 'child_process';
  * (`copyDirectory` defaults to `overwrite: true`), so the bump does not gate
  * delivery — it makes `morph-spec update` report the change honestly instead
  * of "already current".
+ *
+ * 3.8.0 (worktree governance) registers Claude Code's WorktreeCreate /
+ * WorktreeRemove events — the native `claude -w` / EnterWorktree / Agent
+ * isolation worktree is replaced by `morph-spec worktree setup|provision`
+ * (junctions, port block, primary-root landing) and its removal routed
+ * through the safe `worktree remove --if-clean` — and appends
+ * block-raw-worktree-add to the PreToolUse:Bash chain.
  */
-const HOOKS_VERSION = '3.7.0';
+const HOOKS_VERSION = '3.8.0';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -137,14 +145,50 @@ const MORPH_HOOKS = [
   // block-destructive-worktree-removal (dynamic: scans the target for reparse
   // points), so the cheap check short-circuits the filesystem walk. The second
   // one is the only defense against the raw-removal vector that does not depend
-  // on someone having read MORPH.md. ===
+  // on someone having read MORPH.md. block-raw-worktree-add is its way-IN
+  // counterpart (a raw `git worktree add` builds a tree with no junctions, no
+  // ports, no identity) — static, so it costs nothing after the first two.
+  // worktree-env-inject is LAST: it rewrites launcher commands (updatedInput)
+  // with the worktree's port block, and a command a previous link blocked must
+  // never be rewritten. Block-first-wins guarantees it never sees one.
   {
     event: 'PreToolUse',
     matcher: 'Bash',
     hooks: [{
       type: 'command',
       command: 'node framework/hooks/claude-code/core/chain.js',
-      args: ['pre-bash-denylist', 'block-destructive-worktree-removal']
+      args: ['pre-bash-denylist', 'block-destructive-worktree-removal', 'block-raw-worktree-add', 'worktree-env-inject']
+    }]
+  },
+
+  // === WorktreeCreate — REPLACES Claude Code's native `git worktree add` for
+  // `claude -w`, the EnterWorktree tool and `Agent isolation:"worktree"`
+  // (measured: all three fire it). The hook prints the created path as its
+  // last stdout line; a non-zero exit fails the creation. No matcher exists
+  // for this event. 120s: it spawns the morph-spec CLI (setup or provision),
+  // which runs git, links infra, allocates ports and materializes state. ===
+  {
+    event: 'WorktreeCreate',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/worktree-create.js',
+      timeout: 120000
+    }]
+  },
+
+  // === WorktreeRemove — routes Claude Code's own cleanup through
+  // `morph-spec worktree remove --target --if-clean` (junctions dropped BEFORE
+  // git touches the tree; a dirty tree is left alone). Output ignored, always
+  // exit 0. Secondary net: in headless runs the event was observed not to
+  // fire — block-destructive-worktree-removal remains the primary defense. ===
+  {
+    event: 'WorktreeRemove',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/core/worktree-remove.js',
+      timeout: 60000
     }]
   },
 
@@ -237,9 +281,14 @@ const MORPH_HOOKS = [
  * - Tracks installed version via _morph_managed.hooks_version
  *
  * @param {string} targetPath - Project root directory
+ * @param {object} [options]
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
+ *   Coletor de efeitos. Esta função é o seam mais barato do caminho de update:
+ *   o objeto de settings INTEIRO já é montado em memória e há UMA escrita, no
+ *   fim. Previsão e execução percorrem a mesma montagem.
  * @returns {Promise<{ installed: number, updated: boolean }>}
  */
-export async function installClaudeHooks(targetPath) {
+export async function installClaudeHooks(targetPath, { fx = realEffects() } = {}) {
   const claudeDir = join(targetPath, '.claude');
   const settingsPath = join(claudeDir, 'settings.local.json');
 
@@ -366,11 +415,9 @@ export async function installClaudeHooks(targetPath) {
   settings._morph_managed.generated_at = new Date().toISOString();
 
   // Ensure .claude directory exists
-  if (!existsSync(claudeDir)) {
-    await mkdir(claudeDir, { recursive: true });
-  }
+  fx.ensureDir(claudeDir);
 
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  fx.writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n');
   return { installed, updated: !alreadyCurrent };
 }
 
@@ -487,19 +534,24 @@ function resolvePythonForStatusline() {
  *
  * @param {string} hooksSourceDir - Path to framework/hooks/claude-code/
  * @param {string} [globalClaudeDirOverride] - Override ~/.claude/ (for testing)
+ * @param {object} [options]
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
+ *   Coletor de efeitos. Estes são os efeitos FORA do projeto — o relatório do
+ *   `--dry-run` é obrigado a nomeá-los separadamente, porque ninguém os
+ *   adivinha da palavra "update".
  * @returns {Promise<{ installed: boolean, globalDir: string }>}
  */
-export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOverride = null) {
+export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOverride = null, { fx = realEffects() } = {}) {
   const globalDir = globalClaudeDirOverride || join(homedir(), '.claude');
-  await mkdir(globalDir, { recursive: true });
+  fx.ensureDir(globalDir);
 
   // Copy statusline scripts to ~/.claude/
   const scripts = ['statusline.sh', 'statusline.py'];
   for (const fname of scripts) {
     const src = join(hooksSourceDir, fname);
     if (existsSync(src)) {
-      await copyFile(src, join(globalDir, fname));
-      if (process.platform !== 'win32') {
+      fx.copyFile(src, join(globalDir, fname));
+      if (process.platform !== 'win32' && !fx.dryRun) {
         try { chmodSync(join(globalDir, fname), 0o755); } catch { /* non-critical */ }
       }
     }
@@ -507,14 +559,6 @@ export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOve
 
   // Register statusLine in ~/.claude/settings.json (global user settings)
   const settingsPath = join(globalDir, 'settings.json');
-  let settings = {};
-  if (existsSync(settingsPath)) {
-    try {
-      settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
-    } catch {
-      settings = {};
-    }
-  }
 
   // On Windows, Claude Code cannot execute .sh files directly — call Python instead.
   const statuslineCommand = process.platform === 'win32'
@@ -526,14 +570,16 @@ export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOve
   // `↻` countdown to the 5h rate-limit reset — the only widget that moves on
   // its own — sits frozen through a long turn. Everything else is event-driven
   // and would be fine without this.
-  settings.statusLine = {
-    type: 'command',
-    command: statuslineCommand,
-    padding: 2,
-    refreshInterval: 10
-  };
-
-  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  // Fusão rasa: só `statusLine` é do morph-spec; tudo o mais no
+  // `~/.claude/settings.json` é do usuário e sobrevive intocado.
+  fx.mergeJson(settingsPath, {
+    statusLine: {
+      type: 'command',
+      command: statuslineCommand,
+      padding: 2,
+      refreshInterval: 10
+    }
+  });
   return { installed: true, globalDir };
 }