@abide/abide 0.28.0

package/template/src/app.ts

@@ -0,0 +1,28 @@
+/*
+Optional application hooks. Every export is optional; delete the ones you
+don't need. Abide resolves this file at build time via the abide:app virtual
+module — no import is needed from your own code.
+
+  forwardHeaders extra inbound header names forwarded onto in-process rpc
+                 Requests (SSR / MCP), on top of abide's cookie/authorization/
+                 traceparent/tracestate/x-forwarded-* allowlist
+  init           runs once after Bun.serve is up; return a cleanup for SIGINT/SIGTERM
+  handle         middleware wrapping the default request pipeline
+  handleError    custom 500 fallback
+  health         app fields merged into the /__abide/health payload the
+                 client health() polls — public, never put secrets in it
+*/
+import type { AppModule } from '@abide/abide/server/AppModule'
+
+export const init: AppModule['init'] = () => {
+    // one-time setup; optionally return a cleanup to run on SIGINT/SIGTERM
+}
+
+export const handle: AppModule['handle'] = async (request, next) => {
+    return next(request)
+}
+
+export const handleError: AppModule['handleError'] = (error) => {
+    console.error(error)
+    return new Response('something went wrong', { status: 500 })
+}

package/template/src/cli/banner.txt

@@ -0,0 +1,3 @@
+┌───────────────┐
+│   abide app   │
+└───────────────┘

package/template/src/cli/footer.txt

@@ -0,0 +1 @@
+Run `<command> --help` for command-specific flags.

package/template/src/server/config.ts

@@ -0,0 +1,17 @@
+/*
+Typed environment. `env(schema)` validates Bun.env against a Standard Schema at
+boot — a missing or malformed variable fails the boot with every issue listed,
+instead of surfacing as `undefined` inside a handler. Import `config` from
+`$server/config` anywhere server-side; it's typed from the schema.
+
+Abide eager-imports this file at boot (the abide:config virtual) — no import is
+needed from your own code. The floor below re-exports Bun.env untyped; swap it
+for a schema once you have required variables:
+
+  import { env } from '@abide/abide/server/env'
+  import { z } from 'zod'
+  export const config = env(z.object({ DATABASE_URL: z.string() }))
+
+Optional — delete this file to read Bun.env directly instead.
+*/
+export const config = Bun.env

package/template/src/server/rpc/getHello.ts

@@ -0,0 +1,36 @@
+/*
+RPC module — every file under src/server/rpc/ exposes exactly one verb-bound remote
+function. The filename is the export name and the URL path (under `/rpc/`),
+and the imported verb (GET / POST / PUT / PATCH / DELETE / HEAD) picks the
+HTTP method. The bundler swaps the runtime per build target: direct call on
+the server, fetch over the network on the client.
+
+Args (what the caller passes in) come from the handler's parameter type —
+either an inline annotation or an explicit `GET<{ id: string }>(...)`
+generic. Return (what the caller receives after Content-Type-driven
+decoding) is inferred from the handler's return type via the
+`TypedResponse<T>` brand on `json`/`error`/`redirect`/`jsonl`/`sse`, so
+plain `GET(() => json({...}))` already types end-to-end.
+
+For inbound validation pass a Standard Schema as `inputSchema` in the
+second argument: `GET(fn, { inputSchema })`. Args then infers from the
+schema's output type and the server replies with 422 on validation
+failure. An optional `outputSchema` describes the success body for the
+OpenAPI 200 response and the MCP tool output.
+
+`json(...)` from `abide/server/json` is a thin wrapper over `Response.json`
+that defaults `Cache-Control: no-store`, since intermediary caches shouldn't
+memoise rpc replies (the framework's per-request cache handles in-process
+dedupe). Other helpers are siblings, one per file: `abide/server/error`,
+`abide/server/redirect`, `abide/server/sse`, `abide/server/jsonl`.
+
+Every rpc value also exposes `.raw(args?)` (returns the underlying
+`Response`) and `.stream(args?)` (returns a `Subscribable` over the frames —
+feed it to `tail()`) for callers that need headers/status or want to iterate
+jsonl/sse frames.
+*/
+
+import { GET } from '@abide/abide/server/GET'
+import { json } from '@abide/abide/server/json'
+
+export const getHello = GET(() => json({ message: 'Hello from abide' }))

package/template/src/ui/Layout.abide

@@ -0,0 +1,19 @@
+<script>
+/*
+Userland root layout. abide has no framework layout resolution — a layout is just
+a component a page wraps its body in (<Layout>…</Layout>), and the body lands in
+the <slot>. Import and wrap this from each page.abide to share chrome. Runs on the
+server during SSR and on the client after hydration.
+*/
+import './app.css'
+</script>
+
+<header>
+    <nav>
+        <a href="/">Home</a>
+        <a href="/about">About</a>
+    </nav>
+</header>
+<main>
+    <slot></slot>
+</main>

package/template/src/ui/app.css

@@ -0,0 +1,21 @@
+/*
+Global stylesheet. Imported once from src/ui/Layout.abide so it ships
+with every page that wraps it. To enable Tailwind v4, add `bun-plugin-tailwind` and
+`tailwindcss` as devDependencies and replace this file with:
+
+    @import "tailwindcss";
+*/
+
+:root {
+    font-family: system-ui, sans-serif;
+    color: #1f2937;
+    background: #f8fafc;
+}
+
+body {
+    margin: 0;
+}
+
+a {
+    color: inherit;
+}

