@beignet/cli 0.0.31 → 0.0.33

package/dist/index.js

@@ -2,7 +2,7 @@
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { buildApplication, buildCommand, buildRouteMap, proposeCompletions, run, text_en, } from "@stricli/core";
-import { completionShellChoices, databaseChoices, databaseStartCommand, integrationChoices, makeFeatureAddonChoices, makeFeatureRecipeChoices, packageManagerChoices, providerPresetChoices, templateChoices, } from "./choices.js";
+import { completionShellChoices, createIntegrationChoices, databaseChoices, databaseStartCommand, makeFeatureAddonChoices, makeFeatureRecipeChoices, packageManagerChoices, providerPresetChoices, splitCreateIntegrations, templateChoices, } from "./choices.js";
 import { getCliVersion } from "./version.js";
 const outputFormatChoices = [
     "human",
@@ -19,6 +19,16 @@ const databaseSchemaTableChoices = [
     "idempotency",
     "outbox",
 ];
+const outboxMessageStatusChoices = [
+    "pending",
+    "claimed",
+    "delivered",
+    "deadLettered",
+];
+const outboxMessageKindChoices = [
+    "event",
+    "job",
+];
 const parseString = (input) => input;
 const parseProviderPreset = (input) => {
     if (providerPresetChoices.includes(input)) {
@@ -33,6 +43,13 @@ const parsePositiveInteger = (input) => {
     }
     return value;
 };
+const parseDate = (input) => {
+    const value = new Date(input);
+    if (Number.isNaN(value.getTime())) {
+        throw new Error("Expected a valid date.");
+    }
+    return value;
+};
 const forceFlag = {
     kind: "boolean",
     optional: true,
@@ -45,6 +62,12 @@ const dryRunFlag = {
     withNegated: false,
     brief: "Preview generated changes without writing files.",
 };
+const operationDryRunFlag = {
+    kind: "boolean",
+    optional: true,
+    withNegated: false,
+    brief: "Report matching records without deleting them.",
+};
 const jsonFlag = {
     kind: "boolean",
     optional: true,
@@ -57,6 +80,12 @@ const parsedStringFlag = (brief) => ({
     optional: true,
     brief,
 });
+const parsedDateFlag = (brief) => ({
+    kind: "parsed",
+    parse: parseDate,
+    optional: true,
+    brief,
+});
 const cwdFlag = parsedStringFlag("App directory to inspect. Defaults to the current working directory.");
 const formatFlag = {
     kind: "enum",
@@ -91,22 +120,22 @@ const dbFlagParameters = {
     json: jsonFlag,
     dryRun: dryRunFlag,
 };
-const dbSchemaGenerateFlagParameters = {
+const dbSchemaSyncFlagParameters = {
     ...dbFlagParameters,
     dialect: {
         kind: "enum",
         values: databaseSchemaDialectChoices,
         optional: true,
-        brief: "Drizzle dialect to generate for. Inferred from server/providers.ts when omitted.",
+        brief: "Drizzle dialect to sync. Inferred from server/providers.ts when omitted.",
     },
     tables: {
         kind: "enum",
         values: databaseSchemaTableChoices,
         optional: true,
         variadic: ",",
-        brief: "Provider tables to generate as a comma-separated list. Defaults to audit,idempotency,outbox.",
+        brief: "Provider tables to sync as a comma-separated list. Defaults to audit,idempotency,outbox.",
     },
-    output: parsedStringFlag("Generated schema file. Defaults to infra/db/schema/beignet.ts."),
+    output: parsedStringFlag("Synced schema file. Defaults to infra/db/schema/beignet.ts."),
 };
 const taskRunFlagParameters = {
     json: jsonFlag,
@@ -124,6 +153,74 @@ const outboxDrainFlagParameters = {
         brief: "Maximum messages to claim in one drain pass.",
     },
 };
+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.",
+    },
+};
+const outboxShowFlagParameters = {
+    json: jsonFlag,
+    module: parsedStringFlag("Outbox registry module. Defaults to server/outbox.ts."),
+};
+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.",
+    },
+};
+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,
+};
+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,
+};
 const scheduleRunFlagParameters = {
     json: jsonFlag,
     module: parsedStringFlag("Schedule registry module. Defaults to server/schedules.ts."),
@@ -149,6 +246,16 @@ const namePositional = {
         },
     ],
 };
