acrylblends 0.2.0 → 0.4.0

package/templates/todo/src/todo.ts

@@ -0,0 +1,123 @@
+/**
+ * The reference app of the ACRYL Framework: a todo list in one plugin. It needs `router` and `state`, keeps the list in a cell, serves
+ * JSON CRUD plus a page, and writes the list to a file so it survives a restart. Nothing else.
+ */
+
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { App, HTTPException } from './plugins/acryl-router/src/index.ts'
+import { bodyLimit, loopbackOnly } from './plugins/acryl-router/src/middleware/index.ts'
+import { schemaValidator, streamSSE, type StandardSchema } from './plugins/acryl-router/src/helpers/index.ts'
+import type {} from './plugins/acryl-state/src/index.ts'
+import { PAGE } from './page.ts'
+
+/** Stable Cordis plugin name, equal to the package name and the Loader row id. */
+export const name = 'acryl-todo'
+export const inject = ['router', 'state']
+
+export interface Todo { id: number, title: string, done: boolean }
+export interface Config { file?: string }
+
+/** Standard Schema for the body of a new todo, written by hand so the example has no schema library. */
+const NewTodo: StandardSchema<{ title: string }> = {
+  '~standard': {
+    validate: value => {
+      const title = (value as { title?: unknown } | null)?.title
+      return typeof title === 'string' && title.trim() !== '' && title.length <= 200
+        ? { value: { title: title.trim() } }
+        : { issues: [{ message: 'title must be 1 to 200 characters', path: ['title'] }] }
+    },
+  },
+}
+
+/** Standard Schema for a change to a todo. */
+const TodoChange: StandardSchema<{ done: boolean }> = {
+  '~standard': {
+    validate: value => {
+      const done = (value as { done?: unknown } | null)?.done
+      return typeof done === 'boolean' ? { value: { done } } : { issues: [{ message: 'done must be true or false', path: ['done'] }] }
+    },
+  },
+}
+
+/** A todo body is small; anything bigger is refused before it is read. */
+const MAX_BODY_BYTES = 16 * 1024
+
+/** A missing file is a new list. Any other failure (unreadable, corrupt, half-written) refuses to start: starting empty would overwrite the user's real list on the first save. */
+function load(file: string | undefined): Todo[] {
+  if (file === undefined) return []
+  let text: string
+  try {
+    text = readFileSync(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw new Error(`acryl-todo: cannot read ${file}: ${(error as Error).message}`, { cause: error })
+  }
+  try {
+    const parsed: unknown = JSON.parse(text)
+    if (!Array.isArray(parsed)) throw new Error('not a list')
+    return parsed as Todo[]
+  } catch (error) {
+    throw new Error(`acryl-todo: ${file} is not a valid todo list (${(error as Error).message}); fix or remove it, it was left untouched`, { cause: error })
+  }
+}
+
+function save(file: string, todos: readonly Todo[]): void {
+  mkdirSync(dirname(file), { recursive: true })
+  const temporary = `${file}.tmp`
+  writeFileSync(temporary, JSON.stringify(todos))
+  renameSync(temporary, file)
+}
+
+export function apply(ctx: Context, config: Config = {}): void {
+  const todos = ctx.state.cell<readonly Todo[]>('todo.list', load(config.file))
+  if (config.file !== undefined) {
+    const file = config.file
+    ctx.effect(() => todos.subscribe(list => { save(file, list) }), 'acryl-todo: save to file')
+  }
+  const nextId = (): number => todos.get().reduce((max, todo) => Math.max(max, todo.id), 0) + 1
+
+  const find = (id: number): Todo => {
+    const todo = todos.get().find(item => item.id === id)
+    if (todo === undefined) throw new HTTPException(404, { message: 'no such todo' })
+    return todo
+  }
+
+  const api = new App()
+    .use(loopbackOnly({ inProcess: 'allow' }), bodyLimit({ maxSize: MAX_BODY_BYTES }))
+    .get('/', c => c.html(PAGE))
+    .get('/api', c => c.json(todos.get()))
+    .post('/api', schemaValidator('json', NewTodo), c => {
+      const todo: Todo = { id: nextId(), title: c.req.valid('json').title, done: false }
+      todos.update(list => [...list, todo])
+      return c.json(todo, 201)
+    })
+    .patch('/api/:id', schemaValidator('json', TodoChange), c => {
+      const { id } = find(Number(c.req.param('id')))
+      const { done } = c.req.valid('json')
+      todos.update(list => list.map(todo => todo.id === id ? { ...todo, done } : todo))
+      return c.json(find(id))
+    })
+    .delete('/api/:id', c => {
+      const { id } = find(Number(c.req.param('id')))
+      todos.update(list => list.filter(todo => todo.id !== id))
+      return c.body(null, 204)
+    })
+    .get('/events', c => streamSSE(c, async stream => {
+      const ended = new Promise<void>(resolve => { stream.onAbort(resolve) })
+      // Writes are asynchronous; chaining them keeps events in the order the list changed.
+      let queue: Promise<unknown> = Promise.resolve()
+      const send = (list: readonly Todo[]): void => { queue = queue.then(() => stream.writeSSE({ data: JSON.stringify(list) })).catch(() => {}) }
+      send(todos.get())
+      const unsubscribe = todos.subscribe(send)
+      try {
+        await ended
+      } finally {
+        unsubscribe()
+      }
+    }))
+  ctx.router.route('/todo', api)
+
+  ctx.inject(['routerHttp'], inner => { inner.routerHttp.mount('/todo') })
+}

package/templates/todo/template.json

@@ -0,0 +1 @@
+{ "plugins": ["instance", "acryl-router", "acryl-state", "acryl-node-server", "manifest", "save"] }

package/templates/todo/test/todo.test.ts

@@ -0,0 +1,145 @@
+import assert from 'node:assert/strict'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { test } from 'node:test'
+import { fileURLToPath } from 'node:url'
+import { type App, createApp, readManifest } from '../src/app.ts'
+import { pinnedInstance, withPort } from '../src/plugins/instance/index.ts'
+
+const projectRoot = fileURLToPath(new URL('..', import.meta.url))
+
+/** Boot the app on any free port with its data in `home`, run the test, always stop it. */
+async function withApp(home: string, run: (app: App) => Promise<void>) {
+  const app = await createApp(withPort(pinnedInstance(home, { root: projectRoot }), 0))
+  try {
+    await run(app)
+  } finally {
+    await app.stop()
+  }
+}
+
+async function withHome(run: (home: string) => Promise<void>) {
+  const home = await mkdtemp(join(tmpdir(), 'todo-test-'))
+  try {
+    await run(home)
+  } finally {
+    await rm(home, { recursive: true, force: true })
+  }
+}
+
+const send = (app: App, method: string, path: string, body?: unknown) =>
+  fetch(`${app.url}${path}`, {
+    method,
+    headers: { 'content-type': 'application/json' },
+    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+  })
+
+test('creates, completes, lists and deletes', () =>
+  withHome((home) =>
+    withApp(home, async (app) => {
+      const created = await send(app, 'POST', '/todo/api', { title: ' buy milk ' })
+      assert.equal(created.status, 201)
+      assert.deepEqual(await created.json(), { id: 1, title: 'buy milk', done: false })
+
+      const done = await send(app, 'PATCH', '/todo/api/1', { done: true })
+      assert.deepEqual(await done.json(), { id: 1, title: 'buy milk', done: true })
+      assert.deepEqual(await (await send(app, 'GET', '/todo/api')).json(), [
+        { id: 1, title: 'buy milk', done: true },
+      ])
+
+      assert.equal((await send(app, 'DELETE', '/todo/api/1')).status, 204)
+      assert.deepEqual(await (await send(app, 'GET', '/todo/api')).json(), [])
+    }),
+  ))
+
+test('a change from a foreign origin is refused; a plain request from this machine works', () =>
+  withHome((home) =>
+    withApp(home, async (app) => {
+      const post = (headers: Record<string, string>) =>
+        fetch(`${app.url}/todo/api`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json', ...headers },
+          body: JSON.stringify({ title: 'x' }),
+        })
+      assert.equal((await post({ origin: 'http://evil.example' })).status, 403)
+      assert.equal((await post({ origin: 'null' })).status, 403)
+      assert.equal((await post({})).status, 201)
+      assert.equal((await post({ origin: new URL(app.url).origin })).status, 201)
+    }),
+  ))
+
+test('rejects bad input and unknown ids', () =>
+  withHome((home) =>
+    withApp(home, async (app) => {
+      assert.equal((await send(app, 'POST', '/todo/api', { title: '' })).status, 400)
+      assert.equal((await send(app, 'POST', '/todo/api', { title: 42 })).status, 400)
+      assert.equal((await send(app, 'DELETE', '/todo/api/9')).status, 404)
+      assert.equal((await send(app, 'PATCH', '/todo/api/9', { done: true })).status, 404)
+      assert.equal((await send(app, 'GET', '/nope')).status, 404)
+    }),
+  ))
+
+test('the list survives a restart: a second app on the same home sees it', () =>
+  withHome(async (home) => {
+    await withApp(home, async (app) => {
+      await send(app, 'POST', '/todo/api', { title: 'first' })
+      await send(app, 'POST', '/todo/api', { title: 'second' })
+      await send(app, 'PATCH', '/todo/api/2', { done: true })
+    })
+    await withApp(home, async (app) => {
+      const list = (await (await send(app, 'GET', '/todo/api')).json()) as Array<{
+        id: number
+        done: boolean
+      }>
+      assert.deepEqual(
+        list.map((todo) => [todo.id, todo.done]),
+        [
+          [1, false],
+          [2, true],
+        ],
+      )
+      const created = (await (await send(app, 'POST', '/todo/api', { title: 'third' })).json()) as {
+        id: number
+      }
+      assert.equal(created.id, 3)
+    })
+  }))
+
+test('serves the page, and streams the list: now, and again on every change', () =>
+  withHome((home) =>
+    withApp(home, async (app) => {
+      const page = await send(app, 'GET', '/todo')
+      assert.equal(page.status, 200)
+      assert.match(await page.text(), /<title>Todo<\/title>/)
+
+      const controller = new AbortController()
+      const stream = await fetch(`${app.url}/todo/events`, { signal: controller.signal })
+      const reader = stream.body!.getReader()
+      const decoder = new TextDecoder()
+      let text = ''
+      const until = async (what: RegExp) => {
+        for (let waited = 0; !what.test(text) && waited < 3000; waited += 25) {
+          const next = await Promise.race([
+            reader.read(),
+            new Promise<{ done: true; value: undefined }>((done) =>
+              setTimeout(() => done({ done: true, value: undefined }), 25),
+            ),
+          ])
+          if (next.value) text += decoder.decode(next.value, { stream: true })
+        }
+        assert.match(text, what)
+      }
+      await until(/data: \[\]/)
+      await send(app, 'POST', '/todo/api', { title: 'streamed' })
+      await until(/"title":"streamed"/)
+      controller.abort()
+    }),
+  ))
+
+test('the manifest decides what is mounted', () => {
+  assert.deepEqual(
+    readManifest().plugins.map((row) => row.id),
+    ['router', 'state', 'todo', 'server'],
+  )
+})

