windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/selftest/cli.test.d.ts

@@ -0,0 +1,2 @@
+import type { Harness } from './harness.js';
+export declare const cliTests: (t: Harness) => void;

package/dist/selftest/cli.test.js

@@ -0,0 +1,30 @@
+// The command manifest, parser and menu helpers: one definition drives both the flags and the menu.
+import { buildProgram, parseCli } from '../cli/args.js';
+import { COMMANDS } from '../cli/manifest.js';
+import { commandLine, readHistory, recordHistory, splitArgs } from '../cli/menu.js';
+import { editConfigText } from '../cli/settings.js';
+export const cliTests = (t) => {
+    const { check } = t;
+    t.section('CLI: manifest, parser, menu');
+    const program = buildProgram(() => undefined);
+    const visible = COMMANDS.filter((c) => !c.hidden).map((c) => c.name);
+    check(visible.every((name) => program.commands.some((c) => c.name() === name)) && program.commands.find((c) => c.name() === 'launch').options.some((o) => o.long === '--terminal'), 'every manifest command and option exists in the parser');
+    const start = parseCli(['start', '--headless']);
+    check(start.command === 'launch' && start.noAgent && start.headless === true, '`start` is launch without an agent');
+    const clean = parseCli(['data', 'clean', 'tools/go', 'logs', '--yes']);
+    check(clean.command === 'data' && clean.positionals.join() === 'clean,tools/go,logs' && clean.yes, 'data clean takes targets and --yes');
+    check(parseCli(['start', '--database', 'postgres,redis', '--database', 'mongodb']).databases.join() === 'postgres,redis,mongodb' && parseCli(['db', 'start', 'redis']).positionals.join() === 'start,redis', '--database takes lists and repeats; `db` takes an action and a name');
+    check(parseCli(['launch', '--harness', 'opencode', '--', '--continue']).passthrough.join() === '--continue', 'agent arguments after -- reach the agent');
+    check(JSON.stringify(splitArgs('--model "big one" -c \'x y\'')) === '["--model","big one","-c","x y"]' && commandLine(['exec', 'echo', 'a b']) === 'sandbox exec echo "a b"', 'menu: arguments split like a shell, command lines quoted');
+    const original = '{\n  // my notes stay\n  "sandbox": { "headless": true }\n}\n';
+    const set = editConfigText(original, ['attach', 'auto'], true);
+    const nested = 'text' in set ? editConfigText(set.text, ['databases', 'postgres', 'port'], 6543) : set;
+    const reset = 'text' in nested ? editConfigText(nested.text, ['sandbox', 'headless'], undefined) : nested;
+    const invalid = editConfigText(original, ['sandbox', 'memoryMb'], 12);
+    check('text' in reset && reset.text.includes('// my notes stay') && reset.text.includes('"auto": true') && reset.text.includes('"port": 6543') && !reset.text.includes('headless') && 'problems' in invalid && invalid.problems.join().includes('memoryMb'), 'settings screen: changes keep the file\'s comments, nested keys are created, reset removes a key, invalid values are not saved');
+    recordHistory(['launch', '--harness', 'claude']);
+    recordHistory(['status']);
+    recordHistory(['launch', '--harness', 'claude']);
+    recordHistory(['menu']);
+    check(readHistory().map((h) => h.argv.join(' ')).join('|') === 'launch --harness claude|status', 'history: newest first, no duplicates, the menu itself is not recorded');
+};

package/dist/selftest/config.test.d.ts

@@ -0,0 +1,3 @@
+import type { Fixtures } from './fixtures.js';
+import type { Harness } from './harness.js';
+export declare const configTests: (t: Harness, f: Fixtures) => Promise<void>;

package/dist/selftest/config.test.js

