@archipelagolab/lobi 1.0.0

package/src/migration-snapshot.test.ts

@@ -0,0 +1,184 @@
+import fs from "node:fs";
+import path from "node:path";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { withTempHome } from "../../../test/helpers/temp-home.js";
+
+const legacyCryptoInspectorAvailability = vi.hoisted(() => ({
+  available: true,
+}));
+
+vi.mock("./legacy-crypto-inspector-availability.js", () => ({
+  isMatrixLegacyCryptoInspectorAvailable: () => legacyCryptoInspectorAvailability.available,
+}));
+
+import { detectLegacyMatrixCrypto } from "./legacy-crypto.js";
+import {
+  hasActionableMatrixMigration,
+  maybeCreateMatrixMigrationSnapshot,
+  resolveMatrixMigrationSnapshotMarkerPath,
+  resolveMatrixMigrationSnapshotOutputDir,
+} from "./migration-snapshot.js";
+import { resolveMatrixAccountStorageRoot } from "./storage-paths.js";
+
+const createBackupArchiveMock = vi.hoisted(() => vi.fn());
+
+describe("matrix migration snapshots", () => {
+  beforeEach(() => {
+    createBackupArchiveMock.mockReset();
+    legacyCryptoInspectorAvailability.available = true;
+    createBackupArchiveMock.mockImplementation(
+      async (params: { output?: string; includeWorkspace?: boolean }) => {
+        const outputDir = params.output;
+        if (!outputDir) {
+          throw new Error("expected migration snapshot output dir");
+        }
+        fs.mkdirSync(outputDir, { recursive: true });
+        const archivePath = path.join(outputDir, "matrix-migration-backup.tar.gz");
+        fs.writeFileSync(archivePath, "archive\n", "utf8");
+        return {
+          createdAt: "2026-04-05T00:00:00.000Z",
+          archivePath,
+          includeWorkspace: params.includeWorkspace ?? true,
+        };
+      },
+    );
+  });
+
+  it("creates a backup marker after writing a pre-migration snapshot", async () => {
+    await withTempHome(async (home) => {
+      fs.writeFileSync(path.join(home, ".openclaw", "openclaw.json"), "{}\n", "utf8");
+      fs.writeFileSync(path.join(home, ".openclaw", "state.txt"), "state\n", "utf8");
+
+      const result = await maybeCreateMatrixMigrationSnapshot({
+        trigger: "unit-test",
+        createBackupArchive: createBackupArchiveMock,
+      });
+
+      expect(result.created).toBe(true);
+      expect(result.markerPath).toBe(resolveMatrixMigrationSnapshotMarkerPath(process.env));
+      expect(
+        result.archivePath.startsWith(resolveMatrixMigrationSnapshotOutputDir(process.env)),
+      ).toBe(true);
+      expect(fs.existsSync(result.archivePath)).toBe(true);
+      expect(createBackupArchiveMock).toHaveBeenCalledWith({
+        output: resolveMatrixMigrationSnapshotOutputDir(process.env),
+        includeWorkspace: false,
+      });
+    });
+  });
+
+  it("treats resolvable Matrix legacy state as actionable", async () => {
+    await withTempHome(async (home) => {
+      const stateDir = path.join(home, ".openclaw");
+      fs.mkdirSync(path.join(stateDir, "matrix"), { recursive: true });
+      fs.writeFileSync(
+        path.join(stateDir, "matrix", "bot-storage.json"),
+        '{"legacy":true}',
+        "utf8",
+      );
+
+      expect(
+        hasActionableMatrixMigration({
+          cfg: {
+            channels: {
+              matrix: {
+                homeserver: "https://matrix.example.org",
+                userId: "@bot:example.org",
+                accessToken: "tok-123",
+              },
+            },
+          } as never,
+          env: process.env,
+        }),
+      ).toBe(true);
+    });
+  });
+
+  it("treats legacy Matrix crypto as actionable when the extension inspector is present", async () => {
+    await withTempHome(async (home) => {
+      const stateDir = path.join(home, ".openclaw");
+      const { rootDir } = resolveMatrixAccountStorageRoot({
+        stateDir,
+        homeserver: "https://matrix.example.org",
+        userId: "@bot:example.org",
+        accessToken: "tok-123",
+      });
+      fs.mkdirSync(path.join(rootDir, "crypto"), { recursive: true });
+      fs.writeFileSync(
+        path.join(rootDir, "crypto", "bot-sdk.json"),
+        JSON.stringify({ deviceId: "DEVICE123" }),
+        "utf8",
+      );
+
+      const cfg = {
+        channels: {
+          matrix: {
+            homeserver: "https://matrix.example.org",
+            userId: "@bot:example.org",
+            accessToken: "tok-123",
+          },
+        },
+      } as never;
+
+      const detection = detectLegacyMatrixCrypto({
+        cfg,
+        env: process.env,
+      });
+      expect(detection.inspectorAvailable).toBe(true);
+      expect(detection.plans).toHaveLength(1);
+      expect(detection.warnings).toEqual([]);
+      expect(
+        hasActionableMatrixMigration({
+          cfg,
+          env: process.env,
+        }),
+      ).toBe(true);
+    });
+  });
+
+  it("keeps legacy Matrix crypto pending but not actionable when the inspector artifact is unavailable", async () => {
+    legacyCryptoInspectorAvailability.available = false;
+
+    await withTempHome(async (home) => {
+      const stateDir = path.join(home, ".openclaw");
+      const { rootDir } = resolveMatrixAccountStorageRoot({
+        stateDir,
+        homeserver: "https://matrix.example.org",
+        userId: "@bot:example.org",
+        accessToken: "tok-123",
+      });
+      fs.mkdirSync(path.join(rootDir, "crypto"), { recursive: true });
+      fs.writeFileSync(
+        path.join(rootDir, "crypto", "bot-sdk.json"),
+        JSON.stringify({ deviceId: "DEVICE123" }),
+        "utf8",
+      );
+
+      const cfg = {
+        channels: {
+          matrix: {
+            homeserver: "https://matrix.example.org",
+            userId: "@bot:example.org",
+            accessToken: "tok-123",
+          },
+        },
+      } as never;
+
+      const detection = detectLegacyMatrixCrypto({
+        cfg,
+        env: process.env,
+      });
+      expect(detection.inspectorAvailable).toBe(false);
+      expect(detection.plans).toHaveLength(1);
+      expect(detection.warnings).toContain(
+        "Legacy Matrix encrypted state was detected, but the Matrix crypto inspector is unavailable.",
+      );
+      expect(
+        hasActionableMatrixMigration({
+          cfg,
+          env: process.env,
+        }),
+      ).toBe(false);
+    });
+  });
+});

