create-ailk 0.2.0 → 0.3.0

package/templates/apps/api/src/routes/project-listings/__tests__/site-answers.test.ts

@@ -1,3 +1,6 @@
+// Not marked oss: false (D-48/#5366 escalation) — tests the
+// always-shipping project-listings anonymous surface; see
+// routes/project-listings/me.ts's header comment.
 /**
  * @file site-answers.test.ts
  *
@@ -243,6 +246,13 @@ function installStore(): void {
       addressCountry: null,
       questions: null,
       siteAnswers: null,
+      // #5407 — a row written before the columns existed, and a freshly
+      // started draft on a site that asks for one name line: parts null,
+      // no phone, no verification stamp.
+      founderFirstName: null,
+      founderLastName: null,
+      founderPhone: null,
+      emailVerifiedAt: null,
       founderCompany: null,
       leadId: null,
       headline: null,

package/templates/apps/api/src/routes/project-listings/__tests__/site-key.test.ts

@@ -1,3 +1,6 @@
+// Not marked oss: false (D-48/#5366 escalation) — tests the
+// always-shipping project-listings anonymous surface; see
+// routes/project-listings/me.ts's header comment.
 /**
  * @file site-key.test.ts
  *
@@ -28,6 +31,13 @@ jest.mock("../../../lib/prisma.js");
 
 jest.mock("@working-theory/email", () => ({
   sendLeadNotification: jest.fn().mockResolvedValue({ ok: true, messageId: "msg-test" }),
+  // #5406 — `start` now reaches the resume email. Declared here for the reason
+  // docs/lessons/project-listings/04 records: a mock factory that omits an
+  // export the code under test calls leaves it `undefined` at the callsite.
+  // These suites configure no `resumeEmail`, so the send short-circuits before
+  // this is reached; it is declared so a future fixture that DOES configure
+  // one fails on its assertion rather than on a missing mock.
+  sendListingResumeEmail: jest.fn().mockResolvedValue({ ok: true, messageId: "msg-resume" }),
 }));
 
 jest.mock("@working-theory/license", () => ({
@@ -136,6 +146,13 @@ function installStore(): void {
       anythingElse: null,
       address: null,
       questions: null,
+      // #5407 — a row written before the columns existed, and a freshly
+      // started draft on a site that asks for one name line: parts null,
+      // no phone, no verification stamp.
+      founderFirstName: null,
+      founderLastName: null,
+      founderPhone: null,
+      emailVerifiedAt: null,
       founderCompany: null,
       leadId: null,
       headline: null,
@@ -186,6 +203,13 @@ function seedActiveListing(siteId: string, slug: string): void {
     address: "1 Founder Way",
     founderName: "Some Founder",
     founderEmail: "founder@example.com",
+    // #5407 — a row written before the columns existed, and a freshly
+    // started draft on a site that asks for one name line: parts null,
+    // no phone, no verification stamp.
+    founderFirstName: null,
+    founderLastName: null,
+    founderPhone: null,
+    emailVerifiedAt: null,
     founderCompany: null,
     questions: null,
     logoMarkUrl: null,

package/templates/apps/api/src/routes/project-listings/__tests__/structured-address.test.ts

@@ -1,3 +1,6 @@
+// Not marked oss: false (D-48/#5366 escalation) — tests the
+// always-shipping project-listings anonymous surface; see
+// routes/project-listings/me.ts's header comment.
 /**
  * @file structured-address.test.ts
  *
@@ -36,6 +39,13 @@ jest.mock("../../../lib/prisma.js");
 
 jest.mock("@working-theory/email", () => ({
   sendLeadNotification: jest.fn().mockResolvedValue({ ok: true, messageId: "msg-test" }),
+  // #5406 — `start` now reaches the resume email. Declared here for the reason
+  // docs/lessons/project-listings/04 records: a mock factory that omits an
+  // export the code under test calls leaves it `undefined` at the callsite.
+  // These suites configure no `resumeEmail`, so the send short-circuits before
+  // this is reached; it is declared so a future fixture that DOES configure
+  // one fails on its assertion rather than on a missing mock.
+  sendListingResumeEmail: jest.fn().mockResolvedValue({ ok: true, messageId: "msg-resume" }),
 }));
 
 jest.mock("@working-theory/license", () => ({
@@ -221,6 +231,13 @@ function installStore(): void {
       addressPostalCode: null,
       addressCountry: null,
       questions: null,
+      // #5407 — a row written before the columns existed, and a freshly
+      // started draft on a site that asks for one name line: parts null,
+      // no phone, no verification stamp.
+      founderFirstName: null,
+      founderLastName: null,
+      founderPhone: null,
+      emailVerifiedAt: null,
       founderCompany: null,
       leadId: null,
       headline: null,

package/templates/apps/api/src/routes/project-listings/index.ts

@@ -6,6 +6,8 @@
  *   POST  /v1/project-listings                      — anonymous start (leadsScope)
  *   PATCH /v1/project-listings/drafts/:id           — anonymous save-as-you-go, token-gated
  *   POST  /v1/project-listings/drafts/:id/submit    — anonymous submit, token-gated
+ *   POST  /v1/project-listings/drafts/:id/verify-email — anonymous, token- AND
+ *                                                     nonce-gated (#5407)
  *   GET   /v1/project-listings/public               — anonymous page-render read (leadsScope)
  *   GET   /v1/project-listings/me                   — the founder's OWN listings (authScope)
  *   GET   /v1/project-listings                      — tenant-scoped dashboard list
@@ -35,16 +37,24 @@
  */
 import type { FastifyPluginAsync } from "fastify";
 
