windows-development-sandbox 1.0.5 → 1.1.0

package/dist/selftest/data.test.js

@@ -1,73 +1,80 @@
-// `sandbox data` target resolution and `sandbox repair` detection (half-installed toolchains, leftovers, links).
+// `sandbox data` and `sandbox clean`: what a clean target may name, how sizes and removal treat links, and which old
+// launch folders, logs and downloads are pruned.
 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');
+import { resolveCleanTargets } from '../cli/commands/data/clean.js';
+import { removeTree } from '../cli/commands/data/remove.js';
+import { findLinks } from '../cli/commands/repair/finders.js';
+import { humanBytes, sizeOf } from '../core/disk.js';
+import { pruneStorage } from '../host/cleanup.js';
+export const dataSuite = {
+    name: 'data',
+    title: 'data clean targets, sizes and removal with links, storage cleanup',
+    run: async (t) => {
+        t.section('clean targets');
+        const storage = t.at('data-store');
+        const dataPath = path.join(storage, 'data', 'default');
+        const resolve = (...inputs) => resolveCleanTargets(inputs, dataPath, storage).map((r) => path.relative(storage, r.path));
+        const inData = (...parts) => path.join('data', 'default', ...parts);
+        t.equal(resolve('tools/go'), [inData('tools', 'go')], 'tools/<name> resolves inside the data folder');
+        t.equal(resolve('tools\\go'), [inData('tools', 'go')], 'either slash works');
+        t.equal(resolve('Tools/agents/claude'), [inData('tools', 'agents', 'claude')], 'tools/agents/<name> resolves, whatever the case');
+        t.equal(resolve('databases/postgres-18'), [inData('databases', 'postgres-18')], 'databases/<name> resolves');
+        t.equal(resolve('logs'), [inData('logs')], 'logs resolves');
+        t.equal(resolve('launches'), ['launches'], 'launches resolves to the storage folder\'s launches');
+        t.equal(resolve('state/claude'), [inData('state', 'claude')], 'state/<agent> resolves');
+        t.equal(resolve('tools', 'tools/go', 'tools/go'), [inData('tools')], 'nested and repeated targets collapse');
+        t.equal(resolve('all', 'logs'), [inData(), 'launches'], '`all` is the data folder plus launches');
+        t.check(Boolean(resolveCleanTargets(['state/claude'], dataPath, storage)[0].warning?.includes('login')), 'cleaning state warns about the login');
+        t.check(Boolean(resolveCleanTargets(['all'], dataPath, storage)[0].warning), 'cleaning everything carries a warning');
+        const badTargets = ['', '..', '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 = badTargets.filter((target) => {
+            try {
+                resolveCleanTargets([target], dataPath, storage);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        t.equal(accepted, [], 'rejected: .., absolute paths, drive letters, UNC, wildcards, streams, too deep, unknown areas');
+        await t.throws(() => resolveCleanTargets([], dataPath, storage), '', 'rejected: no target at all (that is not "everything")');
+        t.section('sizes and removal never follow links');
+        const sized = t.at('sized');
+        t.write(path.join(sized, 'a.bin'), 'x'.repeat(1000));
+        t.write(path.join(sized, 'sub', 'b.bin'), 'y'.repeat(24));
+        const outside = t.at('outside');
+        t.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 */ }
+        t.equal(sizeOf(sized), 1024, 'sizes count real files only' + (linked ? ' (a junction counts 0)' : ''));
+        t.equal([humanBytes(1536), humanBytes(0), humanBytes(3 * 1024 ** 3)], ['1.5 KB', '0 B', '3.0 GB'], 'sizes are shown in readable units');
+        if (linked)
+            t.equal(findLinks(sized).length, 1, 'repair finds a junction planted in the data folder');
+        removeTree(sized, t.temp);
+        t.check(!fs.existsSync(sized), 'a folder is removed');
+        t.check(fs.existsSync(path.join(outside, 'keep.txt')), 'removing a folder never deletes what a link inside points to');
+        t.section('storage cleanup');
+        const store = t.at('prune');
+        const aged = (p, days) => { const d = new Date(Date.now() - days * 86400000); fs.utimesSync(p, d, d); };
+        for (const [name, days] of [['old', 9], ['kept', 30], ['new', 1]]) {
+            aged(t.write(path.join(store, 'launches', name, 'agent.wsb'), 'x'), days);
+            aged(path.join(store, 'launches', name), days);
+        }
+        aged(t.write(path.join(store, 'data', 'd', 'logs', 'guest-old.log'), 'x'), 20);
+        t.write(path.join(store, 'data', 'd', 'logs', 'guest-new.log'), 'x');
+        const staging = t.dir('prune', 'data', 'd', 'tools', 'git.staging-ab12');
+        aged(staging, 2);
+        t.dir('prune', 'data', 'd', 'tools', 'node');
+        const pruned = pruneStorage(store, { keep: ['kept'] });
+        const left = (p) => fs.existsSync(path.join(store, p));
+        t.equal(pruned.launches, 1, 'cleanup removes one launch folder');
+        t.equal({ old: left('launches/old'), kept: left('launches/kept'), new: left('launches/new') }, { old: false, kept: true, new: true }, 'cleanup: launch folders older than 7 days go; the running launch and recent ones stay');
+        t.equal({ oldLog: left('data/d/logs/guest-old.log'), newLog: left('data/d/logs/guest-new.log') }, { oldLog: false, newLog: true }, 'cleanup: logs older than 14 days go');
+        t.equal({ interrupted: left('data/d/tools/git.staging-ab12'), realTool: left('data/d/tools/node') }, { interrupted: false, realTool: true }, 'cleanup: interrupted downloads go; real tools stay');
+    },
 };

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

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

package/dist/selftest/detect.test.js

@@ -1,42 +1,58 @@
-// "Which databases does this project need?": detection from real-world file shapes, and the plan the host builds.
+// "What does this project need?": databases and toolchains detected from project files, and the plans built from them.
 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 { databaseCatalog, planDatabases } from '../host/database-plan.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');
