@polymorphism-tech/morph-spec 8.47.0 → 9.1.0

package/src/scripts/setup-infra.js

@@ -1,15 +1,3 @@
-/**
- * setup-infra.js
- *
- * Headless infrastructure setup for MORPH-SPEC.
- * Extracted from init.js (steps 1-10) so it can run as
- * `morph-spec setup-infra` without interactive prompts or stack detection.
- *
- * Usage:
- *   import { setupInfra } from './setup-infra.js';
- *   await setupInfra('/path/to/project');
- */
-
 import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { execSync } from 'child_process';
@@ -53,14 +41,7 @@ async function installRequiredPlugins(log, exec) {
   }
 }
 
-/**
- * Install only stack-matching rules from rulesSrc to rulesDest.
- * Also removes orphan rules in rulesDest that are no longer in the install set.
- *
- * @param {string} rulesSrc - Source rules directory (framework/rules/)
- * @param {string} rulesDest - Destination rules directory (.claude/rules/)
- * @param {string[]} projectTags - Stack tags from config (e.g., ['dotnet', 'blazor'])
- */
+/** Also removes orphan rules in rulesDest that are no longer in the install set. */
 export function installRulesForStack(rulesSrc, rulesDest, projectTags, fx = realEffects()) {
   const sourceFiles = readdirSync(rulesSrc).filter(f => f.endsWith('.md'));
   const installed = new Set();
@@ -74,9 +55,7 @@ export function installRulesForStack(rulesSrc, rulesDest, projectTags, fx = real
     }
   }
 
