@commonlyai/cli 0.1.0

package/src/lib/sandbox/bwrap.js

@@ -0,0 +1,127 @@
+/**
+ * bubblewrap sandbox adapter — ADR-008 Phase 1.
+ *
+ * Wraps an inner adapter argv (e.g. claude -p ...) in a bwrap invocation that
+ * pins the spawn into a workspace, isolates the network namespace, and
+ * read-only-binds a small allowlist of host paths the adapter needs to start
+ * (TLS certs, libc, the binary itself).
+ *
+ * Linux-only by design: bwrap is a setuid Linux helper. macOS callers get a
+ * loud, specific error at attach time so the failure shape never reaches run.
+ *
+ * Detection idiom mirrors `claude.js#detect`: spawnSync with --version, treat
+ * non-zero or spawn error as "not available."
+ */
+
+import { spawnSync } from 'child_process';
+import { isAbsolute, join } from 'path';
+import { homedir } from 'os';
+
+// Tilde-expansion lives here (and not in environment.js's expandHome) because
+// bwrap reads OS-level paths verbatim — `~` is a shell construct, not a
+// kernel one, so any `~/foo` entry in `read-outside` / `write-outside` would
+// be passed literally to `--ro-bind-try` and silently skipped (the `-try`
+// variant tolerates missing paths). Surfaced live during the 2026-04-17
+// demo validation: `~/.local/bin` was declared but `claude` still wasn't
+// reachable inside the sandbox.
+const expandHome = (p) => {
+  if (!p || typeof p !== 'string') return p;
+  if (p === '~') return homedir();
+  if (p.startsWith('~/')) return join(homedir(), p.slice(2));
+  return p;
+};
+
+const MACOS_MESSAGE = 'bwrap is Linux-only; use sandbox.mode: none in Phase 1 or wait for sandbox-exec adapter';
+
+const DEFAULT_RO_BINDS = [
+  '/etc/ssl/certs',
+  '/etc/resolv.conf',
+  '/usr/lib',
+  '/usr/lib64',
+  '/usr/bin',
+  '/bin',
+  '/lib',
+  '/lib64',
+];
+
+export const detectBwrap = () => {
+  if (process.platform !== 'linux') {
+    return { available: false, error: MACOS_MESSAGE };
+  }
+  try {
+    const res = spawnSync('bwrap', ['--version'], { encoding: 'utf8' });
+    if (res.error || res.status !== 0) {
+      return {
+        available: false,
+        error: 'bwrap not found on PATH. Install bubblewrap: `apt install bubblewrap` (Debian/Ubuntu) or `dnf install bubblewrap` (Fedora).',
+      };
+    }
+    return { available: true, path: 'bwrap' };
+  } catch (err) {
+    return { available: false, error: `bwrap detection failed: ${err.message}` };
+  }
+};
+
+/**
+ * Build the bwrap-wrapped argv. Caller spawns argv[0] with argv.slice(1).
+ *
+ * Network policy honesty (ADR-008 §invariant #4 informs this):
+ *   - unrestricted → --share-net (host networking inside the namespace)
+ *   - restricted   → --unshare-net (NO network at all). Host-allowlist
+ *     filtering needs an outbound proxy or per-host TLS interception, neither
+ *     of which is in Phase 1 scope. Attach-time emits a loud warning so the
+ *     user sees the gap before they think they're protected.
+ *
+ * The expansion order matches `bwrap`'s left-to-right argument application:
+ * isolation flags first, then binds (later binds win on collision), then
+ * --setenv, then `--` and the inner argv.
+ */
+export const wrapArgvWithBwrap = (innerArgv, env, opts = {}) => {
+  if (process.platform !== 'linux') {
+    throw new Error(MACOS_MESSAGE);
+  }
+  if (!Array.isArray(innerArgv) || innerArgv.length === 0) {
+    throw new Error('wrapArgvWithBwrap requires a non-empty innerArgv');
+  }
+  if (!opts.workspacePath || !isAbsolute(opts.workspacePath)) {
+    throw new Error('wrapArgvWithBwrap requires opts.workspacePath as an absolute path');
+  }
+
+  const policy = env?.sandbox?.network?.policy || 'unrestricted';
+  const networkFlags = policy === 'restricted'
+    ? ['--unshare-net']
+    : ['--share-net'];
+
+  const flags = [
+    '--unshare-all',
+    ...networkFlags,
+    '--die-with-parent',
+    '--new-session',
+    '--proc', '/proc',
+    '--dev', '/dev',
+    '--tmpfs', '/tmp',
+  ];
+
+  const userReadOutside = Array.isArray(env?.sandbox?.filesystem?.['read-outside'])
+    ? env.sandbox.filesystem['read-outside'].map(expandHome)
+    : [];
+  const roBinds = [...new Set([...DEFAULT_RO_BINDS, ...userReadOutside])];
+  for (const p of roBinds) {
+    flags.push('--ro-bind-try', p, p);
+  }
+
+  const userWriteOutside = Array.isArray(env?.sandbox?.filesystem?.['write-outside'])
+    ? env.sandbox.filesystem['write-outside'].map(expandHome)
+    : [];
+  for (const p of userWriteOutside) {
+    flags.push('--bind-try', p, p);
+  }
+
+  flags.push('--bind', opts.workspacePath, opts.workspacePath);
+  flags.push('--chdir', opts.workspacePath);
+  flags.push('--setenv', 'HOME', opts.workspacePath);
+
+  return ['bwrap', ...flags, '--', ...innerArgv];
+};
+
+export const BWRAP_MACOS_MESSAGE = MACOS_MESSAGE;