+const found = (files, host = []) => detectDatabases(files, host).map((d) => d.database);
+const file = (path, text) => ({ path, text });
+export const detectSuite = {
+    name: 'detect',
+    title: 'database and toolchain detection from project files',
+    run: (t) => {
+        t.section('databases from project files');
+        const compose = file('docker-compose.yml', 'services:\n  db:\n    image: postgres:16-alpine\n  cache:\n    image: "redis:7"\n  dynamo:\n    image: amazon/dynamodb-local:latest\n');
+        t.equal(found([compose]), ['postgres', 'redis', 'dynamodb'], 'compose services: postgres, redis and DynamoDB Local images');
+        t.equal(found([file('package.json', '{"dependencies":{"pg":"^8.11.0","ioredis":"5","@aws-sdk/client-dynamodb":"3"}}')]), ['postgres', 'redis', 'dynamodb'], 'package.json: pg, ioredis, @aws-sdk/client-dynamodb');
+        t.equal(found([file('package.json', '{"dependencies":{"pgadmin-ui":"1","mysql-logger":"2","express":"4"}}')]), [], 'package.json: names that only contain a driver name do not count');
+        t.equal(found([file('prisma/schema.prisma', 'datasource db {\n  provider = "mysql"\n  url = env("DATABASE_URL")\n}')]), ['mysql'], 'Prisma: the datasource provider decides');
+        t.equal(found([file('requirements.txt', 'django==5.0\npsycopg2-binary==2.9\npymongo>=4\n')]), ['postgres', 'mongodb'], 'Python requirements: psycopg2 and pymongo');
+        t.equal(found([file('Api/Api.csproj', '<PackageReference Include="Microsoft.EntityFrameworkCore.SqlServer" Version="8.0.0" />')]), ['sqlserver'], '.NET: EF Core SQL Server provider');
+        t.equal(found([file('.env.example', 'DATABASE_URL=postgresql://user:pass@localhost:5432/app\nMONGO_URL=mongodb+srv://cluster/x\n')]), ['postgres', 'mongodb'], '.env templates: connection-string schemes');
+        t.equal(found([file('template.yaml', 'Resources:\n  Table:\n    Type: AWS::DynamoDB::Table\n')]), ['dynamodb'], 'SAM/CloudFormation: a DynamoDB table resource');
+        t.equal(found([file('go.mod', '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');
+        const knex = [file('package.json', '{"dependencies":{"knex":"3"}}')];
+        t.equal(found(knex), [], 'an ORM that names no database uses nothing when this PC has none');
+        t.equal(found(knex, ['mysql']), ['mysql'], 'an ORM that names no database uses the one installed on this PC');
+        t.equal(databasesFromServices(['postgresql-x64-16', 'MySQL80', 'MSSQL$SQLEXPRESS', 'Spooler', 'Redis']), ['postgres', 'mysql', 'sqlserver', 'redis'], 'database services on this PC are recognised by name');
+        // Hostile workspace files (a cloned repository is untrusted): detection must stay linear.
+        const hostile = [
+            file('.env', 'Server=a;Database=a;'.repeat(12000)),
+            file('compose.yaml', 'services:\n  x:\n    image: ' + 'postgres'.repeat(20000) + '!\n'),
+            file('appsettings.json', 'Host=a;'.repeat(30000)),
+        ];
+        const started = Date.now();
+        detectDatabases(hostile);
+        const took = Date.now() - started;
+        t.check(took < 2000, 'database detection stays fast on hostile workspace files (no catastrophic backtracking)', 'took ' + took + ' ms');
+        t.section('the database plan');
+        const plan = planDatabases({ ...DEFAULTS.databases, mongodb: { ...DEFAULTS.databases.mongodb, enabled: true }, redis: { ...DEFAULTS.databases.redis, enabled: false } }, 'unused', { files: [compose], host: [] });
+        t.equal(plan.map((p) => p.database + '@' + p.version + ':' + p.port), ['postgres@16:5432', 'mongodb@latest:27017', 'dynamodb@latest:8000'], 'plan: "auto" from the project (compose pins Postgres 16), true always, false never');
+        t.equal(plan.find((p) => p.database === 'dynamodb')?.adminPort, 8001, 'plan: DynamoDB gets its admin UI port');
+        const catalog = databaseCatalog({ ...DEFAULTS.databases, postgres: { ...DEFAULTS.databases.postgres, enabled: false, port: 6543 } });
+        t.equal(catalog.map((p) => p.database), ['postgres', 'mysql', 'mongodb', 'redis', 'dynamodb'], 'sbx-db catalog: every database that can run (not SQL Server), even ones off at boot');
+        t.equal(catalog[0].port, 6543, 'sbx-db catalog: configured ports are used');
+        t.section('toolchains from project files');
+        const tc = DEFAULTS.toolchains;
+        const goProject = decideToolchains(tc, ['README.md', 'go.mod', 'api/main.go'], ['python', 'rust']);
+        t.equal({ go: goProject.go.on, reason: goProject.go.reason }, { go: true, reason: 'go.mod' }, 'toolchains: a Go project gets Go (and says why)');
+        t.equal({ python: goProject.python.on, rust: goProject.rust.on, dotnet: goProject.dotnet.on, java: goProject.java.on }, { python: false, rust: false, dotnet: false, java: false }, 'toolchains: a Go project gets nothing it does not use, whatever this PC has');
+        const fresh = decideToolchains(tc, ['notes.txt'], ['python', 'dotnet']);
+        t.equal({ python: fresh.python.on, dotnet: fresh.dotnet.on, go: fresh.go.on }, { python: true, dotnet: true, go: false }, 'toolchains: a folder that is no project yet gets the languages this PC has');
+        t.includes(fresh.python.reason, 'this PC', 'toolchains: the reason names this PC');
+        const rusty = decideToolchains({ ...tc, python: { ...tc.python, enabled: true } }, ['Cargo.toml'], []);
+        t.equal({ rust: rusty.rust.on, cpp: rusty.cpp.on }, { rust: true, cpp: true }, 'toolchains: Rust brings its C/C++ linker');
+        t.equal({ python: rusty.python.on, reason: rusty.python.reason }, { python: true, reason: 'enabled in config' }, 'toolchains: true in config always wins');
+        const resolved = resolveToolchains(tc, goProject);
+        t.equal({ go: resolved.go.enabled, python: resolved.python.enabled }, { go: true, python: false }, 'the sandbox gets plain decisions instead of "auto"');
+    },
 };

package/dist/selftest/fixtures.d.ts

@@ -2,6 +2,20 @@ import type { Config, HostProbe, ResolvedRun, RunRequest } from '../core/types.j
 import { generateSandbox } from '../host/generate.js';
 import type { Harness } from './harness.js';
 export declare const HOST_NODE_VERSION = "v22.3.0";
+/** Colour codes are removed from captured output, so tests can match plain text. */
+export declare const stripAnsi: (text: string) => string;
+export interface NodeRun {
+    status: number | null;
+    out: string;
+    timedOut: boolean;
+}
+export interface NodeRunOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+}
+/** Runs `node <args>` and collects stdout + stderr (colours removed). Never throws; a hung process is killed at the timeout. */
+export declare const runNode: (args: string[], options?: NodeRunOptions) => Promise<NodeRun>;
 export declare const createFixtures: (t: Harness) => {
     at: (...parts: string[]) => string;
     hostNode: string;
@@ -26,6 +40,8 @@ export declare const createFixtures: (t: Harness) => {
         sandbox: {
             memoryMb: number | "auto";
             maxMemoryMb: number;
+            maxMemoryPercent: number;
+            cpuLimit: number | "none";
             reserveHostMb: number;
             vGpu: boolean;
             networking: boolean;
@@ -56,6 +72,9 @@ export declare const createFixtures: (t: Harness) => {
                 enabled: boolean;
             };
         };
+        downloads: {
+            requireChecksum: boolean;
+        };
         toolchains: {
             node: {
                 version: string;
@@ -184,6 +203,10 @@ export declare const createFixtures: (t: Harness) => {
             auto: boolean;
             autoHide: boolean;
         };
+        agentCommands: {
+            enabled: boolean;
+            agents: string[] | "auto";
+        };
         secrets: {
             strip: boolean;
             allow: string[];
@@ -217,16 +240,33 @@ export declare const createFixtures: (t: Harness) => {
         hooks: {
             failFast: boolean;
         };
+        projects: {
+            all: boolean;
+            exclude: string[];
+            roots: string[];
+            askToAddRoot: boolean;
+            declinedRoots: string[];
+            wsbShare: boolean;
+        };
         $schema?: string | undefined;
     };
     probe: HostProbe;
     run: (over?: Partial<RunRequest>, config?: Config) => Promise<ResolvedRun>;
     generate: (r: ResolvedRun, args?: string[], p?: HostProbe) => ReturnType<typeof generateSandbox>;
+    launch: (over?: Partial<RunRequest>, options?: {
+        config?: Config;
+        args?: string[];
+        probe?: HostProbe;
+    }) => Promise<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;
+    historySides: (name: string, hostWorkspace: string, guestWorkspace: string) => {
+        hostClaudeDir: string;
+        guestClaudeDir: string;
+        hostWorkspace: string;
+        guestWorkspace: string;
     };
-    readJson: (file: string) => any;
+    runGuest: (launchPath: string, data: string, workspace: string, extra?: Record<string, string>) => Promise<NodeRun>;
+    runBin: (name: string, args: string[], options?: NodeRunOptions) => Promise<NodeRun>;
+    readJson: <T = any>(file: string) => T;
 };
 export type Fixtures = ReturnType<typeof createFixtures>;

package/dist/selftest/fixtures.js

@@ -1,16 +1,27 @@
-// 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';
+// A fake "host PC" inside the temp folder: Node, claude.exe, a ~/.claude profile, workspaces, and helpers to resolve a
+// run, generate the sandbox for it, run the guest against it and start the CLI. Shared by all suites.
 import path from 'node:path';
-import { spawnSync } from 'node:child_process';
+import { spawn } 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';
+/** Colour codes are removed from captured output, so tests can match plain text. */
+export const stripAnsi = (text) => text.replace(/\x1b\[[0-9;]*m/g, '');
+/** Runs `node <args>` and collects stdout + stderr (colours removed). Never throws; a hung process is killed at the timeout. */
+export const runNode = (args, options = {}) => new Promise((resolve) => {
+    const child = spawn(process.execPath, args, { cwd: options.cwd, env: options.env ?? process.env, windowsHide: true });
+    let out = '';
+    let timedOut = false;
+    const timer = setTimeout(() => { timedOut = true; child.kill(); }, options.timeoutMs ?? 120000);
+    child.stdout.on('data', (c) => { out += c.toString(); });
+    child.stderr.on('data', (c) => { out += c.toString(); });
+    child.on('error', (e) => { out += String(e); });
+    child.on('close', (status) => { clearTimeout(timer); resolve({ status: timedOut ? null : status, out: stripAnsi(out), timedOut }); });
+});
 export const createFixtures = (t) => {
-    const { temp, write } = t;
-    const at = (...parts) => path.join(temp, ...parts);
+    const { at, write } = t;
+    // The PC: Node with npm, Claude Code, a ~/.claude profile (with a login that must never be copied) and ~/.claude.json.
     const hostNode = at('host-node');
     write(path.join(hostNode, 'node.exe'), 'x');
     write(path.join(hostNode, 'node_modules', 'npm', 'bin', 'npm-cli.js'), '');
@@ -22,16 +33,18 @@ export const createFixtures = (t) => {
     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 hostGlobalState = t.writeJson(at('host-claude.json'), { hasCompletedOnboarding: true, mcpServers: { github: { command: 'npx' } } });
+    // The install folder, two workspaces (B has a setup script), a folder to share, the storage root, and tools "from this PC".
     const install = at('install');
-    ensureDir(path.join(install, 'sub'));
-    const workA = at('work-a');
+    t.dir('install', 'sub');
+    const workA = t.dir('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);
+    t.dir('work-b', 'assets');
+    const shared = t.dir('shared');
+    t.dir('storage');
     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');
+    /** The default config, pointed at the fake PC. `copyFromHost = false` makes the sandbox download everything instead. */
     const makeConfig = (copyFromHost = true) => {
         const c = structuredClone(DEFAULTS);
         c.storage.root = at('storage');
@@ -47,17 +60,21 @@ export const createFixtures = (t) => {
     };
     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);
+    /** Resolves a run for `workA` (or whatever `over` says). */
+    const run = (over = {}, config = baseConfig) => resolveRun({ packageRoot: install, loaded: { config, configPath: null, base: t.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 });
+    /** Resolves a run and generates its sandbox (.wsb + launch folder + session.json) in one step. */
+    const launch = async (over = {}, options = {}) => generate(await run(over, options.config ?? baseConfig), options.args, options.probe);
+    /** Writes a project's `.sandbox-config.json` (objects are serialised; strings are written as they are). */
     const writeLocal = (dir, content) => { write(path.join(dir, '.sandbox-config.json'), typeof content === 'string' ? content : JSON.stringify(content)); };
+    /** The four folders history sync works with, for a workspace on the PC and its place in the sandbox. */
+    const historySides = (name, hostWorkspace, guestWorkspace) => ({ hostClaudeDir: at(name + '-host'), guestClaudeDir: at(name + '-guest'), hostWorkspace, guestWorkspace });
     /** 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 };
+    const runGuest = async (launchPath, data, workspace, extra = {}) => runNode([path.join(launchPath, 'runtime', 'main.js')], {
+        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 },
+    });
+    /** Runs a built command (dist/bin/<name>.js) as its own process. */
+    const runBin = (name, args, options = {}) => runNode([path.join(t.packageRoot, 'dist', 'bin', name + '.js'), ...args], options);
+    const readJson = t.readJson;
+    return { at, hostNode, hostClaude, hostProfile, hostGlobalState, install, workA, workB, shared, makeConfig, baseConfig, probe, run, generate, launch, writeLocal, historySides, runGuest, runBin, readJson };
 };

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

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const generateSuite: Suite;

package/dist/selftest/generate.test.js

@@ -0,0 +1,63 @@
+// What the host generates for a sandbox: the .wsb file, the launch folder (runtime, C# sources, boot scripts),
+// session.json, the staged Claude profile, and the values read from this PC (git identity, free RAM).
+import fs from 'node:fs';
+import path from 'node:path';
+import { LocalOverrides } from '../core/schema.js';
+import { gitIdentity } from '../host/launch/stage.js';
+import { buildWsb, resolveMemoryMb } from '../host/launch/wsb.js';
+export const generateSuite = {
+    name: 'generate',
+    title: 'generated .wsb, launch folder and session.json',
+    run: async (t, f) => {
+        t.section('the .wsb file');
+        const gen = await f.launch({}, { args: ['--version'], probe: { ...f.probe, gitDir: f.shared, nvmDir: f.workB } });
+        const wsb = fs.readFileSync(gen.wsbPath, 'utf8');
+        t.includes(wsb, '<MemoryInMB>8192</MemoryInMB>', 'wsb: the configured memory');
+        t.includes(wsb, '<SandboxFolder>C:\\Workspace\\work-a</SandboxFolder>', 'wsb: the workspace is mapped to its guest folder');
+        t.includes(wsb, 'C:\\HostTools\\git', 'wsb: this PC\'s git is mapped');
+        t.includes(wsb, 'C:\\HostTools\\nvm', 'wsb: this PC\'s nvm is mapped');
+        t.excludes(wsb, 'Missing', 'wsb: an optional mapping whose folder is missing is skipped');
+        t.includes(wsb, 'logon.cmd</Command>', 'wsb: the logon command');
+        t.includes(wsb, '<vGPU>Disable</vGPU>', 'wsb: vGPU is off');
+        t.includes(buildWsb(f.baseConfig, 4096, [{ host: 'C:\\a&b', guest: 'C:\\X', readOnly: true }]), 'C:\\a&amp;b', 'wsb values are XML-escaped');
+        t.section('the launch folder');
+        const expectedFiles = ['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 = expectedFiles.filter((file) => !fs.existsSync(path.join(gen.launchPath, file)));
+        t.equal(missing, [], 'the launch folder has the runtime, the C# sources and the boot scripts');
+        t.equal(fs.readdirSync(path.join(gen.launchPath, 'runtime')).length, 5, 'the runtime is 5 self-contained files');
+        const logon = fs.readFileSync(path.join(gen.launchPath, 'sandbox', 'logon.cmd'), 'utf8');
+        t.check(logon.indexOf('trust.cmd') < logon.indexOf('wt.exe'), 'logon.cmd applies the sandbox trust settings before opening Windows Terminal');
+        t.includes(logon, 'tools\\terminal\\wt.exe', 'logon.cmd opens Windows Terminal from the tools folder');
+        t.includes(logon, '-NoExit', 'logon.cmd falls back to a PowerShell window');
+        t.section('session.json');
+        const session = f.readJson(gen.sessionPath);
+        t.equal({
+            launchId: session.launchId === gen.launchId,
+            workspace: session.workspace,
+            workspaceHost: session.workspaceHost,
+            firstArgument: session.harnessArguments[0],
+            gitFromHost: Boolean(session.hostTools.git),
+            nvmFromHost: Boolean(session.hostTools.nvm),
+            nodeSpec: session.versions.node.spec,
+            gitAccess: session.provisioning.git.access,
+        }, { launchId: true, workspace: 'C:\\Workspace\\work-a', workspaceHost: f.workA, firstArgument: '--version', gitFromHost: true, nvmFromHost: true, nodeSpec: '22.3.0', gitAccess: 'full' }, 'session.json carries the id, paths, agent arguments, host tools, versions and git access');
+        t.matches(session.hostTools.nodeVersion ?? '', /^\d+\.\d+\.\d+$/, 'session.json: the host Node version is a plain version');
+        t.equal(session.cpuLimitPercent, 80, 'session.json carries the CPU cap for cpucap.ps1 (default 80 %)');
+        t.check(!LocalOverrides.safeParse({ sandbox: { cpuLimit: 'none' } }).success, "a project's .sandbox-config.json cannot lift your CPU cap (sandbox.cpuLimit is yours only)");
+        t.section('what is copied from this PC');
+        const staged = path.join(gen.launchPath, 'claude-profile');
+        const stagedMissing = ['settings.json', 'CLAUDE.md', '.claude.json', 'plugins'].filter((name) => !fs.existsSync(path.join(staged, name)));
+        t.equal(stagedMissing, [], 'Claude settings, instructions, global state and plugins are staged');
+        t.check(!fs.existsSync(path.join(staged, '.credentials.json')), 'the Claude login is not staged');
+        const gitconfig = '[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';
+        t.equal(gitIdentity(gitconfig), '[user]\n\tname = Josh\n\temail = j@x.io\n', 'only name/email from ~/.gitconfig reach the sandbox (no credential helpers or token URLs)');
+        t.equal(gitIdentity('[core]\n\tname = x\n'), '', 'a name outside [user] is not an identity');
+        const auto = { ...f.baseConfig.sandbox, memoryMb: 'auto' };
+        const MB = 1048576;
+        const pcRam = 64 * 1024 * MB;
+        t.equal(resolveMemoryMb(auto, 40000 * MB, pcRam), 31744, "memory 'auto' follows free RAM minus the reserve");
+        await t.throws(() => resolveMemoryMb(auto, 9000 * MB, pcRam), 'Not enough free RAM', "memory 'auto' refuses when too little RAM is free");
+        t.equal(resolveMemoryMb({ ...auto, maxMemoryPercent: 80 }, 30000 * MB, 32 * 1024 * MB), 21504, "memory 'auto' never takes more than maxMemoryPercent of the PC's RAM");
+        t.equal(resolveMemoryMb({ ...auto, maxMemoryPercent: 50 }, 60000 * MB, pcRam), 32768, "memory 'auto' is capped at half the PC's RAM with maxMemoryPercent 50 (free RAM and maxMemoryMb still apply)");
+    },
+};

package/dist/selftest/git-access.test.d.ts

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const gitAccessSuite: Suite;

package/dist/selftest/git-access.test.js

@@ -0,0 +1,26 @@
+// Git access modes ("full", "readonly", "none"): which git commands the guard allows and the matching Claude deny rules.
+import { gitDecision } from '../guest/gitguard.js';
+import { gitDenyRules } from '../guest/gitrules.js';
+export const gitAccessSuite = {
+    name: 'git-access',
+    title: 'git access modes and Claude deny rules',
+    run: (t) => {
+        t.section('readonly');
+        const allowed = (args, mode = 'readonly') => gitDecision(args, mode).allow;
+        const reading = ['status', 'log --oneline', 'diff HEAD~1', 'show HEAD', 'blame a.ts', 'branch', 'branch -a', 'branch --contains HEAD', 'tag', 'tag -l v*', 'remote -v', 'config --get user.name', 'stash list', '-C sub status', '--no-pager log'];
+        t.equal(reading.filter((command) => !allowed(command.split(' '))), [], 'readonly: reading commands are allowed');
+        const writing = ['commit -m x', 'push', 'add .', 'checkout main', 'switch -c x', 'reset --hard', 'stash', 'stash pop', 'branch new', 'branch -D x', 'tag v1', 'merge x', 'rebase main', 'fetch', 'pull', 'config user.name x', 'remote add o u', '-c core.hooksPath=x status', '--git-dir=x status', 'clean -fd', 'apply p.diff'];
+        t.equal(writing.filter((command) => allowed(command.split(' '))), [], 'readonly: anything that writes (or overrides config) is refused');
+        t.section('none and full');
+        t.check(!allowed(['status'], 'none') && !allowed(['--version'], 'none'), 'none: every git call is refused');
+        t.check(allowed(['commit'], 'full'), 'full: everything is allowed');
+        t.section('Claude managed deny rules');
+        const readonlyRules = gitDenyRules('readonly');
+        const noneRules = gitDenyRules('none');
+        t.equal(gitDenyRules('full').length, 0, 'full: no deny rules');
+        t.includes(readonlyRules.join('\n'), 'Bash(git push:*)', 'readonly: pushing is denied');
+        t.check(!readonlyRules.some((r) => r.startsWith('Read(')), 'readonly: reading .git is not denied');
+        t.check(noneRules.includes('Bash(git:*)'), 'none: every git command is denied');
+        t.check(noneRules.includes('Read(**/.git/**)'), 'none: reading .git is denied too');
+    },
+};

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

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const guestBootSuite: Suite;