@belte/belte 0.19.0

package/bin/belte.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env bun
+import { build } from '../src/build.ts'
+import { buildCli } from '../src/buildCli.ts'
+import { bundleApp } from '../src/bundleApp.ts'
+import { compile } from '../src/compile.ts'
+import { normalizeTarget } from '../src/lib/shared/normalizeTarget.ts'
+import { scaffold } from '../src/scaffold.ts'
+
+const PRELOAD = new URL('../src/preload.ts', import.meta.url).pathname
+const SERVER_ENTRY = new URL('../src/serverEntry.ts', import.meta.url).pathname
+const DEV_ENTRY = new URL('../src/devEntry.ts', import.meta.url).pathname
+const cwd = process.cwd()
+const [, , command, ...rest] = process.argv
+
+// Reads `--name=value` or `--name value` from the trailing argv tail.
+function parseFlag(name: string): string | undefined {
+    const prefix = `--${name}=`
+    const match = rest.find((arg) => arg.startsWith(prefix))
+    if (match) {
+        return match.slice(prefix.length)
+    }
+    const index = rest.indexOf(`--${name}`)
+    if (index !== -1 && index + 1 < rest.length) {
+        return rest[index + 1]
+    }
+    return undefined
+}
+
+/*
+Runs a long-lived child (server, job, script) and owns its shutdown. Ctrl+C
+delivers SIGINT to the whole foreground process group, so without a parent
+handler the parent's default action kills it instantly — abandoning the
+`await child.exited` and orphaning the child, which (for a server) can then
+linger holding the port. Forwarding the signal and awaiting the child's exit
+(with a SIGKILL watchdog for a wedged child) guarantees the child is reaped
+before the parent leaves. Mirrors the child's exit code so callers and CI see
+the real result.
+*/
+async function runChild(cmd: string[]): Promise<never> {
+    const child = Bun.spawn({ cmd, cwd, stdio: ['inherit', 'inherit', 'inherit'] })
+    const forward = (signal: NodeJS.Signals) => {
+        child.kill(signal)
+        setTimeout(() => child.kill('SIGKILL'), 3000).unref()
+    }
+    process.on('SIGINT', () => forward('SIGINT'))
+    process.on('SIGTERM', () => forward('SIGTERM'))
+    process.exit(await child.exited)
+}
+
+/*
+Runs the dev orchestrator (devEntry) — not `bun --watch`. The orchestrator owns
+the loop: it builds the client, spawns the server as a child on a fixed dev
+port, watches src/ recursively, and on any change rebuilds + restarts the child.
+The server mounts a live-reload channel under dev, so the browser reloads itself
+when the restarted server comes back. runChild forwards Ctrl+C so the
+orchestrator (and its server child) shut down cleanly.
+*/
+async function dev(): Promise<void> {
+    await runChild(['bun', '--preload', PRELOAD, DEV_ENTRY])
+}
+
+// Performs a single client build with no server attached (for CI / static deploys).
+async function buildOnce(): Promise<void> {
+    await build({ cwd })
+}
+
+// Starts the production server against an already-built dist directory.
+async function start(): Promise<void> {
+    await runChild(['bun', '--preload', PRELOAD, SERVER_ENTRY])
+}
+
+/*
+Runs an arbitrary script under the belte preload — same runtime as the server,
+so jobs/scripts get .svelte compilation, belte/* + $server/$shared resolution,
+and the .css no-op loader for free. Everything after `run` is forwarded
+verbatim: the first token is the script, the rest are its argv (bun stops
+parsing its own flags at the script path).
+*/
+async function runCmd(): Promise<void> {
+    if (rest.length === 0) {
+        console.error('usage: belte run <file> [args...]')
+        process.exit(1)
+    }
+    await runChild(['bun', '--preload', PRELOAD, ...rest])
+}
+
+// Parses the --target and --out flags and produces a standalone executable.
+async function compileCmd(): Promise<void> {
+    const targetFlag = parseFlag('target')
+    const outFlag = parseFlag('out')
+    await compile({
+        cwd,
+        target: targetFlag ? normalizeTarget(targetFlag) : undefined,
+        outfile: outFlag,
+    })
+}
+
+// Builds the standalone CLI binary — a thin remote client (manifest baked in)
+// that ships the compiled server beside it, so it can talk to a remote server
+// or spawn a local instance (`<name> start`). Discovery walks the rpc registry
+// to bake the manifest in. `--platforms a,b,c` cross-compiles per target into
+// dist/cli-thin/<platform>/ (cli + server) — the layout the /__belte/cli
+// download endpoint streams. For just the server, use `belte compile`.
+async function cliCmd(): Promise<void> {
+    const targetFlag = parseFlag('target')
+    const outFlag = parseFlag('out')
+    const platformsFlag = parseFlag('platforms')
+    const platforms = platformsFlag
+        ? platformsFlag.split(',').map((value) => normalizeTarget(value.trim()))
+        : undefined
+    await buildCli({
+        cwd,
+        target: targetFlag ? normalizeTarget(targetFlag) : undefined,
+        outfile: outFlag,
+        platforms,
+    })
+}
+
+// Assembles a movable, self-contained app bundle for the host platform —
+// the server binary, the launcher, and the webview lib together (a .app on
+// macOS, a flat directory elsewhere). Unsigned; for distribution to other
+// users the bundle still needs platform signing/notarization.
+async function bundleCmd(): Promise<void> {
+    await bundleApp({ cwd })
+}
+
+// Scaffolds the bundled template into a new project directory.
+async function scaffoldCmd(): Promise<void> {
+    const name = rest.find((arg) => !arg.startsWith('--'))
+    if (!name) {
+        console.error('usage: bunx belte scaffold <project-name>')
+        process.exit(1)
+    }
+    await scaffold({ cwd, name })
+}
+
+// Prints the CLI synopsis to stderr and exits non-zero. Marked `never` because the process is gone.
+function usage(): never {
+    console.error(
+        'usage:\n' +
+            '  bunx belte scaffold <project-name>   scaffold a new belte project\n' +
+            '  belte dev                            build + run with hot reload\n' +
+            '  belte build                          build the client into dist/_app/\n' +
+            '  belte start                          run the production server against dist/\n' +
+            '  belte run <file> [args...]           run a script under the belte preload\n' +
+            '                                       (jobs, one-off scripts — same runtime as\n' +
+            '                                       the server). For tests, add\n' +
+            '                                       preload = ["@belte/belte/preload"] under\n' +
+            '                                       [test] in bunfig.toml and use `bun test`\n' +
+            '  belte compile [--target=<bun-...>] [--out=<path>]\n' +
+            '                                       build a standalone server executable\n' +
+            '  belte cli [--target=<bun-...>] [--out=<path>] [--platforms=<a,b,c>]\n' +
+            '                                       build the cli binary — a thin remote client that\n' +
+            '                                       ships the server beside it (connect to a remote\n' +
+            '                                       server or `start` a local instance; --platforms\n' +
+            '                                       cross-compiles per platform)\n' +
+            '  belte bundle                         build a movable, self-contained app\n' +
+            '                                       bundle for this platform (unsigned). Boots\n' +
+            '                                       into a connect screen — start the embedded\n' +
+            '                                       server or connect to a remote one',
+    )
+    process.exit(1)
+}
+
+if (command === 'scaffold') {
+    await scaffoldCmd()
+} else if (command === 'dev') {
+    await dev()
+} else if (command === 'build') {
+    await buildOnce()
+} else if (command === 'start') {
+    await start()
+} else if (command === 'run') {
+    await runCmd()
+} else if (command === 'compile') {
+    await compileCmd()
+} else if (command === 'cli') {
+    await cliCmd()
+} else if (command === 'bundle') {
+    await bundleCmd()
+} else {
+    usage()
+}

