acrylblends 1.4.0 → 1.5.0

package/plugins/acryl-node-server/src/transpile.ts

@@ -36,13 +36,32 @@ const importSources = new Map<string, string>()
  * @returns the compiler.
  * @throws MissingTypeScriptError when the app has no `typescript`.
  */
-function compilerFor(file: string, what: string): Compiler {
-  // Only the app's own node_modules chain counts: Node's global folders (NODE_PATH, which a package manager's shims may set) are not the app.
-  let owner: string | undefined
-  for (let dir = dirname(file); owner === undefined; dir = dirname(dir)) {
-    if (existsSync(join(dir, 'node_modules', 'typescript', 'package.json'))) owner = dir
-    else if (dirname(dir) === dir) throw new MissingTypeScriptError(file, what)
+/** The nearest folder from `start` up whose node_modules has `typescript`, or undefined. */
+function typescriptOwner(start: string): string | undefined {
+  for (let dir = start; ; dir = dirname(dir)) {
+    if (existsSync(join(dir, 'node_modules', 'typescript', 'package.json'))) return dir
+    if (dirname(dir) === dir) return undefined
   }
+}
+
+/** The Program's folder when this process is a desktop product's frame host: the person's source has no packages, the bundle has them. */
+let programPackages: string | undefined
+
+/**
+ * In a desktop product's frame host, compile with the Program's packages when a file's own chain has none (`register.ts` calls this once it finds the
+ * product's app tree, plugins/instance/bundle.ts). Nowhere else: an app without `typescript` is told so.
+ */
+export function usePackagesOfProgram(dir: string): void {
+  programPackages = dir
+}
+
+function compilerFor(file: string, what: string): Compiler {
+  // Only the app's own node_modules chain counts: Node's global folders (NODE_PATH, which a package manager's shims may set) are not the app. In a
+  // desktop product the app is the person's source with the Program's packages.
+  const owner =
+    typescriptOwner(dirname(file)) ??
+    (programPackages === undefined ? undefined : typescriptOwner(programPackages))
+  if (owner === undefined) throw new MissingTypeScriptError(file, what)
   const path = createRequire(join(owner, 'package.json')).resolve('typescript')
   let compiler = compilers.get(path)
   if (compiler === undefined) {

package/plugins/acryl-page/src/favicon.ts

@@ -0,0 +1,19 @@
+/**
+ * The page's own icon: the ACRYL Blends logo (plugins/desktop/assets/acrylblends-logo.png at 64 px) inside an SVG, which is what a browser tab reads at 16 px. The wordmark is
+ * unreadable that small. The frontend package the page borrows its scripts from ships DeepSeek's whale as favicon.svg, so the page answers every icon request itself and
+ * never serves that file.
+ */
+export const ACRYL_FAVICON_SVG =
+  "<svg xmlns=\"http://www.w3.org/2000/svg\" xmlns:xlink=\"http://www.w3.org/1999/xlink\" viewBox=\"0 0 64 64\" role=\"img\" aria-label=\"ACRYL Blends\"><image width=\"64\" height=\"64\" xlink:href=\"data:image/png;base64,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\"/></svg>"
+
+/** The web manifest of an app page: its title and the icon above, not the frontend package's own. */
+export function pageManifest(title: string): string {
+  return JSON.stringify({
+    name: title,
+    short_name: title,
+    start_url: './',
+    scope: './',
+    display: 'standalone',
+    icons: [{ src: 'favicon.svg', sizes: 'any', type: 'image/svg+xml', purpose: 'any' }],
+  })
+}

package/plugins/acryl-page/src/index.ts

@@ -10,6 +10,7 @@ import { dirname, extname, join, normalize, sep } from 'node:path'
 import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { Context } from '@deepseek-ai/cordis'
 import type {} from 'acryl-web-server'
+import { ACRYL_FAVICON_SVG, pageManifest } from './favicon.ts'
 
 /** Stable Cordis plugin name, equal to the package name and the Loader row id. */
 export const name = 'acryl-page'
@@ -64,12 +65,17 @@ export function clientAssetTags(indexHtml: string): string {
 
 /** Our document: minimal on purpose; the frame renders into `#root`, and the taps add the boot wire before `</head>`. */
 export function pageDocument(tags: string, title: string, taps: (html: string) => string): string {
+  // The title is an app's name, typed by a person: markup in it is text, never the page's.
+  const text = title.replace(/[&<>"']/gu, (character) => `&#${String(character.charCodeAt(0))};`)
   const document = `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${title}</title>
+    <title>${text}</title>
+    <meta name="application-name" content="${text}" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <link rel="manifest" href="/manifest.webmanifest" />
     ${tags}
   </head>
   <body>
@@ -143,21 +149,20 @@ export function apply(ctx: Context, config: Partial<Config> = {}): void {
       await serveFile(assets, pathname.slice('/assets'.length), res, req.method ?? 'GET')
     },
   })
-  // Browsers ask for /favicon.ico unconditionally; the built light icon answers it.
+  // Browsers ask for /favicon.ico unconditionally. The icon is ours (the ACRYL mark), never the frontend package's DeepSeek whale.
+  const sendIcon = async (req: IncomingMessage, res: ServerResponse): Promise<void> => {
+    res.writeHead(200, { 'content-type': 'image/svg+xml', 'content-length': String(Buffer.byteLength(ACRYL_FAVICON_SVG)), 'cache-control': 'no-cache' })
+    res.end(req.method === 'HEAD' ? undefined : ACRYL_FAVICON_SVG)
+  }
+  for (const path of ['/favicon.ico', '/favicon.svg', '/favicon-dark.svg'])
+    ctx.webServer.register({ kind: 'exact', path, handler: sendIcon })
   ctx.webServer.register({
     kind: 'exact',
-    path: '/favicon.ico',
+    path: '/manifest.webmanifest',
     handler: async (req: IncomingMessage, res: ServerResponse) => {
-      await serveFile(dist, 'favicon.svg', res, req.method ?? 'GET')
+      const manifest = pageManifest(title)
+      res.writeHead(200, { 'content-type': 'application/manifest+json', 'content-length': String(Buffer.byteLength(manifest)) })
+      res.end(req.method === 'HEAD' ? undefined : manifest)
     },
   })
-  for (const file of ['favicon.svg', 'favicon-dark.svg', 'manifest.webmanifest']) {
-    ctx.webServer.register({
-      kind: 'exact',
-      path: `/${file}`,
-      handler: async (req: IncomingMessage, res: ServerResponse) => {
-        await serveFile(dist, file, res, req.method ?? 'GET')
-      },
-    })
-  }
 }

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

@@ -525,6 +525,8 @@ export async function start(prefix: string = '/api/agent-panel'): Promise<void>
   const watch = async (source: RunSource, own: boolean): Promise<void> => {
     let live = true
     let changed = false
+    // Every run the server finishes ends with `done` or `error`; a stream that stops without either lost its server, and the run with it.
+    let finished = false
     let answer: HTMLElement | undefined
     let answered = ''
     // The Assistant's steps on the page, shown under its answer in one line, as the person reads what it did.
@@ -592,11 +594,18 @@ export async function start(prefix: string = '/api/agent-panel'): Promise<void>
           changed = true
           line(`plugin ${String(data.extension)}: ${String(data.action)}`, 'tool')
         } else if (event === 'error') {
+          finished = true
           line(String(data.message ?? 'The run failed.'), 'err')
         } else if (event === 'done') {
+          finished = true
           changed = changed || data.changed === true
         }
       }
+      if (live && working !== undefined && !finished)
+        line(
+          'The app stopped while the agent was working, and the run ended with it (`npm run dev` restarts the app when a file it runs changes). Ask again to go on.',
+          'err',
+        )
     } catch (error) {
       line(`The request failed: ${error instanceof Error ? error.message : String(error)}`, 'err')
     } finally {

package/plugins/agent-panel/headless.ts

@@ -1,9 +1,9 @@
 /** The panel's own drivers, all `chat`: the app's agent, and the coding agents (`claude`, `codex`, `pi`) started headless in the app folder. */
 import { type ChildProcess, spawn, spawnSync } from 'node:child_process'
 import { readFileSync } from 'node:fs'
-import { homedir } from 'node:os'
 import { join } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
+import { personHome } from '../instance/storage.ts'
 import type { ChatDriver, ChatEvent } from './drivers.ts'
 import { resolveLaunch } from './launch.ts'
 
@@ -78,7 +78,7 @@ export function onPath(program: string): boolean {
 /** Whether pi can reach DeepSeek: the key in the environment, or the one pi stored for itself when its owner logged in (`~/.pi/agent/auth.json`, a `deepseek` entry). */
 export function piHasDeepseekKey(
   env: NodeJS.ProcessEnv = process.env,
-  home: string = homedir(),
+  home: string = personHome(env),
 ): boolean {
   if (env.DEEPSEEK_API_KEY) return true
   try {

package/plugins/desktop/app-page.ts

@@ -0,0 +1,151 @@
+/**
+ * What the frame's App pages ask of a desktop product (app-storage.md, "What the person sees"): the first start's "Name your app" and Settings > App
+ * (name, size, show the folder, export, import, start over, the other apps, git's licence). The page asks through one IPC channel that `preload.cjs`
+ * exposes as `window.acrylBlendsApp`; this module answers, over `AppStorage` and the shell's own ports, so it is tested without Electron.
+ *
+ * Every answer is a plain result, never a thrown IPC error: the page shows `message` as it is.
+ */
+
+import type { AppInstance } from '../instance/index.ts'
+import type { AppSize, AppStorage, RegisteredApp } from '../instance/storage.ts'
+import type { ProductGit } from './git.ts'
+
+/** The IPC channel; `preload.cjs` names the same string. */
+export const APP_PAGE_CHANNEL = 'acrylblends:app'
+
+/** What the page shows. `named` is false until the person names the app (the first start asks). */
+export interface AppPageState {
+  readonly id: string
+  readonly name: string
+  readonly named: boolean
+  /** The other apps on this computer, to open one instead. */
+  readonly others: readonly {
+    readonly id: string
+    readonly name: string
+    readonly created: string
+  }[]
+  /** What the OS calls its file manager: the Show button's label. */
+  readonly fileManager: 'Finder' | 'Explorer' | 'Files'
+  /** The product ships git (its licence and source are offered on the page). */
+  readonly git: boolean
+}
+
+export type AppPageResult =
+  | { readonly ok: true; readonly value?: unknown }
+  | { readonly ok: false; readonly message: string }
+
+export interface AppPagePorts {
+  readonly storage: AppStorage
+  /** The id of the app the window shows now. */
+  current(): string
+  /** A new app's starting files (the first start's seed). */
+  readonly seed: (source: string) => void
+  /**
+   * Stop the frame host, run `next` (which may move the old app's folders), and start the host on the app it returns, reloading the windows. When
+   * `next` fails, the app that ran comes back and the failure is the answer.
+   */
+  switchTo(next: () => AppInstance): Promise<void>
+  /** The save dialog for an export (`suggested` is the file name), or undefined when the person cancels. */
+  chooseExportFile(suggested: string): Promise<string | undefined>
+  /** The open dialog for an import, or undefined when the person cancels. */
+  chooseImportFile(): Promise<string | undefined>
+  /** Open a file with the OS's own application for it. */
+  openPath(path: string): Promise<void>
+  /** The app's label changed: the process name and the window titles follow. */
+  renamed(app: RegisteredApp): void
+  readonly platform: NodeJS.Platform
+  readonly git?: ProductGit
+}
+
+const fileManagerOf = (platform: NodeJS.Platform): AppPageState['fileManager'] =>
+  platform === 'darwin' ? 'Finder' : platform === 'win32' ? 'Explorer' : 'Files'
+
+/** A file name every OS accepts, from the app's label: the export's suggested name. */
+export function exportFileName(name: string): string {
+  const safe = [...name]
+    .filter((character) => (character.codePointAt(0) ?? 0) >= 0x20)
+    .join('')
+    .replace(/[<>:"/\\|?*]/gu, '-')
+    .replace(/[. ]+$/u, '')
+    .trim()
+  return `${safe === '' ? 'app' : safe}.acrylblend`
+}
+
+/** The handler of the page's channel: one operation and its argument, one result. */
+export function appPageHandler(
+  ports: AppPagePorts,
+): (op: unknown, arg: unknown) => Promise<AppPageResult> {
+  const state = (): AppPageState => {
+    const id = ports.current()
+    const app = ports.storage.app(id)
+    return {
+      id,
+      name: app.name,
+      named: app.named === true,
+      others: ports.storage
+        .apps()
+        .filter((other) => other.id !== id)
+        .map((other) => ({ id: other.id, name: other.name, created: other.created })),
+      fileManager: fileManagerOf(ports.platform),
+      git: ports.git !== undefined,
+    }
+  }
+  const run = async (op: unknown, arg: unknown): Promise<unknown> => {
+    switch (op) {
+      case 'state':
+        return state()
+      case 'size':
+        return (await ports.storage.size(ports.current())) satisfies AppSize
+      case 'rename': {
+        if (typeof arg !== 'string') throw new Error('a name is text')
+        ports.renamed(ports.storage.rename(ports.current(), arg))
+        return state()
+      }
+      case 'reveal':
+        ports.storage.reveal(ports.current())
+        return undefined
+      case 'export': {
+        const data = (arg as { data?: unknown } | undefined)?.data === true
+        const id = ports.current()
+        const file = await ports.chooseExportFile(exportFileName(ports.storage.app(id).name))
+        if (file === undefined) return { cancelled: true }
+        ports.storage.export(id, file, { data })
+        return { file }
+      }
+      case 'import': {
+        const file = await ports.chooseImportFile()
+        if (file === undefined) return { cancelled: true }
+        // Made beside the running app, which keeps running until the new one is ready to open.
+        const made = ports.storage.import(file)
+        await ports.switchTo(() => ports.storage.open(made.id))
+        return undefined
+      }
+      case 'startOver': {
+        const id = ports.current()
+        await ports.switchTo(() => ports.storage.open(ports.storage.reset(id, ports.seed).id))
+        return undefined
+      }
+      case 'open': {
+        if (typeof arg !== 'string' || !ports.storage.apps().some((app) => app.id === arg))
+          throw new Error('there is no such app on this computer')
+        if (arg !== ports.current()) await ports.switchTo(() => ports.storage.open(arg))
+        return undefined
+      }
+      case 'gitLicence':
+      case 'gitSource': {
+        if (ports.git === undefined) throw new Error('this app ships no git of its own')
+        await ports.openPath(op === 'gitLicence' ? ports.git.licence : ports.git.source)
+        return undefined
+      }
+      default:
+        throw new Error(`the app page cannot ${String(op)}`)
+    }
+  }
+  return async (op, arg) => {
+    try {
+      return { ok: true, value: await run(op, arg) }
+    } catch (cause) {
+      return { ok: false, message: cause instanceof Error ? cause.message : String(cause) }
+    }
+  }
+}

package/plugins/desktop/brand.ts

@@ -0,0 +1,164 @@
+/**
+ * What a person sees of the running desktop app: its name and its icon. In development the window runs on the Electron that npm unpacked, so macOS labels the Dock
+ * and Cmd+Tab "Electron" and draws the atom, however the window is titled. The label and the icon come from the .app bundle, so on macOS the launcher runs a copy of
+ * that bundle under the app's own name with the app's icon: `<acryl root>/electron/<app id>.app`, made once (an APFS clone, so it costs no disk and no time),
+ * and again when the name or the icon changes. Linux and Windows start the stock Electron as before.
+ *
+ * The icon is the app's own `assets/icon.png` when it has one, else the ACRYL Blends logo that ships beside this file.
+ */
+import { execFileSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+
+/** The logo an app without an icon of its own shows. */
+export const DEFAULT_ICON = join(import.meta.dirname, 'assets', 'acrylblends-logo.png')
+
+/** The app's name as a person knows it: the package's name (the frame's header says the same), else the folder's. */
+export function appTitle(projectRoot: string): string {
+  try {
+    const manifest = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8')) as {
+      name?: unknown
+    }
+    if (typeof manifest.name === 'string' && manifest.name.trim() !== '')
+      return manifest.name.trim()
+  } catch {
+    // No manifest, or not JSON: the folder names the app.
+  }
+  return basename(resolve(projectRoot))
+}
+
+/** The icon file: the app's `assets/icon.png`, else the logo of ACRYL Blends. */
+export function iconFile(
+  projectRoot: string,
+  exists: (path: string) => boolean = existsSync,
+): string {
+  const own = join(projectRoot, 'assets', 'icon.png')
+  return exists(own) ? own : DEFAULT_ICON
+}
+
+/** The Info.plist keys that name the bundle. The identifier is per app, so two apps never share a Dock slot or a window state. */
+export function plistNames(name: string, id: string): Record<string, string> {
+  return {
+    CFBundleName: name,
+    CFBundleDisplayName: name,
+    CFBundleIdentifier: `com.acrylblends.app.${id}`,
+  }
+}
+
+/** The .app bundle around Electron's executable (`.../Electron.app/Contents/MacOS/Electron`), or undefined for a path of another shape. */
+export function bundleOf(binary: string): string | undefined {
+  const bundle = dirname(dirname(dirname(binary)))
+  return bundle.endsWith('.app') ? bundle : undefined
+}
+
+/** What the copy was made from: when this changes (a new name, a new icon, a new Electron), the copy is made again. */
+export function stampOf(name: string, id: string, icon: Uint8Array, electron: string): string {
+  return createHash('sha256')
+    .update(JSON.stringify([name, id, electron]))
+    .update(icon)
+    .digest('hex')
+}
+
+/** The iconset sizes macOS reads, as [file, pixels]. */
+const ICONSET: readonly (readonly [string, number])[] = [
+  ['icon_16x16.png', 16],
+  ['icon_16x16@2x.png', 32],
+  ['icon_32x32.png', 32],
+  ['icon_32x32@2x.png', 64],
+  ['icon_128x128.png', 128],
+  ['icon_128x128@2x.png', 256],
+  ['icon_256x256.png', 256],
+  ['icon_256x256@2x.png', 512],
+  ['icon_512x512.png', 512],
+]
+
+export interface BrandedElectron {
+  /** The executable to start: the branded copy's, or the stock one when a copy could not be made. */
+  readonly binary: string
+  /** Why the stock Electron runs, when it does on macOS. */
+  readonly problem?: string
+}
+
+/**
+ * The Electron executable to start. macOS: the branded copy of the bundle, made when missing or out of date. Anywhere else, or when the copy fails, the stock executable
+ * (a failure is returned, never thrown: a window with the wrong Dock label beats no window). `folder` is `<acryl root>/electron`; nothing is written outside it.
+ */
+export function brandedElectron(options: {
+  readonly binary: string
+  readonly folder: string
+  readonly id: string
+  readonly name: string
+  readonly icon: string
+  readonly platform?: NodeJS.Platform
+}): BrandedElectron {
+  const platform = options.platform ?? process.platform
+  const stock = { binary: options.binary }
+  if (platform !== 'darwin') return stock
+  const source = bundleOf(options.binary)
+  if (source === undefined) return stock
+  const target = join(options.folder, `${options.id}.app`)
+  const binary = join(target, 'Contents', 'MacOS', basename(options.binary))
+  try {
+    const version = execFileSync(
+      'plutil',
+      ['-extract', 'CFBundleVersion', 'raw', '-o', '-', join(source, 'Contents', 'Info.plist')],
+      { encoding: 'utf8' },
+    ).trim()
+    const stamp = stampOf(options.name, options.id, readFileSync(options.icon), version)
+    const stampFile = join(options.folder, `${options.id}.stamp`)
+    if (existsSync(binary) && readStamp(stampFile) === stamp) return { binary }
+    mkdirSync(options.folder, { recursive: true, mode: 0o700 })
+    rmSync(target, { recursive: true, force: true })
+    cloneBundle(source, target)
+    const plist = join(target, 'Contents', 'Info.plist')
+    for (const [key, value] of Object.entries(plistNames(options.name, options.id)))
+      execFileSync('plutil', ['-replace', key, '-string', value, plist])
+    const icns = join(target, 'Contents', 'Resources', 'electron.icns')
+    makeIcns(options.icon, icns, join(options.folder, `${options.id}.iconset`))
+    // The bundle's seal no longer matches its Info.plist and icon; a local ad-hoc signature makes it whole again so macOS has nothing to object to.
+    execFileSync('codesign', ['--force', '--deep', '--sign', '-', target], { stdio: 'ignore' })
+    writeFileSync(stampFile, stamp)
+    return { binary }
+  } catch (cause) {
+    return {
+      binary: options.binary,
+      problem: cause instanceof Error ? cause.message : String(cause),
+    }
+  }
+}
+
+function readStamp(file: string): string | undefined {
+  try {
+    return readFileSync(file, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+/** A copy of a bundle: an APFS clone where the volume allows it (instant, no extra disk), else a plain copy that keeps the symbolic links the bundle needs. */
+function cloneBundle(source: string, target: string): void {
+  try {
+    execFileSync('cp', ['-c', '-R', source, target])
+  } catch {
+    rmSync(target, { recursive: true, force: true })
+    cpSync(source, target, { recursive: true, verbatimSymlinks: true })
+  }
+}
+
+/** An .icns from one PNG: the iconset sizes by `sips`, then `iconutil`. The iconset folder is removed after. */
+function makeIcns(png: string, icns: string, iconset: string): void {
+  rmSync(iconset, { recursive: true, force: true })
+  mkdirSync(iconset, { recursive: true })
+  try {
+    for (const [file, pixels] of ICONSET)
+      execFileSync(
+        'sips',
+        ['-z', String(pixels), String(pixels), png, '--out', join(iconset, file)],
+        { stdio: 'ignore' },
+      )
+    execFileSync('iconutil', ['-c', 'icns', iconset, '-o', icns])
+  } finally {
+    rmSync(iconset, { recursive: true, force: true })
+  }
+}