@@ -0,0 +1,74 @@
+// Config loading, argument parsing, workspace resolution and .sandbox-config.json trust.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseCli as parseArgs } from '../cli/args.js';
+import { loadConfig } from '../core/config.js';
+import { ensureDir } from '../core/util.js';
+import { autoGuestWorkspace } from '../core/workspace.js';
+export const configTests = async (t, f) => {
+    const { check, rejects, write, temp } = t;
+    t.section('config');
+    const builtIn = loadConfig();
+    check(builtIn.configPath === null && builtIn.config.guestWorkspace === 'auto' && !builtIn.config.sandbox.headless && !builtIn.config.sandbox.vGpu && builtIn.config.provisioning.git.access === 'full', 'no user config: built-in defaults (auto guest folder, headless off, vGPU off, git full)');
+    const custom = loadConfig(write(path.join(temp, 'cfg.json'), JSON.stringify({ sandbox: { headless: true }, toolchains: { rust: { enabled: false } }, mappings: [{ host: 'rel-folder', guest: 'C:\\Rel', readOnly: true }] })));
+    check(custom.config.sandbox.headless && custom.config.toolchains.rust.enabled === false && custom.config.toolchains.python.enabled === 'auto', 'a config file only needs the keys it changes (deep merge over defaults)');
+    check(await rejects(() => loadConfig(path.join(temp, 'missing.json')), 'Config file not found'), 'an explicit --config that does not exist is an error');
+    check(loadConfig(path.join(t.packageRoot, 'config.example.json')).config.defaultHarness === 'claude', 'config.example.json is valid');
+    ensureDir(path.join(temp, 'rel-folder'));
+    const relRun = await f.run({}, { ...custom.config, storage: f.baseConfig.storage });
+    check(relRun.config.mappings.some((m) => m.host === path.join(temp, 'rel-folder')), 'relative mappings in the user config resolve against the config file\'s folder');
+    t.section('arguments');
+    const wrapped = parseArgs(['--terminal', '--continue', '--headless', '--node', '20', '--', '--terminal'], true);
+    check(wrapped.command === 'launch' && wrapped.terminal && wrapped.headless === true && wrapped.node === '20' && wrapped.passthrough.join(' ') === '--continue --terminal', 'claude-sbx: sandbox flags are consumed, everything else goes to the agent');
+    check(await rejects(() => parseArgs(['status', '--bogus']), 'unknown option') && parseArgs(['account', 'use', 'work', '--no-restart']).positionals.join() === 'use,work' && parseArgs(['clean', '--days=3']).days === 3, 'agent-sandbox: unknown options are errors; positionals and --opt=value work');
+    const agentFlags = parseArgs(['--model', 'opus', '-p', 'fix it', '--json', '-f', 'x', '--timeout', '5', '--resume', 'abc'], true);
+    check(agentFlags.passthrough.join(' ') === '--model opus -p fix it --json -f x --timeout 5 --resume abc' && !agentFlags.json && !agentFlags.follow && agentFlags.timeout === 600, 'claude-sbx: only launch options are ours; any other flag (even ones agent-sandbox uses elsewhere) goes to the agent, in order');
+    const reserved = parseArgs(['--sbx-terminal', '--terminal', '--sbx-node=18'], true);
+    check(reserved.terminal && reserved.node === '18' && reserved.passthrough.join(' ') === '' && parseArgs(['launch', '--continue', '--sbx-headless']).passthrough.join() === '--continue' && await rejects(() => parseArgs(['--sbx-nope'], true), 'Unknown option: --sbx-nope'), '--sbx-<option> always means agent-sandbox; agent-sandbox launch passes agent flags too');
+    t.section('workspace');
+    const rA = await f.run();
+    check(rA.workspaceHost === f.workA && rA.config.guestWorkspace === 'C:\\Workspace\\work-a' && rA.harnessName === 'claude' && rA.dataPath.endsWith(path.join('data', 'testdata')), 'any folder is the workspace; guest path is C:\\Workspace\\<folder name>');
+    check(autoGuestWorkspace('C:\\x\\My Proj (2)') === 'C:\\Workspace\\My Proj _2_' && autoGuestWorkspace('D:\\...') === 'C:\\Workspace\\project', 'auto guest folder names are sanitised');
+    check(rA.versions.node.spec === '22.3.0' && rA.versions.node.source === 'this PC' && rA.versions.python.spec === '3', 'default Node version is this PC\'s; Python defaults to latest 3.x');
+    write(path.join(f.workA, '.nvmrc'), 'lts/iron\n');
+    write(path.join(f.workA, '.python-version'), '3.11\n');
+    const rV = await f.run();
+    check(rV.versions.node.spec === 'lts/iron' && rV.versions.node.source === '.nvmrc' && rV.versions.python.spec === '3.11', '.nvmrc and .python-version are respected');
+    check((await f.run({ nodeVersion: '18' })).versions.node.source === 'command line', '--node beats .nvmrc');
+    fs.rmSync(path.join(f.workA, '.nvmrc'));
+    fs.rmSync(path.join(f.workA, '.python-version'));
+    write(path.join(f.workA, '.node-version'), 'v20.11.1');
+    check((await f.run()).versions.node.spec === 'v20.11.1', '.node-version is respected');
+    fs.rmSync(path.join(f.workA, '.node-version'));
+    check(await rejects(() => f.run({ cwd: f.install }), 'install folder') && await rejects(() => f.run({ cwd: temp }), 'must not be able to change') && await rejects(() => f.run({ cwd: path.join(temp, 'storage') }), 'storage folder'), 'refuses the install folder, its parents and the storage folder');
+    const originalWindir = process.env.WINDIR;
+    ensureDir(path.join(temp, 'winroot', 'sys'));
+    process.env.WINDIR = path.join(temp, 'winroot');
+    const sysRefused = await rejects(() => f.run({ cwd: path.join(temp, 'winroot', 'sys') }), 'system folder');
+    process.env.WINDIR = originalWindir;
+    check(sysRefused && await rejects(() => f.run({ cwd: path.parse(temp).root }), 'whole drive'), 'refuses system folders and drive roots');
+    t.section('.sandbox-config.json');
+    const localB = { harness: 'codex', sandbox: { memoryMb: 4096, networking: false, headless: true }, toolchains: { node: { version: '18' }, rust: { enabled: false } }, mappings: [{ host: './assets', guest: 'C:\\Assets', readOnly: true }, { host: '../shared', guest: 'C:\\Shared', readOnly: false }], scripts: ['./setup.mjs'] };
+    f.writeLocal(f.workB, localB);
+    check(await rejects(() => f.run({ cwd: f.workB }), '--trust-config') && await rejects(() => f.run({ cwd: f.workB }), 'READ/WRITE'), 'an untrusted .sandbox-config.json is refused and its effects are listed');
+    check(await rejects(() => f.run({ cwd: f.workB, ask: async () => false }), 'has not been approved'), 'answering "no" refuses it');
+    const rB = await f.run({ cwd: f.workB, ask: async () => true });
+    check(rB.harnessName === 'codex' && rB.config.sandbox.memoryMb === 4096 && rB.config.sandbox.headless && !rB.config.toolchains.rust.enabled && rB.config.toolchains.python.enabled && rB.versions.node.source === '.sandbox-config.json', 'approved local settings apply over the defaults (incl. toolchains, headless)');
+    check(rB.config.mappings.some((m) => m.host === f.shared && !m.readOnly) && rB.scripts.includes(path.join(f.workB, 'setup.mjs')), 'relative paths resolve against the folder of .sandbox-config.json');
+    check((await f.run({ cwd: f.workB })).harnessName === 'codex' && (await f.run({ cwd: f.workB, noLocalConfig: true })).harnessName === 'claude' && (await f.run({ cwd: f.workB, harness: 'gemini' })).harnessName === 'gemini', 'approval is remembered; --no-local-config and --harness win');
+    check((await f.run({ cwd: f.workB, headless: false })).config.sandbox.headless === false, '--window beats a local headless setting');
+    f.writeLocal(f.workB, { ...localB, sandbox: { memoryMb: 6144 } });
+    check(await rejects(() => f.run({ cwd: f.workB }), 'has not been approved'), 'changing the file requires approval again');
+    const dirC = path.join(temp, 'work-c');
+    ensureDir(dirC);
+    const bad = async (content, needle) => { f.writeLocal(dirC, content); return rejects(() => f.run({ cwd: dirC, trustConfig: true }), needle); };
+    check(await bad({ storage: { root: 'C:\\x' } }, 'storage is not allowed') && await bad({ harnesses: {} }, 'harnesses is not allowed'), 'local file cannot change storage or agent executables');
+    check(await bad({ claudeProfile: { hostDir: 'C:\\x' } }, 'claudeProfile.hostDir is not allowed') && await bad({ toolchains: { node: { hostDir: 'x' } } }, 'toolchains.node.hostDir is not allowed'), 'local file cannot point at host folders');
+    check(await bad({ sandbox: { memoryMb: 12 } }, 'sandbox.memoryMb:') && await bad({ mappings: [{ host: 'x', guest: 'C:\\Windows\\x', readOnly: true }] }, 'reserved or invalid guest path') && await bad({ provisioning: { git: { access: 'admin' } } }, 'provisioning.git.access:'), 'values are type-checked; reserved guest paths and unknown git modes are rejected');
+    check(await bad('{\n  // a comment\n  "readOnly": tru\n}', 'line 3') && await bad({ _comment: 'old style' }, '_comment is not allowed'), 'broken JSON is reported with line and column; unknown keys are rejected');
+    f.writeLocal(dirC, '// comments and trailing commas are fine\n{\n  "readOnly": true, /* inline */\n}\n');
+    check((await f.run({ cwd: dirC, trustConfig: true })).config.readOnly === true, '.sandbox-config.json may contain comments and trailing commas');
+    f.writeLocal(dirC, { claudeProfile: { copyCredentials: true }, network: { blockPrivateRanges: false }, provisioning: { git: { access: 'full' } } });
+    check(await rejects(() => f.run({ cwd: dirC }), 'copies your Claude LOGIN') && await rejects(() => f.run({ cwd: dirC }), 'turns OFF the LAN block') && await rejects(() => f.run({ cwd: dirC }), 'commit and push'), 'risky settings are called out before approval');
+    fs.rmSync(path.join(dirC, '.sandbox-config.json'));
+};

