@abide/abide 0.28.0

package/src/lib/shared/cacheEntryFromSnapshot.ts

@@ -0,0 +1,59 @@
+import type { CacheEntry } from './types/CacheEntry.ts'
+import type { CacheSnapshotEntry } from './types/CacheSnapshotEntry.ts'
+
+/*
+Rebuilds a warm cache entry from a wire snapshot: an already-resolved Response
+plus the synchronously-decoded warm value, so cache() reads it without a network
+round-trip or a microtask hop. Shared by the initial inline snapshot hydration
+and the streamed resolution path. `settled` is true — the body shipped fully
+resolved either way. `hydrated` marks that the wrap options didn't travel:
+the first cache() read adopts its call site's ttl (see CacheEntry).
+*/
+export function cacheEntryFromSnapshot(entry: CacheSnapshotEntry): CacheEntry {
+    const headers = new Headers(entry.headers)
+    const response = new Response(entry.body, {
+        status: entry.status,
+        statusText: entry.statusText,
+        headers,
+    })
+    return {
+        key: entry.key,
+        promise: Promise.resolve(response),
+        request: new Request(entry.url, { method: entry.method }),
+        ttl: undefined,
+        expiresAt: undefined,
+        value: warmValueFromSnapshot(entry.status, headers, entry.body),
+        settled: true,
+        hydrated: true,
+    }
+}
+
+/*
+Synchronously decodes a snapshot body so the warm entry reads without a
+microtask hop on first render. Mirrors decodeResponse for the textual cases the
+snapshot ships; non-2xx and 204 yield no warm value and fall back to the async
+path, which throws HttpError / returns undefined exactly as a live call would.
+Binary/xml bodies also skip the warm path and decode asynchronously.
+*/
+function warmValueFromSnapshot(status: number, headers: Headers, body: string): unknown {
+    if (status === 204 || status < 200 || status >= 300) {
+        return undefined
+    }
+    const contentType = (headers.get('content-type') ?? '').toLowerCase()
+    if (contentType.includes('json')) {
+        /*
+        `.includes('json')` also matches streaming/non-JSON types like
+        application/x-ndjson; fall back to the async path (return undefined)
+        rather than throwing a SyntaxError synchronously during hydration.
+        */
+        try {
+            return JSON.parse(body)
+        } catch {
+            return undefined
+        }
+    }
+    if (contentType.startsWith('text/')) {
+        return body
+    }
+    return undefined
+}

package/src/lib/shared/cacheStoreSlot.ts

@@ -0,0 +1,16 @@
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Internal slot the runtime entries register their resolver into. The
+server entry installs an ALS-backed resolver (request-scoped); the
+client entry installs a module-singleton resolver. `fallback` is a
+single lazy store used only when no resolver is registered — keeps
+isolated tests working without forcing them to spin up the runtime.
+*/
+export const cacheStoreSlot: {
+    resolver: (() => CacheStore | undefined) | undefined
+    fallback: CacheStore | undefined
+} = {
+    resolver: undefined,
+    fallback: undefined,
+}

package/src/lib/shared/cacheStores.ts

@@ -0,0 +1,10 @@
+import { activeCacheStore } from './activeCacheStore.ts'
+import { globalCacheStore } from './globalCacheStore.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/* Active + process-level stores, deduped (one tab store on the client). */
+export function cacheStores(): CacheStore[] {
+    const active = activeCacheStore()
+    const global = globalCacheStore()
+    return active === global ? [active] : [active, global]
+}

package/src/lib/shared/canonicalJson.ts

