acrylblends 1.0.6 → 1.0.8

package/plugins/agent-panel/client/markdown.ts

@@ -0,0 +1,219 @@
+/**
+ * A small, safe Markdown for the agent's answers. The parser turns text into a tree of blocks and inlines; nothing in it is HTML: the panel builds elements from the tree with
+ * `createElement` and `textContent`, so an answer can never put markup, a script or an event handler into the page. A link keeps its address only for `http:`, `https:` and `mailto:`.
+ * What it knows: headings, paragraphs, fenced code, bullet and numbered lists, block quotes, and `code`, **bold**, *italic*, [links](https://...) inside a line.
+ */
+
+export type Inline =
+  | { readonly type: 'text'; readonly text: string }
+  | { readonly type: 'code'; readonly text: string }
+  | { readonly type: 'strong'; readonly children: readonly Inline[] }
+  | { readonly type: 'em'; readonly children: readonly Inline[] }
+  | {
+      readonly type: 'link'
+      readonly href: string | undefined
+      readonly children: readonly Inline[]
+    }
+
+export type Block =
+  | { readonly type: 'heading'; readonly level: number; readonly children: readonly Inline[] }
+  | { readonly type: 'paragraph'; readonly children: readonly Inline[] }
+  | { readonly type: 'code'; readonly language: string; readonly text: string }
+  | {
+      readonly type: 'list'
+      readonly ordered: boolean
+      readonly items: readonly (readonly Inline[])[]
+    }
+  | { readonly type: 'quote'; readonly children: readonly Inline[] }
+
+const SAFE_LINK = /^(?:https?:\/\/|mailto:)/iu
+
+/** The address of a link if it is one the panel will open, else nothing (a `javascript:` or `data:` address is shown as text). */
+export function safeHref(href: string): string | undefined {
+  const trimmed = href.trim()
+  return SAFE_LINK.test(trimmed) && !/[\s<>"]/u.test(trimmed) ? trimmed : undefined
+}
+
+/** Inline syntax inside one line or paragraph. An opener with no closer is plain text. */
+export function parseInline(text: string): Inline[] {
+  const out: Inline[] = []
+  let plain = ''
+  const flush = (): void => {
+    if (plain !== '') out.push({ type: 'text', text: plain })
+    plain = ''
+  }
+  let at = 0
+  while (at < text.length) {
+    const char = text[at] as string
+    if (char === '`') {
+      const end = text.indexOf('`', at + 1)
+      if (end > at + 1) {
+        flush()
+        out.push({ type: 'code', text: text.slice(at + 1, end) })
+        at = end + 1
+        continue
+      }
+    } else if (char === '*' && text[at + 1] === '*') {
+      const end = text.indexOf('**', at + 2)
+      if (end > at + 2) {
+        flush()
+        out.push({ type: 'strong', children: parseInline(text.slice(at + 2, end)) })
+        at = end + 2
+        continue
+      }
+    } else if (
+      (char === '*' || char === '_') &&
+      text[at + 1] !== ' ' &&
+      (at === 0 || !/\w/u.test(text[at - 1] as string))
+    ) {
+      const end = text.indexOf(char, at + 1)
+      if (end > at + 1 && text[end - 1] !== ' ' && !/\w/u.test(text[end + 1] ?? ' ')) {
+        flush()
+        out.push({ type: 'em', children: parseInline(text.slice(at + 1, end)) })
+        at = end + 1
+        continue
+      }
+    } else if (char === '[') {
+      const close = text.indexOf('](', at + 1)
+      const end = close === -1 ? -1 : text.indexOf(')', close + 2)
+      if (close > at + 1 && end > close) {
+        flush()
+        out.push({
+          type: 'link',
+          href: safeHref(text.slice(close + 2, end)),
+          children: parseInline(text.slice(at + 1, close)),
+        })
+        at = end + 1
+        continue
+      }
+    }
+    plain += char
+    at += 1
+  }
+  flush()
+  return out
+}
+
+/** Blocks of a whole answer. A fence that is still open (the answer is streaming) shows what it has so far. */
+export function parseMarkdown(source: string): Block[] {
+  const lines = source.replaceAll('\r\n', '\n').split('\n')
+  const blocks: Block[] = []
+  let paragraph: string[] = []
+  const endParagraph = (): void => {
+    if (paragraph.length > 0)
+      blocks.push({ type: 'paragraph', children: parseInline(paragraph.join('\n')) })
+    paragraph = []
+  }
+  for (let at = 0; at < lines.length; at += 1) {
+    const line = lines[at] as string
+    const fence = /^\s*```\s*([\w+-]*)\s*$/u.exec(line)
+    if (fence) {
+      endParagraph()
+      const body: string[] = []
+      for (at += 1; at < lines.length && !/^\s*```\s*$/u.test(lines[at] as string); at += 1)
+        body.push(lines[at] as string)
+      blocks.push({ type: 'code', language: fence[1] ?? '', text: body.join('\n') })
+      continue
+    }
+    const heading = /^(#{1,6})\s+(.*?)\s*#*\s*$/u.exec(line)
+    if (heading) {
+      endParagraph()
+      blocks.push({
+        type: 'heading',
+        level: (heading[1] as string).length,
+        children: parseInline(heading[2] as string),
+      })
+      continue
+    }
+    const bullet = /^\s*[-*+]\s+(.*)$/u.exec(line)
+    const numbered = /^\s*\d{1,3}[.)]\s+(.*)$/u.exec(line)
+    if (bullet || numbered) {
+      endParagraph()
+      const ordered = numbered !== null
+      const items: Inline[][] = []
+      for (; at < lines.length; at += 1) {
+        const item = (ordered ? /^\s*\d{1,3}[.)]\s+(.*)$/u : /^\s*[-*+]\s+(.*)$/u).exec(
+          lines[at] as string,
+        )
+        if (!item) break
+        items.push(parseInline(item[1] as string))
+      }
+      at -= 1
+      blocks.push({ type: 'list', ordered, items })
+      continue
+    }
+    const quote = /^\s*>\s?(.*)$/u.exec(line)
+    if (quote) {
+      endParagraph()
+      const quoted: string[] = []
+      for (; at < lines.length; at += 1) {
+        const next = /^\s*>\s?(.*)$/u.exec(lines[at] as string)
+        if (!next) break
+        quoted.push(next[1] as string)
+      }
+      at -= 1
+      blocks.push({ type: 'quote', children: parseInline(quoted.join('\n')) })
+      continue
+    }
+    if (line.trim() === '') endParagraph()
+    else paragraph.push(line)
+  }
+  endParagraph()
+  return blocks
+}
+
+/** Build the elements of a parsed answer. Only `createElement`, `textContent` and attributes set here: no HTML string reaches the page. */
+export function renderMarkdown(source: string, document: Document): DocumentFragment {
+  const fragment = document.createDocumentFragment()
+  const inline = (parent: Node, nodes: readonly Inline[]): void => {
+    for (const node of nodes) {
+      if (node.type === 'text') parent.appendChild(document.createTextNode(node.text))
+      else if (node.type === 'code') {
+        const code = document.createElement('code')
+        code.textContent = node.text
+        parent.appendChild(code)
+      } else if (node.type === 'strong' || node.type === 'em') {
+        const element = document.createElement(node.type)
+        inline(element, node.children)
+        parent.appendChild(element)
+      } else if (node.href === undefined) {
+        inline(parent, node.children)
+      } else {
+        const anchor = document.createElement('a')
+        anchor.href = node.href
+        anchor.target = '_blank'
+        anchor.rel = 'noopener noreferrer'
+        inline(anchor, node.children)
+        parent.appendChild(anchor)
+      }
+    }
+  }
+  for (const block of parseMarkdown(source)) {
+    if (block.type === 'code') {
+      const pre = document.createElement('pre')
+      const code = document.createElement('code')
+      code.textContent = block.text
+      pre.appendChild(code)
+      fragment.appendChild(pre)
+    } else if (block.type === 'list') {
+      const list = document.createElement(block.ordered ? 'ol' : 'ul')
+      for (const item of block.items) {
+        const li = document.createElement('li')
+        inline(li, item)
+        list.appendChild(li)
+      }
+      fragment.appendChild(list)
+    } else {
+      const element = document.createElement(
+        block.type === 'heading'
+          ? `h${String(Math.min(block.level + 2, 6))}`
+          : block.type === 'quote'
+            ? 'blockquote'
+            : 'p',
+      )
+      inline(element, block.children)
+      fragment.appendChild(element)
+    }
+  }
+  return fragment
+}

