buildvia-agent-runner 1.0.0

package/README.md

@@ -0,0 +1,80 @@
+# @buildvia/agent-runner
+
+Local bridge between Buildvia's cloud backend and the Salesforce DX MCP Server.
+
+## Why this exists
+
+When you use Demo Builder or Dev Agent in Buildvia, an AI agent (Claude Sonnet, running on Buildvia's servers) needs to read and write to your Salesforce org. We don't want your Salesforce OAuth tokens leaving your machine — so this runner lives on your laptop, holds the tokens locally (via your existing `sf` CLI), and acts as a secure relay.
+
+```
+Buildvia (cloud)  ──WebSocket──  Agent Runner (your laptop)  ──stdio──  DX MCP Server  ──API──  Salesforce
+```
+
+## Install
+
+Requires Node.js 18+ and the Salesforce CLI installed.
+
+```bash
+# Install Node.js if you don't have it
+brew install node            # macOS
+# or download from nodejs.org
+
+# Install the Salesforce CLI if you don't have it
+npm install -g @salesforce/cli
+
+# Install the Agent Runner
+npm install -g @buildvia/agent-runner
+```
+
+## Setup (one-time)
+
+```bash
+# 1. Authenticate to your Buildvia workspace
+buildvia-agent login https://app.buildvia.ai
+
+# 2. Authorize the Salesforce orgs you want to use
+sf org login web -a my-partner-dev-org
+
+# 3. Verify everything is connected
+buildvia-agent status
+```
+
+## Daily use
+
+```bash
+# Start the runner (keep this running while using Buildvia)
+buildvia-agent start
+```
+
+Leave that terminal window open. When you start a Demo Builder or Dev Agent session in Buildvia, it will use this runner automatically.
+
+To stop, press Ctrl+C.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `buildvia-agent login [url]` | Authenticate to Buildvia (device code flow) |
+| `buildvia-agent logout` | Clear stored credentials |
+| `buildvia-agent orgs` | List Salesforce orgs available via sf CLI |
+| `buildvia-agent link-org <alias>` | Verify and tag an org for Buildvia use |
+| `buildvia-agent status` | Show runner status, auth state, available orgs |
+| `buildvia-agent start` | Start the runner (long-running) |
+
+## Security notes
+
+- Salesforce OAuth tokens NEVER leave your machine
+- Buildvia auth uses device code flow with refresh tokens stored in your OS-appropriate config dir
+- WebSocket connection to Buildvia uses TLS + bearer token
+- Local health endpoint (port 47821) only listens on 127.0.0.1
+- Production org connections are blocked by Buildvia (Demo Builder = Partner Dev only, Dev Agent = sandboxes only)
+
+## Troubleshooting
+
+**"command not found: npm"** — install Node.js: `brew install node`
+
+**"command not found: sf"** — install Salesforce CLI: `npm install -g @salesforce/cli`
+
+**"No authorized orgs"** — run `sf org login web -a <alias>` for each org
+
+**Runner won't connect** — check `buildvia-agent status` and verify auth is current

package/auth.js

@@ -0,0 +1,135 @@
+// Authentication for Buildvia workspace
+// Uses device-code flow: CLI shows a code, developer enters it on Buildvia web
+
+import Conf from 'conf';
+import open from 'open';
+import chalk from 'chalk';
+
+const config = new Conf({
+  projectName: 'buildvia-agent',
+  schema: {
+    workspaceUrl: { type: 'string' },
+    accessToken: { type: 'string' },
+    refreshToken: { type: 'string' },
+    userEmail: { type: 'string' },
+    userId: { type: 'string' },
+    expiresAt: { type: 'number' }
+  }
+});
+
+export async function login(workspaceUrl) {
+  if (!workspaceUrl) {
+    workspaceUrl = 'https://app.buildvia.ai';
+  }
+  workspaceUrl = workspaceUrl.replace(/\/$/, '');
+
+  console.log(chalk.cyan('\nStarting device authorization flow...\n'));
+
+  // Step 1: request a device code from Buildvia
+  const deviceCodeRes = await fetch(`${workspaceUrl}/api/agent-runner/device-code`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ clientId: 'buildvia-agent-runner' })
+  });
+
+  if (!deviceCodeRes.ok) {
+    throw new Error(`Failed to request device code: ${deviceCodeRes.statusText}`);
+  }
+
+  const { deviceCode, userCode, verificationUrl, interval } = await deviceCodeRes.json();
+
+  // Step 2: tell user to open browser and enter code
+  console.log(chalk.bold('To complete sign-in:'));
+  console.log(`  1. Open: ${chalk.cyan(verificationUrl)}`);
+  console.log(`  2. Enter code: ${chalk.bold.yellow(userCode)}`);
+  console.log(chalk.gray('\nOpening browser automatically...'));
+
+  try { await open(verificationUrl); } catch { /* user can do it manually */ }
+
+  // Step 3: poll for completion
+  console.log(chalk.gray('\nWaiting for authorization...'));
+  
+  const startTime = Date.now();
+  const maxWaitMs = 5 * 60 * 1000; // 5 minutes
+  
+  while (Date.now() - startTime < maxWaitMs) {
+    await sleep(interval * 1000);
+    
+    const tokenRes = await fetch(`${workspaceUrl}/api/agent-runner/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ deviceCode })
+    });
+
+    if (tokenRes.status === 202) {
+      // Still pending
+      process.stdout.write('.');
+      continue;
+    }
+
+    if (!tokenRes.ok) {
+      throw new Error(`Authorization failed: ${tokenRes.statusText}`);
+    }
+
+    const tokens = await tokenRes.json();
+    
+    config.set('workspaceUrl', workspaceUrl);
+    config.set('accessToken', tokens.accessToken);
+    config.set('refreshToken', tokens.refreshToken);
+    config.set('userEmail', tokens.userEmail);
+    config.set('userId', tokens.userId);
+    config.set('expiresAt', Date.now() + (tokens.expiresIn * 1000));
+    
+    console.log(chalk.green(`\n\nSigned in as ${tokens.userEmail}`));
+    return;
+  }
+
+  throw new Error('Authorization timed out after 5 minutes');
+}
+
+export async function logout() {
+  config.clear();
+}
+
+export async function getStoredAuth() {
+  const workspaceUrl = config.get('workspaceUrl');
+  const accessToken = config.get('accessToken');
+  
+  if (!workspaceUrl || !accessToken) return null;
+
+  // Refresh if expired
+  const expiresAt = config.get('expiresAt');
+  if (expiresAt && Date.now() > expiresAt - 60000) {
+    await refreshTokens();
+  }
+
+  return {
+    workspaceUrl: config.get('workspaceUrl'),
+    accessToken: config.get('accessToken'),
+    userEmail: config.get('userEmail'),
+    userId: config.get('userId')
+  };
+}
+
+async function refreshTokens() {
+  const workspaceUrl = config.get('workspaceUrl');
+  const refreshToken = config.get('refreshToken');
+  if (!workspaceUrl || !refreshToken) throw new Error('Not authenticated');
+
+  const res = await fetch(`${workspaceUrl}/api/agent-runner/refresh`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ refreshToken })
+  });
+
+  if (!res.ok) throw new Error('Token refresh failed — please run login again');
+
+  const tokens = await res.json();
+  config.set('accessToken', tokens.accessToken);
+  config.set('refreshToken', tokens.refreshToken);
+  config.set('expiresAt', Date.now() + (tokens.expiresIn * 1000));
+}
+
+function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}

package/bin/buildvia-agent.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+// CLI entry point for the Buildvia Agent Runner
+
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { login, logout, getStoredAuth } from '../auth.js';
+import { listOrgs, linkOrg } from '../sf-cli.js';
+import { startRunner } from '../runner.js';
+import { getStatus } from '../status.js';
+
+const program = new Command();
+
+program
+  .name('buildvia-agent')
+  .description('Buildvia Agent Runner — local bridge to Salesforce')
+  .version('1.0.0')
+  .showHelpAfterError();
+
+// Login command
+program
+  .command('login [workspace-url]')
+  .description('Authenticate to your Buildvia workspace')
+  .action(async (workspaceUrl) => {
+    try {
+      await login(workspaceUrl);
+      console.log(chalk.green('✓ Successfully authenticated to Buildvia'));
+    } catch (err) {
+      console.error(chalk.red('✗ Login failed:'), err.message);
+      process.exit(1);
+    }
+  });
+
+// Logout command
+program
+  .command('logout')
+  .description('Clear stored Buildvia credentials')
+  .action(async () => {
+    await logout();
+    console.log(chalk.green('✓ Logged out'));
+  });
+
+// List orgs command (shows what sf CLI orgs are available)
+program
+  .command('orgs')
+  .description('List Salesforce orgs available via sf CLI')
+  .action(async () => {
+    try {
+      const orgs = await listOrgs();
+      if (orgs.length === 0) {
+        console.log(chalk.yellow('No authorized orgs found.'));
+        console.log(chalk.gray('Run: sf org login web -a <alias>'));
+        return;
+      }
+      console.log(chalk.bold('\nAuthorized Salesforce orgs:\n'));
+      orgs.forEach(org => {
+        const sandboxBadge = org.isSandbox ? chalk.blue('[sandbox]') : chalk.yellow('[production]');
+        const devEdBadge = org.isDevHub ? chalk.magenta('[devhub]') : '';
+        console.log(`  ${chalk.cyan(org.alias)} ${sandboxBadge} ${devEdBadge}`);
+        console.log(`    ${chalk.gray(org.username)}`);
+        console.log(`    ${chalk.gray(org.instanceUrl)}\n`);
+      });
+    } catch (err) {
+      console.error(chalk.red('✗ Failed to list orgs:'), err.message);
+      process.exit(1);
+    }
+  });
+
+// Link org (verify org is accessible and tag it for Buildvia use)
+program
+  .command('link-org <alias>')
+  .description('Verify and link a Salesforce org for Buildvia use')
+  .action(async (alias) => {
+    try {
+      const result = await linkOrg(alias);
+      console.log(chalk.green(`✓ Org "${alias}" linked`));
+      console.log(chalk.gray(`  Type: ${result.isSandbox ? 'Sandbox' : result.isDevHub ? 'Dev Hub' : 'Production'}`));
+      console.log(chalk.gray(`  Edition: ${result.edition}`));
+    } catch (err) {
+      console.error(chalk.red('✗ Failed to link org:'), err.message);
+      process.exit(1);
+    }
+  });
+
+// Status command
+program
+  .command('status')
+  .description('Show Agent Runner status')
+  .action(async () => {
+    const status = await getStatus();
+    console.log(chalk.bold('\nBuildvia Agent Runner Status\n'));
+    console.log(`  Version:    ${chalk.cyan(status.version)}`);
+    console.log(`  Auth:       ${status.authenticated ? chalk.green('✓ Authenticated') : chalk.red('✗ Not authenticated')}`);
+    if (status.authenticated) {
+      console.log(`  Workspace:  ${chalk.cyan(status.workspaceUrl)}`);
+      console.log(`  User:       ${chalk.cyan(status.userEmail)}`);
+    }
+    console.log(`  sf CLI:     ${status.sfCliInstalled ? chalk.green('✓ Installed') : chalk.red('✗ Not found')}`);
+    console.log(`  DX MCP:     ${status.dxMcpAvailable ? chalk.green('✓ Available') : chalk.yellow('⚠ Not installed (will install on demand)')}`);
+    console.log(`  Orgs:       ${chalk.cyan(status.orgsCount)} authorized`);
+    console.log(`  Runner:     ${status.runnerActive ? chalk.green('● Running') : chalk.gray('○ Idle')}\n`);
+  });
+
+// Start command — opens the WebSocket connection to Buildvia and stays running
+program
+  .command('start')
+  .description('Start the Agent Runner (connects to Buildvia and waits for sessions)')
+  .option('-p, --port <port>', 'Local port for health endpoint', '47821')
+  .action(async (options) => {
+    const auth = await getStoredAuth();
+    if (!auth) {
+      console.error(chalk.red('✗ Not authenticated. Run: buildvia-agent login <workspace-url>'));
+      process.exit(1);
+    }
+    try {
+      await startRunner({ ...auth, port: parseInt(options.port) });
+    } catch (err) {
+      console.error(chalk.red('✗ Runner failed:'), err.message);
+      process.exit(1);
+    }
+  });
+
+program.parse(process.argv);

package/dx-mcp.js

@@ -0,0 +1,132 @@
+// Manages the Salesforce DX MCP Server subprocess
+// Per MCP spec: communication is JSON-RPC over stdin/stdout
+
+import { spawn } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+
+export class DxMcpProcess extends EventEmitter {
+  constructor({ orgAlias, toolsets = ['orgs', 'metadata', 'data', 'users'], allowNonGa = true }) {
+    super();
+    this.orgAlias = orgAlias;
+    this.toolsets = toolsets;
+    this.allowNonGa = allowNonGa;
+    this.proc = null;
+    this.requestId = 0;
+    this.pendingRequests = new Map();
+    this.buffer = '';
+  }
+
+  async start() {
+    const args = [
+      '-y', '@salesforce/dx-mcp-server',
+      '--orgs', this.orgAlias,
+      '--toolsets', this.toolsets.join(',')
+    ];
+    if (this.allowNonGa) args.push('--allow-non-ga-tools');
+
+    this.proc = spawn('npx', args, {
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    this.proc.stdout.on('data', (chunk) => this._onStdoutData(chunk));
+    this.proc.stderr.on('data', (chunk) => {
+      const msg = chunk.toString();
+      // DX MCP often logs to stderr as informational; emit but don't error
+      this.emit('log', msg);
+    });
+    this.proc.on('exit', (code) => {
+      this.emit('exit', code);
+      this._failAllPending(new Error(`MCP server exited with code ${code}`));
+    });
+    this.proc.on('error', (err) => this.emit('error', err));
+
+    // Initialize MCP handshake
+    await this._call('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      clientInfo: { name: 'buildvia-agent-runner', version: '0.1.0' }
+    });
+    
+    // Notify initialized
+    this._notify('notifications/initialized', {});
+  }
+
+  async listTools() {
+    const result = await this._call('tools/list', {});
+    return result.tools || [];
+  }
+
+  async callTool(name, args) {
+    return await this._call('tools/call', { name, arguments: args });
+  }
+
+  async stop() {
+    if (this.proc && !this.proc.killed) {
+      this.proc.kill('SIGTERM');
+      // Give it a moment to clean up
+      await new Promise(resolve => setTimeout(resolve, 500));
+      if (!this.proc.killed) this.proc.kill('SIGKILL');
+    }
+  }
+
+  // ── Internals ──
+
+  _call(method, params) {
+    return new Promise((resolve, reject) => {
+      const id = ++this.requestId;
+      const message = { jsonrpc: '2.0', id, method, params };
+      this.pendingRequests.set(id, { resolve, reject });
+      this.proc.stdin.write(JSON.stringify(message) + '\n');
+      
+      // Timeout after 60s
+      setTimeout(() => {
+        if (this.pendingRequests.has(id)) {
+          this.pendingRequests.delete(id);
+          reject(new Error(`MCP request ${method} timed out`));
+        }
+      }, 60000);
+    });
+  }
+
+  _notify(method, params) {
+    const message = { jsonrpc: '2.0', method, params };
+    this.proc.stdin.write(JSON.stringify(message) + '\n');
+  }
+
+  _onStdoutData(chunk) {
+    this.buffer += chunk.toString();
+    // Messages are newline-delimited JSON
+    let newlineIdx;
+    while ((newlineIdx = this.buffer.indexOf('\n')) !== -1) {
+      const line = this.buffer.slice(0, newlineIdx).trim();
+      this.buffer = this.buffer.slice(newlineIdx + 1);
+      if (!line) continue;
+      try {
+        const message = JSON.parse(line);
+        this._handleMessage(message);
+      } catch (err) {
+        this.emit('log', `Failed to parse MCP message: ${line}`);
+      }
+    }
+  }
+
+  _handleMessage(message) {
+    if (message.id !== undefined && this.pendingRequests.has(message.id)) {
+      const { resolve, reject } = this.pendingRequests.get(message.id);
+      this.pendingRequests.delete(message.id);
+      if (message.error) {
+        reject(new Error(`MCP error: ${message.error.message || JSON.stringify(message.error)}`));
+      } else {
+        resolve(message.result);
+      }
+    } else if (message.method) {
+      // Server-initiated notification — emit for handling
+      this.emit('notification', message);
+    }
+  }
+
+  _failAllPending(err) {
+    for (const { reject } of this.pendingRequests.values()) reject(err);
+    this.pendingRequests.clear();
+  }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+"name": "buildvia-agent-runner",
+  "version": "1.0.0",
+  "description": "Local bridge between Buildvia cloud backend and Salesforce DX MCP Server",
+  "type": "module",
+  "main": "./bin/buildvia-agent.js",
+  "files": [
+    "bin",
+    "*.js"
+  ],
+  "bin": {
+    "buildvia-agent": "bin/buildvia-agent.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node bin/buildvia-agent.js start",
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "buildvia",
+    "salesforce",
+    "mcp",
+    "agent",
+    "claude"
+  ],
+  "author": "Buildvia",
+  "license": "MIT",
+  "dependencies": {
+    "ws": "^8.16.0",
+    "commander": "^11.1.0",
+    "chalk": "^5.3.0",
+    "conf": "^12.0.0",
+    "open": "^10.0.0"
+  }
+}

package/runner.js

@@ -0,0 +1,200 @@
+// The main Runner — connects to Buildvia and relays tool calls to DX MCP
+
+import WebSocket from 'ws';
+import chalk from 'chalk';
+import http from 'node:http';
+import { DxMcpProcess } from './dx-mcp.js';
+import { listOrgs } from './sf-cli.js';
+
+export async function startRunner({ workspaceUrl, accessToken, userEmail, port }) {
+  // Active MCP sessions keyed by sessionId
+  const mcpSessions = new Map();
+
+  // Local health endpoint (Buildvia frontend can detect runner is alive)
+  startHealthServer(port, mcpSessions);
+
+  // Connect to Buildvia
+  const wsUrl = workspaceUrl.replace(/^http/, 'ws') + '/api/agent-runner/bridge';
+  
+  console.log(chalk.cyan(`Connecting to ${wsUrl} as ${userEmail}...`));
+  
+  const ws = new WebSocket(wsUrl, {
+    headers: { Authorization: `Bearer ${accessToken}` }
+  });
+
+  ws.on('open', () => {
+    console.log(chalk.green('● Connected to Buildvia'));
+    console.log(chalk.gray(`Listening for sessions... (Ctrl+C to stop)`));
+    
+    // Send initial info about this runner
+    ws.send(JSON.stringify({
+      type: 'runner_ready',
+      version: '0.1.0',
+      capabilities: ['dx-mcp']
+    }));
+  });
+
+  ws.on('message', async (raw) => {
+    let msg;
+    try {
+      msg = JSON.parse(raw.toString());
+    } catch (err) {
+      console.error(chalk.red('Invalid message from Buildvia:'), err);
+      return;
+    }
+
+    try {
+      await handleMessage(msg, ws, mcpSessions);
+    } catch (err) {
+      console.error(chalk.red(`Error handling ${msg.type}:`), err.message);
+      ws.send(JSON.stringify({
+        type: 'error',
+        requestId: msg.requestId,
+        sessionId: msg.sessionId,
+        error: { message: err.message, stack: err.stack }
+      }));
+    }
+  });
+
+  ws.on('close', () => {
+    console.log(chalk.yellow('○ Disconnected from Buildvia'));
+    // Clean up all active MCP sessions
+    for (const session of mcpSessions.values()) {
+      session.mcp.stop().catch(() => {});
+    }
+    mcpSessions.clear();
+    console.log(chalk.gray('Reconnecting in 5 seconds...'));
+    setTimeout(() => startRunner({ workspaceUrl, accessToken, userEmail, port }), 5000);
+  });
+
+  ws.on('error', (err) => {
+    console.error(chalk.red('WebSocket error:'), err.message);
+  });
+
+  // Graceful shutdown
+  const shutdown = async () => {
+    console.log(chalk.yellow('\nShutting down...'));
+    for (const session of mcpSessions.values()) {
+      await session.mcp.stop().catch(() => {});
+    }
+    ws.close();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+async function handleMessage(msg, ws, mcpSessions) {
+  switch (msg.type) {
+    case 'list_orgs': {
+      const orgs = await listOrgs();
+      ws.send(JSON.stringify({
+        type: 'orgs_list',
+        requestId: msg.requestId,
+        orgs
+      }));
+      break;
+    }
+
+    case 'session_start': {
+      // Buildvia is starting a new agent session — spin up DX MCP for this org
+      const { sessionId, orgAlias, toolsets } = msg;
+      
+      console.log(chalk.cyan(`▶ Starting session ${sessionId} for org ${orgAlias}`));
+      
+      const mcp = new DxMcpProcess({
+        orgAlias,
+        toolsets: toolsets || ['orgs', 'metadata', 'data', 'users']
+      });
+      
+      mcp.on('log', (log) => {
+        // Optionally forward DX MCP logs to Buildvia for debugging
+      });
+      mcp.on('exit', (code) => {
+        console.log(chalk.gray(`MCP for session ${sessionId} exited (${code})`));
+        mcpSessions.delete(sessionId);
+        ws.send(JSON.stringify({
+          type: 'session_ended',
+          sessionId,
+          reason: 'mcp_exit'
+        }));
+      });
+
+      await mcp.start();
+      const tools = await mcp.listTools();
+      
+      mcpSessions.set(sessionId, { mcp, orgAlias, startedAt: Date.now() });
+      
+      ws.send(JSON.stringify({
+        type: 'session_ready',
+        requestId: msg.requestId,
+        sessionId,
+        tools: tools.map(t => ({ name: t.name, description: t.description, inputSchema: t.inputSchema }))
+      }));
+      console.log(chalk.green(`  ✓ Session ${sessionId} ready (${tools.length} tools)`));
+      break;
+    }
+
+    case 'tool_call': {
+      const { sessionId, requestId, toolName, arguments: args } = msg;
+      const session = mcpSessions.get(sessionId);
+      if (!session) {
+        throw new Error(`Session ${sessionId} not found`);
+      }
+      
+      console.log(chalk.gray(`  → ${toolName}`));
+      const startMs = Date.now();
+      const result = await session.mcp.callTool(toolName, args);
+      const durationMs = Date.now() - startMs;
+      
+      ws.send(JSON.stringify({
+        type: 'tool_result',
+        requestId,
+        sessionId,
+        result,
+        durationMs
+      }));
+      console.log(chalk.gray(`    ✓ ${toolName} (${durationMs}ms)`));
+      break;
+    }
+
+    case 'session_end': {
+      const { sessionId } = msg;
+      const session = mcpSessions.get(sessionId);
+      if (session) {
+        await session.mcp.stop();
+        mcpSessions.delete(sessionId);
+        console.log(chalk.cyan(`▶ Ended session ${sessionId}`));
+      }
+      break;
+    }
+
+    case 'ping': {
+      ws.send(JSON.stringify({ type: 'pong', requestId: msg.requestId }));
+      break;
+    }
+
+    default:
+      console.warn(chalk.yellow(`Unknown message type: ${msg.type}`));
+  }
+}
+
+function startHealthServer(port, mcpSessions) {
+  const server = http.createServer((req, res) => {
+    if (req.url === '/health') {
+      res.setHeader('Access-Control-Allow-Origin', '*');
+      res.setHeader('Content-Type', 'application/json');
+      res.end(JSON.stringify({
+        status: 'running',
+        version: '0.1.0',
+        activeSessions: mcpSessions.size
+      }));
+    } else {
+      res.statusCode = 404;
+      res.end('Not found');
+    }
+  });
+  server.listen(port, '127.0.0.1', () => {
+    console.log(chalk.gray(`Health endpoint on http://127.0.0.1:${port}/health`));
+  });
+}

