agileflow 3.4.3 → 4.0.0-alpha.10

package/src/lib/hash.js

@@ -0,0 +1,41 @@
+/**
+ * SHA256 helpers.
+ *
+ * `sha256Hex` accepts either a Buffer or a string. Strings are encoded as
+ * UTF-8 for hashing so the output is deterministic regardless of whether
+ * the caller holds a pre-rendered text string or the raw file bytes.
+ */
+const crypto = require('crypto');
+const fs = require('fs');
+
+/**
+ * @param {Buffer|string} content
+ * @returns {string} lowercase hex digest
+ * @throws {TypeError} if content is null or undefined
+ */
+function sha256Hex(content) {
+  if (content == null) {
+    throw new TypeError(
+      `sha256Hex: content must be Buffer or string, got ${content === null ? 'null' : 'undefined'}`,
+    );
+  }
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+/**
+ * Hash a file on disk. Returns null if the file does not exist.
+ * @param {string} filePath
+ * @returns {Promise<string|null>}
+ */
+async function sha256File(filePath) {
+  try {
+    const data = await fs.promises.readFile(filePath);
+    return sha256Hex(data);
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+module.exports = { sha256Hex, sha256File };

package/src/lib/path-check.js

@@ -0,0 +1,39 @@
+/**
+ * Check whether a command is resolvable on the user's PATH.
+ *
+ * Used by `agileflow launch` to detect which AI CLIs (claude, codex,
+ * cursor-agent, aider) are installed so the onboarding picker only
+ * offers real choices.
+ *
+ * Implementation: shell out to `command -v` (POSIX) or `where` (Windows).
+ * Both are built-ins, present on every supported platform, and exit
+ * non-zero when the name is not found.
+ *
+ * Safety: the name argument is constrained to a conservative character
+ * class before being interpolated into the shell command. These are CLI
+ * binary names — not free-form user input — so the restriction is
+ * intentional rather than limiting.
+ */
+const { execSync } = require("child_process");
+
+const SAFE_NAME = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * @param {string} name
+ * @returns {boolean}
+ */
+function commandExists(name) {
+  if (typeof name !== "string" || !SAFE_NAME.test(name)) return false;
+
+  const probe =
+    process.platform === "win32" ? `where ${name}` : `command -v ${name}`;
+
+  try {
+    execSync(probe, { stdio: "ignore", shell: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = { commandExists, SAFE_NAME };

package/src/runtime/config/defaults.js

@@ -0,0 +1,66 @@
+/**
+ * Default user config.
+ *
+ * Returned when `agileflow.config.json` is absent. Also merged into
+ * user-supplied config so missing sections get sensible defaults.
+ *
+ * @typedef {Object} PluginEntry
+ * @property {boolean} enabled
+ * @property {Record<string, unknown>} [settings]
+ *
+ * @typedef {Object} Behaviors
+ * @property {boolean} loadContext         - SessionStart context dump
+ * @property {boolean} babysitDefault      - HARD mentor mode at SessionStart
+ * @property {boolean} damageControlBash   - PreToolUse guard on Bash
+ * @property {boolean} damageControlEdit   - PreToolUse guard on Edit
+ * @property {boolean} damageControlWrite  - PreToolUse guard on Write
+ * @property {boolean} preCompactState     - PreCompact state preservation
+ *
+ * @typedef {Object} AgileflowConfig
+ * @property {1} version
+ * @property {Record<string, PluginEntry>} plugins
+ * @property {Record<string, { enabled?: boolean, timeout?: number, skipOnError?: boolean }>} hooks
+ * @property {{ scope: 'project' | 'global' }} install
+ * @property {Behaviors} behaviors
+ * @property {{ enabled: boolean }} learnings
+ * @property {{ primary?: string, targets: Array<'claude-code'|'cursor'|'windsurf'|'codex'|'antigravity'> }} ide
+ * @property {string} language
+ */
+
+/** @returns {AgileflowConfig} */
+function defaultConfig() {
+  return {
+    version: 1,
+    plugins: {
+      core: { enabled: true },
+    },
+    hooks: {},
+    install: {
+      scope: "project",
+    },
+    behaviors: {
+      // Behaviors are presets that map to one or more hooks. The
+      // wizard surfaces these as a curated multiselect; advanced
+      // users can override individual hooks via the `hooks:` map.
+      loadContext: true,
+      babysitDefault: true,
+      damageControlBash: true,
+      damageControlEdit: true,
+      damageControlWrite: true,
+      preCompactState: true,
+    },
+    learnings: {
+      // Global on/off for the skill self-improvement system. When false,
+      // install-time scaffolding is skipped and no learnings hint is
+      // injected into the session prompt — the `agileflow learn` CLI
+      // still works for users who want to manually append signals.
+      enabled: true,
+    },
+    ide: {
+      targets: ["claude-code"],
+    },
+    language: "en",
+  };
+}
+
+module.exports = { defaultConfig };

package/src/runtime/config/loader.js

@@ -0,0 +1,186 @@
+/**
+ * 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);
+
+/**
+ * Migrate older config shapes into the current schema before validation.
+ * This keeps `agileflow setup` usable across alpha bumps even when a
+ * project already has an older config checked in.
+ *
+ * @param {any} parsed
+ * @returns {any}
+ */
+function migrateLegacyConfig(parsed) {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return parsed;
+  }
+
+  const migrated = { ...parsed };
+
+  if (
+    migrated.behaviors &&
+    typeof migrated.behaviors === "object" &&
+    !Array.isArray(migrated.behaviors)
+  ) {
+    const behaviors = { ...migrated.behaviors };
+    if (Object.prototype.hasOwnProperty.call(behaviors, "damageControl")) {
+      const damageControl = Boolean(behaviors.damageControl);
+      delete behaviors.damageControl;
+      behaviors.damageControlBash = damageControl;
+      behaviors.damageControlEdit = damageControl;
+      behaviors.damageControlWrite = damageControl;
+    }
+    migrated.behaviors = behaviors;
+  }
+
+  if (
+    migrated.ide &&
+    typeof migrated.ide === "object" &&
+    !Array.isArray(migrated.ide)
+  ) {
+    const ide = { ...migrated.ide };
+    if (!Array.isArray(ide.targets) || ide.targets.length === 0) {
+      if (typeof ide.primary === "string") {
+        ide.targets = [ide.primary];
+      }
+    }
+    migrated.ide = ide;
+  }
+
+  return migrated;
+}
+
+/**
+ * Shallow-merge user config on top of defaults. `plugins` and `hooks`
+ * 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 || {}) },
+    install: { ...defaults.install, ...(user.install || {}) },
+    behaviors: { ...defaults.behaviors, ...(user.behaviors || {}) },
+    learnings: { ...defaults.learnings, ...(user.learnings || {}) },
+    ide: mergeIde(defaults.ide, user.ide),
+    language: user.language ?? defaults.language,
+  };
+}
+
+/**
+ * Merge user `ide` block onto defaults, normalizing legacy `primary` into
+ * `targets`. Old configs (alpha.1 / alpha.2) shipped only `primary`; we
+ * migrate them in-memory so a single re-install moves them onto the new
+ * shape without forcing the user to hand-edit JSON.
+ *
+ * @param {{ targets: string[], primary?: string }} defaultsIde
+ * @param {{ targets?: string[], primary?: string } | undefined} userIde
+ * @returns {{ targets: string[], primary?: string }}
+ */
+function mergeIde(defaultsIde, userIde) {
+  const merged = { ...defaultsIde, ...(userIde || {}) };
+  if (!Array.isArray(merged.targets) || merged.targets.length === 0) {
+    merged.targets =
+      typeof merged.primary === "string"
+        ? [merged.primary]
+        : [...defaultsIde.targets];
+  }
+  return merged;
+}
+
+/**
+ * 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}`);
+  }
+
+  parsed = migrateLegacyConfig(parsed);
+
+  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,126 @@
+{
+  "$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" }
+        }
+      }
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Where AgileFlow is installed. Project installs write into the current repository; global installs write under the user's home directory.",
+      "properties": {
+        "scope": {
+          "type": "string",
+          "enum": ["project", "global"],
+          "description": "Install scope for config, AgileFlow state, and IDE mirrors."
+        }
+      }
+    },
+    "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."
+        },
+        "damageControlBash": {
+          "type": "boolean",
+          "description": "PreToolUse: block dangerous Bash commands (rm -rf /, fork bombs, etc.)."
+        },
+        "damageControlEdit": {
+          "type": "boolean",
+          "description": "PreToolUse: block risky Edit operations on sensitive paths (.env, .ssh/, etc.)."
+        },
+        "damageControlWrite": {
+          "type": "boolean",
+          "description": "PreToolUse: block risky Write operations on sensitive paths (.env, .ssh/, etc.)."
+        },
+        "preCompactState": {
+          "type": "boolean",
+          "description": "PreCompact: capture story IDs, active command, and dirty git state so they survive Claude's compaction summary."
+        }
+      }
+    },
+    "learnings": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Global on/off for the skill self-improvement system. When false, install-time scaffolding is skipped and no learnings hint is injected into the session prompt.",
+      "properties": {
+        "enabled": { "type": "boolean" }
+      }
+    },
+    "ide": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "primary": {
+          "type": "string",
+          "enum": ["claude-code", "cursor", "windsurf", "codex", "antigravity"],
+          "description": "Deprecated alias for targets[0]; kept for back-compat with prior alphas."
+        },
+        "targets": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "enum": [
+              "claude-code",
+              "cursor",
+              "windsurf",
+              "codex",
+              "antigravity"
+            ]
+          },
+          "description": "IDEs / CLIs to install AgileFlow surface into (skills, hooks, settings)."
+        }
+      }
+    },
+    "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,57 @@
+/**
+ * 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,
+    install: config.install,
+    behaviors: config.behaviors,
+    learnings: config.learnings,
+    ide: config.ide,
+    language: config.language,
+  };
+  const content = JSON.stringify(payload, null, 2) + "\n";
+
+  try {
+    await fs.promises.mkdir(cwd, { recursive: true });
+    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,
+};