@ironbee-ai/cli 0.6.2 → 0.7.0

package/dist/lib/config.js

@@ -6,20 +6,45 @@
  *   1. Global:  ~/.ironbee/config.json
  *   2. Project: <projectDir>/.ironbee/config.json
  *
- * Project config overrides global config (shallow merge per key).
+ * Project config overrides global config (deep merge for nested sections,
+ * shallow for primitives — see deepMerge).
+ *
+ * The pre-split layout (top-level `verifyPatterns` / `additionalVerifyPatterns`)
+ * is no longer supported. Configs carrying those fields throw at load time —
+ * patterns must move under `browser.*` (or the appropriate runtime under
+ * `backend.<runtime>.*`).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_BACKEND_NODE_EVIDENCE_PATHS = exports.DEFAULT_BACKEND_NODE_ALWAYS_REQUIRED = exports.DEFAULT_BROWSER_ALWAYS_REQUIRED = exports.DEFAULT_BROWSER_VERIFY_PATTERNS = exports.RUNTIME_TO_SERVER = exports.BACKEND_SERVERS = void 0;
 exports.loadConfig = loadConfig;
+exports.getActiveCycles = getActiveCycles;
 exports.requiresVerification = requiresVerification;
+exports.getRequiredToolsConfig = getRequiredToolsConfig;
 exports.getMcpServerEntry = getMcpServerEntry;
+exports.getNodeDevToolsMcpEntry = getNodeDevToolsMcpEntry;
 exports.getMaxRetries = getMaxRetries;
+exports.isCollectorConfigured = isCollectorConfigured;
 exports.isJobQueueEnabled = isJobQueueEnabled;
 exports.isRecordingEnabled = isRecordingEnabled;
+exports.getVerificationEnabled = getVerificationEnabled;
+exports.isAnalyticsEnabled = isAnalyticsEnabled;
+exports.isAnalyticsEmitOnStopEnabled = isAnalyticsEmitOnStopEnabled;
+exports.getAnalyticsEmitOnStopMinIntervalSeconds = getAnalyticsEmitOnStopMinIntervalSeconds;
+exports.isAnalyticsTurnEventsEnabled = isAnalyticsTurnEventsEnabled;
+exports.isAnalyticsStepEventsEnabled = isAnalyticsStepEventsEnabled;
+exports.isAnalyticsApiRequestEventsEnabled = isAnalyticsApiRequestEventsEnabled;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
 const logger_1 = require("./logger");
