@octalmesh/seagull-cli 0.0.2

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OctalMesh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @octalmesh/seagull-cli
+
+**Internal package** - not published to npm on its own. This holds every
+pipeline command (`lint`, `bundle`, `generate`, `docs generate`, `docs serve`,
+`publish sdk`, `publish registries`, `clean`) and the `commander` program
+that wires them up (`createProgram()`), bundled straight into
+[`@octalmesh/seagull`](../..) at build time - that package owns the actual
+`seagull` executable and reads its own `package.json` for `--version`/
+`--help` text, then calls `createProgram()` from here to build the rest.
+
+See the [main README](https://github.com/OctalMesh/Seagull#readme) for the
+command reference and full config docs.
+
+## What lives here
+
+- `commands/` - one function per pipeline step, each taking a
+  `ResolvedConfig` (from [`@octalmesh/seagull-core`](../core)) and returning
+  `Promise<void>`.
+- `program.ts` - `createProgram(metadata)`, a pure factory building the
+  `commander` `Command` tree. No side effects, no `process.argv` parsing -
+  the actual entrypoint (`@octalmesh/seagull`'s `src/cli.ts`) owns that.
+
+`commands/generate-docs.ts` and `commands/serve-docs.ts` are thin
+delegations to [`@octalmesh/seagull-docs`](../docs) - the actual docs-site
+implementation lives there.
+
+## License
+
+MIT

package/dist/index.mjs

@@ -0,0 +1,354 @@
+import path from "node:path";
+import { GeneratorRegistry, OpenApiGeneratorCli, OpenApiTypescriptGenerator, git, hashSpec, loadConfig, readFileAtTag, remoteBranchExists, renderArtifactTag, renderReadme, requireOk, resolveBinPath, resolveConfigPath, resolveVersion, run, runSync, syncRedoclyConfig, tagExists } from "@octalmesh/seagull-core";
+import { Command } from "commander";
+import { cp, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { generateDocsSite, serveDocsSite } from "@octalmesh/seagull-docs";
+import { tmpdir } from "node:os";
+//#region src/commands/bundle.ts
+/**
+* Bundles every contract's OpenAPI spec into `dist/specs/<contract>.json`.
+*
+* @param config - The resolved seagull 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 seagull 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`.
+* Delegates to `@octalmesh/seagull-docs` - see that package for the actual
+* implementation.
+*
+* @param config - The resolved seagull config.
+*/
+async function generateDocsCommand(config) {
+	await generateDocsSite(config);
+}
+//#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 spec = JSON.parse(raw);
+		const info = {
+			version: resolveVersion(spec, 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 seagull 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;
+	async function runCommand(cmd, args, cwd) {
+		console.log(`$ ${cmd} ${args.join(" ")}  (in ${cwd})`);
+		if (dryRun) return;
+		await run(cmd, args, cwd);
+	}
+	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}) ===`);
+			await runCommand("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}) ===`);
+			await runCommand("mvn", [
+				"-B",
+				"deploy",
+				"-DskipTests"
+			], artifact.outputDir);
+			publishedCount += 1;
+		}
+	}
+	console.log(`\nDone - published ${publishedCount} registry package(s).`);
+}
+//#endregion
+//#region src/commands/publish-sdk.ts
+/**
+* Redistributes each generated artifact's `dist/sdk/<contract>/<artifact-id>`
+* into its own orphan branch (per the artifact's resolved `publishing.branch`)
+* 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 = renderArtifactTag(artifact, contract.name, version, config.github, config.vars);
+		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);
+		const setup = hasRemoteBranch ? git([
+			"worktree",
+			"add",
+			worktreeDir,
+			`origin/${artifact.branch}`
+		], config.rootDir) : git([
+			"worktree",
+			"add",
+			"--detach",
+			worktreeDir
+		], config.rootDir);
+		requireOk(setup, `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
+/**
+* Serves the generated documentation site (`dist/docs`) over plain HTTP for
+* local previewing. Delegates to `@octalmesh/seagull-docs`.
+*
+* @param config - The resolved seagull config.
+*/
+async function serveDocsCommand(config) {
+	await serveDocsSite(config);
+}
+//#endregion
+//#region src/program.ts
+/**
+* Builds the seagull commander program - every subcommand, wired up to the
+* pipeline command functions. Pure and side-effect-free (doesn't parse
+* `process.argv` or read any file itself) so it's usable both by the real
+* CLI entrypoint and by anything that wants to drive it programmatically or
+* test it.
+*
+* @param metadata - `{ name, version, description }` shown in `--help`/`--version`
+*                   - the caller's own `package.json` fields, since this
+*                   package doesn't read its own (it's bundled into
+*                   `@octalmesh/seagull`, whose metadata is what should show).
+* @returns The configured commander `Command`, ready for `.parseAsync()`.
+*/
+function createProgram(metadata) {
+	const program = new Command();
+	program.name(metadata.name).description(metadata.description).version(metadata.version).option("-c, --config <path>", "path to the seagull config file (default: auto-detected in the current directory)");
+	/** Resolves and loads the config, using `--config` if given, else
+	* auto-discovering it in the current directory. */
+	function resolveConfig() {
+		const { config: configOption } = program.opts();
+		const configPath = configOption ? path.resolve(process.cwd(), configOption) : resolveConfigPath(process.cwd());
+		return loadConfig(configPath);
+	}
+	program.command("lint").description("Lint every contract's OpenAPI spec with Redocly.").action(withErrorHandling(async () => lintCommand(resolveConfig())));
+	program.command("bundle").description("Bundle every contract's OpenAPI spec into dist/specs.").action(withErrorHandling(async () => bundleCommand(resolveConfig())));
+	program.command("generate").description("Generate every configured SDK artifact into dist/sdk.").action(withErrorHandling(async () => generateSdkCommand(resolveConfig())));
+	program.command("clean").description("Remove the dist output directory.").action(withErrorHandling(async () => cleanCommand(resolveConfig())));
+	const docs = program.command("docs").description("Documentation site commands.");
+	docs.command("generate").description("Generate the documentation site into dist/docs.").action(withErrorHandling(async () => generateDocsCommand(resolveConfig())));
+	docs.command("serve").description("Serve the generated documentation site locally.").action(withErrorHandling(async () => serveDocsCommand(resolveConfig())));
+	const publish = program.command("publish").description("Publishing commands.");
+	publish.command("sdk").description("Publish generated SDKs to their per-artifact git branches/tags.").option("--dry-run", "print what would be pushed without pushing").action(withErrorHandling(async (opts) => {
+		await publishSdkCommand(resolveConfig(), { dryRun: opts.dryRun });
+	}));
+	publish.command("registries").description("Publish registry-backed packages (npm publish / mvn deploy).").option("--dry-run", "print what would be published without publishing").action(withErrorHandling(async (opts) => {
+		await publishRegistriesCommand(resolveConfig(), { dryRun: opts.dryRun });
+	}));
+	return program;
+}
+/**
+* Wraps a commander action so a thrown Error prints as `seagull: <message>`
+* and exits non-zero, instead of an unhandled-rejection stack trace.
+*
+* @param fn - The action function to wrap.
+* @returns A wrapped action function that handles errors.
+*/
+function withErrorHandling(fn) {
+	return async (...args) => {
+		try {
+			await fn(...args);
+		} catch (error) {
+			console.error(`seagull: ${error instanceof Error ? error.message : String(error)}`);
+			process.exitCode = 1;
+		}
+	};
+}
+//#endregion
+export { bundleCommand, cleanCommand, createProgram, generateDocsCommand, generateSdkCommand, lintCommand, publishRegistriesCommand, publishSdkCommand, serveDocsCommand };
+
+//# sourceMappingURL=index.mjs.map

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@octalmesh/seagull-cli",
+  "version": "0.0.2",
+  "description": "Seagull's pipeline commands and commander program - bundled into @octalmesh/seagull.",
+  "author": "OctalMesh <contact@octalmesh.com> (https://octalmesh.com)",
+  "license": "MIT",
+  "homepage": "https://github.com/OctalMesh/Seagull/tree/main/packages/cli",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OctalMesh/Seagull.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/OctalMesh/Seagull/issues",
+    "email": "security@octalmesh.com"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.22.0"
+  },
+  "dependencies": {
+    "@octalmesh/seagull-core": "0.0.2",
+    "@octalmesh/seagull-docs": "0.0.2",
+    "commander": "^15.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/commands/bundle.ts

@@ -0,0 +1,37 @@
+import { mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  type ResolvedConfig,
+  resolveBinPath,
+  run,
+  syncRedoclyConfig,
+} from "@octalmesh/seagull-core";
+
+/**
+ * Bundles every contract's OpenAPI spec into `dist/specs/<contract>.json`.
+ *
+ * @param config - The resolved seagull config.
+ */
+export async function bundleCommand(config: ResolvedConfig): Promise<void> {
+  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}`,
+  );
+}

package/src/commands/clean.ts

@@ -0,0 +1,14 @@
+import { rm } from "node:fs/promises";
+
+import type { ResolvedConfig } from "@octalmesh/seagull-core";
+
+/**
+ * Removes the entire `dist` output directory.
+ *
+ * @param config - The resolved seagull config.
+ */
+export async function cleanCommand(config: ResolvedConfig): Promise<void> {
+  await rm(config.paths.dist, { recursive: true, force: true });
+
+  console.log(`Cleaned ${config.paths.dist}`);
+}

package/src/commands/generate-docs.ts

@@ -0,0 +1,15 @@
+import type { ResolvedConfig } from "@octalmesh/seagull-core";
+import { generateDocsSite } from "@octalmesh/seagull-docs";
+
+/**
+ * Generates the documentation website for every contract into `dist/docs`.
+ * Delegates to `@octalmesh/seagull-docs` - see that package for the actual
+ * implementation.
+ *
+ * @param config - The resolved seagull config.
+ */
+export async function generateDocsCommand(
+  config: ResolvedConfig,
+): Promise<void> {
+  await generateDocsSite(config);
+}

package/src/commands/generate-sdk.ts

@@ -0,0 +1,107 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  type BundledSpec,
+  GeneratorRegistry,
+  OpenApiGeneratorCli,
+  OpenApiTypescriptGenerator,
+  type ResolvedConfig,
+  hashSpec,
+  renderReadme,
+  resolveVersion,
+  syncRedoclyConfig,
+} from "@octalmesh/seagull-core";
+
+interface VersionInfo {
+  version: string;
+  hash: string;
+}
+
+/**
+ * Generates SDK packages for every artifact of every contract in the config.
+ *
+ * @param config - The resolved config.
+ */
+export async function generateSdkCommand(
+  config: ResolvedConfig,
+): Promise<void> {
+  // openapi-typescript reads 'redocly.yaml' directly, so it needs to be in sync
+  // with the seagull config before that generator's 'prepare()' runs
+  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 = new Map<string, VersionInfo>();
+
+  async function getVersionInfo(contractName: string): Promise<VersionInfo> {
+    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 spec = JSON.parse(raw) as BundledSpec;
+
+    const info: VersionInfo = {
+      version: resolveVersion(spec, contractName),
+      hash: hashSpec(raw),
+    };
+
+    versionCache.set(contractName, info);
+
+    return info;
+  }
+
+  for (const { contract, artifact } of config.allArtifacts) {
+    const { version, hash } = await getVersionInfo(contract.name);
+    const generator = registry.resolve(artifact.tool);
+
+    await generator.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})`,
+  );
+}

