@swarp/cli 0.0.4 → 0.1.0-rc.33

package/src/mcp-server/onboard.mjs

@@ -0,0 +1,291 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+
+const CONFIG_PATH = resolve('.swarp.json');
+
+const PHASES = ['prerequisites', 'router', 'secrets', 'first_agent'];
+
+function readState() {
+  if (!existsSync(CONFIG_PATH)) {
+    return { phases_completed: [], setup_complete: false };
+  }
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
+  } catch {
+    return { phases_completed: [], setup_complete: false };
+  }
+}
+
+function writeState(state) {
+  writeFileSync(CONFIG_PATH, JSON.stringify(state, null, 2) + '\n', 'utf-8');
+}
+
+function completePhase(phaseName) {
+  const state = readState();
+  if (!state.phases_completed) state.phases_completed = [];
+  if (!state.phases_completed.includes(phaseName)) {
+    state.phases_completed.push(phaseName);
+  }
+  writeState(state);
+  return state;
+}
+
+function nextPhase() {
+  const state = readState();
+  const completed = state.phases_completed ?? [];
+  if (state.setup_complete) return null;
+  for (const phase of PHASES) {
+    if (!completed.includes(phase)) return phase;
+  }
+  return null;
+}
+
+// ── Phase checks ────────────────────────────────────────────────────────────
+
+function checkPrerequisites() {
+  const results = [];
+  for (const tool of ['flyctl', 'sprite', 'gh']) {
+    try {
+      execFileSync('which', [tool], { stdio: 'ignore' });
+      results.push({ tool, installed: true });
+    } catch {
+      results.push({ tool, installed: false });
+    }
+  }
+  return results;
+}
+
+function checkRouterExists(state) {
+  if (!state.fly_app) return false;
+  try {
+    const output = execFileSync('flyctl', ['apps', 'list', '--json'], {
+      encoding: 'utf-8',
+      timeout: 10000,
+    });
+    const apps = JSON.parse(output);
+    return apps.some((a) => a.Name === state.fly_app || a.name === state.fly_app);
+  } catch {
+    return false;
+  }
+}
+
+// ── Tool handler ────────────────────────────────────────────────────────────
+
+export async function handleOnboard(toolArgs) {
+  const { action } = toolArgs ?? {};
+  const state = readState();
+  const phase = nextPhase();
+
+  // Status check — no action, just report
+  if (!action || action === 'status') {
+    if (state.setup_complete) {
+      return {
+        content: [{
+          type: 'text',
+          text: [
+            'SWARP setup is complete.',
+            `Router: ${state.router_url ?? 'not set'}`,
+            `Fly app: ${state.fly_app ?? 'not set'}`,
+            `Agents dir: ${state.agents_dir ?? 'agents/'}`,
+            `Phases completed: ${(state.phases_completed ?? []).join(', ')}`,
+            '',
+            'Use swarp_status to check agent health, or swarp_deploy to deploy agents.',
+          ].join('\n'),
+        }],
+      };
+    }
+
+    if (!phase) {
+      return { content: [{ type: 'text', text: 'All phases complete. Run with action="finish" to finalize setup.' }] };
+    }
+
+    return {
+      content: [{
+        type: 'text',
+        text: [
+          `SWARP onboarding — next phase: ${phase}`,
+          `Completed: ${(state.phases_completed ?? []).join(', ') || 'none'}`,
+          '',
+          getPhaseInstructions(phase, state),
+        ].join('\n'),
+      }],
+    };
+  }
+
+  // Complete a phase
+  if (action === 'complete_phase') {
+    const { phase: phaseName } = toolArgs;
+    if (!phaseName || !PHASES.includes(phaseName)) {
+      return { content: [{ type: 'text', text: `Invalid phase: ${phaseName}. Valid: ${PHASES.join(', ')}` }], isError: true };
+    }
+
+    // Validate phase ordering
+    const completed = state.phases_completed ?? [];
+    const phaseIdx = PHASES.indexOf(phaseName);
+    for (let i = 0; i < phaseIdx; i++) {
+      if (!completed.includes(PHASES[i])) {
+        return {
+          content: [{ type: 'text', text: `Cannot complete "${phaseName}" — phase "${PHASES[i]}" must be completed first.` }],
+          isError: true,
+        };
+      }
+    }
+
+    const updated = completePhase(phaseName);
+    const next = nextPhase();
+
+    if (!next) {
+      return {
+        content: [{ type: 'text', text: `Phase "${phaseName}" complete. All phases done! Run with action="finish" to finalize.` }],
+      };
+    }
+
+    return {
+      content: [{
+        type: 'text',
+        text: [
+          `Phase "${phaseName}" complete.`,
+          '',
+          `Next phase: ${next}`,
+          getPhaseInstructions(next, updated),
+        ].join('\n'),
+      }],
+    };
+  }
+
+  // Save config values
+  if (action === 'save_config') {
+    const { key, value } = toolArgs;
+    if (!key || value === undefined) {
+      return { content: [{ type: 'text', text: 'save_config requires key and value' }], isError: true };
+    }
+    const updated = readState();
+    updated[key] = value;
+    writeState(updated);
+    return { content: [{ type: 'text', text: `Saved ${key}=${JSON.stringify(value)} to .swarp.json` }] };
+  }
+
+  // Finalize setup
+  if (action === 'finish') {
+    const completed = state.phases_completed ?? [];
+    const missing = PHASES.filter((p) => !completed.includes(p));
+    if (missing.length > 0) {
+      return {
+        content: [{ type: 'text', text: `Cannot finalize — incomplete phases: ${missing.join(', ')}` }],
+        isError: true,
+      };
+    }
+    const updated = readState();
+    updated.setup_complete = true;
+    writeState(updated);
+    return { content: [{ type: 'text', text: 'SWARP setup complete! Use swarp_status to check your agents.' }] };
+  }
+
+  // Check prerequisites
+  if (action === 'check_prerequisites') {
+    const results = checkPrerequisites();
+    const allInstalled = results.every((r) => r.installed);
+    const lines = results.map((r) => `  ${r.installed ? '✓' : '✗'} ${r.tool}`);
+    return {
+      content: [{
+        type: 'text',
+        text: [
+          'Prerequisite check:',
+          ...lines,
+          '',
+          allInstalled
+            ? 'All prerequisites met. Run swarp_onboard with action="complete_phase" phase="prerequisites" to advance.'
+            : 'Missing tools must be installed before continuing.',
+        ].join('\n'),
+      }],
+    };
+  }
+
+  return { content: [{ type: 'text', text: `Unknown action: ${action}` }], isError: true };
+}
+
+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',
+        '',
+        'Run swarp_onboard with action="check_prerequisites" to verify.',
+      ].join('\n');
+
+    case 'router':
+      return [
+        'Deploy the SWARP router to Fly.io.',
+        '',
+        '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>"',
+        '4. Complete: swarp_onboard action="complete_phase" phase="router"',
+      ].join('\n');
+
+    case 'secrets':
+      return [
+        'Set up GitHub repo secrets for CI deployment.',
+        '',
+        'Tell the user to set these in their repo (Settings → Secrets → Actions):',
+        `  SWARP_SPRITES_TOKEN — from https://sprites.dev/account/${state.fly_org ?? '{org}'}/tokens`,
+        '  SWARP_FLY_API_TOKEN — run: flyctl tokens create deploy',
+        '',
+        'Verify local access:',
+        `  flyctl status --app ${state.fly_app ?? 'swarp-router'}`,
+        '  sprite list',
+        '',
+        'Note: This verifies LOCAL credentials only. CI secrets must be confirmed separately.',
+        'Optionally check: gh secret list',
+        '',
+        'Complete: swarp_onboard action="complete_phase" phase="secrets"',
+      ].join('\n');
+
+    case 'first_agent':
+      return [
+        'Create and deploy the first agent.',
+        '',
+        'Steps:',
+        '1. Ask the user what the agent should do',
+        '2. Generate agents/<name>/agent.yaml with appropriate modes',
+        '3. Use swarp_deploy tool to deploy the agent',
+        '   (This will show a cost estimate and require user approval)',
+        '4. Verify with swarp_status',
+        '5. Complete: swarp_onboard action="complete_phase" phase="first_agent"',
+      ].join('\n');
+
+    default:
+      return `Unknown phase: ${phase}`;
+  }
+}
+
+export const onboardToolDef = {
+  name: 'swarp_onboard',
+  description: 'Manage SWARP onboarding workflow. Tracks setup progress, enforces phase ordering, saves configuration.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action: {
+        type: 'string',
+        enum: ['status', 'check_prerequisites', 'complete_phase', 'save_config', 'finish'],
+        description: 'Action to perform. Default: status (show current phase).',
+      },
+      phase: {
+        type: 'string',
+        enum: ['prerequisites', 'router', 'secrets', 'first_agent'],
+        description: 'Phase name (for complete_phase action)',
+      },
+      key: { type: 'string', description: 'Config key (for save_config action)' },
+      value: { type: 'string', description: 'Config value (for save_config action)' },
+    },
+  },
+};

