appflare 0.0.28 → 0.1.0

package/cli/templates/auth/README.md

@@ -0,0 +1,156 @@
+# Auth Template Generators
+
+This directory contains source generators used by the Appflare CLI to scaffold authentication integration for a Cloudflare Worker backend.
+
+The files here **do not directly implement runtime auth logic** in this folder. Instead, they generate TypeScript source strings that are written into generated backend files (for example under `backend/_generated`).
+
+---
+
+## Purpose
+
+The auth template layer provides:
+
+- A generated `createAuth()` factory based on `better-auth` + Cloudflare integrations.
+- Route-level wiring for auth endpoints (`GET`/`POST` on an auth base path).
+- Request sanitization helpers to normalize header forwarding behavior.
+- Small composition utilities so the CLI can include/exclude KV support based on config.
+
+---
+
+## File-by-file breakdown
+
+## `config.ts`
+
+### `generateAuthConfigSource(configPathImport: string): string`
+
+Builds the full source code for an auth configuration module.
+
+Generated module characteristics:
+
+- Imports:
+  - `better-auth`
+  - `withCloudflare` from `better-auth-cloudflare`
+  - `drizzleAdapter` from `better-auth/adapters/drizzle`
+  - `drizzle` from `drizzle-orm/d1`
+  - Cloudflare worker types (`D1Database`, `KVNamespace`, `IncomingRequestCfProperties`)
+  - Local `auth.schema`
+  - User config module from `configPathImport`
+- Defines `CloudflareBindings` with:
+  - required `DATABASE: D1Database`
+  - optional `KV?: KVNamespace`
+- Exposes:
+  - `createAuth(env?, cf?)`
+  - `auth = createAuth()`
+
+Behavior details:
+
+- If `env` is provided:
+  - Creates a Drizzle D1 database instance.
+  - Configures `withCloudflare` with D1 and optional KV.
+- If `env` is missing:
+  - Falls back to a placeholder `drizzleAdapter` setup to keep type-level/runtime shape valid in non-worker contexts.
+- Merges Cloudflare options with `config.auth.options` so user config can extend behavior.
+
+---
+
+## `route-config.ts`
+
+### `generateKvField(kvBinding?: string): string`
+
+Returns a generated object field snippet for KV binding when configured.
+
+- If `kvBinding` is missing: returns empty string.
+- If present: returns `KV: c.env["<binding>"] as KVNamespace` (prefixed with comma/newline for embedding).
+
+### `generateAuthConfig(databaseBinding: string, kvBinding?: string): string`
+
+Generates the `env` argument payload passed into `createAuth()` in route handlers:
+
+- Always includes `DATABASE: c.env["<databaseBinding>"] as D1Database`.
+- Optionally includes `KV` using `generateKvField()`.
+
+This keeps route generation dynamic for projects that may or may not enable KV.
+
+---
+
+## `route-handler.ts`
+
+### `generateAuthHandler(authBasePath: string, databaseBinding: string, kvBinding?: string): string`
+
+Generates the auth route registration snippet:
+
+- Registers `app.on(["GET", "POST"], "<authBasePath>/*", async (c) => { ... })`.
+- Creates an auth instance per request:
+  - injects generated env bindings from `generateAuthConfig(...)`
+  - injects `c.req.raw.cf` as Cloudflare request metadata
+- Returns `auth.handler(getSanitizedRequest(c.req.raw))`.
+
+This is the bridge between framework routing and Better Auth request handling.
+
+---
+
+## `route-request-utils.ts`
+
+Contains generated helper functions to sanitize incoming request headers.
+
+### `generateGetHeadersFunction(): string`
+
+Generates `getHeaders(headers: Headers)`:
+
+- Converts headers into a plain object.
+- Detects whether a `cookie` header exists.
+- Keeps `authorization` only when it contains a `Bearer` token.
+- If cookies are present, suppresses `authorization` to avoid conflicting auth sources.
+- Returns a rebuilt header object cast back to `Headers`.
+
+### `generateSanitizedRequestFunction(): string`
+
+Generates `getSanitizedRequest(req: Request)`:
+
+- Creates a cloned `Request` with filtered headers from `getHeaders()`.
+
+### `generateRequestUtilities(): string`
+
+Concatenates both helper function source blocks into one string for route output.
+
+---
+
+## `route.ts`
+
+### `generateAuthRoute(authBasePath: string, databaseBinding: string, kvBinding?: string): string`
+
+Top-level composition entry for route generation.
+
+- Combines:
+  - `generateAuthHandler(...)`
+  - `generateRequestUtilities()`
+- Returns one complete source block ready to be written to generated route files.
+
+---
+
+## Generation flow in this directory
+
+1. CLI calls `generateAuthRoute(...)` when producing backend route code.
+2. Route snippet includes handler + request sanitizers.
+3. Handler calls `createAuth(...)` with bindings generated by `generateAuthConfig(...)`.
+4. Separately, CLI can emit full auth configuration module using `generateAuthConfigSource(...)`.
+5. Resulting generated backend code is ready for Cloudflare Worker runtime with D1 (and optional KV).
+
+---
+
+## Design notes
+
+- **String-template based generation**: keeps template logic small and explicit.
+- **Conditional KV support**: avoids forcing KV binding when not configured.
+- **Request normalization**: helps prevent ambiguous auth precedence between cookies and authorization headers.
+- **Cloudflare-first integration**: targets Worker runtime (`cf`, D1, KV) while preserving local compatibility shape.
+
+---
+
+## Expected consumers
+
+These generators are intended to be used by internal CLI code under:
+
+- `packages/appflare/cli/...`
+
+They are implementation details of scaffolding and are not meant as public runtime APIs.

