create-ailk 0.1.0 → 0.1.1

package/templates/database/__tests__/flows-listing-diagnostic.test.ts

@@ -0,0 +1,392 @@
+/**
+ * @file flows-listing-diagnostic.test.ts
+ * @description The shared scoring RULE (#5001 AC2/AC3, reworked by #5036 D4):
+ * a register built from one listing's own questions scores its weakest path
+ * `curious`, its strongest `now`, and a mixed path where the 0–12 total says
+ * it does — evaluated through the real `evaluateWaitlistScoring`, never a
+ * reimplementation of the ladder.
+ *
+ * The load-bearing test here is "a reordered register scores an answer
+ * identically": #5036 D4 moved resolution from option POSITION to option
+ * VALUE, so reordering a founder's Q3/Q4 options and rebuilding the register
+ * leaves an already-stored answer scoring exactly what it always meant. Under
+ * the old `q{n}:{i}of{k}` encoding that assertion was not even expressible.
+ *
+ * The register must also parse against `waitlistScoringSchema` (the grammar
+ * `upsertWaitlistExperiment` validates on every write) AND survive
+ * `waitlistExperimentConfigSchema`'s config-level cross-validation, which is
+ * the only place the "every `optionWeights` key must be a declared option of
+ * the question it names" rule fires
+ * (docs/lessons/2026-09-07-shared-register-needs-a-shared-value-universe.md).
+ * The projection's REAL config is asserted the same way in
+ * `apps/api/src/services/__tests__/project-listing-flow.test.ts`; the minimal
+ * wrapper below exists so a register that could never be persisted fails in
+ * this package rather than one layer away.
+ */
+
+import {
+  evaluateWaitlistScoring,
+  projectListingQuestionsSchema,
+  waitlistExperimentConfigSchema,
+  waitlistScoringSchema,
+  type ProjectListingQuestions,
+} from "@working-theory/validation";
+
+import {
+  buildListingDiagnosticScoring,
+  listingDiagnosticOptionWeights,
+  listingOptionPoints,
+  LISTING_DIAGNOSTIC_Q5_WEIGHTS,
+  LISTING_DIAGNOSTIC_Q6_WEIGHTS,
+} from "../flows/listing-diagnostic";
+
+/**
+ * A listing's template instance: Q3/Q4 at their 4-option maximum with
+ * founder-authored values, Q5's three fixed urgency values, Q6's four fixed
+ * bands. Parsed through the real schema so the fixture cannot drift from the
+ * contract the projection reads.
+ */
+const QUESTIONS: ProjectListingQuestions = projectListingQuestionsSchema.parse({
+  q2: {
+    prompt: "What brings you here?",
+    options: [
+      { value: "shipping-now", label: "I'm shipping something now" },
+      { value: "just-curious", label: "Just curious" },
+    ],
+  },
+  q3: {
+    prompt: "How painful is this problem today?",
+    options: [
+      { value: "none", label: "Not a problem" },
+      { value: "mild", label: "Mildly annoying" },
+      { value: "real", label: "A real drag" },
+      { value: "blocking", label: "It's blocking me" },
+    ],
+  },
+  q4: {
+    prompt: "How close is this to what you need?",
+    options: [
+      { value: "off", label: "Not what I need" },
+      { value: "adjacent", label: "Adjacent" },
+      { value: "close", label: "Close" },
+      { value: "exact", label: "Exactly it" },
+    ],
+  },
+  q5: {
+    prompt: "When would you use this?",
+    options: [
+      { value: "urgent", label: "Right away" },
+      { value: "planning", label: "Next quarter" },
+      { value: "exploring", label: "Just looking" },
+    ],
+  },
+  q6: {
+    prompt: "What would you pay?",
+    options: [
+      { value: "low", label: "Nothing yet" },
+      { value: "medium", label: "A little" },
+      { value: "high", label: "A real budget" },
+      { value: "critical", label: "Whatever it takes" },
+    ],
+  },
+  q7: { prompt: "Anything else we should know?" },
+  extras: [],
+});
+
+const SCORING = buildListingDiagnosticScoring(QUESTIONS);
+
+/** The `optionWeights` map the register declares for one scored question. */
+function weightsOf(
+  scoring: ReturnType<typeof buildListingDiagnosticScoring>,
+  question: string,
+): Record<string, number> {
+  const point = scoring.points.find((p) => p.question === question);
+  if (!point || point.kind !== "optionWeights") {
+    throw new Error(`no optionWeights point for "${question}"`);
+  }
+  return point.weights;
+}
+
+/**
+ * The minimal experiment config that carries a register — enough to fire
+ * `waitlistExperimentConfigSchema`'s weights-key cross-validation, and
+ * nothing more. The question set declares THIS listing's own options, which
+ * is precisely what value-keyed scoring makes possible.
+ */
+function experimentConfigFor(questions: ProjectListingQuestions): unknown {
+  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 {
+    key: "orbit-notes",
+    mode: "qualifying",
+    status: "live",
+    waitlists: [{ key: "listing_orbit_notes", flowSlug: "orbit-notes" }],
+    questionSet: {
+      version: 1,
+      questions: [
+        {
+          id: "email",
+          prompt: { en: "Email" },
+          answerType: "email",
+          mapsTo: "email",
+        },
+        ...scored,
+      ],
+    },
+    scoring: buildListingDiagnosticScoring(questions),
+    tracking: {
+      version: 1,
+      utm: { source: "utm_source", medium: "utm_medium", campaign: "utm_campaign" },
+      waitlists: { listing_orbit_notes: { campaign: "orbit-notes", channels: ["direct"] } },
+    },
+    stripeConfigRef: null,
+  };
+}
+
+describe("listingOptionPoints — the founder's declared order → 0..3", () => {
+  it("spans 0..3 whatever the arity, weakest first", () => {
+    expect([0, 1, 2].map((i) => listingOptionPoints(i, 3))).toEqual([0, 2, 3]);
+    expect([0, 1, 2, 3].map((i) => listingOptionPoints(i, 4))).toEqual([0, 1, 2, 3]);
+  });
+
+  it("yields 0 for a question with no spread to score", () => {
+    expect(listingOptionPoints(0, 1)).toBe(0);
+  });
+});
+
+describe("listingDiagnosticOptionWeights — keyed by value, weighted by order", () => {
+  it("keys the founder's own values and weights them by their declared order", () => {
+    expect(
+      listingDiagnosticOptionWeights([
+        { value: "none" },
+        { value: "mild" },
+        { value: "real" },
+        { value: "blocking" },
+      ]),
+    ).toEqual({ none: 0, mild: 1, real: 2, blocking: 3 });
+  });
+
+  it("still spans 0..3 at three options", () => {
+    expect(
+      listingDiagnosticOptionWeights([{ value: "x" }, { value: "y" }, { value: "z" }]),
+    ).toEqual({ x: 0, y: 2, z: 3 });
+  });
+});
+
+describe("the fixed-value questions", () => {
+  it("scores Q5 STRONGEST-first — `urgent` 3, `exploring` 0", () => {
+    // #4998 pins Q5's values urgency-descending, so the positional rule
+    // scored `urgent` 0 (docs/lessons/2026-09-07-q5-fixed-order-is-
+    // strongest-first.md). Value-keyed weights say what is meant instead.
+    expect(LISTING_DIAGNOSTIC_Q5_WEIGHTS).toEqual({
+      urgent: 3,
+      planning: 2,
+      exploring: 0,
+    });
+  });
+
+  it("keeps Q6 weakest-first — `low` 0, `critical` 3", () => {
+    expect(LISTING_DIAGNOSTIC_Q6_WEIGHTS).toEqual({
+      low: 0,
+      medium: 1,
+      high: 2,
+      critical: 3,
+    });
+  });
+
+  it("leaves the per-question spread at 0..3, so the total stays 0..12", () => {
+    for (const question of ["q3", "q4", "q5", "q6"]) {
+      const values = Object.values(weightsOf(SCORING, question));
+      expect(Math.min(...values)).toBe(0);
+      expect(Math.max(...values)).toBe(3);
+    }
+  });
+});
+
+describe("buildListingDiagnosticScoring — the register", () => {
+  it("parses against waitlistScoringSchema", () => {
+    expect(waitlistScoringSchema.safeParse(SCORING).success).toBe(true);
+  });
+
+  it("parses against waitlistExperimentConfigSchema at the config level", () => {
+    // The weights-key cross-validation only fires here — the question set
+    // declares this listing's OWN options, and the register keys on the same
+    // values, so no value universe is needed.
+    const parsed = waitlistExperimentConfigSchema.safeParse(experimentConfigFor(QUESTIONS));
+    expect(parsed.success).toBe(true);
+  });
+
+  it("scores Q3–Q6 only — Q1/Q2/Q7 and the extras carry no points", () => {
+    expect(SCORING.points.map((p) => p.question)).toEqual(["q3", "q4", "q5", "q6"]);
+  });
+
+  it("keys every weight on the founder's own option values, and nothing else", () => {
+    for (const question of ["q3", "q4", "q5", "q6"] as const) {
+      expect(Object.keys(weightsOf(SCORING, question)).sort()).toEqual(
+        QUESTIONS[question].options.map((o) => o.value).sort(),
+      );
+    }
+  });
+
+  it("gives two listings the same RULE — same shape, same tiers, same fixed weights", () => {
+    const other = buildListingDiagnosticScoring(
+      projectListingQuestionsSchema.parse({
+        ...QUESTIONS,
+        q3: {
+          prompt: "How badly does this hurt?",
+          options: [
+            { value: "x", label: "Not at all" },
+            { value: "y", label: "Somewhat" },
+            { value: "z", label: "Badly" },
+          ],
+        },
+      }),
+    );
+
+    expect(other.points.map((p) => p.name)).toEqual(SCORING.points.map((p) => p.name));
+    expect(other.scores).toEqual(SCORING.scores);
+    expect(other.tiers).toEqual(SCORING.tiers);
+    expect(other.default).toEqual(SCORING.default);
+    // Only the founder-authored questions' KEYS differ.
+    expect(weightsOf(other, "q5")).toEqual(weightsOf(SCORING, "q5"));
+    expect(weightsOf(other, "q6")).toEqual(weightsOf(SCORING, "q6"));
+    expect(weightsOf(other, "q3")).toEqual({ x: 0, y: 2, z: 3 });
+  });
+
+  // ── The three paths (#5001 AC2) ────────────────────────────────────────
+
+  it("scores the WEAKEST path 0 → curious", () => {
+    const result = evaluateWaitlistScoring(SCORING, {
+      q3: "none",
+      q4: "off",
+      q5: "exploring",
+      q6: "low",
+    });
+    expect(result.score).toBe(0);
+    expect(result.tier).toBe("curious");
+  });
+
+  it("scores the STRONGEST path 12 → now", () => {
+    const result = evaluateWaitlistScoring(SCORING, {
+      q3: "blocking",
+      q4: "exact",
+      q5: "urgent",
+      q6: "critical",
+    });
+    expect(result.score).toBe(12);
+    expect(result.tier).toBe("now");
+  });
+
+  it("scores a MIXED path by the sum of its answers", () => {
+    // q3 `real` 2 · q4 `adjacent` 1 · q5 `urgent` 3 · q6 `medium` 1 = 7 →
+    // soon (7–9).
+    const result = evaluateWaitlistScoring(SCORING, {
+      q3: "real",
+      q4: "adjacent",
+      q5: "urgent",
+      q6: "medium",
+    });
+    expect(result.score).toBe(7);
+    expect(result.tier).toBe("soon");
+  });
+
+  it.each([
+    [{ q3: "none", q4: "off", q5: "exploring", q6: "critical" }, 3, "curious"],
+    [{ q3: "mild", q4: "adjacent", q5: "exploring", q6: "high" }, 4, "later"],
+    [{ q3: "real", q4: "close", q5: "exploring", q6: "high" }, 6, "later"],
+    [{ q3: "blocking", q4: "exact", q5: "exploring", q6: "critical" }, 9, "soon"],
+    [{ q3: "blocking", q4: "exact", q5: "planning", q6: "critical" }, 11, "now"],
+  ])("puts total %j (%i) in the %s band", (answers, expectedScore, expectedTier) => {
+    const result = evaluateWaitlistScoring(SCORING, answers as Record<string, string>);
+    expect(result.score).toBe(expectedScore);
+    expect(result.tier).toBe(expectedTier);
+  });
+
+  it("is total — an unanswered diagnostic still lands on a tier", () => {
+    const result = evaluateWaitlistScoring(SCORING, {});
+    expect(result.score).toBe(0);
+    expect(result.tier).toBe("curious");
+  });
+
+  // ── #5036 D4: resolution by value, not position ────────────────────────
+
+  it("a reordered register scores an answer identically", () => {
+    // The founder swaps the two middle Q3 options and the two middle Q4
+    // options — a real edit to the register, which changes what those two
+    // options are worth. The ANSWERED options (`blocking`, the strongest Q3;
+    // `off`, the weakest Q4) keep the strength the founder declared, so the
+    // same stored answer must score exactly what it scored before.
+    //
+    // This test is not expressible under the old `q{n}:{i}of{k}` encoding:
+    // there was no founder value to answer with, and a stored `q3:3of4`
+    // token was a POSITION, so any reorder or insert silently repointed it at
+    // a different option. Resolving by value is what makes the answer survive
+    // an edit to the register.
+    const answers = { q3: "blocking", q4: "off", q5: "urgent", q6: "high" };
+    const before = evaluateWaitlistScoring(SCORING, answers);
+
+    const reordered = buildListingDiagnosticScoring(
+      projectListingQuestionsSchema.parse({
+        ...QUESTIONS,
+        q3: {
+          prompt: QUESTIONS.q3.prompt,
+          options: [
+            { value: "none", label: "Not a problem" },
+            { value: "real", label: "A real drag" },
+            { value: "mild", label: "Mildly annoying" },
+            { value: "blocking", label: "It's blocking me" },
+          ],
+        },
+        q4: {
+          prompt: QUESTIONS.q4.prompt,
+          options: [
+            { value: "off", label: "Not what I need" },
+            { value: "close", label: "Close" },
+            { value: "adjacent", label: "Adjacent" },
+            { value: "exact", label: "Exactly it" },
+          ],
+        },
+      }),
+    );
+    const after = evaluateWaitlistScoring(reordered, answers);
+
+    expect(before.score).toBe(8);
+    expect(after.score).toBe(before.score);
+    expect(after.tier).toBe(before.tier);
+
+    // The reorder is not a no-op: the two moved options really did trade
+    // weights, and the register the answer was resolved against is a
+    // different object than the one it was stored under.
+    expect(weightsOf(reordered, "q3")).not.toEqual(weightsOf(SCORING, "q3"));
+    expect(weightsOf(reordered, "q4")).not.toEqual(weightsOf(SCORING, "q4"));
+    expect(weightsOf(reordered, "q3")).toEqual({ none: 0, real: 1, mild: 2, blocking: 3 });
+  });
+
+  it("still parses at the config level after a reorder", () => {
+    // A reordered register's keys are still exactly the (reordered) options
+    // the question set declares, so the cross-validation holds.
+    const reordered = projectListingQuestionsSchema.parse({
+      ...QUESTIONS,
+      q3: {
+        prompt: QUESTIONS.q3.prompt,
+        options: [
+          { value: "none", label: "Not a problem" },
+          { value: "real", label: "A real drag" },
+          { value: "mild", label: "Mildly annoying" },
+          { value: "blocking", label: "It's blocking me" },
+        ],
+      },
+    });
+    expect(
+      waitlistExperimentConfigSchema.safeParse(experimentConfigFor(reordered)).success,
+    ).toBe(true);
+  });
+});

