poe-code 4.0.14 → 4.0.15

package/package.json

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

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

@@ -1,14 +1,20 @@
 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";
 export type OpenApiDocumentSource = OpenApiDocument | string | URL;
 export interface CommandsFromSpecOptions {
     cwd?: string;
     fetch?: typeof globalThis.fetch;
     fs?: OpenApiSourceFileSystem;
+    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/packages/toolcraft-openapi/dist/runtime.js

@@ -1,7 +1,7 @@
 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";
@@ -9,16 +9,23 @@ 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));
+    return createRuntimeNodes(document, options.config);
 }
 export async function defineClientFromSpec(spec, options) {
-    const { cwd, fetch, fs: specFs, ...clientOptions } = options;
-    const commands = (await commandsFromSpec(spec, {
-        cwd,
-        fetch,
-        fs: specFs
-    }));
-    return defineClient({ ...clientOptions, commands });
+    const { cwd, fetch, fs: specFs, config, baseUrl, environment, env, ...clientOptions } = options;
+    const document = await resolveDocument(spec, { cwd, fetch, fs: specFs, config });
+    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);
+    return defineClient({ ...clientOptions, baseUrl: resolvedBaseUrl, commands });
 }
 async function resolveDocument(source, options) {
     if (typeof source !== "string" && !(source instanceof URL)) {
@@ -49,17 +56,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 +104,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 +138,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/packages/toolcraft-openapi/dist/spec-source.js

@@ -48,10 +48,15 @@ export async function readOpenApiSourceText(input, services) {
 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.`);