windows-development-sandbox 0.0.0-stage → 1.1.0

package/dist/cli/args.js

@@ -0,0 +1,143 @@
+// Command-line parsing with commander. parseCli() only parses (no side effects), so it is easy to test; cli/index.ts
+// dispatches the result. sandbox claude & co parse as `launch`: every option launch does not own goes to the agent, in order.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command, InvalidArgumentError, Option } from 'commander';
+import { z } from 'zod';
+import { fail, tryReadJson } from '../core/util.js';
+import { c } from './colors.js';
+import { COMMANDS } from './manifest.js';
+/** Splits a command line like a shell: "quoted words" and 'quoted words' stay together. */
+export const splitArgs = (text) => [...text.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)].map((m) => m[1] ?? m[2] ?? m[3]);
+/**
+ * `<agent>@<folder>` (the folder may contain '@': only the first one splits), `<agent>` alone = the current folder,
+ * and `|<arguments>` for that session's agent only ('|' cannot be in a Windows path). Folders become absolute against
+ * `cwd`. Pure; validate.ts checks that the agent and folder exist.
+ */
+export const parseSessionWant = (input, cwd = process.cwd()) => {
+    const bar = input.indexOf('|');
+    const text = bar < 0 ? input : input.slice(0, bar);
+    const args = bar < 0 ? [] : splitArgs(input.slice(bar + 1));
+    const at = text.indexOf('@');
+    const harness = (at < 0 ? text : text.slice(0, at)).trim();
+    const folder = at < 0 ? '' : text.slice(at + 1).trim();
+    if (!harness)
+        fail('--session "' + text + '" names no agent.', 'Use --session <agent>@<folder>, e.g. --session claude@C:\\code\\api (the folder defaults to this one).');
+    return { harness, folder: path.resolve(cwd, folder || '.'), ...(args.length ? { args } : {}) };
+};
+/** This package's version (this file is dist/cli/args.js, two folders below package.json). */
+export const packageVersion = () => {
+    const file = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    return z.object({ version: z.string() }).safeParse(tryReadJson(file)).data?.version ?? 'unknown';
+};
+/** Reserved spelling for our launch options that can never clash with an agent's flags: --sbx-terminal, ... */
+const SBX_PREFIX = '--sbx-';
+const positiveNumber = (value) => {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new InvalidArgumentError('expected a positive number');
+    return n;
+};
+const collect = (value, previous = []) => [...previous, value];
+/** One commander option from its manifest entry. */
+const toOption = (o) => {
+    const flags = (o.short ? o.short + ', ' : '') + o.flag + (o.type === 'boolean' ? '' : ' <' + (o.value ?? 'value') + '>');
+    const option = new Option(flags, o.description);
+    if (o.type === 'number')
+        option.argParser(positiveNumber);
+    if (o.type === 'list')
+        option.argParser(collect);
+    if (o.default !== undefined)
+        option.default(o.default);
+    return option;
+};
+/** Every command, its options and help text, from manifest.ts. Actions only record what was parsed. */
+export const buildProgram = (record) => {
+    const program = new Command('sandbox')
+        .description('A disposable Windows Sandbox for development, with or without an AI agent, for the folder you are in. Run it with no arguments for the menu.')
+        .version(packageVersion(), '-v, --version', 'show the version')
+        .enablePositionalOptions()
+        .showHelpAfterError('  Fix:  run the command with --help to see how to use it.')
+        .configureOutput({ outputError: (text, write) => write(c.red('Error: ') + text.replace(/^error: /, '').replace(/^./, (ch) => ch.toUpperCase())) })
+        .addHelpText('after', '\nPut --config <file> before or after the command to use another settings file.\nExamples:\n  sandbox                       the menu\n  sandbox claude -t             start Claude and attach this terminal\n  sandbox data clean logs       delete the saved logs\n  sandbox exec -- npm test      run a command in the running sandbox')
+        .exitOverride();
+    for (const spec of COMMANDS) {
+        const cmd = program.command(spec.name, { hidden: spec.hidden }).description(spec.summary).option('--config <file>', 'config file (default: ~/.agent-sandbox/config.json)');
+        for (const option of spec.options)
+            cmd.addOption(toOption(option));
+        if (spec.json)
+            cmd.option('--json', 'machine-readable output');
+        for (const arg of spec.args)
+            cmd.argument((arg.required ? '<' : '[') + arg.name + (arg.variadic ? '...' : '') + (arg.required ? '>' : ']'), arg.description);
+        if (spec.passthrough === 'agent')
+            cmd.argument('[agentArgs...]', 'passed to the agent').allowUnknownOption().allowExcessArguments();
+        if (spec.passthrough === 'command')
+            cmd.passThroughOptions();
+        cmd.action((...args) => record(spec.name, args[args.length - 1]));
+    }
+    return program;
+};
+/** Turns `--sbx-<option>` into `--<option>` (only for options launch knows; anything else is an error). */
+const expandReserved = (argv, known) => {
+    const end = argv.indexOf('--');
+    return argv.map((token, i) => {
+        if ((end !== -1 && i > end) || !token.startsWith(SBX_PREFIX))
+            return token;
+        const [flag, value] = token.split(/=(.*)/s);
+        const option = '--' + flag.slice(SBX_PREFIX.length);
+        if (!known.has(option))
+            fail('Unknown option: ' + flag, 'Reserved --sbx- options: ' + [...known].map((o) => o.replace('--', SBX_PREFIX)).join(', '));
+        return value === undefined ? option : option + '=' + value;
+    });
+};
+/** Parses argv into the command name and options. Throws commander errors for unknown commands/options. */
+export const parseCli = (argv, wrapper = false) => {
+    let parsed = null;
+    const program = buildProgram((name, cmd) => { parsed = { name, cmd }; });
+    const launchFlags = new Set(program.commands.find((c) => c.name() === 'launch').options.map((o) => o.long).filter(Boolean));
+    const args = expandReserved(wrapper ? ['launch', ...argv] : argv, launchFlags);
+    program.parse(args, { from: 'user' });
+    if (!parsed)
+        return { ...defaults(), command: '' };
+    const { name, cmd } = parsed;
+    const o = { ...program.opts(), ...cmd.opts() };
+    const forAgent = ['launch', 'start', 'generate', 'host-claude'].includes(name);
+    // Commander keeps our `--` separator among the operands when unknown options are allowed; it is ours, not the agent's.
+    const separator = forAgent ? cmd.args.indexOf('--') : -1;
+    const operands = separator === -1 ? cmd.args : [...cmd.args.slice(0, separator), ...cmd.args.slice(separator + 1)];
+    return {
+        ...defaults(),
+        // `start` is launch without an agent.
+        command: name === 'start' ? 'launch' : name,
+        positionals: forAgent || name === 'exec' ? [] : operands,
+        passthrough: forAgent || name === 'exec' ? operands : [],
+        config: o.config,
+        workspace: o.workspace,
+        harness: o.harness,
+        account: o.account,
+        node: o.node,
+        python: o.python,
+        scripts: o.script ?? [],
+        databases: (o.database ?? []).flatMap((d) => d.split(',')).map((d) => d.trim()).filter(Boolean),
+        headless: o.window ? false : o.headless ? true : undefined,
+        terminal: Boolean(o.terminal),
+        newSession: Boolean(o.new),
+        noAgent: o.agent === false || name === 'start',
+        trustConfig: Boolean(o.trustConfig),
+        noLocalConfig: o.localConfig === false,
+        personal: Boolean(o.personal),
+        fromHost: Boolean(o.fromHost),
+        noRestart: o.restart === false,
+        follow: Boolean(o.follow),
+        json: Boolean(o.json),
+        yes: Boolean(o.yes),
+        all: Boolean(o.all),
+        sessions: (o.session ?? []).map((s) => parseSessionWant(s)),
+        timeout: o.timeout ?? 600,
+        days: o.days ?? 7,
+    };
+};
+const defaults = () => ({
+    command: '', positionals: [], passthrough: [], scripts: [], databases: [], terminal: false, newSession: false, noAgent: false, trustConfig: false, noLocalConfig: false,
+    personal: false, fromHost: false, noRestart: false, follow: false, json: false, yes: false, all: false, sessions: [], timeout: 600, days: 7,
+});

