@abide/abide 0.101.0 → 0.103.0

package/src/server/serveDev.ts

@@ -1,5 +1,5 @@
 // 38.4 — `abide dev`: the project, watched, with the app kept up across every save. What is here
-// is the LISTENER and nothing else (38.15): the socket is bound once in this process and survives
+// is the LISTENER and nothing else (38.14): the socket is bound once in this process and survives
 // every reload, so a browser holding a connection open meets a server that is still there when
 // the app behind it has been thrown away and rebuilt.
 //
@@ -12,37 +12,43 @@
 // reload, where a compiler imported into each new app cost 4.5 s a save against the 80 ms the
 // compile takes — and the clause asks for the APP to be in the child, which the compiler is not.
 //
-// 38.16 — A RELOAD IS A NEW PROCESS, not a module cache to invalidate. An app leaves things behind
+// 38.15 — A RELOAD IS A NEW PROCESS, not a module cache to invalidate. An app leaves things behind
 // that no invalidation reaches — a timer, a `share`, a module that ran once, and bun's own memory of
 // a file it failed to find — and a process is the one boundary that takes all of them with it. Every live socket is force-closed with it, which
 // is also the whole of the reload protocol: the reload client reconnects and reloads, so nothing
 // here has a message to send.
 
 import { watch } from 'node:fs' // bun exposes no file watcher of its own
+import { dirname, resolve } from 'node:path' // bun exposes no path helpers of its own
 import {
     type AppChecker,
+    compilationOf,
     compileApp,
     openChecker,
 } from '#compiler/compileApp.ts'
 import { formatDiagnosis } from '#compiler/formatDiagnosis.ts'
 import { DEV_ADDRESS } from '#shared/ADDRESSES.ts'
+import { placeOf } from '#shared/routePattern.ts'
+import type { Compilation } from './abideModules.ts'
 import { DEFAULT_PORT } from './DEFAULT_PORT.ts'
 import type { Ask, FromWorker, ToWorker } from './devWorker.ts'
 import { upgraded } from './muxUpgrade.ts'
 import { plainAnswer } from './plainAnswer.ts'
 import { SETTLE_MILLISECONDS } from './SETTLE_MILLISECONDS.ts'
-import { VIRTUAL_DIRECTORY } from './VIRTUAL_DIRECTORY.ts'
 
 /** What `abide dev` serves, and where. */
 export type DevOptions = {
-    /** The app's source root — the directory `ui/` sits under, and the tree that is watched. */
+    /**
+     * The app's source root — where its pages sit, and the tree that is watched — as its real path
+     * (`appRoot`), which is how the bundler names what it built.
+     */
     root: string
     port?: number | undefined
 }
 
 // A request in flight: the request itself — because a worker replaced before it answered answers
-// nothing, and the ask has to be put to the app that exists (38.25) — and, once its head has come
-// back, the stream the body is fed into and the pull waiting on the worker's next chunk (38.36).
+// nothing, and the ask has to be put to the app that exists (38.24) — and, once its head has come
+// back, the stream the body is fed into and the pull waiting on the worker's next chunk (38.35).
 type InFlight = Omit<Ask, 'id' | 'method' | 'url'> & {
     // 16.22 — the request bun handed the listener, which is the one its idle timeout is raised on.
     request: Request
@@ -60,7 +66,12 @@ type DevWorker = {
     terminate(): void
 }
 
-type Compiled = { modules: Map<string, string>; failure: string }
+type Compiled = {
+    compilation: Compilation
+    /** The public files the compile's walk found (`appFiles`), which the worker answers. */
+    published: Map<string, string>
+    failure: string
+}
 
 const LAST_DEV_PORT = 3099
 
@@ -128,21 +139,31 @@ export async function serveDev(
             if (checker !== undefined && !checker.current())
                 await closeChecker()
             checker ??= await openChecker(options.root)
-            const compiled = await compileApp(
-                options.root,
-                `${options.root}/${VIRTUAL_DIRECTORY}`,
-                checker,
-            )
+            const compiled = await compileApp(options.root, checker)
             // 14 and 32.14 — what the compiler has to say, on every compile.
             for (const warning of compiled.warnings)
                 console.warn(formatDiagnosis(warning, process.cwd()))
-            return { modules: compiled.modules, failure: '' }
+            watchDependencies(compiled.files)
+            return {
+                compilation: compilationOf(compiled),
+                published: compiled.published,
+                failure: '',
+            }
         } catch (thrown) {
             await closeChecker()
             const failure =
                 thrown instanceof Error ? thrown.message : String(thrown)
             console.error(`abide dev: ${failure}`)
-            return { modules: new Map(), failure }
+            return {
+                compilation: {
+                    files: {},
+                    handlers: {},
+                    tables: {},
+                    mounted: {},
+                },
+                published: new Map(),
+                failure,
+            }
         }
     }
 
