@checkstack/collector-hardware-backend 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @checkstack/collector-hardware-backend
+
+## 0.1.0
+
+### Minor Changes
+
+- f5b1f49: Added CPU, Disk, and Memory hardware collectors for SSH-based system monitoring.
+
+  - `CpuCollector`: Monitors CPU usage, load averages (1m, 5m, 15m), and core count
+  - `DiskCollector`: Monitors disk usage for configurable mount points
+  - `MemoryCollector`: Monitors RAM usage and optional swap metrics
+  - All collectors work via SSH transport for remote system monitoring
+
+### Patch Changes
+
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+- Updated dependencies [f5b1f49]
+  - @checkstack/backend-api@0.1.0
+  - @checkstack/healthcheck-common@0.1.0
+  - @checkstack/healthcheck-ssh-common@0.1.0
+  - @checkstack/common@0.0.3

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@checkstack/collector-hardware-backend",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/healthcheck-common": "workspace:*",
+    "@checkstack/healthcheck-ssh-common": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.0.0",
+    "typescript": "^5.0.0",
+    "@checkstack/tsconfig": "workspace:*",
+    "@checkstack/scripts": "workspace:*"
+  }
+}

package/src/collectors/cpu.test.ts

@@ -0,0 +1,138 @@
+import { describe, expect, it, mock } from "bun:test";
+import { CpuCollector, type CpuConfig } from "./cpu";
+import type { SshTransportClient } from "@checkstack/healthcheck-ssh-common";
+
+describe("CpuCollector", () => {
+  const createMockClient = (
+    responses: {
+      stat1?: { stdout: string };
+      stat2?: { stdout: string };
+      loadavg?: { stdout: string };
+      nproc?: { stdout: string };
+    } = {}
+  ): SshTransportClient => {
+    let callCount = 0;
+    return {
+      exec: mock((cmd: string) => {
+        if (cmd.includes("/proc/stat")) {
+          callCount++;
+          if (callCount === 1) {
+            return Promise.resolve({
+              exitCode: 0,
+              stdout:
+                responses.stat1?.stdout ?? "cpu 100 0 50 800 50 0 0 0 0 0",
+              stderr: "",
+            });
+          }
+          return Promise.resolve({
+            exitCode: 0,
+            stdout: responses.stat2?.stdout ?? "cpu 150 0 100 850 50 0 0 0 0 0",
+            stderr: "",
+          });
+        }
+        if (cmd.includes("/proc/loadavg")) {
+          return Promise.resolve({
+            exitCode: 0,
+            stdout: responses.loadavg?.stdout ?? "0.50 0.75 1.00 1/100 12345",
+            stderr: "",
+          });
+        }
+        if (cmd.includes("nproc")) {
+          return Promise.resolve({
+            exitCode: 0,
+            stdout: responses.nproc?.stdout ?? "4\n",
+            stderr: "",
+          });
+        }
+        return Promise.resolve({ exitCode: 0, stdout: "", stderr: "" });
+      }),
+    };
+  };
+
+  describe("execute", () => {
+    it("should collect CPU usage", async () => {
+      const collector = new CpuCollector();
+      const client = createMockClient();
+
+      const result = await collector.execute({
+        config: { includeLoadAverage: false, includeCoreCount: false },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.usagePercent).toBeDefined();
+      expect(result.result.usagePercent).toBeGreaterThanOrEqual(0);
+      expect(result.result.usagePercent).toBeLessThanOrEqual(100);
+    });
+
+    it("should include load averages when configured", async () => {
+      const collector = new CpuCollector();
+      const client = createMockClient({
+        loadavg: { stdout: "1.50 2.00 3.00 1/200 12345" },
+      });
+
+      const result = await collector.execute({
+        config: { includeLoadAverage: true, includeCoreCount: false },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.loadAvg1m).toBe(1.5);
+      expect(result.result.loadAvg5m).toBe(2);
+      expect(result.result.loadAvg15m).toBe(3);
+    });
+
+    it("should include core count when configured", async () => {
+      const collector = new CpuCollector();
+      const client = createMockClient({ nproc: { stdout: "8\n" } });
+
+      const result = await collector.execute({
+        config: { includeLoadAverage: false, includeCoreCount: true },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.coreCount).toBe(8);
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate average and max CPU usage", () => {
+      const collector = new CpuCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { usagePercent: 25, loadAvg1m: 1.0 },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: { usagePercent: 75, loadAvg1m: 2.0 },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.avgUsagePercent).toBe(50);
+      expect(aggregated.maxUsagePercent).toBe(75);
+      expect(aggregated.avgLoadAvg1m).toBe(1.5);
+    });
+  });
+
+  describe("metadata", () => {
+    it("should have correct static properties", () => {
+      const collector = new CpuCollector();
+
+      expect(collector.id).toBe("cpu");
+      expect(collector.displayName).toBe("CPU Metrics");
+      expect(collector.supportedPlugins).toHaveLength(1);
+    });
+  });
+});

package/src/collectors/cpu.ts

@@ -0,0 +1,199 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import { healthResultNumber } from "@checkstack/healthcheck-common";
+import {
+  pluginMetadata as sshPluginMetadata,
+  type SshTransportClient,
+} from "@checkstack/healthcheck-ssh-common";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const cpuConfigSchema = z.object({
+  includeLoadAverage: z
+    .boolean()
+    .default(true)
+    .describe("Include 1m, 5m, 15m load averages"),
+  includeCoreCount: z
+    .boolean()
+    .default(true)
+    .describe("Include number of CPU cores"),
+});
+
+export type CpuConfig = z.infer<typeof cpuConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const cpuResultSchema = z.object({
+  usagePercent: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "CPU Usage",
+    "x-chart-unit": "%",
+  }),
+  loadAvg1m: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Load (1m)",
+  }).optional(),
+  loadAvg5m: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Load (5m)",
+  }).optional(),
+  loadAvg15m: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Load (15m)",
+  }).optional(),
+  coreCount: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "CPU Cores",
+  }).optional(),
+});
+
+export type CpuResult = z.infer<typeof cpuResultSchema>;
+
+const cpuAggregatedSchema = z.object({
+  avgUsagePercent: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg CPU Usage",
+    "x-chart-unit": "%",
+  }),
+  maxUsagePercent: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Max CPU Usage",
+    "x-chart-unit": "%",
+  }),
+  avgLoadAvg1m: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Load (1m)",
+  }),
+});
+
+export type CpuAggregatedResult = z.infer<typeof cpuAggregatedSchema>;
+
+// ============================================================================
+// CPU COLLECTOR
+// ============================================================================
+
+export class CpuCollector
+  implements
+    CollectorStrategy<
+      SshTransportClient,
+      CpuConfig,
+      CpuResult,
+      CpuAggregatedResult
+    >
+{
+  id = "cpu";
+  displayName = "CPU Metrics";
+  description = "Collects CPU usage, load averages, and core count via SSH";
+
+  supportedPlugins = [sshPluginMetadata];
+
+  config = new Versioned({ version: 1, schema: cpuConfigSchema });
+  result = new Versioned({ version: 1, schema: cpuResultSchema });
+  aggregatedResult = new Versioned({ version: 1, schema: cpuAggregatedSchema });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: CpuConfig;
+    client: SshTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<CpuResult>> {
+    // Get CPU usage from /proc/stat (two samples to calculate delta)
+    const stat1 = await client.exec("cat /proc/stat | head -1");
+    await new Promise((resolve) => setTimeout(resolve, 100)); // 100ms sample
+    const stat2 = await client.exec("cat /proc/stat | head -1");
+
+    const usagePercent = this.calculateCpuUsage(stat1.stdout, stat2.stdout);
+
+    const result: CpuResult = { usagePercent };
+
+    // Get load averages
+    if (config.includeLoadAverage) {
+      const uptime = await client.exec("cat /proc/loadavg");
+      const loads = this.parseLoadAvg(uptime.stdout);
+      result.loadAvg1m = loads.load1m;
+      result.loadAvg5m = loads.load5m;
+      result.loadAvg15m = loads.load15m;
+    }
+
+    // Get core count
+    if (config.includeCoreCount) {
+      const nproc = await client.exec("nproc");
+      result.coreCount = Number.parseInt(nproc.stdout.trim(), 10) || undefined;
+    }
+
+    return { result };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<CpuResult>[]
+  ): CpuAggregatedResult {
+    const usages = runs
+      .map((r) => r.metadata?.usagePercent)
+      .filter((v): v is number => typeof v === "number");
+
+    const loads = runs
+      .map((r) => r.metadata?.loadAvg1m)
+      .filter((v): v is number => typeof v === "number");
+
+    return {
+      avgUsagePercent: usages.length > 0 ? this.avg(usages) : 0,
+      maxUsagePercent: usages.length > 0 ? Math.max(...usages) : 0,
+      avgLoadAvg1m: loads.length > 0 ? this.avg(loads) : 0,
+    };
+  }
+
+  // ============================================================================
+  // PARSING HELPERS
+  // ============================================================================
+
+  private parseCpuStat(line: string): { idle: number; total: number } {
+    // Format: cpu user nice system idle iowait irq softirq steal guest guest_nice
+    const parts = line.trim().split(/\s+/).slice(1).map(Number);
+    const idle = parts[3] + parts[4]; // idle + iowait
+    const total = parts.reduce((a, b) => a + b, 0);
+    return { idle, total };
+  }
+
+  private calculateCpuUsage(stat1: string, stat2: string): number {
+    const s1 = this.parseCpuStat(stat1);
+    const s2 = this.parseCpuStat(stat2);
+
+    const idleDelta = s2.idle - s1.idle;
+    const totalDelta = s2.total - s1.total;
+
+    if (totalDelta === 0) return 0;
+
+    return Math.round(((totalDelta - idleDelta) / totalDelta) * 100 * 10) / 10;
+  }
+
+  private parseLoadAvg(output: string): {
+    load1m?: number;
+    load5m?: number;
+    load15m?: number;
+  } {
+    // Format: 0.00 0.01 0.05 1/234 5678
+    const parts = output.trim().split(/\s+/);
+    return {
+      load1m: Number.parseFloat(parts[0]) || undefined,
+      load5m: Number.parseFloat(parts[1]) || undefined,
+      load15m: Number.parseFloat(parts[2]) || undefined,
+    };
+  }
+
+  private avg(nums: number[]): number {
+    return (
+      Math.round((nums.reduce((a, b) => a + b, 0) / nums.length) * 10) / 10
+    );
+  }
+}

