@beignet/cli 0.0.31 → 0.0.33

package/src/outbox.ts

@@ -3,6 +3,10 @@ import path from "node:path";
 import type {
   DrainOutboxOptions,
   DrainOutboxResult,
+  OutboxAdminPort,
+  OutboxMessage,
+  OutboxMessageKind,
+  OutboxMessageStatus,
   OutboxRegistry,
 } from "@beignet/core/outbox";
 import { createJiti } from "jiti";
@@ -17,6 +21,61 @@ export type RunOutboxDrainOptions = {
   batchSize?: number;
 };
 
+/**
+ * Options for listing outbox messages.
+ */
+export type RunOutboxListOptions = {
+  cwd?: string;
+  modulePath?: string;
+  status?: OutboxMessageStatus;
+  kind?: OutboxMessageKind;
+  name?: string;
+  limit?: number;
+};
+
+/**
+ * Options for showing one outbox message.
+ */
+export type RunOutboxShowOptions = {
+  cwd?: string;
+  modulePath?: string;
+  id: string;
+};
+
+/**
+ * Options for requeueing one dead-lettered outbox message.
+ */
+export type RunOutboxRequeueOptions = {
+  cwd?: string;
+  modulePath?: string;
+  id: string;
+  availableAt?: Date;
+  resetAttempts?: boolean;
+};
+
+/**
+ * Options for purging dead-lettered outbox messages.
+ */
+export type RunOutboxPurgeOptions = {
+  cwd?: string;
+  modulePath?: string;
+  before?: Date;
+  all?: boolean;
+  limit?: number;
+  dryRun?: boolean;
+};
+
+/**
+ * Options for pruning delivered outbox messages.
+ */
+export type RunOutboxPruneOptions = {
+  cwd?: string;
+  modulePath?: string;
+  before: Date;
+  limit?: number;
+  dryRun?: boolean;
+};
+
 /**
  * Result returned by `beignet outbox drain`.
  */
@@ -28,6 +87,53 @@ export type RunOutboxDrainResult = {
   durationMs: number;
 };
 
+/**
+ * Result returned by `beignet outbox list`.
+ */
+export type RunOutboxListResult = {
+  schemaVersion: 1;
+  cwd: string;
+  modulePath: string;
+  messages: readonly OutboxMessage[];
+  count: number;
+  durationMs: number;
+};
+
+/**
+ * Result returned by `beignet outbox show`.
+ */
+export type RunOutboxShowResult = {
+  schemaVersion: 1;
+  cwd: string;
+  modulePath: string;
+  message: OutboxMessage;
+  durationMs: number;
+};
+
+/**
+ * Result returned by `beignet outbox requeue`.
+ */
+export type RunOutboxRequeueResult = {
+  schemaVersion: 1;
+  cwd: string;
+  modulePath: string;
+  message: OutboxMessage;
+  durationMs: number;
+};
+
+/**
+ * Result returned by destructive outbox admin commands.
+ */
+export type RunOutboxDeleteResult = {
+  schemaVersion: 1;
+  cwd: string;
+  modulePath: string;
+  dryRun: boolean;
+  matched: number;
+  deleted: number;
+  durationMs: number;
+};
+
 type OutboxDrainLogger = {
   error(message: string, meta?: Record<string, unknown>): unknown;
 };
