@beignet/cli 0.0.3 → 0.0.5

package/src/index.ts

@@ -7,97 +7,54 @@ import {
   buildRouteMap,
   type CommandContext,
   type FlagParametersForType,
+  proposeCompletions,
   run,
   type StricliDynamicCommandContext,
   type StricliProcess,
   text_en,
 } from "@stricli/core";
-import type { CreateOptions } from "./create.js";
-import { createProject } from "./create.js";
-import { type DatabaseCommand, runDatabaseCommand } from "./db.js";
 import {
-  applyDoctorFixes,
-  formatDoctor,
-  formatRoutes,
-  inspectApp,
-} from "./inspect.js";
-import { formatLint, lintApp } from "./lint.js";
-import {
-  makeAdapter,
-  makeContract,
-  makeEvent,
-  makeFactory,
-  makeFeature,
-  makeFeatureAddonChoices,
-  makeJob,
-  makeListener,
-  makeNotification,
-  makePolicy,
-  makePort,
-  makeResource,
-  makeSchedule,
-  makeSeed,
-  makeTest,
-  makeUpload,
-  makeUseCase,
-} from "./make.js";
-
-export type { MakeFeatureAddon } from "./make.js";
-
-import {
-  type FeatureName,
-  featureChoices,
+  type CompletionShell,
+  completionShellChoices,
   type IntegrationName,
   integrationChoices,
+  type MakeFeatureAddon,
+  makeFeatureAddonChoices,
   type PackageManager,
-  type PresetName,
-  presetChoices,
+  packageManagerChoices,
   type TemplateName,
-} from "./templates.js";
-
-export {
-  applyDoctorFixes,
-  type CreateOptions,
-  createProject,
-  formatDoctor,
-  formatLint,
-  formatRoutes,
-  type IntegrationName,
-  inspectApp,
-  lintApp,
-  makeAdapter,
-  makeContract,
-  makeEvent,
-  makeFactory,
-  makeFeature,
-  makeFeatureAddonChoices,
-  makeJob,
-  makeListener,
-  makeNotification,
-  makePolicy,
-  makePort,
-  makeResource,
-  makeSchedule,
-  makeSeed,
-  makeTest,
-  makeUpload,
-  makeUseCase,
-  runDatabaseCommand,
-};
+  templateChoices,
+} from "./choices.js";
+// Type-only: the runtime module stays behind the create command's lazy loader.
+import type { CreateSelections } from "./create-prompts.js";
+import { getCliVersion } from "./version.js";
 
 type CliContext = CommandContext & {
   readonly process: StricliProcess;
 };
 
