windows-development-sandbox 1.0.5 → 1.1.0

package/dist/cli/settings/schema.js

@@ -0,0 +1,29 @@
+/** optional()/default() wrappers hide the real type. */
+export const unwrap = (s) => (['optional', 'default', 'nullable'].includes(s._zod.def.type) && s._zod.def.innerType ? unwrap(s._zod.def.innerType) : s);
+export const kind = (s) => unwrap(s)._zod.def.type;
+export const isSection = (s) => kind(s) === 'object' && Boolean(unwrap(s).shape);
+/** Settings not worth editing here (the schema link). */
+const HIDDEN = new Set(['$schema']);
+/** The settings one level below a section (or the top level), in schema order. */
+export const childrenOf = (schema) => Object.entries(unwrap(schema).shape ?? {}).filter(([name]) => !HIDDEN.has(name));
+/** The description, which `.partial()` and `.optional()` wrappers may carry on the inner schema instead. */
+export const describeSetting = (s) => s.description ?? unwrap(s).description;
+/** Every setting that is edited with a prompt of its own (everything that is not a section), with its path. */
+export const leavesOf = (schema, key = []) => childrenOf(schema).flatMap(([name, child]) => (isSection(child) ? leavesOf(child, [...key, name]) : [{ key: [...key, name], schema: child }]));
+/** Which prompt edits this setting. Lists of objects and maps (mappings, harnesses, environment) fall back to JSON. */
+export const promptKind = (schema) => {
+    const s = unwrap(schema);
+    const type = s._zod.def.type;
+    if (type === 'boolean' || type === 'enum' || type === 'union' || type === 'number' || type === 'string')
+        return type;
+    if (type === 'array' && s._zod.def.element && kind(s._zod.def.element) === 'string')
+        return 'string-list';
+    return 'json';
+};
+const JSON_EXAMPLES = {
+    harnesses: '{"mytool": {"npmPackage": "my-cli", "npmBin": "my-cli", "arguments": [], "environment": {}}}',
+    mappings: '[{"host": "C:\\\\data", "guest": "C:\\\\Data", "readOnly": true}]',
+    environment: '{"NPM_CONFIG_REGISTRY": "https://registry.example.com"}',
+};
+/** A one-line example of the JSON a setting expects, shown in its prompt. */
+export const jsonExample = (key, schema) => JSON_EXAMPLES[key[key.length - 1]] ?? (unwrap(schema)._zod.def.type === 'array' ? '["value", ...]' : '{"name": "value"}');

package/dist/cli/validate.d.ts

@@ -0,0 +1,17 @@
+import type { Context } from './commands/context.js';
+/** Edit distance, for "did you mean". */
+export declare const distance: (a: string, b: string) => number;
+/** The closest of `choices` to `input`, when it is close enough to be a typo. */
+export declare const closest: (input: string, choices: readonly string[]) => string | undefined;
+/** "Unknown agent "cluade". Did you mean claude?" with the valid values as the fix. */
+export declare const unknownValue: (what: string, input: string, choices: readonly string[], howToList: string) => never;
+/** Node: 22, 22.1, v22.1.0, lts, lts/*, lts/iron, latest, current, node. */
+export declare const validNodeSpec: (spec: string) => boolean;
+/** Python 3: 3, 3.12, 3.12.4. */
+export declare const validPythonSpec: (spec: string) => boolean;
+export declare const checkHarness: (name: string | undefined, harnesses: string[]) => void;
+export declare const PROJECT_ACTIONS: readonly ["list", "choose", "add", "remove", "include", "exclude", "all", "roots"];
+/** `sandbox projects <action> [value] [folder]`: the action, then what it needs. Pure (no file checks). */
+export declare const validateProjectsArgs: (args: string[]) => void;
+/** Fails with what is wrong and what is valid, before anything is started. */
+export declare const validateOptions: (ctx: Context) => void;

package/dist/cli/validate.js

