@wjarka/cezarion 0.15.1 → 0.16.0

package/dist/preview/dev-server.js

@@ -0,0 +1,341 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, readSync, rmSync, statSync, truncateSync, appendFileSync, writeFileSync, fstatSync } from 'node:fs';
+import { Socket } from 'node:net';
+import { join, resolve } from 'node:path';
+import { buildCommandEnv } from '../core/agent-env.js';
+import { processStartToken, recordedProcessLive } from '../delegation/process-liveness.js';
+import { CHROMIUM_PID_FILE } from './chromium.js';
+/**
+ * Supervisor for one cezar-owned dev server (#781, spec 2026-10-02-live-preview-v1): spawn the
+ * registered command in its own process group, TCP-probe until the port answers, and kill the
+ * whole group on stop so a command that forks (`npm` -> `node` -> `vite`) frees its port.
+ */
+export const PREVIEW_PORT_WAIT_MS = 2 * 60_000;
+export const PREVIEW_PROBE_MS = 2_000;
+const PROBE_CONNECT_MS = 500;
+const KILL_GRACE_MS = 5_000;
+/** How long a SIGKILLed group gets to disappear before the stop resolves anyway. */
+const KILL_SETTLE_MS = 2_000;
+const LOG_TRIM_ABOVE = 5 * 1024 * 1024;
+const LOG_KEEP = 1024 * 1024;
+const LOG_CHECK_MS = 60_000;
+const TAIL_READ = 64 * 1024;
+function connects(host, port) {
+    return new Promise(resolveConnect => {
+        const socket = new Socket();
+        const done = (up) => { socket.destroy(); resolveConnect(up); };
+        socket.setTimeout(PROBE_CONNECT_MS);
+        socket.once('connect', () => done(true));
+        socket.once('timeout', () => done(false));
+        socket.once('error', () => done(false));
+        socket.connect(port, host);
+    });
+}
+/** Does anything answer on `port`? Vite resolves `localhost` to `::1` on some hosts, so both loopbacks count. */
+export async function probePort(port) {
+    return (await connects('127.0.0.1', port)) || (await connects('::1', port));
+}
+const sleep = (ms) => new Promise(resolveSleep => setTimeout(resolveSleep, ms));
+function signalGroup(pgid, signal) {
+    if (process.platform === 'win32') {
+        return spawnSync('taskkill', ['/pid', String(pgid), '/t', '/f'], { windowsHide: true, timeout: 5_000 }).status === 0;
+    }
+    try {
+        process.kill(-pgid, signal);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function groupAlive(pgid) {
+    if (process.platform === 'win32')
+        return false;
+    try {
+        process.kill(-pgid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+/** SIGTERM one process, SIGKILL it if it is still there after the grace period. */
+async function terminatePid(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return;
+    }
+    const alive = () => { try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    } };
+    const deadline = Date.now() + KILL_GRACE_MS;
+    while (alive() && Date.now() < deadline)
+        await sleep(50);
+    if (alive()) {
+        try {
+            process.kill(pid, 'SIGKILL');
+        }
+        catch { /* gone meanwhile */ }
+    }
+}
+/** SIGTERM the group, SIGKILL whatever is still there after the grace period. */
+async function terminateGroup(pgid) {
+    if (!signalGroup(pgid, 'SIGTERM'))
+        return;
+    const deadline = Date.now() + KILL_GRACE_MS;
+    while (groupAlive(pgid) && Date.now() < deadline)
+        await sleep(50);
+    if (!groupAlive(pgid))
+        return;
+    signalGroup(pgid, 'SIGKILL');
+    // SIGKILL is delivered, not done: until the kernel tears the processes down they still hold
+    // their sockets. Return once the group is gone, so "stopped" means the port is free.
+    const killDeadline = Date.now() + KILL_SETTLE_MS;
+    while (groupAlive(pgid) && Date.now() < killDeadline)
+        await sleep(20);
+}
+/** Keep the last 1 MiB once the log passes 5 MiB. The child holds the file open in append mode, so it keeps writing at the end. */
+export function trimLog(path) {
+    try {
+        if (statSync(path).size <= LOG_TRIM_ABOVE)
+            return;
+        const fd = openSync(path, 'r');
+        const tail = Buffer.alloc(LOG_KEEP);
+        try {
+            readSync(fd, tail, 0, LOG_KEEP, fstatSync(fd).size - LOG_KEEP);
+        }
+        finally {
+            closeSync(fd);
+        }
+        truncateSync(path, 0);
+        appendFileSync(path, tail);
+    }
+    catch { /* a log we cannot trim only grows */ }
+}
+function readTail(path, lines) {
+    try {
+        const fd = openSync(path, 'r');
+        try {
+            const size = fstatSync(fd).size;
+            const length = Math.min(size, TAIL_READ);
+            const buffer = Buffer.alloc(length);
+            readSync(fd, buffer, 0, length, size - length);
+            return buffer.toString('utf8').split('\n').filter(line => line.trim()).slice(-lines);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+    catch {
+        return [];
+    }
+}
+export class DevServer extends EventEmitter {
+    state = 'starting';
+    exitCode;
+    attempts = 0;
+    stopReason;
+    server;
+    worktreePath;
+    dir;
+    probeMs;
+    waitMs;
+    child;
+    childExited;
+    probeTimer;
+    waitTimer;
+    logTimer;
+    probing = false;
+    stopping;
+    constructor(opts) {
+        super();
+        this.server = opts.server;
+        this.worktreePath = opts.worktreePath;
+        this.dir = opts.dir;
+        this.probeMs = opts.probeMs ?? PREVIEW_PROBE_MS;
+        this.waitMs = opts.waitMs ?? PREVIEW_PORT_WAIT_MS;
+    }
+    get pidPath() { return join(this.dir, `${this.server.port}.pid.json`); }
+    get logPath() { return join(this.dir, `${this.server.port}.log`); }
+    start() {
+        if (this.child)
+            return;
+        mkdirSync(this.dir, { recursive: true });
+        // One log per start: after Start again, 5.8 must show this run's failure, not the last one's tail.
+        writeFileSync(this.logPath, '', { mode: 0o600 });
+        const logFd = openSync(this.logPath, 'a');
+        const cwd = resolve(this.worktreePath, this.server.cwd ?? '.');
+        // stdin is closed: nobody can answer a prompt from the cockpit, so one fails fast into `exited` with its log.
+        // The command is the agent's and runs outside its sandbox: it gets the curated env, never cezar's secrets (#427).
+        const env = buildCommandEnv();
+        const child = process.platform === 'win32'
+            ? spawn(this.server.command, { cwd, env, shell: true, windowsHide: true, stdio: ['ignore', logFd, logFd] })
+            : spawn('/bin/sh', ['-c', this.server.command], { cwd, env, detached: true, stdio: ['ignore', logFd, logFd] });
+        closeSync(logFd);
+        this.child = child;
+        this.childExited = new Promise(resolveExit => {
+            child.once('error', error => {
+                try {
+                    appendFileSync(this.logPath, `cezar could not start the command: ${error.message}\n`);
+                }
+                catch { /* log is best effort */ }
+                resolveExit();
+                this.finish('exited');
+            });
+            child.once('exit', (code) => {
+                resolveExit();
+                if (code !== null)
+                    this.exitCode = code;
+                const pid = child.pid;
+                if (this.stopping || pid === undefined)
+                    return this.finish(this.stopping ? 'stopped' : 'exited');
+                // A leader that dies on its own can leave a forked server holding the port. Reap the group
+                // the way a stop does (SIGKILL after the grace period, so a holder that ignores SIGTERM goes
+                // too), and keep the pid record until the group is gone: `stop()` awaits the same cleanup.
+                this.finish('exited', { keepRecord: true });
+                this.stopping = terminateGroup(pid).finally(() => this.removeRecord(pid));
+            });
+        });
+        if (child.pid !== undefined) {
+            writeFileSync(this.pidPath, JSON.stringify({ pid: child.pid, pgid: child.pid, startToken: processStartToken(child.pid) }), { mode: 0o600 });
+            this.beginWaiting();
+            this.logTimer = setInterval(() => trimLog(this.logPath), LOG_CHECK_MS);
+            this.logTimer.unref();
+        }
+    }
+    /** The owner pressed "keep waiting" on a stalled server: probe again for another full window. */
+    keepWaiting() {
+        if (this.state !== 'stalled')
+            return;
+        this.setState('starting');
+        this.beginWaiting();
+    }
+    stop(reason) {
+        if (this.stopping)
+            return this.stopping;
+        if (this.state === 'exited' || this.state === 'stopped')
+            return Promise.resolve();
+        this.stopping ??= this.terminate(reason);
+        return this.stopping;
+    }
+    logTail(lines = 4) {
+        return readTail(this.logPath, lines);
+    }
+    async terminate(reason) {
+        this.stopReason = reason;
+        const pid = this.child?.pid;
+        if (pid === undefined) {
+            this.finish('stopped');
+            return;
+        }
+        await terminateGroup(pid);
+        await this.childExited;
+        this.finish('stopped');
+    }
+    beginWaiting() {
+        this.endWaiting();
+        this.probeTimer = setInterval(() => { void this.probeOnce(); }, this.probeMs);
+        this.waitTimer = setTimeout(() => {
+            if (this.state !== 'starting')
+                return;
+            this.endWaiting();
+            this.setState('stalled');
+        }, this.waitMs);
+    }
+    endWaiting() {
+        clearInterval(this.probeTimer);
+        clearTimeout(this.waitTimer);
+        this.probeTimer = this.waitTimer = undefined;
+    }
+    async probeOnce() {
+        if (this.probing || this.state !== 'starting')
+            return;
+        this.probing = true;
+        this.attempts += 1;
+        this.emit('attempt', this.attempts);
+        const up = await probePort(this.server.port);
+        this.probing = false;
+        if (up && this.state === 'starting') {
+            this.endWaiting();
+            this.setState('up');
+        }
+    }
+    /** A terminal state: the process is gone, so timers and (unless its group is still being reaped) the pid record go with it. */
+    finish(state, opts = {}) {
+        if (this.state === 'exited' || this.state === 'stopped')
+            return;
+        this.endWaiting();
+        clearInterval(this.logTimer);
+        if (!opts.keepRecord && this.child?.pid !== undefined)
+            this.removeRecord(this.child.pid);
+        this.setState(state);
+    }
+    /** Only our own record: a Start again on the same port may already have written its successor's. */
+    removeRecord(pid) {
+        try {
+            if (JSON.parse(readFileSync(this.pidPath, 'utf8')).pid !== pid)
+                return;
+        }
+        catch { /* missing or unreadable: nothing of ours to keep */ }
+        rmSync(this.pidPath, { force: true });
+    }
+    setState(state) {
+        this.state = state;
+        this.emit('state', state);
+    }
+}
+/**
+ * Boot sweep: a crashed cezar leaves pid records behind, `<port>.pid.json` for each dev server and
+ * `chromium.pid.json` for the task's browser. Kill only when the recorded pid is still the process
+ * we started (an exactly matching start token), so a reused pid is never hit; a missing or
+ * unreadable token means skip. A dev server's whole group goes; Chromium shares cezar's group, so
+ * only its pid is signalled.
+ * The record goes either way, except one `keep` claims: a server or browser the live host still runs.
+ * Returns how many processes were killed.
+ */
+export async function sweepPreviewLeftovers(dataDir, opts = {}) {
+    const root = join(dataDir, 'preview');
+    if (!existsSync(root))
+        return 0;
+    const kills = [];
+    for (const run of readdirSync(root, { withFileTypes: true })) {
+        if (!run.isDirectory())
+            continue;
+        for (const file of readdirSync(join(root, run.name))) {
+            if (!file.endsWith('.pid.json'))
+                continue;
+            const what = file === CHROMIUM_PID_FILE ? 'browser' : Number(file.slice(0, -'.pid.json'.length));
+            if (opts.keep?.(run.name, what))
+                continue;
+            const path = join(root, run.name, file);
+            let record;
+            try {
+                record = JSON.parse(readFileSync(path, 'utf8'));
+            }
+            catch { /* unreadable: nothing to kill */ }
+            rmSync(path, { force: true });
+            const { pid, pgid, startToken } = (record ?? {});
+            if (typeof pid !== 'number' || typeof startToken !== 'string')
+                continue;
+            // A dev server leads its own group. The token verifies the pid only, so a record naming
+            // another group is not one cezar wrote, and that group is never signalled.
+            if (what !== 'browser' && pgid !== pid)
+                continue;
+            // `recordedProcessLive` answers "alive" on any uncertainty; a kill needs an exact token match,
+            // so a record without a token, or a pid whose token cannot be read now, is skipped.
+            if (!recordedProcessLive({ pid, startToken }) || processStartToken(pid) !== startToken)
+                continue;
+            kills.push(what === 'browser' ? terminatePid(pid) : terminateGroup(pid));
+        }
+    }
+    await Promise.all(kills);
+    return kills.length;
+}
+//# sourceMappingURL=dev-server.js.map

package/dist/preview/dev-server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev-server.js","sourceRoot":"","sources":["../../src/preview/dev-server.ts"],"names":[],"mappings":"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"}

package/dist/preview/host.d.ts

@@ -0,0 +1,154 @@
+import type { PreviewStopRequest, PreviewStopResult, PreviewClientMessage, PreviewServer } from '../contract/index.js';
+import type { RunStore } from '../runs/store.ts';
+import { type Cdp } from './cdp.ts';
+import { DevServer, type DevServerState } from './dev-server.ts';
+import { type PreviewHostLike } from './registration.ts';
+import { type Viewer } from './session.ts';
+/**
+ * The workspace-wide preview host (#781, spec 2026-10-02-live-preview-v1): one per server process,
+ * because ports are host-global. Keyed by run id, it owns every cezar-started dev server and every
+ * task's Chromium, and every exit in the spec's lifecycle table: idle timers, release on worktree
+ * removal or run deletion, and shutdown. It starts commands only on owner approval or agent reuse of that unchanged approval.
+ */
+export declare const PREVIEW_SERVER_IDLE_MS: number;
+export declare const PREVIEW_BROWSER_IDLE_MS: number;
+export type RunContext = {
+    runId: string;
+    title: string;
+    worktreePath: string;
+    dataDir: string;
+    store: Pick<RunStore, 'getRun' | 'appendEvent'>;
+};
+export type PreviewTarget = {
+    port: number;
+} | {
+    url: string;
+};
+export type BrowserExit = {
+    signal?: string;
+    stderrTail: string;
+};
+/** A launched Chromium with its page's CDP connection. `exited` settles when the process is gone. */
+export type BrowserHandle = {
+    cdp: Cdp;
+    exited: Promise<BrowserExit>;
+    close(): void;
+};
+/** What the host uses of a `DevServer`: its state, its controls and its two events. */
+export type DevServerLike = Pick<DevServer, 'state' | 'attempts' | 'exitCode' | 'stopReason' | 'start' | 'stop' | 'keepWaiting' | 'logTail'> & {
+    on(event: 'state', listener: (state: DevServerState) => void): unknown;
+    on(event: 'attempt', listener: (attempts: number) => void): unknown;
+};
+export type PreviewHostDeps = {
+    probe?: (port: number) => Promise<boolean>;
+    createServer?: (opts: {
+        server: PreviewServer;
+        worktreePath: string;
+        dir: string;
+    }) => DevServerLike;
+    launchBrowser?: (profileDir: string) => Promise<BrowserHandle>;
+    download?: (opts: {
+        signal: AbortSignal;
+        onProgress(received: number, total: number): void;
+    }) => Promise<string>;
+    env?: NodeJS.ProcessEnv;
+    platform?: string;
+    arch?: string;
+    /** /etc/os-release, for the install command. */
+    osRelease?: () => string;
+};
+/** No Chromium anywhere `resolveChromium` looks: the pane offers the download or the OS command. */
+export declare class ChromiumMissingError extends Error {
+}
+export declare class PreviewHost implements PreviewHostLike {
+    private readonly stopping;
+    private readonly entries;
+    private readonly deps;
+    /** Chromium lands in one shared cache, so there is one download for the whole host. */
+    private download?;
+    constructor(deps?: PreviewHostDeps);
+    /**
+     * A pane asks for a server or a URL. A registered port is probed again now: answering is
+     * adopted and streamed, silent asks for approval. Nothing here spawns a command.
+     */
+    open(ctx: RunContext, viewer: Viewer, target: PreviewTarget): Promise<void>;
+    /** The owner's approval, also reused by stopPreview after checking the saved approval. */
+    run(runId: string, port: number): Promise<void>;
+    /**
+     * The agent re-registered `port` with a different command, cwd or path. A server cezar runs
+     * from the old registration stops, an adoption is forgotten, and a pane on that port is asked
+     * to approve the new command: nothing runs it until the owner does.
+     */
+    replaced(runId: string, port: number): Promise<void>;
+    /** Stops a cezar-owned server. An adopted one is not cezar's to stop: refused with `false`. */
+    stop(runId: string, port: number, reason: 'user' | 'idle'): Promise<boolean>;
+    /** Reuse only the approval attached to this exact owned process, including after a crash. */
+    stopPreview(runId: string, request: PreviewStopRequest, signal?: AbortSignal): Promise<PreviewStopResult>;
+    private stopServer;
+    keepWaiting(runId: string, port: number): void;
+    /** The socket closed. The last viewer leaving starts both idle timers. */
+    detach(runId: string, viewer: Viewer): void;
+    /** Agent restarts without a viewer need a bound even after the previous idle timer fired. */
+    private armServerIdle;
+    /** Every message a connected pane sends, already validated against the contract. */
+    handle(ctx: RunContext, viewer: Viewer, msg: PreviewClientMessage): Promise<void>;
+    /**
+     * The run's worktree is going, or the run itself: stop its servers, close its browser, tell the
+     * pane. The profile survives unless `deleteProfile` (run deletion), which removes the whole
+     * `<dataDir>/preview/<runId>/`. `dataDir` covers a run this process never opened.
+     */
+    release(runId: string, opts?: {
+        deleteProfile?: boolean;
+        dataDir?: string;
+    }): Promise<void>;
+    /** The task whose cezar-owned dev server holds `port`. Adopted ports belong to nobody. */
+    portOwner(port: number): {
+        runId: string;
+        title: string;
+    } | undefined;
+    /** Whether this host runs the dev server `<runId>/<port>.pid.json` records: the sweep spares it. */
+    ownsServer(runId: string, port: number): boolean;
+    /** Whether this host runs the run's Chromium (`<runId>/chromium.pid.json`): the sweep spares it. */
+    ownsBrowser(runId: string): boolean;
+    probe(port: number): Promise<boolean>;
+    /** cezar shuts down: every run is released and every pane closed. */
+    close(): Promise<void>;
+    private entryFor;
+    /** One viewer per run: a second one takes over, and the first is told by whom. */
+    private claim;
+    /** Tells the pane `port-held` when another task's cezar-owned server holds `server.port`. */
+    private heldByOther;
+    private registration;
+    private runDir;
+    private onServerState;
+    /** `preview.server-state`, on transitions only. A run already deleted takes no events. */
+    private recordState;
+    /** The pane's view of a cezar-owned server that is not streaming. */
+    private report;
+    /** Where a server's page reopens: the page the owner was last on when it is this server's, else the registered root. */
+    private serverPage;
+    /**
+     * Streams a registered server. With `resume`, a live page already on that server is kept as it
+     * is: a reconnect, a takeover or a reopen inside the browser idle window must not throw the owner
+     * back to the root and lose their form state. Re-attaching restarts the screencast, so the first
+     * frame still announces `streaming`.
+     */
+    private showServer;
+    /** Browser, then page, then the first frame (which the session announces as `streaming`). */
+    private show;
+    private ensureSession;
+    private launch;
+    private launchFailed;
+    /** Chromium died under us: say so with the server's state, and wait for the owner's Retry. */
+    private browserExited;
+    private retryBrowser;
+    private serverUp;
+    private missingState;
+    private startDownload;
+    /** `first` watches before the download starts, so no progress report is lost. */
+    private beginDownload;
+    private closeBrowser;
+    private clearIdle;
+    private releaseEntry;
+    private tell;
+}