@abide/abide 0.58.0 → 0.101.0

package/src/lib/shared/findExportCallSite.ts

@@ -1,233 +0,0 @@
-import { isAsciiWhitespace } from './isAsciiWhitespace.ts'
-import { isIdentPart } from './isIdentPart.ts'
-import { isIdentStart } from './isIdentStart.ts'
-import { skipNonCode } from './skipNonCode.ts'
-
-/*
-Scans a module source character-by-character — skipping strings,
-templates, comments, regex literals (via skipNonCode), and TypeScript
-generics — for an `export const <name> = <IDENT>(...)` binding the caller
-cares about. On a match returns the identifier text, the export name, and
-the byte ranges of the call's open and close parens; the $rpc and $sockets
-rewriters splice their runtime bindings into those ranges.
-
-The scanner enforces a single matching export per module: a second match
-throws `singleExportError` so each $rpc / $sockets file is required to
-declare exactly one remote function / socket.
-
-A regex pass would be tidier but it can't tell a `GET` mention inside a
-docstring or template literal from the real call, and it can't follow
-nested generics like `GET<Map<K, V>>(`.
-*/
-
-export type ExportCallSite = {
-    ident: string
-    exportName: string
-    callStart: number
-    parenStart: number
-    parenEnd: number
-}
-
-export function findExportCallSite(
-    source: string,
-    matchIdent: (ident: string) => boolean,
-    singleExportError: string,
-): ExportCallSite | undefined {
-    let found: ExportCallSite | undefined
-    const len = source.length
-    let i = 0
-    while (i < len) {
-        const skipped = skipNonCode(source, i)
-        if (skipped !== undefined) {
-            i = skipped
-            continue
-        }
-        const c = source[i]
-        if (isIdentStart(c) && !isIdentPart(source[i - 1])) {
-            let j = i + 1
-            while (j < len && isIdentPart(source[j])) {
-                j++
-            }
-            const ident = source.slice(i, j)
-            if (matchIdent(ident)) {
-                const tail = matchCallTail(source, j)
-                if (tail !== undefined) {
-                    const exportName = detectExportName(source, i)
-                    if (exportName !== undefined) {
-                        if (found !== undefined) {
-                            throw new Error(singleExportError)
-                        }
-                        const parenEnd = findCallEnd(source, tail)
-                        if (parenEnd === undefined) {
-                            throw new Error(`[abide] unmatched \`(\` after \`${ident}\` identifier`)
-                        }
-                        found = {
-                            ident,
-                            exportName,
-                            callStart: i,
-                            parenStart: tail,
-                            parenEnd,
-                        }
-                        i = parenEnd + 1
-                        continue
-                    }
-                }
-            }
-            i = j
-            continue
-        }
-        i++
-    }
-    return found
-}
-
-function matchCallTail(source: string, after: number): number | undefined {
-    let j = after
-    while (j < source.length && isAsciiWhitespace(source[j])) {
-        j++
-    }
-    if (source[j] === '<') {
-        const closed = skipGenerics(source, j)
-        if (closed === undefined) {
-            return undefined
-        }
-        j = closed
-        while (j < source.length && isAsciiWhitespace(source[j])) {
-            j++
-        }
-    }
-    return source[j] === '(' ? j : undefined
-}
-
-/*
-Returns the index immediately after the matching `>` for a generic
-argument list starting at `start`. TypeScript type literals inside the
-generic (`<{ a: string; b: number }>`, function types `<() => X>`,
-tuples `<[A, B]>`, etc.) bring their own paired brackets and
-semicolons, so track depth across `<>`, `()`, `{}`, and `[]` and only
-count a closing `>` when every other bracket is balanced.
-Arrow-function `=>` is treated as a single token so the `>` doesn't
-prematurely close the generic.
-*/
-function skipGenerics(source: string, start: number): number | undefined {
-    let angleDepth = 0
-    let parenDepth = 0
-    let braceDepth = 0
-    let bracketDepth = 0
-    let i = start
-    while (i < source.length) {
-        const skipped = skipNonCode(source, i)
-        if (skipped !== undefined) {
-            i = skipped
-            continue
-        }
-        const c = source[i]
-        if (c === '<') {
-            angleDepth++
-        } else if (c === '>') {
-            const isArrow = source[i - 1] === '='
-            if (!isArrow && parenDepth === 0 && braceDepth === 0 && bracketDepth === 0) {
-                angleDepth--
-                if (angleDepth === 0) {
-                    return i + 1
-                }
-            }
-        } else if (c === '(') {
-            parenDepth++
-        } else if (c === ')') {
-            parenDepth--
-        } else if (c === '{') {
-            braceDepth++
-        } else if (c === '}') {
-            braceDepth--
-        } else if (c === '[') {
-            bracketDepth++
-        } else if (c === ']') {
-            bracketDepth--
-        }
-        i++
-    }
-    return undefined
-}
-
-/*
-Walks the call body, skipping strings/templates/comments/regex and
-respecting nested `()` so brackets inside object literals or nested calls
-don't throw the depth count.
-*/
-function findCallEnd(source: string, parenStart: number): number | undefined {
-    let depth = 1
-    let i = parenStart + 1
-    while (i < source.length) {
-        const skipped = skipNonCode(source, i)
-        if (skipped !== undefined) {
-            i = skipped
-            continue
-        }
-        const c = source[i]
-        if (c === '(') {
-            depth++
-        } else if (c === ')') {
-            depth--
-            if (depth === 0) {
-                return i
-            }
-        }
-        i++
-    }
-    return undefined
-}
-
-/*
-Looks backwards from a `<IDENT>(` callStart to confirm it was bound by
-`export const <name> = ...`. Returns the identifier in `<name>` if so,
-undefined otherwise — used to skip mentions of an identifier that
-isn't the module's declared export.
-*/
-function detectExportName(source: string, callStart: number): string | undefined {
-    let i = callStart - 1
-    while (i >= 0 && isAsciiWhitespace(source[i])) {
-        i--
-    }
-    if (source[i] !== '=') {
-        return undefined
-    }
-    i--
-    while (i >= 0 && isAsciiWhitespace(source[i])) {
-        i--
-    }
-    const nameEnd = i + 1
-    while (i >= 0 && isIdentPart(source[i])) {
-        i--
-    }
-    const nameStart = i + 1
-    if (nameStart === nameEnd) {
-        return undefined
-    }
-    const name = source.slice(nameStart, nameEnd)
-    while (i >= 0 && isAsciiWhitespace(source[i])) {
-        i--
-    }
-    if (!matchesBackwards(source, i, 'const')) {
-        return undefined
-    }
-    i -= 'const'.length
-    while (i >= 0 && isAsciiWhitespace(source[i])) {
-        i--
-    }
-    if (!matchesBackwards(source, i, 'export')) {
-        return undefined
-    }
-    return name
-}
-
-function matchesBackwards(source: string, end: number, keyword: string): boolean {
-    const start = end - keyword.length + 1
-    if (start < 0) {
-        return false
-    }
-    if (source.slice(start, end + 1) !== keyword) {
-        return false
-    }
-    return start === 0 || !isIdentPart(source[start - 1])
-}

