Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(docs): perennial download redirects + CI-gated docs tests (#1807)

Andrew Mikofalvyde193db32c01
diff --git a/bun.lock b/bun.lock
index 8ca39f0e0..685f864ec 100644
--- a/bun.lock
+++ b/bun.lock
@@ -37,6 +37,7 @@
"zod": "^4.3.6",
},
"devDependencies": {
+ "@inkeep/open-knowledge-core": "workspace:*",
"@tailwindcss/postcss": "^4",
"@types/node": "^24.0.7",
"@types/react": "^19",
diff --git a/docs/package.json b/docs/package.json
index d795ff4d2..4816e4bc1 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -9,6 +9,7 @@
"build": "next build",
"prebuild": "bun validate-link",
"start": "next start --port 3010",
+ "test": "bun test src",
"typecheck": "next typegen && fumadocs-mdx && tsc --noEmit",
"validate-link": "bun scripts/validate-link.ts",
"generate:og-wordmark": "bun scripts/generate-og-wordmark.ts",
@@ -31,6 +32,7 @@
"zod": "^4.3.6"
},
"devDependencies": {
+ "@inkeep/open-knowledge-core": "workspace:*",
"@tailwindcss/postcss": "^4",
"@types/node": "^24.0.7",
"@types/react": "^19",
diff --git a/docs/src/app/download/beta/route.test.ts b/docs/src/app/download/beta/route.test.ts
new file mode 100644
index 000000000..457ecd12c
--- /dev/null
+++ b/docs/src/app/download/beta/route.test.ts
@@ -0,0 +1,52 @@
+import { describe, expect, mock, test } from 'bun:test';
+import {
+ type BetaRedirect,
+ FALLBACK_CACHE_CONTROL,
+ RELEASES_PAGE_URL,
+ SUCCESS_CACHE_CONTROL,
+} from '../../../lib/download-links.ts';
+
+const TEST_DMG_URL =
+ 'https://github.com/inkeep/open-knowledge/releases/download/v0.1.0-beta.1/Open-Knowledge-arm64.dmg';
+
+let _redirect: BetaRedirect = { kind: 'fresh', url: TEST_DMG_URL };
+
+mock.module('../../../lib/download-links.ts', () => ({
+ createBetaResolver: () => () => Promise.resolve(_redirect),
+ toRedirectResponse: (r: BetaRedirect): Response =>
+ new Response(null, {
+ status: 302,
+ headers: {
+ location: r.url,
+ 'cache-control': r.kind === 'fallback' ? FALLBACK_CACHE_CONTROL : SUCCESS_CACHE_CONTROL,
+ },
+ }),
+}));
+
+const { GET } = await import('./route.ts');
+
+describe('GET /download/beta', () => {
+ test('302 to the fresh beta URL with CDN-cacheable headers', async () => {
+ _redirect = { kind: 'fresh', url: TEST_DMG_URL };
+ const res = await GET();
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe(TEST_DMG_URL);
+ expect(res.headers.get('cache-control')).toBe(SUCCESS_CACHE_CONTROL);
+ });
+
+ test('302 to the stale LKG URL with CDN-cacheable headers', async () => {
+ _redirect = { kind: 'stale-lkg', url: TEST_DMG_URL, refreshError: 'network down' };
+ const res = await GET();
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe(TEST_DMG_URL);
+ expect(res.headers.get('cache-control')).toBe(SUCCESS_CACHE_CONTROL);
+ });
+
+ test('302 to the releases page uncached on fallback', async () => {
+ _redirect = { kind: 'fallback', url: RELEASES_PAGE_URL, cause: 'API error' };
+ const res = await GET();
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe(RELEASES_PAGE_URL);
+ expect(res.headers.get('cache-control')).toBe(FALLBACK_CACHE_CONTROL);
+ });
+});
diff --git a/docs/src/app/download/beta/route.ts b/docs/src/app/download/beta/route.ts
new file mode 100644
index 000000000..7d5b67819
--- /dev/null
+++ b/docs/src/app/download/beta/route.ts
@@ -0,0 +1,18 @@
+import { createBetaResolver, toRedirectResponse } from '@/lib/download-links';
+
+export const dynamic = 'force-dynamic';
+
+const resolveBetaRedirect = createBetaResolver();
+
+export async function GET(): Promise<Response> {
+ const redirect = await resolveBetaRedirect();
+ if (redirect.kind === 'stale-lkg') {
+ console.warn(
+ `[download/beta] serving stale LKG after refresh failure: ${redirect.refreshError}`,
+ );
+ }
+ if (redirect.kind === 'fallback') {
+ console.error(`[download/beta] falling back to releases page: ${redirect.cause}`);
+ }
+ return toRedirectResponse(redirect);
+}
diff --git a/docs/src/app/download/stable/route.test.ts b/docs/src/app/download/stable/route.test.ts
new file mode 100644
index 000000000..d286c801a
--- /dev/null
+++ b/docs/src/app/download/stable/route.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, test } from 'bun:test';
+import { STABLE_CACHE_CONTROL, STABLE_DMG_URL } from '../../../lib/download-links.ts';
+import { GET } from './route.ts';
+
+describe('GET /download/stable', () => {
+ test('302 to the stable DMG URL with CDN-cacheable headers', () => {
+ const res = GET();
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe(STABLE_DMG_URL);
+ expect(res.headers.get('cache-control')).toBe(STABLE_CACHE_CONTROL);
+ });
+});
diff --git a/docs/src/app/download/stable/route.ts b/docs/src/app/download/stable/route.ts
new file mode 100644
index 000000000..1a31829fd
--- /dev/null
+++ b/docs/src/app/download/stable/route.ts
@@ -0,0 +1,13 @@
+import { STABLE_CACHE_CONTROL, STABLE_DMG_URL } from '@/lib/download-links';
+
+export const dynamic = 'force-dynamic';
+
+export function GET(): Response {
+ return new Response(null, {
+ status: 302,
+ headers: {
+ location: STABLE_DMG_URL,
+ 'cache-control': STABLE_CACHE_CONTROL,
+ },
+ });
+}
diff --git a/docs/src/lib/download-links.test.ts b/docs/src/lib/download-links.test.ts
new file mode 100644
index 000000000..e75653118
--- /dev/null
+++ b/docs/src/lib/download-links.test.ts
@@ -0,0 +1,238 @@
+import { describe, expect, test } from 'bun:test';
+import {
+ createBetaResolver,
+ DMG_ASSET_NAME,
+ FALLBACK_CACHE_CONTROL,
+ pickLatestBetaDmgUrl,
+ RELEASES_PAGE_URL,
+ STABLE_DMG_URL,
+ SUCCESS_CACHE_CONTROL,
+ toRedirectResponse,
+} from './download-links.ts';
+
+function release(
+ tag: string,
+ opts: { draft?: boolean; prerelease?: boolean; assetNames?: string[]; assetHost?: string } = {},
+) {
+ const {
+ draft = false,
+ prerelease = true,
+ assetNames = [DMG_ASSET_NAME],
+ assetHost = 'https://github.com/inkeep/open-knowledge/releases/download',
+ } = opts;
+ return {
+ tag_name: tag,
+ draft,
+ prerelease,
+ assets: assetNames.map((name) => ({
+ name,
+ browser_download_url: `${assetHost}/${tag}/${name}`,
+ })),
+ };
+}
+
+function dmgUrl(tag: string) {
+ return `https://github.com/inkeep/open-knowledge/releases/download/${tag}/${DMG_ASSET_NAME}`;
+}
+
+function jsonResponse(payload: unknown, status = 200) {
+ return new Response(JSON.stringify(payload), { status });
+}
+
+describe('pickLatestBetaDmgUrl', () => {
+ test('picks the DMG from the first published beta (API order is newest-first)', () => {
+ const url = pickLatestBetaDmgUrl([
+ release('v0.12.0-beta.7'),
+ release('v0.12.0-beta.6'),
+ release('v0.11.0', { prerelease: false }),
+ ]);
+ expect(url).toBe(dmgUrl('v0.12.0-beta.7'));
+ });
+
+ test('skips stable releases even when they appear first', () => {
+ const url = pickLatestBetaDmgUrl([
+ release('v0.11.0', { prerelease: false }),
+ release('v0.11.0-beta.3'),
+ ]);
+ expect(url).toBe(dmgUrl('v0.11.0-beta.3'));
+ });
+
+ test('skips a beta whose DMG never uploaded and falls back to the previous one', () => {
+ const url = pickLatestBetaDmgUrl([
+ release('v0.12.0-beta.7', { assetNames: ['beta-mac.yml'] }),
+ release('v0.12.0-beta.6'),
+ ]);
+ expect(url).toBe(dmgUrl('v0.12.0-beta.6'));
+ });
+
+ test('skips drafts', () => {
+ const url = pickLatestBetaDmgUrl([
+ release('v0.12.0-beta.7', { draft: true }),
+ release('v0.12.0-beta.6'),
+ ]);
+ expect(url).toBe(dmgUrl('v0.12.0-beta.6'));
+ });
+
+ test('skips prereleases that are not -beta.N tags', () => {
+ const url = pickLatestBetaDmgUrl([
+ release('v0.12.0-rc.1'),
+ release('beta-latest'),
+ release('v0.12.0-beta'),
+ release('v0.12.0-beta.6'),
+ ]);
+ expect(url).toBe(dmgUrl('v0.12.0-beta.6'));
+ });
+
+ test('rejects asset URLs outside our release-download prefix', () => {
+ const url = pickLatestBetaDmgUrl([
+ release('v0.12.0-beta.7', { assetHost: 'https://evil.example.com/releases/download' }),
+ release('v0.12.0-beta.6'),
+ ]);
+ expect(url).toBe(dmgUrl('v0.12.0-beta.6'));
+ });
+
+ test('returns null when no published beta carries the DMG', () => {
+ expect(pickLatestBetaDmgUrl([release('v0.11.0', { prerelease: false })])).toBeNull();
+ expect(pickLatestBetaDmgUrl([])).toBeNull();
+ });
+
+ test('returns null on malformed payloads instead of throwing', () => {
+ expect(pickLatestBetaDmgUrl(null)).toBeNull();
+ expect(pickLatestBetaDmgUrl({ message: 'API rate limit exceeded' })).toBeNull();
+ expect(pickLatestBetaDmgUrl([{ tag_name: 42 }])).toBeNull();
+ });
+});
+
+describe('createBetaResolver', () => {
+ test('resolves fresh, then serves from LKG without refetching inside the TTL', async () => {
+ let clock = 0;
+ let calls = 0;
+ const resolve = createBetaResolver({
+ fetchImpl: async () => {
+ calls++;
+ return jsonResponse([release('v0.12.0-beta.7')]);
+ },
+ now: () => clock,
+ });
+
+ expect(await resolve()).toEqual({ kind: 'fresh', url: dmgUrl('v0.12.0-beta.7') });
+ clock = 299_000;
+ expect(await resolve()).toEqual({ kind: 'cached', url: dmgUrl('v0.12.0-beta.7') });
+ expect(calls).toBe(1);
+ });
+
+ test('refetches after the TTL and picks up a newer beta', async () => {
+ let clock = 0;
+ const payloads = [[release('v0.12.0-beta.7')], [release('v0.12.0-beta.8')]];
+ let calls = 0;
+ const resolve = createBetaResolver({
+ fetchImpl: async () => jsonResponse(payloads[calls++]),
+ now: () => clock,
+ });
+
+ expect(await resolve()).toEqual({ kind: 'fresh', url: dmgUrl('v0.12.0-beta.7') });
+ clock = 300_000;
+ expect(await resolve()).toEqual({ kind: 'fresh', url: dmgUrl('v0.12.0-beta.8') });
+ expect(calls).toBe(2);
+ });
+
+ test('serves the stale LKG when the refresh fails', async () => {
+ let clock = 0;
+ let calls = 0;
+ const resolve = createBetaResolver({
+ fetchImpl: async () => {
+ calls++;
+ if (calls === 1) return jsonResponse([release('v0.12.0-beta.7')]);
+ throw new Error('network down');
+ },
+ now: () => clock,
+ });
+
+ await resolve();
+ clock = 10_000_000;
+ const result = await resolve();
+ expect(result.kind).toBe('stale-lkg');
+ expect(result.url).toBe(dmgUrl('v0.12.0-beta.7'));
+ if (result.kind === 'stale-lkg') {
+ expect(result.refreshError).toBe('network down');
+ }
+ });
+
+ test('falls back to the releases page when the API errors and no LKG exists', async () => {
+ const resolve = createBetaResolver({
+ fetchImpl: async () => jsonResponse({ message: 'rate limited' }, 403),
+ now: () => 0,
+ });
+ const result = await resolve();
+ expect(result.kind).toBe('fallback');
+ expect(result.url).toBe(RELEASES_PAGE_URL);
+ if (result.kind === 'fallback') {
+ expect(result.cause).toContain('403');
+ }
+ });
+
+ test('falls back when the API succeeds but no qualifying beta exists', async () => {
+ const resolve = createBetaResolver({
+ fetchImpl: async () => jsonResponse([release('v0.11.0', { prerelease: false })]),
+ now: () => 0,
+ });
+ const result = await resolve();
+ expect(result.kind).toBe('fallback');
+ expect(result.url).toBe(RELEASES_PAGE_URL);
+ });
+
+ test('falls back when fetch itself rejects and no LKG exists', async () => {
+ const resolve = createBetaResolver({
+ fetchImpl: async () => {
+ throw new Error('ECONNRESET');
+ },
+ now: () => 0,
+ });
+ const result = await resolve();
+ expect(result.kind).toBe('fallback');
+ if (result.kind === 'fallback') {
+ expect(result.cause).toBe('ECONNRESET');
+ }
+ });
+});
+
+describe('toRedirectResponse', () => {
+ test('success kinds redirect with the CDN-cacheable header', () => {
+ for (const kind of ['fresh', 'cached'] as const) {
+ const res = toRedirectResponse({ kind, url: dmgUrl('v0.12.0-beta.7') });
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe(dmgUrl('v0.12.0-beta.7'));
+ expect(res.headers.get('cache-control')).toBe(SUCCESS_CACHE_CONTROL);
+ }
+ });
+
+ test('stale-lkg kind redirects with the CDN-cacheable header', () => {
+ const res = toRedirectResponse({
+ kind: 'stale-lkg',
+ url: dmgUrl('v0.12.0-beta.7'),
+ refreshError: 'network down',
+ });
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe(dmgUrl('v0.12.0-beta.7'));
+ expect(res.headers.get('cache-control')).toBe(SUCCESS_CACHE_CONTROL);
+ });
+
+ test('fallback redirects to the releases page uncached', () => {
+ const res = toRedirectResponse({
+ kind: 'fallback',
+ url: RELEASES_PAGE_URL,
+ cause: 'GitHub releases API responded 502',
+ });
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe(RELEASES_PAGE_URL);
+ expect(res.headers.get('cache-control')).toBe(FALLBACK_CACHE_CONTROL);
+ });
+});
+
+describe('STABLE_DMG_URL', () => {
+ test('targets the GitHub latest alias with the shared asset name', () => {
+ expect(STABLE_DMG_URL).toBe(
+ `https://github.com/inkeep/open-knowledge/releases/latest/download/${DMG_ASSET_NAME}`,
+ );
+ });
+});
diff --git a/docs/src/lib/download-links.ts b/docs/src/lib/download-links.ts
new file mode 100644
index 000000000..4cecc9a56
--- /dev/null
+++ b/docs/src/lib/download-links.ts
@@ -0,0 +1,127 @@
+import { z } from 'zod';
+
+const RELEASES_API_URL = 'https://api.github.com/repos/inkeep/open-knowledge/releases?per_page=15';
+
+export const DMG_ASSET_NAME = 'Open-Knowledge-arm64.dmg';
+
+export const STABLE_DMG_URL = `https://github.com/inkeep/open-knowledge/releases/latest/download/${DMG_ASSET_NAME}`;
+
+export const RELEASES_PAGE_URL = 'https://github.com/inkeep/open-knowledge/releases';
+
+const ASSET_URL_PREFIX = 'https://github.com/inkeep/open-knowledge/releases/download/';
+
+const BETA_TAG_PATTERN = /^v\d+\.\d+\.\d+-beta\.\d+$/;
+
+const LKG_TTL_MS = 300_000;
+
+const releasesSchema = z.array(
+ z.object({
+ tag_name: z.string(),
+ draft: z.boolean(),
+ prerelease: z.boolean(),
+ assets: z.array(
+ z.object({
+ name: z.string(),
+ browser_download_url: z.string(),
+ }),
+ ),
+ }),
+);
+
+export function pickLatestBetaDmgUrl(payload: unknown): string | null {
+ const parsed = releasesSchema.safeParse(payload);
+ if (!parsed.success) {
+ console.warn(
+ `[download-links] releases payload failed schema validation: ${parsed.error.message}`,
+ );
+ return null;
+ }
+
+ for (const release of parsed.data) {
+ if (release.draft || !release.prerelease) continue;
+ if (!BETA_TAG_PATTERN.test(release.tag_name)) continue;
+ const dmg = release.assets.find(
+ (asset) =>
+ asset.name === DMG_ASSET_NAME && asset.browser_download_url.startsWith(ASSET_URL_PREFIX),
+ );
+ if (dmg) return dmg.browser_download_url;
+ }
+ return null;
+}
+
+export type BetaRedirect =
+ | { kind: 'fresh' | 'cached'; url: string }
+ | { kind: 'stale-lkg'; url: string; refreshError: string }
+ | { kind: 'fallback'; url: string; cause: string };
+
+function describeError(err: unknown): string {
+ if (!(err instanceof Error)) return String(err);
+ if (err.cause === undefined) return err.message;
+ const cause = err.cause instanceof Error ? err.cause.message : String(err.cause);
+ return `${err.message} [cause: ${cause}]`;
+}
+
+export function createBetaResolver(
+ deps: { fetchImpl?: typeof fetch; now?: () => number } = {},
+): () => Promise<BetaRedirect> {
+ const fetchImpl = deps.fetchImpl ?? fetch;
+ const now = deps.now ?? Date.now;
+ let lkg: { url: string; fetchedAt: number } | null = null;
+
+ return async function resolveBetaRedirect(): Promise<BetaRedirect> {
+ if (lkg && now() - lkg.fetchedAt < LKG_TTL_MS) {
+ return { kind: 'cached', url: lkg.url };
+ }
+ try {
+ const res = await fetchImpl(RELEASES_API_URL, {
+ signal: AbortSignal.timeout(5_000),
+ headers: {
+ accept: 'application/vnd.github+json',
+ 'user-agent': 'openknowledge.ai download redirect',
+ },
+ });
+ if (!res.ok) {
+ throw new Error(`GitHub releases API responded ${res.status}`);
+ }
+ let payload: unknown;
+ try {
+ payload = await res.json();
+ } catch (parseErr) {
+ throw new Error(`GitHub releases API returned non-JSON body (status ${res.status})`, {
+ cause: parseErr,
+ });
+ }
+ const url = pickLatestBetaDmgUrl(payload);
+ if (!url) {
+ throw new Error('no published beta release carries the DMG asset');
+ }
+ lkg = { url, fetchedAt: now() };
+ return { kind: 'fresh', url };
+ } catch (err) {
+ const refreshError = describeError(err);
+ if (lkg) return { kind: 'stale-lkg', url: lkg.url, refreshError };
+ return {
+ kind: 'fallback',
+ url: RELEASES_PAGE_URL,
+ cause: refreshError,
+ };
+ }
+ };
+}
+
+export const SUCCESS_CACHE_CONTROL = 'public, max-age=0, s-maxage=300, stale-while-revalidate=3600';
+
+export const FALLBACK_CACHE_CONTROL = 'no-store';
+
+export const STABLE_CACHE_CONTROL = 'public, max-age=0, s-maxage=3600';
+
+export function toRedirectResponse(redirect: BetaRedirect): Response {
+ return new Response(null, {
+ status: 302,
+ headers: {
+ location: redirect.url,
+ 'cache-control':
+ redirect.kind === 'fallback' ? FALLBACK_CACHE_CONTROL : SUCCESS_CACHE_CONTROL,
+ },
+ });
+}
diff --git a/knip.config.ts b/knip.config.ts
index c8fc579ba..f355182ac 100644
--- a/knip.config.ts
+++ b/knip.config.ts
@@ -62,9 +62,6 @@ export default {
'packages/desktop/src/shared/ipc-channels.ts': ['types'],
'packages/app/src/lib/desktop-bridge-types.ts': ['types'],
'packages/server/src/share/git-context.ts': ['types'],
- 'docs/src/app/d/[encoded]/opengraph-image.test.ts': ['files'],
- 'docs/src/lib/share-splash.test.ts': ['files'],
- 'docs/src/middleware.test.ts': ['files'],
'packages/server/src/git-preflight.ts': ['exports'],
'packages/cli/src/commands/diagnose-health.ts': ['exports'],
'packages/cli/src/commands/diagnose-health-checks/git.ts': ['exports'],
@@ -100,7 +97,7 @@ export default {
project: 'src/**',
},
docs: {
- entry: ['source.config.ts'],
+ entry: ['source.config.ts', 'src/**/*.test.{ts,tsx}'],
},
'packages/server': {
entry: ['src/**/*.test.ts'],
diff --git a/packages/desktop/electron-builder.yml b/packages/desktop/electron-builder.yml
index 3770584c8..906f8d486 100644
--- a/packages/desktop/electron-builder.yml
+++ b/packages/desktop/electron-builder.yml
@@ -243,6 +243,10 @@ dmg:
# actual asset is `Open-Knowledge-0.4.1-arm64.dmg`. The arch suffix stays
# because we only ship arm64 today; an x64 / universal build would need
# a parallel artifactName + a splash decision rule.
+ # The docs site's /download/beta and /download/stable redirects also
+ # reference this exact asset name via DMG_ASSET_NAME in
+ # docs/src/lib/download-links.ts — changing the pattern breaks both
+ # routes and the share-splash URL together.
artifactName: ${productName}-${arch}.${ext}
title: ${productName}
# The "drag me to Applications" arrow and branding are painted INTO the