windows-development-sandbox 1.0.5 → 1.1.0

package/dist/core/schema.js

@@ -1,264 +1,8 @@
-// Every setting, defined once with zod: the user config (~/.agent-sandbox/config.json) and the much smaller subset a
-// project's .sandbox-config.json may change. Types are inferred from these schemas, and the JSON Schema files in
-// schemas/ (editor autocomplete and docs via "$schema") are generated from them at build time.
-import _ from 'lodash';
-import { z } from 'zod';
-import { isValidGuestPath } from '../shared/guest-paths.js';
-// Rules (and RESERVED_GUEST) live in shared/guest-paths.ts: the host re-checks them before writing the .wsb.
-export const GuestPath = z.string().refine(isValidGuestPath, 'reserved or invalid guest path (a folder under C:\\ other than Windows, Program Files, Users, AgentData, Mirror, ..., or on drive D: to Z:)');
-const Name = z.string().regex(/^[A-Za-z0-9_-]+$/, 'letters, numbers, - and _ only');
-const Strings = z.array(z.string());
-const toggle = (description) => z.strictObject({ enabled: z.boolean().describe(description) });
-const SchemaRef = z.string().describe('Path or URL of the JSON Schema for editor autocomplete and docs.');
-export const GitAccess = z.enum(['full', 'readonly', 'none'])
-    .describe('full: normal git. readonly: status/log/diff/show/blame only (no commit, push, checkout, ...). none: no git at all; .git is hidden from the agent.');
-const GuestWorkspace = z.union([z.literal('auto'), z.literal('mirror'), GuestPath]).describe('Where the workspace appears inside the sandbox. "auto" = C:\\Workspace\\<folder name>. "mirror" = the same path as on this PC, so absolute paths in configs and build caches match (another drive letter such as F: is a subst drive onto C:\\Mirror\\F); paths the sandbox reserves (C:\\Users\\..., C:\\Program Files\\...) fall back to "auto".');
-export const Mapping = z.strictObject({
-    host: z.string().min(1).describe('Folder on this PC (relative paths are relative to the config file).'),
-    guest: GuestPath.describe('Where it appears inside the sandbox, e.g. C:\\Assets, or on another drive letter (D: to Z:) such as F:\\SteamLibrary\\steamapps\\common\\Game: mapped to C:\\Mirror\\F\\... and shown as F: (subst) at boot.'),
-    readOnly: z.boolean().describe('true = the agent can only read it.'),
-    optional: z.boolean().optional().describe('true = skip it quietly when the host folder does not exist.'),
-});
-export const Harness = z.strictObject({
-    hostExecutable: z.string().optional().describe('Executable copied from this PC when installed here (e.g. claude.exe).'),
-    hostDir: z.string().optional().describe('Folder of hostExecutable on this PC, or "auto" to search PATH and ~/.local/bin.'),
-    npmPackage: z.string().optional().describe('npm package installed inside the sandbox when there is no host copy.'),
-    npmBin: z.string().optional().describe('Command the npm package provides.'),
-    uvPackage: z.string().optional().describe('Python package installed with `uv tool install` inside the sandbox (e.g. aider-chat).'),
-    uvBin: z.string().optional().describe('Command the uv package provides.'),
-    arguments: Strings.describe('Arguments always passed to the agent.'),
-    environment: z.record(z.string(), z.string()).describe('Environment variables for the agent.'),
-    resumeArguments: Strings.optional().describe('Arguments used when the agent is restarted in place (e.g. after an account switch) so it resumes the conversation.'),
-})
-    .refine((h) => h.hostExecutable || h.npmPackage || h.uvPackage, 'needs hostExecutable, npmPackage or uvPackage')
-    .refine((h) => !h.uvPackage || h.uvBin, 'needs uvBin when uvPackage is set')
-    .refine((h) => !h.npmPackage || h.npmBin, 'needs npmBin when npmPackage is set');
-const Sandbox = z.strictObject({
-    memoryMb: z.union([z.literal('auto'), z.number().int().min(2048)]).describe('Sandbox RAM in MB (>= 2048), or "auto": free RAM minus reserveHostMb, capped at maxMemoryMb.'),
-    maxMemoryMb: z.number().int().positive().describe('Upper limit for memoryMb "auto".'),
-    reserveHostMb: z.number().int().nonnegative().describe('RAM always left for this PC when memoryMb is "auto".'),
-    vGpu: z.boolean().describe('Virtual GPU. Off by default: Microsoft notes it widens the sandbox attack surface.'),
-    networking: z.boolean().describe('Internet access. false is the only hard network isolation Windows Sandbox offers.'),
-    clipboard: z.boolean().describe('Shared clipboard between this PC and the sandbox.'),
-    audioInput: z.boolean().describe('Microphone access.'),
-    videoInput: z.boolean().describe('Camera access.'),
-    printerRedirection: z.boolean().describe('Printers from this PC.'),
-    protectedClient: z.boolean().describe('Run the sandbox window in Protected Client mode (recommended).'),
-    headless: z.boolean().describe('Hide the sandbox window (sbx-show brings it back). A headless sandbox shuts down when its last session ends.'),
-});
-const Git = z.strictObject({ enabled: z.boolean().describe('Provide Git for Windows (and Git Bash, which Claude Code needs).'), access: GitAccess });
-const Provisioning = z.strictObject({
-    copyFromHost: z.boolean().describe('Copy Node, Git, nvm and the agent from this PC when they are installed here.'),
-    fallbackToInstall: z.boolean().describe('Download anything that cannot be copied from this PC.'),
-    refresh: z.boolean().describe('Re-copy / re-download everything on the next launch.'),
-    git: Git,
-    terminal: toggle('Windows Terminal as the sandbox window (downloaded once).'),
-});
-/** true, false, or "auto": only when the project uses it (found from files like go.mod in the workspace or one level down). */
-export const Enabled = z.union([z.boolean(), z.literal('auto')]);
-const enabled = (what, markers) => Enabled.describe(what + ' true, false, or "auto" = only when the project has ' + markers + '.');
-const Packages = (what, example) => Strings.describe(what + ', installed once and kept (e.g. ' + example + ').');
-const Toolchains = z.strictObject({
-    node: z.strictObject({
-        version: z.string().min(1).describe('Default Node version for nvm. "host" = the Node on this PC. A project\'s .nvmrc / .node-version wins.'),
-        extraVersions: Strings.describe('More Node versions to install (switch with nvm use). On top of the up to 3 versions copied from this PC\'s nvm, not counted towards that limit.'),
-        corepack: z.boolean().describe('pnpm and yarn through corepack (a project\'s "packageManager" in package.json picks the version).'),
-        volta: Enabled.describe('Volta: true, false, or "auto" = when the project\'s package.json has "volta" pins or this PC uses Volta. With pins, Volta\'s node/npm/yarn/pnpm come first on PATH.'),
-        globalPackages: Packages('npm packages installed globally into the default Node version', '["typescript", "npm-check-updates"]'),
-    }),
-    python: z.strictObject({
-        enabled: enabled('Python 3 (CPython with pip).', 'pyproject.toml, requirements.txt, setup.py, Pipfile or .python-version'),
-        version: z.string().min(1).describe('Python 3 version prefix, e.g. "3" or "3.12". A project\'s .python-version wins.'),
-        python2: z.boolean().describe('Also install Python 2.7 as python2 / pip2.'),
-        pyenv: Enabled.describe('pyenv-win (pyenv install / local / global): true, false, or "auto" = when this PC uses pyenv. .python-version is honoured either way, and `uv python install` always works.'),
-        tools: Packages('Python command-line tools installed with `uv tool install` (needs uv)', '["poetry", "ruff", "pre-commit"]'),
-    }),
-    rust: z.strictObject({
-        enabled: enabled('Rust via rustup (cargo, rustc).', 'Cargo.toml or rust-toolchain(.toml)'),
-        toolchain: z.string().min(1).describe('Default toolchain, e.g. "stable". rust-toolchain.toml in a project wins.'),
-        host: z.string().min(1).describe('Host triple, or "auto": x86_64-pc-windows-msvc when the MSVC toolchain is on (like most PCs), else x86_64-pc-windows-gnu (MinGW is its linker).'),
-        components: Packages('Extra rustup components', '["rust-src", "llvm-tools"]'),
-        targets: Packages('Extra rustup targets', '["wasm32-unknown-unknown"]'),
-        crates: Packages('Binaries for cargo: prebuilt via cargo-binstall when the crate publishes a Windows build, else compiled with `cargo install --locked` (slow the first time)', '["sccache", "cargo-nextest", "cargo-deny"]'),
-        targetDir: z.string().min(1).describe('"shared": cargo\'s default target\\ (shared with builds on this PC, so builds on either side invalidate the other), "separate": <workspace>\\target\\sandbox (kept, no cross-talk), "local": on the sandbox\'s own disk (fastest, lost every boot), or a guest path.'),
-    }),
-    msvc: z.strictObject({
-        enabled: enabled('MSVC (cl, link) and the Windows SDK, portable from Microsoft\'s Visual Studio manifest (~1-2 GB once), with vcvars64.bat and vswhere.', 'a .vcxproj, CMakePresets.json, a script calling vcvars/vswhere, or a Rust project when this PC builds Rust with MSVC'),
-        acceptLicense: z.boolean().describe('Required to install MSVC: you accept the Visual Studio licence terms (https://visualstudio.microsoft.com/license-terms/), which need a Visual Studio licence.'),
-        msvcVersion: z.string().min(1).describe('"latest" or an MSVC tools version prefix, e.g. "14.44".'),
-        sdkVersion: z.string().min(1).describe('"latest" or a Windows SDK build, e.g. "26100" or "10.0.22621".'),
-    }),
-    cpp: z.strictObject({
-        enabled: enabled('MinGW-w64 GCC with CMake, Ninja, premake5 and mingw32-make (also Rust\'s linker).', 'CMakeLists.txt, Makefile, meson.build, premake5.lua or Cargo.toml'),
-        flexBison: z.boolean().describe('win_flex / win_bison, the parser generators many C/C++ projects (game engines among them) need; CMake finds them.'),
-    }),
-    dotnet: z.strictObject({
-        enabled: enabled('.NET SDK (C#, F#).', 'a .sln, .slnx, .csproj, .fsproj or global.json'),
-        channels: Strings.describe('SDK channels, e.g. ["LTS", "8.0"]. A project\'s global.json is installed too.'),
-        tools: Packages('Global .NET tools (`dotnet tool install -g`)', '["dotnet-ef", "csharpier"]'),
-        workloads: Packages('SDK workloads (`dotnet workload install`)', '["aspire", "wasm-tools"]'),
-        frameworkTargets: Strings.describe('.NET Framework reference assemblies (targeting packs) from NuGet, so net4x and old-style .csproj projects build without Visual Studio, e.g. ["net48", "net472", "net462"]. The 4.8 runtime itself ships with Windows.'),
-        netfx35: z.boolean().describe('.NET Framework 3.5 runtime (a Windows feature, enabled from Windows Update on every boot; a few minutes).'),
-    }),
-    go: z.strictObject({
-        enabled: enabled('Go.', 'go.mod or go.work'),
-        version: z.string().min(1).describe('"stable" or a version prefix such as "1.23". A go.mod asking for newer fetches it itself (GOTOOLCHAIN=auto).'),
-        tools: Packages('Go tools (`go install <path>@<version>`)', '["golang.org/x/tools/gopls@latest"]'),
-    }),
-    java: z.strictObject({
-        enabled: enabled('Java: Eclipse Temurin JDK.', 'pom.xml, build.gradle(.kts), settings.gradle(.kts), mvnw, gradlew or .java-version'),
-        version: z.string().min(1).describe('"lts" (newest LTS) or a major version such as "21". A project\'s .java-version or .sdkmanrc wins.'),
-        maven: z.boolean().describe('Apache Maven (mvn). A project\'s mvnw works either way.'),
-        gradle: z.boolean().describe('Gradle (gradle). A project\'s gradlew works either way.'),
-    }),
-    ruby: z.strictObject({
-        enabled: enabled('Ruby (RubyInstaller, with gem and bundler). Gems with C extensions need MSYS2, which is not included.', 'Gemfile, a .gemspec or .ruby-version'),
-        version: z.string().min(1).describe('Version prefix, e.g. "3" or "3.3". A project\'s .ruby-version wins.'),
-        gems: Packages('Gems installed globally', '["rubocop"]'),
-    }),
-    php: z.strictObject({
-        enabled: enabled('PHP (with the Visual C++ runtime it needs, installed on every boot).', 'composer.json, artisan or .php-version'),
-        version: z.string().min(1).describe('Version prefix, e.g. "8" or "8.3". A project\'s .php-version wins.'),
-        composer: z.boolean().describe('Composer.'),
-    }),
-    deno: z.strictObject({ enabled: enabled('Deno.', 'deno.json, deno.jsonc or deno.lock') }),
-    pwsh: z.strictObject({ enabled: Enabled.describe('PowerShell 7 (pwsh), portable (~110 MB once); `powershell` stays Windows PowerShell 5.1. true, false, or "auto" = when a .ps1 at the root or one folder down has #Requires -Version 7 / -PSEdition Core or a `pwsh ...` usage line, or, in a folder that is no project yet, when this PC has PowerShell 7.') }),
-    cli: z.strictObject({
-        gh: Enabled.describe('GitHub CLI (gh). Only with provisioning.git.access "full": gh can push and merge through the GitHub API, past a read-only git. Your PC\'s gh login is never copied; `gh auth login` inside persists (GH_CONFIG_DIR). "auto" = when the project has a .github folder.'),
-        zstd: Enabled.describe('Zstandard (zstd). "auto" = off; set true to get it.'),
-        openssl: Enabled.describe('`openssl` on PATH, from the copy Git for Windows ships (its mingw64\\bin is not put on PATH, so it cannot shadow MinGW\'s gcc). "auto" = on.'),
-    }).describe('Small portable command-line tools from their GitHub releases, installed once into tools\\cli.'),
-    bun: toggle('Bun runtime (claude-mem needs it).'),
-    uv: toggle('uv, the Python package manager (claude-mem needs it).'),
-    vcRuntime: toggle('Microsoft Visual C++ runtime for tools that need it (a real installer, so it runs on every boot, ~15 s). PHP installs it regardless.'),
-    mesa: z.strictObject({
-        enabled: z.boolean().describe('Mesa 3D (llvmpipe): OpenGL 4.5 in software for games and apps when there is no GPU (sandbox.vGpu off). Copy opengl32.dll and libgallium_wgl.dll from %MESA_DIR% next to the program\'s .exe.'),
-        vulkan: z.boolean().describe('Also software Vulkan 1.4 (Mesa lavapipe) with the Khronos loader, registered for every program; for wgpu set WGPU_BACKEND=vulkan.'),
-    }),
-    vscode: toggle('Portable VS Code inside the sandbox (code on PATH, desktop shortcut); its settings and extensions persist.'),
-    environment: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/, 'letters, digits and _ only'), z.string()).describe('Extra environment variables for the agent and every terminal, e.g. registry mirrors: {"NPM_CONFIG_REGISTRY": "https://...", "PIP_INDEX_URL": "https://..."}.'),
-});
-const Port = z.number().int().min(1024).max(65535);
-const dbEnabled = (name) => Enabled.describe(name + ': true, false, or "auto" = only when the project needs it (found from compose files, dependencies of every language, Prisma/ORM config and connection strings).');
-const Databases = z.strictObject({
-    postgres: z.strictObject({
-        enabled: dbEnabled('PostgreSQL (with psql, pg_dump). User postgres, no password, localhost only'),
-        version: z.string().min(1).describe('"latest" or a major version such as "16". A compose file pinning postgres:<major> wins.'),
-        port: Port.describe('Port inside the sandbox.'),
-    }),
-    mysql: z.strictObject({
-        enabled: dbEnabled('MySQL-compatible database (MariaDB). User root, no password, localhost only'),
-        version: z.string().min(1).describe('"lts" (newest MariaDB LTS) or a MariaDB series such as "11.4".'),
-        port: Port.describe('Port inside the sandbox.'),
-    }),
-    mongodb: z.strictObject({
-        enabled: dbEnabled('MongoDB with mongosh, localhost only'),
-        version: z.string().min(1).describe('"latest" or a version prefix such as "8.0".'),
-        port: Port.describe('Port inside the sandbox.'),
-    }),
-    redis: z.strictObject({
-        enabled: dbEnabled('Redis (community Windows build), localhost only'),
-        port: Port.describe('Port inside the sandbox.'),
-    }),
-    dynamodb: z.strictObject({
-        enabled: dbEnabled('DynamoDB Local (Amazon\'s official emulator, on the Java toolchain) with dynamodb-admin, a web UI to browse and edit tables'),
-        port: Port.describe('DynamoDB endpoint port inside the sandbox (http://localhost:<port>).'),
-        adminPort: Port.describe('dynamodb-admin web UI port (open http://localhost:<adminPort> in the sandbox\'s browser).'),
-        admin: z.boolean().describe('Run dynamodb-admin next to DynamoDB Local.'),
-    }),
-    sqlserver: z.strictObject({
-        enabled: dbEnabled('SQL Server. It cannot run inside Windows Sandbox; when a project needs it you get a hint to reach the one on this PC through hostAccess.forwards'),
-    }),
-});
-const Secrets = z.strictObject({
-    strip: z.boolean().describe('Remove credentials from everything copied into the sandbox (your Claude settings.json "env" and credential helpers, MCP servers\' env, headers and arguments): AWS, Azure, Google Cloud, Cloudflare, hosting, CI, registries, payment, AI API keys, database URLs, anything named *_TOKEN / *_SECRET / *PASSWORD* / *_KEY or *PROD*, and values that look like keys.'),
-    allow: Strings.describe('Variable names that may go in anyway; * matches anything, e.g. ["AWS_REGION", "AWS_PROFILE", "MY_APP_*"].'),
-    patterns: Strings.describe('More variable names to treat as secrets; * matches anything, e.g. ["ACME_*", "*_INTERNAL_URL"].'),
-    warnFiles: z.boolean().describe('Warn at launch about files in the workspace that usually hold secrets (.env, *.pem, credentials.json, ...). The agent CAN read them: Windows Sandbox maps the whole folder.'),
-});
-const Attach = z.strictObject({
-    enabled: z.boolean().describe('Allow sandbox claude --terminal / sandbox attach from this PC.'),
-    reuseSession: z.boolean().describe('sandbox claude -t in a running sandbox reattaches to this folder\'s session when no terminal on this PC is attached to it (--new always starts another).'),
-    auto: z.boolean().describe('Starting an agent attaches this terminal automatically, as if you passed -t (only in an interactive terminal).'),
-    autoHide: z.boolean().describe('Hide the Windows Sandbox window whenever this terminal attaches; it keeps running (sandbox show brings it back).'),
-});
-const ClaudeProfile = z.strictObject({
-    enabled: z.boolean().describe('Copy selected Claude settings from this PC into the sandbox.'),
-    hostDir: z.string().describe('Your Claude folder, or "auto" (~/.claude or CLAUDE_CONFIG_DIR).'),
-    include: z.array(z.string().regex(/^[A-Za-z0-9._-]+$/)).describe('Files and folders copied from it.'),
-    globalStateFile: z.string().describe('Your .claude.json, or "auto". Empty string = do not copy.'),
-    copyCredentials: z.boolean().describe('Copy your Claude LOGIN into the sandbox. Prefer sandbox account instead.'),
-    overwrite: z.boolean().describe('Refresh these settings from this PC on every launch.'),
-    syncHistory: z.boolean().describe('Bring all conversation history in, and sync new history back (path-translated).'),
-    syncClaudeMem: z.boolean().describe('Bring claude-mem data in, and its database back when the sandbox closes.'),
-});
-export const Config = z.strictObject({
-    $schema: SchemaRef.optional(),
-    defaultHarness: Name.describe('Agent started by `sandbox launch` (sandbox claude always runs claude).'),
-    guestWorkspace: GuestWorkspace,
-    readOnly: z.boolean().describe('Map the workspace read-only.'),
-    mappings: z.array(Mapping).describe('Extra folders from this PC.'),
-    sandbox: Sandbox,
-    storage: z.strictObject({
-        root: z.string().min(1).describe('Where everything is kept on this PC (tools, databases, logins, launches).'),
-        persistAgentState: z.boolean().describe('Keep agent logins and history between sandboxes.'),
-        dataName: Name.describe('Name of the persistent data set (C:\\AgentData) shared by all workspaces.'),
-    }),
-    network: z.strictObject({ blockPrivateRanges: z.boolean().describe('Block your LAN (10/8, 172.16/12, 192.168/16, SMB) from inside the sandbox.') }),
-    provisioning: Provisioning,
-    toolchains: Toolchains,
-    databases: Databases.describe('Databases running inside the sandbox. Data persists in C:\\AgentData\\databases; each one starts at boot.'),
-    attach: Attach,
-    secrets: Secrets,
-    personalization: toggle('Copy your desktop look (theme, accent, taskbar, wallpaper, ...) into the sandbox.'),
-    claudeProfile: ClaudeProfile,
-    harnesses: z.record(Name, Harness).describe('Agents that can run in the sandbox.'),
-    hooks: z.strictObject({ failFast: z.boolean().describe('Stop when a hook script fails.') }),
-}).refine((c) => c.harnesses[c.defaultHarness] !== undefined, { message: 'defaultHarness must be one of the configured harnesses', path: ['defaultHarness'] });
-/**
- * What a project's .sandbox-config.json may change. A repo can ship this file, so it can NOT touch storage, agent
- * executables, host folders for tools or Claude settings, or anything else outside this list.
- */
-export const LocalOverrides = z.strictObject({
-    $schema: SchemaRef,
-    harness: Name.describe('Agent for this project.'),
-    guestWorkspace: GuestWorkspace,
-    readOnly: z.boolean().describe('Map this project read-only.'),
-    mappings: z.array(Mapping).describe('Extra folders (relative to this file).'),
-    scripts: Strings.describe('Scripts (.ps1 / .mjs / .cmd, relative to this file) run inside the sandbox before the agent.'),
-    sandbox: Sandbox.partial(),
-    network: z.strictObject({ blockPrivateRanges: z.boolean() }).partial(),
-    provisioning: Provisioning.pick({ copyFromHost: true, fallbackToInstall: true, refresh: true }).extend({ git: Git.partial(), terminal: toggle('Windows Terminal as the sandbox window.').partial() }).partial(),
-    // Every toolchain setting, each one optional (a project usually only switches languages on or pins a version).
-    toolchains: z.strictObject({
-        ..._.mapValues(_.omit(Toolchains.shape, 'environment'), (shape) => shape.partial()),
-        environment: Toolchains.shape.environment,
-    }).partial(),
-    databases: z.strictObject(_.mapValues(Databases.shape, (shape) => shape.partial())).partial(),
-    attach: Attach.partial(),
-    personalization: toggle('Copy your desktop look into the sandbox.').partial(),
-    claudeProfile: ClaudeProfile.pick({ enabled: true, include: true, overwrite: true, copyCredentials: true, syncHistory: true, syncClaudeMem: true }).partial(),
-    hooks: z.strictObject({ failFast: z.boolean() }).partial(),
-}).partial();
-/** One readable line per problem: "sandbox.memoryMb: Too small: expected number to be >=2048". */
-export const describeIssues = (error) => error.issues.map((issue) => {
-    const at = issue.path.join('.');
-    if (issue.code === 'unrecognized_keys')
-        return issue.keys.map((k) => (at ? at + '.' : '') + k + ' is not allowed here').join('; ');
-    return (at || 'value') + ': ' + issue.message;
-});
-/** JSON Schema documents for editors. The user config only lists what it changes, so nothing in it is required. */
-export const jsonSchemas = () => {
-    const dropRequired = (node) => {
-        if (Array.isArray(node))
-            return node.map(dropRequired);
-        if (typeof node !== 'object' || node === null)
-            return node;
-        return Object.fromEntries(Object.entries(node).filter(([k]) => k !== 'required').map(([k, v]) => [k, dropRequired(v)]));
-    };
-    const toSchema = (schema, title) => ({ title, ...z.toJSONSchema(schema, { io: 'input', unrepresentable: 'any' }) });
-    return {
-        'config.schema.json': dropRequired(toSchema(Config, 'windows-development-sandbox user config (~/.agent-sandbox/config.json)')),
-        'sandbox-config.schema.json': toSchema(LocalOverrides, 'windows-development-sandbox project config (.sandbox-config.json)'),
-    };
-};
+// Every setting, defined once with zod, split by area in schema/. This file is the one place the rest of the code (and
+// scripts/schemas.mjs, which generates the JSON Schema files) imports them from.
+export { GitAccess } from './schema/common.js';
+export { Config, LocalOverrides } from './schema/config.js';
+export { Harness } from './schema/harness.js';
+export { describeIssues, jsonSchemas } from './schema/json-schema.js';
+export { Mapping } from './schema/sandbox.js';
+export { Toolchains } from './schema/toolchains.js';