package/plugins/agent-panel/headless.ts

@@ -195,3 +195,23 @@ export function headlessDriver(name: HeadlessName, root: string): ChatDriver {
     },
   }
 }
+
+/**
+ * Why a driver name cannot be used to ask a question, in a sentence: it is a terminal (picked in the panel, not asked over `/ask`), it is a coding agent that is not installed or not
+ * able to start, or pi without a key to reach its model. Nothing when the name is not one of the headless agents.
+ */
+export function whyNotChat(
+  name: string,
+  kind: 'chat' | 'terminal' | undefined,
+): string | undefined {
+  if (kind === 'terminal')
+    return `"${name}" is a terminal driver: pick it in the panel to open its terminal; /ask runs the chat drivers`
+  if (name !== 'claude' && name !== 'codex' && name !== 'pi') return undefined
+  if (!onPath(name))
+    return `${name} was not found on the PATH of the app, so the panel cannot start it`
+  const launch = resolveLaunch(name, [])
+  if ('error' in launch) return launch.error
+  if (name === 'pi' && !piHasDeepseekKey())
+    return 'pi needs a DeepSeek key: set DEEPSEEK_API_KEY in the environment of the app, or log in with pi once (it keeps the key in ~/.pi/agent/auth.json)'
+  return undefined
+}

