@briancray/belte 0.5.3 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@briancray/belte",
-    "version": "0.5.3",
+    "version": "0.7.0",
     "type": "module",
     "description": "Isomorphic multimodal HTTP framework built for humans and machines in a single Bun runtime",
     "license": "MIT",
@@ -42,7 +42,6 @@
         "./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",
         "./bundle/*": "./src/lib/bundle/*.ts",
         "./shared/*": "./src/lib/shared/*.ts",
         "./build": "./src/build.ts",

package/src/controlServerWorker.ts

@@ -2,13 +2,13 @@ import { mkdir, rm } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { bindConnectedFlag } from './lib/bundle/bindConnectedFlag.ts'
 import { bindRequestNavigate } from './lib/bundle/bindRequestNavigate.ts'
-import { findFreePort } from './lib/bundle/findFreePort.ts'
 import { listenLocalControlServer } from './lib/bundle/listenLocalControlServer.ts'
 import { probeBelteServer } from './lib/bundle/probeBelteServer.ts'
 import { resolveServerBinary } from './lib/bundle/resolveServerBinary.ts'
 import { resolveWebviewLib } from './lib/bundle/resolveWebviewLib.ts'
 import { stableLocalPort } from './lib/bundle/stableLocalPort.ts'
 import { waitForServer } from './lib/bundle/waitForServer.ts'
+import { findOpenPort } from './lib/server/runtime/findOpenPort.ts'
 import { parsePort } from './lib/server/runtime/parsePort.ts'
 import { appDataDir } from './lib/shared/appDataDir.ts'
 import { bundleLayout } from './lib/shared/bundleLayout.ts'
@@ -166,17 +166,18 @@ only one embedded server runs at a time.
 The port the embedded server binds. A `PORT` configured in the data-dir `.env`
 (where the config form writes), the shipped binary-dir `.env`, or the launcher's
 own env is honored — so the server answers at a fixed, known address another
