@sonde/packs 0.0.0

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

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { MemoryUsageResult } from './memory-usage.js';
+import { memoryUsage, parseFreeOutput } from './memory-usage.js';
+
+const SAMPLE_FREE_OUTPUT = `              total        used        free      shared  buff/cache   available
+Mem:    16595034112  8234127360  1021071360   348321792  7339835392 10543906816
+Swap:    8589930496  1073741824  7516188672
+`;
+
+describe('parseFreeOutput', () => {
+  it('parses free -b output into structured data', () => {
+    const result = parseFreeOutput(SAMPLE_FREE_OUTPUT);
+
+    expect(result.totalBytes).toBe(16595034112);
+    expect(result.usedBytes).toBe(8234127360);
+    expect(result.freeBytes).toBe(1021071360);
+    expect(result.availableBytes).toBe(10543906816);
+    expect(result.swap.totalBytes).toBe(8589930496);
+    expect(result.swap.usedBytes).toBe(1073741824);
+    expect(result.swap.freeBytes).toBe(7516188672);
+  });
+
+  it('handles no swap', () => {
+    const output = `              total        used        free      shared  buff/cache   available
+Mem:     4153344000  2076672000   512000000   100000000  1564672000  2576672000
+Swap:             0           0           0
+`;
+    const result = parseFreeOutput(output);
+    expect(result.totalBytes).toBe(4153344000);
+    expect(result.swap.totalBytes).toBe(0);
+    expect(result.swap.usedBytes).toBe(0);
+    expect(result.swap.freeBytes).toBe(0);
+  });
+
+  it('handles minimal output format', () => {
+    const output = `              total        used        free      shared  buff/cache   available
+Mem:     8000000000  4000000000  2000000000   500000000  1500000000  5000000000
+`;
+    const result = parseFreeOutput(output);
+    expect(result.totalBytes).toBe(8000000000);
+    expect(result.swap.totalBytes).toBe(0);
+  });
+});
+
+describe('memoryUsage handler', () => {
+  it('calls free -b and returns parsed result', async () => {
+    const mockExec: ExecFn = async (cmd, args) => {
+      expect(cmd).toBe('free');
+      expect(args).toEqual(['-b']);
+      return SAMPLE_FREE_OUTPUT;
+    };
+
+    const result = (await memoryUsage(undefined, mockExec)) as MemoryUsageResult;
+    expect(result.totalBytes).toBe(16595034112);
+    expect(result.swap.freeBytes).toBe(7516188672);
+  });
+});

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

@@ -0,0 +1,63 @@
+import type { ProbeHandler } from '../../types.js';
+
+export interface MemoryUsageResult {
+  totalBytes: number;
+  usedBytes: number;
+  freeBytes: number;
+  availableBytes: number;
+  swap: {
+    totalBytes: number;
+    usedBytes: number;
+    freeBytes: number;
+  };
+}
+
+/**
+ * Runs `free -b` and parses the output into structured JSON.
+ * `-b` = output in bytes.
+ */
+export const memoryUsage: ProbeHandler = async (_params, exec) => {
+  const stdout = await exec('free', ['-b']);
+  return parseFreeOutput(stdout);
+};
+
+export function parseFreeOutput(stdout: string): MemoryUsageResult {
+  const lines = stdout.trim().split('\n');
+
+  let totalBytes = 0;
+  let usedBytes = 0;
+  let freeBytes = 0;
+  let availableBytes = 0;
+  let swapTotal = 0;
+  let swapUsed = 0;
+  let swapFree = 0;
+
+  for (const line of lines) {
+    const parts = line.trim().split(/\s+/);
+    const label = parts[0]?.toLowerCase();
+
+    if (label === 'mem:') {
+      totalBytes = Number(parts[1]);
+      usedBytes = Number(parts[2]);
+      freeBytes = Number(parts[3]);
+      // "available" is the last column in modern `free` output
+      availableBytes = Number(parts[parts.length - 1]);
+    } else if (label === 'swap:') {
+      swapTotal = Number(parts[1]);
+      swapUsed = Number(parts[2]);
+      swapFree = Number(parts[3]);
+    }
+  }
+
+  return {
+    totalBytes,
+    usedBytes,
+    freeBytes,
+    availableBytes,
+    swap: {
+      totalBytes: swapTotal,
+      usedBytes: swapUsed,
+      freeBytes: swapFree,
+    },
+  };
+}

package/src/systemd/index.ts

