@abide/abide 0.58.0 → 0.101.0

package/src/server/commands.ts

@@ -0,0 +1,442 @@
+// 38.13 — THE COMMAND LINE, for both hosts that have one: `abide`, over an app on disk, and a
+// compiled app's executable, over the app it holds (38.51). One list, so a command either has is a
+// command both have — the executable answers the ones that need the source and the compiler with a
+// refusal naming `abide`, rather than not knowing them.
+
+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 {
+    appUrl,
+    callHandler,
+    followLogs,
+    remoteHeaders,
+    remoteUrl,
+    watch as watchAddress,
+} from './remote.ts'
+import { inScope, LISTENING } from './requestScope.ts'
+import { shell } from './shell.ts'
+import { withoutTrailingSlash } from './withoutTrailingSlash.ts'
+
+/** What a command is handed: the words after the flags, the command's own first, and the flags. */
+export type Given = ReturnType<typeof parsed>
+
+type Command = (given: Given) => Promise<number | undefined>
+
+/** The commands that need the app's source and the compiler, which only `abide` holds. */
+type SourceCommands = Record<
+    'scaffold' | 'dev' | 'build' | 'check' | 'compile' | 'bundle' | 'lsp',
+    Command
+>
+
+/** Where the app a command means is — everything the two hosts differ in. */
+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.
+     */
+    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>
+    source: SourceCommands | undefined
+}
+
+/**
+ * Runs the command `argv` names; returns its exit code, or `undefined` where it took over.
+ *
+ * A COMMAND RETURNING NO CODE HAS TAKEN THE PROCESS OVER, and the caller must not exit on it —
+ * doing so would close the socket `start` just bound, in the same tick it bound it.
+ */
+export async function runCommands(
+    host: Host,
+    argv: string[],
+): Promise<number | undefined> {
+    // 38.2 — EVERYTHING AFTER THE FILE IS THE SCRIPT'S, flags included, so `run` is taken before the
+    // parser sees an argument it does not know.
+    const given: Given =
+        argv[0] === 'run' ? { positionals: argv, values: {} } : parsed(argv)
+    const command = given.positionals[0]
+    const commands = commandsOf(host)
+    if (command === 'help' || given.values.help) {
+        console.log(usage(host, commands))
+        return 0
+    }
+    if (command === undefined) return await shellOn(host, given)
+    for (const [name, , body] of commands)
+        if (name.split(' ')[0] === command) return await body(given)
+    console.error(
+        `${host.name}: unknown command '${command}'\n\n${usage(host, commands)}`,
+    )
+    return 1
+}
+
+// A command, and whether it is one of `SourceCommands` — which a host without them still answers
+// (38.52), and does not list (38.53).
+type Row = [usage: string, meaning: string, run: Command, sourced: boolean]
+
+function commandsOf(host: Host): Row[] {
+    const fromSource = (
+        usage: string,
+        meaning: string,
+        name: keyof SourceCommands,
+    ): Row => [
+        usage,
+        meaning,
+        (given) =>
+            host.source === undefined
+                ? needsSource(host, name)
+                : host.source[name](given),
+        true,
+    ]
+    return [
+        fromSource('scaffold <name>', 'write a starter project', 'scaffold'),
+        [
+            'run <file> [args…]',
+            'run a script under the abide runtime',
+            (given) => run(host, given),
+            false,
+        ],
+        fromSource('dev', 'serve with the compiler in the loop', 'dev'),
+        fromSource(
+            'build',
+            'compile every .abide under the app into .abide/',
+            'build',
+        ),
+        ['start', 'serve the app', (given) => start(host, given), false],
+        [
+            'call <address> [args]',
+            'one call to one handler',
+            (given) => call(host, given),
+            false,
+        ],
+        [
+            'openapi',
+            'the OpenAPI document, written rather than served',
+            (given) => openapi(host, given),
+            false,
+        ],
+        [
+            'mcp',
+            "the app's MCP server over stdio",
+            (given) => mcp(host, given),
+            false,
+        ],
+        [
+            'logs',
+            'a live subscription to log.records',
+            ({ values }) => followLogs(appUrl(values.url)),
+            false,
+        ],
+        [
+            'watch <address> [args]',
+            "a live subscription to one of the app's followed GETs",
+            (given) => watch(host, given),
+            false,
+        ],
+        fromSource(
+            'check [dir…]',
+            'type-check the templates and the TypeScript, on the line you wrote',
+            'check',
+        ),
+        fromSource(
+            'compile',
+            'the build, as one executable named after the app',
+            'compile',
+        ),
+        fromSource(
+            'bundle',
+            'the build, as a desktop app for this platform',
+            'bundle',
+        ),
+        fromSource('lsp', 'the .abide language server, over stdio', 'lsp'),
+    ]
+}
+
+/** Refuses a command that needs the source, pointing at `abide`; returns the exit code. 38.52. */
+async function needsSource(host: Host, name: string): Promise<number> {
+    console.error(
+        `${host.name} ${name}: needs the app's source and the compiler, which this executable does not hold. Run \`abide ${name}\` where the source is.`,
+    )
+    return 1
+}
+
+/**
+ * The usage text, listing what the host can run.
+ *
+ * 38.53 — an executable lists neither the commands it only refuses nor the flags only they read.
+ */
+function usage(host: Host, commands: Row[]): string {
+    const sourced = host.source !== undefined
+    let width = 0
+    for (const [command, , , needs] of commands)
+        if (sourced || !needs) width = Math.max(width, command.length)
+    let text = `${host.name} <command>\n${host.name} [--url <origin>]  a shell on the app — served here, or the running one --url names\n\n`
+    for (const [command, meaning, , needs] of commands)
+        if (sourced || !needs)
+            text += `  ${command.padEnd(width)}  ${meaning}\n`
+    if (!sourced)
+        return `${text}
+  --port  the listen port the app is served on
+  --url   the running app the shell, call, logs, openapi and mcp talk to
+  --out   the file openapi writes
+`
+    text += `
+  --root       the app's source directory, the one ui/ sits under —
+               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
+  --port       the listen port for dev, start and the shell's app
+  --url        the running app the shell, call, logs, openapi and mcp talk to
+  --target     the platform compile builds for — linux-x64, darwin-arm64, windows-x64…
+  --platforms  several of them, comma-separated, one executable each
+`
+    return text
+}
+
+function parsed(argv: string[]) {
+    return parseArgs({
+        args: argv,
+        options: {
+            // NO DEFAULT HERE EITHER. `cd ledger && abide dev` is what the docs tell an author to
+            // type and `--root ./src` is what an app's own scripts write, so which directory is
+            // meant is a question `appRoot` answers rather than one the parser assumes.
+            root: { type: 'string' },
+            out: { type: 'string' },
+            // NO DEFAULT, which is not an omission: `Bun.serve` given no port already reads
+            // `PORT` and then falls back to 3000 — `abide dev` scanning on from there, 38.64 — and
+            // a default written here would take that away from every host that sets it.
+            port: { type: 'string' },
+            url: { type: 'string' },
+            method: { type: 'string' },
+            target: { type: 'string' },
+            platforms: { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+        },
+        allowPositionals: true,
+    })
+}
+
+/** The app served, with the address it answers at and the banner it is announced by. 38.6. */
+async function served(
+    host: Host,
+    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 server = LISTENING.server as Bun.Server<unknown>
+    return {
+        app,
+        url: withoutTrailingSlash(server.url.href),
+        heading: banner(host.name, 'start', host.appPackage(), server),
+    }
+}
+
+/**
+ * `start`: serves the app.
+ *
+ * 38.68 — 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)
+    if (typeof serving === 'number') return serving
+    console.log(serving.heading)
+    return undefined
+}
+
+/**
+ * The command line with no command: 38.7's shell, on the running app `--url` names or on the app
+ * served here.
+ *
+ * 38.7 — WITH `--url`, BOOTS NOTHING. 38.54 — without, the app served and the shell on it, over http
+ * as a remote one's is. 38.55 — `exit` stops the app. 38.56 — 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> {
+    const handlers = await host.handlers(given)
+    const remote = remoteUrl(given.values.url)
+    if (remote !== undefined) {
+        const url = appUrl(remote)
+        await shell({
+            url,
+            handlers,
+            heading: `${host.name}: ${url}`,
+            local: false,
+        })
+        return 0
+    }
+    const serving = await served(host, given)
+    if (typeof serving === 'number') return serving
+    const ended = await shell({
+        url: serving.url,
+        handlers,
+        heading: serving.heading,
+        local: true,
+    })
+    if (ended === 'ended') return undefined
+    await serving.app.stop()
+    return 0
+}
+
+/**
+ * `run`: runs a script under the abide runtime.
+ *
+ * 38.2 — the request scope installed, the configuration resolved against the app it stands in,
+ * and the script run in a scope of its own — so it imports `#server` and `#shared` and reads
+ * `config` without a build.
+ *
+ * HANDS BACK NO CODE ONCE THE SCRIPT IS RUNNING, as `start` does: the script's top level settling
+ * is not the script ending. A timer, a server or a socket it left open keeps the process alive,
+ * and a `process.exitCode` it set is what the process exits with.
+ */
+async function run(
+    host: Host,
+    { positionals: [, file, ...rest] }: Given,
+): Promise<number | undefined> {
+    if (file === undefined) {
+        console.error(
+            `${host.name} run: name the file — ${host.name} run <file> [args…]`,
+        )
+        return 1
+    }
+    const path = resolve(file)
+    process.argv = [process.argv[0] as string, path, ...rest]
+    // 38.58 — 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()
+    await inScope(undefined, () => import(Bun.pathToFileURL(path).href))
+    return undefined
+}
+
+/** `call`: one call to one handler on a running app. 38.8. */
+/** `watch <address> [args]`: a `GET`'s value and each patch, as its event stream sends them (38.70). */
+async function watch(host: Host, given: Given): Promise<number> {
+    const {
+        positionals: [, address, ...args],
+        values: { url },
+    } = given
+    if (address === undefined) {
+        console.error(
+            `${host.name} watch: name the GET — ${host.name} watch chat/room room=lobby`,
+        )
+        return 1
+    }
+    return watchAddress(appUrl(url), address, args).catch((thrown: Error) => {
+        console.error(`${host.name} watch: ${thrown.message}`)
+        return 1
+    })
+}
+
+async function call(host: Host, given: Given): Promise<number> {
+    const {
+        positionals: [, address, ...args],
+        values: { url, method },
+    } = given
+    if (address === undefined) {
+        console.error(
+            `${host.name} call: name the handler — ${host.name} call invoices/getInvoice id=4310`,
+        )
+        return 1
+    }
+    const answered = await callHandler(
+        appUrl(url),
+        address,
+        args,
+        method,
+        await host.handlers(given),
+    ).catch((thrown: Error) => ({ code: 1, text: thrown.message }))
+    if (answered.text !== '')
+        (answered.code === 0 ? console.log : console.error)(answered.text)
+    return answered.code
+}
+
+/**
+ * A fetch against a generated surface, on the app `--url` names or on one booted here.
+ *
+ * 38.9 — the app booted in this process has that surface opened, and derives it from the same
+ * route table the served one does.
+ */
+async function surfaceAt(
+    host: Host,
+    url: string | undefined,
+    surface: string,
+    address: string,
+): Promise<
+    (
+        init?: RequestInit & { headers?: Record<string, string> },
+    ) => Promise<Response>
+> {
+    const remote = remoteUrl(url)
+    if (remote !== undefined)
+        return (init) =>
+            fetch(`${appUrl(remote)}${address}`, {
+                ...init,
+                headers: { ...init?.headers, ...remoteHeaders() },
+            })
+    process.env[surface] = '1'
+    const app = await host.boot()
+    return (init) =>
+        app.fetch(new Request(`http://abide.local${address}`, init))
+}
+
+/**
+ * `openapi`: writes the OpenAPI document.
+ *
+ * 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,
+): Promise<number> {
+    const answer = await (
+        await surfaceAt(host, url, 'ABIDE_OPENAPI', OPENAPI_ADDRESS)
+    )()
+    if (!answer.ok) {
+        console.error(
+            `${host.name} openapi: the app answered ${answer.status}. ABIDE_OPENAPI opens the document.`,
+        )
+        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`)
+    return 0
+}
+
+/**
+ * `mcp`: the app's MCP server over stdio.
+ *
+ * 38.9, 38.14 — 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, 'ABIDE_MCP', MCP_ADDRESS)
+    for await (const line of console) {
+        if (line.trim() === '') continue
+        const answer = await ask({
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: line,
+        })
+        const text = await answer.text()
+        if (text !== '') process.stdout.write(`${text}\n`)
+    }
+    return 0
+}

package/src/server/componentImports.ts

@@ -0,0 +1,56 @@
+// 35.4 — A `.abide` IMPORTED FROM AN APP'S OWN `.ts`, as the component it compiles to. A component
+// importing a component is pointed at the compiled module by the compile itself (34.14); a handler
+// is not compiled, so its import reached bun as written — and bun loads an extension it has no
+// loader for as a `file`, handing the handler the path. `render(Invoice({ invoice }))` then threw
+// "Invoice is not a function".
+//
+// BOUND, NOT RAW. The compiled module is a function of accessors answering its markup (33.4); what
+// an app calls is a function of plain props answering a `Component` (35.4), which `render` invokes
+// with nothing. The adapter is written into the module the import lands on rather than exported
+// from a seam, so no name joins the surface.
+
+import { realpathSync } from 'node:fs' // bun exposes no realpath of its own
+
+/**
+ * The plugin landing a `.abide` under `root` on its compiled server module under `compiled`.
+ *
+ * One per app root: a runtime plugin's `onLoad` is asked in registration order and the first whose
+ * filter matches must answer, so the filter carries the root and another app's plugin is never
+ * asked. The same object serves the bundler, where `abide compile` follows a handler's imports.
+ */
+export function componentImports(
+    root: string,
+    compiled: string,
+): Bun.BunPlugin {
+    // BOTH SPELLINGS OF THE ROOT, because bun names a file with its symlinks resolved and an app
+    // under `/tmp` is `/private/tmp` to it.
+    const roots = new Set([root, realpathSync(root)])
+    return {
+        name: 'abide-component-imports',
+        setup(build) {
+            for (const at of roots)
+                build.onLoad(
+                    { filter: new RegExp(`^${RegExp.escape(at)}/.*\\.abide$`) },
+                    (args) => ({
+                        contents: boundModule(
+                            `${compiled}/${args.path.slice(at.length + 1, -'.abide'.length)}.ts`,
+                        ),
+                        loader: 'js',
+                    }),
+                )
+        },
+    }
+}
+
+function boundModule(compiledModule: string): string {
+    return `import component from ${JSON.stringify(compiledModule)}
+export default (props = {}) => {
+    const accessors = {}
+    for (const key in props) {
+        const value = props[key]
+        accessors[key] = () => value
+    }
+    return () => component(accessors)
+}
+`
+}

package/src/server/componentModules.d.ts

@@ -0,0 +1,9 @@
+// 35.4 — what a `.ts` holds where it imports a `.abide`: the component, called with its props to
+// bind them, answering the `Component` `render` takes (`componentImports`). A wildcard, so the props
+// are not checked here; a declaration in a module would be an augmentation, which takes no wildcard.
+declare module '*.abide' {
+    const component: (
+        props?: Record<string, unknown>,
+    ) => import('./render.ts').Component
+    export default component
+}

package/src/server/compressAnswer.ts

@@ -0,0 +1,100 @@
+// 38.30 — AN ANSWER, COMPRESSED WHOLE: a document, and a JSON value at least `COMPRESSION_FLOOR`
+// bytes long. Both are in hand before a byte goes out — `render` sends nothing until the page is
+// built (41.1), and a value is stringified once — so one compression is the whole answer, with its
+// length known, where a stream compressed as it arrived had to be flushed at every chunk.
+//
+// WHAT EACH LANE SENDS BESIDE THE BYTES is here too, so the two cannot drift. A document names
+// `accept-encoding` in `vary` through `DOCUMENT_HEADERS`, which its `HEAD` and error answers carry as
+// well; a JSON answer names it here. Both say their length: `abide dev` relays a body chunk by chunk
+// from its worker (38.36), and a relayed body with no declared length goes out chunked.
+// BUN'S GZIP parts from zlib's past ~130 KB, which only the off-loop lane reaches — so that lane takes
+// zlib's, the loop keeps bun's, and the two make the same bytes.
+import { brotliCompress, brotliCompressSync, constants, gzip } from 'node:zlib' // bun has no brotli, and no compression off the loop
+import {
+    ENCODINGS,
+    type Encoding,
+    negotiateEncoding,
+} from './negotiateEncoding.ts'
+
+// QUALITY 5, NOT 11. This runs per request, and the top brotli level is priced for a build that
+// runs once: on an 18 KB docs page 11 took 15,800 µs against 5's 150, for 15% fewer bytes. 5 is
+// already under gzip's size at twice gzip's 70 µs.
+const BROTLI_OPTIONS = { params: { [constants.BROTLI_PARAM_QUALITY]: 5 } }
+
+// 38.69 — the bytes under which a JSON answer goes out as it is. Under it an answer saves tens of
+// bytes that leave in the same packet anyway, for 3–8 µs of a ~57 µs request; at 8 KB the same CPU
+// saves seven kilobytes.
+const COMPRESSION_FLOOR = 1024
+
+// 38.96 — the bytes from which an answer is compressed off the event loop. Brotli 5 holds the loop
+// ~360 µs at 64 KB and ~7 ms at 700 KB — every other request and socket waits that long — where
+// the thread pool's hop adds ~20 µs to the answer it carries: 6% at 64 KB, 27% at 16 KB.
+const OFF_LOOP_FLOOR = 64 * 1024
+
+const ENCODER = new TextEncoder()
+
+function compressed(
+    bytes: Uint8Array<ArrayBuffer>,
+    encoding: Encoding,
+): Uint8Array<ArrayBuffer> {
+    return encoding === 'br'
+        ? (brotliCompressSync(bytes, BROTLI_OPTIONS) as Uint8Array<ArrayBuffer>)
+        : Bun.gzipSync(bytes)
+}
+
+function compressedOffLoop(
+    bytes: Uint8Array<ArrayBuffer>,
+    encoding: Encoding,
+): Promise<Uint8Array<ArrayBuffer>> {
+    return new Promise((resolve, reject) => {
+        const settle = (error: Error | null, result: Uint8Array): void => {
+            if (error === null) resolve(result as Uint8Array<ArrayBuffer>)
+            else reject(error)
+        }
+        if (encoding === 'br') brotliCompress(bytes, BROTLI_OPTIONS, settle)
+        else gzip(bytes, settle)
+    })
+}
+
+function answered(
+    body: Uint8Array<ArrayBuffer>,
+    encoding: Encoding | undefined,
+    headers: Headers,
+    status: number,
+): Response {
+    if (encoding !== undefined) headers.set('content-encoding', encoding)
+    headers.set('content-length', String(body.byteLength))
+    return new Response(body, { status, headers })
+}
+
+/**
+ * `answer` as the `Response` to `request`, in the encoding the request takes where it takes one.
+ *
+ * THE LANE IS THE BODY'S TYPE: a built document arrives as its bytes, and a JSON value as its text,
+ * encoded once here and floored by its length. A `Promise` only where the compression runs off the
+ * loop, so an answer under that floor costs no await.
+ */
+export function compressAnswer(
+    answer: Uint8Array<ArrayBuffer> | string,
+    request: Request,
+    headers: Headers,
+    status: number,
+): Response | Promise<Response> {
+    const json = typeof answer === 'string'
+    const bytes = json ? ENCODER.encode(answer) : answer
+    const encoding =
+        json && bytes.byteLength < COMPRESSION_FLOOR
+            ? undefined
+            : negotiateEncoding(
+                  request.headers.get('accept-encoding'),
+                  ENCODINGS,
+              )
+    if (json) headers.append('vary', 'accept-encoding')
+    if (encoding === undefined)
+        return answered(bytes, encoding, headers, status)
+    if (bytes.byteLength >= OFF_LOOP_FLOOR)
+        return compressedOffLoop(bytes, encoding).then((body) =>
+            answered(body, encoding, headers, status),
+        )
+    return answered(compressed(bytes, encoding), encoding, headers, status)
+}