toolcraft-openapi 0.0.138 → 0.0.140

package/README.md

@@ -50,6 +50,45 @@ export const client = defineGeneratedClient({
 Generated lower-level group and operation exports remain available when callers
 want a curated command surface with `defineClient()`.
 
+## Live runtime clients
+
+`defineClientFromSpec()` materializes the same OpenAPI command model at process startup without
+writing generated source files:
+
+```ts
+const client = await defineClientFromSpec("https://api.example.com/openapi.json", {
+  name: "internal-agent",
+  baseUrl: "https://api.example.com",
+  auth,
+  cache: {
+    onFallback: (message) => process.stderr.write(`${message}\n`)
+  }
+});
+```
+
+HTTP sources use a cross-process disk cache by default when the built-in `fetch` is used.
+Successful documents remain fresh for the server's `Cache-Control: max-age`, or five
+minutes when the server does not provide one. Stale entries revalidate with `If-None-Match` when
+an ETag is available. Fetching and reading the response have a three-second timeout; a transport
+failure or timeout uses the last successfully materialized document. HTTP errors and invalid live
+documents still fail visibly.
+
+Runtime source options:
+
+- `cache: false` - disables HTTP source caching and offline fallback.
+- `cache.directory` - absolute cache directory override.
+- `cache.maxAgeMs` - fallback freshness when the response does not define cache behavior.
+- `cache.onFallback(message)` - reports when a stale document is used after a transport failure.
+- `onTimeout({ source, timeoutMs, usingCachedDocument })` - application hook for presenting
+  network-access guidance without coupling the library to a specific network or VPN.
+- `timeoutMs` - total HTTP fetch/body timeout. Defaults to `3000`; `0` disables it.
+
+Supplying a custom `fetch` disables automatic caching unless `cache` is explicitly provided. Use a
+different `cache.directory` for each identity when explicitly caching authenticated custom fetches.
+A custom filesystem participates when it provides `realpath` and the cache write operations;
+read-only filesystems still load the live document without persisting it. New cache entries are
+committed only after the command tree materializes successfully.
+
 ### CI drift check
 
 ```sh
@@ -79,6 +118,9 @@ toolcraft-openapi-generate --check
 - `AUTH_BACKEND` - forwarded to `auth-store` to select `file` or `keychain` storage.
 - `TOOLCRAFT_OPENAPI_ENV` - selects a configured OpenAPI environment when using
   `resolveOpenApiBaseUrl`.
+- `TOOLCRAFT_OPENAPI_CACHE_DIR` - absolute directory for live HTTP OpenAPI cache entries.
+- `TOOLCRAFT_OPENAPI_CACHE` - set to `0` or `false` to disable the default live HTTP cache.
+- `XDG_CACHE_HOME` - cache root fallback; defaults to `~/.cache`.
 
 ## Configuration
 

package/dist/composition.json

@@ -38,12 +38,12 @@
     },
     {
       "name": "toolcraft-openapi",
-      "version": "0.0.138",
+      "version": "0.0.140",
       "license": "MIT"
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.138",
+      "version": "0.0.140",
       "license": "MIT"
     },
     {

package/dist/generate.d.ts

@@ -269,4 +269,5 @@ export declare function generateSkill(document: OpenApiDocument, options?: {
 export declare function collectGeneratedCommands(document: OpenApiDocument, config?: ToolcraftConfig): GeneratedCommand[];
 export declare function collectGeneratedCommand(document: OpenApiDocument, path: string, method: HttpMethod): GeneratedCommand;
 export declare function collectSchemaOptionEntries(param: RenderSchemaOptionsInput): SchemaOptionEntry[];
+export declare function collectTagDescriptions(document: OpenApiDocument): Map<string, string>;
 export {};

package/dist/generate.js

@@ -227,9 +227,7 @@ function refreshGeneratedCommandNames(command) {
     command.exportName = command.topLevel
         ? `${toCamelCase(command.verb)}Command`
         : `${toCamelCase(command.noun)}${toPascalCase(command.verb)}Command`;
-    command.filePath = command.topLevel
-        ? `${command.verb}.ts`
-        : `${command.noun}/${command.verb}.ts`;
+    command.filePath = command.topLevel ? `${command.verb}.ts` : `${command.noun}/${command.verb}.ts`;
 }
 export function collectGeneratedCommand(document, path, method) {
     const normalizedDocument = normalizeOpenApiDocument(document);
@@ -616,10 +614,12 @@ function collectRequestBodyParams(document, operation, operationId, method) {
 function resolveSuccessResponse(document, operation, operationId) {
     let textualMediaType;
     let binaryMediaType;
-    for (const [statusCode, response] of Object.entries(operation.responses ?? {})) {
-        if (!isSuccessStatusCode(statusCode)) {
-            continue;
-        }
+    const responses = Object.entries(operation.responses ?? {});
+    const explicitSuccessResponses = responses.filter(([statusCode]) => isSuccessStatusCode(statusCode));
+    const candidateResponses = explicitSuccessResponses.length > 0
+        ? explicitSuccessResponses
+        : responses.filter(([statusCode]) => statusCode === "default");
+    for (const [statusCode, response] of candidateResponses) {
         const resolvedResponse = expectResponse(document, response, operationId, statusCode);
         const declaredMediaTypes = Object.entries(resolvedResponse.content ?? {})
             .filter(([, mediaType]) => mediaType !== undefined)
@@ -1163,7 +1163,7 @@ function collectPathPlaceholders(path) {
     return placeholders;
 }
 function isSuccessStatusCode(statusCode) {
-    if (statusCode === "default" || statusCode === "2XX") {
+    if (statusCode === "2XX") {
         return true;
     }
     return (statusCode.length === 3 &&
@@ -1858,7 +1858,7 @@ function resolveQueryObjectSerialization(parameter, operationId) {
     }
     throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported query-object serialization for parameter ${JSON.stringify(parameter.name)}. Supported in v1: deepObject with explode true.`);
 }
