@octalmesh/seagull 0.0.1

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,180 @@
+# seagull
+
+Contract-first OpenAPI SDK, docs, and publishing pipeline - driven by a
+single config file. Point it at your `openapi.yaml` files, tell it which SDK
+artifacts you want (TypeScript client, Go server stubs, Java client, ...),
+and it lints, bundles, generates, documents, and publishes them.
+
+Built to manage **several services' contracts from one place** - each
+service just needs an entry in the config; each artifact is generated by a
+reusable, shareable "recipe".
+
+## Install
+
+```bash
+npm install -D @octalmesh/seagull
+# or
+pnpm add -D @octalmesh/seagull
+```
+
+Under the hood, `generate` shells out to
+[`@openapitools/openapi-generator-cli`](https://www.npmjs.com/package/@openapitools/openapi-generator-cli)
+(needs a JVM on `PATH`) and
+[`openapi-typescript`](https://www.npmjs.com/package/openapi-typescript);
+`lint`/`bundle` use [`@redocly/cli`](https://www.npmjs.com/package/@redocly/cli);
+`docs` uses [`@scalar/api-reference`](https://www.npmjs.com/package/@scalar/api-reference).
+All four are seagull's own dependencies - nothing extra to install.
+
+## Quick start
+
+Create a config file at the root of your contracts repo - any of
+`.seagull`, `.seagull.yaml`, `.seagull.yml`, `seagull.yaml`, `seagull.yml`:
+
+```yaml
+# seagull.yaml
+github:
+  owner: your-org
+  repo: your-contracts-repo
+
+vars:
+  org: your-org
+
+docs:
+  server:
+    host: localhost
+    port: 8080
+  metadata:
+    title: "API Reference"
+    description: "..."
+    favicon: https://your-domain.com/favicon.ico
+    baseServerUrl: https://api.your-domain.com
+
+generators:
+  ts-client:
+    tool: openapi-generator
+    generator: typescript-fetch
+    lang: typescript
+    kind: client
+    package: "@{vars.org}/{service}-client"
+    additionalProperties:
+      supportsES6: true
+
+contracts:
+  - name: auth
+    title: Auth Service API
+    entrypoint: specs/auth/openapi.yaml
+    artifacts: [ts-client]
+```
+
+Then:
+
+```bash
+npx seagull lint
+npx seagull bundle
+npx seagull generate
+npx seagull docs generate && npx seagull docs serve
+```
+
+## Configuration
+
+Everything lives in the one config file:
+
+- **`generators:`** - reusable recipes: a `tool` (`openapi-generator` or
+  `openapi-typescript`), which `-g` template to use, and naming templates
+  for the npm package / Go module / Maven coordinates. Any string field may
+  reference `{vars.some.nested.key}`, `{github.owner}`, `{github.repo}`, or
+  `{service}` (the current contract's `name`).
+- **`contracts:`** - one entry per service (`name`, `title`, `entrypoint`,
+  and which `generators:` it wants under `artifacts:`, by id). Two services
+  don't need the same generators - a contract can reference a generator with
+  a per-contract override instead of duplicating the whole recipe:
+
+  ```yaml
+  contracts:
+    - name: payment
+      artifacts:
+        - generator: java-client
+          as: java-client-legacy # renames this artifact's output folder/branch/tag
+          overrides:
+            generator: java-legacy-template
+            additionalProperties: { library: jersey2 }
+  ```
+
+- **`vars:`** - a free-form tree for anything used in naming templates.
+  Nest however deep is useful; every leaf is addressable as `{vars.a.b.c}`.
+- **`paths:`** - only `dist:` is required; `specs`/`docs`/`sdk` default to
+  `<dist>/specs`, `<dist>/docs`, `<dist>/sdk` and only need to be set to
+  override that.
+- **`docs:`** - `server: { host, port }` for `docs serve`, and
+  `metadata: { title, description, favicon, baseServerUrl }` for the
+  generated Scalar site.
+
+A typo or missing field fails immediately with a readable, path-annotated
+error - config is validated with [zod](https://zod.dev) on every run.
+
+### Custom README templates
+
+Every generated artifact gets a `README.md` - by default a sensible
+built-in template for its language/kind. To use your own, point `readme:`
+at a template file (path relative to the config file):
+
+```yaml
+generators:
+  ts-client:
+    # ...
+    readme: readme-templates/ts-client.md
+```
+
+Template files support the same `{...}` placeholders as naming templates,
+plus a few more:
+
+| Placeholder                                                | Value                                            |
+|------------------------------------------------------------|--------------------------------------------------|
+| `{service}`                                                | The contract's `name`                            |
+| `{title}`                                                  | The contract's `title`                           |
+| `{version}`                                                | The resolved SDK version                         |
+| `{vars.*}`                                                 | Anything under `vars:`                           |
+| `{github.owner}` / `{github.repo}`                         | From `github:`                                   |
+| `{artifact.id}`                                            | The artifact's id (as listed under `artifacts:`) |
+| `{artifact.package}`                                       | Resolved npm package name (TypeScript)           |
+| `{artifact.goModule}` / `{artifact.goPackageName}`         | Resolved Go naming                               |
+| `{artifact.maven.groupId}` / `{artifact.maven.artifactId}` | Resolved Maven coordinates                       |
+| `{artifact.branch}` / `{artifact.tagPrefix}`               | Publishing branch/tag prefix                     |
+
+An unresolvable placeholder fails the build loudly (a typo'd
+`{vesion}` won't silently ship as literal text).
+
+## Commands
+
+```
+seagull lint                     Lint every contract with Redocly
+seagull bundle                   Bundle every contract's spec into dist/specs
+seagull generate                 Generate every configured SDK artifact into dist/sdk
+seagull clean                    Remove the dist directory
+seagull docs generate            Generate the Scalar documentation site into dist/docs
+seagull docs serve               Serve the generated documentation site locally
+seagull publish sdk [--dry-run]  Publish generated SDKs to their git branches/tags
+seagull publish registries [--dry-run]
+                                  npm publish / mvn deploy the registry-backed artifacts
+```
+
+Every command accepts `-c, --config <path>` to point at a config file
+outside the current directory.
+
+## Programmatic API
+
+```ts
+import { loadConfig, generateSdkCommand } from "@octalmesh/seagull";
+
+const config = loadConfig("/path/to/seagull.yaml");
+await generateSdkCommand(config);
+```
+
+`loadConfig`, every `*Command` function, the `Generator`/`GeneratorRegistry`
+primitives, and the built-in `OpenApiGeneratorCli`/`OpenApiTypescriptGenerator`
+generators are all exported, for anyone who wants to script against seagull
+directly or register a custom `Generator` for another tool.
+
+## License
+
+MIT

package/dist/cli.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+import { _ as resolveConfigPath, a as generateSdkCommand, d as cleanCommand, f as bundleCommand, i as lintCommand, n as publishSdkCommand, r as publishRegistriesCommand, t as serveDocsCommand, u as generateDocsCommand, v as loadConfig } from "./serve-docs-BZaITOD0.mjs";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+//#region src/cli.ts
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(path.join(__dirname, "..", "package.json"), "utf8"));
+const program = new Command();
+program.name("seagull").description(pkg.description).version(pkg.version).option("-c, --config <path>", "path to the CLI config file (default: auto-detected in the current directory)");
+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 Scalar 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 });
+}));
+await program.parseAsync();
+/**
+* Resolves and loads the config, using `--config` if given, else
+* auto-discovering it in the current directory.
+*
+* @returns The resolved config.
+*/
+function resolveConfig() {
+	const { config: configOption } = program.opts();
+	const configPath = configOption ? path.resolve(process.cwd(), configOption) : resolveConfigPath(process.cwd());
+	return loadConfig(configPath);
+}
+/**
+* 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 : error}`);
+			process.exitCode = 1;
+		}
+	};
+}
+//#endregion
+export {};
+
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["import { readFileSync } from \"node:fs\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\n\nimport { Command } from \"commander\";\n\nimport { loadConfig } from \"@config/loader\";\nimport { resolveConfigPath } from \"@config/resolve-config-file\";\nimport type { ResolvedConfig } from \"@config/types\";\n\nimport { bundleCommand } from \"@commands/bundle\";\nimport { cleanCommand } from \"@commands/clean\";\nimport { generateDocsCommand } from \"@commands/generate-docs\";\nimport { generateSdkCommand } from \"@commands/generate-sdk\";\nimport { lintCommand } from \"@commands/lint\";\nimport { publishRegistriesCommand } from \"@commands/publish-registries\";\nimport { publishSdkCommand } from \"@commands/publish-sdk\";\nimport { serveDocsCommand } from \"@commands/serve-docs\";\n\nconst __dirname = path.dirname(fileURLToPath(import.meta.url));\nconst pkg = JSON.parse(\n  readFileSync(path.join(__dirname, \"..\", \"package.json\"), \"utf8\"),\n) as { version: string; description: string };\nconst program = new Command();\n\n//<editor-fold desc=\"Commands\" defaultstate=\"collapsed\">\n\nprogram\n  .name(\"seagull\")\n  .description(pkg.description)\n  .version(pkg.version)\n  .option(\n    \"-c, --config <path>\",\n    \"path to the CLI config file (default: auto-detected in the current directory)\",\n  );\n\nprogram\n  .command(\"lint\")\n  .description(\"Lint every contract's OpenAPI spec with Redocly.\")\n  .action(withErrorHandling(async () => lintCommand(resolveConfig())));\n\nprogram\n  .command(\"bundle\")\n  .description(\"Bundle every contract's OpenAPI spec into dist/specs.\")\n  .action(withErrorHandling(async () => bundleCommand(resolveConfig())));\n\nprogram\n  .command(\"generate\")\n  .description(\"Generate every configured SDK artifact into dist/sdk.\")\n  .action(withErrorHandling(async () => generateSdkCommand(resolveConfig())));\n\nprogram\n  .command(\"clean\")\n  .description(\"Remove the dist output directory.\")\n  .action(withErrorHandling(async () => cleanCommand(resolveConfig())));\n\nconst docs = program\n  .command(\"docs\")\n  .description(\"Documentation site commands.\");\n\ndocs\n  .command(\"generate\")\n  .description(\"Generate the Scalar documentation site into dist/docs.\")\n  .action(withErrorHandling(async () => generateDocsCommand(resolveConfig())));\n\ndocs\n  .command(\"serve\")\n  .description(\"Serve the generated documentation site locally.\")\n  .action(withErrorHandling(async () => serveDocsCommand(resolveConfig())));\n\nconst publish = program.command(\"publish\").description(\"Publishing commands.\");\n\npublish\n  .command(\"sdk\")\n  .description(\n    \"Publish generated SDKs to their per-artifact git branches/tags.\",\n  )\n  .option(\"--dry-run\", \"print what would be pushed without pushing\")\n  .action(\n    withErrorHandling(async (opts: DryRunOptions) => {\n      await publishSdkCommand(resolveConfig(), { dryRun: opts.dryRun });\n    }),\n  );\n\npublish\n  .command(\"registries\")\n  .description(\"Publish registry-backed packages (npm publish / mvn deploy).\")\n  .option(\"--dry-run\", \"print what would be published without publishing\")\n  .action(\n    withErrorHandling(async (opts: DryRunOptions) => {\n      await publishRegistriesCommand(resolveConfig(), { dryRun: opts.dryRun });\n    }),\n  );\n\n//</editor-fold>\n\nawait program.parseAsync();\n\ninterface DryRunOptions {\n  dryRun?: boolean;\n}\n\n/**\n * Resolves and loads the config, using `--config` if given, else\n * auto-discovering it in the current directory.\n *\n * @returns The resolved config.\n */\nfunction resolveConfig(): ResolvedConfig {\n  const { config: configOption } = program.opts<{ config?: string }>();\n  const configPath = configOption\n    ? path.resolve(process.cwd(), configOption)\n    : resolveConfigPath(process.cwd());\n\n  return loadConfig(configPath);\n}\n\n/**\n * Wraps a commander action so a thrown Error prints as `seagull: <message>`\n * and exits non-zero, instead of an unhandled-rejection stack trace.\n *\n * @param fn The action function to wrap.\n * @returns A wrapped action function that handles errors.\n */\nfunction withErrorHandling<Args extends unknown[]>(\n  fn: (...args: Args) => Promise<void>,\n): (...args: Args) => Promise<void> {\n  return async (...args: Args) => {\n    try {\n      await fn(...args);\n    } catch (error) {\n      console.error(\n        `seagull: ${error instanceof Error ? error.message : error}`,\n      );\n      process.exitCode = 1;\n    }\n  };\n}\n"],"mappings":";;;;;;;;AAmBA,MAAM,YAAY,KAAK,QAAQ,cAAc,YAAY,GAAG,CAAC;AAC7D,MAAM,MAAM,KAAK,MACf,aAAa,KAAK,KAAK,WAAW,MAAM,cAAc,GAAG,MAAM,CACjE;AACA,MAAM,UAAU,IAAI,QAAQ;AAI5B,QACG,KAAK,SAAS,CAAC,CACf,YAAY,IAAI,WAAW,CAAC,CAC5B,QAAQ,IAAI,OAAO,CAAC,CACpB,OACC,uBACA,+EACF;AAEF,QACG,QAAQ,MAAM,CAAC,CACf,YAAY,kDAAkD,CAAC,CAC/D,OAAO,kBAAkB,YAAY,YAAY,cAAc,CAAC,CAAC,CAAC;AAErE,QACG,QAAQ,QAAQ,CAAC,CACjB,YAAY,uDAAuD,CAAC,CACpE,OAAO,kBAAkB,YAAY,cAAc,cAAc,CAAC,CAAC,CAAC;AAEvE,QACG,QAAQ,UAAU,CAAC,CACnB,YAAY,uDAAuD,CAAC,CACpE,OAAO,kBAAkB,YAAY,mBAAmB,cAAc,CAAC,CAAC,CAAC;AAE5E,QACG,QAAQ,OAAO,CAAC,CAChB,YAAY,mCAAmC,CAAC,CAChD,OAAO,kBAAkB,YAAY,aAAa,cAAc,CAAC,CAAC,CAAC;AAEtE,MAAM,OAAO,QACV,QAAQ,MAAM,CAAC,CACf,YAAY,8BAA8B;AAE7C,KACG,QAAQ,UAAU,CAAC,CACnB,YAAY,wDAAwD,CAAC,CACrE,OAAO,kBAAkB,YAAY,oBAAoB,cAAc,CAAC,CAAC,CAAC;AAE7E,KACG,QAAQ,OAAO,CAAC,CAChB,YAAY,iDAAiD,CAAC,CAC9D,OAAO,kBAAkB,YAAY,iBAAiB,cAAc,CAAC,CAAC,CAAC;AAE1E,MAAM,UAAU,QAAQ,QAAQ,SAAS,CAAC,CAAC,YAAY,sBAAsB;AAE7E,QACG,QAAQ,KAAK,CAAC,CACd,YACC,iEACF,CAAC,CACA,OAAO,aAAa,4CAA4C,CAAC,CACjE,OACC,kBAAkB,OAAO,SAAwB;CAC/C,MAAM,kBAAkB,cAAc,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC;AAClE,CAAC,CACH;AAEF,QACG,QAAQ,YAAY,CAAC,CACrB,YAAY,8DAA8D,CAAC,CAC3E,OAAO,aAAa,kDAAkD,CAAC,CACvE,OACC,kBAAkB,OAAO,SAAwB;CAC/C,MAAM,yBAAyB,cAAc,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAC;AACzE,CAAC,CACH;AAIF,MAAM,QAAQ,WAAW;;;;;;;AAYzB,SAAS,gBAAgC;CACvC,MAAM,EAAE,QAAQ,iBAAiB,QAAQ,KAA0B;CACnE,MAAM,aAAa,eACf,KAAK,QAAQ,QAAQ,IAAI,GAAG,YAAY,IACxC,kBAAkB,QAAQ,IAAI,CAAC;CAEnC,OAAO,WAAW,UAAU;AAC9B;;;;;;;;AASA,SAAS,kBACP,IACkC;CAClC,OAAO,OAAO,GAAG,SAAe;EAC9B,IAAI;GACF,MAAM,GAAG,GAAG,IAAI;EAClB,SAAS,OAAO;GACd,QAAQ,MACN,YAAY,iBAAiB,QAAQ,MAAM,UAAU,OACvD;GACA,QAAQ,WAAW;EACrB;CACF;AACF"}

package/dist/index.d.mts

@@ -0,0 +1,391 @@
+
+import { z } from "zod";
+//#region src/config/schema.d.ts
+/**
+ * A free-form tree of leaf values, used for the `vars:` block in the CLI config.
+ * Nest however deep is useful - every leaf becomes addressable as
+ * `{vars.<dot.path>}` in templated fields.
+ */
+type VarsTree = {
+  [key: string]: string | number | boolean | VarsTree;
+};
+//#endregion
+//#region src/config/types.d.ts
+type SdkTool = "openapi-generator" | "openapi-typescript";
+type SdkLang = "typescript" | "go" | "java";
+type SdkKind = "client" | "server";
+/**
+ * A single artifact a contract generates: a generator recipe from the CLI
+ * config, fully resolved (templates interpolated, overrides merged, paths made
+ * absolute) for one specific contract.
+ */
+interface ResolvedArtifact {
+  /**
+   * The id this artifact is known by for this contract - the key under
+   * `generators:` it was resolved from, or its `as` override. Used as the
+   * output folder segment, and to derive the publish branch/tag.
+   */
+  id: string;
+  tool: SdkTool;
+  lang: SdkLang;
+  kind: SdkKind;
+  /** `openapi-generator -g` value. Set only when `tool` is `openapi-generator`. */
+  generator?: string;
+  /** Absolute output directory: `<sdkDir>/<contract>/<id>`. */
+  outputDir: string;
+  /** `sdk/svc-<contract>/<id>` */
+  branch: string;
+  /** `svc-<contract>-<id>` */
+  tagPrefix: string;
+  additionalProperties: Record<string, string | number | boolean>;
+  package?: string;
+  goModule?: string;
+  goPackageName?: string;
+  maven?: {
+    groupId: string;
+    artifactId: string;
+  };
+  /**
+   * Absolute path to a custom README template, if `readme:` was set for this
+   * generator/artifact. Falls back to a built-in default template when unset -
+   * see `core/readme/readme-renderer.ts`.
+   */
+  readmeTemplate?: string;
+}
+interface ResolvedContract {
+  name: string;
+  title: string;
+  /** Absolute path to the source `openapi.yaml`. */
+  entrypoint: string;
+  /**
+   * Path to the source `openapi.yaml`, relative to `rootDir` - what
+   * `redocly.yaml`'s `apis:` section wants.
+   */
+  entrypointRelative: string;
+  artifacts: ResolvedArtifact[];
+}
+/**
+ * One (contract, artifact) pair - the flattened unit of work most commands
+ * actually iterate over.
+ */
+interface ResolvedArtifactEntry {
+  contract: ResolvedContract;
+  artifact: ResolvedArtifact;
+}
+interface ResolvedConfig {
+  /**
+   * Directory containing the config file - every relative path in the config
+   * (entrypoints, `paths.*`, `readme` templates, ...) resolves against this.
+   */
+  rootDir: string;
+  paths: {
+    dist: string;
+    specs: string;
+    docs: string;
+    sdk: string;
+  };
+  github: {
+    owner: string;
+    repo: string;
+  };
+  vars: VarsTree;
+  docs: {
+    server: {
+      host: string;
+      port: number;
+    };
+    metadata: {
+      title: string;
+      description: string;
+      favicon: string;
+      baseServerUrl: string;
+    };
+  };
+  contracts: ResolvedContract[];
+  /**
+   * Every (contract, artifact) pair across every contract, in config order -
+   * the flat list most commands iterate over.
+   */
+  allArtifacts: ResolvedArtifactEntry[];
+}
+//#endregion
+//#region src/config/loader.d.ts
+/**
+ * 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.
+ */
+declare function loadConfig(configPath: string): ResolvedConfig;
+//#endregion
+//#region src/config/resolve-config-file.d.ts
+/**
+ * Config filenames CLI recognizes, checked in this order.
+ */
+declare const CONFIG_FILENAMES: readonly [".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.
+ */
+declare function resolveConfigPath(cwd: string): string;
+//#endregion
+//#region src/core/generator/types.d.ts
+/** Passed once per tool to {@link Generator.prepare}, before any of that
+ * tool's {@link Generator.generate} calls run. */
+interface PrepareContext {
+  rootDir: string;
+  /**
+   * Every (contract, artifact) pair that uses this generator's `tool`, across
+   * all contracts.
+   */
+  entries: ResolvedArtifactEntry[];
+}
+/** Passed once per artifact to {@link Generator.generate}. */
+interface GenerateContext {
+  rootDir: string;
+  contract: ResolvedContract;
+  artifact: ResolvedArtifact;
+  version: string;
+  github: {
+    owner: string;
+    repo: string;
+  };
+  /**
+   * Absolute path to the contract's bundled JSON spec
+   * (`<specsDir>/<contract>.json`).
+   */
+  specInputPath: string;
+}
+//#endregion
+//#region src/core/generator/generator.d.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.
+ */
+declare abstract class Generator {
+  abstract readonly tool: SdkTool;
+  /**
+   * Optional one-time setup step, run once per tool before any of that tool's
+   * {@link generate} calls - for tools like `openapi-typescript` that generate
+   * every contract's output in a single global invocation instead of one call
+   * per artifact.
+   *
+   * @param ctx - Every (contract, artifact) pair using this generator's tool.
+   */
+  prepare?(ctx: PrepareContext): Promise<void>;
+  /**
+   * Generates a single artifact.
+   *
+   * @param ctx - The contract, artifact, and resolved version to generate for.
+   */
+  abstract generate(ctx: GenerateContext): Promise<void>;
+}
+//#endregion
+//#region src/core/generator/registry.d.ts
+/**
+ * Looks up the concrete {@link Generator} implementation for a given tool name.
+ */
+declare class GeneratorRegistry {
+  private readonly generators;
+  /**
+   * Registers a generator implementation under its own {@link Generator.tool}.
+   *
+   * @param generator - The generator instance to register.
+   * @returns `this`, for chaining.
+   */
+  register(generator: Generator): 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: SdkTool): Generator;
+  /**
+   * All distinct tools currently registered.
+   *
+   * @returns The registered tool names.
+   */
+  tools(): SdkTool[];
+}
+//#endregion
+//#region src/core/process/resolve-bin.d.ts
+/**
+ * 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.
+ */
+declare function resolveBinPath(pkgName: string, binName?: string): string;
+//#endregion
+//#region src/core/process/exec.d.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.
+ */
+declare function run(command: string, args: string[], cwd: string): Promise<void>;
+/**
+ * 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).
+ */
+declare function runSync(command: string, args: string[], cwd: string): number;
+//#endregion
+//#region src/generators/openapi-generator-cli/openapi-generator-cli.generator.d.ts
+/**
+ * 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`.
+ */
+declare class OpenApiGeneratorCli extends Generator {
+  readonly tool: SdkTool;
+  private readonly patchers;
+  generate(ctx: GenerateContext): Promise<void>;
+}
+//#endregion
+//#region src/generators/openapi-typescript/openapi-typescript.generator.d.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.
+ */
+declare class OpenApiTypescriptGenerator extends Generator {
+  readonly tool: SdkTool;
+  prepare({ rootDir, entries }: PrepareContext): Promise<void>;
+  generate({ contract, artifact, version, github }: GenerateContext): Promise<void>;
+}
+//#endregion
+//#region src/commands/bundle.d.ts
+/**
+ * Bundles every contract's OpenAPI spec into `dist/specs/<contract>.json`.
+ *
+ * @param config - The resolved CLI config.
+ */
+declare function bundleCommand(config: ResolvedConfig): Promise<void>;
+//#endregion
+//#region src/commands/clean.d.ts
+/**
+ * Removes the entire `dist` output directory.
+ *
+ * @param config - The resolved CLI config.
+ */
+declare function cleanCommand(config: ResolvedConfig): Promise<void>;
+//#endregion
+//#region src/commands/generate-docs.d.ts
+/**
+ * Generates the documentation website for every contract into `dist/docs`.
+ *
+ * @param config - The resolved CLI config.
+ */
+declare function generateDocsCommand(config: ResolvedConfig): Promise<void>;
+//#endregion
+//#region src/commands/generate-sdk.d.ts
+/**
+ * Generates SDK packages for every artifact of every contract in the config.
+ *
+ * @param config - The resolved config.
+ */
+declare function generateSdkCommand(config: ResolvedConfig): Promise<void>;
+//#endregion
+//#region src/commands/lint.d.ts
+/**
+ * Lints every contract's OpenAPI spec.
+ * Sets `process.exitCode = 1` if any contract fails.
+ *
+ * @param config - The resolved CLI config.
+ */
+declare function lintCommand(config: ResolvedConfig): Promise<void>;
+//#endregion
+//#region src/commands/publish-registries.d.ts
+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.
+ */
+declare function publishRegistriesCommand(config: ResolvedConfig, options?: PublishRegistriesOptions): Promise<void>;
+//#endregion
+//#region src/commands/publish-sdk.d.ts
+interface PublishSdkOptions {
+  dryRun?: boolean;
+}
+/**
+ * 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.
+ */
+declare function publishSdkCommand(config: ResolvedConfig, options?: PublishSdkOptions): Promise<void>;
+//#endregion
+//#region src/commands/serve-docs.d.ts
+/**
+ * Serves the generated documentation site (`dist/docs`) over plain HTTP for
+ * local previewing.
+ *
+ * @param config - The resolved CLI config.
+ */
+declare function serveDocsCommand(config: ResolvedConfig): Promise<void>;
+//#endregion
+export { CONFIG_FILENAMES, type GenerateContext, Generator, GeneratorRegistry, OpenApiGeneratorCli, OpenApiTypescriptGenerator, type PrepareContext, type PublishRegistriesOptions, type PublishSdkOptions, type ResolvedArtifact, type ResolvedArtifactEntry, type ResolvedConfig, type ResolvedContract, type SdkKind, type SdkLang, type SdkTool, type VarsTree, bundleCommand, cleanCommand, generateDocsCommand, generateSdkCommand, lintCommand, loadConfig, publishRegistriesCommand, publishSdkCommand, resolveBinPath, resolveConfigPath, run, runSync, serveDocsCommand };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import { _ as resolveConfigPath, a as generateSdkCommand, c as Generator, d as cleanCommand, f as bundleCommand, g as CONFIG_FILENAMES, h as runSync, i as lintCommand, l as GeneratorRegistry, m as run, n as publishSdkCommand, o as OpenApiTypescriptGenerator, p as resolveBinPath, r as publishRegistriesCommand, s as OpenApiGeneratorCli, t as serveDocsCommand, u as generateDocsCommand, v as loadConfig } from "./serve-docs-BZaITOD0.mjs";
+export { CONFIG_FILENAMES, Generator, GeneratorRegistry, OpenApiGeneratorCli, OpenApiTypescriptGenerator, bundleCommand, cleanCommand, generateDocsCommand, generateSdkCommand, lintCommand, loadConfig, publishRegistriesCommand, publishSdkCommand, resolveBinPath, resolveConfigPath, run, runSync, serveDocsCommand };