windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/core/schema.js

@@ -0,0 +1,264 @@
+// 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)'),
+    };
+};

package/dist/core/types.d.ts

@@ -0,0 +1,162 @@
+import type { z } from 'zod';
+import type { Config as ConfigSchema, GitAccess as GitAccessSchema, Harness as HarnessSchema, LocalOverrides, Mapping as MappingSchema } from './schema.js';
+export type { AttachEndpointT as AttachEndpoint, GuestRequestT as GuestRequest, GuestResponseT as GuestResponse, SandboxStatusT as SandboxStatus, SessionStatusT as SessionStatus } from '../shared/schema.js';
+export type Config = z.output<typeof ConfigSchema>;
+export type Overrides = z.output<typeof LocalOverrides>;
+export type GitAccess = z.output<typeof GitAccessSchema>;
+export type Harness = z.output<typeof HarnessSchema>;
+export type Mapping = z.output<typeof MappingSchema>;
+export type Toolchains = Config['toolchains'];
+export type ClaudeProfileConfig = Config['claudeProfile'];
+export interface ResolvedMapping {
+    host: string;
+    guest: string;
+    readOnly: boolean;
+}
+export interface LocalConfigFile {
+    path: string;
+    hash: string;
+    data: unknown;
+}
+export interface LoadedConfig {
+    config: Config;
+    configPath: string | null;
+    base: string;
+}
+export interface RunRequest {
+    packageRoot: string;
+    loaded: LoadedConfig;
+    cwd: string;
+    workspace?: string;
+    harness?: string;
+    noAgent: boolean;
+    noLocalConfig: boolean;
+    trustConfig: boolean;
+    scripts: string[];
+    headless?: boolean;
+    /** --database: start these whatever the config and detection say. */
+    databases?: string[];
+    nodeVersion?: string;
+    pythonVersion?: string;
+    ask?: (question: string) => Promise<boolean>;
+}
+export interface ResolvedRun {
+    config: Config;
+    storageRoot: string;
+    dataPath: string;
+    workspaceHost: string;
+    harnessName: string;
+    scripts: string[];
+    localConfigPath: string | null;
+    notes: string[];
+    versions: ToolVersions;
+}
+/** A requested version plus where the request came from (shown to the user). */
+export interface VersionSpec {
+    spec: string;
+    source: string;
+}
+export interface ToolVersions {
+    node: VersionSpec;
+    nodeExtra: string[];
+    python: VersionSpec;
+}
+export interface HostProbe {
+    nodeDir: string | null;
+    harnessExe: {
+        dir: string;
+        file: string;
+    } | null;
+    gitDir: string | null;
+    nvmDir: string | null;
+    hostNodeVersion: string;
+    /** This PC's Node is one of nvm's versions, so it comes in with nvm and nodeDir stays unmapped. */
+    nvmNode?: boolean;
+    /** This PC has Volta / pyenv-win (VOLTA_HOME / PYENV set). */
+    volta?: boolean;
+    pyenv?: boolean;
+}
+/** A database the sandbox runs, and why ("compose.yaml: a compose service runs Postgres"). */
+export interface DatabasePlan {
+    database: 'postgres' | 'mysql' | 'sqlserver' | 'mongodb' | 'redis' | 'dynamodb';
+    reasons: string[];
+    version: string;
+    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;
+    run: ResolvedRun;
+    harnessArgs: string[];
+    probe: HostProbe;
+    freeMemoryBytes?: number;
+    databases?: DatabasePlan[];
+    pcLanguages?: import('./detect-toolchains.js').AutoToolchain[];
+}
+export interface Generated {
+    wsbPath: string;
+    launchPath: string;
+    launchId: string;
+    sessionPath: string;
+    memoryMb: number;
+    mappings: ResolvedMapping[];
+    profile: ProfileResult;
+    databases: DatabasePlan[];
+    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". */
+export interface ProfileResult {
+    hostDir: string | null;
+    staged: string[];
+    skipped: string[];
+    credentials: boolean;
+    secretsRemoved: string[];
+}
+/** Written by the host to C:\AgentLaunch\session.json (read-only for the guest): everything the guest needs to know. */
+export interface GuestSession {
+    launchId: string;
+    project: string;
+    workspace: string;
+    workspaceHost: string;
+    harnessName: string;
+    harness: Harness | null;
+    harnessArguments: string[];
+    persistAgentState: boolean;
+    networking: boolean;
+    headless: boolean;
+    network: Config['network'];
+    provisioning: Config['provisioning'];
+    toolchains: Toolchains;
+    databases: DatabasePlan[];
+    versions: ToolVersions;
+    /** Every database `sbx-db start` can run later (older launch folders lack it). */
+    databaseCatalog?: DatabasePlan[];
+    attach: Config['attach'];
+    hooks: Config['hooks'];
+    /** 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: {
+        node: boolean;
+        nodeVersion: string | null;
+        harnessExecutable: string | null;
+        git: boolean;
+        nvm: boolean;
+        volta?: boolean;
+        pyenv?: boolean;
+    };
+    claudeProfile: {
+        overwrite: boolean;
+        items: string[];
+        credentials: boolean;
+        hostConfigDir: string | null;
+        syncClaudeMem: boolean;
+    };
+    personalization: boolean;
+    /** Drives other than C: that bootstrap.ps1 makes with subst before anything uses them: letter D-Z onto C:\Mirror\<letter>. */
+    substDrives?: {
+        letter: string;
+        target: string;
+    }[];
+}

package/dist/core/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/util.d.ts

@@ -0,0 +1,53 @@
+export declare const isWin: boolean;
+/** An expected problem the user can act on: what went wrong, and (optionally) how to fix it. */
+export declare class UserError extends Error {
+    readonly fix?: string | undefined;
+    constructor(message: string, fix?: string | undefined);
+}
+/** Throws a UserError. Typed explicitly so TypeScript narrows after calls (arrow functions need it to act as never). */
+export declare const fail: (message: string, fix?: string) => never;
+/**
+ * Parses JSON with comments and trailing commas (JSONC, like VS Code's settings.json). Errors name the file, line
+ * and column, and say what to fix.
+ */
+export declare const parseJsonc: <T>(text: string, source: string) => T;
+export declare const readJsonc: <T>(file: string) => T;
+export declare const errMsg: (e: unknown) => string;
+export declare const ensureDir: (p: string) => void;
+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;
+export declare const writeJson: (p: string, value: unknown) => void;
+export declare const realPath: (p: string) => string;
+export declare const xmlEscape: (v: string) => string;
+export declare const homeDir: () => string;
+export declare const sleep: (ms: number) => Promise<void>;
+/** Expands %VAR% and resolves relative paths against `base`. */
+export declare const expandPath: (input: string, base: string) => string;
+export declare const isRootPath: (p: string) => boolean;
+export declare const isUserProfile: (p: string) => boolean;
+export declare const isInsideOrEqual: (parent: string, child: string) => boolean;
+/**
+ * Text that came from the sandbox, made safe to print: control characters and escape sequences are removed except
+ * plain colours (SGR), so nothing written by the sandbox can drive your terminal (titles, clipboard, cursor tricks).
+ */
+export declare const safeText: (text: string) => string;
+export declare const findOnPath: (names: string[]) => string | null;
+/** True if `p` itself is a symlink or junction (lstat; never follows it). */
+export declare const isLink: (p: string) => boolean;
+/** Removes a symlink or junction itself (never its target). Junctions need rmdir on Windows. */
+export declare const removeLink: (p: string) => void;
+/**
+ * The sandbox can write anywhere in its data folder, so it could swap a folder for a junction that points at this
+ * PC's own disk. Before the host reads, writes or deletes anything under `root`, every existing path component from
+ * `root` down to `target` must be a plain folder/file. Throws otherwise.
+ */
+export declare const assertNoLinks: (root: string, target: string) => void;
+/** Runs a PowerShell script and returns its exit code (and stdout when `capture`). */
+export declare const runPowerShell: (script: string, capture?: boolean) => {
+    status: number;
+    stdout: 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

@@ -0,0 +1,145 @@
+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 { 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. */
+export class UserError extends Error {
+    fix;
+    constructor(message, fix) {
+        super(message);
+        this.fix = fix;
+        this.name = 'UserError';
+    }
+}
+/** Throws a UserError. Typed explicitly so TypeScript narrows after calls (arrow functions need it to act as never). */
+export const fail = (message, fix) => { throw new UserError(message, fix); };
+/**
+ * Parses JSON with comments and trailing commas (JSONC, like VS Code's settings.json). Errors name the file, line
+ * and column, and say what to fix.
+ */
+export const parseJsonc = (text, source) => {
+    const errors = [];
+    const value = parseJsoncText(text.replace(/^/, ''), errors, { allowTrailingComma: true, disallowComments: false });
+    if (errors.length) {
+        const { offset, error } = errors[0];
+        const before = text.slice(0, offset).split(/\r?\n/);
+        fail(source + ' is not valid JSON (line ' + before.length + ', column ' + (before[before.length - 1].length + 1) + ': ' + printParseErrorCode(error) + ').', 'Fix that spot in the file. Comments (// and /* */) and trailing commas are fine.');
+    }
+    return value;
+};
+export const readJsonc = (file) => parseJsonc(fs.readFileSync(file, 'utf8'), file);
+export const errMsg = (e) => e instanceof Error ? e.message : String(e);
+export const ensureDir = (p) => { fs.mkdirSync(p, { recursive: true }); };
+export const dirExists = (p) => { try {
+    return fs.statSync(p).isDirectory();
+}
+catch {
+    return false;
+} };
+export const fileExists = (p) => { try {
+    return fs.statSync(p).isFile();
+}
+catch {
+    return false;
+} };
+export const readJson = (p) => JSON.parse(fs.readFileSync(p, 'utf8').replace(/^\uFEFF/, ''));
+export const tryReadJson = (p) => { try {
+    return readJson(p);
+}
+catch {
+    return null;
+} };
+export const writeJson = (p, value) => { ensureDir(path.dirname(p)); fs.writeFileSync(p, JSON.stringify(value, null, 2) + '\n', 'utf8'); };
+export const realPath = (p) => { try {
+    return fs.realpathSync(p);
+}
+catch {
+    return p;
+} };
+export const xmlEscape = (v) => v.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+export const homeDir = () => process.env.USERPROFILE ?? os.homedir();
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** Expands %VAR% and resolves relative paths against `base`. */
+export const expandPath = (input, base) => {
+    const expanded = input.replace(/%([^%]+)%/g, (_m, name) => process.env[name] ?? '%' + name + '%').replace(/^~(?=$|[\\/])/, homeDir());
+    return path.resolve(path.isAbsolute(expanded) ? expanded : path.join(base, expanded));
+};
+export const isRootPath = (p) => { const n = path.resolve(p); return n.toLowerCase() === path.parse(n).root.toLowerCase(); };
+export const isUserProfile = (p) => { const profile = process.env.USERPROFILE ?? process.env.HOME ?? ''; return profile !== '' && path.resolve(p).toLowerCase() === path.resolve(profile).toLowerCase(); };
+export const isInsideOrEqual = (parent, child) => {
+    const rel = path.relative(path.resolve(parent).toLowerCase(), path.resolve(child).toLowerCase());
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+};
+/**
+ * Text that came from the sandbox, made safe to print: control characters and escape sequences are removed except
+ * plain colours (SGR), so nothing written by the sandbox can drive your terminal (titles, clipboard, cursor tricks).
+ */
+export const safeText = (text) => text.replace(/\x1b\[[0-9;]*m|\x1b(\[[0-9;?]*[ -\/]*[@-~]|\][^\x07\x1b]*(\x07|\x1b\\)|[@-Z\\-_])|[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, (m) => (/^\x1b\[[0-9;]*m$/.test(m) ? m : ''));
+export const findOnPath = (names) => {
+    const dirs = (process.env.PATH ?? process.env.Path ?? '').split(path.delimiter).filter((d) => d !== '');
+    for (const name of names)
+        for (const dir of dirs) {
+            const candidate = path.join(dir, name);
+            if (fileExists(candidate))
+                return candidate;
+        }
+    return null;
+};
+/** True if `p` itself is a symlink or junction (lstat; never follows it). */
+export const isLink = (p) => { try {
+    return fs.lstatSync(p).isSymbolicLink();
+}
+catch {
+    return false;
+} };
+/** Removes a symlink or junction itself (never its target). Junctions need rmdir on Windows. */
+export const removeLink = (p) => { try {
+    fs.unlinkSync(p);
+}
+catch {
+    fs.rmdirSync(p);
+} };
+/**
+ * The sandbox can write anywhere in its data folder, so it could swap a folder for a junction that points at this
+ * PC's own disk. Before the host reads, writes or deletes anything under `root`, every existing path component from
+ * `root` down to `target` must be a plain folder/file. Throws otherwise.
+ */
+export const assertNoLinks = (root, target) => {
+    const rel = path.relative(path.resolve(root), path.resolve(target));
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        fail('Refusing to touch ' + target + ': it is outside ' + root);
+    let current = path.resolve(root);
+    for (const part of ['', ...rel.split(path.sep).filter(Boolean)]) {
+        current = part ? path.join(current, part) : current;
+        if (isLink(current))
+            fail('Refusing to touch ' + target + ': ' + current + ' is a link (possible escape attempt from the sandbox).');
+    }
+};
+/**
+ * PowerShell arguments for a script passed encoded (no quoting issues, no progress-bar noise on stderr). Output is
+ * UTF-8: Windows PowerShell 5.1 otherwise writes redirected stdout in the OEM code page, mangling non-ASCII (regional
+ * date formats, wallpaper paths). UTF8Encoding($false): no byte-order mark in front of the output.
+ */
+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];
+};
+/** Runs a PowerShell script and returns its exit code (and stdout when `capture`). */
+export const runPowerShell = (script, capture = false) => {
+    const result = spawnSync(SYSTEM.powershell(), powerShellArgs(script), { stdio: capture ? ['ignore', 'pipe', 'inherit'] : 'inherit', encoding: 'utf8', windowsHide: true });
+    if (result.error)
+        throw result.error;
+    return { status: result.status ?? 1, stdout: 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 });
+    let out = '';
+    child.stdout.on('data', (d) => { out += d.toString('utf8'); });
+    child.on('error', reject);
+    child.on('close', () => resolve(out));
+});