package/dist/selftest/data.test.d.ts

@@ -0,0 +1,2 @@
+import type { Harness } from './harness.js';
+export declare const dataTests: (t: Harness) => void;

package/dist/selftest/data.test.js

@@ -0,0 +1,73 @@
+// `sandbox data` target resolution and `sandbox repair` detection (half-installed toolchains, leftovers, links).
+import fs from 'node:fs';
+import path from 'node:path';
+import { humanBytes, removeTree, resolveCleanTargets, sizeOf } from '../cli/commands/data.js';
+import { deadPidFiles, findHalfInstalled, findLinks, findStagingLeftovers, globalPackages, resolvedVersionsValid } from '../cli/commands/repair.js';
+import { ensureDir, errMsg } from '../core/util.js';
+export const dataTests = (t) => {
+    const { check, write } = t;
+    t.section('data: clean targets');
+    const storage = path.join(t.temp, 'data-store');
+    const dataPath = path.join(storage, 'data', 'default');
+    const resolve = (...inputs) => resolveCleanTargets(inputs, dataPath, storage).map((r) => path.relative(storage, r.path));
+    const rejected = (...inputs) => { try {
+        resolveCleanTargets(inputs, dataPath, storage);
+        return false;
+    }
+    catch (e) {
+        return errMsg(e).length > 0;
+    } };
+    const d = (...parts) => path.join('data', 'default', ...parts);
+    check(resolve('tools/go').join() === d('tools', 'go') && resolve('tools\\go').join() === d('tools', 'go') && resolve('Tools/agents/claude').join() === d('tools', 'agents', 'claude'), 'clean: tools/<name> and tools/agents/<name> resolve inside the data folder (either slash)');
+    check(resolve('databases/postgres-18').join() === d('databases', 'postgres-18') && resolve('logs').join() === d('logs') && resolve('launches').join() === 'launches' && resolve('state/claude').join() === d('state', 'claude'), 'clean: databases/<name>, logs, launches, state/<agent>');
+    check(resolve('tools', 'tools/go', 'tools/go').join() === d('tools') && resolve('all', 'logs').join() === [d(), 'launches'].join(), 'clean: nested and repeated targets collapse; all = the data folder + launches');
+    check(Boolean(resolveCleanTargets(['state/claude'], dataPath, storage)[0].warning?.includes('login')) && Boolean(resolveCleanTargets(['all'], dataPath, storage)[0].warning), 'clean: state and all carry a warning');
+    const bad = ['', '..', 'tools/..', 'tools/../../x', '../data', 'C:\\Windows', 'C:tools', '/etc', '\\\\server\\share', 'tools/*', 'tools/go:stream', 'tools/a/b', 'tools/agents/a/b', 'logs/guest.log', 'accounts', 'sync', 'windows', 'tools/.', 'tools/go.'];
+    const accepted = bad.filter((b) => !rejected(b));
+    check(accepted.length === 0 && rejected(), 'clean: rejects .., absolute paths, drive letters, UNC, wildcards, streams, too deep, unknown areas, nothing (accepted: ' + JSON.stringify(accepted) + ')');
+    t.section('data: sizes and removal never follow links');
+    const sized = path.join(t.temp, 'sized');
+    write(path.join(sized, 'a.bin'), 'x'.repeat(1000));
+    write(path.join(sized, 'sub', 'b.bin'), 'y'.repeat(24));
+    const outside = path.join(t.temp, 'outside');
+    write(path.join(outside, 'keep.txt'), 'z'.repeat(5000));
+    let linked = false;
+    try {
+        fs.symlinkSync(outside, path.join(sized, 'sub', 'escape'), 'junction');
+        linked = true;
+    }
+    catch { /* no junctions here */ }
+    check(sizeOf(sized) === 1024 && humanBytes(1536) === '1.5 KB' && humanBytes(0) === '0 B' && humanBytes(3 * 1024 ** 3) === '3.0 GB', 'data: sizes count real files only' + (linked ? ' (a junction counts 0)' : ''));
+    if (linked)
+        check(findLinks(sized).length === 1, 'repair: finds a junction planted in the data folder');
+    removeTree(sized, t.temp);
+    check(!fs.existsSync(sized) && fs.existsSync(path.join(outside, 'keep.txt')), 'data: removing a folder never deletes what a link inside points to');
+    t.section('repair: detection');
+    const tools = path.join(t.temp, 'repair', 'tools');
+    write(path.join(tools, 'go', '1.23.2', 'bin', 'go.exe'), 'x');
+    ensureDir(path.join(tools, 'go', '1.22.8', 'src'));
+    write(path.join(tools, 'java', 'jdk-21', 'bin', 'java.exe'), 'x');
+    ensureDir(path.join(tools, 'java', 'jdk-17', 'lib'));
+    write(path.join(tools, 'python', 'python-3.12.7', 'python.exe'), 'x');
+    write(path.join(tools, 'nvm', 'settings.txt'), 'x');
+    write(path.join(tools, 'nvm', 'v22.11.0', 'node.exe'), 'x');
+    ensureDir(path.join(tools, 'nvm', 'v20.18.0'));
+    write(path.join(tools, 'git', 'bin', 'bash.exe'), 'x');
+    ensureDir(path.join(tools, 'dotnet', 'sdk'));
+    ensureDir(path.join(tools, 'go', '1.24.0.staging-ab12cd'));
+    ensureDir(path.join(tools, 'node-staging'));
+    ensureDir(path.join(tools, 'rust.staging-0f'));
+    const half = findHalfInstalled(tools).map((h) => path.relative(tools, h.path)).sort();
+    check(half.join() === ['dotnet', 'java\\jdk-17', 'go\\1.22.8', 'nvm', 'nvm\\v20.18.0'].map((p) => p.split('\\').join(path.sep)).sort().join(), 'repair: half-installed toolchains = folder without its program (got ' + half.join(', ') + ')');
+    const staging = findStagingLeftovers(tools).map((p) => path.relative(tools, p)).sort();
+    check(staging.join() === [path.join('go', '1.24.0.staging-ab12cd'), 'node-staging', 'rust.staging-0f'].sort().join(), 'repair: interrupted downloads in tools and one level down (got ' + staging.join(', ') + ')');
+    check(resolvedVersionsValid('{"go":"1.23.2"}') && resolvedVersionsValid('\uFEFF{}') && !resolvedVersionsValid('{"go":') && !resolvedVersionsValid('[1]'), 'repair: resolved-versions.json must be a JSON object');
+    check(globalPackages('{"dependencies":{"agent-sandbox":{"version":"1.0.0"},"npm":{}}}').join() === 'agent-sandbox,npm' && globalPackages('nope').length === 0 && globalPackages('{"dependencies":3}').length === 0, 'repair: reads npm ls -g --json');
+    const run = path.join(t.temp, 'repair', 'run');
+    write(path.join(run, 'watcher-default.pid'), '4242');
+    write(path.join(run, 'watcher-other.pid'), String(process.pid));
+    write(path.join(run, 'watcher-junk.pid'), 'not a pid');
+    write(path.join(run, 'hidden-windows.json'), '[]');
+    const dead = deadPidFiles(run, (pid) => pid === process.pid).map((f) => path.basename(f)).sort();
+    check(dead.join() === 'watcher-default.pid,watcher-junk.pid', 'repair: stale watcher pid files (dead process or junk) are found; a live one is kept');
+};