package/dist/cli/colors.d.ts

@@ -0,0 +1,24 @@
+/** The colour policy as a pure function (tested); `isTTY` is that of the stream being written to. */
+export declare const colorEnabled: (env: NodeJS.ProcessEnv, isTTY: boolean) => boolean;
+export declare const c: {
+    bold: (text: string) => string;
+    dim: (text: string) => string;
+    red: (text: string) => string;
+    green: (text: string) => string;
+    yellow: (text: string) => string;
+    cyan: (text: string) => string;
+};
+/** Removes colour codes (for measuring or comparing text). */
+export declare const stripAnsi: (text: string) => string;
+/** Cuts `text` to `max` visible characters, ending in an ellipsis (plain text only). */
+export declare const shorten: (text: string, max: number) => string;
+/** Cuts the middle out of a long path or id so both ends stay readable. */
+export declare const shortenMiddle: (text: string, max: number) => string;
+/** 1536 -> "1.5 KB" is in the data command; this is "3 min ago" for the tables. */
+export declare const ago: (then: number | string | Date, now?: number) => string;
+/** Width to lay text out in (terminal columns, 80 when unknown, never absurdly small). */
+export declare const termWidth: () => number;
+/** Each menu page starts on a clean screen (answered prompts would otherwise pile up above it). */
+export declare const clearScreen: () => void;
+/** Rows of a list that fit the terminal (leaving room for the prompt and the help line). */
+export declare const pageSizeFor: (wanted: number) => number;