+const idPositional = {
+    kind: "tuple",
+    parameters: [
+        {
+            parse: parseString,
+            placeholder: "id",
+            brief: "Outbox message ID.",
+        },
+    ],
+};
 const providerPresetPositional = {
     kind: "tuple",
     parameters: [
@@ -182,7 +289,11 @@ and a shadcn UI shell. Pass --api for an API-only scaffold without the
 UI shell, and --db to choose the database.
 
 Available databases: ${databaseChoices.join(", ")}
-Available integrations: ${integrationChoices.join(", ")}
+Available integrations: ${createIntegrationChoices.join(", ")}
+
+--integrations accepts the starter template integrations plus the full
+beignet providers add preset catalog; presets are applied to the scaffold
+with the same machinery as beignet providers add.
 
 Running create on an interactive terminal without selection flags opens a
 prompt-based setup. Pass --yes or any selection flag to skip the prompts.`,
@@ -215,10 +326,10 @@ prompt-based setup. Pass --yes or any selection flag to skip the prompts.`,
             },
             integrations: {
                 kind: "enum",
-                values: integrationChoices,
+                values: createIntegrationChoices,
                 optional: true,
                 variadic: ",",
-                brief: "Add first-party integrations as a comma-separated list.",
+                brief: "Add first-party integrations or provider presets as a comma-separated list.",
             },
             yes: {
                 kind: "boolean",
@@ -271,7 +382,13 @@ prompt-based setup. Pass --yes or any selection flag to skip the prompts.`,
             }
             const api = selections.api ?? false;
             const database = selections.db ?? "sqlite";
-            const integrations = uniqueValues([...(selections.integrations ?? [])]);
+            const { integrations, presets } = splitCreateIntegrations(uniqueValues([...(selections.integrations ?? [])]));
+            let presetsNeedEnv = false;
+            if (presets.length > 0) {
+                const { assertCompatibleCreatePresets, providerPresetNeedsEnv } = await import("./provider-add.js");
+                assertCompatibleCreatePresets(presets, integrations);
+                presetsNeedEnv = presets.some(providerPresetNeedsEnv);
+            }
             const result = await createProject({
                 name: selections.directory,
                 template: flags.template,
@@ -282,9 +399,21 @@ prompt-based setup. Pass --yes or any selection flag to skip the prompts.`,
                 force: Boolean(flags.force),
                 dryRun: Boolean(flags.dryRun),
             });
+            if (!flags.dryRun && presets.length > 0) {
+                const { addProviderPreset } = await import("./provider-add.js");
+                for (const preset of presets) {
+                    await addProviderPreset({ name: preset, cwd: result.targetDir });
+                }
+            }
             writeOutput(this, flags.json
-                ? JSON.stringify(result, null, 2)
-                : nextSteps(result, { api, integrations, database }));
+                ? JSON.stringify({ ...result, providerPresets: presets }, null, 2)
+                : nextSteps(result, {
+                    api,
+                    integrations,
+                    database,
+                    presets,
+                    presetsNeedEnv,
+                }));
         };
     },
 });
@@ -367,6 +496,12 @@ const checkCommand = buildCommand({
                 withNegated: false,
                 brief: "Apply low-risk doctor fixes before checking.",
             },
+            preflight: {
+                kind: "boolean",
+                optional: true,
+                withNegated: false,
+                brief: "Append a beignet preflight step after doctor.",
+            },
             cwd: cwdFlag,
         },
     },
