windows-development-sandbox 1.4.1 → 1.5.0

package/dist/shared/download.js

@@ -1,238 +0,0 @@
-// Download/extract helpers shared by the host (Windows Terminal pre-download) and the guest (toolchains).
-// Node built-ins only, so it stays small in both bundles (the CLI and the guest runtime).
-import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
-import { spawn } from 'node:child_process';
-import { Readable, Transform } from 'node:stream';
-import { pipeline } from 'node:stream/promises';
-import { safeRemove } from './safe-remove.js';
-import { SYSTEM } from './system.js';
-const USER_AGENT = 'windows-development-sandbox';
-/**
- * A fresh `<destination>.staging-<hex>` folder next to `destination`: fill it, then moveIntoPlace. An interrupted copy
- * or extraction leaves only the staging folder (cleanup/repair remove those), never a half-filled destination.
- */
-export const stagingFolder = (destination) => destination + '.staging-' + crypto.randomBytes(3).toString('hex');
-/** Replaces `destination` with the finished `work` folder (a folder rename: the destination is never half there). */
-export const moveIntoPlace = (work, destination) => {
-    safeRemove(destination, path.dirname(destination));
-    fs.mkdirSync(path.dirname(destination), { recursive: true });
-    fs.renameSync(work, destination);
-};
-/** fetch with retries (the sandbox network can take a few seconds to come up) and a timeout per attempt. */
-export const fetchRetry = async (url, init = {}, attempts = 5, timeoutMs = 60000) => {
-    let last;
-    for (let i = 1; i <= attempts; i++) {
-        try {
-            const response = await fetch(url, { ...init, signal: AbortSignal.timeout(timeoutMs), headers: { 'User-Agent': USER_AGENT, ...(init.headers ?? {}) } });
-            if (response.ok)
-                return response;
-            last = new Error('HTTP ' + response.status + ' for ' + url);
-            if (response.status === 404)
-                break;
-        }
-        catch (e) {
-            last = e;
-        }
-        if (i < attempts)
-            await new Promise((r) => setTimeout(r, 3000));
-    }
-    throw last instanceof Error ? last : new Error(String(last));
-};
-/** 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; };
-let downloadWatcher = null;
-export const watchDownloads = (watcher) => { downloadWatcher = watcher; };
-/**
- * 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 (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);
-    fs.mkdirSync(path.dirname(destination), { recursive: true });
-    // Only the hashes that will be checked (sha512 of a 330 MB archive is not free).
-    const checks = ['sha256', 'sha512'].flatMap((kind) => {
-        const want = sums[kind]?.trim().toLowerCase();
-        return want ? [{ want, hash: crypto.createHash(kind) }] : [];
-    });
-    // Progress for the boot screen: every 10% or 5 s at most, never per chunk; called here so it knows who is downloading.
-    const size = Number(response.headers.get('content-length')) || 0;
-    const report = size > 0 ? downloadWatcher?.() ?? null : null;
-    let received = 0;
-    let tenth = 0;
-    let reportedAt = Date.now();
-    const tap = new Transform({ transform(chunk, _encoding, done) {
-            for (const c of checks)
-                c.hash.update(chunk);
-            if (report) {
-                received += chunk.length;
-                const now = Math.floor((received * 10) / size);
-                if (now !== tenth || Date.now() - reportedAt > 5000) {
-                    tenth = now;
-                    reportedAt = Date.now();
-                    try {
-                        report(Math.min(1, received / size));
-                    }
-                    catch { /* progress never breaks a download */ }
-                }
-            }
-            done(null, chunk);
-        } });
-    // 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 });
-        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. */
-export const spawnAsync = (file, args, options = {}) => new Promise((resolve, reject) => {
-    const child = spawn(file, args, { stdio: 'ignore', windowsHide: true, ...options });
-    child.once('error', reject);
-    child.once('close', (code) => resolve(code ?? -1));
-});
-const toAsset = (asset) => ({ url: asset.browser_download_url, name: asset.name, sha256: asset.digest?.startsWith('sha256:') ? asset.digest.slice(7) : null });
-/**
- * Finds an asset in the latest GitHub release of `repo` (with its published sha256 when available). With
- * `searchOlder`, falls back to the newest stable release that still ships a matching asset (projects drop assets).
- */
-export const githubAsset = async (repo, pattern, searchOlder = false) => {
-    let latest;
-    try {
-        latest = await fetchJson('https://api.github.com/repos/' + repo + '/releases/latest');
-    }
-    catch (e) {
-        // The API allows 60 requests an hour per IP without a token; a first boot alone makes a dozen. The release page has
-        // the same assets and digests and no such limit.
-        if (!/HTTP (403|429)/.test(e instanceof Error ? e.message : ''))
-            throw e;
-        return githubAssetFromPage(repo, pattern, searchOlder);
-    }
-    const hit = latest.assets.find((a) => pattern.test(a.name));
-    if (hit)
-        return toAsset(hit);
-    if (searchOlder) {
-        const releases = await fetchJson('https://api.github.com/repos/' + repo + '/releases?per_page=100');
-        for (const release of releases.filter((r) => !r.prerelease && !r.draft)) {
-            const older = release.assets.find((a) => pattern.test(a.name));
-            if (older)
-                return toAsset(older);
-        }
-    }
-    throw new Error('No asset matching ' + pattern + ' in the ' + (searchOlder ? 'stable' : 'latest') + ' ' + repo + ' release(s)');
-};
-/** A release's assets from github.com's expanded_assets page (no API rate limit): each download link, then its sha256. */
-export const parseReleasePage = (html) => {
-    const links = [...html.matchAll(/href="(\/[^"]+\/releases\/download\/[^"]+)"/g)];
-    return links.map((link, i) => {
-        const digest = /sha256:([0-9a-f]{64})/.exec(html.slice(link.index, links[i + 1]?.index ?? html.length))?.[1] ?? null;
-        return { url: 'https://github.com' + link[1], name: decodeURIComponent(link[1].split('/').pop()), sha256: digest };
-    });
-};
-/** The latest release's tag, from github.com's own redirect (no API, no rate limit). */
-export const latestGithubTag = async (repo) => {
-    const latest = await fetchRetry('https://github.com/' + repo + '/releases/latest', {}, 2, 20000);
-    const tag = decodeURIComponent(latest.url.split('/releases/tag/')[1] ?? '');
-    return tag || Promise.reject(new Error('Could not find the latest release of ' + repo));
-};
-/** Release tags in the order github.com's /<repo>/releases page lists them (newest first), without duplicates. */
-export const parseReleaseTags = (html, repo) => {
-    const escaped = repo.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
-    const tags = [...html.matchAll(new RegExp('href="/' + escaped + '/releases/tag/([^"?#]+)"', 'gi'))].map((m) => decodeURIComponent(m[1]));
-    return [...new Set(tags)];
-};
-/** How many releases the rate-limit fallback looks through for `searchOlder` (one page request each). */
-const OLDER_RELEASES = 10;
-const githubAssetFromPage = async (repo, pattern, searchOlder) => {
-    const assetsOf = async (tag) => parseReleasePage(await fetchText('https://github.com/' + repo + '/releases/expanded_assets/' + encodeURIComponent(tag))).find((a) => pattern.test(a.name));
-    const latest = await latestGithubTag(repo);
-    const hit = await assetsOf(latest);
-    if (hit)
-        return hit;
-    // nvm-windows' portable zip and winlibs' builds only exist in older releases: walk the release list like the API path does.
-    if (searchOlder) {
-        const older = parseReleaseTags(await fetchText('https://github.com/' + repo + '/releases'), repo).filter((t) => t !== latest);
-        for (const tag of older.slice(0, OLDER_RELEASES)) {
-            const found = await assetsOf(tag);
-            if (found)
-                return found;
-        }
-    }
-    throw new Error('No asset matching ' + pattern + ' in ' + repo + ' ' + latest + (searchOlder ? ' or the releases before it' : ''));
-};
-/**
- * Extracts .zip / .nupkg / .7z / .tar.gz with the tar.exe that ships with Windows, falling back to Expand-Archive.
- * `members` limits it to those paths inside the archive (e.g. skip pgAdmin in the PostgreSQL zip).
- */
-export const extractArchive = async (archive, destination, members = []) => {
-    fs.mkdirSync(destination, { recursive: true });
-    let status = await spawnAsync(SYSTEM.tar(), ['-xf', archive, '-C', destination, ...members]);
-    if (status !== 0 && /\.(zip|nupkg)$/i.test(archive)) {
-        const zip = archive.endsWith('.zip') ? archive : archive + '.zip';
-        if (zip !== archive)
-            fs.copyFileSync(archive, zip);
-        status = await spawnAsync(SYSTEM.powershell(), ['-NoLogo', '-NoProfile', '-Command', "Expand-Archive -LiteralPath '" + zip.replace(/'/g, "''") + "' -DestinationPath '" + destination.replace(/'/g, "''") + "' -Force"]);
-    }
-    if (status !== 0)
-        throw new Error('Could not extract ' + archive);
-};
-export const findFile = (root, name, maxDepth = 4) => {
-    if (maxDepth < 0 || !fs.existsSync(root))
-        return null;
-    const entries = fs.readdirSync(root, { withFileTypes: true });
-    for (const entry of entries)
-        if (entry.isFile() && entry.name.toLowerCase() === name.toLowerCase())
-            return path.join(root, entry.name);
-    for (const entry of entries)
-        if (entry.isDirectory()) {
-            const found = findFile(path.join(root, entry.name), name, maxDepth - 1);
-            if (found)
-                return found;
-        }
-    return null;
-};
-/**
- * Downloads + extracts into `destination` atomically (staging folder, then rename). With `locate`, only the folder holding
- * that file is kept (`up` folders above it, e.g. locate ruby.exe with up 1 keeps the folder around bin).
- */
-export const installArchive = async (url, destination, options = {}) => {
-    const work = stagingFolder(destination);
-    try {
-        const archive = path.join(work, options.fileName ?? path.basename(new URL(url).pathname));
-        await download(url, archive, { sha256: options.sha256, sha512: options.sha512 });
-        const extracted = path.join(work, 'x');
-        await extractArchive(archive, extracted, options.members);
-        let root = extracted;
-        if (options.locate) {
-            const found = findFile(extracted, options.locate);
-            if (!found)
-                throw new Error(options.locate + ' not found in ' + url);
-            root = path.dirname(found);
-            for (let i = 0; i < (options.up ?? 0) && path.dirname(root).startsWith(extracted); i++)
-                root = path.dirname(root);
-        }
-        moveIntoPlace(root, destination);
-    }
-    finally {
-        safeRemove(work, path.dirname(work));
-    }
-};