package/cli/templates/auth/config.ts

@@ -0,0 +1,61 @@
+export function generateAuthConfigSource(configPathImport: string): string {
+	return `import { betterAuth } from "better-auth";
+import { withCloudflare } from "better-auth-cloudflare";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { drizzle } from "drizzle-orm/d1";
+import type {
+	D1Database,
+	IncomingRequestCfProperties,
+	KVNamespace,
+} from "@cloudflare/workers-types";
+import * as Schema from "./auth.schema";
+import config from "${configPathImport}";
+
+type CloudflareBindings = {
+	DATABASE: D1Database;
+	KV?: KVNamespace;
+};
+
+export const createAuth = (
+	env?: CloudflareBindings,
+	cf?: IncomingRequestCfProperties,
+) => {
+	const db = env
+		? drizzle(env.DATABASE, {
+			schema: Schema,
+		})
+		: ({} as any);
+
+	return betterAuth({
+		...withCloudflare(
+			{
+				autoDetectIpAddress: true,
+				geolocationTracking: true,
+				cf: cf ?? {},
+				d1: env
+					? {
+							db,
+							options: {
+								usePlural: true,
+								debugLogs: true,
+							},
+						}
+					: undefined,
+				kv: env?.KV,
+			},
+			config.auth.options,
+		),
+		...(env
+			? {}
+			: {
+					database: drizzleAdapter({} as D1Database, {
+						provider: "sqlite",
+						usePlural: true,
+						debugLogs: true,
+					}),
+			  }),
+	});
+};
+export const auth = createAuth();
+`;
+}

package/cli/templates/auth/route-config.ts

@@ -0,0 +1,18 @@
+function generateKvField(kvBinding?: string): string {
+	if (!kvBinding) {
+		return "";
+	}
+
+	return `,\n\t\t\tKV: c.env["${kvBinding}"] as KVNamespace`;
+}
+
+function generateAuthConfig(
+	databaseBinding: string,
+	kvBinding?: string,
+): string {
+	return `{
+			DATABASE: c.env["${databaseBinding}"] as D1Database${generateKvField(kvBinding)}
+		}`;
+}
+
+export { generateKvField, generateAuthConfig };

package/cli/templates/auth/route-handler.ts

@@ -0,0 +1,18 @@
+import { generateAuthConfig } from "./route-config";
+
+function generateAuthHandler(
+	authBasePath: string,
+	databaseBinding: string,
+	kvBinding?: string,
+): string {
+	return `app.on(["GET", "POST"], "${authBasePath}/*", async (c) => {
+	const auth = createAuth(
+		${generateAuthConfig(databaseBinding, kvBinding)},
+		c.req.raw.cf as IncomingRequestCfProperties | undefined,
+	);
+	return auth.handler(getSanitizedRequest(c.req.raw));
+});
+`;
+}
+
+export { generateAuthHandler };

