windows-development-sandbox 1.4.1 → 1.5.0

package/dist/shared/channel/schema.js

@@ -0,0 +1,133 @@
+// The host <-> sandbox channel messages, defined once with zod. Both sides parse what they read: the guest only acts on
+// these request kinds, and the host treats everything the guest writes as untrusted (shapes checked, sizes capped).
+import { z } from 'zod';
+import { HarnessSchema, ToolchainsSchema } from '../../core/schema/index.js';
+export const IdSchema = z.string().regex(/^[A-Za-z0-9_-]{1,64}$/, 'invalid id');
+const Text = (max = 4096) => z.string().max(max);
+const TimeSchema = Text(64);
+export const AttachEndpointSchema = z.strictObject({
+    addresses: z.array(Text(64)).max(16),
+    port: z.number().int().min(1024).max(65535),
+    token: Text(256),
+});
+/** The boot's progress in a shape the host can show: step n of m, what is being set up now, how many are done. */
+export const BootProgressSchema = z.strictObject({
+    step: z.number().int().min(1).max(32),
+    steps: z.number().int().min(1).max(32),
+    title: Text(120),
+    /** Being set up now; percent while it downloads (when the size is known). */
+    active: z.array(z.strictObject({ name: Text(64), percent: z.number().int().min(0).max(100).optional() })).max(8),
+    done: z.number().int().min(0).max(1000),
+    total: z.number().int().min(0).max(1000),
+});
+/** C:\AgentData\run\sandbox.json: boot progress of the sandbox as a whole. */
+export const SandboxStatusSchema = z.object({
+    launchId: Text(64),
+    phase: z.enum(['booting', 'provisioning', 'ready', 'failed']),
+    message: Text(),
+    updatedAt: TimeSchema,
+    workspaceHost: Text(),
+    guestWorkspace: Text(),
+    headless: z.boolean(),
+    /** The sandbox's IPv4 addresses (for network.forwardPorts; the host only uses ones on its Hyper-V network). */
+    addresses: z.array(z.string().max(45)).max(8).optional(),
+    /** A malformed progress is dropped, never the status (the phase still counts). */
+    progress: BootProgressSchema.optional().catch(undefined),
+});
+const VersionSchema = z.strictObject({ spec: Text(128), source: Text(256) });
+const DatabasePlanSchema = z.strictObject({
+    database: z.enum(['postgres', 'mysql', 'sqlserver', 'mongodb', 'redis', 'dynamodb']),
+    reasons: z.array(Text(1024)).max(32),
+    version: Text(64),
+    port: z.number().int().min(1024).max(65535),
+    adminPort: z.number().int().min(1024).max(65535).optional(),
+});
+/**
+ * A project the host registered after boot (sandbox claude from another folder): everything the guest needs to
+ * provision it and run its sessions with its own environment, resolved on the host exactly like a fresh launch (its
+ * approved .sandbox-config.json, version files, toolchain detection, database plan). Host -> guest only.
+ */
+export const ProjectSpecSchema = z.strictObject({
+    name: IdSchema,
+    /** Inside the sandbox: C:\Projects\<name>. */
+    workspace: Text(1024),
+    workspaceHost: Text(1024),
+    toolchains: ToolchainsSchema,
+    versions: z.strictObject({ node: VersionSchema, nodeExtra: z.array(Text(128)).max(16), python: VersionSchema }),
+    databases: z.array(DatabasePlanSchema).max(8),
+    /** Agents this project may start that the sandbox did not boot with (its .sandbox-config.json "harness"). */
+    harnesses: z.record(Text(64), HarnessSchema).refine((h) => Object.keys(h).length <= 8, 'at most 8 agents'),
+    /** Its hooks were staged in C:\AgentLaunch\projects\<name>\hooks. */
+    hooks: z.boolean(),
+});
+/** C:\AgentData\run\requests\<id>.json: the ONLY things the host can ask the sandbox to do. */
+export const GuestRequestSchema = z.discriminatedUnion('kind', [
+    z.strictObject({
+        kind: z.literal('session'),
+        id: IdSchema,
+        harness: Text(64),
+        args: z.array(Text()).max(256),
+        cwd: Text(),
+        project: ProjectSpecSchema.optional(),
+        harnessSpec: HarnessSchema.optional(),
+        createdAt: TimeSchema,
+    }),
+    /** Provision a registered project without starting an agent (sandbox start / exec / db from its folder). */
+    z.strictObject({ kind: z.literal('project'), id: IdSchema, project: ProjectSpecSchema, createdAt: TimeSchema }),
+    z.strictObject({
+        kind: z.literal('exec'),
+        id: IdSchema,
+        command: z.array(Text()).min(1).max(256),
+        cwd: Text(),
+        timeoutSeconds: z.number().positive().max(86400),
+        createdAt: TimeSchema,
+    }),
+    /** cwd: only the sessions in this folder or below (one project's); omitted = every session. */
+    z.strictObject({
+        kind: z.literal('restart'),
+        id: IdSchema,
+        harness: Text(64).nullable(),
+        cwd: Text().optional(),
+        createdAt: TimeSchema,
+    }),
+    z.strictObject({ kind: z.literal('ping'), id: IdSchema, createdAt: TimeSchema }),
+]);
+/** C:\AgentData\run\responses\<id>.json: the guest's reply. */
+export const GuestResponseSchema = z.object({
+    id: IdSchema,
+    ok: z.boolean(),
+    message: Text(65536),
+    exitCode: z.number().int().optional(),
+    stdout: Text(4 * 1024 * 1024).optional(),
+    stderr: Text(4 * 1024 * 1024).optional(),
+    finishedAt: TimeSchema,
+});
+/** C:\AgentData\run\sessions\<id>.json: one agent session (its own pseudo console and terminal tab). */
+export const SessionStatusSchema = z.object({
+    id: IdSchema,
+    launchId: Text(64),
+    harness: Text(64),
+    cwd: Text(),
+    /** The project it runs in: its hub name, or the launch folder's for the first project. */
+    project: Text(64).optional(),
+    phase: z.enum(['starting', 'running', 'exited', 'failed']),
+    message: Text(),
+    updatedAt: TimeSchema,
+    startedAt: TimeSchema,
+    /** The agent's own conversation this session is in (Claude: the file name of its .jsonl), once known. */
+    conversation: Text(128).optional(),
+    exitCode: z.number().int().optional(),
+    attach: AttachEndpointSchema.optional(),
+});
+/**
+ * C:\AgentData\run\projects\<name>.json: how far a project's provisioning is (guest-written, so validated and capped).
+ */
+export const ProjectStatusSchema = z.object({
+    name: IdSchema,
+    workspace: Text(1024),
+    phase: z.enum(['provisioning', 'ready', 'failed']),
+    message: Text(),
+    updatedAt: TimeSchema,
+    databases: z.array(z.object({ database: Text(32), port: z.number().int() })).max(16),
+    summary: z.array(Text(512)).max(64),
+});

