@sonde/packs 0.0.0

package/src/docker/probes/containers-list.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { ContainersListResult } from './containers-list.js';
+import { containersList, parseContainersList } from './containers-list.js';
+
+const SAMPLE_OUTPUT = `{"Command":"\\"docker-entrypoint.s…\\"","CreatedAt":"2024-01-15 10:30:00 +0000 UTC","ID":"abc123def456","Image":"nginx:latest","Labels":"","LocalVolumes":"0","Mounts":"","Names":"web-server","Networks":"bridge","Ports":"0.0.0.0:80-\\u003e80/tcp","RunningFor":"2 hours ago","Size":"0B","State":"running","Status":"Up 2 hours"}
+{"Command":"\\"postgres\\"","CreatedAt":"2024-01-15 09:00:00 +0000 UTC","ID":"789xyz000111","Image":"postgres:16","Labels":"","LocalVolumes":"1","Mounts":"pgdata","Names":"db","Networks":"bridge","Ports":"5432/tcp","RunningFor":"3 hours ago","Size":"0B","State":"exited","Status":"Exited (0) 1 hour ago"}`;
+
+describe('parseContainersList', () => {
+  it('parses docker ps JSON output into structured data', () => {
+    const result = parseContainersList(SAMPLE_OUTPUT);
+
+    expect(result.containers).toHaveLength(2);
+    expect(result.containers[0]).toEqual({
+      id: 'abc123def456',
+      name: 'web-server',
+      image: 'nginx:latest',
+      state: 'running',
+      status: 'Up 2 hours',
+      ports: '0.0.0.0:80->80/tcp',
+    });
+    expect(result.containers[1]).toEqual({
+      id: '789xyz000111',
+      name: 'db',
+      image: 'postgres:16',
+      state: 'exited',
+      status: 'Exited (0) 1 hour ago',
+      ports: '5432/tcp',
+    });
+  });
+
+  it('returns empty array for empty output', () => {
+    const result = parseContainersList('');
+    expect(result.containers).toHaveLength(0);
+  });
+});
+
+describe('containersList handler', () => {
+  it('calls docker ps with correct args and returns parsed result', async () => {
+    const mockExec: ExecFn = async (cmd, args) => {
+      expect(cmd).toBe('docker');
+      expect(args).toEqual(['ps', '-a', '--format', 'json']);
+      return SAMPLE_OUTPUT;
+    };
+
+    const result = (await containersList(undefined, mockExec)) as ContainersListResult;
+    expect(result.containers).toHaveLength(2);
+    expect(result.containers[0]?.name).toBe('web-server');
+  });
+});

package/src/docker/probes/containers-list.ts

@@ -0,0 +1,42 @@
+import type { ProbeHandler } from '../../types.js';
+
+export interface ContainerInfo {
+  id: string;
+  name: string;
+  image: string;
+  state: string;
+  status: string;
+  ports: string;
+}
+
+export interface ContainersListResult {
+  containers: ContainerInfo[];
+}
+
+/**
+ * Runs `docker ps -a --format json` and parses each JSON line.
+ * The --format json flag outputs one JSON object per line (Docker 20.10+).
+ */
+export const containersList: ProbeHandler = async (_params, exec) => {
+  const stdout = await exec('docker', ['ps', '-a', '--format', 'json']);
+  return parseContainersList(stdout);
+};
+
+export function parseContainersList(stdout: string): ContainersListResult {
+  const lines = stdout.trim().split('\n').filter(Boolean);
+  const containers: ContainerInfo[] = [];
+
+  for (const line of lines) {
+    const raw = JSON.parse(line);
+    containers.push({
+      id: raw.ID ?? '',
+      name: raw.Names ?? '',
+      image: raw.Image ?? '',
+      state: raw.State ?? '',
+      status: raw.Status ?? '',
+      ports: raw.Ports ?? '',
+    });
+  }
+
+  return { containers };
+}

