toolcraft-openapi 0.0.1

package/dist/group-by-noun.d.ts

@@ -0,0 +1,6 @@
+import type { GeneratedCommand } from "./generate.js";
+export interface GeneratedCommandGroup {
+    noun: string;
+    commands: GeneratedCommand[];
+}
+export declare function groupByNoun(commands: ReadonlyArray<GeneratedCommand>): GeneratedCommandGroup[];

package/dist/group-by-noun.js

@@ -0,0 +1,17 @@
+export function groupByNoun(commands) {
+    const groups = new Map();
+    for (const command of commands) {
+        const current = groups.get(command.noun);
+        if (current === undefined) {
+            groups.set(command.noun, [command]);
+            continue;
+        }
+        current.push(command);
+    }
+    return [...groups.entries()]
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([noun, nounCommands]) => ({
+        noun,
+        commands: nounCommands.slice().sort((left, right) => left.verb.localeCompare(right.verb))
+    }));
+}

package/dist/http.d.ts

@@ -0,0 +1,26 @@
+import type { TokenSource } from "./auth/types.js";
+type QueryScalar = string | number | boolean | null | undefined;
+export type QueryValue = QueryScalar | QueryScalar[];
+export interface HttpRequestOptions {
+    baseUrl: string;
+    path: string;
+    method: string;
+    tokenSource: TokenSource;
+    auth: "required" | "none";
+    fetch?: typeof globalThis.fetch;
+    pathParams?: Record<string, string | number | boolean>;
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    dryRun?: boolean;
+    verbose?: boolean;
+    signal?: AbortSignal;
+    writeStdout?: (chunk: string) => void;
+    writeStderr?: (chunk: string) => void;
+}
+export declare class HttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown, message?: string);
+}
+export declare function requestJson<TResult = unknown>(options: HttpRequestOptions): Promise<TResult | undefined>;
+export {};

package/dist/http.js

