@glubean/runner 0.2.2 → 0.2.4

package/dist/bootstrap.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @module bootstrap
+ *
+ * Project-level plugin bootstrap. Any SDK consumer that depends on plugin
+ * registration state (matchers, protocol adapters) must call `bootstrap()`
+ * at the start of its process — before scanning, running tests, handling
+ * MCP requests, or emitting metadata.
+ *
+ * The bootstrap contract is the single point where "which plugins does this
+ * project use" gets resolved. It locates a `glubean.setup.(ts|js|mjs)` file
+ * via walk-up from the given start directory and dynamically imports it.
+ * That file is expected to call `installPlugin(...)` at module top level.
+ *
+ * Idempotent by design — calling `bootstrap()` multiple times (across
+ * entry points, across sub-scans within one process) is safe and cheap.
+ *
+ * **TypeScript setup files**: Loading a `.ts` setup file requires the
+ * calling process to have a TypeScript module resolver active (tsx,
+ * ts-node, etc.). All first-party Glubean entry points (runner, scanner,
+ * CLI, MCP server, VSCode extension) run under tsx already, so this is
+ * transparent. Third-party embeds that cannot load `.ts` should ship a
+ * `glubean.setup.js` or `glubean.setup.mjs` instead.
+ *
+ * @see {@link installPlugin} in `./install-plugin.js`
+ */
+/**
+ * Walk up from `startDir` searching for a Glubean setup file. Returns the
+ * absolute path of the first match found, or `undefined` if no setup file
+ * exists anywhere between `startDir` and the filesystem root (or `stopDir`).
+ *
+ * Setup files checked per directory, in priority order:
+ * `glubean.setup.ts` → `glubean.setup.js` → `glubean.setup.mjs`.
+ *
+ * @param startDir Directory to begin searching from (absolute or relative to cwd).
+ * @param stopDir  Optional upper bound for the walk (defaults to filesystem root).
+ */
+export declare function discoverSetupFile(startDir: string, stopDir?: string): string | undefined;
+/**
+ * Locate and import the project's `glubean.setup` file, triggering the
+ * `installPlugin(...)` calls inside it.
+ *
+ * This function is the **bootstrap contract** for SDK consumers: every
+ * entry point that observes plugin-registered state (scanner for
+ * `.contract.ts` extraction, runner for test execution, MCP server for
+ * metadata, VSCode for scan) **must** await `bootstrap()` before doing
+ * its own work. Failing to do so causes a silent split where scan-time
+ * sees an empty adapter registry while runtime sees the full one.
+ *
+ * **Behavior:**
+ * - No setup file found → no-op (projects without plugins are fine, silent).
+ * - Setup file found and not yet imported this process → import it and
+ *   await the returned promise (the setup file may call `await installPlugin(...)`).
+ * - Setup file found and already imported successfully → no-op (idempotent).
+ * - Setup file found but `import()` throws → the error is recorded **and**
+ *   re-thrown. Every subsequent `bootstrap()` call that resolves to the same
+ *   file re-throws the remembered error rather than silently succeeding.
+ *   This is consistent with `installPlugin`'s "setup failure is
+ *   process-unrecoverable" contract: later scanner / runner / MCP callers
+ *   MUST see the failure, not a false success.
+ *
+ * @param startDir Starting directory for the walk-up search. Typically the
+ *                 project root or the process cwd. Caller decides — the SDK
+ *                 does not assume `process.cwd()`.
+ * @param stopDir  Optional upper bound for the walk (defaults to filesystem root).
+ *
+ * @example
+ * ```ts
+ * // runner startup
+ * import { bootstrap } from "@glubean/sdk";
+ * await bootstrap(projectRoot);
+ * // ... now safe to import test files / .contract.ts files
+ * ```
+ */
+export declare function bootstrap(startDir: string, stopDir?: string): Promise<void>;
+/**
+ * Test-only: clear the "already bootstrapped" cache so a subsequent
+ * `bootstrap()` call will re-import the setup file. Does **not** reset any
+ * plugin state on the globals — combine with
+ * `__resetInstalledPluginsForTesting()` if you need a full reset.
+ *
+ * @internal
+ */
+export declare function __resetBootstrapForTesting(): void;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AA8CH;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,MAAM,GAAG,SAAS,CAiCpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,SAAS,CAC7B,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/bootstrap.js

