feat(scripts): repair legacy-migrated series with wrong-frame BYDAY

packages/scripts/src/cli.test.ts

@@ -9,6 +9,9 @@ const mockRunPurgeUser = mock((): Promise<void> => Promise.resolve());
 const mockRunRepairRecurringSeries = mock(
   (): Promise<void> => Promise.resolve(),
 );
+const mockRunRepairLegacySeriesWeekday = mock(
+  (): Promise<void> => Promise.resolve(),
+);
 
 mock.module("@scripts/cli.validator", () => ({
   CliValidator: mock().mockImplementation(() => ({
@@ -28,6 +31,10 @@ mock.module("@scripts/commands/repair-recurring-series", () => ({
   __esModule: true,
   runRepairRecurringSeries: mock(() => mockRunRepairRecurringSeries()),
 }));
+mock.module("@scripts/commands/repair-legacy-series-weekday", () => ({
+  __esModule: true,
+  runRepairLegacySeriesWeekday: mock(() => mockRunRepairLegacySeriesWeekday()),
+}));
 
 const { default: CompassCLI } = requireActual(
   "@scripts/cli",
@@ -62,6 +69,14 @@ describe("CompassCLI", () => {
     expect(mockRunRepairRecurringSeries).toHaveBeenCalled();
   });
 
+  it("runs repair-legacy-series-weekday command", async () => {
+    const cli = new CompassCLI(["node", "cli", "repair-legacy-series-weekday"]);
+
+    await cli.run();
+
+    expect(mockRunRepairLegacySeriesWeekday).toHaveBeenCalled();
+  });
+
   it("calls exitHelpfully for unsupported command", async () => {
     const exitSpy = spyOn(process, "exit").mockImplementation(mock() as never);
 

packages/scripts/src/cli.ts

@@ -3,6 +3,7 @@ import { runManageFailedJobs } from "@scripts/commands/manage-failed-jobs";
 import { runPurgeCorruptSyncEvents } from "@scripts/commands/purge-corrupt-sync-events";
 import { runPurgeUser } from "@scripts/commands/purge-user";
 import { runRefreshConnectionStates } from "@scripts/commands/refresh-connection-states";
+import { runRepairLegacySeriesWeekday } from "@scripts/commands/repair-legacy-series-weekday";
 import { runRepairRecurringSeries } from "@scripts/commands/repair-recurring-series";
 import { Command } from "commander";
 
@@ -35,6 +36,9 @@ export default class CompassCLI {
       case cmd === "repair-recurring-series":
         await runRepairRecurringSeries();
         break;
+      case cmd === "repair-legacy-series-weekday":
+        await runRepairLegacySeriesWeekday();
+        break;
       default:
         this.validator.exitHelpfully(`${cmd as string} is not a supported cmd`);
     }
@@ -77,6 +81,14 @@ export default class CompassCLI {
         "Re-derive every provider connection's stored state from live evidence (--apply to write)",
       );
 
+    program
+      .command("repair-legacy-series-weekday")
+      .helpOption(false)
+      .allowUnknownOption(true)
+      .description(
+        "Fix legacy-migrated weekly series with a wrong-frame RRULE BYDAY (--apply to write)",
+      );
+
     program
       .command("manage-failed-jobs")
       .helpOption(false)

packages/scripts/src/commands/repair-legacy-series-weekday.ts

@@ -0,0 +1,63 @@
+import { repairLegacySeriesWeekday } from "@scripts/commands/repair-legacy-series-weekday/repair";
+import { loadCompassConfig } from "@core/config/compass.config";
+import { Logger } from "@core/logger/winston.logger";
+import { SyncMongoService } from "@sync/storage/sync-mongo.service";
+
+const logger = Logger("scripts.commands.repair-legacy-series-weekday");
+
+function syncMongoUri(): string {
+  const fromEnv = process.env["SYNC_MONGO_URI"]?.trim();
+  if (fromEnv) return fromEnv;
+  const uri = loadCompassConfig().sync?.mongoUri?.trim();
+  if (!uri) {
+    throw new Error(
+      "Set SYNC_MONGO_URI or add sync.mongoUri to compass.yaml before repair-legacy-series-weekday",
+    );
+  }
+  return uri;
+}
+
+/**
+ * One-off repair for weekly recurring series migrated from the legacy DB
+ * during the 2026-07-29 Sync cutover whose RRULE BYDAY was captured in the
+ * wrong timezone frame relative to schedule.timeZone — causing a phantom,
+ * wrong-weekday occurrence to render every week alongside the correct one
+ * (which comes from a separately-imported exception holding the real,
+ * Google-sourced instant). Rewrites BYDAY to the weekday the series'
+ * exceptions actually converge on, and reprojects. See
+ * legacy-utc-frame-series-duplicates memory / the migration PR description
+ * for the full root-cause writeup. Default dry-run; `--apply` writes.
+ *
+ *   bun run cli repair-legacy-series-weekday [--apply]
+ */
+export async function runRepairLegacySeriesWeekday(): Promise<void> {
+  const apply = process.argv.slice(3).includes("--apply");
+  const syncMongo = new SyncMongoService();
+  try {
+    await syncMongo.connect({
+      uri: syncMongoUri(),
+      enforceLeastPrivilege: false,
+      forbiddenDatabaseName: "prod_calendar",
+    });
+    const report = await repairLegacySeriesWeekday(
+      syncMongo.db,
+      syncMongo.client,
+      { dryRun: !apply },
+    );
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    logger.info(
+      `repair-legacy-series-weekday dryRun=${report.dryRun} scanned=${report.scanned} ` +
+        `candidatesConsidered=${report.candidatesConsidered} fixed=${report.fixed} skipped=${report.skipped}`,
+    );
+    await syncMongo.disconnect();
+    process.exit(0);
+  } catch (error) {
+    logger.error(error);
+    try {
+      await syncMongo.disconnect();
+    } catch {
+      // ignore
+    }
+    process.exit(1);
+  }
+}