windows-development-sandbox 1.4.0 → 1.4.3

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

@@ -0,0 +1,2 @@
+export { type AppCategory, APP_CATEGORIES, type AppSource, type AppEntry, APPS, appById } from './catalogue.js';
+export { exeMatcher, appsToInstall, appsNeedMesa } from './selection.js';

package/dist/shared/apps/index.js

@@ -0,0 +1,2 @@
+export { APP_CATEGORIES, APPS, appById } from './catalogue.js';
+export { exeMatcher, appsToInstall, appsNeedMesa } from './selection.js';

package/dist/shared/apps/selection.d.ts

@@ -0,0 +1,11 @@
+import type { Config, GitAccess } from '../../core/types.js';
+import { type AppEntry } from './catalogue.js';
+/** 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/selection.js

@@ -0,0 +1,40 @@
+import { appById } from './catalogue.js';
+/** 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/channel/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schema.js';
+export * from './run-dir.js';

package/dist/shared/channel/index.js

@@ -0,0 +1,2 @@
+export * from './schema.js';
+export * from './run-dir.js';

package/dist/shared/channel/run-dir.d.ts

@@ -0,0 +1,30 @@
+import type { GuestRequest, GuestResponse, ProjectStatus, SandboxStatus, SessionStatus } from './schema.js';
+/** Ids become file names, so only a strict alphabet is allowed (no separators, no dots). */
+export declare function safeId(id: string): string;
+export declare function now(): string;
+/** The run folder of one data folder: where each message lives, and reading them validated. */
+export declare class RunDir {
+    readonly root: string;
+    readonly sandboxFile: string;
+    readonly requestsDir: string;
+    readonly responsesDir: string;
+    readonly sessionsDir: string;
+    readonly projectsDir: string;
+    /** audit.processes: programs the sandbox started, in small .jsonl files the host takes in and deletes. */
+    readonly auditDir: string;
+    constructor(dataDir: string);
+    requestFile(id: string): string;
+    responseFile(id: string): string;
+    sessionFile(id: string): string;
+    projectFile(name: string): string;
+    readSandboxStatus(): SandboxStatus | null;
+    readSession(id: string): SessionStatus | null;
+    readResponse(id: string): GuestResponse | null;
+    listSessions(): SessionStatus[];
+    readProjectStatus(name: string): ProjectStatus | null;
+    listProjectStatus(): ProjectStatus[];
+    scanRequests(): {
+        valid: GuestRequest[];
+        invalid: string[];
+    };
+}

package/dist/shared/channel/run-dir.js

@@ -0,0 +1,84 @@
+// The run folder (<data>\run on the host, C:\AgentData\run in the sandbox) is the host <-> sandbox channel. No
+// network needed: boot status, requests (host -> guest) and responses/status (guest -> host) are small JSON files,
+// written atomically and parsed with the channel schemas on read. Anything that does not parse is ignored.
+import fs from 'node:fs';
+import path from 'node:path';
+import { GuestRequestSchema, GuestResponseSchema, IdSchema, ProjectStatusSchema, SandboxStatusSchema, SessionStatusSchema, } from './schema.js';
+import { readValid } from '../io/index.js';
+/** Ids become file names, so only a strict alphabet is allowed (no separators, no dots). */
+export function safeId(id) {
+    return IdSchema.parse(id);
+}
+export function now() {
+    return new Date().toISOString();
+}
+/** Message files in a folder (strict names only), validated; invalid ones are reported separately for deletion. */
+const scan = (schema, dir) => {
+    if (!fs.existsSync(dir))
+        return { valid: [], invalid: [] };
+    const valid = [];
+    const invalid = [];
+    for (const name of fs.readdirSync(dir)) {
+        if (name.endsWith('.tmp'))
+            continue;
+        const message = /^[A-Za-z0-9_-]{1,64}\.json$/.test(name) ? readValid(schema, path.join(dir, name)) : null;
+        if (message)
+            valid.push(message);
+        else
+            invalid.push(path.join(dir, name));
+    }
+    return { valid, invalid };
+};
+/** The run folder of one data folder: where each message lives, and reading them validated. */
+export class RunDir {
+    root;
+    sandboxFile;
+    requestsDir;
+    responsesDir;
+    sessionsDir;
+    projectsDir;
+    /** audit.processes: programs the sandbox started, in small .jsonl files the host takes in and deletes. */
+    auditDir;
+    constructor(dataDir) {
+        this.root = path.join(dataDir, 'run');
+        this.sandboxFile = path.join(this.root, 'sandbox.json');
+        this.requestsDir = path.join(this.root, 'requests');
+        this.responsesDir = path.join(this.root, 'responses');
+        this.sessionsDir = path.join(this.root, 'sessions');
+        this.projectsDir = path.join(this.root, 'projects');
+        this.auditDir = path.join(this.root, 'audit');
+    }
+    requestFile(id) {
+        return path.join(this.requestsDir, safeId(id) + '.json');
+    }
+    responseFile(id) {
+        return path.join(this.responsesDir, safeId(id) + '.json');
+    }
+    sessionFile(id) {
+        return path.join(this.sessionsDir, safeId(id) + '.json');
+    }
+    projectFile(name) {
+        return path.join(this.projectsDir, safeId(name) + '.json');
+    }
+    readSandboxStatus() {
+        return readValid(SandboxStatusSchema, this.sandboxFile);
+    }
+    readSession(id) {
+        return readValid(SessionStatusSchema, this.sessionFile(id));
+    }
+    readResponse(id) {
+        return readValid(GuestResponseSchema, this.responseFile(id));
+    }
+    listSessions() {
+        return scan(SessionStatusSchema, this.sessionsDir).valid.sort((a, b) => a.startedAt.localeCompare(b.startedAt));
+    }
+    readProjectStatus(name) {
+        return readValid(ProjectStatusSchema, this.projectFile(name));
+    }
+    listProjectStatus() {
+        return scan(ProjectStatusSchema, this.projectsDir).valid.slice(0, 64);
+    }
+    scanRequests() {
+        return scan(GuestRequestSchema, this.requestsDir);
+    }
+}

