Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
feat(docs): perennial download redirects + CI-gated docs tests (#1807)
Andrew Mikofalvyde193db32c01
diff --git a/bun.lock b/bun.lockindex 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.jsonindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.ymlindex 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