package/package.json

@@ -0,0 +1,110 @@
+{
+    "name": "@belte/belte",
+    "version": "0.19.0",
+    "type": "module",
+    "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
+    "license": "MIT",
+    "author": "Brian Cray",
+    "homepage": "https://github.com/briancray/belte#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/briancray/belte.git",
+        "directory": "packages/belte"
+    },
+    "bugs": {
+        "url": "https://github.com/briancray/belte/issues"
+    },
+    "keywords": [
+        "bun",
+        "svelte",
+        "ssr",
+        "spa",
+        "framework",
+        "isomorphic",
+        "rpc",
+        "mcp",
+        "cli"
+    ],
+    "engines": {
+        "bun": ">=1.3.0"
+    },
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "exports": {
+        "./server/GET": "./src/lib/server/GET.ts",
+        "./server/POST": "./src/lib/server/POST.ts",
+        "./server/PUT": "./src/lib/server/PUT.ts",
+        "./server/PATCH": "./src/lib/server/PATCH.ts",
+        "./server/DELETE": "./src/lib/server/DELETE.ts",
+        "./server/HEAD": "./src/lib/server/HEAD.ts",
+        "./server/socket": "./src/lib/server/socket.ts",
+        "./server/json": "./src/lib/server/json.ts",
+        "./server/jsonl": "./src/lib/server/jsonl.ts",
+        "./server/sse": "./src/lib/server/sse.ts",
+        "./server/error": "./src/lib/server/error.ts",
+        "./server/redirect": "./src/lib/server/redirect.ts",
+        "./server/request": "./src/lib/server/request.ts",
+        "./server/cookies": "./src/lib/server/cookies.ts",
+        "./server/env": "./src/lib/server/env.ts",
+        "./server/appDataDir": "./src/lib/server/appDataDir.ts",
+        "./server/server": "./src/lib/server/server.ts",
+        "./server/AppModule": "./src/lib/server/AppModule.ts",
+        "./server/agent": "./src/lib/server/agent.ts",
+        "./server/rpc/defineVerb": "./src/lib/server/rpc/defineVerb.ts",
+        "./server/sockets/defineSocket": "./src/lib/server/sockets/defineSocket.ts",
+        "./server/prompts/definePrompt": "./src/lib/server/prompts/definePrompt.ts",
+        "./browser/page": "./src/lib/browser/page.svelte.ts",
+        "./browser/navigate": "./src/lib/browser/page.svelte.ts",
+        "./browser/subscribe": "./src/lib/browser/subscribe.ts",
+        "./shared/bundled": "./src/lib/shared/bundled.ts",
+        "./shared/cache": "./src/lib/shared/cache.ts",
+        "./shared/HttpError": "./src/lib/shared/HttpError.ts",
+        "./shared/withJsonSchema": "./src/lib/shared/withJsonSchema.ts",
+        "./shared/log": "./src/lib/shared/log.ts",
+        "./mcp/createMcpServer": "./src/lib/mcp/createMcpServer.ts",
+        "./bundle/BundleWindow": "./src/lib/bundle/BundleWindow.ts",
+        "./bundle/BundleMenu": "./src/lib/bundle/BundleMenu.ts",
+        "./bundle/BundleMenuItem": "./src/lib/bundle/BundleMenuItem.ts",
+        "./bundle/onMenu": "./src/lib/bundle/onMenu.ts",
+        "./test/createTestClient": "./src/lib/test/createTestClient.ts",
+        "./test/clearVerbRegistry": "./src/lib/test/clearVerbRegistry.ts",
+        "./tsconfig": "./tsconfig.app.json",
+        "./build": "./src/build.ts",
+        "./compile": "./src/compile.ts",
+        "./preload": "./src/preload.ts",
+        "./svelte-plugin": "./src/sveltePlugin.ts",
+        "./resolver-plugin": "./src/belteResolverPlugin.ts",
+        "./browser/remoteProxy": "./src/lib/browser/remoteProxy.ts",
+        "./browser/socketProxy": "./src/lib/browser/socketProxy.ts",
+        "./server/prompts/renderPromptTemplate": "./src/lib/server/prompts/renderPromptTemplate.ts"
+    },
+    "bin": {
+        "belte": "./bin/belte.ts"
+    },
+    "files": [
+        "src",
+        "bin",
+        "template",
+        "tsconfig.app.json",
+        "CHANGELOG.md"
+    ],
+    "peerDependencies": {
+        "svelte": "^5.0.0",
+        "bun-plugin-tailwind": "*",
+        "tailwindcss": "^4.0.0"
+    },
+    "peerDependenciesMeta": {
+        "bun-plugin-tailwind": {
+            "optional": true
+        },
+        "tailwindcss": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "bun-plugin-tailwind": "^0.1.2",
+        "tailwindcss": "^4.0.0"
+    }
+}

