agileflow 3.4.3 → 4.0.0-alpha.2

package/src/runtime/config/loader.js

@@ -0,0 +1,117 @@
+/**
+ * Unified config loader for AgileFlow v4.
+ *
+ * Reads `agileflow.config.json` from a project root, validates against the
+ * JSON Schema, merges with defaults, and returns a frozen config object.
+ *
+ * Missing file → returns defaults (not an error — first-run case).
+ * Invalid JSON → throws with the file path.
+ * Schema violation → throws with a JSON Pointer to the offending field.
+ */
+const fs = require("fs");
+const path = require("path");
+const Ajv = require("ajv");
+
+const schema = require("./schema.json");
+const { defaultConfig } = require("./defaults.js");
+
+const CONFIG_FILENAME = "agileflow.config.json";
+
+const ajv = new Ajv({ allErrors: true, useDefaults: false, strict: false });
+const validate = ajv.compile(schema);
+
+/**
+ * Shallow-merge user config on top of defaults. `plugins`, `hooks`, and
+ * `personalization` sub-objects are deep-merged at one level so that
+ * partial user configs don't wipe defaults.
+ *
+ * @param {import('./defaults.js').AgileflowConfig} defaults
+ * @param {Partial<import('./defaults.js').AgileflowConfig>} user
+ * @returns {import('./defaults.js').AgileflowConfig}
+ */
+function mergeConfig(defaults, user) {
+  return {
+    version: user.version ?? defaults.version,
+    plugins: { ...defaults.plugins, ...(user.plugins || {}) },
+    hooks: { ...defaults.hooks, ...(user.hooks || {}) },
+    behaviors: { ...defaults.behaviors, ...(user.behaviors || {}) },
+    personalization: {
+      ...defaults.personalization,
+      ...(user.personalization || {}),
+    },
+    ide: { ...defaults.ide, ...(user.ide || {}) },
+    language: user.language ?? defaults.language,
+  };
+}
+
+/**
+ * Format Ajv errors as a single human-readable message with JSON Pointers.
+ * @param {import('ajv').ErrorObject[]} errors
+ * @returns {string}
+ */
+function formatSchemaErrors(errors) {
+  return errors
+    .map((e) => `  • ${e.instancePath || "/"} ${e.message}`)
+    .join("\n");
+}
+
+/**
+ * Load config from the given project root.
+ *
+ * @param {string} cwd - project root directory
+ * @returns {Promise<{
+ *   config: import('./defaults.js').AgileflowConfig,
+ *   path: string | null,
+ *   source: 'file' | 'defaults'
+ * }>}
+ */
+async function loadConfig(cwd) {
+  const configPath = path.join(cwd, CONFIG_FILENAME);
+
+  // Read directly and treat ENOENT as "no config → use defaults". This
+  // eliminates the existsSync-then-readFileSync TOCTOU window; between
+  // the two calls another process could delete the file and the user
+  // would get a misleading "Failed to read" error instead of defaults.
+  let raw;
+  try {
+    raw = fs.readFileSync(configPath, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return Object.freeze({
+        config: Object.freeze(defaultConfig()),
+        path: null,
+        source: "defaults",
+      });
+    }
+    throw new Error(`Failed to read ${configPath}: ${err.message}`);
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Invalid JSON in ${configPath}: ${err.message}`);
+  }
+
+  if (!validate(parsed)) {
+    const details = formatSchemaErrors(validate.errors || []);
+    throw new Error(`Config validation failed for ${configPath}:\n${details}`);
+  }
+
+  const merged = mergeConfig(defaultConfig(), parsed);
+  // Core plugin cannot be disabled — enforce at load time.
+  merged.plugins.core = { ...merged.plugins.core, enabled: true };
+
+  return Object.freeze({
+    config: Object.freeze(merged),
+    path: configPath,
+    source: "file",
+  });
+}
+
+module.exports = {
+  CONFIG_FILENAME,
+  loadConfig,
+  mergeConfig,
+  formatSchemaErrors,
+};

package/src/runtime/config/schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/projectquestorg/AgileFlow/apps/cli/config.schema.json",
+  "title": "AgileFlow v4 user config",
+  "description": "User-facing configuration for AgileFlow v4. Lives at agileflow.config.json in project root.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Config schema version. Bumped on breaking changes."
+    },
+    "plugins": {
+      "type": "object",
+      "description": "Map of plugin-id -> { enabled: bool, settings?: object }. core is always enabled.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "settings": { "type": "object", "additionalProperties": true }
+        },
+        "required": ["enabled"]
+      }
+    },
+    "hooks": {
+      "type": "object",
+      "description": "Per-hook-id user overrides applied on top of plugin-supplied defaults.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "timeout": { "type": "integer", "minimum": 0, "maximum": 60000 },
+          "skipOnError": { "type": "boolean" }
+        }
+      }
+    },
+    "behaviors": {
+      "type": "object",
+      "description": "Curated behavior presets. Each maps to one or more hooks the installer wires up. Disabling a behavior excludes its hooks from the generated hook-manifest.yaml.",
+      "additionalProperties": false,
+      "properties": {
+        "loadContext": {
+          "type": "boolean",
+          "description": "SessionStart: print project context (stories, dirty files, recent commits) for Claude to consume."
+        },
+        "babysitDefault": {
+          "type": "boolean",
+          "description": "SessionStart: inject the babysit-mentor pattern so Claude defaults to mentor mode without explicit invocation."
+        },
+        "damageControl": {
+          "type": "boolean",
+          "description": "PreToolUse: block dangerous Bash commands and risky Edit/Write paths via the patterns library."
+        },
+        "preCompactState": {
+          "type": "boolean",
+          "description": "PreCompact: capture story IDs, active command, and dirty git state so they survive Claude's compaction summary."
+        }
+      }
+    },
+    "personalization": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tone": {
+          "type": "string",
+          "enum": ["concise", "detailed", "teaching"]
+        },
+        "ask_level": {
+          "type": "string",
+          "enum": ["none", "decision_points", "always"]
+        },
+        "verbosity": {
+          "type": "string",
+          "enum": ["low", "medium", "high"]
+        }
+      }
+    },
+    "ide": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "primary": {
+          "type": "string",
+          "enum": ["claude-code", "cursor", "windsurf", "codex"]
+        }
+      }
+    },
+    "language": {
+      "type": "string",
+      "description": "IETF BCP 47 language tag (e.g. 'en', 'es', 'pt-BR').",
+      "pattern": "^[a-z]{2}(-[A-Z][a-zA-Z0-9]+)?$"
+    }
+  }
+}

package/src/runtime/config/writer.js

@@ -0,0 +1,55 @@
+/**
+ * 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,
+    behaviors: config.behaviors,
+    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,157 @@
+/**
+ * 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.
+ *
+ * Behavior gating: a plugin hook entry may declare `behavior: <key>`
+ * (e.g. `behavior: damageControl`). When `behaviors` is supplied and
+ * the corresponding key is `false`, the hook is excluded from the
+ * generated manifest — its script never runs at runtime. Hooks
+ * without a `behavior` field are always included (they're not part
+ * of the curated preset surface).
+ *
+ * @param {PluginManifest[]} orderedPlugins
+ * @param {Record<string, boolean>} [behaviors] - user's behavior toggles
+ * @returns {{ version: 1, hooks: Array<object> }}
+ */
+function buildHookManifest(orderedPlugins, behaviors) {
+  /** @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;
+      // Behavior-gated hooks are skipped when the user disabled the
+      // preset. A missing `behavior` field means "always include".
+      if (
+        typeof entry.behavior === "string" &&
+        behaviors &&
+        behaviors[entry.behavior] === false
+      ) {
+        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/
+ * @param {Record<string, boolean>} [behaviors] - user's behavior toggles
+ * @returns {Promise<string>} absolute path of the written manifest
+ */
+async function writeAggregatedManifest(
+  orderedPlugins,
+  agileflowDir,
+  behaviors,
+) {
+  const manifest = buildHookManifest(orderedPlugins, behaviors);
+  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 };