@opengroundplan/core 0.1.1

package/templates/layers/queue-broker/files/src/queue/config.ts

@@ -0,0 +1,60 @@
+/**
+ * The only place queue settings are read. Producers and handlers take what they need
+ * as arguments — nothing else in the app touches process.env for the broker.
+ */
+
+const PREFIX = '{{ queueEnvPrefix }}';
+
+export type QueueConfig = {
+  brokerUrl: string;
+  name: string;
+  concurrency: number;
+  /** First attempt included, so 3 means one try plus two retries. */
+  maxAttempts: number;
+  backoffMs: number;
+  jobTimeoutMs: number;
+  completedTtlSeconds: number;
+  failedTtlSeconds: number;
+  shutdownTimeoutSeconds: number;
+};
+
+/** Typed defaults. The single place a literal queue value may appear. */
+const defaults: QueueConfig = {
+  brokerUrl: 'redis://127.0.0.1:6379/0',
+  name: '{{ queueName }}',
+  concurrency: 5,
+  maxAttempts: 3,
+  backoffMs: 1_000,
+  jobTimeoutMs: 30_000,
+  completedTtlSeconds: 3_600,
+  failedTtlSeconds: 604_800,
+  shutdownTimeoutSeconds: 30,
+};
+
+function raw(key: string): string | undefined {
+  const value = process.env[`${PREFIX}_${key}`];
+  return value === undefined || value === '' ? undefined : value;
+}
+
+function int(key: string, fallback: number): number {
+  const value = raw(key);
+  if (value === undefined) return fallback;
+  const parsed = Number(value);
+  // Fail at startup rather than hand NaN to the broker client.
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`${PREFIX}_${key} must be a positive integer, got "${value}"`);
+  }
+  return parsed;
+}
+
+export const queueConfig: QueueConfig = {
+  brokerUrl: raw('BROKER_URL') ?? defaults.brokerUrl,
+  name: raw('NAME') ?? defaults.name,
+  concurrency: int('CONCURRENCY', defaults.concurrency),
+  maxAttempts: int('MAX_ATTEMPTS', defaults.maxAttempts),
+  backoffMs: int('BACKOFF_MS', defaults.backoffMs),
+  jobTimeoutMs: int('JOB_TIMEOUT_MS', defaults.jobTimeoutMs),
+  completedTtlSeconds: int('COMPLETED_TTL_SECONDS', defaults.completedTtlSeconds),
+  failedTtlSeconds: int('FAILED_TTL_SECONDS', defaults.failedTtlSeconds),
+  shutdownTimeoutSeconds: int('SHUTDOWN_TIMEOUT_SECONDS', defaults.shutdownTimeoutSeconds),
+};

package/templates/layers/queue-broker/files/src/queue/connection.ts

@@ -0,0 +1,19 @@
+import { Redis } from 'ioredis';
+import { queueConfig } from './config.js';
+
+let shared: Redis | null = null;
+
+/**
+ * One connection per process, shared by the producer and the worker.
+ * `maxRetriesPerRequest: null` is mandatory: BullMQ parks on a blocking BRPOPLPUSH and
+ * ioredis would otherwise abort that command, leaving the worker silently idle.
+ */
+export function connection(): Redis {
+  shared ??= new Redis(queueConfig.brokerUrl, { maxRetriesPerRequest: null });
+  return shared;
+}
+
+export async function closeConnection(): Promise<void> {
+  await shared?.quit();
+  shared = null;
+}

package/templates/layers/queue-broker/files/src/queue/handlers.ts

@@ -0,0 +1,22 @@
+import type { Job } from 'bullmq';
+import type { JobPayloads } from './jobs.js';
+
+type Handler<N extends keyof JobPayloads> = (payload: JobPayloads[N], job: Job) => Promise<void>;
+
+/** Replace with real work — it exists so the worker has something to run on day one. */
+const sendWelcomeEmail: Handler<'send-welcome-email'> = async (payload) => {
+  console.info(`[queue] would send a welcome email to ${payload.email} (user ${payload.userId})`);
+};
+
+const registry = {
+  'send-welcome-email': sendWelcomeEmail,
+} satisfies { [N in keyof JobPayloads]: Handler<N> };
+
+/**
+ * Erased on the way out: the dispatcher only learns a job's name at runtime, so payload
+ * typing is enforced where each handler is declared above, not at the lookup.
+ */
+export const handlers = registry as unknown as Record<
+  string,
+  (payload: unknown, job: Job) => Promise<void>
+>;

