@abide/abide 0.58.0 → 0.100.0

package/src/server/CLIENT_BUILD.ts

@@ -0,0 +1,56 @@
+// WHERE THE BROWSER BUNDLE LANDS, named once for the commands that have to agree about it:
+// `abide build` writes it, `abide start` answers it, and `abide dev` builds it into memory
+// (38.17, 38.21). A leaf, with no imports of its own, for the reason every constant crossing a
+// seam is one — the build is in `bin/` and the server is in `src/server/`, and a string spelled out
+// in both is a build that silently serves nothing. The addresses it is answered at are
+// `#shared/ADDRESSES.ts`.
+
+/** The directory the bundle lands in, below the build's own output directory. */
+export const CLIENT_DIRECTORY = 'client'
+
+/**
+ * The module that mounts the app — the one bundle file whose name the shell writes out.
+ *
+ * Everything else a page needs is reached from here and named by the bundler.
+ *
+ * THE STYLESHEET IS THE SAME NAME. A `.abide` that imports a stylesheet (34.6) makes it a
+ * dependency of the client module, and the bundler collects every one it reaches under an entry
+ * into `<entry>.css` — so the extension is the whole difference and there is no second constant.
+ */
+export const CLIENT_ENTRY = 'entry'
+
+/**
+ * The manifest file `abide build` writes beside the client directory.
+ *
+ * 38.5 — the manifest `manifestOf` reads off the bundle, below the build's own output directory
+ * and BESIDE the client directory rather than in it: everything in there is answered under
+ * `CLIENT_ADDRESS` (38.21), and the manifest is the server's, not the browser's.
+ */
+export const MANIFEST = 'manifest.json'
+
+/**
+ * The encodings a response can be compressed in, each with its precompressed file's suffix.
+ *
+ * 38.5 — in the order a tie is broken. Brotli first: it is the smaller of the two on the bundle,
+ * and every browser that sends it over https decodes it. Gzip is the one a browser asks for over
+ * plain http. The build writes these and `abide start` reads them, so the suffix spelled twice is
+ * a build that precompresses into files nothing ever serves.
+ */
+export const ENCODING_SUFFIX = { br: '.br', gzip: '.gz' } as const
+
+/**
+ * Where `abide build` copies `src/ui/public`, below its own output directory.
+ *
+ * 38.19 — a directory rather than the source tree: `abide start` boots what the build produced and
+ * reaches for nothing an app might have moved since.
+ */
+export const PUBLIC_DIRECTORY = 'public'
+
+/**
+ * Where the build puts the module a browser gets in place of each handler module.
+ *
+ * 16.28 — below the build's own output: the source's path, with this in front. One lookup for the
+ * client bundle to make (`fenceServer`), and a place a reader can open to see exactly what the
+ * browser was handed.
+ */
+export const WIRE_DIRECTORY = 'wire'

package/src/server/DEFAULT_PORT.ts

@@ -0,0 +1,6 @@
+/**
+ * The port an app listens on where neither `--port` nor `PORT` names one: `Bun.serve`'s own default,
+ * so `abide start`'s, the first `abide dev` tries (38.64), and the one a command reaching the local
+ * app calls.
+ */
+export const DEFAULT_PORT = 3000

package/src/server/DOCUMENT_HEADERS.ts

@@ -0,0 +1,11 @@
+// The headers a document starts from, a page's and an error page's alike. A leaf, because the page
+// lane and the failure it answers in its place are two modules that have to agree on them.
+
+// 21.3, 21.6, 21.18.
+export const DOCUMENT_HEADERS = {
+    'content-type': 'text/html; charset=utf-8',
+    'cache-control': 'private, no-store',
+    'referrer-policy': 'strict-origin-when-cross-origin',
+    'content-security-policy': "frame-ancestors 'none'",
+    vary: 'accept-encoding',
+}

package/src/server/Inbox.ts