package/dist/shared/download/archive.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 declare function stagingFolder(destination: string): string;
+/** Replaces `destination` with the finished `work` folder (a folder rename: the destination is never half there). */
+export declare function moveIntoPlace(work: string, destination: string): void;
+/**
+ * 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 declare function extractArchive(archive: string, destination: string, members?: string[]): Promise<void>;
+export declare function findFile(root: string, name: string, maxDepth?: number): string | null;

package/dist/shared/download/archive.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { safeRemove } from '../io/index.js';
+import { SYSTEM } from '../system.js';
+import { scriptArgs } from '../scripts.js';
+import { spawnAsync } from './spawn.js';
+/**
+ * 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 function stagingFolder(destination) {
+    return destination + '.staging-' + crypto.randomBytes(3).toString('hex');
+}
+/** Replaces `destination` with the finished `work` folder (a folder rename: the destination is never half there). */
+export function moveIntoPlace(work, destination) {
+    safeRemove(destination, path.dirname(destination));
+    fs.mkdirSync(path.dirname(destination), { recursive: true });
+    fs.renameSync(work, destination);
+}
+/**
+ * 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 async function extractArchive(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(), scriptArgs('expand-archive.ps1', ['-Archive', zip, '-Destination', destination]));
+    }
+    if (status !== 0)
+        throw new Error('Could not extract ' + archive);
+}
+export function 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;
+}

package/dist/shared/download/downloader.d.ts

@@ -0,0 +1,38 @@
+/** Expected checksums of a download; any that are given must match. */
+export interface Checksums {
+    sha256?: string | null;
+    sha512?: string | null;
+}
+export interface ArchiveOptions extends Checksums {
+    /** Keep only the folder holding this file. */
+    locate?: string;
+    /** Folders above `locate`'s to keep. */
+    up?: number;
+    fileName?: string;
+    members?: string[];
+}
+/**
+ * Who wants coarse download progress: called as a download starts (in the caller's async context), returns its
+ * reporter.
+ */
+export type DownloadWatcher = () => ((fraction: number) => void) | null;
+export declare class Downloader {
+    /** downloads.requireChecksum: refuse anything without an expected hash. The guest sets it from session.json. */
+    requireChecksum: boolean;
+    private watcher;
+    /** Reports coarse progress of the downloads that start from now on to `watcher` (null: stop). */
+    watch(watcher: DownloadWatcher | null): 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 (or any failure) leaves no file
+     * behind.
+     */
+    file(url: string, destination: string, expected?: string | null | Checksums): Promise<void>;
+    /**
+     * 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).
+     */
+    archive(url: string, destination: string, options?: ArchiveOptions): Promise<void>;
+}
+/** The one downloader of this process. */
+export declare const downloader: Downloader;

