@polymorphism-tech/morph-spec 4.7.1 → 4.8.1

package/scripts/bump-version.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+
+/**
+ * Version Bump Script for MORPH-SPEC Framework
+ *
+ * Updates the version number across all files that contain it.
+ * Single source of truth: package.json
+ *
+ * Usage:
+ *   node scripts/bump-version.js patch       # 4.8.0 → 4.8.1
+ *   node scripts/bump-version.js minor       # 4.8.0 → 4.9.0
+ *   node scripts/bump-version.js major       # 4.8.0 → 5.0.0
+ *   node scripts/bump-version.js 4.9.0       # explicit version
+ *   node scripts/bump-version.js --dry-run patch  # preview changes
+ *
+ * npm script:
+ *   npm run version:bump -- patch
+ *   npm run version:bump -- --dry-run minor
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { glob } from 'glob';
+
+// ── Exported helpers (used by tests) ─────────────────────────────────
+
+/**
+ * Compute a new version from a current version and bump type.
+ * @param {string} current - Current semver (e.g. "4.8.0")
+ * @param {string} type - "patch", "minor", "major", or explicit "X.Y.Z"
+ * @returns {string} New version string
+ */
+export function bumpVersion(current, type) {
+  const [major, minor, patch] = current.split('.').map(Number);
+  switch (type) {
+    case 'major': return `${major + 1}.0.0`;
+    case 'minor': return `${major}.${minor + 1}.0`;
+    case 'patch': return `${major}.${minor}.${patch + 1}`;
+    default: {
+      if (/^\d+\.\d+\.\d+$/.test(type)) return type;
+      throw new Error(`Invalid version or bump type: "${type}". Expected: patch, minor, major, or X.Y.Z`);
+    }
+  }
+}
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Build the list of file updates for a version bump.
+ * @param {string} rootDir - Project root directory
+ * @param {string} currentVersion - Current version string
+ * @param {string} newVersion - Target version string
+ * @returns {Array<{file: string, replacements: Array<{pattern: RegExp, replacement: string}>}>}
+ */
+export function buildFileUpdates(rootDir, currentVersion, newVersion) {
+  const cv = escapeRegex(currentVersion);
+
+  const updates = [
+    {
+      file: 'package.json',
+      replacements: [
+        { pattern: new RegExp(`"version":\\s*"${cv}"`), replacement: `"version": "${newVersion}"` },
+      ],
+    },
+    {
+      file: 'claude-plugin.json',
+      replacements: [
+        { pattern: new RegExp(`"version":\\s*"${cv}"`), replacement: `"version": "${newVersion}"` },
+      ],
+    },
+    {
+      file: 'README.md',
+      replacements: [
+        { pattern: new RegExp(`\\*\\*Version:\\*\\*\\s*${cv}`), replacement: `**Version:** ${newVersion}` },
+        { pattern: new RegExp(`morph-spec v${cv}`), replacement: `morph-spec v${newVersion}` },
+      ],
+    },
+    {
+      file: 'docs/ARCHITECTURE.md',
+      replacements: [
+        { pattern: new RegExp(`morph-spec v${cv}`, 'g'), replacement: `morph-spec v${newVersion}` },
+      ],
+    },
+    {
+      file: 'docs/CHEATSHEET.md',
+      replacements: [
+        { pattern: new RegExp(`morph-spec v${cv}`), replacement: `morph-spec v${newVersion}` },
+      ],
+    },
+    {
+      file: 'docs/COMMAND-FLOWS.md',
+      replacements: [
+        { pattern: new RegExp(`Version:\\s*${cv}`), replacement: `Version: ${newVersion}` },
+        { pattern: new RegExp(`morph-spec v${cv}`), replacement: `morph-spec v${newVersion}` },
+      ],
+    },
+    {
+      file: 'docs/QUICKSTART.md',
+      replacements: [
+        { pattern: new RegExp(`morph-spec v${cv}`), replacement: `morph-spec v${newVersion}` },
+      ],
+    },
+    {
+      file: 'framework/hooks/dev/guard-version-numbers.js',
+      replacements: [
+        { pattern: new RegExp(`MORPH-SPEC v${cv}`), replacement: `MORPH-SPEC v${newVersion}` },
+      ],
+    },
+  ];
+
+  // Skill files (cliVersion in YAML frontmatter)
+  const skillFiles = glob.sync('framework/skills/level-1-workflows/*/SKILL.md', { cwd: rootDir });
+  for (const sf of skillFiles) {
+    updates.push({
+      file: sf,
+      replacements: [
+        { pattern: new RegExp(`cliVersion:\\s*"${cv}"`), replacement: `cliVersion: "${newVersion}"` },
+      ],
+    });
+  }
+
+  return updates;
+}
+
+/**
+ * Apply version updates to files on disk.
+ * @param {string} rootDir - Project root directory
+ * @param {Array} fileUpdates - From buildFileUpdates()
+ * @param {{ dryRun?: boolean }} options
+ * @returns {{ updatedCount: number, replacementCount: number, warnings: string[] }}
+ */
+export function applyUpdates(rootDir, fileUpdates, { dryRun = false } = {}) {
+  let updatedCount = 0;
+  let replacementCount = 0;
+  const warnings = [];
+
+  for (const { file, replacements } of fileUpdates) {
+    const fullPath = join(rootDir, file);
+
+    if (!existsSync(fullPath)) {
+      warnings.push(`SKIP ${file} (file not found)`);
+      continue;
+    }
+
+    let content = readFileSync(fullPath, 'utf-8');
+    let fileChanged = false;
+
+    for (const { pattern, replacement } of replacements) {
+      if (pattern.test(content)) {
+        content = content.replace(pattern, replacement);
+        fileChanged = true;
+        replacementCount++;
+      }
+    }
+
+    if (fileChanged) {
+      if (!dryRun) {
+        writeFileSync(fullPath, content, 'utf-8');
+      }
+      updatedCount++;
+    } else {
+      warnings.push(`${file} (no matches — pattern may have changed)`);
+    }
+  }
+
+  return { updatedCount, replacementCount, warnings };
+}
+
+// ── CLI entry point ──────────────────────────────────────────────────
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const isMainModule = process.argv[1]?.replace(/\\/g, '/').endsWith('scripts/bump-version.js');
+
+if (isMainModule) {
+  const ROOT = join(__dirname, '..');
+  const args = process.argv.slice(2);
+  const dryRun = args.includes('--dry-run');
+  const filtered = args.filter(a => a !== '--dry-run');
+
+  if (filtered.length === 0) {
+    console.error(
+      'Usage: node scripts/bump-version.js [--dry-run] <patch|minor|major|X.Y.Z>'
+    );
+    process.exit(1);
+  }
+
+  const input = filtered[0];
+  const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8'));
+  const currentVersion = pkg.version;
+
+  let newVersion;
+  try {
+    newVersion = bumpVersion(currentVersion, input);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  if (newVersion === currentVersion) {
+    console.log(`Version is already ${currentVersion}. Nothing to do.`);
+    process.exit(0);
+  }
+
+  console.log(`\nBumping version: ${currentVersion} → ${newVersion}`);
+  if (dryRun) console.log('(dry run — no files will be modified)\n');
+  else console.log('');
+
+  const fileUpdates = buildFileUpdates(ROOT, currentVersion, newVersion);
+  const result = applyUpdates(ROOT, fileUpdates, { dryRun });
+
+  for (const file of fileUpdates) {
+    const fullPath = join(ROOT, file.file);
+    if (existsSync(fullPath)) {
+      const content = readFileSync(fullPath, 'utf-8');
+      const hasMatch = file.replacements.some(r =>
+        dryRun
+          ? new RegExp(escapeRegex(currentVersion)).test(content)
+          : new RegExp(escapeRegex(newVersion)).test(content)
+      );
+      if (hasMatch) console.log(`  ✓ ${file.file}`);
+    }
+  }
+
+  console.log('');
+  if (result.warnings.length > 0) {
+    console.log('Warnings:');
+    for (const w of result.warnings) console.log(`  ⚠ ${w}`);
+    console.log('');
+  }
+
+  console.log(
+    `${dryRun ? 'Would update' : 'Updated'} ${result.updatedCount} files (${result.replacementCount} replacements).`
+  );
+
+  if (dryRun) {
+    console.log('\nRe-run without --dry-run to apply changes.');
+  } else {
+    console.log(`\nVersion is now ${newVersion}.`);
+    console.log('Next steps:');
+    console.log('  1. Review changes: git diff');
+    console.log(`  2. Commit: git commit -am "chore: bump version to ${newVersion}"`);
+    console.log(`  3. Tag: git tag v${newVersion}`);
+    console.log('  4. Publish: npm publish');
+  }
+}

package/scripts/install-dev-hooks.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+
+/**
+ * Dev Hooks Installer for MORPH-SPEC Framework Codebase
+ *
+ * Installs development-only hooks into .claude/settings.local.json.
+ * These hooks enforce quality standards when developing the framework itself:
+ *   - Version number guard (no hardcoded versions in .md files)
+ *   - Standard format validator (required metadata headers)
+ *   - Skill frontmatter validator (required YAML fields)
+ *   - Template registry sync advisory
+ *   - Standards registry sync advisory
+ *   - Sync health check advisory on Stop
+ *
+ * Usage: node scripts/install-dev-hooks.js
+ *
+ * Dev hooks use _morph_dev:true marker (not _morph:true) so they survive
+ * `morph-spec init/update` reinstalls, which only remove _morph:true entries.
+ */
+
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Dev hook definitions.
+ * Commands reference framework/hooks/dev/ directly (not .morph/framework/)
+ * since they only run in the framework repo where this path exists.
+ */
+const DEV_HOOKS = [
+  {
+    event: 'PreToolUse',
+    matcher: 'Write|Edit',
+    hooks: [
+      { type: 'command', command: 'node framework/hooks/dev/guard-version-numbers.js' },
+      { type: 'command', command: 'node framework/hooks/dev/validate-standard-format.js' },
+      { type: 'command', command: 'node framework/hooks/dev/validate-skill-format.js' },
+    ]
+  },
+  {
+    event: 'PostToolUse',
+    matcher: 'Write',
+    hooks: [
+      { type: 'command', command: 'node framework/hooks/dev/sync-template-registry.js' },
+      { type: 'command', command: 'node framework/hooks/dev/sync-standards-registry.js' },
+    ]
+  },
+  {
+    event: 'Stop',
+    matcher: null,
+    hooks: [
+      { type: 'command', command: 'node framework/hooks/dev/check-sync-health.js' },
+    ]
+  },
+];
+
+/**
+ * Install dev hooks into .claude/settings.local.json.
+ * Preserves _morph:true entries and user hooks.
+ * Removes old _morph_dev:true entries before installing (clean slate).
+ *
+ * @param {string} [projectPath] - Project root (defaults to cwd)
+ * @returns {Promise<{ installed: number }>}
+ */
+export async function installDevHooks(projectPath) {
+  const root = projectPath || process.cwd();
+  const claudeDir = join(root, '.claude');
+  const settingsPath = join(claudeDir, 'settings.local.json');
+
+  // Read existing settings
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  settings.hooks = settings.hooks || {};
+
+  // Remove old dev hooks (clean slate)
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(entries)) continue;
+    settings.hooks[event] = entries.filter(entry => entry._morph_dev !== true);
+    if (settings.hooks[event].length === 0) {
+      delete settings.hooks[event];
+    }
+  }
+
+  // Install dev hooks
+  let installed = 0;
+  for (const hookDef of DEV_HOOKS) {
+    const { event, matcher, hooks } = hookDef;
+
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = [];
+    }
+
+    const entry = { _morph_dev: true };
+    if (matcher) {
+      entry.matcher = matcher;
+    }
+    entry.hooks = hooks.map(h => ({ type: h.type, command: h.command }));
+
+    settings.hooks[event].push(entry);
+    installed++;
+  }
+
+  // Ensure .claude directory exists
+  if (!existsSync(claudeDir)) {
+    await mkdir(claudeDir, { recursive: true });
+  }
+
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  return { installed };
+}
+
+/**
+ * Get the dev hooks definitions (for testing/inspection).
+ * @returns {Array}
+ */
+export function getDevHookDefinitions() {
+  return DEV_HOOKS;
+}
+
+// CLI entry point
+const isMainModule = process.argv[1]?.replace(/\\/g, '/').endsWith('scripts/install-dev-hooks.js');
+if (isMainModule) {
+  try {
+    const result = await installDevHooks();
+    console.log(`Installed ${result.installed} dev hooks into .claude/settings.local.json`);
+    console.log('Dev hooks are active for framework development only (_morph_dev: true).');
+  } catch (err) {
+    console.error('Failed to install dev hooks:', err.message);
+    process.exit(1);
+  }
+}

