@glubean/sdk 0.2.1 → 0.2.3

package/dist/install-plugin.js

@@ -0,0 +1,222 @@
+/**
+ * @module install-plugin
+ *
+ * Plugin manifest installation driver — the single entry point for plugin-level
+ * global registration. Builds on top of the low-level primitives
+ * (`Expectation.extend`, `contract.register`) to provide:
+ *
+ * - **Plugin identity** — every manifest has a `name`, tracked for diagnostics.
+ * - **Conflict detection** — duplicate matcher/protocol names throw, whether the
+ *   prior registration was from another plugin manifest or from a direct call
+ *   to the low-level primitive.
+ * - **Idempotent install** — re-installing the same plugin (by `name`) is a no-op.
+ * - **Failed-setup isolation** — if a plugin's `setup()` throws, the plugin is
+ *   marked as setup-failed; retrying the same plugin in the same process raises
+ *   a clear error rather than silently re-registering matchers/contracts.
+ * - **Install-order hooks** — `setup()` runs after matchers/contracts are registered.
+ *
+ * `installPlugin` is the recommended surface for plugin authors. The primitives
+ * (`Expectation.extend`, `contract.register`) remain public for inline patching
+ * or prototyping. `installPlugin` still detects collisions against them — a
+ * plugin trying to register a matcher/protocol that a direct primitive call
+ * already owns will throw.
+ *
+ * @see {@link PluginManifest} in `./types.js`
+ */
+import { Expectation } from "./expect.js";
+import { contract, getAdapter, __unregisterProtocolForTesting } from "./contract-core.js";
+/**
+ * Registry of fully installed plugins (matchers + contracts + setup all
+ * succeeded), keyed by manifest `name`. Feeds `listInstalledPlugins()`.
+ * @internal
+ */
+const installed = new Map();
+/**
+ * Plugins whose `setup()` threw. Matchers/contracts they registered remain
+ * on the globals (irreversible), but the plugin is NOT in `installed`.
+ * Retrying such a plugin in the same process throws immediately.
+ * @internal
+ */
+const setupFailures = new Map();
+/**
+ * Reverse index: which plugin owns which matcher name?
+ * Keyed by matcher name → plugin name.
+ * @internal
+ */
+const matcherOwners = new Map();
+/**
+ * Reverse index: which plugin owns which protocol name?
+ * Keyed by protocol name → plugin name.
+ * @internal
+ */
+const protocolOwners = new Map();
+/**
+ * Install one or more plugin manifests. Drives registration in strict order:
+ *
+ * 1. Validate the manifest shape.
+ * 2. Check each matcher/protocol name for conflicts (both across plugins and
+ *    against direct primitive registrations). Throws on first conflict.
+ * 3. Register all matchers via `Expectation.extend`.
+ * 4. Register all contracts via `contract.register`.
+ * 5. Run `setup()` if present (awaited).
+ * 6. Record the plugin in the installed registry.
+ *
+ * Subsequent calls with an already-installed plugin (same `name`) are no-ops.
+ * Subsequent calls with a previously-setup-failed plugin throw.
+ *
+ * **Failure semantics**: if `setup()` throws, the process is left in a
+ * partially-initialized state (matchers/contracts from this plugin are on
+ * the globals but `installed` does not list the plugin). This state is
+ * **not recoverable within the same process** — the only clean remedy is to
+ * restart. Retrying the same plugin raises a clear error instead of silently
+ * re-registering.
+ *
+ * @param plugins One or more manifests to install, in order.
+ *
+ * @example
+ * ```ts
+ * import { installPlugin } from "@glubean/sdk";
+ * import graphqlPlugin from "@glubean/graphql";
+ * import grpcPlugin from "@glubean/grpc";
+ *
+ * await installPlugin(graphqlPlugin, grpcPlugin);
+ * ```
+ */
+export async function installPlugin(...plugins) {
+    for (const plugin of plugins) {
+        if (!plugin || typeof plugin !== "object" || typeof plugin.name !== "string") {
+            throw new Error("installPlugin: expected a PluginManifest with a string `name` field. " +
+                `Got: ${typeof plugin === "object" ? JSON.stringify(plugin) : typeof plugin}.`);
+        }
+        // Fast-path: successful re-install is idempotent.
+        if (installed.has(plugin.name)) {
+            if (typeof process !== "undefined" && process.env?.["GLUBEAN_DEBUG"]) {
+                process.stderr.write(`[glubean:debug] installPlugin: skipping duplicate install of "${plugin.name}"\n`);
+            }
+            continue;
+        }
+        // Failed-setup path: matchers/contracts from a prior failed attempt are
+        // still on the globals, so re-registering them would double-register.
+        // Throw with full context rather than silently continuing.
+        const prevFailure = setupFailures.get(plugin.name);
+        if (prevFailure) {
+            throw new Error(`installPlugin("${plugin.name}"): previous setup() attempt failed in this process ` +
+                `and left matchers/contracts partially registered. This state is not recoverable — ` +
+                `restart the process to retry. Original error: ${prevFailure.message}`);
+        }
+        // --- Pre-flight conflict checks --------------------------------------
+        // Done BEFORE any mutation so a conflict on the Nth matcher doesn't leave
+        // the first N-1 matchers on the prototype.
+        if (plugin.matchers) {
+            for (const name of Object.keys(plugin.matchers)) {
+                const existingOwner = matcherOwners.get(name);
+                if (existingOwner) {
+                    throw new Error(`installPlugin("${plugin.name}"): matcher "${name}" is already registered ` +
+                        `by plugin "${existingOwner}". ` +
+                        `Each matcher name can only be owned by one plugin.`);
+                }
+                // Catch matchers registered via a direct `Expectation.extend()` call
+                // that bypassed installPlugin. Expectation.extend itself would throw
+                // when we try to register, but with a generic message — pre-check so
+                // the error names the plugin that's trying to register.
+                if (name in Expectation.prototype) {
+                    throw new Error(`installPlugin("${plugin.name}"): matcher "${name}" already exists on Expectation.prototype ` +
+                        `(likely registered by a direct Expectation.extend() call or a built-in matcher). ` +
+                        `Matcher names must be unique across the entire process.`);
+                }
+            }
+        }
+        if (plugin.contracts) {
+            for (const protocol of Object.keys(plugin.contracts)) {
+                const existingOwner = protocolOwners.get(protocol);
+                if (existingOwner) {
+                    throw new Error(`installPlugin("${plugin.name}"): protocol "${protocol}" is already registered ` +
+                        `by plugin "${existingOwner}". ` +
+                        `Each protocol name can only be owned by one plugin.`);
+                }
+                // Catch protocols registered via a direct `contract.register()` call
+                // that bypassed installPlugin. Unlike Expectation.extend, the current
+                // contract.register has no built-in duplicate guard — it would
+                // silently overwrite the live adapter. Pre-check via getAdapter().
+                if (getAdapter(protocol)) {
+                    throw new Error(`installPlugin("${plugin.name}"): protocol "${protocol}" is already present in the contract registry ` +
+                        `(likely registered by a direct contract.register() call). ` +
+                        `Protocol names must be unique across the entire process.`);
+                }
+            }
+        }
+        // --- Mutations (past this point, prototype/registry get modified) ----
+        if (plugin.matchers) {
+            for (const [name, fn] of Object.entries(plugin.matchers)) {
+                Expectation.extend({ [name]: fn });
+                matcherOwners.set(name, plugin.name);
+            }
+        }
+        if (plugin.contracts) {
+            for (const [protocol, adapter] of Object.entries(plugin.contracts)) {
+                contract.register(protocol, adapter);
+                protocolOwners.set(protocol, plugin.name);
+            }
+        }
+        // --- Setup hook (failure leaves partial state) -----------------------
+        if (plugin.setup) {
+            try {
+                await plugin.setup();
+            }
+            catch (err) {
+                const error = err instanceof Error ? err : new Error(String(err));
+                setupFailures.set(plugin.name, error);
+                throw error;
+            }
+        }
+        installed.set(plugin.name, plugin);
+    }
+}
+/**
+ * Return a snapshot array of all successfully installed plugin manifests, in
+ * install order. Plugins whose `setup()` threw are **not** included.
+ *
+ * The returned array is a shallow copy — mutating it does not affect the
+ * installed state. Manifest objects themselves are returned by reference.
+ */
+export function listInstalledPlugins() {
+    return [...installed.values()];
+}
+/**
+ * Clear all installed-plugin state. **Test-only.**
+ *
+ * Performs a **true reset**:
+ *   1. Unregisters every matcher previously installed via a plugin manifest
+ *      from `Expectation.prototype`.
+ *   2. Unregisters every protocol adapter previously installed via a plugin
+ *      manifest from the contract registry (`_adapters` + `contract[protocol]`).
+ *   3. Clears all internal tracking maps (`installed`, `matcherOwners`,
+ *      `protocolOwners`, `setupFailures`).
+ *
+ * **Scope limits:**
+ * - Only touches registrations introduced via `installPlugin`. Matchers /
+ *   protocols registered via a direct call to the primitive (bypassing
+ *   `installPlugin`) are **not** tracked by the owner maps and therefore
+ *   will not be removed.
+ * - Built-in Expectation matchers (defined on the class body, not added
+ *   via `extend()`) are unaffected because `delete` on a class-syntax
+ *   method is a no-op.
+ *
+ * Intended for test suites that install plugins, need to simulate a
+ * fresh process, and then install again.
+ *
+ * @internal
+ */
+export function __resetInstalledPluginsForTesting() {
+    for (const [name] of matcherOwners) {
+        Expectation.__removeMatcherForTesting(name);
+    }
+    for (const [protocol] of protocolOwners) {
+        __unregisterProtocolForTesting(protocol);
+    }
+    installed.clear();
+    matcherOwners.clear();
+    protocolOwners.clear();
+    setupFailures.clear();
+}
+//# sourceMappingURL=install-plugin.js.map