@@ -0,0 +1,169 @@
+/**
+ * @module bootstrap
+ *
+ * Project-level plugin bootstrap. Any SDK consumer that depends on plugin
+ * registration state (matchers, protocol adapters) must call `bootstrap()`
+ * at the start of its process — before scanning, running tests, handling
+ * MCP requests, or emitting metadata.
+ *
+ * The bootstrap contract is the single point where "which plugins does this
+ * project use" gets resolved. It locates a `glubean.setup.(ts|js|mjs)` file
+ * via walk-up from the given start directory and dynamically imports it.
+ * That file is expected to call `installPlugin(...)` at module top level.
+ *
+ * Idempotent by design — calling `bootstrap()` multiple times (across
+ * entry points, across sub-scans within one process) is safe and cheap.
+ *
+ * **TypeScript setup files**: Loading a `.ts` setup file requires the
+ * calling process to have a TypeScript module resolver active (tsx,
+ * ts-node, etc.). All first-party Glubean entry points (runner, scanner,
+ * CLI, MCP server, VSCode extension) run under tsx already, so this is
+ * transparent. Third-party embeds that cannot load `.ts` should ship a
+ * `glubean.setup.js` or `glubean.setup.mjs` instead.
+ *
+ * @see {@link installPlugin} in `./install-plugin.js`
+ */
+import { dirname, isAbsolute, parse, relative, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+/**
+ * Setup file names checked in priority order during walk-up. A directory
+ * containing any of these files is the project root for plugin purposes.
+ * The first hit in each directory wins.
+ */
+const SETUP_FILE_NAMES = [
+    "glubean.setup.ts",
+    "glubean.setup.js",
+    "glubean.setup.mjs",
+];
+const loadState = new Map();
+/**
+ * Return true iff `descendant` is the same as or nested inside `ancestor`.
+ * Both inputs must be absolute, normalized paths.
+ * @internal
+ */
+function isAncestorOrSame(ancestor, descendant) {
+    const rel = relative(ancestor, descendant);
+    // Empty string → equal. Relative path that is not ".." prefixed and not
+    // absolute → descendant is inside ancestor. Anything else → outside.
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/**
+ * Walk up from `startDir` searching for a Glubean setup file. Returns the
+ * absolute path of the first match found, or `undefined` if no setup file
+ * exists anywhere between `startDir` and the filesystem root (or `stopDir`).
+ *
+ * Setup files checked per directory, in priority order:
+ * `glubean.setup.ts` → `glubean.setup.js` → `glubean.setup.mjs`.
+ *
+ * @param startDir Directory to begin searching from (absolute or relative to cwd).
+ * @param stopDir  Optional upper bound for the walk (defaults to filesystem root).
+ */
+export function discoverSetupFile(startDir, stopDir) {
+    const startAbs = resolve(startDir);
+    let root;
+    if (stopDir !== undefined) {
+        const stopAbs = resolve(stopDir);
+        // Reject a stopDir that is not an ancestor of (or equal to) startDir.
+        // Silently walking past a non-ancestor stopDir could pick up an unrelated
+        // setup file above it — reviewer-flagged bug. Fail loud instead.
+        if (!isAncestorOrSame(stopAbs, startAbs)) {
+            throw new Error(`discoverSetupFile: stopDir "${stopAbs}" is not an ancestor of startDir "${startAbs}". ` +
+                "stopDir must be equal to or above startDir in the directory tree.");
+        }
+        root = stopAbs;
+    }
+    else {
+        root = parse(startAbs).root;
+    }
+    let dir = startAbs;
+    while (true) {
+        for (const name of SETUP_FILE_NAMES) {
+            const candidate = resolve(dir, name);
+            if (existsSync(candidate)) {
+                return candidate;
+            }
+        }
+        if (dir === root)
+            break;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return undefined;
+}
+/**
+ * Locate and import the project's `glubean.setup` file, triggering the
+ * `installPlugin(...)` calls inside it.
+ *
+ * This function is the **bootstrap contract** for SDK consumers: every
+ * entry point that observes plugin-registered state (scanner for
+ * `.contract.ts` extraction, runner for test execution, MCP server for
+ * metadata, VSCode for scan) **must** await `bootstrap()` before doing
+ * its own work. Failing to do so causes a silent split where scan-time
+ * sees an empty adapter registry while runtime sees the full one.
+ *
+ * **Behavior:**
+ * - No setup file found → no-op (projects without plugins are fine, silent).
+ * - Setup file found and not yet imported this process → import it and
+ *   await the returned promise (the setup file may call `await installPlugin(...)`).
+ * - Setup file found and already imported successfully → no-op (idempotent).
+ * - Setup file found but `import()` throws → the error is recorded **and**
+ *   re-thrown. Every subsequent `bootstrap()` call that resolves to the same
+ *   file re-throws the remembered error rather than silently succeeding.
+ *   This is consistent with `installPlugin`'s "setup failure is
+ *   process-unrecoverable" contract: later scanner / runner / MCP callers
+ *   MUST see the failure, not a false success.
+ *
+ * @param startDir Starting directory for the walk-up search. Typically the
+ *                 project root or the process cwd. Caller decides — the SDK
+ *                 does not assume `process.cwd()`.
+ * @param stopDir  Optional upper bound for the walk (defaults to filesystem root).
+ *
+ * @example
+ * ```ts
+ * // runner startup
+ * import { bootstrap } from "@glubean/sdk";
+ * await bootstrap(projectRoot);
+ * // ... now safe to import test files / .contract.ts files
+ * ```
+ */
+export async function bootstrap(startDir, stopDir) {
+    const setupFile = discoverSetupFile(startDir, stopDir);
+    if (!setupFile)
+        return;
+    const state = loadState.get(setupFile);
+    if (state?.status === "ok") {
+        // Fast path: already loaded successfully.
+        return;
+    }
+    if (state?.status === "failed") {
+        // Previous attempt threw. Re-throw the remembered error so downstream
+        // callers (scanner / runner / MCP) don't silently proceed with a
+        // half-initialized plugin registry.
+        throw state.error;
+    }
+    const url = pathToFileURL(setupFile).href;
+    try {
+        await import(url);
+        loadState.set(setupFile, { status: "ok" });
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        loadState.set(setupFile, { status: "failed", error });
+        throw error;
+    }
+}
+/**
+ * Test-only: clear the "already bootstrapped" cache so a subsequent
+ * `bootstrap()` call will re-import the setup file. Does **not** reset any
+ * plugin state on the globals — combine with
+ * `__resetInstalledPluginsForTesting()` if you need a full reset.
+ *
+ * @internal
+ */
+export function __resetBootstrapForTesting() {
+    loadState.clear();
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../src/bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/env.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @module env
+ *
+ * Canonical project-env loader for all Glubean entry points (CLI `run`,
+ * MCP tool handlers, VSCode extension, any future consumer).
+ *
+ * Historical background: CLI and MCP used to each have their own env loader
+ * (CLI via `loadEnvFile` without expansion, MCP via a handwritten
+ * `parseEnvContent`). Both dropped `${NAME}` expansion from the production
+ * path despite `expandVars` being implemented in CLI's shared lib — a silent
+ * regression from the original design. This module is the single place all
+ * entry points load env files from now on, with full expansion semantics.
+ *
+ * This lives in `@glubean/runner` because it's tool-level runtime
+ * infrastructure (same category as `bootstrap()`), not design-time SDK API.
+ */
+/**
+ * Load a single `.env`-style file and return its parsed key-value pairs.
+ *
+ * - File missing (ENOENT) → returns `{}` silently (consumers decide whether
+ *   missing is an error)
+ * - File unreadable (other IO error) → returns `{}` with a warning to stderr
+ * - Content is parsed with the standard `dotenv` package (no expansion)
+ *
+ * This is the low-level primitive. Most callers want
+ * {@link loadProjectEnv} instead.
+ */
+export declare function loadEnvFile(envPath: string): Promise<Record<string, string>>;
+/**
+ * Expand `${NAME}` references in env values.
+ *
+ * Lookup order per reference:
+ *   1. Already-resolved values from this same expansion pass (supports
+ *      forward references — keys defined earlier in insertion order).
+ *   2. `process.env[NAME]` (host environment variables).
+ *   3. Empty string fallback.
+ *
+ * Iteration is insertion order. This means:
+ * - Within a single file, a later key can reference earlier keys.
+ * - When called on a merged `{ ...vars, ...secrets }` object, secrets-only
+ *   keys can reference any key from `vars` (because vars keys are inserted
+ *   first). Vars keys referencing secrets-only keys **will not resolve**
+ *   in a single pass — they'd need a multi-pass resolver.
+ *
+ * The multi-pass limitation is accepted — callers who need full
+ * topological expansion should use the SDK's `{{NAME}}` template at
+ * runtime via `resolveTemplate`, which resolves lazily in test execution
+ * context and can pull from vars / secrets / session dynamically.
+ */
+export declare function expandVars(vars: Record<string, string>): Record<string, string>;
+/**
+ * Result of loading a project's env + secrets, with `${NAME}` references
+ * fully expanded.
+ *
+ * `vars` and `secrets` are kept as separate objects (never merged) so
+ * downstream layers can apply redaction / masking to secrets without
+ * affecting vars.
+ *
+ * On key collision between `.env` and `.env.secrets`, the secret wins and
+ * the key appears **only** in `secrets`, not in `vars` (no duplication).
+ */
+export interface ProjectEnv {
+    vars: Record<string, string>;
+    secrets: Record<string, string>;
+}
+/**
+ * Load a project's `.env` + `.env.secrets` with full `${NAME}` expansion.
+ *
+ * This is the canonical entry point for loading project env in any Glubean
+ * tool. CLI, MCP, and future consumers should all go through this function.
+ *
+ * ### Behavior
+ *
+ * 1. Reads `<rootDir>/<envFileName>` (default `.env`) and
+ *    `<rootDir>/<envFileName>.secrets` (`.env.secrets` by default). Missing
+ *    files are silently treated as empty.
+ * 2. Merges them temporarily (secrets override vars on key collision) and
+ *    runs {@link expandVars} over the merged set so `${NAME}` references
+ *    can cross between vars and secrets in either direction (subject to
+ *    insertion-order single-pass limitation — see `expandVars` docs).
+ * 3. Splits the expanded merged map back into `vars` and `secrets`,
+ *    preserving the invariant: a key on collision appears only in
+ *    `secrets`, never duplicated into `vars`.
+ *
+ * ### Naming convention
+ *
+ *   `.env` → `.env.secrets`
+ *   `.env.staging` → `.env.staging.secrets`
+ *   `.env.ci` → `.env.ci.secrets`
+ *
+ * The secrets path is always `<envFileName>.secrets` in the same directory.
+ *
+ * @example
+ * ```ts
+ * import { loadProjectEnv } from "@glubean/runner";
+ *
+ * const { vars, secrets } = await loadProjectEnv(projectRoot);
+ * const { vars: stagingVars, secrets: stagingSecrets } =
+ *   await loadProjectEnv(projectRoot, ".env.staging");
+ * ```
+ */
+export declare function loadProjectEnv(rootDir: string, envFileName?: string): Promise<ProjectEnv>;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAWjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxB;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,MAAM,EACf,WAAW,SAAS,GACnB,OAAO,CAAC,UAAU,CAAC,CA2BrB"}

package/dist/env.js

@@ -0,0 +1,134 @@
+/**
+ * @module env
+ *
+ * Canonical project-env loader for all Glubean entry points (CLI `run`,
+ * MCP tool handlers, VSCode extension, any future consumer).
+ *
+ * Historical background: CLI and MCP used to each have their own env loader
+ * (CLI via `loadEnvFile` without expansion, MCP via a handwritten
+ * `parseEnvContent`). Both dropped `${NAME}` expansion from the production
+ * path despite `expandVars` being implemented in CLI's shared lib — a silent
+ * regression from the original design. This module is the single place all
+ * entry points load env files from now on, with full expansion semantics.
+ *
+ * This lives in `@glubean/runner` because it's tool-level runtime
+ * infrastructure (same category as `bootstrap()`), not design-time SDK API.
+ */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parse as parseDotenv } from "dotenv";
+/**
+ * Load a single `.env`-style file and return its parsed key-value pairs.
+ *
+ * - File missing (ENOENT) → returns `{}` silently (consumers decide whether
+ *   missing is an error)
+ * - File unreadable (other IO error) → returns `{}` with a warning to stderr
+ * - Content is parsed with the standard `dotenv` package (no expansion)
+ *
+ * This is the low-level primitive. Most callers want
+ * {@link loadProjectEnv} instead.
+ */
+export async function loadEnvFile(envPath) {
+    try {
+        const content = await readFile(envPath, "utf-8");
+        return parseDotenv(content);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            return {};
+        }
+        console.warn(`Warning: Could not read env file ${envPath}: ${error.message}`);
+        return {};
+    }
+}
+/**
+ * Expand `${NAME}` references in env values.
+ *
+ * Lookup order per reference:
+ *   1. Already-resolved values from this same expansion pass (supports
+ *      forward references — keys defined earlier in insertion order).
+ *   2. `process.env[NAME]` (host environment variables).
+ *   3. Empty string fallback.
+ *
+ * Iteration is insertion order. This means:
+ * - Within a single file, a later key can reference earlier keys.
+ * - When called on a merged `{ ...vars, ...secrets }` object, secrets-only
+ *   keys can reference any key from `vars` (because vars keys are inserted
+ *   first). Vars keys referencing secrets-only keys **will not resolve**
+ *   in a single pass — they'd need a multi-pass resolver.
+ *
+ * The multi-pass limitation is accepted — callers who need full
+ * topological expansion should use the SDK's `{{NAME}}` template at
+ * runtime via `resolveTemplate`, which resolves lazily in test execution
+ * context and can pull from vars / secrets / session dynamically.
+ */
+export function expandVars(vars) {
+    const result = {};
+    for (const [key, value] of Object.entries(vars)) {
+        result[key] = value.replace(/\$\{(\w+)\}/g, (_, name) => {
+            return result[name] ?? process.env[name] ?? "";
+        });
+    }
+    return result;
+}
+/**
+ * Load a project's `.env` + `.env.secrets` with full `${NAME}` expansion.
+ *
+ * This is the canonical entry point for loading project env in any Glubean
+ * tool. CLI, MCP, and future consumers should all go through this function.
+ *
+ * ### Behavior
+ *
+ * 1. Reads `<rootDir>/<envFileName>` (default `.env`) and
+ *    `<rootDir>/<envFileName>.secrets` (`.env.secrets` by default). Missing
+ *    files are silently treated as empty.
+ * 2. Merges them temporarily (secrets override vars on key collision) and
+ *    runs {@link expandVars} over the merged set so `${NAME}` references
+ *    can cross between vars and secrets in either direction (subject to
+ *    insertion-order single-pass limitation — see `expandVars` docs).
+ * 3. Splits the expanded merged map back into `vars` and `secrets`,
+ *    preserving the invariant: a key on collision appears only in
+ *    `secrets`, never duplicated into `vars`.
+ *
+ * ### Naming convention
+ *
+ *   `.env` → `.env.secrets`
+ *   `.env.staging` → `.env.staging.secrets`
+ *   `.env.ci` → `.env.ci.secrets`
+ *
+ * The secrets path is always `<envFileName>.secrets` in the same directory.
+ *
+ * @example
+ * ```ts
+ * import { loadProjectEnv } from "@glubean/runner";
+ *
+ * const { vars, secrets } = await loadProjectEnv(projectRoot);
+ * const { vars: stagingVars, secrets: stagingSecrets } =
+ *   await loadProjectEnv(projectRoot, ".env.staging");
+ * ```
+ */
+export async function loadProjectEnv(rootDir, envFileName = ".env") {
+    const envPath = resolve(rootDir, envFileName);
+    const secretsPath = resolve(rootDir, `${envFileName}.secrets`);
+    const rawVars = await loadEnvFile(envPath);
+    const rawSecrets = await loadEnvFile(secretsPath);
+    // Merge for expansion so `${NAME}` can cross-reference both files.
+    // `{ ...rawVars, ...rawSecrets }` keeps insertion order — vars keys first,
+    // then secrets-only keys — so secrets can reference vars in a single pass.
+    const merged = { ...rawVars, ...rawSecrets };
+    const expanded = expandVars(merged);
+    // Split back. Keys that exist in both files → secret wins, appears only
+    // in `secrets` (not duplicated into `vars`).
+    const vars = {};
+    for (const key of Object.keys(rawVars)) {
+        if (!(key in rawSecrets)) {
+            vars[key] = expanded[key];
+        }
+    }
+    const secrets = {};
+    for (const key of Object.keys(rawSecrets)) {
+        secrets[key] = expanded[key];
+    }
+    return { vars, secrets };
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,QAAQ,CAAC;AAE9C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAe;IAEf,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjD,OAAO,WAAW,CAAC,OAAO,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YACvD,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,oCAAoC,OAAO,KAAM,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;QACzF,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,UAAU,CACxB,IAA4B;IAE5B,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC,EAAE,IAAY,EAAE,EAAE;YAC9D,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACjD,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAe,EACf,WAAW,GAAG,MAAM;IAEpB,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,OAAO,CAAC,OAAO,EAAE,GAAG,WAAW,UAAU,CAAC,CAAC;IAE/D,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,OAAO,CAAC,CAAC;IAC3C,MAAM,UAAU,GAAG,MAAM,WAAW,CAAC,WAAW,CAAC,CAAC;IAElD,mEAAmE;IACnE,2EAA2E;IAC3E,2EAA2E;IAC3E,MAAM,MAAM,GAAG,EAAE,GAAG,OAAO,EAAE,GAAG,UAAU,EAAE,CAAC;IAC7C,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IAEpC,wEAAwE;IACxE,6CAA6C;IAC7C,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,CAAC,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC;YACzB,IAAI,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1C,OAAO,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC"}

package/dist/harness.d.ts

@@ -5,18 +5,5 @@
  * Usage:
  *   tsx harness.ts --testUrl=<url> --testId=<id>
  */
-declare global {
-    var __glubeanRuntime: {
-        vars: Record<string, string>;
-        secrets: Record<string, string>;
-        session: Record<string, unknown>;
-        http: Record<string, unknown>;
-        test: Record<string, unknown>;
-        trace: (t: import("@glubean/sdk").Trace) => void;
-        action: (a: import("@glubean/sdk").GlubeanAction) => void;
-        event: (ev: import("@glubean/sdk").GlubeanEvent) => void;
-        log: (message: string, data?: unknown) => void;
-    };
-}
 export {};
 //# sourceMappingURL=harness.d.ts.map

package/dist/harness.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../src/harness.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,CAAC,MAAM,CAAC;IACb,IAAI,gBAAgB,EAAE;QACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9B,KAAK,EAAE,CAAC,CAAC,EAAE,OAAO,cAAc,EAAE,KAAK,KAAK,IAAI,CAAC;QACjD,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,cAAc,EAAE,aAAa,KAAK,IAAI,CAAC;QAC1D,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,cAAc,EAAE,YAAY,KAAK,IAAI,CAAC;QACzD,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;KAChD,CAAC;CACH"}
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../src/harness.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/harness.js

@@ -8,7 +8,8 @@
 import { parseArgs } from "node:util";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { inferJsonSchema, truncateDeep } from "./schema_inference.js";
-/* eslint-enable no-var */
+import { bootstrap } from "./bootstrap.js";
+import { setRuntime } from "@glubean/sdk/internal";
 import ky from "ky";
 import { Expectation } from "@glubean/sdk/expect";
 // Global error handlers for async errors that escape try/catch
@@ -848,7 +849,30 @@ function normalizeOptions(options) {
     return normalized;
 }
 /**
- * Run pre-request schema validations (query params, request body).
+ * Normalize a HeadersInit value (Headers instance, plain object, or array of
+ * tuples) into a plain Record<string, string> suitable for schema validation.
+ */
+function normalizeHeadersForValidation(headers) {
+    if (headers == null)
+        return {};
+    if (typeof Headers !== "undefined" && headers instanceof Headers) {
+        return Object.fromEntries(headers.entries());
+    }
+    if (Array.isArray(headers)) {
+        return Object.fromEntries(headers.filter((p) => Array.isArray(p) && p.length === 2));
+    }
+    if (typeof headers === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(headers)) {
+            if (v != null)
+                out[k] = String(v);
+        }
+        return out;
+    }
+    return {};
+}
+/**
+ * Run pre-request schema validations (query params, request body, request headers).
  * Extracts schema option from the options object.
  */
 function runPreRequestSchemaValidation(options) {
@@ -865,6 +889,12 @@ function runPreRequestSchemaValidation(options) {
         const { schema, severity } = resolveSchemaEntry(schemaOpts.request);
         runSchemaValidation(options.json, schema, "request body", severity);
     }
+    // Validate request headers (per-call only; client-level defaults not included)
+    if (schemaOpts.requestHeaders && options?.headers != null) {
+        const { schema, severity } = resolveSchemaEntry(schemaOpts.requestHeaders);
+        const headers = normalizeHeadersForValidation(options.headers);
+        runSchemaValidation(headers, schema, "request headers", severity);
+    }
 }
 /**
  * Wrap a ky response promise to run post-response schema validation.
@@ -888,7 +918,7 @@ function wrapKy(instance, label = "base") {
     const methods = ["get", "post", "put", "patch", "delete", "head"];
     function callWithSchema(kyFn, input, options) {
         const normalized = normalizeOptions(options);
-        // Run pre-request validations (query, request body)
+        // Run pre-request validations (query, request body, request headers)
         runPreRequestSchemaValidation(normalized);
         // Strip schema option before passing to ky (ky doesn't know about it)
         let kyOptions;
@@ -899,6 +929,25 @@ function wrapKy(instance, label = "base") {
         else {
             kyOptions = normalized;
         }
+        // Inject afterResponse hook for response headers validation (fires once per final response)
+        const responseHeadersSchema = normalized?.schema?.responseHeaders;
+        if (responseHeadersSchema) {
+            const { schema, severity } = resolveSchemaEntry(responseHeadersSchema);
+            const headersHook = (_req, _opts, response) => {
+                const headersObj = normalizeHeadersForValidation(response.headers);
+                runSchemaValidation(headersObj, schema, "response headers", severity);
+            };
+            kyOptions = {
+                ...kyOptions,
+                hooks: {
+                    ...kyOptions?.hooks,
+                    afterResponse: [
+                        ...(kyOptions?.hooks?.afterResponse ?? []),
+                        headersHook,
+                    ],
+                },
+            };
+        }
         if (glubeanDebug) {
             process.stderr.write(`[glubean:debug] ky.call [${label}] url=${String(input)} per-call-options=${JSON.stringify(kyOptions ?? null)}\n`);
         }
@@ -944,7 +993,7 @@ function withEnvFallback(explicit) {
         },
     });
 }
-globalThis.__glubeanRuntime = {
+setRuntime({
     vars: withEnvFallback(rawVars),
     secrets: withEnvFallback(rawSecrets),
     session: sessionData,
@@ -963,8 +1012,14 @@ globalThis.__glubeanRuntime = {
     action: ctx.action,
     event: ctx.event,
     log: ctx.log,
-};
+});
 try {
+    // Bootstrap project plugins before loading user code. Without this, any
+    // test module that uses plugin-registered primitives (custom matchers,
+    // `contract.graphql(...)`, `contract.grpc(...)`, ...) would either fail
+    // on first access or silently fall through to the default behavior — see
+    // plugin-manifest-proposal.md D2.
+    await bootstrap(process.cwd());
     // Dynamic import - LOAD phase
     console.log(JSON.stringify({
         type: "log",
@@ -1222,7 +1277,8 @@ async function executeNewTest(test) {
     // downstream code (ctx.assert, ky hooks, globalFetch) can access
     // the per-test state via currentTestCtx().
     await testContext.run(trc, async () => {
-        // Runtime metadata is now served via ALS getter on __glubeanRuntime.test
+        // Runtime metadata is served via the `test` getter on the carrier runtime,
+        // which reads from TestRunContext ALS (see setRuntime() call above).
         emitEvent({
             type: "start",
             id: test.meta.id,