toolcraft-openapi 0.0.27 → 0.0.33

package/dist/auth/bearer-token-auth.js

@@ -1,5 +1,5 @@
 import { defineCommand, defineGroup, S, UserError } from "toolcraft";
-import { isCancel, password } from "@poe-code/design-system";
+import { isCancel, password } from "toolcraft-design";
 import { createSecretStore } from "auth-store";
 import { requestJson } from "../http.js";
 const DEFAULT_COMMAND_PREFIX = "auth";

package/dist/bin/generate.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { type OutputFormat } from "toolcraft-design";
 interface GenerateCliFileSystem {
     lstat(targetPath: string): Promise<{
         isDirectory(): boolean;
@@ -9,11 +10,16 @@ interface GenerateCliFileSystem {
     }): Promise<unknown>;
     readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
     readdir(directoryPath: string): Promise<string[]>;
+    rename(oldPath: string, newPath: string): Promise<unknown>;
     rm(targetPath: string, options?: {
         force?: boolean;
     }): Promise<void>;
     realpath(targetPath: string): Promise<string>;
-    writeFile(filePath: string, contents: string, encoding: BufferEncoding): Promise<void>;
+    unlink(targetPath: string): Promise<void>;
+    writeFile(filePath: string, contents: string, options: BufferEncoding | {
+        encoding?: BufferEncoding;
+        flag?: string;
+    }): Promise<void>;
 }
 interface GenerateCliWriter {
     write(chunk: string | Uint8Array): boolean;
@@ -28,6 +34,8 @@ interface GenerateCliServices {
 interface GenerateCliOptions {
     check: boolean;
     input: string;
+    inspect: boolean;
+    outputFormat: OutputFormat;
     outputDir: string;
 }
 interface SyncGeneratedClientResult {

package/dist/bin/generate.js

@@ -1,15 +1,21 @@
 #!/usr/bin/env node
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { UserError } from "toolcraft";
+import { hasOwnErrorCode } from "../error-codes.js";
+import { withOutputFormat } from "toolcraft-design";
 import { generate } from "../generate.js";
+import { inspectOpenApiSource } from "../inspect-source.js";
+import { renderOpenApiInspection } from "../render-inspection.js";
 import { parseOpenApiDocument, readOpenApiSourceText } from "../spec-source.js";
 const DEFAULT_OPTIONS = {
     check: false,
     input: "openapi.json",
+    inspect: false,
+    outputFormat: "terminal",
     outputDir: "src/generated"
 };
 const HELP_TEXT = `Usage: toolcraft-openapi-generate [options]
@@ -18,6 +24,8 @@ Options:
   --input <path-or-url>  OpenAPI document to read (default: openapi.json)
   --output <dir>         Directory for generated command files (default: src/generated)
   --check                Exit non-zero if generated output would change
+  --inspect              Inspect route compatibility without writing files
+  --output-format <fmt>  Inspection output: terminal, markdown, or json (default: terminal)
   -h, --help             Show this help text
 `;
 export async function runGenerateCli(argv = process.argv, services = {
@@ -33,6 +41,11 @@ export async function runGenerateCli(argv = process.argv, services = {
             services.stdout.write(HELP_TEXT);
             return 0;
         }
+        if (parsed.inspect) {
+            const report = await inspectOpenApiSource(parsed.input, services);
+            services.stdout.write(`${withOutputFormat(parsed.outputFormat, () => renderOpenApiInspection(report))}\n`);
+            return 0;
+        }
         const result = await syncGeneratedClient(parsed, services);
         if (parsed.check) {
             if (result.drifted) {
@@ -106,7 +119,11 @@ function parseGenerateCliArgs(argv) {
             options.check = true;
             continue;
         }
-        if (argument === "--input" || argument === "--output") {
+        if (argument === "--inspect") {
+            options.inspect = true;
+            continue;
+        }
+        if (argument === "--input" || argument === "--output" || argument === "--output-format") {
             const value = argv[index + 1];
             if (value === undefined) {
                 throw new UserError(`Missing value for ${JSON.stringify(argument)}.`);
@@ -123,6 +140,10 @@ function parseGenerateCliArgs(argv) {
             assignOptionValue(options, "--output", argument.slice("--output=".length));
             continue;
         }
+        if (argument.startsWith("--output-format=")) {
+            assignOptionValue(options, "--output-format", argument.slice("--output-format=".length));
+            continue;
+        }
         throw new UserError(`Unknown argument ${JSON.stringify(argument)}.`);
     }
     return options;
@@ -135,6 +156,13 @@ function assignOptionValue(options, argument, value) {
         options.input = value;
         return;
     }
+    if (argument === "--output-format") {
+        if (value !== "terminal" && value !== "markdown" && value !== "json") {
+            throw new UserError(`Invalid value ${JSON.stringify(value)} for "--output-format". Expected terminal, markdown, or json.`);
+        }
+        options.outputFormat = value;
+        return;
+    }
     options.outputDir = value;
 }
 function createSpecSha(sourceText) {
@@ -221,7 +249,7 @@ async function writeGeneratedFiles(fs, outputDir, filesToWrite) {
     for (const file of filesToWrite) {
         await fs.mkdir(path.dirname(file.path), { recursive: true });
         await assertSafeOutputPath(fs, outputDir, file.path);
-        await fs.writeFile(file.path, file.contents, "utf8");
+        await atomicWriteGeneratedFile(fs, outputDir, file.path, file.contents);
     }
 }
 async function assertSafeOutputPath(fs, outputDir, filePath) {
@@ -234,6 +262,34 @@ async function assertSafeOutputPath(fs, outputDir, filePath) {
         canonicalOutputDir !== path.resolve(outputDir)) {
         throw new Error("Generated output must remain inside the output directory.");
     }
+    try {
+        if ((await fs.lstat(filePath)).isSymbolicLink()) {
+            throw new Error("Generated output must remain inside the output directory.");
+        }
+    }
+    catch (error) {
+        if (!isNotFoundError(error)) {
+            throw error;
+        }
+    }
+}
+async function atomicWriteGeneratedFile(fs, outputDir, filePath, contents) {
+    const tempPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${randomUUID()}.tmp`);
+    let tempCreated = false;
+    try {
+        await assertSafeOutputPath(fs, outputDir, tempPath);
+        await fs.writeFile(tempPath, contents, { encoding: "utf8", flag: "wx" });
+        tempCreated = true;
+        await assertSafeOutputPath(fs, outputDir, filePath);
+        await fs.rename(tempPath, filePath);
+        tempCreated = false;
+    }
+    catch (error) {
+        if (tempCreated || !isAlreadyExistsError(error)) {
+            await fs.unlink(tempPath).catch(() => undefined);
+        }
+        throw error;
+    }
 }
 async function deleteGeneratedFiles(fs, outputDir, filePaths) {
     for (const filePath of filePaths) {
@@ -251,7 +307,7 @@ async function restoreGeneratedFiles(fs, outputDir, currentFiles, updatedFiles,
         }
         await fs.mkdir(path.dirname(file.path), { recursive: true });
         await assertSafeOutputPath(fs, outputDir, file.path);
-        await fs.writeFile(file.path, previousContents, "utf8");
+        await atomicWriteGeneratedFile(fs, outputDir, file.path, previousContents);
     }
     for (const filePath of deletedFiles) {
         const previousContents = currentFiles.get(filePath);
@@ -260,14 +316,14 @@ async function restoreGeneratedFiles(fs, outputDir, currentFiles, updatedFiles,
         }
         await fs.mkdir(path.dirname(filePath), { recursive: true });
         await assertSafeOutputPath(fs, outputDir, filePath);
-        await fs.writeFile(filePath, previousContents, "utf8");
+        await atomicWriteGeneratedFile(fs, outputDir, filePath, previousContents);
     }
 }
 function isNotFoundError(error) {
-    return (typeof error === "object" &&
-        error !== null &&
-        "code" in error &&
-        error.code === "ENOENT");
+    return hasOwnErrorCode(error, "ENOENT");
+}
+function isAlreadyExistsError(error) {
+    return hasOwnErrorCode(error, "EEXIST");
 }
 function isDirectExecution(moduleUrl, argv) {
     const entryPoint = argv[1];

package/dist/error-codes.d.ts

@@ -0,0 +1 @@
+export declare function hasOwnErrorCode(error: unknown, code: string): error is NodeJS.ErrnoException;

package/dist/error-codes.js

@@ -0,0 +1,6 @@
+export function hasOwnErrorCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        Object.prototype.hasOwnProperty.call(error, "code") &&
+        error.code === code);
+}

package/dist/generate.d.ts

@@ -58,6 +58,10 @@ export interface OpenApiResponseObject {
 }
 export interface OpenApiMediaTypeObject {
     schema?: OpenApiSchemaObject | OpenApiReferenceObject;
+    example?: unknown;
+    examples?: Record<string, {
+        value?: unknown;
+    } | undefined>;
 }
 export interface OpenApiSchemaObject {
     type?: OpenApiJsonSchemaType | readonly OpenApiJsonSchemaType[];
@@ -93,6 +97,7 @@ interface OpenApiServerObject {
 type OpenApiSecurityRequirementObject = Record<string, string[]>;
 export interface GenerateOptions {
     specSha: string;
+    brand?: string;
 }
 export interface GeneratedFile {
     path: string;
@@ -108,6 +113,12 @@ export interface GeneratedCommand {
     method: string;
     path: string;
     auth: "required" | "none";
+    responseMode: "json" | "text" | "binary";
+    accept: string;
+    baseUrl?: string;
+    bodyMode?: "json" | "form" | "raw" | "base64" | "multipart";
+    contentType?: string;
+    multipartBinaryFields?: readonly string[];
     confirm: boolean;
     params: GeneratedParam[];
     paramsSchemaOptions?: GeneratedObjectSchemaOptions;
@@ -119,7 +130,7 @@ export interface GeneratedCommand {
 export interface GeneratedParam {
     paramName: string;
     sourceName: string;
-    location: "path" | "query" | "body" | "transport";
+    location: "path" | "query" | "header" | "body" | "transport";
     description?: string;
     shortFlag?: string;
     scope?: readonly [GeneratedParamScope, ...GeneratedParamScope[]];
@@ -152,7 +163,10 @@ interface GeneratedArrayParamDefinition extends GeneratedParamDefinitionMetadata
     kind: "array";
     itemDefinition: GeneratedParamDefinition;
 }
-export type GeneratedParamDefinition = GeneratedScalarParamDefinition | GeneratedEnumParamDefinition | GeneratedArrayParamDefinition;
+interface GeneratedJsonParamDefinition extends GeneratedParamDefinitionMetadata {
+    kind: "json";
+}
+export type GeneratedParamDefinition = GeneratedScalarParamDefinition | GeneratedEnumParamDefinition | GeneratedArrayParamDefinition | GeneratedJsonParamDefinition;
 type GeneratedParamScope = "cli" | "mcp" | "sdk";
 type GeneratedEnumValue = string | number | boolean;
 export type GeneratedValueReference = {
@@ -165,6 +179,8 @@ export type GeneratedValueReference = {
 export type GeneratedValueExpression = {
     kind: "reference";
     reference: GeneratedValueReference;
+} | {
+    kind: "emptyObject";
 } | {
     kind: "queryArray";
     reference: GeneratedValueReference;
@@ -208,8 +224,9 @@ interface SchemaOptionEntry {
     key: string;
     value: unknown;
 }
-type QueryArraySerialization = "repeat" | "comma" | "pipe";
+type QueryArraySerialization = "repeat" | "brackets" | "comma" | "pipe";
 export declare function generate(document: OpenApiDocument, options: GenerateOptions): GeneratedFile[];
 export declare function collectGeneratedCommands(document: OpenApiDocument): GeneratedCommand[];
+export declare function collectGeneratedCommand(document: OpenApiDocument, path: string, method: HttpMethod): GeneratedCommand;
 export declare function collectSchemaOptionEntries(param: RenderSchemaOptionsInput): SchemaOptionEntry[];
 export {};