package/src/collectors/disk.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it, mock } from "bun:test";
+import { DiskCollector, type DiskConfig } from "./disk";
+import type { SshTransportClient } from "@checkstack/healthcheck-ssh-common";
+
+describe("DiskCollector", () => {
+  const createMockClient = (
+    dfOutput: string = "/dev/sda1 100G 45G 55G 45% /"
+  ): SshTransportClient => ({
+    exec: mock(() =>
+      Promise.resolve({
+        exitCode: 0,
+        stdout: dfOutput,
+        stderr: "",
+      })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should collect disk usage for mount point", async () => {
+      const collector = new DiskCollector();
+      const client = createMockClient("/dev/sda1     100G   45G   55G  45% /");
+
+      const result = await collector.execute({
+        config: { mountPoint: "/" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.filesystem).toBe("/dev/sda1");
+      expect(result.result.totalGb).toBe(100);
+      expect(result.result.usedGb).toBe(45);
+      expect(result.result.availableGb).toBe(55);
+      expect(result.result.usedPercent).toBe(45);
+      expect(result.result.mountPoint).toBe("/");
+    });
+
+    it("should handle different mount points", async () => {
+      const collector = new DiskCollector();
+      const client = createMockClient(
+        "/dev/sdb1     500G   200G   300G  40% /data"
+      );
+
+      const result = await collector.execute({
+        config: { mountPoint: "/data" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.filesystem).toBe("/dev/sdb1");
+      expect(result.result.totalGb).toBe(500);
+      expect(result.result.usedPercent).toBe(40);
+      expect(result.result.mountPoint).toBe("/data");
+    });
+
+    it("should pass mount point to df command", async () => {
+      const collector = new DiskCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { mountPoint: "/var" },
+        client,
+        pluginId: "test",
+      });
+
+      expect(client.exec).toHaveBeenCalledWith("df -BG /var | tail -1");
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate average and max disk usage", () => {
+      const collector = new DiskCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            filesystem: "/dev/sda1",
+            totalGb: 100,
+            usedGb: 30,
+            availableGb: 70,
+            usedPercent: 30,
+            mountPoint: "/",
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            filesystem: "/dev/sda1",
+            totalGb: 100,
+            usedGb: 50,
+            availableGb: 50,
+            usedPercent: 50,
+            mountPoint: "/",
+          },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.avgUsedPercent).toBe(40);
+      expect(aggregated.maxUsedPercent).toBe(50);
+    });
+  });
+
+  describe("metadata", () => {
+    it("should have correct static properties", () => {
+      const collector = new DiskCollector();
+
+      expect(collector.id).toBe("disk");
+      expect(collector.displayName).toBe("Disk Metrics");
+      expect(collector.supportedPlugins).toHaveLength(1);
+    });
+  });
+});

