fix(serve): embed admin/dist into binary; serve from manifest (closes #1090)

Pre-fix, /admin returned 404 on every globally-installed binary because
serve-http.ts:780 resolved admin/dist via process.cwd(). The admin SPA
files are checked into git but `bun build --compile` does NOT embed
arbitrary directories — only assets imported via `with { type: 'file' }`
ESM imports land in the compiled binary.

Wire:

- scripts/build-admin-embedded.ts walks admin/dist/, emits
  src/admin-embedded.ts with one `with { type: 'file' }` import per
  file + a manifest map (request path → resolved path + mime).
  Auto-invoked by `bun run build:admin`.

- src/admin-embedded.ts is the auto-generated module. Bun resolves
  every file: import to a path that works at runtime inside the
  compiled binary (same pattern as src/core/chunkers/code.ts WASM
  imports).

- serve-http.ts switches to two-tier resolution: cwd-relative
  admin/dist for dev (Vite hot-rebuild), embedded manifest otherwise.
  Embedded path reads bytes lazily and caches per-asset for the
  lifetime of the process.

- scripts/check-admin-embedded.sh CI gate re-runs the generator and
  fails on drift (mirrors check-wasm-embedded.sh). PRs that rebuild
  admin/dist but forget to regenerate the embedded module fail loud.

- package.json wires build:admin-embedded + check:admin-embedded.

Closes #1090.

package.json

@@ -31,7 +31,8 @@
     "dev": "bun run src/cli.ts",
     "build": "bun build --compile --outfile bin/gbrain src/cli.ts",
     "build:all": "bun build --compile --target=bun-darwin-arm64 --outfile bin/gbrain-darwin-arm64 src/cli.ts && bun build --compile --target=bun-linux-x64 --outfile bin/gbrain-linux-x64 src/cli.ts",
-    "build:admin": "cd admin && bun run build",
+    "build:admin": "cd admin && bun run build && cd .. && bun run scripts/build-admin-embedded.ts",
+    "build:admin-embedded": "bun run scripts/build-admin-embedded.ts",
     "build:schema": "bash scripts/build-schema.sh",
     "build:llms": "bun run scripts/build-llms.ts",
     "build:pglite-snapshot": "bun run scripts/build-pglite-snapshot.ts",
@@ -61,6 +62,7 @@
     "check:progress": "scripts/check-progress-to-stdout.sh",
     "check:exports-count": "scripts/check-exports-count.sh",
     "check:admin-build": "scripts/check-admin-build.sh",
+    "check:admin-embedded": "scripts/check-admin-embedded.sh",
     "check:test-isolation": "scripts/check-test-isolation.sh",
     "postinstall": "command -v gbrain >/dev/null 2>&1 && gbrain apply-migrations --yes --non-interactive || echo '[gbrain] postinstall skipped. If installed via bun install -g github:...: run `gbrain doctor` and `gbrain apply-migrations --yes` manually. See https://github.com/garrytan/gbrain/issues/218' 1>&2",
     "prepublish:clawhub": "bun run build:all",

scripts/build-admin-embedded.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env bun
+/**
+ * Generates `src/admin-embedded.ts` from `admin/dist/*`.
+ *
+ * Why: `bun build --compile` does NOT embed arbitrary asset directories.
+ * The only way to ship a file inside a compiled binary is via an ESM
+ * `import x from './path' with { type: 'file' }` reference (which Bun
+ * resolves at runtime to a path that works inside the binary archive).
+ *
+ * Pre-v0.36.x, `serve-http.ts:780` resolved `admin/dist/` via
+ * `process.cwd()` — fine in dev (`cd ~/gbrain && bun start serve --http`),
+ * broken in every globally-installed binary (no admin/dist next to the
+ * binary). Result: every fresh `bun install -g github:garrytan/gbrain`
+ * user got 404 on /admin (issue #1090).
+ *
+ * This generator emits one `import` line per file under admin/dist/,
+ * plus a manifest map keyed by the request path the express handler
+ * sees (e.g. `/admin/index.html`, `/admin/assets/index-XXX.js`).
+ *
+ * Run: `bun run scripts/build-admin-embedded.ts` (also invoked by
+ * `bun run build:admin`).
+ *
+ * CI guard: `scripts/check-admin-embedded.sh` re-runs this generator
+ * and `git diff --exit-code src/admin-embedded.ts` so PRs that change
+ * admin/dist without regenerating the embedded module fail loud.
+ */
+
+import { readdirSync, statSync, writeFileSync, existsSync, readFileSync } from 'fs';
+import { join, relative, posix } from 'path';
+
+const REPO = join(import.meta.dir, '..');
+const DIST = join(REPO, 'admin', 'dist');
+const OUT = join(REPO, 'src', 'admin-embedded.ts');
+
+function walk(dir: string, base: string = dir): string[] {
+  if (!existsSync(dir)) return [];
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) {
+      out.push(...walk(full, base));
+    } else {
+      out.push(relative(base, full));
+    }
+  }
+  return out.sort();
+}
+
+const MIME: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.txt': 'text/plain; charset=utf-8',
+  '.map': 'application/json; charset=utf-8',
+};
+
+function mimeFor(filename: string): string {
+  const dot = filename.lastIndexOf('.');
+  if (dot === -1) return 'application/octet-stream';
+  return MIME[filename.slice(dot).toLowerCase()] ?? 'application/octet-stream';
+}
+
+function safeIdent(rel: string, idx: number): string {
+  // Stable, collision-free identifier per relative path. The numeric
+  // suffix prevents collisions between filenames that normalize to the
+  // same identifier (e.g. `foo.bar.js` and `foo-bar.js`).
+  const cleaned = rel.replace(/[^a-zA-Z0-9]/g, '_').replace(/^_+/, '');
+  return `A_${idx}_${cleaned}`;
+}
+
+const files = walk(DIST);
+if (files.length === 0) {
+  console.error('[build-admin-embedded] no files under admin/dist — run `cd admin && bun run build` first.');
+  process.exit(1);
+}
+
+const imports: string[] = [];
+const manifestEntries: string[] = [];
+
+for (let i = 0; i < files.length; i++) {
+  const rel = files[i];
+  // POSIX-style relative path for the import (works on Windows too).
+  const importRel = `../admin/dist/${rel.split(/[\\/]/).join('/')}`;
+  const ident = safeIdent(rel, i);
+  // @ts-ignore — `with { type: 'file' }` is Bun syntax not in lib.d.ts;
+  // same pattern as src/core/chunkers/code.ts wasm imports.
+  imports.push(`// @ts-ignore — type: 'file' is Bun ESM, not in lib.d.ts`);
+  imports.push(`import ${ident} from '${importRel}' with { type: 'file' };`);
+  const requestPath = '/admin/' + rel.split(/[\\/]/).join('/');
+  manifestEntries.push(`  ${JSON.stringify(requestPath)}: { path: ${ident} as unknown as string, mime: ${JSON.stringify(mimeFor(rel))} },`);
+}
+
+const content = `// AUTO-GENERATED — do not edit by hand.
+// Run \`bun run scripts/build-admin-embedded.ts\` to regenerate.
+// Source: admin/dist/ at ${new Date().toISOString().slice(0, 10)}.
+//
+// Bun resolves the file: imports to a path that works at runtime even
+// inside a compiled binary (\`bun build --compile\`). The manifest maps
+// the request path the express handler sees to (resolved-path, mime).
+
+${imports.join('\n')}
+
+export interface AdminAsset {
+  path: string;
+  mime: string;
+}
+
+export const ADMIN_ASSETS: Record<string, AdminAsset> = {
+${manifestEntries.join('\n')}
+};
+
+/** Index entry point for SPA fallback. */
+export const ADMIN_INDEX_HTML: AdminAsset = ADMIN_ASSETS['/admin/index.html'];
+
+export const ADMIN_ASSET_COUNT = ${files.length};
+`;
+
+const existing = existsSync(OUT) ? readFileSync(OUT, 'utf-8') : '';
+if (existing === content) {
+  console.log(`[build-admin-embedded] up to date (${files.length} files)`);
+} else {
+  writeFileSync(OUT, content, 'utf-8');
+  console.log(`[build-admin-embedded] wrote ${OUT} (${files.length} files)`);
+}