package/src/lib/session-store.js

@@ -0,0 +1,56 @@
+/**
+ * Session store — per-(agent, pod) session IDs at ~/.commonly/sessions/<agent>.json.
+ *
+ * Used by the local-CLI wrapper driver (ADR-005). Wrapped CLIs that support
+ * conversation session IDs (claude --session-id, codex --session, …) call
+ * getSession / setSession around each spawn so the next turn continues where
+ * the previous one left off.
+ *
+ * One file per agent so two `commonly agent run` processes for different
+ * agents never race on the same file (ADR-005 §Spawning semantics permits
+ * parallel agents). Shape on disk:
+ *   {
+ *     "<podId>": { "sessionId": "abc123", "lastTurn": "2026-04-14T18:00:00Z" }
+ *   }
+ *
+ * CLIs without sessions simply never call setSession — getSession returns null.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const sessionsDir = () => join(homedir(), '.commonly', 'sessions');
+const sessionsFile = (agentName) => join(sessionsDir(), `${agentName}.json`);
+
+const readAgent = (agentName) => {
+  const file = sessionsFile(agentName);
+  if (!existsSync(file)) return {};
+  try {
+    return JSON.parse(readFileSync(file, 'utf8'));
+  } catch {
+    return {};
+  }
+};
+
+const writeAgent = (agentName, state) => {
+  if (!existsSync(sessionsDir())) mkdirSync(sessionsDir(), { recursive: true });
+  writeFileSync(sessionsFile(agentName), JSON.stringify(state, null, 2), 'utf8');
+};
+
+export const getSession = (agentName, podId) => {
+  if (!agentName || !podId) return null;
+  return readAgent(agentName)[podId]?.sessionId || null;
+};
+
+export const setSession = (agentName, podId, sessionId) => {
+  if (!agentName || !podId) return;
+  const state = readAgent(agentName);
+  state[podId] = { sessionId, lastTurn: new Date().toISOString() };
+  writeAgent(agentName, state);
+};
+
+export const clearSessions = (agentName) => {
+  const file = sessionsFile(agentName);
+  if (existsSync(file)) rmSync(file);
+};

package/src/lib/skills-import.js

@@ -0,0 +1,112 @@
+/**
+ * Local skills import — the metadata half of "your agent arrives whole"
+ * (retention plan Phase C, D3). Scans a local skills directory
+ * (<cwd>/.claude/skills or ~/.claude/skills) for SKILL.md files, parses
+ * NAME + DESCRIPTION out of the frontmatter, and registers agent-scoped
+ * skill entries so the agent's profile shows what it can do.
+ *
+ * Deliberately metadata-only (plan D3): skill *content* stays on the
+ * user's machine — local agents execute their skills locally, Commonly
+ * doesn't need the body, and skill files can carry private material. The
+ * uploaded SKILL.md is a frontmatter-only stub that says exactly that.
+ */
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export const MAX_SKILLS = 50;
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+/** Parse `name:` and `description:` out of SKILL.md frontmatter. */
+export const parseSkillMeta = (markdown, fallbackName) => {
+  const fm = FRONTMATTER_RE.exec(markdown);
+  if (!fm) return { name: fallbackName, description: '' };
+  const fields = {};
+  for (const line of fm[1].split(/\r?\n/)) {
+    const m = /^(name|description):\s*(.+)$/.exec(line.trim());
+    if (m && !fields[m[1]]) fields[m[1]] = m[2].trim().replace(/^['"]|['"]$/g, '');
+  }
+  return {
+    name: fields.name || fallbackName,
+    description: (fields.description || '').slice(0, 500),
+  };
+};
+
+/**
+ * Find skill directories. Explicit dir wins; otherwise check the two
+ * well-known locations. Each candidate is a directory whose subdirs
+ * contain a SKILL.md.
+ */
+export const detectSkills = ({ cwd = process.cwd(), home = homedir(), explicitDir = null } = {}) => {
+  const roots = [];
+  if (explicitDir) {
+    if (!existsSync(explicitDir) || !statSync(explicitDir).isDirectory()) {
+      throw new Error(`No such directory: ${explicitDir}`);
+    }
+    roots.push(explicitDir);
+  } else {
+    for (const candidate of [join(cwd, '.claude', 'skills'), join(home, '.claude', 'skills')]) {
+      try {
+        if (existsSync(candidate) && statSync(candidate).isDirectory()) roots.push(candidate);
+      } catch {
+        // symlinked skill roots can dangle; skip quietly
+      }
+    }
+  }
+
+  const skills = [];
+  const seen = new Set();
+  for (const root of roots) {
+    for (const entry of readdirSync(root).sort()) {
+      const skillFile = join(root, entry, 'SKILL.md');
+      try {
+        if (!existsSync(skillFile) || !statSync(skillFile).isFile()) continue;
+      } catch {
+        continue;
+      }
+      const meta = parseSkillMeta(readFileSync(skillFile, 'utf8'), entry);
+      if (seen.has(meta.name)) continue;
+      seen.add(meta.name);
+      skills.push({ ...meta, path: skillFile });
+      if (skills.length >= MAX_SKILLS) return skills;
+    }
+  }
+  return skills;
+};
+
+/** The frontmatter-only stub that gets uploaded in place of skill content. */
+export const skillStub = ({ name, description }) => [
+  '---',
+  `name: ${name}`,
+  `description: ${description || name}`,
+  '---',
+  '',
+  'Imported as metadata from a local agent — the skill itself runs on the',
+  "agent's own machine; its content was intentionally not uploaded.",
+  '',
+].join('\n');
+
+/**
+ * Register the skills as agent-scoped entries via POST /api/skills/import.
+ * `client` must be authenticated as the USER (pod membership is checked),
+ * not the agent runtime token.
+ */
+export const importSkills = async (client, { skills, podId, agentName, instanceId = 'default' }) => {
+  const results = [];
+  for (const skill of skills) {
+    // eslint-disable-next-line no-await-in-loop
+    await client.post('/api/skills/import', {
+      podId,
+      name: skill.name,
+      content: skillStub(skill),
+      description: skill.description || undefined,
+      scope: 'agent',
+      agentName,
+      instanceId,
+    });
+    results.push(skill.name);
+  }
+  return { imported: results.length, names: results };
+};

package/src/lib/webhook-server.js

@@ -0,0 +1,88 @@
+/**
+ * Local webhook server — receives forwarded events from the poller
+ * and delivers them to the developer's agent process.
+ *
+ * The developer's agent code handles POST /cap (or custom path)
+ * and returns { outcome, content? }.
+ */
+
+import { createServer } from 'http';
+import { createHmac } from 'crypto';
+
+export const startWebhookServer = ({
+  port = 3001,
+  path = '/cap',
+  secret = null,
+  onEvent,   // async (event) => { outcome, content? }
+  onReady,   // (url) => void
+}) => new Promise((resolve, reject) => {
+  const server = createServer(async (req, res) => {
+    if (req.method !== 'POST' || req.url !== path) {
+      res.writeHead(404);
+      res.end();
+      return;
+    }
+
+    // Read body
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', async () => {
+      const rawBody = Buffer.concat(chunks).toString('utf8');
+
+      // Verify signature if secret configured
+      if (secret) {
+        const sig = req.headers['x-commonly-signature'];
+        const expected = `sha256=${createHmac('sha256', secret).update(rawBody).digest('hex')}`;
+        if (sig !== expected) {
+          res.writeHead(401);
+          res.end(JSON.stringify({ error: 'Invalid signature' }));
+          return;
+        }
+      }
+
+      let event;
+      try { event = JSON.parse(rawBody); } catch {
+        res.writeHead(400);
+        res.end(JSON.stringify({ error: 'Invalid JSON' }));
+        return;
+      }
+
+      let result = { outcome: 'acknowledged' };
+      try {
+        result = (await onEvent(event)) || { outcome: 'acknowledged' };
+      } catch (err) {
+        result = { outcome: 'error', reason: err.message };
+      }
+
+      res.writeHead(200, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify(result));
+    });
+  });
+
+  server.on('error', reject);
+  server.listen(port, () => {
+    const url = `http://localhost:${port}${path}`;
+    onReady?.(url);
+    resolve({ server, url, close: () => server.close() });
+  });
+});
+
+/**
+ * Forward a polled event to a local webhook server.
+ * Used by `agent connect` to bridge polling → local HTTP.
+ */
+export const forwardToLocalWebhook = async (event, webhookUrl, secret = null) => {
+  const payload = JSON.stringify(event);
+  const headers = {
+    'Content-Type': 'application/json',
+    'X-Commonly-Event': event.type,
+    'X-Commonly-Delivery': String(event._id),
+  };
+  if (secret) {
+    headers['X-Commonly-Signature'] = `sha256=${createHmac('sha256', secret).update(payload).digest('hex')}`;
+  }
+
+  const res = await fetch(webhookUrl, { method: 'POST', headers, body: payload });
+  if (!res.ok) throw new Error(`Local webhook returned HTTP ${res.status}`);
+  try { return await res.json(); } catch { return { outcome: 'acknowledged' }; }
+};