@@ -0,0 +1,63 @@
+/*
+Deterministic key string for a value. Object keys (and Map keys, Set members)
+are sorted so values differing only in insertion order produce identical
+strings, and every recognised type carries a tag so distinct types never
+collide — a Date never equals the string of its ISO form, a Map never equals a
+plain object. Used to derive cache keys from producer args and from auto-keyed
+POST/PUT/PATCH bodies; the output is a key, not a request body, so it is free to
+encode types JSON.stringify would silently flatten (Map/Set → {}), coerce
+(Date → its ISO string, via toJSON before any replacer sees it) or drop
+(undefined). Covers the value types commonly passed as rpc args: primitives,
+arrays, plain objects, Date, Map, Set, and bigint. Functions and symbols can't
+key anything meaningful but are tagged rather than dropped so a stray one can't
+silently collapse two distinct argument sets onto the same key.
+*/
+export function canonicalJson(value: unknown): string {
+    if (value === null) {
+        return 'null'
+    }
+    if (value === undefined) {
+        return 'undefined'
+    }
+    const type = typeof value
+    if (type === 'string') {
+        return JSON.stringify(value)
+    }
+    if (type === 'bigint') {
+        return `${value}n`
+    }
+    if (type === 'number') {
+        // -0 and 0 stringify alike but are distinct keys; NaN/Infinity stay stable (JSON drops them to null).
+        return Object.is(value, -0) ? '-0' : String(value)
+    }
+    if (type === 'boolean') {
+        return String(value)
+    }
+    if (type !== 'object') {
+        // function | symbol — not serialisable; tag by type so the key can't crash or alias a real value.
+        return `${type}()`
+    }
+    if (value instanceof Date) {
+        return `Date(${value.getTime()})`
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(',')}]`
+    }
+    if (value instanceof Map) {
+        // Sort by encoded entry so key order doesn't change the result.
+        const entries = Array.from(
+            value,
+            ([key, val]) => `${canonicalJson(key)}=>${canonicalJson(val)}`,
+        ).sort()
+        return `Map{${entries.join(',')}}`
+    }
+    if (value instanceof Set) {
+        const members = Array.from(value, canonicalJson).sort()
+        return `Set{${members.join(',')}}`
+    }
+    const record = value as Record<string, unknown>
+    const entries = Object.keys(record)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`)
+    return `{${entries.join(',')}}`
+}

package/src/lib/shared/carriesBodyArgs.ts

@@ -0,0 +1,13 @@
+import type { HttpVerb } from './types/HttpVerb.ts'
+
+/*
+Whether a verb carries its args in the request body (POST/PUT/PATCH) vs
+on the query string (GET/DELETE/HEAD). Single source for the split so the
+synthesized Request (buildRpcRequest), the handler-side parse (parseArgs),
+the cache key (keyForRemoteCall), and the OpenAPI doc can't disagree.
+*/
+const BODY_METHODS = new Set<HttpVerb>(['POST', 'PUT', 'PATCH'])
+
+export function carriesBodyArgs(method: HttpVerb): boolean {
+    return BODY_METHODS.has(method)
+}

package/src/lib/shared/clearLastConnection.ts

@@ -0,0 +1,7 @@
+import { rm } from 'node:fs/promises'
+import { lastConnectionPath } from './lastConnectionPath.ts'
+
+// Forgets the saved connection (the `/disconnect` reset). Missing file is a no-op.
+export async function clearLastConnection(programName: string): Promise<void> {
+    await rm(lastConnectionPath(programName), { force: true })
+}

package/src/lib/shared/commandNameForUrl.ts

