agileflow 3.4.2 → 4.0.0-alpha.1

package/src/runtime/config/writer.js

@@ -0,0 +1,54 @@
+/**
+ * Config writer — writes `agileflow.config.json` to a project root atomically.
+ *
+ * Write strategy: render to a temp file (`.agileflow.config.json.tmp-<pid>`)
+ * in the same directory, then `fs.rename()` into place. Same-directory
+ * rename is atomic on POSIX and on Windows for files on the same volume,
+ * so readers always see either the old content or the new content — never
+ * a truncated half-write.
+ *
+ * Serializes only the user-facing fields (drops internal loader metadata
+ * like `source`/`path`). Adds `$schema` pointer for editor validation.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const { CONFIG_FILENAME } = require('./loader.js');
+
+const SCHEMA_REF = './node_modules/agileflow/src/runtime/config/schema.json';
+
+/**
+ * @param {string} cwd - project root
+ * @param {import('./defaults.js').AgileflowConfig} config
+ * @returns {Promise<string>} absolute path of the written config file
+ */
+async function writeConfig(cwd, config) {
+  const file = path.join(cwd, CONFIG_FILENAME);
+  const tmp = path.join(cwd, `.${CONFIG_FILENAME}.tmp-${process.pid}`);
+  const payload = {
+    $schema: SCHEMA_REF,
+    version: 1,
+    plugins: config.plugins,
+    hooks: config.hooks,
+    personalization: config.personalization,
+    ide: config.ide,
+    language: config.language,
+  };
+  const content = JSON.stringify(payload, null, 2) + '\n';
+
+  try {
+    await fs.promises.writeFile(tmp, content, 'utf8');
+    await fs.promises.rename(tmp, file);
+  } catch (err) {
+    // Best-effort cleanup of the temp file on failure. Ignore cleanup errors.
+    try {
+      await fs.promises.unlink(tmp);
+    } catch {
+      /* swallow */
+    }
+    throw err;
+  }
+  return file;
+}
+
+module.exports = { writeConfig, SCHEMA_REF };

package/src/runtime/hooks/aggregator.js

