@abide/abide 0.58.0 → 0.101.0

package/src/lib/server/cookies.ts

@@ -1,30 +0,0 @@
-import { requestContext } from './runtime/requestContext.ts'
-
-/*
-The cookie jar for the in-flight request. Reads parse the inbound `Cookie`
-header; writes (`set` / `delete`) are collected and flushed to the response as
-`Set-Cookie` headers when the handler returns (see runWithRequestScope). Backed
-by Bun's native `CookieMap`, so it's a live `Map<string, string>` plus
-`.set(name, value, options)` carrying the standard attributes (httpOnly, secure,
-sameSite, maxAge, path, …) and `.delete(name)` for expiry:
-
-  const jar = cookies()
-  const session = jar.get('session')                       // read inbound
-  jar.set('session', token, { httpOnly: true, sameSite: 'lax' })
-  jar.delete('session')                                     // expire on the way out
-
-Materialized lazily on first call and cached on the request store, so a request
-that never touches cookies parses nothing and emits no `Set-Cookie`. Throws
-outside a request scope, like request().
-*/
-// @documentation request-scope
-export function cookies(): Bun.CookieMap {
-    const store = requestContext.getStore()
-    if (!store) {
-        throw new Error(
-            '[abide] cookies() called outside a request scope — it only resolves while an SSR render or rpc handler is in flight',
-        )
-    }
-    store.cookies ??= new Bun.CookieMap(store.req.headers.get('cookie') ?? '')
-    return store.cookies
-}

package/src/lib/server/env.ts

@@ -1,51 +0,0 @@
-import type { StandardSchemaV1 } from '../shared/types/StandardSchemaV1.ts'
-import { envSchemaStore } from './runtime/envSchemaStore.ts'
-
-/*
-Validates the process environment against a Standard Schema and returns the
-typed, parsed config. Built to be called at module top level so a missing or
-malformed variable fails the boot loudly rather than surfacing as `undefined`
-deep inside a handler:
-
-  // src/server/config.ts
-  export const config = env(
-      v.object({ DATABASE_URL: v.string(), STRIPE_KEY: v.string() }),
-  )
-
-Reads `Bun.env` (the process environment plus any `.env` Bun loaded), so any
-Standard Schema library — zod, valibot, arktype — works without an adapter,
-same as the rpc helpers. Coercion (e.g. a numeric PORT) lives in the schema.
-
-The schema is registered (envSchemaStore) so the bundle launcher can project
-the first-run setup form from the same declaration. When the launcher imports
-this purely to read that schema it sets `skipValidation`, so env() registers
-and returns without validating Bun.env — boot validation stays the server's.
-
-Validation must be synchronous — boot can't await config — so a schema whose
-`validate` returns a Promise throws. On failure every issue is reported at once
-(path + message) so a misconfigured deploy shows the full list rather than one
-variable per restart.
-*/
-// @documentation configuration
-export function env<Schema extends StandardSchemaV1>(
-    schema: Schema,
-): StandardSchemaV1.InferOutput<Schema> {
-    envSchemaStore.schema = schema
-    if (envSchemaStore.skipValidation) {
-        return Bun.env as unknown as StandardSchemaV1.InferOutput<Schema>
-    }
-    const result = schema['~standard'].validate(Bun.env)
-    if (result instanceof Promise) {
-        throw new Error('[abide] env() schema must validate synchronously')
-    }
-    if (result.issues) {
-        const lines = result.issues.map((issue) => {
-            const path = issue.path
-                ?.map((segment) => String(typeof segment === 'object' ? segment.key : segment))
-                .join('.')
-            return path ? `  ${path}: ${issue.message}` : `  ${issue.message}`
-        })
-        throw new Error(`[abide] invalid environment:\n${lines.join('\n')}`)
-    }
-    return result.value
-}

package/src/lib/server/error.ts