package/src/migration-snapshot.ts

@@ -0,0 +1,55 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
+import { detectLegacyMatrixCrypto } from "./legacy-crypto.js";
+import { detectLegacyMatrixState } from "./legacy-state.js";
+import {
+  maybeCreateMatrixMigrationSnapshot,
+  resolveMatrixMigrationSnapshotMarkerPath,
+  resolveMatrixMigrationSnapshotOutputDir,
+  type MatrixMigrationSnapshotResult,
+} from "./migration-snapshot-backup.js";
+
+export type MatrixMigrationStatus = {
+  legacyState: ReturnType<typeof detectLegacyMatrixState>;
+  legacyCrypto: ReturnType<typeof detectLegacyMatrixCrypto>;
+  pending: boolean;
+  actionable: boolean;
+};
+
+export function resolveMatrixMigrationStatus(params: {
+  cfg: OpenClawConfig;
+  env?: NodeJS.ProcessEnv;
+}): MatrixMigrationStatus {
+  const env = params.env ?? process.env;
+  const legacyState = detectLegacyMatrixState({ cfg: params.cfg, env });
+  const legacyCrypto = detectLegacyMatrixCrypto({ cfg: params.cfg, env });
+  const actionableLegacyState = legacyState !== null && !("warning" in legacyState);
+  const actionableLegacyCrypto = legacyCrypto.plans.length > 0 && legacyCrypto.inspectorAvailable;
+  return {
+    legacyState,
+    legacyCrypto,
+    pending:
+      legacyState !== null || legacyCrypto.plans.length > 0 || legacyCrypto.warnings.length > 0,
+    actionable: actionableLegacyState || actionableLegacyCrypto,
+  };
+}
+
+export function hasPendingMatrixMigration(params: {
+  cfg: OpenClawConfig;
+  env?: NodeJS.ProcessEnv;
+}): boolean {
+  return resolveMatrixMigrationStatus(params).pending;
+}
+
+export function hasActionableMatrixMigration(params: {
+  cfg: OpenClawConfig;
+  env?: NodeJS.ProcessEnv;
+}): boolean {
+  return resolveMatrixMigrationStatus(params).actionable;
+}
+
+export {
+  maybeCreateMatrixMigrationSnapshot,
+  resolveMatrixMigrationSnapshotMarkerPath,
+  resolveMatrixMigrationSnapshotOutputDir,
+};
+export type { MatrixMigrationSnapshotResult };

