plumb-bridge 0.1.2 → 0.1.3

package/src/cli.ts

@@ -2,24 +2,222 @@
 // plumb wrap <cli> --port <n>
 // That's the interface. Nothing else.
 
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { Command } from 'commander';
 import express from 'express';
 import { createPlumbServer } from './core/server.ts';
-import { detectAdapter } from './adapters/registry.ts';
-
-function log(level: string, msg: string, data?: Record<string, unknown>): void {
-  process.stderr.write(JSON.stringify({
-    ts: new Date().toISOString(),
-    l: level,
-    m: msg,
-    ...(data ?? {}),
-  }) + '\n');
+import { detectAdapter, detectAll } from './adapters/registry.ts';
+import { loadFleetConfig, validateFleetConfig, agentToPlumbConfig, resolveConfigPath } from './config.ts';
+
+function readPackageVersion(): string {
+  try {
+    const root = join(dirname(fileURLToPath(import.meta.url)), '..');
+    const raw = readFileSync(join(root, 'package.json'), 'utf8');
+    return (JSON.parse(raw) as { version?: string }).version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
 }
 
+import { log } from './core/log.ts';
+
 const program = new Command()
   .name('plumb')
   .description('Quiet pipes for noisy agents. A2A bridge for any CLI coding agent.')
-  .version('0.1.0');
+  .version(readPackageVersion());
+
+// ─── Fleet commands (Wave 2) ────────────────────────────────────────────
+
+const fleet = program
+  .command('fleet')
+  .description('Manage multi-agent fleet (plumb.yaml)');
+
+fleet
+  .command('validate')
+  .description('Parse and validate plumb.yaml')
+  .option('-c, --config <path>', 'Path to plumb.yaml')
+  .action(async (opts: { config?: string }) => {
+    const path = resolveConfigPath(opts.config);
+    if (!path) {
+      log('error', 'config_not_found', { searched: opts.config ?? '(default paths)' });
+      process.exit(1);
+    }
+
+    try {
+      const config = loadFleetConfig(path);
+      if (!config) {
+        log('error', 'config_empty', { path });
+        process.exit(1);
+      }
+
+      log('info', 'config_parsed', { path, agentCount: config.agents.length });
+
+      const validation = await validateFleetConfig(config);
+      for (const agent of validation.agents) {
+        if (agent.errors.length > 0) {
+          for (const e of agent.errors) log('error', 'validation_error', { agent: agent.id, error: e });
+        }
+        if (agent.warnings.length > 0) {
+          for (const w of agent.warnings) log('warn', 'validation_warning', { agent: agent.id, warning: w });
+        }
+      }
+
+      if (!validation.valid) {
+        log('error', 'validation_failed', { agentCount: config.agents.length });
+        process.exit(1);
+      }
+
+      log('info', 'validation_passed', { agentCount: config.agents.length });
+    } catch (err) {
+      log('error', 'config_error', { error: err instanceof Error ? err.message : String(err) });
+      process.exit(1);
+    }
+  });
+
+fleet
+  .command('status')
+  .description('Check health of all fleet agents')
+  .option('-c, --config <path>', 'Path to plumb.yaml')
+  .option('--timeout <ms>', 'Per-agent health check timeout', '5000')
+  .action(async (opts: { config?: string; timeout?: string }) => {
+    const path = resolveConfigPath(opts.config);
+    if (!path) {
+      log('error', 'config_not_found', { searched: opts.config ?? '(default paths)' });
+      process.exit(1);
+    }
+
+    const config = loadFleetConfig(path);
+    if (!config) {
+      log('error', 'config_empty', { path });
+      process.exit(1);
+    }
+
+    const timeout = parseInt(opts.timeout ?? '5000', 10);
+    log('info', 'fleet_status_check', { agentCount: config.agents.length });
+
+    const checks = config.agents.map(async (agent) => {
+      try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), timeout);
+
+        const url = `http://localhost:${agent.port}/health`;
+        const res = await fetch(url, { signal: ctrl.signal });
+        clearTimeout(timer);
+
+        if (res.ok) {
+          const body = await res.json().catch(() => ({})) as Record<string, unknown>;
+          const bodyStatus = typeof body.status === 'string' ? body.status : 'ok';
+          log('info', 'fleet_agent_healthy', {
+            id: agent.id,
+            port: agent.port,
+            status: bodyStatus,
+          });
+          return { id: agent.id, port: agent.port, healthy: true, status: bodyStatus };
+        }
+
+        log('warn', 'fleet_agent_unhealthy', { id: agent.id, port: agent.port, httpStatus: res.status });
+        return { id: agent.id, port: agent.port, healthy: false, status: `HTTP ${res.status}` };
+      } catch (err) {
+        log('warn', 'fleet_agent_down', {
+          id: agent.id,
+          port: agent.port,
+          error: err instanceof Error ? err.message : String(err),
+        });
+        return { id: agent.id, port: agent.port, healthy: false, status: 'unreachable' };
+      }
+    });
+
+    const results = await Promise.all(checks);
+    const healthy = results.filter(r => r.healthy).length;
+    const total = results.length;
+
+    log('info', 'fleet_status_summary', {
+      healthy,
+      total,
+      allHealthy: healthy === total,
+    });
+
+    if (healthy < total) process.exit(1);
+  });
+
+fleet
+  .command('up')
+  .description('Boot all agents defined in plumb.yaml')
+  .option('-c, --config <path>', 'Path to plumb.yaml')
+  .action(async (opts: { config?: string }) => {
+    const path = resolveConfigPath(opts.config);
+    if (!path) {
+      log('error', 'config_not_found', { searched: opts.config ?? '(default paths)' });
+      process.exit(1);
+    }
+
+    try {
+      const config = loadFleetConfig(path);
+      if (!config) {
+        log('error', 'config_empty', { path });
+        process.exit(1);
+      }
+
+      const validation = await validateFleetConfig(config);
+      if (!validation.valid) {
+        for (const agent of validation.agents) {
+          for (const e of agent.errors) log('error', 'validation_error', { agent: agent.id, error: e });
+        }
+        log('error', 'fleet_up_aborted', { reason: 'validation_failed' });
+        process.exit(1);
+      }
+
+      // Spawn all agents
+      type FleetServer = {
+        id: string;
+        port: number;
+        executor: import('./core/executor.ts').PlumbExecutor;
+        server: import('http').Server;
+      };
+      const fleetServers: FleetServer[] = [];
+      for (const agent of config.agents) {
+        const adapter = detectAdapter(agent.cli);
+        log('info', 'fleet_spawning', { id: agent.id, cli: agent.cli, port: agent.port, adapter: adapter.id });
+
+        const { executor, setupApp } = createPlumbServer({
+          ...agentToPlumbConfig(agent),
+          adapter,
+        });
+
+        const app = express();
+        setupApp(app);
+
+        const server = app.listen(agent.port, () => {
+          log('info', 'fleet_agent_up', { id: agent.id, port: agent.port });
+        });
+
+        fleetServers.push({ id: agent.id, port: agent.port, executor, server });
+      }
+
+      log('info', 'fleet_up', { agentCount: fleetServers.length, ports: fleetServers.map(s => s.port) });
+
+      // Graceful shutdown — mirrors wrap command behavior
+      const fleetShutdown = async () => {
+        log('info', 'fleet_shutdown', {});
+        await Promise.allSettled(fleetServers.map(s => s.executor.shutdown()));
+        await Promise.allSettled(fleetServers.map(s => new Promise<void>(r => s.server.close(() => r()))));
+        process.exit(0);
+      };
+
+      process.on('SIGINT', fleetShutdown);
+      process.on('SIGTERM', fleetShutdown);
+
+      // Block until signal
+      await new Promise<void>(() => {});
+    } catch (err) {
+      log('error', 'fleet_up_error', { error: err instanceof Error ? err.message : String(err) });
+      process.exit(1);
+    }
+  });
+
+// ─── Wrap command ────────────────────────────────────────────────────
 
 program
   .command('wrap <cli>')
