agileflow 3.4.3 → 4.0.0-alpha.1

package/src/runtime/hooks/orchestrator.js

@@ -0,0 +1,322 @@
+/**
+ * Hook orchestrator.
+ *
+ * Each Claude Code hook event has one thin dispatcher binary in
+ * `apps/cli/bin/hooks/`. Every dispatcher delegates to `runEvent()`
+ * here, which:
+ *
+ *   1. Loads `.agileflow/hook-manifest.yaml`.
+ *   2. Filters to hooks for the requested event whose `enabled !== false`.
+ *   3. Applies user overrides from `agileflow.config.json.hooks` (per-hook
+ *      enabled / timeout / skipOnError).
+ *   4. Topologically orders the chain via runAfter, detecting cycles.
+ *   5. Spawns each hook's `script` as a child process, forwarding the
+ *      original stdin so Claude Code's payload reaches the hook.
+ *   6. Enforces per-hook timeout via AbortController.
+ *   7. Logs each step to `.agileflow/logs/hook-execution.jsonl`.
+ *   8. Honors `skipOnError`: a non-zero exit becomes a logged WARN that
+ *      does not interrupt the chain.
+ *   9. Exits 0 unless a hook with `skipOnError: false` failed.
+ *
+ * The actual child-process spawn is in `runHook` — it's exported and
+ * injectable so unit tests can substitute a stub without touching the
+ * filesystem.
+ */
+const path = require('path');
+const fs = require('fs');
+const { spawn } = require('child_process');
+
+const { loadHookManifest } = require('./manifest-loader.js');
+const { orderChain } = require('./chain.js');
+const { appendHookLog } = require('./logger.js');
+
+/**
+ * @typedef {import('./manifest-loader.js').HookEntry} HookEntry
+ *
+ * @typedef {Object} RunHookResult
+ * @property {number|null} exitCode - null when timed out / signal-killed
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {number} durationMs
+ * @property {boolean} timedOut
+ *
+ * @typedef {Object} HookOverride
+ * @property {boolean} [enabled]
+ * @property {number} [timeout]
+ * @property {boolean} [skipOnError]
+ *
+ * @typedef {Object} RunEventOptions
+ * @property {string} event - e.g. "SessionStart" or "PreToolUse"
+ * @property {string} agileflowDir - absolute path to .agileflow/
+ * @property {string} [matcher] - the actual tool name (e.g. "Bash") for
+ *           tool-related events. Used to filter manifest hooks whose
+ *           own `matcher` pattern selects this tool.
+ * @property {Buffer|string} [stdin] - data forwarded to each hook on stdin
+ * @property {Record<string, HookOverride>} [overrides] - from agileflow.config.json.hooks
+ * @property {(hook: HookEntry, ctx: { stdin: Buffer|string, agileflowDir: string }) => Promise<RunHookResult>} [runHook]
+ *           Injected for tests; defaults to `defaultRunHook`.
+ *
+ * @typedef {Object} ChainOutcome
+ * @property {number} exitCode - 0 unless a non-skipOnError hook failed
+ * @property {Array<{ hook: HookEntry, status: string, exitCode: number|null, durationMs: number }>} steps
+ */
+
+/**
+ * Default child-process runner for hook scripts.
+ *
+ * Picks an interpreter based on extension:
+ *   .js  → `node <script>`
+ *   .sh  → `bash <script>`
+ *   else → execute directly (must have a shebang and be executable)
+ *
+ * Times out via AbortController after `hook.timeout` ms.
+ *
+ * @type {(hook: HookEntry, ctx: { stdin: Buffer|string, agileflowDir: string }) => Promise<RunHookResult>}
+ */
+async function defaultRunHook(hook, ctx) {
+  const ext = path.extname(hook.script).toLowerCase();
+  /** @type {string} */
+  let cmd;
+  /** @type {string[]} */
+  let args;
+  if (ext === '.js') {
+    cmd = process.execPath;
+    args = [hook.script];
+  } else if (ext === '.sh') {
+    cmd = 'bash';
+    args = [hook.script];
+  } else {
+    cmd = hook.script;
+    args = [];
+  }
+
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), hook.timeout);
+
+  const start = Date.now();
+  return await new Promise((resolve) => {
+    const child = spawn(cmd, args, {
+      cwd: path.dirname(ctx.agileflowDir),
+      stdio: ['pipe', 'pipe', 'pipe'],
+      signal: ac.signal,
+      env: { ...process.env, AGILEFLOW_DIR: ctx.agileflowDir },
+    });
+    /** @type {string[]} */
+    const out = [];
+    /** @type {string[]} */
+    const err = [];
+    child.stdout.on('data', (d) => out.push(d.toString('utf8')));
+    child.stderr.on('data', (d) => err.push(d.toString('utf8')));
+    child.on('error', () => {
+      // Spawn-level errors (ENOENT for missing script, abort signal) — we
+      // surface as exitCode null + timedOut iff we triggered the abort.
+    });
+    child.on('close', (code, signal) => {
+      clearTimeout(timer);
+      resolve({
+        exitCode: code,
+        stdout: out.join(''),
+        stderr: err.join(''),
+        durationMs: Date.now() - start,
+        timedOut: signal === 'SIGTERM' && ac.signal.aborted,
+      });
+    });
+    if (ctx.stdin != null) {
+      try {
+        child.stdin.end(ctx.stdin);
+      } catch {
+        /* swallow if stdin already closed */
+      }
+    } else {
+      child.stdin.end();
+    }
+  });
+}
+
+/**
+ * Match a manifest matcher pattern against a tool name (or any actual
+ * value). Mirrors Claude Code's matcher semantics:
+ *
+ *   - empty/null/undefined/`'*'` → match all
+ *   - alphanumeric + `_` + `|` only → exact match against any pipe-
+ *     separated alternative (`'Bash'` or `'Edit|Write'`)
+ *   - anything else → JavaScript regex (`'^Notebook'`, `'mcp__memory__.*'`)
+ *
+ * @param {string|null|undefined} pattern
+ * @param {string|null|undefined} actual
+ * @returns {boolean}
+ */
+function matcherMatches(pattern, actual) {
+  if (!pattern || pattern === '*') return true;
+  if (typeof actual !== 'string' || actual.length === 0) return false;
+  if (/^[A-Za-z0-9_|]+$/.test(pattern)) {
+    return pattern.split('|').includes(actual);
+  }
+  try {
+    return new RegExp(pattern).test(actual);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Apply per-hook overrides from user config to a hook entry. Returns a
+ * new normalized HookEntry without mutating the input.
+ * @param {HookEntry} hook
+ * @param {HookOverride} [override]
+ * @returns {HookEntry}
+ */
+function applyOverride(hook, override) {
+  if (!override) return hook;
+  return {
+    ...hook,
+    enabled: override.enabled ?? hook.enabled,
+    timeout: override.timeout ?? hook.timeout,
+    skipOnError: override.skipOnError ?? hook.skipOnError,
+  };
+}
+
+/**
+ * Resolve the script path against the agileflow-dir parent (the project
+ * root). Manifest paths are relative to the project root by convention.
+ * @param {HookEntry} hook
+ * @param {string} agileflowDir
+ * @returns {HookEntry}
+ */
+function resolveScriptPath(hook, agileflowDir) {
+  const projectRoot = path.dirname(agileflowDir);
+  const absolute = path.isAbsolute(hook.script)
+    ? hook.script
+    : path.join(projectRoot, hook.script);
+  return { ...hook, script: absolute };
+}
+
+/**
+ * Run the chain for a given event. Always exits the orchestrator with
+ * code 0 unless a non-skipOnError hook fails or the chain itself fails
+ * to load (in which case the dispatcher decides whether to fail open).
+ *
+ * @param {RunEventOptions} options
+ * @returns {Promise<ChainOutcome>}
+ */
+async function runEvent(options) {
+  const {
+    event,
+    agileflowDir,
+    matcher,
+    stdin = '',
+    overrides = {},
+    runHook = defaultRunHook,
+  } = options;
+
+  const manifestPath = path.join(agileflowDir, 'hook-manifest.yaml');
+  const logPath = path.join(agileflowDir, 'logs', 'hook-execution.jsonl');
+
+  let manifest;
+  try {
+    manifest = await loadHookManifest(manifestPath);
+  } catch (err) {
+    // Bad manifest is treated as "no hooks" but logged for visibility.
+    await appendHookLog(logPath, {
+      timestamp: new Date().toISOString(),
+      event,
+      hookId: '<orchestrator>',
+      status: 'error',
+      exitCode: null,
+      durationMs: 0,
+      reason: `manifest load failed: ${err.message}`,
+    }).catch(() => {});
+    return { exitCode: 0, steps: [] };
+  }
+  if (!manifest) return { exitCode: 0, steps: [] };
+
+  // Filter to this event, then by matcher (a manifest hook with no
+  // matcher matches all; a manifest hook with a matcher only matches
+  // when the runtime supplied a matcher that satisfies it). Then
+  // apply user overrides and the enabled gate.
+  const eventHooks = manifest.hooks
+    .filter((h) => h.event === event)
+    .filter((h) => !h.matcher || matcherMatches(h.matcher, matcher))
+    .map((h) => applyOverride(h, overrides[h.id]))
+    .filter((h) => h.enabled);
+
+  if (!eventHooks.length) return { exitCode: 0, steps: [] };
+
+  // Topo sort within the event (orderChain only sees this event's hooks
+  // so cross-event runAfter is rejected as "unknown hook").
+  let ordered;
+  try {
+    ordered = orderChain(eventHooks);
+  } catch (err) {
+    await appendHookLog(logPath, {
+      timestamp: new Date().toISOString(),
+      event,
+      hookId: '<orchestrator>',
+      status: 'error',
+      exitCode: null,
+      durationMs: 0,
+      reason: `chain ordering failed: ${err.message}`,
+    }).catch(() => {});
+    return { exitCode: 1, steps: [] };
+  }
+
+  /** @type {ChainOutcome['steps']} */
+  const steps = [];
+  let chainExitCode = 0;
+
+  for (const hook of ordered) {
+    const resolved = resolveScriptPath(hook, agileflowDir);
+    let result;
+    let runError = null;
+    try {
+      result = await runHook(resolved, { stdin, agileflowDir });
+    } catch (err) {
+      runError = err;
+      result = {
+        exitCode: null,
+        stdout: '',
+        stderr: err && err.message ? err.message : String(err),
+        durationMs: 0,
+        timedOut: false,
+      };
+    }
+    const ok = result.exitCode === 0 && !runError;
+    /** @type {'ok'|'error'|'timeout'|'skipped'} */
+    const status = ok ? 'ok' : result.timedOut ? 'timeout' : 'error';
+    const skippedByOnError = !ok && hook.skipOnError === true;
+
+    await appendHookLog(logPath, {
+      timestamp: new Date().toISOString(),
+      event,
+      hookId: hook.id,
+      status,
+      exitCode: result.exitCode,
+      durationMs: result.durationMs,
+      stdout: result.stdout,
+      stderr: result.stderr,
+      skippedByOnError: skippedByOnError || undefined,
+    }).catch(() => {});
+
+    steps.push({
+      hook: resolved,
+      status,
+      exitCode: result.exitCode,
+      durationMs: result.durationMs,
+    });
+
+    if (!ok && !hook.skipOnError) {
+      chainExitCode = 1;
+      break;
+    }
+  }
+
+  return { exitCode: chainExitCode, steps };
+}
+
+module.exports = {
+  runEvent,
+  defaultRunHook,
+  applyOverride,
+  resolveScriptPath,
+  matcherMatches,
+};

package/src/runtime/ide/capabilities.js

@@ -0,0 +1,111 @@
+/**
+ * IDE / CLI capability declarations.
+ *
+ * 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).
+ *
+ * The installer reads this map to gate plugin content: a plugin's
+ * hooks won't be written into a `cursor` install because Cursor has
+ * nothing to invoke them; a plugin's skills won't be installed into
+ * Windsurf because Windsurf has no skill discovery mechanism. Plugins
+ * stay portable — the gate is at install time, not at authoring time.
+ *
+ * When an IDE adds a feature, bump its capability map here and the
+ * existing plugin content starts flowing into it on the next install.
+ *
+ * Note: the capability values reflect AgileFlow v4's *current*
+ * willingness to ship to that IDE. They are conservative for
+ * non-Claude-Code targets — it's safer to start with "off" and turn
+ * features on as we validate them than to ship features that silently
+ * misbehave.
+ */
+
+/**
+ * @typedef {Object} IdeCapabilities
+ * @property {boolean} hooks - SessionStart / PreToolUse / etc. hooks
+ * @property {boolean} skills - skill discovery + invocation
+ * @property {boolean} commands - slash commands
+ * @property {boolean} agents - subagents
+ * @property {boolean} mcp - MCP server registration
+ * @property {string} settingsFile - path the installer writes IDE config to
+ *           (relative to project root)
+ * @property {string} description - human-readable label for the picker
+ */
+
+/** @type {Record<string, IdeCapabilities>} */
+const IDE_CAPABILITIES = {
+  'claude-code': {
+    hooks: true,
+    skills: true,
+    commands: true,
+    agents: true,
+    mcp: true,
+    settingsFile: '.claude/settings.json',
+    description: 'Anthropic Claude Code (full feature set)',
+  },
+  cursor: {
+    hooks: false,
+    skills: false,
+    commands: true,
+    agents: false,
+    mcp: true,
+    settingsFile: '.cursor/settings.json',
+    description: 'Cursor IDE (slash commands + MCP only)',
+  },
+  windsurf: {
+    hooks: false,
+    skills: false,
+    commands: true,
+    agents: false,
+    mcp: false,
+    settingsFile: '.windsurf/settings.json',
+    description: 'Windsurf (slash commands only)',
+  },
+  codex: {
+    hooks: false,
+    skills: false,
+    commands: false,
+    agents: false,
+    mcp: false,
+    settingsFile: '.codex/settings.json',
+    description: 'OpenAI Codex CLI (limited integration)',
+  },
+};
+
+const SUPPORTED_IDES = Object.keys(IDE_CAPABILITIES);
+
+/**
+ * @param {string} ide
+ * @returns {IdeCapabilities}
+ * @throws {Error} when the ide is not recognized
+ */
+function capabilitiesFor(ide) {
+  const caps = IDE_CAPABILITIES[ide];
+  if (!caps) {
+    throw new Error(
+      `Unknown IDE "${ide}". Supported: ${SUPPORTED_IDES.join(', ')}`,
+    );
+  }
+  return caps;
+}
+
+/**
+ * @param {string} ide
+ * @param {keyof IdeCapabilities} feature
+ * @returns {boolean}
+ */
+function supports(ide, feature) {
+  const caps = IDE_CAPABILITIES[ide];
+  if (!caps) return false;
+  return Boolean(caps[feature]);
+}
+
+module.exports = {
+  IDE_CAPABILITIES,
+  SUPPORTED_IDES,
+  capabilitiesFor,
+  supports,
+};

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

@@ -0,0 +1,234 @@
+/**
+ * Claude Code settings.json writer.
+ *
+ * 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.
+ *
+ * The writer is **non-destructive**: it merges with any existing
+ * settings.json. Only AgileFlow-owned hook entries (identified by the
+ * `agileflow hook` substring in their command) are replaced; the
+ * user's other hook registrations and non-hook fields (permissions,
+ * env, etc.) are preserved.
+ *
+ * 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 HOOK_COMMAND_MARKER = 'agileflow hook';
+const HOOK_TIMEOUT_SECONDS = 30;
+
+/**
+ * The 6 hook registrations we own. Each is `{ event, matcher?, command }`.
+ * 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' },
+];
+
+const MANAGED_EVENTS = new Set(MANAGED_HOOKS.map((h) => h.event));
+
+/**
+ * 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;
+  return entry.hooks.some(
+    (h) =>
+      h &&
+      typeof h === 'object' &&
+      h.type === 'command' &&
+      typeof h.command === 'string' &&
+      h.command.includes(HOOK_COMMAND_MARKER),
+  );
+}
+
+/**
+ * Build a fresh entry for one MANAGED_HOOKS row.
+ * @param {{ matcher: string|null, command: string }} hook
+ */
+function buildEntry({ matcher, command }) {
+  /** @type {{ matcher?: string, hooks: object[] }} */
+  const out = {
+    hooks: [
+      { type: 'command', command, timeout: HOOK_TIMEOUT_SECONDS },
+    ],
+  };
+  if (matcher) out.matcher = matcher;
+  return out;
+}
+
+/**
+ * Read existing settings.json (or {} if absent / malformed).
+ * @param {string} settingsPath
+ * @returns {Promise<object>}
+ */
+async function readExisting(settingsPath) {
+  try {
+    const raw = await fs.promises.readFile(settingsPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return {};
+    return parsed;
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    if (err instanceof SyntaxError) return {};
+    throw err;
+  }
+}
+
+/**
+ * Atomically write the merged settings.
+ * @param {string} settingsPath
+ * @param {object} settings
+ */
+async function writeMerged(settingsPath, settings) {
+  await fs.promises.mkdir(path.dirname(settingsPath), { recursive: true });
+  const tmp = path.join(
+    path.dirname(settingsPath),
+    `.${path.basename(settingsPath)}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
+  );
+  const text = JSON.stringify(settings, null, 2) + '\n';
+  try {
+    await fs.promises.writeFile(tmp, text, 'utf8');
+    await fs.promises.rename(tmp, settingsPath);
+  } catch (err) {
+    try {
+      await fs.promises.unlink(tmp);
+    } catch {
+      /* swallow */
+    }
+    throw err;
+  }
+}
+
+/**
+ * Compute the merged settings: drop any existing AgileFlow entries from
+ * the events we manage, append our fresh ones in the canonical order,
+ * leave everything else alone.
+ *
+ * @param {object} existing
+ * @returns {object}
+ */
+function mergeManagedHooks(existing) {
+  const next = { ...existing };
+  // Reject array-shaped `hooks`: spreading an array into a plain object
+  // produces numeric-keyed garbage. Treat it as missing instead.
+  const baseHooks =
+    existing.hooks &&
+    typeof existing.hooks === 'object' &&
+    !Array.isArray(existing.hooks)
+      ? existing.hooks
+      : {};
+  const hooks = { ...baseHooks };
+
+  for (const event of MANAGED_EVENTS) {
+    const prior = Array.isArray(hooks[event]) ? hooks[event] : [];
+    // Strip our previous registrations, keep user's other entries.
+    const userEntries = prior.filter((e) => !isAgileflowEntry(e));
+    const ours = MANAGED_HOOKS.filter((h) => h.event === event).map(buildEntry);
+    hooks[event] = [...ours, ...userEntries];
+  }
+
+  next.hooks = hooks;
+  return next;
+}
+
+/**
+ * Compute the unmanaged settings: strip AgileFlow entries from every
+ * event we manage. Used when switching to a non-claude-code IDE.
+ *
+ * @param {object} existing
+ * @returns {object}
+ */
+function unmanageHooks(existing) {
+  const next = { ...existing };
+  if (
+    !existing.hooks ||
+    typeof existing.hooks !== 'object' ||
+    Array.isArray(existing.hooks)
+  ) {
+    return next;
+  }
+  const hooks = { ...existing.hooks };
+  for (const event of MANAGED_EVENTS) {
+    if (!Array.isArray(hooks[event])) continue;
+    const userEntries = hooks[event].filter((e) => !isAgileflowEntry(e));
+    if (userEntries.length === 0) {
+      delete hooks[event];
+    } else {
+      hooks[event] = userEntries;
+    }
+  }
+  // If hooks ended up with no keys, drop the field entirely.
+  if (Object.keys(hooks).length === 0) {
+    delete next.hooks;
+  } else {
+    next.hooks = hooks;
+  }
+  return next;
+}
+
+/**
+ * Register the 6 AgileFlow hooks in `<projectRoot>/.claude/settings.json`.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<string>} absolute path of the written settings file
+ */
+async function writeClaudeCodeSettings(projectRoot) {
+  const settingsPath = path.join(projectRoot, '.claude', 'settings.json');
+  const existing = await readExisting(settingsPath);
+  const merged = mergeManagedHooks(existing);
+  await writeMerged(settingsPath, merged);
+  return settingsPath;
+}
+
+/**
+ * Strip AgileFlow hook registrations from settings.json. If the file
+ * ends up empty (no hooks AND no other fields), it's removed; if it
+ * still has content, the cleaned version is written back.
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<{ removed: boolean, settingsPath: string|null }>}
+ */
+async function removeClaudeCodeSettings(projectRoot) {
+  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
+  // removing entries that are still in an unreadable file.
+  const existing = await readExisting(settingsPath);
+  const next = unmanageHooks(existing);
+  if (Object.keys(next).length === 0) {
+    try {
+      await fs.promises.unlink(settingsPath);
+      return { removed: true, settingsPath };
+    } catch (err) {
+      if (err.code === 'ENOENT') return { removed: false, settingsPath: null };
+      throw err;
+    }
+  }
+  await writeMerged(settingsPath, next);
+  return { removed: false, settingsPath };
+}
+
+module.exports = {
+  writeClaudeCodeSettings,
+  removeClaudeCodeSettings,
+  mergeManagedHooks,
+  unmanageHooks,
+  isAgileflowEntry,
+  MANAGED_HOOKS,
+  MANAGED_EVENTS,
+  HOOK_COMMAND_MARKER,
+  HOOK_TIMEOUT_SECONDS,
+};