package/dist/install-plugin.js.map

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

package/dist/internal.d.ts

@@ -11,6 +11,8 @@
  */
 import type { RegisteredTestMeta } from "./types.js";
 export { getRuntime, setRuntime, runWithRuntime, installCarrier, createGlobalThisCarrier, createAlsCarrier, type RuntimeCarrier, type InternalRuntime, } from "./runtime-carrier.js";
+export { __resetInstalledPluginsForTesting, } from "./install-plugin.js";
+export { setExplicitInput, getExplicitInput, setBootstrapInput, getBootstrapInput, setForceStandalone, isForceStandalone, clearRunnerInputs, } from "./runner-input-channel.js";
 /**
  * Register a test to the global registry.
  * Called internally by the test builders.

package/dist/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EACL,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,uBAAuB,EACvB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAW9B;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAE3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,IAAI,kBAAkB,EAAE,CAElD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAErD,OAAO,EACL,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,uBAAuB,EACvB,gBAAgB,EAChB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EACL,iCAAiC,GAClC,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AAWnC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,kBAAkB,GAAG,IAAI,CAE3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,IAAI,kBAAkB,EAAE,CAElD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC"}

package/dist/internal.js

@@ -10,6 +10,14 @@
  * @internal
  */
 export { getRuntime, setRuntime, runWithRuntime, installCarrier, createGlobalThisCarrier, createAlsCarrier, } from "./runtime-carrier.js";