package/cli/templates/auth/route-request-utils.ts

@@ -0,0 +1,55 @@
+function generateGetHeadersFunction(): string {
+	return `export const getHeaders = (headers: Headers) => {
+	const newHeaders = Object.fromEntries(headers as any);
+	const headerObject: Record<string, any> = {};
+	let hasCookie = false;
+
+	for (const key in newHeaders) {
+		if (key.toLowerCase() === "cookie") {
+			hasCookie = true;
+			break;
+		}
+	}
+
+	for (const key in newHeaders) {
+		const isAuthorization =
+			key.toLowerCase() === "authorization" &&
+			newHeaders[key]?.includes("Bearer");
+
+		if (hasCookie && key.toLowerCase() === "authorization") {
+			continue;
+		}
+
+		if (key.toLowerCase() === "authorization" && !isAuthorization) {
+			continue;
+		}
+
+		headerObject[key] = newHeaders[key];
+	}
+
+	return headerObject as any as Headers;
+};
+`;
+}
+
+function generateSanitizedRequestFunction(): string {
+	return `export const getSanitizedRequest = (req: Request) => {
+	const newRequest = new Request(req, {
+		headers: getHeaders(req.headers),
+	});
+	return newRequest;
+};
+`;
+}
+
+function generateRequestUtilities(): string {
+	return (
+		generateGetHeadersFunction() + "\n" + generateSanitizedRequestFunction()
+	);
+}
+
+export {
+	generateGetHeadersFunction,
+	generateSanitizedRequestFunction,
+	generateRequestUtilities,
+};

package/cli/templates/auth/route.ts

@@ -0,0 +1,14 @@
+import { generateAuthHandler } from "./route-handler";
+import { generateRequestUtilities } from "./route-request-utils";
+
+export function generateAuthRoute(
+	authBasePath: string,
+	databaseBinding: string,
+	kvBinding?: string,
+): string {
+	return (
+		generateAuthHandler(authBasePath, databaseBinding, kvBinding) +
+		"\n" +
+		generateRequestUtilities()
+	);
+}

package/cli/templates/core/README.md