package/templates/todo/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noImplicitOverride": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src", "test"]
+}

package/templates/todo/upstream.json

@@ -0,0 +1,12 @@
+{
+  "source": {
+    "repo": "acryldev/acryl",
+    "files": {
+      "examples/acryl-todo/src/index.ts": "src/todo.ts",
+      "examples/acryl-todo/src/page.ts": "src/page.ts"
+    },
+    "commit": "df79b188398b6d4f8cceda35a72b88300a10a9ce"
+  },
+  "rewrittenSpecifiers": 4,
+  "digest": "sha256:c4efede39387681003c6d2f0f2858e157a84bcaaf9ae94ebe23d10f72a538ffd"
+}

package/plugins/events/index.ts

@@ -1,42 +0,0 @@
-/**
- * Events as a stream (`GET /events`, server-sent events). A client connects once and receives every change as it happens: the
- * event name is the Cordis event (`tasks/changed`, `extensions/changed`, any you list), the data is `{ "args": [...] }` with the
- * event's arguments as JSON. Desktop, web and terminal surfaces can all render the same stream (the Pi Durable "one place to
- * observe" idea); nothing here knows about tasks or extensions. Each connection's listeners are removed when the client leaves.
- */
-import type { Context } from '@deepseek-ai/cordis'
-import type {} from '../http/index.ts'
-
-export interface EventsConfig {
-  /** Cordis events to stream. */
-  topics?: readonly string[]
-  /** Where the stream is served. Default `/events`. */
-  path?: string
-}
-
-export const events = {
-  name: 'events',
-  inject: ['http'],
-  apply(ctx: Context, config?: EventsConfig) {
-    const topics = config?.topics ?? []
-    const path = config?.path ?? '/events'
-    const listen = ctx.on as unknown as (
-      topic: string,
-      listener: (...args: unknown[]) => void,
-    ) => () => void
-    ctx.effect(() =>
-      ctx.http.route('GET', path, () => ({
-        body: null,
-        stream: (send) => {
-          const leaves = topics.map((topic) =>
-            listen.call(ctx, topic, (...args: unknown[]) => send(topic, { args })),
-          )
-          send('connected', { topics })
-          return () => {
-            for (const leave of leaves) leave()
-          }
-        },
-      })),
-    )
-  },
-}

