windows-development-sandbox 1.4.0 → 1.4.3

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

@@ -0,0 +1,13 @@
+export declare const trustStorePath: (storageRoot: string) => string;
+export declare const isTrusted: (store: string, file: string, hash: string) => boolean;
+export declare const saveTrust: (store: string, file: string, hash: string) => void;
+export declare const allowStorePath: (storageRoot: string) => string;
+/** true = you allowed it, false = you said no (not asked again), null = not asked yet. */
+export declare const allowedAnswer: (store: string, file: string, setting: string, value: unknown) => boolean | null;
+export declare const saveAllowed: (store: string, file: string, setting: string, value: unknown, allow: boolean) => void;
+/** Answers for folders outside the project are kept with the others, one per folder (and read-only or not). */
+export declare const OUTSIDE_FOLDER = "folder outside the project";
+export declare function outsideKey(m: {
+    host: string;
+    readOnly: boolean;
+}): string;

package/dist/core/local-config/trust.js

@@ -0,0 +1,43 @@
+import path from 'node:path';
+import _ from 'lodash';
+import { z } from 'zod';
+import { tryReadJson, writeJson } from '../util/index.js';
+// ---- approvals (host-only: <storage>\trusted-configs.json) ----------------------------------------------------------
+export const trustStorePath = (storageRoot) => path.join(storageRoot, 'trusted-configs.json');
+const loadTrust = (store) => tryReadJson(store) ?? {};
+const key = (file) => path.resolve(file).toLowerCase();
+export const isTrusted = (store, file, hash) => loadTrust(store)[key(file)] === hash;
+export const saveTrust = (store, file, hash) => writeJson(store, { ...loadTrust(store), [key(file)]: hash });
+// ---- looser settings you allowed for one project (host-only: <storage>\allowed-requests.json) ----------------------
+// A project file can never loosen a protection by itself. When it asks, you are asked once (interactively); a "yes"
+// is kept here, per project file and per "setting = value", so only that value is ever let through for that project.
+export const allowStorePath = (storageRoot) => path.join(storageRoot, 'allowed-requests.json');
+const loadAllowed = (store) => {
+    const parsed = z
+        .record(z.string(), z.array(z.string().max(2000)).max(500))
+        .safeParse(tryReadJson(store) ?? {});
+    return parsed.success ? parsed.data : {};
+};
+const allowKey = (setting, value) => setting + ' = ' + JSON.stringify(value);
+/** true = you allowed it, false = you said no (not asked again), null = not asked yet. */
+export const allowedAnswer = (store, file, setting, value) => {
+    const answers = loadAllowed(store)[key(file)] ?? [];
+    return answers.includes(allowKey(setting, value))
+        ? true
+        : answers.includes('no: ' + allowKey(setting, value))
+            ? false
+            : null;
+};
+export const saveAllowed = (store, file, setting, value, allow) => {
+    const all = loadAllowed(store);
+    const entry = allowKey(setting, value);
+    writeJson(store, {
+        ...all,
+        [key(file)]: _.union(_.without(all[key(file)] ?? [], entry, 'no: ' + entry), [(allow ? '' : 'no: ') + entry]),
+    });
+};
+/** Answers for folders outside the project are kept with the others, one per folder (and read-only or not). */
+export const OUTSIDE_FOLDER = 'folder outside the project';
+export function outsideKey(m) {
+    return (m.readOnly ? 'read-only ' : 'read/write ') + path.resolve(m.host).toLowerCase();
+}

package/dist/core/package-info.d.ts

@@ -0,0 +1,4 @@
+/** The package folder (the one with package.json, dist/, sandbox/ and schemas/). */
+export declare const PACKAGE_ROOT: string;
+/** This package's version. */
+export declare const packageVersion: () => string;

package/dist/core/package-info.js

@@ -0,0 +1,13 @@
+// Where this package is installed and its version. This file is dist/core/package-info.js, two folders below
+// package.json.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import { tryReadJson } from './util/index.js';
+/** The package folder (the one with package.json, dist/, sandbox/ and schemas/). */
+export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+/** This package's version. */
+export const packageVersion = () => {
+    const file = path.join(PACKAGE_ROOT, 'package.json');
+    return z.object({ version: z.string() }).safeParse(tryReadJson(file)).data?.version ?? 'unknown';
+};

