windows-development-sandbox 0.0.0-stage → 1.0.5

package/dist/guest/toolchains/cli.js

@@ -0,0 +1,64 @@
+// Small portable command-line tools (toolchains.cli): one table entry each instead of one step per binary, plus an
+// `openssl` shim onto the copy Git for Windows already ships.
+import fs from 'node:fs';
+import path from 'node:path';
+import { dryRun, errMsg, exists, log, mkdirp, stateDir, warn, workspace } from '../env.js';
+import { CLI_TOOLS, decideCli } from './catalogue.js';
+import { arch, tool } from './common.js';
+import { setupSingleExe } from './runtimes.js';
+/** gh keeps `gh auth login` here, under the agent state (persists like Claude's own login; never copied from the PC). */
+export const ghConfigDir = () => path.join(stateDir, 'gh');
+const toolVars = {
+    gh: () => ({ GH_CONFIG_DIR: mkdirp(ghConfigDir()), GH_NO_UPDATE_NOTIFIER: '1', GH_NO_EXTENSION_UPDATE_NOTIFIER: '1' }),
+};
+/**
+ * openssl.cmd in tools\shims, running Git's mingw64\bin\openssl.exe. Only the shim: putting mingw64\bin itself on PATH
+ * would bring Git's own gcc-runtime DLLs, curl, and friends along and could shadow MinGW's gcc from the C/C++ step.
+ * setlocal keeps OPENSSL_CONF from leaking into a cmd prompt that runs `openssl`. (A .cmd is found by shells and
+ * by programs that use cmd /c; Rust's Command::new("openssl") looks only for openssl.exe.)
+ */
+const shimOpenssl = (env) => {
+    const exe = tool('git', 'mingw64', 'bin', 'openssl.exe');
+    if (!exists(exe)) {
+        env.summary.push('openssl: not in this Git for Windows (skipped)');
+        return;
+    }
+    const conf = tool('git', 'mingw64', 'etc', 'ssl', 'openssl.cnf');
+    const lines = ['@echo off', 'setlocal', ...(exists(conf) ? ['if not defined OPENSSL_CONF set "OPENSSL_CONF=' + conf + '"'] : []), '"' + exe + '" %*'];
+    fs.writeFileSync(path.join(mkdirp(tool('shims')), 'openssl.cmd'), lines.join('\r\n') + '\r\n');
+    env.prepend.push(tool('shims'));
+    env.summary.push('openssl: Git for Windows\' copy (shim)');
+};
+/**
+ * Installs the tools toolchains.cli asks for. Settings still "auto" here (normally the host decides) use the same
+ * rules on the workspace as the host would. The gh rule is enforced here again, whatever the host sent.
+ */
+export const setupCli = async (env, settings, gitAccess, refresh = false) => {
+    const decisions = decideCli(settings, { gitAccess, hasGithubDir: exists(path.join(workspace, '.github')) });
+    if (settings.gh && !decisions.gh.on) {
+        env.summary.push('gh: off (' + decisions.gh.reason + ')');
+        // A login from an earlier full-access sandbox is still on disk; the agent could read the token from there.
+        if (exists(path.join(ghConfigDir(), 'hosts.yml')))
+            warn('gh is off (git access is not "full"), but an earlier gh login is still stored in ' + ghConfigDir() + ' and readable by the agent. Run `gh auth logout` in a full-access sandbox, or delete that folder.');
+    }
+    if (dryRun) {
+        log('(dry run) would provision CLI tools: ' + Object.entries(decisions).filter(([, d]) => d.on).map(([n]) => n).join(', '));
+        return;
+    }
+    for (const entry of CLI_TOOLS) {
+        const name = entry.name;
+        if (!decisions[name].on)
+            continue;
+        try {
+            await setupSingleExe(env, name, entry.repo, entry.asset(arch), entry.exe, tool('cli', name), { refresh, subdir: entry.subdir });
+            Object.assign(env.vars, toolVars[name]?.() ?? {});
+        }
+        catch (e) {
+            // One tool failing never takes the others down.
+            warn(name + ' setup failed (continuing without it): ' + errMsg(e));
+            env.summary.push(entry.name + ': FAILED');
+        }
+    }
+    if (decisions.openssl.on)
+        shimOpenssl(env);
+};

package/dist/guest/toolchains/common.d.ts

