acrylblends 1.1.0 → 1.3.0

package/plugins/builder/index.ts

@@ -5,12 +5,13 @@
  * extensions folder, installs it, and gets back the real result (`active`, `pending` with what it waits for, or the error, with the
  * previous version restored). Writes are confined to that folder. The tools register in `ctx.effect`, so they leave with the builder.
  */
-import { cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path'
 import type { Context } from '@deepseek-ai/cordis'
 import { scripted, type Tools } from '../agent/index.ts'
 import { NAME } from '../extensions/index.ts'
 import type {} from '../instance/index.ts'
+import { packagePlugin } from './package.ts'
 import { builderRules } from './script.ts'
 
 export interface BuilderConfig {
@@ -20,22 +21,6 @@ export interface BuilderConfig {
   packagesDir?: string
 }
 
-/** The package.json of a standalone plugin package: the host framework is a peer, never a second installed copy. */
-export function packageManifest(name: string, description: string): Record<string, unknown> {
-  return {
-    name,
-    version: '0.1.0',
-    description,
-    type: 'module',
-    exports: { '.': './index.ts', './package.json': './package.json' },
-    files: ['*.ts', '**/*.ts', 'README.md'],
-    // ACRYL measured it: a host package listed under dependencies brings a second copy of the framework, and its services stop
-    // matching after a restart. A peer names the version and installs nothing.
-    peerDependencies: { '@deepseek-ai/cordis': '4.0.4' },
-    keywords: ['cordis', 'cordis-plugin', 'acrylblends'],
-  }
-}
-
 const EXTENSIONS = new Set(['.ts', '.js', '.mjs', '.json', '.md'])
 const MAX_BYTES = 256 * 1024
 
@@ -154,8 +139,8 @@ export const builder = {
     )
     register(
       'package_plugin',
-      'Turn an extension into a standalone plugin package other apps can use: input { name, description? }. Returns its folder.',
-      (input) => {
+      'Turn an extension into a standalone plugin package other apps can pull: input { name, description? }. Writes the package folder and its release .tgz, the same bytes on every OS. Returns the folder, the file, its sha512 and its content digest.',
+      async (input) => {
         const name = pluginName(input)
         if (
           !existsSync(join(folder(name), 'index.ts')) &&
@@ -166,24 +151,17 @@ export const builder = {
         const description = String(
           (input as { description?: unknown }).description ?? `The ${name} Cordis plugin.`,
         )
-        const target = join(packagesDir, name)
-        rmSync(target, { recursive: true, force: true })
-        mkdirSync(packagesDir, { recursive: true })
-        cpSync(folder(name), target, {
-          recursive: true,
-          filter: (path) => !path.includes('node_modules'),
-        })
-        writeFileSync(
-          join(target, 'package.json'),
-          `${JSON.stringify(packageManifest(name, description), null, 2)}\n`,
-        )
-        if (!existsSync(join(target, 'README.md'))) {
-          writeFileSync(
-            join(target, 'README.md'),
-            `# ${name}\n\n${description}\n\nA Cordis plugin. In an ACRYLBLENDS app: \`acrylblends add <this folder>\`.\n`,
+        try {
+          return {
+            ok: true,
+            name,
+            ...(await packagePlugin(folder(name), packagesDir, name, description)),
+          }
+        } catch (cause) {
+          throw new BuilderError(
+            `${name}: ${cause instanceof Error ? cause.message : String(cause)}`,
           )
         }
-        return { ok: true, name, dir: target }
       },
     )
 

package/plugins/builder/package.ts

@@ -0,0 +1,186 @@
+/**
+ * Turning a plugin folder into what other people's apps can pull: a package folder and its release tarball, with the same bytes on every OS. The
+ * hub owns the tarball and the contract, blends-core what "portable" and "digest" mean; this module only decides what goes in.
+ */
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { extname, join } from 'node:path'
+import { digestFiles, pluginFiles, portabilityIssues } from '@webboxes/blends-core'
+import { packFolder, readTarball, syncServiceContract } from '@webboxes/plugin-hub'
+
+/** The package.json of a standalone plugin package: the host framework is a peer, never a second installed copy. */
+export function packageManifest(
+  name: string,
+  description: string,
+  version = '0.1.0',
+  release?: PackageRelease,
+): Record<string, unknown> {
+  return {
+    name,
+    version,
+    description,
+    ...(release === undefined
+      ? {}
+      : {
+          license: release.license,
+          repository: {
+            type: 'git',
+            url: `git+https://github.com/${release.owner}/${release.repo}.git`,
+          },
+        }),
+    type: 'module',
+    exports: { '.': './index.ts', './package.json': './package.json' },
+    // No `files` list: a plugin's plugin.json, data and .js files go with it, and the packer's own skips (node_modules, .git) apply.
+    // ACRYL measured it: a host package listed under dependencies brings a second copy of the framework, and its services stop
+    // matching after a restart. A peer names the version and installs nothing.
+    peerDependencies: { '@deepseek-ai/cordis': '4.0.4' },
+    keywords: ['cordis', 'cordis-plugin', 'acrylblends'],
+  }
+}
+
+/** Where a package is going to be released: written in now, so what is planned is byte for byte what is released. */
+export interface PackageRelease {
+  readonly owner: string
+  readonly repo: string
+  readonly license: string
+}
+
+export interface PackageOptions {
+  /** This version, instead of the one already packaged. */
+  readonly version?: string
+  readonly release?: PackageRelease
+}
+
+export interface PackagedPlugin {
+  readonly dir: string
+  readonly version: string
+  readonly files: readonly string[]
+  /** The release file, next to the package folder. */
+  readonly tarball: string
+  /** The tarball's sha512, as the registry lists it. */
+  readonly integrity: string
+  /** The sha256 of the plugin's content, which a source can name (`@sha256:<digest>`). */
+  readonly digest: string
+}
+
+/** Text whose line endings an editor or git on Windows may change: LF in the package, so those endings are not part of the plugin's identity. */
+const TEXT = new Set([
+  '.ts',
+  '.mts',
+  '.cts',
+  '.tsx',
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.jsx',
+  '.json',
+  '.md',
+  '.txt',
+  '.css',
+  '.html',
+  '.yml',
+  '.yaml',
+  '.svg',
+])
+
+function withLineFeeds(dir: string): void {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) withLineFeeds(path)
+    else if (entry.isFile() && TEXT.has(extname(entry.name).toLowerCase())) {
+      const text = readFileSync(path, 'utf8')
+      if (text.includes('\r\n')) writeFileSync(path, text.replaceAll('\r\n', '\n'))
+    }
+  }
+}
+
+/** What the hub's share would otherwise add on the way out, changing the bytes after they were planned. */
+function markPublic(target: string): void {
+  const file = join(target, 'package.json')
+  const manifest = JSON.parse(readFileSync(file, 'utf8')) as Record<string, unknown>
+  writeFileSync(
+    file,
+    `${JSON.stringify({ ...manifest, acryl: { ...(manifest.acryl as object), visibility: 'public' } }, null, 2)}\n`,
+  )
+}
+
+function versionIn(target: string): string | undefined {
+  try {
+    const { version } = JSON.parse(readFileSync(join(target, 'package.json'), 'utf8')) as {
+      version?: unknown
+    }
+    return typeof version === 'string' ? version : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Package the plugin in `source` as `<packages>/<name>/` and `<packages>/<name>-<version>.tgz`. The person's folder is not touched. A version already
+ * packaged stays: a release is made once, and a person bumps it deliberately.
+ * @throws when the plugin would not work on every OS or its contract cannot be read; no package is left.
+ */
+export async function packagePlugin(
+  source: string,
+  packages: string,
+  name: string,
+  description: string,
+  options: PackageOptions = {},
+): Promise<PackagedPlugin> {
+  const target = join(packages, name)
+  const version = options.version ?? versionIn(target)
+  rmSync(target, { recursive: true, force: true })
+  mkdirSync(packages, { recursive: true })
+  cpSync(source, target, { recursive: true, filter: (path) => !path.includes('node_modules') })
+  try {
+    writeFileSync(
+      join(target, 'package.json'),
+      `${JSON.stringify(packageManifest(name, description, version, options.release), null, 2)}\n`,
+    )
+    if (!existsSync(join(target, 'README.md'))) {
+      writeFileSync(
+        join(target, 'README.md'),
+        `# ${name}\n\n${description}\n\nA Cordis plugin. Once it is released, pull it into an ACRYLBLENDS app while that app runs (\`npm run dev\`): \`npm run acryl -- plugin pull github:<owner>/<repo>\`.\n`,
+      )
+    }
+    withLineFeeds(target)
+    const issues = portabilityIssues(pluginFiles(target))
+    if (issues.length > 0)
+      throw new Error(
+        `it would not work on every OS: ${issues.map((issue) => `${issue.path}: ${issue.reason}`).join('; ')}`,
+      )
+    // The contract other people's apps and the registry read: what the plugin needs and provides, from its code.
+    const contract = await syncServiceContract(target)
+    if (!contract.ok)
+      throw new Error(`its service contract cannot be read: ${contract.errors.join('; ')}`)
+    if (options.release !== undefined) markPublic(target)
+    const packed = packFolder(target)
+    const tarball = join(packages, packed.fileName)
+    writeFileSync(tarball, packed.tarball)
+    const digest = digestFiles(
+      readTarball(packed.tarball).map(({ path, content }) => ({
+        path,
+        bytes: content,
+        kind: 'file' as const,
+      })),
+    )
+    return {
+      dir: target,
+      version: packed.version,
+      files: packed.files,
+      tarball,
+      integrity: packed.integrity,
+      digest,
+    }
+  } catch (cause) {
+    rmSync(target, { recursive: true, force: true })
+    throw cause
+  }
+}

package/plugins/builder/plugin.json

@@ -5,7 +5,9 @@
   "inject": ["extensions", "tools", "appInstance"],
   "provides": [],
   "dependencies": {
-    "@deepseek-ai/cordis": "4.0.4"
+    "@deepseek-ai/cordis": "4.0.4",
+    "@webboxes/blends-core": "0.5.0",
+    "@webboxes/plugin-hub": "0.2.0"
   },
   "mount": "mount it after agent and extensions: root.plugin(builder, { dir: join(root, 'plugins') }); dir must be an extensions source"
 }

package/plugins/desktop/frame.ts

@@ -0,0 +1,231 @@
+/**
+ * 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
+ * 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'
+
+/** 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')
+
+/** The line the host prints once it serves the frame, with the launch token in the address. */
+const HOST_LINE = /acrylblends host: (http:\/\/\S+)/u
+
+const LOOPBACK = new Set(['127.0.0.1', 'localhost', '[::1]'])
+
+/** How long a stopping host gets before its tree is killed. */
+export const HOST_STOP_GRACE_MS = 5_000
+
+export function isFrameApp(root: string, exists: (path: string) => boolean = existsSync): boolean {
+  return exists(join(root, HOST_SCRIPT))
+}
+
+/** The app home the host uses: `ACRYLBLENDS_HOME` when set, else `<app>/.acrylblends` (the launcher's own rule). */
+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')
+    : resolve(pinned)
+}
+
+/** The frame address in the host's output so far, or `undefined` while it has not printed it. */
+export function hostAddress(output: string): string | undefined {
+  return HOST_LINE.exec(output)?.[1]
+}
+
+/** A loopback `http:` address, or `undefined` for anything else: the window only ever opens a frame on this machine. */
+export function loopbackAddress(url: unknown): URL | undefined {
+  if (typeof url !== 'string') return undefined
+  try {
+    const parsed = new URL(url)
+    return parsed.protocol === 'http:' && LOOPBACK.has(parsed.hostname) ? parsed : undefined
+  } catch {
+    return undefined
+  }
+}
+
+export interface RecordDeps {
+  readonly read?: (file: string) => string
+  /** Whether something accepts a connection at the address. */
+  readonly listening?: (url: URL) => Promise<boolean>
+}
+
+const tcpListening = (url: URL, timeoutMs = 500): Promise<boolean> =>
+  new Promise((done) => {
+    const socket = connect({
+      host: url.hostname.replace(/^\[|\]$/gu, ''),
+      port: Number(url.port || 80),
+    })
+    const finish = (listening: boolean) => {
+      socket.destroy()
+      done(listening)
+    }
+    socket.setTimeout(timeoutMs)
+    socket.once('connect', () => finish(true))
+    socket.once('timeout', () => finish(false))
+    socket.once('error', () => finish(false))
+  })
+
+/**
+ * The frame that already runs for this app: the host's address record, when it names a loopback address and something listens there. A record a stopped host
+ * left behind is not a running frame.
+ */
+export async function runningFrame(
+  home: string,
+  deps: RecordDeps = {},
+): Promise<string | undefined> {
+  const read = deps.read ?? ((file: string) => readFileSync(file, 'utf8'))
+  let record: { url?: unknown }
+  try {
+    record = JSON.parse(read(join(home, 'frame-url.json'))) as { url?: unknown }
+  } catch {
+    return undefined
+  }
+  const url = loopbackAddress(record.url)
+  if (url === undefined) return undefined
+  return (await (deps.listening ?? tcpListening)(url)) ? url.href : undefined
+}
+
+/** An address as the door may show it: the frame's launch token removed (the token is the way into the frame, so it never goes to a log). */
+export function withoutToken(href: string): string {
+  try {
+    const parsed = new URL(href)
+    if (!parsed.searchParams.has('token')) return href
+    parsed.searchParams.delete('token')
+    return parsed.href
+  } catch {
+    return href
+  }
+}
+
+/**
+ * What the Settings... menu item runs in a frame window: the window event the page's root owner opens its own Settings on (`acryl-blends-frame`'s
+ * `OPEN_SETTINGS_EVENT`, and the IDE's `acryl-workspace`; keep the string in step). The same dialog as the top bar's gear, never a second one.
+ */
+export const openFrameSettings = "window.dispatchEvent(new Event('acryl:open-settings'))"
+
+/** What the window does with a navigation: stay on the frame's origin, hand the address to the system browser, or refuse it. */
+export type Navigation = 'stay' | 'external' | 'block'
+
+/**
+ * ACRYL Desktop's rule (`electron-shell-generation.ts`): only the main frame is checked, so the frame's tiles (the app's page in an iframe) navigate freely;
+ * the frame's own origin stays in the window, an `http(s)` or `mailto` address goes to the system browser, anything else is refused.
+ */
+export function navigation(target: string, origin: string, mainFrame = true): Navigation {
+  if (!mainFrame) return 'stay'
+  let parsed: URL
+  try {
+    parsed = new URL(target)
+  } catch {
+    return 'block'
+  }
+  if (parsed.origin === origin) return 'stay'
+  return parsed.protocol === 'http:' ||
+    parsed.protocol === 'https:' ||
+    parsed.protocol === 'mailto:'
+    ? 'external'
+    : 'block'
+}
+
+/** How the host is started: the npm and Node that ran `npm run desktop`, never Electron's Node (node-pty and DSH's rows are built for Node's ABI). */
+export function hostCommand(
+  env: Record<string, string | undefined>,
+  platform: NodeJS.Platform,
+): { file: string; args: string[]; shell: boolean } {
+  const node = env.npm_node_execpath
+  const npm = env.npm_execpath
+  if (node !== undefined && node !== '' && npm !== undefined && npm !== '')
+    return /\.c?js$/u.test(npm)
+      ? { file: node, args: [npm, 'run', 'dev'], shell: false }
+      : { file: npm, args: ['run', 'dev'], shell: platform === 'win32' }
+  // Started without npm (Electron run by hand): npm from the PATH, `npm.cmd` through the shell on Windows (scripts/lib/platform.mjs, npmSpawn).
+  return platform === 'win32'
+    ? { file: 'npm.cmd', args: ['run', 'dev'], shell: true }
+    : { file: 'npm', args: ['run', 'dev'], shell: false }
+}
+
+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>
+  /** Stop the host and what it started; resolves once it has exited. */
+  stop(): Promise<void>
+}
+
+/** 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,
+): FrameHost {
+  const command = hostCommand(env, platform)
+  // 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 },
+    stdio: ['ignore', 'pipe', 'pipe'],
+    shell: command.shell,
+    detached: platform !== 'win32',
+    windowsHide: true,
+  })
+  let output = ''
+  let exited = false
+  const exit = new Promise<void>((done) => {
+    child.once('exit', () => {
+      exited = true
+      done()
+    })
+    child.once('error', () => {
+      exited = true
+      done()
+    })
+  })
+  const ready = new Promise<string>((done, fail) => {
+    const take = (chunk: Buffer) => {
+      const text = chunk.toString()
+      write(text)
+      if (output.length < 200_000) output += text
+      const address = hostAddress(output)
+      if (address !== undefined) done(address)
+    }
+    child.stdout?.on('data', take)
+    child.stderr?.on('data', take)
+    void exit.then(() =>
+      fail(new Error(`the frame host ended before it served the frame:\n${output.slice(-3000)}`)),
+    )
+  })
+  const signal = (name: NodeJS.Signals) => {
+    if (child.pid === undefined) return
+    // Windows has no process groups and no SIGTERM a console process can answer: the whole tree (npm, the host, its terminals) is ended at once.
+    if (platform === 'win32') {
+      spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], {
+        stdio: 'ignore',
+        windowsHide: true,
+      })
+      return
+    }
+    try {
+      process.kill(-child.pid, name)
+    } catch {
+      // The group is already gone.
+    }
+  }
+  return {
+    ready,
+    async stop() {
+      if (exited) return
+      signal('SIGTERM')
+      const graceful = await Promise.race([
+        exit.then(() => true),
+        new Promise<boolean>((done) => setTimeout(() => done(false), HOST_STOP_GRACE_MS).unref()),
+      ])
+      if (!graceful) {
+        signal('SIGKILL')
+        await exit
+      }
+    },
+  }
+}

package/plugins/desktop/launch.ts

@@ -3,7 +3,7 @@
  * (Ubuntu 23.10 and later: `kernel.apparmor_restrict_unprivileged_userns=1`), Chromium's sandbox cannot start for an Electron that npm unpacked into node_modules, and Electron
  * aborts before any of our code runs. There, and only there, it starts with `--no-sandbox` and says so; everywhere else Electron starts exactly as it does with the sandbox on.
  */
-import { spawn } from 'node:child_process'
+import { type ChildProcess, spawn } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { join } from 'node:path'
@@ -29,9 +29,45 @@ export const SANDBOX_NOTICE =
   "desktop: this Linux restricts unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1), so Electron's sandbox cannot start; starting with --no-sandbox. " +
   'To keep the sandbox, give Electron an AppArmor profile that allows `userns` (the way the VS Code and Chrome packages do): see docs/framework/getting-started/desktop.md'
 
-/** The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. */
-export function electronArgs(entry: string, blocked: boolean): string[] {
-  return blocked ? ['--no-sandbox', entry] : [entry]
+/**
+ * The arguments for Electron: the entry file, with `--no-sandbox` first when the sandbox is blocked. Chromium switches given to the script
+ * (`npm run desktop -- --remote-debugging-port=9222`) go before the entry; anything that is not a switch is dropped.
+ */
+export function electronArgs(
+  entry: string,
+  blocked: boolean,
+  extra: readonly string[] = [],
+): string[] {
+  const switches = extra.filter((arg) => /^--[a-z][a-z0-9-]*(=.*)?$/u.test(arg))
+  return [...(blocked ? ['--no-sandbox'] : []), ...switches, entry]
+}
+
+/** The signals the launcher hands to Electron: Ctrl-C, a stop, and the terminal closing. */
+export const FORWARDED_SIGNALS = ['SIGINT', 'SIGTERM', 'SIGHUP'] as const
+
+/**
+ * Start Electron and make it end the way it was asked to. On macOS and Linux Electron leads its own process group, so a terminal's Ctrl-C (which goes to the
+ * whole foreground group) reaches only this launcher, which hands Electron exactly one signal. Electron answers a first SIGINT, SIGTERM or SIGHUP with a
+ * graceful quit, the one that stops the frame host the window started; a second signal kills it at once, before any of that runs, and a Ctrl-C that reached
+ * both processes was two, as is one that npm passes on after the terminal sent it. Later signals are not passed on. Windows has no process groups and no such signals; there Electron starts as before. This process ends with Electron's exit code.
+ */
+export function runElectron(
+  file: string,
+  args: readonly string[],
+  platform: NodeJS.Platform = process.platform,
+): ChildProcess {
+  const child = spawn(file, args, { stdio: 'inherit', detached: platform !== 'win32' })
+  // One signal, ever: npm hands a Ctrl-C to this process a second time, and Electron's quit is bounded (DESKTOP_SHUTDOWN_TIMEOUT_MS) without another.
+  let forwarded = false
+  for (const signal of FORWARDED_SIGNALS)
+    if (platform !== 'win32' || signal !== 'SIGHUP')
+      process.on(signal, () => {
+        if (forwarded) return
+        forwarded = true
+        child.kill(signal)
+      })
+  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+  return child
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
@@ -40,9 +76,8 @@ 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)
-  const child = spawn(electron, electronArgs(join(import.meta.dirname, 'main.ts'), blocked), {
-    stdio: 'inherit',
-  })
-  for (const signal of ['SIGINT', 'SIGTERM'] as const) process.on(signal, () => child.kill(signal))
-  child.on('exit', (code, signal) => process.exit(code ?? (signal ? 1 : 0)))
+  runElectron(
+    electron,
+    electronArgs(join(import.meta.dirname, 'main.ts'), blocked, process.argv.slice(2)),
+  )
 }