@octalmesh/seagull-core 0.0.2

package/src/readme/default-templates.ts

@@ -0,0 +1,300 @@
+import { renderArtifactTag } from "../config/publishing";
+import type {
+  ResolvedArtifact,
+  ResolvedContract,
+  VarsTree,
+} from "../config/types";
+
+export interface DefaultReadmeArgs {
+  contract: ResolvedContract;
+  artifact: ResolvedArtifact;
+  version: string;
+  github: { owner: string; repo: string };
+  vars: VarsTree;
+}
+
+/**
+ * Renders a sensible default `README.md` for a generated SDK package, used
+ * whenever the artifact has no custom `readme:` template configured. Covers
+ * every built-in `lang`/`kind` combination; anything more specific (house
+ * install instructions, extra usage notes) belongs in a custom template
+ * instead - see `readme-renderer.ts`. Registry URLs and branch/tag names
+ * come from the artifact's resolved `publishing:` config, so a repo that
+ * overrides its registry sees that reflected here automatically.
+ *
+ * @param args - The contract, artifact, version, and github/vars coordinates
+ *               to render for.
+ * @returns The rendered README content.
+ */
+export function renderDefaultReadme({
+  contract,
+  artifact,
+  version,
+  github,
+  vars,
+}: DefaultReadmeArgs): string {
+  const header = `# ${contract.title} - ${label(artifact)}
+
+> Generated from \`${contract.entrypointRelative}\` in [${github.owner}/${github.repo}](https://github.com/${github.owner}/${github.repo}).
+> Do not edit by hand - this package is regenerated and republished on every release.
+
+Version: \`${version}\`
+Source branch: \`${artifact.branch}\`
+`;
+
+  return `${header}\n${body(contract, artifact, version, github, vars)}\n`;
+}
+
+//<editor-fold desc="README Template Helpers" defaultstate="collapsed">
+
+function label(artifact: ResolvedArtifact): string {
+  const lang = { typescript: "TypeScript", go: "Go", java: "Java" }[
+    artifact.lang
+  ];
+  const kind =
+    artifact.kind === "client"
+      ? "Client SDK"
+      : artifact.lang === "typescript"
+        ? "Server Types"
+        : "Server Stubs";
+
+  return `${lang} ${kind}`;
+}
+
+function body(
+  contract: ResolvedContract,
+  artifact: ResolvedArtifact,
+  version: string,
+  github: { owner: string; repo: string },
+  vars: VarsTree,
+): string {
+  switch (`${artifact.lang}-${artifact.kind}`) {
+    case "typescript-client":
+      return tsClient(artifact, version);
+    case "typescript-server":
+      return tsServer(artifact, version);
+    case "go-client":
+      return goClient(contract, artifact, github, vars);
+    case "go-server":
+      return goServer(artifact);
+    case "java-client":
+      return javaClient(artifact, version);
+    case "java-server":
+      return javaServer(artifact, version);
+    default:
+      return "";
+  }
+}
+
+//</editor-fold>
+
+//<editor-fold desc="README Body Templates" defaultstate="collapsed">
+
+function tsClient(artifact: ResolvedArtifact, version: string): string {
+  return `## Install
+
+\`\`\`bash
+npm config set <scope>:registry ${artifact.publishing.npmRegistry}
+npm install ${artifact.package}@${version}
+\`\`\`
+
+(Requires an authenticated \`.npmrc\` with a token for that registry.)
+
+## Usage
+
+\`\`\`ts
+import { Configuration, DefaultApi } from "${artifact.package}";
+
+const api = new DefaultApi(
+  new Configuration({ basePath: "https://api.your-domain.com" }),
+);
+
+const result = await api.someOperation();
+\`\`\`
+`;
+}
+
+function tsServer(artifact: ResolvedArtifact, version: string): string {
+  return `## Install
+
+\`\`\`bash
+npm config set <scope>:registry ${artifact.publishing.npmRegistry}
+npm install --save-dev ${artifact.package}@${version}
+\`\`\`
+
+(Requires an authenticated \`.npmrc\` with a token for that registry.)
+
+## Usage
+
+\`\`\`ts
+import type { components, operations } from "${artifact.package}";
+
+type LoginResponses = operations["login"]["responses"];
+
+// Example: an Express handler typed against the contract
+app.post("/login", (req, res) => {
+  const body = req.body as components["schemas"]["LoginRequest"];
+  const response: LoginResponses[200]["content"]["application/json"] = {
+    // ...
+  };
+  res.json(response);
+});
+\`\`\`
+`;
+}
+
+function goClient(
+  contract: ResolvedContract,
+  artifact: ResolvedArtifact,
+  github: { owner: string; repo: string },
+  vars: VarsTree,
+): string {
+  // Illustrative only - renders the tag template with a literal "<version>"
+  // placeholder rather than an actual version, since this is documentation
+  // text showing the *pattern*, not a specific release.
+  const exampleTag = renderArtifactTag(
+    artifact,
+    contract.name,
+    "<version>",
+    github,
+    vars,
+  );
+
+  return `## Install
+
+Go has no package registry, so this module is pulled directly from its
+publishing branch:
+
+\`\`\`bash
+go get ${artifact.goModule}@${artifact.branch}
+\`\`\`
+
+To pin an exact release instead of the branch head, use the matching tag:
+
+\`\`\`bash
+go get ${artifact.goModule}@${exampleTag}
+\`\`\`
+
+## Usage
+
+\`\`\`go
+import (
+    "context"
+
+    ${artifact.goPackageName} "${artifact.goModule}"
+)
+
+func main() {
+    cfg := ${artifact.goPackageName}.NewConfiguration()
+    client := ${artifact.goPackageName}.NewAPIClient(cfg)
+
+    resp, _, err := client.DefaultAPI.SomeOperation(context.Background()).Execute()
+    _ = resp
+    _ = err
+}
+\`\`\`
+`;
+}
+
+function goServer(artifact: ResolvedArtifact): string {
+  return `## Install
+
+\`\`\`bash
+go get ${artifact.goModule}@${artifact.branch}
+\`\`\`
+
+## Usage
+
+Implement the generated \`${artifact.goPackageName}.*ApiServicer\` interfaces and
+wire them into the generated router:
+
+\`\`\`go
+router := ${artifact.goPackageName}.NewRouter(
+    ${artifact.goPackageName}.NewSomeApiController(yourServiceImpl),
+)
+\`\`\`
+`;
+}
+
+function javaClient(artifact: ResolvedArtifact, version: string): string {
+  return `## Install (Maven)
+
+\`\`\`xml
+<dependency>
+  <groupId>${artifact.maven?.groupId}</groupId>
+  <artifactId>${artifact.maven?.artifactId}</artifactId>
+  <version>${version}</version>
+</dependency>
+\`\`\`
+
+Add the repository to your \`settings.xml\` (or \`pom.xml\`) with credentials
+for that repository:
+
+\`\`\`xml
+<repository>
+  <id>${artifact.publishing.mavenRepositoryId}</id>
+  <url>${artifact.publishing.mavenRepositoryUrl}</url>
+</repository>
+\`\`\`
+
+## Usage
+
+Generated with \`library=restclient\` - Spring's \`RestClient\`, the current
+recommended synchronous HTTP client for Spring apps:
+
+\`\`\`java
+@Configuration
+public class SomeServiceClientConfig {
+
+    @Bean
+    public ApiClient someServiceApiClient(RestClient.Builder builder) {
+        ApiClient client = new ApiClient(builder.build());
+        client.setBasePath("https://api.your-domain.com");
+        return client;
+    }
+
+    @Bean
+    public DefaultApi someServiceApi(ApiClient someServiceApiClient) {
+        return new DefaultApi(someServiceApiClient);
+    }
+}
+\`\`\`
+`;
+}
+
+function javaServer(artifact: ResolvedArtifact, version: string): string {
+  return `## Install (Maven)
+
+\`\`\`xml
+<dependency>
+  <groupId>${artifact.maven?.groupId}</groupId>
+  <artifactId>${artifact.maven?.artifactId}</artifactId>
+  <version>${version}</version>
+</dependency>
+\`\`\`
+
+Add the repository to your \`settings.xml\` (or \`pom.xml\`) with credentials
+for that repository:
+
+\`\`\`xml
+<repository>
+  <id>${artifact.publishing.mavenRepositoryId}</id>
+  <url>${artifact.publishing.mavenRepositoryUrl}</url>
+</repository>
+\`\`\`
+
+## Usage
+
+This artifact only contains the generated Spring \`@RestController\` interfaces
+(\`interfaceOnly=true\`) - implement them in your service:
+
+\`\`\`java
+@RestController
+public class SomeController implements SomeApi {
+    // interface methods generated from the OpenAPI contract
+}
+\`\`\`
+`;
+}
+
+//</editor-fold>

