sideby 0.0.0-stage → 0.2.1

package/dist/src/panel/page.js

@@ -0,0 +1,96 @@
+// The Panel page: one self-contained HTML document with inline CSS and JS, no external resources. The parts live in
+// sibling modules: page-styles.ts (tokens and CSS), page-script.ts (behaviour, with page-logic.ts helpers) and
+// i18n.ts (English and Chinese text); this module assembles them under the CSP nonce.
+import { ALIAS_NAME, RESERVED_ALIASES } from '../core/config.js';
+import { QUOTA_FAIL_PERCENT, QUOTA_WARN_PERCENT, USAGE_DAYS } from '../core/quota-levels.js';
+import { MESSAGES } from './i18n.js';
+import { PAGE_SCRIPT } from './page-script.js';
+import { pageStyles } from './page-styles.js';
+import { resolveTheme } from './theme.js';
+export { pageStyles };
+/** JSON that is safe inside a `<script>` element: no `</script>`, `<!--` or line separators survive. */
+export function jsonForScript(value) {
+    return JSON.stringify(value)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026')
+        .replace(/\u2028/g, '\\u2028')
+        .replace(/\u2029/g, '\\u2029');
+}
+function attr(value) {
+    return value.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
+}
+const SKELETON_ROW = `<div class="sk-row"><span class="sk sk-badge"></span><span class="sk sk-title"></span><span class="sk sk-bar"></span><span class="sk sk-bar"></span></div>`;
+const SKELETON_STAT = `<div class="stat"><span class="sk sk-stat w70"></span></div>`;
+export function renderPage(opts) {
+    const nonce = opts.nonce ? ` nonce="${attr(opts.nonce)}"` : '';
+    const theme = opts.theme ?? resolveTheme(undefined);
+    const scheme = theme.colorScheme === 'auto' ? 'light dark' : theme.colorScheme;
+    const lang = opts.lang ?? 'auto';
+    const boot = jsonForScript({
+        basePath: opts.basePath,
+        token: opts.token,
+        version: opts.version ?? '',
+        build: opts.build ?? '',
+        readOnly: Boolean(opts.readOnly),
+        colorScheme: theme.colorScheme,
+        lang,
+        warn: QUOTA_WARN_PERCENT,
+        fail: QUOTA_FAIL_PERCENT,
+        usageDays: USAGE_DAYS,
+        // The alias rules of the config, so the new-account dialog checks a short command as sideby will.
+        aliasPattern: ALIAS_NAME.source,
+        reservedAliases: [...RESERVED_ALIASES],
+    });
+    return `<!doctype html>
+<html lang="${lang === 'zh' ? 'zh-CN' : 'en'}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="${scheme}">
+<meta name="referrer" content="no-referrer">
+<title>sideby</title>
+<link rel="icon" href="data:,">
+<style${nonce}>${pageStyles(theme)}</style>
+</head>
+<body${theme.header === 'bar' ? ' class="header-bar"' : ''}>
+<header class="top">
+  <div class="top-in">
+    <div class="brand">
+      <span class="logo" aria-hidden="true"><svg viewBox="0 0 40 40"><path d="M18.5 8A10.5 10.5 0 0 0 18.5 29Z"/><path d="M21.5 11A10.5 10.5 0 0 1 21.5 32Z" fill-opacity=".55"/></svg></span>
+      <div>
+        <h1>sideby</h1>
+        <p class="tagline" data-i18n="top.tagline">Every AI coding account, side by side.</p>
+      </div>
+    </div>
+    <div class="top-actions">
+      <span id="updated" class="muted small">Loading…</span>
+      <button id="lang" class="icon-btn lang-btn" type="button"${lang === 'auto' ? '' : ' hidden'}>${lang === 'zh' ? 'EN' : '中文'}</button>
+      <button id="theme" class="icon-btn" type="button" hidden></button>
+      <button id="refresh" class="btn" type="button" aria-label="Refresh"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M20 11a8 8 0 1 0-2.3 5.7"/><path d="M20 4v7h-7"/></svg><span class="hide-sm" data-i18n="top.refresh">Refresh</span></button>
+    </div>
+  </div>
+</header>
+<main class="wrap">
+  <div id="banners"></div>
+  <section id="summary" class="summary" aria-busy="true">${SKELETON_STAT.repeat(4)}</section>
+  <section class="block" aria-labelledby="h-accounts">
+    <div class="section-head acct-head"><h2 id="h-accounts"><span data-i18n="acct.title">Accounts</span><span id="acct-count" class="muted small"></span></h2></div>
+    <div id="toolbar" class="toolbar" hidden></div>
+    <div id="accounts" aria-busy="true"><div class="group group-list">${SKELETON_ROW.repeat(4)}</div></div>
+  </section>
+  <section id="checkup" class="panel checkup" aria-labelledby="h-checkup">
+    <div class="section-head"><h2 id="h-checkup" data-i18n="health.title">Health check</h2></div>
+    <span class="sk sk-line w70"></span><span class="sk sk-line w50"></span>
+  </section>
+  <footer class="foot muted small">sideby <span id="ver"></span> · <span data-i18n="foot.text">runs on this machine; nothing leaves it.</span></footer>
+</main>
+<div id="conn" class="conn" role="status" hidden></div>
+<div id="toasts" class="toasts" aria-live="polite" popover="manual"></div>
+<script type="application/json" id="sideby-boot">${boot}</script>
+<script type="application/json" id="sideby-i18n">${jsonForScript(MESSAGES)}</script>
+<script${nonce}>${PAGE_SCRIPT}</script>
+</body>
+</html>
+`;
+}

