acrylblends 1.4.0 → 1.5.0

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