create-ailk 0.7.0 → 0.8.0

package/templates/.claude/skills/setup-database/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: setup-database
+description: Take this site from no database to a working lead inbox — provision Postgres, set the connection variables, create the tables, pin the owner, and prove it with one test message that must appear in the inbox. Use when the user asks "set up the database", "I want a lead inbox", "keep my leads", "collect newsletter signups", "connect Postgres", or when setup-deploy points here. Confirms before every write and never prints a connection string.
+---
+
+# setup-database
+
+A new site needs no database: contact-form messages are emailed to the
+owner (when the email key is set). A database turns on the **lead inbox**
+— every message kept at `/leads`, reviewed signed in — and newsletter
+signups. This skill takes the site from no database to that inbox, and
+does not call it done until one test message is in it.
+
+## When to use
+
+- "set up the database" / "connect Postgres"
+- "I want a lead inbox" / "keep every message"
+- "collect newsletter signups"
+- `setup-deploy` pointed here from its lead-delivery step
+
+Skip it when the site only needs messages by email — that is
+`setup-deploy`'s email key, no database required.
+
+## Rules for every step
+
+- **Confirm before every write.** Say what file or command is next and
+  wait for a yes.
+- **Never echo a connection string.** A database URL contains a
+  password. Refer to it as "your `DATABASE_URL`", never print it, never
+  commit it. It goes in `.env.local` (gitignored) and the hosting
+  dashboards only.
+- **Stop on the first failure** and say which step failed and why
+  (see "When a step fails"). Never skip ahead.
+
+## The mechanic
+
+### Step 1 — Detect
+
+Look for `DATABASE_URL` in `.env.local`, then `.env`. If it is already
+set, say so (without printing it) and go to Step 4.
+
+### Step 2 — Provision Postgres
+
+Ask which Postgres the owner wants. Any provider that gives a **pooled**
+and a **direct** connection URL works (Neon, Supabase, Railway, RDS, …).
+For local work, the one command in `README.md` § "When you need a
+database":
+
+```bash
+docker run --name ailk-postgres -e POSTGRES_PASSWORD=postgres -p 5432:5432 -d postgres:17
+```
+
+The owner pastes the two URLs. Write them to `.env.local` only:
+
+```bash
+DATABASE_URL=<pooled URL>
+DATABASE_URL_NON_POOLED=<direct URL>
+```
+
+(Local Docker: the same URL for both.) Then tell the owner to add the
+same two variables to **both** hosting projects — the API's (it stores
+the leads) and the web app's (sign-in reads the database). Placeholders
+only in any file you show; the real values go in each dashboard.
+
+### Step 3 — Create the tables, then the default workspace
+
+```bash
+pnpm db:migrate:deploy
+```
+
+```bash
+pnpm db:seed
+```
+
+The seed creates the default Organization and Workspace every lead is
+filed under. Without it the API answers `503 tenant_unresolved` to every
+submission.
+
+### Step 4 — Pin the owner, and make sure they can sign in
+
+The inbox shows leads only to the site's pinned owner. Ask for the
+email address the owner signs in with and set it — in `.env.local`, and
+on the API project's dashboard:
+
+```bash
+AILK_OPERATOR_EMAIL=you@your-domain.com
+```
+
+The owner must sign in with that address, and it must be verified by
+the sign-in provider. If no sign-in provider is configured yet, hand off
+to the `add-auth` skill now — the inbox is behind sign-in — and come
+back to Step 5 when it is done.
+
+### Step 5 — Send one test message
+
+Make a nonce (for example `setup-database 3f9c2a`, a few random
+characters) and submit a lead to the running API (`pnpm dev` locally,
+or the deployed API's URL):
+
+```bash
+curl -sS -X POST <api>/v1/leads/submit \
+  -H 'content-type: application/json' \
+  -d '{"source":"web","email":"<owner email>","payload":{"name":"setup-database test","message":"<nonce>"}}'
+```
+
+It must answer **`201`** with `"persisted": "db"`. Anything else is a
+failed step (see below).
+
+### Step 6 — Verify it is in the inbox
+
+Build the database package once (its `./tenancy` export resolves to
+`dist/`), then read the inbox with the inbox's own rule — the default
+workspace, newest first, the first page of 50:
+
+```bash
+pnpm --filter @working-theory/database build
+pnpm --filter @working-theory/database exec tsx ../.claude/skills/setup-database/scripts/verify-inbox.ts "<nonce>"
+```
+
+It prints `found in inbox` and exits 0 only when the test lead is on
+that page. Then ask the owner to open `/leads`, signed in as the pinned
+email, and confirm they see the "setup-database test" row.
+
+Do not report the database as set up until verify-inbox.ts exits 0.
+
+## When a step fails
+
+Say which step failed and the likely cause — never "done":
+
+| Symptom                                     | Likely cause                                                                                   |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `db:migrate:deploy` cannot connect          | wrong `DATABASE_URL_NON_POOLED`, or the database is not reachable from here                    |
+| submit answers `503 tenant_unresolved` (or, with `CONTENT_ADAPTER=database`, the API refuses to start) | Step 3's `pnpm db:seed` did not run |
+| submit answers `201` with `persisted` ≠ `db` | the API process does not see `DATABASE_URL` — restart it, or set it on the API project        |
+| verify-inbox exits 1                        | the lead landed under another workspace, or 50 newer leads push it off the first page          |
+| `/leads` is empty but verify passed         | `AILK_OPERATOR_EMAIL` unset, a different or unverified sign-in email, or more than one workspace |
+
+## What this skill does not do
+
+- Call a database vendor's API. The owner provisions; the skill walks
+  them through it.
+- Print, log or commit a connection string.
+- Change application code. The API switches to the inbox by itself once
+  `DATABASE_URL` is set.
+
+## Coordination
+
+- **`setup-deploy`** — its lead-delivery step points here, and its
+  `RUNBOOK.md` names this skill as the **Lead inbox** path.
+- **`add-auth`** — the inbox is behind sign-in; Step 4 hands off to it
+  when no provider is configured.
+
+## Files
+
+- `scripts/verify-inbox.ts` — Step 6's read. Exports `findInInbox`
+  (pure, takes an injected Prisma-shaped client) and a thin `main()`.

package/templates/.claude/skills/setup-database/scripts/verify-inbox.ts

@@ -0,0 +1,154 @@
+/**
+ * verify-inbox — the last step of the `setup-database` skill.
+ *
+ * Proves the test lead the skill just submitted is in the lead inbox, by
+ * reading with the inbox's own predicate: `Lead.siteId` = the default
+ * workspace id, newest first, the first page of 50 — exactly what `/leads`
+ * shows. A lead that exists somewhere else in the table does not count.
+ *
+ * Run inside the scaffold's `database` workspace, which owns the Prisma client
+ * and its driver adapter. The script's own imports resolve from the WORKING
+ * directory (`resolveFromWorkspace`), not from where this file sits — the
+ * scaffold root depends on neither package. Build it first — the `./tenancy`
+ * export resolves to `dist/`:
+ *
+ *   pnpm --filter @working-theory/database build
+ *   pnpm --filter @working-theory/database exec tsx ../.claude/skills/setup-database/scripts/verify-inbox.ts <nonce>
+ *
+ * Exit 0, printing `found in inbox`, only when the nonce's lead is on that
+ * page. Exit 1 when it is not; exit 2 on a usage error. Reads only — writes
+ * nothing, and prints no lead field but the match.
+ */
+
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * Import `specifier` as the package at `cwd` sees it. A bare `import()` here
+ * would resolve from this file's own directory (`.claude/skills/…`), where
+ * the scaffold installs neither `@working-theory/database` nor its adapter;
+ * resolving against `<cwd>/package.json` finds the `database` workspace's own
+ * dependencies and its self-reference.
+ */
+export function resolveFromWorkspace(specifier: string, cwd: string = process.cwd()): string {
+  return createRequire(join(cwd, "package.json")).resolve(specifier);
+}
+
+async function importFromWorkspace<T>(specifier: string): Promise<T> {
+  return (await import(pathToFileURL(resolveFromWorkspace(specifier)).href)) as T;
+}
+
+/** The inbox's first page (`GET /v1/leads`'s default `limit`). */
+export const INBOX_PAGE_SIZE = 50;
+
+interface LeadRow {
+  id: string;
+  payload: unknown;
+}
+
+/** The one Prisma call this script makes — injected, so it is testable without a database. */
+export interface InboxReader {
+  lead: {
+    findMany(args: {
+      where: { siteId: string };
+      orderBy: Array<Record<string, "desc">>;
+      take: number;
+      select: { id: true; payload: true };
+    }): Promise<LeadRow[]>;
+  };
+}
+
+function carriesNonce(payload: unknown, nonce: string): boolean {
+  if (typeof payload !== "object" || payload === null) return false;
+  const message = (payload as Record<string, unknown>)["message"];
+  return typeof message === "string" && message.includes(nonce);
+}
+
+/** Whether the lead whose message carries `nonce` is on the inbox's first page. */
+export async function findInInbox(
+  db: InboxReader,
+  { workspaceId, nonce }: { workspaceId: string; nonce: string },
+): Promise<boolean> {
+  const page = await db.lead.findMany({
+    where: { siteId: workspaceId },
+    orderBy: [{ createdAt: "desc" }, { id: "desc" }],
+    take: INBOX_PAGE_SIZE,
+    select: { id: true, payload: true },
+  });
+  return page.some((row) => carriesNonce(row.payload, nonce));
+}
+
+/** `findInInbox` as a process result: 0 + `found in inbox`, or 1 + the reason. */
+export async function verifyInbox(
+  db: InboxReader,
+  args: { workspaceId: string; nonce: string },
+  out: (line: string) => void = (line) => process.stdout.write(`${line}\n`),
+): Promise<0 | 1> {
+  if (await findInInbox(db, args)) {
+    out("found in inbox");
+    return 0;
+  }
+  out(
+    "not in inbox: no lead carrying this nonce is on the default workspace's first page. " +
+      "Check that `pnpm db:seed` ran (else the API answers tenant_unresolved) and that " +
+      "the test submission returned 201 with persisted \"db\".",
+  );
+  return 1;
+}
+
+async function main(argv: string[]): Promise<number> {
+  const nonce = argv[0];
+  if (!nonce) {
+    process.stderr.write("usage: verify-inbox.ts <nonce>\n");
+    return 2;
+  }
+  // DATABASE_URL lives in the scaffold root's `.env.local` (setup-database
+  // writes it there); this runs from `database/`, one level down.
+  for (const file of ["../.env.local", "../.env"]) {
+    if (process.env.DATABASE_URL) break;
+    try {
+      process.loadEnvFile(file);
+    } catch {
+      // absent — try the next one
+    }
+  }
+  if (!process.env.DATABASE_URL) {
+    process.stderr.write("verify-inbox: DATABASE_URL is not set (.env.local)\n");
+    return 1;
+  }
+  // Resolved inside the scaffold's `database` workspace (see the header).
+  // Prisma 7 needs an explicit driver adapter, as `database/seed.ts` does.
+  const [{ PrismaClient }, { PrismaPg }, { DEFAULT_WORKSPACE_ID }] = await Promise.all([
+    importFromWorkspace<{
+      PrismaClient: new (opts: { adapter: unknown }) => InboxReader & {
+        $disconnect(): Promise<void>;
+      };
+    }>("@working-theory/database"),
+    importFromWorkspace<{ PrismaPg: new (opts: { connectionString: string }) => unknown }>(
+      "@prisma/adapter-pg",
+    ),
+    importFromWorkspace<{ DEFAULT_WORKSPACE_ID: string }>("@working-theory/database/tenancy"),
+  ]);
+  const prisma = new PrismaClient({
+    adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL }),
+  });
+  try {
+    return await verifyInbox(prisma, {
+      workspaceId: DEFAULT_WORKSPACE_ID,
+      nonce,
+    });
+  } finally {
+    await prisma.$disconnect();
+  }
+}
+
+if (/verify-inbox\.ts$/.test(process.argv[1] ?? "")) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (err: unknown) => {
+      process.stderr.write(`verify-inbox: ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exit(1);
+    },
+  );
+}

package/templates/.claude/skills/setup-deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-deploy
-description: Emit deploy configuration for an AILK consumer site — `vercel.json`, `.env.example`, and `RUNBOOK.md`. Vercel-only at v1; other platforms reject with a clear "not yet supported" message. Use when the user asks "set up Vercel", "provision deploy config", "what env vars do I need for production?", "I'm ready to ship to Vercel", or otherwise asks about pre-deploy file setup. The RUNBOOK includes the three named persistence-upgrade paths for leads.jsonl (Vercel KV / Supabase / Postgres-via-`@working-theory/database`).
+description: Emit deploy configuration for an AILK consumer site — `vercel.json`, `.env.example`, and `RUNBOOK.md`. Vercel-only at v1; other platforms reject with a clear "not yet supported" message. Use when the user asks "set up Vercel", "provision deploy config", "what env vars do I need for production?", "I'm ready to ship to Vercel", or otherwise asks about pre-deploy file setup. Asks where leads should go — the email key (`RESEND_API_KEY` + the two notification addresses) or a database (`setup-database`) — and warns when neither is set. The RUNBOOK documents the two lead destinations: Email (default) and Lead inbox (setup-database).
 ---
 
 # setup-deploy
@@ -42,9 +42,11 @@ Skip this skill when:
   (merge / overwrite / skip) before writing.
 - Emit the three artifacts at the consumer's project root, derived
   from templates in `references/`.
+- Ask where leads go (Step 5a) — the email key, or a database via
+  `setup-database` — and warn, verbatim, when neither is set.
 - Validate the emitted output (parse `vercel.json` as JSON, check
   `.env.example` covers required vars, confirm `RUNBOOK.md` has the
-  three named persistence-upgrade headings).
+  two lead-destination headings).
 
 **Does not:**
 
@@ -70,9 +72,7 @@ platform, respond:
 > if your platform is missing.
 >
 > Cloudflare is deferred entirely (deploy target + KV/D1/R2 data
-> layer) as a coherent follow-up. CF requires different default
-> persistence per platform because Workers lack the Node `fs` API
-> the JSONL fallback depends on."
+> layer) as a coherent follow-up."
 
 Then stop. Do not emit any files.
 
@@ -102,9 +102,9 @@ Wait for the consumer's choice per file. Do not blindly overwrite.
 file, append it (with comment) at the bottom under a "## Added by
 setup-deploy" section. Vars already present are not modified.
 
-**Merge logic — `RUNBOOK.md`:** if any of the three named
-persistence sections (Vercel KV, Supabase,
-Postgres-via-`@working-theory/database`) is missing from the existing file,
+**Merge logic — `RUNBOOK.md`:** if the "Leads — where messages go"
+section (with its two headings, `Email (default)` and
+`Lead inbox (setup-database)`) is missing from the existing file,
 append it at the end. Existing sections are not modified.
 
 **Merge logic — `vercel.json`:** **not supported.** `vercel.json` is
@@ -147,6 +147,34 @@ the template's expected count. If a var the consumer's site uses
 template, add it under "## Added by setup-deploy" — never silently
 omit a var the consumer needs.
 
+### Step 5a — Lead delivery
+
+Where a contact-form message goes is decided by the API project's
+environment (RUNBOOK § "Leads — where messages go"). Ask the consumer
+two questions:
+
+1. **Will this site use a database?** If yes, point them to the
+   `setup-database` skill — it provisions Postgres, sets
+   `DATABASE_URL`, runs migrations and verifies a test lead reaches
+   the inbox. Do not collect a connection string here.
+2. **What email should messages go to?** Ask for
+   `RESEND_API_KEY`, `AILK_LEAD_NOTIFICATION_TO` (their address) and
+   `AILK_LEAD_NOTIFICATION_FROM` (a sender on their Resend-verified
+   domain). All three are needed — a key alone sends nothing. Write
+   **placeholders only** into `.env.example`; tell the consumer to set
+   the real values in the **API** project's dashboard. Never write a
+   key into a file.
+
+If the consumer provides neither a database nor all three email
+values, print this, verbatim:
+
+> ⚠ No lead destination is set. In production your contact page will show
+> your contact email instead of the form, and no messages will be collected.
+> Run setup-database, or set RESEND_API_KEY, AILK_LEAD_NOTIFICATION_TO and
+> AILK_LEAD_NOTIFICATION_FROM on the API project.
+
+Then continue — the warning does not stop the deploy config.
+
 ### Step 6 — Emit `RUNBOOK.md`
 
 Use the template at `references/runbook-template.md`. The emitted
@@ -154,26 +182,24 @@ runbook has these sections:
 
 1. **Pre-deploy checklist** — what to set in Vercel's project
    dashboard before clicking Deploy.
-2. **Operations — leads.jsonl persistence** — the **critical**
-   section. AILK's lead-capture writes JSONL to
-   `apps/api/leads.jsonl`, which **does not persist** on Vercel's
-   ephemeral filesystem. Consumer must pick a persistence backend
-   before going live or leads disappear on cold-start.
-3. **Persistence upgrade — Vercel KV** — drop-in, no new infra,
-   cheapest fix. When to pick.
-4. **Persistence upgrade — Supabase** — Postgres + auth + storage
-   in one provider. When to pick.
-5. **Persistence upgrade — Postgres via `@working-theory/database`** — for
-   consumers who already have Postgres elsewhere (Neon, Railway,
-   RDS). When to pick.
-6. **Custom domain + DNS** — pointer at Vercel's domain docs.
-7. **Production callbacks for OAuth** — for consumers who used
+2. **Leads — where messages go** — the two lead destinations, in
+   plain words:
+   - **Email (default)** — no database; each message is emailed to
+     the owner (`RESEND_API_KEY`, `AILK_LEAD_NOTIFICATION_TO`,
+     `AILK_LEAD_NOTIFICATION_FROM` on the API project).
+   - **Lead inbox (setup-database)** — `DATABASE_URL` set; messages
+     land in `/leads` and newsletter signups are collected.
+   With neither, production `/contact` shows the site's contact email
+   instead of the form. On a non-Vercel host, the API process needs
+   `NODE_ENV=production`.
+3. **Custom domain + DNS** — pointer at Vercel's domain docs.
+4. **Production callbacks for OAuth** — for consumers who used
    `add-auth` and need to register prod redirect URIs.
 
-After write, grep the RUNBOOK for the three named persistence
-section headings (Vercel KV, Supabase,
-Postgres-via-`@working-theory/database`). All three must be present. If any
-is missing, the skill has a bug — flag with the literal error.
+After write, grep the RUNBOOK for the two lead-destination headings
+(`Email (default)`, `Lead inbox (setup-database)`). Both must be
+present. If either is missing, the skill has a bug — flag with the
+literal error.
 
 ### Step 7 — Closing summary
 
@@ -181,8 +207,9 @@ Print:
 
 - Which artifacts were emitted vs skipped (per consumer's Step 3
   choices).
-- A pointer to `RUNBOOK.md`'s leads-persistence section (the
-  highest-stakes operational caveat).
+- Where leads will go (email, the lead inbox, or — with the Step 5a
+  warning repeated — nowhere), with a pointer to `RUNBOOK.md`'s
+  "Leads — where messages go" section.
 - A reminder that Vercel project-level env-vars need to be set in
   the Vercel dashboard before deploy — `.env.example` is the
   contract, not the values.
@@ -203,8 +230,10 @@ Before reporting "done":
 
 - `vercel.json` parses as JSON ✓
 - `.env.example` declares >= the count of vars in the template ✓
-- `RUNBOOK.md` contains all three named persistence section
-  headings ✓
+- `RUNBOOK.md` contains both lead-destination headings
+  (`Email (default)`, `Lead inbox (setup-database)`) ✓
+- Step 5a ran: the consumer chose a lead destination, or saw the
+  no-destination warning ✓
 
 If any check fails, surface the failure to the consumer (not silent).
 
@@ -223,11 +252,14 @@ If any check fails, surface the failure to the consumer (not silent).
 - `references/vercel-json-template.md` — minimal viable `vercel.json`.
 - `references/env-vars-template.md` — `.env.example` structure with
   placeholder values per category.
-- `references/runbook-template.md` — `RUNBOOK.md` with the three
-  named persistence-upgrade sections.
+- `references/runbook-template.md` — `RUNBOOK.md` with the two lead
+  destinations (Email (default), Lead inbox (setup-database)).
 
 ## Coordination
 
+- **`setup-database`** — takes a site from no database to a working
+  lead inbox. Step 5a hands off to it; this skill never collects a
+  connection string.
 - **`add-auth`** — produces its own `RUNBOOK.md`
   sections for OAuth setup (dev callback URLs). This skill's
   RUNBOOK adds production callback URLs and merges with any

package/templates/.claude/skills/setup-deploy/references/env-vars-template.md

@@ -28,11 +28,23 @@ CONTENT_BACKEND=mdx
 # Override the content directory. Default is <repo-root>/content.
 # AILK_CONTENT_ROOT=
 
-# ── Database (optional in standalone mode) ───────────────────────
-# Required only if you've installed @working-theory/database for persistent
-# leads, sessions, or other data. See RUNBOOK.md § "Persistence
-# upgrade — Postgres via @working-theory/database" for setup.
+# ── Lead delivery ────────────────────────────────────────────────
+# Where contact-form messages go (RUNBOOK.md § "Leads — where
+# messages go"). Set these on the API project.
+#
+# Lead inbox — set by the `setup-database` skill. With it, messages
+# land in /leads and newsletter signups are collected.
 # DATABASE_URL=postgres://user:pass@host:5432/db
+# DATABASE_URL_NON_POOLED=postgres://user:pass@host:5432/db
+#
+# Email (default) — with no database, each message is emailed to you.
+# All three are required; a key alone sends nothing.
+# RESEND_API_KEY=
+# AILK_LEAD_NOTIFICATION_TO=you@your-domain.com
+# AILK_LEAD_NOTIFICATION_FROM=leads@your-domain.com
+#
+# With neither, /contact shows your contact email (content/_site.mdx
+# `contactEmail`) instead of the form in production.
 
 # ── Auth — required env vars ─────────────────────────────────────
 # Set to "1" to require sign-in for protected routes; default is
@@ -78,11 +90,6 @@ CONTENT_BACKEND=mdx
 # Webhooks → <endpoint> → Signing secret. Format: whsec_*.
 # STRIPE_WEBHOOK_SECRET=
 
-# ── Email provider (Resend) ──────────────────────────────────────
-# Used by transactional senders outside auth (e.g., contact form).
-# Same Resend account as magic-link if both are configured.
-# RESEND_API_KEY=
-
 # ── Analytics — all off by default ───────────────────────────────
 # Each provider is independent. Set the env var(s) to enable.
 #
@@ -105,26 +112,11 @@ CONTENT_BACKEND=mdx
 # Get the token from search.google.com/search-console → Settings →
 # Ownership verification → HTML tag. Paste only the content="..." value.
 # GOOGLE_SITE_VERIFICATION=
-
-# ── Persistent leads (optional) ──────────────────────────────────
-# By default, leads.jsonl is written to apps/api/leads.jsonl. On
-# Vercel's ephemeral filesystem this does NOT persist across cold
-# starts. See RUNBOOK.md § "Persistence upgrade" for the three
-# named upgrade paths.
-#
-# Vercel KV (drop-in):
-# KV_REST_API_URL=
-# KV_REST_API_TOKEN=
-#
-# Supabase (Postgres + auth + storage):
-# NEXT_PUBLIC_SUPABASE_URL=
-# NEXT_PUBLIC_SUPABASE_ANON_KEY=
-# SUPABASE_SERVICE_ROLE_KEY=
 ```
 
 ## Categories the skill emits
 
-The template above groups vars into seven categories. Every emitted
+The template above groups vars into six categories. Every emitted
 `.env.example` should hit each category at least with its header
 comment, even if the consumer hasn't activated any vars in that
 category — the comment block tells future-them what's available.
@@ -133,11 +125,10 @@ Categories:
 
 1. Marketing / canonical domain
 2. Content backend
-3. Database (optional)
+3. Lead delivery (database or email)
 4. Auth — required + per-provider
 5. Stripe (sandbox-only)
-6. Email + Analytics
-7. Persistent leads (optional)
+6. Analytics
 
 ## What the skill never includes