@@ -0,0 +1,37 @@
+/** What the toolchains contribute to the agent's environment. */
+export interface ToolEnv {
+    vars: Record<string, string>;
+    prepend: string[];
+    append: string[];
+    summary: string[];
+}
+export declare const emptyEnv: () => ToolEnv;
+export declare const arch: string;
+export declare const tool: (...parts: string[]) => string;
+/** First x.y.z in a tool's `--version` output. */
+export declare const versionOf: (exe: string, args?: string[], options?: {}) => string;
+/**
+ * Resolves a version online and remembers it for a day (provisioning.refresh looks again), so most boots make no
+ * lookups and an offline boot reuses what was installed last time. After a network failure the remaining lookups go
+ * straight to the remembered versions instead of each waiting for the network; other errors (no such version) do not.
+ */
+export declare const resolveCached: (key: string, resolve: () => Promise<string>) => Promise<string>;
+/** Runs one installer; a failure is reported and skipped so it never blocks the other toolchains. */
+export declare const step: (name: string, env: ToolEnv, work: () => Promise<void>) => Promise<void>;
+/** File names in the workspace and its direct sub-folders ("api/go.mod"); read once per boot. */
+export declare const workspaceEntries: () => string[];
+/**
+ * true / false as configured. The host already turns "auto" into a decision at launch (core/detect-toolchains.ts);
+ * this only applies when a session file still says "auto": the workspace has one of the marker files.
+ */
+export declare const wanted: (setting: boolean | "auto", toolchain: string) => boolean;
+/** The first of these version files in the workspace root, parsed (e.g. .ruby-version "3.3.1"). */
+export declare const versionFromFiles: (files: string[], parse?: (text: string, name: string) => string | null) => {
+    spec: string;
+    source: string;
+} | null;
+/**
+ * Installs each package that is not installed yet (remembered in tools\installed-packages.json under `group`, e.g.
+ * "npm@22.11.0"). One failing package is reported and skipped; it is tried again next boot.
+ */
+export declare const installOnce: (env: ToolEnv, group: string, packages: string[], install: (pkg: string) => void | Promise<void>) => Promise<void>;

package/dist/guest/toolchains/common.js

@@ -0,0 +1,124 @@
+// Shared plumbing for the toolchain installers. Everything lives in C:\AgentData\tools (persistent), so only the first
+// boot downloads; later boots only put things on PATH.
+import fs from 'node:fs';
+import path from 'node:path';
+import { z } from 'zod';
+import { writeJsonAtomic } from '../../shared/rundir.js';
+import { errMsg, execOutput, exists, log, session, toolsDir, warn, workspace } from '../env.js';
+import { MARKERS } from '../../core/detect-toolchains.js';
+import { projectUses, specFromVersionFile } from './versions.js';
+export const emptyEnv = () => ({ vars: {}, prepend: [], append: [], summary: [] });
+export const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+export const tool = (...parts) => path.join(toolsDir, ...parts);
+/** First x.y.z in a tool's `--version` output. */
+export const versionOf = (exe, args = ['--version'], options = {}) => /\d+\.\d+\.\d+\S*/.exec(execOutput(exe, args, options))?.[0] ?? 'installed';
+/** Small JSON state files in tools\: read with zod (a half-written file is just empty), written atomically. */
+const readState = (file, schema, empty) => {
+    try {
+        return schema.safeParse(JSON.parse(fs.readFileSync(file, 'utf8').replace(/^/, ''))).data ?? empty;
+    }
+    catch {
+        return empty;
+    }
+};
+/** A remembered lookup; plain strings are what older versions wrote (treated as stale, still usable offline). */
+const Resolved = z.record(z.string(), z.union([z.string(), z.strictObject({ value: z.string(), at: z.number() })]));
+const resolvedFile = () => tool('resolved-versions.json');
+const remembered = () => Object.fromEntries(Object.entries(readState(resolvedFile(), Resolved, {})).map(([k, v]) => [k, typeof v === 'string' ? { value: v, at: 0 } : v]));
+/** How long a looked-up version is trusted: boots within a day make no version lookups at all. */
+const FRESH_MS = 24 * 60 * 60 * 1000;
+let offline = false;
+const networkError = (e) => /fetch failed|timed? ?out|aborted|ENOTFOUND|EAI_AGAIN|ECONN|ENETUNREACH|EHOSTUNREACH|HTTP 5\d\d|socket/i.test(errMsg(e) + ' ' + String(e?.cause ?? ''));
+/**
+ * Resolves a version online and remembers it for a day (provisioning.refresh looks again), so most boots make no
+ * lookups and an offline boot reuses what was installed last time. After a network failure the remaining lookups go
+ * straight to the remembered versions instead of each waiting for the network; other errors (no such version) do not.
+ */
+export const resolveCached = async (key, resolve) => {
+    const cached = remembered()[key];
+    if (cached && (offline || (!session.provisioning.refresh && Date.now() - cached.at < FRESH_MS)))
+        return cached.value;
+    try {
+        const value = await resolve();
+        fs.mkdirSync(toolsDir, { recursive: true });
+        writeJsonAtomic(resolvedFile(), { ...remembered(), [key]: { value, at: Date.now() } });
+        return value;
+    }
+    catch (e) {
+        if (networkError(e))
+            offline = true;
+        if (!cached)
+            throw e;
+        warn('Could not look up ' + key + ' online (' + errMsg(e) + '); using ' + cached.value + ' from an earlier boot.');
+        return cached.value;
+    }
+};
+/** Runs one installer; a failure is reported and skipped so it never blocks the other toolchains. */
+export const step = async (name, env, work) => {
+    try {
+        await work();
+    }
+    catch (e) {
+        warn(name + ' setup failed (continuing without it): ' + errMsg(e));
+        env.summary.push(name + ': FAILED');
+    }
+};
+// ---- which toolchains a project needs ------------------------------------------------------------------------------
+const SKIP_DIRS = new Set(['node_modules', '.git', 'target', 'bin', 'obj', 'dist', 'build', 'vendor', '.venv', 'venv']);
+let entries = null;
+/** File names in the workspace and its direct sub-folders ("api/go.mod"); read once per boot. */
+export const workspaceEntries = () => {
+    if (entries)
+        return entries;
+    const list = (dir) => { try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    } };
+    const top = list(workspace);
+    const below = top.filter((d) => d.isDirectory() && !d.name.startsWith('.') && !SKIP_DIRS.has(d.name.toLowerCase()))
+        .flatMap((d) => list(path.join(workspace, d.name)).filter((f) => f.isFile()).map((f) => d.name + '/' + f.name));
+    entries = [...top.filter((d) => d.isFile()).map((d) => d.name), ...below];
+    return entries;
+};
+/**
+ * true / false as configured. The host already turns "auto" into a decision at launch (core/detect-toolchains.ts);
+ * this only applies when a session file still says "auto": the workspace has one of the marker files.
+ */
+export const wanted = (setting, toolchain) => setting === 'auto' ? projectUses(workspaceEntries(), MARKERS[toolchain] ?? []) : setting;
+/** The first of these version files in the workspace root, parsed (e.g. .ruby-version "3.3.1"). */
+export const versionFromFiles = (files, parse = (t) => specFromVersionFile(t)) => {
+    for (const name of files) {
+        const file = path.join(workspace, name);
+        if (!exists(file))
+            continue;
+        const spec = parse(fs.readFileSync(file, 'utf8'), name);
+        if (spec)
+            return { spec, source: name };
+    }
+    return null;
+};
+// ---- global packages, installed once -------------------------------------------------------------------------------
+const installedFile = () => tool('installed-packages.json');
+const installed = () => readState(installedFile(), z.record(z.string(), z.string()), {});
+/**
+ * Installs each package that is not installed yet (remembered in tools\installed-packages.json under `group`, e.g.
+ * "npm@22.11.0"). One failing package is reported and skipped; it is tried again next boot.
+ */
+export const installOnce = async (env, group, packages, install) => {
+    const todo = packages.filter((p) => !installed()[group + ':' + p]);
+    for (const pkg of todo) {
+        try {
+            log('Installing ' + pkg + ' (' + group + ') ...');
+            await install(pkg);
+            writeJsonAtomic(installedFile(), { ...installed(), [group + ':' + pkg]: new Date().toISOString() });
+        }
+        catch (e) {
+            warn(group + ' package ' + pkg + ' failed: ' + errMsg(e));
+        }
+    }
+    const ok = packages.filter((p) => installed()[group + ':' + p]);
+    if (ok.length)
+        env.summary.push(group.split('@')[0] + ' packages: ' + ok.join(', '));
+};