package/src/commands/lint.ts

@@ -0,0 +1,41 @@
+import {
+  type ResolvedConfig,
+  resolveBinPath,
+  runSync,
+  syncRedoclyConfig,
+} from "@octalmesh/seagull-core";
+
+/**
+ * Lints every contract's OpenAPI spec.
+ * Sets `process.exitCode = 1` if any contract fails.
+ *
+ * @param config - The resolved seagull config.
+ */
+export async function lintCommand(config: ResolvedConfig): Promise<void> {
+  // redocly reads 'redocly.yaml' directly, so it needs to be in sync with the
+  // seagull config before linting
+  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}]...`);
+
+    const status = runSync(
+      "node",
+      [redoclyBin, "lint", contract.entrypoint],
+      config.rootDir,
+    );
+
+    if (status !== 0) {
+      hasErrors = true;
+    }
+  }
+
+  if (hasErrors) {
+    process.exitCode = 1;
+  }
+}

package/src/commands/publish-registries.ts

@@ -0,0 +1,70 @@
+import {
+  type ResolvedConfig,
+  run as runProcess,
+} from "@octalmesh/seagull-core";
+
+export interface PublishRegistriesOptions {
+  dryRun?: boolean;
+}
+
+/**
+ * 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.
+ */
+export async function publishRegistriesCommand(
+  config: ResolvedConfig,
+  options: PublishRegistriesOptions = {},
+): Promise<void> {
+  const dryRun = options.dryRun ?? false;
+
+  async function runCommand(
+    cmd: string,
+    args: string[],
+    cwd: string,
+  ): Promise<void> {
+    console.log(`$ ${cmd} ${args.join(" ")}  (in ${cwd})`);
+
+    if (dryRun) {
+      return;
+    }
+
+    await runProcess(cmd, args, cwd);
+  }
+
+  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}) ===`,
+      );
+      await runCommand("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}) ===`,
+      );
+      await runCommand(
+        "mvn",
+        ["-B", "deploy", "-DskipTests"],
+        artifact.outputDir,
+      );
+
+      publishedCount += 1;
+    }
+  }
+
+  console.log(`\nDone - published ${publishedCount} registry package(s).`);
+}

