toolcraft-openapi 0.0.1

package/dist/define-client.js

@@ -0,0 +1,148 @@
+import { defineCommand, defineGroup, UserError } from "agent-kit";
+import { toMcpPrefix } from "./naming.js";
+const CLI_SCOPE = ["cli"];
+export function defineClient(options) {
+    validateClientName(options.name);
+    if (options.auth === undefined) {
+        throw new UserError("defineClient requires an auth provider.");
+    }
+    const mergedChildren = mergeChildren([
+        { nodes: options.commands, source: "generated" },
+        { nodes: options.handwrittenCommands ?? [], source: "handwritten" },
+        { nodes: options.auth.commands.map((command) => cloneNode(command, CLI_SCOPE)), source: "auth" }
+    ]);
+    return {
+        name: options.name,
+        mcpPrefix: toMcpPrefix(options.name),
+        root: defineGroup({
+            name: options.name,
+            children: mergedChildren
+        }),
+        services: {
+            baseUrl: options.baseUrl,
+            tokenSource: options.auth
+        }
+    };
+}
+function mergeChildren(entries) {
+    const nodeSources = new Map();
+    const merged = [];
+    for (const entry of entries) {
+        mergeInto(merged, entry.nodes, [], entry.source, nodeSources);
+    }
+    // defineGroup snapshots its children at construction time, while mergeInto mutates an
+    // existing group's children after that snapshot. Re-cloning here re-materializes each
+    // merged group so nesting client.root under another group preserves the merged children.
+    return merged.map((node) => cloneNode(node));
+}
+function mergeInto(target, incoming, path, source, nodeSources) {
+    for (const candidate of incoming) {
+        const nextNode = cloneNode(candidate);
+        registerSource(nextNode, source, nodeSources);
+        const existing = target.find((node) => node.name === nextNode.name);
+        if (existing === undefined) {
+            target.push(nextNode);
+            continue;
+        }
+        if (existing.kind !== "group" || nextNode.kind !== "group") {
+            throw createCollisionError([...path, nextNode.name], getRegisteredSource(nodeSources, existing), source);
+        }
+        mergeInto(existing.children, nextNode.children, [...path, nextNode.name], source, nodeSources);
+    }
+}
+function registerSource(node, source, nodeSources) {
+    nodeSources.set(node, source);
+    if (node.kind === "group") {
+        for (const child of node.children) {
+            registerSource(child, source, nodeSources);
+        }
+    }
+}
+function getRegisteredSource(nodeSources, node) {
+    const source = nodeSources.get(node);
+    if (source === undefined) {
+        throw new Error("Bug: merged command node is missing source metadata.");
+    }
+    return source;
+}
+function createCollisionError(path, left, right) {
+    return new UserError(`Command path ${JSON.stringify(path.join(" "))} is defined more than once (${left} and ${right}).`);
+}
+function cloneNode(node, scopeOverride) {
+    if (node.kind === "command") {
+        return cloneCommand(node, scopeOverride);
+    }
+    return cloneGroup(node, scopeOverride);
+}
+function cloneCommand(command, scopeOverride) {
+    return defineCommand({
+        name: command.name,
+        description: command.description,
+        aliases: [...command.aliases],
+        positional: [...command.positional],
+        params: command.params,
+        secrets: { ...command.secrets },
+        scope: [...(scopeOverride ?? command.scope)],
+        confirm: command.confirm,
+        requires: command.requires,
+        handler: command.handler,
+        render: command.render
+    });
+}
+function cloneGroup(group, scopeOverride) {
+    const children = group.children.map((child) => cloneNode(child, scopeOverride));
+    const defaultCommand = findCommand(children, group.default?.name);
+    return defineGroup({
+        name: group.name,
+        description: group.description,
+        aliases: [...group.aliases],
+        scope: cloneScope(group.scope, scopeOverride),
+        secrets: { ...group.secrets },
+        requires: group.requires,
+        children,
+        default: defaultCommand
+    });
+}
+function validateClientName(name) {
+    if (!isValidClientName(name)) {
+        throw new UserError(`Client name ${JSON.stringify(name)} must use lowercase letters, numbers, and hyphens only.`);
+    }
+}
+function isValidClientName(name) {
+    if (name.length === 0 || name.startsWith("-") || name.endsWith("-")) {
+        return false;
+    }
+    for (const character of name) {
+        if (character === "-") {
+            continue;
+        }
+        if (character >= "a" && character <= "z") {
+            continue;
+        }
+        if (character >= "0" && character <= "9") {
+            continue;
+        }
+        return false;
+    }
+    return true;
+}
+function cloneScope(scope, scopeOverride) {
+    if (scopeOverride !== undefined) {
+        return [...scopeOverride];
+    }
+    if (scope === undefined) {
+        return undefined;
+    }
+    return [...scope];
+}
+function findCommand(nodes, name) {
+    if (name === undefined) {
+        return undefined;
+    }
+    for (const node of nodes) {
+        if (node.kind === "command" && node.name === name) {
+            return node;
+        }
+    }
+    return undefined;
+}

