acrylblends 1.1.0 → 1.2.0

package/plugins/driver-pty/index.ts

@@ -5,6 +5,8 @@
  * - The drivers are `terminal` entries of the panel's `drivers` service (`pty:claude`, ...). A panel without this plugin lists none; this plugin without a panel is pending.
  * - Transport is server-sent events down and POST up (no WebSocket): `POST /api/driver-pty/sessions`, `GET /api/driver-pty/<id>/output` (events with ids; a reconnect replays
  *   from `Last-Event-ID`, from a ring buffer of at least 64 KB), `POST .../input`, `.../resize`, `.../stop`. Same origin check and token as the panel, development only.
+ * - The routes live under the app's mount, like the panel's: `/api/driver-pty` on the app's own server, `<mount>/api/driver-pty` when a host serves the app at a prefix
+ *   (the frame's `/app`). The row's `mount` config names it, and each driver carries its view (`view: { module, prefix }`) so the panel calls the mounted paths.
  * - Every process is acquired inside one `ctx.effect`; its disposer ends the process (group), closes the streams and writes the audit line. Unloading or reloading the
  *   plugin with a session open leaves no process behind.
  */
@@ -16,8 +18,9 @@ import { streamSSE } from '../acryl-router/src/helpers/index.ts'
 import { Acryl } from '../acryl-router/src/index.ts'
 import type { TerminalDriver, TerminalSession } from '../agent-panel/drivers.ts'
 import { onPath } from '../agent-panel/headless.ts'
+import { mountedBase, mountedPrefix } from '../agent-panel/mount.ts'
 import type {} from '../agent-panel/registry.ts'
-import { loadNodePty, type PtySpawn } from './spawn.ts'
+import { loadNodePty, type PtySpawn, resolveProgram } from './spawn.ts'
 import { terminalDriver } from './terminal.ts'
 
 export const name = 'driver-pty'
@@ -26,7 +29,7 @@ export const inject = ['drivers', 'router', 'appInstance']
 export type { PtyProcess, PtySpawn } from './spawn.ts'
 export { terminalDriver } from './terminal.ts'
 
-const PREFIX = '/api/driver-pty'
+const DRIVER_PATH = '/api/driver-pty'
 const CLIENT_DIR = join(import.meta.dirname, 'client')
 /** The least output a reconnecting page can be given again. */
 const SCROLLBACK = 64 * 1024
@@ -36,6 +39,11 @@ export interface DriverPtyConfig {
   programs?: Record<string, string[]>
   /** The PTY implementation; default node-pty. Tests give a fake. */
   spawn?: PtySpawn
+  /**
+   * The URL prefix the app is mounted at: empty on the app's own server, `/app` when the ACRYL frame hosts it (the same `mount` the panel takes). The
+   * terminal's routes and its browser view live under it, so the terminal belongs to the app and is served wherever the app is.
+   */
+  mount?: string
 }
 
 interface Chunk {
@@ -61,6 +69,9 @@ interface Live {
 
 export async function apply(ctx: Context, config: DriverPtyConfig = {}): Promise<void> {
   if (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off') return
+  const PREFIX = mountedPrefix(config.mount, DRIVER_PATH, 'driver-pty')
+  // The routes mount at the app's own mount and keep the fixed driver path inside (the frame's router prefixes the mount, not the routes).
+  const MOUNT = mountedBase(config.mount, 'driver-pty')
   const root = ctx.appInstance.root
   let spawn = config.spawn
   if (!spawn) {
@@ -80,7 +91,15 @@ export async function apply(ctx: Context, config: DriverPtyConfig = {}): Promise
       (['claude', 'codex', 'pi'] as const).filter(onPath).map((p) => [p, [] as string[]]),
     )
   for (const [program, args] of Object.entries(programs))
-    ctx.effect(() => ctx.drivers.register(terminalDriver(`pty:${program}`, program, args, spawn)))
+    ctx.effect(() =>
+      ctx.drivers.register(
+        // The name stays the program the app configured; the PTY runs its full path (Windows does not search PATH itself).
+        terminalDriver(`pty:${program}`, resolveProgram(program), args, spawn, {
+          module: `${PREFIX}/client/terminal.ts`,
+          prefix: PREFIX,
+        }),
+      ),
+    )
 
   const auditFile = join(root, '.acryl', 'audit', 'driver-pty.jsonl')
   const audit = (entry: Record<string, unknown>): void => {
@@ -162,8 +181,8 @@ export async function apply(ctx: Context, config: DriverPtyConfig = {}): Promise
   ctx.effect(() => off)
 
   const app = new Acryl()
-    .route(`${PREFIX}/client`, clientModules({ root: CLIENT_DIR }))
-    .post(`${PREFIX}/sessions`, async (c) => {
+    .route(`${DRIVER_PATH}/client`, clientModules({ root: CLIENT_DIR, mount: `${PREFIX}/client` }))
+    .post(`${DRIVER_PATH}/sessions`, async (c) => {
       if (!ctx.drivers.authorized(c.req.raw.headers)) return refuse(c)
       const body = (await c.req.json().catch(() => ({}))) as {
         driver?: unknown
@@ -177,10 +196,18 @@ export async function apply(ctx: Context, config: DriverPtyConfig = {}): Promise
         return c.json({ error: 'a terminal is already open; stop it first' }, 409)
       const num = (value: unknown, fallback: number) =>
         typeof value === 'number' && value >= 1 && value <= 1000 ? Math.floor(value) : fallback
-      live = startSession(driver, num(body.cols, 80), num(body.rows, 24))
+      let session: Live
+      try {
+        session = startSession(driver, num(body.cols, 80), num(body.rows, 24))
+      } catch (error) {
+        // The cause (a native module that cannot spawn, a program that is gone) goes to the app's log; the page gets a plain answer, as everywhere else.
+        console.error('driver-pty: the terminal could not start:', error)
+        return c.json({ error: 'the terminal could not start; the app log has the reason' }, 500)
+      }
+      live = session
       return c.json({ id: live.id })
     })
-    .get(`${PREFIX}/:id/output`, (c) => {
+    .get(`${DRIVER_PATH}/:id/output`, (c) => {
       if (!ctx.drivers.authorized(c.req.raw.headers)) return refuse(c)
       const current = find(c.req.param('id'))
       if (!current) return c.json({ error: 'no such terminal' }, 404)
@@ -216,7 +243,7 @@ export async function apply(ctx: Context, config: DriverPtyConfig = {}): Promise
         })
       })
     })
-    .post(`${PREFIX}/:id/input`, async (c) => {
+    .post(`${DRIVER_PATH}/:id/input`, async (c) => {
       if (!ctx.drivers.authorized(c.req.raw.headers)) return refuse(c)
       const current = find(c.req.param('id'))
       if (!current || current.exit) return c.json({ error: 'no such terminal' }, 404)
@@ -226,7 +253,7 @@ export async function apply(ctx: Context, config: DriverPtyConfig = {}): Promise
       current.session.write(data)
       return c.json({ ok: true })
     })
-    .post(`${PREFIX}/:id/resize`, async (c) => {
+    .post(`${DRIVER_PATH}/:id/resize`, async (c) => {
       if (!ctx.drivers.authorized(c.req.raw.headers)) return refuse(c)
       const current = find(c.req.param('id'))
       if (!current || current.exit) return c.json({ error: 'no such terminal' }, 404)
@@ -239,12 +266,12 @@ export async function apply(ctx: Context, config: DriverPtyConfig = {}): Promise
       current.session.resize(cols, rows)
       return c.json({ ok: true })
     })
-    .post(`${PREFIX}/:id/stop`, async (c) => {
+    .post(`${DRIVER_PATH}/:id/stop`, async (c) => {
       if (!ctx.drivers.authorized(c.req.raw.headers)) return refuse(c)
       const current = find(c.req.param('id'))
       if (!current) return c.json({ error: 'no such terminal' }, 404)
       await current.dispose()
       return c.json({ ok: true })
     })
-  ctx.router.route('/', app)
+  ctx.router.route(MOUNT === '' ? '/' : MOUNT, app)
 }

package/plugins/driver-pty/spawn.ts

@@ -1,4 +1,6 @@
 /** The one place that touches `node-pty`, a native module. Everything else works on this small seam, so tests run on a fake process. */
+import { statSync } from 'node:fs'
+import { delimiter, join } from 'node:path'
 
 export interface PtyProcess {
   readonly pid: number
@@ -16,6 +18,42 @@ export type PtySpawn = (
   options: { cwd: string; env: NodeJS.ProcessEnv; cols: number; rows: number },
 ) => PtyProcess
 
+/**
+ * The file a terminal runs: a full path. On Windows node-pty runs the file as it is given and does not search PATH - a bare `node` is "File not found" - so
+ * a bare program name is looked up once, with the platform's PATH separator and, on Windows, PATHEXT. A name that is not found comes back unchanged, and
+ * the start fails with the PTY's own error.
+ */
+export function resolveProgram(
+  program: string,
+  env: NodeJS.ProcessEnv = process.env,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  if (program === '' || program.includes('/') || (platform === 'win32' && program.includes('\\')))
+    return program
+  const windows = platform === 'win32'
+  const folders = (env.PATH ?? env.Path ?? '').split(windows ? ';' : delimiter)
+  const lower = program.toLowerCase()
+  const known = (env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+  const suffixes = !windows
+    ? ['']
+    : known.some((extension) => lower.endsWith(extension.toLowerCase()))
+      ? ['']
+      : ['', ...new Set(known)]
+  for (const folder of folders) {
+    if (folder === '') continue
+    for (const suffix of suffixes) {
+      const candidate = join(folder, `${program}${suffix}`)
+      try {
+        const stat = statSync(candidate)
+        if (stat.isFile() && (windows || (stat.mode & 0o111) !== 0)) return candidate
+      } catch {
+        // Not here: the next folder, or the next extension.
+      }
+    }
+  }
+  return program
+}
+
 /** Loads node-pty. Rejects with the reason (the error and the platform), so a log says why the driver is not offered. */
 export async function loadNodePty(): Promise<PtySpawn> {
   try {

package/plugins/driver-pty/terminal.ts

@@ -22,10 +22,12 @@ export function terminalDriver(
   program: string,
   args: string[],
   spawn: PtySpawn,
+  view: TerminalDriver['view'],
 ): TerminalDriver {
   return {
     kind: 'terminal',
     name,
+    view,
     start({ cwd, env, cols, rows }): TerminalSession {
       // The agent runs `acryl look` without the folder prefix.
       const path = [join(cwd, '.acryl', 'bin'), env.PATH].filter(Boolean).join(delimiter)

package/plugins/extensions/index.ts

@@ -83,6 +83,16 @@ export interface ExtensionsConfig {
   readOnly?: boolean
   /** Where the read-only start says what it did (the console by default). */
   log?: (line: string) => void
+  /**
+   * Plugins of the sources that are switched off (Settings → Plugins writes this list into `blend.yaml`): they are not started, in development or
+   * production, until taken off the list. Their folders stay as they are.
+   */
+  off?: readonly string[]
+  /**
+   * Plugins of the sources that `blend.yaml` mounts as rows of their own (the app composes them in its row order, with their row's config): they
+   * are not extensions, so they are neither found nor started here, and installing one is refused with that reason.
+   */
+  rows?: readonly string[]
 }
 
 const READ_ONLY =
@@ -227,6 +237,8 @@ export class Extensions extends Service {
   private tail: Promise<unknown> = Promise.resolve()
   private disposed = false
   private readonly readOnly: boolean
+  private readonly off: ReadonlySet<string>
+  private readonly rows: ReadonlySet<string>
   private readonly say: (line: string) => void
   /**
    * The context the service was constructed with. Inside a service method `this.ctx` is Cordis's shadow context, which resolves services as the
@@ -238,6 +250,8 @@ export class Extensions extends Service {
     super(ctx, 'extensions')
     this.owner = ctx
     this.readOnly = config.readOnly === true
+    this.off = new Set(config.off ?? [])
+    this.rows = new Set(config.rows ?? [])
     this.say = config.log ?? ((line) => console.log(line))
     const { home, root } = ctx.appInstance
     this.sources = (config.sources ?? [{ dir: join(home, 'extensions'), trust: 'install' }]).map(
@@ -258,8 +272,9 @@ export class Extensions extends Service {
       )
     ctx.effect(
       () => async () => {
+        // A fiber already being disposed (an app reload) can return nothing here, not a promise.
         for (const entry of [...this.installed.values()].reverse())
-          await entry.fiber.dispose().catch(() => undefined)
+          await Promise.resolve(entry.fiber.dispose()).catch(() => undefined)
         this.installed.clear()
       },
       'extensions: dispose mounted extensions',
@@ -417,6 +432,8 @@ export class Extensions extends Service {
           entry.isDirectory() &&
           NAME.test(entry.name) &&
           !library.has(entry.name) &&
+          !this.off.has(entry.name) &&
+          !this.rows.has(entry.name) &&
           ENTRIES.some((file) => existsSync(join(dir, file)))
         ) {
           if (!found.some((other) => other.name === entry.name))
@@ -442,6 +459,10 @@ export class Extensions extends Service {
       errors.push(
         `the folder name "${name}" must be lowercase letters, digits and dashes; it is the extension's name`,
       )
+    if (this.rows.has(name))
+      errors.push(
+        `"${name}" is a row of blend.yaml, so the app starts it, in its row order and with its row's config; it is not installed here. Change its folder and the running app loads it again (npm run dev); npm test checks it`,
+      )
     if (!existsSync(dir) || !statSync(dir).isDirectory()) errors.push(`"${dir}" is not a folder`)
     else if (!ENTRIES.some((file) => existsSync(join(dir, file))))
       errors.push(`"${dir}" has no ${ENTRIES.join(', ')}`)
@@ -788,6 +809,10 @@ export class Extensions extends Service {
       summary.failed.push({ name: 'extensions.json', error: message(error) })
     }
     for (const [name, record] of Object.entries(records)) {
+      // Switched off: not started, and dropped from the record; switched on again, its folder is found and installed as new.
+      if (this.off.has(name)) continue
+      // Now a row of blend.yaml: the app starts it, and the record of its install is dropped.
+      if (this.rows.has(name)) continue
       try {
         // What was installed before was approved then: an unchanged source starts again without asking.
         this.approved.set(name, record.version)

package/plugins/extensions/resolve.ts

@@ -101,6 +101,19 @@ export function routerAliases(): Record<string, string> {
     // outside the app folder, where Node would not find that entry.
     aliases[folder.name] ??= entry
     aliases[`#${folder.name}`] = entry
+    // Its other top-level modules by subpath, as its package exports them (`acryl-node-server/client-modules`): the door imports one before any extension is installed.
+    for (const file of readdirSync(fileURLToPath(new URL(`${folder.name}/src/`, plugins)))) {
+      if (
+        !file.endsWith('.ts') ||
+        file === 'index.ts' ||
+        file.endsWith('.test.ts') ||
+        file.endsWith('.d.ts')
+      )
+        continue
+      aliases[`${folder.name}/${file.slice(0, -3)}`] ??= fileURLToPath(
+        new URL(`${folder.name}/src/${file}`, plugins),
+      )
+    }
     const suite = fileURLToPath(new URL(`${folder.name}/src/conformance.ts`, plugins))
     if (existsSync(suite)) aliases[`#${folder.name}/conformance`] = suite
   }

package/plugins/feedback/client.d.ts

@@ -0,0 +1,22 @@
+// Types for the browser client served as-is (client.js): the Host reads it as text and appends its start call; tests import the exported helpers.
+
+/** The ACRYL frame's view handle, or undefined when the page is not in the frame's canvas. */
+export function frameViewOf(win: {
+  readonly parent: unknown
+}): { readonly mode: 'build' | 'preview' } | undefined
+
+/** A short name for a picked element: what it says it is, else its heading, else the first words it shows, else its tag. */
+export function elementLabel(element: Element): string
+
+/** The stored size of a screenshot: the whole view, downscaled to `maxSide`. */
+export function shotSize(
+  width: number,
+  height: number,
+  maxSide?: number,
+): { width: number; height: number }
+
+/** The largest screenshot the page sends (decoded bytes); the Host refuses more than 512 KB. */
+export const SHOT_MAX_BYTES: number
+
+/** Whether this browser can capture the current tab (Chromium only; Firefox and Safari would offer the whole screen). */
+export function canCaptureTab(userAgent: string, hasDisplayCapture: boolean): boolean