package/src/lib/shared/formatTraceparent.ts

@@ -1,6 +0,0 @@
-import type { TraceContext } from './types/TraceContext.ts'
-
-// Serialises a TraceContext to the W3C `traceparent` wire form (version 00).
-export function formatTraceparent(context: TraceContext): string {
-    return `00-${context.traceId}-${context.spanId}-${context.flags}`
-}

package/src/lib/shared/forwardHeaders.ts

@@ -1,44 +0,0 @@
-import { extraForwardHeaders } from './extraForwardHeaders.ts'
-
-/*
-Headers abide forwards from an inbound HTTP/MCP request onto every
-synthesized in-process rpc Request — cookies + bearer auth + the four
-forwarding hints proxies set when terminating TLS in front of the app.
-defineRpc uses this when an SSR pass calls a rpc in-process; the MCP
-dispatcher uses it when piping a tool invocation through rpc.fetch.
-
-WARNING — this is an allowlist: every inbound header NOT named here (and
-not added via app.forwardHeaders) is DROPPED on the in-process path. A
-handler that reads e.g. `accept-language`, an idempotency key, a trace
-header, or a custom `x-tenant-*` during SSR or an MCP call sees nothing,
-and the call still succeeds with a degraded request. Add the names you
-rely on via the `forwardHeaders` export in src/app.ts.
-
-Centralised so both call sites can't drift on which headers are
-considered "auth/identity" context.
-*/
-const FORWARDED_HEADERS = [
-    'cookie',
-    'authorization',
-    /* W3C trace context rides every hop so a handler reading headers sees the caller's position. */
-    'traceparent',
-    'tracestate',
-    'x-forwarded-for',
-    'x-forwarded-proto',
-    'x-forwarded-host',
-]
-
-export function forwardHeaders(source: Headers): Headers {
-    const headers = new Headers()
-    // Iterate the two fixed arrays directly — both are request-invariant, so
-    // a spread-concat here would allocate a fresh array on every SSR/MCP call.
-    const copy = (name: string) => {
-        const value = source.get(name)
-        if (value) {
-            headers.set(name, value)
-        }
-    }
-    FORWARDED_HEADERS.forEach(copy)
-    extraForwardHeaders.get().forEach(copy)
-    return headers
-}

