create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,120 @@
+/**
+ * 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/me                   — the founder's OWN listings (authScope)
+ *   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.
+ *
+ * `/me` (#5295) sits between the two scopes: `authScope` only, no tenant guard.
+ * A founder is not a workspace member, so the guard's default-deny answers 403
+ * for their own submission — and the fix is this ADDITIVE route, joined on the
+ * owner link, rather than a relaxed `PROJECT_LISTING_ROLES`. Its static `/me`
+ * segment takes router precedence over the parametric `/:id` below, exactly as
+ * the already-shipped static `/public` does.
+ *
+ * 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 { 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";
+
+export const projectListingStartRoute = startProjectListingRoute;
+export const projectListingDraftPatchRoute = patchProjectListingDraftRoute;
+export const projectListingSubmitRoute = submitProjectListingRoute;
+export const projectListingPublicRoute = publicProjectListingsRoute;
+/**
+ * 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
+ * multi-tenant module, the same as `flowCheckoutRoutes`.
+ */
+export const projectListingMeRoute = meRoute;
+
+/**
+ * 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/me.ts

@@ -0,0 +1,76 @@
+/**
+ * GET /v1/project-listings/me
+ *
+ * The FOUNDER'S OWN listings read (#5295) — the `/v1/flow-checkouts/me` and
+ * `/v1/waitlist-signups/me` posture, for `ProjectListing`.
+ *
+ * Registered INSIDE `server.ts`'s `authScope` (auth only — NOT the inner
+ * `tenantScope`): a founder is not a workspace member, and the tenant guard is
+ * default-deny, so a founder reaching the tenant-scoped list route gets a 403
+ * for their own submission. That is the problem this route exists to solve, and
+ * it is solved by ADDING this route rather than by relaxing
+ * `PROJECT_LISTING_ROLES` — the operator floor on
+ * `GET|PATCH /v1/project-listings[/:id]` is unchanged and still `owner|admin`.
+ *
+ * Identity is `request.userId` ONLY. The route declares no query schema and
+ * reads no query or body key — an `email` parameter is never parsed and never
+ * read — and the service joins on the owner link and nothing else
+ * (`services/project-listings.ts`'s `listMyProjectListings`: `ownerUserId ===
+ * userId`, never a `founderEmail` comparison at read time).
+ *
+ * Route precedence: this static path is registered alongside the parametric
+ * `/v1/project-listings/:id` in the tenant scope. Fastify's router prefers a
+ * static segment over a parametric one, so `/me` reaches this handler, exactly
+ * as the already-shipped static `/v1/project-listings/public` coexists with the
+ * same parametric route.
+ *
+ * Envelope per apps/api/CLAUDE.md: `{ ok: true, data }` /
+ * `{ ok: false, error: { code, message } }`, real HTTP status codes:
+ *   401 unauthorized · 500 internal_error (the 200 body failed its own
+ *   contract schema — a drift is never a leak). A signed-in caller who owns
+ *   NOTHING is a 200 with an empty list, never a 403: they are legitimately
+ *   signed in and simply own no listing yet.
+ *
+ * API↔MCP parity: identity-bound (the session IS the identity; the OSS MCP
+ * surface is identity-blind) — no MCP twin (#3591 exception, the same shape as
+ * `/v1/flow-checkouts/me` and `/v1/waitlist-signups/me`).
+ */
+import { projectListingMeResponseSchema } from "@working-theory/validation";
+import type { FastifyPluginAsync, FastifyReply } from "fastify";
+
+import { listMyProjectListings } 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" },
+  });
+}
+
+export const projectListingMeRoute: FastifyPluginAsync = async (fastify) => {
+  fastify.get("/v1/project-listings/me", async (request, reply) => {
+    const userId = request.userId;
+    if (!userId) return unauthorized(reply);
+
+    const listings = await listMyProjectListings(userId);
+
+    // The omission is explicit at the send site rather than hidden in a schema
+    // strip, the idiom `patch-draft.ts` uses: `projectListingDraftSchema` is
+    // `.strict()`, so a key that stops being dropped here becomes a 500 instead
+    // of quietly shipping an internal reference to the founder.
+    const data = listings.map(
+      ({
+        siteId: _siteId,
+        leadId: _leadId,
+        decidedBy: _decidedBy,
+        issueUrl: _issueUrl,
+        experimentKey: _experimentKey,
+        ...mine
+      }) => mine,
+    );
+
+    return sendValidated(reply, projectListingMeResponseSchema, data, "me");
+  });
+};

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");
+  });
+};