@polymorphism-tech/morph-spec 9.0.0 → 9.2.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/framework/hooks/git/commit-msg/conventional-commits.sh

@@ -1,33 +0,0 @@
-#!/usr/bin/env bash
-# Scope: universal | Validates commit message format (Conventional Commits)
-# MORPH-SPEC Commit Message Hook
-# Enforces Conventional Commits specification
-
-COMMIT_MSG_FILE="$1"
-COMMIT_MSG=$(cat "$COMMIT_MSG_FILE")
-
-# Conventional Commits pattern: type(scope): description
-# Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert
-PATTERN="^(feat|fix|docs|style|refactor|perf|test|chore|build|ci|revert)(\(.+\))?: .{1,100}"
-
-if ! echo "$COMMIT_MSG" | grep -qE "$PATTERN"; then
-  echo "❌ Invalid commit message format!"
-  echo ""
-  echo "Required format: <type>(<scope>): <description>"
-  echo ""
-  echo "Types: feat, fix, docs, style, refactor, perf, test, chore, build, ci, revert"
-  echo ""
-  echo "Examples:"
-  echo "  feat(auth): add JWT refresh token rotation"
-  echo "  fix(api): resolve null reference in UserService"
-  echo "  docs(readme): update installation instructions"
-  echo ""
-  echo "Your message:"
-  echo "  $COMMIT_MSG"
-  echo ""
-  echo "Override with: git commit --no-verify"
-  exit 1
-fi
-
-echo "✅ Commit message format valid"
-exit 0

package/framework/hooks/git/pre-commit/agents.sh

@@ -1,25 +0,0 @@
-#!/bin/bash
-# Scope: universal | Validates agents.json Schema
-# MORPH-SPEC Pre-Commit Hook: Agent Configuration Validation
-# Uses validate-agents.js to check agents.json
-
-echo "🤖 Validating agent configuration..."
-
-# Check if agents.json is being modified
-if git diff --cached --name-only | grep -q 'agents\.json$'; then
-  echo "Detected changes to agents.json"
-
-  # Run validator
-  if ! morph-spec validate-agents-skills; then
-    echo ""
-    echo "❌ COMMIT BLOCKED: agents.json validation failed"
-    echo "   Fix errors above before committing"
-    exit 1
-  fi
-
-  echo "✓ agents.json is valid"
-else
-  echo "✓ No changes to agents.json"
-fi
-
-exit 0

package/framework/hooks/git/pre-commit/orchestrator.sh

@@ -1,64 +0,0 @@
-#!/usr/bin/env bash
-# Scope: universal | Orchestrates framework + stack-specific pre-commit hooks
-# MORPH-SPEC Master Pre-Commit Hook
-# Runs universal framework hooks + stack-specific hooks in sequence
-
-echo "╔════════════════════════════════════════════════╗"
-echo "║     MORPH-SPEC PRE-COMMIT VALIDATION           ║"
-echo "╚════════════════════════════════════════════════╝"
-echo ""
-
-FRAMEWORK_HOOKS_DIR="$(dirname "$0")"
-STACK_HOOKS_DIR=".morph/hooks/pre-commit"
-
-HAS_FAILURES=false
-
-# Run framework hooks (universal - all stacks)
-echo "📦 Running framework hooks (universal)..."
-for hook in "$FRAMEWORK_HOOKS_DIR"/*.sh; do
-  # Skip orchestrator itself
-  if [[ "$hook" == */orchestrator.sh ]]; then
-    continue
-  fi
-
-  if [[ -f "$hook" ]]; then
-    hook_name=$(basename "$hook")
-    echo "─────────────────────────────────────────────────"
-    if ! bash "$hook"; then
-      HAS_FAILURES=true
-      echo "❌ Framework hook failed: $hook_name"
-    fi
-    echo ""
-  fi
-done
-
-# Run stack-specific hooks (if exist)
-if [[ -d "$STACK_HOOKS_DIR" ]]; then
-  echo "🎯 Running stack-specific hooks..."
-  for hook in "$STACK_HOOKS_DIR"/*.sh; do
-    if [[ -f "$hook" ]]; then
-      hook_name=$(basename "$hook")
-      echo "─────────────────────────────────────────────────"
-      if ! bash "$hook"; then
-        HAS_FAILURES=true
-        echo "❌ Stack hook failed: $hook_name"
-      fi
-      echo ""
-    fi
-  done
-else
-  echo "ℹ️  No stack-specific hooks found (optional)"
-  echo ""
-fi
-
-echo "═════════════════════════════════════════════════"
-
-if [[ "$HAS_FAILURES" == "true" ]]; then
-  echo "❌ PRE-COMMIT VALIDATION FAILED"
-  echo "   Fix errors above before committing"
-  echo "   Or use: git commit --no-verify to skip"
-  exit 1
-fi
-
-echo "✅ ALL PRE-COMMIT VALIDATIONS PASSED"
-exit 0

package/framework/hooks/git/pre-push/run-tests.sh

@@ -1,44 +0,0 @@
-#!/usr/bin/env bash
-# Scope: universal | Runs test suite before push
-# MORPH-SPEC Pre-Push Hook
-# Ensures all tests pass before pushing to remote
-
-echo "🧪 Running test suite before push..."
-echo ""
-
-# Detect project type and run appropriate tests
-if [[ -f *.csproj ]] || find . -maxdepth 2 -name "*.csproj" 2>/dev/null | grep -q .; then
-  # .NET project detected
-  echo "📦 Detected .NET project"
-
-  if ! dotnet test --verbosity minimal --no-build --no-restore 2>/dev/null; then
-    echo ""
-    echo "❌ .NET tests failed!"
-    echo ""
-    echo "Fix failing tests before pushing."
-    echo "Override with: git push --no-verify"
-    exit 1
-  fi
-
-elif [[ -f package.json ]]; then
-  # Node.js project detected
-  echo "📦 Detected Node.js project"
-
-  if ! npm test 2>/dev/null; then
-    echo ""
-    echo "❌ Node.js tests failed!"
-    echo ""
-    echo "Fix failing tests before pushing."
-    echo "Override with: git push --no-verify"
-    exit 1
-  fi
-
-else
-  echo "⚠️  No recognized test framework found"
-  echo "   Skipping test execution"
-  exit 0
-fi
-
-echo ""
-echo "✅ All tests passed - safe to push"
-exit 0

package/src/commands/utils/index.js

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