@@ -156,9 +177,34 @@ export async function serveDev(
         }
     }
 
+    // A path a watcher saw move — or a move nobody could name — and the replacement it schedules.
+    let settling: ReturnType<typeof setTimeout> | undefined
+    function moved(path: string | undefined): void {
+        checker?.saw(path)
+        if (settling !== undefined) clearTimeout(settling)
+        settling = setTimeout(replace, SETTLE_MILLISECONDS)
+    }
+
+    // 38.99 — A DEPENDENCY'S `.abide` IS THE APP'S TOO, and a linked package's lies outside the root's
+    // watcher: each directory one was compiled from is watched once, for the session.
+    const watchedDependencies = new Set<string>()
+    function watchDependencies(files: Compilation['files']): void {
+        for (const relative of Object.keys(files)) {
+            if (placeOf(relative) !== 'dependency') continue
+            const directory = dirname(resolve(options.root, relative))
+            if (watchedDependencies.has(directory)) continue
+            watchedDependencies.add(directory)
+            watch(directory, (_event, filename) =>
+                moved(
+                    filename === null ? undefined : `${directory}/${filename}`,
+                ),
+            )
+        }
+    }
+
     // The worker, compiled and answering.
-    function open({ modules, failure }: Compiled): void {
-        // 38.15 — A PROCESS, NOT A THREAD, for the header's reason: bun remembers a file it failed
+    function open({ compilation, published, failure }: Compiled): void {
+        // 38.14 — A PROCESS, NOT A THREAD, for the header's reason: bun remembers a file it failed
         // to find for the life of the process, and a thread inherits the miss.
         //
         // THE ENVIRONMENT AS IT STANDS, `NODE_ENV` included (36.3): the child is handed what this
@@ -182,7 +228,7 @@ export async function serveDev(
                             server.timeout(asked, message.seconds)
                     } else answer(started, message)
                 },
-                // 38.42 — AN APP THAT EXITS ON ITS OWN is replaced, and says so: a listener still
+                // 38.41 — AN APP THAT EXITS ON ITS OWN is replaced, and says so: a listener still
                 // forwarding to it leaves every tab hanging.
                 onExit() {
                     if (worker !== started) return
@@ -200,7 +246,7 @@ export async function serveDev(
                 if (!child.killed && child.exitCode === null)
                     child.send(message)
             },
-            // 38.97 — SIGTERM, which the worker answers by hanging up what it is answering; a worker
+            // 38.96 — SIGTERM, which the worker answers by hanging up what it is answering; a worker
             // wedged in a loop never reads it, so a second later it is killed outright.
             terminate() {
                 child.kill()
@@ -211,7 +257,8 @@ export async function serveDev(
         started.postMessage({
             kind: 'start',
             root: options.root,
-            modules,
+            compilation,
+            published,
             failure,
         })
         // The worker holds every request behind its own compile, so what waited here only had
@@ -221,8 +268,8 @@ export async function serveDev(
     }
 
     // WHAT AN APP THAT IS GONE WAS HOLDING. A request whose head has not gone out is re-asked of the
-    // replacement (38.25), or answered where the app ended itself — the request in hand may be what
-    // ended it (38.42). 38.38 — one whose head has gone out cannot be answered again, and ends as
+    // replacement (38.24), or answered where the app ended itself — the request in hand may be what
+    // ended it (38.41). 38.37 — one whose head has gone out cannot be answered again, and ends as
     // `abide start`'s does.
     function endInFlight(reask: boolean, why: string): void {
         for (const held of inFlight.values()) {
@@ -235,11 +282,11 @@ export async function serveDev(
         inFlight.clear()
     }
 
-    // 38.16 — THE REPLACEMENT. The old worker is terminated, every socket it could still be
+    // 38.15 — THE REPLACEMENT. The old worker is terminated, every socket it could still be
     // answering is force-closed, and the new one is opened. The order matters: a socket closed
     // after the new worker is up is a reload client that reconnects to a server still compiling.
     //
-    // 38.25 — A REQUEST IN FLIGHT IS RE-ASKED rather than failed. Failing it serves a reader a
+    // 38.24 — A REQUEST IN FLIGHT IS RE-ASKED rather than failed. Failing it serves a reader a
     // network error for asking while somebody saved, and during a regeneration of a whole docs
     // tree that is every request; re-asked, they wait and get the app the source now says.
     function replace(): void {
@@ -258,24 +305,19 @@ export async function serveDev(
     await compiling
 
     // 38.4 — THE PROJECT, WATCHED. One recursive watcher over the source root: the pages, the
-    // shell, the stylesheets and `ui/public` are all under it, and every one of them is something
+    // layouts, the stylesheets and every `public` directory are all under it, and every one of them is something
     // the worker read at boot.
     //
     // IT IS NOT UNREFFED. It holds the process open, which is what a command that IS a server
     // wants: the only ways out of `abide dev` are a signal and a throw, exactly as for
     // `abide start`.
-    let settling: ReturnType<typeof setTimeout> | undefined
-    watch(options.root, { recursive: true }, (_event, filename) => {
-        checker?.saw(
-            filename === null ? undefined : `${options.root}/${filename}`,
-        )
-        if (settling !== undefined) clearTimeout(settling)
-        settling = setTimeout(replace, SETTLE_MILLISECONDS)
-    })
+    watch(options.root, { recursive: true }, (_event, filename) =>
+        moved(filename === null ? undefined : `${options.root}/${filename}`),
+    )
 
     // A REQUEST AS A MESSAGE. `Request` does not survive a structured clone, so what crosses is
     // the four things the worker rebuilds one from — and the request's body is collected here, which
-    // is what lets it be asked again of a replacement (38.25). The answer's body streams (38.36).
+    // is what lets it be asked again of a replacement (38.24). The answer's body streams (38.35).
     //
     // COLLECTED ONCE, HERE, rather than inside `forward`: a body can only be read off a
     // `Request` once, and a re-asked request is the second read that is not there.
@@ -294,7 +336,7 @@ export async function serveDev(
         })
     }
 
-    // 38.39 — ASKED WITHOUT `accept-encoding`, so the app answers uncompressed. A failure after the
+    // 38.38 — ASKED WITHOUT `accept-encoding`, so the app answers uncompressed. A failure after the
     // head is shown as markup appended to the stream (`pull` in the worker), and markup appended to a
     // compressed stream is a stream no browser can decode. Localhost buys nothing from the bytes saved.
     function identityOnly(headers: Headers): [string, string][] {
@@ -304,7 +346,7 @@ export async function serveDev(
         return kept
     }
 
-    // 38.36, 38.37 — THE HEAD SETTLES THE RESPONSE, and its body pulls one chunk from the worker per
+    // 38.35, 38.36 — THE HEAD SETTLES THE RESPONSE, and its body pulls one chunk from the worker per
     // read the connection makes: a high-water mark of 0 asks for nothing ahead of the reader.
     function answer(
         from: DevWorker,
@@ -478,7 +520,7 @@ export async function serveDev(
             },
         })
 
-    // 38.65 — A PORT SOMEONE NAMED IS THE PORT, and one taken is the failure. `Bun.serve` given
+    // 38.64 — A PORT SOMEONE NAMED IS THE PORT, and one taken is the failure. `Bun.serve` given
     // none reads `PORT` itself.
     const server =
         options.port !== undefined || process.env.PORT
@@ -487,7 +529,7 @@ export async function serveDev(
     return server as unknown as Bun.Server<undefined>
 }
 
-// 38.64 — NAMED BY NOBODY, the first free port from 3000. A port taken is the next one tried, and
+// 38.63 — NAMED BY NOBODY, the first free port from 3000. A port taken is the next one tried, and
 // any other failure is the failure.
 function listenOnFirstFree<Listener>(
     listen: (port: number) => Listener,

package/src/server/shell.ts

@@ -9,7 +9,7 @@ import { useColor } from '#shared/log.ts'
 import { paint as painted } from '#shared/paint.ts'
 import type { Mount } from './answerRpc.ts'
 import { LogPanel } from './LogPanel.ts'
-import { callHandler, followLogs, watch } from './remote.ts'
+import { callHandler, watch } from './remote.ts'
 import { type Listed, surfaceOf } from './surfaceOf.ts'
 
 /**
@@ -48,8 +48,7 @@ function wordsOf(text: string): string[] {
  * is in argv (38.8). Answers `exit` where the line said so and `ended` where the input did, so a
  * host that owns the app can stop it on the one and keep serving on the other.
  *
- * `local` is the app in this process — the one `abide` alone serves — whose console already tails into the panel, so
- * `logs` has nothing to add, and whose `exit` stops it.
+ * `local` is the app in this process — the one `abide` alone serves — whose `exit` stops it.
  */
 export async function shell(options: {
     url: string
@@ -78,7 +77,7 @@ export async function shell(options: {
             ),
     })
     // CTRL-C AS A SHELL TAKES IT — raw mode takes the key from the terminal, so no signal is sent for
-    // it: a call running is cancelled, then every watch standing, a line typed is dropped, and on
+    // it: a call running is canceled, then every watch standing, a line typed is dropped, and on
     // an empty line it asks once and leaves on the second, as `node`'s REPL does.
     let exited = false
     let closed = false
@@ -169,7 +168,6 @@ export async function shell(options: {
           )
         : undefined
     if (panel === undefined) console.log(options.heading)
-    let tailing = false
     try {
         for await (const line of lines) {
             const [word, address] = line.trim().split(/\s+/)
@@ -199,7 +197,7 @@ export async function shell(options: {
                 ).catch((thrown: Error) => ({
                     code: 1,
                     text: running?.signal.aborted
-                        ? '(cancelled)'
+                        ? '(canceled)'
                         : thrown.message,
                 }))
                 running = undefined
@@ -210,14 +208,8 @@ export async function shell(options: {
                 )
             } else if (word === 'call')
                 console.log('call: name the handler — call <address> [args]')
-            // TAILED ALONGSIDE THE PROMPT rather than in place of it, so the shell still answers.
-            else if (word === 'logs' && !local && !tailing) {
-                tailing = true
-                void followLogs(url).then(() => {
-                    tailing = false
-                })
-            } else if (word === 'watch' && address !== undefined) {
-                // Followed alongside the prompt, as `logs` is.
+            // FOLLOWED ALONGSIDE THE PROMPT rather than in place of it, so the shell still answers.
+            else if (word === 'watch' && address !== undefined) {
                 const following = new AbortController()
                 watching.add(following)
                 void watch(
@@ -235,12 +227,6 @@ export async function shell(options: {
                     .finally(() => watching.delete(following))
             } else if (word === 'watch')
                 console.log('watch: name a GET — watch <address> [args]')
-            else if (word === 'logs')
-                console.log(
-                    local
-                        ? "logs: the app's log already tails here."
-                        : 'logs: already tailing.',
-                )
             else
                 console.log(
                     `unknown: ${word} — help lists what the shell takes`,
@@ -456,7 +442,6 @@ export function shellWords(local: boolean): [usage: string, meaning: string][] {
         ['handlers', 'every handler call can reach, with its args'],
         ['watch <address> [args]', 'follow a GET — watch chat/room room=lobby'],
     ]
-    if (!local) words.push(['logs', "tail the app's log.records here"])
     words.push(
         ['help', 'this list — Ctrl+C clears the line, Ctrl+L the panel'],
         ['exit', local ? 'stop the app and leave' : 'leave the shell'],
@@ -488,7 +473,7 @@ export function cliListing(handlers: Mount[]): Listed[] {
 
 /**
  * The handlers the shell lists: each address with the args it is typed with, and its description on
- * the line under it where it declares one. 38.63.
+ * the line under it where it declares one. 38.62.
  */
 export function handlersText(
     listed: Listed[],

package/src/server/sourceMappings.ts

@@ -0,0 +1,139 @@
+// THE `mappings` FIELD OF A SOURCE MAP (revision 3), read and written. The compiler writes one per
+// module it emits from a `.abide` (`sourceMapOf`), the server reads them to place a stack frame in
+// the `.abide` (`installSourceMaps`), and the client build reads bun's to put the two together —
+// bun reads no map it is handed, at run time or in the bundler, so every one of those is ours.
+
+/** Where one generated column came from: `[column, source, line, sourceColumn]`, all from 0. */
+export type Segment = [number, number, number, number]
+
+const DIGITS =
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/'
+const VALUES = new Map<string, number>()
+for (let index = 0; index < DIGITS.length; index += 1)
+    VALUES.set(DIGITS[index] as string, index)
+
+function vlq(value: number): string {
+    let rest = value < 0 ? (-value << 1) | 1 : value << 1
+    let out = ''
+    do {
+        let digit = rest & 31
+        rest >>>= 5
+        if (rest > 0) digit |= 32
+        out += DIGITS[digit]
+    } while (rest > 0)
+    return out
+}
+
+/** Each generated line's segments, ascending by column, as the `mappings` string. */
+export function encodeMappings(lines: readonly (readonly Segment[])[]): string {
+    let out = ''
+    let source = 0
+    let line = 0
+    let sourceColumn = 0
+    for (let index = 0; index < lines.length; index += 1) {
+        if (index > 0) out += ';'
+        let column = 0
+        const segments = lines[index] as readonly Segment[]
+        for (let at = 0; at < segments.length; at += 1) {
+            const segment = segments[at] as Segment
+            if (at > 0) out += ','
+            out +=
+                vlq(segment[0] - column) +
+                vlq(segment[1] - source) +
+                vlq(segment[2] - line) +
+                vlq(segment[3] - sourceColumn)
+            column = segment[0]
+            source = segment[1]
+            line = segment[2]
+            sourceColumn = segment[3]
+        }
+    }
+    return out
+}
+
+/**
+ * A `mappings` string as each generated line's segments. A segment naming no source — one field
+ * long — places nothing, and is dropped.
+ */
+export function decodeMappings(mappings: string): Segment[][] {
+    const lines: Segment[][] = [[]]
+    const fields: number[] = []
+    let source = 0
+    let line = 0
+    let sourceColumn = 0
+    let column = 0
+    let value = 0
+    let shift = 0
+    const close = (): void => {
+        if (fields.length >= 4) {
+            column += fields[0] as number
+            source += fields[1] as number
+            line += fields[2] as number
+            sourceColumn += fields[3] as number
+            ;(lines[lines.length - 1] as Segment[]).push([
+                column,
+                source,
+                line,
+                sourceColumn,
+            ])
+        } else if (fields.length > 0) column += fields[0] as number
+        fields.length = 0
+    }
+    for (const character of mappings) {
+        if (character === ';') {
+            close()
+            lines.push([])
+            column = 0
+            continue
+        }
+        if (character === ',') {
+            close()
+            continue
+        }
+        const digit = VALUES.get(character) ?? 0
+        value |= (digit & 31) << shift
+        if (digit & 32) {
+            shift += 5
+            continue
+        }
+        fields.push(value & 1 ? -(value >>> 1) : value >>> 1)
+        value = 0
+        shift = 0
+    }
+    close()
+    return lines
+}
+
+/**
+ * Where `column` on generated `line` came from: the last segment at or before it, or the line's
+ * first where the column is before every one — a frame's column points into an expression, and
+ * the segment is its start.
+ */
+export function segmentAt(
+    lines: readonly (readonly Segment[])[],
+    line: number,
+    column: number,
+): Segment | undefined {
+    const segments = lines[line]
+    if (segments === undefined || segments.length === 0) return undefined
+    let found = segments[0] as Segment
+    for (const segment of segments) {
+        if (segment[0] > column) break
+        found = segment
+    }
+    return found
+}
+
+/**
+ * The `[line, column]` generated `line` and `column` came from. Within a segment the run was copied
+ * as written, so the column moves with it.
+ */
+export function placeAt(
+    lines: readonly (readonly Segment[])[],
+    line: number,
+    column: number,
+): [number, number] | undefined {
+    const segment = segmentAt(lines, line, column)
+    if (segment === undefined) return undefined
+    return [segment[2], segment[3] + Math.max(column - segment[0], 0)]
+}

package/src/server/surfaceOf.ts

@@ -1,4 +1,3 @@
-import { RPC_ADDRESS } from '#shared/ADDRESSES.ts'
 import type { Method } from '#shared/rpc.ts'
 import type { Mount, Mounted } from './answerRpc.ts'
 
@@ -9,8 +8,10 @@ export type Surface = 'mcp' | 'openapi' | 'cli'
 export type Listed = {
     address: string
     method: Method
-    /** Its address below `/__abide/rpc` — what `call` spells it (38.8), and every surface names it by. */
+    /** Its route without the leading `/` — what `call` spells it (38.8). */
     path: string
+    /** What MCP and OpenAPI name it by. 20.13. */
+    name: string
     description: string | undefined
     /** Its args' JSON Schema, where it has one. 19.9, 20.11. */
     schema: unknown
@@ -30,6 +31,8 @@ export function surfaceOf(
     mount: Mount | Mounted,
     surface: Surface,
 ): Listed | undefined {
+    // 16.71 — a private handler is its file's alone.
+    if (mount.private) return undefined
     const live = 'handler' in mount ? mount : undefined
     // 16.37 — what its `clients` says, and the build's default where it says nothing.
     const carried =
@@ -39,9 +42,23 @@ export function surfaceOf(
     return {
         address: mount.address,
         method: mount.method,
-        path: mount.address.slice(RPC_ADDRESS.length + 1),
+        path: mount.address.slice(1),
+        name: surfaceName(mount.method, mount.address),
         description:
             live === undefined ? mount.description : live.handler.description,
         schema: live === undefined ? mount.args : live.argsDocument,
     }
 }
+
+/**
+ * A handler's name on MCP and OpenAPI: its method and its route, in the letters a tool's name admits.
+ *
+ * 20.13 — the method first, so two handlers at one route are two names, and a segment's brackets
+ * and dots dropped, so `/media/[id]` reads `media_id` rather than `media__id_`.
+ */
+export function surfaceName(method: Method, route: string): string {
+    return `${method.toLowerCase()}${route === '/' ? '' : route.replace(/[[\].]/g, '')}`.replace(
+        /[^a-zA-Z0-9-]/g,
+        '_',
+    )
+}

package/src/server/testBuild.ts

@@ -7,11 +7,8 @@
 import { mkdir, rename, rm, utimes, writeFile } from 'node:fs/promises' // bun exposes no directory creation, rename, removal, mtime write or exclusive create of its own
 import { dirname } from 'node:path' // bun exposes no path helpers of its own
 import { namesUnder } from './namesUnder.ts'
+import { runBuild } from './runBuild.ts'
 
-// 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),
-)
 // The framework's own source is part of what made a build: a compiler change is a new build.
 const FRAMEWORK = Bun.fileURLToPath(new URL('../..', import.meta.url))
 const POLL_MS = 50
@@ -95,21 +92,6 @@ async function buildInto(
     }
 }
 
-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: createApp could not build the app under ${root} for this test run.\n${said}`,
-        )
-}
-
 /**
  * A hash of everything a build of the app under `root` is made from.
  *