package/templates/layers/queue-broker/files/src/queue/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public surface. Application code imports `enqueue` and `JobName`; only the worker
+ * entrypoint reaches for `startWorker`.
+ */
+export { queueConfig, type QueueConfig } from './config.js';
+export { JobName, type JobPayloads } from './jobs.js';
+export { closeQueue, enqueue, jobQueue } from './producer.js';
+export { startWorker, stopWorker } from './worker.js';

package/templates/layers/queue-broker/files/src/queue/jobs.ts

@@ -0,0 +1,15 @@
+/**
+ * The job catalogue. A name is a wire contract shared by producers and workers across
+ * deploys — renaming one strands every job already sitting in Redis.
+ */
+
+export const JobName = {
+  SendWelcomeEmail: 'send-welcome-email',
+} as const;
+
+export type JobName = (typeof JobName)[keyof typeof JobName];
+
+/** Payload per job name. Keep these JSON-serialisable: they round-trip through Redis. */
+export type JobPayloads = {
+  'send-welcome-email': { userId: string; email: string };
+};

package/templates/layers/queue-broker/files/src/queue/producer.ts

@@ -0,0 +1,39 @@
+import { Queue } from 'bullmq';
+import type { JobsOptions } from 'bullmq';
+import { queueConfig } from './config.js';
+import { connection } from './connection.js';
+import type { JobPayloads } from './jobs.js';
+
+let queue: Queue | null = null;
+
+/** Every job inherits these; a caller may override any of them per enqueue. */
+const jobDefaults: JobsOptions = {
+  attempts: queueConfig.maxAttempts,
+  backoff: { type: 'exponential', delay: queueConfig.backoffMs },
+  removeOnComplete: { age: queueConfig.completedTtlSeconds },
+  removeOnFail: { age: queueConfig.failedTtlSeconds },
+};
+
+export function jobQueue(): Queue {
+  queue ??= new Queue(queueConfig.name, {
+    connection: connection(),
+    defaultJobOptions: jobDefaults,
+  });
+  return queue;
+}
+
+/** The only supported way to schedule work. Returns the job id for log correlation. */
+export async function enqueue<N extends keyof JobPayloads>(
+  name: N,
+  payload: JobPayloads[N],
+  options?: JobsOptions,
+): Promise<string> {
+  const job = await jobQueue().add(name, payload, options);
+  if (!job.id) throw new Error(`Job "${name}" was accepted without an id`);
+  return job.id;
+}
+
+export async function closeQueue(): Promise<void> {
+  await queue?.close();
+  queue = null;
+}

package/templates/layers/queue-broker/files/src/queue/worker.cli.ts

@@ -0,0 +1,32 @@
+/**
+ * Worker entrypoint: `npm run queue:worker`. A separate process from the API so a slow
+ * job never occupies a request thread and the two scale independently.
+ */
+import { queueConfig } from './config.js';
+import { startWorker, stopWorker } from './worker.js';
+
+const worker = startWorker();
+
+worker.on('ready', () => {
+  console.info(
+    `[queue] worker ready on "${queueConfig.name}" (concurrency ${queueConfig.concurrency})`,
+  );
+});
+
+worker.on('failed', (job, error) => {
+  console.error(`[queue] job ${job?.id ?? '?'} (${job?.name ?? '?'}) failed: ${error.message}`);
+});
+
+let stopping = false;
+
+function shutdown(): void {
+  if (stopping) return;
+  stopping = true;
+  // Hard deadline: the platform will SIGKILL us anyway, so exit non-zero on our own terms.
+  const deadline = setTimeout(() => process.exit(1), queueConfig.shutdownTimeoutSeconds * 1_000);
+  deadline.unref();
+  void stopWorker(worker).then(() => process.exit(0));
+}
+
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/templates/layers/queue-broker/files/src/queue/worker.ts

