toolcraft-openapi 0.0.27 → 0.0.34

package/dist/generate.js

@@ -1,10 +1,11 @@
 import { ToolcraftBugError, UserError } from "toolcraft";
-import { METHOD_DEFAULTS, deriveNoun, deriveVerb, isIdentifierName, normalizeParamName, toCamelCase, toPascalCase } from "./naming.js";
+import { METHOD_DEFAULTS, deriveDisambiguatedVerb, deriveNoun, derivePathDisambiguatedVerb, deriveVerb, isIdentifierName, normalizeNoun, 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"]);
+import { normalizeOpenApiDocument } from "./normalize-swagger.js";
+const HTTP_METHOD_ORDER = ["get", "post", "put", "patch", "delete", "head", "options"];
+const UNSUPPORTED_HTTP_METHODS = ["trace"];
+const METHODS_WITHOUT_REQUEST_BODY = new Set(["head", "options"]);
 const SCHEMA_TYPE_TO_KIND = {
     boolean: { kind: "boolean" },
     integer: { kind: "number", jsonType: "integer" },
@@ -13,6 +14,7 @@ const SCHEMA_TYPE_TO_KIND = {
 };
 const NULL_HELPER_SUPPORT = {
     body: { array: true, scalar: true },
+    header: { array: false, scalar: false },
     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.
@@ -108,7 +110,10 @@ const SCHEMA_OPTION_SOURCES = [
     }
 ];
 export function generate(document, options) {
-    const commands = collectGeneratedCommands(document);
+    const normalizedDocument = normalizeOpenApiDocument(document);
+    const commands = collectGeneratedCommands(normalizedDocument);
+    const brand = options.brand ?? "blue";
+    const label = normalizedDocument.info?.title ?? "Toolcraft";
     return [
         ...commands.map((command) => ({
             path: command.filePath,
@@ -117,18 +122,30 @@ export function generate(document, options) {
                 ...command
             })
         })),
-        createIndexFile(commands)
+        createIndexFile(commands),
+        createCliFile({ brand, label })
     ];
 }
 export function collectGeneratedCommands(document) {
-    const paths = document.paths;
+    const normalizedDocument = normalizeOpenApiDocument(document);
+    const paths = normalizedDocument.paths;
     if (paths === undefined) {
         throw new UserError('OpenAPI document must define a top-level "paths" object.');
     }
-    const commands = collectOperations(paths).map((entry) => createGeneratedCommand(document, entry));
+    const commands = collectOperations(paths).map((entry) => createGeneratedCommand(normalizedDocument, entry));
+    disambiguateCommandPaths(commands);
     assertUniqueCommandPaths(commands);
     return commands.slice().sort((left, right) => compareGeneratedCommandPaths(left, right));
 }
+export function collectGeneratedCommand(document, path, method) {
+    const normalizedDocument = normalizeOpenApiDocument(document);
+    const pathItem = normalizedDocument.paths?.[path];
+    const operation = pathItem?.[method];
+    if (pathItem === undefined || operation === undefined) {
+        throw new ToolcraftBugError(`Cannot generate missing OpenAPI operation ${method.toUpperCase()} ${path}.`);
+    }
+    return createGeneratedCommand(normalizedDocument, { method, path, operation, pathItem });
+}
 function collectOperations(paths) {
     return Object.entries(paths)
         .sort(([left], [right]) => left.localeCompare(right))
@@ -138,7 +155,7 @@ function collectOperations(paths) {
         }
         assertSupportedHttpMethods(path, pathItem);
         return HTTP_METHOD_ORDER.flatMap((method) => {
-            const operation = pathItem[method];
+            const operation = getOwnPathItemValue(pathItem, method);
             if (operation === undefined) {
                 return [];
             }
@@ -146,15 +163,20 @@ function collectOperations(paths) {
         });
     });
 }
+function getOwnPathItemValue(pathItem, key) {
+    return Object.prototype.hasOwnProperty.call(pathItem, key)
+        ? pathItem[key]
+        : undefined;
+}
 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 operationBaseUrl = resolveOperationBaseUrl(operation, operationId);
+    const auth = getOperationAuthMode(document, operation, operationId);
+    const response = resolveSuccessResponse(document, operation, operationId);
+    const noun = createSafeGeneratedNoun(deriveNoun(operation, entry.path, operationId));
     const verb = deriveVerb(entry.method, entry.path, operation, operationId, noun);
-    const collected = collectParams(document, entry, operation, operationId);
+    const collected = collectParams(document, entry, operation, operationId, auth);
     const methodDefaults = METHOD_DEFAULTS[entry.method];
     const exportName = `${toCamelCase(noun)}${toPascalCase(verb)}Command`;
     const filePath = `${noun}/${verb}.ts`;
@@ -167,7 +189,13 @@ function createGeneratedCommand(document, entry) {
         description: mergeCommandDescriptions(operation.description ?? operation.summary, collected.requestBodyDescription),
         method: entry.method.toUpperCase(),
         path: entry.path,
-        auth: getOperationAuthMode(document, operation, operationId),
+        auth,
+        responseMode: response.mode,
+        accept: response.accept,
+        baseUrl: operationBaseUrl,
+        bodyMode: collected.bodyMode,
+        contentType: collected.contentType,
+        multipartBinaryFields: collected.multipartBinaryFields,
         confirm: methodDefaults?.confirm === true,
         params: collected.params,
         paramsSchemaOptions: collected.paramsSchemaOptions,
@@ -177,15 +205,26 @@ function createGeneratedCommand(document, entry) {
         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 resolveOperationBaseUrl(operation, operationId) {
+    if (operation.servers === undefined) {
+        return undefined;
+    }
+    const [server] = operation.servers;
+    if (operation.servers.length !== 1 || server === undefined || server.url.includes("{")) {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} must define exactly one fixed per-operation server URL in v1.`);
+    }
+    try {
+        return new URL(server.url).toString().replace(/\/$/, "");
+    }
+    catch {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} defines invalid per-operation server URL ${JSON.stringify(server.url)}.`);
     }
 }