package/src/docker/probes/daemon-info.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { DaemonInfoResult } from './daemon-info.js';
+import { daemonInfo, parseDaemonInfo } from './daemon-info.js';
+
+const SAMPLE_OUTPUT = JSON.stringify({
+  ServerVersion: '24.0.7',
+  Containers: 5,
+  ContainersRunning: 3,
+  ContainersPaused: 0,
+  ContainersStopped: 2,
+  Images: 12,
+  Driver: 'overlay2',
+  OperatingSystem: 'Ubuntu 22.04.3 LTS',
+  MemTotal: 16777216000,
+  NCPU: 8,
+  KernelVersion: '5.15.0-91-generic',
+});
+
+describe('parseDaemonInfo', () => {
+  it('parses docker info JSON output into structured data', () => {
+    const result = parseDaemonInfo(SAMPLE_OUTPUT);
+
+    expect(result).toEqual({
+      serverVersion: '24.0.7',
+      containers: 5,
+      images: 12,
+      driver: 'overlay2',
+      os: 'Ubuntu 22.04.3 LTS',
+      memoryBytes: 16777216000,
+      cpus: 8,
+    });
+  });
+});
+
+describe('daemonInfo handler', () => {
+  it('calls docker info with correct args and returns parsed result', async () => {
+    const mockExec: ExecFn = async (cmd, args) => {
+      expect(cmd).toBe('docker');
+      expect(args).toEqual(['info', '--format', 'json']);
+      return SAMPLE_OUTPUT;
+    };
+
+    const result = (await daemonInfo(undefined, mockExec)) as DaemonInfoResult;
+    expect(result.serverVersion).toBe('24.0.7');
+    expect(result.cpus).toBe(8);
+  });
+});

package/src/docker/probes/daemon-info.ts

@@ -0,0 +1,33 @@
+import type { ProbeHandler } from '../../types.js';
+
+export interface DaemonInfoResult {
+  serverVersion: string;
+  containers: number;
+  images: number;
+  driver: string;
+  os: string;
+  memoryBytes: number;
+  cpus: number;
+}
+
+/**
+ * Runs `docker info --format json` and extracts key daemon info.
+ */
+export const daemonInfo: ProbeHandler = async (_params, exec) => {
+  const stdout = await exec('docker', ['info', '--format', 'json']);
+  return parseDaemonInfo(stdout);
+};
+
+export function parseDaemonInfo(stdout: string): DaemonInfoResult {
+  const raw = JSON.parse(stdout);
+
+  return {
+    serverVersion: raw.ServerVersion ?? '',
+    containers: raw.Containers ?? 0,
+    images: raw.Images ?? 0,
+    driver: raw.Driver ?? '',
+    os: raw.OperatingSystem ?? '',
+    memoryBytes: raw.MemTotal ?? 0,
+    cpus: raw.NCPU ?? 0,
+  };
+}

package/src/docker/probes/images-list.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { ImagesListResult } from './images-list.js';
+import { imagesList, parseImagesList } from './images-list.js';
+
+const SAMPLE_OUTPUT = `{"Containers":"N/A","CreatedAt":"2024-01-10 08:00:00 +0000 UTC","CreatedSince":"5 days ago","Digest":"\u003cnone\u003e","ID":"sha256:abc123","Repository":"nginx","SharedSize":"N/A","Size":"187MB","Tag":"latest","UniqueSize":"N/A","VirtualSize":"187MB"}
+{"Containers":"N/A","CreatedAt":"2024-01-08 12:00:00 +0000 UTC","CreatedSince":"7 days ago","Digest":"\u003cnone\u003e","ID":"sha256:def456","Repository":"postgres","SharedSize":"N/A","Size":"432MB","Tag":"16","UniqueSize":"N/A","VirtualSize":"432MB"}`;
+
+describe('parseImagesList', () => {
+  it('parses docker images JSON output into structured data', () => {
+    const result = parseImagesList(SAMPLE_OUTPUT);
+
+    expect(result.images).toHaveLength(2);
+    expect(result.images[0]).toEqual({
+      id: 'sha256:abc123',
+      repository: 'nginx',
+      tag: 'latest',
+      size: '187MB',
+      created: '5 days ago',
+    });
+    expect(result.images[1]).toEqual({
+      id: 'sha256:def456',
+      repository: 'postgres',
+      tag: '16',
+      size: '432MB',
+      created: '7 days ago',
+    });
+  });
+
+  it('returns empty array for empty output', () => {
+    const result = parseImagesList('');
+    expect(result.images).toHaveLength(0);
+  });
+});
+
+describe('imagesList handler', () => {
+  it('calls docker images with correct args and returns parsed result', async () => {
+    const mockExec: ExecFn = async (cmd, args) => {
+      expect(cmd).toBe('docker');
+      expect(args).toEqual(['images', '--format', 'json']);
+      return SAMPLE_OUTPUT;
+    };
+
+    const result = (await imagesList(undefined, mockExec)) as ImagesListResult;
+    expect(result.images).toHaveLength(2);
+    expect(result.images[0]?.repository).toBe('nginx');
+  });
+});