@@ -0,0 +1,123 @@
+import { UserError } from "agent-kit";
+export class HttpError extends Error {
+    status;
+    body;
+    constructor(status, body, message = `HTTP ${status}`) {
+        super(message);
+        this.name = "HttpError";
+        this.status = status;
+        this.body = body;
+    }
+}
+export async function requestJson(options) {
+    const token = options.auth === "none" ? undefined : await options.tokenSource.getToken();
+    const method = options.method.toUpperCase();
+    const hasBody = options.body !== undefined;
+    const serializedBody = hasBody ? JSON.stringify(options.body) : undefined;
+    const url = buildRequestUrl(options);
+    const headers = createHeaders(token, hasBody);
+    const writeStdout = options.writeStdout ?? process.stdout.write.bind(process.stdout);
+    const writeStderr = options.writeStderr ?? process.stderr.write.bind(process.stderr);
+    const requestLine = `${method} ${url}`;
+    if (options.verbose) {
+        writeStderr(`${requestLine}\n`);
+    }
+    if (options.dryRun) {
+        writeStdout(formatDryRunOutput(requestLine, headers, options.body));
+        return undefined;
+    }
+    const response = await (options.fetch ?? globalThis.fetch)(url, {
+        method,
+        headers,
+        body: serializedBody,
+        signal: options.signal,
+    });
+    const text = await response.text();
+    const contentType = response.headers.get("content-type");
+    if (response.ok) {
+        if (text.length === 0) {
+            return undefined;
+        }
+        if (!isJsonContentType(contentType)) {
+            throw new HttpError(response.status, text, `Expected a JSON response body but received content-type ${JSON.stringify(contentType ?? "<missing>")}.`);
+        }
+        return JSON.parse(text);
+    }
+    if (response.status === 401) {
+        await options.tokenSource.invalidate?.();
+    }
+    throw new HttpError(response.status, parseResponseBody(text, contentType));
+}
+function buildRequestUrl(options) {
+    const resolvedPath = substitutePathParams(options.path, options.pathParams);
+    const baseUrl = new URL(options.baseUrl);
+    const normalizedBasePath = baseUrl.pathname.endsWith("/")
+        ? baseUrl.pathname.slice(0, -1)
+        : baseUrl.pathname;
+    const normalizedPath = resolvedPath.startsWith("/") ? resolvedPath : `/${resolvedPath}`;
+    baseUrl.pathname = `${normalizedBasePath}${normalizedPath}`;
+    for (const [key, value] of Object.entries(options.query ?? {})) {
+        appendQueryValue(baseUrl.searchParams, key, value);
+    }
+    return baseUrl.toString();
+}
+function substitutePathParams(path, pathParams) {
+    const resolvedPath = path.replace(/\{([^}]+)\}/g, (_match, key) => {
+        const value = pathParams?.[key];
+        if (value === undefined) {
+            throw new UserError(`Missing path parameter "${key}".`);
+        }
+        return encodeURIComponent(String(value));
+    });
+    if (resolvedPath.includes("{") || resolvedPath.includes("}")) {
+        throw new UserError(`Invalid path template "${path}".`);
+    }
+    return resolvedPath;
+}
+function appendQueryValue(searchParams, key, value) {
+    const values = Array.isArray(value) ? value : [value];
+    for (const entry of values) {
+        if (entry === undefined) {
+            continue;
+        }
+        searchParams.append(key, entry === null ? "" : String(entry));
+    }
+}
+function createHeaders(token, hasBody) {
+    return {
+        ...(token === undefined ? {} : { Authorization: `Bearer ${token}` }),
+        ...(hasBody ? { "Content-Type": "application/json" } : {}),
+    };
+}
+function formatDryRunOutput(requestLine, headers, body) {
+    const lines = [
+        requestLine,
+        ...Object.entries(headers).map(([key, value]) => {
+            const headerValue = key.toLowerCase() === "authorization" && value.startsWith("Bearer ")
+                ? "Bearer ****"
+                : value;
+            return `${key}: ${headerValue}`;
+        }),
+        "",
+    ];
+    if (body !== undefined) {
+        lines.push(JSON.stringify(body));
+    }
+    return `${lines.join("\n")}\n`;
+}
+function parseResponseBody(text, contentType) {
+    if (text.length === 0) {
+        return undefined;
+    }
+    if (!isJsonContentType(contentType)) {
+        return text;
+    }
+    return JSON.parse(text);
+}
+function isJsonContentType(contentType) {
+    if (contentType === null) {
+        return false;
+    }
+    const normalized = contentType.toLowerCase();
+    return normalized.includes("application/json") || normalized.includes("+json");
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { defineApiCommand } from "./api-command.js";
+export { defineClient } from "./define-client.js";
+export { generate } from "./generate.js";
+export type { GenerateOptions, GeneratedFile, OpenApiDocument } from "./generate.js";
+export { commandsFromSpec, defineClientFromSpec } from "./runtime.js";
+export type { CommandsFromSpecOptions, DefineClientFromSpecOptions, OpenApiDocumentSource } from "./runtime.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";
+export type { BearerTokenAuthOptions } from "./auth/bearer-token-auth.js";
+export { HttpError, requestJson } from "./http.js";
+export type { HttpRequestOptions, QueryValue } from "./http.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { defineApiCommand } from "./api-command.js";
+export { defineClient } from "./define-client.js";
+export { generate } from "./generate.js";
+export { commandsFromSpec, defineClientFromSpec } from "./runtime.js";
+export { bearerTokenAuth } from "./auth/bearer-token-auth.js";
+export { HttpError, requestJson } from "./http.js";

package/dist/interpreter.d.ts

@@ -0,0 +1,6 @@
+import { type RequestSectionKey } from "./request-shape.js";
+import type { GeneratedPreflightBlock, GeneratedRequestField, GeneratedRequestLocation, GeneratedRequestSectionRenders } from "./generate.js";
+export declare function renderPreflightBlock(block: GeneratedPreflightBlock): string[];
+export declare function executePreflightBlocks(blocks: ReadonlyArray<GeneratedPreflightBlock>, params: Readonly<Record<string, unknown>>): Record<string, unknown>;
+export declare function renderRequestShape(requestFields: ReadonlyArray<GeneratedRequestField>, sectionRenders: GeneratedRequestSectionRenders, optionalSections: ReadonlySet<GeneratedRequestLocation>): string[];
+export declare function buildRequestShape(requestFields: ReadonlyArray<GeneratedRequestField>, sectionRenders: GeneratedRequestSectionRenders, optionalSections: ReadonlySet<GeneratedRequestLocation>, params: Readonly<Record<string, unknown>>, resolvedValues: Readonly<Record<string, unknown>>): Partial<Record<RequestSectionKey, unknown>>;

package/dist/interpreter.js

@@ -0,0 +1,289 @@
+import { UserError } from "agent-kit";
+import { isIdentifierName, toCliFlag } from "./naming.js";
+import { REQUEST_PARAM_SECTIONS } from "./request-shape.js";
+const QUERY_ARRAY_SERIALIZATION_SEPARATORS = {
+    comma: ",",
+    pipe: "|"
+};
+const VALUE_REFERENCE_OPERATIONS = {
+    param: {
+        render: (reference) => renderParamAccess(reference.paramName),
+        evaluate: (reference, context) => context.params[reference.paramName]
+    },
+    resolved: {
+        render: (reference) => reference.resolvedName,
+        evaluate: (reference, context) => context.resolvedValues[reference.resolvedName]
+    }
+};
+const VALUE_EXPRESSION_OPERATIONS = {
+    reference: {
+        render: (value) => renderValueReference(value.reference),
+        evaluate: (value, context) => evaluateValueReference(value.reference, context)
+    },
+    queryArray: {
+        render: (value) => renderSerializedQueryArray(renderValueReference(value.reference), value.serialization),
+        evaluate: (value, context) => serializeQueryArrayValue(evaluateValueReference(value.reference, context), value.serialization)
+    }
+};
+const PREFLIGHT_BLOCK_OPERATIONS = {
+    "scalar-null": {
+        render: (block) => {
+            const paramAccess = renderParamAccess(block.paramName);
+            const nullAccess = renderParamAccess(block.nullParamName);
+            return [
+                `    if (${paramAccess} !== undefined && ${paramAccess} !== null && ${nullAccess}) {`,
+                `      throw new UserError(${JSON.stringify(getScalarNullConflictMessage(block))});`,
+                "    }",
+                `    const ${block.resolvedName} = ${nullAccess} ? null : ${paramAccess};`,
+                ...(block.required
+                    ? [
+                        `    if (${block.resolvedName} === undefined) {`,
+                        `      throw new UserError(${JSON.stringify(getMissingRequiredParameterMessage(block.paramName))});`,
+                        "    }"
+                    ]
+                    : [])
+            ];
+        },
+        execute: (block, context) => {
+            const value = context.params[block.paramName];
+            const nullRequested = context.params[block.nullParamName] === true;
+            if (value !== undefined && value !== null && nullRequested) {
+                throw new UserError(getScalarNullConflictMessage(block));
+            }
+            context.resolvedValues[block.resolvedName] = nullRequested ? null : value;
+            if (block.required && context.resolvedValues[block.resolvedName] === undefined) {
+                throw new UserError(getMissingRequiredParameterMessage(block.paramName));
+            }
+        }
+    },
+    array: {
+        render: (block) => {
+            const paramAccess = renderParamAccess(block.paramName);
+            const jsonAccess = renderParamAccess(block.jsonParamName);
+            return [
+                ...(block.nullParamName === undefined
+                    ? []
+                    : [
+                        `    if (${renderParamAccess(block.nullParamName)} && (${paramAccess} !== undefined || ${jsonAccess} !== undefined)) {`,
+                        `      throw new UserError(${JSON.stringify(getArrayNullConflictMessage(block))});`,
+                        "    }"
+                    ]),
+                `    if (${paramAccess} !== undefined && ${jsonAccess} !== undefined) {`,
+                `      throw new UserError(${JSON.stringify(getArrayJsonConflictMessage(block))});`,
+                "    }",
+                `    let ${block.resolvedName} = ${paramAccess};`,
+                `    if (${jsonAccess} !== undefined) {`,
+                "      let parsedJson: unknown;",
+                "      try {",
+                `        parsedJson = JSON.parse(${jsonAccess});`,
+                "      } catch (error) {",
+                `        throw new UserError(${JSON.stringify(getInvalidArrayJsonMessage(block.jsonParamName, "Expected valid JSON."))});`,
+                "      }",
+                "      if (!Array.isArray(parsedJson)) {",
+                `        throw new UserError(${JSON.stringify(getInvalidArrayJsonMessage(block.jsonParamName, "Expected a JSON array."))});`,
+                "      }",
+                `      ${block.resolvedName} = parsedJson;`,
+                "    }",
+                ...(block.nullParamName === undefined
+                    ? []
+                    : [
+                        `    if (${renderParamAccess(block.nullParamName)}) {`,
+                        `      ${block.resolvedName} = null;`,
+                        "    }"
+                    ]),
+                ...(block.required
+                    ? [
+                        `    if (${block.resolvedName} === undefined) {`,
+                        `      throw new UserError(${JSON.stringify(getMissingRequiredParameterMessage(block.paramName))});`,
+                        "    }"
+                    ]
+                    : [])
+            ];
+        },
+        execute: (block, context) => {
+            const directValue = context.params[block.paramName];
+            const jsonValue = context.params[block.jsonParamName];
+            const nullRequested = block.nullParamName !== undefined && context.params[block.nullParamName] === true;
+            if (block.nullParamName !== undefined && nullRequested && (directValue !== undefined || jsonValue !== undefined)) {
+                throw new UserError(getArrayNullConflictMessage(block));
+            }
+            if (directValue !== undefined && jsonValue !== undefined) {
+                throw new UserError(getArrayJsonConflictMessage(block));
+            }
+            let resolved = directValue;
+            if (jsonValue !== undefined) {
+                let parsedJson;
+                try {
+                    parsedJson = JSON.parse(String(jsonValue));
+                }
+                catch {
+                    throw new UserError(getInvalidArrayJsonMessage(block.jsonParamName, "Expected valid JSON."));
+                }
+                if (!Array.isArray(parsedJson)) {
+                    throw new UserError(getInvalidArrayJsonMessage(block.jsonParamName, "Expected a JSON array."));
+                }
+                resolved = parsedJson;
+            }
+            if (nullRequested) {
+                resolved = null;
+            }
+            if (block.required && resolved === undefined) {
+                throw new UserError(getMissingRequiredParameterMessage(block.paramName));
+            }
+            context.resolvedValues[block.resolvedName] = resolved;
+        }
+    }
+};
+const REQUEST_SECTION_OPERATIONS = {
+    inline: {
+        render: (section, sectionFields, optional) => {
+            const [field] = sectionFields;
+            if (field === undefined) {
+                return [];
+            }
+            if (!optional) {
+                return [`      ${section.key}: ${renderValueExpression(field.value)},`];
+            }
+            return [
+                `      ...(${renderOmitWhenUndefinedExpression(field.omitWhenUndefinedReference)}`,
+                "        ? {}",
+                "        : {",
+                `            ${section.key}: ${renderValueExpression(field.value)},`,
+                "          }),"
+            ];
+        },
+        build: (_section, sectionFields, optional, context) => {
+            const [field] = sectionFields;
+            if (field === undefined) {
+                return undefined;
+            }
+            if (optional && evaluateValueReference(field.omitWhenUndefinedReference, context) === undefined) {
+                return undefined;
+            }
+            return evaluateValueExpression(field.value, context);
+        }
+    },
+    wrapped: {
+        render: (section, sectionFields, optional) => {
+            if (!optional) {
+                return [
+                    `      ${section.key}: {`,
+                    ...sectionFields.map((field) => `        ${JSON.stringify(field.wireName)}: ${renderValueExpression(field.value)},`),
+                    "      },"
+                ];
+            }
+            return [
+                `      ...(${sectionFields.map((field) => renderOmitWhenUndefinedExpression(field.omitWhenUndefinedReference)).join(" && ")}`,
+                "        ? {}",
+                "        : {",
+                `            ${section.key}: {`,
+                ...sectionFields.map((field) => `              ${JSON.stringify(field.wireName)}: ${renderValueExpression(field.value)},`),
+                "            },",
+                "          }),"
+            ];
+        },
+        build: (_section, sectionFields, optional, context) => {
+            if (optional &&
+                sectionFields.every((field) => evaluateValueReference(field.omitWhenUndefinedReference, context) === undefined)) {
+                return undefined;
+            }
+            return Object.fromEntries(sectionFields.map((field) => [field.wireName, evaluateValueExpression(field.value, context)]));
+        }
+    }
+};
+export function renderPreflightBlock(block) {
+    return PREFLIGHT_BLOCK_OPERATIONS[block.kind].render(block);
+}
+export function executePreflightBlocks(blocks, params) {
+    const resolvedValues = {};
+    for (const block of blocks) {
+        PREFLIGHT_BLOCK_OPERATIONS[block.kind].execute(block, {
+            params,
+            resolvedValues
+        });
+    }
+    return resolvedValues;
+}
+export function renderRequestShape(requestFields, sectionRenders, optionalSections) {
+    const lines = [];
+    for (const section of REQUEST_PARAM_SECTIONS) {
+        const sectionFields = requestFields.filter((field) => field.location === section.location);
+        if (sectionFields.length === 0) {
+            continue;
+        }
+        const renderKind = sectionRenders[section.location];
+        if (renderKind === undefined) {
+            continue;
+        }
+        lines.push(...REQUEST_SECTION_OPERATIONS[renderKind].render(section, sectionFields, optionalSections.has(section.location)));
+    }
+    return lines;
+}
+export function buildRequestShape(requestFields, sectionRenders, optionalSections, params, resolvedValues) {
+    const requestShape = {};
+    const context = { params, resolvedValues };
+    for (const section of REQUEST_PARAM_SECTIONS) {
+        const sectionFields = requestFields.filter((field) => field.location === section.location);
+        if (sectionFields.length === 0) {
+            continue;
+        }
+        const renderKind = sectionRenders[section.location];
+        if (renderKind === undefined) {
+            continue;
+        }
+        const builtSection = REQUEST_SECTION_OPERATIONS[renderKind].build(section, sectionFields, optionalSections.has(section.location), context);
+        if (builtSection !== undefined) {
+            requestShape[section.key] = builtSection;
+        }
+    }
+    return requestShape;
+}
+function getScalarNullConflictMessage(block) {
+    return `Options "--${toCliFlag(block.paramName)}" and "--${toCliFlag(block.nullParamName)}" are mutually exclusive.`;
+}
+function getArrayNullConflictMessage(block) {
+    const nullParamName = block.nullParamName;
+    if (nullParamName === undefined) {
+        throw new Error("Missing null helper for nullable array preflight block.");
+    }
+    return `Options "--${toCliFlag(nullParamName)}", "--${toCliFlag(block.paramName)}", and "--${toCliFlag(block.jsonParamName)}" cannot be combined.`;
+}
+function getArrayJsonConflictMessage(block) {
+    return `Options "--${toCliFlag(block.paramName)}" and "--${toCliFlag(block.jsonParamName)}" are mutually exclusive.`;
+}
+function getInvalidArrayJsonMessage(paramName, expectation) {
+    return `Invalid value for "--${toCliFlag(paramName)}". ${expectation}`;
+}
+function getMissingRequiredParameterMessage(paramName) {
+    return `Missing required parameter "${toCliFlag(paramName)}".`;
+}
+function renderValueReference(reference) {
+    return VALUE_REFERENCE_OPERATIONS[reference.kind].render(reference);
+}
+function evaluateValueReference(reference, context) {
+    return VALUE_REFERENCE_OPERATIONS[reference.kind].evaluate(reference, context);
+}
+function renderValueExpression(value) {
+    return VALUE_EXPRESSION_OPERATIONS[value.kind].render(value);
+}
+function evaluateValueExpression(value, context) {
+    return VALUE_EXPRESSION_OPERATIONS[value.kind].evaluate(value, context);
+}
+function renderSerializedQueryArray(reference, serialization) {
+    if (serialization === "repeat") {
+        return reference;
+    }
+    return `${reference} === undefined || ${reference} === null ? ${reference} : ${reference}.join(${JSON.stringify(QUERY_ARRAY_SERIALIZATION_SEPARATORS[serialization])})`;
+}
+function serializeQueryArrayValue(value, serialization) {
+    if (serialization === "repeat" || value === undefined || value === null) {
+        return value;
+    }
+    return Array.isArray(value) ? value.join(QUERY_ARRAY_SERIALIZATION_SEPARATORS[serialization]) : value;
+}
+function renderOmitWhenUndefinedExpression(reference) {
+    return `${renderValueReference(reference)} === undefined`;
+}
+function renderParamAccess(name) {
+    return isIdentifierName(name) ? `params.${name}` : `params[${JSON.stringify(name)}]`;
+}

package/dist/lock.d.ts

@@ -0,0 +1,14 @@
+export interface OpenApiLock {
+    specSha: string;
+}
+export interface LockFileSystem {
+    mkdir(directoryPath: string, options?: {
+        recursive?: boolean;
+    }): Promise<unknown>;
+    readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
+    writeFile(filePath: string, contents: string, encoding: BufferEncoding): Promise<void>;
+}
+export declare function parseOpenApiLock(contents: string): OpenApiLock | null;
+export declare function stringifyOpenApiLock(lock: OpenApiLock): string;
+export declare function readOpenApiLock(fs: Pick<LockFileSystem, "readFile">, lockPath: string): Promise<OpenApiLock | null>;
+export declare function writeOpenApiLock(fs: LockFileSystem, lockPath: string, lock: OpenApiLock): Promise<void>;

package/dist/lock.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+export function parseOpenApiLock(contents) {
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        parsed.version !== 1 ||
+        typeof parsed.specSha !== "string" ||
+        parsed.specSha.length === 0) {
+        return null;
+    }
+    return {
+        specSha: parsed.specSha
+    };
+}
+export function stringifyOpenApiLock(lock) {
+    const document = {
+        version: 1,
+        specSha: lock.specSha
+    };
+    return `${JSON.stringify(document, null, 2)}\n`;
+}
+export async function readOpenApiLock(fs, lockPath) {
+    try {
+        return parseOpenApiLock(await fs.readFile(lockPath, "utf8"));
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function writeOpenApiLock(fs, lockPath, lock) {
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    await fs.writeFile(lockPath, stringifyOpenApiLock(lock), "utf8");
+}
+function isNotFoundError(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/dist/naming.d.ts

@@ -0,0 +1,24 @@
+export type HttpMethod = "get" | "post" | "put" | "patch" | "delete";
+type MethodDefaults = {
+    collection: string;
+    resource: string;
+    confirm?: true;
+    genericVerbs?: readonly string[];
+    preferOperationIdWhenPathTailIsGeneric?: true;
+};
+export declare const METHOD_DEFAULTS: Partial<Record<HttpMethod, MethodDefaults>>;
+export declare function deriveNoun(operation: {
+    tags?: string[];
+}, path: string, operationId: string): string;
+export declare function deriveVerb(method: HttpMethod, path: string, operation: {
+    operationId?: string;
+}, operationId: string, noun: string): string;
+export declare function normalizeParamName(name: string): string;
+export declare function toPascalCase(value: string): string;
+export declare function toCamelCase(value: string): string;
+export declare function toKebabCase(value: string): string;
+export declare function toCliFlag(value: string): string;
+export declare function splitWords(value: string): string[];
+export declare function toMcpPrefix(name: string): string;
+export declare function isIdentifierName(value: string): boolean;
+export {};