package/dist/guest/toolchains/databases.d.ts

@@ -0,0 +1,7 @@
+import type { DatabasePlan } from '../../core/types.js';
+import { type ToolEnv } from './common.js';
+export declare const portOpen: (port: number) => Promise<boolean>;
+export declare const DATABASE_NAMES: Record<DatabasePlan['database'], string>;
+/** Stops a database (and DynamoDB's admin UI). PostgreSQL shuts down cleanly through pg_ctl; the others are ended. */
+export declare const stopDatabase: (plan: DatabasePlan) => Promise<boolean>;
+export declare const setupDatabase: (env: ToolEnv, plan: DatabasePlan) => Promise<void>;

package/dist/guest/toolchains/databases.js

@@ -0,0 +1,226 @@
+// Databases inside the sandbox: PostgreSQL, MariaDB (MySQL-compatible), MongoDB and Redis. Binaries live in
+// C:\AgentData\tools, data in C:\AgentData\databases (both persist), and every server listens on localhost only.
+// Which ones run was decided on the host (session.databases): only what the project needs.
+import fs from 'node:fs';
+import net from 'node:net';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { fetchJson, fetchText, githubAsset, installArchive } from '../../shared/download.js';
+import { SYSTEM } from '../../shared/system.js';
+import { ensureJdk } from './java.js';
+import { dataDir, dryRun, execAsync, exists, log, logsDir, mkdirp } from '../env.js';
+import { resolveCached, tool } from './common.js';
+const dataFor = (name) => path.join(dataDir, 'databases', name);
+export const portOpen = (port) => new Promise((resolve) => {
+    const socket = net.connect({ host: '127.0.0.1', port }, () => { socket.destroy(); resolve(true); });
+    socket.once('error', () => resolve(false));
+});
+const waitForPort = async (port, seconds) => {
+    for (const end = Date.now() + seconds * 1000; Date.now() < end;) {
+        if (await portOpen(port))
+            return true;
+        await new Promise((r) => setTimeout(r, 300));
+    }
+    return false;
+};
+/** Starts a server detached (it outlives the boot script) with its output in logs\<name>.log, and waits for its port. */
+const startServer = async (name, exe, args, port) => {
+    if (await portOpen(port))
+        throw new Error('port ' + port + ' is already in use (change databases.' + name + '.port)');
+    const logFile = path.join(logsDir, name + '.log');
+    const out = fs.openSync(logFile, 'a');
+    spawn(exe, args, { detached: true, stdio: ['ignore', out, out], windowsHide: true }).unref();
+    fs.closeSync(out);
+    if (!(await waitForPort(port, 60)))
+        throw new Error(name + ' did not start listening on port ' + port + '; see ' + logFile);
+};
+/** Lock files a sandbox that was closed without shutting the server down leaves behind (this VM never ran it). */
+const clearStaleLocks = (dir, files) => { for (const f of files)
+    fs.rmSync(path.join(dir, f), { force: true }); };
+const setupPostgres = async (env, plan) => {
+    const exact = await resolveCached('postgres:' + plan.version, async () => {
+        const versions = (await fetchJson('https://www.postgresql.org/versions.json')).filter((v) => v.supported);
+        const hit = plan.version === 'latest' ? versions.find((v) => v.current) ?? versions[versions.length - 1] : versions.find((v) => v.major === plan.version.split('.')[0]);
+        return hit ? hit.major + '.' + hit.latestMinor : Promise.reject(new Error('No supported PostgreSQL ' + plan.version));
+    });
+    const home = tool('postgres', exact);
+    const bin = path.join(home, 'bin');
+    if (!exists(path.join(bin, 'pg_ctl.exe'))) {
+        log('Downloading PostgreSQL ' + exact + ' (~330 MB once) ...');
+        // EDB publishes no checksums; the download is HTTPS from EnterpriseDB, PostgreSQL's official Windows packager.
+        await installArchive('https://get.enterprisedb.com/postgresql/postgresql-' + exact + '-1-windows-x64-binaries.zip', home, { locate: 'pg_ctl.exe', up: 1, fileName: 'postgresql-' + exact + '.zip', members: ['pgsql/bin', 'pgsql/lib', 'pgsql/share', 'pgsql/include'] });
+    }
+    const data = dataFor('postgres-' + exact.split('.')[0]);
+    if (!exists(path.join(data, 'PG_VERSION'))) {
+        log('Creating the PostgreSQL database cluster ...');
+        mkdirp(path.dirname(data));
+        await execAsync(path.join(bin, 'initdb.exe'), ['-D', data, '-U', 'postgres', '-A', 'trust', '-E', 'UTF8', '--locale=C'], { stdio: 'ignore' });
+    }
+    clearStaleLocks(data, ['postmaster.pid']);
+    // postgres.exe refuses to run as an administrator (the sandbox user is one); pg_ctl drops the rights first.
+    if (await portOpen(plan.port))
+        throw new Error('port ' + plan.port + ' is already in use (change databases.postgres.port)');
+    await execAsync(path.join(bin, 'pg_ctl.exe'), ['start', '-D', data, '-w', '-t', '60', '-l', path.join(logsDir, 'postgres.log'), '-o', '-p ' + plan.port + ' -c listen_addresses=localhost'], { stdio: 'ignore' });
+    Object.assign(env.vars, { PGHOST: 'localhost', PGPORT: String(plan.port), PGUSER: 'postgres' });
+    env.prepend.push(bin);
+    env.summary.push('postgres ' + exact + ': localhost:' + plan.port + ', user postgres, no password (postgres://postgres@localhost:' + plan.port + '/postgres)');
+};
+const MARIA = 'https://downloads.mariadb.org/rest-api/mariadb/';
+const setupMysql = async (env, plan) => {
+    const series = await resolveCached('mariadb:' + plan.version, async () => {
+        if (plan.version !== 'lts')
+            return plan.version;
+        const { major_releases: all } = await fetchJson(MARIA);
+        return all.find((r) => r.release_status === 'Stable' && r.release_support_type === 'Long Term Support')?.release_id ?? Promise.reject(new Error('No MariaDB LTS release found'));
+    });
+    const latest = async () => {
+        const { releases } = await fetchJson(MARIA + series + '/latest/');
+        const [version, release] = Object.entries(releases)[0] ?? [];
+        const zip = release?.files.find((f) => /-winx64\.zip$/.test(f.file_name));
+        return zip ? { version, zip } : Promise.reject(new Error('No MariaDB ' + series + ' zip for Windows'));
+    };
+    const version = await resolveCached('mariadb-version:' + series, async () => (await latest()).version);
+    const home = tool('mariadb', version);
+    const bin = path.join(home, 'bin');
+    if (!exists(path.join(bin, 'mariadbd.exe'))) {
+        const { zip } = await latest();
+        log('Downloading MariaDB ' + version + ' ...');
+        await installArchive(zip.file_download_url.replace(/^http:/, 'https:'), home, { sha256: zip.checksum?.sha256sum ?? null, locate: 'mariadbd.exe', up: 1, fileName: zip.file_name });
+    }
+    const data = dataFor('mariadb');
+    if (!exists(path.join(data, 'mysql'))) {
+        log('Creating the MariaDB data folder ...');
+        mkdirp(path.dirname(data));
+        await execAsync(path.join(bin, 'mariadb-install-db.exe'), ['--datadir=' + data, '--port=' + plan.port], { stdio: 'ignore' });
+    }
+    await startServer('mysql', path.join(bin, 'mariadbd.exe'), ['--datadir=' + data, '--port=' + plan.port, '--bind-address=127.0.0.1', '--console'], plan.port);
+    Object.assign(env.vars, { MYSQL_HOST: '127.0.0.1', MYSQL_TCP_PORT: String(plan.port) });
+    env.prepend.push(bin);
+    env.summary.push('mysql (MariaDB ' + version + '): 127.0.0.1:' + plan.port + ', user root, no password (mysql://root@127.0.0.1:' + plan.port + ')');
+};
+const setupMongo = async (env, plan) => {
+    const find = async () => {
+        const { versions } = await fetchJson('https://downloads.mongodb.org/full.json');
+        const prod = versions.filter((v) => v.production_release);
+        const hit = plan.version === 'latest' ? prod[0] : prod.find((v) => v.version === plan.version || v.version.startsWith(plan.version + '.'));
+        const archive = hit?.downloads.find((d) => d.target === 'windows' && d.arch === 'x86_64' && d.edition === 'base')?.archive;
+        return hit && archive ? { version: hit.version, archive } : Promise.reject(new Error('No MongoDB ' + plan.version + ' for Windows'));
+    };
+    const version = await resolveCached('mongodb:' + plan.version, async () => (await find()).version);
+    const home = tool('mongodb', version);
+    if (!exists(path.join(home, 'bin', 'mongod.exe'))) {
+        const { archive } = await find();
+        log('Downloading MongoDB ' + version + ' ...');
+        await installArchive(archive.url, home, { sha256: archive.sha256, locate: 'mongod.exe', up: 1 });
+    }
+    const shell = tool('mongosh');
+    if (!exists(path.join(shell, 'mongosh.exe'))) {
+        const asset = await githubAsset('mongodb-js/mongosh', /^mongosh-[\d.]+-win32-x64\.zip$/);
+        log('Downloading mongosh ...');
+        await installArchive(asset.url, shell, { sha256: asset.sha256, locate: 'mongosh.exe', fileName: asset.name });
+    }
+    const data = mkdirp(dataFor('mongodb'));
+    clearStaleLocks(data, ['mongod.lock']);
+    await startServer('mongodb', path.join(home, 'bin', 'mongod.exe'), ['--dbpath', data, '--bind_ip', '127.0.0.1', '--port', String(plan.port)], plan.port);
+    env.prepend.push(path.join(home, 'bin'), shell);
+    env.summary.push('mongodb ' + version + ': mongodb://127.0.0.1:' + plan.port + ' (mongosh on PATH)');
+};
+// ---- Redis -------------------------------------------------------------------------------------------------------
+const setupRedis = async (env, plan) => {
+    const home = tool('redis');
+    if (!exists(path.join(home, 'redis-server.exe'))) {
+        // Redis has no official Windows build; this is the maintained community build of upstream Redis (MSYS2).
+        const asset = await githubAsset('redis-windows/redis-windows', /^Redis-[\d.]+-Windows-x64-msys2\.zip$/);
+        log('Downloading ' + asset.name + ' ...');
+        await installArchive(asset.url, home, { sha256: asset.sha256, locate: 'redis-server.exe', fileName: asset.name });
+    }
+    const data = mkdirp(dataFor('redis'));
+    await startServer('redis', path.join(home, 'redis-server.exe'), ['--port', String(plan.port), '--bind', '127.0.0.1', '--dir', data.replace(/\\/g, '/'), '--appendonly', 'yes'], plan.port);
+    env.prepend.push(home);
+    env.summary.push('redis: redis://127.0.0.1:' + plan.port + ' (redis-cli on PATH)');
+};
+// ---- DynamoDB Local + dynamodb-admin -------------------------------------------------------------------------------
+const DYNAMO_ZIP = 'https://d1ni2b6xgvw0s0.cloudfront.net/v2.x/dynamodb_local_latest.zip';
+/**
+ * Amazon's DynamoDB Local (a Java program; the Java toolchain step runs first, else this installs the LTS JDK) and
+ * dynamodb-admin, the web UI to browse and edit tables, installed with the runner's own npm. Every AWS SDK picks the
+ * local endpoint up from AWS_ENDPOINT_URL_DYNAMODB, with dummy credentials (real ones never reach the sandbox).
+ */
+const setupDynamo = async (env, plan) => {
+    const java = path.join(await ensureJdk(), 'bin', 'java.exe');
+    const home = tool('dynamodb-local');
+    if (!exists(path.join(home, 'DynamoDBLocal.jar'))) {
+        log('Downloading DynamoDB Local ...');
+        const sha256 = (await fetchText(DYNAMO_ZIP + '.sha256')).trim().split(/\s+/)[0];
+        await installArchive(DYNAMO_ZIP, home, { sha256, locate: 'DynamoDBLocal.jar', fileName: 'dynamodb_local.zip' });
+    }
+    const data = mkdirp(dataFor('dynamodb'));
+    // -sharedDb: one database whatever region/credentials a client uses, so the admin UI and the app see the same tables.
+    await startServer('dynamodb', java, ['-Djava.library.path=' + path.join(home, 'DynamoDBLocal_lib'), '-jar', path.join(home, 'DynamoDBLocal.jar'), '-sharedDb', '-dbPath', data, '-port', String(plan.port)], plan.port);
+    const endpoint = 'http://localhost:' + plan.port;
+    const aws = { AWS_ENDPOINT_URL_DYNAMODB: endpoint, DYNAMO_ENDPOINT: endpoint, AWS_ACCESS_KEY_ID: 'local', AWS_SECRET_ACCESS_KEY: 'local', AWS_REGION: 'us-east-1', AWS_DEFAULT_REGION: 'us-east-1' };
+    Object.assign(env.vars, aws);
+    env.summary.push('dynamodb (DynamoDB Local): ' + endpoint + ' (AWS SDKs use it automatically via AWS_ENDPOINT_URL_DYNAMODB; dummy credentials)');
+    if (!plan.adminPort)
+        return;
+    const prefix = tool('dynamodb-admin');
+    const script = path.join(prefix, 'node_modules', 'dynamodb-admin', 'dist', 'dynamodb-admin.js');
+    if (!exists(script)) {
+        log('Installing dynamodb-admin (web UI for DynamoDB) ...');
+        const npmCli = path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js');
+        await execAsync(process.execPath, [npmCli, 'install', '--global', '--prefix', prefix, 'dynamodb-admin', '--no-fund', '--no-audit'], { stdio: 'ignore' });
+    }
+    const admin = { ...process.env, ...aws, DYNAMO_ENDPOINT: endpoint };
+    // The database matters more than its UI: a taken port is reported, not fatal.
+    if (await portOpen(plan.adminPort)) {
+        env.summary.push('dynamodb-admin: NOT started, port ' + plan.adminPort + ' is in use (change databases.dynamodb.adminPort)');
+        return;
+    }
+    const out = fs.openSync(path.join(logsDir, 'dynamodb-admin.log'), 'a');
+    spawn(process.execPath, [script, '--port', String(plan.adminPort), '--dynamo-endpoint', endpoint, '--skip-default-credentials'], { detached: true, stdio: ['ignore', out, out], windowsHide: true, env: admin }).unref();
+    fs.closeSync(out);
+    if (!(await waitForPort(plan.adminPort, 30)))
+        throw new Error('dynamodb-admin did not start; see ' + path.join(logsDir, 'dynamodb-admin.log'));
+    env.summary.push('dynamodb-admin: http://localhost:' + plan.adminPort + ' (browse and edit tables in the sandbox\'s browser)');
+};
+const SETUP = { postgres: setupPostgres, mysql: setupMysql, mongodb: setupMongo, redis: setupRedis, dynamodb: setupDynamo };
+export const DATABASE_NAMES = { postgres: 'PostgreSQL', mysql: 'MySQL (MariaDB)', mongodb: 'MongoDB', redis: 'Redis', dynamodb: 'DynamoDB Local', sqlserver: 'SQL Server' };
+/** The process listening on a local TCP port (netstat: no PowerShell start-up cost), or null. */
+const listenerPid = (port) => {
+    const out = spawnSync(SYSTEM.netstat(), ['-ano', '-p', 'TCP'], { encoding: 'utf8', windowsHide: true }).stdout ?? '';
+    const hit = out.split(/\r?\n/).map((l) => /^\s*TCP\s+\S+:(\d+)\s+\S+\s+LISTENING\s+(\d+)/.exec(l)).find((m) => m && Number(m[1]) === port);
+    return hit ? Number(hit[2]) : null;
+};
+/** Stops a database (and DynamoDB's admin UI). PostgreSQL shuts down cleanly through pg_ctl; the others are ended. */
+export const stopDatabase = async (plan) => {
+    if (!(await portOpen(plan.port)))
+        return false;
+    if (plan.database === 'postgres' && exists(tool('postgres'))) {
+        for (const version of fs.readdirSync(tool('postgres'))) {
+            const data = dataFor('postgres-' + version.split('.')[0]);
+            const pgCtl = path.join(tool('postgres', version), 'bin', 'pg_ctl.exe');
+            if (exists(path.join(data, 'postmaster.pid')) && exists(pgCtl))
+                await execAsync(pgCtl, ['stop', '-D', data, '-m', 'fast', '-w'], { stdio: 'ignore' });
+        }
+    }
+    for (const port of [plan.port, plan.adminPort ?? 0]) {
+        const pid = port && listenerPid(port);
+        if (pid)
+            try {
+                process.kill(pid);
+            }
+            catch { /* already gone */ }
+    }
+    return true;
+};
+export const setupDatabase = async (env, plan) => {
+    if (plan.database === 'sqlserver') {
+        env.summary.push('sqlserver: NOT available (SQL Server cannot start inside Windows Sandbox). Use the one on the PC via hostAccess.forwards, or switch the project to Postgres/SQLite for local work');
+        return;
+    }
+    if (dryRun) {
+        log('(dry run) would run ' + DATABASE_NAMES[plan.database] + ' on port ' + plan.port + ' (' + plan.reasons.join('; ') + ')');
+        return;
+    }
+    await SETUP[plan.database](env, plan);
+};

