windows-development-sandbox 1.0.5 → 1.4.0

package/dist/guest/apps/index.js

@@ -0,0 +1,206 @@
+// Installs the apps you chose (apps.install from the catalogue, apps.custom of your own) into C:\AgentData\tools\apps,
+// once each: later sandboxes find them there. Programs get a desktop and Start menu shortcut; command-line tools go on
+// PATH. Installers are never run: archives are unpacked, NSIS installers opened with 7-Zip and MSIs extracted
+// (msiexec /a), so nothing is registered and nothing is lost when the sandbox closes. One app failing never stops the
+// others.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { appsToInstall, exeMatcher } from '../../shared/apps.js';
+import { download, extractArchive, githubAsset, moveIntoPlace, stagingFolder } from '../../shared/download.js';
+import { safeRemove } from '../../shared/safe-remove.js';
+import { SYSTEM } from '../../shared/system.js';
+import { dryRun, errMsg, execAsync, exists, log, mkdirp, powershell, warn } from '../env.js';
+import { arch, tool } from '../toolchains/common.js';
+import { RESOLVERS } from './resolvers.js';
+export { appsNeedMesa } from '../../shared/apps.js';
+const MARKER = '.agent-sandbox-app';
+/** How many apps download and unpack at once (they are big: a few at a time keeps the disk and network busy). */
+const PARALLEL = 3;
+const sevenZip = () => tool('apps', '7zip', '7z.exe');
+/** Where to download an entry from. */
+const resolve = async (entry) => {
+    const s = entry.source;
+    if ('github' in s) {
+        const a = await githubAsset(s.github, new RegExp(s.asset), true);
+        return { url: a.url, fileName: a.name, sha256: a.sha256 };
+    }
+    if ('url' in s) {
+        const name = decodeURIComponent(new URL(s.url).pathname.split('/').pop() || entry.id);
+        return { url: s.url, fileName: /\.\w{2,5}$/.test(name) ? name : name + '.zip' };
+    }
+    if ('resolve' in s && RESOLVERS[s.resolve])
+        return RESOLVERS[s.resolve]();
+    throw new Error('no download source for ' + entry.name);
+};
+/** The program in an installed folder (breadth first, bounded: big apps have tens of thousands of files). */
+export const findExe = (root, exe) => {
+    const match = exeMatcher(exe);
+    let queue = [root];
+    let seen = 0;
+    for (let depth = 0; depth < 7 && queue.length; depth++) {
+        const next = [];
+        for (const dir of queue) {
+            let entries;
+            try {
+                entries = fs.readdirSync(dir, { withFileTypes: true });
+            }
+            catch {
+                continue;
+            }
+            const hit = entries.find((e) => e.isFile() && match(e.name));
+            if (hit)
+                return path.join(dir, hit.name);
+            next.push(...entries.filter((e) => e.isDirectory() && !e.isSymbolicLink()).map((e) => path.join(dir, e.name)));
+            if ((seen += entries.length) > 50000)
+                return null;
+        }
+        queue = next;
+    }
+    return null;
+};
+/** Downloads and unpacks one entry into its folder (replaced in one step: never half there). */
+const installApp = async (entry, dest) => {
+    const work = stagingFolder(dest);
+    const out = path.join(work, 'out');
+    try {
+        if ('npm' in entry.source) {
+            const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+            log('Installing ' + entry.name + ' (npm) ...');
+            await execAsync(process.execPath, [npmCli, 'install', '--prefix', mkdirp(out), '--no-audit', '--no-fund', '--loglevel=error', entry.source.npm]);
+        }
+        else {
+            const d = await resolve(entry);
+            log('Downloading ' + entry.name + ' (' + d.fileName + ', ~' + entry.size + ' once) ...');
+            const file = path.join(mkdirp(work), d.fileName.replace(/[\\/:*?"<>|]/g, '_'));
+            await download(d.url, file, { sha256: d.sha256 ?? null });
+            await unpack(entry, file, out, d);
+        }
+        fs.writeFileSync(path.join(out, MARKER), JSON.stringify({ id: entry.id, at: new Date().toISOString() }));
+        moveIntoPlace(out, dest);
+    }
+    finally {
+        safeRemove(work, path.dirname(work));
+    }
+};
+const unpack = async (entry, file, out, d) => {
+    if (entry.id === '7zip') {
+        // 7zr.exe (the small standalone 7-Zip) opens the full 7-Zip's installer.
+        const sevenZr = path.join(path.dirname(file), '7zr.exe');
+        const zr = await githubAsset('ip7z/7zip', /^7zr\.exe$/);
+        await download(zr.url, sevenZr, zr.sha256);
+        await execAsync(sevenZr, ['x', '-y', '-o' + out, file], { stdio: 'ignore' });
+        return;
+    }
+    switch (entry.unpack ?? 'archive') {
+        case 'file': {
+            mkdirp(out);
+            fs.renameSync(file, path.join(out, /^\//.test(entry.exe) ? path.basename(file) : entry.exe));
+            return;
+        }
+        case 'nsis': {
+            if (!exists(sevenZip()))
+                throw new Error('7-Zip is needed to unpack ' + entry.name + ' and could not be installed');
+            const raw = path.join(path.dirname(out), 'raw');
+            await execAsync(sevenZip(), ['x', '-y', '-o' + raw, file], { stdio: 'ignore' });
+            // electron-builder installers carry the app as one more archive inside.
+            const inner = findExe(raw, '/^app-64\\.7z$/');
+            if (inner)
+                await execAsync(sevenZip(), ['x', '-y', '-o' + out, inner], { stdio: 'ignore' });
+            else
+                fs.renameSync(raw, out);
+            return;
+        }
+        case 'msi': {
+            // An administrative install only extracts the files: nothing is registered with Windows.
+            mkdirp(out);
+            await execAsync(SYSTEM.msiexec(), ['/a', file, '/qn', 'TARGETDIR=' + out], { stdio: 'ignore' });
+            return;
+        }
+        default:
+            await extractArchive(file, out, d.members);
+    }
+};
+/** Settings an app needs on every boot (the sandbox's registry is new each time), and files next to its program. */
+const afterInstall = async (entry, exe) => {
+    const dir = path.dirname(exe);
+    if (entry.needs?.includes('mesa')) {
+        const mesa = tool('mesa', arch === 'arm64' ? 'arm64' : 'x64');
+        for (const dll of ['opengl32.dll', 'libgallium_wgl.dll', 'dxil.dll']) {
+            if (exists(path.join(mesa, dll)) && !exists(path.join(dir, dll)))
+                fs.copyFileSync(path.join(mesa, dll), path.join(dir, dll));
+        }
+    }
+    // Godot and Sublime keep their settings next to the program instead of in the profile, which is wiped on close.
+    if (entry.id === 'godot' && !exists(path.join(dir, '._sc_')))
+        fs.writeFileSync(path.join(dir, '._sc_'), '');
+    if (entry.id === 'sublime')
+        mkdirp(path.join(dir, 'Data'));
+    if (entry.id === 'sysinternals') {
+        for (const name of ['Process Explorer', 'Process Monitor', 'Autoruns', 'TCPView', 'PsExec', 'PsList', 'PsKill', 'Handle', 'ListDLLs', 'Sigcheck', 'Strings', 'VMMap', 'RAMMap', 'DebugView', 'Disk2vhd', 'Du', 'ZoomIt']) {
+            await execAsync(SYSTEM.reg(), ['add', 'HKCU\\Software\\Sysinternals\\' + name, '/v', 'EulaAccepted', '/t', 'REG_DWORD', '/d', '1', '/f'], { stdio: 'ignore' }).catch(() => undefined);
+        }
+    }
+};
+/** Desktop and Start menu shortcuts, all in one PowerShell call. */
+const shortcuts = (apps) => {
+    if (!apps.length)
+        return;
+    const q = (s) => "'" + s.replace(/'/g, "''") + "'";
+    const desktop = path.join(os.homedir(), 'Desktop');
+    const start = path.join(process.env.APPDATA ?? path.join(os.homedir(), 'AppData', 'Roaming'), 'Microsoft', 'Windows', 'Start Menu', 'Programs', 'Sandbox apps');
+    const lines = ['$w = New-Object -ComObject WScript.Shell', 'New-Item -ItemType Directory -Force -Path ' + q(start) + ' | Out-Null'];
+    for (const app of apps) {
+        for (const folder of [desktop, start]) {
+            const name = app.name.replace(/[\\/:*?"<>|]/g, '');
+            lines.push('$s = $w.CreateShortcut(' + q(path.join(folder, name + '.lnk')) + '); $s.TargetPath = ' + q(app.exe) + '; $s.WorkingDirectory = ' + q(path.dirname(app.exe)) + '; $s.Save()');
+        }
+    }
+    powershell(lines.join('\n'));
+};
+export const setupApps = async (env, apps, o) => {
+    const { entries, skipped } = appsToInstall(apps, o.gitAccess);
+    for (const s of skipped)
+        env.summary.push('app skipped: ' + s);
+    if (dryRun) {
+        log('(dry run) would install apps: ' + entries.map((e) => e.name).join(', '));
+        return;
+    }
+    const gui = [];
+    const installed = [];
+    const one = async (entry) => {
+        try {
+            const dest = tool('apps', ...entry.id.split('/'));
+            if (!exists(path.join(dest, MARKER)) || o.refresh)
+                await installApp(entry, dest);
+            const exe = findExe(dest, entry.exe);
+            if (!exe)
+                throw new Error(entry.exe + ' not found in the download');
+            await afterInstall(entry, exe);
+            if (entry.cli || entry.id === 'sysinternals')
+                env.prepend.push(path.dirname(exe));
+            if (!entry.cli)
+                gui.push({ name: entry.name, exe });
+            installed.push(entry.name);
+        }
+        catch (e) {
+            warn(entry.name + ' could not be installed and is skipped; the other apps are not affected. Reason: ' + errMsg(e));
+            env.summary.push(entry.name + ': FAILED');
+        }
+    };
+    // 7-Zip first: the NSIS apps need it to unpack.
+    const [first, rest] = entries[0]?.id === '7zip' ? [[entries[0]], entries.slice(1)] : [[], entries];
+    for (const e of first)
+        await one(e);
+    const queue = [...rest];
+    await Promise.all(Array.from({ length: Math.min(PARALLEL, queue.length) }, async () => { for (let e = queue.shift(); e; e = queue.shift())
+        await one(e); }));
+    try {
+        shortcuts(gui);
+    }
+    catch (e) {
+        warn('App shortcuts could not be created: ' + errMsg(e));
+    }
+    if (installed.length)
+        env.summary.push('apps: ' + installed.join(', ') + ' (shortcuts on the desktop and in Start > Sandbox apps)');
+};

package/dist/guest/apps/resolvers.d.ts

@@ -0,0 +1,8 @@
+export interface Download {
+    url: string;
+    fileName: string;
+    sha256?: string | null;
+    /** Only these paths of the archive (pgAdmin out of the PostgreSQL zip). */
+    members?: string[];
+}
+export declare const RESOLVERS: Record<string, () => Promise<Download>>;

package/dist/guest/apps/resolvers.js

@@ -0,0 +1,90 @@
+// Where the latest version of an app is, for apps that are not a plain GitHub release: each looks it up on the
+// vendor's own site (and its published checksum, where there is one). Named by AppSource.resolve in shared/apps.ts.
+import { fetchJson, fetchText, githubAsset, latestGithubTag } from '../../shared/download.js';
+/** The SHA-256 on the line of a SHA256SUMS-style file that names `file`. */
+const sumFor = (sums, file) => sums.split(/\r?\n/).map((l) => /^([0-9a-f]{64})\s+\*?(.+)$/i.exec(l.trim())).find((m) => m && m[2].trim().endsWith(file))?.[1].toLowerCase() ?? null;
+const firstHash = (text) => /\b([0-9a-f]{64})\b/i.exec(text)?.[1].toLowerCase() ?? null;
+const stripV = (tag) => tag.replace(/^v/, '');
+export const RESOLVERS = {
+    sublime: async () => {
+        // Sublime publishes no checksums; the download is HTTPS from sublimetext.com.
+        const { latest_version: build } = await fetchJson('https://www.sublimetext.com/updates/4/stable_update_check');
+        return { url: 'https://download.sublimetext.com/sublime_text_build_' + build + '_x64.zip', fileName: 'sublime_text_' + build + '.zip' };
+    },
+    pgadmin: async () => {
+        // pgAdmin is only an installer on pgadmin.org; EnterpriseDB's PostgreSQL binaries zip has a portable copy.
+        const versions = (await fetchJson('https://www.postgresql.org/versions.json')).filter((v) => v.supported);
+        const current = versions.find((v) => v.current) ?? versions[versions.length - 1];
+        const exact = current.major + '.' + current.latestMinor;
+        return { url: 'https://get.enterprisedb.com/postgresql/postgresql-' + exact + '-1-windows-x64-binaries.zip', fileName: 'postgresql-' + exact + '.zip', members: ['pgsql/pgAdmin 4'] };
+    },
+    everything: async () => {
+        const page = await fetchText('https://www.voidtools.com/downloads/');
+        const version = /Everything-([\d.]+)\.x64\.zip/.exec(page)?.[1];
+        if (!version)
+            throw new Error('could not find the Everything download on voidtools.com');
+        const file = 'Everything-' + version + '.x64.zip';
+        const sums = await fetchText('https://www.voidtools.com/Everything-' + version + '.sha256').catch(() => '');
+        return { url: 'https://www.voidtools.com/' + file, fileName: file, sha256: sumFor(sums, file) };
+    },
+    chrome: async () => {
+        const data = await fetchJson('https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json');
+        const hit = data.channels.Stable.downloads.chrome.find((d) => d.platform === 'win64');
+        if (!hit)
+            throw new Error('no win64 Chrome for Testing build listed');
+        return { url: hit.url, fileName: 'chrome-win64.zip' };
+    },
+    firefox: async () => {
+        const { LATEST_FIREFOX_VERSION: v } = await fetchJson('https://product-details.mozilla.org/1.0/firefox_versions.json');
+        const base = 'https://archive.mozilla.org/pub/firefox/releases/' + v + '/';
+        const sums = await fetchText(base + 'SHA256SUMS');
+        return { url: base + 'win64/en-US/Firefox%20Setup%20' + v + '.exe', fileName: 'firefox-setup-' + v + '.exe', sha256: sumFor(sums, 'win64/en-US/Firefox Setup ' + v + '.exe') };
+    },
+    blender: async () => {
+        const releases = await fetchText('https://download.blender.org/release/');
+        const series = [...releases.matchAll(/href="Blender(\d+)\.(\d+)\/"/g)].map((m) => [Number(m[1]), Number(m[2])]).sort((a, b) => a[0] - b[0] || a[1] - b[1]).pop();
+        if (!series)
+            throw new Error('could not list Blender releases');
+        const folder = 'https://download.blender.org/release/Blender' + series[0] + '.' + series[1] + '/';
+        const listing = await fetchText(folder);
+        const files = [...listing.matchAll(/href="(blender-([\d.]+)-windows-x64\.zip)"/g)].map((m) => ({ file: m[1], v: m[2].split('.').map(Number) }));
+        const latest = files.sort((a, b) => a.v[2] - b.v[2]).pop();
+        if (!latest)
+            throw new Error('no Windows build in ' + folder);
+        const sums = await fetchText(folder + 'blender-' + latest.v.join('.') + '.sha256').catch(() => '');
+        return { url: folder + latest.file, fileName: latest.file, sha256: sumFor(sums, latest.file) };
+    },
+    kubectl: async () => {
+        const v = (await fetchText('https://dl.k8s.io/release/stable.txt')).trim();
+        const url = 'https://dl.k8s.io/release/' + v + '/bin/windows/amd64/kubectl.exe';
+        return { url, fileName: 'kubectl.exe', sha256: firstHash(await fetchText(url + '.sha256')) };
+    },
+    helm: async () => {
+        const v = await latestGithubTag('helm/helm');
+        const url = 'https://get.helm.sh/helm-' + v + '-windows-amd64.zip';
+        return { url, fileName: 'helm-' + v + '.zip', sha256: firstHash(await fetchText(url + '.sha256sum')) };
+    },
+    terraform: async () => {
+        const { current_version: v } = await fetchJson('https://checkpoint-api.hashicorp.com/v1/check/terraform');
+        const base = 'https://releases.hashicorp.com/terraform/' + v + '/';
+        const file = 'terraform_' + v + '_windows_amd64.zip';
+        return { url: base + file, fileName: file, sha256: sumFor(await fetchText(base + 'terraform_' + v + '_SHA256SUMS'), file) };
+    },
+    mitmproxy: async () => {
+        // mitmproxy's GitHub releases have no files; its own download server has them (no published checksums).
+        const v = stripV(await latestGithubTag('mitmproxy/mitmproxy'));
+        return { url: 'https://downloads.mitmproxy.org/' + v + '/mitmproxy-' + v + '-windows-x86_64.zip', fileName: 'mitmproxy-' + v + '.zip' };
+    },
+    sqlite: async () => {
+        // The download page lists every file in a CSV comment: PRODUCT,<version>,<year>/<file>,<size>,<sha3>.
+        const page = await fetchText('https://sqlite.org/download.html');
+        const file = /PRODUCT,[^,]+,(\d{4}\/sqlite-tools-win-x64-\d+\.zip),/.exec(page)?.[1];
+        if (!file)
+            throw new Error('could not find the sqlite tools download on sqlite.org');
+        return { url: 'https://sqlite.org/' + file, fileName: file.split('/')[1] };
+    },
+    '7zip': async () => {
+        const asset = await githubAsset('ip7z/7zip', /^7z\d+-x64\.exe$/);
+        return { url: asset.url, fileName: asset.name, sha256: asset.sha256 };
+    },
+};

package/dist/guest/audit-parse.d.ts

@@ -0,0 +1,7 @@
+/** Background programs of Windows itself: never what an agent ran. */
+export declare const NOISE: Set<string>;
+/** The events in wevtutil's XML output as audit lines, with the newest record id seen. */
+export declare const parseProcessEvents: (xml: string) => {
+    lines: string[];
+    last: number;
+};

package/dist/guest/audit-parse.js

@@ -0,0 +1,24 @@
+// Reading Windows process-creation events (Security log, 4688, as wevtutil prints them) into audit lines. Pure, so
+// the self-test can check it on the PC side.
+import path from 'node:path';
+/** Background programs of Windows itself: never what an agent ran. */
+export const NOISE = new Set(['conhost.exe', 'svchost.exe', 'backgroundtaskhost.exe', 'runtimebroker.exe', 'wmiprvse.exe', 'dllhost.exe', 'searchprotocolhost.exe', 'searchfilterhost.exe', 'taskhostw.exe', 'sppsvc.exe', 'wermgr.exe', 'consent.exe', 'smartscreen.exe', 'mpcmdrun.exe', 'compattelrunner.exe', 'wevtutil.exe', 'audiodg.exe', 'ctfmon.exe', 'sihost.exe', 'werfault.exe', 'msmpeng.exe', 'nissrv.exe', 'usoclient.exe', 'musnotification.exe']);
+const decode = (s) => s.replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+const field = (event, name) => decode(new RegExp("<Data Name='" + name + "'>([^<]*)</Data>").exec(event)?.[1] ?? '');
+/** The events in wevtutil's XML output as audit lines, with the newest record id seen. */
+export const parseProcessEvents = (xml) => {
+    const lines = [];
+    let last = 0;
+    for (const event of xml.split('</Event>')) {
+        const id = Number(/<EventRecordID>(\d+)<\/EventRecordID>/.exec(event)?.[1] ?? 0);
+        if (!id)
+            continue;
+        last = Math.max(last, id);
+        const program = field(event, 'NewProcessName');
+        if (!program || NOISE.has(path.win32.basename(program).toLowerCase()))
+            continue;
+        const t = /SystemTime='([^']+)'/.exec(event)?.[1] ?? new Date().toISOString();
+        lines.push(JSON.stringify({ t, k: 'proc', p: program.slice(0, 1024), c: field(event, 'CommandLine').slice(0, 2000), pp: field(event, 'ParentProcessName').slice(0, 1024) }));
+    }
+    return { lines, last };
+};

package/dist/guest/audit.d.ts

@@ -0,0 +1,4 @@
+/** Turns on process-creation auditing with command lines (the registry is new every boot). */
+export declare const enableProcessAudit: () => void;
+/** Reads new process events every 15 s for the daemon's life (from the moment it started: older ones are boot noise). */
+export declare const startProcessCollector: () => void;

package/dist/guest/audit.js

@@ -0,0 +1,47 @@
+// audit.processes, sandbox side: Windows records every program started (Security log, event 4688, with its command
+// line); the daemon reads the new events every 15 s and leaves them in run\audit\ as small .jsonl files, which the
+// host takes into its own log (and deletes). Windows' own background programs are left out. The host treats all of it
+// as untrusted (it is checked line by line there).
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../shared/system.js';
+import { parseProcessEvents } from './audit-parse.js';
+import { dryRun, errMsg, isWin, log, mkdirp, run, session, warn } from './env.js';
+/** The "Process Creation" audit subcategory (a GUID, so it works in every Windows language). */
+const PROCESS_CREATION = '{0CCE922B-69AE-11D9-BED3-505054503030}';
+const MAX_PER_PASS = 2000;
+const auditOn = () => Boolean(session.auditProcesses) && isWin && !dryRun;
+/** Turns on process-creation auditing with command lines (the registry is new every boot). */
+export const enableProcessAudit = () => {
+    if (!auditOn())
+        return;
+    spawnSync(path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'auditpol.exe'), ['/set', '/subcategory:' + PROCESS_CREATION, '/success:enable'], { windowsHide: true, stdio: 'ignore' });
+    spawnSync(SYSTEM.reg(), ['add', 'HKLM\\Software\\Microsoft\\Windows\\CurrentVersion\\Policies\\System\\Audit', '/v', 'ProcessCreationIncludeCmdLine_Enabled', '/t', 'REG_DWORD', '/d', '1', '/f'], { windowsHide: true, stdio: 'ignore' });
+    log('Audit: programs started in the sandbox are recorded (audit.processes).');
+};
+const wevtutil = () => path.join(process.env.WINDIR ?? 'C:\\Windows', 'System32', 'wevtutil.exe');
+const newestRecord = () => {
+    const r = spawnSync(wevtutil(), ['qe', 'Security', '/q:*[System[(EventID=4688)]]', '/f:xml', '/c:1', '/rd:true'], { encoding: 'utf8', windowsHide: true });
+    return parseProcessEvents(r.stdout ?? '').last;
+};
+/** Reads new process events every 15 s for the daemon's life (from the moment it started: older ones are boot noise). */
+export const startProcessCollector = () => {
+    if (!auditOn())
+        return;
+    let last = newestRecord();
+    const pass = () => {
+        try {
+            const r = spawnSync(wevtutil(), ['qe', 'Security', '/q:*[System[(EventID=4688) and (EventRecordID>' + last + ')]]', '/f:xml', '/c:' + MAX_PER_PASS], { encoding: 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024 });
+            const { lines, last: newest } = parseProcessEvents(r.stdout ?? '');
+            if (newest)
+                last = newest;
+            if (lines.length)
+                fs.writeFileSync(path.join(mkdirp(run.audit), Date.now() + '-' + process.pid + '.jsonl'), lines.join('\n') + '\n');
+        }
+        catch (e) {
+            warn('audit: ' + errMsg(e));
+        }
+    };
+    setInterval(pass, 15000).unref?.();
+};

package/dist/guest/boot-env.d.ts

@@ -0,0 +1,4 @@
+import { type BootEnvT } from './project-env.js';
+export { baseEnvFor, type BootEnvT } from './project-env.js';
+export declare const saveBootEnv: (value: BootEnvT) => void;
+export declare const readBootEnv: () => BootEnvT | null;

package/dist/guest/boot-env.js

@@ -0,0 +1,25 @@
+// What the boot's provisioning left for projects that join later: the PATH before any toolchain was added, which
+// variables the toolchains set, and what each step contributed. Kept on the sandbox's own disk (lost on close, as it
+// should be). The session daemon builds every later project's environment from it instead of from the boot
+// project's, so project A's Node, Rust target folder or database variables never leak into project B's sessions.
+import fs from 'node:fs';
+import path from 'node:path';
+import { writeJsonAtomic } from '../shared/rundir.js';
+import { localDir } from './env.js';
+import { BootEnv } from './project-env.js';
+export { baseEnvFor } from './project-env.js';
+const file = () => path.join(localDir, 'boot-env.json');
+export const saveBootEnv = (value) => {
+    try {
+        writeJsonAtomic(file(), value);
+    }
+    catch { /* projects added later then fall back to the boot environment */ }
+};
+export const readBootEnv = () => {
+    try {
+        return BootEnv.safeParse(JSON.parse(fs.readFileSync(file(), 'utf8'))).data ?? null;
+    }
+    catch {
+        return null;
+    }
+};

package/dist/guest/cmdline.d.ts

@@ -0,0 +1,12 @@
+export declare const quoteArg: (arg: string) => string;
+/**
+ * Arguments on a `cmd /d /c <agent>.cmd ...` line (npm agents). cmd parses them twice: the /c line, then the .cmd's %*.
+ * & | < > ^ are literal inside quotes, so arguments with them are quoted (https://x?a=1&b=2 survives). % expands even
+ * inside quotes, so each one sits between quoted pieces ("50"%" off"): every %name% cmd could see then starts with a
+ * quote, and no variable is called that. cmd's quote state runs across the whole line (an embedded \" toggles it too),
+ * so a metacharacter it would see outside quotes gets ^^^ (one caret left after each parse). Arguments without any
+ * of these are quoted as usual.
+ */
+export declare const cmdArgs: (args: string[]) => string;
+/** The command line ptyhost starts; when the program is cmd.exe its arguments are quoted for cmd (cmdArgs). */
+export declare const commandLine: (file: string, args: string[]) => string;

package/dist/guest/cmdline.js

@@ -0,0 +1,23 @@
+// Command lines for the agent: Windows argument quoting, and the extra layer cmd.exe needs for npm agents (.cmd files).
+import path from 'node:path';
+const quoted = (arg) => '"' + arg.replace(/(\\*)"/g, '$1$1\\"').replace(/(\\+)$/, '$1$1') + '"';
+export const quoteArg = (arg) => (arg !== '' && !/[\s"]/.test(arg) ? arg : quoted(arg));
+/**
+ * Arguments on a `cmd /d /c <agent>.cmd ...` line (npm agents). cmd parses them twice: the /c line, then the .cmd's %*.
+ * & | < > ^ are literal inside quotes, so arguments with them are quoted (https://x?a=1&b=2 survives). % expands even
+ * inside quotes, so each one sits between quoted pieces ("50"%" off"): every %name% cmd could see then starts with a
+ * quote, and no variable is called that. cmd's quote state runs across the whole line (an embedded \" toggles it too),
+ * so a metacharacter it would see outside quotes gets ^^^ (one caret left after each parse). Arguments without any
+ * of these are quoted as usual.
+ */
+export const cmdArgs = (args) => {
+    const pieces = args.map((arg) => (/[&|<>^%]/.test(arg) ? arg.split('%').map(quoted).join('%') : quoteArg(arg))).join(' ');
+    let inQuotes = false;
+    return [...pieces].map((c) => {
+        if (c === '"')
+            inQuotes = !inQuotes;
+        return !inQuotes && /[&|<>^]/.test(c) ? '^^^' + c : c;
+    }).join('');
+};
+/** The command line ptyhost starts; when the program is cmd.exe its arguments are quoted for cmd (cmdArgs). */
+export const commandLine = (file, args) => path.win32.basename(file).toLowerCase() === 'cmd.exe' ? [quoteArg(file), cmdArgs(args)].filter(Boolean).join(' ') : [file, ...args].map(quoteArg).join(' ');

package/dist/guest/daemon/exec.d.ts

@@ -0,0 +1,5 @@
+import type { GuestRequest } from '../../core/types.js';
+/** Runs a command for the host without blocking the daemon (other requests and pings keep being answered). */
+export declare const execCommand: (req: Extract<GuestRequest, {
+    kind: "exec";
+}>) => void;

package/dist/guest/daemon/exec.js

@@ -0,0 +1,32 @@
+// `exec` requests: a command run for the host in the workspace.
+import { spawn } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+import { errMsg, exists } from '../env.js';
+import { provisionedFor } from './project.js';
+import { insideWorkspace, respond } from './state.js';
+const MAX_OUTPUT = 1024 * 1024;
+const quoteForCmd = (a) => (/[\s"&|<>^]/.test(a) ? '"' + a.replace(/"/g, '""') + '"' : a);
+const cap = (s) => (s.length > MAX_OUTPUT ? s.slice(0, MAX_OUTPUT) + '\n[output truncated]' : s);
+/** Runs a command for the host without blocking the daemon (other requests and pings keep being answered). */
+export const execCommand = (req) => {
+    if (!insideWorkspace(req.cwd) || !exists(req.cwd)) {
+        respond(req.id, { ok: false, message: 'Folder is not inside the sandbox workspace: ' + req.cwd });
+        return;
+    }
+    // chcp 65001 first: console programs then write UTF-8 (not the OEM code page) into the pipes.
+    // In a project registered after boot, its own environment (its Node, Python, database variables).
+    const env = provisionedFor(req.cwd)?.env ?? process.env;
+    const child = spawn(SYSTEM.cmd(), ['/d', '/s', '/c', '"chcp 65001>nul & ' + req.command.map(quoteForCmd).join(' ') + '"'], { cwd: req.cwd, env, windowsHide: true, windowsVerbatimArguments: true });
+    const output = { stdout: '', stderr: '' };
+    // setEncoding decodes across chunks: a multi-byte character split between two reads is not mangled.
+    const collect = (key) => (d) => { if (output[key].length < MAX_OUTPUT)
+        output[key] += d; };
+    child.stdout.setEncoding('utf8').on('data', collect('stdout'));
+    child.stderr.setEncoding('utf8').on('data', collect('stderr'));
+    const timer = setTimeout(() => child.kill(), Math.min(req.timeoutSeconds, 3600) * 1000);
+    child.on('error', (e) => { clearTimeout(timer); respond(req.id, { ok: false, message: 'Could not run the command: ' + errMsg(e) }); });
+    child.on('close', (code) => {
+        clearTimeout(timer);
+        respond(req.id, { ok: code === 0, message: code === null ? 'stopped after ' + req.timeoutSeconds + ' s' : 'exit ' + code, exitCode: code ?? -1, stdout: cap(output.stdout), stderr: cap(output.stderr) });
+    });
+};

package/dist/guest/daemon/project.d.ts

@@ -0,0 +1,14 @@
+import type { ProjectSpecT } from '../../shared/schema.js';
+export interface Provisioned {
+    spec: ProjectSpecT;
+    env: NodeJS.ProcessEnv;
+    summary: string[];
+}
+/** The provisioned project containing this folder, if any (exec in its folders uses its environment). */
+export declare const provisionedFor: (cwd: string) => Provisioned | null;
+export declare const provisionedProjects: () => Provisioned[];
+/**
+ * Provisions a project (or joins the run already doing it: two sessions requested at once wait for the same one).
+ * `say` gets the progress lines.
+ */
+export declare const provisionProject: (spec: ProjectSpecT, say: (message: string) => void) => Promise<Provisioned>;