@fitlab-ai/agent-infra 0.5.9 → 0.5.10

package/lib/sandbox/dotfiles.js

@@ -0,0 +1,189 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { hostJoin } from './engines/wsl2-paths.js';
+
+export function dotfilesCacheDir(home, project) {
+  return hostJoin(home, '.agent-infra', '.cache', 'dotfiles-resolved', project);
+}
+
+function dotfilesWarning(warnings, writeStderr, relPath, reason, detail = '') {
+  const warning = { rel: relPath, reason };
+  if (detail) {
+    warning.detail = detail;
+  }
+  warnings.push(warning);
+
+  const suffix = detail ? `: ${detail}` : '';
+  writeStderr(`sandbox-dotfiles (host): skipping ${relPath} (${reason}${suffix})\n`);
+}
+
+function copyDotfile(srcPath, dstPath, context) {
+  const { fsModule, relPath, warnings, writeStderr } = context;
+  try {
+    fsModule.mkdirSync(path.dirname(dstPath), { recursive: true });
+    fsModule.copyFileSync(srcPath, dstPath);
+  } catch (error) {
+    dotfilesWarning(warnings, writeStderr, relPath, 'copy failed', error?.code ?? error?.message ?? 'unknown error');
+  }
+}
+
+function walkAndMaterializeDotfiles(context) {
+  const {
+    srcDir,
+    dstDir,
+    relParts,
+    depth,
+    maxDepth,
+    activeDirs,
+    warnings,
+    writeStderr,
+    fsModule
+  } = context;
+  const relPath = relParts.length > 0 ? relParts.join('/') : '.';
+
+  if (depth > maxDepth) {
+    dotfilesWarning(warnings, writeStderr, relPath, 'depth exceeds limit', String(maxDepth));
+    return;
+  }
+
+  let entries;
+  try {
+    entries = fsModule.readdirSync(srcDir, { withFileTypes: true });
+  } catch (error) {
+    dotfilesWarning(warnings, writeStderr, relPath, 'read failed', error?.code ?? error?.message ?? 'unknown error');
+    return;
+  }
+
+  for (const entry of entries) {
+    const childSrc = path.join(srcDir, entry.name);
+    const childDst = path.join(dstDir, entry.name);
+    const childRelParts = [...relParts, entry.name];
+    const childRelPath = childRelParts.join('/');
+
+    if (entry.isSymbolicLink()) {
+      let resolvedTarget;
+      try {
+        resolvedTarget = fsModule.realpathSync(childSrc);
+      } catch (error) {
+        const reason = error?.code === 'ELOOP' ? 'symlink loop' : 'dangling symlink';
+        dotfilesWarning(warnings, writeStderr, childRelPath, reason, error?.code ?? 'unresolved');
+        continue;
+      }
+
+      let targetStat;
+      try {
+        targetStat = fsModule.statSync(resolvedTarget);
+      } catch (error) {
+        dotfilesWarning(warnings, writeStderr, childRelPath, 'target stat failed', error?.code ?? error?.message ?? 'unknown error');
+        continue;
+      }
+
+      if (targetStat.isDirectory()) {
+        if (activeDirs.has(resolvedTarget)) {
+          dotfilesWarning(warnings, writeStderr, childRelPath, 'symlink loop');
+          continue;
+        }
+
+        activeDirs.add(resolvedTarget);
+        walkAndMaterializeDotfiles({
+          srcDir: resolvedTarget,
+          dstDir: childDst,
+          relParts: childRelParts,
+          depth: depth + 1,
+          maxDepth,
+          activeDirs,
+          warnings,
+          writeStderr,
+          fsModule
+        });
+        activeDirs.delete(resolvedTarget);
+        continue;
+      }
+
+      if (targetStat.isFile()) {
+        copyDotfile(resolvedTarget, childDst, {
+          fsModule,
+          relPath: childRelPath,
+          warnings,
+          writeStderr
+        });
+      }
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      let childRealPath = null;
+      try {
+        childRealPath = fsModule.realpathSync(childSrc);
+      } catch {
+        // A real directory may disappear during traversal; readdir will warn below.
+      }
+      if (childRealPath) {
+        activeDirs.add(childRealPath);
+      }
+      walkAndMaterializeDotfiles({
+        srcDir: childSrc,
+        dstDir: childDst,
+        relParts: childRelParts,
+        depth: depth + 1,
+        maxDepth,
+        activeDirs,
+        warnings,
+        writeStderr,
+        fsModule
+      });
+      if (childRealPath) {
+        activeDirs.delete(childRealPath);
+      }
+      continue;
+    }
+
+    if (entry.isFile()) {
+      copyDotfile(childSrc, childDst, {
+        fsModule,
+        relPath: childRelPath,
+        warnings,
+        writeStderr
+      });
+    }
+  }
+}
+
+export function materializeDotfiles(srcDir, cacheDir, options = {}) {
+  const {
+    writeStderr = (message) => process.stderr.write(message),
+    maxDepth = 32,
+    fsModule = fs
+  } = options;
+
+  if (!srcDir || !fsModule.existsSync(srcDir)) {
+    return null;
+  }
+
+  fsModule.mkdirSync(cacheDir, { recursive: true });
+  for (const entry of fsModule.readdirSync(cacheDir)) {
+    fsModule.rmSync(path.join(cacheDir, entry), { recursive: true, force: true });
+  }
+
+  const warnings = [];
+  const activeDirs = new Set();
+  try {
+    activeDirs.add(fsModule.realpathSync(srcDir));
+  } catch {
+    activeDirs.add(srcDir);
+  }
+
+  walkAndMaterializeDotfiles({
+    srcDir,
+    dstDir: cacheDir,
+    relParts: [],
+    depth: 0,
+    maxDepth,
+    activeDirs,
+    warnings,
+    writeStderr,
+    fsModule
+  });
+
+  return { cacheDir, warnings };
+}

