@supercollab/cli 0.4.2 → 0.4.3

package/README.md

@@ -12,9 +12,23 @@ Install:
 
 ```bash
 npm install -g @supercollab/cli
+supercollab
 ```
 
-Create an account and local agent:
+Running `supercollab` opens the guided setup flow. It detects your OS/CPU/Node
+runtime, verifies native SQLite and sqlite-vec, downloads and warms the BGE model
+locally, writes the selected local engine into `~/.supercollab/config.json`,
+creates or logs into your account, registers the local agent, creates or joins a
+room, activates a project directory, and prints MCP config.
+
+You can also run the checks directly:
+
+```bash
+supercollab doctor
+supercollab doctor --json
+```
+
+Manual account setup:
 
 ```bash
 supercollab register --username your_name
@@ -83,8 +97,8 @@ hybrid: reciprocal-rank fusion over keyword and vector results
 ```
 
 The hosted SuperCollab service never computes embeddings and never receives the
-room key. The first local sync/search may download the BGE-small ONNX model into
-the local Hugging Face cache. To verify or prewarm the local embedding system:
+room key. Guided setup downloads and verifies the BGE-small ONNX model into the
+local Hugging Face cache. To verify or prewarm the local embedding system:
 
 ```bash
 supercollab embeddings status

package/bin/supercollab.js

@@ -3,10 +3,11 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 import * as readlineCore from 'node:readline';
 import { stdin as input, stdout as output } from 'node:process';
 
-const VERSION = '0.4.2';
+const VERSION = '0.4.3';
 const DEFAULT_SERVER = process.env.SUPERCOLLAB_URL || 'https://hyper.polynode.dev';
 const DEFAULT_CONFIG = process.env.SUPERCOLLAB_CONFIG || path.join(os.homedir(), '.supercollab', 'config.json');
 const SESSION_TTL_SKEW = 60;
@@ -33,6 +34,8 @@ function printHelp() {
   console.log(`SuperCollab CLI ${VERSION}
 
 Usage:
+  supercollab setup
+  supercollab doctor [--json] [--skip-model]
   supercollab register --username NAME [--password PASS] [--label LABEL]
   supercollab login --username NAME [--password PASS]
   supercollab whoami
@@ -65,6 +68,7 @@ Options:
 Environment:
   SUPERCOLLAB_PASSWORD can provide password non-interactively.
   SUPERCOLLAB_CONFIG can override config path.
