appflare 0.2.30 → 0.2.31

package/cli/templates/core/README.md

@@ -1,266 +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.artifacts.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)
+# 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.artifacts.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

@@ -1,19 +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: string) => d.trim());
-		if (allowed.includes('*')) {
-			return origin;
-		}
-		return allowed.includes(origin) ? origin : null;
-	},
-	credentials: true
-}));
-`;
-}
+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: string) => d.trim());
+		if (allowed.includes('*')) {
+			return origin;
+		}
+		return allowed.includes(origin) ? origin : null;
+	},
+	credentials: true
+}));
+`;
+}