@@ -1,110 +0,0 @@
-import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
-import { TEXT_PLAIN } from '../shared/TEXT_PLAIN.ts'
-import type { StandardSchemaV1 } from '../shared/types/StandardSchemaV1.ts'
-import type { TypedError } from './rpc/types/TypedError.ts'
-import type { TypedResponse } from './rpc/types/TypedResponse.ts'
-import { STATUS_TEXT } from './runtime/STATUS_TEXT.ts'
-import { typedErrorResponse } from './runtime/typedErrorResponse.ts'
-import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
-
-/*
-Plain-text error Response — clearer than constructing a Response by
-hand with a status and a text body, and shaped so the client's
-HttpError carries the message verbatim (`HttpError.response.text()`
-returns the message, no parsing).
-
-  if (!order) return error(404, 'order not found')
-
-`message` defaults to the status's standard reason phrase when
-omitted (e.g. `error(404)` body = 'Not Found'). The body is
-text/plain so intermediaries don't try to render or sniff it. A final
-`ResponseInit` adds headers (e.g. `Retry-After` on a 429); the positional
-`status` always wins over any `init.status`.
-
-For a NAMED, typed error the client can branch on, declare a constructor with
-`error.typed(name, status, schema?)` and return it (see below). To short-circuit
-a handler instead of returning, `throw new Error(...)` or
-`throw new HttpError(error(...))` — the framework's `app.handleError` hook
-catches thrown errors. This helper deliberately returns a Response rather than
-throwing one so a single `return error(...)` is the expected pattern, with the
-same control flow as `return json(...)`.
-*/
-
-/*
-Body type is `never` because `error()` only travels the non-2xx path on
-the wire — the caller's `await fn(args)` throws `HttpError` and never
-resolves to this response's body. Returning a TypedResponse<never> lets
-the union of branches in a handler narrow to whatever the success
-branch carries (`TypedResponse<{user}> | TypedResponse<never>` → Return
-= {user}).
-*/
-function errorResponse(
-    status: number,
-    message?: string,
-    init?: ResponseInit,
-): TypedResponse<never> {
-    const body = message ?? STATUS_TEXT[status] ?? `HTTP ${status}`
-    return new Response(
-        body,
-        withStatusText(
-            withResponseDefaults(
-                init,
-                {
-                    'Content-Type': TEXT_PLAIN,
-                    'Cache-Control': NO_STORE,
-                },
-                status,
-            ),
-            status,
-        ),
-    ) as TypedResponse<never>
-}
-
-/*
-Stamps the status's standard reason phrase onto `init.statusText` so the wire
-status line reads `404 Not Found` and the client's `HttpError.statusText` is
-populated — Bun's `Response` never derives statusText from the code. A caller's
-explicit `init.statusText` (preserved through withResponseDefaults) still wins;
-an unlisted code leaves it untouched.
-*/
-function withStatusText(init: ResponseInit, status: number): ResponseInit {
-    if (init.statusText === undefined && STATUS_TEXT[status] !== undefined) {
-        return { ...init, statusText: STATUS_TEXT[status] }
-    }
-    return init
-}
-
-/*
-Declares a reusable, typed error as a single constructor. With a `data` schema
-the constructor requires that input; without one it's nullary. Returning the
-constructor from a handler IS the error — it serializes a `{ $abideError, data }`
-body at `status`, and the rpc reads the constructor's branded return type to
-expose the error on `rpc.isError(e, 'name')` (`.kind` and typed `.data`). No
-`errors:` option, no set to register — compose by returning whichever you want:
-
-  const duplicateSlug = error.typed('duplicateSlug', 409, z.object({ slug: z.string() }))
-  const rateLimited = error.typed('rateLimited', 429)               // nullary
-
-  export const createPost = POST(({ slug }) =>
-      taken(slug) ? duplicateSlug({ slug }) : json(save(slug)),
-  )
-
-`name` is the wire identity and the `isError` key, so it's an explicit string
-(a const can't read its own variable name); `schema` types `.data` and is never
-validated at runtime here.
-*/
-function typed<Name extends string, Status extends number, Schema extends StandardSchemaV1>(
-    name: Name,
-    status: Status,
-    schema: Schema,
-): (data: StandardSchemaV1.InferInput<Schema>) => TypedError<Name, { status: Status; data: Schema }>
-function typed<Name extends string, Status extends number>(
-    name: Name,
-    status: Status,
-): () => TypedError<Name, { status: Status; data?: undefined }>
-function typed(name: string, status: number, _schema?: StandardSchemaV1) {
-    return (data?: unknown) => typedErrorResponse(name, status, data)
-}
-
-// @documentation response
-export const error = Object.assign(errorResponse, { typed })