@@ -0,0 +1,133 @@
+/**
+ * Hook manifest aggregator.
+ *
+ * At install time, walks every enabled plugin's `provides.hooks` array
+ * and produces a single `.agileflow/hook-manifest.yaml` that the
+ * orchestrator (and the 6 dispatchers) read at runtime.
+ *
+ * Plugin manifests declare hooks with paths relative to the plugin's
+ * source directory:
+ *
+ *   provides:
+ *     hooks:
+ *       - id: babysit-clear-restore
+ *         event: SessionStart
+ *         script: hooks/babysit-clear-restore.js
+ *         timeout: 5000
+ *         skipOnError: true
+ *
+ * The aggregator rewrites the script path to be relative to the
+ * project root (so the orchestrator can find it after install):
+ *
+ *   - script: .agileflow/plugins/core/hooks/babysit-clear-restore.js
+ *
+ * Aggregation is content-only — the loader's strict validator runs
+ * afterwards when the orchestrator reads the file, so any malformed
+ * plugin contribution surfaces with a clear error rather than silently
+ * misbehaving.
+ */
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const HEADER_COMMENT =
+  '# Auto-generated by `agileflow setup` / `agileflow update`.\n' +
+  '# Do not edit by hand — your changes will be overwritten on the next install.\n' +
+  '# To override per-hook settings (timeout, skipOnError, enabled),\n' +
+  '# use the `hooks:` map in agileflow.config.json instead.\n' +
+  '#\n';
+
+/**
+ * @typedef {import('../plugins/registry.js').PluginManifest} PluginManifest
+ */
+
+/**
+ * Build a single normalized hook-manifest object from the ordered set
+ * of enabled plugins. Pure: no I/O.
+ *
+ * @param {PluginManifest[]} orderedPlugins
+ * @returns {{ version: 1, hooks: Array<object> }}
+ */
+function buildHookManifest(orderedPlugins) {
+  /** @type {Array<object>} */
+  const hooks = [];
+  for (const plugin of orderedPlugins) {
+    const provided =
+      plugin.provides && Array.isArray(plugin.provides.hooks)
+        ? plugin.provides.hooks
+        : [];
+    for (const entry of provided) {
+      if (!entry || typeof entry !== 'object') continue;
+      if (typeof entry.id !== 'string' || typeof entry.script !== 'string') continue;
+      const out = {
+        id: entry.id,
+        event: entry.event,
+        script: `.agileflow/plugins/${plugin.id}/${entry.script}`,
+      };
+      if (entry.matcher != null) out.matcher = entry.matcher;
+      if (Array.isArray(entry.runAfter)) out.runAfter = entry.runAfter;
+      if (typeof entry.timeout === 'number') out.timeout = entry.timeout;
+      if (typeof entry.skipOnError === 'boolean') out.skipOnError = entry.skipOnError;
+      if (typeof entry.enabled === 'boolean') out.enabled = entry.enabled;
+      hooks.push(out);
+    }
+  }
+  return { version: 1, hooks };
+}
+
+/**
+ * Aggregate + atomically write the hook manifest to disk. Call only
+ * when the target IDE supports hooks (i.e. claude-code today).
+ *
+ * @param {PluginManifest[]} orderedPlugins
+ * @param {string} agileflowDir - absolute path to .agileflow/
+ * @returns {Promise<string>} absolute path of the written manifest
+ */
+async function writeAggregatedManifest(orderedPlugins, agileflowDir) {
+  const manifest = buildHookManifest(orderedPlugins);
+  const dest = path.join(agileflowDir, 'hook-manifest.yaml');
+  const yamlText = HEADER_COMMENT + yaml.dump(manifest, { noRefs: true });
+
+  await fs.promises.mkdir(agileflowDir, { recursive: true });
+  const tmp = path.join(
+    agileflowDir,
+    `.hook-manifest.yaml.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
+  );
+  try {
+    await fs.promises.writeFile(tmp, yamlText, 'utf8');
+    await fs.promises.rename(tmp, dest);
+  } catch (err) {
+    try {
+      await fs.promises.unlink(tmp);
+    } catch {
+      /* swallow */
+    }
+    throw err;
+  }
+  return dest;
+}
+
+/**
+ * Remove the hook manifest if it exists. Used when switching to a
+ * non-claude-code IDE so a stale claude-code manifest doesn't linger.
+ *
+ * @param {string} agileflowDir
+ * @returns {Promise<boolean>} true if a file was removed
+ */
+async function removeAggregatedManifest(agileflowDir) {
+  const dest = path.join(agileflowDir, 'hook-manifest.yaml');
+  try {
+    await fs.promises.unlink(dest);
+    return true;
+  } catch (err) {
+    if (err.code === 'ENOENT') return false;
+    throw err;
+  }
+}
+
+module.exports = {
+  buildHookManifest,
+  writeAggregatedManifest,
+  removeAggregatedManifest,
+  HEADER_COMMENT,
+};

package/src/runtime/hooks/chain.js

@@ -0,0 +1,93 @@
+/**
+ * Hook chain ordering.
+ *
+ * Given a list of `HookEntry` for a single event, returns the topological
+ * order in which they must be executed (dependencies before dependents)
+ * and detects cycles with a clear error message that names the cycle path.
+ *
+ * Filtering by event happens upstream — `orderChain` accepts whatever
+ * the caller gives it.
+ */
+
+const COLOR_WHITE = 0;
+const COLOR_GRAY = 1;
+const COLOR_BLACK = 2;
+
+/**
+ * @typedef {import('./manifest-loader.js').HookEntry} HookEntry
+ */
+
+/**
+ * Validate that every `runAfter` entry resolves to a hook id in this set.
+ * @param {HookEntry[]} hooks
+ * @param {Map<string, HookEntry>} byId
+ */
+function assertRunAfterExists(hooks, byId) {
+  for (const h of hooks) {
+    for (const dep of h.runAfter) {
+      if (!byId.has(dep)) {
+        throw new Error(
+          `Hook "${h.id}" runAfter references unknown hook "${dep}" (in same event chain)`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Topologically sort the chain. Hooks with `runAfter: [a, b]` come AFTER
+ * a and b. Within a layer, ordering is stable on the original input order
+ * so two ready-to-run hooks keep their declaration order.
+ *
+ * @param {HookEntry[]} hooks
+ * @returns {HookEntry[]}
+ * @throws {Error} on cycles or unresolved runAfter targets
+ */
+function orderChain(hooks) {
+  const byId = new Map(hooks.map((h) => [h.id, h]));
+  if (byId.size !== hooks.length) {
+    // Caller should have rejected duplicates upstream; defensive check.
+    const seen = new Set();
+    for (const h of hooks) {
+      if (seen.has(h.id)) throw new Error(`duplicate hook id in chain: ${h.id}`);
+      seen.add(h.id);
+    }
+  }
+  assertRunAfterExists(hooks, byId);
+
+  /** @type {Map<string, number>} */
+  const color = new Map();
+  /** @type {HookEntry[]} */
+  const order = [];
+
+  /**
+   * @param {string} id
+   * @param {string[]} stack
+   */
+  function visit(id, stack) {
+    const c = color.get(id) ?? COLOR_WHITE;
+    if (c === COLOR_BLACK) return;
+    if (c === COLOR_GRAY) {
+      const start = stack.indexOf(id);
+      const cycle = [...stack.slice(start), id].join(' -> ');
+      throw new Error(`Hook chain cycle detected: ${cycle}`);
+    }
+    color.set(id, COLOR_GRAY);
+    const h = byId.get(id);
+    const next = [...stack, id];
+    for (const dep of h.runAfter) {
+      visit(dep, next);
+    }
+    color.set(id, COLOR_BLACK);
+    order.push(h);
+  }
+
+  // Visit in declaration order so within a topological "layer" the
+  // original order is preserved.
+  for (const h of hooks) {
+    visit(h.id, []);
+  }
+  return order;
+}
+
+module.exports = { orderChain };

package/src/runtime/hooks/logger.js

@@ -0,0 +1,68 @@
+/**
+ * Hook execution logger.
+ *
+ * Appends one JSON object per line to `.agileflow/logs/hook-execution.jsonl`.
+ * The orchestrator writes one entry per hook invocation, capturing
+ * timing, exit code, and truncated stdout/stderr.
+ *
+ * Log file is created on first write; missing parent directories are
+ * created automatically. Append-only — log rotation is a future concern.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const MAX_OUTPUT_BYTES = 4 * 1024; // 4 KB cap per stream
+
+/**
+ * @typedef {Object} HookLogEntry
+ * @property {string} timestamp - ISO 8601
+ * @property {string} event
+ * @property {string} hookId
+ * @property {'ok'|'error'|'timeout'|'skipped'} status
+ * @property {number|null} exitCode
+ * @property {number} durationMs
+ * @property {string} [stdout]
+ * @property {string} [stderr]
+ * @property {boolean} [skippedByOnError] - true when status='error' was tolerated due to skipOnError
+ * @property {string} [reason] - free-form note (e.g. why skipped)
+ */
+
+/**
+ * Truncate a string buffer to `MAX_OUTPUT_BYTES` to keep the log line
+ * bounded. Cuts on byte length, not code units, so trailing multi-byte
+ * sequences are stripped cleanly.
+ * @param {string|Buffer|undefined} value
+ * @returns {string}
+ */
+function truncate(value) {
+  if (value == null || value === '') return '';
+  const buf = Buffer.isBuffer(value) ? value : Buffer.from(String(value), 'utf8');
+  if (buf.length <= MAX_OUTPUT_BYTES) return buf.toString('utf8');
+  return buf.subarray(0, MAX_OUTPUT_BYTES).toString('utf8') + '\n…[truncated]';
+}
+
+/**
+ * Append one entry to the JSONL log.
+ *
+ * Throws on filesystem failures so the orchestrator can surface them in
+ * structured exit codes — but in practice the orchestrator wraps this
+ * in a try/catch and never fails because of a logging error.
+ *
+ * @param {string} logPath - absolute path to hook-execution.jsonl
+ * @param {HookLogEntry} entry
+ */
+async function appendHookLog(logPath, entry) {
+  await fs.promises.mkdir(path.dirname(logPath), { recursive: true });
+  const normalized = {
+    ...entry,
+    stdout: entry.stdout == null ? undefined : truncate(entry.stdout),
+    stderr: entry.stderr == null ? undefined : truncate(entry.stderr),
+  };
+  // Drop undefined keys so the JSONL line is compact.
+  for (const k of Object.keys(normalized)) {
+    if (normalized[k] === undefined) delete normalized[k];
+  }
+  await fs.promises.appendFile(logPath, JSON.stringify(normalized) + '\n', 'utf8');
+}
+
+module.exports = { appendHookLog, truncate, MAX_OUTPUT_BYTES };

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