create-ailk 0.2.0 → 0.4.0

package/templates/apps/api/src/services/project-listing-decision.ts

@@ -1,510 +0,0 @@
-/**
- * @file project-listing-decision.ts
- * @description The one Approve/Reject transition for a `ProjectListing`
- * (#4999) — the SAME function `PATCH /v1/project-listings/:id` (tenant-scoped,
- * via `routes/project-listings/patch.ts`) and `POST /v1/slack/actions` (the
- * Slack button click, no tenant context) both call, so the stamp + backlink
- * logic exists in exactly one place.
- *
- * `siteId` is optional: the tenant-scoped PATCH route passes it (so a foreign
- * listing id 404s, matching every other tenant-scoped read/write in this
- * service group); the Slack handler omits it (the button's `value` carries
- * only the listing id — no tenant context to check).
- *
- * Approve stamps `windowEndsAt = decidedAt + the row's windowDays`, the
- * applicant's requested window already clamped at create against the site's
- * `SiteListingConfig` (#5033 D4). The ninety days this used to hardcode were
- * one site's commercial terms; there is no duration constant here now. A row
- * already decided (`status` already `active` or `rejected`) is idempotent —
- * `{ ok: true, changed: false }`, the row untouched, no second stamp — the
- * "second click" AC (#4999): both the PATCH route (an operator re-submitting
- * the same decision) and the Slack route (a stale button click after the
- * message has already updated) see the same 200/no-op shape. Only a listing
- * still `requested` can transition; anything else (an already-decided row
- * asking for a DIFFERENT decision, or a `draft` asking to be decided) is
- * `invalid_transition`.
- *
- * `value` is a strict `ProjectListing` (safe to pass straight through
- * `routes/project-listings/respond.ts#sendValidated`, which re-parses
- * against `projectListingSchema.strict()`); `slackChannel`/`slackTs` live
- * OUTSIDE it, in the sibling `slack` field, so an unexpected key never
- * reaches that contract check. The row shape/select and the `waitlistCount`
- * join still mirror `services/project-listings.ts` rather than importing it,
- * but the one piece that MUST NOT drift — the computed `closed` state — is
- * now imported from there (`computeListingStatus`), so both modules resolve a
- * row's lifecycle status through the same function.
- *
- * Also exports `sendListingDecisionEmail` — the founder email dispatch
- * `routes/slack/actions.ts` (on a changed Slack decision) and
- * `routes/project-listings/patch.ts` (on a changed PATCH decision) both
- * call, so the founder is emailed exactly once regardless of which channel
- * decided. See that function's own doc comment for the env-var reuse this
- * issue makes (no new email-specific env var beyond the three Slack ones).
- * On an APPROVE, it also fires `fileListingIssue` (#5000,
- * `project-listing-issue.ts`) fire-and-forget after the email — the one
- * work-order GitHub issue for the row, on the site's own repo. Both
- * callers reach it through this one function, so the filing (like the
- * email) fires exactly once per changed decision, never per caller.
- *
- * Also exports `onListingDecided` — the approve-path side-effect seam (#5001):
- * a `requested` → `active` transition projects the row into its live
- * diagnostic (`generateListingFlow`). `decideListing` calls it after a CHANGED
- * approve, and since #5033 collapsed the lifecycle that is the ONLY caller —
- * `requested → active | rejected` is the only transition there is, and both
- * the PATCH route and the Slack click reach it through `decideListing`.
- * Fail-soft by construction — a projection failure is logged
- * and swallowed; the decision has already committed. #5000 (the build issue)
- * joins the same seam.
- *
- * PII boundary: `decideListing` never logs (the DB mutation only).
- * `sendListingDecisionEmail` logs `listingId`/`decision`/an error KIND only —
- * never founderEmail/founderName/questions (mirrors
- * `services/project-listings.ts` and `services/lead-routing.ts`'s
- * discipline).
- */
-
-import type { Prisma } from "@working-theory/database";
-import { sendListingApprovedEmail, sendListingRejectedEmail } from "@working-theory/email";
-import { logger } from "@working-theory/observability";
-import {
-  clampWindowDays,
-  projectListingQuestionsSchema,
-  type ProjectListing,
-  type ProjectListingFaqs,
-  type ProjectListingQuestions,
-} from "@working-theory/validation";
-
-import { config } from "../config/index.js";
-import { prisma } from "../lib/prisma.js";
-
-import { listingConfigFor } from "./listing-config.js";
-import { generateListingFlow } from "./project-listing-flow.js";
-import { fileListingIssue } from "./project-listing-issue.js";
-import {
-  addressPartsFromRow,
-  computeListingStatus,
-  siteAnswersFromRow,
-} from "./project-listings.js";
-
-export type ListingDecision = "active" | "rejected";
-
-/** Days to milliseconds. A unit conversion, not a policy duration. */
-const MS_PER_DAY = 24 * 60 * 60 * 1000;
-
-const SELECT = {
-  id: true,
-  siteId: true,
-  leadId: true,
-  slug: true,
-  name: true,
-  oneLiner: true,
-  problem: true,
-  url: true,
-  product: true,
-  commitment: true,
-  teamComposition: true,
-  faqs: true,
-  anythingElse: true,
-  address: true,
-  // #5279 — the structured parts beside the display string.
-  addressLine1: true,
-  addressLine2: true,
-  addressCity: true,
-  addressRegion: true,
-  addressPostalCode: true,
-  addressCountry: true,
-  questions: true,
-  // #5285 — the operator's review payload carries EVERY site answer, the
-  // `operator-only` ones included. That visibility is what it is for: an
-  // answer a site asked for its own triage reaches the reviewer and stops
-  // short of the public read, which narrows through `publicSiteAnswers`.
-  siteAnswers: true,
-  founderName: true,
-  founderEmail: true,
-  founderCompany: true,
-  headline: true,
-  logoMarkUrl: true,
-  logoWordmarkUrl: true,
-  featured: true,
-  status: true,
-  consentAt: true,
-  decidedAt: true,
-  decidedBy: true,
-  issueUrl: true,
-  experimentKey: true,
-  windowDays: true,
-  windowEndsAt: true,
-  slackChannel: true,
-  slackTs: true,
-  createdAt: true,
-  updatedAt: true,
-} as const satisfies Prisma.ProjectListingSelect;
-
-type Row = Prisma.ProjectListingGetPayload<{ select: typeof SELECT }>;
-
-/**
- * Mirrors `project-listings.ts#attachWaitlistCounts`'s join shape for the
- * single row this module ever handles.
- *
- * Since #5036 D6d the listing stores the experiment's KEY, so this is one
- * count against `WaitlistScore.experimentKey` — the `WaitlistExperiment` read
- * that existed only to translate an id into that key is gone from both
- * modules.
- */
-async function waitlistCountFor(row: Row): Promise<number> {
-  if (!row.experimentKey) return 0;
-  return prisma.waitlistScore.count({
-    where: { siteId: row.siteId, experimentKey: row.experimentKey },
-  });
-}
-
-function toListing(row: Row, waitlistCount: number): ProjectListing {
-  return {
-    id: row.id,
-    siteId: row.siteId,
-    leadId: row.leadId,
-    slug: row.slug,
-    name: row.name,
-    headline: row.headline,
-    oneLiner: row.oneLiner,
-    problem: row.problem,
-    url: row.url,
-    product: row.product as ProjectListing["product"],
-    commitment: row.commitment as ProjectListing["commitment"],
-    teamComposition: row.teamComposition as ProjectListing["teamComposition"],
-    faqs: row.faqs as unknown as ProjectListingFaqs | null,
-    anythingElse: row.anythingElse,
-    address: row.address,
-    // #5279 — one reader of the parts, shared with `project-listings.ts`, so
-    // the two row renderers cannot drift on what "has parts" means.
-    addressParts: addressPartsFromRow(row),
-    founderName: row.founderName,
-    founderEmail: row.founderEmail,
-    founderCompany: row.founderCompany,
-    questions: row.questions as unknown as ProjectListingQuestions | null,
-    siteAnswers: siteAnswersFromRow(row.siteAnswers),
-    logoMarkUrl: row.logoMarkUrl,
-    logoWordmarkUrl: row.logoWordmarkUrl,
-    featured: row.featured,
-    status: computeListingStatus(row.status, row.windowEndsAt, new Date(), row.featured),
-    consentAt: row.consentAt.toISOString(),
-    decidedAt: row.decidedAt ? row.decidedAt.toISOString() : null,
-    decidedBy: row.decidedBy,
-    issueUrl: row.issueUrl,
-    experimentKey: row.experimentKey,
-    windowEndsAt: row.windowEndsAt ? row.windowEndsAt.toISOString() : null,
-    waitlistCount,
-    createdAt: row.createdAt.toISOString(),
-    updatedAt: row.updatedAt.toISOString(),
-  };
-}
-
-export type DecideListingInput = {
-  id: string;
-  decision: ListingDecision;
-  decidedBy: string;
-  /** Tenant scope for the PATCH route; omitted by the Slack handler (no tenant context on a button click). */
-  siteId?: string;
-};
-
-export type DecideListingResult =
-  | {
-      ok: true;
-      changed: boolean;
-      value: ProjectListing;
-      /** The row's posted-message coordinates, for the Slack route's `chat.update` — never part of `value`. */
-      slack: { channel: string | null; ts: string | null };
-    }
-  | {
-      ok: false;
-      error: { kind: "not_found" | "invalid_transition"; message: string };
-    };
-
-const DECIDED_STATUSES: ReadonlySet<string> = new Set(["active", "rejected"]);
-
-/**
- * The window, in whole days, to stamp on an approve. The row's own
- * `windowDays` (the applicant's request, clamped at create against the site's
- * terms) when it has one; otherwise the site's configured default clamped the
- * same way, for a row that was already pending when the column shipped.
- * `null` when the row does not exist — the caller's fresh read reports that.
- */
-async function windowDaysFor(id: string, siteId: string | undefined): Promise<number | null> {
-  const row = await prisma.projectListing.findFirst({
-    where: siteId !== undefined ? { id, siteId } : { id },
-    select: { siteId: true, windowDays: true },
-  });
-  if (!row) return null;
-  if (row.windowDays !== null) return row.windowDays;
-  return clampWindowDays(undefined, await listingConfigFor(row.siteId));
-}
-
-/**
- * The transition write is a GUARDED `updateMany` — `where` includes
- * `status: "applied"`, so the write only lands if the row is STILL `applied`
- * at the moment Postgres evaluates it (row-level locking makes this atomic;
- * mirrors the compare-and-swap shape `routes/webhooks/stripe.ts#stampFlowCheckout`
- * uses on `FlowCheckout.status`). `count === 1` means THIS call made the
- * transition; `count === 0` means it didn't — either the row was never
- * `applied` to begin with, or a CONCURRENT call already decided it between
- * this call's own read and write (security review, PR #4999: a plain
- * read-then-write here would let two racing calls — e.g. Slack's own retry,
- * or a Slack click racing an operator's PATCH — both observe `applied` and
- * both "succeed", double-sending the founder email and possibly leaving the
- * row in whichever decision wrote last). Either way, a fresh read after the
- * guarded write tells the caller which: already decided (idempotent
- * `changed: false`) or a genuinely invalid transition (`live`/`closed`).
- */
-export async function decideListing({
-  id,
-  decision,
-  decidedBy,
-  siteId,
-}: DecideListingInput): Promise<DecideListingResult> {
-  const decidedAt = new Date();
-
-  // #5033 — the window this listing was granted, resolved BEFORE the guarded
-  // write because a `updateMany` cannot read a column it is also setting.
-  // `windowDays` is immutable once stamped at create, so reading it outside
-  // the guard is not part of the compare-and-swap. A row that predates the
-  // column (an application still pending when this shipped) has none, and
-  // takes the site's configured default instead.
-  const windowDays = await windowDaysFor(id, siteId);
-
-  const updateResult = await prisma.projectListing.updateMany({
-    where: siteId !== undefined ? { id, siteId, status: "requested" } : { id, status: "requested" },
-    data: {
-      status: decision,
-      decidedAt,
-      decidedBy,
-      ...(decision === "active" &&
-        windowDays !== null && {
-          windowEndsAt: new Date(decidedAt.getTime() + windowDays * MS_PER_DAY),
-        }),
-    },
-  });
-
-  const current = await prisma.projectListing.findFirst({
-    where: siteId !== undefined ? { id, siteId } : { id },
-    select: SELECT,
-  });
-  if (!current) {
-    return { ok: false, error: { kind: "not_found", message: "Project listing not found" } };
-  }
-
-  if (updateResult.count === 1) {
-    // #5001 — the approve's downstream effects (the diagnostic projection).
-    // Never throws; a failure is logged and the decision stands. Re-read
-    // afterwards so `value.experimentKey` reflects the projection.
-    await onListingDecided(current.siteId, current.id, decision);
-    const projected =
-      (await prisma.projectListing.findFirst({ where: { id: current.id }, select: SELECT })) ?? current;
-    const waitlistCount = await waitlistCountFor(projected);
-    return {
-      ok: true,
-      changed: true,
-      value: toListing(projected, waitlistCount),
-      slack: { channel: projected.slackChannel, ts: projected.slackTs },
-    };
-  }
-
-  // The guarded write matched nothing — the row wasn't `applied` when
-  // Postgres evaluated the guard. Read its CURRENT status to tell an
-  // already-decided idempotent no-op from a genuinely invalid transition.
-  if (DECIDED_STATUSES.has(current.status)) {
-    const waitlistCount = await waitlistCountFor(current);
-    return {
-      ok: true,
-      changed: false,
-      value: toListing(current, waitlistCount),
-      slack: { channel: current.slackChannel, ts: current.slackTs },
-    };
-  }
-
-  return {
-    ok: false,
-    error: {
-      kind: "invalid_transition",
-      message: `cannot transition from '${current.status}' to '${decision}'`,
-    },
-  };
-}
-
-/**
- * Sends the founder's approve/reject email for a just-decided listing
- * (#4999 step 5).
- *
- * Reasonable-call env-var reuse (this issue's footprint is the three Slack
- * vars only — no new email-specific var): `fromAddress` reads the existing
- * `AILK_LEAD_NOTIFICATION_FROM` (already the site's configured "From:" for
- * lead-facing system email, per `services/lead-routing.ts`); the Working
- * Session and diagnostic links are derived from the existing
- * `config.FRONTEND_URL` + fixed paths. The diagnostic page itself is #5001's
- * build — this link is a forward reference to a route that doesn't exist
- * yet. `brand` is left unset (the template's clean, unbranded default) since
- * no per-site branding source is wired into `apps/api` today.
- *
- * Never throws; a missing `AILK_LEAD_NOTIFICATION_FROM` no-ops (logs
- * `listing-email-skipped`, id + decision only) rather than failing the
- * decision that has already landed.
- *
- * On an APPROVE, also fires `fileListingIssue` (#5000) after the email —
- * fire-and-forget, `.catch`-guarded on top of that function's own internal
- * try/catch, so neither a slow GitHub call nor a filing failure can delay or
- * reach the approve path that has already committed. Runs regardless of the
- * email's own outcome (a Resend failure and a GitHub failure are independent
- * best-effort side effects of the same committed decision).
- */
-export async function sendListingDecisionEmail(
-  listing: ProjectListing,
-  decision: ListingDecision,
-): Promise<void> {
-  const fromAddress = process.env["AILK_LEAD_NOTIFICATION_FROM"];
-  if (!fromAddress) {
-    logger.info({ listingId: listing.id, decision }, "listing-email-skipped");
-    fileIssueOnApprove(listing, decision);
-    return;
-  }
-
-  const workingSession = `${config.FRONTEND_URL}/working-session`;
-  // #5036 D1 — `name` and `slug` are nullable at rest so a half-filled draft
-  // is storable, but a decision only ever lands on a SUBMITTED row, which
-  // proved both. The fallbacks discharge the type, they do not paper over a
-  // reachable state.
-  const projectName = listing.name ?? listing.founderName;
-  const diagnosticSlug = listing.slug ?? listing.id;
-
-  const result =
-    decision === "active"
-      ? await sendListingApprovedEmail({
-          to: listing.founderEmail,
-          fromAddress,
-          founderName: listing.founderName,
-          projectName,
-          links: { workingSession },
-        })
-      : await sendListingRejectedEmail({
-          to: listing.founderEmail,
-          fromAddress,
-          founderName: listing.founderName,
-          projectName,
-          links: { workingSession, diagnostic: `${config.FRONTEND_URL}/diagnostic/${diagnosticSlug}` },
-        });
-
-  if (!result.ok) {
-    logger.warn(
-      { listingId: listing.id, decision, errorKind: result.error.kind },
-      "listing email send failed",
-    );
-  }
-
-  fileIssueOnApprove(listing, decision);
-}
-
-/**
- * Fire-and-forget entry to `fileListingIssue` (#5000) — a no-op on
- * `rejected`. `fileListingIssue` already never throws (its own try/catch
- * around the fetch + DB write); this `.catch` is a second boundary for the
- * one thing outside that try — `renderListingIssue` running before it — so
- * NOTHING from this call can ever propagate into `sendListingDecisionEmail`'s
- * caller.
- */
-function fileIssueOnApprove(listing: ProjectListing, decision: ListingDecision): void {
-  if (decision !== "active") return;
-  fileListingIssue(listing).catch((err: unknown) => {
-    logger.warn(
-      { listingId: listing.id, errName: err instanceof Error ? err.name : "UnknownError" },
-      "listing issue filing rejected unexpectedly",
-    );
-  });
-}
-
-// ─── #5001 — the approve-path side-effect seam ─────────────────────────────
-
-/** The status whose arrival triggers the projection — the approved state. */
-const APPROVED = "active";
-
-/**
- * Run the decision's downstream effects for one listing. Called by
- * `patchProjectListing` immediately after a successful transition write;
- * never throws.
- */
-export async function onListingDecided(
-  siteId: string,
-  listingId: string,
-  toStatus: string,
-): Promise<void> {
-  if (toStatus !== APPROVED) return;
-
-  try {
-    const row = await prisma.projectListing.findFirst({
-      where: { id: listingId, siteId },
-      select: {
-        id: true,
-        siteId: true,
-        slug: true,
-        name: true,
-        oneLiner: true,
-        questions: true,
-      },
-    });
-    if (!row) return;
-
-    // The stored `questions` blob is validated on write (#4998's POST route)
-    // — re-parsing here is defense in depth, and the one place a row that
-    // predates or drifts from the template is skipped rather than projected
-    // into a malformed flow.
-    // #5036 D1 — `slug`/`name`/`oneLiner` are nullable at rest so a half-filled
-    // draft is storable. A row can only reach `active` through `submit`, which
-    // asserts all three, so this discharges a type-level possibility rather
-    // than a reachable state — and skips rather than throwing, matching the
-    // fail-soft contract this whole seam carries.
-    if (row.slug === null || row.name === null || row.oneLiner === null) {
-      logger.warn(
-        { siteId, listingId, kind: "incomplete_listing" },
-        "[project-listing-decision] skipping flow generation — an approved listing is missing submit-time fields",
-      );
-      return;
-    }
-
-    const questions = projectListingQuestionsSchema.safeParse(row.questions);
-    if (!questions.success) {
-      logger.warn(
-        { siteId, listingId, slug: row.slug, kind: "invalid_questions" },
-        "[project-listing-decision] skipping flow generation — stored questions failed schema validation",
-      );
-      return;
-    }
-
-    const result = await generateListingFlow({
-      id: row.id,
-      siteId: row.siteId,
-      slug: row.slug,
-      name: row.name,
-      oneLiner: row.oneLiner,
-      questions: questions.data,
-    });
-
-    if (!result.ok) {
-      logger.error(
-        { siteId, listingId, slug: row.slug, kind: result.error.kind },
-        "[project-listing-decision] flow generation failed — the listing is approved but has no diagnostic",
-      );
-      return;
-    }
-
-    logger.info(
-      { siteId, listingId, slug: row.slug, kind: "generated" },
-      "[project-listing-decision] diagnostic flow + experiment generated",
-    );
-  } catch (err) {
-    logger.error(
-      {
-        siteId,
-        listingId,
-        errKind: err instanceof Error ? err.constructor.name : typeof err,
-      },
-      "[project-listing-decision] approve hook failed — the transition still succeeded",
-    );
-  }
-}