@beignet/cli 0.0.32 → 0.0.33

package/src/index.ts

@@ -162,6 +162,60 @@ type OutboxDrainFlags = {
   batchSize?: number;
 };
 
+type OutboxMessageStatus = "pending" | "claimed" | "delivered" | "deadLettered";
+
+type OutboxMessageKind = "event" | "job";
+
+const outboxMessageStatusChoices = [
+  "pending",
+  "claimed",
+  "delivered",
+  "deadLettered",
+] as const satisfies readonly OutboxMessageStatus[];
+
+const outboxMessageKindChoices = [
+  "event",
+  "job",
+] as const satisfies readonly OutboxMessageKind[];
+
+type OutboxListFlags = {
+  json?: boolean;
+  module?: string;
+  status?: OutboxMessageStatus;
+  kind?: OutboxMessageKind;
+  name?: string;
+  limit?: number;
+};
+
+type OutboxShowFlags = {
+  json?: boolean;
+  module?: string;
+};
+
+type OutboxRequeueFlags = {
+  json?: boolean;
+  module?: string;
+  availableAt?: Date;
+  resetAttempts?: boolean;
+};
+
+type OutboxPurgeFlags = {
+  json?: boolean;
+  module?: string;
+  before?: Date;
+  all?: boolean;
+  limit?: number;
+  dryRun?: boolean;
+};
+
+type OutboxPruneFlags = {
+  json?: boolean;
+  module?: string;
+  before?: Date;
+  limit?: number;
+  dryRun?: boolean;
+};
+
 type ScheduleRunFlags = {
   json?: boolean;
   module?: string;
@@ -215,6 +269,13 @@ const parsePositiveInteger = (input: string): number => {
   }
   return value;
 };
+const parseDate = (input: string): Date => {
+  const value = new Date(input);
+  if (Number.isNaN(value.getTime())) {
+    throw new Error("Expected a valid date.");
+  }
+  return value;
+};
 
 const forceFlag = {
   kind: "boolean",
@@ -230,6 +291,13 @@ const dryRunFlag = {
   brief: "Preview generated changes without writing files.",
 } as const;
 
+const operationDryRunFlag = {
+  kind: "boolean",
+  optional: true,
+  withNegated: false,
+  brief: "Report matching records without deleting them.",
+} as const;
+
 const jsonFlag = {
   kind: "boolean",
   optional: true,
@@ -245,6 +313,14 @@ const parsedStringFlag = (brief: string) =>
     brief,
   }) as const;
 
+const parsedDateFlag = (brief: string) =>
+  ({
+    kind: "parsed",
+    parse: parseDate,
+    optional: true,
+    brief,
+  }) as const;
+
 const cwdFlag = parsedStringFlag(
   "App directory to inspect. Defaults to the current working directory.",
 );
@@ -336,6 +412,95 @@ const outboxDrainFlagParameters = {
   },
 } satisfies FlagParametersForType<OutboxDrainFlags, CliContext>;
 
