@cat-factory/app 0.201.1 → 0.204.0

package/app/stores/tutorial.ts

@@ -16,7 +16,7 @@ export type TutorialDecision = 'accepted' | 'declined'
  *    is a real state distinct from `declined` — only an explicit answer stops the launch
  *    prompt from returning, while closing it without answering merely defers it to the
  *    next launch.
- *  - SESSION-ONLY (`promptOpen`, `activeTourId`, `stepIndex`) — a tour is anchored to live
+ *  - SESSION-ONLY (`promptOpen`, `catalogueOpen`, `activeTourId`, `stepIndex`) — a tour is anchored to live
  *    DOM, so replaying progress across a reload would point step N at a board that hasn't
  *    reached that state; a reloaded tour restarts from its beginning instead.
  *
@@ -36,12 +36,47 @@ export const useTutorialStore = defineStore(
     const promptOpen = ref(false)
     /** Once-per-session guard for the launch auto-open; later opens are user-driven. */
     const promptAutoOpened = ref(false)
+    /**
+     * The tutorial catalogue (every tour this deployment ships, startable at any time) is
+     * open. Always user-driven — nothing auto-opens it — which is why it carries none of the
+     * prompt's decision machinery: browsing the catalogue answers no question, so it neither
+     * writes a decision nor consumes the launch offer.
+     */
+    const catalogueOpen = ref(false)
     const activeTourId = ref<string | null>(null)
     const stepIndex = ref(0)
+    /**
+     * Where a tour the user broke off was left, so the prompt can offer to RESUME it rather
+     * than only to start it again from step one.
+     *
+     * Session-only for the same reason the cursor is: a tour is anchored to live DOM, and a
+     * position replayed across a reload would point step N at a board that has not reached
+     * that state. Within one session the board is still exactly where the tour left it, so the
+     * position is good — which matters because breaking off is easy and cheap (Esc, or Skip to
+     * get the overlay out of the way for a moment) while the cost of it was the whole
+     * walkthrough.
+     */
+    const interrupted = ref<{ tourId: string; stepIndex: number } | null>(null)
 
     /** A tour is currently running (the overlay mounts off this). */
     const touring = computed(() => activeTourId.value !== null)
 
+    /**
+     * A window this feature owns — the launch prompt or the catalogue — is on screen.
+     *
+     * The coach-mark overlay STANDS DOWN while it is (see `TutorialOverlay.vue`). The marks
+     * render at `z-[70]`, deliberately above the app's own modals, because a tour step
+     * legitimately points INTO one; no step points into the tutorial's own windows, so there
+     * the same rule floats a highlight ring and a tooltip over the modal the user just opened.
+     * The catalogue reaches this state by design — it is openable mid-tour, which is what the
+     * `continue` launch action exists for.
+     *
+     * A derived FACT rather than a `coachMarksHidden` flag, because the reason is the window,
+     * not the overlay: a third tutorial-owned window inherits the behaviour by being named
+     * here, and nothing has to remember to set a flag.
+     */
+    const ownWindowOpen = computed(() => promptOpen.value || catalogueOpen.value)
+
     /**
      * Auto-open the launch prompt, at most once per session and only while the user has
      * never answered it. Callers gate on the rest of the launch context (board ready, no
@@ -79,6 +114,21 @@ export const useTutorialStore = defineStore(
       promptOpen.value = false
     }
 
+    /**
+     * Open the catalogue. Closes the launch prompt WITHOUT answering it: browsing the full
+     * list is not "no thanks" (it is the opposite), and the two are modals that would
+     * otherwise stack — so the offer returns next launch if the user browses and starts
+     * nothing.
+     */
+    function openCatalogue() {
+      promptOpen.value = false
+      catalogueOpen.value = true
+    }
+
+    function closeCatalogue() {
+      catalogueOpen.value = false
+    }
+
     /** The explicit "no thanks": saved, so the launch prompt never auto-opens again. */
     function decline() {
       decision.value = 'declined'
@@ -93,8 +143,40 @@ export const useTutorialStore = defineStore(
     function startTour(tourId: string) {
       decision.value = 'accepted'
       promptOpen.value = false
+      catalogueOpen.value = false
       activeTourId.value = tourId
       stepIndex.value = 0
+      // Starting from the top is an explicit choice to discard THIS tour's old position;
+      // leaving the record in place would offer Resume again the moment this attempt is
+      // broken off at step 0, pointing at a position the user already walked away from.
+      //
+      // A DIFFERENT tour's position is not this action's to discard. It is still exactly what
+      // its own Resume offer needs, and it will lose the single slot soon enough — the moment
+      // this tour is broken off past step 0. Clearing it here instead means glancing at
+      // another tour and pressing Esc silently costs the position you were coming back to.
+      if (interrupted.value?.tourId === tourId) interrupted.value = null
+    }
+
+    /**
+     * Pick a broken-off tour back up where it stopped. Falls back to a plain start when the
+     * saved position is for a DIFFERENT tour (or gone), so a caller never has to check first
+     * and a stale offer degrades to the ordinary behaviour instead of resuming the wrong tour.
+     *
+     * The index is not validated here: the store deliberately knows nothing about which tours
+     * exist or how many steps they have, so the overlay clamps it against the script it holds.
+     */
+    function resumeTour(tourId: string) {
+      const at = interrupted.value
+      if (!at || at.tourId !== tourId) {
+        startTour(tourId)
+        return
+      }
+      decision.value = 'accepted'
+      promptOpen.value = false
+      catalogueOpen.value = false
+      activeTourId.value = tourId
+      stepIndex.value = at.stepIndex
+      interrupted.value = null
     }
 
     /** Move the step cursor; the overlay owns bounds/skip logic and never goes below 0. */
@@ -102,43 +184,97 @@ export const useTutorialStore = defineStore(
       stepIndex.value = Math.max(0, index)
     }
 
-    /** Abandon the running tour without marking it complete (the Skip action). */
-    function stopTour() {
+    /** Clear the live cursor. Shared by the two ways a tour ends, which differ only in what
+     * they leave behind (a resume point vs. a completion). */
+    function clearCursor() {
       activeTourId.value = null
       stepIndex.value = 0
     }
 
+    /**
+     * Abandon the running tour without marking it complete: Skip, Esc, or a runtime that
+     * could not resolve the tour at all.
+     *
+     * Records where it stopped so the prompt can offer to resume — except from the very first
+     * step, where resuming and starting are the same thing and an offer to "resume" would be
+     * noise. `resumable: false` is for the runtime's own bail-outs, which stop BECAUSE the
+     * position is unusable and must not hand it back.
+     */
+    function stopTour(options?: { resumable?: boolean }) {
+      const id = activeTourId.value
+      if (id !== null && stepIndex.value > 0 && options?.resumable !== false) {
+        interrupted.value = { tourId: id, stepIndex: stepIndex.value }
+      }
+      clearCursor()
+    }
+
     /** Finish the running tour: record completion (idempotent) and clear the cursor. */
     function completeTour() {
       const id = activeTourId.value
       if (id && !completedTourIds.value.includes(id)) {
         completedTourIds.value = [...completedTourIds.value, id]
       }
-      stopTour()
+      // A finished tour has no position left to resume, and an offer to resume the walkthrough
+      // the user just completed would sit beside its own Completed badge.
+      if (id !== null && interrupted.value?.tourId === id) interrupted.value = null
+      clearCursor()
+    }
+
+    /** Where this tour was broken off, if it was; null otherwise (the Resume affordance). */
+    function interruptedAt(tourId: string): number | null {
+      return interrupted.value?.tourId === tourId ? interrupted.value.stepIndex : null
     }
 
     function isCompleted(tourId: string): boolean {
       return completedTourIds.value.includes(tourId)
     }
 
+    /**
+     * Forget everything this browser remembers about the tutorial: which tours were finished,
+     * where one was broken off, and the answer to the launch offer.
+     *
+     * The decision goes with it deliberately. "Reset" is asked for by someone handing the app
+     * to a colleague, demoing it, or re-walking the product after it changed — and every one
+     * of those wants the first-launch experience back, which a cleared completion list alone
+     * does not restore. It does NOT re-open the prompt in this session: `promptAutoOpened` is
+     * session state and stays spent, so the offer returns at the next launch rather than
+     * appearing on top of the catalogue the user is still reading.
+     *
+     * A running tour is left alone: this clears a record, it does not interrupt a walkthrough
+     * the user is in the middle of (which would end it, unrecorded, on a click about history).
+     */
+    function resetProgress() {
+      completedTourIds.value = []
+      interrupted.value = null
+      decision.value = null
+    }
+
     return {
       decision,
       completedTourIds,
       promptOpen,
       promptAutoOpened,
+      catalogueOpen,
       activeTourId,
       stepIndex,
+      interrupted,
       touring,
+      ownWindowOpen,
       maybeOfferOnLaunch,
       openPrompt,
       closePrompt,
       deferPrompt,
+      openCatalogue,
+      closeCatalogue,
+      resetProgress,
       decline,
       startTour,
+      resumeTour,
       setStepIndex,
       stopTour,
       completeTour,
       isCompleted,
+      interruptedAt,
     }
   },
   { persist: { pick: ['decision', 'completedTourIds'] } },

package/app/types/domain.ts

@@ -131,6 +131,15 @@ export interface AgentArchetype {
    * hardcoding a kind. Absent → the generic `AgentStepDetail` panel.
    */
   resultView?: string
+  /**
+   * The kind carries the `binary-output` trait: its deliverable is binary artifacts stored
+   * through a foundational service, so a step of this kind REQUIRES a `stepOptions.binaryOutput`
+   * selection and is refused at pipeline save and at run start without one. Projected onto the
+   * snapshot as `CustomAgentKind.binaryOutput` — the only trait with a UI consequence, and the
+   * only way the builder can know which steps must offer the storage picker. Absent ⇒ false,
+   * which is every built-in kind.
+   */
+  binaryOutput?: boolean
 }
 
 /**

package/app/types/execution.ts

@@ -77,6 +77,11 @@ export type {
   RalphStepState,
   RalphAttempt,
   RalphVerdict,
+  // The binary-output trio: the step's SELECTION (`stepOptions.binaryOutput`), the report the
+  // engine parsed off the agent's declaration (`step.binaryOutputs`), and one declared artifact.
+  BinaryOutputArtifact,
+  BinaryOutputConfig,
+  BinaryOutputReport,
   TesterStepState,
   HumanTestEnvironment,
   RunEnvironment,

package/app/utils/binaryOutput.spec.ts

@@ -0,0 +1,307 @@
+import { describe, expect, it } from 'vitest'
+import type { BinaryOutputReport, PipelineStep } from '~/types/execution'
+import {
+  BINARY_OUTPUT_STATE_KEYS,
+  binaryOutputHasWarnings,
+  binaryOutputPickIssues,
+  binaryOutputView,
+} from './binaryOutput'
+
+function step(patch: Partial<PipelineStep>): PipelineStep {
+  return { agentKind: 'image-maker', state: 'done', ...patch } as PipelineStep
+}
+
+function report(patch: Partial<BinaryOutputReport> = {}): BinaryOutputReport {
+  return { stored: [], unknownServices: [], invalidEntries: 0, omitted: 0, ...patch }
+}
+
+const artifact = (service: string, location: string) => ({ service, location })
+
+describe('binaryOutputView', () => {
+  // The regression this whole surface exists to prevent: five of the six outcomes are NOT
+  // "an empty list", so each must resolve to its own state (and, through the shared key map,
+  // its own copy). Collapsing any pair reports a run that stored nothing and a run whose
+  // declaration was unreadable as the same thing.
+  it('keeps the six outcomes apart', () => {
+    const cases: [PipelineStep, string][] = [
+      [
+        step({ state: 'pending', stepOptions: { binaryOutput: { storageServiceId: 'files' } } }),
+        'not-started',
+      ],
+      [step({ stepOptions: { binaryOutput: { storageServiceId: 'files' } } }), 'configured'],
+      [step({ binaryOutputs: report({ undeclared: true }) }), 'undeclared'],
+      [step({ binaryOutputs: report({ parseFailed: true }) }), 'parse-failed'],
+      [step({ binaryOutputs: report() }), 'declared-none'],
+      [step({ binaryOutputs: report({ stored: [artifact('files', 'a/b.png')] }) }), 'stored'],
+    ]
+    for (const [input, expected] of cases) expect(binaryOutputView(input)?.state).toBe(expected)
+    // Every state has its own copy, so no two rows can read identically.
+    const summaries = Object.values(BINARY_OUTPUT_STATE_KEYS).map((k) => k.summary)
+    expect(new Set(summaries).size).toBe(summaries.length)
+  })
+
+  // Absence is the one thing that must NOT render: a step with neither a report nor a
+  // selection had no binary-output story at all, which is every step of every stock pipeline.
+  it('renders nothing for a step that was never briefed', () => {
+    expect(binaryOutputView(step({}))).toBeNull()
+    expect(binaryOutputView(null)).toBeNull()
+  })
+
+  // A queued step has not had the chance to record anything, which `configured` ("running, or it
+  // died") states as the opposite of what is true. It still renders — unlike a SKIPPED step it
+  // has a story ahead of it, and where the artifacts will land is worth saying in advance.
+  it('separates a step that has not started from one that started and recorded nothing', () => {
+    const config = { binaryOutput: { storageServiceId: 'files' } }
+    const queued = binaryOutputView(step({ state: 'pending', stepOptions: config }))
+    expect(queued?.state).toBe('not-started')
+    expect(queued?.target).toBe('files')
+    // Nothing has gone wrong yet, so the section must not open itself expanded.
+    expect(binaryOutputHasWarnings(queued!)).toBe(false)
+
+    for (const state of ['working', 'waiting_decision', 'done'] as const)
+      expect(binaryOutputView(step({ state, stepOptions: config }))?.state).toBe('configured')
+
+    // A recorded claim still wins over either, exactly as it does for a skipped step.
+    expect(
+      binaryOutputView(
+        step({
+          state: 'pending',
+          stepOptions: config,
+          binaryOutputs: report({ undeclared: true }),
+        }),
+      )?.state,
+    ).toBe('undeclared')
+  })
+
+  // A gated-out step holds a selection it never ran with, so `configured` would tell a reader it
+  // is still running or died mid-generation — both wrong, about a step already marked skipped.
+  it('renders nothing for a step skipped by estimate gating', () => {
+    expect(
+      binaryOutputView(
+        step({ skipped: true, stepOptions: { binaryOutput: { storageServiceId: 'files' } } }),
+      ),
+    ).toBeNull()
+    // A recorded claim is never hidden, whatever else the step says about itself.
+    expect(
+      binaryOutputView(
+        step({
+          skipped: true,
+          stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+          binaryOutputs: report({ stored: [artifact('files', 'a.png')] }),
+        }),
+      )?.state,
+    ).toBe('stored')
+  })
+
+  // A parse failure implies an empty `stored`, so reading the list first would report it as
+  // "the agent said it stored nothing" — the one misreading with a completely wrong remedy.
+  it('reports an unreadable declaration as parse-failed, not as declared-none', () => {
+    const view = binaryOutputView(step({ binaryOutputs: report({ parseFailed: true }) }))
+    expect(view?.state).toBe('parse-failed')
+    expect(view?.rows).toHaveLength(0)
+  })
+
+  it('names unknown services and keeps their rows', () => {
+    const view = binaryOutputView(
+      step({
+        binaryOutputs: report({
+          stored: [artifact('files', 'a.png'), artifact('ghost', 'b.png')],
+          unknownServices: ['ghost'],
+        }),
+      }),
+    )
+    // The claim is recorded, not dropped — a reader judges it.
+    expect(view?.rows).toHaveLength(2)
+    expect(view?.unknownDeclaredServices).toEqual(['ghost'])
+    expect(view?.rows[1]?.unknown).toBe(true)
+    expect(view?.rows[0]?.unknown).toBe(false)
+  })
+
+  // The join the report cannot make alone, and the question a human actually opens this for.
+  it('marks a row stored through a service other than the configured target', () => {
+    const view = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({ stored: [artifact('files', 'a.png'), artifact('audit', 'b.png')] }),
+      }),
+    )
+    expect(view?.target).toBe('files')
+    expect(view?.rows.map((r) => r.misdirected)).toEqual([false, true])
+    expect(view?.misdirected).toBe(1)
+  })
+
+  // A step that never held a selection (a trait-carrying kind dispatched under an overriding
+  // kind) has nothing to compare against — so nothing may be reported as having gone astray.
+  it('marks nothing misdirected when the step carries no selection', () => {
+    const view = binaryOutputView(
+      step({ binaryOutputs: report({ stored: [artifact('audit', 'b.png')] }) }),
+    )
+    expect(view?.target).toBeNull()
+    expect(view?.misdirected).toBe(0)
+    expect(view?.rows[0]?.misdirected).toBe(false)
+  })
+
+  // "The catalog lost the step's own target" and "the agent named a service that never
+  // existed" are the same `unknownServices` entry with opposite fixes.
+  it('distinguishes a lost target from an invented service id', () => {
+    const lost = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({ stored: [artifact('files', 'a.png')], unknownServices: ['files'] }),
+      }),
+    )
+    expect(lost?.targetUnknown).toBe(true)
+
+    expect(lost?.unknownDeclaredServices).toEqual([])
+
+    const invented = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({ stored: [artifact('flies', 'a.png')], unknownServices: ['flies'] }),
+      }),
+    )
+    expect(invented?.targetUnknown).toBe(false)
+    expect(invented?.unknownDeclaredServices).toEqual(['flies'])
+  })
+
+  // Both at once is where sharing one field went wrong: the report's own `unknownServices` mixes
+  // the lost target with the invented ids, so a surface reading it raw named ALL of them as "this
+  // step's own storage service" and dropped the invented ones entirely. The two fields are
+  // disjoint by construction, so no renderer can restate one as the other.
+  it('keeps a lost target out of the invented-id list when both happened', () => {
+    const view = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({
+          stored: [artifact('files', 'a.png'), artifact('ghost', 'b.png')],
+          unknownServices: ['files', 'ghost', 'phantom'],
+        }),
+      }),
+    )
+    expect(view?.targetUnknown).toBe(true)
+    expect(view?.unknownDeclaredServices).toEqual(['ghost', 'phantom'])
+    expect(view?.unknownDeclaredServices).not.toContain('files')
+    expect(binaryOutputHasWarnings(view!)).toBe(true)
+  })
+
+  // A lost target with nothing else unknown is still a warning — it is the whole comparison the
+  // surface exists to make, and the list it used to be counted in is now empty.
+  it('treats a lost target alone as a warning', () => {
+    const view = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({ stored: [artifact('files', 'a.png')], unknownServices: ['files'] }),
+      }),
+    )
+    expect(view?.unknownDeclaredServices).toEqual([])
+    expect(binaryOutputHasWarnings(view!)).toBe(true)
+  })
+
+  // Without the count, a capped list reads as the whole list and its tail as nonexistent.
+  it('carries the counted losses through verbatim', () => {
+    const view = binaryOutputView(
+      step({
+        binaryOutputs: report({ stored: [artifact('files', 'a')], invalidEntries: 2, omitted: 7 }),
+      }),
+    )
+    expect(view?.invalidEntries).toBe(2)
+    expect(view?.omitted).toBe(7)
+    expect(binaryOutputHasWarnings(view!)).toBe(true)
+  })
+
+  it('treats a clean stored report as warning-free', () => {
+    const view = binaryOutputView(
+      step({
+        stepOptions: { binaryOutput: { storageServiceId: 'files' } },
+        binaryOutputs: report({ stored: [artifact('files', 'a.png')] }),
+      }),
+    )
+    expect(binaryOutputHasWarnings(view!)).toBe(false)
+  })
+})
+
+describe('binaryOutputPickIssues', () => {
+  const service = (id: string, capabilities: string[]) => ({ id, capabilities })
+  const catalog = [
+    service('files', ['asset-storage']),
+    service('inventory', ['generation-context']),
+  ]
+
+  it('accepts a selection that resolves against the catalog', () => {
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', contextServiceIds: ['inventory'] },
+      catalog,
+      true,
+    )
+    expect(pick.issues).toEqual([])
+  })
+
+  it('flags a step with no storage selection', () => {
+    expect(binaryOutputPickIssues(undefined, catalog, true).issues).toContain('not_selected')
+  })
+
+  // The two refusals run admission raises, surfaced before the round trip rather than after it.
+  it('mirrors the admission refusals for a stale or untagged storage id', () => {
+    expect(binaryOutputPickIssues({ storageServiceId: 'gone' }, catalog, true).issues).toContain(
+      'unknown_service',
+    )
+    expect(
+      binaryOutputPickIssues({ storageServiceId: 'inventory' }, catalog, true).issues,
+    ).toContain('not_storage_capable')
+  })
+
+  // "Pick another" is not a remedy when there is nothing to pick: with no storage service in the
+  // catalog at all, the per-selection judgements would print an instruction the surface cannot
+  // carry out, beside the one that is actionable. The context half is a different selection,
+  // judged on existence alone, so it stays.
+  it('suppresses the per-selection storage judgements when the catalog has no storage service', () => {
+    const contextOnly = [service('inventory', ['generation-context'])]
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'gone', contextServiceIds: ['inventory', 'vanished'] },
+      contextOnly,
+      true,
+    )
+    expect(pick.issues).toContain('no_storage_service')
+    expect(pick.issues).not.toContain('unknown_service')
+    expect(pick.issues).not.toContain('not_storage_capable')
+    expect(pick.issues).toContain('unknown_context_service')
+    expect(pick.unknownContextIds).toEqual(['vanished'])
+  })
+
+  it('names every unresolved context id, not just the first', () => {
+    const pick = binaryOutputPickIssues(
+      { storageServiceId: 'files', contextServiceIds: ['inventory', 'gone', 'also-gone'] },
+      catalog,
+      true,
+    )
+    expect(pick.issues).toContain('unknown_context_service')
+    expect(pick.unknownContextIds).toEqual(['gone', 'also-gone'])
+  })
+
+  // An empty picker reads as "no services exist", which is a claim. Not-probed-yet, unreachable
+  // and genuinely empty are three facts an empty array cannot tell apart.
+  it('separates an unreachable and an unprobed catalog from an empty one', () => {
+    expect(binaryOutputPickIssues(undefined, [], true).issues).toContain('no_storage_service')
+    expect(binaryOutputPickIssues(undefined, [], false).issues).toEqual([
+      'catalog_unavailable',
+      'not_selected',
+    ])
+    // Before the probe lands there is nothing to say about the catalog — only about the step.
+    expect(binaryOutputPickIssues(undefined, [], null).issues).toEqual(['not_selected'])
+  })
+
+  // An outage (or a load still in flight) changed nothing about the selection, so neither may
+  // flag every step for re-pick.
+  it('does not judge a selection against a catalog it has not read', () => {
+    for (const available of [false, null] as const) {
+      const pick = binaryOutputPickIssues(
+        { storageServiceId: 'files', contextServiceIds: ['inventory'] },
+        [],
+        available,
+      )
+      expect(pick.issues).not.toContain('unknown_service')
+      expect(pick.issues).not.toContain('unknown_context_service')
+      expect(pick.unknownContextIds).toEqual([])
+    }
+  })
+})