golem-kit 0.1.0

package/README.md

@@ -0,0 +1,41 @@
+# Golem
+
+![Golem mascot](assets/golem-mascot.png)
+
+## What is Golem?
+
+Golem is an early local application shell for building applications with AI. **Your app is its own IDE:** enter build mode, ask a locally authenticated Codex to edit the app, and keep using it in the same browser shell.
+
+## Getting Started
+
+Install Node.js >=22.18.0 and pnpm 10.28.2. Then run:
+
+```sh
+mkdir my-app
+cd my-app
+npx golem-kit init
+```
+
+Start the application:
+
+```sh
+./golem dev
+```
+
+Open the browser address printed in the terminal, enter build mode, and start a conversation. Build chat requires the Codex CLI installed and authenticated on the same machine. After a successful build-mode change, the browser shell rebuilds and refreshes; conversations are saved in `.golem/` and restored when the server restarts.
+
+`./golem build` writes the browser shell to `dist/`. `./golem dev` binds only to `127.0.0.1:3000`.
+
+## Local source development
+
+Use an installed package by default, or opt into a durable checkout while developing Golem:
+
+```sh
+GOLEM_SOURCE=/path/to/golem ./golem dev
+```
+
+See [the local CLI guide](docs/local-cli.md) for the complete command contract.
+
+## Current scope
+
+Claude integration, domain storage, accounts, and permissions are planned, not part of this release.

package/docs/local-cli.md

@@ -0,0 +1,64 @@
+# Local command contract
+
+Use Node.js >=22.18.0 (native TypeScript execution) and pnpm 10.28.2.
+Run `pnpm install`, then `./golem help`. The executable wrapper resolves the
+project-local CLI relative to itself, including when invoked from another directory.
+The browser shell uses the local Vite build and the published `golem-ui` package.
+
+## Source resolution seam
+
+The root wrapper explicitly selects `src/cli.ts` relative to the wrapper's own
+directory. This is the sole CLI entrypoint resolution point today; there is no
+package-name lookup or resolution configuration. Generated app wrappers add an
+explicit `GOLEM_SOURCE=/path/to/golem` opt-in for running a framework checkout
+while keeping the app cwd. Unset it to use the installed pinned package.
+
+The CLI imports `./dev-server.ts` relative to the wrapper. The server serves built `dist/`
+files and does not resolve packages or depend on
+the caller's working directory. Keep source/package selection outside this server
+boundary so a hot-source workflow can select the CLI without changing HTTP startup.
+
+## Commands
+
+| Command | Behavior | Exit status |
+| --- | --- | --- |
+| `./golem help` (or `./golem`) | List all commands | 0 |
+| `./golem dev` | Refresh the browser build, then serve it at `http://127.0.0.1:3000/` until SIGINT/SIGTERM | 0 on clean shutdown; 1 on startup failure |
+| `./golem build` | Build the browser shell into `dist/` | 0 |
+| `./golem doctor` | Report local shell and backend readiness | 0 |
+
+Unknown commands and extra arguments exit 2. Built assets are served directly; extensionless browser
+routes fall back to `index.html`, while missing assets return 404. Malformed URLs return 400. The
+server binds to loopback only. Port 3000 must be free.
+`doctor` succeeding means its report ran, not that the full product is ready.
+
+`src/dev-server.ts` exports `startDevServer(port = 3000)`, resolving to a listening
+Node HTTP server. It refreshes the browser build before listening; the CLI owns signal handling and output. `src/browser/app.tsx` is the
+composition boundary: anonymous identity and browser navigation are explicit host adapters, while
+the chat adapter connects explicit browser build-mode sessions to the local Codex runtime.
+
+Check types with `pnpm exec tsc --noEmit`; run the CLI/HTTP smoke check with
+`node --test --test-concurrency=1 test/*.mjs` (serial because the CLI test intentionally removes
+and rebuilds the shared `dist/` directory; requires port 3000).
+
+## Generated projects
+
+`golem-kit init` creates `package.json`, `golem.config.ts`, `src/app.tsx`,
+`docs/domain.md`, and an executable `./golem`. Normal initialization writes the
+pinned npm dependency `golem-kit@<framework version>` and installs it with pnpm.
+For local packed-tarball acceptance only, set `GOLEM_KIT_TARBALL=/path/to/golem-kit.tgz`.
+An existing package is supported only when it already declares `golem-kit`; its
+metadata is preserved. Other nonempty destinations are refused.
+
+Two-checkout development:
+
+```sh
+GOLEM_SOURCE=/path/to/golem /path/to/app/golem build
+GOLEM_SOURCE=/path/to/golem /path/to/app/golem dev
+```
+
+The wrapper changes into the app first, so `src/` and `dist/` remain app-owned.
+The framework checkout uses its own installed dependencies. Source-mode builds
+print framework path and short git revision, plus the same fields for
+`GOLEM_UI_SOURCE` when that override is set. Omit both overrides to return to the
+installed pinned package.