package/dist/shared/guest-paths.d.ts

@@ -1,57 +0,0 @@
-/** Guest folders no mapping may use: the OS, the sandbox's own folders and the mirror root. */
-export declare const RESERVED_GUEST: RegExp;
-/** Where folders for other drive letters really live inside the sandbox: C:\Mirror\<letter>. */
-export declare const MIRROR_ROOT = "C:\\Mirror";
-/** Letters a mirrored path may use. Never C: (the sandbox's own disk); A:/B: are left alone (floppy-era tools). */
-export declare const MIRROR_LETTER: RegExp;
-/** The upper-case drive letter of an absolute guest path (F:\x -> F), or null. */
-export declare const guestDrive: (guest: string) => string | null;
-/**
- * A folder the sandbox can show a host folder at: C:\<not reserved>\... or <D-Z>:\..., never a drive root,
- * no '..' or empty segments, no characters Windows rejects in paths.
- */
-export declare const isValidGuestPath: (guest: string) => boolean;
-/** Where a mapping lands when the path it asks for (or the PC path) cannot be used inside the sandbox. */
-export declare const MAPPED_ROOT = "C:\\Mapped";
-/** A guest path as typed, tidied: '/' -> '\', no doubled or trailing backslashes, upper-case drive letter. */
-export declare const tidyGuestPath: (guest: string) => string;
-/** Why a guest path cannot be used as it is (null: it can). Short, plain English. */
-export declare const guestPathProblem: (guest: string) => string | null;
-/** C:\Mapped\<drive>\<rest of path>: a safe place for a folder whose own path cannot be used (odd characters made safe). */
-export declare const mappedFallback: (path: string) => string;
-/** Two guest folders overlap where they really are (F:\x is C:\Mirror\F\x): the same, or one inside the other. */
-export declare const guestOverlaps: (a: string, b: string) => boolean;
-/**
- * Where an extra folder appears in the sandbox. `wanted` is the guest path asked for (or the one derived from the PC
- * path); when the sandbox cannot use it (reserved, invalid, or overlapping a folder in `taken`), the folder goes to
- * C:\Mapped\<drive>\<path> instead (made unique with -2, -3 ...), and `note` says where and why.
- */
-export declare const placeGuest: (host: string, wanted: string, taken: {
-    guest: string;
-    what: string;
-}[]) => {
-    guest: string;
-    note: string | null;
-};
-/**
- * The guest path a mapping asks for when it gives none: a folder inside the project at the same place in the project's
- * guest folder, any other folder at the same path as on this PC (D: to Z: through C:\Mirror and subst).
- */
-export declare const deriveGuest: (host: string, projectHost: string, projectGuest: string) => string;
-/** Where a guest path really is inside the sandbox (the .wsb SandboxFolder): C: paths as-is, F:\x -> C:\Mirror\F\x. */
-export declare const sandboxFolder: (guest: string) => string;
-export interface SubstDrive {
-    letter: string;
-    target: string;
-}
-/** The subst drives the guest must create at boot for these guest paths, one per letter, sorted. */
-export declare const substDrives: (guests: string[]) => SubstDrive[];
-/**
- * guestWorkspace "mirror": the workspace at the same path as on this PC, so absolute paths (configs, build caches,
- * cargo fingerprints, Claude's project folder) match. Falls back to `fallback` (C:\Workspace\<name>) when the host
- * path cannot be used inside the sandbox (C:\Users\..., a UNC path, A:/B:, odd characters), with a note saying why.
- */
-export declare const planMirrorWorkspace: (workspaceHost: string, fallback: string) => {
-    guest: string;
-    note: string | null;
-};

