@polymorphism-tech/morph-spec 4.7.1 → 4.8.1

package/src/scripts/install-plugin.js

@@ -0,0 +1,126 @@
+// src/scripts/install-plugin.js
+import { join } from 'path';
+import { homedir } from 'os';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { mkdir, writeFile } from 'fs/promises';
+import https from 'node:https';
+
+const PLUGINS_DIR = join(homedir(), '.claude', 'plugins');
+const CACHE_DIR = join(PLUGINS_DIR, 'cache', 'claude-plugins-official');
+const INSTALLED_FILE = join(PLUGINS_DIR, 'installed_plugins.json');
+const GH_REPO = 'anthropics/claude-plugins-official';
+
+/** Fetch JSON from GitHub API (no auth — public repo) */
+async function fetchGitHub(path) {
+  return new Promise((resolve, reject) => {
+    const opts = {
+      hostname: 'api.github.com',
+      path,
+      headers: { 'User-Agent': 'morph-spec', 'Accept': 'application/vnd.github.v3+json' }
+    };
+    https.get(opts, (res) => {
+      let data = '';
+      res.on('data', c => data += c);
+      res.on('end', () => {
+        try { resolve(JSON.parse(data)); }
+        catch (e) { reject(new Error(`GitHub API parse error: ${data.slice(0, 200)}`)); }
+      });
+    }).on('error', reject);
+  });
+}
+
+/** Download raw file content from a URL, following one redirect */
+async function downloadFile(rawUrl) {
+  return new Promise((resolve, reject) => {
+    const doGet = (url) => {
+      const parsed = new URL(url);
+      https.get({
+        hostname: parsed.hostname,
+        path: parsed.pathname + parsed.search,
+        headers: { 'User-Agent': 'morph-spec' }
+      }, (res) => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          return doGet(res.headers.location);
+        }
+        const chunks = [];
+        res.on('data', c => chunks.push(c));
+        res.on('end', () => resolve(Buffer.concat(chunks)));
+      }).on('error', reject);
+    };
+    doGet(rawUrl);
+  });
+}
+
+/** Read installed_plugins.json safely */
+export function readInstalledPlugins() {
+  if (!existsSync(INSTALLED_FILE)) return { version: 2, plugins: {} };
+  try { return JSON.parse(readFileSync(INSTALLED_FILE, 'utf8')); }
+  catch { return { version: 2, plugins: {} }; }
+}
+
+/** Check if plugin key exists in the plugins map */
+export function isPluginInstalled(plugins, name) {
+  return `${name}@claude-plugins-official` in plugins;
+}
+
+/** Build an installed_plugins.json entry */
+export function buildInstallEntry(pluginName, installPath, gitCommitSha, version) {
+  const now = new Date().toISOString();
+  return { scope: 'user', installPath, version, installedAt: now, lastUpdated: now, gitCommitSha };
+}
+
+/** Resolve latest commit SHA for a plugin path in the repo */
+export async function resolvePluginVersion(pluginName) {
+  const commits = await fetchGitHub(`/repos/${GH_REPO}/commits?path=${pluginName}&per_page=1`);
+  if (!Array.isArray(commits) || commits.length === 0) {
+    throw new Error(`Could not resolve version for plugin: ${pluginName}`);
+  }
+  const sha = commits[0].sha;
+  return { sha, shortSha: sha.slice(0, 12) };
+}
+
+/** Download all files for a plugin from the repo tree */
+async function downloadPluginFiles(pluginName, sha, destDir) {
+  const tree = await fetchGitHub(`/repos/${GH_REPO}/git/trees/${sha}?recursive=1`);
+  if (!tree.tree) throw new Error('GitHub tree API returned unexpected shape');
+
+  const pluginFiles = tree.tree.filter(f => f.path.startsWith(`${pluginName}/`) && f.type === 'blob');
+  if (pluginFiles.length === 0) throw new Error(`Plugin "${pluginName}" not found in repository`);
+
+  for (const file of pluginFiles) {
+    const relativePath = file.path.slice(pluginName.length + 1);
+    const destPath = join(destDir, relativePath);
+    await mkdir(join(destPath, '..'), { recursive: true });
+    const content = await downloadFile(
+      `https://raw.githubusercontent.com/${GH_REPO}/${sha}/${file.path}`
+    );
+    await writeFile(destPath, content);
+  }
+}
+
+/**
+ * Install a Claude Code plugin from GitHub.
+ * @param {string} pluginName - e.g. "superpowers"
+ * @returns {{ installed: boolean, version: string, alreadyInstalled: boolean }}
+ */
+export async function installPlugin(pluginName) {
+  const data = readInstalledPlugins();
+  if (isPluginInstalled(data.plugins, pluginName)) {
+    const existing = data.plugins[`${pluginName}@claude-plugins-official`];
+    const version = Array.isArray(existing) ? existing[0]?.version : 'unknown';
+    return { installed: true, alreadyInstalled: true, version };
+  }
+
+  const { sha, shortSha } = await resolvePluginVersion(pluginName);
+  const installPath = join(CACHE_DIR, pluginName, shortSha);
+
+  await mkdir(installPath, { recursive: true });
+  await downloadPluginFiles(pluginName, sha, installPath);
+
+  const entry = buildInstallEntry(pluginName, installPath, sha, shortSha);
+  data.plugins[`${pluginName}@claude-plugins-official`] = [entry];
+  mkdirSync(PLUGINS_DIR, { recursive: true });
+  writeFileSync(INSTALLED_FILE, JSON.stringify(data, null, 2));
+
+  return { installed: true, alreadyInstalled: false, version: shortSha };
+}