+const outboxListFlagParameters = {
+  json: jsonFlag,
+  module: parsedStringFlag(
+    "Outbox registry module. Defaults to server/outbox.ts.",
+  ),
+  status: {
+    kind: "enum",
+    values: outboxMessageStatusChoices,
+    optional: true,
+    brief: "Filter by outbox message status.",
+  },
+  kind: {
+    kind: "enum",
+    values: outboxMessageKindChoices,
+    optional: true,
+    brief: "Filter by outbox message kind.",
+  },
+  name: parsedStringFlag("Filter by event or job name."),
+  limit: {
+    kind: "parsed",
+    parse: parsePositiveInteger,
+    optional: true,
+    brief: "Maximum messages to return. Defaults to 50.",
+  },
+} satisfies FlagParametersForType<OutboxListFlags, CliContext>;
+
+const outboxShowFlagParameters = {
+  json: jsonFlag,
+  module: parsedStringFlag(
+    "Outbox registry module. Defaults to server/outbox.ts.",
+  ),
+} satisfies FlagParametersForType<OutboxShowFlags, CliContext>;
+
+const outboxRequeueFlagParameters = {
+  json: jsonFlag,
+  module: parsedStringFlag(
+    "Outbox registry module. Defaults to server/outbox.ts.",
+  ),
+  availableAt: parsedDateFlag(
+    "Earliest timestamp the requeued message may be claimed. Defaults to now.",
+  ),
+  resetAttempts: {
+    kind: "boolean",
+    optional: true,
+    withNegated: false,
+    brief: "Reset attempts to zero before requeueing.",
+  },
+} satisfies FlagParametersForType<OutboxRequeueFlags, CliContext>;
+
+const outboxPurgeFlagParameters = {
+  json: jsonFlag,
+  module: parsedStringFlag(
+    "Outbox registry module. Defaults to server/outbox.ts.",
+  ),
+  before: parsedDateFlag(
+    "Only purge dead-lettered messages last updated before this timestamp.",
+  ),
+  all: {
+    kind: "boolean",
+    optional: true,
+    withNegated: false,
+    brief: "Purge every dead-lettered message when --before is omitted.",
+  },
+  limit: {
+    kind: "parsed",
+    parse: parsePositiveInteger,
+    optional: true,
+    brief: "Maximum messages to purge.",
+  },
+  dryRun: operationDryRunFlag,
+} satisfies FlagParametersForType<OutboxPurgeFlags, CliContext>;
+
+const outboxPruneFlagParameters = {
+  json: jsonFlag,
+  module: parsedStringFlag(
+    "Outbox registry module. Defaults to server/outbox.ts.",
+  ),
+  before: parsedDateFlag(
+    "Prune delivered messages delivered before this timestamp.",
+  ),
+  limit: {
+    kind: "parsed",
+    parse: parsePositiveInteger,
+    optional: true,
+    brief: "Maximum messages to prune.",
+  },
+  dryRun: operationDryRunFlag,
+} satisfies FlagParametersForType<OutboxPruneFlags, CliContext>;
+
 const scheduleRunFlagParameters = {
   json: jsonFlag,
   module: parsedStringFlag(
@@ -365,6 +530,17 @@ const namePositional = {
   ],
 } as const;
 
+const idPositional = {
+  kind: "tuple",
+  parameters: [
+    {
+      parse: parseString,
+      placeholder: "id",
+      brief: "Outbox message ID.",
+    },
+  ],
+} as const;
+
 const providerPresetPositional = {
   kind: "tuple",
   parameters: [
@@ -1048,12 +1224,178 @@ const outboxDrainCommand = buildCommand<OutboxDrainFlags, [], CliContext>({
   },
 });
 
+const outboxListCommand = buildCommand<OutboxListFlags, [], CliContext>({
+  docs: {
+    brief: "List outbox messages for operational inspection.",
+  },
+  parameters: {
+    flags: outboxListFlagParameters,
+  },
+  loader: async () => {
+    const { runOutboxList } = await import("./outbox.js");
+
+    return async function runList(this: CliContext, flags: OutboxListFlags) {
+      const result = await runOutboxList({
+        modulePath: flags.module,
+        status: flags.status,
+        kind: flags.kind,
+        name: flags.name,
+        limit: flags.limit,
+      });
+
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : outboxListNextSteps(result),
+      );
+    };
+  },
+});
+
+const outboxShowCommand = buildCommand<OutboxShowFlags, [string], CliContext>({
+  docs: {
+    brief: "Show one outbox message.",
+  },
+  parameters: {
+    flags: outboxShowFlagParameters,
+    positional: idPositional,
+  },
+  loader: async () => {
+    const { runOutboxShow } = await import("./outbox.js");
+
+    return async function runShow(
+      this: CliContext,
+      flags: OutboxShowFlags,
+      id: string,
+    ) {
+      const result = await runOutboxShow({
+        modulePath: flags.module,
+        id,
+      });
+
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : outboxShowNextSteps(result),
+      );
+    };
+  },
+});
+
+const outboxRequeueCommand = buildCommand<
+  OutboxRequeueFlags,
+  [string],
+  CliContext
+>({
+  docs: {
+    brief: "Return one dead-lettered outbox message to pending state.",
+  },
+  parameters: {
+    flags: outboxRequeueFlagParameters,
+    positional: idPositional,
+  },
+  loader: async () => {
+    const { runOutboxRequeue } = await import("./outbox.js");
+
+    return async function runRequeue(
+      this: CliContext,
+      flags: OutboxRequeueFlags,
+      id: string,
+    ) {
+      const result = await runOutboxRequeue({
+        modulePath: flags.module,
+        id,
+        availableAt: flags.availableAt,
+        resetAttempts: Boolean(flags.resetAttempts),
+      });
+
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : outboxRequeueNextSteps(result),
+      );
+    };
+  },
+});
+
+const outboxPurgeCommand = buildCommand<OutboxPurgeFlags, [], CliContext>({
+  docs: {
+    brief: "Delete dead-lettered outbox messages.",
+  },
+  parameters: {
+    flags: outboxPurgeFlagParameters,
+  },
+  loader: async () => {
+    const { runOutboxPurge } = await import("./outbox.js");
+
+    return async function runPurge(this: CliContext, flags: OutboxPurgeFlags) {
+      const result = await runOutboxPurge({
+        modulePath: flags.module,
+        before: flags.before,
+        all: Boolean(flags.all),
+        limit: flags.limit,
+        dryRun: Boolean(flags.dryRun),
+      });
+
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : outboxDeleteNextSteps(
+              "Purged dead-lettered outbox messages",
+              result,
+            ),
+      );
+    };
+  },
+});
+
+const outboxPruneCommand = buildCommand<OutboxPruneFlags, [], CliContext>({
+  docs: {
+    brief: "Delete delivered outbox messages older than a retention cutoff.",
+  },
+  parameters: {
+    flags: outboxPruneFlagParameters,
+  },
+  loader: async () => {
+    const { runOutboxPrune } = await import("./outbox.js");
+
+    return async function runPrune(this: CliContext, flags: OutboxPruneFlags) {
+      if (!flags.before) {
+        throw new Error("Pass --before <date> to prune delivered messages.");
+      }
+
+      const result = await runOutboxPrune({
+        modulePath: flags.module,
+        before: flags.before,
+        limit: flags.limit,
+        dryRun: Boolean(flags.dryRun),
+      });
+
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : outboxDeleteNextSteps("Pruned delivered outbox messages", result),
+      );
+    };
+  },
+});
+
 const outboxRoutes = buildRouteMap({
   docs: {
     brief: "Run Beignet outbox operations.",
   },
   routes: {
     drain: outboxDrainCommand,
+    list: outboxListCommand,
+    show: outboxShowCommand,
+    requeue: outboxRequeueCommand,
+    purge: outboxPurgeCommand,
+    prune: outboxPruneCommand,
   },
 });
 
