@cat-factory/app 0.213.1 → 0.214.0

package/app/utils/reproduction.ts

@@ -0,0 +1,51 @@
+import type { ReproductionStatus } from '~/types/reproduction'
+
+// Presentation for the BUGFIX REPRODUCTION PROOF verdict.
+//
+// The lookup is by a wire value, so it lives here as an EXHAUSTIVE `Record` keyed off the
+// contracts union rather than as a t() call over a key assembled at the call site. The typed-key
+// check cannot see a runtime-assembled key, so a fourth verdict added to the union would ship as a
+// blank chip on exactly the surface whose job is to say what was and was not proven; keyed this
+// way it fails to compile until the copy exists.
+
+export interface ReproductionStatusPresentation {
+  /** Short chip copy: the verdict as one or two words. */
+  chip: string
+  /** One sentence a reviewer decides on. */
+  verdict: string
+  icon: string
+  /** Whether this verdict IS proof — the only one a collapsed row states completely. */
+  proven: boolean
+}
+
+export const REPRODUCTION_STATUS_KEYS: Record<ReproductionStatus, ReproductionStatusPresentation> =
+  {
+    reproduced: {
+      chip: 'panels.stepDetail.reproduction.status.reproduced',
+      verdict: 'panels.stepDetail.reproduction.verdict.reproduced',
+      icon: 'i-lucide-bug-off',
+      proven: true,
+    },
+    inconclusive: {
+      chip: 'panels.stepDetail.reproduction.status.inconclusive',
+      verdict: 'panels.stepDetail.reproduction.verdict.inconclusive',
+      icon: 'i-lucide-bug',
+      proven: false,
+    },
+    declared_infeasible: {
+      chip: 'panels.stepDetail.reproduction.status.declared_infeasible',
+      verdict: 'panels.stepDetail.reproduction.verdict.declared_infeasible',
+      icon: 'i-lucide-clipboard-list',
+      proven: false,
+    },
+  }
+
+/**
+ * The two checkouts the same command was run against. A literal pair rather than a lookup: it is
+ * the feature's own vocabulary (the tree BEFORE the change and the tree after it), not a wire
+ * union that can grow.
+ */
+export const REPRODUCTION_TREE_KEYS = {
+  base: 'panels.stepDetail.reproduction.tree.base',
+  final: 'panels.stepDetail.reproduction.tree.final',
+} as const

package/app/utils/tutorial.spec.ts

@@ -1,10 +1,15 @@
 import { describe, expect, it } from 'vitest'
 import en from '../../i18n/locales/en.json'
 import {
+  boardStateFingerprint,
   computeCoachMarkLayout,
   isLaunchOffer,
   launchActionFor,
   needsReveal,
+  newlyAvailableTour,
+  nextTourAfter,
+  readyTourIds,
+  resolveNudge,
   resolveTourCatalogue,
   resolveTours,
   sortTours,
@@ -162,6 +167,256 @@ describe('resolveTourCatalogue', () => {
   })
 })
 
