acrylblends 0.7.7 → 0.8.0

package/templates/blank/test/app.test.ts

@@ -1,19 +1,26 @@
 import assert from 'node:assert/strict'
+import { mkdirSync } from 'node:fs'
 import { mkdtemp, rm } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
+import { createServer } from 'node:net'
 import { join } from 'node:path'
 import { test } from 'node:test'
 import { fileURLToPath } from 'node:url'
+import { pinnedInstance, withPort } from '../plugins/instance/index.ts'
 import { type App, createApp } from '../src/app.ts'
-import { pinnedInstance, withPort } from '../src/plugins/instance/index.ts'
 import { APP_NAME } from '../src/routes.ts'
 
+/** Throwaway homes live inside the project (`.acrylblends/` is ignored by git): a sandboxed agent may not write to the system temp folder. */
+const scratch = join(fileURLToPath(new URL('..', import.meta.url)), '.acrylblends', 'test')
+mkdirSync(scratch, { recursive: true })
+
 const projectRoot = fileURLToPath(new URL('..', import.meta.url))
 
 /** Boot the app in a throwaway home on any free port, run the test, always stop it and remove the home. */
 async function withApp(run: (app: App) => Promise<void>) {
-  const home = await mkdtemp(join(tmpdir(), 'app-test-'))
-  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
+  const home = await mkdtemp(join(scratch, 'app-test-'))
+  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0), {
+    listen: false,
+  })
   try {
     await run(app)
   } finally {
@@ -24,14 +31,14 @@ async function withApp(run: (app: App) => Promise<void>) {
 
 test('serves the index route', () =>
   withApp(async (app) => {
-    const response = await fetch(`${app.url}/`)
+    const response = await app.root.router.request(`/`)
     assert.equal(response.status, 200)
     assert.deepEqual(await response.json(), { app: APP_NAME, ok: true })
   }))
 
 test('renders a .tsx page, and an error in it names the .tsx line', () =>
   withApp(async (app) => {
-    const response = await fetch(`${app.url}/about`)
+    const response = await app.root.router.request(`/about`)
     assert.equal(response.status, 200)
     assert.match(await response.text(), /<main><h1>About<\/h1>/)
     const { failingPage } = await import('../src/about.tsx')
@@ -46,14 +53,26 @@ test('renders a .tsx page, and an error in it names the .tsx line', () =>
 
 test('answers health checks and 404 for unknown paths', () =>
   withApp(async (app) => {
-    assert.equal((await fetch(`${app.url}/health`)).status, 200)
-    const missing = await fetch(`${app.url}/nope`)
+    assert.equal((await app.root.router.request(`/health`)).status, 200)
+    const missing = await app.root.router.request(`/nope`)
     assert.equal(missing.status, 404)
     await missing.body?.cancel()
   }))
 
-test('stops listening when stopped', async () => {
-  const home = await mkdtemp(join(tmpdir(), 'app-test-'))
+/** A sandbox may forbid listening on a port (Codex's workspace-write does); the one test that starts the real server is skipped there, and says so. */
+const canListen = await new Promise<boolean>((done) => {
+  const probe = createServer()
+  probe.once('error', () => done(false))
+  probe.listen(0, '127.0.0.1', () => probe.close(() => done(true)))
+})
+const skip = canListen ? false : 'this environment does not allow listening on a port'
+if (!canListen)
+  console.log(
+    `skipped: the test that starts the real server (${skip}); every other test ran in process`,
+  )
+
+test('stops listening when stopped', { skip }, async () => {
+  const home = await mkdtemp(join(scratch, 'app-test-'))
   const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
   await app.stop()
   await assert.rejects(fetch(`${app.url}/health`))

package/templates/blank/tsconfig.json

@@ -15,5 +15,5 @@
     "jsx": "react-jsx",
     "jsxImportSource": "#acryl-jsx"
   },
-  "include": ["src", "test"]
+  "include": ["src", "test", "plugins"]
 }

package/templates/chat/AGENTS.md

@@ -0,0 +1,16 @@
+
+## This app (chat): a streamed answer, history in a database
+
+A Cordis app: `blend.yaml` lists the plugins that are mounted (`acryl-router`, `acryl-db-sqlite`, `routes`, `acryl-node-server`), `src/app.ts` is the one file that names the SQLite provider, and `src/routes.ts` is the app's own plugin: it builds the app on the `db` port and mounts it.
+
+- **The dependency rule:** only `src/app.ts` (the `opener` in `package.json`) imports the provider. Every other file takes a `Db` (`import type { Db } from '../plugins/acryl-db/src/index.ts'`) as an argument and never imports `node:sqlite`, `pg`, another driver or `acryl-db-sqlite`. `npm test` and `npm run check` run `acrylblends check-deps`, which names the file and line of a violation; do not move the `opener` entry to silence it.
+- `src/llm.ts`: `Llm`, what the app needs from a model (messages in, pieces out, an aborted signal stops the work), and `openAiCompatible`, which calls an OpenAI-compatible chat completions API with `stream: true`. The base URL is `DEEPSEEK_BASE_URL` (default `https://api.deepseek.com`), the model `DEEPSEEK_MODEL` (default `deepseek-chat`), the key **only** the environment variable `DEEPSEEK_API_KEY`, read at the moment of the call: never write it to a file, a response or a log.
+- `src/db.ts`: `chatStore(db)`. The routes only call `chatStore`; keep SQL out of them. Every `db` call returns a promise: `await` it. The database is `data/chat.sqlite` (or the file `$CHAT_DB` names), opened by the `db` row with `migrations/` applied on start. The shape of the database is `migrations/NNN-name.sql`: to change it add the next numbered file and never edit one that has run. See `docs/framework/guides/data.md`.
+- `src/chat-app.ts`: `createApp(db, llm)`. `POST /api/chat` answers Server-Sent Events: `meta` (the conversation id), a `token` per piece, then `done` or `error`. The request's signal (`c.req.raw.signal`) goes to the model call, so a closed tab or the Stop button stops the request to the model; what had arrived is kept.
+- `src/client/chat.tsx`: the client component (own `tsconfig.json`, browser types): sends the message with `fetch`, reads the events as they arrive, shows the answer growing, and aborts on Stop. `clientModules` compiles it when the browser asks; `npm run build` compiles it once into `dist/client`. See `docs/framework/guides/client-modules.md`.
+- `test/chat.test.ts` tests every route with a mock `Llm` (never the network); keep it that way. It boots the whole app on a database file in a throwaway home and takes `app.root.db`. `test/server.test.ts` starts the real server and stops it with a signal.
+- To try it with a real model: `DEEPSEEK_API_KEY=... npm run dev`.
+
+## Before you ship
+
+Read `docs/framework/getting-started/deploy.md`. In short: `npm ci --omit=dev`, `npm run build`, `NODE_ENV=production npm start`; the app listens on `127.0.0.1` (`HOST=0.0.0.0` only in a container); the SQLite file goes outside the code folder (`CHAT_DB=/var/lib/chat/chat.sqlite`) and is backed up; the model key is an environment variable of the service (a root-only environment file for systemd), never a file in the repository. Anyone who can reach the app can spend your key: put it behind a login or on a private network before it is public.

package/templates/chat/blend.yaml

@@ -0,0 +1,29 @@
+# The app as data, in ACRYL's Blend format (blends.acryl.dev/v1alpha1): which plugins it mounts, in what order, with what config.
+# Edit this, not app.ts, to switch a plugin off (disabled: true) or change its config. `npm run lock` records what the app is built from.
+apiVersion: blends.acryl.dev/v1alpha1
+kind: Blueprint
+metadata:
+  id: acrylblends.__APP_NAME__
+  name: __APP_NAME__
+  version: 0.1.0
+  visibility: private # `npm run save` never pushes a private app to a public remote
+spec:
+  runtime: cordis
+  parameters:
+    # The address the server listens on.
+    hostname: { type: string, default: 127.0.0.1 }
+  rows:
+    - id: router
+      name: acryl-router
+    # The db port, on one SQLite file. The file and the migrations folder are set in src/app.ts (data/chat.sqlite, or the file the CHAT_DB environment variable names).
+    - id: db
+      name: acryl-db-sqlite
+    - id: routes
+      name: routes
+    - id: server
+      name: acryl-node-server
+      config:
+        hostname: "{{parameters.hostname}}"
+    # The door: an agent working in this folder looks at the page and acts on it through .acryl/bin/acryl. Development only: src/app.ts leaves it out when NODE_ENV=production.
+    - id: acryl-door
+      name: acryl-door

package/templates/chat/gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.acrylblends/
+.acryl/
+data/
+*.sqlite
+*.sqlite-*

package/templates/chat/migrations/001-chat.sql

@@ -0,0 +1,12 @@
+CREATE TABLE conversations (
+  id INTEGER PRIMARY KEY,
+  title TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE messages (
+  id INTEGER PRIMARY KEY,
+  conversation_id INTEGER NOT NULL REFERENCES conversations(id) ON DELETE CASCADE,
+  role TEXT NOT NULL CHECK (role IN ('user', 'assistant')),
+  content TEXT NOT NULL
+);

package/templates/chat/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "__APP_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "imports": {
+    "#acryl-jsx/jsx-runtime": "./plugins/acryl-router/src/core/jsx/jsx-runtime.ts",
+    "#acryl-jsx/jsx-dev-runtime": "./plugins/acryl-router/src/core/jsx/jsx-dev-runtime.ts"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "start": "node --import ./plugins/acryl-node-server/src/register.ts src/main.ts",
+    "dev": "node --watch --import ./plugins/acryl-node-server/src/register.ts src/main.ts",
+    "test": "acrylblends check-deps && node --import ./plugins/acryl-node-server/src/register.ts --test \"test/**/*.test.{ts,tsx}\"",
+    "check": "tsc --noEmit && tsc --noEmit -p src/client && acrylblends check-deps",
+    "build": "acrylblends build-client",
+    "lock": "node plugins/manifest/lock.ts",
+    "save": "node plugins/save/cli.ts",
+    "upgrade": "node plugins/manifest/upgrade-cli.ts"
+  },
+  "dependencies": {
+    "acrylblends": "__ACRYLBLENDS_RANGE__",
+    "typescript": "6.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0"
+  },
+  "acryl": {
+    "opener": "src/app.ts"
+  }
+}

package/templates/chat/src/app.ts

@@ -0,0 +1,106 @@
+import { isAbsolute, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Context, type Fiber } from '@deepseek-ai/cordis'
+import * as db from '../plugins/acryl-db-sqlite/src/index.ts'
+import * as door from '../plugins/acryl-door/src/index.ts'
+import * as nodeServer from '../plugins/acryl-node-server/src/index.ts'
+import * as router from '../plugins/acryl-router/src/index.ts'
+import { type AppInstance, instance } from '../plugins/instance/index.ts'
+import {
+  blueprintsIn,
+  compose,
+  loadManifest,
+  type ParameterValue,
+} from '../plugins/manifest/index.ts'
+import { doorEnabled } from './door.ts'
+import { routes } from './routes.ts'
+
+/** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them. */
+export const registry = {
+  'acryl-router': router,
+  'acryl-db-sqlite': db,
+  'acryl-node-server': nodeServer,
+  'acryl-door': door,
+  routes,
+}
+
+const projectRoot = fileURLToPath(new URL('..', import.meta.url))
+
+/** The manifest next to this app's source. */
+export const MANIFEST = join(projectRoot, 'blend.yaml')
+
+/** The manifest, resolved. `createApp` and the tests read it the same way. */
+export function readManifest(values?: Readonly<Record<string, ParameterValue>>) {
+  return loadManifest(MANIFEST, {
+    known: Object.keys(registry),
+    getBlueprint: blueprintsIn(join(projectRoot, 'blueprints')),
+    ...(values ? { values } : {}),
+  })
+}
+
+/** The manifest without some rows: without its server (and so its door) the app is reached in process, through `root.router.request`; the door is also left out in production. */
+function without<M extends { plugins: readonly { use: string }[] }>(
+  manifest: M,
+  ...uses: string[]
+): M {
+  return {
+    ...manifest,
+    plugins: manifest.plugins.map((row) =>
+      uses.includes(row.use) ? { ...row, disabled: true } : row,
+    ),
+  }
+}
+
+export interface App {
+  readonly root: Context
+  /** The address the server listens on; empty when the app was made with `listen: false`. */
+  readonly url: string
+  stop(): Promise<void>
+}
+
+export interface AppOptions {
+  readonly values?: Readonly<Record<string, ParameterValue>>
+  /** The SQLite file, relative to the app folder; an absolute path is used as it is (tests give a file in a throwaway home). Default: `data/chat.sqlite`. */
+  readonly database?: string
+  /** Start the HTTP server (default). Tests pass `false` and call `app.root.router.request(path)`: it needs no port, so it also runs where a sandbox forbids listening. */
+  readonly listen?: boolean
+}
+
+/**
+ * The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. The `db` row opens the database and applies
+ * `migrations/`; the one place that names the SQLite provider is this file (`acrylblends check-deps`), so a different provider is a change here.
+ */
+export async function createApp(chosen: AppInstance, options: AppOptions = {}): Promise<App> {
+  const manifest = readManifest(options.values)
+  const listen = options.listen
+  const file = options.database ?? 'data/chat.sqlite'
+  const root = new Context()
+  const first = root.plugin(instance, chosen)
+  await first.await()
+  const fibers: Fiber[] = [
+    first,
+    ...(await compose(
+      root,
+      listen === false
+        ? without(manifest, 'acryl-node-server', 'acryl-door')
+        : doorEnabled()
+          ? manifest
+          : without(manifest, 'acryl-door'),
+      registry,
+      {
+        db: {
+          path: isAbsolute(file) ? file : resolve(projectRoot, file),
+          migrations: join(projectRoot, 'migrations'),
+        },
+        server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 },
+      },
+    )),
+  ]
+  return {
+    root,
+    url: listen === false ? '' : root.nodeServer.url,
+    async stop() {
+      for (const fiber of [...fibers].reverse()) await fiber.dispose()
+    },
+  }
+}

package/templates/chat/src/chat-app.ts

@@ -0,0 +1,101 @@
+import type { Db } from '../plugins/acryl-db/src/index.ts'
+import {
+  type StandardSchema,
+  schemaValidator,
+  streamSSE,
+} from '../plugins/acryl-router/src/helpers/index.ts'
+import { Acryl } from '../plugins/acryl-router/src/index.ts'
+import { chatStore } from './db.ts'
+import { type Llm, openAiCompatible } from './llm.ts'
+import { chatPage } from './page.tsx'
+
+interface ChatInput {
+  message: string
+  conversation?: number
+}
+
+const ChatSchema: StandardSchema<ChatInput> = {
+  '~standard': {
+    validate: (value) => {
+      const input = (value ?? {}) as Record<string, unknown>
+      const message = typeof input.message === 'string' ? input.message.trim() : ''
+      const issues = []
+      if (message === '') issues.push({ message: 'Write a message.', path: ['message'] })
+      else if (message.length > 4000)
+        issues.push({ message: 'The message is at most 4000 characters.', path: ['message'] })
+      if (input.conversation !== undefined && !Number.isInteger(input.conversation))
+        issues.push({ message: 'The conversation is a number.', path: ['conversation'] })
+      return issues.length > 0
+        ? { issues }
+        : { value: { message, conversation: input.conversation as number | undefined } }
+    },
+  },
+}
+
+export function createApp(db: Db, llm: Llm = openAiCompatible) {
+  const store = chatStore(db)
+  const app = new Acryl()
+
+  app.get('/', async (c) => {
+    const id = Number(c.req.query('c'))
+    const current = Number.isInteger(id) ? await store.conversation(id) : undefined
+    return c.html(
+      chatPage(
+        await store.conversations(),
+        current,
+        current ? await store.messages(current.id) : [],
+      ),
+    )
+  })
+
+  app.get('/api/conversations', async (c) => c.json({ conversations: await store.conversations() }))
+  app.get('/api/conversations/:id', async (c) => {
+    const id = Number(c.req.param('id'))
+    const conversation = await store.conversation(id)
+    return conversation
+      ? c.json({ conversation, messages: await store.messages(id) })
+      : c.json({ error: 'No such conversation.' }, 404)
+  })
+  app.delete('/api/conversations/:id', async (c) =>
+    (await store.remove(Number(c.req.param('id'))))
+      ? c.json({ ok: true })
+      : c.json({ error: 'No such conversation.' }, 404),
+  )
+
+  // The answer streams as Server-Sent Events: `meta` (the conversation id), then one `token` per piece, then `done`, or `error`.
+  // The request's signal aborts when the client goes away (the Stop button, a closed tab); it is passed to the model call so the upstream request stops too.
+  app.post('/api/chat', schemaValidator('json', ChatSchema), async (c) => {
+    const { message, conversation } = c.req.valid('json')
+    const known = conversation === undefined ? undefined : await store.conversation(conversation)
+    if (conversation !== undefined && !known) return c.json({ error: 'No such conversation.' }, 404)
+    const id = known?.id ?? (await store.start(message))
+    await store.add(id, 'user', message)
+    const history = (await store.messages(id)).map(({ role, content }) => ({ role, content }))
+    const signal = c.req.raw.signal
+    return streamSSE(c, async (stream) => {
+      let answer = ''
+      await stream.writeSSE({ event: 'meta', data: JSON.stringify({ conversation: id }) })
+      try {
+        for await (const piece of llm(history, signal)) {
+          answer += piece
+          await stream.writeSSE({ event: 'token', data: JSON.stringify(piece) })
+        }
+        await stream.writeSSE({ event: 'done', data: '{}' })
+      } catch (error) {
+        if (!signal.aborted) {
+          console.error(error)
+          // The reason stays in the log; the page gets a plain message.
+          await stream.writeSSE({
+            event: 'error',
+            data: JSON.stringify('The model could not answer. Try again.'),
+          })
+        }
+      } finally {
+        // What arrived is kept, also when the reader pressed Stop.
+        if (answer !== '') await store.add(id, 'assistant', answer)
+      }
+    })
+  })
+
+  return app
+}

package/templates/chat/src/client/chat.tsx

@@ -0,0 +1,115 @@
+import { render, useRef, useState } from 'acrylblends/jsx/dom'
+
+/** Read a Server-Sent Events body: calls `on(event, data)` for each event as it arrives. (EventSource only does GET, and this is a POST.) */
+async function readEvents(
+  body: ReadableStream<Uint8Array>,
+  on: (event: string, data: string) => void,
+): Promise<void> {
+  const reader = body.getReader()
+  const decoder = new TextDecoder()
+  let buffer = ''
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) return
+    // Line endings may be CRLF; a \r at the end of a chunk is completed by the next chunk, so normalise the whole buffer.
+    buffer = (buffer + decoder.decode(value, { stream: true })).replaceAll('\r\n', '\n')
+    const blocks = buffer.split('\n\n')
+    buffer = blocks.pop() ?? ''
+    for (const block of blocks) {
+      let event = 'message'
+      const data: string[] = []
+      for (const line of block.split('\n')) {
+        if (line.startsWith('event:')) event = line.slice(6).trim()
+        else if (line.startsWith('data:')) data.push(line.slice(5).replace(/^ /, '')) // the SSE spec strips one leading space only
+      }
+      on(event, data.join('\n'))
+    }
+  }
+}
+
+const Chat = ({ start }: { start: number | undefined }) => {
+  const [text, setText] = useState('')
+  const [asked, setAsked] = useState('')
+  const [answer, setAnswer] = useState('')
+  const [error, setError] = useState('')
+  const [busy, setBusy] = useState(false)
+  const conversation = useRef<number | undefined>(start)
+  const controller = useRef<AbortController | undefined>(undefined)
+
+  const send = async (event: Event) => {
+    event.preventDefault()
+    const message = text.trim()
+    if (message === '' || busy) return
+    setAsked(message)
+    setAnswer('')
+    setError('')
+    setText('')
+    setBusy(true)
+    controller.current = new AbortController()
+    try {
+      const response = await fetch('/api/chat', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ message, conversation: conversation.current }),
+        signal: controller.current.signal,
+      })
+      if (!response.ok || !response.body) {
+        const problem = (await response.json().catch(() => ({}))) as {
+          issues?: { message: string }[]
+          error?: string
+        }
+        setError(problem.issues?.[0]?.message ?? problem.error ?? 'The message was not accepted.')
+        return
+      }
+      let soFar = ''
+      await readEvents(response.body, (name, data) => {
+        if (name === 'meta') {
+          conversation.current = (JSON.parse(data) as { conversation: number }).conversation
+          history.replaceState(null, '', `/?c=${conversation.current}`)
+        } else if (name === 'token') {
+          soFar += JSON.parse(data) as string
+          setAnswer(soFar)
+        } else if (name === 'error') setError(JSON.parse(data) as string)
+      })
+    } catch (caught) {
+      if (!(caught instanceof DOMException && caught.name === 'AbortError'))
+        setError('The connection was lost.')
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div>
+      {asked !== '' && <p class="row user">{asked}</p>}
+      {answer !== '' && <p class="row">{answer}</p>}
+      {error !== '' && (
+        <p class="row error" role="alert">
+          {error}
+        </p>
+      )}
+      <form onSubmit={send}>
+        <textarea
+          rows={3}
+          value={text}
+          placeholder="Ask something"
+          onInput={(e) => setText((e.target as HTMLTextAreaElement).value)}
+        />
+        <p>
+          <button type="submit" disabled={busy}>
+            Send
+          </button>{' '}
+          {busy && (
+            <button type="button" onClick={() => controller.current?.abort()}>
+              Stop
+            </button>
+          )}
+        </p>
+      </form>
+    </div>
+  )
+}
+
+const root = document.getElementById('chat')!
+const start = root.dataset.conversation ? Number(root.dataset.conversation) : undefined
+render(<Chat start={start} />, root)

package/templates/chat/src/client/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "jsx": "react-jsx",
+    "jsxImportSource": "acrylblends/jsx/dom",
+    "types": [],
+    "paths": {
+      "acrylblends/jsx/dom": ["../../plugins/acryl-router/src/browser/jsx-dom.ts"],
+      "acrylblends/jsx/dom/jsx-runtime": [
+        "../../plugins/acryl-router/src/core/jsx/dom/jsx-runtime.ts"
+      ],
+      "acrylblends/jsx/dom/jsx-dev-runtime": [
+        "../../plugins/acryl-router/src/core/jsx/dom/jsx-dev-runtime.ts"
+      ],
+      "acrylblends/jsx/dom/client": ["../../plugins/acryl-router/src/browser/jsx-dom.ts"],
+      "acrylblends/client": ["../../plugins/acryl-router/src/browser/client.ts"]
+    }
+  },
+  "include": ["**/*.ts", "**/*.tsx"]
+}