package/dist/shared/download/downloader.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { safeRemove } from '../io/index.js';
+import { fetchRetry } from './http.js';
+import { extractArchive, findFile, moveIntoPlace, stagingFolder } from './archive.js';
+export class Downloader {
+    /** downloads.requireChecksum: refuse anything without an expected hash. The guest sets it from session.json. */
+    requireChecksum = false;
+    watcher = null;
+    /** Reports coarse progress of the downloads that start from now on to `watcher` (null: stop). */
+    watch(watcher) {
+        this.watcher = 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.
+     */
+    async file(url, destination, expected = null) {
+        const sums = typeof expected === 'string' || expected === null ? { sha256: expected } : expected;
+        if (this.requireChecksum && !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 ? (this.watcher?.() ?? 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 });
+        }
+    }
+    /**
+     * 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).
+     */
+    async archive(url, destination, options = {}) {
+        const work = stagingFolder(destination);
+        try {
+            const archive = path.join(work, options.fileName ?? path.basename(new URL(url).pathname));
+            await this.file(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));
+        }
+    }
+}
+/** The one downloader of this process. */
+export const downloader = new Downloader();

package/dist/shared/download/github.d.ts

@@ -0,0 +1,18 @@
+export interface ReleaseAsset {
+    url: string;
+    name: string;
+    sha256: string | 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 declare function githubAsset(repo: string, pattern: RegExp, searchOlder?: boolean): Promise<ReleaseAsset>;
+/**
+ * A release's assets from github.com's expanded_assets page (no API rate limit): each download link, then its sha256.
+ */
+export declare function parseReleasePage(html: string): ReleaseAsset[];
+/** The latest release's tag, from github.com's own redirect (no API, no rate limit). */
+export declare function latestGithubTag(repo: string): Promise<string>;
+/** Release tags in the order github.com's /<repo>/releases page lists them (newest first), without duplicates. */
+export declare function parseReleaseTags(html: string, repo: string): string[];

package/dist/shared/download/github.js

@@ -0,0 +1,77 @@
+import { fetchJson, fetchRetry, fetchText } from './http.js';
+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 async function githubAsset(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 function 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 async function latestGithubTag(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 function 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' : ''));
+};

package/dist/shared/download/http.d.ts

@@ -0,0 +1,5 @@
+/** fetch with retries (the sandbox network can take a few seconds to come up) and a timeout per attempt. */
+export declare function fetchRetry(url: string, init?: RequestInit, attempts?: number, timeoutMs?: number): Promise<Response>;
+/** Small lookups fail fast (2 tries, 20 s each) so an offline boot falls back to cached versions quickly. */
+export declare function fetchJson<T>(url: string): Promise<T>;
+export declare function fetchText(url: string): Promise<string>;

package/dist/shared/download/http.js

@@ -0,0 +1,34 @@
+// 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).
+const USER_AGENT = 'windows-development-sandbox';
+/** fetch with retries (the sandbox network can take a few seconds to come up) and a timeout per attempt. */
+export async function fetchRetry(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 async function fetchJson(url) {
+    return (await (await fetchRetry(url, { headers: { Accept: 'application/json' } }, 2, 20000)).json());
+}
+export async function fetchText(url) {
+    return await (await fetchRetry(url)).text();
+}

package/dist/shared/download/index.d.ts

@@ -0,0 +1,5 @@
+export { fetchRetry, fetchJson, fetchText } from './http.js';
+export { stagingFolder, moveIntoPlace, extractArchive, findFile } from './archive.js';
+export { type ArchiveOptions, type Checksums, type DownloadWatcher, Downloader, downloader } from './downloader.js';
+export { spawnAsync } from './spawn.js';
+export { type ReleaseAsset, githubAsset, parseReleasePage, latestGithubTag, parseReleaseTags } from './github.js';

package/dist/shared/download/index.js

@@ -0,0 +1,5 @@
+export { fetchRetry, fetchJson, fetchText } from './http.js';
+export { stagingFolder, moveIntoPlace, extractArchive, findFile } from './archive.js';
+export { Downloader, downloader } from './downloader.js';
+export { spawnAsync } from './spawn.js';
+export { githubAsset, parseReleasePage, latestGithubTag, parseReleaseTags } from './github.js';

package/dist/shared/download/spawn.d.ts

@@ -0,0 +1,3 @@
+import { type SpawnOptions } from 'node:child_process';
+/** Runs a program without blocking the event loop (parallel downloads keep going); resolves with its exit code. */
+export declare function spawnAsync(file: string, args: string[], options?: SpawnOptions): Promise<number>;

package/dist/shared/download/spawn.js

@@ -0,0 +1,9 @@
+import { spawn } from 'node:child_process';
+/** Runs a program without blocking the event loop (parallel downloads keep going); resolves with its exit code. */
+export function spawnAsync(file, args, options = {}) {
+    return 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));
+    });
+}

