@abide/abide 0.104.0 → 0.105.1

package/src/server/claudeApi.ts

@@ -6,7 +6,7 @@
 // Every block of an assistant turn goes back as it came — a `thinking` block with its signature
 // included, which a turn continuing after a tool call is refused without.
 
-import { framedStream, framingPrefix } from '#shared/framing.ts'
+import { framedStream } from '#shared/framing.ts'
 import { refuse } from '#shared/refuse.ts'
 import type { AssistantEvent, Provider } from './assistant.ts'
 
@@ -112,10 +112,7 @@ export function claudeApi(config: ClaudeApiConfig): Provider {
                 const partials: string[] = []
                 const called: Block[] = []
                 let stop = 'end_turn'
-                for await (const chunk of framedStream(
-                    answered.body,
-                    framingPrefix('text/event-stream') as string,
-                )) {
+                for await (const chunk of framedStream(answered.body, 'sse')) {
                     const event = chunk as ApiEvent
                     switch (event.type) {
                         case 'message_start':

package/src/server/clientBundle.ts

@@ -0,0 +1,198 @@
+// 38.5, 38.16 — THE CLIENT BUNDLE, for both lanes that build one: `abide build`, which writes it to
+// disk for `abide start`, and `abide dev`'s worker, which holds it in memory. What decides what the
+// bundle IS — its plugins and their order, whether there is a page to boot, how a stylesheet's
+// addresses are written, the manifest — is here once, so dev resolves an address the way the
+// built app does by construction; a lane picks only a `mode`. And both answer it at
+// `/__abide/client/<name>` through `bundleServer`, differing in where a byte is read from and how
+// long a browser may keep it.
+
+import { CLIENT_ADDRESS } from '#shared/ADDRESSES.ts'
+import { abideModules, type Compilation, tablePath } from './abideModules.ts'
+import { appPlugins } from './appPlugins.ts'
+import { CLIENT_ENTRY } from './CLIENT_BUILD.ts'
+import { fenceServer } from './fenceServer.ts'
+import { type Manifest, manifestOf, NO_MANIFEST } from './manifestOf.ts'
+import { type Encoding, negotiateEncoding } from './negotiateEncoding.ts'
+
+/** One file the bundle produced: its bytes — a stylesheet's already rewritten — and its kind. */
+type BundledFile = {
+    bytes: Uint8Array<ArrayBuffer>
+    type: string
+    kind: Bun.BuildArtifact['kind']
+}
+
+/** A client bundle: every file it produced, by its name below `/__abide/client`, and its manifest. */
+export type ClientBundle = {
+    files: Map<string, BundledFile>
+    manifest: Manifest
+}
+
+/**
+ * The client bundle of the app at `root`, out of `compilation`, built for `mode`.
+ *
+ * `published` is each public file's source path to its address. `'build'` is 38.5's — minified and
+ * every name hashed; `'dev'` is 38.16's — unminified, the entry named by its source, with linked
+ * maps. A bundle that fails throws, its logs the error's.
+ *
+ * AN APP OF HANDLERS ALONE has no page to boot, and is bundled as nothing with no manifest.
+ */
+export async function clientBundle(
+    root: string,
+    compilation: Compilation,
+    published: Map<string, string>,
+    mode: 'build' | 'dev',
+): Promise<ClientBundle> {
+    const bundle: ClientBundle = { files: new Map(), manifest: NO_MANIFEST }
+    // A page among what compiled: the compiler writes the entry only where there is one to boot.
+    if (compilation.tables[`${CLIENT_ENTRY}.ts`] === undefined) return bundle
+    const built = await Bun.build({
+        // The entry is a table the plugin serves (`abideModules`), below the root.
+        entrypoints: [tablePath(root, `${CLIENT_ENTRY}.ts`)],
+        // The app's own root, because `Bun.build` opens the entry's directory otherwise, and the
+        // tables' is not on disk to open.
+        root,
+        // 16.28, 16.29 — the browser's view of the server: a `<script server>` is its stand-ins and a
+        // `server/` module refuses — FENCED FIRST, before the plugin that would serve the module. 38.43
+        // — then the app's own, as `bunfig.toml` declares them.
+        plugins: [
+            fenceServer(root, compilation.mounted),
+            abideModules(root, compilation),
+            ...(await appPlugins(root)),
+        ],
+        target: 'browser',
+        format: 'esm',
+        // So a destination's markup and bindings stay in the chunk its own route loads (30.11)
+        // rather than landing in the entry every page pays for.
+        splitting: true,
+        metafile: true,
+        // 36.15 — a stylesheet's `url('/fonts/…')` is the public file's address, not a path here,
+        // and `Bun.build` reads a leading `/` as a path on this disk and fails on it not being
+        // there. The list is the files that exist rather than every `/…`: a URL naming nothing the
+        // app serves is still worth a build error.
+        external: [...published.values()],
+        throw: false,
+        ...(mode === 'build'
+            ? {
+                  // 38.5 — MINIFIED, and EVERY NAME HASHED, the entry's included: chunks and assets are
+                  // already `[name]-[hash]` by default and the entry is not, which left the one file
+                  // every page loads served for a year under a name the next deploy writes different
+                  // bytes to. The manifest is how the document learns what the entry was called.
+                  //
+                  // NAMES KEPT, because a class's name is what an error reads to say what it was
+                  // handed (`canonicalKey`), and a production error naming `a e` is one nobody can
+                  // act on. It is free where it is paid: the JS the docs app's `/values` sends is
+                  // 25 600 bytes brotli with the names and without, against 31 900 unminified.
+                  minify: {
+                      whitespace: true,
+                      syntax: true,
+                      identifiers: true,
+                      keepNames: true,
+                  },
+                  naming: { entry: '[name]-[hash].[ext]' },
+              }
+            : {
+                  // 38.97 — a debugger in the browser reads the `.abide` (`withAbideSources`).
+                  sourcemap: 'linked' as const,
+                  // 38.16 — the entry named by its source, so what a browser loads and what a stack
+                  // trace names are the module the author wrote. A dev chunk that changed has to be
+                  // fetched again, and a name that changes with it is a cache the reload cannot clear.
+                  naming: {
+                      entry: '[name].[ext]',
+                      chunk: '[name]-[hash].[ext]',
+                      asset: '[name]-[hash].[ext]',
+                  },
+              }),
+    })
+    // THROWN RATHER THAN LOGGED: a build that emitted server modules and no bundle is an app that
+    // serves every page dead — the markup right and nothing wired — which is the one failure a
+    // reader cannot see. Dev catches it (38.17); the build stops on it.
+    if (!built.success)
+        throw new AggregateError(
+            built.logs,
+            `abide ${mode}: the client bundle failed`,
+        )
+    // The outputs are independent, so they are read at once rather than one after another.
+    const read = await Promise.all(
+        built.outputs.map((output) => output.arrayBuffer()),
+    )
+    for (let index = 0; index < built.outputs.length; index += 1) {
+        const output = built.outputs[index] as Bun.BuildArtifact
+        const name = output.path.slice(output.path.lastIndexOf('/') + 1)
+        let bytes = new Uint8Array(read[index] as ArrayBuffer)
+        if (name.endsWith('.css'))
+            bytes = new TextEncoder().encode(
+                stylesheetUnderMount(new TextDecoder().decode(bytes)),
+            )
+        bundle.files.set(name, { bytes, type: output.type, kind: output.kind })
+    }
+    bundle.manifest = manifestOf(built.metafile as Bun.BuildMetafile, root)
+    return bundle
+}
+
+// From the bundle's own directory up to the app's root: `../../` below `/__abide/client`.
+const UP_TO_ROOT = '../'.repeat(CLIENT_ADDRESS.split('/').length - 1)
+
+/**
+ * A built stylesheet with every root-absolute `url()` written relative to the bundle's directory.
+ *
+ * 16.10, 36.15 — THE SAME MECHANISM AS THE HANDLER WRAPPERS: the address is written relative to
+ * where the bundle is served and the browser resolves it against the sheet, so one build serves
+ * at the root and below a mount. What survives the build as `url(/…)` is a public file's address
+ * (the `external` list above), and the browser would resolve it against the origin. `//` is
+ * another host's.
+ */
+function stylesheetUnderMount(css: string): string {
+    return css.replace(
+        /url\((["']?)\/(?!\/)/g,
+        (_whole, quote: string) => `url(${quote}${UP_TO_ROOT}`,
+    )
+}
+
+/** A bundle file as it is answered: its type, its bytes, and each precompressed copy of them. */
+export type ServedFile = {
+    type: string
+    body: () => BodyInit
+    encoded: Partial<Record<Encoding, () => BodyInit>>
+}
+
+/**
+ * Answers `/__abide/client/<name>` out of `files`, each with `cacheControl`; `undefined` for any
+ * other address, and for a name the bundle does not hold.
+ *
+ * THE BUNDLE, ENUMERATED RATHER THAN RESOLVED. A request names a file in this set or it names
+ * nothing — there is no path to normalize, so `..` is not a case that has to be got right, and what
+ * is servable is exactly what the bundle produced.
+ */
+export function bundleServer(
+    files: Map<string, ServedFile>,
+    cacheControl: string,
+): (pathname: string, request: Request) => Response | undefined {
+    // Each file's encodings listed once, rather than on every request for it.
+    const offeredOf = new Map<string, Encoding[]>()
+    for (const [name, file] of files)
+        offeredOf.set(name, Object.keys(file.encoded) as Encoding[])
+    return (pathname, request) => {
+        if (!pathname.startsWith(`${CLIENT_ADDRESS}/`)) return undefined
+        const name = pathname.slice(CLIENT_ADDRESS.length + 1)
+        const file = files.get(name)
+        if (file === undefined) return undefined
+        const headers: Record<string, string> = {
+            'cache-control': cacheControl,
+            'content-type': file.type,
+        }
+        const offered = offeredOf.get(name) as Encoding[]
+        if (offered.length === 0) return new Response(file.body(), { headers })
+        headers.vary = 'accept-encoding'
+        // 38.29 — the precompressed copy where the request takes its encoding.
+        const encoding = negotiateEncoding(
+            request.headers.get('accept-encoding'),
+            offered,
+        )
+        const encoded =
+            encoding === undefined ? undefined : file.encoded[encoding]
+        if (encoding === undefined || encoded === undefined)
+            return new Response(file.body(), { headers })
+        headers['content-encoding'] = encoding
+        return new Response(encoded(), { headers })
+    }
+}

package/src/server/coerceArgs.ts

@@ -7,8 +7,8 @@
 // has declared no types, and its args stay the text they arrived as.
 
 import { numberFromText } from '#shared/numberFromText.ts'
+import { bareName } from '#shared/queryText.ts'
 import { type Gated, gateOf } from '#shared/reactive/argsContract.ts'
-import { bareName } from '#shared/rpcRequest.ts'
 
 export type Document = {
     type?: string | string[]

package/src/server/commands.ts

@@ -6,11 +6,9 @@
 import { resolve } from 'node:path' // bun exposes no path helpers of its own
 import { parseArgs } from 'node:util' // bun exposes no argv parser of its own yet
 import { MCP_ADDRESS, OPENAPI_ADDRESS } from '#shared/ADDRESSES.ts'
-import type { Mount } from './answerRpc.ts'
 import { banner } from './banner.ts'
-import { APP_PACKAGE, type AppPackage, config } from './config.ts'
-import type { App } from './createApp.ts'
-import { installServer } from './installServer.ts'
+import { type App, type AppHandle, enterApp } from './createApp.ts'
+import { stopOnSignalOrFault } from './faultPolicy.ts'
 import {
     appUrl,
     callHandler,
@@ -45,17 +43,10 @@ export type Host = {
     /** What usage and every message speak as: `abide`, or the name the executable was run by. */
     name: string
     /**
-     * The handler table the shell lists and a call reads a handler's method off — so a call is
-     * spelled the same whatever the handler's method, and `--method` is only for an app nobody here
-     * knows the table of. Empty where there is none to read, and never built to be read.
+     * The app the invocation means, found once off its flags (38.25): every command that serves,
+     * boots, lists or announces it derives from this one handle.
      */
-    handlers: (given: Given) => Promise<Mount[]>
-    /** The identity a script `run` resolves its configuration with. 27.3. */
-    appPackage: () => AppPackage
-    /** The app booted in this process: `openapi` and `mcp`'s answer where no `--url` is given. */
-    boot: () => Promise<App>
-    /** The app served, or the exit code of a refusal to. 38.6. */
-    serve: (given: Given) => Promise<App | number>
+    app: (given: Given) => AppHandle
     source: SourceCommands | undefined
 }
 
@@ -79,7 +70,8 @@ export async function runCommands(
         console.log(usage(host, commands))
         return 0
     }
-    if (command === undefined) return await shellOn(host, given)
+    if (command === undefined)
+        return await shellOn(host, host.app(given), given)
     for (const [name, , body] of commands)
         if (name.split(' ')[0] === command) return await body(given)
     console.error(
@@ -111,7 +103,7 @@ function commandsOf(host: Host): Row[] {
         [
             'run <file> [args…]',
             'run a script under the abide runtime',
-            (given) => run(host, given),
+            (given) => run(host, host.app(given), given),
             false,
         ],
         fromSource('dev', 'serve with the compiler in the loop', 'dev'),
@@ -120,23 +112,28 @@ function commandsOf(host: Host): Row[] {
             'compile every .abide under the app into .abide/',
             'build',
         ),
-        ['start', 'serve the app', (given) => start(host, given), false],
+        [
+            'start',
+            'serve the app',
+            (given) => start(host, host.app(given), given),
+            false,
+        ],
         [
             'call <address> [args]',
             'one call to one handler',
-            (given) => call(host, given),
+            (given) => call(host, host.app(given), given),
             false,
         ],
         [
             'openapi',
             'the OpenAPI document, written rather than served',
-            (given) => openapi(host, given),
+            (given) => openapi(host, host.app(given), given),
             false,
         ],
         [
             'mcp',
             "the app's MCP server over stdio",
-            (given) => mcp(host, given),
+            (given) => mcp(host, host.app(given), given),
             false,
         ],
         [
@@ -195,13 +192,12 @@ function usage(host: Host, commands: Row[]): string {
         return `${text}
   --port  the listen port the app is served on
   --url   the running app the shell, call, watch, openapi and mcp talk to
-  --out   the file openapi writes
 `
     text += `
   --root       the app's source directory, where its pages sit —
                src/ where you stand, or where you stand, whichever has one
-  --out        where the build goes, beside the app by default; the file openapi,
-               compile and bundle write — named after the app, where you stand
+  --out        where the build goes, beside the app by default; the file compile and
+               bundle write — named after the app, where you stand
   --port       the listen port for dev, start and the shell's app
   --url        the running app the shell, call, watch, openapi and mcp talk to
   --target     the platform compile builds for — linux-x64, darwin-arm64, windows-x64…
@@ -234,32 +230,63 @@ function parsed(argv: string[]) {
     })
 }
 
-/** The app served, with the address it answers at and the banner it is announced by. 38.6. */
+/**
+ * The app served and listening, with the address it answers at and the banner it is announced by —
+ * or the exit code of a refusal to. 38.6.
+ *
+ * Stopped on a signal or an unawaited fault ONCE SERVING, and not before: a boot that fails is
+ * 37.6's to fail hard.
+ */
 async function served(
     host: Host,
+    app: AppHandle,
     given: Given,
 ): Promise<{ app: App; url: string; heading: string } | number> {
     // 36.3 — `dev`, `build` and `start` each name the environment where the process was started with
     // none, and leave one it was started with exactly as given.
     process.env.NODE_ENV ??= 'production'
-    const app = await host.serve(given)
-    if (typeof app === 'number') return app
+    const booted = await booting(host, app, given)
+    if (typeof booted === 'number') return booted
+    const port = given.values.port
+    await booted.listen(port === undefined ? {} : { port: Number(port) })
+    stopOnSignalOrFault(booted)
     const server = LISTENING.server as Bun.Server<unknown>
     return {
-        app,
+        app: booted,
         url: withoutTrailingSlash(server.url.href),
-        heading: banner(host.name, 'start', host.appPackage(), server),
+        heading: banner(host.name, 'start', app.package, server),
     }
 }
 
+/** The app booted in this process, or the exit code of a refusal naming why there is none. */
+async function booting(
+    host: Host,
+    app: AppHandle,
+    given: Given,
+): Promise<App | number> {
+    const booted = await app.boot()
+    if (typeof booted === 'string') {
+        const command = given.positionals[0]
+        console.error(
+            `${command === undefined ? host.name : `${host.name} ${command}`}: ${booted}`,
+        )
+        return 1
+    }
+    return booted
+}
+
 /**
  * `start`: serves the app.
  *
  * 38.67 — READS NO INPUT, and hands back no code for the process to exit on: the process is the
  * server, for a container or a supervisor to stop.
  */
-async function start(host: Host, given: Given): Promise<number | undefined> {
-    const serving = await served(host, given)
+async function start(
+    host: Host,
+    app: AppHandle,
+    given: Given,
+): Promise<number | undefined> {
+    const serving = await served(host, app, given)
     if (typeof serving === 'number') return serving
     console.log(serving.heading)
     return undefined
@@ -273,24 +300,28 @@ async function start(host: Host, given: Given): Promise<number | undefined> {
  * as a remote one's is. 38.54 — `exit` stops the app. 38.55 — input that ends leaves it serving, and
  * hands back no code for the process to exit on.
  */
-async function shellOn(host: Host, given: Given): Promise<number | undefined> {
+async function shellOn(
+    host: Host,
+    app: AppHandle,
+    given: Given,
+): Promise<number | undefined> {
     const remote = remoteUrl(given.values.url)
     if (remote !== undefined) {
         const url = appUrl(remote)
         await shell({
             url,
-            handlers: await host.handlers(given),
+            handlers: await app.handlers(),
             heading: `${host.name}: ${url}`,
             local: false,
         })
         return 0
     }
-    const serving = await served(host, given)
+    const serving = await served(host, app, given)
     if (typeof serving === 'number') return serving
     // After the serve, which built the app where nothing had.
     const ended = await shell({
         url: serving.url,
-        handlers: await host.handlers(given),
+        handlers: await app.handlers(),
         heading: serving.heading,
         local: true,
     })
@@ -312,6 +343,7 @@ async function shellOn(host: Host, given: Given): Promise<number | undefined> {
  */
 async function run(
     host: Host,
+    app: AppHandle,
     { positionals: [, file, ...rest] }: Given,
 ): Promise<number | undefined> {
     if (file === undefined) {
@@ -322,11 +354,9 @@ async function run(
     }
     const path = resolve(file)
     process.argv = [process.argv[0] as string, path, ...rest]
-    // 38.57 — RE-RESOLVED, as `bootApp` does: a module this process loaded before the script may already have
-    // read the configuration, under no identity.
-    installServer()
-    APP_PACKAGE.current = host.appPackage()
-    config.invalidate()
+    // 38.57 — entered as `bootApp` enters it, its server blocks aside: a script is run against the
+    // app's source, which nothing built.
+    await enterApp({ hooks: undefined, package: app.package })
     await inScope(undefined, () => import(Bun.pathToFileURL(path).href))
     return undefined
 }
@@ -350,7 +380,7 @@ async function watch(host: Host, given: Given): Promise<number> {
     })
 }
 
-async function call(host: Host, given: Given): Promise<number> {
+async function call(host: Host, app: AppHandle, given: Given): Promise<number> {
     const {
         positionals: [, address, ...args],
         values: { url, method },
@@ -366,7 +396,7 @@ async function call(host: Host, given: Given): Promise<number> {
         address,
         args,
         method,
-        await host.handlers(given),
+        await app.handlers(),
     ).catch((thrown: Error) => ({ code: 1, text: thrown.message }))
     if (answered.text !== '')
         (answered.code === 0 ? console.log : console.error)(answered.text)
@@ -374,50 +404,55 @@ async function call(host: Host, given: Given): Promise<number> {
 }
 
 /**
- * A fetch against a generated surface, on the app `--url` names or on one booted here.
+ * A fetch against a generated surface, on the app `--url` names or on one booted here — or the exit
+ * code of a refusal to boot one.
  *
  * 38.9 — the app booted in this process derives it from the same route table the served one does.
  */
 async function surfaceAt(
     host: Host,
-    url: string | undefined,
+    app: AppHandle,
+    given: Given,
     address: string,
 ): Promise<
-    (
-        init?: RequestInit & { headers?: Record<string, string> },
-    ) => Promise<Response>
+    | ((
+          init?: RequestInit & { headers?: Record<string, string> },
+      ) => Promise<Response>)
+    | number
 > {
-    const remote = remoteUrl(url)
+    const remote = remoteUrl(given.values.url)
     if (remote !== undefined)
         return (init) =>
             fetch(`${appUrl(remote)}${address}`, {
                 ...init,
                 headers: { ...init?.headers, ...remoteHeaders() },
             })
-    const app = await host.boot()
+    const booted = await booting(host, app, given)
+    if (typeof booted === 'number') return booted
     return (init) =>
-        app.fetch(new Request(`http://abide.local${address}`, init))
+        booted.fetch(new Request(`http://abide.local${address}`, init))
 }
 
 /**
- * `openapi`: writes the OpenAPI document.
+ * `openapi`: prints the OpenAPI document — redirected to a file, where one is wanted.
  *
  * 38.9 — from `--url` where one is given and from the app in this process where not.
  */
 async function openapi(
     host: Host,
-    { values: { url, out } }: Given,
+    app: AppHandle,
+    given: Given,
 ): Promise<number> {
-    const answer = await (await surfaceAt(host, url, OPENAPI_ADDRESS))()
+    const ask = await surfaceAt(host, app, given, OPENAPI_ADDRESS)
+    if (typeof ask === 'number') return ask
+    const answer = await ask()
     if (!answer.ok) {
         console.error(
             `${host.name} openapi: the app answered ${answer.status}. The document lists every handler with openapi in its clients; none is.`,
         )
         return 1
     }
-    const text = JSON.stringify(await answer.json(), null, 4)
-    if (out === undefined) console.log(text)
-    else await Bun.write(resolve(out), `${text}\n`)
+    console.log(JSON.stringify(await answer.json(), null, 4))
     return 0
 }
 
@@ -427,8 +462,9 @@ async function openapi(
  * 38.9, 38.13 — a bridge a model client spawns and kills: each line in is a JSON-RPC message for
  * `/__abide/mcp`, and each answer is a line out.
  */
-async function mcp(host: Host, { values: { url } }: Given): Promise<number> {
-    const ask = await surfaceAt(host, url, MCP_ADDRESS)
+async function mcp(host: Host, app: AppHandle, given: Given): Promise<number> {
+    const ask = await surfaceAt(host, app, given, MCP_ADDRESS)
+    if (typeof ask === 'number') return ask
     for await (const line of console) {
         if (line.trim() === '') continue
         const answer = await ask({