toolcraft-openapi 0.0.38 → 0.0.40

package/dist/diagnose.js

@@ -0,0 +1,93 @@
+import { DIAGNOSTIC_CODES, createDiagnostic } from "./diagnostics.js";
+export function diagnose(config, document) {
+    const configuredMethods = collectConfiguredMethods(config.resources);
+    return [
+        ...diagnoseDuplicateMethods(configuredMethods),
+        ...diagnoseUnknownPagination(config, configuredMethods),
+        ...diagnoseUnmappedEndpoints(config, document, configuredMethods)
+    ];
+}
+function collectConfiguredMethods(resources) {
+    const methods = [];
+    function visit(resource, path) {
+        for (const [name, method] of Object.entries(resource.methods ?? {})) {
+            methods.push({
+                configPath: [...path, "methods", name].join("."),
+                method
+            });
+        }
+        for (const [name, child] of Object.entries(resource.subresources ?? {})) {
+            visit(child, [...path, "subresources", name]);
+        }
+    }
+    for (const [name, resource] of Object.entries(resources ?? {})) {
+        visit(resource, ["resources", name]);
+    }
+    return methods;
+}
+function diagnoseDuplicateMethods(methods) {
+    const seen = new Map();
+    const diagnostics = [];
+    for (const method of methods) {
+        const key = endpointKey(method.method.method, method.method.path);
+        const existing = seen.get(key);
+        if (existing === undefined) {
+            seen.set(key, method);
+            continue;
+        }
+        diagnostics.push(createDiagnostic({
+            code: DIAGNOSTIC_CODES.duplicateMethodPath,
+            severity: "error",
+            location: method.configPath,
+            message: `${method.configPath} and ${existing.configPath} both bind ${key}.`
+        }));
+    }
+    return diagnostics;
+}
+function diagnoseUnknownPagination(config, methods) {
+    const schemes = new Set(Object.keys(config.pagination ?? {}));
+    return methods
+        .filter((method) => method.method.pagination !== undefined && !schemes.has(method.method.pagination))
+        .map((method) => createDiagnostic({
+        code: DIAGNOSTIC_CODES.unknownPaginationScheme,
+        severity: "error",
+        location: method.configPath,
+        message: `${method.configPath} references undeclared pagination scheme ${JSON.stringify(method.method.pagination)}.`
+    }));
+}
+function diagnoseUnmappedEndpoints(config, document, methods) {
+    if (config.resources === undefined) {
+        return [];
+    }
+    const configured = new Set(methods.map((method) => endpointKey(method.method.method, method.method.path)));
+    const unspecified = new Set((config.unspecified_endpoints ?? []).map(normalizeEndpointText));
+    const diagnostics = [];
+    for (const [path, pathItem] of Object.entries(document.paths ?? {})) {
+        if (pathItem === undefined) {
+            continue;
+        }
+        for (const method of ["get", "post", "put", "patch", "delete", "head", "options"]) {
+            if (!Object.hasOwn(pathItem, method)) {
+                continue;
+            }
+            const key = endpointKey(method, path);
+            if (configured.has(key) || unspecified.has(key)) {
+                continue;
+            }
+            diagnostics.push(createDiagnostic({
+                code: DIAGNOSTIC_CODES.unmappedEndpoint,
+                severity: "error",
+                location: `paths.${path}.${method}`,
+                message: `${method.toUpperCase()} ${path} is not listed in resources or unspecified_endpoints.`
+            }));
+        }
+    }
+    return diagnostics;
+}
+function endpointKey(method, path) {
+    return `${method.toLowerCase()} ${path}`;
+}
+function normalizeEndpointText(value) {
+    const [method, requestPath] = value.trim().split(" ");
+    return `${(method ?? "").toLowerCase()} ${requestPath ?? ""}`;
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,19 @@
+export type DiagnosticSeverity = "error" | "warn";
+export interface Diagnostic {
+    code: string;
+    severity: DiagnosticSeverity;
+    message: string;
+    location?: string;
+}
+export declare const DIAGNOSTIC_CODES: {
+    readonly unmappedEndpoint: "TOOLCRAFT_OPENAPI_001";
+    readonly duplicateMethodPath: "TOOLCRAFT_OPENAPI_002";
+    readonly unknownPaginationScheme: "TOOLCRAFT_OPENAPI_003";
+    readonly specDrift: "TOOLCRAFT_OPENAPI_004";
+    readonly reservedMethodName: "TOOLCRAFT_OPENAPI_005";
+    readonly invalidEdition: "TOOLCRAFT_OPENAPI_006";
+    readonly invalidConfig: "TOOLCRAFT_OPENAPI_007";
+};
+export declare function createDiagnostic(args: Diagnostic): Diagnostic;
+export declare function formatDiagnostic(diagnostic: Diagnostic): string;
+export declare function formatDiagnostics(diagnostics: readonly Diagnostic[]): string;

package/dist/diagnostics.js

@@ -0,0 +1,19 @@
+export const DIAGNOSTIC_CODES = {
+    unmappedEndpoint: "TOOLCRAFT_OPENAPI_001",
+    duplicateMethodPath: "TOOLCRAFT_OPENAPI_002",
+    unknownPaginationScheme: "TOOLCRAFT_OPENAPI_003",
+    specDrift: "TOOLCRAFT_OPENAPI_004",
+    reservedMethodName: "TOOLCRAFT_OPENAPI_005",
+    invalidEdition: "TOOLCRAFT_OPENAPI_006",
+    invalidConfig: "TOOLCRAFT_OPENAPI_007"
+};
+export function createDiagnostic(args) {
+    return args;
+}
+export function formatDiagnostic(diagnostic) {
+    const location = diagnostic.location === undefined ? "" : ` ${diagnostic.location}`;
+    return `${diagnostic.code} ${diagnostic.severity}${location}: ${diagnostic.message}`;
+}
+export function formatDiagnostics(diagnostics) {
+    return diagnostics.map((diagnostic) => `${formatDiagnostic(diagnostic)}\n`).join("");
+}

package/dist/generate.d.ts

@@ -1,4 +1,5 @@
 import { type HttpMethod } from "./naming.js";
+import type { ToolcraftConfig } from "./config.js";
 type OpenApiOperation = OpenApiOperationObject | OpenApiReferenceObject;
 type OpenApiOperationMap = Partial<Record<HttpMethod, OpenApiOperation>>;
 type OpenApiParameterLocation = "path" | "query" | "header" | "cookie";
@@ -12,6 +13,7 @@ export interface OpenApiDocument {
         title?: string;
         version?: string;
     };
+    servers?: OpenApiServerObject[];
     security?: OpenApiSecurityRequirementObject[];
     paths?: Record<string, OpenApiPathItemObject | undefined>;
     components?: {
@@ -98,6 +100,7 @@ type OpenApiSecurityRequirementObject = Record<string, string[]>;
 export interface GenerateOptions {
     specSha: string;
     brand?: string;
+    config?: ToolcraftConfig;
 }
 export interface GeneratedFile {
     path: string;
@@ -110,6 +113,7 @@ export interface GeneratedCommand {
     filePath: string;
     operationId: string;
     description?: string;
+    examples?: GeneratedCommandExample[];
     method: string;
     path: string;
     auth: "required" | "none";
@@ -119,6 +123,8 @@ export interface GeneratedCommand {
     bodyMode?: "json" | "form" | "raw" | "base64" | "multipart";
     contentType?: string;
     multipartBinaryFields?: readonly string[];
+    idempotencyHeader?: string;
+    rawResponse?: boolean;
     confirm: boolean;
     params: GeneratedParam[];
     paramsSchemaOptions?: GeneratedObjectSchemaOptions;
@@ -132,12 +138,17 @@ export interface GeneratedParam {
     sourceName: string;
     location: "path" | "query" | "header" | "body" | "transport";
     description?: string;
+    longAliases?: string[];
     shortFlag?: string;
     scope?: readonly [GeneratedParamScope, ...GeneratedParamScope[]];
     global?: boolean;
     optional: boolean;
     definition: GeneratedParamDefinition;
 }
+interface GeneratedCommandExample {
+    title: string;
+    params: Record<string, unknown>;
+}
 interface GeneratedParamDefinitionMetadata {
     defaultValue?: unknown;
     format?: string;
@@ -202,6 +213,7 @@ export interface GeneratedObjectSchemaOptions {
 interface RenderSchemaOptionsInput {
     definition: GeneratedParamDefinition;
     description?: string;
+    longAliases?: string[];
     shortFlag?: string;
     scope?: readonly [GeneratedParamScope, ...GeneratedParamScope[]];
     global?: boolean;
@@ -226,7 +238,7 @@ interface SchemaOptionEntry {
 }
 type QueryArraySerialization = "repeat" | "brackets" | "comma" | "pipe";
 export declare function generate(document: OpenApiDocument, options: GenerateOptions): GeneratedFile[];
-export declare function collectGeneratedCommands(document: OpenApiDocument): GeneratedCommand[];
+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 {};

package/dist/generate.js

@@ -43,6 +43,15 @@ const TRANSPORT_PARAMS = [
         definition: { kind: "boolean" }
     }
 ];
+const BINARY_OUTPUT_PARAM = {
+    paramName: "output",
+    sourceName: "output",
+    location: "transport",
+    description: "Write a binary response body to this local file path.",
+    scope: ["cli"],
+    optional: true,
+    definition: { kind: "string" }
+};
 const SCHEMA_OPTION_SOURCES = [
     {
         key: "description",
@@ -56,6 +65,10 @@ const SCHEMA_OPTION_SOURCES = [
         key: "short",
         get: (param) => param.shortFlag
     },
+    {
+        key: "cliAliases",
+        get: (param) => param.longAliases
+    },
     {
         key: "scope",
         get: (param) => param.scope
@@ -111,7 +124,7 @@ const SCHEMA_OPTION_SOURCES = [
 ];
 export function generate(document, options) {
     const normalizedDocument = normalizeOpenApiDocument(document);
-    const commands = collectGeneratedCommands(normalizedDocument);
+    const commands = collectGeneratedCommands(normalizedDocument, options.config);
     const brand = options.brand ?? "blue";
     const label = normalizedDocument.info?.title ?? "Toolcraft";
     return [
@@ -126,17 +139,102 @@ export function generate(document, options) {
         createCliFile({ brand, label })
     ];
 }
-export function collectGeneratedCommands(document) {
+export function collectGeneratedCommands(document, config) {
     const normalizedDocument = normalizeOpenApiDocument(document);
     const paths = normalizedDocument.paths;
     if (paths === undefined) {
         throw new UserError('OpenAPI document must define a top-level "paths" object.');
     }
     const commands = collectOperations(paths).map((entry) => createGeneratedCommand(normalizedDocument, entry));
+    applyConfiguredCommandShape(commands, config);
     disambiguateCommandPaths(commands);
     assertUniqueCommandPaths(commands);
     return commands.slice().sort((left, right) => compareGeneratedCommandPaths(left, right));
 }
+function applyConfiguredCommandShape(commands, config) {
+    const configured = collectConfiguredCommandShapes(config?.resources);
+    if (configured.length === 0) {
+        return;
+    }
+    for (const command of commands) {
+        const match = configured.find((candidate) => candidate.method.method.toUpperCase() === command.method && candidate.method.path === command.path);
+        if (match === undefined) {
+            continue;
+        }
+        command.noun = createSafeGeneratedNoun(match.noun);
+        command.verb = createSafeGeneratedVerb(match.verb);
+        command.examples = config?.readme?.examples?.[match.exampleKey];
+        applyConfiguredRawResponse(command);
+        applyConfiguredIdempotency(command, match.method, config);
+        refreshGeneratedCommandNames(command);
+    }
+}
+function applyConfiguredRawResponse(command) {
+    command.rawResponse = true;
+    if (command.params.some((param) => param.paramName === "rawResponse")) {
+        return;
+    }
+    command.params.push({
+        paramName: "rawResponse",
+        sourceName: "rawResponse",
+        location: "transport",
+        description: "Return parsed data with the raw HTTP Response.",
+        longAliases: ["raw"],
+        scope: ["cli", "sdk"],
+        optional: true,
+        definition: { kind: "boolean" }
+    });
+}
+function applyConfiguredIdempotency(command, method, config) {
+    const header = config?.client_settings?.idempotency_header;
+    if (method.idempotent !== true || header === undefined || command.method === "GET") {
+        return;
+    }
+    command.idempotencyHeader = header;
+    if (command.params.some((param) => param.paramName === "idempotencyKey")) {
+        return;
+    }
+    command.params.push({
+        paramName: "idempotencyKey",
+        sourceName: "idempotencyKey",
+        location: "transport",
+        description: "Set an idempotency key to retry this request safely.",
+        scope: ["cli", "mcp", "sdk"],
+        optional: true,
+        definition: { kind: "string" }
+    });
+}
+function collectConfiguredCommandShapes(resources) {
+    const shapes = [];
+    function visit(resourceName, resource, resourcePath) {
+        for (const [methodName, method] of Object.entries(resource.methods ?? {})) {
+            shapes.push({
+                exampleKey: [...resourcePath, methodName].join("."),
+                noun: resourceName,
+                verb: methodName,
+                method
+            });
+        }
+        for (const [childName, childResource] of Object.entries(resource.subresources ?? {})) {
+            visit(childName, childResource, [...resourcePath, childName]);
+        }
+    }
+    for (const [resourceName, resource] of Object.entries(resources ?? {})) {
+        visit(resourceName, resource, [resourceName]);
+    }
+    return shapes;
+}
+function createSafeGeneratedVerb(value) {
+    const verb = toCamelCase(value);
+    if (!isIdentifierName(verb)) {
+        throw new UserError(`Configured method ${JSON.stringify(value)} must map to a valid command name.`);
+    }
+    return verb;
+}
+function refreshGeneratedCommandNames(command) {
+    command.exportName = `${toCamelCase(command.noun)}${toPascalCase(command.verb)}Command`;
+    command.filePath = `${command.noun}/${command.verb}.ts`;
+}
 export function collectGeneratedCommand(document, path, method) {
     const normalizedDocument = normalizeOpenApiDocument(document);
     const pathItem = normalizedDocument.paths?.[path];
@@ -176,7 +274,7 @@ function createGeneratedCommand(document, entry) {
     const response = resolveSuccessResponse(document, operation, operationId);
     const noun = createSafeGeneratedNoun(deriveNoun(operation, entry.path, operationId));
     const verb = deriveVerb(entry.method, entry.path, operation, operationId, noun);
-    const collected = collectParams(document, entry, operation, operationId, auth);
+    const collected = collectParams(document, entry, operation, operationId, auth, response.mode);
     const methodDefaults = METHOD_DEFAULTS[entry.method];
     const exportName = `${toCamelCase(noun)}${toPascalCase(verb)}Command`;
     const filePath = `${noun}/${verb}.ts`;
@@ -220,11 +318,12 @@ function resolveOperationBaseUrl(operation, operationId) {
         throw new UserError(`Operation ${JSON.stringify(operationId)} defines invalid per-operation server URL ${JSON.stringify(server.url)}.`);
     }
 }
-function collectParams(document, entry, operation, operationId, auth) {
+function collectParams(document, entry, operation, operationId, auth, responseMode) {
+    const transportParams = responseMode === "binary" ? [...TRANSPORT_PARAMS, BINARY_OUTPUT_PARAM] : TRANSPORT_PARAMS;
     const operationParams = collectOperationParameters(document, entry.path, entry.pathItem.parameters ?? [], operation.parameters ?? [], operationId, auth);
     const requestBodyParams = collectRequestBodyParams(document, operation, operationId, entry.method);
-    const qualifiedRequestBodyParams = qualifyBodyParamCollisions(requestBodyParams, new Set([...operationParams.params, ...TRANSPORT_PARAMS].map((param) => param.paramName)));
-    const params = [...operationParams.params, ...qualifiedRequestBodyParams.params, ...TRANSPORT_PARAMS];
+    const qualifiedRequestBodyParams = qualifyBodyParamCollisions(requestBodyParams, new Set([...operationParams.params, ...transportParams].map((param) => param.paramName)));
+    const params = [...operationParams.params, ...qualifiedRequestBodyParams.params, ...transportParams];
     const deduped = new Map();
     for (const param of params) {
         const existing = deduped.get(param.paramName);
@@ -1284,16 +1383,30 @@ function applyDisambiguatedVerbs(candidates, existingPaths) {
 }
 function createCommandFile(options) {
     const requiresUserError = options.preflightBlocks.length > 0;
+    const usesMultipartFileInputs = options.bodyMode === "multipart" &&
+        options.multipartBinaryFields !== undefined &&
+        options.multipartBinaryFields.length > 0;
+    const usesBinaryOutput = options.responseMode === "binary";
+    const usesRequestShapeVariable = usesMultipartFileInputs || usesBinaryOutput;
+    const openApiImports = [
+        "requestJson",
+        "defineApiCommand",
+        ...(usesMultipartFileInputs ? ["prepareMultipartFileInputs"] : []),
+        ...(usesBinaryOutput ? ["writeBinaryResponseOutput"] : [])
+    ];
     const lines = createGeneratedTypeScriptFileLines([
         `spec-sha: ${options.specSha}`,
         `operation-id: ${options.operationId}`
     ]);
     lines.push(requiresUserError
         ? 'import { S, UserError } from "toolcraft";'
-        : 'import { S } from "toolcraft";', 'import { requestJson, defineApiCommand } from "toolcraft-openapi";', "", `export const ${options.exportName} = defineApiCommand({`, `  name: ${JSON.stringify(options.verb)},`);
+        : 'import { S } from "toolcraft";', `import { ${openApiImports.join(", ")} } from "toolcraft-openapi";`, "", `export const ${options.exportName} = defineApiCommand({`, `  name: ${JSON.stringify(options.verb)},`);
     if (options.description !== undefined) {
         lines.push(`  description: ${JSON.stringify(options.description)},`);
     }
+    if (options.examples !== undefined && options.examples.length > 0) {
+        lines.push(`  examples: ${JSON.stringify(options.examples)},`);
+    }
     lines.push('  scope: ["cli", "mcp", "sdk"] as const,');
     if (options.confirm) {
         lines.push("  confirm: true,");
@@ -1303,9 +1416,30 @@ function createCommandFile(options) {
     lines.push(options.paramsSchemaOptions?.additionalProperties === false
         ? "  }, { additionalProperties: false }),"
         : "  }),");
-    lines.push("  handler: async ({ params, baseUrl, tokenSource, fetch }) => {");
+    lines.push(usesRequestShapeVariable
+        ? "  handler: async ({ params, baseUrl, tokenSource, fetch, fs, env }) => {"
+        : "  handler: async ({ params, baseUrl, tokenSource, fetch }) => {");
     lines.push(...options.preflightBlocks.flatMap((block) => renderPreflightBlock(block)));
-    lines.push("    return requestJson({");
+    if (usesRequestShapeVariable) {
+        lines.push("    const requestShape = {");
+        lines.push(...renderRequestShape(options.requestFields, options.sectionRenders, options.optionalSections));
+        lines.push("    };");
+        if (usesMultipartFileInputs) {
+            lines.push("    const preparedRequestShape = await prepareMultipartFileInputs(requestShape, {");
+            lines.push('      bodyMode: "multipart",');
+            lines.push(`      multipartBinaryFields: ${JSON.stringify(options.multipartBinaryFields)},`);
+            lines.push("      fs,");
+            lines.push("      env,");
+            lines.push("    });");
+        }
+        else {
+            lines.push("    const preparedRequestShape = requestShape;");
+        }
+        lines.push("    const result = await requestJson({");
+    }
+    else {
+        lines.push("    return requestJson({");
+    }
     lines.push(options.baseUrl === undefined
         ? "      baseUrl,"
         : `      baseUrl: ${JSON.stringify(options.baseUrl)},`);
@@ -1340,8 +1474,26 @@ function createCommandFile(options) {
     lines.push("      fetch,");
     lines.push("      dryRun: params.dryRun,");
     lines.push("      verbose: params.verbose,");
-    lines.push(...renderRequestShape(options.requestFields, options.sectionRenders, options.optionalSections));
+    if (options.rawResponse === true) {
+        lines.push("      rawResponse: params.rawResponse,");
+    }
+    if (options.idempotencyHeader !== undefined) {
+        lines.push("      idempotency: {");
+        lines.push(`        header: ${JSON.stringify(options.idempotencyHeader)},`);
+        lines.push("        enabled: true,");
+        lines.push("        key: params.idempotencyKey,");
+        lines.push("      },");
+    }
+    if (usesRequestShapeVariable) {
+        lines.push("      ...preparedRequestShape,");
+    }
+    else {
+        lines.push(...renderRequestShape(options.requestFields, options.sectionRenders, options.optionalSections));
+    }
     lines.push("    });");
+    if (usesBinaryOutput) {
+        lines.push("    return writeBinaryResponseOutput(result, params.output, { fs, env });");
+    }
     lines.push("  },");
     lines.push("});");
     lines.push("");
@@ -1405,14 +1557,15 @@ function renderParamLines(params) {
     return params.map((param) => `    ${renderObjectKey(param.paramName)}: ${renderParamSchema(param)},`);
 }
 function renderParamSchema(param) {
-    const schema = renderDefinition(param.definition, param.description, param.shortFlag, param.scope, param.global);
+    const schema = renderDefinition(param.definition, param.description, param.shortFlag, param.longAliases, param.scope, param.global);
     return param.optional ? `S.Optional(${schema})` : schema;
 }
-function renderDefinition(definition, description, shortFlag, scope, global) {
+function renderDefinition(definition, description, shortFlag, longAliases, scope, global) {
     const options = renderSchemaOptions({
         definition,
         description,
         shortFlag,
+        longAliases,
         scope,
         global
     });

package/dist/http.d.ts

@@ -1,4 +1,7 @@
+import { HttpError, type HandlerEnv, type HandlerFs, type HttpErrorRequest, type HttpErrorResponse } from "toolcraft";
 import type { TokenSource } from "./auth/types.js";
+export { HttpError };
+export type { HttpErrorRequest, HttpErrorResponse };
 type QueryScalar = string | number | boolean | null | undefined;
 type QueryObject = {
     readonly [key: string]: QueryValue;
@@ -24,38 +27,40 @@ export interface HttpRequestOptions {
     dryRun?: boolean;
     verbose?: boolean;
     signal?: AbortSignal;
+    rawResponse?: boolean;
+    retries?: {
+        max: number;
+        backoff: "exponential";
+        retryOn: number[];
+        sleep?: (ms: number) => Promise<void>;
+        random?: () => number;
+    };
+    idempotency?: {
+        header: string;
+        enabled: boolean;
+        key?: string;
+        createKey?: () => string;
+    };
     writeStdout?: (chunk: string) => void;
     writeStderr?: (chunk: string) => void;
 }
-export interface HttpErrorRequest {
-    method: string;
-    url: string;
-    headers: Record<string, string>;
-    body?: unknown;
-}
-export interface HttpErrorResponse {
-    status: number;
-    statusText: string;
-    headers: Record<string, string>;
-    body: unknown;
-}
 export interface BinaryHttpResponse {
     contentType: string;
     encoding: "base64";
     byteLength: number;
     data: string;
 }
-export declare class HttpError extends Error {
-    readonly status: number;
-    readonly statusText: string;
-    readonly request: HttpErrorRequest;
-    readonly response: HttpErrorResponse;
-    get body(): unknown;
-    constructor(args: {
-        request: HttpErrorRequest;
-        response: HttpErrorResponse;
-        message?: string;
-    });
-}
+type RuntimeFileSystem = Pick<HandlerFs, "exists" | "readFile" | "writeFile">;
+type RuntimeEnvironment = Pick<HandlerEnv, "get">;
+type RequestShape = Partial<Pick<HttpRequestOptions, "pathParams" | "query" | "headers" | "body">>;
 export declare function requestJson<TResult = unknown>(options: HttpRequestOptions): Promise<TResult | undefined>;
-export {};
+export declare function prepareMultipartFileInputs(requestShape: RequestShape, options: {
+    bodyMode?: HttpRequestOptions["bodyMode"];
+    multipartBinaryFields?: readonly string[];
+    fs?: RuntimeFileSystem;
+    env?: RuntimeEnvironment;
+}): Promise<RequestShape>;
+export declare function writeBinaryResponseOutput(result: unknown, outputPath: unknown, runtime: {
+    fs?: RuntimeFileSystem;
+    env?: RuntimeEnvironment;
+}): Promise<unknown>;