@wopr-network/platform-core 1.24.0 → 1.25.0

package/dist/fleet/__tests__/init-fleet-updater.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/fleet/__tests__/init-fleet-updater.test.js

@@ -0,0 +1,93 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { initFleetUpdater } from "../init-fleet-updater.js";
+function mockDocker() {
+    return {};
+}
+function mockFleet() {
+    return {};
+}
+function mockStore() {
+    return {
+        list: vi.fn(async () => []),
+        get: vi.fn(async () => undefined),
+        save: vi.fn(async () => { }),
+        delete: vi.fn(async () => { }),
+    };
+}
+function mockRepo(profiles = []) {
+    return {
+        list: vi.fn(async () => profiles),
+        get: vi.fn(async () => null),
+        save: vi.fn(async (p) => p),
+        delete: vi.fn(async () => true),
+    };
+}
+describe("initFleetUpdater", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("returns a handle with all components", async () => {
+        const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo());
+        expect(handle.poller).toBeDefined();
+        expect(handle.updater).toBeDefined();
+        expect(handle.orchestrator).toBeDefined();
+        expect(handle.snapshotManager).toBeDefined();
+        expect(handle.stop).toBeTypeOf("function");
+        await handle.stop();
+    });
+    it("wires poller.onUpdateAvailable to orchestrator", async () => {
+        const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo());
+        expect(handle.poller.onUpdateAvailable).toBeTypeOf("function");
+        await handle.stop();
+    });
+    it("accepts custom strategy config", async () => {
+        const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo(), {
+            strategy: "immediate",
+            snapshotDir: "/tmp/snapshots",
+        });
+        expect(handle.orchestrator).toBeDefined();
+        await handle.stop();
+    });
+    it("accepts callbacks", async () => {
+        const onBotUpdated = vi.fn();
+        const onRolloutComplete = vi.fn();
+        const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo(), {
+            onBotUpdated,
+            onRolloutComplete,
+        });
+        expect(handle.orchestrator).toBeDefined();
+        await handle.stop();
+    });
+    it("stop() stops the poller", async () => {
+        const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo());
+        const stopSpy = vi.spyOn(handle.poller, "stop");
+        await handle.stop();
+        expect(stopSpy).toHaveBeenCalled();
+    });
+    it("filters manual-policy bots from updatable profiles", async () => {
+        const repo = mockRepo([
+            { id: "b1", updatePolicy: "nightly" },
+            { id: "b2", updatePolicy: "manual" },
+            { id: "b3", updatePolicy: "on-push" },
+        ]);
+        const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), repo, {
+            strategy: "immediate",
+        });
+        const rolloutResult = await handle.orchestrator.rollout();
+        // b2 (manual) should be filtered out, b1 and b3 included
+        expect(rolloutResult.totalBots).toBe(2);
+        await handle.stop();
+    });
+    it("uses profileRepo for updatable profiles, not profileStore", async () => {
+        const store = mockStore();
+        const repo = mockRepo([{ id: "b1", updatePolicy: "nightly" }]);
+        const handle = initFleetUpdater(mockDocker(), mockFleet(), store, repo, {
+            strategy: "immediate",
+        });
+        await handle.orchestrator.rollout();
+        // profileRepo.list() was called for updatable profiles
+        expect(repo.list).toHaveBeenCalled();
+        // profileStore.list() may also be called by ImagePoller — that's expected
+        await handle.stop();
+    });
+});

package/dist/fleet/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./init-fleet-updater.js";
 export * from "./repository-types.js";
 export * from "./rollout-orchestrator.js";
 export * from "./rollout-strategy.js";

package/dist/fleet/index.js

@@ -1,3 +1,4 @@
+export * from "./init-fleet-updater.js";
 export * from "./repository-types.js";
 export * from "./rollout-orchestrator.js";
 export * from "./rollout-strategy.js";