@@ -0,0 +1,14 @@
+import type { Pack } from '../types.js';
+import { systemdManifest } from './manifest.js';
+import { journalQuery } from './probes/journal-query.js';
+import { serviceStatus } from './probes/service-status.js';
+import { servicesList } from './probes/services-list.js';
+
+export const systemdPack: Pack = {
+  manifest: systemdManifest,
+  handlers: {
+    'systemd.services.list': servicesList,
+    'systemd.service.status': serviceStatus,
+    'systemd.journal.query': journalQuery,
+  },
+};

package/src/systemd/manifest.ts

@@ -0,0 +1,52 @@
+import type { PackManifest } from '@sonde/shared';
+
+export const systemdManifest: PackManifest = {
+  name: 'systemd',
+  version: '0.1.0',
+  description: 'systemd service and journal probes',
+  requires: {
+    groups: [],
+    files: [],
+    commands: ['systemctl'],
+  },
+  probes: [
+    {
+      name: 'services.list',
+      description: 'List all systemd service units',
+      capability: 'observe',
+      timeout: 10_000,
+    },
+    {
+      name: 'service.status',
+      description: 'Detailed status of a specific service',
+      capability: 'observe',
+      params: {
+        service: { type: 'string', description: 'Service unit name', required: true },
+      },
+      timeout: 10_000,
+    },
+    {
+      name: 'journal.query',
+      description: 'Query journal logs for a unit',
+      capability: 'observe',
+      params: {
+        unit: { type: 'string', description: 'Systemd unit name', required: true },
+        lines: {
+          type: 'number',
+          description: 'Number of log entries',
+          required: false,
+          default: 50,
+        },
+      },
+      timeout: 15_000,
+    },
+  ],
+  runbook: {
+    category: 'systemd',
+    probes: ['services.list'],
+    parallel: true,
+  },
+  detect: {
+    files: ['/run/systemd/system'],
+  },
+};

package/src/systemd/probes/journal-query.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { JournalQueryResult } from './journal-query.js';
+import { journalQuery, parseJournalQuery } from './journal-query.js';
+
+const SAMPLE_OUTPUT = `{"__REALTIME_TIMESTAMP":"1705312200000000","PRIORITY":"6","MESSAGE":"Starting nginx...","_PID":"1234","_UID":"0","_SYSTEMD_UNIT":"nginx.service"}
+{"__REALTIME_TIMESTAMP":"1705312201000000","PRIORITY":"6","MESSAGE":"Started nginx.","_PID":"1234","_UID":"0","_SYSTEMD_UNIT":"nginx.service"}
+{"__REALTIME_TIMESTAMP":"1705312205000000","PRIORITY":"4","MESSAGE":"worker process exited on signal 15","_PID":"1235","_UID":"33","_SYSTEMD_UNIT":"nginx.service"}`;
+
+describe('parseJournalQuery', () => {
+  it('parses journalctl JSON output into structured data', () => {
+    const result = parseJournalQuery('nginx.service', SAMPLE_OUTPUT);
+
+    expect(result.unit).toBe('nginx.service');
+    expect(result.entries).toHaveLength(3);
+    expect(result.entryCount).toBe(3);
+
+    expect(result.entries[0]).toEqual({
+      timestamp: '1705312200000000',
+      priority: 6,
+      message: 'Starting nginx...',
+      pid: '1234',
+      uid: '0',
+    });
+
+    expect(result.entries[2]?.priority).toBe(4);
+    expect(result.entries[2]?.message).toBe('worker process exited on signal 15');
+  });
+
+  it('handles empty output', () => {
+    const result = parseJournalQuery('nginx.service', '');
+    expect(result.entries).toHaveLength(0);
+    expect(result.entryCount).toBe(0);
+  });
+});
+
+describe('journalQuery handler', () => {
+  it('calls journalctl with default lines and returns parsed result', async () => {
+    const mockExec: ExecFn = async (cmd, args) => {
+      expect(cmd).toBe('journalctl');
+      expect(args).toEqual(['-u', 'nginx.service', '-n', '50', '--no-pager', '-o', 'json']);
+      return SAMPLE_OUTPUT;
+    };
+
+    const result = (await journalQuery({ unit: 'nginx.service' }, mockExec)) as JournalQueryResult;
+    expect(result.unit).toBe('nginx.service');
+    expect(result.entryCount).toBe(3);
+  });
+
+  it('uses custom lines param', async () => {
+    const mockExec: ExecFn = async (cmd, args) => {
+      expect(cmd).toBe('journalctl');
+      expect(args).toEqual(['-u', 'sshd.service', '-n', '20', '--no-pager', '-o', 'json']);
+      return '{}';
+    };
+
+    // Single-line JSON object, not an array — parses as one entry
+    const result = (await journalQuery(
+      { unit: 'sshd.service', lines: 20 },
+      mockExec,
+    )) as JournalQueryResult;
+    expect(result.unit).toBe('sshd.service');
+  });
+});