+// Internal-only test hook for plugin install state. Public callers use
+// `installPlugin` / `listInstalledPlugins` from the main export. The matching
+// bootstrap reset lives in `@glubean/runner/internal` alongside the bootstrap
+// implementation (see runner/src/bootstrap.ts).
+export { __resetInstalledPluginsForTesting, } from "./install-plugin.js";
+// Runner input channel — runner harness populates these before importing
+// the user module; dispatcher reads them when applying §5.1 algorithm.
+export { setExplicitInput, getExplicitInput, setBootstrapInput, getBootstrapInput, setForceStandalone, isForceStandalone, clearRunnerInputs, } from "./runner-input-channel.js";
 /**
  * Global registry for test metadata.
  * Populated at import time when test files are loaded.

package/dist/internal.js.map

@@ -1 +1 @@
-{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EACL,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,uBAAuB,EACvB,gBAAgB,GAGjB,MAAM,sBAAsB,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,SAAS,GAAyB,EAAE,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAwB;IACnD,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;AACvB,CAAC"}
+{"version":3,"file":"internal.js","sourceRoot":"","sources":["../src/internal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EACL,UAAU,EACV,UAAU,EACV,cAAc,EACd,cAAc,EACd,uBAAuB,EACvB,gBAAgB,GAGjB,MAAM,sBAAsB,CAAC;AAE9B,uEAAuE;AACvE,8EAA8E;AAC9E,8EAA8E;AAC9E,gDAAgD;AAChD,OAAO,EACL,iCAAiC,GAClC,MAAM,qBAAqB,CAAC;AAE7B,yEAAyE;AACzE,uEAAuE;AACvE,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,2BAA2B,CAAC;AAEnC;;;;;;GAMG;AACH,MAAM,SAAS,GAAyB,EAAE,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAwB;IACnD,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;AACxB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa;IAC3B,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;AACvB,CAAC"}

package/dist/plugin.d.ts

@@ -1,56 +1,67 @@
 /**
- * Plugin definition helper for Glubean SDK.
+ * Plugin authoring helpers.
  *
- * Plugin authors use `definePlugin()` to create plugin factories that
- * integrate with `configure({ plugins: { ... } })`. This is the recommended
- * way to define plugins — it handles the `PluginFactory` phantom type trick
- * so plugin authors don't need to understand it.
+ * Two APIs live here, one per concept:
  *
- * @example
- * ```ts
- * import { definePlugin } from "@glubean/sdk";
+ * 1. **`definePlugin(manifest)`** — declare a plugin manifest for global
+ *    registration (matchers, protocol adapters, one-time setup). Consumed by
+ *    {@link installPlugin} in `./install-plugin.js`. This is the primary API
+ *    for plugin packages like `@glubean/graphql` and `@glubean/grpc`.
  *
- * export const myPlugin = (opts: MyOptions) =>
- *   definePlugin((runtime) => {
- *     const baseUrl = runtime.requireVar(opts.baseUrlKey);
- *     return new MyClient(baseUrl);
- *   });
- * ```
+ * 2. **`defineClientFactory(create)`** — declare a lazy client factory for
+ *    per-file injection via `configure({ plugins })`. This is what the
+ *    legacy `definePlugin((runtime) => T)` signature used to do; the name
+ *    has been corrected to describe what it actually is (a client factory,
+ *    not a plugin).
+ *
+ * The legacy `definePlugin((runtime) => T)` overload was removed in Phase 3.
+ * Migrate call sites to `defineClientFactory((runtime) => T)` for the same
+ * behavior and better naming.
  *
  * @module plugin
  */
