toolcraft-openapi 0.0.1

package/dist/generate.js

@@ -0,0 +1,1131 @@
+import { UserError } from "agent-kit";
+import { METHOD_DEFAULTS, deriveNoun, deriveVerb, isIdentifierName, normalizeParamName, toCamelCase, toPascalCase } from "./naming.js";
+import { groupByNoun } from "./group-by-noun.js";
+import { renderPreflightBlock, renderRequestShape } from "./interpreter.js";
+const HTTP_METHOD_ORDER = ["get", "post", "put", "patch", "delete"];
+const UNSUPPORTED_HTTP_METHODS = ["head", "options", "trace"];
+const METHODS_WITHOUT_REQUEST_BODY = new Set(["get"]);
+const SCHEMA_TYPE_TO_KIND = {
+    boolean: { kind: "boolean" },
+    integer: { kind: "number", jsonType: "integer" },
+    number: { kind: "number" },
+    string: { kind: "string" }
+};
+const NULL_HELPER_SUPPORT = {
+    body: { array: true, scalar: true },
+    path: { array: false, scalar: false },
+    // Query null already serializes as the existing empty-string wire encoding, so v1
+    // keeps null-helper flags body-only until a real query-null convention lands.
+    query: { array: false, scalar: false }
+};
+const TRANSPORT_PARAMS = [
+    {
+        paramName: "dryRun",
+        sourceName: "dryRun",
+        location: "transport",
+        description: "Print the HTTP request and exit without sending it.",
+        scope: ["cli", "sdk"],
+        optional: true,
+        definition: { kind: "boolean" }
+    },
+    {
+        paramName: "verbose",
+        sourceName: "verbose",
+        location: "transport",
+        description: "Log the request line to stderr.",
+        shortFlag: "v",
+        scope: ["cli", "sdk"],
+        optional: true,
+        definition: { kind: "boolean" }
+    }
+];
+const SCHEMA_OPTION_SOURCES = [
+    {
+        key: "description",
+        get: (param) => param.description
+    },
+    {
+        key: "default",
+        get: (param) => param.definition.defaultValue
+    },
+    {
+        key: "short",
+        get: (param) => param.shortFlag
+    },
+    {
+        key: "scope",
+        get: (param) => param.scope
+    },
+    {
+        key: "minimum",
+        get: (param) => param.definition.minimum
+    },
+    {
+        key: "maximum",
+        get: (param) => param.definition.maximum
+    },
+    {
+        key: "minLength",
+        get: (param) => param.definition.minLength
+    },
+    {
+        key: "maxLength",
+        get: (param) => param.definition.maxLength
+    },
+    {
+        key: "minItems",
+        get: (param) => param.definition.minItems
+    },
+    {
+        key: "maxItems",
+        get: (param) => param.definition.maxItems
+    },
+    {
+        key: "pattern",
+        get: (param) => param.definition.pattern
+    },
+    {
+        key: "format",
+        get: (param) => param.definition.format
+    },
+    {
+        key: "jsonType",
+        get: (param) => param.definition.jsonType
+    },
+    {
+        key: "nullable",
+        get: (param) => param.definition.nullable === true ? true : undefined
+    },
+    {
+        key: "requiredScopes",
+        get: (param) => param.definition.requiredScopes
+    }
+];
+export function generate(document, options) {
+    const commands = collectGeneratedCommands(document);
+    return [
+        ...commands.map((command) => ({
+            path: command.filePath,
+            contents: createCommandFile({
+                specSha: options.specSha,
+                ...command
+            })
+        })),
+        createIndexFile(commands)
+    ];
+}
+export function collectGeneratedCommands(document) {
+    const paths = document.paths;
+    if (paths === undefined) {
+        throw new UserError('OpenAPI document must define a top-level "paths" object.');
+    }
+    const commands = collectOperations(paths).map((entry) => createGeneratedCommand(document, entry));
+    assertUniqueCommandPaths(commands);
+    return commands.slice().sort((left, right) => compareGeneratedCommandPaths(left, right));
+}
+function collectOperations(paths) {
+    return Object.entries(paths)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .flatMap(([path, pathItem]) => {
+        if (pathItem === undefined) {
+            return [];
+        }
+        assertSupportedHttpMethods(path, pathItem);
+        return HTTP_METHOD_ORDER.flatMap((method) => {
+            const operation = pathItem[method];
+            if (operation === undefined) {
+                return [];
+            }
+            return [{ method, path, operation, pathItem }];
+        });
+    });
+}
+function createGeneratedCommand(document, entry) {
+    const operation = expectOperation(document, entry.operation, entry.method, entry.path);
+    const operationId = operation.operationId ?? `${entry.method.toUpperCase()} ${entry.path}`;
+    assertSupportedOperationMetadata(operation, operationId);
+    assertSupportedSuccessResponses(document, operation, operationId);
+    const noun = deriveNoun(operation, entry.path, operationId);
+    assertValidGeneratedNoun(operationId, noun);
+    const verb = deriveVerb(entry.method, entry.path, operation, operationId, noun);
+    const collected = collectParams(document, entry, operation, operationId);
+    const methodDefaults = METHOD_DEFAULTS[entry.method];
+    const exportName = `${toCamelCase(noun)}${toPascalCase(verb)}Command`;
+    const filePath = `${noun}/${verb}.ts`;
+    return {
+        noun,
+        verb,
+        exportName,
+        filePath,
+        operationId,
+        description: mergeCommandDescriptions(operation.description ?? operation.summary, collected.requestBodyDescription),
+        method: entry.method.toUpperCase(),
+        path: entry.path,
+        auth: getOperationAuthMode(document, operation, operationId),
+        confirm: methodDefaults?.confirm === true,
+        params: collected.params,
+        paramsSchemaOptions: collected.paramsSchemaOptions,
+        preflightBlocks: collected.preflightBlocks,
+        requestFields: collected.requestFields,
+        sectionRenders: collected.sectionRenders,
+        optionalSections: collected.optionalSections
+    };
+}
+function assertSupportedOperationMetadata(operation, operationId) {
+    if (operation.servers !== undefined) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported per-operation servers. Configure the client baseUrl instead.`);
+    }
+}
+function collectParams(document, entry, operation, operationId) {
+    const operationParams = collectOperationParameters(document, entry.path, entry.pathItem.parameters ?? [], operation.parameters ?? [], operationId);
+    const requestBodyParams = collectRequestBodyParams(document, operation, operationId, entry.method);
+    const params = [...operationParams.params, ...requestBodyParams.params, ...TRANSPORT_PARAMS];
+    const deduped = new Map();
+    for (const param of params) {
+        const existing = deduped.get(param.paramName);
+        if (existing !== undefined) {
+            throw new UserError(`Operation ${JSON.stringify(operationId)} maps both ${JSON.stringify(existing.sourceName)} and ${JSON.stringify(param.sourceName)} to flag ${JSON.stringify(param.paramName)}.`);
+        }
+        deduped.set(param.paramName, param);
+    }
+    return {
+        params: [...deduped.values()],
+        paramsSchemaOptions: requestBodyParams.paramsSchemaOptions,
+        preflightBlocks: [...operationParams.preflightBlocks, ...requestBodyParams.preflightBlocks],
+        requestFields: [...operationParams.requestFields, ...requestBodyParams.requestFields],
+        sectionRenders: { ...operationParams.sectionRenders, ...requestBodyParams.sectionRenders },
+        optionalSections: new Set([
+            ...operationParams.optionalSections,
+            ...requestBodyParams.optionalSections
+        ]),
+        requestBodyDescription: requestBodyParams.requestBodyDescription
+    };
+}
+function collectOperationParameters(document, path, pathItemParameters, operationParameters, operationId) {
+    const merged = new Map();
+    for (const parameter of pathItemParameters) {
+        const resolved = expectParameter(document, parameter, operationId);
+        merged.set(`${resolved.in}:${resolved.name}`, resolved);
+    }
+    for (const parameter of operationParameters) {
+        const resolved = expectParameter(document, parameter, operationId);
+        merged.set(`${resolved.in}:${resolved.name}`, resolved);
+    }
+    assertPathTemplateParameters(path, merged, operationId);
+    const params = [];
+    const preflightBlocks = [];
+    const requestFields = [];
+    for (const parameter of merged.values()) {
+        const generated = createGeneratedParameter(document, parameter, operationId);
+        params.push(...generated.params);
+        preflightBlocks.push(...generated.preflightBlocks);
+        requestFields.push(generated.requestField);
+    }
+    return {
+        params,
+        paramsSchemaOptions: undefined,
+        preflightBlocks,
+        requestFields,
+        sectionRenders: { path: "wrapped", query: "wrapped" },
+        optionalSections: new Set(),
+        requestBodyDescription: undefined
+    };
+}
+function collectRequestBodyParams(document, operation, operationId, method) {
+    if (operation.requestBody === undefined) {
+        return {
+            params: [],
+            paramsSchemaOptions: undefined,
+            preflightBlocks: [],
+            requestFields: [],
+            sectionRenders: {},
+            optionalSections: new Set(),
+            requestBodyDescription: undefined
+        };
+    }
+    if (METHODS_WITHOUT_REQUEST_BODY.has(method)) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported requestBody on ${method.toUpperCase()}. Request bodies are not supported on GET in v1.`);
+    }
+    const requestBody = expectRequestBody(document, operation.requestBody, operationId, "requestBody");
+    const content = Object.entries(requestBody.content ?? {}).find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && isJsonMediaType(mediaType))?.[1];
+    if (content === undefined) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} must define a JSON request body media type in v1.`);
+    }
+    const schema = expectSchema(document, content.schema, operationId, "requestBody");
+    const bodyOptional = requestBody.required !== true;
+    if (schema.type !== "object") {
+        const bodySchema = schema.description === undefined && requestBody.description !== undefined
+            ? { ...schema, description: requestBody.description }
+            : schema;
+        return createCollectedRequestBodyParams([createBodyField(document, "body", bodySchema, bodyOptional, operationId)], bodyOptional, schema.description === undefined ? undefined : requestBody.description, "inline", undefined);
+    }
+    if (schema.additionalProperties !== undefined && schema.additionalProperties !== false) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported requestBody. Object request bodies with additionalProperties are not supported in v1.`);
+    }
+    if (schema.properties === undefined) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} must define an object-shaped JSON request body.`);
+    }
+    const required = new Set(schema.required ?? []);
+    const assemblies = [];
+    const declaredPropertyCount = Object.keys(schema.properties).length;
+    for (const [name, property] of Object.entries(schema.properties)) {
+        const propertySchema = expectSchema(document, property, operationId, `requestBody.properties.${name}`);
+        if (propertySchema.readOnly === true) {
+            continue;
+        }
+        const generated = createBodyField(document, name, propertySchema, bodyOptional || !required.has(name), operationId);
+        assemblies.push(generated);
+    }
+    if (!bodyOptional && assemblies.length === 0) {
+        const reason = declaredPropertyCount === 0
+            ? "does not define any writable fields"
+            : "all declared fields are readOnly";
+        throw new UserError(`Operation ${JSON.stringify(operationId)} requestBody is required but ${reason}.`);
+    }
+    return createCollectedRequestBodyParams(assemblies, bodyOptional, requestBody.description, "wrapped", schema.additionalProperties === false ? { additionalProperties: false } : undefined);
+}
+function assertSupportedSuccessResponses(document, operation, operationId) {
+    for (const [statusCode, response] of Object.entries(operation.responses ?? {})) {
+        if (!isSuccessStatusCode(statusCode)) {
+            continue;
+        }
+        const resolvedResponse = expectResponse(document, response, operationId, statusCode);
+        const declaredMediaTypes = Object.entries(resolvedResponse.content ?? {})
+            .filter(([, mediaType]) => mediaType !== undefined)
+            .map(([mediaType]) => mediaType);
+        if (declaredMediaTypes.length === 0 ||
+            declaredMediaTypes.every((mediaType) => isJsonMediaType(mediaType))) {
+            for (const [mediaType, mediaTypeObject] of Object.entries(resolvedResponse.content ?? {})) {
+                if (mediaTypeObject === undefined ||
+                    mediaTypeObject.schema === undefined ||
+                    !isJsonMediaType(mediaType)) {
+                    continue;
+                }
+                assertSupportedSuccessResponseSchema(document, mediaTypeObject.schema, operationId, `success response schema for status ${JSON.stringify(statusCode)}`);
+            }
+            continue;
+        }
+        throw new UserError(`Operation ${JSON.stringify(operationId)} declares unsupported success response content type(s) for status ${JSON.stringify(statusCode)}: ${declaredMediaTypes
+            .map((mediaType) => JSON.stringify(mediaType))
+            .join(", ")}. Only application/json responses (or empty success responses) are supported in v1.`);
+    }
+}
+function assertSupportedSuccessResponseSchema(document, schema, operationId, context) {
+    const resolvedSchema = expectSupportedSuccessResponseSchema(document, schema, operationId, context);
+    if (resolvedSchema.additionalProperties !== undefined &&
+        resolvedSchema.additionalProperties !== false) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. Object response schemas with additionalProperties are not supported in v1.`);
+    }
+    for (const [propertyName, propertySchema] of Object.entries(resolvedSchema.properties ?? {})) {
+        assertSupportedSuccessResponseSchema(document, propertySchema, operationId, `${context} property ${JSON.stringify(propertyName)}`);
+    }
+    if (resolvedSchema.items !== undefined) {
+        assertSupportedSuccessResponseSchema(document, resolvedSchema.items, operationId, `${context} items`);
+    }
+}
+function expectSupportedSuccessResponseSchema(document, schema, operationId, context) {
+    const resolvedSchema = resolveSchema(document, schema, operationId, context);
+    const compositionKeyword = getCompositionKeyword(resolvedSchema);
+    if (compositionKeyword === undefined) {
+        return resolvedSchema;
+    }
+    const nullableAnyOfSchema = compositionKeyword === "anyOf"
+        ? resolveNullableAnyOfSchema(document, resolvedSchema, operationId, context)
+        : undefined;
+    if (nullableAnyOfSchema !== undefined) {
+        return nullableAnyOfSchema;
+    }
+    throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. JSON Schema composition keyword ${JSON.stringify(compositionKeyword)} is not supported in v1.`);
+}
+function createGeneratedParameter(document, parameter, operationId) {
+    const schema = expectSchema(document, parameter.schema, operationId, `parameter ${JSON.stringify(parameter.name)}`);
+    if (parameter.in === "path") {
+        if (parameter.required !== true) {
+            throw new UserError(`Operation ${JSON.stringify(operationId)} path parameter ${JSON.stringify(parameter.name)} must set required: true.`);
+        }
+        if (schema.nullable === true) {
+            throw new UserError(`Operation ${JSON.stringify(operationId)} path parameter ${JSON.stringify(parameter.name)} uses unsupported nullable schema. Path parameters cannot be nullable in v1.`);
+        }
+        assertSupportedPathParameterSerialization(parameter, operationId);
+    }
+    return createField({
+        document,
+        name: parameter.name,
+        description: parameter.description ?? schema.description,
+        schema,
+        optional: parameter.required !== true,
+        operationId,
+        context: `parameter ${JSON.stringify(parameter.name)}`,
+        location: parameter.in,
+        querySerialization: parameter.in === "query" && schema.type === "array"
+            ? resolveQueryArraySerialization(parameter, operationId)
+            : undefined
+    });
+}
+function assertSupportedPathParameterSerialization(parameter, operationId) {
+    const style = parameter.style ?? "simple";
+    const explode = parameter.explode ?? false;
+    if (style === "simple" && explode === false) {
+        return;
+    }
+    throw new UserError(`Operation ${JSON.stringify(operationId)} path parameter ${JSON.stringify(parameter.name)} uses unsupported serialization. Path parameters must use style "simple" with explode false in v1.`);
+}
+function createBodyField(document, name, schema, optional, operationId) {
+    return createField({
+        document,
+        name,
+        description: schema.description,
+        schema,
+        optional,
+        operationId,
+        context: `request body field ${JSON.stringify(name)}`,
+        location: "body"
+    });
+}
+function createField(options) {
+    return FIELD_ASSEMBLERS[options.location][getFieldSchemaKind(options.schema)](options);
+}
+function createScalarParam(options) {
+    const { document, name, description, schema, optional, operationId, context, location } = options;
+    const paramName = name;
+    const definition = createParamDefinition(document, schema, operationId, context);
+    const emitsNullHelper = supportsNullHelper(location, "scalar", definition.nullable);
+    const params = [
+        {
+            paramName,
+            sourceName: name,
+            location,
+            description,
+            optional: optional || emitsNullHelper,
+            definition: {
+                ...definition,
+                ...(!optional && emitsNullHelper ? { requiredScopes: ["mcp", "sdk"] } : {})
+            }
+        }
+    ];
+    const preflightBlocks = [];
+    const helperBaseName = normalizeParamName(name);
+    const resolvedName = `resolved${toPascalCase(helperBaseName)}`;
+    if (emitsNullHelper) {
+        params.push({
+            paramName: `${helperBaseName}Null`,
+            sourceName: name,
+            location: "transport",
+            description: `Send null for ${name}.`,
+            optional: true,
+            scope: ["cli"],
+            definition: { kind: "boolean" }
+        });
+        preflightBlocks.push({
+            kind: "scalar-null",
+            paramName,
+            nullParamName: `${helperBaseName}Null`,
+            resolvedName,
+            required: !optional
+        });
+    }
+    return {
+        params,
+        preflightBlocks,
+        requestField: {
+            location,
+            wireName: name,
+            value: emitsNullHelper
+                ? { kind: "reference", reference: { kind: "resolved", resolvedName } }
+                : { kind: "reference", reference: { kind: "param", paramName } },
+            omitWhenUndefinedReference: emitsNullHelper
+                ? { kind: "resolved", resolvedName }
+                : { kind: "param", paramName }
+        }
+    };
+}
+function getFieldSchemaKind(schema) {
+    return schema.type === "array" ? "array" : schema.type === "object" ? "object" : "scalar";
+}
+function createPathScalarOnlyError(name, operationId) {
+    throw new UserError(`Operation ${JSON.stringify(operationId)} path parameter ${JSON.stringify(name)} must use a scalar schema (string, number, integer, or boolean).`);
+}
+function createUnsupportedNestedBodyFieldError(name, operationId) {
+    throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported request body field ${JSON.stringify(name)}. Nested object body fields are not supported in v1.`);
+}
+function createArrayParam(options) {
+    const { document, name, description, schema, optional, operationId, context, location } = options;
+    const paramName = name;
+    const helperBaseName = normalizeParamName(name);
+    const directDefinition = createParamDefinition(document, location === "query" ? stripNullable(schema) : schema, operationId, context);
+    const jsonParamName = `${helperBaseName}Json`;
+    const nullParamName = `${helperBaseName}Null`;
+    const resolvedName = `resolved${toPascalCase(helperBaseName)}`;
+    const reference = { kind: "resolved", resolvedName };
+    const emitsNullHelper = supportsNullHelper(location, "array", directDefinition.nullable);
+    const directParamOptional = true;
+    const params = [
+        {
+            paramName,
+            sourceName: name,
+            location,
+            description,
+            optional: directParamOptional,
+            definition: {
+                ...directDefinition,
+                ...(optional ? {} : { requiredScopes: ["mcp", "sdk"] })
+            }
+        },
+        {
+            paramName: jsonParamName,
+            sourceName: name,
+            location: "transport",
+            description: `JSON-encoded value for ${name}.`,
+            optional: true,
+            scope: ["cli"],
+            definition: { kind: "string" }
+        }
+    ];
+    if (emitsNullHelper) {
+        params.push({
+            paramName: nullParamName,
+            sourceName: name,
+            location: "transport",
+            description: `Send null for ${name}.`,
+            optional: true,
+            scope: ["cli"],
+            definition: { kind: "boolean" }
+        });
+    }
+    return {
+        params,
+        preflightBlocks: [
+            {
+                kind: "array",
+                paramName,
+                jsonParamName,
+                ...(emitsNullHelper ? { nullParamName } : {}),
+                resolvedName,
+                required: !optional
+            }
+        ],
+        requestField: {
+            location,
+            wireName: name,
+            value: ARRAY_VALUE_EXPRESSIONS[location](reference, options.querySerialization),
+            omitWhenUndefinedReference: reference
+        }
+    };
+}
+const ARRAY_VALUE_EXPRESSIONS = {
+    body: (reference) => ({ kind: "reference", reference }),
+    query: (reference, querySerialization) => ({
+        kind: "queryArray",
+        reference,
+        serialization: expectQueryArraySerialization(querySerialization)
+    })
+};
+const FIELD_ASSEMBLERS = {
+    body: {
+        array: (options) => createArrayParam({
+            ...options,
+            location: "body"
+        }),
+        object: (options) => createUnsupportedNestedBodyFieldError(options.name, options.operationId),
+        scalar: (options) => createScalarParam({
+            ...options,
+            location: "body"
+        })
+    },
+    path: {
+        array: (options) => createPathScalarOnlyError(options.name, options.operationId),
+        object: (options) => createPathScalarOnlyError(options.name, options.operationId),
+        scalar: (options) => createScalarParam({
+            ...options,
+            location: "path"
+        })
+    },
+    query: {
+        array: (options) => createArrayParam({
+            ...options,
+            location: "query"
+        }),
+        object: (options) => createScalarParam({
+            ...options,
+            location: "query"
+        }),
+        scalar: (options) => createScalarParam({
+            ...options,
+            location: "query"
+        })
+    }
+};
+function expectQueryArraySerialization(querySerialization) {
+    if (querySerialization === undefined) {
+        throw new Error("Missing query array serialization for generated query array field.");
+    }
+    return querySerialization;
+}
+function supportsNullHelper(location, shape, nullable) {
+    return nullable === true && NULL_HELPER_SUPPORT[location][shape];
+}
+function createCollectedRequestBodyParams(assemblies, bodyOptional, requestBodyDescription, bodyRender, paramsSchemaOptions) {
+    return {
+        params: assemblies.flatMap((assembly) => assembly.params),
+        paramsSchemaOptions,
+        preflightBlocks: assemblies.flatMap((assembly) => assembly.preflightBlocks),
+        requestFields: assemblies.map((assembly) => assembly.requestField),
+        sectionRenders: { body: bodyRender },
+        optionalSections: bodyOptional
+            ? new Set(["body"])
+            : new Set(),
+        requestBodyDescription
+    };
+}
+function createParamDefinition(document, schema, operationId, context) {
+    if (schema.type === "array") {
+        const itemSchema = expectArrayItemsSchema(document, schema, operationId, context);
+        return {
+            kind: "array",
+            itemDefinition: createParamDefinition(document, itemSchema, operationId, `${context} items`),
+            ...(schema.default === undefined ? {} : { defaultValue: schema.default }),
+            ...(schema.minItems === undefined ? {} : { minItems: schema.minItems }),
+            ...(schema.maxItems === undefined ? {} : { maxItems: schema.maxItems }),
+            ...(schema.nullable === true ? { nullable: true } : {})
+        };
+    }
+    const scalarDefinition = schema.type === undefined || !(schema.type in SCHEMA_TYPE_TO_KIND)
+        ? undefined
+        : SCHEMA_TYPE_TO_KIND[schema.type];
+    const enumValues = normalizeEnumValues(schema.enum, operationId, context, schema.nullable === true, schema.type);
+    if (enumValues !== undefined) {
+        return {
+            kind: "enum",
+            enumValues,
+            ...(scalarDefinition?.jsonType === undefined ? {} : { jsonType: scalarDefinition.jsonType }),
+            ...(schema.default === undefined ? {} : { defaultValue: schema.default }),
+            ...(schema.nullable === true || schema.enum?.includes(null) === true
+                ? { nullable: true }
+                : {})
+        };
+    }
+    if (scalarDefinition !== undefined) {
+        return {
+            kind: scalarDefinition.kind,
+            ...(scalarDefinition.jsonType === undefined ? {} : { jsonType: scalarDefinition.jsonType }),
+            ...(schema.default === undefined ? {} : { defaultValue: schema.default }),
+            ...(schema.minimum === undefined ? {} : { minimum: schema.minimum }),
+            ...(schema.maximum === undefined ? {} : { maximum: schema.maximum }),
+            ...(schema.minLength === undefined ? {} : { minLength: schema.minLength }),
+            ...(schema.maxLength === undefined ? {} : { maxLength: schema.maxLength }),
+            ...(schema.pattern === undefined ? {} : { pattern: schema.pattern }),
+            ...(schema.format === undefined ? {} : { format: schema.format }),
+            ...(schema.nullable === true ? { nullable: true } : {})
+        };
+    }
+    throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. Supported shapes in this milestone are string, number, integer, boolean, enum, and arrays of those values.`);
+}
+function assertPathTemplateParameters(path, parameters, operationId) {
+    const placeholders = new Set(collectPathPlaceholders(path));
+    for (const placeholder of placeholders) {
+        if (!parameters.has(`path:${placeholder}`)) {
+            throw new UserError(`Operation ${JSON.stringify(operationId)} path ${JSON.stringify(path)} references ${JSON.stringify(`{${placeholder}}`)} but does not define a matching path parameter.`);
+        }
+    }
+    for (const parameter of parameters.values()) {
+        if (parameter.in !== "path") {
+            continue;
+        }
+        if (!placeholders.has(parameter.name)) {
+            throw new UserError(`Operation ${JSON.stringify(operationId)} path ${JSON.stringify(path)} declares path parameter ${JSON.stringify(parameter.name)} but the path template does not include ${JSON.stringify(`{${parameter.name}}`)}.`);
+        }
+    }
+}
+function collectPathPlaceholders(path) {
+    const placeholders = [];
+    let searchFrom = 0;
+    while (searchFrom < path.length) {
+        const start = path.indexOf("{", searchFrom);
+        if (start === -1) {
+            break;
+        }
+        const end = path.indexOf("}", start + 1);
+        if (end === -1) {
+            break;
+        }
+        placeholders.push(path.slice(start + 1, end));
+        searchFrom = end + 1;
+    }
+    return placeholders;
+}
+function isSuccessStatusCode(statusCode) {
+    if (statusCode === "default" || statusCode === "2XX") {
+        return true;
+    }
+    return (statusCode.length === 3 &&
+        statusCode[0] === "2" &&
+        isAsciiDigit(statusCode[1]) &&
+        isAsciiDigit(statusCode[2]));
+}
+function isAsciiDigit(character) {
+    return character >= "0" && character <= "9";
+}
+function isJsonMediaType(mediaType) {
+    const normalized = mediaType.toLowerCase();
+    return normalized.includes("application/json") || normalized.includes("+json");
+}
+function normalizeEnumValues(enumValues, operationId, context, nullable, schemaType) {
+    if (enumValues === undefined) {
+        return undefined;
+    }
+    const filteredValues = enumValues.filter((value) => value !== null);
+    if (enumValues.includes(null) && nullable !== true) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. Enums may include null only when the schema is marked nullable.`);
+    }
+    if (filteredValues.length === 0) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. Enum values cannot be empty.`);
+    }
+    if (filteredValues.some((value) => !isEnumPrimitiveValue(value))) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. OpenAPI enums must contain only string, number, boolean, or null values.`);
+    }
+    const primitiveTypes = new Set(filteredValues.map((value) => typeof value));
+    if (primitiveTypes.size > 1) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. Enums must not mix primitive types.`);
+    }
+    if (schemaType !== undefined) {
+        const matchesSchemaType = filteredValues.every((value) => {
+            if (schemaType === "integer") {
+                return typeof value === "number" && Number.isInteger(value);
+            }
+            if (schemaType === "number") {
+                return typeof value === "number";
+            }
+            if (schemaType === "string" || schemaType === "boolean") {
+                return typeof value === schemaType;
+            }
+            return true;
+        });
+        if (!matchesSchemaType) {
+            throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. Enum values must match declared schema.type ${JSON.stringify(schemaType)}.`);
+        }
+    }
+    return filteredValues.filter(isEnumPrimitiveValue);
+}
+function resolveLocalReference(document, ref, operationId, context) {
+    if (!ref.startsWith("#/")) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported external $ref ${JSON.stringify(ref)} in ${context}.`);
+    }
+    let current = document;
+    for (const segment of ref.slice(2).split("/").map(unescapeJsonPointerSegment)) {
+        if (typeof current !== "object" || current === null || !(segment in current)) {
+            throw new UserError(`Operation ${JSON.stringify(operationId)} references missing $ref ${JSON.stringify(ref)} in ${context}.`);
+        }
+        current = current[segment];
+    }
+    return current;
+}
+function unescapeJsonPointerSegment(segment) {
+    return segment.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+function expectParameter(document, parameter, operationId, refChain = []) {
+    if (isReferenceObject(parameter)) {
+        assertAcyclicRef(parameter.$ref, refChain, operationId, "parameter");
+        return expectParameter(document, resolveLocalReference(document, parameter.$ref, operationId, "parameter"), operationId, [...refChain, parameter.$ref]);
+    }
+    if (parameter.content !== undefined) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} parameter ${JSON.stringify(parameter.name)} uses unsupported parameter.content. Define path/query parameters with parameter.schema in v1.`);
+    }
+    if (parameter.in !== "path" && parameter.in !== "query") {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported parameter location ${JSON.stringify(parameter.in)}. Only path and query parameters are supported in v1; use auth or handwritten commands for headers/cookies.`);
+    }
+    return parameter;
+}
+function expectOperation(document, operation, method, path, refChain = []) {
+    if (!isReferenceObject(operation)) {
+        return operation;
+    }
+    const operationId = `${method.toUpperCase()} ${path}`;
+    const context = `operation ${method.toUpperCase()} ${path}`;
+    assertAcyclicRef(operation.$ref, refChain, operationId, context);
+    return expectOperation(document, resolveLocalReference(document, operation.$ref, operationId, context), method, path, [...refChain, operation.$ref]);
+}
+function isEnumPrimitiveValue(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function expectRequestBody(document, requestBody, operationId, context, refChain = []) {
+    if (!isReferenceObject(requestBody)) {
+        return requestBody;
+    }
+    assertAcyclicRef(requestBody.$ref, refChain, operationId, context);
+    return expectRequestBody(document, resolveLocalReference(document, requestBody.$ref, operationId, context), operationId, context, [...refChain, requestBody.$ref]);
+}
+function expectResponse(document, response, operationId, statusCode, refChain = []) {
+    if (!isReferenceObject(response)) {
+        return response;
+    }
+    const context = `success response for status ${JSON.stringify(statusCode)}`;
+    assertAcyclicRef(response.$ref, refChain, operationId, context);
+    return expectResponse(document, resolveLocalReference(document, response.$ref, operationId, context), operationId, statusCode, [...refChain, response.$ref]);
+}
+function expectSchema(document, schema, operationId, context, refChain = []) {
+    const resolvedSchema = resolveSchema(document, schema, operationId, context, refChain);
+    const compositionKeyword = getCompositionKeyword(resolvedSchema);
+    if (compositionKeyword !== undefined) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported ${context}. JSON Schema composition keyword ${JSON.stringify(compositionKeyword)} is not supported in v1.`);
+    }
+    return resolvedSchema;
+}
+function resolveSchema(document, schema, operationId, context, refChain = []) {
+    if (schema === undefined) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} is missing a schema for ${context}.`);
+    }
+    if (isReferenceObject(schema)) {
+        assertAcyclicRef(schema.$ref, refChain, operationId, context);
+        return resolveSchema(document, resolveLocalReference(document, schema.$ref, operationId, context), operationId, context, [...refChain, schema.$ref]);
+    }
+    return schema;
+}
+function getCompositionKeyword(schema) {
+    for (const keyword of ["allOf", "anyOf", "oneOf"]) {
+        if (schema[keyword] !== undefined) {
+            return keyword;
+        }
+    }
+    return undefined;
+}
+function resolveNullableAnyOfSchema(document, schema, operationId, context) {
+    const variants = schema.anyOf;
+    if (variants === undefined || variants.length !== 2) {
+        return undefined;
+    }
+    const resolvedVariants = variants.map((variant, index) => resolveSchema(document, variant, operationId, `${context} anyOf variant ${index}`));
+    const nullVariantIndex = resolvedVariants.findIndex(isExplicitNullSchema);
+    if (nullVariantIndex === -1) {
+        return undefined;
+    }
+    const nonNullVariant = resolvedVariants[Number(!nullVariantIndex)];
+    if (nonNullVariant === undefined || getCompositionKeyword(nonNullVariant) !== undefined) {
+        return undefined;
+    }
+    return {
+        ...nonNullVariant,
+        nullable: true
+    };
+}
+function isExplicitNullSchema(schema) {
+    return schema.type === "null";
+}
+function assertAcyclicRef(ref, refChain, operationId, context) {
+    if (!refChain.includes(ref)) {
+        return;
+    }
+    throw new UserError(`Operation ${JSON.stringify(operationId)} uses circular $ref chain in ${context}: ${[
+        ...refChain,
+        ref
+    ]
+        .map((value) => JSON.stringify(value))
+        .join(" -> ")}.`);
+}
+function expectArrayItemsSchema(document, schema, operationId, context) {
+    if (schema.items === undefined) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} is missing array items for ${context}.`);
+    }
+    return expectSchema(document, schema.items, operationId, `${context} items`);
+}
+function assertUniqueCommandPaths(commands) {
+    const seen = new Map();
+    for (const command of commands) {
+        const key = `${command.noun} ${command.verb}`;
+        const existing = seen.get(key);
+        if (existing !== undefined) {
+            throw new UserError(`Generated command path ${JSON.stringify(key)} is defined more than once (${JSON.stringify(existing.operationId)} and ${JSON.stringify(command.operationId)}).`);
+        }
+        seen.set(key, command);
+    }
+}
+function createCommandFile(options) {
+    const requiresUserError = options.preflightBlocks.length > 0;
+    const lines = createGeneratedTypeScriptFileLines([
+        `spec-sha: ${options.specSha}`,
+        `operation-id: ${options.operationId}`
+    ]);
+    lines.push(requiresUserError
+        ? 'import { S, UserError } from "agent-kit";'
+        : 'import { S } from "agent-kit";', 'import { requestJson, defineApiCommand } from "agent-kit-openapi";', "", `export const ${options.exportName} = defineApiCommand({`, `  name: ${JSON.stringify(options.verb)},`);
+    if (options.description !== undefined) {
+        lines.push(`  description: ${JSON.stringify(options.description)},`);
+    }
+    lines.push('  scope: ["cli", "mcp", "sdk"] as const,');
+    if (options.confirm) {
+        lines.push("  confirm: true,");
+    }
+    lines.push("  params: S.Object({");
+    lines.push(...renderParamLines(options.params));
+    lines.push(options.paramsSchemaOptions?.additionalProperties === false
+        ? "  }, { additionalProperties: false }),"
+        : "  }),");
+    lines.push("  handler: async ({ params, baseUrl, tokenSource, fetch }) => {");
+    lines.push(...options.preflightBlocks.flatMap((block) => renderPreflightBlock(block)));
+    lines.push("    return requestJson({");
+    lines.push("      baseUrl,");
+    lines.push(`      path: ${JSON.stringify(options.path)},`);
+    lines.push(`      method: ${JSON.stringify(options.method)},`);
+    lines.push(`      auth: ${JSON.stringify(options.auth)},`);
+    lines.push("      tokenSource,");
+    lines.push("      fetch,");
+    lines.push("      dryRun: params.dryRun,");
+    lines.push("      verbose: params.verbose,");
+    lines.push(...renderRequestShape(options.requestFields, options.sectionRenders, options.optionalSections));
+    lines.push("    });");
+    lines.push("  },");
+    lines.push("});");
+    lines.push("");
+    return lines.join("\n");
+}
+function mergeCommandDescriptions(operationDescription, requestBodyDescription) {
+    const operationText = operationDescription === undefined || operationDescription.length === 0
+        ? undefined
+        : operationDescription;
+    const requestBodyText = requestBodyDescription === undefined || requestBodyDescription.length === 0
+        ? undefined
+        : requestBodyDescription;
+    if (operationText === undefined ||
+        requestBodyText === undefined ||
+        operationText === requestBodyText) {
+        return operationText ?? requestBodyText;
+    }
+    return `${operationText}\n\nRequest body: ${requestBodyText}`;
+}
+function getOperationAuthMode(document, operation, operationId) {
+    const security = operation.security ?? document.security;
+    const securityScope = operation.security === undefined ? "document" : "operation";
+    const definedSchemes = document.components?.securitySchemes;
+    for (const requirement of security ?? []) {
+        for (const schemeName of Object.keys(requirement)) {
+            if (definedSchemes !== undefined && schemeName in definedSchemes) {
+                continue;
+            }
+            throw new UserError(`Operation ${JSON.stringify(operationId)} references undefined security scheme ${JSON.stringify(schemeName)} in ${securityScope} security. Expected components.securitySchemes to define it.`);
+        }
+    }
+    return security === undefined || security.length === 0 ? "none" : "required";
+}
+function assertSupportedHttpMethods(path, pathItem) {
+    const rawPathItem = pathItem;
+    for (const method of UNSUPPORTED_HTTP_METHODS) {
+        const operation = rawPathItem[method];
+        if (operation === undefined) {
+            continue;
+        }
+        throw new UserError(`Operation ${JSON.stringify(getOperationId(path, method, operation))} uses unsupported HTTP method ${JSON.stringify(method.toUpperCase())}. Supported in v1: GET, POST, PUT, PATCH, DELETE.`);
+    }
+}
+function getOperationId(path, method, operation) {
+    if (operation !== null &&
+        typeof operation === "object" &&
+        "operationId" in operation &&
+        typeof operation.operationId === "string" &&
+        operation.operationId.length > 0) {
+        return operation.operationId;
+    }
+    return `${method.toUpperCase()} ${path}`;
+}
+function stripNullable(schema) {
+    if (schema.nullable !== true) {
+        return schema;
+    }
+    return { ...schema, nullable: undefined };
+}
+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);
+    return param.optional ? `S.Optional(${schema})` : schema;
+}
+function renderDefinition(definition, description, shortFlag, scope) {
+    const options = renderSchemaOptions({
+        definition,
+        description,
+        shortFlag,
+        scope
+    });
+    const renderer = DEFINITION_RENDERERS[definition.kind];
+    return renderer(definition, options);
+}
+const DEFINITION_RENDERERS = {
+    array: (definition, options) => renderSchemaCall("S.Array", renderDefinition(definition.itemDefinition, undefined, undefined, undefined), options),
+    boolean: (_definition, options) => renderSchemaCall("S.Boolean", options),
+    enum: (definition, options) => renderSchemaCall("S.Enum", renderConstArray(definition.enumValues), options),
+    number: (_definition, options) => renderSchemaCall("S.Number", options),
+    string: (_definition, options) => renderSchemaCall("S.String", options)
+};
+function renderSchemaCall(builder, ...args) {
+    return `${builder}(${args.filter((arg) => arg !== undefined).join(", ")})`;
+}
+function renderSchemaOptions(param) {
+    const entries = collectSchemaOptionEntries(param).map(({ key, value }) => `${key}: ${renderSchemaOptionValue(value)}`);
+    return entries.length === 0 ? undefined : `{ ${entries.join(", ")} }`;
+}
+function renderConstArray(values) {
+    return `${JSON.stringify(values)} as const`;
+}
+function renderObjectKey(name) {
+    if (name === normalizeParamName(name) && isIdentifierName(name)) {
+        return name;
+    }
+    return JSON.stringify(name);
+}
+function assertValidGeneratedNoun(operationId, noun) {
+    const identifier = toCamelCase(noun);
+    if (isTypeScriptIdentifier(identifier)) {
+        return;
+    }
+    throw new UserError(`Operation ${JSON.stringify(operationId)} derives command noun ${JSON.stringify(noun)}, which maps to invalid TypeScript identifier ${JSON.stringify(identifier)}.`);
+}
+export function collectSchemaOptionEntries(param) {
+    return SCHEMA_OPTION_SOURCES.flatMap(({ key, get }) => {
+        const value = get(param);
+        return value === undefined ? [] : [{ key, value }];
+    });
+}
+function renderSchemaOptionValue(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => renderSchemaOptionValue(entry)).join(", ")}]`;
+    }
+    return JSON.stringify(value);
+}
+const RESERVED_TYPESCRIPT_IDENTIFIERS = new Set([
+    "abstract",
+    "any",
+    "as",
+    "asserts",
+    "async",
+    "await",
+    "bigint",
+    "boolean",
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "declare",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "enum",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "get",
+    "if",
+    "implements",
+    "import",
+    "in",
+    "infer",
+    "instanceof",
+    "interface",
+    "is",
+    "keyof",
+    "let",
+    "module",
+    "namespace",
+    "never",
+    "new",
+    "null",
+    "number",
+    "object",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "readonly",
+    "return",
+    "satisfies",
+    "set",
+    "static",
+    "string",
+    "super",
+    "switch",
+    "symbol",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "type",
+    "typeof",
+    "undefined",
+    "unique",
+    "unknown",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield"
+]);
+function isTypeScriptIdentifier(value) {
+    return isIdentifierName(value) && !RESERVED_TYPESCRIPT_IDENTIFIERS.has(value);
+}
+function resolveQueryArraySerialization(parameter, operationId) {
+    const style = parameter.style ?? "form";
+    const explode = parameter.explode ?? style === "form";
+    if (style === "form") {
+        return explode ? "repeat" : "comma";
+    }
+    if (style === "pipeDelimited" && explode === false) {
+        return "pipe";
+    }
+    throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported query-array serialization for parameter ${JSON.stringify(parameter.name)}. Supported in v1: form (explode true/false) and pipeDelimited.`);
+}
+function createIndexFile(commands) {
+    const groups = groupByNoun(commands);
+    if (groups.length === 0) {
+        return {
+            path: "index.ts",
+            contents: createGeneratedTypeScriptFile(["export {};", ""])
+        };
+    }
+    const lines = createGeneratedTypeScriptFileLines();
+    lines.push('import { defineGroup } from "agent-kit";');
+    for (const { commands: nounCommands } of groups) {
+        for (const command of nounCommands) {
+            lines.push(`import { ${command.exportName} } from ${JSON.stringify(`./${command.filePath.replace(/\.ts$/, ".js")}`)};`);
+        }
+    }
+    if (lines.length > 1) {
+        lines.push("");
+    }
+    for (const { noun, commands: nounCommands } of groups) {
+        lines.push(`export const ${toCamelCase(noun)} = defineGroup({`);
+        lines.push(`  name: ${JSON.stringify(noun)},`);
+        lines.push(`  children: [${nounCommands.map((command) => command.exportName).join(", ")}],`);
+        lines.push("});");
+        lines.push("");
+    }
+    return {
+        path: "index.ts",
+        contents: lines.join("\n")
+    };
+}
+function createGeneratedTypeScriptFile(bodyLines, metadataLines = []) {
+    return [...createGeneratedTypeScriptFileLines(metadataLines), ...bodyLines].join("\n");
+}
+function createGeneratedTypeScriptFileLines(metadataLines = []) {
+    return [
+        "/**",
+        " * Generated by agent-kit-openapi.",
+        ...metadataLines.map((line) => ` * ${line}`),
+        " */"
+    ];
+}
+function compareGeneratedCommandPaths(left, right) {
+    const nounCompare = left.noun.localeCompare(right.noun);
+    if (nounCompare !== 0) {
+        return nounCompare;
+    }
+    return left.verb.localeCompare(right.verb);
+}
+function isReferenceObject(value) {
+    return typeof value === "object" && value !== null && "$ref" in value;
+}