package/src/scripts/setup-infra.js

@@ -0,0 +1,203 @@
+/**
+ * setup-infra.js
+ *
+ * Headless infrastructure setup for MORPH-SPEC.
+ * Extracted from init.js (steps 1-10) so it can be called by the
+ * /morph-init Claude Code skill via `morph-spec setup-infra` without
+ * interactive prompts or stack detection.
+ *
+ * Usage:
+ *   import { setupInfra } from './setup-infra.js';
+ *   await setupInfra('/path/to/project');
+ */
+
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import {
+  copyDirectory,
+  copyFile,
+  pathExists,
+  writeJson,
+  ensureDir,
+  writeFile,
+  updateGitignore
+} from '../utils/file-copier.js';
+import { saveProjectMorphVersion, getInstalledCLIVersion } from '../utils/version-checker.js';
+import { installClaudeHooks, installGlobalStatusline } from '../utils/claude-settings-manager.js';
+import { installSkills } from '../utils/skills-installer.js';
+import { installAgents, installDomainAgents } from '../utils/agents-installer.js';
+
+const FRAMEWORK_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'framework');
+
+/**
+ * Installs MORPH-SPEC infrastructure into the target project directory.
+ * Headless — no prompts, no spinner (suppressed when MORPH_QUIET=1), no stack detection.
+ *
+ * @param {string} targetPath - Absolute path to the target project directory
+ */
+export async function setupInfra(targetPath) {
+  const quiet = process.env.MORPH_QUIET === '1';
+
+  function log(msg) {
+    if (!quiet) process.stdout.write(msg + '\n');
+  }
+
+  // --- 1. Copy CLAUDE.md (backup existing non-MORPH CLAUDE.md) ---
+  log('Step 1: Copying CLAUDE.md...');
+  const claudeMdSrc = join(FRAMEWORK_DIR, 'CLAUDE.md');
+  const claudeMdDest = join(targetPath, 'CLAUDE.md');
+
+  if (await pathExists(claudeMdDest)) {
+    const { readFile } = await import('../utils/file-copier.js');
+    const existingContent = await readFile(claudeMdDest);
+    if (!existingContent.includes('MORPH-SPEC')) {
+      await copyFile(claudeMdDest, `${claudeMdDest}.backup`);
+    }
+  }
+  await copyFile(claudeMdSrc, claudeMdDest);
+
+  // --- 2. Create .morph directory structure ---
+  log('Step 2: Creating .morph structure...');
+  const morphPath = join(targetPath, '.morph');
+  const configDir = join(morphPath, 'config');
+  const frameworkDestDir = join(morphPath, 'framework');
+  const contextDir = join(morphPath, 'context');
+  const featuresDir = join(morphPath, 'features');
+  const checkpointsDir = join(morphPath, 'checkpoints');
+  const memoryDir = join(morphPath, 'memory');
+  const archiveDir = join(morphPath, 'archive');
+
+  await ensureDir(configDir);
+  await ensureDir(frameworkDestDir);
+  await ensureDir(contextDir);
+  await ensureDir(featuresDir);
+  await ensureDir(checkpointsDir);
+  await ensureDir(memoryDir);
+  await ensureDir(archiveDir);
+
+  // --- 3. Write minimal config.json (only if not exists) ---
+  log('Step 3: Writing config.json...');
+  const configPath = join(configDir, 'config.json');
+  if (!(await pathExists(configPath))) {
+    const dirName = targetPath.split(/[\/]/).pop();
+    const config = {
+      framework: 'global',
+      frameworkVersion: getInstalledCLIVersion(),
+      project: {
+        name: dirName
+      }
+    };
+    await writeJson(configPath, config);
+  }
+
+  // --- 4. Write placeholder context/README.md (only if not exists) ---
+  log('Step 4: Writing context/README.md...');
+  const contextReadmePath = join(contextDir, 'README.md');
+  if (!(await pathExists(contextReadmePath))) {
+    const dirName = targetPath.split(/[\/]/).pop();
+    const readmeContent = `# ${dirName} — Project Context\n\nRun /morph-init to generate project context.\n`;
+    await writeFile(contextReadmePath, readmeContent);
+  }
+
+  // --- 5. Copy framework/templates → .morph/framework/templates ---
+  log('Step 5: Copying framework templates...');
+  const frameworkTemplatesSrc = join(FRAMEWORK_DIR, 'templates');
+  const templatesDest = join(frameworkDestDir, 'templates');
+  if (await pathExists(frameworkTemplatesSrc)) {
+    await copyDirectory(frameworkTemplatesSrc, templatesDest);
+  } else {
+    await ensureDir(templatesDest);
+  }
+
+  // --- 6. Copy framework/standards → .morph/framework/standards ---
+  log('Step 6: Copying framework standards...');
+  const frameworkStandardsSrc = join(FRAMEWORK_DIR, 'standards');
+  const frameworkStandardsDest = join(frameworkDestDir, 'standards');
+  if (await pathExists(frameworkStandardsSrc)) {
+    await copyDirectory(frameworkStandardsSrc, frameworkStandardsDest);
+  }
+
+  // --- 7. Copy framework/hooks → .morph/framework/hooks ---
+  log('Step 7: Copying hooks...');
+  const hooksSrc = join(FRAMEWORK_DIR, 'hooks');
+  const hooksDest = join(frameworkDestDir, 'hooks');
+  if (await pathExists(hooksSrc)) {
+    await copyDirectory(hooksSrc, hooksDest);
+  }
+
+  // --- 8. Copy framework/agents.json → .morph/framework/agents.json ---
+  log('Step 8: Copying agents.json...');
+  const agentsSrc = join(FRAMEWORK_DIR, 'agents.json');
+  const agentsDest = join(frameworkDestDir, 'agents.json');
+  if (await pathExists(agentsSrc)) {
+    await copyFile(agentsSrc, agentsDest);
+  }
+
+  // --- 9. Copy framework/commands → .claude/commands ---
+  log('Step 9: Setting up Claude Code integration...');
+  const claudeDest = join(targetPath, '.claude');
+  const commandsSrc = join(FRAMEWORK_DIR, 'commands');
+  const commandsDest = join(claudeDest, 'commands');
+  if (await pathExists(commandsSrc)) {
+    await copyDirectory(commandsSrc, commandsDest);
+  }
+
+  // --- 10. Copy framework/rules → .claude/rules ---
+  log('Step 10: Installing path-scoped rules...');
+  const rulesSrc = join(FRAMEWORK_DIR, 'rules');
+  const rulesDest = join(claudeDest, 'rules');
+  if (await pathExists(rulesSrc)) {
+    await copyDirectory(rulesSrc, rulesDest);
+  }
+
+  // --- 11. installSkills ---
+  log('Step 11: Installing skills...');
+  await installSkills(targetPath);
+
+  // --- 12. installAgents ---
+  log('Step 12: Installing agents...');
+  const agentCounts = await installAgents(targetPath, FRAMEWORK_DIR, { projectStack: null });
+
+  // --- 13. installDomainAgents ---
+  log('Step 13: Installing domain agents...');
+  const domainCounts = await installDomainAgents(targetPath, FRAMEWORK_DIR);
+
+  // --- 14. Copy framework/CLAUDE.md → .claude/CLAUDE.md ---
+  log('Step 14: Installing .claude/CLAUDE.md...');
+  const runtimeClaudeMdDest = join(claudeDest, 'CLAUDE.md');
+  if (await pathExists(claudeMdSrc)) {
+    await copyFile(claudeMdSrc, runtimeClaudeMdDest);
+  }
+
+  // --- 15. installGlobalStatusline (non-critical) ---
+  log('Step 15: Installing global statusline...');
+  const HOOKS_SRC = join(FRAMEWORK_DIR, 'hooks', 'claude-code');
+  try {
+    await installGlobalStatusline(HOOKS_SRC);
+  } catch {
+    // Non-critical — global ~/.claude may not be writable
+  }
+
+  // --- 16. installClaudeHooks ---
+  log('Step 16: Installing Claude Code hooks...');
+  await installClaudeHooks(targetPath);
+
+  // --- 17. saveProjectMorphVersion ---
+  log('Step 17: Saving version info...');
+  const cliVersion = getInstalledCLIVersion();
+  await saveProjectMorphVersion(targetPath, cliVersion);
+
+  // --- 18. updateGitignore ---
+  log('Step 18: Updating .gitignore...');
+  await updateGitignore(targetPath);
+
+  log('setup-infra: complete.');
+
+  return {
+    agents: {
+      tier1: agentCounts?.tier1 ?? 0,
+      tier2: agentCounts?.tier2 ?? 0,
+      specialists: domainCounts?.specialists ?? 0,
+    },
+  };
+}