package/dist/selftest/detect.test.d.ts

@@ -0,0 +1,2 @@
+import type { Harness } from './harness.js';
+export declare const detectTests: (t: Harness) => void;

package/dist/selftest/detect.test.js

@@ -0,0 +1,42 @@
+// "Which databases does this project need?": detection from real-world file shapes, and the plan the host builds.
+import { databasesFromServices, detectDatabases } from '../core/detect-databases.js';
+import { DEFAULTS } from '../core/config.js';
+import { databaseCatalog, planDatabases } from '../host/project-scan.js';
+import { voltaNode } from '../core/workspace.js';
+import { decideToolchains, resolveToolchains } from '../core/detect-toolchains.js';
+import { parseReleasePage } from '../shared/download.js';
+const found = (files, host = []) => detectDatabases(files, host).map((d) => d.database).join(',');
+export const detectTests = (t) => {
+    const { check } = t;
+    t.section('database detection');
+    const compose = { path: 'docker-compose.yml', text: 'services:\n  db:\n    image: postgres:16-alpine\n  cache:\n    image: "redis:7"\n  dynamo:\n    image: amazon/dynamodb-local:latest\n' };
+    check(found([compose]) === 'postgres,redis,dynamodb', 'compose services: postgres, redis and DynamoDB Local images');
+    check(found([{ path: 'package.json', text: '{"dependencies":{"pg":"^8.11.0","ioredis":"5","@aws-sdk/client-dynamodb":"3"}}' }]) === 'postgres,redis,dynamodb', 'package.json: pg, ioredis, @aws-sdk/client-dynamodb');
+    check(found([{ path: 'package.json', text: '{"dependencies":{"pgadmin-ui":"1","mysql-logger":"2","express":"4"}}' }]) === '', 'package.json: names that only contain a driver name do not count');
+    check(found([{ path: 'prisma/schema.prisma', text: 'datasource db {\n  provider = "mysql"\n  url = env("DATABASE_URL")\n}' }]) === 'mysql', 'Prisma: the datasource provider decides');
+    check(found([{ path: 'requirements.txt', text: 'django==5.0\npsycopg2-binary==2.9\npymongo>=4\n' }]) === 'postgres,mongodb', 'Python requirements: psycopg2 and pymongo');
+    check(found([{ path: 'Api/Api.csproj', text: '<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.0" />' }]) === 'sqlserver', '.NET: EF Core SQL Server provider');
+    check(found([{ path: '.env.example', text: 'DATABASE_URL=postgresql://user:pass@localhost:5432/app\nMONGO_URL=mongodb+srv://cluster/x\n' }]) === 'postgres,mongodb', '.env templates: connection-string schemes');
+    check(found([{ path: 'template.yaml', text: 'Resources:\n  Table:\n    Type: AWS::DynamoDB::Table\n' }]) === 'dynamodb', 'SAM/CloudFormation: a DynamoDB table resource');
+    check(found([{ path: 'go.mod', text: 'require (\n\tgithub.com/jackc/pgx/v5 v5.5.0\n\tgithub.com/aws/aws-sdk-go-v2/service/dynamodb v1.0.0\n)' }]) === 'postgres,dynamodb', 'go.mod: pgx and the DynamoDB SDK');
+    check(found([{ path: 'package.json', text: '{"dependencies":{"knex":"3"}}' }]) === '' && found([{ path: 'package.json', text: '{"dependencies":{"knex":"3"}}' }], ['mysql']) === 'mysql', 'an ORM that names no database uses the one installed on this PC (and nothing without one)');
+    check(databasesFromServices(['postgresql-x64-16', 'MySQL80', 'MSSQL$SQLEXPRESS', 'Spooler', 'Redis']).join() === 'postgres,mysql,sqlserver,redis', 'database services on this PC are recognised by name');
+    const plan = planDatabases({ ...DEFAULTS.databases, mongodb: { ...DEFAULTS.databases.mongodb, enabled: true }, redis: { ...DEFAULTS.databases.redis, enabled: false } }, 'unused', { files: [compose], host: [] });
+    check(plan.map((p) => p.database + '@' + p.version + ':' + p.port).join() === 'postgres@16:5432,mongodb@latest:27017,dynamodb@latest:8000' && plan.find((p) => p.database === 'dynamodb')?.adminPort === 8001, 'plan: "auto" from the project (compose pins Postgres 16), true always, false never; DynamoDB gets its admin UI');
+    const catalog = databaseCatalog({ ...DEFAULTS.databases, postgres: { ...DEFAULTS.databases.postgres, enabled: false, port: 6543 } });
+    check(catalog.map((p) => p.database).join() === 'postgres,mysql,mongodb,redis,dynamodb' && catalog[0].port === 6543, 'sbx-db catalog: every database that can run (not SQL Server), even ones off at boot, with their configured ports');
+    const volta = t.write(t.temp + '\\volta-ws\\package.json', '{"name":"x","volta":{"node":"20.11.1","pnpm":"9.1.0"}}');
+    t.write(t.temp + '\\no-volta-ws\\package.json', '{"name":"y","volta":{"node":"latest; rm -rf"}}');
+    check(voltaNode(volta.replace(/\\package\.json$/, '')) === '20.11.1' && voltaNode(t.temp + '\\no-volta-ws') === null && voltaNode(t.temp + '\\missing') === null, 'Volta: package.json "volta.node" picks the Node version (only a plain version is accepted)');
+    const tc = DEFAULTS.toolchains;
+    const goApi = decideToolchains(tc, ['README.md', 'go.mod', 'api/main.go'], ['python', 'rust']);
+    check(goApi.go.on && goApi.go.reason === 'go.mod' && !goApi.python.on && !goApi.rust.on && !goApi.dotnet.on && !goApi.java.on, 'toolchains: a Go project gets Go and nothing it does not use, whatever this PC has');
+    const fresh = decideToolchains(tc, ['notes.txt'], ['python', 'dotnet']);
+    check(fresh.python.on && fresh.dotnet.on && !fresh.go.on && fresh.python.reason.includes('this PC'), 'toolchains: a folder that is no project yet gets the languages this PC has');
+    const rusty = decideToolchains({ ...tc, python: { ...tc.python, enabled: true } }, ['Cargo.toml'], []);
+    check(rusty.rust.on && rusty.cpp.on && rusty.python.on && rusty.python.reason === 'enabled in config', 'toolchains: Rust brings its C/C++ linker; true in config always wins');
+    check(resolveToolchains(tc, goApi).go.enabled === true && resolveToolchains(tc, goApi).python.enabled === false, 'the sandbox gets plain decisions instead of "auto"');
+    const page = '<a href="/o/r/releases/download/v1/tool-win-x64.zip">x</a><span>sha256:' + 'a'.repeat(64) + '</span><a href="/o/r/releases/download/v1/tool-linux.tar.gz">y</a>';
+    const assets = parseReleasePage(page);
+    check(assets.length === 2 && assets[0].url === 'https://github.com/o/r/releases/download/v1/tool-win-x64.zip' && assets[0].sha256 === 'a'.repeat(64) && assets[1].sha256 === null, 'GitHub release page fallback (API rate limit): assets with their own sha256 only');
+};