package/docs/source-development.md

@@ -0,0 +1,65 @@
+# Local UI source development
+
+The normal Golem checkout uses the pinned published `golem-ui@0.1.1` dependency. For a local
+change to `golem-ui`, set `GOLEM_UI_SOURCE` to an isolated UI checkout for that command. Golem
+aliases the package entry point and stylesheet to `src/index.ts` and `src/styles.css`, while
+deduplicating React with the Golem checkout. It also loads the UI checkout's installed
+`@tailwindcss/vite` plugin and adds the checkout as a Tailwind `@source`, so utility classes in
+edited UI components are compiled and scanned.
+
+## Clean checkout
+
+```sh
+git clone https://github.com/tonylampada/golem.git
+git clone https://github.com/tonylampada/golem-ui.git
+cd golem
+pnpm install
+cd ../golem-ui
+pnpm install
+cd ../golem
+```
+
+Run the Golem checkout against the checked-out UI source:
+
+```sh
+GOLEM_UI_SOURCE=../golem-ui ./golem dev
+```
+
+The build prints both checkout paths and their short git revisions in source mode. `./golem
+build` accepts the same override. The path must contain the golem-ui `package.json`, `src/index.ts`,
+and `src/styles.css`; invalid paths fail with an explanatory error.
+
+To return to the published dependency, omit the variable:
+
+```sh
+./golem dev
+```
+
+With the server running, these direct browser assertions check the expected placeholder, computed
+font/display, and desktop/mobile chat/canvas geometry. Install Playwright and its managed Chromium
+in a temporary directory. Set GOLEM_BROWSER_EXECUTABLE only when using another browser binary:
+
+```sh
+browser_tools=$(mktemp -d)
+npm --prefix "$browser_tools" install --no-save playwright
+"$browser_tools/node_modules/.bin/playwright" install chromium
+export PLAYWRIGHT_MODULE="$browser_tools/node_modules/playwright/index.mjs"
+GOLEM_UI_SOURCE=../golem-ui GOLEM_EXPECTED_PLACEHOLDER='Message the agent…' GOLEM_BROWSER_SCREENSHOT=.artifacts/source \
+  node scripts/browser-assertions.mjs
+unset GOLEM_UI_SOURCE GOLEM_EXPECTED_PLACEHOLDER
+GOLEM_BROWSER_SCREENSHOT=.artifacts/published node scripts/browser-assertions.mjs
+rm -rf "$browser_tools"
+```
+
+For example, an explicit browser binary can be selected with `GOLEM_BROWSER_EXECUTABLE=/path/to/chrome`.
+
+For a temporary source marker experiment, set GOLEM_EXPECTED_PLACEHOLDER to the marker after
+editing the isolated UI checkout. Ordinary source mode expects the normal Message the agent… placeholder.
+No package scripts or lockfiles need to change when switching modes. `golem-ui` itself uses Vite
+and its package build is `pnpm build`; source mode consumes its TypeScript entry point directly.
+
+For generated apps, `GOLEM_SOURCE=/path/to/golem /path/to/app/golem dev` opts into
+the framework checkout while preserving the app cwd and lockfile. Omit
+`GOLEM_SOURCE` to use the installed pinned `golem-kit`; combine it with
+`GOLEM_UI_SOURCE=/path/to/golem-ui` when developing both checkouts. Source-mode
+builds print each source path and short git revision.

package/golem.config.ts

@@ -0,0 +1 @@
+export default { title: 'Golem' }