package/src/lib/server/json.ts

@@ -1,57 +0,0 @@
-import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
-import { encodeWireBody } from '../shared/encodeWireBody.ts'
-import type { TypedResponse } from './rpc/types/TypedResponse.ts'
-import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
-
-/* The Content-Type `Response.json` sets — replicated here because the wire-encode step serializes
-   with a replacer, so the body is built by hand rather than through `Response.json`. Seeds the
-   default header set so an explicit caller `content-type` still wins. */
-const JSON_CONTENT_TYPE = 'application/json;charset=utf-8'
-
-/*
-JSON Response with rpc-friendly defaults — same shape as
-`Response.json(data, init)`, except `Cache-Control: no-store` is set
-unless the caller overrides it. Intermediary caches (browsers, CDNs,
-shared proxies) shouldn't cache rpc replies by default; the framework's
-own per-request cache handles in-process dedupe.
-
-  export const getOrder = GET(async ({ id }: { id: string }) =>
-      json(await db.getOrder(id)),
-  )
-
-The return type carries `T` as a phantom brand so the rpc helper can
-infer the caller-facing `Return` from the handler body — you type the
-handler's parameter and let the body infer; there are no `<Args, Return>`
-call generics (a stray one is a compile error).
-
-For non-default cache policy pass `init.headers`; explicit
-`cache-control` wins over the default.
-
-JSON has no encoding for `undefined` — `Response.json(undefined)` throws
-TypeError. `json(undefined)` instead emits 204 No Content, which
-decodeResponse maps back to `undefined` on both the fetch and in-process
-paths, so a handler typed `Shape | undefined` round-trips the wire. The
-helper owns the 204 (a body-bearing status with no body would break the
-round trip), so it wins over any `init.status`.
-*/
-// @documentation response
-export function json<T>(data: T, init?: ResponseInit): TypedResponse<T> {
-    if (data === undefined) {
-        return new Response(
-            undefined,
-            withResponseDefaults(init, { 'Cache-Control': NO_STORE }, 204),
-        ) as TypedResponse<T>
-    }
-    /* Wire-encode the body (ADR-0029 output path) through the shared honest-JSON encoder: a
-       value-directed replacer rewrites a `Set` → array, a `Map` → `[K,V]` entries, and a `bigint`
-       → digit string, so a structured return crosses as honest JSON rather than a lost `{}` or a
-       500 (plain `Response.json` throws on a bigint). A `Date` already rides as an ISO string via
-       its native `toJSON`. */
-    return new Response(
-        encodeWireBody(data),
-        withResponseDefaults(init, {
-            'Cache-Control': NO_STORE,
-            'Content-Type': JSON_CONTENT_TYPE,
-        }),
-    ) as TypedResponse<T>
-}

package/src/lib/server/jsonl.ts

@@ -1,47 +0,0 @@
-/*
-Wraps an AsyncIterable<Frame> in a Response whose body is JSON Lines
-(application/jsonl) — one JSON value per line, terminated by `\n`. Used
-inside an rpc handler to turn a generator into a streaming HTTP response
-that `tail(fn.stream(args))` consumes frame-by-frame on the client.
-
-  export const orderFeed = GET((args: Args) =>
-      jsonl(async function* () {
-          for await (const order of db.watchOrders(args)) yield order
-      }())
-  )
-
-Cancellation flows from the consumer through ReadableStream's `cancel`
-into `iter.return()` so the handler's `for await` exits via its normal
-control path (DB cursors, file handles, etc. get to release in finally).
-
-Errors thrown by the generator are emitted as a final
-`{"$error":"<message>"}` line before the stream closes. The convention
-keeps the format JSON-safe and lets the consumer distinguish "stream
-ended cleanly" from "handler threw" without a side-channel. The full
-error is logged server-side via the framework's error handler — only the
-message crosses the wire.
-*/
-import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
-import { jsonlErrorFrame } from '../shared/jsonlErrorFrame.ts'
-import type { TypedResponse } from './rpc/types/TypedResponse.ts'
-import { streamFromIterator } from './runtime/streamFromIterator.ts'
-import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
-
-// @documentation response
-export function jsonl<Frame>(
-    iterable: AsyncIterable<Frame>,
-    init?: ResponseInit,
-): TypedResponse<AsyncIterable<Frame>> {
-    const body = streamFromIterator(iterable, {
-        encodeFrame: (value) => `${JSON.stringify(value)}\n`,
-        encodeError: (message) => jsonlErrorFrame.encode(message),
-    })
-    return new Response(
-        body,
-        withResponseDefaults(init, {
-            'Content-Type': 'application/jsonl; charset=utf-8',
-            'Cache-Control': NO_STORE,
-            'X-Content-Type-Options': 'nosniff',
-        }),
-    ) as TypedResponse<AsyncIterable<Frame>>
-}