package/dist/selftest/fixtures.d.ts

@@ -0,0 +1,232 @@
+import type { Config, HostProbe, ResolvedRun, RunRequest } from '../core/types.js';
+import { generateSandbox } from '../host/generate.js';
+import type { Harness } from './harness.js';
+export declare const HOST_NODE_VERSION = "v22.3.0";
+export declare const createFixtures: (t: Harness) => {
+    at: (...parts: string[]) => string;
+    hostNode: string;
+    hostClaude: string;
+    hostProfile: string;
+    hostGlobalState: string;
+    install: string;
+    workA: string;
+    workB: string;
+    shared: string;
+    makeConfig: (copyFromHost?: boolean) => Config;
+    baseConfig: {
+        defaultHarness: string;
+        guestWorkspace: string;
+        readOnly: boolean;
+        mappings: {
+            host: string;
+            guest: string;
+            readOnly: boolean;
+            optional?: boolean | undefined;
+        }[];
+        sandbox: {
+            memoryMb: number | "auto";
+            maxMemoryMb: number;
+            reserveHostMb: number;
+            vGpu: boolean;
+            networking: boolean;
+            clipboard: boolean;
+            audioInput: boolean;
+            videoInput: boolean;
+            printerRedirection: boolean;
+            protectedClient: boolean;
+            headless: boolean;
+        };
+        storage: {
+            root: string;
+            persistAgentState: boolean;
+            dataName: string;
+        };
+        network: {
+            blockPrivateRanges: boolean;
+        };
+        provisioning: {
+            copyFromHost: boolean;
+            fallbackToInstall: boolean;
+            refresh: boolean;
+            git: {
+                enabled: boolean;
+                access: "readonly" | "full" | "none";
+            };
+            terminal: {
+                enabled: boolean;
+            };
+        };
+        toolchains: {
+            node: {
+                version: string;
+                extraVersions: string[];
+                corepack: boolean;
+                volta: boolean | "auto";
+                globalPackages: string[];
+            };
+            python: {
+                enabled: boolean | "auto";
+                version: string;
+                python2: boolean;
+                pyenv: boolean | "auto";
+                tools: string[];
+            };
+            rust: {
+                enabled: boolean | "auto";
+                toolchain: string;
+                host: string;
+                components: string[];
+                targets: string[];
+                crates: string[];
+                targetDir: string;
+            };
+            msvc: {
+                enabled: boolean | "auto";
+                acceptLicense: boolean;
+                msvcVersion: string;
+                sdkVersion: string;
+            };
+            cpp: {
+                enabled: boolean | "auto";
+                flexBison: boolean;
+            };
+            dotnet: {
+                enabled: boolean | "auto";
+                channels: string[];
+                tools: string[];
+                workloads: string[];
+                frameworkTargets: string[];
+                netfx35: boolean;
+            };
+            go: {
+                enabled: boolean | "auto";
+                version: string;
+                tools: string[];
+            };
+            java: {
+                enabled: boolean | "auto";
+                version: string;
+                maven: boolean;
+                gradle: boolean;
+            };
+            ruby: {
+                enabled: boolean | "auto";
+                version: string;
+                gems: string[];
+            };
+            php: {
+                enabled: boolean | "auto";
+                version: string;
+                composer: boolean;
+            };
+            deno: {
+                enabled: boolean | "auto";
+            };
+            pwsh: {
+                enabled: boolean | "auto";
+            };
+            cli: {
+                gh: boolean | "auto";
+                zstd: boolean | "auto";
+                openssl: boolean | "auto";
+            };
+            bun: {
+                enabled: boolean;
+            };
+            uv: {
+                enabled: boolean;
+            };
+            vcRuntime: {
+                enabled: boolean;
+            };
+            mesa: {
+                enabled: boolean;
+                vulkan: boolean;
+            };
+            vscode: {
+                enabled: boolean;
+            };
+            environment: Record<string, string>;
+        };
+        databases: {
+            postgres: {
+                enabled: boolean | "auto";
+                version: string;
+                port: number;
+            };
+            mysql: {
+                enabled: boolean | "auto";
+                version: string;
+                port: number;
+            };
+            mongodb: {
+                enabled: boolean | "auto";
+                version: string;
+                port: number;
+            };
+            redis: {
+                enabled: boolean | "auto";
+                port: number;
+            };
+            dynamodb: {
+                enabled: boolean | "auto";
+                port: number;
+                adminPort: number;
+                admin: boolean;
+            };
+            sqlserver: {
+                enabled: boolean | "auto";
+            };
+        };
+        attach: {
+            enabled: boolean;
+            reuseSession: boolean;
+            auto: boolean;
+            autoHide: boolean;
+        };
+        secrets: {
+            strip: boolean;
+            allow: string[];
+            patterns: string[];
+            warnFiles: boolean;
+        };
+        personalization: {
+            enabled: boolean;
+        };
+        claudeProfile: {
+            enabled: boolean;
+            hostDir: string;
+            include: string[];
+            globalStateFile: string;
+            copyCredentials: boolean;
+            overwrite: boolean;
+            syncHistory: boolean;
+            syncClaudeMem: boolean;
+        };
+        harnesses: Record<string, {
+            arguments: string[];
+            environment: Record<string, string>;
+            hostExecutable?: string | undefined;
+            hostDir?: string | undefined;
+            npmPackage?: string | undefined;
+            npmBin?: string | undefined;
+            uvPackage?: string | undefined;
+            uvBin?: string | undefined;
+            resumeArguments?: string[] | undefined;
+        }>;
+        hooks: {
+            failFast: boolean;
+        };
+        $schema?: string | undefined;
+    };
+    probe: HostProbe;
+    run: (over?: Partial<RunRequest>, config?: Config) => Promise<ResolvedRun>;
+    generate: (r: ResolvedRun, args?: string[], p?: HostProbe) => ReturnType<typeof generateSandbox>;
+    writeLocal: (dir: string, content: unknown) => void;
+    runGuest: (launchPath: string, data: string, workspace: string, extra?: Record<string, string>) => {
+        status: number | null;
+        out: string;
+    };
+    readJson: (file: string) => any;
+};
+export type Fixtures = ReturnType<typeof createFixtures>;