package/dist/cli/colors.js

@@ -0,0 +1,42 @@
+// ANSI colours for terminal output (one place, so menus, errors and warnings agree).
+// Colour is on only for a terminal that wants it: not with NO_COLOR, TERM=dumb or piped output; FORCE_COLOR turns it on.
+/** The colour policy as a pure function (tested); `isTTY` is that of the stream being written to. */
+export const colorEnabled = (env, isTTY) => {
+    if (env.NO_COLOR)
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== '')
+        return env.FORCE_COLOR !== '0' && env.FORCE_COLOR !== 'false';
+    return isTTY && env.TERM !== 'dumb';
+};
+const paint = (code) => (text) => (colorEnabled(process.env, Boolean(process.stdout.isTTY)) ? '\x1b[' + code + 'm' + text + '\x1b[0m' : text);
+export const c = { bold: paint(1), dim: paint(2), red: paint(31), green: paint(32), yellow: paint(33), cyan: paint(36) };
+/** Removes colour codes (for measuring or comparing text). */
+export const stripAnsi = (text) => text.replace(/\x1b\[[0-9;]*m/g, '');
+/** Cuts `text` to `max` visible characters, ending in an ellipsis (plain text only). */
+export const shorten = (text, max) => (max < 2 || text.length <= max ? text : text.slice(0, max - 1) + '…');
+/** Cuts the middle out of a long path or id so both ends stay readable. */
+export const shortenMiddle = (text, max) => {
+    if (max < 5 || text.length <= max)
+        return text;
+    const keep = max - 1;
+    const head = Math.ceil(keep / 2);
+    return text.slice(0, head) + '…' + text.slice(text.length - (keep - head));
+};
+/** 1536 -> "1.5 KB" is in the data command; this is "3 min ago" for the tables. */
+export const ago = (then, now = Date.now()) => {
+    const secs = Math.max(0, Math.round((now - new Date(then).getTime()) / 1000));
+    if (secs < 45)
+        return 'just now';
+    if (secs < 3600)
+        return Math.round(secs / 60) + ' min ago';
+    if (secs < 86400)
+        return Math.round(secs / 3600) + ' h ago';
+    return Math.round(secs / 86400) + ' d ago';
+};
+/** Width to lay text out in (terminal columns, 80 when unknown, never absurdly small). */
+export const termWidth = () => Math.max(40, process.stdout.columns ?? 80);
+/** Each menu page starts on a clean screen (answered prompts would otherwise pile up above it). */
+export const clearScreen = () => { if (process.stdout.isTTY)
+    process.stdout.write('\x1b[2J\x1b[3J\x1b[H'); };
+/** Rows of a list that fit the terminal (leaving room for the prompt and the help line). */
+export const pageSizeFor = (wanted) => Math.max(5, Math.min(wanted, (process.stdout.rows ?? 30) - 6));

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

@@ -0,0 +1,2 @@
+import { type Context } from './context.js';
+export declare const account: (ctx: Context) => Promise<number>;

package/dist/cli/commands/accounts.js

@@ -0,0 +1,52 @@
+// `account list | save | use | default | remove`
+import { activateAccount, listAccounts, removeAccount, saveAccount, setDefaultAccount } from '../../host/accounts.js';
+import { restartSessions, runningSessions } from '../../host/channel.js';
+import { hostClaudeDir, hostGlobalStateFile } from '../../host/claude-profile.js';
+import { isSandboxRunning } from '../../host/platform.js';
+import { fail } from '../../core/util.js';
+import { printJson, sandboxAlive, table } from './context.js';
+const label = (a) => '"' + a.name + '"' + (a.email ? ' (' + a.email + ')' : '');
+/** This PC's Claude login location (config folder + global state file). */
+const hostLogin = (ctx) => {
+    const profile = ctx.loaded.config.claudeProfile;
+    return { claudeDir: hostClaudeDir(profile), globalStateFile: hostGlobalStateFile(profile) };
+};
+const list = (ctx) => {
+    const rows = listAccounts(ctx.storageRoot, ctx.dataPath);
+    if (printJson(ctx, rows))
+        return 0;
+    if (rows.length === 0) {
+        console.log('No saved accounts. Sign in inside the sandbox, then: sandbox account save <name>   (or --from-host to save this PC\'s login)');
+        return 0;
+    }
+    table([['', 'NAME', 'EMAIL', 'SAVED'], ...rows.map((a) => [(a.isActive ? '*' : ' ') + (a.isDefault ? 'D' : ' '), a.name, a.email ?? '-', a.savedAt.slice(0, 16).replace('T', ' ')])]);
+    console.log('\n* = active in the sandbox   D = default for new launches');
+    return 0;
+};
+const use = async (ctx, name) => {
+    console.log('Sandbox now uses ' + label(activateAccount(ctx.storageRoot, ctx.dataPath, name)) + '.');
+    const claudeRunning = isSandboxRunning() && runningSessions(ctx.dataPath).some((s) => s.harness === 'claude');
+    if (claudeRunning && !ctx.options.noRestart)
+        console.log((await restartSessions(ctx.dataPath, 'claude', sandboxAlive)).message + ' with --continue; the conversation carries on under the new account.');
+    return 0;
+};
+export const account = async (ctx) => {
+    const [action = 'list', name] = ctx.options.positionals;
+    const needName = () => name ?? fail('Missing account name.', 'Usage: sandbox account ' + action + ' <name>');
+    switch (action) {
+        case 'list': return list(ctx);
+        case 'save':
+            console.log('Saved account ' + label(saveAccount(ctx.storageRoot, ctx.dataPath, needName(), ctx.options.fromHost ? hostLogin(ctx) : null)) + '.');
+            return 0;
+        case 'use': return use(ctx, needName());
+        case 'default':
+            setDefaultAccount(ctx.storageRoot, needName());
+            console.log('Default account: ' + name);
+            return 0;
+        case 'remove':
+            removeAccount(ctx.storageRoot, needName());
+            console.log('Removed account ' + name);
+            return 0;
+        default: fail('Unknown account action "' + action + '".', 'Use one of: sandbox account list | save <name> | use <name> | default <name> | remove <name>');
+    }
+};

package/dist/cli/commands/agent-commands.d.ts

@@ -0,0 +1,6 @@
+import type { Config } from '../../core/types.js';
+import { type Reconciled } from '../../host/agent-commands.js';
+import { type Context } from './context.js';
+/** Brings this PC in line with agentCommands and says what changed (used after on/off, settings and launch). */
+export declare const syncAgentCommands: (ctx: Context, config: Config, quiet?: boolean) => Reconciled | null;
+export declare const agentCommandsCommand: (ctx: Context) => number;

package/dist/cli/commands/agent-commands.js

@@ -0,0 +1,61 @@
+// `sandbox agent-commands [status|on|off]` (Beta): typing claude, codex ... on this PC starts them in a hidden sandbox.
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfig, userConfigPath } from '../../core/config.js';
+import { fail } from '../../core/util.js';
+import { agentCommands, commandsDir, reconcileAgentCommands } from '../../host/agent-commands.js';
+import { insideSandbox } from '../../host/platform.js';
+import { writeFileAtomic } from '../../shared/rundir.js';
+import { c } from '../colors.js';
+import { editConfigText } from '../settings/edit.js';
+import { table } from './context.js';
+const entryOf = (ctx) => path.join(ctx.packageRoot, 'dist', 'bin', 'sandbox.js');
+/** Brings this PC in line with agentCommands and says what changed (used after on/off, settings and launch). */
+export const syncAgentCommands = (ctx, config, quiet = false) => {
+    if (insideSandbox())
+        return null;
+    const result = reconcileAgentCommands(config, ctx.storageRoot, process.execPath, entryOf(ctx));
+    if (!result.changed || quiet)
+        return result;
+    if (result.on) {
+        console.log('Agent commands (Beta) are on for: ' + (result.commands.map((a) => a.command).join(', ') || 'no installed agents found'));
+        console.log(c.dim('Open a new terminal, then type e.g. claude in any project folder. Run the real one: set SANDBOX_AGENT_DIRECT=1'));
+    }
+    else
+        console.log('Agent commands are off: claude, codex ... run on this PC again (open a new terminal).');
+    return result;
+};
+export const agentCommandsCommand = (ctx) => {
+    if (insideSandbox())
+        fail('Agent commands change your PC\'s PATH, so they are set up from your PC, not inside the sandbox.', 'Run sandbox agent-commands on in a terminal on your PC.');
+    const action = ctx.options.positionals[0] ?? 'status';
+    if (action === 'status') {
+        const config = ctx.loaded.config;
+        const found = agentCommands(config, ctx.storageRoot);
+        console.log('Agent commands (Beta): ' + (config.agentCommands.enabled ? c.green('on') : 'off') + c.dim('  (' + commandsDir(ctx.storageRoot) + ')'));
+        if (found.length)
+            table(found.map((a) => [a.command, 'sandboxed ' + a.harness + (config.agentCommands.enabled ? '' : ' when on'), c.dim('real: ' + a.real)]));
+        else
+            console.log(c.dim('No agents found on this PC (claude, codex, gemini ... on your PATH).'));
+        if (!config.agentCommands.enabled)
+            console.log(c.dim('Turn on with: sandbox agent-commands on'));
+        return 0;
+    }
+    if (action !== 'on' && action !== 'off')
+        fail('Unknown action "' + action + '".', 'Use: sandbox agent-commands [status|on|off]');
+    const file = ctx.loaded.configPath ?? userConfigPath();
+    const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+    const edited = editConfigText(text, ['agentCommands', 'enabled'], action === 'on' ? true : undefined);
+    if ('problems' in edited)
+        fail('Could not change ' + file + ': ' + edited.problems.join('; '), 'Fix the file with sandbox config check, then try again.');
+    writeFileAtomic(file, edited.text);
+    const result = syncAgentCommands(ctx, loadConfig(file).config, true);
+    if (result?.on) {
+        console.log('Agent commands (Beta) are on: ' + (result.commands.map((a) => a.command).join(', ') || 'no installed agents found yet'));
+        console.log(c.dim('Open a new terminal, then type e.g. claude in a project folder: it starts in a hidden sandbox and attaches.'));
+        console.log(c.dim('Run the real one on this PC: set SANDBOX_AGENT_DIRECT=1 (PowerShell: $env:SANDBOX_AGENT_DIRECT=1). Turn off: sandbox agent-commands off'));
+    }
+    else
+        console.log('Agent commands are off: claude, codex ... run on this PC again. Open a new terminal.');
+    return 0;
+};

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

