create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,426 @@
+/**
+ * @file project-listing-flow.ts
+ * @description The approve-time projection (#5001): a `ProjectListing` row's
+ * `questions` block becomes a live diagnostic — one `FlowDefinition` the
+ * visitor walks at `/v1/flows/{slug}` and one `WaitlistExperiment` keyed
+ * `{slug}` that scores the walk through the shared scoring rule
+ * (`@working-theory/database/flows/listing-diagnostic`).
+ *
+ * `generateListingFlow` writes through the two existing validated paths —
+ * `upsertFlowDefinition` (`flow-engine.ts`) and `upsertWaitlistExperiment`
+ * (`waitlist-experiments.ts`) — never a second ad-hoc Prisma write, and
+ * never `seedWaitlistExperiments`/`materializeWaitlistFlows`. Both underlying
+ * writes upsert on `[siteId, slug]` / `[siteId, key]`, and the `experimentKey`
+ * write-back is the same value every time, so re-approving a listing is a
+ * no-op rather than a duplicate.
+ *
+ * ONE vocabulary for the scored questions, since #5036 D4: the flow renders
+ * the founder's own option LABELS under the founder's own option VALUES, the
+ * register keys its `optionWeights` on those same values
+ * (`buildListingDiagnosticScoring`), and the experiment's `questionSet`
+ * declares that same per-listing option list — which is what satisfies
+ * `waitlistExperimentConfigSchema`'s "every weights key must be a declared
+ * option of the question it names" cross-validation. The old
+ * `q{n}:{i}of{k}` positional token, and the finite value universe it forced
+ * the question set to declare, are both gone. Only the EXTRAS keep a
+ * positional encoding (`x1:0of3`); they are unscored, so nothing resolves
+ * them by value.
+ *
+ * The tier NEVER reaches the visitor: the flow's terminal `message` step
+ * carries the confirmation line and the founder's own one-liner, and the
+ * config declares no `thankYou` / `deliverables` block, so nothing on the
+ * visitor's path can render a scoring outcome.
+ *
+ * PII boundary: logs and returned errors carry only `{ siteId, listingId,
+ * slug }` — never `founderEmail`, `founderName`, or `questions` (the same
+ * discipline `project-listings.ts` and `lead-routing.ts` document).
+ */
+
+import { buildListingDiagnosticScoring } from "@working-theory/database/flows/listing-diagnostic";
+import type {
+  FlowConfig,
+  FlowStep,
+  ProjectListingQuestions,
+  WaitlistQuestion,
+} from "@working-theory/validation";
+
+import { prisma } from "../lib/prisma.js";
+
+import { upsertFlowDefinition } from "./flow-engine.js";
+import { upsertWaitlistExperiment } from "./waitlist-experiments.js";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/** The subset of the row the projection reads. */
+export type ListingFlowSource = {
+  id: string;
+  siteId: string;
+  slug: string;
+  name: string;
+  oneLiner: string;
+  questions: ProjectListingQuestions;
+};
+
+export type GenerateListingFlowError = {
+  kind: "invalid_input" | "flows_not_configured";
+  message: string;
+};
+
+export type GenerateListingFlowResult =
+  | { ok: true; flowSlug: string; experimentKey: string }
+  | { ok: false; error: GenerateListingFlowError };
+
+const DEFAULT_LOCALE = "en";
+const en = (s: string) => ({ [DEFAULT_LOCALE]: s });
+
+/** At most three extras (`projectListingQuestionsSchema`). */
+type ExtraIndex = 1 | 2 | 3;
+
+// ─── Identifier derivation ──────────────────────────────────────────────────
+
+/**
+ * The register-internal waitlist key for a listing slug. A listing slug is
+ * kebab AND may start with a digit (`^[a-z0-9-]{3,48}$`, #4998), while
+ * `flowIdentifierSchema` demands `^[a-z][a-z0-9_]*$` — so the `listing_`
+ * prefix is load-bearing, not decoration. 8 + 48 = 56 ≤ the 64-char cap.
+ */
+export function listingWaitlistKey(slug: string): string {
+  return `listing_${slug.replace(/-/g, "_")}`;
+}
+
+/** `extra_1` … `extra_3` — the flow field name and question id for one extra. */
+function extraFieldName(index: ExtraIndex): string {
+  return `extra_${index}`;
+}
+
+/**
+ * An extra's option value — `x1:0of3`. Extras carry no points and no
+ * register resolves them, so the positional encoding survives #5036 D4's move
+ * to value-keyed scoring: nothing depends on an extra's value MEANING
+ * anything, only on it being stable and listing-independent for the CSV and
+ * any later reader.
+ */
+function extraOptionValue(index: ExtraIndex, optionIndex: number, arity: number): string {
+  return `x${index}:${optionIndex}of${arity}`;
+}
+
+// ─── The flow (what the visitor walks) ──────────────────────────────────────
+
+/**
+ * One option as every optioned question declares it — the founder's own
+ * `{ value, label }` pair. Since #5036 D4 the scored Q3–Q6 carry exactly the
+ * same shape as the unscored Q2: no positional rewrite in between.
+ */
+type OptionPair = { value: string; label: string };
+
+/** One single-select `field` step — the shape every diagnostic question takes. */
+function selectStep(
+  key: string,
+  fieldName: string,
+  prompt: string,
+  options: readonly OptionPair[],
+): FlowStep {
+  return {
+    key,
+    type: "field",
+    copy: { title: en(prompt) },
+    fields: [
+      {
+        name: fieldName,
+        inputType: "select",
+        required: true,
+        options: options.map((o) => ({ value: o.value, label: en(o.label) })),
+        copy: { label: en(prompt) },
+      },
+    ],
+  };
+}
+
+/**
+ * The six-category step order (#5001): contact → segment → problem → fit →
+ * urgency → price → open → extras, then the confirmation.
+ */
+function buildFlowSteps(listing: ListingFlowSource): FlowStep[] {
+  const { questions } = listing;
+
+  const steps: FlowStep[] = [
+    {
+      key: "contact",
+      type: "field",
+      copy: { title: en(`Join the ${listing.name} waitlist`) },
+      fields: [
+        {
+          name: "name",
+          inputType: "text",
+          mapsTo: "name",
+          copy: { label: en("Name") },
+        },
+        {
+          name: "email",
+          inputType: "email",
+          required: true,
+          mapsTo: "email",
+          copy: { label: en("Email") },
+        },
+      ],
+    },
+    // Every optioned question — the unscored Q2 (including the fixed
+    // `just-curious` bail-out its schema pins last) and the scored Q3–Q6
+    // alike — renders under the founder's OWN option values, so the raw value
+    // in the session state the weekly CSV reads is the same value the
+    // register scores.
+    selectStep("segment", "q2", questions.q2.prompt, questions.q2.options),
+    selectStep("problem", "q3", questions.q3.prompt, questions.q3.options),
+    selectStep("fit", "q4", questions.q4.prompt, questions.q4.options),
+    selectStep("urgency", "q5", questions.q5.prompt, questions.q5.options),
+    selectStep("price", "q6", questions.q6.prompt, questions.q6.options),
+    {
+      key: "open",
+      type: "field",
+      copy: { title: en(questions.q7.prompt) },
+      fields: [
+        {
+          name: "q7",
+          inputType: "textarea",
+          copy: { label: en(questions.q7.prompt) },
+        },
+      ],
+    },
+  ];
+
+  if (questions.extras.length > 0) {
+    steps.push({
+      key: "extras",
+      type: "field",
+      copy: { title: en("A few more questions") },
+      fields: questions.extras.map((extra, i) => {
+        const index = (i + 1) as ExtraIndex;
+        return {
+          name: extraFieldName(index),
+          inputType: "select" as const,
+          required: true,
+          options: extra.options.map((option, optionIndex) => ({
+            value: extraOptionValue(index, optionIndex, extra.options.length),
+            label: en(option.label),
+          })),
+          copy: { label: en(extra.prompt) },
+        };
+      }),
+    });
+  }
+
+  // Confirmation only — the founder's own line, never the tier.
+  steps.push({
+    key: "done",
+    type: "message",
+    copy: {
+      title: en(`You're on the ${listing.name} waitlist`),
+      ...(listing.oneLiner.trim().length > 0 && { body: en(listing.oneLiner) }),
+    },
+  });
+
+  return steps;
+}
+
+function buildFlowConfig(listing: ListingFlowSource): FlowConfig {
+  return {
+    slug: listing.slug,
+    defaultLocale: DEFAULT_LOCALE,
+    steps: buildFlowSteps(listing),
+    experiment: {
+      key: listing.slug,
+      waitlist: listingWaitlistKey(listing.slug),
+    },
+  };
+}
+
+// ─── The experiment (what scores the walk) ──────────────────────────────────
+
+/**
+ * The register's question set — every question mirrors the flow exactly,
+ * Q3–Q6 included: since #5036 D4 the register scores this listing's OWN
+ * option values, so the question set declares this listing's own options and
+ * the config-level cross-validation passes without a value universe.
+ */
+function buildQuestionSet(listing: ListingFlowSource): WaitlistQuestion[] {
+  const { questions } = listing;
+
+  const scored = (["q3", "q4", "q5", "q6"] as const).map((id) => ({
+    id,
+    prompt: en(questions[id].prompt),
+    answerType: "single" as const,
+    options: questions[id].options.map((o) => ({ value: o.value, label: en(o.label) })),
+  }));
+
+  return [
+    {
+      id: "name",
+      prompt: en("Name"),
+      answerType: "text" as const,
+      required: false,
+      mapsTo: "name" as const,
+    },
+    {
+      id: "email",
+      prompt: en("Email"),
+      answerType: "email" as const,
+      mapsTo: "email" as const,
+    },
+    {
+      id: "q2",
+      prompt: en(questions.q2.prompt),
+      answerType: "single" as const,
+      options: questions.q2.options.map((o) => ({ value: o.value, label: en(o.label) })),
+    },
+    ...scored,
+    {
+      id: "q7",
+      prompt: en(questions.q7.prompt),
+      answerType: "text" as const,
+      required: false,
+    },
+    ...questions.extras.map((extra, i) => {
+      const index = (i + 1) as ExtraIndex;
+      return {
+        id: extraFieldName(index),
+        prompt: en(extra.prompt),
+        answerType: "single" as const,
+        options: extra.options.map((option, optionIndex) => ({
+          value: extraOptionValue(index, optionIndex, extra.options.length),
+          label: en(option.label),
+        })),
+      };
+    }),
+  ];
+}
+
+function buildExperimentConfig(listing: ListingFlowSource): unknown {
+  const waitlistKey = listingWaitlistKey(listing.slug);
+  return {
+    key: listing.slug,
+    mode: "qualifying",
+    status: "live",
+    waitlists: [{ key: waitlistKey, flowSlug: listing.slug }],
+    questionSet: { version: 1, questions: buildQuestionSet(listing) },
+    // The shared scoring RULE, applied to this listing's own option values
+    // — same point names, same total, same tier floors for every listing;
+    // only the Q3/Q4 weight keys differ, because those keys are the founder's
+    // own values (#5036 D4). Embedded verbatim:
+    // `waitlistExperimentConfigSchema` carries scoring by value and declares
+    // no by-reference slot.
+    scoring: buildListingDiagnosticScoring(listing.questions),
+    tracking: {
+      version: 1,
+      utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+      waitlists: { [waitlistKey]: { campaign: listing.slug, channels: ["direct"] } },
+    },
+    stripeConfigRef: null,
+  };
+}
+
+// ─── The inverse (what the weekly CSV reads) ────────────────────────────────
+
+/**
+ * `field name -> option value -> the founder's own label`, for every optioned
+ * question the projection emits. The weekly CSV (`listing-csv-sweep.ts`)
+ * renders a signup's stored answer through this so the founder reads their own
+ * wording rather than a bare value.
+ *
+ * Q2–Q6 collapse to a plain value→label map since #5036 D4: the flow renders
+ * the founder's own values, so the inverse is the founder's own option list
+ * read the other way round. Only the extras still need the positional
+ * `extraOptionValue` — derived from the SAME call the projection emits, so
+ * the two can never disagree about what a stored value means.
+ */
+export function listingAnswerLabels(
+  questions: ProjectListingQuestions,
+): Record<string, Record<string, string>> {
+  const labels: Record<string, Record<string, string>> = {};
+
+  for (const question of ["q2", "q3", "q4", "q5", "q6"] as const) {
+    labels[question] = Object.fromEntries(
+      questions[question].options.map((option) => [option.value, option.label]),
+    );
+  }
+
+  questions.extras.forEach((extra, i) => {
+    const index = (i + 1) as ExtraIndex;
+    labels[extraFieldName(index)] = Object.fromEntries(
+      extra.options.map((option, optionIndex) => [
+        extraOptionValue(index, optionIndex, extra.options.length),
+        option.label,
+      ]),
+    );
+  });
+
+  return labels;
+}
+
+// ─── generateListingFlow ────────────────────────────────────────────────────
+
+/**
+ * Project an approved listing into its live diagnostic. Idempotent: both
+ * writes upsert on their natural key and the `experimentKey` write-back is
+ * stable, so a second approve changes nothing.
+ *
+ * Both joins are stated rather than inferred (#5036 D6d). The definition
+ * carries the listing's id, so a session started on this flow names the
+ * listing directly instead of relying on the flow's slug matching it; and the
+ * listing stores the experiment's KEY, which is the string `WaitlistScore`
+ * itself holds, so reading a listing's submissions is one hop rather than an
+ * id-to-key lookup. ADR 0009 forbids a relation across the namespace
+ * boundary, so both are plain strings — which is exactly why each has to be
+ * the string the other side actually stores.
+ *
+ * The FLOW is written first: an experiment row whose `waitlists[].flowSlug`
+ * resolves to nothing would leave `GET /v1/flows/{slug}` answering
+ * `flow_not_found` while the dashboard already showed a live experiment. The
+ * reverse ordering (a servable flow whose experiment has not landed yet)
+ * degrades to "collected, not yet scored" — recoverable on the next approve.
+ */
+export async function generateListingFlow(
+  listing: ListingFlowSource,
+): Promise<GenerateListingFlowResult> {
+  const flow = await upsertFlowDefinition(
+    listing.siteId,
+    buildFlowConfig(listing),
+    listing.id,
+  );
+  if (!flow.ok) {
+    return {
+      ok: false,
+      error: {
+        kind: flow.error.kind === "flows_not_configured" ? "flows_not_configured" : "invalid_input",
+        message: flow.error.message,
+      },
+    };
+  }
+
+  const experiment = await upsertWaitlistExperiment(
+    listing.siteId,
+    buildExperimentConfig(listing),
+  );
+  if (!experiment.ok) {
+    return {
+      ok: false,
+      error: {
+        kind:
+          experiment.error.kind === "flows_not_configured"
+            ? "flows_not_configured"
+            : "invalid_input",
+        message: experiment.error.message,
+      },
+    };
+  }
+
+  // The experiment's key IS the listing's slug (`buildExperimentConfig`), and
+  // it is what `WaitlistScore.experimentKey` stores.
+  const experimentKey = listing.slug;
+
+  await prisma.projectListing.update({
+    where: { id: listing.id },
+    data: { experimentKey },
+  });
+
+  return { ok: true, flowSlug: listing.slug, experimentKey };
+}

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