@@ -0,0 +1,28 @@
+import { Worker } from 'bullmq';
+import type { Job } from 'bullmq';
+import { queueConfig } from './config.js';
+import { closeConnection, connection } from './connection.js';
+import { handlers } from './handlers.js';
+
+async function dispatch(job: Job): Promise<void> {
+  const handler = handlers[job.name];
+  // An unknown name means a producer shipped ahead of this worker; fail loudly so the
+  // job retries and lands in the failed set instead of being acked into the void.
+  if (!handler) throw new Error(`No handler registered for job "${job.name}"`);
+  await handler(job.data, job);
+}
+
+export function startWorker(): Worker {
+  return new Worker(queueConfig.name, dispatch, {
+    connection: connection(),
+    concurrency: queueConfig.concurrency,
+    // The lock must outlive the slowest handler or BullMQ redelivers a job still running.
+    lockDuration: queueConfig.jobTimeoutMs,
+  });
+}
+
+/** Waits for in-flight jobs to finish, then releases the broker connection. */
+export async function stopWorker(worker: Worker): Promise<void> {
+  await worker.close();
+  await closeConnection();
+}

package/templates/layers/queue-broker/files/tests/test_queue_config.py

@@ -0,0 +1,37 @@
+"""Config is the layer's contract with the environment; a silent default here is an outage."""
+
+from __future__ import annotations
+
+import pytest
+
+from {{ solutionName | snake }}.queue.config import load_config
+
+PREFIX = "{{ queueEnvPrefix }}"
+
+
+def test_defaults_apply_when_environment_is_empty(monkeypatch: pytest.MonkeyPatch) -> None:
+    for key in ("BROKER_URL", "NAME", "CONCURRENCY", "MAX_ATTEMPTS"):
+        monkeypatch.delenv(f"{PREFIX}_{key}", raising=False)
+
+    config = load_config()
+
+    assert config.name == "{{ queueName }}"
+    assert config.concurrency >= 1
+    assert config.max_retries == config.max_attempts - 1
+
+
+def test_environment_overrides_defaults(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(f"{PREFIX}_NAME", "urgent")
+    monkeypatch.setenv(f"{PREFIX}_CONCURRENCY", "16")
+
+    config = load_config()
+
+    assert config.name == "urgent"
+    assert config.concurrency == 16
+
+
+def test_non_integer_value_fails_at_load(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv(f"{PREFIX}_CONCURRENCY", "many")
+
+    with pytest.raises(ValueError, match="CONCURRENCY"):
+        load_config()

package/templates/layers/release-automation/blueprint.yaml

@@ -0,0 +1,205 @@
+id: release-automation
+kind: layer
+name: Release automation
+description: >-
+  Conventional-commit enforcement plus an automated release pipeline: a version
+  PR that accumulates changes, a generated CHANGELOG, a git tag, a GitHub
+  Release, and an opt-in publish job that authenticates with OIDC trusted
+  publishing. npm classic tokens were revoked in December 2025, so no workflow
+  here stores a long-lived registry credential — npm, PyPI and NuGet all mint a
+  short-lived key from the workflow's own OIDC identity. Changesets is offered
+  for JavaScript/TypeScript; every other stack uses release-please.
+
+tags:
+  - release
+  - versioning
+  - semver
+  - conventional-commits
+  - changelog
+  - ci
+  - github-actions
+  - oidc
+  - trusted-publishing
+  - supply-chain
+
+# Nothing. The layer ships its own workflows, its own commit hook and its own
+# release config; it reads the repo's existing go.mod / global.json / pyproject.toml
+# for tool versions rather than requiring a base to have declared anything. There is
+# no `ci-*` blueprint in the catalog yet, and `requires` may only name blueprints that
+# exist (loader.assertReferencesResolve) — naming a future one breaks catalog load.
+requires: []
+
+# Deliberately empty for the same reason: a competing release layer (semantic-release,
+# release-plz, a `release-none`) does not exist yet, and conflicts are symmetric at
+# resolve time, so whichever lands second declares the pair from its own side.
+conflicts: []
+
+# Capability names other layers key off instead of naming this blueprint. A container
+# layer wants "there is a version tag to label an image with", not "release-automation
+# is installed".
+provides:
+  - release-automation
+  - conventional-commits
+  - commit-lint
+  - changelog
+  - semantic-versioning
+  - version-tags
+  - github-release
+  - package-publish
+  - trusted-publishing
+
+# Release plumbing lives in .github/ and at the repo root; it is identical under every
+# folder overlay, so listing a subset here would be misleading documentation.
+supportsArchitectures: []
+
+variables:
+  # Changesets is only meaningful where packages are npm packages. Every other stack
+  # gets release-please regardless of what is answered here — the file rules say so.
+  - name: releaseTool
+    prompt: Release tool (JavaScript/TypeScript only — other stacks always use release-please)
+    type: select
+    default: release-please
+    required: true
+    choices:
+      - { value: release-please, label: 'release-please — conventional commits drive the version' }
+      - { value: changesets, label: 'Changesets — contributors write an intent file per change' }
+
+  - name: releaseBranch
+    prompt: Branch releases are cut from
+    type: string
+    default: main
+    required: true
+
+  # The GitHub Environment the publish job runs in. Trusted publishing on npm and PyPI
+  # can be scoped to an environment name, which is what stops a fork or a stray branch
+  # from minting a publish credential.
+  - name: releaseEnvironment
+    prompt: GitHub Environment name the publish job runs in
+    type: string
+    default: release
+    required: true
+
+  - name: commitTypes
+    prompt: Allowed conventional-commit types (comma separated)
+    type: string
+    default: build,chore,ci,docs,feat,fix,perf,refactor,revert,style,test
+    required: true
+
+  - name: commitSubjectMax
+    prompt: Maximum commit subject length, excluding the type and scope prefix
+    type: number
+    default: 72
+    required: true
+
+  # Also declared by the Node bases; the interview asks once and both get the same answer.
+  - name: nodeVersion
+    prompt: Node.js version the release workflow runs on
+    type: string
+    default: '24'
+    when: "stack == 'node' || stack == 'typescript' || stack == 'polyglot'"
+
+  - name: packageManager
+    prompt: Package manager
+    type: select
+    default: pnpm
+    when: "stack == 'node' || stack == 'typescript' || stack == 'polyglot'"
+    choices:
+      - { value: pnpm, label: pnpm }
+      - { value: npm, label: npm }
+      - { value: yarn, label: Yarn }
+      - { value: bun, label: Bun }
+
+  - name: npmRegistryUrl
+    prompt: npm registry the package is published to
+    type: string
+    default: https://registry.npmjs.org
+    when: "stack == 'node' || stack == 'typescript' || stack == 'polyglot'"
+
+  - name: npmAccess
+    prompt: npm access for scoped packages
+    type: select
+    default: public
+    when: "stack == 'node' || stack == 'typescript' || stack == 'polyglot'"
+    choices:
+      - { value: public, label: 'public — anyone can install' }
+      - { value: restricted, label: 'restricted — paid npm scope' }
+
+  - name: pypiRepositoryUrl
+    prompt: PyPI upload endpoint
+    type: string
+    default: https://upload.pypi.org/legacy/
+    when: "stack == 'python'"
+
+  - name: nugetSource
+    prompt: NuGet push source
+    type: string
+    default: https://api.nuget.org/v3/index.json
+    when: "stack == 'dotnet'"
+
+files:
+  # ── universal ───────────────────────────────────────────────────────────────
+  - from: files/docs/release-automation.md
+
+  # Conventional commits are the input to every release tool below, so the gate is
+  # installed regardless of which one was chosen. PR title, not commit list: a
+  # squash merge turns the title into the commit that release-please reads.
+  - from: files/.github/workflows/commit-conventions.yml
+  - from: files/.githooks/commit-msg
+
+  # ── changesets: node / typescript / polyglot ────────────────────────────────
+  - from: files/.changeset/config.json
+    when: "(stack == 'node' || stack == 'typescript' || stack == 'polyglot') && releaseTool == 'changesets'"
+  - from: files/.changeset/README.md
+    when: "(stack == 'node' || stack == 'typescript' || stack == 'polyglot') && releaseTool == 'changesets'"
+  - from: files/.github/workflows/release-changesets.yml
+    when: "(stack == 'node' || stack == 'typescript' || stack == 'polyglot') && releaseTool == 'changesets'"
+
+  # ── release-please ──────────────────────────────────────────────────────────
+  # One workflow per stack rather than a shared workflow plus per-stack publish
+  # workflows: a GitHub Release created with GITHUB_TOKEN does not trigger other
+  # workflows, so a `release: published` publish workflow would never fire. Keeping
+  # publish as a downstream job in the same run sidesteps that entirely.
+  - from: files/.github/workflows/release-node.yml
+    when: "(stack == 'node' || stack == 'typescript') && releaseTool == 'release-please'"
+
+  # A monorepo releases many packages at once, so this one is manifest-driven.
+  - from: files/.github/workflows/release-monorepo.yml
+    when: "stack == 'polyglot' && releaseTool == 'release-please'"
+  - from: files/release-please-config.json
+    when: "stack == 'polyglot' && releaseTool == 'release-please'"
+  - from: files/.release-please-manifest.json
+    when: "stack == 'polyglot' && releaseTool == 'release-please'"
+
+  # Changesets has no meaning outside the npm ecosystem, so these ignore releaseTool.
+  - from: files/.github/workflows/release-python.yml
+    when: "stack == 'python'"
+  - from: files/.github/workflows/release-go.yml
+    when: "stack == 'go'"
+  - from: files/.github/workflows/release-dotnet.yml
+    when: "stack == 'dotnet'"
+
+postApply:
+  # git silently ignores a hook without the executable bit, and file modes are not
+  # carried through the template copy.
+  - run: chmod +x .githooks/commit-msg
+    optional: true
+
+  # Point git at the tracked hook directory; without this the commit-msg hook is inert.
+  - run: git config core.hooksPath .githooks
+    optional: true
+
+  # Changesets is authored locally (`changeset add`), so the CLI has to be a devDependency.
+  # The stack guard matters: releaseTool is answered even on stacks that never receive a
+  # changesets workflow, and installing an npm devDependency into a Go repo is nonsense.
+  - run: pnpm add -D @changesets/cli
+    when: "releaseTool == 'changesets' && packageManager == 'pnpm' && (stack == 'node' || stack == 'typescript' || stack == 'polyglot')"
+    optional: true
+  - run: npm install --save-dev @changesets/cli
+    when: "releaseTool == 'changesets' && packageManager == 'npm' && (stack == 'node' || stack == 'typescript' || stack == 'polyglot')"
+    optional: true
+  - run: yarn add -D @changesets/cli
+    when: "releaseTool == 'changesets' && packageManager == 'yarn' && (stack == 'node' || stack == 'typescript' || stack == 'polyglot')"
+    optional: true
+  - run: bun add -d @changesets/cli
+    when: "releaseTool == 'changesets' && packageManager == 'bun' && (stack == 'node' || stack == 'typescript' || stack == 'polyglot')"
+    optional: true

package/templates/layers/release-automation/files/.changeset/README.md

@@ -0,0 +1,31 @@
+# Changesets
+
+Every change that should show up in a changelog carries an intent file in this folder.
+
+```bash
+npx changeset          # describe the change and pick a bump level
+git add .changeset
+```
+
+The file is markdown with a frontmatter block naming each package and its bump
+(`patch`, `minor`, `major`). Commit it alongside the code it describes.
+
+## What happens next
+
+1. Merging to `{{ releaseBranch }}` makes the release workflow open (or update) a
+   **chore(release): version packages** PR that consumes the pending intent files,
+   bumps versions, and rewrites `CHANGELOG.md`.
+2. Merging that PR publishes: the same workflow tags the release and runs
+   `changeset publish`, authenticating to npm with OIDC — no token is stored anywhere.
+
+Nothing is released until the version PR is merged, so a stack of merges accumulates
+into one coherent release rather than one release per commit.
+
+## Notes
+
+- Packages marked `"private": true` are versioned and tagged but never published, which
+  is what you want for an application. Drop the flag on anything meant for the registry.
+- `access` is set in `config.json`, not per publish command. A scoped package on a free
+  npm account must stay `public`.
+
+See `docs/release-automation.md` for the trusted-publishing setup.

package/templates/layers/release-automation/files/.changeset/config.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.4/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "{{ npmAccess }}",
+  "baseBranch": "{{ releaseBranch }}",
+  "updateInternalDependencies": "patch",
+  "ignore": [],
+  "privatePackages": { "version": true, "tag": true }
+}

package/templates/layers/release-automation/files/.githooks/commit-msg

@@ -0,0 +1,32 @@
+#!/bin/sh
+# Same rule as the CI gate, enforced locally so a bad message costs a second, not a CI round trip.
+set -eu
+
+# Single source for the convention in this file; CI reads its own copy from the workflow env block.
+COMMIT_TYPES="{{ commitTypes }}"
+SUBJECT_MAX={{ commitSubjectMax }}
+
+subject=$(sed -e '/^#/d' -e '/^[[:space:]]*$/d' "$1" | head -n 1)
+
+# git writes these itself; rejecting them would break merge, revert and rebase --autosquash.
+case "$subject" in
+  Merge\ *|Revert\ *|fixup!*|squash!*|amend!*) exit 0 ;;
+esac
+
+pattern="^($(printf '%s' "$COMMIT_TYPES" | tr ',' '|'))(\([a-z0-9._/-]+\))?!?: .+"
+
+if ! printf '%s' "$subject" | grep -Eq "$pattern"; then
+  echo "commit-msg: not a conventional commit." >&2
+  echo "  got:      $subject" >&2
+  echo "  expected: <type>[(scope)][!]: <subject>" >&2
+  echo "  types:    $COMMIT_TYPES" >&2
+  echo "  example:  feat(api): add cursor pagination to /orders" >&2
+  exit 1
+fi
+
+description=${subject#*: }
+if [ "${#description}" -gt "$SUBJECT_MAX" ]; then
+  echo "commit-msg: subject is ${#description} characters, limit is $SUBJECT_MAX." >&2
+  echo "  move the detail into the commit body." >&2
+  exit 1
+fi

package/templates/layers/release-automation/files/.github/workflows/commit-conventions.yml

@@ -0,0 +1,45 @@
+name: Commit conventions
+
+# The PR title is the gate that matters: a squash merge turns it into the single commit
+# the release tool parses, so an unconventional title silently loses a release note.
+on:
+  pull_request:
+    types: [opened, edited, reopened, synchronize]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: commit-conventions-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+# Single place these are configured. Steps read from here and never inline a value.
+env:
+  COMMIT_TYPES: '{{ commitTypes }}'
+  SUBJECT_MAX: '{{ commitSubjectMax }}'
+
+jobs:
+  title:
+    name: Pull request title
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check the title is a conventional commit
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          set -eu
+
+          pattern="^($(printf '%s' "$COMMIT_TYPES" | tr ',' '|'))(\([a-z0-9._/-]+\))?!?: .+"
+
+          if ! printf '%s' "$PR_TITLE" | grep -Eq "$pattern"; then
+            echo "::error title=Unconventional PR title::Expected <type>[(scope)][!]: <subject>. Allowed types: $COMMIT_TYPES"
+            exit 1
+          fi
+
+          description=${PR_TITLE#*: }
+          if [ "${#description}" -gt "$SUBJECT_MAX" ]; then
+            echo "::error title=Subject too long::${#description} characters, limit is $SUBJECT_MAX. Move detail into the description."
+            exit 1
+          fi
+
+          echo "$PR_TITLE" >> "$GITHUB_STEP_SUMMARY"

package/templates/layers/release-automation/files/.github/workflows/release-changesets.yml

@@ -0,0 +1,68 @@
+name: Release
+
+on:
+  push:
+    branches: ['{{ releaseBranch }}']
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+# Single place these are configured. Steps read from here and never inline a value.
+env:
+  NODE_VERSION: '{{ nodeVersion }}'
+  NPM_REGISTRY_URL: '{{ npmRegistryUrl }}'
+
+jobs:
+  release:
+    name: Version or publish
+    runs-on: ubuntu-latest
+    environment: '{{ releaseEnvironment }}'
+    permissions:
+      contents: write # version commit and tags
+      pull-requests: write # the "Version Packages" PR
+      id-token: write # mints the OIDC token npm exchanges for a short-lived publish key
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0 # changesets diffs against tags to decide what changed
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          registry-url: ${{ env.NPM_REGISTRY_URL }}
+
+      - name: Install dependencies
+        run: |
+          set -eu
+          if [ -f pnpm-lock.yaml ]; then
+            npm install --global pnpm@latest
+            pnpm install --frozen-lockfile
+          elif [ -f yarn.lock ]; then
+            npm install --global yarn@latest
+            yarn install --immutable
+          else
+            npm ci
+          fi
+
+      - name: Build
+        run: npm run build --if-present
+
+      # Trusted publishing needs npm >= 11.5.1; the runner's bundled npm may predate it.
+      - name: Update npm
+        run: npm install --global npm@latest
+
+      # No NPM_TOKEN in env: the action only writes an auth line into .npmrc when one is
+      # set, and any auth line at all stops npm from falling back to OIDC.
+      # pnpm 11 has an open OIDC regression (pnpm/pnpm#11513) — see docs/release-automation.md.
+      - uses: changesets/action@v1
+        with:
+          version: npx changeset version
+          publish: npx changeset publish
+          commit: 'chore(release): version packages'
+          title: 'chore(release): version packages'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}