poe-code 4.0.15 → 4.0.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "poe-code",
-  "version": "4.0.15",
+  "version": "4.0.17",
   "description": "CLI tool to configure Poe API for developer workflows.",
   "license": "MIT",
   "type": "module",

package/packages/plan-browser/dist/browser.d.ts

@@ -9,7 +9,6 @@ export declare function runPlanBrowser(options: {
     fs: DiscoveryFs & Partial<ActionFs>;
     kind?: PlanKind;
     variables?: Record<string, string | undefined>;
-    onCreatePlan?: () => Promise<void>;
     runExplorerImpl?: RunExplorerImpl;
 }): Promise<void>;
 export {};

package/packages/plan-browser/dist/browser.js

@@ -28,8 +28,7 @@ export async function runPlanBrowser(options) {
         plans,
         fs: options.fs,
         variables: options.variables ?? process.env,
-        onRefresh: discover,
-        onCreatePlan: options.onCreatePlan
+        onRefresh: discover
     });
     await (options.runExplorerImpl ?? runExplorer)(config);
 }

package/packages/plan-browser/dist/explorer-config.d.ts

@@ -5,7 +5,6 @@ export interface BuildPlanExplorerConfigOptions {
     fs: ActionFs & DiscoveryFs;
     variables: Record<string, string | undefined>;
     onRefresh: () => Promise<PlanEntry[]>;
-    onCreatePlan?: () => Promise<void>;
     promptSaveReason?: (entry: PlanEntry) => Promise<string | null>;
     loadDetailMarkdown?: (entry: PlanEntry, fs: ActionFs & DiscoveryFs) => Promise<string>;
 }

package/packages/plan-browser/dist/explorer-config.js

@@ -98,19 +98,6 @@ export function buildPlanExplorerConfig(options) {
             }
         }
     ];
-    if (options.onCreatePlan !== undefined) {
-        actions.push({
-            id: "new",
-            key: "n",
-            primary: true,
-            label: "New plan",
-            predicate: () => options.onCreatePlan != null,
-            handler: async (ctx) => {
-                await ctx.suspendAnd(() => options.onCreatePlan());
-                await ctx.refresh();
-            }
-        });
-    }
     return {
         title: "Plans",
         rows: async () => rows,

package/packages/toolcraft-openapi/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/packages/toolcraft-openapi/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/packages/toolcraft-openapi/dist/runtime.d.ts

@@ -2,12 +2,15 @@ import { type CommandNode } from "../../toolcraft/dist/index.js";
 import { type DefineClientOptions, type DefinedClient, type OpenApiClientServices } from "./define-client.js";
 import { type OpenApiDocument } from "./generate.js";
 import type { ToolcraftConfig } from "./config.js";
-import { type OpenApiSourceFileSystem } from "./spec-source.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>, "baseUrl" | "commands"> & CommandsFromSpecOptions & {

package/packages/toolcraft-openapi/dist/runtime.js

@@ -5,15 +5,27 @@ import { collectTagDescriptions, collectSchemaOptionEntries, collectGeneratedCom
 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 createRuntimeNodes(document, options.config);
+    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, config, baseUrl, environment, env, ...clientOptions } = options;
-    const document = await resolveDocument(spec, { cwd, fetch, fs: specFs, config });
+    const { cwd, fetch, fs: specFs, cache, onTimeout, timeoutMs, config, baseUrl, environment, env, ...clientOptions } = options;
+    const resolved = await resolveDocument(spec, {
+        cwd,
+        fetch,
+        fs: specFs,
+        cache,
+        onTimeout,
+        timeoutMs,
+        config
+    });
+    const document = resolved.document;
     const resolvedBaseUrl = baseUrl ??
         resolveOpenApiBaseUrl({
             document,
@@ -25,18 +37,51 @@ export async function defineClientFromSpec(spec, options) {
         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);
-    return defineClient({ ...clientOptions, baseUrl: resolvedBaseUrl, commands });
+    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;

package/packages/toolcraft-openapi/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/packages/toolcraft-openapi/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/packages/toolcraft-openapi/dist/spec-source.d.ts

@@ -1,3 +1,4 @@
+import { UserError } from "../../toolcraft/dist/index.js";
 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;