-function collectTagDescriptions(document) {
+export function collectTagDescriptions(document) {
     const descriptions = new Map();
     for (const tag of document.tags ?? []) {
         if (typeof tag.name !== "string" || tag.name.length === 0) {

package/dist/http.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { text as designText } from "toolcraft-design";
-import { HttpError, UserError, createHttpError } from "toolcraft";
+import { HttpError, UserError, createHttpError, shouldEmitDiagnostic } from "toolcraft";
 import { classifyNetworkError } from "./network-error.js";
 import { redactHeaders, redactHeaderValue, redactSensitiveQueryValues } from "./redaction.js";
 export { HttpError };
@@ -29,7 +29,7 @@ export async function requestJson(options) {
         : {};
     const headers = createHeaders(token, hasBody, { ...options.headers, ...idempotencyHeader }, options.accept, options.bodyMode, options.contentType);
     emitHttpDebug(options, `${method} ${url}`, { method, url });
-    emitHttpTrace(options, "HTTP request transcript", formatVerboseRequestTranscript(method, url, headers, options.body));
+    emitHttpTrace(options, "HTTP request transcript", () => formatVerboseRequestTranscript(method, url, headers, options.body));
     const response = await fetchWithRetries(options, url, {
         method,
         headers,
@@ -42,7 +42,7 @@ export async function requestJson(options) {
     if (response.ok && options.responseMode === "binary") {
         const bytes = new Uint8Array(await response.arrayBuffer());
         if (bytes.byteLength === 0) {
-            emitHttpTrace(options, "HTTP response transcript", formatVerboseResponseTranscript(response, responseHeaders));
+            emitHttpTrace(options, "HTTP response transcript", () => formatVerboseResponseTranscript(response, responseHeaders));
             return formatRawResponseResult(undefined, response, options.rawResponse);
         }
         const body = {
@@ -51,17 +51,17 @@ export async function requestJson(options) {
             byteLength: bytes.byteLength,
             data: Buffer.from(bytes).toString("base64")
         };
-        emitHttpTrace(options, "HTTP response transcript", formatVerboseResponseTranscript(response, responseHeaders, body));
+        emitHttpTrace(options, "HTTP response transcript", () => formatVerboseResponseTranscript(response, responseHeaders, body));
         return formatRawResponseResult(body, response, options.rawResponse);
     }
     const text = await response.text();
     if (response.ok) {
         if (text.length === 0) {
-            emitHttpTrace(options, "HTTP response transcript", formatVerboseResponseTranscript(response, responseHeaders));
+            emitHttpTrace(options, "HTTP response transcript", () => formatVerboseResponseTranscript(response, responseHeaders));
             return formatRawResponseResult(undefined, response, options.rawResponse);
         }
         if (options.responseMode === "text") {
-            emitHttpTrace(options, "HTTP response transcript", formatVerboseResponseTranscript(response, responseHeaders, text));
+            emitHttpTrace(options, "HTTP response transcript", () => formatVerboseResponseTranscript(response, responseHeaders, text));
             return formatRawResponseResult(text, response, options.rawResponse);
         }
         if (!isJsonContentType(contentType)) {
@@ -92,7 +92,7 @@ export async function requestJson(options) {
                 message: "Expected a valid JSON response body but received malformed JSON."
             });
         }
-        emitHttpTrace(options, "HTTP response transcript", formatVerboseResponseTranscript(response, responseHeaders, body));
+        emitHttpTrace(options, "HTTP response transcript", () => formatVerboseResponseTranscript(response, responseHeaders, body));
         return formatRawResponseResult(body, response, options.rawResponse);
     }
     if (response.status === 401 && options.auth === "required") {
@@ -153,13 +153,17 @@ function emitHttpDebug(options, message, data) {
         data
     });
 }
-function emitHttpTrace(options, message, lines) {
-    options.diagnostics?.emit({
+function emitHttpTrace(options, message, createLines) {
+    const diagnostics = options.diagnostics;
+    if (diagnostics === undefined || !shouldEmitDiagnostic("trace", diagnostics.level)) {
+        return;
+    }
+    diagnostics.emit({
         level: "trace",
         message,
         category: "http",
         data: {
-            transcript: formatTranscriptLines(lines)
+            transcript: formatTranscriptLines(createLines())
         }
     });
 }

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export type { InspectOpenApiSourceOptions, OpenApiInspectionSource } from "./ins
 export { renderOpenApiInspection } from "./render-inspection.js";
 export { commandsFromSpec, defineClientFromSpec, resolveOpenApiBaseUrl } from "./runtime.js";
 export type { CommandsFromSpecOptions, DefineClientFromSpecOptions, OpenApiDocumentSource } from "./runtime.js";
+export type { OpenApiSpecCacheFileSystem, OpenApiSpecCacheOptions, OpenApiTimeoutContext } from "./spec-cache.js";
 export type { DefineClientOptions, DefinedClient, OpenApiClientServices } from "./define-client.js";
 export type { AuthProvider, CommandContributor, TokenSource } from "./auth/types.js";
 export { bearerTokenAuth } from "./auth/bearer-token-auth.js";

package/dist/network-error.js

@@ -24,6 +24,12 @@ export function classifyNetworkError(error, url) {
             return new UserError(`Temporary DNS failure for ${host}. Network may be down.`, {
                 cause: error
             });
+        case "UND_ERR_SOCKET":
+            return new UserError(`Network connection failed: ${redactedUrl}.`, { cause: error });
+        case "UND_ERR_CONNECT_TIMEOUT":
+        case "UND_ERR_HEADERS_TIMEOUT":
+        case "UND_ERR_BODY_TIMEOUT":
+            return new UserError(`Request timed out: ${redactedUrl}.`, { cause: error });
     }
     if (findAbortError(error) !== null) {
         return new UserError(`Request aborted: ${redactedUrl}.`, { cause: error });

package/dist/normalize-swagger.js

@@ -20,6 +20,8 @@ export function normalizeOpenApiDocument(document) {
     }
     const consumes = readStringArray(source.consumes);
     const produces = readStringArray(source.produces);
+    const { swagger: _swagger, ...sourceWithoutSwagger } = source;
+    void _swagger;
     const paths = Object.fromEntries(Object.entries(source.paths ?? {}).map(([path, pathItem]) => [
         path,
         pathItem === undefined
@@ -36,7 +38,7 @@ export function normalizeOpenApiDocument(document) {
             : { securitySchemes: rewriteReferences(source.securityDefinitions) })
     };
     return rewriteReferences({
-        ...source,
+        ...sourceWithoutSwagger,
         openapi: "3.0.3",
         paths,
         components
@@ -47,7 +49,11 @@ function normalizePathItem(pathItem, documentConsumes, documentProduces, reusabl
         ...pathItem,
         ...(pathItem.parameters === undefined
             ? {}
-            : { parameters: pathItem.parameters.map((parameter) => normalizeParameter(resolveReusableParameter(parameter, reusableParameters))).filter(isOpenApiParameter) })
+            : {
+                parameters: pathItem.parameters
+                    .map((parameter) => normalizeParameter(resolveReusableParameter(parameter, reusableParameters)))
+                    .filter(isOpenApiParameter)
+            })
     };
     for (const method of HTTP_METHODS) {
         const operation = pathItem[method];
@@ -136,7 +142,9 @@ function normalizeResponse(response, produces) {
         ...response,
         content: Object.fromEntries(mediaTypes.map((mediaType) => [
             mediaType,
-            { schema: rewriteReferences(responseRecord.schema) }
+            {
+                schema: rewriteReferences(responseRecord.schema)
+            }
         ]))
     };
 }
@@ -147,7 +155,9 @@ function isSwaggerFormParameter(parameter) {
     return !isReferenceObject(parameter) && parameter.in === "formData";
 }
 function normalizeFormParameters(parameters, consumes) {
-    const required = parameters.filter((parameter) => parameter.required === true).map((parameter) => parameter.name);
+    const required = parameters
+        .filter((parameter) => parameter.required === true)
+        .map((parameter) => parameter.name);
     const mediaType = consumes.find((value) => value.toLowerCase() === "multipart/form-data") ??
         "application/x-www-form-urlencoded";
     return {
@@ -161,7 +171,9 @@ function normalizeFormParameters(parameters, consumes) {
                         parameter.name,
                         {
                             ...parameter.schema,
-                            ...(parameter.description === undefined ? {} : { description: parameter.description })
+                            ...(parameter.description === undefined
+                                ? {}
+                                : { description: parameter.description })
                         }
                     ]))
                 }
@@ -184,7 +196,9 @@ function rewriteReferences(value) {
     }
     return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
         key,
-        key === "$ref" && typeof entry === "string" ? rewriteReference(entry) : rewriteReferences(entry)
+        key === "$ref" && typeof entry === "string"
+            ? rewriteReference(entry)
+            : rewriteReferences(entry)
     ]));
 }
 function rewriteReference(reference) {
@@ -194,7 +208,9 @@ function rewriteReference(reference) {
         .replace("#/responses/", "#/components/responses/");
 }
 function readStringArray(value) {
-    return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+    return Array.isArray(value)
+        ? value.filter((entry) => typeof entry === "string")
+        : [];
 }
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);

package/dist/runtime.d.ts

@@ -1,14 +1,23 @@
 import { type CommandNode } from "toolcraft";
 import { type DefineClientOptions, type DefinedClient, type OpenApiClientServices } from "./define-client.js";
 import { type OpenApiDocument } from "./generate.js";
-import { type OpenApiSourceFileSystem } from "./spec-source.js";
+import type { ToolcraftConfig } from "./config.js";
+import { type OpenApiSpecCacheFileSystem, type OpenApiSpecCacheOptions, type OpenApiTimeoutContext } from "./spec-cache.js";
 export type OpenApiDocumentSource = OpenApiDocument | string | URL;
 export interface CommandsFromSpecOptions {
     cwd?: string;
     fetch?: typeof globalThis.fetch;
-    fs?: OpenApiSourceFileSystem;
+    fs?: OpenApiSpecCacheFileSystem;
+    cache?: false | OpenApiSpecCacheOptions;
+    onTimeout?: (context: OpenApiTimeoutContext) => void | Promise<void>;
+    timeoutMs?: number;
+    config?: ToolcraftConfig;
 }
-export type DefineClientFromSpecOptions<TServices extends object = Record<string, never>> = Omit<DefineClientOptions<TServices>, "commands"> & CommandsFromSpecOptions;
+export type DefineClientFromSpecOptions<TServices extends object = Record<string, never>> = Omit<DefineClientOptions<TServices>, "baseUrl" | "commands"> & CommandsFromSpecOptions & {
+    baseUrl?: string;
+    environment?: string;
+    env?: Record<string, string | undefined>;
+};
 export interface ResolveOpenApiBaseUrlOptions {
     document: OpenApiDocument;
     environments?: Record<string, string>;

package/dist/runtime.js

@@ -1,35 +1,87 @@
 import fs from "node:fs/promises";
 import { UserError, defineCommand, defineGroup, S } from "toolcraft";
 import { defineClient } from "./define-client.js";
-import { collectSchemaOptionEntries, collectGeneratedCommands } from "./generate.js";
+import { collectTagDescriptions, collectSchemaOptionEntries, collectGeneratedCommands } from "./generate.js";
 import { groupByNoun } from "./group-by-noun.js";
 import { prepareMultipartFileInputs, requestJson, writeBinaryResponseOutput } from "./http.js";
 import { buildRequestShape, executePreflightBlocks } from "./interpreter.js";
+import { DEFAULT_OPENAPI_FETCH_TIMEOUT_MS, loadCachedOpenApiSource } from "./spec-cache.js";
 import { parseOpenApiDocument, readOpenApiSourceText } from "./spec-source.js";
 const RUNTIME_COMMAND_SCOPE = ["cli", "mcp", "sdk"];
 export async function commandsFromSpec(source, options = {}) {
-    const document = await resolveDocument(source, options);
-    return createRuntimeGroups(collectGeneratedCommands(document));
+    const resolved = await resolveDocument(source, options);
+    const commands = createRuntimeNodes(resolved.document, options.config);
+    await resolved.commit?.();
+    return commands;
 }
 export async function defineClientFromSpec(spec, options) {
-    const { cwd, fetch, fs: specFs, ...clientOptions } = options;
-    const commands = (await commandsFromSpec(spec, {
+    const { cwd, fetch, fs: specFs, cache, onTimeout, timeoutMs, config, baseUrl, environment, env, ...clientOptions } = options;
+    const resolved = await resolveDocument(spec, {
         cwd,
         fetch,
-        fs: specFs
-    }));
-    return defineClient({ ...clientOptions, commands });
+        fs: specFs,
+        cache,
+        onTimeout,
+        timeoutMs,
+        config
+    });
+    const document = resolved.document;
+    const resolvedBaseUrl = baseUrl ??
+        resolveOpenApiBaseUrl({
+            document,
+            environments: config?.environments,
+            environment,
+            env: env ?? process.env
+        });
+    if (resolvedBaseUrl === undefined) {
+        throw new UserError("defineClientFromSpec could not resolve a base URL. Pass baseUrl, configure an environment, or define OpenAPI servers[0].url.");
+    }
+    const commands = createRuntimeNodes(document, config);
+    const client = defineClient({ ...clientOptions, baseUrl: resolvedBaseUrl, commands });
+    await resolved.commit?.();
+    return client;
 }
 async function resolveDocument(source, options) {
     if (typeof source !== "string" && !(source instanceof URL)) {
-        return source;
+        return { document: source };
+    }
+    const sourceUrl = source instanceof URL ? source : tryParseUrl(source);
+    if (sourceUrl !== null && (sourceUrl.protocol === "http:" || sourceUrl.protocol === "https:")) {
+        const loaded = await loadCachedOpenApiSource(sourceUrl, {
+            cache: options.cache ?? resolveDefaultCache(options),
+            fetch: options.fetch ?? globalThis.fetch,
+            fs: options.fs ?? fs,
+            onTimeout: options.onTimeout,
+            timeoutMs: options.timeoutMs ?? DEFAULT_OPENAPI_FETCH_TIMEOUT_MS
+        });
+        return {
+            document: loaded.document,
+            ...(loaded.commit === undefined ? {} : { commit: loaded.commit })
+        };
     }
     const sourceText = await readOpenApiSourceText(source, {
         cwd: options.cwd ?? process.cwd(),
         fetch: options.fetch ?? globalThis.fetch,
         fs: options.fs ?? fs
     });
-    return parseOpenApiDocument(sourceText, source);
+    return { document: parseOpenApiDocument(sourceText, source) };
+}
+function resolveDefaultCache(options) {
+    if (options.fetch !== undefined) {
+        return false;
+    }
+    const configured = Object.prototype.hasOwnProperty.call(process.env, "TOOLCRAFT_OPENAPI_CACHE")
+        ? process.env.TOOLCRAFT_OPENAPI_CACHE?.trim().toLowerCase()
+        : undefined;
+    return configured === "0" || configured === "false" ? false : {};
+}
+function tryParseUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
 }
 export function resolveOpenApiBaseUrl(options) {
     const environments = options.environments;
@@ -49,17 +101,24 @@ export function resolveOpenApiBaseUrl(options) {
 function normalizeBaseUrl(value) {
     return new URL(value).toString().replace(/\/$/, "");
 }
-function createRuntimeGroups(commands) {
-    return groupByNoun(commands).map(({ noun, commands: nounCommands }) => defineGroup({
-        name: noun,
-        children: nounCommands.map((command) => createRuntimeCommand(command))
-    }));
+function createRuntimeNodes(document, config) {
+    const commands = collectGeneratedCommands(document, config);
+    const tagDescriptions = collectTagDescriptions(document);
+    return [
+        ...commands.filter((command) => command.topLevel).map(createRuntimeCommand),
+        ...groupByNoun(commands).map(({ noun, commands: nounCommands }) => defineGroup({
+            name: noun,
+            description: tagDescriptions.get(noun),
+            children: nounCommands.map(createRuntimeCommand)
+        }))
+    ];
 }
 function createRuntimeCommand(command) {
     const paramsSchema = S.Object(Object.fromEntries(command.params.map((param) => [param.paramName, createRuntimeParamSchema(param)])), command.paramsSchemaOptions);
     return defineCommand({
         name: command.verb,
         ...(command.description === undefined ? {} : { description: command.description }),
+        ...(command.examples === undefined ? {} : { examples: command.examples }),
         scope: RUNTIME_COMMAND_SCOPE,
         ...(command.confirm ? { confirm: true } : {}),
         ...(command.positional.length > 0 ? { positional: command.positional } : {}),
@@ -90,22 +149,32 @@ function createRuntimeHandler(command) {
             tokenSource,
             fetch,
             diagnostics,
+            ...(command.rawResponse === true ? { rawResponse: params.rawResponse } : {}),
+            ...(command.idempotencyHeader === undefined
+                ? {}
+                : {
+                    idempotency: {
+                        header: command.idempotencyHeader,
+                        enabled: true,
+                        key: params.idempotencyKey
+                    }
+                }),
             ...preparedRequestShape
         });
         return writeBinaryResponseOutput(result, command.responseMode === "binary" ? params.output : undefined, { fs, env });
     };
 }
 function createRuntimeParamSchema(param) {
-    const definition = createRuntimeDefinition(param.definition, param.description, param.shortFlag, param.scope, param.global);
+    const definition = createRuntimeDefinition(param.definition, param.description, param.shortFlag, param.longAliases, param.scope, param.global);
     return param.optional ? S.Optional(definition) : definition;
 }
-function createRuntimeDefinition(definition, description, shortFlag, scope, global) {
-    const options = createRuntimeSchemaOptions(definition, description, shortFlag, scope, global);
+function createRuntimeDefinition(definition, description, shortFlag, longAliases, scope, global) {
+    const options = createRuntimeSchemaOptions(definition, description, shortFlag, longAliases, scope, global);
     return RUNTIME_DEFINITION_BUILDERS[definition.kind](definition, options);
 }
 const RUNTIME_DEFINITION_BUILDERS = {
     array: (definition, options) => {
-        const itemDefinition = createRuntimeDefinition(definition.itemDefinition, undefined, undefined, undefined);
+        const itemDefinition = createRuntimeDefinition(definition.itemDefinition, undefined, undefined, undefined, undefined);
         return options === undefined ? S.Array(itemDefinition) : S.Array(itemDefinition, options);
     },
     boolean: (_definition, options) => (options === undefined ? S.Boolean() : S.Boolean(options)),
@@ -114,18 +183,19 @@ const RUNTIME_DEFINITION_BUILDERS = {
     number: (_definition, options) => (options === undefined ? S.Number() : S.Number(options)),
     object: (definition, options) => {
         const shape = Object.fromEntries(definition.properties.map((property) => {
-            const propertySchema = createRuntimeDefinition(property.definition, undefined, undefined, undefined);
+            const propertySchema = createRuntimeDefinition(property.definition, undefined, undefined, undefined, undefined);
             return [property.name, property.optional ? S.Optional(propertySchema) : propertySchema];
         }));
         return options === undefined ? S.Object(shape) : S.Object(shape, options);
     },
     string: (_definition, options) => (options === undefined ? S.String() : S.String(options))
 };
-function createRuntimeSchemaOptions(definition, description, shortFlag, scope, global) {
+function createRuntimeSchemaOptions(definition, description, shortFlag, longAliases, scope, global) {
     const options = Object.fromEntries(collectSchemaOptionEntries({
         definition,
         description,
         shortFlag,
+        longAliases,
         scope,
         global
     }).map(({ key, value }) => [key, Array.isArray(value) ? [...value] : value]));

package/dist/spec-cache.d.ts

@@ -0,0 +1,41 @@
+import { type OpenApiSourceFileSystem } from "./spec-source.js";
+import type { OpenApiDocument } from "./generate.js";
+export declare const DEFAULT_OPENAPI_FETCH_TIMEOUT_MS = 3000;
+export declare const DEFAULT_OPENAPI_CACHE_MAX_AGE_MS: number;
+export interface OpenApiSpecCacheOptions {
+    directory?: string;
+    maxAgeMs?: number;
+    onFallback?: (message: string) => void | Promise<void>;
+}
+export interface LoadCachedOpenApiSourceOptions {
+    cache: false | OpenApiSpecCacheOptions;
+    fetch: typeof globalThis.fetch;
+    fs: OpenApiSpecCacheFileSystem;
+    onTimeout?: (context: OpenApiTimeoutContext) => void | Promise<void>;
+    timeoutMs?: number;
+}
+export interface OpenApiTimeoutContext {
+    source: string;
+    timeoutMs: number;
+    usingCachedDocument: boolean;
+}
+export interface OpenApiSpecCacheFileSystem extends OpenApiSourceFileSystem {
+    writeFile?(filePath: string, contents: string, options?: {
+        encoding?: BufferEncoding;
+        flag?: string;
+        mode?: number;
+    }): Promise<void>;
+    rename?(fromPath: string, toPath: string): Promise<void>;
+    mkdir?(directoryPath: string, options?: {
+        recursive?: boolean;
+        mode?: number;
+    }): Promise<unknown>;
+    unlink?(filePath: string): Promise<void>;
+    realpath?(filePath: string): Promise<string>;
+}
+export interface LoadedOpenApiSource {
+    sourceText: string;
+    document: OpenApiDocument;
+    commit?: () => Promise<void>;
+}
+export declare function loadCachedOpenApiSource(inputUrl: URL, options: LoadCachedOpenApiSourceOptions): Promise<LoadedOpenApiSource>;

package/dist/spec-cache.js

@@ -0,0 +1,376 @@
+import { createHash, randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+import { UserError } from "toolcraft";
+import { hasOwnErrorCode } from "./error-codes.js";
+import { fetchOpenApiHttpSource, OpenApiTimeoutError, OpenApiTransportError, parseOpenApiDocument } from "./spec-source.js";
+import { redactSensitiveQueryValues } from "./redaction.js";
+export const DEFAULT_OPENAPI_FETCH_TIMEOUT_MS = 3_000;
+export const DEFAULT_OPENAPI_CACHE_MAX_AGE_MS = 5 * 60_000;
+export async function loadCachedOpenApiSource(inputUrl, options) {
+    validateTimeout(options.timeoutMs);
+    if (options.cache === false) {
+        let result;
+        try {
+            result = await fetchOpenApiHttpSource(inputUrl, options.fetch, {
+                timeoutMs: options.timeoutMs
+            });
+        }
+        catch (error) {
+            notifyTimeout(options, inputUrl, error, false);
+            throw error;
+        }
+        if (result.status === "not-modified") {
+            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: received 304 without a cached document.`);
+        }
+        return {
+            sourceText: result.sourceText,
+            document: parseOpenApiDocument(result.sourceText, inputUrl)
+        };
+    }
+    validateMaxAge(options.cache.maxAgeMs);
+    const directory = resolveCacheDirectory(options.cache.directory);
+    const cachePath = resolveCachePath(inputUrl, directory);
+    const cached = await readCacheEntry(cachePath, options.fs);
+    const now = Date.now();
+    const freshnessMs = cached?.entry.maxAgeMs;
+    if (cached !== null &&
+        cached.entry.validatedAt <= now &&
+        freshnessMs !== undefined &&
+        now - cached.entry.validatedAt < freshnessMs) {
+        return {
+            sourceText: cached.entry.sourceText,
+            document: cached.document
+        };
+    }
+    let result;
+    try {
+        result = await fetchOpenApiHttpSource(inputUrl, options.fetch, {
+            ...(cached?.entry.etag === undefined ? {} : { etag: cached.entry.etag }),
+            timeoutMs: options.timeoutMs
+        });
+    }
+    catch (error) {
+        notifyTimeout(options, inputUrl, error, cached !== null);
+        if (!(error instanceof OpenApiTransportError) || cached === null) {
+            throw error;
+        }
+        notifyFallback(options.cache, inputUrl, error);
+        return {
+            sourceText: cached.entry.sourceText,
+            document: cached.document
+        };
+    }
+    const writableFs = getWritableFileSystem(options.fs);
+    if (result.status === "not-modified") {
+        if (cached === null) {
+            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: received 304 without a cached document.`);
+        }
+        if (cached.entry.etag === undefined) {
+            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: received 304 without a cached validator.`);
+        }
+        const policy = result.cacheControl === undefined
+            ? {
+                store: true,
+                maxAgeMs: Math.max(0, cached.entry.maxAgeMs - (parseDeltaSeconds(result.age ?? "") ?? 0) * 1_000)
+            }
+            : resolveCachePolicy(result.cacheControl, result.age, options.cache.maxAgeMs, cached.entry.maxAgeMs);
+        if (!policy.store) {
+            return {
+                sourceText: cached.entry.sourceText,
+                document: cached.document,
+                ...(writableFs === null ? {} : { commit: () => removeCacheEntry(cachePath, writableFs) })
+            };
+        }
+        const entry = {
+            ...cached.entry,
+            validatedAt: now,
+            maxAgeMs: policy.maxAgeMs,
+            ...(result.etag === undefined ? {} : { etag: result.etag })
+        };
+        return {
+            sourceText: cached.entry.sourceText,
+            document: cached.document,
+            ...(writableFs === null
+                ? {}
+                : { commit: () => persistCacheEntry(cachePath, entry, writableFs) })
+        };
+    }
+    const policy = resolveCachePolicy(result.cacheControl, result.age, options.cache.maxAgeMs, DEFAULT_OPENAPI_CACHE_MAX_AGE_MS);
+    const document = parseOpenApiDocument(result.sourceText, inputUrl);
+    if (!policy.store) {
+        return {
+            sourceText: result.sourceText,
+            document,
+            ...(writableFs === null ? {} : { commit: () => removeCacheEntry(cachePath, writableFs) })
+        };
+    }
+    const entry = {
+        version: 1,
+        sourceText: result.sourceText,
+        validatedAt: now,
+        maxAgeMs: policy.maxAgeMs,
+        ...(result.etag === undefined ? {} : { etag: result.etag })
+    };
+    return {
+        sourceText: result.sourceText,
+        document,
+        ...(writableFs === null
+            ? {}
+            : { commit: () => persistCacheEntry(cachePath, entry, writableFs) })
+    };
+}
+function notifyTimeout(options, inputUrl, error, usingCachedDocument) {
+    if (!(error instanceof OpenApiTimeoutError) || options.onTimeout === undefined) {
+        return;
+    }
+    try {
+        void Promise.resolve(options.onTimeout({
+            source: redactSensitiveQueryValues(inputUrl.toString()),
+            timeoutMs: error.timeoutMs,
+            usingCachedDocument
+        })).catch(() => undefined);
+    }
+    catch {
+        // A presentation hook cannot change source-loading behavior.
+    }
+}
+function resolveCachePolicy(cacheControl, age, configuredMaxAgeMs, fallbackMaxAgeMs) {
+    const directives = (cacheControl ?? "")
+        .split(",")
+        .map((directive) => directive.trim().toLowerCase());
+    if (directives.includes("no-store")) {
+        return { store: false, maxAgeMs: 0 };
+    }
+    if (directives.includes("no-cache")) {
+        return { store: true, maxAgeMs: 0 };
+    }
+    for (const directive of directives) {
+        if (!directive.startsWith("max-age=")) {
+            continue;
+        }
+        const seconds = parseDeltaSeconds(directive.slice("max-age=".length));
+        if (seconds !== null) {
+            const responseAge = parseDeltaSeconds(age ?? "") ?? 0;
+            return { store: true, maxAgeMs: Math.max(0, seconds - responseAge) * 1_000 };
+        }
+    }
+    return {
+        store: true,
+        maxAgeMs: configuredMaxAgeMs ?? fallbackMaxAgeMs
+    };
+}
+function parseDeltaSeconds(value) {
+    const trimmed = value.trim();
+    const unquoted = trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')
+        ? trimmed.slice(1, -1)
+        : trimmed;
+    if (unquoted.length === 0) {
+        return null;
+    }
+    const seconds = Number(unquoted);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds : null;
+}
+function resolveCacheDirectory(configuredDirectory) {
+    const envDirectory = readOwnEnvValue(process.env, "TOOLCRAFT_OPENAPI_CACHE_DIR");
+    const xdgCacheHome = readOwnEnvValue(process.env, "XDG_CACHE_HOME");
+    const directory = configuredDirectory ?? envDirectory;
+    if (directory !== undefined) {
+        if (!path.isAbsolute(directory)) {
+            throw new UserError("OpenAPI cache directory must be an absolute path.");
+        }
+        return directory;
+    }
+    const cacheRoot = xdgCacheHome ?? path.join(os.homedir(), ".cache");
+    if (!path.isAbsolute(cacheRoot)) {
+        throw new UserError("XDG_CACHE_HOME must be an absolute path.");
+    }
+    return path.join(cacheRoot, "toolcraft-openapi", "specs");
+}
+function resolveCachePath(inputUrl, directory) {
+    const canonicalUrl = new URL(inputUrl);
+    canonicalUrl.hash = "";
+    const key = createHash("sha256").update(canonicalUrl.toString()).digest("hex");
+    return path.join(directory, `${key}.json`);
+}
+async function readCacheEntry(cachePath, fs) {
+    if (!hasRealpath(fs)) {
+        return null;
+    }
+    try {
+        await assertSafeCachePath(cachePath, fs);
+        const parsed = JSON.parse(await fs.readFile(cachePath, "utf8"));
+        if (!isCacheEntry(parsed)) {
+            return null;
+        }
+        return {
+            entry: sanitizeCacheEntry(parsed),
+            document: parseOpenApiDocument(parsed.sourceText, cachePath)
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function sanitizeCacheEntry(entry) {
+    if (entry.etag === undefined || isValidEtag(entry.etag)) {
+        return entry;
+    }
+    const withoutEtag = { ...entry };
+    delete withoutEtag.etag;
+    return withoutEtag;
+}
+function isValidEtag(etag) {
+    try {
+        new Headers({ "If-None-Match": etag });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function persistCacheEntry(cachePath, entry, fs) {
+    try {
+        await assertSafeCachePath(cachePath, fs);
+        await fs.mkdir(path.dirname(cachePath), { recursive: true, mode: 0o700 });
+        await assertSafeCachePath(cachePath, fs);
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const temporaryPath = `${cachePath}.${randomUUID()}.tmp`;
+            let temporaryCreated = false;
+            try {
+                await fs.writeFile(temporaryPath, JSON.stringify(entry), {
+                    encoding: "utf8",
+                    flag: "wx",
+                    mode: 0o600
+                });
+                temporaryCreated = true;
+                await fs.rename(temporaryPath, cachePath);
+                return;
+            }
+            catch (error) {
+                if (temporaryCreated || !hasOwnErrorCode(error, "EEXIST")) {
+                    await fs.unlink(temporaryPath).catch(() => undefined);
+                }
+                if (!hasOwnErrorCode(error, "EEXIST")) {
+                    return;
+                }
+            }
+        }
+    }
+    catch {
+        // Cache writes are best-effort; the materialized live document remains usable.
+    }
+}
+async function removeCacheEntry(cachePath, fs) {
+    try {
+        await assertSafeCachePath(cachePath, fs);
+        await fs.unlink(cachePath);
+    }
+    catch {
+        // Cache removal is best-effort; the materialized live document remains usable.
+    }
+}
+function getWritableFileSystem(fs) {
+    if (typeof fs.writeFile !== "function" ||
+        typeof fs.rename !== "function" ||
+        typeof fs.mkdir !== "function" ||
+        typeof fs.unlink !== "function" ||
+        typeof fs.realpath !== "function") {
+        return null;
+    }
+    return fs;
+}
+function hasRealpath(fs) {
+    return typeof fs.realpath === "function";
+}
+async function assertSafeCachePath(cachePath, fs) {
+    const directory = path.resolve(path.dirname(cachePath));
+    let existingPath = directory;
+    while (true) {
+        try {
+            if (path.resolve(await fs.realpath(existingPath)) !== existingPath) {
+                throw new UserError("OpenAPI cache path must remain inside its configured directory.");
+            }
+            break;
+        }
+        catch (error) {
+            if (!hasOwnErrorCode(error, "ENOENT")) {
+                throw error;
+            }
+            const parentPath = path.dirname(existingPath);
+            if (parentPath === existingPath) {
+                throw error;
+            }
+            existingPath = parentPath;
+        }
+    }
+    try {
+        if (path.resolve(await fs.realpath(directory)) !== directory) {
+            throw new UserError("OpenAPI cache path must remain inside its configured directory.");
+        }
+    }
+    catch (error) {
+        if (hasOwnErrorCode(error, "ENOENT")) {
+            return;
+        }
+        throw error;
+    }
+    try {
+        const canonicalCachePath = path.resolve(await fs.realpath(cachePath));
+        if (canonicalCachePath !== path.resolve(cachePath)) {
+            throw new UserError("OpenAPI cache path must remain inside its configured directory.");
+        }
+    }
+    catch (error) {
+        if (!hasOwnErrorCode(error, "ENOENT")) {
+            throw error;
+        }
+    }
+}
+function isCacheEntry(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const entry = value;
+    return (Object.hasOwn(entry, "version") &&
+        entry.version === 1 &&
+        Object.hasOwn(entry, "sourceText") &&
+        typeof entry.sourceText === "string" &&
+        Object.hasOwn(entry, "validatedAt") &&
+        typeof entry.validatedAt === "number" &&
+        Number.isFinite(entry.validatedAt) &&
+        Object.hasOwn(entry, "maxAgeMs") &&
+        typeof entry.maxAgeMs === "number" &&
+        Number.isFinite(entry.maxAgeMs) &&
+        entry.maxAgeMs >= 0 &&
+        (!Object.hasOwn(entry, "etag") || typeof entry.etag === "string"));
+}
+function notifyFallback(cache, inputUrl, error) {
+    if (cache.onFallback === undefined) {
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    try {
+        void Promise.resolve(cache.onFallback(`Using cached OpenAPI document for ${JSON.stringify(redactSensitiveQueryValues(inputUrl.toString()))} because refresh failed: ${message}`)).catch(() => undefined);
+    }
+    catch {
+        // Cache fallback remains usable even if a presentation callback fails.
+    }
+}
+function validateTimeout(timeoutMs) {
+    if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
+        throw new UserError("OpenAPI fetch timeout must be a finite non-negative number.");
+    }
+}
+function validateMaxAge(maxAgeMs) {
+    if (maxAgeMs !== undefined && (!Number.isFinite(maxAgeMs) || maxAgeMs < 0)) {
+        throw new UserError("OpenAPI cache maxAgeMs must be a finite non-negative number.");
+    }
+}
+function readOwnEnvValue(env, key) {
+    if (!Object.prototype.hasOwnProperty.call(env, key)) {
+        return undefined;
+    }
+    const value = env[key]?.trim();
+    return value === undefined || value.length === 0 ? undefined : value;
+}

package/dist/spec-source.d.ts

@@ -1,3 +1,4 @@
+import { UserError } from "toolcraft";
 import type { OpenApiDocument } from "./generate.js";
 export interface OpenApiSourceFileSystem {
     readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
@@ -7,5 +8,30 @@ export interface OpenApiSourceServices {
     fetch: typeof globalThis.fetch;
     fs: OpenApiSourceFileSystem;
 }
+export interface OpenApiHttpSourceOptions {
+    etag?: string;
+    timeoutMs?: number;
+}
+export type OpenApiHttpSourceResult = {
+    status: "modified";
+    sourceText: string;
+    etag?: string;
+    cacheControl?: string;
+    age?: string;
+} | {
+    status: "not-modified";
+    etag?: string;
+    cacheControl?: string;
+    age?: string;
+};
+export declare class OpenApiHttpStatusError extends UserError {
+}
+export declare class OpenApiTransportError extends UserError {
+}
+export declare class OpenApiTimeoutError extends OpenApiTransportError {
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number, options?: ErrorOptions);
+}
 export declare function readOpenApiSourceText(input: string | URL, services: OpenApiSourceServices): Promise<string>;
+export declare function fetchOpenApiHttpSource(inputUrl: URL, fetch: typeof globalThis.fetch, options?: OpenApiHttpSourceOptions): Promise<OpenApiHttpSourceResult>;
 export declare function parseOpenApiDocument(sourceText: string, input: string | URL): OpenApiDocument;

package/dist/spec-source.js

@@ -4,6 +4,18 @@ import { parse as parseYaml } from "yaml";
 import { UserError } from "toolcraft";
 import { renderSourceSnippet } from "toolcraft/source-snippet";
 import { classifyNetworkError } from "./network-error.js";
+import { redactSensitiveQueryValues } from "./redaction.js";
+export class OpenApiHttpStatusError extends UserError {
+}
+export class OpenApiTransportError extends UserError {
+}
+export class OpenApiTimeoutError extends OpenApiTransportError {
+    timeoutMs;
+    constructor(message, timeoutMs, options) {
+        super(message, options);
+        this.timeoutMs = timeoutMs;
+    }
+}
 export async function readOpenApiSourceText(input, services) {
     const inputUrl = input instanceof URL ? input : tryParseUrl(input);
     const sourceLabel = formatSourceLabel(input);
@@ -20,38 +32,132 @@ export async function readOpenApiSourceText(input, services) {
         if (inputUrl.protocol !== "http:" && inputUrl.protocol !== "https:") {
             throw new UserError(`Unsupported OpenAPI input URL protocol ${JSON.stringify(inputUrl.protocol)}.`);
         }
+        const result = await fetchOpenApiHttpSource(inputUrl, services.fetch);
+        if (result.status === "not-modified") {
+            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: received 304 without a cached document.`);
+        }
+        return result.sourceText;
+    }
+    catch (error) {
+        if (error instanceof UserError) {
+            throw error;
+        }
+        throw new UserError(`Failed to read OpenAPI document ${JSON.stringify(sourceLabel)}: ${getErrorMessage(error)}`);
+    }
+}
+export async function fetchOpenApiHttpSource(inputUrl, fetch, options = {}) {
+    validateTimeout(options.timeoutMs);
+    const url = inputUrl.toString();
+    const timeoutMs = options.timeoutMs;
+    const controller = timeoutMs === undefined || timeoutMs === 0 ? undefined : new AbortController();
+    const requestInit = createOpenApiRequestInit(options.etag, controller?.signal);
+    const request = async () => {
         let response;
         try {
-            response = await services.fetch(inputUrl.toString());
+            response = requestInit === undefined ? await fetch(url) : await fetch(url, requestInit);
         }
         catch (error) {
-            throw classifyNetworkError(error, inputUrl.toString()) ?? error;
+            throw toTransportError(error, url) ?? error;
+        }
+        if (response.status === 304) {
+            return {
+                status: "not-modified",
+                ...readResponseCacheHeaders(response)
+            };
         }
         if (!response.ok) {
             const contentType = response.headers.get("content-type") ?? "";
             const text = await response.text().catch(() => "");
             const snippet = text.length === 0 ? "" : `\n  body: ${truncate(text, 500)}`;
-            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: ` +
+            throw new OpenApiHttpStatusError(`Failed to fetch ${JSON.stringify(url)}: ` +
                 `${response.status} ${response.statusText}` +
                 (contentType ? ` (content-type: ${contentType})` : "") +
                 snippet);
         }
-        return await response.text();
+        try {
+            return {
+                status: "modified",
+                sourceText: await response.text(),
+                ...readResponseCacheHeaders(response)
+            };
+        }
+        catch (error) {
+            throw (toTransportError(error, url) ??
+                new OpenApiTransportError(`Failed to read the OpenAPI response body from ${JSON.stringify(redactSensitiveQueryValues(url))}.`, { cause: error }));
+        }
+    };
+    if (controller === undefined || timeoutMs === undefined) {
+        return await request();
     }
-    catch (error) {
-        if (error instanceof UserError) {
-            throw error;
+    const timeoutCause = Object.assign(new Error("OpenAPI request timed out"), {
+        code: "ETIMEDOUT",
+        timeout: timeoutMs
+    });
+    const classified = classifyNetworkError(timeoutCause, url);
+    const timeoutError = new OpenApiTimeoutError(classified?.message ?? `OpenAPI request timed out after ${timeoutMs}ms.`, timeoutMs, { cause: timeoutCause });
+    let timeout;
+    try {
+        return await Promise.race([
+            request(),
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => {
+                    reject(timeoutError);
+                    controller.abort(timeoutError);
+                }, timeoutMs);
+            })
+        ]);
+    }
+    finally {
+        if (timeout !== undefined) {
+            clearTimeout(timeout);
         }
-        throw new UserError(`Failed to read OpenAPI document ${JSON.stringify(sourceLabel)}: ${getErrorMessage(error)}`);
+    }
+}
+function toTransportError(error, url) {
+    if (error instanceof OpenApiTransportError) {
+        return error;
+    }
+    const classified = classifyNetworkError(error, url);
+    return classified === null
+        ? null
+        : new OpenApiTransportError(classified.message, { cause: error });
+}
+function createOpenApiRequestInit(etag, signal) {
+    if (etag === undefined && signal === undefined) {
+        return undefined;
+    }
+    return {
+        ...(etag === undefined ? {} : { headers: { "If-None-Match": etag } }),
+        ...(signal === undefined ? {} : { signal })
+    };
+}
+function readResponseCacheHeaders(response) {
+    const etag = response.headers.get("etag") ?? undefined;
+    const cacheControl = response.headers.get("cache-control") ?? undefined;
+    const age = response.headers.get("age") ?? undefined;
+    return {
+        ...(etag === undefined ? {} : { etag }),
+        ...(cacheControl === undefined ? {} : { cacheControl }),
+        ...(age === undefined ? {} : { age })
+    };
+}
+function validateTimeout(timeoutMs) {
+    if (timeoutMs !== undefined && (!Number.isFinite(timeoutMs) || timeoutMs < 0)) {
+        throw new UserError("OpenAPI fetch timeout must be a finite non-negative number.");
     }
 }
 export function parseOpenApiDocument(sourceText, input) {
     let parsed;
     try {
-        parsed = parseYaml(sourceText);
+        parsed = JSON.parse(sourceText);
     }
-    catch (error) {
-        throw new UserError(`Failed to parse OpenAPI document ${JSON.stringify(formatSourceLabel(input))}: ${formatParseErrorMessage(error, sourceText, formatSourceLabel(input))}`);
+    catch {
+        try {
+            parsed = parseYaml(sourceText);
+        }
+        catch (error) {
+            throw new UserError(`Failed to parse OpenAPI document ${JSON.stringify(formatSourceLabel(input))}: ${formatParseErrorMessage(error, sourceText, formatSourceLabel(input))}`);
+        }
     }
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
         throw new UserError(`OpenAPI document ${JSON.stringify(formatSourceLabel(input))} must parse to an object.`);

package/node_modules/toolcraft-schema/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-schema",
-  "version": "0.0.138",
+  "version": "0.0.140",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-openapi",
-  "version": "0.0.138",
+  "version": "0.0.140",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -30,7 +30,7 @@
     "toolcraft-openapi-generate": "dist/bin/generate.js"
   },
   "dependencies": {
-    "toolcraft": "0.0.138",
+    "toolcraft": "0.0.140",
     "auth-store": "^0.0.1",
     "fast-string-width": "^3.0.2",
     "fast-wrap-ansi": "^0.2.0",
@@ -46,7 +46,7 @@
     "directory": "packages/toolcraft-openapi"
   },
   "optionalDependencies": {
-    "toolcraft-schema": "0.0.138",
+    "toolcraft-schema": "0.0.140",
     "toolcraft-design": "*",
     "@poe-code/frontmatter": "*"
   },