+import { loadSlice } from "../../lib/slice-load.js";
+
 import { projectListingMeRoute as meRoute } from "./me.js";
 import { patchProjectListingDraftRoute } from "./patch-draft.js";
 import { publicProjectListingsRoute } from "./public.js";
 import { startProjectListingRoute } from "./start.js";
 import { submitProjectListingRoute } from "./submit.js";
+import { verifyProjectListingDraftEmailRoute } from "./verify-email.js";
 
 export const projectListingStartRoute = startProjectListingRoute;
 export const projectListingDraftPatchRoute = patchProjectListingDraftRoute;
 export const projectListingSubmitRoute = submitProjectListingRoute;
 export const projectListingPublicRoute = publicProjectListingsRoute;
+/**
+ * The resume link's verification write (#5407). Static, not a slice: it is
+ * part of the free anonymous surface, exactly like the three routes above.
+ */
+export const projectListingVerifyEmailRoute = verifyProjectListingDraftEmailRoute;
 /**
  * The founder's own listings read (#5295). Static, not a slice: it depends on
  * the owner link alone, so it is registered — and works — on a build with no
@@ -62,50 +72,67 @@ export const projectListingMeRoute = meRoute;
  * purpose, which is why the boundary is drawn here at the registration
  * call-site rather than by splitting the directory.
  *
- * The specifier is read from this table rather than written inline because
- * `tsc` resolves a string-literal `import("...")` EXPRESSION whether or not the
- * branch runs, and would report TS2307 on the stripped tree. The plugin body
+ * The specifier is kept off the `import()` call site because `tsc` resolves a
+ * string-literal `import("...")` EXPRESSION whether or not the branch runs, and
+ * would report TS2307 on the stripped tree. It is held in a module-level
+ * constant rather than read out of the table per iteration (#5304): the table
+ * form was invisible to the deploy-time file tracer too, so these files were
+ * compiled and never shipped, and the constant form is the one shape `tsc`
+ * refuses to resolve and `@vercel/nft` still traces. `specifier` stays on each
+ * row for the drift message and reads the same constant as `load`. The plugin body
  * only executes when `server.ts` registers it, which it does inside
  * `isModuleEnabled('multi-tenant')` — so nothing here runs on an OSS build.
  *
  * The export name is unchanged so `server.ts` needs no edit: it still reaches
  * `projectListingTenantRoutes` from this module.
  */
