@ironbee-ai/cli 0.8.2 → 0.9.0

package/dist/lib/config.js

@@ -2,31 +2,38 @@
 /**
  * IronBee — Configuration Loader
  *
- * Loads config from two sources and merges them:
- *   1. Global:  ~/.ironbee/config.json
- *   2. Project: <projectDir>/.ironbee/config.json
+ * Loads config from up to three sources and merges them in order:
+ *   1. Global:        ~/.ironbee/config.json
+ *   2. Project:       <projectDir>/.ironbee/config.json          (committed)
+ *   3. Project-local: <projectDir>/.ironbee/config.local.json    (gitignored)
  *
- * 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>.*`).
+ * Each later layer overrides earlier ones (deep merge for nested cycle
+ * blocks: `browser`, `node`, `backend`; shallow for primitives and other
+ * top-level keys). The local layer is intended for personal / per-machine
+ * overrides (debug toggles, machine-specific paths, alternate collector
+ * endpoints) and must not be committed — `ironbee install` adds
+ * `.ironbee/config.local.json` to `.gitignore` automatically.
  */
 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.CONFIG_TARGETS_BY_PRECEDENCE = exports.DEFAULT_BACKEND_EVIDENCE_PATHS = exports.DEFAULT_BACKEND_ALWAYS_REQUIRED = exports.DEFAULT_NODE_EVIDENCE_PATHS = exports.DEFAULT_NODE_ALWAYS_REQUIRED = exports.DEFAULT_BROWSER_ALWAYS_REQUIRED = exports.CYCLE_DEFAULT_VERIFY_PATTERNS = exports.DEFAULT_BACKEND_VERIFY_PATTERNS = exports.DEFAULT_NODE_VERIFY_PATTERNS = exports.DEFAULT_BROWSER_VERIFY_PATTERNS = exports.CYCLE_TO_SERVER = exports.CYCLES_ENABLED_BY_DEFAULT = exports.ALL_CYCLES = exports.OPTIONAL_CYCLES = void 0;
+exports.getConfigLayerPaths = getConfigLayerPaths;
+exports.getTargetConfigPath = getTargetConfigPath;
+exports.resolveConfigTargetFromFlags = resolveConfigTargetFromFlags;
 exports.loadConfig = loadConfig;
 exports.getActiveCycles = getActiveCycles;
 exports.requiresVerification = requiresVerification;
+exports.isCycleEnabled = isCycleEnabled;
 exports.getRequiredToolsConfig = getRequiredToolsConfig;
 exports.getMcpServerEntry = getMcpServerEntry;
 exports.getNodeDevToolsMcpEntry = getNodeDevToolsMcpEntry;
+exports.getBackendDevToolsMcpEntry = getBackendDevToolsMcpEntry;
 exports.getMaxRetries = getMaxRetries;
 exports.isCollectorConfigured = isCollectorConfigured;
 exports.isJobQueueEnabled = isJobQueueEnabled;
 exports.isRecordingEnabled = isRecordingEnabled;
 exports.getVerificationEnabled = getVerificationEnabled;
+exports.getCaptureFileChangeset = getCaptureFileChangeset;
+exports.getMaxChangesetBytes = getMaxChangesetBytes;
 exports.isAnalyticsEnabled = isAnalyticsEnabled;
 exports.isAnalyticsEmitOnStopEnabled = isAnalyticsEmitOnStopEnabled;
 exports.getAnalyticsEmitOnStopMinIntervalSeconds = getAnalyticsEmitOnStopMinIntervalSeconds;
@@ -37,13 +44,44 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
 const logger_1 = require("./logger");
