@beignet/cli 0.0.3 → 0.0.5

package/src/templates/index.ts

@@ -0,0 +1,148 @@
+export type {
+  IntegrationName,
+  PackageManager,
+  TemplateName,
+} from "../choices.js";
+export { integrationChoices } from "../choices.js";
+export type { TemplateContext, TemplateFile } from "./shared.js";
+
+import {
+  baseFiles,
+  envExample,
+  integrationsDoc,
+  packageJson,
+  readme,
+} from "./base.js";
+import { dbFiles } from "./db.js";
+import {
+  infrastructurePorts,
+  ports,
+  serverFiles,
+  serverProviders,
+} from "./server.js";
+import { shadcnTemplateFiles } from "./shadcn.js";
+import type { TemplateContext, TemplateFile } from "./shared.js";
+import { shellTemplateFiles } from "./shell.js";
+import { todosFiles } from "./todos.js";
+
+/**
+ * Render all template files for a new Beignet app.
+ *
+ * There is one starter: a full-stack app with a typed API, Better Auth,
+ * Drizzle/libSQL persistence, pino logging, devtools, and a shadcn UI shell.
+ * `ctx.api` swaps the UI shell for a minimal API landing page and a reduced
+ * typed client.
+ */
+export function getTemplateFiles(ctx: TemplateContext): TemplateFile[] {
+  const templateFiles: TemplateFile[] = [
+    { path: "package.json", content: packageJson(ctx) },
+    { path: "README.md", content: readme(ctx) },
+    { path: ".gitignore", content: baseFiles.gitignore },
+    { path: ".env.example", content: envExample(ctx) },
+    { path: "next-env.d.ts", content: baseFiles.nextEnv },
+    { path: "next.config.js", content: baseFiles.nextConfig },
+    { path: "tsconfig.json", content: baseFiles.tsconfig },
+    { path: "app-context.ts", content: serverFiles.appContext },
+    {
+      path: "app/api/[[...path]]/route.ts",
+      content: serverFiles.apiCatchAllRoute,
+    },
+    { path: "app/api/health/route.ts", content: serverFiles.healthRoute },
+    {
+      path: "app/api/devtools/[[...path]]/route.ts",
+      content: serverFiles.devtoolsRoute,
+    },
+    { path: "app/api/openapi/route.ts", content: serverFiles.openApiRoute },
+    {
+      path: "app/api/auth/[...all]/route.ts",
+      content: serverFiles.authRoute,
+    },
+    { path: "features/shared/errors.ts", content: serverFiles.sharedErrors },
+    { path: "features/todos/contracts.ts", content: todosFiles.contracts },
+    { path: "features/todos/schemas.ts", content: todosFiles.schemas },
+    { path: "features/todos/routes.ts", content: todosFiles.routes },
+    { path: "features/todos/policy.ts", content: todosFiles.policy },
+    { path: "features/todos/ports.ts", content: todosFiles.ports },
+    {
+      path: "features/todos/use-cases/create-todo.ts",
+      content: todosFiles.createTodoUseCase,
+    },
+    {
+      path: "features/todos/use-cases/delete-todo.ts",
+      content: todosFiles.deleteTodoUseCase,
+    },
+    {
+      path: "features/todos/use-cases/list-todos.ts",
+      content: todosFiles.listTodosUseCase,
+    },
+    {
+      path: "features/todos/use-cases/update-todo.ts",
+      content: todosFiles.updateTodoUseCase,
+    },
+    {
+      path: "features/todos/use-cases/index.ts",
+      content: todosFiles.useCasesIndex,
+    },
+    {
+      path: "features/todos/tests/helpers.ts",
+      content: todosFiles.testHelpers,
+    },
+    {
+      path: "features/todos/tests/todos.test.ts",
+      content: todosFiles.useCaseTest,
+    },
+    {
+      path: "features/todos/tests/routes.test.ts",
+      content: todosFiles.routesTest,
+    },
+    { path: "ports/index.ts", content: ports(ctx) },
+    { path: "ports/auth.ts", content: serverFiles.authPort },
+    { path: "infra/app-ports.ts", content: infrastructurePorts(ctx) },
+    { path: "infra/db/provider.ts", content: dbFiles.dbProvider },
+    { path: "infra/db/repositories.ts", content: dbFiles.dbRepositories },
+    { path: "infra/db/reset.ts", content: dbFiles.dbReset },
+    { path: "infra/db/test-database.ts", content: dbFiles.dbTestDatabase },
+    { path: "infra/db/schema/index.ts", content: dbFiles.dbSchema },
+    {
+      path: "infra/todos/drizzle-todo-repository.ts",
+      content: dbFiles.drizzleTodoRepository,
+    },
+    { path: "drizzle.config.ts", content: dbFiles.drizzleConfig },
+    { path: "drizzle/0000_starter.sql", content: dbFiles.starterMigrationSql },
+    {
+      path: "drizzle/meta/_journal.json",
+      content: dbFiles.starterMigrationJournal,
+    },
+    {
+      path: "drizzle/meta/0000_snapshot.json",
+      content: dbFiles.starterMigrationSnapshot,
+    },
+    { path: "lib/env.ts", content: serverFiles.env },
+    { path: "lib/auth.ts", content: serverFiles.authHelpers },
+    { path: "lib/better-auth.ts", content: serverFiles.betterAuth },
+    { path: "lib/use-case.ts", content: serverFiles.useCaseBuilder },
+    { path: "server/index.ts", content: serverFiles.server },
+    { path: "server/context.ts", content: serverFiles.serverContext },
+    { path: "server/routes.ts", content: serverFiles.serverRoutes },
+    { path: "server/providers.ts", content: serverProviders(ctx) },
+  ];
+
+  if (ctx.api) {
+    templateFiles.push(
+      { path: "app/layout.tsx", content: serverFiles.apiLayout },
+      { path: "app/page.tsx", content: serverFiles.apiPage },
+      { path: "client/index.ts", content: serverFiles.apiClientIndex },
+    );
+  } else {
+    templateFiles.push(...shadcnTemplateFiles(), ...shellTemplateFiles(ctx));
+  }
+
+  if (ctx.integrations.length > 0) {
+    templateFiles.push({
+      path: "docs/integrations.md",
+      content: integrationsDoc(ctx),
+    });
+  }
+
+  return templateFiles;
+}

