shadow-claw 1.23.4 → 1.24.0

package/src/core/utils/initControlPlane.test.ts

@@ -0,0 +1,276 @@
+import { jest } from "@jest/globals";
+import {
+  shouldConnectControlPlane,
+  detectCapabilities,
+  createDefaultControlPlaneClient,
+} from "./initControlPlane.js";
+
+describe("initControlPlane", () => {
+  const origWebSocket = globalThis.WebSocket;
+  const origEventSource = (globalThis as any).EventSource;
+
+  beforeAll(() => {
+    (globalThis as any).WebSocket = class MockWS {} as any;
+  });
+
+  afterAll(() => {
+    globalThis.WebSocket = origWebSocket;
+    (globalThis as any).EventSource = origEventSource;
+  });
+  describe("shouldConnectControlPlane", () => {
+    it("returns false for file: protocol", () => {
+      expect(
+        shouldConnectControlPlane({
+          protocol: "file:",
+          hostname: "localhost",
+        }),
+      ).toBe(false);
+    });
+
+    it("returns true for web-hosted domains including static hosts and custom servers", () => {
+      expect(
+        shouldConnectControlPlane({
+          protocol: "https:",
+          hostname: "user.github.io",
+        }),
+      ).toBe(true);
+
+      expect(
+        shouldConnectControlPlane({
+          protocol: "http:",
+          hostname: "127.0.0.1",
+        }),
+      ).toBe(true);
+
+      expect(
+        shouldConnectControlPlane({
+          protocol: "https:",
+          hostname: "my-shadowclaw-server.internal",
+        }),
+      ).toBe(true);
+    });
+  });
+
+  describe("detectCapabilities", () => {
+    it("detects available browser capabilities", () => {
+      const capabilities = detectCapabilities();
+      expect(Array.isArray(capabilities)).toBe(true);
+    });
+  });
+
+  describe("isControlPlaneEnabled", () => {
+    it("returns false by default (opt-in)", async () => {
+      const { isControlPlaneEnabled } = await import("./initControlPlane.js");
+      expect(await isControlPlaneEnabled()).toBe(false);
+    });
+
+    it("respects localStorage override", async () => {
+      const { isControlPlaneEnabled } = await import("./initControlPlane.js");
+      localStorage.setItem("control_plane_enabled", "true");
+      expect(await isControlPlaneEnabled()).toBe(true);
+      localStorage.removeItem("control_plane_enabled");
+    });
+  });
+
+  describe("getControlPlaneServerUrl", () => {
+    afterEach(() => {
+      localStorage.removeItem("control_plane_url");
+    });
+
+    it("defaults to 127.0.0.1 on static hosts like github.io", async () => {
+      const { getControlPlaneServerUrl } =
+        await import("./initControlPlane.js");
+
+      const urls = getControlPlaneServerUrl({
+        protocol: "https:",
+        hostname: "xt-ml.github.io",
+        host: "xt-ml.github.io",
+      });
+
+      expect(urls.httpUrl).toBe("http://127.0.0.1:8888");
+      expect(urls.wsUrl).toBe("ws://127.0.0.1:8888/ws/control");
+    });
+
+    it("respects configured custom server URL from localStorage", async () => {
+      const { getControlPlaneServerUrl } =
+        await import("./initControlPlane.js");
+
+      localStorage.setItem(
+        "control_plane_url",
+        "https://my-server.example.com",
+      );
+
+      const urls = getControlPlaneServerUrl();
+      expect(urls.httpUrl).toBe("https://my-server.example.com");
+      expect(urls.wsUrl).toBe("wss://my-server.example.com/ws/control");
+    });
+  });
+
+  describe("getOrCreateControlPlaneClientId", () => {
+    afterEach(() => {
+      localStorage.removeItem("control_plane_client_id");
+    });
+
+    it("generates a persistent non-empty client ID and stores in localStorage", async () => {
+      const { getOrCreateControlPlaneClientId } =
+        await import("./initControlPlane.js");
+      localStorage.removeItem("control_plane_client_id");
+
+      const id1 = getOrCreateControlPlaneClientId();
+      expect(typeof id1).toBe("string");
+      expect(id1.length).toBeGreaterThan(0);
+      expect(localStorage.getItem("control_plane_client_id")).toBe(id1);
+
+      // Subsequent call returns the exact same ID
+      const id2 = getOrCreateControlPlaneClientId();
+      expect(id2).toBe(id1);
+    });
+
+    it("respects pre-existing client ID in localStorage", async () => {
+      const { getOrCreateControlPlaneClientId } =
+        await import("./initControlPlane.js");
+      localStorage.setItem("control_plane_client_id", "my-custom-client-123");
+
+      const id = getOrCreateControlPlaneClientId();
+      expect(id).toBe("my-custom-client-123");
+    });
+  });
+
+  describe("createDefaultControlPlaneClient", () => {
+    afterEach(async () => {
+      const { stopControlPlaneClient } = await import("./initControlPlane.js");
+      stopControlPlaneClient();
+      localStorage.removeItem("control_plane_client_id");
+    });
+
+    it("creates and connects a ControlPlaneClient with orchestrator handlers", () => {
+      const mockOrchestrator: any = {
+        submitMessage: jest.fn(),
+        state: "idle",
+      };
+
+      const client = createDefaultControlPlaneClient({
+        orchestrator: mockOrchestrator,
+        clientId: "test-client-init",
+        autoConnect: false,
+      });
+
+      expect(client).toBeDefined();
+      expect(client.getState()).toBe("disconnected");
+    });
+
+    it("generates a non-empty clientId automatically when not provided in options", async () => {
+      const client = createDefaultControlPlaneClient({
+        autoConnect: false,
+      });
+
+      expect(client).toBeDefined();
+      // Should have generated and saved a client ID
+      const savedId = localStorage.getItem("control_plane_client_id");
+      expect(savedId).toBeTruthy();
+      expect(savedId?.length).toBeGreaterThan(0);
+    });
+
+    it("cleans up existing active client when re-created", async () => {
+      const { getActiveControlPlaneClient } =
+        await import("./initControlPlane.js");
+
+      const client1 = createDefaultControlPlaneClient({ autoConnect: false });
+      expect(getActiveControlPlaneClient()).toBe(client1);
+
+      const client2 = createDefaultControlPlaneClient({ autoConnect: false });
+      expect(getActiveControlPlaneClient()).toBe(client2);
+      expect(client1.getState()).toBe("disconnected");
+    });
+
+    it("handles send-message with browserChat and submitMessage", async () => {
+      const mockSubmit = jest.fn();
+      const mockOrchestrator: any = {
+        browserChat: {
+          submit: mockSubmit,
+        },
+      };
+
+      const client = createDefaultControlPlaneClient({
+        orchestrator: mockOrchestrator,
+        autoConnect: false,
+      });
+
+      const handler = (client as any)._handlers.get("send-message");
+      expect(handler).toBeDefined();
+
+      const result = await handler({ text: "Hello CLI", groupId: "br:main" });
+      expect(result).toEqual({ queued: true, groupId: "br:main" });
+      expect(mockSubmit).toHaveBeenCalledWith("Hello CLI", "br:main");
+    });
+
+    it("handles read-state", async () => {
+      const mockOrchestrator: any = {
+        activeGroupId: "br:custom",
+        state: "responding",
+      };
+
+      const client = createDefaultControlPlaneClient({
+        orchestrator: mockOrchestrator,
+        autoConnect: false,
+      });
+
+      const handler = (client as any)._handlers.get("read-state");
+      expect(handler).toBeDefined();
+
+      const stateResult = await handler();
+      expect(stateResult.activeGroupId).toBe("br:custom");
+      expect(stateResult.state).toBe("responding");
+    });
+
+    it("handles list-tasks and filters by groupId when specified", async () => {
+      const { openDatabase } = await import("../../db/openDatabase.js");
+      const { saveTask } = await import("../../db/saveTask.js");
+      const db = await openDatabase();
+
+      await saveTask(db, {
+        id: "task-1",
+        groupId: "br:main",
+        name: "Main task",
+        prompt: "Do main work",
+        enabled: true,
+        createdAt: Date.now(),
+        lastRun: null,
+      });
+
+      await saveTask(db, {
+        id: "task-2",
+        groupId: "peer:cli-123",
+        name: "Peer task",
+        prompt: "Do peer work",
+        enabled: true,
+        createdAt: Date.now(),
+        lastRun: null,
+      });
+
+      const client = createDefaultControlPlaneClient({
+        autoConnect: false,
+      });
+
+      const handler = (client as any)._handlers.get("list-tasks");
+      expect(handler).toBeDefined();
+
+      // All tasks
+      const allResult = await handler({});
+      expect(allResult.tasks.some((t: any) => t.id === "task-1")).toBe(true);
+      expect(allResult.tasks.some((t: any) => t.id === "task-2")).toBe(true);
+
+      // Filtered by groupId
+      const filteredResult = await handler({ groupId: "br:main" });
+      expect(
+        filteredResult.tasks.every((t: any) => t.groupId === "br:main"),
+      ).toBe(true);
+      expect(filteredResult.tasks.some((t: any) => t.id === "task-1")).toBe(
+        true,
+      );
+      expect(filteredResult.tasks.some((t: any) => t.id === "task-2")).toBe(
+        false,
+      );
+    });
+  });
+});