package/src/lib/shared/generateDeclarations.ts

@@ -1,72 +0,0 @@
-import { existsSync } from 'node:fs'
-import { Glob } from 'bun'
-import { abideImportName } from './abideImportName.ts'
-import { abideLog } from './abideLog.ts'
-import { rpcServerForRoot } from './rpcServerForRoot.ts'
-import { scanPages } from './scanPages.ts'
-import { writeHealthDts } from './writeHealthDts.ts'
-import { writePublicAssetsDts } from './writePublicAssetsDts.ts'
-import { writeRoutesDts } from './writeRoutesDts.ts'
-import { writeRpcDts } from './writeRpcDts.ts'
-import { writeTestRpcDts } from './writeTestRpcDts.ts'
-import { writeTestSocketsDts } from './writeTestSocketsDts.ts'
-
-/* Globs a project subtree once, returning [] when the dir is absent so an app
-   missing a folder still generates the same (mirrors the plugin's scanDir /
-   scanPublicOnce). */
-async function scanDir(dir: string, pattern: string, onlyFiles: boolean): Promise<string[]> {
-    if (!existsSync(dir)) {
-        return []
-    }
-    return await Array.fromAsync(new Glob(pattern).scan({ cwd: dir, onlyFiles }))
-}
-
-/*
-The single producer of the dev-editor `.d.ts` artifacts under src/.abide
-(routes/rpc/testRpc/testSockets/health/publicAssets). Owned by build() and run
-CONCURRENTLY with Bun.build so its one rpc `ts.Program` build (ADR-0025 D2's
-alias-aware method detection) hides under the bundle. The runtime server (dev
-worker / `abide start`) no longer generates any `.d.ts` at boot — that removed
-the per-boot program build. Every `.d.ts` here is a non-critical editor
-convenience (CI typechecks via shadow programs, not these files), so the whole
-body is guarded: a codegen hiccup LOGS and resolves rather than failing the
-build.
-*/
-export async function generateDeclarations({ cwd }: { cwd: string }): Promise<void> {
-    try {
-        const rpcDir = `${cwd}/src/server/rpc`
-        const socketsDir = `${cwd}/src/server/sockets`
-        const pagesDir = `${cwd}/src/ui/pages`
-        const publicDir = `${cwd}/src/ui/public`
-        const [importName, pagesScan, rpcFiles, socketFiles, publicFiles] = await Promise.all([
-            abideImportName(cwd),
-            scanPages(pagesDir),
-            scanDir(rpcDir, '**/*.ts', false),
-            scanDir(socketsDir, '**/*.ts', false),
-            scanDir(publicDir, '**/*', true),
-        ])
-        /* One program per build (ADR-0025 D2): resolve each rpc's method off its export helper
-           SYMBOL so an aliased/re-exported helper resolves where writeRpcDts's regex misses it.
-           Fails open to undefined, in which case writeRpcDts falls back to its own regex. */
-        const rpcServerProgram = rpcServerForRoot(new Map(), cwd, rpcDir)
-        const hasAppModule = existsSync(`${cwd}/src/app.ts`)
-        await Promise.all([
-            writeRoutesDts({ cwd, pageFiles: pagesScan.pageFiles, importName }),
-            writeRpcDts({
-                cwd,
-                rpcDir,
-                rpcFiles,
-                importName,
-                methodForModule: rpcServerProgram
-                    ? (modulePath) => rpcServerProgram.methodForModule(modulePath)
-                    : undefined,
-            }),
-            writeTestRpcDts({ cwd, rpcFiles, importName }),
-            writeTestSocketsDts({ cwd, socketFiles, importName }),
-            writeHealthDts({ cwd, hasAppModule, importName }),
-            writePublicAssetsDts({ cwd, publicFiles, importName }),
-        ])
-    } catch (error) {
-        abideLog.error(error)
-    }
-}

