@octalmesh/seagull 0.0.1

package/dist/serve-docs-BZaITOD0.mjs

@@ -0,0 +1,1567 @@
+#!/usr/bin/env node
+
+import { createRequire } from "node:module";
+import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
+import path, { dirname, extname, join, normalize } from "node:path";
+import { parse, stringify } from "yaml";
+import { z } from "zod";
+import { copyFile, cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { createServer } from "node:http";
+//#region src/config/schema.ts
+const varsTreeSchema = z.lazy(() => z.record(z.string(), z.union([
+	z.string(),
+	z.number(),
+	z.boolean(),
+	varsTreeSchema
+])));
+const githubSchema = z.object({
+	owner: z.string().min(1),
+	repo: z.string().min(1)
+});
+const pathsSchema = z.object({
+	dist: z.string().min(1).default("dist"),
+	specs: z.string().min(1).optional(),
+	docs: z.string().min(1).optional(),
+	sdk: z.string().min(1).optional()
+});
+const docsSchema = z.object({
+	server: z.object({
+		host: z.string().min(1),
+		port: z.number().int().positive()
+	}),
+	metadata: z.object({
+		title: z.string().min(1),
+		description: z.string().min(1),
+		favicon: z.string().min(1),
+		baseServerUrl: z.string().min(1)
+	})
+});
+const sdkToolSchema = z.enum(["openapi-generator", "openapi-typescript"]);
+const sdkLangSchema = z.enum([
+	"typescript",
+	"go",
+	"java"
+]);
+const sdkKindSchema = z.enum(["client", "server"]);
+/**
+* `-g`/`--additional-properties` values: openapi-generator accepts strings,
+* numbers and booleans, all rendered as `key=value` on the CLI.
+*/
+const additionalPropertiesSchema = z.record(z.string(), z.union([
+	z.string(),
+	z.number(),
+	z.boolean()
+])).default({});
+const mavenCoordsSchema = z.object({
+	groupId: z.string().min(1),
+	artifactId: z.string().min(1)
+});
+/**
+* The shape of a generator "recipe", without the cross-field checks below -
+* kept separate so {@link artifactRefSchema}'s `overrides:` can `.partial()`
+* it (zod rejects `.partial()` on a schema with `.check()` refinements
+* attached).
+*/
+const generatorDefBaseSchema = z.object({
+	tool: sdkToolSchema,
+	lang: sdkLangSchema,
+	kind: sdkKindSchema,
+	/**
+	* `openapi-generator -g <generator>` value. Required when `tool` is
+	* `openapi-generator`.
+	*/
+	generator: z.string().min(1).optional(),
+	/** npm package name template, e.g. `"@{vars.org}/{service}-client"`. */
+	package: z.string().min(1).optional(),
+	goModule: z.string().min(1).optional(),
+	goPackageName: z.string().min(1).optional(),
+	maven: mavenCoordsSchema.optional(),
+	additionalProperties: additionalPropertiesSchema,
+	/**
+	* Optional path (relative to the config file's directory) to a custom README
+	* template for this artifact - supports the same `{...}` placeholders as
+	* naming templates, plus `{version}`, `{title}`, and `{artifact.*}`. If
+	* omitted, a built-in default template for the artifact's language/kind is
+	* used instead.
+	*/
+	readme: z.string().min(1).optional()
+});
+/**
+* A single generator "recipe": which tool to invoke and how. Referenced by id
+* from one or more contracts' `artifacts:` list.
+*/
+const generatorDefSchema = generatorDefBaseSchema.check((ctx) => {
+	const value = ctx.value;
+	if (value.tool === "openapi-generator" && !value.generator) ctx.issues.push({
+		code: "custom",
+		message: "\"generator\" is required when tool is \"openapi-generator\"",
+		input: value
+	});
+	if (value.lang === "go" && !value.goModule) ctx.issues.push({
+		code: "custom",
+		message: "\"goModule\" is required for lang \"go\"",
+		input: value
+	});
+	if (value.lang === "java" && !value.maven) ctx.issues.push({
+		code: "custom",
+		message: "\"maven\" ({ groupId, artifactId }) is required for lang \"java\"",
+		input: value
+	});
+	if (value.lang === "typescript" && !value.package) ctx.issues.push({
+		code: "custom",
+		message: "\"package\" is required for lang \"typescript\"",
+		input: value
+	});
+});
+const generatorsSchema = z.record(z.string(), generatorDefSchema);
+/**
+* A contract's reference to a generator by id. The plain-string form just runs
+* that generator as-is; the object form lets one contract tweak a shared
+* generator (extra/overridden `additionalProperties`, a different
+* `maven`/`package`/`readme`/... value) without duplicating the whole recipe
+* under a new id, and `as` renames the artifact's own id (output
+* folder / branch / tag segment) if a contract needs two variants of the same
+* base generator.
+*/
+const artifactRefSchema = z.union([z.string().min(1), z.object({
+	generator: z.string().min(1),
+	as: z.string().min(1).optional(),
+	overrides: generatorDefBaseSchema.partial().optional()
+})]);
+const contractSchema = z.object({
+	name: z.string().min(1),
+	title: z.string().min(1),
+	entrypoint: z.string().min(1),
+	artifacts: z.array(artifactRefSchema).min(1)
+});
+const rootConfigSchema = z.object({
+	github: githubSchema,
+	vars: varsTreeSchema.default({}),
+	paths: pathsSchema.default({ dist: "dist" }),
+	docs: docsSchema,
+	generators: generatorsSchema,
+	contracts: z.array(contractSchema).min(1)
+});
+//#endregion
+//#region src/config/template.ts
+const PLACEHOLDER = /\{([a-zA-Z0-9_.]+)}/g;
+/**
+* Replaces every `{dot.path}` placeholder in `template` with its value from
+* `context`, throwing a descriptive error if a placeholder has no match -
+* a typo'd `{vars.org}` should fail loudly at config-load time, not silently
+* produce a package named literally `@{vars.org}/...`.
+*
+* @param template - The template string, e.g. `"@{vars.org}/{service}-client"`.
+* @param context  - The flattened context to resolve placeholders against.
+* @returns The interpolated string.
+*/
+function interpolate(template, context) {
+	return template.replace(PLACEHOLDER, (_match, key) => {
+		const value = context[key];
+		if (value === void 0) {
+			const available = Object.keys(context).sort().join(", ");
+			throw new Error(`Unknown template placeholder "{${key}}" in "${template}" (available: ${available})`);
+		}
+		return value;
+	});
+}
+/**
+* Recursively interpolates every string value in `value` (walking through plain
+* objects), leaving non-string leaves untouched. Used to resolve
+* `additionalProperties` maps, which may mix templated strings with plain
+* booleans/numbers.
+*
+* @param value   - The value (string, object, or primitive) to interpolate.
+* @param context - The flattened context to resolve placeholders against.
+* @returns A deep copy of `value` with every string interpolated.
+*/
+function interpolateDeep(value, context) {
+	if (typeof value === "string") return interpolate(value, context);
+	if (Array.isArray(value)) return value.map((item) => interpolateDeep(item, context));
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, interpolateDeep(child, context)]));
+	return value;
+}
+/**
+* Flattens a nested scope object (e.g. `{ service: "auth", vars: { org: "x" } }`)
+* into dot-path lookup keys (`{ service: "auth", "vars.org": "x" }`) for use
+* with {@link interpolate}.
+*
+* @param scope - The nested scope to flatten.
+* @returns A flat dot-path -> string map.
+*/
+function buildTemplateContext(scope) {
+	const out = {};
+	flatten(scope, "", out);
+	return out;
+}
+function flatten(value, prefix, out) {
+	if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+		for (const [key, child] of Object.entries(value)) flatten(child, prefix ? `${prefix}.${key}` : key, out);
+		return;
+	}
+	if (value === void 0) return;
+	out[prefix] = String(value);
+}
+//#endregion
+//#region src/config/loader.ts
+/**
+* Reads and validates a CLI config file, throwing a readable, multi-issue error
+* message if it doesn't match the schema.
+*
+* @param configPath - Absolute path to the YAML config file.
+* @returns The validated (but not yet resolved) raw config.
+*/
+function readRawConfig(configPath) {
+	const raw = parse(readFileSync(configPath, "utf8"));
+	const result = rootConfigSchema.safeParse(raw);
+	if (!result.success) {
+		const issues = z.prettifyError(result.error);
+		throw new Error(`Invalid ${path.basename(configPath)}:\n${issues}`);
+	}
+	return result.data;
+}
+/**
+* Deep-merges a generator override (from an artifact's `overrides:` block)
+* onto its base generator def. `additionalProperties` and `maven` are merged
+* key-by-key; every other field is a plain override.
+*
+* @param base      - The base generator def, looked up by id from `generators:`.
+* @param overrides - The partial override from the artifact reference, if any.
+* @returns The merged generator def.
+*/
+function mergeGeneratorOverride(base, overrides) {
+	if (!overrides) return base;
+	return {
+		...base,
+		...overrides,
+		maven: overrides.maven ? {
+			...base.maven,
+			...overrides.maven
+		} : base.maven,
+		additionalProperties: {
+			...base.additionalProperties,
+			...overrides.additionalProperties
+		}
+	};
+}
+/**
+* Resolves a single artifact reference (string id, or `{ generator, overrides,
+* as }`) into its `{ id, def }` pair, looking up the base generator by id and
+* applying any overrides.
+*
+* @param ref          - The artifact reference from a contract's `artifacts:`
+*                       list.
+* @param generators   - The full `generators:` map from the raw config.
+* @param contractName - The owning contract's name.
+* @returns The artifact's resolved id and generator def (templates not yet
+*          interpolated).
+*/
+function resolveArtifactRef(ref, generators, contractName) {
+	const generatorId = typeof ref === "string" ? ref : ref.generator;
+	const base = generators[generatorId];
+	if (!base) {
+		const available = Object.keys(generators).sort().join(", ");
+		throw new Error(`Contract "${contractName}" references unknown generator "${generatorId}" (available: ${available})`);
+	}
+	return {
+		id: typeof ref === "string" ? ref : ref.as ?? ref.generator,
+		def: mergeGeneratorOverride(base, typeof ref === "string" ? void 0 : ref.overrides)
+	};
+}
+/**
+* Interpolates templates and resolves absolute paths for a single artifact.
+*
+* @param id           - The artifact's resolved id (output folder / branch /
+*                       tag segment).
+* @param def          - The (override-merged, not-yet-interpolated) generator
+*                       def.
+* @param rootDir      - Absolute repo root, `readme` template paths are
+*                       resolved relative to this.
+* @param sdkDir       - Absolute path to the SDK output root (`<dist>/sdk`).
+* @param contractName - The owning contract's name.
+* @param context      - The flattened template context for this contract.
+* @returns The fully resolved artifact.
+*/
+function resolveArtifact(id, def, rootDir, sdkDir, contractName, context) {
+	const resolved = interpolateDeep(def, context);
+	return {
+		id,
+		tool: resolved.tool,
+		lang: resolved.lang,
+		kind: resolved.kind,
+		generator: resolved.generator,
+		outputDir: path.join(sdkDir, contractName, id),
+		branch: `sdk/svc-${contractName}/${id}`,
+		tagPrefix: `svc-${contractName}-${id}`,
+		additionalProperties: resolved.additionalProperties,
+		package: resolved.package,
+		goModule: resolved.goModule,
+		goPackageName: resolved.goPackageName,
+		maven: resolved.maven,
+		readmeTemplate: resolved.readme ? path.resolve(rootDir, resolved.readme) : void 0
+	};
+}
+/**
+* Resolves a single contract: its entrypoint path and every artifact in its
+* `artifacts:` list.
+*
+* @param input      - The raw contract config.
+* @param rootDir    - Absolute repo root, entrypoints/`readme` paths are
+*                     resolved relative to this.
+* @param sdkDir     - Absolute path to the SDK output root (`<dist>/sdk`).
+* @param generators - The full `generators:` map from the raw config.
+* @param githubCtx  - `{ owner, repo }`, exposed to templates as
+*                     `{github.owner}`/`{github.repo}`.
+* @param vars       - The `vars:` tree from the raw config, exposed as
+*                     `{vars.*}`.
+* @returns The fully resolved contract.
+*/
+function resolveContract(input, rootDir, sdkDir, generators, githubCtx, vars) {
+	const context = buildTemplateContext({
+		service: input.name,
+		github: githubCtx,
+		vars
+	});
+	const artifacts = input.artifacts.map((ref) => {
+		const { id, def } = resolveArtifactRef(ref, generators, input.name);
+		return resolveArtifact(id, def, rootDir, sdkDir, input.name, context);
+	});
+	const entrypoint = path.join(rootDir, input.entrypoint);
+	return {
+		name: input.name,
+		title: input.title,
+		entrypoint,
+		entrypointRelative: path.relative(rootDir, entrypoint),
+		artifacts
+	};
+}
+/**
+* Loads, validates, and fully resolves a CLI config file - the single entry
+* point every command uses to get its configuration.
+*
+* Unlike a build tool bundled into the consumer's own repo, seagull is
+* installed as a dependency, so it has no way to guess where the
+* consumer's config lives on its own - `configPath` must be supplied by the
+* caller (the CLI resolves it via `resolveConfigPath()` in
+* `config/resolve-config-file.ts`, or `--config`).
+*
+* @param configPath - Absolute path to the CLI config file.
+* @returns The fully resolved config.
+*/
+function loadConfig(configPath) {
+	const rootDir = path.dirname(configPath);
+	const raw = readRawConfig(configPath);
+	const distDir = path.resolve(rootDir, raw.paths.dist);
+	const specsDir = raw.paths.specs ? path.resolve(rootDir, raw.paths.specs) : path.join(distDir, "specs");
+	const docsDir = raw.paths.docs ? path.resolve(rootDir, raw.paths.docs) : path.join(distDir, "docs");
+	const sdkDir = raw.paths.sdk ? path.resolve(rootDir, raw.paths.sdk) : path.join(distDir, "sdk");
+	const contracts = raw.contracts.map((contract) => resolveContract(contract, rootDir, sdkDir, raw.generators, raw.github, raw.vars));
+	return {
+		rootDir,
+		paths: {
+			dist: distDir,
+			specs: specsDir,
+			docs: docsDir,
+			sdk: sdkDir
+		},
+		github: raw.github,
+		vars: raw.vars,
+		docs: raw.docs,
+		contracts,
+		allArtifacts: contracts.flatMap((contract) => contract.artifacts.map((artifact) => ({
+			contract,
+			artifact
+		})))
+	};
+}
+//#endregion
+//#region src/config/resolve-config-file.ts
+/**
+* Config filenames CLI recognizes, checked in this order.
+*/
+const CONFIG_FILENAMES = [
+	".seagull",
+	".seagull.yaml",
+	".seagull.yml",
+	"seagull.yaml",
+	"seagull.yml"
+];
+/**
+* Finds the CLI config file in a directory, trying each of
+* {@link CONFIG_FILENAMES} in order.
+*
+* @param cwd - The directory to look in (typically `process.cwd()`).
+* @returns The absolute path to the first matching config file.
+* @throws Error if none of the candidate filenames exist in `cwd`.
+*
+* @see {@link CONFIG_FILENAMES} - the list of filenames checked, in order.
+*/
+function resolveConfigPath(cwd) {
+	for (const filename of CONFIG_FILENAMES) {
+		const candidate = path.join(cwd, filename);
+		if (existsSync(candidate)) return candidate;
+	}
+	throw new Error(`No CLI config found in ${cwd} - looked for: ${CONFIG_FILENAMES.join(", ")}. Create one of these, or pass --config <path>.`);
+}
+//#endregion
+//#region src/core/process/exec.ts
+/**
+* Runs a command to completion, streaming its stdio straight through
+* (`inherit`), and rejects if it exits non-zero.
+*
+* This is the async counterpart used for the "one long-running tool" commands
+* (`redocly`, `openapi-generator-cli`, `openapi-typescript`); for short
+* synchronous calls (git plumbing, `npm publish`/`mvn deploy`), see
+* {@link runSync}.
+*
+* @param command - The executable to run.
+* @param args    - Arguments to pass to it.
+* @param cwd     - The working directory to run it in.
+* @returns A promise that resolves on exit code 0, and rejects otherwise.
+*/
+function run(command, args, cwd) {
+	return new Promise((resolvePromise, reject) => {
+		spawn(command, args, {
+			cwd,
+			stdio: "inherit",
+			shell: true
+		}).on("close", (code) => {
+			if (code === 0) {
+				resolvePromise();
+				return;
+			}
+			reject(/* @__PURE__ */ new Error(`${command} ${args.join(" ")} exited with ${code}`));
+		});
+	});
+}
+/**
+* Runs a command to completion synchronously, streaming its stdio straight
+* through (`inherit`).
+*
+* @param command - The executable to run.
+* @param args    - Arguments to pass to it.
+* @param cwd     - The working directory to run it in.
+* @returns The exit status (0 on success).
+*/
+function runSync(command, args, cwd) {
+	return spawnSync(command, args, {
+		cwd,
+		stdio: "inherit",
+		shell: true
+	}).status ?? 1;
+}
+//#endregion
+//#region src/core/process/resolve-bin.ts
+const require = createRequire(import.meta.url);
+/**
+* Resolves the absolute path to an installed npm package's own CLI entrypoint
+* script, using Node's standard module resolution algorithm - so it works the
+* same way regardless of which package manager (npm/pnpm/yarn) installed CLI
+* and its dependencies, or how deeply they get hoisted. Shelling out to
+* `pnpm exec`/`npx` instead would assume a specific package manager and a
+* particular install layout, which doesn't hold once CLI is just another
+* dependency in someone else's project.
+*
+* @param pkgName - The npm package name, e.g. `"@org/cli"`.
+* @param binName - Which entry to resolve from that package's `bin` field.
+*                  Defaults to the package's own unscoped name.
+* @returns The absolute path to the resolved bin script.
+* @throws Error if the package or the requested bin entry can't be found.
+*/
+function resolveBinPath(pkgName, binName) {
+	const pkgJsonPath = require.resolve(`${pkgName}/package.json`);
+	const pkgDir = path.dirname(pkgJsonPath);
+	const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+	const key = binName ?? pkg.name.split("/").pop();
+	const bin = typeof pkg.bin === "string" ? pkg.bin : pkg.bin?.[key];
+	if (!bin) throw new Error(`Could not resolve a "${key}" bin entry for package "${pkgName}" - is it installed, and does it expose that bin?`);
+	return path.join(pkgDir, bin);
+}
+//#endregion
+//#region src/core/redocly/redocly-sync.ts
+const GENERATED_HEADER = "# AUTO-GENERATED by Seagull from its config and 'redocly.base.yaml'.\n# Do not edit directly, edit those two files instead (this file is\n# regenerated on every lint/bundle/generate run).\n\n";
+/**
+* Regenerates `redocly.yaml`'s `apis:` section from the resolved CLI config,
+* merging it with the hand-authored `extends`/`rules` in `redocly.base.yaml`.
+*
+* The CLI config stays the single source of truth for which APIs exist and
+* where their TypeScript server types land, instead of that being duplicated
+* by hand into `redocly.yaml`.
+*
+* Called at the start of every command that shells out to `redocly` or
+* `openapi-typescript` (both read `redocly.yaml` directly), so it's always
+* up to date before those tools run.
+*
+* @param config - The resolved CLI config.
+*/
+async function syncRedoclyConfig(config) {
+	const basePath = path.join(config.rootDir, "redocly.base.yaml");
+	const base = parse(await readFile(basePath, "utf8"));
+	const apis = Object.fromEntries(config.contracts.map((contract) => {
+		const typesArtifact = contract.artifacts.find((artifact) => artifact.tool === "openapi-typescript");
+		return [`${contract.name}@v1`, {
+			root: contract.entrypointRelative,
+			...typesArtifact ? { "x-openapi-ts": { output: path.join(path.relative(config.rootDir, typesArtifact.outputDir), "index.d.ts") } } : {}
+		}];
+	}));
+	const final = {
+		extends: base.extends,
+		apis,
+		rules: base.rules
+	};
+	await writeFile(path.join(config.rootDir, "redocly.yaml"), GENERATED_HEADER + stringify(final));
+}
+//#endregion
+//#region src/commands/bundle.ts
+/**
+* Bundles every contract's OpenAPI spec into `dist/specs/<contract>.json`.
+*
+* @param config - The resolved CLI config.
+*/
+async function bundleCommand(config) {
+	await syncRedoclyConfig(config);
+	await rm(config.paths.specs, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(config.paths.specs, { recursive: true });
+	const redoclyBin = resolveBinPath("@redocly/cli", "redocly");
+	for (const contract of config.contracts) {
+		const output = path.join(config.paths.specs, `${contract.name}.json`);
+		await run("node", [
+			redoclyBin,
+			"bundle",
+			contract.entrypoint,
+			"-o",
+			output
+		], config.rootDir);
+	}
+	console.log(`Bundled ${config.contracts.length} specifications into ${config.paths.specs}`);
+}
+//#endregion
+//#region src/commands/clean.ts
+/**
+* Removes the entire `dist` output directory.
+*
+* @param config - The resolved CLI config.
+*/
+async function cleanCommand(config) {
+	await rm(config.paths.dist, {
+		recursive: true,
+		force: true
+	});
+	console.log(`Cleaned ${config.paths.dist}`);
+}
+//#endregion
+//#region src/commands/generate-docs.ts
+/**
+* Generates the documentation website for every contract into `dist/docs`.
+*
+* @param config - The resolved CLI config.
+*/
+async function generateDocsCommand(config) {
+	const output = config.paths.docs;
+	const specsOutput = join(output, "specs");
+	await rm(output, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(specsOutput, { recursive: true });
+	for (const contract of config.contracts) {
+		const source = join(config.paths.specs, `${contract.name}.json`);
+		const target = join(specsOutput, `${contract.name}.json`);
+		const contents = await readFile(source, "utf8");
+		await writeFile(target, contents);
+	}
+	const mainEntryPoint = createRequire(import.meta.url).resolve("@scalar/api-reference");
+	let packageDir = dirname(mainEntryPoint);
+	while (!packageDir.endsWith("@scalar/api-reference") && !packageDir.endsWith("@scalar\\api-reference")) {
+		const parent = dirname(packageDir);
+		if (parent === packageDir) break;
+		packageDir = parent;
+	}
+	const scalarScriptPath = join(packageDir, "dist", "browser", "standalone.js");
+	const scalarTarget = join(output, "scalar.js");
+	await copyFile(scalarScriptPath, scalarTarget);
+	console.log(`Copied Scalar script to ${scalarTarget}`);
+	const sources = config.contracts.map((contract, index) => `{
+      title: ${JSON.stringify(contract.title)},
+      slug: ${JSON.stringify(contract.name)},
+      url: "./specs/${contract.name}.json"${index === 0 ? ",\n      default: true" : ""}
+    }`).join(",\n");
+	const { metadata } = config.docs;
+	const html = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+  </head>
+  <body>
+    <div id="app"></div>
+
+    <!-- Load the Script -->
+    <script src="./scalar.js"><\/script>
+
+    <!-- Initialize the API Reference -->
+    <script>
+      Scalar.createApiReference("#app", {
+        baseServerURL: "${metadata.baseServerUrl}",
+        favicon: "${metadata.favicon}",
+        metaData: {
+          title: "${metadata.title}",
+          description: "${metadata.description}",
+          ogTitle: "${metadata.title}",
+          ogDescription: "${metadata.description}",
+        },
+        layout: "classic",
+        darkMode: true,
+        telemetry: false,
+        showDeveloperTools: "never",
+        showOperationId: true,
+        hideTestRequestButton: false,
+        sources: [
+          ${sources}
+        ]
+      });
+    <\/script>
+  </body>
+</html>
+`;
+	await writeFile(join(output, "index.html"), html);
+	console.log(`Generated documentation website at ${output}`);
+}
+//#endregion
+//#region src/core/generator/registry.ts
+/**
+* Looks up the concrete {@link Generator} implementation for a given tool name.
+*/
+var GeneratorRegistry = class {
+	generators = /* @__PURE__ */ new Map();
+	/**
+	* Registers a generator implementation under its own {@link Generator.tool}.
+	*
+	* @param generator - The generator instance to register.
+	* @returns `this`, for chaining.
+	*/
+	register(generator) {
+		this.generators.set(generator.tool, generator);
+		return this;
+	}
+	/**
+	* Resolves the generator implementation for a given tool name.
+	*
+	* @param tool - The tool name, e.g. `"openapi-generator"`.
+	* @returns The registered generator.
+	* @throws Error if no generator is registered for that tool.
+	*/
+	resolve(tool) {
+		const generator = this.generators.get(tool);
+		if (!generator) {
+			const available = [...this.generators.keys()].join(", ");
+			throw new Error(`No generator implementation registered for tool "${tool}" (available: ${available})`);
+		}
+		return generator;
+	}
+	/**
+	* All distinct tools currently registered.
+	*
+	* @returns The registered tool names.
+	*/
+	tools() {
+		return [...this.generators.keys()];
+	}
+};
+//#endregion
+//#region src/core/readme/default-templates.ts
+/**
+* Renders a sensible default `README.md` for a generated SDK package, used
+* whenever the artifact has no custom `readme:` template configured. Covers
+* every built-in `lang`/`kind` combination; anything more specific (an internal
+* registry URL, a real base API URL, house install instructions) belongs in a
+* custom template instead - see `readme-renderer.ts`.
+*
+* @param args - The contract, artifact, version, and github coordinates to
+*               render for.
+* @returns The rendered README content.
+*/
+function renderDefaultReadme({ contract, artifact, version, github }) {
+	return `${`# ${contract.title} - ${label(artifact)}
+
+> Generated from \`${contract.entrypointRelative}\` in [${github.owner}/${github.repo}](https://github.com/${github.owner}/${github.repo}).
+> Do not edit by hand - this package is regenerated and republished on every release.
+
+Version: \`${version}\`
+Source branch: \`${artifact.branch}\`
+`}\n${body(contract, artifact, version, github)}\n`;
+}
+function label(artifact) {
+	return `${{
+		typescript: "TypeScript",
+		go: "Go",
+		java: "Java"
+	}[artifact.lang]} ${artifact.kind === "client" ? "Client SDK" : artifact.lang === "typescript" ? "Server Types" : "Server Stubs"}`;
+}
+function body(contract, artifact, version, github) {
+	switch (`${artifact.lang}-${artifact.kind}`) {
+		case "typescript-client": return tsClient(artifact, version);
+		case "typescript-server": return tsServer(artifact, version);
+		case "go-client": return goClient(contract, artifact);
+		case "go-server": return goServer(contract, artifact);
+		case "java-client": return javaClient(artifact, version, github);
+		case "java-server": return javaServer(artifact, version, github);
+		default: return "";
+	}
+}
+function tsClient(artifact, version) {
+	return `## Install
+
+\`\`\`bash
+npm config set <scope>:registry https://npm.pkg.github.com
+npm install ${artifact.package}@${version}
+\`\`\`
+
+(GitHub Packages requires an authenticated \`.npmrc\` with a token that has
+\`read:packages\`.)
+
+## Usage
+
+\`\`\`ts
+import { Configuration, DefaultApi } from "${artifact.package}";
+
+const api = new DefaultApi(
+  new Configuration({ basePath: "https://api.your-domain.com" }),
+);
+
+const result = await api.someOperation();
+\`\`\`
+`;
+}
+function tsServer(artifact, version) {
+	return `## Install
+
+\`\`\`bash
+npm config set <scope>:registry https://npm.pkg.github.com
+npm install --save-dev ${artifact.package}@${version}
+\`\`\`
+
+(GitHub Packages requires an authenticated \`.npmrc\` with a token that has
+\`read:packages\`.)
+
+## Usage
+
+\`\`\`ts
+import type { components, operations } from "${artifact.package}";
+
+type LoginResponses = operations["login"]["responses"];
+
+// Example: an Express handler typed against the contract
+app.post("/login", (req, res) => {
+  const body = req.body as components["schemas"]["LoginRequest"];
+  const response: LoginResponses[200]["content"]["application/json"] = {
+    // ...
+  };
+  res.json(response);
+});
+\`\`\`
+`;
+}
+function goClient(contract, artifact) {
+	return `## Install
+
+Go has no package registry, so this module is pulled directly from its
+publishing branch:
+
+\`\`\`bash
+go get ${artifact.goModule}@sdk/svc-${contract.name}/${artifact.id}
+\`\`\`
+
+To pin an exact release instead of the branch head, use the matching tag:
+
+\`\`\`bash
+go get ${artifact.goModule}@${artifact.tagPrefix}-v<version>
+\`\`\`
+
+## Usage
+
+\`\`\`go
+import (
+    "context"
+
+    ${artifact.goPackageName} "${artifact.goModule}"
+)
+
+func main() {
+    cfg := ${artifact.goPackageName}.NewConfiguration()
+    client := ${artifact.goPackageName}.NewAPIClient(cfg)
+
+    resp, _, err := client.DefaultAPI.SomeOperation(context.Background()).Execute()
+    _ = resp
+    _ = err
+}
+\`\`\`
+`;
+}
+function goServer(contract, artifact) {
+	return `## Install
+
+\`\`\`bash
+go get ${artifact.goModule}@sdk/svc-${contract.name}/${artifact.id}
+\`\`\`
+
+## Usage
+
+Implement the generated \`${artifact.goPackageName}.*ApiServicer\` interfaces and
+wire them into the generated router:
+
+\`\`\`go
+router := ${artifact.goPackageName}.NewRouter(
+    ${artifact.goPackageName}.NewSomeApiController(yourServiceImpl),
+)
+\`\`\`
+`;
+}
+function javaClient(artifact, version, github) {
+	return `## Install (Maven, GitHub Packages)
+
+\`\`\`xml
+<dependency>
+  <groupId>${artifact.maven?.groupId}</groupId>
+  <artifactId>${artifact.maven?.artifactId}</artifactId>
+  <version>${version}</version>
+</dependency>
+\`\`\`
+
+Add the repository to your \`settings.xml\` (or \`pom.xml\`) with a token that
+has \`read:packages\`:
+
+\`\`\`xml
+<repository>
+  <id>github</id>
+  <url>https://maven.pkg.github.com/${github.owner}/${github.repo}</url>
+</repository>
+\`\`\`
+
+## Usage
+
+Generated with \`library=restclient\` - Spring's \`RestClient\`, the current
+recommended synchronous HTTP client for Spring apps:
+
+\`\`\`java
+@Configuration
+public class SomeServiceClientConfig {
+
+    @Bean
+    public ApiClient someServiceApiClient(RestClient.Builder builder) {
+        ApiClient client = new ApiClient(builder.build());
+        client.setBasePath("https://api.your-domain.com");
+        return client;
+    }
+
+    @Bean
+    public DefaultApi someServiceApi(ApiClient someServiceApiClient) {
+        return new DefaultApi(someServiceApiClient);
+    }
+}
+\`\`\`
+`;
+}
+function javaServer(artifact, version, github) {
+	return `## Install (Maven, GitHub Packages)
+
+\`\`\`xml
+<dependency>
+  <groupId>${artifact.maven?.groupId}</groupId>
+  <artifactId>${artifact.maven?.artifactId}</artifactId>
+  <version>${version}</version>
+</dependency>
+\`\`\`
+
+Add the repository to your \`settings.xml\` (or \`pom.xml\`) with a token that
+has \`read:packages\`:
+
+\`\`\`xml
+<repository>
+  <id>github</id>
+  <url>https://maven.pkg.github.com/${github.owner}/${github.repo}</url>
+</repository>
+\`\`\`
+
+## Usage
+
+This artifact only contains the generated Spring \`@RestController\` interfaces
+(\`interfaceOnly=true\`) - implement them in your service:
+
+\`\`\`java
+@RestController
+public class SomeController implements SomeApi {
+    // interface methods generated from the OpenAPI contract
+}
+\`\`\`
+`;
+}
+//#endregion
+//#region src/core/readme/readme-renderer.ts
+/**
+* Renders the root-level `README.md` for a generated SDK package.
+*
+* If the artifact has a `readme:` path configured (resolved at config-load time
+* to `artifact.readmeTemplate`), that file is read and interpolated with the
+* same `{...}` placeholder engine naming templates use - `{service}`,
+* `{title}`, `{version}`, `{vars.*}`, `{github.owner}`, `{github.repo}`, plus
+* `{artifact.*}` (id/lang/kind/package/goModule/goPackageName/maven.groupId/
+* maven.artifactId/branch/tagPrefix). Otherwise, falls back to a built-in
+* default template for the artifact's language/kind.
+*
+* @param args - The contract, artifact, version, and github/vars context to
+*               render for.
+* @returns The rendered README content.
+*/
+async function renderReadme(args) {
+	if (!args.artifact.readmeTemplate) return renderDefaultReadme(args);
+	return interpolate(await readFile(args.artifact.readmeTemplate, "utf8"), buildTemplateContext({
+		service: args.contract.name,
+		title: args.contract.title,
+		version: args.version,
+		github: args.github,
+		vars: args.vars,
+		artifact: {
+			id: args.artifact.id,
+			lang: args.artifact.lang,
+			kind: args.artifact.kind,
+			package: args.artifact.package,
+			goModule: args.artifact.goModule,
+			goPackageName: args.artifact.goPackageName,
+			maven: args.artifact.maven,
+			branch: args.artifact.branch,
+			tagPrefix: args.artifact.tagPrefix
+		}
+	}));
+}
+//#endregion
+//#region src/core/version/version.ts
+/**
+* Resolves the version to stamp onto a single contract's generated SDK
+* artifacts (npm/Maven packages, Go module tags, git branches, etc.).
+*
+* The single source of truth is that contract's own `info.version` field in its
+* `openapi.yaml` - bump it there and every artifact, package, and git tag for
+* that contract picks up the new version on the next release. Versions are
+* resolved independently per contract: two services can be at different
+* versions at the same time.
+*
+* `SDK_VERSION_OVERRIDE` (wired up from the release workflow's manual `version`
+* input) bypasses the spec entirely and stamps every contract with the same
+* given value. It exists for one-off emergency republishes, not routine
+* releases. Routine releases should always go through `info.version`.
+*
+* @param spec         - The parsed, bundled OpenAPI document for the contract.
+* @param contractName - The contract name, used only for the error message.
+* @returns The resolved version string (no leading `v`).
+* @throws Error if no override is set and the spec has no `info.version`.
+*/
+function resolveVersion(spec, contractName) {
+	const override = process.env.SDK_VERSION_OVERRIDE?.trim();
+	if (override) return override.replace(/^v/, "");
+	const specVersion = spec.info?.version?.trim();
+	if (!specVersion) throw new Error(`specs/${contractName}/openapi.yaml is missing "info.version" - set it to a semver value. This field is the single source of truth for the ${contractName} contract's SDK version.`);
+	return specVersion.replace(/^v/, "");
+}
+/**
+* Computes a stable content hash of a bundled OpenAPI document's raw JSON text.
+* Stamped alongside `VERSION` into every generated SDK package so
+* `publish-sdk.ts` can tell a genuine no-op republish (same spec, same version)
+* apart from a spec that changed without its `info.version` being bumped.
+*
+* @param raw - The raw bundled spec file contents (JSON text).
+* @returns A `sha256` hex digest of the raw contents.
+*/
+function hashSpec(raw) {
+	return createHash("sha256").update(raw).digest("hex");
+}
+//#endregion
+//#region src/core/generator/generator.ts
+/**
+* The root primitive every concrete SDK generator implements.
+*
+* One instance per underlying tool (`openapi-generator-cli`,
+* `openapi-typescript`, ...) - not one per language, since a single tool
+* invocation (e.g. `openapi-generator-cli -g java`/`-g go`) already covers
+* every language it supports. Language-specific behaviour (patching `go.mod`,
+* `package.json`, `pom.xml`, ...) is composed in via patchers rather than
+* living in per-language subclasses.
+*/
+var Generator = class {};
+//#endregion
+//#region src/generators/openapi-generator-cli/patchers/go-module.patcher.ts
+/**
+* Patches the `go.mod` file in a generated Go SDK package to set the correct
+* module path (`openapi-generator-cli` has no way to be told this up front for
+* every template).
+*/
+var GoModulePatcher = class {
+	async patch({ artifact }) {
+		if (!artifact.goModule) return;
+		const moduleFile = path.join(artifact.outputDir, "go.mod");
+		try {
+			const contents = await readFile(moduleFile, "utf8");
+			await writeFile(moduleFile, contents.replace(/^module .*$/m, `module ${artifact.goModule}`));
+		} catch {}
+	}
+};
+//#endregion
+//#region src/generators/openapi-generator-cli/patchers/maven.patcher.ts
+/**
+* Patches the `pom.xml` file in a generated Java SDK package to set the correct
+* version and distribution management information for publishing.
+*/
+var MavenPomPatcher = class {
+	async patch({ artifact, version, github }) {
+		const pomFile = path.join(artifact.outputDir, "pom.xml");
+		try {
+			let pom = await readFile(pomFile, "utf8");
+			pom = pom.replace(/<version>[^<]*<\/version>/, `<version>${version}</version>`);
+			if (!pom.includes("<distributionManagement>")) pom = pom.replace("</project>", [
+				"  <distributionManagement>",
+				"    <repository>",
+				"      <id>github</id>",
+				`      <n>${github.owner} ${github.repo} Packages</n>`,
+				`      <url>https://maven.pkg.github.com/${github.owner}/${github.repo}</url>`,
+				"    </repository>",
+				"  </distributionManagement>",
+				"</project>"
+			].join("\n"));
+			await writeFile(pomFile, pom);
+		} catch {}
+	}
+};
+//#endregion
+//#region src/generators/openapi-generator-cli/patchers/npm.patcher.ts
+/**
+* Patches the `package.json` file in a generated TypeScript SDK package (the
+* client target - `openapi-generator-cli` produces its own `package.json`, this
+* just fills in the version and publishing metadata) to set the correct version
+* and repository information.
+*/
+var NpmPackagePatcher = class {
+	async patch({ contract, artifact, version, github }) {
+		const pkgFile = path.join(artifact.outputDir, "package.json");
+		const pkgData = await readFile(pkgFile, "utf8");
+		const pkg = JSON.parse(pkgData);
+		pkg.version = version;
+		pkg.repository = {
+			type: "git",
+			url: `git+https://github.com/${github.owner}/${github.repo}.git`,
+			directory: `sdk/svc-${contract.name}/${artifact.id}`
+		};
+		pkg.publishConfig = {
+			registry: "https://npm.pkg.github.com",
+			access: "restricted"
+		};
+		await writeFile(pkgFile, JSON.stringify(pkg, null, 2));
+	}
+};
+//#endregion
+//#region src/generators/openapi-generator-cli/openapi-generator-cli.generator.ts
+/**
+* Additional-properties that are fully derivable from an artifact's own
+* `package`/`goPackageName`/`maven` fields - conventional openapi-generator
+* knobs (`npmName`, `groupId`, ...) that would otherwise have to be duplicated
+* by hand in every generator's `additionalProperties:` block, in lockstep with
+* those same fields. Tool-specific tuning that isn't derivable this way
+* (`library=restclient`, `withGoMod`, ...) still lives in
+* `additionalProperties:` and is layered on top of these.
+*
+* @param artifact - The resolved artifact to derive properties for.
+* @returns The derived additional-properties, before the artifact's own
+*          `additionalProperties` are layered on top.
+*/
+function deriveAdditionalProperties(artifact) {
+	if (artifact.lang === "typescript" && artifact.package) return { npmName: artifact.package };
+	if (artifact.lang === "go" && artifact.goPackageName) return { packageName: artifact.goPackageName };
+	if (artifact.lang === "java" && artifact.maven) {
+		const invokerPackage = `${artifact.maven.groupId}.${artifact.kind}`;
+		return {
+			groupId: artifact.maven.groupId,
+			artifactId: artifact.maven.artifactId,
+			invokerPackage,
+			apiPackage: `${invokerPackage}.api`,
+			modelPackage: `${invokerPackage}.model`
+		};
+	}
+	return {};
+}
+/**
+* Renders an artifact's additional-properties (derived + explicit, explicit
+* wins on conflicts) as the `key=value,key=value` string
+* `openapi-generator-cli --additional-properties` expects.
+*
+* @param artifact - The resolved artifact.
+* @returns The rendered `--additional-properties` value.
+*/
+function buildAdditionalPropertiesArg(artifact) {
+	const merged = {
+		...deriveAdditionalProperties(artifact),
+		...artifact.additionalProperties
+	};
+	return Object.entries(merged).map(([key, value]) => `${key}=${String(value)}`).join(",");
+}
+/**
+* Wraps `openapi-generator-cli` - the single tool implementation behind every
+* `-g` template (`typescript-fetch`, `go`, `go-server`, `java`, `spring`, ...),
+* regardless of language. Language-specific output patching is delegated to a
+* {@link Patcher}, selected by `artifact.lang`.
+*/
+var OpenApiGeneratorCli = class extends Generator {
+	tool = "openapi-generator";
+	patchers = {
+		go: new GoModulePatcher(),
+		typescript: new NpmPackagePatcher(),
+		java: new MavenPomPatcher()
+	};
+	async generate(ctx) {
+		const { artifact, rootDir, specInputPath } = ctx;
+		if (!artifact.generator) throw new Error(`Artifact "${artifact.id}" uses tool "openapi-generator" but has no "generator" value`);
+		await mkdir(artifact.outputDir, { recursive: true });
+		await run("node", [
+			resolveBinPath("@openapitools/openapi-generator-cli", "openapi-generator-cli"),
+			"generate",
+			"-i",
+			specInputPath,
+			"-g",
+			artifact.generator,
+			"-o",
+			artifact.outputDir,
+			`--additional-properties=${buildAdditionalPropertiesArg(artifact)}`
+		], rootDir);
+		await this.patchers[artifact.lang]?.patch(ctx);
+	}
+};
+//#endregion
+//#region src/generators/openapi-typescript/openapi-typescript.generator.ts
+/**
+* Wraps `openapi-typescript`. Unlike `openapi-generator-cli`, it isn't invoked
+* once per artifact - it reads `redocly.yaml`'s `apis:` map (kept in sync with
+* the CLI config by `core/redocly/redocly-sync.ts`) and writes every contract's
+* `index.d.ts` to its configured `x-openapi-ts.output` path in a single run,
+* so that single global invocation happens once in {@link prepare}.
+* {@link generate} then only has to write each artifact's package.json` -
+* `openapi-typescript` emits `index.d.ts` alone, with no package manifest of
+* its own to patch.
+*/
+var OpenApiTypescriptGenerator = class extends Generator {
+	tool = "openapi-typescript";
+	async prepare({ rootDir, entries }) {
+		await Promise.all(entries.map((entry) => mkdir(entry.artifact.outputDir, { recursive: true })));
+		await run("node", [resolveBinPath("openapi-typescript", "openapi-typescript")], rootDir);
+	}
+	async generate({ contract, artifact, version, github }) {
+		const pkg = {
+			name: artifact.package,
+			version,
+			description: `Types-only OpenAPI contract for the ${contract.name} service.`,
+			types: "./index.d.ts",
+			files: ["index.d.ts"],
+			license: "MIT",
+			repository: {
+				type: "git",
+				url: `git+https://github.com/${github.owner}/${github.repo}.git`,
+				directory: `sdk/svc-${contract.name}/${artifact.id}`
+			},
+			publishConfig: {
+				registry: "https://npm.pkg.github.com",
+				access: "restricted"
+			}
+		};
+		await writeFile(path.join(artifact.outputDir, "package.json"), JSON.stringify(pkg, null, 2));
+	}
+};
+//#endregion
+//#region src/commands/generate-sdk.ts
+/**
+* Generates SDK packages for every artifact of every contract in the config.
+*
+* @param config - The resolved config.
+*/
+async function generateSdkCommand(config) {
+	await syncRedoclyConfig(config);
+	const registry = new GeneratorRegistry().register(new OpenApiGeneratorCli()).register(new OpenApiTypescriptGenerator());
+	await rm(config.paths.sdk, {
+		recursive: true,
+		force: true
+	});
+	await mkdir(config.paths.sdk, { recursive: true });
+	for (const tool of registry.tools()) {
+		const entries = config.allArtifacts.filter((entry) => entry.artifact.tool === tool);
+		await registry.resolve(tool).prepare?.({
+			rootDir: config.rootDir,
+			entries
+		});
+	}
+	const versionCache = /* @__PURE__ */ new Map();
+	async function getVersionInfo(contractName) {
+		const cached = versionCache.get(contractName);
+		if (cached) return cached;
+		const specPath = path.join(config.paths.specs, `${contractName}.json`);
+		const raw = await readFile(specPath, "utf8");
+		const info = {
+			version: resolveVersion(JSON.parse(raw), contractName),
+			hash: hashSpec(raw)
+		};
+		versionCache.set(contractName, info);
+		return info;
+	}
+	for (const { contract, artifact } of config.allArtifacts) {
+		const { version, hash } = await getVersionInfo(contract.name);
+		await registry.resolve(artifact.tool).generate({
+			rootDir: config.rootDir,
+			contract,
+			artifact,
+			version,
+			github: config.github,
+			specInputPath: path.join(config.paths.specs, `${contract.name}.json`)
+		});
+		await writeFile(path.join(artifact.outputDir, "VERSION"), `${version}\n`);
+		await writeFile(path.join(artifact.outputDir, "SPEC_HASH"), `${hash}\n`);
+		await writeFile(path.join(artifact.outputDir, "README.md"), await renderReadme({
+			contract,
+			artifact,
+			version,
+			github: config.github,
+			vars: config.vars
+		}));
+	}
+	const versionSummary = [...versionCache.entries()].map(([name, { version }]) => `${name}@${version}`).join(", ");
+	console.log(`Generated ${config.allArtifacts.length} SDK packages into ${config.paths.sdk} (${versionSummary})`);
+}
+//#endregion
+//#region src/commands/lint.ts
+/**
+* Lints every contract's OpenAPI spec.
+* Sets `process.exitCode = 1` if any contract fails.
+*
+* @param config - The resolved CLI config.
+*/
+async function lintCommand(config) {
+	await syncRedoclyConfig(config);
+	console.log("Linting OpenAPI contracts...");
+	const redoclyBin = resolveBinPath("@redocly/cli", "redocly");
+	let hasErrors = false;
+	for (const contract of config.contracts) {
+		console.log(`Checking [${contract.name}]...`);
+		if (runSync("node", [
+			redoclyBin,
+			"lint",
+			contract.entrypoint
+		], config.rootDir) !== 0) hasErrors = true;
+	}
+	if (hasErrors) process.exitCode = 1;
+}
+//#endregion
+//#region src/commands/publish-registries.ts
+/**
+* Publishes registry-backed packages:
+*   - TypeScript (client and server-types) -> npm (needs a configured registry
+*     or auth token on the machine running this).
+*   - Java (client and server) -> Maven (needs `~/.m2/settings.xml` credentials
+*     for whichever repository `mvn deploy` resolves to).
+*
+* Go packages are intentionally skipped - they're consumed straight from
+* their git branch/tag (see `publish-sdk.ts`), Go has no registry step.
+*
+* @param config  - The resolved CLI config.
+* @param options - `{ dryRun }` - print what would run without running it.
+*/
+async function publishRegistriesCommand(config, options = {}) {
+	const dryRun = options.dryRun ?? false;
+	function run(cmd, args, cwd) {
+		console.log(`$ ${cmd} ${args.join(" ")}  (in ${cwd})`);
+		if (dryRun) return;
+		const result = spawnSync(cmd, args, {
+			cwd,
+			stdio: "inherit",
+			shell: true
+		});
+		if (result.status !== 0) throw new Error(`${cmd} ${args.join(" ")} exited with ${result.status}`);
+	}
+	let publishedCount = 0;
+	for (const { contract, artifact } of config.allArtifacts) {
+		if (artifact.lang === "typescript") {
+			console.log(`\n=== npm publish: ${artifact.package} (contract: ${contract.name}, ${artifact.kind}) ===`);
+			run("npm", ["publish"], artifact.outputDir);
+			publishedCount += 1;
+		}
+		if (artifact.lang === "java") {
+			console.log(`\n=== maven deploy: ${artifact.maven?.groupId}:${artifact.maven?.artifactId} (contract: ${contract.name}, ${artifact.kind}) ===`);
+			run("mvn", [
+				"-B",
+				"deploy",
+				"-DskipTests"
+			], artifact.outputDir);
+			publishedCount += 1;
+		}
+	}
+	console.log(`\nDone - published ${publishedCount} registry package(s).`);
+}
+//#endregion
+//#region src/core/git/git.ts
+/**
+* Execute a git command in a given working directory and return the result.
+*
+* @param args - The command-line arguments to pass to the git command.
+* @param cwd  - The working directory in which to execute the git command.
+* @returns The result of the git command.
+*
+* @see {@link GitResult} - The result of executing the git command.
+*/
+function git(args, cwd) {
+	const result = spawnSync("git", args, {
+		cwd,
+		encoding: "utf8"
+	});
+	return {
+		status: result.status ?? 1,
+		stdout: (result.stdout ?? "").trim(),
+		stderr: (result.stderr ?? "").trim()
+	};
+}
+/**
+* Check if a remote branch exists in the given repository.
+*
+* @param repoRoot - The root directory of the repository.
+* @param branch   - The name of the branch to check.
+* @returns Whether the remote branch exists (true) or not (false).
+*/
+function remoteBranchExists(repoRoot, branch) {
+	return git([
+		"ls-remote",
+		"--exit-code",
+		"--heads",
+		"origin",
+		branch
+	], repoRoot).status === 0;
+}
+/**
+* Check if a remote tag exists in the given repository.
+*
+* @param repoRoot - The root directory of the repository.
+* @param tag      - The name of the tag to check.
+* @returns Whether the remote tag exists (true) or not (false).
+*/
+function tagExists(repoRoot, tag) {
+	return git([
+		"ls-remote",
+		"--exit-code",
+		"--tags",
+		"origin",
+		tag
+	], repoRoot).status === 0;
+}
+/**
+* Fetch a single tag's object from origin into the local repo, without
+* fetching the rest of history/tags.
+*
+* @param repoRoot - The root directory of the repository.
+* @param tag      - The name of the tag to fetch.
+* @returns The result of the underlying `git fetch` command.
+*/
+function fetchTag(repoRoot, tag) {
+	return git([
+		"fetch",
+		"origin",
+		`refs/tags/${tag}:refs/tags/${tag}`,
+		"--force"
+	], repoRoot);
+}
+/**
+* Read a single file's content as it existed at a given git tag, without
+* checking out a worktree.
+*
+* Returns `null` (rather than throwing) both when the tag can't be fetched and
+* when the tag exists but doesn't contain the requested file - the latter is
+* expected for tags published before that file was introduced, and callers
+* should treat "unknown" the same as "no mismatch to report".
+*
+* @param repoRoot - The root directory of the repository.
+* @param tag      - The tag to read the file from.
+* @param filePath - The path of the file within that tag's tree.
+* @returns The file's content, or `null` if it couldn't be read.
+*/
+function readFileAtTag(repoRoot, tag, filePath) {
+	if (fetchTag(repoRoot, tag).status !== 0) return null;
+	const show = git(["show", `${tag}:${filePath}`], repoRoot);
+	return show.status === 0 ? show.stdout.trim() : null;
+}
+/**
+* Require that a git command succeeded, throwing an error with the given
+* message if it did not.
+*
+* @param result  - The result of the git command to check.
+* @param message - The error message to throw if the command failed.
+* @throws Error if the git command failed (non-zero exit code).
+*/
+function requireOk(result, message) {
+	if (result.status !== 0) throw new Error(`${message}: ${result.stderr || result.stdout}`);
+}
+//#endregion
+//#region src/commands/publish-sdk.ts
+/**
+* Redistributes each generated artifact's `dist/sdk/<contract>/<artifact-id>`
+* into its own orphan branch (`sdk/svc-<contract>/<artifact-id>`) and tags the
+* publish.
+*
+* @param config  - The resolved CLI config.
+* @param options - `{ dryRun }` - skip pushing, just report what would happen.
+*/
+async function publishSdkCommand(config, options = {}) {
+	const dryRun = options.dryRun ?? false;
+	for (const { contract, artifact } of config.allArtifacts) {
+		const version = (await readFile(path.join(artifact.outputDir, "VERSION"), "utf8")).trim();
+		const localHash = (await readFile(path.join(artifact.outputDir, "SPEC_HASH"), "utf8")).trim();
+		const tag = `${artifact.tagPrefix}-v${version}`;
+		console.log(`\n=== ${contract.name} / ${artifact.id} -> ${artifact.branch} (v${version}) ===`);
+		if (tagExists(config.rootDir, tag)) {
+			const remoteHash = readFileAtTag(config.rootDir, tag, "SPEC_HASH");
+			if (remoteHash !== null && remoteHash !== localHash) throw new Error(`Tag ${tag} already exists, but the ${contract.name} spec content has changed since it was published under that version. Bump "info.version" in ${contract.entrypointRelative} before releasing again.`);
+			console.log(`Tag ${tag} already exists on origin with matching content, skipping (already published).`);
+			continue;
+		}
+		const worktreeDir = await mkdtemp(path.join(tmpdir(), "sdk-publish-"));
+		await rm(worktreeDir, {
+			recursive: true,
+			force: true
+		});
+		git([
+			"fetch",
+			"origin",
+			artifact.branch
+		], config.rootDir);
+		const hasRemoteBranch = remoteBranchExists(config.rootDir, artifact.branch);
+		requireOk(hasRemoteBranch ? git([
+			"worktree",
+			"add",
+			worktreeDir,
+			`origin/${artifact.branch}`
+		], config.rootDir) : git([
+			"worktree",
+			"add",
+			"--detach",
+			worktreeDir
+		], config.rootDir), `Failed to create worktree for ${artifact.branch}`);
+		if (hasRemoteBranch) requireOk(git([
+			"checkout",
+			"-B",
+			artifact.branch,
+			`origin/${artifact.branch}`
+		], worktreeDir), `Failed to check out ${artifact.branch}`);
+		else requireOk(git([
+			"checkout",
+			"--orphan",
+			artifact.branch
+		], worktreeDir), `Failed to create orphan branch ${artifact.branch}`);
+		git([
+			"rm",
+			"-rf",
+			"--quiet",
+			"."
+		], worktreeDir);
+		await cp(artifact.outputDir, worktreeDir, { recursive: true });
+		git(["add", "-A"], worktreeDir);
+		if (!(git([
+			"diff",
+			"--cached",
+			"--quiet"
+		], worktreeDir).status !== 0)) console.log("No content changes since last publish - committing tag only.");
+		else requireOk(git([
+			"commit",
+			"-m",
+			`chore(sdk): publish ${contract.name} ${artifact.id} v${version}`
+		], worktreeDir), `Commit failed for ${artifact.branch}`);
+		requireOk(git(["tag", tag], worktreeDir), `Tagging failed for ${tag}`);
+		if (dryRun) console.log(`[dry-run] would push ${artifact.branch} and tag ${tag}`);
+		else {
+			requireOk(git([
+				"push",
+				"origin",
+				`HEAD:refs/heads/${artifact.branch}`
+			], worktreeDir), `Push failed for ${artifact.branch}`);
+			requireOk(git([
+				"push",
+				"origin",
+				tag
+			], worktreeDir), `Tag push failed for ${tag}`);
+			console.log(`Published ${artifact.branch} @ ${tag}`);
+		}
+		git([
+			"worktree",
+			"remove",
+			"--force",
+			worktreeDir
+		], config.rootDir);
+	}
+	console.log(`\nDone - processed ${config.allArtifacts.length} SDK packages.`);
+}
+//#endregion
+//#region src/commands/serve-docs.ts
+const MIME_TYPES = {
+	".html": "text/html; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".ico": "image/x-icon"
+};
+/**
+* Serves the generated documentation site (`dist/docs`) over plain HTTP for
+* local previewing.
+*
+* @param config - The resolved CLI config.
+*/
+async function serveDocsCommand(config) {
+	const { host, port } = config.docs.server;
+	const server = createServer((request, response) => {
+		if (!request.url) {
+			response.writeHead(400);
+			response.end();
+			return;
+		}
+		const url = new URL(request.url, `http://${host}:${port}`);
+		const pathname = decodeURIComponent(url.pathname);
+		const relativePath = normalize(pathname).replace(/^(\.\.[/\\])+/, "");
+		let file = join(config.paths.docs, relativePath);
+		try {
+			if (statSync(file).isDirectory()) file = join(file, "index.html");
+		} catch {
+			response.writeHead(404);
+			response.end("Not Found");
+			return;
+		}
+		try {
+			if (!statSync(file).isFile()) {
+				response.writeHead(404);
+				response.end("Not Found");
+				return;
+			}
+			response.writeHead(200, { "Content-Type": MIME_TYPES[extname(file)] ?? "application/octet-stream" });
+			createReadStream(file).pipe(response);
+		} catch {
+			response.writeHead(404);
+			response.end("Not Found");
+		}
+	});
+	await new Promise((resolvePromise) => {
+		server.listen(port, host, () => {
+			console.log(`Scalar documentation: http://${host}:${port}`);
+			resolvePromise();
+		});
+	});
+}
+//#endregion
+export { resolveConfigPath as _, generateSdkCommand as a, Generator as c, cleanCommand as d, bundleCommand as f, CONFIG_FILENAMES as g, runSync as h, lintCommand as i, GeneratorRegistry as l, run as m, publishSdkCommand as n, OpenApiTypescriptGenerator as o, resolveBinPath as p, publishRegistriesCommand as r, OpenApiGeneratorCli as s, serveDocsCommand as t, generateDocsCommand as u, loadConfig as v };
+
+//# sourceMappingURL=serve-docs-BZaITOD0.mjs.map