create-ailk 0.1.0 → 0.1.1

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

@@ -0,0 +1,105 @@
+/**
+ * Project-listings route group (#4998 — the founder's application row;
+ * reshaped by #5036 — the application became a resumable draft).
+ *
+ * Routes:
+ *   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
+ *   GET   /v1/project-listings/public               — anonymous page-render read (leadsScope)
+ *   GET   /v1/project-listings                      — tenant-scoped dashboard list
+ *   GET   /v1/project-listings/:id                  — tenant-scoped single read
+ *   PATCH /v1/project-listings/:id                  — tenant-scoped decision + featured flag
+ *   PATCH /v1/project-listings/:id/copy             — tenant-scoped operator copy edit
+ *
+ * The anonymous set is registered in `server.ts`'s rate-limited `leadsScope`
+ * alongside `/v1/leads/*`; the tenant-scoped set is registered inside
+ * `tenantScope`, behind `tenantPreHandlerPlugin`, the same as
+ * `waitlistExperimentRoutes`. The `/drafts/` path segment is what keeps the
+ * anonymous token-gated PATCH and the operator's tenant-guarded PATCH apart
+ * at the router — they differ in segment count, so neither shadows the other.
+ *
+ * API<->MCP parity: no MCP twin. The anonymous set mirrors the leads routes'
+ * own identity-blind posture (an applying founder has no account, and the
+ * resume token is a per-draft capability rather than an identity); the
+ * tenant-scoped set is an identity-bound dashboard surface, the same #3591
+ * exception the sibling `/v1/waitlist-experiments/*` routes record.
+ */
+import type { FastifyPluginAsync } from "fastify";
+
+import { patchProjectListingDraftRoute } from "./patch-draft.js";
+import { publicProjectListingsRoute } from "./public.js";
+import { startProjectListingRoute } from "./start.js";
+import { submitProjectListingRoute } from "./submit.js";
+
+export const projectListingStartRoute = startProjectListingRoute;
+export const projectListingDraftPatchRoute = patchProjectListingDraftRoute;
+export const projectListingSubmitRoute = submitProjectListingRoute;
+export const projectListingPublicRoute = publicProjectListingsRoute;
+
+/**
+ * Tenant-scoped handlers, as { specifier, exportName }, reached at REGISTRATION
+ * time rather than named as static imports (#5182).
+ *
+ * `get.ts`, `list.ts`, `patch.ts` and `patch-copy.ts` are multi-tenant SLICE
+ * files the OSS strip removes; the other four route modules in this directory
+ * are the free anonymous surface and stay static. This directory is mixed on
+ * 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
+ * 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 TENANT_HANDLERS: ReadonlyArray<{
+  method: "get" | "patch";
+  url: string;
+  specifier: string;
+  exportName: string;
+}> = [
+  {
+    method: "get",
+    url: "/v1/project-listings",
+    specifier: "./list.js",
+    exportName: "listProjectListingsHandler",
+  },
+  {
+    method: "get",
+    url: "/v1/project-listings/:id",
+    specifier: "./get.js",
+    exportName: "getProjectListingHandler",
+  },
+  {
+    method: "patch",
+    url: "/v1/project-listings/:id",
+    specifier: "./patch.js",
+    exportName: "patchProjectListingHandler",
+  },
+  {
+    method: "patch",
+    url: "/v1/project-listings/:id/copy",
+    specifier: "./patch-copy.js",
+    exportName: "patchProjectListingCopyHandler",
+  },
+];
+
+export const projectListingTenantRoutes: FastifyPluginAsync = async (fastify) => {
+  for (const { method, url, specifier, exportName } of TENANT_HANDLERS) {
+    const mod = (await import(specifier)) as Record<
+      string,
+      Parameters<typeof fastify.get>[1] | undefined
+    >;
+    const handler = mod[exportName];
+    if (!handler) {
+      throw new Error(
+        `multi-tenant slice drift: '${specifier}' does not export '${exportName}'`,
+      );
+    }
+    fastify[method](url, handler);
+  }
+};

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

@@ -0,0 +1,47 @@
+// oss: false
+/**
+ * GET /v1/project-listings
+ *
+ * Tenant-scoped dashboard list (#4998 AC2), the `waitlist-experiments` list
+ * route's own pattern: scope derived server-side from `request.tenant`
+ * (never a client-supplied site id), role floor `owner|admin` checked before
+ * any read, response re-parsed against its own contract schema before send.
+ */
+import { projectListingListResponseSchema } from "@working-theory/validation";
+import type { FastifyReply, FastifyRequest } from "fastify";
+
+import { listProjectListings, PROJECT_LISTING_ROLES } from "../../services/project-listings.js";
+
+import { sendValidated } from "./respond.js";
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+function forbidden(reply: FastifyReply) {
+  return reply.status(403).send({
+    ok: false,
+    error: { code: "forbidden", message: "Forbidden" },
+  });
+}
+
+export async function listProjectListingsHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenant = request.tenant;
+  if (!tenant) return unauthorized(reply);
+  if (!PROJECT_LISTING_ROLES.has(tenant.role)) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 403 },
+      "[project-listings] list denied; insufficient role",
+    );
+    return forbidden(reply);
+  }
+
+  const data = await listProjectListings(tenant.workspaceId);
+  return sendValidated(reply, projectListingListResponseSchema, data, "list");
+}

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