package/src/collectors/disk.ts

@@ -0,0 +1,171 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import {
+  healthResultNumber,
+  healthResultString,
+} from "@checkstack/healthcheck-common";
+import {
+  pluginMetadata as sshPluginMetadata,
+  type SshTransportClient,
+} from "@checkstack/healthcheck-ssh-common";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const diskConfigSchema = z.object({
+  mountPoint: z
+    .string()
+    .default("/")
+    .describe("Mount point to monitor (e.g., /, /home, /var)"),
+});
+
+export type DiskConfig = z.infer<typeof diskConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const diskResultSchema = z.object({
+  filesystem: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Filesystem",
+  }),
+  totalGb: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Total Disk",
+    "x-chart-unit": "GB",
+  }),
+  usedGb: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Used Disk",
+    "x-chart-unit": "GB",
+  }),
+  availableGb: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Available Disk",
+    "x-chart-unit": "GB",
+  }),
+  usedPercent: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Disk Usage",
+    "x-chart-unit": "%",
+  }),
+  mountPoint: healthResultString({
+    "x-chart-type": "text",
+    "x-chart-label": "Mount Point",
+  }),
+});
+
+export type DiskResult = z.infer<typeof diskResultSchema>;
+
+const diskAggregatedSchema = z.object({
+  avgUsedPercent: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Disk Usage",
+    "x-chart-unit": "%",
+  }),
+  maxUsedPercent: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Max Disk Usage",
+    "x-chart-unit": "%",
+  }),
+});
+
+export type DiskAggregatedResult = z.infer<typeof diskAggregatedSchema>;
+
+// ============================================================================
+// DISK COLLECTOR
+// ============================================================================
+
+export class DiskCollector
+  implements
+    CollectorStrategy<
+      SshTransportClient,
+      DiskConfig,
+      DiskResult,
+      DiskAggregatedResult
+    >
+{
+  id = "disk";
+  displayName = "Disk Metrics";
+  description = "Collects disk usage for a specific mount point via SSH";
+
+  supportedPlugins = [sshPluginMetadata];
+
+  config = new Versioned({ version: 1, schema: diskConfigSchema });
+  result = new Versioned({ version: 1, schema: diskResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: diskAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: DiskConfig;
+    client: SshTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<DiskResult>> {
+    // Use df with specific mount point, output in 1G blocks
+    const dfResult = await client.exec(`df -BG ${config.mountPoint} | tail -1`);
+    const parsed = this.parseDfOutput(dfResult.stdout, config.mountPoint);
+
+    return { result: parsed };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<DiskResult>[]
+  ): DiskAggregatedResult {
+    const usedPercents = runs
+      .map((r) => r.metadata?.usedPercent)
+      .filter((v): v is number => typeof v === "number");
+
+    return {
+      avgUsedPercent: usedPercents.length > 0 ? this.avg(usedPercents) : 0,
+      maxUsedPercent: usedPercents.length > 0 ? Math.max(...usedPercents) : 0,
+    };
+  }
+
+  // ============================================================================
+  // PARSING HELPERS
+  // ============================================================================
+
+  private parseGb(val: string): number {
+    // Remove 'G' suffix and parse
+    return Number.parseInt(val.replace(/G$/i, ""), 10) || 0;
+  }
+
+  private parseDfOutput(output: string, mountPoint: string): DiskResult {
+    // Format: Filesystem     1G-blocks  Used Available Use% Mounted on
+    //         /dev/sda1          100G   45G       55G  45% /
+    const parts = output.trim().split(/\s+/);
+
+    const filesystem = parts[0] || "unknown";
+    const totalGb = this.parseGb(parts[1]);
+    const usedGb = this.parseGb(parts[2]);
+    const availableGb = this.parseGb(parts[3]);
+    const usedPercent = Number.parseInt(parts[4]?.replace(/%$/, ""), 10) || 0;
+
+    return {
+      filesystem,
+      totalGb,
+      usedGb,
+      availableGb,
+      usedPercent,
+      mountPoint,
+    };
+  }
+
+  private avg(nums: number[]): number {
+    return (
+      Math.round((nums.reduce((a, b) => a + b, 0) / nums.length) * 10) / 10
+    );
+  }
+}

package/src/collectors/index.ts

@@ -0,0 +1,12 @@
+export { CpuCollector } from "./cpu";
+export type { CpuConfig, CpuResult, CpuAggregatedResult } from "./cpu";
+
+export { MemoryCollector } from "./memory";
+export type {
+  MemoryConfig,
+  MemoryResult,
+  MemoryAggregatedResult,
+} from "./memory";
+
+export { DiskCollector } from "./disk";
+export type { DiskConfig, DiskResult, DiskAggregatedResult } from "./disk";

package/src/collectors/memory.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it, mock } from "bun:test";
+import { MemoryCollector, type MemoryConfig } from "./memory";
+import type { SshTransportClient } from "@checkstack/healthcheck-ssh-common";
+
+describe("MemoryCollector", () => {
+  const createMockClient = (
+    freeOutput: string = `              total        used        free      shared  buff/cache   available
+Mem:          16000        4000        8000         500        4000       12000
+Swap:          4096         512        3584`
+  ): SshTransportClient => ({
+    exec: mock(() =>
+      Promise.resolve({
+        exitCode: 0,
+        stdout: freeOutput,
+        stderr: "",
+      })
+    ),
+  });
+
+  describe("execute", () => {
+    it("should collect memory usage", async () => {
+      const collector = new MemoryCollector();
+      const client = createMockClient();
+
+      const result = await collector.execute({
+        config: { includeSwap: false, includeBuffersCache: false },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.totalMb).toBe(16000);
+      expect(result.result.usedMb).toBe(4000);
+      expect(result.result.freeMb).toBe(8000);
+      expect(result.result.usedPercent).toBe(25);
+    });
+
+    it("should include swap when configured", async () => {
+      const collector = new MemoryCollector();
+      const client = createMockClient();
+
+      const result = await collector.execute({
+        config: { includeSwap: true, includeBuffersCache: false },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.swapTotalMb).toBe(4096);
+      expect(result.result.swapUsedMb).toBe(512);
+    });
+
+    it("should not include swap when not configured", async () => {
+      const collector = new MemoryCollector();
+      const client = createMockClient();
+
+      const result = await collector.execute({
+        config: { includeSwap: false, includeBuffersCache: false },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.result.swapTotalMb).toBeUndefined();
+      expect(result.result.swapUsedMb).toBeUndefined();
+    });
+
+    it("should call free -m command", async () => {
+      const collector = new MemoryCollector();
+      const client = createMockClient();
+
+      await collector.execute({
+        config: { includeSwap: false, includeBuffersCache: false },
+        client,
+        pluginId: "test",
+      });
+
+      expect(client.exec).toHaveBeenCalledWith("free -m");
+    });
+  });
+
+  describe("aggregateResult", () => {
+    it("should calculate average and max memory usage", () => {
+      const collector = new MemoryCollector();
+      const runs = [
+        {
+          id: "1",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            totalMb: 16000,
+            usedMb: 4000,
+            freeMb: 12000,
+            usedPercent: 25,
+          },
+        },
+        {
+          id: "2",
+          status: "healthy" as const,
+          latencyMs: 100,
+          checkId: "c1",
+          timestamp: new Date(),
+          metadata: {
+            totalMb: 16000,
+            usedMb: 12000,
+            freeMb: 4000,
+            usedPercent: 75,
+          },
+        },
+      ];
+
+      const aggregated = collector.aggregateResult(runs);
+
+      expect(aggregated.avgUsedPercent).toBe(50);
+      expect(aggregated.maxUsedPercent).toBe(75);
+      expect(aggregated.avgUsedMb).toBe(8000);
+    });
+  });
+
+  describe("metadata", () => {
+    it("should have correct static properties", () => {
+      const collector = new MemoryCollector();
+
+      expect(collector.id).toBe("memory");
+      expect(collector.displayName).toBe("Memory Metrics");
+      expect(collector.supportedPlugins).toHaveLength(1);
+    });
+  });
+});

package/src/collectors/memory.ts

@@ -0,0 +1,206 @@
+import {
+  Versioned,
+  z,
+  type HealthCheckRunForAggregation,
+  type CollectorResult,
+  type CollectorStrategy,
+} from "@checkstack/backend-api";
+import { healthResultNumber } from "@checkstack/healthcheck-common";
+import {
+  pluginMetadata as sshPluginMetadata,
+  type SshTransportClient,
+} from "@checkstack/healthcheck-ssh-common";
+
+// ============================================================================
+// CONFIGURATION SCHEMA
+// ============================================================================
+
+const memoryConfigSchema = z.object({
+  includeSwap: z
+    .boolean()
+    .default(true)
+    .describe("Include swap usage in results"),
+  includeBuffersCache: z
+    .boolean()
+    .default(false)
+    .describe("Include buffers/cache breakdown"),
+});
+
+export type MemoryConfig = z.infer<typeof memoryConfigSchema>;
+
+// ============================================================================
+// RESULT SCHEMAS
+// ============================================================================
+
+const memoryResultSchema = z.object({
+  totalMb: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Total Memory",
+    "x-chart-unit": "MB",
+  }),
+  usedMb: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Used Memory",
+    "x-chart-unit": "MB",
+  }),
+  freeMb: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Free Memory",
+    "x-chart-unit": "MB",
+  }),
+  usedPercent: healthResultNumber({
+    "x-chart-type": "gauge",
+    "x-chart-label": "Memory Usage",
+    "x-chart-unit": "%",
+  }),
+  swapUsedMb: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Swap Used",
+    "x-chart-unit": "MB",
+  }).optional(),
+  swapTotalMb: healthResultNumber({
+    "x-chart-type": "counter",
+    "x-chart-label": "Swap Total",
+    "x-chart-unit": "MB",
+  }).optional(),
+});
+
+export type MemoryResult = z.infer<typeof memoryResultSchema>;
+
+const memoryAggregatedSchema = z.object({
+  avgUsedPercent: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Memory Usage",
+    "x-chart-unit": "%",
+  }),
+  maxUsedPercent: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Max Memory Usage",
+    "x-chart-unit": "%",
+  }),
+  avgUsedMb: healthResultNumber({
+    "x-chart-type": "line",
+    "x-chart-label": "Avg Memory Used",
+    "x-chart-unit": "MB",
+  }),
+});
+
+export type MemoryAggregatedResult = z.infer<typeof memoryAggregatedSchema>;
+
+// ============================================================================
+// MEMORY COLLECTOR
+// ============================================================================
+
+export class MemoryCollector
+  implements
+    CollectorStrategy<
+      SshTransportClient,
+      MemoryConfig,
+      MemoryResult,
+      MemoryAggregatedResult
+    >
+{
+  id = "memory";
+  displayName = "Memory Metrics";
+  description = "Collects RAM and swap usage via SSH";
+
+  supportedPlugins = [sshPluginMetadata];
+
+  config = new Versioned({ version: 1, schema: memoryConfigSchema });
+  result = new Versioned({ version: 1, schema: memoryResultSchema });
+  aggregatedResult = new Versioned({
+    version: 1,
+    schema: memoryAggregatedSchema,
+  });
+
+  async execute({
+    config,
+    client,
+  }: {
+    config: MemoryConfig;
+    client: SshTransportClient;
+    pluginId: string;
+  }): Promise<CollectorResult<MemoryResult>> {
+    // Use free -m for memory in megabytes
+    const freeResult = await client.exec("free -m");
+    const parsed = this.parseFreeOutput(freeResult.stdout);
+
+    const result: MemoryResult = {
+      totalMb: parsed.totalMb,
+      usedMb: parsed.usedMb,
+      freeMb: parsed.freeMb,
+      usedPercent: parsed.usedPercent,
+    };
+
+    if (config.includeSwap && parsed.swapTotalMb > 0) {
+      result.swapTotalMb = parsed.swapTotalMb;
+      result.swapUsedMb = parsed.swapUsedMb;
+    }
+
+    return { result };
+  }
+
+  aggregateResult(
+    runs: HealthCheckRunForAggregation<MemoryResult>[]
+  ): MemoryAggregatedResult {
+    const usedPercents = runs
+      .map((r) => r.metadata?.usedPercent)
+      .filter((v): v is number => typeof v === "number");
+
+    const usedMbs = runs
+      .map((r) => r.metadata?.usedMb)
+      .filter((v): v is number => typeof v === "number");
+
+    return {
+      avgUsedPercent: usedPercents.length > 0 ? this.avg(usedPercents) : 0,
+      maxUsedPercent: usedPercents.length > 0 ? Math.max(...usedPercents) : 0,
+      avgUsedMb: usedMbs.length > 0 ? this.avg(usedMbs) : 0,
+    };
+  }
+
+  // ============================================================================
+  // PARSING HELPERS
+  // ============================================================================
+
+  private parseFreeOutput(output: string): {
+    totalMb: number;
+    usedMb: number;
+    freeMb: number;
+    usedPercent: number;
+    swapTotalMb: number;
+    swapUsedMb: number;
+  } {
+    // Format:
+    //               total        used        free      shared  buff/cache   available
+    // Mem:          15896        5234        1234         123        9428       10234
+    // Swap:          4096         512        3584
+
+    const lines = output.trim().split("\n");
+    const memLine = lines.find((l) => l.startsWith("Mem:"));
+    const swapLine = lines.find((l) => l.startsWith("Swap:"));
+
+    const memParts = memLine?.split(/\s+/).map(Number) ?? [];
+    const swapParts = swapLine?.split(/\s+/).map(Number) ?? [];
+
+    const totalMb = memParts[1] || 0;
+    const usedMb = memParts[2] || 0;
+    const freeMb = memParts[3] || 0;
+    const usedPercent =
+      totalMb > 0 ? Math.round((usedMb / totalMb) * 100 * 10) / 10 : 0;
+
+    return {
+      totalMb,
+      usedMb,
+      freeMb,
+      usedPercent,
+      swapTotalMb: swapParts[1] || 0,
+      swapUsedMb: swapParts[2] || 0,
+    };
+  }
+
+  private avg(nums: number[]): number {
+    return (
+      Math.round((nums.reduce((a, b) => a + b, 0) / nums.length) * 10) / 10
+    );
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
+import { CpuCollector, MemoryCollector, DiskCollector } from "./collectors";
+import { pluginMetadata } from "./plugin-metadata";
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+  register(env) {
+    env.registerInit({
+      deps: {
+        collectorRegistry: coreServices.collectorRegistry,
+        logger: coreServices.logger,
+      },
+      init: async ({ collectorRegistry, logger }) => {
+        logger.debug("🔌 Registering hardware collectors...");
+
+        // Register all hardware collectors
+        // Owner plugin metadata is auto-injected via scoped factory
+        collectorRegistry.register(new CpuCollector());
+        collectorRegistry.register(new MemoryCollector());
+        collectorRegistry.register(new DiskCollector());
+
+        logger.info("✅ Hardware collectors registered (CPU, Memory, Disk)");
+      },
+    });
+  },
+});

package/src/plugin-metadata.ts

@@ -0,0 +1,5 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "collector-hardware",
+});

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json",
+  "include": [
+    "src"
+  ]
+}