acrylblends 1.3.1 → 1.3.2

package/legacy/todo/164274ffcf7f/src/app.ts

@@ -0,0 +1,145 @@
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { Context, type Fiber } from '@deepseek-ai/cordis'
+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 * as state from '../plugins/acryl-state/src/index.ts'
+import { type AppInstance, instance } from '../plugins/instance/index.ts'
+import {
+  appPluginNames,
+  blueprintsIn,
+  compose,
+  loadAppPlugins,
+  loadManifest,
+  type ParameterValue,
+} from '../plugins/manifest/index.ts'
+import { doorEnabled } from './door.ts'
+import * as todo from './todo.ts'
+import { FRAME_MOUNT_PREFIX } from './todo.ts'
+
+/** The plugins this app's code provides. `blend.yaml` chooses, orders and configures them, and adds the app's own plugins from `plugins/` by name. */
+export const registry = {
+  'acryl-router': router,
+  'acryl-state': state,
+  todo,
+  'acryl-node-server': nodeServer,
+  'acryl-door': door,
+}
+
+export const APP_NAME = '__APP_NAME__'
+
+/** The manifest next to this app's source. */
+export const MANIFEST = join(fileURLToPath(new URL('..', import.meta.url)), 'blend.yaml')
+/** The app's plugins: the library copies `registry` imports, and the app's own plugins (a feature each), which `blend.yaml` mounts by their folder name. */
+const PLUGINS_DIR = join(fileURLToPath(new URL('..', import.meta.url)), 'plugins')
+
+/**
+ * The app's manifest, resolved. A Blend finds its Blueprint in `blueprints/<id>.yaml`; an app that is itself a Blueprint never looks.
+ * `createApp` and the tests read it the same way.
+ */
+export function readManifest(values?: Readonly<Record<string, ParameterValue>>) {
+  return loadManifest(MANIFEST, {
+    known: [...Object.keys(registry), ...appPluginNames(PLUGINS_DIR)],
+    getBlueprint: blueprintsIn(join(fileURLToPath(new URL('..', import.meta.url)), '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 path the app is mounted at; absent on its own server, where it keeps `/todo`, and {@link FRAME_MOUNT_PREFIX} in the frame. */
+  readonly prefix?: 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 rows the frame host provides: the app contributes only the plugins that are its own. */
+const HOST_ROWS = [
+  'instance',
+  'acryl-router',
+  'acryl-node-server',
+  'acryl-web-server',
+  'acryl-page',
+  'manifest',
+  'save',
+  'acryl-door',
+]
+
+/**
+ * The app's rows, composed into `ctx`: the app's own server calls this from `createApp`, and the generated frame layer mounts it as one row, so the frame
+ * runs the app exactly as the app's own server does (same rows, same order, same config). `host: true` leaves the infrastructure rows to the frame host,
+ * which is where the door lives too, and mounts the app at {@link FRAME_MOUNT_PREFIX}.
+ */
+export async function composeInto(
+  ctx: Context,
+  chosen: AppInstance,
+  options: AppOptions & { readonly host?: boolean } = {},
+): Promise<Fiber[]> {
+  const read = readManifest(options.values)
+  const own = options.host !== true && options.listen !== false
+  // The frame host mounts the app under its own prefix; the app's own server keeps the app's old path.
+  const prefix = options.prefix ?? (options.host === true ? FRAME_MOUNT_PREFIX : undefined)
+  const leaveOut = new Set<string>(options.host === true ? HOST_ROWS : [])
+  // The server, and the door that needs it, are not mounted when the app is reached in process or inside the frame host.
+  if (!own) leaveOut.add('acryl-node-server').add('acryl-door')
+  if (!doorEnabled()) leaveOut.add('acryl-door')
+  const manifest = without(read, ...leaveOut)
+  // The rows that name one of the app's own plugin folders (a feature: plugins/<name>/ and its row) rather than a registry import; each one that runs is imported here.
+  const ownRows = [
+    ...new Set(read.plugins.map((row) => row.use).filter((use) => !Object.hasOwn(registry, use))),
+  ]
+  const ownPlugins = await loadAppPlugins(
+    PLUGINS_DIR,
+    ownRows.filter((use) => manifest.plugins.some((row) => row.use === use && !row.disabled)),
+  )
+  return compose(
+    ctx,
+    manifest,
+    { ...registry, ...ownPlugins },
+    {
+      // Runtime values the manifest cannot hold: where the list is kept (in the app's home) and, in the frame, the prefix the app answers at.
+      todo: {
+        file: join(chosen.home, 'todo.json'),
+        ...(prefix === undefined ? {} : { prefix }),
+      },
+      // Only the app's own server listens; the frame host owns the server and its port.
+      ...(own ? { server: { port: chosen.port.start, scan: chosen.port.scan ? 20 : 0 } } : {}),
+    },
+  )
+}
+
+/** The app: `instance` first (where it lives, chosen at run time), then the manifest's rows in order. */
+export async function createApp(chosen: AppInstance, options: AppOptions = {}): Promise<App> {
+  const root = new Context()
+  const first = root.plugin(instance, chosen)
+  await first.await()
+  const fibers: Fiber[] = [first, ...(await composeInto(root, chosen, options))]
+  return {
+    root,
+    url: options.listen === false ? '' : root.nodeServer.url,
+    async stop() {
+      for (const fiber of [...fibers].reverse()) await fiber.dispose()
+    },
+  }
+}

package/legacy/todo/164274ffcf7f/src/todo.ts

@@ -0,0 +1,137 @@
+/**
+ * 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 { Acryl, HTTPException } from '../plugins/acryl-router/src/index.ts'
+import { bodyLimit, loopbackOnly, trimTrailingSlash } 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 { pageHtml } 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']
+
+/**
+ * The only place the app's mount prefix is named: the app answers under `/todo` on its own server (`npm start`), and the ACRYL frame mounts the same app
+ * at `/app` (`npm run dev`). Every URL the page writes is derived from the prefix it is mounted at, so both are served by one source.
+ */
+export const FRAME_MOUNT_PREFIX = '/app'
+
+export interface Todo { id: number, title: string, done: boolean }
+export interface Config {
+  file?: string
+  /**
+   * The path the app is mounted at, and the base of every URL its page writes. `/todo` on the app's own server (and the default); the ACRYL frame passes
+   * `/app` so the same app answers at the frame's app prefix, with nothing else of its URLs moved.
+   */
+  prefix?: 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 prefix = config.prefix ?? '/todo'
+  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
+  }
+
+  // `/todo/` is what people type: trimTrailingSlash answers a GET for an unknown path ending in `/` with a 301 to the path without it,
+  // so the page is found either way while each route keeps one canonical path (the router itself treats `/a` and `/a/` as different).
+  const api = new Acryl()
+    .use(loopbackOnly({ inProcess: 'allow' }), bodyLimit({ maxSize: MAX_BODY_BYTES }), trimTrailingSlash())
+    .get('/', c => c.html(pageHtml(prefix)))
+    .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(prefix === '' ? '/' : prefix, api)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",