@kodelyth/matrix 2026.5.42 → 2026.6.2

package/src/migration-config.ts

@@ -1,243 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import { DEFAULT_ACCOUNT_ID, normalizeAccountId } from "klaw/plugin-sdk/account-id";
-import type { KlawConfig } from "klaw/plugin-sdk/config-contracts";
-import { resolveStateDir } from "klaw/plugin-sdk/state-paths";
-import { normalizeOptionalString } from "klaw/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: KlawConfig,
-  accountId: string,
-): Record<string, unknown> | null {
-  return findMatrixAccountEntry(cfg, accountId);
-}
-
-function resolveMatrixFlatStoreSelectionNote(
-  cfg: KlawConfig,
-  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: KlawConfig;
-  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: KlawConfig;
-  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: KlawConfig;
-  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 "klaw 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 "klaw 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 "klaw doctor --fix" after cached credentials are available.',
-    };
-  }
-
-  return {
-    ...target,
-    selectionNote: resolveMatrixFlatStoreSelectionNote(params.cfg, accountId),
-  };
-}

package/src/migration-snapshot-backup.ts

@@ -1,116 +0,0 @@
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { writeJsonFileAtomically } from "klaw/plugin-sdk/json-store";
-import { resolveRequiredHomeDir, resolveStateDir } from "klaw/plugin-sdk/state-paths";
-
-const MATRIX_MIGRATION_SNAPSHOT_DIRNAME = "klaw-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("klaw/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("klaw/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

@@ -1,53 +0,0 @@
-import type { KlawConfig } from "klaw/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: KlawConfig;
-  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: KlawConfig;
-  env?: NodeJS.ProcessEnv;
-}): boolean {
-  return resolveMatrixMigrationStatus(params).pending;
-}
-
-export function hasActionableMatrixMigration(params: {
-  cfg: KlawConfig;
-  env?: NodeJS.ProcessEnv;
-}): boolean {
-  return resolveMatrixMigrationStatus(params).actionable;
-}
-
-export {
-  maybeCreateMatrixMigrationSnapshot,
-  resolveMatrixMigrationSnapshotMarkerPath,
-  resolveMatrixMigrationSnapshotOutputDir,
-};