golem-kit 0.1.0

package/src/cli.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env tsx
+import { startDevServer } from './dev-server.ts';
+import { buildBrowser } from './browser-build.ts';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const help = `Golem — local project CLI
+
+Usage: ./golem <command>
+
+  help    Show every command (also the default).
+  init    Create a minimal app in the current directory.
+  dev     Serve the browser shell at http://127.0.0.1:3000/.
+          Stop with Ctrl+C. Uses the local Codex runtime from the browser.
+  build   Build the browser shell into dist/.
+  doctor  Report local shell and backend readiness.
+
+Requires Node.js >=22.18.0. Commands accept no additional arguments.
+Exit codes: 0 success/clean shutdown, 1 unavailable or failed, 2 invalid usage.
+`;
+
+const [command = 'help', ...args] = process.argv.slice(2);
+
+if (args.length || !['help', 'init', 'dev', 'build', 'doctor'].includes(command)) {
+  console.error('Invalid command or arguments. Run ./golem help.');
+  process.exitCode = 2;
+} else {
+  switch (command) {
+    case 'help':
+      console.log(help);
+      break;
+    case 'init':
+      try {
+        initProject();
+        console.log('Initialized Golem app. Run ./golem help.');
+      } catch (error) {
+        console.error(`Cannot initialize Golem app: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+      break;
+    case 'doctor':
+      console.log(`Golem shell readiness (Node ${process.version})
+Ready: local CLI, HTTP shell, golem-ui browser build and Codex session seam.
+Claude integration: not yet connected.
+Not implemented: Claude integration.
+No network exposure is enabled; the dev server binds to loopback.`);
+      break;
+    case 'build':
+      try {
+        await buildBrowser();
+      } catch (error) {
+        console.error(`Cannot build Golem browser shell: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+      break;
+    case 'dev':
+      try {
+        const server = await startDevServer();
+        const stop = () => {
+          server.close((error) => {
+            process.removeListener('SIGINT', stop);
+            process.removeListener('SIGTERM', stop);
+            if (error) {
+              console.error(error.message);
+              process.exitCode = 1;
+            } else {
+              console.log('Golem dev server stopped.');
+            }
+          });
+          server.closeAllConnections();
+        };
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        console.log('Golem shell: http://127.0.0.1:3000/ (Ctrl+C to stop)');
+      } catch (error) {
+        console.error(`Cannot start Golem dev server: ${error instanceof Error ? error.message : String(error)}`);
+        process.exitCode = 1;
+      }
+  }
+}
+
+function initProject(): void {
+  const root = resolve(process.cwd());
+  const files = ['golem.config.ts', 'src/app.tsx', 'docs/domain.md', 'golem'];
+  const existing = files.filter((file) => existsSync(resolve(root, file)));
+  if (existing.length) throw new Error(`refusing to overwrite existing files: ${existing.join(', ')}`);
+  const packagePath = resolve(root, 'package.json');
+  const packageExisted = existsSync(packagePath);
+  if (existsSync(packagePath)) {
+    const current = JSON.parse(readFileSync(packagePath, 'utf8')) as { dependencies?: Record<string, string> };
+    if (!current.dependencies?.['golem-kit']) throw new Error('refusing to overwrite existing package.json');
+  }
+  const frameworkRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+  const framework = JSON.parse(readFileSync(resolve(frameworkRoot, 'package.json'), 'utf8')) as { version: string };
+  mkdirSync(resolve(root, 'src'), { recursive: true });
+  mkdirSync(resolve(root, 'docs'), { recursive: true });
+  if (!existsSync(packagePath)) {
+    writeFileSync(packagePath, JSON.stringify({
+      name: 'golem-app', private: true, type: 'module', packageManager: 'pnpm@10.28.2',
+      engines: { node: '>=22.18.0', pnpm: '10.28.2' },
+      ...(process.env.GOLEM_KIT_TARBALL ? {} : { dependencies: { 'golem-kit': framework.version } }),
+    }, null, 2) + '\n');
+  }
+  writeFileSync(resolve(root, 'golem.config.ts'), "export default { title: 'Golem' }\n");
+  writeFileSync(resolve(root, 'src/app.tsx'), `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>
+  )
+}
+`);
+  writeFileSync(resolve(root, 'docs/domain.md'), '# Golem app\n\nA minimal editable app entrypoint.\n');
+  const ignorePath = resolve(root, '.gitignore');
+  const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, 'utf8') : '';
+  if (!ignore.split(/\r?\n/).includes('.golem/')) writeFileSync(ignorePath, `${ignore}${ignore && !ignore.endsWith('\n') ? '\n' : ''}.golem/\n`);
+  if (!packageExisted) {
+    const packageSpec = process.env.GOLEM_KIT_TARBALL ?? `golem-kit@${framework.version}`;
+    execFileSync('pnpm', ['add', '--save-exact', packageSpec], { cwd: root, stdio: 'inherit' });
+  }
+  writeFileSync(resolve(root, 'golem'), '#!/bin/sh\nset -eu\ncd -- "$(dirname -- "$0")"\nif [ -n "${GOLEM_SOURCE:-}" ]; then\n  exec node "$GOLEM_SOURCE/src/cli.ts" "$@"\nfi\nexec node_modules/.bin/golem-kit "$@"\n', { mode: 0o755 });
+}

package/src/dev-server.ts

@@ -0,0 +1,190 @@
+import { createServer, type Server } from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { extname, join, normalize, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { buildBrowser, rebuild } from './browser-build.ts';
+import { discoverAgents, runtimeState } from './runtime/discovery.ts';
+import { CodexBackend, type SandboxMode } from './runtime/codex.ts';
+import { SessionManager, type Session, type SessionBackend } from './runtime/session.ts';
+import { ConversationState } from './runtime/state.ts';
+
+const appRoot = resolve(process.cwd());
+const root = pathToFileURL(`${process.cwd()}/dist/`);
+const types: Record<string, string> = {
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.svg': 'image/svg+xml',
+};
+
+// The CLI owns logging and signals; this server only serves the built browser shell.
+export async function startDevServer(
+  port = 3000,
+  createBackend: (mode: SandboxMode, threadId?: string) => SessionBackend = (mode, threadId) => new CodexBackend(appRoot, mode, 'codex', [], threadId),
+  stateDirectory = join(appRoot, '.golem'),
+): Promise<Server> {
+  await buildBrowser();
+  const state = new ConversationState(stateDirectory);
+  const sessions = new SessionManager((snapshots) => state.save(snapshots));
+  sessions.restore(await state.load(), (snapshot) => createBackend(snapshot.buildMode ? 'danger-full-access' : 'read-only', snapshot.threadId));
+  const server = createServer((request, response) => {
+    void handleRequest(request, response, sessions, port, createBackend).catch((error) => {
+      if (!response.headersSent) json(response, 400, { error: error instanceof Error ? error.message : 'Malformed request' });
+      else response.destroy();
+    });
+  });
+  server.once('close', () => { void sessions.disposeAll().then(() => sessions.flushAll()) });
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', () => resolve(server));
+  });
+}
+
+async function handleRequest(
+  request: import('node:http').IncomingMessage,
+  response: import('node:http').ServerResponse,
+  sessions: SessionManager,
+  port: number,
+  createBackend: (mode: SandboxMode, threadId?: string) => SessionBackend,
+): Promise<void> {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    decodeURIComponent(url.pathname);
+    if (url.pathname.startsWith('/api/')) {
+      await handleApi(request, response, url, sessions, port, createBackend);
+      return;
+    }
+    let pathname: string;
+    try {
+      pathname = decodeURIComponent(new URL(request.url ?? '/', 'http://127.0.0.1').pathname);
+    } catch {
+      response.writeHead(400, { 'Content-Type': 'text/plain; charset=utf-8' });
+      response.end('Malformed URL\n');
+      return;
+    }
+    const relative = pathname === '/' ? 'index.html' : pathname.slice(1);
+    const normalized = normalize(join('.', relative));
+    const file = new URL(normalized, root);
+    if (!file.pathname.startsWith(root.pathname)) {
+      response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+      response.end('Not found\n');
+      return;
+    }
+    try {
+      const body = await readFile(file);
+      response.writeHead(200, { 'Content-Type': types[extname(relative)] ?? 'application/octet-stream' });
+      response.end(body);
+    } catch {
+      if (extname(relative)) {
+        response.writeHead(404, { 'Content-Type': 'text/plain; charset=utf-8' });
+        response.end('Not found\n');
+        return;
+      }
+      try {
+        const body = await readFile(new URL('index.html', root));
+        response.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+        response.end(body);
+      } catch {
+        response.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' });
+        response.end('Run `./golem build` before starting the dev server.\n');
+      }
+    }
+}
+
+function json(response: import('node:http').ServerResponse, status: number, body: unknown): void {
+  response.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
+  response.end(JSON.stringify(body));
+}
+
+async function body(request: import('node:http').IncomingMessage): Promise<unknown> {
+  let text = '';
+  for await (const chunk of request) {
+    text += String(chunk);
+    if (text.length > 100_000) throw new Error('Request body is too large');
+  }
+  try { return JSON.parse(text || '{}'); } catch { throw new Error('Request body must be valid JSON'); }
+}
+
+/** Fires once after a successful build-mode turn; never blocks the turn's own response. */
+function triggerRebuild(session: Session): void {
+  void rebuild().then(
+    () => session.notifyRebuilt(),
+    (error) => session.notifyBuildFailed(error instanceof Error ? error.message : String(error)),
+  );
+}
+
+function mutationAllowed(request: import('node:http').IncomingMessage, port: number): boolean {
+  const origin = request.headers.origin;
+  return !origin || origin === `http://127.0.0.1:${port}` || origin === `http://localhost:${port}`;
+}
+
+async function handleApi(
+  request: import('node:http').IncomingMessage,
+  response: import('node:http').ServerResponse,
+  url: URL,
+  sessions: SessionManager,
+  port: number,
+  createBackend: (mode: SandboxMode) => SessionBackend,
+): Promise<void> {
+  if (request.method === 'GET' && url.pathname === '/api/runtime') {
+    const discoveries = await discoverAgents();
+    json(response, 200, { discoveries, state: runtimeState(discoveries) });
+    return;
+  }
+  if (request.method === 'POST' && url.pathname === '/api/sessions') {
+    if (!mutationAllowed(request, port)) return json(response, 403, { error: 'Cross-origin mutations are not allowed' });
+    try {
+      const input = await body(request) as { backend?: string; intent?: string };
+      if (input.backend !== 'codex') return json(response, 400, { error: 'Only the connected Codex backend can start a session' });
+      // Server-owned: only an explicit build intent grants filesystem access. Omitted intent stays read-only.
+      // danger-full-access, not app-root-confined — see CodexBackend's doc comment for why.
+      const buildMode = input.intent === 'build';
+      const session = await sessions.start('codex', createBackend(buildMode ? 'danger-full-access' : 'read-only'), buildMode);
+      json(response, 201, { id: session.id, backend: session.backend, status: session.status });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      json(response, message.startsWith('Request body') ? 400 : 503, { error: message });
+    }
+    return;
+  }
+  const match = url.pathname.match(/^\/api\/sessions\/([^/]+)(?:\/(history|events|interrupt))?$/);
+  if (!match) return json(response, 404, { error: 'Unknown API route' });
+  const session = sessions.get(match[1]);
+  if (!session) return json(response, 404, { error: 'Unknown session' });
+  if (request.method === 'GET' && match[2] === 'history') {
+    json(response, 200, { events: session.history, status: session.status, backend: session.backend });
+    return;
+  }
+  if (request.method === 'GET' && match[2] === 'events') {
+    const after = Number(url.searchParams.get('after') ?? request.headers['last-event-id'] ?? '-1');
+    if (!Number.isInteger(after)) return json(response, 400, { error: 'after must be an integer sequence' });
+    response.writeHead(200, { 'Content-Type': 'text/event-stream; charset=utf-8', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+    response.flushHeaders();
+    const write = (event: { sequence: number }) => response.write(`id: ${event.sequence}\ndata: ${JSON.stringify(event)}\n\n`);
+    const unsubscribe = session.subscribeFrom(after, write);
+    request.on('close', unsubscribe);
+    return;
+  }
+  if (request.method === 'POST' && !match[2]) {
+    if (!mutationAllowed(request, port)) return json(response, 403, { error: 'Cross-origin mutations are not allowed' });
+    try {
+      const input = await body(request) as { text?: unknown };
+      if (typeof input.text !== 'string' || !input.text.trim()) return json(response, 400, { error: 'text must be a non-empty string' });
+      await session.send(input.text);
+      await session.flush();
+      json(response, 202, { status: session.status });
+      if (session.buildMode) triggerRebuild(session);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      json(response, message.startsWith('Request body') ? 400 : 409, { error: message, status: session.status });
+    }
+    return;
+  }
+  if (request.method === 'POST' && match[2] === 'interrupt') {
+    if (!mutationAllowed(request, port)) return json(response, 403, { error: 'Cross-origin mutations are not allowed' });
+    await session.interrupt();
+    await session.flush();
+    json(response, 200, { status: session.status });
+    return;
+  }
+  json(response, 404, { error: 'Unknown API route' });
+}

package/src/runtime/codex.ts

@@ -0,0 +1,119 @@
+import { spawn, type ChildProcess } from 'node:child_process'
+import type { BackendEvent, SessionBackend } from './session.ts'
+
+type JsonEvent = { type?: string; thread_id?: string; item?: { type?: string; text?: string }; error?: string; message?: string }
+export type SandboxMode = 'read-only' | 'danger-full-access'
+
+/**
+ * One native `codex exec --json` process per turn; the thread id preserves continuity.
+ * `mode` is chosen by the caller (the dev server, from the session's explicit build intent),
+ * never defaulted here: an explicit build intent selects `danger-full-access`, a supported
+ * `-s`/`--sandbox` value (`codex exec --help`) that runs with the account's own ordinary
+ * filesystem permissions — not the `--dangerously-bypass-approvals-and-sandbox` omnibus flag,
+ * which is never used here; every other session stays `read-only`.
+ *
+ * `cwd`/`-C` are pinned to the resolved app root so Codex resolves relative paths correctly —
+ * not as a security boundary. A build-mode session can write anywhere this account can.
+ */
+export class CodexBackend implements SessionBackend {
+  private emit!: (event: BackendEvent) => void
+  private nativeThreadId: string | undefined
+  private child: ChildProcess | undefined
+  private request: Promise<void> | undefined
+  private interrupted = false
+  private childClosed: Promise<void> | undefined
+  private readonly cwd: string
+  private readonly mode: SandboxMode
+  private readonly executable: string
+  private readonly prefixArgs: string[]
+
+  constructor(cwd: string, mode: SandboxMode, executable = 'codex', prefixArgs: string[] = [], threadId?: string) {
+    this.cwd = cwd
+    this.mode = mode
+    this.executable = executable
+    this.prefixArgs = prefixArgs
+    this.nativeThreadId = threadId
+  }
+
+  async start(emit: (event: BackendEvent) => void): Promise<void> { this.emit = emit }
+
+  threadId(): string | undefined { return this.nativeThreadId }
+
+  send(text: string): Promise<void> {
+    if (this.request) return Promise.reject(new Error('Codex is already handling a request'))
+    const args = this.nativeThreadId
+      ? [...this.prefixArgs, 'exec', 'resume', this.nativeThreadId, '--json', '-c', `sandbox_mode="${this.mode}"`, '--skip-git-repo-check', text]
+      : [...this.prefixArgs, 'exec', '--json', '-s', this.mode, '-C', this.cwd, '--skip-git-repo-check', text]
+    this.request = new Promise((resolve, reject) => {
+      this.interrupted = false
+      const child = spawn(this.executable, args, { cwd: this.cwd, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true, detached: process.platform !== 'win32' })
+      this.child = child
+      this.childClosed = new Promise((resolve) => child.once('close', () => resolve()))
+      let stderr = ''
+      let output = ''
+      let settled = false
+      const fail = (message: string) => {
+        if (settled) return
+        settled = true
+        this.emit({ type: 'error', message })
+        reject(new Error(message))
+        void this.stopChild(child)
+      }
+      child.stderr.setEncoding('utf8').on('data', (chunk) => { stderr += chunk })
+      child.stdout.setEncoding('utf8').on('data', (chunk) => {
+        output += String(chunk)
+        const lines = output.split('\n')
+        output = lines.pop() ?? ''
+        for (const line of lines.filter(Boolean)) {
+          let event: JsonEvent
+          try { event = JSON.parse(line) } catch { continue }
+          if (event.type === 'thread.started' && event.thread_id) this.nativeThreadId = event.thread_id
+          if (event.type === 'item.completed' && event.item?.type === 'agent_message' && event.item.text) {
+            this.emit({ type: 'message', text: event.item.text })
+          }
+          if (event.type === 'error' || event.type === 'turn.failed') fail(event.error ?? event.message ?? 'Codex request failed')
+        }
+      })
+      child.once('error', (error) => fail(error.message))
+      child.once('close', (code, signal) => {
+        this.child = undefined
+        this.childClosed = undefined
+        this.request = undefined
+        if (settled) return
+        if (code === 0 || this.interrupted) { settled = true; resolve(); return }
+        fail(stderr.trim() || (signal ? `Codex terminated by ${signal}` : `Codex exited with code ${code}`))
+      })
+    })
+    return this.request
+  }
+
+  async interrupt(): Promise<void> {
+    if (!this.child) return
+    this.interrupted = true
+    await this.stopChild(this.child)
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.child) await this.stopChild(this.child)
+    if (this.request) await this.request.catch(() => {})
+    this.child = undefined
+  }
+
+  private async stopChild(child: ChildProcess): Promise<void> {
+    const closed = this.childClosed ?? new Promise<void>((resolve) => child.once('close', () => resolve()))
+    this.signal(child, 'SIGTERM')
+    // Always escalate the request group: its leader may exit after TERM while a child survives.
+    await new Promise<void>((resolve) => setTimeout(resolve, 250))
+    this.signal(child, 'SIGKILL')
+    await Promise.race([closed, new Promise<void>((resolve) => setTimeout(resolve, 750))])
+  }
+
+  private signal(child: ChildProcess, signal: NodeJS.Signals): void {
+    try {
+      if (process.platform !== 'win32' && child.pid) process.kill(-child.pid, signal)
+      else child.kill(signal)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error
+    }
+  }
+}

package/src/runtime/discovery.ts

@@ -0,0 +1,92 @@
+import { spawn } from 'node:child_process'
+
+export type AgentName = 'claude' | 'codex'
+export type ProbeStatus = 'available' | 'missing' | 'failed'
+
+export type AgentDiscovery = {
+  agent: AgentName
+  executable: string
+  status: ProbeStatus
+  runnable?: boolean
+  detail?: string
+}
+
+export type Probe = (executable: string, args: string[], timeoutMs: number) => Promise<ProbeResult>
+
+export type ProbeResult = {
+  status: 'available' | 'missing' | 'failed'
+  detail?: string
+}
+
+const executables: Record<AgentName, string> = { claude: 'claude', codex: 'codex' }
+
+export function probeExecutable(executable: string, args = ['--version'], timeoutMs = 2_000): Promise<ProbeResult> {
+  return new Promise((resolve) => {
+    const child = spawn(executable, args, { stdio: 'ignore', windowsHide: true })
+    let settled = false
+    let timedOut = false
+    let timeoutTimer: NodeJS.Timeout
+    let killTimer: NodeJS.Timeout | undefined
+    let settleTimer: NodeJS.Timeout | undefined
+    const finish = (result: ProbeResult) => {
+      if (settled) return
+      settled = true
+      clearTimeout(timeoutTimer)
+      if (killTimer) clearTimeout(killTimer)
+      if (settleTimer) clearTimeout(settleTimer)
+      resolve(result)
+    }
+    timeoutTimer = setTimeout(() => {
+      timedOut = true
+      child.kill('SIGTERM')
+      killTimer = setTimeout(() => {
+        child.kill('SIGKILL')
+        settleTimer = setTimeout(() => finish({ status: 'failed', detail: 'timed out' }), 500)
+      }, 100)
+    }, timeoutMs)
+    child.once('error', (error: NodeJS.ErrnoException) => {
+      finish(error.code === 'ENOENT'
+        ? { status: 'missing' }
+        : { status: 'failed', detail: error.message })
+    })
+    child.once('exit', (code, signal) => {
+      finish(timedOut
+        ? { status: 'failed', detail: 'timed out' }
+        : code === 0
+          ? { status: 'available' }
+          : { status: 'failed', detail: signal ? `terminated by ${signal}` : `exited with code ${code}` })
+    })
+  })
+}
+
+export async function discoverAgents(
+  probe: Probe = probeExecutable,
+  timeoutMs = 2_000,
+): Promise<AgentDiscovery[]> {
+  return Promise.all((Object.entries(executables) as [AgentName, string][]).map(async ([agent, executable]) => ({
+    agent,
+    executable,
+    ...(probe === probeExecutable ? { runnable: agent === 'codex' } : {}),
+    ...(await probe(executable, ['--version'], timeoutMs)),
+  })))
+}
+
+export type RuntimeState =
+  | { kind: 'setup'; explanation: string }
+  | { kind: 'ready'; backend: AgentName }
+  | { kind: 'choice-required'; available: AgentName[]; explanation: string }
+
+export function runtimeState(discoveries: AgentDiscovery[]): RuntimeState {
+  const available = discoveries
+    .filter(({ status, runnable = true }) => status === 'available' && runnable)
+    .map(({ agent }) => agent)
+  if (available.length === 0) {
+    return { kind: 'setup', explanation: 'Install Codex to start an agent session; Claude is not connected yet.' }
+  }
+  if (available.length === 1) return { kind: 'ready', backend: available[0] }
+  return {
+    kind: 'choice-required',
+    available,
+    explanation: 'Both Claude Code and Codex are available; choose one before starting a session.',
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,2 @@
+export * from './discovery.ts'
+export * from './session.ts'