package/dist/selftest/fixtures.js

@@ -0,0 +1,63 @@
+// A fake "host PC" inside the temp folder: Node, claude.exe, a ~/.claude profile, workspaces, and helpers to resolve,
+// generate and run the guest against it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { DEFAULTS } from '../core/config.js';
+import { generateSandbox } from '../host/generate.js';
+import { ensureDir } from '../core/util.js';
+import { resolveRun } from '../core/workspace.js';
+export const HOST_NODE_VERSION = 'v22.3.0';
+export const createFixtures = (t) => {
+    const { temp, write } = t;
+    const at = (...parts) => path.join(temp, ...parts);
+    const hostNode = at('host-node');
+    write(path.join(hostNode, 'node.exe'), 'x');
+    write(path.join(hostNode, 'node_modules', 'npm', 'bin', 'npm-cli.js'), '');
+    const hostClaude = at('host-claude');
+    write(path.join(hostClaude, 'claude.exe'), 'fake-claude');
+    const hostProfile = at('host-dot-claude');
+    write(path.join(hostProfile, 'settings.json'), '{ "theme": "dark" }');
+    write(path.join(hostProfile, 'CLAUDE.md'), 'my rules');
+    write(path.join(hostProfile, 'commands', 'review.md'), 'review cmd');
+    write(path.join(hostProfile, 'plugins', 'installed_plugins.json'), JSON.stringify({ path: hostProfile + '\\plugins\\cache\\claude-mem' }));
+    write(path.join(hostProfile, '.credentials.json'), '{ "token": "secret" }');
+    const hostGlobalState = write(at('host-claude.json'), JSON.stringify({ hasCompletedOnboarding: true, mcpServers: { github: { command: 'npx' } } }));
+    const install = at('install');
+    ensureDir(path.join(install, 'sub'));
+    const workA = at('work-a');
+    const workB = at('work-b');
+    const shared = at('shared');
+    for (const d of [workA, workB, shared, path.join(workB, 'assets'), at('storage')])
+        ensureDir(d);
+    write(path.join(workB, 'setup.mjs'), "import fs from 'node:fs'; import path from 'node:path'; fs.writeFileSync(path.join(process.env.AGENT_DATA, 'hook-ran.txt'), process.env.AGENT_WORKSPACE);\n");
+    write(at('host-tools', 'agents', 'claude', 'claude.exe'), 'fake-claude');
+    const makeConfig = (copyFromHost = true) => {
+        const c = structuredClone(DEFAULTS);
+        c.storage.root = at('storage');
+        c.storage.dataName = 'testdata';
+        c.sandbox.memoryMb = 8192;
+        c.provisioning.copyFromHost = copyFromHost;
+        c.provisioning.terminal.enabled = false;
+        c.harnesses.claude.hostDir = hostClaude;
+        c.claudeProfile = { ...c.claudeProfile, hostDir: hostProfile, globalStateFile: hostGlobalState };
+        c.personalization.enabled = false;
+        c.mappings = [{ host: at('missing-optional'), guest: 'C:\\GameSources\\Missing', readOnly: true, optional: true }];
+        return c;
+    };
+    const baseConfig = makeConfig();
+    const probe = { nodeDir: hostNode, harnessExe: { dir: hostClaude, file: 'claude.exe' }, gitDir: null, nvmDir: null, hostNodeVersion: HOST_NODE_VERSION };
+    const run = (over = {}, config = baseConfig) => resolveRun({ packageRoot: install, loaded: { config, configPath: null, base: temp }, cwd: workA, noAgent: false, noLocalConfig: false, trustConfig: false, scripts: [], ...over }, HOST_NODE_VERSION);
+    const generate = (r, args = [], p = probe) => generateSandbox({ packageRoot: t.packageRoot, run: r, harnessArgs: args, probe: p });
+    const writeLocal = (dir, content) => { write(path.join(dir, '.sandbox-config.json'), typeof content === 'string' ? content : JSON.stringify(content)); };
+    /** Runs the guest's bundled main.js in dry-run mode against fake sandbox folders. */
+    const runGuest = (launchPath, data, workspace, extra = {}) => {
+        const r = spawnSync(process.execPath, [path.join(launchPath, 'runtime', 'main.js')], {
+            encoding: 'utf8',
+            env: { ...process.env, AGENT_LAUNCH_DIR: launchPath, AGENT_DATA_DIR: data, AGENT_HOST_TOOLS_DIR: at('host-tools'), AGENT_WORKSPACE: workspace, AGENT_LOCAL_DIR: at('local'), AGENT_MANAGED_DIR: at('managed'), AGENT_DRY_RUN: '1', ...extra },
+        });
+        return { status: r.status, out: (r.stdout ?? '') + (r.stderr ?? '') };
+    };
+    const readJson = (file) => JSON.parse(fs.readFileSync(file, 'utf8'));
+    return { at, hostNode, hostClaude, hostProfile, hostGlobalState, install, workA, workB, shared, makeConfig, baseConfig, probe, run, generate, writeLocal, runGuest, readJson };
+};