@@ -1758,6 +2100,37 @@ type OutboxDrainNextStepsResult = {
   };
 };
 
+type OutboxAdminMessage = {
+  id: string;
+  kind: string;
+  name: string;
+  status: string;
+  attempts: number;
+  maxAttempts: number;
+  availableAt: Date | string;
+  deliveredAt: Date | string | null;
+  updatedAt: Date | string;
+  lastError: { name?: string; message: string } | null;
+};
+
+type OutboxListNextStepsResult = {
+  durationMs: number;
+  messages: readonly OutboxAdminMessage[];
+  count: number;
+};
+
+type OutboxMessageNextStepsResult = {
+  durationMs: number;
+  message: OutboxAdminMessage;
+};
+
+type OutboxDeleteNextStepsResult = {
+  durationMs: number;
+  dryRun: boolean;
+  matched: number;
+  deleted: number;
+};
+
 type ScheduleRunNextStepsResult = {
   name: string;
   durationMs: number;
@@ -1794,6 +2167,69 @@ Result:
   deadLettered: ${result.result.deadLettered}`;
 }
 
+function formatOutboxDate(value: Date | string | null | undefined): string {
+  if (!value) return "none";
+  return value instanceof Date ? value.toISOString() : value;
+}
+
+function outboxMessageLine(message: OutboxAdminMessage): string {
+  return `${message.id}  ${message.status}  ${message.kind}  ${message.name}  attempts ${message.attempts}/${message.maxAttempts}  updated ${formatOutboxDate(message.updatedAt)}`;
+}
+
+function outboxListNextSteps(result: OutboxListNextStepsResult): string {
+  const messages =
+    result.messages.length === 0
+      ? "  none"
+      : result.messages
+          .map((message) => `  ${outboxMessageLine(message)}`)
+          .join("\n");
+
+  return `Listed ${result.messages.length} of ${result.count} matching outbox messages in ${result.durationMs}ms
+
+Messages:
+${messages}`;
+}
+
+function outboxShowNextSteps(result: OutboxMessageNextStepsResult): string {
+  const message = result.message;
+  const error = message.lastError
+    ? `${message.lastError.name ?? "Error"}: ${message.lastError.message}`
+    : "none";
+
+  return `Outbox message ${message.id} (${message.status}) in ${result.durationMs}ms
+
+Message:
+  kind: ${message.kind}
+  name: ${message.name}
+  attempts: ${message.attempts}/${message.maxAttempts}
+  availableAt: ${formatOutboxDate(message.availableAt)}
+  deliveredAt: ${formatOutboxDate(message.deliveredAt)}
+  updatedAt: ${formatOutboxDate(message.updatedAt)}
+  lastError: ${error}`;
+}
+
+function outboxRequeueNextSteps(result: OutboxMessageNextStepsResult): string {
+  return `Requeued outbox message ${result.message.id} in ${result.durationMs}ms
+
+Message:
+  status: ${result.message.status}
+  attempts: ${result.message.attempts}/${result.message.maxAttempts}
+  availableAt: ${formatOutboxDate(result.message.availableAt)}`;
+}
+
+function outboxDeleteNextSteps(
+  label: string,
+  result: OutboxDeleteNextStepsResult,
+): string {
+  const action = result.dryRun ? "Would delete" : "Deleted";
+
+  return `${label} in ${result.durationMs}ms
+
+Result:
+  matched: ${result.matched}
+  ${action}: ${result.deleted}`;
+}
+
 function scheduleRunNextSteps(result: ScheduleRunNextStepsResult): string {
   return `Ran schedule ${result.name} in ${result.durationMs}ms
 
@@ -2103,7 +2539,7 @@ function makeOutboxNextSteps(result: MakeNextStepsResult): string {
 function makeListenerNextSteps(result: MakeNextStepsResult): string {
   return makeNextSteps(result, "listener", [
     "Replace the starter handler with the event reaction.",
-    "Register the listener collection from infrastructure startup.",
+    "Register the listener collection from server provider wiring.",
   ]);
 }