@fitlab-ai/agent-infra 0.4.5 → 0.5.1

package/lib/sandbox/commands/enter.js

@@ -0,0 +1,64 @@
+import { loadConfig } from '../config.js';
+import { assertValidBranchName, containerNameCandidates } from '../constants.js';
+import { runInteractive, runSafe } from '../shell.js';
+import { resolveTaskBranch } from '../task-resolver.js';
+
+const USAGE = `Usage: ai sandbox exec <branch> [cmd...]`;
+export const TMUX_INTERACTIVE_TIP =
+  "tip: for long-running TUI sessions, run 'tmux new -s work' to survive disconnects (reattach with 'tmux a -t work')\n";
+
+export function printInteractiveEntryTip(stream = process.stderr) {
+  stream.write(TMUX_INTERACTIVE_TIP);
+}
+
+// Terminal-detection variables that interactive TUIs (e.g. claude-code)
+// inspect to enable progressive enhancements such as the kitty keyboard
+// protocol, which is what makes Shift+Enter distinguishable from Enter.
+// `docker exec` does not forward these by default, so we must pass them
+// through explicitly.
+const FORWARDED_TERMINAL_ENV = [
+  'TERM_PROGRAM',
+  'TERM_PROGRAM_VERSION',
+  'LC_TERMINAL',
+  'LC_TERMINAL_VERSION'
+];
+
+export function terminalEnvFlags(env = process.env) {
+  const flags = [];
+  for (const name of FORWARDED_TERMINAL_ENV) {
+    const value = env[name];
+    if (value) {
+      flags.push('-e', `${name}=${value}`);
+    }
+  }
+  return flags;
+}
+
+export function enter(args) {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(`${USAGE}\n`);
+    if (args.length === 0) {
+      return 1;
+    }
+    return 0;
+  }
+
+  const config = loadConfig();
+  const [branchOrTaskId, ...cmd] = args;
+  const branch = resolveTaskBranch(branchOrTaskId, config.repoRoot);
+  assertValidBranchName(branch);
+  const running = runSafe('docker', ['ps', '--format', '{{.Names}}']).split('\n');
+  const container = containerNameCandidates(config, branch).find((name) => running.includes(name));
+
+  if (!container) {
+    throw new Error(`No running sandbox found for branch '${branch}'`);
+  }
+
+  const envFlags = terminalEnvFlags();
+  if (cmd.length === 0) {
+    printInteractiveEntryTip();
+    return runInteractive('docker', ['exec', '-it', ...envFlags, container, 'bash']);
+  }
+
+  return runInteractive('docker', ['exec', '-it', ...envFlags, container, ...cmd]);
+}

package/lib/sandbox/commands/ls.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { loadConfig } from '../config.js';
+import { sandboxLabel } from '../constants.js';
+import { runSafe } from '../shell.js';
+import { resolveTools, toolProjectDirCandidates } from '../tools.js';
+
+const USAGE = 'Usage: ai sandbox ls';
+
+function listChildren(dir) {
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+
+  return fs.readdirSync(dir).sort().map((entry) => path.join(dir, entry));
+}
+
+export function ls(args = []) {
+  if (args.length > 0 && (args[0] === '--help' || args[0] === '-h')) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  const config = loadConfig();
+  const tools = resolveTools(config);
+  const label = sandboxLabel(config);
+  const containers = runSafe('docker', [
+    'ps',
+    '-a',
+    '--filter',
+    `label=${label}`,
+    '--format',
+    'table {{.Names}}\t{{.Status}}\t{{.Label "' + `${label}.branch` + '"}}'
+  ]);
+
+  p.intro(pc.cyan(`Sandbox status for ${config.project}`));
+
+  p.log.step('Containers');
+  if (!containers || containers.split('\n').length <= 1) {
+    p.log.warn('  No sandbox containers');
+  } else {
+    for (const line of containers.split('\n')) {
+      process.stdout.write(`  ${line}\n`);
+    }
+  }
+
+  p.log.step('Worktrees');
+  const worktrees = listChildren(config.worktreeBase);
+  if (worktrees.length === 0) {
+    p.log.warn('  No sandbox worktrees');
+  } else {
+    for (const worktree of worktrees) {
+      process.stdout.write(`  ${worktree}\n`);
+    }
+  }
+
+  for (const tool of tools) {
+    p.log.step(`${tool.name} state`);
+    const entries = toolProjectDirCandidates(tool, config.project)
+      .flatMap((dir) => listChildren(dir));
+    if (entries.length === 0) {
+      p.log.warn(`  No ${tool.name} sandbox state`);
+      continue;
+    }
+    for (const entry of entries) {
+      process.stdout.write(`  ${entry}\n`);
+    }
+  }
+}