package/src/lib/server/prompts/definePrompt.ts

@@ -1,21 +0,0 @@
-import { registerPrompt } from './registerPrompt.ts'
-import type { Prompt } from './types/Prompt.ts'
-import type { PromptOptions } from './types/PromptOptions.ts'
-
-/*
-Builds a Prompt from a name + options. The resolver plugin parses every
-`src/mcp/prompts/<file>.md` and generates a module that calls
-`definePrompt("<name>", { description, jsonSchema, render })`, so the file
-path becomes the prompt's identity. Registers itself so the MCP dispatcher
-can enumerate and render it.
-*/
-// @documentation plumbing
-export function definePrompt(name: string, opts: PromptOptions): Prompt {
-    const self: Prompt = {
-        name,
-        description: opts.description,
-        render: opts.render,
-    }
-    registerPrompt({ prompt: self, jsonSchema: opts.jsonSchema })
-    return self
-}

package/src/lib/server/prompts/promptRegistry.ts

@@ -1,9 +0,0 @@
-import type { PromptRegistryEntry } from './types/PromptRegistryEntry.ts'
-
-/*
-Process-wide registry of every prompt declared in the app. definePrompt
-inserts on first construction (eagerly when the registry loader walks the
-prompts manifest on first enumeration request). The MCP server reads this to build its
-`prompts/list` + `prompts/get` responses.
-*/
-export const promptRegistry = new Map<string, PromptRegistryEntry>()

package/src/lib/server/prompts/registerPrompt.ts

@@ -1,6 +0,0 @@
-import { promptRegistry } from './promptRegistry.ts'
-import type { PromptRegistryEntry } from './types/PromptRegistryEntry.ts'
-
-export function registerPrompt(entry: PromptRegistryEntry): void {
-    promptRegistry.set(entry.prompt.name, entry)
-}

package/src/lib/server/prompts/renderPromptTemplate.ts

@@ -1,17 +0,0 @@
-// `{{name}}` placeholder, surrounding whitespace tolerated, names are
-// word chars or hyphens to match valid MCP argument identifiers.
-const PLACEHOLDER = /\{\{\s*([\w-]+)\s*\}\}/g
-
-/*
-Renders a markdown prompt body by substituting each `{{name}}` placeholder
-with the matching argument value. Missing arguments collapse to an empty
-string — MCP only enforces `required` at the client, so an optional
-argument the model omits should vanish from the text. Called by the
-render closure the resolver plugin generates for every `.md` prompt.
-*/
-// @documentation plumbing
-export function renderPromptTemplate(template: string, args: Record<string, string>): string {
-    return template.replace(PLACEHOLDER, (_match, key: string) =>
-        args[key] === undefined ? '' : String(args[key]),
-    )
-}

package/src/lib/server/prompts/types/Prompt.ts

@@ -1,14 +0,0 @@
-/*
-An MCP prompt declared by a markdown file under `src/mcp/prompts/`. The
-resolver plugin parses the file's frontmatter + body and generates a call
-to definePrompt, stamping in the `name` from the file path; `render(args)`
-interpolates the body's `{{name}}` placeholders and returns the rendered
-string; `renderPrompt` in mcpSurface.ts then wraps it as the single user
-message returned by `prompts/get`. Prompts are MCP-only — there is no
-client-side counterpart, so the shape carries no ClientFlags.
-*/
-export type Prompt = {
-    readonly name: string
-    readonly description: string | undefined
-    render(args: Record<string, string>): string
-}