-const DEFAULT_VERIFY_PATTERNS = [
+/** Backend MCP servers in the runtime registry. Code change to extend. */
+exports.BACKEND_SERVERS = ["node-devtools"];
+/** Map runtime key (`node`) → backend server name (`node-devtools`). */
+exports.RUNTIME_TO_SERVER = {
+    node: "node-devtools",
+};
+/** Browser default verify patterns — preserves the pre-split list as-is. */
+exports.DEFAULT_BROWSER_VERIFY_PATTERNS = [
     "*.ts", "*.tsx",
     "*.js", "*.jsx", "*.mjs", "*.cjs",
     "*.vue", "*.svelte",
@@ -46,6 +71,36 @@ const DEFAULT_VERIFY_PATTERNS = [
     "*.hbs", "*.ejs", "*.pug", "*.jade",
     "*.astro",
 ];
+/** Browser-cycle required tools — strict all-of, no alternative paths. */
+exports.DEFAULT_BROWSER_ALWAYS_REQUIRED = [
+    "bdt_navigation_go-to",
+    "bdt_content_take-screenshot",
+    "bdt_a11y_take-aria-snapshot",
+    "bdt_o11y_get-console-messages",
+];
+/** Node-cycle required tools — connect always; then probe path or log path. */
+exports.DEFAULT_BACKEND_NODE_ALWAYS_REQUIRED = [
+    "ndt_debug_connect",
+];
+exports.DEFAULT_BACKEND_NODE_EVIDENCE_PATHS = [
+    {
+        name: "probe",
+        allOf: [
+            {
+                anyOf: [
+                    "ndt_debug_put-tracepoint",
+                    "ndt_debug_put-logpoint",
+                    "ndt_debug_put-exceptionpoint",
+                ],
+            },
+            "ndt_debug_get-probe-snapshots",
+        ],
+    },
+    {
+        name: "log",
+        allOf: ["ndt_debug_get-logs"],
+    },
+];
 const DEFAULT_MAX_RETRIES = 3;
 function loadJsonFile(filePath) {
     if (!(0, fs_1.existsSync)(filePath)) {
@@ -59,116 +114,282 @@ function loadJsonFile(filePath) {
         return {};
     }
 }
+/** Detect pre-split flat config. Loud failure per design D6. */
+function assertNoLegacyShape(config, sourcePath) {
+    const legacy = [];
+    if (Object.prototype.hasOwnProperty.call(config, "verifyPatterns")) {
+        legacy.push("'verifyPatterns'");
+    }
+    if (Object.prototype.hasOwnProperty.call(config, "additionalVerifyPatterns")) {
+        legacy.push("'additionalVerifyPatterns'");
+    }
+    if (legacy.length === 0) {
+        return;
+    }
+    throw new Error(`Legacy IronBee config detected in ${sourcePath}: ${legacy.join(", ")} at the top level is no longer supported. ` +
+        `Move them under 'browser.*' (or the appropriate runtime under 'backend.<runtime>.*').`);
+}
+function assertVerificationShape(config, sourcePath) {
+    if (!Object.prototype.hasOwnProperty.call(config, "verification")) {
+        return;
+    }
+    const v = config.verification;
+    if (v === null || typeof v !== "object" || Array.isArray(v)) {
+        throw new Error(`Invalid IronBee config in ${sourcePath}: 'verification' must be an object. ` +
+            `Expected shape: { "enable": boolean }.`);
+    }
+    const block = v;
+    if (Object.prototype.hasOwnProperty.call(block, "enable") && typeof block.enable !== "boolean") {
+        throw new Error(`Invalid IronBee config in ${sourcePath}: 'verification.enable' must be boolean. ` +
+            `Got ${typeof block.enable}.`);
+    }
+}
+/** Deep merge for the nested `browser` / `backend.<runtime>` blocks. */
+function mergeCycleConfig(base, override) {
+    if (base === undefined && override === undefined) {
+        return undefined;
+    }
+    return { ...(base ?? {}), ...(override ?? {}) };
+}
+function mergeBackend(base, override) {
+    if (base === undefined && override === undefined) {
+        return undefined;
+    }
+    const merged = {};
+    const keys = new Set([
+        ...Object.keys(base ?? {}),
+        ...Object.keys(override ?? {}),
+    ]);
+    for (const key of keys) {
+        merged[key] = mergeCycleConfig(base?.[key], override?.[key]);
+    }
+    return merged;
+}
 function loadConfig(projectDir) {
     const globalPath = (0, path_1.join)((0, os_1.homedir)(), ".ironbee", "config.json");
     const globalConfig = loadJsonFile(globalPath);
+    if ((0, fs_1.existsSync)(globalPath)) {
+        assertNoLegacyShape(globalConfig, globalPath);
+        assertVerificationShape(globalConfig, globalPath);
+    }
     let projectConfig = {};
+    let projectPath = "";
     if (projectDir) {
-        const projectPath = (0, path_1.join)(projectDir, ".ironbee", "config.json");
+        projectPath = (0, path_1.join)(projectDir, ".ironbee", "config.json");
         projectConfig = loadJsonFile(projectPath);
+        if ((0, fs_1.existsSync)(projectPath)) {
+            assertNoLegacyShape(projectConfig, projectPath);
+            assertVerificationShape(projectConfig, projectPath);
+        }
     }
-    // merge: defaults < global < project
     const merged = {
         ...globalConfig,
         ...projectConfig,
     };
+    merged.browser = mergeCycleConfig(globalConfig.browser, projectConfig.browser);
+    merged.backend = mergeBackend(globalConfig.backend, projectConfig.backend);
     return merged;
 }
-/**
- * Converts a glob pattern to a RegExp.
- * Supports: *, **, ?
- * Examples:
- *   "*.ts"                → matches "foo.ts"
- *   "src/components/**"   → matches "src/components/Button/index.tsx"
- *   "*.test.*"            → matches "foo.test.ts"
- */
+// Glob → RegExp. Supports *, **, ** + slash (zero-or-more segments), ?, and
+// brace expansion {a,b,c} → (a|b|c). The trailing-slash form of ** matches
+// the empty path, so "server/**/*.ts" correctly matches both "server/api.ts"
+// (depth 0) and "server/sub/api.ts" (depth 1+).
 function globToRegExp(pattern) {
-    let regexStr = pattern
-        .replace(/[.+^${}()|[\]\\]/g, "\\$&") // escape regex special chars (except * and ?)
-        .replace(/\*\*/g, "{{GLOBSTAR}}") // placeholder for **
-        .replace(/\*/g, "[^/]*") // * = anything except /
-        .replace(/\?/g, "[^/]") // ? = single char except /
-        .replace(/\{\{GLOBSTAR\}\}/g, ".*"); // ** = anything including /
-    // if pattern has no path separators, match against basename only
-    if (!pattern.includes("/")) {
-        regexStr = `(^|/)${regexStr}$`;
-    }
-    else {
-        regexStr = `(^|/)${regexStr}$`;
-    }
-    return new RegExp(regexStr);
+    // 1. Brace expansion `{a,b,c}` → `(a|b|c)` before any escaping.
+    let p = pattern.replace(/\{([^}]+)\}/g, (_match, group) => {
+        return `(${group.split(",").map((s) => s.trim()).join("|")})`;
+    });
+    // 2. Tokenize globs to placeholders so the escape pass leaves them alone.
+    p = p.replace(/\*\*\//g, "\x00DSS\x00") // **/
+        .replace(/\*\*/g, "\x00DS\x00") // **
+        .replace(/\*/g, "\x00SS\x00") // *
+        .replace(/\?/g, "\x00QM\x00"); // ?
+    // 3. Escape regex specials (parens / pipe stay literal — they came from brace expansion).
+    p = p.replace(/[.+^$\\[\]]/g, "\\$&");
+    // 4. Restore globs as regex equivalents.
+    p = p.replace(/\x00DSS\x00/g, "(?:.*/)?")
+        .replace(/\x00DS\x00/g, ".*")
+        .replace(/\x00SS\x00/g, "[^/]*")
+        .replace(/\x00QM\x00/g, "[^/]");
+    return new RegExp(`(^|/)${p}$`);
 }
-/**
- * Tests if a file path matches any of the given glob patterns.
- */
 function matchesAny(filePath, patterns) {
     for (const pattern of patterns) {
-        const regex = globToRegExp(pattern);
-        if (regex.test(filePath)) {
+        if (globToRegExp(pattern).test(filePath)) {
             return true;
         }
     }
     return false;
 }
+/** Returns the effective pattern set for the browser cycle. */
+function getBrowserPatterns(config) {
+    const block = config.browser;
+    const base = block?.verifyPatterns ?? exports.DEFAULT_BROWSER_VERIFY_PATTERNS;
+    const additional = block?.additionalVerifyPatterns ?? [];
+    return [...base, ...additional];
+}
+/** Returns the effective pattern set for `backend.<runtime>`. Empty by default. */
+function getBackendRuntimePatterns(config, runtime) {
+    const block = config.backend?.[runtime];
+    const base = block?.verifyPatterns ?? [];
+    const additional = block?.additionalVerifyPatterns ?? [];
+    return [...base, ...additional];
+}
 /**
- * Determines whether a file requires browser verification.
+ * Returns the names of cycles whose pattern set matches `filePath`.
+ * Used by verify-gate to determine which cycles are active for a Stop hook.
  *
- * Check order:
- *   1. ignoredVerifyPatterns → if matched, skip (return false)
- *   2. verifyPatterns (+ additionalVerifyPatterns) → if matched, verify (return true)
- *   3. No match → skip (return false)
+ * Order: browser first, then each registered backend runtime. `ignoredVerifyPatterns`
+ * applies globally — a file matched there activates no cycles.
  */
-function requiresVerification(filePath, config) {
-    // 1. check ignored patterns first
+function getActiveCycles(filePath, config) {
     const ignored = config.ignoredVerifyPatterns ?? [];
     if (ignored.length > 0 && matchesAny(filePath, ignored)) {
-        return false;
+        return [];
+    }
+    const active = [];
+    if (matchesAny(filePath, getBrowserPatterns(config))) {
+        active.push("browser");
     }
-    // 2. build verify patterns: base + additional
-    const base = config.verifyPatterns ?? DEFAULT_VERIFY_PATTERNS;
-    const additional = config.additionalVerifyPatterns ?? [];
-    const patterns = [...base, ...additional];
-    return matchesAny(filePath, patterns);
+    for (const server of exports.BACKEND_SERVERS) {
+        const runtime = Object.keys(exports.RUNTIME_TO_SERVER).find((k) => exports.RUNTIME_TO_SERVER[k] === server);
+        if (runtime === undefined) {
+            continue;
+        }
+        const patterns = getBackendRuntimePatterns(config, runtime);
+        if (patterns.length > 0 && matchesAny(filePath, patterns)) {
+            active.push(runtime);
+        }
+    }
+    return active;
 }
-const IRONBEE_ENV = {
+/**
+ * Returns true if a file is under verification by *any* cycle. Used by
+ * `clear-verdict` and `require-verdict` hooks where the question is just
+ * "should this edit be tracked / gated?", regardless of which cycle.
+ */
+function requiresVerification(filePath, config) {
+    return getActiveCycles(filePath, config).length > 0;
+}
+/**
+ * Per-cycle resolved required-tools spec. Falls back to defaults at this layer
+ * so consumers always get a complete `{ alwaysRequired, evidencePaths }` shape.
+ *
+ * Validity rule: at least one of `alwaysRequired` or `evidencePaths` must be
+ * non-empty. Both empty → config error (caught here, surfaced to caller).
+ */
+function getRequiredToolsConfig(config, cycle) {
+    let alwaysRequired;
+    let evidencePaths;
+    if (cycle === "browser") {
+        alwaysRequired = config.browser?.alwaysRequired ?? exports.DEFAULT_BROWSER_ALWAYS_REQUIRED;
+        evidencePaths = config.browser?.evidencePaths ?? [];
+    }
+    else if (cycle === "node") {
+        alwaysRequired = config.backend?.node?.alwaysRequired ?? exports.DEFAULT_BACKEND_NODE_ALWAYS_REQUIRED;
+        evidencePaths = config.backend?.node?.evidencePaths ?? exports.DEFAULT_BACKEND_NODE_EVIDENCE_PATHS;
+    }
+    else {
+        const block = config.backend?.[cycle];
+        alwaysRequired = block?.alwaysRequired ?? [];
+        evidencePaths = block?.evidencePaths ?? [];
+    }
+    if (alwaysRequired.length === 0 && evidencePaths.length === 0) {
+        throw new Error(`Invalid required-tools config for cycle '${cycle}': both 'alwaysRequired' and 'evidencePaths' are empty. ` +
+            `At least one must specify required tools.`);
+    }
+    return { alwaysRequired, evidencePaths };
+}
+const DEFAULT_MCP_COMMAND = "npx";
+const DEFAULT_MCP_ARGS = ["-y", "browser-devtools-mcp"];
+const BROWSER_IRONBEE_ENV = {
     TOOL_NAME_PREFIX: "bdt_",
     TOOL_INPUT_METADATA_ENABLE: "true",
 };
-const DEFAULT_MCP_ENV = {
+const NODE_IRONBEE_ENV = {
+    PLATFORM: "node",
+    TOOL_NAME_PREFIX: "ndt_",
+    TOOL_INPUT_METADATA_ENABLE: "true",
+};
+const BROWSER_DEFAULT_MCP_ENV = {
     BROWSER_DEVTOOLS_INSTALL_CHROMIUM: "true",
 };
-const DEFAULT_MCP_COMMAND = "npx";
-const DEFAULT_MCP_ARGS = ["-y", "browser-devtools-mcp"];
+const NODE_DEFAULT_MCP_ENV = {};
 /**
- * Returns the MCP server config for browser-devtools.
+ * Auto-derive OTEL exporter env for the devtools MCP server when the
+ * IronBee Collector is configured + enabled. Returns `{}` when the
+ * collector is absent / disabled / missing a URL — in that case the MCP
+ * server runs without telemetry, same as before.
  *
- * Config is read from `browserDevTools` key in IronBee config:
- *   - `browserDevTools.mcp` — full MCP config (used as-is if provided)
- *   - `browserDevTools.env` — env vars for the MCP server (used only when mcp is not provided)
+ * Precedence in the final env block (lowest → highest):
+ *   default static env  <  auto-injected OTEL env  <  user override env  <  ironbee env
  *
- * Priority:
- *   1. If `browserDevTools.mcp` exists → use as-is (env from mcp config, not from browserDevTools.env)
- *   2. Otherwise → build default config (npx -y browser-devtools-mcp) with browserDevTools.env merged
+ * So operators can still override individual keys via `browserDevTools.env`
+ * (e.g. point OTEL at a separate observability endpoint), or fully opt out
+ * by setting `OTEL_ENABLE: "false"` in their override.
  *
- * IronBee's own env vars (TOOL_NAME_PREFIX, TOOL_INPUT_METADATA_ENABLE) are always applied last,
- * overriding any user-provided values.
+ * `runtime` toggles browser-only vars (USER_INTERACTION_EVENTS,
+ * BROWSER_HEADLESS_ENABLE) — node-devtools doesn't honor those.
  */
-function getMcpServerEntry(projectDir) {
-    const config = loadConfig(projectDir);
-    const browserDevTools = config.browserDevTools;
-    if (browserDevTools && typeof browserDevTools === "object" && !Array.isArray(browserDevTools)) {
-        const bdtConfig = browserDevTools;
-        // if mcp is explicitly provided, use as-is + ironbee env overrides
-        if (bdtConfig.mcp && typeof bdtConfig.mcp === "object" && !Array.isArray(bdtConfig.mcp)) {
-            const mcp = { ...bdtConfig.mcp };
-            const mcpEnv = { ...(mcp.env ?? {}), ...IRONBEE_ENV };
+function buildOtelEnv(config, runtime) {
+    if (!isCollectorConfigured(config)) {
+        return {};
+    }
+    // Cast: `isCollectorConfigured` already guaranteed url + apiKey are
+    // non-empty strings.
+    const section = config.collector;
+    const env = {
+        OTEL_ENABLE: "true",
+        OTEL_EXPORTER_HTTP_URL: section.url,
+        OTEL_EXPORTER_HTTP_HEADERS: `X-API-Key=${section.apiKey}`,
+        OTEL_EXPORTER_TYPE: "otlp/http-protobuf",
+    };
+    if (runtime === "browser") {
+        env.OTEL_INSTRUMENTATION_USER_INTERACTION_EVENTS = "change,input,click";
+        env.BROWSER_HEADLESS_ENABLE = "true";
+    }
+    return env;
+}
+/**
+ * Builds an MCP server entry for the given runtime ("browser" or "node").
+ *
+ * Reads override config from `config.<runtime>DevTools`:
+ *   - `<...>.mcp` — full MCP config (used as-is + ironbee env always wins)
+ *   - `<...>.env` — env vars merged into the default (npx -y) config
+ *
+ * Env precedence (lowest → highest):
+ *   1. Static `defaultEnv` (e.g. `BROWSER_DEVTOOLS_INSTALL_CHROMIUM`)
+ *   2. Auto-injected OTEL exporter env (when `collector` is configured + enabled)
+ *   3. User override env from `<runtime>DevTools.env`
+ *   4. IronBee invariant env (`TOOL_NAME_PREFIX`, `TOOL_INPUT_METADATA_ENABLE`, `PLATFORM`)
+ *
+ * Operators can override individual OTEL vars or opt out entirely
+ * (`<runtime>DevTools.env.OTEL_ENABLE: "false"`). IronBee env always wins
+ * so the wire contract (tool-name prefix, metadata-injection toggle) cannot
+ * be broken from outside.
+ */
+function buildMcpEntry(config, overrideKey, ironbeeEnv, defaultEnv, runtime) {
+    const otelEnv = buildOtelEnv(config, runtime);
+    const override = config[overrideKey];
+    if (override && typeof override === "object" && !Array.isArray(override)) {
+        const block = override;
+        if (block.mcp && typeof block.mcp === "object" && !Array.isArray(block.mcp)) {
+            // Full-replacement MCP override. We still inject OTEL into the
+            // env (auto-derived from collector config) and let ironbee env
+            // win last. Operator's own `mcp.env` keys take precedence over
+            // OTEL but lose to ironbee env.
+            const mcp = { ...block.mcp };
+            const mcpEnv = {
+                ...otelEnv,
+                ...(mcp.env ?? {}),
+                ...ironbeeEnv,
+            };
             mcp.env = mcpEnv;
             return mcp;
         }
-        // no mcp provided — build default with browserDevTools.env merged
         const userEnv = {};
-        if (bdtConfig.env && typeof bdtConfig.env === "object" && !Array.isArray(bdtConfig.env)) {
-            const envObj = bdtConfig.env;
+        if (block.env && typeof block.env === "object" && !Array.isArray(block.env)) {
+            const envObj = block.env;
             for (const key of Object.keys(envObj)) {
                 if (typeof envObj[key] === "string") {
                     userEnv[key] = envObj[key];
@@ -178,57 +399,229 @@ function getMcpServerEntry(projectDir) {
         return {
             command: DEFAULT_MCP_COMMAND,
             args: [...DEFAULT_MCP_ARGS],
-            env: { ...DEFAULT_MCP_ENV, ...userEnv, ...IRONBEE_ENV },
+            env: { ...defaultEnv, ...otelEnv, ...userEnv, ...ironbeeEnv },
         };
     }
-    // no browserDevTools config — full defaults
     return {
         command: DEFAULT_MCP_COMMAND,
         args: [...DEFAULT_MCP_ARGS],
-        env: { ...DEFAULT_MCP_ENV, ...IRONBEE_ENV },
+        env: { ...defaultEnv, ...otelEnv, ...ironbeeEnv },
     };
 }
+/** Returns the MCP server entry for `browser-devtools` (PLATFORM=browser, bdt_). */
+function getMcpServerEntry(projectDir) {
+    const config = loadConfig(projectDir);
+    return buildMcpEntry(config, "browserDevTools", BROWSER_IRONBEE_ENV, BROWSER_DEFAULT_MCP_ENV, "browser");
+}
+/** Returns the MCP server entry for `node-devtools` (PLATFORM=node, ndt_). */
+function getNodeDevToolsMcpEntry(projectDir) {
+    const config = loadConfig(projectDir);
+    return buildMcpEntry(config, "nodeDevTools", NODE_IRONBEE_ENV, NODE_DEFAULT_MCP_ENV, "node");
+}
 function getMaxRetries(config) {
     return (typeof config.maxRetries === "number" && config.maxRetries > 0)
         ? config.maxRetries
         : DEFAULT_MAX_RETRIES;
 }
 /**
- * Returns true when the job queue layer is enabled for this project.
+ * Returns true when the IronBee Collector is configured + active for this
+ * config — i.e. the collector section is present, `enable !== false`, the
+ * `url` is non-empty, and the `IRONBEE_COLLECTOR=false` env override isn't
+ * set. Pure check over an already-loaded `IronBeeConfig` so callers that
+ * have a config in hand don't pay an extra `loadConfig` round-trip.
  *
- * Rule:
- *   - No `jobQueue` section in config → disabled (default-off).
- *   - `jobQueue` section present → enabled, unless `enable: false` is set
- *     explicitly. Adding any sub-key (e.g. `autoFlushSizeBytes`) implicitly
- *     opts in.
+ * Used by the auto-enable behavior in `isJobQueueEnabled` /
+ * `isRecordingEnabled` / `isAnalyticsEnabled`: when the operator has
+ * configured a collector, we treat all three feature switches as
+ * implicitly opted in. Rationale: setting up a collector is a strong
+ * signal that the operator wants events to flow there, and these three
+ * sections are exactly what makes events flow (queue dispatch, recording
+ * enforcement, analytics derivation). Explicit `enable: false` on any of
+ * them still wins — the auto-enable only fires for "section absent".
+ */
+function isCollectorConfigured(config) {
+    if (process.env.IRONBEE_COLLECTOR === "false") {
+        return false;
+    }
+    const section = config.collector;
+    if (!section) {
+        return false;
+    }
+    if (section.enable === false) {
+        return false;
+    }
+    if (typeof section.url !== "string" || section.url.length === 0) {
+        return false;
+    }
+    // apiKey is required — a collector running without auth is a developer
+    // convenience that ironbee no longer supports as the "configured" state.
+    // Production deployments always have an api key; for local testing,
+    // operators can either set a placeholder key or use IRONBEE_COLLECTOR=false
+    // to fully disable.
+    if (typeof section.apiKey !== "string" || section.apiKey.length === 0) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Returns true when the job queue layer is enabled for this project.
  *
- * Used as both a producer-side gate (track-action skips wire construction
- * when off) and a defense-in-depth guard inside `submit()` itself.
+ * Resolution:
+ *   1. Section explicitly disabled (`enable: false`) → `false`.
+ *   2. Section present (any other shape) → `true` (presence-as-opt-in).
+ *   3. Collector configured + valid → `true` (auto-enable: a collector is
+ *      pointless without a queue feeding it tool_call events).
+ *   4. Otherwise → `false`.
  */
 function isJobQueueEnabled(projectDir) {
     const config = loadConfig(projectDir);
-    return isPresenceEnabled(config.jobQueue);
+    return isFeatureEnabledWithCollectorAutoEnable(config, config.jobQueue);
 }
 /**
  * Returns true when recording enforcement is enabled for this project.
- * Same presence-as-opt-in semantics as `isJobQueueEnabled`: the `recording`
- * section being present in config.json turns enforcement on; set
- * `enable: false` explicitly to suspend without removing the section.
+ * Same resolution as `isJobQueueEnabled` (presence-as-opt-in + collector
+ * auto-enable + explicit-disable wins).
  */
 function isRecordingEnabled(projectDir) {
     const config = loadConfig(projectDir);
-    return isPresenceEnabled(config.recording);
+    return isFeatureEnabledWithCollectorAutoEnable(config, config.recording);
 }
 /**
- * Shared "section present + not explicitly disabled" check used by the
- * three master-switch helpers (`jobQueue`, `recording`, and inline by
- * `getCollectorTarget`). Defensive against malformed config values
- * (null / non-object / array) — those are treated as disabled.
+ * Shared resolution for sections that follow the "presence-as-opt-in +
+ * auto-enable when collector is configured" pattern. `jobQueue`, `recording`,
+ * `analytics` all use this. `collector` itself uses `isCollectorConfigured`
+ * directly (it's the one that drives the auto-enable, not subject to it).
  */
+function isFeatureEnabledWithCollectorAutoEnable(config, section) {
+    // Explicit opt-out always wins, regardless of collector config.
+    if (section !== undefined && section !== null && typeof section === "object" && !Array.isArray(section)) {
+        if (section.enable === false) {
+            return false;
+        }
+        // Presence (with non-false `enable`) opts in.
+        return true;
+    }
+    // Section absent → fall back to collector-driven auto-enable.
+    return isCollectorConfigured(config);
+}
 function isPresenceEnabled(section) {
     if (section === undefined || section === null || typeof section !== "object" || Array.isArray(section)) {
         return false;
     }
     return section.enable !== false;
 }
+/**
+ * Returns true when verification enforcement is enabled for this config.
+ *
+ * **Inverse semantics from `isJobQueueEnabled` / `isRecordingEnabled`**:
+ * verification is the core feature, opt-out by `enable: false`. Section absent,
+ * empty section, or `enable: true` all return true. Only `enable: false`
+ * returns false.
+ */
+function getVerificationEnabled(config) {
+    const section = config.verification;
+    if (section === undefined || section === null) {
+        return true;
+    }
+    if (typeof section !== "object" || Array.isArray(section)) {
+        return true;
+    }
+    return section.enable !== false;
+}
+/**
+ * Returns true when analytics collection is enabled for this project.
+ * Same resolution as `isJobQueueEnabled` / `isRecordingEnabled`:
+ * explicit-disable wins, presence opts in, and collector configured +
+ * section absent auto-enables.
+ */
+function isAnalyticsEnabled(projectDir) {
+    const config = loadConfig(projectDir);
+    return isFeatureEnabledWithCollectorAutoEnable(config, config.analytics);
+}
+/** Whether the Stop hook should project + emit analytics. Default `true` when analytics is enabled. */
+function isAnalyticsEmitOnStopEnabled(projectDir) {
+    const config = loadConfig(projectDir);
+    const section = config.analytics;
+    if (section === null || typeof section !== "object" || Array.isArray(section)) {
+        return true;
+    }
+    const v = section.emitOnStop;
+    return v !== false;
+}
+/**
+ * Throttle interval (seconds) for Stop-hook projection. Default 0 (disabled).
+ *
+ * The CLI used to default to 30s here as a "don't hammer the backend on
+ * hot Stop loops" guard. That was a CLI-side judgment about cadence — backends
+ * can rate-limit / dedupe / aggregate however they want, and a 30s default
+ * silently dropped per-Stop visibility (especially painful for verify-gate
+ * retry loops where each Stop carries fresh signal). Default is now 0;
+ * operators who DO want CLI-side throttling can set the config explicitly.
+ * `throttleState` in `hook-trigger.ts` returns null when interval ≤ 0, so
+ * 0 = no-op fast path.
+ */
+function getAnalyticsEmitOnStopMinIntervalSeconds(projectDir) {
+    const config = loadConfig(projectDir);
+    const section = config.analytics;
+    if (section === null || typeof section !== "object" || Array.isArray(section)) {
+        return 0;
+    }
+    const v = section.emitOnStopMinIntervalSeconds;
+    return typeof v === "number" && v >= 0 ? v : 0;
+}
+/**
+ * Returns true when the per-turn `session_turn_analytics` wire records should
+ * be emitted alongside `session_analytics`. **Default `false` (opt-in)** —
+ * inverse of the `analytics` master switch's presence-as-opt-in.
+ *
+ * Rationale: turn-grain records are high-volume secondary signal; backends
+ * that only want session aggregates shouldn't pay for them by default. The
+ * base `session_analytics` record always ships when analytics is enabled.
+ */
+function isAnalyticsTurnEventsEnabled(projectDir) {
+    const config = loadConfig(projectDir);
+    const section = config.analytics;
+    if (section === null || typeof section !== "object" || Array.isArray(section)) {
+        return false;
+    }
+    return section.emitTurnEvents === true;
+}
+/**
+ * Returns true when the per-step `session_turn_step_analytics` wire records
+ * should be emitted. **Default `false` (opt-in)** — same rationale as
+ * {@link isAnalyticsTurnEventsEnabled}, with one extra dimension: step-grain
+ * records are an order of magnitude higher volume than turn-grain.
+ *
+ * Independent of `emitTurnEvents`. Backend can reconstruct turn from steps,
+ * so step-only / turn-only / both / neither are all valid combinations.
+ */
+function isAnalyticsStepEventsEnabled(projectDir) {
+    const config = loadConfig(projectDir);
+    const section = config.analytics;
+    if (section === null || typeof section !== "object" || Array.isArray(section)) {
+        return false;
+    }
+    return section.emitStepEvents === true;
+}
+/**
+ * Returns true when the per-API-request `api_request` wire records should be
+ * emitted. **Default `true` (opt-out)** — INVERSE of the turn / step event
+ * gating, mirroring the `verification.enable` opt-out semantics. Per-request
+ * audit (cost attribution, failure tracking, request-id timeline) is the
+ * primary value of the analytics pipeline for backend cost accounting, so
+ * it ships by default. Operators can opt out via `emitApiRequestEvents: false`
+ * if backend doesn't consume them.
+ *
+ * Independent of `emitTurnEvents` / `emitStepEvents`. The `analytics` master
+ * switch (section presence) still gates everything below it — without
+ * `analytics` in config, no api_request events ship regardless of this flag.
+ */
+function isAnalyticsApiRequestEventsEnabled(projectDir) {
+    const config = loadConfig(projectDir);
+    const section = config.analytics;
+    if (section === null || typeof section !== "object" || Array.isArray(section)) {
+        return false;
+    }
+    return section.emitApiRequestEvents !== false;
+}
 //# sourceMappingURL=config.js.map