+const LIST_HANDLER = "./list.js";
+const GET_HANDLER = "./get.js";
+const PATCH_HANDLER = "./patch.js";
+const PATCH_COPY_HANDLER = "./patch-copy.js";
+
 const TENANT_HANDLERS: ReadonlyArray<{
   method: "get" | "patch";
   url: string;
   specifier: string;
   exportName: string;
+  load: () => Promise<unknown>;
 }> = [
   {
     method: "get",
     url: "/v1/project-listings",
-    specifier: "./list.js",
+    specifier: LIST_HANDLER,
     exportName: "listProjectListingsHandler",
+    load: () => import(LIST_HANDLER),
   },
   {
     method: "get",
     url: "/v1/project-listings/:id",
-    specifier: "./get.js",
+    specifier: GET_HANDLER,
     exportName: "getProjectListingHandler",
+    load: () => import(GET_HANDLER),
   },
   {
     method: "patch",
     url: "/v1/project-listings/:id",
-    specifier: "./patch.js",
+    specifier: PATCH_HANDLER,
     exportName: "patchProjectListingHandler",
+    load: () => import(PATCH_HANDLER),
   },
   {
     method: "patch",
     url: "/v1/project-listings/:id/copy",
-    specifier: "./patch-copy.js",
+    specifier: PATCH_COPY_HANDLER,
     exportName: "patchProjectListingCopyHandler",
+    load: () => import(PATCH_COPY_HANDLER),
   },
 ];
 