package/dist/shared/{schema.d.ts → channel/schema.d.ts}

@@ -1,12 +1,24 @@
 import { z } from 'zod';
-export declare const Id: z.ZodString;
-export declare const AttachEndpoint: z.ZodObject<{
+export declare const IdSchema: z.ZodString;
+export declare const AttachEndpointSchema: z.ZodObject<{
     addresses: z.ZodArray<z.ZodString>;
     port: z.ZodNumber;
     token: z.ZodString;
 }, z.core.$strict>;
+/** 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 declare const BootProgressSchema: z.ZodObject<{
+    step: z.ZodNumber;
+    steps: z.ZodNumber;
+    title: z.ZodString;
+    active: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        percent: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    done: z.ZodNumber;
+    total: z.ZodNumber;
+}, z.core.$strict>;
 /** C:\AgentData\run\sandbox.json: boot progress of the sandbox as a whole. */
-export declare const SandboxStatus: z.ZodObject<{
+export declare const SandboxStatusSchema: z.ZodObject<{
     launchId: z.ZodString;
     phase: z.ZodEnum<{
         provisioning: "provisioning";
@@ -20,13 +32,24 @@ export declare const SandboxStatus: z.ZodObject<{
     guestWorkspace: z.ZodString;
     headless: z.ZodBoolean;
     addresses: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    progress: z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        step: z.ZodNumber;
+        steps: z.ZodNumber;
+        title: z.ZodString;
+        active: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            percent: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        done: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strict>>>;
 }, z.core.$strip>;
 /**
  * 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 declare const ProjectSpec: z.ZodObject<{
+export declare const ProjectSpecSchema: z.ZodObject<{
     name: z.ZodString;
     workspace: z.ZodString;
     workspaceHost: z.ZodString;
@@ -53,6 +76,11 @@ export declare const ProjectSpec: z.ZodObject<{
             targets: z.ZodArray<z.ZodString>;
             crates: z.ZodArray<z.ZodString>;
             targetDir: z.ZodString;
+            linker: z.ZodEnum<{
+                lld: "lld";
+                gnu: "gnu";
+            }>;
+            linkSlots: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodNumber]>;
         }, z.core.$strict>;
         msvc: z.ZodObject<{
             enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
@@ -140,10 +168,10 @@ export declare const ProjectSpec: z.ZodObject<{
         database: z.ZodEnum<{
             postgres: "postgres";
             mysql: "mysql";
+            sqlserver: "sqlserver";
             mongodb: "mongodb";
             redis: "redis";
             dynamodb: "dynamodb";
-            sqlserver: "sqlserver";
         }>;
         reasons: z.ZodArray<z.ZodString>;
         version: z.ZodString;
@@ -164,7 +192,7 @@ export declare const ProjectSpec: z.ZodObject<{
     hooks: z.ZodBoolean;
 }, z.core.$strict>;
 /** C:\AgentData\run\requests\<id>.json: the ONLY things the host can ask the sandbox to do. */
-export declare const GuestRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
+export declare const GuestRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"session">;
     id: z.ZodString;
     harness: z.ZodString;
@@ -197,6 +225,11 @@ export declare const GuestRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 targets: z.ZodArray<z.ZodString>;
                 crates: z.ZodArray<z.ZodString>;
                 targetDir: z.ZodString;
+                linker: z.ZodEnum<{
+                    lld: "lld";
+                    gnu: "gnu";
+                }>;
+                linkSlots: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodNumber]>;
             }, z.core.$strict>;
             msvc: z.ZodObject<{
                 enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
@@ -284,10 +317,10 @@ export declare const GuestRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
             database: z.ZodEnum<{
                 postgres: "postgres";
                 mysql: "mysql";
+                sqlserver: "sqlserver";
                 mongodb: "mongodb";
                 redis: "redis";
                 dynamodb: "dynamodb";
-                sqlserver: "sqlserver";
             }>;
             reasons: z.ZodArray<z.ZodString>;
             version: z.ZodString;
@@ -349,6 +382,11 @@ export declare const GuestRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
                 targets: z.ZodArray<z.ZodString>;
                 crates: z.ZodArray<z.ZodString>;
                 targetDir: z.ZodString;
+                linker: z.ZodEnum<{
+                    lld: "lld";
+                    gnu: "gnu";
+                }>;
+                linkSlots: z.ZodUnion<readonly [z.ZodLiteral<"auto">, z.ZodNumber]>;
             }, z.core.$strict>;
             msvc: z.ZodObject<{
                 enabled: z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"auto">]>;
@@ -436,10 +474,10 @@ export declare const GuestRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
             database: z.ZodEnum<{
                 postgres: "postgres";
                 mysql: "mysql";
+                sqlserver: "sqlserver";
                 mongodb: "mongodb";
                 redis: "redis";
                 dynamodb: "dynamodb";
-                sqlserver: "sqlserver";
             }>;
             reasons: z.ZodArray<z.ZodString>;
             version: z.ZodString;
@@ -479,7 +517,7 @@ export declare const GuestRequest: z.ZodDiscriminatedUnion<[z.ZodObject<{
     createdAt: z.ZodString;
 }, z.core.$strict>], "kind">;
 /** C:\AgentData\run\responses\<id>.json: the guest's reply. */
-export declare const GuestResponse: z.ZodObject<{
+export declare const GuestResponseSchema: z.ZodObject<{
     id: z.ZodString;
     ok: z.ZodBoolean;
     message: z.ZodString;
@@ -489,7 +527,7 @@ export declare const GuestResponse: z.ZodObject<{
     finishedAt: z.ZodString;
 }, z.core.$strip>;
 /** C:\AgentData\run\sessions\<id>.json: one agent session (its own pseudo console and terminal tab). */
-export declare const SessionStatus: z.ZodObject<{
+export declare const SessionStatusSchema: z.ZodObject<{
     id: z.ZodString;
     launchId: z.ZodString;
     harness: z.ZodString;
@@ -511,8 +549,10 @@ export declare const SessionStatus: z.ZodObject<{
         token: z.ZodString;
     }, z.core.$strict>>;
 }, z.core.$strip>;
-/** C:\AgentData\run\projects\<name>.json: how far a project's provisioning is (guest-written, so validated and capped). */
-export declare const ProjectStatus: z.ZodObject<{
+/**
+ * C:\AgentData\run\projects\<name>.json: how far a project's provisioning is (guest-written, so validated and capped).
+ */
+export declare const ProjectStatusSchema: z.ZodObject<{
     name: z.ZodString;
     workspace: z.ZodString;
     phase: z.ZodEnum<{
@@ -528,10 +568,11 @@ export declare const ProjectStatus: z.ZodObject<{
     }, z.core.$strip>>;
     summary: z.ZodArray<z.ZodString>;
 }, z.core.$strip>;
-export type ProjectSpecT = z.output<typeof ProjectSpec>;
-export type ProjectStatusT = z.output<typeof ProjectStatus>;
-export type AttachEndpointT = z.output<typeof AttachEndpoint>;
-export type SandboxStatusT = z.output<typeof SandboxStatus>;
-export type GuestRequestT = z.output<typeof GuestRequest>;
-export type GuestResponseT = z.output<typeof GuestResponse>;
-export type SessionStatusT = z.output<typeof SessionStatus>;
+export type ProjectSpec = z.output<typeof ProjectSpecSchema>;
+export type ProjectStatus = z.output<typeof ProjectStatusSchema>;
+export type AttachEndpoint = z.output<typeof AttachEndpointSchema>;
+export type SandboxStatus = z.output<typeof SandboxStatusSchema>;
+export type BootProgress = z.output<typeof BootProgressSchema>;
+export type GuestRequest = z.output<typeof GuestRequestSchema>;
+export type GuestResponse = z.output<typeof GuestResponseSchema>;
+export type SessionStatus = z.output<typeof SessionStatusSchema>;

package/dist/shared/channel/schema.js

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

package/dist/shared/download/archive.js

@@ -0,0 +1,57 @@
+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 { 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 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);
+};
+/**
+ * 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;
+};

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

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