package/dist/fleet/init-fleet-updater.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Wires the fleet auto-update pipeline: ImagePoller → RolloutOrchestrator → ContainerUpdater.
+ *
+ * Consumers call initFleetUpdater() with a Docker instance, FleetManager, and config.
+ * The pipeline detects new image digests, batches updates via a rollout strategy,
+ * snapshots volumes before updating, and restores on failure (nuclear rollback).
+ *
+ * When a new image digest is detected for ANY bot, the orchestrator triggers a
+ * fleet-wide rollout across all non-manual bots. This is intentional: the managed
+ * Paperclip image is shared across all tenants, so a single digest change means
+ * all bots need updating.
+ */
+import type Docker from "dockerode";
+import type { IBotProfileRepository } from "./bot-profile-repository.js";
+import type { FleetManager } from "./fleet-manager.js";
+import { ImagePoller } from "./image-poller.js";
+import type { IProfileStore } from "./profile-store.js";
+import { RolloutOrchestrator, type RolloutResult } from "./rollout-orchestrator.js";
+import { type RollingWaveOptions } from "./rollout-strategy.js";
+import { ContainerUpdater } from "./updater.js";
+import { VolumeSnapshotManager } from "./volume-snapshot-manager.js";
+export interface FleetUpdaterConfig {
+    /** Rollout strategy type. Default: "rolling-wave" */
+    strategy?: "rolling-wave" | "single-bot" | "immediate";
+    /** Options for RollingWaveStrategy (ignored for other strategies) */
+    strategyOptions?: RollingWaveOptions;
+    /** Directory for volume snapshots. Default: "/data/fleet/snapshots" */
+    snapshotDir?: string;
+    /** Called after each bot update */
+    onBotUpdated?: (result: {
+        botId: string;
+        success: boolean;
+        volumeRestored: boolean;
+    }) => void;
+    /** Called when a rollout completes */
+    onRolloutComplete?: (result: RolloutResult) => void;
+}
+export interface FleetUpdaterHandle {
+    poller: ImagePoller;
+    updater: ContainerUpdater;
+    orchestrator: RolloutOrchestrator;
+    snapshotManager: VolumeSnapshotManager;
+    /** Stop the poller and wait for any active rollout to finish */
+    stop: () => Promise<void>;
+}
+/**
+ * Initialize the fleet auto-update pipeline.
+ *
+ * Creates and wires: ImagePoller → RolloutOrchestrator → ContainerUpdater
+ * with VolumeSnapshotManager for nuclear rollback.
+ *
+ * @param docker - Dockerode instance for container operations
+ * @param fleet - FleetManager for container lifecycle
+ * @param profileStore - Legacy IProfileStore (used by ImagePoller/ContainerUpdater)
+ * @param profileRepo - PostgreSQL-backed IBotProfileRepository (used for updatable profile queries)
+ * @param config - Optional pipeline configuration
+ */
+export declare function initFleetUpdater(docker: Docker, fleet: FleetManager, profileStore: IProfileStore, profileRepo: IBotProfileRepository, config?: FleetUpdaterConfig): FleetUpdaterHandle;

package/dist/fleet/init-fleet-updater.js

