@swarp/cli 0.1.2-rc.40 → 0.1.2-rc.42

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarp/cli",
-  "version": "0.1.2-rc.40",
+  "version": "0.1.2-rc.42",
   "description": "SWARP agent orchestration platform — CLI, MCP server, generator",
   "type": "module",
   "bin": {

package/skills/swarp/SKILL.md

@@ -20,6 +20,17 @@ The onboard tool manages a 4-phase workflow:
 
 Each phase must complete before the next can start. The tool enforces this — do not try to skip phases.
 
+## Autonomy Principle
+
+**Run commands directly. Do not ask the user to run things for you.** Claude Code's permission system is the gate — if a command needs approval, the user will be prompted automatically. For example:
+
+- Missing CLI tools? Run the install command yourself.
+- Need to authenticate? Run `fly auth login` yourself (Claude Code will handle the interactive prompt if needed, or the user will be prompted to approve).
+- Need to verify credentials? Run `flyctl status` or `sprite list` yourself.
+- Read-only commands like `flyctl orgs list` or `gh secret list`? Just run them.
+
+Only stop to ask the user when you need **information** from them (e.g., "which Fly.io org?" or "what should the agent do?"), not when you need to **execute** something.
+
 ## Commands
 
 ### `/swarp` (no arguments)

package/src/mcp-server/deploy-router.mjs

@@ -0,0 +1,378 @@
+// swarp_deploy_router MCP tool implementation.
+//
+// Deploys the SWARP gRPC router to the user's Fly.io account. Uses flyctl
+// as a subprocess (required because fly.toml's http_service.h2_backend
+// option isn't exposable via the Machines API REST interface, and we
+// need h2_backend for gRPC to work through the Fly HTTP proxy).
+//
+// Flow:
+//   1. Validate flyctl auth and fly_org parameter
+//   2. Fetch per-user install secret from swarp.dev (provisions on first run)
+//   3. Idempotency: check if app already exists
+//   4. Create app if needed, generate temp fly.toml, set secrets, deploy
+//   5. Save router config to .swarp.json and return the URL
+//
+// Configuration:
+//   - SWARP_AUTH_TOKEN — user's swarp.dev Supabase session token. Loaded
+//     from a .env file in the project directory (cwd). Users generate
+//     this on https://swarp.dev/account (after signing in) and paste it
+//     into .env as SWARP_AUTH_TOKEN=<token>.
+//   - SWARP_API_BASE — default https://xzcysgjzygqhfdrriibs.supabase.co
+//   - SWARP_ROUTER_IMAGE — Docker image for the router. Defaults to the
+//     CI-published image at ghcr.io/dl3consulting/swarp-router:latest.
+//     Override via env var for forks or dev builds.
+
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, writeFileSync, readFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const DEFAULT_SWARP_API_BASE = 'https://xzcysgjzygqhfdrriibs.supabase.co';
+const DEFAULT_REGION = 'dfw';
+const DEFAULT_APP_NAME_PREFIX = 'swarp-router';
+const DEFAULT_ROUTER_IMAGE = 'ghcr.io/dl3consulting/swarp-router:latest';
+
+// Minimal .env parser — supports KEY=value, KEY="value", comment lines, blank
+// lines. Does not support multi-line values or variable interpolation.
+function loadDotEnv(cwd) {
+  const envPath = resolve(cwd, '.env');
+  if (!existsSync(envPath)) return {};
+  const content = readFileSync(envPath, 'utf-8');
+  const out = {};
+  for (const rawLine of content.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eqIdx = line.indexOf('=');
+    if (eqIdx === -1) continue;
+    const key = line.slice(0, eqIdx).trim();
+    let value = line.slice(eqIdx + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    out[key] = value;
+  }
+  return out;
+}
+
+// Resolve a config var: prefer process.env, fall back to .env file
+function resolveVar(name, dotEnv) {
+  return process.env[name] ?? dotEnv[name];
+}
+
+const FLY_TOML_TEMPLATE = (image, appName) => `
+app = "${appName}"
+primary_region = "${DEFAULT_REGION}"
+
+[build]
+  image = "${image}"
+
+[processes]
+  router = "/usr/local/bin/swarp-router"
+
+[[mounts]]
+  source = "swarp_data"
+  destination = "/data"
+  processes = ["router"]
+
+# gRPC router: Fly HTTP proxy terminates TLS, forwards h2c to :50051.
+# h2_backend is required for gRPC — tells Fly to speak HTTP/2 to the backend.
+[http_service]
+  internal_port = 50051
+  processes = ["router"]
+  force_https = true
+  [http_service.http_options]
+    h2_backend = true
+`.trim() + '\n';
+
+function flyctl(args, opts = {}) {
+  try {
+    return execFileSync('flyctl', args, {
+      encoding: 'utf-8',
+      timeout: opts.timeout ?? 60_000,
+      stdio: opts.stdio ?? ['ignore', 'pipe', 'pipe'],
+      ...opts,
+    });
+  } catch (err) {
+    const stderr = err.stderr?.toString() ?? '';
+    const stdout = err.stdout?.toString() ?? '';
+    const message = stderr || stdout || err.message;
+    throw new Error(`flyctl ${args[0]} failed: ${message.trim()}`);
+  }
+}
+
+async function provisionInstallSecret({ authToken, apiBase, flyOrg, flyApp }) {
+  const url = `${apiBase}/functions/v1/swarp-install-provision`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${authToken}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ fly_org: flyOrg, fly_app: flyApp }),
+  });
+
+  if (!res.ok) {
+    const body = await res.text();
+    throw new Error(`swarp.dev provision failed: ${res.status} ${body}`);
+  }
+
+  return res.json();
+}
+
+function appExists(appName) {
+  try {
+    const output = flyctl(['apps', 'list', '--json']);
+    const apps = JSON.parse(output);
+    return apps.some((a) => (a.Name ?? a.name) === appName);
+  } catch {
+    return false;
+  }
+}
+
+function volumeExists(appName) {
+  try {
+    const output = flyctl(['volumes', 'list', '--app', appName, '--json']);
+    const volumes = JSON.parse(output);
+    return volumes.some((v) => v.name === 'swarp_data' || v.Name === 'swarp_data');
+  } catch {
+    return false;
+  }
+}
+
+function createApp(appName, flyOrg) {
+  flyctl(['apps', 'create', appName, '--org', flyOrg], { timeout: 30_000 });
+}
+
+function createVolume(appName, region) {
+  flyctl([
+    'volumes', 'create', 'swarp_data',
+    '--app', appName,
+    '--region', region,
+    '--size', '1',
+    '--yes',
+  ], { timeout: 60_000 });
+}
+
+function setSecret(appName, key, value) {
+  // --stage so the secret is staged without triggering a deploy. The
+  // subsequent `deploy` command picks up staged secrets. We don't pass
+  // the value via argv — flyctl reads stdin when given `-` as the value.
+  execFileSync(
+    'flyctl',
+    ['secrets', 'set', '--app', appName, '--stage', `${key}=${value}`],
+    { stdio: ['ignore', 'pipe', 'pipe'], timeout: 30_000 },
+  );
+}
+
+function deploy(configPath, appName) {
+  flyctl([
+    'deploy',
+    '--config', configPath,
+    '--app', appName,
+    '--now',
+    '--ha=false',
+  ], { timeout: 600_000 });
+}
+
+function getAppUrl(appName) {
+  try {
+    const output = flyctl(['status', '--app', appName, '--json']);
+    const status = JSON.parse(output);
+    return status.Hostname ?? status.hostname ?? `${appName}.fly.dev`;
+  } catch {
+    return `${appName}.fly.dev`;
+  }
+}
+
+function writeSwarpConfig(configPath, updates) {
+  const existing = existsSync(configPath)
+    ? JSON.parse(readFileSync(configPath, 'utf-8'))
+    : {};
+  const merged = { ...existing, ...updates };
+  writeFileSync(configPath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+  return merged;
+}
+
+export async function handleDeployRouter(toolArgs) {
+  const { fly_org: flyOrg, app_name: appNameInput, region = DEFAULT_REGION } = toolArgs ?? {};
+
+  if (!flyOrg) {
+    return {
+      content: [{ type: 'text', text: 'Error: fly_org is required. Example: { "fly_org": "personal" }' }],
+      isError: true,
+    };
+  }
+
+  const dotEnv = loadDotEnv(process.cwd());
+
+  const authToken = resolveVar('SWARP_AUTH_TOKEN', dotEnv);
+  if (!authToken) {
+    return {
+      content: [{
+        type: 'text',
+        text: [
+          'Error: SWARP_AUTH_TOKEN is not set.',
+          '',
+          'The plugin needs your swarp.dev session token to fetch a unique',
+          'HMAC signing key for your router. To generate it:',
+          '',
+          '  1. Sign in at https://swarp.dev with your Google account',
+          '  2. Go to https://swarp.dev/account and click "Generate CLI token"',
+          '  3. Copy the token and add it to a .env file in this directory:',
+          '',
+          '     echo \'SWARP_AUTH_TOKEN="<paste-token-here>"\' >> .env',
+          '',
+          '  4. Re-run swarp_deploy_router',
+          '',
+          'The token grants the plugin permission to provision and retrieve',
+          'install secrets on your behalf. Treat it like a password — never',
+          'commit .env to git (it should be in .gitignore already).',
+        ].join('\n'),
+      }],
+      isError: true,
+    };
+  }
+
+  const routerImage = resolveVar('SWARP_ROUTER_IMAGE', dotEnv) ?? DEFAULT_ROUTER_IMAGE;
+
+  // Verify flyctl is authenticated
+  try {
+    flyctl(['auth', 'whoami'], { timeout: 10_000 });
+  } catch {
+    return {
+      content: [{
+        type: 'text',
+        text: 'Error: flyctl is not authenticated. Run: fly auth login',
+      }],
+      isError: true,
+    };
+  }
+
+  const apiBase = resolveVar('SWARP_API_BASE', dotEnv) ?? DEFAULT_SWARP_API_BASE;
+  const appName = appNameInput ?? DEFAULT_APP_NAME_PREFIX;
+  const configPath = resolve('.swarp.json');
+
+  const steps = [];
+
+  try {
+    // 1. Fetch or provision install secret
+    steps.push('→ Fetching install secret from swarp.dev...');
+    const install = await provisionInstallSecret({
+      authToken,
+      apiBase,
+      flyOrg,
+      flyApp: appName,
+    });
+    steps.push(`  ${install.existed ? '↻ Reusing existing install secret' : '✓ New install secret provisioned'}`);
+
+    // 2. Idempotency check
+    const exists = appExists(appName);
+    if (exists) {
+      steps.push(`  ↻ Fly app "${appName}" already exists — skipping create`);
+    } else {
+      steps.push(`→ Creating Fly app "${appName}" in org "${flyOrg}"...`);
+      createApp(appName, flyOrg);
+      steps.push('  ✓ App created');
+    }
+
+    // 3. Volume
+    if (!volumeExists(appName)) {
+      steps.push('→ Creating 1GB volume "swarp_data"...');
+      createVolume(appName, region);
+      steps.push('  ✓ Volume created');
+    } else {
+      steps.push('  ↻ Volume "swarp_data" already exists');
+    }
+
+    // 4. Stage secrets
+    steps.push('→ Setting SUPABASE_JWT_SECRET (staged)...');
+    setSecret(appName, 'SUPABASE_JWT_SECRET', install.jwt_secret);
+    steps.push('  ✓ Secret staged');
+
+    // 5. Generate fly.toml and deploy
+    const tmpDir = mkdtempSync(join(tmpdir(), 'swarp-deploy-'));
+    const tomlPath = join(tmpDir, 'fly.toml');
+    writeFileSync(tomlPath, FLY_TOML_TEMPLATE(routerImage, appName), 'utf-8');
+    steps.push(`→ Deploying router image ${routerImage}...`);
+    deploy(tomlPath, appName);
+    steps.push('  ✓ Deploy complete');
+
+    // 6. Save config
+    const hostname = getAppUrl(appName);
+    const routerUrl = `${hostname}:443`;
+    writeSwarpConfig(configPath, {
+      router_url: routerUrl,
+      fly_app: appName,
+      fly_org: flyOrg,
+    });
+
+    // 7. Tell swarp.dev about the final URL so token issuance can reference it
+    try {
+      await provisionInstallSecret({
+        authToken,
+        apiBase,
+        flyOrg,
+        flyApp: appName,
+      });
+    } catch (err) {
+      steps.push(`  ⚠ Could not update swarp.dev with final URL: ${err.message}`);
+    }
+
+    return {
+      content: [{
+        type: 'text',
+        text: [
+          ...steps,
+          '',
+          `Router deployed: https://${hostname}`,
+          `gRPC endpoint: ${routerUrl}`,
+          '',
+          'Config saved to .swarp.json.',
+          'Run swarp_onboard action="complete_phase" phase="router" to advance.',
+        ].join('\n'),
+      }],
+    };
+  } catch (err) {
+    return {
+      content: [{
+        type: 'text',
+        text: [
+          ...steps,
+          '',
+          `Error: ${err.message}`,
+          '',
+          'You can re-run this tool — it is idempotent (existing apps and volumes are skipped).',
+        ].join('\n'),
+      }],
+      isError: true,
+    };
+  }
+}
+
+export const deployRouterToolDef = {
+  name: 'swarp_deploy_router',
+  description:
+    'Deploy the SWARP gRPC router to Fly.io. Creates the app, volume, and machine, sets the per-user install secret, and saves router_url to .swarp.json. Idempotent. Requires flyctl installed and authenticated, and SWARP_AUTH_TOKEN set in a .env file in the project directory (generate the token at https://swarp.dev/account).',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      fly_org: {
+        type: 'string',
+        description: 'Fly.io organization slug to deploy into (e.g. "personal")',
+      },
+      app_name: {
+        type: 'string',
+        description: 'Fly app name (default: "swarp-router")',
+      },
+      region: {
+        type: 'string',
+        description: 'Fly region code (default: "dfw")',
+      },
+    },
+    required: ['fly_org'],
+  },
+  annotations: {
+    destructiveHint: true,
+  },
+};