package/dist/shared/io/index.d.ts

@@ -0,0 +1,3 @@
+export * from './json.js';
+export * from './json-file.js';
+export * from './safe-remove.js';

package/dist/shared/io/index.js

@@ -0,0 +1,3 @@
+export * from './json.js';
+export * from './json-file.js';
+export * from './safe-remove.js';

package/dist/shared/io/json-file.d.ts

@@ -0,0 +1,10 @@
+import type { z } from 'zod';
+export declare class JsonFile<T> {
+    private readonly schema;
+    readonly file: string;
+    constructor(schema: z.ZodType<T>, file: string);
+    read(): T | null;
+    write(value: T): void;
+    /** Reads, changes and writes back; returns what was written. */
+    update(change: (current: T | null) => T): T;
+}

package/dist/shared/io/json-file.js

@@ -0,0 +1,21 @@
+import { readValid, writeJsonAtomic } from './json.js';
+export class JsonFile {
+    schema;
+    file;
+    constructor(schema, file) {
+        this.schema = schema;
+        this.file = file;
+    }
+    read() {
+        return readValid(this.schema, this.file);
+    }
+    write(value) {
+        writeJsonAtomic(this.file, value);
+    }
+    /** Reads, changes and writes back; returns what was written. */
+    update(change) {
+        const next = change(this.read());
+        this.write(next);
+        return next;
+    }
+}

