@beignet/cli 0.0.3 → 0.0.5

package/src/templates/base.ts

@@ -0,0 +1,377 @@
+import { shadcnDependencies, shadcnDevDependencies } from "./shadcn.js";
+import {
+  externalVersions,
+  hasIntegration,
+  integrationDeps,
+  json,
+  packageRunner,
+  type TemplateContext,
+} from "./shared.js";
+import { shellDependencies, shellDevDependencies } from "./shell.js";
+
+export function packageJson(ctx: TemplateContext): string {
+  const dependencies: Record<string, string> = {
+    "@beignet/core": ctx.beignetVersion,
+    "@beignet/devtools": ctx.beignetVersion,
+    "@beignet/next": ctx.beignetVersion,
+    "@beignet/provider-auth-better-auth": ctx.beignetVersion,
+    "@beignet/provider-drizzle-turso": ctx.beignetVersion,
+    "@beignet/provider-logger-pino": ctx.beignetVersion,
+    "@libsql/client": externalVersions.libsqlClient,
+    "better-auth": externalVersions.betterAuth,
+    "drizzle-orm": externalVersions.drizzleOrm,
+    next: externalVersions.next,
+    pino: externalVersions.pino,
+    react: externalVersions.react,
+    "react-dom": externalVersions.reactDom,
+    zod: externalVersions.zod,
+  };
+
+  if (!ctx.api) {
+    dependencies["@beignet/react-query"] = ctx.beignetVersion;
+    dependencies["@beignet/react-hook-form"] = ctx.beignetVersion;
+    dependencies["@hookform/resolvers"] = externalVersions.hookformResolvers;
+    dependencies["@tanstack/react-query"] = externalVersions.tanstackReactQuery;
+    dependencies["react-hook-form"] = externalVersions.reactHookForm;
+
+    for (const [name, version] of Object.entries(shadcnDependencies)) {
+      dependencies[name] = version;
+    }
+    for (const [name, version] of Object.entries(shellDependencies)) {
+      dependencies[name] = version;
+    }
+  }
+
+  for (const integration of ctx.integrations) {
+    for (const [name, version] of Object.entries(
+      integrationDeps[integration],
+    )) {
+      dependencies[name] = version || ctx.beignetVersion;
+    }
+  }
+
+  const devDependencies: Record<string, string> = {
+    "@beignet/cli": ctx.beignetVersion,
+    "@beignet/web": ctx.beignetVersion,
+    "@types/bun": externalVersions.typesBun,
+    "@types/node": externalVersions.typesNode,
+    "@types/react": externalVersions.typesReact,
+    "@types/react-dom": externalVersions.typesReactDom,
+    "drizzle-kit": externalVersions.drizzleKit,
+    typescript: externalVersions.typescript,
+  };
+
+  if (!ctx.api) {
+    for (const [name, version] of Object.entries(shadcnDevDependencies)) {
+      devDependencies[name] = version;
+    }
+    for (const [name, version] of Object.entries(shellDevDependencies)) {
+      devDependencies[name] = version;
+    }
+  }
+
+  const scripts: Record<string, string> = {
+    beignet: "beignet",
+    dev: "next dev",
+    build: "next build",
+    start: "next start",
+    test: "bun test",
+    typecheck: "tsc --noEmit",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "drizzle-kit migrate",
+    "db:reset": "bun infra/db/reset.ts",
+  };
+
+  return json({
+    name: ctx.name,
+    version: "0.1.0",
+    private: true,
+    type: "module",
+    scripts,
+    dependencies: sortRecord(dependencies),
+    devDependencies: sortRecord(devDependencies),
+  });
+}
+
+function sortRecord(record: Record<string, string>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(record).sort(([left], [right]) => left.localeCompare(right)),
+  );
+}
+
+export function readme(ctx: TemplateContext): string {
+  const install = `${ctx.packageManager} install`;
+  const run =
+    ctx.packageManager === "npm"
+      ? "npm run dev"
+      : `${ctx.packageManager} run dev`;
+  const build =
+    ctx.packageManager === "npm"
+      ? "npm run build"
+      : `${ctx.packageManager} run build`;
+  const start =
+    ctx.packageManager === "npm"
+      ? "npm run start"
+      : `${ctx.packageManager} run start`;
+  const test =
+    ctx.packageManager === "npm"
+      ? "npm run test"
+      : `${ctx.packageManager} run test`;
+  const typecheck =
+    ctx.packageManager === "npm"
+      ? "npm run typecheck"
+      : `${ctx.packageManager} run typecheck`;
+  const cli = packageRunner(ctx);
+
+  const firstOpen = ctx.api
+    ? "Open http://localhost:3000 for the API landing page. The todos API under `/api/todos` requires a signed-in Better Auth user."
+    : "Open http://localhost:3000/sign-up, create the first account, and you land in the app shell with the todos worked example.";
+
+  const shellMap = ctx.api
+    ? ""
+    : `- \`app/(auth)/\` and \`app/(app)/\` own the sign-in/sign-up pages and the authenticated shell.
+- \`components/\` owns the app shell and shadcn/ui primitives.
+- \`client/\` owns the typed API client, React Query helpers, and the Better Auth client.
+`;
+
+  return `# ${ctx.name}
+
+Beignet app scaffolded with \`@beignet/cli\`.
+
+## Getting started
+
+\`\`\`bash
+${install}
+cp .env.example .env.local
+\`\`\`
+
+## Prepare the database
+
+\`\`\`bash
+${cli} db migrate
+\`\`\`
+
+The starter ships its initial Drizzle migration in \`drizzle/\`, so the first run only applies it. After you change \`infra/db/schema/\`, run \`${cli} db generate\` and \`${cli} db migrate\` together.
+
+## Start the app
+
+\`\`\`bash
+${run}
+\`\`\`
+
+${firstOpen}
+
+## First checks
+
+\`\`\`bash
+# in another terminal
+${cli} routes
+${cli} lint
+${cli} doctor
+${test}
+${typecheck}
+\`\`\`
+
+\`routes\` shows the contracts Beignet can inspect. \`lint\` checks dependency direction. \`doctor\` catches route, OpenAPI, and resource drift.
+
+## Build for production
+
+\`\`\`bash
+${build}
+${start}
+\`\`\`
+
+## Generate a feature
+
+\`\`\`bash
+${cli} make feature projects
+${cli} db generate
+${cli} db migrate
+${test}
+${typecheck}
+${cli} lint
+${cli} doctor
+\`\`\`
+
+\`make feature\` creates a contract-to-test vertical slice with Drizzle schema and repository files, so regenerate and migrate the database before running the app against the new feature.
+
+## App map
+
+- \`features/todos/contracts.ts\` owns the HTTP contract and reuses shared feature schemas.
+- \`features/todos/schemas.ts\` owns shared DTO and validation schemas used by contracts, use cases, ports, tests, and clients.
+- \`features/todos/use-cases/\` owns application behavior and validation. Every todos use case requires a signed-in user.
+- \`features/todos/policy.ts\` owns the ownership rules registered with \`createGate(...)\`.
+- \`features/shared/errors.ts\` keeps application errors and route-owned error schemas together.
+- \`ports/\` defines app-owned dependencies.
+- \`infra/\` implements ports for the selected runtime.
+- \`infra/db/schema/\` contains the Drizzle schema, \`drizzle/\` contains the checked-in migrations, and \`infra/todos/\` contains the durable todo repository adapter.
+- \`server/routes.ts\` keeps the central route registry and OpenAPI contract list.
+- \`server/context.ts\` declares the context blueprint shared by the server and route tests.
+- \`server/providers.ts\` wires devtools, Better Auth, pino, Drizzle/libSQL, and the starter database provider.
+- \`lib/env.ts\` validates deployment configuration at startup.
+- \`lib/auth.ts\` exposes \`requireUser(ctx)\` for protected use cases.
+- \`lib/better-auth.ts\` owns Better Auth setup and keeps provider-specific auth details outside use cases.
+${shellMap}
+## Before deploying
+
+- Create a Turso database or keep \`TURSO_DB_URL=file:local.db\` for local libSQL development.
+- Run \`${cli} db generate\` and \`${cli} db migrate\` after changing the Drizzle schema.
+- Run \`${cli} db reset\` to rebuild a local SQLite database from the checked-in migrations.
+- Remove \`DEVTOOLS_ENABLED=true\` in production unless you add authentication and stricter redaction.
+- Set \`APP_URL\`, \`BETTER_AUTH_SECRET\`, \`LOG_LEVEL\`, and service-specific integration variables in your hosting environment.
+- Set \`BETTER_AUTH_TRUSTED_ORIGINS\` before serving auth across multiple origins.
+- Review the starter authorization policy before exposing user-owned data.
+${ctx.integrations.length > 0 ? "\nSee `docs/integrations.md` for setup notes.\n" : ""}`;
+}
+
+export function integrationsDoc(ctx: TemplateContext): string {
+  const lines = [
+    "# Integrations",
+    "",
+    "The starter app added dependencies for the integrations you selected. Runtime providers are wired in `server/providers.ts` when Beignet can do so safely; integrations that need app-owned setup list their follow-up steps below.",
+    "",
+  ];
+
+  for (const integration of ctx.integrations) {
+    if (integration === "inngest") {
+      lines.push(
+        "## Inngest",
+        "",
+        "- Package: `@beignet/core` (`@beignet/core/events`, `@beignet/core/jobs`)",
+        "- Package: `@beignet/provider-inngest`",
+        "- Peer dependency: `inngest`",
+        "- The starter wires `inngestProvider` in `server/providers.ts`.",
+        "- Define jobs with `defineJob(...)` and dispatch them through `ctx.ports.jobs.dispatch(...)`.",
+        "- Keep direct Inngest client usage inside infrastructure code unless you intentionally add an app-owned escape-hatch port.",
+        "",
+      );
+    }
+
+    if (integration === "resend") {
+      lines.push(
+        "## Resend mail",
+        "",
+        "- Package: `@beignet/provider-mail-resend`",
+        "- Peer dependency: `resend`",
+        "- The starter wires `mailResendProvider` in `server/providers.ts`.",
+        "- `.env.example` ships dev placeholders so the app boots; set real `RESEND_API_KEY` and `RESEND_FROM` values before sending mail.",
+        "",
+      );
+    }
+
+    if (integration === "upstash-rate-limit") {
+      lines.push(
+        "## Upstash rate limit",
+        "",
+        "- Package: `@beignet/provider-rate-limit-upstash`",
+        "- Peer dependencies: `@upstash/ratelimit` and `@upstash/redis`",
+        "- The starter wires `upstashRateLimitProvider` in `server/providers.ts` and adds `rateLimit: RateLimitPort` to `AppPorts`.",
+        "- `.env.example` ships dev placeholders so the app boots; set real `UPSTASH_REDIS_REST_URL` and `UPSTASH_REDIS_REST_TOKEN` values before rate limiting requests.",
+        "",
+      );
+    }
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export function envExample(ctx: TemplateContext): string {
+  const lines = [
+    "# Copy to .env.local and fill in values for your app.",
+    "APP_URL=http://localhost:3000",
+    "",
+    "# Dev-only default; remove in production.",
+    "DEVTOOLS_ENABLED=true",
+    "",
+    "LOG_LEVEL=info",
+    "LOG_FORMAT=json",
+    `LOG_SERVICE=${ctx.name}`,
+    "",
+    "# Use file:local.db for local libSQL or libsql://... for Turso cloud.",
+    "TURSO_DB_URL=file:local.db",
+    "# TURSO_DB_AUTH_TOKEN=",
+    "",
+    "BETTER_AUTH_SECRET=local-dev-better-auth-secret-change-me",
+    "BETTER_AUTH_URL=http://localhost:3000",
+    "# BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:3000",
+    "",
+  ];
+
+  if (hasIntegration(ctx, "inngest")) {
+    lines.push("INNGEST_APP_NAME=beignet-app", "# INNGEST_EVENT_KEY=", "");
+  }
+
+  if (hasIntegration(ctx, "resend")) {
+    lines.push(
+      "# Dev placeholders keep the app bootable; set real Resend values before sending mail.",
+      "RESEND_API_KEY=dev-placeholder-change-me",
+      "RESEND_FROM=Beignet Starter <noreply@example.com>",
+      "",
+    );
+  }
+
+  if (hasIntegration(ctx, "upstash-rate-limit")) {
+    lines.push(
+      "# Dev placeholders keep the app bootable; set real Upstash values before rate limiting.",
+      "UPSTASH_REDIS_REST_URL=https://dev-placeholder.upstash.io",
+      "UPSTASH_REDIS_REST_TOKEN=dev-placeholder-change-me",
+      "UPSTASH_PREFIX=beignet:ratelimit",
+      "",
+    );
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+const files = {
+  gitignore: `.next
+node_modules
+dist
+coverage
+.env
+.env.local
+local.db
+local.db-*
+`,
+  nextEnv: `/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// This file should not be edited.
+`,
+  nextConfig: `/** @type {import("next").NextConfig} */
+const nextConfig = {};
+
+export default nextConfig;
+`,
+  tsconfig: json({
+    compilerOptions: {
+      target: "ES2017",
+      lib: ["dom", "dom.iterable", "esnext"],
+      allowJs: true,
+      skipLibCheck: true,
+      strict: true,
+      noEmit: true,
+      esModuleInterop: true,
+      module: "esnext",
+      moduleResolution: "bundler",
+      resolveJsonModule: true,
+      isolatedModules: true,
+      jsx: "react-jsx",
+      incremental: true,
+      plugins: [{ name: "next" }],
+      paths: {
+        "@/*": ["./*"],
+      },
+    },
+    include: [
+      "next-env.d.ts",
+      "**/*.ts",
+      "**/*.tsx",
+      ".next/types/**/*.ts",
+      ".next/dev/types/**/*.ts",
+    ],
+    exclude: ["node_modules"],
+  }),
+};
+
+export { files as baseFiles };