package/dist/guest/toolchains/git.d.ts

@@ -0,0 +1,3 @@
+import type { GitAccess } from '../../core/types.js';
+import { type ToolEnv } from './common.js';
+export declare const setupGit: (env: ToolEnv, hostCopy: boolean, refresh: boolean, access: GitAccess) => Promise<void>;

package/dist/guest/toolchains/git.js

@@ -0,0 +1,112 @@
+// Full Git for Windows (with bash: Claude Code on Windows needs Git Bash). Copied from the host when installed there.
+// provisioning.git.access decides what the agent gets: 'full' git, a 'readonly' guarded git, or 'none' (bash only).
+import fs from 'node:fs';
+import path from 'node:path';
+import { download, githubAsset, moveIntoPlace, stagingFolder } from '../../shared/download.js';
+import { dataDir, dryRun, errMsg, execAsync, execOutput, exists, hostToolsDir, launchDir, log, mkdirp, robocopy, warn } from '../env.js';
+import { ensureCompiled } from '../ptyhost.js';
+import { arch, tool } from './common.js';
+const BLOCKED_HOOKS = ['pre-commit', 'commit-msg', 'pre-merge-commit', 'pre-push', 'pre-rebase', 'pre-applypatch', 'applypatch-msg'];
+const posix = (p) => p.replace(/\\/g, '/');
+const installPortableGit = async (root) => {
+    const asset = await githubAsset('git-for-windows/git', arch === 'arm64' ? /^PortableGit-[\d.]+-arm64\.7z\.exe$/ : /^PortableGit-[\d.]+-64-bit\.7z\.exe$/);
+    const sfx = tool(asset.name);
+    log('Downloading ' + asset.name + ' ...');
+    await download(asset.url, sfx, asset.sha256);
+    await execAsync(sfx, ['-o' + root, '-y'], { stdio: 'ignore' });
+    fs.rmSync(sfx, { force: true });
+};
+/**
+ * readonly / none: a `git` wrapper first on PATH and as a bash function (Git Bash would otherwise find the real
+ * git.exe), plus git config from the environment (which repository config cannot override).
+ */
+const installGuard = (env, access, realGit) => {
+    const dir = mkdirp(tool('gitguard'));
+    const guard = path.join(launchDir, 'runtime', 'gitguard.js');
+    // A real git.exe (programs like Claude Code only look for .exe); a .cmd only if the C# compiler is unavailable.
+    try {
+        fs.copyFileSync(ensureCompiled('gitshim'), path.join(dir, 'git.exe'));
+        fs.rmSync(path.join(dir, 'git.cmd'), { force: true });
+    }
+    catch (e) {
+        warn('git guard: falling back to git.cmd (' + errMsg(e) + ')');
+        fs.writeFileSync(path.join(dir, 'git.cmd'), '@"' + process.execPath + '" "' + guard + '" %*\r\n');
+    }
+    fs.writeFileSync(path.join(dir, 'bashenv.sh'), 'git() { "' + posix(process.execPath) + '" "' + posix(guard) + '" "$@"; }\nexport -f git\n');
+    env.prepend.unshift(dir);
+    Object.assign(env.vars, {
+        AGENT_GIT_ACCESS: access, AGENT_REAL_GIT: access === 'readonly' ? realGit : '',
+        AGENT_GUARD_NODE: process.execPath, AGENT_GUARD_SCRIPT: guard, BASH_ENV: posix(path.join(dir, 'bashenv.sh')),
+    });
+    if (access === 'readonly') {
+        const hooks = mkdirp(path.join(dir, 'hooks'));
+        for (const hook of BLOCKED_HOOKS)
+            fs.writeFileSync(path.join(hooks, hook), '#!/bin/sh\necho "git is read-only in this sandbox: ' + hook + ' refused." >&2\nexit 1\n');
+        Object.assign(env.vars, { GIT_CONFIG_COUNT: '1', GIT_CONFIG_KEY_0: 'core.hooksPath', GIT_CONFIG_VALUE_0: posix(hooks) });
+    }
+    else {
+        // Even a git.exe found some other way sees no repository.
+        env.vars.GIT_DIR = path.join(dataDir, 'git-disabled');
+    }
+};
+/**
+ * Git copied from this PC keeps its installer's absolute paths in etc\gitconfig, e.g. http.sslCAInfo =
+ * C:/Program Files/Git/mingw64/etc/ssl/certs/ca-bundle.crt, which does not exist here: every HTTPS clone/fetch failed
+ * with "error setting certificate file". Point it at the bundle inside this copy.
+ */
+const pointAtOwnCertificates = (root) => {
+    const config = path.join(root, 'etc', 'gitconfig');
+    const bundle = path.join(root, 'mingw64', 'etc', 'ssl', 'certs', 'ca-bundle.crt');
+    if (!exists(config) || !exists(bundle))
+        return;
+    const text = fs.readFileSync(config, 'utf8');
+    const fixed = text.replace(/^(\s*sslCAInfo\s*=\s*).*$/gim, (_m, key) => key + posix(bundle));
+    if (fixed !== text)
+        fs.writeFileSync(config, fixed);
+};
+export const setupGit = async (env, hostCopy, refresh, access) => {
+    const root = tool('git');
+    const bash = path.join(root, 'bin', 'bash.exe');
+    const gitExe = path.join(root, 'cmd', 'git.exe');
+    const hostGit = path.join(hostToolsDir, 'git');
+    if (exists(root) && !exists(bash)) {
+        log('Replacing the old MinGit (no bash) with full Git for Windows.');
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+    if (!exists(bash) || refresh) {
+        if (dryRun) {
+            log('(dry run) would provision Git for Windows' + (hostCopy ? ' from this PC' : '') + ' (access: ' + access + ')');
+            return;
+        }
+        // Into a staging folder, then renamed: an interrupted copy/extraction must not leave a tools\git that has bash.exe
+        // (so looks installed) but is missing the rest.
+        const work = stagingFolder(root);
+        try {
+            if (hostCopy && exists(path.join(hostGit, 'bin', 'bash.exe'))) {
+                log('Copying Git for Windows from this PC ...');
+                robocopy(hostGit, work);
+            }
+            else
+                await installPortableGit(work);
+            if (!exists(path.join(work, 'bin', 'bash.exe')))
+                throw new Error('bash.exe missing after installing Git');
+            moveIntoPlace(work, root);
+        }
+        finally {
+            fs.rmSync(work, { recursive: true, force: true });
+        }
+    }
+    if (!exists(bash))
+        throw new Error('bash.exe missing after installing Git');
+    pointAtOwnCertificates(root);
+    env.vars.CLAUDE_CODE_GIT_BASH_PATH = bash;
+    env.append.push(path.join(root, 'usr', 'bin'));
+    const version = execOutput(gitExe, ['--version']).replace(/^git version /, '');
+    if (access === 'full') {
+        env.prepend.push(path.join(root, 'cmd'));
+        env.summary.push('git: ' + version);
+        return;
+    }
+    installGuard(env, access, gitExe);
+    env.summary.push(access === 'readonly' ? 'git: ' + version + ' READ-ONLY (status/log/diff/show/blame; no commit, push, checkout, ...)' : 'git: DISABLED (bash only; the agent cannot use git)');
+};

package/dist/guest/toolchains/go.d.ts

@@ -0,0 +1,3 @@
+import type { Toolchains } from '../../core/types.js';
+import { type ToolEnv } from './common.js';
+export declare const setupGo: (env: ToolEnv, config: Toolchains["go"]) => Promise<void>;

package/dist/guest/toolchains/go.js

@@ -0,0 +1,33 @@
+// Go from go.dev (checksum-verified zip). Modules, build cache and `go install` binaries live in persistent storage;
+// GOTOOLCHAIN=auto lets a go.mod that needs a newer Go fetch it itself.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fetchJson, installArchive } from '../../shared/download.js';
+import { dryRun, execAsync, exists, log } from '../env.js';
+import { arch, installOnce, resolveCached, tool, versionOf } from './common.js';
+import { pickGoRelease } from './versions.js';
+const findRelease = async (spec) => pickGoRelease(await fetchJson('https://go.dev/dl/?mode=json&include=all'), spec) ?? Promise.reject(new Error('No Go release matches "' + spec + '"'));
+export const setupGo = async (env, config) => {
+    if (dryRun) {
+        log('(dry run) would provision Go ' + config.version);
+        return;
+    }
+    const version = await resolveCached('go:' + config.version, async () => (await findRelease(config.version)).version);
+    const root = tool('go', version);
+    if (!exists(path.join(root, 'bin', 'go.exe'))) {
+        const goArch = arch === 'arm64' ? 'arm64' : 'amd64';
+        const file = (await findRelease(version)).files.find((f) => f.os === 'windows' && f.arch === goArch && f.kind === 'archive');
+        if (!file)
+            throw new Error(version + ' has no Windows ' + goArch + ' zip');
+        log('Downloading ' + file.filename + ' ...');
+        await installArchive('https://go.dev/dl/' + file.filename, root, { sha256: file.sha256, locate: 'VERSION', fileName: file.filename });
+    }
+    const GOPATH = tool('go-path');
+    const vars = { GOROOT: root, GOPATH, GOBIN: path.join(GOPATH, 'bin'), GOMODCACHE: path.join(GOPATH, 'pkg', 'mod'), GOCACHE: tool('go-cache'), GOTOOLCHAIN: 'auto', GOTELEMETRY: 'off' };
+    fs.mkdirSync(vars.GOBIN, { recursive: true });
+    Object.assign(env.vars, vars);
+    env.prepend.push(path.join(root, 'bin'), vars.GOBIN);
+    const go = path.join(root, 'bin', 'go.exe');
+    env.summary.push('go: ' + versionOf(go, ['version']));
+    await installOnce(env, 'go', config.tools, (pkg) => execAsync(go, ['install', pkg.includes('@') ? pkg : pkg + '@latest'], { env: { ...process.env, ...vars } }));
+};

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

@@ -0,0 +1,13 @@
+import type { DatabasePlan, GitAccess, Toolchains, ToolVersions } from '../../core/types.js';
+import { type ToolEnv } from './common.js';
+export type { ToolEnv } from './common.js';
+export { pickNodeVersion, pickPackageVersion } from './versions.js';
+export interface ToolchainOptions {
+    gitEnabled: boolean;
+    gitAccess: GitAccess;
+    hostGit: boolean;
+    refresh: boolean;
+    databases: DatabasePlan[];
+}
+/** Provisions every enabled toolchain and database, and returns the combined environment for the agent. */
+export declare const setupToolchains: (config: Toolchains, versions: ToolVersions, options: ToolchainOptions) => Promise<ToolEnv>;