package/templates/database/__tests__/flows-presets.test.ts

@@ -0,0 +1,173 @@
+/**
+ * @file flows-presets.test.ts
+ * @description Parse-validity for the four static capture presets (#3958
+ * §3.5; the `roadmap` preset added by #3963 D2). This is the AC1 + AC3
+ * verification: each preset must parse against
+ * `flowConfigSchema` and every user-facing string must be a
+ * `LocalizedString` carrying the flow's `defaultLocale` key. A bare-string
+ * literal is not assignable to `LocalizedString` at the type layer — caught
+ * by `pnpm type-check`'s `tsc -b`, via `database/tsconfig.flows.json`'s
+ * flows-directory TypeScript include (built in the `db:generate` -> `build`
+ * chain; the root `tsconfig.json` project-references
+ * `database/tsconfig.build.json`, not `database/tsconfig.json`, so
+ * `tsconfig.flows.json` is what actually puts `flows/presets.ts` on the
+ * whole-monorepo `tsc -b` graph). `database/tsconfig.json`'s own matching
+ * include entry (added alongside) serves a SEPARATE consumer —
+ * `eslint.config.ts`'s typed-lint project discovery, so this file isn't an
+ * unlinted "orphan" — and is rejected here at the schema layer as a
+ * belt-and-suspenders runtime check.
+ */
+
+import { flowConfigSchema } from "@working-theory/validation";
+
+import { FLOW_PRESETS } from "../flows/presets";
+
+describe("FLOW_PRESETS", () => {
+  it("declares exactly the four static presets, by slug", () => {
+    expect(FLOW_PRESETS.map((p) => p.slug).sort()).toEqual([
+      "form",
+      "lead-magnet",
+      "roadmap",
+      "waitlist",
+    ]);
+  });
+
+  it.each(["form", "waitlist", "lead-magnet", "roadmap"])(
+    "the %s preset validates against flowConfigSchema",
+    (slug) => {
+      const preset = FLOW_PRESETS.find((p) => p.slug === slug);
+      expect(preset?.slug).toBe(slug);
+
+      const parsed = flowConfigSchema.safeParse(preset);
+      expect(parsed.success).toBe(true);
+    },
+  );
+
+  it("every preset declares defaultLocale: en with a key present on every LocalizedString", () => {
+    for (const preset of FLOW_PRESETS) {
+      expect(preset.defaultLocale).toBe("en");
+      // A parse failure here means some LocalizedString is missing the
+      // defaultLocale key (flowConfigSchema's superRefine) — re-assert with
+      // full issue detail for a failing preset's diagnosis.
+      const parsed = flowConfigSchema.safeParse(preset);
+      if (!parsed.success) {
+        throw new Error(
+          `${preset.slug} failed validation: ${JSON.stringify(parsed.error.issues, null, 2)}`,
+        );
+      }
+    }
+  });
+
+  it("the lead-magnet preset's qualifier step carries no segments band map (spec §7 item 4)", () => {
+    const preset = FLOW_PRESETS.find((p) => p.slug === "lead-magnet");
+    const qualifier = preset?.steps.find((s) => s.key === "qualifier");
+    expect(qualifier?.type).toBe("segmentation");
+    if (qualifier?.type === "segmentation") {
+      expect(qualifier.segments).toBeUndefined();
+    }
+  });
+
+  it("every preset declares exactly one field mapped to mapsTo: email — some steps collapse name+email into one 'contact' step, roadmap splits them (spec #3963 D2)", () => {
+    for (const preset of FLOW_PRESETS) {
+      const emailFields = preset.steps.flatMap((step) =>
+        step.type === "field"
+          ? step.fields.filter((f) => f.mapsTo === "email")
+          : [],
+      );
+      expect(emailFields).toHaveLength(1);
+      expect(emailFields[0]?.name).toBe("email");
+    }
+  });
+
+  it("no field step in any preset declares copy.cta — the FlowStepper default fallback (#4708) is what renders their submit control", () => {
+    // #4708's drift guard, the other half of which is
+    // packages/ui/src/sections/__tests__/FlowStepper.test.tsx's
+    // `roadmapShapedConfig()` / `noCtaConfig()` — packages/ui cannot import
+    // FLOW_PRESETS directly (database/flows is not a workspace package and
+    // packages/ui declares no dependency on it — a first-time cross-tier
+    // import architecture.yaml's boundary lint would refuse), so this
+    // in-package assertion is the closest mechanical proof that the shape
+    // the UI-side mirror configs cover is the shape these real presets
+    // actually carry. If a preset ever gains an explicit cta, this
+    // assertion needs updating — re-check the UI-side mirror still matches.
+    for (const preset of FLOW_PRESETS) {
+      for (const step of preset.steps) {
+        if (step.type !== "field") continue;
+        expect(step.copy.cta).toBeUndefined();
+      }
+    }
+  });
+
+  it("rejects a preset carrying a bare-string title instead of a LocalizedString", () => {
+    const mutated = {
+      ...FLOW_PRESETS[0],
+      steps: [
+        {
+          ...FLOW_PRESETS[0]!.steps[0]!,
+          copy: { ...FLOW_PRESETS[0]!.steps[0]!.copy, title: "Get in touch" },
+        },
+        ...FLOW_PRESETS[0]!.steps.slice(1),
+      ],
+    };
+
+    const parsed = flowConfigSchema.safeParse(mutated);
+    expect(parsed.success).toBe(false);
+  });
+});
+
+// ─── FLOW_PRESETS — roadmap preset (#3963 D2) ────────────────────────────────
+
+describe("roadmap preset (#3963 D2)", () => {
+  const preset = FLOW_PRESETS.find((p) => p.slug === "roadmap");
+
+  it("exists and validates against flowConfigSchema", () => {
+    expect(preset?.slug).toBe("roadmap");
+    expect(flowConfigSchema.safeParse(preset).success).toBe(true);
+  });
+
+  it("declares a two-band segments map on its segmentation step", () => {
+    const stage = preset?.steps.find((s) => s.key === "stage");
+    expect(stage?.type).toBe("segmentation");
+    if (stage?.type === "segmentation") {
+      expect(stage.segments?.bands.map((b) => b.key).sort()).toEqual([
+        "early",
+        "scaling",
+      ]);
+    }
+  });
+
+  it("maps each band to a distinct thankYou slug (AC2 — two different segmentation answers derive different TY slugs)", () => {
+    expect(preset?.thankYou?.default).toBe("roadmap-thanks");
+    expect(preset?.thankYou?.bySegment).toEqual({
+      early: "roadmap-thanks",
+      scaling: "roadmap-thanks-qualified",
+    });
+    // The "scaling" (qualified) arm resolves to a DIFFERENT TY page than the
+    // "early" arm and the default — the divergence the AC requires.
+    expect(preset?.thankYou?.bySegment?.scaling).not.toBe(
+      preset?.thankYou?.default,
+    );
+  });
+
+  it("maps each band to a distinct deliverables assetKey (AC2 — different asset grants)", () => {
+    const assets = preset?.deliverables?.assets ?? [];
+    const early = assets.find((a) => a.segment === "early");
+    const scaling = assets.find((a) => a.segment === "scaling");
+    expect(early?.assetKey).toBe("roadmap-early");
+    expect(scaling?.assetKey).toBe("roadmap-scaling");
+    expect(early?.assetKey).not.toBe(scaling?.assetKey);
+  });
+
+  it("declares abandonEmail authored but dark (#3962 D2 — shipped off, no send)", () => {
+    expect(preset?.abandonEmail?.mode).toBe("dark");
+    expect(preset?.abandonEmail?.delayMinutes).toBeGreaterThanOrEqual(5);
+  });
+
+  it("collects no phone/address fields (the acquisition-capture's §5 over-collection is deliberately not reproduced)", () => {
+    const fieldNames = (preset?.steps ?? []).flatMap((step) =>
+      step.type === "field" ? step.fields.map((f) => f.name) : [],
+    );
+    expect(fieldNames).not.toContain("phone");
+    expect(fieldNames).not.toContain("address");
+  });
+});