package/dist/shared/io/json.d.ts

@@ -0,0 +1,13 @@
+import type { z } from 'zod';
+/** Anything bigger than this from the other side is ignored (a compromised sandbox must not exhaust the host). */
+export declare const MAX_MESSAGE_BYTES: number;
+export declare function readJsonFile<T>(file: string): T | null;
+/** Reads and validates; a missing, oversized or malformed file is simply absent. */
+export declare function readValid<S extends z.ZodType>(schema: S, file: string): z.output<S> | null;
+/**
+ * Write to a uniquely named temp file and rename, so a reader on the other side of the mapped folder never sees half a
+ * file. The rename is retried briefly: antivirus or the other side's reader can hold the target for a moment.
+ */
+export declare function writeJsonAtomic(file: string, value: unknown): void;
+/** Same for any text file (two commands at once, or a watcher and a command, never leave a half-written file). */
+export declare function writeFileAtomic(file: string, text: string): void;

package/dist/shared/io/json.js

@@ -0,0 +1,51 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertTestWritable } from '../test-guard.js';
+/** Anything bigger than this from the other side is ignored (a compromised sandbox must not exhaust the host). */
+export const MAX_MESSAGE_BYTES = 8 * 1024 * 1024;
+export function readJsonFile(file) {
+    try {
+        if (fs.statSync(file).size > MAX_MESSAGE_BYTES)
+            return null;
+        return JSON.parse(fs.readFileSync(file, 'utf8').replace(/^\uFEFF/, ''));
+    }
+    catch {
+        return null;
+    }
+}
+/** Reads and validates; a missing, oversized or malformed file is simply absent. */
+export function readValid(schema, file) {
+    const parsed = schema.safeParse(readJsonFile(file));
+    return parsed.success ? parsed.data : null;
+}
+const pause = (ms) => {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+};
+/**
+ * Write to a uniquely named temp file and rename, so a reader on the other side of the mapped folder never sees half a
+ * file. The rename is retried briefly: antivirus or the other side's reader can hold the target for a moment.
+ */
+export function writeJsonAtomic(file, value) {
+    return writeFileAtomic(file, JSON.stringify(value, null, 2) + '\n');
+}
+/** Same for any text file (two commands at once, or a watcher and a command, never leave a half-written file). */
+export function writeFileAtomic(file, text) {
+    assertTestWritable(file);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temp = file + '.' + process.pid + '-' + Math.random().toString(36).slice(2) + '.tmp';
+    fs.writeFileSync(temp, text, { encoding: 'utf8', flag: 'wx' });
+    for (let attempt = 1;; attempt++) {
+        try {
+            fs.renameSync(temp, file);
+            return;
+        }
+        catch (e) {
+            const code = e.code;
+            if (attempt >= 8 || (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES')) {
+                fs.rmSync(temp, { force: true });
+                throw e;
+            }
+            pause(50 * attempt);
+        }
+    }
+}

package/dist/shared/io/safe-remove.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Why `target` may not be deleted, or null when it may. Refused: a relative path, a drive root, a protected folder or
+ * any folder that contains one, and anything that is not strictly inside `root`.
+ */
+export declare function removeRefusal(target: string, root: string): string | null;
+/**
+ * Deletes `target` (a folder tree or file) only when it is strictly inside `root` and nothing protected; a link is
+ * removed itself, never followed. Throws instead of deleting anything else.
+ */
+export declare function safeRemove(target: string, root: string): void;