poe-code 3.0.185 → 3.0.186

package/packages/cmdkit-openapi/dist/naming.js

@@ -0,0 +1,218 @@
+import { UserError } from "@poe-code/cmdkit";
+export const METHOD_DEFAULTS = {
+    delete: {
+        collection: "delete",
+        resource: "delete",
+        confirm: true
+    },
+    get: {
+        collection: "list",
+        resource: "view",
+        genericVerbs: ["get", "list", "view"],
+        preferOperationIdWhenPathTailIsGeneric: true
+    }
+};
+export function deriveNoun(operation, path, operationId) {
+    const noun = operation.tags?.[0];
+    if (typeof noun !== "string" || noun.length === 0) {
+        const fallbackNoun = deriveNounFromPath(path);
+        if (fallbackNoun === undefined) {
+            throw new UserError(`Operation ${JSON.stringify(operationId)} must define tags[0] or a static resource segment in the path to derive a command noun.`);
+        }
+        return fallbackNoun;
+    }
+    return toKebabCase(noun);
+}
+export function deriveVerb(method, path, operation, operationId, noun) {
+    const segments = splitPathSegments(path);
+    const defaults = METHOD_DEFAULTS[method];
+    if (defaults !== undefined) {
+        const lastSegment = segments.at(-1);
+        if (isPathTemplateSegment(lastSegment)) {
+            return defaults.resource;
+        }
+        if (defaults.preferOperationIdWhenPathTailIsGeneric === true) {
+            const derived = deriveVerbFromOperationId(method, operation.operationId, noun, defaults);
+            const pathTail = lastSegment === undefined ? undefined : toKebabCase(lastSegment);
+            if (derived !== undefined) {
+                if (pathTail === undefined || derived !== pathTail) {
+                    return derived;
+                }
+                if (!operationIdStartsWithCollectionVerb(method, operation.operationId, noun, defaults)) {
+                    return pathTail;
+                }
+            }
+        }
+        return defaults.collection;
+    }
+    const derived = deriveVerbFromOperationId(method, operation.operationId, noun);
+    if (derived !== undefined) {
+        return derived;
+    }
+    throw new UserError(`Operation ${JSON.stringify(operationId)} is missing an operationId, so cmdkit-openapi cannot derive a stable command verb.`);
+}
+export function normalizeParamName(name) {
+    return toCamelCase(name);
+}
+export function toPascalCase(value) {
+    const camel = toCamelCase(value);
+    return camel.length === 0 ? camel : `${camel[0]?.toUpperCase() ?? ""}${camel.slice(1)}`;
+}
+export function toCamelCase(value) {
+    return splitWords(value)
+        .map((word, index) => (index === 0 ? word : `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`))
+        .join("");
+}
+export function toKebabCase(value) {
+    return splitWords(value).join("-");
+}
+export function toCliFlag(value) {
+    return toKebabCase(value);
+}
+export function splitWords(value) {
+    const normalized = value
+        .replaceAll("-", " ")
+        .replaceAll("_", " ")
+        .replaceAll(".", " ")
+        .replaceAll("/", " ");
+    return normalized
+        .split(" ")
+        .flatMap(splitCamelCaseWord)
+        .filter((word) => word.length > 0)
+        .map((word) => word.toLowerCase());
+}
+export function toMcpPrefix(name) {
+    return name.replaceAll("-", "_");
+}
+export function isIdentifierName(value) {
+    return /^[$A-Z_a-z][$\w]*$/u.test(value);
+}
+function splitPathSegments(path) {
+    return path.split("/").filter((segment) => segment.length > 0);
+}
+function deriveNounFromPath(path) {
+    return splitPathSegments(path)
+        .find((segment) => !isPathTemplateSegment(segment) && segment !== "api" && !isVersionWord(segment))
+        ?.split("/")
+        .map((segment) => toKebabCase(segment))
+        .find((segment) => segment.length > 0);
+}
+function isPathTemplateSegment(segment) {
+    return segment !== undefined && segment.startsWith("{") && segment.endsWith("}");
+}
+function deriveVerbFromOperationId(method, operationId, noun, defaults) {
+    const words = normalizeOperationIdWords(method, operationId, noun);
+    if (words === undefined) {
+        return undefined;
+    }
+    const verbWords = stripLeadingGenericVerb(words, defaults?.genericVerbs);
+    return verbWords.length === 0 ? undefined : verbWords.join("-");
+}
+function operationIdStartsWithCollectionVerb(method, operationId, noun, defaults) {
+    const words = normalizeOperationIdWords(method, operationId, noun);
+    return words?.[0] === defaults.collection;
+}
+function normalizeOperationIdWords(method, operationId, noun) {
+    if (operationId === undefined) {
+        return undefined;
+    }
+    const nounWords = splitWords(noun);
+    return dedupeAdjacentWords(trimTrailingNounUnlessItConsumesAll(trimTrailingMethod(trimLeadingWords(splitWords(operationId).filter((word) => !isVersionWord(word)), nounWords), method), nounWords));
+}
+function stripLeadingGenericVerb(words, genericVerbs) {
+    if (genericVerbs === undefined || words.length <= 1 || !genericVerbs.includes(words[0] ?? "")) {
+        return words;
+    }
+    let start = 1;
+    while (start < words.length - 1 && words[start] === words[0]) {
+        start += 1;
+    }
+    return words.slice(start);
+}
+function trimTrailingNounUnlessItConsumesAll(words, nounWords) {
+    const withoutTrailingNoun = trimTrailingWords(words, nounWords);
+    return withoutTrailingNoun.length === 0 ? words : withoutTrailingNoun;
+}
+function trimLeadingWords(words, prefix) {
+    if (prefix.length === 0 || prefix.length > words.length) {
+        return words;
+    }
+    for (let index = 0; index < prefix.length; index += 1) {
+        if (words[index] !== prefix[index]) {
+            return words;
+        }
+    }
+    return words.slice(prefix.length);
+}
+function trimTrailingWords(words, suffix) {
+    if (suffix.length === 0 || suffix.length >= words.length) {
+        return words;
+    }
+    const start = words.length - suffix.length;
+    for (let index = 0; index < suffix.length; index += 1) {
+        if (words[start + index] !== suffix[index]) {
+            return words;
+        }
+    }
+    return words.slice(0, start);
+}
+function trimTrailingMethod(words, method) {
+    return words.at(-1) === method ? words.slice(0, -1) : words;
+}
+function dedupeAdjacentWords(words) {
+    if (words.length === 0) {
+        return [];
+    }
+    const deduped = [words[0] ?? ""];
+    for (let index = 1; index < words.length; index += 1) {
+        const word = words[index] ?? "";
+        if (word !== deduped.at(-1)) {
+            deduped.push(word);
+        }
+    }
+    return deduped;
+}
+function isVersionWord(word) {
+    if (!word.startsWith("v") || word.length < 2) {
+        return false;
+    }
+    for (const character of word.slice(1)) {
+        if (character < "0" || character > "9") {
+            return false;
+        }
+    }
+    return true;
+}
+function splitCamelCaseWord(value) {
+    if (value.length === 0) {
+        return [];
+    }
+    const words = [value[0] ?? ""];
+    for (let index = 1; index < value.length; index += 1) {
+        const character = value[index] ?? "";
+        const previous = value[index - 1] ?? "";
+        const next = value[index + 1];
+        if (shouldStartNewWord(previous, character, next)) {
+            words.push(character);
+            continue;
+        }
+        const currentWord = words.at(-1) ?? "";
+        words[words.length - 1] = `${currentWord}${character}`;
+    }
+    return words;
+}
+function shouldStartNewWord(previous, character, next) {
+    if (!isUppercaseLetter(character)) {
+        return false;
+    }
+    if (isLowercaseLetter(previous)) {
+        return true;
+    }
+    return isUppercaseLetter(previous) && next !== undefined && isLowercaseLetter(next);
+}
+function isLowercaseLetter(character) {
+    return character >= "a" && character <= "z";
+}
+function isUppercaseLetter(character) {
+    return character >= "A" && character <= "Z";
+}

