windows-development-sandbox 1.0.5 → 1.1.0

package/dist/guest/setup/hooks.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { SYSTEM } from '../../shared/system.js';
+import { spawnAsync } from '../../shared/download.js';
 import { exists, isWin, launchDir, log, session, warn, workspace } from '../env.js';
 const commandFor = (file) => {
     const ext = path.extname(file).toLowerCase();
@@ -16,21 +17,34 @@ const commandFor = (file) => {
         return [SYSTEM.cmd(), ['/d', '/c', file]];
     return null;
 };
-export const runHooks = (stage, env) => {
-    const dir = path.join(launchDir, 'hooks', stage);
+const BOOT = { root: path.join(launchDir, 'hooks'), cwd: workspace };
+export const projectHooks = (name, cwd) => ({ root: path.join(launchDir, 'projects', name, 'hooks'), cwd });
+const hooksOf = (stage, target) => {
+    const dir = path.join(target.root, stage);
     if (!exists(dir))
-        return;
-    for (const name of fs.readdirSync(dir).sort()) {
-        const command = commandFor(path.join(dir, name));
-        if (!command)
-            continue;
+        return [];
+    return fs.readdirSync(dir).sort().flatMap((name) => { const command = commandFor(path.join(dir, name)); return command ? [{ name, command }] : []; });
+};
+const failed = (stage, name, status) => {
+    const message = 'Hook failed (' + stage + '/' + name + ', exit ' + status + ')';
+    if (session.hooks.failFast)
+        throw new Error(message);
+    warn(message);
+};
+export const runHooks = (stage, env, target = BOOT) => {
+    for (const { name, command } of hooksOf(stage, target)) {
+        log('Hook [' + stage + ']: ' + name);
+        const result = spawnSync(command[0], command[1], { stdio: 'inherit', cwd: target.cwd, env });
+        if (result.status !== 0)
+            failed(stage, name, result.status);
+    }
+};
+/** The same without blocking: the session daemon keeps answering other requests while a project's hooks run. */
+export const runHooksAsync = async (stage, env, target) => {
+    for (const { name, command } of hooksOf(stage, target)) {
         log('Hook [' + stage + ']: ' + name);
-        const result = spawnSync(command[0], command[1], { stdio: 'inherit', cwd: workspace, env });
-        if (result.status === 0)
-            continue;
-        const message = 'Hook failed (' + stage + '/' + name + ', exit ' + result.status + ')';
-        if (session.hooks.failFast)
-            throw new Error(message);
-        warn(message);
+        const status = await spawnAsync(command[0], command[1], { stdio: 'ignore', cwd: target.cwd, env, windowsHide: true });
+        if (status !== 0)
+            failed(stage, name, status);
     }
 };

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

@@ -17,6 +17,8 @@ export interface CliTool {
     subdir?: string;
     /** What the tool is for (summary and docs). */
     about: string;
+    /** Rough download size for the progress line. */
+    size: string;
 }
 export declare const CLI_TOOLS: readonly [{
     readonly name: "gh";
@@ -24,12 +26,14 @@ export declare const CLI_TOOLS: readonly [{
     readonly asset: (arch: Arch) => RegExp;
     readonly exe: "gh.exe";
     readonly about: "GitHub CLI";
+    readonly size: "15 MB";
 }, {
     readonly name: "zstd";
     readonly repo: "facebook/zstd";
     readonly asset: () => RegExp;
     readonly exe: "zstd.exe";
     readonly about: "Zstandard compression";
+    readonly size: "2 MB";
 }];
 export type CliName = (typeof CLI_TOOLS)[number]['name'] | 'openssl';
 export declare const CLI_NAMES: readonly CliName[];

package/dist/guest/toolchains/catalogue.js

@@ -4,9 +4,9 @@ export const pwshAsset = (arch) => (arch === 'arm64' ? /^PowerShell-\d+\.\d+\.\d
 export const binstallAsset = (arch) => (arch === 'arm64' ? /^cargo-binstall-aarch64-pc-windows-msvc\.zip$/ : /^cargo-binstall-x86_64-pc-windows-msvc\.zip$/);
 export const CLI_TOOLS = [
     // gh_2.102.0_windows_amd64.zip holds bin\gh.exe.
-    { name: 'gh', repo: 'cli/cli', asset: (arch) => (arch === 'arm64' ? /^gh_\d+\.\d+\.\d+_windows_arm64\.zip$/ : /^gh_\d+\.\d+\.\d+_windows_amd64\.zip$/), exe: 'gh.exe', about: 'GitHub CLI' },
+    { name: 'gh', repo: 'cli/cli', asset: (arch) => (arch === 'arm64' ? /^gh_\d+\.\d+\.\d+_windows_arm64\.zip$/ : /^gh_\d+\.\d+\.\d+_windows_amd64\.zip$/), exe: 'gh.exe', about: 'GitHub CLI', size: '15 MB' },
     // zstd-v1.5.7-win64.zip; there is no arm64 build, and Windows on Arm runs the x64 one.
-    { name: 'zstd', repo: 'facebook/zstd', asset: () => /^zstd-v\d+\.\d+\.\d+-win64\.zip$/, exe: 'zstd.exe', about: 'Zstandard compression' },
+    { name: 'zstd', repo: 'facebook/zstd', asset: () => /^zstd-v\d+\.\d+\.\d+-win64\.zip$/, exe: 'zstd.exe', about: 'Zstandard compression', size: '2 MB' },
 ];
 export const CLI_NAMES = [...CLI_TOOLS.map((t) => t.name), 'openssl'];
 /**

package/dist/guest/toolchains/cli.js

@@ -2,39 +2,40 @@
 // `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 { dryRun, errMsg, exists, log, mkdirp, stateDir, warn } from '../env.js';
+import { projectWorkspace } from '../project-context.js';
 import { CLI_TOOLS, decideCli } from './catalogue.js';
 import { arch, tool } from './common.js';
 import { setupSingleExe } from './runtimes.js';
+import { ensureCompiled } from '../helpers.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.)
+ * tools\shims\openssl.exe (sandbox/openssl.cs), a launcher for Git's mingw64\bin\openssl.exe. A real .exe so programs
+ * that call CreateProcess directly (Rust's Command::new("openssl")) find it, and only the shim is on PATH: mingw64\bin
+ * itself would bring Git's runtime DLLs along and could shadow MinGW's gcc from the C/C++ step.
  */
 const shimOpenssl = (env) => {
-    const exe = tool('git', 'mingw64', 'bin', 'openssl.exe');
-    if (!exists(exe)) {
+    if (!exists(tool('git', 'mingw64', 'bin', 'openssl.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)');
+    const shims = mkdirp(tool('shims'));
+    fs.copyFileSync(ensureCompiled('openssl'), path.join(shims, 'openssl.exe'));
+    // An earlier version wrote a .cmd; it would still win for shells that prefer it.
+    fs.rmSync(path.join(shims, 'openssl.cmd'), { force: true });
+    env.prepend.push(shims);
+    env.summary.push('openssl: Git for Windows\' copy');
 };
 /**
  * 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')) });
+    const decisions = decideCli(settings, { gitAccess, hasGithubDir: exists(path.join(projectWorkspace(), '.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.
@@ -50,15 +51,22 @@ export const setupCli = async (env, settings, gitAccess, refresh = false) => {
         if (!decisions[name].on)
             continue;
         try {
-            await setupSingleExe(env, name, entry.repo, entry.asset(arch), entry.exe, tool('cli', name), { refresh, subdir: entry.subdir });
+            await setupSingleExe(env, name, entry.repo, entry.asset(arch), entry.exe, tool('cli', name), { refresh, subdir: entry.subdir, size: entry.size });
             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));
+            warn(name + ' could not be set up and is skipped; the other tools are not affected. Reason: ' + errMsg(e));
             env.summary.push(entry.name + ': FAILED');
         }
     }
-    if (decisions.openssl.on)
-        shimOpenssl(env);
+    if (decisions.openssl.on) {
+        try {
+            shimOpenssl(env);
+        }
+        catch (e) {
+            warn('openssl could not be set up and is skipped (Git Bash still has its own). Reason: ' + errMsg(e));
+            env.summary.push('openssl: FAILED');
+        }
+    }
 };

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

@@ -1,3 +1,4 @@
+import { type ReleaseAsset } from '../../shared/download.js';
 /** What the toolchains contribute to the agent's environment. */
 export interface ToolEnv {
     vars: Record<string, string>;
@@ -16,9 +17,24 @@ export declare const versionOf: (exe: string, args?: string[], options?: {}) =>
  * 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>;
+/** A single file download that lands as `file` only when complete (and checksum-verified): a cut-off one never looks finished. */
+export declare const downloadFile: (url: string, file: string, sha256?: string | null) => Promise<void>;
+interface GithubInstall {
+    /** The folder the archive is unpacked into (replaced atomically). */
+    dest: string;
+    /** What the progress line says is being downloaded, with its size; a function gets the release asset. */
+    what: string | ((asset: ReleaseAsset) => string);
+    /** Look past the latest release for a matching asset. */
+    searchOlder?: boolean;
+    /** installArchive's `locate` / `up`: keep only the folder holding this file. */
+    locate?: string;
+    up?: number;
+}
+/** The newest GitHub release asset matching `pattern`, checksum-verified, unpacked into `dest`. */
+export declare const installFromGithub: (repo: string, pattern: RegExp, o: GithubInstall) => Promise<void>;
 /** 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. */
+/** File names in the project's folder and its direct sub-folders ("api/go.mod"); read once per project. */
 export declare const workspaceEntries: () => string[];
 /**
  * true / false as configured. The host already turns "auto" into a decision at launch (core/detect-toolchains.ts);
@@ -35,3 +51,4 @@ export declare const versionFromFiles: (files: string[], parse?: (text: string,
  * "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>;
+export {};

package/dist/guest/toolchains/common.js

@@ -3,8 +3,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
+import { download, githubAsset, installArchive } from '../../shared/download.js';
 import { writeJsonAtomic } from '../../shared/rundir.js';
-import { errMsg, execOutput, exists, log, session, toolsDir, warn, workspace } from '../env.js';
+import { errMsg, execOutput, exists, log, session, toolsDir, warn } from '../env.js';
+import { projectWorkspace } from '../project-context.js';
 import { MARKERS } from '../../core/detect-toolchains.js';
 import { projectUses, specFromVersionFile } from './versions.js';
 export const emptyEnv = () => ({ vars: {}, prepend: [], append: [], summary: [] });
@@ -49,27 +51,47 @@ export const resolveCached = async (key, resolve) => {
             offline = true;
         if (!cached)
             throw e;
-        warn('Could not look up ' + key + ' online (' + errMsg(e) + '); using ' + cached.value + ' from an earlier boot.');
+        warn('Could not look up the latest ' + key + ' online (' + errMsg(e) + '); using ' + cached.value + ' from an earlier start.');
         return cached.value;
     }
 };
+/** A single file download that lands as `file` only when complete (and checksum-verified): a cut-off one never looks finished. */
+export const downloadFile = async (url, file, sha256 = null) => {
+    const part = file + '.part';
+    try {
+        await download(url, part, sha256);
+        fs.rmSync(file, { force: true });
+        fs.renameSync(part, file);
+    }
+    finally {
+        fs.rmSync(part, { force: true });
+    }
+};
+/** The newest GitHub release asset matching `pattern`, checksum-verified, unpacked into `dest`. */
+export const installFromGithub = async (repo, pattern, o) => {
+    const asset = await githubAsset(repo, pattern, o.searchOlder);
+    log('Downloading ' + (typeof o.what === 'string' ? o.what : o.what(asset)) + ' ...');
+    await installArchive(asset.url, o.dest, { sha256: asset.sha256, fileName: asset.name, ...(o.locate ? { locate: o.locate } : {}), ...(o.up ? { up: o.up } : {}) });
+};
 /** 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));
+        warn(name + ' could not be set up and is skipped; everything else still works, and the next start tries again. Reason: ' + 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. */
+const entries = new Map();
+/** File names in the project's folder and its direct sub-folders ("api/go.mod"); read once per project. */
 export const workspaceEntries = () => {
-    if (entries)
-        return entries;
+    const workspace = projectWorkspace();
+    const known = entries.get(workspace.toLowerCase());
+    if (known)
+        return known;
     const list = (dir) => { try {
         return fs.readdirSync(dir, { withFileTypes: true });
     }
@@ -79,8 +101,9 @@ export const workspaceEntries = () => {
     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;
+    const found = [...top.filter((d) => d.isFile()).map((d) => d.name), ...below];
+    entries.set(workspace.toLowerCase(), found);
+    return found;
 };
 /**
  * true / false as configured. The host already turns "auto" into a decision at launch (core/detect-toolchains.ts);
@@ -90,7 +113,7 @@ export const wanted = (setting, toolchain) => setting === 'auto' ? projectUses(w
 /** 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);
+        const file = path.join(projectWorkspace(), name);
         if (!exists(file))
             continue;
         const spec = parse(fs.readFileSync(file, 'utf8'), name);
@@ -115,7 +138,7 @@ export const installOnce = async (env, group, packages, install) => {
             writeJsonAtomic(installedFile(), { ...installed(), [group + ':' + pkg]: new Date().toISOString() });
         }
         catch (e) {
-            warn(group + ' package ' + pkg + ' failed: ' + errMsg(e));
+            warn(pkg + ' (' + group + ') could not be installed and is skipped; the next start tries again. Reason: ' + errMsg(e));
         }
     }
     const ok = packages.filter((p) => installed()[group + ':' + p]);

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

@@ -0,0 +1,8 @@
+import type { DatabasePlan } from '../../../core/types.js';
+import { type ToolEnv } from '../common.js';
+/**
+ * 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).
+ */
+export declare const setupDynamo: (env: ToolEnv, plan: DatabasePlan) => Promise<void>;

package/dist/guest/toolchains/databases/dynamodb.js

@@ -0,0 +1,52 @@
+// DynamoDB Local + dynamodb-admin.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fetchText, installArchive } from '../../../shared/download.js';
+import { execAsync, exists, log, logsDir, mkdirp } from '../../env.js';
+import { ensureJdk } from '../java.js';
+import { tool } from '../common.js';
+import { portOpen, waitForPort } from '../../ports.js';
+import { dataFor, startServer } from './server.js';
+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).
+ */
+export 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 (~60 MB once) ...');
+        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, the DynamoDB web UI (~20 MB once) ...');
+        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' });
+    }
+    // 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: { ...process.env, ...aws } }).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)');
+};

package/dist/guest/toolchains/{databases.d.ts → databases/index.d.ts}

@@ -1,6 +1,5 @@
-import type { DatabasePlan } from '../../core/types.js';
-import { type ToolEnv } from './common.js';
-export declare const portOpen: (port: number) => Promise<boolean>;
+import type { DatabasePlan } from '../../../core/types.js';
+import { type ToolEnv } from '../common.js';
 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>;

package/dist/guest/toolchains/databases/index.js

@@ -0,0 +1,62 @@
+// Databases inside the sandbox: PostgreSQL, MariaDB (MySQL-compatible), MongoDB, Redis and DynamoDB Local. 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 path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { SYSTEM } from '../../../shared/system.js';
+import { dryRun, execAsync, exists, log } from '../../env.js';
+import { tool } from '../common.js';
+import { setupDynamo } from './dynamodb.js';
+import { setupMongo } from './mongodb.js';
+import { setupMysql } from './mysql.js';
+import { postgresData, setupPostgres } from './postgres.js';
+import { setupRedis } from './redis.js';
+import { portOpen } from '../../ports.js';
+import { duringSession } from '../../project-context.js';
+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 = postgresData(version);
+            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). Switch the project to Postgres or SQLite for local work');
+        return;
+    }
+    if (dryRun) {
+        log('(dry run) would run ' + DATABASE_NAMES[plan.database] + ' on port ' + plan.port + ' (' + plan.reasons.join('; ') + ')');
+        return;
+    }
+    // A project that joined later, while another project's server already listens there: they share it.
+    if (duringSession() && (await portOpen(plan.port))) {
+        env.summary.push(plan.database + ': shared, already running on port ' + plan.port);
+        return;
+    }
+    await SETUP[plan.database](env, plan);
+};

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

@@ -0,0 +1,3 @@
+import type { DatabasePlan } from '../../../core/types.js';
+import { type ToolEnv } from '../common.js';
+export declare const setupMongo: (env: ToolEnv, plan: DatabasePlan) => Promise<void>;

package/dist/guest/toolchains/databases/mongodb.js

@@ -0,0 +1,31 @@
+// MongoDB Community, with mongosh.
+import path from 'node:path';
+import { fetchJson, installArchive } from '../../../shared/download.js';
+import { exists, log, mkdirp } from '../../env.js';
+import { installFromGithub, resolveCached, tool } from '../common.js';
+import { clearStaleLocks, dataFor, startServer } from './server.js';
+export 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 + ' (~400 MB once) ...');
+        await installArchive(archive.url, home, { sha256: archive.sha256, locate: 'mongod.exe', up: 1 });
+    }
+    const shell = tool('mongosh');
+    if (!exists(path.join(shell, 'mongosh.exe'))) {
+        await installFromGithub('mongodb-js/mongosh', /^mongosh-[\d.]+-win32-x64\.zip$/, { dest: shell, what: 'mongosh, the MongoDB shell (~50 MB once)', locate: 'mongosh.exe' });
+    }
+    const data = mkdirp(dataFor('mongodb'));
+    await clearStaleLocks(data, ['mongod.lock'], plan.port);
+    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)');
+};

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

@@ -0,0 +1,3 @@
+import type { DatabasePlan } from '../../../core/types.js';
+import { type ToolEnv } from '../common.js';
+export declare const setupMysql: (env: ToolEnv, plan: DatabasePlan) => Promise<void>;

package/dist/guest/toolchains/databases/mysql.js

@@ -0,0 +1,38 @@
+// MariaDB, the MySQL-compatible server.
+import path from 'node:path';
+import { fetchJson, installArchive } from '../../../shared/download.js';
+import { execAsync, exists, log } from '../../env.js';
+import { resolveCached, tool } from '../common.js';
+import { createOnce, dataFor, startServer } from './server.js';
+const MARIA = 'https://downloads.mariadb.org/rest-api/mariadb/';
+export 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 + ' (~90 MB once) ...');
+        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');
+    await createOnce(data, 'mysql', async () => {
+        log('Creating the MariaDB database (first start) ...');
+        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 + ')');
+};

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

@@ -0,0 +1,5 @@
+import type { DatabasePlan } from '../../../core/types.js';
+import { type ToolEnv } from '../common.js';
+/** The data folder of a PostgreSQL major version (one cluster per major). */
+export declare const postgresData: (version: string) => string;
+export declare const setupPostgres: (env: ToolEnv, plan: DatabasePlan) => Promise<void>;

package/dist/guest/toolchains/databases/postgres.js

@@ -0,0 +1,38 @@
+// PostgreSQL from EnterpriseDB's Windows binaries (without pgAdmin).
+import path from 'node:path';
+import { fetchJson, installArchive } from '../../../shared/download.js';
+import { execAsync, exists, log, logsDir } from '../../env.js';
+import { resolveCached, tool } from '../common.js';
+import { portOpen } from '../../ports.js';
+import { clearStaleLocks, createOnce, dataFor } from './server.js';
+/** The data folder of a PostgreSQL major version (one cluster per major). */
+export const postgresData = (version) => dataFor('postgres-' + version.split('.')[0]);
+export 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 = postgresData(exact);
+    await createOnce(data, 'PG_VERSION', async () => {
+        log('Creating the PostgreSQL database (first start) ...');
+        await execAsync(path.join(bin, 'initdb.exe'), ['-D', data, '-U', 'postgres', '-A', 'trust', '-E', 'UTF8', '--locale=C'], { stdio: 'ignore' });
+    });
+    if (await portOpen(plan.port))
+        throw new Error('port ' + plan.port + ' is already in use (change databases.postgres.port)');
+    await clearStaleLocks(data, ['postmaster.pid'], plan.port);
+    // postgres.exe refuses to run as an administrator (the sandbox user is one); pg_ctl drops the rights first.
+    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)');
+};

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

