@polymorphism-tech/morph-spec 4.3.7 → 4.6.0

package/src/utils/hooks-installer.js

@@ -1,23 +1,166 @@
 /**
- * Claude Code Hooks Installer
+ * Claude Code Hooks Installer (v2)
  *
- * Merges the MORPH-SPEC agent-teams PostToolUse hook into
- * .claude/settings.local.json without overwriting existing config.
+ * Registry-based installer for all MORPH-SPEC Claude Code hooks.
+ * Declarative MORPH_HOOKS array defines all hooks.
+ * Idempotent merge into .claude/settings.local.json.
  *
  * Called by `morph-spec init` and `morph-spec update`.
  */
 
 import { join } from 'path';
-import { readFile, writeFile, mkdir } from 'fs/promises';
-import { existsSync } from 'fs';
+import { readFile, writeFile, mkdir, copyFile } from 'fs/promises';
+import { existsSync, chmodSync } from 'fs';
+import { homedir } from 'os';
 
-const DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
+/** Current hooks schema version — bump when hook definitions change */
+const HOOKS_VERSION = '2.4.0';
+
+/** Marker for old dispatch.js (v1) */
+const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
+
+/**
+ * Native permissions.deny entries managed by MORPH-SPEC.
+ * These replace the protect-readonly-files.js PreToolUse hook,
+ * using Claude Code's built-in permissions system instead.
+ */
+const MORPH_PERMISSIONS = [
+  'Write(.morph/state.json)',
+  'Edit(.morph/state.json)',
+  'Write(.morph/framework/**)',
+  'Edit(.morph/framework/**)',
+];
+
+/**
+ * All MORPH-SPEC hook definitions.
+ * Each entry maps to a Claude Code hook event.
+ */
+const MORPH_HOOKS = [
+  // === SessionStart ===
+  {
+    event: 'SessionStart',
+    matcher: 'startup|resume|compact',
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/session-start/inject-morph-context.js'
+    }]
+  },
+
+  // === UserPromptSubmit ===
+  {
+    event: 'UserPromptSubmit',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/user-prompt/enrich-prompt.js'
+    }]
+  },
+
+  // === PreToolUse: Write|Edit ===
+  {
+    event: 'PreToolUse',
+    matcher: 'Write|Edit',
+    hooks: [
+      // Note: protect-readonly-files.js replaced by native permissions.deny (see MORPH_PERMISSIONS)
+      // Order matters: cheapest check first
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/pre-tool-use/protect-spec-files.js'
+      },
+      {
+        type: 'command',
+        command: 'node framework/hooks/claude-code/pre-tool-use/enforce-phase-writes.js'
+      }
+    ]
+  },
+
+  // === PreToolUse: Bash ===
+  {
+    event: 'PreToolUse',
+    matcher: 'Bash',
+    hooks: [{
+      type: 'prompt',
+      prompt: `You are a guard for a morph-spec project. Read the bash command from the hook input and check:
+1. Does the command delete .morph/ (e.g. contains "rm" with "-r" or "-rf" and ".morph")? If yes, BLOCK.
+2. Does the command edit state.json directly via sed, jq, awk, echo, cat, or printf with a shell redirect (>)? If yes, BLOCK.
+3. Does the command write to .morph/framework/ via a shell redirect (>)? If yes, BLOCK.
+If any condition is true, respond: {"ok": false, "reason": "MORPH-SPEC: <brief explanation and suggested alternative using morph-spec CLI>"}
+Otherwise respond: {"ok": true}`
+    }]
+  },
+
+  // === PostToolUse: Bash ===
+  {
+    event: 'PostToolUse',
+    matcher: 'Bash',
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/post-tool-use/dispatch.js'
+    }]
+  },
+
+  // === Stop ===
+  {
+    event: 'Stop',
+    matcher: null,
+    hooks: [{
+      type: 'agent',
+      prompt: `Check if the active morph-spec feature phase outputs are complete.
+1. Read the file .morph/state.json to find features with status "in_progress".
+2. For each in_progress feature, check if required output files for the current phase exist and are non-empty.
+   - proposal phase: .morph/features/{feature}/0-proposal/proposal.md
+   - design phase: .morph/features/{feature}/1-design/spec.md
+   - tasks phase: .morph/features/{feature}/3-tasks/tasks.md
+   - implement phase: check tasks.completed vs tasks.total from state.json
+3. If all required outputs exist and tasks are complete, return {"ok": true}.
+4. If any required output is missing or empty, return {"ok": false, "reason": "Missing output: <path>"}.
+5. If state.json does not exist or no feature is in_progress, return {"ok": true}.
+Do NOT modify any files. Read only.`,
+      timeout: 60
+    }]
+  },
+
+  // === PreCompact ===
+  {
+    event: 'PreCompact',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/pre-compact/save-morph-context.js'
+    }]
+  },
+
+  // === PostToolUseFailure ===
+  {
+    event: 'PostToolUseFailure',
+    matcher: null,
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/post-tool-use/handle-tool-failure.js',
+      timeout: 10000,
+    }]
+  },
+
+  // === Notification ===
+  {
+    event: 'Notification',
+    matcher: 'idle_prompt',
+    hooks: [{
+      type: 'command',
+      command: 'node framework/hooks/claude-code/notification/approval-reminder.js'
+    }]
+  }
+];
 
 /**
- * Install or update the MORPH-SPEC PostToolUse hook in .claude/settings.local.json.
+ * Install or update all MORPH-SPEC hooks in .claude/settings.local.json.
+ *
+ * - Idempotent: safe to call multiple times
+ * - Removes old v1 dispatch.js entry if present
+ * - Tracks installed version via _morph_managed.hooks_version
  *
  * @param {string} targetPath - Project root directory
- * @returns {boolean} true if the hook was newly added, false if it was already present
+ * @returns {Promise<{ installed: number, updated: boolean }>}
  */
 export async function installClaudeHooks(targetPath) {
   const claudeDir = join(targetPath, '.claude');
@@ -29,35 +172,89 @@ export async function installClaudeHooks(targetPath) {
     try {
       settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
     } catch {
-      // Malformed JSON — start fresh to avoid corrupting the file
       settings = {};
     }
   }
 
-  // Ensure hooks.PostToolUse array exists
   settings.hooks = settings.hooks || {};
-  settings.hooks.PostToolUse = settings.hooks.PostToolUse || [];
 
-  // Check if dispatch.js is already registered (avoid duplicate entries)
-  const alreadyRegistered = settings.hooks.PostToolUse.some(entry =>
-    Array.isArray(entry.hooks) &&
-    entry.hooks.some(h => h.command === DISPATCH_COMMAND)
+  // Check if already at current version
+  const managed = settings._morph_managed || {};
+  const alreadyCurrent = managed.hooks_version === HOOKS_VERSION;
+
+  // Remove old v1 dispatch.js entry
+  removeOldDispatch(settings);
+
+  // Remove all morph-managed hooks (clean slate for idempotent update)
+  removeMorphHooks(settings);
+
+  // Install all hooks from the registry
+  let installed = 0;
+  for (const hookDef of MORPH_HOOKS) {
+    const { event, matcher, hooks } = hookDef;
+
+    if (!settings.hooks[event]) {
+      settings.hooks[event] = [];
+    }
+
+    const entry = { _morph: true };
+    if (matcher) {
+      entry.matcher = matcher;
+    }
+    entry.hooks = hooks.map(h => {
+      // Agent and prompt hooks: pass through as-is (no command path transform)
+      if (h.type === 'agent' || h.type === 'prompt') {
+        const agentHook = { type: h.type, prompt: h.prompt };
+        if (h.timeout !== undefined) agentHook.timeout = h.timeout;
+        return agentHook;
+      }
+      // Command hooks: transform path to use $CLAUDE_PROJECT_DIR
+      return {
+        type: h.type,
+        command: `node "$CLAUDE_PROJECT_DIR/framework/hooks/claude-code/${getHookSubpath(h.command)}"`,
+        ...(h.timeout !== undefined ? { timeout: h.timeout } : {})
+      };
+    });
+
+    settings.hooks[event].push(entry);
+    installed++;
+  }
+
+  // Install native permissions.deny entries (idempotent)
+  settings.permissions = settings.permissions || {};
+  settings.permissions.deny = settings.permissions.deny || [];
+  // Remove previously managed permissions to avoid duplicates on re-install
+  settings.permissions.deny = settings.permissions.deny.filter(
+    p => !MORPH_PERMISSIONS.includes(p)
   );
+  for (const perm of MORPH_PERMISSIONS) {
+    settings.permissions.deny.push(perm);
+  }
+
+  // JSON Schema for IDE auto-complete and validation
+  settings['$schema'] = 'https://json.schemastore.org/claude-code-settings.json';
 
-  if (alreadyRegistered) {
-    return false;
+  // Environment variables — always set MORPH_SPEC_ACTIVE, preserve user additions
+  settings.env = { ...settings.env, MORPH_SPEC_ACTIVE: 'true' };
+
+  // Attribution — only set if not already customized by user
+  if (!settings.attribution) {
+    settings.attribution = {
+      commit: '🤖 Co-authored by MORPH-SPEC',
+      pr: '',
+    };
   }
 
-  // Add the agent-teams dispatch hook
-  settings.hooks.PostToolUse.push({
-    matcher: 'Bash',
-    hooks: [
-      {
-        type: 'command',
-        command: DISPATCH_COMMAND
-      }
-    ]
-  });
+  // Plans directory for Claude Code plan mode
+  if (!settings.plansDirectory) {
+    settings.plansDirectory = '.morph/plans';
+  }
+
+  // Track installed hooks version
+  settings._morph_managed = settings._morph_managed || {};
+  settings._morph_managed.hooks_version = HOOKS_VERSION;
+  settings._morph_managed.hooks_installed = [...new Set(MORPH_HOOKS.map(h => h.event))];
+  settings._morph_managed.generated_at = new Date().toISOString();
 
   // Ensure .claude directory exists
   if (!existsSync(claudeDir)) {
@@ -65,5 +262,134 @@ export async function installClaudeHooks(targetPath) {
   }
 
   await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-  return true;
+  return { installed, updated: !alreadyCurrent };
+}
+
+/**
+ * Install the morph-spec statusline globally into ~/.claude/.
+ *
+ * Copies statusline.sh and statusline.py to ~/.claude/ and registers
+ * the statusLine config in ~/.claude/settings.json so it applies to
+ * every Claude Code session, not just morph-spec projects.
+ *
+ * Python 3 must be available as `python3` on PATH (global prerequisite).
+ *
+ * @param {string} hooksSourceDir - Path to framework/hooks/claude-code/
+ * @param {string} [globalClaudeDirOverride] - Override ~/.claude/ (for testing)
+ * @returns {Promise<{ installed: boolean, globalDir: string }>}
+ */
+export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOverride = null) {
+  const globalDir = globalClaudeDirOverride || join(homedir(), '.claude');
+  await mkdir(globalDir, { recursive: true });
+
+  // Copy statusline scripts to ~/.claude/
+  const scripts = ['statusline.sh', 'statusline.py'];
+  for (const fname of scripts) {
+    const src = join(hooksSourceDir, fname);
+    if (existsSync(src)) {
+      await copyFile(src, join(globalDir, fname));
+      if (process.platform !== 'win32') {
+        try { chmodSync(join(globalDir, fname), 0o755); } catch { /* non-critical */ }
+      }
+    }
+  }
+
+  // Register statusLine in ~/.claude/settings.json (global user settings)
+  const settingsPath = join(globalDir, 'settings.json');
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(await readFile(settingsPath, 'utf-8'));
+    } catch {
+      settings = {};
+    }
+  }
+
+  settings.statusLine = {
+    type: 'command',
+    command: join(globalDir, 'statusline.sh').replace(/\\/g, '/'),
+    padding: 2
+  };
+
+  await writeFile(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+  return { installed: true, globalDir };
+}
+
+/**
+ * Remove old v1 agent-teams/dispatch.js hook entries.
+ * @param {Object} settings
+ */
+function removeOldDispatch(settings) {
+  if (!settings.hooks?.PostToolUse) return;
+
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(entry => {
+    if (!Array.isArray(entry.hooks)) return true;
+    return !entry.hooks.some(h =>
+      h.command === OLD_DISPATCH_COMMAND ||
+      (typeof h.command === 'string' && h.command.includes('agent-teams/dispatch.js'))
+    );
+  });
+
+  if (settings.hooks.PostToolUse.length === 0) {
+    delete settings.hooks.PostToolUse;
+  }
+}
+
+/**
+ * Remove all morph-managed hook entries.
+ * Uses _morph:true marker (v2.2+) with legacy path-pattern fallback.
+ * Preserves any user-added hooks.
+ * @param {Object} settings
+ */
+function removeMorphHooks(settings) {
+  const morphPathPattern = /framework\/hooks\/claude-code\//;
+
+  for (const [event, entries] of Object.entries(settings.hooks)) {
+    if (!Array.isArray(entries)) continue;
+
+    settings.hooks[event] = entries.filter(entry => {
+      // Remove if explicitly marked as morph-managed
+      if (entry._morph === true) return false;
+
+      if (!Array.isArray(entry.hooks)) return true;
+      // Legacy path-pattern detection: remove if all hooks are morph command hooks
+      // Note: legacy path only covers command-type hooks (those with a path-matching command).
+      // Agent/prompt hooks without _morph marker are NOT removed by this fallback.
+      // This is acceptable since all morph hooks since v2.2.0 carry the _morph marker.
+      const nonMorphHooks = entry.hooks.filter(h =>
+        typeof h.command !== 'string' || !morphPathPattern.test(h.command)
+      );
+      return nonMorphHooks.length > 0;
+    });
+
+    if (settings.hooks[event].length === 0) {
+      delete settings.hooks[event];
+    }
+  }
+}
+
+/**
+ * Extract hook subpath from a full command string.
+ * @param {string} command - e.g., 'node framework/hooks/claude-code/stop/validate-completion.js'
+ * @returns {string} e.g., 'stop/validate-completion.js'
+ */
+function getHookSubpath(command) {
+  const match = command.match(/claude-code\/(.+)$/);
+  return match ? match[1] : command;
+}
+
+/**
+ * Get the current hooks version.
+ * @returns {string}
+ */
+export function getHooksVersion() {
+  return HOOKS_VERSION;
+}
+
+/**
+ * Get the list of hook definitions (for testing/inspection).
+ * @returns {Array}
+ */
+export function getHookDefinitions() {
+  return MORPH_HOOKS;
 }

package/src/utils/skills-installer.js

@@ -0,0 +1,118 @@
+/**
+ * Skills Installer
+ *
+ * Copies framework skills to .claude/skills/ during morph-spec init.
+ * Installs level-0-meta and level-1-workflows skills using the native Claude Code
+ * subdirectory format: .claude/skills/{skill-name}/SKILL.md (plus optional
+ * scripts/, references/, and assets/ subdirectories).
+ * Level-2 domain specialists are installed as native subagents via installDomainAgents().
+ * Level-3 and level-4 only contain README.md placeholder files and are skipped.
+ *
+ * Source skills can be either:
+ *   - Directory-based: framework/skills/{level}/{skill-name}/SKILL.md  (preferred)
+ *   - Flat file: framework/skills/{level}/{skill-name}.md               (legacy, still supported)
+ *
+ * Directory-based skills have their entire directory copied (scripts/, references/,
+ * assets/) so Claude Code can execute scripts and load references on demand.
+ */
+
+import { mkdirSync, copyFileSync, existsSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const FRAMEWORK_SKILLS_DIR = join(__dirname, '..', '..', 'framework', 'skills');
+
+/**
+ * Skill levels to install in .claude/skills/.
+ * Level-0 meta skills (planning, reviewing) and level-1 workflow skills
+ * (phase-design, phase-implement, etc.) are installed. Level-2 domain
+ * specialists are installed as native subagents via installDomainAgents()
+ * instead. Level-3 and level-4 are skipped (no content yet).
+ */
+const SKILL_LEVELS_TO_INSTALL = ['level-0-meta', 'level-1-workflows'];
+
+/**
+ * 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
+ *
+ * Level directories (level-0-meta, level-1-workflows, sub-categories) are
+ * 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/)
+ */
+function installSkillsFromDir(srcDir, destDir) {
+  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 — copy entire directory including scripts/, references/, assets/
+        const skillDestDir = join(destDir, entry);
+        copyDirectory(srcPath, skillDestDir);
+      } else {
+        // Level/category directory — recurse
+        installSkillsFromDir(srcPath, destDir);
+      }
+    } else if (entry.endsWith('.md') && entry !== 'README.md') {
+      // Legacy flat .md skill — wrap in subdirectory as SKILL.md
+      const skillName = entry.slice(0, -3);
+      const skillDir = join(destDir, skillName);
+      mkdirSync(skillDir, { recursive: true });
+      copyFileSync(srcPath, join(skillDir, 'SKILL.md'));
+    }
+  }
+}
+
+/**
+ * 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,
+ * /blazor-builder). Directory-based skills also get their scripts/,
+ * references/, and assets/ subdirectories copied for on-demand loading.
+ *
+ * @param {string} projectDir - Target project root directory
+ */
+export async function installSkills(projectDir) {
+  const claudeSkillsDir = join(projectDir, '.claude', 'skills');
+  mkdirSync(claudeSkillsDir, { recursive: true });
+
+  for (const level of SKILL_LEVELS_TO_INSTALL) {
+    const levelDir = join(FRAMEWORK_SKILLS_DIR, level);
+    if (!existsSync(levelDir)) continue;
+    installSkillsFromDir(levelDir, claudeSkillsDir);
+  }
+}

