swarmiq 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tal Wayn / SwarmIQ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,176 @@
+# SwarmIQ Init CLI
+
+<div dir="rtl">
+
+## סקירה
+
+`swarmiq-init` הוא כלי שורת פקודה לחיבור ראשוני של המשתמש לפרוקסי SwarmIQ.
+הוא מוביל את המשתמש דרך GitHub OAuth (דרך Clerk), מקבל `api_key`, שומר אותו
+בקובץ קונפיגורציה מקומי, ומדפיס את משתני הסביבה שיש להגדיר ב-Claude Code / VS Code
+כדי שכל הבקשות יעברו דרך הפרוקסי.
+
+**פרסום ל-npm** הוא פעולה ידנית של Tal (מוגדרת למועד מאוחר יותר, כמו רכישת Contabo).
+עד אז יש להשתמש בהפעלה מקומית (ראה להלן).
+
+</div>
+
+---
+
+## Onboarding flow
+
+```
+User  →  npx swarmiq-init  →  GitHub OAuth (Clerk)  →  JWT
+                                                          │
+                                                          ▼
+                                         POST /v1/auth/callback
+                                         (proxy creates tenant + api_key)
+                                                          │
+                                                          ▼
+                                         ~/.swarmiq/config.json  ←  key written
+                                                          │
+                                                          ▼
+                                         env-var instructions printed
+```
+
+---
+
+## Usage (after npm publish — deferred)
+
+```sh
+npx swarmiq-init
+```
+
+---
+
+## Local dev invocation (no npm publish required)
+
+```sh
+# From the repo root:
+node tools/cli/src/index.mjs
+
+# Or from within tools/cli/:
+node src/index.mjs
+```
+
+---
+
+## Options
+
+| Flag | Effect |
+|------|--------|
+| `--help` / `-h` | Show help and exit |
+| `--version` / `-v` | Print version and exit |
+
+---
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SWARMIQ_CONFIG_HOME` | `~/.swarmiq` | Directory where `config.json` is written |
+| `SWARMIQ_PROXY_URL` | `http://127.0.0.1:8000` | SwarmIQ proxy base URL |
+
+---
+
+## Output — config.json
+
+After a successful run, `$SWARMIQ_CONFIG_HOME/config.json` contains:
+
+```json
+{
+  "api_key": "<your-swarmiq-api-key>",
+  "tenant_id": "tnt_abc123",
+  "tier": "free",
+  "proxy_base_url": "http://127.0.0.1:8000",
+  "updated_at": "2026-05-31T12:00:00.000Z"
+}
+```
+
+---
+
+## Output — env vars printed to terminal
+
+```sh
+export ANTHROPIC_BASE_URL="http://127.0.0.1:8000"
+export ANTHROPIC_API_KEY="<your-swarmiq-api-key>"
+```
+
+Add these to your `~/.zshrc` / `~/.bashrc` (or Windows equivalent), or configure
+Claude Code with:
+
+```sh
+claude config set apiBaseUrl "http://127.0.0.1:8000"
+```
+
+---
+
+## Running tests
+
+No dependencies required. Uses Node's built-in test runner.
+
+```sh
+cd tools/cli
+node --test test/
+```
+
+Expected output: all 11 tests pass, `fail 0`.
+
+---
+
+## Architecture
+
+```
+tools/cli/
+├── src/
+│   ├── index.mjs    ← CLI entry point (bin: swarmiq-init)
+│   ├── init.mjs     ← Core flow, fully injectable (no network in tests)
+│   ├── oauth.mjs    ← URL builder + local callback HTTP server
+│   ├── api.mjs      ← POST /v1/auth/callback exchange
+│   └── config.mjs   ← ~/.swarmiq/config.json read/write
+└── test/
+    └── init.test.mjs ← 11 tests, node --test
+```
+
+**Runtime dependencies: zero.** Only Node built-ins (`node:fs`, `node:http`,
+`node:crypto`, `node:os`, `node:path`, `node:url`, `node:child_process`).
+
+**Design choice — plain ESM `.mjs` (not TypeScript):** The project has no
+existing Node build pipeline. TypeScript would require `npm install` + `npx tsc`
+on every change, creating offline-fragile CI. Plain ESM runs with zero build
+steps: `node src/index.mjs` and `node --test test/` both work immediately on
+Node 18+.
+
+---
+
+## Auth contract
+
+The CLI implements the onboarding leg of
+`infra/contracts/auth.contract.md` (C3, Wave-0B):
+
+- OAuth entry point: `https://clerk.swarmiq.dev/oauth/github`
+- Exchange endpoint: `POST /v1/auth/callback`
+- Response: `{ tenant_id, api_key, tier }`
+- Config written: `{ api_key, tenant_id, tier, proxy_base_url }`
+
+---
+
+<div dir="rtl">
+
+## פרסום ל-npm (פעולה ידנית)
+
+כאשר מגיע הזמן לפרסם:
+
+```sh
+cd tools/cli
+npm publish --access public
+```
+
+ברגע שהחבילה פורסמה, המשתמשים יוכלו להריץ:
+
+```sh
+npx swarmiq-init
+```
+
+עד אז — השתמשו בהפעלה מקומית.
+
+</div>

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "swarmiq",
+  "version": "0.2.0",
+  "description": "Route Claude Code through SwarmIQ's free-LLM cascade and save your Anthropic Max quota.",
+  "type": "module",
+  "main": "src/index.mjs",
+  "bin": {
+    "swarmiq": "src/index.mjs"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/init.test.mjs test/github_auth.test.mjs"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "anthropic",
+    "llm",
+    "proxy",
+    "router",
+    "cascade",
+    "swarmiq"
+  ],
+  "license": "MIT",
+  "homepage": "https://swarmiq.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TalWayn72/swarmiq-os.git",
+    "directory": "tools/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/TalWayn72/swarmiq-os/issues"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,99 @@
+/**
+ * api.mjs — HTTP helpers for talking to the SwarmIQ proxy.
+ *
+ * All functions accept an injectable `fetch` parameter so tests can replace
+ * network calls with fakes without ever hitting the wire.
+ *
+ * IMPORTANT: Provider API keys are accepted as parameters but NEVER written
+ * to disk and NEVER logged. They are sent once over HTTPS and then discarded.
+ */
+
+import { PROXY_BASE_URL_DEFAULT } from './config.mjs';
+
+// ─── BYOK: store a provider key in the Vault ─────────────────────────────────
+
+/**
+ * POST /v1/vault/provider-key
+ * Stores a provider API key in the SwarmIQ Vault under the caller's tenant.
+ * The key parameter is used exactly once — never cached, never written to disk.
+ *
+ * @param {object}   opts
+ * @param {string}   opts.provider        - e.g. "anthropic", "openai"
+ * @param {string}   opts.key             - the raw API key (not persisted locally)
+ * @param {string}   opts.accessToken     - Bearer token from device flow
+ * @param {string}  [opts.proxyBaseUrl]
+ * @param {Function}[opts.fetch]
+ * @returns {Promise<{status:string, provider:string}>}
+ */
+export async function storeProviderKey({
+  provider,
+  key,
+  accessToken,
+  proxyBaseUrl = PROXY_BASE_URL_DEFAULT,
+  fetch: fetchFn = globalThis.fetch,
+}) {
+  const url = `${proxyBaseUrl}/v1/vault/provider-key`;
+  const res = await fetchFn(url, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${accessToken}`,
+    },
+    body: JSON.stringify({ provider, key }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(
+      `POST /v1/vault/provider-key failed: HTTP ${res.status} — ${body}`
+    );
+  }
+
+  return res.json();
+}
+
+// ─── Health + Savings summary ─────────────────────────────────────────────────
+
+/**
+ * GET /health
+ * Returns raw JSON from the health endpoint or null on failure.
+ *
+ * @param {object}   opts
+ * @param {string}  [opts.proxyBaseUrl]
+ * @param {Function}[opts.fetch]
+ * @returns {Promise<Record<string,unknown>|null>}
+ */
+export async function fetchHealth({
+  proxyBaseUrl = PROXY_BASE_URL_DEFAULT,
+  fetch: fetchFn = globalThis.fetch,
+} = {}) {
+  try {
+    const res = await fetchFn(`${proxyBaseUrl}/health`);
+    if (!res.ok) return null;
+    return res.json();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * GET /v1/savings/summary
+ * Returns the savings summary or null on failure.
+ *
+ * @param {object}   opts
+ * @param {string}  [opts.proxyBaseUrl]
+ * @param {Function}[opts.fetch]
+ * @returns {Promise<Record<string,unknown>|null>}
+ */
+export async function fetchSavings({
+  proxyBaseUrl = PROXY_BASE_URL_DEFAULT,
+  fetch: fetchFn = globalThis.fetch,
+} = {}) {
+  try {
+    const res = await fetchFn(`${proxyBaseUrl}/v1/savings/summary`);
+    if (!res.ok) return null;
+    return res.json();
+  } catch {
+    return null;
+  }
+}

package/src/config.mjs

@@ -0,0 +1,165 @@
+/**
+ * config.mjs — Config file read/write for SwarmIQ CLI.
+ *
+ * Config location: $SWARMIQ_CONFIG_HOME/config.json  (default: ~/.swarmiq/config.json)
+ * Overridable via env SWARMIQ_CONFIG_HOME for tests.
+ *
+ * Also handles read-modify-write of ~/.claude/settings.json to inject the
+ * SwarmIQ env block (ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY).
+ * The "SwarmIQ block" is identified by the presence of ANTHROPIC_BASE_URL under
+ * the settings.env key so --logout can cleanly remove exactly those keys.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+
+// ─── proxy / OAuth base URLs ─────────────────────────────────────────────────
+
+/** Default proxy base — overridable via SWARMIQ_PROXY_URL env var. */
+export const PROXY_BASE_URL_DEFAULT =
+  process.env.SWARMIQ_PROXY_URL ?? 'https://api.swarmiq.dev';
+
+// ─── SwarmIQ config.json helpers ─────────────────────────────────────────────
+
+/**
+ * Resolve the directory that holds config.json.
+ * @returns {string} absolute path to config directory
+ */
+export function configDir() {
+  if (process.env.SWARMIQ_CONFIG_HOME) {
+    return process.env.SWARMIQ_CONFIG_HOME;
+  }
+  return join(homedir(), '.swarmiq');
+}
+
+/**
+ * Resolve the config file path.
+ * @returns {string} absolute path to config.json
+ */
+export function configPath() {
+  return join(configDir(), 'config.json');
+}
+
+/**
+ * Read config.json; returns {} if it doesn't exist.
+ * @returns {Record<string, unknown>}
+ */
+export function readConfig() {
+  const p = configPath();
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write (merge) fields into config.json, creating the directory if needed.
+ * Idempotent: merges over existing keys.
+ * Never writes provider keys — callers must strip sensitive fields before
+ * passing to this function.
+ * @param {Record<string, unknown>} fields
+ */
+export function writeConfig(fields) {
+  const dir = configDir();
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  const existing = readConfig();
+  const merged = { ...existing, ...fields, updated_at: new Date().toISOString() };
+  writeFileSync(configPath(), JSON.stringify(merged, null, 2) + '\n', 'utf8');
+}
+
+// ─── ~/.claude/settings.json helpers ─────────────────────────────────────────
+
+/**
+ * Resolve the Claude Code settings.json path.
+ * Overridable via SWARMIQ_CLAUDE_SETTINGS_PATH for tests.
+ * @returns {string}
+ */
+export function claudeSettingsPath() {
+  if (process.env.SWARMIQ_CLAUDE_SETTINGS_PATH) {
+    return process.env.SWARMIQ_CLAUDE_SETTINGS_PATH;
+  }
+  return join(homedir(), '.claude', 'settings.json');
+}
+
+/**
+ * Read ~/.claude/settings.json; returns {} if absent or unparseable.
+ * @returns {Record<string, unknown>}
+ */
+export function readClaudeSettings() {
+  const p = claudeSettingsPath();
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Write the SwarmIQ env block into ~/.claude/settings.json.
+ * Merges carefully: existing keys outside of `env` are preserved;
+ * within `env`, only the three SwarmIQ keys are added/updated.
+ *
+ * @param {object} opts
+ * @param {string} opts.proxyBaseUrl   - written as ANTHROPIC_BASE_URL
+ * @param {string} opts.accessToken    - written as ANTHROPIC_AUTH_TOKEN
+ */
+export function writeClaudeSettings({ proxyBaseUrl, accessToken }) {
+  const p = claudeSettingsPath();
+  const dir = dirname(p);
+
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  const existing = readClaudeSettings();
+  const existingEnv = (existing.env && typeof existing.env === 'object')
+    ? existing.env
+    : {};
+
+  const merged = {
+    ...existing,
+    env: {
+      ...existingEnv,
+      ANTHROPIC_BASE_URL: proxyBaseUrl,
+      ANTHROPIC_AUTH_TOKEN: accessToken,
+      ANTHROPIC_API_KEY: '',
+    },
+  };
+
+  writeFileSync(p, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+}
+
+/**
+ * Remove the SwarmIQ env block from ~/.claude/settings.json.
+ * Removes ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY.
+ * If `env` becomes empty after removal it is deleted from the settings object.
+ * If the file doesn't exist, this is a no-op.
+ */
+export function removeClaudeSettings() {
+  const p = claudeSettingsPath();
+  if (!existsSync(p)) return;
+
+  const existing = readClaudeSettings();
+  if (!existing.env || typeof existing.env !== 'object') return;
+
+  const SWARMIQ_KEYS = ['ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY'];
+  const newEnv = { ...existing.env };
+  for (const k of SWARMIQ_KEYS) {
+    delete newEnv[k];
+  }
+
+  const updated = { ...existing };
+  if (Object.keys(newEnv).length === 0) {
+    delete updated.env;
+  } else {
+    updated.env = newEnv;
+  }
+
+  writeFileSync(p, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+}

package/src/github_auth.mjs

@@ -0,0 +1,168 @@
+/**
+ * github_auth.mjs — GitHub OAuth Device Flow for SwarmIQ CLI.
+ *
+ * Implements the GitHub Device Flow (https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#device-flow):
+ *   1. POST https://github.com/login/device/code
+ *      body: client_id + scope=read:user user:email
+ *      → {device_code, user_code, verification_uri, expires_in, interval}
+ *   2. Display user_code + verification_uri to user; open browser (caller handles this).
+ *   3. Poll POST https://github.com/login/oauth/access_token
+ *      body: client_id + device_code + grant_type=urn:ietf:params:oauth:grant-type:device_code
+ *      → {access_token, ...} or {error: "authorization_pending"|"slow_down"|"expired_token"|"access_denied"}
+ *
+ * All network calls and the sleep function are injectable for testing.
+ * The GitHub access token is NEVER written to disk — callers must keep it in
+ * memory only and discard it after exchanging for a SwarmIQ token.
+ */
+
+const GITHUB_DEVICE_CODE_URL = 'https://github.com/login/device/code';
+const GITHUB_TOKEN_URL = 'https://github.com/login/oauth/access_token';
+
+/**
+ * Start the GitHub device flow: POST to GitHub's device/code endpoint.
+ *
+ * @param {string}   clientId   - The GitHub OAuth App client_id
+ * @param {Function} [fetchFn]  - Injectable fetch (defaults to globalThis.fetch)
+ * @returns {Promise<{
+ *   device_code: string,
+ *   user_code: string,
+ *   verification_uri: string,
+ *   expires_in: number,
+ *   interval: number,
+ * }>}
+ */
+export async function requestGitHubDeviceCode(clientId, fetchFn = globalThis.fetch) {
+  const res = await fetchFn(GITHUB_DEVICE_CODE_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded',
+      Accept: 'application/json',
+    },
+    body: new URLSearchParams({
+      client_id: clientId,
+      scope: 'read:user user:email',
+    }).toString(),
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(
+      `GitHub device code request failed: HTTP ${res.status} — ${body}`
+    );
+  }
+
+  const data = await res.json();
+
+  if (data.error) {
+    throw new Error(`GitHub device code error: ${data.error} — ${data.error_description ?? ''}`);
+  }
+
+  if (!data.device_code || !data.user_code || !data.verification_uri) {
+    throw new Error(
+      'Unexpected response from GitHub device/code: missing required fields'
+    );
+  }
+
+  return {
+    device_code: data.device_code,
+    user_code: data.user_code,
+    verification_uri: data.verification_uri,
+    expires_in: data.expires_in ?? 900,
+    interval: data.interval ?? 5,
+  };
+}
+
+/**
+ * Poll GitHub's token endpoint until the user completes authorisation.
+ *
+ * SECURITY: The returned access_token is a GitHub token and must NEVER be
+ * written to disk. Callers must exchange it immediately via POST /v1/auth/github
+ * and then discard it.
+ *
+ * @param {string}   clientId    - The GitHub OAuth App client_id
+ * @param {string}   deviceCode  - device_code from requestGitHubDeviceCode
+ * @param {number}   interval    - Initial polling interval in seconds
+ * @param {object}  [opts]
+ * @param {Function}[opts.fetch]  - Injectable fetch (defaults to globalThis.fetch)
+ * @param {Function}[opts.sleep]  - Injectable sleep (ms:number)=>Promise<void>
+ * @param {number}  [opts.expiresIn] - Total expiry window in seconds (default 900)
+ * @returns {Promise<string>}   The GitHub access token (transient — do not persist)
+ */
+export async function pollGitHubToken(
+  clientId,
+  deviceCode,
+  interval,
+  { fetch: fetchFn = globalThis.fetch, sleep = defaultSleep, expiresIn = 900 } = {}
+) {
+  const deadline = Date.now() + expiresIn * 1000;
+  let currentInterval = interval;
+
+  while (Date.now() < deadline) {
+    await sleep(currentInterval * 1000);
+
+    const res = await fetchFn(GITHUB_TOKEN_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        Accept: 'application/json',
+      },
+      body: new URLSearchParams({
+        client_id: clientId,
+        device_code: deviceCode,
+        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+      }).toString(),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      throw new Error(
+        `GitHub token poll failed: HTTP ${res.status} — ${body}`
+      );
+    }
+
+    const data = await res.json();
+
+    if (data.access_token) {
+      // Success — return token immediately (do NOT persist it)
+      return data.access_token;
+    }
+
+    const error = data.error ?? 'unknown_error';
+
+    switch (error) {
+      case 'authorization_pending':
+        // User hasn't approved yet — keep polling
+        break;
+
+      case 'slow_down':
+        // GitHub asked us to back off — increase interval by 5s
+        currentInterval += 5;
+        break;
+
+      case 'expired_token':
+        throw new Error(
+          'GitHub device authorisation expired. Please run `swarmiq` again to restart.'
+        );
+
+      case 'access_denied':
+        throw new Error(
+          'GitHub authorisation was denied. Please run `swarmiq` again and approve access.'
+        );
+
+      default:
+        throw new Error(
+          `Unexpected error from GitHub token endpoint: ${error} — ${data.error_description ?? ''}`
+        );
+    }
+  }
+
+  throw new Error(
+    'GitHub device authorisation timed out. Please run `swarmiq` again to restart.'
+  );
+}
+
+// ─── internal helpers ─────────────────────────────────────────────────────────
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}