package/src/readme/readme-renderer.ts

@@ -0,0 +1,69 @@
+import { readFile } from "node:fs/promises";
+
+import { renderArtifactTag } from "../config/publishing";
+import { buildTemplateContext, interpolate } from "../config/template";
+import type {
+  ResolvedArtifact,
+  ResolvedContract,
+  VarsTree,
+} from "../config/types";
+import { renderDefaultReadme } from "./default-templates";
+
+export 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.
+ */
+export async function renderReadme(args: RenderReadmeArgs): Promise<string> {
+  if (!args.artifact.readmeTemplate) {
+    return renderDefaultReadme(args);
+  }
+
+  const raw = await readFile(args.artifact.readmeTemplate, "utf8");
+  const context = buildTemplateContext({
+    service: args.contract.name,
+    title: args.contract.title,
+    version: args.version,
+    github: args.github,
+    vars: args.vars,
+    artifact: {
+      id: args.artifact.id,
+      lang: args.artifact.lang,
+      kind: args.artifact.kind,
+      package: args.artifact.package,
+      goModule: args.artifact.goModule,
+      goPackageName: args.artifact.goPackageName,
+      maven: args.artifact.maven,
+      branch: args.artifact.branch,
+      tag: renderArtifactTag(
+        args.artifact,
+        args.contract.name,
+        args.version,
+        args.github,
+        args.vars,
+      ),
+      npmRegistry: args.artifact.publishing.npmRegistry,
+      mavenRepositoryUrl: args.artifact.publishing.mavenRepositoryUrl,
+    },
+  });
+
+  return interpolate(raw, context);
+}