+describe('nextTourAfter', () => {
+  const ready = (...ids: string[]) => ids.map((id, index) => tour(id, (index + 1) * 10))
+  const none = () => false
+
+  it('offers the next unfinished tour after the one just completed', () => {
+    const next = nextTourAfter(ready('a', 'b', 'c'), { justFinishedId: 'a', isCompleted: none })
+    expect(next?.id).toBe('b')
+  })
+
+  it('never offers the tour just finished, even before it is recorded as complete', () => {
+    // The handoff renders on the finish card, BEFORE Done writes the completion, so
+    // `isCompleted` still says no about the tour the user is looking at.
+    const next = nextTourAfter(ready('a', 'b'), { justFinishedId: 'b', isCompleted: none })
+    expect(next?.id).toBe('a')
+  })
+
+  it('skips tours already completed', () => {
+    const next = nextTourAfter(ready('a', 'b', 'c'), {
+      justFinishedId: 'a',
+      isCompleted: (id) => id === 'b',
+    })
+    expect(next?.id).toBe('c')
+  })
+
+  it('prefers the launch-offer arc over a lower-ordered catalogue-only tour', () => {
+    // The rule ordering alone would get wrong. A deployment's reference tour at order 1 must
+    // not cut into the delivery loop, which is the chain the handoff exists to keep moving.
+    const shelf = { ...tour('shelf', 1), offeredAtLaunch: false as const }
+    const next = nextTourAfter([shelf, tour('loop', 50)], {
+      justFinishedId: 'x',
+      isCompleted: none,
+    })
+    expect(next?.id).toBe('loop')
+  })
+
+  it('falls back to a catalogue-only tour once the arc is exhausted', () => {
+    // Finishing the delivery loop is exactly when the platform half becomes the right thing
+    // to point at, so the preference is an ordering, not a filter.
+    const shelf = { ...tour('shelf', 60), offeredAtLaunch: false as const }
+    const next = nextTourAfter([shelf, tour('loop', 10)], {
+      justFinishedId: 'loop',
+      isCompleted: none,
+    })
+    expect(next?.id).toBe('shelf')
+  })
+
+  it('offers nothing when every other tour is done', () => {
+    // Absence is a legitimate answer here, unlike in the catalogue: this is an offer, and the
+    // finish card keeps its plain Done.
+    expect(nextTourAfter(ready('a', 'b'), { justFinishedId: 'a', isCompleted: () => true })).toBe(
+      null,
+    )
+    expect(nextTourAfter([], { justFinishedId: 'a', isCompleted: none })).toBe(null)
+  })
+})
+
+describe('newlyAvailableTour', () => {
+  const entries = (...tours: TutorialTour[]) => resolveTourCatalogue(tours, gates(true))
+  const open = { declined: false, isCompleted: () => false, wasNudged: () => false }
+
+  it('offers a tour that has just become ready', () => {
+    const catalogue = entries(withSteps('a', [step('one')]), withSteps('b', [step('one')]))
+    const offer = newlyAvailableTour({
+      catalogue,
+      previouslyReady: new Set(['a']),
+      ...open,
+    })
+    expect(offer?.id).toBe('b')
+  })
+
+  it('says nothing about a tour that was already ready', () => {
+    // The transition rule. Fired on the standing state this would greet every board load with
+    // an offer about a walkthrough that has been available for weeks.
+    const catalogue = entries(withSteps('a', [step('one')]))
+    expect(newlyAvailableTour({ catalogue, previouslyReady: new Set(['a']), ...open })).toBe(null)
+  })
+
+  it('ignores a tour that is still blocked', () => {
+    const catalogue = resolveTourCatalogue(
+      [withSteps('a', [step('one')], [needsAdvanced])],
+      gates(false),
+    )
+    expect(newlyAvailableTour({ catalogue, previouslyReady: new Set(), ...open })).toBe(null)
+  })
+
+  it('leaves the catalogue-only half alone', () => {
+    // `offeredAtLaunch: false` declares a tour as reference material someone comes and gets;
+    // interrupting them with it is the thing that declaration rules out.
+    const shelf = { ...withSteps('shelf', [step('one')]), offeredAtLaunch: false as const }
+    expect(
+      newlyAvailableTour({ catalogue: entries(shelf), previouslyReady: new Set(), ...open }),
+    ).toBe(null)
+  })
+
+  it('never re-offers a tour already offered or already completed', () => {
+    const catalogue = entries(withSteps('a', [step('one')]))
+    expect(
+      newlyAvailableTour({
+        catalogue,
+        previouslyReady: new Set(),
+        ...open,
+        wasNudged: (id) => id === 'a',
+      }),
+    ).toBe(null)
+    expect(
+      newlyAvailableTour({
+        catalogue,
+        previouslyReady: new Set(),
+        ...open,
+        isCompleted: (id) => id === 'a',
+      }),
+    ).toBe(null)
+  })
+
+  it('says nothing at all to a user who declined', () => {
+    // "No thanks" answered the question about guided tours, not about when it was asked.
+    const catalogue = entries(withSteps('a', [step('one')]))
+    expect(
+      newlyAvailableTour({ catalogue, previouslyReady: new Set(), ...open, declined: true }),
+    ).toBe(null)
+  })
+
+  it('offers the lowest-ordered tour when several become ready at once', () => {
+    const catalogue = entries(
+      { ...withSteps('later', [step('one')]), order: 50 },
+      { ...withSteps('earlier', [step('one')]), order: 20 },
+    )
+    const offer = newlyAvailableTour({ catalogue, previouslyReady: new Set(), ...open })
+    expect(offer?.id).toBe('earlier')
+  })
+})
+
+describe('boardStateFingerprint', () => {
+  /** Only the fields the fingerprint reads, plus the two it must ignore. */
+  const worldGates = (over: Partial<NavGates> = {}) =>
+    ({
+      boardHasService: true,
+      boardHasTask: true,
+      boardHasRun: true,
+      boardHasOpenDecision: false,
+      boardHasPendingApproval: false,
+      boardHasFinishedRun: false,
+      boardHasFailedRun: false,
+      githubAvailable: true,
+      canWriteBoard: true,
+      ...over,
+    }) as NavGates
+
+  it('changes when the world moves', () => {
+    expect(boardStateFingerprint(worldGates({ boardHasOpenDecision: true }))).not.toBe(
+      boardStateFingerprint(worldGates()),
+    )
+  })
+
+  it('does NOT change when a permission or a capability resolves', () => {
+    // The distinction the contextual offer turns on. A run parking is something that HAPPENED; a
+    // probe answering is the app finding out about itself, and only the first is a moment to
+    // interrupt someone about. Every gate here loads asynchronously, so without this the app's own
+    // startup is indistinguishable from the user having done something.
+    expect(
+      boardStateFingerprint(worldGates({ githubAvailable: false, canWriteBoard: false })),
+    ).toBe(boardStateFingerprint(worldGates()))
+  })
+})
+
+describe('resolveNudge', () => {
+  const entries = (...tours: TutorialTour[]) => resolveTourCatalogue(tours, gates(true))
+  const open = { declined: false, isCompleted: () => false, wasNudged: () => false }
+  const catalogue = entries(withSteps('a', [step('one')]), withSteps('b', [step('one')]))
+  const AFTER = 'world-moved'
+  const held = (...ids: string[]) => ({ ready: new Set(ids), boardState: 'world-before' })
+
+  it('seeds nothing and offers nothing before the board is up', () => {
+    // Every gate reads a store something fills asynchronously, so BEFORE the snapshot lands
+    // nothing is ready — and a baseline taken then makes the app's own startup a transition.
+    expect(
+      resolveNudge({ boardReady: false, catalogue, boardState: AFTER, previous: null, ...open }),
+    ).toEqual({ baseline: null, offer: null })
+  })
+
+  it('seeds the standing state on the first resolution once the board is up, silently', () => {
+    const { baseline, offer } = resolveNudge({
+      boardReady: true,
+      catalogue,
+      boardState: AFTER,
+      previous: null,
+      ...open,
+    })
+    expect([...(baseline?.ready ?? [])]).toEqual(['a', 'b'])
+    expect(baseline?.boardState).toBe(AFTER)
+    expect(offer).toBeNull()
+  })
+
+  it('offers what crossed into ready when the world also moved', () => {
+    const { baseline, offer } = resolveNudge({
+      boardReady: true,
+      catalogue,
+      boardState: AFTER,
+      previous: held('a'),
+      ...open,
+    })
+    expect(offer?.id).toBe('b')
+    // Advanced even though it produced an offer, so a tour flickering ready → blocked → ready
+    // (which live run gates do) cannot re-offer itself.
+    expect([...(baseline?.ready ?? [])]).toEqual(['a', 'b'])
+  })
+
+  it('says NOTHING when readiness widened but the world did not move', () => {
+    // The failure this guard exists for, and the general form of it: a permission resolving or a
+    // capability probe answering makes tours takeable that were only "blocked" because the app had
+    // not found out yet. Offered there, the mechanism greets every board load — which is the thing
+    // it was built to replace. The baseline still advances, so the widening is absorbed silently.
+    const { baseline, offer } = resolveNudge({
+      boardReady: true,
+      catalogue,
+      boardState: 'world-before',
+      previous: held('a'),
+      ...open,
+    })
+    expect(offer).toBeNull()
+    expect([...(baseline?.ready ?? [])]).toEqual(['a', 'b'])
+  })
+
+  it('DISCARDS the baseline when the board goes away, so the next one re-seeds', () => {
+    // A board switch re-inits the workspace store, and the incoming board legitimately satisfies a
+    // different set of tours. Carrying the old baseline across would report every one of them as
+    // having just become takeable.
+    expect(
+      resolveNudge({
+        boardReady: false,
+        catalogue,
+        boardState: AFTER,
+        previous: held('a'),
+        ...open,
+      }).baseline,
+    ).toBeNull()
+  })
+})
+
+describe('readyTourIds', () => {
+  it('is exactly the ids resolveTours would return', () => {
+    const tours = [
+      withSteps('ready', [step('one')]),
+      withSteps('blocked', [step('one')], [needsAdvanced]),
+    ]
+    const catalogue = resolveTourCatalogue(tours, gates(false))
+    expect([...readyTourIds(catalogue)]).toEqual(resolveTours(tours, gates(false)).map((t) => t.id))
+  })
+})
+
 describe('tourState / launchActionFor', () => {
   const state = (over: Partial<Parameters<typeof tourState>[0]>) =>
     tourState({ active: false, resumable: false, completed: false, ...over })

package/app/utils/tutorial.ts

@@ -286,6 +286,179 @@ export function isLaunchOffer(tour: TutorialTour): boolean {
   return tour.offeredAtLaunch !== false
 }
 
+/** The ids a catalogue resolution says can be started right now. */
+export function readyTourIds(catalogue: readonly TutorialCatalogueEntry[]): Set<string> {
+  return new Set(
+    catalogue.filter((entry) => entry.availability === 'ready').map((entry) => entry.tour.id),
+  )
+}
+
+/**
+ * The tour that just became takeable, for the contextual offer, or null when nothing did.
+ *
+ * The catalogue made every walkthrough reachable; this is what reaches the user who needs one
+ * WITHOUT going looking. The trigger is deliberately not a per-surface hook ("when a run parks,
+ * mention `answer-park`"): every tour already declares, as its `requires`, the exact predicate
+ * that means "you can take this now". So one rule over the resolved catalogue covers the whole
+ * catalog and inherits `navRequirementDrift` unchanged, where a hand-wired trigger per surface
+ * would be a second copy of each requirement to keep in step.
+ *
+ * Three rules, and the first is the one that is easy to get wrong:
+ *
+ *  - It fires on a TRANSITION into `ready`, never on the standing state, which is why the caller
+ *    must SEED `previouslyReady` from a resolution taken once the board is up AND may only offer
+ *    where the world itself moved (see {@link resolveNudge}, which owns both halves). Fired on
+ *    the standing state it would nudge about everything already available on every board load,
+ *    which is the launch prompt with none of its manners. The transition rule also means the
+ *    permission-gated platform tours (ready from the first render on any board) naturally never
+ *    reach it, and only the board-state tours — a run parked, a run failed, a PR ready to
+ *    merge — can.
+ *  - Only the launch-offer arc, for the reason `offeredAtLaunch` exists: a tour declared as
+ *    reference material someone comes and gets is not one to interrupt them with. Reusing that
+ *    declaration rather than inventing a second opt-out keeps a consumer deployment's tour
+ *    behaving here exactly as it does in the prompt.
+ *  - Never twice for the same tour (`wasNudged`) and never one already completed. A contextual
+ *    offer that returns is a nag, and this one is unusually well placed to become one: the gates
+ *    it reads flip several times per run.
+ *
+ * And nothing at all for a user who DECLINED. "No thanks" was an answer about guided tours, not
+ * about the startup timing of the question, so a mechanism that goes on offering them anyway is
+ * overriding the one explicit preference this feature collects. They keep the catalogue, which is
+ * where someone who changed their mind goes; `resetProgress` is the way back to being asked.
+ */
+export function newlyAvailableTour(input: {
+  catalogue: readonly TutorialCatalogueEntry[]
+  previouslyReady: ReadonlySet<string>
+  declined: boolean
+  isCompleted: (tourId: string) => boolean
+  wasNudged: (tourId: string) => boolean
+}): TutorialTour | null {
+  if (input.declined) return null
+  const candidate = input.catalogue.find(
+    (entry) =>
+      entry.availability === 'ready' &&
+      isLaunchOffer(entry.tour) &&
+      !input.previouslyReady.has(entry.tour.id) &&
+      !input.isCompleted(entry.tour.id) &&
+      !input.wasNudged(entry.tour.id),
+  )
+  return candidate?.tour ?? null
+}
+
+/**
+ * The gates that describe the WORLD: facts about this board that a person or a run changed.
+ *
+ * Everything else `NavGates` carries is a fact about the DEPLOYMENT or the VIEWER (a permission, a
+ * wired integration, the interface tier), and the difference is what {@link resolveNudge} turns on.
+ */
+const BOARD_STATE_GATES = [
+  'boardHasService',
+  'boardHasTask',
+  'boardHasRun',
+  'boardHasOpenDecision',
+  'boardHasPendingApproval',
+  'boardHasFinishedRun',
+  'boardHasFailedRun',
+] as const satisfies readonly (keyof NavGates)[]
+
+/**
+ * A comparable stamp of the board-state gates, so "did the world move" is one `!==`.
+ *
+ * A string of bits rather than a Set of what is true: the question is only whether this differs
+ * from the last look, and a stamp makes that answerable without caring which bit moved.
+ */
+export function boardStateFingerprint(gates: NavGates): string {
+  return BOARD_STATE_GATES.map((gate) => (gates[gate] ? '1' : '0')).join('')
+}
+
+/**
+ * One step of the contextual offer's state machine: the baseline to carry forward, and the tour
+ * to offer (if any) from this resolution of the catalogue.
+ *
+ * Pure, and separate from {@link newlyAvailableTour}, because the BASELINE is the part that was
+ * wrong when this shipped and the part a reactive wrapper cannot be trusted with. A transition
+ * rule is only as good as what it is measured against, and this one was measured against an app
+ * that had not finished starting: every gate reads a store something fills asynchronously, so a
+ * baseline taken too early records "nothing is takeable" and the app's own startup then reads as a
+ * transition. That turns the mechanism into exactly the every-board-load greeting it exists to
+ * prevent ("here is a new walkthrough", about a run that finished a fortnight ago).
+ *
+ * Two guards, because the first alone was not enough and the second is the general form of why:
+ *
+ *  - `boardReady` gates any baseline at all on the workspace snapshot having been fanned out, so
+ *    board state is in place before anything is recorded as the standing state. It also DISCARDS
+ *    the baseline when the board goes away, so switching boards re-seeds against the new one
+ *    rather than reporting everything it happens to satisfy as having just changed.
+ *  - `boardState` (a {@link boardStateFingerprint}) is what an offer actually requires to have
+ *    MOVED. Readiness widening is not the same as the world changing: a permission resolving, or
+ *    a capability probe answering, makes tours takeable that were "blocked" only because the app
+ *    did not know yet, and the app finding out about itself is not a moment to interrupt anyone
+ *    about. Those resolutions advance the baseline SILENTLY. This is the guard that generalises:
+ *    it needs no list of which stores load late, because none of them describe the world.
+ *
+ * So an offer needs both halves — a tour that just became takeable, and a world that just moved —
+ * and the baseline advances on every resolution either way, so a tour flickering
+ * ready → blocked → ready (which live run gates do) cannot re-offer itself.
+ */
+export function resolveNudge(input: {
+  boardReady: boolean
+  catalogue: readonly TutorialCatalogueEntry[]
+  boardState: string
+  previous: { ready: ReadonlySet<string>; boardState: string } | null
+  declined: boolean
+  isCompleted: (tourId: string) => boolean
+  wasNudged: (tourId: string) => boolean
+}): { baseline: { ready: Set<string>; boardState: string } | null; offer: TutorialTour | null } {
+  if (!input.boardReady) return { baseline: null, offer: null }
+  const baseline = { ready: readyTourIds(input.catalogue), boardState: input.boardState }
+  if (input.previous === null) return { baseline, offer: null }
+  if (input.previous.boardState === input.boardState) return { baseline, offer: null }
+  return {
+    baseline,
+    offer: newlyAvailableTour({ ...input, previouslyReady: input.previous.ready }),
+  }
+}
+
+/**
+ * The tour to hand the user off to when they finish `justFinishedId`, or null when there is
+ * nothing left to offer.
+ *
+ * The catalog is a COURSE, not a list: each delivery-loop tour produces the state the next
+ * one requires, so finishing one is the single most reliable moment at which another became
+ * takeable. Without a handoff the walkthrough that the user's own last action unlocked is
+ * reachable only from the catalogue, and the launch prompt cannot bring it up either: starting
+ * any tour writes `decision: 'accepted'`, which is what stops the prompt auto-opening for good.
+ * So the finish card is the ONLY place the product can still say "and now this one".
+ *
+ * Two rules make it an offer rather than a list:
+ *
+ *  - Launch-offer tours come FIRST, whatever their `order` (see {@link TutorialTour.offeredAtLaunch}).
+ *    The delivery loop is the arc someone taking a tour is on; a deployment's catalogue-only
+ *    tour with a low `order` must not jump in front of it. Ordering alone is not that
+ *    guarantee — it only happens to be true of the built-ins' numbering.
+ *  - It offers exactly one, and only a READY one. A list is what the catalogue is for, and a
+ *    blocked tour named here would ask the user to go and do something at the moment they
+ *    finished doing something.
+ *
+ * Absence is a legitimate answer, unlike in the catalogue: this is an offer, so having nothing
+ * to suggest means the card keeps its plain Done. The caller still shows the way to the
+ * catalogue, so the card never dead-ends.
+ *
+ * `ready` is deliberately read LIVE by the caller rather than from the tour's held script,
+ * which is the one place the "resolve once and HOLD" rule must not apply: completing
+ * `first-task` is exactly what makes `run-task` ready, so a candidate list frozen at tour
+ * start would be empty precisely when this exists to be useful.
+ */
+export function nextTourAfter(
+  ready: readonly TutorialTour[],
+  input: { justFinishedId: string; isCompleted: (tourId: string) => boolean },
+): TutorialTour | null {
+  const fresh = sortTours(ready).filter(
+    (tour) => tour.id !== input.justFinishedId && !input.isCompleted(tour.id),
+  )
+  return fresh.find(isLaunchOffer) ?? fresh[0] ?? null
+}
+
 /**
  * Where a tour stands for this user: the state the catalogue badges and the action label
  * derive from. Camel-cased because the values ARE the i18n leaf keys