@beignet/cli 0.0.50 → 0.0.51

package/src/index.ts

@@ -8,6 +8,7 @@ import {
   type CommandContext,
   type FlagParametersForType,
   proposeCompletions,
+  type RouteMap,
   run,
   type StricliDynamicCommandContext,
   type StricliProcess,
@@ -180,6 +181,7 @@ type OutboxDrainFlags = {
   json?: boolean;
   module?: string;
   batchSize?: number;
+  concurrency?: number;
   cwd?: string;
 };
 
@@ -486,7 +488,13 @@ const outboxDrainFlagParameters = {
     kind: "parsed",
     parse: parsePositiveInteger,
     optional: true,
-    brief: "Maximum messages to claim in one drain pass.",
+    brief: "Maximum eligible messages to handle in one drain pass.",
+  },
+  concurrency: {
+    kind: "parsed",
+    parse: parsePositiveInteger,
+    optional: true,
+    brief: "Maximum concurrent deliveries; values above one are unordered.",
   },
   cwd: cwdFlag,
 } satisfies FlagParametersForType<OutboxDrainFlags, CliContext>;
@@ -1597,6 +1605,7 @@ const outboxDrainCommand = buildCommand<OutboxDrainFlags, [], CliContext>({
         cwd: flags.cwd,
         modulePath: flags.module,
         batchSize: flags.batchSize,
+        concurrency: flags.concurrency,
       });
 
       writeOutput(
@@ -1605,6 +1614,9 @@ const outboxDrainCommand = buildCommand<OutboxDrainFlags, [], CliContext>({
           ? JSON.stringify(result, null, 2)
           : outboxDrainNextSteps(result),
       );
+      if (result.result.settlementFailed > 0 || result.result.leaseLost > 0) {
+        this.process.exitCode = 1;
+      }
     };
   },
 });
