Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

release: version every main push, ship the CLI with the release

Carl-Gerhard Lindesvärd08c1f21b8f07
diff --git a/bun.lock b/bun.lock
index afe77882e..ef197eac8 100644
--- a/bun.lock
+++ b/bun.lock
@@ -606,6 +606,20 @@
"typescript": "catalog:",
},
},
+ "tooling/release": {
+ "name": "@openpanel/release",
+ "version": "0.1.0",
+ "dependencies": {
+ "@anthropic-ai/sdk": "0.130.0",
+ "semver": "7.6.0",
+ },
+ "devDependencies": {
+ "@openpanel/tsconfig": "workspace:*",
+ "@types/semver": "7.5.7",
+ "bun-types": "1.4.0",
+ "typescript": "catalog:",
+ },
+ },
"tooling/typescript": {
"name": "@openpanel/tsconfig",
"version": "0.1.0",
@@ -656,6 +670,8 @@
"@ampproject/remapping": ["@ampproject/[email protected]", "", { "dependencies": { "@jridgewell/gen-mapping": "^0.3.5", "@jridgewell/trace-mapping": "^0.3.24" } }, "sha512-30iZtAPgz+LTIYoeivqYo853f02jBYSd5uGnGpkFV0M3xOt9aN73erkgYAmZU43x4VfqcnLxW9Kpg3R5LC4YYw=="],
+ "@anthropic-ai/sdk": ["@anthropic-ai/[email protected]", "", { "dependencies": { "json-schema-to-ts": "^3.1.1", "standardwebhooks": "^1.0.0" }, "peerDependencies": { "zod": "^3.25.0 || ^4.0.0" }, "optionalPeers": ["zod"], "bin": { "anthropic-ai-sdk": "bin/cli" } }, "sha512-UMkwdFHvIdhYJHuPYkufmBTePKgk50RolnqZPUqyPclXp7LoVM7QgXsfQnx7KlmbkQtb+RhmUjN5ARYpbnz9YQ=="],
+
"@asamuzakjp/css-color": ["@asamuzakjp/[email protected]", "", { "dependencies": { "@csstools/css-calc": "^2.1.3", "@csstools/css-color-parser": "^3.0.9", "@csstools/css-parser-algorithms": "^3.0.4", "@csstools/css-tokenizer": "^3.0.3", "lru-cache": "^10.4.3" } }, "sha512-K1A6z8tS3XsmCMM86xoWdn7Fkdn9m6RSVtocUrJYIwZnFVkng/PvkEoWtOWmP+Scc6saYWHWZYbndEEXxl24jw=="],
"@ast-grep/napi": ["@ast-grep/[email protected]", "", { "optionalDependencies": { "@ast-grep/napi-darwin-arm64": "0.40.5", "@ast-grep/napi-darwin-x64": "0.40.5", "@ast-grep/napi-linux-arm64-gnu": "0.40.5", "@ast-grep/napi-linux-arm64-musl": "0.40.5", "@ast-grep/napi-linux-x64-gnu": "0.40.5", "@ast-grep/napi-linux-x64-musl": "0.40.5", "@ast-grep/napi-win32-arm64-msvc": "0.40.5", "@ast-grep/napi-win32-ia32-msvc": "0.40.5", "@ast-grep/napi-win32-x64-msvc": "0.40.5" } }, "sha512-hJA62OeBKUQT68DD2gDyhOqJxZxycqg8wLxbqjgqSzYttCMSDL9tiAQ9abgekBYNHudbJosm9sWOEbmCDfpX2A=="],
@@ -1594,6 +1610,8 @@
"@openpanel/redis": ["@openpanel/redis@workspace:packages/redis"],
+ "@openpanel/release": ["@openpanel/release@workspace:tooling/release"],
+
"@openpanel/sdk": ["@openpanel/sdk@workspace:packages/sdks/sdk"],
"@openpanel/sdk-info": ["@openpanel/sdk-info@workspace:packages/sdks/_info"],
diff --git a/package.json b/package.json
index 2d168806a..248c63df0 100644
--- a/package.json
+++ b/package.json
@@ -55,7 +55,7 @@
"vue": "3.5.25"
},
"scripts": {
- "test": "bun run --filter @openpanel/core test && bun run --filter @openpanel/db test && bun run --filter @openpanel/api test && bun run --filter @openpanel/seed test && bun run --filter start test && vitest run && bun test tooling/gates/conformance",
+ "test": "bun run --filter @openpanel/core test && bun run --filter @openpanel/db test && bun run --filter @openpanel/api test && bun run --filter @openpanel/seed test && bun run --filter start test && bun run --filter @openpanel/release test && vitest run && bun test tooling/gates/conformance",
"gen:bots": "bun run --filter @openpanel/core gen:bots",
"gen:referrers": "bun run --filter @openpanel/core gen:referrers",
"dock:up": "docker compose up -d",
diff --git a/self-hosting/cli/package.json b/self-hosting/cli/package.json
index 0c873e417..77e417b6c 100644
--- a/self-hosting/cli/package.json
+++ b/self-hosting/cli/package.json
@@ -1,6 +1,6 @@
{
"name": "@openpanel/cli",
- "version": "0.1.0",
+ "version": "0.0.0",
"private": true,
"type": "module",
"description": "Set up, upgrade and diagnose a self-hosted OpenPanel install",
diff --git a/self-hosting/cli/src/doctor/checks.ts b/self-hosting/cli/src/doctor/checks.ts
index 849660be5..4623b3e3c 100644
--- a/self-hosting/cli/src/doctor/checks.ts
+++ b/self-hosting/cli/src/doctor/checks.ts
@@ -1,8 +1,10 @@
import { randomBytes } from 'node:crypto';
import { type Document, isAlias, isMap, isSeq, parseDocument } from 'yaml';
+import { isNewer } from '../self-update';
import {
DEFAULT_EVENTS_TOPIC_PARTITIONS,
renderRedpandaBootstrap,
+ STACK_IMAGE_TAG,
templates,
} from '../templates';
import type { Check, Install } from './types';
@@ -194,20 +196,32 @@ export const redpandaBootstrapFile: Check = (install) => {
const OPENPANEL_IMAGE = /^(lindesvard\/openpanel-(?:api|dashboard)):(.+)$/;
const IMAGE_SERVICES = ['op-api', 'op-dashboard', 'op-worker'] as const;
-// The tag this CLI release is built for, read from the template so there is one
-// place to change it.
-export const STACK_IMAGE_TAG = String(
- templateCompose.getIn(['services', 'op-api', 'image'])
-)
- .split(':')
- .pop() as string;
+const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
+const MAJOR_ONLY = /^\d+$/;
+
+// An image already on the CLI's tag, or newer than it, is left alone: an older
+// CLI must never downgrade a stack. A dev build (floating major, e.g. "3") is
+// satisfied by any exact version of that major.
+export const satisfiesStack = (
+ tag: string,
+ stack: string = STACK_IMAGE_TAG
+): boolean => {
+ if (tag === stack) {
+ return true;
+ }
+ if (MAJOR_ONLY.test(stack)) {
+ return tag.startsWith(`${stack}.`) && EXACT_VERSION.test(tag);
+ }
+ const bothExact = EXACT_VERSION.test(tag) && EXACT_VERSION.test(stack);
+ return bothExact && isNewer(tag, stack);
+};
const staleImages = (install: Install) =>
IMAGE_SERVICES.flatMap((service) => {
const image = serviceImage(install, service);
const match = image ? OPENPANEL_IMAGE.exec(image) : null;
const [, repository, tag] = match ?? [];
- return repository && tag && tag !== STACK_IMAGE_TAG
+ return repository && tag && !satisfiesStack(tag)
? [{ service, repository, tag }]
: [];
});
diff --git a/self-hosting/cli/src/init/generate.ts b/self-hosting/cli/src/init/generate.ts
index 0c17cc08c..de82828bf 100644
--- a/self-hosting/cli/src/init/generate.ts
+++ b/self-hosting/cli/src/init/generate.ts
@@ -5,9 +5,16 @@ import type { EnvFile } from '../env-file';
import {
DEFAULT_EVENTS_TOPIC_PARTITIONS,
renderRedpandaBootstrap,
+ STACK_IMAGE_TAG,
templates,
} from '../templates';
+const OPENPANEL_IMAGE_SERVICES = [
+ 'op-api',
+ 'op-dashboard',
+ 'op-worker',
+] as const;
+
const BCRYPT_COST = 10;
const SECRET_BYTES = { cookie: 16, encryption: 32, admin: 12 } as const;
@@ -126,6 +133,16 @@ const renderCompose = (answers: InitAnswers): string => {
if (answers.proxy === 'external') {
removeService(compose, 'op-proxy');
}
+ for (const service of OPENPANEL_IMAGE_SERVICES) {
+ const image = String(compose.getIn(['services', service, 'image']) ?? '');
+ const repository = image.split(':')[0];
+ if (compose.hasIn(['services', service]) && repository) {
+ compose.setIn(
+ ['services', service, 'image'],
+ `${repository}:${STACK_IMAGE_TAG}`
+ );
+ }
+ }
// Interpolated by compose from .env, so scaling is one edit and `up -d`.
compose.setIn(
['services', 'op-worker', 'deploy', 'replicas'],
diff --git a/self-hosting/cli/src/self-update.ts b/self-hosting/cli/src/self-update.ts
index 263a2df6f..b60e25694 100644
--- a/self-hosting/cli/src/self-update.ts
+++ b/self-hosting/cli/src/self-update.ts
@@ -2,8 +2,10 @@ import { createHash } from 'node:crypto';
import { chmod, rename, writeFile } from 'node:fs/promises';
import { basename } from 'node:path';
-// CLI releases live next to the product's own, so they are told apart by tag.
-const RELEASE_TAG_PREFIX = 'cli-v';
+// The CLI ships inside each public self-hosting release (`v3.1.4`), so a
+// release counts only if it carries the CLI binaries. Internal builds are
+// tagged too but never become GitHub releases.
+const RELEASE_TAG_PREFIX = 'v';
const RELEASES_API =
process.env.OPENPANEL_RELEASES_API ??
'https://api.github.com/repos/Openpanel-dev/openpanel/releases?per_page=30';
@@ -70,7 +72,8 @@ export const fetchLatestRelease = async (
(release) =>
release.tag_name.startsWith(RELEASE_TAG_PREFIX) &&
!release.draft &&
- !release.prerelease
+ !release.prerelease &&
+ release.assets.some((asset) => asset.name === CHECKSUMS_ASSET)
);
if (!latest) {
return null;
diff --git a/self-hosting/cli/src/templates.ts b/self-hosting/cli/src/templates.ts
index 7e02da2be..75137435e 100644
--- a/self-hosting/cli/src/templates.ts
+++ b/self-hosting/cli/src/templates.ts
@@ -15,6 +15,7 @@ import composeTemplate from '../../docker-compose.template.yml' with {
import redpandaTemplate from '../../redpanda/bootstrap.template.yaml' with {
type: 'text',
};
+import { RELEASE_VERSION } from './version';
// `with { type: 'text' }` yields a string, but bun-types types *.xml as a DOM
// Document, so the two XML imports are narrowed here.
@@ -32,6 +33,14 @@ export const templates = {
export const DEFAULT_EVENTS_TOPIC_PARTITIONS = 24;
+const TEMPLATE_IMAGE_TAG = /lindesvard\/openpanel-api:(\S+)/;
+
+// The OpenPanel image tag this CLI installs: its own version for a release
+// build, so CLI and images always match; the template's tag for a dev build.
+export const STACK_IMAGE_TAG: string =
+ RELEASE_VERSION ??
+ (TEMPLATE_IMAGE_TAG.exec(templates.compose)?.[1] as string);
+
export const renderRedpandaBootstrap = (partitions: number): string =>
templates.redpanda.replace(
'$KAFKA_EVENTS_TOPIC_PARTITIONS',
diff --git a/self-hosting/cli/src/version.ts b/self-hosting/cli/src/version.ts
index 457ca268c..2e027d5f0 100644
--- a/self-hosting/cli/src/version.ts
+++ b/self-hosting/cli/src/version.ts
@@ -1,3 +1,13 @@
import pkg from '../package.json' with { type: 'json' };
-export const VERSION: string = pkg.version;
+// Release builds are stamped at compile time
+// (`bun build --define OPENPANEL_RELEASE_VERSION='"3.1.4"'`); anything else,
+// including `bun src/main.ts`, is a dev build.
+declare const OPENPANEL_RELEASE_VERSION: string | undefined;
+
+export const RELEASE_VERSION: string | null =
+ typeof OPENPANEL_RELEASE_VERSION === 'string'
+ ? OPENPANEL_RELEASE_VERSION
+ : null;
+
+export const VERSION: string = RELEASE_VERSION ?? `${pkg.version}-dev`;
diff --git a/self-hosting/cli/test/image-tag.test.ts b/self-hosting/cli/test/image-tag.test.ts
index 35bac3755..7a09f61ec 100644
--- a/self-hosting/cli/test/image-tag.test.ts
+++ b/self-hosting/cli/test/image-tag.test.ts
@@ -1,10 +1,10 @@
import { describe, expect, test } from 'bun:test';
import { parseDocument } from 'yaml';
import { applyFixes, runDoctor } from '../src/doctor';
-import { STACK_IMAGE_TAG } from '../src/doctor/checks';
+import { satisfiesStack } from '../src/doctor/checks';
import type { Install } from '../src/doctor/types';
import { EnvFile } from '../src/env-file';
-import { templates } from '../src/templates';
+import { STACK_IMAGE_TAG, templates } from '../src/templates';
// A current install whose image lines are replaced, so only the tag check can fire.
const installWithImages = (images: Record<string, string>): Install => {
@@ -99,3 +99,24 @@ describe('compose/image-tag', () => {
);
});
});
+
+describe('satisfiesStack', () => {
+ test('a release CLI moves floating and older tags to its exact version', () => {
+ expect(satisfiesStack('3', '3.1.4')).toBe(false);
+ expect(satisfiesStack('latest', '3.1.4')).toBe(false);
+ expect(satisfiesStack('3.1.3', '3.1.4')).toBe(false);
+ expect(satisfiesStack('2.3.0', '3.1.4')).toBe(false);
+ });
+
+ test('a release CLI never downgrades newer images', () => {
+ expect(satisfiesStack('3.1.4', '3.1.4')).toBe(true);
+ expect(satisfiesStack('3.2.0', '3.1.4')).toBe(true);
+ });
+
+ test('a dev build (floating major) accepts any exact version of that major', () => {
+ expect(satisfiesStack('3.1.4', '3')).toBe(true);
+ expect(satisfiesStack('3', '3')).toBe(true);
+ expect(satisfiesStack('2', '3')).toBe(false);
+ expect(satisfiesStack('2.3.0', '3')).toBe(false);
+ });
+});
diff --git a/self-hosting/cli/test/self-update.test.ts b/self-hosting/cli/test/self-update.test.ts
index 4142b39de..91e6dcae8 100644
--- a/self-hosting/cli/test/self-update.test.ts
+++ b/self-hosting/cli/test/self-update.test.ts
@@ -36,7 +36,7 @@ const fakeFetcher = (
const name = assetName('linux', 'x64');
const base = 'https://example.test';
const release = {
- tag_name: options.tag ?? 'cli-v0.2.0',
+ tag_name: options.tag ?? 'v0.2.0',
draft: false,
prerelease: false,
assets: [
@@ -47,7 +47,8 @@ const fakeFetcher = (
return async (url) => {
if (url.includes('/releases')) {
return Response.json([
- { tag_name: 'v2.9.0', draft: false, prerelease: false, assets: [] },
+ // A release without the CLI binaries (say, a docs-only one) is not a CLI release.
+ { tag_name: 'v9.9.9', draft: false, prerelease: false, assets: [] },
release,
]);
}
@@ -138,12 +139,12 @@ describe('selfUpdate', () => {
expect(readFileSync(execPath, 'utf8')).toBe('old-binary-bytes');
});
- test('product releases without the cli- prefix are ignored', async () => {
+ test('releases tagged another way (like the old cli-v*) are ignored', async () => {
const execPath = installedBinary();
const result = await selfUpdate({
currentVersion: '0.1.0',
execPath,
- fetcher: fakeFetcher({ tag: 'v9.9.9' }),
+ fetcher: fakeFetcher({ tag: 'cli-v9.9.9' }),
platform: 'linux',
arch: 'x64',
});
diff --git a/self-hosting/cli/test/update-notice.test.ts b/self-hosting/cli/test/update-notice.test.ts
index 6510ff283..224e80a9d 100644
--- a/self-hosting/cli/test/update-notice.test.ts
+++ b/self-hosting/cli/test/update-notice.test.ts
@@ -33,10 +33,15 @@ const feed = (version: string): { fetcher: Fetcher; calls: () => number } => {
calls++;
return Response.json([
{
- tag_name: `cli-v${version}`,
+ tag_name: `v${version}`,
draft: false,
prerelease: false,
- assets: [],
+ assets: [
+ {
+ name: 'checksums.txt',
+ browser_download_url: 'https://example.test/checksums.txt',
+ },
+ ],
},
]);
},
diff --git a/self-hosting/install.sh b/self-hosting/install.sh
index 661d52c2b..16132e58e 100755
--- a/self-hosting/install.sh
+++ b/self-hosting/install.sh
@@ -10,7 +10,7 @@
set -eu
RELEASES_API="${OPENPANEL_RELEASES_API:-https://api.github.com/repos/Openpanel-dev/openpanel/releases?per_page=30}"
-TAG_PREFIX="cli-v"
+TAG_PREFIX="v"
fail() {
echo "error: $*" >&2
@@ -47,10 +47,14 @@ trap 'rm -rf "$tmp"' EXIT
echo "Finding the latest release..."
curl -fsSL "$RELEASES_API" -o "$tmp/releases.json" || fail "could not reach $RELEASES_API"
-# Each release object lists its tag before its assets, so the first matching
-# tag's asset URLs are the ones that follow it, up to the next tag.
-tag="$(grep -o "\"tag_name\": *\"$TAG_PREFIX[^\"]*\"" "$tmp/releases.json" | head -n 1 | cut -d'"' -f4)"
-[ -n "$tag" ] || fail "no $TAG_PREFIX release found"
+# Each release object lists its tag before its assets. The newest release that
+# carries this machine's binary is the one to install: every public self-hosting
+# release does, and internal version tags never become releases at all.
+tag="$(awk -v prefix="\"$TAG_PREFIX" -v name="/$asset\"" '
+ /"tag_name":/ { split($0, parts, "\""); current = (index("\"" parts[4], prefix) == 1) ? parts[4] : "" }
+ current != "" && /"browser_download_url":/ && index($0, name) { print current; exit }
+' "$tmp/releases.json")"
+[ -n "$tag" ] || fail "no release with $asset found"
url_for() {
awk -v tag="$tag" -v name="$1" '
diff --git a/tooling/release/package.json b/tooling/release/package.json
new file mode 100644
index 000000000..04b31d0af
--- /dev/null
+++ b/tooling/release/package.json
@@ -0,0 +1,21 @@
+{
+ "name": "@openpanel/release",
+ "version": "0.1.0",
+ "private": true,
+ "license": "MIT",
+ "type": "module",
+ "scripts": {
+ "test": "bun test",
+ "typecheck": "tsc --noEmit"
+ },
+ "dependencies": {
+ "@anthropic-ai/sdk": "0.130.0",
+ "semver": "7.6.0"
+ },
+ "devDependencies": {
+ "@openpanel/tsconfig": "workspace:*",
+ "@types/semver": "7.5.7",
+ "bun-types": "1.4.0",
+ "typescript": "catalog:"
+ }
+}
diff --git a/tooling/release/src/decide.test.ts b/tooling/release/src/decide.test.ts
new file mode 100644
index 000000000..a7cdf1c9e
--- /dev/null
+++ b/tooling/release/src/decide.test.ts
@@ -0,0 +1,66 @@
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { decide } from './next-version';
+
+const repo = mkdtempSync(join(tmpdir(), 'op-release-'));
+const run = (...args: string[]) =>
+ execFileSync('git', args, { cwd: repo, encoding: 'utf8' }).trim();
+const commit = (message: string) => {
+ run('commit', '--allow-empty', '-q', '-m', message);
+ return run('rev-parse', 'HEAD');
+};
+const originalCwd = process.cwd();
+
+beforeAll(() => {
+ run('init', '-q', '-b', 'main');
+ run('config', 'user.email', '[email protected]');
+ run('config', 'user.name', 'test');
+ process.chdir(repo);
+});
+
+afterAll(() => {
+ process.chdir(originalCwd);
+ rmSync(repo, { recursive: true, force: true });
+});
+
+describe('decide', () => {
+ test('from the v2.3.0 baseline, the first push is v3.0.0', () => {
+ run('tag', 'v2.3.0', commit('v2 era'));
+ const head = commit('self-hosting: the openpanel CLI');
+ expect(decide(head)).toEqual({
+ kind: 'new',
+ version: '3.0.0',
+ previous: '2.3.0',
+ bump: 'patch',
+ });
+ run('tag', 'v3.0.0', head);
+ });
+
+ test('a feat since the last tag is a minor bump', () => {
+ commit('fix: small thing');
+ const head = commit('feat(api): new endpoint');
+ expect(decide(head)).toMatchObject({
+ kind: 'new',
+ version: '3.1.0',
+ bump: 'minor',
+ });
+ run('tag', 'v3.1.0', head);
+ });
+
+ test('rerunning an already-tagged commit keeps its version', () => {
+ expect(decide(run('rev-parse', 'HEAD'))).toEqual({
+ kind: 'existing',
+ version: '3.1.0',
+ });
+ });
+
+ test('a run for an older commit that finishes after a newer release is skipped', () => {
+ const older = commit('fix: older push');
+ const newer = commit('fix: newer push');
+ run('tag', 'v3.1.1', newer);
+ expect(decide(older)).toEqual({ kind: 'superseded', by: '3.1.1' });
+ });
+});
diff --git a/tooling/release/src/git.ts b/tooling/release/src/git.ts
new file mode 100644
index 000000000..3d53781f3
--- /dev/null
+++ b/tooling/release/src/git.ts
@@ -0,0 +1,22 @@
+import { execFileSync } from 'node:child_process';
+
+export const git = (...args: string[]): string =>
+ execFileSync('git', args, {
+ encoding: 'utf8',
+ maxBuffer: 256 * 1024 * 1024,
+ }).trim();
+
+// Absent refs are normal here (no earlier tag), so they return null rather than throw.
+export const gitOrNull = (...args: string[]): string | null => {
+ try {
+ return git(...args);
+ } catch {
+ return null;
+ }
+};
+
+export const lines = (text: string | null): string[] =>
+ (text ?? '')
+ .split('\n')
+ .map((line) => line.trim())
+ .filter(Boolean);
diff --git a/tooling/release/src/next-version.test.ts b/tooling/release/src/next-version.test.ts
new file mode 100644
index 000000000..8980b5aad
--- /dev/null
+++ b/tooling/release/src/next-version.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, test } from 'bun:test';
+import {
+ bumpFor,
+ highestBump,
+ MINIMUM_VERSION,
+ nextVersion,
+} from './next-version';
+
+describe('bumpFor', () => {
+ test.each([
+ ['fix(dashboard): stop double-encoding ids', 'patch'],
+ ['self-hosting: fix what the review found', 'patch'],
+ ['ci: faster builds', 'patch'],
+ ['feat: funnels by cohort', 'minor'],
+ ['feat(api): export endpoint', 'minor'],
+ ['self-hosting: new doctor check [minor]', 'minor'],
+ ['feat!: drop the v1 ingest route', 'major'],
+ ['fix(api)!: rename the events field', 'major'],
+ [
+ 'refactor: move ingest\n\nBREAKING CHANGE: KAFKA_BROKERS is required',
+ 'major',
+ ],
+ ['merge the rewrite [major]', 'major'],
+ ] as const)('%s -> %s', (message, bump) => {
+ expect(bumpFor(message)).toBe(bump);
+ });
+
+ test('"feat" only counts as the type, not anywhere in the subject', () => {
+ expect(bumpFor('docs: describe the feat: syntax')).toBe('patch');
+ });
+});
+
+describe('highestBump', () => {
+ test('a push takes the largest bump among its commits', () => {
+ expect(highestBump(['fix: a', 'feat: b', 'ci: c'])).toBe('minor');
+ expect(highestBump(['fix: a', 'feat!: b'])).toBe('major');
+ expect(highestBump([])).toBe('patch');
+ });
+});
+
+describe('nextVersion', () => {
+ test('bumps the previous release', () => {
+ expect(nextVersion('3.1.4', 'patch')).toBe('3.1.5');
+ expect(nextVersion('3.1.4', 'minor')).toBe('3.2.0');
+ expect(nextVersion('3.1.4', 'major')).toBe('4.0.0');
+ });
+
+ test('never produces anything below the v3 floor', () => {
+ expect(nextVersion(null, 'patch')).toBe(MINIMUM_VERSION);
+ expect(nextVersion('2.3.0', 'patch')).toBe(MINIMUM_VERSION);
+ expect(nextVersion('2.3.0', 'minor')).toBe(MINIMUM_VERSION);
+ });
+});
diff --git a/tooling/release/src/next-version.ts b/tooling/release/src/next-version.ts
new file mode 100644
index 000000000..c57e35a03
--- /dev/null
+++ b/tooling/release/src/next-version.ts
@@ -0,0 +1,134 @@
+import { appendFileSync } from 'node:fs';
+import semver from 'semver';
+import { git, gitOrNull, lines } from './git';
+
+export type Bump = 'patch' | 'minor' | 'major';
+
+// v3 is the first release numbered this way. Anything computed below it (the
+// baseline tag is v2.3.0) is lifted to it, so v3 code can never ship as 2.3.x.
+export const MINIMUM_VERSION = '3.0.0';
+export const TAG_PREFIX = 'v';
+const TAG_PATTERN = 'v[0-9]*';
+
+const BUMP_RANK: Record<Bump, number> = { patch: 0, minor: 1, major: 2 };
+const MAJOR_MARKER = '[major]';
+const MINOR_MARKER = '[minor]';
+// Conventional commits: `feat!:` / `fix(api)!:` and a BREAKING CHANGE footer are
+// breaking, `feat:` / `feat(scope):` is a feature. Every other subject is a patch.
+const BREAKING_SUBJECT = /^[a-z]+(\([^)]*\))?!:/i;
+const BREAKING_FOOTER = /^BREAKING[ -]CHANGE:/m;
+const FEATURE_SUBJECT = /^feat(\([^)]*\))?:/i;
+
+export const bumpFor = (message: string): Bump => {
+ const subject = message.split('\n', 1)[0]?.trim() ?? '';
+ const isBreaking =
+ message.includes(MAJOR_MARKER) ||
+ BREAKING_SUBJECT.test(subject) ||
+ BREAKING_FOOTER.test(message);
+ if (isBreaking) {
+ return 'major';
+ }
+ const isFeature =
+ message.includes(MINOR_MARKER) || FEATURE_SUBJECT.test(subject);
+ return isFeature ? 'minor' : 'patch';
+};
+
+export const highestBump = (messages: string[]): Bump =>
+ messages
+ .map(bumpFor)
+ .reduce<Bump>(
+ (highest, bump) =>
+ BUMP_RANK[bump] > BUMP_RANK[highest] ? bump : highest,
+ 'patch'
+ );
+
+export const nextVersion = (previous: string | null, bump: Bump): string => {
+ const candidate = previous ? semver.inc(previous, bump) : null;
+ if (!candidate || semver.lt(candidate, MINIMUM_VERSION)) {
+ return MINIMUM_VERSION;
+ }
+ return candidate;
+};
+
+export type Decision =
+ | { kind: 'existing'; version: string }
+ | { kind: 'superseded'; by: string }
+ | { kind: 'new'; version: string; previous: string | null; bump: Bump };
+
+const versionOf = (tag: string) => semver.valid(tag.slice(TAG_PREFIX.length));
+
+const highestVersion = (tags: string[]): string | null =>
+ tags
+ .map(versionOf)
+ .filter((version): version is string => version !== null)
+ .sort(semver.rcompare)[0] ?? null;
+
+export const decide = (sha: string): Decision => {
+ // A rerun of an already-tagged commit keeps its number.
+ const existing = highestVersion(
+ lines(gitOrNull('tag', '--points-at', sha, '--list', TAG_PATTERN))
+ );
+ if (existing) {
+ return { kind: 'existing', version: existing };
+ }
+ // A later commit already released means this run finished late: tagging it
+ // now would give an older commit a higher version.
+ const newer = highestVersion(
+ lines(gitOrNull('tag', '--contains', sha, '--list', TAG_PATTERN))
+ );
+ if (newer) {
+ return { kind: 'superseded', by: newer };
+ }
+
+ const previousTag = gitOrNull(
+ 'describe',
+ '--tags',
+ '--abbrev=0',
+ '--match',
+ TAG_PATTERN,
+ sha
+ );
+ const previous = previousTag ? versionOf(previousTag) : null;
+ const range = previousTag ? `${previousTag}..${sha}` : sha;
+ const messages = git('log', '--format=%B%x00', range)
+ .split('\0')
+ .filter((message) => message.trim());
+ const bump = highestBump(messages);
+ return { kind: 'new', version: nextVersion(previous, bump), previous, bump };
+};
+
+const writeOutputs = (outputs: Record<string, string>) => {
+ const text = Object.entries(outputs)
+ .map(([key, value]) => `${key}=${value}\n`)
+ .join('');
+ if (process.env.GITHUB_OUTPUT) {
+ appendFileSync(process.env.GITHUB_OUTPUT, text);
+ }
+ process.stdout.write(text);
+};
+
+if (import.meta.main) {
+ const sha = process.argv[2] ?? 'HEAD';
+ const decision = decide(sha);
+ if (decision.kind === 'superseded') {
+ console.error(
+ `${sha} is older than the released v${decision.by}; not tagging it.`
+ );
+ writeOutputs({ skip: 'true' });
+ } else {
+ const version = decision.version;
+ const major = String(semver.major(version));
+ console.error(
+ decision.kind === 'existing'
+ ? `${sha} is already v${version}`
+ : `${decision.previous ?? 'no earlier tag'} + ${decision.bump} -> ${version}`
+ );
+ writeOutputs({
+ skip: 'false',
+ is_new: String(decision.kind === 'new'),
+ version,
+ minor: `${major}.${semver.minor(version)}`,
+ major,
+ });
+ }
+}
diff --git a/tooling/release/src/release-notes.test.ts b/tooling/release/src/release-notes.test.ts
new file mode 100644
index 000000000..4a7f6f6a6
--- /dev/null
+++ b/tooling/release/src/release-notes.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, test } from 'bun:test';
+import type Anthropic from '@anthropic-ai/sdk';
+import {
+ fallbackNotes,
+ generateNotes,
+ isUpgradeSensitive,
+ type NotesInput,
+ stripMarkers,
+} from './release-notes';
+
+const input: NotesInput = {
+ version: '3.1.0',
+ previous: '3.0.0',
+ commits: [
+ {
+ sha: 'a'.repeat(40),
+ subject: 'feat(api): export endpoint [minor]',
+ body: 'Adds /export.',
+ },
+ { sha: 'b'.repeat(40), subject: 'fix: stop crash [release now]', body: '' },
+ ],
+ sensitivePaths: ['apps/api/src/config/env.ts'],
+ compareUrl: 'https://github.com/o/r/compare/v3.0.0...v3.1.0',
+};
+
+// Just enough of the client for generateNotes; each test decides the outcome.
+const fakeClient = (create: () => Promise<unknown>) =>
+ ({ beta: { messages: { create } } }) as unknown as Anthropic;
+
+describe('release notes', () => {
+ test('CI markers never reach the notes', () => {
+ expect(stripMarkers('fix: stop crash [release now] [MINOR]')).toBe(
+ 'fix: stop crash'
+ );
+ });
+
+ test('upgrade-sensitive paths are recognised', () => {
+ expect(isUpgradeSensitive('self-hosting/docker-compose.template.yml')).toBe(
+ true
+ );
+ expect(
+ isUpgradeSensitive('packages/db/prisma/migrations/2026/migration.sql')
+ ).toBe(true);
+ expect(isUpgradeSensitive('apps/start/src/routes/index.tsx')).toBe(false);
+ });
+
+ test('the fallback lists every commit without markers, with the compare link', () => {
+ const notes = fallbackNotes(input);
+ expect(notes).toContain('- feat(api): export endpoint (aaaaaaa)');
+ expect(notes).toContain('- fix: stop crash (bbbbbbb)');
+ expect(notes).not.toContain('[');
+ expect(notes).toContain(input.compareUrl as string);
+ });
+
+ test('no API key means the fallback, not a failed release', async () => {
+ expect(await generateNotes(input, null)).toMatchObject({
+ source: 'fallback',
+ reason: 'no API key',
+ });
+ });
+
+ test('an API error means the fallback, not a failed release', async () => {
+ const client = fakeClient(() =>
+ Promise.reject(new Error('529 overloaded'))
+ );
+ expect(await generateNotes(input, client)).toMatchObject({
+ source: 'fallback',
+ reason: '529 overloaded',
+ });
+ });
+
+ test('a declined request means the fallback', async () => {
+ const client = fakeClient(() =>
+ Promise.resolve({ stop_reason: 'refusal', content: [] })
+ );
+ expect(await generateNotes(input, client)).toMatchObject({
+ source: 'fallback',
+ reason: 'model declined',
+ });
+ });
+
+ test('model text is used, with the compare link appended', async () => {
+ const client = fakeClient(() =>
+ Promise.resolve({
+ stop_reason: 'end_turn',
+ content: [
+ { type: 'thinking', thinking: '' },
+ { type: 'text', text: '## Added\n- Export endpoint' },
+ ],
+ })
+ );
+ const notes = await generateNotes(input, client);
+ expect(notes.source).toBe('claude');
+ expect(notes.markdown).toStartWith('## Added\n- Export endpoint');
+ expect(notes.markdown).toContain(input.compareUrl as string);
+ });
+});
diff --git a/tooling/release/src/release-notes.ts b/tooling/release/src/release-notes.ts
new file mode 100644
index 000000000..df31ac68f
--- /dev/null
+++ b/tooling/release/src/release-notes.ts
@@ -0,0 +1,188 @@
+import { writeFileSync } from 'node:fs';
+import { parseArgs } from 'node:util';
+import Anthropic from '@anthropic-ai/sdk';
+import { git, lines } from './git';
+
+const MODEL = 'claude-opus-5-5';
+const MAX_TOKENS = 16_000;
+const FIELD = '\u001f';
+const RECORD = '\u001e';
+
+// Markers only steer CI (debounce, version bump); they are noise in the notes.
+const CI_MARKERS = /\s*\[(release now|minor|major)\]/gi;
+
+// Paths whose changes mean a self-hoster may have to act when upgrading.
+export const UPGRADE_SENSITIVE_PATHS = [
+ 'self-hosting/',
+ 'apps/api/src/config/env.ts',
+ 'packages/db/prisma/migrations/',
+ 'packages/db/src/code-migrations/',
+ 'apps/api/Dockerfile',
+ 'apps/start/Dockerfile',
+] as const;
+
+export interface Commit {
+ sha: string;
+ subject: string;
+ body: string;
+}
+
+export interface NotesInput {
+ version: string;
+ previous: string;
+ commits: Commit[];
+ sensitivePaths: string[];
+ compareUrl: string | null;
+}
+
+export const stripMarkers = (text: string): string =>
+ text.replace(CI_MARKERS, '').trim();
+
+export const isUpgradeSensitive = (path: string): boolean =>
+ UPGRADE_SENSITIVE_PATHS.some(
+ (prefix) => path === prefix || path.startsWith(prefix)
+ );
+
+const compareLine = (input: NotesInput) =>
+ input.compareUrl ? `\n\n**Full changelog:** ${input.compareUrl}` : '';
+
+// Used when the API is unavailable: accurate, just unsummarised.
+export const fallbackNotes = (input: NotesInput): string => {
+ const items = input.commits.map(
+ (commit) => `- ${stripMarkers(commit.subject)} (${commit.sha.slice(0, 7)})`
+ );
+ return `## Changes since v${input.previous}\n\n${items.join('\n')}${compareLine(input)}\n`;
+};
+
+const SYSTEM_PROMPT = `You write release notes for OpenPanel, an open-source product analytics tool that people self-host with Docker Compose and upgrade with the \`openpanel\` CLI.
+
+You get the commit messages between two releases, and the list of changed files that can affect a self-hosted install. Write Markdown release notes for the people running it.
+
+Rules:
+- Describe only what the commit messages say. Never invent features, numbers, or behaviour, and do not guess at what an unexplained change does.
+- Group into these sections, leaving out any that would be empty: "Highlights" (at most 3 bullets, only for changes a user would notice), "Added", "Changed", "Fixed", "Upgrade notes".
+- "Upgrade notes" covers anything a self-hoster must know or do: new or renamed environment variables, compose changes, migrations, removed features. Base it on the commits and the changed-files list. Mention that \`openpanel upgrade\` applies the compose and .env changes when the commits say so.
+- Leave out purely internal work (CI, tests, lint, refactors with no visible effect); if the release is only that, write a single line saying it contains internal improvements.
+- One line per bullet, plain language, no commit hashes, no author names, no marketing tone.
+- Do not start with a title; the release already has one.`;
+
+const userPrompt = (input: NotesInput): string => {
+ const commits = input.commits
+ .map(
+ (commit) =>
+ `### ${stripMarkers(commit.subject)}\n${stripMarkers(commit.body)}`
+ )
+ .join('\n\n');
+ const sensitive =
+ input.sensitivePaths.length > 0
+ ? input.sensitivePaths.join('\n')
+ : '(none)';
+ return `Release v${input.version} (previous release: v${input.previous}).\n\nChanged files that can affect a self-hosted install:\n${sensitive}\n\nCommits:\n\n${commits}`;
+};
+
+type Generated = {
+ markdown: string;
+ source: 'claude' | 'fallback';
+ reason?: string;
+};
+
+export const generateNotes = async (
+ input: NotesInput,
+ client: Anthropic | null
+): Promise<Generated> => {
+ if (!client) {
+ return {
+ markdown: fallbackNotes(input),
+ source: 'fallback',
+ reason: 'no API key',
+ };
+ }
+ try {
+ const response = await client.beta.messages.create({
+ model: MODEL,
+ max_tokens: MAX_TOKENS,
+ betas: ['server-side-fallback-2026-07-01'],
+ fallbacks: 'default',
+ output_config: { effort: 'medium' },
+ system: SYSTEM_PROMPT,
+ messages: [{ role: 'user', content: userPrompt(input) }],
+ });
+ if (response.stop_reason === 'refusal') {
+ return {
+ markdown: fallbackNotes(input),
+ source: 'fallback',
+ reason: 'model declined',
+ };
+ }
+ const text = response.content
+ .flatMap((block) => (block.type === 'text' ? [block.text] : []))
+ .join('')
+ .trim();
+ if (!text) {
+ return {
+ markdown: fallbackNotes(input),
+ source: 'fallback',
+ reason: 'empty response',
+ };
+ }
+ return { markdown: `${text}${compareLine(input)}\n`, source: 'claude' };
+ } catch (error) {
+ return {
+ markdown: fallbackNotes(input),
+ source: 'fallback',
+ reason: (error as Error).message,
+ };
+ }
+};
+
+export const readCommits = (from: string, to: string): Commit[] =>
+ git(
+ 'log',
+ '--no-merges',
+ `--format=%H${FIELD}%s${FIELD}%b${RECORD}`,
+ `${from}..${to}`
+ )
+ .split(RECORD)
+ .map((record) => record.trim())
+ .filter(Boolean)
+ .map((record) => {
+ const [sha = '', subject = '', body = ''] = record.split(FIELD);
+ return { sha, subject, body: body.trim() };
+ });
+
+if (import.meta.main) {
+ const { values } = parseArgs({
+ options: {
+ from: { type: 'string' },
+ to: { type: 'string' },
+ out: { type: 'string', default: 'release-notes.md' },
+ },
+ });
+ if (!(values.from && values.to)) {
+ throw new Error(
+ 'Usage: release-notes.ts --from v3.0.0 --to v3.1.0 [--out notes.md]'
+ );
+ }
+ const repository = process.env.GITHUB_REPOSITORY;
+ const input: NotesInput = {
+ version: values.to.replace(/^v/, ''),
+ previous: values.from.replace(/^v/, ''),
+ commits: readCommits(values.from, values.to),
+ sensitivePaths: lines(
+ git('diff', '--name-only', values.from, values.to)
+ ).filter(isUpgradeSensitive),
+ compareUrl: repository
+ ? `${process.env.GITHUB_SERVER_URL ?? 'https://github.com'}/${repository}/compare/${values.from}...${values.to}`
+ : null,
+ };
+ const client = process.env.ANTHROPIC_API_KEY ? new Anthropic() : null;
+ const notes = await generateNotes(input, client);
+ writeFileSync(values.out, notes.markdown);
+ const usage =
+ notes.source === 'claude'
+ ? 'written by Claude'
+ : `plain commit list (${notes.reason})`;
+ console.error(
+ `${input.commits.length} commits, ${input.sensitivePaths.length} upgrade-sensitive files; notes ${usage} -> ${values.out}`
+ );
+}
diff --git a/tooling/release/tsconfig.json b/tooling/release/tsconfig.json
new file mode 100644
index 000000000..7dd5678bf
--- /dev/null
+++ b/tooling/release/tsconfig.json
@@ -0,0 +1,16 @@
+{
+ "extends": "@openpanel/tsconfig/base.json",
+ "compilerOptions": {
+ "tsBuildInfoFile": "node_modules/.cache/tsbuildinfo.json",
+ "strictNullChecks": true,
+ "types": [
+ "bun-types"
+ ]
+ },
+ "include": [
+ "."
+ ],
+ "exclude": [
+ "node_modules"
+ ]
+}