@@ -0,0 +1,222 @@
+// oss: false
+/**
+ * PATCH /v1/project-listings/:id/copy
+ *
+ * The operator's copy edit — the THIRD review outcome, beside approve and
+ * reject.
+ *
+ * Before this route a submitted listing's copy was frozen for everyone: the
+ * legal transitions out of `requested` are `active` and `rejected` only, there
+ * is no route back to `draft`, and `PATCH /v1/project-listings/drafts/:id` is
+ * scoped to `status: "draft"` plus the applicant's own resume-token hash. A
+ * listing whose headline needed a trim could therefore be published exactly as
+ * written or rejected outright, and the founder could not revise it either.
+ *
+ * Deliberately NOT folded into `PATCH /v1/project-listings/:id`. That body is
+ * `.strict()`, carries at most `status` and `featured`, and exists to express
+ * the DECISION transition; entangling "edit the copy" with "decide the
+ * listing" would muddy a contract that is currently clean. The lifecycle is
+ * untouched by this route — it adds no status, no transition and no decision
+ * target.
+ *
+ * Auth, tenant scoping and the error shapes are `patch.ts`'s: the same
+ * owner-or-admin floor, the same `siteId` scoping from `request.tenant`, and
+ * the same 401 / 403 / 400 / 404 bodies. A foreign or missing id is `404`, so a
+ * cross-tenant probe cannot tell "exists but not yours" from "does not exist".
+ *
+ * `questions` is replaced wholesale, and its `extras` array carries a
+ * `.default([])` in the package schema, so a payload omitting that key would
+ * parse to an empty array and silently delete the founder's extra questions.
+ * A `questions` body without an explicit `extras` is therefore a `400`, which
+ * makes clearing them something the caller has to say rather than something it
+ * can do by forgetting.
+ *
+ * The status floor (`requested` or `active` only) lives in the service's WHERE
+ * clause rather than in a read-then-write check, so a concurrent decision
+ * cannot slip the row out of the editable set between the check and the write.
+ * A `draft`, `rejected` or `closed` row is `404` and unchanged — `closed`
+ * included, even though nothing stores it: the WHERE transcribes
+ * `computeListingStatus`'s accepting branches rather than its stored string,
+ * so an elapsed window refuses the edit exactly as it refuses on a read.
+ */
+import { zProjectListingId } from "@working-theory/ids";
+import {
+  buildProjectListingDraftPatchSchema,
+  projectListingSchema,
+} from "@working-theory/validation";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+
+import { listingConfigFor } from "../../services/listing-config.js";
+import { patchListingCopy, PROJECT_LISTING_ROLES } from "../../services/project-listings.js";
+
+import { sendValidated } from "./respond.js";
+
+const paramsSchema = z.object({ id: zProjectListingId });
+
+/**
+ * The five PUBLISHED copy fields this route may rewrite.
+ *
+ * `questions` is in because its prompts and option labels render on the public
+ * page, which is exactly where abusive language would land. `name` is out
+ * because the slug is derived from it at submit and stored, so editing it would
+ * desync the public URL from the name. `url`, `product`, `commitment`,
+ * `teamComposition`, `address` and `founderCompany` are out because they are
+ * facts rather than copy — a wrong fact is a question to the founder or a
+ * reject, not an edit. `anythingElse` is out because it is a note to the
+ * reviewer and never renders.
+ */
+const COPY_FIELDS = ["headline", "oneLiner", "problem", "faqs", "questions"] as const;
+
+/**
+ * The copy-edit body, DERIVED from the application's own schema at THIS SITE's
+ * configured bounds rather than re-declared.
+ *
+ * Deriving is what carries the word caps, the exactly-three-FAQ rule and every
+ * question refinement into this route for free, and what keeps them from
+ * drifting: a bound the application gains is a bound the copy edit gains in the
+ * same commit.
+ *
+ * Built from `buildProjectListingDraftPatchSchema` — the same builder the
+ * applicant's own write path uses — rather than from the fixed
+ * `projectListingApplicationFieldsSchema`, because since #5048 D5/D6 the word
+ * caps and the collected field set are the SITE's configuration, not platform
+ * constants. Against the fixed schema an operator could not re-save copy the
+ * applicant was legitimately allowed to submit: a site configured to fifteen
+ * words would accept a fourteen-word headline at submit and refuse the same
+ * text here. Passing the intersection of the site's `collectedFields` with
+ * `COPY_FIELDS` as the collected set is what narrows the builder's full roster
+ * to this route's five, so a field the site does not collect cannot be authored
+ * onto a founder's public page by the operator either — the same security
+ * property the builder's own docblock records.
+ *
+ * Unlike `patch-draft.ts`, which must resolve the draft before it knows the
+ * site and therefore validates inside the service, this route reads the site
+ * from the caller's own session, so the schema is built here and the editable
+ * set stays visible in this file.
+ *
+ * NOT lifted into `@working-theory/validation` as a sibling of
+ * `projectListingPatchSchema`, tempting as the symmetry is. This file is
+ * vendored byte-for-byte into a consuming repo that installs that package from
+ * a PUBLISHED version, so a new export would leave the synced copy referencing
+ * a symbol its installed version does not have — broken until a publish and a
+ * version bump land. `buildProjectListingDraftPatchSchema` is already public in
+ * the version that repo has (`services/project-listings.ts` imports it), so
+ * this local derivation syncs cleanly.
+ *
+ * The builder supplies the at-least-one-key refine, so an empty body is a 400
+ * rather than a silent no-op the caller would read as a successful save.
+ */
+function copyPatchSchemaFor(
+  wordCaps: Parameters<typeof buildProjectListingDraftPatchSchema>[0],
+  collectedFields: readonly string[],
+) {
+  return buildProjectListingDraftPatchSchema(
+    wordCaps,
+    COPY_FIELDS.filter((field) => collectedFields.includes(field)),
+  );
+}
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+function forbidden(reply: FastifyReply) {
+  return reply.status(403).send({
+    ok: false,
+    error: { code: "forbidden", message: "Forbidden" },
+  });
+}
+
+function invalidParams(reply: FastifyReply) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "validation_failed", message: "Invalid project listing id" },
+  });
+}
+
+function invalidBody(reply: FastifyReply, message: string) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "invalid_input", message },
+  });
+}
+
+function notFound(reply: FastifyReply) {
+  return reply.status(404).send({
+    ok: false,
+    error: { code: "not_found", message: "Project listing not found" },
+  });
+}
+
+export async function patchProjectListingCopyHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenant = request.tenant;
+  if (!tenant) return unauthorized(reply);
+  if (!PROJECT_LISTING_ROLES.has(tenant.role)) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 403 },
+      "[project-listings] copy patch denied; insufficient role",
+    );
+    return forbidden(reply);
+  }
+
+  const parsedParams = paramsSchema.safeParse(request.params);
+  if (!parsedParams.success) return invalidParams(reply);
+
+  const listingConfig = await listingConfigFor(tenant.workspaceId);
+  const editableFields = COPY_FIELDS.filter((field) =>
+    listingConfig.collectedFields.includes(field),
+  );
+  if (editableFields.length === 0) {
+    // A site whose application collects none of the five copy fields has no
+    // copy to edit. Refused here rather than handed to the builder, whose
+    // `pickCollected` throws on an empty mask — that throw guards the
+    // applicant's surface and would be a 500 on this one.
+    return invalidBody(reply, "this site collects none of the editable copy fields");
+  }
+
+  const parsedBody = copyPatchSchemaFor(
+    listingConfig.wordCaps,
+    listingConfig.collectedFields,
+  ).safeParse(request.body);
+  if (!parsedBody.success) {
+    return invalidBody(reply, parsedBody.error.issues[0]?.message ?? "invalid input");
+  }
+
+  // `questions.extras` carries a `.default([])` in the package schema, so a
+  // `questions` payload that OMITS the key parses to `extras: []` —
+  // indistinguishable from a deliberate clear. `questions` is replaced
+  // wholesale, so accepting the ambiguous body would silently delete the
+  // founder's up-to-three extra questions with no error. Refuse it instead and
+  // make the caller say which it meant. Checked against the RAW body because
+  // the parsed value always carries the key once zod has applied the default.
+  if (parsedBody.data.questions !== undefined) {
+    const rawQuestions = (request.body as { questions?: unknown }).questions;
+    if (
+      typeof rawQuestions !== "object" ||
+      rawQuestions === null ||
+      !("extras" in rawQuestions)
+    ) {
+      return invalidBody(
+        reply,
+        "questions must carry an explicit 'extras' array; send [] to clear it",
+      );
+    }
+  }
+
+  const result = await patchListingCopy(
+    tenant.workspaceId,
+    parsedParams.data.id,
+    parsedBody.data,
+    tenant.userId,
+  );
+  if (!result.ok) return notFound(reply);
+
+  return sendValidated(reply, projectListingSchema, result.value, "patch-copy");
+}

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

