windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/host/personalize.js

@@ -0,0 +1,97 @@
+// Captures the look of this desktop (theme, accent colour, taskbar, Explorer options, wallpaper, mouse/keyboard,
+// regional formats) from HKCU as a .reg file the sandbox imports at logon. Only an allow-list of values is read.
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureDir, errMsg, fileExists, isWin, runPowerShell } from '../core/util.js';
+const VALUES = {
+    'Software\\Microsoft\\Windows\\CurrentVersion\\Themes\\Personalize': ['AppsUseLightTheme', 'SystemUsesLightTheme', 'EnableTransparency', 'ColorPrevalence'],
+    'Software\\Microsoft\\Windows\\DWM': ['AccentColor', 'AccentColorInactive', 'ColorizationColor', 'ColorizationAfterglow', 'ColorizationColorBalance', 'ColorPrevalence', 'EnableWindowColorization'],
+    'Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Accent': ['AccentPalette', 'AccentColorMenu', 'StartColorMenu'],
+    'Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\Advanced': ['TaskbarAl', 'TaskbarSi', 'TaskbarDa', 'TaskbarMn', 'TaskbarGlomLevel', 'ShowTaskViewButton', 'Hidden', 'HideFileExt', 'ShowSuperHidden', 'LaunchTo', 'NavPaneExpandToCurrentFolder', 'NavPaneShowAllFolders', 'ShowCopilotButton', 'Start_TrackDocs', 'Start_Layout'],
+    'Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\StuckRects3': ['Settings'],
+    'Software\\Microsoft\\Windows\\CurrentVersion\\Search': ['SearchboxTaskbarMode'],
+    'Control Panel\\Desktop': ['WallpaperStyle', 'TileWallpaper', 'MenuShowDelay', 'CursorBlinkRate', 'DragFullWindows', 'FontSmoothing', 'FontSmoothingType', 'UserPreferencesMask'],
+    'Control Panel\\Colors': ['Background', 'Hilight', 'HotTrackingColor'],
+    'Control Panel\\Mouse': ['MouseSpeed', 'MouseSensitivity', 'MouseThreshold1', 'MouseThreshold2', 'DoubleClickSpeed', 'SwapMouseButtons'],
+    'Control Panel\\Keyboard': ['KeyboardDelay', 'KeyboardSpeed'],
+    'Control Panel\\International': ['sShortDate', 'sLongDate', 'sShortTime', 'sTimeFormat', 'iFirstDayOfWeek', 'sDecimal', 'sThousand', 'sList', 'iMeasure', 'iTime', 'iTLZero'],
+    'Control Panel\\Accessibility\\StickyKeys': ['Flags'],
+};
+const toHex = (bytes) => [...bytes].map((b) => b.toString(16).padStart(2, '0')).join(',');
+const regString = (s) => '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"';
+/** Formats captured values as a .reg file (UTF-16 friendly text; written as UTF-16LE with BOM). */
+export const toRegFile = (values) => {
+    const byKey = new Map();
+    for (const v of values)
+        byKey.set(v.key, [...(byKey.get(v.key) ?? []), v]);
+    const lines = ['Windows Registry Editor Version 5.00', ''];
+    for (const [key, list] of byKey) {
+        lines.push('[HKEY_CURRENT_USER\\' + key + ']');
+        for (const v of list) {
+            const name = regString(v.name);
+            switch (v.kind) {
+                case 'DWord':
+                    lines.push(name + '=dword:' + (Number(v.value) >>> 0).toString(16).padStart(8, '0'));
+                    break;
+                case 'QWord':
+                    lines.push(name + '=hex(b):' + toHex(Buffer.from(BigInt.asUintN(64, BigInt(v.value)).toString(16).padStart(16, '0'), 'hex').reverse()));
+                    break;
+                case 'Binary':
+                    lines.push(name + '=hex:' + toHex(Buffer.from(String(v.value), 'base64')));
+                    break;
+                case 'ExpandString':
+                    lines.push(name + '=hex(2):' + toHex(Buffer.from(String(v.value) + '\0', 'utf16le')));
+                    break;
+                case 'MultiString':
+                    lines.push(name + '=hex(7):' + toHex(Buffer.from(v.value.join('\0') + '\0\0', 'utf16le')));
+                    break;
+                default: lines.push(name + '=' + regString(String(v.value)));
+            }
+        }
+        lines.push('');
+    }
+    return lines.join('\r\n');
+};
+const CAPTURE_SCRIPT = (spec) => [
+    '$ErrorActionPreference = "SilentlyContinue"',
+    '$spec = \'' + JSON.stringify(spec).replace(/'/g, "''") + '\' | ConvertFrom-Json',
+    '$out = @()',
+    'foreach ($p in $spec.PSObject.Properties) {',
+    '  $key = Get-Item -LiteralPath ("HKCU:\\" + $p.Name)',
+    '  if (-not $key) { continue }',
+    '  foreach ($name in $p.Value) {',
+    '    $raw = $key.GetValue($name, $null, "DoNotExpandEnvironmentNames")',
+    '    if ($null -eq $raw) { continue }',
+    '    $kind = $key.GetValueKind($name).ToString()',
+    '    if ($kind -eq "Binary") { $raw = [Convert]::ToBase64String([byte[]]$raw) }',
+    '    $out += [pscustomobject]@{ key = $p.Name; name = $name; kind = $kind; value = $raw }',
+    '  }',
+    '}',
+    '$wall = (Get-ItemProperty -LiteralPath "HKCU:\\Control Panel\\Desktop").WallPaper',
+    '[pscustomobject]@{ values = $out; wallpaper = $wall } | ConvertTo-Json -Depth 5 -Compress',
+].join('\n');
+/** Writes personalize.reg (+ the wallpaper image) into `<launch>\personalize`. Returns a short summary. */
+export const capturePersonalization = (launchPath) => {
+    if (!isWin)
+        return 'skipped (not Windows)';
+    try {
+        const { status, stdout } = runPowerShell(CAPTURE_SCRIPT(VALUES), true);
+        if (status !== 0)
+            return 'skipped (registry read failed)';
+        // runPowerShell has PowerShell write UTF-8 (non-ASCII date formats and wallpaper paths survive); a BOM is tolerated.
+        const parsed = JSON.parse(stdout.replace(/^/, '').trim());
+        const values = parsed.values === null ? [] : Array.isArray(parsed.values) ? parsed.values : [parsed.values];
+        const dir = path.join(launchPath, 'personalize');
+        ensureDir(dir);
+        fs.writeFileSync(path.join(dir, 'personalize.reg'), '' + toRegFile(values), 'utf16le');
+        const wallpaper = parsed.wallpaper ?? '';
+        const themesCopy = path.join(process.env.APPDATA ?? '', 'Microsoft', 'Windows', 'Themes', 'TranscodedWallpaper');
+        const source = fileExists(wallpaper) ? wallpaper : fileExists(themesCopy) ? themesCopy : null;
+        if (source)
+            fs.copyFileSync(source, path.join(dir, 'wallpaper' + (path.extname(source) || '.jpg')));
+        return values.length + ' settings' + (source ? ' + wallpaper' : '');
+    }
+    catch (e) {
+        return 'skipped (' + errMsg(e) + ')';
+    }
+};

package/dist/host/platform.d.ts

@@ -0,0 +1,17 @@
+import type { Config, HostProbe } from '../core/types.js';
+/** What can be copied from this PC instead of downloaded inside the sandbox. */
+export declare const probeHost: (config: Config, harnessName: string) => HostProbe;
+/**
+ * Running INSIDE a Windows Sandbox this tool started (its launch folder and data folder are mapped in): then the CLI
+ * talks to the sandbox it is in, through C:\\AgentData and loopback, instead of looking for one on a PC.
+ */
+export declare const insideSandbox: () => boolean;
+export declare const GUEST_DATA_DIR = "C:\\AgentData";
+export declare const isSandboxRunning: () => boolean;
+export declare const sandboxFeatureInstalled: () => boolean;
+export declare const assertCanLaunch: () => void;
+export declare const startSandbox: (wsbPath: string) => void;
+/** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
+export declare const spawnDetached: (entry: string, args: string[]) => void;
+export declare const hostClaude: (storageRoot: string, personal: boolean, args: string[]) => number;
+export declare const doctorRows: (config: Config, harnessName: string, storageRoot: string, configPath: string | null) => [string, string][];

package/dist/host/platform.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { SYSTEM } from '../shared/system.js';
+import { dirExists, ensureDir, fail, fileExists, findOnPath, homeDir, isWin, realPath } from '../core/util.js';
+const findHarnessExe = (config, harnessName) => {
+    const harness = config.harnesses[harnessName];
+    if (!harness?.hostExecutable)
+        return null;
+    const explicit = harness.hostDir && harness.hostDir !== 'auto' ? path.join(harness.hostDir, harness.hostExecutable) : null;
+    const found = explicit
+        ? (fileExists(explicit) ? explicit : null)
+        : findOnPath([harness.hostExecutable]) ?? [path.join(homeDir(), '.local', 'bin', harness.hostExecutable)].find(fileExists) ?? null;
+    if (!found)
+        return null;
+    const real = realPath(found);
+    return { dir: path.dirname(real), file: path.basename(real) };
+};
+/** Git for Windows root (the folder with cmd\git.exe and bin\bash.exe), from git on PATH. */
+const findGitRoot = () => {
+    const git = findOnPath(['git.exe']);
+    if (!git)
+        return null;
+    const root = path.resolve(path.dirname(realPath(git)), '..');
+    return fileExists(path.join(root, 'bin', 'bash.exe')) ? root : null;
+};
+/** What can be copied from this PC instead of downloaded inside the sandbox. */
+export const probeHost = (config, harnessName) => {
+    const nodeDir = isWin ? path.dirname(process.execPath) : null;
+    const copy = config.provisioning.copyFromHost;
+    const nvmHome = process.env.NVM_HOME;
+    const nvmDir = copy && nvmHome && dirExists(nvmHome) ? realPath(nvmHome) : null;
+    const hasNode = (dir) => fileExists(path.join(dir, 'node.exe')) && fileExists(path.join(dir, 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+    // One source for Node: nvm's copy of this version when there is one, otherwise the Node folder itself.
+    const nvmNode = Boolean(nvmDir && hasNode(path.join(nvmDir, process.version)));
+    return {
+        nodeDir: copy && !nvmNode && nodeDir && hasNode(nodeDir) ? realPath(nodeDir) : null,
+        harnessExe: copy ? findHarnessExe(config, harnessName) : null,
+        gitDir: copy && config.provisioning.git.enabled ? findGitRoot() : null,
+        nvmDir,
+        hostNodeVersion: process.version,
+        nvmNode,
+        volta: Boolean(process.env.VOLTA_HOME),
+        pyenv: Boolean(process.env.PYENV ?? process.env.PYENV_ROOT ?? process.env.PYENV_HOME),
+    };
+};
+const SANDBOX_PROCESSES = ['WindowsSandboxClient.exe', 'WindowsSandboxRemoteSession.exe', 'WindowsSandbox.exe'];
+/**
+ * Running INSIDE a Windows Sandbox this tool started (its launch folder and data folder are mapped in): then the CLI
+ * talks to the sandbox it is in, through C:\\AgentData and loopback, instead of looking for one on a PC.
+ */
+export const insideSandbox = () => isWin && !process.env.AGENT_SANDBOX_HOST_ONLY && fs.existsSync('C:\\AgentLaunch\\session.json') && fs.existsSync('C:\\AgentData\\run');
+export const GUEST_DATA_DIR = 'C:\\AgentData';
+export const isSandboxRunning = () => {
+    if (!isWin)
+        return false;
+    if (insideSandbox())
+        return true;
+    const result = spawnSync(SYSTEM.tasklist(), ['/NH', '/FO', 'CSV'], { encoding: 'utf8', windowsHide: true });
+    const out = (result.stdout ?? '').toLowerCase();
+    return SANDBOX_PROCESSES.some((image) => out.includes('"' + image.toLowerCase() + '"'));
+};
+export const sandboxFeatureInstalled = () => isWin && fileExists(path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'WindowsSandbox.exe'));
+export const assertCanLaunch = () => {
+    if (!isWin)
+        fail('Windows Sandbox only runs on Windows.', 'Use sandbox generate to only write the files.');
+    if (!sandboxFeatureInstalled())
+        fail('Windows Sandbox is not enabled on this PC.', 'Run in an admin PowerShell, then reboot: Enable-WindowsOptionalFeature -Online -FeatureName Containers-DisposableClientVM -All  (needs Windows Pro, Enterprise or Education)');
+    if (isSandboxRunning())
+        fail('A Windows Sandbox is already running (Windows allows one at a time).', 'Attach to it with sandbox claude -t, show it with sbx-show, or shut it down with sandbox stop.');
+};
+export const startSandbox = (wsbPath) => {
+    const result = spawnSync(SYSTEM.cmd(), ['/d', '/c', 'start', '""', '"' + wsbPath + '"'], { stdio: 'inherit', windowsVerbatimArguments: true });
+    if (result.error)
+        throw result.error;
+};
+/** Runs a detached copy of this CLI (used for the background history/claude-mem sync watcher). */
+export const spawnDetached = (entry, args) => {
+    // cwd = the install folder: the caller's folder is the workspace, which the sandbox can write.
+    spawn(process.execPath, [entry, ...args], { cwd: path.dirname(entry), detached: true, stdio: 'ignore', windowsHide: true }).unref();
+};
+export const hostClaude = (storageRoot, personal, args) => {
+    const exe = findOnPath(['claude.exe', 'claude.cmd']);
+    if (!exe)
+        fail('Claude Code is not installed on this PC (no claude.exe or claude.cmd on PATH).', 'Install it: npm install -g @anthropic-ai/claude-code');
+    const env = { ...process.env };
+    if (!personal) {
+        const profile = path.join(storageRoot, 'host', 'claude');
+        ensureDir(profile);
+        env.CLAUDE_CONFIG_DIR = profile;
+        console.warn('Host Claude is NOT sandboxed. Using separate profile: ' + profile + ' (pass --personal to use your normal one).');
+    }
+    const result = exe.toLowerCase().endsWith('.cmd') ? spawnSync(SYSTEM.cmd(), ['/d', '/c', exe, ...args], { stdio: 'inherit', env }) : spawnSync(exe, args, { stdio: 'inherit', env });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+};
+export const doctorRows = (config, harnessName, storageRoot, configPath) => {
+    const probe = probeHost(config, harnessName);
+    return [
+        ['Config file', configPath ?? '(none; built-in defaults; create one with: sandbox config init)'],
+        ['Windows', isWin ? 'yes' : 'NO (launch needs Windows)'],
+        ['Windows Sandbox feature', sandboxFeatureInstalled() ? 'enabled' : 'NOT enabled'],
+        ['Sandbox running', isSandboxRunning() ? 'YES' : 'no'],
+        ['Free host RAM (MB)', String(Math.floor(os.freemem() / 1048576))],
+        ['Provisioning', config.provisioning.copyFromHost ? 'copy from this PC' + (config.provisioning.fallbackToInstall ? ', fall back to download' : ', no fallback') : 'download inside sandbox'],
+        ['Host Node (runner)', probe.nvmNode ? 'nvm ' + probe.hostNodeVersion : probe.nodeDir ?? '(none; will download)'],
+        ['Host nvm versions', probe.nvmDir ?? '(no NVM_HOME; versions will be downloaded)'],
+        ['Host ' + harnessName, probe.harnessExe ? path.join(probe.harnessExe.dir, probe.harnessExe.file) : '(none; will npm install)'],
+        ['Host Git for Windows', probe.gitDir ?? '(none with bash; PortableGit will be downloaded)'],
+        ['Storage root', storageRoot + (dirExists(storageRoot) ? '' : ' (will be created)')],
+    ];
+};

package/dist/host/project-scan.d.ts

@@ -0,0 +1,23 @@
+import type { Config, DatabasePlan } from '../core/types.js';
+import { type Database, type ProjectFile } from '../core/detect-databases.js';
+import { type AutoToolchain } from '../core/detect-toolchains.js';
+/** Manifest-type files in the project, up to 3 folders deep. Links are not followed (the workspace may be guest-written). */
+export declare const readProjectFiles: (root: string, depth?: number) => ProjectFile[];
+/** File names in the project and its direct sub-folders ("api/go.mod"), for toolchain detection. No links followed. */
+export declare const projectEntries: (root: string) => string[];
+/** Scripts in the project root or one folder down that set up MSVC (vcvars*.bat, vswhere): read with bounded effort. */
+export declare const msvcHint: (root: string) => string | undefined;
+/** Languages this PC has (their commands on PATH; Windows' Store stubs for python do not count). */
+export declare const pcLanguages: () => AutoToolchain[];
+/** Database services installed on this PC (names from the service control manager; nothing is started or changed). */
+export declare const hostDatabases: () => Database[];
+/**
+ * What to run in this sandbox: databases set to true, plus "auto" ones the project needs. SQL Server is reported (so
+ * the user hears about it) but cannot run inside Windows Sandbox.
+ */
+export declare const planDatabases: (config: Config["databases"], workspace: string, probe?: {
+    files?: ProjectFile[];
+    host?: Database[];
+}) => DatabasePlan[];
+/** Every database the sandbox can run, so `sbx-db start <name>` works for ones that did not start at boot. */
+export declare const databaseCatalog: (config: Config["databases"]) => DatabasePlan[];

package/dist/host/project-scan.js

@@ -0,0 +1,173 @@
+// Reads a project the way detect-databases.ts needs it (only manifest/config/compose files, bounded), and looks at which
+// database services this PC has, so `enabled: "auto"` databases are installed only for projects that use them.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { DATABASES, databasesFromServices, detectDatabases, INTERESTING_FILE } from '../core/detect-databases.js';
+import os from 'node:os';
+import { AUTO_TOOLCHAINS } from '../core/detect-toolchains.js';
+import { pcHasPwsh } from '../core/detect-pwsh.js';
+import { isWin } from '../core/util.js';
+import { system32 } from '../shared/system.js';
+const SKIP = /^(node_modules|\.git|\.hg|\.svn|vendor|target|bin|obj|dist|build|out|\.next|\.nuxt|\.venv|venv|env|__pycache__|\.gradle|\.idea|\.vs|coverage|packages)$/i;
+const MAX_FILES = 400;
+const MAX_BYTES = 256 * 1024;
+const MAX_FOLDERS = 2000;
+/** Reads a file through one handle, only if that handle is a regular file of at most MAX_BYTES. */
+const readSmallFile = (file) => {
+    let fd = null;
+    try {
+        fd = fs.openSync(file, 'r');
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile() || stat.size > MAX_BYTES)
+            return null;
+        const buffer = Buffer.alloc(stat.size);
+        fs.readSync(fd, buffer, 0, stat.size, 0);
+        return buffer.toString('utf8');
+    }
+    catch {
+        return null;
+    }
+    finally {
+        if (fd !== null)
+            fs.closeSync(fd);
+    }
+};
+/** Manifest-type files in the project, up to 3 folders deep. Links are not followed (the workspace may be guest-written). */
+export const readProjectFiles = (root, depth = 3) => {
+    const files = [];
+    let folders = 0;
+    const walk = (dir, level) => {
+        if (++folders > MAX_FOLDERS)
+            return;
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (files.length >= MAX_FILES)
+                return;
+            const full = path.join(dir, entry.name);
+            if (entry.isFile() && INTERESTING_FILE.test(entry.name)) {
+                const text = readSmallFile(full);
+                if (text !== null)
+                    files.push({ path: path.relative(root, full), text });
+            }
+            else if (entry.isDirectory() && level < depth && !SKIP.test(entry.name))
+                walk(full, level + 1);
+        }
+    };
+    walk(root, 0);
+    return files;
+};
+/** File names in the project and its direct sub-folders ("api/go.mod"), for toolchain detection. No links followed. */
+export const projectEntries = (root) => {
+    const list = (dir) => { try {
+        return fs.readdirSync(dir, { withFileTypes: true }).slice(0, 2000);
+    }
+    catch {
+        return [];
+    } };
+    const top = list(root);
+    const below = top.filter((d) => d.isDirectory() && !d.name.startsWith('.') && !SKIP.test(d.name)).slice(0, 200)
+        .flatMap((d) => list(path.join(root, d.name)).filter((f) => f.isFile()).map((f) => d.name + '/' + f.name));
+    return [...top.filter((d) => d.isFile()).map((d) => d.name), ...below];
+};
+/** This PC builds Rust with MSVC: rustup's default host is *-msvc (read from rustup's settings; nothing is run). */
+const msvcRust = () => {
+    const settings = path.join(process.env.RUSTUP_HOME ?? path.join(os.homedir(), '.rustup'), 'settings.toml');
+    try {
+        return /default_host_triple\s*=\s*"[^"]*-msvc"/.test(fs.readFileSync(settings, 'utf8').slice(0, 64 * 1024));
+    }
+    catch {
+        return false;
+    }
+};
+/** Scripts in the project root or one folder down that set up MSVC (vcvars*.bat, vswhere): read with bounded effort. */
+export const msvcHint = (root) => {
+    const scripts = projectEntries(root).filter((e) => /\.(ps1|cmd|bat|psm1)$/i.test(e)).slice(0, 60);
+    for (const rel of scripts) {
+        let text = '';
+        try {
+            const file = path.join(root, rel);
+            if (fs.statSync(file).size <= 256 * 1024)
+                text = fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        if (/vcvars(all|64|32)?\.bat|vswhere(\.exe)?/i.test(text))
+            return rel + ' sets up MSVC';
+    }
+    return undefined;
+};
+/** Languages this PC has (their commands on PATH; Windows' Store stubs for python do not count). */
+export const pcLanguages = () => {
+    const dirs = (process.env.PATH ?? '').split(path.delimiter).filter((d) => d && !/WindowsApps/i.test(d));
+    const has = (...names) => dirs.some((d) => names.some((n) => fs.existsSync(path.join(d, n))));
+    const found = {
+        python: has('python.exe', 'py.exe'), rust: has('cargo.exe', 'rustc.exe'), cpp: has('gcc.exe', 'g++.exe', 'cl.exe', 'clang.exe'),
+        msvc: msvcRust(), pwsh: pcHasPwsh(), dotnet: has('dotnet.exe'), go: has('go.exe'), java: has('java.exe', 'javac.exe'), ruby: has('ruby.exe'), php: has('php.exe'), deno: has('deno.exe'),
+    };
+    return AUTO_TOOLCHAINS.filter((t) => found[t]);
+};
+/** Database services installed on this PC (names from the service control manager; nothing is started or changed). */
+export const hostDatabases = () => {
+    if (!isWin)
+        return [];
+    const result = spawnSync(system32('sc.exe'), ['query', 'type=', 'service', 'state=', 'all'], { encoding: 'utf8', windowsHide: true, timeout: 10000 });
+    const names = [...(result.stdout ?? '').matchAll(/^SERVICE_NAME:\s*(.+)$/gm)].map((m) => m[1].trim());
+    return databasesFromServices(names);
+};
+/** The version a compose file pins (postgres:16-alpine -> 16, mongo:7.0 -> 7.0), if any. */
+const pinnedVersion = (files, image) => {
+    for (const file of files) {
+        const match = image.exec(file.text);
+        if (match?.[1] && /^\d+(\.\d+)?/.test(match[1]))
+            return /^\d+(\.\d+)?/.exec(match[1])[0];
+    }
+    return null;
+};
+/**
+ * What to run in this sandbox: databases set to true, plus "auto" ones the project needs. SQL Server is reported (so
+ * the user hears about it) but cannot run inside Windows Sandbox.
+ */
+export const planDatabases = (config, workspace, probe = {}) => {
+    const autos = DATABASES.filter((db) => config[db].enabled === 'auto');
+    const files = autos.length ? probe.files ?? readProjectFiles(workspace) : [];
+    const detected = autos.length ? detectDatabases(files, probe.host ?? hostDatabases) : [];
+    const plan = databasePlanner(config, files.filter((f) => /compose/i.test(f.path)));
+    return DATABASES.flatMap((database) => {
+        const setting = config[database].enabled;
+        const found = detected.find((d) => d.database === database);
+        if (setting === true)
+            return [plan(database, ['enabled in config'])];
+        if (setting === 'auto' && found)
+            return [plan(database, found.reasons)];
+        return [];
+    });
+};
+/** Every database the sandbox can run, so `sbx-db start <name>` works for ones that did not start at boot. */
+export const databaseCatalog = (config) => {
+    const plan = databasePlanner(config, []);
+    return DATABASES.filter((db) => db !== 'sqlserver').map((db) => plan(db, ['started with sbx-db']));
+};
+/** Version (a compose file's image tag wins), port and admin UI for one database. */
+const databasePlanner = (config, compose) => {
+    const versions = {
+        postgres: pinnedVersion(compose, /image:\s*["']?(?:[\w.-]+\/)*postgres:([\w.-]+)/i) ?? (config.postgres.version === 'latest' ? 'latest' : config.postgres.version),
+        mysql: config.mysql.version,
+        mongodb: pinnedVersion(compose, /image:\s*["']?(?:[\w.-]+\/)*mongo:([\w.-]+)/i) ?? config.mongodb.version,
+        redis: 'latest',
+        dynamodb: 'latest',
+        sqlserver: '',
+    };
+    const ports = { postgres: config.postgres.port, mysql: config.mysql.port, mongodb: config.mongodb.port, redis: config.redis.port, dynamodb: config.dynamodb.port, sqlserver: 1433 };
+    return (database, reasons) => ({
+        database, reasons, version: versions[database], port: ports[database],
+        ...(database === 'dynamodb' && config.dynamodb.admin ? { adminPort: config.dynamodb.adminPort } : {}),
+    });
+};

package/dist/host/repo-guard.d.ts

@@ -0,0 +1,23 @@
+export interface RepoSnapshot {
+    gitDir: boolean;
+    config: string[];
+    hooks: Record<string, string>;
+    redirects: string[];
+    commands: Record<string, string>;
+}
+export interface RepoFinding {
+    kind: 'hook' | 'config' | 'git' | 'command';
+    detail: string;
+}
+export declare const snapshotRepo: (workspace: string) => RepoSnapshot;
+/**
+ * Compares the workspace with its pre-launch snapshot and neutralises anything new that would execute on this PC.
+ * Returns what was found (and fixed). Never touches what was already there before the sandbox ran.
+ */
+export declare const guardRepo: (workspace: string, before: RepoSnapshot) => RepoFinding[];
+export declare const saveRepoSnapshot: (dataPath: string, workspace: string) => void;
+/** Re-checks the workspace of the current/last launch; findings are kept in a host-only file for `status`. */
+export declare const checkRepo: (dataPath: string) => RepoFinding[];
+export declare const repoFindings: (dataPath: string) => (RepoFinding & {
+    at?: string;
+})[];

package/dist/host/repo-guard.js

@@ -0,0 +1,128 @@
+// Zero-click protection for the folder the sandbox shares with this PC.
+//
+// The agent can write the workspace. Two kinds of change there would run code on THIS PC without you doing anything
+// unusual, so they are snapshotted before launch, re-checked every minute while the sandbox runs and when it closes,
+// and neutralised:
+//  - git: new or changed hooks, and config that makes git run programs (core.fsmonitor, core.sshCommand, filters,
+//    include.path, ...), plus files that redirect where git reads config and hooks (commondir, config.worktree);
+//  - commands: executables dropped in the project root under the name of something you type there (node.exe,
+//    git.cmd, npm.cmd, ...), because Windows runs a program from the current folder before searching PATH.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+import { dirExists, fileExists, isLink, tryReadJson, writeJson } from '../core/util.js';
+/** Config keys that make git run a program, or load more config. */
+const DANGEROUS_KEY = /^(fsmonitor|hookspath|sshcommand|pager|editor|askpass|program|gpgprogram|textconv|command|cmd|clean|smudge|process|driver|helper|uploadpack|receivepack|path|attributesfile|excludesfile|worktree|worktreeconfig|gitproxy|proxycommand|sendemailvalidate|tool)\s*=/i;
+const SECTION = /^\s*\[([^\]]*)\]\s*/;
+const MARK = '# [agent-sandbox] disabled, added inside the sandbox: ';
+/** Files in .git that make git read config/hooks from somewhere else. */
+const REDIRECTS = ['commondir', 'config.worktree'];
+/** Names you are likely to run in a project folder; with any of these extensions Windows would pick the local copy. */
+const COMMANDS = new RegExp('^(' + [
+    // this tool's own commands (package.json "bin")
+    'sandbox', 'windows-development-sandbox', 'agent-sandbox', 'claude-sbx', 'claude-sandbox', 'codex-sbx', 'codex-sandbox', 'gemini-sbx', 'gemini-sandbox', 'claude-host', 'sbx-show', 'sbx-hide',
+    // agents
+    'claude', 'codex', 'gemini', 'opencode', 'qwen', 'crush', 'copilot', 'kilo', 'kilocode', 'amp', 'cline', 'cn', 'kimi', 'reasonix', 'codewhale', 'aider', 'cursor-agent', 'agent', 'goose',
+    // toolchains and everyday tools
+    'node', 'npm', 'npx', 'pnpm', 'pnpx', 'yarn', 'corepack', 'volta', 'nvm', 'deno', 'bun', 'bunx', 'tsc', 'git', 'gh', 'code', 'python', 'python3', 'py', 'pip', 'pip3', 'uv', 'uvx', 'pyenv', 'poetry',
+    'cargo', 'rustc', 'rustup', 'dotnet', 'nuget', 'msbuild', 'go', 'java', 'javac', 'mvn', 'mvnw', 'gradle', 'gradlew', 'ruby', 'gem', 'bundle', 'rake', 'rails', 'php', 'composer',
+    'make', 'cmake', 'ninja', 'gcc', 'g\\+\\+', 'clang', 'psql', 'mysql', 'mariadb', 'mongosh', 'redis-cli', 'docker', 'kubectl', 'terraform', 'az', 'aws',
+    'powershell', 'pwsh', 'cmd', 'where', 'tasklist', 'tar', 'curl', 'ssh', 'scp',
+].join('|') + ')\\.(exe|com|bat|cmd|vbs|vbe|js|jse|wsf|wsh|msc|ps1)$', 'i');
+const hash = (file) => (isLink(file) ? 'link' : crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex'));
+const plainGitDir = (workspace) => {
+    const dir = path.join(workspace, '.git');
+    return dirExists(dir) && !isLink(dir) ? dir : null;
+};
+const filesIn = (dir, accept) => dirExists(dir) && !isLink(dir)
+    ? Object.fromEntries(fs.readdirSync(dir, { withFileTypes: true }).filter((e) => (e.isFile() || e.isSymbolicLink()) && accept(e.name)).map((e) => [e.name, hash(path.join(dir, e.name))]))
+    : {};
+const configLines = (dir) => {
+    const file = path.join(dir, 'config');
+    return fileExists(file) && !isLink(file) ? fs.readFileSync(file, 'utf8').split(/\r?\n/) : [];
+};
+export const snapshotRepo = (workspace) => {
+    const dir = plainGitDir(workspace);
+    return {
+        gitDir: dir !== null,
+        config: dir ? configLines(dir) : [],
+        hooks: dir ? filesIn(path.join(dir, 'hooks'), (n) => !n.endsWith('.sample')) : {},
+        redirects: dir ? REDIRECTS.filter((n) => fs.existsSync(path.join(dir, n))) : [],
+        commands: filesIn(workspace, (n) => COMMANDS.test(n)),
+    };
+};
+/** Moves files into <dir>\agent-sandbox-quarantine\<time>\ and reports them. */
+const quarantine = (from, names, into, kind) => {
+    if (names.length === 0)
+        return [];
+    const target = path.join(into, 'agent-sandbox-quarantine', String(Date.now()));
+    fs.mkdirSync(target, { recursive: true });
+    return names.map((name) => {
+        fs.renameSync(path.join(from, name), path.join(target, name));
+        return { kind, detail: name + ' (moved to ' + target + ')' };
+    });
+};
+/** Comments out newly added config lines that make git run programs. Existing lines are never touched. */
+const disableConfig = (dir, before) => {
+    const lines = configLines(dir);
+    const known = _.countBy(before);
+    const seen = {};
+    const findings = [];
+    let inInclude = false;
+    const fixed = lines.map((line) => {
+        const header = SECTION.exec(line);
+        if (header)
+            inInclude = /^include(if\s+"[^"]*")?$/i.test(header[1].trim());
+        seen[line] = (seen[line] ?? 0) + 1;
+        if (line.startsWith(MARK) || seen[line] <= (known[line] ?? 0))
+            return line;
+        // git also accepts "[core] fsmonitor = x" on one line, so look past a leading section header.
+        const keyPart = line.replace(SECTION, '').trim();
+        if (!(DANGEROUS_KEY.test(keyPart) || (inInclude && keyPart.includes('='))))
+            return line;
+        findings.push({ kind: 'config', detail: line.trim() });
+        return MARK + line.trim();
+    });
+    if (findings.length)
+        fs.writeFileSync(path.join(dir, 'config'), fixed.join('\n'), 'utf8');
+    return findings;
+};
+/**
+ * Compares the workspace with its pre-launch snapshot and neutralises anything new that would execute on this PC.
+ * Returns what was found (and fixed). Never touches what was already there before the sandbox ran.
+ */
+export const guardRepo = (workspace, before) => {
+    const findings = [];
+    const commandsNow = filesIn(workspace, (n) => COMMANDS.test(n));
+    findings.push(...quarantine(workspace, Object.keys(commandsNow).filter((n) => before.commands[n] !== commandsNow[n]), workspace, 'command'));
+    const dir = plainGitDir(workspace);
+    if (!dir) {
+        const replaced = before.gitDir && fs.existsSync(path.join(workspace, '.git'));
+        if (replaced)
+            findings.push({ kind: 'git', detail: '.git was replaced by a link or a "gitdir:" file inside the sandbox. Do not run git in ' + workspace + ' until you have checked it.' });
+        return findings;
+    }
+    const hooksDir = path.join(dir, 'hooks');
+    const hooksNow = filesIn(hooksDir, (n) => !n.endsWith('.sample'));
+    findings.push(...quarantine(hooksDir, Object.keys(hooksNow).filter((n) => before.hooks[n] !== hooksNow[n]), dir, 'hook'));
+    findings.push(...quarantine(dir, REDIRECTS.filter((n) => fs.existsSync(path.join(dir, n)) && !before.redirects.includes(n)), dir, 'git'));
+    findings.push(...disableConfig(dir, before.config));
+    return findings;
+};
+// ---- snapshot storage (host-only, next to the sync state) ---------------------------------------------------------
+const syncDir = (dataPath) => path.join(path.dirname(path.dirname(dataPath)), 'sync');
+const snapshotFile = (dataPath) => path.join(syncDir(dataPath), path.basename(dataPath) + '-repo.json');
+const findingsFile = (dataPath) => path.join(syncDir(dataPath), path.basename(dataPath) + '-repo-findings.json');
+export const saveRepoSnapshot = (dataPath, workspace) => writeJson(snapshotFile(dataPath), { workspace, snapshot: snapshotRepo(workspace) });
+/** Re-checks the workspace of the current/last launch; findings are kept in a host-only file for `status`. */
+export const checkRepo = (dataPath) => {
+    const saved = tryReadJson(snapshotFile(dataPath));
+    if (!saved?.snapshot?.commands)
+        return [];
+    const findings = guardRepo(saved.workspace, saved.snapshot);
+    if (findings.length)
+        writeJson(findingsFile(dataPath), [...repoFindings(dataPath), ...findings.map((f) => ({ ...f, at: new Date().toISOString() }))]);
+    return findings;
+};
+export const repoFindings = (dataPath) => tryReadJson(findingsFile(dataPath)) ?? [];

package/dist/host/secrets.d.ts

@@ -0,0 +1,14 @@
+import type { Config } from '../core/types.js';
+export type SecretsConfig = Config['secrets'];
+export declare const isSecretName: (name: string, secrets: SecretsConfig) => boolean;
+export declare const isSecretValue: (value: string) => boolean;
+/** Whether a variable (name and value) may go into the sandbox. secrets.allow always wins. */
+export declare const mayPass: (name: string, value: unknown, secrets: SecretsConfig) => boolean;
+/** A copy of an env/headers map without the secrets; the names removed are added to `removed` (with `where`). */
+export declare const stripVariables: (vars: unknown, secrets: SecretsConfig, where: string, removed: string[]) => unknown;
+/** settings.json for the sandbox: secrets out of "env", credential helper commands removed. */
+export declare const stripSettings: (settings: Record<string, unknown>, secrets: SecretsConfig, removed: string[]) => Record<string, unknown>;
+/** Every MCP server in a .claude.json-shaped object (top level and per project). */
+export declare const stripMcpServers: (state: Record<string, unknown>, secrets: SecretsConfig, removed: string[]) => Record<string, unknown>;
+/** Secret-looking files in the workspace root and one folder down (skipping dependency folders). */
+export declare const findSecretFiles: (workspace: string) => string[];