@oddessentials/agent-guild 0.35.0 → 0.37.0

package/src/manager/environment-probe.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { spawn } from 'node:child_process';
 import { resolveCommand, killWindowsTree } from './command-resolver.mjs';
 import { scanPins } from './environment-pins.mjs';
+import { systemInfo, dockerInfo, isWsl, wslInteropEnabled } from './environment-system.mjs';
 
 export const RUNTIMES = [
   { id: 'node', label: 'Node.js', command: 'node', args: ['--version'], pattern: /^v(\d+\.\d+\.\d+(?:-[\w.-]+)?)\s*$/m },
@@ -57,10 +58,7 @@ export function passiveExecutable(file, id, { platform = process.platform, env =
     return { error: WINDOWS_ALIAS };
   }
   const head = read(real);
-  const binary = head[0] === 0x4d && head[1] === 0x5a // PE
-    || head[0] === 0x7f && head.subarray(1, 4).toString() === 'ELF'
-    || ['feedface', 'feedfacf', 'cefaedfe', 'cffaedfe', 'cafebabe', 'bebafeca', 'cafebabf', 'bfbafeca'].includes(head.subarray(0, 4).toString('hex'));
-  if (binary) {
+  if (nativeProgram(head)) {
     // rustup dispatches using argv[0]; preserve its rustc proxy's name.
     return { file: id === 'rust' && /\/rustup(?:\.exe)?$/.test(normalized) ? file : real };
   }
@@ -71,6 +69,12 @@ export function passiveExecutable(file, id, { platform = process.platform, env =
 
 const WINDOWS_ALIAS = 'A Windows execution alias was found. A runtime behind this alias has not been verified.';
 
+function nativeProgram(head) {
+  return head[0] === 0x4d && head[1] === 0x5a // PE
+    || head[0] === 0x7f && head.subarray(1, 4).toString() === 'ELF'
+    || ['feedface', 'feedfacf', 'cefaedfe', 'cffaedfe', 'cafebabe', 'bebafeca', 'cafebabf', 'bfbafeca'].includes(head.subarray(0, 4).toString('hex'));
+}
+
 function windowsAlias(file) {
   return /[\\/]windowsapps[\\/]/i.test(file);
 }
@@ -78,7 +82,7 @@ function windowsAlias(file) {
 // The helper has a second, independent overall deadline in Environment. A
 // timeout here resolves immediately, even if a descendant retains stdout.
 // The kill is recorded for directory cleanup and does not delay this result.
-export function runProbe(file, args, { env, cwd, timeoutMs = TIMEOUT_MS, spawnProcess = spawn, kills = null } = {}) {
+export function runProbe(file, args, { env, cwd, timeoutMs = TIMEOUT_MS, limit = LIMIT, spawnProcess = spawn, kills = null } = {}) {
   return new Promise((resolve) => {
     let child, timer, size = 0, output = '', settled = false;
     const stop = () => {
@@ -113,7 +117,7 @@ export function runProbe(file, args, { env, cwd, timeoutMs = TIMEOUT_MS, spawnPr
       timer = setTimeout(() => finish({ error: 'Version check timed out.' }, true), timeoutMs);
       for (const stream of [child.stdout, child.stderr]) stream.on('data', (chunk) => {
         size += chunk.length;
-        if (size > LIMIT) return finish({ error: 'Version check produced too much output.' }, true);
+        if (size > limit) return finish({ error: 'Version check produced too much output.' }, true);
         output += chunk.toString();
       });
       child.on('error', () => finish({ error: 'Could not run the resolved executable.' }, true));
@@ -195,6 +199,229 @@ export function detectTools({ env, platform = process.platform, resolve = resolv
   return tools;
 }
 
+// Design tools an agent can drive from a terminal. A version is read only from
+// a native program whose real name is the tool's own: a snap, a Flatpak
+// launcher or another wrapper is reported by presence. Windows `convert` is a
+// disk utility, so ImageMagick is only `magick` there.
+export const DESIGN_TOOLS = [
+  {
+    id: 'blender', label: 'Blender', args: ['--version', '--factory-startup'],
+    commands: () => ['blender'],
+    pattern: /^Blender (\d+\.\d+(?:\.\d+)?)/m, program: /^blender(?:\.exe)?$/i, installed: /^Blender\b/i,
+  },
+  {
+    id: 'ffmpeg', label: 'FFmpeg', args: ['-version'],
+    commands: () => ['ffmpeg'],
+    pattern: /^ffmpeg version n?(\d+(?:\.\d+)+|N-\d+)/m, program: /^ffmpeg(?:\.exe)?$/i, installed: /^FFmpeg\b/i,
+  },
+  {
+    // GIMP's window program on Windows does not print its version; the console build does.
+    id: 'gimp', label: 'GIMP', args: ['--version'],
+    commands: (platform) => platform === 'win32' ? ['gimp-console'] : ['gimp-console', 'gimp'],
+    pattern: /version (\d+\.\d+\.\d+)/, installed: /^GIMP\b/i,
+    program: (platform) => platform === 'win32' ? /^gimp-console(?:-[\d.]+)?\.exe$/i : /^gimp(?:-console)?(?:-[\d.]+)?$/i,
+  },
+  {
+    id: 'inkscape', label: 'Inkscape', args: ['--version'],
+    commands: () => ['inkscape'],
+    pattern: /^Inkscape (\d+\.\d+(?:\.\d+)?)/m, program: /^inkscape(?:\.com|\.exe)?$/i, installed: /^Inkscape\b/i,
+  },
+  {
+    id: 'imagemagick', label: 'ImageMagick', args: ['-version'],
+    commands: (platform) => platform === 'win32' ? ['magick'] : ['magick', 'convert'],
+    pattern: /^Version: ImageMagick (\d+\.\d+\.\d+(?:-\d+)?)/m, program: /^(?:magick|convert)(?:-im\d[\w.]*)?(?:\.exe)?$/i, installed: /^ImageMagick\b/i,
+  },
+];
+const DESIGN_TIMEOUT_MS = 3000;
+const REGISTRY_LIMIT = 1024 * 1024;
+const UNINSTALL_KEYS = [
+  'HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall',
+  'HKLM\\SOFTWARE\\WOW6432Node\\Microsoft\\Windows\\CurrentVersion\\Uninstall',
+  'HKCU\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Uninstall',
+];
+// Paths inside an install folder, Windows. A RegExp segment matches a directory entry.
+const WINDOWS_FILES = {
+  blender: [['blender.exe']],
+  ffmpeg: [['bin', 'ffmpeg.exe'], ['ffmpeg.exe'], [/^ffmpeg-/i, 'bin', 'ffmpeg.exe']],
+  gimp: [['bin', 'gimp-console.exe'], ['bin', /^gimp-console-[\d.]+\.exe$/i]],
+  inkscape: [['bin', 'inkscape.com'], ['bin', 'inkscape.exe']],
+  imagemagick: [['magick.exe']],
+};
+
+// Usual install locations, used only when PATH has no match. Each entry is an
+// absolute root followed by segments below it.
+export function designLocations(id, { platform = process.platform, env = process.env, registry = [] } = {}) {
+  if (platform === 'win32') {
+    const programFiles = [value(env, 'ProgramFiles'), value(env, 'ProgramW6432'), 'C:\\Program Files'].filter(Boolean);
+    const profile = value(env, 'USERPROFILE');
+    const local = value(env, 'LOCALAPPDATA') || (profile && path.win32.join(profile, 'AppData', 'Local'));
+    const folders = {
+      blender: programFiles.map((root) => [root, 'Blender Foundation', /^Blender/i]),
+      ffmpeg: [],
+      gimp: [...programFiles.map((root) => [root, /^GIMP/i]), ...(local ? [[local, 'Programs', /^GIMP/i]] : [])],
+      inkscape: programFiles.map((root) => [root, 'Inkscape']),
+      imagemagick: programFiles.map((root) => [root, /^ImageMagick/i]),
+    }[id];
+    return [...registry.map((dir) => [dir]), ...folders].flatMap((folder) => WINDOWS_FILES[id].map((file) => [...folder, ...file]));
+  }
+  const home = value(env, 'HOME') || os.homedir();
+  const bins = platform === 'darwin'
+    ? ['/opt/homebrew/bin', '/usr/local/bin', '/opt/local/bin']
+    : ['/usr/local/bin', '/usr/bin', '/snap/bin', '/home/linuxbrew/.linuxbrew/bin'];
+  const flatpaks = ['/var/lib/flatpak/exports/bin', path.posix.join(home, '.local/share/flatpak/exports/bin')];
+  const apps = ['/Applications', path.posix.join(home, 'Applications')];
+  const inBins = (names) => bins.flatMap((dir) => names.map((name) => [dir, name]));
+  const flatpak = (app) => platform === 'linux' ? flatpaks.map((dir) => [dir, app]) : [];
+  const bundle = (app, file) => platform === 'darwin' ? apps.map((dir) => [dir, app, 'Contents', 'MacOS', file]) : [];
+  return {
+    blender: [...bundle(/^Blender.*\.app$/i, 'Blender'), ...inBins(['blender']), ...flatpak('org.blender.Blender')],
+    ffmpeg: inBins(['ffmpeg']),
+    gimp: [...bundle(/^GIMP.*\.app$/i, /^gimp(?:-[\d.]+)?$/i), ...inBins(['gimp-console', 'gimp']), ...flatpak('org.gimp.GIMP')],
+    inkscape: [...bundle(/^Inkscape.*\.app$/i, 'inkscape'), ...inBins(['inkscape']), ...flatpak('org.inkscape.Inkscape')],
+    imagemagick: inBins(platform === 'darwin' ? ['magick'] : ['magick', 'convert']),
+  }[id];
+}
+
+// The first existing file among the locations, in order. Directory listings are sorted.
+export function findInstalled(locations, { platform = process.platform, readdir = fs.readdirSync, isFile = (file) => isExecutable(file, platform) } = {}) {
+  const join = platform === 'win32' ? path.win32.join : path.posix.join;
+  for (const [root, ...segments] of locations) {
+    let paths = [root];
+    for (const segment of segments) {
+      paths = paths.flatMap((dir) => {
+        if (typeof segment === 'string') return [join(dir, segment)];
+        try { return readdir(dir).filter((name) => segment.test(name)).sort().map((name) => join(dir, name)); } catch { return []; }
+      });
+    }
+    const hit = paths.find((file) => isFile(file));
+    if (hit) return hit;
+  }
+  return null;
+}
+
+function isExecutable(file, platform) {
+  try {
+    if (!fs.statSync(file).isFile()) return false;
+    if (platform !== 'win32') fs.accessSync(file, fs.constants.X_OK);
+    return true;
+  } catch { return false; }
+}
+
+// Install folders from Windows uninstall entries whose name is a design tool.
+// Each query is bounded; a failed query adds nothing.
+export async function windowsInstallFolders({ env, cwd, run = runProbe, kills = null } = {}) {
+  const reg = path.win32.join(value(env, 'SystemRoot') || 'C:\\Windows', 'System32', 'reg.exe');
+  const query = (args) => run(reg, ['query', ...args], { env, cwd, kills, timeoutMs: DESIGN_TIMEOUT_MS, limit: REGISTRY_LIMIT })
+    .then((result) => result.code === 0 ? result.output : '');
+  const entries = (output, name) => {
+    const found = [];
+    let key = null;
+    for (const line of output.split(/\r?\n/)) {
+      if (/^HKEY_/.test(line)) key = line.trim();
+      const match = line.match(new RegExp(`^\\s+${name}\\s+REG_(?:EXPAND_)?SZ\\s+(.+?)\\s*$`));
+      if (key && match) found.push({ key, value: match[1] });
+    }
+    return found;
+  };
+  const named = (await Promise.all(UNINSTALL_KEYS.map((root) => query([root, '/s', '/v', 'DisplayName']))))
+    .flatMap((output) => entries(output, 'DisplayName'))
+    .map(({ key, value: name }) => ({ key, tool: DESIGN_TOOLS.find((tool) => tool.installed.test(name)) }))
+    .filter(({ tool }) => tool);
+  const folders = Object.fromEntries(DESIGN_TOOLS.map(({ id }) => [id, []]));
+  await Promise.all(named.map(async ({ key, tool }) => {
+    const folder = entries(await query([key, '/v', 'InstallLocation']), 'InstallLocation')[0]?.value.replace(/^"(.*)"$/, '$1');
+    if (folder && path.win32.isAbsolute(folder)) folders[tool.id].push(folder);
+  }));
+  return folders;
+}
+
+// A Homebrew cask's command wrapper is exactly `exec "<program in the app>" "$@"`.
+// Only that exact form is followed; any other script stays unchecked.
+const HOMEBREW_WRAPPER = /\/Caskroom\/[^/]+\/[^/]+\/\.homebrew-command-wrappers\/[^/]+$/;
+
+function homebrewTarget(head) {
+  return head.toString('utf8').match(/^#!\/bin\/(?:ba)?sh\nexec "(\/[^"$`\\\n]+)"\s+"\$@"\n?$/)?.[1] ?? null;
+}
+
+// Why a found program's version is not read, or the program to run.
+export function designProgram(file, tool, { platform = process.platform, realpath = fs.realpathSync, read = readHead } = {}) {
+  let real = realpath(file);
+  const normalized = real.replaceAll('\\', '/');
+  if (/\/flatpak\/exports\/bin\//.test(file.replaceAll('\\', '/'))) return { reason: 'A Flatpak app. Its version is not checked.' };
+  if (/(?:^|\/)snap$/.test(normalized)) return { reason: 'A snap. Its version is not checked.' };
+  const head = read(real);
+  if (!nativeProgram(head)) {
+    const target = platform === 'darwin' && HOMEBREW_WRAPPER.test(normalized) ? homebrewTarget(head) : null;
+    if (!target) return { reason: 'A launcher script. Its version is not checked.' };
+    real = realpath(target);
+    if (!nativeProgram(read(real))) return { reason: 'A launcher script. Its version is not checked.' };
+  }
+  const name = path.posix.basename(real.replaceAll('\\', '/'));
+  const program = typeof tool.program === 'function' ? tool.program(platform) : tool.program;
+  if (!program.test(name)) return { reason: `This runs ${name}, so its version is not checked.` };
+  return { file: real };
+}
+
+// GTK programs write a D-Bus keyring and profile folders even for --version.
+// Point every home and profile location at the scan's own temporary folder.
+export function designEnv(env, cwd) {
+  const out = probeEnv(env);
+  const overrides = { DBUS_SESSION_BUS_ADDRESS: 'disabled:' };
+  for (const key of ['HOME', 'XDG_CONFIG_HOME', 'XDG_DATA_HOME', 'XDG_CACHE_HOME', 'XDG_STATE_HOME', 'INKSCAPE_PROFILE_DIR', 'GIMP2_DIRECTORY', 'GIMP3_DIRECTORY']) overrides[key] = cwd;
+  for (const key of Object.keys(out)) if (Object.hasOwn(overrides, key.toUpperCase())) delete out[key];
+  return { ...out, ...overrides };
+}
+
+export async function scanDesignTool(tool, {
+  env, cwd, platform = process.platform, resolve = resolveCommand, installed = async () => null,
+  inspect = designProgram, run = runProbe, kills = null, wslInterop = false,
+} = {}) {
+  const { id, label, args, pattern } = tool;
+  const base = { id, label, status: 'not_found', version: null, path: null, command: null, detail: null };
+  let command = null, file = null;
+  for (const name of tool.commands(platform)) {
+    file = resolve(name, env, platform, { onSkip: (candidate) => platform === 'win32' && windowsAlias(candidate) });
+    if (file) { command = name; break; }
+  }
+  // WSL puts the Windows PATH on its own. Agents there run a Windows program by its .exe name.
+  if (!file && wslInterop) {
+    for (const name of tool.commands('win32').map((name) => `${name}.exe`)) {
+      file = resolve(name, env, platform);
+      if (file) return { ...base, status: 'on_path', path: file, command: name, detail: 'A Windows program, run through WSL. Its version is not checked.' };
+    }
+  }
+  const onPath = Boolean(file);
+  if (!file) file = await installed(id);
+  if (!file) return { ...base, detail: 'Not on PATH or in the usual install locations.' };
+  const row = { ...base, status: onPath ? 'on_path' : 'not_on_path', path: file, command };
+  try {
+    const program = inspect(file, tool, { platform });
+    if (program.reason) return { ...row, detail: program.reason };
+    const result = await run(program.file, args, { env: designEnv(env, cwd), cwd, kills, timeoutMs: DESIGN_TIMEOUT_MS });
+    const version = !result.error && result.code === 0 ? pattern.exec(result.output)?.[1] : null;
+    if (version) return { ...row, version };
+    return { ...row, detail: result.error === 'Version check timed out.' ? 'The version check timed out.'
+      : result.error ? 'Could not read its version.' : 'Its version response was not recognized.' };
+  } catch { return { ...row, detail: 'Could not read its version.' }; }
+}
+
+export async function scanDesignTools({ env, cwd, platform = process.platform, resolve = resolveCommand, kills = null, send = () => {} } = {}) {
+  let folders = null;
+  // Read the registry at most once, and only when some tool is missing from PATH.
+  const registry = () => folders ??= platform === 'win32'
+    ? windowsInstallFolders({ env, cwd, kills }).catch(() => ({}))
+    : Promise.resolve({});
+  const installed = async (id) => findInstalled(designLocations(id, { platform, env, registry: (await registry())[id] || [] }), { platform });
+  const wslInterop = platform === 'linux' && isWsl({ env }) && wslInteropEnabled();
+  // Bounded concurrency: cold starts of large applications compete for the disk.
+  const queue = [...DESIGN_TOOLS];
+  await Promise.all([0, 1, 2].map(async () => {
+    for (let tool = queue.shift(); tool; tool = queue.shift()) {
+      send(await scanDesignTool(tool, { env, cwd, platform, resolve, installed, kills, wslInterop }));
+    }
+  }));
+}
+
 // Windows cannot remove a process's current working directory, and a probe
 // killed at its deadline can still hold that directory. Cleanup must not
 // decide whether the scan succeeded.
@@ -235,13 +462,25 @@ if (process.argv[2] === '--scan-environment' && process.send) {
     process.chdir(cwd);
     const env = { ...process.env };
     process.send({ tools: detectTools({ env }) });
-    // Two batches bound concurrency while giving each runtime its own result.
-    for (let i = 0; i < RUNTIMES.length; i += 3) {
-      await Promise.all(RUNTIMES.slice(i, i + 3).map(async (definition) => {
-        const runtime = await scanRuntime(definition, { env, cwd, kills });
-        process.send({ runtime });
-      }));
-    }
+    await Promise.all([
+      (async () => {
+        // Two batches bound concurrency while giving each runtime its own result.
+        for (let i = 0; i < RUNTIMES.length; i += 3) {
+          await Promise.all(RUNTIMES.slice(i, i + 3).map(async (definition) => {
+            const runtime = await scanRuntime(definition, { env, cwd, kills });
+            process.send({ runtime });
+          }));
+        }
+      })(),
+      scanDesignTools({ env, cwd, kills, send: (design) => process.send({ design }) }),
+      dockerInfo({ env, resolve: resolveCommand })
+        .catch(() => ({ status: 'failed', detail: 'The Docker check did not finish.' }))
+        .then((docker) => process.send({ docker })),
+      // System facts are the same for every scope, so only the manager asks.
+      process.argv.includes('--system') && systemInfo({ env, cwd, run: runProbe, kills })
+        .catch(() => null)
+        .then((system) => process.send({ system })),
+    ]);
     finished = true;
   } finally {
     await releaseScanDirectory(cwd, kills);

package/src/manager/environment-system.mjs

@@ -0,0 +1,205 @@
+// System facts and the Docker engine, for the environment helper. Reads only:
+// os, a few small files, one registry query on Windows, and one GET /version
+// on a local Docker socket or pipe. No docker process is started and a remote
+// engine is never contacted. Where systemd starts the engine on demand
+// (docker.socket, podman.socket), opening its socket starts it.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import http from 'node:http';
+import { createHash } from 'node:crypto';
+
+const DOCKER_TIMEOUT_MS = 1500;
+const DOCKER_LIMIT = 256 * 1024;
+const REGISTRY_TIMEOUT_MS = 3000;
+const LXSS = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Lxss';
+// Linux's system sockets belong to the docker group; a rootless or Podman socket does not.
+const GROUP_SOCKETS = ['/var/run/docker.sock', '/run/docker.sock'];
+
+function value(env, name) {
+  return env[Object.keys(env).find((key) => key.toUpperCase() === name.toUpperCase())];
+}
+
+function readText(file, read) {
+  try { return read(file, 'utf8'); } catch { return null; }
+}
+
+export function isWsl({ env = process.env, release = os.release() } = {}) {
+  return Boolean(value(env, 'WSL_DISTRO_NAME')) || /microsoft|wsl/i.test(release);
+}
+
+// WSL 1 kernels end in "-Microsoft"; WSL 2 kernels name WSL2. Newer WSL registers interop as WSLInterop-late.
+export function wslInteropEnabled({ read = fs.readFileSync } = {}) {
+  return ['WSLInterop', 'WSLInterop-late'].some((name) => /^enabled/.test(readText(`/proc/sys/fs/binfmt_misc/${name}`, read) || ''));
+}
+
+function normalArch(name) {
+  const lower = String(name || '').toLowerCase();
+  if (['x86_64', 'amd64', 'x64'].includes(lower)) return 'x64';
+  if (['aarch64', 'arm64', 'aarch64_be'].includes(lower)) return 'arm64';
+  return lower || null;
+}
+
+function linuxName(read) {
+  for (const file of ['/etc/os-release', '/usr/lib/os-release']) {
+    const text = readText(file, read);
+    const match = text?.match(/^PRETTY_NAME=(["']?)(.+)\1\s*$/m);
+    if (match) return match[2];
+  }
+  return 'Linux';
+}
+
+function macName(read) {
+  const text = readText('/System/Library/CoreServices/SystemVersion.plist', read);
+  const version = text?.match(/<key>ProductVersion<\/key>\s*<string>([^<]+)<\/string>/)?.[1];
+  return version ? `macOS ${version}` : 'macOS';
+}
+
+// Windows lists WSL distributions under the user's Lxss key. Reading it does not start WSL.
+export async function wslDistributions({ env, cwd, run, kills = null } = {}) {
+  const reg = path.win32.join(value(env, 'SystemRoot') || 'C:\\Windows', 'System32', 'reg.exe');
+  const result = await run(reg, ['query', LXSS, '/s'], { env, cwd, kills, timeoutMs: REGISTRY_TIMEOUT_MS });
+  if (result.error) return null;
+  if (result.code !== 0) return /unable to find/i.test(result.output) ? [] : null;
+  const fallback = result.output.match(/^\s+DefaultDistribution\s+REG_SZ\s+(\S+)/m)?.[1]?.toLowerCase();
+  const distros = new Map();
+  let key = null;
+  for (const line of result.output.split(/\r?\n/)) {
+    if (/^HKEY_/.test(line)) key = line.trim().split('\\').pop().toLowerCase();
+    const name = line.match(/^\s+DistributionName\s+REG_SZ\s+(.+?)\s*$/)?.[1];
+    const version = line.match(/^\s+Version\s+REG_DWORD\s+0x([0-9a-f]+)/i)?.[1];
+    if (!key || !key.startsWith('{')) continue;
+    const entry = distros.get(key) || { name: null, version: null, default: key === fallback };
+    if (name) entry.name = name;
+    if (version) entry.version = parseInt(version, 16);
+    distros.set(key, entry);
+  }
+  return [...distros.values()].filter((entry) => entry.name)
+    .sort((a, b) => Number(b.default) - Number(a.default) || a.name.localeCompare(b.name));
+}
+
+export async function systemInfo({
+  env = process.env, cwd, platform = process.platform, run, kills = null,
+  read = fs.readFileSync, release = os.release(), version = os.version(),
+  arch = process.arch, machine = os.machine(), cpus = os.cpus(), threads = os.availableParallelism(), memory = os.totalmem(),
+} = {}) {
+  // Node says 'unknown' for a CPU it cannot name, such as many arm64 cores on Linux.
+  const model = cpus[0]?.model?.trim();
+  const info = {
+    os: null, osDetail: null, arch: normalArch(arch), hostArch: null,
+    cpu: { model: model && model !== 'unknown' ? model : null, threads }, memory, wsl: null, wslDistributions: null,
+  };
+  // Linux names the kernel's architecture, which can differ from Node's
+  // without emulation (a 32-bit build on a 64-bit kernel), so only Windows
+  // and macOS name a host architecture.
+  const host = platform === 'win32' || platform === 'darwin' ? normalArch(machine) : null;
+  if (host && host !== info.arch) info.hostArch = host;
+  if (platform === 'win32') {
+    info.os = version || 'Windows';
+    info.osDetail = `Version ${release}`;
+    try { info.wslDistributions = await wslDistributions({ env, cwd, run, kills }); } catch { /* the row is left out */ }
+  } else if (platform === 'darwin') {
+    info.os = macName(read);
+    info.osDetail = `Darwin ${release}`;
+  } else {
+    info.os = linuxName(read);
+    info.osDetail = `Kernel ${release}`;
+    if (isWsl({ env, release })) {
+      info.wsl = { version: /WSL2/i.test(release) ? 2 : 1, distro: value(env, 'WSL_DISTRO_NAME') || null, interop: wslInteropEnabled({ read }) };
+    }
+  }
+  return info;
+}
+
+// Which engine the docker command would use: DOCKER_HOST, then DOCKER_CONTEXT,
+// then the config's current context, then the platform default.
+export function dockerEndpoint({ env = process.env, platform = process.platform, read = fs.readFileSync } = {}) {
+  const host = value(env, 'DOCKER_HOST');
+  if (host) return { endpoint: host, context: null, source: 'DOCKER_HOST' };
+  const home = platform === 'win32' ? value(env, 'USERPROFILE') || os.homedir() : value(env, 'HOME') || os.homedir();
+  const join = platform === 'win32' ? path.win32.join : path.posix.join;
+  const configDir = value(env, 'DOCKER_CONFIG') || join(home, '.docker');
+  let context = value(env, 'DOCKER_CONTEXT');
+  let source = 'DOCKER_CONTEXT';
+  if (!context) {
+    try { context = JSON.parse(read(join(configDir, 'config.json'), 'utf8')).currentContext; } catch { /* no config */ }
+    source = 'config';
+  }
+  if (!context || context === 'default') {
+    return { endpoint: platform === 'win32' ? 'npipe:////./pipe/docker_engine' : 'unix:///var/run/docker.sock', context: 'default', source: 'default' };
+  }
+  const id = createHash('sha256').update(context).digest('hex');
+  try {
+    const meta = JSON.parse(read(join(configDir, 'contexts', 'meta', id, 'meta.json'), 'utf8'));
+    const endpoint = meta?.Endpoints?.docker?.Host;
+    if (typeof endpoint === 'string' && endpoint) return { endpoint, context, source };
+  } catch { /* reported below */ }
+  return { endpoint: null, context, source, error: `Docker context ${context} was not found.` };
+}
+
+// A local socket or named pipe, or null for an engine reached over the network.
+export function localSocket(endpoint) {
+  if (/^unix:\/\//i.test(endpoint)) return endpoint.replace(/^unix:\/\//i, '') || null;
+  if (/^npipe:/i.test(endpoint)) {
+    const name = endpoint.replace(/^npipe:/i, '').replace(/^[/\\]+\.?[/\\]+pipe[/\\]+/i, '');
+    return name && !/[/\\]/.test(name) ? `\\\\.\\pipe\\${name}` : null;
+  }
+  return null;
+}
+
+export function requestVersion(socketPath, { timeoutMs = DOCKER_TIMEOUT_MS, request = http.request } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (result) => { if (!settled) { settled = true; resolve(result); } };
+    try {
+      const req = request({ socketPath, path: '/version', method: 'GET', headers: { Host: 'docker' }, timeout: timeoutMs }, (res) => {
+        let body = '';
+        res.setEncoding('utf8');
+        res.on('data', (chunk) => {
+          body += chunk;
+          if (body.length > DOCKER_LIMIT) { req.destroy(); finish({ error: 'too_large' }); }
+        });
+        res.on('end', () => finish({ status: res.statusCode, body }));
+        res.on('error', () => finish({ error: 'read' }));
+      });
+      req.on('timeout', () => { req.destroy(); finish({ error: 'timeout' }); });
+      req.on('error', (err) => finish({ error: err.code || 'error' }));
+      req.end();
+    } catch (err) { finish({ error: err.code || 'error' }); }
+  });
+}
+
+export async function dockerInfo({ env = process.env, platform = process.platform, read = fs.readFileSync, resolve, query = requestVersion } = {}) {
+  const cli = resolve('docker', env, platform);
+  const target = dockerEndpoint({ env, platform, read });
+  const row = {
+    status: 'failed', version: null, platform: null, os: null, arch: null, wsl2: false,
+    context: target.context, endpoint: target.endpoint, cli, detail: null,
+  };
+  if (target.error) return { ...row, detail: target.error };
+  const socket = localSocket(target.endpoint);
+  if (!socket) return { ...row, status: 'remote', detail: 'This engine is reached over the network, so it is not checked.' };
+  const result = await query(socket);
+  if (result.error === 'EACCES' || result.error === 'EPERM') {
+    return { ...row, status: 'denied', detail: platform === 'win32'
+      ? 'The engine is running, but this user cannot open its pipe.'
+      : `The engine socket exists, but this user cannot open it.${platform === 'linux' && GROUP_SOCKETS.includes(socket) ? ' Adding the user to the docker group allows it.' : ''}` };
+  }
+  if (['ENOENT', 'ECONNREFUSED', 'ENOTSOCK'].includes(result.error)) {
+    return cli
+      ? { ...row, status: 'stopped', detail: 'The Docker engine is not running.' }
+      : { ...row, status: 'not_found', detail: 'No docker command on PATH and no engine answered.' };
+  }
+  if (result.error === 'timeout') return { ...row, detail: 'The engine did not answer in time.' };
+  if (result.error || result.status !== 200) return { ...row, detail: 'The engine did not give a usable answer.' };
+  let data;
+  try { data = JSON.parse(result.body); } catch { return { ...row, detail: 'The engine did not give a usable answer.' }; }
+  const version = typeof data?.Version === 'string' ? data.Version : null;
+  if (!version) return { ...row, detail: 'The engine did not give a usable answer.' };
+  const text = (item) => typeof item === 'string' && item ? item.slice(0, 200) : null;
+  return {
+    ...row, status: 'running', version,
+    platform: text(data.Platform?.Name), os: text(data.Os), arch: text(data.Arch),
+    wsl2: data.Os === 'linux' && /microsoft-standard-WSL2/i.test(data.KernelVersion || ''),
+  };
+}