@askrjs/cli 0.0.2 → 0.0.4

package/dist/generate.js

@@ -0,0 +1,461 @@
+import { mkdir, mkdtemp, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { load } from "js-yaml";
+//#region src/generate/generator.ts
+const OWNED = [
+	".askr-generated.json",
+	"schemas.ts",
+	"operations.ts",
+	"api.ts",
+	"index.ts"
+];
+const METHODS = [
+	"get",
+	"post",
+	"put",
+	"patch",
+	"delete",
+	"head",
+	"options"
+];
+const identifier = /^[A-Za-z_$][\w$]*$/;
+const pointer = (...parts) => `#/${parts.map((p) => String(p).replace(/~/g, "~0").replace(/\//g, "~1")).join("/")}`;
+var GenerationError = class extends Error {};
+const fail = (message, at, operationId) => {
+	throw new GenerationError(`${operationId ? `${operationId}: ` : ""}${message} at ${at}`);
+};
+const pascal = (name) => {
+	const result = name.replace(/(^|[^A-Za-z0-9]+)([A-Za-z0-9])/g, (_, _s, c) => c.toUpperCase()).replace(/[^A-Za-z0-9_$]/g, "");
+	return /^\d/.test(result) ? `_${result}` : result;
+};
+function schemaType(schema, at, direction = "response") {
+	if (schema.$ref) {
+		const name = decodeURIComponent(String(schema.$ref).split("/").at(-1));
+		return pascal(name);
+	}
+	if (Array.isArray(schema.type)) {
+		const includesNull = schema.type.includes("null");
+		const rendered = [...new Set(schema.type.filter((value) => value !== "null"))].map((variant) => schemaType({
+			...schema,
+			type: variant,
+			nullable: false
+		}, at, direction));
+		if (includesNull) rendered.push("null");
+		if (rendered.length === 0) fail("Schema type array must not be empty", at);
+		return [...new Set(rendered)].join(" | ");
+	}
+	if (schema.const !== void 0) return JSON.stringify(schema.const);
+	if (schema.enum) return schema.enum.map((value) => JSON.stringify(value)).join(" | ") || "never";
+	if (schema.oneOf || schema.anyOf) return (schema.oneOf ?? schema.anyOf).map((item, i) => schemaType(item, `${at}/${schema.oneOf ? "oneOf" : "anyOf"}/${i}`, direction)).join(" | ");
+	if (schema.allOf) return schema.allOf.map((item, i) => schemaType(item, `${at}/allOf/${i}`, direction)).join(" & ");
+	let type = "never";
+	if (schema.type === "string") type = "string";
+	else if (schema.type === "number" || schema.type === "integer") type = "number";
+	else if (schema.type === "boolean") type = "boolean";
+	else if (schema.type === "null") type = "null";
+	else if (schema.type === "array" || schema.items) type = `Array<${schemaType(schema.items ?? {}, `${at}/items`, direction)}>`;
+	else if (schema.type === "object" || schema.properties || schema.additionalProperties !== void 0) {
+		const required = new Set(schema.required ?? []);
+		const properties = Object.entries(schema.properties ?? {}).filter(([, value]) => !(direction === "request" ? value.readOnly : value.writeOnly)).map(([key, value]) => `  ${JSON.stringify(key)}${required.has(key) ? "" : "?"}: ${schemaType(value, `${at}/properties/${key}`, direction)};`);
+		if (schema.additionalProperties && typeof schema.additionalProperties === "object") properties.push(`  [key: string]: ${schemaType(schema.additionalProperties, `${at}/additionalProperties`, direction)};`);
+		type = `{\n${properties.join("\n")}\n}`;
+	} else if (!schema.type) fail("Unsupported schema without a type", at);
+	else fail(`Unsupported schema type ${schema.type}`, at);
+	return schema.nullable || Array.isArray(schema.type) && schema.type.includes("null") ? `${type} | null` : type;
+}
+function responseSchema(operation, at, success) {
+	return Object.entries(operation.responses ?? {}).filter(([status]) => status === "default" ? !success : success === /^2\d\d$/.test(status)).sort(([a], [b]) => a.localeCompare(b, void 0, { numeric: true }));
+}
+function pickContent(content, at, direction) {
+	const entries = Object.entries(content ?? {}).sort(([a], [b]) => a.localeCompare(b));
+	if (!entries.length) return {
+		type: "undefined",
+		codec: "empty()",
+		media: []
+	};
+	const types = entries.map(([mediaType, value]) => ({
+		mediaType,
+		type: schemaType(value.schema ?? {}, `${at}/content/${mediaType.replace(/~/g, "~0").replace(/\//g, "~1")}/schema`, direction)
+	}));
+	const union = [...new Set(types.map((v) => v.type))].join(" | ");
+	return {
+		type: union,
+		codec: types.length === 1 ? codecFor(types[0].mediaType, union) : `content({ ${types.map((v) => `${JSON.stringify(v.mediaType)}: ${codecFor(v.mediaType, v.type)}`).join(", ")} })`,
+		media: types.map((v) => v.mediaType)
+	};
+}
+function codecFor(mediaType, type) {
+	if (mediaType === "application/json" || mediaType.endsWith("+json")) return `json<${type}>()`;
+	if (mediaType.startsWith("text/")) return "text()";
+	if (mediaType === "application/x-www-form-urlencoded") return "urlEncoded()";
+	if (mediaType === "multipart/form-data") return "multipart()";
+	if (mediaType === "application/octet-stream") return "arrayBuffer()";
+	fail(`Unsupported media type ${mediaType}`, "#/content");
+}
+const pointerPart = (value) => decodeURIComponent(value).replace(/~1/g, "/").replace(/~0/g, "~");
+const pointerValue = (document, fragment) => {
+	let value = document;
+	for (const part of fragment.replace(/^#?\/?/, "").split("/").filter(Boolean)) {
+		if (!value || typeof value !== "object") throw new GenerationError(`Reference target is missing at #/${part}`);
+		value = value[pointerPart(part)];
+	}
+	if (value === void 0) throw new GenerationError(`Reference target is missing at ${fragment || "#"}`);
+	return value;
+};
+function parseOpenApiDocument(contents, source) {
+	let parsed;
+	try {
+		parsed = JSON.parse(contents);
+	} catch {
+		try {
+			parsed = load(contents);
+		} catch (error) {
+			throw new GenerationError(`Unable to parse OpenAPI document ${source}: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new GenerationError(`OpenAPI document must be an object: ${source}`);
+	return parsed;
+}
+async function readSource(uri) {
+	if (uri.startsWith("http://") || uri.startsWith("https://")) {
+		const response = await fetch(uri);
+		if (!response.ok) throw new GenerationError(`Unable to fetch OpenAPI reference ${uri}: ${response.status} ${response.statusText}`);
+		return {
+			uri,
+			document: parseOpenApiDocument(await response.text(), uri)
+		};
+	}
+	const path = fileURLToPath(uri);
+	return {
+		uri,
+		document: parseOpenApiDocument(await readFile(path, "utf8"), path)
+	};
+}
+var OpenApiBundler = class {
+	root;
+	rootUri;
+	sources = /* @__PURE__ */ new Map();
+	aliases = /* @__PURE__ */ new Map();
+	names = /* @__PURE__ */ new Map();
+	constructor(root, rootUri) {
+		this.root = root;
+		this.rootUri = rootUri;
+	}
+	async bundle() {
+		if (!this.root.components) this.root.components = {};
+		if (!this.root.components.schemas) this.root.components.schemas = {};
+		await this.expandObject(this.root, this.rootUri, this.root, /* @__PURE__ */ new Set());
+		return this.root;
+	}
+	async source(uri) {
+		let pending = this.sources.get(uri);
+		if (!pending) {
+			pending = readSource(uri);
+			this.sources.set(uri, pending);
+		}
+		return pending;
+	}
+	componentName(uri, fragment) {
+		const canonical = `${uri}#${fragment}`;
+		const existing = this.aliases.get(canonical);
+		if (existing) return existing;
+		const raw = fragment.split("/").filter(Boolean).at(-1) ?? basename(new URL(uri).pathname).replace(/\.[^.]+$/, "");
+		const base = pascal(pointerPart(raw)) || "ExternalSchema";
+		let name = base;
+		let suffix = 2;
+		while (this.names.has(name) && this.names.get(name) !== canonical) name = `${base}${suffix++}`;
+		this.aliases.set(canonical, name);
+		this.names.set(name, canonical);
+		return name;
+	}
+	async expandObject(value, uri, document, stack) {
+		for (const [key, child] of Object.entries(value)) value[key] = await this.expand(child, uri, document, stack);
+	}
+	async expand(value, uri, document, stack) {
+		if (Array.isArray(value)) return Promise.all(value.map((item) => this.expand(item, uri, document, stack)));
+		if (!value || typeof value !== "object") return value;
+		const object = value;
+		if (typeof object.$ref === "string") {
+			const resolved = await this.resolveRef(object.$ref, uri, document, stack);
+			const siblingEntries = Object.entries(object).filter(([key]) => key !== "$ref");
+			if (!siblingEntries.length) return resolved;
+			const result = resolved && typeof resolved === "object" && !Array.isArray(resolved) ? { ...resolved } : {};
+			for (const [key, child] of siblingEntries) result[key] = await this.expand(child, uri, document, stack);
+			return result;
+		}
+		const result = {};
+		for (const [key, child] of Object.entries(object)) result[key] = await this.expand(child, uri, document, stack);
+		return result;
+	}
+	async resolveRef(ref, baseUri, document, stack) {
+		const hash = ref.indexOf("#");
+		const targetUri = hash === -1 ? new URL(ref, baseUri).href : new URL(ref.slice(0, hash) || baseUri, baseUri).href;
+		const fragment = hash === -1 ? "" : ref.slice(hash + 1);
+		const canonical = `${targetUri}#${fragment}`;
+		const targetSource = targetUri === this.rootUri ? {
+			uri: targetUri,
+			document
+		} : await this.source(targetUri);
+		const target = pointerValue(targetSource.document, fragment);
+		if (targetUri === this.rootUri && fragment.startsWith("/components/schemas/")) return { $ref: `#${fragment}` };
+		if (fragment.startsWith("/components/schemas/")) {
+			const name = this.componentName(targetUri, fragment);
+			if (stack.has(canonical)) return { $ref: `#/components/schemas/${name}` };
+			if (!(name in this.root.components.schemas)) {
+				this.root.components.schemas[name] = {};
+				const next = new Set(stack).add(canonical);
+				this.root.components.schemas[name] = await this.expand(target, targetSource.uri, targetSource.document, next);
+			}
+			return { $ref: `#/components/schemas/${name}` };
+		}
+		if (stack.has(canonical)) throw new GenerationError(`Circular non-schema reference at ${ref}`);
+		return this.expand(target, targetSource.uri, targetSource.document, new Set(stack).add(canonical));
+	}
+};
+async function loadOpenApi(input) {
+	const source = await readSource(/^https?:\/\//.test(input) ? input : pathToFileURL(resolve(input)).href);
+	return new OpenApiBundler(source.document, source.uri).bundle();
+}
+function generateFiles(document) {
+	const version = String(document.openapi ?? "");
+	if (!/^3\.(0|1)\.\d+$/.test(version)) fail(`Unsupported OpenAPI version ${version || "missing"}`, "#/openapi");
+	if (document.webhooks) fail("Webhooks are unsupported", "#/webhooks");
+	const schemas = document.components?.schemas ?? {};
+	const names = /* @__PURE__ */ new Map();
+	for (const name of Object.keys(schemas).sort()) {
+		const safe = pascal(name);
+		if (!safe || names.has(safe)) fail(`Component name collision for ${name}`, pointer("components", "schemas", name));
+		names.set(safe, name);
+	}
+	const schemaLines = [...names].map(([safe, original]) => `export type ${safe} = ${schemaType(schemas[original], pointer("components", "schemas", original))};`);
+	const operationTypes = [];
+	const descriptors = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const path of Object.keys(document.paths ?? {}).sort()) for (const method of METHODS) {
+		const operation = document.paths[path]?.[method];
+		if (!operation) continue;
+		const at = pointer("paths", path, method);
+		const id = operation.operationId;
+		if (!id || !identifier.test(id)) fail("A unique JavaScript-identifier operationId is required", `${at}/operationId`, id);
+		if (seen.has(id)) fail("Duplicate operationId", `${at}/operationId`, id);
+		seen.add(id);
+		if (operation.callbacks) fail("Callbacks are unsupported", `${at}/callbacks`, id);
+		const parametersByIdentity = /* @__PURE__ */ new Map();
+		for (const parameter of [...document.paths[path].parameters ?? [], ...operation.parameters ?? []]) {
+			if (parameter.$ref) fail("Parameter references must be bundled", `${at}/parameters`, id);
+			if (typeof parameter.name !== "string" || typeof parameter.in !== "string") fail("Parameters require string name and in fields", `${at}/parameters`, id);
+			parametersByIdentity.set(`${parameter.in}\0${parameter.name}`, parameter);
+		}
+		const parameters = [...parametersByIdentity.values()];
+		const byLocation = {
+			path: [],
+			query: [],
+			header: []
+		};
+		for (const parameter of parameters) {
+			if (parameter.in === "cookie") fail("Cookie parameters are unsupported", `${at}/parameters`, id);
+			if (!byLocation[parameter.in]) fail(`Unsupported parameter location ${parameter.in}`, `${at}/parameters`, id);
+			byLocation[parameter.in].push(parameter);
+		}
+		const templateParameters = new Set([...path.matchAll(/\{([^{}]+)\}/g)].map((match) => match[1]));
+		const declaredPathParameters = new Set(byLocation.path.map((parameter) => parameter.name));
+		for (const name of templateParameters) {
+			const parameter = byLocation.path.find((candidate) => candidate.name === name);
+			if (!parameter) fail(`Path template parameter ${name} is not declared`, `${at}/parameters`, id);
+			if (!parameter || parameter.required !== true) fail(`Path parameter ${name} must be required`, `${at}/parameters`, id);
+		}
+		for (const name of declaredPathParameters) if (!templateParameters.has(name)) fail(`Path parameter ${name} is not present in the path template`, `${at}/parameters`, id);
+		const prefix = pascal(id);
+		const renderParameters = (location) => {
+			const list = byLocation[location].sort((a, b) => a.name.localeCompare(b.name));
+			if (!list.length) return void 0;
+			const name = `${prefix}${pascal(location)}`;
+			operationTypes.push(`export type ${name} = {\n${list.map((p) => `  ${JSON.stringify(p.name)}${p.required || location === "path" ? "" : "?"}: ${schemaType(p.schema ?? {}, `${at}/parameters`, "request")};`).join("\n")}\n};`);
+			const defaultStyle = location === "query" ? "form" : "simple";
+			return {
+				name,
+				spec: `{ ${list.map((p) => {
+					const style = p.style ?? defaultStyle;
+					const explode = p.explode ?? style === "form";
+					return `${JSON.stringify(p.name)}: { style: ${JSON.stringify(style)}, explode: ${explode} }`;
+				}).join(", ")} }`
+			};
+		};
+		const params = renderParameters("path"), query = renderParameters("query"), headers = renderParameters("header");
+		const body = operation.requestBody ? pickContent(operation.requestBody.content, `${at}/requestBody`, "request") : void 0;
+		if (body) operationTypes.push(`export type ${prefix}Body = ${body.type};`);
+		const successes = responseSchema(operation, at, true);
+		if (!successes.length) fail("At least one 2xx response is required", `${at}/responses`, id);
+		const errors = responseSchema(operation, at, false);
+		const chain = [`${method === "delete" ? "del" : method}(${JSON.stringify(path)})`];
+		if (params) chain.push(`params<${params.name}>(${params.spec})`);
+		if (query) chain.push(`query<${query.name}>(${query.spec})`);
+		if (headers) chain.push(`headers<${headers.name}>(${headers.spec})`);
+		if (body) chain.push(`body(${body.codec})`);
+		for (const [status, response] of successes) {
+			if (response.links) fail("Response links are unsupported", `${at}/responses/${status}/links`, id);
+			const value = pickContent(response.content, `${at}/responses/${status}`, "response");
+			const typeName = `${prefix}Response${status}`;
+			operationTypes.push(`export type ${typeName} = ${value.type};`);
+			chain.push(`returns(${status === "200" ? "" : `${status}, `}${value.codec})`);
+		}
+		if (errors.length) {
+			const rendered = errors.map(([status, response]) => {
+				if (response.links) fail("Response links are unsupported", `${at}/responses/${status}/links`, id);
+				const value = pickContent(response.content, `${at}/responses/${status}`, "response");
+				const typeName = `${prefix}Error${pascal(status)}`;
+				operationTypes.push(`export type ${typeName} = ${value.type};`);
+				return `${JSON.stringify(status)}: ${value.codec}`;
+			});
+			chain.push(`errors({ ${rendered.join(", ")} })`);
+		}
+		if (operation.security ?? document.security) chain.push(`security(${JSON.stringify(operation.security ?? document.security)})`);
+		descriptors.push(`  ${id}: ${chain.join("\n    .")},`);
+	}
+	const imports = [...new Set(descriptors.join(" ").match(/\b(get|post|put|patch|del|head|options|json|text|urlEncoded|multipart|arrayBuffer|empty|content)\b/g) ?? [])].sort();
+	const files = {
+		"schemas.ts": `${schemaLines.join("\n\n")}\n`,
+		"operations.ts": `${names.size ? `import type { ${[...names.keys()].join(", ")} } from "./schemas";\n\n` : ""}${operationTypes.join("\n\n")}\n`,
+		"api.ts": `import { ${[
+			"defineApi",
+			"createClient",
+			...imports
+		].join(", ")} } from "@askrjs/fetch";\nimport type { ClientOptions } from "@askrjs/fetch";\nimport type { ${operationTypes.map((line) => line.match(/^export type (\w+)/)?.[1]).filter(Boolean).join(", ")} } from "./operations";\n\nexport const api = defineApi({\n${descriptors.join("\n")}\n}, ${JSON.stringify({
+			servers: (document.servers ?? []).map((s) => s.url),
+			securitySchemes: document.components?.securitySchemes ?? {}
+		}, null, 2)});\n\nexport const createApiClient = (options?: ClientOptions) => createClient(api, options);\n`,
+		"index.ts": `export * from "./schemas";\nexport * from "./operations";\nexport { api, createApiClient } from "./api";\n`,
+		".askr-generated.json": ""
+	};
+	files[".askr-generated.json"] = `${JSON.stringify({
+		version: 1,
+		files: [...OWNED]
+	}, null, 2)}\n`;
+	return files;
+}
+async function existingFiles(directory) {
+	try {
+		return (await readdir(directory)).sort();
+	} catch {
+		return [];
+	}
+}
+async function writeGenerated(directory, files, check) {
+	const output = resolve(directory);
+	const outputStat = await stat(output).catch(() => null);
+	if (outputStat && !outputStat.isDirectory()) throw new GenerationError(`Generated output must be a directory: ${output}`);
+	const entries = await existingFiles(output);
+	if (check) {
+		if (!entries.length) throw new GenerationError(`Generated directory is missing: ${output}`);
+		const expected = Object.keys(files).sort();
+		if (JSON.stringify(entries) !== JSON.stringify(expected)) throw new GenerationError(`Generated file ownership differs in ${output}`);
+		for (const name of expected) if (await readFile(join(output, name), "utf8") !== files[name]) throw new GenerationError(`Generated file is stale: ${name}`);
+		return;
+	}
+	if (entries.length && !entries.includes(".askr-generated.json")) throw new GenerationError(`Refusing to overwrite non-generated directory: ${output}`);
+	const stage = await mkdtemp(join(dirname(output), `.${basename(output)}-stage-`));
+	for (const [name, content] of Object.entries(files)) await writeFile(join(stage, name), content);
+	const backup = `${output}.backup-${process.pid}`;
+	let moved = false;
+	try {
+		if (entries.length) {
+			await rename(output, backup);
+			moved = true;
+		}
+		await rename(stage, output);
+		if (moved) await rm(backup, {
+			recursive: true,
+			force: true
+		});
+	} catch (error) {
+		await rm(output, {
+			recursive: true,
+			force: true
+		});
+		if (moved) await rename(backup, output);
+		throw error;
+	} finally {
+		await rm(stage, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+async function generate(input, output, check = false) {
+	if (!/^https?:\/\//.test(input)) {
+		const resolvedInput = resolve(input);
+		const inputWithinOutput = relative(resolve(output), resolvedInput);
+		if (!inputWithinOutput.startsWith("..") && !isAbsolute(inputWithinOutput)) throw new GenerationError("Generated output must not contain its OpenAPI input document");
+	}
+	const files = generateFiles(await loadOpenApi(input));
+	await mkdir(dirname(resolve(output)), { recursive: true });
+	await writeGenerated(output, files, check);
+}
+//#endregion
+//#region src/bin/generate.ts
+async function runGenerateCli(args, io = console) {
+	const wantsJson = args.includes("--json");
+	let output;
+	let check = false;
+	let json = false;
+	let help = false;
+	const inputs = [];
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i];
+		if (arg === "--check") check = true;
+		else if (arg === "--json") json = true;
+		else if (arg === "--help" || arg === "-h") help = true;
+		else if (arg === "-o" || arg === "--output") {
+			const value = args[i + 1];
+			if (!value || value.startsWith("-")) {
+				const message = `${arg} requires a path`;
+				io.error(wantsJson ? JSON.stringify({
+					status: "error",
+					error: message
+				}) : message);
+				return 1;
+			}
+			output = value;
+			i += 1;
+		} else if (arg.startsWith("--output=")) output = arg.slice(9);
+		else if (arg.startsWith("-")) {
+			const message = `Unknown option: ${arg}`;
+			io.error(wantsJson ? JSON.stringify({
+				status: "error",
+				error: message
+			}) : message);
+			return 1;
+		} else inputs.push(arg);
+	}
+	const usage = "Usage: askr generate <input> -o <output-directory> [--check] [--json]";
+	if (help) {
+		io.log(usage);
+		return 0;
+	}
+	if (inputs.length !== 1 || !output) {
+		io.error(json ? JSON.stringify({
+			status: "error",
+			error: usage
+		}) : usage);
+		return 1;
+	}
+	try {
+		await generate(inputs[0], output, check);
+		io.log(json ? JSON.stringify({
+			status: "ok",
+			action: check ? "checked" : "generated",
+			output
+		}) : check ? "Generated client is current." : `Generated client in ${output}.`);
+		return 0;
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		io.error(json ? JSON.stringify({
+			status: "error",
+			error: message
+		}) : message);
+		return 1;
+	}
+}
+//#endregion
+export { runGenerateCli };

package/dist/is-direct-execution-Cdlr-ZUl.js

@@ -16,5 +16,3 @@ function isDirectExecution(moduleUrl, argvPath = process.argv[1]) {
 }
 //#endregion
 export { isDirectExecution as t };
-
-//# sourceMappingURL=is-direct-execution-Cdlr-ZUl.js.map

package/dist/openapi.d.ts

@@ -0,0 +1,25 @@
+//#region src/bin/openapi.d.ts
+type CliIo = Pick<Console, "error" | "log">;
+interface ParsedArgs {
+  entry: string;
+  output: string;
+  check: boolean;
+  help: boolean;
+  json: boolean;
+}
+interface OpenApiDeps {
+  cwd(): string;
+  importModule(filePath: string): Promise<unknown>;
+  readFile(filePath: string): Promise<string>;
+  mkdir(directory: string): Promise<void>;
+  writeFile(filePath: string, contents: string): Promise<void>;
+  rename(from: string, to: string): Promise<void>;
+  rm(filePath: string): Promise<void>;
+  temporarySuffix(): string;
+}
+declare function parseOpenApiArgs(args: readonly string[]): ParsedArgs;
+declare function serializeOpenApi(document: unknown): string;
+declare function validateOpenApiDocument(document: unknown): asserts document is Record<string, unknown>;
+declare function runOpenApiCli(args?: string[], io?: CliIo, overrides?: Partial<OpenApiDeps>): Promise<number>;
+//#endregion
+export { parseOpenApiArgs, runOpenApiCli, serializeOpenApi, validateOpenApiDocument };

package/dist/openapi.js

@@ -3,8 +3,8 @@ import { t as isDirectExecution } from "./is-direct-execution-Cdlr-ZUl.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { dump } from "js-yaml";
 import { tsImport } from "tsx/esm/api";
-import { stringify } from "yaml";
 //#region src/bin/openapi.ts
 const helpText = `askr openapi - Generate an OpenAPI YAML artifact
 
@@ -15,6 +15,7 @@ Options:
   --entry <path>   TypeScript API module (default: ./src/api.ts)
   --output <path>  YAML artifact (default: ./openapi.yml)
   --check          Fail when the artifact is missing or byte-stale; never write
+  --json           Print machine-readable command results
   --help, -h       Show help
 `;
 const defaultDeps = {
@@ -32,17 +33,19 @@ function parseOpenApiArgs(args) {
 		entry: "./src/api.ts",
 		output: "./openapi.yml",
 		check: false,
-		help: false
+		help: false,
+		json: false
 	};
 	for (let index = 0; index < args.length; index += 1) {
 		const value = args[index];
 		if (value === "--entry" || value === "--output") {
 			const next = args[index + 1];
-			if (!next) throw new Error(`${value} requires a path`);
+			if (!next || next.startsWith("-")) throw new Error(`${value} requires a path`);
 			if (value === "--entry") parsed.entry = next;
 			else parsed.output = next;
 			index += 1;
 		} else if (value === "--check") parsed.check = true;
+		else if (value === "--json") parsed.json = true;
 		else if (value === "--help" || value === "-h") parsed.help = true;
 		else throw new Error(`Unknown option: ${value}`);
 	}
@@ -56,14 +59,24 @@ function exporterFrom(moduleValue) {
 	return exported;
 }
 function serializeOpenApi(document) {
-	return `${stringify(document, {
-		aliasDuplicateObjects: false,
-		lineWidth: 0
+	return `${dump(document, {
+		lineWidth: -1,
+		noCompatMode: true,
+		noRefs: true
 	}).replace(/\n+$/, "")}\n`;
 }
-async function generate(entry, deps) {
-	const document = exporterFrom(await deps.importModule(entry)).toOpenApiDocument();
+function validateOpenApiDocument(document) {
 	if (!document || typeof document !== "object" || Array.isArray(document)) throw new Error("toOpenApiDocument() must return an OpenAPI document object");
+	const candidate = document;
+	if (typeof candidate.openapi !== "string" || !/^3\.(?:0|1)\.\d+(?:[-+].+)?$/.test(candidate.openapi)) throw new Error("OpenAPI document must declare a supported openapi 3.0.x or 3.1.x version");
+	if (!candidate.info || typeof candidate.info !== "object" || Array.isArray(candidate.info)) throw new Error("OpenAPI document must contain an info object");
+	const info = candidate.info;
+	if (typeof info.title !== "string" || !info.title.trim() || typeof info.version !== "string" || !info.version.trim()) throw new Error("OpenAPI info must contain non-empty title and version strings");
+	if (!candidate.paths || typeof candidate.paths !== "object" || Array.isArray(candidate.paths)) throw new Error("OpenAPI document must contain a paths object");
+}
+async function generate(entry, deps) {
+	const document = await exporterFrom(await deps.importModule(entry)).toOpenApiDocument();
+	validateOpenApiDocument(document);
 	return serializeOpenApi(document);
 }
 async function atomicWrite(output, contents, deps) {
@@ -82,6 +95,7 @@ async function runOpenApiCli(args = process.argv.slice(2), io = console, overrid
 		...defaultDeps,
 		...overrides
 	};
+	const wantsJson = args.includes("--json");
 	try {
 		const parsed = parseOpenApiArgs(args);
 		if (parsed.help) {
@@ -90,6 +104,7 @@ async function runOpenApiCli(args = process.argv.slice(2), io = console, overrid
 		}
 		const entry = path.resolve(deps.cwd(), parsed.entry);
 		const output = path.resolve(deps.cwd(), parsed.output);
+		if (entry === output) throw new Error("OpenAPI output must not overwrite its source entry");
 		const expected = await generate(entry, deps);
 		if (parsed.check) {
 			let actual;
@@ -97,23 +112,43 @@ async function runOpenApiCli(args = process.argv.slice(2), io = console, overrid
 				actual = await deps.readFile(output);
 			} catch (error) {
 				if (error.code === "ENOENT") {
-					io.error(`OpenAPI artifact is missing: ${output}`);
+					io.error(parsed.json ? JSON.stringify({
+						status: "error",
+						reason: "missing",
+						output
+					}) : `OpenAPI artifact is missing: ${output}`);
 					return 1;
 				}
 				throw error;
 			}
 			if (actual !== expected) {
-				io.error(`OpenAPI artifact is stale: ${output}`);
+				io.error(parsed.json ? JSON.stringify({
+					status: "error",
+					reason: "stale",
+					output
+				}) : `OpenAPI artifact is stale: ${output}`);
 				return 1;
 			}
-			io.log(`OpenAPI artifact is current: ${output}`);
+			io.log(parsed.json ? JSON.stringify({
+				status: "ok",
+				action: "checked",
+				output
+			}) : `OpenAPI artifact is current: ${output}`);
 			return 0;
 		}
 		await atomicWrite(output, expected, deps);
-		io.log(`Generated OpenAPI artifact: ${output}`);
+		io.log(parsed.json ? JSON.stringify({
+			status: "ok",
+			action: "generated",
+			output
+		}) : `Generated OpenAPI artifact: ${output}`);
 		return 0;
 	} catch (error) {
-		io.error(error instanceof Error ? error.message : String(error));
+		const message = error instanceof Error ? error.message : String(error);
+		io.error(wantsJson ? JSON.stringify({
+			status: "error",
+			error: message
+		}) : message);
 		return 1;
 	}
 }
@@ -122,6 +157,4 @@ async function main() {
 }
 if (isDirectExecution(import.meta.url)) main();
 //#endregion
-export { parseOpenApiArgs, runOpenApiCli, serializeOpenApi };
-
-//# sourceMappingURL=openapi.js.map
+export { parseOpenApiArgs, runOpenApiCli, serializeOpenApi, validateOpenApiDocument };