package/src/lib/server/prompts/types/PromptOptions.ts

@@ -1,12 +0,0 @@
-/*
-Options definePrompt receives for one markdown prompt. The resolver plugin
-generates this object from the file: `description` + `jsonSchema` come from
-the frontmatter (the schema built from the `arguments` list), and `render`
-closes over the parsed body. All of this is server-only — prompts are never
-imported by client code.
-*/
-export type PromptOptions = {
-    description?: string
-    jsonSchema?: Record<string, unknown>
-    render: (args: Record<string, string>) => string
-}

package/src/lib/server/prompts/types/PromptRegistryEntry.ts

@@ -1,13 +0,0 @@
-import type { Prompt } from './Prompt.ts'
-
-/*
-Per-prompt registry record. The MCP dispatcher enumerates this to build
-`prompts/list` (description + arguments from the JSON Schema) and to
-dispatch `prompts/get` (render the body with the caller's arguments).
-jsonSchema stays off the public Prompt shape so the render closure isn't
-burdened with metadata it never reads.
-*/
-export type PromptRegistryEntry = {
-    prompt: Prompt
-    jsonSchema: Record<string, unknown> | undefined
-}

package/src/lib/server/prompts/types/PromptRoutes.ts

@@ -1,10 +0,0 @@
-import type { Prompt } from './Prompt.ts'
-
-/*
-Manifest of prompt-name → module loader. Produced by the resolver plugin
-from each `.md` under src/mcp/prompts/. Each markdown file is transformed
-into a module that registers one Prompt (its `.name` stamped in by the
-generated definePrompt call) on import. The registry loader imports every
-module once so the MCP dispatcher can enumerate the full prompt surface.
-*/
-export type PromptRoutes = Record<string, () => Promise<Record<string, Prompt>>>

package/src/lib/server/redirect.ts

@@ -1,43 +0,0 @@
-/*
-Redirect Response with abide-friendly ergonomics — accepts relative
-URLs (the platform's `Response.redirect` throws on them), defaults to
-302, and matches the helper-style call site of `json`/`error` for
-visual consistency inside a handler.
-
-  return redirect('/login')              // 302 to /login
-  return redirect('/articles/1', 301)    // permanent
-  return redirect(externalUrl, 307)      // preserve method (POST stays POST)
-
-Status guidance:
-- 301 — moved permanently (cacheable; browsers may swap method to GET)
-- 302 — found / temporary (default; browsers may swap method to GET)
-- 303 — "after a POST, GET this" (forces GET on the follow-up)
-- 307 — temporary, preserve method
-- 308 — permanent, preserve method
-
-A final `ResponseInit` adds headers (e.g. a `Set-Cookie` on the redirect);
-the positional `status` always wins over any `init.status`.
-*/
-import { NO_STORE } from '../shared/CACHE_CONTROL_VALUES.ts'
-import type { TypedResponse } from './rpc/types/TypedResponse.ts'
-import { withResponseDefaults } from './runtime/withResponseDefaults.ts'
-
-type RedirectStatus = 301 | 302 | 303 | 307 | 308
-
-/*
-Return type is `TypedResponse<never>` for the same reason `error()` is —
-the wire response is a 3xx with no body the caller resolves to, so it
-must not pollute the inferred `Return` of a route that conditionally
-redirects vs returns json.
-*/
-// @documentation response
-export function redirect(
-    url: string,
-    status: RedirectStatus = 302,
-    init?: ResponseInit,
-): TypedResponse<never> {
-    return new Response(
-        null,
-        withResponseDefaults(init, { Location: url, 'Cache-Control': NO_STORE }, status),
-    ) as TypedResponse<never>
-}

package/src/lib/server/render.ts