package/src/commands/publish-sdk.ts

@@ -0,0 +1,148 @@
+import { cp, mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import {
+  type ResolvedConfig,
+  git,
+  readFileAtTag,
+  remoteBranchExists,
+  renderArtifactTag,
+  requireOk,
+  tagExists,
+} from "@octalmesh/seagull-core";
+
+export interface PublishSdkOptions {
+  dryRun?: boolean;
+}
+
+/**
+ * Redistributes each generated artifact's `dist/sdk/<contract>/<artifact-id>`
+ * into its own orphan branch (per the artifact's resolved `publishing.branch`)
+ * and tags the
+ * publish.
+ *
+ * @param config  - The resolved CLI config.
+ * @param options - `{ dryRun }` - skip pushing, just report what would happen.
+ */
+export async function publishSdkCommand(
+  config: ResolvedConfig,
+  options: PublishSdkOptions = {},
+): Promise<void> {
+  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 = renderArtifactTag(
+      artifact,
+      contract.name,
+      version,
+      config.github,
+      config.vars,
+    );
+
+    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);
+
+    const setup = hasRemoteBranch
+      ? git(
+          ["worktree", "add", worktreeDir, `origin/${artifact.branch}`],
+          config.rootDir,
+        )
+      : git(["worktree", "add", "--detach", worktreeDir], config.rootDir);
+    requireOk(setup, `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);
+    const hasChanges =
+      git(["diff", "--cached", "--quiet"], worktreeDir).status !== 0;
+
+    if (!hasChanges) {
+      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.`);
+}