package/proto/swarp/v1/swarp.proto

@@ -1,157 +0,0 @@
-syntax = "proto3";
-package swarp.v1;
-
-option go_package = "github.com/dl3consulting/swarp/gen/go/swarp/v1;swarpv1";
-
-// Router <-> Sprite communication
-service AgentRunnerService {
-  rpc Dispatch(DispatchRequest) returns (stream DispatchResponse);
-  rpc GetStatus(GetStatusRequest) returns (GetStatusResponse);
-  rpc GetHealth(GetHealthRequest) returns (GetHealthResponse);
-}
-
-// Sprite -> Router registration
-service AgentRegistryService {
-  rpc Register(RegisterRequest) returns (RegisterResponse);
-}
-
-// Plugin/MCP -> Router communication
-// Plugins must implement DispatchTask. ListAgents, CancelTask, GetAgentStatus are optional.
-service AgentDispatchService {
-  rpc DispatchTask(DispatchTaskRequest) returns (stream DispatchTaskResponse);
-  rpc ListAgents(ListAgentsRequest) returns (ListAgentsResponse);
-  rpc CancelTask(CancelTaskRequest) returns (CancelTaskResponse);
-  rpc GetAgentStatus(GetAgentStatusRequest) returns (GetAgentStatusResponse);
-}
-
-message RegisterRequest {
-  string name = 1;
-  string address = 2;
-  repeated ModeInfo modes = 3;
-  string version = 4;
-}
-
-message RegisterResponse {
-  bool accepted = 1;
-}
-
-message DispatchRequest {
-  string mode = 1;
-  map<string, string> params = 2;
-  string session_id = 3;
-  int32 remaining_budget = 4;
-}
-
-message DispatchTaskRequest {
-  string agent = 1;
-
-  oneof dispatch {
-    StructuredDispatch structured = 2;
-    string raw_text = 3;
-  }
-
-  string callback_id = 4;
-  string session_id = 5;
-  int32 remaining_budget = 6;
-}
-
-message DispatchResponse {
-  AgentEvent event = 1;
-}
-
-message DispatchTaskResponse {
-  AgentEvent event = 1;
-}
-
-message StructuredDispatch {
-  string mode = 1;
-  map<string, string> params = 2;
-}
-
-message AgentEvent {
-  enum EventType {
-    EVENT_TYPE_UNSPECIFIED = 0;
-    EVENT_TYPE_THINKING = 1;
-    EVENT_TYPE_TOOL_USE = 2;
-    EVENT_TYPE_DONE = 3;
-    EVENT_TYPE_ERROR = 4;
-  }
-  EventType type = 1;
-  string text = 2;
-  string task_id = 3;
-  string session_id = 4;
-  TaskResult result = 5;
-  int64 timestamp = 6;
-}
-
-message TaskResult {
-  string status = 1;
-  string summary = 2;
-  map<string, string> structured = 3;
-  CostInfo cost = 4;
-  repeated string notify = 5;
-}
-
-message CostInfo {
-  double usd = 1;
-  int32 turns = 2;
-  int64 duration_ms = 3;
-}
-
-message GetStatusRequest {}
-
-message GetStatusResponse {
-  string status = 1;
-  string task_id = 2;
-  string mode = 3;
-  string session_id = 4;
-  TaskResult result = 5;
-  string last_output = 6;
-}
-
-message GetHealthRequest {}
-
-message GetHealthResponse {
-  bool up = 1;
-  bool has_task = 2;
-}
-
-message CancelTaskRequest {
-  string task_id = 1;
-}
-
-message CancelTaskResponse {
-  string status = 1;
-}
-
-message ListAgentsRequest {}
-
-message ListAgentsResponse {
-  repeated AgentInfo agents = 1;
-}
-
-message AgentInfo {
-  string name = 1;
-  string display_name = 2;
-  string role = 3;
-  repeated ModeInfo modes = 4;
-  bool online = 5;
-}
-
-message ModeInfo {
-  string name = 1;
-  string description = 2;
-  string model = 3;
-  int32 max_turns = 4;
-}
-
-message GetAgentStatusRequest {
-  string agent = 1;
-}
-
-message GetAgentStatusResponse {
-  bool up = 1;
-  string status = 2;
-  string mode = 3;
-  CostInfo last_cost = 4;
-}