package/plugins/events/plugin.json

@@ -1,9 +0,0 @@
-{
-  "name": "events",
-  "description": "A live stream of Cordis events over server-sent events, so a surface renders state instead of polling.",
-  "requires": ["http"],
-  "inject": ["http"],
-  "provides": [],
-  "dependencies": { "@deepseek-ai/cordis": "4.0.4" },
-  "mount": "add a row to blend.yaml: events, with config { topics: ['tasks/changed', 'extensions/changed'] }"
-}

package/plugins/http/index.ts

@@ -1,64 +0,0 @@
-import type { Context } from '@deepseek-ai/cordis'
-
-/** A request as routes see it: the method, the path and the parsed JSON body, if any. */
-export interface RouteRequest {
-  readonly method: string
-  readonly path: string
-  readonly body: unknown
-}
-
-/** What a route answers. The status defaults to 200; the body is sent as JSON. */
-/** Sends one server-sent event: `topic` is the event name, `data` is sent as JSON. */
-export type Send = (topic: string, data: unknown) => void
-
-/** A live stream: called when a client connects, it returns what to run when the client leaves. */
-export type Stream = (send: Send) => () => void
-
-export interface Reply {
-  readonly status?: number
-  readonly body: unknown
-  /** Answer with a stream of server-sent events instead of a JSON body. */
-  readonly stream?: Stream
-}
-
-export type Handler = (request: RouteRequest) => Reply | Promise<Reply>
-
-/** The router service. Plugins add routes; the server asks it to answer requests. */
-export interface Http {
-  /** Add a route. Returns the function that removes it, so it can be the disposer of a `ctx.effect`. */
-  route(method: string, path: string, handler: Handler): () => void
-  /** Answer a request from the registered routes, 404 when none matches. */
-  handle(request: RouteRequest): Promise<{ status: number; body: unknown; stream?: Stream }>
-  /** The registered routes, as `METHOD /path`. */
-  list(): string[]
-}
-
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    http: Http
-  }
-}
-
-/** Provides the `http` router. Nothing listens here: see the `server` plugin. */
-export function http(ctx: Context) {
-  const routes = new Map<string, Handler>()
-  ctx.provide('http', {
-    route(method, path, handler) {
-      const key = `${method.toUpperCase()} ${path}`
-      if (routes.has(key)) throw new Error(`route ${key} is already registered`)
-      routes.set(key, handler)
-      return () => void routes.delete(key)
-    },
-    async handle(request) {
-      const handler = routes.get(`${request.method.toUpperCase()} ${request.path}`)
-      if (!handler) return { status: 404, body: { error: 'not found' } }
-      const reply = await handler(request)
-      return {
-        status: reply.status ?? 200,
-        body: reply.body,
-        ...(reply.stream ? { stream: reply.stream } : {}),
-      }
-    },
-    list: () => [...routes.keys()].sort(),
-  } satisfies Http)
-}