package/template/src/ui/app.html

@@ -0,0 +1,24 @@
+<!--
+Optional HTML shell. If present at src/ui/app.html, abide uses this as the SSR
+template; otherwise an identical default shell is used. abide has no component
+<head>, so static tags like <title> live here. abide injects its client entry
+(the /_app/client.css <link> and /_app/client.js <script>) automatically, so the
+shell only needs page structure and the three markers, replaced at render time:
+  ssr:head     abide's hydration bootstrap
+  ssr:body     rendered page body
+  ssr:state    cache snapshot + route info for hydration
+Delete this file to use the default shell.
+-->
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<title>abide app</title>
+<!--ssr:head-->
+</head>
+<body>
+<div id="app"><!--ssr:body--></div>
+<!--ssr:state-->
+</body>
+</html>

package/template/src/ui/pages/about/page.abide

@@ -0,0 +1,9 @@
+<script>
+/* A second page — served at GET /about. Folder name becomes the URL segment. */
+import Layout from '../../Layout.abide'
+</script>
+
+<Layout>
+    <h1>About</h1>
+    <p>This is a barebones abide app.</p>
+</Layout>

package/template/src/ui/pages/page.abide

@@ -0,0 +1,22 @@
+<script>
+/*
+Root page — served at GET /. Every folder under src/ui/pages/ that contains a
+page.abide mounts at that folder's URL.
+
+The blocking await-block below (the `then` attribute sits ON the <template await>)
+resolves on the server during SSR and renders inline — no pending placeholder. The
+decoded body is captured into the per-request cache, serialized into the HTML, and
+replayed on the client during hydration with no second fetch. A `then` *child*
+instead would stream the resolution in out of order.
+*/
+import { cache } from '@abide/abide/shared/cache'
+import Layout from '../Layout.abide'
+import { getHello } from '$server/rpc/getHello.ts'
+</script>
+
+<Layout>
+    <template await={cache(getHello)()} then="hello">
+        <h1>{hello.message}</h1>
+    </template>
+    <p>Edit <code>src/ui/pages/page.abide</code> and the page hot-reloads.</p>
+</Layout>

package/template/test/app.test.ts

@@ -0,0 +1,30 @@
+/*
+Test module — `createTestApp()` boots your real app on an ephemeral port (the
+same wiring as `abide start`, no fixtures) and hands back the whole surface:
+
+  app.fetch(path)        — pages and raw HTTP, origin + mount base resolved
+  app.rpc.<verb>(args)   — verbs over the real pipeline (CSRF, cookies, base),
+                           typed and decoded; .raw(args) for the Response
+  app.sockets.<name>     — a live Socket: iterate it, .tail(n), .publish(m)
+  app.health()           — the /__abide/health payload
+
+`app.rpc` / `app.sockets` are typed from your own verbs and sockets — generated
+into src/.abide during a build, so the keys exist with no imports. The abide
+preload (see bunfig.toml) makes the project's routes resolvable under bun test.
+
+`await using` disposes the app (server + restored slots) when the block ends,
+so a thrown assertion still releases the port.
+*/
+import { expect, test } from 'bun:test'
+import { createTestApp } from '@abide/abide/test/createTestApp'
+
+test('serves the home page', async () => {
+    await using app = await createTestApp()
+    const html = await (await app.fetch('/')).text()
+    expect(html).toContain('Hello from abide')
+})
+
+test('getHello returns the greeting', async () => {
+    await using app = await createTestApp()
+    expect(await app.rpc.getHello()).toEqual({ message: 'Hello from abide' })
+})

package/template/tsconfig.json

@@ -0,0 +1,18 @@
+{
+    "extends": "@abide/abide/tsconfig",
+    "include": ["src/**/*.ts", "src/.abide/**/*.ts", "src/**/*.abide"],
+    "compilerOptions": {
+        "paths": {
+            "$server": ["./src/server"],
+            "$server/*": ["./src/server/*"],
+            "$ui": ["./src/ui"],
+            "$ui/*": ["./src/ui/*"],
+            "$shared": ["./src/shared"],
+            "$shared/*": ["./src/shared/*"],
+            "$mcp": ["./src/mcp"],
+            "$mcp/*": ["./src/mcp/*"],
+            "$cli": ["./src/cli"],
+            "$cli/*": ["./src/cli/*"]
+        }
+    }
+}

package/tsconfig.app.json

@@ -0,0 +1,17 @@
+{
+    "compilerOptions": {
+        "target": "ESNext",
+        "module": "ESNext",
+        "moduleResolution": "bundler",
+        "lib": ["ESNext", "DOM", "DOM.Iterable"],
+        "strict": true,
+        "esModuleInterop": true,
+        "skipLibCheck": true,
+        "allowImportingTsExtensions": true,
+        "verbatimModuleSyntax": true,
+        "noEmit": true,
+        "isolatedModules": true,
+        "erasableSyntaxOnly": true,
+        "types": ["bun"]
+    }
+}