golem-kit 0.1.0 → 0.1.1

package/README.md

@@ -24,7 +24,9 @@ Start the application:
 
 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`.
+`./golem build` writes the browser shell to `dist/`. `./golem dev` defaults to
+`127.0.0.1:3000`; set an optional `host` and `port` in `golem.config.ts`, then restart
+the dev server. The terminal prints the usable address.
 
 ## Local source development
 

package/docs/local-cli.md

@@ -23,16 +23,25 @@ boundary so a hot-source workflow can select the CLI without changing HTTP start
 | 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 dev` | Refresh the browser build, then serve it at the `golem.config.ts` address (default `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.
+default server binds to loopback on port 3000. To use another local port or a
+specific tailnet address, export optional root settings from `golem.config.ts`:
+
+```ts
+export default { title: 'Golem', host: '100.64.0.10', port: 3000 }
+```
+
+`host` must be a nonempty string and `port` an integer from 1 through 65535.
+Configuration, build, and bind failures are printed by `./golem dev`. Restart
+the server after changing these settings.
 `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
+`src/dev-server.ts` exports `startDevServer(port = 3000, backend, stateDirectory, host = '127.0.0.1')`, 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "golem-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Starter kit and local CLI for Golem applications.",
   "type": "module",
   "files": [

package/src/cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { startDevServer } from './dev-server.ts';
 import { buildBrowser } from './browser-build.ts';
+import { loadAppConfig, serverUrl } from './config.ts';
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
@@ -12,8 +13,8 @@ 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.
+  dev     Serve the browser shell using golem.config.ts (127.0.0.1:3000 by default).
+          Restart after changing settings. Uses the local Codex runtime from the browser.
   build   Build the browser shell into dist/.
   doctor  Report local shell and backend readiness.
 
@@ -45,7 +46,7 @@ if (args.length || !['help', 'init', 'dev', 'build', 'doctor'].includes(command)
 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.`);
+The dev server defaults to 127.0.0.1:3000 and uses optional host/port from golem.config.ts.`);
       break;
     case 'build':
       try {
@@ -57,7 +58,8 @@ No network exposure is enabled; the dev server binds to loopback.`);
       break;
     case 'dev':
       try {
-        const server = await startDevServer();
+        const config = await loadAppConfig();
+        const server = await startDevServer(config.port, undefined, undefined, config.host);
         const stop = () => {
           server.close((error) => {
             process.removeListener('SIGINT', stop);
@@ -73,7 +75,7 @@ No network exposure is enabled; the dev server binds to loopback.`);
         };
         process.once('SIGINT', stop);
         process.once('SIGTERM', stop);
-        console.log('Golem shell: http://127.0.0.1:3000/ (Ctrl+C to stop)');
+        console.log(`Golem shell: ${serverUrl(config.host, config.port)} (Ctrl+C to stop)`);
       } catch (error) {
         console.error(`Cannot start Golem dev server: ${error instanceof Error ? error.message : String(error)}`);
         process.exitCode = 1;

package/src/config.ts

@@ -0,0 +1,35 @@
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export type AppConfig = { host: string; port: number }
+
+export async function loadAppConfig(): Promise<AppConfig> {
+  const path = resolve(process.cwd(), 'golem.config.ts')
+  let value: unknown
+  try {
+    value = (await import(pathToFileURL(path).href)).default
+  } catch (error) {
+    throw new Error(`Cannot load golem.config.ts: ${message(error)}`)
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('golem.config.ts must default-export an object')
+  }
+  const configured = value as { host?: unknown; port?: unknown }
+  const host: unknown = configured.host === undefined ? '127.0.0.1' : configured.host
+  const port: unknown = configured.port === undefined ? 3000 : configured.port
+  if (typeof host !== 'string' || !host.trim()) {
+    throw new Error('golem.config.ts host must be a nonempty string')
+  }
+  if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error('golem.config.ts port must be an integer from 1 to 65535')
+  }
+  return { host, port }
+}
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error)
+}
+
+export function serverUrl(host: string, port: number): string {
+  return `http://${host.includes(':') ? `[${host}]` : host}:${port}/`
+}

package/src/dev-server.ts

@@ -7,6 +7,7 @@ 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';
+import { serverUrl } from './config.ts';
 
 const appRoot = resolve(process.cwd());
 const root = pathToFileURL(`${process.cwd()}/dist/`);
@@ -22,13 +23,14 @@ export async function startDevServer(
   port = 3000,
   createBackend: (mode: SandboxMode, threadId?: string) => SessionBackend = (mode, threadId) => new CodexBackend(appRoot, mode, 'codex', [], threadId),
   stateDirectory = join(appRoot, '.golem'),
+  host = '127.0.0.1',
 ): 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) => {
+    void handleRequest(request, response, sessions, port, host, createBackend).catch((error) => {
       if (!response.headersSent) json(response, 400, { error: error instanceof Error ? error.message : 'Malformed request' });
       else response.destroy();
     });
@@ -36,7 +38,7 @@ export async function startDevServer(
   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));
+    server.listen(port, host, () => resolve(server));
   });
 }
 
@@ -45,12 +47,13 @@ async function handleRequest(
   response: import('node:http').ServerResponse,
   sessions: SessionManager,
   port: number,
+  host: string,
   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);
+      await handleApi(request, response, url, sessions, port, host, createBackend);
       return;
     }
     let pathname: string;
@@ -112,9 +115,9 @@ function triggerRebuild(session: Session): void {
   );
 }
 
-function mutationAllowed(request: import('node:http').IncomingMessage, port: number): boolean {
+function mutationAllowed(request: import('node:http').IncomingMessage, port: number, host: string): boolean {
   const origin = request.headers.origin;
-  return !origin || origin === `http://127.0.0.1:${port}` || origin === `http://localhost:${port}`;
+  return !origin || origin === serverUrl(host, port).slice(0, -1) || (host === '127.0.0.1' && origin === `http://localhost:${port}`);
 }
 
 async function handleApi(
@@ -123,6 +126,7 @@ async function handleApi(
   url: URL,
   sessions: SessionManager,
   port: number,
+  host: string,
   createBackend: (mode: SandboxMode) => SessionBackend,
 ): Promise<void> {
   if (request.method === 'GET' && url.pathname === '/api/runtime') {
@@ -131,7 +135,7 @@ async function handleApi(
     return;
   }
   if (request.method === 'POST' && url.pathname === '/api/sessions') {
-    if (!mutationAllowed(request, port)) return json(response, 403, { error: 'Cross-origin mutations are not allowed' });
+    if (!mutationAllowed(request, port, host)) 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' });
@@ -165,7 +169,7 @@ async function handleApi(
     return;
   }
   if (request.method === 'POST' && !match[2]) {
-    if (!mutationAllowed(request, port)) return json(response, 403, { error: 'Cross-origin mutations are not allowed' });
+    if (!mutationAllowed(request, port, host)) 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' });
@@ -180,7 +184,7 @@ async function handleApi(
     return;
   }
   if (request.method === 'POST' && match[2] === 'interrupt') {
-    if (!mutationAllowed(request, port)) return json(response, 403, { error: 'Cross-origin mutations are not allowed' });
+    if (!mutationAllowed(request, port, host)) return json(response, 403, { error: 'Cross-origin mutations are not allowed' });
     await session.interrupt();
     await session.flush();
     json(response, 200, { status: session.status });