package/plugins/agent-panel/index.ts

@@ -9,17 +9,24 @@
  * - Only the app's own page may ask (a same-origin request carrying the token), one run at a time, and every ask is written to `.acryl/audit/agent-panel.jsonl`.
  * - Development only: the plugin does nothing with `NODE_ENV=production` or `ACRYL_DOOR=off`.
  */
-import { randomBytes } from 'node:crypto'
+import { randomBytes, timingSafeEqual } from 'node:crypto'
 import { appendFileSync, mkdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import { clientModules } from '../acryl-node-server/src/client-modules.ts'
-import { streamSSE } from '../acryl-router/src/helpers/index.ts'
-import { Acryl } from '../acryl-router/src/index.ts'
+import { streamSSE, type UpgradeWebSocket } from '../acryl-router/src/helpers/index.ts'
+import { Acryl, type MiddlewareHandler } from '../acryl-router/src/index.ts'
+import { loopbackAuthority } from '../acryl-router/src/middleware/index.ts'
 import type {} from '../agent/index.ts'
 import type {} from '../extensions/index.ts'
 import type { ChatDriver } from './drivers.ts'
-import { agentDriver, availableHeadless, type HeadlessName, headlessDriver } from './headless.ts'
+import {
+  agentDriver,
+  availableHeadless,
+  type HeadlessName,
+  headlessDriver,
+  whyNotChat,
+} from './headless.ts'
 import { provideDrivers } from './registry.ts'
 
 export type {
@@ -117,25 +124,9 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
       if (!fromOwnPage(c.req.raw.headers) || c.req.header('x-agent-panel-token') !== token)
         return c.json({ error: "only the app's own page may ask" }, 403)
       const body = (await c.req.json().catch(() => ({}))) as { message?: unknown; driver?: unknown }
-      const message = typeof body.message === 'string' ? body.message.trim() : ''
-      const driverName = typeof body.driver === 'string' ? body.driver : 'agent'
-      if (message === '' || message.length > 8000)
-        return c.json({ error: 'write a message of at most 8000 characters' }, 400)
-      const driver = registry.get(driverName)
-      if (driver?.kind !== 'chat')
-        return c.json(
-          {
-            error: `the driver "${driverName}" is not available here (${registry
-              .list()
-              .filter((d) => d.kind === 'chat')
-              .map((d) => d.name)
-              .join(', ')})`,
-          },
-          400,
-        )
-      if (current !== undefined && !current.ended)
-        return c.json({ error: 'a run is already going; wait for it to end' }, 409)
-      const run = startRun(driverName, message, driver)
+      const checked = checkAsk(body.message, body.driver)
+      if ('error' in checked) return c.json({ error: checked.error }, checked.status)
+      const run = startRun(checked.driverName, checked.message, checked.driver)
       return follow(c, run, false)
     })
     // Stop: the only thing that cancels a run. A page that goes away (a reload, a move to another page, a closed tab) does not: the agent goes on, and the page picks it up again.