@@ -47,6 +153,7 @@ type OutboxDrainInstrumentation = {
 
 type OutboxDrainPorts = {
   outbox: DrainOutboxOptions["outbox"];
+  outboxAdmin?: OutboxAdminPort;
   eventBus?: DrainOutboxOptions["eventBus"];
   jobs?: DrainOutboxOptions["jobs"];
   logger?: OutboxDrainLogger;
@@ -65,13 +172,24 @@ type OutboxDrainContextArgs = {
   batchSize?: number;
 };
 
+type OutboxAdminOperation = "list" | "show" | "requeue" | "purge" | "prune";
+
+type OutboxAdminContextArgs = {
+  operation: OutboxAdminOperation;
+};
+
 type OutboxModule = {
   outboxRegistry?: unknown;
   createOutboxDrainContext?: (args: OutboxDrainContextArgs) => unknown;
+  createOutboxAdminContext?: (args: OutboxAdminContextArgs) => unknown;
   stopOutboxDrainContext?: (
     ctx: OutboxDrainContext,
     args: OutboxDrainContextArgs,
   ) => unknown;
+  stopOutboxAdminContext?: (
+    ctx: OutboxDrainContext,
+    args: OutboxAdminContextArgs,
+  ) => unknown;
 };
 
 /**
@@ -138,6 +256,190 @@ export async function runOutboxDrain(
   }
 }
 
+/**
+ * List outbox messages through the app's outbox admin port.
+ */
+export async function runOutboxList(
+  options: RunOutboxListOptions = {},
+): Promise<RunOutboxListResult> {
+  return withOutboxAdminContext(options, "list", async ({ admin, base }) => {
+    const query = {
+      status: options.status,
+      kind: options.kind,
+      name: options.name,
+    };
+    const messages = await admin.listMessages({
+      ...query,
+      limit: options.limit,
+    });
+    const count = await admin.countMessages(query);
+
+    return {
+      ...base,
+      messages,
+      count,
+    };
+  });
+}
+
+/**
+ * Show one outbox message through the app's outbox admin port.
+ */
+export async function runOutboxShow(
+  options: RunOutboxShowOptions,
+): Promise<RunOutboxShowResult> {
+  return withOutboxAdminContext(options, "show", async ({ admin, base }) => {
+    const message = await admin.getMessage(options.id);
+    if (!message) {
+      throw new Error(`Outbox message "${options.id}" does not exist.`);
+    }
+
+    return {
+      ...base,
+      message,
+    };
+  });
+}
+
+/**
+ * Requeue one dead-lettered outbox message.
+ */
+export async function runOutboxRequeue(
+  options: RunOutboxRequeueOptions,
+): Promise<RunOutboxRequeueResult> {
+  return withOutboxAdminContext(options, "requeue", async ({ admin, base }) => {
+    const message = await admin.requeueMessage({
+      id: options.id,
+      availableAt: options.availableAt,
+      resetAttempts: options.resetAttempts,
+    });
+
+    return {
+      ...base,
+      message,
+    };
+  });
+}
+
+/**
+ * Purge dead-lettered outbox messages.
+ */
+export async function runOutboxPurge(
+  options: RunOutboxPurgeOptions = {},
+): Promise<RunOutboxDeleteResult> {
+  if (!options.before && !options.all) {
+    throw new Error(
+      "Pass --before <date> to purge old dead-lettered messages, or pass --all to purge every dead-lettered message.",
+    );
+  }
+
+  return withOutboxAdminContext(options, "purge", async ({ admin, base }) => {
+    const query = {
+      status: "deadLettered" as const,
+      updatedBefore: options.before,
+    };
+    const matched = await admin.countMessages(query);
+    const result = options.dryRun
+      ? { deleted: dryRunDeleteCount(matched, options.limit) }
+      : await admin.purgeDeadLettered({
+          before: options.before,
+          limit: options.limit,
+        });
+
+    return {
+      ...base,
+      dryRun: Boolean(options.dryRun),
+      matched,
+      deleted: result.deleted,
+    };
+  });
+}
+
+/**
+ * Prune delivered outbox messages.
+ */
+export async function runOutboxPrune(
+  options: RunOutboxPruneOptions,
+): Promise<RunOutboxDeleteResult> {
+  return withOutboxAdminContext(options, "prune", async ({ admin, base }) => {
+    const query = {
+      status: "delivered" as const,
+      deliveredBefore: options.before,
+    };
+    const matched = await admin.countMessages(query);
+    const result = options.dryRun
+      ? { deleted: dryRunDeleteCount(matched, options.limit) }
+      : await admin.pruneDelivered({
+          before: options.before,
+          limit: options.limit,
+        });
+
+    return {
+      ...base,
+      dryRun: Boolean(options.dryRun),
+      matched,
+      deleted: result.deleted,
+    };
+  });
+}
+
+async function withOutboxAdminContext<T extends object>(
+  options: { cwd?: string; modulePath?: string },
+  operation: OutboxAdminOperation,
+  run: (args: {
+    admin: OutboxAdminPort;
+    base: {
+      schemaVersion: 1;
+      cwd: string;
+      modulePath: string;
+    };
+  }) => Promise<T>,
+): Promise<T & { durationMs: number }> {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const config = await loadBeignetConfig(cwd);
+  const modulePath = normalizePath(options.modulePath ?? config.paths.outbox);
+  const startedAt = performance.now();
+  const outboxModule = await loadOutboxModule(cwd, modulePath);
+  const contextArgs = { operation };
+  const rawContext = outboxModule.createOutboxAdminContext
+    ? await outboxModule.createOutboxAdminContext(contextArgs)
+    : await createFallbackOutboxAdminContext(outboxModule);
+  const ctx = assertOutboxAdminContext(rawContext, modulePath);
+  const admin = resolveOutboxAdminPort(ctx, modulePath);
+
+  try {
+    const result = await run({
+      admin,
+      base: {
+        schemaVersion: 1,
+        cwd,
+        modulePath,
+      },
+    });
+    return {
+      ...result,
+      durationMs: Math.round(performance.now() - startedAt),
+    };
+  } finally {
+    if (outboxModule.stopOutboxAdminContext) {
+      await outboxModule.stopOutboxAdminContext(ctx, contextArgs);
+    } else {
+      await outboxModule.stopOutboxDrainContext?.(ctx, {
+        registry: maybeOutboxRegistry(outboxModule.outboxRegistry),
+      });
+    }
+  }
+}
+
+async function createFallbackOutboxAdminContext(
+  outboxModule: OutboxModule,
+): Promise<unknown> {
+  if (!outboxModule.createOutboxDrainContext) return undefined;
+  return outboxModule.createOutboxDrainContext({
+    registry: maybeOutboxRegistry(outboxModule.outboxRegistry),
+  });
+}
+
 async function loadOutboxModule(
   cwd: string,
   modulePath: string,
@@ -197,6 +499,19 @@ function assertOutboxDrainContext(
   return ctx as OutboxDrainContext;
 }
 
+function assertOutboxAdminContext(
+  ctx: unknown,
+  modulePath: string,
+): OutboxDrainContext {
+  if (!isRecord(ctx) || !isRecord(ctx.ports)) {
+    throw new Error(
+      `${modulePath} must export createOutboxAdminContext or createOutboxDrainContext that returns an app context with ports.outboxAdmin.`,
+    );
+  }
+
+  return ctx as OutboxDrainContext;
+}
+
 function isOutboxPort(value: unknown): value is DrainOutboxOptions["outbox"] {
   return (
     isRecord(value) &&
@@ -207,6 +522,48 @@ function isOutboxPort(value: unknown): value is DrainOutboxOptions["outbox"] {
   );
 }
 
+function isOutboxAdminPort(value: unknown): value is OutboxAdminPort {
+  return (
+    isRecord(value) &&
+    typeof value.listMessages === "function" &&
+    typeof value.countMessages === "function" &&
+    typeof value.getMessage === "function" &&
+    typeof value.requeueMessage === "function" &&
+    typeof value.purgeDeadLettered === "function" &&
+    typeof value.pruneDelivered === "function"
+  );
+}
+
+function resolveOutboxAdminPort(
+  ctx: OutboxDrainContext,
+  modulePath: string,
+): OutboxAdminPort {
+  if (isOutboxAdminPort(ctx.ports.outboxAdmin)) return ctx.ports.outboxAdmin;
+  if (isOutboxAdminPort(ctx.ports.outbox)) return ctx.ports.outbox;
+
+  throw new Error(
+    `${modulePath} createOutboxAdminContext must return ports.outboxAdmin, or ports.outbox must implement OutboxAdminPort.`,
+  );
+}
+
+function maybeOutboxRegistry(registry: unknown): OutboxRegistry {
+  if (
+    isRecord(registry) &&
+    registry.events instanceof Map &&
+    registry.jobs instanceof Map
+  ) {
+    return {
+      events: registry.events,
+      jobs: registry.jobs,
+    } as unknown as OutboxRegistry;
+  }
+
+  return {
+    events: new Map(),
+    jobs: new Map(),
+  };
+}
+
 async function recordOutboxDrain(
   ctx: OutboxDrainContext,
   result: DrainOutboxResult,
@@ -235,6 +592,12 @@ function assertPositiveInteger(name: string, value: number): void {
   }
 }
 
+function dryRunDeleteCount(matched: number, limit: number | undefined): number {
+  if (limit === undefined) return matched;
+  assertPositiveInteger("limit", limit);
+  return Math.min(matched, limit);
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }