acrylblends 0.7.7 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acrylblends",
-  "version": "0.7.7",
+  "version": "0.8.0",
   "description": "The Acryl web framework (import { Acryl } from \"acrylblends\") and the acrylblends command that scaffolds Cordis apps.",
   "license": "MIT",
   "type": "module",
@@ -402,6 +402,10 @@
       "types": "./lib/schema-validator.d.ts",
       "default": "./lib/schema-validator.js"
     },
+    "./read-sse": {
+      "types": "./lib/read-sse.d.ts",
+      "default": "./lib/read-sse.js"
+    },
     "./node-server": {
       "types": "./lib/node-server.d.ts",
       "default": "./lib/node-server.js"

package/plugins/acryl-db/plugin.json

@@ -7,6 +7,11 @@
   "dependencies": {
     "@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"]
+  "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": ["**/*.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": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
+    "commit": "20bdc263d6f0f8febbd967007bda4cf4a802efd2"
   },
   "vendored": [
     "src",
@@ -10,7 +10,7 @@
     "LICENSE"
   ],
   "rewrittenSpecifiers": 0,
-  "digest": "sha256:51e5613457498bfab7c281e0c6443c4f7535401c16520ac44624dc8791a90fa6",
+  "digest": "sha256:656f5bb8468ea1d1f5cef2fc14c4c3d3c8cfa1d85a75cebbf6bc98f1b2d245a7",
   "testsNotRun": {},
   "notice": [
     "LICENSE"

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": "f8e385e4389fe2fdc6fd2a4366a7f2a7389faacb"
+    "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"]
+}

