@abide/abide 0.101.0 → 0.103.0

package/src/server/reportHealth.ts

@@ -9,7 +9,7 @@ import { isRecord } from '#shared/isRecord.ts'
 import { namedLogger } from '#shared/log.ts'
 import abidePackage from '../../package.json' with { type: 'json' }
 import { appIdentity, config } from './config.ts'
-import { HOOKS } from './hooks.ts'
+import { HOOKS, inOrder } from './hooks.ts'
 
 const HEALTH_LOG = namedLogger('abide:health')
 
@@ -23,7 +23,7 @@ export async function reportHealth(): Promise<Health> {
         abide: abidePackage.version,
         startedAt: STARTED_AT,
     }
-    for (const report of HOOKS.health) {
+    for (const report of inOrder(HOOKS.health)) {
         let answered: unknown
         try {
             answered = await report()

package/src/server/requestScope.ts

@@ -11,6 +11,7 @@
 
 import { AsyncLocalStorage } from 'node:async_hooks' // bun implements AsyncLocalStorage and has no context-carrying api of its own
 import { Cookies } from '#shared/cookies.ts'
+import type { Params } from '#shared/matchRoute.ts'
 import type { Principal } from '#shared/principal.ts'
 import { SCOPING, type Scope } from '#shared/reactive/scoping.ts'
 import type { RpcRequest } from '#shared/rpcRequest.ts'
@@ -51,6 +52,14 @@ export type RequestScope = Scope & {
     trace: { id: string; span: string; flags: string } | undefined
     /** `undefined` where the scope was opened without one — 42.8's scope, which 22.1 throws in. */
     request: Request | undefined
+    /**
+     * The route the request matched, once routing has run: the file route whose hooks answer it.
+     *
+     * 37.5 — which `onError` hooks an error in this request reaches.
+     */
+    route: string | undefined
+    /** What that route matched in the address, for the answer its rungs reach (16.14). */
+    params: Params | undefined
     /**
      * The app that opened this scope: the `App.fetch` `RPC_SERVER.raw` answers through, and its MCP
      * surface.
@@ -158,6 +167,8 @@ export function scopeFor(
         principal: undefined,
         applied: false,
         request: given,
+        route: undefined,
+        params: undefined,
         received,
         app,
         response: { status: 200, headers: new Headers() },
@@ -376,7 +387,7 @@ export function handlerTook(rpc: object, duration: number): void {
 /**
  * Adds `duration` to the time spent in rungs.
  *
- * 21.20 — or takes it back out where it was the centre's.
+ * 21.20 — or takes it back out where it was the center's.
  */
 export function rungsTook(duration: number): void {
     const timing = STORAGE.getStore()?.timing

package/src/server/runBuild.ts

@@ -0,0 +1,24 @@
+// The CLI, spawned rather than imported: the compiler is not reachable from the server seam.
+const ABIDE_BIN = Bun.fileURLToPath(
+    new URL('../../bin/abide.ts', import.meta.url),
+)
+
+/**
+ * `abide build` of the app under `root` into `out`, run as the CLI.
+ *
+ * SPAWNED RATHER THAN IMPORTED: the compiler is not reachable from the server seam.
+ */
+export async function runBuild(root: string, out: string): Promise<void> {
+    const child = Bun.spawn(
+        [process.execPath, ABIDE_BIN, 'build', '--root', root, '--out', out],
+        { stdout: 'ignore', stderr: 'pipe' },
+    )
+    const [exitCode, said] = await Promise.all([
+        child.exited,
+        new Response(child.stderr).text(),
+    ])
+    if (exitCode !== 0)
+        throw new Error(
+            `abide: could not build the app under ${root}.\n${said}`,
+        )
+}

package/src/server/runCompiled.ts

@@ -1,4 +1,4 @@
-// 38.51 — A COMPILED APP'S COMMAND LINE: `abide`'s list (`commands.ts`), over the app the executable
+// 38.50 — A COMPILED APP'S COMMAND LINE: `abide`'s list (`commands.ts`), over the app the executable
 // holds rather than one on disk, and spoken under the name it was started by — a `--platforms` build
 // is `ledger-linux-x64`, and that is what a reader types.
 
@@ -9,11 +9,11 @@ import { type BuildParts, builtSources, serveApp } from './serveBuild.ts'
 export async function runCompiled(
     origin: AppOrigin,
     parts: BuildParts,
-    // 38.57 — every specifier a script `run` may import out of the executable: abide's own entries
-    // and the app's handler modules, each to the module it holds.
+    // 38.56 — every specifier a script `run` may import out of the executable: abide's own entries
+    // and the app's `.abide` modules, each to the module it holds.
     specifiers: Record<string, () => Promise<Record<string, unknown>>>,
 ): Promise<void> {
-    // REGISTERED AT START AND LOADED ON FIRST IMPORT: a handler module a script never names never
+    // REGISTERED AT START AND LOADED ON FIRST IMPORT: an app module a script never names never
     // runs its top level, as it would not under `abide run`.
     Bun.plugin({
         name: 'abide:compiled-specifiers',
@@ -30,7 +30,7 @@ export async function runCompiled(
         handlers: async () => parts.handlers,
         appPackage: () => origin.package,
         boot: () => bootApp(origin, () => builtSources(parts)),
-        // 38.50.
+        // 38.49.
         serve: ({ values: { port } }) =>
             serveApp(
                 origin,

package/src/server/runDesktop.ts

@@ -1,4 +1,4 @@
-// 38.71 — WHAT `abide bundle` WRITES, STARTED WITH NO COMMAND: a window on the app. Given a command
+// 38.70 — WHAT `abide bundle` WRITES, STARTED WITH NO COMMAND: a window on the app. Given a command
 // it is the executable `abide compile` writes (`runCompiled`), so a terminal still reaches every one.
 //
 // ONE PROCESS. The app, the launcher's own page and the window share it: AppKit's events are drained
@@ -25,18 +25,19 @@ import {
 import { APP_PACKAGE, configuredMount, dataDirectory } from './config.ts'
 import { configFields } from './configFields.ts'
 import { type App, type AppOrigin, bootApp } from './createApp.ts'
-import { reportUnexpected } from './hooks.ts'
+import { executableName } from './executableName.ts'
+import { HOOKS, inOrder, reportUnexpected } from './hooks.ts'
 import { installServer } from './installServer.ts'
-import type { LauncherOptions } from './launcherOptions.ts'
+import { launcherOf } from './launcherOptions.ts'
 import { type Launch, launcherPage } from './launcherPage.ts'
 import { installMenu, menuBar, type NativeItem } from './nativeMenu.ts'
 import { randomToken } from './randomToken.ts'
-import { type Component, render } from './render.ts'
+import { type Component, renderDocument } from './render.ts'
 import { LISTENING } from './requestScope.ts'
 import { runCompiled } from './runCompiled.ts'
 import { type BuildParts, builtSources } from './serveBuild.ts'
 
-/** What the launcher did last, and what its forms held, kept across launches. 38.74. */
+/** What the launcher did last, and what its forms held, kept across launches. 38.73. */
 type Remembered = {
     last: { start: Record<string, string> } | { connect: string } | null
     values: Record<string, string>
@@ -50,15 +51,17 @@ type Failure = {
     issues: Record<string, string[]>
 }
 
-/** What `abide bundle` read out of `src/bundle/`, carried in the executable. */
+/** What `abide bundle` read of the launcher's files, carried in the executable. */
 export type Desktop = {
-    options: LauncherOptions
-    /** 38.83 — `src/bundle/launch.abide`, where the app has one. */
+    /** 38.82 — `src/launcher.abide`'s page, where the app has one that paints. */
     launch:
         | (() => Promise<{ default: (props: Launch) => Component }>)
         | undefined
-    /** The document the launch page renders into, its stylesheet already in its head. */
-    shell: string
+    /** The document the launch page renders into, its stylesheet already in its head (38.84). */
+    document: string
+    /** 38.101 — the app's icon as a data URL, and the accent taken from it. */
+    icon: string | undefined
+    accent: string | undefined
 }
 
 const LOOPBACK = '127.0.0.1'
@@ -79,14 +82,24 @@ export async function runDesktop(
 async function launch(
     origin: AppOrigin,
     load: () => ReturnType<typeof builtSources>,
-    { options, launch: launchPage, shell }: Desktop,
+    { launch: launchModule, document, icon, accent }: Desktop,
 ): Promise<void> {
     installServer()
     APP_PACKAGE.current = origin.package
-    // 37.1 — imported for what it files, so the start form reads `onConfig`.
+    // 37.1 — imported for what it files, so the start form reads `onConfig` and the launcher's
+    // `onLauncher` is filed.
     await origin.hooks?.()
-    const appName =
-        options.name ?? (origin.package.name ?? 'app').replace(/^@[^/]+\//, '')
+    // 38.85 — a launcher page that fails to load leaves the built-in page, with its defaults.
+    const launchPage = await launchModule?.().catch((thrown: unknown) => {
+        reportUnexpected(thrown)
+        return undefined
+    })
+    // 38.80 — what its `onLauncher` answers.
+    const options = launcherOf(inOrder(HOOKS.launcher).at(-1)?.())
+    // 38.81 — an `onLauncher` answer the checker would have refused, written where nothing checked it.
+    if (typeof options === 'string')
+        throw new Error(`abide: ${options}. RULEBOOK 38.81.`)
+    const appName = executableName(origin.package.name)
     const directory = dataDirectory(origin.package.name ?? 'app')
     const stateFile = `${directory}/desktop.json`
     const remembered: Remembered = {
@@ -149,21 +162,24 @@ async function launch(
                 )
                 return connected === undefined ? onwards() : page('connect')
             }
+            // The Connect… menu item asks for the page with its connect form open.
             return page(
                 url.searchParams.get('focus') === 'connect'
                     ? 'connect'
-                    : 'start',
+                    : undefined,
             )
         },
     })
     const base = `${launcher.url.origin}/${token}/`
-    // 38.72 — the answer to a start or a connect that took: the app the window now shows.
+    // 38.71 — the answer to a start or a connect that took: the app the window now shows.
     const onwards = (): Response =>
         new Response(null, {
             status: 303,
             headers: { location: current?.url ?? base },
         })
-    const page = async (focus: 'start' | 'connect'): Promise<Response> => {
+    const page = async (
+        focus: 'start' | 'connect' | undefined,
+    ): Promise<Response> => {
         const shown = failure
         failure = undefined
         const props: Launch = {
@@ -173,17 +189,21 @@ async function launch(
             fields: configFields(derived()),
             url: remembered.url,
             failure: shown,
-            focus: shown?.form ?? (options.start ? focus : 'connect'),
+            focus:
+                shown?.form ??
+                (focus === 'connect' && options.connect ? focus : undefined),
+            icon,
+            accent,
         }
         const headers = { 'content-type': 'text/html; charset=utf-8' }
         if (launchPage !== undefined)
             try {
                 return new Response(
-                    await render((await launchPage()).default(props), shell),
+                    await renderDocument(launchPage.default(props), document),
                     { headers },
                 )
             } catch (thrown) {
-                // 38.86 — the built-in page stands in for one that failed.
+                // 38.85 — the built-in page stands in for one that failed.
                 reportUnexpected(thrown)
             }
         return new Response(launcherPage(props), { headers })
@@ -196,7 +216,7 @@ async function launch(
             await leaving.app.stop().catch(reportUnexpected)
     }
 
-    // 38.73 — the form's values are the environment the app is booted under, so 27.8 coerces them
+    // 38.72 — the form's values are the environment the app is booted under, so 27.8 coerces them
     // and 27.7's schema refuses them as it would any other.
     async function start(
         values: Record<string, string>,
@@ -215,7 +235,7 @@ async function launch(
         }
         try {
             await app
-                // 38.76.
+                // 38.75.
                 .listen({ hostname: LOOPBACK, port: remembered.port })
                 // The port the last launch served on, so the app's origin — and its storage with
                 // it — is the one it had; any free one where that is taken.
@@ -296,7 +316,7 @@ async function launch(
                     types: 'Q@:@',
                     args: [FFIType.ptr],
                     returns: FFIType.u64,
-                    // NSTerminateCancel: 38.77 — the app is stopped first, and the process ends after.
+                    // NSTerminateCancel: 38.76 — the app is stopped first, and the process ends after.
                     run: () => {
                         quit()
                         return 0
@@ -382,20 +402,20 @@ async function launch(
         ),
         null,
     )
-    // 38.89 — THE MENU BAR IS THE PAGE'S: the defaults until the page the window loads tells it
+    // 38.88 — THE MENU BAR IS THE PAGE'S: the defaults until the page the window loads tells it
     // what its route exports, and again after every navigation it makes.
     const showMenu = (told: NativeItem[]): void =>
         installMenu(menuBar(appName, options.connect, told), (item) => {
             if (item.role === 'connect')
                 return navigate(`${base}?focus=connect`)
-            // 38.75.
+            // 38.74.
             if (item.role === 'disconnect') {
                 remembered.last = null
                 void remember()
                 return void disconnect().then(() => navigate(base))
             }
             if (item.role === 'reload') return void send(view, 'reload')
-            // 38.91, 38.92 — the page that numbered the item does what it means.
+            // 38.90, 38.91 — the page that numbered the item does what it means.
             if (item.id !== undefined)
                 send(
                     view,
@@ -433,7 +453,7 @@ async function launch(
         nsString('abideMenu'),
     )
     const navigate = (address: string): void => {
-        // 38.93.
+        // 38.92.
         showMenu([])
         send(
             view,
@@ -485,7 +505,7 @@ async function launch(
         send(window, 'setTitle:', nsString(title))
     }, DRAIN_MILLISECONDS)
 
-    // 38.74 — WHAT IT DID LAST, done again.
+    // 38.73 — WHAT IT DID LAST, done again.
     const last = remembered.last
     if (options.start && last !== null && 'start' in last)
         await start(last.start)

package/src/server/serveBuild.ts

@@ -1,4 +1,4 @@
-// 38.6 and 38.11 — `abide start` and a compiled app: the built app, over http. The request path is
+// 38.6 and 38.10 — `abide start` and a compiled app: the built app, over http. The request path is
 // `answerRequest`'s, shared with `abide dev`; what this module is, is the SUPPLIER — where each part
 // comes from when the parts are what `abide build` produced.
 //
@@ -8,19 +8,22 @@
 
 import { CLIENT_ADDRESS } from '#shared/ADDRESSES.ts'
 import {
+    type Compilation,
+    serveCompilation,
+    servedTable,
+} from './abideModules.ts'
+import {
+    type AppSources,
     appSources,
-    type LoadedSources,
-    type ServerTable,
     type SourceParts,
 } from './answerRequest.ts'
-import type { Mount } from './answerRpc.ts'
 import {
     CLIENT_DIRECTORY,
+    COMPILATION,
     ENCODING_SUFFIX,
     MANIFEST,
     PUBLIC_DIRECTORY,
 } from './CLIENT_BUILD.ts'
-import { componentImports } from './componentImports.ts'
 import { type App, type AppOrigin, bootApp } from './createApp.ts'
 import { stopOnSignalOrFault } from './faultPolicy.ts'
 import type { Manifest } from './manifestOf.ts'
@@ -30,13 +33,13 @@ import {
     type Encoding,
     negotiateEncoding,
 } from './negotiateEncoding.ts'
-import { shellUnder } from './render.ts'
+import { runBuild } from './runBuild.ts'
 
 /**
  * What `abide build` produced, as the parts an `App` is booted over.
  *
  * Read off disk by `abide start` (`loadBuild`), and out of the executable itself by a compiled app
- * (38.11). ONE SHAPE, so the two are answered by one path and differ only in where a byte is read
+ * (38.10). ONE SHAPE, so the two are answered by one path and differ only in where a byte is read
  * from — a file is a PATH in both, and `Bun.file` reads the executable's own the same way it reads
  * the disk's.
  */
@@ -53,7 +56,7 @@ export type BuildParts = Omit<SourceParts, 'client' | 'explained'> & {
  */
 export async function serveApp(
     origin: AppOrigin,
-    load: () => Promise<LoadedSources>,
+    load: () => Promise<AppSources>,
     port: number | undefined,
 ): Promise<App> {
     const app = await bootApp(origin, load)
@@ -64,63 +67,51 @@ export async function serveApp(
 }
 
 /**
- * A loader for a handler's module, out of the app's source tree.
+ * Serves the compilation `abide build` kept in `out` to this process's imports; `false` where there
+ * is none, because the app under `root` holds nothing to build.
  *
- * `compiled` is where the app's components were compiled to, which a `.abide` the module imports
- * lands on (`componentImports`).
+ * 38.6 — what `abide start` boots: no compiler is loaded, and every `.abide` the app imports is
+ * answered out of what the build compiled. 38.100 — AN APP NOBODY BUILT IS BUILT, by `build`, rather
+ * than refused, so every caller boots the same way whether or not a build came first. The CLI passes
+ * its own build, in-process; anything else spawns it.
  */
-export function sourceModuleLoader(
+export async function serveBuild(
     root: string,
-    compiled: string,
-): (source: string) => Promise<Record<string, unknown>> {
-    Bun.plugin(componentImports(root, compiled))
-    return (source) => import(Bun.pathToFileURL(`${root}/${source}`).href)
-}
-
-/** The handler table a build wrote into `directory`. */
-export async function handlersIn(directory: string): Promise<Mount[]> {
-    const rpc = (await import(
-        Bun.pathToFileURL(`${directory}/rpc.ts`).href
-    )) as {
-        handlers: Mount[]
+    out: string,
+    build: (root: string, out: string) => Promise<unknown> = runBuild,
+): Promise<boolean> {
+    const path = `${out}/${COMPILATION}`
+    if (!(await Bun.file(path).exists())) {
+        await build(root, out)
+        // A FRESH HANDLE: one taken before the build wrote the file reads it as empty.
+        if (!(await Bun.file(path).exists())) return false
     }
-    return rpc.handlers
+    serveCompilation(root, (await Bun.file(path).json()) as Compilation)
+    return true
 }
 
-/** What `abide build` left on disk, as the sources an `App` is booted over. */
+/**
+ * What `abide build` left on disk, as the sources an `App` is booted over — its compilation served
+ * already (`serveBuild`).
+ */
 export async function loadBuild(options: {
     /**
-     * The app's source root — the directory `ui/` and `server/` sit under, and the one 35.6's
-     * shell is resolved against.
+     * The app's source root — the directory its pages sit under.
      */
     root: string
     /** Where `abide build` put its output. */
     out: string
-}): Promise<LoadedSources> {
-    if (!(await Bun.file(`${options.out}/server.ts`).exists()))
-        throw new Error(
-            `abide: no build at ${options.out}. Run \`abide build\` first.`,
-        )
-    // THE BOOT READS OVERLAP: the route table, the handler table, the shell and the manifest are
-    // independent of each other.
-    //
-    // THE SHELL IS READ ONCE, at boot. `render`'s own note prices the per-render read at 98% of the
-    // op and leaves the caching to whatever server got written; this is that server. The manifest
-    // names the stylesheet only where the bundler collected one, so an app that imports none links
-    // none.
-    const [table, handlers, shell, manifest] = await Promise.all([
-        import(
-            Bun.pathToFileURL(`${options.out}/server.ts`).href
-        ) as Promise<ServerTable>,
-        handlersIn(options.out),
-        shellUnder(options.root),
+}): Promise<AppSources> {
+    // THE BOOT READS OVERLAP: the tables and the manifest are independent of each other. The
+    // manifest names the stylesheet only where the bundler collected one, so an app that imports
+    // none links none.
+    const [table, manifest] = await Promise.all([
+        servedTable(options.root),
         Bun.file(`${options.out}/${MANIFEST}`).json() as Promise<Manifest>,
     ])
     return builtSources({
         table,
-        handlers,
-        handlerModule: sourceModuleLoader(options.root, options.out),
-        shell,
+        handlers: table.handlers,
         manifest,
         client: pathsUnder(`${options.out}/${CLIENT_DIRECTORY}`),
         published: pathsUnder(`${options.out}/${PUBLIC_DIRECTORY}`),
@@ -136,9 +127,9 @@ export function pathsUnder(directory: string): Map<string, string> {
 }
 
 /** The sources an `App` is booted over, out of the parts `abide build` produced. */
-export function builtSources(parts: BuildParts): Promise<LoadedSources> {
+export function builtSources(parts: BuildParts): Promise<AppSources> {
     // THE BUNDLE, ENUMERATED RATHER THAN RESOLVED. A request names a file in this set or it names
-    // nothing — there is no path to normalise, so `..` is not a case that has to be got right,
+    // 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 build produced.
     //
     // THE PRECOMPRESSED COPIES ARE NOT ADDRESSES OF THEIR OWN. They are the same file in another
@@ -173,7 +164,7 @@ export function builtSources(parts: BuildParts): Promise<LoadedSources> {
             'content-type': type,
             vary: 'accept-encoding',
         }
-        // 38.30 — the precompressed copy where the request takes its encoding.
+        // 38.29 — the precompressed copy where the request takes its encoding.
         const encoding = negotiateEncoding(
             request.headers.get('accept-encoding'),
             encodings,