package/src/commands/serve-docs.ts

@@ -0,0 +1,12 @@
+import type { ResolvedConfig } from "@octalmesh/seagull-core";
+import { serveDocsSite } from "@octalmesh/seagull-docs";
+
+/**
+ * Serves the generated documentation site (`dist/docs`) over plain HTTP for
+ * local previewing. Delegates to `@octalmesh/seagull-docs`.
+ *
+ * @param config - The resolved seagull config.
+ */
+export async function serveDocsCommand(config: ResolvedConfig): Promise<void> {
+  await serveDocsSite(config);
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+export { createProgram } from "./program";
+export type { ProgramMetadata } from "./program";
+
+export { bundleCommand } from "./commands/bundle";
+export { cleanCommand } from "./commands/clean";
+export { generateDocsCommand } from "./commands/generate-docs";
+export { generateSdkCommand } from "./commands/generate-sdk";
+export { lintCommand } from "./commands/lint";
+export type { PublishRegistriesOptions } from "./commands/publish-registries";
+export { publishRegistriesCommand } from "./commands/publish-registries";
+export type { PublishSdkOptions } from "./commands/publish-sdk";
+export { publishSdkCommand } from "./commands/publish-sdk";
+export { serveDocsCommand } from "./commands/serve-docs";

package/src/program.ts

@@ -0,0 +1,154 @@
+import path from "node:path";
+
+import {
+  type ResolvedConfig,
+  loadConfig,
+  resolveConfigPath,
+} from "@octalmesh/seagull-core";
+import { Command } from "commander";
+
+import { bundleCommand } from "./commands/bundle";
+import { cleanCommand } from "./commands/clean";
+import { generateDocsCommand } from "./commands/generate-docs";
+import { generateSdkCommand } from "./commands/generate-sdk";
+import { lintCommand } from "./commands/lint";
+import { publishRegistriesCommand } from "./commands/publish-registries";
+import { publishSdkCommand } from "./commands/publish-sdk";
+import { serveDocsCommand } from "./commands/serve-docs";
+
+export interface ProgramMetadata {
+  name: string;
+  version: string;
+  description: string;
+}
+
+interface DryRunOptions {
+  dryRun?: boolean;
+}
+
+/**
+ * Builds the seagull commander program - every subcommand, wired up to the
+ * pipeline command functions. Pure and side-effect-free (doesn't parse
+ * `process.argv` or read any file itself) so it's usable both by the real
+ * CLI entrypoint and by anything that wants to drive it programmatically or
+ * test it.
+ *
+ * @param metadata - `{ name, version, description }` shown in `--help`/`--version`
+ *                   - the caller's own `package.json` fields, since this
+ *                   package doesn't read its own (it's bundled into
+ *                   `@octalmesh/seagull`, whose metadata is what should show).
+ * @returns The configured commander `Command`, ready for `.parseAsync()`.
+ */
+export function createProgram(metadata: ProgramMetadata): Command {
+  const program = new Command();
+
+  program
+    .name(metadata.name)
+    .description(metadata.description)
+    .version(metadata.version)
+    .option(
+      "-c, --config <path>",
+      "path to the seagull config file (default: auto-detected in the current directory)",
+    );
+
+  /**
+   * Resolves and loads the config, using `--config` if given, else
+   * auto-discovering it in the current directory.
+   */
+  function resolveConfig(): ResolvedConfig {
+    const { config: configOption } = program.opts<{ config?: string }>();
+    const configPath = configOption
+      ? path.resolve(process.cwd(), configOption)
+      : resolveConfigPath(process.cwd());
+
+    return loadConfig(configPath);
+  }
+
+  program
+    .command("lint")
+    .description("Lint every contract's OpenAPI spec with Redocly.")
+    .action(withErrorHandling(async () => lintCommand(resolveConfig())));
+
+  program
+    .command("bundle")
+    .description("Bundle every contract's OpenAPI spec into dist/specs.")
+    .action(withErrorHandling(async () => bundleCommand(resolveConfig())));
+
+  program
+    .command("generate")
+    .description("Generate every configured SDK artifact into dist/sdk.")
+    .action(withErrorHandling(async () => generateSdkCommand(resolveConfig())));
+
+  program
+    .command("clean")
+    .description("Remove the dist output directory.")
+    .action(withErrorHandling(async () => cleanCommand(resolveConfig())));
+
+  const docs = program
+    .command("docs")
+    .description("Documentation site commands.");
+
+  docs
+    .command("generate")
+    .description("Generate the documentation site into dist/docs.")
+    .action(
+      withErrorHandling(async () => generateDocsCommand(resolveConfig())),
+    );
+
+  docs
+    .command("serve")
+    .description("Serve the generated documentation site locally.")
+    .action(withErrorHandling(async () => serveDocsCommand(resolveConfig())));
+
+  const publish = program
+    .command("publish")
+    .description("Publishing commands.");
+
+  publish
+    .command("sdk")
+    .description(
+      "Publish generated SDKs to their per-artifact git branches/tags.",
+    )
+    .option("--dry-run", "print what would be pushed without pushing")
+    .action(
+      withErrorHandling(async (opts: DryRunOptions) => {
+        await publishSdkCommand(resolveConfig(), { dryRun: opts.dryRun });
+      }),
+    );
+
+  publish
+    .command("registries")
+    .description("Publish registry-backed packages (npm publish / mvn deploy).")
+    .option("--dry-run", "print what would be published without publishing")
+    .action(
+      withErrorHandling(async (opts: DryRunOptions) => {
+        await publishRegistriesCommand(resolveConfig(), {
+          dryRun: opts.dryRun,
+        });
+      }),
+    );
+
+  return program;
+}
+
+/**
+ * Wraps a commander action so a thrown Error prints as `seagull: <message>`
+ * and exits non-zero, instead of an unhandled-rejection stack trace.
+ *
+ * @param fn - The action function to wrap.
+ * @returns A wrapped action function that handles errors.
+ */
+function withErrorHandling<Args extends unknown[]>(
+  fn: (...args: Args) => Promise<void>,
+): (...args: Args) => Promise<void> {
+  return async (...args: Args) => {
+    try {
+      await fn(...args);
+    } catch (error) {
+      console.error(
+        `seagull: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      process.exitCode = 1;
+    }
+  };
+}

package/tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+
+  "compilerOptions": {
+    /* Environment */
+    "target": "es2024",
+    "lib": ["esnext"],
+    "types": ["node"],
+    "allowJs": false,
+
+    /* Modules */
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "moduleDetection": "force",
+    "allowImportingTsExtensions": false,
+    "erasableSyntaxOnly": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "noEmit": true,
+
+    /* Strict Type Checking */
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noUncheckedIndexedAccess": true
+  },
+
+  "include": ["src/**/*.ts", "*.config.ts"]
+}

package/tsdown.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from "tsdown";
+
+/**
+ * Tsdown configuration
+ *
+ * @see {@link https://tsdown.dev Tsdown documentation}
+ */
+// noinspection JSUnusedGlobalSymbols
+export default defineConfig({
+  entry: {
+    index: "src/index.ts",
+  },
+  platform: "node",
+  format: ["esm"],
+  target: "node22",
+  dts: {
+    entry: "src/index.ts",
+  },
+  clean: true,
+  sourcemap: true,
+});