@sonde/agent 0.2.3 → 0.2.4

package/src/cli/update.test.ts

@@ -0,0 +1,69 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { checkForUpdate, semverLt } from './update.js';
+
+describe('semverLt', () => {
+  it('returns true when a < b (major)', () => {
+    expect(semverLt('0.1.0', '1.0.0')).toBe(true);
+  });
+
+  it('returns true when a < b (minor)', () => {
+    expect(semverLt('1.0.0', '1.1.0')).toBe(true);
+  });
+
+  it('returns true when a < b (patch)', () => {
+    expect(semverLt('1.1.0', '1.1.1')).toBe(true);
+  });
+
+  it('returns false when equal', () => {
+    expect(semverLt('1.2.3', '1.2.3')).toBe(false);
+  });
+
+  it('returns false when a > b', () => {
+    expect(semverLt('2.0.0', '1.9.9')).toBe(false);
+  });
+});
+
+describe('checkForUpdate', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('returns update info when newer version is available', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: '99.0.0' }),
+    });
+
+    const result = await checkForUpdate();
+    expect(result.latestVersion).toBe('99.0.0');
+    expect(result.updateAvailable).toBe(true);
+  });
+
+  it('returns no update when on latest version', async () => {
+    // Use 0.0.0 which is lower than any real version
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({ version: '0.0.0' }),
+    });
+
+    const result = await checkForUpdate();
+    expect(result.updateAvailable).toBe(false);
+  });
+
+  it('throws on network error', async () => {
+    globalThis.fetch = vi.fn().mockRejectedValue(new Error('Network error'));
+
+    await expect(checkForUpdate()).rejects.toThrow('Network error');
+  });
+
+  it('throws on non-ok response', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 500,
+    });
+
+    await expect(checkForUpdate()).rejects.toThrow('Failed to check npm registry');
+  });
+});

package/src/cli/update.ts