package/src/onboarding.resolve.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { installMatrixTestRuntime } from "./test-runtime.js";
+import type { CoreConfig } from "./types.js";
+
+const resolveMatrixTargetsMock = vi.hoisted(() =>
+  vi.fn(async () => [{ input: "Alice", resolved: true, id: "@alice:example.org" }]),
+);
+
+vi.mock("./resolve-targets.js", () => ({
+  resolveMatrixTargets: resolveMatrixTargetsMock,
+}));
+
+let runMatrixAddAccountAllowlistConfigure: typeof import("./onboarding.test-harness.js").runMatrixAddAccountAllowlistConfigure;
+
+describe("matrix onboarding account-scoped resolution", () => {
+  beforeAll(async () => {
+    ({ runMatrixAddAccountAllowlistConfigure } = await import("./onboarding.test-harness.js"));
+  });
+
+  beforeEach(() => {
+    installMatrixTestRuntime();
+    resolveMatrixTargetsMock.mockClear();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("passes accountId into Matrix allowlist target resolution during onboarding", async () => {
+    const result = await runMatrixAddAccountAllowlistConfigure({
+      cfg: {
+        channels: {
+          matrix: {
+            accounts: {
+              default: {
+                homeserver: "https://matrix.main.example.org",
+                accessToken: "main-token",
+              },
+            },
+          },
+        },
+      } as CoreConfig,
+      allowFromInput: "Alice",
+      roomsAllowlistInput: "",
+    });
+
+    expect(result).not.toBe("skip");
+    expect(resolveMatrixTargetsMock).toHaveBeenCalledWith({
+      cfg: expect.any(Object),
+      accountId: "ops",
+      inputs: ["Alice"],
+      kind: "user",
+    });
+  });
+});

package/src/onboarding.test-harness.ts

@@ -0,0 +1,158 @@
+import type { OutputRuntimeEnv } from "openclaw/plugin-sdk/runtime";
+import type { ChannelSetupWizardAdapter } from "openclaw/plugin-sdk/setup";
+import { afterEach, vi } from "vitest";
+import type { RuntimeEnv, WizardPrompter } from "../runtime-api.js";
+import type { CoreConfig } from "./types.js";
+
+type MatrixInteractiveOptions = Parameters<
+  NonNullable<ChannelSetupWizardAdapter["configureInteractive"]>
+>[0]["options"];
+
+const MATRIX_ENV_KEYS = [
+  "LOBI_HOMESERVER",
+  "LOBI_USER_ID",
+  "LOBI_ACCESS_TOKEN",
+  "LOBI_PASSWORD",
+  "LOBI_DEVICE_ID",
+  "LOBI_DEVICE_NAME",
+  "LOBI_OPS_HOMESERVER",
+  "LOBI_OPS_ACCESS_TOKEN",
+] as const;
+
+const previousMatrixEnv = Object.fromEntries(
+  MATRIX_ENV_KEYS.map((key) => [key, process.env[key]]),
+) as Record<(typeof MATRIX_ENV_KEYS)[number], string | undefined>;
+
+function createNonExitingTypedRuntimeEnv<TRuntime>(): TRuntime {
+  return {
+    log: vi.fn(),
+    error: vi.fn(),
+    writeStdout: vi.fn(),
+    writeJson: vi.fn(),
+    exit: vi.fn(),
+  } as OutputRuntimeEnv as TRuntime;
+}
+
+export function installMatrixOnboardingEnvRestoreHooks() {
+  afterEach(() => {
+    for (const [key, value] of Object.entries(previousMatrixEnv)) {
+      if (value === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = value;
+      }
+    }
+  });
+}
+
+type PromptHandler<T> = (message: string) => T;
+
+export function createMatrixWizardPrompter(params: {
+  notes?: string[];
+  select?: Record<string, string>;
+  text?: Record<string, string>;
+  confirm?: Record<string, boolean>;
+  onNote?: PromptHandler<void | Promise<void>>;
+  onSelect?: PromptHandler<string | Promise<string>>;
+  onText?: PromptHandler<string | Promise<string>>;
+  onConfirm?: PromptHandler<boolean | Promise<boolean>>;
+}): WizardPrompter {
+  const resolvePromptValue = async <T>(
+    kind: string,
+    message: string,
+    values: Record<string, T> | undefined,
+    fallback: PromptHandler<T | Promise<T>> | undefined,
+  ): Promise<T> => {
+    if (values && message in values) {
+      return values[message];
+    }
+    if (fallback) {
+      return await fallback(message);
+    }
+    throw new Error(`unexpected ${kind} prompt: ${message}`);
+  };
+
+  return {
+    note: vi.fn(async (message: unknown) => {
+      const text = String(message);
+      params.notes?.push(text);
+      await params.onNote?.(text);
+    }),
+    select: vi.fn(async ({ message }: { message: string }) => {
+      return await resolvePromptValue("select", message, params.select, params.onSelect);
+    }),
+    text: vi.fn(async ({ message }: { message: string }) => {
+      return await resolvePromptValue("text", message, params.text, params.onText);
+    }),
+    confirm: vi.fn(async ({ message }: { message: string }) => {
+      return await resolvePromptValue("confirm", message, params.confirm, params.onConfirm);
+    }),
+  } as unknown as WizardPrompter;
+}
+
+export async function runMatrixInteractiveConfigure(params: {
+  cfg: CoreConfig;
+  prompter: WizardPrompter;
+  options?: MatrixInteractiveOptions;
+  accountOverrides?: Record<string, string>;
+  shouldPromptAccountIds?: boolean;
+  forceAllowFrom?: boolean;
+  configured?: boolean;
+}) {
+  const { matrixOnboardingAdapter } = await import("./onboarding.js");
+  return await matrixOnboardingAdapter.configureInteractive!({
+    cfg: params.cfg,
+    runtime: createNonExitingTypedRuntimeEnv<RuntimeEnv>(),
+    prompter: params.prompter,
+    options: params.options,
+    accountOverrides: params.accountOverrides ?? {},
+    shouldPromptAccountIds: params.shouldPromptAccountIds ?? false,
+    forceAllowFrom: params.forceAllowFrom ?? false,
+    configured: params.configured ?? false,
+    label: "Matrix",
+  });
+}
+
+export async function runMatrixAddAccountAllowlistConfigure(params: {
+  cfg: CoreConfig;
+  allowFromInput: string;
+  roomsAllowlistInput: string;
+  autoJoinPolicy?: "always" | "allowlist" | "off";
+  autoJoinAllowlistInput?: string;
+  deviceName?: string;
+  notes?: string[];
+}) {
+  const prompter = createMatrixWizardPrompter({
+    notes: params.notes,
+    select: {
+      "Matrix already configured. What do you want to do?": "add-account",
+      "Matrix auth method": "token",
+      "Matrix rooms access": "allowlist",
+      "Matrix invite auto-join": params.autoJoinPolicy ?? "allowlist",
+    },
+    text: {
+      "Matrix account name": "ops",
+      "Matrix homeserver URL": "https://matrix.ops.example.org",
+      "Matrix access token": "ops-token",
+      "Matrix device name (optional)": params.deviceName ?? "",
+      "Matrix allowFrom (full @user:server; display name only if unique)": params.allowFromInput,
+      "Matrix rooms allowlist (comma-separated)": params.roomsAllowlistInput,
+      "Matrix invite auto-join allowlist (comma-separated)":
+        params.autoJoinAllowlistInput ?? "#ops-invites:example.org",
+    },
+    confirm: {
+      "Enable end-to-end encryption (E2EE)?": false,
+      "Configure Matrix rooms access?": true,
+      "Configure Matrix invite auto-join?": true,
+    },
+    onConfirm: async () => false,
+  });
+
+  return await runMatrixInteractiveConfigure({
+    cfg: params.cfg,
+    prompter,
+    shouldPromptAccountIds: true,
+    forceAllowFrom: true,
+    configured: true,
+  });
+}