acrylblends 1.4.0 → 1.5.1

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 })
+  }
+}

package/plugins/desktop/frame.ts

@@ -1,12 +1,14 @@
 /**
  * The desktop window on the ACRYL frame (docs/plans/ide-host-inversion.md, section 27). An app with `scripts/ide-host.mjs` runs inside the frame on `npm run dev`;
- * `npm run desktop` shows that same frame: it attaches to a host that already runs (the host's address record, `.acrylblends/frame-url.json`), or starts the host
+ * `npm run desktop` shows that same frame: it attaches to a host that already runs (the host's address record, `frame-url.json` in the app's data folder), or starts the host
  * the way `npm run dev` does and loads the address it prints. Nothing here imports electron: `main.ts` decides with these functions and owns the window.
  */
 import { type ChildProcess, spawn, spawnSync } from 'node:child_process'
 import { existsSync, readFileSync } from 'node:fs'
 import { connect } from 'node:net'
 import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { appDataHome } from '../instance/index.ts'
 
 /** The launcher every frame app has; without it the app runs on its own server (made before the frame). */
 export const HOST_SCRIPT = join('scripts', 'ide-host.mjs')
@@ -23,11 +25,11 @@ export function isFrameApp(root: string, exists: (path: string) => boolean = exi
   return exists(join(root, HOST_SCRIPT))
 }
 
-/** The app home the host uses: `ACRYLBLENDS_HOME` when set, else `<app>/.acrylblends` (the launcher's own rule). */
+/** The app home the host uses: `ACRYLBLENDS_HOME` when set, else the app's data folder under ~/.acryl (`appDataHome`, the one place that decides it). */
 export function frameHome(root: string, env: Record<string, string | undefined>): string {
   const pinned = env.ACRYLBLENDS_HOME?.trim()
   return pinned === undefined || pinned === ''
-    ? join(resolve(root), '.acrylblends')
+    ? appDataHome(resolve(root), process.platform, env)
     : resolve(pinned)
 }
 
@@ -147,25 +149,93 @@ export function hostCommand(
     : { file: 'npm', args: ['run', 'dev'], shell: false }
 }
 
+/** How a host ended: its exit, the last of its output, and whether the window asked for it (`stop`) or it ended by itself. */
+export interface HostEnd {
+  readonly code: number | null
+  readonly signal: NodeJS.Signals | null
+  readonly tail: string
+  readonly requested: boolean
+}
+
 export interface FrameHost {
   /** The frame address the host printed, or a rejection with the host's output when it ended first. */
   readonly ready: Promise<string>
+  /** Resolves once, when the host has ended, whenever that is: after it served the frame too (a stop it did not get asked for is a death). */
+  readonly ended: Promise<HostEnd>
   /** Stop the host and what it started; resolves once it has exited. */
   stop(): Promise<void>
 }
 
