windows-development-sandbox 1.4.0 → 1.4.3

package/dist/cli/commands/launch/first-start.d.ts

@@ -0,0 +1,10 @@
+/** The wanted tools that are not downloaded yet (`has` says whether a folder in <data>\tools exists), with their rough size. */
+export declare function pendingDownloads(wanted: readonly string[], has: (dir: string) => boolean): {
+    names: string[];
+    mb: number;
+};
+/** The heads-up before the wait, or null when everything is already downloaded. first: nothing was ever installed. */
+export declare function firstStartNotice(first: boolean, pending: {
+    names: string[];
+    mb: number;
+}): string | null;

package/dist/cli/commands/launch/first-start.js

@@ -0,0 +1,53 @@
+// The first-start heads-up: what a start downloads once (the tools this project needs) and roughly how much.
+/** What a first start downloads, by setting name: its folder in <data>\tools, rough size and a readable name. */
+const DOWNLOADS = {
+    node: { dir: 'nvm', mb: 30 },
+    python: { dir: 'python', mb: 30 },
+    rust: { dir: 'rust', mb: 300 },
+    msvc: { dir: 'msvc', mb: 1500, label: 'MSVC' },
+    cpp: { dir: 'mingw', mb: 270, label: 'C/C++' },
+    dotnet: { dir: 'dotnet', mb: 250, label: '.NET' },
+    go: { dir: 'go', mb: 80 },
+    java: { dir: 'java', mb: 200 },
+    ruby: { dir: 'ruby', mb: 100 },
+    php: { dir: 'php', mb: 30 },
+    deno: { dir: 'deno', mb: 40 },
+    pwsh: { dir: 'pwsh', mb: 100, label: 'PowerShell 7' },
+    vscode: { dir: 'vscode', mb: 150, label: 'VS Code' },
+    postgres: { dir: 'postgres', mb: 330, label: 'PostgreSQL' },
+    mysql: { dir: 'mariadb', mb: 90, label: 'MariaDB' },
+    mongodb: { dir: 'mongodb', mb: 450, label: 'MongoDB' },
+    redis: { dir: 'redis', mb: 10 },
+    dynamodb: { dir: 'dynamodb-local', mb: 80, label: 'DynamoDB Local' },
+};
+/** The wanted tools that are not downloaded yet (`has` says whether a folder in <data>\tools exists), with their rough size. */
+export function pendingDownloads(wanted, has) {
+    const missing = [...new Set(wanted)].filter((w) => Object.hasOwn(DOWNLOADS, w) && !has(DOWNLOADS[w].dir));
+    return {
+        names: missing.map((w) => DOWNLOADS[w].label ?? w),
+        mb: missing.reduce((sum, w) => sum + DOWNLOADS[w].mb, 0),
+    };
+}
+function roughSize(mb) {
+    return mb >= 950 ? Math.round(mb / 100) / 10 + ' GB' : Math.max(10, Math.round(mb / 10) * 10) + ' MB';
+}
+/** The heads-up before the wait, or null when everything is already downloaded. first: nothing was ever installed. */
+export function firstStartNotice(first, pending) {
+    if (!first && !pending.names.length)
+        return null;
+    const what = pending.names.length
+        ? ' (about ' +
+            roughSize(pending.mb) +
+            ': ' +
+            pending.names.slice(0, 8).join(', ') +
+            (pending.names.length > 8 ? ', ...' : '') +
+            ')'
+        : '';
+    return first
+        ? 'First start: the sandbox downloads the tools this project needs once' +
+            what +
+            '. This can take 5-20 minutes depending on your connection; later starts take about a minute.'
+        : 'New tools for this project: the sandbox downloads them once' +
+            what +
+            '. This can take a few minutes; later starts skip it.';
+}

package/dist/cli/commands/launch/index.d.ts

@@ -0,0 +1,6 @@
+export * from './launch.js';
+export * from './running.js';
+export * from './prepare.js';
+export * from './add-root.js';
+export { bootLine, readyIn, stillWorking } from './boot-progress.js';
+export { firstStartNotice, pendingDownloads } from './first-start.js';

package/dist/cli/commands/launch/index.js