package/src/init/wizard.mjs

@@ -1,38 +0,0 @@
-import readline from 'node:readline';
-
-/**
- * Prompts the user for a value, showing a default in brackets.
- * Returns the default if the user presses Enter without typing.
- */
-function prompt(rl, question, defaultValue) {
-  return new Promise((resolve) => {
-    const display = defaultValue ? `${question} [${defaultValue}]: ` : `${question}: `;
-    rl.question(display, (answer) => {
-      resolve(answer.trim() || defaultValue || '');
-    });
-  });
-}
-
-/**
- * Runs the interactive CLI wizard.
- * Returns an object with the user's answers.
- *
- * @param {object} [opts] - Optional overrides for testing
- * @param {NodeJS.ReadableStream} [opts.input] - Readable stream (default: process.stdin)
- * @param {NodeJS.WritableStream} [opts.output] - Writable stream (default: process.stdout)
- * @returns {Promise<{agentsDir: string, flyOrg: string, firstAgentName: string}>}
- */
-export async function runWizard({ input = process.stdin, output = process.stdout } = {}) {
-  const rl = readline.createInterface({ input, output, terminal: false });
-
-  output.write('\nSWARP init — setting up your agent swarm\n');
-  output.write('─'.repeat(44) + '\n\n');
-
-  const agentsDir = await prompt(rl, 'Agents directory', 'agents/');
-  const flyOrg = await prompt(rl, 'Fly.io org name', '');
-  const firstAgentName = await prompt(rl, 'First agent name', 'example');
-
-  rl.close();
-
-  return { agentsDir, flyOrg, firstAgentName };
-}

package/src/skill/generate.mjs

@@ -1,141 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import yaml from 'js-yaml';
-
-/**
- * Scans the agents directory, reads each agent.yaml, and generates
- * a SKILL.md tailored to the user's actual agents and modes.
- *
- * @param {object} opts
- * @param {string} opts.agentsDir - Absolute path to agents directory
- * @param {string} opts.routerUrl - Router gRPC address
- * @returns {string} Rendered SKILL.md content
- */
-export function generateSkill({ agentsDir, routerUrl }) {
-  const agents = scanAgents(agentsDir);
-
-  let md = `# /swarp
-
-Use this skill when dispatching tasks to SWARP agents, checking agent status, or managing deployments.
-
-## Available Agents
-
-`;
-
-  if (agents.length === 0) {
-    md += `No agents found in \`${agentsDir}\`. Run \`npx @swarp/cli init\` to create one.\n`;
-  } else {
-    for (const agent of agents) {
-      md += `### \`${agent.name}\`\n\n`;
-      if (agent.modes.length > 0) {
-        md += '| Mode | Description | Model | Timeout |\n';
-        md += '|------|-------------|-------|--------|\n';
-        for (const mode of agent.modes) {
-          const desc = mode.description || '—';
-          const model = mode.model || 'default';
-          const timeout = mode.timeout_minutes ? `${mode.timeout_minutes}m` : '30m';
-          md += `| \`${mode.name}\` | ${desc} | ${model} | ${timeout} |\n`;
-        }
-        md += '\n';
-      }
-    }
-  }
-
-  md += `## MCP Tools
-
-The SWARP MCP server registers one tool per agent, plus management tools.
-
-### Agent tools (one per agent above)
-
-Each agent tool accepts:
-- \`mode\` (required): one of the modes listed above
-- \`params\` (optional): key-value pairs interpolated into the mode prompt
-- \`session_id\` (optional): resume an existing session
-
-Example:
-\`\`\`
-`;
-
-  if (agents.length > 0) {
-    const first = agents[0];
-    const firstMode = first.modes[0]?.name || 'implement';
-    md += `Use the \`${first.name}\` tool with mode "${firstMode}" and params.task = "Add error handling to the API"\n`;
-  } else {
-    md += `Use the \`agent-name\` tool with mode "implement" and params.task = "..."\n`;
-  }
-
-  md += `\`\`\`
-
-### Management tools
-
-| Tool | Description |
-|------|-------------|
-| \`swarm_status\` | Check if an agent is online |
-| \`swarm_audit\` | Validate all agent.yaml files |
-| \`swarm_generate\` | Regenerate runner configs |
-| \`swarm_deploy\` | Deploy an agent (destructive — confirm first) |
-
-## CLI
-
-\`\`\`bash
-npx @swarp/cli status             # All agents
-npx @swarp/cli status <agent>     # Specific agent
-npx @swarp/cli audit              # Validate configs
-npx @swarp/cli deploy <agent>     # Deploy one agent
-npx @swarp/cli deploy --all       # Deploy all
-npx @swarp/cli certs generate     # Generate mTLS keypairs
-\`\`\`
-
-## Configuration
-
-Router: \`${routerUrl}\`
-Agents directory: \`${path.relative(process.cwd(), agentsDir) || agentsDir}\`
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| \`SWARP_SPRITES_TOKEN\` | For deploy | Fly Sprites API token |
-| \`SWARP_ROUTER_URL\` | For gRPC | Router address (overrides .swarp.json) |
-
-**Security:** \`SWARP_SPRITES_TOKEN\` must be set in the environment — never loaded from .env files.
-`;
-
-  return md;
-}
-
-/**
- * Reads all agent.yaml files from the agents directory.
- *
- * @param {string} agentsDir
- * @returns {Array<{name: string, modes: Array<{name: string, description?: string, model?: string, timeout_minutes?: number}>}>}
- */
-function scanAgents(agentsDir) {
-  if (!fs.existsSync(agentsDir)) return [];
-
-  const entries = fs.readdirSync(agentsDir, { withFileTypes: true });
-  const agents = [];
-
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const yamlPath = path.join(agentsDir, entry.name, 'agent.yaml');
-    if (!fs.existsSync(yamlPath)) continue;
-
-    try {
-      const config = yaml.load(fs.readFileSync(yamlPath, 'utf8'));
-      agents.push({
-        name: config.name || entry.name,
-        modes: (config.modes || []).map((m) => ({
-          name: m.name,
-          description: m.description,
-          model: m.model,
-          timeout_minutes: m.timeout_minutes,
-        })),
-      });
-    } catch {
-      // Skip malformed configs — swarm_audit will catch them
-    }
-  }
-
-  return agents.sort((a, b) => a.name.localeCompare(b.name));
-}