@@ -0,0 +1,266 @@
+# Core Template Generators
+
+This directory contains **code generators** used by the Appflare CLI to produce the backend runtime scaffolding for Cloudflare Workers + Hono + Better Auth.
+
+Instead of shipping static template files, each module returns source code strings (or JSON objects) assembled by higher-level generation flows.
+
+---
+
+## What this folder does
+
+The core template modules are responsible for generating:
+
+1. **Worker server source** (`src/index.ts` style output)
+2. **Cloudflare Wrangler config** (`wrangler.json` shape)
+3. **Drizzle config source** (`drizzle.config.ts`)
+4. **Typed Appflare client source** (Better Auth client wrapper)
+5. **Generated handlers integration** (registering auto-generated route handlers)
+
+In short: this folder is the backbone that wires auth, handlers, CORS, DB/KV bindings, and deployment configuration together.
+
+---
+
+## Generation flow
+
+The main composition entry is:
+
+- `generateServerSource()` in `server.ts`
+
+It assembles output in this order:
+
+1. `generateImports()`
+2. `generateTypes()`
+3. `generateAppCreation()`
+4. `generateHandlersRoute()`
+5. `generateAuthRoute()` (from `../auth/route`)
+6. `generateExport()`
+
+This produces one server entry file that:
+
+- Creates a Hono app
+- Adds CORS middleware
+- Registers generated handlers
+- Adds auth routes
+- Exports a Worker-compatible `fetch` handler
+
+---
+
+## File-by-file documentation
+
+### `app-creation.ts`
+
+Provides `generateAppCreation()`.
+
+Generated behavior:
+
+- Creates `const app = new Hono<WorkerEnv>()`
+- Installs `cors()` middleware for all routes (`app.use('*', ...)`)
+- Implements dynamic origin allow-list logic based on `c.env.ALLOWED_DOMAINS`
+
+CORS behavior details:
+
+- If `ALLOWED_DOMAINS` is missing, all origins are allowed
+- If `ALLOWED_DOMAINS` contains `*`, all origins are allowed
+- Otherwise only exact origin matches are allowed
+- `credentials: true` is enabled
+
+---
+
+### `client.ts`
+
+Provides `generateClientArtifacts(configPathImport)`.
+
+Generates modular typed client artifacts under a `client/` directory:
+
+- `client/types.ts` for shared client/auth/storage types
+- `client/storage.ts` for storage API methods
+- `client/appflare.ts` for `Appflare` and `createAppflare()`
+- `client/index.ts` as barrel export
+- a root `client.ts` barrel (`export * from "./client"`)
+
+Runtime behavior:
+
+- Normalizes `endpoint` by removing trailing slash
+- Builds auth base URL as:
+  - `${endpoint}${authPath ?? "/api/auth"}`
+- Uses provided `fetch` override or global `fetch`
+
+This gives app consumers a stable, strongly typed client API.
+
+---
+
+### `drizzle.ts`
+
+Provides `generateDrizzleConfigSource(schema)`.
+
+Generates a `drizzle-kit` config with:
+
+- `dialect: "sqlite"`
+- `driver: "d1-http"`
+- provided `schema` paths
+- placeholder `dbCredentials` values (`accountId`, `databaseId`, `token`)
+
+Purpose: bootstrap Drizzle migrations/introspection for Cloudflare D1-backed projects.
+
+---
+
+### `export.ts`
+
+Provides `generateExport()`.
+
+Generates the Worker export:
+
+```ts
+export default {
+	fetch: app.fetch,
+};
+```
+
+This is the standard Cloudflare Worker module format.
+
+---
+
+### `handlers-route.ts`
+
+Provides `generateHandlersRoute(databaseBinding, kvBinding?)`.
+
+Generates a call to `registerGeneratedHandlers(app, { ... })` with:
+
+- required `databaseBinding`
+- optional `kvBinding`
+
+This bridges generated handler artifacts into the live Hono router.
+
+---
+
+### `handlers.ts`
+
+Re-exports `generateHandlersArtifacts` from `../handlers/index`.
+
+Role:
+
+- Keeps core template entrypoints centralized
+- Lets higher-level orchestration import handler generation through core exports
+
+---
+
+### `imports.ts`
+
+Provides `generateImports()`.
+
+Generates import statements used by server source:
+
+- `createAuth` from `./auth.config`
+- `registerGeneratedHandlers` from `./handlers.routes`
+- `Hono` from `hono`
+- `cors` from `hono/cors`
+- Worker-related types from `@cloudflare/workers-types`
+
+This keeps import assembly in one place so server template composition stays simple.
+
+---
+
+### `server.ts`
+
+Provides `generateServerSource(authBasePath, databaseBinding, kvBinding?)`.
+
+This is the **composition root** for server template output. It concatenates string fragments from all generator modules (including auth route generator from the auth template area).
+
+Inputs:
+
+- `authBasePath`: mount path for auth route generation
+- `databaseBinding`: D1 binding key used by handlers/auth wiring
+- `kvBinding` (optional): KV namespace binding key
+
+Output:
+
+- Full Worker/Hono server source file text
+
+---
+
+### `types.ts`
+
+Provides `generateTypes()`.
+
+Generates:
+
+```ts
+type WorkerEnv = {
+	Bindings: Record<string, unknown>;
+};
+```
+
+This gives the Hono app a generic Worker env shape and avoids hard-coding concrete bindings in this template fragment.
+
+---
+
+### `wrangler.ts`
+
+Provides `generateWranglerJson(config)`.
+
+Builds a base Wrangler JSON object from loaded Appflare config:
+
+- `name: "appflare-worker"`
+- `main: "./src/index.ts"`
+- maps `database` definitions -> `d1_databases`
+- maps `kv` definitions -> `kv_namespaces`
+
+Additional behavior:
+
+- Adds `migrations_dir` only when present
+- Adds KV `preview_id` only when present
+- If `wranglerOverrides` exists, merges it into base output via `deepMergeJson()`
+
+This lets generated defaults stay predictable while still supporting user overrides.
+
+---
+
+## Design patterns used
+
+1. **String-template generators**
+   - Each module returns source text with minimal side effects
+2. **Composable assembly**
+   - `server.ts` composes focused fragments in deterministic order
+3. **Config-driven output**
+   - Wrangler generation maps structured config into deploy-ready shape
+4. **Type inference for SDK ergonomics**
+   - Client generator infers auth options from config types
+5. **Optional feature toggles via args**
+   - KV-related code paths are included only when KV binding is provided
+
+---
+
+## Typical usage in CLI pipeline
+
+At a high level, CLI code can:
+
+1. Load and validate Appflare config
+2. Generate server source and write to `_generated/server.ts` (or similar)
+3. Generate handler/auth artifacts
+4. Generate wrangler JSON with merged overrides
+5. Generate client source for application consumption
+
+This folder specifically owns the **core primitives** used in steps 2, 4, and part of 5.
+
+---
+
+## Maintenance notes
+
+- Keep generator outputs deterministic for stable diffs.
+- When changing generated code contracts, update both:
+  - template generators
+  - consuming runtime code expecting those contracts
+- Prefer extending via optional args/config (as done with `kvBinding`) instead of branching per project type.
+- If new Worker bindings are added, update both:
+  - route registration generation
+  - wrangler JSON generation
+
+---
+
+## Quick reference
+
+- Server composition: `generateServerSource()`
+- Client generation: `generateClientArtifacts()`
+- Wrangler config generation: `generateWranglerJson()`
+- Drizzle config generation: `generateDrizzleConfigSource()`
+- Handlers artifacts export: `generateHandlersArtifacts` (re-exported)

