@gakr-gakr/matrix 0.1.0

package/src/migration-config.ts

@@ -0,0 +1,243 @@
+import fs from "node:fs";
+import os from "node:os";
+import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "autobot/plugin-sdk/account-id";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { resolveStateDir } from "autobot/plugin-sdk/state-paths";
+import { normalizeOptionalString } from "autobot/plugin-sdk/string-coerce-runtime";
+import {
+  findMatrixAccountEntry,
+  requiresExplicitMatrixDefaultAccount,
+  resolveConfiguredMatrixAccountIds,
+  resolveMatrixChannelConfig,
+  resolveMatrixDefaultOrOnlyAccountId,
+} from "./account-selection.js";
+import { resolveMatrixAccountStringValues } from "./auth-precedence.js";
+import {
+  resolveGlobalMatrixEnvConfig,
+  resolveScopedMatrixEnvConfig,
+} from "./matrix/client/env-auth.js";
+import { resolveMatrixAccountStorageRoot, resolveMatrixCredentialsPath } from "./storage-paths.js";
+
+type MatrixStoredCredentials = {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  deviceId?: string;
+};
+
+type MatrixMigrationAccountTarget = {
+  accountId: string;
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  rootDir: string;
+  storedDeviceId: string | null;
+};
+
+type MatrixLegacyFlatStoreTarget = MatrixMigrationAccountTarget & {
+  selectionNote?: string;
+};
+
+type MatrixLegacyFlatStoreKind = "state" | "encrypted state";
+
+function clean(value: unknown): string {
+  return normalizeOptionalString(value) ?? "";
+}
+
+function resolveMatrixAccountConfigEntry(
+  cfg: AutoBotConfig,
+  accountId: string,
+): Record<string, unknown> | null {
+  return findMatrixAccountEntry(cfg, accountId);
+}
+
+function resolveMatrixFlatStoreSelectionNote(
+  cfg: AutoBotConfig,
+  accountId: string,
+): string | undefined {
+  if (resolveConfiguredMatrixAccountIds(cfg).length <= 1) {
+    return undefined;
+  }
+  return (
+    `Legacy Matrix flat store uses one shared on-disk state, so it will be migrated into ` +
+    `account "${accountId}".`
+  );
+}
+
+function resolveMatrixMigrationConfigFields(params: {
+  cfg: AutoBotConfig;
+  env: NodeJS.ProcessEnv;
+  accountId: string;
+}): {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+} {
+  const channel = resolveMatrixChannelConfig(params.cfg);
+  const account = resolveMatrixAccountConfigEntry(params.cfg, params.accountId);
+  const scopedEnv = resolveScopedMatrixEnvConfig(params.accountId, params.env);
+  const globalEnv = resolveGlobalMatrixEnvConfig(params.env);
+  const normalizedAccountId = normalizeAccountId(params.accountId);
+  const resolvedStrings = resolveMatrixAccountStringValues({
+    accountId: normalizedAccountId,
+    account: {
+      homeserver: clean(account?.homeserver),
+      userId: clean(account?.userId),
+      accessToken: clean(account?.accessToken),
+    },
+    scopedEnv,
+    channel: {
+      homeserver: clean(channel?.homeserver),
+      userId: clean(channel?.userId),
+      accessToken: clean(channel?.accessToken),
+    },
+    globalEnv,
+  });
+
+  return {
+    homeserver: resolvedStrings.homeserver,
+    userId: resolvedStrings.userId,
+    accessToken: resolvedStrings.accessToken,
+  };
+}
+
+function loadStoredMatrixCredentials(
+  env: NodeJS.ProcessEnv,
+  accountId: string,
+): MatrixStoredCredentials | null {
+  const stateDir = resolveStateDir(env, os.homedir);
+  const credentialsPath = resolveMatrixCredentialsPath({
+    stateDir,
+    accountId: normalizeAccountId(accountId),
+  });
+  try {
+    if (!fs.existsSync(credentialsPath)) {
+      return null;
+    }
+    const parsed = JSON.parse(
+      fs.readFileSync(credentialsPath, "utf8"),
+    ) as Partial<MatrixStoredCredentials>;
+    if (
+      typeof parsed.homeserver !== "string" ||
+      typeof parsed.userId !== "string" ||
+      typeof parsed.accessToken !== "string"
+    ) {
+      return null;
+    }
+    return {
+      homeserver: parsed.homeserver,
+      userId: parsed.userId,
+      accessToken: parsed.accessToken,
+      deviceId: typeof parsed.deviceId === "string" ? parsed.deviceId : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function credentialsMatchResolvedIdentity(
+  stored: MatrixStoredCredentials | null,
+  identity: {
+    homeserver: string;
+    userId: string;
+    accessToken: string;
+  },
+): stored is MatrixStoredCredentials {
+  if (!stored || !identity.homeserver) {
+    return false;
+  }
+  if (!identity.userId) {
+    if (!identity.accessToken) {
+      return false;
+    }
+    return stored.homeserver === identity.homeserver && stored.accessToken === identity.accessToken;
+  }
+  return stored.homeserver === identity.homeserver && stored.userId === identity.userId;
+}
+
+export function resolveMatrixMigrationAccountTarget(params: {
+  cfg: AutoBotConfig;
+  env: NodeJS.ProcessEnv;
+  accountId: string;
+}): MatrixMigrationAccountTarget | null {
+  const stored = loadStoredMatrixCredentials(params.env, params.accountId);
+  const resolved = resolveMatrixMigrationConfigFields(params);
+  const matchingStored = credentialsMatchResolvedIdentity(stored, {
+    homeserver: resolved.homeserver,
+    userId: resolved.userId,
+    accessToken: resolved.accessToken,
+  })
+    ? stored
+    : null;
+  const homeserver = resolved.homeserver;
+  const userId = resolved.userId || matchingStored?.userId || "";
+  const accessToken = resolved.accessToken || matchingStored?.accessToken || "";
+  if (!homeserver || !userId || !accessToken) {
+    return null;
+  }
+
+  const stateDir = resolveStateDir(params.env, os.homedir);
+  const { rootDir } = resolveMatrixAccountStorageRoot({
+    stateDir,
+    homeserver,
+    userId,
+    accessToken,
+    accountId: params.accountId,
+  });
+
+  return {
+    accountId: params.accountId,
+    homeserver,
+    userId,
+    accessToken,
+    rootDir,
+    storedDeviceId: matchingStored?.deviceId ?? null,
+  };
+}
+
+export function resolveLegacyMatrixFlatStoreTarget(params: {
+  cfg: AutoBotConfig;
+  env: NodeJS.ProcessEnv;
+  detectedPath: string;
+  detectedKind: MatrixLegacyFlatStoreKind;
+}): MatrixLegacyFlatStoreTarget | { warning: string } {
+  const channel = resolveMatrixChannelConfig(params.cfg);
+  if (!channel) {
+    return {
+      warning:
+        `Legacy Matrix ${params.detectedKind} detected at ${params.detectedPath}, but channels.matrix is not configured yet. ` +
+        'Configure Matrix, then rerun "autobot doctor --fix" or restart the gateway.',
+    };
+  }
+  if (requiresExplicitMatrixDefaultAccount(params.cfg)) {
+    return {
+      warning:
+        `Legacy Matrix ${params.detectedKind} detected at ${params.detectedPath}, but multiple Matrix accounts are configured and channels.matrix.defaultAccount is not set. ` +
+        'Set "channels.matrix.defaultAccount" to the intended target account before rerunning "autobot doctor --fix" or restarting the gateway.',
+    };
+  }
+
+  const accountId = resolveMatrixDefaultOrOnlyAccountId(params.cfg);
+  const target = resolveMatrixMigrationAccountTarget({
+    cfg: params.cfg,
+    env: params.env,
+    accountId,
+  });
+  if (!target) {
+    const targetDescription =
+      params.detectedKind === "state"
+        ? "the new account-scoped target"
+        : "the account-scoped target";
+    return {
+      warning:
+        `Legacy Matrix ${params.detectedKind} detected at ${params.detectedPath}, but ${targetDescription} could not be resolved yet ` +
+        `(need homeserver, userId, and access token for channels.matrix${accountId === DEFAULT_ACCOUNT_ID ? "" : `.accounts.${accountId}`}). ` +
+        'Start the gateway once with a working Matrix login, or rerun "autobot doctor --fix" after cached credentials are available.',
+    };
+  }
+
+  return {
+    ...target,
+    selectionNote: resolveMatrixFlatStoreSelectionNote(params.cfg, accountId),
+  };
+}

package/src/migration-snapshot-backup.ts

@@ -0,0 +1,116 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { writeJsonFileAtomically } from "autobot/plugin-sdk/json-store";
+import { resolveRequiredHomeDir, resolveStateDir } from "autobot/plugin-sdk/state-paths";
+
+const MATRIX_MIGRATION_SNAPSHOT_DIRNAME = "autobot-migrations";
+
+type MatrixMigrationSnapshotMarker = {
+  version: 1;
+  createdAt: string;
+  archivePath: string;
+  trigger: string;
+  includeWorkspace: boolean;
+};
+
+type MatrixMigrationSnapshotResult = {
+  created: boolean;
+  archivePath: string;
+  markerPath: string;
+};
+
+function loadSnapshotMarker(filePath: string): MatrixMigrationSnapshotMarker | null {
+  try {
+    if (!fs.existsSync(filePath)) {
+      return null;
+    }
+    const parsed = JSON.parse(
+      fs.readFileSync(filePath, "utf8"),
+    ) as Partial<MatrixMigrationSnapshotMarker>;
+    if (
+      parsed.version !== 1 ||
+      typeof parsed.createdAt !== "string" ||
+      typeof parsed.archivePath !== "string" ||
+      typeof parsed.trigger !== "string"
+    ) {
+      return null;
+    }
+    return {
+      version: 1,
+      createdAt: parsed.createdAt,
+      archivePath: parsed.archivePath,
+      trigger: parsed.trigger,
+      includeWorkspace: parsed.includeWorkspace === true,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function resolveMatrixMigrationSnapshotMarkerPath(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const stateDir = resolveStateDir(env, os.homedir);
+  return path.join(stateDir, "matrix", "migration-snapshot.json");
+}
+
+export function resolveMatrixMigrationSnapshotOutputDir(
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const homeDir = resolveRequiredHomeDir(env, os.homedir);
+  return path.join(homeDir, "Backups", MATRIX_MIGRATION_SNAPSHOT_DIRNAME);
+}
+
+export async function maybeCreateMatrixMigrationSnapshot(params: {
+  trigger: string;
+  env?: NodeJS.ProcessEnv;
+  outputDir?: string;
+  createBackupArchive?: typeof import("autobot/plugin-sdk/runtime").createBackupArchive;
+  log?: { info?: (message: string) => void; warn?: (message: string) => void };
+}): Promise<MatrixMigrationSnapshotResult> {
+  const env = params.env ?? process.env;
+  const createBackupArchive =
+    params.createBackupArchive ?? (await import("autobot/plugin-sdk/runtime")).createBackupArchive;
+  const markerPath = resolveMatrixMigrationSnapshotMarkerPath(env);
+  const existingMarker = loadSnapshotMarker(markerPath);
+  if (existingMarker?.archivePath && fs.existsSync(existingMarker.archivePath)) {
+    params.log?.info?.(
+      `matrix: reusing existing pre-migration backup snapshot: ${existingMarker.archivePath}`,
+    );
+    return {
+      created: false,
+      archivePath: existingMarker.archivePath,
+      markerPath,
+    };
+  }
+  if (existingMarker?.archivePath && !fs.existsSync(existingMarker.archivePath)) {
+    params.log?.warn?.(
+      `matrix: previous migration snapshot is missing (${existingMarker.archivePath}); creating a replacement backup before continuing`,
+    );
+  }
+
+  const snapshot = await createBackupArchive({
+    output: (() => {
+      const outputDir = params.outputDir ?? resolveMatrixMigrationSnapshotOutputDir(env);
+      fs.mkdirSync(outputDir, { recursive: true });
+      return outputDir;
+    })(),
+    includeWorkspace: false,
+  });
+
+  const marker: MatrixMigrationSnapshotMarker = {
+    version: 1,
+    createdAt: snapshot.createdAt,
+    archivePath: snapshot.archivePath,
+    trigger: params.trigger,
+    includeWorkspace: snapshot.includeWorkspace,
+  };
+  await writeJsonFileAtomically(markerPath, marker);
+  params.log?.info?.(`matrix: created pre-migration backup snapshot: ${snapshot.archivePath}`);
+  return {
+    created: true,
+    archivePath: snapshot.archivePath,
+    markerPath,
+  };
+}

package/src/migration-snapshot.ts

@@ -0,0 +1,53 @@
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { detectLegacyMatrixCrypto } from "./legacy-crypto.js";
+import { detectLegacyMatrixState } from "./legacy-state.js";
+import {
+  maybeCreateMatrixMigrationSnapshot,
+  resolveMatrixMigrationSnapshotMarkerPath,
+  resolveMatrixMigrationSnapshotOutputDir,
+} 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: AutoBotConfig;
+  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: AutoBotConfig;
+  env?: NodeJS.ProcessEnv;
+}): boolean {
+  return resolveMatrixMigrationStatus(params).pending;
+}
+
+export function hasActionableMatrixMigration(params: {
+  cfg: AutoBotConfig;
+  env?: NodeJS.ProcessEnv;
+}): boolean {
+  return resolveMatrixMigrationStatus(params).actionable;
+}
+
+export {
+  maybeCreateMatrixMigrationSnapshot,
+  resolveMatrixMigrationSnapshotMarkerPath,
+  resolveMatrixMigrationSnapshotOutputDir,
+};