package/dist/src/panel/server.d.ts

@@ -0,0 +1,32 @@
+import type { Runtime } from '../runtime.ts';
+export declare const DEFAULT_PANEL_PORT = 17420;
+export interface PanelServerOptions {
+    runtimeFactory: () => Promise<Runtime>;
+    port?: number;
+    open?: boolean;
+    log?: (s: string) => void;
+    version?: string;
+    /**
+     * Random id of a detached Panel. `/api/health` then also returns it with the server's pid, so `sideby ui
+     * --stop` can tell this Panel from a reused pid or from another Panel before it sends a signal.
+     */
+    instance?: string;
+}
+export interface PanelServer {
+    url: string;
+    reused: boolean;
+    close(): Promise<void>;
+}
+export interface PanelIdentity {
+    instance?: string;
+    pid?: number;
+    /** buildId() of the code serving it; absent from Panels older than this field. */
+    build?: string;
+}
+/** What the sideby Panel on this port says about itself, or undefined when none answers. */
+export declare function panelIdentity(port: number): Promise<PanelIdentity | undefined>;
+/** True when a sideby Panel answers on this port. */
+export declare function isSidebyPanel(port: number): Promise<boolean>;
+/** Opens `url` in the default browser; returns false (and never throws) when that is not possible. */
+export declare function openBrowser(url: string): Promise<boolean>;
+export declare function startPanelServer(opts: PanelServerOptions): Promise<PanelServer>;

package/dist/src/panel/server.js

