@farming-labs/docs 0.2.115 → 0.2.116

package/dist/openapi-sdk-DqRHPsCb.mjs

@@ -0,0 +1,415 @@
+import "./markdown-sections-BKy4labo.mjs";
+import "./agent-CEZCaYto.mjs";
+import "./standards-discovery-Bpz90VYq.mjs";
+import { n as buildNormalizedOpenApiModel } from "./openapi-operations-DFpaqOqA.mjs";
+import "./api-reference-0XdEWya8.mjs";
+import { n as loadOpenApiCliSource, t as displayOpenApiCliSource } from "./openapi-source-CiKbUK71.mjs";
+import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import pc from "picocolors";
+
+//#region src/cli/openapi-sdk.ts
+const GENERATED_SDK_MARKER = "// Generated by @farming-labs/docs openapi sdk. Do not edit.";
+const GENERATED_TYPE_NAMES = new Set([
+	"ApiClientOptions",
+	"ApiError",
+	"ApiResponse"
+]);
+const RESERVED_METHOD_NAMES = new Set(["constructor"]);
+function parseOpenApiSdkArgs(argv) {
+	const positionals = [];
+	let source;
+	let output;
+	let clientName;
+	let baseUrl;
+	let sourceBaseUrl;
+	let check = false;
+	let dryRun = false;
+	let force = false;
+	let help = false;
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index] ?? "";
+		if (argument === "--help" || argument === "-h") {
+			help = true;
+			continue;
+		}
+		if (argument === "--check") {
+			check = true;
+			continue;
+		}
+		if (argument === "--dry-run") {
+			dryRun = true;
+			continue;
+		}
+		if (argument === "--force") {
+			force = true;
+			continue;
+		}
+		if (!argument.startsWith("--")) {
+			positionals.push(argument);
+			continue;
+		}
+		const separator = argument.indexOf("=");
+		const flag = argument.slice(2, separator === -1 ? void 0 : separator);
+		const inlineValue = separator === -1 ? void 0 : argument.slice(separator + 1);
+		const value = inlineValue ?? argv[index + 1];
+		if (value === void 0 || value.startsWith("--")) throw new Error(`Missing value for --${flag}.`);
+		if (inlineValue === void 0) index += 1;
+		if (flag === "source") source = value;
+		else if (flag === "output" || flag === "out") output = value;
+		else if (flag === "client-name" || flag === "name") clientName = value;
+		else if (flag === "base-url") baseUrl = value;
+		else if (flag === "source-base-url") sourceBaseUrl = value;
+		else throw new Error(`Unknown OpenAPI SDK option: --${flag}.`);
+	}
+	for (const positional of positionals) if (!source) source = positional;
+	else throw new Error("Pass exactly one OpenAPI source.");
+	if (check && dryRun) throw new Error("Use either --check or --dry-run, not both.");
+	if (!help && !source) throw new Error("Pass an OpenAPI source.");
+	if (!help && !output) throw new Error("Pass --output <path> for the generated TypeScript SDK.");
+	return {
+		source,
+		output,
+		clientName,
+		baseUrl,
+		sourceBaseUrl,
+		check,
+		dryRun,
+		force,
+		help
+	};
+}
+async function runOpenApiSdk(options) {
+	if (!options.source || !options.output) throw new Error("OpenAPI SDK source and output are required.");
+	const rootDir = path.resolve(options.rootDir ?? process.cwd());
+	const outputPath = resolveOutputPath(rootDir, options.output);
+	const document = await loadOpenApiCliSource(options.source, {
+		rootDir,
+		baseUrl: options.sourceBaseUrl
+	});
+	const model = buildNormalizedOpenApiModel(document);
+	const clientName = normalizeTypeName(options.clientName ?? `${model.title} Client`);
+	const code = generateOpenApiTypeScriptSdk(document, {
+		clientName,
+		baseUrl: options.baseUrl,
+		source: displayOpenApiCliSource(options.source)
+	});
+	const current = existsSync(outputPath) ? readFileSync(outputPath, "utf-8") : void 0;
+	const changed = current !== code;
+	const report = {
+		format: "farming-labs-openapi-sdk.v1",
+		source: displayOpenApiCliSource(options.source),
+		output: normalizeRelativePath(path.relative(rootDir, outputPath)),
+		clientName,
+		operationCount: model.operationCount,
+		schemaCount: collectComponentSchemas(document).length,
+		changed,
+		wrote: false
+	};
+	if (options.dryRun) {
+		console.log(code);
+		return report;
+	}
+	if (options.check) {
+		if (changed) {
+			console.error(pc.red(`${report.output} is missing or stale. Run docs openapi sdk ${options.source} --output ${options.output}.`));
+			process.exitCode = 1;
+		} else console.log(pc.green(`${report.output} is up to date.`));
+		return report;
+	}
+	if (current !== void 0 && !current.startsWith(GENERATED_SDK_MARKER) && !options.force) throw new Error(`Refusing to replace non-generated file ${report.output}. Pass --force only after reviewing that file.`);
+	mkdirSync(path.dirname(outputPath), { recursive: true });
+	writeFileSync(outputPath, code, "utf-8");
+	report.wrote = true;
+	console.log(pc.green(`${changed ? "Generated" : "Refreshed"} ${report.output} with ${report.operationCount} operation${report.operationCount === 1 ? "" : "s"} and ${report.schemaCount} schema${report.schemaCount === 1 ? "" : "s"}.`));
+	return report;
+}
+function generateOpenApiTypeScriptSdk(document, options = {}) {
+	const model = buildNormalizedOpenApiModel(document);
+	const usedTypeNames = new Set(GENERATED_TYPE_NAMES);
+	const clientName = claimName(normalizeTypeName(options.clientName ?? `${model.title} Client`), usedTypeNames);
+	const components = collectComponentSchemas(document, usedTypeNames);
+	const referenceNames = new Map(components.map((component) => [component.reference, component.name]));
+	const operationNames = /* @__PURE__ */ new Map();
+	const usedMethodNames = /* @__PURE__ */ new Set();
+	for (const operation of model.operations) {
+		const baseName = normalizeTypeName(operation.operationId);
+		operationNames.set(operation, {
+			methodName: claimName(normalizeMethodName(operation.operationId), usedMethodNames),
+			inputName: claimName(`${baseName}Input`, usedTypeNames),
+			responseName: claimName(`${baseName}Response`, usedTypeNames)
+		});
+	}
+	const schemaContext = {
+		document,
+		referenceNames,
+		references: /* @__PURE__ */ new Set()
+	};
+	const defaultBaseUrl = resolveSdkBaseUrl(options.baseUrl, model.servers);
+	const lines = [
+		GENERATED_SDK_MARKER,
+		`// Source: ${sanitizeLineComment(options.source ?? "OpenAPI contract")}`,
+		"",
+		"export interface ApiClientOptions {",
+		"  baseUrl?: string;",
+		"  fetch?: typeof fetch;",
+		"  headers?: HeadersInit;",
+		"}",
+		"",
+		"export interface ApiResponse<TStatus extends number | string, TData> {",
+		"  status: TStatus;",
+		"  data: TData;",
+		"  headers: Headers;",
+		"}",
+		"",
+		"export class ApiError<TData = unknown> extends Error {",
+		"  readonly status: number;",
+		"  readonly data: TData;",
+		"  readonly headers: Headers;",
+		"",
+		"  constructor(status: number, data: TData, headers: Headers) {",
+		"    super(`API request failed with status ${status}.`);",
+		"    this.name = \"ApiError\";",
+		"    this.status = status;",
+		"    this.data = data;",
+		"    this.headers = headers;",
+		"  }",
+		"}"
+	];
+	for (const component of components) lines.push("", `export type ${component.name} = ${schemaToTypeScript(component.schema, schemaContext)};`);
+	for (const operation of model.operations) {
+		const names = operationNames.get(operation);
+		lines.push("", ...renderOperationTypes(operation, names, schemaContext));
+	}
+	lines.push("", `const DEFAULT_BASE_URL = ${JSON.stringify(defaultBaseUrl)};`, "", "function joinUrl(baseUrl: string, pathname: string): string {", "  return `${baseUrl.replace(/\\/+$/, \"\")}/${pathname.replace(/^\\/+/, \"\")}`;", "}", "", "function appendQueryParameter(searchParams: URLSearchParams, name: string, value: unknown): void {", "  if (value === undefined || value === null) return;", "  if (Array.isArray(value)) {", "    for (const entry of value) appendQueryParameter(searchParams, name, entry);", "    return;", "  }", "  searchParams.append(name, typeof value === \"object\" ? JSON.stringify(value) : String(value));", "}", "", "async function parseApiResponse(response: Response): Promise<unknown> {", "  if (response.status === 204 || response.status === 205) return undefined;", "  const contentLength = response.headers.get(\"content-length\");", "  if (contentLength === \"0\") return undefined;", "  const contentType = response.headers.get(\"content-type\")?.toLowerCase() ?? \"\";", "  if (contentType.includes(\"json\") || contentType.includes(\"+json\")) return response.json();", "  return response.text();", "}", "", `export class ${clientName} {`, "  private readonly baseUrl: string;", "  private readonly fetchImpl: typeof fetch;", "  private readonly defaultHeaders: Headers;", "", "  constructor(options: ApiClientOptions = {}) {", "    this.baseUrl = options.baseUrl ?? DEFAULT_BASE_URL;", "    if (!this.baseUrl) {", "      throw new Error(\"A baseUrl is required because the OpenAPI contract has no absolute server URL.\");", "    }", "    this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);", "    this.defaultHeaders = new Headers(options.headers);", "  }");
+	for (const operation of model.operations) lines.push("", ...renderOperationMethod(operation, operationNames.get(operation)));
+	lines.push("}", "");
+	return lines.join("\n");
+}
+function printOpenApiSdkHelp() {
+	console.log(`${pc.bold("docs openapi sdk")} — Generate a typed TypeScript fetch client.
+
+Usage:
+  docs openapi sdk <source> --output <path> [options]
+  docs api sdk --source <source> --out <path> [options]
+
+Sources:
+  Project-relative or absolute JSON/YAML files, file: URLs, and HTTP(S) URLs.
+
+Options:
+  ${pc.cyan("--source <source>")}          OpenAPI contract; positional form is also accepted
+  ${pc.cyan("--output, --out <path>")}    TypeScript output path inside the project root
+  ${pc.cyan("--client-name <name>")}      Generated client class name
+  ${pc.cyan("--base-url <url>")}          Override the generated client default base URL
+  ${pc.cyan("--source-base-url <url>")}   Resolve a request-relative remote source
+  ${pc.cyan("--check")}                   Fail when the generated file is missing or stale
+  ${pc.cyan("--dry-run")}                 Print generated TypeScript without writing
+  ${pc.cyan("--force")}                   Replace an existing non-generated output file
+  ${pc.cyan("--help")}                    Show this help
+`);
+}
+function renderOperationTypes(operation, names, context) {
+	const lines = [`export interface ${names.inputName} {`];
+	for (const location of [
+		"path",
+		"query",
+		"header",
+		"cookie"
+	]) {
+		const parameters = operation.parameters.filter((parameter) => parameter.in === location);
+		if (parameters.length === 0) continue;
+		const required = parameters.some((parameter) => parameter.required);
+		lines.push(`  ${location}${required ? "" : "?"}: ${renderParameterObject(parameters, context)};`);
+	}
+	if (operation.requestBody) {
+		const media = selectMediaType(operation.requestBody.content);
+		lines.push(`  body${operation.requestBody.required ? "" : "?"}: ${schemaToTypeScript(media?.schema, context)};`);
+	}
+	lines.push("  request?: Omit<RequestInit, \"method\" | \"body\" | \"headers\"> & { headers?: HeadersInit };", "}", "", `export type ${names.responseName} = ${renderResponseType(operation.responses, context)};`);
+	return lines;
+}
+function renderOperationMethod(operation, names) {
+	const inputRequired = operation.parameters.some((parameter) => parameter.required) || operation.requestBody?.required === true;
+	const lines = [`  async ${names.methodName}(input: ${names.inputName}${inputRequired ? "" : " = {}"}): Promise<${names.responseName}> {`, `    let operationPath = ${JSON.stringify(operation.path)};`];
+	for (const parameter of operation.parameters.filter((entry) => entry.in === "path")) lines.push(`    operationPath = operationPath.replaceAll(${JSON.stringify(`{${parameter.name}}`)}, encodeURIComponent(String(input.path[${JSON.stringify(parameter.name)}])));`);
+	lines.push("    const url = new URL(joinUrl(this.baseUrl, operationPath));");
+	for (const parameter of operation.parameters.filter((entry) => entry.in === "query")) lines.push(`    appendQueryParameter(url.searchParams, ${JSON.stringify(parameter.name)}, input.query?.[${JSON.stringify(parameter.name)}]);`);
+	lines.push("    const headers = new Headers(this.defaultHeaders);");
+	for (const parameter of operation.parameters.filter((entry) => entry.in === "header")) lines.push(`    if (input.header?.[${JSON.stringify(parameter.name)}] !== undefined) headers.set(${JSON.stringify(parameter.name)}, String(input.header[${JSON.stringify(parameter.name)}]));`);
+	const cookieParameters = operation.parameters.filter((entry) => entry.in === "cookie");
+	if (cookieParameters.length > 0) {
+		lines.push("    const cookieParts: string[] = [];");
+		for (const parameter of cookieParameters) lines.push(`    if (input.cookie?.[${JSON.stringify(parameter.name)}] !== undefined) cookieParts.push(${JSON.stringify(`${parameter.name}=`)} + encodeURIComponent(String(input.cookie[${JSON.stringify(parameter.name)}])));`);
+		lines.push("    if (cookieParts.length > 0) headers.set(\"cookie\", cookieParts.join(\"; \"));");
+	}
+	lines.push("    const requestHeaders = new Headers(input.request?.headers);", "    requestHeaders.forEach((value, name) => headers.set(name, value));", "    const requestOptions = { ...input.request };", "    delete requestOptions.headers;");
+	const requestMedia = operation.requestBody ? selectMediaType(operation.requestBody.content) : void 0;
+	if (operation.requestBody) if (requestMedia?.mediaType.includes("json") || requestMedia?.mediaType.includes("+json")) lines.push(`    headers.set("content-type", ${JSON.stringify(requestMedia.mediaType)});`, "    const body = input.body === undefined ? undefined : JSON.stringify(input.body);");
+	else {
+		if (requestMedia) lines.push(`    headers.set("content-type", ${JSON.stringify(requestMedia.mediaType)});`);
+		lines.push("    const body = input.body as BodyInit | null | undefined;");
+	}
+	else lines.push("    const body = undefined;");
+	lines.push("    const response = await this.fetchImpl(url, {", "      ...requestOptions,", `      method: ${JSON.stringify(operation.method)},`, "      headers,", "      body,", "    });", "    const data = await parseApiResponse(response);", "    if (!response.ok) throw new ApiError(response.status, data, response.headers);", `    return { status: response.status, data, headers: response.headers } as ${names.responseName};`, "  }");
+	return lines;
+}
+function renderParameterObject(parameters, context) {
+	return `{ ${parameters.map((parameter) => `${JSON.stringify(parameter.name)}${parameter.required ? "" : "?"}: ${schemaToTypeScript(parameter.schema, context)}`).join("; ")} }`;
+}
+function renderResponseType(responses, context) {
+	const successful = responses.filter((response) => /^2\d\d$/.test(response.status) || /^2XX$/i.test(response.status));
+	const candidates = successful.length > 0 ? successful : responses.filter((response) => response.status === "default");
+	if (candidates.length === 0) return "ApiResponse<number, unknown>";
+	return candidates.map((response) => {
+		const media = selectMediaType(response.content);
+		const data = media ? schemaToTypeScript(media.schema, context) : "undefined";
+		return `ApiResponse<${/^\d+$/.test(response.status) ? response.status : "number"}, ${data}>`;
+	}).join(" | ");
+}
+function selectMediaType(mediaTypes) {
+	return mediaTypes.find((entry) => entry.mediaType === "application/json") ?? mediaTypes.find((entry) => entry.mediaType.includes("+json")) ?? mediaTypes[0];
+}
+function collectComponentSchemas(document, usedNames = /* @__PURE__ */ new Set()) {
+	const componentSchemas = asRecord(asRecord(document.components)?.schemas) ?? {};
+	const definitions = asRecord(document.definitions) ?? {};
+	const schemas = [];
+	for (const [prefix, entries] of [["#/components/schemas", componentSchemas], ["#/definitions", definitions]]) for (const key of Object.keys(entries).sort()) schemas.push({
+		name: claimName(normalizeTypeName(key), usedNames),
+		reference: `${prefix}/${escapeJsonPointer(key)}`,
+		schema: entries[key]
+	});
+	return schemas;
+}
+function schemaToTypeScript(schema, context) {
+	if (schema === void 0 || schema === true) return "unknown";
+	if (schema === false) return "never";
+	const record = asRecord(schema);
+	if (!record) return "unknown";
+	const reference = typeof record.$ref === "string" ? record.$ref : void 0;
+	if (reference) {
+		const named = context.referenceNames.get(reference);
+		if (named) return named;
+		if (!context.references.has(reference) && reference.startsWith("#/")) {
+			const target = resolvePointer(context.document, reference.slice(1));
+			if (target !== void 0) return schemaToTypeScript(target, {
+				...context,
+				references: new Set(context.references).add(reference)
+			});
+		}
+		return "unknown";
+	}
+	if (Object.hasOwn(record, "const")) return literalType(record.const);
+	if (Array.isArray(record.enum) && record.enum.length > 0) return record.enum.map(literalType).join(" | ");
+	const allOf = schemaArray(record.allOf);
+	if (allOf.length > 0) return allOf.map((entry) => parenthesize(schemaToTypeScript(entry, context))).join(" & ");
+	const union = [...schemaArray(record.oneOf), ...schemaArray(record.anyOf)];
+	if (union.length > 0) return union.map((entry) => schemaToTypeScript(entry, context)).join(" | ");
+	const types = normalizeSchemaTypes(record.type);
+	let result;
+	if (types.length > 1) result = types.map((type) => schemaTypeToTypeScript(type, record, context)).join(" | ");
+	else result = schemaTypeToTypeScript(types[0], record, context);
+	if (record.nullable === true && !result.split(" | ").includes("null")) result += " | null";
+	return result;
+}
+function schemaTypeToTypeScript(type, schema, context) {
+	if (type === "string") return schema.format === "binary" ? "Blob" : "string";
+	if (type === "integer" || type === "number") return "number";
+	if (type === "boolean") return "boolean";
+	if (type === "null") return "null";
+	if (type === "array" || schema.items !== void 0) return `Array<${schemaToTypeScript(schema.items, context)}>`;
+	const properties = asRecord(schema.properties);
+	if (type === "object" || properties || schema.additionalProperties !== void 0) {
+		const required = new Set(stringArray(schema.required));
+		const fields = Object.keys(properties ?? {}).sort().map((name) => `${JSON.stringify(name)}${required.has(name) ? "" : "?"}: ${schemaToTypeScript(properties?.[name], context)}`);
+		const objectType = fields.length > 0 ? `{ ${fields.join("; ")} }` : "Record<string, never>";
+		const additional = schema.additionalProperties;
+		if (additional === false) return objectType;
+		const additionalType = additional === void 0 || additional === true ? "unknown" : schemaToTypeScript(additional, context);
+		if (fields.length === 0) return `Record<string, ${additionalType}>`;
+		return `${parenthesize(objectType)} & Record<string, ${additionalType}>`;
+	}
+	return "unknown";
+}
+function resolveSdkBaseUrl(override, servers) {
+	if (override) return override;
+	for (const server of servers) try {
+		const url = new URL(server);
+		if (url.protocol === "http:" || url.protocol === "https:") return url.href.replace(/\/$/, "");
+	} catch {}
+	return "";
+}
+function resolveOutputPath(rootDir, output) {
+	const outputPath = path.resolve(rootDir, output);
+	if (!isPathInside(rootDir, outputPath)) throw new Error("OpenAPI SDK output must be a file inside the project root.");
+	let existingAncestor = outputPath;
+	while (!existsSync(existingAncestor)) {
+		const parent = path.dirname(existingAncestor);
+		if (parent === existingAncestor) break;
+		existingAncestor = parent;
+	}
+	if (!isPathInside(realpathSync(rootDir), realpathSync(existingAncestor), true)) throw new Error("OpenAPI SDK output must not escape the project root through a symlink.");
+	return outputPath;
+}
+function isPathInside(rootDir, candidate, allowRoot = false) {
+	const relative = path.relative(rootDir, candidate);
+	return (allowRoot || relative.length > 0) && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+function normalizeTypeName(value) {
+	const normalized = (value.match(/[A-Za-z0-9]+/g) ?? []).map((part) => `${part[0]?.toUpperCase() ?? ""}${part.slice(1)}`).join("") || "ApiClient";
+	return /^\d/.test(normalized) ? `_${normalized}` : normalized;
+}
+function normalizeMethodName(value) {
+	const typeName = normalizeTypeName(value);
+	const methodName = `${typeName[0]?.toLowerCase() ?? "a"}${typeName.slice(1)}`;
+	return RESERVED_METHOD_NAMES.has(methodName) ? `${methodName}Operation` : methodName;
+}
+function claimName(base, used) {
+	let candidate = base;
+	let suffix = 2;
+	while (used.has(candidate)) {
+		candidate = `${base}${suffix}`;
+		suffix += 1;
+	}
+	used.add(candidate);
+	return candidate;
+}
+function normalizeSchemaTypes(value) {
+	if (typeof value === "string") return [value];
+	return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function schemaArray(value) {
+	return Array.isArray(value) ? value : [];
+}
+function stringArray(value) {
+	return Array.isArray(value) ? value.filter((entry) => typeof entry === "string") : [];
+}
+function literalType(value) {
+	return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null ? JSON.stringify(value) : "unknown";
+}
+function parenthesize(value) {
+	return value.includes(" | ") || value.includes(" & ") ? `(${value})` : value;
+}
+function asRecord(value) {
+	return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function resolvePointer(document, pointer) {
+	let current = document;
+	for (const token of pointer.slice(1).split("/")) {
+		const record = asRecord(current);
+		if (!record) return void 0;
+		current = record[token.replaceAll("~1", "/").replaceAll("~0", "~")];
+	}
+	return current;
+}
+function escapeJsonPointer(value) {
+	return value.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+function normalizeRelativePath(value) {
+	return value.replaceAll(path.sep, "/");
+}
+function sanitizeLineComment(value) {
+	return value.replace(/[\r\n]+/g, " ");
+}
+
+//#endregion
+export { parseOpenApiSdkArgs, printOpenApiSdkHelp, runOpenApiSdk };

package/dist/openapi-source-CiKbUK71.mjs

@@ -0,0 +1,37 @@
+import { d as loadApiReferenceOpenApiDocumentAsync } from "./api-reference-0XdEWya8.mjs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+//#region src/cli/openapi-source.ts
+async function loadOpenApiCliSource(source, options = {}) {
+	const rootDir = path.resolve(options.rootDir ?? process.cwd());
+	const localPath = path.isAbsolute(source) ? source : path.resolve(rootDir, source);
+	return loadApiReferenceOpenApiDocumentAsync({
+		entry: "docs",
+		apiReference: {
+			enabled: true,
+			specUrl: existsSync(localPath) && path.isAbsolute(source) ? pathToFileURL(localPath).href : source
+		}
+	}, {
+		framework: "next",
+		rootDir,
+		baseUrl: options.baseUrl
+	});
+}
+function displayOpenApiCliSource(source) {
+	if (!/^https?:/i.test(source)) return source;
+	try {
+		const url = new URL(source);
+		url.username = url.username ? "redacted" : "";
+		url.password = url.password ? "redacted" : "";
+		url.search = "";
+		url.hash = "";
+		return url.href;
+	} catch {
+		return "remote OpenAPI source";
+	}
+}
+
+//#endregion
+export { loadOpenApiCliSource as n, displayOpenApiCliSource as t };

package/dist/{package-version-Ci99L0yo.mjs → package-version-CTkii52k.mjs}

@@ -1,4 +1,4 @@
-import { i as detectPackageManagerFromProject, l as formatPackageManagerDetection, t as detectFramework, u as installCommand } from "./utils-Cc1SrVza.mjs";
+import { i as detectPackageManagerFromProject, l as formatPackageManagerDetection, t as detectFramework, u as installCommand } from "./utils-c9arebCi.mjs";
 import pc from "picocolors";
 import * as p from "@clack/prompts";
 

package/dist/{prompt-references-CV1zw72C.mjs → prompt-references-Cficetgk.mjs}

@@ -1,7 +1,7 @@
-import { Un as DEFAULT_MCP_WELL_KNOWN_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, f as DEFAULT_DOCS_CONFIG_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, jt as DEFAULT_SITEMAP_XML_ROUTE, kt as DEFAULT_SITEMAP_MD_ROUTE, m as DEFAULT_DOCS_DIAGNOSTICS_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE } from "./agent-5jyEosML.mjs";
+import { At as DEFAULT_SITEMAP_MD_ROUTE, Mt as DEFAULT_SITEMAP_XML_ROUTE, Wn as DEFAULT_MCP_WELL_KNOWN_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, f as DEFAULT_DOCS_CONFIG_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, i as DEFAULT_AGENT_FEEDBACK_ROUTE, m as DEFAULT_DOCS_DIAGNOSTICS_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE } from "./agent-CEZCaYto.mjs";
 import { C as DOCS_AGENT_MANIFEST_SCHEMA_MEDIA_TYPE, S as DOCS_AGENT_MANIFEST_FORMAT, T as DOCS_AGENT_MANIFEST_VERSION, f as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, n as API_CATALOG_MEDIA_TYPE, r as API_CATALOG_PROFILE_URI, t as AGENT_SKILLS_DISCOVERY_SCHEMA_URI, u as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, v as DEFAULT_API_CATALOG_ROUTE, w as DOCS_AGENT_MANIFEST_SCHEMA_URI } from "./standards-discovery-Bpz90VYq.mjs";
 import { isDocsAgentSkillName, validateDocsAgentSkillFrontmatter } from "./agent-skills-spec.mjs";
-import { n as DEFAULT_ROBOTS_TXT_ROUTE } from "./robots-Bne9ODlC.mjs";
+import { n as DEFAULT_ROBOTS_TXT_ROUTE } from "./robots-BPYWIGqD.mjs";
 import matter from "gray-matter";
 
 //#region src/define-docs.ts

package/dist/{retrieval-digest-CBhsp9LK.d.mts → retrieval-digest-PD4fFy7P.d.mts}

@@ -1,5 +1,5 @@
-import { $ as DocsAgentGoldenExpectedExample, Ft as DocsCodeBlocksPlannerProvider, J as DocsAgentFeedbackData, Rr as OpenDocsProvider, Rt as DocsCodeBlocksValidateConfig, Vr as OpenDocsTarget, W as DocsAgentEvaluationSurface, Z as DocsAgentGoldenCoverageApplicability, ai as ResolvedDocsRelatedLink, at as DocsAgentGoldenTask, nt as DocsAgentGoldenQueryVariant, ot as DocsAgentGoldenTaskExpectation, qn as DocsSearchConfig, st as DocsAgentGoldenTaskFilters, vr as DocsSitemapConfig, z as DocsAgentEvaluationAnswerProvider } from "./types-BkAk6B2d.mjs";
-import { R as DocsDiscoveryApiRouteOptions } from "./standards-discovery-CjyUCxdy.mjs";
+import { B as DocsAgentEvaluationAnswerProvider, G as DocsAgentEvaluationSurface, Hr as OpenDocsTarget, It as DocsCodeBlocksPlannerProvider, Jn as DocsSearchConfig, Q as DocsAgentGoldenCoverageApplicability, Y as DocsAgentFeedbackData, ct as DocsAgentGoldenTaskFilters, et as DocsAgentGoldenExpectedExample, oi as ResolvedDocsRelatedLink, ot as DocsAgentGoldenTask, rt as DocsAgentGoldenQueryVariant, st as DocsAgentGoldenTaskExpectation, yr as DocsSitemapConfig, zr as OpenDocsProvider, zt as DocsCodeBlocksValidateConfig } from "./types-Dkl2DUfp.mjs";
+import { R as DocsDiscoveryApiRouteOptions } from "./standards-discovery-C1RLKwV9.mjs";
 import { DocsMcpPage } from "./mcp.mjs";
 
 //#region src/agent-feedback-loop.d.ts

package/dist/{review-BdM27yh7.mjs → review-CcplK9Hj.mjs}

@@ -1,16 +1,16 @@
 import { _ as hasStructuredPageAgentContract, f as PAGE_AGENT_CONTRACT_FIELDS, g as getPageAgentFrontmatterIssues, v as normalizePageAgentFrontmatter } from "./markdown-sections-BKy4labo.mjs";
-import { A as buildDocsAgentDiscoverySpec, Cn as findDocsAudienceMdxIssues, Gn as getDocsMcpProtectedResourceMetadataRoutes, M as buildDocsConfigMap, T as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, mn as resolveAskAISearchRequestConfig } from "./agent-5jyEosML.mjs";
+import { A as buildDocsAgentDiscoverySpec, Kn as getDocsMcpProtectedResourceMetadataRoutes, M as buildDocsConfigMap, T as DOCS_CONFIG_MAP_TOP_LEVEL_KEYS, hn as resolveAskAISearchRequestConfig, wn as findDocsAudienceMdxIssues } from "./agent-CEZCaYto.mjs";
 import { I as resolveDocsDiscoveryApiRoute, _ as DEFAULT_API_CATALOG_FORMAT, d as DEFAULT_AGENT_SKILLS_ROUTE_PATTERN, h as DEFAULT_AGENT_SKILL_FORMAT, l as DEFAULT_AGENT_SKILLS_INDEX_FORMAT, u as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, v as DEFAULT_API_CATALOG_ROUTE } from "./standards-discovery-Bpz90VYq.mjs";
-import "./openapi-mcp-D8NVpTW1.mjs";
+import "./openapi-mcp-UF4Cx885.mjs";
 import { a as resolveDocsMetadataBaseUrl } from "./metadata-7htr-Xj_.mjs";
-import "./agent-skills-server-Ddbf15pY.mjs";
-import { c as resolveDocsReviewConfig, o as ensureDocsReviewWorkflow, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-CnQC3W2a.mjs";
+import "./agent-skills-server-Ddm90WL6.mjs";
+import { c as resolveDocsReviewConfig, o as ensureDocsReviewWorkflow, s as readDocsReviewConfigFromSource, t as runDocsGoldenTasks } from "./agent-evals-CmeTjDMC.mjs";
 import { createFilesystemDocsMcpSource, getDocsConfigSchema, resolveDocsMcpConfig } from "./mcp.mjs";
-import "./code-blocks-D90CCJFs.mjs";
-import { _ as resolveDocsContentDir, g as resolveDocsConfigPath, h as readTopLevelStringProperty, s as loadDocsConfigModuleResultWithProjectEnv } from "./config-DrZ3fXgf.mjs";
-import { t as detectFramework } from "./utils-Cc1SrVza.mjs";
-import { a as extractAgentBlocks, i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-D49vhw5u.mjs";
-import { t as analyzeConfiguredAgentSkillsProgressiveDisclosure } from "./agent-skills-progressive-disclosure-DL-q4JZo.mjs";
+import "./code-blocks-GYdvS3BH.mjs";
+import { _ as resolveDocsContentDir, g as resolveDocsConfigPath, h as readTopLevelStringProperty, s as loadDocsConfigModuleResultWithProjectEnv } from "./config-BnUOoj07.mjs";
+import { t as detectFramework } from "./utils-c9arebCi.mjs";
+import { a as extractAgentBlocks, i as createAgentUsefulnessPagesFromMcp, n as analyzeAgentSurfaceDrift, r as analyzeAgentUsefulness, t as resolveGoldenEvaluationInput } from "./golden-evaluations-B1QDOzYj.mjs";
+import { t as analyzeConfiguredAgentSkillsProgressiveDisclosure } from "./agent-skills-progressive-disclosure-BDSjGGFd.mjs";
 import matter from "gray-matter";
 import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
 import path from "node:path";

package/dist/{robots-Bne9ODlC.mjs → robots-BPYWIGqD.mjs}

@@ -1,4 +1,4 @@
-import { Lt as resolveDocsSitemapConfig, S as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, Un as DEFAULT_MCP_WELL_KNOWN_ROUTE, Vn as DEFAULT_MCP_PUBLIC_ROUTE, a as DEFAULT_AGENT_MD_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, tt as normalizeDocsPathSegment, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-5jyEosML.mjs";
+import { Hn as DEFAULT_MCP_PUBLIC_ROUTE, Rt as resolveDocsSitemapConfig, S as DEFAULT_SKILL_MD_WELL_KNOWN_ROUTE, Wn as DEFAULT_MCP_WELL_KNOWN_ROUTE, a as DEFAULT_AGENT_MD_ROUTE, c as DEFAULT_AGENT_SPEC_WELL_KNOWN_JSON_ROUTE, g as DEFAULT_LLMS_FULL_TXT_WELL_KNOWN_ROUTE, h as DEFAULT_LLMS_FULL_TXT_ROUTE, l as DEFAULT_AGENT_SPEC_WELL_KNOWN_ROUTE, n as DEFAULT_AGENTS_MD_WELL_KNOWN_ROUTE, o as DEFAULT_AGENT_MD_WELL_KNOWN_ROUTE, t as DEFAULT_AGENTS_MD_ROUTE, tt as normalizeDocsPathSegment, v as DEFAULT_LLMS_TXT_ROUTE, x as DEFAULT_SKILL_MD_ROUTE, y as DEFAULT_LLMS_TXT_WELL_KNOWN_ROUTE } from "./agent-CEZCaYto.mjs";
 import { a as DEFAULT_A2A_AGENT_CARD_ROUTE, b as DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, f as DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, u as DEFAULT_AGENT_SKILLS_INDEX_ROUTE, v as DEFAULT_API_CATALOG_ROUTE, x as DEFAULT_LEGACY_SKILLS_ROUTE_PREFIX } from "./standards-discovery-Bpz90VYq.mjs";
 
 //#region src/robots.ts

package/dist/{robots-D6VufwPn.mjs → robots-D4T3zZr_.mjs}

@@ -1,9 +1,9 @@
 import "./markdown-sections-BKy4labo.mjs";
-import "./agent-5jyEosML.mjs";
+import "./agent-CEZCaYto.mjs";
 import "./standards-discovery-Bpz90VYq.mjs";
-import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-Bne9ODlC.mjs";
-import { a as loadDocsConfigModule, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, m as readTopLevelBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-DrZ3fXgf.mjs";
-import { t as detectFramework } from "./utils-Cc1SrVza.mjs";
+import { c as renderDocsRobotsGeneratedBlock, f as upsertDocsRobotsGeneratedBlock, i as DOCS_ROBOTS_GENERATED_BLOCK_START, r as DOCS_ROBOTS_GENERATED_BLOCK_END, u as resolveDocsRobotsConfig } from "./robots-BPYWIGqD.mjs";
+import { a as loadDocsConfigModule, g as resolveDocsConfigPath, h as readTopLevelStringProperty, l as readBooleanProperty, m as readTopLevelBooleanProperty, p as readStringProperty, t as extractNestedObjectLiteral } from "./config-BnUOoj07.mjs";
+import { t as detectFramework } from "./utils-c9arebCi.mjs";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";

package/dist/{search-BCxmGlxh.mjs → search-BNmlDQJ2.mjs}

@@ -1,22 +1,28 @@
 import "./markdown-sections-BKy4labo.mjs";
-import { rn as createAlgoliaSearchAdapter, sn as createTypesenseSearchAdapter, tn as buildDocsSearchDocuments } from "./agent-5jyEosML.mjs";
+import { cn as createTypesenseSearchAdapter, in as createAlgoliaSearchAdapter, nn as buildDocsSearchDocuments } from "./agent-CEZCaYto.mjs";
 import "./standards-discovery-Bpz90VYq.mjs";
-import "./openapi-mcp-D8NVpTW1.mjs";
+import "./openapi-mcp-UF4Cx885.mjs";
 import { t as resolveDocsI18n } from "./i18n-B1gJ9EW0.mjs";
 import { a as resolveDocsMetadataBaseUrl } from "./metadata-7htr-Xj_.mjs";
-import "./sitemap-server-D3mFJkjE.mjs";
-import "./agent-skills-server-Ddbf15pY.mjs";
-import "./agent-evals-CnQC3W2a.mjs";
+import "./sitemap-server-C4bpuoLi.mjs";
+import { o as buildApiReferenceOperationPagesAsync } from "./api-reference-0XdEWya8.mjs";
+import "./agent-skills-server-Ddm90WL6.mjs";
+import "./agent-evals-CmeTjDMC.mjs";
 import { createFilesystemDocsMcpSource } from "./mcp.mjs";
-import "./authoring-mcp-BpwboE3k.mjs";
-import "./code-blocks-D90CCJFs.mjs";
+import "./authoring-mcp-C35lj3cI.mjs";
+import "./code-blocks-GYdvS3BH.mjs";
 import "./server.mjs";
-import { _ as resolveDocsContentDir, c as loadProjectEnv, g as resolveDocsConfigPath, h as readTopLevelStringProperty, s as loadDocsConfigModuleResultWithProjectEnv } from "./config-DrZ3fXgf.mjs";
+import { _ as resolveDocsContentDir, c as loadProjectEnv, g as resolveDocsConfigPath, h as readTopLevelStringProperty, s as loadDocsConfigModuleResultWithProjectEnv } from "./config-BnUOoj07.mjs";
+import { t as detectFramework } from "./utils-c9arebCi.mjs";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import pc from "picocolors";
 
 //#region src/cli/search.ts
+function resolveApiReferenceFramework(rootDir) {
+	const framework = detectFramework(rootDir);
+	return framework === "nextjs" ? "next" : framework ?? void 0;
+}
 function getEnvValue(loadedEnv, key) {
 	return process.env[key] ?? loadedEnv[key];
 }
@@ -101,6 +107,12 @@ async function syncSearch(options = {}) {
 		contentDir
 	}];
 	const contexts = [];
+	const apiReferenceFramework = resolveApiReferenceFramework(rootDir);
+	const apiOperationPages = configLoad.status === "evaluated" && apiReferenceFramework ? await buildApiReferenceOperationPagesAsync(configLoad.config, {
+		framework: apiReferenceFramework,
+		rootDir,
+		baseUrl: canonicalBaseUrl
+	}) : [];
 	for (const localized of localizedSources) {
 		const source = createFilesystemDocsMcpSource({
 			rootDir,
@@ -110,11 +122,15 @@ async function syncSearch(options = {}) {
 			baseUrl: canonicalBaseUrl
 		});
 		const scannedPages = await source.getPages();
-		if (scannedPages.length === 0) continue;
-		const pages = localized.locale ? scannedPages.map((page) => ({
+		const projectedApiPages = localized.locale ? apiOperationPages.map((page) => ({
+			...page,
+			locale: localized.locale
+		})) : apiOperationPages;
+		const pages = [...localized.locale ? scannedPages.map((page) => ({
 			...page,
 			locale: localized.locale
-		})) : scannedPages;
+		})) : scannedPages, ...projectedApiPages];
+		if (pages.length === 0) continue;
 		contexts.push({
 			pages,
 			documents: buildDocsSearchDocuments(pages),