package/src/docker/probes/images-list.ts

@@ -0,0 +1,39 @@
+import type { ProbeHandler } from '../../types.js';
+
+export interface ImageInfo {
+  id: string;
+  repository: string;
+  tag: string;
+  size: string;
+  created: string;
+}
+
+export interface ImagesListResult {
+  images: ImageInfo[];
+}
+
+/**
+ * Runs `docker images --format json` and parses each JSON line.
+ */
+export const imagesList: ProbeHandler = async (_params, exec) => {
+  const stdout = await exec('docker', ['images', '--format', 'json']);
+  return parseImagesList(stdout);
+};
+
+export function parseImagesList(stdout: string): ImagesListResult {
+  const lines = stdout.trim().split('\n').filter(Boolean);
+  const images: ImageInfo[] = [];
+
+  for (const line of lines) {
+    const raw = JSON.parse(line);
+    images.push({
+      id: raw.ID ?? '',
+      repository: raw.Repository ?? '',
+      tag: raw.Tag ?? '',
+      size: raw.Size ?? '',
+      created: raw.CreatedSince ?? raw.CreatedAt ?? '',
+    });
+  }
+
+  return { images };
+}

package/src/docker/probes/logs-tail.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { LogsTailResult } from './logs-tail.js';
+import { logsTail, parseLogsTail } from './logs-tail.js';
+
+const SAMPLE_LOGS = `2024-01-15T10:30:00Z Starting nginx...
+2024-01-15T10:30:01Z Listening on port 80
+2024-01-15T10:30:05Z GET / 200 0.5ms
+`;
+
+describe('parseLogsTail', () => {
+  it('parses log output into structured data', () => {
+    const result = parseLogsTail('web-server', SAMPLE_LOGS);
+
+    expect(result.container).toBe('web-server');
+    expect(result.lines).toHaveLength(3);
+    expect(result.lineCount).toBe(3);
+    expect(result.lines[0]).toBe('2024-01-15T10:30:00Z Starting nginx...');
+  });
+
+  it('handles empty output', () => {
+    const result = parseLogsTail('web-server', '');
+    expect(result.lines).toHaveLength(0);
+    expect(result.lineCount).toBe(0);
+  });
+});
+
+describe('logsTail handler', () => {
+  it('calls docker logs with default lines and returns parsed result', async () => {
+    const mockExec: ExecFn = async (cmd, args) => {
+      expect(cmd).toBe('docker');
+      expect(args).toEqual(['logs', '--tail', '100', 'web-server']);
+      return SAMPLE_LOGS;
+    };
+
+    const result = (await logsTail({ container: 'web-server' }, mockExec)) as LogsTailResult;
+    expect(result.container).toBe('web-server');
+    expect(result.lineCount).toBe(3);
+  });
+
+  it('uses custom lines param', async () => {
+    const mockExec: ExecFn = async (cmd, args) => {
+      expect(cmd).toBe('docker');
+      expect(args).toEqual(['logs', '--tail', '50', 'my-app']);
+      return SAMPLE_LOGS;
+    };
+
+    const result = (await logsTail({ container: 'my-app', lines: 50 }, mockExec)) as LogsTailResult;
+    expect(result.container).toBe('my-app');
+  });
+});