-import type { GlubeanRuntime, PluginFactory } from "./types.js";
+import type { ClientFactory, GlubeanRuntime, PluginManifest } from "./types.js";
 /**
- * Create a plugin factory. This is the recommended way to define plugins.
+ * Declare a lazy client factory.
  *
- * The factory function receives a `GlubeanRuntime` with access to vars,
- * secrets, HTTP client, and template resolution. It is called lazily on
+ * The factory function receives a `GlubeanRuntime` (vars / secrets / http /
+ * template resolution) and returns a client instance. It is invoked lazily on
  * first property access during test execution, not at module load time.
  *
- * @param create Factory function that receives the runtime and returns the plugin instance
- * @returns A `PluginFactory<T>` suitable for use in `configure({ plugins: { ... } })`
+ * Output is consumed by `configure({ plugins: { name: factory } })` for
+ * per-file client injection.
  *
- * @example Simple plugin
+ * @param create Factory function receiving the runtime; returns the client.
+ * @returns A `ClientFactory<T>` suitable for `configure({ plugins })`.
+ *
+ * @example Simple client
  * ```ts
- * export const myPlugin = (opts: { baseUrlKey: string }) =>
- *   definePlugin((runtime) => {
+ * export const myClient = (opts: { baseUrlKey: string }) =>
+ *   defineClientFactory((runtime) => {
  *     const baseUrl = runtime.requireVar(opts.baseUrlKey);
  *     return new MyClient(baseUrl);
  *   });
  * ```
+ */
+export declare function defineClientFactory<T>(create: (runtime: GlubeanRuntime) => T): ClientFactory<T>;
+/**
+ * Declare a plugin manifest for global registration.
  *
- * @example Plugin with auth headers
+ * The returned manifest is consumed by `installPlugin(...manifests)` at
+ * bootstrap time. A manifest can declare custom matchers, protocol adapters,
+ * and a one-time `setup()` hook. See {@link PluginManifest}.
+ *
+ * @example Plugin manifest
  * ```ts
- * export const graphql = (opts: { endpoint: string; headers?: Record<string, string> }) =>
- *   definePlugin((runtime) => {
- *     const url = runtime.requireVar(opts.endpoint);
- *     const headers: Record<string, string> = {};
- *     for (const [k, v] of Object.entries(opts.headers ?? {})) {
- *       headers[k] = runtime.resolveTemplate(v);
- *     }
- *     return createGraphQLClient(runtime.http, { endpoint: url, headers });
- *   });
+ * export default definePlugin({
+ *   name: "@glubean/graphql",
+ *   matchers: { toHaveGraphqlData, toHaveGraphqlErrorCode },
+ *   contracts: { graphql: graphqlAdapter },
+ *   setup() {
+ *     // Optional one-time registration work
+ *   },
+ * });
  * ```
  */