-/** 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 = {
+/**
+ * Optional cycles — those that default to **disabled** (empty `verifyPatterns`)
+ * until the operator explicitly opts in via `ironbee <cycle> enable`. The
+ * always-on browser cycle is the only default-enabled cycle and is excluded
+ * from this list. Order is the canonical sort order used by verify-gate when
+ * building per-cycle messages.
+ */
+exports.OPTIONAL_CYCLES = ["node", "backend"];
+/**
+ * Every cycle the runtime knows about — browser plus all optional cycles.
+ * Used by the platform-section sync (skill / rule / command-verify md files
+ * carry one marker block per cycle) and by toggle commands when validating
+ * the cycle name. Order matches verify-gate's canonical block ordering
+ * (browser first, then OPTIONAL_CYCLES).
+ */
+exports.ALL_CYCLES = ["browser", ...exports.OPTIONAL_CYCLES];
+/**
+ * Cycles whose default state is "enabled" (the cycle activates without the
+ * operator having to write `verifyPatterns` in config). Currently only the
+ * browser cycle ships with built-in default patterns; node and backend cycles
+ * default to inert (`[]`) and require `ironbee <cycle> enable`.
+ *
+ * Used by `getCyclePatterns` runtime fallback (block-absent + default-on
+ * → code defaults activate) and by toggle commands. `<cycle> disable` records
+ * its intent via the top-level `disabled` list — that takes precedence over
+ * the default-on fallback, so a disabled browser stays off even though
+ * `CYCLES_ENABLED_BY_DEFAULT` contains it.
+ */
+exports.CYCLES_ENABLED_BY_DEFAULT = new Set(["browser"]);
+/** Map cycle key → MCP server name. Browser is always `browser-devtools`. */
+exports.CYCLE_TO_SERVER = {
+    browser: "browser-devtools",
     node: "node-devtools",
+    backend: "backend-devtools",
 };