package/src/lib/shared/getRemoteMeta.ts

@@ -1,5 +0,0 @@
-import { remoteMetaStore } from './remoteMetaStore.ts'
-
-export function getRemoteMeta(promise: Promise<unknown>): Request | undefined {
-    return remoteMetaStore.get(promise)?.()
-}

package/src/lib/shared/hasSeedableRequest.ts

@@ -1,25 +0,0 @@
-import type { CacheEntry } from './types/CacheEntry.ts'
-
-/*
-Whether a cache entry carries a wire request that can be SEEDED into the SSR warm
-snapshot — any method, so an inline (bare smart read) call hydrates warm on the
-client instead of re-firing after render, regardless of verb. A value called
-inline during render is being used as a read; the seed carries the SSR-computed
-body so the client reads it warm rather than issuing a second call. Producer
-entries (no request) and stream cells (a `NamedAsyncIterable` cell holds no wire
-request) fail it — neither can round-trip a url/method/body through the snapshot.
-
-This gates SEEDING, not re-firing. Re-firing unprompted (invalidate-policy
-refetch, snapshot replay) stays GET-only (REPLAYABLE_METHODS / isReplayableMethod
-in cache.ts) so a genuine write coalesces-only and stays re-submittable — a
-seeded POST is read warm once, never auto-replayed.
-
-The request half of snapshot shippability, factored out so the two gates that
-need it cannot drift: `snapshotShippable` composes it with `settled` for the
-store-filter sites, and `snapshotEntryFromCache` calls it alone — its
-streaming-drain caller hands it still-pending entries it then awaits, so it can't
-require `settled` up front.
-*/
-export function hasSeedableRequest(entry: CacheEntry): boolean {
-    return entry.request !== undefined
-}

package/src/lib/shared/health.ts

