@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/src/utils/skills-installer.js

@@ -1,187 +1,194 @@
-/**
- * Skills Installer
- *
- * Copies framework skills to .claude/skills/ during morph-spec init.
- * Installs only the `core/` skill set — the canonical NLH skills referenced by
- * MORPH.md (morph-brainstorming, morph-stack-scan, morph-plan, morph-implement,
- * morph-eval, morph-review, morph-standards). The 3-tier system was collapsed
- * into a single source of truth in framework/skills/core/.
- *
- * Source skills are directory-based: framework/skills/core/{skill-name}/SKILL.md
- * (plus optional scripts/, references/, assets/ subdirectories).
- *
- * Directory-based skills have their entire directory copied so Claude Code can
- * execute scripts and load references on demand.
- */
-
-import { mkdirSync, copyFileSync, existsSync, readdirSync, statSync, readFileSync, rmSync } from 'fs';
-import { join } from 'path';
-import { fileURLToPath } from 'url';
-import { parseStacks, shouldInstall } from '../lib/stack-filter.js';
-
-const __dirname = fileURLToPath(new URL('.', import.meta.url));
-const FRAMEWORK_SKILLS_DIR = join(__dirname, '..', '..', 'framework', 'skills');
-
-/**
- * Skill levels to install in .claude/skills/.
- * Only `core/` survives — single source of truth aligned with MORPH.md.
- */
-const SKILL_LEVELS_TO_INSTALL = ['core'];
-
-/**
- * Check if a skill should be installed based on its stacks: frontmatter.
- * @param {string} skillContent - Raw SKILL.md content
- * @param {string[]} projectTags - Stack tags from config
- * @returns {boolean}
- */
-export function shouldInstallSkill(skillContent, projectTags) {
-  return shouldInstall(parseStacks(skillContent), projectTags);
-}
-
-/**
- * Recursively copy a directory tree from src to dest.
- * Creates dest if it doesn't exist. Skips README.md files.
- *
- * @param {string} src - Source directory path
- * @param {string} dest - Destination directory path
- */
-function copyDirectory(src, dest) {
-  mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src)) {
-    if (entry === 'README.md') continue;
-    const srcPath = join(src, entry);
-    const destPath = join(dest, entry);
-    if (statSync(srcPath).isDirectory()) {
-      copyDirectory(srcPath, destPath);
-    } else {
-      copyFileSync(srcPath, destPath);
-    }
-  }
-}
-
-/**
- * Walk srcDir and install skills into destDir.
- *
- * Handles two source formats:
- *   1. Directory-based skill: srcDir/{skill-name}/SKILL.md
- *      → copies entire directory (SKILL.md + scripts/ + references/ + assets/)
- *      → destDir/{skill-name}/
- *
- *   2. Flat .md skill (legacy): srcDir/{skill-name}.md
- *      → destDir/{skill-name}/SKILL.md
- *
- * The `core/` level directory is traversed recursively. A directory is
- * recognized as a skill directory when it contains a SKILL.md file.
- *
- * @param {string} srcDir - Source directory to walk
- * @param {string} destDir - Destination base directory (.claude/skills/)
- * @param {string[]} projectTags - Stack tags from config
- * @param {Set<string>} installedNow - Accumulator: skill names this call
- *   actually (re)installed. NOT derived by re-scanning destDir afterwards —
- *   a disk scan can't distinguish "installed this run" from "leftover from a
- *   previous run with different projectTags", which is exactly the stale
- *   entry a stack change needs cleaned up.
- */
-function installSkillsFromDir(srcDir, destDir, projectTags, installedNow) {
-  const entries = readdirSync(srcDir);
-  for (const entry of entries) {
-    const srcPath = join(srcDir, entry);
-    const stat = statSync(srcPath);
-
-    if (stat.isDirectory()) {
-      const skillMdPath = join(srcPath, 'SKILL.md');
-      if (existsSync(skillMdPath)) {
-        // Directory-based skill — check stack filter before copying
-        const content = readFileSync(skillMdPath, 'utf-8');
-        if (!shouldInstallSkill(content, projectTags)) continue;
-        const skillDestDir = join(destDir, entry);
-        copyDirectory(srcPath, skillDestDir);
-        installedNow.add(entry);
-      } else {
-        // Level/category directory — recurse
-        installSkillsFromDir(srcPath, destDir, projectTags, installedNow);
-      }
-    } else if (entry.endsWith('.md') && entry !== 'README.md') {
-      // Legacy flat .md skill — check stack filter before copying
-      const content = readFileSync(srcPath, 'utf-8');
-      if (!shouldInstallSkill(content, projectTags)) continue;
-      const skillName = entry.slice(0, -3);
-      const skillDir = join(destDir, skillName);
-      mkdirSync(skillDir, { recursive: true });
-      copyFileSync(srcPath, join(skillDir, 'SKILL.md'));
-      installedNow.add(skillName);
-    }
-  }
-}
-
-function collectSourceSkillNames() {
-  const names = new Set();
-  for (const level of SKILL_LEVELS_TO_INSTALL) {
-    const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
-    if (!existsSync(levelDir)) continue;
-    collectNamesFromDir(levelDir, names);
-  }
-  return names;
-}
-
-function collectNamesFromDir(dir, names) {
-  for (const entry of readdirSync(dir)) {
-    const fullPath = join(dir, entry);
-    if (!statSync(fullPath).isDirectory()) continue;
-    if (existsSync(join(fullPath, 'SKILL.md'))) {
-      names.add(entry);
-    } else {
-      collectNamesFromDir(fullPath, names);
-    }
-  }
-}
-
-/**
- * Install morph framework skills to .claude/skills/ in the target project.
- * Skills are copied into subdirectories as SKILL.md files so Claude Code can
- * discover them natively via /<skill-name> syntax (e.g., /phase-design,
- * /nextjs-expert). Directory-based skills also get their scripts/,
- * references/, and assets/ subdirectories copied for on-demand loading.
- *
- * Stack filtering: if projectTags is provided, only skills whose `stacks:`
- * frontmatter matches the project tags are installed. Skills without a
- * `stacks:` field are always installed (universal).
- *
- * @param {string} projectDir - Target project root directory
- * @param {Object} [options]
- * @param {string[]} [options.projectTags=[]] - Stack tags from config
- */
-export async function installSkills(projectDir, { projectTags = [] } = {}) {
-  const claudeSkillsDir = join(projectDir, '.claude', 'skills');
-  mkdirSync(claudeSkillsDir, { recursive: true });
-
-  // Skill names this call actually (re)installs, given projectTags. Tracked
-  // as we go (NOT by re-scanning claudeSkillsDir afterwards) — a disk scan
-  // can't tell "installed this run" apart from "leftover from a previous
-  // run with different projectTags", which is exactly the stale entry a
-  // stack change (or a re-run that narrows the stack) needs cleaned up.
-  const installedNow = new Set();
-  for (const level of SKILL_LEVELS_TO_INSTALL) {
-    const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
-    if (!existsSync(levelDir)) continue;
-    installSkillsFromDir(levelDir, claudeSkillsDir, projectTags, installedNow);
-  }
-
-  // Clean-slate: remove any skill dir that is a KNOWN framework skill (still
-  // present in framework/skills/core/) but did NOT get (re)installed this
-  // run — i.e. it was filtered out by a `stacks:` mismatch (project.stack
-  // changed, or a re-run narrowed the tags). Previously scoped to `morph-`
-  // prefixed names only, which silently exempted every non-`morph-` skill
-  // (the Umbraco pair) from ever being cleaned up: install once with
-  // `umbraco` in the stack, drop the stack later, and they'd survive every
-  // reinstall/update forever. Names outside allSourceSkills (user-added,
-  // non-framework skills) are never touched.
-  const allSourceSkills = collectSourceSkillNames();
-  for (const entry of readdirSync(claudeSkillsDir)) {
-    if (!installedNow.has(entry) && allSourceSkills.has(entry)) {
-      rmSync(join(claudeSkillsDir, entry), { recursive: true, force: true });
-    }
-  }
-
-  return { installed: installedNow.size };
-}
+/**
+ * Skills Installer
+ *
+ * Copies framework skills to .claude/skills/ during morph-spec init.
+ * Installs only the `core/` skill set — the canonical NLH skills referenced by
+ * MORPH.md (morph-brainstorming, morph-stack-scan, morph-plan, morph-implement,
+ * morph-eval, morph-review, morph-standards). The 3-tier system was collapsed
+ * into a single source of truth in framework/skills/core/.
+ *
+ * Source skills are directory-based: framework/skills/core/{skill-name}/SKILL.md
+ * (plus optional scripts/, references/, assets/ subdirectories).
+ *
+ * Directory-based skills have their entire directory copied so Claude Code can
+ * execute scripts and load references on demand.
+ */
+
+import { existsSync, readdirSync, statSync, readFileSync } from 'fs';
+import { basename, join } from 'path';
+import { fileURLToPath } from 'url';
+import { parseStacks, shouldInstall } from '../lib/stack-filter.js';
+import { realEffects } from '../lib/installers/effects.js';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const FRAMEWORK_SKILLS_DIR = join(__dirname, '..', '..', 'framework', 'skills');
+
+/**
+ * Skill levels to install in .claude/skills/.
+ * Only `core/` survives — single source of truth aligned with MORPH.md.
+ */
+const SKILL_LEVELS_TO_INSTALL = ['core'];
+
+/**
+ * Check if a skill should be installed based on its stacks: frontmatter.
+ * @param {string} skillContent - Raw SKILL.md content
+ * @param {string[]} projectTags - Stack tags from config
+ * @returns {boolean}
+ */
+export function shouldInstallSkill(skillContent, projectTags) {
+  return shouldInstall(parseStacks(skillContent), projectTags);
+}
+
+/**
+ * Copy a skill directory tree from src to dest, skipping README.md files.
+ *
+ * UM efeito por skill (não um por arquivo): é assim que o instalador pensa
+ * ("instalar a skill X"), e é o que o relatório do `--dry-run` precisa dizer.
+ *
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} fx
+ */
+function copySkillDirectory(src, dest, fx) {
+  fx.copyDir(src, dest, { filter: (from) => basename(from) !== 'README.md' });
+}
+
+/**
+ * Walk srcDir and install skills into destDir.
+ *
+ * Handles two source formats:
+ *   1. Directory-based skill: srcDir/{skill-name}/SKILL.md
+ *      → copies entire directory (SKILL.md + scripts/ + references/ + assets/)
+ *      → destDir/{skill-name}/
+ *
+ *   2. Flat .md skill (legacy): srcDir/{skill-name}.md
+ *      → destDir/{skill-name}/SKILL.md
+ *
+ * The `core/` level directory is traversed recursively. A directory is
+ * recognized as a skill directory when it contains a SKILL.md file.
+ *
+ * @param {string} srcDir - Source directory to walk
+ * @param {string} destDir - Destination base directory (.claude/skills/)
+ * @param {string[]} projectTags - Stack tags from config
+ * @param {Set<string>} installedNow - Accumulator: skill names this call
+ *   actually (re)installed. NOT derived by re-scanning destDir afterwards —
+ *   a disk scan can't distinguish "installed this run" from "leftover from a
+ *   previous run with different projectTags", which is exactly the stale
+ *   entry a stack change needs cleaned up.
+ */
+function installSkillsFromDir(srcDir, destDir, projectTags, installedNow, fx) {
+  const entries = readdirSync(srcDir);
+  for (const entry of entries) {
+    const srcPath = join(srcDir, entry);
+    const stat = statSync(srcPath);
+
+    if (stat.isDirectory()) {
+      const skillMdPath = join(srcPath, 'SKILL.md');
+      if (existsSync(skillMdPath)) {
+        // Directory-based skill — check stack filter before copying.
+        // O filtro é PURO e continua sendo o único: previsão e execução
+        // percorrem esta mesma linha.
+        const content = readFileSync(skillMdPath, 'utf-8');
+        if (!shouldInstallSkill(content, projectTags)) continue;
+        const skillDestDir = join(destDir, entry);
+        copySkillDirectory(srcPath, skillDestDir, fx);
+        installedNow.add(entry);
+      } else {
+        // Level/category directory — recurse
+        installSkillsFromDir(srcPath, destDir, projectTags, installedNow, fx);
+      }
+    } else if (entry.endsWith('.md') && entry !== 'README.md') {
+      // Legacy flat .md skill — check stack filter before copying
+      const content = readFileSync(srcPath, 'utf-8');
+      if (!shouldInstallSkill(content, projectTags)) continue;
+      const skillName = entry.slice(0, -3);
+      const skillDir = join(destDir, skillName);
+      fx.ensureDir(skillDir);
+      fx.copyFile(srcPath, join(skillDir, 'SKILL.md'));
+      installedNow.add(skillName);
+    }
+  }
+}
+
+function collectSourceSkillNames() {
+  const names = new Set();
+  for (const level of SKILL_LEVELS_TO_INSTALL) {
+    const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
+    if (!existsSync(levelDir)) continue;
+    collectNamesFromDir(levelDir, names);
+  }
+  return names;
+}
+
+function collectNamesFromDir(dir, names) {
+  for (const entry of readdirSync(dir)) {
+    const fullPath = join(dir, entry);
+    if (!statSync(fullPath).isDirectory()) continue;
+    if (existsSync(join(fullPath, 'SKILL.md'))) {
+      names.add(entry);
+    } else {
+      collectNamesFromDir(fullPath, names);
+    }
+  }
+}
+
+/**
+ * Install morph framework skills to .claude/skills/ in the target project.
+ * Skills are copied into subdirectories as SKILL.md files so Claude Code can
+ * discover them natively via /<skill-name> syntax (e.g., /phase-design,
+ * /nextjs-expert). Directory-based skills also get their scripts/,
+ * references/, and assets/ subdirectories copied for on-demand loading.
+ *
+ * Stack filtering: if projectTags is provided, only skills whose `stacks:`
+ * frontmatter matches the project tags are installed. Skills without a
+ * `stacks:` field are always installed (universal).
+ *
+ * @param {string} projectDir - Target project root directory
+ * @param {Object} [options]
+ * @param {string[]} [options.projectTags=[]] - Stack tags from config
+ * @param {ReturnType<import('../lib/installers/effects.js').createEffects>} [options.fx]
+ *   Coletor de efeitos; o default executa e registra numa lista descartada.
+ */
+export async function installSkills(projectDir, { projectTags = [], fx = realEffects() } = {}) {
+  const claudeSkillsDir = join(projectDir, '.claude', 'skills');
+  fx.ensureDir(claudeSkillsDir);
+
+  // Skill names this call actually (re)installs, given projectTags. Tracked
+  // as we go (NOT by re-scanning claudeSkillsDir afterwards) — a disk scan
+  // can't tell "installed this run" apart from "leftover from a previous
+  // run with different projectTags", which is exactly the stale entry a
+  // stack change (or a re-run that narrows the stack) needs cleaned up.
+  const installedNow = new Set();
+  for (const level of SKILL_LEVELS_TO_INSTALL) {
+    const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
+    if (!existsSync(levelDir)) continue;
+    installSkillsFromDir(levelDir, claudeSkillsDir, projectTags, installedNow, fx);
+  }
+
+  // Clean-slate: remove any skill dir that is a KNOWN framework skill (still
+  // present in framework/skills/core/) but did NOT get (re)installed this
+  // run — i.e. it was filtered out by a `stacks:` mismatch (project.stack
+  // changed, or a re-run narrowed the tags). Previously scoped to `morph-`
+  // prefixed names only, which silently exempted every non-`morph-` skill
+  // (the Umbraco pair) from ever being cleaned up: install once with
+  // `umbraco` in the stack, drop the stack later, and they'd survive every
+  // reinstall/update forever. Names outside allSourceSkills (user-added,
+  // non-framework skills) are never touched.
+  //
+  // Em `dryRun` este laço NÃO emite nada, e a razão está na D6: numa execução
+  // real do `update` ele sempre vê um diretório VAZIO, porque
+  // `cleanFrameworkDirs()` acabou de apagar `.claude/skills/` inteiro. Num dry
+  // ingênuo nada foi apagado, ele veria o diretório POPULADO, e o relatório
+  // preveria remoções que a execução real nunca faz — errado na direção que
+  // assusta o usuário. O clean subsome este laço, provadamente.
+  if (!fx.dryRun) {
+    const allSourceSkills = collectSourceSkillNames();
+    for (const entry of readdirSync(claudeSkillsDir)) {
+      if (!installedNow.has(entry) && allSourceSkills.has(entry)) {
+        fx.remove(join(claudeSkillsDir, entry));
+      }
+    }
+  }
+
+  return { installed: installedNow.size };
+}

