@beignet/cli 0.0.3 → 0.0.5

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@beignet/cli",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "description": "CLI for creating and maintaining Beignet apps.",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "main": "./dist/lib.js",
+  "types": "./dist/lib.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "types": "./dist/lib.d.ts",
+      "default": "./dist/lib.js"
     },
     "./config": {
       "types": "./dist/config.d.ts",
@@ -16,8 +16,7 @@
     }
   },
   "bin": {
-    "beignet": "dist/index.js",
-    "create-beignet": "dist/create-bin.js"
+    "beignet": "dist/index.js"
   },
   "files": [
     "dist",
@@ -29,7 +28,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsc && chmod +x dist/index.js dist/create-bin.js",
+    "build": "tsc && chmod +x dist/index.js",
     "prepack": "bun run build",
     "dev": "tsc --watch",
     "clean": "rm -rf dist coverage .turbo",
@@ -67,6 +66,8 @@
     "typescript": "^5.3.0"
   },
   "dependencies": {
+    "@beignet/core": "^0.0.5",
+    "@clack/prompts": "^1.5.1",
     "@stricli/core": "^1.2.7",
     "jiti": "^2.7.0"
   }

package/src/ansi.ts

@@ -0,0 +1,30 @@
+/**
+ * Minimal ANSI color helpers for human-readable CLI output.
+ */
+export type AnsiColor = "red" | "yellow" | "cyan" | "green" | "bold";
+
+const ansiEscape = String.fromCharCode(27);
+
+const ansiCodes: Record<AnsiColor, string> = {
+  red: `${ansiEscape}[31m`,
+  yellow: `${ansiEscape}[33m`,
+  cyan: `${ansiEscape}[36m`,
+  green: `${ansiEscape}[32m`,
+  bold: `${ansiEscape}[1m`,
+};
+
+const ansiReset = `${ansiEscape}[0m`;
+
+/**
+ * Create a paint function that wraps text in ANSI codes when enabled and
+ * returns the text unchanged otherwise.
+ */
+export function createPainter(
+  enabled: boolean | undefined,
+): (text: string, color: AnsiColor) => string {
+  if (!enabled) {
+    return (text) => text;
+  }
+
+  return (text, color) => `${ansiCodes[color]}${text}${ansiReset}`;
+}

package/src/choices.ts

@@ -0,0 +1,83 @@
+/**
+ * Choice lists and string-literal types shared by the CLI entrypoint and the
+ * heavier scaffold/generator modules. Keeping them here lets the bin define
+ * flag enums without loading templates or generators at startup.
+ */
+
+/**
+ * Package managers supported by the app template generator.
+ */
+export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
+/**
+ * Application templates supported by the app template generator.
+ */
+export type TemplateName = "next";
+/**
+ * Optional provider integrations that can be scaffolded into a new app.
+ *
+ * Better Auth, Drizzle/libSQL, and pino ship in every starter, so only
+ * integrations that add an external service remain selectable.
+ */
+export type IntegrationName = "inngest" | "resend" | "upstash-rate-limit";
+
+/**
+ * Supported scaffold template choices.
+ */
+export const templateChoices = [
+  "next",
+] as const satisfies readonly TemplateName[];
+
+/**
+ * Supported scaffold package manager choices.
+ */
+export const packageManagerChoices = [
+  "bun",
+  "npm",
+  "pnpm",
+  "yarn",
+] as const satisfies readonly PackageManager[];
+
+/**
+ * Supported scaffold integration choices.
+ */
+export const integrationChoices = [
+  "inngest",
+  "resend",
+  "upstash-rate-limit",
+] as const satisfies readonly IntegrationName[];
+
+/**
+ * Shells supported by `beignet completion install` and `uninstall`.
+ */
+export type CompletionShell = "bash" | "zsh";
+
+/**
+ * Supported completion shell choices.
+ */
+export const completionShellChoices = [
+  "bash",
+  "zsh",
+] as const satisfies readonly CompletionShell[];
+
+/**
+ * Optional artifacts supported by `beignet make feature --with`.
+ */
+export const makeFeatureAddonChoices = [
+  "policy",
+  "event",
+  "events",
+  "job",
+  "jobs",
+  "notification",
+  "notifications",
+  "task",
+  "tasks",
+  "ui",
+  "upload",
+  "uploads",
+] as const;
+
+/**
+ * Optional artifact accepted by `beignet make feature --with`.
+ */
+export type MakeFeatureAddon = (typeof makeFeatureAddonChoices)[number];