+type OutputFormat = "human" | "json" | "github";
+
+const outputFormatChoices = [
+  "human",
+  "json",
+  "github",
+] as const satisfies readonly OutputFormat[];
+
 type CreateFlags = {
   template: TemplateName;
-  preset: PresetName;
+  api?: boolean;
   packageManager?: PackageManager;
-  feature?: readonly FeatureName[];
-  features?: readonly FeatureName[];
-  integration?: readonly IntegrationName[];
   integrations?: readonly IntegrationName[];
+  yes?: boolean;
   force?: boolean;
+  dryRun?: boolean;
+  json?: boolean;
+};
+
+type CompletionFlags = {
+  shell?: CompletionShell;
+  json?: boolean;
 };
 
 type MakeFlags = {
@@ -106,8 +63,15 @@ type MakeFlags = {
   json?: boolean;
 };
 
+type MakeResourceFlags = MakeFlags & {
+  auth?: boolean;
+  tenant?: boolean;
+  events?: boolean;
+  softDelete?: boolean;
+};
+
 type MakeFeatureFlags = MakeFlags & {
-  with?: readonly (typeof makeFeatureAddonChoices)[number][];
+  with?: readonly MakeFeatureAddon[];
 };
 
 type MakeListenerFlags = MakeFlags & {
@@ -120,8 +84,15 @@ type MakeScheduleFlags = MakeFlags & {
   route?: boolean;
 };
 
-type JsonFlags = {
+type RoutesFlags = {
+  json?: boolean;
+  cwd?: string;
+};
+
+type LintFlags = {
   json?: boolean;
+  cwd?: string;
+  format?: OutputFormat;
 };
 
 type DbFlags = {
@@ -129,21 +100,45 @@ type DbFlags = {
   dryRun?: boolean;
 };
 
+type TaskRunFlags = {
+  json?: boolean;
+  input?: string;
+  module?: string;
+};
+
+type OutboxDrainFlags = {
+  json?: boolean;
+  module?: string;
+  batchSize?: number;
+};
+
+type ScheduleRunFlags = {
+  json?: boolean;
+  module?: string;
+  payload?: string;
+  id?: string;
+  attempt?: number;
+  scheduledAt?: string;
+  triggeredAt?: string;
+  source?: string;
+};
+
 type DoctorFlags = {
   json?: boolean;
   strict?: boolean;
   fix?: boolean;
+  cwd?: string;
+  format?: OutputFormat;
 };
 
-const templateChoices = ["next"] as const satisfies readonly TemplateName[];
-const packageManagerChoices = [
-  "bun",
-  "npm",
-  "pnpm",
-  "yarn",
-] as const satisfies readonly PackageManager[];
-
 const parseString = (input: string): string => input;
+const parsePositiveInteger = (input: string): number => {
+  const value = Number(input);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error("Expected a positive integer.");
+  }
+  return value;
+};
 
 const forceFlag = {
   kind: "boolean",
@@ -174,21 +169,79 @@ const parsedStringFlag = (brief: string) =>
     brief,
   }) as const;
 
+const cwdFlag = parsedStringFlag(
+  "App directory to inspect. Defaults to the current working directory.",
+);
+
+const formatFlag = {
+  kind: "enum",
+  values: outputFormatChoices,
+  optional: true,
+  brief:
+    "Output format. Defaults to human, or github when GITHUB_ACTIONS=true.",
+} as const;
+
 const makeFlagParameters = {
   force: forceFlag,
   dryRun: dryRunFlag,
   json: jsonFlag,
 } satisfies FlagParametersForType<MakeFlags, CliContext>;
 
-const jsonFlagParameters = {
+const routesFlagParameters = {
+  json: jsonFlag,
+  cwd: cwdFlag,
+} satisfies FlagParametersForType<RoutesFlags, CliContext>;
+
+const lintFlagParameters = {
   json: jsonFlag,
-} satisfies FlagParametersForType<JsonFlags, CliContext>;
+  cwd: cwdFlag,
+  format: formatFlag,
+} satisfies FlagParametersForType<LintFlags, CliContext>;
 
 const dbFlagParameters = {
   json: jsonFlag,
   dryRun: dryRunFlag,
 } satisfies FlagParametersForType<DbFlags, CliContext>;
 
+const taskRunFlagParameters = {
+  json: jsonFlag,
+  input: parsedStringFlag("JSON input passed to the task schema."),
+  module: parsedStringFlag(
+    "Task registry module. Defaults to server/tasks.ts.",
+  ),
+} satisfies FlagParametersForType<TaskRunFlags, CliContext>;
+
+const outboxDrainFlagParameters = {
+  json: jsonFlag,
+  module: parsedStringFlag(
+    "Outbox registry module. Defaults to server/outbox.ts.",
+  ),
+  batchSize: {
+    kind: "parsed",
+    parse: parsePositiveInteger,
+    optional: true,
+    brief: "Maximum messages to claim in one drain pass.",
+  },
+} satisfies FlagParametersForType<OutboxDrainFlags, CliContext>;
+
+const scheduleRunFlagParameters = {
+  json: jsonFlag,
+  module: parsedStringFlag(
+    "Schedule registry module. Defaults to server/schedules.ts.",
+  ),
+  payload: parsedStringFlag("JSON payload passed to the schedule schema."),
+  id: parsedStringFlag("Provider or app schedule run ID."),
+  attempt: {
+    kind: "parsed",
+    parse: parsePositiveInteger,
+    optional: true,
+    brief: "One-based provider attempt number.",
+  },
+  scheduledAt: parsedStringFlag("Provider scheduled timestamp."),
+  triggeredAt: parsedStringFlag("Schedule trigger timestamp."),
+  source: parsedStringFlag("Provider or app source label."),
+} satisfies FlagParametersForType<ScheduleRunFlags, CliContext>;
+
 const namePositional = {
   kind: "tuple",
   parameters: [
@@ -200,12 +253,43 @@ const namePositional = {
   ],
 } as const;
 
-const createCommand = buildCommand<CreateFlags, [string], CliContext>({
+function resolveOutputFormat(flags: {
+  json?: boolean;
+  format?: OutputFormat;
+}): OutputFormat {
+  if (flags.json) {
+    if (flags.format && flags.format !== "json") {
+      throw new Error(
+        `--json conflicts with --format ${flags.format}. Pass one of them.`,
+      );
+    }
+    return "json";
+  }
+
+  if (flags.format) return flags.format;
+  return process.env.GITHUB_ACTIONS === "true" ? "github" : "human";
+}
+
+function useColor(): boolean {
+  return process.stdout.isTTY === true && !process.env.NO_COLOR;
+}
+
+const createCommand = buildCommand<
+  CreateFlags,
+  [string | undefined],
+  CliContext
+>({
   docs: {
     brief: "Create a new Beignet app.",
-    fullDescription: `Available features: ${featureChoices.join(", ")}
+    fullDescription: `Scaffolds a full-stack Beignet starter: typed contracts, Better Auth,
+Drizzle/libSQL persistence with checked-in migrations, pino logging,
+devtools, and a shadcn UI shell. Pass --api for an API-only scaffold
+without the UI shell.
+
+Available integrations: ${integrationChoices.join(", ")}
 
-Available integrations: ${integrationChoices.join(", ")}`,
+Running create on an interactive terminal without selection flags opens a
+prompt-based setup. Pass --yes or any selection flag to skip the prompts.`,
   },
   parameters: {
     flags: {
@@ -215,11 +299,11 @@ Available integrations: ${integrationChoices.join(", ")}`,
         default: "next",
         brief: "Template to use.",
       },
-      preset: {
-        kind: "enum",
-        values: presetChoices,
-        default: "standard",
-        brief: "Starter preset to generate.",
+      api: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief: "Scaffold an API-only app without the UI shell.",
       },
       packageManager: {
         kind: "enum",
@@ -227,35 +311,22 @@ Available integrations: ${integrationChoices.join(", ")}`,
         optional: true,
         brief: "Package manager to use in next-step commands.",
       },
-      feature: {
-        kind: "enum",
-        values: featureChoices,
-        optional: true,
-        variadic: true,
-        brief: "Add a starter feature. Repeatable.",
-      },
-      features: {
-        kind: "enum",
-        values: featureChoices,
-        optional: true,
-        variadic: ",",
-        brief: "Add comma-separated starter features.",
-      },
-      integration: {
-        kind: "enum",
-        values: integrationChoices,
-        optional: true,
-        variadic: true,
-        brief: "Add a first-party integration. Repeatable.",
-      },
       integrations: {
         kind: "enum",
         values: integrationChoices,
         optional: true,
         variadic: ",",
-        brief: "Add comma-separated first-party integrations.",
+        brief: "Add first-party integrations as a comma-separated list.",
+      },
+      yes: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief: "Skip interactive prompts and use the defaults.",
       },
       force: forceFlag,
+      dryRun: dryRunFlag,
+      json: jsonFlag,
     },
     positional: {
       kind: "tuple",
@@ -264,45 +335,91 @@ Available integrations: ${integrationChoices.join(", ")}`,
           parse: parseString,
           placeholder: "directory",
           brief: "Project directory to create.",
+          optional: true,
         },
       ],
     },
   },
-  async func(flags, directory) {
-    const integrations = uniqueValues([
-      ...(flags.integration ?? []),
-      ...(flags.integrations ?? []),
-    ]);
-    const result = await createProject({
-      name: directory,
-      template: flags.template,
-      preset: flags.preset,
-      features: uniqueValues([
-        ...(flags.feature ?? []),
-        ...(flags.features ?? []),
-      ]),
-      packageManager: flags.packageManager,
-      integrations,
-      force: Boolean(flags.force),
-    });
-
-    writeOutput(this, nextSteps(result, { integrations }));
+  loader: async () => {
+    const { createProject } = await import("./create.js");
+    const { promptCreateSelections, shouldPromptInteractively } = await import(
+      "./create-prompts.js"
+    );
+
+    return async function runCreate(
+      this: CliContext,
+      flags: CreateFlags,
+      directory: string | undefined,
+    ) {
+      let selections: CreateSelections = {
+        directory,
+        api: flags.api,
+        integrations: flags.integrations,
+        packageManager: flags.packageManager,
+      };
+
+      const interactive = shouldPromptInteractively(
+        { ...selections, yes: flags.yes },
+        {
+          stdin: process.stdin.isTTY === true,
+          stdout: process.stdout.isTTY === true,
+        },
+      );
+      if (interactive) {
+        const answers = await promptCreateSelections(selections);
+        if (answers === undefined) {
+          this.process.stderr.write("Cancelled.\n");
+          this.process.exitCode = 2;
+          return;
+        }
+        selections = answers;
+      }
+
+      if (selections.directory === undefined) {
+        throw new Error(
+          "Project directory is required. Pass beignet create <directory>, or run beignet create in an interactive terminal.",
+        );
+      }
+
+      const api = selections.api ?? false;
+      const integrations = uniqueValues([...(selections.integrations ?? [])]);
+      const result = await createProject({
+        name: selections.directory,
+        template: flags.template,
+        api,
+        packageManager: selections.packageManager,
+        integrations,
+        force: Boolean(flags.force),
+        dryRun: Boolean(flags.dryRun),
+      });
+
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : nextSteps(result, { api, integrations }),
+      );
+    };
   },
 });
 
-const routesCommand = buildCommand<JsonFlags, [], CliContext>({
+const routesCommand = buildCommand<RoutesFlags, [], CliContext>({
   docs: {
     brief: "Inspect registered Beignet routes.",
   },
   parameters: {
-    flags: jsonFlagParameters,
+    flags: routesFlagParameters,
   },
-  async func(flags) {
-    const result = await inspectApp();
-    writeOutput(
-      this,
-      flags.json ? JSON.stringify(result, null, 2) : formatRoutes(result),
-    );
+  loader: async () => {
+    const { formatRoutes, inspectApp } = await import("./inspect.js");
+
+    return async function runRoutes(this: CliContext, flags: RoutesFlags) {
+      const result = await inspectApp({ cwd: flags.cwd });
+      writeOutput(
+        this,
+        flags.json ? JSON.stringify(result, null, 2) : formatRoutes(result),
+      );
+    };
   },
 });
 
@@ -325,50 +442,79 @@ const doctorCommand = buildCommand<DoctorFlags, [], CliContext>({
         withNegated: false,
         brief: "Apply low-risk fixes before reporting.",
       },
+      cwd: cwdFlag,
+      format: formatFlag,
     },
   },
-  async func(flags) {
-    const fixes = flags.fix
-      ? await applyDoctorFixes({ strict: Boolean(flags.strict) })
-      : [];
-    const result = await inspectApp({ strict: Boolean(flags.strict) });
-    result.fixes = fixes;
-    writeOutput(
-      this,
-      flags.json ? JSON.stringify(result, null, 2) : formatDoctor(result),
-    );
-    if (
-      result.diagnostics.some(
-        (diagnostic) =>
-          diagnostic.severity === "error" ||
-          (flags.strict && diagnostic.severity === "warning"),
-      )
-    ) {
-      this.process.exitCode = 1;
-    }
+  loader: async () => {
+    const { applyDoctorFixes, formatDoctor, formatDoctorGithub, inspectApp } =
+      await import("./inspect.js");
+
+    return async function runDoctor(this: CliContext, flags: DoctorFlags) {
+      const format = resolveOutputFormat(flags);
+      const fixes = flags.fix
+        ? await applyDoctorFixes({
+            cwd: flags.cwd,
+            strict: Boolean(flags.strict),
+          })
+        : [];
+      const result = await inspectApp({
+        cwd: flags.cwd,
+        strict: Boolean(flags.strict),
+      });
+      result.fixes = fixes;
+      writeOutput(
+        this,
+        format === "json"
+          ? JSON.stringify(result, null, 2)
+          : format === "github"
+            ? formatDoctorGithub(result)
+            : formatDoctor(result, { color: useColor() }),
+      );
+      if (
+        result.diagnostics.some(
+          (diagnostic) =>
+            diagnostic.severity === "error" ||
+            (flags.strict && diagnostic.severity === "warning"),
+        )
+      ) {
+        this.process.exitCode = 1;
+      }
+    };
   },
 });
 
-const lintCommand = buildCommand<JsonFlags, [], CliContext>({
+const lintCommand = buildCommand<LintFlags, [], CliContext>({
   docs: {
     brief: "Check Beignet dependency direction conventions.",
   },
   parameters: {
-    flags: jsonFlagParameters,
+    flags: lintFlagParameters,
   },
-  async func(flags) {
-    const result = await lintApp();
-    writeOutput(
-      this,
-      flags.json ? JSON.stringify(result, null, 2) : formatLint(result),
-    );
-    if (result.diagnostics.length > 0) {
-      this.process.exitCode = 1;
-    }
+  loader: async () => {
+    const { formatLint, formatLintGithub, lintApp } = await import("./lint.js");
+
+    return async function runLint(this: CliContext, flags: LintFlags) {
+      const format = resolveOutputFormat(flags);
+      const result = await lintApp({ cwd: flags.cwd });
+      writeOutput(
+        this,
+        format === "json"
+          ? JSON.stringify(result, null, 2)
+          : format === "github"
+            ? formatLintGithub(result)
+            : formatLint(result, { color: useColor() }),
+      );
+      if (result.diagnostics.length > 0) {
+        this.process.exitCode = 1;
+      }
+    };
   },
 });
 
-function databaseCommand(command: DatabaseCommand) {
+type DatabaseCommandName = "generate" | "migrate" | "reset" | "seed";
+
+function databaseCommand(command: DatabaseCommandName) {
   return buildCommand<DbFlags, [], CliContext>({
     docs: {
       brief: `Run the app's db:${command} script.`,
@@ -376,22 +522,26 @@ function databaseCommand(command: DatabaseCommand) {
     parameters: {
       flags: dbFlagParameters,
     },
-    async func(flags) {
-      const result = await runDatabaseCommand({
-        command,
-        captureOutput: Boolean(flags.json),
-        dryRun: Boolean(flags.dryRun),
-      });
-
-      writeOutput(
-        this,
-        flags.json
-          ? JSON.stringify(result, null, 2)
-          : databaseCommandNextSteps(result),
-      );
-      if (result.exitCode !== 0) {
-        this.process.exitCode = result.exitCode;
-      }
+    loader: async () => {
+      const { runDatabaseCommand } = await import("./db.js");
+
+      return async function runDb(this: CliContext, flags: DbFlags) {
+        const result = await runDatabaseCommand({
+          command,
+          captureOutput: Boolean(flags.json),
+          dryRun: Boolean(flags.dryRun),
+        });
+
+        writeOutput(
+          this,
+          flags.json
+            ? JSON.stringify(result, null, 2)
+            : databaseCommandNextSteps(result),
+        );
+        if (result.exitCode !== 0) {
+          this.process.exitCode = result.exitCode;
+        }
+      };
     },
   });
 }
@@ -408,409 +558,461 @@ const dbRoutes = buildRouteMap({
   },
 });
 
-const makeResourceCommand = buildCommand<MakeFlags, [string], CliContext>({
+const taskRunCommand = buildCommand<TaskRunFlags, [string], CliContext>({
   docs: {
-    brief: "Generate a feature resource.",
+    brief: "Run an app-owned operational task.",
   },
   parameters: {
-    flags: makeFlagParameters,
+    flags: taskRunFlagParameters,
     positional: namePositional,
   },
-  async func(flags, name) {
-    const result = await makeResource({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json
-        ? JSON.stringify(result, null, 2)
-        : makeResourceNextSteps(result),
-    );
-  },
-});
+  loader: async () => {
+    const { runAppTask } = await import("./task.js");
 
-const makeFeatureCommand = buildCommand<MakeFeatureFlags, [string], CliContext>(
-  {
-    docs: {
-      brief: "Generate a contract-first feature slice.",
-    },
-    parameters: {
-      flags: {
-        ...makeFlagParameters,
-        with: {
-          kind: "enum",
-          values: makeFeatureAddonChoices,
-          optional: true,
-          variadic: ",",
-          brief:
-            "Add feature-owned artifacts. Supports policy, event/events, job/jobs, and upload/uploads.",
-        },
-      } satisfies FlagParametersForType<MakeFeatureFlags, CliContext>,
-      positional: namePositional,
-    },
-    async func(flags, name) {
-      const result = await makeFeature({
+    return async function runTask(
+      this: CliContext,
+      flags: TaskRunFlags,
+      name: string,
+    ) {
+      const result = await runAppTask({
         name,
-        with: flags.with,
-        force: Boolean(flags.force),
-        dryRun: Boolean(flags.dryRun),
+        input: flags.input,
+        modulePath: flags.module,
       });
+
       writeOutput(
         this,
         flags.json
           ? JSON.stringify(result, null, 2)
-          : makeFeatureNextSteps(result),
+          : appTaskRunNextSteps(result),
       );
-    },
-  },
-);
-
-const makeContractCommand = buildCommand<MakeFlags, [string], CliContext>({
-  docs: {
-    brief: "Generate a contract group.",
-  },
-  parameters: {
-    flags: makeFlagParameters,
-    positional: namePositional,
-  },
-  async func(flags, name) {
-    const result = await makeContract({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json
-        ? JSON.stringify(result, null, 2)
-        : makeContractNextSteps(result),
-    );
+    };
   },
 });
 
-const makeUseCaseCommand = buildCommand<MakeFlags, [string], CliContext>({
+const taskRoutes = buildRouteMap({
   docs: {
-    brief: "Generate a use case.",
-  },
-  parameters: {
-    flags: makeFlagParameters,
-    positional: namePositional,
+    brief: "Run Beignet app operational tasks.",
   },
-  async func(flags, name) {
-    const result = await makeUseCase({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json
-        ? JSON.stringify(result, null, 2)
-        : makeUseCaseNextSteps(result),
-    );
+  routes: {
+    run: taskRunCommand,
   },
 });
 
-const makeTestCommand = buildCommand<MakeFlags, [string], CliContext>({
+const outboxDrainCommand = buildCommand<OutboxDrainFlags, [], CliContext>({
   docs: {
-    brief: "Generate a use case test.",
+    brief: "Run one app-owned outbox drain pass.",
   },
   parameters: {
-    flags: makeFlagParameters,
-    positional: namePositional,
-  },
-  async func(flags, name) {
-    const result = await makeTest({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json ? JSON.stringify(result, null, 2) : makeTestNextSteps(result),
-    );
+    flags: outboxDrainFlagParameters,
   },
-});
+  loader: async () => {
+    const { runOutboxDrain } = await import("./outbox.js");
 
-const makePortCommand = buildCommand<MakeFlags, [string], CliContext>({
-  docs: {
-    brief: "Generate an application port.",
-  },
-  parameters: {
-    flags: makeFlagParameters,
-    positional: namePositional,
-  },
-  async func(flags, name) {
-    const result = await makePort({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json ? JSON.stringify(result, null, 2) : makePortNextSteps(result),
-    );
+    return async function runDrain(this: CliContext, flags: OutboxDrainFlags) {
+      const result = await runOutboxDrain({
+        modulePath: flags.module,
+        batchSize: flags.batchSize,
+      });
+
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : outboxDrainNextSteps(result),
+      );
+    };
   },
 });
 
-const makeAdapterCommand = buildCommand<MakeFlags, [string], CliContext>({
+const outboxRoutes = buildRouteMap({
   docs: {
-    brief: "Generate a port adapter.",
-  },
-  parameters: {
-    flags: makeFlagParameters,
-    positional: namePositional,
+    brief: "Run Beignet outbox operations.",
   },
-  async func(flags, name) {
-    const result = await makeAdapter({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json
-        ? JSON.stringify(result, null, 2)
-        : makeAdapterNextSteps(result),
-    );
+  routes: {
+    drain: outboxDrainCommand,
   },
 });
 
-const makePolicyCommand = buildCommand<MakeFlags, [string], CliContext>({
-  docs: {
-    brief: "Generate an authorization policy.",
-  },
-  parameters: {
-    flags: makeFlagParameters,
-    positional: namePositional,
-  },
-  async func(flags, name) {
-    const result = await makePolicy({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json
-        ? JSON.stringify(result, null, 2)
-        : makePolicyNextSteps(result),
-    );
+const scheduleRunCommand = buildCommand<ScheduleRunFlags, [string], CliContext>(
+  {
+    docs: {
+      brief: "Run an app-owned schedule.",
+    },
+    parameters: {
+      flags: scheduleRunFlagParameters,
+      positional: namePositional,
+    },
+    loader: async () => {
+      const { runAppSchedule } = await import("./schedule.js");
+
+      return async function runSchedule(
+        this: CliContext,
+        flags: ScheduleRunFlags,
+        name: string,
+      ) {
+        const result = await runAppSchedule({
+          name,
+          modulePath: flags.module,
+          payload: flags.payload,
+          id: flags.id,
+          attempt: flags.attempt,
+          scheduledAt: flags.scheduledAt,
+          triggeredAt: flags.triggeredAt,
+          source: flags.source,
+        });
+
+        writeOutput(
+          this,
+          flags.json
+            ? JSON.stringify(result, null, 2)
+            : scheduleRunNextSteps(result),
+        );
+      };
+    },
   },
-});
+);
 
-const makeEventCommand = buildCommand<MakeFlags, [string], CliContext>({
+const scheduleRoutes = buildRouteMap({
   docs: {
-    brief: "Generate a feature event.",
-  },
-  parameters: {
-    flags: makeFlagParameters,
-    positional: namePositional,
+    brief: "Run Beignet schedule operations.",
   },
-  async func(flags, name) {
-    const result = await makeEvent({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json ? JSON.stringify(result, null, 2) : makeEventNextSteps(result),
-    );
+  routes: {
+    run: scheduleRunCommand,
   },
 });
 
-const makeJobCommand = buildCommand<MakeFlags, [string], CliContext>({
-  docs: {
-    brief: "Generate a feature job.",
-  },
-  parameters: {
-    flags: makeFlagParameters,
-    positional: namePositional,
-  },
-  async func(flags, name) {
-    const result = await makeJob({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json ? JSON.stringify(result, null, 2) : makeJobNextSteps(result),
-    );
+const completionShellFlagParameters = {
+  shell: {
+    kind: "enum",
+    values: completionShellChoices,
+    optional: true,
+    brief: "Shell to manage completions for. Defaults to $SHELL.",
   },
-});
+  json: jsonFlag,
+} satisfies FlagParametersForType<CompletionFlags, CliContext>;
 
-const makeFactoryCommand = buildCommand<MakeFlags, [string], CliContext>({
+const completionInstallCommand = buildCommand<CompletionFlags, [], CliContext>({
   docs: {
-    brief: "Generate a feature test data factory.",
+    brief: "Install beignet shell completions for bash or zsh.",
   },
   parameters: {
-    flags: makeFlagParameters,
-    positional: namePositional,
+    flags: completionShellFlagParameters,
   },
-  async func(flags, name) {
-    const result = await makeFactory({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json
-        ? JSON.stringify(result, null, 2)
-        : makeFactoryNextSteps(result),
-    );
+  loader: async () => {
+    const { installCompletions } = await import("./completion.js");
+
+    return async function runInstall(this: CliContext, flags: CompletionFlags) {
+      const result = await installCompletions({ shell: flags.shell });
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : `${result.status === "updated" ? "Updated" : "Installed"} ${result.shell} completions in ${result.file}
+
+Restart your shell or source the file to activate them.`,
+      );
+    };
   },
 });
 
-const makeSeedCommand = buildCommand<MakeFlags, [string], CliContext>({
+const completionUninstallCommand = buildCommand<
+  CompletionFlags,
+  [],
+  CliContext
+>({
   docs: {
-    brief: "Generate a feature seed.",
+    brief: "Remove beignet shell completions for bash or zsh.",
   },
   parameters: {
-    flags: makeFlagParameters,
-    positional: namePositional,
+    flags: completionShellFlagParameters,
   },
-  async func(flags, name) {
-    const result = await makeSeed({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json ? JSON.stringify(result, null, 2) : makeSeedNextSteps(result),
-    );
+  loader: async () => {
+    const { uninstallCompletions } = await import("./completion.js");
+
+    return async function runUninstall(
+      this: CliContext,
+      flags: CompletionFlags,
+    ) {
+      const result = await uninstallCompletions({ shell: flags.shell });
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : result.status === "removed"
+            ? `Removed ${result.shell} completions from ${result.file}`
+            : `No beignet completions found in ${result.file}`,
+      );
+    };
   },
 });
 
-const makeNotificationCommand = buildCommand<MakeFlags, [string], CliContext>({
+const completionRoutes = buildRouteMap({
   docs: {
-    brief: "Generate a feature notification.",
-  },
-  parameters: {
-    flags: makeFlagParameters,
-    positional: namePositional,
+    brief: "Manage beignet shell completions.",
   },
-  async func(flags, name) {
-    const result = await makeNotification({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json
-        ? JSON.stringify(result, null, 2)
-        : makeNotificationNextSteps(result),
-    );
+  routes: {
+    install: completionInstallCommand,
+    uninstall: completionUninstallCommand,
   },
 });
 
-const makeListenerFlagParameters = {
-  ...makeFlagParameters,
-  event: parsedStringFlag("Event to listen to, for example posts/published."),
-} satisfies FlagParametersForType<MakeListenerFlags, CliContext>;
-
-const makeListenerCommand = buildCommand<
-  MakeListenerFlags,
+const makeResourceCommand = buildCommand<
+  MakeResourceFlags,
   [string],
   CliContext
 >({
   docs: {
-    brief: "Generate a feature event listener.",
+    brief: "Generate a CRUD-shaped resource slice.",
   },
   parameters: {
-    flags: makeListenerFlagParameters,
+    flags: {
+      ...makeFlagParameters,
+      auth: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief:
+          "Generate policy metadata and use-case authorization checks for mutating routes.",
+      },
+      tenant: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief:
+          "Generate tenant-scoped schemas, repository methods, and use-case checks.",
+      },
+      events: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief: "Generate domain event definitions and publish resource events.",
+      },
+      softDelete: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief:
+          "Generate soft-delete persistence that archives rows with deletedAt.",
+      },
+    } satisfies FlagParametersForType<MakeResourceFlags, CliContext>,
     positional: namePositional,
   },
-  async func(flags, name) {
-    if (!flags.event) {
-      throw new Error(
-        "beignet make listener requires --event feature/name, for example --event posts/published.",
-      );
-    }
+  loader: async () => {
+    const { makeResource } = await import("./make.js");
 
-    const result = await makeListener({
-      name,
-      event: flags.event,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json
-        ? JSON.stringify(result, null, 2)
-        : makeListenerNextSteps(result),
-    );
+    return async function runMakeResource(
+      this: CliContext,
+      flags: MakeResourceFlags,
+      name: string,
+    ) {
+      const result = await makeResource({
+        name,
+        force: Boolean(flags.force),
+        dryRun: Boolean(flags.dryRun),
+        auth: Boolean(flags.auth),
+        tenant: Boolean(flags.tenant),
+        events: Boolean(flags.events),
+        softDelete: Boolean(flags.softDelete),
+      });
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : makeResourceNextSteps(result),
+      );
+    };
   },
 });
 
-const makeScheduleFlagParameters = {
-  ...makeFlagParameters,
-  cron: parsedStringFlag("Cron expression. Defaults to 0 9 * * *."),
-  timezone: parsedStringFlag("IANA timezone, for example America/Chicago."),
-  route: {
-    kind: "boolean",
-    optional: true,
-    withNegated: false,
-    brief: "Generate a Next.js cron route for this schedule.",
+const makeFeatureCommand = buildCommand<MakeFeatureFlags, [string], CliContext>(
+  {
+    docs: {
+      brief: "Generate a contract-first feature slice.",
+    },
+    parameters: {
+      flags: {
+        ...makeFlagParameters,
+        with: {
+          kind: "enum",
+          values: makeFeatureAddonChoices,
+          optional: true,
+          variadic: ",",
+          brief:
+            "Add feature-owned artifacts. Supports policy, task/tasks, event/events, job/jobs, notification/notifications, ui, and upload/uploads.",
+        },
+      } satisfies FlagParametersForType<MakeFeatureFlags, CliContext>,
+      positional: namePositional,
+    },
+    loader: async () => {
+      const { makeFeature } = await import("./make.js");
+
+      return async function runMakeFeature(
+        this: CliContext,
+        flags: MakeFeatureFlags,
+        name: string,
+      ) {
+        const result = await makeFeature({
+          name,
+          with: flags.with,
+          force: Boolean(flags.force),
+          dryRun: Boolean(flags.dryRun),
+        });
+        writeOutput(
+          this,
+          flags.json
+            ? JSON.stringify(result, null, 2)
+            : makeFeatureNextSteps(result),
+        );
+      };
+    },
   },
-} satisfies FlagParametersForType<MakeScheduleFlags, CliContext>;
+);
 
-const makeScheduleCommand = buildCommand<
-  MakeScheduleFlags,
+type MakeGeneratorName =
+  | "makeAdapter"
+  | "makeContract"
+  | "makeEvent"
+  | "makeFactory"
+  | "makeJob"
+  | "makeNotification"
+  | "makePolicy"
+  | "makePort"
+  | "makeSeed"
+  | "makeTask"
+  | "makeTest"
+  | "makeUpload"
+  | "makeUseCase";
+
+function simpleMakeCommand(
+  generator: MakeGeneratorName,
+  brief: string,
+  formatNextSteps: (result: MakeNextStepsResult) => string,
+) {
+  return buildCommand<MakeFlags, [string], CliContext>({
+    docs: {
+      brief,
+    },
+    parameters: {
+      flags: makeFlagParameters,
+      positional: namePositional,
+    },
+    loader: async () => {
+      const generators = await import("./make.js");
+
+      return async function runMake(
+        this: CliContext,
+        flags: MakeFlags,
+        name: string,
+      ) {
+        const result = await generators[generator]({
+          name,
+          force: Boolean(flags.force),
+          dryRun: Boolean(flags.dryRun),
+        });
+        writeOutput(
+          this,
+          flags.json
+            ? JSON.stringify(result, null, 2)
+            : formatNextSteps(result),
+        );
+      };
+    },
+  });
+}
+
+const makeListenerCommand = buildCommand<
+  MakeListenerFlags,
   [string],
   CliContext
 >({
   docs: {
-    brief: "Generate a feature schedule.",
+    brief: "Generate a feature event listener.",
   },
   parameters: {
-    flags: makeScheduleFlagParameters,
+    flags: {
+      ...makeFlagParameters,
+      event: parsedStringFlag(
+        "Event to listen to, for example posts/published.",
+      ),
+    } satisfies FlagParametersForType<MakeListenerFlags, CliContext>,
     positional: namePositional,
   },
-  async func(flags, name) {
-    const result = await makeSchedule({
-      name,
-      cron: flags.cron,
-      timezone: flags.timezone,
-      route: Boolean(flags.route),
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json
-        ? JSON.stringify(result, null, 2)
-        : makeScheduleNextSteps(result),
-    );
+  loader: async () => {
+    const { makeListener } = await import("./make.js");
+
+    return async function runMakeListener(
+      this: CliContext,
+      flags: MakeListenerFlags,
+      name: string,
+    ) {
+      if (!flags.event) {
+        throw new Error(
+          "beignet make listener requires --event feature/name, for example --event posts/published.",
+        );
+      }
+
+      const result = await makeListener({
+        name,
+        event: flags.event,
+        force: Boolean(flags.force),
+        dryRun: Boolean(flags.dryRun),
+      });
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : makeListenerNextSteps(result),
+      );
+    };
   },
 });
 
-const makeUploadCommand = buildCommand<MakeFlags, [string], CliContext>({
+const makeScheduleCommand = buildCommand<
+  MakeScheduleFlags,
+  [string],
+  CliContext
+>({
   docs: {
-    brief: "Generate a feature upload.",
+    brief: "Generate a feature schedule.",
   },
   parameters: {
-    flags: makeFlagParameters,
+    flags: {
+      ...makeFlagParameters,
+      cron: parsedStringFlag("Cron expression. Defaults to 0 9 * * *."),
+      timezone: parsedStringFlag("IANA timezone, for example America/Chicago."),
+      route: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief: "Generate a Next.js cron route for this schedule.",
+      },
+    } satisfies FlagParametersForType<MakeScheduleFlags, CliContext>,
     positional: namePositional,
   },
-  async func(flags, name) {
-    const result = await makeUpload({
-      name,
-      force: Boolean(flags.force),
-      dryRun: Boolean(flags.dryRun),
-    });
-    writeOutput(
-      this,
-      flags.json
-        ? JSON.stringify(result, null, 2)
-        : makeUploadNextSteps(result),
-    );
+  loader: async () => {
+    const { makeSchedule } = await import("./make.js");
+
+    return async function runMakeSchedule(
+      this: CliContext,
+      flags: MakeScheduleFlags,
+      name: string,
+    ) {
+      const result = await makeSchedule({
+        name,
+        cron: flags.cron,
+        timezone: flags.timezone,
+        route: Boolean(flags.route),
+        force: Boolean(flags.force),
+        dryRun: Boolean(flags.dryRun),
+      });
+      writeOutput(
+        this,
+        flags.json
+          ? JSON.stringify(result, null, 2)
+          : makeScheduleNextSteps(result, { route: Boolean(flags.route) }),
+      );
+    };
   },
 });
 
@@ -819,22 +1021,75 @@ const makeRoutes = buildRouteMap({
     brief: "Generate Beignet app files.",
   },
   routes: {
-    adapter: makeAdapterCommand,
-    contract: makeContractCommand,
-    event: makeEventCommand,
-    factory: makeFactoryCommand,
+    adapter: simpleMakeCommand(
+      "makeAdapter",
+      "Generate a port adapter.",
+      makeAdapterNextSteps,
+    ),
+    contract: simpleMakeCommand(
+      "makeContract",
+      "Generate a contract group.",
+      makeContractNextSteps,
+    ),
+    event: simpleMakeCommand(
+      "makeEvent",
+      "Generate a feature event.",
+      makeEventNextSteps,
+    ),
+    factory: simpleMakeCommand(
+      "makeFactory",
+      "Generate a feature test data factory.",
+      makeFactoryNextSteps,
+    ),
     feature: makeFeatureCommand,
-    job: makeJobCommand,
-    notification: makeNotificationCommand,
+    job: simpleMakeCommand(
+      "makeJob",
+      "Generate a feature job.",
+      makeJobNextSteps,
+    ),
+    notification: simpleMakeCommand(
+      "makeNotification",
+      "Generate a feature notification.",
+      makeNotificationNextSteps,
+    ),
     listener: makeListenerCommand,
-    policy: makePolicyCommand,
-    port: makePortCommand,
+    policy: simpleMakeCommand(
+      "makePolicy",
+      "Generate an authorization policy.",
+      makePolicyNextSteps,
+    ),
+    port: simpleMakeCommand(
+      "makePort",
+      "Generate an application port.",
+      makePortNextSteps,
+    ),
     resource: makeResourceCommand,
     schedule: makeScheduleCommand,
-    seed: makeSeedCommand,
-    test: makeTestCommand,
-    upload: makeUploadCommand,
-    useCase: makeUseCaseCommand,
+    seed: simpleMakeCommand(
+      "makeSeed",
+      "Generate a feature seed.",
+      makeSeedNextSteps,
+    ),
+    task: simpleMakeCommand(
+      "makeTask",
+      "Generate a feature operational task.",
+      makeTaskNextSteps,
+    ),
+    test: simpleMakeCommand(
+      "makeTest",
+      "Generate a use case test.",
+      makeTestNextSteps,
+    ),
+    upload: simpleMakeCommand(
+      "makeUpload",
+      "Generate a feature upload.",
+      makeUploadNextSteps,
+    ),
+    useCase: simpleMakeCommand(
+      "makeUseCase",
+      "Generate a use case.",
+      makeUseCaseNextSteps,
+    ),
   },
 });
 
@@ -843,20 +1098,27 @@ const rootRoutes = buildRouteMap({
     brief: "Beignet CLI",
     fullDescription: `Create apps, generate framework files, inspect routes, and check Beignet conventions.
 
-create-beignet <directory> is equivalent to beignet create <directory>.`,
+Run npm create beignet@latest (or bun create beignet) to scaffold a new app.`,
   },
   routes: {
+    completion: completionRoutes,
     create: createCommand,
     db: dbRoutes,
     doctor: doctorCommand,
     lint: lintCommand,
     make: makeRoutes,
+    outbox: outboxRoutes,
     routes: routesCommand,
+    schedule: scheduleRoutes,
+    task: taskRoutes,
   },
 });
 
 const cli = buildApplication(rootRoutes, {
   name: "beignet",
+  versionInfo: {
+    currentVersion: getCliVersion(),
+  },
   scanner: {
     caseStyle: "allow-kebab-for-camel",
   },
@@ -870,7 +1132,7 @@ const cli = buildApplication(rootRoutes, {
       commandErrorResult: (error) => error.message,
     },
   },
-  determineExitCode: () => 1,
+  determineExitCode: () => 2,
 });
 
 function uniqueValues<T>(values: readonly T[]): T[] {
@@ -885,29 +1147,161 @@ function formatCliException(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }
 
+type CreateNextStepsResult = {
+  name: string;
+  targetDir: string;
+  dryRun: boolean;
+  files: string[];
+  packageManager: PackageManager;
+};
+
+type MakeNextStepsResult = {
+  name: string;
+  targetDir: string;
+  dryRun: boolean;
+  createdFiles: string[];
+  updatedFiles: string[];
+  skippedFiles: string[];
+};
+
+type DatabaseCommandNextStepsResult = {
+  script: string;
+  cwd: string;
+  runner: string;
+  args: string[];
+  dryRun: boolean;
+};
+
+type AppTaskRunNextStepsResult = {
+  name: string;
+  durationMs: number;
+  output: unknown;
+};
+
+type OutboxDrainNextStepsResult = {
+  durationMs: number;
+  result: {
+    claimed: number;
+    delivered: number;
+    retried: number;
+    deadLettered: number;
+  };
+};
+
+type ScheduleRunNextStepsResult = {
+  name: string;
+  durationMs: number;
+  run: {
+    source: string;
+    id?: string;
+    attempt?: number;
+    scheduledAt?: string;
+    triggeredAt?: string;
+  };
+};
+
+function appTaskRunNextSteps(result: AppTaskRunNextStepsResult): string {
+  const output =
+    result.output === undefined
+      ? "undefined"
+      : JSON.stringify(result.output, null, 2);
+
+  return `Ran task ${result.name} in ${result.durationMs}ms
+
+Output:
+${output}`;
+}
+
+function outboxDrainNextSteps(result: OutboxDrainNextStepsResult): string {
+  return `Drained outbox in ${result.durationMs}ms
+
+Result:
+  claimed: ${result.result.claimed}
+  delivered: ${result.result.delivered}
+  retried: ${result.result.retried}
+  deadLettered: ${result.result.deadLettered}`;
+}
+
+function scheduleRunNextSteps(result: ScheduleRunNextStepsResult): string {
+  return `Ran schedule ${result.name} in ${result.durationMs}ms
+
+Run:
+  source: ${result.run.source}
+  id: ${result.run.id ?? "none"}
+  attempt: ${result.run.attempt ?? "none"}
+  scheduledAt: ${result.run.scheduledAt ?? "none"}
+  triggeredAt: ${result.run.triggeredAt ?? "none"}`;
+}
+
 function nextSteps(
-  result: Awaited<ReturnType<typeof createProject>>,
-  options: { integrations?: readonly IntegrationName[] } = {},
+  result: CreateNextStepsResult,
+  options: {
+    api?: boolean;
+    integrations?: readonly IntegrationName[];
+  } = {},
 ): string {
+  if (result.dryRun) {
+    const plannedFiles = result.files.map((file) => `  ${file}`).join("\n");
+
+    return `Would create ${result.name} at ${result.targetDir}
+
+Planned files:
+${plannedFiles}`;
+  }
+
   const pm = result.packageManager;
   const run = pm === "npm" ? "npm run" : `${pm} run`;
-  const envFileStep = result.files.includes(".env.example")
-    ? "  cp .env.example .env.local\n"
-    : "";
+  const cli = packageRunnerFromPackageManager(pm);
   const envRequiredIntegrations =
     options.integrations?.filter(isEnvRequiredProviderIntegration) ?? [];
   const envStep =
     envRequiredIntegrations.length > 0
       ? "  Fill .env.local for selected provider integrations before starting the app.\n"
       : "";
+  const openStep = options.api
+    ? "  open http://localhost:3000 for the API landing page"
+    : "  open http://localhost:3000/sign-up";
 
   return `Created ${result.name} at ${result.targetDir}
 
 Next steps:
   cd ${result.targetDir}
   ${pm} install
-${envFileStep}${envStep}\
-  ${run} dev`;
+  cp .env.example .env.local
+${envStep}
+Prepare the database:
+  ${cli} db migrate
+
+Start the app:
+  ${run} dev
+${openStep}
+
+Inspect the app:
+  ${cli} routes
+  ${cli} lint
+  ${cli} doctor
+
+Generate a feature:
+  ${cli} make feature projects
+  ${cli} db generate
+  ${cli} db migrate
+  ${run} test
+  ${run} typecheck
+  ${cli} lint
+  ${cli} doctor`;
+}
+
+function packageRunnerFromPackageManager(pm: PackageManager): string {
+  switch (pm) {
+    case "npm":
+      return "npm run beignet --";
+    case "pnpm":
+      return "pnpm beignet";
+    case "yarn":
+      return "yarn beignet";
+    default:
+      return "bun beignet";
+  }
 }
 
 function isEnvRequiredProviderIntegration(
@@ -920,29 +1314,46 @@ function isEnvRequiredProviderIntegration(
   );
 }
 
-function makeResourceNextSteps(
-  result: Awaited<ReturnType<typeof makeResource>>,
+function changedFileLines(result: MakeNextStepsResult): {
+  changedFiles: string;
+  skippedFiles: string;
+} {
+  return {
+    changedFiles: [...result.createdFiles, ...result.updatedFiles]
+      .map((file) => `  ${file}`)
+      .join("\n"),
+    skippedFiles: result.skippedFiles.map((file) => `  ${file}`).join("\n"),
+  };
+}
+
+function makeNextSteps(
+  result: MakeNextStepsResult,
+  noun: string,
+  steps: readonly string[],
 ): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
+  const { changedFiles, skippedFiles } = changedFileLines(result);
 
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} resource in ${result.targetDir}
+  return `${result.dryRun ? "Would create" : "Created"} ${result.name} ${noun} in ${result.targetDir}
 
 Changed files:
 ${changedFiles || "  none"}
 ${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
 
 Next steps:
-  Review the generated schemas and repository fields.
-  Run your app's typecheck and test commands.`;
+${steps.map((step) => `  ${step}`).join("\n")}`;
+}
+
+function makeResourceNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "resource", [
+    "Use make resource when the feature maps cleanly to a REST resource with repository-backed persistence.",
+    "Review the generated schemas and repository fields.",
+    "If this app uses Drizzle, run beignet db generate and beignet db migrate so the new schema is ready.",
+    "Run your app's test and typecheck commands, then beignet lint and beignet doctor.",
+  ]);
 }
 
 function databaseCommandNextSteps(
-  result: Awaited<ReturnType<typeof runDatabaseCommand>>,
+  result: DatabaseCommandNextStepsResult,
 ): string {
   const command = [result.runner, ...result.args].join(" ");
   const prefix = result.dryRun ? "Would run" : "Ran";
@@ -953,317 +1364,125 @@ Command:
   ${command}`;
 }
 
-function makeFeatureNextSteps(
-  result: Awaited<ReturnType<typeof makeFeature>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} feature slice in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Treat the generated name field as a placeholder and shape the contracts, use cases, and repository around the feature's real workflow.
-  Run your app's typecheck, test, beignet lint, and beignet doctor commands.`;
+function makeFeatureNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "feature slice", [
+    "Use make feature for product capabilities and workflows. Use make resource when the concept is mostly CRUD-shaped.",
+    "Treat the generated name field as a placeholder and shape the contracts, use cases, and repository around the feature's real workflow.",
+    "If this app uses Drizzle, run beignet db generate and beignet db migrate so the new schema is ready.",
+    "Run your app's test and typecheck commands, then beignet lint and beignet doctor.",
+  ]);
 }
 
-function makeContractNextSteps(
-  result: Awaited<ReturnType<typeof makeContract>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} contract in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Add route handlers for the generated contracts.
-  Register the exported contract list with OpenAPI if this app publishes docs.`;
+function makeContractNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "contract", [
+    "Add route handlers for the generated contracts.",
+    "Register the exported contract list with OpenAPI if this app publishes docs.",
+  ]);
 }
 
-function makeUseCaseNextSteps(
-  result: Awaited<ReturnType<typeof makeUseCase>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} use case in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the starter input and output schemas with domain-specific shapes.
-  Add a focused use case test before wiring it to an HTTP route.`;
+function makeTaskNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "task", [
+    "Replace the starter input schema and handler with the operational workflow.",
+    "Keep business rules in use cases and call them from the task handler.",
+  ]);
 }
 
-function makeTestNextSteps(
-  result: Awaited<ReturnType<typeof makeTest>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} test in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the starter input, context, and assertion with behavior-specific coverage.
-  Run your app's test command.`;
+function makeUseCaseNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "use case", [
+    "Replace the starter input and output schemas with domain-specific shapes.",
+    "Add a focused use case test before wiring it to an HTTP route.",
+  ]);
 }
 
-function makePortNextSteps(
-  result: Awaited<ReturnType<typeof makePort>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} port in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the starter execute method with domain-specific operations.
-  Replace the generated infrastructure stub with a real port adapter.`;
+function makeTestNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "test", [
+    "Replace the starter input, context, and assertion with behavior-specific coverage.",
+    "Run your app's test command.",
+  ]);
 }
 
-function makePolicyNextSteps(
-  result: Awaited<ReturnType<typeof makePolicy>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} policy in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the starter abilities with domain-specific authorization rules.
-  Register the policy with createGate(...) and bind it in request context.`;
+function makePortNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "port", [
+    "Replace the starter execute method with domain-specific operations.",
+    "Replace the generated infrastructure stub with a real port adapter.",
+  ]);
 }
 
-function makeAdapterNextSteps(
-  result: Awaited<ReturnType<typeof makeAdapter>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} port adapter in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the generated throwing implementation with real infrastructure code.
-  Keep the adapter behind the port interface so use cases stay infrastructure-agnostic.`;
+function makePolicyNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "policy", [
+    "Replace the starter abilities with domain-specific authorization rules.",
+    "Register the policy with createGate(...) and bind it in request context.",
+  ]);
 }
 
-function makeEventNextSteps(
-  result: Awaited<ReturnType<typeof makeEvent>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} event in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the starter payload schema with the domain fact shape.
-  Emit the event from a use case with .emits(...) and events.record(...).`;
+function makeAdapterNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "port adapter", [
+    "Replace the generated throwing implementation with real infrastructure code.",
+    "Keep the adapter behind the port interface so use cases stay infrastructure-agnostic.",
+  ]);
 }
 
-function makeJobNextSteps(result: Awaited<ReturnType<typeof makeJob>>): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} job in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the starter payload and handler with the real background work.
-  Dispatch the job through ctx.ports.jobs from a use case, listener, or schedule.`;
+function makeEventNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "event", [
+    "Replace the starter payload schema with the domain fact shape.",
+    "Emit the event from a use case with .emits(...) and events.record(...).",
+  ]);
 }
 
-function makeFactoryNextSteps(
-  result: Awaited<ReturnType<typeof makeFactory>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} factory in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the starter defaults with realistic test data for this feature.
-  Persist through app-owned repository ports so tests avoid raw database clients.`;
+function makeJobNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "job", [
+    "Replace the starter payload and handler with the real background work.",
+    "Dispatch the job through ctx.ports.jobs from a use case, listener, or schedule.",
+  ]);
 }
 
-function makeSeedNextSteps(
-  result: Awaited<ReturnType<typeof makeSeed>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} seed in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the starter record with idempotent local or demo data.
-  Import the feature seed from your app-owned database seed entrypoint and run it with runSeeds(...).`;
+function makeFactoryNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "factory", [
+    "Replace the starter defaults with realistic test data for this feature.",
+    "Persist through app-owned repository ports so tests avoid raw database clients.",
+  ]);
 }
 
-function makeNotificationNextSteps(
-  result: Awaited<ReturnType<typeof makeNotification>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} notification in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the starter payload and channels with the real user-facing message.
-  Send the notification through ctx.ports.notifications so delivery can run inline in tests and through jobs in production.`;
+function makeSeedNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "seed", [
+    "Replace the starter record with idempotent local or demo data.",
+    "Import the feature seed from your app-owned database seed entrypoint and run it with runSeeds(...).",
+  ]);
 }
 
-function makeListenerNextSteps(
-  result: Awaited<ReturnType<typeof makeListener>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} listener in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
+function makeNotificationNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "notification", [
+    "Replace the starter payload and channels with the real user-facing message.",
+    "Send the notification through ctx.ports.notifications so delivery can run inline in tests and through jobs in production.",
+  ]);
+}
 
-Next steps:
-  Replace the starter handler with the event reaction.
-  Register the listener collection from infrastructure startup.`;
+function makeListenerNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "listener", [
+    "Replace the starter handler with the event reaction.",
+    "Register the listener collection from infrastructure startup.",
+  ]);
 }
 
 function makeScheduleNextSteps(
-  result: Awaited<ReturnType<typeof makeSchedule>>,
+  result: MakeNextStepsResult,
+  options: { route?: boolean } = {},
 ): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} schedule in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the starter payload and handler with the scheduled workflow.
-  Trigger it from a cron route, worker, or provider adapter.`;
+  return makeNextSteps(result, "schedule", [
+    "Replace the starter payload and handler with the scheduled workflow.",
+    ...(options.route
+      ? [
+          "Set CRON_SECRET in your deployment and configure a scheduled request with Authorization: Bearer $CRON_SECRET.",
+        ]
+      : ["Trigger it from a cron route, worker, or provider adapter."]),
+  ]);
 }
 
-function makeUploadNextSteps(
-  result: Awaited<ReturnType<typeof makeUpload>>,
-): string {
-  const changedFiles = [...result.createdFiles, ...result.updatedFiles]
-    .map((file) => `  ${file}`)
-    .join("\n");
-  const skippedFiles = result.skippedFiles
-    .map((file) => `  ${file}`)
-    .join("\n");
-
-  return `${result.dryRun ? "Would create" : "Created"} ${result.name} upload in ${result.targetDir}
-
-Changed files:
-${changedFiles || "  none"}
-${skippedFiles ? `\nSkipped identical files:\n${skippedFiles}` : ""}
-
-Next steps:
-  Replace the starter metadata, constraints, key, authorization, and onComplete behavior.
-  Register the upload in createUploadRouter(...) and expose it with createUploadRoute(...).`;
+function makeUploadNextSteps(result: MakeNextStepsResult): string {
+  return makeNextSteps(result, "upload", [
+    "Replace the starter metadata, constraints, key, authorization, and onComplete behavior.",
+    "Register the upload in createUploadRouter(...) and expose it with createUploadRoute(...).",
+  ]);
 }
 
 export async function main(
@@ -1272,7 +1491,15 @@ export async function main(
 ): Promise<void> {
   if (inputs.length === 0) {
     await run(cli, ["--help"], context);
-    context.process.exitCode = 1;
+    context.process.exitCode = 2;
+    return;
+  }
+
+  // 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") {
+    await writeCompletionProposals(inputs.slice(2), context);
     return;
   }
 
@@ -1280,11 +1507,42 @@ export async function main(
   normalizeExitCode(context.process);
 }
 
+async function writeCompletionProposals(
+  inputs: readonly string[],
+  context: StricliDynamicCommandContext<CliContext>,
+): Promise<void> {
+  try {
+    const proposals = await proposeCompletions(
+      cli,
+      inputs.length === 0 ? [""] : inputs,
+      context,
+    );
+    for (const proposal of proposals) {
+      context.process.stdout.write(`${proposal.completion}\n`);
+    }
+  } catch {
+    // Completion failures must never break the shell; propose nothing.
+  }
+}
+
+// Stricli reports usage and internal failures as negative ExitCode values
+// (-5..-1). Node keeps the negative value on process.exitCode while Bun wraps
+// it to 251..255 on assignment, so both forms map to the usage exit code.
+const stricliErrorExitCodes = new Set([
+  -5, -4, -3, -2, -1, 251, 252, 253, 254, 255,
+]);
+
 function normalizeExitCode(proc: StricliProcess): void {
-  if (
-    typeof proc.exitCode === "number" &&
-    (proc.exitCode < 0 || proc.exitCode > 127)
-  ) {
+  if (typeof proc.exitCode !== "number") {
+    return;
+  }
+
+  if (stricliErrorExitCodes.has(proc.exitCode)) {
+    proc.exitCode = 2;
+    return;
+  }
+
+  if (proc.exitCode > 127) {
     proc.exitCode = 1;
   }
 }
@@ -1307,6 +1565,6 @@ function isCliEntrypoint(): boolean {
 if (isCliEntrypoint()) {
   main().catch((error: unknown) => {
     console.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
+    process.exitCode = 2;
   });
 }