@@ -0,0 +1,78 @@
+import { execFileSync } from 'node:child_process';
+import { VERSION } from '../version.js';
+
+/**
+ * Lightweight semver comparison: returns true if a < b.
+ */
+export function semverLt(a: string, b: string): boolean {
+  const pa = a.split('.').map(Number);
+  const pb = b.split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const av = pa[i] ?? 0;
+    const bv = pb[i] ?? 0;
+    if (av < bv) return true;
+    if (av > bv) return false;
+  }
+  return false;
+}
+
+/**
+ * Check for available updates by querying the npm registry.
+ */
+export async function checkForUpdate(): Promise<{
+  currentVersion: string;
+  latestVersion: string;
+  updateAvailable: boolean;
+}> {
+  const res = await fetch('https://registry.npmjs.org/@sonde/agent/latest', {
+    headers: { Accept: 'application/json' },
+    signal: AbortSignal.timeout(10_000),
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to check npm registry (HTTP ${res.status})`);
+  }
+  const data = (await res.json()) as { version?: string };
+  const latestVersion = data.version;
+  if (!latestVersion) {
+    throw new Error('No version found in npm registry response');
+  }
+
+  return {
+    currentVersion: VERSION,
+    latestVersion,
+    updateAvailable: semverLt(VERSION, latestVersion),
+  };
+}
+
+/**
+ * Perform the update by running npm install -g.
+ * After install, tries to restart the systemd service (best-effort).
+ */
+export function performUpdate(targetVersion: string): void {
+  console.log(`Installing @sonde/agent@${targetVersion}...`);
+  execFileSync('npm', ['install', '-g', `@sonde/agent@${targetVersion}`], {
+    stdio: 'inherit',
+    timeout: 120_000,
+  });
+
+  // Verify the installed version
+  const output = execFileSync('sonde', ['--version'], {
+    encoding: 'utf-8',
+    timeout: 5_000,
+  }).trim();
+  if (output !== targetVersion) {
+    throw new Error(`Version mismatch after install: expected ${targetVersion}, got ${output}`);
+  }
+
+  console.log(`Successfully updated to v${targetVersion}`);
+
+  // Best-effort systemd restart
+  try {
+    execFileSync('systemctl', ['restart', 'sonde-agent'], {
+      timeout: 10_000,
+    });
+    console.log('Restarted sonde-agent systemd service');
+  } catch {
+    // systemd not available or service not installed — that's fine
+  }
+}

package/src/config.ts

@@ -12,6 +12,7 @@ export interface AgentConfig {
   keyPath?: string;
   caCertPath?: string;
   scrubPatterns?: string[];
+  allowUnsignedPacks?: boolean;
 }
 
 const CONFIG_DIR = path.join(os.homedir(), '.sonde');
@@ -22,11 +23,24 @@ export function getConfigPath(): string {
 }
 
 export function loadConfig(): AgentConfig | undefined {
+  let raw: string;
+  try {
+    raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
+  } catch (err: unknown) {
+    const code = (err as { code?: string }).code;
+    if (code === 'ENOENT') return undefined;
+    if (code === 'EACCES') {
+      console.error(`Cannot read config at ${CONFIG_FILE}. Check file permissions.`);
+      process.exit(1);
+    }
+    return undefined;
+  }
+
   try {
-    const raw = fs.readFileSync(CONFIG_FILE, 'utf-8');
     return JSON.parse(raw) as AgentConfig;
   } catch {
-    return undefined;
+    console.error(`Config file corrupted at ${CONFIG_FILE}. Re-enroll with "sonde enroll".`);
+    process.exit(1);
   }
 }
 

package/src/index.ts

@@ -2,6 +2,7 @@
 
 import os from 'node:os';
 import { handlePacksCommand } from './cli/packs.js';
+import { checkForUpdate, performUpdate } from './cli/update.js';
 import { type AgentConfig, getConfigPath, loadConfig, saveConfig } from './config.js';
 import { AgentConnection, type ConnectionEvents, enrollWithHub } from './runtime/connection.js';
 import { ProbeExecutor } from './runtime/executor.js';
@@ -26,6 +27,8 @@ function printUsage(): void {
   console.log('  start     Start the agent (TUI by default, --headless for daemon)');
   console.log('  status    Show agent status');
   console.log('  packs     Manage packs (list, scan, install, uninstall)');
+  console.log('  update    Check for and install agent updates');
+  console.log('  mcp-bridge  stdio MCP bridge (for Claude Code integration)');
   console.log('');
   console.log('Enroll options:');
   console.log('  --hub <url>      Hub URL (e.g. http://localhost:3000)');
@@ -64,6 +67,21 @@ function createRuntime(events: ConnectionEvents): Runtime {
   return { config, executor, connection };
 }
 
+async function cmdUpdate(): Promise<void> {
+  console.log(`Current version: v${VERSION}`);
+  console.log('Checking for updates...');
+
+  const { latestVersion, updateAvailable } = await checkForUpdate();
+
+  if (!updateAvailable) {
+    console.log(`Already on the latest version (v${latestVersion}).`);
+    return;
+  }
+
+  console.log(`New version available: v${latestVersion}`);
+  performUpdate(latestVersion);
+}
+
 async function cmdEnroll(): Promise<void> {
   const hubUrl = getArg('--hub');
   const apiKey = getArg('--key');
@@ -129,6 +147,11 @@ function cmdStart(): void {
       config.agentId = agentId;
       saveConfig(config);
     },
+    onUpdateAvailable: (latestVersion, currentVersion) => {
+      console.log(
+        `Update available: v${currentVersion} → v${latestVersion}. Run "sonde update" to upgrade.`,
+      );
+    },
   });
 
   console.log(`Sonde Agent v${VERSION}`);
@@ -137,12 +160,15 @@ function cmdStart(): void {
   console.log('');
 
   connection.start();
+  process.stdin.unref();
 
-  process.on('SIGINT', () => {
+  const shutdown = () => {
     console.log('\nShutting down...');
     connection.stop();
     process.exit(0);
-  });
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
 }
 
 async function cmdManager(): Promise<void> {
@@ -190,8 +216,17 @@ switch (command) {
     });
     break;
   case 'enroll':
-    cmdEnroll().catch((err: Error) => {
-      console.error(`Enrollment failed: ${err.message}`);
+    cmdEnroll().catch((err: Error & { code?: string }) => {
+      if (err.code === 'ECONNREFUSED') {
+        const hubUrl = getArg('--hub') ?? 'the hub';
+        console.error(`Could not connect to hub at ${hubUrl}. Verify the hub is running.`);
+      } else if (err.message?.includes('401') || err.message?.includes('Unauthorized')) {
+        console.error('Authentication failed. Check your API key or enrollment token.');
+      } else if (err.message?.includes('timed out')) {
+        console.error('Enrollment timed out. The hub may be unreachable.');
+      } else {
+        console.error(`Enrollment failed: ${err.message}`);
+      }
       process.exit(1);
     });
     break;
@@ -199,8 +234,14 @@ switch (command) {
     if (hasFlag('--headless')) {
       cmdStart();
     } else {
-      cmdManager().catch((err: Error) => {
-        console.error(err.message);
+      cmdManager().catch((err: Error & { code?: string }) => {
+        if (err.code === 'ECONNREFUSED') {
+          console.error(
+            'Could not connect to hub. Verify the hub is running and the URL is correct.',
+          );
+        } else {
+          console.error(err.message);
+        }
         process.exit(1);
       });
     }
@@ -211,10 +252,28 @@ switch (command) {
   case 'packs':
     handlePacksCommand(args.slice(1));
     break;
+  case 'update':
+    cmdUpdate().catch((err: Error) => {
+      console.error(`Update failed: ${err.message}`);
+      process.exit(1);
+    });
+    break;
+  case 'mcp-bridge':
+    import('./cli/mcp-bridge.js').then(({ startMcpBridge }) =>
+      startMcpBridge().catch((err: Error) => {
+        process.stderr.write(`[sonde-bridge] Fatal: ${err.message}\n`);
+        process.exit(1);
+      }),
+    );
+    break;
   default:
     if (command) {
       printUsage();
-      console.error(`\nUnknown command: ${command}`);
+      if (command.startsWith('--')) {
+        console.error(`\nUnknown flag: ${command}. Did you mean "sonde start ${command}"?`);
+      } else {
+        console.error(`\nUnknown command: ${command}`);
+      }
       process.exit(1);
     } else {
       // No command: launch TUI if enrolled, otherwise show usage

package/src/runtime/connection.ts

@@ -22,6 +22,7 @@ export interface ConnectionEvents {
   onError?: (error: Error) => void;
   onRegistered?: (agentId: string) => void;
   onProbeCompleted?: (probe: string, status: string, durationMs: number) => void;
+  onUpdateAvailable?: (latestVersion: string, currentVersion: string) => void;
 }
 
 /** Minimum/maximum reconnect delays */
@@ -119,13 +120,27 @@ export function enrollWithHub(
       }
     });
 
-    ws.on('error', (err) => {
+    ws.on('error', (err: Error & { code?: string }) => {
       clearTimeout(timeout);
-      reject(err);
+      reject(new Error(humanizeWsError(err, config.hubUrl)));
     });
   });
 }
 
+/** Map low-level WebSocket/network error codes to actionable messages. */
+function humanizeWsError(err: Error & { code?: string }, hubUrl: string): string {
+  switch (err.code) {
+    case 'ECONNREFUSED':
+      return `Could not connect to hub at ${hubUrl}. Verify the hub is running.`;
+    case 'ENOTFOUND':
+      return `Hub hostname not found: ${hubUrl}. Check the URL.`;
+    case 'ETIMEDOUT':
+      return `Connection to hub at ${hubUrl} timed out. The hub may be unreachable.`;
+    default:
+      return err.message;
+  }
+}
+
 /** Build WebSocket options, including TLS client cert if available. */
 function buildWsOptions(config: AgentConfig): WebSocket.ClientOptions {
   const options: WebSocket.ClientOptions = {
@@ -139,7 +154,7 @@ function buildWsOptions(config: AgentConfig): WebSocket.ClientOptions {
       options.cert = fs.readFileSync(config.certPath, 'utf-8');
       options.key = fs.readFileSync(config.keyPath, 'utf-8');
       options.ca = [fs.readFileSync(config.caCertPath, 'utf-8')];
-      options.rejectUnauthorized = false; // Hub uses self-signed CA cert
+      options.rejectUnauthorized = true; // Verify hub cert against our CA
     } catch {
       // Cert files missing or unreadable — fall back to API key only
     }
@@ -224,16 +239,21 @@ export class AgentConnection {
       this.handleMessage(data.toString());
     });
 
-    this.ws.on('close', () => {
+    this.ws.on('close', (code) => {
       this.clearTimers();
+      if (code === 4001) {
+        this.events.onError?.(
+          new Error("Authentication rejected by hub. Run 'sonde enroll' to re-authenticate."),
+        );
+      }
       this.events.onDisconnected?.();
       if (this.running) {
         this.scheduleReconnect();
       }
     });
 
-    this.ws.on('error', (err) => {
-      this.events.onError?.(err);
+    this.ws.on('error', (err: Error & { code?: string }) => {
+      this.events.onError?.(new Error(humanizeWsError(err, this.config.hubUrl)));
     });
   }
 
@@ -261,6 +281,14 @@ export class AgentConnection {
       case 'probe.request':
         this.handleProbeRequest(envelope);
         break;
+      case 'hub.update_available': {
+        const updatePayload = envelope.payload as {
+          latestVersion: string;
+          currentVersion: string;
+        };
+        this.events.onUpdateAvailable?.(updatePayload.latestVersion, updatePayload.currentVersion);
+        break;
+      }
       default:
         break;
     }
@@ -288,6 +316,11 @@ export class AgentConnection {
 
     const response = await this.executor.execute(request);
 
+    // Echo back requestId for concurrent probe correlation
+    if (request.requestId) {
+      response.requestId = request.requestId;
+    }
+
     this.auditLog.log(request.probe, response.status, response.durationMs);
     this.events.onProbeCompleted?.(request.probe, response.status, response.durationMs);
 

package/src/runtime/executor.ts

@@ -1,6 +1,12 @@
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
-import { type ExecFn, type Pack, packRegistry } from '@sonde/packs';
+import {
+  type ExecFn,
+  type Pack,
+  type PackRegistryOptions,
+  createPackRegistry,
+  packRegistry,
+} from '@sonde/packs';
 import type { ProbeRequest, ProbeResponse } from '@sonde/shared';
 import { VERSION } from '../version.js';
 import { type ScrubPattern, buildPatterns, scrubData } from './scrubber.js';
@@ -16,6 +22,13 @@ async function defaultExec(command: string, args: string[]): Promise<string> {
   return stdout;
 }
 
+export interface ProbeExecutorOptions {
+  packs?: ReadonlyMap<string, Pack>;
+  exec?: ExecFn;
+  scrubPatterns?: ScrubPattern[];
+  allowUnsignedPacks?: boolean;
+}
+
 export class ProbeExecutor {
   private packs: ReadonlyMap<string, Pack>;
   private exec: ExecFn;