package/src/mcp-server/index.mjs

@@ -9,6 +9,7 @@ import { loadConfig } from '../config.mjs';
 import { auditConfigs } from '../generator/audit.mjs';
 import { generateRunnerConfig } from '../generator/generate.mjs';
 import { handleOnboard, onboardToolDef } from './onboard.mjs';
+import { handleDeployRouter, deployRouterToolDef } from './deploy-router.mjs';
 
 export async function startMcpServer() {
   let config = {};
@@ -44,8 +45,13 @@ export async function startMcpServer() {
 
   const localTools = client ? buildLocalTools(config) : [];
 
+  // swarp_deploy_router is always available — it's needed during onboarding
+  // (before the router exists) and is harmless to expose afterwards (it's
+  // idempotent).
+  const onboardingTools = [onboardToolDef, deployRouterToolDef];
+
   server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools: [onboardToolDef, ...agentTools, ...localTools] };
+    return { tools: [...onboardingTools, ...agentTools, ...localTools] };
   });
 
   server.setRequestHandler(CallToolRequestSchema, async (req) => {
@@ -57,6 +63,7 @@ export async function startMcpServer() {
     }
 
     if (name === 'swarp_onboard') return handleOnboard(toolArgs);
+    if (name === 'swarp_deploy_router') return handleDeployRouter(toolArgs);
     if (name === 'swarm_audit') return handleAudit(config, toolArgs);
     if (name === 'swarm_generate') return handleGenerate(config, toolArgs);
     if (name === 'swarm_status') return handleStatus(client, toolArgs);

package/src/mcp-server/onboard.mjs

@@ -44,13 +44,18 @@ function nextPhase() {
 // ── Phase checks ────────────────────────────────────────────────────────────
 
 function checkPrerequisites() {
+  const versionFlags = { flyctl: 'version', sprite: '--version', gh: '--version' };
   const results = [];
   for (const tool of ['flyctl', 'sprite', 'gh']) {
     try {
       execFileSync('which', [tool], { stdio: 'ignore' });
-      results.push({ tool, installed: true });
+      let version = 'unknown';
+      try {
+        version = execFileSync(tool, [versionFlags[tool]], { encoding: 'utf-8', timeout: 5000 }).trim().split('\n')[0];
+      } catch { /* version check is best-effort */ }
+      results.push({ tool, installed: true, version });
     } catch {
-      results.push({ tool, installed: false });
+      results.push({ tool, installed: false, version: null });
     }
   }
   return results;
@@ -186,7 +191,22 @@ export async function handleOnboard(toolArgs) {
   if (action === 'check_prerequisites') {
     const results = checkPrerequisites();
     const allInstalled = results.every((r) => r.installed);
-    const lines = results.map((r) => `  ${r.installed ? '✓' : '✗'} ${r.tool}`);
+    const lines = results.map((r) => `  ${r.installed ? '✓' : '✗'} ${r.tool} — ${r.installed ? `installed (${r.version})` : 'not installed'}`);
+    const missing = results.filter((r) => !r.installed);
+
+    const installInstructions = missing.map((r) => {
+      switch (r.tool) {
+        case 'flyctl':
+          return `Install flyctl by running: curl -L https://fly.io/install.sh | sh\nThen authenticate: fly auth login`;
+        case 'sprite':
+          return `Install sprite by running: curl -fsSL https://sprites.dev/install.sh | sh`;
+        case 'gh':
+          return `Install gh by running: (type -p wget >/dev/null || (apt-get update && apt-get install -y wget)) && mkdir -p /etc/apt/keyrings && wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null && apt-get update && apt-get install -y gh`;
+        default:
+          return `Install ${r.tool} manually.`;
+      }
+    });
+
     return {
       content: [{
         type: 'text',
@@ -196,7 +216,14 @@ export async function handleOnboard(toolArgs) {
           '',
           allInstalled
             ? 'All prerequisites met. Run swarp_onboard with action="complete_phase" phase="prerequisites" to advance.'
-            : 'Missing tools must be installed before continuing.',
+            : [
+                `${missing.length} missing tool(s). Install them now:`,
+                '',
+                ...installInstructions,
+                '',
+                'Run these install commands directly — Claude Code will ask for permission.',
+                'After installing, run swarp_onboard with action="check_prerequisites" again to verify.',
+              ].join('\n'),
         ].join('\n'),
       }],
     };
@@ -209,26 +236,31 @@ function getPhaseInstructions(phase, state) {
   switch (phase) {
     case 'prerequisites':
       return [
-        'Check that required CLIs are installed:',
-        '  - flyctl (Fly.io CLI): https://fly.io/docs/getting-started/installing-flyctl/',
-        '  - sprite (Fly Sprites CLI): https://sprites.dev',
-        '  - gh (GitHub CLI): https://cli.github.com',
+        'Check that required CLIs are installed by running swarp_onboard action="check_prerequisites".',
         '',
-        'Run swarp_onboard with action="check_prerequisites" to verify.',
+        'If any tools are missing, install them by running the provided install commands directly.',
+        'Claude Code permissions will gate execution — just run the commands.',
+        'After installing, re-run check_prerequisites to verify, then complete the phase.',
       ].join('\n');
 
     case 'router':
       return [
         'Deploy the SWARP router to Fly.io.',
         '',
+        'Before calling swarp_deploy_router, make sure the user has:',
+        '  a. A swarp.dev CLI token in .env as SWARP_AUTH_TOKEN. If missing,',
+        '     guide them: sign in at https://swarp.dev, generate a token at',
+        '     https://swarp.dev/account, then add it to .env in this directory.',
+        '  b. flyctl installed and authenticated (fly auth login).',
+        '',
         'Steps:',
-        '1. Ask the user for their Fly.io org name',
-        '2. Use swarp_deploy_router tool with the org name',
-        '   (This will show a cost estimate and require user approval)',
-        '3. Save router_url and fly_app to config:',
-        '   swarp_onboard action="save_config" key="router_url" value="<url>"',
-        '   swarp_onboard action="save_config" key="fly_app" value="<app-name>"',
-        '   swarp_onboard action="save_config" key="fly_org" value="<org>"',
+        '1. Ask the user for their Fly.io org name (default: "personal")',
+        '2. Call swarp_deploy_router with { "fly_org": "<org>" }',
+        '   The cost confirmation hook will show an estimate (~$2.09/mo)',
+        '   and ask for approval before anything is created.',
+        '   The tool is idempotent — safe to re-run if something fails.',
+        '3. On success the tool saves router_url, fly_app, and fly_org',
+        '   to .swarp.json automatically — no additional save_config calls.',
         '4. Complete: swarp_onboard action="complete_phase" phase="router"',
       ].join('\n');