@@ -0,0 +1,97 @@
+/**
+ * PATCH /v1/project-listings/drafts/:id
+ *
+ * `patch` — the save-as-you-go write (#5036 D1). Anonymous, token-gated,
+ * registered in the rate-limited `leadsScope`.
+ *
+ * It merges a partial application into a draft and ENFORCES NO COMPLETENESS.
+ * A present field is still checked against its own bounds (length, enum
+ * membership, and the SITE's own word caps — #5048 D6, which is why the body
+ * is validated inside the service, where the draft's site is known) because
+ * this is an anonymous write surface; what
+ * it deliberately does not assert is that the application is finished. That is
+ * `submit`'s job alone, and the split is the whole point of the lifecycle.
+ *
+ * The credential is the `Authorization: Bearer` resume token minted at
+ * `start`, and it is bound to ONE listing: a valid token presented against a
+ * different id resolves to nothing. A wrong token, a spent token, an unknown
+ * id and an already-submitted row are all the same `404` — the anonymous
+ * surface must not distinguish "exists but not yours" from "does not exist".
+ *
+ * The response is `projectListingDraftSchema`, NOT the tenant dashboard's
+ * row shape: an anonymous caller addresses its site by an opaque public key
+ * and must not be handed the real `siteId` back on every save (security
+ * review on this change, finding 3).
+ *
+ * Distinct from the tenant-scoped `PATCH /v1/project-listings/:id`, which
+ * carries the operator's decision and lives behind the tenant guard. The
+ * `/drafts/` segment keeps the two apart at the router.
+ */
+import { zProjectListingId } from "@working-theory/ids";
+import { projectListingDraftSchema } from "@working-theory/validation";
+import type { FastifyPluginAsync } from "fastify";
+import { z } from "zod";
+
+import { patchProjectListingDraft } from "../../services/project-listings.js";
+
+import { sendValidated } from "./respond.js";
+import { resumeTokenFrom } from "./resume-token.js";
+
+const paramsSchema = z.object({ id: zProjectListingId });
+
+export const patchProjectListingDraftRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.patch("/v1/project-listings/drafts/:id", 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 body is validated INSIDE the service (#5048 D6), not here: the word
+    // caps are the site's own configuration, and which site this draft belongs
+    // to is not knowable until the draft is resolved. A caller holding no valid
+    // token still never reaches body validation — the service answers
+    // `not_found` first.
+    const result = await patchProjectListingDraft(
+      parsedParams.data.id,
+      resumeToken,
+      request.body,
+    );
+    if (!result.ok) {
+      if (result.error.kind === "invalid_input") {
+        return reply.status(400).send({
+          ok: false,
+          error: { code: "invalid_input", message: result.error.message },
+        });
+      }
+      return reply.status(404).send({
+        ok: false,
+        error: { code: "not_found", message: "Draft not found" },
+      });
+    }
+
+    // The omission is explicit at the send site rather than hidden in a
+    // schema strip: `projectListingDraftSchema` is `.strict()`, so a key that
+    // stops being dropped here becomes a 500 instead of quietly shipping.
+    const {
+      siteId: _siteId,
+      leadId: _leadId,
+      decidedBy: _decidedBy,
+      issueUrl: _issueUrl,
+      experimentKey: _experimentKey,
+      ...draft
+    } = result.value;
+
+    return sendValidated(reply, projectListingDraftSchema, draft, "patch-draft");
+  });
+};

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