@@ -0,0 +1,23 @@
+import type { CliOptions } from '../args.js';
+import type { LoadedConfig } from '../../core/types.js';
+export interface Context {
+    packageRoot: string;
+    entry: string;
+    options: CliOptions;
+    loaded: LoadedConfig;
+    storageRoot: string;
+    dataPath: string;
+}
+export declare const createContext: (packageRoot: string, entry: string, options: CliOptions) => Context;
+/** Prints rows as aligned columns (the last column is not padded). */
+export declare const table: (rows: string[][]) => void;
+/** Prints `value` as JSON when --json was given; returns whether it did. */
+export declare const printJson: (ctx: Context, value: unknown) => boolean;
+export declare const sandboxAlive: () => boolean;
+/** For commands that control the sandbox from your PC: inside the sandbox they make no sense. */
+export declare const requireOnPc: (what: string) => void;
+export declare const requireRunning: (hint?: string) => void;
+/** Maps a folder on this PC to its path inside the running sandbox (only folders inside the mapped workspace exist there). */
+export declare const guestPathFor: (hostDir: string, workspaceHost: string, guestWorkspace: string) => string;
+/** The guest folder for the current directory (or --workspace) in the running sandbox. */
+export declare const currentGuestDir: (ctx: Context, workspaceHost: string, guestWorkspace: string) => string;