-export const projectListingTenantRoutes: FastifyPluginAsync = async (fastify) => {
-  for (const { method, url, specifier, exportName } of TENANT_HANDLERS) {
-    const mod = (await import(specifier)) as Record<
+export const projectListingTenantRoutes: FastifyPluginAsync = async (
+  fastify,
+) => {
+  for (const { method, url, specifier, exportName, load } of TENANT_HANDLERS) {
+    const mod = (await loadSlice(specifier, load)) as Record<
       string,
       Parameters<typeof fastify.get>[1] | undefined
     >;

package/templates/apps/api/src/routes/project-listings/me.ts

@@ -1,4 +1,14 @@
 /**
+ * NOT marked `oss: false` (D-48/#5366 escalation, mirrors the original
+ * multi-tenant/#5088 card's own conclusion about this exact file, lines
+ * 556-571 of module-architecture.ts): `./index.ts` in this directory is a
+ * MIXED barrel that statically imports this file, and `server.ts` reaches
+ * `./index.ts` via a plain (non-slice) literal `import()` for multi-tenant's
+ * tenant-scoped routes — a specifier `tsc` always resolves, module selection
+ * or not. Stripping this file leaves that barrel with a dangling import on
+ * every tree. Registration stays gated (`isModuleEnabled("signal-collectors")`
+ * in server.ts); only the source file itself must ship unconditionally.
+ *
  * GET /v1/project-listings/me
  *
  * The FOUNDER'S OWN listings read (#5295) — the `/v1/flow-checkouts/me` and

package/templates/apps/api/src/routes/project-listings/patch-draft.ts

@@ -1,4 +1,9 @@
 /**
+ * NOT marked `oss: false` — see `./me.ts`'s header comment (D-48/#5366
+ * escalation: `./index.ts` is a mixed barrel multi-tenant's `server.ts`
+ * reaches by a literal, always-resolved `import()`; this file ships
+ * unconditionally, registration stays gated).
+ *
  * PATCH /v1/project-listings/drafts/:id
  *
  * `patch` — the save-as-you-go write (#5036 D1). Anonymous, token-gated,

package/templates/apps/api/src/routes/project-listings/public.ts

@@ -1,4 +1,9 @@
 /**
+ * NOT marked `oss: false` — see `./me.ts`'s header comment (D-48/#5366
+ * escalation: `./index.ts` is a mixed barrel multi-tenant's `server.ts`
+ * reaches by a literal, always-resolved `import()`; this file ships
+ * unconditionally, registration stays gated).
+ *
  * GET /v1/project-listings/public?siteKey=
  *
  * The anonymous page-render read (#4998 AC4, reshaped by #5033). Every

package/templates/apps/api/src/routes/project-listings/respond.ts

@@ -1,4 +1,15 @@
 /**
+ * NOT marked `oss: false` (D-48/#5366 escalation, reversing this pass's
+ * own D6 read — see `./me.ts`'s header comment): `sendValidated` is imported
+ * by `./me.ts`, `./patch-draft.ts` and `./public.ts`, each of which must ship
+ * unconditionally because `./index.ts`'s multi-tenant literal `import()`
+ * forces it. A file imported by an always-shipping file cannot itself be
+ * excluded — this is the ORIGINAL multi-tenant/#5088 card's own conclusion
+ * about this exact file (module-architecture.ts lines 569-571), which D6's
+ * "every other consumer is Pro Plus" premise doesn't override: two of its
+ * three non-tenant consumers are these three always-shipping files, not a
+ * gated one.
+ *
  * Response-schema validation for the project-listings routes (#4998),
  * mirroring `waitlist-experiments/respond.ts`'s discipline: response schemas
  * are contract-only unless re-parsed against their own `.strict()` schema

package/templates/apps/api/src/routes/project-listings/resume-token.ts

@@ -1,4 +1,9 @@
 /**
+ * NOT marked `oss: false` — see `./me.ts`'s header comment (D-48/#5366
+ * escalation): imported only by `./patch-draft.ts` and `./submit.ts`, both
+ * of which ship unconditionally (`./index.ts`'s multi-tenant literal
+ * `import()`), so this file cannot be excluded either.
+ *
  * The resume token's transport (#5036 D1).
  *
  * `start` hands the client an opaque token; `patch` and `submit` present it

package/templates/apps/api/src/routes/project-listings/start.ts

@@ -1,4 +1,9 @@
 /**
+ * NOT marked `oss: false` — see `./me.ts`'s header comment (D-48/#5366
+ * escalation: `./index.ts` is a mixed barrel multi-tenant's `server.ts`
+ * reaches by a literal, always-resolved `import()`; this file ships
+ * unconditionally, registration stays gated).
+ *
  * POST /v1/project-listings
  *
  * `start` — step one of the application (#5036 D1). Anonymous, registered in
@@ -37,6 +42,24 @@
  * PII-safe logging (mirrors `routes/leads/index.ts`): routing metadata only —
  * never founderEmail, founderName, or the resume token.
  *
+ * SENDS THE RESUME EMAIL (#5406), fire-and-forget, after the row exists. The
+ * 201 below is never delayed or failed by it: `sendListingResumeLink` returns
+ * `void` and swallows everything, exactly as `sendListingDecisionEmail`'s
+ * `fileIssueOnApprove` does on the approve path. The email is OPT-IN — a site
+ * whose `SiteListingConfig` carries no `resumeEmail.fromAddress` gets none, so
+ * a site sending its own today does not start sending two — and the request
+ * and response shapes of this hard-floor route are unchanged.
+ *
+ * THE EMAIL IS ALSO THE ONLY CARRIER OF THE VERIFICATION NONCE (#5407).
+ * `startProjectListingDraft` mints it, stores only its digest, and returns it
+ * as a SIBLING of the result — never inside the value parsed below, because
+ * `projectListingStartResponseSchema` is this route's hard-floor contract and
+ * carries `id` and `resumeToken` and nothing else. The nonce reaches
+ * `sendListingResumeLink` from a local variable and goes nowhere else: not
+ * into the response, not into the log line above it. That is precisely what
+ * makes `email_verified_at` mean something the resume token alone could not
+ * prove — see `verifyProjectListingDraftEmail`.
+ *
  * The response uses the API's own `{ ok, data }` / `{ ok, error }` envelope
  * (`apps/api/CLAUDE.md`) on BOTH the success and the failure path — the
  * anonymous create it replaces answered bare on success and enveloped on
@@ -49,6 +72,7 @@ import {
 import type { FastifyPluginAsync } from "fastify";
 
 import { siteIdForPublicKey } from "../../services/listing-config.js";
+import { sendListingResumeLink } from "../../services/project-listing-resume-email.js";
 import { startProjectListingDraft } from "../../services/project-listings.js";
 
 export const startProjectListingRoute: FastifyPluginAsync = async (fastify) => {
@@ -97,6 +121,12 @@ export const startProjectListingRoute: FastifyPluginAsync = async (fastify) => {
       "project listing draft started",
     );
 
+    // #5406 — the founder's way back to this draft. NOT awaited: the 201 must
+    // not wait on Resend, and must not fail if Resend does. Both credentials
+    // are handed over here and neither is ever logged — they ride the link
+    // inside the email, and the #5407 nonce rides NOTHING ELSE anywhere.
+    sendListingResumeLink(result.id, result.resumeToken, result.verifyNonce);
+
     const body = projectListingStartResponseSchema.parse({
       id: result.id,
       resumeToken: result.resumeToken,

package/templates/apps/api/src/routes/project-listings/submit.ts

@@ -1,4 +1,9 @@
 /**
+ * NOT marked `oss: false` — see `./me.ts`'s header comment (D-48/#5366
+ * escalation: `./index.ts` is a mixed barrel multi-tenant's `server.ts`
+ * reaches by a literal, always-resolved `import()`; this file ships
+ * unconditionally, registration stays gated).
+ *
  * POST /v1/project-listings/drafts/:id/submit
  *
  * `submit` — the moment an application stops being a draft (#5036 D1).

package/templates/apps/api/src/routes/project-listings/verify-email.ts

@@ -0,0 +1,150 @@
+/**
+ * POST /v1/project-listings/drafts/:id/verify-email
+ *
+ * Records that the founder proved control of `founderEmail`, by opening the
+ * resume link emailed at step one (#5407). Anonymous, credential-gated,
+ * registered in the same rate-limited `leadsScope` as the other three
+ * anonymous listing routes.
+ *
+ * WHY THE ROUTE EXISTS. The resume email (#5406) tells the founder to "verify
+ * your email and continue", and until this route nothing made that sentence
+ * true: `ListingApplicationFlow` rehydrated from `?draft=&token=` entirely in
+ * the browser and touched the server only on the NEXT advance — so a founder
+ * who opened the link and closed the tab left no record, and the operator had
+ * no way to tell a proved address from a typed one at review (samhenry spec
+ * 316 D6b).
+ *
+ * WHAT IT PROVES. That somebody who can read mail at `founderEmail` opened
+ * this link — evidence about the ADDRESS, not about who is driving the draft
+ * (`verifyProjectListingDraftEmail` carries the full note). It takes
+ * TWO credentials and only the second carries that: the `Authorization:
+ * Bearer` resume token says "you opened this draft" (it is in `start`'s own
+ * 201 body, so anyone who posted the form has it), and the `verifyNonce` in
+ * the body says "you read the email" — it is minted at `start`, digested onto
+ * the row, and handed to nothing but the resume-email builder, reaching the
+ * outside world only as the `?verify=` parameter inside the message. Keying
+ * this route on the resume token ALONE was the first design and was
+ * forgeable in two HTTP calls; `verifyProjectListingDraftEmail` carries the
+ * full note.
+ *
+ * It still says nothing about WHO the founder is. `ownerUserId` (#5295) is
+ * the column that carries an identity claim.
+ *
+ * A SITE THAT SENDS NO RESUME EMAIL CAN NEVER VERIFY, and that is correct:
+ * the nonce is minted on every draft but delivered only by the email, so
+ * where `SiteListingConfig` carries no `resumeEmail` the column stays null
+ * forever — nobody has read anything at that address.
+ *
+ * IDEMPOTENT, AND WRITE-ONCE. The service stamps by compare-and-swap on
+ * `emailVerifiedAt: null`, so a founder who opens the link five times is
+ * stamped once and every call answers with that FIRST stamp.
+ *
+ * THE ERROR SURFACE IS `patch`'s AND `submit`'s, deliberately unchanged: a
+ * malformed id or a body that is not `{ verifyNonce }` is `400
+ * validation_failed`, a missing or malformed `Authorization: Bearer` is `401
+ * unauthorized`, and a WRONG token, a WRONG nonce, a credential bound to
+ * another listing, an unknown id and an already-submitted row are all one
+ * `404 not_found`. The 400s describe the REQUEST's shape and reveal nothing
+ * about any row; everything that depends on a row is the single 404. An
+ * anonymous surface must not distinguish "exists but not yours" from "does
+ * not exist", and this route least of all — a distinguishable answer would
+ * make it both an oracle for which drafts exist and a guessing channel for
+ * the nonce.
+ *
+ * THE NONCE TRAVELS IN THE BODY, not the query string, for the reason
+ * `resume-token.ts` gives about the resume token: a query parameter lands in
+ * access logs, proxy logs and `Referer` headers. The claim is about THIS hop
+ * only, and it is worth being exact about that — the nonce's DELIVERY hop is
+ * itself a query parameter on the consuming site's URL, so it lands in that
+ * site's own access logs exactly as the resume token does. What the body
+ * placement buys is that the API's logs and any proxy between the browser and
+ * this server never see it. The resume token keeps its `Authorization:
+ * Bearer` header. Neither credential is ever logged and neither is ever
+ * returned.
+ */
+import { zProjectListingId } from "@working-theory/ids";
+import { projectListingVerifyEmailResponseSchema } from "@working-theory/validation";
+import type { FastifyPluginAsync } from "fastify";
+import { z } from "zod";
+
+import { verifyProjectListingDraftEmail } from "../../services/project-listings.js";
+
+import { sendValidated } from "./respond.js";
+import { resumeTokenFrom } from "./resume-token.js";
+
+const paramsSchema = z.object({ id: zProjectListingId });
+
+/**
+ * The nonce, as the emailed link carried it. Bounded so an oversized body is
+ * refused before any digest is computed; the value is 256 bits of CSPRNG
+ * output in base64url, which is 43 characters.
+ */
+const bodySchema = z.object({ verifyNonce: z.string().min(1).max(256) }).strict();
+
+export const verifyProjectListingDraftEmailRoute: FastifyPluginAsync = async (
+  fastify,
+) => {
+  fastify.post(
+    "/v1/project-listings/drafts/:id/verify-email",
+    async (request, reply) => {
+      const parsedParams = paramsSchema.safeParse(request.params);
+      if (!parsedParams.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: { code: "validation_failed", message: "Invalid project listing id" },
+        });
+      }
+
+      const resumeToken = resumeTokenFrom(request);
+      if (resumeToken === null) {
+        return reply.status(401).send({
+          ok: false,
+          error: { code: "unauthorized", message: "A resume token is required" },
+        });
+      }
+
+      // The message names the FIELD, never whether the value would have
+      // matched — that distinction is the 404's, below.
+      const parsedBody = bodySchema.safeParse(request.body);
+      if (!parsedBody.success) {
+        return reply.status(400).send({
+          ok: false,
+          error: {
+            code: "validation_failed",
+            message: "A verification nonce is required",
+          },
+        });
+      }
+
+      const result = await verifyProjectListingDraftEmail(
+        parsedParams.data.id,
+        resumeToken,
+        parsedBody.data.verifyNonce,
+      );
+      if (!result.ok) {
+        return reply.status(404).send({
+          ok: false,
+          error: { code: "not_found", message: "Draft not found" },
+        });
+      }
+
+      // Routing metadata only, the same PII boundary `start` documents: the
+      // listing id and the caller's ip, never the founder's email and never
+      // the token.
+      request.log.info(
+        { listingId: result.value.id, ip: request.ip },
+        "project listing draft email verified",
+      );
+
+      return sendValidated(
+        reply,
+        projectListingVerifyEmailResponseSchema,
+        {
+          id: result.value.id,
+          emailVerifiedAt: result.value.emailVerifiedAt.toISOString(),
+        },
+        "verify-email",
+      );
+    },
+  );
+};