agileflow 4.0.0-alpha.2 → 4.0.0-alpha.21

package/src/runtime/ide/capabilities.js

@@ -3,9 +3,12 @@
  *
  * Different agentic IDEs and CLIs support different subsets of the
  * AgileFlow surface. Claude Code is the full-feature target — hooks,
- * skills, slash commands, subagents, MCP. Cursor / Windsurf / Codex
- * support only a subset (mostly slash commands and MCP, with no
- * formalized hook system).
+ * skills, subagents, MCP. Cursor / Windsurf support only a subset
+ * (mostly MCP, with no formalized hook system). Codex now supports
+ * hooks through its experimental config.toml / hooks.json surface, but
+ * with a smaller event set than Claude Code. Antigravity appears to
+ * support skills and agent workflows, but we have not verified a hook
+ * surface yet, so it stays skill/agent-only for now.
  *
  * The installer reads this map to gate plugin content: a plugin's
  * hooks won't be written into a `cursor` install because Cursor has
@@ -25,53 +28,88 @@
 
 /**
  * @typedef {Object} IdeCapabilities
- * @property {boolean} hooks - SessionStart / PreToolUse / etc. hooks
+ * @property {boolean} hooks - whether this IDE can run any AgileFlow hooks
+ * @property {string[]} hookEvents - supported lifecycle events
  * @property {boolean} skills - skill discovery + invocation
- * @property {boolean} commands - slash commands
- * @property {boolean} agents - subagents
- * @property {boolean} mcp - MCP server registration
+ * @property {boolean} agents - subagents (Task tool / multi-agent spawning)
+ * @property {boolean} interactivePrompts - AskUserQuestion renders as interactive UI
+ * @property {boolean} multiAgent - parallel agent spawning via Task tool
+ * @property {boolean} sessionRestore - PostCompact hook fires to re-inject context
  * @property {string} settingsFile - path the installer writes IDE config to
  *           (relative to project root)
+ * @property {string} skillsDir - path the installer mirrors SKILL.md files
+ *           into (relative to project root). Convention: <ide-dotdir>/skills.
  * @property {string} description - human-readable label for the picker
  */
 
 /** @type {Record<string, IdeCapabilities>} */
 const IDE_CAPABILITIES = {
-  'claude-code': {
+  "claude-code": {
     hooks: true,
+    hookEvents: ["SessionStart", "PreToolUse", "PostCompact", "Stop"],
     skills: true,
-    commands: true,
     agents: true,
-    mcp: true,
-    settingsFile: '.claude/settings.json',
-    description: 'Anthropic Claude Code (full feature set)',
+    interactivePrompts: true,
+    multiAgent: true,
+    sessionRestore: true,
+    settingsFile: ".claude/settings.json",
+    skillsDir: ".claude/skills",
+    description: "Claude Code",
   },
   cursor: {
     hooks: false,
-    skills: false,
-    commands: true,
+    hookEvents: [],
+    skills: true,
     agents: false,
-    mcp: true,
-    settingsFile: '.cursor/settings.json',
-    description: 'Cursor IDE (slash commands + MCP only)',
+    interactivePrompts: false,
+    multiAgent: false,
+    sessionRestore: false,
+    settingsFile: ".cursor/settings.json",
+    skillsDir: ".cursor/skills",
+    description: "Cursor",
   },
   windsurf: {
     hooks: false,
-    skills: false,
-    commands: true,
+    hookEvents: [],
+    skills: true,
     agents: false,
-    mcp: false,
-    settingsFile: '.windsurf/settings.json',
-    description: 'Windsurf (slash commands only)',
+    interactivePrompts: false,
+    multiAgent: false,
+    sessionRestore: false,
+    settingsFile: ".windsurf/settings.json",
+    skillsDir: ".windsurf/skills",
+    description: "Windsurf",
   },
   codex: {
+    hooks: true,
+    hookEvents: [
+      "SessionStart",
+      "PreToolUse",
+      "PermissionRequest",
+      "PostToolUse",
+      "UserPromptSubmit",
+      "Stop",
+    ],
+    skills: true,
+    agents: true,
+    interactivePrompts: false,
+    multiAgent: true,
+    sessionRestore: false,
+    settingsFile: ".codex/config.toml",
+    skillsDir: ".codex/skills",
+    description: "Codex",
+  },
+  antigravity: {
     hooks: false,
-    skills: false,
-    commands: false,
-    agents: false,
-    mcp: false,
-    settingsFile: '.codex/settings.json',
-    description: 'OpenAI Codex CLI (limited integration)',
+    hookEvents: [],
+    skills: true,
+    agents: true,
+    interactivePrompts: false,
+    multiAgent: true,
+    sessionRestore: false,
+    settingsFile: ".antigravity/settings.json",
+    skillsDir: ".antigravity/skills",
+    description: "Antigravity",
   },
 };
 
@@ -86,7 +124,7 @@ function capabilitiesFor(ide) {
   const caps = IDE_CAPABILITIES[ide];
   if (!caps) {
     throw new Error(
-      `Unknown IDE "${ide}". Supported: ${SUPPORTED_IDES.join(', ')}`,
+      `Unknown IDE "${ide}". Supported: ${SUPPORTED_IDES.join(", ")}`,
     );
   }
   return caps;
@@ -103,9 +141,26 @@ function supports(ide, feature) {
   return Boolean(caps[feature]);
 }
 
+/**
+ * @param {string[]} ides
+ * @returns {Set<string>}
+ */
+function hookEventsForIdes(ides) {
+  const events = new Set();
+  for (const ide of ides || []) {
+    const caps = IDE_CAPABILITIES[ide];
+    if (!caps || !Array.isArray(caps.hookEvents)) continue;
+    for (const event of caps.hookEvents) {
+      events.add(event);
+    }
+  }
+  return events;
+}
+
 module.exports = {
   IDE_CAPABILITIES,
   SUPPORTED_IDES,
   capabilitiesFor,
   supports,
+  hookEventsForIdes,
 };

package/src/runtime/ide/claude-code-content.js

@@ -0,0 +1,177 @@
+/**
+ * Mirrors plugin-provided slash commands and subagents into Claude Code.
+ *
+ * Plugin source files live under:
+ *   apps/cli/content/plugins/<id>/commands/...
+ *   apps/cli/content/plugins/<id>/agents/...
+ *
+ * Claude Code discovers them from project-local dotdirs:
+ *   .claude/commands/agileflow/...
+ *   .claude/agents/agileflow/...
+ */
+const fs = require("fs");
+const path = require("path");
+
+/**
+ * @typedef {import('../plugins/registry.js').PluginManifest} PluginManifest
+ *
+ * @typedef {Object} MirrorContentResult
+ * @property {string[]} mirrored
+ * @property {Array<{ id: string, error: string }>} skipped
+ */
+
+/**
+ * @param {string} p
+ * @returns {string}
+ */
+function toPosix(p) {
+  return p.split(path.sep).join("/");
+}
+
+/**
+ * @param {string} filePath
+ * @returns {Promise<void>}
+ */
+async function mkdirFor(filePath) {
+  await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+}
+
+/**
+ * @param {string} dir
+ * @returns {Promise<void>}
+ */
+async function rmDir(dir) {
+  await fs.promises.rm(dir, { recursive: true, force: true });
+}
+
+/**
+ * @param {PluginManifest[]} orderedPlugins
+ * @param {"commands" | "agents"} kind
+ * @returns {Array<{ id: string, sourcePath: string, relativePath: string }>}
+ */
+function collectPluginContent(orderedPlugins, kind) {
+  /** @type {Array<{ id: string, sourcePath: string, relativePath: string }>} */
+  const out = [];
+  for (const plugin of orderedPlugins) {
+    const entries =
+      plugin.provides && Array.isArray(plugin.provides[kind])
+        ? plugin.provides[kind]
+        : [];
+    for (const entry of entries) {
+      if (
+        !entry ||
+        typeof entry.id !== "string" ||
+        !entry.id ||
+        typeof entry.path !== "string" ||
+        !entry.path
+      ) {
+        continue;
+      }
+      const relativePath = entry.path.startsWith(`${kind}/`)
+        ? entry.path.slice(kind.length + 1)
+        : entry.path;
+      out.push({
+        id: entry.id,
+        sourcePath: path.join(plugin.dir, entry.path),
+        relativePath: toPosix(relativePath),
+      });
+    }
+  }
+  return out;
+}
+
+/**
+ * @param {PluginManifest[]} orderedPlugins
+ * @param {string} projectRoot
+ * @param {string} targetDirRel
+ * @param {"commands" | "agents"} kind
+ * @returns {Promise<MirrorContentResult>}
+ */
+async function mirrorClaudeCodeContent(
+  orderedPlugins,
+  projectRoot,
+  targetDirRel,
+  kind,
+) {
+  const targetRoot = path.join(projectRoot, targetDirRel);
+  await rmDir(targetRoot);
+  await fs.promises.mkdir(targetRoot, { recursive: true });
+
+  const items = collectPluginContent(orderedPlugins, kind);
+  /** @type {string[]} */
+  const mirrored = [];
+  /** @type {Array<{ id: string, error: string }>} */
+  const skipped = [];
+
+  for (const item of items) {
+    const dest = path.join(targetRoot, item.relativePath);
+    try {
+      await mkdirFor(dest);
+      await fs.promises.copyFile(item.sourcePath, dest);
+      mirrored.push(item.id);
+    } catch (err) {
+      if (err && err.code === "ENOENT") {
+        skipped.push({
+          id: item.id,
+          error: `source not found: ${item.sourcePath}`,
+        });
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  return { mirrored, skipped };
+}
+
+/**
+ * @param {PluginManifest[]} orderedPlugins
+ * @param {string} projectRoot
+ * @returns {Promise<MirrorContentResult>}
+ */
+function mirrorClaudeCodeCommands(orderedPlugins, projectRoot) {
+  return mirrorClaudeCodeContent(
+    orderedPlugins,
+    projectRoot,
+    ".claude/commands/agileflow",
+    "commands",
+  );
+}
+
+/**
+ * @param {PluginManifest[]} orderedPlugins
+ * @param {string} projectRoot
+ * @returns {Promise<MirrorContentResult>}
+ */
+function mirrorClaudeCodeAgents(orderedPlugins, projectRoot) {
+  return mirrorClaudeCodeContent(
+    orderedPlugins,
+    projectRoot,
+    ".claude/agents/agileflow",
+    "agents",
+  );
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<void>}
+ */
+async function unmirrorClaudeCodeCommands(projectRoot) {
+  await rmDir(path.join(projectRoot, ".claude/commands/agileflow"));
+}
+
+/**
+ * @param {string} projectRoot
+ * @returns {Promise<void>}
+ */
+async function unmirrorClaudeCodeAgents(projectRoot) {
+  await rmDir(path.join(projectRoot, ".claude/agents/agileflow"));
+}
+
+module.exports = {
+  collectPluginContent,
+  mirrorClaudeCodeCommands,
+  mirrorClaudeCodeAgents,
+  unmirrorClaudeCodeCommands,
+  unmirrorClaudeCodeAgents,
+};

package/src/runtime/ide/claude-code-settings.js

@@ -3,9 +3,10 @@
  *
  * When the target IDE is `claude-code`, the installer registers our 6
  * hook entry points in `.claude/settings.json` so Claude Code actually
- * invokes them at runtime. We use the unified `npx --no-install
- * agileflow hook <event> [--matcher <m>]` command so the path resolves
- * regardless of how the package is installed.
+ * invokes them at runtime. We use `npx agileflow hook <event>` so npx
+ * resolves the project-local binary from node_modules first. --no-install is
+ * intentionally omitted: it skips local node_modules and falls back to the
+ * npm cache, which can pick up a stale older version.
  *
  * The writer is **non-destructive**: it merges with any existing
  * settings.json. Only AgileFlow-owned hook entries (identified by the
@@ -16,10 +17,10 @@
  * On a non-claude-code switch, `removeManagedHooks` strips our entries
  * but leaves the rest of the file alone.
  */
-const fs = require('fs');
-const path = require('path');
+const fs = require("fs");
+const path = require("path");
 
-const HOOK_COMMAND_MARKER = 'agileflow hook';
+const HOOK_COMMAND_MARKER = "agileflow hook";
 const HOOK_TIMEOUT_SECONDS = 30;
 
 /**
@@ -27,28 +28,65 @@ const HOOK_TIMEOUT_SECONDS = 30;
  * The `command` is what gets baked into settings.json.
  */
 const MANAGED_HOOKS = [
-  { event: 'SessionStart', matcher: null, command: 'npx --no-install agileflow hook SessionStart' },
-  { event: 'PreToolUse', matcher: 'Bash', command: 'npx --no-install agileflow hook PreToolUse --matcher Bash' },
-  { event: 'PreToolUse', matcher: 'Edit', command: 'npx --no-install agileflow hook PreToolUse --matcher Edit' },
-  { event: 'PreToolUse', matcher: 'Write', command: 'npx --no-install agileflow hook PreToolUse --matcher Write' },
-  { event: 'PreCompact', matcher: null, command: 'npx --no-install agileflow hook PreCompact' },
-  { event: 'Stop', matcher: null, command: 'npx --no-install agileflow hook Stop' },
+  {
+    event: "SessionStart",
+    matcher: null,
+    command: "npx agileflow hook SessionStart",
+  },
+  {
+    event: "PreToolUse",
+    matcher: "Bash",
+    command: "npx agileflow hook PreToolUse --matcher Bash",
+  },
+  {
+    event: "PreToolUse",
+    matcher: "Edit",
+    command: "npx agileflow hook PreToolUse --matcher Edit",
+  },
+  {
+    event: "PreToolUse",
+    matcher: "Write",
+    command: "npx agileflow hook PreToolUse --matcher Write",
+  },
+  {
+    event: "PostCompact",
+    matcher: null,
+    command: "npx agileflow hook PostCompact",
+  },
+  {
+    event: "Stop",
+    matcher: null,
+    command: "npx agileflow hook Stop",
+  },
 ];
 
 const MANAGED_EVENTS = new Set(MANAGED_HOOKS.map((h) => h.event));
 
+/**
+ * Events AgileFlow wrote in previous versions but no longer manages.
+ * Used by `doctor` to detect stale entries that update wouldn't sweep
+ * (mergeManagedHooks only touches MANAGED_EVENTS). Add the OLD name
+ * here whenever a hook event is renamed or retired so old installs
+ * surface the leftover.
+ *
+ *   - PreCompact   → renamed to PostCompact in v4.0.0-alpha.6
+ *   - PostToolUse  → retired in v4 (was v3-era damage-control hook)
+ */
+const LEGACY_MANAGED_EVENTS = new Set(["PreCompact", "PostToolUse"]);
+
 /**
  * Detect whether a settings.json hook entry belongs to AgileFlow.
  * @param {*} entry
  */
 function isAgileflowEntry(entry) {
-  if (!entry || typeof entry !== 'object' || !Array.isArray(entry.hooks)) return false;
+  if (!entry || typeof entry !== "object" || !Array.isArray(entry.hooks))
+    return false;
   return entry.hooks.some(
     (h) =>
       h &&
-      typeof h === 'object' &&
-      h.type === 'command' &&
-      typeof h.command === 'string' &&
+      typeof h === "object" &&
+      h.type === "command" &&
+      typeof h.command === "string" &&
       h.command.includes(HOOK_COMMAND_MARKER),
   );
 }
@@ -60,9 +98,7 @@ function isAgileflowEntry(entry) {
 function buildEntry({ matcher, command }) {
   /** @type {{ matcher?: string, hooks: object[] }} */
   const out = {
-    hooks: [
-      { type: 'command', command, timeout: HOOK_TIMEOUT_SECONDS },
-    ],
+    hooks: [{ type: "command", command, timeout: HOOK_TIMEOUT_SECONDS }],
   };
   if (matcher) out.matcher = matcher;
   return out;
@@ -75,12 +111,13 @@ function buildEntry({ matcher, command }) {
  */
 async function readExisting(settingsPath) {
   try {
-    const raw = await fs.promises.readFile(settingsPath, 'utf8');
+    const raw = await fs.promises.readFile(settingsPath, "utf8");
     const parsed = JSON.parse(raw);
-    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return {};
     return parsed;
   } catch (err) {
-    if (err.code === 'ENOENT') return {};
+    if (err.code === "ENOENT") return {};
     if (err instanceof SyntaxError) return {};
     throw err;
   }
@@ -97,9 +134,9 @@ async function writeMerged(settingsPath, settings) {
     path.dirname(settingsPath),
     `.${path.basename(settingsPath)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
   );
-  const text = JSON.stringify(settings, null, 2) + '\n';
+  const text = JSON.stringify(settings, null, 2) + "\n";
   try {
-    await fs.promises.writeFile(tmp, text, 'utf8');
+    await fs.promises.writeFile(tmp, text, "utf8");
     await fs.promises.rename(tmp, settingsPath);
   } catch (err) {
     try {
@@ -125,7 +162,7 @@ function mergeManagedHooks(existing) {
   // produces numeric-keyed garbage. Treat it as missing instead.
   const baseHooks =
     existing.hooks &&
-    typeof existing.hooks === 'object' &&
+    typeof existing.hooks === "object" &&
     !Array.isArray(existing.hooks)
       ? existing.hooks
       : {};
@@ -154,7 +191,7 @@ function unmanageHooks(existing) {
   const next = { ...existing };
   if (
     !existing.hooks ||
-    typeof existing.hooks !== 'object' ||
+    typeof existing.hooks !== "object" ||
     Array.isArray(existing.hooks)
   ) {
     return next;
@@ -185,7 +222,7 @@ function unmanageHooks(existing) {
  * @returns {Promise<string>} absolute path of the written settings file
  */
 async function writeClaudeCodeSettings(projectRoot) {
-  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  const settingsPath = path.join(projectRoot, ".claude", "settings.json");
   const existing = await readExisting(settingsPath);
   const merged = mergeManagedHooks(existing);
   await writeMerged(settingsPath, merged);
@@ -201,7 +238,7 @@ async function writeClaudeCodeSettings(projectRoot) {
  * @returns {Promise<{ removed: boolean, settingsPath: string|null }>}
  */
 async function removeClaudeCodeSettings(projectRoot) {
-  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  const settingsPath = path.join(projectRoot, ".claude", "settings.json");
   // readExisting already converts ENOENT and SyntaxError to {} — any
   // exception here means a real filesystem problem (EACCES / EIO).
   // Do NOT swallow: a silent success would lie about successfully
@@ -213,7 +250,7 @@ async function removeClaudeCodeSettings(projectRoot) {
       await fs.promises.unlink(settingsPath);
       return { removed: true, settingsPath };
     } catch (err) {
-      if (err.code === 'ENOENT') return { removed: false, settingsPath: null };
+      if (err.code === "ENOENT") return { removed: false, settingsPath: null };
       throw err;
     }
   }
@@ -229,6 +266,7 @@ module.exports = {
   isAgileflowEntry,
   MANAGED_HOOKS,
   MANAGED_EVENTS,
+  LEGACY_MANAGED_EVENTS,
   HOOK_COMMAND_MARKER,
   HOOK_TIMEOUT_SECONDS,
 };