package/src/redocly/redocly-sync.ts

@@ -0,0 +1,67 @@
+import { readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+
+import type { ResolvedConfig } from "../config/types";
+
+const GENERATED_HEADER =
+  "# AUTO-GENERATED by Seagull from its config and 'redocly.base.yaml'.\n" +
+  "# Do not edit directly, edit those two files instead (this file is\n" +
+  "# regenerated on every lint/bundle/generate run).\n\n";
+
+interface RedoclyBase {
+  extends?: string[];
+  rules?: Record<string, string>;
+}
+
+/**
+ * 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.
+ */
+export async function syncRedoclyConfig(config: ResolvedConfig): Promise<void> {
+  const basePath = path.join(config.rootDir, "redocly.base.yaml");
+  const base = parseYaml(await readFile(basePath, "utf8")) as RedoclyBase;
+
+  const apis = Object.fromEntries(
+    config.contracts.map((contract) => {
+      const typesArtifact = contract.artifacts.find(
+        (artifact) => artifact.tool === "openapi-typescript",
+      );
+
+      return [
+        `${contract.name}@v1`,
+        {
+          root: contract.entrypointRelative,
+          ...(typesArtifact
+            ? {
+                "x-openapi-ts": {
+                  output: path.join(
+                    path.relative(config.rootDir, typesArtifact.outputDir),
+                    "index.d.ts",
+                  ),
+                },
+              }
+            : {}),
+        },
+      ];
+    }),
+  );
+
+  const final = { extends: base.extends, apis, rules: base.rules };
+
+  await writeFile(
+    path.join(config.rootDir, "redocly.yaml"),
+    GENERATED_HEADER + stringifyYaml(final),
+  );
+}

package/src/version/version.ts

@@ -0,0 +1,67 @@
+import { createHash } from "node:crypto";
+
+/**
+ * Shape of a bundled OpenAPI document, narrowed to the one field this module
+ * cares about.
+ */
+export 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`.
+ */
+export function resolveVersion(
+  spec: BundledSpec,
+  contractName: string,
+): string {
+  const override = process.env.SDK_VERSION_OVERRIDE?.trim();
+
+  if (override) {
+    return override.replace(/^v/, "");
+  }
+
+  const specVersion = spec.info?.version?.trim();
+
+  if (!specVersion) {
+    throw new Error(
+      `specs/${contractName}/openapi.yaml is missing "info.version" - set it ` +
+        `to a semver value. This field is the single source of truth for ` +
+        `the ${contractName} contract's SDK version.`,
+    );
+  }
+
+  return specVersion.replace(/^v/, "");
+}
+
+/**
+ * Computes a stable content hash of a bundled OpenAPI document's raw JSON text.
+ * Stamped alongside `VERSION` into every generated SDK package so
+ * `publish-sdk.ts` can tell a genuine no-op republish (same spec, same version)
+ * apart from a spec that changed without its `info.version` being bumped.
+ *
+ * @param raw - The raw bundled spec file contents (JSON text).
+ * @returns A `sha256` hex digest of the raw contents.
+ */
+export function hashSpec(raw: string): string {
+  return createHash("sha256").update(raw).digest("hex");
+}

package/tsconfig.json

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

package/tsdown.config.ts

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