@@ -0,0 +1,89 @@
+// Checks what the user typed before anything starts, so a typo fails at once with the list of valid values
+// instead of halfway into a sandbox boot. Pure helpers first, then validateOptions (the one call from the dispatcher).
+import fs from 'node:fs';
+import path from 'node:path';
+import { DATABASES } from '../core/detect-databases.js';
+import { fail } from '../core/util.js';
+import { listAccounts } from '../host/accounts.js';
+/** Edit distance, for "did you mean". */
+export const distance = (a, b) => {
+    let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i++) {
+        const next = [i];
+        for (let j = 1; j <= b.length; j++)
+            next[j] = Math.min(row[j] + 1, next[j - 1] + 1, row[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        row = next;
+    }
+    return row[b.length];
+};
+/** The closest of `choices` to `input`, when it is close enough to be a typo. */
+export const closest = (input, choices) => {
+    const best = choices.map((c) => ({ c, d: distance(input.toLowerCase(), c.toLowerCase()) })).sort((x, y) => x.d - y.d)[0];
+    return best && best.d <= Math.max(2, Math.floor(input.length / 3)) ? best.c : undefined;
+};
+/** "Unknown agent "cluade". Did you mean claude?" with the valid values as the fix. */
+export const unknownValue = (what, input, choices, howToList) => {
+    const hint = closest(input, choices);
+    return fail('Unknown ' + what + ' "' + input + '".' + (hint ? ' Did you mean ' + hint + '?' : ''), (choices.length ? 'Choose one of: ' + choices.join(', ') + '. ' : '') + howToList);
+};
+/** Node: 22, 22.1, v22.1.0, lts, lts/*, lts/iron, latest, current, node. */
+export const validNodeSpec = (spec) => /^(v?\d+(\.\d+){0,2}|node|latest|current|stable|lts(\/(\*|[a-z]+))?)$/i.test(spec.trim());
+/** Python 3: 3, 3.12, 3.12.4. */
+export const validPythonSpec = (spec) => /^v?3(\.\d+){0,2}$/.test(spec.trim());
+export const checkHarness = (name, harnesses) => {
+    if (name !== undefined && !harnesses.includes(name))
+        unknownValue('agent', name, harnesses, 'Add your own under "harnesses" in your settings (sandbox config).');
+};
+/** Commands that read these options; checked only for them (restart/doctor take --harness too). */
+const LAUNCHING = new Set(['launch', 'generate', 'host-claude']);
+export const PROJECT_ACTIONS = ['list', 'choose', 'add', 'remove', 'include', 'exclude', 'all', 'roots'];
+/** `sandbox projects <action> [value] [folder]`: the action, then what it needs. Pure (no file checks). */
+export const validateProjectsArgs = (args) => {
+    const [action = 'list', value, folder] = args;
+    if (!PROJECT_ACTIONS.includes(action))
+        unknownValue('projects action', action, PROJECT_ACTIONS, 'sandbox projects with no action lists your projects.');
+    if (['add', 'remove', 'include', 'exclude'].includes(action) && !value)
+        fail('Which folder?', 'Usage: sandbox projects ' + action + ' <folder>   (. = this folder)');
+    if (action === 'all' && value !== undefined && !['on', 'off'].includes(value))
+        unknownValue('value for projects all', value, ['on', 'off'], 'sandbox projects all on|off');
+    if (action === 'roots' && value !== undefined && !['list', 'add', 'remove'].includes(value))
+        unknownValue('projects roots action', value, ['list', 'add', 'remove'], 'sandbox projects roots add|remove <folder>');
+    if (action === 'roots' && (value === 'add' || value === 'remove') && !folder)
+        fail('Which folder?', 'Usage: sandbox projects roots ' + value + ' <folder>');
+};
+/** Fails with what is wrong and what is valid, before anything is started. */
+export const validateOptions = (ctx) => {
+    const o = ctx.options;
+    const harnesses = Object.keys(ctx.loaded.config.harnesses);
+    if (['launch', 'generate', 'restart', 'doctor'].includes(o.command))
+        checkHarness(o.harness, harnesses);
+    if (o.command === 'projects')
+        validateProjectsArgs(o.positionals);
+    if (!LAUNCHING.has(o.command))
+        return;
+    if (o.node !== undefined && !validNodeSpec(o.node))
+        fail('"' + o.node + '" is not a Node version.', 'Use a number like 22 or 22.11.0, or lts, latest.');
+    if (o.python !== undefined && !validPythonSpec(o.python))
+        fail('"' + o.python + '" is not a Python 3 version.', 'Use 3, 3.12 or 3.12.4.');
+    for (const db of o.databases.flatMap((d) => d.split(',')).map((d) => d.trim()).filter(Boolean)) {
+        if (!DATABASES.includes(db))
+            unknownValue('database', db, DATABASES, 'Repeat --database for several.');
+    }
+    if (o.account !== undefined) {
+        const names = listAccounts(ctx.storageRoot, ctx.dataPath).map((a) => a.name);
+        if (!names.includes(o.account))
+            unknownValue('account', o.account, names, names.length ? 'See them with: sandbox account list' : 'None saved yet: sign in inside the sandbox, then run sandbox account save <name>.');
+    }
+    for (const s of o.sessions) {
+        checkHarness(s.harness, harnesses);
+        if (!fs.existsSync(s.folder) || !fs.statSync(s.folder).isDirectory())
+            fail('The folder ' + s.folder + ' (--session ' + s.harness + '@...) does not exist.', 'Check the path after the @.');
+    }
+    if (o.sessions.length && (o.harness !== undefined || o.workspace !== undefined))
+        fail('--session names the agent and folder of each session, so --harness and --workspace do not apply.', 'Use only --session <agent>@<folder> (repeatable).');
+    if (o.workspace !== undefined && !fs.existsSync(path.resolve(o.workspace)))
+        fail('The folder ' + path.resolve(o.workspace) + ' does not exist.', 'Check the --workspace path (or leave it out to use the current folder).');
+    for (const script of o.scripts)
+        if (!fs.existsSync(path.resolve(script)))
+            fail('The script ' + path.resolve(script) + ' does not exist.', 'Check the --script path.');
+};

package/dist/core/config.js

@@ -9,10 +9,11 @@ export const DEFAULTS = {
     guestWorkspace: 'auto',
     readOnly: false,
     mappings: [],
-    sandbox: { memoryMb: 'auto', maxMemoryMb: 32768, reserveHostMb: 8192, vGpu: false, networking: true, clipboard: true, audioInput: false, videoInput: false, printerRedirection: false, protectedClient: true, headless: false },
+    sandbox: { memoryMb: 'auto', maxMemoryMb: 32768, maxMemoryPercent: 80, cpuLimit: 80, reserveHostMb: 8192, vGpu: false, networking: true, clipboard: true, audioInput: false, videoInput: false, printerRedirection: false, protectedClient: true, headless: false },
     storage: { root: '%LOCALAPPDATA%\\AgentSandbox', persistAgentState: true, dataName: 'default' },
     network: { blockPrivateRanges: true },
     provisioning: { copyFromHost: true, fallbackToInstall: true, refresh: false, git: { enabled: true, access: 'full' }, terminal: { enabled: true } },
+    downloads: { requireChecksum: false },
     toolchains: {
         node: { version: 'host', extraVersions: [], corepack: true, volta: 'auto', globalPackages: [] },
         python: { enabled: 'auto', version: '3', python2: true, pyenv: 'auto', tools: [] },
@@ -44,6 +45,7 @@ export const DEFAULTS = {
         sqlserver: { enabled: 'auto' },
     },
     attach: { enabled: true, reuseSession: true, auto: false, autoHide: false },
+    agentCommands: { enabled: false, agents: 'auto' },
     secrets: { strip: true, allow: [], patterns: [], warnFiles: true },
     personalization: { enabled: true },
     claudeProfile: { enabled: true, hostDir: 'auto', include: ['settings.json', 'CLAUDE.md', 'commands', 'agents', 'skills', 'plugins'], globalStateFile: 'auto', copyCredentials: false, overwrite: true, syncHistory: true, syncClaudeMem: true },
@@ -67,6 +69,7 @@ export const DEFAULTS = {
         aider: { uvPackage: 'aider-chat', uvBin: 'aider', arguments: [], environment: {}, resumeArguments: ['--restore-chat-history'] },
     },
     hooks: { failFast: false },
+    projects: { all: false, exclude: [], roots: [], askToAddRoot: true, declinedRoots: [], wsbShare: true },
 };
 /** Per-user folder for config and hooks. Survives reinstalling the npm package. */
 export const userDir = () => process.env.AGENT_SANDBOX_HOME ?? path.join(homeDir(), '.agent-sandbox');

package/dist/core/disk.d.ts

@@ -0,0 +1,16 @@
+export declare const GB: number;
+/** 1536 -> "1.5 KB". */
+export declare const humanBytes: (bytes: number) => string;
+/** Size on disk, never following links or junctions (a link counts as 0, so a planted junction cannot make us walk this PC's disk). */
+export declare const sizeOf: (p: string) => number;
+/** Free bytes on the drive that holds `dir` (which may not exist yet: the nearest existing parent is asked); null if unknown. */
+export declare const freeBytesAt: (dir: string) => number | null;
+export interface DiskUsage {
+    drive: string;
+    totalBytes: number;
+    freeBytes: number;
+    usedBytes: number;
+    holdsStorage: boolean;
+}
+/** Every local drive's size and free space, and which one holds the sandbox storage. */
+export declare const diskUsage: (storageRoot: string) => DiskUsage[];

package/dist/core/disk.js

@@ -0,0 +1,55 @@
+// Sizes and free space on disk, shared by `data`, `repair`, `setup` and the storage cleanup.
+import fs from 'node:fs';
+import path from 'node:path';
+import _ from 'lodash';
+export const GB = 1024 ** 3;
+/** 1536 -> "1.5 KB". */
+export const humanBytes = (bytes) => {
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = bytes <= 0 ? 0 : Math.min(units.length - 1, Math.floor(Math.log(bytes) / Math.log(1024)));
+    const value = bytes / 1024 ** i;
+    return (i === 0 ? String(bytes) : value.toFixed(value < 10 ? 1 : 0)) + ' ' + units[i];
+};
+/** Size on disk, never following links or junctions (a link counts as 0, so a planted junction cannot make us walk this PC's disk). */
+export const sizeOf = (p) => {
+    try {
+        const stat = fs.lstatSync(p);
+        if (stat.isSymbolicLink())
+            return 0;
+        if (!stat.isDirectory())
+            return stat.size;
+        return _.sumBy(fs.readdirSync(p, { withFileTypes: true }), (d) => (d.isSymbolicLink() ? 0 : sizeOf(path.join(p, d.name))));
+    }
+    catch {
+        return 0;
+    }
+};
+/** Free bytes on the drive that holds `dir` (which may not exist yet: the nearest existing parent is asked); null if unknown. */
+export const freeBytesAt = (dir) => {
+    let at = path.resolve(dir);
+    while (!fs.existsSync(at) && path.dirname(at) !== at)
+        at = path.dirname(at);
+    try {
+        const s = fs.statfsSync(at);
+        return s.bavail * s.bsize;
+    }
+    catch {
+        return null;
+    }
+};
+/** Every local drive's size and free space, and which one holds the sandbox storage. */
+export const diskUsage = (storageRoot) => {
+    const storageDrive = path.parse(path.resolve(storageRoot)).root.toUpperCase();
+    return 'CDEFGHIJKLMNOPQRSTUVWXYZ'.split('').map((letter) => letter + ':\\').flatMap((drive) => {
+        try {
+            const s = fs.statfsSync(drive);
+            const totalBytes = s.blocks * s.bsize;
+            if (!totalBytes)
+                return [];
+            return [{ drive, totalBytes, freeBytes: s.bavail * s.bsize, usedBytes: totalBytes - s.bfree * s.bsize, holdsStorage: drive.toUpperCase() === storageDrive }];
+        }
+        catch {
+            return [];
+        }
+    });
+};

package/dist/core/local-config.d.ts

@@ -2,6 +2,14 @@ import type { Config, LocalConfigFile, Overrides } from './types.js';
 export declare const LOCAL_CONFIG_NAME = ".sandbox-config.json";
 /** Validates a folder's settings and resolves its relative paths against that folder. */
 export declare const normalizeOverrides: (data: unknown, dir: string, source: string) => Overrides;
+/**
+ * Protections a project file may only make stricter, never looser. A repo can ship the file, so it must not be able to
+ * switch off what you turned on (or turn on what you turned off). The strictest of the two values always wins.
+ */
+export declare const ON_IS_SAFER: string[];
+export declare const OFF_IS_SAFER: string[];
+export declare const GIT_STRICTNESS: Record<string, number>;
+export declare const NEVER_LOOSER: string[];
 /** Applies validated overrides. Mappings with the same guest folder replace the configured ones. */
 export declare const applyOverrides: (config: Config, ov: Overrides) => Config;
 /** Human-readable list of what a local config changes, with risky items flagged. */

package/dist/core/local-config.js

@@ -20,10 +20,25 @@ export const normalizeOverrides = (data, dir, source) => {
         fail(source + ' is not valid:\n  - scripts: file not found: ' + missing.join(', '));
     return { ...overrides, scripts, mappings: overrides.mappings?.map((m) => ({ ...m, host: expandPath(m.host, dir) })) };
 };
+/**
+ * Protections a project file may only make stricter, never looser. A repo can ship the file, so it must not be able to
+ * switch off what you turned on (or turn on what you turned off). The strictest of the two values always wins.
+ */
+export const ON_IS_SAFER = ['readOnly', 'network.blockPrivateRanges', 'sandbox.protectedClient', 'downloads.requireChecksum'];
+export const OFF_IS_SAFER = ['sandbox.networking', 'sandbox.clipboard', 'sandbox.audioInput', 'sandbox.videoInput', 'sandbox.printerRedirection', 'sandbox.vGpu', 'claudeProfile.copyCredentials'];
+export const GIT_STRICTNESS = { full: 0, readonly: 1, none: 2 };
+export const NEVER_LOOSER = [...ON_IS_SAFER, ...OFF_IS_SAFER, 'provisioning.git.access'];
+const keepStrictest = (yours, merged) => {
+    ON_IS_SAFER.forEach((p) => _.set(merged, p, Boolean(_.get(yours, p)) || Boolean(_.get(merged, p))));
+    OFF_IS_SAFER.forEach((p) => _.set(merged, p, Boolean(_.get(yours, p)) && Boolean(_.get(merged, p))));
+    if (GIT_STRICTNESS[yours.provisioning.git.access] > GIT_STRICTNESS[merged.provisioning.git.access])
+        merged.provisioning.git.access = yours.provisioning.git.access;
+};
 /** Applies validated overrides. Mappings with the same guest folder replace the configured ones. */
 export const applyOverrides = (config, ov) => {
     const { harness, mappings, scripts: _scripts, $schema: _schema, ...rest } = ov;
     const next = mergeConfig(config, rest);
+    keepStrictest(config, next);
     if (harness)
         next.defaultHarness = harness;
     if (mappings)
@@ -41,13 +56,11 @@ export const describeOverrides = (ov) => {
         ...flatten(sections),
     ];
     const risky = _.compact([
-        ov.claudeProfile?.copyCredentials === true && 'claudeProfile.copyCredentials = true copies your Claude LOGIN into the sandbox',
-        ov.network?.blockPrivateRanges === false && 'network.blockPrivateRanges = false turns OFF the LAN block',
         mappings.some((m) => !m.readOnly) && 'a READ/WRITE mapping lets the agent change files outside your workspace',
-        ov.provisioning?.git?.access === 'full' && 'provisioning.git.access = full lets the agent commit and push',
-        ov.sandbox?.vGpu === true && 'sandbox.vGpu = true widens the sandbox attack surface',
     ]);
-    return [...lines, ...risky.map((r) => '!! ' + r)];
+    // These are only used when they are stricter than your own settings, so a project can never loosen them.
+    const limited = NEVER_LOOSER.filter((p) => _.has(sections, p)).map((p) => p + ' is only used if it is stricter than your own setting');
+    return [...lines, ...risky.map((r) => '!! ' + r), ...limited.map((r) => '   ' + r)];
 };
 export const readLocalConfig = (dir) => {
     const file = path.join(dir, LOCAL_CONFIG_NAME);

package/dist/core/project-policy.d.ts

@@ -0,0 +1,15 @@
+import type { Config } from './types.js';
+/** The protections of a running sandbox, by setting path (`sandbox.networking`, `provisioning.git.access`, ...). */
+export type Protections = Record<string, boolean | string>;
+export declare const protectionsOf: (config: Config) => Protections;
+export interface JoinCheck {
+    /** Settings this project needs stricter than the running sandbox: the launch is refused. */
+    stricter: string[];
+    /** Settings it would have looser: it gets the sandbox's (stricter) value; shown as a note. */
+    looser: string[];
+}
+/**
+ * Compares a project's effective protections with the running sandbox's. Hub projects are always read/write
+ * (Windows Sandbox maps the hub once, read/write), so a read-only project counts as stricter.
+ */
+export declare const checkJoin: (running: Protections, wanted: Protections) => JoinCheck;

package/dist/core/project-policy.js

@@ -0,0 +1,35 @@
+// Joining a running sandbox from another project. Its protections (network, LAN block, git access, clipboard, the
+// .wsb device settings, read-only) are machine-wide: they were fixed when the sandbox booted for the first project.
+// A second project may never loosen them, and a project that needs a STRICTER setting than the running sandbox has
+// cannot get it there without changing it for the sessions already running, so that launch is refused with a clear
+// message. A project asking for less than the sandbox has simply runs with the sandbox's (stricter) setting.
+// Pure: the host checks it before registering a project, the tests drive it directly.
+import _ from 'lodash';
+import { GIT_STRICTNESS, NEVER_LOOSER, OFF_IS_SAFER, ON_IS_SAFER } from './local-config.js';
+export const protectionsOf = (config) => Object.fromEntries(NEVER_LOOSER.map((p) => [p, _.get(config, p)]));
+/** 1 = `wanted` is stricter than `running`, -1 = looser, 0 = the same. */
+const compare = (setting, running, wanted) => {
+    if (setting === 'provisioning.git.access')
+        return Math.sign((GIT_STRICTNESS[String(wanted)] ?? 0) - (GIT_STRICTNESS[String(running)] ?? 0));
+    if (ON_IS_SAFER.includes(setting))
+        return Number(Boolean(wanted)) - Number(Boolean(running));
+    if (OFF_IS_SAFER.includes(setting))
+        return Number(Boolean(running)) - Number(Boolean(wanted));
+    return 0;
+};
+/**
+ * Compares a project's effective protections with the running sandbox's. Hub projects are always read/write
+ * (Windows Sandbox maps the hub once, read/write), so a read-only project counts as stricter.
+ */
+export const checkJoin = (running, wanted) => {
+    const stricter = [];
+    const looser = [];
+    for (const setting of NEVER_LOOSER) {
+        const result = compare(setting, setting === 'readOnly' ? false : running[setting], wanted[setting]);
+        if (result > 0)
+            stricter.push(setting + ' = ' + JSON.stringify(wanted[setting]) + ' (the running sandbox has ' + JSON.stringify(setting === 'readOnly' ? false : running[setting]) + ')');
+        if (result < 0)
+            looser.push(setting + ' stays ' + JSON.stringify(running[setting]));
+    }
+    return { stricter, looser };
+};

package/dist/core/prompt.d.ts

@@ -0,0 +1,4 @@
+/** A yes/no question (default no). */
+export declare const askYesNo: (question: string, defaultYes?: boolean) => Promise<boolean>;
+/** Asks the user to type `expected` (a stronger confirmation than yes/no). */
+export declare const askTyped: (question: string, expected: string) => Promise<boolean>;

package/dist/core/prompt.js

@@ -0,0 +1,15 @@
+// Questions asked on the terminal, all through @inquirer/prompts. Without an interactive terminal the answer is always "no".
+import { confirm, input } from '@inquirer/prompts';
+/** A yes/no question (default no). */
+export const askYesNo = async (question, defaultYes = false) => {
+    if (!process.stdin.isTTY)
+        return false;
+    return confirm({ message: question, default: defaultYes });
+};
+/** Asks the user to type `expected` (a stronger confirmation than yes/no). */
+export const askTyped = async (question, expected) => {
+    if (!process.stdin.isTTY)
+        return false;
+    const answer = await input({ message: question + ' Type "' + expected + '" to confirm:' });
+    return answer.trim().toLowerCase() === expected;
+};

package/dist/core/safe-paths.d.ts

@@ -0,0 +1,4 @@
+/** 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;

package/dist/core/safe-paths.js

@@ -0,0 +1,37 @@
+// Which folders may be shared with the sandbox. The agent gets read/write access to what is mapped, so nothing that
+// would let it reach this tool, its storage, your settings or the OS may be mapped.
+import { userDir } from './config.js';
+import { fail, isInsideOrEqual, isRootPath, isUserProfile } from './util.js';
+/** 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', 'SystemRoot', '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.');
+    }
+};

package/dist/core/schema/common.d.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod';
+export declare const GuestPath: z.ZodString;
+export declare const Name: z.ZodString;
+export declare const Strings: z.ZodArray<z.ZodString>;
+export declare const toggle: (description: string) => z.ZodObject<{
+    enabled: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const SchemaRef: z.ZodString;
+export declare const GitAccess: z.ZodEnum<{
+    readonly: "readonly";
+    full: "full";
+    none: "none";
+}>;
+/** true, false, or "auto": only when the project uses it (found from files like go.mod in the workspace or one level down). */
+export declare const Enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+export declare const enabled: (what: string, markers: string) => z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+export declare const Packages: (what: string, example: string) => z.ZodArray<z.ZodString>;

package/dist/core/schema/common.js

@@ -0,0 +1,15 @@
+// Building blocks shared by the settings schemas.
+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:)');
+export const Name = z.string().regex(/^[A-Za-z0-9_-]+$/, 'letters, numbers, - and _ only');
+export const Strings = z.array(z.string());
+export const toggle = (description) => z.strictObject({ enabled: z.boolean().describe(description) });
+export 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.');
+/** 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')]);
+export const enabled = (what, markers) => Enabled.describe(what + ' true, false, or "auto" = only when the project has ' + markers + '.');
+export const Packages = (what, example) => Strings.describe(what + ', installed once and kept (e.g. ' + example + ').');