package/sf-cli.js

@@ -0,0 +1,81 @@
+// Salesforce CLI integration
+// Calls `sf` CLI commands to interact with the developer's authorized orgs
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+export async function isSfCliInstalled() {
+  try {
+    await execFileAsync('sf', ['--version']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function listOrgs() {
+  if (!(await isSfCliInstalled())) {
+    throw new Error('Salesforce CLI not found. Install from https://developer.salesforce.com/tools/salesforcecli');
+  }
+
+  const { stdout } = await execFileAsync('sf', ['org', 'list', '--json']);
+  const result = JSON.parse(stdout);
+
+  const allOrgs = [
+    ...(result.result?.devHubs || []).map(o => ({ ...o, isDevHub: true })),
+    ...(result.result?.nonScratchOrgs || []),
+    ...(result.result?.sandboxes || []).map(o => ({ ...o, isSandbox: true })),
+    ...(result.result?.scratchOrgs || []).map(o => ({ ...o, isScratch: true }))
+  ];
+
+  return allOrgs.map(org => ({
+    alias: org.alias || org.username,
+    username: org.username,
+    instanceUrl: org.instanceUrl,
+    isSandbox: !!org.isSandbox,
+    isDevHub: !!org.isDevHub,
+    isScratch: !!org.isScratch,
+    orgId: org.orgId
+  }));
+}
+
+export async function getOrgInfo(alias) {
+  if (!(await isSfCliInstalled())) {
+    throw new Error('Salesforce CLI not found');
+  }
+
+  const { stdout } = await execFileAsync('sf', [
+    'org', 'display',
+    '--target-org', alias,
+    '--json'
+  ]);
+  const result = JSON.parse(stdout);
+  return result.result;
+}
+
+export async function linkOrg(alias) {
+  // Verify the org is accessible by fetching its details
+  const info = await getOrgInfo(alias);
+
+  // Determine sandbox vs production by querying the Organization object
+  const { stdout } = await execFileAsync('sf', [
+    'data', 'query',
+    '--query', 'SELECT IsSandbox, OrganizationType, InstanceName FROM Organization LIMIT 1',
+    '--target-org', alias,
+    '--json'
+  ]);
+  const queryResult = JSON.parse(stdout);
+  const orgRecord = queryResult.result?.records?.[0] || {};
+
+  return {
+    alias,
+    username: info.username,
+    instanceUrl: info.instanceUrl,
+    edition: orgRecord.OrganizationType || 'Unknown',
+    isSandbox: !!orgRecord.IsSandbox,
+    isDevHub: false, // we'd need a different query to detect this
+    orgId: info.id
+  };
+}

package/status.js

@@ -0,0 +1,51 @@
+// Status reporting for the CLI
+
+import { getStoredAuth } from './auth.js';
+import { isSfCliInstalled, listOrgs } from './sf-cli.js';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import http from 'node:http';
+
+const execFileAsync = promisify(execFile);
+
+export async function getStatus() {
+  const auth = await getStoredAuth();
+  const sfInstalled = await isSfCliInstalled();
+  
+  let orgsCount = 0;
+  if (sfInstalled) {
+    try {
+      const orgs = await listOrgs();
+      orgsCount = orgs.length;
+    } catch { /* ignore */ }
+  }
+
+  let dxMcpAvailable = false;
+  try {
+    await execFileAsync('npx', ['-y', '@salesforce/dx-mcp-server', '--version']);
+    dxMcpAvailable = true;
+  } catch { /* not installed yet, will install on demand */ }
+
+  // Check if a runner is already active locally on the health port
+  let runnerActive = false;
+  try {
+    runnerActive = await new Promise((resolve) => {
+      const req = http.get('http://127.0.0.1:47821/health', { timeout: 1000 }, (res) => {
+        resolve(res.statusCode === 200);
+      });
+      req.on('error', () => resolve(false));
+      req.on('timeout', () => { req.destroy(); resolve(false); });
+    });
+  } catch { /* not running */ }
+
+  return {
+    version: '0.1.0',
+    authenticated: !!auth,
+    workspaceUrl: auth?.workspaceUrl,
+    userEmail: auth?.userEmail,
+    sfCliInstalled: sfInstalled,
+    dxMcpAvailable,
+    orgsCount,
+    runnerActive
+  };
+}