windows-development-sandbox 1.23.1 → 1.25.0

package/dist/guest/boot/boot.js

@@ -15,7 +15,7 @@ import { linkProfileDirsAsync } from '../agents/profile-links.js';
 import { restoreClaudeMem } from '../setup/claude-mem.js';
 import { syncClaudeProfile } from '../setup/claude-profile.js';
 import { agentEnv, persistEnvironment } from '../setup/environment.js';
-import { runHooks } from '../setup/hooks.js';
+import { hasHooks, runHooks } from '../setup/hooks.js';
 import { applyAllowOnly, proxyEnv } from '../network/allow-only.js';
 import { applyNetworkPolicy, networkProblems } from '../network/firewall.js';
 import { writeManagedSettings } from '../setup/managed-policy.js';
@@ -37,12 +37,14 @@ import { now } from '../../shared/channel/run-dir.js';
 import { writeJsonAtomic } from '../../shared/io/json.js';
 import { viewSession } from '../sessions/viewer.js';
 import { saveBootEnv } from './boot-env.js';
-import { BOOT_DEFS, STAGES, stageTitle } from './graph.js';
-import { BootRunner, bootSummary, seconds } from './runner.js';
+import { BOOT_DEFS, STAGES, stageName, stageTitle } from './graph.js';
+import { BootRunner, duration } from './runner.js';
+import { BootConsole } from './boot-console.js';
+import { stepsDetail } from './progress-view.js';
 import { installPools } from '../runtime/pools.js';
 import { primaryProject, saveProjectStatus } from './project-status.js';
 import { dryRun, isWin, localDir, logsDir, run, toolsDir } from '../runtime/paths.js';
-import { log, logPath, runQuiet, warn, withLogContext } from '../runtime/log.js';
+import { log, logPath, notice, record, runQuiet, warn, withLogContext } from '../runtime/log.js';
 import { mkdirp } from '../runtime/fs.js';
 import { session, workspace } from '../runtime/session.js';
 import { applyBootEnvironment, BOOT_SECRETS_VARIABLE, takeSecrets } from '../runtime/secrets.js';