package/dist/core/run/guest-workspace.d.ts

@@ -0,0 +1,23 @@
+import type { Config, Mapping } from '../types.js';
+/** 'auto' guest workspace: C:\Workspace\<folder name> (shared/paths/projects.ts, where every project's place is decided). */
+export declare const autoGuestWorkspace: (hostDir: string) => string;
+/**
+ * A launch folder inside a project root appears under the root's folder (C:\Projects\<root>\<name>, or its PC path
+ * with "mirror"), where it also is when another project started the sandbox, so git worktrees and Claude's project
+ * folders keep working whichever project starts it. Only for "auto" / "mirror"; a filtered or read-only workspace
+ * keeps its own mapping (the root would show the folder unfiltered and writable at that place).
+ */
+export declare function placeInRoot(config: Config, workspaceHost: string, mirror: boolean, notes: string[]): Config;
+/** Where the workspace appears: guestWorkspace "auto", "mirror" (with a note when it falls back) or a path. */
+export declare function guestWorkspaceOf(config: Pick<Config, 'guestWorkspace'>, workspaceHost: string): {
+    guest: string;
+    note: string | null;
+};
+/**
+ * Where a mapping will most likely appear, before the launch knows every other folder (the prompt and config check
+ * show it; the launch places it for real in host/launch/mappings.ts with the same rules).
+ */
+export declare function previewGuest(m: Pick<Mapping, 'host' | 'guest'>, workspaceHost: string, workspaceGuest: string): {
+    guest: string;
+    note: string | null;
+};

package/dist/core/run/guest-workspace.js

@@ -0,0 +1,47 @@
+import { autoGuestFolder, deriveGuest, guestConflict, guestFix, planMirrorWorkspace, PROJECTS_GUEST, rootGuestDir, tidyGuestPath, usableRoots, } from '../../shared/paths/index.js';
+import { dirExists, isInsideOrEqual } from '../util/index.js';
+/** 'auto' guest workspace: C:\Workspace\<folder name> (shared/paths/projects.ts, where every project's place is decided). */
+export const autoGuestWorkspace = autoGuestFolder;
+/**
+ * A launch folder inside a project root appears under the root's folder (C:\Projects\<root>\<name>, or its PC path
+ * with "mirror"), where it also is when another project started the sandbox, so git worktrees and Claude's project
+ * folders keep working whichever project starts it. Only for "auto" / "mirror"; a filtered or read-only workspace
+ * keeps its own mapping (the root would show the folder unfiltered and writable at that place).
+ */
+export function placeInRoot(config, workspaceHost, mirror, notes) {
+    const guest = rootGuestDir(usableRoots(config.projects.roots, dirExists), mirror, workspaceHost);
+    if (!guest)
+        return config;
+    if (config.workspaceFilter.enabled || config.readOnly) {
+        notes.push(workspaceHost +
+            ' is inside a project root, but ' +
+            (config.readOnly ? 'readOnly' : 'workspaceFilter') +
+            ' is on, so it is mapped on its own at ' +
+            config.guestWorkspace +
+            ' (when another project starts the sandbox it is at ' +
+            guest +
+            ').');
+        return config;
+    }
+    return { ...config, guestWorkspace: guest };
+}
+/** Where the workspace appears: guestWorkspace "auto", "mirror" (with a note when it falls back) or a path. */
+export function guestWorkspaceOf(config, workspaceHost) {
+    if (config.guestWorkspace === 'auto')
+        return { guest: autoGuestWorkspace(workspaceHost), note: null };
+    if (config.guestWorkspace === 'mirror')
+        return planMirrorWorkspace(workspaceHost, autoGuestWorkspace(workspaceHost));
+    return { guest: config.guestWorkspace, note: null };
+}
+/**
+ * Where a mapping will most likely appear, before the launch knows every other folder (the prompt and config check
+ * show it; the launch places it for real in host/launch/mappings.ts with the same rules).
+ */
+export function previewGuest(m, workspaceHost, workspaceGuest) {
+    const guest = tidyGuestPath(m.guest ?? deriveGuest(m.host, workspaceHost, workspaceGuest));
+    const conflict = guestConflict(guest, [
+        ...(m.guest || !isInsideOrEqual(workspaceHost, m.host) ? [{ guest: workspaceGuest, what: 'the project' }] : []),
+        { guest: PROJECTS_GUEST, what: 'other projects' },
+    ]);
+    return { guest, note: conflict ? m.host + ': ' + conflict + '. Fix: ' + guestFix(m.guest) : null };
+}

