acrylblends 1.0.6 → 1.0.8

package/plugins/desktop/window.ts

@@ -1,23 +1,69 @@
 /** The one window of a desktop app: the operating system's frame around a page the app's own server serves, with the renderer locked down. */
-import type { BrowserWindowConstructorOptions } from 'electron'
 
 export interface WindowSpec {
   readonly title: string
   readonly width?: number
   readonly height?: number
+  /** Where the window's top left corner goes; Electron centers the window when these are left out. */
+  readonly x?: number
+  readonly y?: number
+}
+
+export interface Rect {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+/** How far each new window sits from the one it was opened from. */
+export const CASCADE_STEP = 32
+
+/**
+ * Where a new window goes so that it does not cover another one exactly: down and to the right of `from` by one step, and back at the top left of the work area when that would put
+ * it past the edge of the screen (so a row of windows cascades, then starts again).
+ */
+export function cascade(
+  from: Rect,
+  work: Rect,
+  size: { width: number; height: number },
+): { x: number; y: number } {
+  const x = from.x + CASCADE_STEP
+  const y = from.y + CASCADE_STEP
+  const fitsRight = x + size.width <= work.x + work.width
+  const fitsBottom = y + size.height <= work.y + work.height
+  return { x: fitsRight ? x : work.x, y: fitsBottom ? y : work.y }
 }
 
 /**
  * Secure BrowserWindow options. The settings are ACRYL Desktop's: context isolation on, no Node in the page, the sandbox on, web security on; the window stays
  * hidden until the page has painted (`show: false`, shown on `ready-to-show`).
  */
-export function windowOptions(spec: WindowSpec): BrowserWindowConstructorOptions {
+export interface WindowOptions {
+  readonly title: string
+  readonly width: number
+  readonly height: number
+  readonly minWidth: number
+  readonly minHeight: number
+  readonly x?: number
+  readonly y?: number
+  readonly show: boolean
+  readonly webPreferences: {
+    readonly contextIsolation: boolean
+    readonly nodeIntegration: boolean
+    readonly sandbox: boolean
+    readonly webSecurity: boolean
+  }
+}
+
+export function windowOptions(spec: WindowSpec): WindowOptions {
   return {
     title: spec.title,
     width: spec.width ?? 1100,
     height: spec.height ?? 760,
     minWidth: 480,
     minHeight: 360,
+    ...(spec.x === undefined || spec.y === undefined ? {} : { x: spec.x, y: spec.y }),
     show: false,
     webPreferences: {
       contextIsolation: true,

package/plugins/extensions/index.ts

@@ -75,8 +75,19 @@ export interface ExtensionsConfig {
   sources?: readonly ExtensionSource[]
   /** When true, every source that would install by itself asks for approval instead (`ask`). */
   approval?: boolean
+  /**
+   * Production: the extension folders of the sources that install by themselves are started straight from where they are, once, and nothing can be installed, updated or
+   * removed afterwards (those calls are refused). No staging, no state file, no ledger, no approval queue are written or asked: the code that runs is the code in the folder,
+   * as it is deployed. One line says what was started, and a recorded extension whose folder is missing is a warning.
+   */
+  readOnly?: boolean
+  /** Where the read-only start says what it did (the console by default). */
+  log?: (line: string) => void
 }
 
+const READ_ONLY =
+  'the extensions of this app are read-only here (production): nothing can be installed, updated, removed or approved while it runs'
+
 export interface ExtensionInfo {
   readonly name: string
   readonly source: string
@@ -215,6 +226,8 @@ export class Extensions extends Service {
   private readonly requests = new Map<string, { dir: string; version: string }>()
   private tail: Promise<unknown> = Promise.resolve()
   private disposed = false
+  private readonly readOnly: boolean
+  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
    * service's own fiber, so a plugin mounted from it would read `ctx.router` from the installer's fiber and fail. Extensions mount from this one.
@@ -224,6 +237,8 @@ export class Extensions extends Service {
   constructor(ctx: Context, config: ExtensionsConfig = {}) {
     super(ctx, 'extensions')
     this.owner = ctx
+    this.readOnly = config.readOnly === true
+    this.say = config.log ?? ((line) => console.log(line))
     const { home, root } = ctx.appInstance
     this.sources = (config.sources ?? [{ dir: join(home, 'extensions'), trust: 'install' }]).map(
       (source) => ({
@@ -235,10 +250,12 @@ export class Extensions extends Service {
     this.stateFile = join(home, 'extensions.json')
     this.ledgerFile = join(home, 'extensions-ledger.jsonl')
     // Effects run their disposers newest first: settle pending operations, then dispose every mounted extension, then drop the hook.
-    ctx.effect(
-      () => resolveFromApp(this.stageRoot, root, routerAliases()),
-      'extensions: resolve staged imports from the app',
-    )
+    // Staged copies live in the app's home, outside the app: their bare imports are resolved from the app. A read-only start imports the folders where they are (inside the app).
+    if (!this.readOnly)
+      ctx.effect(
+        () => resolveFromApp(this.stageRoot, root, routerAliases()),
+        'extensions: resolve staged imports from the app',
+      )
     ctx.effect(
       () => async () => {
         for (const entry of [...this.installed.values()].reverse())
@@ -265,16 +282,19 @@ export class Extensions extends Service {
 
   /** Install a folder, or update the installed extension of the same name. The folder must be inside one of the sources. */
   install(source: string): Promise<InstallResult> {
+    if (this.readOnly) return Promise.reject(new Error(READ_ONLY))
     return this.serial(() => this.installNow(source))
   }
 
   /** Remove an installed extension: dispose it, forget it, delete its staged copies. Its source folder is left alone. */
   remove(name: string): Promise<RemoveResult> {
+    if (this.readOnly) return Promise.reject(new Error(READ_ONLY))
     return this.serial(() => this.removeNow(name))
   }
 
   /** Bring every installed extension in line with its source, and install new folders from sources trusted to install. */
   reload(): Promise<InstallResult[]> {
+    if (this.readOnly) return Promise.reject(new Error(READ_ONLY))
     return this.serial(async () => {
       const results: InstallResult[] = []
       for (const entry of [...this.installed.values()]) {
@@ -317,6 +337,7 @@ export class Extensions extends Service {
 
   /** Approve the version that is waiting, then install it. Refused when the source changed since it was requested. */
   approve(name: string): Promise<InstallResult> {
+    if (this.readOnly) return Promise.reject(new Error(READ_ONLY))
     return this.serial(async (): Promise<InstallResult> => {
       const request = this.requests.get(name)
       if (!request) {
@@ -349,6 +370,7 @@ export class Extensions extends Service {
 
   /** Refuse the version that is waiting. Nothing changes except the ledger. */
   deny(name: string): Promise<RemoveResult> {
+    if (this.readOnly) return Promise.reject(new Error(READ_ONLY))
     return this.serial(async (): Promise<RemoveResult> => {
       const request = this.requests.get(name)
       if (!request)
@@ -701,7 +723,62 @@ export class Extensions extends Service {
   }
 
   /** Never throws: one extension's failure is recorded and the others still start. */
+  /**
+   * The production start: every folder of a source that installs by itself is loaded from where it is and mounted; the line says which. An extension that the app's own record
+   * (`extensions.json`, written by dev) names while its folder is gone is named in a warning, because it is not started.
+   */
+  private async startupReadOnly(): Promise<StartupSummary> {
+    const summary: StartupSummary = { installed: [], pending: [], stale: [], failed: [] }
+    const found = this.discover()
+    for (const folder of found) {
+      if (folder.trust !== 'install') {
+        summary.pending.push(folder.name)
+        continue
+      }
+      try {
+        const module = await this.load(folder.dir, folder.name)
+        const mounted = await this.mount(module)
+        this.installed.set(folder.name, {
+          name: folder.name,
+          source: folder.dir,
+          version: hashFolder(folder.dir),
+          dir: folder.dir,
+          module,
+          fiber: mounted.fiber,
+        })
+        if (mounted.error !== undefined)
+          summary.failed.push({ name: folder.name, error: message(mounted.error) })
+        else summary.installed.push(folder.name)
+      } catch (error) {
+        summary.failed.push({ name: folder.name, error: message(error) })
+      }
+    }
+    this.say(
+      summary.installed.length === 0
+        ? `extensions: none found in ${this.sources.map((source) => basename(source.dir)).join(', ')}/`
+        : `extensions (read-only): ${summary.installed.join(', ')}`,
+    )
+    for (const failure of summary.failed)
+      this.say(`WARNING: extension "${failure.name}" did not start: ${failure.error}`)
+    try {
+      if (existsSync(this.stateFile)) {
+        for (const recorded of Object.keys(
+          JSON.parse(readFileSync(this.stateFile, 'utf8')) as Record<string, unknown>,
+        )) {
+          if (!found.some((folder) => folder.name === recorded))
+            this.say(
+              `WARNING: ${basename(this.stateFile)} records the extension "${recorded}", but ${this.sources.map((source) => basename(source.dir)).join(', ')}/ has no folder for it: it is not started in production. Commit its folder, or run the app in development and install it again`,
+            )
+        }
+      }
+    } catch {
+      // A record that cannot be read says nothing about what to start.
+    }
+    return summary
+  }
+
   private async startup(): Promise<StartupSummary> {
+    if (this.readOnly) return this.startupReadOnly()
     const summary: StartupSummary = { installed: [], pending: [], stale: [], failed: [] }
     let records: Record<string, Record_> = {}
     try {

package/templates/agent/AGENTS.md

@@ -7,6 +7,8 @@ and an optional `check(ctx)` that receives the plugin's own context (so `ctx.rou
 
 **Write an extension, not a row.** A feature you build while the app runs is a folder `plugins/<name>/` installed with `.acryl/bin/acryl plugin add plugins/<name>` (the `extensions` plugin loads it again at every start). Add a row to `blend.yaml` and an entry to the `registry` of `src/app.ts` only when the person asks for a plugin that is part of the app itself. Both kinds may import the framework by name (`acrylblends`, `acrylblends/body-limit`, `acryl-router`); a row's relative imports of its sibling plugins also work.
 
-**Drive the app you build.** `.acryl/bin/acryl look` reads the open page as text with refs, and `acryl act click|type|press|scroll|wait --ref <ref>` presses its buttons, opens its sidebars and fills its forms (look again before each act: the refs change). `act navigate --path /settings` goes to another page of the app; a path the app does not serve answers `404 at /nope` and the window shows a 404 page, so navigate on from there. In the desktop app (`npm run desktop`) the app's windows and menu are verbs too: `acryl window list`, `acryl window open --path /settings`, `acryl look --window <id>` (and `act ... --window <id>`) to drive that window's page, `acryl window resize|focus|close --id <id>`, `acryl menu list` and `acryl menu click --path "File>New Note"`. Closing the last window and Quit end the desktop app, so they need `--force`: do not use it unless the person asks. When a person asks for settings, build them as a page at `/settings`, so `acryl window open --path /settings` opens them in every app. Without a desktop app these answer "no desktop window is attached; run npm run desktop".
+**Drive the app you build.** `.acryl/bin/acryl look` reads the open page as text with refs, and `acryl act click|type|press|scroll|wait --ref <ref>` presses its buttons, opens its sidebars and fills its forms (look again before each act: the refs change). `act navigate --path /settings` goes to another page of the app; a path the app does not serve answers `404 at /nope` and the window shows a 404 page, so navigate on from there. In the desktop app (`npm run desktop`) the app's windows and menu are verbs too: `acryl window list`, `acryl window open --path /settings`, `acryl look --window <id>` (and `act ... --window <id>`) to drive that window's page, `acryl window resize|focus|close --id <id>`, `acryl menu list` and `acryl menu click --path "File>New Note"`. Closing the last window and Quit end the desktop app, so they need `--force`: do not use it unless the person asks. The app has a `/settings` page already (the appearance: system, light or dark, kept in the browser) and the desktop app's menu has a Settings item that opens it; add a person's other settings to that page, not to a new one, so `acryl menu click --path "File>Settings..."` and `acryl window open --path /settings` keep opening them (on macOS the item is in the application menu). Without a desktop app these answer "no desktop window is attached; run npm run desktop".
 
-**Production.** The agent, the builder and the extensions are development tools: `POST /ask` spends the model key and runs tools, a plugin installed live runs in this process, and none of it is behind a login. With `NODE_ENV=production` `src/app.ts` leaves those three rows out, so `/ask`, `/extensions*` and `/tasks*` are not mounted; the page and `GET /health` stay. `ACRYL_PRODUCTION_KEEP=agent,builder,extensions` keeps the named rows, and each one kept prints a `WARNING` line at start.
+**Keep to two event streams a page.** A browser lets a page hold six connections to one host, across all the windows of the app, and an `EventSource` holds one for as long as the page is open. The door and the panel use none (they are WebSockets), but a page you build that streams several things in two windows can fill all six, and then every request waits. Give a page at most two streams: share one stream for several cells, or fetch what changes now and then instead.
+
+**Production.** The agent, the builder and the extensions are development tools: `POST /ask` spends the model key and runs tools, a plugin installed live runs in this process, and none of it is behind a login. With `NODE_ENV=production` `src/app.ts` leaves the agent and the builder out, so `/ask`, `/extensions*` and `/tasks*` are not mounted; the page and `GET /health` stay. The extensions you installed (the folders of `plugins/`, committed with the app) still run in production, read-only: nothing can be installed or changed there. `ACRYL_PRODUCTION_KEEP=agent,builder,extensions` keeps the named rows, and each one kept prints a `WARNING` line at start.

package/templates/agent/src/app.ts

@@ -64,7 +64,12 @@ export interface App {
   stop(): Promise<void>
 }
 
-/** The development rows production leaves out, and what each one gives a visitor. */
+/**
+ * The development rows, and what each one gives a visitor. Production leaves the agent and the builder out. The extensions row is not left out: it starts again, read-only,
+ * the extensions in the app's `plugins/` folder (what the agent built and installed in development, committed with the app), so a deployed app has its own features; nothing
+ * can be installed, updated or approved while it runs, and `/ask`, `/extensions*` and `/tasks*` stay unmounted (they need the agent). `ACRYL_PRODUCTION_KEEP=extensions` keeps the
+ * live install itself.
+ */
 const DEVELOPMENT_ROWS: Record<string, string> = {
   agent: 'POST /ask runs the agent, which spends the model key and calls its tools',
   builder: 'the agent can write plugin source into plugins/',
@@ -91,6 +96,7 @@ export async function createApp(
   // serves a folder's door, so the tests that start several apps set it).
   const listen = options.listen !== false
   const leaveOut = new Set<string>()
+  let extensionsReadOnly = false
   if (!listen) leaveOut.add('acryl-node-server').add('acryl-door')
   if (process.env.NODE_ENV === 'production' || process.env.ACRYL_DOOR === 'off')
     leaveOut.add('acryl-door')
@@ -114,6 +120,7 @@ export async function createApp(
         console.warn(
           `WARNING: the "${row}" row runs in production because ACRYL_PRODUCTION_KEEP names it: ${danger}. Nothing here is behind a login; put the app behind your own.`,
         )
+      else if (row === 'extensions') extensionsReadOnly = true
       else leaveOut.add(row)
     }
   }
@@ -141,6 +148,7 @@ export async function createApp(
       tasks: { manifest: `sha256:${manifest.digest}` },
       // The `approval` parameter in blend.yaml (the extensions row) turns this source into one that asks.
       extensions: {
+        ...(extensionsReadOnly ? { readOnly: true } : {}),
         sources: [
           { dir: extensionsDir, trust: 'install' },
           ...(legacy ? [{ dir: legacyDir, trust: 'install' as const }] : []),

package/templates/agent/src/routes.ts

@@ -16,9 +16,18 @@ const DOOR_TAG =
 /**
  * The app's own routes on the router. Always: the page and `GET /health`. While the agent, the extensions and the task recorder run: `POST /ask` for the agent; `GET /extensions`
  * (and `POST /extensions/approve` and `/deny`) and `GET /tasks` to observe and steer what it did (every run is a durable task owning one task per tool call); `POST /tasks/cancel`.
- * What changes is also streamed: `GET /api/state/tasks/events` and `GET /api/state/extensions/events`. In production `src/app.ts` leaves the agent, builder and extensions rows
- * out (unless `ACRYL_PRODUCTION_KEEP` names them), and then those routes are not mounted at all. The mounts are removed when the plugin is disposed.
+ * What changes is also streamed: `GET /api/state/tasks/events` and `GET /api/state/extensions/events`. In production `src/app.ts` leaves the agent and builder rows out
+ * and starts the extensions read-only (unless `ACRYL_PRODUCTION_KEEP` names them), and then those routes are not mounted at all. The mounts are removed when the plugin is disposed.
  */
+/** The page's look: the person's choice from /settings (kept in this browser), applied before the page paints. */
+const APPEARANCE_STYLE =
+  '<style>:root{color-scheme:light dark}html[data-theme=dark]{color-scheme:dark;background:#111827;color:#f9fafb}html[data-theme=light]{color-scheme:light;background:#fff;color:#111827}body{font:16px system-ui,sans-serif;margin:2rem auto;max-width:42rem;padding:0 1rem}a{color:inherit}</style>'
+const APPEARANCE_SCRIPT =
+  "<script>(function(){try{var t=localStorage.getItem('theme');if(t==='dark'||t==='light')document.documentElement.dataset.theme=t}catch(e){}})()</script>"
+
+/** `/settings`: the one setting the template has, the appearance. The desktop app's Settings menu item opens this page. */
+const settingsPage = `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>Settings - ${APP_NAME}</title>${APPEARANCE_STYLE}${APPEARANCE_SCRIPT}</head><body><h1>Settings</h1><p><label for="theme">Appearance</label> <select id="theme" name="theme"><option value="system">Match the system</option><option value="light">Light</option><option value="dark">Dark</option></select></p><p id="saved" role="status"></p><p><a href="/">Back to ${APP_NAME}</a></p><script>(function(){var select=document.getElementById('theme'),saved=document.getElementById('saved');try{select.value=localStorage.getItem('theme')||'system'}catch(e){}select.addEventListener('change',function(){var value=select.value;try{if(value==='system'){localStorage.removeItem('theme');delete document.documentElement.dataset.theme}else{localStorage.setItem('theme',value);document.documentElement.dataset.theme=value}saved.textContent='Saved: '+select.options[select.selectedIndex].text}catch(e){saved.textContent='This browser would not keep the setting.'}})})()</script></body></html>`
+
 export const routes = {
   name: 'routes',
   inject: ['router'],
@@ -37,11 +46,12 @@ export const routes = {
       .get('/', (c) =>
         (c.req.header('accept') ?? '').includes('text/html')
           ? c.html(
-              `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${APP_NAME}</title></head><body><h1>${APP_NAME}</h1><p>This app runs an agent unless it is switched off (production switches it off, see ACRYL_PRODUCTION_KEEP in AGENTS.md). Ask it for a feature in the agent panel on this page (or with <code>POST /ask</code>).</p>${DOOR_TAG}</body></html>`,
+              `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${APP_NAME}</title>${APPEARANCE_STYLE}${APPEARANCE_SCRIPT}</head><body><h1>${APP_NAME}</h1><p>This app runs an agent unless it is switched off (production switches it off, see ACRYL_PRODUCTION_KEEP in AGENTS.md). Ask it for a feature in the agent panel on this page (or with <code>POST /ask</code>).</p>${DOOR_TAG}</body></html>`,
             )
           : c.json({ app: APP_NAME, ok: true }),
       )
       .get('/health', (c) => c.json({ ok: true }))
+      .get('/settings', (c) => c.html(settingsPage))
     ctx.router.route('/', base)
     // The routes that give a visitor the agent: mounted only while the agent, the extensions and the tasks run (see the header).
     ctx.inject(['agent', 'extensions', 'tasks'], (inner) => {

package/templates/agent/test/app.test.ts

@@ -97,7 +97,7 @@ const asking = (app: App) =>
     body: JSON.stringify({ question: 'add 2 3' }),
   })
 
-test('in production the agent, the builder and the extensions are left out: no /ask, no live install, no approve route; the page and /health stay', () =>
+test('in production the agent and the builder are left out and the extensions are read-only: no /ask, no live install, no approve route; the page and /health stay', () =>
   inEnvironment({ NODE_ENV: 'production', ACRYL_PRODUCTION_KEEP: undefined }, async (app) => {
     assert.equal((await app.root.router.request('/health')).status, 200)
     assert.equal((await app.root.router.request('/')).status, 200)
@@ -112,7 +112,12 @@ test('in production the agent, the builder and the extensions are left out: no /
       await response.body?.cancel()
     }
     assert.equal((app.root as unknown as { agent?: unknown }).agent, undefined)
-    assert.equal((app.root as unknown as { extensions?: unknown }).extensions, undefined)
+    // The service is there (it starts what plugins/ holds, once) and refuses every change.
+    const service = (
+      app.root as unknown as { extensions?: { install(source: string): Promise<unknown> } }
+    ).extensions
+    assert.ok(service, 'the extensions service starts read-only in production')
+    await assert.rejects(service.install('/anywhere'), /read-only here \(production\)/)
   }))
 
 test('ACRYL_PRODUCTION_KEEP keeps the named rows in production and says so at start; a name it does not know is reported', () =>
@@ -139,3 +144,23 @@ test('outside production nothing changes: the agent answers and the extensions r
     assert.equal((await app.root.router.request('/extensions')).status, 200)
     assert.deepEqual(warnings, [])
   }))
+
+test('the app has a /settings page with the appearance setting, and the home page applies it', () =>
+  inEnvironment({ NODE_ENV: 'test', ACRYL_PRODUCTION_KEEP: undefined }, async (app) => {
+    const settings = await app.root.router.request('/settings', {
+      headers: { accept: 'text/html' },
+    })
+    assert.equal(settings.status, 200)
+    const page = await settings.text()
+    assert.match(page, /<h1>Settings<\/h1>/)
+    assert.match(page, /<select id="theme"/)
+    for (const option of ['System', 'Light', 'Dark'])
+      assert.match(page, new RegExp(`>(?:Match the )?${option.toLowerCase()}|>${option}<`, 'i'))
+    // The setting is kept in the browser and applied to the home page before it paints.
+    const home = await (
+      await app.root.router.request('/', { headers: { accept: 'text/html' } })
+    ).text()
+    assert.match(home, /localStorage\.getItem\('theme'\)/)
+    // ... without leaving a global behind for the page's own code to collide with.
+    assert.doesNotMatch(home, /<script>\s*(?:var|let|const) /)
+  }))