@polymorphism-tech/morph-spec 9.0.0 → 9.1.0

package/src/utils/skills-installer.js

@@ -1,18 +1,3 @@
-/**
- * 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-plan, morph-uiux, morph-apply, 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';
@@ -22,59 +7,16 @@ 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) {
@@ -84,20 +26,15 @@ function installSkillsFromDir(srcDir, destDir, projectTags, installedNow, fx) {
     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);
@@ -131,32 +68,12 @@ function collectNamesFromDir(dir, 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.
+  // Tracked as we go: a disk scan can't tell this run's installs from leftovers
+  // of a run with other projectTags, which a stack change must clean up.
   const installedNow = new Set();
   for (const level of SKILL_LEVELS_TO_INSTALL) {
     const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
@@ -164,22 +81,8 @@ export async function installSkills(projectDir, { projectTags = [], fx = realEff
     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.
+  // Removes known framework skills not reinstalled this run; user skills are never touched.
+  // Silent in dryRun: the real update's cleanFrameworkDirs() already emptied the dir.
   if (!fx.dryRun) {
     const allSourceSkills = collectSourceSkillNames();
     for (const entry of readdirSync(claudeSkillsDir)) {

package/src/utils/version-checker.js

@@ -6,10 +6,6 @@ import { realEffects } from '../lib/installers/effects.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-/**
- * Get the current CLI version from package.json
- * @returns {string} Version string (e.g., "1.0.4")
- */
 export function getInstalledCLIVersion() {
   try {
     const pkgPath = join(__dirname, '..', '..', 'package.json');
@@ -20,11 +16,6 @@ export function getInstalledCLIVersion() {
   }
 }
 
-/**
- * Get the latest version from npm registry
- * @param {string} packageName - The package name (default: @polymorphism-tech/morph-spec)
- * @returns {Promise<string|null>} Latest version or null if failed
- */
 export async function getLatestNPMVersion(packageName = '@polymorphism-tech/morph-spec') {
   try {
     const response = await fetch(`https://registry.npmjs.org/${packageName}/latest`);
@@ -36,11 +27,6 @@ export async function getLatestNPMVersion(packageName = '@polymorphism-tech/morp
   }
 }
 
-/**
- * Get the MORPH version installed in the project
- * @param {string} projectPath - Path to the project
- * @returns {Promise<object|null>} Version info object or null if not found
- */
 export async function getProjectMorphVersion(projectPath) {
   try {
     const versionPath = join(projectPath, '.morph', '.morphversion');
@@ -53,12 +39,6 @@ export async function getProjectMorphVersion(projectPath) {
   }
 }
 
-/**
- * Save the MORPH version to the project
- * @param {string} projectPath - Path to the project
- * @param {string} version - Version to save
- * @returns {Promise<void>}
- */
 export async function saveProjectMorphVersion(projectPath, version, fx = realEffects()) {
   const versionPath = join(projectPath, '.morph', '.morphversion');
   const versionInfo = {
@@ -69,12 +49,7 @@ export async function saveProjectMorphVersion(projectPath, version, fx = realEff
   fx.writeJson(versionPath, versionInfo);
 }
 
-/**
- * Compare two semver versions
- * @param {string} v1 - First version
- * @param {string} v2 - Second version
- * @returns {number} -1 if v1 < v2, 0 if equal, 1 if v1 > v2
- */
+/** @returns {number} -1 if v1 < v2, 0 if equal, 1 if v1 > v2 */
 export function compareVersions(v1, v2) {
   if (!v1 || !v2) return 0;
 
@@ -92,49 +67,17 @@ 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}
- */
+/** @returns {number|null} `null` when the string does not determine a major */
 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 }}
- */
+// An unreadable installed version refuses with its own reason: not knowing how old
+// the project is is when a blind overwrite is most dangerous.
 export function majorJump(installedVersion, targetVersion, { limit = MAJOR_JUMP_LIMIT } = {}) {
   const installedMajor = majorOf(installedVersion);
   const targetMajor = majorOf(targetVersion);
@@ -143,8 +86,6 @@ export function majorJump(installedVersion, targetVersion, { limit = MAJOR_JUMP_
     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) {
@@ -156,17 +97,11 @@ export function majorJump(installedVersion, targetVersion, { limit = MAJOR_JUMP_
   return { refuse: false, reason: null, jump };
 }
 
-/**
- * Detect how the CLI was installed
- * @returns {'global'|'npx'|'unknown'}
- */
 export function detectInstallMethod() {
-  // Check if running via npx
   if (process.env.npm_execpath && process.env.npm_execpath.includes('npx')) {
     return 'npx';
   }
 
-  // Check if installed globally
   const isGlobal = process.env.npm_config_global === 'true' ||
                    process.execPath.includes('node_modules');
 
@@ -177,11 +112,6 @@ export function detectInstallMethod() {
   return 'unknown';
 }
 
-/**
- * Get update instructions based on install method
- * @param {string} method - Install method ('global', 'npx', 'unknown')
- * @returns {string[]} Array of instruction strings
- */
 export function getUpdateInstructions(method) {
   switch (method) {
     case 'global':
@@ -198,10 +128,6 @@ export function getUpdateInstructions(method) {
   }
 }
 
-/**
- * Check if CLI version is outdated
- * @returns {Promise<{isOutdated: boolean, current: string, latest: string|null}>}
- */
 export async function checkCLIOutdated() {
   const current = getInstalledCLIVersion();
   const latest = await getLatestNPMVersion();
@@ -215,11 +141,6 @@ export async function checkCLIOutdated() {
   return { isOutdated, current, latest };
 }
 
-/**
- * Check if project MORPH version is outdated
- * @param {string} projectPath - Path to the project
- * @returns {Promise<{isOutdated: boolean, current: string|null, cliVersion: string}>}
- */
 export async function checkProjectOutdated(projectPath) {
   const cliVersion = getInstalledCLIVersion();
   const projectVersion = await getProjectMorphVersion(projectPath);

package/framework/commands/morph-proposal.md

@@ -1,9 +0,0 @@
----
-description: Inicia ou retoma uma feature MORPH-SPEC — entrevista, plan.md, plan-check e gate do plano.
-argument-hint: <feature-name>
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Agent, AskUserQuestion, Skill
----
-
-Invoque `Skill(morph-plan)` com o argumento abaixo e siga a skill.
-
-**Feature:** $ARGUMENTS

package/src/commands/utils/index.js

@@ -1,3 +0,0 @@
-/**
- * Utility Commands — no active commands after CLI simplification
- */

package/src/lib/detectors/design-system-detector.js

@@ -1,188 +0,0 @@
-/**
- * @fileoverview Design System Detector
- *
- * Detects if a design system exists for the project or feature.
- * Checks multiple locations in priority order.
- *
- * @module design-system-detector
- */
-
-import { existsSync, readFileSync, readdirSync } from 'fs';
-import { join } from 'path';
-
-const SKIP_DIRS = new Set(['node_modules', '.git', '.morph', 'dist', 'build', '.next', 'obj', 'bin', '.vs']);
-const CSS_SCAN_MAX_DEPTH = 6;
-
-/**
- * Recursively walk a directory collecting files with given extensions.
- * @param {string} dir - Directory to walk
- * @param {string[]} extensions - File extensions to collect (e.g. ['.css', '.scss'])
- * @param {string[]} files - Accumulator array (mutated in-place)
- * @param {number} depth - Current recursion depth
- * @param {number} maxDepth - Maximum recursion depth
- */
-function walkDirForCss(dir, extensions, files, depth, maxDepth) {
-  if (depth > maxDepth) return;
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    if (entry.isDirectory()) {
-      if (!SKIP_DIRS.has(entry.name)) {
-        walkDirForCss(join(dir, entry.name), extensions, files, depth + 1, maxDepth);
-      }
-    } else if (entry.isFile()) {
-      const lower = entry.name.toLowerCase();
-      if (extensions.some(ext => lower.endsWith(ext))) {
-        files.push(join(dir, entry.name));
-      }
-    }
-  }
-}
-
-/**
- * Detect design system for project or feature
- * @param {string} projectPath - Root path of the project
- * @param {string|null} featureName - Feature name (optional, checks feature-level if provided)
- * @returns {Object} { hasDesignSystem, path, isProjectLevel, isFeatureLevel, source }
- */
-export function detectDesignSystem(projectPath, featureName = null) {
-  const result = {
-    hasDesignSystem: false,
-    path: null,
-    isProjectLevel: false,
-    isFeatureLevel: false,
-    source: null
-  };
-
-  // Priority 1: Feature-level design system (if feature specified)
-  if (featureName) {
-    const featureDesignSystemPath = join(
-      projectPath,
-      '.morph/features',
-      featureName,
-      '1-design',
-      'design-system.md'
-    );
-
-    if (existsSync(featureDesignSystemPath)) {
-      return {
-        hasDesignSystem: true,
-        path: featureDesignSystemPath,
-        isProjectLevel: false,
-        isFeatureLevel: true,
-        source: 'feature-output'
-      };
-    }
-  }
-
-  // Priority 2: Project-level design system (markdown)
-  const projectDesignSystemPath = join(projectPath, '.morph/context/design-system.md');
-  if (existsSync(projectDesignSystemPath)) {
-    return {
-      hasDesignSystem: true,
-      path: projectDesignSystemPath,
-      isProjectLevel: true,
-      isFeatureLevel: false,
-      source: 'project-markdown'
-    };
-  }
-
-  // Priority 3: Generated CSS design system
-  const cssDesignSystemPath = join(projectPath, 'wwwroot/css/design-system.css');
-  if (existsSync(cssDesignSystemPath)) {
-    return {
-      hasDesignSystem: true,
-      path: cssDesignSystemPath,
-      isProjectLevel: true,
-      isFeatureLevel: false,
-      source: 'generated-css'
-    };
-  }
-
-  // Priority 4: Recursively scan frontend root directories for CSS/SCSS with design tokens
-  const frontendRoots = ['wwwroot', 'styles', 'src/styles', 'src', 'public'];
-  const extensions = ['.css', '.scss'];
-  const collected = [];
-
-  for (const root of frontendRoots) {
-    const rootPath = join(projectPath, root);
-    if (existsSync(rootPath)) {
-      walkDirForCss(rootPath, extensions, collected, 0, CSS_SCAN_MAX_DEPTH);
-    }
-  }
-
-  // Deduplicate by resolved path
-  const seen = new Set();
-  const cssFiles = [];
-  for (const file of collected) {
-    if (!seen.has(file)) {
-      seen.add(file);
-      cssFiles.push(file);
-    }
-  }
-
-  // Sort for deterministic first-match across platforms
-  cssFiles.sort();
-
-  for (const cssFile of cssFiles) {
-    try {
-      const content = readFileSync(cssFile, 'utf8');
-      const hasDesignTokens = /:root\s*\{[\s\S]*?--/.test(content);
-      if (hasDesignTokens) {
-        return {
-          hasDesignSystem: true,
-          path: cssFile,
-          isProjectLevel: true,
-          isFeatureLevel: false,
-          source: 'existing-css-variables'
-        };
-      }
-    } catch {
-      // Continue checking other files
-    }
-  }
-
-  // No design system found
-  return result;
-}
-
-/**
- * Get recommended design system locations based on project type
- * @param {string} projectPath - Root path of the project
- * @returns {Object} { markdown, css, description }
- */
-export function getRecommendedLocations(projectPath) {
-  try {
-    const configPath = join(projectPath, '.morph/config/config.json');
-
-    let projectType = 'unknown';
-    if (existsSync(configPath)) {
-      const config = JSON.parse(readFileSync(configPath, 'utf8'));
-      projectType = config.project?.type || 'unknown';
-    }
-
-    // Default locations
-    const locations = {
-      markdown: '.morph/context/design-system.md',
-      css: 'public/design-system.css',
-      description: 'Project-level design system (shared across features)'
-    };
-
-    // Adjust based on project type
-    if (projectType === 'nextjs' || projectType.includes('nextjs')) {
-      locations.css = 'styles/design-system.css';
-    }
-
-    return locations;
-  } catch {
-    return {
-      markdown: '.morph/context/design-system.md',
-      css: 'wwwroot/css/design-system.css',
-      description: 'Project-level design system (shared across features)'
-    };
-  }
-}