package/src/docker/probes/logs-tail.ts

@@ -0,0 +1,32 @@
+import type { ProbeHandler } from '../../types.js';
+
+export interface LogsTailResult {
+  container: string;
+  lines: string[];
+  lineCount: number;
+}
+
+/**
+ * Runs `docker logs --tail N <container>` and returns the log lines.
+ */
+export const logsTail: ProbeHandler = async (params, exec) => {
+  const container = params?.container as string;
+  const lines = (params?.lines as number) ?? 100;
+
+  const stdout = await exec('docker', ['logs', '--tail', String(lines), container]);
+  return parseLogsTail(container, stdout);
+};
+
+export function parseLogsTail(container: string, stdout: string): LogsTailResult {
+  const lines = stdout.split('\n');
+  // Remove trailing empty line from split
+  if (lines.length > 0 && lines[lines.length - 1] === '') {
+    lines.pop();
+  }
+
+  return {
+    container,
+    lines,
+    lineCount: lines.length,
+  };
+}

package/src/index.ts

@@ -0,0 +1,18 @@
+import { dockerPack } from './docker/index.js';
+import { systemPack } from './system/index.js';
+import { systemdPack } from './systemd/index.js';
+import type { Pack } from './types.js';
+import { createPackRegistry } from './validation.js';
+
+export type { ExecFn, Pack, ProbeHandler } from './types.js';
+export { systemPack } from './system/index.js';
+export { dockerPack } from './docker/index.js';
+export { systemdPack } from './systemd/index.js';
+export { createPackRegistry, PackValidationError, validatePack } from './validation.js';
+
+/** Registry of all built-in packs, keyed by pack name */
+export const packRegistry: ReadonlyMap<string, Pack> = createPackRegistry([
+  systemPack,
+  dockerPack,
+  systemdPack,
+]);

package/src/system/index.ts

@@ -0,0 +1,14 @@
+import type { Pack } from '../types.js';
+import { systemManifest } from './manifest.js';
+import { cpuUsage } from './probes/cpu-usage.js';
+import { diskUsage } from './probes/disk-usage.js';
+import { memoryUsage } from './probes/memory-usage.js';
+
+export const systemPack: Pack = {
+  manifest: systemManifest,
+  handlers: {
+    'system.disk.usage': diskUsage,
+    'system.memory.usage': memoryUsage,
+    'system.cpu.usage': cpuUsage,
+  },
+};

package/src/system/manifest.ts

@@ -0,0 +1,40 @@
+import type { PackManifest } from '@sonde/shared';
+
+export const systemManifest: PackManifest = {
+  name: 'system',
+  version: '0.1.0',
+  description: 'Basic system metrics: disk usage, memory usage, CPU load',
+  requires: {
+    groups: [],
+    files: [],
+    commands: ['df'],
+  },
+  probes: [
+    {
+      name: 'disk.usage',
+      description: 'Disk usage per mounted filesystem',
+      capability: 'observe',
+      timeout: 10_000,
+    },
+    {
+      name: 'memory.usage',
+      description: 'System memory and swap usage',
+      capability: 'observe',
+      timeout: 10_000,
+    },
+    {
+      name: 'cpu.usage',
+      description: 'CPU load averages and core count',
+      capability: 'observe',
+      timeout: 10_000,
+    },
+  ],
+  runbook: {
+    category: 'system',
+    probes: ['disk.usage', 'memory.usage', 'cpu.usage'],
+    parallel: true,
+  },
+  detect: {
+    files: ['/proc/loadavg'],
+  },
+};

