toolcraft-openapi 0.0.38 → 0.0.40

package/README.md

@@ -24,6 +24,10 @@ command files.
 - `--input <path-or-url>` — OpenAPI document to read. Defaults to `openapi.json`.
 - `--output <dir>` — directory for generated files. Defaults to `src/generated`.
 - `--check` — exits non-zero when generated files would change.
+- `--diff` — prints the generated file changes without writing them.
+
+When `toolcraft.yml` is present next to the input file, the generator validates it, prints
+diagnostics, and uses it to shape generated command names for mapped resources.
 
 ### CI drift check
 
@@ -36,6 +40,14 @@ toolcraft-openapi-generate --check
 - `bearerTokenAuth(opts)`
 - `requestJson(options)`
 - `HttpError`
+- `readToolcraftConfig(path)`
+- `validateToolcraftConfig(value)`
+- `mergeToolcraftConfig(base, override)`
+- `diagnose(config, document)`
+- `formatDiagnostic(diagnostic)`
+- `formatDiagnostics(diagnostics)`
+- `resolveOpenApiBaseUrl(options)`
+- `DIAGNOSTIC_CODES`
 - `TokenSource`
 - `CommandContributor`
 - `AuthProvider`
@@ -44,9 +56,64 @@ toolcraft-openapi-generate --check
 
 - `<envVar passed to bearerTokenAuth>` — bearer token override; wins over stored credentials.
 - `AUTH_BACKEND` — forwarded to `auth-store` to select `file` or `keychain` storage.
+- `TOOLCRAFT_OPENAPI_ENV` — selects a configured OpenAPI environment when using
+  `resolveOpenApiBaseUrl`.
 
 ## Configuration
 
+### `toolcraft.yml`
+
+`toolcraft.yml` lives next to `openapi.json`. Without it, OpenAPI-only generation remains the
+default.
+
+```yaml
+edition: 2026-05-16
+
+client_settings:
+  idempotency_header: Idempotency-Key
+
+pagination:
+  cursor:
+    request: { cursor: cursor, limit: limit }
+    response: { items: data, next_cursor: meta.next_cursor }
+
+resources:
+  messages:
+    methods:
+      list: get /messages { pagination: cursor }
+      create: post /messages { idempotent: true }
+
+unspecified_endpoints:
+  - get /internal/health
+```
+
+Supported keys:
+
+- `edition` — required when `toolcraft.yml` exists. Currently `2026-05-16`.
+- `environments` — named base URLs for `resolveOpenApiBaseUrl`.
+- `client_settings.idempotency_header` — header used for generated idempotency keys.
+- `client_settings.auth.*.env` — declarative auth environment metadata.
+- `pagination` — named request/response field mappings. Schemes are validated today; iterator
+  generation is not implemented yet.
+- `resources` — resource/method mapping. Mapped methods shape generated names and file paths.
+- `readme.examples` — examples emitted into generated command help and MCP descriptions.
+- `unspecified_endpoints` — endpoints intentionally omitted from `resources`.
+
+Mapped idempotent methods with `client_settings.idempotency_header` get an optional
+`idempotencyKey` param across CLI, MCP, and SDK surfaces. Mapped methods also get a CLI/SDK
+`rawResponse` param that returns `{ data, response }`; the CLI accepts both `--raw-response` and
+`--raw`.
+
+Diagnostics use stable codes:
+
+- `TOOLCRAFT_OPENAPI_001` — endpoint is not mapped or listed in `unspecified_endpoints`.
+- `TOOLCRAFT_OPENAPI_002` — duplicate configured method path.
+- `TOOLCRAFT_OPENAPI_003` — unknown pagination scheme.
+- `TOOLCRAFT_OPENAPI_004` — reserved for spec drift.
+- `TOOLCRAFT_OPENAPI_005` — reserved method name.
+- `TOOLCRAFT_OPENAPI_006` — missing or unsupported edition.
+- `TOOLCRAFT_OPENAPI_007` — invalid config shape.
+
 ### `bearerTokenAuth(opts)`
 
 - `serviceName: string` — auth-store service name and file-store key.

package/dist/bin/generate.d.ts

@@ -1,5 +1,7 @@
 #!/usr/bin/env node
 import { type OutputFormat } from "toolcraft-design";
+import { type Diagnostic } from "../diagnostics.js";
+import { type GeneratedFile } from "../generate.js";
 interface GenerateCliFileSystem {
     lstat(targetPath: string): Promise<{
         isDirectory(): boolean;
@@ -33,6 +35,7 @@ interface GenerateCliServices {
 }
 interface GenerateCliOptions {
     check: boolean;
+    diff: boolean;
     input: string;
     inspect: boolean;
     outputFormat: OutputFormat;
@@ -40,10 +43,16 @@ interface GenerateCliOptions {
 }
 interface SyncGeneratedClientResult {
     deletedFileCount: number;
+    deletedFiles: string[];
+    diagnostics: Diagnostic[];
     drifted: boolean;
     specSha: string;
+    updatedFiles: UpdatedGeneratedFile[];
     updatedFileCount: number;
 }
+interface UpdatedGeneratedFile extends GeneratedFile {
+    previousContents?: string;
+}
 export declare function runGenerateCli(argv?: string[], services?: GenerateCliServices): Promise<number>;
 export declare function syncGeneratedClient(options: GenerateCliOptions, services: Pick<GenerateCliServices, "cwd" | "fetch" | "fs">): Promise<SyncGeneratedClientResult>;
 export {};

package/dist/bin/generate.js

@@ -7,12 +7,16 @@ import { fileURLToPath } from "node:url";
 import { UserError } from "toolcraft";
 import { hasOwnErrorCode } from "../error-codes.js";
 import { withOutputFormat } from "toolcraft-design";
+import { readToolcraftConfig } from "../config.js";
+import { diagnose } from "../diagnose.js";
+import { formatDiagnostics } from "../diagnostics.js";
 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,
+    diff: false,
     input: "openapi.json",
     inspect: false,
     outputFormat: "terminal",
@@ -24,6 +28,7 @@ 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
+  --diff                 Print a diff of generated changes without writing files
   --inspect              Inspect route compatibility without writing files
   --output-format <fmt>  Inspection output: terminal, markdown, or json (default: terminal)
   -h, --help             Show this help text
@@ -47,11 +52,26 @@ export async function runGenerateCli(argv = process.argv, services = {
             return 0;
         }
         const result = await syncGeneratedClient(parsed, services);
+        if (result.diagnostics.length > 0) {
+            services.stderr.write(formatDiagnostics(result.diagnostics));
+        }
+        if (parsed.diff) {
+            if (!result.drifted) {
+                services.stdout.write(`OpenAPI output is up to date (${result.specSha}).\n`);
+                return 0;
+            }
+            services.stdout.write(renderGeneratedDiff(result, services.cwd));
+            return 1;
+        }
         if (parsed.check) {
             if (result.drifted) {
                 services.stderr.write(`OpenAPI output is out of date for ${parsed.outputDir}. Run the generator without --check to update it.\n`);
                 return 1;
             }
+            if (hasErrorDiagnostics(result.diagnostics)) {
+                services.stderr.write("OpenAPI diagnostics failed for toolcraft.yml.\n");
+                return 1;
+            }
             services.stdout.write(`OpenAPI output is up to date (${result.specSha}).\n`);
             return 0;
         }
@@ -81,7 +101,12 @@ export async function syncGeneratedClient(options, services) {
     const sourceText = await readOpenApiSourceText(options.input, services);
     const specSha = createSpecSha(sourceText);
     const document = parseOpenApiDocument(sourceText, options.input);
-    const generatedFiles = generate(document, { specSha });
+    const configResult = await readAdjacentToolcraftConfig(options.input, services);
+    const diagnostics = configResult.config === undefined
+        ? configResult.diagnostics
+        : [...configResult.diagnostics, ...diagnose(configResult.config, document)];
+    const effectiveConfig = hasErrorDiagnostics(diagnostics) ? undefined : configResult.config;
+    const generatedFiles = generate(document, { specSha, config: effectiveConfig });
     const outputDir = path.resolve(services.cwd, options.outputDir);
     const currentFiles = await readGeneratedFiles(services.fs, outputDir);
     const desiredFiles = new Map([
@@ -91,7 +116,7 @@ export async function syncGeneratedClient(options, services) {
     const updatedFiles = collectUpdatedFiles(currentFiles, desiredFiles);
     const deletedFiles = collectDeletedFiles(currentFiles, desiredFiles);
     const drifted = updatedFiles.length > 0 || deletedFiles.length > 0;
-    if (!options.check && drifted) {
+    if (!options.check && !options.diff && drifted) {
         try {
             await writeGeneratedFiles(services.fs, outputDir, updatedFiles);
             await deleteGeneratedFiles(services.fs, outputDir, deletedFiles);
@@ -102,12 +127,98 @@ export async function syncGeneratedClient(options, services) {
         }
     }
     return {
+        deletedFiles,
+        deletedFileCount: deletedFiles.length,
+        diagnostics,
         drifted,
         specSha,
-        updatedFileCount: updatedFiles.length,
-        deletedFileCount: deletedFiles.length
+        updatedFiles,
+        updatedFileCount: updatedFiles.length
     };
 }
+async function readAdjacentToolcraftConfig(input, services) {
+    const configPath = resolveAdjacentConfigPath(input, services.cwd);
+    if (configPath === undefined) {
+        return { diagnostics: [] };
+    }
+    try {
+        return await readToolcraftConfig(configPath, { fs: services.fs });
+    }
+    catch (error) {
+        if (isNotFoundError(error)) {
+            return { diagnostics: [] };
+        }
+        throw error;
+    }
+}
+function resolveAdjacentConfigPath(input, cwd) {
+    const inputUrl = tryParseUrl(input);
+    if (inputUrl !== null && (inputUrl.protocol === "http:" || inputUrl.protocol === "https:")) {
+        return undefined;
+    }
+    return path.resolve(cwd, path.dirname(input), "toolcraft.yml");
+}
+function hasErrorDiagnostics(diagnostics) {
+    return diagnostics.some((diagnostic) => diagnostic.severity === "error");
+}
+function renderGeneratedDiff(result, outputDir) {
+    const sections = [];
+    for (const file of result.updatedFiles) {
+        const relativePath = path.relative(outputDir, file.path);
+        sections.push(renderFileDiff(relativePath, file.previousContents ?? "", file.contents));
+    }
+    for (const filePath of result.deletedFiles) {
+        const relativePath = path.relative(outputDir, filePath);
+        sections.push([`--- ${relativePath}`, `+++ /dev/null`, "-<deleted>"].join("\n"));
+    }
+    return `${sections.join("\n")}\n`;
+}
+function renderFileDiff(relativePath, previousContents, nextContents) {
+    const previousLines = previousContents.split("\n");
+    const nextLines = nextContents.split("\n");
+    return [
+        `--- ${relativePath}`,
+        `+++ ${relativePath}`,
+        ...collectChangedDiffLines(previousLines, nextLines)
+    ].join("\n");
+}
+function collectChangedDiffLines(previousLines, nextLines) {
+    const lengths = Array.from({ length: previousLines.length + 1 }, () => Array(nextLines.length + 1).fill(0));
+    for (let leftIndex = previousLines.length - 1; leftIndex >= 0; leftIndex -= 1) {
+        for (let rightIndex = nextLines.length - 1; rightIndex >= 0; rightIndex -= 1) {
+            lengths[leftIndex][rightIndex] =
+                previousLines[leftIndex] === nextLines[rightIndex]
+                    ? lengths[leftIndex + 1][rightIndex + 1] + 1
+                    : Math.max(lengths[leftIndex + 1][rightIndex], lengths[leftIndex][rightIndex + 1]);
+        }
+    }
+    const lines = [];
+    let leftIndex = 0;
+    let rightIndex = 0;
+    while (leftIndex < previousLines.length && rightIndex < nextLines.length) {
+        if (previousLines[leftIndex] === nextLines[rightIndex]) {
+            leftIndex += 1;
+            rightIndex += 1;
+            continue;
+        }
+        if (lengths[leftIndex + 1][rightIndex] >= lengths[leftIndex][rightIndex + 1]) {
+            lines.push(`-${previousLines[leftIndex]}`);
+            leftIndex += 1;
+            continue;
+        }
+        lines.push(`+${nextLines[rightIndex]}`);
+        rightIndex += 1;
+    }
+    while (leftIndex < previousLines.length) {
+        lines.push(`-${previousLines[leftIndex]}`);
+        leftIndex += 1;
+    }
+    while (rightIndex < nextLines.length) {
+        lines.push(`+${nextLines[rightIndex]}`);
+        rightIndex += 1;
+    }
+    return lines;
+}
 function parseGenerateCliArgs(argv) {
     const options = { ...DEFAULT_OPTIONS };
     for (let index = 0; index < argv.length; index += 1) {
@@ -119,6 +230,10 @@ function parseGenerateCliArgs(argv) {
             options.check = true;
             continue;
         }
+        if (argument === "--diff") {
+            options.diff = true;
+            continue;
+        }
         if (argument === "--inspect") {
             options.inspect = true;
             continue;
@@ -228,10 +343,11 @@ async function readGeneratedFiles(fs, directoryPath) {
 function collectUpdatedFiles(currentFiles, desiredFiles) {
     const updatedFiles = [];
     for (const [filePath, contents] of desiredFiles) {
-        if (currentFiles.get(filePath) === contents) {
+        const previousContents = currentFiles.get(filePath);
+        if (previousContents === contents) {
             continue;
         }
-        updatedFiles.push({ path: filePath, contents });
+        updatedFiles.push({ path: filePath, contents, previousContents });
     }
     return updatedFiles;
 }

package/dist/config.d.ts

@@ -0,0 +1,53 @@
+import type { Diagnostic } from "./diagnostics.js";
+export declare const SUPPORTED_TOOLCRAFT_EDITION = "2026-05-16";
+export type ToolcraftHttpMethod = "get" | "post" | "put" | "patch" | "delete" | "head" | "options";
+export interface ToolcraftMethodConfig {
+    method: ToolcraftHttpMethod;
+    path: string;
+    pagination?: string;
+    idempotent?: boolean;
+}
+export interface ToolcraftResourceConfig {
+    methods?: Record<string, ToolcraftMethodConfig>;
+    subresources?: Record<string, ToolcraftResourceConfig>;
+}
+export interface ToolcraftConfig {
+    edition: string;
+    environments?: Record<string, string>;
+    client_settings?: {
+        idempotency_header?: string;
+        auth?: Record<string, {
+            env?: string;
+        }>;
+    };
+    pagination?: Record<string, {
+        request: Record<string, string>;
+        response: Record<string, string>;
+    }>;
+    retries?: {
+        max?: number;
+        backoff?: "exponential";
+        retry_on?: number[];
+    };
+    resources?: Record<string, ToolcraftResourceConfig>;
+    readme?: {
+        examples?: Record<string, Array<{
+            title: string;
+            params: Record<string, unknown>;
+        }>>;
+    };
+    unspecified_endpoints?: string[];
+}
+export interface ReadToolcraftConfigOptions {
+    cwd?: string;
+    fs?: {
+        readFile(filePath: string, encoding: BufferEncoding): Promise<string>;
+    };
+}
+export interface ToolcraftConfigResult {
+    config?: ToolcraftConfig;
+    diagnostics: Diagnostic[];
+}
+export declare function readToolcraftConfig(filePath: string, options?: ReadToolcraftConfigOptions): Promise<ToolcraftConfigResult>;
+export declare function validateToolcraftConfig(value: unknown): ToolcraftConfigResult;
+export declare function mergeToolcraftConfig(base: Partial<ToolcraftConfig>, override: Partial<ToolcraftConfig>): Partial<ToolcraftConfig>;

package/dist/config.js

@@ -0,0 +1,266 @@
+import path from "node:path";
+import { parse } from "yaml";
+import { S, validate } from "toolcraft-schema";
+import { DIAGNOSTIC_CODES, createDiagnostic } from "./diagnostics.js";
+export const SUPPORTED_TOOLCRAFT_EDITION = "2026-05-16";
+const configSchema = S.Object({
+    edition: S.Optional(S.String()),
+    environments: S.Optional(S.Record(S.String())),
+    client_settings: S.Optional(S.Object({
+        idempotency_header: S.Optional(S.String()),
+        auth: S.Optional(S.Record(S.Object({
+            env: S.Optional(S.String())
+        }, { additionalProperties: false })))
+    }, { additionalProperties: false })),
+    pagination: S.Optional(S.Record(S.Object({
+        request: S.Record(S.String()),
+        response: S.Record(S.String())
+    }, { additionalProperties: false }))),
+    retries: S.Optional(S.Object({
+        max: S.Optional(S.Number({ jsonType: "integer", minimum: 0 })),
+        backoff: S.Optional(S.Enum(["exponential"])),
+        retry_on: S.Optional(S.Array(S.Number({ jsonType: "integer", minimum: 100, maximum: 599 })))
+    }, { additionalProperties: false })),
+    resources: S.Optional(S.Json()),
+    readme: S.Optional(S.Json()),
+    unspecified_endpoints: S.Optional(S.Array(S.String()))
+}, { additionalProperties: false });
+export async function readToolcraftConfig(filePath, options = {}) {
+    const fs = options.fs ?? (await import("node:fs/promises"));
+    const resolvedPath = path.resolve(options.cwd ?? process.cwd(), filePath);
+    const source = await fs.readFile(resolvedPath, "utf8");
+    const parsed = parseToolcraftYaml(source);
+    return validateToolcraftConfig(parsed);
+}
+function parseToolcraftYaml(source) {
+    try {
+        return parse(source);
+    }
+    catch {
+        return parse(quoteMethodShorthandValues(source));
+    }
+}
+function quoteMethodShorthandValues(source) {
+    let methodsIndent;
+    return source
+        .split("\n")
+        .map((line) => {
+        const trimmed = line.trim();
+        if (trimmed.length === 0) {
+            return line;
+        }
+        const indent = countLeadingSpaces(line);
+        if (methodsIndent !== undefined && indent <= methodsIndent) {
+            methodsIndent = undefined;
+        }
+        if (trimmed === "methods:") {
+            methodsIndent = indent;
+            return line;
+        }
+        if (methodsIndent === undefined) {
+            return line;
+        }
+        const separatorIndex = line.indexOf(":");
+        if (separatorIndex < 0) {
+            return line;
+        }
+        const value = line.slice(separatorIndex + 1).trim();
+        if (!value.includes("{") ||
+            value.startsWith("{") ||
+            value.startsWith("\"") ||
+            value.startsWith("'")) {
+            return line;
+        }
+        return `${line.slice(0, separatorIndex + 1)} ${JSON.stringify(value)}`;
+    })
+        .join("\n");
+}
+function countLeadingSpaces(value) {
+    let count = 0;
+    for (const character of value) {
+        if (character !== " ") {
+            break;
+        }
+        count += 1;
+    }
+    return count;
+}
+export function validateToolcraftConfig(value) {
+    const result = validate(configSchema, value);
+    const diagnostics = [];
+    if (!isPlainObject(value) || typeof value.edition !== "string") {
+        diagnostics.push(createDiagnostic({
+            code: DIAGNOSTIC_CODES.invalidEdition,
+            severity: "error",
+            location: "edition",
+            message: `toolcraft.yml must set edition: ${SUPPORTED_TOOLCRAFT_EDITION}.`
+        }));
+    }
+    else if (value.edition !== SUPPORTED_TOOLCRAFT_EDITION) {
+        diagnostics.push(createDiagnostic({
+            code: DIAGNOSTIC_CODES.invalidEdition,
+            severity: "error",
+            location: "edition",
+            message: `Unsupported edition ${JSON.stringify(value.edition)}. Expected ${SUPPORTED_TOOLCRAFT_EDITION}.`
+        }));
+    }
+    if (!result.ok) {
+        diagnostics.push(...result.issues.map((issue) => createDiagnostic({
+            code: DIAGNOSTIC_CODES.invalidConfig,
+            severity: "error",
+            location: issue.path.join("."),
+            message: issue.message
+        })));
+    }
+    if (diagnostics.length > 0 || !result.ok) {
+        return { diagnostics };
+    }
+    return {
+        config: normalizeToolcraftConfig(result.value),
+        diagnostics
+    };
+}
+export function mergeToolcraftConfig(base, override) {
+    return deepMerge(base, override);
+}
+function normalizeToolcraftConfig(value) {
+    return {
+        ...value,
+        resources: normalizeResources(value.resources),
+        readme: normalizeReadme(value.readme)
+    };
+}
+function normalizeResources(value) {
+    if (!isPlainObject(value)) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(value).map(([name, resource]) => [name, normalizeResource(resource)]));
+}
+function normalizeResource(value) {
+    if (!isPlainObject(value)) {
+        return {};
+    }
+    return {
+        methods: normalizeMethods(value.methods),
+        subresources: normalizeResources(value.subresources)
+    };
+}
+function normalizeMethods(value) {
+    if (!isPlainObject(value)) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(value)
+        .map(([name, method]) => [name, normalizeMethod(method)])
+        .filter((entry) => entry[1] !== undefined));
+}
+function normalizeMethod(value) {
+    if (typeof value === "string") {
+        return parseMethodShorthand(value);
+    }
+    if (!isPlainObject(value)) {
+        return undefined;
+    }
+    const method = value.method;
+    const requestPath = value.path;
+    if (!isHttpMethod(method) || typeof requestPath !== "string") {
+        return undefined;
+    }
+    return {
+        method,
+        path: requestPath,
+        ...(typeof value.pagination === "string" ? { pagination: value.pagination } : {}),
+        ...(typeof value.idempotent === "boolean" ? { idempotent: value.idempotent } : {})
+    };
+}
+function parseMethodShorthand(value) {
+    const parts = value.trim().split(" ").filter((part) => part.length > 0);
+    const method = parts[0];
+    const requestPath = parts[1];
+    if (!isHttpMethod(method) || requestPath === undefined) {
+        return undefined;
+    }
+    const optionsText = parts.slice(2).join(" ");
+    const options = parseInlineOptions(optionsText);
+    return {
+        method,
+        path: requestPath,
+        ...(typeof options.pagination === "string" ? { pagination: options.pagination } : {}),
+        ...(typeof options.idempotent === "boolean" ? { idempotent: options.idempotent } : {})
+    };
+}
+function parseInlineOptions(value) {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) {
+        return {};
+    }
+    const body = trimmed.slice(1, -1).trim();
+    if (body.length === 0) {
+        return {};
+    }
+    const entries = [];
+    for (const pair of body.split(",")) {
+        const separatorIndex = pair.indexOf(":");
+        if (separatorIndex < 0) {
+            continue;
+        }
+        const key = pair.slice(0, separatorIndex).trim();
+        const rawValue = pair.slice(separatorIndex + 1).trim();
+        entries.push([key, parseInlineScalar(rawValue)]);
+    }
+    return Object.fromEntries(entries);
+}
+function parseInlineScalar(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    return value;
+}
+function normalizeReadme(value) {
+    if (!isPlainObject(value) || !isPlainObject(value.examples)) {
+        return undefined;
+    }
+    const examples = Object.fromEntries(Object.entries(value.examples)
+        .filter((entry) => Array.isArray(entry[1]))
+        .map(([key, entries]) => [
+        key,
+        entries
+            .filter(isPlainObject)
+            .map((entry) => ({
+            title: typeof entry.title === "string" ? entry.title : "Example",
+            params: isPlainObject(entry.params) ? entry.params : {}
+        }))
+    ]));
+    return { examples };
+}
+function isHttpMethod(value) {
+    return (value === "get" ||
+        value === "post" ||
+        value === "put" ||
+        value === "patch" ||
+        value === "delete" ||
+        value === "head" ||
+        value === "options");
+}
+function deepMerge(left, right) {
+    if (!isPlainObject(left) || !isPlainObject(right)) {
+        return cloneMergeValue(right);
+    }
+    const merged = { ...left };
+    for (const [key, value] of Object.entries(right)) {
+        merged[key] = key in merged ? deepMerge(merged[key], value) : cloneMergeValue(value);
+    }
+    return merged;
+}
+function cloneMergeValue(value) {
+    if (Array.isArray(value)) {
+        return [...value];
+    }
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, cloneMergeValue(entry)]));
+    }
+    return value;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/define-client.js

@@ -78,6 +78,10 @@ function cloneCommand(command, scopeOverride) {
     return defineCommand({
         name: command.name,
         description: command.description,
+        examples: command.examples.map((example) => ({
+            title: example.title,
+            params: { ...example.params }
+        })),
         aliases: [...command.aliases],
         positional: [...command.positional],
         params: command.params,

package/dist/diagnose.d.ts

@@ -0,0 +1,4 @@
+import { type Diagnostic } from "./diagnostics.js";
+import type { ToolcraftConfig } from "./config.js";
+import type { OpenApiDocument } from "./generate.js";
+export declare function diagnose(config: ToolcraftConfig, document: OpenApiDocument): Diagnostic[];