package/src/completion.ts

@@ -0,0 +1,169 @@
+/**
+ * Shell completion install/uninstall for the `beignet` bin.
+ *
+ * The shell scripts call the hidden `beignet completion propose` entrypoint,
+ * which prints one proposal per line through stricli's completion engine. The
+ * route map and flag definitions live eagerly in index.ts, so proposals work
+ * without loading any lazy command module.
+ */
+
+import { readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import type { CompletionShell } from "./choices.js";
+
+const beginMarker = "# >>> beignet completions >>>";
+const endMarker = "# <<< beignet completions <<<";
+
+const bashScript = `_beignet_completions() {
+  local -a completions
+  while IFS= read -r line; do
+    [ -n "$line" ] && completions+=("$line")
+  done < <(beignet completion propose "\${COMP_WORDS[@]:1:COMP_CWORD}" 2>/dev/null)
+  COMPREPLY=("\${completions[@]}")
+}
+complete -F _beignet_completions beignet`;
+
+const zshScript = `_beignet_completions() {
+  local -a completions
+  completions=("\${(@f)$(beignet completion propose "\${(@)words[2,CURRENT]}" 2>/dev/null)}")
+  compadd -- "\${completions[@]}"
+}
+compdef _beignet_completions beignet`;
+
+/**
+ * Result of installing or uninstalling shell completions.
+ */
+export type CompletionResult = {
+  schemaVersion: 1;
+  shell: CompletionShell;
+  file: string;
+  status: "installed" | "updated" | "removed" | "not-installed";
+};
+
+type CompletionOptions = {
+  shell?: CompletionShell;
+  /**
+   * Home directory override for tests.
+   */
+  home?: string;
+};
+
+/**
+ * Detect the completion shell from a `$SHELL`-style path.
+ */
+export function detectCompletionShell(
+  shellPath = process.env.SHELL,
+): CompletionShell | undefined {
+  const shellName = shellPath ? path.basename(shellPath) : "";
+  if (shellName === "bash") return "bash";
+  if (shellName === "zsh") return "zsh";
+  return undefined;
+}
+
+/**
+ * The completion script block written to the shell rc file.
+ */
+export function completionScript(shell: CompletionShell): string {
+  return shell === "bash" ? bashScript : zshScript;
+}
+
+/**
+ * The rc file that owns completions for the given shell.
+ */
+export function completionRcFile(
+  shell: CompletionShell,
+  home = homedir(),
+): string {
+  return path.join(home, shell === "bash" ? ".bashrc" : ".zshrc");
+}
+
+/**
+ * Install (or refresh) `beignet` completions in the shell rc file.
+ */
+export async function installCompletions(
+  options: CompletionOptions = {},
+): Promise<CompletionResult> {
+  const shell = resolveShell(options.shell);
+  const file = completionRcFile(shell, options.home);
+  const source = await readRcFile(file);
+  const stripped = removeCompletionBlock(source);
+  const block = `${beginMarker}\n${completionScript(shell)}\n${endMarker}`;
+  const next =
+    stripped === "" ? `${block}\n` : `${trimEnd(stripped)}\n\n${block}\n`;
+
+  await writeFile(file, next);
+
+  return {
+    schemaVersion: 1,
+    shell,
+    file,
+    status: stripped === source ? "installed" : "updated",
+  };
+}
+
+/**
+ * Remove `beignet` completions from the shell rc file.
+ */
+export async function uninstallCompletions(
+  options: CompletionOptions = {},
+): Promise<CompletionResult> {
+  const shell = resolveShell(options.shell);
+  const file = completionRcFile(shell, options.home);
+  const source = await readRcFile(file);
+  const stripped = removeCompletionBlock(source);
+
+  if (stripped === source) {
+    return { schemaVersion: 1, shell, file, status: "not-installed" };
+  }
+
+  await writeFile(file, stripped === "" ? "" : `${trimEnd(stripped)}\n`);
+  return { schemaVersion: 1, shell, file, status: "removed" };
+}
+
+function resolveShell(shell: CompletionShell | undefined): CompletionShell {
+  if (shell) return shell;
+
+  const detected = detectCompletionShell();
+  if (!detected) {
+    throw new Error(
+      `Could not detect a supported shell from $SHELL (${process.env.SHELL ?? "unset"}). Pass --shell bash or --shell zsh.`,
+    );
+  }
+
+  return detected;
+}
+
+async function readRcFile(file: string): Promise<string> {
+  try {
+    return await readFile(file, "utf8");
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as { code?: string }).code === "ENOENT"
+    ) {
+      return "";
+    }
+    throw error;
+  }
+}
+
+function removeCompletionBlock(source: string): string {
+  const beginIndex = source.indexOf(beginMarker);
+  if (beginIndex === -1) return source;
+
+  const endIndex = source.indexOf(endMarker, beginIndex);
+  if (endIndex === -1) return source;
+
+  const before = trimEnd(source.slice(0, beginIndex));
+  const after = source.slice(endIndex + endMarker.length).replace(/^\n+/, "");
+
+  if (before === "") return after;
+  if (after === "") return `${before}\n`;
+  return `${before}\n\n${after}`;
+}
+
+function trimEnd(source: string): string {
+  return source.replace(/\s+$/, "");
+}