@@ -0,0 +1,36 @@
+/**
+ * A queue one side pushes into and one reader drains as an async iterator, ending when closed.
+ *
+ * The relay's shape: whatever arrives from the bridge is pushed as it lands, and the turn reading it
+ * waits only where nothing has.
+ */
+export class Inbox<Item> implements AsyncIterable<Item> {
+    #items: Item[] = []
+    #closed = false
+    #wake: (() => void) | undefined = undefined
+
+    push(item: Item): void {
+        if (this.#closed) return
+        this.#items.push(item)
+        this.#wake?.()
+    }
+
+    close(): void {
+        this.#closed = true
+        this.#wake?.()
+    }
+
+    async *[Symbol.asyncIterator](): AsyncGenerator<Item> {
+        for (;;) {
+            if (this.#items.length > 0) {
+                yield this.#items.shift() as Item
+                continue
+            }
+            if (this.#closed) return
+            await new Promise<void>((done) => {
+                this.#wake = done
+            })
+            this.#wake = undefined
+        }
+    }
+}

package/src/server/LogPanel.ts

@@ -0,0 +1,239 @@
+import { useColor } from '#shared/log.ts'
+import { paint } from '#shared/paint.ts'
+
+const ESCAPE = '\x1b['
+const CONSOLE_METHODS = ['log', 'info', 'warn', 'error', 'debug'] as const
+/** The panel lines kept for a repaint — more than any terminal is tall. */
+const LINES_KEPT = 1000
+
+/**
+ * The shell's terminal layout: a heading pinned at the top, the console tailed in a scrolling panel
+ * under it, and the prompt pinned on the last row.
+ *
+ * EVERY CONSOLE LINE LANDS IN THE PANEL, the logger's among them (28.1 writes through the console),
+ * so the prompt and whatever the user is half-way through typing stay put while the app logs.
+ *
+ * A SCROLL REGION: the terminal scrolls the panel's rows itself, and Enter on the last row, below the
+ * region, moves nothing. After each write the cursor goes back to the last row and `redraw` puts the
+ * prompt and the line being typed there — asked of whoever holds that line, rather than restored with
+ * DECSC/DECRC, which some terminals clamp into the scroll region.
+ *
+ * ON THE ALTERNATE SCREEN, REPAINTED WHOLE ON A RESIZE, out of the lines kept. A terminal made taller
+ * pulls its scrollback down into view, and one made narrower reflows what it holds, so a layout that
+ * only redrew its own rows left every earlier copy of the heading standing beneath the new one. The
+ * alternate screen has no scrollback to pull, and hands the shell's screen back as it was on close.
+ */
+export class LogPanel {
+    #heading: string[]
+    #hint: string
+    /** What the divider says in place of `#hint` while the line being typed has something to say. */
+    #signature: string | undefined = undefined
+    #redraw: () => void
+    #color = useColor()
+    #rows = 0
+    #columns = 0
+    #top = 1
+    #bottom = 1
+    /** The next empty row while the panel fills from the top; past `#bottom` it scrolls. */
+    #next = 1
+    /** The panel's lines, newest last — trimmed back to `LINES_KEPT` once twice that. */
+    #lines: string[] = []
+    /** What Tab could complete to, laid over the panel's last rows until `hideCompletions`. */
+    #completions: string[] = []
+    #originals: Pick<Console, (typeof CONSOLE_METHODS)[number]>
+    #closed = false
+    #resize = (): void => this.#layout()
+    #exit = (): void => this.close()
+
+    constructor(heading: string, hint: string, redraw: () => void) {
+        this.#heading = heading.replace(/\n+$/, '').split('\n')
+        this.#hint = hint
+        this.#redraw = redraw
+        this.#originals = {
+            log: console.log,
+            info: console.info,
+            warn: console.warn,
+            error: console.error,
+            debug: console.debug,
+        }
+        const write = (...args: unknown[]): void =>
+            this.write(formatted(args, this.#color))
+        for (const method of CONSOLE_METHODS) console[method] = write
+        process.stdout.on('resize', this.#resize)
+        // A signal ends the process through `stopOnSignalOrFault`, and a terminal left on the
+        // alternate screen with a scroll region set is one the next command cannot use.
+        process.on('exit', this.#exit)
+        process.stdout.write(`${ESCAPE}?1049h`)
+        this.#layout()
+    }
+
+    /** Writes text into the panel, above the prompt. */
+    write(text: string): void {
+        if (this.#closed) {
+            this.#originals.log(text)
+            return
+        }
+        let out = ''
+        for (const line of text.split('\n')) {
+            this.#lines.push(line)
+            out += this.#placed(line)
+        }
+        if (this.#lines.length > LINES_KEPT * 2)
+            this.#lines.splice(0, this.#lines.length - LINES_KEPT)
+        // A line scrolled under the completions would carry them up the panel with it.
+        if (this.#completions.length > 0) {
+            this.#layout()
+            return
+        }
+        process.stdout.write(out)
+        this.prompt()
+    }
+
+    /** Lays `completions` over the panel's last rows, in columns, until `hideCompletions`. */
+    showCompletions(completions: string[]): void {
+        if (this.#closed) return
+        this.#completions = completions
+        this.#layout()
+    }
+
+    /** Empties the panel. */
+    clear(): void {
+        if (this.#closed) return
+        this.#lines = []
+        this.#completions = []
+        this.#layout()
+    }
+
+    /** Takes the completions away, and paints the panel back under them. */
+    hideCompletions(): void {
+        if (this.#closed || this.#completions.length === 0) return
+        this.#completions = []
+        this.#layout()
+    }
+
+    /** Puts the cursor on the last row and has the prompt redrawn there. */
+    prompt(): void {
+        if (this.#closed) return
+        process.stdout.write(`${ESCAPE}${this.#rows};1H`)
+        this.#redraw()
+    }
+
+    /** Hands the terminal back as it was found: its own screen, the console its own again. */
+    close(): void {
+        if (this.#closed) return
+        this.#closed = true
+        Object.assign(console, this.#originals)
+        process.stdout.off('resize', this.#resize)
+        process.off('exit', this.#exit)
+        process.stdout.write(`${ESCAPE}r${ESCAPE}?1049l`)
+    }
+
+    /** The escapes that write one line at the panel's next row, scrolling it once it is full. */
+    #placed(line: string): string {
+        if (this.#next > this.#bottom)
+            return `${ESCAPE}${this.#bottom};1H\n${line}`
+        const placed = `${ESCAPE}${this.#next};1H${line}`
+        this.#next += this.#rowsOf(line)
+        return placed
+    }
+
+    #rowsOf(line: string): number {
+        return Math.max(1, Math.ceil(Bun.stringWidth(line) / this.#columns))
+    }
+
+    #layout(): void {
+        this.#rows = process.stdout.rows
+        this.#columns = process.stdout.columns
+        const headingRows = this.#heading.length + 1
+        // PINNED ONLY WHERE THERE IS ROOM: a panel of a row or two under a tall heading tails nothing.
+        this.#top = this.#rows - headingRows > 6 ? headingRows + 1 : 1
+        this.#bottom = this.#rows - 2
+        let out = `${ESCAPE}r${ESCAPE}2J`
+        if (this.#top > 1)
+            for (let row = 0; row < this.#heading.length; row += 1)
+                out += `${ESCAPE}${row + 1};1H${this.#heading[row]}`
+        out += `${ESCAPE}${this.#top};${this.#bottom}r`
+        // The newest lines that fit, oldest of them first.
+        let first = this.#lines.length
+        let used = 0
+        while (first > 0) {
+            used += this.#rowsOf(this.#lines[first - 1] as string)
+            if (used > this.#bottom - this.#top + 1) break
+            first -= 1
+        }
+        this.#next = this.#top
+        for (let at = first; at < this.#lines.length; at += 1)
+            out += this.#placed(this.#lines[at] as string)
+        out += this.#completionRows()
+        process.stdout.write(out + this.#divider())
+        this.prompt()
+    }
+
+    /** Has the divider say `signature` in place of its hint, or its hint again where `undefined`. */
+    setSignature(signature: string | undefined): void {
+        if (this.#closed || signature === this.#signature) return
+        this.#signature = signature
+        process.stdout.write(this.#divider())
+        this.prompt()
+    }
+
+    #divider(): string {
+        const text = (this.#signature ?? this.#hint).slice(
+            0,
+            Math.max(0, this.#columns - 4),
+        )
+        const fill = '─'.repeat(Math.max(0, this.#columns - text.length - 4))
+        const said =
+            this.#signature === undefined ? this.#paint('2', text) : text
+        return `${ESCAPE}${this.#rows - 1};1H${ESCAPE}2K${this.#paint('2', '── ')}${said}${this.#paint('2', ` ${fill}`)}`
+    }
+
+    /** The completions in columns, over the panel's last rows — as many rows as half the panel. */
+    #completionRows(): string {
+        const count = this.#completions.length
+        if (count === 0) return ''
+        let widest = 0
+        for (const completion of this.#completions)
+            widest = Math.max(widest, Bun.stringWidth(completion))
+        const width = Math.min(widest + 2, this.#columns)
+        const perRow = Math.max(1, Math.floor(this.#columns / width))
+        const room = Math.max(1, Math.floor((this.#bottom - this.#top + 1) / 2))
+        let rows = Math.ceil(count / perRow)
+        // The last row says how many more there are, rather than one more of them.
+        const shown = rows > room ? (room - 1) * perRow : count
+        rows = Math.min(rows, room)
+        let out = ''
+        for (let row = 0; row < rows; row += 1) {
+            let text = ''
+            for (let column = 0; column < perRow; column += 1) {
+                const completion = this.#completions[row * perRow + column]
+                if (completion === undefined || row * perRow + column >= shown)
+                    break
+                text += completion.slice(0, width - 2).padEnd(width)
+            }
+            if (row === rows - 1 && shown < count)
+                text = this.#paint(
+                    '2',
+                    `… ${count - shown} more — type to narrow`,
+                )
+            out += `${ESCAPE}${this.#bottom - rows + 1 + row};1H${ESCAPE}2K${text}`
+        }
+        return out
+    }
+
+    #paint(code: string, text: string): string {
+        return paint(this.#color, code, text)
+    }
+}
+
+/** A console call's arguments as the one line `console.log` would print. */
+function formatted(args: unknown[], color: boolean): string {
+    let text = ''
+    for (let at = 0; at < args.length; at += 1) {
+        const arg = args[at]
+        if (at > 0) text += ' '
+        text +=
+            typeof arg === 'string' ? arg : Bun.inspect(arg, { colors: color })
+    }
+    return text
+}

package/src/server/MCP_PROTOCOL_VERSION.ts

@@ -0,0 +1,3 @@
+// The MCP protocol version abide's servers answer `initialize` with: `/__abide/mcp`, and the one a
+// paired bridge's Claude Code reaches through the relay (45.17).
+export const MCP_PROTOCOL_VERSION = '2025-06-18'

package/src/server/SETTLE_MILLISECONDS.ts

@@ -0,0 +1,7 @@
+/**
+ * How long to wait for the tree to stop moving before rebuilding.
+ *
+ * A save from an editor is more than one event — a write, a rename, an attribute change — and one
+ * rebuild per event is several rebuilds for one keystroke.
+ */
+export const SETTLE_MILLISECONDS = 25

package/src/server/VIRTUAL_DIRECTORY.ts

@@ -0,0 +1,6 @@
+// Where `abide dev`'s compiled modules pretend to live, below the app's root: the compile points a
+// relative import back at its source from here (34.14), and the worker serves the modules under it.
+// Under the app's own root so that `#ui/…` and a bare package name resolve from here exactly as they
+// resolve from the build tree — both sit inside the app's package — and under a `__abide` directory
+// for the reason the addresses are: no app writes one.
+export const VIRTUAL_DIRECTORY = '__abide'

package/src/server/answerFailure.ts

@@ -0,0 +1,91 @@
+// A FAILURE, ANSWERED IN THE REPRESENTATION OF THE LANE IT HAPPENED IN: a page's is the nearest error
+// page (35.2), a handler's is the refusal as Problem Details (15.21), and abide's own addresses and
+// the listener answer as text (21.3). Which lane a request is in is the caller's to know; what each
+// lane's failure looks like is decided here, once.
+
+import { type Failed, problemOf } from '#shared/Failed.ts'
+import { RENDER_LOG } from '#shared/log.ts'
+import { coversPrefix, partsOf } from '#shared/matchRoute.ts'
+import type { AppSources } from './answerRequest.ts'
+import { DOCUMENT_HEADERS } from './DOCUMENT_HEADERS.ts'
+import { boundPage, render } from './render.ts'
+import { beginRender } from './requestScope.ts'
+
+/** What a page's failure is painted from: the error pages, and the document they go into. */
+export type ErrorPages = Pick<AppSources, 'errors' | 'errorDocument'>
+
+type RankedError = ErrorPages['errors'][number]
+
+/**
+ * The headers a handler's answer starts from: JSON, never stored, varying on `Origin`.
+ *
+ * 21.7 — whether it is another origin's to read, and whether a mutation from one is refused, both
+ * depend on `Origin`, however this one came.
+ */
+export function handlerHeaders(): Headers {
+    return new Headers({
+        'content-type': 'application/json',
+        'cache-control': 'private, no-store',
+        vary: 'origin',
+    })
+}
+
+/**
+ * The `Response` a refusal is answered with.
+ *
+ * 15.1 — a refusal crosses the wire as Problem Details (RFC 9457), at its own status.
+ */
+export function answered(failure: Failed<string, unknown>): Response {
+    const headers = handlerHeaders()
+    headers.set('content-type', 'application/problem+json')
+    return new Response(JSON.stringify(problemOf(failure)), {
+        status: failure.status,
+        headers,
+    })
+}
+
+/**
+ * The error pages for `pathname`, nearest first.
+ *
+ * 35.2 — every one whose directory is a prefix of the address, each segment meaning what it means
+ * in a route.
+ */
+function errorsFor(errors: RankedError[], pathname: string): RankedError[] {
+    // 15.16's address has no parts to be nearest to, so the root's page paints it.
+    const parts = partsOf(pathname) ?? []
+    const found: RankedError[] = []
+    for (const error of errors)
+        if (coversPrefix(error.segments, parts)) found.push(error)
+    return found
+}
+
+/**
+ * A refusal, painted by the nearest error page at the refusal's own status.
+ *
+ * 35.2, 35.3 — the page is rendered whole before a byte is answered, so one that fails is not
+ * half-sent: it escalates to the next ancestor, and says so on `abide:render`. With none left,
+ * the refusal is answered as text.
+ */
+export async function answerFailure(
+    app: ErrorPages,
+    pathname: string,
+    failure: Failed<string, unknown>,
+): Promise<Response> {
+    const headers = new Headers(DOCUMENT_HEADERS)
+    const status = failure.status
+    for (const error of errorsFor(app.errors, pathname)) {
+        try {
+            const bound = boundPage(error, { failure: () => failure })
+            beginRender(undefined)
+            const document = await render(bound, app.errorDocument)
+            return new Response(document, { status, headers })
+        } catch (thrown) {
+            RENDER_LOG.warning(
+                `the error page for ${error.pattern} failed, so the next one answers`,
+                thrown,
+            )
+        }
+    }
+    headers.set('content-type', 'text/plain; charset=utf-8')
+    return new Response(failure.message, { status, headers })
+}