package/src/core/utils/initControlPlane.ts

@@ -0,0 +1,437 @@
+/**
+ * ShadowClaw — Control Plane Browser Initialization Helper
+ */
+
+import { ControlPlaneClient } from "../control-plane-client.js";
+import { getDeploymentNamespace } from "../app-routes.js";
+import { getDb } from "../../db/db.js";
+import { getAllTasks } from "../../db/getAllTasks.js";
+import { ulid } from "../../utils/ulid.js";
+import {
+  CONFIG_KEYS,
+  DEFAULT_CONTROL_PLANE_ENABLED,
+  DEFAULT_CONTROL_PLANE_TRANSPORT,
+} from "../../config/config.js";
+import type { ControlPlaneTransport } from "../../server/control-plane-types.js";
+
+export function getOrCreateControlPlaneClientId(): string {
+  if (typeof localStorage !== "undefined") {
+    try {
+      const stored = localStorage.getItem(CONFIG_KEYS.CONTROL_PLANE_CLIENT_ID);
+      if (stored && stored.trim()) {
+        return stored.trim();
+      }
+    } catch (_) {}
+  }
+
+  const namespace = getDeploymentNamespace();
+  const generated = namespace
+    ? `${namespace}-${ulid().toLowerCase()}`
+    : `client-${ulid().toLowerCase()}`;
+
+  if (typeof localStorage !== "undefined") {
+    try {
+      localStorage.setItem(CONFIG_KEYS.CONTROL_PLANE_CLIENT_ID, generated);
+    } catch (_) {}
+  }
+
+  return generated;
+}
+
+export function isControlPlaneEnabledSync(): boolean {
+  if (typeof localStorage !== "undefined") {
+    try {
+      const val = localStorage.getItem(CONFIG_KEYS.CONTROL_PLANE_ENABLED);
+      if (val !== null) {
+        return val === "true" || val === "1";
+      }
+    } catch (_) {}
+  }
+  return DEFAULT_CONTROL_PLANE_ENABLED;
+}
+
+export async function isControlPlaneEnabled(db?: any): Promise<boolean> {
+  if (typeof localStorage !== "undefined") {
+    try {
+      const val = localStorage.getItem(CONFIG_KEYS.CONTROL_PLANE_ENABLED);
+      if (val !== null) {
+        return val === "true" || val === "1";
+      }
+    } catch (_) {}
+  }
+
+  if (db) {
+    try {
+      const { getConfig } = await import("../../db/getConfig.js");
+      const val = await getConfig(db, CONFIG_KEYS.CONTROL_PLANE_ENABLED);
+      if (val !== null && val !== undefined) {
+        return val === "true" || val === "1";
+      }
+    } catch (_) {}
+  }
+
+  return DEFAULT_CONTROL_PLANE_ENABLED;
+}
+
+export function shouldConnectControlPlane(loc?: {
+  protocol?: string;
+  hostname?: string;
+}): boolean {
+  if (typeof EventSource === "undefined" && typeof WebSocket === "undefined") {
+    return false;
+  }
+
+  const currentLoc = loc || (typeof location !== "undefined" ? location : null);
+  if (!currentLoc) {
+    return false;
+  }
+
+  if (currentLoc.protocol === "file:") {
+    return false;
+  }
+
+  if (
+    typeof document !== "undefined" &&
+    document.querySelector('meta[name="shadowclaw-static-only"]')
+  ) {
+    return false;
+  }
+
+  return true;
+}
+
+export function getControlPlaneServerUrl(loc?: {
+  protocol?: string;
+  host?: string;
+  hostname?: string;
+}): { httpUrl: string; wsUrl: string } {
+  let customUrl = "";
+  if (typeof localStorage !== "undefined") {
+    try {
+      customUrl = (
+        localStorage.getItem(CONFIG_KEYS.CONTROL_PLANE_URL) || ""
+      ).trim();
+    } catch (_) {}
+  }
+
+  const currentLoc = loc || (typeof location !== "undefined" ? location : null);
+  const isStaticHost =
+    currentLoc &&
+    (currentLoc.protocol === "file:" ||
+      (currentLoc.hostname &&
+        (currentLoc.hostname.endsWith(".github.io") ||
+          currentLoc.hostname.endsWith(".pages.dev"))));
+
+  let baseHttp = customUrl;
+  if (!baseHttp) {
+    if (isStaticHost) {
+      baseHttp = "http://127.0.0.1:8888";
+    } else if (currentLoc && currentLoc.host) {
+      baseHttp = `${currentLoc.protocol}//${currentLoc.host}`;
+    } else {
+      baseHttp = "http://127.0.0.1:8888";
+    }
+  }
+
+  baseHttp = baseHttp.replace(/\/+$/, "");
+
+  const baseWs = baseHttp.replace(/^https?:/, (proto) =>
+    proto === "https:" ? "wss:" : "ws:",
+  );
+
+  return {
+    httpUrl: baseHttp,
+    wsUrl: `${baseWs}/ws/control`,
+  };
+}
+
+export function detectCapabilities(): string[] {
+  const caps: string[] = [];
+
+  if (typeof navigator !== "undefined") {
+    if (
+      navigator.storage &&
+      typeof navigator.storage.getDirectory === "function"
+    ) {
+      caps.push("opfs");
+    }
+
+    if (
+      "serviceWorker" in navigator &&
+      typeof window !== "undefined" &&
+      "PushManager" in window
+    ) {
+      caps.push("push");
+    }
+
+    if (
+      (typeof document !== "undefined" && (document as any).modelContext) ||
+      ((navigator as any) && (navigator as any).modelContext)
+    ) {
+      caps.push("webmcp");
+    }
+  }
+
+  if (typeof RTCPeerConnection !== "undefined") {
+    caps.push("peerjs");
+  }
+
+  return caps;
+}
+
+export function detectDeviceLabel(): string {
+  if (typeof navigator === "undefined") {
+    return "ShadowClaw Node";
+  }
+
+  const ua = navigator.userAgent;
+  let device = "Desktop";
+  if (/iPad/i.test(ua)) device = "iPad";
+  else if (/iPhone/i.test(ua)) device = "iPhone";
+  else if (/Android/i.test(ua)) device = "Android";
+  else if (/Macintosh/i.test(ua)) device = "Mac";
+  else if (/Windows/i.test(ua)) device = "Windows";
+  else if (/Linux/i.test(ua)) device = "Linux";
+
+  let browser = "Browser";
+  if (/Chrome/i.test(ua) && !/Edg/i.test(ua)) browser = "Chrome";
+  else if (/Safari/i.test(ua) && !/Chrome/i.test(ua)) browser = "Safari";
+  else if (/Firefox/i.test(ua)) browser = "Firefox";
+  else if (/Edg/i.test(ua)) browser = "Edge";
+
+  return `${device} ${browser}`;
+}
+
+export interface InitControlPlaneOptions {
+  orchestrator?: any;
+  clientId?: string;
+  transport?: ControlPlaneTransport;
+  autoConnect?: boolean;
+}
+
+let activeClient: ControlPlaneClient | null = null;
+
+export async function executeClientControlCommand(
+  action: string,
+  args: any = {},
+  options: InitControlPlaneOptions = {},
+): Promise<any> {
+  const clientId = getOrCreateControlPlaneClientId();
+  const deviceLabel = detectDeviceLabel();
+  const capabilities = detectCapabilities();
+
+  switch (action) {
+    case "send-message": {
+      if (!args.text) {
+        throw new Error("Missing text parameter");
+      }
+      const { orchestratorStore } =
+        await import("../../stores/orchestrator.js");
+      const orch = options.orchestrator || orchestratorStore.orchestrator;
+      const targetGroupId =
+        args.groupId || orchestratorStore.activeGroupId || "br:main";
+
+      if (orch?.browserChat?.submit) {
+        orch.browserChat.submit(args.text, targetGroupId);
+        return { queued: true, groupId: targetGroupId };
+      }
+      if (orch?.submitMessage) {
+        orch.submitMessage(args.text, targetGroupId);
+        return { queued: true, groupId: targetGroupId };
+      }
+      if (orchestratorStore.sendMessage) {
+        orchestratorStore.sendMessage(args.text);
+        return { queued: true, groupId: targetGroupId };
+      }
+      return { queued: false, error: "Orchestrator not ready" };
+    }
+
+    case "list-tasks": {
+      const db = await getDb();
+      let tasks = await getAllTasks(db);
+      if (args?.groupId) {
+        tasks = tasks.filter((t) => t.groupId === args.groupId);
+      }
+      return { tasks };
+    }
+
+    case "read-state": {
+      const { orchestratorStore } =
+        await import("../../stores/orchestrator.js");
+      const orch = options.orchestrator || orchestratorStore.orchestrator;
+      return {
+        clientId,
+        deviceLabel,
+        capabilities,
+        activeGroupId:
+          options.orchestrator?.activeGroupId ||
+          orchestratorStore.activeGroupId ||
+          orch?.activeGroupId ||
+          "br:main",
+        state:
+          options.orchestrator?.state ||
+          orchestratorStore.state ||
+          orch?.state ||
+          "idle",
+      };
+    }
+
+    case "invoke-tool": {
+      if (!args.toolName) {
+        throw new Error("Missing toolName parameter");
+      }
+      const ctx =
+        (typeof document !== "undefined" && (document as any).modelContext) ||
+        (typeof navigator !== "undefined" && (navigator as any).modelContext);
+
+      const result = await ctx.invoke(args.toolName, args.input);
+      return { result };
+    }
+
+    case "trigger-backup": {
+      const { orchestratorStore } =
+        await import("../../stores/orchestrator.js");
+      const targetGroupId =
+        args.groupId ||
+        options.orchestrator?.activeGroupId ||
+        orchestratorStore.activeGroupId ||
+        "br:main";
+      const db = await getDb();
+      const { getGroupDir } = await import("../../storage/getGroupDir.js");
+      const groupDir = await getGroupDir(db, targetGroupId);
+
+      async function collectFiles(
+        dir: FileSystemDirectoryHandle,
+        prefix = "",
+      ): Promise<string[]> {
+        const result: string[] = [];
+        for await (const [name, handle] of (dir as any).entries()) {
+          const relPath = prefix ? `${prefix}/${name}` : name;
+          if (handle.kind === "directory") {
+            const sub = await collectFiles(handle, relPath);
+            result.push(...sub);
+          } else {
+            result.push(relPath);
+          }
+        }
+        return result;
+      }
+
+      async function readFile(relPath: string): Promise<Uint8Array | null> {
+        try {
+          const parts = relPath.split("/");
+          let cur: FileSystemDirectoryHandle = groupDir;
+          for (let i = 0; i < parts.length - 1; i++) {
+            cur = await cur.getDirectoryHandle(parts[i]);
+          }
+          const fileHandle = await cur.getFileHandle(parts[parts.length - 1]);
+          const file = await fileHandle.getFile();
+          const buffer = await file.arrayBuffer();
+          return new Uint8Array(buffer);
+        } catch {
+          return null;
+        }
+      }
+
+      const { BackupController } = await import("../backup-controller.js");
+      const backupCtrl = new BackupController({
+        clientId,
+        token: args.token,
+        fileEnumerator: () => collectFiles(groupDir),
+        fileReader: (filePath) => readFile(filePath),
+      });
+
+      const result = await backupCtrl.initiate();
+      return result;
+    }
+
+    default:
+      throw new Error(`Unknown action '${action}'`);
+  }
+}
+
+export function createDefaultControlPlaneClient(
+  options: InitControlPlaneOptions = {},
+): ControlPlaneClient {
+  if (activeClient) {
+    try {
+      activeClient.disconnect();
+    } catch (_) {}
+    activeClient = null;
+  }
+
+  const clientId =
+    (options.clientId && options.clientId.trim()) ||
+    getOrCreateControlPlaneClientId();
+  const capabilities = detectCapabilities();
+  const deviceLabel = detectDeviceLabel();
+
+  let configuredTransport: ControlPlaneTransport | null = null;
+  if (typeof localStorage !== "undefined") {
+    try {
+      const stored = localStorage.getItem(CONFIG_KEYS.CONTROL_PLANE_TRANSPORT);
+      if (stored === "sse" || stored === "websocket") {
+        configuredTransport = stored;
+      }
+    } catch (_) {}
+  }
+
+  const transport =
+    options.transport ||
+    configuredTransport ||
+    (DEFAULT_CONTROL_PLANE_TRANSPORT as ControlPlaneTransport);
+
+  let peerId: string | undefined;
+  if (typeof localStorage !== "undefined") {
+    try {
+      // CONFIG_KEYS.PEERJS_MY_PEER_ID is "peerjs_my_peer_id" — set by configurePeerJs via setConfig.
+      // We also check the raw IndexedDB config key written by setConfig, which mirrors to localStorage
+      // under the same key name in browser environments that support it.
+      peerId = localStorage.getItem(CONFIG_KEYS.PEERJS_MY_PEER_ID) || undefined;
+    } catch (_) {}
+  }
+
+  const { httpUrl, wsUrl } = getControlPlaneServerUrl();
+
+  const client = new ControlPlaneClient({
+    clientId,
+    deviceLabel,
+    capabilities,
+    peerId,
+    transport,
+    httpUrl,
+    url: wsUrl,
+    handlers: {
+      "send-message": (args: any) =>
+        executeClientControlCommand("send-message", args, options),
+      "list-tasks": (args: any) =>
+        executeClientControlCommand("list-tasks", args, options),
+      "read-state": (args: any) =>
+        executeClientControlCommand("read-state", args, options),
+      "invoke-tool": (args: any) =>
+        executeClientControlCommand("invoke-tool", args, options),
+      "trigger-backup": (args: any) =>
+        executeClientControlCommand("trigger-backup", args, options),
+    },
+  });
+
+  if (options.autoConnect !== false && shouldConnectControlPlane()) {
+    client.connect();
+  }
+
+  activeClient = client;
+  return client;
+}
+
+export function getActiveControlPlaneClient(): ControlPlaneClient | null {
+  return activeClient;
+}
+
+export function stopControlPlaneClient(): void {
+  if (activeClient) {
+    try {
+      activeClient.disconnect();
+    } catch (_) {}
+    activeClient = null;
+  }
+}