@commonlyai/cli 0.1.0

package/src/commands/login.js

@@ -0,0 +1,105 @@
+/**
+ * commonly login [--instance <url>] [--key <name>]
+ *
+ * Authenticates and stores the token in ~/.commonly/config.json.
+ * Supports multiple named instances.
+ */
+
+import { createInterface } from 'readline';
+import { login as apiLogin } from '../lib/api.js';
+import { saveInstance, LOCAL_URL } from '../lib/config.js';
+
+const prompt = (rl, question) => new Promise((resolve) => rl.question(question, resolve));
+
+const promptSecret = (question) => new Promise((resolve) => {
+  process.stdout.write(question);
+  const { stdin } = process;
+  stdin.setRawMode?.(true);
+  stdin.resume();
+  stdin.setEncoding('utf8');
+
+  let password = '';
+  const onData = (ch) => {
+    if (ch === '\n' || ch === '\r' || ch === '\u0003') {
+      stdin.setRawMode?.(false);
+      stdin.pause();
+      stdin.removeListener('data', onData);
+      process.stdout.write('\n');
+      resolve(password);
+    } else if (ch === '\u007f') {
+      password = password.slice(0, -1);
+    } else {
+      password += ch;
+    }
+  };
+  stdin.on('data', onData);
+});
+
+export const registerLogin = (program) => {
+  program
+    .command('login')
+    .description('Authenticate to a Commonly instance')
+    .option('--instance <url>', 'Instance URL (default: https://api.commonly.me)')
+    .option('--key <name>', 'Config key to save as (default: "default" or "local")')
+    .addHelpText('after', `
+Examples:
+  $ commonly login                                                   # production (default key)
+  $ commonly login --instance https://api.commonly.me --key dev  # named profile
+  $ commonly login --instance http://localhost:5000                  # saved as "local"
+
+Tokens are stored in ~/.commonly/config.json. Other commands take
+--instance <url-or-key> to target the right profile.
+`)
+    .action(async (opts) => {
+      const instanceUrl = opts.instance
+        ? opts.instance.replace(/\/$/, '')
+        : 'https://api.commonly.me';
+
+      const isLocal = instanceUrl.includes('localhost') || instanceUrl.includes('127.0.0.1');
+      const configKey = opts.key || (isLocal ? 'local' : 'default');
+
+      console.log(`Logging in to ${instanceUrl}`);
+
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      const email = await prompt(rl, 'Email: ');
+      rl.close();
+
+      const password = await promptSecret('Password: ');
+
+      try {
+        const data = await apiLogin(instanceUrl, email.trim(), password);
+        const token = data.token;
+        const userId = data.user?._id || data.user?.id;
+        const username = data.user?.username;
+
+        saveInstance({ key: configKey, url: instanceUrl, token, userId, username });
+
+        console.log(`\nLogged in as ${username} (${configKey})`);
+        console.log(`Token saved to ~/.commonly/config.json`);
+      } catch (err) {
+        console.error(`Login failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+};
+
+export const registerWhoami = (program) => {
+  program
+    .command('whoami')
+    .description('Show current auth state')
+    .option('--instance <url>', 'Target instance')
+    .action(async (opts) => {
+      const { getActiveInstance, listInstances } = await import('../lib/config.js');
+      const instances = listInstances();
+
+      if (instances.length === 0) {
+        console.log('Not logged in. Run: commonly login');
+        return;
+      }
+
+      instances.forEach(({ key, url, username, active, savedAt }) => {
+        const marker = active ? '→' : ' ';
+        console.log(`${marker} ${key}  ${username || '?'}@${url}  (saved ${new Date(savedAt).toLocaleDateString()})`);
+      });
+    });
+};

package/src/commands/pod.js

@@ -0,0 +1,123 @@
+/**
+ * commonly pod <subcommand>
+ *
+ * list   — list pods you're a member of
+ * send   — post a message to a pod
+ * tail   — watch a pod's messages live
+ */
+
+import { createClient } from '../lib/api.js';
+import { getToken, resolveInstanceUrl } from '../lib/config.js';
+
+export const registerPod = (program) => {
+  const pod = program.command('pod').description('Manage pods');
+
+  pod.addHelpText('after', `
+Examples:
+  $ commonly pod list
+  $ commonly pod send <podId> "hello from the CLI"
+  $ commonly pod tail <podId>
+
+Each command accepts --instance <url-or-key> to target a non-default
+Commonly instance (see: commonly login --help).
+`);
+
+  // ── list ──────────────────────────────────────────────────────────────────
+  pod
+    .command('list')
+    .description('List pods you are a member of')
+    .option('--instance <url>', 'Target Commonly instance')
+    .action(async (opts) => {
+      const token = getToken(opts.instance);
+      if (!token) { console.error('Not logged in. Run: commonly login'); process.exit(1); }
+
+      const client = createClient({ instance: resolveInstanceUrl(opts.instance), token });
+
+      try {
+        const data = await client.get('/api/pods');
+        const pods = Array.isArray(data) ? data : data.pods || [];
+
+        if (pods.length === 0) { console.log('No pods found.'); return; }
+
+        const col = (s, w) => String(s ?? '').padEnd(w).slice(0, w);
+        console.log(`${col('NAME', 24)} ${col('TYPE', 12)} ${col('MEMBERS', 8)} ID`);
+        console.log('─'.repeat(70));
+        pods.forEach((p) => {
+          console.log(`${col(p.name, 24)} ${col(p.type || 'chat', 12)} ${col(p.memberCount ?? p.members?.length ?? '?', 8)} ${p._id}`);
+        });
+      } catch (err) {
+        console.error(`Failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // ── send ──────────────────────────────────────────────────────────────────
+  pod
+    .command('send <podId> <message>')
+    .description('Post a message to a pod')
+    .option('--instance <url>', 'Target Commonly instance')
+    .action(async (podId, message, opts) => {
+      const token = getToken(opts.instance);
+      if (!token) { console.error('Not logged in. Run: commonly login'); process.exit(1); }
+
+      const client = createClient({ instance: resolveInstanceUrl(opts.instance), token });
+
+      try {
+        // Try agent runtime endpoint first (agent token), fall back to user endpoint
+        const result = await client.post(`/api/agents/runtime/pods/${podId}/messages`, {
+          content: message,
+        }).catch(() => client.post(`/api/messages/${podId}`, {
+          content: message,
+        }));
+
+        console.log(`Sent (${result._id || result.id || 'ok'})`);
+      } catch (err) {
+        console.error(`Failed: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // ── tail ──────────────────────────────────────────────────────────────────
+  pod
+    .command('tail <podId>')
+    .description('Watch pod messages live')
+    .option('--filter <type>', 'Filter by sender type: agents, humans, all', 'all')
+    .option('--instance <url>', 'Target Commonly instance')
+    .action(async (podId, opts) => {
+      const token = getToken(opts.instance);
+      if (!token) { console.error('Not logged in. Run: commonly login'); process.exit(1); }
+
+      const client = createClient({ instance: resolveInstanceUrl(opts.instance), token });
+
+      let lastId = null;
+      console.log(`Watching pod ${podId}... (Ctrl+C to stop)\n`);
+
+      const poll = async () => {
+        try {
+          const data = await client.get(`/api/messages/${podId}`, {
+            limit: 20,
+            after: lastId,
+          });
+          const messages = Array.isArray(data) ? data : data.messages || [];
+
+          messages.forEach((m) => {
+            const isBot = m.isBot || m.sender?.isBot;
+            if (opts.filter === 'agents' && !isBot) return;
+            if (opts.filter === 'humans' && isBot) return;
+
+            const ts = new Date(m.createdAt || m.timestamp).toTimeString().slice(0, 8);
+            const who = m.username || m.sender?.username || '?';
+            const marker = isBot ? '🤖' : '👤';
+            console.log(`[${ts}] ${marker} ${who}: ${m.content}`);
+            lastId = m._id || m.id;
+          });
+        } catch (err) {
+          console.error(`[poll error] ${err.message}`);
+        }
+      };
+
+      await poll();
+      const interval = setInterval(poll, 3000);
+      process.on('SIGINT', () => { clearInterval(interval); process.exit(0); });
+    });
+};

package/src/index.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * @commonlyai/cli — the developer interface to CAP.
+ *
+ * Usage:
+ *   commonly login
+ *   commonly agent connect --name my-agent --port 3001
+ *   commonly pod send <podId> "hello"
+ *   commonly dev up
+ */
+
+import { Command } from 'commander';
+import { readFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+import { registerLogin, registerWhoami } from './commands/login.js';
+import { registerAgent } from './commands/agent.js';
+import { registerPod } from './commands/pod.js';
+import { registerDev } from './commands/dev.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+const program = new Command();
+
+program
+  .name('commonly')
+  .description('The Commonly CLI — connect agents, manage pods, iterate fast')
+  .version(pkg.version)
+  .showHelpAfterError('(run `commonly --help` for usage)');
+
+// Auth
+registerLogin(program);
+registerWhoami(program);
+
+// Agent management
+registerAgent(program);
+
+// Pod management
+registerPod(program);
+
+// Local dev environment
+registerDev(program);
+
+// Each subcommand owns its own `--instance <url>` flag; a program-level
+// duplicate shadowed the subcommand value on commander v12, causing
+// `commonly login --instance …` to silently fall back to the default URL.
+
+program.addHelpText('after', `
+Quick start:
+  $ commonly login --instance https://api.commonly.me --key dev
+  $ commonly agent attach claude --pod <podId> --name my-claude
+  $ commonly agent run my-claude                       # Ctrl+C to stop
+  $ commonly agent detach my-claude                    # clean uninstall
+
+Custom Python agent:
+  $ commonly agent init --language python --name research-bot --pod <podId>
+  $ python3 research-bot.py
+
+Subcommand help:
+  $ commonly login --help
+  $ commonly agent attach --help
+  $ commonly agent run --help
+  $ commonly pod tail --help
+
+Note: --instance is a subcommand option, not a program option. It accepts
+either a saved key name ("dev", "local", "default") or a full URL.
+
+Docs: https://github.com/Team-Commonly/commonly/blob/main/docs/cli/README.md
+`);
+
+program.parse(process.argv);

package/src/lib/adapters/claude.js

@@ -0,0 +1,296 @@
+/**
+ * claude adapter — wraps the local `claude` CLI as a Commonly agent.
+ *
+ * Contract: ADR-005 §Adapter pattern.
+ *
+ * Memory preamble: if ctx.memoryLongTerm is non-empty, the adapter prepends
+ * it to the prompt as a system-context preamble (§Memory bridge).
+ *
+ * Environment (ADR-008 Phase 1): if ctx.environment is present, the adapter
+ * symlinks declared Claude skills into `<cwd>/.claude/skills/`, writes an MCP
+ * config file at `<cwd>/.commonly/mcp-config.json` when `mcp` is declared,
+ * and wraps the argv with bwrap when `sandbox.mode === 'bwrap'`. The spawn
+ * binary becomes `bwrap` in that case — claude moves to the inner argv.
+ * When ctx.environment is absent, behaviour is identical to pre-ADR-008.
+ *
+ * Session continuity (IMPORTANT — the two claude flags are not interchangeable):
+ *   - First turn (no persisted id): mint a UUID and pass `--session-id <uuid>`.
+ *     claude treats `--session-id` as "CREATE a session with this exact UUID"
+ *     and rejects with "Session ID ... is already in use" if the UUID was
+ *     already used.
+ *   - Subsequent turns (persisted id present): pass `--resume <uuid>` instead.
+ *     `--resume` means "continue this existing session."
+ *   The wrapper persists the UUID so the SAME id is used across turns — this
+ *   adapter just picks the right flag for it.
+ *
+ * Purity (§Load-bearing invariants #1): input = argv + env + prompt;
+ * output = text + session id. No direct network, no direct CAP calls.
+ *
+ * Test seam: `ctx._spawnImpl` is the sanctioned way for any adapter in this
+ * codebase to swap `child_process.spawn` out for a mock. Unit tests pass a
+ * fake that returns an EventEmitter; production never sets `_spawnImpl` so
+ * the default `childSpawn` is used. Future adapters should follow the same
+ * convention rather than inventing their own seam.
+ *
+ * Timeout caveat: we SIGTERM at `timeoutMs` and wait for `close`. If claude
+ * ignores SIGTERM the promise never resolves — the run loop stalls silently.
+ * SIGKILL escalation is a post-v1 concern (ADR-005 §Spawning semantics).
+ */
+
+import { spawn as childSpawn, spawnSync } from 'child_process';
+import { randomUUID } from 'crypto';
+import { mkdir, writeFile } from 'fs/promises';
+import { join } from 'path';
+
+import { linkSkills } from '../environment.js';
+import { wrapArgvWithBwrap } from '../sandbox/bwrap.js';
+
+// See codex.js for the rationale on bumping the default + env override.
+// Keeping both adapters in lockstep so any wrapper agent runtime has the
+// same timeout posture regardless of which CLI is underneath.
+const DEFAULT_TIMEOUT_MS = (() => {
+  const fallback = 15 * 60 * 1000;
+  const raw = process.env.COMMONLY_AGENT_RUN_TIMEOUT_MS;
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+})();
+
+const buildPrompt = (prompt, memoryLongTerm) => {
+  if (!memoryLongTerm) return prompt;
+  return `=== Context (your persistent memory) ===\n${memoryLongTerm}\n=== Current turn ===\n${prompt}`;
+};
+
+const runClaude = ({ cmd, args, cwd, env, timeoutMs, spawnImpl = childSpawn }) => new Promise((resolve, reject) => {
+  const proc = spawnImpl(cmd, args, { cwd, env });
+  let stdout = '';
+  let stderr = '';
+  let timedOut = false;
+
+  const timer = setTimeout(() => {
+    timedOut = true;
+    proc.kill('SIGTERM');
+  }, timeoutMs);
+
+  proc.stdout?.on('data', (chunk) => { stdout += chunk.toString(); });
+  proc.stderr?.on('data', (chunk) => { stderr += chunk.toString(); });
+  proc.on('error', (err) => {
+    clearTimeout(timer);
+    reject(err);
+  });
+  proc.on('close', (code) => {
+    clearTimeout(timer);
+    if (timedOut) return reject(new Error(`claude timed out after ${timeoutMs}ms`));
+    if (code !== 0) return reject(new Error(`claude exited with code ${code}: ${stderr.trim()}`));
+    resolve(stdout);
+  });
+});
+
+// ── MCP config write — claude consumes this via --mcp-config <path> ─────────
+
+// Substitute Commonly-supplied placeholders in MCP env values, command args,
+// and URLs so users don't have to hand-paste secrets into their env file
+// every time they re-attach. Surfaced during the 2026-04-17 cross-agent demo:
+// every spec referencing commonly-mcp had to be rewritten with the agent's
+// runtime token after attach, because the token is minted at attach time and
+// only known to the wrapper.
+//
+// Recognised placeholders (substituted everywhere a string appears in the
+// MCP config):
+//   ${COMMONLY_AGENT_TOKEN}   — the per-(agent, pod) cm_agent_* runtime token
+//   ${COMMONLY_API_URL}       — the instance URL the agent is attached to
+//   ${COMMONLY_INSTANCE_URL}  — alias for COMMONLY_API_URL (clearer in context)
+//
+// Substitution is one-pass + literal — no nested expansion, no shell quoting.
+// Unknown placeholders are left intact so the user sees a clear runtime error
+// from the MCP server rather than a silent empty string.
+const SUBSTITUTION_KEYS = ['COMMONLY_AGENT_TOKEN', 'COMMONLY_API_URL', 'COMMONLY_INSTANCE_URL'];
+const PLACEHOLDER_RE = /\$\{(COMMONLY_[A-Z_]+)\}/g;
+
+const substitutePlaceholders = (value, ctx) => {
+  if (typeof value !== 'string') return value;
+  if (!value.includes('${COMMONLY_')) return value;
+  const subs = {
+    COMMONLY_AGENT_TOKEN: ctx.runtimeToken || '',
+    COMMONLY_API_URL: ctx.instanceUrl || '',
+    COMMONLY_INSTANCE_URL: ctx.instanceUrl || '',
+  };
+  return value.replace(PLACEHOLDER_RE, (whole, key) => (
+    SUBSTITUTION_KEYS.includes(key) && subs[key] ? subs[key] : whole
+  ));
+};
+
+const buildMcpConfig = (mcpServers, ctx = {}) => {
+  // Shape: `{ mcpServers: { <name>: { ... } } }` — the standard MCP client
+  // config, which claude's `--mcp-config` reads directly.
+  const mcpServersMap = {};
+  for (const server of mcpServers) {
+    const entry = { type: server.transport || 'stdio' };
+    if (server.url) entry.url = substitutePlaceholders(server.url, ctx);
+    if (server.command) {
+      const [command, ...args] = server.command;
+      entry.command = command;
+      if (args.length) entry.args = args.map((a) => substitutePlaceholders(a, ctx));
+    }
+    if (server.env) {
+      entry.env = {};
+      for (const [k, v] of Object.entries(server.env)) {
+        entry.env[k] = substitutePlaceholders(v, ctx);
+      }
+    }
+    mcpServersMap[server.name] = entry;
+  }
+  return { mcpServers: mcpServersMap };
+};
+
+// Regenerated on every spawn from the env spec; do not hand-edit — the file
+// is overwritten before each `claude` invocation, so any local changes are
+// silently clobbered. ADR-008 §invariant #5 (edits propagate on next spawn).
+const writeMcpConfig = async (cwd, mcpServers, ctx = {}) => {
+  const dir = join(cwd, '.commonly');
+  await mkdir(dir, { recursive: true });
+  const file = join(dir, 'mcp-config.json');
+  await writeFile(file, JSON.stringify(buildMcpConfig(mcpServers, ctx), null, 2), 'utf8');
+  return file;
+};
+
+// ── argv preparation — environment-aware ────────────────────────────────────
+
+// Resolve the absolute path of `claude` so bwrap's execvp doesn't depend on
+// PATH being correctly populated inside the sandbox namespace. Surfaced live
+// during the 2026-04-17 demo validation: bwrap silently inherits parent
+// PATH but cannot reach the user's `~/.local/bin` without an absolute path
+// argv[0], even when that directory is bound read-only into the sandbox.
+const resolveClaudePath = () => {
+  // Defensive: spawnSync can return undefined under aggressive mocks (the
+  // adapters.claude.environment.test.mjs suite stubs child_process so no real
+  // process runs). Treat any failure mode as "use the bare command name."
+  let which;
+  try { which = spawnSync('which', ['claude'], { encoding: 'utf8' }); } catch { /* ignore */ }
+  if (which && which.status === 0) {
+    const p = (which.stdout || '').trim();
+    if (p) return p;
+  }
+  return 'claude';
+};
+
+const prepareArgv = async (innerArgv, ctx) => {
+  const env = ctx.environment;
+  if (!env) return { cmd: 'claude', args: innerArgv };
+
+  if (Array.isArray(env.mcp) && env.mcp.length > 0 && ctx.cwd) {
+    const configPath = await writeMcpConfig(ctx.cwd, env.mcp, {
+      runtimeToken: ctx.runtimeToken,
+      instanceUrl: ctx.instanceUrl,
+    });
+    // Insert --mcp-config immediately after the subcommand-style `-p` block
+    // so claude parses it before prompt collection begins.
+    innerArgv = [...innerArgv, '--mcp-config', configPath];
+    // Pre-approve every MCP tool from the declared servers (`mcp__<name>__*`).
+    // Without this claude runs in non-interactive `-p` mode and asks for
+    // permission before invoking any MCP tool — the wrapper has no way to
+    // approve, so the model just narrates the request and bails. The user
+    // already opted into these servers by declaring them in the env spec, so
+    // auto-allowing the corresponding tool prefix is the honest default.
+    // Surfaced live during the 2026-04-17 cross-agent demo validation.
+    const allowedPatterns = env.mcp
+      .map((server) => server && server.name)
+      .filter(Boolean)
+      .map((name) => `mcp__${name}__*`);
+    if (allowedPatterns.length > 0) {
+      innerArgv = [...innerArgv, '--allowedTools', ...allowedPatterns];
+    }
+  }
+
+  const sandboxMode = env.sandbox?.mode;
+  if (sandboxMode === 'bwrap') {
+    const claudeBin = resolveClaudePath();
+    const wrapped = wrapArgvWithBwrap([claudeBin, ...innerArgv], env, {
+      workspacePath: ctx.cwd,
+    });
+    return { cmd: wrapped[0], args: wrapped.slice(1) };
+  }
+
+  return { cmd: 'claude', args: innerArgv };
+};
+
+export default {
+  name: 'claude',
+  // Identity-bearing runtime tag written into AgentInstallation.config.runtime
+  // by `commonly agent attach`. The CLI command stays `commonly agent attach
+  // claude` (ergonomic) but the persisted runtimeType matches AGENT_TYPES so
+  // the inspector + API can classify it as the same thing as cloud Claude
+  // Code. Pair with `host: 'byo'` (set in agent.js) to disambiguate from the
+  // hosted variant.
+  runtimeType: 'claude-code',
+
+  async detect() {
+    try {
+      const res = spawnSync('claude', ['--version'], { encoding: 'utf8' });
+      if (res.error || res.status !== 0) return null;
+      // `claude --version` prints e.g. "2.5.1 (Claude Code)" — first token is enough
+      const version = (res.stdout || '').trim().split(/\s+/)[0] || 'unknown';
+      // Best-effort resolve of the binary path for clearer UX ("claude detected
+      // at /usr/local/bin/claude"). Falls back to the bare command name on
+      // platforms without `which` (e.g. Windows).
+      const where = spawnSync('which', ['claude'], { encoding: 'utf8' });
+      const path = where.status === 0 ? (where.stdout || '').trim() || 'claude' : 'claude';
+      return { path, version };
+    } catch {
+      return null;
+    }
+  },
+
+  async spawn(prompt, ctx = {}) {
+    const isResume = !!ctx.sessionId;
+    const sessionId = ctx.sessionId || randomUUID();
+    const fullPrompt = buildPrompt(prompt, ctx.memoryLongTerm || '');
+    const sessionFlag = isResume ? '--resume' : '--session-id';
+    const baseArgs = ['-p', fullPrompt, '--output-format', 'text', sessionFlag, sessionId];
+
+    if (ctx.environment && ctx.cwd) {
+      const skills = await linkSkills(ctx.environment, ctx.cwd);
+      if (skills.conflicted.length > 0) {
+        for (const c of skills.conflicted) {
+          // eslint-disable-next-line no-console
+          console.warn(`[claude] skill not linked (${c.reason}): ${c.path}`);
+        }
+      }
+      if (ctx.onSkillsLinked) ctx.onSkillsLinked(skills);
+    }
+
+    const { cmd, args } = await prepareArgv(baseArgs, ctx);
+
+    try {
+      const stdout = await runClaude({
+        cmd,
+        args,
+        cwd: ctx.cwd,
+        env: ctx.env,
+        timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
+        spawnImpl: ctx._spawnImpl, // test seam only — do not use in production
+      });
+      return { text: stdout.trim(), newSessionId: sessionId };
+    } catch (err) {
+      // Self-heal against a corrupted session store. If the persisted id is
+      // already in use (or claude has forgotten about it), discard it and
+      // restart the turn with a fresh UUID. Without this, a single bad
+      // session id poisons every subsequent event re-delivery.
+      if (isResume && /already in use|no conversation|no session/i.test(String(err.message))) {
+        const freshId = randomUUID();
+        const retryBase = ['-p', fullPrompt, '--output-format', 'text', '--session-id', freshId];
+        const retry = await prepareArgv(retryBase, ctx);
+        const stdout = await runClaude({
+          cmd: retry.cmd,
+          args: retry.args,
+          cwd: ctx.cwd,
+          env: ctx.env,
+          timeoutMs: ctx.timeoutMs || DEFAULT_TIMEOUT_MS,
+          spawnImpl: ctx._spawnImpl,
+        });
+        return { text: stdout.trim(), newSessionId: freshId };
+      }
+      throw err;
+    }
+  },
+};