package/dist/shared/guest-paths.js

@@ -1,129 +0,0 @@
-// Guest paths on drive letters other than C:. Windows Sandbox can only map folders onto its own C: drive, so a
-// guest path like F:\SteamLibrary\x is mapped to C:\Mirror\F\SteamLibrary\x and, at boot (bootstrap.ps1, before
-// anything else uses the workspace), `subst F: C:\Mirror\F` makes it appear at F:\SteamLibrary\x.
-// Pure functions only: used by the schema, the host (.wsb, session.json) and history sync.
-import { win32 } from 'node:path';
-/** Guest folders no mapping may use: the OS, the sandbox's own folders and the mirror root. */
-export const RESERVED_GUEST = /^C:\\(?:Windows|Program Files|Program Files \(x86\)|ProgramData|Users|AgentLaunch|AgentData|HostTools|nvm|Mirror)(?:\\|$)/i;
-/** Where folders for other drive letters really live inside the sandbox: C:\Mirror\<letter>. */
-export const MIRROR_ROOT = 'C:\\Mirror';
-/** Letters a mirrored path may use. Never C: (the sandbox's own disk); A:/B: are left alone (floppy-era tools). */
-export const MIRROR_LETTER = /^[D-Z]$/;
-const DRIVE_PATH = /^([A-Za-z]):\\(.*)$/;
-// No other ':' (alternate data streams), no wildcards or pipes, no control characters, no forward slashes.
-const BAD_CHARS = /[<>:"|?*/\x00-\x1f]/;
-/** The upper-case drive letter of an absolute guest path (F:\x -> F), or null. */
-export const guestDrive = (guest) => DRIVE_PATH.exec(guest)?.[1].toUpperCase() ?? null;
-/**
- * A folder the sandbox can show a host folder at: C:\<not reserved>\... or <D-Z>:\..., never a drive root,
- * no '..' or empty segments, no characters Windows rejects in paths.
- */
-export const isValidGuestPath = (guest) => {
-    const m = DRIVE_PATH.exec(guest);
-    if (!m)
-        return false;
-    const letter = m[1].toUpperCase();
-    const rest = m[2].replace(/\\+$/, '');
-    if (rest === '' || BAD_CHARS.test(rest))
-        return false;
-    if (rest.split('\\').some((segment) => segment === '' || segment === '.' || segment === '..' || /[. ]$/.test(segment)))
-        return false;
-    if (letter === 'C')
-        return !RESERVED_GUEST.test('C:\\' + rest);
-    return MIRROR_LETTER.test(letter);
-};
-/** Where a mapping lands when the path it asks for (or the PC path) cannot be used inside the sandbox. */
-export const MAPPED_ROOT = 'C:\\Mapped';
-/** A guest path as typed, tidied: '/' -> '\', no doubled or trailing backslashes, upper-case drive letter. */
-export const tidyGuestPath = (guest) => {
-    const p = guest.trim().replace(/\//g, '\\').replace(/\\{2,}/g, '\\').replace(/\\+$/, '');
-    return /^[a-z]:/.test(p) ? p[0].toUpperCase() + p.slice(1) : p;
-};
-/** Why a guest path cannot be used as it is (null: it can). Short, plain English. */
-export const guestPathProblem = (guest) => {
-    if (isValidGuestPath(guest))
-        return null;
-    const letter = guestDrive(guest);
-    if (letter === 'C' && RESERVED_GUEST.test(guest))
-        return guest + ' is a folder the sandbox keeps for itself (Windows, Program Files, Users, AgentData, ...)';
-    if (letter && !MIRROR_LETTER.test(letter) && letter !== 'C')
-        return 'the sandbox cannot show drive ' + letter + ':';
-    if (letter && /^[A-Za-z]:\\?$/.test(guest))
-        return guest + ' is a whole drive';
-    return guest + ' is not a folder path the sandbox can use';
-};
-/** C:\Mapped\<drive>\<rest of path>: a safe place for a folder whose own path cannot be used (odd characters made safe). */
-export const mappedFallback = (path) => {
-    const m = /^([A-Za-z]):\\?(.*)$/.exec(tidyGuestPath(path)) ?? /^\\\\(.*)$/.exec(path);
-    const letter = m && m.length === 3 ? m[1].toUpperCase() : 'UNC';
-    const rest = (m ? m[m.length - 1] : path).split(/[\\/]+/).map((s) => s.replace(/[<>:"|?*\x00-\x1f]/g, '_').replace(/[. ]+$/, '')).filter((s) => s !== '' && s !== '..').join('\\');
-    return MAPPED_ROOT + '\\' + letter + (rest ? '\\' + rest : '');
-};
-/** Two guest folders overlap where they really are (F:\x is C:\Mirror\F\x): the same, or one inside the other. */
-export const guestOverlaps = (a, b) => {
-    const x = sandboxFolder(a).replace(/\\+$/, '').toLowerCase();
-    const y = sandboxFolder(b).replace(/\\+$/, '').toLowerCase();
-    return x === y || x.startsWith(y + '\\') || y.startsWith(x + '\\');
-};
-/**
- * Where an extra folder appears in the sandbox. `wanted` is the guest path asked for (or the one derived from the PC
- * path); when the sandbox cannot use it (reserved, invalid, or overlapping a folder in `taken`), the folder goes to
- * C:\Mapped\<drive>\<path> instead (made unique with -2, -3 ...), and `note` says where and why.
- */
-export const placeGuest = (host, wanted, taken) => {
-    const clash = (g) => taken.find((t) => guestOverlaps(g, t.guest));
-    const tidy = tidyGuestPath(wanted);
-    const problem = guestPathProblem(tidy);
-    const other = problem ? null : clash(tidy);
-    if (!problem && !other)
-        return { guest: tidy, note: null };
-    const why = problem ?? tidy + ' is already used by ' + other.what + (other.guest.toLowerCase() === tidy.toLowerCase() ? '' : ' (' + other.guest + ')');
-    const guest = freePlace(mappedFallback(/^[A-Za-z]:/.test(tidy) ? tidy : host), clash);
-    return { guest, note: host + ': ' + why + ', so it is at ' + guest + ' in the sandbox.' };
-};
-/**
- * The guest path a mapping asks for when it gives none: a folder inside the project at the same place in the project's
- * guest folder, any other folder at the same path as on this PC (D: to Z: through C:\Mirror and subst).
- */
-export const deriveGuest = (host, projectHost, projectGuest) => {
-    const rel = win32.relative(win32.resolve(projectHost), win32.resolve(host));
-    const inside = rel === '' || (!rel.startsWith('..') && !win32.isAbsolute(rel));
-    return inside ? (rel ? win32.join(projectGuest, rel) : projectGuest) : tidyGuestPath(win32.resolve(host));
-};
-const freePlace = (base, clash) => {
-    const ok = (g) => isValidGuestPath(g) && !clash(g);
-    if (ok(base))
-        return base;
-    for (let i = 2; i < 1000; i++)
-        if (ok(base + '-' + i))
-            return base + '-' + i;
-    return base + '-' + Date.now();
-};
-/** Where a guest path really is inside the sandbox (the .wsb SandboxFolder): C: paths as-is, F:\x -> C:\Mirror\F\x. */
-export const sandboxFolder = (guest) => {
-    const m = DRIVE_PATH.exec(guest);
-    if (!m || m[1].toUpperCase() === 'C')
-        return guest;
-    return MIRROR_ROOT + '\\' + m[1].toUpperCase() + (m[2] ? '\\' + m[2] : '');
-};
-/** The subst drives the guest must create at boot for these guest paths, one per letter, sorted. */
-export const substDrives = (guests) => {
-    const letters = [...new Set(guests.map(guestDrive).filter((l) => l !== null && l !== 'C'))].sort();
-    return letters.map((letter) => ({ letter, target: MIRROR_ROOT + '\\' + letter }));
-};
-/**
- * guestWorkspace "mirror": the workspace at the same path as on this PC, so absolute paths (configs, build caches,
- * cargo fingerprints, Claude's project folder) match. Falls back to `fallback` (C:\Workspace\<name>) when the host
- * path cannot be used inside the sandbox (C:\Users\..., a UNC path, A:/B:, odd characters), with a note saying why.
- */
-export const planMirrorWorkspace = (workspaceHost, fallback) => {
-    const host = workspaceHost.replace(/\\+$/, '');
-    if (isValidGuestPath(host)) {
-        const letter = guestDrive(host);
-        return { guest: letter + host.slice(1), note: letter === 'C' ? null : 'guestWorkspace "mirror": ' + host + ' is mapped to ' + sandboxFolder(letter + host.slice(1)) + ' and shown as ' + letter + ': (subst) inside the sandbox.' };
-    }
-    const why = !guestDrive(host) ? 'it is not on a drive letter'
-        : guestDrive(host) === 'C' && RESERVED_GUEST.test(host) ? 'that folder is reserved inside the sandbox (Windows, Program Files, Users, ...)'
-            : 'the sandbox cannot show a folder at that path';
-    return { guest: fallback, note: 'guestWorkspace "mirror": ' + host + ' cannot appear at the same path (' + why + '); using ' + fallback + ' instead.' };
-};

package/dist/shared/netpolicy.d.ts

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

@@ -1,51 +0,0 @@
-// 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/netrules.d.ts

@@ -1,18 +0,0 @@
-/** Private, carrier-grade NAT (Tailscale and similar live here), link-local and multicast ranges. */
-export declare const PRIVATE_V4: string[];
-export declare const PRIVATE_V6: string[];
-export declare const RULE_NAMES: string[];
-export declare const isIPv4: (ip: string) => boolean;
-export declare const ipToInt: (ip: string) => number;
-export declare const intToIp: (n: number) => string;
-export declare const cidrToRange: (cidr: string) => [number, number];
-export declare const subtractIps: (ranges: [number, number][], ips: string[]) => [number, number][];
-export declare const formatRange: (range: [number, number]) => string;
-export declare const isPrivateV4: (ip: string) => boolean;
-export declare const parseDefaultGateways: (routePrint: string) => string[];
-/** The IPv4 servers in a dns.getServers() list ('8.8.8.8', '8.8.8.8:1053', '[::1]:53'); IPv6 ones are dropped. */
-export declare const ipv4DnsServers: (servers: string[]) => string[];
-/** Fallback only: the "DNS Servers" label is English, so this finds nothing on localised Windows (dns.getServers() does). */
-export declare const parseDnsServers: (ipconfigAll: string) => string[];
-/** netsh argument lists. Private ranges are blocked EXCEPT DNS/DHCP to the sandbox's own gateway, so name resolution keeps working. */
-export declare const buildFirewallCommands: (exemptIps: string[]) => string[][];

package/dist/shared/netrules.js

@@ -1,98 +0,0 @@
-/** Private, carrier-grade NAT (Tailscale and similar live here), link-local and multicast ranges. */
-export const PRIVATE_V4 = ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16', '100.64.0.0/10', '169.254.0.0/16', '224.0.0.0/4'];
-export const PRIVATE_V6 = ['fc00::/7', 'fe80::/10', 'ff00::/8'];
-export const RULE_NAMES = ['AgentSandbox-Block-Private', 'AgentSandbox-Block-IPv6-Local', 'AgentSandbox-Block-SMB', 'AgentSandbox-Gateway-TCP', 'AgentSandbox-Gateway-UDP'];
-export const isIPv4 = (ip) => {
-    const parts = ip.split('.');
-    return parts.length === 4 && parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255);
-};
-export const ipToInt = (ip) => {
-    if (!isIPv4(ip))
-        throw new Error('Invalid IPv4 address: ' + ip);
-    const p = ip.split('.').map(Number);
-    return p[0] * 16777216 + p[1] * 65536 + p[2] * 256 + p[3];
-};
-export const intToIp = (n) => {
-    return [Math.floor(n / 16777216) % 256, Math.floor(n / 65536) % 256, Math.floor(n / 256) % 256, n % 256].join('.');
-};
-export const cidrToRange = (cidr) => {
-    const [ip, bits] = cidr.split('/');
-    const size = 2 ** (32 - Number(bits));
-    const start = Math.floor(ipToInt(ip) / size) * size;
-    return [start, start + size - 1];
-};
-export const subtractIps = (ranges, ips) => {
-    let result = ranges.map((r) => [r[0], r[1]]);
-    for (const ip of ips) {
-        const n = ipToInt(ip);
-        const next = [];
-        for (const [start, end] of result) {
-            if (n < start || n > end) {
-                next.push([start, end]);
-                continue;
-            }
-            if (n > start)
-                next.push([start, n - 1]);
-            if (n < end)
-                next.push([n + 1, end]);
-        }
-        result = next;
-    }
-    return result;
-};
-export const formatRange = (range) => {
-    return range[0] === range[1] ? intToIp(range[0]) : intToIp(range[0]) + '-' + intToIp(range[1]);
-};
-export const isPrivateV4 = (ip) => {
-    const n = ipToInt(ip);
-    return PRIVATE_V4.some((c) => { const [s, e] = cidrToRange(c); return n >= s && n <= e; });
-};
-export const parseDefaultGateways = (routePrint) => {
-    const found = [];
-    for (const line of routePrint.split(/\r?\n/)) {
-        const m = /^\s*0\.0\.0\.0\s+0\.0\.0\.0\s+(\d{1,3}(?:\.\d{1,3}){3})\s/.exec(line);
-        if (m && isIPv4(m[1]))
-            found.push(m[1]);
-    }
-    return found;
-};
-/** The IPv4 servers in a dns.getServers() list ('8.8.8.8', '8.8.8.8:1053', '[::1]:53'); IPv6 ones are dropped. */
-export const ipv4DnsServers = (servers) => servers.map((s) => s.replace(/:\d+$/, '')).filter(isIPv4);
-/** Fallback only: the "DNS Servers" label is English, so this finds nothing on localised Windows (dns.getServers() does). */
-export const parseDnsServers = (ipconfigAll) => {
-    const found = [];
-    let inDns = false;
-    for (const line of ipconfigAll.split(/\r?\n/)) {
-        if (/DNS Servers/i.test(line)) {
-            inDns = true;
-            for (const m of line.matchAll(/(\d{1,3}(?:\.\d{1,3}){3})/g))
-                if (isIPv4(m[1]))
-                    found.push(m[1]);
-        }
-        else if (inDns && /^\s+\d{1,3}(?:\.\d{1,3}){3}\s*$/.test(line)) {
-            found.push(line.trim());
-        }
-        else {
-            inDns = false;
-        }
-    }
-    return found;
-};
-/** netsh argument lists. Private ranges are blocked EXCEPT DNS/DHCP to the sandbox's own gateway, so name resolution keeps working. */
-export const buildFirewallCommands = (exemptIps) => {
-    const exempt = [...new Set(exemptIps.filter((ip) => isIPv4(ip) && isPrivateV4(ip)))];
-    const v4 = subtractIps(PRIVATE_V4.map(cidrToRange), exempt).map(formatRange);
-    const add = (name, extra) => ['advfirewall', 'firewall', 'add', 'rule', 'name=' + name, 'dir=out', 'action=block', 'enable=yes', 'profile=any', ...extra];
-    const commands = [];
-    for (const name of RULE_NAMES)
-        commands.push(['advfirewall', 'firewall', 'delete', 'rule', 'name=' + name]);
-    commands.push(['advfirewall', 'set', 'allprofiles', 'state', 'on']);
-    commands.push(add('AgentSandbox-Block-Private', ['protocol=any', 'remoteip=' + v4.join(',')]));
-    commands.push(add('AgentSandbox-Block-IPv6-Local', ['protocol=any', 'remoteip=' + PRIVATE_V6.join(',')]));
-    commands.push(add('AgentSandbox-Block-SMB', ['protocol=tcp', 'remoteport=135,139,445']));
-    if (exempt.length > 0) {
-        commands.push(add('AgentSandbox-Gateway-TCP', ['protocol=tcp', 'remoteip=' + exempt.join(','), 'remoteport=1-52,54-65535']));
-        commands.push(add('AgentSandbox-Gateway-UDP', ['protocol=udp', 'remoteip=' + exempt.join(','), 'remoteport=1-52,54-66,69-65535']));
-    }
-    return commands;
-};

package/dist/shared/paths.d.ts

@@ -1,14 +0,0 @@
-/** Claude Code's per-project folder name: every non-alphanumeric character becomes '-' (F:\A\b -> F--A-b). */
-export declare const projectFolderName: (workspace: string) => string;
-/**
- * Every path the guest may know its workspace by, the real one first: a mirrored F:\A\b is a subst drive onto
- * 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;