package/lib/sandbox/commands/rebuild.js

@@ -0,0 +1,102 @@
+import { parseArgs } from 'node:util';
+import { createHash } from 'node:crypto';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { loadConfig } from '../config.js';
+import { prepareDockerfile } from '../dockerfile.js';
+import { sandboxImageConfigLabel, sandboxLabel } from '../constants.js';
+import { ensureDocker } from '../engine.js';
+import { run, runOk, runVerbose } from '../shell.js';
+import { resolveTools, toolNpmPackagesArg } from '../tools.js';
+
+const USAGE = `Usage: ai sandbox rebuild [--quiet]`;
+
+function buildSignature(preparedDockerfile, tools) {
+  return createHash('sha256')
+    .update(JSON.stringify({
+      dockerfile: preparedDockerfile.signature,
+      tools: tools.map((tool) => tool.npmPackage)
+    }))
+    .digest('hex')
+    .slice(0, 12);
+}
+
+function buildArgs(config, tools, dockerfilePath, imageSignature) {
+  const hostUid = run('id', ['-u']);
+  const hostGid = run('id', ['-g']);
+
+  return [
+    'build',
+    '-t',
+    config.imageName,
+    '--build-arg',
+    `HOST_UID=${hostUid}`,
+    '--build-arg',
+    `HOST_GID=${hostGid}`,
+    '--build-arg',
+    `AI_TOOL_PACKAGES=${toolNpmPackagesArg(tools)}`,
+    '--label',
+    sandboxLabel(config),
+    '--label',
+    `${sandboxImageConfigLabel(config)}=${imageSignature}`,
+    '-f',
+    dockerfilePath,
+    config.repoRoot
+  ];
+}
+
+function removeImageIfPresent(imageName) {
+  if (runOk('docker', ['image', 'inspect', imageName])) {
+    run('docker', ['rmi', imageName]);
+  }
+}
+
+export async function rebuild(args) {
+  const { values } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      quiet: { type: 'boolean', short: 'q' },
+      help: { type: 'boolean', short: 'h' }
+    }
+  });
+
+  if (values.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  const config = loadConfig();
+  const tools = resolveTools(config);
+  const preparedDockerfile = prepareDockerfile(config);
+  const imageSignature = buildSignature(preparedDockerfile, tools);
+  const quiet = values.quiet ?? false;
+
+  await ensureDocker(config);
+  p.intro(pc.cyan('Rebuilding sandbox image'));
+
+  try {
+    if (quiet) {
+      const spinner = p.spinner();
+      spinner.start(`Removing old image ${config.imageName}...`);
+      removeImageIfPresent(config.imageName);
+      spinner.stop('Old image removed');
+      spinner.start('Building image...');
+      run('docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature), { cwd: config.repoRoot });
+      spinner.stop(pc.green('Sandbox image rebuilt'));
+    } else {
+      p.log.step(`Removing old image ${config.imageName}`);
+      removeImageIfPresent(config.imageName);
+      p.log.step('Building image');
+      runVerbose(
+        'docker',
+        buildArgs(config, tools, preparedDockerfile.path, imageSignature),
+        { cwd: config.repoRoot }
+      );
+      p.log.success(pc.green('Sandbox image rebuilt'));
+    }
+  } finally {
+    preparedDockerfile.cleanup();
+  }
+}

package/lib/sandbox/commands/rm.js

@@ -0,0 +1,211 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { loadConfig } from '../config.js';
+import {
+  assertValidBranchName,
+  containerNameCandidates,
+  sandboxBranchLabel,
+  sandboxLabel,
+  worktreeDirCandidates
+} from '../constants.js';
+import { isVmManaged } from '../engine.js';
+import { run, runOk, runSafe } from '../shell.js';
+import { resolveTaskBranch } from '../task-resolver.js';
+import { resolveTools, toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.js';
+
+const USAGE = `Usage: ai sandbox rm <branch> [--all]`;
+
+function projectToolDirs(config, tools) {
+  return tools.flatMap((tool) => toolProjectDirCandidates(tool, config.project));
+}
+
+async function rmOne(config, tools, branch) {
+  assertValidBranchName(branch);
+  let effectiveBranch = branch;
+  let worktreeCandidates = worktreeDirCandidates(config, branch);
+  let toolCandidates = tools.map((tool) => ({
+    tool,
+    candidates: toolConfigDirCandidates(tool, config.project, branch)
+  }));
+
+  p.intro(pc.cyan(`Removing sandbox for ${branch}`));
+
+  const existing = runSafe('docker', ['ps', '-a', '--format', '{{.Names}}']).split('\n').filter(Boolean);
+  const matchedContainers = containerNameCandidates(config, branch)
+    .filter((name) => existing.includes(name));
+
+  if (matchedContainers.length > 0) {
+    const resolvedBranch = runSafe('docker', [
+      'inspect',
+      '-f',
+      `{{ index .Config.Labels "${sandboxBranchLabel(config)}" }}`,
+      matchedContainers[0]
+    ]);
+    if (resolvedBranch) {
+      effectiveBranch = resolvedBranch;
+      worktreeCandidates = worktreeDirCandidates(config, effectiveBranch);
+      toolCandidates = tools.map((tool) => ({
+        tool,
+        candidates: toolConfigDirCandidates(tool, config.project, effectiveBranch)
+      }));
+    }
+
+    const spinner = p.spinner();
+    spinner.start(`Stopping container(s): ${matchedContainers.join(', ')}`);
+    for (const name of matchedContainers) {
+      runSafe('docker', ['stop', name]);
+      runSafe('docker', ['rm', name]);
+    }
+    spinner.stop(pc.green(`Removed container(s): ${matchedContainers.join(', ')}`));
+  } else {
+    p.log.warn(`No sandbox container found for '${branch}'`);
+  }
+
+  const existingWorktrees = worktreeCandidates.filter((candidate) => fs.existsSync(candidate));
+  if (existingWorktrees.length > 0) {
+    const shouldRemoveWorktree = await p.confirm({
+      message: `Remove worktree(s): ${existingWorktrees.join(', ')}?`,
+      initialValue: true
+    });
+
+    if (p.isCancel(shouldRemoveWorktree)) {
+      p.outro('Cancelled');
+      return;
+    }
+
+    if (shouldRemoveWorktree) {
+      for (const worktree of existingWorktrees) {
+        try {
+          run('git', ['-C', config.repoRoot, 'worktree', 'remove', worktree, '--force']);
+        } catch {
+          fs.rmSync(worktree, { recursive: true, force: true });
+        }
+      }
+
+      const shouldDeleteBranch = await p.confirm({
+        message: `Also delete local branch '${effectiveBranch}'?`,
+        initialValue: false
+      });
+
+      if (!p.isCancel(shouldDeleteBranch) && shouldDeleteBranch) {
+        if (!runOk('git', ['-C', config.repoRoot, 'branch', '-D', effectiveBranch])) {
+          p.log.warn(`Local branch '${effectiveBranch}' was not deleted`);
+        }
+      }
+    }
+  }
+
+  for (const { tool, candidates } of toolCandidates) {
+    for (const dir of candidates.filter((candidate) => fs.existsSync(candidate))) {
+      fs.rmSync(dir, { recursive: true, force: true });
+      p.log.success(`${tool.name} state removed: ${dir}`);
+    }
+  }
+
+  p.outro(pc.green('Sandbox removed'));
+}
+
+async function rmAll(config, tools) {
+  p.intro(pc.cyan(`Removing all sandboxes for ${config.project}`));
+
+  const containers = runSafe('docker', [
+    'ps',
+    '-a',
+    '--filter',
+    `label=${sandboxLabel(config)}`,
+    '--format',
+    '{{.Names}}'
+  ]);
+  if (containers) {
+    const spinner = p.spinner();
+    spinner.start('Stopping project sandbox containers...');
+    for (const name of containers.split('\n').filter(Boolean)) {
+      runSafe('docker', ['stop', name]);
+      runSafe('docker', ['rm', name]);
+    }
+    spinner.stop(pc.green('Project sandbox containers removed'));
+  } else {
+    p.log.warn('No project sandbox containers found');
+  }
+
+  if (fs.existsSync(config.worktreeBase) && fs.readdirSync(config.worktreeBase).length > 0) {
+    const shouldRemoveWorktrees = await p.confirm({
+      message: `Remove all worktrees in ${config.worktreeBase}?`,
+      initialValue: true
+    });
+
+    if (!p.isCancel(shouldRemoveWorktrees) && shouldRemoveWorktrees) {
+      for (const entry of fs.readdirSync(config.worktreeBase)) {
+        const dir = path.join(config.worktreeBase, entry);
+        try {
+          run('git', ['-C', config.repoRoot, 'worktree', 'remove', dir, '--force']);
+        } catch {
+          fs.rmSync(dir, { recursive: true, force: true });
+        }
+      }
+      runSafe('git', ['-C', config.repoRoot, 'worktree', 'prune']);
+    }
+  }
+
+  for (const dir of projectToolDirs(config, tools)) {
+    if (fs.existsSync(dir)) {
+      fs.rmSync(dir, { recursive: true, force: true });
+      p.log.success(`Removed tool state: ${dir}`);
+    }
+  }
+
+  const shouldRemoveImage = await p.confirm({
+    message: `Remove image ${config.imageName}?`,
+    initialValue: false
+  });
+  if (!p.isCancel(shouldRemoveImage) && shouldRemoveImage) {
+    runSafe('docker', ['rmi', config.imageName]);
+  }
+
+  if (isVmManaged()) {
+    const shouldStopVm = await p.confirm({
+      message: 'Stop Colima VM?',
+      initialValue: false
+    });
+    if (!p.isCancel(shouldStopVm) && shouldStopVm) {
+      runSafe('colima', ['stop']);
+    }
+  }
+
+  p.outro(pc.green('All project sandboxes removed'));
+}
+
+export async function rm(args) {
+  const { values, positionals } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      all: { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' }
+    }
+  });
+
+  if (values.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  if (!values.all && positionals.length !== 1) {
+    throw new Error(USAGE);
+  }
+
+  const config = loadConfig();
+  const tools = resolveTools(config);
+
+  if (values.all) {
+    await rmAll(config, tools);
+    return;
+  }
+
+  const branch = resolveTaskBranch(positionals[0], config.repoRoot);
+  await rmOne(config, tools, branch);
+}

package/lib/sandbox/commands/vm.js

@@ -0,0 +1,101 @@
+import { parseArgs } from 'node:util';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { loadConfig } from '../config.js';
+import { parsePositiveIntegerOption } from '../constants.js';
+import { detectEngine, ensureDocker, isVmManaged } from '../engine.js';
+import { run, runOk, runSafe } from '../shell.js';
+
+const USAGE = `Usage: ai sandbox vm <status|start|stop> [--cpu <n>] [--memory <n>]`;
+
+function ensureManagedVm() {
+  if (!isVmManaged()) {
+    throw new Error(`VM management is unavailable on ${detectEngine()}.`);
+  }
+}
+
+function status() {
+  ensureManagedVm();
+  p.intro(pc.cyan('Sandbox VM status'));
+
+  if (runOk('colima', ['status'])) {
+    process.stdout.write(`${runSafe('colima', ['status'])}\n`);
+  } else {
+    p.log.warn('Colima VM is not running');
+  }
+}
+
+async function start(args) {
+  ensureManagedVm();
+
+  const { values } = parseArgs({
+    args,
+    allowPositionals: true,
+    strict: true,
+    options: {
+      cpu: { type: 'string' },
+      memory: { type: 'string' },
+      help: { type: 'boolean', short: 'h' }
+    }
+  });
+
+  if (values.help) {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  const config = loadConfig();
+  const effectiveConfig = {
+    ...config,
+    vm: {
+      ...config.vm,
+      cpu: parsePositiveIntegerOption(values.cpu, '--cpu') ?? config.vm.cpu,
+      memory: parsePositiveIntegerOption(values.memory, '--memory') ?? config.vm.memory
+    }
+  };
+
+  p.intro(pc.cyan('Starting sandbox VM'));
+  await ensureDocker(effectiveConfig, (detail) => {
+    p.log.info(detail);
+  });
+  p.outro(pc.green('VM ready'));
+}
+
+function stop() {
+  ensureManagedVm();
+  p.intro(pc.cyan('Stopping sandbox VM'));
+
+  if (!runOk('colima', ['status'])) {
+    p.log.warn('Colima VM is not running');
+    return;
+  }
+
+  run('colima', ['stop']);
+  p.outro(pc.green('VM stopped'));
+}
+
+export async function vm(args) {
+  const [subcommand, ...rest] = args;
+
+  if (!subcommand || subcommand === '--help' || subcommand === '-h') {
+    process.stdout.write(`${USAGE}\n`);
+    if (!subcommand) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  switch (subcommand) {
+    case 'status':
+      status();
+      break;
+    case 'start':
+      await start(rest);
+      break;
+    case 'stop':
+      stop();
+      break;
+    default:
+      throw new Error(USAGE);
+  }
+}

package/lib/sandbox/config.js

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const DEFAULTS = Object.freeze({
+  runtimes: ['node20'],
+  tools: ['claude-code', 'codex', 'opencode', 'gemini-cli'],
+  dockerfile: null,
+  vm: {
+    cpu: null,
+    memory: null,
+    disk: null
+  }
+});
+
+function detectRepoRoot() {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    throw new Error('sandbox: current directory is not inside a git repository');
+  }
+}
+
+function cloneDefaults() {
+  return {
+    runtimes: [...DEFAULTS.runtimes],
+    tools: [...DEFAULTS.tools],
+    dockerfile: DEFAULTS.dockerfile,
+    vm: { ...DEFAULTS.vm }
+  };
+}
+
+export function loadConfig() {
+  const repoRoot = detectRepoRoot();
+  const home = process.env.HOME;
+
+  if (!home) {
+    throw new Error('sandbox: HOME environment variable is required');
+  }
+
+  const configPath = path.join(repoRoot, '.agents', '.airc.json');
+  if (!fs.existsSync(configPath)) {
+    throw new Error('No .agents/.airc.json found. Run "ai init" first.');
+  }
+
+  const airc = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+  const defaults = cloneDefaults();
+  const sandbox = airc.sandbox ?? {};
+  const project = airc.project;
+
+  if (!project || typeof project !== 'string') {
+    throw new Error('sandbox: .agents/.airc.json is missing a valid "project" field');
+  }
+
+  return {
+    repoRoot,
+    configPath,
+    project,
+    org: airc.org ?? '',
+    home,
+    containerPrefix: `${project}-dev`,
+    imageName: `${project}-sandbox:latest`,
+    worktreeBase: path.join(home, '.agent-infra', 'worktrees', project),
+    runtimes: Array.isArray(sandbox.runtimes) && sandbox.runtimes.length > 0
+      ? [...sandbox.runtimes]
+      : defaults.runtimes,
+    tools: Array.isArray(sandbox.tools) && sandbox.tools.length > 0
+      ? [...sandbox.tools]
+      : defaults.tools,
+    dockerfile: sandbox.dockerfile ?? defaults.dockerfile,
+    vm: {
+      ...defaults.vm,
+      ...(sandbox.vm ?? {})
+    }
+  };
+}