package/dist/generate.d.ts

@@ -0,0 +1,210 @@
+import { type HttpMethod } from "./naming.js";
+type OpenApiOperation = OpenApiOperationObject | OpenApiReferenceObject;
+type OpenApiOperationMap = Partial<Record<HttpMethod, OpenApiOperation>>;
+type OpenApiParameterLocation = "path" | "query" | "header" | "cookie";
+export type GeneratedRequestLocation = Exclude<GeneratedParam["location"], "transport">;
+export interface OpenApiDocument {
+    openapi?: string;
+    info?: {
+        title?: string;
+        version?: string;
+    };
+    security?: OpenApiSecurityRequirementObject[];
+    paths?: Record<string, OpenApiPathItemObject | undefined>;
+    components?: {
+        securitySchemes?: Record<string, unknown>;
+        parameters?: Record<string, OpenApiParameterObject | OpenApiReferenceObject>;
+        requestBodies?: Record<string, OpenApiRequestBodyObject | OpenApiReferenceObject>;
+        responses?: Record<string, OpenApiResponseObject | OpenApiReferenceObject>;
+        schemas?: Record<string, OpenApiSchemaObject | OpenApiReferenceObject>;
+    };
+}
+export interface OpenApiPathItemObject extends OpenApiOperationMap {
+    parameters?: OpenApiParameter[];
+}
+export interface OpenApiOperationObject {
+    tags?: string[];
+    summary?: string;
+    description?: string;
+    operationId?: string;
+    security?: OpenApiSecurityRequirementObject[];
+    servers?: OpenApiServerObject[];
+    parameters?: OpenApiParameter[];
+    requestBody?: OpenApiRequestBodyObject | OpenApiReferenceObject;
+    responses?: Record<string, OpenApiResponseObject | OpenApiReferenceObject>;
+}
+export type OpenApiParameter = OpenApiParameterObject | OpenApiReferenceObject;
+export interface OpenApiParameterObject {
+    name: string;
+    in: OpenApiParameterLocation;
+    required?: boolean;
+    description?: string;
+    content?: Record<string, OpenApiMediaTypeObject | undefined>;
+    explode?: boolean;
+    schema?: OpenApiSchemaObject | OpenApiReferenceObject;
+    style?: string;
+}
+export interface OpenApiRequestBodyObject {
+    description?: string;
+    required?: boolean;
+    content?: Record<string, OpenApiMediaTypeObject | undefined>;
+}
+export interface OpenApiResponseObject {
+    description?: string;
+    content?: Record<string, OpenApiMediaTypeObject | undefined>;
+}
+export interface OpenApiMediaTypeObject {
+    schema?: OpenApiSchemaObject | OpenApiReferenceObject;
+}
+export interface OpenApiSchemaObject {
+    type?: "string" | "number" | "integer" | "boolean" | "object" | "array";
+    additionalProperties?: boolean | OpenApiSchemaObject | OpenApiReferenceObject;
+    allOf?: Array<OpenApiSchemaObject | OpenApiReferenceObject>;
+    anyOf?: Array<OpenApiSchemaObject | OpenApiReferenceObject>;
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    format?: string;
+    items?: OpenApiSchemaObject | OpenApiReferenceObject;
+    maxItems?: number;
+    maximum?: number;
+    maxLength?: number;
+    minItems?: number;
+    minimum?: number;
+    minLength?: number;
+    nullable?: boolean;
+    oneOf?: Array<OpenApiSchemaObject | OpenApiReferenceObject>;
+    pattern?: string;
+    required?: string[];
+    properties?: Record<string, OpenApiSchemaObject | OpenApiReferenceObject>;
+    readOnly?: boolean;
+    writeOnly?: boolean;
+}
+export interface OpenApiReferenceObject {
+    $ref: string;
+}
+interface OpenApiServerObject {
+    url: string;
+    description?: string;
+}
+type OpenApiSecurityRequirementObject = Record<string, string[]>;
+export interface GenerateOptions {
+    specSha: string;
+}
+export interface GeneratedFile {
+    path: string;
+    contents: string;
+}
+export interface GeneratedCommand {
+    noun: string;
+    verb: string;
+    exportName: string;
+    filePath: string;
+    operationId: string;
+    description?: string;
+    method: string;
+    path: string;
+    auth: "required" | "none";
+    confirm: boolean;
+    params: GeneratedParam[];
+    paramsSchemaOptions?: GeneratedObjectSchemaOptions;
+    preflightBlocks: GeneratedPreflightBlock[];
+    requestFields: GeneratedRequestField[];
+    sectionRenders: GeneratedRequestSectionRenders;
+    optionalSections: ReadonlySet<Exclude<GeneratedParam["location"], "transport">>;
+}
+export interface GeneratedParam {
+    paramName: string;
+    sourceName: string;
+    location: "path" | "query" | "body" | "transport";
+    description?: string;
+    shortFlag?: string;
+    scope?: readonly [GeneratedParamScope, ...GeneratedParamScope[]];
+    optional: boolean;
+    definition: GeneratedParamDefinition;
+}
+interface GeneratedParamDefinitionMetadata {
+    defaultValue?: unknown;
+    format?: string;
+    jsonType?: "integer";
+    maxItems?: number;
+    maximum?: number;
+    maxLength?: number;
+    minItems?: number;
+    minimum?: number;
+    minLength?: number;
+    nullable?: boolean;
+    pattern?: string;
+    requiredScopes?: readonly [GeneratedParamScope, ...GeneratedParamScope[]];
+}
+interface GeneratedScalarParamDefinition extends GeneratedParamDefinitionMetadata {
+    kind: "string" | "number" | "boolean";
+}
+interface GeneratedEnumParamDefinition extends GeneratedParamDefinitionMetadata {
+    kind: "enum";
+    enumValues: readonly [GeneratedEnumValue, ...GeneratedEnumValue[]];
+}
+interface GeneratedArrayParamDefinition extends GeneratedParamDefinitionMetadata {
+    kind: "array";
+    itemDefinition: GeneratedParamDefinition;
+}
+export type GeneratedParamDefinition = GeneratedScalarParamDefinition | GeneratedEnumParamDefinition | GeneratedArrayParamDefinition;
+type GeneratedParamScope = "cli" | "mcp" | "sdk";
+type GeneratedEnumValue = string | number | boolean;
+export type GeneratedValueReference = {
+    kind: "param";
+    paramName: string;
+} | {
+    kind: "resolved";
+    resolvedName: string;
+};
+export type GeneratedValueExpression = {
+    kind: "reference";
+    reference: GeneratedValueReference;
+} | {
+    kind: "queryArray";
+    reference: GeneratedValueReference;
+    serialization: QueryArraySerialization;
+};
+export interface GeneratedRequestField {
+    location: Exclude<GeneratedParam["location"], "transport">;
+    omitWhenUndefinedReference: GeneratedValueReference;
+    wireName: string;
+    value: GeneratedValueExpression;
+}
+export type GeneratedRequestSectionRender = "inline" | "wrapped";
+export type GeneratedRequestSectionRenders = Partial<{
+    [K in GeneratedRequestLocation]: K extends "body" ? GeneratedRequestSectionRender : "wrapped";
+}>;
+export interface GeneratedObjectSchemaOptions {
+    additionalProperties?: boolean;
+}
+interface RenderSchemaOptionsInput {
+    definition: GeneratedParamDefinition;
+    description?: string;
+    shortFlag?: string;
+    scope?: readonly [GeneratedParamScope, ...GeneratedParamScope[]];
+}
+export type GeneratedPreflightBlock = {
+    kind: "scalar-null";
+    paramName: string;
+    nullParamName: string;
+    resolvedName: string;
+    required: boolean;
+} | {
+    kind: "array";
+    paramName: string;
+    jsonParamName: string;
+    nullParamName?: string;
+    resolvedName: string;
+    required: boolean;
+};
+interface SchemaOptionEntry {
+    key: string;
+    value: unknown;
+}
+type QueryArraySerialization = "repeat" | "comma" | "pipe";
+export declare function generate(document: OpenApiDocument, options: GenerateOptions): GeneratedFile[];
+export declare function collectGeneratedCommands(document: OpenApiDocument): GeneratedCommand[];
+export declare function collectSchemaOptionEntries(param: RenderSchemaOptionsInput): SchemaOptionEntry[];
+export {};