-/** Browser default verify patterns — preserves the pre-split list as-is. */
+/** Browser default verify patterns — kicks in whenever the browser block is
+ *  present without an explicit `verifyPatterns`, OR (since browser is
+ *  default-on) whenever no browser block is present at any layer. */
 exports.DEFAULT_BROWSER_VERIFY_PATTERNS = [
     "*.ts", "*.tsx",
     "*.js", "*.jsx", "*.mjs", "*.cjs",
@@ -71,6 +109,65 @@ exports.DEFAULT_BROWSER_VERIFY_PATTERNS = [
     "*.hbs", "*.ejs", "*.pug", "*.jade",
     "*.astro",
 ];
+/**
+ * Node-cycle default verify patterns — kicks in when the `node` block is
+ * present without an explicit `verifyPatterns`. The node cycle is opt-in so
+ * the block must be present (a fully-absent block keeps the cycle disabled).
+ *
+ * Heuristic-tuned for typical Node.js backends — server entry points, API
+ * route handlers (Next.js / Remix / SvelteKit conventions), and the routes/
+ * folder.
+ */
+exports.DEFAULT_NODE_VERIFY_PATTERNS = [
+    "server/**/*.{ts,js,mjs,cjs}",
+    "src/server/**/*.{ts,js,mjs,cjs}",
+    "backend/**/*.{ts,js,mjs,cjs}",
+    "api/**/*.{ts,js,mjs,cjs}",
+    "src/api/**/*.{ts,js,mjs,cjs}",
+    "pages/api/**/*.{ts,js,mjs,cjs}",
+    "app/api/**/*.{ts,js,mjs,cjs}",
+    "routes/**/*.{ts,js,mjs,cjs}",
+    "**/server.{ts,js,mjs,cjs}",
+];
+/**
+ * Backend-cycle default verify patterns — kicks in when the `backend` block
+ * is present without an explicit `verifyPatterns`. Multi-language coverage —
+ * the cycle drives wire protocols, not language-specific tooling, so the
+ * heuristic spans every common server-side language.
+ */
+exports.DEFAULT_BACKEND_VERIFY_PATTERNS = [
+    "server/**/*.{ts,js,mjs,cjs,py,go,java,rb,cs,rs,kt,scala,ex,exs,php,clj}",
+    "src/server/**/*.{ts,js,mjs,cjs,py,go,java,rb,cs,rs,kt,scala,ex,exs,php,clj}",
+    "backend/**/*.{ts,js,mjs,cjs,py,go,java,rb,cs,rs,kt,scala,ex,exs,php,clj}",
+    "api/**/*.{ts,js,mjs,cjs,py,go,java,rb,cs,rs,kt,scala,ex,exs,php,clj}",
+    "src/api/**/*.{ts,js,mjs,cjs,py,go,java,rb,cs,rs,kt,scala,ex,exs,php,clj}",
+    "pages/api/**/*.{ts,js,mjs,cjs}",
+    "app/api/**/*.{ts,js,mjs,cjs}",
+    "routes/**/*.{ts,js,mjs,cjs,py,go,java,rb,cs,rs,kt,scala,ex,exs,php,clj}",
+    "controllers/**/*.{ts,js,mjs,cjs,py,go,java,rb,cs,rs,kt,scala,ex,exs,php,clj}",
+    "handlers/**/*.{ts,js,mjs,cjs,py,go,java,rb,cs,rs,kt,scala,ex,exs,php,clj}",
+    "services/**/*.{ts,js,mjs,cjs,py,go,java,rb,cs,rs,kt,scala,ex,exs,php,clj}",
+    "**/server.{ts,js,mjs,cjs,py,go,java,rb,cs,rs,kt,scala,ex,exs,php,clj}",
+    "**/main.{go,py,java,rb,kt,scala}",
+];
+/**
+ * Per-cycle default `verifyPatterns` lookup. Single source of truth used by:
+ *
+ *   - `getCyclePatterns` runtime fallback when the cycle block is present
+ *     without an explicit `verifyPatterns`.
+ *   - For browser only: also kicks in when the cycle block is fully absent
+ *     (browser is the default-on cycle — `CYCLES_ENABLED_BY_DEFAULT`).
+ *
+ * `<cycle> enable` does NOT materialize these into config.json; the cycle
+ * block is written empty (`{}`) and these defaults flow in at runtime.
+ * Keeps `config.json` minimal and lets defaults track the CLI version
+ * automatically.
+ */
+exports.CYCLE_DEFAULT_VERIFY_PATTERNS = {
+    browser: exports.DEFAULT_BROWSER_VERIFY_PATTERNS,
+    node: exports.DEFAULT_NODE_VERIFY_PATTERNS,
+    backend: exports.DEFAULT_BACKEND_VERIFY_PATTERNS,
+};
 /** Browser-cycle required tools — strict all-of, no alternative paths. */
 exports.DEFAULT_BROWSER_ALWAYS_REQUIRED = [
     "bdt_navigation_go-to",
@@ -79,10 +176,10 @@ exports.DEFAULT_BROWSER_ALWAYS_REQUIRED = [
     "bdt_o11y_get-console-messages",
 ];
 /** Node-cycle required tools — connect always; then probe path or log path. */
-exports.DEFAULT_BACKEND_NODE_ALWAYS_REQUIRED = [
+exports.DEFAULT_NODE_ALWAYS_REQUIRED = [
     "ndt_debug_connect",
 ];
-exports.DEFAULT_BACKEND_NODE_EVIDENCE_PATHS = [
+exports.DEFAULT_NODE_EVIDENCE_PATHS = [
     {
         name: "probe",
         allOf: [
@@ -101,6 +198,29 @@ exports.DEFAULT_BACKEND_NODE_EVIDENCE_PATHS = [
         allOf: ["ndt_debug_get-logs"],
     },
 ];
+/**
+ * Backend-cycle required tools — no single tool is mandatory (different
+ * tasks need different protocols), so `alwaysRequired` is empty and the
+ * gate is satisfied by any one protocol-call evidence path. The replay
+ * tool counts because it issues a real protocol call against the target.
+ */
+exports.DEFAULT_BACKEND_ALWAYS_REQUIRED = [];
+exports.DEFAULT_BACKEND_EVIDENCE_PATHS = [
+    {
+        name: "protocol-call",
+        allOf: [
+            {
+                anyOf: [
+                    "bedt_request_http",
+                    "bedt_request_grpc",
+                    "bedt_request_graphql",
+                    "bedt_request_websocket-open",
+                    "bedt_request_replay",
+                ],
+            },
+        ],
+    },
+];
 const DEFAULT_MAX_RETRIES = 3;
 function loadJsonFile(filePath) {
     if (!(0, fs_1.existsSync)(filePath)) {
@@ -114,21 +234,6 @@ 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;
@@ -144,51 +249,96 @@ function assertVerificationShape(config, sourcePath) {
             `Got ${typeof block.enable}.`);
     }
 }
-/** Deep merge for the nested `browser` / `backend.<runtime>` blocks. */
+/** Deep merge for a single cycle block (browser / node / backend). */
 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]);
-    }
+/**
+ * Merge two `IronBeeConfig` layers — `override` wins. Top-level keys are
+ * shallow-merged; the cycle blocks (`browser`, `node`, `backend`) deep-merge
+ * so a project override of `browser.verifyPatterns` doesn't wipe a global
+ * `browser.evidencePaths` (and vice-versa for the local layer).
+ */
+function mergeConfigLayers(base, override) {
+    const merged = { ...base, ...override };
+    merged.browser = mergeCycleConfig(base.browser, override.browser);
+    merged.node = mergeCycleConfig(base.node, override.node);
+    merged.backend = mergeCycleConfig(base.backend, override.backend);
     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) {
-        projectPath = (0, path_1.join)(projectDir, ".ironbee", "config.json");
-        projectConfig = loadJsonFile(projectPath);
-        if ((0, fs_1.existsSync)(projectPath)) {
-            assertNoLegacyShape(projectConfig, projectPath);
-            assertVerificationShape(projectConfig, projectPath);
+/** Returns the on-disk paths of all three config layers without reading them. */
+function getConfigLayerPaths(projectDir) {
+    return {
+        global: (0, path_1.join)((0, os_1.homedir)(), ".ironbee", "config.json"),
+        project: projectDir ? (0, path_1.join)(projectDir, ".ironbee", "config.json") : undefined,
+        local: projectDir ? (0, path_1.join)(projectDir, ".ironbee", "config.local.json") : undefined,
+    };
+}
+/** Layers in merge-precedence order, low → high. Used by override detection. */
+exports.CONFIG_TARGETS_BY_PRECEDENCE = ["global", "project", "local"];
+/**
+ * Returns the on-disk path for a single config layer. Throws when the
+ * caller asks for a project-scoped layer without a `projectDir` (e.g.
+ * `--local` outside a project context). Used by all write-side commands
+ * to keep the targeted-path resolution in one place.
+ */
+function getTargetConfigPath(target, projectDir) {
+    const paths = getConfigLayerPaths(projectDir);
+    if (target === "global") {
+        return paths.global;
+    }
+    if (target === "project") {
+        if (paths.project === undefined) {
+            throw new Error("Project layer requested but no projectDir was provided.");
         }
+        return paths.project;
     }
-    const merged = {
-        ...globalConfig,
-        ...projectConfig,
-    };
-    merged.browser = mergeCycleConfig(globalConfig.browser, projectConfig.browser);
-    merged.backend = mergeBackend(globalConfig.backend, projectConfig.backend);
-    return merged;
+    // local
+    if (paths.local === undefined) {
+        throw new Error("Local layer requested but no projectDir was provided.");
+    }
+    return paths.local;
+}
+/**
+ * Resolves a `ConfigTarget` from CLI flag booleans, enforcing mutual
+ * exclusion. Used by every write-side command that exposes
+ * `-g / --global` and `--local` flags (`config set`, `config unset`,
+ * `enable-verification`, `disable-verification`, `backend enable`,
+ * `backend disable`) so the flag-resolution rules stay identical.
+ *
+ * Returns `"project"` when neither flag is set (the default for
+ * project-scoped commands). Throws on the impossible `--global --local`
+ * combination — commander doesn't enforce mutual exclusion across
+ * arbitrary option pairs, so we do.
+ */
+function resolveConfigTargetFromFlags(opts) {
+    if (opts.global === true && opts.local === true) {
+        throw new Error("Pass at most one of --global / --local.");
+    }
+    if (opts.global === true) {
+        return "global";
+    }
+    if (opts.local === true) {
+        return "local";
+    }
+    return "project";
+}
+function loadAndValidateLayer(path) {
+    const raw = loadJsonFile(path);
+    if ((0, fs_1.existsSync)(path)) {
+        assertVerificationShape(raw, path);
+    }
+    return raw;
+}
+function loadConfig(projectDir) {
+    const paths = getConfigLayerPaths(projectDir);
+    const globalConfig = loadAndValidateLayer(paths.global);
+    const projectConfig = paths.project ? loadAndValidateLayer(paths.project) : {};
+    const localConfig = paths.local ? loadAndValidateLayer(paths.local) : {};
+    return mergeConfigLayers(mergeConfigLayers(globalConfig, projectConfig), localConfig);
 }
 // Glob → RegExp. Supports *, **, ** + slash (zero-or-more segments), ?, and
 // brace expansion {a,b,c} → (a|b|c). The trailing-slash form of ** matches
@@ -226,26 +376,76 @@ function matchesAny(filePath, patterns) {
     }
     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 per-cycle config block. Always-on browser, opt-in node / backend. */
+function getCycleBlock(config, cycle) {
+    if (cycle === "browser") {
+        return config.browser;
+    }
+    if (cycle === "node") {
+        return config.node;
+    }
+    if (cycle === "backend") {
+        return config.backend;
+    }
+    return undefined;
 }
-/** 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 ?? [];
+/**
+ * Returns the effective pattern set for a cycle. Resolution order:
+ *
+ *   1. **`block.enable === false`** → cycle-specific disable signal written
+ *      by `<cycle> disable`. Mirrors `recording.enable` / `jobQueue.enable`
+ *      / `verification.enable`.
+ *   2. **Block absent** → for default-on cycles (browser), the code defaults
+ *      kick in. For default-off cycles (node, backend), no patterns.
+ *   3. **`verifyPatterns: []`** → hard kill (legacy disable marker — still
+ *      respected for older configs; new disables write `enable: false`).
+ *   4. **Block present, `verifyPatterns` undefined** → enabled with code
+ *      defaults (`CYCLE_DEFAULT_VERIFY_PATTERNS[cycle]`). Post-`<cycle> enable`
+ *      shape — minimal config, defaults track CLI version.
+ *   5. **`verifyPatterns: [...non-empty]`** → enabled with custom patterns.
+ *
+ * `additionalVerifyPatterns` is appended to whatever base resolves at step
+ * 4/5 — EXCEPT when the cycle is disabled via step 1 or 3.
+ *
+ * **Note:** does NOT check the master `verification.enable` switch. That
+ * happens at the verification-level (install-time gating + the higher-level
+ * {@link isCycleEnabled} helper). This function returns the cycle's pattern
+ * shape independent of master state — useful for code paths that want
+ * pattern info even when enforcement is off.
+ */
+function getCyclePatterns(config, cycle) {
+    const block = getCycleBlock(config, cycle);
+    // Explicit per-cycle disable signal.
+    if (block !== undefined && block.enable === false) {
+        return [];
+    }
+    const cycleDefaults = exports.CYCLE_DEFAULT_VERIFY_PATTERNS[cycle] ?? [];
+    if (block === undefined) {
+        // Block absent: only default-on cycles activate via code defaults.
+        if (exports.CYCLES_ENABLED_BY_DEFAULT.has(cycle)) {
+            return [...cycleDefaults];
+        }
+        return [];
+    }
+    // Legacy hard kill: `verifyPatterns: []` still fully disables. Newer
+    // configs use `enable: false` (above) but pre-existing configs may
+    // carry this older marker — keep honoring it.
+    if (Array.isArray(block.verifyPatterns) && block.verifyPatterns.length === 0) {
+        return [];
+    }
+    // Block present, enabled: `verifyPatterns` wins when set; otherwise
+    // fall back to code defaults (post-`<cycle> enable` shape).
+    const base = block.verifyPatterns ?? cycleDefaults;
+    const additional = block.additionalVerifyPatterns ?? [];
     return [...base, ...additional];
 }
 /**
  * Returns the names of cycles whose pattern set matches `filePath`.
  * Used by verify-gate to determine which cycles are active for a Stop hook.
  *
- * Order: browser first, then each registered backend runtime. `ignoredVerifyPatterns`
- * applies globally — a file matched there activates no cycles.
+ * Order: browser first, then each optional cycle in {@link OPTIONAL_CYCLES}
+ * order. `ignoredVerifyPatterns` applies globally — a file matched there
+ * activates no cycles.
  */
 function getActiveCycles(filePath, config) {
     const ignored = config.ignoredVerifyPatterns ?? [];
@@ -253,17 +453,13 @@ function getActiveCycles(filePath, config) {
         return [];
     }
     const active = [];
-    if (matchesAny(filePath, getBrowserPatterns(config))) {
+    if (matchesAny(filePath, getCyclePatterns(config, "browser"))) {
         active.push("browser");
     }
-    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);
+    for (const cycle of exports.OPTIONAL_CYCLES) {
+        const patterns = getCyclePatterns(config, cycle);
         if (patterns.length > 0 && matchesAny(filePath, patterns)) {
-            active.push(runtime);
+            active.push(cycle);
         }
     }
     return active;
@@ -276,6 +472,34 @@ function getActiveCycles(filePath, config) {
 function requiresVerification(filePath, config) {
     return getActiveCycles(filePath, config).length > 0;
 }
+/**
+ * Returns true if `cycle` is currently enabled for verification in `config`
+ * (effective merged shape).
+ *
+ * Two conditions must BOTH hold:
+ *   1. The master switch `verification.enable` is on (or absent — defaults
+ *      to true). When `verification.enable: false`, every cycle is off
+ *      regardless of its own block — per-cycle settings never override the
+ *      master switch.
+ *   2. The cycle's own resolution per {@link getCyclePatterns} yields
+ *      non-empty patterns:
+ *      - `block.enable === false` → disabled (canonical signal).
+ *      - Block absent + default-on (browser) → enabled (code defaults).
+ *      - Block absent + default-off (node, backend) → disabled.
+ *      - `verifyPatterns: []` (legacy) → disabled.
+ *      - Block present with `verifyPatterns` undefined → enabled (defaults).
+ *      - Block present with non-empty `verifyPatterns` → enabled (custom).
+ *
+ * Used by `platform-section.syncPlatformSectionsToConfig` to decide whether to
+ * splice the cycle's fragment or the placeholder into installed md files,
+ * and by client `install` paths to gate MCP server entries + permissions.
+ */
+function isCycleEnabled(config, cycle) {
+    if (!getVerificationEnabled(config)) {
+        return false;
+    }
+    return getCyclePatterns(config, cycle).length > 0;
+}
 /**
  * Per-cycle resolved required-tools spec. Falls back to defaults at this layer
  * so consumers always get a complete `{ alwaysRequired, evidencePaths }` shape.
@@ -291,13 +515,16 @@ function getRequiredToolsConfig(config, cycle) {
         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;
+        alwaysRequired = config.node?.alwaysRequired ?? exports.DEFAULT_NODE_ALWAYS_REQUIRED;
+        evidencePaths = config.node?.evidencePaths ?? exports.DEFAULT_NODE_EVIDENCE_PATHS;
+    }
+    else if (cycle === "backend") {
+        alwaysRequired = config.backend?.alwaysRequired ?? exports.DEFAULT_BACKEND_ALWAYS_REQUIRED;
+        evidencePaths = config.backend?.evidencePaths ?? exports.DEFAULT_BACKEND_EVIDENCE_PATHS;
     }
     else {
-        const block = config.backend?.[cycle];
-        alwaysRequired = block?.alwaysRequired ?? [];
-        evidencePaths = block?.evidencePaths ?? [];
+        alwaysRequired = [];
+        evidencePaths = [];
     }
     if (alwaysRequired.length === 0 && evidencePaths.length === 0) {
         throw new Error(`Invalid required-tools config for cycle '${cycle}': both 'alwaysRequired' and 'evidencePaths' are empty. ` +
@@ -316,10 +543,16 @@ const NODE_IRONBEE_ENV = {
     TOOL_NAME_PREFIX: "ndt_",
     TOOL_INPUT_METADATA_ENABLE: "true",
 };
+const BACKEND_IRONBEE_ENV = {
+    PLATFORM: "backend",
+    TOOL_NAME_PREFIX: "bedt_",
+    TOOL_INPUT_METADATA_ENABLE: "true",
+};
 const BROWSER_DEFAULT_MCP_ENV = {
     BROWSER_DEVTOOLS_INSTALL_CHROMIUM: "true",
 };
 const NODE_DEFAULT_MCP_ENV = {};
+const BACKEND_DEFAULT_MCP_ENV = {};
 /**
  * Auto-derive OTEL exporter env for the devtools MCP server when the
  * IronBee Collector is configured + enabled. Returns `{}` when the
@@ -334,7 +567,8 @@ const NODE_DEFAULT_MCP_ENV = {};
  * by setting `OTEL_ENABLE: "false"` in their override.
  *
  * `runtime` toggles browser-only vars (USER_INTERACTION_EVENTS,
- * BROWSER_HEADLESS_ENABLE) — node-devtools doesn't honor those.
+ * BROWSER_HEADLESS_ENABLE) — node-devtools and backend-devtools don't
+ * honor those.
  */
 function buildOtelEnv(config, runtime) {
     if (!isCollectorConfigured(config)) {
@@ -423,6 +657,11 @@ function getNodeDevToolsMcpEntry(projectDir) {
     const config = loadConfig(projectDir);
     return buildMcpEntry(config, "nodeDevTools", NODE_IRONBEE_ENV, NODE_DEFAULT_MCP_ENV, "node");
 }
+/** Returns the MCP server entry for `backend-devtools` (PLATFORM=backend, bedt_). */
+function getBackendDevToolsMcpEntry(projectDir) {
+    const config = loadConfig(projectDir);
+    return buildMcpEntry(config, "backendDevTools", BACKEND_IRONBEE_ENV, BACKEND_DEFAULT_MCP_ENV, "backend");
+}
 function getMaxRetries(config) {
     return (typeof config.maxRetries === "number" && config.maxRetries > 0)
         ? config.maxRetries
@@ -533,6 +772,31 @@ function getVerificationEnabled(config) {
     }
     return section.enable !== false;
 }
+const DEFAULT_MAX_CHANGESET_BYTES = 65536;
+/**
+ * Returns true when `file_change` events should carry a unified-diff
+ * `changeset` string. Off by default — the default wire shape stays
+ * metadata-only (operation + line counts).
+ */
+function getCaptureFileChangeset(config) {
+    const section = config.fileChange;
+    if (!section || typeof section !== "object" || Array.isArray(section)) {
+        return false;
+    }
+    return section.captureChangeset === true;
+}
+/** Per-event hard cap in bytes for the `changeset` string. Truncated past this. */
+function getMaxChangesetBytes(config) {
+    const section = config.fileChange;
+    if (!section || typeof section !== "object" || Array.isArray(section)) {
+        return DEFAULT_MAX_CHANGESET_BYTES;
+    }
+    const raw = section.maxChangesetBytes;
+    if (typeof raw !== "number" || !Number.isFinite(raw) || raw <= 0) {
+        return DEFAULT_MAX_CHANGESET_BYTES;
+    }
+    return Math.floor(raw);
+}
 /**
  * Returns true when analytics collection is enabled for this project.
  * Same resolution as `isJobQueueEnabled` / `isRecordingEnabled`: