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

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(); };
+}

package/src/worktrees.mjs

@@ -0,0 +1,154 @@
+import { spawn } from 'node:child_process';
+import { constants, createWriteStream } from 'node:fs';
+import { mkdir, realpath, lstat, open, readFile, writeFile, rm, rmdir } from 'node:fs/promises';
+import { pipeline } from 'node:stream/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { shouldSync, worktreeExclusions } from './source-paths.mjs';
+
+async function git(cwd, args, input) {
+  return new Promise((resolveResult, reject) => {
+    const child = spawn('git', ['-C', cwd, ...args], { stdio: ['pipe', 'pipe', 'pipe'], env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } });
+    const output = [], errors = [];
+    child.stdout.on('data', chunk => output.push(chunk));
+    child.stderr.on('data', chunk => errors.push(chunk));
+    child.stdin.on('error', () => {});
+    child.on('error', reject);
+    child.on('close', code => code === 0
+      ? resolveResult(Buffer.concat(output))
+      : reject(new Error(`Git ${args[0]} failed: ${Buffer.concat(errors).toString().trim()}`)));
+    child.stdin.end(input);
+  });
+}
+
+const text = async (cwd, args) => (await git(cwd, args)).toString().trim();
+const names = buffer => buffer.toString().split('\0').filter(Boolean);
+const inside = (root, path) => { const part = relative(root, path); return part === '' || (!part.startsWith(`..${sep}`) && part !== '..' && !isAbsolute(part)); };
+
+function credential(path) {
+  return path.split('/').some(part =>
+    /^\.env(?:\..*)?$/.test(part) && !/\.(?:example|sample|template)$/.test(part)
+    || /^(?:\.ssh|\.aws|\.gnupg|\.kube|\.docker|\.netrc|\.npmrc|\.pypirc|\.git-credentials|\.envrc|(?:application_default_)?credentials(?:\.json)?|service[-_]account(?:[-_].*)?\.json|secrets?(?:\..*)?|id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?)$/i.test(part)
+    || /\.(?:pem|key|p12|pfx|keystore)$/i.test(part));
+}
+
+function excluded(path) {
+  return credential(path) || !shouldSync(path, worktreeExclusions);
+}
+
+async function absent(path) {
+  try { await lstat(path); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  throw new Error(`Destination ${path} already exists. Choose a new path.`);
+}
+
+async function copySourceFile(sourceRoot, destination, path) {
+  const source = join(sourceRoot, path), target = join(destination, path);
+  if (!inside(sourceRoot, source) || !inside(destination, target)) throw new Error('The source path leaves the repository.');
+  const info = await lstat(source);
+  if (!info.isFile()) return false;
+  if (!inside(sourceRoot, await realpath(source))) throw new Error('The source file resolves outside the repository.');
+  // Check each destination ancestor before copying through it.
+  let current = destination;
+  for (const part of relative(destination, dirname(target)).split(sep).filter(Boolean)) {
+    current = join(current, part);
+    try { await mkdir(current); } catch (error) { if (error.code !== 'EEXIST') throw error; }
+    if (!(await lstat(current)).isDirectory()) throw new Error(`Destination ancestor ${current} is not a directory.`);
+  }
+  // Exclusive creation prevents a source file from replacing a file in the selected ref.
+  const sourceHandle = await open(source, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    if (!(await sourceHandle.stat()).isFile()) throw new Error('Only regular untracked files can be copied.');
+    await pipeline(sourceHandle.createReadStream(), createWriteStream(target, { flags: 'wx', mode: info.mode & 0o777 }));
+  } finally { await sourceHandle.close(); }
+  return true;
+}
+
+async function recordPath(ownership) {
+  if (ownership?.version !== 1 || !/^[0-9a-f-]{36}$/.test(ownership.token ?? '')) throw new Error('Valid worktree ownership metadata is required.');
+  const commonDir = await realpath(ownership.commonDir);
+  return join(commonDir, 'agent-env-worktrees', `${ownership.token}.json`);
+}
+
+/** Create a Git worktree and copy the current source changes into it. */
+export async function createWorktree(sourceSpec, destinationName, options = {}) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(destinationName)) throw new Error('Use a destination name without path separators.');
+  const sourceCwd = await realpath(typeof sourceSpec === 'string' ? sourceSpec : sourceSpec.cwd);
+  const sourceRoot = await realpath(await text(sourceCwd, ['rev-parse', '--show-toplevel']));
+  const commonDir = await realpath(await text(sourceRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir']));
+  const branch = options.branch ?? destinationName;
+  if (branch.startsWith('-')) throw new Error('The branch cannot start with a hyphen.');
+  await git(sourceRoot, ['check-ref-format', '--branch', branch]);
+  const branches = names(await git(sourceRoot, ['for-each-ref', '--format=%(refname)%00', `refs/heads/${branch}`]));
+  if (branches.some(value => value.trim() === `refs/heads/${branch}`)) throw new Error(`Branch ${branch} already exists.`);
+  const head = await text(sourceRoot, ['rev-parse', '--verify', '--end-of-options', `${options.ref ?? 'HEAD'}^{commit}`]);
+  const tracked = names(await git(sourceRoot, ['ls-tree', '-rz', '--name-only', head]));
+  if (tracked.some(credential)) throw new Error('The selected ref tracks credential files. Remove those files from Git before creating a fork.');
+  const requested = resolve(options.path ?? join(dirname(sourceRoot), destinationName));
+  const parent = await realpath(dirname(requested));
+  const destination = join(parent, basename(requested));
+  if (inside(sourceRoot, destination)) throw new Error('Create the worktree outside the source repository.');
+  await absent(destination);
+  // Git resolves repository boundaries and refs. Never copy .git directories.
+  const changed = options.copyChanges === false ? [] : names(await git(sourceRoot, ['diff', 'HEAD', '--name-only', '--no-renames', '-z']));
+  const untracked = options.copyChanges === false ? [] : names(await git(sourceRoot, ['ls-files', '--others', '--exclude-standard', '-z']));
+  const omittedPaths = [...changed, ...untracked].filter(excluded);
+  const safeChanges = changed.filter(path => !excluded(path));
+  const patch = safeChanges.length ? await git(sourceRoot, ['diff', 'HEAD', '--binary', '--no-ext-diff', '--no-textconv', '--no-renames', '--', ...safeChanges.map(path => `:(literal)${path}`)]) : null;
+  const ownership = { version: 1, token: randomUUID(), commonDir, path: destination, branch, head, sourceRoot };
+  let added = false, reserved = false, saved = false, branchCreated = false;
+  try {
+    await mkdir(destination);
+    reserved = true;
+    await git(sourceRoot, ['branch', '--', branch, head]);
+    branchCreated = true;
+    await git(sourceRoot, ['worktree', 'add', '--', destination, branch]);
+    added = true;
+    await mkdir(join(commonDir, 'agent-env-worktrees'), { recursive: true, mode: 0o700 });
+    await writeFile(await recordPath(ownership), JSON.stringify(ownership), { flag: 'wx', mode: 0o600 });
+    saved = true;
+    if (patch?.length) await git(destination, ['apply', '--binary', '--whitespace=nowarn', '-'], patch);
+    for (const path of untracked.filter(path => !excluded(path))) {
+      if (!await copySourceFile(sourceRoot, destination, path)) omittedPaths.push(path);
+    }
+    const cwd = join(destination, relative(sourceRoot, sourceCwd));
+    if (!(await lstat(cwd)).isDirectory() || !inside(destination, await realpath(cwd))) throw new Error('The selected ref does not provide the source working directory.');
+    return { cwd, ownership, omittedPaths };
+  } catch (error) {
+    try {
+      const registered = reserved && names(await git(sourceRoot, ['worktree', 'list', '--porcelain', '-z'])).includes(`worktree ${destination}`);
+      if (added || registered) {
+        await git(sourceRoot, ['worktree', 'remove', '--force', '--', destination]);
+      } else if (reserved) await rmdir(destination).catch(failure => { if (failure.code !== 'ENOENT') throw failure; });
+      // Delete only the new branch, and only while it still points at the original commit.
+      if (branchCreated) await git(sourceRoot, ['update-ref', '-d', `refs/heads/${branch}`, head]);
+      if (saved) await rm(await recordPath(ownership));
+    } catch (cleanupError) { error.cleanupError = cleanupError; }
+    throw error;
+  }
+}
+
+/** Remove a recorded worktree. Set dirty: 'discard' to explicitly discard its files. */
+export async function removeOwnedWorktree(result, options = {}) {
+  const ownership = result.ownership ?? result;
+  const file = await recordPath(ownership);
+  const saved = JSON.parse(await readFile(file, 'utf8'));
+  if (JSON.stringify(saved) !== JSON.stringify(ownership)) throw new Error('The worktree ownership metadata does not match the saved record.');
+  const path = await realpath(saved.path);
+  if (path !== saved.path || path === saved.sourceRoot) throw new Error('The owned worktree path changed.');
+  const commonDir = await realpath(await text(path, ['rev-parse', '--path-format=absolute', '--git-common-dir']));
+  const root = await realpath(await text(path, ['rev-parse', '--show-toplevel']));
+  const branch = await text(path, ['symbolic-ref', '--quiet', 'HEAD']);
+  if (root !== path || commonDir !== saved.commonDir || branch !== `refs/heads/${saved.branch}`) throw new Error('Git does not identify this checkout as the owned worktree.');
+  const status = await git(path, ['status', '--porcelain=v1', '--untracked-files=all', '--ignored=matching', '-z']);
+  if (status.length && options.dirty !== 'discard') throw new Error('The worktree is dirty. Preserve its files or explicitly select dirty: discard.');
+  if (options.checkOnly) return { checked: path };
+  const head = await text(path, ['rev-parse', 'HEAD']);
+  await git(commonDir, ['worktree', 'remove', ...(options.dirty === 'discard' ? ['--force'] : []), '--', path]);
+  let branchRetained = head !== saved.head;
+  if (!branchRetained) {
+    try { await git(commonDir, ['update-ref', '-d', `refs/heads/${saved.branch}`, saved.head]); }
+    catch { branchRetained = true; }
+  }
+  await rm(file);
+  return { removed: path, branchRetained };
+}