package/plugins/acryl-door/src/cli/acryl.ts

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+/**
+ * The door's operator client: what `<app>/.acryl/bin/acryl` runs. It finds the app from the folder it is started in (the nearest
+ * `.acryl/door.json` upward, or `--dir`), never through PATH or a machine-wide registry, so it reaches only the app running from that
+ * folder. The secret is read from that file and sent as a `Bearer` header; it is never printed.
+ *
+ *   acryl brief | look | act <op> ... | plugin list|add|remove|reload | tool list|call | verbs      (--json for the raw value)
+ *   acryl control <...>   the same, the ACRYL Host form (`control snapshot`, `control click`, ... are look and act)
+ *
+ * Exit codes: 0 done, 1 the verb failed (its code and message are printed), 2 a usage error, 3 no running app in this folder.
+ */
+
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { readDoorFile, STATE_DIR, DOOR_FILE } from '../host/door-file.ts'
+
+const ACT_OPS = new Set(['click', 'type', 'select', 'press', 'scroll', 'wait'])
+const VALUED = new Set(['--dir', '--ref', '--text', '--option', '--key', '--direction', '--amount', '--cursor', '--max-nodes', '--role', '--name', '--timeout-ms', '--tool', '--args'])
+const FLAGS = new Set(['--json', '--submit', '--no-clear', '--gone', '--help'])
+
+export class UsageError extends Error {}
+
+export interface Invocation {
+  readonly verb: string
+  readonly args: Record<string, unknown>
+  readonly json: boolean
+  readonly dir: string | undefined
+}
+
+const USAGE = `usage: acryl <verb> [options] [--json] [--dir <app folder>]
+  brief
+  look [--cursor <n>] [--max-nodes <n>]
+  act click --ref <r>
+  act type --ref <r> --text <t> [--submit] [--no-clear]
+  act select --ref <r> --option <o>
+  act press --key <key> [--ref <r>]
+  act scroll --direction up|down|left|right [--ref <r>] [--amount <px>]
+  act wait (--text <t> | --role <role> [--name <n>]) [--gone] [--timeout-ms <ms>]
+  plugin list | plugin add <folder> | plugin remove <name> | plugin reload
+  tool list | tool call --tool <name> [--args '<json>']
+  verbs`
+
+function integer(values: Map<string, string>, flag: string): number | undefined {
+  const raw = values.get(flag)
+  if (raw === undefined) return undefined
+  const value = Number(raw)
+  if (!Number.isInteger(value) || value < 0) throw new UsageError(`${flag} must be a non-negative integer`)
+  return value
+}
+
+/** @throws UsageError. */
+export function parseInvocation(argv: readonly string[]): Invocation {
+  const words: string[] = []
+  const values = new Map<string, string>()
+  const set = new Set<string>()
+  for (let at = 0; at < argv.length; at += 1) {
+    const arg = argv[at] as string
+    if (VALUED.has(arg)) {
+      const value = argv[at + 1]
+      if (value === undefined) throw new UsageError(`${arg} needs a value`)
+      values.set(arg, value)
+      at += 1
+    } else if (FLAGS.has(arg)) set.add(arg)
+    else if (arg.startsWith('--')) throw new UsageError(`unknown option ${arg}`)
+    else words.push(arg)
+  }
+  if (set.has('--help')) throw new UsageError(USAGE)
+  if (words[0] === 'control') words.shift()
+  // The ACRYL Host form: `control snapshot` is look, `control click` is act click.
+  if (words[0] === 'snapshot') words[0] = 'look'
+  else if (words[0] !== undefined && ACT_OPS.has(words[0])) words.unshift('act')
+  const [first, second, third] = words
+  const json = set.has('--json')
+  const dir = values.get('--dir')
+  const make = (verb: string, args: Record<string, unknown> = {}): Invocation => ({ verb, args, json, dir })
+  switch (first) {
+    case 'brief': return make('brief')
+    case 'verbs': return make('verbs')
+    case 'look': {
+      const cursor = integer(values, '--cursor')
+      const maxNodes = integer(values, '--max-nodes')
+      return make('look', { ...(cursor === undefined ? {} : { cursor }), ...(maxNodes === undefined ? {} : { maxNodes }) })
+    }
+    case 'act': {
+      if (second === undefined || !ACT_OPS.has(second)) throw new UsageError(`act needs one of ${[...ACT_OPS].join(', ')}\n${USAGE}`)
+      const amount = integer(values, '--amount')
+      const timeoutMs = integer(values, '--timeout-ms')
+      const pick = (flag: string, key: string): Record<string, string> => (values.has(flag) ? { [key]: values.get(flag) as string } : {})
+      return make('act', {
+        op: second,
+        ...pick('--ref', 'ref'), ...pick('--text', 'text'), ...pick('--option', 'option'), ...pick('--key', 'key'),
+        ...pick('--direction', 'direction'), ...pick('--role', 'role'), ...pick('--name', 'name'),
+        ...(amount === undefined ? {} : { amount }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(set.has('--submit') ? { submit: true } : {}),
+        ...(set.has('--no-clear') ? { clear: false } : {}),
+        ...(set.has('--gone') ? { gone: true } : {}),
+      })
+    }
+    case 'plugin': {
+      if (second === 'list' || second === 'reload') return make(`plugin-${second}`)
+      if (second === 'add') { if (third === undefined) throw new UsageError('plugin add needs a folder, e.g. plugin add plugins/pomodoro'); return make('plugin-add', { folder: third }) }
+      if (second === 'remove') { if (third === undefined) throw new UsageError('plugin remove needs a plugin name'); return make('plugin-remove', { name: third }) }
+      throw new UsageError(`plugin needs list, add, remove or reload\n${USAGE}`)
+    }
+    case 'tool': {
+      if (second === 'list') return make('tool-list')
+      if (second === 'call') {
+        const tool = values.get('--tool')
+        if (tool === undefined) throw new UsageError('tool call needs --tool <name>')
+        const raw = values.get('--args')
+        let args: unknown = {}
+        if (raw !== undefined) {
+          try { args = JSON.parse(raw) } catch { throw new UsageError('--args must be JSON') }
+        }
+        return make('tool-call', { tool, args })
+      }
+      throw new UsageError(`tool needs list or call\n${USAGE}`)
+    }
+    default: throw new UsageError(USAGE)
+  }
+}
+
+/** The app folder: `--dir`, or the nearest folder upward from `cwd` that has `.acryl/door.json` (or at least `.acryl/`). */
+export function findApp(cwd: string, dir: string | undefined): string | undefined {
+  if (dir !== undefined) return resolve(cwd, dir)
+  let fallback: string | undefined
+  for (let at = resolve(cwd); ; at = dirname(at)) {
+    if (existsSync(join(at, STATE_DIR, DOOR_FILE))) return at
+    if (fallback === undefined && existsSync(join(at, STATE_DIR))) fallback = at
+    if (dirname(at) === at) return fallback
+  }
+}
+
+export interface Io {
+  readonly cwd: string
+  readonly out: (text: string) => void
+  readonly err: (text: string) => void
+  readonly fetch?: typeof fetch
+}
+
+/** Run one invocation. @returns the exit code. */
+export async function main(argv: readonly string[], io: Io): Promise<number> {
+  let invocation: Invocation
+  try {
+    invocation = parseInvocation(argv)
+  } catch (cause) {
+    if (cause instanceof UsageError) { io.err(`${cause.message}\n`); return 2 }
+    throw cause
+  }
+  const app = findApp(io.cwd, invocation.dir)
+  const file = app === undefined ? undefined : readDoorFile(app)
+  if (app === undefined || file === undefined) {
+    io.err(`no running app${app === undefined ? ` in ${io.cwd} or above it` : ` in ${app}`}: start it (npm run dev) in its folder, then try again\n`)
+    return 3
+  }
+  const request = io.fetch ?? fetch
+  const headers = { authorization: `Bearer ${file.secret}`, 'content-type': 'application/json' }
+  let response: Response
+  try {
+    response = invocation.verb === 'verbs'
+      ? await request(`${file.url}/api/acryl-door/verbs`, { headers })
+      : await request(`${file.url}/api/acryl-door/call`, { method: 'POST', headers, body: JSON.stringify({ verb: invocation.verb, args: invocation.args }) })
+  } catch {
+    io.err(`no running app in ${app}: ${file.url} does not answer (it stopped without removing .acryl/door.json?); start it again\n`)
+    return 3
+  }
+  if (response.status === 403) {
+    io.err(`refused by the app in ${app}: the secret did not match (the app restarted? run the command again)\n`)
+    return 1
+  }
+  const body = await response.json().catch(() => undefined) as { ok?: boolean; value?: unknown; text?: string; code?: string; message?: string; verbs?: unknown } | undefined
+  if (body === undefined) { io.err(`the app answered ${String(response.status)} with no readable body\n`); return 1 }
+  if (invocation.verb === 'verbs') {
+    io.out(invocation.json ? `${JSON.stringify(body.verbs)}\n` : `${(body.verbs as string[]).join('\n')}\n`)
+    return 0
+  }
+  if (body.ok !== true) {
+    io.err(invocation.json ? `${JSON.stringify(body)}\n` : `${body.code ?? 'error'}: ${body.message ?? JSON.stringify(body)}\n`)
+    return 1
+  }
+  io.out(invocation.json ? `${JSON.stringify(body.value)}\n` : `${body.text ?? ''}\n`)
+  return 0
+}
+
+/** True when this file is the program Node was started with (not imported by a test). */
+function isProgram(): boolean {
+  const entry = process.argv[1]
+  if (entry === undefined) return false
+  try {
+    return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url))
+  } catch {
+    return false
+  }
+}
+
+if (isProgram()) {
+  main(process.argv.slice(2), {
+    cwd: process.cwd(),
+    out: (text) => { process.stdout.write(text) },
+    err: (text) => { process.stderr.write(text) },
+  }).then((code) => { process.exitCode = code }, (cause: unknown) => {
+    process.stderr.write(`${cause instanceof Error ? cause.message : String(cause)}\n`)
+    process.exitCode = 1
+  })
+}