+export interface FrameHostLaunch {
+  /**
+   * A packaged product has no npm to run `npm run dev` with: the host runs on the app's own Electron runtime as Node, with the same loader the dev script uses.
+   */
+  readonly runtime?: string
+  /**
+   * Where the Program is when it is not in the app folder: a product's bundle. The host, its loader and the resolver that serves the Program from there
+   * and the person's files from the app's source (plugins/instance/bundle-overlay.ts) start from it; the host still runs in the app folder.
+   */
+  readonly program?: string
+}
+
+/**
+ * What a packaged host watches: the person's own files that make the app, and nothing else. `node --watch` alone follows only the modules the host has loaded,
+ * so a new plugin folder, or a row added to `blend.yaml`, stayed unseen until some loaded file changed (found on a packed app: a plugin written into
+ * `plugins/notes/` was not served after 15 s). Naming a path turns the module watching off, so the folders are named whole; `.git` (a commit must not restart
+ * the app) and the app's data are not among them.
+ */
+export const WATCHED_IN_SOURCE = ['src', 'plugins', 'blend.yaml'] as const
+
+/**
+ * The arguments of a packaged product's host (the runtime is Electron as Node): `--watch` first, as the app's `dev` script has it, so a saved change in the
+ * person's source or plugins restarts the host and the app shows it, with no extensions plugin in the frame to do it (found on a packed app: an edit of
+ * `src/routes.ts` stayed unseen until the app was quit). Then the loader and, when the Program is in a bundle, the overlay that serves it.
+ */
+export function packagedHostArgs(
+  program: string,
+  root: string,
+  exists: (path: string) => boolean = existsSync,
+): string[] {
+  return [
+    '--watch',
+    ...WATCHED_IN_SOURCE.map((name) => join(root, name))
+      .filter((path) => exists(path))
+      .map((path) => `--watch-path=${path}`),
+    // The loader first and the overlay second: a hook registered later runs first, so the overlay sees every import before the loader's aliases.
+    '--import',
+    pathToFileURL(join(program, 'plugins', 'acryl-node-server', 'src', 'register.ts')).href,
+    ...(program === root
+      ? []
+      : [
+          '--import',
+          pathToFileURL(join(program, 'plugins', 'instance', 'bundle-overlay.ts')).href,
+        ]),
+    join(program, HOST_SCRIPT),
+  ]
+}
+
 /** Start the app's frame host as `npm run dev` does, in the app folder; its output is passed through to `write`. */
 export function startFrameHost(
   root: string,
   env: NodeJS.ProcessEnv,
   write: (text: string) => void,
   platform: NodeJS.Platform = process.platform,
+  launch: FrameHostLaunch = {},
 ): FrameHost {
-  const command = hostCommand(env, platform)
+  const program = launch.program ?? root
+  const command =
+    launch.runtime === undefined
+      ? hostCommand(env, platform)
+      : { file: launch.runtime, args: packagedHostArgs(program, root), shell: false }
   // The host leads its own process group on macOS and Linux, so a stop reaches npm, the host and every terminal it runs; Windows stops the tree with taskkill.
   const child: ChildProcess = spawn(command.file, command.args, {
     cwd: root,
-    env: { ...env, ELECTRON_RUN_AS_NODE: undefined },
+    env: {
+      ...env,
+      ...(launch.runtime === undefined
+        ? { ELECTRON_RUN_AS_NODE: undefined }
+        : { ELECTRON_RUN_AS_NODE: '1' }),
+    },
     stdio: ['ignore', 'pipe', 'pipe'],
     shell: command.shell,
     detached: platform !== 'win32',
@@ -173,16 +243,21 @@ export function startFrameHost(
   })
   let output = ''
   let exited = false
+  let requested = false
+  let outcome: Pick<HostEnd, 'code' | 'signal'> = { code: null, signal: null }
   const exit = new Promise<void>((done) => {
-    child.once('exit', () => {
+    child.once('exit', (code, signal) => {
       exited = true
+      outcome = { code, signal }
       done()
     })
-    child.once('error', () => {
+    child.once('error', (cause) => {
       exited = true
+      output += `\n${cause.message}`
       done()
     })
   })
+  const ended = exit.then((): HostEnd => ({ ...outcome, tail: output.slice(-3000), requested }))
   const ready = new Promise<string>((done, fail) => {
     const take = (chunk: Buffer) => {
       const text = chunk.toString()
@@ -213,9 +288,15 @@ export function startFrameHost(
       // The group is already gone.
     }
   }
+  // What the host left running (its terminals, the watcher's child) does not outlive a host that ended by itself.
+  void exit.then(() => {
+    if (!requested) signal('SIGTERM')
+  })
   return {
     ready,
+    ended,
     async stop() {
+      requested = true
       if (exited) return
       signal('SIGTERM')
       const graceful = await Promise.race([

package/plugins/desktop/git.ts

@@ -0,0 +1,44 @@
+/**
+ * The git a desktop product ships (desktop/dugite-native, packed by scripts/pack-blank-mac.mjs into `Resources/git`, beside the app). A clean Mac has only
+ * the shim that asks to install the Command Line Tools, and Windows has no git, while versions, export, the terminals and every agent run `git`. The
+ * frame host gets it first on its PATH, so everything it starts (versions, the workspace's git, terminals, the chat's shell, PTY agents) finds the same git
+ * by name. Outside a product, or in a product packed without it, the person's own git is used as before.
+ */
+
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface ProductGit {
+  /** The executable to run (on macOS and Linux a wrapper that finds git's helpers from where it lies). */
+  readonly executable: string
+  /** The folder to put first on PATH. */
+  readonly bin: string
+  /** Git's licence and the offer of its source, shown from Settings > App. */
+  readonly licence: string
+  readonly source: string
+}
+
+/** The product's git under `resources` (Electron's `process.resourcesPath`), or undefined when the product carries none. */
+export function productGit(resources: string, platform: NodeJS.Platform): ProductGit | undefined {
+  const dir = join(resources, 'git')
+  // dugite-native's Windows build is MinGit: `cmd/git.exe` finds its own helpers.
+  const bin = join(dir, platform === 'win32' ? 'cmd' : 'bin')
+  const executable = join(bin, platform === 'win32' ? 'git.exe' : 'git')
+  if (!existsSync(executable)) return undefined
+  return { executable, bin, licence: join(dir, 'COPYING.txt'), source: join(dir, 'SOURCE.txt') }
+}
+
+/** `env` with the product's git first on its PATH (Windows names the variable `Path`, in any case; the existing name is kept). */
+export function withGitFirst(
+  env: Readonly<Record<string, string | undefined>>,
+  git: ProductGit,
+  platform: NodeJS.Platform,
+): Record<string, string | undefined> {
+  const key =
+    platform === 'win32'
+      ? (Object.keys(env).find((name) => name.toUpperCase() === 'PATH') ?? 'Path')
+      : 'PATH'
+  const separator = platform === 'win32' ? ';' : ':'
+  const rest = (env[key] ?? '').split(separator).filter((dir) => dir !== '' && dir !== git.bin)
+  return { ...env, [key]: [git.bin, ...rest].join(separator) }
+}

package/plugins/desktop/host-supervisor.ts

@@ -0,0 +1,63 @@
+/**
+ * What the window does when its frame host stops by itself (found on an installed app 2026-11-09: the host had ended days before, nothing restarted it, and
+ * the window kept asking a closed port, a thousand errors and a dead page). Two small rules, both pure of Electron so they are tested without a window:
+ * when to start the host again, and where its output is kept so the next stop has a cause on disk.
+ */
+import { appendFileSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+export interface RestartPolicy {
+  /** Stops inside `windowMs` that are forgiven; one more and the host is not started again by itself. */
+  readonly maxInWindow: number
+  readonly windowMs: number
+  /** The wait before the n-th restart inside the window: short first, then longer. */
+  readonly delaysMs: readonly number[]
+}
+
+export const RESTART_POLICY: RestartPolicy = Object.freeze({
+  maxInWindow: 4,
+  windowMs: 120_000,
+  delaysMs: [500, 2_000, 5_000, 10_000],
+})
+
+export type RestartDecision = { restart: true; delayMs: number } | { restart: false }
+
+/** `stops` are the times (ms) the host stopped by itself, oldest or newest first; those older than the window are forgotten. */
+export function nextRestart(
+  stops: readonly number[],
+  now: number,
+  policy: RestartPolicy = RESTART_POLICY,
+): RestartDecision {
+  const recent = stops.filter((at) => now - at < policy.windowMs).length
+  if (recent >= policy.maxInWindow) return { restart: false }
+  return {
+    restart: true,
+    delayMs: policy.delaysMs[Math.min(recent, policy.delaysMs.length - 1)] ?? 0,
+  }
+}
+
+const KEEP_DAYS = 14
+
+/** The host's output, one file a day (`host-YYYY-MM-DD.log`) in the app's logs folder; files older than two weeks go. Never throws: a log must not stop the app. */
+export function appendHostLog(dir: string, text: string, now: Date = new Date()): void {
+  try {
+    mkdirSync(dir, { recursive: true })
+    appendFileSync(join(dir, `host-${now.toISOString().slice(0, 10)}.log`), text)
+    for (const name of readdirSync(dir)) {
+      if (!/^host-\d{4}-\d{2}-\d{2}\.log$/u.test(name)) continue
+      const file = join(dir, name)
+      if (now.getTime() - statSync(file).mtimeMs > KEEP_DAYS * 86_400_000)
+        rmSync(file, { force: true })
+    }
+  } catch {
+    // The disk is full or the folder is gone: the host goes on.
+  }
+}
+
+/**
+ * `node --watch` does not end when the host it runs crashes: it prints this line and waits for a saved file (reproduced on a packed app by killing the host's
+ * child: the watcher stayed, the port was closed, nothing answered and nothing restarted). So the window reads the line as the host's death.
+ */
+export function hostCrashed(output: string): boolean {
+  return /Failed running '/u.test(output)
+}

package/plugins/desktop/launch.ts

@@ -8,6 +8,8 @@ import { readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { acrylRoot, appIdOf, personHome } from '../instance/home.ts'
+import { appTitle, brandedElectron, iconFile } from './brand.ts'
 
 /** The sysctl that makes the sandbox fail for an Electron without an AppArmor profile; its value, or `undefined` where it does not exist (every system but a recent Ubuntu). */
 export const RESTRICT_USERNS = '/proc/sys/kernel/apparmor_restrict_unprivileged_userns'
@@ -76,8 +78,22 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
   const blocked =
     process.env.ACRYLBLENDS_DESKTOP_SANDBOX !== '1' && sandboxBlocked(process.platform)
   if (blocked) console.warn(SANDBOX_NOTICE)
+  // macOS: the Dock and Cmd+Tab name the app and draw its icon only when the bundle says so (brand.ts); a copy that cannot be made leaves the stock Electron, with a note.
+  const projectRoot = fileURLToPath(new URL('../..', import.meta.url))
+  const branded = brandedElectron({
+    binary: electron,
+    folder: join(
+      acrylRoot(process.platform, process.env, personHome(process.env, process.platform)),
+      'electron',
+    ),
+    id: appIdOf(projectRoot),
+    name: appTitle(projectRoot),
+    icon: iconFile(projectRoot),
+  })
+  if (branded.problem !== undefined)
+    console.warn(`desktop: the Dock shows Electron's own name and icon (${branded.problem})`)
   runElectron(
-    electron,
+    branded.binary,
     electronArgs(join(import.meta.dirname, 'main.ts'), blocked, process.argv.slice(2)),
   )
 }