package/packages/cmdkit-openapi/dist/request-shape.d.ts

@@ -0,0 +1,15 @@
+export declare const REQUEST_PARAM_SECTIONS: readonly [{
+    readonly location: "path";
+    readonly key: "pathParams";
+    readonly omittable: false;
+}, {
+    readonly location: "query";
+    readonly key: "query";
+    readonly omittable: false;
+}, {
+    readonly location: "body";
+    readonly key: "body";
+    readonly omittable: true;
+}];
+export type RequestParamSection = (typeof REQUEST_PARAM_SECTIONS)[number];
+export type RequestSectionKey = RequestParamSection["key"];

package/packages/cmdkit-openapi/dist/request-shape.js

@@ -0,0 +1,5 @@
+export const REQUEST_PARAM_SECTIONS = [
+    { location: "path", key: "pathParams", omittable: false },
+    { location: "query", key: "query", omittable: false },
+    { location: "body", key: "body", omittable: true }
+];

package/packages/cmdkit-openapi/dist/runtime.d.ts

@@ -0,0 +1,13 @@
+import { type CommandNode } from "@poe-code/cmdkit";
+import { type DefineClientOptions, type DefinedClient, type OpenApiClientServices } from "./define-client.js";
+import { type OpenApiDocument } from "./generate.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;
+}
+export type DefineClientFromSpecOptions<TServices extends object = Record<string, never>> = Omit<DefineClientOptions<TServices>, "commands"> & CommandsFromSpecOptions;
+export declare function commandsFromSpec(source: OpenApiDocumentSource, options?: CommandsFromSpecOptions): Promise<CommandNode<OpenApiClientServices>[]>;
+export declare function defineClientFromSpec<TServices extends object = Record<string, never>>(spec: OpenApiDocumentSource, options: DefineClientFromSpecOptions<TServices>): Promise<DefinedClient<TServices>>;

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