package/dist/cli/commands/context.js

@@ -0,0 +1,57 @@
+// What every command receives, plus the small helpers they share.
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { loadConfig, userDir } from '../../core/config.js';
+import { expandPath, fail, isInsideOrEqual } from '../../core/util.js';
+import { GUEST_DATA_DIR, insideSandbox, isSandboxRunning } from '../../host/platform.js';
+/** Keeps ~/.agent-sandbox/*.schema.json in step with the installed version (local schema paths editors trust). */
+const refreshSchemas = (packageRoot) => {
+    const source = path.join(packageRoot, 'schemas');
+    if (!fs.existsSync(source))
+        return;
+    try {
+        fs.mkdirSync(userDir(), { recursive: true });
+        for (const name of fs.readdirSync(source)) {
+            const target = path.join(userDir(), name);
+            const text = fs.readFileSync(path.join(source, name), 'utf8');
+            if (!fs.existsSync(target) || fs.readFileSync(target, 'utf8') !== text)
+                fs.writeFileSync(target, text, 'utf8');
+        }
+    }
+    catch { /* editor help only; never block a command over it */ }
+};
+export const createContext = (packageRoot, entry, options) => {
+    refreshSchemas(packageRoot);
+    const loaded = loadConfig(options.config);
+    const storageRoot = expandPath(loaded.config.storage.root, loaded.base);
+    // Inside a sandbox, the sandbox's own data folder is the one to talk to.
+    return { packageRoot, entry, options, loaded, storageRoot, dataPath: insideSandbox() ? GUEST_DATA_DIR : path.join(storageRoot, 'data', loaded.config.storage.dataName) };
+};
+/** Prints rows as aligned columns (the last column is not padded). */
+export const table = (rows) => {
+    const widths = _.range(_.max(rows.map((r) => r.length)) ?? 0).map((i) => _.max(rows.map((r) => (r[i] ?? '').length)) ?? 0);
+    for (const row of rows)
+        console.log(row.map((cell, i) => (i === row.length - 1 ? cell : _.padEnd(cell, widths[i] + 2))).join(''));
+};
+/** Prints `value` as JSON when --json was given; returns whether it did. */
+export const printJson = (ctx, value) => {
+    if (ctx.options.json)
+        console.log(JSON.stringify(value, null, 2));
+    return ctx.options.json;
+};
+export const sandboxAlive = () => isSandboxRunning();
+/** For commands that control the sandbox from your PC: inside the sandbox they make no sense. */
+export const requireOnPc = (what) => { if (insideSandbox())
+    fail('You are inside the sandbox already, so "sandbox ' + what + '" has nothing to control.', 'Run it from a terminal on your PC.'); };
+export const requireRunning = (hint = '') => { if (!isSandboxRunning())
+    fail('No Windows Sandbox is running.', hint || 'Start one with sandbox claude.'); };
+/** Maps a folder on this PC to its path inside the running sandbox (only folders inside the mapped workspace exist there). */
+export const guestPathFor = (hostDir, workspaceHost, guestWorkspace) => {
+    if (!isInsideOrEqual(workspaceHost, hostDir))
+        fail('The running sandbox works on ' + workspaceHost + ', and Windows Sandbox cannot add folders while it runs.', 'Run from inside that folder, or stop the sandbox (sandbox stop) and launch again from ' + hostDir + '.');
+    const rel = path.relative(workspaceHost, hostDir);
+    return rel ? path.win32.join(guestWorkspace, rel) : guestWorkspace;
+};
+/** The guest folder for the current directory (or --workspace) in the running sandbox. */
+export const currentGuestDir = (ctx, workspaceHost, guestWorkspace) => guestPathFor(path.resolve(ctx.options.workspace ?? process.cwd()), workspaceHost, guestWorkspace);