package/templates/chat/src/db.ts

@@ -0,0 +1,43 @@
+import type { Db } from '../plugins/acryl-db/src/index.ts'
+
+export interface Message {
+  id: number
+  conversation_id: number
+  role: 'user' | 'assistant'
+  content: string
+}
+export interface Conversation {
+  id: number
+  title: string
+}
+
+export function chatStore(db: Db) {
+  return {
+    conversations: (): Promise<Conversation[]> =>
+      db.all<Conversation>('SELECT id, title FROM conversations ORDER BY id DESC'),
+    conversation: (id: number): Promise<Conversation | undefined> =>
+      db.get<Conversation>('SELECT id, title FROM conversations WHERE id = ?', id),
+    messages: (id: number): Promise<Message[]> =>
+      db.all<Message>('SELECT * FROM messages WHERE conversation_id = ? ORDER BY id', id),
+    async start(title: string): Promise<number> {
+      const row = await db.get<{ id: number }>(
+        'INSERT INTO conversations (title, created_at) VALUES (?, ?) RETURNING id',
+        title.slice(0, 60),
+        new Date().toISOString(),
+      )
+      return row!.id
+    },
+    async add(conversationId: number, role: Message['role'], content: string): Promise<void> {
+      await db.run(
+        'INSERT INTO messages (conversation_id, role, content) VALUES (?, ?, ?)',
+        conversationId,
+        role,
+        content,
+      )
+    },
+    async remove(id: number): Promise<boolean> {
+      const { changes } = await db.run('DELETE FROM conversations WHERE id = ?', id)
+      return changes > 0
+    },
+  }
+}

