@beignet/cli 0.0.44 → 0.0.46

package/src/outbox.ts

@@ -1,4 +1,4 @@
-import { readFile, stat } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import type { ErrorReporterPort } from "@beignet/core/error-reporting";
 import type {
@@ -16,6 +16,8 @@ import {
   flushOperationalErrorReporter,
   reportOperationalFailure,
 } from "./operational-error-reporting.js";
+import { runWithOperationalCleanup } from "./operational-lifecycle.js";
+import { resolveAppOperationalModulePath } from "./operational-path.js";
 
 /**
  * Options for running one bounded outbox drain pass.
@@ -126,10 +128,19 @@ export type RunOutboxRequeueResult = {
   durationMs: number;
 };
 
-/**
- * Result returned by destructive outbox admin commands.
- */
-export type RunOutboxDeleteResult = {
+/** Result returned by `beignet outbox purge`. */
+export type RunOutboxPurgeResult = {
+  schemaVersion: 1;
+  cwd: string;
+  modulePath: string;
+  dryRun: boolean;
+  matched: number;
+  deleted: number;
+  durationMs: number;
+};
+
+/** Result returned by `beignet outbox prune`. */
+export type RunOutboxPruneResult = {
   schemaVersion: 1;
   cwd: string;
   modulePath: string;
@@ -222,115 +233,122 @@ export async function runOutboxDrain(
     : undefined;
   const ctx = assertOutboxDrainContext(rawContext, modulePath);
 
-  try {
-    // Loaded lazily so CLI commands that never touch the app runtime, such as
-    // `beignet lint`, work without a built @beignet/core.
-    const { drainOutbox } = await import("@beignet/core/outbox");
-    const result = await drainOutbox({
-      outbox: ctx.ports.outbox,
-      registry,
-      eventBus: ctx.ports.eventBus,
-      jobs: ctx.ports.jobs,
-      batchSize,
-      instrumentation: ctx.ports.instrumentation ?? ctx.ports.devtools,
-      instrumentationContext: {
-        requestId: ctx.requestId,
-        traceId: ctx.traceId,
-      },
-      onError(error, message) {
-        ctx.ports.logger?.error("Outbox delivery failed", {
-          error,
-          outboxMessageId: message.id,
-          kind: message.kind,
-          name: message.name,
-          attempts: message.attempts,
-        });
-      },
-      onDeadLetter(error, message) {
-        return reportOperationalFailure({
-          ctx,
-          error,
-          reportOptions: {
-            level: "error",
-            mechanism: "beignet.outbox.cli",
-            handled: false,
-            tags: {
-              "beignet.kind": "outbox",
-              "beignet.outbox.kind": message.kind,
-              "beignet.outbox.name": message.name,
-              "beignet.outbox.outcome": "deadLettered",
-            },
-            contexts: {
-              outbox: {
-                messageId: message.id,
-                kind: message.kind,
-                name: message.name,
-                attempts: message.attempts,
-                maxAttempts: message.maxAttempts,
-                outcome: "deadLettered",
+  return runWithOperationalCleanup({
+    operation: "Outbox drain",
+    cleanupLabel: "stopOutboxDrainContext",
+    run: async () => {
+      try {
+        // Loaded lazily so CLI commands that never touch the app runtime, such
+        // as `beignet lint`, work without a built @beignet/core.
+        const { drainOutbox } = await import("@beignet/core/outbox");
+        const result = await drainOutbox({
+          outbox: ctx.ports.outbox,
+          registry,
+          eventBus: ctx.ports.eventBus,
+          jobs: ctx.ports.jobs,
+          batchSize,
+          instrumentation: ctx.ports.instrumentation ?? ctx.ports.devtools,
+          instrumentationContext: {
+            requestId: ctx.requestId,
+            traceId: ctx.traceId,
+          },
+          onError(error, message) {
+            ctx.ports.logger?.error("Outbox delivery failed", {
+              error,
+              outboxMessageId: message.id,
+              kind: message.kind,
+              name: message.name,
+              attempts: message.attempts,
+            });
+          },
+          onDeadLetter(error, message) {
+            return reportOperationalFailure({
+              ctx,
+              error,
+              reportOptions: {
+                level: "error",
+                mechanism: "beignet.outbox.cli",
+                handled: false,
+                tags: {
+                  "beignet.kind": "outbox",
+                  "beignet.outbox.kind": message.kind,
+                  "beignet.outbox.name": message.name,
+                  "beignet.outbox.outcome": "deadLettered",
+                },
+                contexts: {
+                  outbox: {
+                    messageId: message.id,
+                    kind: message.kind,
+                    name: message.name,
+                    attempts: message.attempts,
+                    maxAttempts: message.maxAttempts,
+                    outcome: "deadLettered",
+                  },
+                },
               },
-            },
+            });
+          },
+          onSettlementError(settlementError, message) {
+            return reportOperationalFailure({
+              ctx,
+              error: settlementError,
+              reportOptions: {
+                level: "error",
+                mechanism: "beignet.outbox.cli",
+                handled: false,
+                tags: {
+                  "beignet.kind": "outbox",
+                  "beignet.outbox.kind": message.kind,
+                  "beignet.outbox.name": message.name,
+                  "beignet.outbox.outcome": "settlementFailed",
+                },
+                contexts: {
+                  outbox: {
+                    messageId: message.id,
+                    kind: message.kind,
+                    name: message.name,
+                    attempts: message.attempts,
+                    maxAttempts: message.maxAttempts,
+                    outcome: "settlementFailed",
+                  },
+                },
+              },
+            });
           },
         });
-      },
-      onSettlementError(settlementError, message) {
-        return reportOperationalFailure({
+
+        await recordOutboxDrain(ctx, result);
+
+        return {
+          schemaVersion: 1,
+          cwd,
+          modulePath,
+          result,
+          durationMs: Math.round(performance.now() - startedAt),
+        };
+      } catch (error) {
+        await reportOperationalFailure({
           ctx,
-          error: settlementError,
+          error,
           reportOptions: {
             level: "error",
             mechanism: "beignet.outbox.cli",
             handled: false,
             tags: {
               "beignet.kind": "outbox",
-              "beignet.outbox.kind": message.kind,
-              "beignet.outbox.name": message.name,
-              "beignet.outbox.outcome": "settlementFailed",
-            },
-            contexts: {
-              outbox: {
-                messageId: message.id,
-                kind: message.kind,
-                name: message.name,
-                attempts: message.attempts,
-                maxAttempts: message.maxAttempts,
-                outcome: "settlementFailed",
-              },
+              "beignet.outbox.outcome": "drainFailed",
             },
+            contexts: { outbox: { outcome: "drainFailed" } },
           },
         });
-      },
-    });
-
-    await recordOutboxDrain(ctx, result);
-
-    return {
-      schemaVersion: 1,
-      cwd,
-      modulePath,
-      result,
-      durationMs: Math.round(performance.now() - startedAt),
-    };
-  } catch (error) {
-    await reportOperationalFailure({
-      ctx,
-      error,
-      reportOptions: {
-        level: "error",
-        mechanism: "beignet.outbox.cli",
-        handled: false,
-        tags: {
-          "beignet.kind": "outbox",
-          "beignet.outbox.outcome": "drainFailed",
-        },
-        contexts: { outbox: { outcome: "drainFailed" } },
-      },
-    });
-    throw error;
-  } finally {
-    await flushOperationalErrorReporter(ctx);
-    await outboxModule.stopOutboxDrainContext?.(ctx, contextArgs);
-  }
+        throw error;
+      }
+    },
+    cleanup: async () => {
+      await flushOperationalErrorReporter(ctx);
+      await outboxModule.stopOutboxDrainContext?.(ctx, contextArgs);
+    },
+  });
 }
 
 /**
@@ -403,7 +421,7 @@ export async function runOutboxRequeue(
  */
 export async function runOutboxPurge(
   options: RunOutboxPurgeOptions = {},
-): Promise<RunOutboxDeleteResult> {
+): Promise<RunOutboxPurgeResult> {
   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.",
@@ -437,7 +455,7 @@ export async function runOutboxPurge(
  */
 export async function runOutboxPrune(
   options: RunOutboxPruneOptions,
-): Promise<RunOutboxDeleteResult> {
+): Promise<RunOutboxPruneResult> {
   return withOutboxAdminContext(options, "prune", async ({ admin, base }) => {
     const query = {
       status: "delivered" as const,
@@ -482,30 +500,37 @@ async function withOutboxAdminContext<T extends object>(
     ? 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),
+  return runWithOperationalCleanup({
+    operation: `Outbox ${operation}`,
+    cleanupLabel: outboxModule.stopOutboxAdminContext
+      ? "stopOutboxAdminContext"
+      : "stopOutboxDrainContext",
+    run: async () => {
+      const admin = resolveOutboxAdminPort(ctx, modulePath);
+      const result = await run({
+        admin,
+        base: {
+          schemaVersion: 1,
+          cwd,
+          modulePath,
+        },
       });
-    }
-  }
+      return {
+        ...result,
+        durationMs: Math.round(performance.now() - startedAt),
+      };
+    },
+    cleanup: async () => {
+      if (outboxModule.stopOutboxAdminContext) {
+        await outboxModule.stopOutboxAdminContext(ctx, contextArgs);
+      } else {
+        await outboxModule.stopOutboxDrainContext?.(ctx, {
+          registry: maybeOutboxRegistry(outboxModule.outboxRegistry),
+        });
+      }
+    },
+  });
 }
 
 async function createFallbackOutboxAdminContext(
@@ -521,10 +546,11 @@ async function loadOutboxModule(
   cwd: string,
   modulePath: string,
 ): Promise<OutboxModule> {
-  const absolutePath = path.join(cwd, modulePath);
+  let absolutePath: string;
   try {
-    await stat(absolutePath);
-  } catch {
+    absolutePath = await resolveAppOperationalModulePath(cwd, modulePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
     throw new Error(
       `Could not find app outbox registry at ${modulePath}. Create server/outbox.ts or configure paths.outbox in beignet.config.ts.`,
     );

package/src/schedule.ts

@@ -1,4 +1,4 @@
-import { readFile, stat } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import type { ErrorReporterPort } from "@beignet/core/error-reporting";
 import type { ProviderInstrumentationPort } from "@beignet/core/providers";
@@ -13,6 +13,8 @@ import {
   flushOperationalErrorReporter,
   reportOperationalFailure,
 } from "./operational-error-reporting.js";
+import { runWithOperationalCleanup } from "./operational-lifecycle.js";
+import { resolveAppOperationalModulePath } from "./operational-path.js";
 
 /**
  * Options for running one app-owned schedule.
@@ -21,7 +23,8 @@ export type RunAppScheduleOptions = {
   name: string;
   cwd?: string;
   modulePath?: string;
-  payload?: string | Record<string, unknown>;
+  /** Pre-parsed payload validated by the registered schedule schema. */
+  payload?: unknown;
   id?: string;
   attempt?: number;
   scheduledAt?: string;
@@ -106,91 +109,97 @@ export async function runAppSchedule(
     : {};
   const scheduleContext = toScheduleContext(ctx);
 
-  try {
-    // Loaded lazily so CLI commands that never touch the app runtime, such as
-    // `beignet lint`, work without a built @beignet/core.
-    const { createInlineScheduleRunner } = await import(
-      "@beignet/core/schedules"
-    );
-    const runner = createInlineScheduleRunner<unknown>({
-      ctx,
-      instrumentation: scheduleContext.ports,
-      instrumentationContext: {
-        requestId: scheduleContext.requestId,
-        traceId: scheduleContext.traceId,
-      },
-      onError({ error }) {
-        scheduleContext.ports?.logger?.error("Schedule failed", {
-          error,
-          scheduleName: schedule.name,
-        });
-      },
-      onHookError({ error, hook }) {
-        scheduleContext.ports?.logger?.warn?.(
-          "Schedule lifecycle hook failed",
-          {
+  return runWithOperationalCleanup({
+    operation: `Schedule "${schedule.name}"`,
+    cleanupLabel: "stopScheduleContext",
+    run: async () => {
+      // Loaded lazily so CLI commands that never touch the app runtime, such as
+      // `beignet lint`, work without a built @beignet/core.
+      const { createInlineScheduleRunner } = await import(
+        "@beignet/core/schedules"
+      );
+      const runner = createInlineScheduleRunner<unknown>({
+        ctx,
+        instrumentation: scheduleContext.ports,
+        instrumentationContext: {
+          requestId: scheduleContext.requestId,
+          traceId: scheduleContext.traceId,
+        },
+        onError({ error }) {
+          scheduleContext.ports?.logger?.error("Schedule failed", {
             error,
-            hook,
             scheduleName: schedule.name,
-          },
-        );
-      },
-    });
-
-    try {
-      await runner.run(schedule, runOptions);
-    } catch (error) {
-      await reportOperationalFailure({
-        ctx: scheduleContext,
-        error,
-        reportOptions: {
-          level: "error",
-          mechanism: "beignet.schedule.cli",
-          handled: false,
-          tags: {
-            "beignet.kind": "schedule",
-            "beignet.schedule": schedule.name,
-          },
-          contexts: {
-            schedule: {
-              name: schedule.name,
-              source: runOptions.source ?? "beignet-cli",
-              attempt: runOptions.attempt ?? null,
+          });
+        },
+        onHookError({ error, hook }) {
+          scheduleContext.ports?.logger?.warn?.(
+            "Schedule lifecycle hook failed",
+            {
+              error,
+              hook,
+              scheduleName: schedule.name,
             },
-          },
+          );
         },
       });
-      throw error;
-    }
 
-    return {
-      schemaVersion: 1,
-      name: schedule.name,
-      cwd,
-      modulePath,
-      run: {
-        id: runOptions.id,
-        attempt: runOptions.attempt,
-        scheduledAt: stringifyDateInput(runOptions.scheduledAt),
-        triggeredAt: stringifyDateInput(runOptions.triggeredAt),
-        source: runOptions.source ?? "beignet-cli",
-      },
-      durationMs: Math.round(performance.now() - startedAt),
-    };
-  } finally {
-    await flushOperationalErrorReporter(scheduleContext);
-    await scheduleModule.stopScheduleContext?.(ctx, contextArgs);
-  }
+      try {
+        await runner.run(schedule, runOptions);
+      } catch (error) {
+        await reportOperationalFailure({
+          ctx: scheduleContext,
+          error,
+          reportOptions: {
+            level: "error",
+            mechanism: "beignet.schedule.cli",
+            handled: false,
+            tags: {
+              "beignet.kind": "schedule",
+              "beignet.schedule": schedule.name,
+            },
+            contexts: {
+              schedule: {
+                name: schedule.name,
+                source: runOptions.source ?? "beignet-cli",
+                attempt: runOptions.attempt ?? null,
+              },
+            },
+          },
+        });
+        throw error;
+      }
+
+      return {
+        schemaVersion: 1,
+        name: schedule.name,
+        cwd,
+        modulePath,
+        run: {
+          id: runOptions.id,
+          attempt: runOptions.attempt,
+          scheduledAt: stringifyDateInput(runOptions.scheduledAt),
+          triggeredAt: stringifyDateInput(runOptions.triggeredAt),
+          source: runOptions.source ?? "beignet-cli",
+        },
+        durationMs: Math.round(performance.now() - startedAt),
+      };
+    },
+    cleanup: async () => {
+      await flushOperationalErrorReporter(scheduleContext);
+      await scheduleModule.stopScheduleContext?.(ctx, contextArgs);
+    },
+  });
 }
 
 async function loadScheduleModule(
   cwd: string,
   modulePath: string,
 ): Promise<ScheduleModule> {
-  const absolutePath = path.join(cwd, modulePath);
+  let absolutePath: string;
   try {
-    await stat(absolutePath);
-  } catch {
+    absolutePath = await resolveAppOperationalModulePath(cwd, modulePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
     throw new Error(
       `Could not find app schedule registry at ${modulePath}. Create server/schedules.ts or configure paths.schedules in beignet.config.ts.`,
     );
@@ -213,7 +222,7 @@ function buildScheduleRunOptions(
   };
 
   if (options.payload !== undefined) {
-    runOptions.payload = parseSchedulePayloadFlag(options.payload);
+    runOptions.payload = options.payload;
   }
   if (options.id !== undefined) runOptions.id = options.id;
   if (options.attempt !== undefined) runOptions.attempt = options.attempt;
@@ -223,20 +232,6 @@ function buildScheduleRunOptions(
   return runOptions;
 }
 
-function parseSchedulePayloadFlag(
-  input: NonNullable<RunAppScheduleOptions["payload"]>,
-): unknown {
-  if (typeof input !== "string") return input;
-
-  try {
-    return JSON.parse(input) as unknown;
-  } catch (error) {
-    throw new Error(
-      `Invalid --payload JSON: ${error instanceof Error ? error.message : String(error)}`,
-    );
-  }
-}
-
 function findSchedule(
   schedules: readonly unknown[] | undefined,
   name: string,