@@ -0,0 +1,6 @@
+export * from './launch.js';
+export * from './running.js';
+export * from './prepare.js';
+export * from './add-root.js';
+export { bootLine, readyIn, stillWorking } from './boot-progress.js';
+export { firstStartNotice, pendingDownloads } from './first-start.js';

package/dist/cli/commands/launch/launch.d.ts

@@ -0,0 +1,8 @@
+import { type Context } from '../context.js';
+/** A restart that adds a project: map these too, start no session at boot (restart.ts opens them), wait until ready. */
+export interface LaunchExtras {
+    readonly extraProjects?: string[];
+    readonly autoSession?: boolean;
+    readonly waitUntilReady?: boolean;
+}
+export declare function launch(ctx: Context, generateOnly?: boolean, extras?: LaunchExtras): Promise<number>;

package/dist/cli/commands/launch/launch.js

@@ -0,0 +1,211 @@
+// `launch` / `generate`, and what sandbox claude runs: start a sandbox, or another session in the running one. From a
+// folder the running sandbox does not have yet, the folder joins it (no restart) when it can, and otherwise a
+// restart that adds it is offered (restart.ts).
+import path from 'node:path';
+import _ from 'lodash';
+import { generateSandbox } from '../../../host/launch/index.js';
+import { findSecretFiles } from '../../../host/profile/index.js';
+import { RepoGuardStore } from '../../../host/guard/index.js';
+import { assertCanLaunch, isSandboxRunning, spawnDetached, startSandbox, probeHost, hideSandboxWindow, } from '../../../host/sandbox/index.js';
+import { KnownProjects, ProjectRegistry } from '../../../host/projects/index.js';
+import { LifeRecord } from '../../../host/life/index.js';
+import { isWithin } from '../../../shared/paths/index.js';
+import { watcherRunning } from '../../../sync/index.js';
+import { protectionsOf } from '../../../core/local-config/index.js';
+import { errMsg } from '../../../core/util/index.js';
+import { askYesNo } from '../../../core/prompt.js';
+import { resolveRun } from '../../../core/run/index.js';
+import { c, table } from '../../output/index.js';
+import { syncAgentCommands } from '../agent-commands.js';
+import { requireOnPc } from '../context.js';
+import { joinHere } from '../projects/index.js';
+import { startIntoRunning, launchIntoRunning, contextFor, waitForBoot, attachHere, waitForStart, openSession, readySandbox, } from './running.js';
+import { maybeAddRoot } from './add-root.js';
+import { prepare, firstBootNotice } from './prepare.js';
+import { bootWantsFor } from './boot-wants.js';
+import { launchSummary } from './summary.js';
+/** One launch (or `generate`): from the command line to a started sandbox, a session in it, or the written files. */
+class Launcher {
+    ctx;
+    generateOnly;
+    extras;
+    options;
+    constructor(ctx, generateOnly, extras) {
+        this.ctx = ctx;
+        this.generateOnly = generateOnly;
+        this.extras = extras;
+        this.options = ctx.options;
+    }
+    async run() {
+        const { options, generateOnly } = this;
+        // attach.auto: an agent started from an interactive terminal attaches it, as with -t.
+        if (this.ctx.loaded.config.attach.auto && !options.noAgent && process.stdin.isTTY && process.stdout.isTTY)
+            options.terminal = true;
+        if (!generateOnly)
+            requireOnPc('launch');
+        if (!generateOnly)
+            this.syncAgentCommands();
+        if (!generateOnly && isSandboxRunning())
+            return options.noAgent ? startIntoRunning(this.ctx, RELAUNCHER) : launchIntoRunning(this.ctx, RELAUNCHER);
+        if (options.sessions.length)
+            return this.launchSessions();
+        return this.launchHere();
+    }
+    /** agentCommands (Beta) follows the config: a setting changed in the file takes effect here too. Never blocks. */
+    syncAgentCommands() {
+        try {
+            syncAgentCommands(this.ctx, this.ctx.loaded.config);
+        }
+        catch (e) {
+            console.warn('Agent commands (Beta): ' + errMsg(e));
+        }
+    }
+    /**
+     * Several sessions: the sandbox starts from the first one's folder with the others' folders mapped too, then they
+     * all open in it (each project is set up on demand, in parallel). One --session is an ordinary launch.
+     */
+    async launchSessions() {
+        const { ctx, generateOnly, extras } = this;
+        const wants = this.options.sessions;
+        if (wants.length === 1)
+            return launch(contextFor(ctx, wants[0]), generateOnly, extras);
+        const first = contextFor(ctx, wants[0]);
+        const others = _.uniqBy(wants
+            .slice(1)
+            .map((w) => w.folder)
+            .filter((f) => !isWithin(wants[0].folder, f)), (f) => f.toLowerCase());
+        const started = await launch({ ...first, options: { ...first.options, terminal: false } }, generateOnly, {
+            ...extras,
+            extraProjects: [...(extras.extraProjects ?? []), ...others],
+            autoSession: false,
+            waitUntilReady: true,
+        });
+        return generateOnly || started !== 0 ? started : launchIntoRunning(ctx, RELAUNCHER);
+    }
+    resolve() {
+        const { options } = this;
+        return resolveRun({
+            packageRoot: this.ctx.packageRoot,
+            loaded: this.ctx.loaded,
+            cwd: process.cwd(),
+            workspace: options.workspace,
+            harness: options.harness,
+            noAgent: options.noAgent,
+            noLocalConfig: options.noLocalConfig,
+            trustConfig: options.trustConfig,
+            scripts: options.scripts,
+            databases: options.databases,
+            headless: options.headless,
+            nodeVersion: options.node,
+            pythonVersion: options.python,
+            ask: askYesNo,
+        });
+    }
+    /** One sandbox for this folder: resolve, prepare, write the launch files, then (unless generate) start it. */
+    async launchHere() {
+        const { ctx, generateOnly, extras } = this;
+        const run = await this.resolve();
+        const { config } = run;
+        if (!generateOnly)
+            assertCanLaunch();
+        if (!generateOnly && !extras.extraProjects)
+            await maybeAddRoot(ctx, run);
+        const prepared = generateOnly ? null : await prepare(ctx, run);
+        const bootWants = await bootWantsFor(ctx, run, extras.extraProjects);
+        const generated = generateSandbox({
+            packageRoot: ctx.packageRoot,
+            run,
+            harnessArgs: this.options.passthrough,
+            probe: probeHost(config, run.harnessName),
+            extraProjects: extras.extraProjects,
+            autoSession: extras.autoSession,
+            bootWants: bootWants.wants,
+        });
+        const notes = [...run.notes, ...bootWants.notes, ...generated.projects.notes, ...generated.mappingNotes];
+        for (const note of notes)
+            console.log(note);
+        this.warnSecretFiles(run);
+        table(launchSummary(run, generated, prepared));
+        if (generateOnly)
+            return 0;
+        this.record(run, generated);
+        startSandbox(generated.wsbPath);
+        this.startWatcher();
+        return this.afterStart(run, generated);
+    }
+    warnSecretFiles(run) {
+        const secretFiles = run.config.secrets.warnFiles ? findSecretFiles(run.workspaceHost) : [];
+        if (!secretFiles.length)
+            return;
+        const shown = secretFiles.slice(0, 12).join(', ') + (secretFiles.length > 12 ? ', ...' : '');
+        console.warn(c.yellow('Heads-up: the agent can read these files in your workspace, which often hold secrets: ' +
+            shown +
+            '. Move real credentials out of the folder (or use test ones). Silence with secrets.warnFiles = false.'));
+    }
+    /**
+     * Every folder the sandbox can write is snapshotted before it starts (the guard compares against this), and the
+     * projects it starts with are recorded host-side for the commands that run later.
+     */
+    record(run, generated) {
+        const { dataPath, storageRoot } = this.ctx;
+        const { config } = run;
+        const { roots, projects } = generated.projects;
+        new RepoGuardStore(dataPath).save(run.workspaceHost, projects.map((p) => p.host), roots.map((r) => r.host));
+        new ProjectRegistry(storageRoot).start({
+            launchId: generated.launchId,
+            protections: protectionsOf(generated.bootConfig),
+            primary: { host: run.workspaceHost, guest: config.guestWorkspace },
+            roots,
+            boot: projects,
+            atBoot: { memoryMb: generated.memoryMb, mappings: generated.mappings, widened: generated.widened },
+        });
+        new KnownProjects(storageRoot).remember(run.workspaceHost);
+        new LifeRecord(storageRoot, dataPath).start(config.sandbox.keepAwake);
+    }
+    /** Absolute: the watcher runs from another folder, and a relative --config there would make it exit silently. */
+    startWatcher() {
+        const { config } = this.options;
+        if (!watcherRunning(this.ctx.dataPath))
+            spawnDetached(this.ctx.entry, ['_watch', ...(config ? ['--config', path.resolve(config)] : [])]);
+    }
+    /** Waits for the boot and attaches when asked to; otherwise says where the agent opens. */
+    async afterStart(run, generated) {
+        const { ctx, options, extras } = this;
+        const { dataPath, storageRoot } = ctx;
+        const { config } = run;
+        // Hiding runs alongside; a failure to find the window must never break the launch or an attach.
+        const hidden = config.sandbox.headless ? hideSandboxWindow(storageRoot).catch(() => false) : null;
+        const headsUp = firstBootNotice(dataPath, generated, config);
+        if (options.terminal || options.noAgent || extras.waitUntilReady) {
+            if (headsUp)
+                console.log(headsUp);
+            await waitForBoot(dataPath, generated.launchId, Boolean(headsUp));
+            if (extras.waitUntilReady)
+                return 0;
+            // Without an agent there is no session to attach to: the sandbox itself is the result.
+            if (options.noAgent) {
+                console.log('Sandbox ready. Its window has a terminal in ' +
+                    config.guestWorkspace +
+                    '; from here: sandbox exec -- <command>, sandbox stop.');
+                return 0;
+            }
+            return attachHere(ctx, await waitForStart(ctx, generated.launchId, 'Starting ' + run.harnessName));
+        }
+        if (headsUp)
+            console.log(headsUp + '\nFollow along: sandbox logs -f');
+        if (hidden)
+            console.log((await hidden)
+                ? 'Sandbox running headless. Open the window: sbx-show   Attach here: sandbox claude -t'
+                : 'Could not find the sandbox window to hide (it may still be starting); run sandbox hide in a moment.');
+        else
+            console.log('Sandbox starting. ' +
+                run.harnessName +
+                ' opens in Windows Terminal inside it. Attach here any time: sandbox claude -t');
+        return 0;
+    }
+}
+export function launch(ctx, generateOnly = false, extras = {}) {
+    return new Launcher(ctx, generateOnly, extras).run();
+}
+/** What a restart (restart.ts) uses to start the sandbox again and reopen its sessions. */
+const RELAUNCHER = { launch, readySandbox, joinHere, openSession };