package/src/system/probes/cpu-usage.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { CpuUsageResult } from './cpu-usage.js';
+import { cpuUsage, parseLoadAvg } from './cpu-usage.js';
+
+describe('parseLoadAvg', () => {
+  it('parses /proc/loadavg and nproc output', () => {
+    const result = parseLoadAvg('1.52 0.89 0.65 2/345 12345\n', '4\n');
+
+    expect(result.loadAvg1).toBeCloseTo(1.52);
+    expect(result.loadAvg5).toBeCloseTo(0.89);
+    expect(result.loadAvg15).toBeCloseTo(0.65);
+    expect(result.cpuCount).toBe(4);
+  });
+
+  it('handles high load values', () => {
+    const result = parseLoadAvg('24.50 18.30 12.10 5/1200 99999\n', '8\n');
+
+    expect(result.loadAvg1).toBeCloseTo(24.5);
+    expect(result.loadAvg5).toBeCloseTo(18.3);
+    expect(result.loadAvg15).toBeCloseTo(12.1);
+    expect(result.cpuCount).toBe(8);
+  });
+
+  it('handles single CPU', () => {
+    const result = parseLoadAvg('0.01 0.02 0.00 1/50 100\n', '1\n');
+
+    expect(result.loadAvg1).toBeCloseTo(0.01);
+    expect(result.cpuCount).toBe(1);
+  });
+});
+
+describe('cpuUsage handler', () => {
+  it('calls cat /proc/loadavg and nproc, returns parsed result', async () => {
+    const calls: Array<{ cmd: string; args: string[] }> = [];
+
+    const mockExec: ExecFn = async (cmd, args) => {
+      calls.push({ cmd, args });
+      if (cmd === 'cat' && args[0] === '/proc/loadavg') {
+        return '2.10 1.50 0.90 3/400 54321\n';
+      }
+      if (cmd === 'nproc') {
+        return '16\n';
+      }
+      throw new Error(`Unexpected command: ${cmd}`);
+    };
+
+    const result = (await cpuUsage(undefined, mockExec)) as CpuUsageResult;
+    expect(result.loadAvg1).toBeCloseTo(2.1);
+    expect(result.loadAvg5).toBeCloseTo(1.5);
+    expect(result.loadAvg15).toBeCloseTo(0.9);
+    expect(result.cpuCount).toBe(16);
+    expect(calls).toHaveLength(2);
+  });
+});

package/src/system/probes/cpu-usage.ts

@@ -0,0 +1,30 @@
+import type { ProbeHandler } from '../../types.js';
+
+export interface CpuUsageResult {
+  loadAvg1: number;
+  loadAvg5: number;
+  loadAvg15: number;
+  cpuCount: number;
+}
+
+/**
+ * Reads /proc/loadavg for load averages and `nproc` for CPU count.
+ * Returns load averages and core count so consumers can compute utilization.
+ */
+export const cpuUsage: ProbeHandler = async (_params, exec) => {
+  const [loadAvgRaw, nprocRaw] = await Promise.all([
+    exec('cat', ['/proc/loadavg']),
+    exec('nproc', []),
+  ]);
+  return parseLoadAvg(loadAvgRaw, nprocRaw);
+};
+
+export function parseLoadAvg(loadAvgRaw: string, nprocRaw: string): CpuUsageResult {
+  const parts = loadAvgRaw.trim().split(/\s+/);
+  const loadAvg1 = Number(parts[0]);
+  const loadAvg5 = Number(parts[1]);
+  const loadAvg15 = Number(parts[2]);
+  const cpuCount = Number.parseInt(nprocRaw.trim(), 10);
+
+  return { loadAvg1, loadAvg5, loadAvg15, cpuCount };
+}

