windows-development-sandbox 1.0.5 → 1.4.0

package/dist/selftest/workspace-view.test.js

@@ -0,0 +1,89 @@
+// workspaceFilter: the sandbox works on a copy of the project without what git ignores, kept in step both ways.
+import fs from 'node:fs';
+import path from 'node:path';
+import { IgnoreRules } from '../host/workspace-view/rules.js';
+import { WorkspaceView } from '../host/workspace-view/view.js';
+export const workspaceViewSuite = {
+    name: 'workspace-view',
+    title: 'git-ignored files kept out of the sandbox (filtered view, two-way sync)',
+    run: async (t, f) => {
+        t.section('a filtered launch');
+        const project = t.dir('filtered-app');
+        fs.mkdirSync(path.join(project, '.git'));
+        const filtered = { ...f.baseConfig, workspaceFilter: { enabled: true, exclude: [], include: [] } };
+        const gen = await f.launch({ cwd: project }, { config: filtered });
+        const workspace = gen.mappings.find((m) => m.guest.toLowerCase().endsWith('\\filtered-app'));
+        const git = gen.mappings.find((m) => m.guest.toLowerCase().endsWith('\\filtered-app.git'));
+        t.check(Boolean(workspace) && !workspace.host.toLowerCase().startsWith(project.toLowerCase()) && workspace.host.includes('views'), 'the sandbox maps the filtered view, not the project folder');
+        t.check(git?.host === path.join(project, '.git') && !git.readOnly, '... and the project\'s .git beside it, so git works');
+        const noGit = await f.launch({ cwd: project }, { config: { ...filtered, provisioning: { ...filtered.provisioning, git: { ...filtered.provisioning.git, access: 'none' } } } });
+        t.check(!noGit.mappings.some((m) => m.guest.toLowerCase().endsWith('.git')), 'with git access "none" no .git is mapped at all');
+        t.section('which files git ignores');
+        const rulesRoot = t.at('rules');
+        t.write(path.join(rulesRoot, '.gitignore'), 'node_modules/\n*.log\n!keep.log\n.env*\n!.env.example\ndist\n');
+        t.write(path.join(rulesRoot, 'sub', '.gitignore'), 'secret.txt\n!*.log\n');
+        t.write(path.join(rulesRoot, '.git', 'info', 'exclude'), 'local-notes.md\n');
+        const rules = new IgnoreRules(rulesRoot, ['*.pem'], ['dist/keep-me.js']);
+        const verdicts = Object.fromEntries(['src/a.ts', 'node_modules/x/index.js', 'a.log', 'keep.log', '.env', '.env.local', '.env.example', 'dist/out.js', 'sub/secret.txt', 'sub/b.log', 'local-notes.md', 'key.pem', 'dist/keep-me.js', '.git/config'].map((p) => [p, rules.isIgnored(p)]));
+        t.equal(verdicts, {
+            'src/a.ts': false, 'node_modules/x/index.js': true, 'a.log': true, 'keep.log': false, '.env': true, '.env.local': true, '.env.example': false,
+            'dist/out.js': true, 'sub/secret.txt': true, 'sub/b.log': false, 'local-notes.md': true, 'key.pem': true, 'dist/keep-me.js': false, '.git/config': true,
+        }, 'rules: nested .gitignore files, ! exceptions, .git/info/exclude, your own exclude and include patterns');
+        t.section('the view');
+        const host = t.at('project');
+        t.write(path.join(host, '.gitignore'), 'node_modules/\n.env\ndist/\n');
+        t.write(path.join(host, 'src', 'main.ts'), 'console.log(1);\n');
+        t.write(path.join(host, 'README.md'), '# hi\n');
+        t.write(path.join(host, '.env'), 'API_KEY=secret\n');
+        t.write(path.join(host, 'node_modules', 'pkg', 'index.js'), 'host build');
+        fs.mkdirSync(path.join(host, '.git'), { recursive: true });
+        const paths = WorkspaceView.pathsFor(t.at('storage'), host);
+        const view = new WorkspaceView({ ...paths, guestGitDir: 'C:\\Workspace\\project.git' });
+        view.prepare();
+        const inView = (rel) => fs.existsSync(path.join(paths.view, ...rel.split('/')));
+        t.check(inView('src/main.ts') && inView('README.md') && inView('.gitignore'), 'view: what git tracks is there');
+        t.check(!inView('.env') && !inView('node_modules'), 'view: ignored files (.env, node_modules) are not');
+        t.equal(fs.readFileSync(path.join(paths.view, '.git'), 'utf8'), 'gitdir: C:/Workspace/project.git\n', 'view: its .git points at the project\'s real .git (mapped separately)');
+        t.check(!paths.view.toLowerCase().startsWith(host.toLowerCase()), 'view: it lives outside the project');
+        t.section('both ways');
+        t.write(path.join(host, 'src', 'main.ts'), 'console.log(2);\n');
+        t.touch(path.join(host, 'src', 'main.ts'), 5);
+        view.syncChanged(['src/main.ts']);
+        t.equal(fs.readFileSync(path.join(paths.view, 'src', 'main.ts'), 'utf8'), 'console.log(2);\n', 'your edit reaches the sandbox');
+        t.write(path.join(paths.view, 'src', 'new.ts'), 'export {};\n');
+        t.write(path.join(paths.view, 'node_modules', 'pkg', 'index.js'), 'sandbox build');
+        t.write(path.join(paths.view, 'dist', 'bundle.js'), 'built');
+        view.syncAll();
+        t.check(fs.existsSync(path.join(host, 'src', 'new.ts')), 'a file the agent creates reaches your project');
+        t.equal(fs.readFileSync(path.join(host, 'node_modules', 'pkg', 'index.js'), 'utf8'), 'host build', 'the sandbox\'s own node_modules never overwrite yours');
+        t.check(!fs.existsSync(path.join(host, 'dist')), 'its build output stays in the sandbox');
+        fs.rmSync(path.join(paths.view, 'README.md'));
+        view.syncAll();
+        t.check(!fs.existsSync(path.join(host, 'README.md')), 'a deletion in the sandbox is repeated in your project');
+        fs.rmSync(path.join(host, 'src', 'new.ts'));
+        view.syncAll();
+        t.check(!inView('src/new.ts'), 'a deletion in your project is repeated in the sandbox');
+        t.section('conflicts and changing rules');
+        t.write(path.join(host, 'src', 'main.ts'), 'yours\n');
+        t.touch(path.join(host, 'src', 'main.ts'), 20);
+        t.write(path.join(paths.view, 'src', 'main.ts'), 'sandbox\n');
+        t.touch(path.join(paths.view, 'src', 'main.ts'), 30);
+        const stats = view.syncAll();
+        const conflicts = fs.readdirSync(path.join(host, 'src')).filter((n) => n.includes('.sandbox-conflict-'));
+        t.check(stats.conflicts === 1 && fs.readFileSync(path.join(host, 'src', 'main.ts'), 'utf8') === 'yours\n' && conflicts.length === 1 && fs.readFileSync(path.join(host, 'src', conflicts[0]), 'utf8') === 'sandbox\n', 'changed on both sides: yours stays, the sandbox\'s version is kept next to it');
+        t.equal(fs.readFileSync(path.join(paths.view, 'src', 'main.ts'), 'utf8'), 'yours\n', '... and the sandbox sees yours');
+        t.write(path.join(host, '.gitignore'), 'node_modules/\ndist/\n');
+        view.syncChanged(['.gitignore']);
+        t.check(inView('.env'), 'a file no longer ignored comes in when .gitignore changes');
+        t.equal(view.syncAll(), { toView: 0, toHost: 0, deleted: 0, conflicts: 0, skipped: 0 }, 'a pass with nothing changed copies nothing');
+        t.check(view.syncChanged(['../outside.txt', 'C:/Windows/x', '']).toHost === 0, 'paths from outside the project are ignored');
+        t.section('live');
+        const stop = view.watch(60000);
+        t.write(path.join(host, 'live.txt'), 'from you');
+        const arrived = await t.waitFor(() => inView('live.txt'), 5000);
+        t.write(path.join(paths.view, 'live-back.txt'), 'from the sandbox');
+        const back = await t.waitFor(() => fs.existsSync(path.join(host, 'live-back.txt')), 5000);
+        stop();
+        t.check(Boolean(arrived) && Boolean(back), 'changes on either side arrive within a second or two while it watches');
+    },
+};

package/dist/selftest/workspace.test.d.ts

@@ -0,0 +1,2 @@
+import type { Suite } from './suite.js';
+export declare const workspaceSuite: Suite;

package/dist/selftest/workspace.test.js

@@ -0,0 +1,53 @@
+// Turning the folder you run in into a sandbox run: guest path, tool versions from version files, folders that are refused.
+import fs from 'node:fs';
+import path from 'node:path';
+import { voltaNode, autoGuestWorkspace } from '../core/workspace.js';
+export const workspaceSuite = {
+    name: 'workspace',
+    title: 'workspace resolution, version files (.nvmrc ...), refused folders',
+    run: async (t, f) => {
+        t.section('guest folder and defaults');
+        const run = await f.run();
+        t.equal({ host: run.workspaceHost, guest: run.config.guestWorkspace, harness: run.harnessName, dataFolder: path.basename(run.dataPath) }, { host: f.workA, guest: 'C:\\Workspace\\work-a', harness: 'claude', dataFolder: 'testdata' }, 'any folder is the workspace; its guest path is C:\\Workspace\\<folder name>');
+        t.equal(autoGuestWorkspace('C:\\x\\My Proj (2)'), 'C:\\Workspace\\My Proj _2_', 'auto guest folder names are sanitised');
+        t.equal(autoGuestWorkspace('D:\\...'), 'C:\\Workspace\\project', 'a folder name with nothing usable becomes "project"');
+        t.equal({ node: run.versions.node.spec, nodeSource: run.versions.node.source, python: run.versions.python.spec }, { node: '22.3.0', nodeSource: 'this PC', python: '3' }, 'the default Node version is this PC\'s; Python defaults to the latest 3.x');
+        t.section('version files');
+        const nvmrc = path.join(f.workA, '.nvmrc');
+        const pythonVersion = path.join(f.workA, '.python-version');
+        t.write(nvmrc, 'lts/iron\n');
+        t.write(pythonVersion, '3.11\n');
+        const withFiles = await f.run();
+        t.equal({ node: withFiles.versions.node.spec, source: withFiles.versions.node.source, python: withFiles.versions.python.spec }, { node: 'lts/iron', source: '.nvmrc', python: '3.11' }, '.nvmrc and .python-version are respected');
+        t.equal((await f.run({ nodeVersion: '18' })).versions.node.source, 'command line', '--node beats .nvmrc');
+        fs.rmSync(nvmrc);
+        fs.rmSync(pythonVersion);
+        const nodeVersion = path.join(f.workA, '.node-version');
+        t.write(nodeVersion, 'v20.11.1');
+        t.equal((await f.run()).versions.node.spec, 'v20.11.1', '.node-version is respected');
+        fs.rmSync(nodeVersion);
+        const voltaProject = t.write(t.at('volta-ws', 'package.json'), '{"name":"x","volta":{"node":"20.11.1","pnpm":"9.1.0"}}');
+        t.write(t.at('no-volta-ws', 'package.json'), '{"name":"y","volta":{"node":"latest; rm -rf"}}');
+        t.equal(voltaNode(path.dirname(voltaProject)), '20.11.1', 'Volta: package.json "volta.node" picks the Node version');
+        t.equal(voltaNode(t.at('no-volta-ws')), null, 'Volta: only a plain version is accepted');
+        t.equal(voltaNode(t.at('missing')), null, 'Volta: a folder without package.json has no version');
+        t.section('folders that are refused');
+        await t.throws(() => f.run({ cwd: f.install }), 'install folder', 'the install folder is refused');
+        await t.throws(() => f.run({ cwd: t.temp }), 'must not be able to change', 'a parent of the install folder is refused');
+        await t.throws(() => f.run({ cwd: t.at('storage') }), 'storage folder', 'the storage folder is refused');
+        const originalWindir = process.env.WINDIR;
+        const fakeWindows = t.dir('winroot');
+        const systemFolder = t.dir('winroot', 'sys');
+        process.env.WINDIR = fakeWindows;
+        try {
+            await t.throws(() => f.run({ cwd: systemFolder }), 'system folder', 'a folder inside the Windows folder is refused');
+        }
+        finally {
+            if (originalWindir === undefined)
+                delete process.env.WINDIR;
+            else
+                process.env.WINDIR = originalWindir;
+        }
+        await t.throws(() => f.run({ cwd: path.parse(t.temp).root }), 'whole drive', 'a whole drive is refused');
+    },
+};