@@ -2448,6 +2460,27 @@ Run npm create beignet@latest (or bun create beignet) to scaffold a new app.`,
   },
 });
 
+const completionProposalCommandPath = ["completion", "propose"] as const;
+
+function commandPathsFromRouteMap(
+  routeMap: RouteMap<CliContext>,
+  prefix: readonly string[] = [],
+): string[][] {
+  return routeMap.getAllEntries().flatMap((entry) => {
+    const path = [...prefix, entry.name["convert-camel-to-kebab"]];
+    if ("getAllEntries" in entry.target) {
+      return commandPathsFromRouteMap(entry.target, path);
+    }
+    return [path];
+  });
+}
+
+/** Every canonical CLI command path, derived from runtime routing definitions. */
+export const cliCommandPaths: readonly (readonly string[])[] = [
+  ...commandPathsFromRouteMap(rootRoutes),
+  completionProposalCommandPath,
+].sort((left, right) => left.join(" ").localeCompare(right.join(" ")));
+
 const cli = buildApplication(rootRoutes, {
   name: "beignet",
   versionInfo: {
@@ -2541,6 +2574,9 @@ type OutboxDrainNextStepsResult = {
     delivered: number;
     retried: number;
     deadLettered: number;
+    abandonedDeadLettered: number;
+    settlementFailed: number;
+    leaseLost: number;
   };
 };
 
@@ -2608,7 +2644,10 @@ Result:
   claimed: ${result.result.claimed}
   delivered: ${result.result.delivered}
   retried: ${result.result.retried}
-  deadLettered: ${result.result.deadLettered}`;
+  deadLettered: ${result.result.deadLettered}
+  abandonedDeadLettered: ${result.result.abandonedDeadLettered}
+  settlementFailed: ${result.result.settlementFailed}
+  leaseLost: ${result.result.leaseLost}`;
 }
 
 function formatOutboxDate(value: Date | string | null | undefined): string {
@@ -3053,7 +3092,10 @@ export async function main(
   // Shell completion scripts call `beignet completion propose <words...>`.
   // Handle it before stricli parses the inputs: the trailing words are a
   // partial command line, not flags for this CLI.
-  if (inputs[0] === "completion" && inputs[1] === "propose") {
+  if (
+    inputs[0] === completionProposalCommandPath[0] &&
+    inputs[1] === completionProposalCommandPath[1]
+  ) {
     await writeCompletionProposals(inputs.slice(2), context);
     return;
   }

package/src/inspect.ts

@@ -1576,36 +1576,57 @@ function parseRouteExports(
   config: ResolvedBeignetConfig,
 ): RouteExport[] {
   const exports: RouteExport[] = [];
-  const imports = parseNamedImports(source, config);
-  const exportRegex =
-    /export const\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s*=\s*([^;\n]+)/g;
-  const apiRouteExportRegex =
-    /export const\s*\{([^}]+)\}\s*=\s*createApiRoute\s*\(/g;
+  const sourceFile = ts.createSourceFile(
+    handlerFile,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const imports = parseRouteNamedImports(sourceFile, config, handlerFile);
 
-  for (const match of source.matchAll(apiRouteExportRegex)) {
-    for (const member of match[1].split(",")) {
-      const parts = member.split(":");
-      const method = (parts[1] ?? parts[0])?.trim();
-      if (!method || !isHttpMethod(method)) continue;
+  for (const statement of sourceFile.statements) {
+    if (
+      !ts.isVariableStatement(statement) ||
+      !statement.modifiers?.some(
+        (modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword,
+      )
+    ) {
+      continue;
+    }
 
-      exports.push({
-        method,
-        handlerFile,
-        contractRef: routePath,
-        catchAllPrefix: catchAllRoutePrefix(routePath),
-        source: "next-route",
-      });
+    for (const declaration of statement.declarationList.declarations) {
+      if (
+        !declaration.initializer ||
+        !ts.isObjectBindingPattern(declaration.name) ||
+        !isNamedRouteFactoryCall(declaration.initializer, "createApiRoute")
+      ) {
+        continue;
+      }
+
+      for (const element of declaration.name.elements) {
+        if (!ts.isIdentifier(element.name)) continue;
+        const method = element.name.text;
+        if (!isHttpMethod(method)) continue;
+        exports.push({
+          method,
+          handlerFile,
+          contractRef: routePath,
+          catchAllPrefix: catchAllRoutePrefix(routePath),
+          source: "next-route",
+        });
+      }
     }
   }
 
-  for (const match of source.matchAll(exportRegex)) {
-    const method = match[1] as HttpMethod;
-    const expression = match[2];
-    const contractMatch =
-      /server\.route\(\s*([A-Za-z_$][\w$]*)\s*\)\.handle/.exec(expression);
+  for (const { exportName, declaration } of exportedVariableDeclarations(
+    sourceFile,
+  )) {
+    if (!isHttpMethod(exportName) || !declaration.initializer) continue;
+    const method = exportName;
+    const localName = routeLocalContractIdentifier(declaration.initializer);
 
-    if (contractMatch) {
-      const localName = contractMatch[1];
+    if (localName) {
       const imported = imports.get(localName);
       exports.push({
         method,
@@ -1617,7 +1638,7 @@ function parseRouteExports(
       continue;
     }
 
-    if (/server\.api\b/.test(expression)) {
+    if (isServerApiExpression(declaration.initializer)) {
       exports.push({
         method,
         handlerFile,
@@ -1631,6 +1652,98 @@ function parseRouteExports(
   return exports;
 }
 
+function parseRouteNamedImports(
+  sourceFile: ts.SourceFile,
+  config: ResolvedBeignetConfig,
+  handlerFile: string,
+): Map<string, { importedName: string; contractFile?: string }> {
+  const imports = new Map<
+    string,
+    { importedName: string; contractFile?: string }
+  >();
+
+  for (const statement of sourceFile.statements) {
+    if (
+      !ts.isImportDeclaration(statement) ||
+      !ts.isStringLiteral(statement.moduleSpecifier) ||
+      statement.importClause?.isTypeOnly ||
+      !statement.importClause?.namedBindings ||
+      !ts.isNamedImports(statement.importClause.namedBindings)
+    ) {
+      continue;
+    }
+
+    const contractFile = contractFileFromImport(
+      statement.moduleSpecifier.text,
+      config,
+      handlerFile,
+    );
+    for (const element of statement.importClause.namedBindings.elements) {
+      if (element.isTypeOnly) continue;
+      imports.set(element.name.text, {
+        importedName: element.propertyName?.text ?? element.name.text,
+        contractFile,
+      });
+    }
+  }
+
+  return imports;
+}
+
+function isNamedRouteFactoryCall(
+  expression: ts.Expression,
+  name: string,
+): boolean {
+  const unwrapped = unwrapContractExpression(expression);
+  if (!ts.isCallExpression(unwrapped)) return false;
+  const callee = unwrapContractExpression(unwrapped.expression);
+  return ts.isIdentifier(callee) && callee.text === name;
+}
+
+function routeLocalContractIdentifier(
+  expression: ts.Expression,
+): string | undefined {
+  const handleCall = unwrapContractExpression(expression);
+  if (!ts.isCallExpression(handleCall)) return undefined;
+  const handleAccess = unwrapContractExpression(handleCall.expression);
+  if (
+    !ts.isPropertyAccessExpression(handleAccess) ||
+    handleAccess.name.text !== "handle"
+  ) {
+    return undefined;
+  }
+
+  const routeCall = unwrapContractExpression(handleAccess.expression);
+  if (!ts.isCallExpression(routeCall)) return undefined;
+  const routeAccess = unwrapContractExpression(routeCall.expression);
+  if (
+    !ts.isPropertyAccessExpression(routeAccess) ||
+    routeAccess.name.text !== "route" ||
+    !ts.isIdentifier(routeAccess.expression) ||
+    routeAccess.expression.text !== "server"
+  ) {
+    return undefined;
+  }
+
+  const contract = routeCall.arguments[0];
+  const unwrappedContract = contract
+    ? unwrapContractExpression(contract)
+    : undefined;
+  return unwrappedContract && ts.isIdentifier(unwrappedContract)
+    ? unwrappedContract.text
+    : undefined;
+}
+
+function isServerApiExpression(expression: ts.Expression): boolean {
+  const unwrapped = unwrapContractExpression(expression);
+  return (
+    ts.isPropertyAccessExpression(unwrapped) &&
+    ts.isIdentifier(unwrapped.expression) &&
+    unwrapped.expression.text === "server" &&
+    unwrapped.name.text === "api"
+  );
+}
+
 function catchAllRoutePrefix(routePath: string): string | undefined {
   const segments = routePath.split("/").filter(Boolean);
   const catchAllIndex = segments.findIndex((segment) => segment.endsWith("*"));
@@ -1762,6 +1875,29 @@ function contractFileFromImport(
   config: ResolvedBeignetConfig,
   importerFile?: string,
 ): string | undefined {
+  const resolveCandidate = (candidate: string) => {
+    const extension = path.extname(candidate).toLowerCase();
+    if (!extension) return `${candidate}.ts`;
+
+    let sourceExtension: string | undefined;
+    switch (extension) {
+      case ".js":
+        sourceExtension = ".ts";
+        break;
+      case ".jsx":
+        sourceExtension = ".tsx";
+        break;
+      case ".mjs":
+        sourceExtension = ".mts";
+        break;
+      case ".cjs":
+        sourceExtension = ".cts";
+        break;
+    }
+    return sourceExtension
+      ? `${candidate.slice(0, -extension.length)}${sourceExtension}`
+      : candidate;
+  };
   const contractsPath = directoryPath(config.paths.contracts);
   const aliasPrefix = `@/${contractsPath}/`;
   const aliasExact = `@/${contractsPath}`;
@@ -1772,18 +1908,18 @@ function contractFileFromImport(
     return `${contractsPath}/index.ts`;
   }
   if (sourcePath.startsWith(aliasPrefix)) {
-    return `${sourcePath.slice("@/".length)}.ts`;
+    return resolveCandidate(sourcePath.slice("@/".length));
   }
 
   if (sourcePath.startsWith(relativePrefix)) {
-    return `${sourcePath}.ts`;
+    return resolveCandidate(sourcePath);
   }
 
   if (importerFile && sourcePath.startsWith(".")) {
     const resolved = normalizePath(
       path.join(path.dirname(importerFile), sourcePath),
     );
-    return `${resolved}.ts`;
+    return resolveCandidate(resolved);
   }
 
   return undefined;

package/src/make.ts

@@ -2225,7 +2225,6 @@ async function updateOutboxDrainProvider(
 \t\t\tdefer: after,
 \t\t\tcreateContext: () => createServiceContext(undefined),
 \t\t\tregistry: async () => (await import("${outboxModule}")).outboxRegistry,
-\t\t\tbatchSize: 100,
 \t\t});
 
 \t\treturn {
@@ -5921,7 +5920,6 @@ export const { GET, POST } = createOutboxDrainRoute({
 \tserver: getServer,
 \tregistry: outboxRegistry,
 \tsecret: env.CRON_SECRET,
-\tbatchSize: 100,
 });
 `;
 }