@@ -151,6 +142,34 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
         return c.json({ error: "only the app's own page may read the run" }, 403)
       return current === undefined ? c.json({ run: null }) : follow(c, current, true)
     })
+  /** What `/ask` and the socket's `ask` both check: a message of a sensible size, a chat driver that is here, and no run going. */
+  const checkAsk = (
+    rawMessage: unknown,
+    rawDriver: unknown,
+  ):
+    | { message: string; driverName: string; driver: ChatDriver }
+    | { error: string; status: 400 | 409 } => {
+    const message = typeof rawMessage === 'string' ? rawMessage.trim() : ''
+    const driverName = typeof rawDriver === 'string' ? rawDriver : 'agent'
+    if (message === '' || message.length > 8000)
+      return { error: 'write a message of at most 8000 characters', status: 400 }
+    const driver = registry.get(driverName)
+    if (driver?.kind !== 'chat') {
+      const chat = registry
+        .list()
+        .filter((d) => d.kind === 'chat')
+        .map((d) => d.name)
+        .join(', ')
+      const why = whyNotChat(driverName, driver?.kind)
+      return {
+        error: `the driver "${driverName}" is not available here${why === undefined ? '' : `: ${why}`} (chat drivers: ${chat})`,
+        status: 400,
+      }
+    }
+    if (current !== undefined && !current.ended)
+      return { error: 'a run is already going; wait for it to end', status: 409 }
+    return { message, driverName, driver }
+  }
   /** One run of an agent: its events as they came, and who is following. It lives in the app, not in a page. */
   interface Run {
     readonly id: number
@@ -205,33 +224,35 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
     })()
     return run
   }