package/src/App.svelte

@@ -0,0 +1,31 @@
+<script lang="ts">
+import type { Component } from 'svelte'
+import type { Page as PageState } from './lib/browser/page.svelte.ts'
+
+let {
+    state,
+}: {
+    state: {
+        page: PageState
+        render: { Layout: Component | undefined; Page: Component | undefined }
+    }
+} = $props()
+
+let Layout = $derived(state.render.Layout)
+let PageView = $derived(state.render.Page)
+let params = $derived(state.page.params)
+</script>
+
+{#if Layout}
+    <Layout>
+        {#if PageView}
+            {#key PageView}
+                <PageView {...params} />
+            {/key}
+        {/if}
+    </Layout>
+{:else if PageView}
+    {#key PageView}
+        <PageView {...params} />
+    {/key}
+{/if}

package/src/appEntry.ts

@@ -0,0 +1,151 @@
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import { disconnectedHtml } from './_virtual/bundle-disconnected.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import bundleWindow from './_virtual/bundle-window.ts'
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+import programName from './_virtual/cli-name.ts'
+import type { BundleMenu } from './lib/bundle/BundleMenu.ts'
+import type { BundleWindow } from './lib/bundle/BundleWindow.ts'
+import { openWebview } from './lib/bundle/openWebview.ts'
+import { envSchemaStore } from './lib/server/runtime/envSchemaStore.ts'
+import { jsonSchemaForSchema } from './lib/shared/jsonSchemaForSchema.ts'
+import { log } from './lib/shared/log.ts'
+
+/*
+Compiled bundle launcher entry — the executable a bundle runs. Instead of a blank
+window it boots into a connect screen, letting the user either connect to a remote
+server by URL or start the embedded server binary that ships beside this launcher.
+
+The connect screen is served by a tiny control server, but that server can't live
+on this main thread: `openWebview` calls `webview_run`, a native UI loop that
+blocks the thread (and its JS event loop) until the window closes, so an
+in-process `Bun.serve` would never answer. The control server runs in a Worker
+instead (see controlServerWorker.ts) and hands back the origin to point the window
+at; it also owns the embedded-server child and the native menu flag, since neither
+can be driven from a main thread frozen inside webview_run.
+
+Bun doesn't apply this build's plugins to the worker entry, so the worker can't
+import belte's virtual modules; this entry imports them (the connect-screen HTML,
+the app title) and passes them in the worker's `init` message.
+
+The window owns the main thread; on close we tell the worker to reap its child.
+*/
+const window = bundleWindow as BundleWindow
+const title = window.title ?? programName
+
+/*
+Derive the config form's JSON Schema here (the worker can't import the virtuals
+that carry the schema) and pass the plain object through init — the validator
+itself isn't serializable, but its JSON Schema is. Undefined when the app
+declares no config, so the connect screen never gates Start.
+
+Default source is src/server/config.ts's env schema, so one declaration drives
+both boot validation and the setup form. Imported with skipValidation set — we
+want the schema's shape, not a boot check the launcher has no business running.
+`window.config` replaces it when set, for a bundle form that should differ from
+the env schema.
+*/
+envSchemaStore.skipValidation = true
+// @ts-expect-error virtual module resolved by belteResolverPlugin
+await import('./_virtual/config.ts')
+const formSchema = window.config ?? envSchemaStore.schema
+const configSchema = formSchema ? jsonSchemaForSchema(formSchema) : undefined
+
+/*
+Spawn the control server worker. `__BELTE_WORKER_ENTRY__` is the worker's absolute
+path, injected by bundleApp via Bun's `define` so the specifier is a static literal
+at build time — that's what makes `bun build --compile` embed the worker module
+into the standalone binary. A relative specifier resolves against the build's cwd
+(the consumer project), not this file, so it isn't found; a
+`new URL(..., import.meta.url)` specifier isn't embedded at all.
+*/
+declare const __BELTE_WORKER_ENTRY__: string
+const worker = new Worker(__BELTE_WORKER_ENTRY__)
+
+worker.addEventListener('error', (event: ErrorEvent) => {
+    log.error(`control server worker failed: ${event.message}`)
+})
+
+// Hand the worker the plugin-resolved data it can't import itself, then start it.
+worker.postMessage({
+    type: 'init',
+    init: { disconnectedHtml: disconnectedHtml as string, title, programName, configSchema },
+})
+
+/*
+The worker, once bound, resolves where the window should open and posts both the
+control-server `origin` (for the File-menu action URLs) and the `target` to point
+the window at now: the live server when it could resume the last connection, else
+the connect screen. Resolving before this means a successful resume opens straight
+at the app — no connect-screen flash — at the cost of a brief window-less moment
+while it boots/probes (the OS shows the launching dock icon meanwhile).
+*/
+const { origin, target } = await new Promise<{ origin: string; target: string }>((resolve) => {
+    worker.addEventListener('message', (event: MessageEvent) => {
+        const data = event.data as { type: string; origin?: string; target?: string }
+        if (data.type === 'ready' && data.origin && data.target) {
+            resolve({ origin: data.origin, target: data.target })
+        }
+    })
+})
+
+/*
+The built-in File menu (Start / Disconnect), placed before Edit. Each item is a
+`navigate` repointing the window at a control-server URL the connect screen
+interprets; the internal `role` drives the native validateMenuItem: gating (Start
+when disconnected, Disconnect when connected). There's no Connect item — Disconnect
+already returns to the connect screen, whose form is the place to point at another
+server. Roled items are launcher-only, so they carry an extra field the public
+BundleMenuItem type doesn't advertise — modelled here with a local type and bridged
+to BundleMenu when handed to openWebview (which only serialises the menu to JSON).
+*/
+type FileMenuItem =
+    | { separator: true }
+    | {
+          label: string
+          shortcut?: string
+          navigate: string
+          role: 'start' | 'disconnect'
+      }
+const fileMenu: { label: string; items: FileMenuItem[] } = {
+    label: 'File',
+    items: [
+        { label: 'Start Server', navigate: `${origin}/?action=start`, role: 'start' },
+        { separator: true },
+        { label: 'Disconnect', navigate: `${origin}/?action=disconnect`, role: 'disconnect' },
+    ],
+}
+
+log.info(`opening ${title} window at ${target}`)
+await openWebview({
+    url: target,
+    title,
+    width: window.width,
+    height: window.height,
+    menu: window.menu,
+    fileMenu: fileMenu as unknown as BundleMenu,
+    // Forward the window handle so the worker can bounce it back to the connect
+    // screen if the connected server stops responding.
+    onWindow: (handle) => {
+        if (handle) {
+            worker.postMessage({ type: 'window', handle: Number(handle) })
+        }
+    },
+})
+
+/*
+Window closed — have the worker reap the embedded server child and stop its
+control server before we exit, since both live on the worker thread. Bounded by a
+timeout so a wedged worker can't keep the launcher alive.
+*/
+await new Promise<void>((resolve) => {
+    worker.addEventListener('message', (event: MessageEvent) => {
+        if ((event.data as { type?: string }).type === 'shutdownDone') {
+            resolve()
+        }
+    })
+    worker.postMessage({ type: 'shutdown' })
+    setTimeout(resolve, 1000)
+})
+worker.terminate()
+process.exit(0)

package/src/assets/app.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<link rel="stylesheet" href="/_app/client.css" />
+<!--ssr:head-->
+</head>
+<body>
+<div id="app"><!--ssr:body--></div>
+<!--ssr:state-->
+<script type="module" src="/_app/client.js"></script>
+</body>
+</html>