-  // Cleanup orphans — calado em `dryRun` pelo mesmo motivo dos laços gêmeos em
-  // skills-installer.js e agents-installer.js (D6): `cleanFrameworkDirs()` já
-  // apagou `.claude/rules/` inteiro antes de este código rodar de verdade.
+  // Calado em `dryRun`: `cleanFrameworkDirs()` já apagou `.claude/rules/` inteiro antes da execução real.
   if (!fx.dryRun) {
     for (const file of readdirSync(rulesDest).filter(f => f.endsWith('.md'))) {
       if (!installed.has(file)) {
@@ -88,11 +67,7 @@ export function installRulesForStack(rulesSrc, rulesDest, projectTags, fx = real
   return { installed: installed.size };
 }
 
-/**
- * Slash commands filtered by `stacks:` frontmatter. Clean-slate like the
- * skills: removes only a framework command that the stack filtered out, never
- * a command the user wrote into `.claude/commands/`.
- */
+/** Clean-slate: removes only a framework command the stack filtered out, never one the user wrote. */
 export function installCommandsForStack(commandsSrc, commandsDest, projectTags, fx = realEffects()) {
   const sourceFiles = readdirSync(commandsSrc).filter(f => f.endsWith('.md'));
   let installed = 0;
@@ -108,22 +83,13 @@ export function installCommandsForStack(commandsSrc, commandsDest, projectTags,
   return { installed };
 }
 
-/**
- * Re-install only stack-aware assets (commands, rules, skills, agents) using current config.json.
- * Skips infrastructure steps (dirs, framework copy, hooks).
- *
- * @param {string} targetPath - Absolute path to the target project directory
- * @param {Function} log - Logging function
- * @returns {{ agentCounts: object, domainCounts: object, projectTags: string[] }}
- */
 async function installStackAwareAssets(targetPath, log) {
   const configPath = join(targetPath, '.morph', 'config', 'config.json');
   let projectTags = [];
   if (await pathExists(configPath)) {
     try {
-      // BOM-tolerant: a config.json hand-edited on Windows (PS 5.1 Out-File)
-      // carries a UTF-8 BOM; without stripping it this parse fails silently
-      // and only universal personas get installed.
+      // BOM-tolerant: a config.json written by PS 5.1 Out-File carries a BOM, and a failed parse
+      // here silently installs only the universal personas.
       const config = JSON.parse(readFileSync(configPath, 'utf-8').replace(/^/, ''));
       projectTags = getProjectTags(config);
     } catch { /* ignore malformed config */ }
@@ -159,20 +125,8 @@ async function installStackAwareAssets(targetPath, log) {
 }
 
 /**
- * Rewrite the managed personas block in .claude/CLAUDE.md with the agents
- * ACTUALLY installed (derived list — never a hand-written promise).
- * No markers / no file → no-op (fail-open).
- * Exported so `morph-spec update` derives the same block on upgrades.
- *
- * @param {string} claudeMdPath - Absolute path to the installed .claude/CLAUDE.md
- * @param {Array<{ name: string, title: string, domains: string[] }>} agents
- * @param {object} [options]
- * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
- * @param {string} [options.readFrom] - De onde LER o conteúdo-base.
- *   Num `--dry-run` o arquivo de destino ainda não recebeu a cópia que o passo
- *   anterior previu, então ler o destino diria "sem marcadores" e o efeito de
- *   escrita sumiria da previsão — divergindo da execução real. Lendo a MESMA
- *   origem que seria copiada, previsão e execução decidem igual.
+ * No markers or no file is a no-op. `readFrom`: on `--dry-run` the destination has not received
+ * the predicted copy yet, so read the copy's source and let preview and real run decide alike.
  */
 export async function updateClaudeMdAgentsBlock(claudeMdPath, agents = [], options = {}) {
   const { fx = realEffects(), readFrom = claudeMdPath } = options;
@@ -195,20 +149,8 @@ export async function updateClaudeMdAgentsBlock(claudeMdPath, agents = [], optio
 }
 
 /**
- * Installs MORPH-SPEC infrastructure into the target project directory.
- * Headless — no prompts, no spinner (suppressed when MORPH_QUIET=1), no stack detection.
- *
- * @param {string} targetPath - Absolute path to the target project directory
- * @param {object} options
- * @param {Function} options._exec - exec function (for testing)
- * @param {Function} [options._detectGraphifyVersion] - graphify probe (for testing: the
- *   step-18b branches differ with graphify installed or not, and CI has no Python)
- * @param {Function} [options._log] - log sink (for testing: replaces stdout, which the test
- *   runner itself reports through — stubbing it swallows test results)
- * @param {boolean} options.reinstall - If true, only re-install stack-aware assets (rules, skills, agents)
- * @param {boolean} options.force - Bypass the secondary-worktree guard (see below). Callers
- *   (e.g. `initCommand`) that already performed their own equivalent check pass this so the
- *   check isn't redundantly re-applied here.
+ * Headless install: no prompts, no stack detection. `force` skips the secondary-worktree guard
+ * for callers that already ran an equivalent check.
  */
 export async function setupInfra(targetPath, {
   _exec = execSync, _detectGraphifyVersion = null, _log = null, reinstall = false, force = false,
@@ -220,16 +162,9 @@ export async function setupInfra(targetPath, {
     else if (!quiet) process.stdout.write(msg + '\n');
   }
 
-  // Guard: refuse a FULL install from inside a secondary (linked) worktree.
-  // `.claude/` and `.morph/framework/` are junctions back to the primary root
-  // there, but `.morph/config/`, `.morph/context/`, `.morph/checkpoints/`,
-  // `.morph/memory/`, `.morph/archive/` and `.morph/state.json` are NOT — a
-  // full install would scaffold a second, disconnected config/state tree
-  // inside the worktree. `reinstall` mode is exempt: it only touches
-  // .claude/* stack-aware assets, which are the junctioned (safe) subset.
-  // `resolvePrimaryRoot` fails open to `targetPath` itself outside a git repo
-  // (or on any git error), so non-git projects and the primary root are
-  // never blocked.
+  // In a linked worktree only .claude/ and .morph/framework/ are junctions to the root: a full
+  // install would scaffold a second, disconnected config/state tree. `reinstall` touches only
+  // the junctioned subset.
   if (!reinstall && !force) {
     const target = resolve(targetPath).replace(/\\/g, '/');
     const root = resolvePrimaryRoot(targetPath);
@@ -241,12 +176,9 @@ export async function setupInfra(targetPath, {
     }
   }
 
-  // --- Reinstall mode: only re-install stack-aware assets ---
   if (reinstall) {
     log('setup-infra (reinstall): re-installing stack-aware assets...');
     const { agentCounts, domainCounts } = await installStackAwareAssets(targetPath, log);
-    // Keep the derived personas list in .claude/CLAUDE.md in sync with what
-    // was actually (re)installed.
     await updateClaudeMdAgentsBlock(join(targetPath, '.claude', 'CLAUDE.md'), agentCounts?.agents ?? []);
     log('setup-infra (reinstall): complete.');
     return {
@@ -258,17 +190,14 @@ export async function setupInfra(targetPath, {
     };
   }
 
-  // --- 0. Install required Claude Code plugins ---
   await installRequiredPlugins(log, _exec);
 
-  // --- 1. Inject @import into root CLAUDE.md (preserves user content) ---
   log('Step 1: Setting up CLAUDE.md...');
   const claudeMdSrc = join(FRAMEWORK_DIR, 'CLAUDE.md');
   const claudeMdDest = join(targetPath, 'CLAUDE.md');
   const importResult = await injectMorphImport(claudeMdDest);
   log(`  ✓ Root CLAUDE.md: ${importResult}`);
 
-  // --- 2. Create .morph directory structure ---
   log('Step 2: Creating .morph structure...');
   const morphPath = join(targetPath, '.morph');
   const configDir = join(morphPath, 'config');
@@ -287,7 +216,6 @@ export async function setupInfra(targetPath, {
   await ensureDir(memoryDir);
   await ensureDir(archiveDir);
 
-  // --- 3. Write minimal config.json (only if not exists) ---
   log('Step 3: Writing config.json...');
   const configPath = join(configDir, 'config.json');
   if (!(await pathExists(configPath))) {
@@ -303,7 +231,6 @@ export async function setupInfra(targetPath, {
     await writeJson(configPath, config);
   }
 
-  // --- 4. Write placeholder context/README.md (only if not exists) ---
   log('Step 4: Writing context/README.md...');
   const contextReadmePath = join(contextDir, 'README.md');
   if (!(await pathExists(contextReadmePath))) {
@@ -312,27 +239,9 @@ export async function setupInfra(targetPath, {
     await writeFile(contextReadmePath, readmeContent);
   }
 
-  // --- 5. framework/templates is intentionally NOT copied to
-  // .morph/framework/templates anymore (R3 perf plan, Task 2). Template
-  // resolution is layered (template-registry.js, architecture-scanner.js
-  // resolveTemplatePath): a project-local .morph/framework/templates/{path}
-  // is still checked FIRST as an explicit override, then falls back to the
-  // npm package's own framework/templates/ — which is what every template
-  // actually rendered from until now anyway, since the installed copy was
-  // never read as anything but that override. Pre-populating it was a
-  // byte-for-byte redundant 348KB copy on every install/update.
   log('Step 5: Skipping framework templates copy (resolved from package; local override still supported)...');
-  // Cópia legada de instalação pré-R3: se existir, ela SOMBREIA os templates
-  // do pacote (override-first). `update` sempre reconcilia porque
-  // checkProjectOutdated() já leu a versão anterior do projeto antes de
-  // chamar update. Aqui (init/setup-infra) fazemos o mesmo QUANDO a mesma
-  // fonte está disponível: getProjectMorphVersion() lê .morph/.morphversion
-  // — o MESMO arquivo/campo que checkProjectOutdated().current usa — e essa
-  // leitura acontece ANTES do Passo 17 (saveProjectMorphVersion) sobrescrever
-  // esse arquivo com a versão atual, então "versão anterior" aqui é real, não
-  // a que este próprio run está prestes a gravar. Sem esse registro (projeto
-  // nunca rastreado antes, ou greenfield), não há fonte segura — mantém o
-  // aviso como fallback, igual ao comportamento anterior.
+  // A cópia legada SOMBREIA os templates do pacote (override-first). A versão anterior é lida
+  // aqui, antes de o passo 17 regravar .morph/.morphversion; sem ela, não há fonte segura e só avisa.
   const legacyTemplatesDir = join(frameworkDestDir, 'templates');
   if (await pathExists(legacyTemplatesDir)) {
     const priorVersionInfo = await getProjectMorphVersion(targetPath);
@@ -348,7 +257,6 @@ export async function setupInfra(targetPath, {
     }
   }
 
-  // --- 6. Copy framework/standards → .morph/framework/standards ---
   log('Step 6: Copying framework standards...');
   const frameworkStandardsSrc = join(FRAMEWORK_DIR, 'standards');
   const frameworkStandardsDest = join(frameworkDestDir, 'standards');
@@ -356,7 +264,6 @@ export async function setupInfra(targetPath, {
     await copyDirectory(frameworkStandardsSrc, frameworkStandardsDest);
   }
 
-  // --- 7. Copy framework/hooks → .morph/framework/hooks ---
   log('Step 7: Copying hooks...');
   const hooksSrc = join(FRAMEWORK_DIR, 'hooks');
   const hooksDest = join(frameworkDestDir, 'hooks');
@@ -364,7 +271,6 @@ export async function setupInfra(targetPath, {
     await copyDirectory(hooksSrc, hooksDest);
   }
 
-  // --- 7c. Copy framework/evals → .morph/framework/evals ---
   log('Step 7c: Copying evals (review checklist + trace schema)...');
   const evalsSrc = join(FRAMEWORK_DIR, 'evals');
   const evalsDest = join(frameworkDestDir, 'evals');
@@ -372,7 +278,6 @@ export async function setupInfra(targetPath, {
     await copyDirectory(evalsSrc, evalsDest);
   }
 
-  // --- 8. Copy framework/agents.json → .morph/framework/agents.json ---
   log('Step 8: Copying agents.json...');
   const agentsSrc = join(FRAMEWORK_DIR, 'agents.json');
   const agentsDest = join(frameworkDestDir, 'agents.json');
@@ -380,7 +285,6 @@ export async function setupInfra(targetPath, {
     await copyFile(agentsSrc, agentsDest);
   }
 
-  // --- 8b. Copy framework/MORPH.md → .morph/framework/MORPH.md ---
   log('Step 8b: Copying MORPH.md (NLH charter)...');
   const morphMdSrc = join(FRAMEWORK_DIR, 'MORPH.md');
   const morphMdDest = join(frameworkDestDir, 'MORPH.md');
@@ -388,9 +292,6 @@ export async function setupInfra(targetPath, {
     await copyFile(morphMdSrc, morphMdDest);
   }
 
-  // --- 8b2. Copy framework/docs/CLI.md → .morph/framework/CLI.md ---
-  // Referência completa dos comandos (flags, semântica, exemplos) — o
-  // CLAUDE.md residente carrega só a tabela compacta e aponta para cá.
   log('Step 8b2: Copying CLI.md (command reference)...');
   const cliMdSrc = join(FRAMEWORK_DIR, 'docs', 'CLI.md');
   const cliMdDest = join(frameworkDestDir, 'CLI.md');
@@ -398,7 +299,6 @@ export async function setupInfra(targetPath, {
     await copyFile(cliMdSrc, cliMdDest);
   }
 
-  // --- 8c. Copy framework/phases.json → .morph/framework/phases.json ---
   log('Step 8c: Copying phases.json...');
   const phasesSrc = join(FRAMEWORK_DIR, 'phases.json');
   const phasesDest = join(frameworkDestDir, 'phases.json');
@@ -406,7 +306,6 @@ export async function setupInfra(targetPath, {
     await copyFile(phasesSrc, phasesDest);
   }
 
-  // --- 8d. Copy framework/schemas → .morph/framework/schemas (JSON schemas) ---
   log('Step 8d: Copying schemas...');
   const schemasSrc = join(FRAMEWORK_DIR, 'schemas');
   const schemasDest = join(frameworkDestDir, 'schemas');
@@ -416,20 +315,16 @@ export async function setupInfra(targetPath, {
 
   const claudeDest = join(targetPath, '.claude');
 
-  // --- 9-13. Install stack-aware assets (commands, rules, skills, agents) ---
   log('Steps 10-13: Installing stack-aware assets...');
   const { agentCounts, domainCounts, projectTags } = await installStackAwareAssets(targetPath, log);
 
-  // --- 14. Copy framework/CLAUDE.md → .claude/CLAUDE.md (morph-owned, gitignored) ---
   log('Step 14: Installing .claude/CLAUDE.md...');
   const runtimeClaudeMdDest = join(claudeDest, 'CLAUDE.md');
   if (await pathExists(claudeMdSrc)) {
     await copyFile(claudeMdSrc, runtimeClaudeMdDest);
-    // Derive the personas section from what step 10-13 actually installed.
     await updateClaudeMdAgentsBlock(runtimeClaudeMdDest, agentCounts?.agents ?? []);
   }
 
-  // --- 15. installGlobalStatusline (non-critical) ---
   log('Step 15: Installing global statusline...');
   const HOOKS_SRC = join(FRAMEWORK_DIR, 'hooks', 'claude-code');
   try {
@@ -438,16 +333,13 @@ export async function setupInfra(targetPath, {
     // Non-critical — global ~/.claude may not be writable
   }
 
-  // --- 16. installClaudeHooks ---
   log('Step 16: Installing Claude Code hooks...');
   await installClaudeHooks(targetPath);
 
-  // --- 17. saveProjectMorphVersion ---
   log('Step 17: Saving version info...');
   const cliVersion = getInstalledCLIVersion();
   await saveProjectMorphVersion(targetPath, cliVersion);
 
-  // --- 18. updateGitignore + .gitattributes ---
   log('Step 18: Updating .gitignore + .gitattributes...');
   await updateGitignore(targetPath);
   await ensureGitattributes(targetPath);
@@ -455,10 +347,7 @@ export async function setupInfra(targetPath, {
   log('Step 18a: Editor excludes for worktrees...');
   try { applyEditorSettings(targetPath); } catch { /* fail-open */ }
 
-  // --- 18b. Codebase graph (graphify) ---
-  // Fail-open por inteiro (ADR-002): sem Python, sem uv e sem pipx, o step
-  // registra e segue. O wrapper de CLI mata o processo em qualquer throw
-  // (setup-infra-cmd.js), então nada aqui pode escapar do try.
+  // Fail-open por inteiro: o wrapper de CLI mata o processo em qualquer throw.
   log('Step 18b: Codebase graph (graphify)...');
   try {
     const { writeGraphifyignore, describeOutdatedIgnore } = await import('../lib/graph/graphifyignore.js');
@@ -486,7 +375,6 @@ export async function setupInfra(targetPath, {
     } else {
       const { kind } = detectInstaller();
       if (!kind) {
-        // Registra e segue: o framework funciona sem grafo, por grep.
         log(`  ⚠ Sem uv/pipx/python — grafo indisponível. Depois: uv tool install ${GRAPHIFY_PACKAGE}==${GRAPHIFY_VERSION}`);
       } else {
         // Sem o extra [sql] os arquivos .sql são ignorados em silêncio.
@@ -501,16 +389,8 @@ export async function setupInfra(targetPath, {
       }
     }
 
-    // Nenhum hook do graphify: o refresh mora nos hooks do Claude (step 16 —
-    // graph-refresh-kick + SessionStart), que o `update` reinstala. O
-    // `graphify hook install` ficou de fora por três defeitos medidos no 0.9.50:
-    // sai sem fazer nada em worktree vinculada, não tem post-merge (merge e pull
-    // nunca rebuildam) e, num commit depois de um fast-forward, carimba o HEAD
-    // num grafo sem os arquivos do merge. E nunca `graphify claude install`:
-    // escreveria no CLAUDE.md e um PreToolUse próprio.
-    //
-    // A linha só sai com o graphify presente, e diz o que dispara de fato: um
-    // commit feito no terminal não dispara nada até o próximo desses.
+    // Sem hook git do graphify: o refresh mora nos hooks do Claude (step 16). O `graphify hook install`
+    // 0.9.50 não roda em worktree vinculada, não tem post-merge e carimba HEAD num grafo sem o merge.
     if (probe()) {
       log('  ✓ refresh automático do grafo da raiz: depois dos comandos git/gh/morph-spec do agente e no início de cada sessão');
     }
@@ -518,7 +398,6 @@ export async function setupInfra(targetPath, {
     log(`  ⚠ Step do grafo pulado: ${err.message}`);
   }
 
-  // --- 19. Initialize state.json (only if not exists) ---
   log('Step 19: Initializing state.json...');
   const statePath = join(morphPath, 'state.json');
   if (!(await pathExists(statePath))) {