@briancray/belte 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brian Cray
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @briancray/belte
+
+Isomorphic multimodal HTTP framework built for humans and machines in a single [Bun](https://bun.sh) runtime.
+
+Declare a backend once and it answers on every surface. Humans reach it through the web
+(server-rendered Svelte) and the command line; machines reach it through MCP and the command line.
+The bundler swaps the runtime per target — the call site, name, and behaviour stay identical.
+
+> **Requires Bun ≥ 1.3.** Modules are shipped as TypeScript and consumed directly by Bun.
+
+## Install
+
+```sh
+bun add @briancray/belte
+```
+
+`svelte` is a peer dependency; `tailwindcss` and `bun-plugin-tailwind` are optional peers.
+
+## At a glance
+
+Declare a remote function once:
+
+```ts
+// src/server/rpc/getOrder.ts
+import { GET } from '@briancray/belte/server/GET'
+import { json } from '@briancray/belte/server/json'
+
+export const getOrder = GET<{ id: string }>(async ({ id }) => json(await db.getOrder(id)))
+```
+
+Consume the same `getOrder` from each client:
+
+| Surface | How it is exposed | Call |
+| --- | --- | --- |
+| Browser / HTTP | function + `GET /rpc/getOrder?id=…` | `await getOrder({ id })` |
+| MCP | tool `getOrder` (with a schema) | `tools/call { name: "getOrder", arguments: { id } }` |
+| CLI | subcommand `getOrder` (with a schema) | `app getOrder --id 7` |
+
+Browser exposure is always on; MCP and CLI flip on automatically when a declaration carries a
+validation schema.
+
+## Documentation
+
+Full docs, the API reference, and runnable examples live in the
+[repository README](https://github.com/briancray/belte#readme).
+
+## License
+
+[MIT](./LICENSE) © Brian Cray

package/bin/belte.ts

@@ -0,0 +1,136 @@
+#!/usr/bin/env bun
+import { build } from '../src/build.ts'
+import { buildCli } from '../src/buildCli.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
+}
+
+/*
+Spawns the server under `bun --watch` against the dev entry. The dev entry
+re-runs the client build and eagerly imports every page/layout/rpc/socket
+module on each boot, so Bun's watcher sees them from the start and
+restarts the whole process whenever any file in the graph changes. The
+browser is not auto-reloaded — refresh manually after the server is back.
+*/
+async function dev(): Promise<void> {
+    const child = Bun.spawn({
+        cmd: ['bun', '--watch', '--preload', PRELOAD, DEV_ENTRY],
+        cwd,
+        stdio: ['inherit', 'inherit', 'inherit'],
+    })
+    process.exit(await child.exited)
+}
+
+// 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.
+// Awaits the child process so the parent's exit code mirrors the server's.
+async function start(): Promise<void> {
+    const child = Bun.spawn({
+        cmd: ['bun', '--preload', PRELOAD, SERVER_ENTRY],
+        cwd,
+        stdio: ['inherit', 'inherit', 'inherit'],
+    })
+    process.exit(await child.exited)
+}
+
+// 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. Defaults to full (backend embedded, runs
+// locally); `--thin` builds the remote client (manifest only, needs APP_URL
+// at runtime). Discovery walks the rpc registry to bake the manifest in.
+// `--platforms a,b,c` cross-compiles per target — thin binaries land in
+// dist/cli-thin/<platform>/ (the layout the /__belte/cli download endpoint
+// streams), full binaries in dist/cli/<platform>/.
+async function cliCmd(): Promise<void> {
+    const targetFlag = parseFlag('target')
+    const outFlag = parseFlag('out')
+    const platformsFlag = parseFlag('platforms')
+    const thin = rest.includes('--thin')
+    const platforms = platformsFlag
+        ? platformsFlag.split(',').map((value) => normalizeTarget(value.trim()))
+        : undefined
+    await buildCli({
+        cwd,
+        target: targetFlag ? normalizeTarget(targetFlag) : undefined,
+        outfile: outFlag,
+        platforms,
+        thin,
+    })
+}
+
+// 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 compile [--target=<bun-...>] [--out=<path>]\n' +
+            '                                       build a standalone server executable\n' +
+            '  belte cli [--thin] [--target=<bun-...>] [--out=<path>] [--platforms=<a,b,c>]\n' +
+            '                                       build the cli binary (full by default — runs\n' +
+            '                                       locally; --thin builds the remote client;\n' +
+            '                                       --platforms cross-compiles per platform)',
+    )
+    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 === 'compile') {
+    await compileCmd()
+} else if (command === 'cli') {
+    await cliCmd()
+} else {
+    usage()
+}

package/package.json

@@ -0,0 +1,80 @@
+{
+    "name": "@briancray/belte",
+    "version": "0.1.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/*": "./src/lib/server/*.ts",
+        "./server/rpc/*": "./src/lib/server/rpc/*.ts",
+        "./server/sockets/*": "./src/lib/server/sockets/*.ts",
+        "./server/prompts/*": "./src/lib/server/prompts/*.ts",
+        "./browser/*": "./src/lib/browser/*.ts",
+        "./browser/page": "./src/lib/browser/page.svelte.ts",
+        "./browser/navigate": "./src/lib/browser/page.svelte.ts",
+        "./browser/HttpError": "./src/lib/server/HttpError.ts",
+        "./mcp/*": "./src/lib/mcp/*.ts",
+        "./cli/*": "./src/lib/cli/*.ts",
+        "./shared/*": "./src/lib/shared/*.ts",
+        "./build": "./src/build.ts",
+        "./compile": "./src/compile.ts",
+        "./preload": "./src/preload.ts",
+        "./svelte-plugin": "./src/sveltePlugin.ts",
+        "./resolver-plugin": "./src/belteResolverPlugin.ts",
+        "./tsconfig": "./tsconfig.app.json"
+    },
+    "bin": {
+        "belte": "./bin/belte.ts"
+    },
+    "files": [
+        "src",
+        "bin",
+        "template",
+        "tsconfig.app.json"
+    ],
+    "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": "latest",
+        "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/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>