windows-development-sandbox 1.4.0 → 1.4.3

package/dist/core/util/fs.js

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import { writeJsonAtomic } from '../../shared/io/index.js';
+export const ensureDir = (p) => {
+    fs.mkdirSync(p, { recursive: true });
+};
+export const dirExists = (p) => {
+    try {
+        return fs.statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+export const fileExists = (p) => {
+    try {
+        return fs.statSync(p).isFile();
+    }
+    catch {
+        return false;
+    }
+};
+export const readJson = (p) => JSON.parse(fs.readFileSync(p, 'utf8').replace(/^\uFEFF/, ''));
+export const tryReadJson = (p) => {
+    try {
+        return readJson(p);
+    }
+    catch {
+        return null;
+    }
+};
+/** Atomic (a crash or a second command never leaves half a file); refused outside temp during the self-test. */
+export const writeJson = (p, value) => writeJsonAtomic(p, value);
+export const realPath = (p) => {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+};

package/dist/core/util/index.d.ts

@@ -0,0 +1,7 @@
+export { isWin, sleep, runPowerShell, captureOutput, runPowerShellAsync } from './process.js';
+export { UserError, fail, errMsg } from './errors.js';
+export { parseJsonc, readJsonc } from './jsonc.js';
+export { ensureDir, dirExists, fileExists, readJson, tryReadJson, writeJson, realPath } from './fs.js';
+export { xmlEscape, safeText, plainText } from './text.js';
+export { homeDir, expandPath, isRootPath, isUserProfile, isInsideOrEqual, findOnPath } from './paths.js';
+export { isLink, removeLink, assertNoLinks } from './links.js';

package/dist/core/util/index.js

@@ -0,0 +1,7 @@
+export { isWin, sleep, runPowerShell, captureOutput, runPowerShellAsync } from './process.js';
+export { UserError, fail, errMsg } from './errors.js';
+export { parseJsonc, readJsonc } from './jsonc.js';
+export { ensureDir, dirExists, fileExists, readJson, tryReadJson, writeJson, realPath } from './fs.js';
+export { xmlEscape, safeText, plainText } from './text.js';
+export { homeDir, expandPath, isRootPath, isUserProfile, isInsideOrEqual, findOnPath } from './paths.js';
+export { isLink, removeLink, assertNoLinks } from './links.js';

package/dist/core/util/jsonc.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parses JSON with comments and trailing commas (JSONC, like VS Code's settings.json). Errors name the file, line
+ * and column, and say what to fix.
+ */
+export declare const parseJsonc: <T>(text: string, source: string) => T;
+export declare const readJsonc: <T>(file: string) => T;

package/dist/core/util/jsonc.js

@@ -0,0 +1,25 @@
+import fs from 'node:fs';
+import { parse as parseJsoncText, printParseErrorCode } from 'jsonc-parser';
+import { fail } from './errors.js';
+/**
+ * Parses JSON with comments and trailing commas (JSONC, like VS Code's settings.json). Errors name the file, line
+ * and column, and say what to fix.
+ */
+export const parseJsonc = (text, source) => {
+    const errors = [];
+    const value = parseJsoncText(text.replace(/^/, ''), errors, { allowTrailingComma: true, disallowComments: false });
+    if (errors.length) {
+        const { offset, error } = errors[0];
+        const before = text.slice(0, offset).split(/\r?\n/);
+        fail(source +
+            ' is not valid JSON (line ' +
+            before.length +
+            ', column ' +
+            (before[before.length - 1].length + 1) +
+            ': ' +
+            printParseErrorCode(error) +
+            ').', 'Fix that spot in the file. Comments (// and /* */) and trailing commas are fine.');
+    }
+    return value;
+};
+export const readJsonc = (file) => parseJsonc(fs.readFileSync(file, 'utf8'), file);

package/dist/core/util/links.d.ts

@@ -0,0 +1,10 @@
+/** True if `p` itself is a symlink or junction (lstat; never follows it). */
+export declare const isLink: (p: string) => boolean;
+/** Removes a symlink or junction itself (never its target). Junctions need rmdir on Windows. */
+export declare const removeLink: (p: string) => void;
+/**
+ * The sandbox can write anywhere in its data folder, so it could swap a folder for a junction that points at this
+ * PC's own disk. Before the host reads, writes or deletes anything under `root`, every existing path component from
+ * `root` down to `target` must be a plain folder/file. Throws otherwise.
+ */
+export declare const assertNoLinks: (root: string, target: string) => void;

package/dist/core/util/links.js

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { assertTestWritable } from '../../shared/test-guard.js';
+import { fail } from './errors.js';
+/** True if `p` itself is a symlink or junction (lstat; never follows it). */
+export const isLink = (p) => {
+    try {
+        return fs.lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+};
+/** Removes a symlink or junction itself (never its target). Junctions need rmdir on Windows. */
+export const removeLink = (p) => {
+    assertTestWritable(p);
+    try {
+        fs.unlinkSync(p);
+    }
+    catch {
+        fs.rmdirSync(p);
+    }
+};
+/**
+ * The sandbox can write anywhere in its data folder, so it could swap a folder for a junction that points at this
+ * PC's own disk. Before the host reads, writes or deletes anything under `root`, every existing path component from
+ * `root` down to `target` must be a plain folder/file. Throws otherwise.
+ */
+export const assertNoLinks = (root, target) => {
+    const rel = path.relative(path.resolve(root), path.resolve(target));
+    if (rel.startsWith('..') || path.isAbsolute(rel))
+        fail('Refusing to touch ' + target + ': it is outside ' + root);
+    let current = path.resolve(root);
+    for (const part of ['', ...rel.split(path.sep).filter(Boolean)]) {
+        current = part ? path.join(current, part) : current;
+        if (isLink(current))
+            fail('Refusing to touch ' + target + ': ' + current + ' is a link (possible escape attempt from the sandbox).');
+    }
+};

package/dist/core/util/paths.d.ts

@@ -0,0 +1,7 @@
+export declare const homeDir: () => string;
+/** Expands %VAR% and resolves relative paths against `base`. */
+export declare const expandPath: (input: string, base: string) => string;
+export declare const isRootPath: (p: string) => boolean;
+export declare const isUserProfile: (p: string) => boolean;
+export declare const isInsideOrEqual: (parent: string, child: string) => boolean;
+export declare const findOnPath: (names: string[]) => string | null;

package/dist/core/util/paths.js

@@ -0,0 +1,33 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileExists } from './fs.js';
+export const homeDir = () => process.env.USERPROFILE ?? os.homedir();
+/** Expands %VAR% and resolves relative paths against `base`. */
+export const expandPath = (input, base) => {
+    const expanded = input
+        .replace(/%([^%]+)%/g, (_m, name) => process.env[name] ?? '%' + name + '%')
+        .replace(/^~(?=$|[\\/])/, homeDir());
+    return path.resolve(path.isAbsolute(expanded) ? expanded : path.join(base, expanded));
+};
+export const isRootPath = (p) => {
+    const n = path.resolve(p);
+    return n.toLowerCase() === path.parse(n).root.toLowerCase();
+};
+export const isUserProfile = (p) => {
+    const profile = process.env.USERPROFILE ?? process.env.HOME ?? '';
+    return profile !== '' && path.resolve(p).toLowerCase() === path.resolve(profile).toLowerCase();
+};
+export const isInsideOrEqual = (parent, child) => {
+    const rel = path.relative(path.resolve(parent).toLowerCase(), path.resolve(child).toLowerCase());
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+};
+export const findOnPath = (names) => {
+    const dirs = (process.env.PATH ?? process.env.Path ?? '').split(path.delimiter).filter((d) => d !== '');
+    for (const name of names)
+        for (const dir of dirs) {
+            const candidate = path.join(dir, name);
+            if (fileExists(candidate))
+                return candidate;
+        }
+    return null;
+};

package/dist/core/util/process.d.ts

@@ -0,0 +1,15 @@
+export declare const isWin: boolean;
+export declare const sleep: (ms: number) => Promise<void>;
+/** Runs a PowerShell script and returns its exit code (and stdout when `capture`). */
+export declare const runPowerShell: (script: string, capture?: boolean) => {
+    status: number;
+    stdout: string;
+};
+/** Runs a program (an absolute path: `SYSTEM.*`, never a bare name) and returns its stdout, or '' if it failed or timed out. */
+export declare const captureOutput: (file: string, args: string[], options?: {
+    timeout?: number;
+    cwd?: string;
+    maxBuffer?: number;
+}) => string;
+/** Async variant (does not block the event loop), resolving with stdout. */
+export declare const runPowerShellAsync: (script: string) => Promise<string>;

package/dist/core/util/process.js

@@ -0,0 +1,54 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../shared/system.js';
+export const isWin = process.platform === 'win32';
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * PowerShell arguments for a script passed encoded (no quoting issues, no progress-bar noise on stderr). Output is
+ * UTF-8: Windows PowerShell 5.1 otherwise writes redirected stdout in the OEM code page, mangling non-ASCII (regional
+ * date formats, wallpaper paths). UTF8Encoding($false): no byte-order mark in front of the output.
+ */
+const powerShellArgs = (script) => {
+    const prelude = "[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding $false\n$ProgressPreference = 'SilentlyContinue'\n";
+    const encoded = Buffer.from(prelude + script, 'utf16le').toString('base64');
+    // -OutputFormat Text: with redirected output PowerShell would otherwise print its progress stream as "#< CLIXML" XML.
+    return [
+        '-NoLogo',
+        '-NoProfile',
+        '-NonInteractive',
+        '-OutputFormat',
+        'Text',
+        '-ExecutionPolicy',
+        'Bypass',
+        '-EncodedCommand',
+        encoded,
+    ];
+};
+/** Runs a PowerShell script and returns its exit code (and stdout when `capture`). */
+export const runPowerShell = (script, capture = false) => {
+    const result = spawnSync(SYSTEM.powershell(), powerShellArgs(script), {
+        stdio: capture ? ['ignore', 'pipe', 'inherit'] : 'inherit',
+        encoding: 'utf8',
+        windowsHide: true,
+    });
+    if (result.error)
+        throw result.error;
+    return { status: result.status ?? 1, stdout: result.stdout ?? '' };
+};
+/** Runs a program (an absolute path: `SYSTEM.*`, never a bare name) and returns its stdout, or '' if it failed or timed out. */
+export const captureOutput = (file, args, options = {}) => {
+    const result = spawnSync(file, args, { encoding: 'utf8', windowsHide: true, timeout: 60000, ...options });
+    return result.status === 0 ? (result.stdout ?? '') : '';
+};
+/** Async variant (does not block the event loop), resolving with stdout. */
+export const runPowerShellAsync = (script) => new Promise((resolve, reject) => {
+    const child = spawn(SYSTEM.powershell(), powerShellArgs(script), {
+        stdio: ['ignore', 'pipe', 'inherit'],
+        windowsHide: true,
+    });
+    let out = '';
+    child.stdout.on('data', (d) => {
+        out += d.toString('utf8');
+    });
+    child.on('error', reject);
+    child.on('close', () => resolve(out));
+});

package/dist/core/util/text.d.ts

@@ -0,0 +1,8 @@
+export declare const xmlEscape: (v: string) => string;
+/**
+ * Text that came from the sandbox, made safe to print: control characters and escape sequences are removed except
+ * plain colours (SGR), so nothing written by the sandbox can drive your terminal (titles, clipboard, cursor tricks).
+ */
+export declare const safeText: (text: string) => string;
+/** safeText without colours either: for text you are asked to approve, which must not be able to hide parts of itself. */
+export declare const plainText: (text: string) => string;

package/dist/core/util/text.js

@@ -0,0 +1,8 @@
+export const xmlEscape = (v) => v.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+/**
+ * Text that came from the sandbox, made safe to print: control characters and escape sequences are removed except
+ * plain colours (SGR), so nothing written by the sandbox can drive your terminal (titles, clipboard, cursor tricks).
+ */
+export const safeText = (text) => text.replace(/\x1b\[[0-9;]*m|\x1b(\[[0-9;?]*[ -\/]*[@-~]|\][^\x07\x1b]*(\x07|\x1b\\)|[@-Z\\-_])|[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, (m) => (/^\x1b\[[0-9;]*m$/.test(m) ? m : ''));
+/** safeText without colours either: for text you are asked to approve, which must not be able to hide parts of itself. */
+export const plainText = (text) => safeText(text).replace(/\x1b\[[0-9;]*m/g, '');

package/dist/guest/{setup/agents.js → agents/agent-installer.js}

@@ -3,11 +3,20 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { SYSTEM } from '../../shared/system.js';
 import { uvVars } from '../toolchains/runtimes.js';
-import { dryRun, execAsync, exists, hostToolsDir, isWin, log, mkdirp, session, toolsDir, warn } from '../env.js';
+import { dryRun, hostToolsDir, isWin, toolsDir } from '../runtime/paths.js';
+import { execAsync } from '../runtime/process.js';
+import { exists, mkdirp } from '../runtime/fs.js';
+import { log, warn } from '../runtime/log.js';
+import { session } from '../runtime/session.js';
+import { addMachineEnvironment } from '../setup/environment.js';
 const harnessPaths = (name, harness) => {
     const dir = path.join(toolsDir, 'agents', name);
     const exe = harness.hostExecutable ?? (harness.uvBin ? harness.uvBin + '.exe' : null);
-    return { dir, exe: exe ? path.join(dir, exe) : null, cmd: harness.npmBin ? path.join(dir, harness.npmBin + '.cmd') : null };
+    return {
+        dir,
+        exe: exe ? path.join(dir, exe) : null,
+        cmd: harness.npmBin ? path.join(dir, harness.npmBin + '.cmd') : null,
+    };
 };
 /** npm install with the runner's own npm into tools\agents\<name> (no global state outside persistent storage). */
 const installViaNpm = async (name, harness, dir, env) => {
@@ -34,7 +43,9 @@ const installViaUv = async (name, harness, dir, env) => {
     }
     if (!exists(uv))
         throw new Error(name + ' is installed with uv; enable toolchains.uv');
-    await execAsync(uv, ['tool', 'install', '--force', '--python', '3.12', harness.uvPackage], { env: { ...env, ...uvVars(), UV_TOOL_BIN_DIR: dir } });
+    await execAsync(uv, ['tool', 'install', '--force', '--python', '3.12', harness.uvPackage], {
+        env: { ...env, ...uvVars(), UV_TOOL_BIN_DIR: dir },
+    });
 };
 /** One install per agent at a time: two sessions asking for a new agent at once share the first one's install. */
 const installing = new Map();
@@ -46,10 +57,19 @@ export const provisionHarness = (name, harness, env, refresh = session.provision
     const current = installing.get(name);
     if (current)
         return current;
-    const work = installHarness(name, harness, env, refresh).finally(() => installing.delete(name));
+    const work = installHarness(name, harness, env, refresh)
+        .then(() => onPath(harnessPaths(name, harness).dir, env))
+        .finally(() => installing.delete(name));
     installing.set(name, work);
     return work;
 };
+/** The agent's folder at the end of PATH: `claude` (or `codex` ...) works in every new terminal tab and in sessions. */
+const onPath = (dir, env) => {
+    const parts = (env.PATH ?? '').split(path.delimiter);
+    if (!parts.some((p) => p.toLowerCase() === dir.toLowerCase()))
+        env.PATH = [...parts, dir].join(path.delimiter);
+    addMachineEnvironment({}, [dir], true);
+};
 const installHarness = async (name, harness, env, refresh) => {
     const p = harnessPaths(name, harness);
     const cached = (p.exe !== null && exists(p.exe)) || (p.cmd !== null && exists(p.cmd));

package/dist/guest/apps/after-install.d.ts

@@ -0,0 +1,3 @@
+import type { AppEntry } from '../../shared/apps/index.js';
+/** Settings an app needs on every boot (the sandbox's registry is new each time), and files next to its program. */
+export declare function afterInstall(entry: AppEntry, exe: string): Promise<void>;

package/dist/guest/apps/after-install.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { SYSTEM } from '../../shared/system.js';
+import { execAsync } from '../runtime/process.js';
+import { exists, mkdirp } from '../runtime/fs.js';
+import { arch, tool } from '../toolchains/tool-env.js';
+/** The Sysinternals tools whose EULA is accepted up front (each asks once otherwise). */
+const SYSINTERNALS_TOOLS = [
+    'Process Explorer',
+    'Process Monitor',
+    'Autoruns',
+    'TCPView',
+    'PsExec',
+    'PsList',
+    'PsKill',
+    'Handle',
+    'ListDLLs',
+    'Sigcheck',
+    'Strings',
+    'VMMap',
+    'RAMMap',
+    'DebugView',
+    'Disk2vhd',
+    'Du',
+    'ZoomIt',
+];
+/** Settings an app needs on every boot (the sandbox's registry is new each time), and files next to its program. */
+export async function afterInstall(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 SYSINTERNALS_TOOLS) {
+            await execAsync(SYSTEM.reg(), ['add', 'HKCU\\Software\\Sysinternals\\' + name, '/v', 'EulaAccepted', '/t', 'REG_DWORD', '/d', '1', '/f'], { stdio: 'ignore' }).catch(() => undefined);
+        }
+    }
+}

package/dist/guest/apps/app-installer.d.ts

@@ -0,0 +1,22 @@
+import type { Config, GitAccess } from '../../core/types.js';
+import { type AppEntry } from '../../shared/apps/index.js';
+import { type ToolEnv } from '../toolchains/tool-env.js';
+export interface AppsOptions {
+    gitAccess: GitAccess;
+    refresh: boolean;
+}
+export declare class AppInstaller {
+    private readonly env;
+    private readonly options;
+    private readonly parallel;
+    private readonly gui;
+    private readonly installed;
+    constructor(env: ToolEnv, options: AppsOptions, parallel?: number);
+    /** Installs the entries (7-Zip first: the NSIS apps need it to unpack), then their shortcuts. */
+    installAll(entries: readonly AppEntry[]): Promise<void>;
+    private installOne;
+    /** Downloads and unpacks one entry into its folder (replaced in one step: never half there). */
+    private download;
+}
+/** Installs apps.install and apps.custom (skipped ones are listed in the summary). */
+export declare function setupApps(env: ToolEnv, apps: Config['apps'], o: AppsOptions): Promise<void>;

package/dist/guest/apps/app-installer.js

@@ -0,0 +1,116 @@
+// Installs the chosen apps into tools\apps, a few at a time, each once (a marker file says it is complete). One app
+// failing is reported and never stops the others.
+import fs from 'node:fs';
+import path from 'node:path';
+import { appsToInstall } from '../../shared/apps/index.js';
+import { downloader, moveIntoPlace, stagingFolder } from '../../shared/download/index.js';
+import { safeRemove } from '../../shared/io/safe-remove.js';
+import { dryRun } from '../runtime/paths.js';
+import { execAsync } from '../runtime/process.js';
+import { exists, mkdirp } from '../runtime/fs.js';
+import { log, warn } from '../runtime/log.js';
+import { errMsg } from '../../core/util/errors.js';
+import { tool } from '../toolchains/tool-env.js';
+import { afterInstall } from './after-install.js';
+import { findExe } from './find-exe.js';
+import { shortcuts } from './shortcuts.js';
+import { resolve } from './sources.js';
+import { unpack } from './unpack.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;
+export class AppInstaller {
+    env;
+    options;
+    parallel;
+    gui = [];
+    installed = [];
+    constructor(env, options, parallel = PARALLEL) {
+        this.env = env;
+        this.options = options;
+        this.parallel = parallel;
+    }
+    /** Installs the entries (7-Zip first: the NSIS apps need it to unpack), then their shortcuts. */
+    async installAll(entries) {
+        const [first, rest] = entries[0]?.id === '7zip' ? [[entries[0]], entries.slice(1)] : [[], entries];
+        for (const e of first)
+            await this.installOne(e);
+        const queue = [...rest];
+        await Promise.all(Array.from({ length: Math.min(this.parallel, queue.length) }, async () => {
+            for (let e = queue.shift(); e; e = queue.shift())
+                await this.installOne(e);
+        }));
+        try {
+            shortcuts(this.gui);
+        }
+        catch (e) {
+            warn('App shortcuts could not be created: ' + errMsg(e));
+        }
+        if (this.installed.length)
+            this.env.summary.push('apps: ' + this.installed.join(', ') + ' (shortcuts on the desktop and in Start > Sandbox apps)');
+    }
+    async installOne(entry) {
+        try {
+            const dest = tool('apps', ...entry.id.split('/'));
+            if (!exists(path.join(dest, MARKER)) || this.options.refresh)
+                await this.download(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')
+                this.env.prepend.push(path.dirname(exe));
+            if (!entry.cli)
+                this.gui.push({ name: entry.name, exe });
+            this.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));
+            this.env.summary.push(entry.name + ': FAILED');
+        }
+    }
+    /** Downloads and unpacks one entry into its folder (replaced in one step: never half there). */
+    async download(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 downloader.file(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));
+        }
+    }
+}
+/** Installs apps.install and apps.custom (skipped ones are listed in the summary). */
+export async function setupApps(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;
+    }
+    await new AppInstaller(env, o).installAll(entries);
+}

package/dist/guest/apps/find-exe.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The program in an installed folder (breadth first, bounded: big apps have tens of thousands of files). Of several
+ * copies at the same depth, one in an amd64/x64 folder wins.
+ */
+export declare function findExe(root: string, exe: string): string | null;

package/dist/guest/apps/find-exe.js

@@ -0,0 +1,41 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { exeMatcher } from '../../shared/apps/index.js';
+const MAX_DEPTH = 7;
+const MAX_ENTRIES = 50000;
+/** A folder for 64-bit x86 builds (zips that ship amd64\ and i386\ copies of the same program). */
+const X64_FOLDER = /(^|[\\/])(amd64|x64|x86_64|win64)([\\/]|$)/i;
+/**
+ * The program in an installed folder (breadth first, bounded: big apps have tens of thousands of files). Of several
+ * copies at the same depth, one in an amd64/x64 folder wins.
+ */
+export function findExe(root, exe) {
+    const match = exeMatcher(exe);
+    const best = (hits) => hits.find((h) => X64_FOLDER.test(path.relative(root, h))) ?? hits[0] ?? null;
+    let queue = [root];
+    let seen = 0;
+    for (let depth = 0; depth < MAX_DEPTH && queue.length; depth++) {
+        const next = [];
+        const hits = [];
+        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)
+                hits.push(path.join(dir, hit.name));
+            else
+                next.push(...entries.filter((e) => e.isDirectory() && !e.isSymbolicLink()).map((e) => path.join(dir, e.name)));
+            if ((seen += entries.length) > MAX_ENTRIES)
+                return best(hits);
+        }
+        if (hits.length)
+            return best(hits);
+        queue = next;
+    }
+    return null;
+}

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

@@ -1,10 +1,3 @@
-import type { Config, GitAccess } from '../../core/types.js';
-import { type ToolEnv } from '../toolchains/common.js';
-export { appsNeedMesa } from '../../shared/apps.js';
-export interface AppsOptions {
-    gitAccess: GitAccess;
-    refresh: boolean;
-}
-/** The program in an installed folder (breadth first, bounded: big apps have tens of thousands of files). */
-export declare const findExe: (root: string, exe: string) => string | null;
-export declare const setupApps: (env: ToolEnv, apps: Config["apps"], o: AppsOptions) => Promise<void>;
+export { appsNeedMesa } from '../../shared/apps/index.js';
+export { setupApps, type AppsOptions } from './app-installer.js';
+export { findExe } from './find-exe.js';