docs: add Cloudflare target implementation plan

9 tasks in 5 batches: D1 adapter, Worker entry, Container entry,
build command, integration and docs.

Co-Authored-By: Claude Opus 4.6 <[e-mail]>

docs/superpowers/plans/2026-03-18-cloudflare-target.md

···
+# Cloudflare Target Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add `target: 'cloudflare'` to hatk so apps deploy to Cloudflare Workers + Containers with D1 as the database.
+
+**Architecture:** Worker handles HTTP (XRPC, SvelteKit SSR, OAuth, admin). Container handles firehose + backfill. Both share D1. Worker calls Container via Service Binding RPC for resync.
+
+**Tech Stack:** Cloudflare Workers, Cloudflare Containers, D1, Service Bindings RPC, `@sveltejs/adapter-cloudflare`
+
+**Design doc:** `docs/superpowers/specs/2026-03-18-cloudflare-target-design.md`
+
+---
+
+## Batch 1: Config + D1 Adapter
+
+### Task 1: Add `target` field to config
+
+**Files:**
+- Modify: `packages/hatk/src/config.ts`
+
+**Step 1: Add `target` to `HatkConfig` and `HatkConfigInput`**
+
+In `HatkConfig` interface, add after `databaseEngine`:
+
+```ts
+target: 'node' | 'cloudflare'
+```
+
+In `HatkConfigInput`, `target` is already optional via the `Partial<>` wrapping.
+
+In `loadConfig()`, add to the `config` object construction (after the `databaseEngine` line):
+
+```ts
+target: (env.HATK_TARGET || parsed.target || 'node') as HatkConfig['target'],
+```
+
+**Step 2: Verify build**
+
+Run: `npm run build`
+Expected: Compiles without errors
+
+**Step 3: Commit**
+
+```bash
+git add packages/hatk/src/config.ts
+git commit -m "feat: add target field to HatkConfig (node | cloudflare)"
+```
+
+### Task 2: Add `Dialect` type for D1
+
+**Files:**
+- Modify: `packages/hatk/src/database/ports.ts`
+
+**Step 1: Add `d1` to Dialect union**
+
+Change line 1 from:
+
+```ts
+export type Dialect = 'duckdb' | 'sqlite' | 'postgres'
+```
+
+To:
+
+```ts
+export type Dialect = 'duckdb' | 'sqlite' | 'd1' | 'postgres'
+```
+
+**Step 2: Commit**
+
+```bash
+git add packages/hatk/src/database/ports.ts
+git commit -m "feat: add d1 to Dialect type"
+```
+
+### Task 3: Create D1 database adapter
+
+**Files:**
+- Create: `packages/hatk/src/database/adapters/d1.ts`
+
+This is the core of the Cloudflare support. The adapter implements `DatabasePort` using Cloudflare's D1 binding API. It fakes transactions by buffering statements and flushing as `d1.batch()`.
+
+**Step 1: Write the adapter**
+
+```ts
+import type { DatabasePort, BulkInserter, Dialect } from '../ports.ts'
+
+/**
+ * D1 database adapter for Cloudflare Workers/Containers.
+ *
+ * D1 is SQLite under the hood but accessed via an HTTP-based binding API.
+ * Key differences from the SQLite adapter:
+ * - No raw transactions — uses d1.batch() for atomic multi-statement execution
+ * - No prepared statement reuse — each query is a fresh prepare+bind
+ * - Bulk inserts use batched INSERT statements instead of native appenders
+ */
+
+/** Minimal D1 type definitions (matches Cloudflare's D1Database binding) */
+interface D1Database {
+  prepare(sql: string): D1PreparedStatement
+  batch<T = unknown>(statements: D1PreparedStatement[]): Promise<D1Result<T>[]>
+  exec(sql: string): Promise<D1ExecResult>
+}
+
+interface D1PreparedStatement {
+  bind(...values: unknown[]): D1PreparedStatement
+  all<T = Record<string, unknown>>(): Promise<D1Result<T>>
+  run(): Promise<D1Result>
+  first<T = Record<string, unknown>>(column?: string): Promise<T | null>
+}
+
+interface D1Result<T = unknown> {
+  results: T[]
+  success: boolean
+  meta: Record<string, unknown>
+}
+
+interface D1ExecResult {
+  count: number
+  duration: number
+}
+
+/**
+ * Translate DuckDB-style $1, $2 placeholders to ? placeholders.
+ * Same logic as the SQLite adapter — D1 uses ? style.
+ */
+function translateParams(sql: string, params: unknown[]): { sql: string; params: unknown[] } {
+  if (params.length === 0) return { sql, params }
+
+  const expandedParams: unknown[] = []
+  const translated = sql.replace(/\$(\d+)/g, (_match, numStr) => {
+    const idx = parseInt(numStr) - 1
+    expandedParams.push(params[idx])
+    return '?'
+  })
+
+  return { sql: translated, params: expandedParams }
+}
+
+export class D1Adapter implements DatabasePort {
+  dialect: Dialect = 'd1'
+
+  private db!: D1Database
+  private txBuffer: D1PreparedStatement[] | null = null
+
+  /**
+   * Initialize with an existing D1 binding (from env.DB in Worker/Container).
+   * The `path` argument is ignored — D1 bindings are configured in wrangler.jsonc.
+   */
+  async open(path: string): Promise<void> {
+    // D1 binding is injected via initWithBinding(), not opened by path.
+    // This is a no-op if already initialized.
+    if (!this.db) {
+      throw new Error('D1Adapter requires initWithBinding(db) before use')
+    }
+  }
+
+  /** Set the D1 binding directly (called before open). */
+  initWithBinding(db: D1Database): void {
+    this.db = db
+  }
+
+  close(): void {
+    // D1 bindings don't need explicit cleanup
+  }
+
+  async query<T = Record<string, unknown>>(sql: string, params: unknown[] = []): Promise<T[]> {
+    const t = translateParams(sql, params)
+    const stmt = this.db.prepare(t.sql).bind(...t.params)
+    const result = await stmt.all<T>()
+    return result.results
+  }
+
+  async execute(sql: string, params: unknown[] = []): Promise<void> {
+    const t = translateParams(sql, params)
+    const stmt = this.db.prepare(t.sql).bind(...t.params)
+
+    // If inside a transaction, buffer instead of executing
+    if (this.txBuffer !== null) {
+      this.txBuffer.push(stmt)
+      return
+    }
+
+    await stmt.run()
+  }
+
+  async executeMultiple(sql: string): Promise<void> {
+    // D1's exec() handles multi-statement SQL
+    await this.db.exec(sql)
+  }
+
+  async beginTransaction(): Promise<void> {
+    this.txBuffer = []
+  }
+
+  async commit(): Promise<void> {
+    if (this.txBuffer === null) return
+    const statements = this.txBuffer
+    this.txBuffer = null
+    if (statements.length > 0) {
+      await this.db.batch(statements)
+    }
+  }
+
+  async rollback(): Promise<void> {
+    this.txBuffer = null
+  }
+
+  async createBulkInserter(
+    table: string,
+    columns: string[],
+    options?: { onConflict?: 'ignore' | 'replace'; batchSize?: number },
+  ): Promise<BulkInserter> {
+    const placeholders = columns.map(() => '?').join(', ')
+    const conflict =
+      options?.onConflict === 'ignore' ? ' OR IGNORE' : options?.onConflict === 'replace' ? ' OR REPLACE' : ''
+    const sqlTemplate = `INSERT${conflict} INTO ${table} (${columns.join(', ')}) VALUES (${placeholders})`
+    const buffer: D1PreparedStatement[] = []
+    const batchSize = options?.batchSize ?? 200 // smaller batches for D1 CPU limits
+    const db = this.db
+
+    const flush = async () => {
+      if (buffer.length > 0) {
+        await db.batch(buffer)
+        buffer.length = 0
+      }
+    }
+
+    return {
+      append(values: unknown[]) {
+        buffer.push(db.prepare(sqlTemplate).bind(...values))
+        if (buffer.length >= batchSize) {
+          // Fire and forget — next append or flush will await
+          flush()
+        }
+      },
+      async flush() {
+        await flush()
+      },
+      async close() {
+        await flush()
+      },
+    }
+  }
+}
+```
+
+**Step 2: Verify build**
+
+Run: `npm run build`
+Expected: Compiles without errors
+
+**Step 3: Commit**
+
+```bash
+git add packages/hatk/src/database/adapters/d1.ts
+git commit -m "feat: add D1 database adapter for Cloudflare"
+```
+
+### Task 4: Add D1 to adapter factory and dialect
+
+**Files:**
+- Modify: `packages/hatk/src/database/adapter-factory.ts`
+- Modify: `packages/hatk/src/database/dialect.ts`
+
+**Step 1: Add `d1` case to adapter factory**
+
+Read `packages/hatk/src/database/adapter-factory.ts`. Add a new case after the `sqlite` case:
+
+```ts
+case 'd1': {
+  const { D1Adapter } = await import('./adapters/d1.ts')
+  const { SQLiteSearchPort } = await import('./adapters/sqlite-search.ts')
+  const adapter = new D1Adapter()
+  // D1 uses SQLite FTS5, same search port
+  const searchPort = new SQLiteSearchPort(adapter)
+  return { adapter, searchPort }
+}
+```
+
+Also update the function signature to accept `'d1'`:
+
+```ts
+export async function createAdapter(engine: 'duckdb' | 'sqlite' | 'd1'): Promise<{
+```
+
+**Step 2: Add D1 dialect to dialect.ts**
+
+Read `packages/hatk/src/database/dialect.ts` to understand the `SqlDialect` shape. Add a D1 dialect entry that reuses the SQLite dialect's values (D1 is SQLite under the hood). The D1 dialect should be identical to the SQLite dialect.
+
+**Step 3: Verify build**
+
+Run: `npm run build`
+Expected: Compiles without errors
+
+**Step 4: Commit**
+
+```bash
+git add packages/hatk/src/database/adapter-factory.ts packages/hatk/src/database/dialect.ts
+git commit -m "feat: wire D1 into adapter factory and dialect"
+```
+
+---
+
+## Batch 2: Worker Entry
+
+### Task 5: Create Worker entry point
+
+**Files:**
+- Create: `packages/hatk/src/cloudflare/worker.ts`
+
+This is the Cloudflare Worker fetch handler. It wires together the same XRPC handlers, OAuth, and admin routes that `server.ts` provides, but in a Worker context with D1.
+
+**Step 1: Read existing server code for reference**
+
+Read these files to understand the current request handling:
+- `packages/hatk/src/server.ts` — the `createHandler()` function and route matching
+- `packages/hatk/src/server-init.ts` — server directory initialization
+- `packages/hatk/src/adapter.ts` — HTTP serving
+- `packages/hatk/src/main.ts` — full startup sequence
+
+**Step 2: Write the Worker entry**
+
+Create `packages/hatk/src/cloudflare/worker.ts` that:
+
+1. Defines an `Env` interface with `DB: D1Database`, `CONTAINER: ContainerBinding`
+2. Exports a default fetch handler
+3. On first request, initializes the D1 adapter via `initWithBinding(env.DB)`
+4. Runs XRPC route matching (reuse `createHandler()` from server.ts)
+5. For admin resync routes, calls `env.CONTAINER.resync(did)` via RPC instead of `triggerAutoBackfill`
+6. Falls through to SvelteKit for non-API routes
+
+Note: The exact SvelteKit integration depends on `@sveltejs/adapter-cloudflare` output. For now, create a placeholder that handles XRPC + admin + OAuth, and marks where SvelteKit would slot in.
+
+**Step 3: Verify build**
+
+Run: `npm run build`
+Expected: Compiles without errors
+
+**Step 4: Commit**
+
+```bash
+git add packages/hatk/src/cloudflare/worker.ts
+git commit -m "feat: add Cloudflare Worker entry point"
+```
+
+---
+
+## Batch 3: Container Entry
+
+### Task 6: Create Container entry point
+
+**Files:**
+- Create: `packages/hatk/src/cloudflare/container.ts`
+
+This is the Cloudflare Container entry — a long-lived Node process that runs the firehose and backfill, writing to D1.
+
+**Step 1: Read existing entry points for reference**
+
+Read these files:
+- `packages/hatk/src/main.ts` — full startup (we need firehose + backfill parts)
+- `packages/hatk/src/indexer.ts` — firehose subscription (the `startIndexer` function)
+- `packages/hatk/src/backfill.ts` — repo backfill
+
+**Step 2: Write the Container entry**
+
+Create `packages/hatk/src/cloudflare/container.ts` that:
+
+1. Initializes the D1 adapter (Container gets D1 binding from env)
+2. Loads lexicons, builds schemas, initializes database tables
+3. Initializes feeds, XRPC, labels (same as main.ts)
+4. Starts the firehose indexer (`startIndexer`)
+5. Starts the backfill loop (`runBackfill`)
+6. Exposes RPC methods: `resync(did)`, `resyncAll()`, `getStatus()`
+
+The Container does NOT start an HTTP server — communication is via RPC only.
+
+**Step 3: Verify build**
+
+Run: `npm run build`
+Expected: Compiles without errors
+
+**Step 4: Commit**
+
+```bash
+git add packages/hatk/src/cloudflare/container.ts
+git commit -m "feat: add Cloudflare Container entry point"
+```
+
+---
+
+## Batch 4: Build Command
+
+### Task 7: Add `--target cloudflare` to build command
+
+**Files:**
+- Modify: `packages/hatk/src/cli.ts`
+
+**Step 1: Read the existing build command**
+
+Read `packages/hatk/src/cli.ts` and find the `hatk build` command handler. Understand what it currently does (likely runs Vite build for SvelteKit).
+
+**Step 2: Add cloudflare build path**
+
+When `target === 'cloudflare'` in config (or `--target cloudflare` CLI flag):
+
+1. Run `@sveltejs/adapter-cloudflare` build for SvelteKit (this may require swapping the adapter in svelte.config.js or generating a cloudflare-specific one)
+2. Bundle `packages/hatk/src/cloudflare/worker.ts` into `dist/worker/index.js`
+3. Bundle `packages/hatk/src/cloudflare/container.ts` into `dist/container/index.js`
+4. Generate `dist/wrangler.jsonc` with:
+   - D1 database binding (`DB`)
+   - Service Binding to Container (`CONTAINER`)
+   - Container configuration
+
+Example wrangler.jsonc structure:
+
+```jsonc
+{
+  "name": "my-app",
+  "main": "worker/index.js",
+  "compatibility_date": "2026-03-18",
+  "d1_databases": [
+    { "binding": "DB", "database_name": "hatk", "database_id": "TODO" }
+  ],
+  "services": [
+    { "binding": "CONTAINER", "service": "my-app-container" }
+  ]
+}
+```
+
+**Step 3: Verify build**
+
+Run: `npm run build`
+Expected: Compiles without errors (the cloudflare build path won't run unless target is set)
+
+**Step 4: Commit**
+
+```bash
+git add packages/hatk/src/cli.ts
+git commit -m "feat: add --target cloudflare to build command"
+```
+
+---
+
+## Batch 5: Integration & Docs
+
+### Task 8: Update `databaseEngine` handling for cloudflare target
+
+**Files:**
+- Modify: `packages/hatk/src/config.ts`
+- Modify: `packages/hatk/src/main.ts`
+
+**Step 1: Auto-set databaseEngine to 'd1' when target is cloudflare**
+
+In `loadConfig()`, after constructing the config object, add:
+
+```ts
+if (config.target === 'cloudflare') {
+  config.databaseEngine = 'd1' as any
+}
+```
+
+Update `HatkConfig.databaseEngine` type to include `'d1'`:
+
+```ts
+databaseEngine: 'duckdb' | 'sqlite' | 'd1'
+```
+
+**Step 2: Skip file-based operations in main.ts for cloudflare**
+
+In `main.ts`, the `mkdirSync` for the data directory, schema.sql write, and `pragma` settings don't apply to D1. Guard these with `config.target !== 'cloudflare'` checks (or the D1 adapter handles them as no-ops — verify which approach is cleaner).
+
+**Step 3: Verify build**
+
+Run: `npm run build`
+Expected: Compiles without errors
+
+**Step 4: Commit**
+
+```bash
+git add packages/hatk/src/config.ts packages/hatk/src/main.ts
+git commit -m "feat: auto-set d1 engine for cloudflare target, guard file ops"
+```
+
+### Task 9: Add Cloudflare deployment docs
+
+**Files:**
+- Create: `docs/site/cli/cloudflare.md`
+- Modify: `docs/site/.vitepress/config.ts` (add to CLI sidebar)
+
+**Step 1: Write the docs page**
+
+Cover:
+- What `target: 'cloudflare'` does (Worker + Container + D1)
+- Prerequisites (Cloudflare account, wrangler CLI)
+- Config: add `target: 'cloudflare'` to `hatk.config.ts`
+- Build: `hatk build` generates `dist/` with worker, container, wrangler.jsonc
+- Deploy: `npx wrangler deploy` (after setting D1 database_id)
+- Create D1 database: `npx wrangler d1 create hatk`
+- Known limitations (10GB D1 limit, slower backfill)
+
+**Step 2: Add to sidebar**
+
+In `docs/site/.vitepress/config.ts`, add to the CLI Reference items:
+
+```ts
+{ text: 'Cloudflare', link: '/cli/cloudflare' },
+```
+
+**Step 3: Verify docs build**
+
+Run: `cd docs/site && npx vitepress build`
+Expected: Build succeeds
+
+**Step 4: Commit**
+
+```bash
+git add docs/site/cli/cloudflare.md docs/site/.vitepress/config.ts
+git commit -m "docs: add Cloudflare deployment guide"
+```