package/dist/cli/commands/launch/prepare.d.ts

@@ -0,0 +1,23 @@
+import type { Config, ResolvedRun } from '../../../core/types.js';
+import { type Context } from '../context.js';
+/** Nothing has been installed into this data set yet: the first start downloads every toolchain once. */
+export declare function firstBoot(dataPath: string): boolean;
+/** The first-start heads-up (also when this project needs tools not downloaded yet), or null. */
+export declare function firstBootNotice(dataPath: string, generated: {
+    toolchains: Record<string, {
+        on: boolean;
+    }>;
+    databases: {
+        database: string;
+    }[];
+}, config: Config): string | null;
+/** What prepare did, for the launch summary. */
+export interface Prepared {
+    readonly account: string | null;
+    readonly terminal: string;
+    readonly history: string;
+    readonly pruned: string;
+    readonly filter: string;
+}
+/** Everything a real launch does before the sandbox starts (skipped by `generate`, which only writes files). */
+export declare function prepare(ctx: Context, run: ResolvedRun): Promise<Prepared>;

package/dist/cli/commands/launch/prepare.js

@@ -0,0 +1,109 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { AccountStore } from '../../../host/profile/index.js';
+import { SandboxChannel } from '../../../host/channel/index.js';
+import { describePrune, pruneStorage } from '../../../host/storage/index.js';
+import { RepoGuardStore, readDataSize, saveMarkedProjects } from '../../../host/guard/index.js';
+import { ensureConpty, ensureTerminal } from '../../../host/tools/index.js';
+import { planView, viewSkipped, saveActiveViews, WorkspaceView } from '../../../host/workspace-view/index.js';
+import { saveForwards } from '../../../host/network/index.js';
+import { saveAuditSettings } from '../../../host/audit/collect.js';
+import { humanBytes } from '../../../core/disk.js';
+import { syncBeforeLaunch, watcherRunning } from '../../../sync/index.js';
+import { errMsg } from '../../../core/util/index.js';
+import { c, working } from '../../output/index.js';
+import { firstStartNotice, pendingDownloads } from './first-start.js';
+import { LifeRecord, UPDATE_RESTART_WARNING, updateRestartPending } from '../../../host/life/index.js';
+/** Nothing has been installed into this data set yet: the first start downloads every toolchain once. */
+export function firstBoot(dataPath) {
+    return !fs.existsSync(path.join(dataPath, 'tools', 'resolved-versions.json'));
+}
+/** The first-start heads-up (also when this project needs tools not downloaded yet), or null. */
+export function firstBootNotice(dataPath, generated, config) {
+    const wanted = [
+        'node',
+        ...Object.entries(generated.toolchains)
+            .filter(([, d]) => d.on)
+            .map(([name]) => name),
+        ...(config.toolchains.vscode.enabled ? ['vscode'] : []),
+        ...generated.databases.map((d) => d.database),
+    ];
+    return firstStartNotice(firstBoot(dataPath), pendingDownloads(wanted, (dir) => fs.existsSync(path.join(dataPath, 'tools', dir))));
+}
+function syncSummary(config, dataPath, workspaceHost) {
+    try {
+        const s = syncBeforeLaunch(config, dataPath, workspaceHost);
+        return s.history + ' file(s) of history in, claude-mem ' + s.claudeMem;
+    }
+    catch (e) {
+        return 'FAILED: ' + errMsg(e);
+    }
+}
+/**
+ * workspaceFilter: brings the project's filtered view in step before the sandbox maps it, and tells the background
+ * watcher to keep it in step while the sandbox runs. Returns the line for the launch table.
+ */
+async function prepareWorkspaceView(ctx, run) {
+    const plan = planView(run.config, ctx.storageRoot, run.workspaceHost);
+    saveActiveViews(ctx.storageRoot, ctx.dataPath, plan ? [plan.options] : []);
+    saveForwards(ctx.storageRoot, ctx.dataPath, run.config.sandbox.networking ? run.config.network.forwardPorts : []);
+    saveAuditSettings(ctx.storageRoot, ctx.dataPath, { ...run.config.audit, projects: [run.workspaceHost] });
+    saveMarkedProjects(ctx.storageRoot, ctx.dataPath, run.config.storage.markSandboxFiles ? [run.workspaceHost] : []);
+    const size = readDataSize(ctx.storageRoot, ctx.dataPath);
+    const limit = run.config.storage.warnDataGb;
+    if (limit > 0 && size && size.bytes > limit * 1024 ** 3)
+        console.warn(c.yellow('The persisted data takes ' +
+            humanBytes(size.bytes) +
+            ' (more than storage.warnDataGb, ' +
+            limit +
+            ' GB). See what: sandbox data; free space: sandbox data clean <what>.'));
+    if (!plan)
+        return (viewSkipped(run.config, run.workspaceHost) ??
+            'off (git-ignored files are visible in the sandbox; workspaceFilter.enabled keeps them out)');
+    const stats = await working('Preparing the workspace without its git-ignored files', () => new WorkspaceView(plan.options).prepare());
+    return ('on: git-ignored files stay on this PC' +
+        (stats.toView || stats.toHost
+            ? ' (' +
+                stats.toView +
+                ' copied in, ' +
+                stats.toHost +
+                ' out' +
+                (stats.conflicts ? ', ' + stats.conflicts + ' conflicts kept next to the file' : '') +
+                ')'
+            : '') +
+        '; ' +
+        plan.options.view);
+}
+/** Everything a real launch does before the sandbox starts (skipped by `generate`, which only writes files). */
+export async function prepare(ctx, run) {
+    const { options, dataPath, storageRoot } = ctx;
+    const { config } = run;
+    const accounts = new AccountStore(storageRoot);
+    const account = options.account ?? accounts.defaultName();
+    if (account && run.harnessName === 'claude' && account !== accounts.activeFor(dataPath))
+        accounts.activate(dataPath, account);
+    const terminal = config.provisioning.terminal.enabled
+        ? await ensureTerminal(dataPath, config.provisioning.refresh, { pwsh: config.toolchains.pwsh.enabled !== false })
+        : { exe: null, message: 'disabled' };
+    const conpty = config.provisioning.conpty.enabled ? await ensureConpty(dataPath, config.provisioning.refresh) : 'off';
+    const history = syncSummary(config, dataPath, run.workspaceHost);
+    const guarded = new RepoGuardStore(dataPath).check();
+    if (guarded.length)
+        console.warn(c.yellow('SECURITY: neutralised ' +
+            guarded.length +
+            ' change(s) the last sandbox made that could run code on this PC (see sandbox status).'));
+    const stopped = new LifeRecord(storageRoot, dataPath).lastStopWarning(watcherRunning(dataPath));
+    if (stopped)
+        console.warn(c.yellow(stopped));
+    if (updateRestartPending())
+        console.warn(c.yellow(UPDATE_RESTART_WARNING));
+    new SandboxChannel(dataPath).reset();
+    const filter = await prepareWorkspaceView(ctx, run);
+    return {
+        account,
+        terminal: terminal.message + '; pseudo console: ' + conpty,
+        history,
+        pruned: describePrune(pruneStorage(storageRoot)),
+        filter,
+    };
+}

