Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
Retire the Open Knowledge main reset (PRD-9389) (#6540)
Andrew Mikofalvy3e5832d507f7
diff --git a/.changeset/README.md b/.changeset/README.mdindex ad0bd338a..6265d885f 100644--- a/.changeset/README.md+++ b/.changeset/README.md@@ -36,4 +36,4 @@ When `1.0.0` does eventually ship, this convention will be retired and standard> Authoring tip: run `pnpm changeset` from anywhere under `public/open-knowledge/` — the CLI walks up to find this folder. Don't hand-create files; the tool's interactive flow asks for bump types in order and writes a well-formed frontmatter block. Per the convention above, only pick `minor` or `patch`.-> SKILL.md metadata is synced automatically by the VP workflow via [`scripts/sync-skill-version.sh`](../scripts/sync-skill-version.sh). You don't need to bump the bundled SKILL.md files' `metadata.version:` by hand — `pnpm exec changeset version` (in CI) bumps the package.json files, then the sync script propagates the new version into SKILL.md. The same script can be run manually from `public/open-knowledge/` if you ever need to re-sync after a hand edit.+> Nothing on `main` carries a release version: the packages commit `0.0.0-unknown`, and each release stamps its version from the tag at build time. A changeset is deleted from `main` by the daily cleanup once a published stable carries it.diff --git a/.changeset/pre.json b/.changeset/pre.jsondeleted file mode 100644index 7c5ca6838..000000000--- a/.changeset/pre.json+++ /dev/null@@ -1,17 +0,0 @@-{- "mode": "pre",- "tag": "beta",- "initialVersions": {- "@inkeep/open-knowledge-docs": "0.0.272",- "@inkeep/open-knowledge-app": "0.86.18",- "@inkeep/open-knowledge": "0.86.18",- "@inkeep/open-knowledge-core": "0.86.18",- "@inkeep/open-knowledge-desktop": "0.86.18",- "@inkeep/md-conformance": "0.0.280",- "@inkeep/open-knowledge-md-audit": "0.0.0",- "@inkeep/open-knowledge-native-config": "0.0.0",- "@inkeep/open-knowledge-plugin": "0.3.1",- "@inkeep/open-knowledge-server": "0.86.18"- },- "changesets": []-}diff --git a/.github/scripts/point-release-plan.mjs b/.github/scripts/point-release-plan.mjsindex 9b06e7888..b57159096 100644--- a/.github/scripts/point-release-plan.mjs+++ b/.github/scripts/point-release-plan.mjs@@ -50,10 +50,6 @@ export function parseFixRefs(raw) {return refs;}-export function parseDeltaIds(raw) {- return splitList(raw);-}-function splitList(raw) {const items = [];for (const piece of String(raw ?? '').split(/[\s,[\]"']+/)) {@@ -402,20 +398,6 @@ export function guardNativeConfigProvenance({ selection }) {);}-export function guardMainResetDeltaIds({ deltaIds }) {- if (!Array.isArray(deltaIds) || deltaIds.length === 0) {- return refuse(- 'empty-delta-ids',- 'Refusing to dispatch main-reset without an explicit changeset delta: it treats an empty or absent ' +- 'delta as consolidate-the-whole-pending-pile, which would consume every unsoaked changeset. ' +- 'Supply the delta, or skip the dispatch entirely.',- );- }- return pass(`main-reset would consolidate exactly ${deltaIds.length} changeset(s).`);-}--const MAIN_RESET_REPO = 'inkeep/agents-private';-export const APP_CREDENTIAL_HELPER ='!f() { test "$1" = get || return 0; echo username=x-access-token; echo "password=$GH_TOKEN"; }; f';@@ -472,12 +454,10 @@ export function runPointRelease(opts, io) {const {mode,fixRefs,- anchorDeltaIds,resolvePaths = [],dryRun = true,dispatchedBy = '',selfRepo = '',- bridgeConfigured = true,} = opts;if (mode !== 'cherry-pick' && mode !== 'revert') {@@ -548,8 +528,6 @@ export function runPointRelease(opts, io) {if (mode === 'revert') warnings.push(revertFollowUpWarning(version.removedIds));- const mainReset = decideMainReset({ anchorDeltaIds, addedIds: version.addedIds, bridgeConfigured, guards, warnings });-const changesetEntries = version.addedIds.map((id) => {let body = null;try {@@ -581,7 +559,6 @@ export function runPointRelease(opts, io) {addedIds: version.addedIds,removedIds: version.removedIds,changesetEntries,- mainReset,guards,warnings,};@@ -607,13 +584,6 @@ export function runPointRelease(opts, io) {eventType: 'desktop-release',clientPayload: { release_tag: plan.tag, ref: plan.tag, dispatched_by: dispatchedBy },});- if (mainReset.dispatch) {- io.gh.dispatch({- repo: MAIN_RESET_REPO,- eventType: 'main-reset',- clientPayload: { stable_version: plan.version, delta_ids: mainReset.deltaIds, dispatched_by: dispatchedBy },- });- }} catch (err) {const marked = err instanceof Error ? err : new Error(String(err));marked.pushedTag = plan.tag;@@ -707,7 +677,7 @@ function revertFollowUpWarning(removedIds) {if (removedIds.length > 0) {return (`This revert deletes ${removedIds.map((id) => `.changeset/${id}.md`).join(', ')}. ` +- 'If main-reset has already consumed these files on main, an ordinary code-only revert there cannot ' ++ 'If the daily changeset cleanup has already deleted these files from main, an ordinary code-only revert there cannot ' +'reproduce the shipped patch. The shipped-fix check will refuse that later main promotion even when ' +'the rollback code is correct; putting its changeset in a separate PR does not resolve this mismatch. ' +'Unless the revert cannot wait for main, land it on main and ship it in cherry-pick mode instead, ' +@@ -721,35 +691,6 @@ function revertFollowUpWarning(removedIds) {);}-function decideMainReset({ anchorDeltaIds, addedIds, bridgeConfigured, guards, warnings }) {- const named = String(anchorDeltaIds ?? '').trim() !== '';- const deltaIds = named ? parseDeltaIds(anchorDeltaIds) : addedIds;-- if (!named && deltaIds.length === 0) {- warnings.push(- 'Skipping the main-reset dispatch: this release forwards no changeset delta, and dispatching an ' +- 'empty one would consolidate the entire pending pile. Two follow-ups are now yours: land the fix ' +- '(for a revert, the revert itself) on main so the pile stops carrying it, and run main-reset with ' +- 'that changeset so the anchor advances past this stable. Until the anchor advances, every later ' +- 'automatic main-reset fails its version guard; beta and stable versions come from the stable tags ' +- 'and are unaffected.',- );- return { dispatch: false, deltaIds: null, skipReason: 'no-delta-to-forward' };- }-- checkGuard(guards, guardMainResetDeltaIds({ deltaIds }));-- if (!bridgeConfigured) {- warnings.push(- 'Skipping the main-reset dispatch: the cross-repo bridge App is not configured on this repo. Run ' +- `main-reset manually with delta_ids ${JSON.stringify(deltaIds)} so the anchor advances past this stable.`,- );- return { dispatch: false, deltaIds, skipReason: 'bridge-not-configured' };- }-- return { dispatch: true, deltaIds, skipReason: null };-}-function provenanceLines(plan) {return [`Point release over ${plan.latestStableTag}: the current stable plus ${plan.fixRefs.length} applied ` +@@ -773,7 +714,7 @@ function renderedReleaseNotes(plan, io, warnings) {} catch (err) {warnings.push(`The release notes could not be rendered from the changesets (${messageOf(err)}), so the body quotes ` +- `them instead and carries no notes-source marker; the docs changelog keeps CHANGELOG.md for ${plan.tag}.`,+ `them instead and carries no notes-source marker; the docs changelog lists no entry for ${plan.tag} until the body carries one.`,);return formatReleaseNotes(plan);}@@ -866,10 +807,6 @@ export function realIo() {const res = spawnSync('gh', ['api', '-X', 'POST', `repos/${repo}/dispatches`, '--input', '-'], {encoding: 'utf8',input: JSON.stringify({ event_type: eventType, client_payload: clientPayload }),- env:- repo === MAIN_RESET_REPO && process.env.BRIDGE_GH_TOKEN- ? { ...process.env, GH_TOKEN: process.env.BRIDGE_GH_TOKEN }- : process.env,});if (res.status !== 0) {throw new Error(@@ -937,12 +874,10 @@ function main() {{mode: process.env.MODE,fixRefs: parseFixRefs(process.env.FIX_REFS),- anchorDeltaIds: process.env.ANCHOR_DELTA_IDS,resolvePaths: parseResolvePaths(process.env.RESOLVE_PATHS),dryRun,dispatchedBy: process.env.DISPATCHED_BY || '',selfRepo: process.env.GITHUB_REPOSITORY || '',- bridgeConfigured: process.env.BRIDGE_CONFIGURED === 'true',},io,);@@ -985,8 +920,7 @@ function main() {`latest_stable_tag=${plan.latestStableTag}`,`synthetic_sha=${plan.syntheticSha}`,`resolved_paths=${JSON.stringify(plan.resolvedPaths.map((r) => r.path))}`,- `delta_ids=${JSON.stringify(plan.mainReset.deltaIds ?? [])}`,- `main_reset_dispatched=${plan.mainReset.dispatch ? 'true' : 'false'}`,+ `added_ids=${JSON.stringify(plan.addedIds)}`,'',].join('\n'),);diff --git a/.github/scripts/point-release-plan.test.mjs b/.github/scripts/point-release-plan.test.mjsindex 1d0383238..b774bac91 100644--- a/.github/scripts/point-release-plan.test.mjs+++ b/.github/scripts/point-release-plan.test.mjs@@ -16,7 +16,6 @@ import {formatReleaseNotes,guardBasePublished,guardDeltaMatchesFix,- guardMainResetDeltaIds,guardNativeConfigProvenance,guardPatchOnly,guardRefsOnMain,@@ -260,28 +259,6 @@ describe('guardNativeConfigProvenance', () => {});});-describe('guardMainResetDeltaIds', () => {- test('passes on a non-empty delta', () => {- expect(guardMainResetDeltaIds({ deltaIds: ['brave-pandas-sing'] })).toMatchObject({- ok: true,- code: null,- });- });-- test('refuses an empty array, which main-reset reads as consolidate-everything', () => {- const r = guardMainResetDeltaIds({ deltaIds: [] });- expect(r.ok).toBe(false);- expect(r.code).toBe('empty-delta-ids');- });-- test('refuses an absent delta for the same reason', () => {- expect(guardMainResetDeltaIds({ deltaIds: null })).toMatchObject({- ok: false,- code: 'empty-delta-ids',- });- });-});-const WS_STABLE = `packages:- 'packages/*'@@ -574,7 +551,6 @@ describe('guard codes', () => {guardDeltaMatchesFix({ mode: 'revert', addedIds: ['x'], fixChangesetIds: [] }),guardPatchOnly({ bump: 'major' }),guardNativeConfigProvenance({ selection: { headSha: '', reason: 'nothing qualified' } }),- guardMainResetDeltaIds({ deltaIds: [] }),guardBasePublished({ latestStableTag: 'v0.32.1', publishedTags: ['v0.32.0'] }),guardShipsPublishedFixes({ verdict: droppedFixVerdict(), latestStableTag: 'v0.32.0' }),];@@ -823,15 +799,6 @@ describe('runPointRelease cascade', () => {eventType: 'desktop-release',clientPayload: { release_tag: 'v0.32.1', ref: 'v0.32.1', dispatched_by: 'https://run/1' },},- {- repo: 'inkeep/agents-private',- eventType: 'main-reset',- clientPayload: {- stable_version: '0.32.1',- delta_ids: ['shiny-fix'],- dispatched_by: 'https://run/1',- },- },]);});@@ -973,7 +940,7 @@ describe('runPointRelease cascade', () => {expect(plan.releaseNotes).toContain(NOTES_SOURCE_MARKER);});- test('a revert body carries no notes-source marker, so the docs keep CHANGELOG.md for it', () => {+ test('a revert body carries no notes-source marker', () => {const io = makeIo();runPointRelease({ mode: 'revert', fixRefs: ['bad1'], dryRun: false }, io);expect(io.releases[0].notes).not.toContain('ok-notes-source');@@ -998,25 +965,11 @@ describe('runPointRelease cascade', () => {);});- test('revert with no named delta skips main-reset and names both follow-ups', () => {+ test('a revert dispatches only desktop-release and writes nothing to agents-private', () => {const io = makeIo();const plan = runPointRelease({ mode: 'revert', fixRefs: ['bad1'], dryRun: false }, io);- expect(plan.mainReset).toMatchObject({ dispatch: false, skipReason: 'no-delta-to-forward' });- expect(io.dispatches.map((d) => d.eventType)).toEqual(['desktop-release']);- expect(io.dispatches.every((d) => d.clientPayload.delta_ids === undefined)).toBe(true);- const warning = plan.warnings.join(' ');- expect(warning).toMatch(/on main/i);- expect(warning).toMatch(/anchor advances/i);- });-- test('revert forwards the changeset the operator landed to represent it', () => {- const io = makeIo();- runPointRelease(- { mode: 'revert', fixRefs: ['bad1'], anchorDeltaIds: '["undo-bad"]', dryRun: false },- io,- );- const mainReset = io.dispatches.find((d) => d.eventType === 'main-reset');- expect(mainReset.clientPayload.delta_ids).toEqual(['undo-bad']);+ expect(io.dispatches.map((d) => [d.repo, d.eventType])).toEqual([['', 'desktop-release']]);+ expect(plan).not.toHaveProperty('mainReset');});test('revert mode warns that main must carry the same patch before the next promotion', () => {@@ -1035,7 +988,7 @@ describe('runPointRelease cascade', () => {expect(plan.removedIds).toEqual(['bad-change']);const warning = plan.warnings.join(' ');expect(warning).toContain('This revert deletes .changeset/bad-change.md');- expect(warning).toContain('If main-reset has already consumed these files on main');+ expect(warning).toContain('If the daily changeset cleanup has already deleted these files from main');expect(warning).toContain('an ordinary code-only revert there cannot reproduce the shipped patch');expect(warning).toContain('putting its changeset in a separate PR does not resolve this mismatch');expect(warning).toContain('ship it in cherry-pick mode instead');@@ -1050,32 +1003,6 @@ describe('runPointRelease cascade', () => {expect(plan.warnings.join(' ')).not.toContain('shipped-fix check will refuse');});- test('refuses when the operator names a delta that parses to nothing', () => {- const io = makeIo();- let refusal;- try {- runPointRelease(- { mode: 'revert', fixRefs: ['bad1'], anchorDeltaIds: '[]', dryRun: false },- io,- );- } catch (err) {- refusal = err;- }- expect(refusal?.code).toBe('empty-delta-ids');- expect(io.calls).toEqual({ tag: 0, pushTag: 0, createRelease: 0, dispatch: 0 });- });-- test('skips main-reset when the cross-repo bridge App is absent, without failing the run', () => {- const io = cherryPickIo();- const plan = runPointRelease(- { mode: 'cherry-pick', fixRefs: ['fix1'], dryRun: false, bridgeConfigured: false },- io,- );- expect(plan.mainReset).toMatchObject({ dispatch: false, skipReason: 'bridge-not-configured' });- expect(io.dispatches.map((d) => d.eventType)).toEqual(['desktop-release']);- expect(plan.warnings.join(' ')).toContain('shiny-fix');- });-test('a cascade failure after the tag is pushed marks the error with the pushed tag', () => {const io = cherryPickIo();io.gh.createRelease = () => {diff --git a/.github/scripts/release-cascade-shape.test.mjs b/.github/scripts/release-cascade-shape.test.mjsindex 64f9a5b71..e153f5098 100644--- a/.github/scripts/release-cascade-shape.test.mjs+++ b/.github/scripts/release-cascade-shape.test.mjs@@ -1858,7 +1858,7 @@ describe('the release App credential never shares a job with installed packages'for (const run of ['node scripts/compute-stable-version.mjs "$BETA_TAG"','echo "dispatches publish-stable to release.yml for npm. npm latest does NOT move"',- '# pnpm exec changeset version runs in main-reset',+ '# pnpm exec changeset version runs in compute-next-beta',' # if ! timeout 300 pnpm install; then exit 1; fi','# x; pnpm install',' # x; pnpm install',diff --git a/.github/scripts/share-contract-cache-shape.test.mjs b/.github/scripts/share-contract-cache-shape.test.mjsindex ec2642723..9694deaab 100644--- a/.github/scripts/share-contract-cache-shape.test.mjs+++ b/.github/scripts/share-contract-cache-shape.test.mjs@@ -14,7 +14,7 @@ describe('share contract corpus cache wiring', () => {expect(turbo.globalDependencies.filter((entry) => entry === corpusPath)).toHaveLength(1);});- test('the static docs manifest deployment identity invalidates the docs build cache', () => {+ test('the static docs manifest deployment identity, and each Vercel deployment, invalidates the docs build cache', () => {const turbo = JSON.parse(readFileSync(join(REPO_ROOT, 'turbo.json'), 'utf8'));const docsBuild = turbo.tasks['@inkeep/open-knowledge-docs#build'];@@ -23,8 +23,10 @@ describe('share contract corpus cache wiring', () => {'GITHUB_SHA','VERCEL_ENV','OK_ALLOW_BLOGLESS_LLMS_TXT',+ 'OK_ALLOW_PARTIAL_CHANGELOG','CI','VERCEL',+ 'VERCEL_DEPLOYMENT_ID',]);});});diff --git a/.github/workflows/bug-lane.yml b/.github/workflows/bug-lane.ymlindex af0a0cda1..3162ee0dd 100644--- a/.github/workflows/bug-lane.yml+++ b/.github/workflows/bug-lane.yml@@ -34,7 +34,7 @@ name: Bug lane# patch-only bump, anchor, provenance) and its cascade smokes the signed# DMG before the release publishes or npm moves.# 4. Re-release is structurally impossible: candidates come from the pending-# pile (main-reset consumes a released fix's changeset), commits already+# pile (a changeset a published stable carries is not pending), commits already# in the stable are pre-filtered, and an empty pick is refused. Every# stable this lane cuts carries novel changesets.#diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.ymlindex 03918f990..5bd6f5bb2 100644--- a/.github/workflows/desktop-release.yml+++ b/.github/workflows/desktop-release.yml@@ -168,11 +168,10 @@ jobs:# release commits a version (release.yml's header describes the# transient override for each path), so the tag is the only source# of truth for the release's version — the public repo's commits at- # the tagged SHA carry the version the last main reset wrote- # (normally the previous stable), never the tag's and never a- # `-beta.N`. Tag also drives manifest selection (beta-* vs latest-*- # channel files), since tag (`v0.4.0` or `v0.4.0-beta.N`) and on-disk- # package.json (`0.3.2`) always diverge.+ # the tagged SHA carry the placeholder 0.0.0-unknown, never the tag's+ # and never a `-beta.N`. Tag also drives manifest selection (beta-* vs+ # latest-* channel files), since tag (`v0.4.0` or `v0.4.0-beta.N`) and+ # on-disk package.json (`0.0.0-unknown`) always diverge.## Fail-fast on anything other than `-beta.*` or plain semver —# `-rc.*` / `-canary.*` etc. would ship manifests with a channel@@ -434,14 +433,11 @@ jobs:# describes the transient override), so workspace package.json# files on disk at the tagged SHA always lag the release tag.# `tsdown` inlines `import pkgJson from "../package.json"` into- # `packages/cli/dist/constants-*.mjs` at build time, and- # `packages/cli/build:skill-asset` composes + copies both- # `packages/server/assets/skills/{project,discovery}/SKILL.md` into- # `packages/cli/dist/assets/...`. Both bake in during the workspace- # build below, so the override has to land here first.+ # `packages/cli/dist/constants-*.mjs` during the workspace build+ # below, so the override has to land here first.#- # Mirrors release.yml (same `jq` loop over the five fixed-group packages- # + same `sed` regex against SKILL.md) so the workflows stay in lockstep.+ # Mirrors release.yml (same `jq` loop over the five fixed-group+ # packages) so the workflows stay in lockstep.- name: Override fixed-group versions on disk (zero-commit-bump cadence)env:VERSION: ${{ steps.channel.outputs.version }}@@ -452,12 +448,7 @@ jobs:jq --arg v "$VERSION" '.version=$v' "$f" > "${f}.tmp"mv "${f}.tmp" "$f"done- for skill in packages/server/assets/skills/project/SKILL.md \- packages/server/assets/skills/discovery/SKILL.md; do- sed -i'.bak' -E "s/^([[:space:]]+version:[[:space:]]+\")[^\"]+(\".*)$/\1${VERSION}\2/" "$skill"- rm -f "${skill}.bak"- done- echo "All fixed-group package.json files + both skill bundles' metadata.version now at ${VERSION} (in-memory only)."+ echo "All fixed-group package.json files now at ${VERSION} (in-memory only)."- name: Build workspace (produces packages/cli/dist for extraResources)run: |@@ -624,12 +615,7 @@ jobs:jq --arg v "$VERSION" '.version=$v' "$f" > "${f}.tmp"mv "${f}.tmp" "$f"done- for skill in packages/server/assets/skills/project/SKILL.md \- packages/server/assets/skills/discovery/SKILL.md; do- sed -i'.bak' -E "s/^([[:space:]]+version:[[:space:]]+\")[^\"]+(\".*)$/\1${VERSION}\2/" "$skill"- rm -f "${skill}.bak"- done- echo "All fixed-group package.json files + both skill bundles' metadata.version now at ${VERSION} (in-memory only)."+ echo "All fixed-group package.json files now at ${VERSION} (in-memory only)."- name: Install the declared Rust toolchainrun: |@@ -883,10 +869,9 @@ jobs:# zero-commit-bump cadence the on-disk versions ALWAYS lag the# release tag, so this override is never a no-op for the Desktop's# own metadata. But it does NOT reach the CLI bundle's- # compile-time-inlined PACKAGE_VERSION or the bundled SKILL.md- # asset's metadata.version; those are baked in at Build time, so- # the workspace-wide on-disk override step above is what makes- # them match the tag. See PRD-6650.+ # compile-time-inlined PACKAGE_VERSION, which is baked in at Build+ # time, so the workspace-wide on-disk override step above is what+ # makes it match the tag. See PRD-6650.set -euo pipefailWRAPPER="${RUNNER_TEMP}/retry-transient.mjs"WRAPPER_TMP="${WRAPPER}.tmp.$$"diff --git a/.github/workflows/point-release.yml b/.github/workflows/point-release.ymlindex e8e902ef9..1e70e073e 100644--- a/.github/workflows/point-release.yml+++ b/.github/workflows/point-release.yml@@ -42,11 +42,10 @@ name: Point release# release on the channel every default install follows.## Cascade. On a real run the script tags, creates a DRAFT Release, and dispatches-# the same three consumers the ordinary promotion does — release.yml (npm-# publish), desktop-release.yml (every platform's signed installers, which also flips-# the draft to published), and main-reset on agents-private (changeset consolidation). Their-# input contracts are untouched: this is a different way to reach the existing-# cascade, not a second one.+# desktop-release.yml, the same consumer the ordinary promotion does: it builds+# every platform's signed installers, flips the draft to published and then+# dispatches release.yml for the npm publish. Its input contract is untouched:+# this is a different way to reach the existing cascade, not a second one.## Token model, inherited from promote-stable.yml. The synthetic commit carries# the LAST STABLE's .github/workflows/ tree, which differs from main whenever any@@ -75,10 +74,6 @@ on:description: "Commit SHA(s) to apply, comma- or space-separated. Each must already be on main."required: truetype: string- anchor_delta_ids:- description: "Changeset id(s) for main-reset to consolidate. Revert mode has none of its own — name one here or the main-reset dispatch is skipped and the anchor stays behind."- required: false- type: stringresolve_paths:description: "Config path(s) whose conflict may be re-derived instead of refused. Allowlisted config registries only (pnpm-workspace.yaml); a conflict anywhere else always hard-fails. Blank by default."required: false@@ -196,38 +191,6 @@ jobs:git config user.name "github-actions[bot]"git config user.email "41898282+github-actions[bot]@users.noreply.github.com"- - name: Detect bridge App for cross-repo dispatch- # main-reset runs on agents-private, and neither GITHUB_TOKEN nor the- # INTERNAL_CI_APP token can write there. The "Inkeep OK Release Bridge"- # App supplies that credential. Absence is not an error: the release- # still ships and the plan warns the operator to run main-reset by hand.- # Secrets are unreadable in `if:` expressions, so the presence check runs- # as a step and gates the mint through an output.- id: bridge-check- env:- OK_RELEASE_BRIDGE_APP_ID: ${{ secrets.OK_RELEASE_BRIDGE_APP_ID }}- run: |- set -euo pipefail- if [[ -n "${OK_RELEASE_BRIDGE_APP_ID:-}" ]]; then- echo "configured=true" >> "$GITHUB_OUTPUT"- else- echo "configured=false" >> "$GITHUB_OUTPUT"- echo "OK_RELEASE_BRIDGE_APP_ID not set — the main-reset dispatch will be skipped; run it manually on agents-private."- fi-- - name: Mint cross-repo dispatch token (bridge App)- if: steps.bridge-check.outputs.configured == 'true'- id: bridge-token- uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1- with:- # Public client ID for inkeep-ok-release-bridge (non-secret; supersedes the deprecated app-id input).- client-id: Iv23lii4qS2FAc6tkzfI- private-key: ${{ secrets.OK_RELEASE_BRIDGE_APP_PRIVATE_KEY }}- # The bridge App is installed on agents-private, not on the repo this- # workflow runs on; owner + repositories scope the token to it.- owner: inkeep- repositories: agents-private-- name: Attest production reader before point releaseif: inputs.dry_run == falseuses: ./.github/composite-actions/share-contract-reader-gate@@ -243,15 +206,10 @@ jobs:# the line, so a crafted input would run as shell. Defense-in-depth,# since dispatching this workflow already needs repo write access.GH_TOKEN: ${{ steps.app-token.outputs.token }}- # Empty when the bridge App is absent; the script reads that as- # "no cross-repo credential" and skips the main-reset dispatch.- BRIDGE_GH_TOKEN: ${{ steps.bridge-token.outputs.token }}- BRIDGE_CONFIGURED: ${{ steps.bridge-check.outputs.configured }}BUMP_VERDICTS: ${{ needs.read-bumps.outputs.bump_verdicts }}NOTE_LEVELS: ${{ needs.read-bumps.outputs.note_levels }}MODE: ${{ inputs.mode }}FIX_REFS: ${{ inputs.fix_refs }}- ANCHOR_DELTA_IDS: ${{ inputs.anchor_delta_ids }}# Blank unless an operator deliberately named a path, so automated# dispatches (the bug lane) never resolve anything and keep the# unconditional hard-fail on conflict.@@ -261,8 +219,8 @@ jobs:DRY_RUN: ${{ inputs.dry_run }}DISPATCHED_BY: ${{ inputs.dispatched_by }}# Writes the plan as JSON to stdout and dry_run / point_release_tag /- # point_release_version / latest_stable_tag / synthetic_sha / delta_ids /- # main_reset_dispatched to GITHUB_OUTPUT. Exit 2 is a guard refusing+ # point_release_version / latest_stable_tag / synthetic_sha / added_ids to+ # GITHUB_OUTPUT. Exit 2 is a guard refusing# (a named precondition said no); exit 1 is an infra failure. Either way# nothing remote has been touched — every mutation happens after the# last guard. Logic + tests: .github/scripts/point-release-plan.{mjs,test.mjs}.@@ -274,8 +232,7 @@ jobs:POINT_RELEASE_TAG: ${{ steps.plan.outputs.point_release_tag }}LATEST_STABLE_TAG: ${{ steps.plan.outputs.latest_stable_tag }}SYNTHETIC_SHA: ${{ steps.plan.outputs.synthetic_sha }}- DELTA_IDS: ${{ steps.plan.outputs.delta_ids }}- MAIN_RESET_DISPATCHED: ${{ steps.plan.outputs.main_reset_dispatched }}+ ADDED_IDS: ${{ steps.plan.outputs.added_ids }}RESOLVED_PATHS: ${{ steps.plan.outputs.resolved_paths }}MODE: ${{ inputs.mode }}FIX_REFS: ${{ inputs.fix_refs }}@@ -291,7 +248,7 @@ jobs:echo "- Over stable: \`${LATEST_STABLE_TAG}\`"echo "- Mode: \`${MODE}\` of \`${FIX_REFS}\`"echo "- Desktop product: \`stable\` (Beta has an independent release lane)"- echo "- Changeset delta for main-reset: \`${DELTA_IDS}\` (dispatched: ${MAIN_RESET_DISPATCHED})"+ echo "- Changesets added over the stable: \`${ADDED_IDS}\`"if [[ -n "${RESOLVED_PATHS:-}" && "$RESOLVED_PATHS" != "[]" ]]; thenecho "- **Re-derived config paths: \`${RESOLVED_PATHS}\`** — the pick conflicted there and the file"echo " was rebuilt as the last stable plus the entries the fix itself changed. The exact entries"diff --git a/.github/workflows/promote-stable.yml b/.github/workflows/promote-stable.ymlindex 8094d274b..bfddb95e0 100644--- a/.github/workflows/promote-stable.yml+++ b/.github/workflows/promote-stable.yml@@ -37,12 +37,6 @@ name: Promote stable# `ok-release-cadence` lock at WORKFLOW level, so a 15-75 min build here# would block every beta cut for the duration.#-# After a successful cut this dispatches main-reset.yml on-# inkeep/agents-private (via the "Inkeep OK Release Bridge" App) to advance-# the base for the next cycle — one-button promotion. When the bridge App-# secrets are absent the dispatch skips and the engineer runs main-reset.yml-# manually (two-button fallback).-## Concurrency group is shared with release.yml so beta cuts and stable# promotions never race on the same public-repo state.#@@ -63,9 +57,7 @@ name: Promote stable# installation UI, not something this workflow file can change. If the# installation lacks the grant, the App token has the same scope problem# as GITHUB_TOKEN and the `remote rejected` signature recurs on the next-# stale-tree promotion. See sister workflow-# .github/workflows/public-open-knowledge-main-reset.yml on agents-private-# for the same primitive applied to the post-promotion cycle.+# stale-tree promotion.on:workflow_dispatch:@@ -97,7 +89,7 @@ permissions:# write.contents: write# Read-only: lets the dispatch steps resolve the run URLs of the workflows they- # trigger (release.yml, desktop-release.yml, main-reset) for run-to-run links.+ # trigger (release.yml, desktop-release.yml) for run-to-run links.actions: readconcurrency:@@ -484,73 +476,3 @@ jobs:if [[ -n "$CHILD" ]]; then echo "- Run: ${CHILD}"; else echo "- (run link unresolved; open desktop-release.yml)"; fiecho "- That run smokes the DMG, promotes the draft Release, then dispatches publish-stable to release.yml for npm. npm \`latest\` does NOT move until the smoke passes."} >> "$GITHUB_STEP_SUMMARY"-- - 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 the public repo only and cannot dispatch cross-repo. The- # "Inkeep OK Release Bridge" GitHub App supplies it: installed on- # agents-private, its App-ID + private key live in the public repo's- # secrets, and the next step mints a short-lived installation token- # at runtime (no static- # long-lived token stored). If the App secrets are absent the bridge- # is not configured — skip silently and promotion stays two-button- # (engineer runs main-reset.yml manually). Secrets cannot be read in- # `if:` expressions, so the presence check runs here and gates the- # mint + dispatch steps via an output.- id: bridge-check- env:- OK_RELEASE_BRIDGE_APP_ID: ${{ secrets.OK_RELEASE_BRIDGE_APP_ID }}- run: |- set -euo pipefail- if [[ -n "${OK_RELEASE_BRIDGE_APP_ID:-}" ]]; then- echo "configured=true" >> "$GITHUB_OUTPUT"- else- echo "configured=false" >> "$GITHUB_OUTPUT"- echo "OK_RELEASE_BRIDGE_APP_ID not set — skipping auto-trigger of main-reset; promotion stays two-button (run main-reset.yml manually on agents-private)."- fi-- - name: Mint cross-repo dispatch token (bridge App)- if: steps.bridge-check.outputs.configured == 'true'- id: bridge-token- uses: actions/create-github-app-token@1b10c78c7865c340bc4f6099eb2f838309f1e8c3 # v3.1.1- with:- # Public client ID for inkeep-ok-release-bridge (non-secret; supersedes the deprecated app-id input).- client-id: Iv23lii4qS2FAc6tkzfI- private-key: ${{ secrets.OK_RELEASE_BRIDGE_APP_PRIVATE_KEY }}- # The bridge App is installed on agents-private, not on the public- # repo (where this workflow runs). owner + repositories scope the minted- # token to that cross-repo installation.- owner: inkeep- repositories: agents-private-- - name: Trigger main-reset on agents-private- if: steps.bridge-check.outputs.configured == 'true'- 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- SELF_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"- SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)- payload=$(jq -nc --arg v "$STABLE_VERSION" --argjson d "${DELTA_IDS:-[]}" --arg by "$SELF_URL" \- '{event_type: "main-reset", client_payload: {stable_version: $v, delta_ids: $d, dispatched_by: $by}}')- gh api -X POST "repos/inkeep/agents-private/dispatches" --input - <<<"$payload"- # Best-effort cross-repo forward-link (the bridge token reads agents-private).- CHILD=""- for _ in 1 2 3 4 5 6; do- CHILD=$(gh run list --repo inkeep/agents-private --workflow=public-open-knowledge-main-reset.yml --event=repository_dispatch --limit 8 --json url,createdAt \- --jq "[.[] | select(.createdAt >= \"$SINCE\")] | sort_by(.createdAt) | last | .url // empty" 2>/dev/null || true)- [[ -n "$CHILD" ]] && break- sleep 3- done- {- echo "### Dispatched main-reset (agents-private)"- if [[ -n "$CHILD" ]]; then echo "- Run: ${CHILD}"; else echo "- (run link unresolved; open the main-reset workflow on agents-private)"; fi- } >> "$GITHUB_STEP_SUMMARY"- echo "Dispatched main-reset to agents-private (stable_version=${STABLE_VERSION}, delta_ids=${DELTA_IDS})."diff --git a/.github/workflows/release.yml b/.github/workflows/release.ymlindex 646d4134e..9d17db1bb 100644--- a/.github/workflows/release.yml+++ b/.github/workflows/release.yml@@ -5,8 +5,8 @@ name: Release## Beta path: event-driven on `push` to open-knowledge/main with a paths# filter on `.changeset/**`. Copybara mirrors-# `public/open-knowledge/.changeset/*.md`, `pre.json`, and `config.json`-# from agents-private. When agents-private merges a PR with a changeset,+# `public/open-knowledge/.changeset/*.md` and `config.json` from+# agents-private. When agents-private merges a PR with a changeset,# Copybara batches it into a Project-import commit on open-knowledge/main;# that import push IS the release trigger. The workflow then runs# `compute-next-beta.mjs` locally to derive baseVersion@@ -34,9 +34,8 @@ name: Release# matching the paths filter) → skip cleanly.# - Resolves -beta.N counter from existing vX.Y.Z-beta.* tags# (race-free inside the ok-release-cadence concurrency slot).-# - Overrides every fixed-group packages/*/package.json#version AND-# both packages/server/assets/skills/{project,discovery}/SKILL.md-# metadata.version to X.Y.Z-beta.N (transient jq, never committed).+# - Overrides every fixed-group packages/*/package.json#version+# to X.Y.Z-beta.N (transient jq, never committed).# - Tags vX.Y.Z-beta.N at `github.sha` + creates a prerelease GitHub# Release with the rendered notes (consumed-set marker embedded# for the next cut to read).@@ -57,8 +56,8 @@ name: Release# - Checks out the stable tag (the promoted beta's SHA, or the# synthetic commit a point release tags).# - Overrides every fixed-group package.json#version to the clean-# X.Y.Z (the public repo's commit at that SHA carries the version-# the last main reset wrote, normally the previous stable).+# X.Y.Z (the public repo's commit at that SHA carries the committed+# placeholder 0.0.0-unknown).# - Publishes @inkeep/[email protected] to npm with# `--tag latest --provenance`.# desktop-release.yml is dispatched by promote-stable.yml or@@ -347,9 +346,10 @@ jobs:# listing read-releases recorded; emits `{skip: true, reason}` when no# new changesets exist since the last beta (e.g., a Copybara import# that touched `.changeset/config.json` but no `.md` files). The- # script MUTATES the working tree (a transient pre.json + CHANGELOG.md- # + package.json + deletes .changeset/*.md); the final `Restore- # working tree` step cleans up.+ # script MUTATES the working tree (writes a transient pre.json, which+ # main does not commit, + CHANGELOG.md + package.json, and deletes+ # .changeset/*.md); the final `Restore working tree` step restores the+ # tracked files.- name: Compute next beta base version + render release notesif: github.event_name == 'push' || github.event_name == 'workflow_dispatch'id: compute-beta@@ -448,17 +448,7 @@ jobs:jq --arg v "$VERSION" '.version=$v' "$f" > "${f}.tmp"mv "${f}.tmp" "$f"done- # Both skill bundles' metadata.version "tracks- # @inkeep/open-knowledge-server package version" — the build-time- # invariant test in packages/server/src/skill-state.test.ts asserts- # they match. Mutate in place (sed: same transient-only model as jq- # above), once per bundle.- for skill in packages/server/assets/skills/project/SKILL.md \- packages/server/assets/skills/discovery/SKILL.md; do- sed -i'.bak' -E "s/^([[:space:]]+version:[[:space:]]+\")[^\"]+(\".*)$/\1${VERSION}\2/" "$skill"- rm -f "${skill}.bak"- done- echo "All fixed-group package.json files + both skill bundles' metadata.version now at ${VERSION} (in-memory only)."+ echo "All fixed-group package.json files now at ${VERSION} (in-memory only)."- name: Validate stable_version + override package.json (publish-stable)if: github.event.action == 'publish-stable'@@ -481,12 +471,7 @@ jobs:jq --arg v "$STABLE_VERSION" '.version=$v' "$f" > "${f}.tmp"mv "${f}.tmp" "$f"done- for skill in packages/server/assets/skills/project/SKILL.md \- packages/server/assets/skills/discovery/SKILL.md; do- sed -i'.bak' -E "s/^([[:space:]]+version:[[:space:]]+\")[^\"]+(\".*)$/\1${STABLE_VERSION}\2/" "$skill"- rm -f "${skill}.bak"- done- echo "All fixed-group package.json files + both skill bundles' metadata.version now at ${STABLE_VERSION} (in-memory only)."+ echo "All fixed-group package.json files now at ${STABLE_VERSION} (in-memory only)."- name: Build the cli and its workspace dependencies at the overridden versionsrun: |diff --git a/.github/workflows/select-beta-to-promote.yml b/.github/workflows/select-beta-to-promote.ymlindex 3b1f51a8b..398611510 100644--- a/.github/workflows/select-beta-to-promote.yml+++ b/.github/workflows/select-beta-to-promote.yml@@ -22,8 +22,8 @@ name: Select beta to promote# This workflow does NOT reimplement promotion. It dispatches promote-stable.yml# 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+# creates the Release, and cascades npm --tag latest + signed stable DMG+# unchanged. "OK desktop to stable" is covered for free via the# promote-stable -> desktop-release cascade (latest-mac.yml + DMG). NOTE:# 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@@ -115,8 +115,8 @@ permissions:# actions:write is required to dispatch promote-stable.yml (workflow_dispatch# via the API) and covers the read for the in-flight `gh run list` check.# contents:read to read tags. No id-token and no App token here — promote-stable- # mints its own App token for the identity-asserting work (tag push, cross-repo- # main-reset dispatch), so this evaluator stays minimally scoped.+ # mints its own App token for the identity-asserting work (the tag push), so+ # this evaluator stays minimally scoped.contents: readactions: write@@ -335,7 +335,7 @@ jobs:SELF_URL="${GITHUB_SERVER_URL}/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)gh workflow run promote-stable.yml -f beta_tag="$TARGET" -f dispatched_by="$SELF_URL"- echo "::notice::Dispatched promote-stable for ${TARGET} (it computes the stable version from the changeset delta, then 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)."# Link this run to the promote-stable run it just created. `gh workflow# run` does not return the new run id, so resolve it (best-effort) as the# newest workflow_dispatch run of promote-stable created after SINCE.diff --git a/AGENTS.md b/AGENTS.mdindex 66ebccaca..89bc8b0a0 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -86,7 +86,7 @@ Shell scripts are declared in scope by `no-comments.config.jsonc`, but the sweep## Changesets-Every behavior-changing PR ships a `.changeset/<kebab-name>.md` file. The body becomes the user-facing entry on the next beta's GitHub Release and on the aggregated stable Release notes — that's how npm consumers and desktop auto-update users learn what changed. Write release-note copy, not a commit-message reprise.+Every behavior-changing PR ships a `.changeset/<kebab-name>.md` file. The body becomes the user-facing entry on the next beta's GitHub Release and on the stable Release notes — that's how npm consumers and desktop auto-update users learn what changed. Write release-note copy, not a commit-message reprise.- Create one with `pnpm run changeset`, or hand-write a file named `.changeset/<descriptive-kebab-slug>.md`.- Use a name no shipped changeset has used. A stable that carried the name counts it as released, so the new notes would never appear; the PR check refuses the file and asks for a rename.diff --git a/docs/package.json b/docs/package.jsonindex 02191e741..8db5f51fd 100644--- a/docs/package.json+++ b/docs/package.json@@ -1,6 +1,6 @@{"name": "@inkeep/open-knowledge-docs",- "version": "0.0.272",+ "version": "0.0.0-unknown","license": "GPL-3.0-or-later","private": true,"packageManager": "[email protected]",diff --git a/docs/src/lib/releases.test.ts b/docs/src/lib/releases.test.tsindex 72e4af885..75f90f36a 100644--- a/docs/src/lib/releases.test.ts+++ b/docs/src/lib/releases.test.ts@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs';import { join } from 'node:path';import { describe, expect, test, vi } from 'vitest';import {+ ALLOW_PARTIAL_CHANGELOG,collectDates,collectMarkedNotes,cutoverOf,@@ -14,6 +15,7 @@ import {parseChangelog,passedCutover,releaseNotesFrom,+ releaseNotesRequired,} from './releases.ts';const SAMPLE = `# @inkeep/open-knowledge@@ -140,6 +142,7 @@ function mockFetch(responder: (page: number) => Response) {}const json = (data: unknown) => new Response(JSON.stringify(data), { status: 200 });+const noWait = async () => {};const fullPage = (page: number) =>Array.from({ length: 100 }, (_, i) => apiRelease(`v9.${page}.${i}`, { prerelease: i > 0 }));@@ -148,7 +151,7 @@ describe('fetchReleaseFeed dates (best-effort)', () => {const feed = await fetchReleaseFeed({dateLimit: 2,changelogTags: new Set(),- fetchImpl: mockFetch((p) => json(fullPage(p))),+ fetchImpl: mockFetch((p) => json(p <= 3 ? fullPage(p) : [])),});expect(feed.dates.size).toBe(2);});@@ -165,6 +168,7 @@ describe('fetchReleaseFeed dates (best-effort)', () => {const feed = await fetchReleaseFeed({changelogTags: new Set(),fetchImpl: mockFetch(() => new Response('nope', { status: 500 })),+ sleep: noWait,});expect(feed.dates.size).toBe(0);});@@ -174,6 +178,7 @@ describe('fetchReleaseFeed dates (best-effort)', () => {const feed = await fetchReleaseFeed({changelogTags: new Set(),fetchImpl: (() => Promise.reject(new Error('offline'))) as never,+ sleep: noWait,});expect(feed.dates.size).toBe(0);warn.mockRestore();@@ -440,7 +445,11 @@ describe('fetchReleaseFeed', () => {[[apiRelease('v1.1.0', { body: marked('- New.') }), ...betas(1, 99)]],(page) => (page === 2 ? 502 : 200),);- const feed = await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: impl });+ const feed = await fetchReleaseFeed({+ changelogTags: new Set(['v1.0.0']),+ fetchImpl: impl,+ sleep: noWait,+ });expect(feed.notesComplete).toBe(false);expect(feed.failure).toBe('page 2 returned HTTP 502');expect([...feed.dates.keys()]).toEqual(['v1.1.0']);@@ -454,17 +463,239 @@ describe('fetchReleaseFeed', () => {expect(feed.failure).toBe('page 1 returned a body that is not a list of releases');});- test('stops at the page cap without passing the cutover, and says the notes are incomplete', async () => {+ test('walks as many pages as the cutover is deep, so release volume alone never leaves the notes incomplete', async () => {+ const pages = [+ ...Array.from({ length: 40 }, (_, i) => [+ apiRelease(`v2.${i}.0`, { body: marked(`- Release ${i}.`), published_at: day(i) }),+ ...betasCreated(i, 99, i),+ ]),+ [+ apiRelease('v1.0.0', { body: '- Old.', published_at: day(60) }),+ ...betasCreated(40, 99, 80),+ ],+ [apiRelease('v0.9.0', { body: marked('- Not read.') })],+ ];+ const { impl, requested } = pagedFetch(pages);+ const feed = await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: impl });+ expect(requested).toEqual(Array.from({ length: 41 }, (_, i) => i + 1));+ expect(feed.notes.size).toBe(40);+ expect(feed.notesComplete).toBe(true);+ expect(feed.failure).toBeNull();+ });++ test('a listing that never ends stops at the runaway bound with a failure that says so', async () => {const { impl, requested } = pagedFetch(- Array.from({ length: 30 }, (_, i) => [+ Array.from({ length: 10 }, (_, i) => [apiRelease(`v2.${i}.0`, { body: marked('- x') }),...betas(i, 99),]),);- const feed = await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: impl });- expect(requested).toHaveLength(20);+ const feed = await fetchReleaseFeed({+ changelogTags: new Set(['v1.0.0']),+ fetchImpl: impl,+ runawayPages: 6,+ });+ expect(requested).toHaveLength(6);expect(feed.notesComplete).toBe(false);- expect(feed.failure).toBe('stopped at the 20-page cap');+ expect(feed.failure).toBe(+ 'the Releases listing did not end within 6 pages and never reached the cutover',+ );+ });++ test('retries a transient 5xx, a network error and a short retry-after, with a deadline on every request', async () => {+ const waits: number[] = [];+ const sleep = async (ms: number) => {+ waits.push(ms);+ };+ const deadlines: number[] = [];+ const issued: AbortSignal[] = [];+ const deadline = (ms: number) => {+ deadlines.push(ms);+ const signal = new AbortController().signal;+ issued.push(signal);+ return signal;+ };+ const scripted = (answers: (() => Response | Error)[]) => {+ const seen: (AbortSignal | null | undefined)[] = [];+ const impl = ((_url: string | URL, init?: RequestInit) => {+ seen.push(init?.signal);+ const next = answers.shift()?.();+ return next instanceof Error ? Promise.reject(next) : Promise.resolve(next);+ }) as unknown as typeof fetch;+ return { impl, seen };+ };+ const page = () => json([apiRelease('v1.1.0', { body: marked('- New.') })]);+ const flaky = scripted([+ () => new Response('busy', { status: 503 }),+ () => new Error('socket hang up'),+ page,+ ]);+ const feed = await fetchReleaseFeed({+ changelogTags: new Set(['v1.0.0']),+ fetchImpl: flaky.impl,+ sleep,+ deadline,+ });+ expect(feed.failure).toBeNull();+ expect(feed.notesComplete).toBe(true);+ expect([...feed.notes.keys()]).toEqual(['v1.1.0']);+ expect(deadlines).toEqual([30_000, 30_000, 30_000]);+ expect(flaky.seen).toEqual(issued);+ expect(waits).toEqual([1000, 2000]);+ waits.length = 0;+ const limited = scripted([+ () => new Response('slow down', { status: 403, headers: { 'retry-after': '5' } }),+ page,+ ]);+ const throttled = await fetchReleaseFeed({+ changelogTags: new Set(['v1.0.0']),+ fetchImpl: limited.impl,+ sleep,+ deadline,+ });+ expect(throttled.failure).toBeNull();+ expect(waits).toEqual([5000]);+ });++ test('gives up on a page after three attempts and does not retry another 4xx', async () => {+ const { impl, requested } = pagedFetch([], () => 503);+ const failed = await fetchReleaseFeed({+ changelogTags: new Set(['v1.0.0']),+ fetchImpl: impl,+ sleep: noWait,+ });+ expect(requested).toEqual([1, 1, 1]);+ expect(failed.failure).toBe('page 1 returned HTTP 503');+ const forbidden = pagedFetch([], () => 403);+ const refused = await fetchReleaseFeed({+ changelogTags: new Set(['v1.0.0']),+ fetchImpl: forbidden.impl,+ sleep: noWait,+ });+ expect(forbidden.requested).toEqual([1]);+ expect(refused.failure).toBe('page 1 returned HTTP 403');+ });++ test('a rate limit that outlasts the retry-after cap, a spent primary limit and a refused token each fail at once, naming the cause', async () => {+ const cases: [() => Response, string][] = [+ [+ () => new Response('', { status: 429, headers: { 'retry-after': '60' } }),+ 'page 1 was rate-limited (HTTP 429)',+ ],+ [+ () => new Response('', { status: 403, headers: { 'x-ratelimit-remaining': '0' } }),+ 'page 1 was rate-limited (HTTP 403)',+ ],+ [+ () => new Response('', { status: 401 }),+ 'page 1 returned HTTP 401: the GITHUB_TOKEN this build sent was refused',+ ],+ ];+ for (const [respond, failure] of cases) {+ const waits: number[] = [];+ let calls = 0;+ const impl = (() => {+ calls += 1;+ return Promise.resolve(respond());+ }) as unknown as typeof fetch;+ const feed = await fetchReleaseFeed({+ changelogTags: new Set(['v1.0.0']),+ fetchImpl: impl,+ sleep: async (ms) => {+ waits.push(ms);+ },+ });+ expect(feed.failure).toBe(failure);+ expect(calls).toBe(1);+ expect(waits).toEqual([]);+ }+ });++ test('a network failure names its page and the underlying cause, and an unparseable body names its page', async () => {+ const unreachable = (() =>+ Promise.reject(+ new TypeError('fetch failed', {+ cause: Object.assign(new Error('getaddrinfo ENOTFOUND api.github.com'), {+ code: 'ENOTFOUND',+ }),+ }),+ )) as unknown as typeof fetch;+ const offline = await fetchReleaseFeed({+ changelogTags: new Set(['v1.0.0']),+ fetchImpl: unreachable,+ sleep: noWait,+ });+ expect(offline.failure).toBe(+ 'page 1 request failed after 3 attempts: fetch failed (ENOTFOUND)',+ );+ const html = (() =>+ Promise.resolve(new Response('<html>', { status: 200 }))) as unknown as typeof fetch;+ const garbled = await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: html });+ expect(garbled.failure).toMatch(/^page 1 returned a body that is not JSON: /);+ });++ test('a body read that times out or resets is retried, and reported as a request failure rather than as a body that is not JSON', async () => {+ const cut = (reason: () => Error) =>+ ({+ ok: true,+ status: 200,+ headers: new Headers(),+ text: () => Promise.reject(reason()),+ }) as unknown as Response;+ const answers = [+ cut(() => new DOMException('The operation was aborted due to timeout', 'TimeoutError')),+ json([apiRelease('v1.1.0', { body: marked('- New.') })]),+ ];+ const waits: number[] = [];+ const recovered = await fetchReleaseFeed({+ changelogTags: new Set(['v1.0.0']),+ fetchImpl: (() => Promise.resolve(answers.shift())) as unknown as typeof fetch,+ sleep: async (ms) => {+ waits.push(ms);+ },+ });+ expect(recovered.failure).toBeNull();+ expect([...recovered.notes.keys()]).toEqual(['v1.1.0']);+ expect(waits).toEqual([1000]);+ const reset = (() =>+ Promise.resolve(+ cut(+ () =>+ new TypeError('terminated', {+ cause: Object.assign(new Error('other side closed'), { code: 'UND_ERR_SOCKET' }),+ }),+ ),+ )) as unknown as typeof fetch;+ const failed = await fetchReleaseFeed({+ changelogTags: new Set(['v1.0.0']),+ fetchImpl: reset,+ sleep: noWait,+ });+ expect(failed.failure).toBe(+ 'page 1 request failed after 3 attempts: terminated (UND_ERR_SOCKET)',+ );+ });++ test('warns about a published stable that has neither marked notes nor a CHANGELOG.md section', async () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ const { impl } = pagedFetch([+ [+ apiRelease('v1.2.0', { body: '- Unmarked, after the freeze.' }),+ apiRelease('v1.1.0', { body: marked('- New.') }),+ apiRelease('v1.0.0', { body: '- Old.' }),+ ],+ ]);+ await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: impl });+ expect(warn).toHaveBeenCalledWith(+ expect.stringMatching(+ /no notes-source marker and no packages\/cli\/CHANGELOG\.md section.*: v1\.2\.0\./,+ ),+ );+ warn.mockClear();+ const covered = pagedFetch([[apiRelease('v1.0.0', { body: '- Old.' })]]);+ await fetchReleaseFeed({ changelogTags: new Set(['v1.0.0']), fetchImpl: covered.impl });+ expect(warn).not.toHaveBeenCalled();+ warn.mockRestore();});test('a network throw leaves the notes incomplete and never throws', async () => {@@ -472,34 +703,77 @@ describe('fetchReleaseFeed', () => {const feed = await fetchReleaseFeed({changelogTags: new Set(['v1.0.0']),fetchImpl: (() => Promise.reject(new Error('offline'))) as never,+ sleep: noWait,});expect(feed).toEqual({dates: new Map(),notes: new Map(),notesComplete: false,- failure: 'offline',+ failure: 'page 1 request failed after 3 attempts: offline',});warn.mockRestore();});});+describe('releaseNotesRequired', () => {+ test('only a production Vercel build requires the Release bodies, unless the operator override is set', () => {+ expect(releaseNotesRequired({ VERCEL: '1', VERCEL_ENV: 'production' })).toBe(true);+ expect(releaseNotesRequired({ VERCEL: '1', VERCEL_ENV: 'preview' })).toBe(false);+ expect(releaseNotesRequired({ VERCEL: '1' })).toBe(false);+ expect(releaseNotesRequired({ CI: 'true' })).toBe(false);+ expect(releaseNotesRequired({})).toBe(false);+ expect(releaseNotesRequired({ VERCEL_ENV: 'production', [ALLOW_PARTIAL_CHANGELOG]: '1' })).toBe(+ false,+ );+ expect(+ releaseNotesRequired({ VERCEL_ENV: 'production', [ALLOW_PARTIAL_CHANGELOG]: 'true' }),+ ).toBe(true);+ });+});+describe('releaseNotesFrom', () => {- test('passes complete notes through and drops incomplete ones with a warning', () => {- const notes = new Map([['v1.0.0', '- One.']]);- expect(releaseNotesFrom({ dates: new Map(), notes, notesComplete: true, failure: null })).toBe(- notes,+ const notes = new Map([['v1.0.0', '- One.']]);+ const incomplete = {+ dates: new Map(),+ notes,+ notesComplete: false,+ failure: 'page 2 returned HTTP 403',+ };++ const production = { VERCEL: '1', VERCEL_ENV: 'production' };++ test('passes complete notes through whether or not they are required', () => {+ const complete = { dates: new Map(), notes, notesComplete: true, failure: null };+ expect(releaseNotesFrom(complete, production)).toBe(notes);+ expect(releaseNotesFrom(complete, {})).toBe(notes);+ });++ test('incomplete notes fail a production build, naming the failure, GITHUB_TOKEN and the override', () => {+ expect(() => releaseNotesFrom(incomplete, production)).toThrow(+ /\(page 2 returned HTTP 403\).*CHANGELOG\.md is frozen.*GITHUB_TOKEN.*OK_ALLOW_PARTIAL_CHANGELOG=1/,);+ });++ test('a preview or local build drops incomplete notes with a warning', () => {+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ expect(releaseNotesFrom(incomplete, { VERCEL: '1', VERCEL_ENV: 'preview' }).size).toBe(0);+ expect(releaseNotesFrom(incomplete, {}).size).toBe(0);+ expect(warn).toHaveBeenCalledWith(+ expect.stringMatching(/\(page 2 returned HTTP 403\).*CHANGELOG\.md notes only/),+ );+ expect(warn).not.toHaveBeenCalledWith(expect.stringMatching(/PRODUCTION/));+ warn.mockRestore();+ });++ test('the override lets a production build publish with a warning that names it', () => {const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});expect(- releaseNotesFrom({- dates: new Map(),- notes,- notesComplete: false,- failure: 'page 2 returned HTTP 403',- }).size,+ releaseNotesFrom(incomplete, { ...production, [ALLOW_PARTIAL_CHANGELOG]: '1' }).size,).toBe(0);expect(warn).toHaveBeenCalledWith(- expect.stringMatching(/\(page 2 returned HTTP 403\).*CHANGELOG\.md notes only/),+ expect.stringMatching(+ /OK_ALLOW_PARTIAL_CHANGELOG=1 is set, so this PRODUCTION build publishes it/,+ ),);warn.mockRestore();});@@ -583,10 +857,50 @@ describe('loadStableReleases', () => {);});- test('when the Release bodies cannot be read it falls back to CHANGELOG.md alone', async () => {+ test('a production build fails when the Release bodies cannot be read, rather than drop every newer stable', async () => {+ const env = { VERCEL: '1', VERCEL_ENV: 'production' };+ await expect(+ loadStableReleases(undefined, {+ fetchImpl: pagedFetch([], () => 503).impl,+ env,+ sleep: noWait,+ }),+ ).rejects.toThrow(/page 1 returned HTTP 503.*CHANGELOG\.md is frozen/);+ const offline = (() => Promise.reject(new Error('offline'))) as unknown as typeof fetch;+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});+ await expect(+ loadStableReleases(undefined, { fetchImpl: offline, env, sleep: noWait }),+ ).rejects.toThrow(/attempts: offline\)/);+ warn.mockRestore();+ });++ test('the Release fetch sends GITHUB_TOKEN when the build has one, and nothing when it does not', async () => {+ const seen: (string | null)[] = [];+ const recording = ((_url: string | URL, init?: RequestInit) => {+ seen.push(new Headers(init?.headers).get('authorization'));+ return Promise.resolve(new Response('[]', { status: 200 }));+ }) as unknown as typeof fetch;+ vi.stubEnv('GITHUB_TOKEN', 'ghs_fixture');+ try {+ await fetchReleaseFeed({ changelogTags: new Set(), fetchImpl: recording });+ } finally {+ vi.unstubAllEnvs();+ }+ vi.stubEnv('GITHUB_TOKEN', '');+ try {+ await fetchReleaseFeed({ changelogTags: new Set(), fetchImpl: recording });+ } finally {+ vi.unstubAllEnvs();+ }+ expect(seen).toEqual(['Bearer ghs_fixture', null]);+ });++ test('outside production, unreadable Release bodies fall back to CHANGELOG.md alone', async () => {const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});const out = await loadStableReleases(undefined, {fetchImpl: pagedFetch([], () => 503).impl,+ env: { VERCEL: '1', VERCEL_ENV: 'preview' },+ sleep: noWait,});expect(out).toEqual(parseChangelog(realChangelog, new Map()));expect(warn).toHaveBeenCalledWith(expect.stringMatching(/CHANGELOG\.md notes only/));diff --git a/docs/src/lib/releases.ts b/docs/src/lib/releases.tsindex 1e636c7a4..0507a26e0 100644--- a/docs/src/lib/releases.ts+++ b/docs/src/lib/releases.ts@@ -10,14 +10,22 @@ const PER_PAGE = 100;const MAX_DATE_PAGES = 5;-const MAX_RELEASE_PAGES = 20;-const DATE_LIMIT = 30;-const RELEASE_NOTES_REQUIRED = false;-const NOTES_LAG_MS = 14 * 24 * 60 * 60 * 1000;+const RUNAWAY_PAGES = 1000;++const FETCH_ATTEMPTS = 3;++const FETCH_TIMEOUT_MS = 30_000;++const MAX_RETRY_AFTER_MS = 10_000;++const RETRY_BACKOFF_MS = 1000;++export const ALLOW_PARTIAL_CHANGELOG = 'OK_ALLOW_PARTIAL_CHANGELOG';+export const NOTES_SOURCE_MARKER = '<!-- ok-notes-source: stable-tag-tree -->';const DOWNLOADS_BLOCK = /<!-- ok-downloads:start -->[\s\S]*?<!-- ok-downloads:end -->/g;@@ -107,6 +115,7 @@ interface PublishedStable {export interface MarkedNotesScan {notes: Map<string, string>;unmarkedCovered: PublishedStable[];+ unlisted: string[];earliestMarkedAt: number;oldestCreatedAt: number;}@@ -115,6 +124,7 @@ export function newMarkedNotesScan(): MarkedNotesScan {return {notes: new Map(),unmarkedCovered: [],+ unlisted: [],earliestMarkedAt: Number.POSITIVE_INFINITY,oldestCreatedAt: Number.POSITIVE_INFINITY,};@@ -157,8 +167,10 @@ export function collectMarkedNotes(if (Number.isFinite(publishedAt)) {scan.earliestMarkedAt = Math.min(scan.earliestMarkedAt, publishedAt);}- } else if (changelogTags.has(tag) && Number.isFinite(publishedAt)) {- scan.unmarkedCovered.push({ tag, publishedAt });+ } else if (changelogTags.has(tag)) {+ if (Number.isFinite(publishedAt)) scan.unmarkedCovered.push({ tag, publishedAt });+ } else if (!scan.unlisted.includes(tag)) {+ scan.unlisted.push(tag);}}}@@ -184,14 +196,108 @@ export interface ReleaseFeed {failure: string | null;}+interface PageIo {+ fetchImpl: typeof fetch;+ sleep: (ms: number) => Promise<void>;+ deadline: (ms: number) => AbortSignal;+}++const realSleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));++function errorText(err: unknown): string {+ if (!(err instanceof Error)) return String(err);+ const cause = err.cause as { code?: unknown; message?: unknown } | undefined;+ const detail =+ typeof cause?.code === 'string'+ ? cause.code+ : typeof cause?.message === 'string'+ ? cause.message+ : null;+ return detail ? `${err.message} (${detail})` : err.message;+}++function rateLimited(res: Response): boolean {+ return (+ res.status === 429 ||+ (res.status === 403 &&+ (res.headers.get('x-ratelimit-remaining') === '0' || res.headers.has('retry-after')))+ );+}++function httpFailure(page: number, res: Response): string {+ if (res.status === 401) {+ return `page ${page} returned HTTP 401: the GITHUB_TOKEN this build sent was refused`;+ }+ if (rateLimited(res)) return `page ${page} was rate-limited (HTTP ${res.status})`;+ return `page ${page} returned HTTP ${res.status}`;+}++type PageRead = { payload: unknown; failure: null } | { payload: null; failure: string };++async function readPage(+ page: number,+ headers: Record<string, string>,+ io: PageIo,+): Promise<PageRead> {+ const url = `${RELEASES_API}?per_page=${PER_PAGE}&page=${page}`;+ for (let attempt = 1; ; attempt++) {+ let res: Response;+ let body = '';+ try {+ res = await io.fetchImpl(url, { headers, signal: io.deadline(FETCH_TIMEOUT_MS) });+ if (res.ok) body = await res.text();+ } catch (err) {+ if (attempt >= FETCH_ATTEMPTS) {+ return {+ payload: null,+ failure: `page ${page} request failed after ${FETCH_ATTEMPTS} attempts: ${errorText(err)}`,+ };+ }+ await io.sleep(RETRY_BACKOFF_MS * attempt);+ continue;+ }+ if (res.ok) {+ try {+ return { payload: JSON.parse(body), failure: null };+ } catch (err) {+ return {+ payload: null,+ failure: `page ${page} returned a body that is not JSON: ${errorText(err)}`,+ };+ }+ }+ if (attempt < FETCH_ATTEMPTS && res.status >= 500) {+ await io.sleep(RETRY_BACKOFF_MS * attempt);+ continue;+ }+ const retryAfterMs = Number(res.headers.get('retry-after')) * 1000;+ if (+ attempt < FETCH_ATTEMPTS &&+ rateLimited(res) &&+ retryAfterMs > 0 &&+ retryAfterMs <= MAX_RETRY_AFTER_MS+ ) {+ await io.sleep(retryAfterMs);+ continue;+ }+ return { payload: null, failure: httpFailure(page, res) };+ }+}+export async function fetchReleaseFeed({dateLimit = DATE_LIMIT,changelogTags,fetchImpl = fetch,+ sleep = realSleep,+ deadline = (ms: number) => AbortSignal.timeout(ms),+ runawayPages = RUNAWAY_PAGES,}: {dateLimit?: number;changelogTags: ReadonlySet<string>;fetchImpl?: typeof fetch;+ sleep?: (ms: number) => Promise<void>;+ deadline?: (ms: number) => AbortSignal;+ runawayPages?: number;}): Promise<ReleaseFeed> {const dates = new Map<string, string>();const scan = newMarkedNotesScan();@@ -203,34 +309,34 @@ export async function fetchReleaseFeed({'user-agent': 'openknowledge.ai changelog',...(token ? { authorization: `Bearer ${token}` } : {}),};- try {- for (let page = 1; ; page++) {- const wantDates = page <= MAX_DATE_PAGES && dates.size < dateLimit;- if (!wantDates && passedCutover(scan)) break;- if (page > MAX_RELEASE_PAGES) {- failure = `stopped at the ${MAX_RELEASE_PAGES}-page cap`;- break;- }- const res = await fetchImpl(`${RELEASES_API}?per_page=${PER_PAGE}&page=${page}`, { headers });- if (!res.ok) {- failure = `page ${page} returned HTTP ${res.status}`;- break;- }- const payload = await res.json();- if (!Array.isArray(payload)) {- failure = `page ${page} returned a body that is not a list of releases`;- break;- }- if (wantDates) collectDates(payload, dates, dateLimit);- collectMarkedNotes(payload, scan, changelogTags);- if (payload.length < PER_PAGE) {- exhausted = true;- break;- }+ for (let page = 1; ; page++) {+ const wantDates = page <= MAX_DATE_PAGES && dates.size < dateLimit;+ if (!wantDates && passedCutover(scan)) break;+ if (page > runawayPages) {+ failure = `the Releases listing did not end within ${runawayPages} pages and never reached the cutover`;+ break;}- } catch (err) {- failure = err instanceof Error ? err.message : String(err);- console.warn(`[releases] date enrichment failed; building changelog without dates: ${failure}`);+ const read = await readPage(page, headers, { fetchImpl, sleep, deadline });+ if (read.failure !== null) {+ failure = read.failure;+ break;+ }+ const { payload } = read;+ if (!Array.isArray(payload)) {+ failure = `page ${page} returned a body that is not a list of releases`;+ break;+ }+ if (wantDates) collectDates(payload, dates, dateLimit);+ collectMarkedNotes(payload, scan, changelogTags);+ if (payload.length < PER_PAGE) {+ exhausted = true;+ break;+ }+ }+ if (scan.unlisted.length > 0) {+ console.warn(+ `[releases] published stable Release(s) with no notes-source marker and no packages/cli/CHANGELOG.md section, so the changelog has no entry for them: ${scan.unlisted.join(', ')}. Restore the marked notes in each Release body and re-fire the docs deploy.`,+ );}return {dates,@@ -262,14 +368,39 @@ export function mergeReleaseNotes();}-export function releaseNotesFrom(feed: ReleaseFeed): ReadonlyMap<string, string> {+type BuildEnv = Readonly<Record<string, string | undefined>>;++export function releaseNotesRequired(env: BuildEnv = process.env): boolean {+ return env.VERCEL_ENV === 'production' && env[ALLOW_PARTIAL_CHANGELOG] !== '1';+}++export function releaseNotesFrom(+ feed: ReleaseFeed,+ env: BuildEnv = process.env,+): ReadonlyMap<string, string> {if (feed.notesComplete) return feed.notes;const reason ='[releases] could not read every stable Release body back to the newest one without notes' +`${feed.failure ? ` (${feed.failure})` : ''}; ` +'the changelog cannot tell which versions have notes in their Release body.';- if (RELEASE_NOTES_REQUIRED) throw new Error(reason);- console.warn(`${reason} Showing packages/cli/CHANGELOG.md notes only.`);+ if (releaseNotesRequired(env)) {+ throw new Error(+ `${reason} packages/cli/CHANGELOG.md is frozen, so a production build without the Release ` ++ 'bodies would drop every newer stable from the live changelog. Re-run the deploy. A rate ' ++ 'limit needs GITHUB_TOKEN on the Vercel project, and an HTTP 401 means the token set there ' ++ 'was refused and needs replacing. Set ' ++ `${ALLOW_PARTIAL_CHANGELOG}=1 to publish the CHANGELOG.md notes alone. Runbook: RELEASES.md, ` ++ '"The docs changelog reads the Release bodies".',+ );+ }+ const production =+ env.VERCEL_ENV === 'production'+ ? ` ${ALLOW_PARTIAL_CHANGELOG}=1 is set, so this PRODUCTION build publishes it; unset it once the cause is fixed.`+ : '';+ console.warn(+ `${reason} Showing packages/cli/CHANGELOG.md notes only, so every stable newer than it is ` ++ `missing from this build's changelog.${production}`,+ );return new Map();}@@ -292,7 +423,11 @@ function readChangelog(): string | null {export async function loadStableReleases(limit = Number.POSITIVE_INFINITY,- deps: { fetchImpl?: typeof fetch } = {},+ deps: {+ fetchImpl?: typeof fetch;+ env?: BuildEnv;+ sleep?: (ms: number) => Promise<void>;+ } = {},): Promise<ReleaseNote[]> {const markdown = readChangelog();if (markdown === null) return [];@@ -306,6 +441,7 @@ export async function loadStableReleases(dateLimit: DATE_LIMIT,changelogTags,fetchImpl: deps.fetchImpl ?? fetch,+ sleep: deps.sleep,});const changelogReleases = parseChangelog(markdown, feed.dates);if (changelogReleases.length === 0) {@@ -313,6 +449,10 @@ export async function loadStableReleases(`[changelog] CHANGELOG.md at ${CHANGELOG_PATH} has no \`## X.Y.Z\` sections — malformed or empty.`,);}- const releases = mergeReleaseNotes(changelogReleases, releaseNotesFrom(feed), feed.dates);+ const releases = mergeReleaseNotes(+ changelogReleases,+ releaseNotesFrom(feed, deps.env ?? process.env),+ feed.dates,+ );return Number.isFinite(limit) ? releases.slice(0, limit) : releases;}diff --git a/packages/app/package.json b/packages/app/package.jsonindex d7b5735d5..dd7b9da35 100644--- a/packages/app/package.json+++ b/packages/app/package.json@@ -1,6 +1,6 @@{"name": "@inkeep/open-knowledge-app",- "version": "0.86.18",+ "version": "0.0.0-unknown","license": "GPL-3.0-or-later","private": true,"type": "module",diff --git a/packages/app/src/build/app-version.test.ts b/packages/app/src/build/app-version.test.tsindex 67a01862d..f29fab573 100644--- a/packages/app/src/build/app-version.test.ts+++ b/packages/app/src/build/app-version.test.ts@@ -1,5 +1,6 @@-import { readFileSync } from 'node:fs';-import { dirname, resolve } from 'node:path';+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { dirname, join, resolve } from 'node:path';import { fileURLToPath } from 'node:url';import { CLIENT_RUNTIME_VERSION_FALLBACK } from '@inkeep/open-knowledge-core';import { loadConfigFromFile } from 'vite';@@ -25,11 +26,30 @@ describe('the unresolved-version sentinel', () => {});describe('resolveAppVersion', () => {- test('returns the real packages/app/package.json version, not a sentinel', () => {- const version = resolveAppVersion();- expect(version).toBe(appPkgVersion);- expect(version).not.toBe('dev');- expect(version).not.toBe(APP_VERSION_UNKNOWN);+ let fixtureDir = '';+ beforeEach(() => {+ fixtureDir = mkdtempSync(join(tmpdir(), 'ok-app-version-'));+ });+ afterEach(() => rmSync(fixtureDir, { recursive: true, force: true }));++ test('reads packages/app/package.json by default', () => {+ expect(resolveAppVersion()).toBe(appPkgVersion);+ });++ test('returns the version a package.json carries, not the sentinel', () => {+ const pkgPath = join(fixtureDir, 'package.json');+ writeFileSync(pkgPath, JSON.stringify({ name: 'fixture', version: '1.2.3-beta.4' }));+ expect(resolveAppVersion(pkgPath)).toBe('1.2.3-beta.4');+ });++ test('falls back to the sentinel when the package.json is missing, unparseable or versionless', () => {+ expect(resolveAppVersion(join(fixtureDir, 'absent.json'))).toBe(APP_VERSION_UNKNOWN);+ const broken = join(fixtureDir, 'broken.json');+ writeFileSync(broken, '{');+ expect(resolveAppVersion(broken)).toBe(APP_VERSION_UNKNOWN);+ const versionless = join(fixtureDir, 'versionless.json');+ writeFileSync(versionless, JSON.stringify({ name: 'fixture', version: '' }));+ expect(resolveAppVersion(versionless)).toBe(APP_VERSION_UNKNOWN);});});diff --git a/packages/app/src/build/app-version.ts b/packages/app/src/build/app-version.tsindex cbfec6da3..c12f7e582 100644--- a/packages/app/src/build/app-version.ts+++ b/packages/app/src/build/app-version.ts@@ -6,10 +6,15 @@ export const APP_VERSION_ENV_VAR = 'VITE_APP_VERSION';export const APP_VERSION_UNKNOWN = '0.0.0-unknown';-export function resolveAppVersion(): string {+const APP_PACKAGE_JSON = resolve(+ dirname(fileURLToPath(import.meta.url)),+ '..',+ '..',+ 'package.json',+);++export function resolveAppVersion(pkgPath: string = APP_PACKAGE_JSON): string {try {- const here = dirname(fileURLToPath(import.meta.url));- const pkgPath = resolve(here, '..', '..', 'package.json');const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: unknown };if (typeof pkg.version === 'string' && pkg.version.length > 0) {return pkg.version;diff --git a/packages/cli/package.json b/packages/cli/package.jsonindex 5319da2e4..abb59bbd6 100644--- a/packages/cli/package.json+++ b/packages/cli/package.json@@ -1,6 +1,6 @@{"name": "@inkeep/open-knowledge",- "version": "0.86.18",+ "version": "0.0.0-unknown","description": "Local-first, agent-friendly Markdown knowledge base with a cross-platform CLI and web editor","keywords": ["knowledge-base",diff --git a/packages/core/package.json b/packages/core/package.jsonindex a7c270563..e6c79b1c3 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -1,6 +1,6 @@{"name": "@inkeep/open-knowledge-core",- "version": "0.86.18",+ "version": "0.0.0-unknown","license": "GPL-3.0-or-later","private": true,"type": "module",diff --git a/packages/desktop/package.json b/packages/desktop/package.jsonindex f8295502e..7dcd5e352 100644--- a/packages/desktop/package.json+++ b/packages/desktop/package.json@@ -1,7 +1,7 @@{"name": "@inkeep/open-knowledge-desktop","productName": "OpenKnowledge",- "version": "0.86.18",+ "version": "0.0.0-unknown","license": "GPL-3.0-or-later","homepage": "https://openknowledge.ai","author": {diff --git a/packages/plugin/package.json b/packages/plugin/package.jsonindex 502815a04..e6e2044cc 100644--- a/packages/plugin/package.json+++ b/packages/plugin/package.json@@ -1,6 +1,6 @@{"name": "@inkeep/open-knowledge-plugin",- "version": "0.3.1",+ "version": "0.0.0-unknown","license": "GPL-3.0-or-later","private": true}diff --git a/packages/server/package.json b/packages/server/package.jsonindex dcb2c408d..38d9ac5f8 100644--- a/packages/server/package.json+++ b/packages/server/package.json@@ -1,6 +1,6 @@{"name": "@inkeep/open-knowledge-server",- "version": "0.86.18",+ "version": "0.0.0-unknown","license": "GPL-3.0-or-later","private": true,"type": "module",diff --git a/packages/server/src/version-constants.test.ts b/packages/server/src/version-constants.test.tsindex 73772b3fd..594a5fa9a 100644--- a/packages/server/src/version-constants.test.ts+++ b/packages/server/src/version-constants.test.ts@@ -1,10 +1,40 @@+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { CLIENT_RUNTIME_VERSION_FALLBACK } from '@inkeep/open-knowledge-core';import { describe, expect, test } from 'vitest';-import { PROTOCOL_VERSION, RUNTIME_VERSION, STATE_SCHEMA_VERSION } from './version-constants.ts';+import {+ PROTOCOL_VERSION,+ RUNTIME_VERSION,+ readRuntimeVersion,+ STATE_SCHEMA_VERSION,+} from './version-constants.ts';describe('version-constants', () => {- test('RUNTIME_VERSION resolves from package.json (NOT the unknown sentinel)', () => {- expect(RUNTIME_VERSION).not.toBe('0.0.0-unknown');- expect(RUNTIME_VERSION).toMatch(/^\d+\.\d+\.\d+/);+ test('RUNTIME_VERSION is the version field of the neighbouring package.json', () => {+ const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {+ version: string;+ };+ expect(RUNTIME_VERSION).toBe(pkg.version);+ });++ test('a source checkout carries the unknown placeholder, which clients read as indeterminate', () => {+ expect(RUNTIME_VERSION).toBe(CLIENT_RUNTIME_VERSION_FALLBACK);+ });++ test('readRuntimeVersion reads a stamped version and falls back when the file is missing or unversioned', () => {+ const dir = mkdtempSync(join(tmpdir(), 'runtime-version-'));+ try {+ const stamped = join(dir, 'stamped.json');+ writeFileSync(stamped, JSON.stringify({ version: '0.87.0' }));+ expect(readRuntimeVersion(stamped)).toBe('0.87.0');+ const unversioned = join(dir, 'unversioned.json');+ writeFileSync(unversioned, JSON.stringify({ name: 'x' }));+ expect(readRuntimeVersion(unversioned)).toBe(CLIENT_RUNTIME_VERSION_FALLBACK);+ expect(readRuntimeVersion(join(dir, 'missing.json'))).toBe(CLIENT_RUNTIME_VERSION_FALLBACK);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }});test('PROTOCOL_VERSION is a positive integer', () => {diff --git a/packages/server/src/version-constants.ts b/packages/server/src/version-constants.tsindex e377e2eab..9de1e6bac 100644--- a/packages/server/src/version-constants.ts+++ b/packages/server/src/version-constants.ts@@ -4,10 +4,10 @@ import { fileURLToPath } from 'node:url';export { PROTOCOL_VERSION } from '@inkeep/open-knowledge-core';-function readRuntimeVersion(): string {+export function readRuntimeVersion(+ pkgPath = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'),+): string {try {- const here = dirname(fileURLToPath(import.meta.url));- const pkgPath = resolve(here, '..', 'package.json');const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8')) as { version?: unknown };if (typeof pkg.version === 'string' && pkg.version.length > 0) {return pkg.version;diff --git a/scripts/compute-next-beta.test.mjs b/scripts/compute-next-beta.test.mjsindex 8c9f91ec7..a2b162d6d 100644--- a/scripts/compute-next-beta.test.mjs+++ b/scripts/compute-next-beta.test.mjs@@ -675,15 +675,11 @@ describe('the compute-next-beta CLI numbers from the stable tags and reads onlyconst root = mkdtempSync(join(tmpdir(), 'compute-next-beta-cli-'));roots.push(root);mkdirSync(join(root, '.changeset'));- writeFileSync(- join(root, '.changeset', 'pre.json'),- JSON.stringify({ mode: 'pre', tag: 'beta', initialVersions: { [OK]: '0.81.4' }, changesets: [] }),- );writeFileSync(join(root, '.changeset', 'config.json'), JSON.stringify({ fixed: [[OK]] }));writeFileSync(join(root, 'package.json'), JSON.stringify({ name: 'fixture-root', private: true }));writeFileSync(join(root, 'pnpm-workspace.yaml'), 'packages:\n - packages/*\n');mkdirSync(join(root, 'packages', 'cli'), { recursive: true });- writeFileSync(join(root, 'packages', 'cli', 'package.json'), JSON.stringify({ name: OK, version: '0.81.4' }));+ writeFileSync(join(root, 'packages', 'cli', 'package.json'), JSON.stringify({ name: OK, version: '0.0.0-unknown' }));git(root, ['init', '-q', '-b', 'main']);configureTestGitRepository(root);const commit = (name, bump, body) => {@@ -764,7 +760,7 @@ describe('the compute-next-beta CLI numbers from the stable tags and reads onlyexpect(out.releaseNotes).toContain('<!-- ok-consumed-set: ["drafted","fixture-change"] -->');});- test('a draft newest stable keeps its changesets pending and the stale anchor in pre.json is ignored', () => {+ test('a draft newest stable keeps its changesets pending', () => {const fx = fixture();const res = run(fx, { ...previousBetaConsumed(['drafted', 'fixture-change']), ...publishedThrough12 });expect(res.status, res.stderr).toBe(0);diff --git a/scripts/compute-stable-version.mjs b/scripts/compute-stable-version.mjsindex 1e861f4b2..69b3fa5b4 100644--- a/scripts/compute-stable-version.mjs+++ b/scripts/compute-stable-version.mjs@@ -337,7 +337,6 @@ function main() {`stable_tag=${result.stableTag ?? ''}`,`beta_sha=${result.betaSha ?? ''}`,`latest_stable_sha=${result.latestStableSha ?? ''}`,- `delta_ids=${JSON.stringify(result.deltaIds ?? [])}`,`bump_verdicts=${serializeBumpVerdicts(verdicts)}`,];appendFileSync(process.env.GITHUB_OUTPUT, `${lines.join('\n')}\n`);diff --git a/scripts/render-stable-notes.mjs b/scripts/render-stable-notes.mjsindex 25b206090..81e2a9626 100644--- a/scripts/render-stable-notes.mjs+++ b/scripts/render-stable-notes.mjs@@ -108,7 +108,7 @@ export function readPublishedStableTags({ releasesFile = '' } = {}) {console.error(`::warning::render-stable-notes: could not read the published stable Releases (${err instanceof Error ? err.message : String(err)}). ` +'The notes count every stable tag as released, so they may leave out changesets first tagged in a stable ' +- 'whose Release never published, and they carry no notes-source marker; the docs keep CHANGELOG.md for this version.',+ 'whose Release never published, and they carry no notes-source marker; the docs changelog lists no entry for this version until the body carries one.',);return null;}diff --git a/scripts/render-stable-notes.test.mjs b/scripts/render-stable-notes.test.mjsindex 5e5f01ffe..ffa7c23ba 100644--- a/scripts/render-stable-notes.test.mjs+++ b/scripts/render-stable-notes.test.mjs@@ -150,7 +150,7 @@ describe('renderStableNotes', () => {expect(markedNotes(renderStableNotes([], { marked: true }))).toBeNull();});- test('a release with no entries says so and carries no marker, so the docs keep CHANGELOG.md', () => {+ test('a release with no entries says so and carries no marker', () => {expect(renderStableNotes([], { marked: true })).toBe(`${EMPTY_NOTES}\n`);});});diff --git a/turbo.json b/turbo.jsonindex ee8313149..84b5cefc0 100644--- a/turbo.json+++ b/turbo.json@@ -106,8 +106,10 @@"GITHUB_SHA","VERCEL_ENV","OK_ALLOW_BLOGLESS_LLMS_TXT",+ "OK_ALLOW_PARTIAL_CHANGELOG","CI",- "VERCEL"+ "VERCEL",+ "VERCEL_DEPLOYMENT_ID"]},"test": {