@browserstack/mcp-server 1.5.1-beta.2 → 2.0.0

package/dist/tools/capability-registry/index-loader.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Load the index artifact(s) and expose the lookups the tools need.
+ *
+ * ONE FILE PER PRODUCT is the released contract, so loading is a merge across files. The
+ * merged model keeps the products map the rest of the server already reads, which is what
+ * lets searchCapability rank across products from N single-product files.
+ */
+import { Capability, ProductIndex, Provenance, RegistryIndex, ResponseDoc, SchemaNode } from "./types.js";
+export declare class IndexError extends Error {
+}
+/** Thrown to the caller as a tool error, so the wording is caller-facing. */
+export declare class InvocationError extends Error {
+}
+/** The file inside a product subdirectory, for the earlier nested layout. */
+export declare const INDEX_FILE = "index.json";
+/** The stored layout, and the name the export publishes: `<product>.capability-index.json`. */
+export declare const FLAT_SUFFIX = ".capability-index.json";
+/**
+ * The product a file's LOCATION claims to describe, if its layout says so.
+ *
+ * `capability/tm.capability-index.json` and `capability/tm/index.json` both name their
+ * product, and
+ * `fromFiles` cross-checks that against the product key inside. A file in the wrong place
+ * would otherwise register its product under the directory's name and answer for endpoints
+ * it does not have.
+ */
+export declare function productFromPath(file: string): string | undefined;
+export declare function endpointKey(method: string, path: string): string;
+/**
+ * Is this capability withheld from the surface?
+ *
+ * FAILS CLOSED: any truthy `disabled` hides it, not just `=== true`. The flag exists to
+ * suppress something that cannot work, so an unexpected shape must hide it rather than be
+ * ignored — the opposite default would turn a typo into a silently re-enabled capability.
+ */
+export declare function isDisabled(capability: Capability): boolean;
+export interface LoadedProduct {
+    name: string;
+    product: ProductIndex;
+    provenance: Provenance;
+}
+/**
+ * Read one artifact file into the product it carries.
+ *
+ * SHAPE DETECTION, NOT VERSION DETECTION. The released envelope and the pre-release one
+ * both declare `schema_version: 1`, so the number cannot tell them apart; the `products`
+ * wrapper can, and is the documented discriminator. The pre-release branch is defensive
+ * only — that shape was never deployed.
+ */
+export declare function readIndexFile(raw: unknown, source?: string): LoadedProduct;
+export declare class CapabilityRegistry {
+    readonly index: RegistryIndex;
+    /** product -> provenance of the file it came from. */
+    readonly provenance: Record<string, Provenance>;
+    /** product -> "METHOD /path" -> capability */
+    private readonly byEndpoint;
+    /** product -> capability name -> capability. Empty for products that publish no names. */
+    private readonly byName;
+    /**
+     * product -> name AND "METHOD /path" -> the capability that flag withheld.
+     *
+     * Kept only so an invoke against a handle the caller already holds can say
+     * `capability_disabled` instead of `unknown_capability`. Nothing else reads it, and it
+     * is deliberately not reachable from `index`.
+     */
+    private readonly withheld;
+    constructor(index: RegistryIndex, provenance?: Record<string, Provenance>);
+    /**
+     * The `capability_disabled` message for a handle this build withholds, if it is one.
+     *
+     * Says THAT it is disabled and nothing about why. The reason is documentation and lives
+     * with the decision; repeating it here would put four copies of a paragraph in the
+     * shipped artifact to serve a path the flag itself makes rare.
+     *
+     * Returns undefined for anything else, so the caller falls through to its own
+     * not-found wording.
+     */
+    private withheldMatch;
+    /** How many capabilities each product withholds. Startup logging only. */
+    disabledCounts(): Record<string, number>;
+    static fromFile(file: string): CapabilityRegistry;
+    /**
+     * Merge every discovered artifact into one registry.
+     *
+     * ANY unreadable file fails the whole load, deliberately. Skipping one and carrying on
+     * would leave a registry that answers "no such capability" for a product that exists —
+     * a confident wrong answer, which is worse than the caller-visible absence of the whole
+     * surface (which `register.ts` logs a reason for).
+     */
+    static fromFiles(files: string[]): CapabilityRegistry;
+    /** The single product's build id, or `name:id` pairs when several are loaded. */
+    get buildId(): string;
+    productNames(): string[];
+    /** Per-product `{build_id, version}`, for logging and cache-busting only. */
+    buildInfo(): Record<string, Provenance>;
+    /**
+     * Find a capability by its published name — the preferred handle.
+     *
+     * Names are unique within a product but not across products, so an ambiguous name is
+     * reported rather than resolved by load order. A name that exists in no index is
+     * `unknown_capability`: a distinct outcome from a name that exists elsewhere, because the
+     * caller's next move differs — search again, versus pass `product`.
+     */
+    byNameLookup(name: string, product?: string): {
+        product: string;
+        capability: Capability;
+    };
+    /**
+     * Find a capability by the endpoint it exposes — the handle for unnamed products.
+     *
+     * The endpoint is what searchCapability returns, so it is the only thing a caller can
+     * hold. `unknown_endpoint` is a defined outcome rather than a generic failure: a caller
+     * working from stale search output needs to know to search again, not to retry.
+     */
+    byEndpointLookup(method: string, path: string, product?: string): {
+        product: string;
+        capability: Capability;
+    };
+}
+/**
+ * Resolve a `{$response|$schema: "Name"}` reference against the product's lookup tables.
+ *
+ * ONE HOP. The named component it returns may itself contain references — 39 of tm's 53
+ * named responses do — so this is the primitive, not the whole job. Use `resolveResponses`
+ * to get a tree with nothing left to look up.
+ *
+ * A node that is not a reference is returned as-is, and an unresolvable name yields
+ * `undefined` rather than throwing: the tables are additive and their absence means "no
+ * response schema available".
+ */
+export declare function resolveComponent<T extends ResponseDoc | SchemaNode>(product: ProductIndex, node: T | undefined): T | undefined;
+/**
+ * Resolve every reference in a tree, however deep.
+ *
+ * REFERENCES ARE NESTED, which is the part a one-hop reader gets wrong. They appear at the
+ * top of a response (`{"$response": "BadRequest"}`), on its schema
+ * (`.../schema/{"$schema": "TestCaseListResponse"}`), and inside the schema's own
+ * properties (`.../schema/properties/data/properties/folder`). Chains are real too: a
+ * capability's 400 resolves to the named `BadRequest`, whose schema is `{"$schema":
+ * "ErrorResponse"}`.
+ *
+ * AN UNRESOLVABLE REFERENCE IS LEFT IN PLACE, not dropped and not thrown on. A dangling
+ * name (the tables are built separately from the capabilities) or a cycle (a folder whose
+ * schema contains folders) then shows up as the `{"$schema": "…"}` node it is, which a
+ * reader can still act on, rather than as a silently truncated schema.
+ */
+export declare function resolveDeep<T>(product: ProductIndex, node: T): T;
+/** Which declared responses to hand back. */
+export type ResponseSelection = "success" | "all" | "none";
+/**
+ * A capability's declared responses with every reference followed.
+ *
+ * SUCCESS ONLY BY DEFAULT. The error entries are near-identical across the surface — 148 of
+ * 173 capabilities declare the same `InternalServerError`, and all of them bottom out in
+ * one `ErrorResponse` schema — so including them multiplies a search payload by 6.4x to
+ * repeat boilerplate the caller learns from the actual failure anyway. The 2xx entry is the
+ * one that says what a successful call returns, which is what a caller needs BEFORE calling.
+ *
+ * Returns undefined when the capability declares none — which is every capability in an
+ * index built before the response tables were added, and is not an error.
+ */
+export declare function resolveResponses(product: ProductIndex, capability: Capability, selection?: ResponseSelection): Record<string, ResponseDoc> | undefined;