-export declare function definePlugin<T>(create: (runtime: GlubeanRuntime) => T): PluginFactory<T>;
+export declare function definePlugin(manifest: PluginManifest): PluginManifest;
 //# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,CAAC,GACrC,aAAa,CAAC,CAAC,CAAC,CAElB"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EACnC,MAAM,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,CAAC,GACrC,aAAa,CAAC,CAAC,CAAC,CAElB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,cAAc,GAAG,cAAc,CAErE"}

package/dist/plugin.js

@@ -1,57 +1,70 @@
 /**
- * Plugin definition helper for Glubean SDK.
+ * Plugin authoring helpers.
  *
- * Plugin authors use `definePlugin()` to create plugin factories that
- * integrate with `configure({ plugins: { ... } })`. This is the recommended
- * way to define plugins — it handles the `PluginFactory` phantom type trick
- * so plugin authors don't need to understand it.
+ * Two APIs live here, one per concept:
  *
- * @example
- * ```ts
- * import { definePlugin } from "@glubean/sdk";
+ * 1. **`definePlugin(manifest)`** — declare a plugin manifest for global
+ *    registration (matchers, protocol adapters, one-time setup). Consumed by
+ *    {@link installPlugin} in `./install-plugin.js`. This is the primary API
+ *    for plugin packages like `@glubean/graphql` and `@glubean/grpc`.
  *
- * export const myPlugin = (opts: MyOptions) =>
- *   definePlugin((runtime) => {
- *     const baseUrl = runtime.requireVar(opts.baseUrlKey);
- *     return new MyClient(baseUrl);
- *   });
- * ```
+ * 2. **`defineClientFactory(create)`** — declare a lazy client factory for
+ *    per-file injection via `configure({ plugins })`. This is what the
+ *    legacy `definePlugin((runtime) => T)` signature used to do; the name
+ *    has been corrected to describe what it actually is (a client factory,
+ *    not a plugin).
+ *
+ * The legacy `definePlugin((runtime) => T)` overload was removed in Phase 3.
+ * Migrate call sites to `defineClientFactory((runtime) => T)` for the same
+ * behavior and better naming.
  *
  * @module plugin
  */
 /**
- * Create a plugin factory. This is the recommended way to define plugins.
+ * Declare a lazy client factory.
  *
- * The factory function receives a `GlubeanRuntime` with access to vars,
- * secrets, HTTP client, and template resolution. It is called lazily on
+ * The factory function receives a `GlubeanRuntime` (vars / secrets / http /
+ * template resolution) and returns a client instance. It is invoked lazily on
  * first property access during test execution, not at module load time.
  *
- * @param create Factory function that receives the runtime and returns the plugin instance
- * @returns A `PluginFactory<T>` suitable for use in `configure({ plugins: { ... } })`
+ * Output is consumed by `configure({ plugins: { name: factory } })` for
+ * per-file client injection.
+ *
+ * @param create Factory function receiving the runtime; returns the client.
+ * @returns A `ClientFactory<T>` suitable for `configure({ plugins })`.
  *
- * @example Simple plugin
+ * @example Simple client
  * ```ts
- * export const myPlugin = (opts: { baseUrlKey: string }) =>
- *   definePlugin((runtime) => {
+ * export const myClient = (opts: { baseUrlKey: string }) =>
+ *   defineClientFactory((runtime) => {
  *     const baseUrl = runtime.requireVar(opts.baseUrlKey);
  *     return new MyClient(baseUrl);
  *   });
  * ```
+ */
+export function defineClientFactory(create) {
+    return { __type: undefined, create };
+}
+/**
+ * Declare a plugin manifest for global registration.
  *
- * @example Plugin with auth headers
+ * The returned manifest is consumed by `installPlugin(...manifests)` at
+ * bootstrap time. A manifest can declare custom matchers, protocol adapters,
+ * and a one-time `setup()` hook. See {@link PluginManifest}.
+ *
+ * @example Plugin manifest
  * ```ts
- * export const graphql = (opts: { endpoint: string; headers?: Record<string, string> }) =>
- *   definePlugin((runtime) => {
- *     const url = runtime.requireVar(opts.endpoint);
- *     const headers: Record<string, string> = {};
- *     for (const [k, v] of Object.entries(opts.headers ?? {})) {
- *       headers[k] = runtime.resolveTemplate(v);
- *     }
- *     return createGraphQLClient(runtime.http, { endpoint: url, headers });
- *   });
+ * export default definePlugin({
+ *   name: "@glubean/graphql",
+ *   matchers: { toHaveGraphqlData, toHaveGraphqlErrorCode },
+ *   contracts: { graphql: graphqlAdapter },
+ *   setup() {
+ *     // Optional one-time registration work
+ *   },
+ * });
  * ```
  */