package/.morph/project/context/README.md

@@ -1,17 +0,0 @@
-# morph-spec-framework - Project Context
-
-## Overview
-
-This file will be auto-updated by MORPH-SPEC detection system.
-
-## Stack
-
-Run `morph-spec detect` to analyze your project.
-
-## Technologies
-
-(To be detected)
-
-## Architecture
-
-(To be detected)

package/.morph/project/context/detection-log.md

@@ -1,16 +0,0 @@
-## Detection Summary
-
-### Stack
-- **Type**: nodejs
-- **Architecture**: cli-library
-
-### Technologies
-- **Language**: javascript
-- **Version**: >=18.0.0
-- **Package Manager**: npm
-
-### Patterns Detected
-- API Routes
-- Unit Tests
-
-### Recommendations

package/.morph/project/standards/inferred.md

@@ -1,59 +0,0 @@
-# Inferred Standards (Auto-generated)
-
-> ⚠️ This file is auto-generated by MORPH-SPEC detection system.
-> Manual edits will be overwritten. Create custom standards in `overrides.md`.
-
-**Generated:** 2026-02-19T22:12:05.727Z
-
----
-
-## 🎯 Project Stack
-
-- **Type**: nodejs
-- **Language**: javascript
-- **Version**: >=18.0.0
-- **Architecture**: cli-library
-
-## 📐 Patterns in Use
-
-- API Routes
-- Unit Tests
-
-## 💻 Inferred Coding Standards
-
-### JavaScript / TypeScript Conventions
-
-Based on detected patterns in your codebase:
-
-- **Package Manager**: npm
-
-**Recommendation**: Refer to framework standards for JavaScript best practices.
-
-## 🏗️ Architecture Pattern
-
-### CLI / Library Architecture
-
-Your project follows a CLI/Library pattern:
-
-- ✅ **bin/** entry points detected
-- ✅ **src/** source directory detected
-- ✅ **package.json** present
-
-**Key principles**:
-- Commands exposed via bin/
-- Core logic in src/commands/ and src/lib/
-- Public API exported from src/index.js
-
-## 📦 Key Dependencies
-
-- @polymorphism-tech/morph-spec
-- ajv
-- ajv-formats
-- chalk
-- commander
-- diff
-- fs-extra
-- glob
-- handlebars
-- inquirer
-- ... and 6 more