agentcage 0.1.6 → 0.1.8

package/src/server.js

@@ -0,0 +1,188 @@
+// `agentcage ui`: a local web UI. A JSON API on 127.0.0.1 over the same functions the CLI uses, plus one static page.
+// Security: loopback only, a random session token (sent by the page in a header, so other sites can't call the API:
+// a custom header needs a CORS preflight, which is never answered) and a Host check against DNS rebinding.
+// The server stops itself when the UI window has been closed for a few seconds and no job is running.
+import { createServer } from 'node:http';
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { AGENTS, DEV_TOOLS, PROVIDERS, TOOLS, hostInfo } from './catalog.js';
+import { ROOT, cleanName, createContainer, findIdes, hasContainer, listContainers, loadContainer, nameError, openIde, removeContainer, state, up, upgradeContainer } from './container.js';
+import { isGitUrl, localRemote, parseRemote } from './git.js';
+import { connectDesktop, desktopRunning, desktopRunningAsync, desktopServers, detectDesktop, latestVersion, serverName, setProviderKey, setupProject } from './opencode.js';
+import { run } from './run.js';
+import { CHOICES, DEFAULTS, LABELS, loadSettings, saveSettings } from './settings.js';
+import { openWindow, pickFolder } from './shortcut.js';
+import * as conn from './connections.js';
+
+const PAGE = new URL('./ui.html', import.meta.url), LOCK = join(ROOT, 'ui.json');
+const CSP = "default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src 'self' data:; connect-src 'self'";
+const fail = (status, message) => Object.assign(new Error(message), { status });
+
+// Already running? Then just open its window again.
+async function running() {
+  try {
+    const { port, token } = JSON.parse(readFileSync(LOCK, 'utf8'));
+    const r = await fetch(`http://127.0.0.1:${port}/api/meta`, { headers: { 'x-agentcage-token': token }, signal: AbortSignal.timeout(1500) });
+    return r.ok && `http://127.0.0.1:${port}/#${token}`;
+  } catch { return false; }
+}
+
+export async function serve({ open = true } = {}) {
+  const again = await running();
+  if (again) { if (open) openWindow(again); return console.log(`agentcage UI is already running: ${again}`); }
+
+  const token = randomBytes(24).toString('hex'), tok = Buffer.from(token), ides = findIdes();
+  const busy = new Map(); // container name → { label, error?, create? }: what is running for it (polled by the page)
+  let port, clients = 0, seen = false;
+
+  // Runs fn in the background; fn gets createContainer's step(label, f) to report progress
+  const job = (name, label, fn, create = false) => {
+    busy.set(name, { label, create });
+    fn((l, f) => ((busy.get(name).label = l), f())).then(() => busy.delete(name), e => busy.set(name, { ...busy.get(name), error: e.message }))
+      .finally(maybeExit);
+  };
+  const ensureRunning = async b => { if (state(b) !== 'running') await up(b); };
+  const project = b => (b.tools.includes('opencode') ? setupProject(b).catch(() => {}) : null); // icon/name: nice to have
+
+  // One `docker ps` for all containers (null: Docker is not running)
+  const dockerStates = () => run('docker', ['ps', '-a', '--format', '{{.Names}}\t{{.State}}\t{{.Status}}'])
+    .then(out => new Map(out.split('\n').filter(Boolean).map(l => l.split('\t')).map(([n, s, st]) => [n, { state: s, status: st }])), () => null);
+
+  async function snapshot() {
+    const d = detectDesktop();
+    const [docker, desktopOpen, ports] = await Promise.all([dockerStates(), desktopRunningAsync(),
+      d.hasDb ? desktopServers().then(l => new Set(l.map(x => x.port)), () => null) : null]);
+    const list = listContainers().map(b => ({
+      name: b.name, container: b.container, ...(docker?.get(b.container) ?? { state: docker ? 'missing' : 'unknown', status: '' }),
+      port: b.port, tools: b.tools, git: b.git, source: b.source, opencodeVersion: b.opencodeVersion, server: serverName(b),
+      registered: ports && b.tools.includes('opencode') ? ports.has(b.port) : null, busy: busy.get(b.name) ?? null,
+    }));
+    for (const [name, job] of busy) if (!list.some(c => c.name === name)) list.push({ name, state: 'creating', status: '', tools: [], busy: job });
+    return { docker: !!docker, desktop: { found: d.hasDb, version: d.version ?? null, running: desktopOpen }, containers: list, ides, settings: loadSettings() };
+  }
+
+  // What the dialog needs to know about a source and name
+  function check(src, name) {
+    const git = !!src && isGitUrl(src), srcError = !src ? 'Enter a folder or a repository URL' : !git && !existsSync(src) ? 'Folder not found' : undefined;
+    const remote = !srcError && parseRemote(git ? src : localRemote(src));
+    const suggested = srcError ? '' : cleanName(src);
+    return { srcError, suggested, nameError: (name || suggested) ? nameError(name || suggested) : undefined,
+      remote: remote ? `${remote.host}/${remote.path}` : null, help: remote ? hostInfo(remote.host).help(remote.path) : null,
+      cloneWith: git && conn.cloneToken(src) ? 'your connection' : null };
+  }
+
+  async function create(o) {
+    if ([...busy.values()].some(j => j.create && !j.error)) throw fail(409, 'Another container is being created. Wait for it to finish.');
+    const src = o.src?.trim(), name = o.name?.trim(), c = check(src, name);
+    if (c.srcError || c.nameError || !name) throw fail(400, c.srcError ?? c.nameError ?? 'Enter a name');
+    const remoteUrl = isGitUrl(src) ? src : localRemote(src), git = !c.remote ? 'none' : o.git === 'token' ? 'token' : 'forward';
+    if (git === 'token' && !o.token) throw fail(400, 'Paste the repo token, or choose forwarded credentials');
+    const tools = TOOLS.map(t => t.id).filter(id => o.tools?.includes(id)), clone = isGitUrl(src) ? conn.cloneToken(src) : null;
+    job(name, 'Preparing', async step => {
+      const oc = tools.includes('opencode'), opencodeVersion = oc ? detectDesktop().version ?? await latestVersion() : undefined;
+      const b = await createContainer({ src, name, tools, git, token: git === 'token' ? o.token : undefined, remote: remoteUrl, opencodeVersion,
+        cloneToken: clone?.token, cloneBearer: clone?.header }, step);
+      if (oc) {
+        await step('Setting up the OpenCode project', () => project(b));
+        if (detectDesktop().hasDb && !desktopRunning()) await step('Adding it to OpenCode Desktop', () => connectDesktop(b));
+      }
+      if (o.ide) openIde(b, o.ide);
+    }, true);
+  }
+
+  const ACTIONS = {
+    start: b => job(b.name, 'Starting', () => ensureRunning(b)),
+    stop: b => job(b.name, 'Stopping', () => run('docker', ['stop', b.container])),
+    open: (b, o) => job(b.name, 'Starting', async () => { await ensureRunning(b); openIde(b, o.ide || ides[0]?.value || 'code'); }),
+    upgrade: b => job(b.name, 'Rebuilding (code, logins and sessions are kept)', async () => {
+      await upgradeContainer(b, detectDesktop().version ?? await latestVersion()); await project(b);
+    }),
+    remove: b => job(b.name, 'Removing', () => removeContainer(b)),
+    connect: b => {
+      if (desktopRunning()) throw fail(409, 'Close OpenCode Desktop first, then click Add to OpenCode again. Its server list can only be changed while it is closed.');
+      job(b.name, 'Adding to OpenCode Desktop', async () => { await ensureRunning(b); await project(b); await connectDesktop(b); });
+    },
+    provider: async (b, o) => {
+      if (!PROVIDERS.some(x => x.id === o.id) || !o.key) throw fail(400, 'Pick a provider and paste its API key');
+      await ensureRunning(b);
+      await setProviderKey(b, o.id, o.key);
+    },
+  };
+
+  function saveSettingsFrom(body) {
+    const s = loadSettings();
+    for (const [k, v] of Object.entries(body)) {
+      if (!(k in DEFAULTS)) continue;
+      if (CHOICES[k] ? !(v in CHOICES[k]) : !/^[a-z0-9-]*$/.test(v)) throw fail(400, `${LABELS[k]}: invalid value`);
+      s[k] = v;
+    }
+    saveSettings(s);
+  }
+
+  const ROUTES = [
+    ['GET', /^\/api\/meta$/, () => ({ agents: AGENTS, devTools: DEV_TOOLS, providers: PROVIDERS, labels: LABELS, choices: CHOICES, keys: Object.keys(DEFAULTS), platform: process.platform })],
+    ['GET', /^\/api\/state$/, snapshot],
+    ['GET', /^\/api\/check$/, (_, q) => check(q.get('src')?.trim(), q.get('name')?.trim())],
+    ['POST', /^\/api\/containers$/, (_, __, body) => create(body)],
+    ['POST', /^\/api\/containers\/([a-z0-9-]+)\/(\w+)$/, async ([, name, action], _, body) => {
+      if (action === 'dismiss' || (action === 'remove' && !hasContainer(name))) return void busy.delete(name);
+      if (!ACTIONS[action]) throw fail(404, 'Unknown action');
+      if (busy.get(name) && !busy.get(name).error) throw fail(409, `${name} is busy: ${busy.get(name).label}`);
+      busy.delete(name);
+      await ACTIONS[action](loadContainer(name), body);
+    }],
+    ['PUT', /^\/api\/settings$/, (_, __, body) => saveSettingsFrom(body)],
+    ['GET', /^\/api\/connections$/, () => conn.status()],
+    ['PUT', /^\/api\/connections\/(github|azure)$/, ([, id], _, body) => conn.savePat(id, body.token?.trim(), body.org?.trim())],
+    ['DELETE', /^\/api\/connections\/(github|azure)$/, ([, id]) => conn.removePat(id)],
+    ['GET', /^\/api\/repos\/(github|azure)$/, ([, id], q) => conn.repos(id, q.get('org'))],
+    ['POST', /^\/api\/browse$/, async (_, __, body) => ({ path: await pickFolder(body.start?.trim()) })],
+  ];
+
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url, 'http://localhost');
+    const send = (code, body, type = 'application/json') => {
+      res.writeHead(code, { 'content-type': type, 'cache-control': 'no-store', 'x-content-type-options': 'nosniff', 'content-security-policy': CSP });
+      res.end(type === 'application/json' ? JSON.stringify(body ?? {}) : body);
+    };
+    if (req.headers.host !== `127.0.0.1:${port}`) return send(403, { error: 'Wrong host' });
+    if (req.method === 'GET' && url.pathname === '/') return send(200, readFileSync(PAGE), 'text/html; charset=utf-8');
+    if (req.method === 'GET' && url.pathname === '/icon.svg') return send(200, readFileSync(new URL('./logo.svg', import.meta.url)), 'image/svg+xml');
+    const t = Buffer.from(String(req.headers['x-agentcage-token'] ?? ''));
+    if (t.length !== tok.length || !timingSafeEqual(t, tok)) return send(401, { error: 'Not authorized. Open the UI with: agentcage ui' });
+
+    // The page keeps this request open while it is open; when it closes, the server can stop
+    if (url.pathname === '/api/alive') {
+      clients++; seen = true;
+      res.writeHead(200, { 'content-type': 'text/plain', 'cache-control': 'no-store' }).write('ok\n');
+      const ping = setInterval(() => res.write('.'), 20000);
+      // res, not req: req's close fires as soon as its (empty) body is read; res's fires when the connection drops
+      return res.on('close', () => { clients--; clearInterval(ping); setTimeout(maybeExit, 8000); });
+    }
+    const route = ROUTES.find(([m, re]) => m === req.method && re.test(url.pathname));
+    if (!route) return send(404, { error: 'Not found' });
+    try {
+      let raw = '';
+      for await (const c of req) raw += c;
+      send(200, await route[2](url.pathname.match(route[1]), url.searchParams, raw ? JSON.parse(raw) : {}));
+    } catch (e) { send(e.status ?? 500, { error: e.message }); }
+  });
+
+  function maybeExit() {
+    if (clients > 0 || !seen || [...busy.values()].some(j => !j.error)) return;
+    rmSync(LOCK, { force: true });
+    process.exit(0);
+  }
+  // Nobody opened the page within 10 minutes (no browser?): stop
+  setTimeout(() => { if (!seen) { seen = true; maybeExit(); } }, 10 * 60 * 1000).unref();
+  for (const sig of ['SIGINT', 'SIGTERM']) process.on(sig, () => { rmSync(LOCK, { force: true }); process.exit(0); });
+
+  await new Promise(r => server.listen(0, '127.0.0.1', r));
+  port = server.address().port;
+  mkdirSync(ROOT, { recursive: true }); // first run: ~/.agentcage may not exist yet
+  writeFileSync(LOCK, JSON.stringify({ port, token, pid: process.pid }), { mode: 0o600 });
+  const url = `http://127.0.0.1:${port}/#${token}`;
+  console.log(`agentcage UI: ${url}\nIt stops by itself when you close the window. Ctrl+C stops it now.`);
+  if (open) openWindow(url);
+}

package/src/settings.js

@@ -6,10 +6,17 @@ import { join } from 'node:path';
 const FILE = join(homedir(), '.agentcage', 'settings.json');
 // Project icon colors OpenCode Desktop can show (others render as gray). green first: our default, gray: OpenCode's.
 export const COLORS = ['green', 'gray', 'pink', 'blue', 'red', 'purple', 'yellow', 'orange', 'cyan'];
-export const DEFAULTS = { color: 'green', containerPrefix: 'ac-', serverPrefix: 'ac-', projectPrefix: 'ac-' };
+export const DEFAULTS = { projectIcon: 'image', color: 'green', containerPrefix: 'ac-', serverPrefix: 'ac-', projectPrefix: 'ac-', gitToken: 'never' };
 export const LABELS = {
-  color: 'OpenCode project color', containerPrefix: 'Docker container prefix',
+  projectIcon: 'OpenCode project icon', color: 'OpenCode project color (for a plain-color icon)', containerPrefix: 'Docker container prefix',
   serverPrefix: 'OpenCode server prefix', projectPrefix: 'OpenCode project prefix',
+  gitToken: 'Git token per project (GitHub, GitLab, Bitbucket, Azure DevOps)',
+};
+// Settings with fixed choices ({ value: label }); the others are free-text prefixes
+export const CHOICES = {
+  projectIcon: { image: 'generated image (prefix + first three letters of the name)', color: 'plain color' },
+  color: Object.fromEntries(COLORS.map(c => [c, c === 'gray' ? "gray (OpenCode's default)" : c])),
+  gitToken: { never: "don't use (push with the IDE's forwarded credentials)", ask: 'ask every time', always: 'always use' },
 };
 
 export const loadSettings = () => ({ ...DEFAULTS, ...(existsSync(FILE) && JSON.parse(readFileSync(FILE, 'utf8'))) });

package/src/shortcut.js

@@ -0,0 +1,90 @@
+// Desktop / Start Menu shortcut for `agentcage ui`, its icon, and opening the UI in an app-style browser window.
+import { spawn, spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { ROOT } from './container.js';
+import { appIcon, appIco } from './icon.js';
+import { launch, run, runSync } from './run.js';
+
+const P = process.platform, WIN = P === 'win32', SCRIPT = fileURLToPath(new URL('../bin/agentcage.js', import.meta.url));
+export const SHORTCUT_PLACES = WIN ? 'the desktop and Start Menu' : 'the desktop and app menu';
+
+// Starts the UI server in the background without a console window (the shortcut runs `agentcage ui --detach`)
+export const detach = (open = true) => spawn(process.execPath, [SCRIPT, 'ui', ...(open ? [] : ['--no-open'])], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
+
+// ~/.agentcage/agentcage.png (Linux) and .ico (Windows shortcuts)
+function iconFiles() {
+  mkdirSync(ROOT, { recursive: true });
+  const f = ext => join(ROOT, `agentcage.${ext}`);
+  writeFileSync(f('png'), appIcon());
+  writeFileSync(f('ico'), appIco());
+  return { png: f('png'), ico: f('ico') };
+}
+
+// Windows: .lnk files via the built-in WScript.Shell. Paths come in through env vars, so nothing needs quoting.
+// GetFolderPath follows a Desktop redirected to OneDrive.
+const PS = `$w = New-Object -ComObject WScript.Shell
+foreach ($d in [Environment]::GetFolderPath('Desktop'), [Environment]::GetFolderPath('Programs')) {
+  $f = Join-Path $d 'agentcage.lnk'
+  if ($env:AC_REMOVE) { if (Test-Path $f) { Remove-Item $f; $f }; continue }
+  $s = $w.CreateShortcut($f); $s.TargetPath = $env:AC_NODE; $s.Arguments = '"' + $env:AC_SCRIPT + '" ui --detach'
+  $s.IconLocation = $env:AC_ICO; $s.WindowStyle = 7; $s.Description = 'agentcage: dev containers for AI coding agents'; $s.Save(); $f }`;
+const powershell = env => spawnSync('powershell', ['-NoProfile', '-NonInteractive', '-Command', PS], { encoding: 'utf8', env: { ...process.env, ...env }, windowsHide: true })
+  .stdout.split(/\r?\n/).filter(Boolean);
+
+// Linux: .desktop entries in the app menu and on the desktop
+const linuxFiles = () => [join(homedir(), '.local', 'share', 'applications'), runSync('xdg-user-dir', ['DESKTOP']) || join(homedir(), 'Desktop')]
+  .filter(existsSync).map(d => join(d, 'agentcage.desktop'));
+
+// Returns the shortcut files created
+export function createShortcuts() {
+  const { png, ico } = iconFiles();
+  if (WIN) return powershell({ AC_NODE: process.execPath, AC_SCRIPT: SCRIPT, AC_ICO: ico });
+  if (P === 'darwin') throw new Error('Shortcuts are not supported on macOS yet. Run: agentcage ui');
+  const entry = `[Desktop Entry]\nType=Application\nName=agentcage\nComment=Dev containers for AI coding agents\n`
+    + `Exec="${process.execPath}" "${SCRIPT}" ui\nIcon=${png}\nTerminal=false\nCategories=Development;\n`;
+  return linuxFiles().map(f => {
+    writeFileSync(f, entry);
+    chmodSync(f, 0o755);
+    spawnSync('gio', ['set', f, 'metadata::trusted', 'true'], { stdio: 'ignore' }); // GNOME: launchable from the desktop
+    return f;
+  });
+}
+export const removeShortcuts = () => (WIN ? powershell({ AC_REMOVE: '1' }) : linuxFiles().filter(existsSync).map(f => (rmSync(f), f)));
+
+// Edge / Chrome / Chromium, for an app window (own window and taskbar icon, no tabs or address bar)
+function appBrowser() {
+  if (WIN) {
+    const E = process.env;
+    return [[E['ProgramFiles(x86)'], 'Microsoft', 'Edge'], [E.ProgramFiles, 'Microsoft', 'Edge'], [E.ProgramFiles, 'Google', 'Chrome'], [E.LOCALAPPDATA, 'Google', 'Chrome']]
+      .filter(([root]) => root).map(([root, ...p]) => join(root, ...p, 'Application', p[1] === 'Edge' ? 'msedge.exe' : 'chrome.exe')).find(existsSync);
+  }
+  if (P === 'linux') return ['google-chrome', 'google-chrome-stable', 'chromium', 'chromium-browser', 'microsoft-edge', 'microsoft-edge-stable']
+    .find(c => runSync('which', [c]));
+}
+
+// Opens the UI: an app window when a Chromium browser is installed, else the default browser
+export function openWindow(url) {
+  const b = appBrowser();
+  if (b) launch(b, [`--app=${url}`, '--window-size=1200,860']);
+  else launch(WIN ? 'start' : P === 'darwin' ? 'open' : 'xdg-open', [url]);
+}
+
+// Native folder picker for the New container dialog (a web page can't see full paths). Resolves to the path, or null if cancelled.
+// Windows: PowerShell 7 (.NET 8) shows the modern dialog, Windows PowerShell the classic folder tree; -STA is needed for dialogs.
+const PICK = `Add-Type -AssemblyName System.Windows.Forms
+$d = New-Object System.Windows.Forms.FolderBrowserDialog
+$d.Description = 'Choose the project folder for the new container'
+try { $d.UseDescriptionForTitle = $true } catch {}
+if ($env:AC_START -and (Test-Path $env:AC_START)) { $d.SelectedPath = $env:AC_START }
+if ($d.ShowDialog((New-Object System.Windows.Forms.Form -Property @{ TopMost = $true })) -eq 'OK') { $d.SelectedPath }`;
+export function pickFolder(start = '') {
+  const has = c => runSync(WIN ? 'where' : 'which', [c]);
+  const [cmd, args] = WIN ? [has('pwsh') ? 'pwsh' : 'powershell', ['-NoProfile', '-NonInteractive', '-STA', '-Command', PICK]]
+    : has('zenity') ? ['zenity', ['--file-selection', '--directory', '--title=Choose the project folder', ...(start ? [`--filename=${start}/`] : [])]]
+    : has('kdialog') ? ['kdialog', ['--getexistingdirectory', start || homedir()]] : [];
+  if (!cmd) return Promise.reject(new Error('No folder picker found (install zenity). Type the folder path instead.'));
+  return run(cmd, args, { env: { AC_START: start } }).then(p => p || null, () => null); // cancel exits non-zero
+}