package/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Golem</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/browser/main.tsx"></script>
+  </body>
+</html>

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "golem-kit",
+  "version": "0.1.0",
+  "description": "Starter kit and local CLI for Golem applications.",
+  "type": "module",
+  "files": [
+    "README.md",
+    "assets/golem-mascot.png",
+    "docs/local-cli.md",
+    "docs/source-development.md",
+    "golem.config.ts",
+    "index.html",
+    "src",
+    "tsconfig.json",
+    "vite.config.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tonylampada/golem.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tonylampada/golem/issues"
+  },
+  "homepage": "https://github.com/tonylampada/golem#readme",
+  "packageManager": "pnpm@10.28.2",
+  "engines": {
+    "node": ">=22.18.0",
+    "pnpm": "10.28.2"
+  },
+  "bin": {
+    "golem-kit": "src/cli.ts"
+  },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 test/*.test.mjs"
+  },
+  "dependencies": {
+    "@types/node": "22.20.3",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.1",
+    "@vitejs/plugin-react": "5.0.4",
+    "typescript": "7.0.2",
+    "vite": "7.1.9",
+    "tsx": "4.23.13",
+    "golem-ui": "0.1.1",
+    "react": "19.2.0",
+    "react-dom": "19.2.0"
+  }
+}

package/src/app.tsx

@@ -0,0 +1,10 @@
+export default function App() {
+  return (
+    <section className="flex h-full min-h-64 items-center justify-center bg-neutral-50 p-6 text-center">
+      <div>
+        <h1 className="text-lg font-semibold">Welcome to Golem</h1>
+        <p className="mt-2 text-sm text-neutral-500">Edit src/app.tsx to build your app.</p>
+      </div>
+    </section>
+  )
+}

package/src/browser/adapters.ts

@@ -0,0 +1,164 @@
+import type { ChatAdapter, ChatAttachment, ChatMessage, IdentityAdapter, NavigationAdapter, Route, User } from 'golem-ui'
+
+const unavailable = () => Promise.reject(new Error('No agent or identity service is connected.'))
+
+/** Anonymous means only that this host has no sign-in service; it grants no authorization. */
+export const anonymousIdentity: IdentityAdapter = {
+  currentUser: async () => null,
+  subscribe: () => () => {},
+  signIn: unavailable,
+  signUp: unavailable,
+  requestCode: unavailable,
+  verifyCode: unavailable,
+  signOut: async () => {},
+  listMembers: async () => [],
+  invite: unavailable,
+  removeMember: unavailable,
+  setRole: unavailable,
+}
+
+function route(): Route {
+  return { path: window.location.pathname, params: Object.fromEntries(new URLSearchParams(window.location.search)) }
+}
+
+export const navigation: NavigationAdapter = {
+  current: route,
+  go(path) { window.history.pushState({}, '', path); window.dispatchEvent(new PopStateEvent('popstate')) },
+  subscribe(listener) {
+    const update = () => listener(route())
+    window.addEventListener('popstate', update)
+    return () => window.removeEventListener('popstate', update)
+  },
+}
+
+const storageKey = 'golem.browser.session'
+let sessionId: string | undefined = (() => {
+  try { return window.sessionStorage.getItem(storageKey) ?? undefined } catch { return undefined }
+})()
+let messages: ChatMessage[] = []
+let cursor = -1
+let eventLog = new Map<number, { sequence: number; type: string; text?: string; status?: string; reason?: string }>()
+let status = 'starting'
+let source: EventSource | undefined
+const listeners = new Set<(messages: ChatMessage[]) => void>()
+const statusListeners = new Set<(status: string) => void>()
+const emit = () => listeners.forEach((listener) => listener([...messages]))
+const setStatus = (next: string) => { status = next; statusListeners.forEach((listener) => listener(status)) }
+
+function mergeEvents(events: Array<{ sequence: number; type: string; text?: string; status?: string; reason?: string }>): string | undefined {
+  for (const event of events) if (!eventLog.has(event.sequence)) eventLog.set(event.sequence, event)
+  const ordered = [...eventLog.values()].sort((left, right) => left.sequence - right.sequence)
+  cursor = Math.max(cursor, ...ordered.map((event) => event.sequence))
+  messages = fromEvents(ordered)
+  return ordered.findLast((event) => event.type === 'status')?.status
+}
+
+function fromEvents(events: Array<{ type: string; sequence: number; text?: string; status?: string; reason?: string }>): ChatMessage[] {
+  return events.flatMap((event) => {
+    if ((event.type === 'user' || event.type === 'message') && event.text) {
+      return [{ id: `${event.sequence}`, role: event.type === 'user' ? 'user' : 'agent', text: event.text, at: new Date().toISOString() }]
+    }
+    if (event.type === 'error') return [{ id: `${event.sequence}`, role: 'agent', text: `Error: ${event.text ?? 'Agent failed.'}`, at: new Date().toISOString() }]
+    if (event.type === 'interrupted') return [{ id: `${event.sequence}`, role: 'agent', text: `Interrupted${event.reason ? `: ${event.reason}` : '.'}`, at: new Date().toISOString() }]
+    return []
+  })
+}
+
+/** The only session-starting call in the UI — declares build intent explicitly; the server decides permission from it. */
+export async function startBrowserSession(): Promise<{ id: string; backend: string }> {
+  const response = await fetch('/api/sessions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ backend: 'codex', intent: 'build' }) })
+  const result = await response.json() as { id?: string; backend?: string; error?: string }
+  if (!response.ok || !result.id) throw new Error(result.error ?? 'Unable to start session')
+  source?.close()
+  source = undefined
+  sessionId = result.id
+  window.sessionStorage.setItem(storageKey, sessionId)
+  cursor = -1
+  eventLog = new Map()
+  setStatus('ready')
+  messages = []
+  emit()
+  return { id: result.id, backend: result.backend ?? 'codex' }
+}
+
+export function currentBrowserSession(): string | undefined { return sessionId }
+
+export async function restoreBrowserSession(): Promise<boolean> {
+  if (!sessionId) return false
+  const response = await fetch(`/api/sessions/${sessionId}/history`)
+  if (response.status === 404) {
+    sessionId = undefined
+    window.sessionStorage.removeItem(storageKey)
+    return false
+  }
+  if (!response.ok) throw new Error((await response.json()).error ?? 'Unable to restore session')
+  const result = await response.json() as { events: Array<{ sequence: number; type: string; text?: string; reason?: string }>; status: string }
+  eventLog = new Map()
+  setStatus(mergeEvents(result.events) ?? result.status)
+  emit()
+  return true
+}
+
+export function subscribeBrowserStatus(listener: (status: string) => void): () => void {
+  statusListeners.add(listener)
+  listener(status)
+  return () => statusListeners.delete(listener)
+}
+
+export async function interruptBrowserSession(): Promise<void> {
+  if (!sessionId) return
+  const response = await fetch(`/api/sessions/${sessionId}/interrupt`, { method: 'POST', headers: { 'Content-Type': 'application/json' } })
+  if (!response.ok) throw new Error((await response.json()).error ?? 'Unable to interrupt session')
+}
+
+function applyEvent(event: { sessionId?: string; sequence: number; type: string; text?: string; status?: string; reason?: string }): void {
+  if (event.sessionId && event.sessionId !== sessionId) return
+  if (event.sequence <= cursor) return
+  cursor = event.sequence
+  if (event.status) setStatus(event.status)
+  // Live-only: a replayed 'rebuilt' from history/reload restoration must never re-trigger this.
+  if (event.type === 'rebuilt') { window.location.reload(); return }
+  mergeEvents([event])
+  emit()
+}
+
+export const chat: ChatAdapter = {
+  history: async () => {
+    if (!sessionId) return []
+    const response = await fetch(`/api/sessions/${sessionId}/history`)
+    if (!response.ok) throw new Error((await response.json()).error ?? 'Unable to load session history')
+    const result = await response.json() as { events: Array<{ sequence: number; type: string; text?: string; reason?: string }>; status: string }
+  setStatus(mergeEvents(result.events) ?? result.status)
+    emit()
+    return [...messages]
+  },
+  subscribe(listener) {
+    listeners.add(listener)
+    if (sessionId) {
+      source?.close()
+      const subscribedSession = sessionId
+      let subscribedSource: EventSource
+      const connect = () => {
+        const nextSource = new EventSource(`/api/sessions/${subscribedSession}/events?after=${cursor}`)
+        subscribedSource = nextSource
+        source = nextSource
+        nextSource.onmessage = (event) => applyEvent(JSON.parse(event.data))
+        nextSource.onerror = () => {
+          if (source === nextSource && nextSource.readyState === EventSource.CLOSED && sessionId === subscribedSession) {
+            connect()
+          }
+        }
+      }
+      connect()
+      return () => { subscribedSource.close(); if (source === subscribedSource) source = undefined; listeners.delete(listener) }
+    }
+    return () => listeners.delete(listener)
+  },
+  async send(text, attachments) {
+    if (!sessionId) throw new Error('Enter build mode before sending a message')
+    const response = await fetch(`/api/sessions/${sessionId}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ text, attachments }) })
+    if (!response.ok) throw new Error((await response.json()).error ?? 'Agent request failed')
+  },
+}
+
+export type { ChatMessage, User }

package/src/browser/app.d.ts

@@ -0,0 +1,9 @@
+declare module '@golem/app' {
+  import type { ComponentType } from 'react'
+  const App: ComponentType
+  export default App
+}
+declare module '@golem/config' {
+  const config: { title: string }
+  export default config
+}

package/src/browser/app.tsx

@@ -0,0 +1,63 @@
+import { useEffect, useRef, useState } from 'react'
+import { Chat, Shell } from 'golem-ui'
+import UserApp from '@golem/app'
+import projectConfig from '@golem/config'
+import { anonymousIdentity, chat, interruptBrowserSession, navigation, restoreBrowserSession, startBrowserSession, subscribeBrowserStatus } from './adapters'
+
+const shellAdapters = { identity: anonymousIdentity, navigation }
+const chatAdapters = { chat }
+
+export function App() {
+  const [mode, setMode] = useState(false)
+  const [session, setSession] = useState<string>()
+  const [sessionStatus, setSessionStatus] = useState('starting')
+  const [enteringBuildMode, setEnteringBuildMode] = useState(false)
+  const enteringBuildModeRef = useRef(false)
+  const [runtime, setRuntime] = useState<{ codex: boolean; claude: boolean }>({ codex: false, claude: false })
+  const [error, setError] = useState<string>()
+  useEffect(() => {
+    fetch('/api/runtime').then((response) => response.json()).then((result) => {
+      const discoveries = result.discoveries as Array<{ agent: string; status: string; runnable: boolean }>
+      setRuntime({ codex: discoveries.some((item) => item.agent === 'codex' && item.status === 'available' && item.runnable), claude: false })
+    }).catch(() => setError('Runtime discovery unavailable.'))
+  }, [])
+  useEffect(() => {
+    const unsubscribe = subscribeBrowserStatus(setSessionStatus)
+    restoreBrowserSession().then((restored) => {
+      if (restored) { setSession(window.sessionStorage.getItem('golem.browser.session') ?? undefined); setMode(true) }
+    }).catch((cause) => setError(cause instanceof Error ? cause.message : String(cause)))
+    return unsubscribe
+  }, [])
+  const enterBuildMode = async () => {
+    if (enteringBuildModeRef.current) return
+    enteringBuildModeRef.current = true
+    setEnteringBuildMode(true)
+    setError(undefined)
+    try { const started = await startBrowserSession(); setSession(started.id); setMode(true) }
+    catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)) }
+    finally { enteringBuildModeRef.current = false; setEnteringBuildMode(false) }
+  }
+  const interrupt = async () => {
+    try { await interruptBrowserSession() } catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)) }
+  }
+  return (
+    <Shell
+      config={{ title: projectConfig.title, chatSide: 'left', breakpoint: 768 }}
+      adapters={shellAdapters}
+      chat={
+        <div className="flex h-full min-h-0 flex-col">
+          <div className="flex items-center justify-between border-b border-neutral-200 bg-white px-4 py-3 text-sm">
+            <span className="font-medium">{mode ? 'Build mode' : 'Conversation mode'}</span>
+            <span className={mode ? 'text-green-700' : 'text-neutral-500'}>{mode ? `${sessionStatus} · ${session}` : 'Not connected'}</span>
+            {mode && (sessionStatus === 'ready' || sessionStatus === 'starting') && <button className="rounded border border-red-300 px-2 py-1 text-red-700" onClick={interrupt}>Interrupt</button>}
+          </div>
+          {!mode ? <div className="p-4 text-sm"><p className="text-neutral-600">Codex: {runtime.codex ? 'available' : 'unavailable'} · Claude: not yet connected</p><button className="mt-4 rounded bg-neutral-900 px-3 py-2 text-white disabled:opacity-40" disabled={!runtime.codex || enteringBuildMode} onClick={enterBuildMode}>Enter build mode</button>{error && <p className="mt-3 text-red-700">{error}</p>}</div> : <Chat key={session} config={{ agentName: 'Golem Codex', emptyState: 'Ask Codex to inspect or explain this workspace.' }} adapters={chatAdapters} />}
+        </div>
+      }
+      canvas={
+        <UserApp />
+      }
+      account={<span className="shrink-0 text-sm text-neutral-500">Guest</span>}
+    />
+  )
+}

package/src/browser/main.tsx

@@ -0,0 +1,9 @@
+import { createRoot } from 'react-dom/client'
+import 'golem-ui/styles.css'
+import { App } from './app'
+
+document.documentElement.style.height = '100%'
+document.body.style.height = '100%'
+document.body.style.margin = '0'
+document.getElementById('root')!.style.height = '100%'
+createRoot(document.getElementById('root')!).render(<App />)

package/src/browser/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/src/browser-build.ts

@@ -0,0 +1,70 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { resolve } from 'node:path';
+import { build } from 'vite';
+import { resolveUiSource } from '../vite.config.ts';
+
+const frameworkRoot = resolve(fileURLToPath(new URL('..', import.meta.url)));
+
+/**
+ * The one build boundary used by both `./golem build` and `./golem dev`.
+ * Typecheck runs before the Vite build on purpose: Vite's own `dist/` write only happens once
+ * its build succeeds, so checking types first means a type-only failure never touches `dist/`
+ * either, matching the same previous-build-preserved-on-failure guarantee a parse failure gets.
+ */
+export async function buildBrowser(): Promise<void> {
+  const ui = resolveUiSource();
+  if (process.env.GOLEM_SOURCE) console.log(`Golem source: ${frameworkRoot} (${gitRevision(frameworkRoot)})`);
+  if (ui) {
+    console.log(`Golem source: ${frameworkRoot} (${gitRevision(frameworkRoot)})`);
+    console.log(`golem-ui source: ${ui.root} (${ui.revision})`);
+  }
+  const tsc = resolve(frameworkRoot, 'node_modules/.bin/tsc');
+  const typeRoots = existsSync(resolve(frameworkRoot, 'node_modules/@types'))
+    ? resolve(frameworkRoot, 'node_modules/@types')
+    : resolve(frameworkRoot, '../@types');
+  execFileSync(tsc, ['--noEmit', '-p', resolve(frameworkRoot, 'tsconfig.json')], {
+    cwd: process.cwd(),
+    stdio: 'inherit',
+  });
+  execFileSync(tsc, [
+    '--ignoreConfig', '--noEmit', '--jsx', 'react-jsx', '--module', 'ESNext',
+    '--moduleResolution', 'Bundler', '--skipLibCheck', '--types', 'node,react,react-dom',
+    '--typeRoots', typeRoots,
+    resolve(process.cwd(), 'src/app.tsx'), resolve(process.cwd(), 'golem.config.ts'),
+  ], { cwd: process.cwd(), stdio: 'inherit' });
+  await build({ configFile: resolve(frameworkRoot, 'vite.config.ts') });
+}
+
+let buildInFlight: Promise<void> | undefined
+let queued = false
+
+/**
+ * Server-owned rebuild trigger for after a build-mode turn. Coalesces overlapping calls into
+ * one rerun instead of racing concurrent `buildBrowser()` invocations.
+ */
+export function rebuild(): Promise<void> {
+  if (buildInFlight) { queued = true; return buildInFlight }
+  buildInFlight = runQueuedBuilds()
+  return buildInFlight
+}
+
+async function runQueuedBuilds(): Promise<void> {
+  try {
+    do {
+      queued = false
+      await buildBrowser()
+    } while (queued)
+  } finally {
+    buildInFlight = undefined
+  }
+}
+
+function gitRevision(root: string): string {
+  try {
+    return execFileSync('git', ['-C', root, 'rev-parse', '--short', 'HEAD'], { encoding: 'utf8' }).trim();
+  } catch {
+    return 'unavailable';
+  }
+}