package/plugins/acryl-door/src/host/api.ts

@@ -0,0 +1,9 @@
+/**
+ * The door's host core for another Host to build its own door on (`acryl-door/host`): the page channel and its routes, and the audit log.
+ * ACRYL's DSH Host uses it in `acryl-agent-control`, with its own tools, approval and secret.
+ */
+
+export { UiChannel, type PageStream } from './channel.ts'
+export { AuditLog, auditPath, type AuditEntry } from './audit.ts'
+export { HEARTBEAT_MS, pageChannelRoutes, type PageRoutesOptions } from './page-routes.ts'
+export { renderSnapshot } from '../page/snapshot-text.ts'

package/plugins/acryl-door/src/host/audit.ts

@@ -0,0 +1,64 @@
+/**
+ * The audit log: one JSON line per door call, append-only, in the app's own `.acryl/audit/` (moved from `acryl-agent-control`, spec 041).
+ *
+ * It is the record of what the agent did to the app. It never holds text the agent typed or values it read,
+ * only which control was touched and how the call ended.
+ */
+
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, statSync, writeSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import type { AuditEntry } from '../page/protocol.ts'
+
+export type { AuditEntry } from '../page/protocol.ts'
+
+const MAX_LOG_BYTES = 5 * 1024 * 1024
+
+/** The audit log below a folder the caller owns (the app's `.acryl/` here; ACRYL's app home for the DSH face). */
+export function auditPath(folder: string): string {
+  return join(folder, 'audit', 'ui-control.jsonl')
+}
+
+export class AuditLog {
+  private readonly path: string
+
+  constructor(path: string) {
+    this.path = path
+  }
+
+  /** Append one line; a failing disk never breaks the tool call. */
+  record(entry: AuditEntry): void {
+    try {
+      mkdirSync(dirname(this.path), { recursive: true })
+      this.rotateIfLarge()
+      const fd = openSync(this.path, 'a', 0o600)
+      try {
+        writeSync(fd, `${JSON.stringify(entry)}\n`)
+      } finally {
+        closeSync(fd)
+      }
+    } catch {
+      // Best effort: the record is important, but the app must keep working.
+    }
+  }
+
+  /** The most recent entries, oldest first. */
+  recent(limit = 100): AuditEntry[] {
+    try {
+      const lines = readFileSync(this.path, 'utf8').split('\n').filter(line => line !== '').slice(-limit)
+      return lines.flatMap((line) => {
+        try { return [JSON.parse(line) as AuditEntry] } catch { return [] }
+      })
+    } catch {
+      return []
+    }
+  }
+
+  private rotateIfLarge(): void {
+    try {
+      if (statSync(this.path).size >= MAX_LOG_BYTES) renameSync(this.path, `${this.path}.1`)
+    } catch {
+      // Nothing to rotate yet.
+    }
+  }
+}
+