-  /** Follow a run as server-sent events: a `run` event (what it is, whether it already ended), the events so far, then the new ones until it ends. Following does not keep it alive. */
-  const follow = (c: Parameters<typeof streamSSE>[0], run: Run, announce: boolean): Response =>
-    streamSSE(c, async (stream) => {
-      if (announce)
-        await stream.writeSSE({
-          event: 'run',
-          data: JSON.stringify({
-            id: run.id,
-            driver: run.driver,
-            message: run.message,
-            ended: run.ended,
-            endedAt: run.endedAt ?? null,
-          }),
-        })
-      const queue: Array<{ event: string; data: unknown }> = [...run.events]
-      let wake: (() => void) | undefined
-      const follower = (item: { event: string; data: unknown }): void => {
-        queue.push(item)
-        wake?.()
-      }
-      if (!run.ended) run.followers.add(follower)
-      let open = true
-      stream.onAbort(() => {
-        open = false
-        run.followers.delete(follower)
-        wake?.()
+  /**
+   * Follow a run into `write`: a `run` event (what it is, whether it already ended) when `announce`, the events so far, then the new ones until it ends. Following does not keep the
+   * run alive. `detach` stops following (the page went away); `done` settles when the run ended or the following was detached.
+   */
+  const pump = (
+    run: Run,
+    announce: boolean,
+    write: (event: string, data: unknown) => void | Promise<void>,
+  ): { done: Promise<void>; detach(): void } => {
+    const queue: Array<{ event: string; data: unknown }> = [...run.events]
+    if (announce)
+      queue.unshift({
+        event: 'run',
+        data: {
+          id: run.id,
+          driver: run.driver,
+          message: run.message,
+          ended: run.ended,
+          endedAt: run.endedAt ?? null,
+        },
       })
+    let wake: (() => void) | undefined
+    const follower = (item: { event: string; data: unknown }): void => {
+      queue.push(item)
+      wake?.()
+    }
+    if (!run.ended) run.followers.add(follower)
+    let open = true
+    const done = (async () => {
       try {
         while (open) {
           const item = queue.shift()
@@ -244,11 +265,130 @@ export function apply(ctx: Context, config: PanelConfig = {}): void {
             continue
           }
           if (item.event === 'end') break
-          await stream.writeSSE({ event: item.event, data: JSON.stringify(item.data) })
+          await write(item.event, item.data)
         }
       } finally {
         run.followers.delete(follower)
       }
+    })()
+    return {
+      done,
+      detach: () => {
+        open = false
+        run.followers.delete(follower)
+        wake?.()
+      },
+    }
+  }
+  /** Follow a run as server-sent events. */
+  const follow = (c: Parameters<typeof streamSSE>[0], run: Run, announce: boolean): Response =>
+    streamSSE(c, async (stream) => {
+      const following = pump(run, announce, (event, data) =>
+        stream.writeSSE({ event, data: JSON.stringify(data) }),
+      )
+      stream.onAbort(following.detach)
+      await following.done
     })
+  // The same runs over a WebSocket, which is not one of the browser's six connections per host: a page that streams its own state in two windows, with a run going, would otherwise
+  // queue the panel's Stop and the door's answers behind them. A WebSocket has no CORS and cannot set a header, so the Origin must be this app's own and the first frame carries the
+  // token. Frames: up `{ t: 'hello', token }`, then `{ t: 'ask', message, driver }`, `{ t: 'follow' }` or `{ t: 'stop' }`; down `{ e: <event>, d: <data> }`, as the stream's events.
+  // The server row comes after this plugin in a blend, so the WebSocket form is mounted when the server appears (and not at all without one that upgrades or without the `ws` package).
+  ctx.inject(['nodeServer'], (inner) => {
+    let upgrade: UpgradeWebSocket
+    try {
+      upgrade = (
+        inner as unknown as { nodeServer: { upgrades(): UpgradeWebSocket } }
+      ).nodeServer.upgrades()
+    } catch {
+      return
+    }
+    const ws = new Acryl()
+    const own: MiddlewareHandler = async (c, next) => {
+      const authority = loopbackAuthority(c)
+      const origin = c.req.header('origin')
+      const site = c.req.header('sec-fetch-site')
+      if (
+        authority === undefined ||
+        origin === undefined ||
+        origin !== authority.origin ||
+        (site !== undefined && site !== 'same-origin')
+      )
+        return c.json({ error: "only the app's own page may use the panel" }, 403)
+      await next()
+    }
+    const sameToken = (presented: unknown): boolean => {
+      if (typeof presented !== 'string') return false
+      const a = Buffer.from(presented)
+      const b = Buffer.from(token)
+      return a.length === b.length && timingSafeEqual(a, b)
+    }
+    ws.get(
+      `${PREFIX}/run/ws`,
+      own,
+      upgrade(
+        () => {
+          let authed = false
+          let following: { detach(): void } | undefined
+          let hello: NodeJS.Timeout | undefined
+          return {
+            onOpen(_event, ws) {
+              hello = setTimeout(() => ws.close(4401, 'no token'), 5000)
+            },
+            onMessage(event, ws) {
+              if (typeof event.data !== 'string') return
+              let message: { t?: unknown; token?: unknown; message?: unknown; driver?: unknown }
+              try {
+                message = JSON.parse(event.data) as typeof message
+              } catch {
+                return
+              }
+              if (!authed) {
+                if (message.t !== 'hello' || !sameToken(message.token)) {
+                  ws.close(4401, 'token')
+                  return
+                }
+                authed = true
+                if (hello !== undefined) clearTimeout(hello)
+                return
+              }
+              const send = (e: string, d: unknown): void => {
+                ws.send(JSON.stringify({ e, d }))
+              }
+              if (message.t === 'stop') {
+                current?.cancel.abort()
+                return
+              }
+              if (following !== undefined) return
+              const watch = (run: Run, announce: boolean): void => {
+                const pumped = pump(run, announce, send)
+                following = pumped
+                void pumped.done.then(() => ws.close(1000, 'run ended'))
+              }
+              if (message.t === 'ask') {
+                const checked = checkAsk(message.message, message.driver)
+                if ('error' in checked) {
+                  send('error', { message: checked.error })
+                  ws.close(1000, 'refused')
+                  return
+                }
+                watch(startRun(checked.driverName, checked.message, checked.driver), false)
+              } else if (message.t === 'follow') {
+                if (current === undefined) {
+                  send('idle', {})
+                  ws.close(1000, 'no run')
+                } else watch(current, true)
+              }
+            },
+            onClose() {
+              if (hello !== undefined) clearTimeout(hello)
+              following?.detach()
+            },
+          }
+        },
+        { textOnly: true },
+      ),
+    )
+    inner.router.route('/', ws)
+  })
   ctx.router.route('/', app)
 }

package/plugins/desktop/main.ts

@@ -9,7 +9,7 @@
 import { mkdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
-import { app, BrowserWindow, Menu, type MenuItem, shell } from 'electron'
+import { app, BrowserWindow, Menu, MenuItem, screen, shell } from 'electron'
 import type { App } from '../../src/app.ts'
 import '../acryl-node-server/src/register.ts'
 import { selectInstance } from '../instance/index.ts'
@@ -20,9 +20,10 @@ import {
   startDoorShell,
   type WindowPort,
 } from './door-shell.ts'
+import { hasSettings, settingsPlacement } from './menu.ts'
 import { createDesktopShutdown, installShutdownRequests } from './shutdown.ts'
 import { resolveDesktopUserDataOverride } from './user-data.ts'
-import { windowOptions } from './window.ts'
+import { cascade, windowOptions } from './window.ts'
 
 const projectRoot = fileURLToPath(new URL('../..', import.meta.url))
 const chosen = selectInstance({ projectRoot, env: process.env })
@@ -91,7 +92,19 @@ if (!app.requestSingleInstanceLock()) {
     const origin = new URL(url).origin
     /** One window on a path of the app. Navigation stays on the app's own server; any other address opens in the system browser. The user agent names the window to the door (`AcrylWindow/<id>`), so an agent can drive it with `--window <id>`. */
     const createWindow = (path: string): BrowserWindow => {
-      const created = new BrowserWindow(windowOptions({ title: chosen.name }))
+      // A window opened while another is open sits a step down and to the right of it, not exactly on top.
+      const beside =
+        BrowserWindow.getFocusedWindow() ??
+        BrowserWindow.getAllWindows().find((other) => !other.isDestroyed())
+      const where = (() => {
+        if (beside === undefined) return {}
+        const bounds = beside.getBounds()
+        return cascade(bounds, screen.getDisplayMatching(bounds).workArea, {
+          width: 1100,
+          height: 760,
+        })
+      })()
+      const created = new BrowserWindow(windowOptions({ title: chosen.name, ...where }))
       created.webContents.setUserAgent(
         `${created.webContents.getUserAgent()} AcrylWindow/${String(created.id)}`,
       )
@@ -147,6 +160,40 @@ if (!app.requestSingleInstanceLock()) {
       open: (path) => port(createWindow(path ?? startPath())),
       menu: () => (Menu.getApplicationMenu()?.items ?? []).map(menuItem),
     }
+    // An app that serves a /settings page gets a Settings item in the menu (Electron's own menu otherwise): it opens that page, in the window that already shows it when there is one.
+    const settingsServed = await fetch(new URL('/settings', url), {
+      headers: { accept: 'text/html' },
+      signal: AbortSignal.timeout(2000),
+    }).then(
+      (answer) => answer.ok,
+      () => false,
+    )
+    const menu = Menu.getApplicationMenu()
+    const placement =
+      menu === null || !settingsServed || hasSettings(menu.items)
+        ? undefined
+        : settingsPlacement(menu.items, process.platform)
+    if (menu !== null && placement !== undefined) {
+      const target = menu.items[placement.menu]?.submenu
+      const openSettings = (): void => {
+        const shown = live().find(
+          (candidate) =>
+            new URL(candidate.webContents.getURL() || 'about:blank', url).pathname === '/settings',
+        )
+        if (shown === undefined) createWindow('/settings')
+        else {
+          if (shown.isMinimized()) shown.restore()
+          shown.focus()
+        }
+      }
+      target?.insert(
+        placement.at,
+        new MenuItem({ label: 'Settings...', accelerator: 'CmdOrCtrl+,', click: openSettings }),
+      )
+      if (placement.separatorAfter)
+        target?.insert(placement.at + 1, new MenuItem({ type: 'separator' }))
+      Menu.setApplicationMenu(menu)
+    }
     stopDoorShell = startDoorShell(projectRoot, { desktop, log: console.log })
   })
 }

package/plugins/desktop/menu.ts

@@ -0,0 +1,60 @@
+/**
+ * The desktop app's Settings menu item. An app that serves a `/settings` page gets a "Settings..." item that opens it in a window (Cmd+, on macOS, Ctrl+, elsewhere); an app without
+ * the page gets nothing. Where the item goes is decided here, from the labels of the application menu Electron built, so it is tested without Electron.
+ */
+
+/** The part of an Electron menu item this file reads. */
+export interface MenuNode {
+  readonly label: string
+  readonly role?: string | undefined
+  readonly type?: string | undefined
+  readonly submenu?: { readonly items: readonly MenuNode[] } | null | undefined
+}
+
+export interface Placement {
+  /** Index of the top-level menu that gets the item. */
+  readonly menu: number
+  /** Index inside that menu to insert at. */
+  readonly at: number
+  /** Whether a separator goes after the item (so it sits in a group of its own). */
+  readonly separatorAfter: boolean
+}
+
+/**
+ * macOS puts Settings in the application menu, under About; elsewhere it is the first item of the File menu. Returns nothing when the menu has neither place (an app that
+ * replaced Electron's menu with its own keeps its own).
+ */
+export function settingsPlacement(
+  items: readonly MenuNode[],
+  platform: NodeJS.Platform,
+): Placement | undefined {
+  if (platform === 'darwin') {
+    const submenu = items[0]?.submenu?.items
+    if (submenu === undefined || submenu === null) return undefined
+    const about = submenu.findIndex(
+      (item) => item.role === 'about' || /^about\b/iu.test(item.label),
+    )
+    // Under About and the separator after it; first when there is no About.
+    const separator =
+      about === -1
+        ? -1
+        : submenu.findIndex((item, index) => index > about && item.type === 'separator')
+    return {
+      menu: 0,
+      at: separator === -1 ? (about === -1 ? 0 : about + 1) : separator + 1,
+      separatorAfter: true,
+    }
+  }
+  const file = items.findIndex((item) => /^&?file$/iu.test(item.label) || item.role === 'fileMenu')
+  if (file === -1 || items[file]?.submenu == null) return undefined
+  return { menu: file, at: 0, separatorAfter: true }
+}
+
+/** Whether a menu already has a Settings item (so a restart that builds the menu twice adds it once). */
+export function hasSettings(items: readonly MenuNode[]): boolean {
+  return items.some(
+    (item) =>
+      /^settings\b|^preferences\b/iu.test(item.label) ||
+      (item.submenu?.items !== undefined && hasSettings(item.submenu.items)),
+  )
+}