windows-development-sandbox 1.4.1 → 1.4.3

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/pty-client.d.ts

@@ -1,108 +0,0 @@
-import net from 'node:net';
-export declare const FrameType: {
-    readonly Hello: 1;
-    readonly Input: 2;
-    readonly Resize: 3;
-    readonly Restart: 4;
-    readonly Ping: 5;
-    readonly Output: 16;
-    readonly Exit: 17;
-    readonly Error: 18;
-    readonly Restarting: 19;
-    readonly Status: 20;
-    readonly Console: 21;
-};
-/** HELLO flags: control-only connections get no output and never size the console; a query only asks for STATUS. */
-export declare const HelloFlag: {
-    readonly ControlOnly: 1;
-    readonly Query: 2;
-};
-/** Viewers ping this often; ptyhost counts a viewer as gone after 15 s of silence (e.g. its terminal tab was closed). */
-export declare const PING_INTERVAL_MS = 5000;
-export interface Frame {
-    type: number;
-    payload: Buffer;
-}
-export interface Endpoint {
-    addresses: string[];
-    port: number;
-    token: string;
-}
-export type ClientResult = {
-    reason: 'exit';
-    exitCode: number;
-} | {
-    reason: 'detach' | 'closed';
-} | {
-    reason: 'error';
-    message: string;
-};
-/** Turns off every mouse tracking mode a program may have turned on in your terminal (normal, button, any, UTF-8, SGR, urxvt). */
-export declare const MOUSE_OFF = "\u001B[?1000l\u001B[?1002l\u001B[?1003l\u001B[?1005l\u001B[?1006l\u001B[?1015l";
-/** Ctrl+] — the same detach key telnet uses; Claude Code does not bind it. */
-export declare const DETACH_KEY = 29;
-export declare const encodeFrame: (type: number, payload?: Buffer) => Buffer;
-export declare const helloFrame: (token: string, cols: number, rows: number, flags?: number) => Buffer;
-export declare const resizeFrame: (cols: number, rows: number) => Buffer;
-/** Same limit as ptyhost.cs; a peer announcing more is broken or hostile. */
-export declare const MAX_FRAME_BYTES: number;
-/** Splits a TCP byte stream back into frames. */
-export declare class FrameReader {
-    private pending;
-    push(chunk: Buffer): Frame[];
-}
-/**
- * Removes the terminal "strings" an untrusted program could abuse from the sandbox's output before it reaches your
- * terminal: clipboard writes (OSC 52), terminal macros (ConEmu's OSC 9), DCS / APC / PM / SOS, and their C1 forms.
- * Titles, links, progress and colours pass. A byte-level state machine, so no split across chunks, leading zero
- * (ESC]052) or huge payload slips through: a dropped string stays dropped until its terminator, however long it is.
- */
-export declare class OutputFilter {
-    /** text: normal output; esc: after ESC; c2: after a 0xC2 lead byte; string: inside an OSC/DCS/...; stringEsc / stringC2: a possible terminator inside one. */
-    private state;
-    /** The string being read: an OSC worth keeping is collected until its terminator; null = being dropped. */
-    private body;
-    push(chunk: Buffer): Buffer;
-}
-/** Tries every address the sandbox published and returns the first one that answers. */
-export declare const connect: (endpoint: Endpoint, timeoutMs?: number) => Promise<net.Socket>;
-/** Sends one control frame (e.g. RESTART) without taking over the screen. */
-export declare const sendControl: (endpoint: Endpoint, type: number) => Promise<void>;
-/** Who is watching a session right now: `remote` counts viewers on the PC (not the sandbox's own tabs). */
-export interface Viewers {
-    viewers: number;
-    remote: number;
-}
-/**
- * Asks a session's ptyhost who is attached. Only viewers heard from in the last few seconds count, so a terminal that
- * was closed (or a PC that went to sleep) is not reported. null when the session does not answer: an older ptyhost
- * treats the query as a silent control connection, so the caller must not assume anything.
- */
-export declare const queryViewers: (endpoint: Endpoint, timeoutMs?: number) => Promise<Viewers | null>;
-/**
- * Node on Windows reads keys through the console API, where Backspace is ^H and Ctrl+Backspace is DEL: the reverse of
- * what terminals send. ConPTY reads ^H as Ctrl+Backspace (delete a word), so swap them back.
- */
-export declare const fixWindowsKeys: (chunk: Buffer) => Buffer;
-/** How long an unfinished escape sequence is held back waiting for the rest (a lone Esc key press waits this long). */
-export declare const JOIN_MS = 30;
-/**
- * Keeps each escape sequence typed into your terminal (keys, mouse reports, the terminal's replies) in one INPUT frame.
- * The console can hand one over in pieces; ConPTY reads a lone "ESC[" as Alt+[ and the rest as typed text, so a split
- * Right arrow (ESC[C) left a stray "C" in the agent's prompt. An unfinished sequence at the end of a chunk is held
- * until the rest arrives (or JOIN_MS passes).
- */
-export declare class InputJoiner {
-    private held;
-    /** The bytes to send now; an unfinished sequence at the end is kept for the next chunk. */
-    push(chunk: Buffer): Buffer;
-    holding(): boolean;
-    flush(): Buffer;
-}
-/**
- * Bridges this process's terminal to the remote program until it exits, the connection drops, or the user presses
- * the detach key. Restores the terminal before resolving.
- */
-export declare const runTerminalClient: (socket: net.Socket, token: string, options?: {
-    detachKey?: number;
-}) => Promise<ClientResult>;