package/src/config.ts

@@ -17,6 +17,9 @@ export type BeignetPaths = {
   routes: string;
   server: string;
   openapiRoute: string;
+  tasks: string;
+  outbox: string;
+  schedules: string;
   appContext: string;
   ports: string;
   infrastructurePorts: string;
@@ -24,6 +27,11 @@ export type BeignetPaths = {
   policies: string;
   useCases: string;
   useCaseBuilder: string;
+  listenersBuilder: string;
+  jobsBuilder: string;
+  schedulesBuilder: string;
+  notificationsBuilder: string;
+  tasksBuilder: string;
   tests: string;
 };
 
@@ -54,6 +62,9 @@ export const defaultBeignetConfig: ResolvedBeignetConfig = {
     routes: "app/api",
     server: "server/index.ts",
     openapiRoute: "app/api/openapi/route.ts",
+    tasks: "server/tasks.ts",
+    outbox: "server/outbox.ts",
+    schedules: "server/schedules.ts",
     appContext: "app-context.ts",
     ports: "ports/index.ts",
     infrastructurePorts: "infra/app-ports.ts",
@@ -61,6 +72,11 @@ export const defaultBeignetConfig: ResolvedBeignetConfig = {
     policies: "features",
     useCases: "features",
     useCaseBuilder: "lib/use-case.ts",
+    listenersBuilder: "lib/listeners.ts",
+    jobsBuilder: "lib/jobs.ts",
+    schedulesBuilder: "lib/schedules.ts",
+    notificationsBuilder: "lib/notifications.ts",
+    tasksBuilder: "lib/tasks.ts",
     tests: "tests",
   },
 };

package/src/create-prompts.ts

@@ -0,0 +1,114 @@
+/**
+ * Interactive selection flow for `beignet create`.
+ *
+ * The decision helper is pure so the TTY gating stays unit-testable, and
+ * `@clack/prompts` is loaded lazily inside the prompt flow so non-interactive
+ * runs and CLI startup never pay for it.
+ */
+
+import {
+  type IntegrationName,
+  integrationChoices,
+  type PackageManager,
+} from "./choices.js";
+
+/**
+ * Selections shared by create flags and interactive prompt answers.
+ */
+export type CreateSelections = {
+  directory?: string;
+  api?: boolean;
+  integrations?: readonly IntegrationName[];
+  packageManager?: PackageManager;
+};
+
+type CreatePromptFlags = CreateSelections & {
+  yes?: boolean;
+};
+
+type CreatePromptTty = {
+  stdin: boolean;
+  stdout: boolean;
+};
+
+/**
+ * Decide whether `beignet create` should run the interactive prompt flow.
+ *
+ * Prompts run only on a full TTY, only when `--yes` is absent, and only when
+ * no selection flag was passed. Any explicit api, integration, or package
+ * manager selection means the invocation is scripted, so the non-interactive
+ * path stays byte-identical for agents and CI.
+ */
+export function shouldPromptInteractively(
+  flags: CreatePromptFlags,
+  tty: CreatePromptTty,
+): boolean {
+  if (!tty.stdin || !tty.stdout) return false;
+  if (flags.yes) return false;
+
+  const selectionFlagPassed =
+    flags.api !== undefined ||
+    (flags.integrations?.length ?? 0) > 0 ||
+    flags.packageManager !== undefined;
+
+  return !selectionFlagPassed;
+}
+
+const integrationHints: Record<IntegrationName, string> = {
+  inngest: "Inngest-backed background jobs",
+  resend: "Resend-backed mail provider",
+  "upstash-rate-limit": "Upstash-backed rate limiting",
+};
+
+/**
+ * Run the interactive `beignet create` prompt flow.
+ *
+ * Returns the completed selections, or undefined when the user cancels.
+ */
+export async function promptCreateSelections(
+  initial: CreateSelections,
+): Promise<CreateSelections | undefined> {
+  const prompts = await import("@clack/prompts");
+
+  prompts.intro("beignet create");
+
+  let directory = initial.directory;
+  if (directory === undefined) {
+    const answer = await prompts.text({
+      message: "Where should the app be created?",
+      placeholder: "my-app",
+      validate: (value) =>
+        value === undefined || value.trim() === ""
+          ? "Enter a project directory."
+          : undefined,
+    });
+    if (prompts.isCancel(answer)) return undefined;
+    directory = answer;
+  }
+
+  const api = await prompts.confirm({
+    message: "API-only app (no UI shell)?",
+    initialValue: false,
+  });
+  if (prompts.isCancel(api)) return undefined;
+
+  const integrations = await prompts.multiselect<IntegrationName>({
+    message: "Add provider integrations? (press enter to skip)",
+    options: integrationChoices.map((integration) => ({
+      value: integration,
+      label: integration,
+      hint: integrationHints[integration],
+    })),
+    required: false,
+  });
+  if (prompts.isCancel(integrations)) return undefined;
+
+  prompts.outro(`Creating ${directory}`);
+
+  return {
+    directory,
+    api,
+    integrations,
+    packageManager: initial.packageManager,
+  };
+}

package/src/create.ts

@@ -1,16 +1,13 @@
-import { readFileSync } from "node:fs";
 import { mkdir, readdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import {
-  type FeatureName,
-  featureChoices,
   getTemplateFiles,
   type IntegrationName,
   integrationChoices,
   type PackageManager,
-  type PresetName,
   type TemplateName,
-} from "./templates.js";
+} from "./templates/index.js";
+import { getCliVersion } from "./version.js";
 
 /**
  * Options for creating a new Beignet app.
@@ -19,26 +16,31 @@ export type CreateOptions = {
   name: string;
   cwd?: string;
   template?: TemplateName;
-  preset?: PresetName;
-  features?: FeatureName[];
+  /**
+   * Scaffold an API-only app without the UI shell.
+   */
+  api?: boolean;
   packageManager?: PackageManager;
   integrations?: IntegrationName[];
   force?: boolean;
+  dryRun?: boolean;
   beignetVersion?: string;
 };
 
 /**
- * Result returned after a new app is scaffolded.
+ * Result returned after a new app is scaffolded or previewed.
  */
 export type CreateResult = {
+  schemaVersion: 1;
   name: string;
   targetDir: string;
+  dryRun: boolean;
   files: string[];
   packageManager: PackageManager;
 };
 
 /**
- * Create a Beignet app from a starter template.
+ * Create a Beignet app from the starter template.
  */
 export async function createProject(
   options: CreateOptions,
@@ -48,9 +50,8 @@ export async function createProject(
   const targetDir = path.resolve(cwd, options.name);
   const packageManager = options.packageManager ?? "bun";
   const template = options.template ?? "next";
-  const preset = options.preset ?? "standard";
-  const features = resolveFeatures(preset, options.features ?? []);
-  const integrations = resolveIntegrations(preset, options.integrations ?? []);
+  const api = Boolean(options.api);
+  const integrations = resolveIntegrations(options.integrations ?? []);
 
   if (template !== "next") {
     throw new Error(
@@ -58,90 +59,65 @@ export async function createProject(
     );
   }
 
+  const dryRun = Boolean(options.dryRun);
+
   await assertCanWrite(targetDir, Boolean(options.force));
-  await mkdir(targetDir, { recursive: true });
 
   const files = getTemplateFiles({
     name,
     packageManager,
     beignetVersion: options.beignetVersion ?? getDefaultBeignetVersion(),
-    preset,
-    features,
+    api,
     integrations,
   });
 
-  for (const file of files) {
-    const destination = path.join(targetDir, file.path);
-    await mkdir(path.dirname(destination), { recursive: true });
-    await writeFile(destination, file.content);
+  if (!dryRun) {
+    await mkdir(targetDir, { recursive: true });
+
+    for (const file of files) {
+      const destination = path.join(targetDir, file.path);
+      await mkdir(path.dirname(destination), { recursive: true });
+      await writeFile(destination, file.content);
+    }
   }
 
   return {
+    schemaVersion: 1,
     name,
     targetDir,
+    dryRun,
     files: files.map((file) => file.path),
     packageManager,
   };
 }
 
-function resolveFeatures(
-  preset: PresetName,
-  explicitFeatures: FeatureName[],
-): FeatureName[] {
-  const features = new Set<FeatureName>();
-
-  if (preset === "standard") {
-    for (const feature of featureChoices) {
-      features.add(feature);
-    }
-  }
-
-  for (const feature of explicitFeatures) {
-    features.add(feature);
-  }
-
-  if (features.has("forms")) {
-    features.add("react-query");
-  }
-  if (features.has("react-query")) {
-    features.add("client");
-  }
-
-  return featureChoices.filter((feature) => features.has(feature));
-}
+/**
+ * Providers that ship in every starter. They used to be `--integrations`
+ * choices, so passing them gets a pointed error instead of a generic one.
+ */
+const baseProviderNames = new Set(["better-auth", "drizzle-turso", "pino"]);
 
 function resolveIntegrations(
-  preset: PresetName,
   explicitIntegrations: IntegrationName[],
 ): IntegrationName[] {
-  const integrations = new Set<IntegrationName>();
-
-  if (preset === "standard") {
-    integrations.add("better-auth");
-    integrations.add("drizzle-turso");
-    integrations.add("pino");
-  }
-
   for (const integration of explicitIntegrations) {
-    integrations.add(integration);
+    if (baseProviderNames.has(integration)) {
+      throw new Error(
+        `${integration} is part of every Beignet starter and no longer an --integrations choice.`,
+      );
+    }
   }
 
+  const integrations = new Set<IntegrationName>(explicitIntegrations);
+
   return integrationChoices.filter((integration) =>
     integrations.has(integration),
   );
 }
 
 function getDefaultBeignetVersion(): string {
-  try {
-    const packageJsonUrl = new URL("../package.json", import.meta.url);
-    const packageJson = JSON.parse(readFileSync(packageJsonUrl, "utf8")) as {
-      version?: string;
-    };
-
-    return packageJson.version ? `^${packageJson.version}` : "latest";
-  } catch {
-    return "latest";
-  }
+  const version = getCliVersion();
+  return version === "0.0.0" ? "latest" : `^${version}`;
 }
 
 function normalizeProjectName(name: string): string {