Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
fix(open-knowledge): serve content assets from every server by default (#2650)
Andrew Mikofalvyf99af3083818
diff --git a/.changeset/serve-content-assets-by-default.md b/.changeset/serve-content-assets-by-default.mdnew file mode 100644index 000000000..a6a3fbdf5--- /dev/null+++ b/.changeset/serve-content-assets-by-default.md@@ -0,0 +1,5 @@+---+"@inkeep/open-knowledge": patch+---++Inline images now render in desktop windows attached to a server the desktop did not spawn (MCP-autostarted or terminal `ok start`). Every server now serves content-directory assets (images, video, audio, PDF, file attachments) at their `/<contentDir-relative>` paths by default, through the same admission middleware `ok ui` uses (inline/attachment dispatch, fail-closed 404 for missing assets). Previously only desktop-spawned servers passed `--serve-content-assets`, so a desktop window attaching to an MCP-spawned server resolved image srcs against an origin that 404'd them, showing broken images for every inline image in the project. The flag is still accepted for compatibility; pass `serveContentAssets: false` to `bootServer` to opt out. Servers that don't serve the React shell keep the `ok ui` pointer hint in their catch-all 404.diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.tsindex 7ee52e3c7..fbb1fa116 100644--- a/packages/cli/src/commands/start.test.ts+++ b/packages/cli/src/commands/start.test.ts@@ -1213,13 +1213,16 @@ describe('bootStartServer (integration)', () => {for (const c of captured) expect(c.reclaimDisableEnv).toBeNull();});- // --- single-origin opt-ins (--serve-content-assets, --react-shell-dist-dir) ---+ // --- content-asset serving (default-on) + --react-shell-dist-dir opt-in ---- test('serveContentAssets: false (default) — content paths return the SPA-pointer 404', async () => {- // Pre-seed a real asset in the content directory. With serveContentAssets- // off, the server has no /<contentDir-relative> middleware and the request- // falls through to the "React UI is served by `ok ui`" pointer.- writeFileSync(join(tmpDir, 'fixture-asset.png'), 'fake-png-bytes', 'utf-8');+ test('default — content assets are served from the server origin', async () => {+ // Nested path mirrors the attach-mode desktop shape: the renderer rewrites+ // `/<contentDir-relative>` inline-image srcs onto the lock holder's origin,+ // so a server booted with NO flags (MCP-autostarted, terminal `ok start`)+ // must serve them or attached windows render broken images.+ const assetBytes = `fake-png-bytes-${Math.random()}`;+ mkdirSync(join(tmpDir, 'specs', 'nested'), { recursive: true });+ writeFileSync(join(tmpDir, 'specs', 'nested', 'mockup.png'), assetBytes, 'utf-8');booted = await bootStartServer({config: makeTestConfig(),@@ -1229,18 +1232,18 @@ describe('bootStartServer (integration)', () => {skipUiAutoSpawn: true,});- const res = await fetchText(booted.port, '/fixture-asset.png');- expect(res.status).toBe(404);- const body = JSON.parse(res.body);- expect(body.detail).toContain('React UI is served by `ok ui`');+ const res = await fetchText(booted.port, '/specs/nested/mockup.png');+ expect(res.status).toBe(200);+ expect(res.body).toBe(assetBytes);+ // PNGs are inline-renderable; Content-Disposition should be inline.+ const disposition = res.headers['content-disposition'];+ expect(typeof disposition === 'string' ? disposition : '').toContain('inline');});- test('serveContentAssets: true — content asset is served from the server origin', async () => {- // Real fixture; serveContentAssets installs createAssetServeMiddleware- // over the content directory, so the same path now returns 200 with the- // file bytes (Content-Disposition: inline for image extensions).- const assetBytes = `fake-png-bytes-${Math.random()}`;- writeFileSync(join(tmpDir, 'fixture-asset.png'), assetBytes, 'utf-8');+ test('serveContentAssets: false — content paths return the SPA-pointer 404', async () => {+ // Explicit opt-out: no /<contentDir-relative> middleware, so the request+ // falls through to the "React UI is served by `ok ui`" pointer.+ writeFileSync(join(tmpDir, 'fixture-asset.png'), 'fake-png-bytes', 'utf-8');booted = await bootStartServer({config: makeTestConfig(),@@ -1248,15 +1251,13 @@ describe('bootStartServer (integration)', () => {host: TEST_HOST,skipAutoInit: true,skipUiAutoSpawn: true,- serveContentAssets: true,+ serveContentAssets: false,});const res = await fetchText(booted.port, '/fixture-asset.png');- expect(res.status).toBe(200);- expect(res.body).toBe(assetBytes);- // PNGs are inline-renderable; Content-Disposition should be inline.- const disposition = res.headers['content-disposition'];- expect(typeof disposition === 'string' ? disposition : '').toContain('inline');+ expect(res.status).toBe(404);+ const body = JSON.parse(res.body);+ expect(body.detail).toContain('React UI is served by `ok ui`');});test('reactShellDistDir — server serves the shell on /, auto-suppresses ok ui sibling', async () => {diff --git a/packages/cli/src/commands/start.ts b/packages/cli/src/commands/start.tsindex add4d2876..368db5f98 100644--- a/packages/cli/src/commands/start.ts+++ b/packages/cli/src/commands/start.ts@@ -691,14 +691,15 @@ interface BootStartServerOptions {logger?: (event: { event: string }) => void;}) => Promise<unknown> | unknown;/**- * When `true`, the server serves content-directory assets- * (images/video/PDF/file attachments) at their `/<contentDir-relative>`- * paths via `createAssetServeMiddleware` — matching the Vite dev plugin- * and `ok ui`. Off by default — terminal-launched `ok start` relies on- * the `ok ui` sibling for asset serving. The OpenKnowledge desktop- * passes this when spawning the detached server so its renderer can- * fetch assets from the same origin as `/api/*` and `/collab*`. Forwards- * directly to `BootServerOptions.serveContentAssets`.+ * When `true` (the `bootServer` default), the server serves+ * content-directory assets (images/video/PDF/file attachments) at their+ * `/<contentDir-relative>` paths via `createAssetServeMiddleware` —+ * matching the Vite dev plugin and `ok ui`. On by default so a desktop+ * window that ATTACHES to this server (MCP-autostarted or terminal+ * `ok start` — its renderer fetches assets from the same origin as+ * `/api/*` and `/collab*`) renders inline images; the `ok ui` sibling+ * still serves assets for browser mode. Forwards directly to+ * `BootServerOptions.serveContentAssets`.*/serveContentAssets?: boolean;/**@@ -1041,9 +1042,12 @@ export async function bootStartServer(opts: BootStartServerOptions): Promise<Booreturn withIdleShutdownProcessExit(reaped, { log, exit: opts.idleExit });},log,- // Single-origin opt-ins for desktop-spawned servers. Forwarded only- // when set so terminal `ok start` retains today's two-process behavior.- ...(opts.serveContentAssets ? { serveContentAssets: true } : {}),+ // Content assets serve by default (bootServer default-on); the React+ // shell stays a desktop-spawn opt-in so terminal `ok start` retains the+ // two-process shell model (`ok ui` sibling).+ ...(opts.serveContentAssets !== undefined+ ? { serveContentAssets: opts.serveContentAssets }+ : {}),...(opts.reactShellDistDir ? { reactShellDistDir: opts.reactShellDistDir } : {}),});@@ -1114,7 +1118,11 @@ interface StartCommandOptions {open?: boolean;/** From `--mode`: undefined (default → browser) | 'browser' | 'app'. */mode?: StartMode;- /** From `--serve-content-assets`. See `BootStartServerOptions.serveContentAssets`. */+ /**+ * From `--serve-content-assets`. Redundant now that `bootServer` defaults+ * the surface on; accepted for compatibility with older desktop spawners+ * that still pass the flag. See `BootStartServerOptions.serveContentAssets`.+ */serveContentAssets?: boolean;/** From `--react-shell-dist-dir <path>`. See `BootStartServerOptions.reactShellDistDir`. */reactShellDistDir?: string;@@ -1260,7 +1268,9 @@ export async function runStartCommand(config: Config, opts: StartCommandOptions)host,port,...(requestedUiPort !== undefined ? { uiPort: requestedUiPort } : {}),- ...(opts.serveContentAssets ? { serveContentAssets: true } : {}),+ ...(opts.serveContentAssets !== undefined+ ? { serveContentAssets: opts.serveContentAssets }+ : {}),...(opts.reactShellDistDir ? { reactShellDistDir: opts.reactShellDistDir } : {}),...(opts.singleFile ? { singleFile: opts.singleFile } : {}),...(opts.projectDir ? { projectDir: opts.projectDir } : {}),@@ -1471,7 +1481,10 @@ export function startCommand(getConfig: () => Config): Command {.option('-H, --host <host>', 'Server host', undefined).option('--open', 'Open browser after start').option('--mode <mode>', "Force dispatch mode: 'browser' or 'app'", parseStartMode)- .option('--serve-content-assets', 'Serve content assets from this server')+ .option(+ '--serve-content-assets',+ 'Serve content assets from this server (now the default; kept for compatibility)',+ ).option('--react-shell-dist-dir <path>','Serve React shell from <path> (suppresses ok ui sibling)',diff --git a/packages/server/src/boot.ts b/packages/server/src/boot.tsindex 95082dc4a..8865647d5 100644--- a/packages/server/src/boot.ts+++ b/packages/server/src/boot.ts@@ -238,17 +238,20 @@ export interface BootServerOptions/*** Serve content-directory assets (images / video / audio / PDF / file* attachments) over this HTTP server, mirroring the `bun run dev` Vite- * plugin and `ok ui`. Default `false`.+ * plugin and `ok ui`. Default `true`; pass `false` to opt out (tests+ * that pin the no-middleware surface).*- * The Electron utility sets this `true`: the BrowserWindow renderer- * page origin (a Vite dev URL or a `file://` path) has no asset middleware,- * so server-absolute `/<contentDir-relative>` image srcs can't resolve- * there. With this on, the renderer rewrites those srcs onto- * `window.okDesktop.config.apiOrigin` (the utility server's origin), which- * serves them via `createAssetServeMiddleware` — the canonical primitive,- * so the inline/attachment policy + fail-closed 404 guard come for free.- * The CLI leaves it `false` — `ok ui` already serves content assets on its- * own port.+ * Default-on because the desktop renderer resolves server-absolute+ * `/<contentDir-relative>` image srcs against+ * `window.okDesktop.config.apiOrigin`, and attach-mode treats lock kind as+ * provenance-only — the desktop attaches to servers it did not spawn+ * (MCP-autostarted, user-run `ok start`). Every attachable server must+ * therefore expose the content-asset surface, or inline images 404 in+ * attach-mode windows. Serving is additive: the same bytes are already+ * reachable via `/api/asset`, and `createAssetServeMiddleware` — the+ * canonical primitive — brings the inline/attachment policy + fail-closed+ * 404 guard. `ok ui` continues to serve content assets on its own port for+ * browser mode; the React shell (`reactShellDistDir`) stays opt-in.*/serveContentAssets?: boolean;/**@@ -682,19 +685,22 @@ async function bootServerInner(opts: BootServerOptions): Promise<BootedServer> {httpServer.headersTimeout = 30_000;httpServer.requestTimeout = 60_000;- // Content-asset serving — desktop mode only. Reuses the canonical+ // Content-asset serving — default-on for every boot path so attach-mode+ // desktop windows resolve inline-image srcs against any lock holder (see+ // the `serveContentAssets` option doc). Reuses the canonical// `createAssetServeMiddleware` (STOP rule: serve-side asset admission goes// through this factory) so the inline/attachment Content-Disposition policy// + fail-closed 404 guard match the Vite dev plugin and `ok ui`.- const contentAssetMiddleware = opts.serveContentAssets- ? createAssetServeMiddleware({- contentFilter: serverInstance.contentFilter,- contentSirv: sirv(opts.contentDir, { dev: true, dotfiles: false }),- inlineExtensions: INLINE_RENDERABLE_EXTENSIONS,- assetExtensions: ASSET_EXTENSIONS,- blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,- })- : undefined;+ const contentAssetMiddleware =+ opts.serveContentAssets !== false+ ? createAssetServeMiddleware({+ contentFilter: serverInstance.contentFilter,+ contentSirv: sirv(opts.contentDir, { dev: true, dotfiles: false }),+ inlineExtensions: INLINE_RENDERABLE_EXTENSIONS,+ assetExtensions: ASSET_EXTENSIONS,+ blocklistExtensions: EXECUTABLE_BLOCKLIST_EXTENSIONS,+ })+ : undefined;// When serving the React shell, try to advertise via `ui.lock` so external// preview-URL consumers find our port. If a live holder already owns thediff --git a/packages/server/src/mcp-mount.ts b/packages/server/src/mcp-mount.tsindex da70f0977..d46fc019a 100644--- a/packages/server/src/mcp-mount.ts+++ b/packages/server/src/mcp-mount.ts@@ -344,9 +344,17 @@ export function mountMcpAndApi(opts: MountMcpAndApiOptions): MountMcpAndApiHandlrunMiddleware(reactShellMiddleware, 'react-shell', onMiss);const notFound = (): void => {if (res.writableEnded || res.headersSent) return;+ // When this server doesn't serve the React shell (CLI / MCP-spawned —+ // content assets mount by default but the UI lives on the `ok ui`+ // sibling), keep the operator hint so a human loading `/` in a browser+ // is pointed at the right port.+ const uiHint =+ reactShellMiddleware === undefined+ ? 'The React UI is served by `ok ui` (run `ok ui` and check `ui.lock.port`). '+ : '';errorResponse(res, 404, 'urn:ok:error:not-found', 'Not found.', {handler: 'mcp-mount',- detail: `No handler for ${url ?? '/'}`,+ detail: `${uiHint}No handler for ${url ?? '/'}`,});};