package/dist/cli/commands/data/clean.d.ts

@@ -0,0 +1,15 @@
+import { type Context } from '../context.js';
+export interface CleanTarget {
+    /** The target as normalised (forward slashes), e.g. "tools/go". */
+    target: string;
+    path: string;
+    /** Folder the target must stay inside, with no links between the two. */
+    root: string;
+    warning?: string;
+}
+/**
+ * Turns `sandbox data clean` arguments into folders. Pure (no disk access); throws a UserError for anything that is
+ * not a plain relative target inside the data folder: absolute paths, drive letters, `..`, wildcards, unknown areas.
+ */
+export declare const resolveCleanTargets: (inputs: string[], dataPath: string, storageRoot: string) => CleanTarget[];
+export declare const dataClean: (ctx: Context) => Promise<number>;

package/dist/cli/commands/data/clean.js

@@ -0,0 +1,101 @@
+// `sandbox data clean`: turns the targets you name into folders inside the data folder, and removes them.
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { humanBytes, sizeOf } from '../../../core/disk.js';
+import { askTyped, askYesNo } from '../../../core/prompt.js';
+import { assertNoLinks, fail, isInsideOrEqual, isLink } from '../../../core/util.js';
+import { isSandboxRunning } from '../../../host/platform.js';
+import { table } from '../context.js';
+import { removeTree } from './remove.js';
+const DATA_AREAS = ['tools', 'databases', 'state', 'logs'];
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._ +@-]*$/;
+const LOGIN_WARNING = 'removes the agent logins, settings and history inside the sandbox (save a Claude login first with: sandbox account save <name>)';
+const ALL_WARNING = 'removes EVERYTHING the sandbox keeps: toolchains, databases, agent logins and history, logs and launch folders';
+/**
+ * Turns `sandbox data clean` arguments into folders. Pure (no disk access); throws a UserError for anything that is
+ * not a plain relative target inside the data folder: absolute paths, drive letters, `..`, wildcards, unknown areas.
+ */
+export const resolveCleanTargets = (inputs, dataPath, storageRoot) => {
+    const usage = 'Targets: all | tools | tools/<name> | tools/agents/<name> | databases | databases/<name> | state | state/<agent> | logs | launches. See them with: sandbox data';
+    if (!inputs.length)
+        fail('Say what to remove.', usage);
+    const resolved = inputs.map((raw) => {
+        const input = raw.trim();
+        if (!input)
+            fail('Empty target.', usage);
+        if (path.win32.isAbsolute(input) || path.posix.isAbsolute(input) || /^[A-Za-z]:/.test(input) || input.includes(':'))
+            fail('Refusing "' + raw + '": targets are relative to the data folder, not paths on this PC.', usage);
+        const parts = input.replace(/\\/g, '/').split('/').filter(Boolean);
+        const bad = parts.find((p) => !SEGMENT.test(p) || /^\.+$/.test(p) || /[. ]$/.test(p));
+        if (bad !== undefined)
+            fail('Refusing "' + raw + '": "' + bad + '" is not a plain folder name (no .., wildcards or special characters).', usage);
+        const [head, ...rest] = parts;
+        const area = head.toLowerCase();
+        if (parts.length > 3)
+            fail('Refusing "' + raw + '": too deep.', usage);
+        const target = [area, ...rest].join('/');
+        if (area === 'all' && !rest.length)
+            return { target: 'all', path: dataPath, root: path.join(storageRoot, 'data'), warning: ALL_WARNING };
+        if (area === 'launches')
+            return { target, path: path.join(storageRoot, 'launches', ...rest), root: storageRoot };
+        if (area === 'accounts' || area === 'sync')
+            fail('"' + area + '" is kept on this PC on purpose and is not removed here.', area === 'accounts' ? 'Remove a saved login with: sandbox account remove <name>' : usage);
+        if (!DATA_AREAS.includes(area))
+            fail('Unknown target "' + raw + '".', usage);
+        if (area === 'logs' && rest.length)
+            fail('Remove all logs ("logs"), not single files.', usage);
+        if (rest.length > (area === 'tools' && rest[0]?.toLowerCase() === 'agents' ? 2 : 1))
+            fail('Refusing "' + raw + '": too deep.', usage);
+        return { target, path: path.join(dataPath, area, ...rest), root: dataPath, ...(area === 'state' ? { warning: LOGIN_WARNING } : {}) };
+    });
+    // "all" covers everything; otherwise drop targets inside another target (tools + tools/go = tools).
+    const all = resolved.find((t) => t.target === 'all');
+    if (all)
+        return [all, { target: 'launches', path: path.join(storageRoot, 'launches'), root: storageRoot }];
+    const unique = _.uniqBy(resolved, (t) => t.path.toLowerCase());
+    return unique.filter((t) => !unique.some((o) => o !== t && isInsideOrEqual(o.path, t.path)));
+};
+export const dataClean = async (ctx) => {
+    const targets = resolveCleanTargets(ctx.options.positionals.slice(1), ctx.dataPath, ctx.storageRoot);
+    if (isSandboxRunning())
+        fail('A Windows Sandbox is running, and it uses these folders.', 'Close it first (sandbox stop), then run this again.');
+    // Every folder from the root down to the target's parent must be real; a link in place of the target is removed itself.
+    for (const t of targets)
+        assertNoLinks(t.root, path.dirname(t.path));
+    const present = targets.filter((t) => fs.existsSync(t.path) || isLink(t.path));
+    if (!present.length) {
+        console.log('Nothing to remove: ' + targets.map((t) => t.target).join(', ') + ' do(es) not exist.');
+        return 0;
+    }
+    const sized = present.map((t) => ({ ...t, bytes: sizeOf(t.path) }));
+    const total = _.sumBy(sized, 'bytes');
+    table(sized.map((t) => ['  ' + t.target, humanBytes(t.bytes), t.path]));
+    for (const t of sized)
+        if (t.warning)
+            console.log('Warning: ' + t.target + ' ' + t.warning + '.');
+    const yes = Boolean(ctx.options.yes);
+    if (!yes) {
+        const ok = sized.some((t) => t.target === 'all')
+            ? await askTyped('This cannot be undone; the next sandbox starts from scratch and reinstalls everything.', 'all')
+            : await askYesNo('Delete ' + sized.map((t) => t.target).join(', ') + ' (' + humanBytes(total) + ')? This cannot be undone.');
+        if (!ok) {
+            console.log('Nothing removed.' + (process.stdin.isTTY ? '' : ' Pass --yes to confirm without a prompt.'));
+            return 1;
+        }
+    }
+    const failed = [];
+    for (const t of sized) {
+        try {
+            removeTree(t.path, t.root);
+        }
+        catch (e) {
+            failed.push(t.target + ' (' + (e instanceof Error ? e.message : String(e)) + ')');
+        }
+    }
+    const freed = total - _.sumBy(sized, (t) => sizeOf(t.path));
+    console.log('Freed ' + humanBytes(freed) + '. ' + (sized.some((t) => t.root === ctx.dataPath || t.target === 'all') ? 'The next sandbox reinstalls what it needs.' : ''));
+    if (failed.length)
+        fail('Could not remove everything: ' + failed.join('; '), 'Close programs using those folders and run the same command again.');
+    return 0;
+};