package/src/templates/server.ts

@@ -0,0 +1,528 @@
+import { hasIntegration, type TemplateContext } from "./shared.js";
+
+export function serverProviders(ctx: TemplateContext): string {
+  const imports = [
+    'import type { beignetServerOnly } from "@beignet/core/server-only";',
+    'import { createDevtoolsProvider } from "@beignet/devtools";',
+    'import { createAuthBetterAuthProvider } from "@beignet/provider-auth-better-auth";',
+    'import { createDrizzleTursoProvider } from "@beignet/provider-drizzle-turso";',
+    hasIntegration(ctx, "inngest")
+      ? 'import { inngestProvider } from "@beignet/provider-inngest";'
+      : undefined,
+    'import { loggerPinoProvider } from "@beignet/provider-logger-pino";',
+    hasIntegration(ctx, "resend")
+      ? 'import { mailResendProvider } from "@beignet/provider-mail-resend";'
+      : undefined,
+    hasIntegration(ctx, "upstash-rate-limit")
+      ? 'import { upstashRateLimitProvider } from "@beignet/provider-rate-limit-upstash";'
+      : undefined,
+    'import * as schema from "@/infra/db/schema";',
+    'import { starterDatabaseProvider } from "@/infra/db/provider";',
+    'import { auth } from "@/lib/better-auth";',
+    'import type { AuthSessionMetadata, AuthUser } from "@/ports/auth";',
+  ].filter((line): line is string => Boolean(line));
+
+  const entries = [
+    "\tcreateDevtoolsProvider(),",
+    "\tcreateAuthBetterAuthProvider<AuthUser, AuthSessionMetadata>(auth),",
+    "\tloggerPinoProvider,",
+    "\tdrizzleTursoProvider,",
+    "\tstarterDatabaseProvider,",
+    hasIntegration(ctx, "inngest") ? "\tinngestProvider," : undefined,
+    hasIntegration(ctx, "resend") ? "\tmailResendProvider," : undefined,
+    hasIntegration(ctx, "upstash-rate-limit")
+      ? "\tupstashRateLimitProvider,"
+      : undefined,
+  ].filter((entry): entry is string => Boolean(entry));
+
+  return `${imports.join("\n")}
+
+const drizzleTursoProvider = createDrizzleTursoProvider({ schema });
+
+export const providers = [
+${entries.join("\n")}
+] as const;
+`;
+}
+
+export function ports(ctx: TemplateContext): string {
+  const usesInngest = hasIntegration(ctx, "inngest");
+  const usesResend = hasIntegration(ctx, "resend");
+  const usesUpstash = hasIntegration(ctx, "upstash-rate-limit");
+  const coreImports = [
+    "\tBoundGate,",
+    "\tGatePort,",
+    ...(usesInngest ? ["\tJobDispatcherPort,"] : []),
+    "\tLoggerPort,",
+    ...(usesUpstash ? ["\tRateLimitPort,"] : []),
+    "\tUnitOfWorkPort,",
+  ];
+  const mailImport = usesResend
+    ? 'import type { MailerPort } from "@beignet/core/mail";\n'
+    : "";
+
+  return `import type { IdempotencyPort } from "@beignet/core/idempotency";
+${mailImport}import type {
+${coreImports.join("\n")}
+} from "@beignet/core/ports";
+import type { AuthorizationContext, todoPolicy } from "@/features/todos/policy";
+import type { TodoRepository } from "@/features/todos/ports";
+import type { AuthPort } from "./auth";
+
+export type AppTransactionPorts = {
+	idempotency: IdempotencyPort;
+	todos: TodoRepository;
+};
+
+export type AppGate = BoundGate<[typeof todoPolicy]>;
+
+export type AppPorts = {
+	auth: AuthPort;
+	gate: GatePort<AuthorizationContext, [typeof todoPolicy]>;
+	idempotency: IdempotencyPort;
+${usesInngest ? "\tjobs: JobDispatcherPort;\n" : ""}	logger: LoggerPort;
+${usesResend ? "\tmailer: MailerPort;\n" : ""}${usesUpstash ? "\trateLimit: RateLimitPort;\n" : ""}	todos: TodoRepository;
+	uow: UnitOfWorkPort<AppTransactionPorts>;
+};
+`;
+}
+
+export function infrastructurePorts(ctx: TemplateContext): string {
+  const deferred = [
+    '\t\t"auth",',
+    '\t\t"idempotency",',
+    hasIntegration(ctx, "inngest") ? '\t\t"jobs",' : undefined,
+    '\t\t"logger",',
+    hasIntegration(ctx, "resend") ? '\t\t"mailer",' : undefined,
+    hasIntegration(ctx, "upstash-rate-limit") ? '\t\t"rateLimit",' : undefined,
+    '\t\t"todos",',
+    '\t\t"uow",',
+  ].filter((entry): entry is string => Boolean(entry));
+
+  return `import { createGate, definePorts } from "@beignet/core/ports";
+import { todoPolicy } from "@/features/todos/policy";
+import { appError } from "@/features/shared/errors";
+import type { AppPorts } from "@/ports";
+
+const gate = createGate({
+	policies: [todoPolicy],
+	onDeny(decision) {
+		return appError("Forbidden", {
+			message: decision.reason ?? "Forbidden",
+			details: decision.details,
+		});
+	},
+});
+
+/**
+ * App ports the server boots with.
+ *
+ * Bound ports are app-owned. Every deferred key is contributed by a provider
+ * in server/providers.ts during startup; createNextServer(...) fails boot if
+ * any of them is still unbound after providers have started.
+ */
+export const appPorts = definePorts<AppPorts>()({
+	bound: {
+		gate,
+	},
+	deferred: [
+${deferred.join("\n")}
+	],
+});
+`;
+}
+
+const files = {
+  env: `import { createEnv } from "@beignet/core/config";
+import { z } from "zod";
+
+const BooleanEnv = z.enum(["true", "false"]).transform((value) => value === "true");
+
+export const env = createEnv({
+	server: {
+		NODE_ENV: z
+			.enum(["development", "test", "production"])
+			.default("development"),
+		APP_URL: z.string().url().default("http://localhost:3000"),
+		DEVTOOLS_ENABLED: BooleanEnv.optional(),
+		BETTER_AUTH_SECRET: z
+			.string()
+			.min(32)
+			.default("local-dev-better-auth-secret-change-me"),
+		BETTER_AUTH_URL: z.string().url().default("http://localhost:3000"),
+		BETTER_AUTH_TRUSTED_ORIGINS: z.string().optional(),
+		TURSO_DB_URL: z.string().default("file:local.db"),
+		TURSO_DB_AUTH_TOKEN: z.string().optional(),
+		LOG_LEVEL: z
+			.enum(["trace", "debug", "info", "warn", "error", "fatal"])
+			.default("info"),
+		LOG_FORMAT: z.enum(["pretty", "json"]).default("json"),
+		LOG_SERVICE: z.string().default("beignet-app"),
+	},
+	runtimeEnv: process.env,
+});
+
+export const isProduction = env.NODE_ENV === "production";
+
+export const isDevtoolsEnabled =
+	env.DEVTOOLS_ENABLED ?? process.env.NODE_ENV !== "production";
+`,
+  appContext: `import type { ActivityActor, ActivityTenant } from "@beignet/core/ports";
+import type { InferProviderPorts } from "@beignet/core/providers";
+import type { TraceContext } from "@beignet/core/tracing";
+import type { AppGate, AppPorts } from "@/ports";
+import type { AuthSession } from "@/ports/auth";
+import type { providers } from "@/server/providers";
+
+/**
+ * App ports plus the ports contributed by the server's providers at startup.
+ */
+export type AppRuntimePorts = AppPorts & InferProviderPorts<typeof providers>;
+
+export type AppContext = {
+	requestId: string;
+	actor: ActivityActor;
+	auth: AuthSession | null;
+	gate: AppGate;
+	ports: AppRuntimePorts;
+	tenant?: ActivityTenant;
+} & Partial<TraceContext>;
+`,
+  sharedErrors: `import { createAppError, defineErrors } from "@beignet/core/errors";
+
+export const errors = defineErrors({
+	Unauthorized: {
+		code: "UNAUTHORIZED",
+		status: 401,
+		message: "Authentication required",
+	},
+	Forbidden: {
+		code: "FORBIDDEN",
+		status: 403,
+		message: "Forbidden",
+	},
+	TodoNotFound: {
+		code: "TODO_NOT_FOUND",
+		status: 404,
+		message: "Todo not found",
+	},
+});
+
+export const appError = createAppError(errors);
+`,
+  useCaseBuilder: `import type { beignetServerOnly } from "@beignet/core/server-only";
+import { createUseCase } from "@beignet/core/application";
+import type { AppContext } from "@/app-context";
+
+export const useCase = createUseCase<AppContext>();
+`,
+  authHelpers: `import type { AppContext } from "@/app-context";
+import type { AuthSession, AuthUser } from "@/ports/auth";
+import { appError } from "@/features/shared/errors";
+
+export function requireSession(ctx: AppContext): AuthSession {
+	if (!ctx.auth) {
+		throw appError("Unauthorized");
+	}
+
+	return ctx.auth;
+}
+
+export function requireUser(ctx: AppContext): AuthUser {
+	return requireSession(ctx).user;
+}
+`,
+  authPort: `import type {
+	AuthPort as BeignetAuthPort,
+	AuthRequestLike,
+	AuthSession as BeignetAuthSession,
+} from "@beignet/core/ports";
+
+export type AuthRequest = AuthRequestLike;
+
+export type AuthUser = {
+	id: string;
+	email?: string;
+	name?: string;
+};
+
+export type AuthSessionMetadata = {
+	id?: string;
+};
+
+export type AuthSession = BeignetAuthSession<
+	AuthUser,
+	AuthSessionMetadata
+>;
+
+export type AuthPort = BeignetAuthPort<
+	AuthUser,
+	AuthSessionMetadata,
+	AuthRequest
+>;
+`,
+  serverRoutes: `import type { beignetServerOnly } from "@beignet/core/server-only";
+import { contractsFromRoutes, defineRoutes } from "@beignet/next";
+import type { AppContext } from "@/app-context";
+import { todoRoutes } from "@/features/todos/routes";
+
+export const routes = defineRoutes<AppContext>([
+	todoRoutes,
+]);
+export const contracts = contractsFromRoutes(routes);
+`,
+  serverContext: `import type { beignetServerOnly } from "@beignet/core/server-only";
+import {
+	type ActivityActor,
+	createAnonymousActor,
+	createServiceActor,
+	createTenant,
+	createUserActor,
+} from "@beignet/core/ports";
+import { defineServerContext } from "@beignet/core/server";
+import type { TraceContext } from "@beignet/core/tracing";
+import type { AppContext, AppRuntimePorts } from "@/app-context";
+
+export type AppServiceContextInput =
+	| {
+			actor?: ActivityActor;
+			tenantId?: string;
+	  }
+	| undefined;
+
+/**
+ * Context blueprint shared by the runtime server and route tests.
+ */
+export const appContext = defineServerContext<AppContext, AppRuntimePorts>()({
+	gate: (ports) => ports.gate,
+	request: async ({ req, ports, requestId, trace }) => {
+		const auth = await ports.auth.getSession(req);
+		const tenantId = req.headers.get("x-tenant-id") || undefined;
+
+		return {
+			requestId,
+			actor: auth
+				? createUserActor(auth.user.id, { displayName: auth.user.name })
+				: createAnonymousActor(),
+			auth,
+			...trace,
+			ports,
+			tenant: tenantId ? createTenant(tenantId) : undefined,
+		};
+	},
+	service: ({
+		ports,
+		input,
+		requestId,
+		trace,
+	}: {
+		ports: AppRuntimePorts;
+		input: AppServiceContextInput;
+		requestId: string;
+		trace: TraceContext;
+	}) => ({
+		requestId,
+		actor: input?.actor ?? createServiceActor("beignet-service"),
+		auth: null,
+		...trace,
+		ports,
+		tenant: createTenant(input?.tenantId ?? "tenant_default"),
+	}),
+});
+`,
+  server: `import type { beignetServerOnly } from "@beignet/core/server-only";
+import { createNextServer } from "@beignet/next";
+import { createIdempotencyHooks } from "@beignet/core/server";
+import type { AppContext } from "@/app-context";
+import { appPorts } from "@/infra/app-ports";
+import { env } from "@/lib/env";
+import { appContext } from "./context";
+import { providers } from "./providers";
+import { routes } from "./routes";
+
+export const server = await createNextServer({
+	ports: appPorts,
+	providers,
+	providerConfig: {
+		"drizzle-turso": {
+			DB_URL: env.TURSO_DB_URL,
+			DB_AUTH_TOKEN: env.TURSO_DB_AUTH_TOKEN,
+		},
+	},
+	hooks: [createIdempotencyHooks<AppContext>()],
+	context: appContext,
+	routes,
+	mapUnhandledError: ({ err, ctx }) => {
+		ctx?.ports.logger.error("Unhandled API error", {
+			error: err,
+			requestId: ctx?.requestId,
+			environment: env.NODE_ENV,
+		});
+
+		return {
+			status: 500,
+			body: {
+				code: "INTERNAL_SERVER_ERROR",
+				message: "Internal server error",
+				requestId: ctx?.requestId,
+			},
+		};
+	},
+});
+`,
+  apiCatchAllRoute: `import { server } from "@/server";
+
+export const GET = server.api;
+export const HEAD = server.api;
+export const OPTIONS = server.api;
+export const PATCH = server.api;
+export const POST = server.api;
+export const PUT = server.api;
+export const DELETE = server.api;
+`,
+  healthRoute: `import { env } from "@/lib/env";
+
+export function GET() {
+	return Response.json(
+		{
+			status: "ok",
+			environment: env.NODE_ENV,
+			timestamp: new Date().toISOString(),
+		},
+		{
+			headers: {
+				"cache-control": "no-store",
+			},
+		},
+	);
+}
+`,
+  devtoolsRoute: `import { createDevtoolsRoute } from "@beignet/devtools";
+import { env } from "@/lib/env";
+import { server } from "@/server";
+
+export const { GET, POST } = createDevtoolsRoute(server.ports.devtools, {
+	basePath: "/api/devtools",
+	enabled: env.DEVTOOLS_ENABLED,
+});
+`,
+  openApiRoute: `import { createOpenAPIHandler } from "@beignet/next";
+import { server } from "@/server";
+
+export const GET = createOpenAPIHandler(server.contracts, {
+	title: "Beignet starter API",
+	version: "0.1.0",
+});
+`,
+  authRoute: `import { toNextJsHandler } from "better-auth/next-js";
+import { auth } from "@/lib/better-auth";
+
+export const { GET, POST } = toNextJsHandler(auth);
+`,
+  betterAuth: `import { createClient } from "@libsql/client";
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { drizzle } from "drizzle-orm/libsql";
+import * as schema from "@/infra/db/schema";
+import { env } from "@/lib/env";
+
+const client = createClient({
+	url: env.TURSO_DB_URL,
+	authToken: env.TURSO_DB_AUTH_TOKEN,
+});
+
+const db = drizzle(client, { schema });
+
+const trustedOrigins = [
+	env.APP_URL,
+	env.BETTER_AUTH_URL,
+	...(env.BETTER_AUTH_TRUSTED_ORIGINS?.split(",")
+		.map((origin) => origin.trim())
+		.filter(Boolean) ?? []),
+];
+
+export const auth = betterAuth({
+	baseURL: env.BETTER_AUTH_URL,
+	secret: env.BETTER_AUTH_SECRET,
+	trustedOrigins: [...new Set(trustedOrigins)],
+	database: drizzleAdapter(db, {
+		provider: "sqlite",
+		schema,
+	}),
+	emailAndPassword: {
+		enabled: true,
+	},
+	user: {
+		changeEmail: {
+			enabled: true,
+		},
+		deleteUser: {
+			enabled: true,
+		},
+	},
+});
+`,
+  // API-only scaffold frontend: a minimal layout and landing page that point
+  // at the contract-backed API surface, plus a typed client without React
+  // Query. The full-stack scaffold gets its frontend from templates/shell.ts.
+  apiLayout: `import type { Metadata } from "next";
+import type { ReactNode } from "react";
+
+export const metadata: Metadata = {
+	title: "Beignet API",
+	description: "A contract-first Beignet API.",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+	return (
+		<html lang="en">
+			<body
+				style={{
+					margin: 0,
+					fontFamily:
+						'ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+				}}
+			>
+				{children}
+			</body>
+		</html>
+	);
+}
+`,
+  apiPage: `export default function HomePage() {
+	return (
+		<main style={{ margin: "0 auto", maxWidth: "640px", padding: "64px 24px" }}>
+			<h1>Beignet API starter</h1>
+			<p>
+				This app is API-only. Contract-backed routes live under{" "}
+				<code>/api</code>, and the todos API requires a signed-in Better Auth
+				user.
+			</p>
+			<ul style={{ display: "grid", gap: "8px", paddingLeft: "20px" }}>
+				<li>
+					<a href="/api/health">/api/health</a> — health check
+				</li>
+				<li>
+					<a href="/api/openapi">/api/openapi</a> — OpenAPI document
+				</li>
+				<li>
+					<a href="/api/devtools">/api/devtools</a> — devtools (development
+					only)
+				</li>
+				<li>
+					<a href="https://beignetjs.com">Beignet docs</a>
+				</li>
+			</ul>
+		</main>
+	);
+}
+`,
+  apiClientIndex: `import { createClient } from "@beignet/core/client";
+
+export const apiClient = createClient({
+	validateInput: true,
+});
+`,
+};
+
+export { files as serverFiles };