package/cli/templates/core/app-creation.ts

@@ -0,0 +1,19 @@
+export function generateAppCreation(): string {
+	return `const app = new Hono<WorkerEnv>();
+
+app.use('*', cors({
+	origin: (origin, c) => {
+		const allowedDomains = c.env.ALLOWED_DOMAINS;
+		if (!allowedDomains) {
+			return origin; // Allow everything if not set
+		}
+		const allowed = allowedDomains.split(',').map(d => d.trim());
+		if (allowed.includes('*')) {
+			return origin;
+		}
+		return allowed.includes(origin) ? origin : null;
+	},
+	credentials: true
+}));
+`;
+}

package/cli/templates/core/client/appflare.ts

@@ -0,0 +1,37 @@
+export function generateClientAppflareSource(): string {
+	return `import { createAuthClient, type BetterAuthClientOptions } from "better-auth/client";
+import type {
+	AppflareAuth,
+	AppflareOptions,
+	InferredAuthOptions,
+	StorageClient,
+} from "./types";
+import { createStorageClient } from "./storage";
+
+export class Appflare<Options extends BetterAuthClientOptions = InferredAuthOptions> {
+	public readonly endpoint: string;
+	public readonly auth: AppflareAuth<Options>;
+	public readonly storage: StorageClient;
+
+	public constructor(options: AppflareOptions<Options>) {
+		this.endpoint = options.endpoint.replace(/\/$/, "");
+		const authOptions = (options.authOptions ?? {}) as Options;
+		const request = options.fetch ?? fetch;
+
+		this.auth = createAuthClient<Options>({
+			...authOptions,
+			baseURL: \`\${this.endpoint}\${options.authPath ?? "/api/auth"}\`,
+			fetch: request,
+		});
+
+		this.storage = createStorageClient(this.endpoint, request);
+	}
+}
+
+export function createAppflare<Options extends BetterAuthClientOptions = InferredAuthOptions>(
+	options: AppflareOptions<Options>,
+): Appflare<Options> {
+	return new Appflare(options);
+}
+`;
+}

package/cli/templates/core/client/index.ts

@@ -0,0 +1,6 @@
+export function generateClientIndexSource(): string {
+	return `export * from "./types";
+export * from "./appflare";
+export * from "./storage";
+`;
+}