@polymorphism-tech/morph-spec 8.28.0 → 8.31.0

package/src/utils/skills-installer.js

@@ -1,187 +1,187 @@
-/**
- * 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 { 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 };
+}