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.lockindex 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.jsonindex 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.jsonindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.shindex 661d52c2b..16132e58e 100755--- a/self-hosting/install.sh+++ b/self-hosting/install.sh@@ -10,7 +10,7 @@set -euRELEASES_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"' EXITecho "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.jsonnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.jsonnew file mode 100644index 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"+ ]+}