windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/cli/args.js

@@ -0,0 +1,111 @@
+// 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 { Command, InvalidArgumentError, Option } from 'commander';
+import { fail } from '../core/util.js';
+import { COMMANDS } from './manifest.js';
+/** 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.')
+        .enablePositionalOptions()
+        .showHelpAfterError('(run with --help for usage)')
+        .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),
+        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, timeout: 600, days: 7,
+});

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/context.d.ts

@@ -0,0 +1,21 @@
+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;
+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,54 @@
+// 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();
+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.d.ts

@@ -0,0 +1,46 @@
+import { type Context } from './context.js';
+export type DataArea = 'tools' | 'databases' | 'state' | 'logs' | 'data' | 'host';
+export interface DataEntry {
+    area: DataArea;
+    name: string;
+    path: string;
+    bytes: number;
+}
+/** 1536 -> "1.5 KB". */
+export declare const humanBytes: (bytes: number) => string;
+/** Size on disk, never following links or junctions (a link counts as 0). */
+export declare const sizeOf: (p: string) => number;
+/**
+ * Deletes a folder or file without ever following a link: links found anywhere inside are removed themselves first,
+ * then the (now link-free) tree is deleted. A link in place of `p` is removed itself.
+ */
+/** Deletes p (strictly inside root): links inside are removed first and never followed; see shared/safe-remove.ts. */
+export declare const removeTree: (p: string, root: string) => void;
+/** 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[];
+export interface DiskUsage {
+    drive: string;
+    totalBytes: number;
+    freeBytes: number;
+    usedBytes: number;
+    holdsStorage: boolean;
+}
+/** Every local drive's size and free space, and which one holds the sandbox storage. */
+export declare const diskUsage: (storageRoot: string) => DiskUsage[];
+export declare const dataInfo: (ctx: Context) => number;
+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>;
+/** `sandbox data [info|clean] [targets...]`. */
+export declare const data: (ctx: Context) => number | Promise<number>;

package/dist/cli/commands/data.js