package/src/systemd/probes/journal-query.ts

@@ -0,0 +1,56 @@
+import type { ProbeHandler } from '../../types.js';
+
+export interface JournalEntry {
+  timestamp: string;
+  priority: number;
+  message: string;
+  pid: string;
+  uid: string;
+}
+
+export interface JournalQueryResult {
+  unit: string;
+  entries: JournalEntry[];
+  entryCount: number;
+}
+
+/**
+ * Runs `journalctl -u <unit> -n <lines> --no-pager -o json` and parses each JSON line.
+ */
+export const journalQuery: ProbeHandler = async (params, exec) => {
+  const unit = params?.unit as string;
+  const lines = (params?.lines as number) ?? 50;
+
+  const stdout = await exec('journalctl', [
+    '-u',
+    unit,
+    '-n',
+    String(lines),
+    '--no-pager',
+    '-o',
+    'json',
+  ]);
+  return parseJournalQuery(unit, stdout);
+};
+
+export function parseJournalQuery(unit: string, stdout: string): JournalQueryResult {
+  const lines = stdout.trim().split('\n').filter(Boolean);
+  const entries: JournalEntry[] = [];
+
+  for (const line of lines) {
+    const raw = JSON.parse(line);
+    entries.push({
+      timestamp: raw.__REALTIME_TIMESTAMP ?? raw._SOURCE_REALTIME_TIMESTAMP ?? '',
+      priority: Number(raw.PRIORITY ?? 6),
+      message: raw.MESSAGE ?? '',
+      pid: raw._PID ?? '',
+      uid: raw._UID ?? '',
+    });
+  }
+
+  return {
+    unit,
+    entries,
+    entryCount: entries.length,
+  };
+}

package/src/systemd/probes/service-status.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { ServiceStatusResult } from './service-status.js';
+import { parseServiceStatus, serviceStatus } from './service-status.js';
+
+const SAMPLE_OUTPUT = `Type=notify
+Restart=on-failure
+Id=nginx.service
+LoadState=loaded
+ActiveState=active
+SubState=running
+MainPID=1234
+MemoryCurrent=52428800
+NRestarts=2
+ExecMainStartTimestamp=Mon 2024-01-15 10:30:00 UTC`;
+
+describe('parseServiceStatus', () => {
+  it('parses systemctl show output into structured data', () => {
+    const result = parseServiceStatus(SAMPLE_OUTPUT);
+
+    expect(result).toEqual({
+      name: 'nginx.service',
+      loadState: 'loaded',
+      activeState: 'active',
+      subState: 'running',
+      mainPid: 1234,
+      memoryBytes: 52428800,
+      restartCount: 2,
+    });
+  });
+
+  it('handles missing fields with defaults', () => {
+    const result = parseServiceStatus('Id=unknown.service\nLoadState=not-found');
+
+    expect(result.name).toBe('unknown.service');
+    expect(result.loadState).toBe('not-found');
+    expect(result.activeState).toBe('');
+    expect(result.mainPid).toBe(0);
+    expect(result.memoryBytes).toBe(0);
+    expect(result.restartCount).toBe(0);
+  });
+});
+
+describe('serviceStatus handler', () => {
+  it('calls systemctl show with correct args and returns parsed result', async () => {
+    const mockExec: ExecFn = async (cmd, args) => {
+      expect(cmd).toBe('systemctl');
+      expect(args).toEqual(['show', 'nginx.service', '--no-pager']);
+      return SAMPLE_OUTPUT;
+    };
+
+    const result = (await serviceStatus(
+      { service: 'nginx.service' },
+      mockExec,
+    )) as ServiceStatusResult;
+    expect(result.name).toBe('nginx.service');
+    expect(result.mainPid).toBe(1234);
+  });
+});

package/src/systemd/probes/service-status.ts