@@ -0,0 +1,94 @@
+import fs from "node:fs/promises";
+import { defineCommand, defineGroup, S } from "@poe-code/cmdkit";
+import { defineClient } from "./define-client.js";
+import { collectSchemaOptionEntries, collectGeneratedCommands } from "./generate.js";
+import { groupByNoun } from "./group-by-noun.js";
+import { requestJson } from "./http.js";
+import { buildRequestShape, executePreflightBlocks } from "./interpreter.js";
+import { parseOpenApiDocument, readOpenApiSourceText } from "./spec-source.js";
+const RUNTIME_COMMAND_SCOPE = ["cli", "mcp", "sdk"];
+export async function commandsFromSpec(source, options = {}) {
+    const document = await resolveDocument(source, options);
+    return createRuntimeGroups(collectGeneratedCommands(document));
+}
+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 });
+}
+async function resolveDocument(source, options) {
+    if (typeof source !== "string" && !(source instanceof URL)) {
+        return source;
+    }
+    const sourceText = await readOpenApiSourceText(source, {
+        cwd: options.cwd ?? process.cwd(),
+        fetch: options.fetch ?? globalThis.fetch,
+        fs: options.fs ?? fs
+    });
+    return parseOpenApiDocument(sourceText, source);
+}
+function createRuntimeGroups(commands) {
+    return groupByNoun(commands).map(({ noun, commands: nounCommands }) => defineGroup({
+        name: noun,
+        children: nounCommands.map((command) => createRuntimeCommand(command))
+    }));
+}
+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 }),
+        scope: RUNTIME_COMMAND_SCOPE,
+        ...(command.confirm ? { confirm: true } : {}),
+        params: paramsSchema,
+        handler: createRuntimeHandler(command)
+    });
+}
+function createRuntimeHandler(command) {
+    return async ({ params, baseUrl, tokenSource, fetch }) => {
+        const resolvedValues = executePreflightBlocks(command.preflightBlocks, params);
+        const requestShape = buildRequestShape(command.requestFields, command.sectionRenders, command.optionalSections, params, resolvedValues);
+        return requestJson({
+            baseUrl,
+            path: command.path,
+            method: command.method,
+            auth: command.auth,
+            tokenSource,
+            fetch,
+            dryRun: params.dryRun,
+            verbose: params.verbose,
+            ...requestShape
+        });
+    };
+}
+function createRuntimeParamSchema(param) {
+    const definition = createRuntimeDefinition(param.definition, param.description, param.shortFlag, param.scope);
+    return param.optional ? S.Optional(definition) : definition;
+}
+function createRuntimeDefinition(definition, description, shortFlag, scope) {
+    const options = createRuntimeSchemaOptions(definition, description, shortFlag, scope);
+    return RUNTIME_DEFINITION_BUILDERS[definition.kind](definition, options);
+}
+const RUNTIME_DEFINITION_BUILDERS = {
+    array: (definition, options) => {
+        const itemDefinition = createRuntimeDefinition(definition.itemDefinition, undefined, undefined, undefined);
+        return options === undefined ? S.Array(itemDefinition) : S.Array(itemDefinition, options);
+    },
+    boolean: (_definition, options) => options === undefined ? S.Boolean() : S.Boolean(options),
+    enum: (definition, options) => options === undefined ? S.Enum(definition.enumValues) : S.Enum(definition.enumValues, options),
+    number: (_definition, options) => options === undefined ? S.Number() : S.Number(options),
+    string: (_definition, options) => options === undefined ? S.String() : S.String(options)
+};
+function createRuntimeSchemaOptions(definition, description, shortFlag, scope) {
+    const options = Object.fromEntries(collectSchemaOptionEntries({
+        definition,
+        description,
+        shortFlag,
+        scope
+    }).map(({ key, value }) => [key, Array.isArray(value) ? [...value] : value]));
+    return Object.keys(options).length === 0 ? undefined : options;
+}