@@ -45,6 +243,13 @@ program
     const adapter = detectAdapter(cli);
     log('info', 'adapter_detected', { cli, adapter: adapter.id, mode: adapter.mode, tier: adapter.tier });
 
+    // Boot-time adapter matrix — logs all registered adapters once
+    detectAll().then(results => {
+      log('info', 'adapter_matrix', { results });
+    }).catch(err => {
+      log('warn', 'adapter_matrix_error', { error: err instanceof Error ? err.message : String(err) });
+    });
+
     const { executor, setupApp } = createPlumbServer({
       adapter,
       cli,

package/src/config.test.ts

@@ -0,0 +1,170 @@
+// PLUMB — Config tests (Wave 2)
+// Tests for plumb.yaml parsing, validation, and CLI commands.
+
+import { describe, it, expect } from 'bun:test';
+import { writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+// We test loadFleetConfig and validateFleetConfig via import
+let loadFleetConfig: typeof import('./config.ts').loadFleetConfig;
+let validateFleetConfig: typeof import('./config.ts').validateFleetConfig;
+let resolveConfigPath: typeof import('./config.ts').resolveConfigPath;
+
+// Lazy import to avoid module side-effects
+async function setup() {
+  const mod = await import('./config.ts');
+  loadFleetConfig = mod.loadFleetConfig;
+  validateFleetConfig = mod.validateFleetConfig;
+  resolveConfigPath = mod.resolveConfigPath;
+}
+
+function tmpFile(content: string): string {
+  const p = join(tmpdir(), `plumb-test-${Date.now()}-${Math.random().toString(36).slice(2)}.yaml`);
+  writeFileSync(p, content);
+  return p;
+}
+
+describe('loadFleetConfig', () => {
+  it('parses a valid plumb.yaml', async () => {
+    await setup();
+    const path = tmpFile(`
+version: "1"
+agents:
+  - id: pi
+    cli: pi
+    port: 3001
+    mode: persistent
+  - id: cursor
+    cli: cursor-agent --print
+    port: 3002
+`);
+    const config = loadFleetConfig!(path);
+    expect(config).not.toBeNull();
+    expect(config!.version).toBe('1');
+    expect(config!.agents).toHaveLength(2);
+    expect(config!.agents[0].id).toBe('pi');
+    expect(config!.agents[0].port).toBe(3001);
+    expect(config!.agents[0].mode).toBe('persistent');
+    expect(config!.agents[1].id).toBe('cursor');
+    expect(config!.agents[1].port).toBe(3002);
+    unlinkSync(path);
+  });
+
+  it('rejects missing agents field', async () => {
+    await setup();
+    const path = tmpFile(`version: "1"\n`);
+    expect(() => loadFleetConfig!(path)).toThrow('agents');
+    unlinkSync(path);
+  });
+
+  it('rejects agents without id', async () => {
+    await setup();
+    const path = tmpFile(`
+version: "1"
+agents:
+  - cli: cat
+    port: 3001
+`);
+    expect(() => loadFleetConfig!(path)).toThrow('id');
+    unlinkSync(path);
+  });
+
+  it('rejects agents without cli', async () => {
+    await setup();
+    const path = tmpFile(`
+version: "1"
+agents:
+  - id: test
+    port: 3001
+`);
+    expect(() => loadFleetConfig!(path)).toThrow('cli');
+    unlinkSync(path);
+  });
+
+  it('rejects invalid port', async () => {
+    await setup();
+    const path = tmpFile(`
+version: "1"
+agents:
+  - id: test
+    cli: cat
+    port: 99999
+`);
+    expect(() => loadFleetConfig!(path)).toThrow('port');
+    unlinkSync(path);
+  });
+
+  it('returns null when file does not exist', async () => {
+    await setup();
+    const result = resolveConfigPath!('/nonexistent/plumb.yaml');
+    expect(result).toBeNull();
+  });
+
+  it('parses optional fields', async () => {
+    await setup();
+    const path = tmpFile(`
+version: "1"
+agents:
+  - id: venom
+    cli: venom --mode rpc
+    port: 4000
+    mode: oneshot
+    timeout: 600
+    labels: [heavy, deep]
+    env:
+      API_KEY: "\${VENOM_KEY}"
+`);
+    const config = loadFleetConfig!(path);
+    expect(config!.agents[0].timeout).toBe(600);
+    expect(config!.agents[0].labels).toEqual(['heavy', 'deep']);
+    expect(config!.agents[0].env?.API_KEY).toBe('${VENOM_KEY}');
+    unlinkSync(path);
+  });
+});
+
+describe('validateFleetConfig', () => {
+  it('detects duplicate ports', async () => {
+    await setup();
+    const config = {
+      version: '1',
+      agents: [
+        { id: 'a', cli: 'cat', port: 3001 },
+        { id: 'b', cli: 'cat', port: 3001 },
+      ],
+    };
+    // validate is async, calls detectAll which does real binary checks
+    // We test it runs without throw and reports errors
+    const result = await validateFleetConfig!(config as any);
+    expect(result.valid).toBe(false);
+    const portErrors = result.agents.filter(a => a.errors.some(e => e.includes('port')));
+    expect(portErrors.length).toBeGreaterThan(0);
+  });
+
+  it('detects duplicate ids', async () => {
+    await setup();
+    const config = {
+      version: '1',
+      agents: [
+        { id: 'dup', cli: 'cat', port: 3001 },
+        { id: 'dup', cli: 'cat', port: 3002 },
+      ],
+    };
+    const result = await validateFleetConfig!(config as any);
+    expect(result.valid).toBe(false);
+    const idErrors = result.agents.filter(a => a.errors.some(e => e.includes('duplicate agent id')));
+    expect(idErrors.length).toBeGreaterThan(0);
+  });
+
+  it('passes for a valid single-agent config', async () => {
+    await setup();
+    const config = {
+      version: '1',
+      agents: [
+        { id: 'echo', cli: 'cat', port: 3099 },
+      ],
+    };
+    const result = await validateFleetConfig!(config as any);
+    expect(result.valid).toBe(true);
+  });
+});

package/src/config.ts

@@ -0,0 +1,178 @@
+// PLUMB — Config (Wave 2)
+// Declarative plumb.yaml fleet definition.
+// Parsed at boot. Immutable while running.
+// Plumb is a bridge, not an orchestrator — config is for validation + codegen.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { load as parseYaml } from 'js-yaml';
+import type { PlumbConfig } from './types.ts';
+
+export interface FleetAgent {
+  /** Stable identifier used in logs, ledger, and future Pulse. */
+  id: string;
+  /** CLI command string (same as `plumb wrap <cli>`). */
+  cli: string;
+  /** HTTP port for this agent's A2A server. */
+  port: number;
+  /** Oneshot (process-per-task) or persistent (single long-running process). */
+  mode?: 'oneshot' | 'persistent';
+  /** Working directory override. */
+  workdir?: string;
+  /** Task timeout in seconds (default 300). */
+  timeout?: number;
+  /** Display name override for agent card. */
+  name?: string;
+  /** Bearer token for /a2a endpoints. */
+  apiKey?: string;
+  /** Environment variables (supports ${VAR} substitution). */
+  env?: Record<string, string>;
+  /** Labels for routing / documentation. */
+  labels?: string[];
+  /** Enable session store (Cursor only). */
+  sessionStore?: boolean;
+}
+
+export interface FleetConfig {
+  version: string;
+  agents: FleetAgent[];
+}
+
+export interface FleetValidation {
+  valid: boolean;
+  agents: Array<{
+    id: string;
+    cli: string;
+    port: number;
+    errors: string[];
+    warnings: string[];
+  }>;
+}
+
+const DEFAULT_PATHS = ['plumb.yaml', 'plumb.yml', './config/plumb.yaml'];
+
+/**
+ * Resolve plumb.yaml path. Checks default paths if none given.
+ * Returns null if no file found (optional config).
+ */
+export function resolveConfigPath(customPath?: string): string | null {
+  if (customPath) {
+    return existsSync(customPath) ? customPath : null;
+  }
+  for (const p of DEFAULT_PATHS) {
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+/**
+ * Load and parse plumb.yaml.
+ * Throws on parse errors. Returns null if no file found.
+ */
+export function loadFleetConfig(path?: string): FleetConfig | null {
+  const resolved = resolveConfigPath(path);
+  if (!resolved) return null;
+
+  const raw = readFileSync(resolved, 'utf8');
+  const parsed = parseYaml(raw) as Record<string, unknown>;
+
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`${resolved}: invalid YAML — expected a document`);
+  }
+
+  const version = String(parsed.version ?? '1');
+  const agentsRaw = parsed.agents;
+
+  if (!Array.isArray(agentsRaw)) {
+    throw new Error(`${resolved}: missing or invalid 'agents' list`);
+  }
+
+  const agents: FleetAgent[] = agentsRaw.map((a: Record<string, unknown>, i: number) => {
+    if (!a || typeof a !== 'object') {
+      throw new Error(`${resolved}: agents[${i}] is not an object`);
+    }
+    if (!a.id || typeof a.id !== 'string') {
+      throw new Error(`${resolved}: agents[${i}] missing required string field 'id'`);
+    }
+    if (!a.cli || typeof a.cli !== 'string') {
+      throw new Error(`${resolved}: agents[${i}] ('${a.id}') missing required string field 'cli'`);
+    }
+    const port = typeof a.port === 'number' ? a.port : parseInt(String(a.port), 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+      throw new Error(`${resolved}: agents[${i}] ('${a.id}') invalid 'port' — must be 1-65535`);
+    }
+
+    return {
+      id: a.id as string,
+      cli: a.cli as string,
+      port,
+      mode: (a.mode as 'oneshot' | 'persistent') ?? undefined,
+      workdir: a.workdir as string | undefined,
+      timeout: typeof a.timeout === 'number' ? a.timeout : undefined,
+      name: a.name as string | undefined,
+      apiKey: a.apiKey as string | undefined,
+      env: a.env as Record<string, string> | undefined,
+      labels: Array.isArray(a.labels) ? (a.labels as string[]) : undefined,
+      sessionStore: a.sessionStore as boolean | undefined,
+    };
+  });
+
+  return { version, agents };
+}
+
+/**
+ * Validate a fleet config against registered adapters.
+ * Checks: binary exists, port unique, no duplicate IDs.
+ */
+export async function validateFleetConfig(config: FleetConfig): Promise<FleetValidation> {
+  const { detectAll } = await import('./adapters/registry.ts');
+  const detection = await detectAll();
+  const seenPorts = new Set<number>();
+  const seenIds = new Set<string>();
+  const results: FleetValidation['agents'] = [];
+
+  for (const agent of config.agents) {
+    const errors: string[] = [];
+    const warnings: string[] = [];
+
+    if (seenIds.has(agent.id)) {
+      errors.push(`duplicate agent id '${agent.id}'`);
+    }
+    seenIds.add(agent.id);
+
+    if (seenPorts.has(agent.port)) {
+      errors.push(`port ${agent.port} is already in use by another agent`);
+    }
+    seenPorts.add(agent.port);
+
+    const match = detection.find(d =>
+      agent.cli.includes(d.name.toLowerCase()) ||
+      (typeof d.path === 'string' && d.path.includes(agent.cli.split(/[/\s]/).filter(Boolean).pop() ?? agent.cli))
+    );
+
+    if (!match || !match.found) {
+      warnings.push(`no registered adapter matches '${agent.cli}' — will fall back to generic adapter`);
+    }
+
+    results.push({ id: agent.id, cli: agent.cli, port: agent.port, errors, warnings });
+  }
+
+  return {
+    valid: results.every(r => r.errors.length === 0),
+    agents: results,
+  };
+}
+
+/**
+ * Build a PlumbConfig for a single fleet agent.
+ */
+export function agentToPlumbConfig(agent: FleetAgent): PlumbConfig & { adapterName?: string } {
+  return {
+    cli: agent.cli,
+    port: agent.port,
+    name: agent.name,
+    workdir: agent.workdir,
+    taskTimeout: agent.timeout ?? 300,
+    apiKey: agent.apiKey,
+    env: agent.env,
+  };
+}