@@ -0,0 +1,42 @@
+import type { ProbeHandler } from '../../types.js';
+
+export interface ServiceStatusResult {
+  name: string;
+  loadState: string;
+  activeState: string;
+  subState: string;
+  mainPid: number;
+  memoryBytes: number;
+  restartCount: number;
+}
+
+/**
+ * Runs `systemctl show <service> --no-pager` and parses key=value output.
+ */
+export const serviceStatus: ProbeHandler = async (params, exec) => {
+  const service = params?.service as string;
+  const stdout = await exec('systemctl', ['show', service, '--no-pager']);
+  return parseServiceStatus(stdout);
+};
+
+export function parseServiceStatus(stdout: string): ServiceStatusResult {
+  const props = new Map<string, string>();
+
+  for (const line of stdout.trim().split('\n')) {
+    const idx = line.indexOf('=');
+    if (idx === -1) continue;
+    const key = line.slice(0, idx);
+    const value = line.slice(idx + 1);
+    props.set(key, value);
+  }
+
+  return {
+    name: props.get('Id') ?? '',
+    loadState: props.get('LoadState') ?? '',
+    activeState: props.get('ActiveState') ?? '',
+    subState: props.get('SubState') ?? '',
+    mainPid: Number(props.get('MainPID') ?? '0'),
+    memoryBytes: Number(props.get('MemoryCurrent') ?? '0'),
+    restartCount: Number(props.get('NRestarts') ?? '0'),
+  };
+}

package/src/systemd/probes/services-list.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest';
+import type { ExecFn } from '../../types.js';
+import type { ServicesListResult } from './services-list.js';
+import { parseServicesList, servicesList } from './services-list.js';
+
+const SAMPLE_OUTPUT = JSON.stringify([
+  {
+    unit: 'nginx.service',
+    load: 'loaded',
+    active: 'active',
+    sub: 'running',
+    description: 'A high performance web server',
+  },
+  {
+    unit: 'postgresql.service',
+    load: 'loaded',
+    active: 'inactive',
+    sub: 'dead',
+    description: 'PostgreSQL RDBMS',
+  },
+]);
+
+describe('parseServicesList', () => {
+  it('parses systemctl JSON output into structured data', () => {
+    const result = parseServicesList(SAMPLE_OUTPUT);
+
+    expect(result.services).toHaveLength(2);
+    expect(result.services[0]).toEqual({
+      unit: 'nginx.service',
+      load: 'loaded',
+      active: 'active',
+      sub: 'running',
+      description: 'A high performance web server',
+    });
+    expect(result.services[1]).toEqual({
+      unit: 'postgresql.service',
+      load: 'loaded',
+      active: 'inactive',
+      sub: 'dead',
+      description: 'PostgreSQL RDBMS',
+    });
+  });
+
+  it('handles empty array', () => {
+    const result = parseServicesList('[]');
+    expect(result.services).toHaveLength(0);
+  });
+});
+
+describe('servicesList handler', () => {
+  it('calls systemctl with correct args and returns parsed result', async () => {
+    const mockExec: ExecFn = async (cmd, args) => {
+      expect(cmd).toBe('systemctl');
+      expect(args).toEqual([
+        'list-units',
+        '--type=service',
+        '--all',
+        '--no-pager',
+        '--output=json',
+      ]);
+      return SAMPLE_OUTPUT;
+    };
+
+    const result = (await servicesList(undefined, mockExec)) as ServicesListResult;
+    expect(result.services).toHaveLength(2);
+    expect(result.services[0]?.unit).toBe('nginx.service');
+  });
+});

package/src/systemd/probes/services-list.ts

@@ -0,0 +1,45 @@
+import type { ProbeHandler } from '../../types.js';
+
+export interface ServiceInfo {
+  unit: string;
+  load: string;
+  active: string;
+  sub: string;
+  description: string;
+}
+
+export interface ServicesListResult {
+  services: ServiceInfo[];
+}
+
+/**
+ * Runs `systemctl list-units --type=service --all --no-pager --output=json`
+ * and parses the JSON output.
+ */
+export const servicesList: ProbeHandler = async (_params, exec) => {
+  const stdout = await exec('systemctl', [
+    'list-units',
+    '--type=service',
+    '--all',
+    '--no-pager',
+    '--output=json',
+  ]);
+  return parseServicesList(stdout);
+};
+
+export function parseServicesList(stdout: string): ServicesListResult {
+  const raw = JSON.parse(stdout);
+  const services: ServiceInfo[] = [];
+
+  for (const entry of raw) {
+    services.push({
+      unit: entry.unit ?? '',
+      load: entry.load ?? '',
+      active: entry.active ?? '',
+      sub: entry.sub ?? '',
+      description: entry.description ?? '',
+    });
+  }
+
+  return { services };
+}

package/src/types.ts

@@ -0,0 +1,16 @@
+import type { PackManifest } from '@sonde/shared';
+
+/** Function that executes a command and returns stdout */
+export type ExecFn = (command: string, args: string[]) => Promise<string>;
+
+/** Probe handler: takes params + exec helper, returns structured data */
+export type ProbeHandler = (
+  params: Record<string, unknown> | undefined,
+  exec: ExecFn,
+) => Promise<unknown>;
+
+/** A loaded pack with its manifest and probe handlers */
+export interface Pack {
+  manifest: PackManifest;
+  handlers: Record<string, ProbeHandler>;
+}

