@octalmesh/seagull 0.0.1 → 0.0.2

package/dist/index.d.mts

@@ -1,19 +1,44 @@
-
-import { z } from "zod";
+//#region packages/core/dist/index.d.mts
 //#region src/config/schema.d.ts
+/**
+ * The seagull config *schema* version - not the npm package's own version.
+ * Bumped only when the shape of `seagull.yaml` changes in a breaking way, so
+ * older configs fail with a clear "this config targets schema vN, seagull
+ * expects vM" error instead of a confusing validation failure on some
+ * unrelated field once the schema moves on.
+ */
+declare const CONFIG_SCHEMA_VERSION = 1;
 /**
  * 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 = {
+interface 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";
+/**
+ * Fully resolved publishing conventions for one artifact.
+ */
+interface ResolvedPublishing {
+  /** Fully resolved git branch name (no runtime-only placeholders left). */
+  branch: string;
+  /**
+   * Raw tag template - still contains `{version}`, resolved at publish
+   * time via `renderArtifactTag()` in `config/publishing.ts`.
+   */
+  tagTemplate: string;
+  /** Resolved `repository.url` for generated package.json / README examples. */
+  repositoryUrl: string;
+  npmRegistry: string;
+  npmAccess: "public" | "restricted";
+  mavenRepositoryId: string;
+  mavenRepositoryUrl: string;
+}
 /**
  * A single artifact a contract generates: a generator recipe from the CLI
  * config, fully resolved (templates interpolated, overrides merged, paths made
@@ -33,10 +58,16 @@ interface ResolvedArtifact {
   generator?: string;
   /** Absolute output directory: `<sdkDir>/<contract>/<id>`. */
   outputDir: string;
-  /** `sdk/svc-<contract>/<id>` */
+  /**
+   * Fully resolved git branch name - convenience alias for
+   * `publishing.branch`.
+   */
   branch: string;
-  /** `svc-<contract>-<id>` */
-  tagPrefix: string;
+  /**
+   * Publishing conventions (branch/tag/registry) for this artifact - see
+   * {@link ResolvedPublishing}.
+   */
+  publishing: ResolvedPublishing;
   additionalProperties: Record<string, string | number | boolean>;
   package?: string;
   goModule?: string;