package/src/commands/agents/index.js

@@ -1,4 +1,3 @@
 /**
- * Agent Team Commands
+ * Agent Commands — no active commands after CLI simplification
  */
-export { spawnTeamCommand } from './spawn-team.js';

package/src/commands/index.js

@@ -1,16 +1,13 @@
-/**
- * All Commands - Category Exports
- *
- * Commands organized by functional category.
- */
-
-export * from './feature/index.js';
-export * from './state/index.js';
-export * from './generation/index.js';
-export * from './validation/index.js';
-export * from './templates/index.js';
-export * from './project/index.js';
-export * from './learning/index.js';
-export * from './tasks/index.js';
-export * from './agents/index.js';
-export * from './utils/index.js';
+/**
+ * All Commands - Category Exports
+ *
+ * Commands organized by functional category.
+ */
+
+export * from './state/index.js';
+export * from './validation/index.js';
+export * from './templates/index.js';
+export * from './project/index.js';
+export * from './tasks/index.js';
+export * from './agents/index.js';
+export * from './utils/index.js';

package/src/commands/project/doctor.js

@@ -1,6 +1,6 @@
 import { join } from 'path';
 import { execSync } from 'child_process';
-import { platform } from 'os';
+import { platform, homedir } from 'os';
 import fs from 'fs-extra';
 import chalk from 'chalk';
 import { logger } from '../../utils/logger.js';