package/src/mcp.ts

@@ -285,6 +285,7 @@ const outboxRunInputSchema = z.discriminatedUnion("operation", [
   z.object({
     operation: z.literal("drain"),
     batchSize: z.number().int().positive().optional(),
+    concurrency: z.number().int().positive().optional(),
     module: operationalModuleSchema,
     timeoutMs: operationalTimeoutSchema,
   }),
@@ -349,17 +350,36 @@ function jsonResult(value: unknown): McpToolResult {
   };
 }
 
-function operationalJsonResult(value: unknown): McpToolResult {
+function operationalJsonResult(
+  value: unknown,
+  options: { isError?: boolean } = {},
+): McpToolResult {
   const formatted = JSON.stringify(value, null, 2);
   const text =
     Buffer.byteLength(formatted) <= defaultOperationalResultMaxBytes
       ? formatted
       : JSON.stringify(value);
   return {
+    ...(options.isError ? { isError: true } : {}),
     content: [{ type: "text", text }],
   };
 }
 
+function isUncertainOutboxDrainReport(value: unknown): boolean {
+  if (typeof value !== "object" || value === null || !("result" in value)) {
+    return false;
+  }
+  const result = value.result;
+  if (typeof result !== "object" || result === null) return false;
+  const settlementFailed =
+    "settlementFailed" in result ? result.settlementFailed : undefined;
+  const leaseLost = "leaseLost" in result ? result.leaseLost : undefined;
+  return (
+    (typeof settlementFailed === "number" && settlementFailed > 0) ||
+    (typeof leaseLost === "number" && leaseLost > 0)
+  );
+}
+
 function errorResult(error: unknown): McpToolResult {
   return {
     isError: true,
@@ -972,7 +992,7 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
     "outbox_run",
     {
       description:
-        "Run a state-changing outbox drain, requeue, purge, or prune operation and return exactly the matching versioned beignet outbox <operation> --json report. Purge and prune support dryRun. Runs in an isolated process with bounded structured output, cancellation, and a timeout.",
+        "Run a state-changing outbox drain, requeue, purge, or prune operation and return exactly the matching versioned beignet outbox <operation> --json report. Drain supports bounded unordered concurrency and returns an error-bearing report when settlement or lease state is uncertain. Purge and prune support dryRun. Runs in an isolated process with bounded structured output, cancellation, and a timeout.",
       inputSchema: outboxRunInputSchema,
       annotations: {
         readOnlyHint: false,
@@ -988,6 +1008,7 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
             ? {
                 command: "outbox:drain" as const,
                 batchSize: input.batchSize,
+                concurrency: input.concurrency,
                 modulePath: input.module,
               }
             : input.operation === "requeue"
@@ -1014,14 +1035,16 @@ export function buildBeignetMcpServer(options: McpServerOptions): McpServer {
                     dryRun: input.dryRun,
                     modulePath: input.module,
                   };
-        return operationalJsonResult(
-          await runIsolatedOperationalCommand({
-            cwd,
-            request,
-            signal: ctx.mcpReq.signal,
-            timeoutMs: input.timeoutMs ?? defaultOperationalCommandTimeoutMs,
-          }),
-        );
+        const result = await runIsolatedOperationalCommand({
+          cwd,
+          request,
+          signal: ctx.mcpReq.signal,
+          timeoutMs: input.timeoutMs ?? defaultOperationalCommandTimeoutMs,
+        });
+        return operationalJsonResult(result, {
+          isError:
+            input.operation === "drain" && isUncertainOutboxDrainReport(result),
+        });
       }),
   );
 

package/src/operational-process.ts

@@ -44,6 +44,7 @@ export type OperationalCommandRequest =
   | {
       command: "outbox:drain";
       batchSize?: number;
+      concurrency?: number;
       modulePath?: string;
     }
   | {

package/src/operational-runner.ts

@@ -47,6 +47,7 @@ async function runOperationalRequest(input: OperationalRunnerInput) {
       return runOutboxDrain({
         cwd,
         batchSize: request.batchSize,
+        concurrency: request.concurrency,
         modulePath: request.modulePath,
       });
     case "outbox:list":

package/src/outbox.ts

@@ -10,6 +10,7 @@ import type {
   OutboxMessageStatus,
   OutboxRegistry,
 } from "@beignet/core/outbox";
+import type { TracingPort } from "@beignet/core/tracing";
 import { createJiti } from "jiti";
 import { loadBeignetConfig, normalizePath } from "./config.js";
 import {
@@ -26,6 +27,7 @@ export type RunOutboxDrainOptions = {
   cwd?: string;
   modulePath?: string;
   batchSize?: number;
+  concurrency?: number;
 };
 
 /**
@@ -175,6 +177,7 @@ type OutboxDrainPorts = {
   logger?: OutboxDrainLogger;
   devtools?: OutboxDrainInstrumentation;
   instrumentation?: OutboxDrainInstrumentation;
+  tracing?: TracingPort;
   errorReporter?: ErrorReporterPort;
 };
 
@@ -187,6 +190,7 @@ type OutboxDrainContext = {
 type OutboxDrainContextArgs = {
   registry: OutboxRegistry;
   batchSize?: number;
+  concurrency?: number;
 };
 
 type OutboxAdminOperation = "list" | "show" | "requeue" | "purge" | "prune";
@@ -219,7 +223,11 @@ export async function runOutboxDrain(
   const config = await loadBeignetConfig(cwd);
   const modulePath = normalizePath(options.modulePath ?? config.paths.outbox);
   const batchSize = options.batchSize;
+  const concurrency = options.concurrency;
   if (batchSize !== undefined) assertPositiveInteger("batchSize", batchSize);
+  if (concurrency !== undefined) {
+    assertPositiveInteger("concurrency", concurrency);
+  }
 
   const startedAt = performance.now();
   const outboxModule = await loadOutboxModule(cwd, modulePath);
@@ -227,7 +235,7 @@ export async function runOutboxDrain(
     outboxModule.outboxRegistry,
     modulePath,
   );
-  const contextArgs = { registry, batchSize };
+  const contextArgs = { registry, batchSize, concurrency };
   const rawContext = outboxModule.createOutboxDrainContext
     ? await outboxModule.createOutboxDrainContext(contextArgs)
     : undefined;
@@ -247,7 +255,11 @@ export async function runOutboxDrain(
           eventBus: ctx.ports.eventBus,
           jobs: ctx.ports.jobs,
           batchSize,
-          instrumentation: ctx.ports.instrumentation ?? ctx.ports.devtools,
+          concurrency,
+          instrumentation: {
+            instrumentation: ctx.ports.instrumentation ?? ctx.ports.devtools,
+            tracing: ctx.ports.tracing,
+          },
           instrumentationContext: {
             requestId: ctx.requestId,
             traceId: ctx.traceId,
@@ -288,27 +300,65 @@ export async function runOutboxDrain(
               },
             });
           },
-          onSettlementError(settlementError, message) {
+          onLeaseError(failure) {
+            const outcome =
+              failure.state === "lost"
+                ? "leaseLost"
+                : failure.state === "recovered"
+                  ? "leaseRecovered"
+                  : "leaseDegraded";
             return reportOperationalFailure({
               ctx,
-              error: settlementError,
+              error: failure.error,
+              reportOptions: {
+                level: failure.state === "lost" ? "error" : "warning",
+                mechanism: "beignet.outbox.cli",
+                handled: failure.state !== "lost",
+                tags: {
+                  "beignet.kind": "outbox",
+                  "beignet.outbox.kind": failure.message.kind,
+                  "beignet.outbox.name": failure.message.name,
+                  "beignet.outbox.outcome": outcome,
+                },
+                contexts: {
+                  outbox: {
+                    messageId: failure.message.id,
+                    kind: failure.message.kind,
+                    name: failure.message.name,
+                    attempts: failure.message.attempts,
+                    maxAttempts: failure.message.maxAttempts,
+                    operation: failure.operation,
+                    state: failure.state,
+                    confirmedLost: failure.confirmedLost,
+                    outcome,
+                  },
+                },
+              },
+            });
+          },
+          onSettlementError(failure) {
+            return reportOperationalFailure({
+              ctx,
+              error: failure.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.kind": failure.message.kind,
+                  "beignet.outbox.name": failure.message.name,
                   "beignet.outbox.outcome": "settlementFailed",
                 },
                 contexts: {
                   outbox: {
-                    messageId: message.id,
-                    kind: message.kind,
-                    name: message.name,
-                    attempts: message.attempts,
-                    maxAttempts: message.maxAttempts,
+                    messageId: failure.message.id,
+                    kind: failure.message.kind,
+                    name: failure.message.name,
+                    attempts: failure.message.attempts,
+                    maxAttempts: failure.message.maxAttempts,
+                    operation: failure.operation,
+                    deliverySucceeded: failure.deliverySucceeded,
                     outcome: "settlementFailed",
                   },
                 },
@@ -620,6 +670,7 @@ function isOutboxPort(value: unknown): value is DrainOutboxOptions["outbox"] {
     isRecord(value) &&
     typeof value.enqueue === "function" &&
     typeof value.claimBatch === "function" &&
+    typeof value.renewClaim === "function" &&
     typeof value.markDelivered === "function" &&
     typeof value.markFailed === "function"
   );
@@ -677,7 +728,7 @@ async function recordOutboxDrain(
       watcher: "outbox",
       name: "outbox.drain",
       label: "Outbox drain",
-      summary: `${result.delivered} delivered, ${result.retried} retried, ${result.deadLettered} dead-lettered`,
+      summary: `${result.delivered} delivered, ${result.retried} retried, ${result.deadLettered} dead-lettered, ${result.settlementFailed} settlement-uncertain, ${result.leaseLost} lease-lost`,
       requestId: ctx.requestId,
       traceId: ctx.traceId,
       details: result,

package/src/templates/agents.ts

@@ -107,7 +107,9 @@ re-exports and \`db\` for \`generate\`, \`migrate\`, \`seed\`, or \`reset\`
 instead of falling back to a shell. Use the read-only \`db_status\` tool before
 deploying. Use \`task_run\`, \`schedule_run\`,
 \`outbox_inspect\`, and \`outbox_run\` for registered operational workflows
-and outbox recovery.
+and outbox recovery. Treat a drain with nonzero \`settlementFailed\` or
+\`leaseLost\` as an operational failure. Parallel delivery is opt-in and does
+not preserve message order.
 
 ## The framework already solves these
 
@@ -242,7 +244,10 @@ and reports the script without executing it; it does not simulate SQL or data
 changes. Use \`task_run\` and \`schedule_run\` for registered operational
 workflows, \`outbox_inspect\` for read-only \`list\` and \`show\`, and
 \`outbox_run\` for \`drain\`, \`requeue\`, \`purge\`, or \`prune\`; purge and
-prune support \`dryRun\`. Operational commands run in isolated process trees
+prune support \`dryRun\`. A drain with nonzero \`settlementFailed\` or
+\`leaseLost\` remains a complete JSON report but is an error result; inspect
+storage health and clock synchronization before retrying. Operational commands
+run in isolated process trees
 with bounded results, cancellation, and timeouts. Optional \`module\` overrides
 must remain inside the app root where the MCP server started. Cancellation and
 timeouts cannot roll back side effects that already completed. Inspect app