@abide/abide 0.58.0 → 0.101.0

package/README.md

@@ -1,249 +0,0 @@
-# abide
-
-**One typed declaration fans out to HTTP, a browser proxy, a CLI, an MCP tool, and an OpenAPI spec — in a single Bun runtime, for humans and machines alike.**
-
-abide is an isomorphic framework where a server RPC is one typed function: the bundler swaps its runtime per side (in-process on the server, `fetch` in the browser) and projects the same declaration onto every other surface. The `.abide` component grammar ties those RPCs, live sockets, and reactive state into one page that server-renders and hydrates.
-
-- One direct dependency (TypeScript); one runtime (Bun ≥ 1.3). Tailwind is an optional peer.
-
-## Quick start
-
-```sh
-bunx abide scaffold my-app   # scaffolds the project, installs deps, starts the dev server
-```
-
-Or run the kitchen-sink example:
-
-```sh
-git clone https://github.com/briancray/abide
-cd abide && bun install
-cd examples/kitchen-sink && bun dev
-```
-
-## RPCs
-
-An RPC is one export per file under `src/server/rpc/` — the file path is the URL. The handler's typed input parameter is the contract: at build it projects to JSON Schema (ADR-0030) that drives the MCP tool, CLI flags, and OpenAPI operation. A Standard Schema (zod / valibot / arktype, unadapted) in `schemas.input` adds runtime validation on top.
-
-```ts
-// src/server/rpc/getMessages.ts
-import { GET } from '@abide/abide/server/GET'
-import { json } from '@abide/abide/server/json'
-import { z } from 'zod'
-import { listMessages } from '../db.ts'
-
-export const getMessages = GET(
-  async ({ limit }: { limit: number }) => json(await listMessages(limit)),
-  { schemas: { input: z.object({ limit: z.number().max(100) }) } },
-)
-```
-
-One declaration, five surfaces:
-
-```text
-                        getMessages  (src/server/rpc/getMessages.ts)
-                              │
-   ┌──────────────┬──────────┼───────────────┬───────────────────┐
-   ▼              ▼          ▼               ▼                   ▼
- SSR call     browser      MCP tool        CLI               OpenAPI op
- (in-proc)    fetch        get_messages    app get-messages   GET /rpc/
- smart read   typed proxy  (read → auto)   --limit 20         getMessages
-```
-
-A **typed input** unlocks the CLI, and for a read-only method (GET/HEAD) the MCP tool, with no hand-written schema — the projected shape is the machine-advertisable contract. A mutating method (POST/PUT/PATCH/DELETE) never auto-exposes to MCP; it needs explicit `clients: { mcp: true }`.
-
-```ts
-// src/server/rpc/sendMessage.ts — a plainly-typed mutation, opted into MCP
-import { POST } from '@abide/abide/server/POST'
-import { json } from '@abide/abide/server/json'
-import { appendMessage } from '../db.ts'
-
-export const sendMessage = POST(
-  async ({ text }: { text: string }) => json(await appendMessage(text)),
-  { clients: { mcp: true } },
-)
-```
-
-Consume it many ways. The **bare call `fn(args)` is the smart read** — cached, coalesced, reactive, isomorphic (in-process during SSR, `fetch` in the browser). Alongside it: `fn.raw(args, init?)` for the raw `Response`, and the probes/mutators `fn.pending()` / `fn.refreshing()` / `fn.error()` / `fn.peek()` / `fn.refresh()` / `fn.invalidate()` / `fn.amend(...)`. A streaming handler (`jsonl`/`sse`) makes the bare call return a `Subscribable`. There is no `cache()` wrapper — the bare call carries the caching.
-
-> Query / path / form args auto-coerce from the endpoint's typed shape (ADR-0028): a numeric / boolean / date field arrives already typed, so no `z.coerce` is needed — a value that won't parse stays a string so the schema raises an honest 422. The per-RPC `timeout` (504, on every surface) is distinct from `ABIDE_CLIENT_TIMEOUT`.
-
-## Sockets
-
-A socket is one broadcast topic per file under `src/server/sockets/`. A `Socket<T>` is an isomorphic `AsyncIterable<T>`; every socket multiplexes onto one WebSocket at `/__abide/sockets`.
-
-```ts
-// src/server/sockets/chat.ts
-import { socket } from '@abide/abide/server/socket'
-import { z } from 'zod'
-
-export const chat = socket({
-  schema: z.object({ id: z.string(), text: z.string() }),
-  tail: 50,        // retain the last 50 frames for late joiners / reconnects
-  ttl: 60_000,     // evict retained frames older than 60s before replay
-})
-```
-
-The HTTP face is `/__abide/sockets/<name>`: `GET` returns the retained tail, `POST` publishes (gated by `clientPublish`).
-
-## Components
-
-A `.abide` component is a single page that server-renders and hydrates. This one imports the RPC and socket above and exercises the whole grammar.
-
-```html
-<script>
-import { getMessages } from '$server/rpc/getMessages.ts'
-import { sendMessage } from '$server/rpc/sendMessage.ts'
-import { chat } from '$server/sockets/chat.ts'
-import Card from '$ui/Card.abide'
-import { state } from '@abide/abide/ui/state'
-import { watch } from '@abide/abide/ui/watch'
-import { html } from '@abide/abide/ui/html'
-import { props } from '@abide/abide/ui/props'
-
-const { room = 'general' } = props()
-
-let draft = state('')
-let limit = state(20)
-let live = state(true)
-let tab = state('feed')
-let unread = state(0)
-
-// state.computed — read-only derived; state.linked — writable, reseeded from a thunk
-let trimmed = state.computed(() => draft.trim())
-let title = state.linked(() => `#${room}`)
-
-// watch — the single reaction primitive (client-only): a cell, then a socket
-watch(trimmed, next => console.debug('draft', next))
-watch(chat, frame => { unread += 1 })
-
-const badge = html`<sup>${unread}</sup>`
-
-async function send() {
-  if (!trimmed) return
-  await sendMessage({ text: draft })   // mutating RPC in an event handler
-  draft = ''
-}
-
-// an attach directive: run against the element, return a teardown
-function autofocus(node: HTMLElement) {
-  node.focus()
-  return () => {}
-}
-
-// the get/set pair for a derived two-way binding
-function get() { return draft.toUpperCase() }
-function set(next: string) { draft = next }
-</script>
-
-<header class="row" class:live={live} style:opacity={live ? 1 : 0.5} {...{ id: 'top' }}>
-  <h1>{title} {badge}</h1>
-  <label><input type="checkbox" bind:checked={live} /> live</label>
-</header>
-
-<!-- bare async read: undefined while pending, composes with ?. and ?? -->
-<p>{getMessages({ limit })?.length ?? 0} loaded</p>
-{#if getMessages.pending()}<span>loading…</span>{/if}
-{#if getMessages.error()}<span role="alert">failed</span>{/if}
-
-<form onsubmit={send}>
-  <input name={room} bind:value={draft} attach={autofocus} />
-  <!-- derived two-way binding: { get, set } -->
-  <input bind:value={{ get, set }} />
-  <button type="submit" disabled={trimmed === ''}>Send</button>
-</form>
-
-<nav>
-  {#for name of ['feed', 'about']}<span>{name}</span>{/for}
-  <label><input type="radio" bind:group={tab} value="feed" /> feed</label>
-  <label><input type="radio" bind:group={tab} value="about" /> about</label>
-</nav>
-
-{#switch tab}
-  {:case 'feed'}
-    <ol>
-      {#for message, i of getMessages({ limit }) ?? [] by message.id}
-        <li style:--i={i}>{message.text}</li>
-      {/for}
-    </ol>
-  {:case 'about'}
-    <p>Room {room}.</p>
-  {:default}
-    <p>—</p>
-{/switch}
-
-<!-- inline await: blocks SSR until the value is in the initial HTML -->
-<p>total: {await getMessages({ limit: 100 })?.length ?? 0}</p>
-
-<!-- {#await} is the opt-in for a distinct pending branch and {:then} narrowing -->
-{#await getMessages({ limit })}
-  <p>loading feed…</p>
-{:then messages}
-  <p>{messages.length} messages</p>
-{:catch failure}
-  <p>{failure instanceof Error ? failure.message : String(failure)}</p>
-{:finally}
-  <hr />
-{/await}
-
-{#if live}
-  <script>
-  // a nested branch <script> — branch-local state, re-seeded per mount, no imports
-  let seen = state(0)
-  let plural = state.computed(() => (seen === 1 ? 'frame' : 'frames'))
-  </script>
-  <style>
-    /* nested <style> scopes to this branch's subtree */
-    p { font-variant-numeric: tabular-nums; }
-  </style>
-  <p>{seen} {plural} this session</p>
-  <ul>
-    {#for await frame of chat}
-      <li>{frame.text}</li>
-    {:catch streamError}
-      <li>{streamError instanceof Error ? streamError.message : String(streamError)}</li>
-    {/for}
-  </ul>
-{:else if unread > 0}
-  <p>{unread} while paused</p>
-{:else}
-  <p>paused</p>
-{/if}
-
-{#try}
-  <Card {...{ tone: 'accent' }} class:wide={live}>
-    <p>{html('<em>trusted</em>')}</p>
-  </Card>
-{:catch renderError}
-  <p>card failed: {renderError instanceof Error ? renderError.message : String(renderError)}</p>
-{:finally}
-  <footer>room {room}</footer>
-{/try}
-
-{#snippet row(message: { id: string; text: string })}
-  <li data-id={message.id}>{message.text}</li>
-{/snippet}
-<ul>{#if getMessages({ limit })}{row({ id: '0', text: 'pinned' })}{/if}</ul>
-
-<style>
-  /* a root <style> is component-scoped */
-  .row { display: flex; gap: 0.5rem; }
-</style>
-```
-
-The child component renders its passed content at `{children()}`, with a fallback:
-
-```html
-<script>
-import { props } from '@abide/abide/ui/props'
-import type { Snippet } from '@abide/abide/shared/snippet'
-const { tone = 'plain', children } = props<{ tone?: string; children?: Snippet }>()
-</script>
-
-<section class:accent={tone === 'accent'}>
-  {#if children}{children()}{:else}<em>empty</em>{/if}
-</section>
-```
-
-Async reads have no ceremony: the bare call in `{getMessages({ limit })}` is the way — a peek that reads `undefined` while pending and auto-streams on SSR, pairing with `.pending()` / `.error()` for affordances. Reach for `{#await}` only when you want an explicit pending branch, a local `{:catch}`, or `{:then}` narrowing.
-
-MIT

package/src/abideLsp.ts

@@ -1,251 +0,0 @@
-import ts from 'typescript'
-import { ABIDE_SEMANTIC_TOKENS_LEGEND } from './lib/ui/compile/ABIDE_SEMANTIC_TOKENS_LEGEND.ts'
-import type {
-    ShadowLanguageService,
-    ShadowQuickInfo,
-} from './lib/ui/compile/createShadowLanguageService.ts'
-import { createShadowLanguageService } from './lib/ui/compile/createShadowLanguageService.ts'
-import { encodeSemanticTokens } from './lib/ui/compile/encodeSemanticTokens.ts'
-import { nearestProjectRoot } from './lib/ui/compile/nearestProjectRoot.ts'
-import { offsetToPosition } from './lib/ui/compile/offsetToPosition.ts'
-import { templateSemanticTokens } from './lib/ui/compile/templateSemanticTokens.ts'
-import type { AbideDiagnostic } from './lib/ui/compile/types/AbideDiagnostic.ts'
-
-/*
-A minimal Language Server for `.abide` files over stdio (JSON-RPC with
-Content-Length framing). It publishes type-check diagnostics — the shadow's
-errors mapped onto the component source — on open/change/save, and answers hover
-requests with TypeScript's quick-info for the expression under the cursor, so an
-editor shows squiggles and signature popovers on template expressions and child
-props. Full-document sync keeps the loop tiny; the shadow LanguageService holds
-unsaved text as overlays. Each document routes to a shadow service for its
-nearest tsconfig, so files in a monorepo opened at its root are checked against
-their own project — matching `abide check` run from that package.
-*/
-/*
-The semantic-tokens `data` array for one component: the HTML markup structure and
-the structural `{#…}` framing — both driven by the ONE parse walk
-(`templateSemanticTokens`) — merged with the shadow's type-aware expression tokens,
-encoded to the LSP wire format. The markup tokens make the LSP own the
-element/attribute coloring too, so a tree-sitter parse desynced by an `attr={expr}`
-value can't bleed miscoloring below it. Never throws — on any internal failure it
-yields an empty stream so the editor falls back to tree-sitter highlighting.
-*/
-export function componentSemanticTokens(
-    service: ShadowLanguageService,
-    abidePath: string,
-    text: string,
-): number[] {
-    try {
-        const tokens = [
-            ...templateSemanticTokens(text),
-            ...service.semanticClassifications(abidePath),
-        ]
-        return encodeSemanticTokens(text, tokens)
-    } catch {
-        return []
-    }
-}
-
-export async function abideLsp({ cwd }: { cwd: string }): Promise<void> {
-    const documentText = new Map<string, string>()
-
-    /* A shadow service per project root, created on first use. A document's
-       diagnostics/hover come from the service for its nearest tsconfig. */
-    const services = new Map<string, ShadowLanguageService>()
-    const serviceFor = (path: string): ShadowLanguageService => {
-        const root = nearestProjectRoot(path, cwd)
-        const existing = services.get(root)
-        if (existing !== undefined) {
-            return existing
-        }
-        const created = createShadowLanguageService(root)
-        services.set(root, created)
-        return created
-    }
-
-    const send = (message: object): void => {
-        const body = JSON.stringify(message)
-        process.stdout.write(`Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`)
-    }
-
-    const publish = (path: string): void => {
-        const text = documentText.get(path) ?? ''
-        send({
-            jsonrpc: '2.0',
-            method: 'textDocument/publishDiagnostics',
-            params: {
-                uri: Bun.pathToFileURL(path).href,
-                diagnostics: serviceFor(path)
-                    .diagnostics(path)
-                    .map((diagnostic) => toLspDiagnostic(text, diagnostic)),
-            },
-        })
-    }
-
-    const isAbide = (uri: string): boolean => uri.endsWith('.abide')
-
-    const handle = (message: LspMessage): void => {
-        switch (message.method) {
-            case 'initialize':
-                send({
-                    jsonrpc: '2.0',
-                    id: message.id,
-                    result: {
-                        capabilities: {
-                            textDocumentSync: 1,
-                            hoverProvider: true,
-                            semanticTokensProvider: {
-                                legend: ABIDE_SEMANTIC_TOKENS_LEGEND,
-                                full: true,
-                            },
-                        },
-                        serverInfo: { name: 'abide-lsp' },
-                    },
-                })
-                return
-            case 'textDocument/didOpen': {
-                const { uri, text } = message.params.textDocument
-                if (isAbide(uri)) {
-                    const path = Bun.fileURLToPath(uri)
-                    documentText.set(path, text)
-                    serviceFor(path).update(path, text)
-                    publish(path)
-                }
-                return
-            }
-            case 'textDocument/didChange': {
-                const { uri } = message.params.textDocument
-                if (isAbide(uri)) {
-                    const path = Bun.fileURLToPath(uri)
-                    const text = message.params.contentChanges.at(-1)?.text ?? ''
-                    documentText.set(path, text)
-                    serviceFor(path).update(path, text)
-                    publish(path)
-                }
-                return
-            }
-            case 'textDocument/didSave': {
-                const { uri } = message.params.textDocument
-                if (isAbide(uri)) {
-                    publish(Bun.fileURLToPath(uri))
-                }
-                return
-            }
-            case 'textDocument/hover': {
-                /* A request: always answer (null when there's nothing to show) so
-                   the editor isn't left waiting. */
-                const { uri } = message.params.textDocument
-                const text = isAbide(uri) ? (documentText.get(Bun.fileURLToPath(uri)) ?? '') : ''
-                const info = isAbide(uri)
-                    ? serviceFor(Bun.fileURLToPath(uri)).quickInfo(
-                          Bun.fileURLToPath(uri),
-                          positionToOffset(text, message.params.position),
-                      )
-                    : undefined
-                send({
-                    jsonrpc: '2.0',
-                    id: message.id,
-                    result: info === undefined ? null : toLspHover(text, info),
-                })
-                return
-            }
-            case 'textDocument/semanticTokens/full': {
-                const { uri } = message.params.textDocument
-                const data = isAbide(uri)
-                    ? componentSemanticTokens(
-                          serviceFor(Bun.fileURLToPath(uri)),
-                          Bun.fileURLToPath(uri),
-                          documentText.get(Bun.fileURLToPath(uri)) ?? '',
-                      )
-                    : []
-                send({ jsonrpc: '2.0', id: message.id, result: { data } })
-                return
-            }
-            case 'textDocument/didClose': {
-                const { uri } = message.params.textDocument
-                if (isAbide(uri)) {
-                    const path = Bun.fileURLToPath(uri)
-                    serviceFor(path).close(path)
-                    documentText.delete(path)
-                    send({
-                        jsonrpc: '2.0',
-                        method: 'textDocument/publishDiagnostics',
-                        params: { uri, diagnostics: [] },
-                    })
-                }
-                return
-            }
-            case 'shutdown':
-                send({ jsonrpc: '2.0', id: message.id, result: null })
-                return
-            case 'exit':
-                process.exit(0)
-        }
-    }
-
-    /* Pull complete `Content-Length`-framed messages out of the byte stream. */
-    let buffer = Buffer.alloc(0)
-    for await (const chunk of process.stdin) {
-        buffer = Buffer.concat([buffer, chunk as Buffer])
-        while (true) {
-            const headerEnd = buffer.indexOf('\r\n\r\n')
-            if (headerEnd === -1) {
-                break
-            }
-            const header = buffer.toString('utf8', 0, headerEnd)
-            const length = Number(header.match(/Content-Length: (\d+)/i)?.[1])
-            const bodyStart = headerEnd + 4
-            if (!Number.isFinite(length) || buffer.length < bodyStart + length) {
-                break
-            }
-            const body = buffer.toString('utf8', bodyStart, bodyStart + length)
-            buffer = buffer.subarray(bodyStart + length)
-            handle(JSON.parse(body))
-        }
-    }
-}
-
-/* The LSP requests this server reads; loosely typed since it only branches on
-   `method` and reads a few known fields. */
-type LspMessage = {
-    id?: number | string
-    method: string
-    params?: any
-}
-
-/* Converts a mapped abide diagnostic to an LSP diagnostic over the document text. */
-function toLspDiagnostic(text: string, diagnostic: AbideDiagnostic): object {
-    return {
-        range: {
-            start: offsetToPosition(text, diagnostic.start),
-            end: offsetToPosition(text, diagnostic.start + diagnostic.length),
-        },
-        severity: diagnostic.category === ts.DiagnosticCategory.Error ? 1 : 2,
-        source: 'abide',
-        message: diagnostic.message,
-    }
-}
-
-/* Renders mapped quick-info as an LSP hover: TypeScript's signature in a fenced
-   `ts` block, the doc comment (if any) below, over the covered source range. */
-function toLspHover(text: string, info: ShadowQuickInfo): object {
-    const fence = ['```ts', info.text, '```'].join('\n')
-    const value = info.documentation.length > 0 ? `${fence}\n\n${info.documentation}` : fence
-    return {
-        contents: { kind: 'markdown', value },
-        range: {
-            start: offsetToPosition(text, info.start),
-            end: offsetToPosition(text, info.start + info.length),
-        },
-    }
-}
-
-/* An LSP `{ line, character }` (0-based) → absolute offset in `text`. */
-function positionToOffset(text: string, position: { line: number; character: number }): number {
-    const lineStart = text
-        .split('\n')
-        .slice(0, position.line)
-        .reduce((sum, line) => sum + line.length + 1, 0)
-    return lineStart + position.character
-}

package/src/abideModules.d.ts

@@ -1,8 +0,0 @@
-/* Ambient type for `.abide` single-file component imports: the default export is a
-   compiled abide-ui component (client mounter + SSR render + hydration hooks). */
-declare module '*.abide' {
-    import type { UiComponent } from './lib/ui/runtime/types/UiComponent.ts'
-
-    const component: UiComponent
-    export default component
-}