@abide/abide 0.103.0 → 0.105.0

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({

package/src/server/createApp.ts

@@ -12,6 +12,7 @@ import { MOUNT, unmounted } from '#shared/mount.ts'
 import { RPC_SERVER } from '#shared/RPC_SERVER.ts'
 import { servedTable } from './abideModules.ts'
 import { type AppSources, answerRequest } from './answerRequest.ts'
+import type { Mount } from './answerRpc.ts'
 import { Mux, type MuxConnection } from './answerSocket.ts'
 import { appDirectories } from './appDirectories.ts'
 import { holdsApp } from './appTree.ts'
@@ -61,17 +62,69 @@ export interface App {
  */
 export async function createApp(): Promise<App> {
     const root = appRoot(undefined)
-    if (root === undefined)
-        throw new Error(
-            `abide: createApp found no app. Looked for a .abide under ${resolve('src')}, or under ${process.cwd()} where it has no src.`,
-        )
-    const out = await servedBuild(root)
-    if (out === undefined)
-        throw new Error(
-            `abide: createApp found nothing under ${root} to build.`,
-        )
-    const { loadBuild } = await import('./serveBuild.ts')
-    return bootApp(originUnder(root), () => loadBuild({ root, out }))
+    const app = await appOnDisk(
+        root === undefined ? undefined : { root, out: buildDirectory(root) },
+        (root) => servedBuild(root),
+    ).boot()
+    if (typeof app === 'string')
+        throw new Error(`abide: createApp found ${app}`)
+    return app
+}
+
+/**
+ * One app, as one invocation means it: FOUND ONCE, and everything a command derives — the banner's
+ * identity, the shell's handler table, the boot — read off this rather than found again from where
+ * the process happens to stand. An app on disk (`appOnDisk`), or the one an executable holds.
+ */
+export type AppHandle = {
+    /** 27.3's name and version: the banner's, and what a script `run` resolves its configuration with. */
+    package: AppPackage
+    /**
+     * The handler table of a build already there, NEVER ONE MADE FOR THE ASKING: `call` and the
+     * shell are aimed at a running app (38.7), which this tree may not even be. Empty where none.
+     */
+    handlers: () => Promise<Mount[]>
+    /** The app's build made this process's, and booted — or why there is nothing to boot. */
+    boot: () => Promise<App | string>
+}
+
+/** Why there is no app where none was named: where 38.25 looked. 38.26. */
+export function noAppHere(): string {
+    return `no app here. Looked for a .abide under ${resolve('src')}, or under ${process.cwd()} where it has no src.`
+}
+
+/**
+ * The app on disk at `found` — its source root and build directory, both absolute — or the
+ * refusal where nothing was found. `built` makes its build this process's (`serveBuild`, which
+ * builds one nobody built — 38.100) and answers the directory it is in, or `undefined` where
+ * nothing under the root builds.
+ */
+export function appOnDisk(
+    found: { root: string; out: string } | undefined,
+    built: (root: string, out: string) => Promise<string | undefined>,
+): AppHandle {
+    if (found === undefined)
+        return {
+            package: packageUnder(process.cwd()),
+            handlers: async () => [],
+            boot: async () => noAppHere(),
+        }
+    const { root, out } = found
+    const origin = originUnder(root)
+    return {
+        package: origin.package,
+        handlers: async () => {
+            const { serveBuild } = await import('./serveBuild.ts')
+            if (!(await serveBuild(root, out, async () => undefined))) return []
+            return (await servedTable(root)).handlers
+        },
+        boot: async () => {
+            const served = await built(root, out)
+            if (served === undefined) return `nothing under ${root} to build.`
+            const { loadBuild } = await import('./serveBuild.ts')
+            return bootApp(origin, () => loadBuild({ root, out: served }))
+        },
+    }
 }
 
 /**
@@ -152,22 +205,43 @@ export function originUnder(root: string): AppOrigin {
  */
 export type BootedApp = App & { openMux(): Mux }
 
+/**
+ * Enters the app as this process's server — every slot `#shared` leaves for one filled, the app's
+ * identity set, every server block imported — and re-resolves the configuration: the one preamble
+ * `bootApp`, a script `run` and the desktop launcher each start with.
+ *
+ * 37.1 — EVERY SERVER BLOCK, imported for what it CALLS: every hook it runs is filed by the time the
+ * import settles, which is before `onStart` is composed around a boot. 38.57 — RE-RESOLVED: a module
+ * this process loaded first may already have read the configuration, under no identity.
+ */
+export async function enterApp(origin: AppOrigin): Promise<void> {
+    installServer()
+    APP_PACKAGE.current = origin.package
+    if (origin.hooks !== undefined) await origin.hooks()
+    config.invalidate()
+}
+
 /** An `App` booted over the sources `load` supplies, inside the app's `onStart` hooks. */
 export async function bootApp(
     origin: AppOrigin,
     load: () => Promise<AppSources>,
 ): Promise<BootedApp> {
-    installServer()
-    // 37.1 — EVERY SERVER BLOCK, imported for what it CALLS: every hook it runs is filed by the
-    // time the import settles, which is before `onStart` is composed around the boot.
-    if (origin.hooks !== undefined) await origin.hooks()
+    await enterApp(origin)
+    return bootEntered(load)
+}
 
+/**
+ * `bootApp` in a process `enterApp` already entered the app in: the desktop launcher's, which enters
+ * once for the hooks its own page reads and boots again on every start.
+ */
+export async function bootEntered(
+    load: () => Promise<AppSources>,
+): Promise<BootedApp> {
     // 37.4 — THE BOOT, INSIDE `onStart`. 37.6 — a throw out of a hook or out of the boot rejects
     // `createApp`, and nothing is served.
     //
     // 42.2 — THE CONFIGURATION IS READ AS PART OF THE BOOT, so a configuration that does not resolve
     // is a boot that fails rather than a first request that does.
-    APP_PACKAGE.current = origin.package
     let sources: AppSources | undefined
     await compose(inOrder(HOOKS.starts), async () => {
         config.invalidate()

package/src/server/deferredBuilds.ts

@@ -0,0 +1,175 @@
+// 41.28 — A CHILD WHOSE SETUP MADE A CALL IS BUILT AS A PAGE IS: after the turn.
+// A component is set up where its parent's markup invokes it, so its build cannot wait inline; it is
+// left as a marker in the parent's head and body, built once the turn has run, and written in where
+// its marker stands. A child whose setup made no call builds where it stands, as before, and pays a
+// counter read on either side of its setup for the difference.
+//
+// THE MARKERS ARE NEVER IN WHAT IS SENT. Every one is replaced before `composePage` answers, and the
+// nonce is never written anywhere, so no text an author or a caller supplies can stand in for one.
+
+import { regionMarkup } from '#shared/anchorMarkup.ts'
+import { isReactive, isStreaming, loadOf } from '#shared/reactive/index.ts'
+import type { Rendered } from './render.ts'
+import type { PageCall } from './requestScope.ts'
+
+// SYNCHRONOUS SETUP IS WHAT MAKES ONE COUNTER ENOUGH. 34.3 keeps a setup from awaiting, so no other
+// request's render runs between a component's two reads, however many renders are in flight.
+let callsInRenders = 0
+
+/** How many calls renders have made, read on either side of a component's setup. */
+export function callsInRender(): number {
+    return callsInRenders
+}
+
+/** Counts a call a page's render made (`reachedInRender`). */
+export function noteCallInRender(): void {
+    callsInRenders += 1
+}
+
+/** A deferred child: its record, and the page's calls its setup made, marked with its build. */
+type Deferred = { rendered: Rendered; callsFrom: number; callsTo: number }
+
+type Build = { deferred: Deferred[]; calls: PageCall[] }
+
+/**
+ * The render whose markup is being built. Set only while `pass` runs, which is synchronous, so
+ * renders in flight never see each other's.
+ */
+let building: Build | undefined
+
+const NONCE = crypto.randomUUID()
+const MARKER = new RegExp(`\u0000${NONCE}([hb])(\\d+)\u0000`, 'g')
+
+/** The page's calls so far, for a child to note where its setup's begin; `-1` outside a build. */
+export function callsMadeSoFar(): number {
+    return building === undefined ? -1 : building.calls.length
+}
+
+/**
+ * Where a child that deferred stands in its parent's markup: a marker in the head and in the body,
+ * or `undefined` where no page is being built and the child builds where it stands.
+ */
+export function deferBuild(
+    rendered: Rendered,
+    heads: string[],
+    callsFrom: number,
+): string | undefined {
+    if (building === undefined) return undefined
+    const at = building.deferred.length
+    building.deferred.push({
+        rendered,
+        callsFrom,
+        callsTo: building.calls.length,
+    })
+    heads.push(`\u0000${NONCE}h${at}\u0000`)
+    return regionMarkup(`\u0000${NONCE}b${at}\u0000`)
+}
+
+/**
+ * `build`'s markup, with every child it deferred built after the turn — and the children those
+ * defer after another — each written in where its marker stands.
+ */
+export async function buildDeferred(
+    calls: PageCall[],
+    build: () => { head: string; body: string },
+): Promise<{ head: string; body: string }> {
+    const state: Build = { deferred: [], calls }
+    let built = { head: '', body: '' }
+    pass(state, () => {
+        built = build()
+    })
+    if (state.deferred.length === 0) return built
+    const fills: { head: string; body: string }[] = []
+    let from = 0
+    while (from < state.deferred.length) {
+        await new Promise((settled) => setImmediate(settled))
+        const to = state.deferred.length
+        pass(state, () => {
+            for (let at = from; at < to; at++)
+                fills.push(filled((state.deferred[at] as Deferred).rendered))
+        })
+        from = to
+    }
+    return {
+        head: expanded(built.head, fills),
+        body: expanded(built.body, fills),
+    }
+}
+
+/**
+ * Marks every call not yet marked: settled or not, as the markup just built read it.
+ *
+ * 41.25 — READ WHERE THE MARKUP HAS JUST BEEN BUILT, before anything has run since: a call that
+ * settles a microtask later was painted in flight, and marked settled it has hydration choose an
+ * arm the server never painted.
+ */
+export function markPainted(calls: PageCall[]): void {
+    for (const call of calls)
+        if (call.painted === undefined) call.painted = paintedSettled(call)
+}
+
+// One synchronous build pass, and the calls it built from marked at its end — all but those a
+// child it deferred made, which its own pass marks.
+function pass(state: Build, run: () => void): void {
+    const deferredFrom = state.deferred.length
+    building = state
+    try {
+        run()
+    } finally {
+        building = undefined
+    }
+    const { calls, deferred } = state
+    for (let at = 0; at < calls.length; at++) {
+        const call = calls[at] as PageCall
+        if (
+            call.painted !== undefined ||
+            ownedByDeferred(at, deferred, deferredFrom)
+        )
+            continue
+        call.painted = paintedSettled(call)
+    }
+}
+
+function ownedByDeferred(
+    call: number,
+    deferred: Deferred[],
+    from: number,
+): boolean {
+    for (let at = from; at < deferred.length; at++) {
+        const child = deferred[at] as Deferred
+        if (call >= child.callsFrom && call < child.callsTo) return true
+    }
+    return false
+}
+
+// 41.26 — a call that streams is never marked.
+function paintedSettled({ reached }: PageCall): boolean {
+    return (
+        isReactive(reached) &&
+        loadOf(reached) === undefined &&
+        !isStreaming(reached)
+    )
+}
+
+/** 35.16 — a document is written by the outermost component alone, and `rendered` is placed. */
+export function refuseDocument(rendered: Rendered): void {
+    if (rendered.document !== undefined)
+        throw new Error(
+            'abide: a component that writes <html> is placed inside another, and only the outermost component writes the document. RULEBOOK 35.16.',
+        )
+}
+
+function filled(rendered: Rendered): { head: string; body: string } {
+    refuseDocument(rendered)
+    return { head: rendered.head, body: rendered.body }
+}
+
+function expanded(
+    markup: string,
+    fills: { head: string; body: string }[],
+): string {
+    return markup.replace(MARKER, (_, kind: string, at: string) => {
+        const fill = fills[Number(at)] as { head: string; body: string }
+        return expanded(kind === 'h' ? fill.head : fill.body, fills)
+    })
+}