@@ -0,0 +1,136 @@
+// oss: false
+/**
+ * PATCH /v1/project-listings/:id
+ *
+ * Tenant-scoped listing mutation (#4998 AC3, reshaped by #5033). The body is
+ * `.strict()` and carries at most two optional fields, at least one:
+ *
+ *   - `status` — `active` | `rejected`, the only transition there is. The
+ *     lifecycle collapsed to five states with `closed` COMPUTED (#5033 D3),
+ *     so `approved -> live` and `live -> closed` no longer exist and `closed`
+ *     is not a value this route (or any route) can write. Routed through
+ *     `decideListing` — the SAME function `POST /v1/slack/actions` calls — so
+ *     the stamp, the window end and the "already decided" idempotency live in
+ *     one place. On a changed decision the founder is emailed once via
+ *     `sendListingDecisionEmail`.
+ *   - `featured` — the operator's shelf flag (#5033 D6), through
+ *     `setListingFeatured`. Whether it reaches the public read at all is the
+ *     site's `featuredEnabled` config, read server-side; this route sets the
+ *     row's own flag and never the config.
+ *
+ * Sent together, the featured write lands first and the decision's response
+ * is what the caller gets back, so one call cannot return a row that
+ * contradicts either write.
+ *
+ * `:id` is validated at the boundary the same way `get.ts` does; a foreign or
+ * missing id is `404`. An operator re-PATCHing an already-decided listing
+ * gets `200` with the row unchanged (`decideListing`'s idempotent "second
+ * click" branch — #4999 AC).
+ */
+import { zProjectListingId } from "@working-theory/ids";
+import { projectListingPatchSchema, projectListingSchema } from "@working-theory/validation";
+import type { FastifyReply, FastifyRequest } from "fastify";
+import { z } from "zod";
+
+import {
+  decideListing,
+  sendListingDecisionEmail,
+} from "../../services/project-listing-decision.js";
+import { setListingFeatured, PROJECT_LISTING_ROLES } from "../../services/project-listings.js";
+
+import { sendValidated } from "./respond.js";
+
+const paramsSchema = z.object({ id: zProjectListingId });
+
+function unauthorized(reply: FastifyReply) {
+  return reply.status(401).send({
+    ok: false,
+    error: { code: "unauthorized", message: "Authentication required" },
+  });
+}
+
+function forbidden(reply: FastifyReply) {
+  return reply.status(403).send({
+    ok: false,
+    error: { code: "forbidden", message: "Forbidden" },
+  });
+}
+
+function invalidParams(reply: FastifyReply) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "validation_failed", message: "Invalid project listing id" },
+  });
+}
+
+function invalidBody(reply: FastifyReply, message: string) {
+  return reply.status(400).send({
+    ok: false,
+    error: { code: "invalid_input", message },
+  });
+}
+
+function notFound(reply: FastifyReply) {
+  return reply.status(404).send({
+    ok: false,
+    error: { code: "not_found", message: "Project listing not found" },
+  });
+}
+
+export async function patchProjectListingHandler(
+  request: FastifyRequest,
+  reply: FastifyReply,
+): Promise<void> {
+  const tenant = request.tenant;
+  if (!tenant) return unauthorized(reply);
+  if (!PROJECT_LISTING_ROLES.has(tenant.role)) {
+    request.log.warn(
+      { method: request.method, path: request.url, status: 403 },
+      "[project-listings] patch denied; insufficient role",
+    );
+    return forbidden(reply);
+  }
+
+  const parsedParams = paramsSchema.safeParse(request.params);
+  if (!parsedParams.success) return invalidParams(reply);
+
+  const parsedBody = projectListingPatchSchema.safeParse(request.body);
+  if (!parsedBody.success) {
+    return invalidBody(reply, parsedBody.error.issues[0]?.message ?? "invalid input");
+  }
+
+  const { status, featured } = parsedBody.data;
+
+  if (featured !== undefined) {
+    const featuredResult = await setListingFeatured(
+      tenant.workspaceId,
+      parsedParams.data.id,
+      featured,
+    );
+    if (!featuredResult.ok) return notFound(reply);
+    if (status === undefined) {
+      return sendValidated(reply, projectListingSchema, featuredResult.value, "patch");
+    }
+  }
+
+  if (status === undefined) {
+    // Unreachable — the body schema refuses an empty object — but the
+    // narrowing has to be discharged before `decideListing`.
+    return invalidBody(reply, "patch body must carry at least one of 'status' or 'featured'");
+  }
+
+  const decisionResult = await decideListing({
+    id: parsedParams.data.id,
+    decision: status,
+    decidedBy: tenant.userId,
+    siteId: tenant.workspaceId,
+  });
+  if (!decisionResult.ok) {
+    if (decisionResult.error.kind === "not_found") return notFound(reply);
+    return invalidBody(reply, decisionResult.error.message);
+  }
+  if (decisionResult.changed) {
+    await sendListingDecisionEmail(decisionResult.value, status);
+  }
+  return sendValidated(reply, projectListingSchema, decisionResult.value, "patch");
+}

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

