windows-development-sandbox 1.0.5 → 1.4.0

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

@@ -0,0 +1,106 @@
+// `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 | views. 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 === 'views') {
+            if (rest.length)
+                fail('Remove all views ("views"), not single ones.', usage);
+            return { target, path: path.join(storageRoot, 'views'), root: storageRoot, warning: 'Views are the copies of your projects without their git-ignored files (workspaceFilter). Your projects are not touched; what the sandbox built or installed in them (node_modules, build output) goes, and the next start copies the projects again.' };
+        }
+        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', 'views', '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' || entry.name === 'views'))
+        return entry.name;
+    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>;

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

@@ -0,0 +1,45 @@
+// `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 _ from 'lodash';
+import { diskUsage, humanBytes } from '../../../core/disk.js';
+import { fail } from '../../../core/util.js';
+import { printJson, table } from '../context.js';
+import { working } from '../../progress.js';
+import { dataClean } from './clean.js';
+import { collectDataEntries } from './collect.js';
+const AREA_LABEL = { tools: 'Toolchains', databases: 'Databases', state: 'Agent state', logs: 'Logs', data: 'Other', host: 'On this PC' };
+export const dataInfo = async (ctx) => {
+    const entries = await working('Measuring the saved data (big folders take a moment)', () => collectDataEntries(ctx.dataPath, ctx.storageRoot), !ctx.options.json);
+    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;
+};
+/** `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/data/remove.d.ts

@@ -0,0 +1,2 @@
+/** 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;

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

@@ -0,0 +1,30 @@
+// Deleting inside the data folder. The sandbox can write there, so links are removed themselves and never followed.
+import fs from 'node:fs';
+import path from 'node:path';
+import { dirExists, isLink, removeLink } from '../../../core/util.js';
+import { removeRefusal, safeRemove } from '../../../shared/safe-remove.js';
+/** 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);
+};

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

@@ -1,8 +1,10 @@
 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 { setup } from './setup/index.js';
+export { data } from './data/index.js';
+export { repairCommand } from './repair/index.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';
+export { projects } from './projects.js';
+export { audit, claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
+export { agentCommandsCommand, syncAgentCommands } from './agent-commands.js';

package/dist/cli/commands/index.js

@@ -1,8 +1,10 @@
 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 { setup } from './setup/index.js';
+export { data } from './data/index.js';
+export { repairCommand } from './repair/index.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';
+export { projects } from './projects.js';
+export { audit, claudeHost, clean, config, doctor, logs, sync, watcher } from './maintenance.js';
+export { agentCommandsCommand, syncAgentCommands } from './agent-commands.js';

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

@@ -1,5 +1,29 @@
-import { attachTerminal } from '../../host/channel.js';
+import { attachTerminal } from '../../host/attach.js';
+import type { SandboxStatus } from '../../core/types.js';
 import { type Context } from './context.js';
+import { type Joined } from './project.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>;
+/** The sandbox writes sandbox.json a few seconds into its boot; a second launch right after the first waits for it. */
+export declare const runningSandboxStatus: (dataPath: string) => Promise<SandboxStatus>;
+/** Waits for the boot with its current step on a spinner (plain lines without a terminal). */
+export declare const waitForBoot: (dataPath: string, launchId: string | null) => Promise<SandboxStatus>;
+/** The running sandbox, once it is ready. */
+export declare const readySandbox: (dataPath: string) => Promise<SandboxStatus>;
+/**
+ * Starts (or picks back up) a session in the folder `joined` describes. attach: show it in this terminal.
+ * Exported for restart.ts, which reopens the sessions a restart ended.
+ */
+export declare const openSession: (ctx: Context, ready: SandboxStatus, joined: Joined, o: {
+    attach: boolean;
+    harness?: string;
+    args?: string[];
+    reuse?: boolean;
+}) => Promise<number>;
+/** A restart that adds a project: map these too, start no session at boot (restart.ts opens them), wait until ready. */
+export interface LaunchExtras {
+    extraProjects?: string[];
+    autoSession?: boolean;
+    waitUntilReady?: boolean;
+}
+export declare const launch: (ctx: Context, generateOnly?: boolean, extras?: LaunchExtras) => Promise<number>;