-export function definePlugin(create) {
-    return { __type: undefined, create };
+export function definePlugin(manifest) {
+    return manifest;
 }
 //# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,YAAY,CAC1B,MAAsC;IAEtC,OAAO,EAAE,MAAM,EAAE,SAAyB,EAAE,MAAM,EAAE,CAAC;AACvD,CAAC"}
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAAsC;IAEtC,OAAO,EAAE,MAAM,EAAE,SAAyB,EAAE,MAAM,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,YAAY,CAAC,QAAwB;IACnD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/runner-input-channel.d.ts

@@ -0,0 +1,95 @@
+/**
+ * @module runner-input-channel
+ *
+ * Process-local channel for runner-supplied case inputs. The dispatcher
+ * (`contract-core.ts`) reads from this channel when applying the §5.1
+ * runnable resolution algorithm. The runner harness writes to it before
+ * importing the user module.
+ *
+ * Two independent slots per testId (per attachment-model §8):
+ *
+ * - `explicit input` — fed via CLI `--input-json` / MCP `inputJson` /
+ *   programmatic `input`. When present, the dispatcher runs the raw case
+ *   with this input AFTER validating against the case's `needs` schema
+ *   (§5.1 step 1). Bootstrap overlay is NOT invoked even if registered.
+ *
+ * - `bootstrap input` — fed via CLI `--bootstrap-json` /
+ *   MCP `bootstrapInput` / programmatic `bootstrapInput`. Passed to the
+ *   overlay's `run(ctx, params)` after validation against the overlay's
+ *   `params` schema. Only meaningful when an overlay is registered AND
+ *   the run uses overlay mode.
+ *
+ * - `force standalone` (debug) — for no-needs cases marked
+ *   `runnability.requireAttachment: true`, allows bypassing the
+ *   "requires attachment" guard. §6.3 escape valve. Author-debug only;
+ *   warning emitted at runtime.
+ *
+ * The channel is process-local (a plain Map). Subprocess boundaries are
+ * the harness's responsibility — it serializes runner options, spawns the
+ * subprocess with env vars / args, and the harness's `setRuntime`-time
+ * code populates this channel before the user module imports.
+ *
+ * @internal
+ */
+/**
+ * Set the explicit case input for a given testId. Subsequent dispatcher
+ * runs of that testId will take this path (§5.1 step 1) regardless of
+ * whether a bootstrap overlay is registered.
+ *
+ * @internal
+ */
+export declare function setExplicitInput(testId: string, input: unknown): void;
+/**
+ * Read the explicit case input for a given testId. Returns
+ * `{ has: true, value }` when present (including when value is
+ * `undefined` / `null` / `false`), `{ has: false }` otherwise.
+ *
+ * @internal
+ */
+export declare function getExplicitInput(testId: string): {
+    has: true;
+    value: unknown;
+} | {
+    has: false;
+};
+/**
+ * Set the bootstrap params for a given testId. Read by the dispatcher
+ * when invoking an overlay (§5.1 step 3a).
+ *
+ * @internal
+ */
+export declare function setBootstrapInput(testId: string, input: unknown): void;
+/**
+ * Read the bootstrap params for a given testId.
+ *
+ * @internal
+ */
+export declare function getBootstrapInput(testId: string): {
+    has: true;
+    value: unknown;
+} | {
+    has: false;
+};
+/**
+ * Mark a testId as force-standalone (§6.3 debug escape valve for
+ * `requireAttachment` no-needs cases). The dispatcher will bypass the
+ * `requireAttachment` guard for this testId; a runtime warning is
+ * emitted alongside.
+ *
+ * @internal
+ */
+export declare function setForceStandalone(testId: string): void;
+/**
+ * Check whether a testId is force-standalone.
+ *
+ * @internal
+ */
+export declare function isForceStandalone(testId: string): boolean;
+/**
+ * Clear all runner-supplied inputs. Test hook; not part of the public
+ * API. Called by harness teardown and by tests that want a clean slate.
+ *
+ * @internal
+ */
+export declare function clearRunnerInputs(): void;
+//# sourceMappingURL=runner-input-channel.d.ts.map

package/dist/runner-input-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner-input-channel.d.ts","sourceRoot":"","sources":["../src/runner-input-channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAcH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAErE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,GACb;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,KAAK,CAAA;CAAE,CAGhD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAEtE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,GACb;IAAE,GAAG,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,GAAG,EAAE,KAAK,CAAA;CAAE,CAGhD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAIxC"}