@desplega.ai/agent-env 0.0.0-stage → 0.3.0

package/src/snapshots.mjs

@@ -0,0 +1,394 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { mkdir, mkdtemp, readFile, writeFile, rm, stat, open } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve, posix } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { pipeline } from 'node:stream/promises';
+import { run } from './system.mjs';
+
+const FORMAT = 'agent-env-snapshot';
+const VERSION = 1;
+const IMAGE = 'busybox:1.37';
+const VOLUME_NAME = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
+
+function locationInfo(location) {
+  if (typeof location !== 'string' || !location) throw new Error('Specify a snapshot directory or an S3 URL.');
+  if (!location.startsWith('s3://')) return { directory: resolve(location) };
+  const match = /^s3:\/\/([^/]+)\/(.+?)\/*$/.exec(location);
+  if (!match || /[\r\n?#]/.test(location) || match[2].split('/').some(part => part === '..' || part === '.')) throw new Error('Use s3://bucket/nonempty-prefix without query parameters.');
+  return { bucket: match[1], prefix: `${match[2]}/` };
+}
+
+function aws(options, args) {
+  return run(options.awsCommand ?? 'aws', [
+    ...(options.endpointUrl ? ['--endpoint-url', options.endpointUrl] : []),
+    '--no-cli-pager', 's3api', ...args,
+  ], { env: { ...process.env, ...options.awsEnv, AWS_PAGER: '' } });
+}
+
+async function matchingContainers(provider, spec, filter) {
+  const ids = (await provider.docker(spec, ['container', 'ls', '-aq', '--filter', filter])).split(/\s+/).filter(Boolean);
+  if (!ids.length) return [];
+  try { return JSON.parse(await provider.docker(spec, ['inspect', ...ids])); }
+  catch {
+    const containers = [];
+    for (const id of ids) {
+      try { containers.push(...JSON.parse(await provider.docker(spec, ['inspect', id]))); }
+      catch (error) {
+        // An unrelated temporary container can disappear between listing and inspection.
+        const remaining = await provider.docker(spec, ['container', 'ls', '-aq', '--filter', `id=${id}`]);
+        if (remaining.trim()) throw error;
+      }
+    }
+    return containers;
+  }
+}
+
+function serviceContainers(service) {
+  return service.containers ?? (service.container ? [service.container] : []);
+}
+
+function checkStopped(info) {
+  if (info.State?.Running || info.State?.Restarting || info.State?.Paused) throw new Error(`Stop service container ${info.Name ?? info.Id} before snapshot or restore.`);
+  if (!['exited', 'created', 'dead'].includes(info.State?.Status)) throw new Error('The service state is unknown. Check the Docker host before snapshot or restore.');
+}
+
+async function discover(handle, provider, options) {
+  const entries = Object.entries(handle.services ?? {});
+  if (!entries.length) throw new Error('The handle must identify its service containers.');
+  const containers = [];
+  for (const [service, value] of entries) {
+    const ids = serviceContainers(value);
+    if (!Array.isArray(ids) || !ids.length || ids.some(id => typeof id !== 'string' || !id)) throw new Error(`Service ${service} must identify its container or containers.`);
+    for (const info of JSON.parse(await provider.docker(handle.spec, ['inspect', ...ids]))) {
+      checkStopped(info);
+      containers.push({ service, info });
+    }
+  }
+  const ownIds = new Set(containers.map(({ info }) => info.Id));
+  const volumeUsers = new Map();
+  const volumes = new Map(), omittedMounts = [];
+  for (const { service, info } of containers) {
+    for (const mount of info.Mounts ?? []) {
+      const omit = reason => {
+        omittedMounts.push({ service, target: mount.Destination, type: mount.Type, reason });
+      };
+      if (mount.Type === 'bind' && (mount.Source === (handle.workspace ?? handle.spec.cwd) || mount.Source?.startsWith(`${handle.workspace ?? handle.spec.cwd}/`))) {
+        omit('Source files require a separate Git worktree or source synchronization.');
+        continue;
+      }
+      let reason;
+      if (mount.Type !== 'volume' || !mount.Name) reason = 'This mount is not a managed named volume.';
+      else {
+        const volume = JSON.parse(await provider.docker(handle.spec, ['volume', 'inspect', mount.Name]))[0];
+        const labels = volume.Labels ?? {};
+        const project = info.Config?.Labels?.['com.docker.compose.project'];
+        const managed = labels['agent-env.owner'] && labels['agent-env.owner'] === handle.spec.owner
+          || project && labels['com.docker.compose.project'] === project;
+        if (!managed) reason = 'This volume is external or has no matching ownership label.';
+        else if (volume.Driver !== 'local' || Object.keys(volume.Options ?? {}).length || volume.Scope !== 'local') reason = 'This volume uses an external driver or mount options.';
+        else {
+          if (!volumeUsers.has(mount.Name)) volumeUsers.set(mount.Name, await matchingContainers(provider, handle.spec, `volume=${mount.Name}`));
+          if (volumeUsers.get(mount.Name).some(other => !ownIds.has(other.Id) && (other.Mounts ?? []).some(item => item.Type === 'volume' && item.Name === mount.Name))) reason = 'Another container shares this volume.';
+        }
+      }
+      if (!reason && provider.snapshotVolumeNames) {
+        try { await provider.snapshotVolumeNames(handle.spec, { volumes: [{ id: 'check', mounts: [{ service, target: mount.Destination }] }] }); }
+        catch (error) { reason = error.message; }
+      }
+      if (reason) {
+        if (!options.omitUnsupportedMounts) throw new Error(`${service}:${mount.Destination}: ${reason} Create a separate backup for this mount or select omitUnsupportedMounts.`);
+        omit(reason);
+        continue;
+      }
+      let volume = volumes.get(mount.Name);
+      if (!volume) {
+        volume = { id: `v${volumes.size}`, sourceName: mount.Name, archive: `v${volumes.size}.tar`, mounts: [] };
+        volumes.set(mount.Name, volume);
+      }
+      const key = Object.entries(handle.spec.services?.[service]?.volumes ?? {}).find(([, target]) => target === mount.Destination)?.[0];
+      volume.mounts.push({ service, target: mount.Destination, ...(key ? { key } : {}) });
+    }
+  }
+  return { volumes: [...volumes.values()], omittedMounts };
+}
+
+async function streamDocker(provider, spec, args, { input, output }) {
+  const file = input ? await open(input, 'r') : await open(output, 'wx', 0o600);
+  try {
+    // Redirect bytes through OS file descriptors. The provider only captures text on stderr.
+    await provider.docker(spec, args, { stdio: [input ? file.fd : 'ignore', output ? file.fd : 'ignore', 'pipe'] });
+  } finally { await file.close(); }
+}
+
+async function archiveVolume(provider, spec, volume, archive, options, restore = false) {
+  const token = randomUUID();
+  const name = `agent-env-snapshot-${token}`;
+  const args = ['run', '--rm', ...(restore ? ['-i'] : []), '--name', name, '--label', `agent-env.snapshot=${token}`, '--network', 'none', '--read-only', '--mount', `type=volume,src=${volume},dst=/data,volume-nocopy${restore ? '' : ',readonly'}`, options.image ?? IMAGE, 'tar', '-C', '/data', restore ? '-xf' : '-cf', '-', ...(restore ? [] : ['.'])];
+  try { await streamDocker(provider, spec, args, restore ? { input: archive } : { output: archive }); }
+  finally {
+    // A failed transport can leave a helper on the remote Docker host.
+    const info = await provider.docker(spec, ['inspect', name]).then(value => JSON.parse(value)[0], () => null);
+    if (info?.Config?.Labels?.['agent-env.snapshot'] === token) await provider.docker(spec, ['rm', '-f', name]);
+  }
+}
+
+function tarString(buffer) { return buffer.subarray(0, buffer.indexOf(0) < 0 ? buffer.length : buffer.indexOf(0)).toString('utf8'); }
+
+function archivePath(value) {
+  if (!value || value.includes('\\') || value.includes('\ufffd') || posix.isAbsolute(value) || value.split('/').includes('..')) throw new Error('The archive contains an unsafe extraction path.');
+  return posix.normalize(value).replace(/\/$/, '');
+}
+
+// Validate tar records without buffering file bodies or invoking an extractor.
+async function verifyTar(file) {
+  let pending = Buffer.alloc(0), remaining = 0, zeros = 0, ended = false;
+  let extension, longName, longLink;
+  const paths = new Map();
+  for await (const chunk of createReadStream(file)) {
+    pending = pending.length ? Buffer.concat([pending, chunk]) : chunk;
+    while (pending.length) {
+      if (remaining) {
+        const consumed = Math.min(remaining, pending.length);
+        if (extension && extension.read < extension.size) {
+          const size = Math.min(consumed, extension.size - extension.read);
+          extension.chunks.push(Buffer.from(pending.subarray(0, size)));
+          extension.read += size;
+        }
+        remaining -= consumed;
+        pending = pending.subarray(consumed);
+        if (!remaining && extension) {
+          const body = Buffer.concat(extension.chunks);
+          if (body.indexOf(0) !== body.length - 1) throw new Error('The archive contains an invalid GNU path extension.');
+          const value = tarString(body);
+          if (extension.type === 'L') longName = value;
+          else longLink = value;
+          extension = undefined;
+        }
+        continue;
+      }
+      if (pending.length < 512) break;
+      const header = pending.subarray(0, 512);
+      pending = pending.subarray(512);
+      if (header.every(byte => byte === 0)) { zeros++; ended = true; continue; }
+      if (ended) throw new Error('The archive contains data after its end marker.');
+      let sum = 0;
+      for (let i = 0; i < 512; i++) sum += i >= 148 && i < 156 ? 32 : header[i];
+      const checksum = tarString(header.subarray(148, 156)).trim();
+      const sizeField = tarString(header.subarray(124, 136)).trim();
+      if (!/^[0-7]+$/.test(checksum) || parseInt(checksum, 8) !== sum || !/^[0-7]+$/.test(sizeField)) throw new Error('The archive contains an invalid tar header.');
+      const size = parseInt(sizeField, 8);
+      if (!Number.isSafeInteger(size)) throw new Error('The archive file size is not supported.');
+      const magic = header.subarray(257, 265).toString('latin1');
+      const gnu = magic === 'ustar  \0';
+      if (magic !== `ustar${String.fromCharCode(0)}00` && !gnu) throw new Error('The archive tar format is not supported.');
+      if (gnu && header.subarray(345, 500).some(byte => byte !== 0)) throw new Error('The archive contains unsupported GNU metadata.');
+      const type = String.fromCharCode(header[156] || 48);
+      if (['L', 'K'].includes(type)) {
+        if (size < 1 || size > 1024 * 1024 || type === 'L' && longName !== undefined || type === 'K' && longLink !== undefined) throw new Error('The archive contains an invalid GNU path extension.');
+        extension = { type, size, read: 0, chunks: [] };
+        remaining = Math.ceil(size / 512) * 512;
+        continue;
+      }
+      if (!['0', '1', '2', '5'].includes(type)) throw new Error('The archive contains an unsupported entry. Only files, directories, and internal links are supported.');
+      if (type !== '0' && size !== 0) throw new Error('The archive contains an invalid directory or link size.');
+      const prefix = gnu ? '' : tarString(header.subarray(345, 500));
+      const rawName = tarString(header.subarray(0, 100));
+      archivePath(rawName);
+      if (prefix) archivePath(prefix);
+      const path = archivePath(longName ?? `${prefix ? `${prefix}/` : ''}${rawName}`);
+      const target = longLink ?? tarString(header.subarray(157, 257));
+      longName = undefined; longLink = undefined;
+      if (path === '.' && type !== '5') throw new Error('The archive root must be a directory.');
+      if (paths.has(path)) throw new Error('The archive contains duplicate extraction paths.');
+      if (type === '1') {
+        const linked = paths.get(archivePath(target));
+        if (!linked || !['0', '1'].includes(linked.type)) throw new Error('The archive hard link does not reference an earlier regular file.');
+      }
+      if (type === '2') {
+        if (!target || posix.isAbsolute(target) || target.includes('\\') || target.includes('\ufffd')) throw new Error('The archive contains an unsafe symbolic link.');
+      }
+      paths.set(path, { type, target });
+      remaining = Math.ceil(size / 512) * 512;
+    }
+  }
+  if (remaining || pending.length || zeros < 2 || longName !== undefined || longLink !== undefined) throw new Error('The archive is truncated.');
+  const resolveLink = (target, base, visited) => {
+    const stack = [...base];
+    for (const part of target.split('/')) {
+      if (part === '.' || part === '') continue;
+      if (part === '..') {
+        if (!stack.length) throw new Error('The symbolic link leaves the volume.');
+        stack.pop();
+        continue;
+      }
+      stack.push(part);
+      const path = stack.join('/'), entry = paths.get(path);
+      if (entry?.type === '2') {
+        if (visited.has(path) || visited.size > 64) throw new Error('The archive contains a symbolic link cycle or an excessive link chain.');
+        const resolved = resolveLink(entry.target, stack.slice(0, -1), new Set([...visited, path]));
+        stack.splice(0, stack.length, ...resolved);
+      }
+    }
+    return stack;
+  };
+  for (const [path, entry] of paths) {
+    if (entry.type === '2') resolveLink(entry.target, posix.dirname(path).split('/').filter(part => part !== '.'), new Set([path]));
+    let ancestor = posix.dirname(path);
+    while (ancestor !== '.') {
+      if (paths.has(ancestor) && paths.get(ancestor).type !== '5') throw new Error('An archive path traverses a symbolic link or file.');
+      ancestor = posix.dirname(ancestor);
+    }
+  }
+}
+
+async function digest(file) {
+  const hash = createHash('sha256');
+  let bytes = 0;
+  for await (const chunk of createReadStream(file)) { hash.update(chunk); bytes += chunk.length; }
+  return { sha256: hash.digest('hex'), bytes };
+}
+
+function validateManifest(manifest) {
+  if (manifest.format !== FORMAT || manifest.version !== VERSION || !Array.isArray(manifest.volumes) || !Array.isArray(manifest.omittedMounts)) throw new Error('The snapshot manifest format or version is not supported.');
+  const ids = new Set(), archives = new Set(), sources = new Set();
+  for (const volume of manifest.volumes) {
+    if (!/^v\d+$/.test(volume.id) || volume.archive !== `${volume.id}.tar` || !VOLUME_NAME.test(volume.sourceName)
+      || ids.has(volume.id) || archives.has(volume.archive) || sources.has(volume.sourceName)
+      || !Number.isSafeInteger(volume.bytes) || volume.bytes < 1024 || !/^[a-f0-9]{64}$/.test(volume.sha256)
+      || !Array.isArray(volume.mounts) || !volume.mounts.length
+      || volume.mounts.some(mount => typeof mount.service !== 'string' || typeof mount.target !== 'string' || !mount.target.startsWith('/'))) throw new Error('The snapshot contains an invalid volume record.');
+    ids.add(volume.id); archives.add(volume.archive); sources.add(volume.sourceName);
+  }
+  return manifest;
+}
+
+/** Export stopped, managed Docker volumes to a new local directory or S3 prefix. */
+export async function snapshotInstance(handle, location, provider, options = {}) {
+  const storage = locationInfo(location);
+  const discovered = await discover(handle, provider, options);
+  let directory, owned = false;
+  try {
+    if (storage.bucket) {
+      const existing = JSON.parse(await aws(options, ['list-objects-v2', '--bucket', storage.bucket, '--prefix', storage.prefix, '--max-keys', '1', '--output', 'json']));
+      if (existing.Contents?.length) throw new Error('The S3 snapshot prefix already contains data. Choose a new prefix.');
+      directory = await mkdtemp(join(tmpdir(), 'agent-env-snapshot-'));
+    } else {
+      directory = storage.directory;
+      await mkdir(directory, { mode: 0o700 });
+    }
+    owned = true;
+    const manifest = {
+      format: FORMAT, version: VERSION, createdAt: new Date().toISOString(),
+      source: { name: handle.spec.name, owner: handle.spec.owner, provider: handle.spec.provider },
+      volumes: discovered.volumes, omittedMounts: discovered.omittedMounts,
+    };
+    for (const volume of manifest.volumes) {
+      const file = join(directory, volume.archive);
+      await archiveVolume(provider, handle.spec, volume.sourceName, file, options);
+      await verifyTar(file);
+      Object.assign(volume, await digest(file));
+    }
+    // Reject a snapshot if a service restarted during export.
+    await discover(handle, provider, options);
+    await writeFile(join(directory, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx', mode: 0o600 });
+    if (storage.bucket) {
+      // Conditional writes prevent races from overwriting another writer's objects.
+      for (const name of [...manifest.volumes.map(volume => volume.archive), 'manifest.json']) {
+        await aws(options, ['put-object', '--bucket', storage.bucket, '--key', `${storage.prefix}${name}`, '--body', join(directory, name), '--if-none-match', '*']);
+      }
+    }
+    return { location, manifest };
+  } catch (error) {
+    if (owned && !storage.bucket) await rm(directory, { recursive: true, force: true });
+    throw error;
+  } finally {
+    if (owned && storage.bucket) await rm(directory, { recursive: true, force: true });
+  }
+}
+
+async function destinationVolumes(spec, manifest, provider, options) {
+  const names = new Set();
+  const mapped = options.volumeNames ?? await provider.snapshotVolumeNames?.(spec, manifest);
+  return manifest.volumes.map(volume => {
+    let name = mapped?.[volume.id];
+    if (!name) {
+      const destinations = volume.mounts.map(mount => {
+        const key = Object.entries(spec.services?.[mount.service]?.volumes ?? {}).find(([, target]) => target === mount.target)?.[0];
+        return key && typeof provider.volume === 'function' ? provider.volume(spec, mount.service, key) : undefined;
+      });
+      if (destinations.some(item => !item) || new Set(destinations).size !== 1) throw new Error(`Set volumeNames.${volume.id} to the destination volume name. Match all mounts of this volume.`);
+      name = destinations[0];
+    }
+    if (!VOLUME_NAME.test(name) || names.has(name)) throw new Error('Destination volumes must have distinct valid Docker volume names.');
+    names.add(name);
+    return { ...volume, destinationName: name };
+  });
+}
+
+/** Restore verified archives into new volumes. This function never starts services. */
+export async function restoreSnapshot(spec, location, provider, options = {}) {
+  const storage = locationInfo(location);
+  const directory = await mkdtemp(join(tmpdir(), 'agent-env-restore-'));
+  const created = [], token = randomUUID();
+  try {
+    const fetch = async name => {
+      const file = join(directory, name);
+      if (storage.bucket) await aws(options, ['get-object', '--bucket', storage.bucket, '--key', `${storage.prefix}${name}`, file]);
+      else await pipeline(createReadStream(join(storage.directory, name)), createWriteStream(file, { flags: 'wx', mode: 0o600 }));
+      return file;
+    };
+    const manifestFile = await fetch('manifest.json');
+    if ((await stat(manifestFile)).size > 4 * 1024 * 1024) throw new Error('The snapshot manifest exceeds 4 MiB.');
+    const manifest = validateManifest(JSON.parse(await readFile(manifestFile, 'utf8')));
+    // Verify every archive before allocating any destination resource.
+    for (const volume of manifest.volumes) {
+      const file = await fetch(volume.archive);
+      const actual = await digest(file);
+      if (actual.sha256 !== volume.sha256 || actual.bytes !== volume.bytes) throw new Error(`Checksum or size mismatch for ${volume.archive}.`);
+      await verifyTar(file);
+    }
+    if (options.destinationHandle) await discover(options.destinationHandle, provider, { omitUnsupportedMounts: true });
+    const volumes = await destinationVolumes(spec, manifest, provider, options);
+    const prefix = typeof provider.prefix === 'function' ? provider.prefix(spec) : undefined;
+    const containers = [
+      ...(prefix ? await matchingContainers(provider, spec, `name=${prefix}`) : []),
+      ...(options.composeProject ? await matchingContainers(provider, spec, `label=com.docker.compose.project=${options.composeProject}`) : []),
+    ];
+    for (const info of containers) {
+      if (prefix && (info.Name === `/${prefix}` || info.Name?.startsWith(`/${prefix}-`))
+        || options.composeProject && info.Config?.Labels?.['com.docker.compose.project'] === options.composeProject) checkStopped(info);
+    }
+    const existing = new Set((await provider.docker(spec, ['volume', 'ls', '-q'])).split(/\s+/).filter(Boolean));
+    for (const volume of volumes) if (existing.has(volume.destinationName)) throw new Error(`Volume ${volume.destinationName} already exists. Restore requires new destination volumes.`);
+    for (const volume of volumes) {
+      // Docker volume create is idempotent. A unique claim label detects a concurrent creator.
+      created.push(volume.destinationName);
+      const labels = provider.snapshotVolumeLabels?.(spec, volume.destinationName) ?? {};
+      await provider.docker(spec, ['volume', 'create', '--label', `agent-env.owner=${spec.owner}`, '--label', `agent-env.restore=${token}`,
+        ...Object.entries(labels).flatMap(([key, value]) => ['--label', `${key}=${value}`]), volume.destinationName]);
+      const info = JSON.parse(await provider.docker(spec, ['volume', 'inspect', volume.destinationName]))[0];
+      if (info.Labels?.['agent-env.restore'] !== token) throw new Error('Another operation created the destination volume. Restore stopped without modifying it.');
+      await archiveVolume(provider, spec, volume.destinationName, join(directory, volume.archive), options, true);
+    }
+    return { location, manifest, volumes, restoreId: token, volumeNames: Object.fromEntries(volumes.map(volume => [volume.id, volume.destinationName])) };
+  } catch (error) {
+    const cleanupErrors = [];
+    for (const name of created.reverse()) {
+      try {
+        const info = JSON.parse(await provider.docker(spec, ['volume', 'inspect', name]))[0];
+        if (info.Labels?.['agent-env.restore'] === token) await provider.docker(spec, ['volume', 'rm', name]);
+      } catch (cleanupError) { cleanupErrors.push(cleanupError); }
+    }
+    if (cleanupErrors.length) error.cleanupErrors = cleanupErrors;
+    throw error;
+  } finally { await rm(directory, { recursive: true, force: true }); }
+}
+
+export async function disposeRestoredVolumes(result, spec, provider) {
+  for (const volume of result.volumes) {
+    const info = JSON.parse(await provider.docker(spec, ['volume', 'inspect', volume.destinationName]))[0];
+    if (info.Labels?.['agent-env.restore'] !== result.restoreId) throw new Error('The restored volume ownership changed. Cleanup stopped.');
+    await provider.docker(spec, ['volume', 'rm', volume.destinationName]);
+  }
+}

package/src/source-paths.mjs

@@ -0,0 +1,15 @@
+// Unanchored rules apply at every depth. Leading slashes anchor rules to the checkout root.
+export const sourceExclusions = Object.freeze(['.git', 'node_modules', '.agent-env', '.env', '.env.*', '/.next', '/dist', '/build', '/coverage', '/.cache']);
+export const worktreeExclusions = Object.freeze(['/vendor', '/target', '/.nuxt', '/.turbo', '/.venv', '/venv', '/__pycache__']);
+
+export function shouldSync(file, exclusions = []) {
+  if (!file) return true;
+  const path = String(file).replaceAll('\\', '/').replace(/^\.\//, '');
+  const parts = path.split('/');
+  const excluded = [...sourceExclusions, ...exclusions].some(rule => {
+    if (rule.startsWith('/')) return path === rule.slice(1) || path.startsWith(`${rule.slice(1)}/`);
+    if (rule.endsWith('*')) return parts.some(part => part.startsWith(rule.slice(0, -1)));
+    return parts.includes(rule) || path.startsWith(`${rule}/`);
+  });
+  return !excluded;
+}

package/src/system.mjs

@@ -0,0 +1,39 @@
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+import { once } from 'node:events';
+import { setTimeout as delay } from 'node:timers/promises';
+
+export { delay };
+export const quote = value => `'${String(value).replaceAll("'", "'\\''")}'`;
+export function run(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'], ...options });
+    let stdout = '', stderr = '';
+    child.stdout?.on('data', data => { stdout += data; });
+    child.stderr?.on('data', data => { stderr += data; if (options.combined) stdout += data; });
+    child.on('error', reject);
+    child.on('close', code => {
+      if (code === 0) return resolve(stdout.trimEnd());
+      const output = options.errorStdout === false ? stderr.trimEnd()
+        : options.combined ? stdout.trimEnd() : [stdout.trimEnd(), stderr.trimEnd()].filter(Boolean).join('\n');
+      reject(Object.assign(new Error(`${command} failed (${code}): ${output}`), { exitCode: code ?? 1 }));
+    });
+  });
+}
+export async function freePort() {
+  const server = net.createServer();
+  server.listen(0, '127.0.0.1');
+  await once(server, 'listening');
+  const port = server.address().port;
+  await new Promise(resolve => server.close(resolve));
+  return port;
+}
+export async function reachable(port) {
+  return new Promise(resolve => {
+    const socket = net.connect(port, '127.0.0.1');
+    const finish = value => { socket.destroy(); resolve(value); };
+    socket.setTimeout(500, () => finish(false));
+    socket.on('connect', () => finish(true));
+    socket.on('error', () => finish(false));
+  });
+}

package/src/tls.mjs

@@ -0,0 +1,57 @@
+import { mkdir, readFile, writeFile, chmod, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+import { run } from './system.mjs';
+import { home } from './paths.mjs';
+import { createPrivateKey, createPublicKey, X509Certificate } from 'node:crypto';
+import { withFileLock } from './locks.mjs';
+
+export async function ensureTls(directory = join(home, 'tls'), hosts = []) {
+  if (hosts.some(host => !/^[a-z0-9][a-z0-9-]{0,62}\.localhost$/.test(host))) throw new Error('TLS names must be valid localhost hostnames.');
+  hosts = [...new Set(hosts)].sort();
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  await chmod(directory, 0o700);
+  return withFileLock(join(directory, 'generation.lock'), () => generateTls(directory, hosts), { waitMs: 15000 });
+}
+async function generateTls(directory, hosts) {
+  const ca = join(directory, 'ca.pem'), caKey = join(directory, 'ca.key');
+  const cert = join(directory, 'server.pem'), key = join(directory, 'server.key');
+  const exists = path => readFile(path).then(() => true, error => { if (error.code === 'ENOENT') return false; throw error; });
+  if (await exists(ca) !== await exists(caKey)) throw new Error('The local CA is incomplete. Restore its certificate and key before enabling HTTPS.');
+  const config = join(directory, 'openssl.cnf');
+  await writeFile(config, `[req]\ndistinguished_name=dn\nx509_extensions=ca\nprompt=no\n[dn]\nCN=agent-env local development\n[ca]\nbasicConstraints=critical,CA:TRUE\nkeyUsage=critical,keyCertSign,cRLSign\nnameConstraints=critical,permitted;DNS:localhost,permitted;DNS:.localhost,permitted;IP:127.0.0.1/255.255.255.255,permitted;IP:::1/ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff\n[server]\nbasicConstraints=critical,CA:FALSE\nkeyUsage=critical,digitalSignature\nextendedKeyUsage=serverAuth\nsubjectAltName=DNS:localhost,DNS:*.localhost,IP:127.0.0.1,IP:::1${hosts.map(host => `,DNS:${host}`).join('')}\n`, { mode: 0o600 });
+  try {
+    if (!await exists(ca)) {
+      await run('openssl', ['ecparam', '-genkey', '-name', 'prime256v1', '-noout', '-out', caKey]);
+      await chmod(caKey, 0o600);
+      await run('openssl', ['req', '-new', '-x509', '-sha256', '-key', caKey, '-out', ca, '-days', '3650', '-config', config]);
+    }
+    const authority = new X509Certificate(await readFile(ca));
+    const publicKey = createPublicKey(createPrivateKey(await readFile(caKey))).export({ type: 'spki', format: 'der' });
+    if (!authority.publicKey.export({ type: 'spki', format: 'der' }).equals(publicKey)) throw new Error('The local CA certificate and key do not match. Restore the matching pair before enabling HTTPS.');
+    await run('openssl', ['x509', '-checkend', '86400', '-noout', '-in', ca]).catch(() => { throw new Error('The local CA is expired. Replace it and repeat agent-env trust.'); });
+    const oldNames = await readFile(join(directory, 'names.json'), 'utf8').catch(() => '');
+    const valid = oldNames === JSON.stringify(hosts) && await exists(key) && await exists(cert) && await run('openssl', ['x509', '-checkend', '86400', '-noout', '-in', cert]).then(() => true, () => false);
+    if (!valid) {
+      await run('openssl', ['ecparam', '-genkey', '-name', 'prime256v1', '-noout', '-out', key]);
+      await chmod(key, 0o600);
+      const csr = join(directory, 'server.csr');
+      try {
+        await run('openssl', ['req', '-new', '-key', key, '-out', csr, '-subj', '/CN=localhost']);
+        await run('openssl', ['x509', '-req', '-sha256', '-in', csr, '-CA', ca, '-CAkey', caKey, '-CAcreateserial', '-out', cert, '-days', '365', '-extfile', config, '-extensions', 'server']);
+      } finally { await rm(csr, { force: true }); }
+    }
+    await writeFile(join(directory, 'names.json'), JSON.stringify(hosts), { mode: 0o600 });
+    return { key: await readFile(key), cert: await readFile(cert), caPath: ca };
+  } finally { await rm(config, { force: true }); }
+}
+export async function trustTls() {
+  const { caPath } = await ensureTls();
+  if (platform() === 'darwin') {
+    await run('security', ['add-trusted-cert', '-r', 'trustRoot', '-k', join(homedir(), 'Library/Keychains/login.keychain-db'), caPath]);
+  } else if (platform() === 'linux') {
+    await run('sudo', ['-n', 'install', '-m', '0644', caPath, '/usr/local/share/ca-certificates/agent-env.crt']);
+    await run('sudo', ['-n', 'update-ca-certificates']);
+  } else throw new Error(`Install ${caPath} in your user trust store. Automatic trust supports macOS and Debian-based Linux.`);
+  return { message: `Trusted the agent-env local CA: ${caPath}` };
+}

package/src/ui-client.js

@@ -0,0 +1,51 @@
+const $ = id => document.getElementById(id);
+const element = (tag, text, className) => { const node = document.createElement(tag); if (text !== undefined) node.textContent = text; if (className) node.className = className; return node; };
+let loading = false;
+async function refresh() {
+  if (loading || $('logs').open) return;
+  loading = true;
+  try {
+    const response = await fetch('/api/status');
+    if (!response.ok) throw new Error('Status is unavailable. Retry shortly.');
+    const data = await response.json();
+    $('notice').textContent = data.error ?? '';
+    $('empty').hidden = data.instances.length !== 0;
+    $('instances').replaceChildren();
+    for (const item of data.instances) {
+      const section = element('section');
+      const top = element('div', undefined, 'top');
+      const title = element('div'); title.append(element('h2', item.name), element('div', `${item.provider} · ${item.host}${item.environment ? ` · ${item.environment}` : ''}`, 'sub'));
+      const state = !item.running ? 'Stopped' : item.connected ? 'Connected' : 'Reconnecting';
+      top.append(title, element('span', state, `badge${item.connected ? '' : ' off'}`));
+      section.append(top);
+      const services = element('div', undefined, 'services');
+      for (const [name, service] of Object.entries(item.services)) {
+        const row = element('div', undefined, 'service'); row.append(element('strong', name));
+        const url = service.httpsUrl ?? service.url;
+        if (url?.startsWith('http')) { const link = element('a', url); link.href = url; link.target = '_blank'; link.rel = 'noopener noreferrer'; row.append(link); }
+        else row.append(element('span', url ?? 'Internal service', 'address sub'));
+        const actions = element('div', undefined, 'actions');
+        actions.append(element('span', item.status?.[name] ?? '', 'sub'));
+        const button = element('button', 'Logs'); button.setAttribute('aria-label', `Read ${item.name} ${name} logs`);
+        button.onclick = async () => {
+          $('log-title').textContent = `${item.name} / ${name}`; $('log-body').textContent = 'Loading logs...'; $('logs').showModal();
+          try { const response = await fetch(`/api/logs?name=${encodeURIComponent(item.name)}&service=${encodeURIComponent(name)}`); const data = await response.json(); $('log-body').textContent = data.output ?? data.error ?? 'No logs yet.'; }
+          catch { $('log-body').textContent = 'Could not read logs.'; }
+        };
+        actions.append(button); row.append(actions); services.append(row);
+      }
+      section.append(services);
+      if (item.error) section.append(element('p', item.error, 'hint error'));
+      else if (item.sync) section.append(element('p', `Sync: ${item.sync}`, 'hint'));
+      $('instances').append(section);
+    }
+    $('updated').textContent = `Local access only · Updated ${new Intl.DateTimeFormat('en-GB', { timeZone: 'Europe/Madrid', hour: '2-digit', minute: '2-digit', second: '2-digit' }).format(new Date())} BCN`;
+  } catch (error) { $('notice').textContent = error.message; }
+  finally { loading = false; }
+}
+$('refresh').onclick = refresh;
+$('close').onclick = () => $('logs').close();
+$('auto').checked = localStorage.getItem('agent-env-auto-refresh') === 'true';
+$('auto').onchange = () => localStorage.setItem('agent-env-auto-refresh', String($('auto').checked));
+setInterval(() => { if ($('auto').checked && !document.hidden) refresh(); }, 5000);
+refresh();

package/src/ui.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>agent-env</title>
+<link rel="icon" href="/icon.svg" type="image/svg+xml">
+<style>
+:root{color-scheme:light;--ink:#20241f;--muted:#62695e;--line:#d9ded3;--paper:#f6f7f2;--green:#256941}*{box-sizing:border-box}body{margin:0;background:var(--paper);color:var(--ink);font:15px/1.5 ui-sans-serif,system-ui,sans-serif}main{max-width:1040px;margin:0 auto;padding:48px 24px}header{display:flex;align-items:center;justify-content:space-between;gap:20px;margin-bottom:40px}h1{font-size:26px;letter-spacing:-1px;margin:0}h2{font-size:18px;margin:0}.sub{color:var(--muted);font-size:13px}button,select,a{font:inherit}button,select{padding:7px 12px;border:1px solid var(--line);border-radius:7px;background:white;color:var(--ink)}button{cursor:pointer}button:hover{border-color:var(--green)}button:focus-visible,a:focus-visible{outline:3px solid #90b899;outline-offset:3px}section{border:1px solid var(--line);border-radius:12px;background:#fff;margin-bottom:18px;overflow:hidden}.top{display:flex;align-items:flex-start;justify-content:space-between;gap:16px;padding:20px 22px}.top>div{min-width:0;overflow-wrap:anywhere}.service>strong{min-width:0;overflow-wrap:anywhere}.badge{flex-shrink:0;font-size:12px;border-radius:99px;padding:3px 9px;background:#edf3e9;color:#286240}.badge.off{background:#f0f0ec;color:#5e6559}.services{border-top:1px solid var(--line)}.service{display:grid;grid-template-columns:140px 1fr auto;align-items:center;gap:12px;padding:12px 22px;border-bottom:1px solid #eef0e9}.service:last-child{border-bottom:0}.service a{color:var(--green);overflow-wrap:anywhere}.actions{display:flex;align-items:center;gap:8px}.hint{margin:0 22px 18px;color:var(--muted);font-size:12px}.error{color:#983c25;white-space:pre-wrap}#empty{padding:60px 20px;text-align:center;border:1px dashed var(--line);border-radius:12px}code{font:13px ui-monospace,monospace}dialog{width:min(850px,95vw);border:1px solid var(--line);border-radius:12px;padding:20px}dialog::backdrop{background:#20241f80}dialog header{margin-bottom:16px}pre{background:#181d18;color:#e5eae0;white-space:pre-wrap;overflow-wrap:anywhere;max-height:65vh;overflow:auto;border-radius:8px;padding:16px;font:12px/1.6 ui-monospace,monospace}footer{margin-top:30px;color:var(--muted);font-size:12px}@media(max-width:600px){main{padding:24px 14px}header{margin-bottom:24px}.top{padding:16px}.service{padding:12px 16px;grid-template-columns:1fr auto}.service a,.service .address{grid-row:2;grid-column:1/-1}.hint{margin-left:16px}.top .actions{flex-wrap:wrap;justify-content:flex-end}}
+.brand{display:flex;align-items:center;gap:12px}.brand img{flex-shrink:0}@media(max-width:600px){main>header{flex-wrap:wrap}}
+</style></head>
+<body><main><header><div class="brand"><img src="/icon.svg" width="44" height="44" alt=""><div><h1>agent-env<span style="color:var(--green)">.</span></h1><div class="sub">Your development environments</div></div></div><div class="actions"><label class="sub"><input id="auto" type="checkbox"> Auto refresh</label><button id="refresh">Refresh</button></div></header>
+<p id="notice" class="error" role="status"></p><div id="instances"></div><div id="empty" hidden><h2>Nothing running yet</h2><p class="sub">Start an environment from your terminal.</p><code>agent-env up</code></div><footer id="updated">Local access only</footer></main>
+<dialog id="logs"><header><h2 id="log-title">Logs</h2><button id="close">Close</button></header><pre id="log-body"></pre></dialog>
+<script src="/ui.js"></script></body></html>

package/src/ui.mjs

@@ -0,0 +1,32 @@
+import http from 'node:http';
+import { readFile } from 'node:fs/promises';
+import { once } from 'node:events';
+
+export async function startUi({ port = 4780, status, logs }) {
+  const [html, script, icon] = await Promise.all(['ui.html', 'ui-client.js', '../assets/icon.svg'].map(file => readFile(new URL(file, import.meta.url))));
+  const server = http.createServer(async (request, response) => {
+    const send = (code, data, type = 'application/json') => {
+      response.writeHead(code, { 'content-type': `${type}; charset=utf-8`, 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', 'content-security-policy': "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'" });
+      response.end(type === 'application/json' ? JSON.stringify(data) : data);
+    };
+    if (!['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(request.socket.remoteAddress)) return send(403, { error: 'Local access only.' });
+    const address = server.address();
+    const allowed = new Set([`127.0.0.1:${address.port}`, `localhost:${address.port}`, `[::1]:${address.port}`]);
+    if (!allowed.has(request.headers.host)) return send(403, { error: 'Use the local dashboard address.' });
+    if (request.headers.origin && ![`http://${request.headers.host}`].includes(request.headers.origin)) return send(403, { error: 'Cross-origin requests are not allowed.' });
+    if (request.headers['sec-fetch-site'] === 'cross-site') return send(403, { error: 'Cross-site requests are not allowed.' });
+    if (request.method !== 'GET') return send(405, { error: 'This dashboard is read-only.' });
+    const url = new URL(request.url, 'http://localhost');
+    try {
+      if (url.pathname === '/') return send(200, html, 'text/html');
+      if (url.pathname === '/ui.js') return send(200, script, 'text/javascript');
+      if (url.pathname === '/icon.svg') return send(200, icon, 'image/svg+xml');
+      if (url.pathname === '/api/status') return send(200, { instances: await status() });
+      if (url.pathname === '/api/logs') return send(200, { output: await logs(url.searchParams.get('name'), url.searchParams.get('service')) });
+      send(404, { error: 'Not found.' });
+    } catch (error) { send(400, { error: error.message }); }
+  });
+  server.listen(port, '127.0.0.1');
+  await once(server, 'listening');
+  return { url: `http://127.0.0.1:${server.address().port}`, close: () => new Promise(resolve => { server.closeAllConnections(); server.close(resolve); }) };
+}

package/src/watch.mjs

@@ -0,0 +1,20 @@
+import { watch, existsSync } from 'node:fs';
+import { resolve, sep, basename } from 'node:path';
+import { shouldSync } from './source-paths.mjs';
+export { shouldSync } from './source-paths.mjs';
+// The caller serializes synchronization with lifecycle changes.
+export function watchSource(cwd, { changed, error = () => {}, debounceMs = 350, exclusions = [], stateDirectory } = {}) {
+  let timer;
+  const state = stateDirectory ? resolve(stateDirectory) : null;
+  const watcher = watch(cwd, { recursive: true, persistent: false }, (_, filename) => {
+    const path = resolve(cwd, filename ?? '');
+    if (filename === basename(cwd) && !existsSync(path)) return;
+    if (state && (path === state || path.startsWith(`${state}${sep}`))) return;
+    if (!shouldSync(filename, exclusions)) return;
+    clearTimeout(timer);
+    timer = setTimeout(changed, debounceMs);
+    timer.unref();
+  });
+  watcher.on('error', error);
+  return () => { clearTimeout(timer); watcher.close(); };
+}