create-pracht 0.6.0 → 0.6.2

package/skills/add-db/SKILL.md

@@ -1,14 +1,12 @@
 ---
 name: add-db
-version: 1.1.0
+version: 1.2.0
 description: |
-  Wire Drizzle ORM into a pracht app. Asks the user which database to target
-  (Cloudflare D1, PlanetScale, Neon, Supabase, Turso, Postgres, MySQL, SQLite,
-  ...) and generates the matching driver setup, schema scaffold, migration
-  workflow, and a typed client accessible from loaders, middleware, and API
-  routes.
-  Use when asked to "add database", "set up Drizzle", "wire D1",
-  "add Postgres", "set up an ORM", or "I need a DB".
+  Wire Drizzle ORM into a pracht app: pick the target (D1, PlanetScale, Neon,
+  Supabase, Turso, Postgres, MySQL, SQLite), then generate driver setup, schema,
+  migration workflow, and a typed client for loaders, middleware, and API routes.
+  Use for "add database", "set up Drizzle", "wire D1", "add Postgres", "set up an
+  ORM", "I need a DB".
 allowed-tools:
   - Bash
   - Read
@@ -21,60 +19,47 @@ allowed-tools:
 
 # Pracht Add Database (Drizzle)
 
-Drizzle works well in pracht because it is small, type-safe, and runs in
-both Node and edge runtimes (Cloudflare Workers, Vercel Edge). This skill
-sets up the driver, schema directory, migration tooling, and a client
-factory wired to the project's adapter.
+Drizzle suits pracht because it is small, type-safe, and runs in both Node and
+edge runtimes. This skill sets up the driver, schema, migration tooling, and a
+client factory wired to the project's adapter. Never overwrite an existing
+`drizzle.config.ts`, `wrangler.toml`, or `package.json` script — diff, merge,
+and ask about collisions.
 
-## Step 1: Pick the target
-
-Use `AskUserQuestion`:
-
-| Provider           | Driver                                   | Adapter notes                |
-| ------------------ | ---------------------------------------- | ---------------------------- |
-| Cloudflare D1      | `drizzle-orm/d1`                         | Workers binding              |
-| Cloudflare Hyperdrive (Postgres) | `drizzle-orm/postgres-js` or `node-postgres` | Workers binding |
-| PlanetScale        | `drizzle-orm/planetscale-serverless`     | Works on Node + edge         |
-| Neon (Postgres)    | `drizzle-orm/neon-serverless` or `neon-http` | Works on Node + edge     |
-| Supabase Postgres  | `drizzle-orm/postgres-js`                | Node + edge (HTTP variant)   |
-| Turso (libSQL)     | `drizzle-orm/libsql`                     | Node + edge                  |
-| Vanilla Postgres   | `drizzle-orm/node-postgres`              | Node only                    |
-| Vanilla MySQL      | `drizzle-orm/mysql2`                     | Node only                    |
-| SQLite (better-sqlite3) | `drizzle-orm/better-sqlite3`        | Node only                    |
-
-If the pracht MCP server is registered (see docs/MCP.md), prefer its tools
-(`inspect_routes`, `inspect_api`, `inspect_build`, `doctor`, `verify`,
-`generate_*`) over shelling out. Prerequisites: `pracht inspect` needs a vite
-config with the pracht plugin; `pracht inspect build` reads artifacts from a
-prior `pracht build`.
+MCP: when the pracht MCP server is registered (docs/MCP.md), prefer its
+`inspect_routes`/`inspect_api`/`inspect_build`/`doctor`/`verify`/`generate_*`
+tools over shelling out. `pracht inspect` needs the pracht plugin in the vite
+config; `inspect build` needs a prior `pracht build`.
 