@@ -1,179 +0,0 @@
-import { canonicalJson } from './canonicalJson.ts'
-import { createLivenessWatch } from './createLivenessWatch.ts'
-import { createSubscriber } from './createSubscriber.ts'
-import { HEALTH_PATH } from './HEALTH_PATH.ts'
-import { healthReadSlot } from './healthReadSlot.ts'
-import { healthSeedSlot } from './healthSeedSlot.ts'
-import { isAbideHealthPayload } from './isAbideHealthPayload.ts'
-import { withBase } from './withBase.ts'
-
-/*
-Augmented by the generated `src/.abide/health.d.ts` with
-`{ fields: <the app health() hook's resolved return> }`, so a project's
-`health()` reads type against its own hook. Unaugmented (no app.ts, or no
-hook), AppHealth resolves to no fields.
-*/
-// @documentation observability
-// biome-ignore lint/suspicious/noEmptyInterface: augmented by the generated health.d.ts
-export interface AppHealthMap {}
-export type AppHealth = AppHealthMap extends { fields: infer Fields }
-    ? Fields extends object
-        ? Fields
-        : Record<never, never>
-    : Record<never, never>
-
-/*
-What health() reports: `reachable` is the framework's transport verdict; the
-rest is the last successful payload, whole — the framework identity (`abide`
-carries the framework version, `name`/`version` the app's) plus the app
-health() hook's fields, exactly as /__abide/health serves them. Fields
-persist while unreachable (last-known state beats vanishing fields: "was
-authenticated, currently unreachable" and "reachable, not authenticated"
-need different UI) and are Partial because nothing has arrived before the
-first poll — unless the SSR seed shipped them with the document.
-*/
-export type HealthState = {
-    reachable: boolean
-    abide?: string
-    name?: string
-    version?: string
-} & Partial<AppHealth>
-
-const PROBE_INTERVAL_MS = 10_000
-const PROBE_TIMEOUT_MS = 5_000
-
-/* Last successful payload's app fields (framework identity keys stripped). */
-let fields: Record<string, unknown> = {}
-/* The watch's verdict; composed with navigator.onLine at read time. */
-let backendAlive = true
-let notify: (() => void) | undefined
-
-/*
-One probe: the same standard of proof as the launcher's probeAbideServer —
-a `abide` key in the body, never response.ok alone, because a captive
-portal answers any GET with a 200. Captures the whole payload (identity
-keys included) as a side effect; a changed payload (e.g. authenticated
-flipping) notifies readers even though reachability didn't transition.
-*/
-async function probeHealth(url: string): Promise<boolean> {
-    try {
-        const response = await fetch(url, {
-            headers: { accept: 'application/json' },
-            cache: 'no-store',
-            signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
-        })
-        if (!response.ok) {
-            return false
-        }
-        const body = (await response.json()) as Record<string, unknown>
-        if (!isAbideHealthPayload(body)) {
-            return false
-        }
-        applyFields(body)
-        return true
-    } catch {
-        return false
-    }
-}
-
-/* Swaps in a changed payload and notifies readers; identical payloads stay silent. */
-function applyFields(payload: Record<string, unknown>): void {
-    if (canonicalJson(payload) !== canonicalJson(fields)) {
-        fields = payload
-        notify?.()
-    }
-}
-
-const watch = createLivenessWatch({
-    probe: probeHealth,
-    onChange(alive) {
-        backendAlive = alive
-        notify?.()
-    },
-    intervalMs: PROBE_INTERVAL_MS,
-})
-
-/*
-Reader-driven lifecycle (the createSubscriber rule): the first tracking
-reader starts the poll, the last one tears it down — an app that never
-reads health() never sends a byte. Mirrors the socket channel's visibility
-philosophy: hidden tabs hold no poll (nobody is looking at the banner),
-and the visible transition probes immediately so the value is honest the
-moment eyes return. The online event also probes immediately — recovery
-confirmation shouldn't wait out the interval; offline needs no probe
-because read-time composition with navigator.onLine reports it instantly.
-*/
-const subscribeHealth =
-    typeof window === 'undefined'
-        ? undefined
-        : createSubscriber((update) => {
-              notify = update
-              const onVisibility = () => {
-                  if (document.visibilityState === 'hidden') {
-                      watch.stop()
-                      return
-                  }
-                  watch.watch(withBase(HEALTH_PATH))
-                  watch.probeNow()
-              }
-              const onOnline = () => {
-                  watch.probeNow()
-                  update()
-              }
-              const onOffline = () => update()
-              document.addEventListener('visibilitychange', onVisibility)
-              window.addEventListener('online', onOnline)
-              window.addEventListener('offline', onOffline)
-              watch.watch(withBase(HEALTH_PATH))
-              /*
-              SSR seed: a page that read health() during its server render
-              shipped the payload in __SSR__ (startClient parks it on the
-              slot). The document's arrival just proved the server
-              reachable, so the immediate first probe is skipped — the
-              watch's interval owns the next one — and the fields apply a
-              microtask after connect: the hydration read still matches the
-              server-rendered DOM (the server render carried no fields),
-              while the update lands before first paint. Consumed once;
-              later reconnects probe immediately as usual.
-              */
-              const seed = healthSeedSlot.payload
-              healthSeedSlot.payload = undefined
-              if (seed) {
-                  queueMicrotask(() => applyFields(seed))
-              } else {
-                  watch.probeNow()
-              }
-              return () => {
-                  document.removeEventListener('visibilitychange', onVisibility)
-                  window.removeEventListener('online', onOnline)
-                  window.removeEventListener('offline', onOffline)
-                  watch.stop()
-                  notify = undefined
-              }
-          })
-
-/*
-Reactive backend-health read: `reachable` plus whatever the app's
-health(request) hook reports, polled from /__abide/health only while a
-tracking scope ($derived/$effect) is reading it. Like tail and cache —
-and unlike the pending()/refreshing() probes — reading this opens a
-resource (the poll). Constant `{ reachable: true }` on the server: the
-server is its own backend. navigator.onLine composes in at read time, so
-a lost network reports instantly without waiting for a probe to time out.
-*/
-export function health(): HealthState {
-    /* window, not navigator: Bun defines a partial navigator with no onLine. */
-    if (typeof window === 'undefined') {
-        /*
-        Mark the request (when the server runtime installed a marker) so the
-        renderer stamps the health payload into __SSR__ — the client's seed.
-        The render itself stays fields-less: the hook may be async and this
-        read is sync, so the payload is built after the render returns.
-        */
-        healthReadSlot.mark?.()
-        return { reachable: true } as HealthState
-    }
-    subscribeHealth?.()
-    /* reachable last: it is the framework's verdict, never a hook field's to shadow. */
-    return { ...fields, reachable: backendAlive && navigator.onLine } as HealthState
-}