package/dist/cli/commands/launch/running.d.ts

@@ -0,0 +1,45 @@
+import { attachTerminal } from '../../../host/channel/index.js';
+import type { SandboxStatus, SessionStatus } from '../../../core/types.js';
+import type { Context } from '../context.js';
+import { type Joined, type Relauncher } from '../projects/index.js';
+/** How openSession starts a session; restart.ts reopens sessions with reuse off and the agent's resume arguments. */
+export interface OpenSessionOptions {
+    readonly attach: boolean;
+    readonly harness?: string;
+    readonly args?: string[];
+    readonly reuse?: boolean;
+}
+/** A session to open: an agent (the default one when not given), a folder, arguments of its own. */
+interface Want {
+    readonly harness?: string;
+    readonly folder: string;
+    readonly args?: string[];
+}
+/**
+ * Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the
+ * attach).
+ */
+export declare function attachHere(ctx: Context, session: Parameters<typeof attachTerminal>[0]): Promise<number>;
+/** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
+export declare function runningSandboxStatus(dataPath: string): Promise<SandboxStatus>;
+/**
+ * Waits for the boot with its current step and what it sets up on one line (plain lines without a terminal).
+ * timed: say how long it took (a first start, where that is worth knowing).
+ */
+export declare function waitForBoot(dataPath: string, launchId: string | null, timed?: boolean): Promise<SandboxStatus>;
+/** The running sandbox, once it is ready. */
+export declare function readySandbox(dataPath: string): Promise<SandboxStatus>;
+/** Waits for a session to start (its project's setup, the agent's install) with its progress on a spinner. */
+export declare function waitForStart(ctx: Context, requestId: string, what: string): Promise<SessionStatus>;
+/**
+ * Starts (or picks back up) a session in the folder `joined` describes. attach: show it in this terminal.
+ * Exported for restart.ts, which reopens the sessions a restart ended.
+ */
+export declare function openSession(ctx: Context, ready: SandboxStatus, joined: Joined, o: OpenSessionOptions): Promise<number>;
+/** The same command, for one of its sessions (its folder, agent, and the arguments after -- plus its own). */
+export declare function contextFor(ctx: Context, want: Want): Context;
+/** A sandbox is already running: open the sessions in it (new tabs inside; optionally attach here). */
+export declare function launchIntoRunning(ctx: Context, relauncher: Relauncher): Promise<number>;
+/** `sandbox start` while one runs: this folder joins it (set up, no agent), or a restart that adds it is offered. */
+export declare function startIntoRunning(ctx: Context, relauncher: Relauncher): Promise<number>;
+export {};