@@ -0,0 +1,52 @@
+/**
+ * GET /v1/project-listings/public?siteKey=
+ *
+ * The anonymous page-render read (#4998 AC4, reshaped by #5033). Every
+ * `active` row for the site, ordered: the three newest by `decidedAt` among
+ * them first, then the rest by `waitlistCount` desc, then `decidedAt` desc.
+ * A row whose window has elapsed comes back with a COMPUTED `closed` status —
+ * no job runs, nothing is stored, and a consumer partitions its shelves on
+ * what it is handed. `featured` surfaces only where the site's
+ * `SiteListingConfig` enables it. `founderEmail` never leaves this route —
+ * `projectListingPublicSchema` (`.omit({founderEmail})`) is what the response
+ * is re-parsed against before send.
+ */
+import {
+  projectListingPublicListResponseSchema,
+  publicSiteKeySchema,
+} from "@working-theory/validation";
+import type { FastifyPluginAsync } from "fastify";
+import { z } from "zod";
+
+import { siteIdForPublicKey } from "../../services/listing-config.js";
+import { publicProjectListings } from "../../services/project-listings.js";
+
+import { sendValidated } from "./respond.js";
+
+const querySchema = z.object({ siteKey: publicSiteKeySchema });
+
+export const publicProjectListingsRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/project-listings/public", async (request, reply) => {
+    const parsedQuery = querySchema.safeParse(request.query);
+    if (!parsedQuery.success) {
+      return reply.status(400).send({
+        ok: false,
+        error: { code: "validation_failed", message: "Invalid siteKey" },
+      });
+    }
+
+    // #5048 D2 — one identifier for the whole mountable contract. The shelves
+    // and the application form are configured with the same public key, so a
+    // site never has to hold two different names for itself.
+    const siteId = await siteIdForPublicKey(parsedQuery.data.siteKey);
+    if (siteId === null) {
+      return reply.status(400).send({
+        ok: false,
+        error: { code: "unknown_site_key", message: "Unknown site key" },
+      });
+    }
+
+    const data = await publicProjectListings(siteId);
+    return sendValidated(reply, projectListingPublicListResponseSchema, data, "public");
+  });
+};