@@ -377,6 +512,7 @@ const checkCommand = buildCommand({
             const result = await checkApp({
                 cwd: flags.cwd,
                 fix: flags.fix,
+                preflight: flags.preflight,
                 color,
                 ...(flags.json
                     ? {}
@@ -393,6 +529,47 @@ const checkCommand = buildCommand({
         };
     },
 });
+const preflightCommand = buildCommand({
+    docs: {
+        brief: "Validate the deploy environment before shipping.",
+        fullDescription: "Runtime production gate, unlike the static doctor checks: reads the actual environment the process runs with, verifies every env var installed provider manifests mark as required, flags values still matching .env.example or common placeholders on secret-like keys, and validates the app env schema by importing lib/env.ts. Run it in the deploy pipeline where production configuration is present. Exits 1 on any error finding.",
+    },
+    parameters: {
+        flags: {
+            json: jsonFlag,
+            envFile: parsedStringFlag("Dotenv-style file merged under the environment (existing env keys win) for local rehearsal."),
+            envModule: parsedStringFlag("App env module validated by importing it. Defaults to lib/env.ts."),
+            connect: {
+                kind: "boolean",
+                optional: true,
+                withNegated: false,
+                brief: "Boot the app server and run every port's checkHealth(). Needs network and real credentials.",
+            },
+            serverModule: parsedStringFlag("Module exporting getServer, used by --connect. Defaults to server/index.ts."),
+            cwd: cwdFlag,
+        },
+    },
+    loader: async () => {
+        const { formatPreflight, runPreflight } = await import("./preflight.js");
+        const path = await import("node:path");
+        return async function runPreflightCommand(flags) {
+            const cwd = path.resolve(flags.cwd ?? process.cwd());
+            const result = await runPreflight({
+                cwd,
+                envFile: flags.envFile,
+                envModule: flags.envModule,
+                connect: flags.connect,
+                serverModule: flags.serverModule,
+            });
+            writeOutput(this, flags.json
+                ? JSON.stringify({ schemaVersion: 1, cwd, ...result }, null, 2)
+                : formatPreflight(result, cwd));
+            if (result.findings.some((finding) => finding.severity === "error")) {
+                this.process.exitCode = 1;
+            }
+        };
+    },
+});
 const lintCommand = buildCommand({
     docs: {
         brief: "Check Beignet dependency direction conventions.",
@@ -515,18 +692,18 @@ function databaseCommand(command) {
         },
     });
 }
-const dbSchemaGenerateCommand = buildCommand({
+const dbSchemaSyncCommand = buildCommand({
     docs: {
-        brief: "Generate provider-owned Drizzle schema exports.",
-        fullDescription: "Writes an app-owned schema file that re-exports Beignet provider tables, then updates the schema index. Run beignet db generate afterward to let the app's Drizzle Kit script create migrations.",
+        brief: "Sync app-owned re-exports of Beignet provider tables.",
+        fullDescription: "Idempotently brings the app-owned schema file that re-exports Beignet provider tables in sync with the installed providers, then updates the schema index. Run beignet db generate afterward to let the app's Drizzle Kit script create migrations.",
     },
     parameters: {
-        flags: dbSchemaGenerateFlagParameters,
+        flags: dbSchemaSyncFlagParameters,
     },
     loader: async () => {
-        const { generateDatabaseSchema } = await import("./db.js");
-        return async function runDbSchemaGenerate(flags) {
-            const result = await generateDatabaseSchema({
+        const { syncDatabaseSchema } = await import("./db.js");
+        return async function runDbSchemaSync(flags) {
+            const result = await syncDatabaseSchema({
                 dialect: flags.dialect,
                 tables: flags.tables,
                 output: flags.output,
@@ -534,16 +711,16 @@ const dbSchemaGenerateCommand = buildCommand({
             });
             writeOutput(this, flags.json
                 ? JSON.stringify(result, null, 2)
-                : databaseSchemaGenerateNextSteps(result));
+                : databaseSchemaSyncNextSteps(result));
         };
     },
 });
 const dbSchemaRoutes = buildRouteMap({
     docs: {
-        brief: "Generate Beignet database schema helpers.",
+        brief: "Sync app-owned Beignet provider schema exports.",
     },
     routes: {
-        generate: dbSchemaGenerateCommand,
+        sync: dbSchemaSyncCommand,
     },
 });
 const dbRoutes = buildRouteMap({
@@ -609,12 +786,132 @@ const outboxDrainCommand = buildCommand({
         };
     },
 });
+const outboxListCommand = buildCommand({
+    docs: {
+        brief: "List outbox messages for operational inspection.",
+    },
+    parameters: {
+        flags: outboxListFlagParameters,
+    },
+    loader: async () => {
+        const { runOutboxList } = await import("./outbox.js");
+        return async function runList(flags) {
+            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({
+    docs: {
+        brief: "Show one outbox message.",
+    },
+    parameters: {
+        flags: outboxShowFlagParameters,
+        positional: idPositional,
+    },
+    loader: async () => {
+        const { runOutboxShow } = await import("./outbox.js");
+        return async function runShow(flags, id) {
+            const result = await runOutboxShow({
+                modulePath: flags.module,
+                id,
+            });
+            writeOutput(this, flags.json
+                ? JSON.stringify(result, null, 2)
+                : outboxShowNextSteps(result));
+        };
+    },
+});
+const outboxRequeueCommand = buildCommand({
+    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(flags, id) {
+            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({
+    docs: {
+        brief: "Delete dead-lettered outbox messages.",
+    },
+    parameters: {
+        flags: outboxPurgeFlagParameters,
+    },
+    loader: async () => {
+        const { runOutboxPurge } = await import("./outbox.js");
+        return async function runPurge(flags) {
+            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({
+    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(flags) {
+            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,
     },
 });
 const scheduleRunCommand = buildCommand({
@@ -1012,6 +1309,7 @@ Run npm create beignet@latest (or bun create beignet) to scaffold a new app.`,
         make: makeRoutes,
         mcp: mcpCommand,
         outbox: outboxRoutes,
+        preflight: preflightCommand,
         providers: providerRoutes,
         routes: routesCommand,
         schedule: scheduleRoutes,
@@ -1070,6 +1368,57 @@ Result:
   retried: ${result.result.retried}
   deadLettered: ${result.result.deadLettered}`;
 }
+function formatOutboxDate(value) {
+    if (!value)
+        return "none";
+    return value instanceof Date ? value.toISOString() : value;
+}
+function outboxMessageLine(message) {
+    return `${message.id}  ${message.status}  ${message.kind}  ${message.name}  attempts ${message.attempts}/${message.maxAttempts}  updated ${formatOutboxDate(message.updatedAt)}`;
+}
+function outboxListNextSteps(result) {
+    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) {
+    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) {
+    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, result) {
+    const action = result.dryRun ? "Would delete" : "Deleted";
+    return `${label} in ${result.durationMs}ms
+
+Result:
+  matched: ${result.matched}
+  ${action}: ${result.deleted}`;
+}
 function scheduleRunNextSteps(result) {
     return `Ran schedule ${result.name} in ${result.durationMs}ms
 
@@ -1083,18 +1432,28 @@ Run:
 function nextSteps(result, options = {}) {
     if (result.dryRun) {
         const plannedFiles = result.files.map((file) => `  ${file}`).join("\n");
+        const plannedPresets = options.presets && options.presets.length > 0
+            ? `\n\nProvider presets applied after scaffold (skipped in dry run):\n${options.presets
+                .map((preset) => `  ${preset}`)
+                .join("\n")}`
+            : "";
         return `Would create ${result.name} at ${result.targetDir}
 
 Planned files:
-${plannedFiles}`;
+${plannedFiles}${plannedPresets}`;
     }
     const pm = result.packageManager;
     const run = pm === "npm" ? "npm run" : `${pm} run`;
     const cli = packageRunnerFromPackageManager(pm);
     const envRequiredIntegrations = options.integrations?.filter(isEnvRequiredProviderIntegration) ?? [];
-    const envStep = envRequiredIntegrations.length > 0
+    const envStep = envRequiredIntegrations.length > 0 || options.presetsNeedEnv
         ? "  Fill .env.local for selected provider integrations before starting the app.\n"
         : "";
+    const presetSection = options.presets && options.presets.length > 0
+        ? `\nProvider presets applied:\n${options.presets
+            .map((preset) => `  ${preset}`)
+            .join("\n")}\n  See docs/integrations.md for setup notes and follow-up steps.\n`
+        : "";
     const openStep = options.api
         ? "  open http://localhost:3000 for the API landing page"
         : "  open http://localhost:3000/sign-up";
@@ -1108,7 +1467,7 @@ ${plannedFiles}`;
 `
         : "";
     return `Created ${result.name} at ${result.targetDir}
-
+${presetSection}
 Next steps:
   cd ${result.targetDir}
   ${pm} install
@@ -1195,13 +1554,13 @@ function databaseCommandNextSteps(result) {
 Command:
   ${command}`;
 }
-function databaseSchemaGenerateNextSteps(result) {
+function databaseSchemaSyncNextSteps(result) {
     const { changedFiles, skippedFiles } = changedFileLines({
         createdFiles: result.createdFiles,
         updatedFiles: result.updatedFiles,
         skippedFiles: result.skippedFiles,
     });
-    const prefix = result.dryRun ? "Would generate" : "Generated";
+    const prefix = result.dryRun ? "Would sync" : "Synced";
     const tables = result.tables.join(", ");
     return `${prefix} Beignet ${result.dialect} database schema (${tables}) in ${result.cwd}
 
@@ -1303,7 +1662,7 @@ function makeOutboxNextSteps(result) {
 function makeListenerNextSteps(result) {
     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.",
     ]);
 }
 function makeScheduleNextSteps(result, options = {}) {