package/lib/sandbox/engine.js

@@ -1,256 +1,199 @@
 import { platform } from 'node:os';
 import { detectHostResources } from './constants.js';
+import { ADAPTERS, enginesForPlatform, getAdapter } from './engines/index.js';
 import { run, runOk, runSafe, runVerbose } from './shell.js';
 
 export const ENGINES = Object.freeze({
   COLIMA: 'colima',
   ORBSTACK: 'orbstack',
-  DOCKER_DESKTOP: 'docker-desktop'
+  DOCKER_DESKTOP: 'docker-desktop',
+  NATIVE: 'native',
+  WSL2: 'wsl2'
 });
 
-export const ENGINE_DOCKER_CONTEXT = Object.freeze({
-  [ENGINES.COLIMA]: 'colima',
-  [ENGINES.ORBSTACK]: 'orbstack',
-  [ENGINES.DOCKER_DESKTOP]: 'desktop-linux'
+const PLATFORM_DEFAULTS = Object.freeze({
+  linux: ENGINES.NATIVE,
+  darwin: ENGINES.COLIMA,
+  win32: ENGINES.WSL2
 });
 
-const VALID_CONFIG_ENGINES = new Set(Object.values(ENGINES));
+function runFns({
+  runFn = run,
+  runOkFn = runOk,
+  runSafeFn = runSafe,
+  runVerboseFn = runVerbose
+} = {}) {
+  return {
+    run: runFn,
+    runOk: runOkFn,
+    runSafe: runSafeFn,
+    runVerbose: runVerboseFn
+  };
+}
 
-function applyDockerContext(engine) {
-  const context = ENGINE_DOCKER_CONTEXT[engine];
-  if (context) {
-    process.env.DOCKER_CONTEXT = context;
+function applyDockerContext(adapter) {
+  if (adapter.dockerContext) {
+    process.env.DOCKER_CONTEXT = adapter.dockerContext;
   }
 }
 
-export function validateSandboxEngine(engine) {
+export function validateSandboxEngine(engine, { platformFn = platform } = {}) {
   if (engine === null || engine === undefined) {
     return null;
   }
 
-  if (VALID_CONFIG_ENGINES.has(engine)) {
-    return engine;
-  }
-
-  throw new Error(
-    `sandbox: invalid "sandbox.engine" value "${engine}". `
-    + 'Expected one of: null, colima, orbstack, docker-desktop. '
-    + 'This setting only affects macOS sandbox engine selection.'
-  );
-}
-
-export function detectEngine(config = {}, { platformFn = platform } = {}) {
-  const configured = validateSandboxEngine(config.engine);
   const os = platformFn();
-  if (os === 'linux') {
-    return 'native';
-  }
-  if (os === 'win32') {
-    return 'wsl2';
-  }
-  if (os === 'darwin') {
-    if (configured) {
-      return configured;
-    }
-
-    return ENGINES.COLIMA;
+  if (!(engine in ADAPTERS)) {
+    const known = Object.keys(ADAPTERS).join(', ');
+    throw new Error(
+      `sandbox: invalid "sandbox.engine" value "${engine}" (unknown sandbox engine). `
+      + `Valid engines: ${known}.`
+    );
   }
-  return 'unsupported';
-}
 
-function colimaArgs(config, runSafeFn = runSafe) {
-  const arch = runSafeFn('uname', ['-m']);
-  const defaults = detectHostResources();
-  const vm = config.vm ?? {};
-  const cpu = vm.cpu ?? defaults.cpu;
-  const memory = vm.memory ?? defaults.memory;
-  const disk = vm.disk ?? 60;
-  const args = ['start', '--cpu', String(cpu), '--memory', String(memory), '--disk', String(disk)];
-
-  if (arch === 'arm64') {
-    args.push('--arch', 'aarch64', '--vm-type=vz', '--mount-type=virtiofs');
-  } else {
-    args.push('--arch', 'x86_64');
+  const adapter = ADAPTERS[engine];
+  if (!adapter.supportedPlatforms.includes(os)) {
+    const supported = enginesForPlatform(os);
+    const supportedList = supported.length > 0 ? supported.join(', ') : 'none';
+    throw new Error(
+      `sandbox: "sandbox.engine" value "${engine}" is not supported on ${os}. `
+      + `Supported engines on ${os}: ${supportedList}.`
+    );
   }
 
-  return args;
+  return engine;
 }
 
-export async function ensureColima(
-  config,
-  onMessage,
-  { runOkFn = runOk, runSafeFn = runSafe, runVerboseFn = runVerbose } = {}
-) {
-  applyDockerContext(ENGINES.COLIMA);
-
-  if (!runOkFn('which', ['colima'])) {
-    onMessage?.('Installing colima + docker via Homebrew...');
-    runVerboseFn('brew', ['install', 'colima', 'docker']);
+export function detectEngine(config = {}, { platformFn = platform } = {}) {
+  const configured = validateSandboxEngine(config.engine, { platformFn });
+  if (configured) {
+    return configured;
   }
 
-  if (!runOkFn('colima', ['status'])) {
-    onMessage?.('Starting Colima VM...');
-    runVerboseFn('colima', colimaArgs(config, runSafeFn));
+  const os = platformFn();
+  const fallback = PLATFORM_DEFAULTS[os];
+  if (fallback) {
+    return fallback;
   }
 
-  if (!runOkFn('docker', ['info'])) {
-    throw new Error('Docker daemon is not available after starting Colima');
-  }
+  throw new Error(
+    `sandbox: platform "${os}" is not supported. `
+    + 'Supported platforms: linux (native), darwin (colima/orbstack/docker-desktop), win32 (wsl2). '
+    + 'Please open an issue at https://github.com/fitlab-ai/agent-infra/issues/new '
+    + 'with your platform details if you need this added.'
+  );
 }
 
-export async function ensureOrbStack(
-  _config,
-  onMessage,
-  { runOkFn = runOk, runVerboseFn = runVerbose } = {}
-) {
-  applyDockerContext(ENGINES.ORBSTACK);
-
-  if (!runOkFn('which', ['orb'])) {
-    onMessage?.('Installing OrbStack via Homebrew...');
-    runVerboseFn('brew', ['install', '--cask', 'orbstack']);
-  }
-
-  if (!runOkFn('docker', ['info'])) {
-    onMessage?.('Starting OrbStack...');
-    runVerboseFn('orb', ['start']);
-  }
-
-  if (!runOkFn('docker', ['info'])) {
-    throw new Error('Docker daemon is not available after starting OrbStack');
-  }
+export function hasUserVmConfig(vm = {}) {
+  return vm.cpu != null || vm.memory != null || vm.disk != null;
 }
 
-export async function ensureDockerDesktop(
-  _config,
-  onMessage,
-  { runOkFn = runOk } = {}
+export function resolveEffectiveVm(
+  adapter,
+  userVm = {},
+  { detectHostResourcesFn = detectHostResources } = {}
 ) {
-  applyDockerContext(ENGINES.DOCKER_DESKTOP);
+  let host = null;
+  const getHost = () => {
+    host ??= detectHostResourcesFn();
+    return host;
+  };
+  const defaults = adapter.defaultResources?.(getHost) ?? {};
 
-  if (!runOkFn('docker', ['info'])) {
-    throw new Error('Docker Desktop is not running. Please start Docker Desktop manually.');
-  }
+  return {
+    cpu: userVm.cpu ?? defaults.cpu ?? null,
+    memory: userVm.memory ?? defaults.memory ?? null,
+    disk: userVm.disk ?? defaults.disk ?? null
+  };
 }
 
-export async function ensureNativeDocker(
-  _config,
-  _onMessage,
-  { runOkFn = runOk, runSafeFn = runSafe } = {}
-) {
-  if (!runOkFn('which', ['docker'])) {
-    throw new Error([
-      'Docker is not installed.',
-      'Install Docker Engine for your distribution: https://docs.docker.com/engine/install/',
-      'Then start the daemon with: sudo systemctl enable --now docker',
-      'If you want to run Docker without sudo, add your user to the docker group: sudo usermod -aG docker $USER'
-    ].join('\n'));
-  }
-
-  if (runOkFn('docker', ['info'])) {
-    return;
-  }
-
-  const serverVersion = runSafeFn('docker', ['version', '--format', '{{.Server.Version}}']);
-  if (!serverVersion) {
-    throw new Error([
-      'Docker daemon is not running or is unreachable.',
-      'Start it with: sudo systemctl start docker',
-      'Enable it on boot with: sudo systemctl enable docker',
-      'If you use rootless or remote Docker, verify DOCKER_HOST points at a reachable socket.',
-      'Then retry: ai sandbox create <branch>'
-    ].join('\n'));
-  }
-
-  throw new Error([
-    'Docker is installed, but the current user may lack permission to use the daemon.',
-    'Add your user to the docker group: sudo usermod -aG docker $USER',
-    'Open a new login shell or run: newgrp docker',
-    'For rootless Docker, make sure DOCKER_HOST points at the rootless daemon socket.'
-  ].join('\n'));
+function effectiveConfigFor(adapter, config) {
+  const userVm = config.vm ?? {};
+  return {
+    ...config,
+    userVm,
+    hasUserVmConfig,
+    vm: resolveEffectiveVm(adapter, userVm)
+  };
 }
 
-export async function ensureDocker(config, onMessage) {
-  const engine = detectEngine(config);
-
-  if (engine === ENGINES.COLIMA) {
-    await ensureColima(config, onMessage);
-    return;
-  }
-
-  if (engine === ENGINES.ORBSTACK) {
-    await ensureOrbStack(config, onMessage);
-    return;
-  }
-
-  if (engine === ENGINES.DOCKER_DESKTOP) {
-    await ensureDockerDesktop(config, onMessage);
-    return;
-  }
-
-  if (engine === 'native') {
-    await ensureNativeDocker(config, onMessage);
-    return;
-  }
-
-  if (engine === 'wsl2') {
-    throw new Error('Windows sandbox support is reserved for a future WSL2 implementation.');
-  }
+export async function ensureDocker(config, onMessage, dependencies = {}) {
+  const engine = detectEngine(config, dependencies);
+  const adapter = getAdapter(engine);
+  const effectiveConfig = effectiveConfigFor(adapter, config);
 
-  throw new Error(`Unsupported sandbox engine: ${engine}`);
+  applyDockerContext(adapter);
+  const vmJustStarted = await adapter.ensure(effectiveConfig, onMessage, runFns(dependencies));
+  adapter.syncResources(effectiveConfig, onMessage, runFns(dependencies), { vmJustStarted });
 }
 
 export function isVmManaged(config = {}, dependencies = {}) {
-  const engine = detectEngine(config, dependencies);
-  return isManagedEngine(engine);
+  try {
+    const engine = detectEngine(config, dependencies);
+    return isManagedEngine(engine);
+  } catch (error) {
+    const message = error?.message ?? '';
+    if (
+      message.startsWith('sandbox: platform "')
+      || / is not supported on [^.]+\. Supported engines on [^:]+: none\./.test(message)
+    ) {
+      return false;
+    }
+
+    throw error;
+  }
 }
 
 export function isManagedEngine(engine) {
-  return engine === ENGINES.COLIMA || engine === ENGINES.ORBSTACK;
+  try {
+    return getAdapter(engine).managed;
+  } catch {
+    return false;
+  }
 }
 
 export function engineDisplayName(engine) {
-  const names = {
-    [ENGINES.COLIMA]: 'Colima',
-    [ENGINES.ORBSTACK]: 'OrbStack',
-    [ENGINES.DOCKER_DESKTOP]: 'Docker Desktop',
-    native: 'native Docker',
-    wsl2: 'WSL2'
-  };
-  return names[engine] ?? engine;
+  try {
+    return getAdapter(engine).displayName;
+  } catch {
+    return engine;
+  }
 }
 
 export function startManagedVm(
   config,
-  { platformFn = platform, runOkFn = runOk, runVerboseFn = runVerbose } = {}
+  { platformFn = platform, runOkFn = runOk, runSafeFn = runSafe, runVerboseFn = runVerbose, onMessage } = {}
 ) {
   const engine = detectEngine(config, { platformFn });
-  if (!isManagedEngine(engine)) {
-    throw new Error(`VM management is unavailable for engine '${engineDisplayName(engine)}'.`);
-  }
-
-  if (engine === ENGINES.COLIMA && runOkFn('colima', ['status'])) {
-    return 'already-running';
-  }
-  if (engine === ENGINES.ORBSTACK && runOkFn('orb', ['status'])) {
-    return 'already-running';
+  const adapter = getAdapter(engine);
+  if (!adapter.managed) {
+    throw new Error(`VM management is unavailable for engine '${adapter.displayName}'.`);
   }
 
-  if (engine === ENGINES.COLIMA) {
-    runVerboseFn('colima', colimaArgs(config));
-  } else if (engine === ENGINES.ORBSTACK) {
-    runVerboseFn('orb', ['start']);
-  }
-  return 'started';
+  const effectiveConfig = effectiveConfigFor(adapter, config);
+  applyDockerContext(adapter);
+  const result = adapter.startVm(
+    effectiveConfig,
+    onMessage,
+    runFns({ runOkFn, runSafeFn, runVerboseFn })
+  );
+  adapter.syncResources(
+    effectiveConfig,
+    onMessage,
+    runFns({ runOkFn, runSafeFn, runVerboseFn }),
+    { vmJustStarted: result === 'started' }
+  );
+  return result;
 }
 
 export function stopManagedVm(config, { platformFn = platform, runFn = run } = {}) {
   const engine = detectEngine(config, { platformFn });
-  if (engine === ENGINES.COLIMA) {
-    runFn('colima', ['stop']);
-    return 'stopped';
-  } else if (engine === ENGINES.ORBSTACK) {
-    runFn('orb', ['stop']);
-    return 'stopped';
+  const adapter = getAdapter(engine);
+  if (!adapter.managed) {
+    throw new Error(`VM management is unavailable for engine '${adapter.displayName}'.`);
   }
-  throw new Error(`VM management is unavailable for engine '${engineDisplayName(engine)}'.`);
+
+  // Stop commands do not read Docker context or VM resource values; keep the
+  // previous environment unchanged and pass the original config intentionally.
+  return adapter.stopVm(config, null, runFns({ runFn }));
 }

package/lib/sandbox/engines/colima.js

@@ -0,0 +1,79 @@
+function colimaArgs(config, runSafeFn) {
+  const arch = runSafeFn('uname', ['-m']);
+  const vm = config.vm ?? {};
+  const args = ['start', '--cpu', String(vm.cpu), '--memory', String(vm.memory), '--disk', String(vm.disk)];
+
+  if (arch === 'arm64') {
+    args.push('--arch', 'aarch64', '--vm-type=vz', '--mount-type=virtiofs');
+  } else {
+    args.push('--arch', 'x86_64');
+  }
+
+  return args;
+}
+
+export const colimaAdapter = {
+  id: 'colima',
+  displayName: 'Colima',
+  supportedPlatforms: ['darwin'],
+  dockerContext: 'colima',
+  managed: true,
+  canApplyResources: 'on-start',
+
+  defaultResources(getHost) {
+    const host = getHost();
+    return {
+      cpu: host.cpu,
+      memory: host.memory,
+      disk: 60
+    };
+  },
+
+  async ensure(config, onMessage, { runOk, runSafe, runVerbose }) {
+    let started = false;
+
+    if (!runOk('which', ['colima'])) {
+      onMessage?.('Installing colima + docker via Homebrew...');
+      runVerbose('brew', ['install', 'colima', 'docker']);
+    }
+
+    if (!runOk('colima', ['status'])) {
+      onMessage?.('Starting Colima VM...');
+      runVerbose('colima', colimaArgs(config, runSafe));
+      started = true;
+    }
+
+    if (!runOk('docker', ['info'])) {
+      throw new Error('Docker daemon is not available after starting Colima');
+    }
+
+    return started;
+  },
+
+  startVm(config, _onMessage, { runOk, runSafe, runVerbose }) {
+    if (runOk('colima', ['status'])) {
+      return 'already-running';
+    }
+
+    runVerbose('colima', colimaArgs(config, runSafe));
+    return 'started';
+  },
+
+  stopVm(_config, _onMessage, { run }) {
+    run('colima', ['stop']);
+    return 'stopped';
+  },
+
+  syncResources(config, onMessage, _runFns, { vmJustStarted } = {}) {
+    if (vmJustStarted || !config.hasUserVmConfig?.(config.userVm)) {
+      return;
+    }
+
+    onMessage?.(
+      'Warning: Colima VM is already running; restart with '
+      + '`ai sandbox vm stop && ai sandbox vm start` to apply new sandbox.vm.* values.'
+    );
+  }
+};
+
+export default colimaAdapter;

package/lib/sandbox/engines/docker-desktop.js

@@ -0,0 +1,34 @@
+export const dockerDesktopAdapter = {
+  id: 'docker-desktop',
+  displayName: 'Docker Desktop',
+  supportedPlatforms: ['darwin', 'linux', 'win32'],
+  dockerContext: 'desktop-linux',
+  managed: false,
+  canApplyResources: 'never',
+
+  defaultResources() {
+    return null;
+  },
+
+  async ensure(_config, _onMessage, { runOk }) {
+    if (!runOk('docker', ['info'])) {
+      throw new Error('Docker Desktop is not running. Please start Docker Desktop manually.');
+    }
+
+    return false;
+  },
+
+  syncResources(config, onMessage) {
+    if (!config.hasUserVmConfig?.(config.userVm)) {
+      return;
+    }
+
+    onMessage?.(
+      'Warning: Docker Desktop manages CPU/memory/disk via Settings -> Resources. '
+      + 'sandbox.vm.* values and --cpu/--memory flags are not applied for this engine. '
+      + 'Please configure resources in Docker Desktop GUI to match.'
+    );
+  }
+};
+
+export default dockerDesktopAdapter;