package/src/system/probes/disk-usage.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { DiskUsageResult } from './disk-usage.js';
+import { diskUsage, parseDfOutput } from './disk-usage.js';
+
+const SAMPLE_DF_OUTPUT = `Filesystem     1024-blocks      Used Available Capacity Mounted on
+/dev/sda1         51474044  31285940  17548392      65% /
+/dev/sdb1        103081248  45234112  52579600      47% /data
+tmpfs              8152560         0   8152560       0% /dev/shm
+`;
+
+describe('parseDfOutput', () => {
+  it('parses df -kP output into structured data', () => {
+    const result = parseDfOutput(SAMPLE_DF_OUTPUT);
+
+    expect(result.filesystems).toHaveLength(2);
+
+    expect(result.filesystems[0]).toEqual({
+      filesystem: '/dev/sda1',
+      sizeKb: 51474044,
+      usedKb: 31285940,
+      availableKb: 17548392,
+      usePct: 65,
+      mountedOn: '/',
+    });
+
+    expect(result.filesystems[1]).toEqual({
+      filesystem: '/dev/sdb1',
+      sizeKb: 103081248,
+      usedKb: 45234112,
+      availableKb: 52579600,
+      usePct: 47,
+      mountedOn: '/data',
+    });
+  });
+
+  it('filters out tmpfs and devtmpfs', () => {
+    const result = parseDfOutput(SAMPLE_DF_OUTPUT);
+    const names = result.filesystems.map((f) => f.filesystem);
+    expect(names).not.toContain('tmpfs');
+    expect(names).not.toContain('devtmpfs');
+  });
+
+  it('handles single filesystem output', () => {
+    const output = `Filesystem     1024-blocks  Used Available Capacity Mounted on
+/dev/vda1         25671908 5432100  19912300      22% /
+`;
+    const result = parseDfOutput(output);
+    expect(result.filesystems).toHaveLength(1);
+    expect(result.filesystems[0]?.usePct).toBe(22);
+  });
+
+  it('returns empty array for header-only output', () => {
+    const output = `Filesystem     1024-blocks  Used Available Capacity Mounted on
+`;
+    const result = parseDfOutput(output);
+    expect(result.filesystems).toHaveLength(0);
+  });
+});
+
+describe('diskUsage handler', () => {
+  it('calls df -kP and returns parsed result', async () => {
+    const mockExec: ExecFn = async (cmd, args) => {
+      expect(cmd).toBe('df');
+      expect(args).toEqual(['-kP']);
+      return SAMPLE_DF_OUTPUT;
+    };
+
+    const result = (await diskUsage(undefined, mockExec)) as DiskUsageResult;
+    expect(result.filesystems).toHaveLength(2);
+    expect(result.filesystems[0]?.mountedOn).toBe('/');
+  });
+});

package/src/system/probes/disk-usage.ts

@@ -0,0 +1,53 @@
+import type { ProbeHandler } from '../../types.js';
+
+export interface FilesystemUsage {
+  filesystem: string;
+  sizeKb: number;
+  usedKb: number;
+  availableKb: number;
+  usePct: number;
+  mountedOn: string;
+}
+
+export interface DiskUsageResult {
+  filesystems: FilesystemUsage[];
+}
+
+/**
+ * Runs `df -kP` and parses the output into structured JSON.
+ * `-k` = 1K blocks, `-P` = POSIX portable output format (one line per fs).
+ */
+export const diskUsage: ProbeHandler = async (_params, exec) => {
+  const stdout = await exec('df', ['-kP']);
+  return parseDfOutput(stdout);
+};
+
+export function parseDfOutput(stdout: string): DiskUsageResult {
+  const lines = stdout.trim().split('\n');
+  // Skip header line
+  const dataLines = lines.slice(1);
+
+  const filesystems: FilesystemUsage[] = [];
+
+  for (const line of dataLines) {
+    const parts = line.trim().split(/\s+/);
+    if (parts.length < 6) continue;
+
+    const [filesystem, sizeStr, usedStr, availStr, pctStr, mountedOn] = parts;
+    if (!filesystem || !sizeStr || !usedStr || !availStr || !pctStr || !mountedOn) continue;
+
+    // Skip pseudo-filesystems
+    if (filesystem === 'tmpfs' || filesystem === 'devtmpfs' || filesystem === 'none') continue;
+
+    const sizeKb = Number(sizeStr);
+    const usedKb = Number(usedStr);
+    const availableKb = Number(availStr);
+    const usePct = Number.parseInt(pctStr.replace('%', ''), 10);
+
+    if (Number.isNaN(sizeKb) || Number.isNaN(usedKb)) continue;
+
+    filesystems.push({ filesystem, sizeKb, usedKb, availableKb, usePct, mountedOn });
+  }
+
+  return { filesystems };
+}