@@ -0,0 +1,251 @@
+/**
+ * @file project-listing-issue.ts
+ * @description The approve-time GitHub issue filing (#5000): an approved
+ * `ProjectListing` becomes a work order filed on the SITE's own repo
+ * (`AILK_GITHUB_REPO`), in the shape that repo's issue-claiming pipeline
+ * reads (`.claude/skills/file-issue/references/issue.md`'s canonical Issue
+ * body — `## What` / `## Why` / `## Acceptance Criteria` / `## Scope` /
+ * `## Grounding` / the `<!-- dep-graph: -->` block).
+ *
+ * `renderListingIssue` is pure — no fetch, no Prisma, no config read — so
+ * the shape is unit-testable against a fixture row with no network double.
+ * `fileListingIssue` is the effectful half: skip (env absent, or `issueUrl`
+ * already set) -> POST -> write `issueUrl` back on 201 -> log + return on
+ * ANY failure. It never throws; `project-listing-decision.ts`'s
+ * `sendListingDecisionEmail` calls it fire-and-forget after the founder
+ * email, with its own `.catch` boundary on top of the try/catch below, so a
+ * filing failure can never reach the approve path that has already
+ * committed.
+ *
+ * Injection hardening, mirroring `slack-notify.ts`'s `escapeMrkdwn` for the
+ * same class of anonymous-input risk (PR #4999 security review): every
+ * founder-authored scalar field (name/oneLiner/audience/problem/founderName/
+ * founderCompany/url) is (1) collapsed to a single line — an embedded
+ * newline could otherwise open a line with `## ` and forge a section a
+ * naive line-based consumer parser reads as real (e.g. a fake `## Scope`
+ * re-pointing what a worker builds), and (2) rendered as inline code, which
+ * GitHub never parses for an `@mention` or `#issue` auto-link. The
+ * `questions` block is embedded as fenced JSON instead — `JSON.stringify`
+ * already escapes any embedded newline to the two-character `\n` sequence,
+ * so no extra sanitization is needed there, and it stays byte-for-byte the
+ * stored value (#5000 AC2 — "the questions block verbatim").
+ *
+ * PII boundary: `founderEmail` lives on `ProjectListing` but is never
+ * referenced here — the row has it; this file never renders or logs it.
+ */
+import { logger } from "@working-theory/observability";
+import type { ProjectListing } from "@working-theory/validation";
+
+import { config } from "../config/index.js";
+import { prisma } from "../lib/prisma.js";
+
+const GITHUB_API_BASE = "https://api.github.com";
+const ISSUE_LABELS = ["status/ready"] as const;
+
+const SCOPE_PATHS = [
+  "apps/web/app/[locale]/projects/[slug]/**",
+  "apps/web/src/content/projects/**",
+  "apps/web/src/content/diagnostic/**",
+] as const;
+
+export type RenderListingIssueOptions = {
+  /** `owner/name` of the repo the issue is filed ON — the site's own repo, never this one. */
+  targetRepo: string;
+};
+
+export type RenderedListingIssue = {
+  title: string;
+  body: string;
+  labels: string[];
+};
+
+/**
+ * Collapses an embedded line ending (CR and/or LF) to a space — see the
+ * module doc's injection note — and strips backticks. Without stripping
+ * backticks, a founder-authored value containing one (e.g. `` Bob` @someone ``)
+ * closes `code()`'s single-backtick span early, leaving everything after it
+ * as live, unfenced markdown GitHub WILL autolink into a real `@mention`
+ * (PR #5011 security review, Finding 1) — the same failure mode `escapeMrkdwn`
+ * exists to prevent for Slack, just triggered by a different delimiter.
+ * A backtick is not meaningful content in any of these fields (a name, a
+ * one-liner, a URL, …), so substituting a straight quote is a lossless-enough
+ * trade for closing the injection outright, rather than computing a
+ * CommonMark-safe variable-length fence.
+ */
+function singleLine(value: string): string {
+  return value.replace(/[\r\n]+/g, " ").replace(/`/g, "'").trim();
+}
+
+/** What an absent field renders as. */
+const ABSENT = "—";
+
+/**
+ * Inline code: verbatim AND immune to GitHub's `@mention`/`#issue` markdown
+ * parsing.
+ *
+ * `null` is accepted because every application field became nullable at rest
+ * in #5036 D1 — a half-filled draft is a legitimate row. An issue is only ever
+ * filed from an APPROVED listing, which `submit` proved complete, so the null
+ * branch discharges a type-level possibility rather than a reachable state.
+ */
+function code(value: string | null): string {
+  return value === null ? ABSENT : `\`${singleLine(value)}\``;
+}
+
+/**
+ * Renders the build-issue title/body/labels from an approved listing row.
+ * Pure — every value comes from `listing` and `targetRepo`, nothing is read
+ * from config or the network.
+ */
+export function renderListingIssue(
+  listing: ProjectListing,
+  { targetRepo }: RenderListingIssueOptions,
+): RenderedListingIssue {
+  // `slug` is null only on a draft, and a draft never reaches this renderer.
+  const slug = listing.slug ?? listing.id;
+  const title = `feat(web): /projects/${slug} listing + diagnostic (listing ${listing.id})`;
+
+  const rowLines = [
+    `- id: ${code(listing.id)}`,
+    `- slug: ${code(listing.slug)}`,
+    `- name: ${code(listing.name)}`,
+    `- oneLiner: ${code(listing.oneLiner)}`,
+    `- problem: ${code(listing.problem)}`,
+    `- url: ${listing.url ? code(listing.url) : ABSENT}`,
+    `- product: ${code(listing.product)}`,
+    `- commitment: ${code(listing.commitment)}`,
+    `- teamComposition: ${code(listing.teamComposition)}`,
+    `- address: ${code(listing.address)}`,
+    `- anythingElse: ${listing.anythingElse ? code(listing.anythingElse) : ABSENT}`,
+    `- founderName: ${code(listing.founderName)}`,
+    `- founderCompany: ${listing.founderCompany ? code(listing.founderCompany) : ABSENT}`,
+  ].join("\n");
+
+  const questionsJson = JSON.stringify(listing.questions, null, 2);
+  // #5036 — the three FAQ entries the detail page renders. Emitted as FENCED
+  // JSON rather than as `- ` bullets, the same treatment `questions` already
+  // gets: `answer` is 1000 characters of anonymous free text with no
+  // control-character rule, and a bullet list is exactly the shape
+  // docs/lessons/project-listings/07 describes — anonymous text landing in a
+  // document a downstream tool parses by heading. Inside a fence it forges
+  // nothing.
+  const faqsJson = JSON.stringify(listing.faqs ?? [], null, 2);
+  const scopeLines = SCOPE_PATHS.map((p) => `- ${p}`).join("\n");
+
+  const body = `<!-- ailk-listing-issue: repo=${targetRepo} listing=${listing.id} -->
+
+## What
+
+Build the public listing page and its diagnostic flow for ${code(listing.name)}:
+
+- The page at \`/projects/${slug}\`, rendered from this row via the public read (\`GET /v1/project-listings/public\`).
+- The diagnostic at \`/flows/${slug}\`, registered from the flow generated on approve.
+
+**Row**
+
+${rowLines}
+
+**FAQs**
+
+\`\`\`\`json
+${faqsJson}
+\`\`\`\`
+
+**Questions**
+
+\`\`\`\`json
+${questionsJson}
+\`\`\`\`
+
+## Why
+
+An approved application must be a complete work order a worker can build from without the operator touching it again.
+
+## Acceptance Criteria
+
+- [ ] page renders from the row
+- [ ] diagnostic flow live at /flows/${slug}
+- [ ] waitlist joins land under the listing's experiment
+- [ ] /projects tile appears in the D6 order
+
+## Scope
+
+${scopeLines}
+
+## Grounding
+
+- **Governance:** \`internal\`
+- **Nature:** \`feature\`
+- **Resourced:** \`n/a\`
+
+<!-- dep-graph:
+  blocked-by:
+  blocks:
+  priority:
+  scope-paths: ${SCOPE_PATHS.join(", ")}
+-->
+`;
+
+  return { title, body, labels: [...ISSUE_LABELS] };
+}
+
+/**
+ * Files the build issue for an approved listing, writing `issueUrl` back on
+ * success. No-op (`github-skipped`) when `AILK_GITHUB_REPO`/`AILK_GITHUB_TOKEN`
+ * are absent, or when the row already carries `issueUrl` (idempotent — a
+ * second approve, or a stray re-call, never double-files). Never throws: any
+ * failure (network, non-201, a malformed response) is logged — id + status
+ * only, never the token, never a response body that could carry one — and
+ * the row is left with `issueUrl: null` for a later retry via the PATCH
+ * route.
+ */
+export async function fileListingIssue(listing: ProjectListing): Promise<void> {
+  const targetRepo = config.AILK_GITHUB_REPO;
+  const token = config.AILK_GITHUB_TOKEN;
+  if (!targetRepo || !token) {
+    logger.info({ listingId: listing.id }, "github-skipped");
+    return;
+  }
+  if (listing.issueUrl) {
+    return;
+  }
+
+  const { title, body, labels } = renderListingIssue(listing, { targetRepo });
+
+  try {
+    const res = await fetch(`${GITHUB_API_BASE}/repos/${targetRepo}/issues`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${token}`,
+        accept: "application/vnd.github+json",
+        "content-type": "application/json",
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+      body: JSON.stringify({ title, body, labels }),
+    });
+
+    if (res.status !== 201) {
+      logger.warn({ listingId: listing.id, status: res.status }, "listing issue filing failed");
+      return;
+    }
+
+    const json = (await res.json()) as { html_url?: unknown };
+    if (typeof json.html_url !== "string" || json.html_url.length === 0) {
+      logger.warn(
+        { listingId: listing.id, status: res.status },
+        "listing issue filing returned no html_url",
+      );
+      return;
+    }
+
+    await prisma.projectListing.update({
+      where: { id: listing.id },
+      data: { issueUrl: json.html_url },
+    });
+  } catch (err) {
+    logger.warn(
+      { listingId: listing.id, errName: err instanceof Error ? err.name : "UnknownError" },
+      "listing issue filing threw",
+    );
+  }
+}