package/dist/core/run/index.d.ts

@@ -0,0 +1,3 @@
+export { autoGuestWorkspace, placeInRoot, guestWorkspaceOf, previewGuest } from './guest-workspace.js';
+export { voltaNode, resolveVersions } from './versions.js';
+export { resolveRun } from './resolve-run.js';

package/dist/core/run/index.js

@@ -0,0 +1,3 @@
+export { autoGuestWorkspace, placeInRoot, guestWorkspaceOf, previewGuest } from './guest-workspace.js';
+export { voltaNode, resolveVersions } from './versions.js';
+export { resolveRun } from './resolve-run.js';

package/dist/core/run/resolve-run.d.ts

@@ -0,0 +1,3 @@
+import type { ResolvedRun, RunRequest } from '../types.js';
+/** Precedence (lowest to highest): built-in defaults, user config, .sandbox-config.json in the workspace, command-line flags. */
+export declare const resolveRun: (req: RunRequest, hostNodeVersion?: string) => Promise<ResolvedRun>;

package/dist/core/run/resolve-run.js

@@ -0,0 +1,202 @@
+import path from 'node:path';
+import { DATABASES } from '../detect/index.js';
+import { allowedAnswer, allowRequests, allowStorePath, applyOverrides, describeOverrides, isTrusted, LOCAL_CONFIG_NAME, loosenedRequests, normalizeOverrides, OUTSIDE_FOLDER, outsideKey, outsideMappings, readLocalConfig, saveAllowed, saveTrust, trustStorePath, } from '../local-config/index.js';
+import { assertSafeWorkspace } from '../safe-paths.js';
+import { dirExists, expandPath, fail, plainText } from '../util/index.js';
+import { guestWorkspaceOf, placeInRoot, previewGuest } from './guest-workspace.js';
+import { resolveVersions } from './versions.js';
+/** Precedence (lowest to highest): built-in defaults, user config, .sandbox-config.json in the workspace, command-line flags. */
+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.
+    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))
+        fail('The workspace folder does not exist: ' + workspaceHost, 'Check the --workspace path, or cd into the project first.');
+    assertSafeWorkspace(workspaceHost, req.packageRoot, storageRoot);
+    const scripts = [];
+    let localConfigPath = null;
+    let overrides = {};
+    const local = req.noLocalConfig ? null : readLocalConfig(workspaceHost);
+    let outsideAllowed = [];
+    if (local) {
+        overrides = normalizeOverrides(local.data, workspaceHost, local.path);
+        const store = trustStorePath(storageRoot);
+        if (!isTrusted(store, local.path, local.hash)) {
+            const summary = describeOverrides(overrides, workspaceHost);
+            let trusted = req.trustConfig;
+            if (!trusted && req.ask) {
+                console.log('\nFound ' + local.path + ' which is not trusted yet. It would apply:');
+                for (const line of summary)
+                    console.log('  ' + plainText(line));
+                trusted = await req.ask('Trust and use this file?');
+            }
+            if (!trusted)
+                fail(local.path +
+                    ' has not been approved yet (a repo can ship this file, so it needs your OK). It would apply:\n  ' +
+                    (summary.map(plainText).join('\n  ') || '(no changes)'), 'Review it, then run again in an interactive terminal and answer y, or add --trust-config. To ignore the file: --no-local-config');
+            saveTrust(store, local.path, local.hash);
+            notes.push('Trusted ' + local.path + ' (you will only be asked again if the file changes).');
+        }
+        const requests = await projectFileRequests(req, config, overrides, local.path, workspaceHost, storageRoot, notes);
+        const allowed = requests.allowed;
+        outsideAllowed = requests.outside;
+        config = applyOverrides(allowRequests(config, allowed), overrides);
+        scripts.push(...(overrides.scripts ?? []));
+        localConfigPath = local.path;
+        notes.push('Using ' + local.path);
+    }
+    if (req.headless !== undefined)
+        config = { ...config, sandbox: { ...config.sandbox, headless: req.headless } };
+    for (const name of req.databases ?? []) {
+        const db = name.toLowerCase();
+        if (!DATABASES.includes(db))
+            fail('Unknown database "' + name + '".', 'Choose from: ' + DATABASES.join(', '));
+        config = { ...config, databases: { ...config.databases, [db]: { ...config.databases[db], enabled: true } } };
+    }
+    // auto / mirror: a project inside a root is where the root shows it, whichever project starts the sandbox.
+    const guest = guestWorkspaceOf(config, workspaceHost);
+    const placed = config.guestWorkspace === 'auto' || mirror
+        ? placeInRoot({ ...config, guestWorkspace: guest.guest }, workspaceHost, mirror, notes)
+        : { ...config, guestWorkspace: guest.guest };
+    if (guest.note && placed.guestWorkspace === guest.guest)
+        notes.push(guest.note);
+    config = placed;
+    scripts.push(...req.scripts.map((s) => path.resolve(s)));
+    const harnessName = req.noAgent ? 'none' : (req.harness ?? config.defaultHarness);
+    if (harnessName !== 'none' && !config.harnesses[harnessName])
+        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);
+    // 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,
+        outsideMappings: outsideAllowed,
+    };
+};
+/**
+ * A project may only tighten. What it asks for beyond that (a looser setting, a folder outside the project) is used
+ * only if you allowed it for this project: asked once, in one question, at an interactive launch, never by
+ * --trust-config. Folders outside the project follow projects.allowOutsideMappings (your settings only). A looser
+ * setting you did not allow is named in the notes instead of dropped silently.
+ */
+async function projectFileRequests(req, config, overrides, localPath, workspaceHost, storageRoot, notes) {
+    const allowStore = allowStorePath(storageRoot);
+    const policy = config.projects.allowOutsideMappings;
+    // An optional folder that is not on this PC is skipped at launch, so it needs no answer (yet).
+    const outside = outsideMappings(workspaceHost, overrides.mappings).filter((m) => !m.optional || dirExists(m.host));
+    const name = path.basename(workspaceHost) + "'s " + LOCAL_CONFIG_NAME;
+    const preview = guestWorkspaceOf(applyOverrides(config, overrides), workspaceHost).guest;
+    const describe = (m) => (m.readOnly ? 'read-only  ' : 'READ/WRITE ') + m.host + '  ->  ' + previewGuest(m, workspaceHost, preview).guest;
+    const plural = (n) => (n === 1 ? '' : 's');
+    if (outside.length && policy === false) {
+        fail(name +
+            ' maps ' +
+            outside.length +
+            ' folder' +
+            plural(outside.length) +
+            ' outside the project, and your settings do not allow that:\n  ' +
+            outside.map(describe).join('\n  '), 'Allow it: set projects.allowOutsideMappings to "ask" or true in your settings (sandbox > Settings, or the file sandbox config path shows). Or remove those mappings from the file.');
+    }
+    const looser = loosenedRequests(config, overrides);
+    const interactive = Boolean(req.ask) && (req.interactive ?? Boolean(process.stdin.isTTY));
+    const notAllowedYet = () => policy === 'ask'
+        ? outside.filter((m) => allowedAnswer(allowStore, localPath, OUTSIDE_FOLDER, outsideKey(m)) !== true)
+        : [];
+    const openOutside = notAllowedYet();
+    const openLooser = looser.filter((a) => allowedAnswer(allowStore, localPath, a.key, a.wanted) === null);
+    let declinedOutside = false;
+    if (interactive && req.ask && (openOutside.length || openLooser.length)) {
+        console.log('\n' + name + ' asks for more than your settings allow:');
+        if (openOutside.length)
+            console.log('  Folders outside the project:\n' + openOutside.map((m) => '    ' + plainText(describe(m))).join('\n'));
+        for (const a of openLooser)
+            console.log('  ' + a.key + ' = ' + JSON.stringify(a.wanted) + '  (your settings: ' + JSON.stringify(a.yours) + ')');
+        const ok = await req.ask('Allow ' + (openOutside.length + openLooser.length === 1 ? 'it' : 'these') + ' for this project?');
+        for (const a of openLooser)
+            saveAllowed(allowStore, localPath, a.key, a.wanted, ok);
+        // A "no" to folders is not kept: the next interactive launch asks again.
+        if (ok)
+            for (const m of openOutside)
+                saveAllowed(allowStore, localPath, OUTSIDE_FOLDER, outsideKey(m), true);
+        declinedOutside = !ok && openOutside.length > 0;
+    }
+    const notAllowed = notAllowedYet();
+    if (notAllowed.length) {
+        const them = notAllowed.length === 1 ? 'it' : 'them';
+        const what = name +
+            ' maps ' +
+            notAllowed.length +
+            ' folder' +
+            plural(notAllowed.length) +
+            ' outside the project:\n  ' +
+            notAllowed.map(describe).join('\n  ');
+        fail(what +
+            (declinedOutside
+                ? '\nYou did not allow ' + them + ', so the sandbox was not started.'
+                : '\nThat needs your OK once (a repo ships this file), and this launch cannot ask (no interactive terminal).'), 'Allow ' +
+            them +
+            ': start it from an interactive terminal and answer y, or set projects.allowOutsideMappings to true in your settings (sandbox > Settings, or the file sandbox config path shows).');
+    }
+    const allowedHosts = [...new Set(outside.map((m) => m.host))];
+    if (outside.length)
+        notes.push('Folders outside the project allowed for ' +
+            name +
+            ' (' +
+            (policy === true ? 'projects.allowOutsideMappings is true' : 'your answer is kept in ' + allowStore) +
+            '): ' +
+            allowedHosts.join(', '));
+    const allowed = [];
+    for (const ask of looser) {
+        const ok = allowedAnswer(allowStore, localPath, ask.key, ask.wanted);
+        if (ok) {
+            allowed.push(ask);
+            notes.push('Allowed for this project: ' +
+                ask.key +
+                ' = ' +
+                JSON.stringify(ask.wanted) +
+                ' (your answer is kept in ' +
+                allowStore +
+                ').');
+        }
+        else
+            notes.push('The project asks for ' +
+                ask.key +
+                ' = ' +
+                JSON.stringify(ask.wanted) +
+                ', but your settings say ' +
+                JSON.stringify(ask.yours) +
+                ', so it is not used. ' +
+                (ok === false
+                    ? 'You said no (kept in ' + allowStore + ').'
+                    : 'Start it from an interactive terminal to allow it for this project.') +
+                ' Or set ' +
+                ask.key +
+                ' in your own settings (sandbox, then Settings > All projects).');
+    }
+    return { allowed, outside: allowedHosts };
+}