scripts/check-admin-embedded.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# CI gate: src/admin-embedded.ts must match admin/dist/ contents.
+#
+# This protects against the v0.36.x #1090 bug class re-emerging — a PR
+# that rebuilds admin/dist but forgets to regenerate src/admin-embedded.ts
+# would silently break /admin on every fresh install of the compiled
+# binary. The Vite build outputs hashed filenames, so a stale embedded
+# manifest references nonexistent assets.
+#
+# How: re-run the generator, then `git diff --exit-code` on the output.
+# Exits 0 when in sync, 1 when the generator produces different output
+# than what's committed.
+#
+# Mirrors scripts/check-wasm-embedded.sh's pattern.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+if [ ! -d admin/dist ]; then
+  echo "[check:admin-embedded] no admin/dist (run \`cd admin && bun run build\` first); skipping"
+  exit 0
+fi
+
+bun run scripts/build-admin-embedded.ts > /dev/null
+
+if ! git diff --exit-code -- src/admin-embedded.ts; then
+  echo ""
+  echo "[check:admin-embedded] src/admin-embedded.ts is out of sync with admin/dist/."
+  echo "  Fix: bun run build:admin && bun run build:admin-embedded"
+  echo "  Then re-commit the regenerated src/admin-embedded.ts."
+  exit 1
+fi
+
+echo "[check:admin-embedded] OK"

src/admin-embedded.ts