@@ -13,6 +13,18 @@ import {
 import { resetMorphSettings } from '../../utils/claude-settings-manager.js';
 
 const isWindows = platform() === 'win32';
+/**
+ * Check which required Claude Code plugins are installed.
+ * @param {Object} pluginsData - The `plugins` object from installed_plugins.json
+ * @returns {{ superpowers: boolean, context7: boolean }}
+ */
+export function checkInstalledPlugins(pluginsData) {
+  const REQUIRED = ['superpowers', 'context7'];
+  return Object.fromEntries(
+    REQUIRED.map(name => [name, `${name}@claude-plugins-official` in (pluginsData || {})])
+  );
+}
+
 
 /**
  * Check if morph-spec command is in PATH
@@ -72,18 +84,20 @@ const REQUIRED_LIB_FILES = [
   'src/lib/trust/trust-manager.js'
 ];
 
-// command files
+// command files (current CLI surface after radical simplification)
 const REQUIRED_COMMAND_FILES = [
-  'src/commands/agents/agents-fuse.js',
-  'src/commands/analytics/analytics.js',
-  'src/commands/context/context-prime.js',
-  'src/commands/context/core-four.js',
-  'src/commands/mcp/mcp.js',
-  'src/commands/agents/micro-agent.js',
-  'src/commands/agents/squad-template.js',
-  'src/commands/threads/thread-template.js',
-  'src/commands/threads/threads.js',
-  'src/commands/trust/trust.js'
+  'src/commands/project/init.js',
+  'src/commands/project/update.js',
+  'src/commands/project/doctor.js',
+  'src/commands/project/status.js',
+  'src/commands/project/tutorial.js',
+  'src/commands/state/state.js',
+  'src/commands/state/advance-phase.js',
+  'src/commands/state/approve.js',
+  'src/commands/tasks/task.js',
+  'src/commands/trust/trust.js',
+  'src/commands/validation/validate-feature.js',
+  'src/commands/templates/template-render.js'
 ];
 
 // HOP templates (meta-prompts)
@@ -227,9 +241,9 @@ async function doctorFullCommand(frameworkRoot) {
   if (await pathExists(statePath)) {
     try {
       const state = JSON.parse(await fs.readFile(statePath, 'utf8'));
-      const isCurrent = state.version === '3.0.0';
+      const isCurrent = state.version === '5.0.0';
       check(`state.json schema (${state.version})`, isCurrent, true,
-        isCurrent ? '' : 'run: morph-spec state init --force');
+        isCurrent ? '' : `expected 5.0.0, found ${state.version} — run any CLI command to auto-migrate`);
     } catch {
       check('state.json parse', false, false, 'invalid JSON');
     }
@@ -558,6 +572,78 @@ export async function doctorCommand(options = {}) {
         checks.push({ name: '.claude/agents/', status: 'warn', msg: 'missing — run morph-spec update' });
         hasWarnings = true;
       }
+      // ── Hook health: verify hook scripts exist ───────────────────────────────
+      const settingsLocalPath = join(claudePath, 'settings.local.json');
+      if (await pathExists(settingsLocalPath)) {
+        try {
+          const settings = JSON.parse(await fs.readFile(settingsLocalPath, 'utf8'));
+          const hookCommands = [];
+          for (const eventHooks of Object.values(settings.hooks || {})) {
+            for (const group of (Array.isArray(eventHooks) ? eventHooks : [])) {
+              for (const h of (group.hooks || [])) {
+                if (h.type === 'command' && h.command) hookCommands.push(h.command);
+              }
+            }
+          }
+          const hookPathRe = /\$CLAUDE_PROJECT_DIR\/([^\s"]+\.js)/;
+          const missingHooks = [];
+          for (const cmd of hookCommands) {
+            const m = cmd.match(hookPathRe);
+            if (m && !(await pathExists(join(targetPath, m[1])))) {
+              missingHooks.push(m[1].split('/').pop());
+            }
+          }
+          if (missingHooks.length === 0) {
+            checks.push({ name: 'hook scripts', status: 'ok', msg: `${hookCommands.length} hooks configured` });
+          } else {
+            checks.push({ name: 'hook scripts', status: 'warn', msg: `missing: ${missingHooks.join(', ')} — run morph-spec update` });
+            hasWarnings = true;
+          }
+        } catch {
+          checks.push({ name: 'hook scripts', status: 'warn', msg: 'could not parse settings.local.json' });
+          hasWarnings = true;
+        }
+      } else {
+        checks.push({ name: 'hook scripts', status: 'warn', msg: 'settings.local.json missing — run morph-spec init' });
+        hasWarnings = true;
+      }
+
+      // ── Skills cliVersion: warn if installed skills reference older CLI ──────
+      try {
+        const cliVersion = getInstalledCLIVersion();
+        if (cliVersion) {
+          const skillDirsForVersion = await fs.readdir(skillsPath);
+          const staleSkills = [];
+          for (const skillDir of skillDirsForVersion) {
+            const skillMdPath = join(skillsPath, skillDir, 'SKILL.md');
+            if (!(await pathExists(skillMdPath))) continue;
+            const content = await fs.readFile(skillMdPath, 'utf8');
+            const m = content.match(/^cliVersion:\s*"?([^"\n]+)"?/m);
+            if (m && m[1].trim() !== cliVersion) {
+              staleSkills.push(skillDir);
+            }
+          }
+          if (staleSkills.length === 0) {
+            checks.push({ name: 'skill cliVersion', status: 'ok' });
+          } else {
+            checks.push({ name: 'skill cliVersion', status: 'warn', msg: `${staleSkills.length} skill(s) behind CLI v${cliVersion} — run morph-spec update` });
+            hasWarnings = true;
+          }
+        }
+      } catch { /* non-fatal */ }
+
+      // ── Claude Code Plugins ──────────────────────────────────────────────────
+      console.log(chalk.cyan('\n  Claude Code Plugins (required for /morph-init)'));
+      const pluginsFile = join(homedir(), '.claude', 'plugins', 'installed_plugins.json');
+      let pluginData = { plugins: {} };
+      try {
+        pluginData = JSON.parse(await fs.readFile(pluginsFile, 'utf8'));
+      } catch { /* file may not exist */ }
+      const pluginStatus = checkInstalledPlugins(pluginData.plugins || {});
+      check('superpowers plugin', pluginStatus.superpowers, false,
+        'Run: morph-spec install-plugin superpowers');
+      check('context7 plugin', pluginStatus.context7, false,
+        'Run: morph-spec install-plugin context7');
     } else {
       checks.push({ name: '.claude/', status: 'warn', msg: 'incomplete structure' });
     }

package/src/commands/project/index.js

@@ -1,10 +1,7 @@
-/**
- * Project-Level Commands
- */
-export { initCommand } from './init.js';
-export { doctorCommand } from './doctor.js';
-export { detectCommand } from './detect.js';
-export { detectWorkflowCommand } from './detect-workflow.js';
-export { detectAgentsCommand } from './detect-agents.js';
-export { syncCommand } from './sync.js';
-export { updateCommand } from './update.js';
+/**
+ * Project-Level Commands
+ */
+export { initCommand } from './init.js';
+export { doctorCommand } from './doctor.js';
+export { updateCommand } from './update.js';
+export { tutorialCommand } from './tutorial.js';