-function collectParams(document, entry, operation, operationId) {
-    const operationParams = collectOperationParameters(document, entry.path, entry.pathItem.parameters ?? [], operation.parameters ?? [], operationId);
+function collectParams(document, entry, operation, operationId, auth) {
+    const operationParams = collectOperationParameters(document, entry.path, entry.pathItem.parameters ?? [], operation.parameters ?? [], operationId, auth);
     const requestBodyParams = collectRequestBodyParams(document, operation, operationId, entry.method);
-    const params = [...operationParams.params, ...requestBodyParams.params, ...TRANSPORT_PARAMS];
+    const qualifiedRequestBodyParams = qualifyBodyParamCollisions(requestBodyParams, new Set([...operationParams.params, ...TRANSPORT_PARAMS].map((param) => param.paramName)));
+    const params = [...operationParams.params, ...qualifiedRequestBodyParams.params, ...TRANSPORT_PARAMS];
     const deduped = new Map();
     for (const param of params) {
         const existing = deduped.get(param.paramName);
@@ -196,18 +235,75 @@ function collectParams(document, entry, operation, operationId) {
     }
     return {
         params: [...deduped.values()],
-        paramsSchemaOptions: requestBodyParams.paramsSchemaOptions,
-        preflightBlocks: [...operationParams.preflightBlocks, ...requestBodyParams.preflightBlocks],
-        requestFields: [...operationParams.requestFields, ...requestBodyParams.requestFields],
-        sectionRenders: { ...operationParams.sectionRenders, ...requestBodyParams.sectionRenders },
+        paramsSchemaOptions: qualifiedRequestBodyParams.paramsSchemaOptions,
+        preflightBlocks: [...operationParams.preflightBlocks, ...qualifiedRequestBodyParams.preflightBlocks],
+        requestFields: [...operationParams.requestFields, ...qualifiedRequestBodyParams.requestFields],
+        sectionRenders: { ...operationParams.sectionRenders, ...qualifiedRequestBodyParams.sectionRenders },
         optionalSections: new Set([
             ...operationParams.optionalSections,
-            ...requestBodyParams.optionalSections
+            ...qualifiedRequestBodyParams.optionalSections
         ]),
-        requestBodyDescription: requestBodyParams.requestBodyDescription
+        requestBodyDescription: qualifiedRequestBodyParams.requestBodyDescription,
+        bodyMode: qualifiedRequestBodyParams.bodyMode,
+        contentType: qualifiedRequestBodyParams.contentType,
+        multipartBinaryFields: qualifiedRequestBodyParams.multipartBinaryFields
     };
 }
-function collectOperationParameters(document, path, pathItemParameters, operationParameters, operationId) {
+function qualifyBodyParamCollisions(collected, reservedNames) {
+    const renames = new Map();
+    const usedNames = new Set(reservedNames);
+    for (const param of collected.params) {
+        let paramName = param.paramName;
+        if (usedNames.has(paramName)) {
+            const baseName = `body${toPascalCase(paramName)}`;
+            paramName = baseName;
+            let suffix = 2;
+            while (usedNames.has(paramName)) {
+                paramName = `${baseName}${suffix}`;
+                suffix += 1;
+            }
+            renames.set(param.paramName, paramName);
+        }
+        usedNames.add(paramName);
+    }
+    if (renames.size === 0) {
+        return collected;
+    }
+    const renameReference = (reference) => reference.kind === "param" && renames.has(reference.paramName)
+        ? { ...reference, paramName: renames.get(reference.paramName) }
+        : reference;
+    return {
+        ...collected,
+        params: collected.params.map((param) => ({
+            ...param,
+            paramName: renames.get(param.paramName) ?? param.paramName
+        })),
+        preflightBlocks: collected.preflightBlocks.map((block) => block.kind === "scalar-null"
+            ? {
+                ...block,
+                paramName: renames.get(block.paramName) ?? block.paramName,
+                nullParamName: renames.get(block.nullParamName) ?? block.nullParamName
+            }
+            : {
+                ...block,
+                paramName: renames.get(block.paramName) ?? block.paramName,
+                jsonParamName: renames.get(block.jsonParamName) ?? block.jsonParamName,
+                ...(block.nullParamName === undefined
+                    ? {}
+                    : { nullParamName: renames.get(block.nullParamName) ?? block.nullParamName })
+            }),
+        requestFields: collected.requestFields.map((field) => ({
+            ...field,
+            omitWhenUndefinedReference: renameReference(field.omitWhenUndefinedReference),
+            value: field.value.kind === "reference"
+                ? { ...field.value, reference: renameReference(field.value.reference) }
+                : field.value.kind === "queryArray"
+                    ? { ...field.value, reference: renameReference(field.value.reference) }
+                    : field.value
+        }))
+    };
+}
+function collectOperationParameters(document, path, pathItemParameters, operationParameters, operationId, auth) {
     const merged = new Map();
     for (const parameter of pathItemParameters) {
         const resolved = expectParameter(document, parameter, operationId);
@@ -217,12 +313,28 @@ function collectOperationParameters(document, path, pathItemParameters, operatio
         const resolved = expectParameter(document, parameter, operationId);
         merged.set(`${resolved.in}:${resolved.name}`, resolved);
     }
+    promoteQueryDeclaredPathParameters(path, merged);
     assertPathTemplateParameters(path, merged, operationId);
     const params = [];
     const preflightBlocks = [];
     const requestFields = [];
+    const usedParamNames = new Set();
     for (const parameter of merged.values()) {
-        const generated = createGeneratedParameter(document, parameter, operationId);
+        if (parameter.in === "header" &&
+            ["accept", "content-type"].includes(parameter.name.toLowerCase())) {
+            continue;
+        }
+        const paramName = usedParamNames.has(parameter.name)
+            ? `${parameter.in}${toPascalCase(parameter.name)}`
+            : parameter.name;
+        const generated = createGeneratedParameter(document, paramName === parameter.name ? parameter : { ...parameter, name: paramName }, operationId, auth);
+        generated.requestField.wireName = generated.requestField.wireName.endsWith("[]")
+            ? `${parameter.name}[]`
+            : parameter.name;
+        for (const param of generated.params) {
+            param.sourceName = parameter.name;
+            usedParamNames.add(param.paramName);
+        }
         params.push(...generated.params);
         preflightBlocks.push(...generated.preflightBlocks);
         requestFields.push(generated.requestField);
@@ -232,11 +344,24 @@ function collectOperationParameters(document, path, pathItemParameters, operatio
         paramsSchemaOptions: undefined,
         preflightBlocks,
         requestFields,
-        sectionRenders: { path: "wrapped", query: "wrapped" },
+        sectionRenders: { path: "wrapped", query: "wrapped", header: "wrapped" },
         optionalSections: new Set(),
         requestBodyDescription: undefined
     };
 }
+function promoteQueryDeclaredPathParameters(path, parameters) {
+    for (const placeholder of collectPathPlaceholders(path)) {
+        if (parameters.has(`path:${placeholder}`)) {
+            continue;
+        }
+        const queryParameter = parameters.get(`query:${placeholder}`);
+        if (queryParameter === undefined) {
+            continue;
+        }
+        parameters.delete(`query:${placeholder}`);
+        parameters.set(`path:${placeholder}`, { ...queryParameter, in: "path", required: true });
+    }
+}
 function collectRequestBodyParams(document, operation, operationId, method) {
     if (operation.requestBody === undefined) {
         return {
@@ -253,29 +378,65 @@ function collectRequestBodyParams(document, operation, operationId, 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];
+    const contentEntries = Object.entries(requestBody.content ?? {});
+    const contentEntry = contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && isJsonMediaType(mediaType)) ?? contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && mediaType.toLowerCase() === "application/x-www-form-urlencoded") ?? contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && isTextMediaType(mediaType)) ?? contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && isBinaryMediaType(mediaType)) ?? contentEntries.find(([mediaType, mediaTypeObject]) => mediaTypeObject !== undefined && mediaType.toLowerCase() === "multipart/form-data");
+    const content = contentEntry?.[1];
+    const requestMediaType = contentEntry?.[0];
+    const bodyMode = requestMediaType?.toLowerCase() === "application/x-www-form-urlencoded"
+        ? "form"
+        : requestMediaType?.toLowerCase() === "multipart/form-data"
+            ? "multipart"
+            : requestMediaType !== undefined && !isJsonMediaType(requestMediaType)
+                ? isTextMediaType(requestMediaType)
+                    ? "raw"
+                    : "base64"
+                : "json";
     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");
+    if (bodyMode === "raw" || bodyMode === "base64") {
+        const description = requestBody.description;
+        return {
+            ...createCollectedRequestBodyParams([
+                createBodyField(document, "body", { type: "string", ...(description === undefined ? {} : { description }) }, requestBody.required !== true, operationId)
+            ], requestBody.required !== true, description, "inline", undefined, bodyMode),
+            contentType: requestMediaType
+        };
+    }
+    const schema = resolveBodySchema(document, content.schema, operationId, "requestBody");
     const bodyOptional = requestBody.required !== true;
-    if (schema.type !== "object") {
+    const multipartBinaryFields = bodyMode === "multipart" && schema.properties !== undefined
+        ? Object.entries(schema.properties)
+            .filter(([, property]) => {
+            const resolved = resolveBodySchema(document, property, operationId, "requestBody multipart field");
+            return resolved.type === "string" && resolved.format === "binary";
+        })
+            .map(([name]) => name)
+        : undefined;
+    if (schema.type !== "object" || getCompositionKeyword(schema) !== undefined) {
         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.`);
+        return createCollectedRequestBodyParams([createBodyField(document, "body", bodySchema, bodyOptional, operationId)], bodyOptional, schema.description === undefined ? undefined : requestBody.description, "inline", undefined, bodyMode, multipartBinaryFields);
+    }
+    if ((schema.additionalProperties !== undefined && schema.additionalProperties !== false) ||
+        schema.properties === undefined) {
+        return createCollectedRequestBodyParams([createJsonBodyField({
+                document,
+                name: "body",
+                description: schema.description ?? requestBody.description,
+                schema,
+                optional: bodyOptional,
+                operationId,
+                context: "requestBody",
+                location: "body"
+            })], bodyOptional, requestBody.description, "inline", undefined, bodyMode, multipartBinaryFields);
     }
     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}`);
+        const propertySchema = resolveBodySchema(document, property, operationId, `requestBody.properties.${name}`);
         if (propertySchema.readOnly === true) {
             continue;
         }
@@ -283,14 +444,31 @@ function collectRequestBodyParams(document, operation, operationId, method) {
         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}.`);
+        if (declaredPropertyCount === 0) {
+            return {
+                params: [],
+                paramsSchemaOptions: schema.additionalProperties === false ? { additionalProperties: false } : undefined,
+                preflightBlocks: [],
+                requestFields: [{
+                        location: "body",
+                        wireName: "body",
+                        value: { kind: "emptyObject" },
+                        omitWhenUndefinedReference: { kind: "resolved", resolvedName: "emptyBody" }
+                    }],
+                sectionRenders: { body: "inline" },
+                optionalSections: new Set(),
+                requestBodyDescription: requestBody.description,
+                bodyMode,
+                ...(multipartBinaryFields === undefined ? {} : { multipartBinaryFields })
+            };
+        }
+        throw new UserError(`Operation ${JSON.stringify(operationId)} requestBody is required but all declared fields are readOnly.`);
     }
-    return createCollectedRequestBodyParams(assemblies, bodyOptional, requestBody.description, "wrapped", schema.additionalProperties === false ? { additionalProperties: false } : undefined);
+    return createCollectedRequestBodyParams(assemblies, bodyOptional, requestBody.description, "wrapped", schema.additionalProperties === false ? { additionalProperties: false } : undefined, bodyMode, multipartBinaryFields);
 }
-function assertSupportedSuccessResponses(document, operation, operationId) {
+function resolveSuccessResponse(document, operation, operationId) {
+    let textualMediaType;
+    let binaryMediaType;
     for (const [statusCode, response] of Object.entries(operation.responses ?? {})) {
         if (!isSuccessStatusCode(statusCode)) {
             continue;
@@ -300,45 +478,33 @@ function assertSupportedSuccessResponses(document, operation, operationId) {
             .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)}`);
-            }
+            declaredMediaTypes.some((mediaType) => isJsonMediaType(mediaType))) {
             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)}`);
+        const textual = declaredMediaTypes.find(isTextMediaType);
+        if (textual !== undefined && declaredMediaTypes.every(isTextMediaType)) {
+            textualMediaType ??= textual;
+            continue;
+        }
+        binaryMediaType ??= declaredMediaTypes[0];
     }
-    if (resolvedSchema.items !== undefined) {
-        assertSupportedSuccessResponseSchema(document, resolvedSchema.items, operationId, `${context} items`);
+    if (binaryMediaType !== undefined) {
+        return { mode: "binary", accept: binaryMediaType };
     }
+    return textualMediaType === undefined
+        ? { mode: "json", accept: "application/json" }
+        : { mode: "text", accept: textualMediaType };
 }
-function expectSupportedSuccessResponseSchema(document, schema, operationId, context) {
-    const resolvedSchema = normalizeNullableSchema(document, resolveSchema(document, schema, operationId, context), operationId, context);
-    const compositionKeyword = getCompositionKeyword(resolvedSchema);
-    if (compositionKeyword === undefined) {
-        return resolvedSchema;
+function createGeneratedParameter(document, parameter, operationId, auth) {
+    if (parameter.in === "header" &&
+        parameter.name.toLowerCase() === "authorization" &&
+        auth === "required") {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} header parameter ${JSON.stringify(parameter.name)} is managed by the HTTP transport and cannot be generated as a command parameter.`);
     }