@@ -0,0 +1,30 @@
+// AUTO-GENERATED — do not edit by hand.
+// Run `bun run scripts/build-admin-embedded.ts` to regenerate.
+// Source: admin/dist/ at 2026-05-18.
+//
+// Bun resolves the file: imports to a path that works at runtime even
+// inside a compiled binary (`bun build --compile`). The manifest maps
+// the request path the express handler sees to (resolved-path, mime).
+
+// @ts-ignore — type: 'file' is Bun ESM, not in lib.d.ts
+import A_0_assets_index_BOifXQpQ_css from '../admin/dist/assets/index-BOifXQpQ.css' with { type: 'file' };
+// @ts-ignore — type: 'file' is Bun ESM, not in lib.d.ts
+import A_1_assets_index_CDv6_ml5_js from '../admin/dist/assets/index-CDv6_ml5.js' with { type: 'file' };
+// @ts-ignore — type: 'file' is Bun ESM, not in lib.d.ts
+import A_2_index_html from '../admin/dist/index.html' with { type: 'file' };
+
+export interface AdminAsset {
+  path: string;
+  mime: string;
+}
+
+export const ADMIN_ASSETS: Record<string, AdminAsset> = {
+  "/admin/assets/index-BOifXQpQ.css": { path: A_0_assets_index_BOifXQpQ_css as unknown as string, mime: "text/css; charset=utf-8" },
+  "/admin/assets/index-CDv6_ml5.js": { path: A_1_assets_index_CDv6_ml5_js as unknown as string, mime: "application/javascript; charset=utf-8" },
+  "/admin/index.html": { path: A_2_index_html as unknown as string, mime: "text/html; charset=utf-8" },
+};
+
+/** Index entry point for SPA fallback. */
+export const ADMIN_INDEX_HTML: AdminAsset = ADMIN_ASSETS['/admin/index.html'];
+
+export const ADMIN_ASSET_COUNT = 3;

src/commands/serve-http.ts

@@ -783,22 +783,64 @@ export async function runServeHttp(engine: BrainEngine, options: ServeHttpOption
   });
 
   // ---------------------------------------------------------------------------
-  // Admin SPA static files
+  // Admin SPA static files (v0.36.x #1090)
   // ---------------------------------------------------------------------------
-  // Serve from admin/dist if it exists (development), otherwise embedded assets
+  // Two-tier resolution:
+  //   1. Dev path — admin/dist next to cwd. Vite rebuilds land here first,
+  //      so devs hacking on the SPA see changes without re-running
+  //      build-admin-embedded.
+  //   2. Binary path — `src/admin-embedded.ts` exports `ADMIN_ASSETS`, a
+  //      manifest of request-path → resolved-path keyed by every file in
+  //      admin/dist at generation time. Bun's `with { type: 'file' }` ESM
+  //      imports resolve correctly inside the compiled binary, so a
+  //      globally-installed `gbrain serve --http` actually serves /admin
+  //      instead of 404. Pre-fix the cwd-relative path was the ONLY
+  //      resolution path, and every fresh install of the compiled binary
+  //      hit 404 on /admin (issue #1090).
   const path = await import('path');
   const fs = await import('fs');
   const adminDistPath = path.join(process.cwd(), 'admin', 'dist');
-  if (fs.existsSync(adminDistPath)) {
+  const useDevPath = fs.existsSync(adminDistPath);
+  if (useDevPath) {
     app.use('/admin', express.static(adminDistPath));
-    // SPA fallback: serve index.html for all unmatched /admin/* routes
     app.get('/admin/{*path}', (req: Request, res: Response, next: NextFunction) => {
-      // Skip API and events routes
       if (req.path.startsWith('/admin/api/') || req.path === '/admin/events' || req.path === '/admin/login') {
         return next();
       }
       res.sendFile(path.join(adminDistPath, 'index.html'));
     });
+  } else {
+    // Embedded path. Read assets from the generated manifest. Cache the
+    // bytes per asset on first request — these never change for a given
+    // binary, so subsequent requests skip the fs read.
+    const { ADMIN_ASSETS, ADMIN_INDEX_HTML } = await import('../admin-embedded.ts');
+    const cache = new Map<string, Buffer>();
+    function loadAsset(asset: { path: string }): Buffer {
+      const hit = cache.get(asset.path);
+      if (hit) return hit;
+      const buf = fs.readFileSync(asset.path);
+      cache.set(asset.path, buf);
+      return buf;
+    }
+    app.get('/admin/{*path}', (req: Request, res: Response, next: NextFunction) => {
+      if (req.path.startsWith('/admin/api/') || req.path === '/admin/events' || req.path === '/admin/login') {
+        return next();
+      }
+      const hit = ADMIN_ASSETS[req.path];
+      if (hit) {
+        res.setHeader('Content-Type', hit.mime);
+        res.send(loadAsset(hit));
+        return;
+      }
+      // SPA fallback — every unmatched /admin/* route resolves to index.html
+      // so client-side routing takes over (login, dashboard, agents, ...).
+      if (ADMIN_INDEX_HTML) {
+        res.setHeader('Content-Type', ADMIN_INDEX_HTML.mime);
+        res.send(loadAsset(ADMIN_INDEX_HTML));
+        return;
+      }
+      res.status(404).send('admin SPA not available');
+    });
   }
 
   // ---------------------------------------------------------------------------