@@ -0,0 +1,88 @@
+/**
+ * Wires the fleet auto-update pipeline: ImagePoller → RolloutOrchestrator → ContainerUpdater.
+ *
+ * Consumers call initFleetUpdater() with a Docker instance, FleetManager, and config.
+ * The pipeline detects new image digests, batches updates via a rollout strategy,
+ * snapshots volumes before updating, and restores on failure (nuclear rollback).
+ *
+ * When a new image digest is detected for ANY bot, the orchestrator triggers a
+ * fleet-wide rollout across all non-manual bots. This is intentional: the managed
+ * Paperclip image is shared across all tenants, so a single digest change means
+ * all bots need updating.
+ */
+import { logger } from "../config/logger.js";
+import { ImagePoller } from "./image-poller.js";
+import { RolloutOrchestrator } from "./rollout-orchestrator.js";
+import { createRolloutStrategy } from "./rollout-strategy.js";
+import { ContainerUpdater } from "./updater.js";
+import { VolumeSnapshotManager } from "./volume-snapshot-manager.js";
+/**
+ * Initialize the fleet auto-update pipeline.
+ *
+ * Creates and wires: ImagePoller → RolloutOrchestrator → ContainerUpdater
+ * with VolumeSnapshotManager for nuclear rollback.
+ *
+ * @param docker - Dockerode instance for container operations
+ * @param fleet - FleetManager for container lifecycle
+ * @param profileStore - Legacy IProfileStore (used by ImagePoller/ContainerUpdater)
+ * @param profileRepo - PostgreSQL-backed IBotProfileRepository (used for updatable profile queries)
+ * @param config - Optional pipeline configuration
+ */
+export function initFleetUpdater(docker, fleet, profileStore, profileRepo, config = {}) {
+    const { strategy: strategyType = "rolling-wave", strategyOptions, snapshotDir = "/data/fleet/snapshots", onBotUpdated, onRolloutComplete, } = config;
+    const poller = new ImagePoller(docker, profileStore);
+    const updater = new ContainerUpdater(docker, profileStore, fleet, poller);
+    const snapshotManager = new VolumeSnapshotManager(docker, snapshotDir);
+    const strategy = createRolloutStrategy(strategyType, strategyOptions);
+    const orchestrator = new RolloutOrchestrator({
+        updater,
+        snapshotManager,
+        strategy,
+        getUpdatableProfiles: async () => {
+            const profiles = await profileRepo.list();
+            return profiles.filter((p) => p.updatePolicy !== "manual");
+        },
+        onBotUpdated,
+        onRolloutComplete,
+    });
+    // Wire the detection → orchestration pipeline.
+    // Any digest change triggers a fleet-wide rollout because the managed image
+    // is shared across all tenants — one new digest means all bots need updating.
+    poller.onUpdateAvailable = async (_botId, _newDigest) => {
+        if (orchestrator.isRolling) {
+            logger.debug("Skipping update trigger — rollout already in progress");
+            return;
+        }
+        logger.info("New image digest detected — starting fleet-wide rollout");
+        await orchestrator.rollout().catch((err) => {
+            logger.error("Rollout failed", { err });
+        });
+    };
+    // Start polling
+    poller.start().catch((err) => {
+        logger.error("ImagePoller failed to start", { err });
+    });
+    logger.info("Fleet auto-update pipeline initialized", {
+        strategy: strategyType,
+        snapshotDir,
+    });
+    return {
+        poller,
+        updater,
+        orchestrator,
+        snapshotManager,
+        stop: async () => {
+            poller.stop();
+            // Wait for any in-flight rollout to complete before returning
+            if (orchestrator.isRolling) {
+                logger.info("Waiting for active rollout to finish before shutdown...");
+                // Poll until rollout finishes (max 5 minutes)
+                const deadline = Date.now() + 5 * 60 * 1000;
+                while (orchestrator.isRolling && Date.now() < deadline) {
+                    await new Promise((r) => setTimeout(r, 1000));
+                }
+            }
+            logger.info("Fleet auto-update pipeline stopped");
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/platform-core",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/fleet/__tests__/init-fleet-updater.test.ts

@@ -0,0 +1,129 @@
+import type Docker from "dockerode";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { IBotProfileRepository } from "../bot-profile-repository.js";
+import type { FleetManager } from "../fleet-manager.js";
+import { initFleetUpdater } from "../init-fleet-updater.js";
+import type { IProfileStore } from "../profile-store.js";
+
+function mockDocker(): Docker {
+  return {} as Docker;
+}
+
+function mockFleet(): FleetManager {
+  return {} as FleetManager;
+}
+
+function mockStore(): IProfileStore {
+  return {
+    list: vi.fn(async () => []),
+    get: vi.fn(async () => undefined),
+    save: vi.fn(async () => {}),
+    delete: vi.fn(async () => {}),
+  } as unknown as IProfileStore;
+}
+
+function mockRepo(profiles: unknown[] = []): IBotProfileRepository {
+  return {
+    list: vi.fn(async () => profiles),
+    get: vi.fn(async () => null),
+    save: vi.fn(async (p: unknown) => p),
+    delete: vi.fn(async () => true),
+  } as unknown as IBotProfileRepository;
+}
+
+describe("initFleetUpdater", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns a handle with all components", async () => {
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo());
+
+    expect(handle.poller).toBeDefined();
+    expect(handle.updater).toBeDefined();
+    expect(handle.orchestrator).toBeDefined();
+    expect(handle.snapshotManager).toBeDefined();
+    expect(handle.stop).toBeTypeOf("function");
+
+    await handle.stop();
+  });
+
+  it("wires poller.onUpdateAvailable to orchestrator", async () => {
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo());
+
+    expect(handle.poller.onUpdateAvailable).toBeTypeOf("function");
+
+    await handle.stop();
+  });
+
+  it("accepts custom strategy config", async () => {
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo(), {
+      strategy: "immediate",
+      snapshotDir: "/tmp/snapshots",
+    });
+
+    expect(handle.orchestrator).toBeDefined();
+
+    await handle.stop();
+  });
+
+  it("accepts callbacks", async () => {
+    const onBotUpdated = vi.fn();
+    const onRolloutComplete = vi.fn();
+
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo(), {
+      onBotUpdated,
+      onRolloutComplete,
+    });
+
+    expect(handle.orchestrator).toBeDefined();
+
+    await handle.stop();
+  });
+
+  it("stop() stops the poller", async () => {
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), mockRepo());
+
+    const stopSpy = vi.spyOn(handle.poller, "stop");
+
+    await handle.stop();
+
+    expect(stopSpy).toHaveBeenCalled();
+  });
+
+  it("filters manual-policy bots from updatable profiles", async () => {
+    const repo = mockRepo([
+      { id: "b1", updatePolicy: "nightly" },
+      { id: "b2", updatePolicy: "manual" },
+      { id: "b3", updatePolicy: "on-push" },
+    ]);
+
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), mockStore(), repo, {
+      strategy: "immediate",
+    });
+
+    const rolloutResult = await handle.orchestrator.rollout();
+
+    // b2 (manual) should be filtered out, b1 and b3 included
+    expect(rolloutResult.totalBots).toBe(2);
+
+    await handle.stop();
+  });
+
+  it("uses profileRepo for updatable profiles, not profileStore", async () => {
+    const store = mockStore();
+    const repo = mockRepo([{ id: "b1", updatePolicy: "nightly" }]);
+
+    const handle = initFleetUpdater(mockDocker(), mockFleet(), store, repo, {
+      strategy: "immediate",
+    });
+
+    await handle.orchestrator.rollout();
+
+    // profileRepo.list() was called for updatable profiles
+    expect(repo.list).toHaveBeenCalled();
+    // profileStore.list() may also be called by ImagePoller — that's expected
+
+    await handle.stop();
+  });
+});