@@ -0,0 +1,133 @@
+// Standalone Panel server for `sideby ui`: loopback only, reuses a running Panel, shifts past busy ports.
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { buildId } from '../core/version.js';
+import { createPanelHandler } from './handler.js';
+export const DEFAULT_PANEL_PORT = 17420;
+const PORT_ATTEMPTS = 20;
+const LOOPBACK = '127.0.0.1';
+function listen(server, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => {
+            server.off('listening', onListening);
+            if (err.code === 'EADDRINUSE')
+                resolve('busy');
+            else
+                reject(err);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve('ok');
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, LOOPBACK);
+    });
+}
+/** What the sideby Panel on this port says about itself, or undefined when none answers. */
+export async function panelIdentity(port) {
+    try {
+        const res = await fetch(`http://${LOOPBACK}:${port}/api/health`, { signal: AbortSignal.timeout(1500) });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        if (body?.app !== 'sideby')
+            return undefined;
+        return {
+            ...(typeof body.instance === 'string' ? { instance: body.instance } : {}),
+            ...(Number.isInteger(body.pid) ? { pid: body.pid } : {}),
+            ...(typeof body.build === 'string' ? { build: body.build } : {}),
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when a sideby Panel answers on this port. */
+export async function isSidebyPanel(port) {
+    return (await panelIdentity(port)) !== undefined;
+}
+/** Opens `url` in the default browser; returns false (and never throws) when that is not possible. */
+export function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    return new Promise((resolve) => {
+        try {
+            const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+            child.once('error', () => resolve(false));
+            child.once('exit', (code) => resolve(code === 0));
+            child.unref();
+        }
+        catch {
+            resolve(false);
+        }
+    });
+}
+export async function startPanelServer(opts) {
+    const log = opts.log ?? ((s) => console.log(s));
+    const first = opts.port ?? DEFAULT_PANEL_PORT;
+    const announce = async (url, reused) => {
+        log(reused ? `sideby panel is already running at ${url}` : `sideby panel: ${url}`);
+        if (opts.open && !(await openBrowser(url)))
+            log(`open ${url} in your browser`);
+    };
+    for (let port = first; port < first + PORT_ATTEMPTS && port <= 65535; port++) {
+        const hosts = [`${LOOPBACK}:${port}`, `localhost:${port}`];
+        const handler = createPanelHandler({
+            runtime: opts.runtimeFactory,
+            allowedHosts: hosts,
+            ...(opts.version ? { version: opts.version } : {}),
+        });
+        const server = createServer((req, res) => {
+            if (opts.instance &&
+                req.method === 'GET' &&
+                req.url === '/api/health' &&
+                hosts.includes(req.headers.host ?? '')) {
+                res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                res.end(JSON.stringify({
+                    app: 'sideby',
+                    ...(opts.version ? { version: opts.version } : {}),
+                    build: buildId(),
+                    instance: opts.instance,
+                    pid: process.pid,
+                }));
+                return;
+            }
+            handler(req, res)
+                .then((handled) => {
+                if (!handled) {
+                    res.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+                    res.end('not found');
+                }
+            })
+                .catch(() => {
+                if (!res.headersSent)
+                    res.writeHead(500);
+                res.end();
+            });
+        });
+        const result = await listen(server, port);
+        const url = `http://${LOOPBACK}:${port}/`;
+        if (result === 'ok') {
+            if (port !== first)
+                log(`port ${first} is busy; using ${port}`);
+            await announce(url, false);
+            return {
+                url,
+                reused: false,
+                close: () => new Promise((resolve, reject) => {
+                    server.close((err) => (err ? reject(err) : resolve()));
+                    server.closeAllConnections();
+                }),
+            };
+        }
+        if (await isSidebyPanel(port)) {
+            await announce(url, true);
+            return { url, reused: true, close: async () => { } };
+        }
+    }
+    throw new Error(`ports ${first}-${first + PORT_ATTEMPTS - 1} are all busy; pick another with \`sideby ui --port <n>\``);
+}

package/dist/src/panel/theme.d.ts

@@ -0,0 +1,116 @@
+/** Values for the Panel's design tokens. Every value is one CSS value, such as `#3f8fc4`, `14px` or a font stack. */
+export interface PanelThemeTokens {
+    /** Font stack for all text but code. */
+    font?: string;
+    monoFont?: string;
+    /** Body text, 14px by default. */
+    fontSize?: string;
+    /** Meta text, hints and small labels, 12.5px. */
+    smallSize?: string;
+    /** Button text, 13.5px. */
+    controlSize?: string;
+    /** Section headings, 15px. */
+    headingSize?: string;
+    /** Account names on cards, 16px. */
+    largeSize?: string;
+    /** Page title, 22px. */
+    titleSize?: string;
+    titleWeight?: string;
+    /** Section headings and account names. */
+    headingWeight?: string;
+    /** Labels, emphasis and numbers. */
+    strongWeight?: string;
+    buttonWeight?: string;
+    /** Main action button; defaults to `buttonWeight`. */
+    primaryWeight?: string;
+    /** Page background. */
+    bg?: string;
+    /** Cards, panels, fields and buttons. */
+    surface?: string;
+    /** Quiet areas inside a card: notes, logo tiles, chips. */
+    surfaceMuted?: string;
+    border?: string;
+    /** Borders of fields and buttons. */
+    borderStrong?: string;
+    text?: string;
+    muted?: string;
+    faint?: string;
+    /** Background of a hovered or pressed secondary button. */
+    hover?: string;
+    active?: string;
+    /** Links and the Subscription chip. */
+    accent?: string;
+    accentSoft?: string;
+    /** Focus outline and focused field border. */
+    focus?: string;
+    /** Main action button. */
+    primary?: string;
+    primaryHover?: string;
+    primaryActive?: string;
+    onPrimary?: string;
+    primaryBorder?: string;
+    primaryHoverBorder?: string;
+    /** Secondary button text, and its border and text on hover. */
+    buttonText?: string;
+    buttonHoverBorder?: string;
+    buttonHoverText?: string;
+    /** Checkbox color. */
+    checkColor?: string;
+    ok?: string;
+    okSoft?: string;
+    warn?: string;
+    warnSoft?: string;
+    fail?: string;
+    failSoft?: string;
+    /** The sideby mark in the page header. */
+    logoBg?: string;
+    logoColor?: string;
+    logoBorder?: string;
+    shadow?: string;
+    /** `outline` of focused controls (`none` to rely on `focusRing`). */
+    focusOutline?: string;
+    /** `box-shadow` of focused controls, such as a soft halo. */
+    focusRing?: string;
+    /** Cards and panels; banners and notes derive smaller radii from it. */
+    radius?: string;
+    /** Buttons and fields. */
+    controlRadius?: string;
+    chipRadius?: string;
+    /** Button height; `controlHeightSmall` for buttons inside cards and banners. */
+    controlHeight?: string;
+    controlHeightSmall?: string;
+    /** Text field and select height. */
+    fieldHeight?: string;
+    /** Maximum width of the page content (`none` for full width). */
+    contentWidth?: string;
+    /** Left and right page padding. */
+    gutter?: string;
+}
+export interface PanelTheme {
+    /** `auto` (default) follows the system; `light` or `dark` fixes one scheme. */
+    colorScheme?: 'auto' | 'light' | 'dark';
+    /** `plain` (default): the title sits on the page background. `bar`: a full-width header strip on the surface color. */
+    header?: 'plain' | 'bar';
+    /**
+     * Light-mode values. Color tokens set here apply in light mode only; the others (type, shape, layout) also apply
+     * in dark mode unless `dark` sets them.
+     */
+    light?: PanelThemeTokens;
+    /** Dark-mode values, layered over the built-in dark palette. */
+    dark?: PanelThemeTokens;
+}
+/** Token name to the CSS custom property the page reads. */
+export declare const THEME_TOKENS: Record<keyof PanelThemeTokens, string>;
+/** A theme checked and turned into CSS declarations, ready for the page. */
+export interface ResolvedTheme {
+    colorScheme: 'auto' | 'light' | 'dark';
+    header: 'plain' | 'bar';
+    /** `--name: value` declarations. */
+    light: string[];
+    dark: string[];
+}
+export declare const MAX_THEME_VALUE = 200;
+/** Why a theme value is unsafe or malformed, or null when it can go into the style block as is. */
+export declare function themeValueProblem(value: unknown): string | null;
+/** Checks a host theme and turns it into CSS declarations. Throws a TypeError that names the bad token. */
+export declare function resolveTheme(theme: PanelTheme | undefined): ResolvedTheme;

package/dist/src/panel/theme.js

@@ -0,0 +1,132 @@
+// Host theming for the Panel page: a typed set of tokens that become CSS custom properties inside the page's
+// nonce'd <style>, so an embedding host can match its own look without loosening the CSP.
+/** Token name to the CSS custom property the page reads. */
+export const THEME_TOKENS = {
+    font: '--font',
+    monoFont: '--mono',
+    fontSize: '--font-size',
+    smallSize: '--small',
+    controlSize: '--control-size',
+    headingSize: '--heading-size',
+    largeSize: '--large',
+    titleSize: '--title-size',
+    titleWeight: '--title-weight',
+    headingWeight: '--heading-weight',
+    strongWeight: '--strong-weight',
+    buttonWeight: '--button-weight',
+    primaryWeight: '--primary-weight',
+    bg: '--bg',
+    surface: '--surface',
+    surfaceMuted: '--surface-2',
+    border: '--border',
+    borderStrong: '--border-strong',
+    text: '--text',
+    muted: '--muted',
+    faint: '--faint',
+    hover: '--hover',
+    active: '--active',
+    accent: '--accent',
+    accentSoft: '--accent-soft',
+    focus: '--focus',
+    primary: '--primary',
+    primaryHover: '--primary-hover',
+    primaryActive: '--primary-active',
+    onPrimary: '--on-primary',
+    primaryBorder: '--primary-border',
+    primaryHoverBorder: '--primary-hover-border',
+    buttonText: '--btn-text',
+    buttonHoverBorder: '--btn-hover-border',
+    buttonHoverText: '--btn-hover-text',
+    checkColor: '--check',
+    ok: '--ok',
+    okSoft: '--ok-soft',
+    warn: '--warn',
+    warnSoft: '--warn-soft',
+    fail: '--fail',
+    failSoft: '--fail-soft',
+    logoBg: '--logo-bg',
+    logoColor: '--logo-fg',
+    logoBorder: '--logo-line',
+    shadow: '--shadow',
+    focusOutline: '--focus-outline',
+    focusRing: '--focus-ring',
+    radius: '--radius',
+    controlRadius: '--ctl-radius',
+    chipRadius: '--chip-radius',
+    controlHeight: '--ctl-h',
+    controlHeightSmall: '--ctl-h-sm',
+    fieldHeight: '--field-h',
+    contentWidth: '--content-width',
+    gutter: '--gutter',
+};
+export const MAX_THEME_VALUE = 200;
+// Letters, digits, spaces and the punctuation CSS values need (`#`, `%`, `(`, `)`, `,`, `.`, `+`, `-`, `/`, quotes, `_`).
+// Nothing that ends a declaration, a block or the <style> element (`;`, `{`, `}`, `<`), no escapes (`\`), no comments (`*`)
+// and no `:`, so no URL scheme either.
+const VALUE_RE = /^[A-Za-z0-9 #%(),.+\-/'"_]+$/;
+/** Why a theme value is unsafe or malformed, or null when it can go into the style block as is. */
+export function themeValueProblem(value) {
+    if (typeof value !== 'string')
+        return 'must be a string';
+    if (!value.trim())
+        return 'must not be empty';
+    if (value.length > MAX_THEME_VALUE)
+        return `is over ${MAX_THEME_VALUE} characters`;
+    if (!VALUE_RE.test(value))
+        return 'may hold only letters, digits, spaces and # % ( ) , . + - / \' " _ (no ; { } < \\ * or :)';
+    if (/url\s*\(/i.test(value))
+        return 'must not load a URL';
+    let depth = 0;
+    for (const c of value) {
+        if (c === '(')
+            depth++;
+        else if (c === ')' && --depth < 0)
+            break;
+    }
+    if (depth !== 0)
+        return 'has unbalanced parentheses';
+    if (value.split('"').length % 2 === 0 || value.split("'").length % 2 === 0)
+        return 'has an unclosed quote';
+    return null;
+}
+function declarations(tokens, where) {
+    if (tokens === undefined)
+        return [];
+    if (typeof tokens !== 'object' || tokens === null || Array.isArray(tokens))
+        throw new TypeError(`panel theme: ${where} must be an object of tokens`);
+    const out = [];
+    for (const [name, value] of Object.entries(tokens)) {
+        if (value === undefined)
+            continue;
+        const prop = Object.hasOwn(THEME_TOKENS, name) ? THEME_TOKENS[name] : undefined;
+        if (!prop)
+            throw new TypeError(`panel theme: unknown token ${where}.${name}; known tokens: ${Object.keys(THEME_TOKENS).join(', ')}`);
+        const problem = themeValueProblem(value);
+        if (problem)
+            throw new TypeError(`panel theme: ${where}.${name} ${problem}`);
+        out.push(`${prop}: ${value.trim()}`);
+    }
+    return out;
+}
+/** Checks a host theme and turns it into CSS declarations. Throws a TypeError that names the bad token. */
+export function resolveTheme(theme) {
+    if (theme === undefined)
+        return { colorScheme: 'auto', header: 'plain', light: [], dark: [] };
+    if (typeof theme !== 'object' || theme === null || Array.isArray(theme))
+        throw new TypeError('panel theme must be an object');
+    for (const key of Object.keys(theme))
+        if (!['colorScheme', 'header', 'light', 'dark'].includes(key))
+            throw new TypeError(`panel theme: unknown option ${key}; use colorScheme, header, light or dark`);
+    const colorScheme = theme.colorScheme ?? 'auto';
+    if (!['auto', 'light', 'dark'].includes(colorScheme))
+        throw new TypeError('panel theme: colorScheme must be "auto", "light" or "dark"');
+    const header = theme.header ?? 'plain';
+    if (!['plain', 'bar'].includes(header))
+        throw new TypeError('panel theme: header must be "plain" or "bar"');
+    return {
+        colorScheme,
+        header,
+        light: declarations(theme.light, 'light'),
+        dark: declarations(theme.dark, 'dark'),
+    };
+}

package/dist/src/plugins/account-script.d.ts

@@ -0,0 +1,4 @@
+import type { Plugin } from '../types.ts';
+export declare const SCRIPT_NAME = "sideby-before-launch";
+export declare const SCRIPT_TIMEOUT_MS = 25000;
+export declare const accountScript: Plugin;

package/dist/src/plugins/account-script.js

@@ -0,0 +1,66 @@
+// Built-in, off by default. Runs `<account>/sideby-before-launch` before each Launch: the general form of
+// a common hand-rolled convention (for example, start a local gateway an API Account needs).
+// It is local code with the user's permissions, so it gets the same ownership checks as Plugins.
+import { spawn } from 'node:child_process';
+import { access, constants } from 'node:fs/promises';
+import { join } from 'node:path';
+import { lstatOrNull } from '../core/fs-safe.js';
+import { checkTrusted } from './loader.js';
+export const SCRIPT_NAME = 'sideby-before-launch';
+export const SCRIPT_TIMEOUT_MS = 25_000;
+const TAIL_LINES = 20;
+function tail(text) {
+    return text.trimEnd().split('\n').slice(-TAIL_LINES).join('\n');
+}
+export const accountScript = {
+    name: 'account-script',
+    register(api) {
+        api.on('launch.before', async (ctx) => {
+            const script = join(ctx.account.dir, SCRIPT_NAME);
+            const st = await lstatOrNull(script);
+            if (!st)
+                return;
+            if (!st.isFile())
+                throw api.abort(`${script} must be a regular file`);
+            const problem = await checkTrusted(script);
+            if (problem)
+                throw api.abort(`refusing to run ${SCRIPT_NAME}: ${problem}`);
+            try {
+                await access(script, constants.X_OK);
+            }
+            catch {
+                throw api.abort(`${script} is not executable; run \`chmod u+x "${script}"\``);
+            }
+            const { code, stderr, timedOut } = await new Promise((resolve) => {
+                const child = spawn(script, [], {
+                    cwd: ctx.account.dir,
+                    env: ctx.env,
+                    stdio: ['ignore', 'ignore', 'pipe'],
+                });
+                let err = '';
+                child.stderr.on('data', (d) => {
+                    err = (err + d.toString()).slice(-16_384);
+                });
+                const timer = setTimeout(() => {
+                    child.kill('SIGKILL');
+                    child.stderr.destroy();
+                    resolve({ code: null, stderr: err, timedOut: true });
+                }, SCRIPT_TIMEOUT_MS);
+                child.on('error', (e) => {
+                    clearTimeout(timer);
+                    resolve({ code: 1, stderr: e.message, timedOut: false });
+                });
+                child.on('exit', (c) => {
+                    clearTimeout(timer);
+                    // A background process the script started (a gateway, say) inherits stderr; stop reading it.
+                    child.stderr.destroy();
+                    resolve({ code: c, stderr: err, timedOut: false });
+                });
+            });
+            if (timedOut)
+                throw api.abort(`${SCRIPT_NAME} did not finish within ${SCRIPT_TIMEOUT_MS / 1000}s`);
+            if (code !== 0)
+                throw api.abort(`${SCRIPT_NAME} exited with ${code}; the host was not started\n${tail(stderr)}`);
+        });
+    },
+};

package/dist/src/plugins/bus.d.ts

@@ -0,0 +1,33 @@
+import type { HookEvent, HookEvents, HookFilter, HookHandler } from '../types.ts';
+export declare const HOOK_TIMEOUT_MS: Record<HookEvent, number>;
+/** Error thrown by a hook, labelled with the Plugin that raised it. */
+export declare class HookError extends Error {
+    readonly plugin: string;
+    readonly aborted: boolean;
+    constructor(plugin: string, message: string, aborted: boolean);
+}
+/** Thrown by `api.abort()` to stop a Launch or a new Account on purpose. */
+export declare class HookAbort extends Error {
+}
+export declare class HookBus {
+    private readonly entries;
+    private readonly timeouts;
+    constructor(timeouts?: Partial<Record<HookEvent, number>>);
+    add<E extends HookEvent>(plugin: string, event: E, filter: HookFilter, handler: HookHandler<E>): void;
+    count(event: HookEvent): number;
+    /**
+     * Runs matching handlers in registration order. Each gets the event's timeout.
+     * Returns per-plugin results; the first failure stops the chain and is thrown as HookError.
+     */
+    run<E extends HookEvent>(event: E, family: string, ctx: HookEvents[E]['ctx']): Promise<{
+        plugin: string;
+        result: HookEvents[E]['result'];
+    }[]>;
+    /** Like `run`, but a failing handler is reported and the others still run (used by Doctor). */
+    runIsolated<E extends HookEvent>(event: E, family: string, ctx: HookEvents[E]['ctx']): Promise<{
+        plugin: string;
+        result?: HookEvents[E]['result'];
+        error?: HookError;
+    }[]>;
+    private invoke;
+}