ci(release): add automated npm release workflow (#2)

Release on every push to main (merged PR or direct push) by auto-
bumping the patch segment, with manual workflow_dispatch as an escape
hatch to pin an exact version or bump minor/major. Git tags (vX.Y.Z) are
the source of truth, so the committed package.json version is only the
baseline before the first tag exists, and the bump is never committed
back — a release never pushes to main and cannot re-trigger itself.

Version resolution is delegated to bun-run scripts under scripts/release
so each CI step (compute-version, set-version, publish,
create-github-release) stays idempotent and is reusable as a plain
command.

Publishing uses npm OIDC trusted publishing with provenance, so no
NPM_TOKEN is needed. This requires package.json to carry a repository
field (mandatory for --provenance) and publishConfig; files is narrowed
to providers + meta.json so the published tarball excludes the workflow
and release scripts.

Signed-off-by: Kevin Cui <bh@bugs.cc>

Author: BlackHole1

.bun-version

@@ -0,0 +1 @@
+1.3.14

.github/workflows/release.yml

@@ -0,0 +1,88 @@
+name: Release
+
+# Automated npm + GitHub release. Two triggers:
+#   - push to main (every merged PR or direct push) → auto-bump the patch segment, or
+#   - manual workflow_dispatch → set "expected_version" to release an exact X.Y.Z, or leave it
+#     empty and pick a "version_bump" segment to auto-bump from the latest tag.
+#
+# Versions are resolved by scripts/release/cli.ts; git tags (vX.Y.Z) are the source of truth, so
+# the committed package.json version is only the baseline used before the first tag exists.
+# The package.json version bump is never committed back, so a release never pushes to main and
+# therefore never re-triggers itself.
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+    inputs:
+      expected_version:
+        description: "Exact version to release (e.g. 1.2.3). Leave empty to auto-bump from the latest tag."
+        required: false
+        type: string
+        default: ""
+      version_bump:
+        description: "Segment to bump when expected_version is empty."
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+        default: patch
+
+permissions:
+  contents: write # create the git tag + GitHub release
+  id-token: write # OIDC: npm trusted publishing (token-free) + provenance
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    env:
+      # On a push there are no inputs: EXPECTED_VERSION is empty (→ auto-bump) and
+      # VERSION_BUMP falls back to patch via the `|| 'patch'` guard.
+      EXPECTED_VERSION: ${{ inputs.expected_version }}
+      VERSION_BUMP: ${{ inputs.version_bump || 'patch' }}
+      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # need full history + tags to compute the next version
+          fetch-tags: true
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version-file: .bun-version
+
+      - uses: actions/setup-node@v4
+        with:
+          # OIDC trusted publishing needs Node >= 22.14.0; "22" resolves to the latest 22.x.
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      # Trusted publishing needs npm >= 11.5.1, but Node 22 ships npm 10.x — upgrade the
+      # global npm so `release:publish` runs a CLI that performs the OIDC token exchange.
+      # Pinned to the 11.x major (>= 11.5.1) so a future npm major can't silently change the
+      # publish/provenance behaviour; `npm --version` echoes the resolved version to the log.
+      - name: Upgrade npm for OIDC trusted publishing
+        run: npm install -g "npm@^11.5.1" && npm --version
+
+      # Exports RELEASE_VERSION / RELEASE_TAG / PREVIOUS_TAG to the following steps,
+      # and fails fast if the target tag already exists.
+      - name: Compute release version
+        run: bun run release:compute-version
+
+      # Write the resolved version into package.json before publishing.
+      - name: Set package.json version
+        run: bun run release:set-version
+
+      # Authenticates via OIDC trusted publishing (configured in the npm package settings
+      # for this repo + workflow file), so no NPM_TOKEN / NODE_AUTH_TOKEN is required.
+      - name: Publish to npm
+        run: bun run release:publish
+
+      # Creates the git tag at this commit and the GitHub release with generated notes.
+      - name: Create GitHub release
+        run: bun run release:create-github-release

package.json

@@ -3,7 +3,24 @@
   "version": "0.0.0",
   "description": "Auto-generated type augmentation for @oomol-lab/connector. Import the per-provider subpath you use.",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oomol-lab/connector-types.git"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  },
   "sideEffects": false,
+  "files": [
+    "providers",
+    "meta.json"
+  ],
+  "scripts": {
+    "release:compute-version": "bun scripts/release/cli.ts compute-version",
+    "release:set-version": "bun scripts/release/cli.ts set-version",
+    "release:publish": "bun scripts/release/cli.ts publish",
+    "release:create-github-release": "bun scripts/release/cli.ts create-github-release"
+  },
   "exports": {
     "./*": {
       "types": "./providers/*.d.ts",

scripts/release/cli.ts

@@ -0,0 +1,157 @@
+/**
+ * Release workflow CLI. Run a single step with `bun run scripts/release/cli.ts <command>`:
+ *
+ *   compute-version         Resolve the version from git tags + workflow inputs and export
+ *                           RELEASE_VERSION / RELEASE_TAG / PREVIOUS_TAG to later job steps.
+ *   set-version             Write RELEASE_VERSION into package.json before publish.
+ *   publish                 Publish the current package to npm (idempotent; skips if the
+ *                           version already exists). In CI it authenticates via npm OIDC
+ *                           trusted publishing (no token) and adds --provenance.
+ *   create-github-release   Create the git tag + GitHub release at GITHUB_SHA (idempotent).
+ *
+ * Inputs are read from the environment so the same script works as plain CI steps:
+ *   compute-version  ← EXPECTED_VERSION, VERSION_BUMP
+ *   set-version      ← RELEASE_VERSION
+ *   publish          ← RELEASE_VERSION, GITHUB_ACTIONS (auth via OIDC trusted publishing in CI)
+ *   create-release   ← RELEASE_TAG, PREVIOUS_TAG, GITHUB_SHA, GH_TOKEN
+ */
+
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+import {
+  listGitTags,
+  readPackageName,
+  readPackageVersion,
+  readRequiredEnv,
+  runCapture,
+  runInherit,
+  setPackageVersion,
+  writeGitHubEnv,
+} from "./lib";
+import {
+  computeReleaseVersion,
+  isStableSemver,
+  readVersionBump,
+} from "./version";
+
+// Run everything from the repo root regardless of the caller's cwd, so git/npm/gh and the
+// relative package.json path all resolve correctly.
+const repoRoot = fileURLToPath(new URL("../../", import.meta.url));
+process.chdir(repoRoot);
+const packageJsonPath = "package.json";
+
+async function runComputeVersion(): Promise<void> {
+  const baseVersion = await readPackageVersion(packageJsonPath);
+  const result = computeReleaseVersion({
+    expectedVersion: process.env.EXPECTED_VERSION ?? "",
+    versionBump: readVersionBump(process.env.VERSION_BUMP ?? "patch"),
+    tags: listGitTags(),
+    baseVersion: isStableSemver(baseVersion) ? baseVersion : "0.0.0",
+  });
+
+  await writeGitHubEnv({
+    RELEASE_VERSION: result.version,
+    RELEASE_TAG: result.tagName,
+    PREVIOUS_TAG: result.previousTag,
+  });
+  process.stdout.write(
+    `Release version ${result.version} (tag ${result.tagName}, previous ${result.previousTag || "none"}).\n`,
+  );
+}
+
+async function runSetVersion(): Promise<void> {
+  const version = readRequiredEnv("RELEASE_VERSION");
+  await setPackageVersion(packageJsonPath, version);
+  process.stdout.write(`Set package.json version to ${version}.\n`);
+}
+
+function npmVersionExists(packageSpec: string): boolean {
+  const result = runCapture("npm", ["view", packageSpec, "version", "--json"]);
+  if (result.status === 0) {
+    return result.stdout.trim() !== "";
+  }
+
+  const output = `${result.stdout}\n${result.stderr}`.toLowerCase();
+  if (output.includes("e404") || output.includes("no match found")) {
+    return false;
+  }
+  throw new Error(`Failed to query npm for ${packageSpec}:\n${(result.stderr || result.stdout).trim()}`);
+}
+
+async function runPublish(): Promise<void> {
+  const version = readRequiredEnv("RELEASE_VERSION");
+  const name = await readPackageName(packageJsonPath);
+  const packageSpec = `${name}@${version}`;
+
+  if (npmVersionExists(packageSpec)) {
+    process.stdout.write(`Skipping publish: ${packageSpec} already exists on npm.\n`);
+    return;
+  }
+
+  const args = ["publish", "--access", "public"];
+  // In CI npm authenticates via OIDC trusted publishing; provenance rides on the same
+  // id-token (id-token: write). Neither is available locally, so add --provenance only here.
+  if (process.env.GITHUB_ACTIONS === "true") {
+    args.push("--provenance");
+  }
+  runInherit("npm", args);
+  process.stdout.write(`Published ${packageSpec}.\n`);
+}
+
+function gitHubReleaseExists(tag: string): boolean {
+  return runCapture("gh", ["release", "view", tag, "--json", "tagName"]).status === 0;
+}
+
+function runCreateGitHubRelease(): void {
+  const tag = readRequiredEnv("RELEASE_TAG");
+
+  if (gitHubReleaseExists(tag)) {
+    process.stdout.write(`Skipping GitHub release: ${tag} already exists.\n`);
+    return;
+  }
+
+  const previousTag = process.env.PREVIOUS_TAG ?? "";
+  const args = [
+    "release",
+    "create",
+    tag,
+    "--target",
+    readRequiredEnv("GITHUB_SHA"),
+    "--title",
+    tag,
+    "--generate-notes",
+  ];
+  if (previousTag !== "") {
+    args.push("--notes-start-tag", previousTag);
+  }
+  args.push("--latest");
+
+  runInherit("gh", args);
+  process.stdout.write(`Created GitHub release ${tag}.\n`);
+}
+
+async function main(): Promise<void> {
+  const command = process.argv[2];
+  switch (command) {
+    case "compute-version":
+      await runComputeVersion();
+      return;
+    case "set-version":
+      await runSetVersion();
+      return;
+    case "publish":
+      await runPublish();
+      return;
+    case "create-github-release":
+      runCreateGitHubRelease();
+      return;
+    default:
+      throw new Error(
+        `Unknown command: ${command ?? "(none)"}. `
+        + "Expected one of: compute-version, set-version, publish, create-github-release.",
+      );
+  }
+}
+
+await main();

scripts/release/lib.ts

@@ -0,0 +1,109 @@
+/**
+ * Side-effect helpers for the Release workflow: git, npm/gh subprocesses,
+ * package.json I/O, and GitHub Actions env wiring.
+ *
+ * Node built-ins only (no `Bun.*`) so the scripts stay portable; they still run under `bun run`.
+ */
+
+import { spawnSync } from "node:child_process";
+import { appendFile, readFile, writeFile } from "node:fs/promises";
+import process from "node:process";
+
+export interface CommandResult {
+  status: number;
+  stdout: string;
+  stderr: string;
+}
+
+/** Runs a command and captures its output. Use for queries (git tags, npm view). */
+export function runCapture(command: string, args: readonly string[]): CommandResult {
+  const result = spawnSync(command, [...args], { encoding: "utf8" });
+  if (result.error) throw result.error;
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+/**
+ * Runs a command with inherited stdio (so its output streams to the CI log) and throws
+ * on a non-zero exit. Use for side-effecting steps (npm publish, gh release create).
+ */
+export function runInherit(
+  command: string,
+  args: readonly string[],
+  env?: NodeJS.ProcessEnv,
+): void {
+  const result = spawnSync(command, [...args], {
+    stdio: "inherit",
+    env: env ?? process.env,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(" ")} exited with code ${result.status ?? "unknown"}.`);
+  }
+}
+
+/** Lists `vX.Y.Z`-style tags newest-first; returns `[]` when the repo has no matching tags. */
+export function listGitTags(): string[] {
+  const result = runCapture("git", ["tag", "-l", "v*", "--sort=-v:refname"]);
+  if (result.status !== 0) {
+    throw new Error(`Failed to list git tags: ${result.stderr.trim() || "unknown error"}`);
+  }
+  return result.stdout
+    .split("\n")
+    .map(tag => tag.trim())
+    .filter(tag => tag !== "");
+}
+
+interface PackageManifest {
+  name?: unknown;
+  version?: unknown;
+}
+
+async function readManifest(packageJsonPath: string): Promise<Record<string, unknown>> {
+  return JSON.parse(await readFile(packageJsonPath, "utf8")) as Record<string, unknown>;
+}
+
+export async function readPackageVersion(packageJsonPath: string): Promise<string> {
+  const manifest = await readManifest(packageJsonPath) as PackageManifest;
+  return typeof manifest.version === "string" ? manifest.version : "";
+}
+
+export async function readPackageName(packageJsonPath: string): Promise<string> {
+  const manifest = await readManifest(packageJsonPath) as PackageManifest;
+  if (typeof manifest.name !== "string" || manifest.name === "") {
+    throw new Error(`package.json at ${packageJsonPath} is missing a "name".`);
+  }
+  return manifest.name;
+}
+
+/** Writes `version` into package.json, preserving key order and 2-space formatting. */
+export async function setPackageVersion(packageJsonPath: string, version: string): Promise<void> {
+  const manifest = await readManifest(packageJsonPath);
+  manifest.version = version;
+  await writeFile(packageJsonPath, `${JSON.stringify(manifest, null, 2)}\n`, "utf8");
+}
+
+/**
+ * Exports `key=value` pairs to later steps of the same job via `$GITHUB_ENV`.
+ * Outside Actions (no `$GITHUB_ENV`) it just prints them, so local dry-runs work.
+ */
+export async function writeGitHubEnv(entries: Record<string, string>): Promise<void> {
+  const text = `${Object.entries(entries).map(([key, value]) => `${key}=${value}`).join("\n")}\n`;
+  const githubEnvPath = process.env.GITHUB_ENV;
+  if (githubEnvPath === undefined || githubEnvPath === "") {
+    process.stdout.write(text);
+    return;
+  }
+  await appendFile(githubEnvPath, text, "utf8");
+}
+
+export function readRequiredEnv(name: string): string {
+  const value = process.env[name];
+  if (value === undefined || value === "") {
+    throw new Error(`${name} is required.`);
+  }
+  return value;
+}