package/src/validation.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import type { Pack } from './types.js';
+import { PackValidationError, createPackRegistry, validatePack } from './validation.js';
+
+function makePack(overrides?: Partial<Pack>): Pack {
+  return {
+    manifest: {
+      name: 'test',
+      version: '0.1.0',
+      description: 'Test pack',
+      requires: { groups: [], files: [], commands: [] },
+      probes: [
+        { name: 'foo', description: 'Foo probe', capability: 'observe', timeout: 10_000 },
+        { name: 'bar', description: 'Bar probe', capability: 'observe', timeout: 10_000 },
+      ],
+    },
+    handlers: {
+      'test.foo': async () => ({}),
+      'test.bar': async () => ({}),
+    },
+    ...overrides,
+  };
+}
+
+describe('validatePack', () => {
+  it('passes for a valid pack', () => {
+    expect(() => validatePack(makePack())).not.toThrow();
+  });
+
+  it('throws on missing handler', () => {
+    const pack = makePack({
+      handlers: {
+        'test.foo': async () => ({}),
+        // missing test.bar
+      },
+    });
+    expect(() => validatePack(pack)).toThrow(PackValidationError);
+    expect(() => validatePack(pack)).toThrow('missing handler for probe "test.bar"');
+  });
+
+  it('throws on extra handler', () => {
+    const pack = makePack({
+      handlers: {
+        'test.foo': async () => ({}),
+        'test.bar': async () => ({}),
+        'test.baz': async () => ({}),
+      },
+    });
+    expect(() => validatePack(pack)).toThrow(PackValidationError);
+    expect(() => validatePack(pack)).toThrow('extra handler "test.baz" not in manifest');
+  });
+});
+
+describe('createPackRegistry', () => {
+  it('returns a map of validated packs', () => {
+    const pack = makePack();
+    const registry = createPackRegistry([pack]);
+
+    expect(registry.size).toBe(1);
+    expect(registry.get('test')).toBe(pack);
+  });
+
+  it('throws on duplicate pack names', () => {
+    const pack1 = makePack();
+    const pack2 = makePack();
+
+    expect(() => createPackRegistry([pack1, pack2])).toThrow(PackValidationError);
+    expect(() => createPackRegistry([pack1, pack2])).toThrow('Duplicate pack name: "test"');
+  });
+
+  it('throws if any pack is invalid', () => {
+    const validPack = makePack();
+    const invalidPack = makePack({
+      manifest: {
+        name: 'broken',
+        version: '0.1.0',
+        description: 'Broken pack',
+        requires: { groups: [], files: [], commands: [] },
+        probes: [{ name: 'x', description: 'X', capability: 'observe', timeout: 10_000 }],
+      },
+      handlers: {}, // missing handler
+    });
+
+    expect(() => createPackRegistry([validPack, invalidPack])).toThrow(PackValidationError);
+  });
+});

package/src/validation.ts

@@ -0,0 +1,52 @@
+import type { Pack } from './types.js';
+
+export class PackValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PackValidationError';
+  }
+}
+
+/**
+ * Validates that a pack's handlers match its manifest probes exactly.
+ * - Every probe in manifest must have a handler keyed as `{packName}.{probeName}`
+ * - No extra handlers may exist beyond what the manifest declares
+ */
+export function validatePack(pack: Pack): void {
+  const packName = pack.manifest.name;
+  const expectedKeys = new Set(pack.manifest.probes.map((p) => `${packName}.${p.name}`));
+  const actualKeys = new Set(Object.keys(pack.handlers));
+
+  // Check for missing handlers
+  for (const key of expectedKeys) {
+    if (!actualKeys.has(key)) {
+      throw new PackValidationError(`Pack "${packName}": missing handler for probe "${key}"`);
+    }
+  }
+
+  // Check for extra handlers
+  for (const key of actualKeys) {
+    if (!expectedKeys.has(key)) {
+      throw new PackValidationError(`Pack "${packName}": extra handler "${key}" not in manifest`);
+    }
+  }
+}
+
+/**
+ * Validates all packs and builds a frozen registry map.
+ * Throws on duplicate pack names or invalid packs.
+ */
+export function createPackRegistry(packs: Pack[]): ReadonlyMap<string, Pack> {
+  const registry = new Map<string, Pack>();
+
+  for (const pack of packs) {
+    validatePack(pack);
+
+    if (registry.has(pack.manifest.name)) {
+      throw new PackValidationError(`Duplicate pack name: "${pack.manifest.name}"`);
+    }
+    registry.set(pack.manifest.name, pack);
+  }
+
+  return registry;
+}