package/plugins/http/plugin.json

@@ -1,10 +0,0 @@
-{
-  "name": "http",
-  "description": "The router service: plugins add routes inside ctx.effect, so a route disappears with the plugin that added it.",
-  "requires": [],
-  "inject": [],
-  "provides": ["http"],
-  "dependencies": {
-    "@deepseek-ai/cordis": "4.0.4"
-  }
-}

package/plugins/server/index.ts

@@ -1,138 +0,0 @@
-import {
-  createServer,
-  type IncomingMessage,
-  type Server as NodeServer,
-  type ServerResponse,
-} from 'node:http'
-import type { AddressInfo } from 'node:net'
-import type { Context } from '@deepseek-ai/cordis'
-import type { Send, Stream } from '../http/index.ts'
-
-/** Where the server listens. Passed as this plugin's Cordis config. */
-export interface ServerConfig {
-  readonly port: number
-  readonly hostname?: string
-  /** Try the next port when this one is taken (up to 20 more). */
-  readonly scan?: boolean
-}
-
-/** The running server, provided once it listens. */
-export interface Server {
-  readonly url: string
-  readonly port: number
-}
-
-declare module '@deepseek-ai/cordis' {
-  interface Context {
-    server: Server
-  }
-}
-
-const SCAN_LIMIT = 20
-
-async function readJson(
-  request: IncomingMessage,
-): Promise<{ ok: true; body: unknown } | { ok: false }> {
-  const chunks: Buffer[] = []
-  for await (const chunk of request) chunks.push(chunk as Buffer)
-  if (chunks.length === 0) return { ok: true, body: undefined }
-  try {
-    return { ok: true, body: JSON.parse(Buffer.concat(chunks).toString('utf8')) }
-  } catch {
-    return { ok: false }
-  }
-}
-
-function listen(listener: NodeServer, port: number, hostname: string): Promise<void> {
-  return new Promise((resolve, reject) => {
-    const onError = (error: Error) => {
-      listener.off('listening', onListening)
-      reject(error)
-    }
-    const onListening = () => {
-      listener.off('error', onError)
-      resolve()
-    }
-    listener.once('error', onError)
-    listener.once('listening', onListening)
-    listener.listen(port, hostname)
-  })
-}
-
-const KEEPALIVE_MS = 15_000
-
-/**
- * Answer with server-sent events. Each event has a rising `id`, a `topic` as its event name and JSON `data`; a comment line every 15 s
- * keeps proxies from closing an idle stream. When the client leaves (or the server stops) the stream's own cleanup runs.
- */
-function openStream(request: IncomingMessage, response: ServerResponse, stream: Stream): void {
-  response.writeHead(200, {
-    'content-type': 'text/event-stream',
-    'cache-control': 'no-cache',
-    connection: 'keep-alive',
-  })
-  response.write(': connected\n\n')
-  let id = 0
-  let open = true
-  const send: Send = (topic, data) => {
-    if (!open) return
-    id += 1
-    response.write(`id: ${id}\nevent: ${topic}\ndata: ${JSON.stringify(data)}\n\n`)
-  }
-  const leave = stream(send)
-  const keepalive = setInterval(() => response.write(': keepalive\n\n'), KEEPALIVE_MS)
-  const close = () => {
-    if (!open) return
-    open = false
-    clearInterval(keepalive)
-    leave()
-  }
-  request.on('close', close)
-  response.on('close', close)
-}
-
-/** Serves the `http` router with Node's own `node:http`. The returned disposer closes the server. */
-export const server = {
-  name: 'server',
-  inject: ['http'],
-  async apply(ctx: Context, config: ServerConfig) {
-    const hostname = config.hostname ?? '127.0.0.1'
-    const listener = createServer(async (request, response) => {
-      const send = (status: number, body: unknown) => {
-        response.writeHead(status, { 'content-type': 'application/json' })
-        response.end(JSON.stringify(body))
-      }
-      try {
-        const parsed = await readJson(request)
-        if (!parsed.ok) return send(400, { error: 'invalid JSON' })
-        const path = new URL(request.url ?? '/', 'http://localhost').pathname
-        const reply = await ctx.http.handle({
-          method: request.method ?? 'GET',
-          path,
-          body: parsed.body,
-        })
-        if (reply.stream) return openStream(request, response, reply.stream)
-        send(reply.status, reply.body)
-      } catch (error) {
-        send(500, { error: error instanceof Error ? error.message : String(error) })
-      }
-    })
-    const attempts = config.scan && config.port !== 0 ? SCAN_LIMIT + 1 : 1
-    for (let attempt = 0; ; attempt++) {
-      try {
-        await listen(listener, config.port + attempt, hostname)
-        break
-      } catch (error) {
-        const inUse = (error as NodeJS.ErrnoException).code === 'EADDRINUSE'
-        if (!inUse || attempt + 1 >= attempts) throw error
-      }
-    }
-    const { port } = listener.address() as AddressInfo
-    ctx.provide('server', { url: `http://${hostname}:${port}`, port } satisfies Server)
-    return () =>
-      new Promise<void>((done) => {
-        listener.close(() => done())
-        listener.closeAllConnections()
-      })
-  },
-}

package/plugins/server/plugin.json

@@ -1,10 +0,0 @@
-{
-  "name": "server",
-  "description": "Serves the http router over node:http; moves to the next free port when asked; closes on stop.",
-  "requires": ["http"],
-  "inject": ["http"],
-  "provides": ["server"],
-  "dependencies": {
-    "@deepseek-ai/cordis": "4.0.4"
-  }
-}

package/templates/app/src/routes.ts

@@ -1,14 +0,0 @@
-import type { Context } from '@deepseek-ai/cordis'
-import type {} from './plugins/http/index.ts'
-
-export const APP_NAME = '__APP_NAME__'
-
-/** The app's own routes. Each one lives in a `ctx.effect`, so it is removed when this plugin is disposed. */
-export const routes = {
-  name: 'routes',
-  inject: ['http'],
-  apply(ctx: Context) {
-    ctx.effect(() => ctx.http.route('GET', '/', () => ({ body: { app: APP_NAME, ok: true } })))
-    ctx.effect(() => ctx.http.route('GET', '/health', () => ({ body: { ok: true } })))
-  },
-}

package/templates/app/template.json

@@ -1 +0,0 @@
-{ "plugins": ["instance", "http", "server", "manifest", "save"] }