@@ -159,6 +161,12 @@ export class Boot {
     secrets = Object.freeze({});
     basePath = '';
     startedAt = Date.now();
+    who = {
+        ...(session.vpn ? { vpnServer: session.vpn.server } : {}),
+        agent: session.harnessName,
+    };
+    /** The console while the boot runs: the stage rows, warnings and summary (released before the first session). */
+    progress = BootConsole.create(Array.from({ length: STAGES }, (_, i) => ({ stage: i + 1, name: stageName(i + 1, this.who) })), BOOT_DEFS.filter((d) => !d.background), { plain: dryRun });
     openGate = () => undefined;
     gate = new Promise((resolve) => {
         this.openGate = resolve;
@@ -170,14 +178,39 @@ export class Boot {
     stepsDone = 0;
     stepsTotal = 0;
     async run() {
-        log('Agent sandbox: ' +
-            session.project +
-            ' | workspace ' +
-            workspace +
-            ' | agent ' +
-            session.harnessName +
-            ' | log ' +
-            logPath);
+        const agent = session.harness ? session.harnessName : 'no agent';
+        this.progress.start('Agent sandbox · ' + session.project + ' · ' + agent + ' · ' + workspace);
+        let runner;
+        try {
+            runner = await this.foreground();
+        }
+        catch (e) {
+            this.progress.release(null);
+            throw e;
+        }
+        this.progress.release({
+            ms: Date.now() - this.startedAt,
+            outcomes: runner.results(),
+            background: this.backgroundNames(),
+            logPath,
+        });
+        if (dryRun) {
+            // Same graph, one task at a time: the background tasks run in place, right after the session.
+            this.openGate();
+            await runner.run('background');
+            return;
+        }
+        this.openGate();
+        const later = runner.run('background');
+        // The viewer owns the console now: the background tasks write to the log file only.
+        if (session.harness && session.autoSession !== false && process.stdin.isTTY) {
+            await viewSession(session.launchId);
+            log('\nThis window stays open in ' + workspace + '. Other sessions keep running in their own tabs.');
+        }
+        await later.catch((e) => warn('Background work failed: ' + errMsg(e)));
+    }
+    /** The prelude, then every foreground task (the console shows them). */
+    async foreground() {
         if (!fs.statSync(workspace, { throwIfNoEntry: false })?.isDirectory())
             throw new Error('Workspace folder is missing in the sandbox: ' + workspace);
         this.basePath = process.env.PATH ?? '';
@@ -189,7 +222,7 @@ export class Boot {
         prepareGithubFolder(this.secrets.githubToken);
         installPools();
         const runner = new BootRunner(BOOT_DEFS, this.tasks(), {
-            say: (line, quiet) => (quiet ? runQuiet(() => log(line)) : log(line)),
+            trace: (line) => record(line),
             warn: (line, quiet) => (quiet ? runQuiet(() => warn(line)) : warn(line)),
             now: () => Date.now(),
             dryRun,
@@ -199,36 +232,26 @@ export class Boot {
                 this.lastStatus = s;
                 this.publish();
             },
-            inContext: (ctx, work) => withLogContext({ prefix: ctx.prefix, quiet: ctx.quiet }, work),
+            observer: this.progress,
+            inContext: (ctx, work) => withLogContext({ stage: ctx.stage, task: ctx.title, quiet: ctx.quiet }, work),
         });
         await runner.run('foreground');
-        const background = this.backgroundNames();
-        log(bootSummary(Date.now() - this.startedAt, runner.results(), background, logPath));
-        if (dryRun) {
-            // Same graph, one task at a time: the background tasks run in place, right after the session.
-            this.openGate();
-            await runner.run('background');
-            return;
-        }
-        this.openGate();
-        const later = runner.run('background');
-        // The viewer owns the console now: the background tasks write to the log file only.
-        if (session.harness && session.autoSession !== false && process.stdin.isTTY) {
-            await viewSession(session.launchId);
-            log('\nThis window stays open in ' + workspace + '. Other sessions keep running in their own tabs.');
-        }
-        await later.catch((e) => warn('Background work failed: ' + errMsg(e)));
+        return runner;
     }
     stageTitle(n) {
-        return stageTitle(n, { ...(session.vpn ? { vpnServer: session.vpn.server } : {}), agent: session.harnessName });
+        return stageTitle(n, this.who);
     }
-    /** The names shown for work that goes on after the boot is ready. */
+    /** The toolchain steps that go on after the boot is ready (Visual Studio and what needs it), in plan order. */
     backgroundNames() {
         const t = this.tools;
         if (!t?.later)
             return [];
-        const later = t.names.filter((n) => !(n in t.steps));
-        return later.length ? [later.slice(0, 3).join(', ') + (later.length > 3 ? ' ...' : '')] : [];
+        return t.names.filter((n) => !(n in t.steps));
+    }
+    /** Runs a stage's hooks; they write to the terminal themselves, so the progress block steps aside for them. */
+    hooks(stage, env) {
+        if (hasHooks(stage))
+            this.progress.aside(() => runHooks(stage, env));
     }
     /**
      * The host's one-shot file, read once. Your saved service sign-ins (accounts.<kind>.share) go to their tools before
@@ -262,7 +285,7 @@ export class Boot {
         setSandboxStatus(s.phase, s.message, {
             step: s.step,
             steps: STAGES,
-            title: this.stageTitle(s.step).replace(/ \(.*\)$/, ''),
+            title: stageName(s.step, this.who),
             active: [...s.running.map((name) => ({ name })), ...this.activeSteps],
             done: this.stepsDone,
             total: this.stepsTotal,
@@ -281,7 +304,7 @@ export class Boot {
             },
             audit: () => enableProcessAudit(),
             // 2 - pre-provision hooks and desktop
-            hooksPreProvision: () => runHooks('pre-provision', process.env),
+            hooksPreProvision: () => this.hooks('pre-provision', process.env),
             desktop: () => applyPersonalization(),
             browserGpu: () => keepBrowsersOffGpu(),
             // 3 - developer tools
@@ -343,7 +366,7 @@ export class Boot {
                     await agents.provision(session.harnessName, session.harness, this.env);
             },
             // 8 - pre-agent hooks
-            hooksPreAgent: () => runHooks('pre-agent', this.env),
+            hooksPreAgent: () => this.hooks('pre-agent', this.env),
             // 9 - start
             session: () => this.start(),
             // After the first session runs
@@ -371,6 +394,7 @@ export class Boot {
             ...(session.pcInstalls ? { pcInstalls: session.pcInstalls } : {}),
         }, {
             progress: (p) => {
+                this.progress.detail('toolchains', stepsDetail(p.active.map((a) => a.name + (a.percent === undefined ? '' : ' ' + Math.round(a.percent) + '%')), p.done, p.total));
                 this.activeSteps = p.active;
                 this.stepsDone = p.done;
                 this.stepsTotal = p.total;
@@ -424,8 +448,7 @@ export class Boot {
             lan: this.lan,
         });
         saveProjectStatus(primaryProject(), workspace, 'ready', 'Ready', session.databases ?? [], this.summary);
-        for (const line of this.summary)
-            log('  ' + line);
+        this.progress.summary(this.summary);
     }
     /** The toolchains' lines, then the missing protections, allowOnly and VS Code (in this order). */
     summaryLines(toolchainLines) {
@@ -441,7 +464,8 @@ export class Boot {
         const tools = this.tools;
         if (!tools?.later)
             return;
-        const name = this.backgroundNames()[0] ?? 'Visual Studio';
+        const names = this.backgroundNames();
+        const name = names.length ? names.slice(0, 3).join(', ') + (names.length > 3 ? ' ...' : '') : 'Visual Studio';
         const began = Date.now();
         setBackgroundWork([{ name, state: 'running' }]);
         log('Background: ' + name + ' (installing)');
@@ -468,7 +492,7 @@ export class Boot {
             saveProjectStatus(primaryProject(), workspace, 'ready', 'Ready', session.databases ?? [], this.summary);
             await soft('Sandbox guide for the agent', () => writeGuides(this.summary, this.lan));
             setBackgroundWork([{ name, state: 'done' }]);
-            log('Background done in ' + seconds(Date.now() - began) + ': ' + name);
+            log('Background done in ' + duration(Date.now() - began) + ': ' + name);
         }
         catch (e) {
             setBackgroundWork([{ name, state: 'failed' }]);
@@ -512,7 +536,7 @@ export class Boot {
         });
         if (!(await waitForPrimary()))
             throw new Error('The agent session did not start. Logs: ' + logsDir);
-        log('If Claude asks you to sign in, do it once; the login is saved in persistent storage.');
+        notice('If Claude asks you to sign in, do it once; the login is saved in persistent storage.');
     }
 }
 export function runBoot() {

package/dist/guest/boot/graph.d.ts

@@ -1,10 +1,14 @@
 import type { BootTaskDef } from './runner.js';
 export declare const STAGES = 9;
-/** The titles of the nine stages (the host shows the short form without the brackets). */
-export declare function stageTitle(stage: number, who?: {
-    vpnServer?: string;
-    agent?: string;
-}): string;
+/** Who the stage titles name. */
+export interface StageWho {
+    readonly vpnServer?: string;
+    readonly agent?: string;
+}
+/** The titles of the nine stages, with a note where one helps (the host's status message). */
+export declare function stageTitle(stage: number, who?: StageWho): string;
+/** The short titles of the nine stages: the console's stage rows and the host's progress line. */
+export declare function stageName(stage: number, who?: StageWho): string;
 /** The boot state the tasks share. */
 export type BootStateKey = 'ptyHost' | 'lan' | 'tools' | 'dbBin' | 'allowSummary' | 'vscodeSummary' | 'env' | 'toolVars' | 'summary' | 'headroom' | 'later';
 export interface BootTaskInfo {

package/dist/guest/boot/graph.js

@@ -1,13 +1,19 @@
 export const STAGES = 9;
-/** The titles of the nine stages (the host shows the short form without the brackets). */
+/** The titles of the nine stages, with a note where one helps (the host's status message). */
 export function stageTitle(stage, who = {}) {
+    return stage === 3
+        ? stageName(stage, who) + ' (the first start downloads them once; later starts are quick)'
+        : stageName(stage, who);
+}
+/** The short titles of the nine stages: the console's stage rows and the host's progress line. */
+export function stageName(stage, who = {}) {
     switch (stage) {
         case 1:
             return 'Network and session host';
         case 2:
             return 'Pre-provision hooks and desktop';
         case 3:
-            return 'Developer tools (the first start downloads them once; later starts are quick)';
+            return 'Developer tools';
         case 4:
             return who.vpnServer ? 'VPN (' + who.vpnServer + ')' : 'VPN (off)';
         case 5:

package/dist/guest/boot/progress-view.d.ts

@@ -0,0 +1,116 @@
+import { type TaskOutcome } from './runner.js';
+export interface ViewStage {
+    readonly stage: number;
+    readonly name: string;
+}
+export interface ViewTask {
+    readonly id: string;
+    readonly stage: number;
+    readonly title: string;
+    /** Its failure fails the boot (a soft failure is a warning). */
+    readonly critical?: boolean;
+}
+/** The marks of a stage row. */
+export interface Glyphs {
+    readonly done: string;
+    readonly failed: string;
+    readonly warned: string;
+    readonly skipped: string;
+    readonly waiting: string;
+    readonly more: string;
+    readonly spinner: readonly string[];
+}
+/** For Windows Terminal (Cascadia has braille and check marks). */
+export declare const RICH_GLYPHS: Glyphs;
+/** For the classic console (Consolas has neither braille nor check marks). */
+export declare const CONSOLE_GLYPHS: Glyphs;
+export interface Screen {
+    /** Writes text as it is (the view writes its own line ends and, when live, its cursor moves). */
+    write(text: string): void;
+    /** The terminal's width (live mode). */
+    columns(): number;
+}
+export interface ViewOptions {
+    /** A terminal: the stage block redraws in place. Otherwise plain, ordered lines. */
+    readonly live: boolean;
+    readonly screen: Screen;
+    /** Milliseconds. */
+    readonly now: () => number;
+    readonly glyphs?: Glyphs;
+}
+/** The end of the boot: how long it took, which tasks took longest and what goes on in the background. */
+export interface ReadyInfo {
+    readonly ms: number;
+    readonly outcomes: readonly TaskOutcome[];
+    readonly background: readonly string[];
+    readonly logPath: string;
+}
+/** "Node, Python, Rust +2 (5/13)": what the toolchain scheduler runs now. */
+export declare function stepsDetail(active: readonly string[], done: number, total: number): string;
+/** "Ready in 46.8s (slowest: ...)" and, when work goes on, the line that says what still installs. */
+export declare function readyLines(info: ReadyInfo): string[];
+/** Word-wraps `text` to `width` columns; a word longer than that is cut. Linear in the text. */
+export declare function wrap(text: string, width: number): string[];
+/** One boot's console: fed by the runner's events and the boot's lines, drawn on a screen. */
+export declare class ProgressView {
+    private readonly o;
+    private readonly stages;
+    private readonly byStage;
+    private readonly taskById;
+    private readonly nameWidth;
+    private readonly glyphs;
+    private readonly warnings;
+    private readonly notices;
+    private tools;
+    /** Lines of the live block on the screen now (the cursor is just below them). */
+    private drawn;
+    private lastFrame;
+    private asideDepth;
+    private released;
+    constructor(stages: readonly ViewStage[], tasks: readonly ViewTask[], o: ViewOptions);
+    /**
+     * Whether programs should hand their output to the log now: it would draw over the live block, or come out between
+     * the plain stages. Not while a hook has the terminal.
+     */
+    get capturing(): boolean;
+    /** The header line, then (live) the first frame. */
+    start(header: string): void;
+    started(task: ViewTask): void;
+    finished(task: ViewTask, outcome: TaskOutcome): void;
+    /** What a running task's place on its row says instead of its title (null: its title again). */
+    detail(taskId: string, text: string | null): void;
+    /** An info line: the file has it; plain output shows it under its stage (or at once, outside a stage). */
+    line(text: string, stage: number | undefined): void;
+    warning(text: string): void;
+    notice(text: string): void;
+    /** The tool summary ("name: detail" lines), printed once at the end. */
+    summary(lines: readonly string[]): void;
+    /** Redraws the live block (the boot calls it a few times a second). */
+    tick(): void;
+    /** Runs `work`, which writes to the terminal itself (the hooks): the live block steps aside until it is done. */
+    aside<T>(work: () => T): T;
+    /**
+     * The boot is over (`ready`) or failed (null): the final block, warnings, tools, notices and the ready line, once.
+     * The console is free afterwards (the first session takes it); nothing of this view prints again.
+     */
+    release(ready: ReadyInfo | null): void;
+    /** The live block as it would be drawn now (no colours when `colour` is false): the tests read it. */
+    frame(colour?: boolean): string[];
+    private draw;
+    private erase;
+    /** Plain output: every finished stage whose earlier stages are printed, in stage order. */
+    private flushPlain;
+    private stageBlock;
+    private indent;
+    /** One stage row; `now` null: the final, still row (no spinner). */
+    private row;
+    /** The tool summary as two aligned columns, the detail wrapped under itself. */
+    private toolRows;
+    /** `lead` + `text`, wrapped to `width` with the next lines indented under the text. */
+    private hanging;
+    /** The segments as one line of at most `width` columns, cut with the "more" mark. */
+    private render;
+    private paint;
+    /** The usable width: one column less than the terminal (a full line would wrap the cursor). */
+    private width;
+}