@@ -1,70 +0,0 @@
-import { basePath } from '../shared/basePath.ts'
-import { forwardHeaders } from '../shared/forwardHeaders.ts'
-import type { PageRoutes, PathParams } from '../shared/url.ts'
-import { url } from '../shared/url.ts'
-import { getActiveServer } from './runtime/getActiveServer.ts'
-import { pageRenderSlot } from './runtime/pageRenderSlot.ts'
-import { requestContext } from './runtime/requestContext.ts'
-
-/* Query args carried onto the rendered URL — the same shape url() appends. */
-type Query = Record<string, string | number | boolean | undefined>
-
-/*
-Renders a page route to its HTML string, server-side, from anywhere in a request
-scope — the same pipeline (app.html shell, layout chain, params, inline rpc
-reads) an HTTP GET of that URL would run, so the page stays directly linkable and
-its emailed form is one call away. Argument shape mirrors url()/navigate: a route
-literal with `[name]` segments takes its params first (`render('/emails/[id]',
-{ id })`), then optional query; a paramless route takes optional query directly.
-
-The page renders in a fresh nested request scope (like an in-process rpc call), so
-its own `cache()`/rpc reads resolve exactly as under a live request; app.handle
-middleware and gzip are not applied. A page whose content is baked inline —
-top-level `await` or a blocking `{#await expr then value}` — returns complete,
-self-contained HTML. A page with streaming `{#await}` blocks returns the shell
-plus trailing `<abide-resolve>` fragments a browser reassembles client-side, so
-for a no-JS surface (email) use blocking awaits.
-*/
-// @documentation render
-export function render<P extends keyof PageRoutes | (string & {})>(
-    path: P,
-    ...args: keyof PathParams<P> extends never
-        ? [query?: Query]
-        : [params: PathParams<P>, query?: Query]
-): Promise<string>
-export async function render(path: string, first?: Query, second?: Query): Promise<string> {
-    const dispatch = pageRenderSlot.render
-    if (!dispatch) {
-        throw new Error(
-            '[abide] render() called before init — make sure your call happens inside or after app.ts init() resolves',
-        )
-    }
-    /* url() discriminates params-vs-query off the path's own segments at runtime;
-       cast past its typed overload since `path` is a plain string here. */
-    const resolved = (url as (path: string, first?: Query, second?: Query) => string)(
-        path,
-        first,
-        second,
-    )
-    /* url() prefixes the mount base for browser-facing links; strip it back off so
-       the pathname matches the base-less page route keys the resolver matches on. */
-    const base = basePath()
-    const routePath =
-        base && resolved.startsWith(base) ? resolved.slice(base.length) || '/' : resolved
-    /* Origin only shapes absolute-URL generation inside the page; the live server's
-       own origin when booted, a stable localhost otherwise. */
-    const origin = getActiveServer()?.url.origin ?? 'http://localhost'
-    const requestUrl = new URL(routePath, origin)
-    /* Called inside a request scope, inherit the caller's auth/identity context —
-       the same allowlisted cookies/authorization/trace/forwarded headers defineRpc
-       threads onto an in-process rpc, cached per scope. Outside a scope (a cron/CLI
-       render) the page renders with no forwarded headers. */
-    const store = requestContext.getStore()
-    let headers: Headers | undefined
-    if (store) {
-        store.forwardedHeaders ??= forwardHeaders(store.req.headers)
-        headers = store.forwardedHeaders
-    }
-    const response = await dispatch(new Request(requestUrl, { headers }), requestUrl)
-    return response.text()
-}

package/src/lib/server/request.ts

@@ -1,19 +0,0 @@
-import { requestContext } from './runtime/requestContext.ts'
-
-/*
-Returns the inbound Request for the current SSR/RPC pass. Implemented as an
-AsyncLocalStorage lookup over the per-request store the server installs at
-the fetch boundary. Throws if called outside a request scope (e.g. from
-top-level module code or from app.ts init) — silent undefined would mask
-the misuse.
-*/
-// @documentation request-scope
-export function request(): Request {
-    const store = requestContext.getStore()
-    if (!store) {
-        throw new Error(
-            '[abide] request() called outside a request scope — it only resolves while an SSR render or rpc handler is in flight',
-        )
-    }
-    return store.req
-}