-Cross-check with the project's pracht adapter (`pracht inspect build --json`):
-flag mismatches (e.g., `node-postgres` on Cloudflare Workers — won't work).
+## Step 1: Pick the target
 
-## Step 2: Install
+Ask with `AskUserQuestion`, then **cross-check against the project's adapter**
+(`pracht inspect build --json`) and flag mismatches — `node-postgres` on
+Cloudflare Workers will not work.
+
+| Provider                         | Driver import                                | Extra package | Runtimes |
+| -------------------------------- | -------------------------------------------- | ------------- | -------- |
+| Cloudflare D1                    | `drizzle-orm/d1`                             | — (Workers binding) | Edge |
+| Cloudflare Hyperdrive (Postgres) | `drizzle-orm/postgres-js` or `node-postgres` | `postgres` / `pg` | Edge (binding) |
+| PlanetScale                      | `drizzle-orm/planetscale-serverless`         | `@planetscale/database` | Node + edge |
+| Neon                             | `drizzle-orm/neon-serverless` or `neon-http` | `@neondatabase/serverless` | Node + edge |
+| Supabase Postgres                | `drizzle-orm/postgres-js`                    | `postgres` | Node + edge (HTTP) |
+| Turso (libSQL)                   | `drizzle-orm/libsql`                         | `@libsql/client` | Node + edge |
+| Vanilla Postgres                 | `drizzle-orm/node-postgres`                  | `pg` + `-D @types/pg` | Node only |
+| Vanilla MySQL                    | `drizzle-orm/mysql2`                         | `mysql2` | Node only |
+| SQLite                           | `drizzle-orm/better-sqlite3`                 | `better-sqlite3` + `-D @types/better-sqlite3` | Node only |
 
 ```bash
-pnpm add drizzle-orm <driver>
+pnpm add drizzle-orm <driver-package>
 pnpm add -D drizzle-kit
 ```
 
-Specific drivers:
-
-- D1: no additional package; uses the Workers binding.
-- PlanetScale: `pnpm add @planetscale/database`.
-- Neon: `pnpm add @neondatabase/serverless`.
-- Postgres / Supabase: `pnpm add postgres` (postgres-js).
-- Turso: `pnpm add @libsql/client`.
-- node-postgres: `pnpm add pg && pnpm add -D @types/pg`.
-- mysql2: `pnpm add mysql2`.
-- better-sqlite3: `pnpm add better-sqlite3 && pnpm add -D @types/better-sqlite3`.
+## Step 2: Schema
 
-## Step 3: Schema directory
-
-`src/db/schema.ts`:
+`src/db/schema.ts` — `pgTable` from `drizzle-orm/pg-core`, `sqliteTable` from
+`drizzle-orm/sqlite-core` (D1 and SQLite), or `mysqlTable` from
+`drizzle-orm/mysql-core`:
 
 ```ts
-// Postgres example — substitute sqliteTable / mysqlTable for other dialects.
 import { pgTable, serial, text, timestamp } from "drizzle-orm/pg-core";
 
 export const users = pgTable("users", {
@@ -84,15 +69,20 @@ export const users = pgTable("users", {
 });
 ```
 
-For D1/SQLite, use `sqliteTable` from `drizzle-orm/sqlite-core`. For MySQL,
-use `mysqlTable` from `drizzle-orm/mysql-core`.
+## Step 3: Client factory
 
-## Step 4: Client factory
+Read connection strings via `serverEnv` from `@pracht/core/env/server`, never
+`process.env` — it keeps the secret out of the client bundle and resolves per
+adapter (docs/ENV.md). The shape depends on the runtime:
 
-`src/db/client.ts`:
+- **Node, persistent process** — a module-level singleton is fine, because
+  `serverEnv` works at module top level there.
+- **Edge with per-request context (Cloudflare, Vercel Edge)** — read
+  `serverEnv` or the binding *inside* a factory. Workers env bindings only
+  exist per request, so a module-level read bricks the worker at import time.
 
 ```ts
-// Example for Postgres on Node:
+// src/db/client.ts — Postgres on Node
 import { serverEnv } from "@pracht/core/env/server";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { Pool } from "pg";
@@ -102,15 +92,8 @@ const pool = new Pool({ connectionString: serverEnv.DATABASE_URL });
 export const db = drizzle(pool, { schema });
 ```
 
-Read the connection string via `serverEnv` (from `@pracht/core/env/server`),
-never `process.env` — it keeps the secret out of the client bundle and
-resolves per adapter (see docs/ENV.md). The module-level singleton above is
-fine on the Node adapter, where `serverEnv` works at module top level; on
-Cloudflare/Vercel Edge, read `serverEnv` inside a factory function instead —
-Workers env bindings only exist per request.
-
-For Cloudflare D1, first register the Cloudflare context type once via the
-`Register` augmentation (the pattern the docs recommend — see
+For Cloudflare D1, register the Cloudflare context type once via the `Register`
+augmentation (the pattern in
 `examples/docs/src/routes/docs/recipes-fullstack-cloudflare.md`):
 
 ```ts
@@ -125,37 +108,26 @@ declare module "@pracht/core" {
 }
 ```
 
-Then the factory needs no per-file generics:
+The factory then needs no per-file generics:
 
 ```ts
+import type { LoaderArgs } from "@pracht/core";
 import { drizzle } from "drizzle-orm/d1";
 import * as schema from "./schema";
-import type { LoaderArgs } from "@pracht/core";
 
 export function getDb({ context }: Pick<LoaderArgs, "context">) {
   return drizzle(context.env.DB, { schema });
 }
 ```
 
-(Without the `Register` augmentation, the inline generic must describe the
-full Cloudflare context shape —
+Without that augmentation, the inline generic must describe the full context —
 `LoaderArgs<{ env: { DB: D1Database }; executionContext: ExecutionContext }>` —
-the context is `{ env, executionContext }`, not the bindings object itself.)
-
-For PlanetScale / Neon / Turso, follow the matching driver pattern. The
-pattern is:
-
-- **Node + persistent process**: module-level singleton.
-- **Edge + per-request context (Cloudflare/Vercel Edge)**: factory called
-  with `context` inside the loader.
+because the context is `{ env, executionContext }`, not the bindings object.
 
-## Step 5: `drizzle.config.ts`
+## Step 4: drizzle.config.ts and scripts
 
-If `drizzle.config.ts` already exists, diff and merge — never overwrite.
-(`process.env` is fine here: this file runs under the drizzle-kit CLI on
-Node, never inside the worker.)
-
-### Non-D1 providers (Postgres, MySQL, Turso, PlanetScale, Neon, local SQLite)
+`process.env` *is* fine in `drizzle.config.ts`: it runs under the drizzle-kit
+CLI on Node, never inside the worker.
 
 ```ts
 import { defineConfig } from "drizzle-kit";
@@ -164,74 +136,44 @@ export default defineConfig({
   schema: "./src/db/schema.ts",
   out: "./drizzle/migrations",
   dialect: "postgresql", // or "sqlite" / "mysql"
-  dbCredentials: {
-    url: process.env.DATABASE_URL!,
-  },
-});
-```
-
-### Cloudflare D1
-
-D1 has no TCP endpoint, so drizzle-kit can only *generate* migrations. It
-cannot apply them — applying goes through `wrangler` (Step 6):
-
-```ts
-import { defineConfig } from "drizzle-kit";
-
-export default defineConfig({
-  schema: "./src/db/schema.ts",
-  out: "./drizzle/migrations",
-  dialect: "sqlite",
+  dbCredentials: { url: process.env.DATABASE_URL! },
 });
 ```
 
-If you want `drizzle-kit studio` against D1, add a `driver: "d1-http"` block
-with Cloudflare account/database/API-token credentials (see Drizzle's D1
-docs). Otherwise omit `dbCredentials` entirely — `drizzle-kit generate`
-doesn't need them.
+**D1 is the exception.** It has no TCP endpoint, so drizzle-kit can only
+*generate* migrations — applying goes through `wrangler`. Omit `dbCredentials`
+entirely (add a `driver: "d1-http"` block with Cloudflare account/database/API
+token only if you want `drizzle-kit studio`), and omit `db:push`: the
+migrations-apply flow is the only supported path. Split local from remote so
+the miniflare D1 can be iterated without touching production.
 
-## Step 6: Scripts
+| Script | Non-D1 | Cloudflare D1 |
+| ------ | ------ | ------------- |
+| `db:generate` | `drizzle-kit generate` | `drizzle-kit generate` |
+| `db:migrate` | `drizzle-kit migrate` | `wrangler d1 migrations apply <db-name> --local` / `--remote` as `db:migrate:local` / `db:migrate:remote` |
+| `db:push` | `drizzle-kit push` (local dev only — prefer migrations beyond that) | *omit* |
+| `db:studio` | `drizzle-kit studio` | `drizzle-kit studio` |
 
-Merge these into the existing `package.json` `scripts` block — never
-overwrite scripts that already exist; diff and ask if one collides.
+`<db-name>` is the `database_name` from `wrangler.toml`/`.jsonc`.
 
-### Non-D1 providers
+## Step 5: Bindings and env
 
-```json
-{
-  "scripts": {
-    "db:generate": "drizzle-kit generate",
-    "db:migrate":  "drizzle-kit migrate",
-    "db:push":     "drizzle-kit push",
-    "db:studio":   "drizzle-kit studio"
-  }
-}
-```
+- **Cloudflare D1** — merge the binding into `wrangler.toml`/`.jsonc`.
+  `migrations_dir` must match `out` in `drizzle.config.ts` or wrangler will not
+  find the SQL drizzle-kit emits:
 
-### Cloudflare D1
-
-`drizzle-kit migrate` does not work against D1 (no TCP). Apply migrations
-via `wrangler d1 migrations apply <db-name>`, split into local vs remote so
-you can iterate safely against the miniflare D1 before touching production:
-
-```json
-{
-  "scripts": {
-    "db:generate":      "drizzle-kit generate",
-    "db:migrate:local": "wrangler d1 migrations apply <db-name> --local",
-    "db:migrate:remote": "wrangler d1 migrations apply <db-name> --remote",
-    "db:studio":        "drizzle-kit studio"
-  }
-}
-```
-
-Replace `<db-name>` with the `database_name` from `wrangler.toml`/`.jsonc`.
-Omit `db:push` for D1 — the migrations-apply flow is the only supported
-path.
+  ```toml
+  [[d1_databases]]
+  binding = "DB"
+  database_name = "my-app"
+  database_id = "<id>"
+  migrations_dir = "drizzle/migrations"
+  ```
 
-## Step 7: Use in a loader
+- **Node / Vercel** — document `DATABASE_URL` in `.env.example`, and add
+  `.env*` to `.gitignore` if it is missing.
 
-Demonstrate the wired-up usage:
+## Step 6: Use it in a loader
 
 ```ts
 import type { LoaderArgs } from "@pracht/core";
@@ -240,77 +182,26 @@ import { users } from "../db/schema";
 
 export async function loader(_args: LoaderArgs) {
   const rows = await db.select().from(users).limit(20);
-  return { users: rows.map(u => ({ id: u.id, email: u.email })) };
+  return { users: rows.map((u) => ({ id: u.id, email: u.email })) };
 }
 ```
 
-Note: explicit projection — never spread DB rows into loader return values
-(see `audit-secrets`).
+Project explicitly — never spread DB rows into loader return values, since
+everything returned crosses the wire (see `/audit-secrets`).
 
-## Step 8: Bindings & env vars
-
-- For Cloudflare adapters with D1: add the binding to `wrangler.toml` (or
-  `wrangler.jsonc`). If the file already exists, diff and merge the binding
-  in — never overwrite the existing config. `migrations_dir` must match the
-  `out` in `drizzle.config.ts` so wrangler finds the SQL drizzle-kit emits:
-  ```toml
-  [[d1_databases]]
-  binding = "DB"
-  database_name = "my-app"
-  database_id = "<id>"
-  migrations_dir = "drizzle/migrations"
-  ```
-- For Node/Vercel: document `DATABASE_URL` in `.env.example`. Add `.env*` to
-  `.gitignore` if missing.
-
-## Step 9: Verify
-
-Non-D1:
-
-```bash
-pnpm db:generate
-pnpm db:push   # or db:migrate after creating one
-```
-
-D1:
+## Step 7: Verify
 
 ```bash
 pnpm db:generate
-pnpm db:migrate:local   # apply to miniflare D1
-# when happy:
-pnpm db:migrate:remote  # apply to production D1
-```
-
-Then:
-
-```bash
+pnpm db:push            # non-D1; or db:migrate once a migration exists
+pnpm db:migrate:local   # D1 — then db:migrate:remote when happy
 pracht verify --json
 pnpm test
 ```
 
-Note: on a fresh project `pnpm test` is a no-op (no tests exist yet) — it
-proves nothing about the DB wiring. Suggest a loader smoke test that calls
-the Step 7 loader with a real (local) DB and asserts on the returned shape,
-or run `scaffold-tests` to set that up.
-
-## Rules
-
-1. Always confirm the adapter ↔ driver compatibility before installing.
-2. Never spread DB rows into loader return values — project explicitly.
-3. For edge runtimes, do not module-cache a connection — use a factory keyed
-   by `context.env`.
-4. In app code, read connection strings via `serverEnv` from
-   `@pracht/core/env/server`, not `process.env`; on Cloudflare, read it
-   inside functions only. (Exception: `drizzle.config.ts` runs under the
-   drizzle-kit CLI on Node, where `process.env` is fine.)
-5. Add `.env*` to `.gitignore` if a connection string is involved.
-6. Recommend a migration workflow (`db:migrate`) over `db:push` for
-   anything beyond local dev.
-7. For D1, apply migrations with `wrangler d1 migrations apply`, not
-   `drizzle-kit migrate` — D1 exposes no TCP endpoint and drizzle-kit will
-   silently fail to connect. Split into `db:migrate:local` and
-   `db:migrate:remote` so the local miniflare DB can be iterated without
-   touching production. Ensure `migrations_dir` in `wrangler.toml` matches
-   `out` in `drizzle.config.ts`.
+On a fresh project `pnpm test` is a no-op and proves nothing about the DB
+wiring. Suggest a loader smoke test that calls the Step 6 loader against a real
+local DB and asserts the returned shape, or run `/scaffold-tests` to set that
+up.
 
 $ARGUMENTS