package/src/lib/shared/healthReadSlot.ts

@@ -1,11 +0,0 @@
-/*
-Server-side registration point for health()'s SSR read mark. createServer
-installs a marker that flags the current request store; the renderer reads
-the flag to stamp the health payload into __SSR__ only for pages that
-actually read health() during their render — the same reader-driven rule as
-the client poll. Browser bundles never install one, so the shared module's
-call no-ops there. Mirrors requestScopeSlot.
-*/
-export const healthReadSlot: { mark: (() => void) | undefined } = {
-    mark: undefined,
-}

package/src/lib/shared/healthSeedSlot.ts

@@ -1,12 +0,0 @@
-/*
-One-shot handoff of the SSR-stamped health payload (__SSR__.health) from
-startClient to the shared health module. startClient writes it before
-hydrate; health()'s first subscriber consumes it, applying the fields
-without the immediate first probe — the document's arrival just proved the
-server reachable, so the first poll waits a full interval. A slot rather
-than a second export on health.ts keeps the seeding one-way and the module
-single-callable. Mirrors healthReadSlot, its server half.
-*/
-export const healthSeedSlot: { payload: Record<string, unknown> | undefined } = {
-    payload: undefined,
-}

package/src/lib/shared/html.ts

@@ -1,19 +0,0 @@
-/* The registered brand for trusted raw markup. `Symbol.for` resolves through the
-   global registry, so this binding is the same symbol across module/bundle copies;
-   `html` (`abide/ui/html`) imports it to brand, `rawHtmlString` reads it back. */
-export const RAW_HTML = Symbol.for('abide.rawHtml')
-
-/* A value marked as trusted raw markup — a `{expr}` interpolation inserts it
-   verbatim (not escaped) on both sides. The brand is a registered Symbol, so it
-   survives across module/bundle copies. Branded by `html` (`abide/ui/html`); read
-   back by `rawHtmlString` here — the isomorphic reader both runtimes consume. */
-export type RawHtml = { readonly [RAW_HTML]: string }
-
-/* The raw markup of a `html`-branded value, or undefined for anything else
-   (so text bindings can fast-path plain values and only branded ones go raw). */
-// @documentation plumbing
-export function rawHtmlString(value: unknown): string | undefined {
-    return value !== null && typeof value === 'object' && RAW_HTML in value
-        ? (value as RawHtml)[RAW_HTML]
-        : undefined
-}

package/src/lib/shared/httpErrorFor.ts

@@ -1,26 +0,0 @@
-import { contentBodyKind } from './contentBodyKind.ts'
-import { contentTypeOf } from './contentTypeOf.ts'
-import { HttpError } from './HttpError.ts'
-
-/*
-Builds the HttpError for a non-2xx response, parsing a typed-error body
-(`{ $abideError, data }`, emitted by an `error.typed(...)` constructor and validation 422)
-onto `.kind` / `.data`. Reads a clone so the original `response.body` stays
-unread for callers that inspect it. A non-JSON or malformed body leaves
-`.kind` / `.data` undefined (a plain `error(status, text)`). Shared by the
-plain decode path (decodeResponse) and the streaming path (streamResponse) so
-both surface the same typed error on a non-2xx.
-*/
-export async function httpErrorFor(response: Response): Promise<HttpError> {
-    if (contentBodyKind(contentTypeOf(response.headers)) === 'json') {
-        try {
-            const body = await response.clone().json()
-            if (body !== null && typeof body === 'object' && '$abideError' in body) {
-                return new HttpError(response, body.$abideError, body.data)
-            }
-        } catch {
-            /* malformed JSON error body — fall through to a plain HttpError */
-        }
-    }
-    return new HttpError(response)
-}