create-ailk 0.15.0 → 0.17.0

package/templates/database/scripts/person-backfill.sql

@@ -0,0 +1,132 @@
+-- #852 — the Person backfill (spec
+-- docs/specs/852-person-the-per-workspace-client-spec.md D2, D4).
+--
+-- Fills "people" from the rows the hub already holds and stamps
+-- leads.person_id and appointments.person_id, so the People list is not
+-- empty on the day it ships. Set-based and idempotent: every insert is
+-- ON CONFLICT DO NOTHING and every update is guarded by IS NULL, so running
+-- this text twice changes nothing the first run wrote.
+--
+-- THE SAME TEXT, byte for byte, is database/scripts/person-backfill.sql. The
+-- previous deployment keeps writing leads and appointments without a
+-- person_id between this migration and the cutover to the new code; run
+-- that script ONCE against the hub database after the cutover to stamp them.
+-- database/__tests__/person.db.test.ts asserts the two files are identical
+-- and that a second run changes no row.
+--
+-- Normalization — the SQL twin of apps/api/src/services/person.ts's
+-- normalizePersonEmail / isStorablePersonEmail:
+--   N(x)     = lower(btrim(x, E' \t\n\r\f\x0B') COLLATE "C")
+--              (\x0B is vertical tab; an E-string has no \v escape — E'\v'
+--              is the letter v, which would strip the v of every .dev)
+--   VALID(e) = e ~ '^[!-?A-~]+@[!-?A-~]+$' AND length(e) <= 254
+--   NAME(x)  = C0/C1 controls and bidi controls removed, trimmed, cut to
+--              200 characters; empty → NULL
+-- A row whose email is not VALID makes no Person and keeps person_id NULL.
+--
+-- Sources, in order: leads (oldest first), then completed hub FlowCheckouts
+-- through their lead (the customer id, first writer wins), then appointments
+-- by attendee email. Subscriber is NOT a source; FlowSession, ProjectListing
+-- and DeliverableGrant reach a Person through their lead at read time.
+-- The join to "users" reads the auth namespace inside this one-off
+-- statement only; it adds no foreign key (ADR 0009 invariant 1).
+--
+-- Rollback: nothing to undo on its own — dropping 20261010120000_person's
+-- table and columns removes everything this wrote.
+
+-- 1. Leads, oldest first: one Person per (workspace, normalized email). The
+--    name is the oldest lead's payload.name when it is a JSON string.
+INSERT INTO "people" ("workspace_id", "email", "name", "created_at", "updated_at")
+SELECT DISTINCT ON (l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"))
+       l."workspace_id",
+       lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"),
+       CASE WHEN jsonb_typeof(l."payload" -> 'name') = 'string'
+            THEN NULLIF(left(btrim(regexp_replace(l."payload" ->> 'name', '[\x01-\x1F\x7F-\x9F\u200E\u200F\u202A-\u202E\u2066-\u2069]', '', 'g')), 200), '')
+       END,
+       l."created_at",
+       now()
+FROM "leads" l
+WHERE lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C") ~ '^[!-?A-~]+@[!-?A-~]+$'
+  AND length(lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C")) <= 254
+ORDER BY l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"), l."created_at" ASC, l."id" ASC
+ON CONFLICT ("workspace_id", "email") DO NOTHING;
+
+-- 2. Hub FlowCheckouts, through their lead (same workspace): the oldest
+--    completed checkout with a customer id writes it onto a Person that has
+--    none. First writer wins — oldest by completed_at, then created_at, then id.
+UPDATE "people" p
+SET "billing_provider" = 'stripe',
+    "billing_customer_id" = c."stripe_customer_id",
+    "updated_at" = now()
+FROM (
+  SELECT DISTINCT ON (fc."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"))
+         fc."workspace_id",
+         lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C") AS "email",
+         fc."stripe_customer_id"
+  FROM "flow_checkouts" fc
+  JOIN "leads" l ON l."id" = fc."lead_id" AND l."workspace_id" = fc."workspace_id"
+  WHERE fc."status" = 'completed'
+    AND fc."stripe_customer_id" IS NOT NULL
+    AND fc."stripe_customer_id" <> ''
+    AND length(fc."stripe_customer_id") <= 255
+  ORDER BY fc."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"),
+           fc."completed_at" ASC NULLS LAST, fc."created_at" ASC, fc."id" ASC
+) c
+WHERE p."workspace_id" = c."workspace_id"
+  AND p."email" = c."email"
+  AND p."billing_customer_id" IS NULL;
+
+-- 3. Appointments, by attendee email: a Person a lead already made keeps its
+--    lead-derived name and created_at (ON CONFLICT DO NOTHING).
+INSERT INTO "people" ("workspace_id", "email", "name", "created_at", "updated_at")
+SELECT DISTINCT ON (a."workspace_id", lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C"))
+       a."workspace_id",
+       lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C"),
+       NULLIF(left(btrim(regexp_replace(a."attendee_name", '[\x01-\x1F\x7F-\x9F\u200E\u200F\u202A-\u202E\u2066-\u2069]', '', 'g')), 200), ''),
+       a."created_at",
+       now()
+FROM "appointments" a
+WHERE lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C") ~ '^[!-?A-~]+@[!-?A-~]+$'
+  AND length(lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C")) <= 254
+ORDER BY a."workspace_id", lower(btrim(a."attendee_email", E' \t\n\r\f\x0B') COLLATE "C"), a."created_at" ASC, a."id" ASC
+ON CONFLICT ("workspace_id", "email") DO NOTHING;
+
+-- 4. Stamps: every lead and appointment with a storable email points at its
+--    workspace's Person; a row already stamped is left alone.
+UPDATE "leads"
+SET "person_id" = p."id"
+FROM "people" p
+WHERE "leads"."person_id" IS NULL
+  AND p."workspace_id" = "leads"."workspace_id"
+  AND p."email" = lower(btrim("leads"."email", E' \t\n\r\f\x0B') COLLATE "C");
+
+UPDATE "appointments"
+SET "person_id" = p."id"
+FROM "people" p
+WHERE "appointments"."person_id" IS NULL
+  AND p."workspace_id" = "appointments"."workspace_id"
+  AND p."email" = lower(btrim("appointments"."attendee_email", E' \t\n\r\f\x0B') COLLATE "C");
+
+-- 5. user_id, verified only: the oldest promoted lead (by promoted_at, then
+--    created_at, then id) whose user is email-verified and whose verified
+--    address normalizes to the Person's. An unverified or differing user is
+--    never copied — the rule stampPersonUser applies to new rows.
+UPDATE "people" p
+SET "user_id" = c."user_id",
+    "updated_at" = now()
+FROM (
+  SELECT DISTINCT ON (l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"))
+         l."workspace_id",
+         lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C") AS "email",
+         l."promoted_user_id" AS "user_id"
+  FROM "leads" l
+  JOIN "users" u ON u."id" = l."promoted_user_id"
+  WHERE l."promoted_user_id" IS NOT NULL
+    AND u."email_verified" = true
+    AND lower(btrim(u."email", E' \t\n\r\f\x0B') COLLATE "C") = lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C")
+  ORDER BY l."workspace_id", lower(btrim(l."email", E' \t\n\r\f\x0B') COLLATE "C"),
+           l."promoted_at" ASC NULLS LAST, l."created_at" ASC, l."id" ASC
+) c
+WHERE p."workspace_id" = c."workspace_id"
+  AND p."email" = c."email"
+  AND p."user_id" IS NULL;

package/templates/database/tenancy.ts

@@ -128,3 +128,56 @@ export async function resolveSentinelWorkspaceRow(
   }
   return { id: DEFAULT_WORKSPACE_ID, organizationId: workspace.organizationId };
 }
+
+// ---------------------------------------------------------------------------
+// #852 D7 — the Person timeline's pre-migration email fallback.
+//
+// A FlowSession or ProjectListing written before the Person backfill and
+// never tied to a lead (`lead_id IS NULL`) reaches its Person only by email.
+// These three SQL texts are the ONLY way that match is made: run by
+// `apps/api/src/lib/tenant-db.ts`'s `people.timeline` through
+// `$queryRawUnsafe(SQL, email, workspaceId, cutoff)`, and executed verbatim
+// against live Postgres by `database/__tests__/person.db.test.ts` — one
+// string, proven where it runs. `$n` placeholders only, never interpolation.
+//
+// The match is EXACT equality of the normalized column against the Person's
+// stored (already-normalized) email — never Prisma's `mode: "insensitive"`,
+// which compiles to ILIKE: `_`/`%` would act as wildcards and non-ASCII case
+// would fold, joining another client's rows (SEC-852-B). The normalization is
+// the backfill's N(x) (database/migrations/20261010121000_person_backfill).
+//
+// `$3` is the cutoff: `finished_at` of the backfill migration's
+// `_prisma_migrations` row (`PERSON_CUTOFF_SQL`). That column is timestamptz;
+// the inbox `created_at` columns are timestamp(3) holding UTC (Prisma's
+// convention), so the comparison converts the cutoff to UTC wall time. Only
+// rows strictly older than the cutoff qualify. Each returns ids only, at most
+// 50, newest first; the caller re-reads them through its scoped findMany.
+// ---------------------------------------------------------------------------
+
+/** The `_prisma_migrations` key whose `finished_at` is the fallback cutoff. */
+export const PERSON_BACKFILL_MIGRATION = "20261010121000_person_backfill";
+
+/** `$1` = the Person's email, `$2` = workspace id, `$3` = the cutoff. */
+export const PERSON_FALLBACK_FLOW_SESSIONS_SQL = String.raw`SELECT "id" FROM "flow_sessions"
+WHERE "workspace_id" = $2::text
+  AND "lead_id" IS NULL
+  AND "created_at" < ($3::timestamptz AT TIME ZONE 'UTC')
+  AND lower(btrim("email", E' \t\n\r\f\x0B') COLLATE "C") = $1::text
+ORDER BY "created_at" DESC, "id" DESC
+LIMIT 50`;
+
+/** `$1` = the Person's email, `$2` = workspace id, `$3` = the cutoff. */
+export const PERSON_FALLBACK_PROJECT_LISTINGS_SQL = String.raw`SELECT "id" FROM "project_listings"
+WHERE "workspace_id" = $2::text
+  AND "lead_id" IS NULL
+  AND "created_at" < ($3::timestamptz AT TIME ZONE 'UTC')
+  AND lower(btrim("founder_email", E' \t\n\r\f\x0B') COLLATE "C") = $1::text
+ORDER BY "created_at" DESC, "id" DESC
+LIMIT 50`;
+
+/** The cutoff read: the backfill's `finished_at`, or no row when it has not run. */
+export const PERSON_CUTOFF_SQL = `SELECT "finished_at" FROM "_prisma_migrations"
+WHERE "migration_name" = '20261010121000_person_backfill'
+  AND "finished_at" IS NOT NULL
+  AND "rolled_back_at" IS NULL
+LIMIT 1`;

package/templates/tools/check-declared-env.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env tsx
+/**
+ * Declared-env check — fails when this site's code reads an environment
+ * variable that `project.yaml` does not declare.
+ *
+ * Every literal `process.env` read in the site's source (tests, stories and
+ * this `tools/` directory excepted) needs a row in `project.yaml`'s
+ * `env_contract` block: a `name`, a one-line `description`, and
+ * `secret: true` or `false`. Platform names (`NODE_ENV`, `CI`, `VERCEL_*`, …)
+ * need none. On a spoke (`.ailk-site-manifest.json` records
+ * `"topology": "spoke"`), `NEXT_PUBLIC_AILK_API_URL` is refused outright:
+ * a spoke's hub origin is server-only, so read `AILK_API_URL` instead.
+ *
+ * The scanner is `tools/declared-env.ts`, a copy of create-ailk's own, which
+ * writes this site's rows when it adds a module or a route. Add a row by hand
+ * for a variable you add; create-ailk never edits or removes one.
+ *
+ * Usage:
+ *   pnpm env:declared          # or: tsx tools/check-declared-env.ts
+ *
+ * Exit codes:
+ *   0 — every read is declared
+ *   1 — an undeclared read, a malformed row, a refused name, or a missing file
+ */
+
+import { dirname, resolve } from "node:path";
+
+import { checkDeclaredEnv } from "./declared-env";
+
+const ROOT = resolve(dirname(process.argv[1] ?? "."), "..");
+
+const { findings, summary } = checkDeclaredEnv(ROOT);
+if (findings.length > 0) {
+  for (const finding of findings) console.error(finding);
+  process.exit(1);
+}
+console.log(summary);