@@ -0,0 +1,17 @@
+/*
+Derives the MCP tool name / CLI subcommand name from an rpc URL. Strips
+the framework's `/rpc/` mount and joins nested folder segments with `-`
+so `users/list.ts` (mounted at `/rpc/users/list`) becomes `users-list`
+across both surfaces. Folder prefixing prevents collisions when two
+files in different folders share the same stem (e.g. `users/list.ts`
+and `posts/list.ts`); `/` is not a valid character in MCP tool names or
+typical CLI subcommands, so the join uses `-`.
+*/
+const RPC_PREFIX = '/rpc/'
+
+export function commandNameForUrl(url: string): string {
+    const trimmed = url.startsWith(RPC_PREFIX)
+        ? url.slice(RPC_PREFIX.length)
+        : url.replace(/^\//, '')
+    return trimmed.replaceAll('/', '-')
+}

package/src/lib/shared/createCacheStore.ts

@@ -0,0 +1,104 @@
+import { createLifecycleChannel } from './createLifecycleChannel.ts'
+import { createSubscriber } from './createSubscriber.ts'
+import { keyMatchesPrefix } from './keyMatchesPrefix.ts'
+import type { CacheEntry } from './types/CacheEntry.ts'
+import type { CacheInvalidation } from './types/CacheInvalidation.ts'
+import type { CacheStore } from './types/CacheStore.ts'
+
+/*
+Returns a fresh cache store. On the server, every request gets its own
+store via the AsyncLocalStorage RequestStore. On the client, a single
+module-level store is created at startup and shared across the tab.
+
+Each key gets a lazily-created subscriber. Reading a key from a
+tracking scope (derived / effect) subscribes that scope; invalidating
+the key dispatches an 'invalidate' event whose detail is a Set of affected
+keys so each listener's lookup is O(1). The subscriber outlives entry
+eviction — invalidating/refetching a key reuses the same subscriber, so
+there's no listener churn or duplicate registration as cache values come
+and go. It's evicted only when its last reactive reader tears down (the
+client store is module-level/tab-scoped, so retaining a thunk per distinct
+key would otherwise grow unbounded across a session), identity-guarded so
+a concurrent re-subscribe isn't clobbered — mirroring tail.ts.
+*/
+export function createCacheStore(): CacheStore {
+    const entries = new Map<string, CacheEntry>()
+    const events = new EventTarget()
+    const subscribers = new Map<string, () => void>()
+    const pendingRefresh = new Set<string>()
+
+    function subscribe(key: string): void {
+        const existing = subscribers.get(key)
+        if (existing) {
+            existing()
+            return
+        }
+        const registered = createSubscriber((update) => {
+            const onInvalidate = (event: Event) => {
+                if ((event as CustomEvent<CacheInvalidation>).detail.has(key)) {
+                    update()
+                }
+            }
+            events.addEventListener('invalidate', onInvalidate)
+            return () => {
+                events.removeEventListener('invalidate', onInvalidate)
+                if (subscribers.get(key) === registered) {
+                    subscribers.delete(key)
+                }
+            }
+        })
+        subscribers.set(key, registered)
+        registered()
+    }
+
+    /* Store-wide in-flight tap for the probes; semantics live in createLifecycleChannel. */
+    const lifecycle = createLifecycleChannel()
+    /*
+    Per-prefix channels arm fn-selector probes (pending(fn) / refreshing(fn))
+    without waking them on unrelated cache events. Keyed by selector prefix
+    (method+url / producer reference id — see selectorPrefix), so the
+    population is bounded by probe call sites in code, not by data; a channel
+    whose last reader tore down is an inert closure, not a leak.
+    */
+    const prefixLifecycles = new Map<string, ReturnType<typeof createLifecycleChannel>>()
+
+    function trackLifecycle(keyPrefix?: string): void {
+        if (keyPrefix === undefined) {
+            lifecycle.track()
+            return
+        }
+        let channel = prefixLifecycles.get(keyPrefix)
+        if (channel === undefined) {
+            channel = createLifecycleChannel()
+            prefixLifecycles.set(keyPrefix, channel)
+        }
+        channel.track()
+    }
+
+    /*
+    Marks the store-wide channel always (bare/scope probes scan everything)
+    plus any probed prefix channel owning the changed key — a new entry's key
+    starts with its fn's prefix, so prefix probes see membership too.
+    */
+    function markLifecycle(key?: string): void {
+        lifecycle.mark()
+        if (key === undefined) {
+            return
+        }
+        prefixLifecycles.forEach((channel, prefix) => {
+            if (keyMatchesPrefix(key, prefix)) {
+                channel.mark()
+            }
+        })
+    }
+
+    return {
+        entries,
+        events,
+        subscribe,
+        trackLifecycle,
+        markLifecycle,
+        pendingRefresh,
+        stats: { hits: 0, misses: 0, coalesced: 0 },
+    }
+}

package/src/lib/shared/createChannelLog.ts

@@ -0,0 +1,122 @@
+import { emitLogRecord } from './emitLogRecord.ts'
+import { isDebugEnabled } from './isDebugEnabled.ts'
+import { isDebugNegated } from './isDebugNegated.ts'
+import { randomHexId } from './randomHexId.ts'
+import type { ChannelLog } from './types/ChannelLog.ts'
+
+/*
+Channel gating source. Server: the DEBUG env var, npm-debug conventions via
+isDebugEnabled. Browser: the `abide-debug` localStorage key with the same
+pattern syntax, read per call so toggling it in devtools takes effect without
+a reload. localStorage access is guarded — privacy modes throw on read.
+*/
+function channelPatterns(): string | undefined {
+    if (typeof process !== 'undefined' && process.env.DEBUG) {
+        return process.env.DEBUG
+    }
+    if (typeof localStorage !== 'undefined') {
+        try {
+            return localStorage.getItem('abide-debug') ?? undefined
+        } catch {
+            return undefined
+        }
+    }
+    return undefined
+}
+
+// Prefers a full stack trace when the value is an Error so logs include the call site.
+function errorParts(value: unknown): { msg: string; stack?: string } {
+    if (value instanceof Error) {
+        return { msg: value.message, stack: value.stack }
+    }
+    return { msg: String(value) }
+}
+
+/* Times `work` under an operation name, minting the record's span id so a future exporter can materialise it as a span. */
+async function traceWork<Return>(
+    name: string,
+    work: () => Return | Promise<Return>,
+    channel: string,
+): Promise<Return> {
+    const spanId = randomHexId(8)
+    const startMs = performance.now()
+    try {
+        const result = await work()
+        emitLogRecord({
+            level: 'info',
+            msg: '',
+            name,
+            spanId,
+            durationMs: performance.now() - startMs,
+            channel,
+        })
+        return result
+    } catch (error) {
+        const { msg, stack } = errorParts(error)
+        emitLogRecord({
+            level: 'error',
+            msg,
+            stack,
+            name,
+            spanId,
+            durationMs: performance.now() - startMs,
+            channel,
+        })
+        throw error
+    }
+}
+
+/*
+Builds the callable-with-levels log shape bound to a channel. Every record
+carries the channel; `getChannel` is a thunk because the default (app-name)
+channel resolves after module init. `always` channels — the app's own and
+abide's framework voice — emit unless a `-name` DEBUG pattern explicitly
+shuts them off; everything else is a diagnostic channel gated by DEBUG
+(browser: the abide-debug localStorage key). Levels never gate: a silenced
+channel is silent at every level, an enabled one shows them all.
+*/
+export function createChannelLog(
+    getChannel: () => string,
+    always: boolean,
+): ChannelLog & { enabled(): boolean } {
+    const enabled = () =>
+        always
+            ? !isDebugNegated(getChannel(), channelPatterns())
+            : isDebugEnabled(getChannel(), channelPatterns())
+    const call = (message: string, data?: unknown): void => {
+        if (enabled()) {
+            emitLogRecord({ level: 'info', msg: message, data, channel: getChannel() })
+        }
+    }
+    return Object.assign(call, {
+        /* Exposed so wrappers (abideLog's styling voices) emit through the same gate. */
+        enabled,
+        warn(message: string, data?: unknown): void {
+            if (enabled()) {
+                emitLogRecord({ level: 'warn', msg: message, data, channel: getChannel() })
+            }
+        },
+        error(value: unknown, data?: unknown): void {
+            if (enabled()) {
+                emitLogRecord({ level: 'error', ...errorParts(value), data, channel: getChannel() })
+            }
+        },
+        trace<Return>(name: string, work: () => Return | Promise<Return>): Promise<Return> {
+            if (enabled()) {
+                return traceWork(name, work, getChannel())
+            }
+            /*
+            No span: skip the async-wrapper allocation that every other method
+            already gates away, and hand back work()'s own promise untouched so
+            a coalesced cache join keeps the shared promise's identity. A
+            synchronous throw still surfaces as a rejection, matching traceWork.
+            */
+            try {
+                const result = work()
+                return result instanceof Promise ? result : Promise.resolve(result)
+            } catch (error) {
+                return Promise.reject(error)
+            }
+        },
+    })
+}

package/src/lib/shared/createLifecycleChannel.ts

@@ -0,0 +1,56 @@
+import { createSubscriber } from './createSubscriber.ts'
+
+/*
+Lifecycle tap shared by the cache store and the tail registry: one
+"membership or state changed" signal for the pending()/refreshing() probes,
+which match a group of entries and re-derive by scanning. The owning
+registry decides the granularity — the cache store keeps a store-wide
+channel plus one per probed selector prefix; this module only owns the
+subscribe/notify semantics. track() inside a
+tracking scope ($derived / $effect) re-runs that scope on every mark();
+outside one it is a no-op. The subscriber is created lazily on the first
+tracked read and self-evicts when its last reader tears down,
+identity-guarded so a concurrent re-track isn't clobbered. mark() is a plain
+callback — the channel only ever has the one memoized listener, so no
+EventTarget dispatch is needed.
+
+mark() defers its notify to a microtask: registry mutations happen inside
+consumer read paths, and the documented read idiom is `$derived(await
+cache(fn)())` — a cold read there registers an entry mid-derived, where
+writing the subscriber's version source throws state_unsafe_mutation. The
+probes scan the registry at re-derive time, so a deferred ping reads state
+that is already current; marks within one tick coalesce into one notify.
+*/
+export function createLifecycleChannel(): { track: () => void; mark: () => void } {
+    let notify: (() => void) | undefined
+    let tracker: (() => void) | undefined
+    let marked = false
+    return {
+        track() {
+            if (!tracker) {
+                const created = createSubscriber((update) => {
+                    notify = update
+                    return () => {
+                        notify = undefined
+                        if (tracker === created) {
+                            tracker = undefined
+                        }
+                    }
+                })
+                tracker = created
+            }
+            tracker()
+        },
+        mark() {
+            if (notify === undefined || marked) {
+                return
+            }
+            marked = true
+            queueMicrotask(() => {
+                marked = false
+                /* Re-read: the last reader may have torn down during the deferral. */
+                notify?.()
+            })
+        },
+    }
+}

package/src/lib/shared/createLivenessWatch.ts

@@ -0,0 +1,118 @@
+/*
+The liveness state machine shared by every "is that server still there?"
+consumer: a recursive timer (never setInterval, so a slow probe can't overlap
+the next) runs `probe(url)`; a success resets the miss count, `failureLimit`
+consecutive misses declare the target down. Two modes by which hook is given:
+
+- `onLost` (terminal): the bundle launcher's mode — down fires onLost once
+  and the watch stops; the user reconnects deliberately.
+- `onChange` (continuous): the client health() mode — down fires
+  onChange(false), polling continues, and the first subsequent success fires
+  onChange(true). Transitions only, never per-poll — except the first success
+  after watch(), which always reports so a consumer that kept state across a
+  stop()/watch() cycle (health's backendAlive) resyncs with the machine.
+
+watch(url) (re)starts against a new target (first probe after one interval —
+probeNow() forces an immediate one); a probe resolving after the target
+changed is discarded (the url capture is the staleness guard). Probe
+transport is injected — the launcher passes the identity-endpoint check, the
+client health() a browser fetch — so the machine is side-neutral.
+*/
+export function createLivenessWatch(options: {
+    probe: (url: string) => Promise<boolean>
+    onLost?: (url: string) => void
+    onChange?: (alive: boolean) => void
+    intervalMs?: number
+    failureLimit?: number
+}): {
+    watch: (url: string) => void
+    stop: () => void
+    probeNow: () => void
+} {
+    const intervalMs = options.intervalMs ?? 4000
+    const failureLimit = options.failureLimit ?? 2
+    let watchedUrl: string | undefined
+    let timer: ReturnType<typeof setTimeout> | undefined
+    let inFlight = false
+    let failures = 0
+    let alive = true
+    /* No verdict reported since watch() — makes the first success always report. */
+    let fresh = true
+
+    async function runProbe(): Promise<void> {
+        const url = watchedUrl
+        if (!url) {
+            return
+        }
+        if (inFlight) {
+            /*
+            A stale probe from a previous target is still awaiting. Keep this
+            watch's timer armed — the stale resolution discards itself without
+            rescheduling, so returning bare here would leave no timer and the
+            new target silently unwatched.
+            */
+            timer = setTimeout(runProbe, intervalMs)
+            return
+        }
+        inFlight = true
+        const up = await options.probe(url)
+        inFlight = false
+        // A stop or re-watch during the await moved the target — discard.
+        if (watchedUrl !== url) {
+            return
+        }
+        if (up) {
+            failures = 0
+            if (!alive || fresh) {
+                alive = true
+                fresh = false
+                options.onChange?.(true)
+            }
+        } else {
+            failures += 1
+            if (failures >= failureLimit && alive) {
+                alive = false
+                fresh = false
+                if (options.onChange) {
+                    options.onChange(false)
+                } else {
+                    stop()
+                    options.onLost?.(url)
+                    return
+                }
+            }
+        }
+        timer = setTimeout(runProbe, intervalMs)
+    }
+
+    function watch(url: string): void {
+        stop()
+        watchedUrl = url
+        fresh = true
+        timer = setTimeout(runProbe, intervalMs)
+    }
+
+    function stop(): void {
+        if (timer) {
+            clearTimeout(timer)
+            timer = undefined
+        }
+        watchedUrl = undefined
+        failures = 0
+        alive = true
+    }
+
+    /* Event-accelerated check (visibility return, online event): probe immediately instead of waiting out the interval. */
+    function probeNow(): void {
+        if (!watchedUrl || inFlight) {
+            return
+        }
+        if (timer) {
+            clearTimeout(timer)
+            timer = undefined
+        }
+        void runProbe()
+    }
+
+    return { watch, stop, probeNow }
+}