@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -1,167 +1,167 @@
-/**
- * Hook Executor — Agent Teams hook validation
- *
- * Executes validation hooks triggered by Claude Code agent-teams events:
- *   TeammateIdle, TaskCompleted, PhaseAdvanced
- *
- * Reads agents.json to find validators with matching hook_triggers,
- * then runs each validator's checks against the current project state.
- *
- * @module hook-executor
- */
-
-import { readFileSync, existsSync } from 'fs';
-import { join } from 'path';
-
-// ============================================================================
-// Loaders
-// ============================================================================
-
-function loadAgents(projectPath) {
-  const agentPaths = [
-    join(projectPath, '.morph/framework/agents.json'),
-  ];
-
-  const allAgents = {};
-  for (const agentPath of agentPaths) {
-    if (existsSync(agentPath)) {
-      try {
-        const data = JSON.parse(readFileSync(agentPath, 'utf8'));
-        Object.assign(allAgents, data.agents || {});
-      } catch (e) { /* skip malformed files */ }
-    }
-  }
-  return allAgents;
-}
-
-function loadStateFeature(projectPath, featureName) {
-  const statePath = join(projectPath, '.morph/state.json');
-  if (!existsSync(statePath)) return null;
-
-  const state = JSON.parse(readFileSync(statePath, 'utf8'));
-  const features = state.features;
-
-  // Support both object format { featureName: {...} } and array format [{name, ...}]
-  if (Array.isArray(features)) {
-    return features.find(f => f.name === featureName) || null;
-  }
-  return features[featureName] || null;
-}
-
-// ============================================================================
-// Main Executor
-// ============================================================================
-
-/**
- * Execute agent-teams hook validation
- * @param {string} projectPath - Absolute path to project root
- * @param {string} featureName - Feature to validate
- * @param {string} hookEvent - Event name (TeammateIdle, TaskCompleted, PhaseAdvanced)
- * @param {Object} [opts]
- * @param {boolean} [opts.dryRun=false] - Identify validators without running them
- * @param {boolean} [opts.verbose=true] - Print results to console
- * @returns {Promise<Object>} { passed, blocked, errors, warnings }
- */
-export async function executeHook(projectPath, featureName, hookEvent, opts = {}) {
-  const { dryRun = false } = opts;
-
-  // Load feature state
-  const feature = loadStateFeature(projectPath, featureName);
-  if (!feature) {
-    return {
-      passed: false,
-      blocked: true,
-      errors: [`Feature not found: ${featureName}`],
-      warnings: []
-    };
-  }
-
-  // Load all available agents
-  const agents = loadAgents(projectPath);
-
-  // Filter: agents that run in hooks AND trigger on this event
-  const hookValidators = Object.entries(agents)
-    .filter(([, agent]) =>
-      agent.relationships?.runs_in === 'hooks' &&
-      Array.isArray(agent.relationships?.hook_triggers) &&
-      agent.relationships.hook_triggers.includes(hookEvent)
-    )
-    .map(([agentId, agent]) => ({ agentId, ...agent }));
-
-  // No validators configured for this event, or dry run — pass immediately
-  if (hookValidators.length === 0 || dryRun) {
-    return { passed: true, blocked: false, errors: [], warnings: [] };
-  }
-
-  // Run validators
-  // In production, each validator would execute its actual checks.
-  // This implementation returns pass since real validation requires external tooling.
-  const errors = [];
-  const warnings = [];
-
-  const passed = errors.length === 0;
-  const blocked = errors.some(e => typeof e === 'object' && e.blocksOnFail !== false);
-
-  return { passed, blocked, errors, warnings };
-}
-
-// ============================================================================
-// Formatter
-// ============================================================================
-
-/**
- * Format hook execution results as a human-readable string
- * @param {Object} results - Result from executeHook
- * @param {string} hookEvent - Event name
- * @returns {string} Formatted output
- */
-export function formatHookResults(results, hookEvent) {
-  const { passed, blocked, errors = [], warnings = [] } = results;
-  const lines = [];
-
-  if (!passed && errors.length > 0) {
-    lines.push(`❌ Hook: ${hookEvent}`);
-    lines.push('FAILED');
-    lines.push('ERRORS (blocking):');
-
-    for (const err of errors) {
-      if (err.issues && Array.isArray(err.issues)) {
-        for (const issue of err.issues) {
-          lines.push(`  ${issue.message}`);
-          if (issue.file && issue.line !== undefined) {
-            lines.push(`  ${issue.file}:${issue.line}`);
-          }
-        }
-      } else if (err.error) {
-        lines.push(`  Error: ${err.error}`);
-      } else if (typeof err === 'string') {
-        lines.push(`  ${err}`);
-      }
-    }
-
-    if (blocked) {
-      lines.push('BLOCKED');
-    }
-  } else if (warnings.length === 0) {
-    lines.push(`✅ Hook: ${hookEvent}`);
-    lines.push('All validators passed');
-  }
-
-  if (warnings.length > 0) {
-    lines.push(`⚠️ Hook: ${hookEvent}`);
-    lines.push('WARNINGS (non-blocking):');
-
-    for (const warn of warnings) {
-      if (warn.issues && Array.isArray(warn.issues)) {
-        for (const issue of warn.issues) {
-          lines.push(`  ${issue.message}`);
-          if (issue.file && issue.line !== undefined) {
-            lines.push(`  ${issue.file}:${issue.line}`);
-          }
-        }
-      }
-    }
-  }
-
-  return lines.join('\n');
-}
+/**
+ * Hook Executor — Agent Teams hook validation
+ *
+ * Executes validation hooks triggered by Claude Code agent-teams events:
+ *   TeammateIdle, TaskCompleted, PhaseAdvanced
+ *
+ * Reads agents.json to find validators with matching hook_triggers,
+ * then runs each validator's checks against the current project state.
+ *
+ * @module hook-executor
+ */
+
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+// ============================================================================
+// Loaders
+// ============================================================================
+
+function loadAgents(projectPath) {
+  const agentPaths = [
+    join(projectPath, '.morph/framework/agents.json'),
+  ];
+
+  const allAgents = {};
+  for (const agentPath of agentPaths) {
+    if (existsSync(agentPath)) {
+      try {
+        const data = JSON.parse(readFileSync(agentPath, 'utf8'));
+        Object.assign(allAgents, data.agents || {});
+      } catch (e) { /* skip malformed files */ }
+    }
+  }
+  return allAgents;
+}
+
+function loadStateFeature(projectPath, featureName) {
+  const statePath = join(projectPath, '.morph/state.json');
+  if (!existsSync(statePath)) return null;
+
+  const state = JSON.parse(readFileSync(statePath, 'utf8'));
+  const features = state.features;
+
+  // Support both object format { featureName: {...} } and array format [{name, ...}]
+  if (Array.isArray(features)) {
+    return features.find(f => f.name === featureName) || null;
+  }
+  return features[featureName] || null;
+}
+
+// ============================================================================
+// Main Executor
+// ============================================================================
+
+/**
+ * Execute agent-teams hook validation
+ * @param {string} projectPath - Absolute path to project root
+ * @param {string} featureName - Feature to validate
+ * @param {string} hookEvent - Event name (TeammateIdle, TaskCompleted, PhaseAdvanced)
+ * @param {Object} [opts]
+ * @param {boolean} [opts.dryRun=false] - Identify validators without running them
+ * @param {boolean} [opts.verbose=true] - Print results to console
+ * @returns {Promise<Object>} { passed, blocked, errors, warnings }
+ */
+export async function executeHook(projectPath, featureName, hookEvent, opts = {}) {
+  const { dryRun = false } = opts;
+
+  // Load feature state
+  const feature = loadStateFeature(projectPath, featureName);
+  if (!feature) {
+    return {
+      passed: false,
+      blocked: true,
+      errors: [`Feature not found: ${featureName}`],
+      warnings: []
+    };
+  }
+
+  // Load all available agents
+  const agents = loadAgents(projectPath);
+
+  // Filter: agents that run in hooks AND trigger on this event
+  const hookValidators = Object.entries(agents)
+    .filter(([, agent]) =>
+      agent.relationships?.runs_in === 'hooks' &&
+      Array.isArray(agent.relationships?.hook_triggers) &&
+      agent.relationships.hook_triggers.includes(hookEvent)
+    )
+    .map(([agentId, agent]) => ({ agentId, ...agent }));
+
+  // No validators configured for this event, or dry run — pass immediately
+  if (hookValidators.length === 0 || dryRun) {
+    return { passed: true, blocked: false, errors: [], warnings: [] };
+  }
+
+  // Run validators
+  // In production, each validator would execute its actual checks.
+  // This implementation returns pass since real validation requires external tooling.
+  const errors = [];
+  const warnings = [];
+
+  const passed = errors.length === 0;
+  const blocked = errors.some(e => typeof e === 'object' && e.blocksOnFail !== false);
+
+  return { passed, blocked, errors, warnings };
+}
+
+// ============================================================================
+// Formatter
+// ============================================================================
+
+/**
+ * Format hook execution results as a human-readable string
+ * @param {Object} results - Result from executeHook
+ * @param {string} hookEvent - Event name
+ * @returns {string} Formatted output
+ */
+export function formatHookResults(results, hookEvent) {
+  const { passed, blocked, errors = [], warnings = [] } = results;
+  const lines = [];
+
+  if (!passed && errors.length > 0) {
+    lines.push(`❌ Hook: ${hookEvent}`);
+    lines.push('FAILED');
+    lines.push('ERRORS (blocking):');
+
+    for (const err of errors) {
+      if (err.issues && Array.isArray(err.issues)) {
+        for (const issue of err.issues) {
+          lines.push(`  ${issue.message}`);
+          if (issue.file && issue.line !== undefined) {
+            lines.push(`  ${issue.file}:${issue.line}`);
+          }
+        }
+      } else if (err.error) {
+        lines.push(`  Error: ${err.error}`);
+      } else if (typeof err === 'string') {
+        lines.push(`  ${err}`);
+      }
+    }
+
+    if (blocked) {
+      lines.push('BLOCKED');
+    }
+  } else if (warnings.length === 0) {
+    lines.push(`✅ Hook: ${hookEvent}`);
+    lines.push('All validators passed');
+  }
+
+  if (warnings.length > 0) {
+    lines.push(`⚠️ Hook: ${hookEvent}`);
+    lines.push('WARNINGS (non-blocking):');
+
+    for (const warn of warnings) {
+      if (warn.issues && Array.isArray(warn.issues)) {
+        for (const issue of warn.issues) {
+          lines.push(`  ${issue.message}`);
+          if (issue.file && issue.line !== undefined) {
+            lines.push(`  ${issue.file}:${issue.line}`);
+          }
+        }
+      }
+    }
+  }
+
+  return lines.join('\n');
+}

