acrylblends 0.7.8 → 0.8.1

package/docs/framework/guides/bring-your-own-tool.md

@@ -0,0 +1,216 @@
+# Bring your own tool: a provider of a port
+
+Every choice in an app is a plugin behind a port, and what the app starts with is only a fallback. Any outside npm tool (a database, a store, a renderer, an auth library) joins the
+app as another **provider** of the same port: a plugin that implements the port's interface on top of the tool and provides the service by its name. The code that uses the port
+does not change. The port's **conformance suite** decides whether your provider is accepted, whoever wrote it. And because Cordis finds services by name, the app can swap the
+provider **while it runs**: the plugins that use the port wait, and carry on when the new provider arrives. A person does it, or an agent working in the app folder, through the door.
+
+This page does it once, from start to end, with a real tool: [lowdb](https://github.com/typicode/lowdb), a small JSON-file database, becomes a provider of the `kv` port ([Data](data.md#a-tiny-app-kv)).
+Every step runs as written: the code on this page is extracted and run against a fresh app by `scripts/verify-byo-tool.mjs`.
+
+You need an app with the `extensions` plugin, which installs plugins while the app runs: `npx acrylblends init my-app --template agent`, then `cd my-app` and `npm install`.
+
+## 1. Bring the port, its suite and a way to run it
+
+```sh
+npx acrylblends add kv --suite
+npm install
+```
+
+`add kv` copies the port (`plugins/acryl-kv`) and the JSON-file provider (`plugins/acryl-kv-json`) and gives your plugins the names `#acryl-kv` and `#acryl-kv-json` (entries in `package.json` "imports").
+`--suite` also copies the port's conformance suite (`#acryl-kv/conformance`) and adds `vitest`, which runs it. The same works for the `db` port: `npx acrylblends add db --suite`.
+
+## 2. Install the tool
+
+```sh
+npm install lowdb
+```
+
+## 3. Write the provider
+
+A provider is a folder in `plugins/` with an `index.ts` that exports `name`, and `apply(ctx)` which provides the service. Keep the tool behind a plain function that returns the port's interface (`openKv`
+here), so tests and plain code use it without Cordis, and let `apply` be a thin wrapper that provides it for as long as the plugin runs.
+
+The port gives you the checks every provider must make alike (`checkKey`, `encodeValue`, `decodeValue`, `runChange`, `compareKeys`), so a bad call fails the same way on a file, on SQL and on your tool.
+
+```ts no-check
+// plugins/kv-lowdb/index.ts
+import { join } from 'node:path'
+import type { Context } from '@deepseek-ai/cordis'
+import { checkKey, compareKeys, decodeValue, encodeValue, KV_SERVICE, runChange } from '#acryl-kv'
+import type { Kv, KvOpened } from '#acryl-kv'
+import { Low } from 'lowdb'
+import { JSONFile } from 'lowdb/node'
+
+/** The kv port on lowdb: one JSON file, written atomically by lowdb after every change. */
+export async function openKv({ path }: { path: string }): Promise<KvOpened> {
+  const db = new Low<Record<string, unknown>>(new JSONFile(path), {})
+  await db.read()
+  // One call at a time, in order: that is what makes `update` atomic and lets `close` wait for the writes in flight.
+  let queue: Promise<unknown> = Promise.resolve()
+  let closed = false
+  const run = <T>(work: () => Promise<T>): Promise<T> => {
+    if (closed) return Promise.reject(new Error('the kv store is closed'))
+    const result = queue.then(work)
+    queue = result.catch(() => {})
+    return result
+  }
+  // A copy of the stored value, so changing what `get` returned changes nothing stored.
+  const copy = (key: string): unknown =>
+    key in db.data ? decodeValue(encodeValue(db.data[key])) : undefined
+  const kv: Kv = {
+    get: <T>(key: string) =>
+      run(async () => {
+        checkKey(key)
+        return copy(key) as T | undefined
+      }),
+    set: (key, value) =>
+      run(async () => {
+        checkKey(key)
+        db.data[key] = decodeValue(encodeValue(value))
+        await db.write()
+      }),
+    update: <T>(key: string, change: (current: T | undefined) => T) =>
+      run(async () => {
+        checkKey(key)
+        const next = runChange(change, copy(key) as T | undefined)
+        db.data[key] = decodeValue(encodeValue(next))
+        await db.write()
+        return copy(key) as T
+      }),
+    delete: (key) =>
+      run(async () => {
+        checkKey(key)
+        delete db.data[key]
+        await db.write()
+      }),
+    list: (prefix = '') =>
+      run(async () =>
+        Object.keys(db.data)
+          .filter((key) => key.startsWith(prefix))
+          .sort(compareKeys),
+      ),
+  }
+  return {
+    kv,
+    async close() {
+      closed = true
+      await queue
+    },
+  }
+}
+
+export const name = 'kv-lowdb'
+
+/** As a plugin: provide `kv` for as long as the plugin runs; the store closes after `kv` is withdrawn. */
+export async function apply(ctx: Context, config: { path?: string } = {}): Promise<void> {
+  const file = config.path ?? join(ctx.appInstance.home, 'kv-lowdb.json')
+  await ctx.effect(async function* () {
+    const opened = await openKv({ path: file })
+    yield () => opened.close()
+    yield ctx.reflect.provide(KV_SERVICE, opened.kv)
+  }, `kv-lowdb: ${file}`)
+}
+```
+
+(A block whose first line is a path comment is the file of that name.)
+
+## 4. Pass the suite
+
+The suite is the contract: it runs the same cases against every provider. A test gives it a fresh store for each case and a way to reopen the same storage.
+
+```ts no-check
+// test/kv-lowdb.spec.ts
+import { mkdir, mkdtemp } from 'node:fs/promises'
+import { join } from 'node:path'
+import { describeKvConformance, type KvUnderTest } from '#acryl-kv/conformance'
+import { openKv } from '../plugins/kv-lowdb/index.ts'
+
+const underTest = async (path: string): Promise<KvUnderTest> => {
+  const opened = await openKv({ path })
+  return {
+    kv: opened.kv,
+    close: opened.close,
+    reopen: async () => {
+      await opened.close()
+      return underTest(path)
+    },
+  }
+}
+
+// A fresh file per case, in a folder of the project (a sandboxed agent may not write to the system temp folder).
+describeKvConformance('kv-lowdb', async () => {
+  await mkdir('.acrylblends', { recursive: true })
+  return underTest(join(await mkdtemp(join('.acrylblends', 'kv-lowdb-')), 'kv.json'))
+})
+```
+
+```sh
+npx vitest run test/kv-lowdb.spec.ts
+```
+
+All the cases must pass. A failure names the rule that broke (`counts fifty concurrent updates to exactly fifty`, `keeps what was written across close and reopen`, ...): fix the provider, not the test.
+
+## 5. Make the default swappable, and swap
+
+A provider that the app's code mounts at start (a row of `blend.yaml`) is fixed until the next start. To swap while the app runs, install both the default and yours as plugins of the app. A one-line plugin
+names the default:
+
+```ts no-check
+// plugins/kv/index.ts
+export { apply, Config } from '#acryl-kv-json'
+export const name = 'kv'
+```
+
+Start the app and open it in a browser (`npm run dev`). The door is the command `.acryl/bin/acryl` in the app folder:
+
+```sh
+.acryl/bin/acryl plugin add plugins/kv
+```
+
+Any plugin that declares `inject: ['kv']` now has a store. This one counts visits:
+
+```ts no-check
+// plugins/visits/index.ts
+import type { Context } from '@deepseek-ai/cordis'
+import { Acryl } from 'acrylblends'
+import type {} from '#acryl-kv'
+
+export const name = 'visits'
+export const inject = ['router', 'kv']
+
+/** GET /visits counts the visits in the kv store, whichever provider holds it. */
+export function apply(ctx: Context): void {
+  ctx.router.route(
+    '/',
+    new Acryl().get('/visits', async (c) =>
+      c.json({ visits: await ctx.kv.update<number>('visits', (n) => (n ?? 0) + 1) }),
+    ),
+  )
+}
+```
+
+```sh
+.acryl/bin/acryl plugin add plugins/visits
+curl <the address npm run dev printed>/visits       # {"visits":1}, then 2, then 3
+```
+
+Now swap. Two providers of one service cannot run together (the second is refused and nothing changes), so take the default out and put yours in:
+
+```sh
+.acryl/bin/acryl plugin remove kv
+.acryl/bin/acryl plugin list            # visits: pending, missing kv
+.acryl/bin/acryl plugin add plugins/kv-lowdb
+curl <the address>/visits       # {"visits":1}: served again, by the same process
+```
+
+`visits` was never edited. While no provider existed its route was gone and its state was `pending`; the moment `kv-lowdb` provided `kv` it started again. The process did not restart, and the swap survives a
+restart: the app remembers what was installed.
+
+## What to know
+
+- **Data does not move by itself.** The new store starts empty (the visits counted from 1 again). To carry it over, copy before you swap, in a script or a plugin: `copyKv(source, target)` from `#acryl-kv` copies one store into another.
+- **A failed install changes nothing.** A provider that throws on start, or that cannot import something, is refused and the previous state stays. To go back: `plugin remove kv-lowdb`, then `plugin add plugins/kv`.
+- **The suite checks the port, not your tool.** It cannot know that lowdb loses a write on a power cut. Read what the tool promises about durability before you trust it with more than a demo.
+- **Other ports and tools work the same way.** `db`: `npx acrylblends add db --suite`, wrap a driver or an ORM behind `Db`, pass `describeDbConformance`. Keep the opener rule ([Data](data.md#why-the-database-is-opened-in-one-place)): only the file that mounts the provider imports the tool.
+- **An agent can do all of it.** Give a coding agent in the app folder the page and one line: "wrap `<package>` as a provider of the `kv` port, pass its suite, and swap it in through the door". `AGENTS.md` in the app names the door.

package/docs/framework/guides/create-acrylblends.md

@@ -7,13 +7,14 @@
 
 | Template | What you get |
 | --- | --- |
-| `nodejs` | an Acryl application served with `serve()` from `acrylblends/node-server`; run with Node.js 22.19 or newer |
+| `nodejs` | a web app: routes, a server-rendered JSX page and a client component, mounted by the app's own plugin; run with Node.js 22.19 or newer |
 | `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite through the [`db` port](data.md) with numbered migrations, validated forms, search, a JSON API with a typed test client, csrf, a test for every route, a client-component counter |
 | `chat` | an AI chat starter: the answer streams token by token from an OpenAI-compatible API (DeepSeek by default, key only from `DEEPSEEK_API_KEY`), a client component with a Stop button that also stops the request to the model, history in SQLite through the [`db` port](data.md), tests with a mock model |
-| `bun` (experimental) | an Acryl application with `export default app`, run with `bun` |
 | `acryl-app` | a Cordis app built from plugins, with an agent that can extend it while it runs (the same app `npx acrylblends init --template agent` creates) |
 
-Every template includes `AGENTS.md` and `CLAUDE.md` (which imports `AGENTS.md`) and a copy of these docs in `docs/framework/`, so a coding agent working in the folder reads the
+Every template is a Cordis app: `blend.yaml` lists the plugins that are mounted, every plugin is a folder in `plugins/`, and the app is started by `src/main.ts`. A bare template name after the directory is the same as `--template`: `npm create acrylblends@latest my-app notes`. `bun` is no longer a template; the framework still runs on Bun (see [Bun](../getting-started/bun.md)), but a new app is a Cordis app on Node.
+
+Every template includes `AGENTS.md` and `CLAUDE.md` (the same text), one skill (`app-guide`) in `.claude/skills/` and `.agents/skills/`, and a copy of these docs in `docs/framework/`, so a coding agent working in the folder reads the
 API from the folder.
 
 ## Passing arguments
@@ -50,7 +51,7 @@ bun create acrylblends@latest my-app --template nodejs
 | :-- | :-- | :-- |
 | `[directory]` | The folder to create. It must not exist or must be empty. Asked for when it is missing. | `my-app` |
 | `[source]` | A template from outside the package: `github:owner/repo[#ref]`, `@scope/name[@version]` or a packed `.tgz` file. See [Templates from a repository or a package](#templates-from-a-repository-or-a-package). | `github:acme/starter` |
-| `--template <template>` | One of `nodejs`, `notes`, `chat`, `bun` (experimental), `acryl-app`. Skips the template question. | `--template bun` |
+| `--template <template>` | One of `nodejs`, `notes`, `chat`, `acryl-app`. Skips the template question; a bare name after the directory means the same. | `--template notes` |
 | `--install` | Install the dependencies with the package manager after creating the project. For a template from a source, the install scripts it will run are listed first. | `--install` |
 | `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
 | `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |

package/docs/framework/guides/data.md

@@ -10,6 +10,7 @@ interface; it is not part of `acrylblends` or the templates, and an app adds it
 | The app | Use | State |
 | --- | --- | --- |
 | Normal web or desktop app, users, lists, orders | `db` with SQLite (the `notes` and `chat` templates) | available |
+| SQLite is not enough, but no server | `db` with the optional `acryl-db-pglite` plugin: Postgres in the app's process, one folder in the app home | optional, not in `acrylblends` |
 | Must use Postgres or Supabase | `db` with the optional `acryl-db-postgres` plugin | optional, not in `acrylblends` |
 | Tiny, one person, a few screens | [`kv`](#a-tiny-app-kv), named JSON documents with no SQL | available |
 
@@ -190,7 +191,7 @@ await db.transaction(async (tx) => {
 
 ## Writing SQL that moves to Postgres
 
-The optional Postgres plugin serves the same interface. SQL that stays inside this list runs on both:
+The optional Postgres plugins (`acryl-db-pglite` embedded, `acryl-db-postgres` on a server) serve the same interface. SQL that stays inside this list runs on both:
 
 - Placeholders are `?` on every provider.
 - Use `RETURNING` to get a new row, not a driver-specific "last id".

package/docs/framework/upstream.json

@@ -2,8 +2,8 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "docs/framework",
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
-  "files": 99,
-  "digest": "sha256:9b0fe3329319398ce1108a015a99247c001b02cfb30a953b4b180a73674e2aec"
+  "files": 100,
+  "digest": "sha256:ab5a055bc0bfb6c47ee6bb70c72ef6ec675ad070d790b58e601cd764591df788"
 }

package/lib/node-server.js

@@ -835,6 +835,7 @@ const drainIncoming = (incoming) => {
 		bytesRead += chunk.length;
 		if (bytesRead > MAX_DRAIN_BYTES) forceClose();
 	};
+	incoming.removeAllListeners("data");
 	incoming.on("data", onData);
 	incoming.on("end", cleanup);
 	incoming.on("error", cleanup);

package/package.json

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

package/plugins/acryl-db/plugin.json

@@ -8,5 +8,10 @@
     "@deepseek-ai/cordis": "4.0.4"
   },
   "mount": "it is the port, not a service: a plugin declares inject: ['db'] and imports its types from '../plugins/acryl-db/src/index.ts' (or the ctx.db type from '../plugins/acryl-db/src/cordis.ts'); add acryl-db-sqlite to provide it",
-  "omit": ["src/conformance.ts", "**/*.test.*", "**/*.case.ts"]
+  "omit": ["**/*.test.*", "**/*.case.ts"],
+  "imports": {
+    "#acryl-db": "acryl-db/src/index.ts",
+    "#acryl-db/conformance": "acryl-db/src/conformance.ts"
+  },
+  "suite": "src/conformance.ts"
 }

package/plugins/acryl-db/src/conformance.ts

@@ -0,0 +1,224 @@
+/**
+ * The `db` conformance suite: what every provider of the port must do, as Vitest tests. A provider passes it to be accepted
+ * (`describeDbConformance('acryl-db-sqlite', open)` in its own tests); the SQL is the portable subset, with `?` bindings, so the same
+ * suite runs unchanged on SQLite and Postgres.
+ *
+ * A `?` inside a string literal, a quoted identifier or a comment is text, not a binding. Foreign keys are enforced (`ON DELETE CASCADE` works) and `INSERT ... RETURNING` answers through `get`, on every provider.
+ *
+ * The transaction cases are the contract the SQL facade documents (and its SQLite tests check): other calls and transactions wait for
+ * an active transaction, a rejected callback rolls back and rejects with its own error, and a handle is dead once its transaction settles.
+ */
+
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import type { Db, DbExecutor } from './facade/database.ts'
+import { applyMigrations } from './facade/migrations.ts'
+import { readMigrationFiles } from './migration-files.ts'
+import { MIGRATIONS_TABLE } from './index.ts'
+
+/** A fresh, empty database from the provider under test, and how to close it. */
+export interface DbUnderTest {
+  readonly db: Db
+  close(): Promise<void>
+}
+
+/** A promise and the function that settles it, for holding a transaction open. */
+function gate(): { readonly promise: Promise<void>, readonly open: () => void } {
+  let open!: () => void
+  const promise = new Promise<void>(resolve => { open = resolve })
+  return { promise, open }
+}
+
+export function describeDbConformance(provider: string, open: () => Promise<DbUnderTest>): void {
+  describe(`db conformance: ${provider}`, () => {
+    const opened: DbUnderTest[] = []
+    const fresh = async (): Promise<Db> => {
+      const subject = await open()
+      opened.push(subject)
+      return subject.db
+    }
+    afterEach(async () => {
+      await Promise.all(opened.splice(0).map(subject => subject.close()))
+    })
+
+    it('round-trips null, integers, bigints in the safe range, reals, text and bytes', async () => {
+      const db = await fresh()
+      await db.exec('CREATE TABLE value_probe (n INTEGER, i INTEGER, b BIGINT, r DOUBLE PRECISION, t TEXT, x BYTEA)')
+      const bytes = new Uint8Array([0, 1, 254, 255])
+      await db.run('INSERT INTO value_probe (n, i, b, r, t, x) VALUES (?, ?, ?, ?, ?, ?)', null, 42, 9_007_199_254_740_991n, 1.5, 'café ✓', bytes)
+      const row = await db.get<{ n: unknown, i: unknown, b: unknown, r: unknown, t: unknown, x: unknown }>('SELECT n, i, b, r, t, x FROM value_probe')
+      expect(row).toEqual({ n: null, i: 42, b: 9_007_199_254_740_991, r: 1.5, t: 'café ✓', x: bytes })
+      expect(row?.x).toBeInstanceOf(Uint8Array)
+    })
+
+    it('answers get with undefined and all with [] when nothing matches', async () => {
+      const db = await fresh()
+      await db.exec('CREATE TABLE empty_probe (value INTEGER)')
+      expect(await db.get('SELECT value FROM empty_probe WHERE value = ?', 1)).toBeUndefined()
+      expect(await db.all('SELECT value FROM empty_probe')).toEqual([])
+    })
+
+    it('reports how many rows run changed', async () => {
+      const db = await fresh()
+      await db.exec('CREATE TABLE change_probe (value INTEGER)')
+      expect(await db.run('INSERT INTO change_probe (value) VALUES (?), (?), (?)', 1, 2, 3)).toEqual({ changes: 3 })
+      expect(await db.run('UPDATE change_probe SET value = value + 10 WHERE value < ?', 3)).toEqual({ changes: 2 })
+      expect(await db.run('DELETE FROM change_probe WHERE value = ?', 99)).toEqual({ changes: 0 })
+    })
+
+    it('runs several statements in one exec', async () => {
+      const db = await fresh()
+      await db.exec('CREATE TABLE multi_probe (value INTEGER); INSERT INTO multi_probe (value) VALUES (1); INSERT INTO multi_probe (value) VALUES (2);')
+      expect(await db.all('SELECT value FROM multi_probe ORDER BY value')).toEqual([{ value: 1 }, { value: 2 }])
+    })
+
+    it('enforces foreign keys: ON DELETE CASCADE removes the children, and an orphan insert is refused', async () => {
+      const db = await fresh()
+      await db.exec('CREATE TABLE fk_parent (id INTEGER PRIMARY KEY); CREATE TABLE fk_child (id INTEGER PRIMARY KEY, parent INTEGER NOT NULL REFERENCES fk_parent (id) ON DELETE CASCADE)')
+      await db.run('INSERT INTO fk_parent (id) VALUES (?), (?)', 1, 2)
+      await db.run('INSERT INTO fk_child (id, parent) VALUES (?, ?), (?, ?), (?, ?)', 10, 1, 11, 1, 20, 2)
+      expect(await db.run('DELETE FROM fk_parent WHERE id = ?', 1)).toEqual({ changes: 1 })
+      expect(await db.all('SELECT id FROM fk_child ORDER BY id')).toEqual([{ id: 20 }])
+      await expect(db.run('INSERT INTO fk_child (id, parent) VALUES (?, ?)', 30, 99)).rejects.toThrow()
+      expect(await db.all('SELECT id FROM fk_child ORDER BY id')).toEqual([{ id: 20 }])
+    })
+
+    it('returns the inserted row through get with INSERT ... RETURNING, inside a transaction too', async () => {
+      const db = await fresh()
+      await db.exec('CREATE TABLE returning_probe (id INTEGER PRIMARY KEY, body TEXT NOT NULL)')
+      expect(await db.get('INSERT INTO returning_probe (id, body) VALUES (?, ?) RETURNING id, body', 1, 'first')).toEqual({ id: 1, body: 'first' })
+      const second = await db.transaction(tx => tx.get<{ id: number }>('INSERT INTO returning_probe (id, body) VALUES (?, ?) RETURNING id', 2, 'second'))
+      expect(second).toEqual({ id: 2 })
+      expect(await db.all('SELECT body FROM returning_probe ORDER BY id')).toEqual([{ body: 'first' }, { body: 'second' }])
+    })
+
+    it('binds only the ? outside string literals, quoted identifiers and comments', async () => {
+      const db = await fresh()
+      expect(await db.get("SELECT '?' AS q, CAST(? AS INTEGER) AS v, 'it''s ?' AS r", 7)).toEqual({ q: '?', v: 7, r: "it's ?" })
+      expect(await db.get('SELECT CAST(? AS INTEGER) AS v /* not ? a binding */, CAST(? AS INTEGER) AS w -- nor ?\n', 1, 2)).toEqual({ v: 1, w: 2 })
+      await db.exec('CREATE TABLE "odd?name" ("col?" INTEGER, body TEXT)')
+      await db.run('INSERT INTO "odd?name" ("col?", body) VALUES (?, \'what?\')', 3)
+      expect(await db.all('SELECT "col?" AS c, body FROM "odd?name" WHERE "col?" = ?', 3)).toEqual([{ c: 3, body: 'what?' }])
+    })
+
+    it('commits work done through the transaction handle and resolves the callback value', async () => {
+      const db = await fresh()
+      const value = await db.transaction(async tx => {
+        await tx.exec('CREATE TABLE commit_probe (value INTEGER)')
+        await tx.run('INSERT INTO commit_probe (value) VALUES (?)', 1)
+        return 'committed'
+      })
+      expect(value).toBe('committed')
+      expect(await db.all('SELECT value FROM commit_probe')).toEqual([{ value: 1 }])
+    })
+
+    it('rolls back when the callback rejects, and rejects with that same error', async () => {
+      const db = await fresh()
+      await db.exec('CREATE TABLE rollback_probe (value INTEGER)')
+      const failure = new Error('roll back')
+      const outcome = db.transaction(async tx => {
+        await tx.run('INSERT INTO rollback_probe (value) VALUES (?)', 1)
+        throw failure
+      })
+      await expect(outcome).rejects.toBe(failure)
+      expect(await db.all('SELECT value FROM rollback_probe')).toEqual([])
+    })
+
+    it('makes other calls and transactions wait for an active transaction, then runs them in call order', async () => {
+      const db = await fresh()
+      await db.exec('CREATE TABLE queue_probe (value INTEGER)')
+      const started = gate()
+      const release = gate()
+      const first = db.transaction(async tx => {
+        await tx.run('INSERT INTO queue_probe (value) VALUES (?)', 1)
+        started.open()
+        await release.promise
+      })
+      await started.promise
+      const settled: string[] = []
+      const write = db.run('INSERT INTO queue_probe (value) VALUES (?)', 2).then(() => { settled.push('write') })
+      const second = db.transaction(async tx => { await tx.run('INSERT INTO queue_probe (value) VALUES (?)', 3) }).then(() => { settled.push('second') })
+      const read = db.all<{ value: number }>('SELECT value FROM queue_probe ORDER BY value').then(rows => { settled.push('read'); return rows })
+      await new Promise(resolve => setTimeout(resolve, 20))
+      expect(settled).toEqual([])
+      release.open()
+      await Promise.all([first, write, second])
+      expect(await read).toEqual([{ value: 1 }, { value: 2 }, { value: 3 }])
+      expect(settled).toEqual(['write', 'second', 'read'])
+    })
+
+    it('keeps a rolled-back transaction from leaking into calls made while it ran', async () => {
+      const db = await fresh()
+      await db.exec('CREATE TABLE isolation_probe (value INTEGER)')
+      const transaction = db.transaction(async tx => {
+        await tx.run('INSERT INTO isolation_probe (value) VALUES (?)', 1)
+        await Promise.resolve()
+        throw new Error('roll back')
+      })
+      const before = db.all('SELECT value FROM isolation_probe')
+      const write = db.run('INSERT INTO isolation_probe (value) VALUES (?)', 2)
+      const after = db.all('SELECT value FROM isolation_probe')
+      await expect(transaction).rejects.toThrow('roll back')
+      await write
+      expect(await before).toEqual([])
+      expect(await after).toEqual([{ value: 2 }])
+    })
+
+    it('rejects a transaction handle used after its transaction settles', async () => {
+      const db = await fresh()
+      await db.exec('CREATE TABLE stale_probe (value INTEGER)')
+      let handle!: DbExecutor
+      await db.transaction(async tx => {
+        handle = tx
+        await tx.run('INSERT INTO stale_probe (value) VALUES (?)', 1)
+      })
+      await expect(handle.run('INSERT INTO stale_probe (value) VALUES (?)', 2)).rejects.toThrow()
+      await expect(handle.get('SELECT value FROM stale_probe')).rejects.toThrow()
+      expect(await db.all('SELECT value FROM stale_probe')).toEqual([{ value: 1 }])
+    })
+
+    it('applies migrations once and in order, and refuses a schema newer than the code', async () => {
+      const db = await fresh()
+      const first = [{ version: 1, statements: ['CREATE TABLE notes (body TEXT)', "INSERT INTO notes (body) VALUES ('kept')"] }]
+      await applyMigrations(db, first, { table: MIGRATIONS_TABLE })
+      await applyMigrations(db, first, { table: MIGRATIONS_TABLE })
+      await applyMigrations(db, [...first, { version: 2, statements: ['ALTER TABLE notes ADD COLUMN title TEXT'] }], { table: MIGRATIONS_TABLE })
+      expect(await db.all('SELECT body, title FROM notes')).toEqual([{ body: 'kept', title: null }])
+      expect(await db.get(`SELECT version FROM ${MIGRATIONS_TABLE}`)).toEqual({ version: 2 })
+      await expect(applyMigrations(db, first, { table: MIGRATIONS_TABLE })).rejects.toThrow('Schema version 2 is newer than supported version 1')
+    })
+
+    it('rolls every pending migration back together when one fails', async () => {
+      const db = await fresh()
+      const failing = [
+        { version: 1, statements: ['CREATE TABLE migration_first (value TEXT)', "INSERT INTO migration_first (value) VALUES ('retained')"] },
+        { version: 2, statements: ['CREATE TABLE migration_second (value TEXT)', 'THIS IS NOT SQL'] },
+      ]
+      await expect(applyMigrations(db, failing, { table: MIGRATIONS_TABLE })).rejects.toThrow()
+      await expect(db.all('SELECT value FROM migration_first')).rejects.toThrow()
+      // A provider may create the version table when it opens; then it still says 0.
+      const version = await db.get<{ version: unknown }>(`SELECT version FROM ${MIGRATIONS_TABLE}`).catch(() => undefined)
+      expect(version === undefined || Number(version.version) === 0).toBe(true)
+      await applyMigrations(db, [failing[0]!, { version: 2, statements: ['CREATE TABLE migration_second (value TEXT)'] }], { table: MIGRATIONS_TABLE })
+      expect(await db.get(`SELECT version FROM ${MIGRATIONS_TABLE}`)).toEqual({ version: 2 })
+      expect(await db.all('SELECT value FROM migration_first')).toEqual([{ value: 'retained' }])
+    })
+
+    it('applies an app\'s numbered migration files', async () => {
+      const db = await fresh()
+      const folder = await mkdtemp(join(tmpdir(), 'acryl-db-migrations-'))
+      try {
+        await writeFile(join(folder, '001-notes.sql'), 'CREATE TABLE notes (id INTEGER PRIMARY KEY, body TEXT NOT NULL);\nINSERT INTO notes (id, body) VALUES (1, \'first\');\n')
+        await writeFile(join(folder, '002-tags.sql'), 'CREATE TABLE tags (note INTEGER NOT NULL, tag TEXT NOT NULL);\n')
+        await applyMigrations(db, await readMigrationFiles(folder), { table: MIGRATIONS_TABLE })
+        await db.run('INSERT INTO tags (note, tag) VALUES (?, ?)', 1, 'todo')
+        expect(await db.all('SELECT body, tag FROM notes JOIN tags ON tags.note = notes.id')).toEqual([{ body: 'first', tag: 'todo' }])
+        expect(await db.get(`SELECT version FROM ${MIGRATIONS_TABLE}`)).toEqual({ version: 2 })
+      } finally {
+        await rm(folder, { recursive: true, force: true })
+      }
+    })
+  })
+}

package/plugins/acryl-db/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-db",
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",

package/plugins/acryl-db-sqlite/plugin.json

@@ -9,5 +9,8 @@
     "@deepseek-ai/schemastery": "3.18.4"
   },
   "mount": "mount it after instance: root.plugin(dbSqlite, { migrations: 'migrations' }) with the migrations/ folder (001-name.sql, ...) next to src/; then a plugin that declares inject: ['db'] calls await ctx.db.all('SELECT ...', value)",
-  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"]
+  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"],
+  "imports": {
+    "#acryl-db-sqlite": "acryl-db-sqlite/src/index.ts"
+  }
 }

package/plugins/acryl-db-sqlite/upstream.json

@@ -2,7 +2,7 @@
   "source": {
     "repo": "acryldev/acryl",
     "path": "plugins/acryl-db-sqlite",
-    "commit": "f132283c43337f5e1d58dfbbbc15786efb5e756c"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",

package/plugins/acryl-door/LICENSE

@@ -0,0 +1,47 @@
+MIT License
+
+Copyright (c) 2026 WebBoxes s.r.o.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The files under src/facade are derived from the SQLite facade of chord in pi (https://github.com/earendil-works/pi, packages/chord, commit d5b3de22d0e24a3e9c38a9410d3329b099717283), used under this license:
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/plugins/acryl-door/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "acryl-door",
+  "description": "The door of the app: an agent working in the app folder looks at the running page, acts on it (click, type, select, press, scroll, wait) and adds, removes or reloads plugins live, through .acryl/bin/acryl. Loopback only, a per-run secret in .acryl/door.json, an audit log and an in-page indicator with a stop button. Vendored from ACRYL.",
+  "requires": ["acryl-router", "acryl-node-server", "instance"],
+  "inject": ["router", "appInstance", "nodeServer"],
+  "provides": ["door"],
+  "dependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/schemastery": "3.18.4"
+  },
+  "mount": "mount it after acryl-node-server and extensions in development builds: root.plugin(door); add <script type=\"module\" src=\"/api/acryl-door/page.js\"></script> to the pages; the command is .acryl/bin/acryl",
+  "gitignore": [".acryl/"],
+  "omit": ["**/*.test.*", "**/*.spec.*", "**/*.case.ts"]
+}