+  SUPERCOLLAB_MODEL_CACHE can override the local Hugging Face model cache.
   SUPERCOLLAB_WORKDIR sets the local workspace directory for MCP activation checks.
 `);
 }
@@ -363,6 +367,78 @@ async function doLogin(config, file, opts) {
   return { ok: true, username: config.username, user_id: config.userId, config: file };
 }
 
+function commandExists(command, args = ['--version']) {
+  const result = spawnSync(command, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+  return {
+    ok: result.status === 0,
+    command,
+    status: result.status,
+    output: String(result.stdout || result.stderr || '').trim().split('\n')[0] || '',
+  };
+}
+
+function installAdvice(profile, checks = {}) {
+  const advice = [];
+  const platform = profile.platform;
+  if (!checks.node_supported?.ok) {
+    advice.push('Install Node.js 20 LTS or newer, then reinstall @supercollab/cli.');
+  }
+  if (!checks.native_sqlite_vec?.ok) {
+    if (profile.tools?.npm_ignore_scripts?.output === 'true') {
+      advice.push('Your npm config has `ignore-scripts=true`, which prevents native SQLite from installing. Run `npm config set ignore-scripts false`, then reinstall or run `npm rebuild -g better-sqlite3 --ignore-scripts=false`.');
+    }
+    if (platform === 'darwin') {
+      advice.push('Install Apple command line tools with `xcode-select --install`, then run `npm rebuild -g better-sqlite3`.');
+    } else if (platform === 'linux') {
+      advice.push('Install Python 3, make, and a C/C++ compiler, then run `npm rebuild -g better-sqlite3`.');
+    } else if (platform === 'win32') {
+      advice.push('Install Microsoft Visual Studio Build Tools with the C++ workload and Python, then run `npm rebuild -g better-sqlite3`.');
+    } else {
+      advice.push('Install a native build toolchain for your OS, then run `npm rebuild -g better-sqlite3`.');
+    }
+  }
+  if (!checks.bge_model?.ok && checks.bge_model?.error) {
+    advice.push('Check internet access to Hugging Face model downloads, then run `supercollab embeddings warmup`.');
+  }
+  return advice;
+}
+
+function detectSystemProfile() {
+  const cpus = os.cpus() || [];
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  const tools = {
+    npm: commandExists('npm', ['--version']),
+    npm_ignore_scripts: commandExists('npm', ['config', 'get', 'ignore-scripts']),
+  };
+  if (process.platform === 'darwin') {
+    tools.xcode_select = commandExists('xcode-select', ['-p']);
+    tools.clang = commandExists('clang', ['--version']);
+  } else if (process.platform === 'linux') {
+    tools.python3 = commandExists('python3', ['--version']);
+    tools.make = commandExists('make', ['--version']);
+    tools.cc = commandExists('cc', ['--version']);
+    tools.gpp = commandExists('g++', ['--version']);
+  } else if (process.platform === 'win32') {
+    tools.python = commandExists('python', ['--version']);
+    tools.node_gyp = commandExists('node-gyp', ['--version']);
+  }
+  return {
+    detected_at: nowIso(),
+    cli_version: VERSION,
+    platform: process.platform,
+    arch: process.arch,
+    os_type: os.type(),
+    os_release: os.release(),
+    hostname: os.hostname(),
+    node: process.versions.node,
+    node_modules_abi: process.versions.modules,
+    node_supported: nodeMajor >= 20,
+    cpu_model: cpus[0]?.model || null,
+    cpu_count: cpus.length,
+    tools,
+  };
+}
+
 let nativeSqlitePromise = null;
 
 async function loadNativeSqlite() {
@@ -1094,14 +1170,14 @@ async function runMcp(opts) {
 
 function printCodexConfig(opts) {
   const file = configPath(opts);
-  console.log(`[mcp_servers.supercollab]\ncommand = "supercollab"\nargs = ["mcp", "stdio", "--config", "${file.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"]`);
+  console.log(mcpConfigText(String(opts.client || 'codex'), file));
 }
 
 async function embeddingStatus() {
   return {
     ok: true,
     profile: EMBEDDING_PROFILE,
-    model_download: 'lazy on first embedding, or now via `supercollab embeddings warmup`',
+    model_download: 'installed during setup, or manually via `supercollab embeddings warmup`',
     cache_dir: process.env.SUPERCOLLAB_MODEL_CACHE || 'default @huggingface/transformers cache',
   };
 }
@@ -1115,14 +1191,344 @@ async function embeddingWarmup() {
   };
 }
 
+async function nativeEngineCheck() {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'supercollab-doctor-'));
+  const dbPath = path.join(tempDir, 'native.sqlite');
+  let db = null;
+  try {
+    const { Database, sqliteVec } = await loadNativeSqlite();
+    db = new Database(dbPath);
+    sqliteVec.load(db);
+    const version = db.prepare('SELECT vec_version() AS version').get()?.version;
+    db.exec(`CREATE VIRTUAL TABLE vec_check USING vec0(id TEXT PRIMARY KEY, embedding float[${EMBEDDING_DIMS}] distance_metric=cosine)`);
+    db.prepare('INSERT INTO vec_check(id, embedding) VALUES(?, ?)').run('ok', new Float32Array(new Array(EMBEDDING_DIMS).fill(0).map((_, i) => i === 0 ? 1 : 0)));
+    const rows = db.prepare('SELECT id, distance FROM vec_check WHERE embedding MATCH ? AND k = 1').all(new Float32Array(new Array(EMBEDDING_DIMS).fill(0).map((_, i) => i === 0 ? 1 : 0)));
+    if (rows[0]?.id !== 'ok') throw new Error('sqlite-vec query did not return expected row');
+    return {
+      ok: true,
+      engine: 'native-sqlite-vec',
+      sqlite_vec_version: version,
+      dims: EMBEDDING_DIMS,
+    };
+  } catch (err) {
+    return {
+      ok: false,
+      engine: 'native-sqlite-vec',
+      error: err.message || String(err),
+    };
+  } finally {
+    try { db?.close(); } catch {}
+    try { fs.rmSync(tempDir, { recursive: true, force: true }); } catch {}
+  }
+}
+
+async function runDoctor(config, file, opts = {}) {
+  const profile = detectSystemProfile();
+  const checks = {
+    node_supported: {
+      ok: profile.node_supported,
+      version: profile.node,
+      required: '>=20',
+    },
+    native_sqlite_vec: await nativeEngineCheck(),
+  };
+
+  if (!opts['skip-model']) {
+    try {
+      const warmed = await embeddingWarmup();
+      checks.bge_model = {
+        ok: warmed.ok && warmed.dims === EMBEDDING_DIMS,
+        dims: warmed.dims,
+        profile: EMBEDDING_PROFILE,
+        cache_dir: process.env.SUPERCOLLAB_MODEL_CACHE || 'default @huggingface/transformers cache',
+      };
+    } catch (err) {
+      checks.bge_model = {
+        ok: false,
+        profile: EMBEDDING_PROFILE,
+        error: err.message || String(err),
+      };
+    }
+  } else {
+    checks.bge_model = {
+      ok: null,
+      skipped: true,
+      profile: EMBEDDING_PROFILE,
+    };
+  }
+
+  const ok = checks.node_supported.ok && checks.native_sqlite_vec.ok && (checks.bge_model.ok === true || checks.bge_model.skipped === true);
+  const result = {
+    ok,
+    checked_at: nowIso(),
+    system: profile,
+    checks,
+    local_engine: {
+      id: 'native-sqlite-vec',
+      transcript_store: 'better-sqlite3',
+      vector_store: 'sqlite-vec',
+      vector_version: checks.native_sqlite_vec.sqlite_vec_version || null,
+      embedding_profile_id: EMBEDDING_PROFILE.id,
+    },
+    advice: installAdvice(profile, checks),
+  };
+
+  config.systemProfile = profile;
+  config.localEngine = result.local_engine;
+  config.embeddingProfile = EMBEDDING_PROFILE;
+  config.setupChecks = {
+    ok,
+    checked_at: result.checked_at,
+    checks,
+    advice: result.advice,
+  };
+  saveConfig(config, file);
+  return result;
+}
+
+function printDoctor(result) {
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function loadPrompts() {
+  return import('@clack/prompts');
+}
+
+function isConfigured(config) {
+  return Boolean(config.userToken && config.agentId && config.agentPrivateKeyPem);
+}
+
+function promptRequired(value) {
+  return String(value || '').trim() ? undefined : 'Required';
+}
+
+async function ensureAgentForSetup(config, file, prompts) {
+  if (config.agentId && config.agentPrivateKeyPem) return null;
+  const label = await prompts.text({
+    message: 'Name this local agent',
+    placeholder: `${os.hostname()}-agent`,
+    defaultValue: `${os.hostname()}-agent`,
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(label)) throw new Error('cancelled');
+  const agent = await registerAgent(config, String(label));
+  saveConfig(config, file);
+  return agent;
+}
+
+async function runAuthSetup(config, file, prompts) {
+  if (isConfigured(config)) {
+    const reuse = await prompts.confirm({
+      message: `Use existing login as ${config.username || 'current user'}?`,
+      initialValue: true,
+    });
+    if (prompts.isCancel(reuse)) throw new Error('cancelled');
+    if (reuse) return { reused: true };
+  }
+
+  const mode = await prompts.select({
+    message: 'Account setup',
+    options: [
+      { value: 'register', label: 'Create account', hint: 'new SuperCollab username' },
+      { value: 'login', label: 'Log in', hint: 'existing username' },
+    ],
+  });
+  if (prompts.isCancel(mode)) throw new Error('cancelled');
+
+  const username = await prompts.text({
+    message: mode === 'register' ? 'Choose a username' : 'Username',
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(username)) throw new Error('cancelled');
+
+  const pass = await prompts.password({
+    message: mode === 'register' ? 'Choose a password' : 'Password',
+    validate: (value) => String(value || '').length >= 8 ? undefined : 'Use at least 8 characters',
+  });
+  if (prompts.isCancel(pass)) throw new Error('cancelled');
+
+  if (mode === 'register') {
+    return doRegister(config, file, { username: String(username), password: String(pass), label: `${os.hostname()}-agent` });
+  }
+
+  const login = await doLogin(config, file, { username: String(username), password: String(pass) });
+  const agent = await ensureAgentForSetup(config, file, prompts);
+  return { ...login, agent_id: agent?.agent_id || config.agentId, fingerprint: agent?.fingerprint || config.agentFingerprint };
+}
+
+async function runRoomSetup(config, file, prompts) {
+  const choice = await prompts.select({
+    message: 'Room setup',
+    options: [
+      { value: 'create', label: 'Create a new room', hint: 'start solo or invite agents later' },
+      { value: 'join', label: 'Join with private invite', hint: 'paste sci_...sck_...' },
+      { value: 'skip', label: 'Skip for now', hint: 'set up auth and local engine only' },
+    ],
+  });
+  if (prompts.isCancel(choice)) throw new Error('cancelled');
+  if (choice === 'skip') return null;
+
+  if (choice === 'join') {
+    const invite = await prompts.text({
+      message: 'Paste private invite',
+      placeholder: 'sci_....sck_...',
+      validate: promptRequired,
+    });
+    if (prompts.isCancel(invite)) throw new Error('cancelled');
+    const joined = await doRoomJoin(config, file, { invite: String(invite).trim() });
+    return { room_id: joined.room_id || joined.workspace_id, joined };
+  }
+
+  const title = await prompts.text({
+    message: 'Room title',
+    placeholder: 'Launch Room',
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(title)) throw new Error('cancelled');
+  const goal = await prompts.text({
+    message: 'Room goal',
+    placeholder: 'Coordinate agents on this project',
+    validate: promptRequired,
+  });
+  if (prompts.isCancel(goal)) throw new Error('cancelled');
+  const created = await doRoomCreate(config, file, { title: String(title), goal: String(goal) });
+  return { room_id: created.room_id || created.id, created };
+}
+
+async function runActivationSetup(config, file, roomId, prompts) {
+  if (!roomId) return null;
+  const shouldActivate = await prompts.confirm({
+    message: 'Activate SuperCollab for a local project directory now?',
+    initialValue: true,
+  });
+  if (prompts.isCancel(shouldActivate)) throw new Error('cancelled');
+  if (!shouldActivate) return null;
+  const cwd = await prompts.text({
+    message: 'Project directory',
+    defaultValue: process.cwd(),
+    placeholder: process.cwd(),
+    validate: (value) => {
+      const resolved = path.resolve(String(value || ''));
+      return fs.existsSync(resolved) ? undefined : 'Directory does not exist';
+    },
+  });
+  if (prompts.isCancel(cwd)) throw new Error('cancelled');
+  return activate(config, file, { room: roomId, cwd: String(cwd) });
+}
+
+async function runSetupSmoke(config, file, roomId, prompts) {
+  if (!roomId) return null;
+  const shouldSmoke = await prompts.confirm({
+    message: 'Send a setup note and verify local BGE search?',
+    initialValue: true,
+  });
+  if (prompts.isCancel(shouldSmoke)) throw new Error('cancelled');
+  if (!shouldSmoke) return null;
+  const marker = `setup-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
+  const text = `SuperCollab setup complete on ${os.hostname()} (${marker})`;
+  await doChatSend(config, file, { room: roomId, text, channel: 'agents', kind: 'setup.note' });
+  const search = await doChatSearch(config, file, { room: roomId, query: marker, mode: 'hybrid', limit: 5 });
+  return {
+    ok: search.results.some((row) => String(row.body || '').includes(marker)),
+    marker,
+    search_count: search.results.length,
+  };
+}
+
+function mcpConfigText(client, file) {
+  const escaped = file.replaceAll('\\', '\\\\').replaceAll('"', '\\"');
+  if (client === 'claude') {
+    return JSON.stringify({
+      mcpServers: {
+        supercollab: {
+          command: 'supercollab',
+          args: ['mcp', 'stdio', '--config', file],
+        },
+      },
+    }, null, 2);
+  }
+  if (client === 'codex') {
+    return `[mcp_servers.supercollab]\ncommand = "supercollab"\nargs = ["mcp", "stdio", "--config", "${escaped}"]`;
+  }
+  return `supercollab mcp stdio --config "${escaped}"`;
+}
+
+async function runSetupWizard(config, file, opts = {}) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    throw new Error('interactive setup requires a TTY; run `supercollab doctor --json` for non-interactive diagnostics');
+  }
+  const prompts = await loadPrompts();
+  prompts.intro(`SuperCollab ${VERSION}`);
+  try {
+    const spin = prompts.spinner();
+    spin.start('Checking this machine and installing the local BGE model');
+    const doctor = await runDoctor(config, file, {});
+    if (doctor.ok) {
+      spin.stop(`Local engine ready: ${doctor.local_engine.id}, ${doctor.local_engine.vector_version || 'sqlite-vec'}`);
+    } else {
+      spin.stop('Local engine check needs attention');
+      for (const line of doctor.advice || []) prompts.note(line, 'Fix');
+      const cont = await prompts.confirm({ message: 'Continue setup anyway?', initialValue: false });
+      if (prompts.isCancel(cont) || !cont) throw new Error('cancelled');
+    }
+
+    await runAuthSetup(config, file, prompts);
+    const room = await runRoomSetup(config, file, prompts);
+    const roomId = room?.room_id || null;
+    const activation = await runActivationSetup(config, file, roomId, prompts);
+    const smoke = await runSetupSmoke(config, file, roomId, prompts);
+
+    const client = await prompts.select({
+      message: 'MCP client config',
+      options: [
+        { value: 'codex', label: 'Codex', hint: 'TOML config snippet' },
+        { value: 'claude', label: 'Claude', hint: 'JSON config snippet' },
+        { value: 'manual', label: 'Manual', hint: 'stdio command' },
+        { value: 'skip', label: 'Skip', hint: 'show later with mcp print-config' },
+      ],
+    });
+    if (prompts.isCancel(client)) throw new Error('cancelled');
+
+    config.onboarding = {
+      completed_at: nowIso(),
+      cli_version: VERSION,
+      room_id: roomId,
+      activation_root: activation?.cwd || null,
+      smoke,
+    };
+    saveConfig(config, file);
+
+    if (client !== 'skip') {
+      prompts.note(mcpConfigText(client, file), `${client} MCP config`);
+    }
+    prompts.outro(`Ready. Config saved at ${file}`);
+    return { ok: true, room_id: roomId, activation, smoke, config: file };
+  } catch (err) {
+    prompts.cancel(err.message === 'cancelled' ? 'Setup cancelled.' : `Setup stopped: ${err.message}`);
+    throw err;
+  }
+}
+
 async function main() {
   const { positionals, opts } = parse(process.argv.slice(2));
-  if (opts.help || positionals.length === 0) { printHelp(); return; }
+  if (opts.help) { printHelp(); return; }
   const [cmd, sub] = positionals;
   const file = configPath(opts);
   const config = attachRuntimeConfig(loadConfig(file), file);
   config.serverUrl = opts.server || config.serverUrl || DEFAULT_SERVER;
 
+  if (positionals.length === 0) {
+    if (process.stdin.isTTY && process.stdout.isTTY) return runSetupWizard(config, file, opts);
+    printHelp();
+    return;
+  }
+  if (cmd === 'setup') return runSetupWizard(config, file, opts);
+  if (cmd === 'doctor') {
+    const data = await runDoctor(config, file, opts);
+    if (opts.json) return console.log(JSON.stringify(data, null, 2));
+    printDoctor(data);
+    return;
+  }
   if (cmd === 'register') return console.log(JSON.stringify(await doRegister(config, file, opts), null, 2));
   if (cmd === 'login') return console.log(JSON.stringify(await doLogin(config, file, opts), null, 2));
   if (cmd === 'whoami') return console.log(JSON.stringify(await api(config, 'GET', '/v1/me'), null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supercollab/cli",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "SuperCollab CLI and MCP bridge for encrypted local-search agent group chat.",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "@clack/prompts": "0.11.0",
     "@huggingface/transformers": "3.8.1",
     "better-sqlite3": "12.11.1",
     "sqlite-vec": "0.1.9"