acrylblends 0.7.8 → 0.8.1

package/templates/chat/src/app.ts

@@ -0,0 +1,107 @@
+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 { extensions } from '../plugins/extensions/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,
+  extensions,
+  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 read = readManifest(options.values)
+  const listen = options.listen
+  // Rows left out: the server (and the door, which needs it) when the app is reached in process; the door when it is switched off; live plugin installs in production.
+  const leaveOut = new Set<string>()
+  if (listen === false) leaveOut.add('acryl-node-server').add('acryl-door')
+  if (!doorEnabled()) leaveOut.add('acryl-door')
+  if (process.env.NODE_ENV === 'production') leaveOut.add('extensions')
+  const manifest = without(read, ...leaveOut)
+  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, manifest, registry, {
+      db: {
+        path: isAbsolute(file) ? file : resolve(projectRoot, file),
+        migrations: join(projectRoot, 'migrations'),
+      },
+      // What is installed while the app runs lives in plugins/, next to the plugins copied from the library (plugins/library.json lists those, so they are not installed twice).
+      extensions: { sources: [{ dir: join(projectRoot, 'plugins'), trust: 'install' }] },
+      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)

package/templates/chat/src/page.tsx

@@ -0,0 +1,40 @@
+import type { Conversation, Message } from './db.ts'
+import { doorEnabled } from './door.ts'
+
+export const chatPage = (
+  conversations: Conversation[],
+  current: Conversation | undefined,
+  messages: Message[],
+): string =>
+  (
+    <html lang="en">
+      <head>
+        <meta charset="utf-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <title>Chat</title>
+        <style
+          dangerouslySetInnerHTML={{
+            __html:
+              'body{font:16px system-ui;max-width:48rem;margin:2rem auto;padding:0 1rem}.row{white-space:pre-wrap;margin:.75rem 0}.user{font-weight:600}.error{color:#b00020}textarea{width:100%;box-sizing:border-box;padding:.5rem}nav a{margin-right:.75rem}',
+          }}
+        />
+      </head>
+      <body>
+        <h1>Chat</h1>
+        <nav>
+          <a href="/">New chat</a>
+          {conversations.map((c) => (
+            <a href={`/?c=${c.id}`}>{c.title}</a>
+          ))}
+        </nav>
+        <div id="log">
+          {messages.map((m) => (
+            <p class={`row ${m.role}`}>{m.content}</p>
+          ))}
+        </div>
+        <div id="chat" data-conversation={current ? String(current.id) : ''} />
+        <script type="module" src="/client/chat.tsx" />
+        {doorEnabled() ? <script type="module" src="/api/acryl-door/page.js" /> : null}
+      </body>
+    </html>
+  ).toString()

package/templates/chat/src/routes.ts

@@ -0,0 +1,15 @@
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '../plugins/acryl-db/src/cordis.ts'
+import { createApp } from './chat-app.ts'
+import { openAiCompatible } from './llm.ts'
+import { createClient } from './runtime.ts'
+
+/** The app's own plugin: it builds the app on the `db` port and mounts it on the router. The mount is removed when the plugin is disposed. */
+export const routes = {
+  name: 'routes',
+  inject: ['router', 'db'],
+  apply(ctx: Context) {
+    ctx.router.route('/', createApp(ctx.db, openAiCompatible))
+    ctx.router.route('/client', createClient())
+  },
+}

package/templates/chat/src/runtime.ts

@@ -0,0 +1,17 @@
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { clientModules } from '../plugins/acryl-node-server/src/client-modules.ts'
+
+/** The browser builds of the DOM renderer and the typed client, shipped by the `acrylblends` package this app depends on (`clientModules` serves them). */
+const runtimeDir = join(
+  dirname(createRequire(import.meta.url).resolve('acrylblends/package.json')),
+  'lib',
+  'browser',
+)
+
+/**
+ * Client components without a bundler: `src/client` is compiled when the browser asks; `npm run build` compiles it once for production
+ * (`NODE_ENV=production` then serves only `dist/client`). `src/routes.ts` mounts it at `/client` on the router, next to the app.
+ */
+export const createClient = () =>
+  clientModules({ root: 'src/client', compiled: 'dist/client', runtimeDir })

package/templates/chat/template.json

@@ -0,0 +1,12 @@
+{
+  "plugins": [
+    "instance",
+    "acryl-router",
+    "acryl-node-server",
+    "acryl-db-sqlite",
+    "manifest",
+    "save",
+    "extensions",
+    "acryl-door"
+  ]
+}