package/dist/core/run/versions.d.ts

@@ -0,0 +1,13 @@
+import type { Config, Overrides, ToolVersions } from '../types.js';
+/**
+ * The Node version a Volta project pins ("volta": { "node": "20.11.1" } in package.json), so nvm defaults to it too.
+ */
+export declare const voltaNode: (workspace: string) => string | null;
+/**
+ * Picks tool versions. Highest priority first: command line, the folder's .sandbox-config.json,
+ * version files in the workspace (.nvmrc, .node-version, .python-version), the tool config, this PC's node version.
+ */
+export declare const resolveVersions: (config: Config, workspace: string, local: Overrides, req: {
+    nodeVersion?: string;
+    pythonVersion?: string;
+}, hostNodeVersion: string) => ToolVersions;

package/dist/core/run/versions.js

@@ -0,0 +1,65 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { fileExists } from '../util/index.js';
+const firstLine = (file) => {
+    if (!fileExists(file))
+        return null;
+    const line = fs
+        .readFileSync(file, 'utf8')
+        .replace(/^\uFEFF/, '')
+        .split(/\r?\n/)
+        .map((l) => l.replace(/#.*$/, '').trim())
+        .find((l) => l !== '');
+    return line ?? null;
+};
+const VOLTA_PIN = 'package.json volta.node';
+const PackageJsonSchema = z.object({
+    volta: z
+        .object({
+        node: z
+            .string()
+            .regex(/^\d+(\.\d+){0,2}$/)
+            .optional(),
+    })
+        .optional(),
+});
+/**
+ * The Node version a Volta project pins ("volta": { "node": "20.11.1" } in package.json), so nvm defaults to it too.
+ */
+export const voltaNode = (workspace) => {
+    const file = path.join(workspace, 'package.json');
+    if (!fileExists(file))
+        return null;
+    try {
+        return (PackageJsonSchema.safeParse(JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''))).data?.volta?.node ??
+            null);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Picks tool versions. Highest priority first: command line, the folder's .sandbox-config.json,
+ * version files in the workspace (.nvmrc, .node-version, .python-version), the tool config, this PC's node version.
+ */
+export const resolveVersions = (config, workspace, local, req, hostNodeVersion) => {
+    const localTools = (local.toolchains ?? {});
+    const pick = (cli, localValue, files, configured) => {
+        if (cli)
+            return { spec: cli, source: 'command line' };
+        if (localValue)
+            return { spec: localValue, source: '.sandbox-config.json' };
+        for (const name of files) {
+            const value = name === VOLTA_PIN ? voltaNode(workspace) : firstLine(path.join(workspace, name));
+            if (value)
+                return { spec: value, source: name };
+        }
+        return { spec: configured, source: 'config' };
+    };
+    let node = pick(req.nodeVersion, localTools.node?.version, ['.nvmrc', '.node-version', VOLTA_PIN], config.toolchains.node.version);
+    if (node.spec === 'host')
+        node = { spec: hostNodeVersion.replace(/^v/, ''), source: 'this PC' };
+    const python = pick(req.pythonVersion, localTools.python?.version, ['.python-version'], config.toolchains.python.version);
+    return { node, nodeExtra: config.toolchains.node.extraVersions, python };
+};

package/dist/core/safe-paths.js

@@ -1,10 +1,10 @@
 // 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';
+import { userDir } from './config/index.js';
+import { fail, isInsideOrEqual, isRootPath, isUserProfile } from './util/index.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],
+    ["this tool's install folder", packageRoot],
     ['the sandbox storage folder', storageRoot],
     ['your sandbox settings folder', userDir()],
 ];
@@ -25,9 +25,21 @@ export const assertSafeWorkspace = (workspace, packageRoot, storageRoot) => {
         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.');
+            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.');
+            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];

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

@@ -1,9 +1,9 @@
 import { z } from 'zod';
-export declare const AppId: z.ZodEnum<{
+export declare const AppIdSchema: z.ZodEnum<{
     [x: string]: string;
 }>;
-export declare const CustomAppId: z.ZodString;
-export declare const CustomApp: z.ZodObject<{
+export declare const CustomAppIdSchema: z.ZodString;
+export declare const CustomAppSchema: z.ZodObject<{
     name: z.ZodString;
     github: z.ZodOptional<z.ZodString>;
     asset: z.ZodOptional<z.ZodString>;
@@ -18,7 +18,7 @@ export declare const CustomApp: z.ZodObject<{
     exe: z.ZodString;
     cli: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
-export declare const Apps: z.ZodObject<{
+export declare const AppsSchema: z.ZodObject<{
     install: z.ZodArray<z.ZodEnum<{
         [x: string]: string;
     }>>;

package/dist/core/schema/apps.js

@@ -1,27 +1,61 @@
 // Apps installed in the sandbox: entries from the catalogue (shared/apps.ts) and programs of your own.
 import { z } from 'zod';
-import { APPS } from '../../shared/apps.js';
+import { APPS } from '../../shared/apps/index.js';
 const CATALOGUE_IDS = APPS.filter((a) => !a.setting).map((a) => a.id);
-export const AppId = z.enum(CATALOGUE_IDS);
-export const CustomAppId = z.string().regex(/^[a-z0-9][a-z0-9-]{0,40}$/, 'lower-case letters, digits and - only');
-const compiles = (pattern) => { try {
-    new RegExp(pattern);
-    return true;
-}
-catch {
-    return false;
-} };
-export const CustomApp = z.strictObject({
+export const AppIdSchema = z.enum(CATALOGUE_IDS);
+export const CustomAppIdSchema = z.string().regex(/^[a-z0-9][a-z0-9-]{0,40}$/, 'lower-case letters, digits and - only');
+const compiles = (pattern) => {
+    try {
+        new RegExp(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const CustomAppSchema = z
+    .strictObject({
     name: z.string().min(1).max(80).describe('The name on the desktop shortcut, e.g. "My Tool".'),
-    github: z.string().regex(/^[\w.-]+\/[\w.-]+$/, 'owner/repo, e.g. sharkdp/bat').optional().describe('GitHub repository (owner/repo): the file comes from its latest release.'),
-    asset: z.string().max(200).refine(compiles, 'not a valid pattern').optional().describe('With github: a pattern (regular expression) matching the release file, e.g. windows.*x64\\.zip$'),
-    url: z.string().url().startsWith('https://', 'https:// only').optional().describe('Or a direct https:// download link (zip, 7z, exe or msi).'),
-    sha256: z.string().regex(/^[0-9a-fA-F]{64}$/, '64 hex characters').optional().describe('SHA-256 of the download (GitHub releases usually publish one; then this is not needed).'),
-    unpack: z.enum(['archive', 'file', 'nsis', 'msi']).optional().describe('archive (zip, 7z, tar: the default), file (a single .exe), nsis (an installer 7-Zip can open) or msi.'),
+    github: z
+        .string()
+        .regex(/^[\w.-]+\/[\w.-]+$/, 'owner/repo, e.g. sharkdp/bat')
+        .optional()
+        .describe('GitHub repository (owner/repo): the file comes from its latest release.'),
+    asset: z
+        .string()
+        .max(200)
+        .refine(compiles, 'not a valid pattern')
+        .optional()
+        .describe('With github: a pattern (regular expression) matching the release file, e.g. windows.*x64\\.zip$'),
+    url: z
+        .string()
+        .url()
+        .startsWith('https://', 'https:// only')
+        .optional()
+        .describe('Or a direct https:// download link (zip, 7z, exe or msi).'),
+    sha256: z
+        .string()
+        .regex(/^[0-9a-fA-F]{64}$/, '64 hex characters')
+        .optional()
+        .describe('SHA-256 of the download (GitHub releases usually publish one; then this is not needed).'),
+    unpack: z
+        .enum(['archive', 'file', 'nsis', 'msi'])
+        .optional()
+        .describe('archive (zip, 7z, tar: the default), file (a single .exe), nsis (an installer 7-Zip can open) or msi.'),
     exe: z.string().min(1).max(200).describe('The program to start (found anywhere in the download), e.g. mytool.exe.'),
-    cli: z.boolean().optional().describe('A command-line tool: its folder goes on PATH instead of getting a desktop shortcut.'),
-}).refine((a) => (a.github && a.asset ? !a.url : Boolean(a.url) && !a.github && !a.asset), { message: 'give github + asset, or url (not both)' });
-export const Apps = z.strictObject({
-    install: z.array(AppId).describe('Apps from the catalogue to install in every sandbox (the Apps screen in the menu lists them by category). Each is downloaded once and kept.'),
-    custom: z.record(CustomAppId, CustomApp).describe('Programs of your own: a GitHub release or a download link, and the program to start. Installed like the catalogue apps.'),
+    cli: z
+        .boolean()
+        .optional()
+        .describe('A command-line tool: its folder goes on PATH instead of getting a desktop shortcut.'),
+})
+    .refine((a) => (a.github && a.asset ? !a.url : Boolean(a.url) && !a.github && !a.asset), {
+    message: 'give github + asset, or url (not both)',
+});
+export const AppsSchema = z.strictObject({
+    install: z
+        .array(AppIdSchema)
+        .describe('Apps from the catalogue to install in every sandbox (the Apps screen in the menu lists them by category). Each is downloaded once and kept.'),
+    custom: z
+        .record(CustomAppIdSchema, CustomAppSchema)
+        .describe('Programs of your own: a GitHub release or a download link, and the program to start. Installed like the catalogue apps.'),
 });

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

@@ -1,17 +1,20 @@
 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 GuestPathSchema: z.ZodString;
+export declare const NameSchema: z.ZodString;
+export declare const StringsSchema: 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<{
+export declare const SchemaRefSchema: z.ZodString;
+export declare const GitAccessSchema: z.ZodEnum<{
     readonly: "readonly";
-    full: "full";
     none: "none";
+    full: "full";
 }>;
-/** 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>;
+/**
+ * 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 EnabledSchema: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
+export declare const enabled: (what: string, markers: string) => typeof EnabledSchema;
+export declare const Packages: (what: string, example: string) => typeof StringsSchema;