Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Version stable promotions from the changeset delta over the last stable (#2654)
Andrew Mikofalvybf2e3c085cb1
diff --git a/.changeset/stable-version-from-changeset-delta.md b/.changeset/stable-version-from-changeset-delta.mdnew file mode 100644index 000000000..80abf198c--- /dev/null+++ b/.changeset/stable-version-from-changeset-delta.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Stable releases are now versioned as a single semantic-version bump over the previous stable, derived from the changeset delta between them, instead of stripping the `-beta.N` suffix from the promoted beta tag. Accumulated patch work now ships as its own patch (for example `0.30.1 → 0.30.2`) rather than collapsing an entire beta cycle to one stable, and a minor changeset in the delta still bumps the minor. Promotion selection and version determination are also separated: a scheduled job selects the newest soak-proven beta, and the promote job — shared by manual and automatic promotions — computes the version.diff --git a/.github/scripts/promote-stable-auto.mjs b/.github/scripts/select-beta-to-promote.mjssimilarity index 50%rename from .github/scripts/promote-stable-auto.mjsrename to .github/scripts/select-beta-to-promote.mjsindex e9d9ff6a9..5e7db5d9e 100644--- a/.github/scripts/promote-stable-auto.mjs+++ b/.github/scripts/select-beta-to-promote.mjs@@ -1,35 +1,34 @@-// Beta-selection logic for the Auto-promote stable workflow-// (.github/workflows/promote-stable-auto.yml).+// Beta-selection logic for the Select beta to promote workflow+// (.github/workflows/select-beta-to-promote.yml).//-// Extracted here (rather than inline bash) so the release-critical decision —-// which beta, if any, to promote to stable — is unit-tested under-// `bun test --cwd .github/scripts` (the OK `check` gate), mirroring the-// scripts/compute-next-beta.mjs precedent. The pure core (deriveStableTag,-// parseBetaTags, selectPromotion) takes its git/GitHub boundary as injected+// This job does SELECTION ONLY: it finds the most-recently soak-proven beta+// (the newest beta that is fully cut AND online >= 24h) that has NOT already+// been shipped in the latest stable, then dispatches promote-stable.yml with it+// as an explicit beta_tag. It computes NO version — promote-stable.yml owns+// version determination (scripts/compute-stable-version.mjs), so manual and auto+// promotions share one source of version truth.+//+// Extracted here (rather than inline bash) so the release-critical selection is+// unit-tested under `bun test --cwd .github/scripts` (the OK `check` gate),+// mirroring the scripts/compute-next-beta.mjs precedent. The pure core+// (parseBetaTags, selectPromotion) takes its git/GitHub boundary as injected// dependencies so tests need no live repo or API.//// Fail-loud contract: selectPromotion treats ONLY a genuine "release not found"// (404) as "this beta has no release yet" (skip to the next-older candidate).// Any other fetch failure (auth, network, rate-limit) is an infrastructure-// error the caller must surface and retry, NEVER fold into a promote/no-op+// error the caller must surface and retry, NEVER fold into a select/no-op// decision — an unattended path that ships npm `latest` + a signed auto-update// DMG must not mis-decide silently. fetchReleaseMeta signals this by returning// null for 404 and throwing for everything else; selectPromotion lets the throw// propagate so main() can exit non-zero.-import { execFileSync } from "node:child_process";+import { execFileSync, spawnSync } from "node:child_process";import { appendFileSync } from "node:fs";import { pathToFileURL } from "node:url";const BETA_TAG_RE = /^v\d+\.\d+\.\d+-beta\.\d+$/;--// v0.10.0-beta.10 -> v0.10.0. The digit-run match keeps double-digit beta-// numbers intact (the derived stable tag drops the whole -beta.N suffix).-export function deriveStableTag(betaTag) {- const m = /^(v\d+\.\d+\.\d+)-beta\.\d+$/.exec(betaTag);- if (!m) throw new Error(`not a vX.Y.Z-beta.N tag: ${betaTag}`);- return m[1];-}+const STABLE_TAG_RE = /^v\d+\.\d+\.\d+$/;// Filter raw `git tag` output to conforming beta tags, preserving input order.// Ordering is git's job (`--sort=-version:refname`, newest first) — the same@@ -49,42 +48,70 @@ function isFullyCut(meta) {return meta.isDraft !== true && Boolean(meta.publishedAt) && hasDmg && hasManifest;}-// Walk betaTags newest -> oldest and return the promotion decision:-// { kind: "select", target, stableTag } -> dispatch promote-stable for `target`-// { kind: "stop-promoted", beta, stableTag } -> newest unpromoted candidate is already-// promoted; descent stops (no target)-// { kind: "none" } -> nothing eligible right now-// Selects the LATEST beta that is unpromoted + fully cut + soaked >= soakSeconds.-// A fresher, under-soaked/not-yet-cut head is skipped in favor of the previous-// eligible beta; the descent STOPS at the first already-promoted beta so it-// never reaches back across a promoted cycle boundary. Propagates any throw from-// fetchReleaseMeta (a non-404 infra error) instead of skipping the candidate.-export function selectPromotion({ betaTags, tagExists, fetchReleaseMeta, soakSeconds, nowMs }) {+// Walk betaTags newest -> oldest and return the selection decision:+// { kind: "select", target } -> dispatch promote-stable for `target`+// { kind: "none" } -> nothing eligible right now+// Selects the NEWEST beta that is unshipped + fully cut + soaked >= soakSeconds.+// A fresher head that is under-soaked or not-yet-cut is skipped in favor of the+// previous soaked beta. The descent STOPS at the first already-shipped beta (its+// commit is contained in the latest stable, so everything older is too), so it+// never reaches back across a shipped boundary. Version is NOT computed here —+// promote-stable derives it from the changeset delta over the latest stable.+// Propagates any throw from fetchReleaseMeta (a non-404 infra error) instead of+// skipping the candidate.+export function selectPromotion({ betaTags, isAlreadyShipped, fetchReleaseMeta, soakSeconds, nowMs }) {const soakMs = soakSeconds * 1000;for (const beta of betaTags) {- const stableTag = deriveStableTag(beta);- if (tagExists(stableTag)) {- return { kind: "stop-promoted", beta, stableTag };+ if (isAlreadyShipped(beta)) {+ // This beta's commit is already in the latest stable; every older beta is+ // too. Nothing newer than this is eligible below, so stop.+ return { kind: "none" };}const meta = fetchReleaseMeta(beta); // null === 404 (no release yet); throws on infra errorif (meta === null) continue;if (!isFullyCut(meta)) continue;const ageMs = nowMs - Date.parse(meta.publishedAt);if (Number.isNaN(ageMs) || ageMs < soakMs) continue;- return { kind: "select", target: beta, stableTag };+ return { kind: "select", target: beta };}return { kind: "none" };}// --- workflow-runtime wiring (real git / gh boundary) ----function realTagExists(tag) {- try {- execFileSync("git", ["rev-parse", "--verify", "--quiet", `refs/tags/${tag}`], { stdio: "ignore" });- return true;- } catch {- return false;+// Newest plain vX.Y.Z stable tag's commit SHA ("" if no stable exists yet). The+// shipped boundary is defined by commit ancestry against this SHA rather than by+// a stable-tag-name existence check: under delta versioning a beta's name no+// longer maps 1:1 to a stable version, so "is this beta already released" is+// "is its commit contained in the latest stable".+function resolveLatestStableSha() {+ const out = execFileSync("git", ["tag", "--list", "v*", "--sort=-version:refname"], { encoding: "utf8" });+ for (const line of out.split("\n")) {+ const t = line.trim();+ if (STABLE_TAG_RE.test(t)) {+ return execFileSync("git", ["rev-parse", "--verify", `${t}^{commit}`], { encoding: "utf8" }).trim();+ }}+ return "";+}++function makeRealIsAlreadyShipped(latestStableSha) {+ return (betaTag) => {+ if (!latestStableSha) return false; // no stable yet -> nothing is shipped+ const betaSha = execFileSync("git", ["rev-parse", "--verify", `${betaTag}^{commit}`], {+ encoding: "utf8",+ }).trim();+ // Distinguish a clean "not an ancestor" (exit 1) from an infra failure (any+ // other non-zero), which must fail loud rather than read as "not shipped".+ const res = spawnSync("git", ["merge-base", "--is-ancestor", betaSha, latestStableSha], {+ encoding: "utf8",+ });+ if (res.status === 0) return true;+ if (res.status === 1) return false;+ throw new Error(+ `git merge-base --is-ancestor ${betaSha} ${latestStableSha} failed (exit ${res.status}): ${String(res.stderr || "").trim()}`,+ );+ };}// Distinguish a genuine 404 ("release not found") from any other gh failure.@@ -114,12 +141,13 @@ function main() {encoding: "utf8",});const betaTags = parseBetaTags(rawTags);+ const latestStableSha = resolveLatestStableSha();let result;try {result = selectPromotion({betaTags,- tagExists: realTagExists,+ isAlreadyShipped: makeRealIsAlreadyShipped(latestStableSha),fetchReleaseMeta: realFetchReleaseMeta,soakSeconds,nowMs: Date.now(),@@ -128,24 +156,20 @@ function main() {// Fail loud: an infra error means we cannot trust the decision. Exit// non-zero so the failure surfaces in the Actions UI and the next tick// retries once the issue clears — never a silent skip/no-op.- console.error(`::error::promote-stable-auto: ${err.message}`);+ console.error(`::error::select-beta-to-promote: ${err.message}`);process.exit(1);}let target = "";- let stable = "";if (result.kind === "select") {target = result.target;- stable = result.stableTag;- console.log(`::notice::Eligible: ${target} (unpromoted + fully cut + soaked >= ${soakSeconds}s) -> ${stable}`);- } else if (result.kind === "stop-promoted") {- console.log(`No-op: newest candidate ${result.beta} is already promoted to ${result.stableTag}.`);+ console.log(`::notice::Eligible: ${target} (unshipped + fully cut + soaked >= ${soakSeconds}s).`);} else {- console.log("No-op: no beta is currently eligible (need unpromoted + fully cut + soaked >= 24h).");+ console.log("No-op: no beta is currently eligible (need unshipped + fully cut + soaked >= 24h).");}if (process.env.GITHUB_OUTPUT) {- appendFileSync(process.env.GITHUB_OUTPUT, `target=${target}\nstable=${stable}\n`);+ appendFileSync(process.env.GITHUB_OUTPUT, `target=${target}\n`);}}diff --git a/.github/scripts/promote-stable-auto.test.mjs b/.github/scripts/select-beta-to-promote.test.mjssimilarity index 79%rename from .github/scripts/promote-stable-auto.test.mjsrename to .github/scripts/select-beta-to-promote.test.mjsindex 7ac1974d0..a35ab029b 100644--- a/.github/scripts/promote-stable-auto.test.mjs+++ b/.github/scripts/select-beta-to-promote.test.mjs@@ -1,5 +1,5 @@import { describe, expect, test } from "bun:test";-import { deriveStableTag, parseBetaTags, selectPromotion } from "./promote-stable-auto.mjs";+import { parseBetaTags, selectPromotion } from "./select-beta-to-promote.mjs";// Fixed clock so tests never call Date.now().const NOW = Date.parse("2026-07-08T20:00:00Z");@@ -24,28 +24,14 @@ function fetcher(map) {};}-const noneExist = () => false;-const existsIn = (...tags) => {+const shippedNone = () => false;+const shippedIn = (...tags) => {const set = new Set(tags);return (t) => set.has(t);};const select = (over) =>- selectPromotion({ tagExists: noneExist, soakSeconds: SOAK, nowMs: NOW, ...over });--describe("deriveStableTag", () => {- test("strips the -beta.N suffix", () => {- expect(deriveStableTag("v0.9.0-beta.1")).toBe("v0.9.0");- expect(deriveStableTag("v1.2.3-beta.0")).toBe("v1.2.3");- });- test("keeps double-digit beta numbers intact", () => {- expect(deriveStableTag("v0.10.0-beta.10")).toBe("v0.10.0");- });- test("throws on a non-beta tag", () => {- expect(() => deriveStableTag("v0.10.0")).toThrow();- expect(() => deriveStableTag("random")).toThrow();- });-});+ selectPromotion({ isAlreadyShipped: shippedNone, soakSeconds: SOAK, nowMs: NOW, ...over });describe("parseBetaTags", () => {test("filters to conforming beta tags, preserving order", () => {@@ -66,7 +52,7 @@ describe("selectPromotion", () => {"v0.10.0-beta.5": meta({ publishedAt: SOAKED }),}),});- expect(r).toEqual({ kind: "select", target: "v0.10.0-beta.5", stableTag: "v0.10.0" });+ expect(r).toEqual({ kind: "select", target: "v0.10.0-beta.5" });});test("selects the head when the head itself is soaked", () => {@@ -77,21 +63,33 @@ describe("selectPromotion", () => {"v0.10.0-beta.5": meta({ publishedAt: SOAKED }),}),});- expect(r).toEqual({ kind: "select", target: "v0.10.0-beta.6", stableTag: "v0.10.0" });+ expect(r).toEqual({ kind: "select", target: "v0.10.0-beta.6" });+ });++ test("selects the newest soaked UNSHIPPED beta, even across a version boundary", () => {+ // Catch-up shape: a fresh head, then several soaked betas spanning two X.Y.Z+ // lines, none shipped yet -> pick the newest soaked (promote-stable batches+ // the whole changeset delta over the latest stable into one bump).+ const r = select({+ betaTags: ["v0.31.0-beta.1", "v0.31.0-beta.0", "v0.30.1-beta.8"],+ fetchReleaseMeta: fetcher({+ "v0.31.0-beta.1": meta({ publishedAt: FRESH }),+ "v0.31.0-beta.0": meta({ publishedAt: SOAKED }),+ "v0.30.1-beta.8": meta({ publishedAt: SOAKED }),+ }),+ });+ expect(r).toEqual({ kind: "select", target: "v0.31.0-beta.0" });});- test("stops at the first already-promoted beta and never reaches an older cycle", () => {+ test("stops at the first already-shipped beta and never reaches an older cycle", () => {const r = select({betaTags: ["v0.10.0-beta.6", "v0.9.0-beta.3"],- tagExists: existsIn("v0.10.0"), // beta.6's stable already exists+ isAlreadyShipped: shippedIn("v0.10.0-beta.6"), // beta.6 is contained in the latest stablefetchReleaseMeta: fetcher({"v0.9.0-beta.3": meta({ publishedAt: SOAKED }), // soaked but must NOT be chosen}),});- expect(r.kind).toBe("stop-promoted");- expect(r.beta).toBe("v0.10.0-beta.6");- expect(r.stableTag).toBe("v0.10.0");- expect(r.target).toBeUndefined();+ expect(r).toEqual({ kind: "none" });});test("skips a draft head and promotes the older soaked beta", () => {@@ -102,7 +100,7 @@ describe("selectPromotion", () => {"v0.10.0-beta.5": meta({ publishedAt: SOAKED }),}),});- expect(r).toEqual({ kind: "select", target: "v0.10.0-beta.5", stableTag: "v0.10.0" });+ expect(r).toEqual({ kind: "select", target: "v0.10.0-beta.5" });});test("skips a head missing the DMG asset", () => {diff --git a/.github/workflows/promote-stable.yml b/.github/workflows/promote-stable.ymlindex e4dfadf57..9491f99f6 100644--- a/.github/workflows/promote-stable.yml+++ b/.github/workflows/promote-stable.yml@@ -153,11 +153,16 @@ jobs:fiecho "beta_tag=$RESOLVED" >> "$GITHUB_OUTPUT"- - name: Guard - auto-resolved beta is unpromoted + fully cut- # Only the auto path (Slack button / blank dispatch) needs these- # guards. The explicit beta_tag path is an operator override that- # keeps the workflow's idempotent recovery behavior (re-run to repair- # a partial promotion), so it bypasses this step.+ - name: Guard - auto-resolved beta is fully cut+ # Only the blank/auto dispatch path (promote-newest) needs this guard.+ # The explicit beta_tag path is an operator override that keeps the+ # workflow's idempotent recovery behavior (re-run to repair a partial+ # promotion), so it bypasses this step. The "already promoted" no-op is+ # no longer checked here — compute-stable-version.mjs derives the target+ # from the changeset delta over the latest stable and emits skip=true (a+ # clean no-op) when the beta is already shipped, so a stripped-name+ # stable-tag existence check would be both redundant and wrong (one beta+ # name no longer maps 1:1 to one stable version).if: steps.resolve.outputs.auto == 'true'env:GH_TOKEN: ${{ steps.app-token.outputs.token }}@@ -165,19 +170,6 @@ jobs:run: |set -euo pipefail- # Guard A — must not already be promoted to stable. After a- # promotion the newest beta tag still points at the just-promoted- # version until a fresh beta is cut. release.yml's "beta base must- # lead the latest stable" guard guarantees no new vX.Y.Z-beta.M is- # cut once vX.Y.Z exists, so a present stable tag means this beta is- # already released — re-promoting would re-publish an existing npm- # version (hard error) and re-upload onto the live stable Release.- STABLE_TAG="v$(printf '%s' "$BETA_TAG" | sed -E 's/^v//; s/-beta\.[0-9]+$//')"- if git rev-parse "refs/tags/${STABLE_TAG}" >/dev/null 2>&1; then- echo "::error::Newest beta ${BETA_TAG} is already promoted to stable ${STABLE_TAG}. Cut a new beta before promoting again — there is nothing newer to release."- exit 1- fi-# Guard B — the beta cut must be COMPLETE. release.yml creates the# beta Release as --draft; desktop-release.yml flips it to published# ONLY after the signed DMG + beta-mac.yml upload succeeds, and it@@ -199,7 +191,7 @@ jobs:echo "::error::Beta ${BETA_TAG} is not fully cut (draft=${isDraft}, dmg=${dmg}, mac.yml=${manifest}). Its desktop-release build is still running or failed — wait a few minutes and retry, or fix the failed cut before promoting."exit 1fi- echo "Beta ${BETA_TAG} is complete (published, ${dmg} dmg, ${manifest} mac.yml) and not yet promoted to ${STABLE_TAG}; safe to promote."+ echo "Beta ${BETA_TAG} is complete (published, ${dmg} dmg, ${manifest} mac.yml); safe to promote."- name: Verify beta tag existsenv:@@ -220,33 +212,19 @@ jobs:BETA_TAG: ${{ steps.resolve.outputs.beta_tag }}run: |set -euo pipefail- # Derive the version from the beta tag NAME, not from package.json- # at the tagged commit. release.yml's zero-commit-bump cadence- # applies the -beta.N version via a transient jq override that is- # never committed (its `Restore working tree` step reverts it), so- # the tagged commit's package.json still carries the placeholder- # version on main. The tag name is the only authoritative source- # of the cycle version.- if [[ ! "$BETA_TAG" =~ ^v([0-9]+\.[0-9]+\.[0-9]+)-beta\.[0-9]+$ ]]; then- echo "::error::Beta tag '$BETA_TAG' is not in the expected vX.Y.Z-beta.N format."- exit 1- fi-- BETA_VERSION="${BETA_TAG#v}"- STABLE_VERSION="${BASH_REMATCH[1]}"- STABLE_TAG="v${STABLE_VERSION}"- BETA_SHA=$(git rev-parse "refs/tags/${BETA_TAG}")-- {- echo "beta_version=$BETA_VERSION"- echo "stable_version=$STABLE_VERSION"- echo "stable_tag=$STABLE_TAG"- echo "beta_sha=$BETA_SHA"- } >> "$GITHUB_OUTPUT"-- echo "Promoting beta tag $BETA_TAG (SHA $BETA_SHA) to stable $STABLE_VERSION ($STABLE_TAG)"+ # Compute the stable version as a SINGLE semver bump over the current+ # latest stable, from the changeset delta between that stable's SHA and+ # this beta's SHA — NOT by stripping -beta.N. Stripping collapsed every+ # beta in a cycle to one stable, so a later beta could never promote and+ # a manual re-promote collided with the existing vX.Y.Z tag. This script+ # is the single source of version truth for manual + auto promotions; it+ # writes skip / stable_version / stable_tag / beta_sha / latest_stable_sha+ # to $GITHUB_OUTPUT. skip=true is a clean no-op (the beta is already+ # shipped, or adds no changesets) and gates every step below.+ node scripts/compute-stable-version.mjs "$BETA_TAG"- name: Tag stable at beta SHA+ if: steps.ver.outputs.skip != 'true'env:GH_TOKEN: ${{ steps.app-token.outputs.token }}STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}@@ -272,6 +250,7 @@ jobs:- name: Aggregate beta release bodies since previous stableid: changelog+ if: steps.ver.outputs.skip != 'true'env:GH_TOKEN: ${{ steps.app-token.outputs.token }}STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}@@ -297,12 +276,17 @@ jobs:| grep -v "^${STABLE_TAG}$" \| head -n 1 || true)+ # Betas whose changes are in this stable = beta tags reachable from the+ # promoted beta SHA but NOT from the previous stable. Under delta+ # versioning the promoted beta's NAME (e.g. v0.30.1-beta.6) no longer+ # matches the computed stable version (e.g. 0.30.2), so we range by+ # commit ancestry (--merged/--no-merged), not a name glob.if [[ -n "$PREV_STABLE" ]]; then- echo "Aggregating betas in range ${PREV_STABLE}..${STABLE_TAG}"- BETA_TAGS_IN_RANGE=$(git tag --list "v${STABLE_VERSION}-beta.*" --merged "$BETA_SHA" --sort=version:refname | grep -v "^${PREV_STABLE}$" || true)+ echo "Aggregating betas reachable from ${BETA_TAG_INPUT} but not ${PREV_STABLE}"+ BETA_TAGS_IN_RANGE=$(git tag --list 'v*-beta.*' --merged "$BETA_SHA" --no-merged "$PREV_STABLE" --sort=version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$' || true)else- echo "No previous stable tag; aggregating all betas at ${STABLE_VERSION}"- BETA_TAGS_IN_RANGE=$(git tag --list "v${STABLE_VERSION}-beta.*" --merged "$BETA_SHA" --sort=version:refname || true)+ echo "No previous stable tag; aggregating all betas reachable from ${BETA_TAG_INPUT}"+ BETA_TAGS_IN_RANGE=$(git tag --list 'v*-beta.*' --merged "$BETA_SHA" --sort=version:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+-beta\.[0-9]+$' || true)fi# Under the zero-commit-bump cadence, beta release bodies are@@ -364,6 +348,7 @@ jobs:echo "------------------------------"- name: Create stable GitHub Release+ if: steps.ver.outputs.skip != 'true'env:GH_TOKEN: ${{ steps.app-token.outputs.token }}STABLE_TAG: ${{ steps.ver.outputs.stable_tag }}@@ -398,6 +383,7 @@ jobs:fi- name: Trigger release.yml to publish stable to npm+ if: steps.ver.outputs.skip != 'true'# Same-repo repository_dispatch into release.yml. release.yml# listens for event_type=publish-stable, checks out the stable# tag, applies the transient package.json#version override, and@@ -432,6 +418,7 @@ jobs:echo "release.yml will run the npm publish + provenance attestation in its own job."- name: Trigger desktop-release.yml to build + upload stable DMG+ if: steps.ver.outputs.skip != 'true'# The `gh release create` above creates the release as `--draft`# so it stays out of the .atom feed until desktop-release.yml# uploads latest-mac.yml AND promotes draft → published. GitHub@@ -456,6 +443,7 @@ jobs:echo "Dispatched desktop-release for ${STABLE_TAG}; desktop-release.yml will build the signed DMG and upload it + latest-mac.yml to the stable Release."- name: Detect bridge App for cross-repo dispatch+ if: steps.ver.outputs.skip != 'true'# Auto-triggering main-reset.yml on agents-private needs a credential# with write access to THAT repo; the workflow-default GITHUB_TOKEN is# scoped to legacy only and cannot dispatch cross-repo. The "Inkeep OK@@ -498,9 +486,13 @@ jobs:env:GH_TOKEN: ${{ steps.bridge-token.outputs.token }}STABLE_VERSION: ${{ steps.ver.outputs.stable_version }}+ # JSON array of changeset IDs this stable consumed. main-reset consumes+ # ONLY these and leaves later changesets pending, so the anchor advances+ # exactly one stable per promotion without stranding newer work.+ DELTA_IDS: ${{ steps.ver.outputs.delta_ids }}run: |set -euo pipefail- payload=$(jq -nc --arg v "$STABLE_VERSION" \- '{event_type: "main-reset", client_payload: {stable_version: $v}}')+ payload=$(jq -nc --arg v "$STABLE_VERSION" --argjson d "${DELTA_IDS:-[]}" \+ '{event_type: "main-reset", client_payload: {stable_version: $v, delta_ids: $d}}')gh api -X POST "repos/inkeep/agents-private/dispatches" --input - <<<"$payload"- echo "Dispatched main-reset to agents-private (stable_version=${STABLE_VERSION})."+ echo "Dispatched main-reset to agents-private (stable_version=${STABLE_VERSION}, delta_ids=${DELTA_IDS})."diff --git a/.github/workflows/promote-stable-auto.yml b/.github/workflows/select-beta-to-promote.ymlsimilarity index 77%rename from .github/workflows/promote-stable-auto.ymlrename to .github/workflows/select-beta-to-promote.ymlindex f6c9f8cb1..3ac055045 100644--- a/.github/workflows/promote-stable-auto.yml+++ b/.github/workflows/select-beta-to-promote.yml@@ -1,29 +1,34 @@-name: Auto-promote stable+name: Select beta to promote-# Scheduled gatekeeper on inkeep/open-knowledge that AUTOMATICALLY promotes the-# LATEST beta that has soaked >= 24h online to stable, but only fires the-# promotion inside the US business-hours window (9am ET .. 4pm PT, Mon-Fri).+# Scheduled gatekeeper on inkeep/open-knowledge that SELECTS the most-recently+# soak-proven beta to promote to stable and dispatches promote-stable.yml with+# it, but only inside the US business-hours window (9am ET .. 4pm PT, Mon-Fri).+# It does SELECTION ONLY — it computes no version. promote-stable.yml owns+# version determination (scripts/compute-stable-version.mjs), so manual and auto+# promotions share one source of version truth.## "Latest soaked" (not simply "newest"): it walks the beta tags newest -> oldest-# in the established version order and promotes the first that is unpromoted,-# fully cut, and >= 24h online. A fresher beta cut < 24h ago is skipped in favor-# of the previous soaked beta; the skipped beta's changeset rolls forward into a-# later beta/stable via the cumulative changeset model, so nothing is lost. The-# descent stops at the first already-promoted beta, so it never reaches back-# across a promoted cycle boundary. This selection logic lives in-# .github/scripts/promote-stable-auto.mjs (unit-tested under `bun test --cwd+# in the established version order and selects the first that is unshipped, fully+# cut, and >= 24h online. A fresher beta cut < 24h ago is skipped in favor of the+# previous soaked beta; the skipped beta's changeset rolls forward — promote-+# stable batches the whole delta over the latest stable into one bump, so nothing+# is lost. The descent stops at the first already-shipped beta (its commit is+# contained in the latest stable), so it never reaches back across a shipped+# boundary. This selection logic lives in+# .github/scripts/select-beta-to-promote.mjs (unit-tested under `bun test --cwd# .github/scripts`), not inline bash — it is the sole safety gate for automated-# promotions (see NOTE below), so it is fail-loud and test-covered.+# selection (see NOTE below), so it is fail-loud and test-covered.## This workflow does NOT reimplement promotion. It dispatches promote-stable.yml-# with an EXPLICIT beta_tag (the selected beta); promote-stable tags vX.Y.Z,+# with an EXPLICIT beta_tag (the selected beta); promote-stable computes the+# stable version from the changeset delta over the latest stable, tags it,# creates the Release, and cascades npm --tag latest + signed stable DMG +# main-reset unchanged. "OK desktop to stable" is covered for free via the# promote-stable -> desktop-release cascade (latest-mac.yml + DMG). NOTE:-# promote-stable's Guard A/B run only on its blank/auto path, so the explicit-# dispatch bypasses them; the script performs the unpromoted + fully-cut checks-# itself, and fails loud (job error, retry next tick) on any non-404 gh/git-# error rather than folding an infra failure into a promote/no-op decision.+# promote-stable's fully-cut guard runs only on its blank/auto path, so the+# explicit dispatch bypasses it; this script performs the unshipped + fully-cut+# checks itself, and fails loud (job error, retry next tick) on any non-404+# gh/git error rather than folding an infra failure into a select/no-op decision.## Why a schedule is the backbone (not push alone): eligibility here is reached# by the passage of TIME (a beta crossing 24h old), not by a commit. During a@@ -51,8 +56,8 @@ name: Auto-promote stable# never blocks a real cut. Double-promotion is prevented three ways:# (1) cancel-in-progress supersedes an overlapping eval, (2) a fail-loud in-flight# check skips when a promote-stable run is already in_progress/queued, and-# (3) the script stops at the first already-promoted beta and never selects one-# whose stable tag already exists.+# (3) the script stops at the first already-shipped beta (commit contained in the+# latest stable) and never selects one whose changes are already released.on:schedule:@@ -150,18 +155,17 @@ jobs:env:GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}SOAK_SECONDS: "86400" # 24h online soak- # Writes target= / stable= to GITHUB_OUTPUT (empty target => no-op). Exits- # non-zero (fails the job) on any non-404 gh/git infra error — a fail-loud+ # Writes target= to GITHUB_OUTPUT (empty target => no-op). Exits non-zero+ # (fails the job) on any non-404 gh/git infra error — a fail-loud# retry-next-tick, never a silent skip. Logic + tests:- # .github/scripts/promote-stable-auto.{mjs,test.mjs}.- run: node .github/scripts/promote-stable-auto.mjs+ # .github/scripts/select-beta-to-promote.{mjs,test.mjs}.+ run: node .github/scripts/select-beta-to-promote.mjs- name: Guard against an in-flight promotion, then dispatchif: steps.hours.outputs.open == 'true' && steps.select.outputs.target != ''env:GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}TARGET: ${{ steps.select.outputs.target }}- TARGET_STABLE: ${{ steps.select.outputs.stable }}# workflow_dispatch supplies the boolean; schedule/push leave inputs# null, so default to "false" (never a dry run on the automated path).DRY_RUN: ${{ github.event.inputs.dry_run || 'false' }}@@ -169,7 +173,7 @@ jobs:set -euo pipefail# Don't double-fire while a promote-stable run is already active — covers# the window between dispatch and promote-stable pushing the stable tag- # (after which the script's stop-at-already-promoted catches it). Fail+ # (after which the script's stop-at-already-shipped catches it). Fail# loud on a query error: an evaluator that cannot confirm "no promotion# in flight" must abort and retry next tick, not assume zero (no# `|| echo 0`).@@ -180,12 +184,12 @@ jobs:exit 0fiif [[ "$DRY_RUN" == "true" ]]; then- echo "::notice::DRY RUN: would dispatch promote-stable.yml with beta_tag=${TARGET} -> ${TARGET_STABLE}."+ echo "::notice::DRY RUN: would dispatch promote-stable.yml with beta_tag=${TARGET} (promote-stable computes the stable version)."exit 0fi# Explicit beta_tag (not blank): a blank dispatch auto-resolves the NEWEST# beta, but under "latest soaked" the target may sit below the head.- # promote-stable's explicit-tag path skips its own Guard A/B, so the- # script's unpromoted + fully-cut checks are the safety net for this dispatch.+ # promote-stable's explicit-tag path skips its own fully-cut guard, so this+ # script's unshipped + fully-cut checks are the safety net for this dispatch.gh workflow run promote-stable.yml -f beta_tag="$TARGET"- echo "::notice::Dispatched promote-stable for ${TARGET} -> ${TARGET_STABLE} (npm --tag latest + stable DMG + main-reset)."+ echo "::notice::Dispatched promote-stable for ${TARGET} (it computes the stable version from the changeset delta, then npm --tag latest + stable DMG + main-reset)."diff --git a/knip.config.ts b/knip.config.tsindex c12f11e77..6686f6d7c 100644--- a/knip.config.ts+++ b/knip.config.ts@@ -44,6 +44,8 @@ export default {'biome-plugins/__fixtures__/**': ['files'],'scripts/compute-next-beta.mjs': ['files'],'scripts/compute-next-beta.test.mjs': ['files'],+ 'scripts/compute-stable-version.mjs': ['files'],+ 'scripts/compute-stable-version.test.mjs': ['files'],'scripts/check-license-fields.test.mjs': ['files'],'scripts/check-gate-catches-build-errors.test.mjs': ['files'],'scripts/bun-install-ci.test.mjs': ['files'],@@ -76,7 +78,7 @@ export default {'.github/scripts/cla-gate.test.mjs': ['files'],'.github/scripts/cla-gate.mjs': ['exports'],'.github/scripts/bridge-public-pr-to-monorepo.test.mjs': ['files'],- '.github/scripts/promote-stable-auto.test.mjs': ['files'],+ '.github/scripts/select-beta-to-promote.test.mjs': ['files'],'docs/src/lib/share-splash.ts': ['exports', 'types'],'packages/app/src/components/PublishToGitHubDialog.tsx': ['types'],'packages/app/src/components/ShareButton.tsx': ['types'],diff --git a/scripts/compute-stable-version.mjs b/scripts/compute-stable-version.mjsnew file mode 100644index 000000000..96eddd6f0--- /dev/null+++ b/scripts/compute-stable-version.mjs@@ -0,0 +1,218 @@+#!/usr/bin/env node+/**+ * Determine the STABLE version a beta promotes to, as a single semantic-version+ * bump over the current latest stable — NOT by stripping `-beta.N` from the tag.+ *+ * Why. The old promote path derived the stable version from the tag NAME+ * (`v0.30.1-beta.6` -> `v0.30.1`). That collapses every beta in a cycle to one+ * stable, so only the first beta could ever ship; later betas' work was stranded+ * or swept into the next computed version, and a manual re-promote of a newer+ * beta collided with the already-existing `vX.Y.Z` tag. Instead, the stable+ * version is `bump(latestStableVersion, maxBumpType(<changeset delta>))`, where+ * the delta is the changesets present at the beta's commit but not yet consumed+ * by the latest stable. A patch-only delta bumps the patch (`0.30.1 -> 0.30.2`);+ * a minor changeset in the delta bumps the minor (`-> 0.31.0`). This is the+ * single source of version truth for BOTH manual and auto promotions.+ *+ * The latest stable tag points at the beta SHA it was cut from, so the set of+ * `.changeset/*.md` at that SHA is exactly what that stable shipped; the delta+ * is a plain set difference against the promoted beta's SHA.+ *+ * Usage: node scripts/compute-stable-version.mjs <vX.Y.Z-beta.N>+ * Emits JSON to stdout and, under Actions, appends+ * skip / stable_version / stable_tag / beta_sha / latest_stable_sha+ * to $GITHUB_OUTPUT. Logs go to stderr. Fail-loud: any git failure other than a+ * clean `merge-base --is-ancestor` false exits non-zero (retry next tick) rather+ * than folding an infra error into a promote/no-op decision.+ *+ * The pure core (`computeStablePromotion`) takes its git boundary as an injected+ * dependency so tests need no live repo (mirrors promote-stable-auto.mjs).+ */+import { spawnSync } from 'node:child_process';+import { appendFileSync } from 'node:fs';+import { pathToFileURL } from 'node:url';+import { bumpSemver, maxBumpType, parseFrontmatterBumpType } from './compute-next-beta.mjs';++const BETA_TAG_RE = /^v\d+\.\d+\.\d+-beta\.\d+$/;+const STABLE_TAG_RE = /^v\d+\.\d+\.\d+$/;++function log(...args) {+ process.stderr.write(`${args.join(' ')}\n`);+}++function stripBetaToVersion(betaTag) {+ const m = /^v(\d+\.\d+\.\d+)-beta\.\d+$/.exec(betaTag);+ if (!m) throw new Error(`not a vX.Y.Z-beta.N tag: ${betaTag}`);+ return m[1];+}++/**+ * Pure decision core. `git` is an injected boundary so tests need no repo:+ * revParse(ref) -> commit SHA (string)+ * newestStableTag() -> "vX.Y.Z" | "" (highest plain vX.Y.Z tag)+ * changesetIds(sha) -> string[] (basename-without-.md of .changeset/*.md at sha)+ * isAncestor(a, b) -> boolean (a is ancestor-or-equal of b)+ * bumpTypeOf(sha, id) -> 'patch'|'minor'|'major'|null+ *+ * Returns one of:+ * { skip:false, stableVersion, stableTag, bump, deltaCount, betaSha, latestStableSha }+ * { skip:false, bootstrap:true, stableVersion, stableTag, betaSha, latestStableSha:"" }+ * { skip:true, reason, betaSha, latestStableSha }+ */+export function computeStablePromotion(betaTag, git) {+ if (!BETA_TAG_RE.test(betaTag)) {+ throw new Error(`Beta tag '${betaTag}' is not in the expected vX.Y.Z-beta.N format.`);+ }+ const betaSha = git.revParse(betaTag);++ const latestStableTag = git.newestStableTag();+ if (!latestStableTag) {+ // Bootstrap: no prior stable — the first stable is the beta's own X.Y.Z+ // (the cycle target compute-next-beta already resolved from the anchor).+ const stableVersion = stripBetaToVersion(betaTag);+ return {+ skip: false,+ bootstrap: true,+ stableVersion,+ stableTag: `v${stableVersion}`,+ bump: null,+ deltaCount: null,+ betaSha,+ latestStableSha: '',+ };+ }+ if (!STABLE_TAG_RE.test(latestStableTag)) {+ throw new Error(`newestStableTag returned a non-stable tag: ${latestStableTag}`);+ }+ const latestStableVersion = latestStableTag.slice(1);+ const latestStableSha = git.revParse(latestStableTag);++ // Already shipped: the beta's commit is the latest stable's commit or an+ // ancestor of it. Nothing newer to promote — clean no-op (this replaces the+ // old "does vX.Y.Z tag exist" boundary, which no longer maps 1:1 to a beta).+ if (git.isAncestor(betaSha, latestStableSha)) {+ return {+ skip: true,+ reason: `${betaTag} (${betaSha.slice(0, 12)}) is already shipped in stable ${latestStableTag}.`,+ betaSha,+ latestStableSha,+ };+ }++ const stableIds = new Set(git.changesetIds(latestStableSha));+ const deltaIds = git.changesetIds(betaSha).filter((id) => !stableIds.has(id));+ if (deltaIds.length === 0) {+ return {+ skip: true,+ reason: `${betaTag} introduces no changesets beyond ${latestStableTag}; nothing to promote.`,+ betaSha,+ latestStableSha,+ };+ }++ const bump = maxBumpType(deltaIds.map((id) => git.bumpTypeOf(betaSha, id)));+ const stableVersion = bumpSemver(latestStableVersion, bump);+ return {+ skip: false,+ stableVersion,+ stableTag: `v${stableVersion}`,+ bump,+ // The exact changeset IDs this stable consumes. main-reset (on+ // agents-private, which has no OK release tags) can't recompute the delta+ // itself, so promote-stable forwards this list in the main-reset dispatch so+ // that reset consolidates ONLY these changesets and leaves later ones pending.+ deltaIds,+ deltaCount: deltaIds.length,+ betaSha,+ latestStableSha,+ };+}++// --- workflow-runtime wiring (real git boundary) ---++function runGit(args) {+ const res = spawnSync('git', args, { encoding: 'utf8' });+ if (res.status !== 0) {+ throw new Error(`git ${args.join(' ')} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`);+ }+ return String(res.stdout || '');+}++const realGit = {+ revParse: (ref) => runGit(['rev-parse', '--verify', `${ref}^{commit}`]).trim(),+ newestStableTag: () => {+ for (const line of runGit(['tag', '--list', 'v*', '--sort=-version:refname']).split('\n')) {+ const t = line.trim();+ if (STABLE_TAG_RE.test(t)) return t;+ }+ return '';+ },+ changesetIds: (sha) => {+ const ids = [];+ for (const line of runGit(['ls-tree', '-r', '--name-only', sha, '--', '.changeset']).split('\n')) {+ const m = /^\.changeset\/(.+)\.md$/.exec(line.trim());+ if (m && m[1] !== 'README') ids.push(m[1]);+ }+ return ids;+ },+ isAncestor: (a, b) => {+ // Distinguish a clean "not an ancestor" (exit 1) from an infra failure+ // (any other non-zero) — the latter must fail loud, not read as "false".+ const res = spawnSync('git', ['merge-base', '--is-ancestor', a, b], { encoding: 'utf8' });+ if (res.status === 0) return true;+ if (res.status === 1) return false;+ throw new Error(+ `git merge-base --is-ancestor ${a} ${b} failed (exit ${res.status}): ${String(res.stderr || '').trim()}`,+ );+ },+ bumpTypeOf: (sha, id) => parseFrontmatterBumpType(runGit(['show', `${sha}:.changeset/${id}.md`])),+};++function main() {+ const betaTag = process.argv[2];+ if (!betaTag) {+ log('::error::compute-stable-version: missing beta tag argument (usage: compute-stable-version.mjs <vX.Y.Z-beta.N>).');+ process.exit(1);+ }++ let result;+ try {+ result = computeStablePromotion(betaTag, realGit);+ } catch (err) {+ // Fail loud: an infra/format error means we cannot trust the decision.+ console.error(`::error::compute-stable-version: ${err.message}`);+ process.exit(1);+ }++ if (result.skip) {+ log(`No-op: ${result.reason}`);+ } else if (result.bootstrap) {+ log(`Promote ${betaTag} -> ${result.stableTag} (bootstrap: first stable, no prior stable tag).`);+ } else {+ log(+ `Promote ${betaTag} -> ${result.stableTag} (${result.bump} bump over v${result.latestStableSha.slice(0, 12)}; ${result.deltaCount} changeset delta).`,+ );+ }++ console.log(JSON.stringify(result));++ if (process.env.GITHUB_OUTPUT) {+ const lines = [+ `skip=${result.skip ? 'true' : 'false'}`,+ `stable_version=${result.stableVersion ?? ''}`,+ `stable_tag=${result.stableTag ?? ''}`,+ `beta_sha=${result.betaSha ?? ''}`,+ `latest_stable_sha=${result.latestStableSha ?? ''}`,+ // JSON array of changeset IDs consumed by this stable (empty for skip /+ // bootstrap). promote-stable forwards it to main-reset for incremental+ // consolidation.+ `delta_ids=${JSON.stringify(result.deltaIds ?? [])}`,+ ];+ appendFileSync(process.env.GITHUB_OUTPUT, `${lines.join('\n')}\n`);+ }+}++// Run main() only as a CLI, not when imported by the test file.+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {+ main();+}diff --git a/scripts/compute-stable-version.test.mjs b/scripts/compute-stable-version.test.mjsnew file mode 100644index 000000000..ab89afada--- /dev/null+++ b/scripts/compute-stable-version.test.mjs@@ -0,0 +1,111 @@+import { describe, expect, test } from 'bun:test';+import { computeStablePromotion } from './compute-stable-version.mjs';++// Injected git boundary so tests need no repo. Defaults: unknown changeset bump+// types resolve to 'patch' (the patch floor), isAncestor false.+function fakeGit({ shas = {}, newestStable = '', changesets = {}, ancestor = () => false, bumps = {} } = {}) {+ return {+ revParse: (ref) => {+ if (!(ref in shas)) throw new Error(`fakeGit: no sha for ${ref}`);+ return shas[ref];+ },+ newestStableTag: () => newestStable,+ changesetIds: (sha) => changesets[sha] ?? [],+ isAncestor: (a, b) => ancestor(a, b),+ bumpTypeOf: (_sha, id) => (id in bumps ? bumps[id] : 'patch'),+ };+}++describe('computeStablePromotion', () => {+ test('single patch changeset over the latest stable -> next patch (the beta.1 -> 0.30.2 case)', () => {+ const git = fakeGit({+ shas: { 'v0.30.1-beta.1': 'B1', 'v0.30.1': 'S1' },+ newestStable: 'v0.30.1',+ changesets: { S1: ['c0'], B1: ['c0', 'c1'] },+ });+ const r = computeStablePromotion('v0.30.1-beta.1', git);+ expect(r).toMatchObject({+ skip: false,+ stableVersion: '0.30.2',+ stableTag: 'v0.30.2',+ bump: 'patch',+ deltaCount: 1,+ deltaIds: ['c1'],+ });+ });++ test('cumulative patch pile promotes as a SINGLE patch bump (beta.6 -> 0.30.2, not 0.30.7)', () => {+ const git = fakeGit({+ shas: { 'v0.30.1-beta.6': 'B6', 'v0.30.1': 'S1' },+ newestStable: 'v0.30.1',+ changesets: { S1: ['c0'], B6: ['c0', 'c1', 'c2', 'c3', 'c4', 'c5', 'c6'] },+ });+ const r = computeStablePromotion('v0.30.1-beta.6', git);+ expect(r).toMatchObject({ skip: false, stableVersion: '0.30.2', bump: 'patch', deltaCount: 6 });+ });++ test('a minor changeset in the delta bumps the minor and resets patch to 0', () => {+ const git = fakeGit({+ shas: { 'v0.31.0-beta.0': 'M0', 'v0.30.1': 'S1' },+ newestStable: 'v0.30.1',+ changesets: { S1: ['c0'], M0: ['c0', 'c1', 'm1'] },+ bumps: { c1: 'patch', m1: 'minor' },+ });+ const r = computeStablePromotion('v0.31.0-beta.0', git);+ expect(r).toMatchObject({ skip: false, stableVersion: '0.31.0', bump: 'minor', deltaCount: 2 });+ });++ test('a major changeset in the delta bumps the major', () => {+ const git = fakeGit({+ shas: { 'v1.0.0-beta.0': 'MJ', 'v0.30.1': 'S1' },+ newestStable: 'v0.30.1',+ changesets: { S1: ['c0'], MJ: ['c0', 'x'] },+ bumps: { x: 'major' },+ });+ const r = computeStablePromotion('v1.0.0-beta.0', git);+ expect(r.stableVersion).toBe('1.0.0');+ expect(r.bump).toBe('major');+ });++ test('a beta already shipped in the latest stable (ancestor) is a clean no-op', () => {+ const git = fakeGit({+ shas: { 'v0.30.1-beta.0': 'S1', 'v0.30.1': 'S1' },+ newestStable: 'v0.30.1',+ ancestor: (a, b) => a === 'S1' && b === 'S1',+ });+ const r = computeStablePromotion('v0.30.1-beta.0', git);+ expect(r.skip).toBe(true);+ expect(r.reason).toMatch(/already shipped/);+ });++ test('a beta introducing no new changesets beyond the latest stable is a no-op', () => {+ const git = fakeGit({+ shas: { 'v0.30.1-beta.9': 'B9', 'v0.30.1': 'S1' },+ newestStable: 'v0.30.1',+ changesets: { S1: ['c0', 'c1'], B9: ['c0', 'c1'] },+ });+ const r = computeStablePromotion('v0.30.1-beta.9', git);+ expect(r.skip).toBe(true);+ expect(r.reason).toMatch(/no changesets beyond/);+ });++ test('bootstrap: with no prior stable, the first stable is the beta own X.Y.Z', () => {+ const git = fakeGit({ shas: { 'v0.1.0-beta.3': 'B' }, newestStable: '' });+ const r = computeStablePromotion('v0.1.0-beta.3', git);+ expect(r).toMatchObject({ skip: false, bootstrap: true, stableVersion: '0.1.0', stableTag: 'v0.1.0' });+ });++ test('double-digit patch/beta components bump correctly', () => {+ const git = fakeGit({+ shas: { 'v0.30.10-beta.12': 'B', 'v0.30.10': 'S' },+ newestStable: 'v0.30.10',+ changesets: { S: ['c0'], B: ['c0', 'c1'] },+ });+ expect(computeStablePromotion('v0.30.10-beta.12', git).stableVersion).toBe('0.30.11');+ });++ test('rejects a non-beta tag', () => {+ expect(() => computeStablePromotion('v0.30.1', fakeGit())).toThrow(/vX\.Y\.Z-beta\.N/);+ expect(() => computeStablePromotion('garbage', fakeGit())).toThrow();+ });+});