@@ -0,0 +1,249 @@
+// `sandbox data`: what persists between sandboxes (toolchains, databases, agent state, logs, host storage) and
+// removing chosen parts of it. Everything under the data folder is sandbox-writable: sizes and deletes never follow
+// links, and targets resolve strictly inside the data folder.
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import _ from 'lodash';
+import { removeRefusal, safeRemove } from '../../shared/safe-remove.js';
+import { assertNoLinks, dirExists, fail, isInsideOrEqual, isLink, removeLink } from '../../core/util.js';
+import { askYesNo } from '../../core/workspace.js';
+import { isSandboxRunning } from '../../host/platform.js';
+import { printJson, table } from './context.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'];
+/** 1536 -> "1.5 KB". */
+export const humanBytes = (bytes) => {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = bytes <= 0 ? 0 : Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+    const value = bytes / 1024 ** i;
+    return (i === 0 ? String(bytes) : value.toFixed(value < 10 ? 1 : 0)) + ' ' + units[i];
+};
+/** Size on disk, never following links or junctions (a link counts as 0). */
+export const sizeOf = (p) => {
+    try {
+        const stat = fs.lstatSync(p);
+        if (stat.isSymbolicLink())
+            return 0;
+        if (!stat.isDirectory())
+            return stat.size;
+        return _.sumBy(fs.readdirSync(p, { withFileTypes: true }), (d) => (d.isSymbolicLink() ? 0 : sizeOf(path.join(p, d.name))));
+    }
+    catch {
+        return 0;
+    }
+};
+/**
+ * Deletes a folder or file without ever following a link: links found anywhere inside are removed themselves first,
+ * then the (now link-free) tree is deleted. A link in place of `p` is removed itself.
+ */
+/** Deletes p (strictly inside root): links inside are removed first and never followed; see shared/safe-remove.ts. */
+export const removeTree = (p, root) => {
+    const unlinkInside = (dir) => {
+        for (const d of fs.readdirSync(dir, { withFileTypes: true })) {
+            const child = path.join(dir, d.name);
+            if (d.isSymbolicLink() || isLink(child))
+                removeLink(child);
+            else if (d.isDirectory())
+                unlinkInside(child);
+        }
+    };
+    if (isLink(p)) {
+        removeLink(p);
+        return;
+    }
+    if (!fs.existsSync(p))
+        return;
+    // Refused before anything is touched (safeRemove below checks again).
+    const refusal = removeRefusal(p, root);
+    if (refusal)
+        throw new Error('Refusing to delete ' + p + ': ' + refusal);
+    if (dirExists(p))
+        unlinkInside(p);
+    safeRemove(p, root);
+};
+/** 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());
+};
+const AREA_LABEL = { tools: 'Toolchains', databases: 'Databases', state: 'Agent state', logs: 'Logs', data: 'Other', host: 'On this PC' };
+/** Every local drive's size and free space, and which one holds the sandbox storage. */
+export const diskUsage = (storageRoot) => {
+    const storageDrive = path.parse(path.resolve(storageRoot)).root.toUpperCase();
+    return 'CDEFGHIJKLMNOPQRSTUVWXYZ'.split('').map((letter) => letter + ':\\').flatMap((drive) => {
+        try {
+            const s = fs.statfsSync(drive);
+            const totalBytes = s.blocks * s.bsize;
+            if (!totalBytes)
+                return [];
+            return [{ drive, totalBytes, freeBytes: s.bavail * s.bsize, usedBytes: totalBytes - s.bfree * s.bsize, holdsStorage: drive.toUpperCase() === storageDrive }];
+        }
+        catch {
+            return [];
+        }
+    });
+};
+export const dataInfo = (ctx) => {
+    const entries = collectDataEntries(ctx.dataPath, ctx.storageRoot);
+    const total = _.sumBy(entries, 'bytes');
+    const disks = diskUsage(ctx.storageRoot);
+    if (printJson(ctx, { dataPath: ctx.dataPath, storageRoot: ctx.storageRoot, totalBytes: total, entries, disks }))
+        return 0;
+    console.log('Disks\n');
+    table([['DRIVE', 'USED', 'FREE', 'SIZE', ''], ...disks.map((d) => [d.drive, humanBytes(d.usedBytes) + ' (' + Math.round((d.usedBytes / d.totalBytes) * 100) + '%)', humanBytes(d.freeBytes), humanBytes(d.totalBytes), d.holdsStorage ? '<- sandbox storage (' + humanBytes(total) + ' of it)' : ''])]);
+    console.log('');
+    console.log('Persistent data for the sandbox: ' + ctx.dataPath + ' (C:\\AgentData inside)\n');
+    if (!entries.length) {
+        console.log('Nothing stored yet. Toolchains, databases and agent logins appear here after the first start.');
+        return 0;
+    }
+    const rows = _.flatMap(_.groupBy(entries, 'area'), (group, area) => [
+        [AREA_LABEL[area], humanBytes(_.sumBy(group, 'bytes')), ''],
+        ...group.map((e) => ['  ' + e.name, humanBytes(e.bytes), e.path]),
+    ]);
+    table([...rows, ['', '', ''], ['Total', humanBytes(total), '']]);
+    console.log('\nFree space with: sandbox data clean <target...>  (e.g. tools/go, databases/postgres-18, logs, launches)');
+    return 0;
+};
+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)));
+};
+/** Asks the user to type `expected` (a stronger confirmation than y/N). */
+const askTyped = async (question, expected) => {
+    if (!process.stdin.isTTY)
+        return false;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((resolve) => rl.question(question + ' Type "' + expected + '" to confirm: ', resolve));
+    rl.close();
+    return answer.trim().toLowerCase() === expected;
+};
+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('Remove ' + (sized.length === 1 ? 'this' : 'these ' + sized.length) + ' (' + humanBytes(total) + ')?');
+        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;
+};
+/** `sandbox data [info|clean] [targets...]`. */
+export const data = (ctx) => {
+    const [action = 'info'] = ctx.options.positionals;
+    switch (action) {
+        case 'info':
+        case 'show':
+        case 'list': return dataInfo(ctx);
+        case 'clean':
+        case 'remove': return dataClean(ctx);
+        default: return fail('Unknown data action "' + action + '".', 'Use: sandbox data  (what is stored)  or  sandbox data clean <target...>');
+    }
+};

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

@@ -0,0 +1,8 @@
+export { createContext, type Context } from './context.js';
+export { launch } from './launch.js';
+export { setup } from './setup.js';
+export { data } from './data.js';
+export { repair, repairCommand } from './repair.js';
+export { attach, db, exec, hide, restart, sessions, show, status, stop } from './sessions.js';
+export { account } from './accounts.js';
+export { claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';

package/dist/cli/commands/index.js

@@ -0,0 +1,8 @@
+export { createContext } from './context.js';
+export { launch } from './launch.js';
+export { setup } from './setup.js';
+export { data } from './data.js';
+export { repair, repairCommand } from './repair.js';
+export { attach, db, exec, hide, restart, sessions, show, status, stop } from './sessions.js';
+export { account } from './accounts.js';
+export { claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';

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

@@ -0,0 +1,5 @@
+import { attachTerminal } from '../../host/channel.js';
+import { type Context } from './context.js';
+/** Attaches this terminal; with attach.autoHide the sandbox window hides meanwhile (best effort, never fails the attach). */
+export declare const attachHere: (ctx: Context, session: Parameters<typeof attachTerminal>[0]) => Promise<number>;
+export declare const launch: (ctx: Context, generateOnly?: boolean) => Promise<number>;