@ravefox/space 0.0.0-stage → 0.2.0

package/src/commands/verify.js

@@ -0,0 +1,48 @@
+/** Repository verification entry point; scenario implementations live in backend. */
+import { existsSync } from 'fs';
+import { resolve, join } from 'path';
+import { spawnSync } from 'child_process';
+
+export const SCENARIOS = {
+  wave1: '__tests__/service/verify.wave1.test.js',
+  'connector-grant': '__tests__/service/verify.connectorGrant.test.js',
+};
+const testDatabase = (name) => /^(test|verify)([-_0-9]|$)|[-_]test$/.test(name || '');
+
+export const verificationPlan = (scenario, repo, env = process.env) => {
+  const suite = SCENARIOS[scenario];
+  if (!suite) throw new Error(`Unknown scenario: ${scenario}. Choose ${Object.keys(SCENARIOS).join(', ')}.`);
+  let mongoDatabase = '';
+  // MongoDB authorities can contain comma-separated seed hosts, unlike WHATWG URLs.
+  const mongoPath = /^mongodb(?:\+srv)?:\/\/[^/?#]+\/([^?#]*)/.exec(env.MONGO_URI || '');
+  try { mongoDatabase = decodeURIComponent(mongoPath?.[1] || ''); } catch { /* refused below */ }
+  if (!env.PG_HOST || !testDatabase(env.PG_DATABASE) || !testDatabase(mongoDatabase)) {
+    throw new Error('Set MONGO_URI, PG_HOST and PG_DATABASE to dedicated test/verify databases. Fixture setup clears their data.');
+  }
+  const cwd = resolve(repo, 'backend');
+  const runner = join(cwd, 'node_modules/jest/bin/jest.js');
+  if (!existsSync(join(cwd, suite)) || !existsSync(runner)) {
+    throw new Error('Use --repo with a Space checkout containing the scenario and installed backend dependencies.');
+  }
+  return { command: process.execPath, args: [runner, '--runInBand', '--forceExit', '--runTestsByPath', suite,
+    ...(env.COMMONLY_VERIFY_CACHE_DIR ? ['--cacheDirectory', env.COMMONLY_VERIFY_CACHE_DIR] : [])],
+    options: { cwd, stdio: 'inherit', env: { ...env, INTEGRATION_TEST: 'true' } } };
+};
+
+export const registerVerify = (program, run = spawnSync) => {
+  program.command('verify <scenario>')
+    .description(`Run shared real-HTTP scenarios against isolated test databases (${Object.keys(SCENARIOS).join(', ')})`)
+    .option('--repo <path>', 'Space checkout with backend test dependencies', process.cwd())
+    .addHelpText('after', '\nUse Node 22 and explicit MONGO_URI, PG_HOST and PG_DATABASE. Fixture databases are cleared.\nRun inside the bounded test container when available; this command does not build images or contact a live instance.\n')
+    .action((scenario, options) => {
+      try {
+        const plan = verificationPlan(scenario, options.repo);
+        const result = run(plan.command, plan.args, plan.options);
+        if (result.error) throw result.error;
+        process.exitCode = result.status === null ? 1 : result.status;
+      } catch (error) {
+        console.error(error.message);
+        process.exitCode = 1;
+      }
+    });
+};

package/src/index.js

@@ -0,0 +1,99 @@
+#!/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 { registerInbox } from './commands/inbox.js';
+import { registerAgent } from './commands/agent.js';
+import { registerDaemon } from './commands/daemon.js';
+import { registerPod } from './commands/pod.js';
+import { registerDev } from './commands/dev.js';
+import { registerVerify } from './commands/verify.js';
+import { registerDoctor } from './commands/doctor.js';
+import { registerMcp } from './commands/mcp.js';
+import { registerTask } from './commands/task.js';
+import { CLI } from './lib/cli-hint.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '../package.json'), 'utf8'));
+
+const program = new Command();
+
+program
+  .name('space')
+  .description('The Space CLI — connect agents, manage pods, iterate fast')
+  .version(pkg.version)
+  .showHelpAfterError('(run `space --help` for usage)');
+
+// Auth
+registerLogin(program);
+registerWhoami(program);
+
+// An operator account's own attention queue (explicit token file, never the
+// saved login — see cli/src/lib/inbox.js)
+registerInbox(program);
+
+// Agent management
+registerAgent(program);
+
+// Local daemon lifecycle
+registerDaemon(program);
+
+// Pod management
+registerPod(program);
+
+// Local dev environment
+registerDev(program);
+registerVerify(program);
+
+// Install health: one line per check (TASK-660)
+registerDoctor(program);
+registerMcp(program);
+
+// The task board as an agent: list, create, claim, update, close (TASK-703)
+registerTask(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:
+  $ ${CLI} login --instance https://api.commonly.me --key dev
+  $ ${CLI} agent attach claude --pod <podId> --name my-claude
+  $ ${CLI} agent run my-claude                       # Ctrl+C to stop
+  $ ${CLI} agent detach my-claude                    # clean uninstall
+  $ ${CLI} daemon register --name "My MacBook"
+  $ ${CLI} daemon status
+  $ ${CLI} doctor                                   # check Node, install, login, daemon, adapters
+  $ ${CLI} inbox list --token-file ~/.commonly/bin/ops-token   # an operator's own queue
+
+Custom Python agent:
+  $ ${CLI} agent init --language python --name research-bot --pod <podId>
+  $ python3 research-bot.py
+
+Subcommand help:
+  $ ${CLI} login --help
+  $ ${CLI} agent attach --help
+  $ ${CLI} agent run --help
+  $ ${CLI} 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/grootbro/space/blob/space/bootstrap/docs/cli/README.md
+`);
+
+program.parse(process.argv);

package/src/lib/adapter-login.js

@@ -0,0 +1,76 @@
+import { spawn } from 'child_process';
+
+// Whether each installed CLI adapter is signed in, by the exit code of its own
+// status command. A stranger on a fresh computer otherwise learns it from a
+// failed @mention ("claude exited 1: Not logged in"), after setup said all was
+// well (Growth's F370 hand walk). Only the exit code is read: the commands'
+// output, which names the account, is never captured or printed.
+//
+// Both commands exit 1 when signed out (checked 2026-11-10 under an empty HOME:
+// `claude auth status --json`, `codex login status`). opencode is left out: its
+// `auth list` was not checked, and a guessed probe would cry wolf.
+export const LOGIN_STATUS_ARGS = {
+  claude: ['auth', 'status', '--json'],
+  codex: ['login', 'status'],
+};
+
+// Credentials a seat runs on without a CLI login, so the probe is skipped.
+// codex's are the ones codexAuthKind and the proxy route accept (adapters/
+// codex.js), even though `codex login status` exits 1 with only a key set.
+const KEY_ENV = {
+  claude: ['ANTHROPIC_API_KEY'],
+  codex: ['OPENAI_API_KEY', 'CODEX_API_KEY', 'CODEX_ACCESS_TOKEN'],
+};
+const envSet = (env, name) => typeof env[name] === 'string' && env[name].trim() !== '';
+
+// Both CLIs exit exactly 1 when signed out. Any other non-zero code (2 for an
+// unknown subcommand on an old CLI) is no verdict, not "signed out".
+const SIGNED_OUT_EXIT = 1;
+
+export const signedOutHint = (name) => `${name} is installed but not signed in; run \`${name}\` once to log in before adding an agent`;
+
+/**
+ * The installed adapters that report signed out. `detect(name)` resolves truthy
+ * when the CLI is installed; `runStatus(name, args)` resolves its exit code, or
+ * null when it could not be run (timeout, spawn error), which is not a verdict.
+ */
+export const signedOutAdapters = async ({ detect, runStatus, env = process.env, names = Object.keys(LOGIN_STATUS_ARGS) }) => {
+  const out = [];
+  for (const name of names) {
+    if (!LOGIN_STATUS_ARGS[name] || (KEY_ENV[name] || []).some((key) => envSet(env, key))) continue;
+    let installed = false;
+    try { installed = Boolean(await detect(name)); } catch { /* not installed */ }
+    if (!installed) continue;
+    const code = await runStatus(name, LOGIN_STATUS_ARGS[name]).catch(() => null);
+    if (code === SIGNED_OUT_EXIT) out.push(name);
+  }
+  return out;
+};
+
+/**
+ * One harness's login, for the daemon's inventory (F458): true signed in (exit
+ * 0), false signed out (exit 1), null when there is no verdict: no checked
+ * probe for it, a key in the environment it runs on instead, or a probe that
+ * couldn't run. Only the exit code is read, as above.
+ */
+export const loginState = async (name, { runStatus = runLoginStatus, env = process.env } = {}) => {
+  if (!LOGIN_STATUS_ARGS[name] || (KEY_ENV[name] || []).some((key) => envSet(env, key))) return null;
+  const code = await runStatus(name, LOGIN_STATUS_ARGS[name]).catch(() => null);
+  if (code === 0) return true;
+  return code === SIGNED_OUT_EXIT ? false : null;
+};
+
+// The exit code of `<name> <args>`, with every stream discarded. null when it
+// cannot run or takes longer than `timeoutMs` (a CLI that opens a prompt).
+export const runLoginStatus = (name, args, { timeoutMs = 10_000, spawnFn = spawn } = {}) => new Promise((done) => {
+  let child;
+  try {
+    child = spawnFn(name, args, { stdio: 'ignore', windowsHide: true, shell: process.platform === 'win32' });
+  } catch {
+    done(null);
+    return;
+  }
+  const timer = setTimeout(() => { child.kill(); done(null); }, timeoutMs);
+  child.on('error', () => { clearTimeout(timer); done(null); });
+  child.on('exit', (code) => { clearTimeout(timer); done(typeof code === 'number' ? code : null); });
+});

package/src/lib/adapters/broker-bridge-entry.js

@@ -0,0 +1,76 @@
+/**
+ * The stdio server a harness runs to reach the grant broker (F175b, F175d).
+ *
+ * Codex, Qwen and Goose can't hold the broker's bearer token in an HTTP entry
+ * without putting it somewhere the rule forbids: Codex reads it from an env
+ * var, Qwen sends `--mcp-config` headers literally, and Goose fills a header
+ * from its own environment or a literal in the recipe (measured on Qwen 0.26.2
+ * and Goose 1.54.0). So each runs our bridge (codex-broker-bridge.mjs), told
+ * the broker's url, its headers as templates and the path of this spawn's
+ * credential file. None of those is a secret. The token stays in that one file,
+ * and the bridge reads it for each request.
+ *
+ * Whether a seat may hold the broker at all was decided before the adapter
+ * (grant-broker-guard.js). This decides whether THIS entry can be wired, and a
+ * command the entry declares is never run.
+ */
+import {
+  BRIDGE_HEADERS_VAR, BRIDGE_PATH, BRIDGE_URL_VAR, CREDENTIAL_FILE_VAR,
+} from './codex-broker-bridge.mjs';
+
+// A server name becomes a config key or a tool-name prefix.
+export const SERVER_NAME = /^[A-Za-z0-9_-]+$/;
+// What fetch accepts in a header: Latin-1, no CR, LF or NUL.
+// eslint-disable-next-line no-control-regex
+const HEADER_TEXT = /^[^\r\n\0Ā-￿]*$/;
+const INSTANCE_PLACEHOLDER = /\$\{(?:COMMONLY_API_URL|COMMONLY_INSTANCE_URL)\}/g;
+
+/**
+ * `{ command, args, env, readPath }`, or `{ skip }` with why it can't be wired.
+ * `readPath` is the one file a jailed seat must be able to read: the bridge
+ * imports node builtins only.
+ */
+export const brokerBridgeEntry = (server, { instanceUrl, credentialFile, runtimeToken } = {}) => {
+  if (!SERVER_NAME.test(server?.name || '')) return { skip: 'its name is not a plain config key' };
+  if (!credentialFile) return { skip: 'there is no seat credential to read' };
+  // Resolve the instance placeholders only: the token placeholder stays in the
+  // header template and is filled by the bridge from the file.
+  const resolve = (value) => String(value).replace(INSTANCE_PLACEHOLDER, (whole) => instanceUrl || whole);
+  const resolvedUrl = resolve(server.url);
+  const headers = Object.fromEntries(Object.entries(server.headers || {})
+    .map(([name, value]) => [String(name), resolve(String(value))]));
+  const carriesToken = (value) => !!runtimeToken && value.includes(runtimeToken);
+  if (carriesToken(resolvedUrl)
+    || Object.entries(headers).some(([name, value]) => carriesToken(name) || carriesToken(value))) {
+    return { skip: 'the entry holds the seat token as a literal, which would ride a config' };
+  }
+  if (resolvedUrl.includes('${')) return { skip: 'its url holds a placeholder this host cannot resolve' };
+  // A header fetch would reject quotes its value in the error, and that value
+  // holds the token once the bridge fills it, so such an entry is not wired.
+  if (Object.entries(headers).some(([name, value]) => !HEADER_TEXT.test(name) || !HEADER_TEXT.test(value))) {
+    return { skip: 'a header holds a control or non-Latin-1 character' };
+  }
+  // The url the guard judged (isOurGrantBroker) is normalised: resolved against
+  // the instance, with doubled slashes collapsed. The bridge fetches that same
+  // url, on the instance's own origin, or nothing.
+  let url;
+  try {
+    const instance = new URL(instanceUrl);
+    const parsed = new URL(resolvedUrl, instance);
+    if (parsed.origin !== instance.origin) return { skip: 'its url is not on this instance' };
+    parsed.pathname = parsed.pathname.replace(/\/{2,}/g, '/');
+    url = parsed.href;
+  } catch {
+    return { skip: 'its url does not resolve against this instance' };
+  }
+  return {
+    command: process.execPath,
+    args: [BRIDGE_PATH],
+    env: {
+      [BRIDGE_URL_VAR]: url,
+      [BRIDGE_HEADERS_VAR]: JSON.stringify(headers),
+      [CREDENTIAL_FILE_VAR]: credentialFile,
+    },
+    readPath: BRIDGE_PATH,
+  };
+};