agileflow 3.4.3 → 4.0.0-alpha.2

package/src/runtime/hooks/manifest-loader.js

@@ -0,0 +1,228 @@
+/**
+ * Hook manifest loader.
+ *
+ * Reads `.agileflow/hook-manifest.yaml` and returns a normalized array
+ * of hook entries. Schema:
+ *
+ *   version: 1
+ *   hooks:
+ *     - id: damage-control-bash
+ *       event: PreToolUse              # one of VALID_EVENTS
+ *       matcher: Bash                  # optional; only meaningful on tool events
+ *       script: .agileflow/plugins/core/hooks/damage-control-bash.js
+ *       runAfter: []                   # optional, default []
+ *       timeout: 3000                  # optional, default 10000 ms
+ *       skipOnError: false             # optional, default true
+ *       enabled: true                  # optional, default true
+ *
+ * Returns null when the file does not exist (treated as "no hooks
+ * registered" by callers). Throws with a clear message on invalid
+ * YAML or schema violations — partial/silent acceptance is the v3
+ * anti-pattern that caused the cascade failures we're fixing.
+ *
+ * Event list mirrors the official Claude Code hooks reference
+ * (https://code.claude.com/docs/en/hooks); kept in sync manually.
+ * The docs grow over time — when a new event lands, add it here.
+ */
+const fs = require('fs');
+const yaml = require('js-yaml');
+
+/** @type {ReadonlySet<string>} */
+const VALID_EVENTS = new Set([
+  'SessionStart',
+  'SessionEnd',
+  'UserPromptSubmit',
+  'UserPromptExpansion',
+  'PreToolUse',
+  'PermissionRequest',
+  'PermissionDenied',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'PostToolBatch',
+  'PreCompact',
+  'PostCompact',
+  'Stop',
+  'StopFailure',
+  'SubagentStart',
+  'SubagentStop',
+  'TaskCreated',
+  'TaskCompleted',
+  'TeammateIdle',
+  'InstructionsLoaded',
+  'ConfigChange',
+  'CwdChanged',
+  'FileChanged',
+  'WorktreeCreate',
+  'WorktreeRemove',
+  'Notification',
+  'Elicitation',
+  'ElicitationResult',
+]);
+
+/**
+ * Events that support a `matcher` field (per the Claude Code docs).
+ * Specifying a `matcher` on any other event is a manifest error.
+ * @type {ReadonlySet<string>}
+ */
+const MATCHER_EVENTS = new Set([
+  'PreToolUse',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'PermissionRequest',
+  'PermissionDenied',
+]);
+
+const MANIFEST_VERSION = 1;
+const DEFAULT_TIMEOUT_MS = 10000;
+
+/**
+ * @typedef {Object} HookEntry
+ * @property {string} id
+ * @property {string} event
+ * @property {string|null} matcher
+ * @property {string} script
+ * @property {string[]} runAfter
+ * @property {number} timeout
+ * @property {boolean} skipOnError
+ * @property {boolean} enabled
+ *
+ * @typedef {Object} HookManifest
+ * @property {1} version
+ * @property {HookEntry[]} hooks
+ */
+
+/**
+ * @param {*} raw
+ * @param {number} index
+ * @returns {HookEntry}
+ */
+function normalizeHook(raw, index) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error(`hook[${index}] must be an object`);
+  }
+  if (typeof raw.id !== 'string' || !raw.id) {
+    throw new Error(`hook[${index}].id must be a non-empty string`);
+  }
+  if (typeof raw.event !== 'string' || !VALID_EVENTS.has(raw.event)) {
+    throw new Error(
+      `hook[${index} (${raw.id})].event must be one of: ${[...VALID_EVENTS].sort().join(', ')}`,
+    );
+  }
+  /** @type {string|null} */
+  let matcher = null;
+  if (raw.matcher != null) {
+    if (typeof raw.matcher !== 'string') {
+      throw new Error(`hook[${raw.id}].matcher must be a string`);
+    }
+    if (!MATCHER_EVENTS.has(raw.event)) {
+      throw new Error(
+        `hook[${raw.id}].matcher is not allowed on event "${raw.event}"; matcher is only valid on tool-related events: ${[...MATCHER_EVENTS].join(', ')}`,
+      );
+    }
+    matcher = raw.matcher;
+  }
+  if (typeof raw.script !== 'string' || !raw.script) {
+    throw new Error(`hook[${index} (${raw.id})].script must be a non-empty string`);
+  }
+  let runAfter = [];
+  if (raw.runAfter != null) {
+    if (!Array.isArray(raw.runAfter)) {
+      throw new Error(`hook[${raw.id}].runAfter must be an array`);
+    }
+    for (const dep of raw.runAfter) {
+      if (typeof dep !== 'string' || !dep) {
+        throw new Error(`hook[${raw.id}].runAfter contains invalid entry: ${JSON.stringify(dep)}`);
+      }
+    }
+    runAfter = raw.runAfter;
+  }
+  let timeout = DEFAULT_TIMEOUT_MS;
+  if (raw.timeout != null) {
+    if (typeof raw.timeout !== 'number' || !Number.isFinite(raw.timeout) || raw.timeout < 0) {
+      throw new Error(`hook[${raw.id}].timeout must be a non-negative number (ms)`);
+    }
+    timeout = raw.timeout;
+  }
+  let skipOnError = true;
+  if (raw.skipOnError != null) {
+    if (typeof raw.skipOnError !== 'boolean') {
+      throw new Error(`hook[${raw.id}].skipOnError must be a boolean`);
+    }
+    skipOnError = raw.skipOnError;
+  }
+  let enabled = true;
+  if (raw.enabled != null) {
+    if (typeof raw.enabled !== 'boolean') {
+      throw new Error(`hook[${raw.id}].enabled must be a boolean`);
+    }
+    enabled = raw.enabled;
+  }
+  return {
+    id: raw.id,
+    event: raw.event,
+    matcher,
+    script: raw.script,
+    runAfter,
+    timeout,
+    skipOnError,
+    enabled,
+  };
+}
+
+/**
+ * @param {*} parsed
+ * @returns {HookManifest}
+ */
+function normalizeManifest(parsed) {
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('hook manifest must be an object');
+  }
+  if (parsed.version !== MANIFEST_VERSION) {
+    throw new Error(
+      `hook manifest version must be ${MANIFEST_VERSION}, got ${JSON.stringify(parsed.version)}`,
+    );
+  }
+  if (!Array.isArray(parsed.hooks)) {
+    throw new Error('hook manifest `hooks` must be an array');
+  }
+  const hooks = parsed.hooks.map(normalizeHook);
+  const seen = new Set();
+  for (const h of hooks) {
+    if (seen.has(h.id)) {
+      throw new Error(`duplicate hook id: ${h.id}`);
+    }
+    seen.add(h.id);
+  }
+  return { version: MANIFEST_VERSION, hooks };
+}
+
+/**
+ * @param {string} manifestPath
+ * @returns {Promise<HookManifest|null>}
+ */
+async function loadHookManifest(manifestPath) {
+  let raw;
+  try {
+    raw = await fs.promises.readFile(manifestPath, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  let parsed;
+  try {
+    parsed = yaml.load(raw);
+  } catch (err) {
+    throw new Error(`Invalid YAML in ${manifestPath}: ${err.message}`);
+  }
+  return normalizeManifest(parsed);
+}
+
+module.exports = {
+  loadHookManifest,
+  normalizeManifest,
+  normalizeHook,
+  VALID_EVENTS,
+  MATCHER_EVENTS,
+  MANIFEST_VERSION,
+  DEFAULT_TIMEOUT_MS,
+};

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,
+};