package/src/utils/agents-installer.js

@@ -47,6 +47,8 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     return true;
   });
 
+  let tier1 = 0;
+  let tier2 = 0;
   for (const agent of eligible) {
     const slug = agent.id ?? agent.name?.toLowerCase().replace(/\s+/g, '-');
     const filename = `morph-${slug}.md`;
@@ -58,7 +60,11 @@ export async function installAgents(projectDir, frameworkDir = 'framework', opti
     const frontmatter = buildFrontmatter(agent, description);
     const content = `---\n${frontmatter}---\n\n${body}\n`;
     writeFileSync(targetPath, content, 'utf-8');
+
+    if (agent.tier === 1) tier1++;
+    else if (agent.tier === 2) tier2++;
   }
+  return { tier1, tier2 };
 }
 
 /**
@@ -191,11 +197,12 @@ export function collectSkillFiles(dir) {
  */
 export async function installDomainAgents(projectDir, frameworkDir = 'framework') {
   const domainsDir = join(frameworkDir, 'agents');
-  if (!existsSync(domainsDir)) return;
+  if (!existsSync(domainsDir)) return { specialists: 0 };
 
   const targetDir = join(projectDir, '.claude', 'agents');
   mkdirSync(targetDir, { recursive: true });
 
+  let specialists = 0;
   for (const filePath of collectSkillFiles(domainsDir)) {
     const raw = readFileSync(filePath, 'utf-8');
     const { name, description, allowedTools, body } = parseSkillFile(raw);
@@ -214,5 +221,7 @@ export async function installDomainAgents(projectDir, frameworkDir = 'framework'
 
     const targetPath = join(targetDir, `morph-domain-${name}.md`);
     writeFileSync(targetPath, `---\n${frontmatter}---\n\n${body.trimStart()}`, 'utf-8');
+    specialists++;
   }
+  return { specialists };
 }

package/src/utils/hooks-installer.js

@@ -10,11 +10,12 @@
 
 import { join } from 'path';
 import { readFile, writeFile, mkdir, copyFile } from 'fs/promises';
-import { existsSync, chmodSync } from 'fs';
+import { existsSync, chmodSync, readdirSync } from 'fs';
 import { homedir } from 'os';
+import { execSync } from 'child_process';
 
 /** Current hooks schema version — bump when hook definitions change */
-const HOOKS_VERSION = '2.4.0';
+const HOOKS_VERSION = '2.5.1';
 
 /** Marker for old dispatch.js (v1) */
 const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
@@ -25,10 +26,26 @@ const OLD_DISPATCH_COMMAND = 'node framework/hooks/agent-teams/dispatch.js';
  * using Claude Code's built-in permissions system instead.
  */
 const MORPH_PERMISSIONS = [
+  // Core framework state and readonly files
   'Write(.morph/state.json)',
   'Edit(.morph/state.json)',
   'Write(.morph/framework/**)',
   'Edit(.morph/framework/**)',
+  // Root CLAUDE.md (managed copy — source is framework/CLAUDE.md)
+  'Write(CLAUDE.md)',
+  'Edit(CLAUDE.md)',
+  // .claude/CLAUDE.md (managed copy — source is framework/CLAUDE_runtime.md)
+  'Write(.claude/CLAUDE.md)',
+  'Edit(.claude/CLAUDE.md)',
+  // .claude/rules/ (copied from framework/rules/)
+  'Write(.claude/rules/**)',
+  'Edit(.claude/rules/**)',
+  // .claude/agents/morph-* (generated by agents-installer)
+  'Write(.claude/agents/morph-*)',
+  'Edit(.claude/agents/morph-*)',
+  // .claude/skills/ (copied from framework/skills/)
+  'Write(.claude/skills/**)',
+  'Edit(.claude/skills/**)',
 ];
 
 /**
@@ -104,19 +121,8 @@ Otherwise respond: {"ok": true}`
     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
+      type: 'command',
+      command: 'node framework/hooks/claude-code/stop/validate-completion.js'
     }]
   },
 
@@ -209,9 +215,10 @@ export async function installClaudeHooks(targetPath) {
         return agentHook;
       }
       // Command hooks: transform path to use $CLAUDE_PROJECT_DIR
+      // Hooks are copied to .morph/framework/hooks/ during `morph-spec init/update`
       return {
         type: h.type,
-        command: `node "$CLAUDE_PROJECT_DIR/framework/hooks/claude-code/${getHookSubpath(h.command)}"`,
+        command: `node "$CLAUDE_PROJECT_DIR/.morph/framework/hooks/claude-code/${getHookSubpath(h.command)}"`,
         ...(h.timeout !== undefined ? { timeout: h.timeout } : {})
       };
     });
@@ -265,6 +272,47 @@ export async function installClaudeHooks(targetPath) {
   return { installed, updated: !alreadyCurrent };
 }
 
+/**
+/**
+ * Resolve Python executable suitable for the statusLine command.
+ *
+ * On non-Windows: returns 'python3' (standard PATH name).
+ * On Windows: Claude Code runs commands via the system shell where python3/python
+ * may not be on PATH. We probe with execSync first, then fall back to known
+ * Windows install locations (AppData\Local\Programs\Python\Python3*).
+ *
+ * @returns {string} Python executable (full path on Windows if needed)
+ */
+function resolvePythonForStatusline() {
+  if (process.platform !== 'win32') {
+    return 'python3';
+  }
+  // Try PATH-visible commands first (works if user added Python to PATH)
+  // 'py' is the Windows Python Launcher — standard on any Windows Python install
+  for (const cmd of ['python3', 'py', 'python']) {
+    try {
+      const ver = execSync(`${cmd} --version`, { encoding: 'utf-8', timeout: 3000, stdio: ['pipe', 'pipe', 'pipe'] });
+      if ((ver + '').includes('Python 3')) return cmd;
+    } catch { /* not on PATH */ }
+  }
+  // Probe known Windows install locations
+  const base = join(homedir(), 'AppData', 'Local', 'Programs', 'Python');
+  if (existsSync(base)) {
+    let dirs;
+    try { dirs = readdirSync(base); } catch { dirs = []; }
+    const py3 = dirs
+      .filter(d => /^Python3\d*/i.test(d))
+      .sort()
+      .reverse(); // prefer highest version
+    for (const dir of py3) {
+      const exe = join(base, dir, 'python.exe');
+      if (existsSync(exe)) return exe;
+    }
+  }
+  // Last resort: return python3 and let it fail with a clear error
+  return 'python3';
+}
+
 /**
  * Install the morph-spec statusline globally into ~/.claude/.
  *
@@ -305,9 +353,14 @@ export async function installGlobalStatusline(hooksSourceDir, globalClaudeDirOve
     }
   }
 
+  // On Windows, Claude Code cannot execute .sh files directly — call Python instead.
+  const statuslineCommand = process.platform === 'win32'
+    ? `"${resolvePythonForStatusline()}" "${join(globalDir, 'statusline.py').replace(/\\/g, '/')}"`
+    : join(globalDir, 'statusline.sh').replace(/\\/g, '/');
+
   settings.statusLine = {
     type: 'command',
-    command: join(globalDir, 'statusline.sh').replace(/\\/g, '/'),
+    command: statuslineCommand,
     padding: 2
   };
 

package/CLAUDE.md

@@ -1,77 +0,0 @@
-# MORPH-SPEC Runtime Instructions
-
-> by Polymorphism Tech — Spec-driven development for .NET/Blazor/Next.js/Azure
-
----
-
-## Project Context
-
-@.morph/context/README.md
-
----
-
-## Critical Rules
-
-**NEVER:**
-- Skip to code without a specification
-- Implement without design approval
-- Ignore standards in `.morph/framework/standards/`
-- Create infrastructure manually
-- Generate code without defined contracts
-
-**ALWAYS:**
-- Follow the mandatory phases
-- Generate outputs in `.morph/features/{feature}/`
-- Document decisions in `decisions.md`
-- Checkpoint every 3 implemented tasks
-- Use Infrastructure as Code
-
----
-
-## Quick Reference
-
-| Command | Purpose |
-|---------|---------|
-| `/morph-proposal {feature}` | Full spec pipeline (phases 1–4, pauses for approval) |
-| `/morph-apply {feature}` | Implement feature (phase 5) |
-| `/morph-status` | Feature status dashboard |
-| `/morph-preflight` | Pre-implementation validation |
-
----
-
-## State & Outputs
-
-| Path | Notes |
-|------|-------|
-| `.morph/state.json` | **READ-ONLY** — use `morph-spec` CLI to update |
-| `.morph/features/{feature}/{phase}/` | Feature outputs organized by phase |
-| `.morph/framework/` | **READ-ONLY** — framework files managed by morph-spec |
-| `.morph/config/config.json` | Project configuration (editable) |
-
----
-
-## Phase Sequence
-
-```
-proposal → setup → [uiux] → design → clarify → tasks → implement → [sync]
-```
-
-Use `morph-spec state show {feature}` to see current phase and pending approval gates.
-
----
-
-## Agents
-
-Tier-1 and tier-2 MORPH agents are available as native subagents in `.claude/agents/`.
-They can be invoked directly by Claude Code during multi-agent workflows.
-
----
-
-## Context Window Tip
-
-When using 3+ MCPs, add `"experimental": { "mcpCliMode": true }` to `.claude/settings.json`.
-MCP tools load on-demand instead of all at startup — keeps context clean for actual work.
-
----
-
-*MORPH-SPEC v4.5.0 by Polymorphism Tech*