package/packages/cmdkit-openapi/dist/spec-source.d.ts

@@ -0,0 +1,11 @@
+import type { OpenApiDocument } from "./generate.js";
+export interface OpenApiSourceFileSystem {
+    readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
+}
+export interface OpenApiSourceServices {
+    cwd: string;
+    fetch: typeof globalThis.fetch;
+    fs: OpenApiSourceFileSystem;
+}
+export declare function readOpenApiSourceText(input: string | URL, services: OpenApiSourceServices): Promise<string>;
+export declare function parseOpenApiDocument(sourceText: string, input: string | URL): OpenApiDocument;

package/packages/cmdkit-openapi/dist/spec-source.js

@@ -0,0 +1,63 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { UserError } from "@poe-code/cmdkit";
+export async function readOpenApiSourceText(input, services) {
+    const inputUrl = input instanceof URL ? input : tryParseUrl(input);
+    const sourceLabel = formatSourceLabel(input);
+    try {
+        if (typeof input === "string" && inputUrl === null) {
+            return await services.fs.readFile(path.resolve(services.cwd, input), "utf8");
+        }
+        if (inputUrl === null) {
+            throw new UserError(`Unsupported OpenAPI input ${JSON.stringify(sourceLabel)}.`);
+        }
+        if (inputUrl.protocol === "file:") {
+            return await services.fs.readFile(fileURLToPath(inputUrl), "utf8");
+        }
+        if (inputUrl.protocol !== "http:" && inputUrl.protocol !== "https:") {
+            throw new UserError(`Unsupported OpenAPI input URL protocol ${JSON.stringify(inputUrl.protocol)}.`);
+        }
+        const response = await services.fetch(inputUrl.toString());
+        if (!response.ok) {
+            throw new UserError(`Failed to fetch ${JSON.stringify(inputUrl.toString())}: ${response.status} ${response.statusText}`);
+        }
+        return await response.text();
+    }
+    catch (error) {
+        if (error instanceof UserError) {
+            throw error;
+        }
+        throw new UserError(`Failed to read OpenAPI document ${JSON.stringify(sourceLabel)}: ${getErrorMessage(error)}`);
+    }
+}
+export function parseOpenApiDocument(sourceText, input) {
+    let parsed;
+    try {
+        parsed = parseYaml(sourceText);
+    }
+    catch (error) {
+        throw new UserError(`Failed to parse OpenAPI document ${JSON.stringify(formatSourceLabel(input))}: ${getErrorMessage(error)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new UserError(`OpenAPI document ${JSON.stringify(formatSourceLabel(input))} must parse to an object.`);
+    }
+    return parsed;
+}
+function tryParseUrl(value) {
+    try {
+        return new URL(value);
+    }
+    catch {
+        return null;
+    }
+}
+function formatSourceLabel(source) {
+    return source instanceof URL ? source.toString() : source;
+}
+function getErrorMessage(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}