package/dist/tools/capability-registry/index-loader.js

@@ -0,0 +1,523 @@
+/**
+ * Load the index artifact(s) and expose the lookups the tools need.
+ *
+ * ONE FILE PER PRODUCT is the released contract, so loading is a merge across files. The
+ * merged model keeps the products map the rest of the server already reads, which is what
+ * lets searchCapability rank across products from N single-product files.
+ */
+import { readFileSync } from "node:fs";
+import { basename, dirname } from "node:path";
+import { ENVELOPE_KEYS, SUPPORTED_SCHEMA_VERSION, } from "./types.js";
+export class IndexError extends Error {
+}
+/** Thrown to the caller as a tool error, so the wording is caller-facing. */
+export class InvocationError extends Error {
+}
+/** The file inside a product subdirectory, for the earlier nested layout. */
+export const INDEX_FILE = "index.json";
+/** The stored layout, and the name the export publishes: `<product>.capability-index.json`. */
+export const FLAT_SUFFIX = ".capability-index.json";
+/**
+ * The product a file's LOCATION claims to describe, if its layout says so.
+ *
+ * `capability/tm.capability-index.json` and `capability/tm/index.json` both name their
+ * product, and
+ * `fromFiles` cross-checks that against the product key inside. A file in the wrong place
+ * would otherwise register its product under the directory's name and answer for endpoints
+ * it does not have.
+ */
+export function productFromPath(file) {
+    const base = basename(file);
+    if (base.endsWith(FLAT_SUFFIX))
+        return base.slice(0, -FLAT_SUFFIX.length);
+    if (base === INDEX_FILE)
+        return basename(dirname(file));
+    return undefined;
+}
+export function endpointKey(method, path) {
+    return `${(method || "").trim().toUpperCase()} ${(path || "").trim()}`;
+}
+/**
+ * Is this capability withheld from the surface?
+ *
+ * FAILS CLOSED: any truthy `disabled` hides it, not just `=== true`. The flag exists to
+ * suppress something that cannot work, so an unexpected shape must hide it rather than be
+ * ignored — the opposite default would turn a typo into a silently re-enabled capability.
+ */
+export function isDisabled(capability) {
+    return Boolean(capability.disabled);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Read one artifact file into the product it carries.
+ *
+ * SHAPE DETECTION, NOT VERSION DETECTION. The released envelope and the pre-release one
+ * both declare `schema_version: 1`, so the number cannot tell them apart; the `products`
+ * wrapper can, and is the documented discriminator. The pre-release branch is defensive
+ * only — that shape was never deployed.
+ */
+export function readIndexFile(raw, source = "index") {
+    if (!isPlainObject(raw)) {
+        throw new IndexError(`${source}: expected a JSON object`);
+    }
+    if (raw.schema_version !== SUPPORTED_SCHEMA_VERSION) {
+        // Refuse rather than best-effort read: a shape change the generator announced is
+        // exactly the case where guessing produces silently wrong tool output.
+        throw new IndexError(`${source}: unsupported index schema_version ${raw.schema_version}; this build reads ` +
+            `${SUPPORTED_SCHEMA_VERSION}. Rebuild the artifact or update the server.`);
+    }
+    const provenance = {
+        build_id: typeof raw.build_id === "string" ? raw.build_id : "",
+        ...(typeof raw.version === "string" ? { version: raw.version } : {}),
+    };
+    if (isPlainObject(raw.products)) {
+        // Pre-release shape. Never deployed; recognised so a stray file reads rather than
+        // failing in a way that looks like a corrupt artifact.
+        const entries = Object.entries(raw.products);
+        if (entries.length === 0)
+            throw new IndexError(`${source}: contains no products`);
+        if (entries.length > 1) {
+            throw new IndexError(`${source}: carries ${entries.length} products; one file describes one product`);
+        }
+        const [name, product] = entries[0];
+        return {
+            name,
+            product: asProduct(product, `${source}:${name}`),
+            provenance,
+        };
+    }
+    // Released shape: exactly one key that is not part of the envelope.
+    const envelope = new Set(ENVELOPE_KEYS);
+    const entries = Object.entries(raw).filter(([key, value]) => !envelope.has(key) && isPlainObject(value));
+    if (entries.length === 0) {
+        throw new IndexError(`${source}: no product object found; expected one top-level key besides ` +
+            `${[...envelope].join(", ")}`);
+    }
+    if (entries.length > 1) {
+        throw new IndexError(`${source}: found ${entries.length} candidate product keys ` +
+            `(${entries
+                .map(([key]) => key)
+                .sort()
+                .join(", ")}); one file describes one product`);
+    }
+    const [name, product] = entries[0];
+    return { name, product: asProduct(product, `${source}:${name}`), provenance };
+}
+function asProduct(value, source) {
+    if (!isPlainObject(value) || !Array.isArray(value.capabilities)) {
+        throw new IndexError(`${source}: product object has no capabilities[]`);
+    }
+    return value;
+}
+/**
+ * Remove withheld names from `entities[*].capabilities[]`.
+ *
+ * describeEntity returns the entity doc WHOLESALE (`{ ...doc }`), so a name left here is a
+ * name the caller sees, looks up, and cannot invoke — the surface would be advertising the
+ * capability in the one place that is not a search result.
+ *
+ * An entity whose list empties is KEPT, not dropped. It still describes a real thing the
+ * product models — its id convention, its relations and its key facts remain true and are
+ * what a caller resolving an id actually needs — and removing entities would change what
+ * listProducts routes on. No tm entity empties today (attachment keeps 4 of 7, dataset 7
+ * of 8); this is the rule for when one does.
+ */
+function stripDisabledFromEntities(bundle, withheld) {
+    const entities = {};
+    for (const [entity, doc] of Object.entries(bundle.entities || {})) {
+        const listed = doc?.capabilities;
+        if (!Array.isArray(listed)) {
+            entities[entity] = doc;
+            continue;
+        }
+        const kept = listed.filter((name) => typeof name !== "string" || !withheld.has(name));
+        entities[entity] =
+            kept.length === listed.length ? doc : { ...doc, capabilities: kept };
+    }
+    return entities;
+}
+export class CapabilityRegistry {
+    index;
+    /** product -> provenance of the file it came from. */
+    provenance;
+    /** product -> "METHOD /path" -> capability */
+    byEndpoint = new Map();
+    /** product -> capability name -> capability. Empty for products that publish no names. */
+    byName = new Map();
+    /**
+     * product -> name AND "METHOD /path" -> the capability that flag withheld.
+     *
+     * Kept only so an invoke against a handle the caller already holds can say
+     * `capability_disabled` instead of `unknown_capability`. Nothing else reads it, and it
+     * is deliberately not reachable from `index`.
+     */
+    withheld = new Map();
+    constructor(index, provenance = {}) {
+        if (index?.schema_version !== SUPPORTED_SCHEMA_VERSION) {
+            throw new IndexError(`unsupported index schema_version ${index?.schema_version}; this build reads ` +
+                `${SUPPORTED_SCHEMA_VERSION}. Rebuild the artifact or update the server.`);
+        }
+        if (!index.products || Object.keys(index.products).length === 0) {
+            throw new IndexError("index contains no products");
+        }
+        this.provenance = provenance;
+        // DISABLED CAPABILITIES ARE REMOVED HERE, ONCE, and never reach the rest of the server.
+        //
+        // The alternative — a `disabled` check at each read site — was rejected: there are four
+        // readers of `bundle.capabilities` today (three in search, one in discovery) plus the
+        // entity docs, and the cost of a missed one is a capability that is hidden from search
+        // and still invokable, which is the exact failure the flag exists to prevent. Filtering
+        // the model itself makes the invariant structural instead of remembered.
+        const products = {};
+        for (const [product, bundle] of Object.entries(index.products)) {
+            const lookup = new Map();
+            const names = new Map();
+            const withheld = new Map();
+            const enabled = [];
+            for (const capability of bundle.capabilities) {
+                // UNIQUENESS IS CHECKED OVER EVERY CAPABILITY, disabled ones included. A clash
+                // between a disabled name and a live one is still a broken artifact, and skipping
+                // the disabled half would mean re-enabling the flag could fail the load later,
+                // somewhere with less context than here.
+                if (isDisabled(capability)) {
+                    withheld.set(endpointKey(capability.method, capability.path), capability);
+                    if (capability.name)
+                        withheld.set(capability.name, capability);
+                }
+                else {
+                    enabled.push(capability);
+                    lookup.set(endpointKey(capability.method, capability.path), capability);
+                }
+                if (!capability.name)
+                    continue;
+                const clash = names.get(capability.name);
+                if (clash) {
+                    // A duplicate name makes one of the two permanently unreachable, and which one
+                    // wins would depend on array order. The export gates this, but a hand-edited or
+                    // stale artifact must not load and then silently drop an endpoint.
+                    throw new IndexError(`${product}: capability name '${capability.name}' is used by both ` +
+                        `${endpointKey(clash.method, clash.path)} and ` +
+                        `${endpointKey(capability.method, capability.path)}; names must be unique ` +
+                        `within a product`);
+                }
+                if (!isDisabled(capability))
+                    names.set(capability.name, capability);
+            }
+            this.byEndpoint.set(product, lookup);
+            this.byName.set(product, names);
+            this.withheld.set(product, withheld);
+            products[product] = withheld.size
+                ? {
+                    ...bundle,
+                    capabilities: enabled,
+                    entities: stripDisabledFromEntities(bundle, withheld),
+                }
+                : bundle;
+        }
+        this.index = { ...index, products };
+    }
+    /**
+     * The `capability_disabled` message for a handle this build withholds, if it is one.
+     *
+     * Says THAT it is disabled and nothing about why. The reason is documentation and lives
+     * with the decision; repeating it here would put four copies of a paragraph in the
+     * shipped artifact to serve a path the flag itself makes rare.
+     *
+     * Returns undefined for anything else, so the caller falls through to its own
+     * not-found wording.
+     */
+    withheldMatch(handle, product) {
+        for (const [owner, withheld] of this.withheld) {
+            if (product && owner !== product)
+                continue;
+            if (!withheld.has(handle))
+                continue;
+            return (`capability_disabled: ${handle} is disabled on this surface. This is ` +
+                `deliberate — it is withheld by the ${owner} index, not missing from it — so ` +
+                `retrying will not help.`);
+        }
+        return undefined;
+    }
+    /** How many capabilities each product withholds. Startup logging only. */
+    disabledCounts() {
+        const out = {};
+        for (const [product, withheld] of this.withheld) {
+            // Each capability is keyed twice when it has a name — by endpoint and by name.
+            const distinct = new Set(withheld.values());
+            if (distinct.size)
+                out[product] = distinct.size;
+        }
+        return out;
+    }
+    static fromFile(file) {
+        return CapabilityRegistry.fromFiles([file]);
+    }
+    /**
+     * Merge every discovered artifact into one registry.
+     *
+     * ANY unreadable file fails the whole load, deliberately. Skipping one and carrying on
+     * would leave a registry that answers "no such capability" for a product that exists —
+     * a confident wrong answer, which is worse than the caller-visible absence of the whole
+     * surface (which `register.ts` logs a reason for).
+     */
+    static fromFiles(files) {
+        if (files.length === 0)
+            throw new IndexError("no index files to load");
+        const products = {};
+        const provenance = {};
+        for (const file of files) {
+            let parsed;
+            try {
+                parsed = JSON.parse(readFileSync(file, "utf8"));
+            }
+            catch (error) {
+                throw new IndexError(`${file}: could not be read as JSON (${error instanceof Error ? error.message : String(error)})`);
+            }
+            const loaded = readIndexFile(parsed, file);
+            const claimed = productFromPath(file);
+            if (claimed && claimed !== loaded.name) {
+                // The name is stated twice — by the path and by the key inside — and they must
+                // agree. Trusting either one alone would serve a product's endpoints under the
+                // other's name, and every search result would then point at the wrong host.
+                throw new IndexError(`${file}: is stored as product '${claimed}' but declares '${loaded.name}'`);
+            }
+            if (products[loaded.name]) {
+                // Two files claiming one product cannot both be right, and picking one silently
+                // decides which endpoints exist.
+                throw new IndexError(`product '${loaded.name}' is declared by more than one index file; ${file} is a duplicate`);
+            }
+            products[loaded.name] = loaded.product;
+            provenance[loaded.name] = loaded.provenance;
+        }
+        return new CapabilityRegistry({
+            schema_version: SUPPORTED_SCHEMA_VERSION,
+            build_id: compositeBuildId(provenance),
+            products,
+        }, provenance);
+    }
+    /** The single product's build id, or `name:id` pairs when several are loaded. */
+    get buildId() {
+        return this.index.build_id;
+    }
+    productNames() {
+        return Object.keys(this.index.products).sort();
+    }
+    /** Per-product `{build_id, version}`, for logging and cache-busting only. */
+    buildInfo() {
+        return this.provenance;
+    }
+    /**
+     * Find a capability by its published name — the preferred handle.
+     *
+     * Names are unique within a product but not across products, so an ambiguous name is
+     * reported rather than resolved by load order. A name that exists in no index is
+     * `unknown_capability`: a distinct outcome from a name that exists elsewhere, because the
+     * caller's next move differs — search again, versus pass `product`.
+     */
+    byNameLookup(name, product) {
+        const matches = [];
+        for (const [owner, lookup] of this.byName) {
+            if (product && owner !== product)
+                continue;
+            const capability = lookup.get(name);
+            if (capability)
+                matches.push({ product: owner, capability });
+        }
+        if (matches.length === 0) {
+            // WITHHELD IS A DIFFERENT ANSWER FROM ABSENT, and only here. Search cannot surface a
+            // disabled capability, so reaching this branch means the caller already held the
+            // exact handle — from an older index, a doc, or a human. "unknown_capability" would
+            // send it hunting for a synonym that does not exist; the reason ends the attempt.
+            const off = this.withheldMatch(name, product);
+            if (off)
+                throw new InvocationError(off);
+            // Say whether names are published at all for the product asked about: "no such name"
+            // and "this product does not name its capabilities" need different fixes.
+            const unnamed = [...this.byName]
+                .filter(([owner, lookup]) => (!product || owner === product) && lookup.size === 0)
+                .map(([owner]) => owner);
+            const hint = unnamed.length
+                ? ` ${unnamed.sort().join(", ")} ${unnamed.length > 1 ? "publish" : "publishes"} ` +
+                    `no capability names yet — call those by \`method\` and \`path\` instead.`
+                : " Search again — names come from searchCapability and describeEntity.";
+            throw new InvocationError(`unknown_capability: ${name}.${hint}`);
+        }
+        if (matches.length > 1 && !product) {
+            const owners = matches
+                .map((m) => m.product)
+                .sort()
+                .join(", ");
+            throw new InvocationError(`capability name '${name}' exists in several products (${owners}); pass product`);
+        }
+        return matches[0];
+    }
+    /**
+     * Find a capability by the endpoint it exposes — the handle for unnamed products.
+     *
+     * The endpoint is what searchCapability returns, so it is the only thing a caller can
+     * hold. `unknown_endpoint` is a defined outcome rather than a generic failure: a caller
+     * working from stale search output needs to know to search again, not to retry.
+     */
+    byEndpointLookup(method, path, product) {
+        const key = endpointKey(method, path);
+        const matches = [];
+        for (const [name, lookup] of this.byEndpoint) {
+            if (product && name !== product)
+                continue;
+            const capability = lookup.get(key);
+            if (capability)
+                matches.push({ product: name, capability });
+        }
+        if (matches.length === 0) {
+            const off = this.withheldMatch(key, product);
+            if (off)
+                throw new InvocationError(off);
+            throw new InvocationError(`unknown_endpoint: ${key}. Search again — send \`method\` and \`path\` exactly as ` +
+                `searchCapability returned them, placeholders included.`);
+        }
+        if (matches.length > 1 && !product) {
+            const owners = matches
+                .map((m) => m.product)
+                .sort()
+                .join(", ");
+            throw new InvocationError(`${key} exists in several products (${owners}); pass product`);
+        }
+        return matches[0];
+    }
+}
+function compositeBuildId(provenance) {
+    const names = Object.keys(provenance).sort();
+    if (names.length === 1)
+        return provenance[names[0]].build_id;
+    return names.map((name) => `${name}:${provenance[name].build_id}`).join(" ");
+}
+/**
+ * Resolve a `{$response|$schema: "Name"}` reference against the product's lookup tables.
+ *
+ * ONE HOP. The named component it returns may itself contain references — 39 of tm's 53
+ * named responses do — so this is the primitive, not the whole job. Use `resolveResponses`
+ * to get a tree with nothing left to look up.
+ *
+ * A node that is not a reference is returned as-is, and an unresolvable name yields
+ * `undefined` rather than throwing: the tables are additive and their absence means "no
+ * response schema available".
+ */
+export function resolveComponent(product, node) {
+    if (!node || typeof node !== "object")
+        return node;
+    const ref = node;
+    if (typeof ref.$response === "string") {
+        return product.responses?.[ref.$response];
+    }
+    if (typeof ref.$schema === "string") {
+        return product.schemas?.[ref.$schema];
+    }
+    return node;
+}
+/**
+ * Resolve every reference in a tree, however deep.
+ *
+ * REFERENCES ARE NESTED, which is the part a one-hop reader gets wrong. They appear at the
+ * top of a response (`{"$response": "BadRequest"}`), on its schema
+ * (`.../schema/{"$schema": "TestCaseListResponse"}`), and inside the schema's own
+ * properties (`.../schema/properties/data/properties/folder`). Chains are real too: a
+ * capability's 400 resolves to the named `BadRequest`, whose schema is `{"$schema":
+ * "ErrorResponse"}`.
+ *
+ * AN UNRESOLVABLE REFERENCE IS LEFT IN PLACE, not dropped and not thrown on. A dangling
+ * name (the tables are built separately from the capabilities) or a cycle (a folder whose
+ * schema contains folders) then shows up as the `{"$schema": "…"}` node it is, which a
+ * reader can still act on, rather than as a silently truncated schema.
+ */
+export function resolveDeep(product, node) {
+    return resolveNode(product, node, new Set());
+}
+function resolveNode(product, node, seen) {
+    if (Array.isArray(node)) {
+        return node.map((item) => resolveNode(product, item, seen));
+    }
+    if (typeof node !== "object" || node === null)
+        return node;
+    const ref = node;
+    const kind = typeof ref.$response === "string"
+        ? "$response"
+        : typeof ref.$schema === "string"
+            ? "$schema"
+            : undefined;
+    if (kind) {
+        const name = (kind === "$response" ? ref.$response : ref.$schema);
+        const key = `${kind}:${name}`;
+        const target = kind === "$response"
+            ? product.responses?.[name]
+            : product.schemas?.[name];
+        // Leave the reference visible when it cannot be followed, or when following it would
+        // revisit a name already on this path.
+        if (!target || seen.has(key))
+            return node;
+        const resolved = resolveNode(product, target, new Set([...seen, key]));
+        // KEYS WRITTEN BESIDE THE REF SURVIVE IT, AND WIN.
+        //
+        // This used to return the target and drop every sibling, which silently ate 16 nodes
+        // in the shipped tm index: 14 authored descriptions and two `nullable: true` flags.
+        // The losses are exactly the caveats hardest to rediscover — "only when no step
+        // results were submitted", "Present only on root-folder creation", and a `nullable`
+        // marking the one field that comes back NULL when a search fails, which is the
+        // absent-versus-explicitly-null distinction a caller cannot otherwise make.
+        //
+        // It also cost real work downstream. A live probe reported one of those caveats as a
+        // missing conditional and it had been written all along — this resolver removed it
+        // between the author and the caller. Worse, the product team began splitting shared
+        // schemas so a caveat would have somewhere to live that survived, trading a lost
+        // sentence for two descriptions of one serializer that then drift apart.
+        //
+        // SIBLINGS WIN over the resolved target, not the reverse. A description written at the
+        // reference site is about THAT usage — "only when no step results were submitted" is
+        // true of one consumer of TestResult, not of TestResult everywhere — which is the
+        // whole reason it was written beside the ref instead of on the schema.
+        const siblings = {};
+        for (const [field, value] of Object.entries(node)) {
+            if (field !== "$schema" && field !== "$response")
+                siblings[field] = value;
+        }
+        if (Object.keys(siblings).length === 0)
+            return resolved;
+        if (typeof resolved !== "object" ||
+            resolved === null ||
+            Array.isArray(resolved)) {
+            return resolved;
+        }
+        return {
+            ...resolved,
+            ...resolveNode(product, siblings, seen),
+        };
+    }
+    const out = {};
+    for (const [field, value] of Object.entries(node)) {
+        out[field] = resolveNode(product, value, seen);
+    }
+    return out;
+}
+/**
+ * A capability's declared responses with every reference followed.
+ *
+ * SUCCESS ONLY BY DEFAULT. The error entries are near-identical across the surface — 148 of
+ * 173 capabilities declare the same `InternalServerError`, and all of them bottom out in
+ * one `ErrorResponse` schema — so including them multiplies a search payload by 6.4x to
+ * repeat boilerplate the caller learns from the actual failure anyway. The 2xx entry is the
+ * one that says what a successful call returns, which is what a caller needs BEFORE calling.
+ *
+ * Returns undefined when the capability declares none — which is every capability in an
+ * index built before the response tables were added, and is not an error.
+ */
+export function resolveResponses(product, capability, selection = "success") {
+    if (selection === "none" || !capability.responses)
+        return undefined;
+    const wanted = selection === "all"
+        ? Object.entries(capability.responses)
+        : Object.entries(capability.responses).filter(([status]) => status.startsWith("2"));
+    if (wanted.length === 0)
+        return undefined;
+    return resolveDeep(product, Object.fromEntries(wanted));
+}