npm - @octalmesh/seagull - Versions diffs - 0.0.2 → 0.1.1 - Mend

@octalmesh/seagull 0.0.2 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +425 -180
package/dist/cli.mjs +1 -1
package/dist/index.d.mts +3 -1556
package/dist/index.mjs +4 -2
package/package.json +32 -21
package/dist/dist-Ou2inxGj.mjs +0 -16783
package/dist/dist-Ou2inxGj.mjs.map +0 -1

package/README.md CHANGED Viewed

@@ -1,104 +1,228 @@
-# 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".
-## Packages
-This repo is a monorepo, but only **one** package is ever published:
-`@octalmesh/seagull`. The three packages under [`packages/`](./packages)
-are private and exist purely for internal organization - each is bundled
-straight into `@octalmesh/seagull`'s own `dist/` at build time (see the root
-[`tsdown.config.ts`](./tsdown.config.ts)), so installing the one package is
-installing all of it.
-| Package                                     | Role                                                                     |
-|------------------------------------------------|-------------------------------------------------------------------------|
-| **`@octalmesh/seagull`** (this repo's root)     | Published. The `seagull` CLI + programmatic API.                        |
-| [`@octalmesh/seagull-core`](./packages/core)    | Private. Config loading, the `Generator` primitive, built-in generators. |
-| [`@octalmesh/seagull-cli`](./packages/cli)      | Private. Pipeline commands + the `commander` program.                   |
-| [`@octalmesh/seagull-docs`](./packages/docs)    | Private. Docs-site generation - a Scalar-based placeholder today, a fully custom UI later. |
-If you're just using seagull, none of that matters - `npm install @octalmesh/seagull`
-gets you the `seagull` command and the full programmatic API in one package.
-The split only matters if you're contributing to seagull itself.
+<!--suppress HtmlDeprecatedAttribute, HtmlUnknownTarget -->
+<div align="center">
+  <!--
+  =====================
+         HEADER
+  =====================
+  -->
+  <br />
+  <a rel="noopener noreferrer" href="https://github.com/OctalMesh/Seagull">
+    <picture>
+      <source media="(prefers-color-scheme: light)" srcset="./.github/assets/svg/seagull_logo.svg">
+      <img alt="Seagull" src="./.github/assets/svg/seagull_logo_white.svg">
+    </picture>
+  </a>
+  <br /><br /><br />
+  <!--
+  =====================
+         BADGES
+  =====================
+  -->
+  <div>
+    <!-- Repo Stars Badge -->
+    <a rel="noopener noreferrer" href="https://github.com/OctalMesh/Seagull/stargazers">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/stars/OctalMesh/Seagull?style=for-the-badge&logo=starship&color=363636&labelColor=464646" />
+        <img alt="Stars" src="https://img.shields.io/github/stars/OctalMesh/Seagull?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiI+DQogIDxwYXRoIGZpbGw9IiMzNjM2MzYiIGQ9Ik04IC4yNWEuNzUuNzUgMCAwIDEgLjY3My40MThsMS44ODIgMy44MTUgNC4yMS42MTJhLjc1Ljc1IDAgMCAxIC40MTYgMS4yNzlsLTMuMDQ2IDIuOTcuNzE5IDQuMTkyYS43NTEuNzUxIDAgMCAxLTEuMDg4Ljc5MUw4IDEyLjM0N2wtMy43NjYgMS45OGEuNzUuNzUgMCAwIDEtMS4wODgtLjc5bC43Mi00LjE5NEwuODE4IDYuMzc0YS43NS43NSAwIDAgMSAuNDE2LTEuMjhsNC4yMS0uNjExTDcuMzI3LjY2OEEuNzUuNzUgMCAwIDEgOCAuMjVabTAgMi40NDVMNi42MTUgNS41YS43NS43NSAwIDAgMS0uNTY0LjQxbC0zLjA5Ny40NSAyLjI0IDIuMTg0YS43NS43NSAwIDAgMSAuMjE2LjY2NGwtLjUyOCAzLjA4NCAyLjc2OS0xLjQ1NmEuNzUuNzUgMCAwIDEgLjY5OCAwbDIuNzcgMS40NTYtLjUzLTMuMDg0YS43NS43NSAwIDAgMSAuMjE2LS42NjRsMi4yNC0yLjE4My0zLjA5Ni0uNDVhLjc1Ljc1IDAgMCAxLS41NjQtLjQxTDggMi42OTRaIi8+DQo8L3N2Zz4=&color=fff&labelColor=eaeaea" />
+      </picture>
+    </a>
+    <!-- Repo Contributors Badge -->
+    <a rel="noopener noreferrer" href="https://github.com/OctalMesh/Seagull/contributors">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/contributors/OctalMesh/Seagull?style=for-the-badge&logo=githubsponsors&logoColor=fff&color=363636&labelColor=464646" />
+        <img alt="Contributors" src="https://img.shields.io/github/contributors/OctalMesh/Seagull?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxNiAxNiI+DQogIDxwYXRoIGZpbGw9IiMzNjM2MzYiIGQ9Ik0yIDUuNWEzLjUgMy41IDAgMSAxIDUuOSAyLjU1IDUuNSA1LjUgMCAwIDEgMy4wMyA0LjA4Ljc1Ljc1IDAgMSAxLTEuNDguMjQgNCA0IDAgMCAwLTcuOSAwIC43NS43NSAwIDAgMS0xLjQ4LS4yNEE1LjUgNS41IDAgMCAxIDMuMSA4LjA1IDMuNSAzLjUgMCAwIDEgMiA1LjVaTTExIDRhMyAzIDAgMCAxIDIuMjIgNS4wMiA1LjAxIDUuMDEgMCAwIDEgMi41NiAzLjAxLjc1Ljc1IDAgMCAxLS44OC45NS43NS43NSAwIDAgMS0uNTUtLjUxIDMuNSAzLjUgMCAwIDAtMi41My0yLjM3Ljc1Ljc1IDAgMCAxLS41Ny0uNzN2LS4zNWEuNzUuNzUgMCAwIDEgLjQyLS42OEExLjUgMS41IDAgMCAwIDExIDUuNS43NS43NSAwIDAgMSAxMSA0Wm0tNS41LS41YTIgMiAwIDEgMCAwIDQgMiAyIDAgMCAwIDAtNFoiLz4NCjwvc3ZnPg==&color=fff&labelColor=eaeaea" />
+      </picture>
+    </a>
+    <!-- Repo Views Badge -->
+    <a rel="noopener noreferrer" href="https://hits.sh/github.com/OctalMesh/Seagull">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://hits.sh/github.com/OctalMesh/Seagull.svg?style=for-the-badge&label=Views&logo=github&color=363636&labelColor=464646" />
+        <img alt="Views" src="https://hits.sh/github.com/OctalMesh/Seagull.svg?style=for-the-badge&label=Views&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMDI0IDEwMjQiPjxwYXRoIGZpbGw9IiMzNjM2MzYiIGQ9Ik01MTIgMGE1MTIgNTEyIDAgMCAwLTE2MiA5OThjMjYgNCAzNS0xMSAzNS0yNXYtOTVjLTEyOSAyNC0xNjItMzEtMTczLTYwLTUtMTUtMzAtNjAtNTItNzItMTgtMTAtNDQtMzQtMS0zNCA0MS0xIDY5IDM3IDc5IDUyIDQ2IDc4IDEyMCA1NiAxNDkgNDIgNS0zMyAxOC01NSAzMy02OC0xMTQtMTMtMjMzLTU3LTIzMy0yNTMgMC01NiAyMC0xMDIgNTItMTM3LTUtMTMtMjMtNjYgNS0xMzYgMCAwIDQzLTE0IDE0MSA1MmE0NzUgNDc1IDAgMCAxIDI1NiAwYzk4LTY2IDE0MS01MiAxNDEtNTIgMjggNzAgMTAgMTIzIDUgMTM2IDMzIDM1IDUzIDgxIDUzIDEzNyAwIDE5Ny0xMjAgMjQwLTIzNCAyNTMgMTkgMTYgMzUgNDcgMzUgOTVsLTEgMTQwYzAgMTQgMTAgMzAgMzUgMjVBNTEzIDUxMyAwIDAgMCA1MTIgMFoiLz48L3N2Zz4=&color=fff&labelColor=eaeaea" />
+      </picture>
+    </a>
+    <br />
+    <!-- Version Badge -->
+    <a rel="noopener noreferrer" href="https://npmjs.com/package/@octalmesh/seagull">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/npm/v/@octalmesh/seagull?style=for-the-badge&label=Version&color=363636&labelColor=464646&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTEgNy44di01UTEuMiAxLjIgMi44IDFoNXEuNyAwIDEuMi41bDYuMyA2LjNhMiAyIDAgMCAxIDAgMi40bC01IDVhMiAyIDAgMCAxLTIuNSAwTDEuNSA5QTIgMiAwIDAgMSAxIDcuOG0xLjUgMFY4bDYuMyA2LjJoLjRsNS01di0uNEw4IDIuNmwtLjItLjFoLTVsLS4zLjNaTTYgNWExIDEgMCAxIDEgMCAyIDEgMSAwIDAgMSAwLTIiLz48L3N2Zz4=" />
+        <img alt="Version" src="https://img.shields.io/npm/v/@octalmesh/seagull?style=for-the-badge&label=Version&color=fff&labelColor=eaeaea&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiI+PHBhdGggZmlsbD0iIzM2MzYzNiIgZD0iTTEgNy44di01UTEuMiAxLjIgMi44IDFoNXEuNyAwIDEuMi41bDYuMyA2LjNhMiAyIDAgMCAxIDAgMi40bC01IDVhMiAyIDAgMCAxLTIuNSAwTDEuNSA5QTIgMiAwIDAgMSAxIDcuOG0xLjUgMFY4bDYuMyA2LjJoLjRsNS01di0uNEw4IDIuNmwtLjItLjFoLTVsLS4zLjNaTTYgNWExIDEgMCAxIDEgMCAyIDEgMSAwIDAgMSAwLTIiLz48L3N2Zz4=" />
+      </picture>
+    </a>
+    <!-- NPM Downloads Badge -->
+    <a rel="noopener noreferrer" href="https://www.npmjs.com/package/@octalmesh/seagull">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/npm/dm/@octalmesh/seagull?style=for-the-badge&logo=npm&color=363636&labelColor=464646" />
+        <img alt="NPM Downloads" src="https://img.shields.io/npm/dm/@octalmesh/seagull?style=for-the-badge&logo=npm&logoColor=464646&color=fff&labelColor=eaeaea" />
+      </picture>
+    </a>
+    <!-- License Badge -->
+    <a rel="noopener noreferrer" href="LICENSE.md">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://img.shields.io/github/license/OctalMesh/Seagull?style=for-the-badge&color=363636&labelColor=464646&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiI+PHBhdGggZmlsbD0iI2ZmZiIgZD0iTTguOC44VjJoMXEuMyAwIC44LjJsMS4zLjhoMi40YS44LjggMCAwIDEgMCAxLjVoLS41TDE2IDkuMmExIDEgMCAwIDEtLjEuOGwtLjUtLjUuNS41di4xbC0uOC40cS0uNi41LTIgLjVhNSA1IDAgMCAxLTItLjVsLS43LS40YTEgMSAwIDAgMS0uMi0xbDItNC42cS0uNiAwLTEtLjJMMTAgMy41SDguN1YxM2gyLjZhLjguOCAwIDAgMSAwIDEuNUg0LjhhLjguOCAwIDAgMSAwLTEuNWgyLjVWMy41SDZMNSA0LjNsLTEgLjIgMiA0LjdhMSAxIDAgMCAxLS4xLjhsLS41LS41LjUuNXYuMWwtLjguNHEtLjYuNS0yIC41YTUgNSAwIDAgMS0yLS41bC0uNy0uNEExIDEgMCAwIDEgMCA5bDItNC42aC0uNGEuOC44IDAgMCAxIDAtMS41aDIuNGwxLjMtLjguOS0uMmgxVi44YS44LjggMCAwIDEgMS41IDBtMi45IDguNHEuNC4zIDEuMy4zYy45IDAgMS0uMSAxLjMtLjNMMTMgNi4zWm0tMTAgMHEuNC4zIDEuMy4zYy45IDAgMS0uMSAxLjMtLjNMMyA2LjNaIi8+PC9zdmc+" />
+        <img alt="License" src="https://img.shields.io/github/license/OctalMesh/Seagull?style=for-the-badge&color=fff&labelColor=eaeaea&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNiIgaGVpZ2h0PSIxNiI+PHBhdGggZmlsbD0iIzM2MzYzNiIgZD0iTTguOC44VjJoMXEuMyAwIC44LjJsMS4zLjhoMi40YS44LjggMCAwIDEgMCAxLjVoLS41TDE2IDkuMmExIDEgMCAwIDEtLjEuOGwtLjUtLjUuNS41di4xbC0uOC40cS0uNi41LTIgLjVhNSA1IDAgMCAxLTItLjVsLS43LS40YTEgMSAwIDAgMS0uMi0xbDItNC42cS0uNiAwLTEtLjJMMTAgMy41SDguN1YxM2gyLjZhLjguOCAwIDAgMSAwIDEuNUg0LjhhLjguOCAwIDAgMSAwLTEuNWgyLjVWMy41SDZMNSA0LjNsLTEgLjIgMiA0LjdhMSAxIDAgMCAxLS4xLjhsLS41LS41LjUuNXYuMWwtLjguNHEtLjYuNS0yIC41YTUgNSAwIDAgMS0yLS41bC0uNy0uNEExIDEgMCAwIDEgMCA5bDItNC42aC0uNGEuOC44IDAgMCAxIDAtMS41aDIuNGwxLjMtLjguOS0uMmgxVi44YS44LjggMCAwIDEgMS41IDBtMi45IDguNHEuNC4zIDEuMy4zYy45IDAgMS0uMSAxLjMtLjNMMTMgNi4zWm0tMTAgMHEuNC4zIDEuMy4zYy45IDAgMS0uMSAxLjMtLjNMMyA2LjNaIi8+PC9zdmc+" />
+      </picture>
+    </a>
+  </div>
+  <h1></h1>
+  <!--
+  =====================
+         SOURCES
+  =====================
+  -->
+  <h6>
+    <a rel="noopener noreferrer" href="CODE_OF_CONDUCT.md">Code of Conduct</a>
+    ·
+    <a rel="noopener noreferrer" href="CONTRIBUTING.md">Contributing</a>
+    ·
+    <a rel="noopener noreferrer" href="SECURITY.md">Security Policy</a>
+    ·
+    <a rel="noopener noreferrer" href="SUPPORT.md">Support</a>
+    ·
+    <a rel="noopener noreferrer" href="RELEASING.md">Releasing</a>
+    ·
+    <a rel="noopener noreferrer" href="LICENSE.md">License</a>
+    ·
+    <a rel="noopener noreferrer" href="examples/README.md">Examples</a>
+  </h6>
+</div>
+<div align="justify">
+  <!--
+  =====================
+       DESCRIPTION
+  =====================
+  -->
+  <p>
+    Seagull is a 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 and it lints, bundles, generates, documents,
+    and publishes them.
+  </p>
+</div>
+<div align="center">
+  <h2 id="overview">Overview</h2>
+</div>
+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".
+| Stage        | What it does                                                                                                                                                                                                   |
+|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| **Lint**     | Validates every contract's OpenAPI spec for structural and style issues                                                                                                                                        |
+| **Bundle**   | Dereferences and bundles each spec into `dist/specs`                                                                                                                                                           |
+| **Generate** | Runs each configured "recipe" through [`openapi-generator-cli`](https://www.npmjs.com/package/@openapitools/openapi-generator-cli) or [`openapi-typescript`](https://www.npmjs.com/package/openapi-typescript) |
+| **Document** | Builds an interactive docs site across every contract into `dist/docs`                                                                                                                                         |
+| **Publish**  | Pushes generated SDKs to orphan git branches/tags, and to artifact registries                                                                                                                                  |
+```mermaid
+flowchart LR
+  A["Contract"] --> B["Lint"]
+  B --> C["Bundle<br/>(spec files)"]
+  C --> D["Generate<br/>(SDK artifacts)"]
+  C --> E["Docs website"]
+  D --> F["Publish SDK<br/>(git branch + tag)"]
+  D --> G["Publish registries<br/>(npm / Maven)"]
+  classDef stage fill:#363636,stroke:#666,color:#fff,rx:6,ry:6
+  class A,B,C,D,E,F,G stage
+```
-## Install
+<div align="center">
+  <h2 id="packages">Packages</h2>
+</div>
+This repo is a monorepo of four packages, all versioned and published together
+(see [`.changeset/config.json`](.changeset/config.json)'s `fixed` group and
+[RELEASING.md](RELEASING.md)). Most people only need the first one - it bundles
+the other three straight into its own `dist/` via [`tsdown`](https://tsdown.dev).
+The three internal packages are published independently too, for anyone who
+wants a smaller dependency (e.g. scripting against just
+`@octalmesh/seagull-core`'s config loader without pulling in the CLI or the docs
+generator).
+| Package                                    | Role                                                                                           |
+|--------------------------------------------|------------------------------------------------------------------------------------------------|
+| [`@octalmesh/seagull`](.)                  | The `seagull` CLI + programmatic API. What almost everyone should install.                     |
+| [`@octalmesh/seagull-core`](packages/core) | Config loading, the `Generator` primitive, built-in generators, version/publishing logic, etc. |
+| [`@octalmesh/seagull-cli`](packages/cli)   | Pipeline commands (`lint`/`bundle`/`generate`/`publish`/...) + the `commander` program.        |
+| [`@octalmesh/seagull-docs`](packages/docs) | Docs-site generation from bundled specs, plus a local dev server for previewing the site.      |
+<div align="center">
+  <h2 id="installation">Installation</h2>
+</div>
 ```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 `@octalmesh/seagull`'s own dependencies, resolved via Node's
-module resolution (not `npx`/`pnpm exec`) - nothing extra to install, and it
-works the same regardless of which package manager you use.
+Under the hood, `generate` shells out to `@openapitools/openapi-generator-cli`
+(needs a JVM on `PATH`) and `openapi-typescript`; `lint`/`bundle` and `docs`
+each rely on their own established OpenAPI tooling under the hood. All of these
+are `@octalmesh/seagull`'s own dependencies, resolved via Node's module
+resolution.
-## Quick start
+<div align="center">
+  <h2 id="quick-start">Quick Start</h2>
+</div>
-Create a config file at the root of your contracts repo - any of
-`.seagull`, `.seagull.yaml`, `.seagull.yml`, `seagull.yaml`, `seagull.yml`:
+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
+# Seagull config version
 configVersion: 1
-github:
-  owner: your-org
-  repo: your-contracts-repo
+# Custom variables to use in config
 vars:
-  org: your-org
+  org: "your-npm-scope"
+  repository:
+    owner: "your-org"
+    repo: "your-contracts-repo"
+# Documentation configuration
 docs:
   server:
-    host: localhost
+    host: "localhost"
     port: 8080
   metadata:
-    title: "API Reference"
-    description: "..."
-    favicon: https://your-domain.com/favicon.ico
-    baseServerUrl: https://api.your-domain.com
+    title: "Your API Docs"
+    description: "Generated API documentation"
+    favicon: "/favicon.ico"
+    baseServerUrl: "https://api.example.com"
+# Publishing configuration
 publishing:
   branch: "sdk/svc-{service}/{id}"
   tag: "svc-{service}-{id}-v{version}"
-  repositoryUrl: "https://github.com/{github.owner}/{github.repo}"
+  repositoryUrl: "https://github.com/{vars.repository.owner}/{vars.repository.repo}"
   npm:
-    registry: "https://npm.pkg.github.com"
-    access: restricted
+    registry: "https://registry.npmjs.org"
+    access: "public"
   maven:
-    repositoryId: github
-    repositoryUrl: "https://maven.pkg.github.com/{github.owner}/{github.repo}"
+    repositoryId: "github"
+    repositoryUrl: "https://maven.pkg.github.com/{vars.repository.owner}/{vars.repository.repo}"
+# Generators configuration used to produce SDK artifacts
 generators:
   ts-client:
-    tool: openapi-generator
-    generator: typescript-fetch
-    lang: typescript
-    kind: client
+    tool: "openapi-generator"
+    generator: "typescript-fetch"
+    lang: "typescript"
+    kind: "client"
     package: "@{vars.org}/{service}-client"
-    additionalProperties:
-      supportsES6: true
+# Per-service contract configuration
 contracts:
-  - name: auth
-    title: Auth Service API
-    entrypoint: specs/auth/openapi.yaml
-    artifacts: [ts-client]
+  - name: "auth"
+    title: "Auth Service API"
+    entrypoint: "specs/auth/openapi.yaml"
+    artifacts:
+      - "ts-client"
 ```
 Then:
@@ -110,79 +234,133 @@ npx seagull generate
 npx seagull docs generate && npx seagull docs serve
 ```
-## Configuration
+See [`examples/`](examples/README.md) for complete, runnable configs covering
+every generator/publishing/docs feature, plus an API walkthrough.
+<div align="center">
+  <h2 id="configuration">Configuration</h2>
+</div>
-- **`configVersion:`** (required) - which version of the config *schema*
-  this file targets, currently always `1`. Decoupled from `@octalmesh/seagull`'s
-  own npm version on purpose: this only changes if `seagull.yaml`'s shape
-  changes in a breaking way, so an old config fails with a clear "expected
-  configVersion 1" error instead of a confusing failure on some unrelated
-  field once the schema moves on.
-- **`generators:`** - reusable recipes: a `tool` (`openapi-generator` or
+- `configVersion:` (required) - which version of the config schema this file
+  targets. Decoupled from `@octalmesh/seagull`'s own npm version on purpose:
+  this only changes if `seagull.yaml`'s shape changes in a breaking way, so an
+  old config fails with a clear "expected configVersion 1" error.
+- `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:
+  reference `{vars.some.nested.key}` 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
+    - name: "payment"
       artifacts:
-        - generator: java-client
-          as: java-client-legacy # renames this artifact's output folder/branch/tag
+        - generator: "java-client"
+          as: "java-client-legacy" # renames this artifact's output folder/branch/tag
           overrides:
-            generator: java-legacy-template
-            additionalProperties: { library: jersey2 }
+            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
+- `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
+  override that. `specFormat:` controls what format(s) `seagull bundle` writes
+  specs in - `json` (default), `yaml`, or a list of both
+  (`specFormat: [json, yaml]`) to bundle into more than one format at once;
+  Redocly infers the output format from the file extension on its own, so
+  this is a free choice, not a compatibility trade-off. When more than one
+  format is configured, the first one listed is the "primary" format SDK
+  generation and the docs site actually read from - the rest are bundled as
+  additional static artifacts alongside it.
+- `docs:` - `server: { host, port }` for `docs serve`, and
   `metadata: { title, description, favicon, baseServerUrl }` for the
   generated docs site.
-- **`publishing:`** (required) - see below.
-A typo or missing field fails immediately with a readable, path-annotated
-error - config is validated with [zod](https://zod.dev) on every run.
+- `publishing:` (required) - see below.
+A typo or missing field fails immediately with a readable, path-annotated error.
+Config is validated on every run.
+`seagull.yaml` (and `redocly.base.yaml`) also support the YAML `<<: *anchor`
+merge key, so shared fields don't need to be repeated across every entry:
+```yaml
+_defaults: &defaults
+  lang: "typescript"
+generators:
+  ts-server:
+    <<: *defaults
+    tool: "openapi-typescript"
+    kind: "server"
+    package: "@{vars.org}/{service}-server"
+  ts-client:
+    <<: *defaults
+    tool: "openapi-generator"
+    generator: "typescript-fetch"
+    kind: "client"
+    package: "@{vars.org}/{service}-client"
+```
-### Publishing
+<h3 id="publishing">Publishing</h3>
-`publishing:` controls where things get published to - git branch/tag
-naming, and npm/Maven registry URLs. It's required at the root level:
-seagull has no built-in convention here, so a config that omits it fails
-validation with a message pointing at exactly what's missing, rather than
-silently applying an opinionated default nobody chose.
+`publishing:` controls where things get published to - git branch/tag naming,
+and npm/Maven registry URLs. It's required at the root level: seagull has no
+built-in convention here, so a config that omits it fails validation with a
+message pointing at exactly what's missing, rather than silently applying an
+opinionated default nobody chose.
 ```yaml
 publishing:
-  branch: "sdk/svc-{service}/{id}" # git branch each artifact publishes to
-  tag: "svc-{service}-{id}-v{version}" # git tag - the only field where {version} is available
-  repositoryUrl: "https://github.com/{github.owner}/{github.repo}"
+  branch: "sdk/svc-{service}/{id}"                                                   # git branch each artifact publishes to
+  tag: "svc-{service}-{id}-v{version}"                                               # git tag - the only field where {version} is available
+  repositoryUrl: "https://github.com/{vars.repository.owner}/{vars.repository.repo}" # git remote URL for pushing branches/tags
   npm:
     registry: "https://npm.pkg.github.com"
-    access: restricted # or "public"
+    access: "restricted" # or "public"
   maven:
-    repositoryId: github
-    repositoryUrl: "https://maven.pkg.github.com/{github.owner}/{github.repo}"
+    repositoryId: "github"
+    repositoryUrl: "https://maven.pkg.github.com/{vars.repository.owner}/{vars.repository.repo}"
 ```
-Every field is a template - the same `{...}` engine as naming templates,
-plus `{id}` (the artifact's id) and, for `tag` only, `{version}` (resolved
-once the contract's spec is bundled, since a branch is created before a
-version is known but a tag isn't).
+Every field is a template - the same `{...}` engine as naming templates, plus
+`{id}` (the artifact's id) and, for `tag` only, `{version}` (resolved once the
+contract's spec is bundled, since a branch is created before a version is known
+but a tag isn't).
 Like `additionalProperties` and `readme`, `publishing:` can be overridden
 per-generator (`generators.<id>.publishing`) or per-contract-artifact
 (`artifacts[].overrides.publishing`) - only the fields that differ need
 repeating, the rest fall through to the root-level config:
+```mermaid
+flowchart TD
+  A["Root config<br/>(fallback for everything)"] --> B["Generator override<br/>(per recipe)"]
+  B --> C["Artifact override<br/>(per contract)"]
+  C --> D(["Effective config<br/>for this artifact"])
+  classDef layer fill:#363636,stroke:#666,color:#fff,rx:6,ry:6
+  classDef result fill:#1f6feb,stroke:#1f6feb,color:#fff,rx:20,ry:20
+  class A,B,C layer
+  class D result
+```
+The same three-layer precedence (root -> generator -> artifact `overrides`)
+applies to `additionalProperties` and `readme` too, not just `publishing`.
 ```yaml
 generators:
   ts-client:
@@ -192,92 +370,159 @@ generators:
         registry: "https://registry.internal.example.com" # every contract's ts-client uses this registry
 contracts:
-  - name: payment
+  - name: "payment"
     artifacts:
-      - generator: ts-client
+      - generator: "ts-client"
         overrides:
           publishing:
             branch: "custom/{service}-{id}-branch" # ...except payment's ts-client, which also uses a different branch
 ```
-### Custom README templates
+<h3 id="custom-readme-templates">Custom README templates</h3>
-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):
+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
+    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.tag}`                             | Resolved publishing branch / tag                 |
-| `{artifact.npmRegistry}` / `{artifact.mavenRepositoryUrl}`         | Resolved registry URLs from `publishing:`        |
-An unresolvable placeholder fails the build loudly (a typo'd `{vesion}`
-won't silently ship as literal text).
-## Commands
+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:`                           |
+| `{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.tag}`                     | Resolved publishing branch / tag                 |
+| `{artifact.npmRegistry}` / `{artifact.mavenRepositoryUrl}` | Resolved registry URLs from `publishing:`        |
+An unresolvable placeholder fails the build loudly (a typo'd `{vesion}` won't
+silently ship as literal text).
+<div align="center">
+  <h2 id="commands">Commands</h2>
+</div>
 ```
-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 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);
+seagull lint                           Lint every contract's OpenAPI spec
+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 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
 ```
-`loadConfig`, every `*Command` function, `createProgram` (the `commander`
-program factory), 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.
+Every command accepts `-c, --config <path>` to point at a config file outside
+the current directory.
-## Development
+<div align="center">
+  <h2 id="development">Development</h2>
+</div>
 ```bash
-pnpm install
-pnpm run build       # builds packages/* first (topological), then bundles the root package
-pnpm run typecheck    # run after build - resolves the private packages via their built dist/
-pnpm run lint
-pnpm run test:run
+pnpm install       # install dependencies for all packages
+pnpm run build     # builds packages/* first (topological), then bundles the root package
+pnpm run typecheck # run after build - resolves the workspace packages via their built dist/
+pnpm run lint      # lint all packages
+pnpm run test      # run all tests
 ```
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to propose changes, and
-[RELEASING.md](./RELEASING.md) for how versioning and publishing work.
-## License
-MIT
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to propose changes, and
+[RELEASING.md](RELEASING.md) for how versioning and publishing work.
+<div align="center">
+  <!--
+  =====================
+         FOOTER
+  =====================
+  -->
+  <h1></h1>
+  <br />
+  <!-- OctalMesh Logo -->
+  <a rel="noopener noreferrer" target="_blank" href="https://octalmesh.com">
+    <picture>
+      <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/logo/svg/octal_mesh_center.svg" />
+      <img alt="OctalMesh" src="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/logo/svg/octal_mesh_center_white.svg" height="48" />
+    </picture>
+  </a>
+  <br /><br />
+  <!-- Socials -->
+  <div>
+    <!-- Telegram Badge -->
+    <a rel="noopener noreferrer" target="_blank" href="https://octalmesh.com/telegram">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/telegram.svg" />
+        <img alt="Telegram" src="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/telegram_white.svg" width="48" />
+      </picture>
+    </a>
+    &nbsp;
+    <!-- YouTube Badge -->
+    <a rel="noopener noreferrer" target="_blank" href="https://octalmesh.com/youtube">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/youtube.svg" />
+        <img alt="YouTube" src="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/youtube_white.svg" width="48" />
+      </picture>
+    </a>
+    &nbsp;
+    <!-- TikTok Badge -->
+    <a rel="noopener noreferrer" target="_blank" href="https://octalmesh.com/tiktok">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/tiktok.svg" />
+        <img alt="TikTok" src="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/tiktok_white.svg" width="48" />
+      </picture>
+    </a>
+    &nbsp;
+    <!-- Instagram Badge -->
+    <a rel="noopener noreferrer" target="_blank" href="https://octalmesh.com/instagram">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/instagram.svg" />
+        <img alt="Instagram" src="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/instagram_white.svg" width="48" />
+      </picture>
+    </a>
+    &nbsp;
+    <!-- X Badge -->
+    <a rel="noopener noreferrer" target="_blank" href="https://octalmesh.com/x">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/x.svg" />
+        <img alt="X" src="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/x_white.svg" width="48" />
+      </picture>
+    </a>
+    &nbsp;
+    <!-- Reddit Badge -->
+    <a rel="noopener noreferrer" target="_blank" href="https://octalmesh.com/reddit">
+      <picture>
+        <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/reddit.svg" />
+        <img alt="Reddit" src="https://raw.githubusercontent.com/OctalMesh/OctalDesign/release/assets/icon/svg/reddit_white.svg" width="48" />
+      </picture>
+    </a>
+  </div>
+</div>
+<h6>
+  <div align="center">
+    • • •
+    <br /><br />
+    This project is licensed under the <a rel="noopener noreferrer" href="../../LICENSE.md">MIT License</a>
+    <br /><br />
+  </div>
+  <div align="justify">
+    <ul>
+      <li>Feel free to use this project for any purpose, including commercial applications.</li>
+      <li>You are permitted to modify, distribute, and include this project in any form, as long as the original copyright notice is retained.</li>
+      <li>If you share or publish modified versions, attribution to the original <a rel="noopener noreferrer" href="https://github.com/OctalMesh/Seagull">GitHub repository</a> is appreciated.</li>
+      <li>This software is provided "as is", without any warranties or guarantees, as detailed in the license terms.</li>
+    </ul>
+  </div>
+</h6>