package/src/fleet/index.ts

@@ -1,3 +1,4 @@
+export * from "./init-fleet-updater.js";
 export * from "./repository-types.js";
 export * from "./rollout-orchestrator.js";
 export * from "./rollout-strategy.js";

package/src/fleet/init-fleet-updater.ts

@@ -0,0 +1,134 @@
+/**
+ * Wires the fleet auto-update pipeline: ImagePoller → RolloutOrchestrator → ContainerUpdater.
+ *
+ * Consumers call initFleetUpdater() with a Docker instance, FleetManager, and config.
+ * The pipeline detects new image digests, batches updates via a rollout strategy,
+ * snapshots volumes before updating, and restores on failure (nuclear rollback).
+ *
+ * When a new image digest is detected for ANY bot, the orchestrator triggers a
+ * fleet-wide rollout across all non-manual bots. This is intentional: the managed
+ * Paperclip image is shared across all tenants, so a single digest change means
+ * all bots need updating.
+ */
+
+import type Docker from "dockerode";
+import { logger } from "../config/logger.js";
+import type { IBotProfileRepository } from "./bot-profile-repository.js";
+import type { FleetManager } from "./fleet-manager.js";
+import { ImagePoller } from "./image-poller.js";
+import type { IProfileStore } from "./profile-store.js";
+import { RolloutOrchestrator, type RolloutResult } from "./rollout-orchestrator.js";
+import { createRolloutStrategy, type RollingWaveOptions } from "./rollout-strategy.js";
+import { ContainerUpdater } from "./updater.js";
+import { VolumeSnapshotManager } from "./volume-snapshot-manager.js";
+
+export interface FleetUpdaterConfig {
+  /** Rollout strategy type. Default: "rolling-wave" */
+  strategy?: "rolling-wave" | "single-bot" | "immediate";
+  /** Options for RollingWaveStrategy (ignored for other strategies) */
+  strategyOptions?: RollingWaveOptions;
+  /** Directory for volume snapshots. Default: "/data/fleet/snapshots" */
+  snapshotDir?: string;
+  /** Called after each bot update */
+  onBotUpdated?: (result: { botId: string; success: boolean; volumeRestored: boolean }) => void;
+  /** Called when a rollout completes */
+  onRolloutComplete?: (result: RolloutResult) => void;
+}
+
+export interface FleetUpdaterHandle {
+  poller: ImagePoller;
+  updater: ContainerUpdater;
+  orchestrator: RolloutOrchestrator;
+  snapshotManager: VolumeSnapshotManager;
+  /** Stop the poller and wait for any active rollout to finish */
+  stop: () => Promise<void>;
+}
+
+/**
+ * Initialize the fleet auto-update pipeline.
+ *
+ * Creates and wires: ImagePoller → RolloutOrchestrator → ContainerUpdater
+ * with VolumeSnapshotManager for nuclear rollback.
+ *
+ * @param docker - Dockerode instance for container operations
+ * @param fleet - FleetManager for container lifecycle
+ * @param profileStore - Legacy IProfileStore (used by ImagePoller/ContainerUpdater)
+ * @param profileRepo - PostgreSQL-backed IBotProfileRepository (used for updatable profile queries)
+ * @param config - Optional pipeline configuration
+ */
+export function initFleetUpdater(
+  docker: Docker,
+  fleet: FleetManager,
+  profileStore: IProfileStore,
+  profileRepo: IBotProfileRepository,
+  config: FleetUpdaterConfig = {},
+): FleetUpdaterHandle {
+  const {
+    strategy: strategyType = "rolling-wave",
+    strategyOptions,
+    snapshotDir = "/data/fleet/snapshots",
+    onBotUpdated,
+    onRolloutComplete,
+  } = config;
+
+  const poller = new ImagePoller(docker, profileStore);
+  const updater = new ContainerUpdater(docker, profileStore, fleet, poller);
+  const snapshotManager = new VolumeSnapshotManager(docker, snapshotDir);
+  const strategy = createRolloutStrategy(strategyType, strategyOptions);
+
+  const orchestrator = new RolloutOrchestrator({
+    updater,
+    snapshotManager,
+    strategy,
+    getUpdatableProfiles: async () => {
+      const profiles = await profileRepo.list();
+      return profiles.filter((p) => p.updatePolicy !== "manual");
+    },
+    onBotUpdated,
+    onRolloutComplete,
+  });
+
+  // Wire the detection → orchestration pipeline.
+  // Any digest change triggers a fleet-wide rollout because the managed image
+  // is shared across all tenants — one new digest means all bots need updating.
+  poller.onUpdateAvailable = async (_botId: string, _newDigest: string) => {
+    if (orchestrator.isRolling) {
+      logger.debug("Skipping update trigger — rollout already in progress");
+      return;
+    }
+    logger.info("New image digest detected — starting fleet-wide rollout");
+    await orchestrator.rollout().catch((err) => {
+      logger.error("Rollout failed", { err });
+    });
+  };
+
+  // Start polling
+  poller.start().catch((err) => {
+    logger.error("ImagePoller failed to start", { err });
+  });
+
+  logger.info("Fleet auto-update pipeline initialized", {
+    strategy: strategyType,
+    snapshotDir,
+  });
+
+  return {
+    poller,
+    updater,
+    orchestrator,
+    snapshotManager,
+    stop: async () => {
+      poller.stop();
+      // Wait for any in-flight rollout to complete before returning
+      if (orchestrator.isRolling) {
+        logger.info("Waiting for active rollout to finish before shutdown...");
+        // Poll until rollout finishes (max 5 minutes)
+        const deadline = Date.now() + 5 * 60 * 1000;
+        while (orchestrator.isRolling && Date.now() < deadline) {
+          await new Promise((r) => setTimeout(r, 1000));
+        }
+      }
+      logger.info("Fleet auto-update pipeline stopped");
+    },
+  };
+}