package/dist/cli/commands/data/collect.d.ts

@@ -0,0 +1,11 @@
+export type DataArea = 'tools' | 'databases' | 'state' | 'logs' | 'data' | 'host';
+export interface DataEntry {
+    area: DataArea;
+    name: string;
+    path: string;
+    bytes: number;
+}
+/** Every row of `sandbox data`: the sandbox's data folder by area, then what this PC keeps for it. */
+export declare const collectDataEntries: (dataPath: string, storageRoot: string) => DataEntry[];
+/** The `sandbox data clean` target for a listed row, or null when that row is not removable (kept on this PC on purpose). */
+export declare const cleanTargetOf: (entry: DataEntry) => string | null;

package/dist/cli/commands/data/collect.js

@@ -0,0 +1,54 @@
+// What `sandbox data` lists: the data folder by area, then what this PC keeps for the sandbox.
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { sizeOf } from '../../../core/disk.js';
+import { dirExists, isLink } from '../../../core/util.js';
+const AREA_ORDER = ['tools', 'databases', 'state', 'logs', 'data', 'host'];
+/** Folders of the data folder that get one row per child; anything else at the top level is listed as itself. */
+const PER_CHILD = ['tools', 'databases', 'state'];
+/** Real (non-link) children of a real folder; a link in place of the folder yields nothing. */
+const entriesOf = (dir) => (dirExists(dir) && !isLink(dir) ? fs.readdirSync(dir, { withFileTypes: true }).filter((d) => !d.isSymbolicLink()) : []);
+const toolRows = (toolsDir) => {
+    const entries = entriesOf(toolsDir);
+    const folders = entries.filter((d) => d.isDirectory());
+    const files = entries.filter((d) => !d.isDirectory());
+    const row = (name, p) => ({ area: 'tools', name, path: p, bytes: sizeOf(p) });
+    return [
+        ...folders.flatMap((d) => (d.name.toLowerCase() === 'agents'
+            ? entriesOf(path.join(toolsDir, d.name)).map((a) => row('agents/' + a.name, path.join(toolsDir, d.name, a.name)))
+            : [row(d.name, path.join(toolsDir, d.name))])),
+        ...(files.length ? [{ area: 'tools', name: '(files in tools)', path: toolsDir, bytes: _.sumBy(files, (f) => sizeOf(path.join(toolsDir, f.name))) }] : []),
+    ];
+};
+/** Every row of `sandbox data`: the sandbox's data folder by area, then what this PC keeps for it. */
+export const collectDataEntries = (dataPath, storageRoot) => {
+    const inData = entriesOf(dataPath);
+    const rows = inData.flatMap((d) => {
+        const p = path.join(dataPath, d.name);
+        const area = d.name.toLowerCase();
+        if (area === 'tools')
+            return toolRows(p);
+        if (PER_CHILD.includes(area))
+            return entriesOf(p).map((c) => ({ area, name: area + '/' + c.name, path: path.join(p, c.name), bytes: sizeOf(path.join(p, c.name)) }));
+        return [{ area: area === 'logs' ? 'logs' : 'data', name: d.name, path: p, bytes: sizeOf(p) }];
+    });
+    const otherData = entriesOf(path.join(storageRoot, 'data')).filter((d) => d.isDirectory() && path.join(storageRoot, 'data', d.name).toLowerCase() !== path.resolve(dataPath).toLowerCase());
+    const host = [
+        ...['launches', 'accounts', 'sync', 'logs', 'run', 'host'].map((name) => ({ area: 'host', name, path: path.join(storageRoot, name), bytes: sizeOf(path.join(storageRoot, name)) })),
+        ...otherData.map((d) => ({ area: 'host', name: 'other data folder: ' + d.name, path: path.join(storageRoot, 'data', d.name), bytes: sizeOf(path.join(storageRoot, 'data', d.name)) })),
+    ].filter((r) => fs.existsSync(r.path));
+    return _.sortBy([...rows, ...host], (r) => AREA_ORDER.indexOf(r.area), (r) => -r.bytes, (r) => r.name.toLowerCase());
+};
+/** The `sandbox data clean` target for a listed row, or null when that row is not removable (kept on this PC on purpose). */
+export const cleanTargetOf = (entry) => {
+    if (entry.area === 'tools')
+        return entry.name.startsWith('(') ? null : 'tools/' + entry.name;
+    if (entry.area === 'databases' || entry.area === 'state')
+        return entry.name;
+    if (entry.area === 'logs')
+        return 'logs';
+    if (entry.area === 'host' && entry.name === 'launches')
+        return 'launches';
+    return null;
+};

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

@@ -0,0 +1,4 @@
+import { type Context } from '../context.js';
+export declare const dataInfo: (ctx: Context) => Promise<number>;
+/** `sandbox data [info|clean] [targets...]`. */
+export declare const data: (ctx: Context) => number | Promise<number>;