@@ -0,0 +1,3 @@
+import type { DatabasePlan } from '../../../core/types.js';
+import { type ToolEnv } from '../common.js';
+export declare const setupRedis: (env: ToolEnv, plan: DatabasePlan) => Promise<void>;

package/dist/guest/toolchains/databases/redis.js

@@ -0,0 +1,16 @@
+// Redis (the maintained community Windows build of upstream Redis).
+import path from 'node:path';
+import { exists, mkdirp } from '../../env.js';
+import { installFromGithub, tool } from '../common.js';
+import { dataFor, startServer } from './server.js';
+export const setupRedis = async (env, plan) => {
+    const home = tool('redis');
+    if (!exists(path.join(home, 'redis-server.exe'))) {
+        // Redis has no official Windows build; this one is built from upstream Redis with MSYS2.
+        await installFromGithub('redis-windows/redis-windows', /^Redis-[\d.]+-Windows-x64-msys2\.zip$/, { dest: home, what: (a) => 'Redis (' + a.name + ', ~10 MB once)', locate: 'redis-server.exe' });
+    }
+    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)');
+};

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

@@ -0,0 +1,14 @@
+/** C:\AgentData\databases\<name>: the data survives the sandbox. */
+export declare const dataFor: (name: string) => string;
+/** Starts a server detached (it outlives the boot script) with its output in logs\<name>.log, and waits for its port. */
+export declare const startServer: (name: string, exe: string, args: string[], port: number) => Promise<void>;
+/**
+ * Lock files a sandbox that was closed without shutting the server down leaves behind. Only when nothing listens on
+ * the port: a server already running in this VM keeps its lock.
+ */
+export declare const clearStaleLocks: (dir: string, files: string[], port: number) => Promise<void>;
+/**
+ * Creates a database folder with `create` (initdb, install-db) unless `marker` is there. A failed or interrupted run
+ * removes the folder again when this call made it, so the half-made one is not taken for a finished database next boot.
+ */
+export declare const createOnce: (data: string, marker: string, create: () => Promise<void>) => Promise<void>;