package/templates/chat/src/door.ts

@@ -0,0 +1,7 @@
+/**
+ * The door (`plugins/acryl-door`) lets an agent working in this folder look at the running page and act on it, through `.acryl/bin/acryl`. It is on in development
+ * and off in production (`NODE_ENV=production`) and when `ACRYL_DOOR=off`: `src/app.ts` leaves its row out then, and the pages leave its script tag out. One process
+ * at a time serves a folder's door, so the tests that start the real server set `ACRYL_DOOR=off` and a second `npm start` beside a running one does not fail on it.
+ */
+export const doorEnabled = (): boolean =>
+  process.env.NODE_ENV !== 'production' && process.env.ACRYL_DOOR !== 'off'

package/templates/chat/src/llm.ts

@@ -0,0 +1,42 @@
+/** What the app needs from a language model: the conversation so far in, the answer out piece by piece. Aborting the signal must stop the work. */
+export type Llm = (
+  messages: { role: string; content: string }[],
+  signal: AbortSignal,
+) => AsyncIterable<string>
+
+/**
+ * An OpenAI-compatible chat completions API with `stream: true` (DeepSeek by default). The key is read from DEEPSEEK_API_KEY at the moment of the call and
+ * is never stored; DEEPSEEK_BASE_URL and DEEPSEEK_MODEL choose the service.
+ */
+export const openAiCompatible: Llm = async function* (messages, signal) {
+  const key = process.env.DEEPSEEK_API_KEY
+  if (!key) throw new Error('DEEPSEEK_API_KEY is not set')
+  const base = (process.env.DEEPSEEK_BASE_URL ?? 'https://api.deepseek.com').replace(/\/$/, '')
+  const response = await fetch(`${base}/chat/completions`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` },
+    body: JSON.stringify({
+      model: process.env.DEEPSEEK_MODEL ?? 'deepseek-chat',
+      messages,
+      stream: true,
+    }),
+    signal,
+  })
+  if (!response.ok || !response.body)
+    throw new Error(`the model service answered ${response.status}`)
+  const decoder = new TextDecoder()
+  let buffer = ''
+  for await (const chunk of response.body) {
+    buffer += decoder.decode(chunk, { stream: true })
+    const lines = buffer.split('\n')
+    buffer = lines.pop() ?? ''
+    for (const line of lines) {
+      if (!line.startsWith('data:')) continue
+      const data = line.slice(5).trim()
+      if (data === '[DONE]') return
+      const piece = (JSON.parse(data) as { choices?: { delta?: { content?: string } }[] })
+        .choices?.[0]?.delta?.content
+      if (piece) yield piece
+    }
+  }
+}

package/templates/chat/src/main.ts

@@ -0,0 +1,28 @@
+import { fileURLToPath } from 'node:url'
+import { selectInstance } from '../plugins/instance/index.ts'
+import { createApp } from './app.ts'
+
+// The composition root: the one place that reads the environment and chooses where the app lives.
+const chosen = selectInstance({
+  projectRoot: fileURLToPath(new URL('..', import.meta.url)),
+  // PORT and HOST are the names hosting platforms set; ACRYLBLENDS_PORT and ACRYLBLENDS_HOST win when both are given.
+  env: {
+    ...(process.env.PORT ? { ACRYLBLENDS_PORT: process.env.PORT } : {}),
+    ...(process.env.HOST ? { ACRYLBLENDS_HOST: process.env.HOST } : {}),
+    ...process.env,
+  },
+})
+const app = await createApp(chosen, {
+  ...(process.env.CHAT_DB ? { database: process.env.CHAT_DB } : {}),
+})
+console.log(`listening on ${app.url} (data in ${chosen.home})`)
+
+// Stop taking requests, let the ones in flight finish, then close the database (the db plugin does, when it is disposed) and exit.
+const stop = async () => {
+  const timer = setTimeout(() => process.exit(1), 10_000)
+  timer.unref()
+  await app.stop()
+  process.exit(0)
+}
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)