@@ -73,6 +104,11 @@ interface ResolvedArtifactEntry {
   artifact: ResolvedArtifact;
 }
 interface ResolvedConfig {
+  /**
+   * The config schema version this file targets - see `CONFIG_SCHEMA_VERSION`
+   * in `config/schema.ts`.
+   */
+  configVersion: number;
   /**
    * Directory containing the config file - every relative path in the config
    * (entrypoints, `paths.*`, `readme` templates, ...) resolves against this.
@@ -115,16 +151,39 @@ interface ResolvedConfig {
  * 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`).
+ * 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/publishing.d.ts
+/**
+ * Renders an artifact's final git tag from its `publishing.tagTemplate` -
+ * the one piece of `publishing:` config that can't be resolved at config-load
+ * time, since it needs the artifact's version, which is only known once the
+ * contract's spec has been bundled.
+ *
+ * @param artifact     - The resolved artifact (for `id` and
+ *                       `publishing.tagTemplate`).
+ * @param contractName - The owning contract's name, exposed to the template as
+ *                       `{service}`.
+ * @param version      - The resolved SDK version, exposed to the template as
+ *                       `{version}`.
+ * @param github       - `{ owner, repo }`, exposed as `{github.owner}`/
+ *                       `{github.repo}`.
+ * @param vars         - The config's `vars:` tree, exposed as `{vars.*}`.
+ * @returns The rendered tag name.
+ */
+declare function renderArtifactTag(artifact: ResolvedArtifact, contractName: string, version: string, github: {
+  owner: string;
+  repo: string;
+}, vars: VarsTree): string;
+//#endregion
 //#region src/config/resolve-config-file.d.ts
 /**
  * Config filenames CLI recognizes, checked in this order.
@@ -142,7 +201,7 @@ declare const CONFIG_FILENAMES: readonly [".seagull", ".seagull.yaml", ".seagull
  */
 declare function resolveConfigPath(cwd: string): string;
 //#endregion
-//#region src/core/generator/types.d.ts
+//#region src/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 {
@@ -170,7 +229,7 @@ interface GenerateContext {
   specInputPath: string;
 }
 //#endregion
-//#region src/core/generator/generator.d.ts
+//#region src/generator/generator.d.ts
 /**
  * The root primitive every concrete SDK generator implements.
  *
@@ -200,7 +259,7 @@ declare abstract class Generator {
   abstract generate(ctx: GenerateContext): Promise<void>;
 }
 //#endregion
-//#region src/core/generator/registry.d.ts
+//#region src/generator/registry.d.ts
 /**
  * Looks up the concrete {@link Generator} implementation for a given tool name.
  */
@@ -229,25 +288,7 @@ declare class GeneratorRegistry {
   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
+//#region src/process/exec.d.ts
 /**
  * Runs a command to completion, streaming its stdio straight through
  * (`inherit`), and rejects if it exits non-zero.
@@ -274,6 +315,173 @@ declare function run(command: string, args: string[], cwd: string): Promise<void
  */
 declare function runSync(command: string, args: string[], cwd: string): number;
 //#endregion
+//#region src/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/git/git.d.ts
+/**
+ * The result of executing a git command.
+ *
+ * @see {@link git} - The function that executes the git command.
+ */
+interface GitResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+/**
+ * Execute a git command in a given working directory and return the result.
+ *
+ * @param args - The command-line arguments to pass to the git command.
+ * @param cwd  - The working directory in which to execute the git command.
+ * @returns The result of the git command.
+ *
+ * @see {@link GitResult} - The result of executing the git command.
+ */
+declare function git(args: string[], cwd: string): GitResult;
+/**
+ * Check if a remote branch exists in the given repository.
+ *
+ * @param repoRoot - The root directory of the repository.
+ * @param branch   - The name of the branch to check.
+ * @returns Whether the remote branch exists (true) or not (false).
+ */
+declare function remoteBranchExists(repoRoot: string, branch: string): boolean;
+/**
+ * Check if a remote tag exists in the given repository.
+ *
+ * @param repoRoot - The root directory of the repository.
+ * @param tag      - The name of the tag to check.
+ * @returns Whether the remote tag exists (true) or not (false).
+ */
+declare function tagExists(repoRoot: string, tag: string): boolean;
+/**
+ * Read a single file's content as it existed at a given git tag, without
+ * checking out a worktree.
+ *
+ * Returns `null` (rather than throwing) both when the tag can't be fetched and
+ * when the tag exists but doesn't contain the requested file - the latter is
+ * expected for tags published before that file was introduced, and callers
+ * should treat "unknown" the same as "no mismatch to report".
+ *
+ * @param repoRoot - The root directory of the repository.
+ * @param tag      - The tag to read the file from.
+ * @param filePath - The path of the file within that tag's tree.
+ * @returns The file's content, or `null` if it couldn't be read.
+ */
+declare function readFileAtTag(repoRoot: string, tag: string, filePath: string): string | null;
+/**
+ * Require that a git command succeeded, throwing an error with the given
+ * message if it did not.
+ *
+ * @param result  - The result of the git command to check.
+ * @param message - The error message to throw if the command failed.
+ * @throws Error if the git command failed (non-zero exit code).
+ */
+declare function requireOk(result: GitResult, message: string): void;
+//#endregion
+//#region src/version/version.d.ts
+/**
+ * Shape of a bundled OpenAPI document, narrowed to the one field this module
+ * cares about.
+ */
+interface BundledSpec {
+  info?: {
+    version?: string;
+  };
+}
+/**
+ * Resolves the version to stamp onto a single contract's generated SDK
+ * artifacts (npm/Maven packages, Go module tags, git branches, etc.).
+ *
+ * The single source of truth is that contract's own `info.version` field in its
+ * `openapi.yaml` - bump it there and every artifact, package, and git tag for
+ * that contract picks up the new version on the next release. Versions are
+ * resolved independently per contract: two services can be at different
+ * versions at the same time.
+ *
+ * `SDK_VERSION_OVERRIDE` (wired up from the release workflow's manual `version`
+ * input) bypasses the spec entirely and stamps every contract with the same
+ * given value. It exists for one-off emergency republishes, not routine
+ * releases. Routine releases should always go through `info.version`.
+ *
+ * @param spec         - The parsed, bundled OpenAPI document for the contract.
+ * @param contractName - The contract name, used only for the error message.
+ * @returns The resolved version string (no leading `v`).
+ * @throws Error if no override is set and the spec has no `info.version`.
+ */
+declare function resolveVersion(spec: BundledSpec, contractName: string): string;
+/**
+ * Computes a stable content hash of a bundled OpenAPI document's raw JSON text.
+ * Stamped alongside `VERSION` into every generated SDK package so
+ * `publish-sdk.ts` can tell a genuine no-op republish (same spec, same version)
+ * apart from a spec that changed without its `info.version` being bumped.
+ *
+ * @param raw - The raw bundled spec file contents (JSON text).
+ * @returns A `sha256` hex digest of the raw contents.
+ */
+declare function hashSpec(raw: string): string;
+//#endregion
+//#region src/readme/readme-renderer.d.ts
+interface RenderReadmeArgs {
+  contract: ResolvedContract;
+  artifact: ResolvedArtifact;
+  version: string;
+  github: {
+    owner: string;
+    repo: string;
+  };
+  vars: VarsTree;
+}
+/**
+ * Renders the root-level `README.md` for a generated SDK package.
+ *
+ * If the artifact has a `readme:` path configured (resolved at config-load time
+ * to `artifact.readmeTemplate`), that file is read and interpolated with the
+ * same `{...}` placeholder engine naming templates use - `{service}`,
+ * `{title}`, `{version}`, `{vars.*}`, `{github.owner}`, `{github.repo}`, plus
+ * `{artifact.*}` (id/lang/kind/package/goModule/goPackageName/maven.groupId/
+ * maven.artifactId/branch/tag/npmRegistry/mavenRepositoryUrl). Otherwise,
+ * falls back to a built-in default template for the artifact's language/kind.
+ *
+ * @param args - The contract, artifact, version, and github/vars context to
+ *               render for.
+ * @returns The rendered README content.
+ */
+declare function renderReadme(args: RenderReadmeArgs): Promise<string>;
+//#endregion
+//#region src/redocly/redocly-sync.d.ts
+/**
+ * Regenerates `redocly.yaml`'s `apis:` section from the resolved CLI config,
+ * merging it with the hand-authored `extends`/`rules` in `redocly.base.yaml`.
+ *
+ * The CLI config stays the single source of truth for which APIs exist and
+ * where their TypeScript server types land, instead of that being duplicated
+ * by hand into `redocly.yaml`.
+ *
+ * Called at the start of every command that shells out to `redocly` or
+ * `openapi-typescript` (both read `redocly.yaml` directly), so it's always
+ * up to date before those tools run.
+ *
+ * @param config - The resolved CLI config.
+ */
+declare function syncRedoclyConfig(config: ResolvedConfig): Promise<void>;
+//#endregion
 //#region src/generators/openapi-generator-cli/openapi-generator-cli.generator.d.ts
 /**
  * Wraps `openapi-generator-cli` - the single tool implementation behind every
@@ -301,14 +509,944 @@ declare class OpenApiGeneratorCli extends Generator {
 declare class OpenApiTypescriptGenerator extends Generator {
   readonly tool: SdkTool;
   prepare({ rootDir, entries }: PrepareContext): Promise<void>;
-  generate({ contract, artifact, version, github }: GenerateContext): Promise<void>;
+  generate({ contract, artifact, version }: GenerateContext): Promise<void>;
 }
 //#endregion
+//#region node_modules/.pnpm/commander@15.0.0/node_modules/commander/typings/index.d.ts
+// Type definitions for commander
+// Original definitions by: Alan Agius <https://github.com/alan-agius4>, Marcelo Dezem <https://github.com/mdezem>, vvakame <https://github.com/vvakame>, Jules Randolph <https://github.com/sveinburne>
+/* eslint-disable @typescript-eslint/no-explicit-any */
+// This is a trick to encourage editor to suggest the known literals while still
+// allowing any BaseType value.
+// References:
+// - https://github.com/microsoft/TypeScript/issues/29729
+// - https://github.com/sindresorhus/type-fest/blob/main/source/literal-union.d.ts
+// - https://github.com/sindresorhus/type-fest/blob/main/source/primitive.d.ts
+type LiteralUnion<LiteralType, BaseType extends string | number> = LiteralType | (BaseType & Record<never, never>);
+declare class CommanderError extends Error {
+  code: string;
+  exitCode: number;
+  message: string;
+  nestedError?: string;
+  /**
+   * Constructs the CommanderError class
+   * @param exitCode - suggested exit code which could be used with process.exit
+   * @param code - an id string representing the error
+   * @param message - human-readable description of the error
+   */
+  constructor(exitCode: number, code: string, message: string);
+}
+interface ErrorOptions {
+  // optional parameter for error()
+  /** an id string representing the error */
+  code?: string;
+  /** suggested exit code which could be used with process.exit */
+  exitCode?: number;
+}
+declare class Argument {
+  description: string;
+  required: boolean;
+  variadic: boolean;
+  defaultValue?: any;
+  defaultValueDescription?: string;
+  parseArg?: <T>(value: string, previous: T) => T;
+  argChoices?: string[];
+  /**
+   * Initialize a new command argument with the given name and description.
+   * The default is that the argument is required, and you can explicitly
+   * indicate this with <> around the name. Put [] around the name for an optional argument.
+   */
+  constructor(arg: string, description?: string);
+  /**
+   * Return argument name.
+   */
+  name(): string;
+  /**
+   * Set the default value, and optionally supply the description to be displayed in the help.
+   */
+  default(value: unknown, description?: string): this;
+  /**
+   * Set the custom handler for processing CLI command arguments into argument values.
+   */
+  argParser<T>(fn: (value: string, previous: T) => T): this;
+  /**
+   * Only allow argument value to be one of choices.
+   */
+  choices(values: readonly string[]): this;
+  /**
+   * Make argument required.
+   */
+  argRequired(): this;
+  /**
+   * Make argument optional.
+   */
+  argOptional(): this;
+}
+declare class Option {
+  flags: string;
+  description: string;
+  required: boolean; // A value must be supplied when the option is specified.
+  optional: boolean; // A value is optional when the option is specified.
+  variadic: boolean;
+  mandatory: boolean; // The option must have a value after parsing, which usually means it must be specified on command line.
+  short?: string;
+  long?: string;
+  negate: boolean;
+  defaultValue?: any;
+  defaultValueDescription?: string;
+  presetArg?: unknown;
+  envVar?: string;
+  parseArg?: <T>(value: string, previous: T) => T;
+  hidden: boolean;
+  argChoices?: string[];
+  helpGroupHeading?: string;
+  constructor(flags: string, description?: string);
+  /**
+   * Set the default value, and optionally supply the description to be displayed in the help.
+   */
+  default(value: unknown, description?: string): this;
+  /**
+   * Preset to use when option used without option-argument, especially optional but also boolean and negated.
+   * The custom processing (parseArg) is called.
+   *
+   * @example
+   * ```ts
+   * new Option('--color').default('GREYSCALE').preset('RGB');
+   * new Option('--donate [amount]').preset('20').argParser(parseFloat);
+   * ```
+   */
+  preset(arg: unknown): this;
+  /**
+   * Add option name(s) that conflict with this option.
+   * An error will be displayed if conflicting options are found during parsing.
+   *
+   * @example
+   * ```ts
+   * new Option('--rgb').conflicts('cmyk');
+   * new Option('--js').conflicts(['ts', 'jsx']);
+   * ```
+   */
+  conflicts(names: string | string[]): this;
+  /**
+   * Specify implied option values for when this option is set and the implied options are not.
+   *
+   * The custom processing (parseArg) is not called on the implied values.
+   *
+   * @example
+   * program
+   *   .addOption(new Option('--log', 'write logging information to file'))
+   *   .addOption(new Option('--trace', 'log extra details').implies({ log: 'trace.txt' }));
+   */
+  implies(optionValues: OptionValues): this;
+  /**
+   * Set environment variable to check for option value.
+   *
+   * An environment variables is only used if when processed the current option value is
+   * undefined, or the source of the current value is 'default' or 'config' or 'env'.
+   */
+  env(name: string): this;
+  /**
+   * Set the custom handler for processing CLI option arguments into option values.
+   */
+  argParser<T>(fn: (value: string, previous: T) => T): this;
+  /**
+   * Whether the option is mandatory and must have a value after parsing.
+   */
+  makeOptionMandatory(mandatory?: boolean): this;
+  /**
+   * Hide option in help.
+   */
+  hideHelp(hide?: boolean): this;
+  /**
+   * Only allow option value to be one of choices.
+   */
+  choices(values: readonly string[]): this;
+  /**
+   * Return option name.
+   */
+  name(): string;
+  /**
+   * Return option name, in a camelcase format that can be used
+   * as an object attribute key.
+   */
+  attributeName(): string;
+  /**
+   * Set the help group heading.
+   */
+  helpGroup(heading: string): this;
+  /**
+   * Return whether a boolean option.
+   *
+   * Options are one of boolean, negated, required argument, or optional argument.
+   */
+  isBoolean(): boolean;
+}
+declare class Help {
+  /** output helpWidth, long lines are wrapped to fit */
+  helpWidth?: number;
+  minWidthToWrap: number;
+  sortSubcommands: boolean;
+  sortOptions: boolean;
+  showGlobalOptions: boolean;
+  constructor();
+  /*
+   * prepareContext is called by Commander after applying overrides from `Command.configureHelp()`
+   * and just before calling `formatHelp()`.
+   *
+   * Commander just uses the helpWidth and the others are provided for subclasses.
+   */
+  prepareContext(contextOptions: {
+    error?: boolean;
+    helpWidth?: number;
+    outputHasColors?: boolean;
+  }): void;
+  /** Get the command term to show in the list of subcommands. */
+  subcommandTerm(cmd: Command): string;
+  /** Get the command summary to show in the list of subcommands. */
+  subcommandDescription(cmd: Command): string;
+  /** Get the option term to show in the list of options. */
+  optionTerm(option: Option): string;
+  /** Get the option description to show in the list of options. */
+  optionDescription(option: Option): string;
+  /** Get the argument term to show in the list of arguments. */
+  argumentTerm(argument: Argument): string;
+  /** Get the argument description to show in the list of arguments. */
+  argumentDescription(argument: Argument): string;
+  /** Get the command usage to be displayed at the top of the built-in help. */
+  commandUsage(cmd: Command): string;
+  /** Get the description for the command. */
+  commandDescription(cmd: Command): string;
+  /** Get an array of the visible subcommands. Includes a placeholder for the implicit help command, if there is one. */
+  visibleCommands(cmd: Command): Command[];
+  /** Get an array of the visible options. Includes a placeholder for the implicit help option, if there is one. */
+  visibleOptions(cmd: Command): Option[];
+  /** Get an array of the visible global options. (Not including help.) */
+  visibleGlobalOptions(cmd: Command): Option[];
+  /** Get an array of the arguments which have descriptions. */
+  visibleArguments(cmd: Command): Argument[];
+  /** Get the longest command term length. */
+  longestSubcommandTermLength(cmd: Command, helper: Help): number;
+  /** Get the longest option term length. */
+  longestOptionTermLength(cmd: Command, helper: Help): number;
+  /** Get the longest global option term length. */
+  longestGlobalOptionTermLength(cmd: Command, helper: Help): number;
+  /** Get the longest argument term length. */
+  longestArgumentTermLength(cmd: Command, helper: Help): number;
+  /** Return display width of string, ignoring ANSI escape sequences. Used in padding and wrapping calculations. */
+  displayWidth(str: string): number;
+  /** Style the titles. Called with 'Usage:', 'Options:', etc. */
+  styleTitle(title: string): string;
+  /** Usage: <str> */
+  styleUsage(str: string): string;
+  /** Style for command name in usage string.  */
+  styleCommandText(str: string): string;
+  styleCommandDescription(str: string): string;
+  styleOptionDescription(str: string): string;
+  styleSubcommandDescription(str: string): string;
+  styleArgumentDescription(str: string): string;
+  /** Base style used by descriptions. */
+  styleDescriptionText(str: string): string;
+  styleOptionTerm(str: string): string;
+  styleSubcommandTerm(str: string): string;
+  styleArgumentTerm(str: string): string;
+  /** Base style used in terms and usage for options. */
+  styleOptionText(str: string): string;
+  /** Base style used in terms and usage for subcommands. */
+  styleSubcommandText(str: string): string;
+  /** Base style used in terms and usage for arguments. */
+  styleArgumentText(str: string): string;
+  /** Calculate the pad width from the maximum term length. */
+  padWidth(cmd: Command, helper: Help): number;
+  /**
+   * Wrap a string at whitespace, preserving existing line breaks.
+   * Wrapping is skipped if the width is less than `minWidthToWrap`.
+   */
+  boxWrap(str: string, width: number): string;
+  /** Detect manually wrapped and indented strings by checking for line break followed by whitespace. */
+  preformatted(str: string): boolean;
+  /**
+   * Format the "item", which consists of a term and description. Pad the term and wrap the description, indenting the following lines.
+   *
+   * So "TTT", 5, "DDD DDDD DD DDD" might be formatted for this.helpWidth=17 like so:
+   *   TTT    DDD DDDD
+   *          DD DDD
+   */
+  formatItem(term: string, termWidth: number, description: string, helper: Help): string;
+  /**
+   * Format a list of items, given a heading and an array of formatted items.
+   */
+  formatItemList(heading: string, items: string[], helper: Help): string[];
+  /**
+   * Group items by their help group heading.
+   */
+  groupItems<T extends Command | Option>(unsortedItems: T[], visibleItems: T[], getGroup: (item: T) => string): Map<string, T[]>;
+  /** Generate the built-in help text. */
+  formatHelp(cmd: Command, helper: Help): string;
+}
+type HelpConfiguration = Partial<Help>;
+interface ParseOptions {
+  from: 'node' | 'electron' | 'user';
+}
+interface HelpContext {
+  // optional parameter for .help() and .outputHelp()
+  error: boolean;
+}
+interface AddHelpTextContext {
+  // passed to text function used with .addHelpText()
+  error: boolean;
+  command: Command;
+}
+interface OutputConfiguration {
+  writeOut?(str: string): void;
+  writeErr?(str: string): void;
+  outputError?(str: string, write: (str: string) => void): void;
+  getOutHelpWidth?(): number;
+  getErrHelpWidth?(): number;
+  getOutHasColors?(): boolean;
+  getErrHasColors?(): boolean;
+  stripColor?(str: string): string;
+}
+type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
+type HookEvent = 'preSubcommand' | 'preAction' | 'postAction';
+// The source is a string so author can define their own too.
+type OptionValueSource = LiteralUnion<'default' | 'config' | 'env' | 'cli' | 'implied', string> | undefined;
+type OptionValues = Record<string, any>;
+declare class Command {
+  args: string[];
+  processedArgs: any[];
+  readonly commands: readonly Command[];
+  readonly options: readonly Option[];
+  readonly registeredArguments: readonly Argument[];
+  parent: Command | null;
+  constructor(name?: string);
+  /**
+   * Set the program version to `str`.
+   *
+   * This method auto-registers the "-V, --version" flag
+   * which will print the version number when passed.
+   *
+   * You can optionally supply the  flags and description to override the defaults.
+   */
+  version(str: string, flags?: string, description?: string): this;
+  /**
+   * Get the program version.
+   */
+  version(): string | undefined;
+  /**
+   * Define a command, implemented using an action handler.
+   *
+   * @remarks
+   * The command description is supplied using `.description`, not as a parameter to `.command`.
+   *
+   * @example
+   * ```ts
+   * program
+   *   .command('clone <source> [destination]')
+   *   .description('clone a repository into a newly created directory')
+   *   .action((source, destination) => {
+   *     console.log('clone command called');
+   *   });
+   * ```
+   *
+   * @param nameAndArgs - command name and arguments, args are  `<required>` or `[optional]` and last may also be `variadic...`
+   * @param opts - configuration options
+   * @returns new command
+   */
+  command(nameAndArgs: string, opts?: CommandOptions): ReturnType<this['createCommand']>;
+  /**
+   * Define a command, implemented in a separate executable file.
+   *
+   * @remarks
+   * The command description is supplied as the second parameter to `.command`.
+   *
+   * @example
+   * ```ts
+   *  program
+   *    .command('start <service>', 'start named service')
+   *    .command('stop [service]', 'stop named service, or all if no name supplied');
+   * ```
+   *
+   * @param nameAndArgs - command name and arguments, args are  `<required>` or `[optional]` and last may also be `variadic...`
+   * @param description - description of executable command
+   * @param opts - configuration options
+   * @returns `this` command for chaining
+   */
+  command(nameAndArgs: string, description: string, opts?: ExecutableCommandOptions): this;
+  /**
+   * Factory routine to create a new unattached command.
+   *
+   * See .command() for creating an attached subcommand, which uses this routine to
+   * create the command. You can override createCommand to customise subcommands.
+   */
+  createCommand(name?: string): Command;
+  /**
+   * Add a prepared subcommand.
+   *
+   * See .command() for creating an attached subcommand which inherits settings from its parent.
+   *
+   * @returns `this` command for chaining
+   */
+  addCommand(cmd: Command, opts?: CommandOptions): this;
+  /**
+   * Factory routine to create a new unattached argument.
+   *
+   * See .argument() for creating an attached argument, which uses this routine to
+   * create the argument. You can override createArgument to return a custom argument.
+   */
+  createArgument(name: string, description?: string): Argument;
+  /**
+   * Define argument syntax for command.
+   *
+   * The default is that the argument is required, and you can explicitly
+   * indicate this with <> around the name. Put [] around the name for an optional argument.
+   *
+   * @example
+   * ```
+   * program.argument('<input-file>');
+   * program.argument('[output-file]');
+   * ```
+   *
+   * @returns `this` command for chaining
+   */
+  argument<T>(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this;
+  argument(name: string, description?: string, defaultValue?: unknown): this;
+  /**
+   * Define argument syntax for command, adding a prepared argument.
+   *
+   * @returns `this` command for chaining
+   */
+  addArgument(arg: Argument): this;
+  /**
+   * Define argument syntax for command, adding multiple at once (without descriptions).
+   *
+   * See also .argument().
+   *
+   * @example
+   * ```
+   * program.arguments('<cmd> [env]');
+   * ```
+   *
+   * @returns `this` command for chaining
+   */
+  arguments(names: string): this;
+  /**
+   * Customise or override default help command. By default a help command is automatically added if your command has subcommands.
+   *
+   * @example
+   * ```ts
+   * program.helpCommand('help [cmd]');
+   * program.helpCommand('help [cmd]', 'show help');
+   * program.helpCommand(false); // suppress default help command
+   * program.helpCommand(true); // add help command even if no subcommands
+   * ```
+   */
+  helpCommand(nameAndArgs: string, description?: string): this;
+  helpCommand(enable: boolean): this;
+  /**
+   * Add prepared custom help command.
+   */
+  addHelpCommand(cmd: Command): this;
+  /** @deprecated since v12, instead use helpCommand */
+  addHelpCommand(nameAndArgs: string, description?: string): this;
+  /** @deprecated since v12, instead use helpCommand */
+  addHelpCommand(enable?: boolean): this;
+  /**
+   * Add hook for life cycle event.
+   */
+  hook(event: HookEvent, listener: (thisCommand: Command, actionCommand: Command) => void | Promise<void>): this;
+  /**
+   * Register callback to use as replacement for calling process.exit.
+   */
+  exitOverride(callback?: (err: CommanderError) => never | void): this;
+  /**
+   * Display error message and exit (or call exitOverride).
+   */
+  error(message: string, errorOptions?: ErrorOptions): never;
+  /**
+   * You can customise the help with a subclass of Help by overriding createHelp,
+   * or by overriding Help properties using configureHelp().
+   */
+  createHelp(): Help;
+  /**
+   * You can customise the help by overriding Help properties using configureHelp(),
+   * or with a subclass of Help by overriding createHelp().
+   */
+  configureHelp(configuration: HelpConfiguration): this;
+  /** Get configuration */
+  configureHelp(): HelpConfiguration;
+  /**
+   * The default output goes to stdout and stderr. You can customise this for special
+   * applications. You can also customise the display of errors by overriding outputError.
+   *
+   * The configuration properties are all functions:
+   * ```
+   * // functions to change where being written, stdout and stderr
+   * writeOut(str)
+   * writeErr(str)
+   * // matching functions to specify width for wrapping help
+   * getOutHelpWidth()
+   * getErrHelpWidth()
+   * // functions based on what is being written out
+   * outputError(str, write) // used for displaying errors, and not used for displaying help
+   * ```
+   */
+  configureOutput(configuration: OutputConfiguration): this;
+  /** Get configuration */
+  configureOutput(): OutputConfiguration;
+  /**
+   * Copy settings that are useful to have in common across root command and subcommands.
+   *
+   * (Used internally when adding a command using `.command()` so subcommands inherit parent settings.)
+   */
+  copyInheritedSettings(sourceCommand: Command): this;
+  /**
+   * Display the help or a custom message after an error occurs.
+   */
+  showHelpAfterError(displayHelp?: boolean | string): this;
+  /**
+   * Display suggestion of similar commands for unknown commands, or options for unknown options.
+   */
+  showSuggestionAfterError(displaySuggestion?: boolean): this;
+  /**
+   * Register callback `fn` for the command.
+   *
+   * @example
+   * ```
+   * program
+   *   .command('serve')
+   *   .description('start service')
+   *   .action(function() {
+   *     // do work here
+   *   });
+   * ```
+   *
+   * @returns `this` command for chaining
+   */
+  action(fn: (this: this, ...args: any[]) => void | Promise<void>): this;
+  /**
+   * Define option with `flags`, `description`, and optional argument parsing function or `defaultValue` or both.
+   *
+   * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space. A required
+   * option-argument is indicated by `<>` and an optional option-argument by `[]`.
+   *
+   * See the README for more details, and see also addOption() and requiredOption().
+   *
+   * @example
+   *
+   * ```js
+   * program
+   *     .option('-p, --pepper', 'add pepper')
+   *     .option('--pt, --pizza-type <TYPE>', 'type of pizza') // required option-argument
+   *     .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default
+   *     .option('-t, --tip <VALUE>', 'add tip to purchase cost', parseFloat) // custom parse function
+   * ```
+   *
+   * @returns `this` command for chaining
+   */
+  option(flags: string, description?: string, defaultValue?: string | boolean | string[]): this;
+  option<T>(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this;
+  /** @deprecated since v7, instead use choices or a custom function */
+  option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this;
+  /**
+   * Define a required option, which must have a value after parsing. This usually means
+   * the option must be specified on the command line. (Otherwise the same as .option().)
+   *
+   * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space.
+   */
+  requiredOption(flags: string, description?: string, defaultValue?: string | boolean | string[]): this;
+  requiredOption<T>(flags: string, description: string, parseArg: (value: string, previous: T) => T, defaultValue?: T): this;
+  /** @deprecated since v7, instead use choices or a custom function */
+  requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this;
+  /**
+   * Factory routine to create a new unattached option.
+   *
+   * See .option() for creating an attached option, which uses this routine to
+   * create the option. You can override createOption to return a custom option.
+   */
+  createOption(flags: string, description?: string): Option;
+  /**
+   * Add a prepared Option.
+   *
+   * See .option() and .requiredOption() for creating and attaching an option in a single call.
+   */
+  addOption(option: Option): this;
+  /**
+   * Whether to store option values as properties on command object,
+   * or store separately (specify false). In both cases the option values can be accessed using .opts().
+   *
+   * @returns `this` command for chaining
+   */
+  storeOptionsAsProperties<T extends OptionValues>(): this & T;
+  storeOptionsAsProperties<T extends OptionValues>(storeAsProperties: true): this & T;
+  storeOptionsAsProperties(storeAsProperties?: boolean): this;
+  /**
+   * Retrieve option value.
+   */
+  getOptionValue(key: string): any;
+  /**
+   * Store option value.
+   */
+  setOptionValue(key: string, value: unknown): this;
+  /**
+   * Store option value and where the value came from.
+   */
+  setOptionValueWithSource(key: string, value: unknown, source: OptionValueSource): this;
+  /**
+   * Get source of option value.
+   */
+  getOptionValueSource(key: string): OptionValueSource | undefined;
+  /**
+   * Get source of option value. See also .optsWithGlobals().
+   */
+  getOptionValueSourceWithGlobals(key: string): OptionValueSource | undefined;
+  /**
+   * Alter parsing of short flags with optional values.
+   *
+   * @example
+   * ```
+   * // for `.option('-f,--flag [value]'):
+   * .combineFlagAndOptionalValue(true)  // `-f80` is treated like `--flag=80`, this is the default behaviour
+   * .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b`
+   * ```
+   *
+   * @returns `this` command for chaining
+   */
+  combineFlagAndOptionalValue(combine?: boolean): this;
+  /**
+   * Allow unknown options on the command line.
+   *
+   * @returns `this` command for chaining
+   */
+  allowUnknownOption(allowUnknown?: boolean): this;
+  /**
+   * Allow excess command-arguments on the command line. Pass false to make excess arguments an error.
+   *
+   * @returns `this` command for chaining
+   */
+  allowExcessArguments(allowExcess?: boolean): this;
+  /**
+   * Enable positional options. Positional means global options are specified before subcommands which lets
+   * subcommands reuse the same option names, and also enables subcommands to turn on passThroughOptions.
+   *
+   * The default behaviour is non-positional and global options may appear anywhere on the command line.
+   *
+   * @returns `this` command for chaining
+   */
+  enablePositionalOptions(positional?: boolean): this;
+  /**
+   * Pass through options that come after command-arguments rather than treat them as command-options,
+   * so actual command-options come before command-arguments. Turning this on for a subcommand requires
+   * positional options to have been enabled on the program (parent commands).
+   *
+   * The default behaviour is non-positional and options may appear before or after command-arguments.
+   *
+   * @returns `this` command for chaining
+   */
+  passThroughOptions(passThrough?: boolean): this;
+  /**
+   * Parse `argv`, setting options and invoking commands when defined.
+   *
+   * Use parseAsync instead of parse if any of your action handlers are async.
+   *
+   * Call with no parameters to parse `process.argv`. Detects Electron and special node options like `node --eval`. Easy mode!
+   *
+   * Or call with an array of strings to parse, and optionally where the user arguments start by specifying where the arguments are `from`:
+   * - `'node'`: default, `argv[0]` is the application and `argv[1]` is the script being run, with user arguments after that
+   * - `'electron'`: `argv[0]` is the application and `argv[1]` varies depending on whether the electron application is packaged
+   * - `'user'`: just user arguments
+   *
+   * @example
+   * ```
+   * program.parse(); // parse process.argv and auto-detect electron and special node flags
+   * program.parse(process.argv); // assume argv[0] is app and argv[1] is script
+   * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * ```
+   *
+   * @returns `this` command for chaining
+   */
+  parse(argv?: readonly string[], parseOptions?: ParseOptions): this;
+  /**
+   * Parse `argv`, setting options and invoking commands when defined.
+   *
+   * Call with no parameters to parse `process.argv`. Detects Electron and special node options like `node --eval`. Easy mode!
+   *
+   * Or call with an array of strings to parse, and optionally where the user arguments start by specifying where the arguments are `from`:
+   * - `'node'`: default, `argv[0]` is the application and `argv[1]` is the script being run, with user arguments after that
+   * - `'electron'`: `argv[0]` is the application and `argv[1]` varies depending on whether the electron application is packaged
+   * - `'user'`: just user arguments
+   *
+   * @example
+   * ```
+   * await program.parseAsync(); // parse process.argv and auto-detect electron and special node flags
+   * await program.parseAsync(process.argv); // assume argv[0] is app and argv[1] is script
+   * await program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
+   * ```
+   *
+   * @returns Promise
+   */
+  parseAsync(argv?: readonly string[], parseOptions?: ParseOptions): Promise<this>;
+  /**
+   * Called the first time parse is called to save state and allow a restore before subsequent calls to parse.
+   * Not usually called directly, but available for subclasses to save their custom state.
+   *
+   * This is called in a lazy way. Only commands used in parsing chain will have state saved.
+   */
+  saveStateBeforeParse(): void;
+  /**
+   * Restore state before parse for calls after the first.
+   * Not usually called directly, but available for subclasses to save their custom state.
+   *
+   * This is called in a lazy way. Only commands used in parsing chain will have state restored.
+   */
+  restoreStateBeforeParse(): void;
+  /**
+   * Parse options from `argv` removing known options,
+   * and return argv split into operands and unknown arguments.
+   *
+   * Side effects: modifies command by storing options. Does not reset state if called again.
+   *
+   *     argv => operands, unknown
+   *     --known kkk op => [op], []
+   *     op --known kkk => [op], []
+   *     sub --unknown uuu op => [sub], [--unknown uuu op]
+   *     sub -- --unknown uuu op => [sub --unknown uuu op], []
+   */
+  parseOptions(argv: string[]): ParseOptionsResult;
+  /**
+   * Return an object containing local option values as key-value pairs
+   */
+  opts<T extends OptionValues>(): T;
+  /**
+   * Return an object containing merged local and global option values as key-value pairs.
+   */
+  optsWithGlobals<T extends OptionValues>(): T;
+  /**
+   * Set the description.
+   *
+   * @returns `this` command for chaining
+   */
+  description(str: string): this;
+  /** @deprecated since v8, instead use .argument to add command argument with description */
+  description(str: string, argsDescription: Record<string, string>): this;
+  /**
+   * Get the description.
+   */
+  description(): string;
+  /**
+   * Set the summary. Used when listed as subcommand of parent.
+   *
+   * @returns `this` command for chaining
+   */
+  summary(str: string): this;
+  /**
+   * Get the summary.
+   */
+  summary(): string;
+  /**
+   * Set an alias for the command.
+   *
+   * You may call more than once to add multiple aliases. Only the first alias is shown in the auto-generated help.
+   *
+   * @returns `this` command for chaining
+   */
+  alias(alias: string): this;
+  /**
+   * Get alias for the command.
+   */
+  alias(): string;
+  /**
+   * Set aliases for the command.
+   *
+   * Only the first alias is shown in the auto-generated help.
+   *
+   * @returns `this` command for chaining
+   */
+  aliases(aliases: readonly string[]): this;
+  /**
+   * Get aliases for the command.
+   */
+  aliases(): string[];
+  /**
+   * Set the command usage.
+   *
+   * @returns `this` command for chaining
+   */
+  usage(str: string): this;
+  /**
+   * Get the command usage.
+   */
+  usage(): string;
+  /**
+   * Set the name of the command.
+   *
+   * @returns `this` command for chaining
+   */
+  name(str: string): this;
+  /**
+   * Get the name of the command.
+   */
+  name(): string;
+  /**
+   * Set the name of the command from script filename, such as process.argv[1],
+   * or import.meta.filename.
+   *
+   * (Used internally and public although not documented in README.)
+   *
+   * @example
+   * ```ts
+   * program.nameFromFilename(import.meta.filename);
+   * ```
+   *
+   * @returns `this` command for chaining
+   */
+  nameFromFilename(filename: string): this;
+  /**
+   * Set the directory for searching for executable subcommands of this command.
+   *
+   * @example
+   * ```ts
+   * program.executableDir(import.meta.dirname);
+   * // or
+   * program.executableDir('subcommands');
+   * ```
+   *
+   * @returns `this` command for chaining
+   */
+  executableDir(path: string): this;
+  /**
+   * Get the executable search directory.
+   */
+  executableDir(): string | null;
+  /**
+   * Set the help group heading for this subcommand in parent command's help.
+   *
+   * @returns `this` command for chaining
+   */
+  helpGroup(heading: string): this;
+  /**
+   * Get the help group heading for this subcommand in parent command's help.
+   */
+  helpGroup(): string;
+  /**
+   * Set the default help group heading for subcommands added to this command.
+   * (This does not override a group set directly on the subcommand using .helpGroup().)
+   *
+   * @example
+   * program.commandsGroup('Development Commands:);
+   * program.command('watch')...
+   * program.command('lint')...
+   * ...
+   *
+   * @returns `this` command for chaining
+   */
+  commandsGroup(heading: string): this;
+  /**
+   * Get the default help group heading for subcommands added to this command.
+   */
+  commandsGroup(): string;
+  /**
+   * Set the default help group heading for options added to this command.
+   * (This does not override a group set directly on the option using .helpGroup().)
+   *
+   * @example
+   * program
+   *   .optionsGroup('Development Options:')
+   *   .option('-d, --debug', 'output extra debugging')
+   *   .option('-p, --profile', 'output profiling information')
+   *
+   * @returns `this` command for chaining
+   */
+  optionsGroup(heading: string): this;
+  /**
+   * Get the default help group heading for options added to this command.
+   */
+  optionsGroup(): string;
+  /**
+   * Output help information for this command.
+   *
+   * Outputs built-in help, and custom text added using `.addHelpText()`.
+   *
+   */
+  outputHelp(context?: HelpContext): void;
+  /** @deprecated since v7 */
+  outputHelp(cb: (str: string) => string): void;
+  /**
+   * Return command help documentation.
+   */
+  helpInformation(context?: HelpContext): string;
+  /**
+   * You can pass in flags and a description to override the help
+   * flags and help description for your command. Pass in false
+   * to disable the built-in help option.
+   */
+  helpOption(flags?: string | boolean, description?: string): this;
+  /**
+   * Supply your own option to use for the built-in help option.
+   * This is an alternative to using helpOption() to customise the flags and description etc.
+   */
+  addHelpOption(option: Option): this;
+  /**
+   * Output help information and exit.
+   *
+   * Outputs built-in help, and custom text added using `.addHelpText()`.
+   */
+  help(context?: HelpContext): never;
+  /** @deprecated since v7 */
+  help(cb: (str: string) => string): never;
+  /**
+   * Add additional text to be displayed with the built-in help.
+   *
+   * Position is 'before' or 'after' to affect just this command,
+   * and 'beforeAll' or 'afterAll' to affect this command and all its subcommands.
+   */
+  addHelpText(position: AddHelpTextPosition, text: string): this;
+  addHelpText(position: AddHelpTextPosition, text: (context: AddHelpTextContext) => string): this;
+  /**
+   * Add a listener (callback) for when events occur. (Implemented using EventEmitter.)
+   */
+  on(event: string | symbol, listener: (...args: any[]) => void): this;
+}
+interface CommandOptions {
+  hidden?: boolean;
+  isDefault?: boolean;
+  /** @deprecated since v7, replaced by hidden */
+  noHelp?: boolean;
+}
+interface ExecutableCommandOptions extends CommandOptions {
+  executableFile?: string;
+}
+interface ParseOptionsResult {
+  operands: string[];
+  unknown: string[];
+}
+//#endregion
+//#region packages/cli/dist/index.d.mts
+//#region src/program.d.ts
+interface ProgramMetadata {
+  name: string;
+  version: string;
+  description: string;
+}
+/**
+ * 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()`.
+ */
+declare function createProgram(metadata: ProgramMetadata): Command;
+//#endregion
 //#region src/commands/bundle.d.ts
 /**
  * Bundles every contract's OpenAPI spec into `dist/specs/<contract>.json`.
  *
- * @param config - The resolved CLI config.
+ * @param config - The resolved seagull config.
  */
 declare function bundleCommand(config: ResolvedConfig): Promise<void>;
 //#endregion
@@ -316,15 +1454,17 @@ declare function bundleCommand(config: ResolvedConfig): Promise<void>;
 /**
  * Removes the entire `dist` output directory.
  *
- * @param config - The resolved CLI config.
+ * @param config - The resolved seagull 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`.
+ * Delegates to `@octalmesh/seagull-docs` - see that package for the actual
+ * implementation.
  *
- * @param config - The resolved CLI config.
+ * @param config - The resolved seagull config.
  */
 declare function generateDocsCommand(config: ResolvedConfig): Promise<void>;
 //#endregion
@@ -341,7 +1481,7 @@ declare function generateSdkCommand(config: ResolvedConfig): Promise<void>;
  * Lints every contract's OpenAPI spec.
  * Sets `process.exitCode = 1` if any contract fails.
  *
- * @param config - The resolved CLI config.
+ * @param config - The resolved seagull config.
  */
 declare function lintCommand(config: ResolvedConfig): Promise<void>;
 //#endregion
@@ -370,7 +1510,8 @@ interface PublishSdkOptions {
 }
 /**
  * Redistributes each generated artifact's `dist/sdk/<contract>/<artifact-id>`
- * into its own orphan branch (`sdk/svc-<contract>/<artifact-id>`) and tags the
+ * into its own orphan branch (per the artifact's resolved `publishing.branch`)
+ * and tags the
  * publish.
  *
  * @param config  - The resolved CLI config.
@@ -381,11 +1522,35 @@ declare function publishSdkCommand(config: ResolvedConfig, options?: PublishSdkO
 //#region src/commands/serve-docs.d.ts
 /**
  * Serves the generated documentation site (`dist/docs`) over plain HTTP for
- * local previewing.
+ * local previewing. Delegates to `@octalmesh/seagull-docs`.
  *
- * @param config - The resolved CLI config.
+ * @param config - The resolved seagull 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 };
+//#region packages/docs/dist/index.d.mts
+//#region src/generate-docs.d.ts
+/**
+ * Generates the documentation website for every contract into `dist/docs`.
+ *
+ * Currently, a thin wrapper around Scalar's standalone bundle - a placeholder
+ * pending a fully custom docs UI. The `generateDocsSite`/`serveDocsSite`
+ * function signatures are the stable boundary the CLI's `docs generate`/
+ * `docs serve` commands call through, so that future rewrite stays contained
+ * to this package.
+ *
+ * @param config - The resolved seagull config.
+ */
+declare function generateDocsSite(config: ResolvedConfig): Promise<void>;
+//#endregion
+//#region src/serve-docs.d.ts
+/**
+ * Serves the generated documentation site (`dist/docs`) over plain HTTP for
+ * local previewing.
+ *
+ * @param config - The resolved seagull config.
+ */
+declare function serveDocsSite(config: ResolvedConfig): Promise<void>;
+//#endregion
+export { type BundledSpec, CONFIG_FILENAMES, CONFIG_SCHEMA_VERSION, type GenerateContext, Generator, GeneratorRegistry, type GitResult, OpenApiGeneratorCli, OpenApiTypescriptGenerator, type PrepareContext, type ProgramMetadata, type PublishRegistriesOptions, type PublishSdkOptions, type RenderReadmeArgs, type ResolvedArtifact, type ResolvedArtifactEntry, type ResolvedConfig, type ResolvedContract, type ResolvedPublishing, type SdkKind, type SdkLang, type SdkTool, type VarsTree, bundleCommand, cleanCommand, createProgram, generateDocsCommand, generateDocsSite, generateSdkCommand, git, hashSpec, lintCommand, loadConfig, publishRegistriesCommand, publishSdkCommand, readFileAtTag, remoteBranchExists, renderArtifactTag, renderReadme, requireOk, resolveBinPath, resolveConfigPath, resolveVersion, run, runSync, serveDocsCommand, serveDocsSite, syncRedoclyConfig, tagExists };
 //# sourceMappingURL=index.d.mts.map