windows-development-sandbox 1.4.0 → 1.4.3

package/dist/cli/commands/launch.js

@@ -1,366 +0,0 @@
-// `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 fs from 'node:fs';
-import { select } from '@inquirer/prompts';
-import { activateAccount, activeAccount, defaultAccount } from '../../host/accounts.js';
-import { attachTerminal, findUnwatchedSession } from '../../host/attach.js';
-import { requestSession, resetRunDir, waitForReady, waitForSession } from '../../host/channel.js';
-import { describePrune, pruneStorage } from '../../host/cleanup.js';
-import { generateSandbox } from '../../host/generate.js';
-import { findSecretFiles } from '../../host/secrets.js';
-import { checkRepo, saveRepoSnapshot } from '../../host/repo-guard.js';
-import { assertCanLaunch, insideSandbox, isSandboxRunning, probeHost, spawnDetached, startSandbox } from '../../host/platform.js';
-import { NeedsRestart, rememberProject, startRegistry } from '../../host/projects.js';
-import { ensureConpty, ensureTerminal } from '../../host/terminal.js';
-import { planView, saveActiveViews, viewSkipped, WorkspaceView } from '../../host/workspace-view/index.js';
-import { saveForwards } from '../../host/port-forward.js';
-import { saveAuditSettings } from '../../host/audit/collect.js';
-import { readDataSize, saveMarkedProjects } from '../../host/motw.js';
-import { humanBytes } from '../../core/disk.js';
-import { hideSandboxWindow, showSandboxWindow } from '../../host/window.js';
-import { readSandboxStatus } from '../../shared/rundir.js';
-import { isWithin } from '../../shared/projects.js';
-import { syncBeforeLaunch, watcherRunning } from '../../sync/watcher.js';
-import { protectionsOf } from '../../core/project-policy.js';
-import { assertSafeMapping, assertSafeWorkspace } from '../../core/safe-paths.js';
-import { errMsg, fail, isRootPath, sleep } from '../../core/util.js';
-import { syncAgentCommands } from './agent-commands.js';
-import { askYesNo } from '../../core/prompt.js';
-import { resolveRun } from '../../core/workspace.js';
-import { c } from '../colors.js';
-import { working } from '../progress.js';
-import { requireOnPc, sandboxAlive, table } from './context.js';
-import _ from 'lodash';
-import { hereDir, joinHere, readyHere } from './project.js';
-import { offerRestart } from './restart.js';
-import { addToList, setSetting } from './user-config.js';
-import { lastStopWarning, startLife, UPDATE_RESTART_WARNING, updateRestartPending } from '../../host/stops.js';
-/** Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the attach). */
-export const attachHere = (ctx, session) => {
-    if (ctx.loaded.config.attach.autoHide && !insideSandbox())
-        void hideSandboxWindow(ctx.storageRoot, 120).catch(() => false);
-    return attachTerminal(session);
-};
-/** Nothing has been installed into this data set yet: the first start downloads every toolchain once. */
-const firstBoot = (dataPath) => !fs.existsSync(path.join(dataPath, 'tools', 'resolved-versions.json'));
-const FIRST_BOOT = 'First start for this storage: the sandbox downloads and installs the toolchains, databases and agent this project needs.\n' +
-    'That takes a few minutes, once. Everything is kept, so every later start reuses it and takes seconds.';
-/** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
-export const runningSandboxStatus = async (dataPath) => {
-    for (let i = 0; i < 60; i++) {
-        const status = readSandboxStatus(dataPath);
-        if (status)
-            return status;
-        await sleep(1000);
-    }
-    return fail('A Windows Sandbox is running that this tool did not start (or that uses another storage.dataName).', 'Close that sandbox window first, then run sandbox claude again.');
-};
-/** Waits for the boot with its current step on a spinner (plain lines without a terminal). */
-export const waitForBoot = (dataPath, launchId) => {
-    let step = 'starting Windows Sandbox';
-    return working(() => 'Waiting for the sandbox: ' + step, () => waitForReady(dataPath, launchId, sandboxAlive, (m) => { step = m; }));
-};
-/** The running sandbox, once it is ready. */
-export const readySandbox = async (dataPath) => {
-    const status = await runningSandboxStatus(dataPath);
-    return status.phase === 'ready' ? status : waitForBoot(dataPath, status.launchId);
-};
-/** Waits for a session to start (its project's setup, the agent's install) with its progress on a spinner. */
-const waitForStart = (ctx, requestId, what) => {
-    let step = 'starting';
-    return working(() => what + ': ' + step, () => waitForSession(ctx.dataPath, requestId, sandboxAlive, 60 * 60 * 1000, (m) => { step = m; }));
-};
-/**
- * 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 const openSession = async (ctx, ready, joined, o) => {
-    const { options, loaded, dataPath } = ctx;
-    const cwd = joined.guestDir;
-    const harness = o.harness ?? options.harness ?? joined.harness ?? loaded.config.defaultHarness;
-    const args = o.args ?? options.passthrough;
-    // -t with nothing new for the agent: pick up this folder's session if no terminal on this PC shows it (its tab was
-    // closed, or you detached). Someone already attached, --new, or agent arguments: a new session, as before.
-    const reuse = (o.reuse ?? true) && o.attach && !options.newSession && args.length === 0 && loaded.config.attach.reuseSession;
-    const existing = reuse ? await findUnwatchedSession(dataPath, harness, cwd) : null;
-    if (existing) {
-        console.log('Reattaching to ' + harness + ' session ' + existing.id + ' in ' + cwd + ' (no other terminal is attached; --new starts another).');
-        return attachHere(ctx, existing);
-    }
-    console.log(joined.spec
-        ? 'Starting ' + harness + ' for ' + joined.project?.host + ' in the running sandbox (' + cwd + '; the first time sets up what it needs).'
-        : 'Sandbox already running: starting another ' + harness + ' session in ' + cwd);
-    // The agent's definition goes along: the sandbox may have booted with another agent.
-    const harnessSpec = loaded.config.harnesses[harness];
-    const requestId = requestSession(dataPath, harness, args, cwd, { ...(joined.spec ? { project: joined.spec } : {}), ...(harnessSpec ? { harnessSpec } : {}) });
-    const session = await waitForStart(ctx, requestId, 'Starting ' + harness + ' in ' + cwd);
-    if (o.attach)
-        return attachHere(ctx, session);
-    console.log('Session ' + session.id + ' opened in a new tab inside the sandbox. Attach here with: sandbox attach ' + session.id + (ready.headless ? '   (headless: sbx-show opens the window)' : ''));
-    return 0;
-};
-/** The sessions a launch asks for: each --session, else one (the agent, in this folder). */
-const wantedSessions = (ctx) => ctx.options.sessions.length ? ctx.options.sessions : [{ harness: ctx.options.harness, folder: hereDir(ctx) }];
-/** The same command, for one of its sessions (its folder, agent, and the arguments after -- plus its own). */
-const contextFor = (ctx, want) => ({ ...ctx, options: { ...ctx.options, workspace: want.folder, harness: want.harness, sessions: [], passthrough: [...ctx.options.passthrough, ...(want.args ?? [])] } });
-/** Several sessions at once: all requested together (projects set up in parallel), then listed; -t attaches the first. */
-const openSessions = async (ctx, ready, list) => {
-    const { dataPath, loaded, options } = ctx;
-    const requests = list.map(({ ctx: at, joined }) => {
-        const harness = at.options.harness ?? joined.harness ?? loaded.config.defaultHarness;
-        const harnessSpec = loaded.config.harnesses[harness];
-        const id = requestSession(dataPath, harness, at.options.passthrough, joined.guestDir, { ...(joined.spec ? { project: joined.spec } : {}), ...(harnessSpec ? { harnessSpec } : {}) });
-        return { id, harness, folder: at.options.workspace ?? joined.guestDir, cwd: joined.guestDir };
-    });
-    let started = 0;
-    const results = await working(() => 'Starting ' + requests.length + ' sessions (' + started + ' running)', () => Promise.allSettled(requests.map(async (r) => {
-        const s = await waitForSession(dataPath, r.id, sandboxAlive, 60 * 60 * 1000, () => undefined);
-        started++;
-        return s;
-    })));
-    table([['SESSION', 'AGENT', 'FOLDER', ''], ...requests.map((r, i) => {
-            const result = results[i];
-            return [r.id, r.harness, r.folder, result.status === 'fulfilled' ? 'running   sandbox attach ' + r.id : c.red('FAILED: ' + errMsg(result.reason))];
-        })]);
-    const first = results.find((r) => r.status === 'fulfilled');
-    if (options.terminal && first)
-        return attachHere(ctx, first.value);
-    if (!first)
-        return 1;
-    console.log('Each has its own tab inside the sandbox' + (ready.headless ? ' (headless: sbx-show opens the window)' : '') + '. Attach to any of them, from any terminal: sandbox attach');
-    return results.every((r) => r.status === 'fulfilled') ? 0 : 1;
-};
-/** A sandbox is already running: open the sessions in it (new tabs inside; optionally attach here). */
-const launchIntoRunning = async (ctx) => {
-    const ready = await readySandbox(ctx.dataPath);
-    const wants = wantedSessions(ctx);
-    // Every folder joins first: when one needs a restart, nothing has been started that the restart would end.
-    const joined = [];
-    const needs = [];
-    for (const want of wants) {
-        const at = ctx.options.sessions.length ? contextFor(ctx, want) : ctx;
-        try {
-            joined.push({ ctx: at, joined: await joinHere(at, ready) });
-        }
-        catch (e) {
-            if (!(e instanceof NeedsRestart))
-                throw e;
-            if (!needs.some((n) => n.hostDir.toLowerCase() === e.hostDir.toLowerCase()))
-                needs.push(e);
-        }
-    }
-    if (needs.length)
-        return offerRestart(ctx, needs, () => launchIntoRunning(ctx));
-    for (const note of _.uniq(joined.flatMap((j) => j.joined.notes)))
-        console.log(note);
-    if (joined.length === 1)
-        return openSession(joined[0].ctx, ready, joined[0].joined, { attach: ctx.options.terminal });
-    return openSessions(ctx, ready, joined);
-};
-/** `sandbox start` while one runs: this folder joins it (set up, no agent), or a restart that adds it is offered. */
-const startIntoRunning = async (ctx) => {
-    const ready = await readySandbox(ctx.dataPath);
-    let joined;
-    try {
-        joined = await readyHere(ctx, ready);
-    }
-    catch (e) {
-        if (e instanceof NeedsRestart)
-            return offerRestart(ctx, [e], () => startIntoRunning(ctx));
-        throw e;
-    }
-    const where = joined.spec ? ' This folder is ready in it as ' + joined.guestDir + ' (sbx-shell ' + joined.spec.name + ' opens a terminal there inside).' : '';
-    console.log('A sandbox is already running' + (showSandboxWindow(ctx.storageRoot) ? '; its window is in front now.' : '.') + where + ' Start an agent in it with sandbox claude (or sandbox <agent>); stop it with sandbox stop.');
-    return 0;
-};
-const 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);
-    }
-};
-/**
- * Asked once per parent folder: map it at every start (a project root), so the projects next to this one open in the
- * running sandbox without a restart. The answer is saved to your config.
- */
-const maybeAddRoot = async (ctx, run) => {
-    const { projects } = run.config;
-    const parent = path.dirname(run.workspaceHost);
-    if (!projects.askToAddRoot || ctx.options.yes || !process.stdin.isTTY || !process.stdout.isTTY)
-        return;
-    if (projects.roots.some((r) => isWithin(r, run.workspaceHost)) || projects.declinedRoots.some((d) => isWithin(d, parent) && isWithin(parent, d)))
-        return;
-    if (isRootPath(parent))
-        return;
-    try {
-        assertSafeWorkspace(parent, ctx.packageRoot, run.storageRoot);
-        assertSafeMapping(parent, ctx.packageRoot, run.storageRoot);
-    }
-    catch {
-        return;
-    }
-    const answer = await select({
-        message: 'Map ' + parent + ' at every start, so other projects there (also new ones) open in the running sandbox without a restart? Agents in the sandbox can then see every project in it.',
-        choices: [
-            { name: 'Yes, from now on', value: 'yes' },
-            { name: 'No (and do not ask again for this folder)', value: 'no' },
-            { name: 'Never ask this again', value: 'never' },
-        ],
-    });
-    if (answer === 'yes') {
-        addToList(ctx, ['projects', 'roots'], parent);
-        run.config.projects.roots.push(parent);
-        console.log('Added ' + parent + ' to projects.roots (sandbox projects roots remove ' + parent + ' undoes it).');
-    }
-    if (answer === 'no')
-        addToList(ctx, ['projects', 'declinedRoots'], parent);
-    if (answer === 'never')
-        setSetting(ctx, ['projects', 'askToAddRoot'], false);
-};
-/**
- * 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.
- */
-const prepareWorkspaceView = async (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). */
-const prepare = async (ctx, run) => {
-    const { options, dataPath, storageRoot } = ctx;
-    const { config } = run;
-    const account = options.account ?? defaultAccount(storageRoot);
-    if (account && run.harnessName === 'claude' && account !== activeAccount(dataPath))
-        activateAccount(storageRoot, 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 = checkRepo(dataPath);
-    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 = lastStopWarning(storageRoot, dataPath, watcherRunning(dataPath));
-    if (stopped)
-        console.warn(c.yellow(stopped));
-    if (updateRestartPending())
-        console.warn(c.yellow(UPDATE_RESTART_WARNING));
-    resetRunDir(dataPath);
-    const filter = await prepareWorkspaceView(ctx, run);
-    return { account, terminal: terminal.message + '; pseudo console: ' + conpty, history, pruned: describePrune(pruneStorage(storageRoot)), filter };
-};
-export const launch = async (ctx, generateOnly = false, extras = {}) => {
-    const { options, loaded, packageRoot, dataPath, storageRoot } = ctx;
-    // attach.auto: an agent started from an interactive terminal attaches it, as with -t.
-    if (loaded.config.attach.auto && !options.noAgent && process.stdin.isTTY && process.stdout.isTTY)
-        options.terminal = true;
-    if (!generateOnly)
-        requireOnPc('launch');
-    // agentCommands (Beta) follows the config: a setting changed in the file takes effect here too. Never blocks a launch.
-    if (!generateOnly) {
-        try {
-            syncAgentCommands(ctx, loaded.config);
-        }
-        catch (e) {
-            console.warn('Agent commands (Beta): ' + errMsg(e));
-        }
-    }
-    if (!generateOnly && isSandboxRunning())
-        return options.noAgent ? startIntoRunning(ctx) : launchIntoRunning(ctx);
-    // 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.
-    const wants = options.sessions;
-    if (wants.length === 1)
-        return launch(contextFor(ctx, wants[0]), generateOnly, extras);
-    if (wants.length > 1) {
-        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);
-    }
-    const run = await resolveRun({
-        packageRoot, 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,
-    });
-    const { config } = run;
-    if (!generateOnly)
-        assertCanLaunch();
-    if (!generateOnly && !extras.extraProjects)
-        await maybeAddRoot(ctx, run);
-    const prepared = generateOnly ? null : await prepare(ctx, run);
-    const generated = generateSandbox({ packageRoot, run, harnessArgs: options.passthrough, probe: probeHost(config, run.harnessName), extraProjects: extras.extraProjects, autoSession: extras.autoSession });
-    for (const note of [...run.notes, ...generated.projects.notes])
-        console.log(note);
-    const secretFiles = config.secrets.warnFiles ? findSecretFiles(run.workspaceHost) : [];
-    if (secretFiles.length) {
-        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.'));
-    }
-    const { roots, projects } = generated.projects;
-    table([
-        ['Workspace', run.workspaceHost + '  ->  ' + config.guestWorkspace + (config.readOnly ? '  (read-only)' : '')],
-        ['Agent', run.harnessName + (prepared?.account ? '  (account: ' + prepared.account + ')' : '') + '   Memory: ' + generated.memoryMb + ' MB   CPU: ' + (config.sandbox.cpuLimit === 'none' ? 'all' : 'max ' + config.sandbox.cpuLimit + '%') + '   Network: ' + config.sandbox.networking + (config.sandbox.headless ? '   HEADLESS' : '')],
-        ['Node', run.versions.node.spec + ' (' + run.versions.node.source + ')   Python: ' + run.versions.python.spec + ' (' + run.versions.python.source + ')'],
-        ...(prepared ? [['Ignored files', prepared.filter], ['Terminal', prepared.terminal], ['History', prepared.history], ['Cleanup', prepared.pruned]] : []),
-        ['Toolchains', Object.entries(generated.toolchains).filter(([, d]) => d.on).map(([name, d]) => name + ' (' + d.reason + ')').join(', ') || 'Node only (nothing else used by this project)'],
-        ...(generated.databases.length
-            ? generated.databases.map((d, i) => [i ? '' : 'Databases', d.database + (d.database === 'sqlserver' ? ' (cannot run in the sandbox; use Postgres or SQLite for local work)' : ' on port ' + d.port) + '  because ' + d.reasons[0] + (d.reasons.length > 1 ? ' (+' + (d.reasons.length - 1) + ' more)' : '')])
-            : [['Databases', 'none needed (databases.<name>.enabled = true adds one)']]),
-        ['Desktop', generated.personalization],
-        ['Claude', generated.profile.staged.length ? generated.profile.staged.join(', ') + (generated.profile.credentials ? '  (INCLUDING YOUR LOGIN)' : '') : 'no settings copied'],
-        ['Secrets', !config.secrets.strip ? 'NOT stripped (secrets.strip is off)' : generated.profile.secretsRemoved.length ? 'kept on this PC: ' + generated.profile.secretsRemoved.join(', ') + '  (secrets.allow lets one through)' : 'none found in what is copied'],
-        ...roots.map((r, i) => [i ? '' : 'Project roots', r.host + '  ->  ' + r.guest + '  (every project in it opens without a restart)']),
-        ...projects.map((p, i) => [i ? '' : 'Projects', p.host + '  ->  ' + p.guest]),
-        ...generated.mappings.slice(3).filter((m) => ![...roots, ...projects].some((p) => p.guest === m.guest)).map((m) => ['  map ' + (m.readOnly ? 'ro' : 'rw'), m.host + '  ->  ' + m.guest]),
-        ['Generated', generated.wsbPath],
-    ]);
-    if (generateOnly)
-        return 0;
-    // 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.
-    saveRepoSnapshot(dataPath, run.workspaceHost, projects.map((p) => p.host), roots.map((r) => r.host));
-    startRegistry(storageRoot, { launchId: generated.launchId, protections: protectionsOf(config), primary: { host: run.workspaceHost, guest: config.guestWorkspace }, roots, boot: projects });
-    rememberProject(storageRoot, run.workspaceHost);
-    startLife(storageRoot, dataPath, config.sandbox.keepAwake);
-    startSandbox(generated.wsbPath);
-    // Absolute: the watcher runs from another folder, and a relative --config there would make it exit silently.
-    if (!watcherRunning(dataPath))
-        spawnDetached(ctx.entry, ['_watch', ...(options.config ? ['--config', path.resolve(options.config)] : [])]);
-    // 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;
-    if (options.terminal || options.noAgent || extras.waitUntilReady) {
-        if (firstBoot(dataPath))
-            console.log(FIRST_BOOT);
-        await waitForBoot(dataPath, generated.launchId);
-        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 (firstBoot(dataPath))
-        console.log(FIRST_BOOT);
-    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;
-};

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

@@ -1,10 +0,0 @@
-import { type Context } from './context.js';
-export declare const sync: (ctx: Context) => number;
-export declare const logs: (ctx: Context) => Promise<number>;
-export declare const clean: (ctx: Context) => number;
-export declare const config: (ctx: Context) => number;
-export declare const doctor: (ctx: Context) => number;
-export declare const claudeHost: (ctx: Context) => number;
-export declare const watcher: (ctx: Context) => Promise<void>;
-/** `sandbox audit`: the audit log of the last days (audit.enabled), newest last. */
-export declare const audit: (ctx: Context) => Promise<number>;

package/dist/cli/commands/maintenance.js

@@ -1,187 +0,0 @@
-// sync, logs, clean, config, doctor, host-claude and the internal sync watcher.
-import fs from 'node:fs';
-import path from 'node:path';
-import { pathToFileURL } from 'node:url';
-import _ from 'lodash';
-import { DEFAULTS, userConfigPath, userDir } from '../../core/config.js';
-import { describeOverrides, isTrusted, LOCAL_CONFIG_NAME, normalizeOverrides, readLocalConfig, trustStorePath } from '../../core/local-config.js';
-import { assertNoLinks, expandPath, fail, plainText, safeText, sleep, writeJson } from '../../core/util.js';
-import { humanBytes } from '../../core/disk.js';
-import { AuditLog } from '../../host/audit/log.js';
-import { readKnown, readRegistry } from '../../host/projects.js';
-import { detectWsb } from '../../host/wsb.js';
-import { describePrune, pruneStorage } from '../../host/cleanup.js';
-import { doctorRows, hostClaude, insideSandbox, isSandboxRunning } from '../../host/platform.js';
-import { readSandboxStatus } from '../../shared/rundir.js';
-import { syncBack, watch } from '../../sync/watcher.js';
-import { printJson, table } from './context.js';
-import { c } from '../colors.js';
-export const sync = (ctx) => {
-    const running = isSandboxRunning();
-    const result = syncBack(ctx.dataPath, !running);
-    console.log('History: ' + result.history + ' item(s) synced back. claude-mem: ' + result.claudeMem + (running ? ' (claude-mem syncs when the sandbox closes)' : ''));
-    return 0;
-};
-const newestLog = (dir) => {
-    if (!fs.existsSync(dir))
-        return null;
-    const logs = fs.readdirSync(dir).filter((f) => /^(guest|daemon|bootstrap)-.*\.log$/.test(f) && fs.lstatSync(path.join(dir, f)).isFile());
-    const newest = _.maxBy(logs, (f) => fs.statSync(path.join(dir, f)).mtimeMs);
-    return newest ? path.join(dir, newest) : null;
-};
-export const logs = async (ctx) => {
-    const dir = path.join(ctx.dataPath, 'logs');
-    // The sandbox writes this folder: never read through a link it planted there.
-    assertNoLinks(ctx.dataPath, dir);
-    const file = newestLog(dir) ?? fail('No sandbox logs yet in ' + dir + '.', 'Logs appear after the first start (sandbox claude).');
-    console.log('== ' + file + ' ==');
-    let printed = 0;
-    // The log is written inside the sandbox: read only its tail, and make it safe for your terminal.
-    const print = () => {
-        const size = fs.statSync(file).size;
-        const from = printed === 0 ? Math.max(0, size - 64 * 1024) : printed;
-        if (size <= from)
-            return;
-        const fd = fs.openSync(file, 'r');
-        const buffer = Buffer.alloc(Math.min(size - from, 4 * 1024 * 1024));
-        fs.readSync(fd, buffer, 0, buffer.length, from);
-        fs.closeSync(fd);
-        const text = safeText(buffer.toString('utf8'));
-        process.stdout.write(printed === 0 ? text.split('\n').slice(-120).join('\n') : text);
-        printed = from + buffer.length;
-    };
-    print();
-    if (ctx.options.follow)
-        console.error('(following; Ctrl+C to stop)');
-    while (ctx.options.follow) {
-        await sleep(1000);
-        print();
-    }
-    return 0;
-};
-export const clean = (ctx) => {
-    const running = isSandboxRunning() ? readSandboxStatus(ctx.dataPath)?.launchId : undefined;
-    console.log('Cleanup: ' + describePrune(pruneStorage(ctx.storageRoot, { launchDays: ctx.options.days, keep: _.compact([running]) })));
-    return 0;
-};
-const initConfig = () => {
-    const file = userConfigPath();
-    if (fs.existsSync(file))
-        fail(file + ' already exists.');
-    fs.mkdirSync(path.join(userDir(), 'hooks', 'pre-agent'), { recursive: true });
-    // The schema sits next to the file (a local path), so editors trust it and show docs and autocomplete.
-    writeJson(file, { $schema: './config.schema.json', ...DEFAULTS });
-    console.log('Created ' + file + '. It lists every setting with its default; delete the ones you do not change.');
-    console.log('Your own hook scripts go in ' + path.join(userDir(), 'hooks') + '\\{pre-provision,pre-agent,post-agent}.');
-    console.log('For editor help in every project\'s .sandbox-config.json, run: sandbox config schema');
-    return 0;
-};
-/**
- * VS Code setting that maps every .sandbox-config.json (and the user config) to the local schema files, so project
- * files need no "$schema" line and nothing is fetched from the internet (remote schemas need trusting).
- */
-const printSchemaSettings = () => {
-    const url = (name) => pathToFileURL(path.join(userDir(), name)).href;
-    const setting = {
-        'json.schemas': [
-            { fileMatch: ['**/.sandbox-config.json'], url: url('sandbox-config.schema.json') },
-            { fileMatch: ['**/.agent-sandbox/config.json'], url: url('config.schema.json') },
-        ],
-    };
-    console.log('Add this to your VS Code settings.json (Ctrl+Shift+P > "Preferences: Open User Settings (JSON)"):\n');
-    console.log(JSON.stringify(setting, null, 2).slice(2, -2));
-    console.log('\nThe schema files live in ' + userDir() + ' and are refreshed whenever the sandbox command runs.');
-    return 0;
-};
-/**
- * `sandbox config check`: the folder's .sandbox-config.json validated and described (risky settings flagged, approval
- * state), without launching. Fails with the same message a launch would give when the file is not valid.
- */
-const checkLocalConfig = (ctx) => {
-    const dir = path.resolve(ctx.options.workspace ?? process.cwd());
-    const file = readLocalConfig(dir);
-    if (!file) {
-        console.log('No ' + LOCAL_CONFIG_NAME + ' in ' + dir + '; the sandbox uses your own settings only.');
-        return 0;
-    }
-    const overrides = normalizeOverrides(file.data, dir, file.path);
-    const approved = isTrusted(trustStorePath(ctx.storageRoot), file.path, file.hash);
-    console.log(file.path + ': valid. ' + (approved ? 'Approved (this exact version).' : 'Not approved yet: the next launch asks you.') + '\n');
-    for (const line of describeOverrides(overrides))
-        console.log('  ' + safeText(line));
-    return 0;
-};
-export const config = (ctx) => {
-    const [action = 'summary'] = ctx.options.positionals;
-    switch (action) {
-        case 'summary':
-            table([
-                ['Settings file', ctx.loaded.configPath ?? userConfigPath() + '  (does not exist yet; sandbox config init creates it)'],
-                ['Default agent', ctx.loaded.config.defaultHarness],
-                ['Storage', ctx.storageRoot],
-                ['Memory', String(ctx.loaded.config.sandbox.memoryMb) + (ctx.loaded.config.sandbox.memoryMb === 'auto' ? '' : ' MB')],
-            ]);
-            console.log('\nChange settings in the menu (sandbox > Settings). All of them as JSON: sandbox config show');
-            return 0;
-        case 'path':
-            console.log(ctx.loaded.configPath ?? userConfigPath() + '  (does not exist yet)');
-            return 0;
-        case 'init': return initConfig();
-        case 'show':
-            console.log(JSON.stringify(ctx.loaded.config, null, 2));
-            return 0;
-        case 'schema': return printSchemaSettings();
-        case 'check': return checkLocalConfig(ctx);
-        default: fail('Unknown config action "' + action + '".', 'Use one of: sandbox config show | path | init | schema | check');
-    }
-};
-export const doctor = (ctx) => {
-    const rows = doctorRows(ctx.loaded.config, ctx.options.harness ?? ctx.loaded.config.defaultHarness, ctx.storageRoot, ctx.loaded.configPath);
-    // Inside a sandbox the feature and "running" rows describe the sandbox itself, and the host rows describe nothing useful.
-    if (insideSandbox()) {
-        table([['Where', 'inside a Windows Sandbox started by this tool (run doctor on your PC to check the PC)'], ...rows.filter(([name]) => name === 'Config file')]);
-        return 0;
-    }
-    // Several projects: the roots mapped at every start, what the running sandbox has, and whether wsb share is there.
-    const p = ctx.loaded.config.projects;
-    const registry = isSandboxRunning() ? readRegistry(ctx.storageRoot) : null;
-    const wsb = p.wsbShare ? detectWsb() : null;
-    table([
-        ...rows,
-        ['Project roots', p.roots.length ? p.roots.map((r) => expandPath(r, ctx.loaded.base)).join(', ') : 'none (sandbox projects roots add <folder>)'],
-        ['All projects', p.all ? 'on: ' + readKnown(ctx.storageRoot).length + ' known project(s) mapped at every start (' + p.exclude.length + ' excluded)' : 'off'],
-        ['Projects running', registry ? registry.projects.map((x) => x.name + ' (' + x.mechanism + ')').join(', ') : '-'],
-        ['wsb share', !p.wsbShare ? 'off (projects.wsbShare)' : wsb ? 'available: ' + wsb.exe + (wsb.version ? ' ' + wsb.version : '') + ' (untested; a failure offers a restart instead)' : 'not on this Windows (needs Windows 11 24H2+ with the updated Windows Sandbox): folders outside your roots need a restart'],
-    ]);
-    return 0;
-};
-export const claudeHost = (ctx) => hostClaude(ctx.storageRoot, ctx.options.personal, ctx.options.passthrough);
-export const watcher = (ctx) => watch(ctx.dataPath);
-const KINDS = ['proc', 'file', 'session', 'guard', 'note'];
-const KIND_LABEL = { proc: 'program', file: 'file', session: 'session', guard: 'GUARD', note: 'note' };
-/** `sandbox audit`: the audit log of the last days (audit.enabled), newest last. */
-export const audit = async (ctx) => {
-    const settings = ctx.loaded.config.audit;
-    const kind = ctx.options.kind;
-    if (kind && !KINDS.includes(kind))
-        fail('Unknown kind "' + kind + '".', 'Use one of: ' + KINDS.join(', '));
-    const log = new AuditLog(AuditLog.dirFor(ctx.storageRoot, ctx.dataPath), settings);
-    const events = log.read({ days: ctx.options.days, kinds: kind ? [kind] : undefined, grep: ctx.options.grep });
-    if (printJson(ctx, events))
-        return 0;
-    if (!events.length) {
-        console.log(settings.enabled ? 'Nothing in the audit log for the last ' + ctx.options.days + ' day(s).' : 'The audit log is off. Turn it on in the menu (Settings > Security & privacy > Audit log) or with audit.enabled in your config.');
-        return 0;
-    }
-    for (const e of events) {
-        // What the sandbox reported is text from the sandbox: no control codes reach your terminal.
-        const [p, cmd, parent, dir, act] = [e.p, e.c, e.pp, e.w, e.a].map((v) => plainText(v ?? ''));
-        const what = e.k === 'proc' ? (cmd || p) + (parent ? c.dim('  <- ' + path.win32.basename(parent)) : '')
-            : e.k === 'file' ? act + ' ' + p + c.dim('  in ' + dir)
-                : e.k === 'session' ? act + ' ' + p + c.dim('  ' + dir + ' ' + cmd)
-                    : p;
-        console.log(c.dim(new Date(e.t).toLocaleString()) + '  ' + (e.k === 'guard' ? c.yellow(KIND_LABEL[e.k].padEnd(8)) : KIND_LABEL[e.k].padEnd(8)) + what + (e.n && e.n > 1 ? c.dim('  x' + e.n) : ''));
-    }
-    console.log(c.dim('\n' + events.length + ' event(s); the log takes ' + humanBytes(log.bytes()) + ' (' + AuditLog.dirFor(ctx.storageRoot, ctx.dataPath) + ').'));
-    return 0;
-};

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

@@ -1,29 +0,0 @@
-import type { SandboxStatus } from '../../core/types.js';
-import { type RegistryEntry } from '../../host/projects.js';
-import type { ProjectSpecT } from '../../shared/schema.js';
-import { type Context } from './context.js';
-/** The folder the command is about: --workspace, else the current one. */
-export declare const hereDir: (ctx: Context) => string;
-export interface Located {
-    project: RegistryEntry | null;
-    guestDir: string | null;
-}
-/** Where this folder is in the running sandbox, if it is in it at all (nothing is registered). */
-export declare const locateHere: (ctx: Context, status: SandboxStatus | null) => Located;
-export interface Joined {
-    project: RegistryEntry | null;
-    guestDir: string;
-    spec: ProjectSpecT | null;
-    harness: string | null;
-    notes: string[];
-}
-/**
- * Makes this folder a project of the running sandbox (nothing to do for the launch folder and projects already in
- * it): its .sandbox-config.json is approved like at a launch, its protections are checked, and it is made visible.
- * Throws NeedsRestart (host/projects.ts) when that is impossible without a restart.
- */
-export declare const joinHere: (ctx: Context, status: SandboxStatus) => Promise<Joined>;
-/** Waits until the sandbox has set a project up, with its progress on a spinner (plain lines without a terminal). */
-export declare const provisionJoined: (ctx: Context, joined: Joined) => Promise<void>;
-/** joinHere, then (for another project) waits until the sandbox has set it up. */
-export declare const readyHere: (ctx: Context, status: SandboxStatus) => Promise<Joined>;