toolcraft-openapi 0.0.13 → 0.0.15

package/dist/generate.d.ts

@@ -2,6 +2,9 @@ import { type HttpMethod } from "./naming.js";
 type OpenApiOperation = OpenApiOperationObject | OpenApiReferenceObject;
 type OpenApiOperationMap = Partial<Record<HttpMethod, OpenApiOperation>>;
 type OpenApiParameterLocation = "path" | "query" | "header" | "cookie";
+type OpenApiScalarType = "string" | "number" | "integer" | "boolean";
+type OpenApiSchemaType = OpenApiScalarType | "object" | "array";
+type OpenApiJsonSchemaType = OpenApiSchemaType | "null";
 export type GeneratedRequestLocation = Exclude<GeneratedParam["location"], "transport">;
 export interface OpenApiDocument {
     openapi?: string;
@@ -57,7 +60,7 @@ export interface OpenApiMediaTypeObject {
     schema?: OpenApiSchemaObject | OpenApiReferenceObject;
 }
 export interface OpenApiSchemaObject {
-    type?: "string" | "number" | "integer" | "boolean" | "object" | "array";
+    type?: OpenApiJsonSchemaType | readonly OpenApiJsonSchemaType[];
     additionalProperties?: boolean | OpenApiSchemaObject | OpenApiReferenceObject;
     allOf?: Array<OpenApiSchemaObject | OpenApiReferenceObject>;
     anyOf?: Array<OpenApiSchemaObject | OpenApiReferenceObject>;
@@ -120,6 +123,7 @@ export interface GeneratedParam {
     description?: string;
     shortFlag?: string;
     scope?: readonly [GeneratedParamScope, ...GeneratedParamScope[]];
+    global?: boolean;
     optional: boolean;
     definition: GeneratedParamDefinition;
 }
@@ -184,6 +188,7 @@ interface RenderSchemaOptionsInput {
     description?: string;
     shortFlag?: string;
     scope?: readonly [GeneratedParamScope, ...GeneratedParamScope[]];
+    global?: boolean;
 }
 export type GeneratedPreflightBlock = {
     kind: "scalar-null";

package/dist/generate.js

@@ -25,6 +25,7 @@ const TRANSPORT_PARAMS = [
         location: "transport",
         description: "Print the HTTP request and exit without sending it.",
         scope: ["cli", "sdk"],
+        global: true,
         optional: true,
         definition: { kind: "boolean" }
     },
@@ -35,6 +36,7 @@ const TRANSPORT_PARAMS = [
         description: "Log the request line to stderr.",
         shortFlag: "v",
         scope: ["cli", "sdk"],
+        global: true,
         optional: true,
         definition: { kind: "boolean" }
     }
@@ -56,6 +58,10 @@ const SCHEMA_OPTION_SOURCES = [
         key: "scope",
         get: (param) => param.scope
     },
+    {
+        key: "global",
+        get: (param) => (param.global === true ? true : undefined)
+    },
     {
         key: "minimum",
         get: (param) => param.definition.minimum
@@ -324,17 +330,11 @@ function assertSupportedSuccessResponseSchema(document, schema, operationId, con
     }
 }
 function expectSupportedSuccessResponseSchema(document, schema, operationId, context) {
-    const resolvedSchema = resolveSchema(document, schema, operationId, context);
+    const resolvedSchema = normalizeNullableSchema(document, resolveSchema(document, schema, operationId, context), operationId, context);
     const compositionKeyword = getCompositionKeyword(resolvedSchema);
     if (compositionKeyword === undefined) {
         return resolvedSchema;
     }
-    const nullableAnyOfSchema = compositionKeyword === "anyOf"
-        ? resolveNullableAnyOfSchema(document, resolvedSchema, operationId, context)
-        : undefined;
-    if (nullableAnyOfSchema !== undefined) {
-        return nullableAnyOfSchema;
-    }
     throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. JSON Schema composition keyword ${JSON.stringify(compositionKeyword)} is not supported in v1.`);
 }
 function createGeneratedParameter(document, parameter, operationId) {
@@ -578,6 +578,9 @@ function createCollectedRequestBodyParams(assemblies, bodyOptional, requestBodyD
     };
 }
 function createParamDefinition(document, schema, operationId, context) {
+    if (Array.isArray(schema.type)) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. JSON Schema type arrays with multiple non-null types are not supported in v1.`);
+    }
     if (schema.type === "array") {
         const itemSchema = expectArrayItemsSchema(document, schema, operationId, context);
         return {
@@ -589,9 +592,9 @@ function createParamDefinition(document, schema, operationId, context) {
             ...(schema.nullable === true ? { nullable: true } : {})
         };
     }
-    const scalarDefinition = schema.type === undefined || !(schema.type in SCHEMA_TYPE_TO_KIND)
-        ? undefined
-        : SCHEMA_TYPE_TO_KIND[schema.type];
+    const scalarDefinition = isOpenApiScalarType(schema.type)
+        ? SCHEMA_TYPE_TO_KIND[schema.type]
+        : undefined;
     const enumValues = normalizeEnumValues(schema.enum, operationId, context, schema.nullable === true, schema.type);
     if (enumValues !== undefined) {
         return {
@@ -747,6 +750,9 @@ function expectOperation(document, operation, method, path, refChain = []) {
 function isEnumPrimitiveValue(value) {
     return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 }
+function isOpenApiScalarType(type) {
+    return typeof type === "string" && type in SCHEMA_TYPE_TO_KIND;
+}
 function expectRequestBody(document, requestBody, operationId, context, refChain = []) {
     if (!isReferenceObject(requestBody)) {
         return requestBody;
@@ -763,7 +769,7 @@ function expectResponse(document, response, operationId, statusCode, refChain =
     return expectResponse(document, resolveLocalReference(document, response.$ref, operationId, context), operationId, statusCode, [...refChain, response.$ref]);
 }
 function expectSchema(document, schema, operationId, context, refChain = []) {
-    const resolvedSchema = resolveSchema(document, schema, operationId, context, refChain);
+    const resolvedSchema = normalizeNullableSchema(document, resolveSchema(document, schema, operationId, context, refChain), operationId, context);
     const compositionKeyword = getCompositionKeyword(resolvedSchema);
     if (compositionKeyword !== undefined) {
         throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. JSON Schema composition keyword ${JSON.stringify(compositionKeyword)} is not supported in v1.`);
@@ -780,6 +786,28 @@ function resolveSchema(document, schema, operationId, context, refChain = []) {
     }
     return schema;
 }
+function normalizeNullableSchema(document, schema, operationId, context) {
+    const typeNormalizedSchema = normalizeNullableTypeArray(schema);
+    if (getCompositionKeyword(typeNormalizedSchema) !== "anyOf") {
+        return typeNormalizedSchema;
+    }
+    return (resolveNullableAnyOfSchema(document, typeNormalizedSchema, operationId, context) ??
+        typeNormalizedSchema);
+}
+function normalizeNullableTypeArray(schema) {
+    if (!Array.isArray(schema.type)) {
+        return schema;
+    }
+    const nonNullTypes = schema.type.filter((type) => type !== "null");
+    if (nonNullTypes.length === schema.type.length) {
+        return schema;
+    }
+    return {
+        ...schema,
+        type: nonNullTypes.length === 1 ? nonNullTypes[0] : nonNullTypes,
+        nullable: true
+    };
+}
 function getCompositionKeyword(schema) {
     for (const keyword of ["allOf", "anyOf", "oneOf"]) {
         if (schema[keyword] !== undefined) {
@@ -793,7 +821,7 @@ function resolveNullableAnyOfSchema(document, schema, operationId, context) {
     if (variants === undefined || variants.length !== 2) {
         return undefined;
     }
-    const resolvedVariants = variants.map((variant, index) => resolveSchema(document, variant, operationId, `${context} anyOf variant ${index}`));
+    const resolvedVariants = variants.map((variant, index) => normalizeNullableSchema(document, resolveSchema(document, variant, operationId, `${context} anyOf variant ${index}`), operationId, `${context} anyOf variant ${index}`));
     const nullVariantIndex = resolvedVariants.findIndex(isExplicitNullSchema);
     if (nullVariantIndex === -1) {
         return undefined;
@@ -802,8 +830,14 @@ function resolveNullableAnyOfSchema(document, schema, operationId, context) {
     if (nonNullVariant === undefined || getCompositionKeyword(nonNullVariant) !== undefined) {
         return undefined;
     }
+    const { anyOf: _anyOf, nullable: _nullable, ...wrapperSchema } = schema;
+    void _anyOf;
+    void _nullable;
     return {
+        ...wrapperSchema,
         ...nonNullVariant,
+        description: nonNullVariant.description ?? schema.description,
+        default: nonNullVariant.default ?? schema.default,
         nullable: true
     };
 }
@@ -935,15 +969,16 @@ function renderParamLines(params) {
     return params.map((param) => `    ${renderObjectKey(param.paramName)}: ${renderParamSchema(param)},`);
 }
 function renderParamSchema(param) {
-    const schema = renderDefinition(param.definition, param.description, param.shortFlag, param.scope);
+    const schema = renderDefinition(param.definition, param.description, param.shortFlag, param.scope, param.global);
     return param.optional ? `S.Optional(${schema})` : schema;
 }
-function renderDefinition(definition, description, shortFlag, scope) {
+function renderDefinition(definition, description, shortFlag, scope, global) {
     const options = renderSchemaOptions({
         definition,
         description,
         shortFlag,
-        scope
+        scope,
+        global
     });
     const renderer = DEFINITION_RENDERERS[definition.kind];
     return renderer(definition, options);

package/dist/http.js

@@ -1,3 +1,4 @@
+import { text as designText } from "@poe-code/design-system";
 import { UserError } from "toolcraft";
 export class HttpError extends Error {
     status;
@@ -20,7 +21,7 @@ export async function requestJson(options) {
     const writeStderr = options.writeStderr ?? process.stderr.write.bind(process.stderr);
     const requestLine = `${method} ${url}`;
     if (options.verbose) {
-        writeStderr(`${requestLine}\n`);
+        writeStderr(`${designText.muted(requestLine)}\n`);
     }
     if (options.dryRun) {
         writeStdout(formatDryRunOutput(requestLine, headers, options.body));

package/dist/mock/fetch.d.ts

@@ -0,0 +1,35 @@
+import type { OpenApiDocument } from "../generate.js";
+import { type OpenApiSourceFileSystem } from "../spec-source.js";
+export type OnUnmocked = "throw" | "reply404";
+export interface MockFixtureEntry {
+    status?: number;
+    headers?: Record<string, string>;
+    body?: unknown;
+}
+export type MockFetchFixtures = Record<string, MockFixtureEntry> | string;
+export interface MockFetchFileSystem extends OpenApiSourceFileSystem {
+    readdir?(directory: string): Promise<string[]>;
+}
+export interface MockFetchOptions {
+    spec: OpenApiDocument | string | URL;
+    fixtures?: MockFetchFixtures;
+    onUnmocked?: OnUnmocked;
+    cwd?: string;
+    fs?: MockFetchFileSystem;
+    fetch?: typeof globalThis.fetch;
+}
+export interface RequestRecord {
+    method: string;
+    path: string;
+    operationId: string;
+    headers: Record<string, string>;
+    body: unknown;
+    at: Date;
+}
+export interface MockFetchHandle {
+    fetch: typeof globalThis.fetch;
+    requests: RequestRecord[];
+    reset(): void;
+}
+export declare function mockFetch(options: MockFetchOptions): Promise<MockFetchHandle>;
+export type { OpenApiSourceFileSystem };

package/dist/mock/fetch.js

@@ -0,0 +1,498 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { UserError } from "toolcraft";
+import { parseOpenApiDocument, readOpenApiSourceText } from "../spec-source.js";
+const HTTP_METHOD_NAMES = ["get", "post", "put", "patch", "delete"];
+export async function mockFetch(options) {
+    const document = await resolveSpec(options);
+    const operations = compileOperations(document);
+    const operationIds = new Set(operations.map((op) => op.operationId));
+    const fixtureLoader = await createFixtureLoader(options.fixtures, options.cwd, options.fs, operationIds);
+    const onUnmocked = options.onUnmocked ?? "throw";
+    const requests = [];
+    const fetchImpl = async (input, init) => {
+        const requestUrl = parseRequestUrl(input);
+        const method = (init?.method ?? getRequestMethod(input) ?? "GET").toUpperCase();
+        const headers = collectHeaders(input, init);
+        const bodyText = await readRequestBody(input, init);
+        const parsedBody = parseJsonOrUndefined(bodyText);
+        const matchingPath = operations.filter((op) => op.pathRegex.test(requestUrl.pathname));
+        if (matchingPath.length === 0) {
+            throw new MockFetchError(`mockFetch: no operation in the spec matches ${method} ${requestUrl.pathname}.`);
+        }
+        const operation = matchingPath.find((op) => op.method === method);
+        if (operation === undefined) {
+            const allowed = matchingPath.map((op) => op.method).join(", ");
+            throw new MockFetchError(`mockFetch: method ${method} not declared for ${requestUrl.pathname} (spec allows ${allowed}).`);
+        }
+        requests.push({
+            method,
+            path: requestUrl.pathname,
+            operationId: operation.operationId,
+            headers,
+            body: parsedBody,
+            at: new Date()
+        });
+        if (operation.requestBodySchema !== undefined && parsedBody !== undefined) {
+            const errors = validateAgainstSchema(parsedBody, operation.requestBodySchema, document, "$");
+            if (errors.length > 0) {
+                return jsonResponse(422, { errors });
+            }
+        }
+        else if (operation.requestBodyRequired && parsedBody === undefined) {
+            return jsonResponse(422, { errors: ["$: request body is required"] });
+        }
+        const fixture = await fixtureLoader(operation.operationId);
+        if (fixture !== undefined) {
+            const status = fixture.status ?? operation.defaultStatus;
+            const responseSchema = operation.responseSchemas.get(status);
+            if (responseSchema !== undefined && fixture.body !== undefined) {
+                const errors = validateAgainstSchema(fixture.body, responseSchema, document, "$response");
+                if (errors.length > 0) {
+                    throw new MockFetchError(`mockFetch: response fixture for ${JSON.stringify(operation.operationId)} ` +
+                        `violates the spec response schema for status ${status}:\n  ${errors.join("\n  ")}`);
+                }
+            }
+            return buildResponse(fixture, operation.defaultStatus);
+        }
+        if (operation.defaultExample !== undefined) {
+            return buildResponse({ body: operation.defaultExample }, operation.defaultStatus);
+        }
+        if (onUnmocked === "reply404") {
+            return jsonResponse(404, { error: `unmocked: ${operation.operationId}` });
+        }
+        throw new MockFetchError(`mockFetch: unmocked operation ${JSON.stringify(operation.operationId)}. ` +
+            `Add a fixture, an OpenAPI example on the success response, or pass { onUnmocked: "reply404" }.`);
+    };
+    return {
+        fetch: fetchImpl,
+        requests,
+        reset() {
+            requests.length = 0;
+        }
+    };
+}
+class MockFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MockFetchError";
+    }
+}
+async function resolveSpec(options) {
+    const { spec } = options;
+    if (typeof spec !== "string" && !(spec instanceof URL)) {
+        return spec;
+    }
+    const sourceText = await readOpenApiSourceText(spec, {
+        cwd: options.cwd ?? process.cwd(),
+        fetch: options.fetch ?? globalThis.fetch,
+        fs: options.fs ?? fs
+    });
+    return parseOpenApiDocument(sourceText, spec);
+}
+function compileOperations(document) {
+    const paths = document.paths;
+    if (paths === undefined) {
+        throw new UserError('mockFetch: OpenAPI document must define a top-level "paths" object.');
+    }
+    const compiled = [];
+    for (const [pathTemplate, pathItem] of Object.entries(paths)) {
+        if (pathItem === undefined) {
+            continue;
+        }
+        for (const method of HTTP_METHOD_NAMES) {
+            const operation = pathItem[method];
+            if (operation === undefined) {
+                continue;
+            }
+            const resolvedOperation = resolveOperation(operation, document);
+            const operationId = resolvedOperation.operationId ?? `${method.toUpperCase()} ${pathTemplate}`;
+            const { defaultStatus, defaultExample, responseSchemas } = pickResponseMetadata(resolvedOperation, document);
+            const { schema: requestBodySchema, required: requestBodyRequired } = pickRequestBody(resolvedOperation, document);
+            compiled.push({
+                method: method.toUpperCase(),
+                pathTemplate,
+                pathRegex: pathTemplateToRegex(pathTemplate),
+                pathSpecificity: countPathPlaceholders(pathTemplate),
+                operationId,
+                operation: resolvedOperation,
+                defaultStatus,
+                defaultExample,
+                requestBodySchema,
+                requestBodyRequired,
+                responseSchemas
+            });
+        }
+    }
+    // Literal paths win over templated paths when both match the same pathname.
+    // Sort ascending by placeholder count so concrete operations are matched first.
+    compiled.sort((a, b) => a.pathSpecificity - b.pathSpecificity);
+    return compiled;
+}
+function countPathPlaceholders(template) {
+    return (template.match(/\{[^}]+\}/g) ?? []).length;
+}
+function pathTemplateToRegex(template) {
+    // Escape regex metacharacters except for "{...}" placeholders, which become non-slash captures.
+    const pattern = template.replace(/[.*+?^${}()|[\]\\]/g, (match) => match === "{" || match === "}" ? match : `\\${match}`);
+    const withParams = pattern.replace(/\{[^}]+\}/g, "[^/]+");
+    return new RegExp(`^${withParams}$`);
+}
+function resolveOperation(operation, document) {
+    if (isReference(operation)) {
+        return resolveReference(operation, document);
+    }
+    return operation;
+}
+function pickResponseMetadata(operation, document) {
+    const responses = operation.responses ?? {};
+    const responseSchemas = new Map();
+    for (const [code, response] of Object.entries(responses)) {
+        const status = parseInt(code, 10);
+        if (!Number.isFinite(status) || response === undefined) {
+            continue;
+        }
+        const resolved = isReference(response)
+            ? resolveReference(response, document)
+            : response;
+        const schema = extractResponseSchema(resolved, document);
+        if (schema !== undefined) {
+            responseSchemas.set(status, schema);
+        }
+    }
+    const successCodes = Object.keys(responses)
+        .map((code) => parseInt(code, 10))
+        .filter((code) => Number.isFinite(code) && code >= 200 && code < 300)
+        .sort((a, b) => a - b);
+    if (successCodes.length === 0) {
+        return { defaultStatus: 200, defaultExample: undefined, responseSchemas };
+    }
+    const status = successCodes[0];
+    const response = responses[String(status)];
+    const resolvedResponse = response !== undefined && isReference(response)
+        ? resolveReference(response, document)
+        : response;
+    return {
+        defaultStatus: status,
+        defaultExample: extractExample(resolvedResponse, document),
+        responseSchemas
+    };
+}
+function extractResponseSchema(response, document) {
+    if (response === undefined) {
+        return undefined;
+    }
+    const media = pickJsonMediaType(response.content);
+    if (media === undefined || media.schema === undefined) {
+        return undefined;
+    }
+    return isReference(media.schema)
+        ? resolveReference(media.schema, document)
+        : media.schema;
+}
+function pickRequestBody(operation, document) {
+    const raw = operation.requestBody;
+    if (raw === undefined) {
+        return { schema: undefined, required: false };
+    }
+    const resolved = isReference(raw)
+        ? resolveReference(raw, document)
+        : raw;
+    const media = pickJsonMediaType(resolved.content);
+    if (media === undefined) {
+        return { schema: undefined, required: resolved.required === true };
+    }
+    if (media.schema === undefined) {
+        return { schema: undefined, required: resolved.required === true };
+    }
+    const schema = isReference(media.schema)
+        ? resolveReference(media.schema, document)
+        : media.schema;
+    return { schema, required: resolved.required === true };
+}
+function extractExample(response, document) {
+    if (response === undefined) {
+        return undefined;
+    }
+    const media = pickJsonMediaType(response.content);
+    if (media === undefined) {
+        return undefined;
+    }
+    if (media.example !== undefined) {
+        return media.example;
+    }
+    if (media.examples !== undefined) {
+        for (const value of Object.values(media.examples)) {
+            if (value !== undefined && "value" in value) {
+                return value.value;
+            }
+        }
+    }
+    if (media.schema !== undefined) {
+        const schema = isReference(media.schema)
+            ? resolveReference(media.schema, document)
+            : media.schema;
+        const schemaExample = schema.example;
+        if (schemaExample !== undefined) {
+            return schemaExample;
+        }
+    }
+    return undefined;
+}
+function pickJsonMediaType(content) {
+    if (content === undefined) {
+        return undefined;
+    }
+    for (const [type, media] of Object.entries(content)) {
+        if (media !== undefined && /application\/json|\+json/i.test(type)) {
+            return media;
+        }
+    }
+    return undefined;
+}
+function isReference(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "$ref" in value &&
+        typeof value.$ref === "string");
+}
+function resolveReference(reference, document) {
+    const ref = reference.$ref;
+    if (!ref.startsWith("#/")) {
+        throw new UserError(`mockFetch: only local $ref values are supported, got ${JSON.stringify(ref)}.`);
+    }
+    const segments = ref
+        .slice(2)
+        .split("/")
+        .map((segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~"));
+    let current = document;
+    for (const segment of segments) {
+        if (current === null || typeof current !== "object") {
+            throw new UserError(`mockFetch: failed to resolve $ref ${JSON.stringify(ref)}.`);
+        }
+        current = current[segment];
+    }
+    if (current === undefined) {
+        throw new UserError(`mockFetch: failed to resolve $ref ${JSON.stringify(ref)}.`);
+    }
+    return current;
+}
+function validateAgainstSchema(value, schema, document, pointer) {
+    const resolved = isReference(schema)
+        ? resolveReference(schema, document)
+        : schema;
+    if (resolved.anyOf !== undefined) {
+        return resolved.anyOf.some((branch) => validateAgainstSchema(value, branch, document, pointer).length === 0)
+            ? []
+            : [`${pointer}: did not match any anyOf branch`];
+    }
+    if (resolved.oneOf !== undefined) {
+        const matches = resolved.oneOf.filter((branch) => validateAgainstSchema(value, branch, document, pointer).length === 0);
+        return matches.length === 1 ? [] : [`${pointer}: matched ${matches.length} oneOf branches`];
+    }
+    const errors = [];
+    if (resolved.allOf !== undefined) {
+        for (const branch of resolved.allOf) {
+            errors.push(...validateAgainstSchema(value, branch, document, pointer));
+        }
+    }
+    const types = normalizeTypes(resolved);
+    if (types.length > 0 && !types.some((type) => matchesPrimitiveType(value, type))) {
+        errors.push(`${pointer}: expected ${types.join(" or ")}, got ${describeValue(value)}`);
+        return errors;
+    }
+    if (types.includes("object") && typeof value === "object" && value !== null && !Array.isArray(value)) {
+        for (const required of resolved.required ?? []) {
+            if (!(required in value)) {
+                errors.push(`${pointer}/${required}: required`);
+            }
+        }
+        if (resolved.properties !== undefined) {
+            for (const [key, propValue] of Object.entries(value)) {
+                const propSchema = resolved.properties[key];
+                if (propSchema !== undefined) {
+                    errors.push(...validateAgainstSchema(propValue, propSchema, document, `${pointer}/${key}`));
+                }
+            }
+        }
+    }
+    if (types.includes("array") && Array.isArray(value) && resolved.items !== undefined) {
+        for (let i = 0; i < value.length; i++) {
+            errors.push(...validateAgainstSchema(value[i], resolved.items, document, `${pointer}/${i}`));
+        }
+    }
+    if (resolved.enum !== undefined && !resolved.enum.includes(value)) {
+        errors.push(`${pointer}: not in enum`);
+    }
+    return errors;
+}
+function normalizeTypes(schema) {
+    const type = schema.type;
+    if (type === undefined) {
+        return [];
+    }
+    const list = Array.isArray(type) ? type.slice() : [type];
+    if (schema.nullable === true && !list.includes("null")) {
+        list.push("null");
+    }
+    return list;
+}
+function matchesPrimitiveType(value, type) {
+    switch (type) {
+        case "object":
+            return typeof value === "object" && value !== null && !Array.isArray(value);
+        case "array":
+            return Array.isArray(value);
+        case "string":
+            return typeof value === "string";
+        case "number":
+            return typeof value === "number" && !Number.isNaN(value);
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "null":
+            return value === null;
+        default:
+            return true;
+    }
+}
+function describeValue(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+function parseRequestUrl(input) {
+    if (input instanceof URL) {
+        return input;
+    }
+    if (typeof input === "string") {
+        return new URL(input);
+    }
+    return new URL(input.url);
+}
+function getRequestMethod(input) {
+    if (typeof input === "string" || input instanceof URL) {
+        return undefined;
+    }
+    return input.method;
+}
+function collectHeaders(input, init) {
+    const headers = {};
+    const initHeaders = init?.headers;
+    const requestHeaders = typeof input !== "string" && !(input instanceof URL) ? input.headers : undefined;
+    appendHeaders(headers, requestHeaders);
+    appendHeaders(headers, initHeaders);
+    return headers;
+}
+function appendHeaders(target, source) {
+    if (source === undefined) {
+        return;
+    }
+    if (source instanceof Headers) {
+        source.forEach((value, key) => {
+            target[key.toLowerCase()] = value;
+        });
+        return;
+    }
+    if (Array.isArray(source)) {
+        for (const [key, value] of source) {
+            target[key.toLowerCase()] = value;
+        }
+        return;
+    }
+    for (const [key, value] of Object.entries(source)) {
+        target[key.toLowerCase()] = String(value);
+    }
+}
+async function readRequestBody(input, init) {
+    if (init?.body !== undefined && init.body !== null) {
+        return typeof init.body === "string" ? init.body : await new Response(init.body).text();
+    }
+    if (typeof input !== "string" && !(input instanceof URL)) {
+        return await input.clone().text();
+    }
+    return undefined;
+}
+function parseJsonOrUndefined(text) {
+    if (text === undefined || text.length === 0) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function buildResponse(fixture, defaultStatus) {
+    const status = fixture.status ?? defaultStatus;
+    const headers = new Headers(fixture.headers ?? { "content-type": "application/json" });
+    const body = fixture.body === undefined ? null : fixture.body === null ? null : JSON.stringify(fixture.body);
+    return new Response(body, { status, headers });
+}
+function jsonResponse(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" }
+    });
+}
+async function createFixtureLoader(fixtures, cwd, injectedFs, operationIds) {
+    if (fixtures === undefined) {
+        return async () => undefined;
+    }
+    if (typeof fixtures !== "string") {
+        rejectUnknownFixtureKeys(Object.keys(fixtures), operationIds, "fixture key");
+        const map = fixtures;
+        return async (operationId) => map[operationId];
+    }
+    const directory = path.resolve(cwd ?? process.cwd(), fixtures);
+    const fileSystem = injectedFs ?? fs;
+    const readdir = fileSystem.readdir?.bind(fileSystem);
+    if (readdir === undefined) {
+        throw new UserError("mockFetch: directory fixtures require an fs implementation that exposes readdir.");
+    }
+    let entries;
+    try {
+        entries = await readdir(directory);
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return async () => undefined;
+        }
+        throw error;
+    }
+    const fixtureFiles = entries.filter((entry) => entry.endsWith(".json"));
+    const operationIdsFromFiles = fixtureFiles.map((entry) => entry.slice(0, -".json".length));
+    rejectUnknownFixtureKeys(operationIdsFromFiles, operationIds, "fixture file");
+    const cache = new Map();
+    for (const entry of fixtureFiles) {
+        const operationId = entry.slice(0, -".json".length);
+        const filePath = path.join(directory, entry);
+        const contents = await fileSystem.readFile(filePath, "utf8");
+        cache.set(operationId, JSON.parse(contents));
+    }
+    return async (operationId) => cache.get(operationId);
+}
+function rejectUnknownFixtureKeys(candidates, operationIds, label) {
+    const unknown = candidates.filter((key) => !operationIds.has(key));
+    if (unknown.length === 0) {
+        return;
+    }
+    const sorted = [...operationIds].sort();
+    throw new UserError(`mockFetch: ${unknown.length === 1 ? label : `${label}s`} ${formatList(unknown)} ` +
+        `${unknown.length === 1 ? "is" : "are"} not declared in the spec. ` +
+        `Known operationIds: ${sorted.length === 0 ? "(none)" : formatList(sorted)}.`);
+}
+function formatList(values) {
+    return values.map((value) => JSON.stringify(value)).join(", ");
+}
+function isNotFoundError(error) {
+    if (typeof error !== "object" || error === null) {
+        return false;
+    }
+    const code = error.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}

package/dist/mock.compile-check.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mock.compile-check.js

@@ -0,0 +1,15 @@
+import { mockFetch } from "./mock.js";
+const ignoredHandlePromise = mockFetch({
+    spec: { openapi: "3.0.0", info: { title: "T", version: "0" }, paths: {} },
+    fixtures: { whoami: { body: { handle: "x" } } },
+    onUnmocked: "throw"
+});
+void ignoredHandlePromise.then((handle) => {
+    void handle.fetch;
+    void handle.requests;
+    void handle.reset;
+});
+const ignoredOptions = { spec: "./openapi.json" };
+void ignoredOptions;
+const ignoredFixture = { status: 200, body: { ok: true } };
+void ignoredFixture;

package/dist/mock.d.ts

@@ -0,0 +1,2 @@
+export { mockFetch } from "./mock/fetch.js";
+export type { MockFetchHandle, MockFetchOptions, MockFetchFixtures, MockFixtureEntry, OnUnmocked, RequestRecord } from "./mock/fetch.js";

package/dist/mock.js

@@ -0,0 +1 @@
+export { mockFetch } from "./mock/fetch.js";

package/dist/runtime.js

@@ -66,11 +66,11 @@ function createRuntimeHandler(command) {
     };
 }
 function createRuntimeParamSchema(param) {
-    const definition = createRuntimeDefinition(param.definition, param.description, param.shortFlag, param.scope);
+    const definition = createRuntimeDefinition(param.definition, param.description, param.shortFlag, param.scope, param.global);
     return param.optional ? S.Optional(definition) : definition;
 }
-function createRuntimeDefinition(definition, description, shortFlag, scope) {
-    const options = createRuntimeSchemaOptions(definition, description, shortFlag, scope);
+function createRuntimeDefinition(definition, description, shortFlag, scope, global) {
+    const options = createRuntimeSchemaOptions(definition, description, shortFlag, scope, global);
     return RUNTIME_DEFINITION_BUILDERS[definition.kind](definition, options);
 }
 const RUNTIME_DEFINITION_BUILDERS = {
@@ -83,12 +83,13 @@ const RUNTIME_DEFINITION_BUILDERS = {
     number: (_definition, options) => options === undefined ? S.Number() : S.Number(options),
     string: (_definition, options) => options === undefined ? S.String() : S.String(options)
 };
-function createRuntimeSchemaOptions(definition, description, shortFlag, scope) {
+function createRuntimeSchemaOptions(definition, description, shortFlag, scope, global) {
     const options = Object.fromEntries(collectSchemaOptionEntries({
         definition,
         description,
         shortFlag,
-        scope
+        scope,
+        global
     }).map(({ key, value }) => [key, Array.isArray(value) ? [...value] : value]));
     return Object.keys(options).length === 0 ? undefined : options;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-openapi",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -8,12 +8,16 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./mock": {
+      "types": "./dist/mock.d.ts",
+      "import": "./dist/mock.js"
     }
   },
   "scripts": {
     "build": "rm -rf dist && tsc",
-    "test": "cd ../.. && vitest run packages/toolcraft-openapi/src/*.test.ts",
-    "test:unit": "cd ../.. && vitest run packages/toolcraft-openapi/src/*.test.ts",
+    "test": "cd ../.. && vitest run packages/toolcraft-openapi/src",
+    "test:unit": "cd ../.. && vitest run packages/toolcraft-openapi/src",
     "prepack": "node ../../scripts/manage-bundled-workspace-deps.mjs prepare . @poe-code/design-system auth-store",
     "postpack": "node ../../scripts/manage-bundled-workspace-deps.mjs cleanup . @poe-code/design-system auth-store"
   },
@@ -30,7 +34,7 @@
     "auth-store": "^0.0.1",
     "chalk": "^5.6.2",
     "console-table-printer": "^2.15.0",
-    "toolcraft": "^0.0.13",
+    "toolcraft": "^0.0.15",
     "yaml": "^2.8.2"
   },
   "engines": {