Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Retire the Open Knowledge main reset (PRD-9389) (#6540)

Andrew Mikofalvy3e5832d507f7
diff --git a/.changeset/README.md b/.changeset/README.md
index 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.json
deleted file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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.mjs
index 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.yml
index 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.yml
index 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 toolchain
run: |
@@ -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 pipefail
WRAPPER="${RUNNER_TEMP}/retry-transient.mjs"
WRAPPER_TMP="${WRAPPER}.tmp.$$"
diff --git a/.github/workflows/point-release.yml b/.github/workflows/point-release.yml
index 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: true
type: 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: string
resolve_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 release
if: inputs.dry_run == false
uses: ./.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" != "[]" ]]; then
echo "- **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.yml
index 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: read
concurrency:
@@ -484,73 +476,3 @@ jobs:
if [[ -n "$CHILD" ]]; then echo "- Run: ${CHILD}"; else echo "- (run link unresolved; open desktop-release.yml)"; fi
echo "- 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.yml
index 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 notes
if: 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 versions
run: |
diff --git a/.github/workflows/select-beta-to-promote.yml b/.github/workflows/select-beta-to-promote.yml
index 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: read
actions: 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.md
index 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.json
index 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.ts
index 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.ts
index 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.json
index 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.ts
index 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.ts
index 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.json
index 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.json
index 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.json
index 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.json
index 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.json
index 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.ts
index 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.ts
index 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.mjs
index 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 only
const 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 only
expect(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.mjs
index 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.mjs
index 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.mjs
index 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.json
index 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": {