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

package/dist/tools/capability-registry/bind.js

@@ -0,0 +1,407 @@
+/**
+ * Turn grouped caller arguments into a path, a query and a body.
+ *
+ * Arguments arrive GROUPED — {path_params, query, body} — because spec parameter names
+ * collide across locations: four tm operations declare one name in two places (`bulk-move`
+ * has `folder_id` as both a path parameter and a body field). A flat map cannot say which
+ * one is meant, which is exactly why the Python side used to rename body fields `body_*`.
+ * Grouping removes the collision AND the rename, so a caller sends the spec's own names.
+ */
+import { InvocationError } from "./index-loader.js";
+/**
+ * String formats worth ENFORCING, as opposed to merely publishing.
+ *
+ * A validator that rejects a correct value is worse than no validator: the caller cannot
+ * route around it, and the request that would have worked never leaves. So this covers only
+ * the formats where "wrong" is unambiguous and a legitimate value cannot trip it.
+ *
+ * tm declares eight formats. `date`, `date-time` and `uuid` are here. `email` and `uri` are
+ * deliberately NOT — every compact regex for either rejects addresses and URLs that servers
+ * accept, and being wrong in that direction blocks real work. `int64`, `float` and `binary`
+ * say what a number or blob is, which `type` already covers.
+ */
+const FORMATS = {
+    date: {
+        // A real calendar date, so 2026-02-31 fails rather than being reformatted.
+        test: (v) => /^\d{4}-\d{2}-\d{2}$/.test(v) &&
+            !Number.isNaN(Date.parse(`${v}T00:00:00Z`)) &&
+            new Date(`${v}T00:00:00Z`).toISOString().startsWith(v),
+        want: "a date (YYYY-MM-DD)",
+    },
+    "date-time": {
+        // Permissive on purpose: offset or Z, optional fractional seconds. Tightening this
+        // buys nothing and starts rejecting timestamps the product would have taken.
+        test: (v) => /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:?\d{2})?$/.test(v) && !Number.isNaN(Date.parse(v)),
+        want: "a date-time (e.g. 2026-01-31T09:30:00Z)",
+    },
+    uuid: {
+        test: (v) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(v),
+        want: "a UUID",
+    },
+};
+/**
+ * A declared `pattern`, compiled once, or undefined if it will not compile here.
+ *
+ * `u` because tm's patterns use `\p{L}`/`\p{N}`, which are a syntax error without it. A
+ * pattern this engine cannot compile is SKIPPED rather than thrown: the index is generated
+ * from someone else's spec, and refusing to invoke a working endpoint because its regex
+ * dialect differs would be our bug landing on the caller.
+ */
+const patternCache = new Map();
+function compiled(pattern) {
+    if (!patternCache.has(pattern)) {
+        let regex;
+        try {
+            regex = new RegExp(pattern, "u");
+        }
+        catch {
+            try {
+                regex = new RegExp(pattern);
+            }
+            catch {
+                regex = undefined;
+            }
+        }
+        patternCache.set(pattern, regex);
+    }
+    return patternCache.get(pattern);
+}
+/**
+ * Every constraint the parameter declares, checked against the COERCED value.
+ *
+ * Runs inside `bind`, which register.ts calls dry before the write-consent gate — so a
+ * value that breaks a constraint is refused before the user is asked to approve anything,
+ * and nothing reaches egress.
+ *
+ * `label` carries the parent name for a nested field, so the message names `test_case.name`
+ * rather than a bare `name` the caller would have to go looking for.
+ */
+function checkConstraints(value, param, label = param.name) {
+    const fail = (what) => {
+        throw new InvocationError(`'${label}' ${what}`);
+    };
+    if (typeof value === "number") {
+        if (param.minimum !== undefined && value < param.minimum)
+            fail(`must be at least ${param.minimum}`);
+        if (param.maximum !== undefined && value > param.maximum)
+            fail(`must be at most ${param.maximum}`);
+        if (param.multipleOf !== undefined && param.multipleOf > 0) {
+            // Scale BOTH to integers before the modulo: 0.3 % 0.1 is 0.09999… in binary floating
+            // point and would reject a value the product accepts. The scale has to cover the
+            // value's decimals as well as the step's — scaling by the step alone rounds 0.25 to
+            // 3 against a step of 1, which then divides evenly and lets a bad value through.
+            const scale = 10 ** Math.max(decimals(param.multipleOf), decimals(value));
+            if (Math.round(value * scale) % Math.round(param.multipleOf * scale) !==
+                0)
+                fail(`must be a multiple of ${param.multipleOf}`);
+        }
+    }
+    if (typeof value === "string") {
+        if (param.minLength !== undefined && value.length < param.minLength)
+            fail(`must be at least ${param.minLength} character(s)`);
+        if (param.maxLength !== undefined && value.length > param.maxLength)
+            fail(`must be at most ${param.maxLength} character(s)`);
+        if (param.pattern) {
+            const regex = compiled(param.pattern);
+            if (regex && !regex.test(value))
+                fail(`must match ${param.pattern}`);
+        }
+        const format = param.format ? FORMATS[param.format] : undefined;
+        if (format && !format.test(value))
+            fail(`must be ${format.want}`);
+    }
+    if (Array.isArray(value)) {
+        if (param.minItems !== undefined && value.length < param.minItems)
+            fail(`must have at least ${param.minItems} item(s)`);
+        if (param.maxItems !== undefined && value.length > param.maxItems)
+            fail(`must have at most ${param.maxItems} item(s)`);
+        if (param.uniqueItems) {
+            const seen = new Set(value.map((item) => JSON.stringify(item)));
+            if (seen.size !== value.length)
+                fail("must not contain duplicate items");
+        }
+    }
+}
+/** Decimal places, for scaling `multipleOf` out of floating point. */
+function decimals(n) {
+    const text = String(n);
+    const dot = text.indexOf(".");
+    return dot < 0 ? 0 : text.length - dot - 1;
+}
+/**
+ * The declared fields one level inside an object, or inside each item of an array.
+ *
+ * Only what `fields` names is checked, and an undeclared key is left alone — `fields` is a
+ * projection of the shape, not a closed contract, so rejecting the rest would refuse valid
+ * bodies. That is the opposite of the top level, where the full parameter list IS known and
+ * an unknown name is an error.
+ */
+function checkFields(value, param) {
+    if (!param.fields?.length)
+        return;
+    const items = Array.isArray(value) ? value : [value];
+    for (const item of items) {
+        if (typeof item !== "object" || item === null || Array.isArray(item))
+            continue;
+        const record = item;
+        for (const field of param.fields) {
+            if (!(field.name in record)) {
+                if (field.required)
+                    throw new InvocationError(`missing required parameter(s): ${param.name}.${field.name}`);
+                continue;
+            }
+            const label = `${param.name}.${field.name}`;
+            const coerced = coerceType(record[field.name], field, label);
+            checkConstraints(coerced, field, label);
+        }
+    }
+}
+/**
+ * One path value, checked for the segments that silently retarget the request.
+ *
+ * `encodeURIComponent` does NOT escape a dot, and `new URL()` in egress resolves `.` and
+ * `..` the way a filesystem would. So a string path parameter carrying `..` walks up a
+ * segment and the call lands somewhere else entirely:
+ *
+ *     update_test_case { project_id: "PR-1", test_case_id: ".." }
+ *       -> PATCH /api/v2/projects/PR-1/            (the PROJECT, not a test case)
+ *
+ * That is worse than a failed call. The human approved "update this test case" and gave a
+ * change_summary saying so, and the request edits a different resource — with the approval
+ * already banked. A prompt injection sitting in test-case content is enough to steer an
+ * agent into it.
+ *
+ * Empty and `.` are refused for the same reason: both collapse the segment and leave the
+ * request pointing at the collection.
+ *
+ * TYPE CHECKING IS NOT THE DEFENCE HERE, though a comment used to claim it was. It holds
+ * only for `type: integer` ids; eleven enabled capabilities take a STRING path parameter
+ * with no pattern, enum or format, and every one of those values reaches the URL as given.
+ */
+function pathSegment(value, name) {
+    const text = String(value);
+    const trimmed = text.trim();
+    if (trimmed === "" || trimmed === "." || trimmed === "..") {
+        throw new InvocationError(`'${name}' is not a usable path value: ${JSON.stringify(text)} would ` +
+            `retarget the request at a different resource rather than identify one. ` +
+            `Pass the id exactly as a read returned it.`);
+    }
+    return text;
+}
+/**
+ * Check one argument against its declared schema, raising a caller-safe error.
+ *
+ * For path parameters this is only half the defence — see `pathSegment`, which covers the
+ * string ids that carry no type constraint worth the name.
+ */
+export function coerce(value, param) {
+    const coerced = coerceType(value, param);
+    checkConstraints(coerced, param);
+    checkFields(coerced, param);
+    return coerced;
+}
+function coerceType(value, param, label = param.name) {
+    const expected = param.type;
+    if (expected === "object" || expected === "array") {
+        // An opaque body object is passed through as given: the spec does not describe its
+        // fields, so validating or reshaping it would mean inventing a contract.
+        if (expected === "object" &&
+            (typeof value !== "object" || value === null || Array.isArray(value))) {
+            throw new InvocationError(`'${label}' must be an object`);
+        }
+        if (expected === "array" && !Array.isArray(value)) {
+            throw new InvocationError(`'${label}' must be a list`);
+        }
+        return value;
+    }
+    if (expected === "integer" || expected === "number") {
+        // `Number("")` and `Number(" ")` are both 0, so a blank id silently became id 0 and the
+        // call went to whatever that resolves to. Refuse instead of inventing a value.
+        const raw = String(value).trim();
+        if (raw === "") {
+            throw new InvocationError(`'${label}' must be a number, and was empty`);
+        }
+        const parsed = Number(raw);
+        if (!Number.isFinite(parsed)) {
+            throw new InvocationError(`'${label}' must be a number`);
+        }
+        // `Math.trunc` turned "1.9" into 1 without a word. An id is either an integer or it is
+        // the wrong id, and quietly rounding it addresses the wrong record.
+        if (expected === "integer" && !Number.isInteger(parsed)) {
+            throw new InvocationError(`'${label}' must be a whole number, not ${JSON.stringify(raw)}`);
+        }
+        // Past 2^53 `Number` rounds: TRA's 17-digit unique-error cluster ids came back as a
+        // neighbouring id, so the call silently targeted the wrong cluster. Keep the caller's
+        // exact digits instead — path and query serialise a string identically, and a JSON body
+        // carrying a digit string still binds to a Long on the server.
+        if (expected === "integer" &&
+            !Number.isSafeInteger(parsed) &&
+            /^-?\d+$/.test(raw)) {
+            return raw;
+        }
+        return parsed;
+    }
+    if (expected === "boolean") {
+        if (typeof value === "boolean")
+            return value;
+        const text = String(value).trim().toLowerCase();
+        if (["true", "1", "yes"].includes(text))
+            return true;
+        if (["false", "0", "no"].includes(text))
+            return false;
+        throw new InvocationError(`'${label}' must be true or false`);
+    }
+    // NO DECLARED TYPE: pass the value through as given.
+    //
+    // The fallthrough below is String(value), which is right for a declared string and
+    // silently destructive for anything the spec left untyped. create_report declares
+    // `mail_to` and `report_filters` with no type and the API wants objects for both, so a
+    // correct payload was serialised to the literal "[object Object]" and refused:
+    //
+    //   The property '#/mail_to' of type string did not match the following type: object
+    //
+    // The caller sent the right thing, this layer broke it, and the server's message blames
+    // the caller for a string it never wrote. An untyped parameter means the spec declines to
+    // say what shape it is — which is a reason to leave it alone, not to guess "string".
+    const untyped = !expected;
+    if (untyped && (typeof value === "object" || typeof value === "boolean")) {
+        return value;
+    }
+    const text = String(value);
+    if (param.values && param.values.length > 0) {
+        const allowed = param.values.map((v) => String(v));
+        if (!allowed.includes(text)) {
+            throw new InvocationError(`'${label}' must be one of: ${allowed.join(", ")}`);
+        }
+    }
+    return text;
+}
+/** Place a value at a JSON-pointer-ish path, creating the objects on the way. */
+function place(root, pointer, value) {
+    const segments = pointer.split("/").filter((segment) => segment !== "");
+    let cursor = root;
+    for (const segment of segments.slice(0, -1)) {
+        const next = cursor[segment];
+        if (typeof next !== "object" || next === null || Array.isArray(next)) {
+            cursor[segment] = {};
+        }
+        cursor = cursor[segment];
+    }
+    cursor[segments[segments.length - 1]] = value;
+}
+const MAP_KEY = /^[A-Za-z0-9][\w.-]*$/;
+function keyedParam(group, params) {
+    if (group !== "body")
+        return undefined;
+    return params.find((param) => /^\{\w+\}$/.test(param.name));
+}
+const GROUPS = [
+    { group: "path_params", declared: "path_params" },
+    { group: "query", declared: "query" },
+    { group: "body", declared: "body" },
+];
+export function bind(capability, args) {
+    let path = capability.path;
+    const query = {};
+    const body = {};
+    for (const { group, declared } of GROUPS) {
+        const supplied = args[group] || {};
+        if (typeof supplied !== "object" ||
+            supplied === null ||
+            Array.isArray(supplied)) {
+            throw new InvocationError(`${group} must be an object of name -> value`);
+        }
+        const params = capability[declared] || [];
+        const byName = new Map(params.map((param) => [param.name, param]));
+        const keyed = keyedParam(group, params);
+        // Unknown arguments are an error rather than being dropped: silently ignoring a
+        // misspelled filter would return a larger result set that looks like a correct answer.
+        const unknown = Object.keys(supplied).filter((name) => !byName.has(name) && !keyed);
+        if (unknown.length > 0) {
+            // A CALLER WHO SENT THE WRAPPER WE BUILD DESERVES TO BE TOLD SO.
+            //
+            // Most of these endpoints want a nested body — Rails `params.require(:test_case)` —
+            // and the fields declare that as `json_path: /test_case/name`, so this layer
+            // assembles the wrapper itself and the caller sends the fields flat. A caller who
+            // wraps it by hand therefore sends a key that is never a declared param, and the
+            // bare message reads as "that field does not exist" when the truth is the opposite:
+            // it exists, and building it is our job.
+            //
+            // Worth special-casing because the guidance itself has been telling callers to wrap:
+            // 25 tm capabilities carried a line describing the WIRE format to a caller who never
+            // writes the wire. Those lines are being corrected, but an agent working from an
+            // older artifact, or reasoning from the Rails convention, lands here either way.
+            const wrappers = new Set(params
+                .map((param) => param.json_path)
+                .filter((path) => Boolean(path))
+                .map((path) => path.replace(/^\//, "").split("/")[0])
+                .filter((segment) => segment && !byName.has(segment)));
+            const sentAWrapper = unknown.filter((name) => wrappers.has(name));
+            throw new InvocationError(`unknown ${group}: ${unknown.sort().join(", ")}. accepted: ` +
+                `${[...byName.keys()].sort().join(", ") || "none"}` +
+                (sentAWrapper.length > 0
+                    ? `. ${sentAWrapper.sort().join(" and ")} ` +
+                        `${sentAWrapper.length > 1 ? "are wrappers" : "is a wrapper"} this ` +
+                        `surface builds for you from each field's json_path — send the fields ` +
+                        `directly instead of nesting them`
+                    : ""));
+        }
+        for (const [name, raw] of Object.entries(supplied)) {
+            const param = byName.get(name) ?? keyed;
+            if (param === keyed && !MAP_KEY.test(name)) {
+                throw new InvocationError(`'${name}' is not a usable ${keyed.name} key: use the id exactly as a read returned it`);
+            }
+            const value = coerce(raw, param);
+            if (group === "path_params") {
+                // Encode with nothing exempt: a `/` inside a path value would otherwise rewrite the
+                // route. Schema checking already stops this for integer ids; this covers strings.
+                path = path.replaceAll(`{${name}}`, encodeURIComponent(pathSegment(value, name)));
+            }
+            else if (group === "body") {
+                const pointer = param.json_path || `/${param.name}`;
+                place(body, param === keyed && !byName.has(name)
+                    ? pointer.replace(keyed.name, name)
+                    : pointer, value);
+            }
+            else {
+                query[name] = value;
+            }
+        }
+    }
+    // `required` is enforced for BODY as well as path. It was path-only on the Python side at
+    // first, so a missing required body field passed silently and the product answered with a
+    // 4xx that read like the caller's fault.
+    const missing = [];
+    for (const { group, declared } of GROUPS) {
+        if (group === "query")
+            continue;
+        const supplied = args[group] || {};
+        const params = capability[declared] || [];
+        const keyed = keyedParam(group, params);
+        const declaredNames = new Set(params.map((param) => param.name));
+        for (const param of params) {
+            const present = param.name in supplied ||
+                (param === keyed &&
+                    Object.keys(supplied).some((name) => !declaredNames.has(name)));
+            if (param.required && !present)
+                missing.push(param.name);
+        }
+    }
+    if (missing.length > 0) {
+        throw new InvocationError(`missing required parameter(s): ${missing.sort().join(", ")}`);
+    }
+    const leftover = path.match(/\{[a-z_]+\}/gi);
+    if (leftover) {
+        throw new InvocationError(`path placeholder(s) not supplied: ${leftover.join(", ")}`);
+    }
+    // An explicitly supplied empty body is still a body. Dropping it sent no request body at
+    // all, and a route with a required @RequestBody (TRA close_build, whose guidance says to
+    // send `{}`) answered 400 "Invalid request payload". GET/HEAD never carry one.
+    const sentEmptyBody = args.body !== undefined &&
+        !["GET", "HEAD"].includes(capability.method.toUpperCase());
+    return {
+        path,
+        query,
+        body: Object.keys(body).length > 0 || sentEmptyBody ? body : undefined,
+    };
+}

package/dist/tools/capability-registry/config.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Where the index comes from, and where each product lives.
+ *
+ * A product may DECLARE its host in its own index file (`<product>.base_url`, authored in
+ * the harness's product.yaml and carried through by the export). That is the default, not
+ * the last word: config overrides it, and for a region-sharded product account discovery
+ * outranks it — see `resolveBaseUrl`. The same artifact therefore still ships to every
+ * environment, because anything environment- or account-specific is resolved here.
+ */
+import { BrowserStackConfig } from "../../lib/types.js";
+import { HostSource } from "./discovery.js";
+import { Transport } from "./egress.js";
+/**
+ * The environment this DEPLOYMENT points at, e.g. "preprod".
+ *
+ * Process-level on purpose, and the distinction from region matters: an environment is a
+ * property of the deployment (this instance talks to preprod), whereas a REGION is a
+ * property of the account (this user's data lives in EU). That is why region discovery is
+ * per request and never cached under REMOTE_MCP, while the environment is read once here.
+ */
+export declare function selectedEnvironment(): string;
+/** True when this product's host is account-specific and must be discovered per call. */
+export declare function isRegionSharded(product: string, source?: HostSource): boolean;
+/**
+ * Resolve a product's host.
+ *
+ * Atlas resolves: an explicit per-session override, then the host for the session's
+ * environment (`harness.extra_environments[env][product]`), then the profile's own
+ * `base_url`. The same rungs, in the same order, with one addition:
+ *
+ *   1. CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>            explicit, environment-agnostic
+ *   2. CAPABILITY_REGISTRY_BASE_URL_<PRODUCT>_<ENV>      this environment's host
+ *   3. CAPABILITY_REGISTRY_BASE_URLS {product:{env:url}} the same, as one map
+ *   4. account discovery — the index's `base_urls`, probed
+ *   5. the single host declared in the index, `base_url`
+ *   6. refuse, by name
+ *
+ * DISCOVERY OUTRANKS THE DECLARED HOST, which is where this departs from Atlas. A declared
+ * host is one fixed origin, so for a region-sharded product it would send every account
+ * outside the default region to the wrong host — a failure that only shows up on those
+ * accounts, and so passes any test run from inside the default one. Discovery answers with
+ * the region the account is actually on; `base_url` is the fallback for when the probe
+ * cannot answer at all.
+ *
+ * Refusing rather than guessing is deliberate: a guessed host fails as a DNS error or a 404
+ * that reads like the caller's problem, when it is our missing configuration.
+ */
+export declare function resolveBaseUrl(product: string, config: BrowserStackConfig, source?: HostSource, transport?: Transport): Promise<string>;
+/**
+ * Locate the artifact(s).
+ *
+ * ONE FILE PER PRODUCT, so this returns a list. Explicit env wins; otherwise look for a
+ * `capability/` directory beside the compiled module and at the package root, then fall
+ * back to a single `capability-index.json` for the pre-release layout. The package-root
+ * candidates exist because `tsc` compiles TS and does not copy JSON into `dist`.
+ *
+ * Returns an empty list when nothing is found — the caller logs that and registers no
+ * tools, rather than throwing.
+ */
+export declare function indexPaths(): string[];
+/** Off by default is wrong for a shipped feature, but a kill switch is not. */
+export declare function isEnabled(): boolean;