package/dist/selftest/guest.test.d.ts

@@ -0,0 +1,3 @@
+import type { Fixtures } from './fixtures.js';
+import type { Harness } from './harness.js';
+export declare const guestTests: (t: Harness, f: Fixtures) => Promise<string>;

package/dist/selftest/guest.test.js

@@ -0,0 +1,61 @@
+// Generated sandbox (.wsb + launch folder) and the guest boot in dry-run mode.
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildWsb, gitIdentity, resolveMemoryMb } from '../host/generate.js';
+import { readJsonFile } from '../shared/rundir.js';
+export const guestTests = async (t, f) => {
+    const { check, rejects, at } = { ...t, at: f.at };
+    t.section('generated sandbox');
+    const rA = await f.run();
+    const gen = f.generate(rA, ['--version'], { ...f.probe, gitDir: f.shared, nvmDir: f.workB });
+    const wsb = fs.readFileSync(gen.wsbPath, 'utf8');
+    check(wsb.includes('<MemoryInMB>8192</MemoryInMB>') && wsb.includes('<SandboxFolder>C:\\Workspace\\work-a</SandboxFolder>') && wsb.includes('C:\\HostTools\\git') && wsb.includes('C:\\HostTools\\nvm') && !wsb.includes('Missing') && wsb.includes('logon.cmd</Command>') && wsb.includes('<vGPU>Disable</vGPU>'), 'wsb: memory, workspace, host git/nvm, optional mapping skipped, logon command, vGPU off');
+    const files = ['package.json', 'runtime/main.js', 'runtime/daemon.js', 'runtime/view.js', 'runtime/gitguard.js', 'sandbox/bootstrap.ps1', 'sandbox/logon.cmd', 'sandbox/trust.cmd', 'sandbox/ptyhost.cs', 'sandbox/gitshim.cs'];
+    const missing = files.filter((file) => !fs.existsSync(path.join(gen.launchPath, file)));
+    check(missing.length === 0 && fs.readdirSync(path.join(gen.launchPath, 'runtime')).length === 5, 'launch folder has the bundled sandbox runtime (5 self-contained files), the C# sources and the boot scripts' + (missing.length ? ' (missing: ' + missing.join(', ') + ')' : ''));
+    const logon = fs.readFileSync(path.join(gen.launchPath, 'sandbox', 'logon.cmd'), 'utf8');
+    check(logon.indexOf('trust.cmd') < logon.indexOf('wt.exe') && logon.includes('tools\\terminal\\wt.exe') && logon.includes('-NoExit'), 'logon.cmd applies sandbox trust settings first, then opens Windows Terminal (PowerShell fallback)');
+    const session = f.readJson(gen.sessionPath);
+    check(session.launchId === gen.launchId && session.workspace === 'C:\\Workspace\\work-a' && session.workspaceHost === f.workA && session.harnessArguments[0] === '--version' && session.hostTools.git && session.hostTools.nvm && /^\d+\.\d+\.\d+$/.test(session.hostTools.nodeVersion ?? '') && session.versions.node.spec === '22.3.0' && session.provisioning.git.access === 'full', 'session.json carries ids, paths, versions, host tools and git access');
+    const staged = path.join(gen.launchPath, 'claude-profile');
+    check(['settings.json', 'CLAUDE.md', '.claude.json', 'plugins'].every((file) => fs.existsSync(path.join(staged, file))) && !fs.existsSync(path.join(staged, '.credentials.json')), 'Claude settings and plugins staged; the login is not');
+    check(gitIdentity('[user]\n\tname = Josh\n\temail = "j@x.io"\n[credential]\n\thelper = store\n[url "https://TOKEN@github.com/"]\n\tinsteadOf = https://github.com/\n') === '[user]\n\tname = Josh\n\temail = j@x.io\n' && gitIdentity('[core]\n\tname = x\n') === '', 'only name/email from ~/.gitconfig reach the sandbox (no credential helpers or token URLs)');
+    check(buildWsb(f.baseConfig, 4096, [{ host: 'C:\\a&b', guest: 'C:\\X', readOnly: true }]).includes('C:\\a&amp;b'), 'wsb values are XML-escaped');
+    check(resolveMemoryMb({ ...f.baseConfig.sandbox, memoryMb: 'auto' }, 40000 * 1048576) === 31744 && await rejects(() => resolveMemoryMb({ ...f.baseConfig.sandbox, memoryMb: 'auto' }, 9000 * 1048576), 'Not enough free RAM'), "memory 'auto' follows free RAM minus reserve");
+    t.section('guest boot (dry run)');
+    const data1 = at('data1');
+    const r1 = f.runGuest(gen.launchPath, data1, f.workA, { AGENT_TEST_EXEMPT: '172.28.0.1' });
+    check(r1.status === 0 && r1.out.includes('would run:') && r1.out.includes('--version') && r1.out.includes('cwd=' + f.workA), 'guest starts the agent with its arguments in the workspace' + (r1.status === 0 ? '' : '\n' + r1.out));
+    check(['would provision nvm and Node 22.3.0 (from this PC)', 'would provision Python 3', 'would provision MinGW-w64 GCC', 'would provision Rust', '.NET SDK', 'would provision bun', 'would provision uv', 'would provision Git for Windows from this PC'].every((s) => r1.out.includes(s)), 'guest provisions nvm/Node, Python, MinGW, Rust, .NET, Bun, uv, Git');
+    const claudeState = path.join(data1, 'state', 'claude');
+    check(fs.readFileSync(path.join(claudeState, 'settings.json'), 'utf8').includes('dark') && fs.existsSync(path.join(claudeState, 'commands', 'review.md')) && !fs.existsSync(path.join(claudeState, '.credentials.json')), 'guest applied host Claude settings (no login)');
+    check(fs.readFileSync(path.join(claudeState, 'plugins', 'installed_plugins.json'), 'utf8').includes(JSON.stringify(claudeState).slice(1, -1)), 'plugin manifests are re-pointed at the sandbox Claude folder');
+    const guestState = f.readJson(path.join(claudeState, '.claude.json'));
+    check(guestState.mcpServers?.github?.command === 'npx', 'MCP servers from this PC are in the sandbox');
+    const manifest = fs.readFileSync(at('managed', 'CLAUDE.md'), 'utf8');
+    check(manifest.includes('DISPOSABLE Windows Sandbox') && manifest.includes(f.workA) && manifest.split('\n').length < 16 && fs.readFileSync(path.join(claudeState, 'CLAUDE.md'), 'utf8') === 'my rules' && fs.existsSync(path.join(data1, 'SANDBOX.md')), 'agent manifest goes to the managed CLAUDE.md (tiny); the user CLAUDE.md is untouched');
+    check(!fs.existsSync(at('managed', 'managed-settings.json')), 'git access full: no managed deny rules');
+    check(r1.out.includes('AgentSandbox-Block-Private') && r1.out.includes('remoteport=1-52,54-65535'), 'guest firewall plan blocks the LAN but keeps DNS to the gateway');
+    check(readJsonFile(path.join(data1, 'run', 'sandbox.json'))?.phase === 'ready', 'guest reports "ready" in run/sandbox.json');
+    // Second boot: host changed its MCP servers; the sandbox keeps its own .claude.json but gets the new servers.
+    fs.writeFileSync(path.join(claudeState, '.claude.json'), JSON.stringify({ ...guestState, oauthAccount: { emailAddress: 'sandbox@x' }, mcpServers: { local: { command: 'x' } } }));
+    fs.writeFileSync(path.join(gen.launchPath, 'claude-profile', '.claude.json'), JSON.stringify({ mcpServers: { github: { command: 'npx2' } }, projects: { [f.workA.replace(/\\/g, '/')]: { mcpServers: { db: { command: 'pg' } } } } }));
+    f.runGuest(gen.launchPath, data1, f.workA);
+    const merged = f.readJson(path.join(claudeState, '.claude.json'));
+    check(merged.oauthAccount.emailAddress === 'sandbox@x' && merged.mcpServers.github.command === 'npx2' && merged.mcpServers.local.command === 'x' && Object.values(merged.projects).some((p) => p.mcpServers?.db), 'MCP servers re-sync every boot (user + project scope) without touching the sandbox login');
+    const readonlyConfig = f.makeConfig();
+    readonlyConfig.provisioning.git.access = 'readonly';
+    const genRo = f.generate(await f.run({}, readonlyConfig));
+    f.runGuest(genRo.launchPath, at('data-ro'), f.workA, { AGENT_MANAGED_DIR: at('managed-ro') });
+    const policy = f.readJson(at('managed-ro', 'managed-settings.json'));
+    check(policy.permissions.deny.includes('Bash(git commit:*)') && policy.permissions.deny.includes('PowerShell(git push:*)') && policy.permissions.deny.includes('Edit(**/.git/**)') && !policy.permissions.deny.includes('Bash(git status:*)'), 'git readonly: Claude managed settings deny writing git commands and .git edits');
+    const genHook = f.generate(await f.run({ cwd: f.workB, harness: 'claude', trustConfig: true }));
+    const rHook = f.runGuest(genHook.launchPath, at('data-hook'), f.workB);
+    check(rHook.status === 0 && fs.readFileSync(at('data-hook', 'hook-ran.txt'), 'utf8') === f.workB, 'local "scripts" run inside the sandbox with the workspace set');
+    const genInstall = f.generate(await f.run({}, f.makeConfig(false)), [], { ...f.probe, nodeDir: null, harnessExe: null });
+    const r3 = f.runGuest(genInstall.launchPath, at('data3'), f.workA, { AGENT_HOST_TOOLS_DIR: at('empty') });
+    check(r3.status === 0 && r3.out.includes('npm-cli.js') && r3.out.includes('@anthropic-ai/claude-code') && !fs.readFileSync(genInstall.wsbPath, 'utf8').includes('HostTools'), 'install mode: nothing mapped from this PC, agent installed with npm');
+    const r5 = f.runGuest(f.generate(await f.run({ noAgent: true })).launchPath, at('data5'), f.workA);
+    check(r5.status === 0 && r5.out.includes('no agent requested'), '--no-agent provisions without an agent');
+    return gen.launchPath;
+};