package/dist/shared/apps.d.ts

@@ -0,0 +1,49 @@
+import type { Config, GitAccess } from '../core/types.js';
+export type AppCategory = 'editors' | 'databases' | 'api' | 'git' | 'utilities' | 'browsers' | 'gamedev' | 'cloud' | 'diagrams' | 'network' | 'cli';
+export declare const APP_CATEGORIES: {
+    id: AppCategory;
+    label: string;
+    description: string;
+}[];
+/** Where a download comes from. Resolvers (sublime, kubectl ...) are code in guest/apps, named here by id. */
+export type AppSource = {
+    github: string;
+    asset: string;
+} | {
+    url: string;
+} | {
+    resolve: string;
+} | {
+    npm: string;
+};
+export interface AppEntry {
+    id: string;
+    name: string;
+    category: AppCategory;
+    about: string;
+    size: string;
+    source: AppSource;
+    /** How the download is unpacked: an archive (zip/7z/tar, the default), the file itself, an NSIS installer or an MSI. */
+    unpack?: 'archive' | 'file' | 'nsis' | 'msi';
+    /** The program to start (or the tool on PATH): a file name, or a regex (/.../) for names with a version in them. */
+    exe: string;
+    /** A command-line tool: its folder goes on PATH (no desktop shortcut). */
+    cli?: boolean;
+    /** Needs these first: 7-Zip to unpack an installer, Mesa for OpenGL without a GPU. */
+    needs?: ('7zip' | 'mesa')[];
+    /** Settings elsewhere that this entry stands for (VS Code, Windows Terminal): shown in the catalogue, not installed by it. */
+    setting?: string;
+    /** Only with full git access (it pushes on its own, past the sandbox's git guard). */
+    fullGitOnly?: boolean;
+}
+export declare const APPS: AppEntry[];
+export declare const appById: (id: string) => AppEntry | undefined;
+/** A catalogue `exe` that is a regex ("/.../") matches names with a version in them. */
+export declare const exeMatcher: (exe: string) => ((name: string) => boolean);
+/** The apps to install, in order: 7-Zip first when anything needs it to unpack. */
+export declare const appsToInstall: (apps: Config["apps"], gitAccess: GitAccess) => {
+    entries: AppEntry[];
+    skipped: string[];
+};
+/** Does any chosen app draw with OpenGL (so the Mesa step must run first)? */
+export declare const appsNeedMesa: (apps: Config["apps"] | undefined) => boolean;

package/dist/shared/apps.js