package/dist/core/types.d.ts

@@ -50,6 +50,8 @@ export interface ResolvedRun {
     localConfigPath: string | null;
     notes: string[];
     versions: ToolVersions;
+    /** Your config asks for guestWorkspace "mirror" (project roots then appear at their PC paths too). */
+    mirror?: boolean;
 }
 /** A requested version plus where the request came from (shown to the user). */
 export interface VersionSpec {
@@ -84,7 +86,6 @@ export interface DatabasePlan {
     port: number;
     adminPort?: number;
 }
-/** databases: the plan to use instead of scanning the workspace (tests). */
 /** databases / pcLanguages: use these instead of scanning (tests). */
 export interface GenerateOptions {
     packageRoot: string;
@@ -94,6 +95,11 @@ export interface GenerateOptions {
     freeMemoryBytes?: number;
     databases?: DatabasePlan[];
     pcLanguages?: import('./detect-toolchains.js').AutoToolchain[];
+    /** More projects to map (a restart that adds one keeps the ones in use); knownProjects: instead of known-projects.json (tests). */
+    extraProjects?: string[];
+    knownProjects?: string[];
+    /** false: no agent session at boot. */
+    autoSession?: boolean;
 }
 export interface Generated {
     wsbPath: string;
@@ -104,6 +110,18 @@ export interface Generated {
     mappings: ResolvedMapping[];
     profile: ProfileResult;
     databases: DatabasePlan[];
+    /** Project roots and other projects mapped with the launch folder. */
+    projects: {
+        roots: {
+            host: string;
+            guest: string;
+        }[];
+        projects: {
+            host: string;
+            guest: string;
+        }[];
+        notes: string[];
+    };
     toolchains: Record<import('./detect-toolchains.js').AutoToolchain, import('./detect-toolchains.js').ToolchainDecision>;
 }
 /** secretsRemoved: what secrets.strip kept on this PC, e.g. "settings.json env.AWS_SECRET_ACCESS_KEY". */
@@ -120,6 +138,13 @@ export interface GuestSession {
     project: string;
     workspace: string;
     workspaceHost: string;
+    /** The launch folder's project id (file-name safe; status files and sessions use it). Older launch folders lack it. */
+    projectId?: string;
+    /** Where other projects appear (C:\Projects), and the project roots' guest folders. Older launch folders lack them. */
+    projectsDir?: string;
+    roots?: string[];
+    /** false: start no agent session at boot (a restart that adds a project opens its sessions itself). */
+    autoSession?: boolean;
     harnessName: string;
     harness: Harness | null;
     harnessArguments: string[];
@@ -135,6 +160,7 @@ export interface GuestSession {
     databaseCatalog?: DatabasePlan[];
     attach: Config['attach'];
     hooks: Config['hooks'];
+    downloads: Config['downloads'];
     /** nodeVersion: this PC's Node (e.g. 22.11.0), found under nvm\v<version> when nvm is mapped, else under node. */
     /** volta / pyenv: this PC uses them (their "auto" settings turn them on in the sandbox too). */
     hostTools: {
@@ -159,4 +185,6 @@ export interface GuestSession {
         letter: string;
         target: string;
     }[];
+    /** sandbox.cpuLimit as a number (null = no cap); sandbox\cpucap.ps1 applies it before anything starts. */
+    cpuLimitPercent?: number | null;
 }

package/dist/core/util.d.ts

@@ -18,6 +18,7 @@ export declare const dirExists: (p: string) => boolean;
 export declare const fileExists: (p: string) => boolean;
 export declare const readJson: <T>(p: string) => T;
 export declare const tryReadJson: <T>(p: string) => T | null;
+/** Atomic (a crash or a second command never leaves half a file); refused outside temp during the self-test. */
 export declare const writeJson: (p: string, value: unknown) => void;
 export declare const realPath: (p: string) => string;
 export declare const xmlEscape: (v: string) => string;
@@ -49,5 +50,11 @@ export declare const runPowerShell: (script: string, capture?: boolean) => {
     status: number;
     stdout: string;
 };
+/** Runs a program (an absolute path: `SYSTEM.*`, never a bare name) and returns its stdout, or '' if it failed or timed out. */
+export declare const captureOutput: (file: string, args: string[], options?: {
+    timeout?: number;
+    cwd?: string;
+    maxBuffer?: number;
+}) => string;
 /** Async variant (does not block the event loop), resolving with stdout. */
 export declare const runPowerShellAsync: (script: string) => Promise<string>;

package/dist/core/util.js

@@ -3,6 +3,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { spawn, spawnSync } from 'node:child_process';
 import { SYSTEM } from '../shared/system.js';
+import { writeJsonAtomic } from '../shared/rundir.js';
+import { assertTestWritable } from '../shared/test-guard.js';
 import { parse as parseJsoncText, printParseErrorCode } from 'jsonc-parser';
 export const isWin = process.platform === 'win32';
 /** An expected problem the user can act on: what went wrong, and (optionally) how to fix it. */
@@ -52,7 +54,8 @@ export const tryReadJson = (p) => { try {
 catch {
     return null;
 } };
-export const writeJson = (p, value) => { ensureDir(path.dirname(p)); fs.writeFileSync(p, JSON.stringify(value, null, 2) + '\n', 'utf8'); };
+/** Atomic (a crash or a second command never leaves half a file); refused outside temp during the self-test. */
+export const writeJson = (p, value) => writeJsonAtomic(p, value);
 export const realPath = (p) => { try {
     return fs.realpathSync(p);
 }
@@ -96,7 +99,7 @@ catch {
     return false;
 } };
 /** Removes a symlink or junction itself (never its target). Junctions need rmdir on Windows. */
-export const removeLink = (p) => { try {
+export const removeLink = (p) => { assertTestWritable(p); try {
     fs.unlinkSync(p);
 }
 catch {
@@ -126,7 +129,8 @@ export const assertNoLinks = (root, target) => {
 const powerShellArgs = (script) => {
     const prelude = "[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false\n$ProgressPreference = 'SilentlyContinue'\n";
     const encoded = Buffer.from(prelude + script, 'utf16le').toString('base64');
-    return ['-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded];
+    // -OutputFormat Text: with redirected output PowerShell would otherwise print its progress stream as "#< CLIXML" XML.
+    return ['-NoLogo', '-NoProfile', '-NonInteractive', '-OutputFormat', 'Text', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded];
 };
 /** Runs a PowerShell script and returns its exit code (and stdout when `capture`). */
 export const runPowerShell = (script, capture = false) => {
@@ -135,6 +139,11 @@ export const runPowerShell = (script, capture = false) => {
         throw result.error;
     return { status: result.status ?? 1, stdout: result.stdout ?? '' };
 };
+/** Runs a program (an absolute path: `SYSTEM.*`, never a bare name) and returns its stdout, or '' if it failed or timed out. */
+export const captureOutput = (file, args, options = {}) => {
+    const result = spawnSync(file, args, { encoding: 'utf8', windowsHide: true, timeout: 60000, ...options });
+    return result.status === 0 ? result.stdout ?? '' : '';
+};
 /** Async variant (does not block the event loop), resolving with stdout. */
 export const runPowerShellAsync = (script) => new Promise((resolve, reject) => {
     const child = spawn(SYSTEM.powershell(), powerShellArgs(script), { stdio: ['ignore', 'pipe', 'inherit'], windowsHide: true });

package/dist/core/workspace.d.ts

@@ -1,9 +1,4 @@
 import type { Config, Overrides, ResolvedRun, RunRequest, ToolVersions } from './types.js';
-export declare const askYesNo: (question: string) => Promise<boolean>;
-/** A read/write folder mapped into the sandbox must not contain, or sit inside, any protected folder. */
-export declare const assertSafeMapping: (folder: string, packageRoot: string, storageRoot: string) => void;
-/** The agent gets read/write access to the workspace, so refuse folders that would let it reach the tool itself, its storage, or the OS. */
-export declare const assertSafeWorkspace: (workspace: string, packageRoot: string, storageRoot: string) => void;
 /**
  * 'auto' guest workspace: C:\Workspace\<folder name>. Keeping the real folder name means Claude's per-project history
  * and claude-mem's project name match this PC instead of every project being "Workspace".

package/dist/core/workspace.js

@@ -1,53 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import readline from 'node:readline';
 import { z } from 'zod';
-import { userDir } from './config.js';
 import { planMirrorWorkspace } from '../shared/guest-paths.js';
 import { DATABASES } from './detect-databases.js';
 import { applyOverrides, describeOverrides, isTrusted, normalizeOverrides, readLocalConfig, saveTrust, trustStorePath } from './local-config.js';
-import { dirExists, expandPath, fail, fileExists, isInsideOrEqual, isRootPath, isUserProfile } from './util.js';
-export const askYesNo = async (question) => {
-    if (!process.stdin.isTTY)
-        return false;
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    const answer = await new Promise((resolve) => rl.question(question + ' [y/N] ', resolve));
-    rl.close();
-    return /^y(es)?$/i.test(answer.trim());
-};
-/** Folders the agent must never be able to write: the tool itself, its storage and your settings for it. */
-const protectedFolders = (packageRoot, storageRoot) => [
-    ['this tool\'s install folder', packageRoot],
-    ['the sandbox storage folder', storageRoot],
-    ['your sandbox settings folder', userDir()],
-];
-/** A read/write folder mapped into the sandbox must not contain, or sit inside, any protected folder. */
-export const assertSafeMapping = (folder, packageRoot, storageRoot) => {
-    if (isRootPath(folder) || isUserProfile(folder))
-        fail('A whole drive or user profile cannot be mapped into the sandbox: ' + folder, 'Map a specific folder instead.');
-    for (const [label, dir] of protectedFolders(packageRoot, storageRoot)) {
-        if (isInsideOrEqual(dir, folder) || isInsideOrEqual(folder, dir))
-            fail(folder + ' cannot be mapped into the sandbox: it overlaps ' + label + ' (' + dir + ').', 'Map a folder that is not inside (and does not contain) ' + dir + '.');
-    }
-};
-/** The agent gets read/write access to the workspace, so refuse folders that would let it reach the tool itself, its storage, or the OS. */
-export const assertSafeWorkspace = (workspace, packageRoot, storageRoot) => {
-    if (isRootPath(workspace))
-        fail('A whole drive cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder (or pass --workspace <folder>).');
-    if (isUserProfile(workspace))
-        fail('Your whole user profile cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder (or pass --workspace <folder>).');
-    for (const [label, dir] of protectedFolders(packageRoot, storageRoot)) {
-        if (isInsideOrEqual(dir, workspace))
-            fail(workspace + ' cannot be the workspace: it is inside ' + label + ' (' + dir + '), so the agent could change the code that runs on this PC.', dir === packageRoot ? 'Developing windows-development-sandbox itself? Install it as a copy instead of a link: run `npm run install:global` in the repository, then sandbox claude works there.' : 'Run sandbox claude from a project folder somewhere else.');
-        if (isInsideOrEqual(workspace, dir))
-            fail(workspace + ' cannot be the workspace: it contains ' + label + ' (' + dir + '), which the agent must not be able to change.', 'Run sandbox claude from a project folder that does not contain it.');
-    }
-    for (const name of ['WINDIR', 'ProgramFiles', 'ProgramFiles(x86)', 'ProgramData']) {
-        const dir = process.env[name];
-        if (dir && isInsideOrEqual(dir, workspace))
-            fail('A system folder cannot be the workspace: ' + workspace, 'Run sandbox claude from a project folder.');
-    }
-};
+import { assertSafeWorkspace } from './safe-paths.js';
+import { dirExists, expandPath, fail, fileExists } from './util.js';
 /**
  * 'auto' guest workspace: C:\Workspace\<folder name>. Keeping the real folder name means Claude's per-project history
  * and claude-mem's project name match this PC instead of every project being "Workspace".
@@ -104,7 +62,14 @@ export const resolveVersions = (config, workspace, local, req, hostNodeVersion)
 export const resolveRun = async (req, hostNodeVersion = process.version) => {
     const notes = [];
     // Mappings from the user config are relative to that config file; expand them before anything else uses them.
-    let config = { ...req.loaded.config, mappings: req.loaded.config.mappings.map((m) => ({ ...m, host: expandPath(m.host, req.loaded.base) })) };
+    const expand = (list) => list.map((p) => expandPath(p, req.loaded.base));
+    const projects = req.loaded.config.projects;
+    let config = {
+        ...req.loaded.config,
+        mappings: req.loaded.config.mappings.map((m) => ({ ...m, host: expandPath(m.host, req.loaded.base) })),
+        projects: { ...projects, roots: expand(projects.roots), exclude: expand(projects.exclude), declinedRoots: expand(projects.declinedRoots) },
+    };
+    const mirror = config.guestWorkspace === 'mirror';
     const storageRoot = expandPath(config.storage.root, req.loaded.base);
     const workspaceHost = path.resolve(req.workspace ?? req.cwd);
     if (!dirExists(workspaceHost))
@@ -158,5 +123,6 @@ export const resolveRun = async (req, hostNodeVersion = process.version) => {
         fail('Unknown agent "' + harnessName + '".', 'Configured agents: ' + Object.keys(config.harnesses).join(', ') + ' (add more under "harnesses" in your config).');
     const versions = resolveVersions(config, workspaceHost, overrides, req, hostNodeVersion);
     const dataPath = path.join(storageRoot, 'data', config.storage.dataName);
-    return { config, storageRoot, dataPath, workspaceHost, harnessName, scripts, localConfigPath, notes, versions };
+    // A project file may ask for "mirror" too (it decides only its own path); project roots follow the user's choice.
+    return { config, storageRoot, dataPath, workspaceHost, harnessName, scripts, localConfigPath, notes, versions, mirror };
 };

package/dist/guest/boot-env.d.ts

@@ -0,0 +1,4 @@
+import { type BootEnvT } from './project-env.js';
+export { baseEnvFor, type BootEnvT } from './project-env.js';
+export declare const saveBootEnv: (value: BootEnvT) => void;
+export declare const readBootEnv: () => BootEnvT | null;

package/dist/guest/boot-env.js

@@ -0,0 +1,25 @@
+// What the boot's provisioning left for projects that join later: the PATH before any toolchain was added, which
+// variables the toolchains set, and what each step contributed. Kept on the sandbox's own disk (lost on close, as it
+// should be). The session daemon builds every later project's environment from it instead of from the boot
+// project's, so project A's Node, Rust target folder or database variables never leak into project B's sessions.
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeJsonAtomic } from '../shared/rundir.js';
+import { localDir } from './env.js';
+import { BootEnv } from './project-env.js';
+export { baseEnvFor } from './project-env.js';
+const file = () => path.join(localDir, 'boot-env.json');
+export const saveBootEnv = (value) => {
+    try {
+        writeJsonAtomic(file(), value);
+    }
+    catch { /* projects added later then fall back to the boot environment */ }
+};
+export const readBootEnv = () => {
+    try {
+        return BootEnv.safeParse(JSON.parse(fs.readFileSync(file(), 'utf8'))).data ?? null;
+    }
+    catch {
+        return null;
+    }
+};

package/dist/guest/cmdline.d.ts

@@ -0,0 +1,12 @@
+export declare const quoteArg: (arg: string) => string;
+/**
+ * Arguments on a `cmd /d /c <agent>.cmd ...` line (npm agents). cmd parses them twice: the /c line, then the .cmd's %*.
+ * & | < > ^ are literal inside quotes, so arguments with them are quoted (https://x?a=1&b=2 survives). % expands even
+ * inside quotes, so each one sits between quoted pieces ("50"%" off"): every %name% cmd could see then starts with a
+ * quote, and no variable is called that. cmd's quote state runs across the whole line (an embedded \" toggles it too),
+ * so a metacharacter it would see outside quotes gets ^^^ (one caret left after each parse). Arguments without any
+ * of these are quoted as usual.
+ */
+export declare const cmdArgs: (args: string[]) => string;
+/** The command line ptyhost starts; when the program is cmd.exe its arguments are quoted for cmd (cmdArgs). */
+export declare const commandLine: (file: string, args: string[]) => string;

package/dist/guest/cmdline.js

@@ -0,0 +1,23 @@
+// Command lines for the agent: Windows argument quoting, and the extra layer cmd.exe needs for npm agents (.cmd files).
+import path from 'node:path';
+const quoted = (arg) => '"' + arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1') + '"';
+export const quoteArg = (arg) => (arg !== '' && !/[\s"]/.test(arg) ? arg : quoted(arg));
+/**
+ * Arguments on a `cmd /d /c <agent>.cmd ...` line (npm agents). cmd parses them twice: the /c line, then the .cmd's %*.
+ * & | < > ^ are literal inside quotes, so arguments with them are quoted (https://x?a=1&b=2 survives). % expands even
+ * inside quotes, so each one sits between quoted pieces ("50"%" off"): every %name% cmd could see then starts with a
+ * quote, and no variable is called that. cmd's quote state runs across the whole line (an embedded \" toggles it too),
+ * so a metacharacter it would see outside quotes gets ^^^ (one caret left after each parse). Arguments without any
+ * of these are quoted as usual.
+ */
+export const cmdArgs = (args) => {
+    const pieces = args.map((arg) => (/[&|<>^%]/.test(arg) ? arg.split('%').map(quoted).join('%') : quoteArg(arg))).join(' ');
+    let inQuotes = false;
+    return [...pieces].map((c) => {
+        if (c === '"')
+            inQuotes = !inQuotes;
+        return !inQuotes && /[&|<>^]/.test(c) ? '^^^' + c : c;
+    }).join('');
+};
+/** The command line ptyhost starts; when the program is cmd.exe its arguments are quoted for cmd (cmdArgs). */
+export const commandLine = (file, args) => path.win32.basename(file).toLowerCase() === 'cmd.exe' ? [quoteArg(file), cmdArgs(args)].filter(Boolean).join(' ') : [file, ...args].map(quoteArg).join(' ');

package/dist/guest/daemon/exec.d.ts

@@ -0,0 +1,5 @@
+import type { GuestRequest } from '../../core/types.js';
+/** Runs a command for the host without blocking the daemon (other requests and pings keep being answered). */
+export declare const execCommand: (req: Extract<GuestRequest, {
+    kind: "exec";
+}>) => void;