package/src/lib/installers/effects.js

@@ -0,0 +1,193 @@
+/**
+ * effects.js — o coletor de efeitos ÚNICO do caminho de instalação/atualização.
+ *
+ * A propriedade que faz o `--dry-run` ser honesto está numa frase:
+ *
+ *   > **o caminho real também emite.**
+ *
+ * Em modo normal cada verbo EXECUTA e registra; em `dryRun`, só registra. O
+ * resumo impresso ao fim de uma execução real sai de `list()`, não de
+ * contadores paralelos. A consequência é o ponto: um ponto de emissão
+ * esquecido some das DUAS saídas ao mesmo tempo, e o resumo de uma execução
+ * real fica visivelmente incompleto — o defeito aparece sem sequer usar o
+ * `--dry-run`.
+ *
+ * **Não há segunda travessia.** Nenhum filtro, walker ou lista de payload é
+ * reimplementado aqui. Os filtros que decidem o que instalar
+ * (`shouldInstallSkill`, `agentEligible`, `shouldInstall`) já são puros e
+ * continuam sendo os únicos. O anti-exemplar tem nome e mora neste
+ * repositório: `checkAgentsDrift` funciona como preditor porque re-deriva o
+ * conjunto elegível por conta própria e porque os dois lados chamam o mesmo
+ * renderer puro. Estender essa forma para 9 payloads + hooks + merge de
+ * settings + gitignore + índice do git é reimplementar o instalador inteiro e
+ * depender de disciplina humana para mantê-los sincronizados.
+ *
+ * **Os verbos são SÍNCRONOS de propósito.** Metade dos instaladores que eles
+ * atravessam (`installSkills`, `installAgents`, `installRulesForStack`) é
+ * síncrona; um coletor assíncrono obrigaria a tornar `installRulesForStack`
+ * async e a mudar a assinatura que `setup-infra`, `init` e os testes já usam.
+ *
+ * **O registro é a IDENTIDADE do efeito, nunca o conteúdo.** `writeFile` grava
+ * `{ verb, target }`, não os bytes: `installClaudeHooks` carimba um
+ * `generated_at` a cada execução, e comparar conteúdo faria o canário de
+ * igualdade dry × real reprovar por causa do relógio.
+ */
+
+import fs from 'fs-extra';
+import { spawnSync } from 'node:child_process';
+import { dirname } from 'node:path';
+
+/**
+ * @typedef {Object} Effect
+ * @property {string} verb   - ensureDir | remove | copyDir | copyFile | writeFile | writeJson | mergeJson | spawn | gitIndex
+ * @property {string} target - o caminho (ou comando) sobre o qual o efeito age
+ * @property {string} [from] - origem, para os verbos de cópia
+ * @property {string} [detail] - qualificador estável (argumentos do spawn, operação do git)
+ */
+
+/**
+ * Cria um coletor de efeitos.
+ *
+ * @param {{ dryRun?: boolean }} [options]
+ * @returns {{
+ *   dryRun: boolean,
+ *   ensureDir: (path: string) => void,
+ *   remove: (path: string) => void,
+ *   copyDir: (from: string, to: string) => void,
+ *   copyFile: (from: string, to: string) => void,
+ *   writeFile: (path: string, content: string) => void,
+ *   writeJson: (path: string, data: object) => void,
+ *   mergeJson: (path: string, patch: object) => void,
+ *   spawn: (cmd: string, args: string[], options?: object) => object|null,
+ *   gitIndex: (op: string, path: string, options?: object) => boolean,
+ *   list: () => Effect[],
+ * }}
+ */
+export function createEffects({ dryRun = false } = {}) {
+  /** @type {Effect[]} */
+  const effects = [];
+
+  const record = (verb, target, extra = {}) => {
+    const effect = { verb, target };
+    if (extra.from !== undefined) effect.from = extra.from;
+    if (extra.detail !== undefined) effect.detail = extra.detail;
+    if (extra.args !== undefined) effect.args = extra.args;
+    effects.push(effect);
+    return effect;
+  };
+
+  return {
+    dryRun,
+
+    ensureDir(path) {
+      record('ensureDir', path);
+      if (!dryRun) fs.ensureDirSync(path);
+    },
+
+    remove(path) {
+      record('remove', path);
+      if (!dryRun) fs.removeSync(path);
+    },
+
+    copyDir(from, to, options = {}) {
+      record('copyDir', to, { from });
+      if (!dryRun) fs.copySync(from, to, { overwrite: true, errorOnExist: false, ...options });
+    },
+
+    copyFile(from, to) {
+      record('copyFile', to, { from });
+      if (!dryRun) {
+        fs.ensureDirSync(dirname(to));
+        fs.copySync(from, to, { overwrite: true });
+      }
+    },
+
+    writeFile(path, content) {
+      record('writeFile', path);
+      if (!dryRun) {
+        fs.ensureDirSync(dirname(path));
+        fs.writeFileSync(path, content, 'utf8');
+      }
+    },
+
+    writeJson(path, data) {
+      record('writeJson', path);
+      if (!dryRun) {
+        fs.ensureDirSync(dirname(path));
+        fs.writeJsonSync(path, data, { spaces: 2 });
+      }
+    },
+
+    /**
+     * Leitura + fusão rasa + escrita, como UM efeito.
+     *
+     * A leitura acontece nos dois modos (ler não muda nada); só a escrita é
+     * suprimida em dry. É assim que `~/.claude/settings.json` — um arquivo do
+     * usuário, FORA do projeto — é atualizado sem que o dry o toque.
+     */
+    mergeJson(path, patch) {
+      record('mergeJson', path);
+      if (dryRun) return;
+      let current = {};
+      try {
+        if (fs.existsSync(path)) current = fs.readJsonSync(path);
+      } catch {
+        current = {};
+      }
+      fs.ensureDirSync(dirname(path));
+      fs.writeJsonSync(path, { ...current, ...patch }, { spaces: 2 });
+    },
+
+    /**
+     * @param {string} cmd
+     * @param {string[]} args
+     * @param {{ cwd?: string, dryRunArgs?: string[] }} [options]
+     *   `dryRunArgs` é a variante SÓ-LEITURA do mesmo comando (por exemplo
+     *   `--check`). Em dry ela é executada no lugar; sem ela, nada roda.
+     *   O REGISTRO é o mesmo nos dois modos: o efeito previsto é o comando
+     *   real, não a sua sonda.
+     */
+    spawn(cmd, args = [], options = {}) {
+      // `args` viaja no registro ALÉM do `detail` legível. O `detail` é para
+      // humano; quebrá-lo por espaço para descobrir onde o spawn escreve é o
+      // bug que um caminho como `R:\Polymorphism Tech\...` produz em silêncio,
+      // e que o relatório mostrou pondo um efeito do PACOTE da CLI no grupo
+      // "no projeto".
+      record('spawn', cmd, { detail: args.join(' '), args: [...args] });
+      const { cwd, dryRunArgs } = options;
+      if (dryRun) {
+        if (!dryRunArgs) return null;
+        return spawnSync(cmd, dryRunArgs, { cwd, encoding: 'utf8' });
+      }
+      return spawnSync(cmd, args, { cwd, encoding: 'utf8' });
+    },
+
+    /**
+     * Mutação do índice do git (`git rm --cached`, etc.). A SONDA que decide
+     * se há o que fazer fica fora daqui de propósito: sondar é ler, e ler
+     * acontece nos dois modos.
+     */
+    gitIndex(op, path, options = {}) {
+      record('gitIndex', path, { detail: op });
+      if (dryRun) return true;
+      const result = spawnSync('git', [...op.split(' '), path], {
+        cwd: options.cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'],
+      });
+      return result.status === 0;
+    },
+
+    list() {
+      return effects.map((e) => ({ ...e }));
+    },
+  };
+}
+
+/**
+ * Coletor no-op-de-registro para chamadores que não passam um: executa
+ * normalmente e registra numa lista descartada. Existe para que assinaturas
+ * novas de `installSkills`/`installAgents`/`installRulesForStack` continuem
+ * funcionando para `setup-infra` e `init` sem mudança de comportamento.
+ */
+export function realEffects() {
+  return createEffects({ dryRun: false });
+}