swarmiq 0.2.0

package/src/index.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * index.mjs — CLI entry point for `npx swarmiq`.
+ *
+ * Usage:
+ *   npx swarmiq                      # GitHub device-flow login (default)
+ *   npx swarmiq --auth swarmiq       # Force SwarmIQ/Clerk device-flow
+ *   npx swarmiq --auth clerk         # Alias for --auth swarmiq
+ *   npx swarmiq --logout             # Remove SwarmIQ env block from ~/.claude/settings.json
+ *   npx swarmiq --help               # Show help
+ *   npx swarmiq --version            # Show version
+ *
+ * Dev invocation (no npm publish needed):
+ *   node tools/cli/src/index.mjs
+ */
+
+import { runInit } from './init.mjs';
+import { removeClaudeSettings, claudeSettingsPath } from './config.mjs';
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+swarmiq — SwarmIQ connect CLI
+
+Usage:
+  npx swarmiq                   Authenticate via GitHub (default) and configure Claude Code
+  npx swarmiq --auth swarmiq    Force SwarmIQ/Clerk device-flow instead of GitHub
+  npx swarmiq --auth clerk      Alias for --auth swarmiq
+  npx swarmiq --logout          Remove SwarmIQ settings from ~/.claude/settings.json
+
+Environment variables:
+  SWARMIQ_PROXY_URL             Override proxy base URL (default: https://api.swarmiq.dev)
+  SWARMIQ_OAUTH_URL             Override OAuth base URL  (default: https://api.swarmiq.dev)
+  SWARMIQ_CONFIG_HOME           Override config directory (default: ~/.swarmiq)
+  SWARMIQ_CLAUDE_SETTINGS_PATH  Override Claude settings path (default: ~/.claude/settings.json)
+
+What it does (GitHub flow — default):
+  1. Fetches /v1/auth/config from the SwarmIQ proxy to get the GitHub OAuth client_id.
+  2. Starts GitHub Device Flow: prints a short code and opens https://github.com/login/device.
+  3. Polls GitHub until you approve; the GitHub token is kept in memory only (never saved).
+  4. Exchanges the GitHub token for a SwarmIQ access token via POST /v1/auth/github.
+  5. Writes an env block to ~/.claude/settings.json so Claude Code routes through SwarmIQ.
+  6. Optionally stores a provider API key in the SwarmIQ Vault (BYOK).
+  7. Verifies the connection and shows 7-day savings if available.
+
+What it does (SwarmIQ flow — --auth swarmiq):
+  1. Requests a device code from the SwarmIQ auth server.
+  2. Prints a short code and opens the verification URL in your browser.
+  3. Polls until you approve access (RFC 8628 device flow).
+  4-7. Same as above.
+`);
+  process.exit(0);
+}
+
+if (args.includes('--version') || args.includes('-v')) {
+  const { readFileSync } = await import('node:fs');
+  const { fileURLToPath } = await import('node:url');
+  const { join, dirname } = await import('node:path');
+  const __dir = dirname(fileURLToPath(import.meta.url));
+  const pkg = JSON.parse(readFileSync(join(__dir, '..', 'package.json'), 'utf8'));
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (args.includes('--logout')) {
+  try {
+    removeClaudeSettings();
+    console.log(`SwarmIQ env block removed from ${claudeSettingsPath()}`);
+    console.log('Claude Code will now use its default settings.');
+  } catch (err) {
+    console.error(`swarmiq --logout failed: ${err.message}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+// Parse --auth <value>
+let authMode = null;
+const authIdx = args.indexOf('--auth');
+if (authIdx !== -1) {
+  const authValue = args[authIdx + 1];
+  if (authValue === 'swarmiq' || authValue === 'clerk') {
+    authMode = authValue;
+  } else if (!authValue || authValue.startsWith('--')) {
+    console.error(`swarmiq: --auth requires a value: swarmiq | clerk`);
+    process.exit(1);
+  } else {
+    console.error(`swarmiq: unknown --auth value "${authValue}". Use: swarmiq | clerk`);
+    process.exit(1);
+  }
+}
+
+// Main connect flow
+try {
+  await runInit({ authMode });
+} catch (err) {
+  console.error(`\nswarmiq failed: ${err.message}`);
+  process.exit(1);
+}

package/src/init.mjs

@@ -0,0 +1,501 @@
+/**
+ * init.mjs — Core connect flow, fully injectable for testing.
+ *
+ * Default flow (GitHub Device Flow):
+ *   0. GET {proxyBase}/v1/auth/config  →  {github_client_id, github_oauth_enabled}
+ *   1a. If github_client_id present AND github_oauth_enabled=true (AND --auth != swarmiq/clerk):
+ *       → GitHub Device Flow (requestGitHubDeviceCode / pollGitHubToken)
+ *       → Display user_code + verification_uri; open browser
+ *       → POST {proxyBase}/v1/auth/github with {github_access_token}  [token is memory-only]
+ *       → Receive SwarmIQ access_token + tenant_id + tier
+ *   1b. Otherwise (no client_id, github_oauth_enabled=false, or --auth swarmiq/clerk flag):
+ *       → SwarmIQ Device Flow (existing requestDeviceCode / pollDeviceToken)
+ *
+ *   2. Write ~/.claude/settings.json env block (writeClaudeSettings)
+ *   3. Offer BYOK: prompt y/N → masked key input → POST /v1/vault/provider-key
+ *   4. POST-CONNECT VERIFY: GET /health + /v1/savings/summary → print status
+ *
+ * All I/O is injected: fetch, browser opener, readline, print.
+ * Tests can run the entire flow without network calls or FS side effects outside
+ * a temp dir.
+ */
+
+import { requestDeviceCode, pollDeviceToken, OAUTH_BASE_URL } from './oauth.mjs';
+import { requestGitHubDeviceCode, pollGitHubToken } from './github_auth.mjs';
+import { storeProviderKey, fetchHealth, fetchSavings } from './api.mjs';
+import {
+  writeConfig,
+  configPath,
+  writeClaudeSettings,
+  claudeSettingsPath,
+  PROXY_BASE_URL_DEFAULT,
+} from './config.mjs';
+
+/**
+ * @typedef {object} ConnectDeps
+ * @property {Function}  openBrowser            - (url:string) => void | Promise<void>
+ * @property {Function}  requestCode            - same sig as requestDeviceCode (SwarmIQ flow)
+ * @property {Function}  pollToken              - same sig as pollDeviceToken (SwarmIQ flow)
+ * @property {Function}  requestGHCode          - same sig as requestGitHubDeviceCode
+ * @property {Function}  pollGHToken            - same sig as pollGitHubToken
+ * @property {Function}  exchangeGHToken        - (github_access_token, proxyBaseUrl, fetch) => {access_token, tenant_id, tier}
+ * @property {Function}  fetchAuthConfig        - (proxyBaseUrl, fetch) => {github_client_id, github_oauth_enabled}
+ * @property {Function}  storeKey               - same sig as storeProviderKey
+ * @property {Function}  getHealth              - same sig as fetchHealth
+ * @property {Function}  getSavings             - same sig as fetchSavings
+ * @property {Function}  writeCfg               - (fields) => void
+ * @property {Function}  writeSettings          - (opts) => void
+ * @property {Function}  print                  - (msg:string) => void
+ * @property {Function}  prompt                 - (msg:string) => Promise<string>   (y/N)
+ * @property {Function}  promptMasked           - (msg:string) => Promise<string>   (no echo)
+ * @property {Function}  promptShellAlias       - () => Promise<boolean>            (y/N)
+ * @property {string}   [proxyBaseUrl]
+ * @property {string}   [oauthBaseUrl]
+ * @property {string}   [authMode]             - 'github' | 'swarmiq' | 'clerk' — overrides auto-detect
+ * @property {Function} [fetchFn]             - injectable fetch for internal calls
+ * @property {Function} [sleep]               - injectable sleep for GitHub poll
+ */
+
+/**
+ * Run the SwarmIQ connect flow end-to-end.
+ *
+ * @param {Partial<ConnectDeps>} [deps] - inject for testing
+ * @returns {Promise<{access_token:string, tenant_id:string, tier:string}>}
+ */
+export async function runInit(deps = {}) {
+  const {
+    openBrowser = defaultOpenBrowser,
+    requestCode = requestDeviceCode,
+    pollToken = pollDeviceToken,
+    requestGHCode = requestGitHubDeviceCode,
+    pollGHToken = pollGitHubToken,
+    exchangeGHToken = defaultExchangeGHToken,
+    fetchAuthConfig = defaultFetchAuthConfig,
+    storeKey = storeProviderKey,
+    getHealth = fetchHealth,
+    getSavings = fetchSavings,
+    writeCfg = writeConfig,
+    writeSettings = writeClaudeSettings,
+    print = defaultPrint,
+    prompt = defaultPrompt,
+    promptMasked = defaultPromptMasked,
+    promptShellAlias = defaultPromptShellAlias,
+    proxyBaseUrl = PROXY_BASE_URL_DEFAULT,
+    oauthBaseUrl = OAUTH_BASE_URL,
+    authMode = null,
+    fetchFn = globalThis.fetch,
+    sleep = defaultSleep,
+  } = deps;
+
+  print('');
+  print('SwarmIQ — connect');
+  print('─────────────────────────────────────────');
+
+  // ── Step 0: determine auth mode ──────────────────────────────────────────────
+  // Forced SwarmIQ/Clerk path → skip config fetch entirely.
+  const forcedSwarmiq = authMode === 'swarmiq' || authMode === 'clerk';
+
+  let useGitHub = false;
+  let githubClientId = null;
+
+  if (!forcedSwarmiq) {
+    // Probe /v1/auth/config — errors are non-fatal; fall back to SwarmIQ flow.
+    try {
+      const cfg = await fetchAuthConfig(proxyBaseUrl, fetchFn);
+      if (cfg && cfg.github_oauth_enabled && cfg.github_client_id) {
+        useGitHub = true;
+        githubClientId = cfg.github_client_id;
+      }
+    } catch {
+      // Config endpoint unreachable or returned unexpected shape — fall back.
+      useGitHub = false;
+    }
+  }
+
+  // ── Auth path split ───────────────────────────────────────────────────────────
+  let access_token, tenant_id, tier;
+
+  if (useGitHub) {
+    // ── GitHub Device Flow ──────────────────────────────────────────────────────
+    print('');
+    print('  Authenticating via GitHub (default)...');
+    print('');
+
+    const ghCode = await requestGHCode(githubClientId, fetchFn);
+
+    // Show user_code prominently
+    print('  Open the following URL in your browser to authenticate with GitHub:');
+    print('');
+    print(`  ${ghCode.verification_uri}`);
+    print('');
+    print('  Then enter this code when prompted:');
+    print('');
+    print(`       ╔══════════════════╗`);
+    print(`       ║  ${ghCode.user_code.padEnd(16)}  ║`);
+    print(`       ╚══════════════════╝`);
+    print('');
+    print(`  (Expires in ${Math.round(ghCode.expires_in / 60)} minutes)`);
+    print('');
+
+    // Best-effort browser open
+    await openBrowser(ghCode.verification_uri).catch(() => {});
+
+    print('Waiting for GitHub authorisation...');
+
+    // Poll GitHub — token is transient, never persisted
+    const githubAccessToken = await pollGHToken(
+      githubClientId,
+      ghCode.device_code,
+      ghCode.interval,
+      { fetch: fetchFn, sleep, expiresIn: ghCode.expires_in }
+    );
+
+    // Exchange GitHub token for SwarmIQ token — GitHub token discarded after this call
+    const swarmiqResult = await exchangeGHToken(githubAccessToken, proxyBaseUrl, fetchFn);
+
+    access_token = swarmiqResult.access_token;
+    tenant_id = swarmiqResult.tenant_id;
+    tier = swarmiqResult.tier ?? 'free';
+
+  } else {
+    // ── SwarmIQ / Clerk Device Flow (existing path) ──────────────────────────────
+    print('');
+    print('  Authenticating via SwarmIQ device flow...');
+    print('');
+
+    const {
+      device_code,
+      user_code,
+      verification_uri,
+      verification_uri_complete,
+      expires_in,
+      interval,
+    } = await requestCode({ oauthBaseUrl });
+
+    print('  Open the following URL in your browser to authenticate:');
+    print('');
+    print(`  ${verification_uri_complete}`);
+    print('');
+    print('  Then enter this code when prompted:');
+    print('');
+    print(`       ╔══════════════════╗`);
+    print(`       ║  ${user_code.padEnd(16)}  ║`);
+    print(`       ╚══════════════════╝`);
+    print('');
+    print(`  (Expires in ${Math.round(expires_in / 60)} minutes)`);
+    print('');
+
+    // Best-effort browser open
+    await openBrowser(verification_uri_complete).catch(() => {});
+
+    print('Waiting for authorisation in browser...');
+
+    const tokenResult = await pollToken({
+      device_code,
+      interval,
+      expires_in,
+      oauthBaseUrl,
+    });
+
+    access_token = tokenResult.access_token;
+    tenant_id = tokenResult.tenant_id;
+    tier = tokenResult.tier ?? 'free';
+  }
+
+  print('');
+  print(`Authorised.  Tenant: ${tenant_id}  |  Tier: ${tier}`);
+  print('');
+
+  // ── Write ~/.claude/settings.json ────────────────────────────────────────────
+  writeSettings({ proxyBaseUrl, accessToken: access_token });
+  // Also persist non-sensitive session info to ~/.swarmiq/config.json
+  writeCfg({ tenant_id, tier, proxy_base_url: proxyBaseUrl });
+
+  print(`Claude Code settings updated: ${claudeSettingsPath()}`);
+  print('  ANTHROPIC_BASE_URL     set to proxy');
+  print('  ANTHROPIC_AUTH_TOKEN   set to your access token');
+  print('  ANTHROPIC_API_KEY      cleared (SwarmIQ handles auth)');
+  print('');
+
+  // ── Offer shell rc alias (optional) ─────────────────────────────────────────
+  const wantAlias = await promptShellAlias();
+  if (wantAlias) {
+    await appendShellAlias({ proxyBaseUrl, print });
+  }
+
+  // ── BYOK prompt ──────────────────────────────────────────────────────────────
+  const byokAnswer = await prompt(
+    'Add a provider API key so SwarmIQ can route on your behalf? [y/N] '
+  );
+  if (byokAnswer.trim().toLowerCase() === 'y') {
+    const providerRaw = await prompt('Provider (default: anthropic): ');
+    const provider = providerRaw.trim() || 'anthropic';
+    const key = await promptMasked('API key (input hidden): ');
+    if (!key.trim()) {
+      print('No key entered — skipping.');
+    } else {
+      await storeKey({ provider, key: key.trim(), accessToken: access_token, proxyBaseUrl });
+      // Key is now in the Vault. Discard from local scope.
+      print(`  Provider key for "${provider}" stored in SwarmIQ Vault.`);
+      print('  The key was transmitted over HTTPS and is NOT saved locally.');
+    }
+  }
+
+  print('');
+
+  // ── Post-connect verify ───────────────────────────────────────────────────────
+  print('Verifying connection...');
+  const health = await getHealth({ proxyBaseUrl });
+  const savings = await getSavings({ proxyBaseUrl });
+
+  if (health) {
+    const savingsLine = buildSavingsLine(savings);
+    print(`  Connected — routing active${savingsLine}`);
+  } else {
+    print('  Warning: proxy health check did not respond. Check that the proxy');
+    print(`  is reachable at ${proxyBaseUrl}`);
+  }
+  print('');
+
+  return { access_token, tenant_id, tier };
+}
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * Build a human-readable savings suffix line from the savings summary.
+ * Prefers true_savings_vs_max_plan_7d_usd; falls back to total_savings_usd.
+ * @param {Record<string,unknown>|null} savings
+ * @returns {string}
+ */
+function buildSavingsLine(savings) {
+  if (!savings) return '';
+  const val =
+    savings.true_savings_vs_max_plan_7d_usd ??
+    savings.total_savings_usd ??
+    null;
+  if (val == null) return '';
+  const formatted = typeof val === 'number' ? `$${val.toFixed(2)}` : String(val);
+  return `  |  7d savings: ${formatted}`;
+}
+
+/**
+ * GET /v1/auth/config — probe whether GitHub OAuth is enabled and obtain client_id.
+ * Returns null (not throws) on any network/parse failure so callers can fall back.
+ *
+ * @param {string}   proxyBaseUrl
+ * @param {Function} fetchFn
+ * @returns {Promise<{github_client_id:string|null, github_oauth_enabled:boolean}|null>}
+ */
+async function defaultFetchAuthConfig(proxyBaseUrl, fetchFn) {
+  try {
+    const res = await fetchFn(`${proxyBaseUrl}/v1/auth/config`);
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * POST /v1/auth/github — exchange a transient GitHub access token for a SwarmIQ token.
+ * The github_access_token is sent once over HTTPS and then discarded by the caller.
+ *
+ * @param {string}   githubAccessToken  - TRANSIENT — never write to disk
+ * @param {string}   proxyBaseUrl
+ * @param {Function} fetchFn
+ * @returns {Promise<{access_token:string, token_type:string, tenant_id:string, tier:string}>}
+ */
+async function defaultExchangeGHToken(githubAccessToken, proxyBaseUrl, fetchFn) {
+  const url = `${proxyBaseUrl}/v1/auth/github`;
+  const res = await fetchFn(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ github_access_token: githubAccessToken }),
+  });
+
+  if (!res.ok) {
+    let detail = '';
+    try {
+      const body = await res.json();
+      detail = body?.detail ?? body?.error ?? '';
+    } catch {
+      detail = await res.text().catch(() => '');
+    }
+    const msg = detail ? ` — ${detail}` : '';
+    throw new Error(
+      `GitHub token exchange failed: HTTP ${res.status}${msg}`
+    );
+  }
+
+  const data = await res.json();
+
+  if (!data.access_token || !data.tenant_id) {
+    throw new Error(
+      'Unexpected response from /v1/auth/github: missing access_token or tenant_id'
+    );
+  }
+
+  return {
+    access_token: data.access_token,
+    token_type: data.token_type ?? 'bearer',
+    tenant_id: data.tenant_id,
+    tier: data.tier ?? 'free',
+  };
+}
+
+/**
+ * Append a `claude-swarmiq` alias to the user's shell rc file.
+ * Best-effort only — errors are printed, not thrown.
+ * @param {object} opts
+ * @param {string} opts.proxyBaseUrl
+ * @param {Function} opts.print
+ */
+async function appendShellAlias({ proxyBaseUrl, print }) {
+  const { homedir } = await import('node:os');
+  const { appendFileSync, existsSync } = await import('node:fs');
+  const { join } = await import('node:path');
+
+  const home = homedir();
+  const rcCandidates = [
+    join(home, '.zshrc'),
+    join(home, '.bashrc'),
+    join(home, '.bash_profile'),
+  ];
+
+  const rcFile = rcCandidates.find((f) => existsSync(f));
+  if (!rcFile) {
+    print('  Could not locate a shell rc file — alias not added.');
+    return;
+  }
+
+  const alias = `\n# SwarmIQ — added by npx swarmiq\nalias claude-swarmiq='ANTHROPIC_BASE_URL="${proxyBaseUrl}" claude'\n`;
+
+  try {
+    appendFileSync(rcFile, alias, 'utf8');
+    print(`  Alias claude-swarmiq added to ${rcFile}`);
+    print('  Reload your shell or run: source ' + rcFile);
+  } catch (err) {
+    print(`  Could not write to ${rcFile}: ${err.message}`);
+  }
+}
+
+// ─── production I/O implementations ──────────────────────────────────────────
+
+async function defaultOpenBrowser(url) {
+  const { exec } = await import('node:child_process');
+  const cmd =
+    process.platform === 'win32'
+      ? `start "" "${url}"`
+      : process.platform === 'darwin'
+      ? `open "${url}"`
+      : `xdg-open "${url}"`;
+  exec(cmd, () => {});
+}
+
+function defaultPrint(msg) {
+  process.stdout.write(msg + '\n');
+}
+
+/**
+ * Read a single line of stdin (plain, echoed).
+ * @param {string} question
+ * @returns {Promise<string>}
+ */
+function defaultPrompt(question) {
+  return new Promise((resolve) => {
+    process.stdout.write(question);
+    let buf = '';
+    const onData = (chunk) => {
+      buf += chunk;
+      const nl = buf.indexOf('\n');
+      if (nl !== -1) {
+        process.stdin.off('data', onData);
+        process.stdin.pause();
+        resolve(buf.slice(0, nl).replace(/\r$/, ''));
+      }
+    };
+    process.stdin.setEncoding('utf8');
+    process.stdin.resume();
+    process.stdin.on('data', onData);
+  });
+}
+
+/**
+ * Read a line from stdin with echo disabled (for API keys).
+ * Falls back to plain readline if raw mode is unavailable.
+ * @param {string} question
+ * @returns {Promise<string>}
+ */
+function defaultPromptMasked(question) {
+  return new Promise((resolve) => {
+    process.stdout.write(question);
+    let buf = '';
+
+    const stdin = process.stdin;
+    const wasRaw = stdin.isRaw;
+    let rawModeSet = false;
+
+    try {
+      if (typeof stdin.setRawMode === 'function') {
+        stdin.setRawMode(true);
+        rawModeSet = true;
+      }
+    } catch {
+      // raw mode unavailable (piped stdin in tests) — fall through to plain
+    }
+
+    stdin.setEncoding('utf8');
+    stdin.resume();
+
+    const onData = (chunk) => {
+      for (const ch of chunk) {
+        if (ch === '\r' || ch === '\n') {
+          // Enter pressed
+          stdin.off('data', onData);
+          if (rawModeSet) {
+            try { stdin.setRawMode(wasRaw); } catch { /* ignore */ }
+          }
+          stdin.pause();
+          process.stdout.write('\n');
+          resolve(buf);
+          return;
+        } else if (ch === '') {
+          // Ctrl-C
+          stdin.off('data', onData);
+          if (rawModeSet) {
+            try { stdin.setRawMode(wasRaw); } catch { /* ignore */ }
+          }
+          process.stdout.write('\n');
+          process.exit(130);
+        } else if (ch === '' || ch === '\b') {
+          // Backspace
+          if (buf.length > 0) buf = buf.slice(0, -1);
+        } else {
+          buf += ch;
+        }
+      }
+    };
+
+    stdin.on('data', onData);
+  });
+}
+
+/**
+ * Ask the user whether to add the claude-swarmiq alias.
+ * @returns {Promise<boolean>}
+ */
+async function defaultPromptShellAlias() {
+  if (process.platform === 'win32') {
+    // Shell aliases not applicable on Windows
+    return false;
+  }
+  const ans = await defaultPrompt(
+    'Append a `claude-swarmiq` alias to your shell rc? [y/N] '
+  );
+  return ans.trim().toLowerCase() === 'y';
+}
+
+async function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}