-machine can reliably connect to. With none set, a free port is chosen (the
-historical behaviour). Precedence matches the server's own env stack: shell >
-data-dir > binary-dir. A configured port is used as-is and not second-guessed —
-if it's taken, the bind failure surfaces rather than silently moving.
+machine can reliably connect to. With none set, the first open port at/above
+3000 is chosen (matching the standalone server's default). Precedence matches
+the server's own env stack: shell > data-dir > binary-dir. A configured port is
+used as-is and not second-guessed — if it's taken, the bind failure surfaces
+rather than silently moving.
 */
 async function resolveEmbeddedPort(): Promise<number> {
     const [dataDirEnv, binaryDirEnv] = await Promise.all([
         readEnvFile(dataDirEnvPath()),
         readEnvFile(binaryDirEnvPath()),
     ])
-    return parsePort(process.env.PORT ?? dataDirEnv.PORT ?? binaryDirEnv.PORT) ?? findFreePort()
+    return parsePort(process.env.PORT ?? dataDirEnv.PORT ?? binaryDirEnv.PORT) ?? findOpenPort(3000)
 }
 
 async function startEmbeddedServer(timeoutMs?: number): Promise<string> {

package/src/lib/browser/cache.ts

@@ -61,6 +61,16 @@ export function cache<Args, Return>(
         store.subscribe(key)
         const existing = store.entries.get(key)
         /*
+        Tag an existing entry with this call's scope so a later
+        cache.invalidate({ scope }) reaches entries hydrated from the SSR
+        snapshot (which carry a value but no scope) without a refetch. Merge
+        rather than replace so a read tagging one group can't drop tags a
+        different read site already added.
+        */
+        if (existing && options?.scope !== undefined) {
+            existing.scope = mergeScopes(existing.scope, options.scope)
+        }
+        /*
         Snapshot warm path: hydration pre-decoded the SSR body onto the
         entry, so the decoded variant returns it synchronously — the first
         {#await} render resolves without a microtask suspension and matches
@@ -109,6 +119,7 @@ function invokeWithCache<Args>(
         request,
         ttl,
         expiresAt: undefined as number | undefined,
+        scope: options?.scope === undefined ? undefined : toScopeSet(options.scope),
     }
     store.entries.set(key, entry)
     function deleteIfCurrent() {
@@ -150,8 +161,18 @@ function shareable(promise: Promise<Response>): Promise<Response> {
     return promise.then((response) => response.clone())
 }
 
-cache.invalidate = function invalidate<Args, Return>(
-    arg?: AnyRemote<Args, Return> | CacheOptions['key'],
+/*
+Three call shapes:
+  invalidate()                  → drop everything
+  invalidate(fn)                → drop one function's calls (method+url prefix)
+  invalidate({ key?, scope? })  → drop one entry by key and/or tagged groups
+A selector with both fields drops the union; an empty or unmatched selector
+is a no-op. `key` accepts the same string/array/object the cache() `key`
+option does and is canonicalised the same way. `scope` accepts one tag or an
+array; an entry is dropped when its tag set shares any tag with the request.
+*/
+function invalidate<Args, Return>(
+    arg?: AnyRemote<Args, Return> | Pick<CacheOptions, 'key' | 'scope'>,
 ): void {
     const store = activeCacheStore()
     if (arg === undefined) {
@@ -175,12 +196,26 @@ cache.invalidate = function invalidate<Args, Return>(
         emit(store, affected)
         return
     }
-    const target = canonicalKey(arg)
-    if (store.entries.delete(target)) {
-        emit(store, [target])
-    }
+    const target = arg.key !== undefined ? canonicalKey(arg.key) : undefined
+    const byKey = target !== undefined && store.entries.has(target) ? [target] : []
+    const requestedScopes = arg.scope === undefined ? undefined : toScopeSet(arg.scope)
+    const byScope =
+        requestedScopes === undefined
+            ? []
+            : Array.from(store.entries.values())
+                  .filter(
+                      (entry) =>
+                          entry.scope !== undefined && intersects(entry.scope, requestedScopes),
+                  )
+                  .map((entry) => entry.key)
+    /* emit() dedupes via a Set, so a key matching both criteria is harmless. */
+    const affected = [...byKey, ...byScope]
+    affected.forEach((key) => store.entries.delete(key))
+    emit(store, affected)
 }
 
+cache.invalidate = invalidate
+
 function resolveKey<Args>(
     rawFn: RawRemoteFunction<Args>,
     args: Args | undefined,
@@ -199,6 +234,21 @@ function canonicalKey(value: CacheOptions['key']): string {
     return canonicalJson(value)
 }
 
+/* Normalizes a scope option (one tag or many) to a Set for O(1) membership. */
+function toScopeSet(scope: string | string[]): Set<string> {
+    return new Set(typeof scope === 'string' ? [scope] : scope)
+}
+
+/* Folds new tags into an entry's existing set without duplicating them. */
+function mergeScopes(existing: Set<string> | undefined, incoming: string | string[]): Set<string> {
+    return new Set([...(existing ?? []), ...toScopeSet(incoming)])
+}
+
+/* True when an entry's tags and the requested tags overlap on any tag. */
+function intersects(entryScopes: Set<string>, requestedScopes: Set<string>): boolean {
+    return Array.from(requestedScopes).some((scope) => entryScopes.has(scope))
+}
+
 /*
 Detail is a Set so each subscriber's `has(key)` check is O(1) regardless of
 how many keys a single invalidate touches.

package/src/lib/server/runtime/createServer.ts

@@ -29,6 +29,7 @@ import { cacheControlForAsset } from './cacheControlForAsset.ts'
 import { containsTraversal } from './containsTraversal.ts'
 import { createAssetHeaderCache } from './createAssetHeaderCache.ts'
 import { createPublicAssetServer } from './createPublicAssetServer.ts'
+import { findOpenPort } from './findOpenPort.ts'
 import { globToPathSet } from './globToPathSet.ts'
 import { logBrowserOnlyRoutes } from './logBrowserOnlyRoutes.ts'
 import { parsePort } from './parsePort.ts'
@@ -108,7 +109,9 @@ export async function createServer({
     distDir = `${process.cwd()}/dist`,
     publicDir = `${process.cwd()}/src/browser/public`,
     resourcesDir = `${process.cwd()}/src/mcp/resources`,
-    port = parsePort(process.env.PORT) ?? 3000,
+    // No PORT set → scan for the first open port at/above 3000 rather than
+    // hardcoding 3000, so a second app boots cleanly instead of colliding.
+    port = parsePort(process.env.PORT) ?? findOpenPort(3000),
 }: {
     pages: Pages
     rpc: RemoteRoutes

package/src/lib/server/runtime/findOpenPort.ts

@@ -0,0 +1,35 @@
+// Ports probed upward from `start` before giving up and letting the kernel assign one.
+const SCAN_RANGE = 100
+
+/*
+Returns the first bindable TCP port at or above `start`, probing upward.
+Used when no PORT is configured so the server lands on a predictable
+3000+ port (3000, then 3001, …) instead of a random kernel-assigned one —
+running a second app just steps to the next free port. Each probe binds a
+throwaway server and stops it; like any release-then-rebind there's a tiny
+race before the real listener takes the port, negligible for a local boot.
+After SCAN_RANGE occupied ports it gives up scanning and lets the kernel
+assign any free port (bind to 0).
+*/
+export function findOpenPort(start: number): number {
+    for (let port = start; port < start + SCAN_RANGE; port++) {
+        try {
+            return bindAndRelease(port)
+        } catch {
+            // port in use — try the next one up
+        }
+    }
+    // every candidate was taken; bind to 0 so the kernel picks a free port
+    return bindAndRelease(0)
+}
+
+/*
+Binds a throwaway server to `port` (0 = let the kernel assign one), reads the
+actual bound port, and releases it. Throws if the port is already in use.
+*/
+function bindAndRelease(port: number): number {
+    const probe = Bun.serve({ port, fetch: () => new Response() })
+    const bound = probe.port as number
+    probe.stop(true)
+    return bound
+}

package/src/lib/shared/types/CacheEntry.ts

@@ -11,6 +11,10 @@ layer hands callers a decoded view derived from this same promise.
 snapshot body is pre-decoded synchronously so the first client render can
 read it without a microtask hop and byte-match the SSR DOM. Live fetches
 leave it undefined and take the async decode path.
+
+`scope` holds the cache() call's scope tags as a Set so
+`cache.invalidate({ scope })` can drop every entry sharing any tag with O(1)
+membership; a re-read merges new tags in rather than replacing them.
 */
 export type CacheEntry = {
     key: string
@@ -19,4 +23,5 @@ export type CacheEntry = {
     ttl: number | undefined
     expiresAt: number | undefined
     value?: unknown
+    scope?: Set<string>
 }

package/src/lib/shared/types/CacheOptions.ts

@@ -3,8 +3,12 @@ Options for cache(). `key` overrides the auto-derived WeakMap key — useful
 when sharing entries across calls or stripping noisy args. `ttl` is the
 milliseconds-past-resolve that the entry stays live: omitted = forever, 0 =
 dedupe only (entry dropped once the promise settles), any other number = TTL.
+`scope` is one or more free-form tags grouping unrelated calls so one
+`cache.invalidate({ scope })` drops every entry sharing any of them — pass an
+array when a call belongs to multiple invalidation groups.
 */
 export type CacheOptions = {
     key?: string | unknown[] | Record<string, unknown>
     ttl?: number
+    scope?: string | string[]
 }

package/src/lib/bundle/findFreePort.ts

@@ -1,14 +0,0 @@
-/*
-Asks the OS for an unused TCP port by binding a throwaway Bun server to
-port 0 (the kernel assigns a free port), reading the assigned port, then
-stopping it immediately. There is an unavoidable race between releasing
-the port here and the server child re-binding it, but for a
-single-user bundle launch the window is negligible.
-*/
-export function findFreePort(): number {
-    const probe = Bun.serve({ port: 0, fetch: () => new Response() })
-    // A TCP server bound to port 0 always reports a numeric assigned port.
-    const port = probe.port as number
-    probe.stop(true)
-    return port
-}