@beignet/cli 0.0.1

package/src/index.ts

@@ -0,0 +1,992 @@
+#!/usr/bin/env node
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import {
+  buildApplication,
+  buildCommand,
+  buildRouteMap,
+  type CommandContext,
+  type FlagParametersForType,
+  run,
+  type StricliDynamicCommandContext,
+  type StricliProcess,
+  text_en,
+} from "@stricli/core";
+import type { CreateOptions } from "./create.js";
+import { createProject } from "./create.js";
+import {
+  applyDoctorFixes,
+  formatDoctor,
+  formatRoutes,
+  inspectApp,
+} from "./inspect.js";
+import { formatLint, lintApp } from "./lint.js";
+import {
+  makeAdapter,
+  makeContract,
+  makeEvent,
+  makeJob,
+  makeListener,
+  makePolicy,
+  makePort,
+  makeResource,
+  makeSchedule,
+  makeTest,
+  makeUseCase,
+} from "./make.js";
+import {
+  type FeatureName,
+  featureChoices,
+  type IntegrationName,
+  integrationChoices,
+  type PackageManager,
+  type PresetName,
+  presetChoices,
+  type TemplateName,
+} from "./templates.js";
+
+export {
+  applyDoctorFixes,
+  type CreateOptions,
+  createProject,
+  formatDoctor,
+  formatLint,
+  formatRoutes,
+  type IntegrationName,
+  inspectApp,
+  lintApp,
+  makeAdapter,
+  makeContract,
+  makeEvent,
+  makeJob,
+  makeListener,
+  makePolicy,
+  makePort,
+  makeResource,
+  makeSchedule,
+  makeTest,
+  makeUseCase,
+};
+
+type CliContext = CommandContext & {
+  readonly process: StricliProcess;
+};
+
+type CreateFlags = {
+  template: TemplateName;
+  preset: PresetName;
+  packageManager?: PackageManager;
+  feature?: readonly FeatureName[];
+  features?: readonly FeatureName[];
+  integration?: readonly IntegrationName[];
+  integrations?: readonly IntegrationName[];
+  force?: boolean;
+};
+
+type MakeFlags = {
+  force?: boolean;
+  dryRun?: boolean;
+  json?: boolean;
+};
+
+type MakeListenerFlags = MakeFlags & {
+  event?: string;
+};
+
+type MakeScheduleFlags = MakeFlags & {
+  cron?: string;
+  timezone?: string;
+  route?: boolean;
+};
+
+type JsonFlags = {
+  json?: boolean;
+};
+
+type DoctorFlags = {
+  json?: boolean;
+  strict?: boolean;
+  fix?: boolean;
+};
+
+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 forceFlag = {
+  kind: "boolean",
+  optional: true,
+  withNegated: false,
+  brief: "Overwrite conflicting files or write into a non-empty directory.",
+} as const;
+
+const dryRunFlag = {
+  kind: "boolean",
+  optional: true,
+  withNegated: false,
+  brief: "Preview generated changes without writing files.",
+} as const;
+
+const jsonFlag = {
+  kind: "boolean",
+  optional: true,
+  withNegated: false,
+  brief: "Print machine-readable JSON.",
+} as const;
+
+const parsedStringFlag = (brief: string) =>
+  ({
+    kind: "parsed",
+    parse: parseString,
+    optional: true,
+    brief,
+  }) as const;
+
+const makeFlagParameters = {
+  force: forceFlag,
+  dryRun: dryRunFlag,
+  json: jsonFlag,
+} satisfies FlagParametersForType<MakeFlags, CliContext>;
+
+const jsonFlagParameters = {
+  json: jsonFlag,
+} satisfies FlagParametersForType<JsonFlags, CliContext>;
+
+const namePositional = {
+  kind: "tuple",
+  parameters: [
+    {
+      parse: parseString,
+      placeholder: "name",
+      brief: "Name for the generated artifact.",
+    },
+  ],
+} as const;
+
+const createCommand = buildCommand<CreateFlags, [string], CliContext>({
+  docs: {
+    brief: "Create a new Beignet app.",
+    fullDescription: `Available features: ${featureChoices.join(", ")}
+
+Available integrations: ${integrationChoices.join(", ")}`,
+  },
+  parameters: {
+    flags: {
+      template: {
+        kind: "enum",
+        values: templateChoices,
+        default: "next",
+        brief: "Template to use.",
+      },
+      preset: {
+        kind: "enum",
+        values: presetChoices,
+        default: "standard",
+        brief: "Starter preset to generate.",
+      },
+      packageManager: {
+        kind: "enum",
+        values: packageManagerChoices,
+        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.",
+      },
+      force: forceFlag,
+    },
+    positional: {
+      kind: "tuple",
+      parameters: [
+        {
+          parse: parseString,
+          placeholder: "directory",
+          brief: "Project directory to create.",
+        },
+      ],
+    },
+  },
+  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 }));
+  },
+});
+
+const routesCommand = buildCommand<JsonFlags, [], CliContext>({
+  docs: {
+    brief: "Inspect registered Beignet routes.",
+  },
+  parameters: {
+    flags: jsonFlagParameters,
+  },
+  async func(flags) {
+    const result = await inspectApp();
+    writeOutput(
+      this,
+      flags.json ? JSON.stringify(result, null, 2) : formatRoutes(result),
+    );
+  },
+});
+
+const doctorCommand = buildCommand<DoctorFlags, [], CliContext>({
+  docs: {
+    brief: "Inspect app wiring and framework conventions.",
+  },
+  parameters: {
+    flags: {
+      json: jsonFlag,
+      strict: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief: "Include CI-oriented warnings and fail on warnings.",
+      },
+      fix: {
+        kind: "boolean",
+        optional: true,
+        withNegated: false,
+        brief: "Apply low-risk fixes before reporting.",
+      },
+    },
+  },
+  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;
+    }
+  },
+});
+
+const lintCommand = buildCommand<JsonFlags, [], CliContext>({
+  docs: {
+    brief: "Check Beignet dependency direction conventions.",
+  },
+  parameters: {
+    flags: jsonFlagParameters,
+  },
+  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;
+    }
+  },
+});
+
+const makeResourceCommand = buildCommand<MakeFlags, [string], CliContext>({
+  docs: {
+    brief: "Generate a feature resource.",
+  },
+  parameters: {
+    flags: makeFlagParameters,
+    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),
+    );
+  },
+});
+
+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>({
+  docs: {
+    brief: "Generate a use case.",
+  },
+  parameters: {
+    flags: makeFlagParameters,
+    positional: namePositional,
+  },
+  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),
+    );
+  },
+});
+
+const makeTestCommand = buildCommand<MakeFlags, [string], CliContext>({
+  docs: {
+    brief: "Generate a use case test.",
+  },
+  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),
+    );
+  },
+});
+
+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),
+    );
+  },
+});
+
+const makeAdapterCommand = buildCommand<MakeFlags, [string], CliContext>({
+  docs: {
+    brief: "Generate a port adapter.",
+  },
+  parameters: {
+    flags: makeFlagParameters,
+    positional: namePositional,
+  },
+  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),
+    );
+  },
+});
+
+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 makeEventCommand = buildCommand<MakeFlags, [string], CliContext>({
+  docs: {
+    brief: "Generate a feature event.",
+  },
+  parameters: {
+    flags: makeFlagParameters,
+    positional: namePositional,
+  },
+  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),
+    );
+  },
+});
+
+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 makeListenerFlagParameters = {
+  ...makeFlagParameters,
+  event: parsedStringFlag("Event to listen to, for example posts/published."),
+} satisfies FlagParametersForType<MakeListenerFlags, CliContext>;
+
+const makeListenerCommand = buildCommand<
+  MakeListenerFlags,
+  [string],
+  CliContext
+>({
+  docs: {
+    brief: "Generate a feature event listener.",
+  },
+  parameters: {
+    flags: makeListenerFlagParameters,
+    positional: namePositional,
+  },
+  async func(flags, name) {
+    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 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.",
+  },
+} satisfies FlagParametersForType<MakeScheduleFlags, CliContext>;
+
+const makeScheduleCommand = buildCommand<
+  MakeScheduleFlags,
+  [string],
+  CliContext
+>({
+  docs: {
+    brief: "Generate a feature schedule.",
+  },
+  parameters: {
+    flags: makeScheduleFlagParameters,
+    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),
+    );
+  },
+});
+
+const makeRoutes = buildRouteMap({
+  docs: {
+    brief: "Generate Beignet app files.",
+  },
+  routes: {
+    adapter: makeAdapterCommand,
+    contract: makeContractCommand,
+    event: makeEventCommand,
+    job: makeJobCommand,
+    listener: makeListenerCommand,
+    policy: makePolicyCommand,
+    port: makePortCommand,
+    resource: makeResourceCommand,
+    schedule: makeScheduleCommand,
+    test: makeTestCommand,
+    useCase: makeUseCaseCommand,
+  },
+});
+
+const rootRoutes = buildRouteMap({
+  docs: {
+    brief: "Beignet CLI",
+    fullDescription: `Create apps, generate framework files, inspect routes, and check Beignet conventions.
+
+create-beignet <directory> is equivalent to beignet create <directory>.`,
+  },
+  routes: {
+    create: createCommand,
+    doctor: doctorCommand,
+    lint: lintCommand,
+    make: makeRoutes,
+    routes: routesCommand,
+  },
+});
+
+const cli = buildApplication(rootRoutes, {
+  name: "beignet",
+  scanner: {
+    caseStyle: "allow-kebab-for-camel",
+  },
+  documentation: {
+    disableAnsiColor: true,
+  },
+  localization: {
+    text: {
+      ...text_en,
+      exceptionWhileRunningCommand: formatCliException,
+      commandErrorResult: (error) => error.message,
+    },
+  },
+  determineExitCode: () => 1,
+});
+
+function uniqueValues<T>(values: readonly T[]): T[] {
+  return [...new Set(values)];
+}
+
+function writeOutput(context: CliContext, output: string): void {
+  context.process.stdout.write(`${output}\n`);
+}
+
+function formatCliException(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function nextSteps(
+  result: Awaited<ReturnType<typeof createProject>>,
+  options: { integrations?: readonly IntegrationName[] } = {},
+): string {
+  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 envRequiredIntegrations =
+    options.integrations?.filter(isEnvRequiredProviderIntegration) ?? [];
+  const envStep =
+    envRequiredIntegrations.length > 0
+      ? "  Fill .env.local for selected provider integrations before starting the app.\n"
+      : "";
+
+  return `Created ${result.name} at ${result.targetDir}
+
+Next steps:
+  cd ${result.targetDir}
+  ${pm} install
+${envFileStep}${envStep}\
+  ${run} dev`;
+}
+
+function isEnvRequiredProviderIntegration(
+  integration: IntegrationName,
+): boolean {
+  return (
+    integration === "inngest" ||
+    integration === "resend" ||
+    integration === "upstash-rate-limit"
+  );
+}
+
+function makeResourceNextSteps(
+  result: Awaited<ReturnType<typeof makeResource>>,
+): 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} resource 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.`;
+}
+
+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 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 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 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 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 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 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 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 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}` : ""}
+
+Next steps:
+  Replace the starter handler with the event reaction.
+  Register the listener collection from infrastructure startup.`;
+}
+
+function makeScheduleNextSteps(
+  result: Awaited<ReturnType<typeof makeSchedule>>,
+): 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.`;
+}
+
+export async function main(
+  inputs = process.argv.slice(2),
+  context: StricliDynamicCommandContext<CliContext> = { process },
+): Promise<void> {
+  if (inputs.length === 0) {
+    await run(cli, ["--help"], context);
+    context.process.exitCode = 1;
+    return;
+  }
+
+  await run(cli, inputs, context);
+  normalizeExitCode(context.process);
+}
+
+function normalizeExitCode(proc: StricliProcess): void {
+  if (
+    typeof proc.exitCode === "number" &&
+    (proc.exitCode < 0 || proc.exitCode > 127)
+  ) {
+    proc.exitCode = 1;
+  }
+}
+
+function isCliEntrypoint(): boolean {
+  const argvPath = process.argv[1];
+  if (!argvPath) {
+    return false;
+  }
+
+  try {
+    return (
+      realpathSync(fileURLToPath(import.meta.url)) === realpathSync(argvPath)
+    );
+  } catch {
+    return false;
+  }
+}
+
+if (isCliEntrypoint()) {
+  main().catch((error: unknown) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}