-    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)}`);
+    const context = `parameter ${JSON.stringify(parameter.name)}`;
+    const schema = parameter.in === "query" && parameter.style === "deepObject"
+        ? resolveBodySchema(document, parameter.schema, operationId, context)
+        : expectSchema(document, parameter.schema, operationId, context);
     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.`);
@@ -348,19 +514,43 @@ function createGeneratedParameter(document, parameter, operationId) {
         }
         assertSupportedPathParameterSerialization(parameter, operationId);
     }
-    return createField({
+    if (parameter.in === "query" &&
+        parameter.style === "deepObject" &&
+        (getCompositionKeyword(schema) !== undefined ||
+            (schema.type === "array" && schema.items !== undefined && isComplexJsonBodySchema(document, schema.items, operationId, `${context} items`)))) {
+        return createJsonQueryField({
+            document,
+            name: parameter.name,
+            description: parameter.description ?? schema.description,
+            schema,
+            optional: parameter.required !== true,
+            operationId,
+            context,
+            location: "query",
+            queryObjectSerialization: resolveQueryObjectSerialization(parameter, operationId)
+        });
+    }
+    const querySerialization = parameter.in === "query" && schema.type === "array"
+        ? resolveQueryArraySerialization(parameter, operationId)
+        : undefined;
+    const generated = createField({
         document,
         name: parameter.name,
         description: parameter.description ?? schema.description,
         schema,
         optional: parameter.required !== true,
         operationId,
-        context: `parameter ${JSON.stringify(parameter.name)}`,
+        context,
         location: parameter.in,
-        querySerialization: parameter.in === "query" && schema.type === "array"
-            ? resolveQueryArraySerialization(parameter, operationId)
+        querySerialization,
+        queryObjectSerialization: parameter.in === "query" && schema.type === "object"
+            ? resolveQueryObjectSerialization(parameter, operationId)
             : undefined
     });
+    if (querySerialization === "brackets") {
+        generated.requestField.wireName = `${parameter.name}[]`;
+    }
+    return generated;
 }
 function assertSupportedPathParameterSerialization(parameter, operationId) {
     const style = parameter.style ?? "simple";
@@ -371,6 +561,18 @@ function assertSupportedPathParameterSerialization(parameter, operationId) {
     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) {
+    if (isComplexJsonBodySchema(document, schema, operationId, `request body field ${JSON.stringify(name)}`)) {
+        return createJsonBodyField({
+            document,
+            name,
+            description: schema.description,
+            schema,
+            optional,
+            operationId,
+            context: `request body field ${JSON.stringify(name)}`,
+            location: "body"
+        });
+    }
     return createField({
         document,
         name,
@@ -382,6 +584,32 @@ function createBodyField(document, name, schema, optional, operationId) {
         location: "body"
     });
 }
+function isComplexJsonBodySchema(document, schema, operationId, context) {
+    if (isUnconstrainedJsonSchema(schema)) {
+        return true;
+    }
+    if (schema.type === "object" ||
+        schema.properties !== undefined ||
+        schema.additionalProperties !== undefined ||
+        getCompositionKeyword(schema) !== undefined ||
+        Array.isArray(schema.type)) {
+        return true;
+    }
+    if (schema.type !== "array" || schema.items === undefined) {
+        return false;
+    }
+    const itemSchema = resolveBodySchema(document, schema.items, operationId, `${context} items`);
+    return isComplexJsonBodySchema(document, itemSchema, operationId, `${context} items`);
+}
+function isUnconstrainedJsonSchema(schema) {
+    return (schema.type === undefined &&
+        schema.enum === undefined &&
+        schema.properties === undefined &&
+        schema.additionalProperties === undefined &&
+        schema.allOf === undefined &&
+        schema.anyOf === undefined &&
+        schema.oneOf === undefined);
+}
 function createField(options) {
     return FIELD_ASSEMBLERS[options.location][getFieldSchemaKind(options.schema)](options);
 }
@@ -442,11 +670,53 @@ function createScalarParam(options) {
 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 createScalarOnlyParameterError(name, operationId, location) {
+    throw new UserError(`Operation ${JSON.stringify(operationId)} ${location} 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 createJsonBodyField(options) {
+    return {
+        params: [
+            {
+                paramName: options.name,
+                sourceName: options.name,
+                location: "body",
+                description: options.description,
+                optional: options.optional,
+                definition: { kind: "json" }
+            }
+        ],
+        preflightBlocks: [],
+        requestField: {
+            location: "body",
+            wireName: options.name,
+            value: { kind: "reference", reference: { kind: "param", paramName: options.name } },
+            omitWhenUndefinedReference: { kind: "param", paramName: options.name }
+        }
+    };
+}
+function createJsonQueryField(options) {
+    if (options.queryObjectSerialization !== "deepObject") {
+        throw new ToolcraftBugError("Missing deep-object serialization for generated JSON query field.");
+    }
+    return {
+        params: [
+            {
+                paramName: options.name,
+                sourceName: options.name,
+                location: "query",
+                description: options.description,
+                optional: options.optional,
+                definition: { kind: "json" }
+            }
+        ],
+        preflightBlocks: [],
+        requestField: {
+            location: "query",
+            wireName: options.name,
+            value: { kind: "reference", reference: { kind: "param", paramName: options.name } },
+            omitWhenUndefinedReference: { kind: "param", paramName: options.name }
+        }
+    };
 }
 function createArrayParam(options) {
     const { document, name, description, schema, optional, operationId, context, location } = options;
@@ -526,15 +796,23 @@ const FIELD_ASSEMBLERS = {
             ...options,
             location: "body"
         }),
-        object: (options) => createUnsupportedNestedBodyFieldError(options.name, options.operationId),
+        object: (options) => createJsonBodyField(options),
         scalar: (options) => createScalarParam({
             ...options,
             location: "body"
         })
     },
+    header: {
+        array: (options) => createScalarOnlyParameterError(options.name, options.operationId, "header"),
+        object: (options) => createScalarOnlyParameterError(options.name, options.operationId, "header"),
+        scalar: (options) => createScalarParam({
+            ...options,
+            location: "header"
+        })
+    },
     path: {
-        array: (options) => createPathScalarOnlyError(options.name, options.operationId),
-        object: (options) => createPathScalarOnlyError(options.name, options.operationId),
+        array: (options) => createPathArrayParam(options),
+        object: (options) => createScalarOnlyParameterError(options.name, options.operationId, "path"),
         scalar: (options) => createScalarParam({
             ...options,
             location: "path"
@@ -545,16 +823,34 @@ const FIELD_ASSEMBLERS = {
             ...options,
             location: "query"
         }),
-        object: (options) => createScalarParam({
-            ...options,
-            location: "query"
-        }),
+        object: (options) => createJsonQueryField(options),
         scalar: (options) => createScalarParam({
             ...options,
             location: "query"
         })
     }
 };
+function createPathArrayParam(options) {
+    const definition = createParamDefinition(options.document, options.schema, options.operationId, options.context);
+    const paramName = options.name;
+    return {
+        params: [{
+                paramName,
+                sourceName: options.name,
+                location: "path",
+                description: options.description,
+                optional: false,
+                definition
+            }],
+        preflightBlocks: [],
+        requestField: {
+            location: "path",
+            wireName: options.name,
+            value: { kind: "queryArray", reference: { kind: "param", paramName }, serialization: "comma" },
+            omitWhenUndefinedReference: { kind: "param", paramName }
+        }
+    };
+}
 function expectQueryArraySerialization(querySerialization) {
     if (querySerialization === undefined) {
         throw new ToolcraftBugError("Missing query array serialization for generated query array field.");
@@ -564,7 +860,7 @@ function expectQueryArraySerialization(querySerialization) {
 function supportsNullHelper(location, shape, nullable) {
     return nullable === true && NULL_HELPER_SUPPORT[location][shape];
 }
-function createCollectedRequestBodyParams(assemblies, bodyOptional, requestBodyDescription, bodyRender, paramsSchemaOptions) {
+function createCollectedRequestBodyParams(assemblies, bodyOptional, requestBodyDescription, bodyRender, paramsSchemaOptions, bodyMode, multipartBinaryFields) {
     return {
         params: assemblies.flatMap((assembly) => assembly.params),
         paramsSchemaOptions,
@@ -574,7 +870,9 @@ function createCollectedRequestBodyParams(assemblies, bodyOptional, requestBodyD
         optionalSections: bodyOptional
             ? new Set(["body"])
             : new Set(),
-        requestBodyDescription
+        requestBodyDescription,
+        bodyMode,
+        ...(multipartBinaryFields === undefined ? {} : { multipartBinaryFields })
     };
 }
 function createParamDefinition(document, schema, operationId, context) {
@@ -595,7 +893,7 @@ function createParamDefinition(document, schema, operationId, context) {
     const scalarDefinition = isOpenApiScalarType(schema.type)
         ? SCHEMA_TYPE_TO_KIND[schema.type]
         : undefined;
-    const enumValues = normalizeEnumValues(schema.enum, operationId, context, schema.nullable === true, schema.type);
+    const enumValues = normalizeEnumValues(schema.enum, operationId, context);
     if (enumValues !== undefined) {
         return {
             kind: "enum",
@@ -670,44 +968,32 @@ function isAsciiDigit(character) {
 }
 function isJsonMediaType(mediaType) {
     const normalized = mediaType.toLowerCase();
-    return normalized.includes("application/json") || normalized.includes("+json");
+    return normalized === "*/*" || normalized === "text/json" || normalized.includes("application/json") || normalized.includes("+json");
 }
-function normalizeEnumValues(enumValues, operationId, context, nullable, schemaType) {
+function isTextMediaType(mediaType) {
+    const normalized = mediaType.toLowerCase();
+    return normalized.startsWith("text/") || normalized === "plain/text" || normalized === "application/jwt";
+}
+function isBinaryMediaType(mediaType) {
+    const normalized = mediaType.toLowerCase();
+    return (normalized === "application/octet-stream" ||
+        normalized === "application/zip" ||
+        normalized === "application/gzip" ||
+        normalized === "application/pdf");
+}
+function normalizeEnumValues(enumValues, operationId, context) {
     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.`);
-    }
+    const filteredValues = enumValues.filter(isEnumPrimitiveValue);
     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);
+    return filteredValues.filter((value) => value !== null);
 }
 function resolveLocalReference(document, ref, operationId, context) {
     if (!ref.startsWith("#/")) {
@@ -715,7 +1001,9 @@ function resolveLocalReference(document, ref, operationId, context) {
     }
     let current = document;
     for (const segment of ref.slice(2).split("/").map(unescapeJsonPointerSegment)) {
-        if (typeof current !== "object" || current === null || !(segment in current)) {
+        if (typeof current !== "object" ||
+            current === null ||
+            !Object.prototype.hasOwnProperty.call(current, segment)) {
             throw new UserError(`Operation ${JSON.stringify(operationId)} references missing $ref ${JSON.stringify(ref)} in ${context}.`);
         }
         current = current[segment];
@@ -723,7 +1011,13 @@ function resolveLocalReference(document, ref, operationId, context) {
     return current;
 }
 function unescapeJsonPointerSegment(segment) {
-    return segment.replaceAll("~1", "/").replaceAll("~0", "~");
+    const unescaped = segment.replaceAll("~1", "/").replaceAll("~0", "~");
+    try {
+        return decodeURIComponent(unescaped);
+    }
+    catch {
+        return unescaped;
+    }
 }
 function expectParameter(document, parameter, operationId, refChain = []) {
     if (isReferenceObject(parameter)) {
@@ -733,8 +1027,8 @@ function expectParameter(document, parameter, operationId, refChain = []) {
     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.`);
+    if (parameter.in !== "path" && parameter.in !== "query" && parameter.in !== "header") {
+        throw new UserError(`Operation ${JSON.stringify(operationId)} uses unsupported parameter location ${JSON.stringify(parameter.in)}. Only path, query, and header parameters are supported in v1; use auth or handwritten commands for cookies.`);
     }
     return parameter;
 }
@@ -751,7 +1045,7 @@ function isEnumPrimitiveValue(value) {
     return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
 }
 function isOpenApiScalarType(type) {
-    return typeof type === "string" && Object.prototype.hasOwnProperty.call(SCHEMA_TYPE_TO_KIND, type);
+    return (typeof type === "string" && Object.prototype.hasOwnProperty.call(SCHEMA_TYPE_TO_KIND, type));
 }
 function expectRequestBody(document, requestBody, operationId, context, refChain = []) {
     if (!isReferenceObject(requestBody)) {
@@ -776,24 +1070,86 @@ function expectSchema(document, schema, operationId, context, refChain = []) {
     }
     return resolvedSchema;
 }
+function resolveBodySchema(document, schema, operationId, context) {
+    return normalizeNullableSchema(document, resolveSchema(document, schema, operationId, context), operationId, context);
+}
 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]);
+        const resolved = resolveLocalReference(document, schema.$ref, operationId, context);
+        const nestedSchema = isSchemaContainer(resolved) ? resolved.schema : resolved;
+        return resolveSchema(document, nestedSchema, operationId, context, [...refChain, schema.$ref]);
+    }
+    return cloneOwnSchemaObject(schema);
+}
+function cloneOwnSchemaObject(schema) {
+    const clone = Object.create(null);
+    for (const [key, value] of Object.entries(schema)) {
+        Object.defineProperty(clone, key, {
+            value,
+            enumerable: true,
+            configurable: true,
+            writable: true
+        });
     }
-    return schema;
+    return clone;
+}
+function isSchemaContainer(value) {
+    return !isReferenceObject(value) && "schema" in value && value.schema !== undefined;
 }
 function normalizeNullableSchema(document, schema, operationId, context) {
     const typeNormalizedSchema = normalizeNullableTypeArray(schema);
+    const equivalentComposition = resolveEquivalentCompositionSchema(document, typeNormalizedSchema, operationId, context);
+    if (equivalentComposition !== undefined) {
+        return equivalentComposition;
+    }
     if (getCompositionKeyword(typeNormalizedSchema) !== "anyOf") {
         return typeNormalizedSchema;
     }
     return (resolveNullableAnyOfSchema(document, typeNormalizedSchema, operationId, context) ??
         typeNormalizedSchema);
 }
+function resolveEquivalentCompositionSchema(document, schema, operationId, context) {
+    const keyword = getCompositionKeyword(schema);
+    if (keyword !== "anyOf" && keyword !== "oneOf") {
+        return undefined;
+    }
+    const variants = schema[keyword];
+    if (variants === undefined || variants.length === 0) {
+        return undefined;
+    }
+    const resolved = variants.map((variant, index) => normalizeNullableSchema(document, resolveSchema(document, variant, operationId, `${context} ${keyword} variant ${index}`), operationId, `${context} ${keyword} variant ${index}`));
+    const shapes = resolved.map(getEquivalentSchemaShape);
+    const [firstShape] = shapes;
+    if (firstShape === undefined || shapes.some((shape) => shape !== firstShape)) {
+        return undefined;
+    }
+    const { anyOf: _anyOf, oneOf: _oneOf, ...wrapper } = schema;
+    void _anyOf;
+    void _oneOf;
+    return { ...wrapper, ...createSchemaFromEquivalentShape(firstShape) };
+}
+function getEquivalentSchemaShape(schema) {
+    if (getCompositionKeyword(schema) !== undefined || Array.isArray(schema.type)) {
+        return undefined;
+    }
+    if (schema.type === "array") {
+        if (schema.items === undefined || isReferenceObject(schema.items))
+            return undefined;
+        const itemShape = getEquivalentSchemaShape(schema.items);
+        return itemShape === undefined ? undefined : `array:${itemShape}`;
+    }
+    return isOpenApiScalarType(schema.type) ? schema.type : undefined;
+}
+function createSchemaFromEquivalentShape(shape) {
+    if (!shape.startsWith("array:")) {
+        return { type: shape };
+    }
+    return { type: "array", items: createSchemaFromEquivalentShape(shape.slice("array:".length)) };
+}
 function normalizeNullableTypeArray(schema) {
     if (!Array.isArray(schema.type)) {
         return schema;
@@ -810,7 +1166,8 @@ function normalizeNullableTypeArray(schema) {
 }
 function getCompositionKeyword(schema) {
     for (const keyword of ["allOf", "anyOf", "oneOf"]) {
-        if (schema[keyword] !== undefined) {
+        if (Object.prototype.hasOwnProperty.call(schema, keyword) &&
+            schema[keyword] !== undefined) {
             return keyword;
         }
     }
@@ -872,6 +1229,59 @@ function assertUniqueCommandPaths(commands) {
         seen.set(key, command);
     }
 }
+function disambiguateCommandPaths(commands) {
+    const byCommandPath = new Map();
+    for (const command of commands) {
+        const key = `${command.noun} ${command.verb}`;
+        byCommandPath.set(key, [...(byCommandPath.get(key) ?? []), command]);
+    }
+    for (const collisions of byCommandPath.values()) {
+        if (collisions.length < 2) {
+            continue;
+        }
+        const existingPaths = new Set(commands
+            .filter((command) => !collisions.includes(command))
+            .map((command) => `${command.noun} ${command.verb}`));
+        const operationIdCandidates = collisions.map((command) => ({
+            command,
+            verb: deriveDisambiguatedVerb(command.operationId, command.noun)
+        }));
+        if (applyDisambiguatedVerbs(operationIdCandidates, existingPaths)) {
+            continue;
+        }
+        const pathCandidates = collisions.map((command) => ({
+            command,
+            verb: derivePathDisambiguatedVerb(command.method.toLowerCase(), command.path, command.noun, command.verb)
+        }));
+        if (applyDisambiguatedVerbs(pathCandidates, existingPaths)) {
+            continue;
+        }
+        if (applyDisambiguatedVerbs(collisions.map((command) => ({
+            command,
+            verb: derivePathDisambiguatedVerb(command.method.toLowerCase(), command.path, command.noun, command.verb, true)
+        })), existingPaths)) {
+            continue;
+        }
+        applyDisambiguatedVerbs(collisions.map((command) => ({
+            command,
+            verb: derivePathDisambiguatedVerb(command.method.toLowerCase(), command.path, command.noun, command.verb, true, true)
+        })), existingPaths);
+    }
+}
+function applyDisambiguatedVerbs(candidates, existingPaths) {
+    const candidatePaths = candidates.map(({ command, verb }) => `${command.noun} ${verb}`);
+    if (candidates.some(({ verb }) => verb.length === 0) ||
+        new Set(candidatePaths).size !== candidatePaths.length ||
+        candidatePaths.some((path) => existingPaths.has(path))) {
+        return false;
+    }
+    for (const { command, verb } of candidates) {
+        command.verb = verb;
+        command.exportName = `${toCamelCase(command.noun)}${toPascalCase(verb)}Command`;
+        command.filePath = `${command.noun}/${verb}.ts`;
+    }
+    return true;
+}
 function createCommandFile(options) {
     const requiresUserError = options.preflightBlocks.length > 0;
     const lines = createGeneratedTypeScriptFileLines([
@@ -896,10 +1306,36 @@ function createCommandFile(options) {
     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(options.baseUrl === undefined
+        ? "      baseUrl,"
+        : `      baseUrl: ${JSON.stringify(options.baseUrl)},`);
     lines.push(`      path: ${JSON.stringify(options.path)},`);
     lines.push(`      method: ${JSON.stringify(options.method)},`);
     lines.push(`      auth: ${JSON.stringify(options.auth)},`);
+    if (options.responseMode !== "json") {
+        lines.push(`      responseMode: ${JSON.stringify(options.responseMode)},`);
+    }
+    if (options.accept !== "application/json") {
+        lines.push(`      accept: ${JSON.stringify(options.accept)},`);
+    }
+    if (options.bodyMode === "form") {
+        lines.push('      bodyMode: "form",');
+    }
+    else if (options.bodyMode === "raw") {
+        lines.push('      bodyMode: "raw",');
+    }
+    else if (options.bodyMode === "base64") {
+        lines.push('      bodyMode: "base64",');
+    }
+    else if (options.bodyMode === "multipart") {
+        lines.push('      bodyMode: "multipart",');
+    }
+    if (options.multipartBinaryFields !== undefined) {
+        lines.push(`      multipartBinaryFields: ${JSON.stringify(options.multipartBinaryFields)},`);
+    }
+    if (options.contentType !== undefined) {
+        lines.push(`      contentType: ${JSON.stringify(options.contentType)},`);
+    }
     lines.push("      tokenSource,");
     lines.push("      fetch,");
     lines.push("      dryRun: params.dryRun,");
@@ -941,13 +1377,12 @@ function getOperationAuthMode(document, operation, operationId) {
     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];
+        const operation = getOwnPathItemValue(pathItem, 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.`);
+        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, HEAD, OPTIONS.`);
     }
 }
 function getOperationId(path, method, operation) {
@@ -988,6 +1423,7 @@ 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),
+    json: (_definition) => renderSchemaCall("S.Json"),
     number: (_definition, options) => renderSchemaCall("S.Number", options),
     string: (_definition, options) => renderSchemaCall("S.String", options)
 };
@@ -1010,12 +1446,9 @@ function renderObjectKey(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)}.`);
+function createSafeGeneratedNoun(noun) {
+    const normalized = normalizeNoun(noun);
+    return isTypeScriptIdentifier(toCamelCase(normalized)) ? normalized : `api-${normalized || "operation"}`;
 }
 export function collectSchemaOptionEntries(param) {
     return SCHEMA_OPTION_SOURCES.flatMap(({ key, get }) => {
@@ -1115,8 +1548,17 @@ function resolveQueryArraySerialization(parameter, operationId) {
     if (style === "pipeDelimited" && explode === false) {
         return "pipe";
     }
+    if (style === "deepObject" && explode === true) {
+        return "brackets";
+    }
     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 resolveQueryObjectSerialization(parameter, operationId) {
+    if (parameter.style === "deepObject" && parameter.explode !== false) {
+        return "deepObject";
+    }
+    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 createIndexFile(commands) {
     const groups = groupByNoun(commands);
     if (groups.length === 0) {
@@ -1147,6 +1589,22 @@ function createIndexFile(commands) {
         contents: lines.join("\n")
     };
 }
+function createCliFile(theme) {
+    return {
+        path: "cli.ts",
+        contents: [
+            "#!/usr/bin/env node",
+            ...createGeneratedTypeScriptFileLines(),
+            'import { configureTheme, runCLI } from "toolcraft/cli";',
+            'import * as groups from "./index.js";',
+            "",
+            `configureTheme({ brand: ${JSON.stringify(theme.brand)}, label: ${JSON.stringify(theme.label)} });`,
+            "",
+            "await runCLI(Object.values(groups));",
+            ""
+        ].join("\n")
+    };
+}
 function createGeneratedTypeScriptFile(bodyLines, metadataLines = []) {
     return [...createGeneratedTypeScriptFileLines(metadataLines), ...bodyLines].join("\n");
 }
@@ -1166,5 +1624,7 @@ function compareGeneratedCommandPaths(left, right) {
     return left.verb.localeCompare(right.verb);
 }
 function isReferenceObject(value) {
-    return typeof value === "object" && value !== null && "$ref" in value;
+    return (typeof value === "object" &&
+        value !== null &&
+        Object.prototype.hasOwnProperty.call(value, "$ref"));
 }