package/src/utils/version-checker.js

@@ -1,7 +1,8 @@
 import { readFileSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'url';
-import { pathExists, readJson, writeJson } from './file-copier.js';
+import { pathExists, readJson } from './file-copier.js';
+import { realEffects } from '../lib/installers/effects.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -58,14 +59,14 @@ export async function getProjectMorphVersion(projectPath) {
  * @param {string} version - Version to save
  * @returns {Promise<void>}
  */
-export async function saveProjectMorphVersion(projectPath, version) {
+export async function saveProjectMorphVersion(projectPath, version, fx = realEffects()) {
   const versionPath = join(projectPath, '.morph', '.morphversion');
   const versionInfo = {
     morphVersion: version,
     installedAt: new Date().toISOString(),
     cliVersion: version
   };
-  await writeJson(versionPath, versionInfo);
+  fx.writeJson(versionPath, versionInfo);
 }
 
 /**
@@ -91,6 +92,70 @@ export function compareVersions(v1, v2) {
   return 0;
 }
 
+/**
+ * Major de uma versão, ou `null` quando a string não permite decidir.
+ *
+ * Vive aqui, ao lado de `compareVersions`, de propósito: uma segunda
+ * aritmética de versão noutro arquivo é exatamente como duas verdades sobre a
+ * mesma versão nascem.
+ *
+ * @param {string|null|undefined} version
+ * @returns {number|null}
+ */
+export function majorOf(version) {
+  if (typeof version !== 'string') return null;
+  const m = /^\s*v?(\d+)\./.exec(version) ?? /^\s*v?(\d+)\s*$/.exec(version);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Limiar do freio: um salto de DOIS majors ou mais recusa sem `--force`.
+ *
+ * O limiar não é "quantos majors dá para pular com segurança" — é "a partir de
+ * onde o usuário merece ler o relatório antes". Medido: um projeto em 7.x indo
+ * para 9.x recusa; um em 8.x atualiza sem atrito.
+ */
+export const MAJOR_JUMP_LIMIT = 2;
+
+/**
+ * Avalia o salto entre a versão instalada no projeto e a versão de destino.
+ *
+ * Três resultados, e a diferença entre eles é o que a mensagem tem de dizer:
+ *
+ * - `reason: 'unknown-installed'` — a versão instalada é indeterminável.
+ *   Tratada como salto grande, com motivo PRÓPRIO: "não sei quão velho isto é"
+ *   é precisamente quando sobrescrever às cegas é mais perigoso, e tratá-la
+ *   como zero seria a única leitura que libera o pior caso.
+ * - `reason: 'major-jump'` — salto medido de `jump` majors, >= ao limiar.
+ * - `reason: null` — sem freio (mesmo major, um só major de diferença, ou
+ *   destino não superior à instalada).
+ *
+ * @param {string|null} installedVersion
+ * @param {string|null} targetVersion
+ * @param {{ limit?: number }} [options]
+ * @returns {{ refuse: boolean, reason: 'unknown-installed'|'major-jump'|null, jump: number|null }}
+ */
+export function majorJump(installedVersion, targetVersion, { limit = MAJOR_JUMP_LIMIT } = {}) {
+  const installedMajor = majorOf(installedVersion);
+  const targetMajor = majorOf(targetVersion);
+
+  if (installedMajor === null) {
+    return { refuse: true, reason: 'unknown-installed', jump: null };
+  }
+  if (targetMajor === null) {
+    // Sem destino legível não há salto a medir — e inventar um seria decidir
+    // por um número que ninguém mantém.
+    return { refuse: false, reason: null, jump: null };
+  }
+  if (compareVersions(installedVersion, targetVersion) >= 0) {
+    return { refuse: false, reason: null, jump: 0 };
+  }
+
+  const jump = targetMajor - installedMajor;
+  if (jump >= limit) return { refuse: true, reason: 'major-jump', jump };
+  return { refuse: false, reason: null, jump };
+}
+
 /**
  * Detect how the CLI was installed
  * @returns {'global'|'npx'|'unknown'}