@@ -0,0 +1,114 @@
+export const APP_CATEGORIES = [
+    { id: 'editors', label: 'Editors & IDEs', description: 'Code and text editors (VS Code is a setting of its own and on by default).' },
+    { id: 'databases', label: 'Database clients', description: 'GUIs for the databases the sandbox runs (PostgreSQL, MySQL, MongoDB, Redis, SQLite, DynamoDB).' },
+    { id: 'api', label: 'API clients', description: 'Send HTTP, REST and GraphQL requests to what you are building.' },
+    { id: 'git', label: 'Git tools', description: 'Git GUIs and terminal UIs. They use the sandbox\'s git, so its git access rules apply.' },
+    { id: 'utilities', label: 'Utilities', description: 'Archives, comparing files, finding files, process tools, hex editing.' },
+    { id: 'browsers', label: 'Browsers', description: 'Browsers for testing web apps (Edge is already in Windows).' },
+    { id: 'gamedev', label: 'Game development', description: 'Engines and editors. They draw with OpenGL on the CPU (Mesa) when the sandbox has no GPU.' },
+    { id: 'cloud', label: 'Cloud & Kubernetes', description: 'Command-line tools for clouds, Kubernetes and infrastructure as code.' },
+    { id: 'diagrams', label: 'Diagrams & docs', description: 'Diagrams and document conversion.' },
+    { id: 'network', label: 'Network & HTTP', description: 'Inspect and test HTTP traffic and APIs.' },
+    { id: 'cli', label: 'Command-line tools', description: 'Small tools developers reach for: JSON and YAML, search, diff, builds, media, load testing ...' },
+];
+const gh = (github, asset) => ({ github, asset });
+export const APPS = [
+    // ---- editors
+    { id: 'vscode', name: 'Visual Studio Code', category: 'editors', about: 'Code editor with debugging, set up for the sandbox\'s languages.', size: '150 MB', source: { resolve: 'setting' }, exe: 'Code.exe', setting: 'toolchains.vscode.enabled' },
+    { id: 'windows-terminal', name: 'Windows Terminal', category: 'utilities', about: 'The sandbox window: tabs, panes, PowerShell 7 profile.', size: '40 MB', source: { resolve: 'setting' }, exe: 'WindowsTerminal.exe', setting: 'provisioning.terminal.enabled' },
+    { id: 'notepadpp', name: 'Notepad++', category: 'editors', about: 'Fast text and code editor.', size: '8 MB', source: gh('notepad-plus-plus/notepad-plus-plus', '^npp\\.[\\d.]+\\.portable\\.x64\\.zip$'), exe: 'notepad++.exe' },
+    { id: 'sublime', name: 'Sublime Text', category: 'editors', about: 'Fast code editor (paid licence, free to evaluate).', size: '28 MB', source: { resolve: 'sublime' }, exe: 'sublime_text.exe' },
+    { id: 'neovim', name: 'Neovim', category: 'editors', about: 'Terminal text editor (nvim).', size: '12 MB', source: gh('neovim/neovim', '^nvim-win64\\.zip$'), exe: 'nvim.exe', cli: true },
+    // ---- database clients
+    { id: 'dbeaver', name: 'DBeaver Community', category: 'databases', about: 'Universal database client: PostgreSQL, MySQL, SQLite, SQL Server and more.', size: '120 MB', source: gh('dbeaver/dbeaver', '^dbeaver-ce-[\\d.]+-windows-x86_64\\.zip$'), exe: 'dbeaver.exe' },
+    { id: 'pgadmin', name: 'pgAdmin 4', category: 'databases', about: 'The PostgreSQL admin GUI (from the PostgreSQL binaries zip).', size: '330 MB', source: { resolve: 'pgadmin' }, exe: 'pgAdmin4.exe' },
+    { id: 'heidisql', name: 'HeidiSQL', category: 'databases', about: 'Light client for MySQL, MariaDB, PostgreSQL and SQL Server.', size: '28 MB', source: gh('HeidiSQL/HeidiSQL', '^HeidiSQL_[\\d.]+_64_Portable\\.zip$'), exe: 'heidisql.exe' },
+    { id: 'sqlitebrowser', name: 'DB Browser for SQLite', category: 'databases', about: 'Open, browse and edit SQLite files.', size: '21 MB', source: gh('sqlitebrowser/sqlitebrowser', '^DB\\.Browser\\.for\\.SQLite-v?[\\d.]+-win64\\.zip$'), exe: 'DB Browser for SQLite.exe' },
+    { id: 'compass', name: 'MongoDB Compass', category: 'databases', about: 'The MongoDB GUI.', size: '220 MB', source: gh('mongodb-js/compass', '^mongodb-compass-[\\d.]+-win32-x64\\.zip$'), exe: 'MongoDBCompass.exe' },
+    { id: 'redisinsight', name: 'Redis Insight', category: 'databases', about: 'The Redis GUI.', size: '110 MB', source: gh('redis/RedisInsight', '^Redis-Insight-win-installer\\.exe$'), unpack: 'nsis', exe: 'Redis Insight.exe', needs: ['7zip'] },
+    { id: 'dbgate', name: 'DbGate', category: 'databases', about: 'Database manager for SQL and NoSQL databases.', size: '180 MB', source: gh('dbgate/dbgate', '^dbgate-[\\d.]+-win_x64\\.zip$'), exe: 'DbGate.exe' },
+    { id: 'beekeeper', name: 'Beekeeper Studio', category: 'databases', about: 'SQL editor and database manager.', size: '245 MB', source: gh('beekeeper-studio/beekeeper-studio', '^Beekeeper-Studio-[\\d.]+-portable\\.exe$'), unpack: 'nsis', exe: 'Beekeeper Studio.exe', needs: ['7zip'] },
+    { id: 'dynamodb-admin', name: 'dynamodb-admin', category: 'databases', about: 'Web GUI for DynamoDB Local: run dynamodb-admin, then open http://localhost:8001.', size: '5 MB', source: { npm: 'dynamodb-admin' }, exe: 'dynamodb-admin.cmd', cli: true },
+    // ---- API clients
+    { id: 'bruno', name: 'Bruno', category: 'api', about: 'Offline, git-friendly API client (collections are files in your repo).', size: '175 MB', source: gh('usebruno/bruno', '^bruno_[\\d.]+_x64_win\\.zip$'), exe: 'Bruno.exe' },
+    { id: 'insomnia', name: 'Insomnia', category: 'api', about: 'REST, GraphQL and gRPC client.', size: '590 MB', source: gh('Kong/insomnia', '^insomnia-[\\d.]+-full\\.nupkg$'), exe: 'Insomnia.exe' },
+    // ---- git
+    { id: 'sourcegit', name: 'SourceGit', category: 'git', about: 'Fast open-source Git GUI.', size: '26 MB', source: gh('sourcegit-scm/sourcegit', '^sourcegit_[\\d.]+\\.win-x64\\.zip$'), exe: 'SourceGit.exe' },
+    { id: 'githubdesktop', name: 'GitHub Desktop', category: 'git', about: 'Simple Git GUI from GitHub. It has its own git, so it needs provisioning.git.access "full".', size: '300 MB', source: gh('desktop/desktop', '^GitHubDesktop-[\\d.]+-x64-full\\.nupkg$'), exe: 'GitHubDesktop.exe', fullGitOnly: true },
+    { id: 'lazygit', name: 'lazygit', category: 'git', about: 'Git in the terminal.', size: '7 MB', source: gh('jesseduffield/lazygit', '^lazygit_[\\d.]+_windows_x86_64\\.zip$'), exe: 'lazygit.exe', cli: true },
+    // ---- utilities
+    { id: '7zip', name: '7-Zip', category: 'utilities', about: 'Archive manager (7z, zip, rar, tar ...). Also unpacks installers for other apps.', size: '2 MB', source: { resolve: '7zip' }, exe: '7zFM.exe' },
+    { id: 'winmerge', name: 'WinMerge', category: 'utilities', about: 'Compare and merge files and folders.', size: '23 MB', source: gh('WinMerge/winmerge', '^winmerge-[\\d.]+-x64-exe\\.zip$'), exe: 'WinMergeU.exe' },
+    { id: 'everything', name: 'Everything', category: 'utilities', about: 'Finds files by name instantly.', size: '2 MB', source: { resolve: 'everything' }, exe: 'Everything.exe' },
+    { id: 'sysinternals', name: 'Sysinternals Suite', category: 'utilities', about: 'Process Explorer, Process Monitor, Autoruns, TCPView and more (on PATH).', size: '200 MB', source: { url: 'https://download.sysinternals.com/files/SysinternalsSuite.zip' }, exe: 'procexp64.exe' },
+    { id: 'imhex', name: 'ImHex', category: 'utilities', about: 'Hex editor for reverse engineering and binary formats.', size: '80 MB', source: gh('WerWolv/ImHex', '^imhex-[\\d.]+-Windows-Portable-NoGPU-x86_64\\.zip$'), exe: 'imhex-gui.exe' },
+    // ---- browsers
+    { id: 'chrome', name: 'Chrome for Testing', category: 'browsers', about: 'Chrome build made for automated tests (with chromedriver on PATH).', size: '170 MB', source: { resolve: 'chrome' }, exe: 'chrome.exe' },
+    { id: 'firefox', name: 'Firefox', category: 'browsers', about: 'Firefox for testing.', size: '75 MB', source: { resolve: 'firefox' }, unpack: 'nsis', exe: 'firefox.exe', needs: ['7zip'] },
+    // ---- game development
+    { id: 'godot', name: 'Godot', category: 'gamedev', about: 'Open-source 2D and 3D game engine.', size: '80 MB', source: gh('godotengine/godot', '^Godot_v[\\d.]+-stable_win64\\.exe\\.zip$'), exe: '/^Godot_v[\\d.]+-stable_win64\\.exe$/', needs: ['mesa'] },
+    { id: 'blender', name: 'Blender', category: 'gamedev', about: '3D modelling, animation and rendering.', size: '400 MB', source: { resolve: 'blender' }, exe: 'blender.exe', needs: ['mesa'] },
+    { id: 'love', name: 'LÖVE', category: 'gamedev', about: 'Lua framework for 2D games.', size: '4 MB', source: gh('love2d/love', '^love-[\\d.]+-win64\\.zip$'), exe: 'love.exe', needs: ['mesa'] },
+    { id: 'defold', name: 'Defold', category: 'gamedev', about: 'Free 2D/3D game engine and editor.', size: '330 MB', source: gh('defold/defold', '^Defold-x86_64-win32\\.zip$'), exe: 'Defold.exe', needs: ['mesa'] },
+    { id: 'pixelorama', name: 'Pixelorama', category: 'gamedev', about: 'Pixel-art and sprite editor.', size: '40 MB', source: gh('Orama-Interactive/Pixelorama', '^Pixelorama-Windows-64bit\\.zip$'), exe: 'Pixelorama.exe', needs: ['mesa'] },
+    { id: 'tiled', name: 'Tiled', category: 'gamedev', about: 'Tile map editor.', size: '22 MB', source: gh('mapeditor/tiled', '^Tiled-[\\d.]+_Windows-10\\+_x86_64\\.msi$'), unpack: 'msi', exe: 'tiled.exe' },
+    // ---- cloud
+    { id: 'kubectl', name: 'kubectl', category: 'cloud', about: 'Kubernetes command line.', size: '60 MB', source: { resolve: 'kubectl' }, unpack: 'file', exe: 'kubectl.exe', cli: true },
+    { id: 'helm', name: 'Helm', category: 'cloud', about: 'Kubernetes package manager.', size: '20 MB', source: { resolve: 'helm' }, exe: 'helm.exe', cli: true },
+    { id: 'k9s', name: 'k9s', category: 'cloud', about: 'Kubernetes cluster UI in the terminal.', size: '40 MB', source: gh('derailed/k9s', '^k9s_Windows_amd64\\.zip$'), exe: 'k9s.exe', cli: true },
+    { id: 'terraform', name: 'Terraform', category: 'cloud', about: 'Infrastructure as code.', size: '30 MB', source: { resolve: 'terraform' }, exe: 'terraform.exe', cli: true },
+    { id: 'azure-cli', name: 'Azure CLI', category: 'cloud', about: 'Manage Azure (az).', size: '90 MB', source: { url: 'https://aka.ms/installazurecliwindowszipx64' }, exe: 'az.cmd', cli: true },
+    { id: 'gcloud', name: 'Google Cloud CLI', category: 'cloud', about: 'Manage Google Cloud (gcloud, gsutil, bq).', size: '120 MB', source: { url: 'https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-windows-x86_64-bundled-python.zip' }, exe: 'gcloud.cmd', cli: true },
+    { id: 'aws-cli', name: 'AWS CLI', category: 'cloud', about: 'Manage AWS (aws).', size: '50 MB', source: { url: 'https://awscli.amazonaws.com/AWSCLIV2.msi' }, unpack: 'msi', exe: 'aws.exe', cli: true },
+    // ---- diagrams and docs
+    { id: 'drawio', name: 'draw.io', category: 'diagrams', about: 'Diagram editor (flowcharts, architecture, UML).', size: '170 MB', source: gh('jgraph/drawio-desktop', '^draw\\.io-[\\d.]+-windows\\.zip$'), exe: 'draw.io.exe' },
+    { id: 'pandoc', name: 'Pandoc', category: 'diagrams', about: 'Convert documents between Markdown, HTML, Word, PDF ...', size: '35 MB', source: gh('jgm/pandoc', '^pandoc-[\\d.]+-windows-x86_64\\.zip$'), exe: 'pandoc.exe', cli: true },
+    // ---- network
+    { id: 'mitmproxy', name: 'mitmproxy', category: 'network', about: 'Intercepting HTTPS proxy (mitmweb opens a web UI).', size: '90 MB', source: { resolve: 'mitmproxy' }, exe: 'mitmweb.exe', cli: true },
+    { id: 'xh', name: 'xh', category: 'network', about: 'Friendly HTTP requests from the terminal (like HTTPie).', size: '5 MB', source: gh('ducaale/xh', '^xh-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'xh.exe', cli: true },
+    { id: 'grpcurl', name: 'grpcurl', category: 'network', about: 'curl for gRPC servers.', size: '10 MB', source: gh('fullstorydev/grpcurl', '^grpcurl_[\\d.]+_windows_x86_64\\.zip$'), exe: 'grpcurl.exe', cli: true },
+    { id: 'k6', name: 'k6', category: 'network', about: 'Load testing with JavaScript scripts.', size: '30 MB', source: gh('grafana/k6', '^k6-v[\\d.]+-windows-amd64\\.zip$'), exe: 'k6.exe', cli: true },
+    // ---- command-line tools
+    { id: 'jq', name: 'jq', category: 'cli', about: 'Query and reshape JSON.', size: '1 MB', source: gh('jqlang/jq', '^jq-windows-amd64\\.exe$'), unpack: 'file', exe: 'jq.exe', cli: true },
+    { id: 'yq', name: 'yq', category: 'cli', about: 'Query and edit YAML, JSON, XML and TOML.', size: '10 MB', source: gh('mikefarah/yq', '^yq_windows_amd64\\.exe$'), unpack: 'file', exe: 'yq.exe', cli: true },
+    { id: 'ripgrep', name: 'ripgrep', category: 'cli', about: 'Very fast recursive search (rg).', size: '2 MB', source: gh('BurntSushi/ripgrep', '^ripgrep-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'rg.exe', cli: true },
+    { id: 'fd', name: 'fd', category: 'cli', about: 'Fast, friendly alternative to find.', size: '2 MB', source: gh('sharkdp/fd', '^fd-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'fd.exe', cli: true },
+    { id: 'bat', name: 'bat', category: 'cli', about: 'cat with syntax highlighting and git changes.', size: '3 MB', source: gh('sharkdp/bat', '^bat-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'bat.exe', cli: true },
+    { id: 'fzf', name: 'fzf', category: 'cli', about: 'Fuzzy finder for the terminal.', size: '2 MB', source: gh('junegunn/fzf', '^fzf-[\\d.]+-windows_amd64\\.zip$'), exe: 'fzf.exe', cli: true },
+    { id: 'delta', name: 'delta', category: 'cli', about: 'Readable git diffs with syntax highlighting.', size: '3 MB', source: gh('dandavison/delta', '^delta-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'delta.exe', cli: true },
+    { id: 'just', name: 'just', category: 'cli', about: 'Command runner (a simpler make for project tasks).', size: '2 MB', source: gh('casey/just', '^just-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'just.exe', cli: true },
+    { id: 'hyperfine', name: 'hyperfine', category: 'cli', about: 'Benchmark commands.', size: '1 MB', source: gh('sharkdp/hyperfine', '^hyperfine-v[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'hyperfine.exe', cli: true },
+    { id: 'watchexec', name: 'watchexec', category: 'cli', about: 'Run a command when files change.', size: '5 MB', source: gh('watchexec/watchexec', '^watchexec-[\\d.]+-x86_64-pc-windows-msvc\\.zip$'), exe: 'watchexec.exe', cli: true },
+    { id: 'protoc', name: 'protoc', category: 'cli', about: 'Protocol Buffers compiler.', size: '3 MB', source: gh('protocolbuffers/protobuf', '^protoc-[\\d.]+-win64\\.zip$'), exe: 'protoc.exe', cli: true },
+    { id: 'ninja', name: 'Ninja', category: 'cli', about: 'Small, fast build system (CMake\'s favourite generator).', size: '1 MB', source: gh('ninja-build/ninja', '^ninja-win\\.zip$'), exe: 'ninja.exe', cli: true },
+    { id: 'ffmpeg', name: 'FFmpeg', category: 'cli', about: 'Convert and process audio and video.', size: '200 MB', source: gh('BtbN/FFmpeg-Builds', '^ffmpeg-master-latest-win64-gpl\\.zip$'), exe: 'ffmpeg.exe', cli: true },
+    { id: 'sqlite', name: 'SQLite tools', category: 'cli', about: 'sqlite3 command-line shell.', size: '5 MB', source: { resolve: 'sqlite' }, exe: 'sqlite3.exe', cli: true },
+    { id: 'shellcheck', name: 'ShellCheck', category: 'cli', about: 'Finds bugs in shell scripts.', size: '10 MB', source: gh('koalaman/shellcheck', '^shellcheck-v[\\d.]+\\.zip$'), exe: 'shellcheck.exe', cli: true },
+    { id: 'gitleaks', name: 'Gitleaks', category: 'cli', about: 'Finds secrets committed to git.', size: '8 MB', source: gh('gitleaks/gitleaks', '^gitleaks_[\\d.]+_windows_x64\\.zip$'), exe: 'gitleaks.exe', cli: true },
+];
+export const appById = (id) => APPS.find((a) => a.id === id);
+/** A catalogue `exe` that is a regex ("/.../") matches names with a version in them. */
+export const exeMatcher = (exe) => {
+    const regex = /^\/(.+)\/$/.exec(exe);
+    if (regex) {
+        const r = new RegExp(regex[1], 'i');
+        return (name) => r.test(name);
+    }
+    return (name) => name.toLowerCase() === exe.toLowerCase();
+};
+/** Your own program as a catalogue entry (its folder is apps\custom\<id>). */
+const customEntry = (id, app) => ({
+    id: 'custom/' + id, name: app.name, category: 'utilities', about: 'Your own program.', size: '?',
+    source: app.github && app.asset ? { github: app.github, asset: app.asset } : { url: app.url },
+    unpack: app.unpack, exe: app.exe, cli: app.cli,
+});
+/** The apps to install, in order: 7-Zip first when anything needs it to unpack. */
+export const appsToInstall = (apps, gitAccess) => {
+    const chosen = apps.install.flatMap((id) => { const e = appById(id); return e && !e.setting ? [e] : []; });
+    const skipped = chosen.filter((e) => e.fullGitOnly && gitAccess !== 'full').map((e) => e.name + ' (needs provisioning.git.access "full")');
+    const allowed = [...chosen.filter((e) => !(e.fullGitOnly && gitAccess !== 'full')), ...Object.entries(apps.custom).map(([id, app]) => customEntry(id, app))];
+    const needs7zip = allowed.some((e) => e.needs?.includes('7zip') || e.unpack === 'nsis') && !allowed.some((e) => e.id === '7zip');
+    return { entries: [...(needs7zip ? [appById('7zip')] : []), ...allowed], skipped };
+};
+/** Does any chosen app draw with OpenGL (so the Mesa step must run first)? */
+export const appsNeedMesa = (apps) => Boolean(apps?.install.some((id) => appById(id)?.needs?.includes('mesa')));

package/dist/shared/download.d.ts

@@ -15,9 +15,11 @@ export interface Checksums {
     sha256?: string | null;
     sha512?: string | null;
 }
+/** downloads.requireChecksum: from then on download() refuses anything it has no expected hash for. The guest sets it from session.json. */
+export declare const setChecksumRequired: (on: boolean) => void;
 /**
  * Streams a download to disk, hashing as it goes: big archives (PostgreSQL is ~330 MB) never sit in memory, and the
- * event loop stays free so other toolchains keep downloading meanwhile. A mismatch deletes the file.
+ * event loop stays free so other toolchains keep downloading meanwhile. A mismatch (or any failure) leaves no file behind.
  */
 export declare const download: (url: string, destination: string, expected?: string | null | Checksums) => Promise<void>;
 /** Runs a program without blocking the event loop (parallel downloads keep going); resolves with its exit code. */

package/dist/shared/download.js

@@ -43,12 +43,18 @@ export const fetchRetry = async (url, init = {}, attempts = 5, timeoutMs = 60000
 /** Small lookups fail fast (2 tries, 20 s each) so an offline boot falls back to cached versions quickly. */
 export const fetchJson = async (url) => await (await fetchRetry(url, { headers: { Accept: 'application/json' } }, 2, 20000)).json();
 export const fetchText = async (url) => await (await fetchRetry(url)).text();
+let checksumRequired = false;
+/** downloads.requireChecksum: from then on download() refuses anything it has no expected hash for. The guest sets it from session.json. */
+export const setChecksumRequired = (on) => { checksumRequired = on; };
 /**
  * Streams a download to disk, hashing as it goes: big archives (PostgreSQL is ~330 MB) never sit in memory, and the
- * event loop stays free so other toolchains keep downloading meanwhile. A mismatch deletes the file.
+ * event loop stays free so other toolchains keep downloading meanwhile. A mismatch (or any failure) leaves no file behind.
  */
 export const download = async (url, destination, expected = null) => {
     const sums = typeof expected === 'string' || expected === null ? { sha256: expected } : expected;
+    if (checksumRequired && !sums.sha256?.trim() && !sums.sha512?.trim()) {
+        throw new Error('Refusing to download ' + path.basename(destination) + ' (' + url + '): no checksum is published for it, and downloads.requireChecksum is on. Turn that setting off to allow downloads that cannot be verified.');
+    }
     const response = await fetchRetry(url, {}, 3, 20 * 60 * 1000);
     if (!response.body)
         throw new Error('Empty response for ' + url);
@@ -60,10 +66,19 @@ export const download = async (url, destination, expected = null) => {
     });
     const tap = new Transform({ transform(chunk, _encoding, done) { for (const c of checks)
             c.hash.update(chunk); done(null, chunk); } });
-    await pipeline(Readable.fromWeb(response.body), tap, fs.createWriteStream(destination));
-    if (checks.some((c) => c.hash.digest('hex') !== c.want)) {
+    // Written to <destination>.part and moved into place only once complete and verified, so an interrupted download never
+    // leaves a partial file under the real name.
+    const partial = destination + '.part';
+    try {
+        await pipeline(Readable.fromWeb(response.body), tap, fs.createWriteStream(partial));
+        if (checks.some((c) => c.hash.digest('hex') !== c.want))
+            throw new Error('Checksum mismatch for ' + url);
+        // Mapped folders refuse rename-over, so the old file goes first.
         fs.rmSync(destination, { force: true });
-        throw new Error('Checksum mismatch for ' + url);
+        fs.renameSync(partial, destination);
+    }
+    finally {
+        fs.rmSync(partial, { force: true });
     }
 };
 /** Runs a program without blocking the event loop (parallel downloads keep going); resolves with its exit code. */

package/dist/shared/netpolicy.d.ts

@@ -0,0 +1,27 @@
+/** A host name or a "*.example.com" pattern (lower case, no scheme, no port). */
+export declare const HOST_PATTERN: RegExp;
+/**
+ * What "@developer" stands for in allowOnly: package registries, source hosts, toolchain downloads and the AI
+ * providers the agents talk to. Enough for an agent to install dependencies, push to GitHub and reach its model.
+ */
+export declare const DEVELOPER_HOSTS: string[];
+/** The allowOnly list with "@developer" expanded, lower case, without duplicates. */
+export declare const expandAllowList: (list: string[]) => string[];
+/** Does `host` match one of the patterns? "*.example.com" matches its subdomains (not example.com itself). */
+export declare const hostAllowed: (host: string, patterns: string[]) => boolean;
+export declare const HOSTS_BEGIN = "# >>> windows-development-sandbox network.blockHosts";
+export declare const HOSTS_END = "# <<< windows-development-sandbox network.blockHosts";
+/** The hosts file with our block section replaced by `hosts` (each sent to 0.0.0.0 and ::); everything else stays. */
+export declare const withBlockedHosts: (hostsFile: string, hosts: string[]) => string;
+/** One forwarded port: <pc> on this PC (localhost only) reaches <sandbox> inside. */
+export interface PortForward {
+    pc: number;
+    sandbox: number;
+}
+/**
+ * The port the sandbox's relay for forward `index` listens on (it connects on to localhost:<sandbox> inside, so a
+ * server that only listens on localhost is reachable too). Out of the range Windows hands out for outgoing connections.
+ */
+export declare const relayPort: (index: number) => number;
+/** The address the sandbox's built-in proxy listens on (allowOnly). */
+export declare const PROXY_PORT = 38080;

package/dist/shared/netpolicy.js

@@ -0,0 +1,51 @@
+// The network settings as rules: which hosts the sandbox may reach (network.allowOnly), which never (blockHosts), and
+// the ports forwarded from this PC into the sandbox. Pure (tested); the guest applies them (guest/setup/network.ts,
+// guest/netproxy.ts) and the host runs the forwarders (host/port-forward.ts).
+/** A host name or a "*.example.com" pattern (lower case, no scheme, no port). */
+export const HOST_PATTERN = /^(\*\.)?([a-z0-9-]+\.)*[a-z0-9-]+$/i;
+/**
+ * What "@developer" stands for in allowOnly: package registries, source hosts, toolchain downloads and the AI
+ * providers the agents talk to. Enough for an agent to install dependencies, push to GitHub and reach its model.
+ */
+export const DEVELOPER_HOSTS = [
+    // AI providers
+    'api.anthropic.com', 'claude.ai', '*.claude.ai', 'console.anthropic.com', 'statsig.anthropic.com', 'sentry.io', '*.sentry.io',
+    'api.openai.com', 'chatgpt.com', '*.openai.com', 'generativelanguage.googleapis.com', 'oauth2.googleapis.com', 'accounts.google.com',
+    // source hosts
+    'github.com', '*.github.com', '*.githubusercontent.com', 'codeload.github.com', 'gitlab.com', '*.gitlab.com', 'bitbucket.org',
+    // package registries
+    'registry.npmjs.org', '*.npmjs.org', 'registry.yarnpkg.com', 'pypi.org', 'files.pythonhosted.org', 'crates.io', 'index.crates.io', 'static.crates.io',
+    'proxy.golang.org', 'sum.golang.org', 'repo1.maven.org', 'repo.maven.apache.org', 'plugins.gradle.org', 'services.gradle.org', 'api.nuget.org',
+    '*.nuget.org', 'rubygems.org', 'index.rubygems.org', 'repo.packagist.org', 'packagist.org', 'jsr.io', 'deno.land',
+    // toolchains
+    'nodejs.org', '*.nodejs.org', 'static.rust-lang.org', 'go.dev', 'dl.google.com', 'aka.ms', 'download.visualstudio.microsoft.com',
+    'dotnetcli.azureedge.net', 'builds.dotnet.microsoft.com', 'api.adoptium.net', 'objects.githubusercontent.com', 'marketplace.visualstudio.com',
+    '*.gallerycdn.vsassets.io', '*.vscode-cdn.net', 'update.code.visualstudio.com',
+];
+/** The allowOnly list with "@developer" expanded, lower case, without duplicates. */
+export const expandAllowList = (list) => [...new Set(list.flatMap((h) => (h.trim().toLowerCase() === '@developer' ? DEVELOPER_HOSTS : [h])).map((h) => h.trim().toLowerCase()).filter((h) => HOST_PATTERN.test(h)))];
+/** Does `host` match one of the patterns? "*.example.com" matches its subdomains (not example.com itself). */
+export const hostAllowed = (host, patterns) => {
+    const h = host.toLowerCase().replace(/\.$/, '');
+    return patterns.some((p) => (p.startsWith('*.') ? h.endsWith(p.slice(1)) && h.length > p.length - 1 : h === p));
+};
+export const HOSTS_BEGIN = '# >>> windows-development-sandbox network.blockHosts';
+export const HOSTS_END = '# <<< windows-development-sandbox network.blockHosts';
+/** The hosts file with our block section replaced by `hosts` (each sent to 0.0.0.0 and ::); everything else stays. */
+export const withBlockedHosts = (hostsFile, hosts) => {
+    const begin = hostsFile.indexOf(HOSTS_BEGIN);
+    const end = hostsFile.indexOf(HOSTS_END);
+    const outside = begin >= 0 && end > begin ? hostsFile.slice(0, begin) + hostsFile.slice(end + HOSTS_END.length) : hostsFile;
+    const clean = [...new Set(hosts.map((h) => h.trim().toLowerCase()).filter((h) => HOST_PATTERN.test(h) && !h.startsWith('*.')))];
+    const base = outside.replace(/\s+$/, '');
+    if (!clean.length)
+        return base + '\r\n';
+    return [base, HOSTS_BEGIN, ...clean.flatMap((h) => ['0.0.0.0 ' + h, ':: ' + h]), HOSTS_END, ''].join('\r\n');
+};
+/**
+ * The port the sandbox's relay for forward `index` listens on (it connects on to localhost:<sandbox> inside, so a
+ * server that only listens on localhost is reachable too). Out of the range Windows hands out for outgoing connections.
+ */
+export const relayPort = (index) => 38100 + index;
+/** The address the sandbox's built-in proxy listens on (allowOnly). */
+export const PROXY_PORT = 38080;

package/dist/shared/paths.d.ts

@@ -5,5 +5,10 @@ export declare const projectFolderName: (workspace: string) => string;
  * C:\Mirror\F\A\b, and programs that resolve real paths (realpath, GetFinalPathNameByHandle) report that one.
  */
 export declare const guestWorkspaceAliases: (guestWorkspace: string) => string[];
+/**
+ * A file or folder name that is safe to recreate on this PC. The sandbox can create names Windows would treat as devices
+ * (CON.jsonl opens the console), as streams (a:b), or that end in a dot or space (silently renamed); none of them are copied.
+ */
+export declare const isSafeFileName: (name: string) => boolean;
 /** Rewrites `from` to `to` wherever it appears as a whole path (raw, JSON-escaped or with forward slashes). */
 export declare const translatePaths: (text: string, from: string, to: string) => string;

package/dist/shared/paths.js

@@ -10,6 +10,12 @@ export const guestWorkspaceAliases = (guestWorkspace) => {
     const real = sandboxFolder(guestWorkspace);
     return real.toLowerCase() === guestWorkspace.toLowerCase() ? [guestWorkspace] : [real, guestWorkspace];
 };
+const DEVICE_NAME = /^(con|prn|aux|nul|conin\$|conout\$|com[0-9¹²³]|lpt[0-9¹²³])(\..*)?$/i;
+/**
+ * A file or folder name that is safe to recreate on this PC. The sandbox can create names Windows would treat as devices
+ * (CON.jsonl opens the console), as streams (a:b), or that end in a dot or space (silently renamed); none of them are copied.
+ */
+export const isSafeFileName = (name) => name !== '' && name.length <= 200 && name !== '.' && name !== '..' && !/[<>:"|?*/\\\x00-\x1f]/.test(name) && !/[. ]$/.test(name) && !DEVICE_NAME.test(name);
 const jsonEscaped = (p) => JSON.stringify(p).slice(1, -1);
 const escapeRegex = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 const forward = (p) => p.replace(/\\/g, '/');

package/dist/shared/projects.d.ts

@@ -0,0 +1,53 @@
+/** Where roots, boot-mapped projects and shared folders appear inside the sandbox. */
+export declare const PROJECTS_GUEST = "C:\\Projects";
+/** How a project got into the sandbox. */
+export type Mechanism = 'launch' | 'root' | 'boot' | 'wsb';
+/** One project the running sandbox works on. */
+export interface ProjectEntry {
+    name: string;
+    host: string;
+    guest: string;
+    primary: boolean;
+    mechanism: Mechanism;
+}
+/** `child` is `parent` or somewhere below it (Windows paths, case-insensitive). */
+export declare const isWithin: (parent: string, child: string) => boolean;
+/**
+ * A project id (also its folder name under C:\Projects) for a folder: its name with only letters, digits, '-' and
+ * '_' (ids become file names on both sides), at most 48 characters, made unique against `taken` with -2, -3, ...
+ */
+export declare const hubName: (hostDir: string, taken: Iterable<string>) => string;
+/** The project a folder on this PC belongs to: the most specific one that contains it (a project inside another wins). */
+export declare const projectForHostDir: <P extends {
+    host: string;
+}>(projects: P[], hostDir: string) => P | null;
+/** The same for a folder inside the sandbox. */
+export declare const projectForGuestDir: <P extends {
+    guest: string;
+}>(projects: P[], guestDir: string) => P | null;
+/** Where a folder on this PC appears inside the sandbox, given the mapped folder (project or root) that contains it. */
+export declare const guestDirFor: (mapped: {
+    host: string;
+    guest: string;
+}, hostDir: string) => string;
+/** The other way: where a folder inside the sandbox is on this PC, given the mapped folder that contains it. */
+export declare const hostDirFor: (mapped: {
+    host: string;
+    guest: string;
+}, guestDir: string) => string;
+/** Strictly below `parent` (never `parent` itself). */
+export declare const isBelow: (parent: string, child: string) => boolean;
+/** A guest folder some project can be in: below C:\Projects, or inside one of the roots (their guest paths). */
+export declare const insideProjects: (guestDir: string, roots?: string[], projectsDir?: string) => boolean;
+export interface RootMapping {
+    host: string;
+    guest: string;
+}
+/**
+ * Guest folders for the project roots and the projects mapped at boot: C:\Projects\<name>, unique; with
+ * guestWorkspace "mirror" a root appears at its PC path when the sandbox can show it there.
+ */
+export declare const planProjectMappings: (roots: string[], projects: string[], mirror: boolean, taken?: string[]) => {
+    roots: RootMapping[];
+    projects: RootMapping[];
+};