@cat-factory/app 0.145.0 → 0.146.0

package/app/modular/journeys/environmentSetup.logic.ts

@@ -10,15 +10,26 @@
  * trial) stay in that Pinia store, which the step components still drive; the
  * journey just decides WHICH step shows and threads the target frame id.
  *
- * This file is deliberately free of Vue/`.vue`/`defineModule` imports so the
- * transition graph is unit-tested directly (`environmentSetup.spec.ts`); the
- * component wiring lives in `environmentSetup.ts`, which feeds these helpers into
- * `defineJourney`'s `transitions` map.
+ * The step ORDER is no longer spelled out a second time as an ordered array: it
+ * is DERIVED from the annotated transition graph below (production-feedback item
+ * 4 in modular-react#83). Each transition wraps its handler with
+ * `defineTransition({ targets, handle })` so the static `targets` declare where
+ * the flow can go; `resolveStepSequence` / `useJourneyProgress` walk that graph
+ * to produce the ordered step list and the wizard's "Step X of N" progress from
+ * the one place the flow is encoded. `steps` carries each step's progress-label
+ * key beside the transitions.
+ *
+ * This definition lives in the logic file (not the SFC-importing
+ * `environmentSetup.ts`) so the graph stays free of `.vue` imports and is
+ * unit-tested directly (`environmentSetup.logic.spec.ts`). It references the step
+ * module only as a TYPE (`import type`), which is erased at runtime, so importing
+ * this file pulls no components. `environmentSetup.ts` supplies the module (with
+ * its step components) and re-exports the journey + the launch handle + the
+ * persistence adapter.
  */
-
-/** The journey's ordered step entries (also the module's `entryPoints` keys). */
-export const ENV_STEP_ORDER = ['pick', 'review', 'preflight', 'save'] as const
-export type EnvStep = (typeof ENV_STEP_ORDER)[number]
+import type { ExitCtx } from '@modular-vue/journeys'
+import { defineJourney, defineTransition } from '@modular-vue/journeys'
+import type { environmentSetupModule } from '~/modular/journeys/environmentSetup'
 
 /** The single module id every step entry lives under. */
 export const ENV_MODULE_ID = 'cat-factory:environment-setup' as const
@@ -52,35 +63,91 @@ export function envInitialState(input: EnvSetupInput): EnvSetupState {
 }
 
 /** First step: skip the picker when the launcher already chose a frame. */
-export function envStartStep(_state: EnvSetupState, input: EnvSetupInput): EnvStep {
+export function envStartStep(_state: EnvSetupState, input: EnvSetupInput): 'pick' | 'review' {
   return input.frameId ? 'review' : 'pick'
 }
 
 /**
- * The step reached by advancing from `from` via its forward exit, or `'done'`
- * when the flow completes. The pick step advances via `select` (a distinct
- * exit); the rest via `advance`. Pure and total over `EnvStep`.
- *
- * This is the SINGLE SOURCE OF TRUTH for the linear forward chain: the journey
- * definition (`environmentSetup.ts`) derives its `advance` transitions' target
- * entries from it, so pinning this function in `environmentSetup.logic.spec.ts`
- * genuinely guards the wired graph against a silent reorder/drop. The overloads
- * narrow the return to a concrete entry (or `'done'`) so a transition handler can
- * feed the result straight into a `StepSpec` without a widened `EnvStep | 'done'`.
+ * The journey's module type map — one module, referenced by its `typeof` so the
+ * transition + step maps resolve its literal entry/exit vocabulary with no casts.
+ * This is the case production-feedback item 3 (modular-react#83) fixed: before it,
+ * `defineModule` widened the descriptor, so `typeof environmentSetupModule` could
+ * not stand in as a `TModules` member without re-declaring the entry names by hand.
  */
-export function envNextAfter(from: 'pick'): 'review'
-export function envNextAfter(from: 'review'): 'preflight'
-export function envNextAfter(from: 'preflight'): 'save'
-export function envNextAfter(from: 'save'): 'done'
-export function envNextAfter(from: EnvStep): EnvStep | 'done' {
-  switch (from) {
-    case 'pick':
-      return 'review'
-    case 'review':
-      return 'preflight'
-    case 'preflight':
-      return 'save'
-    case 'save':
-      return 'done'
-  }
-}
+export type EnvModules = { [ENV_MODULE_ID]: typeof environmentSetupModule }
+
+/** Binder threading the journey generics into each annotated transition handler. */
+const transition = defineTransition<EnvModules, EnvSetupState>()
+
+/**
+ * The journey definition. `start` skips the picker when a frame was preselected.
+ * The forward chain is the annotated transitions' `targets`: pick →(select)→
+ * review →(advance)→ preflight →(advance)→ save →(advance)→ complete. Back
+ * navigation is handled by the entries' `allowBack` (declared on the module in
+ * `environmentSetup.ts`), not explicit transitions.
+ */
+export const environmentSetupJourney = defineJourney<EnvModules, EnvSetupState>()({
+  id: 'environment-setup',
+  version: '1.0.0',
+  initialState: (input: EnvSetupInput) => envInitialState(input),
+  start: (state, input: EnvSetupInput) =>
+    envStartStep(state, input) === 'review'
+      ? { module: ENV_MODULE_ID, entry: 'review', input: { frameId: state.frameId } }
+      : { module: ENV_MODULE_ID, entry: 'pick', input: { frameId: state.frameId } },
+  steps: {
+    [ENV_MODULE_ID]: {
+      pick: { progressLabel: 'environmentWizard.steps.pick' },
+      review: { progressLabel: 'environmentWizard.steps.review' },
+      preflight: { progressLabel: 'environmentWizard.steps.preflight' },
+      save: { progressLabel: 'environmentWizard.steps.save' },
+    },
+  },
+  transitions: {
+    [ENV_MODULE_ID]: {
+      pick: {
+        [ENV_SELECT_EXIT]: transition({
+          targets: [{ module: ENV_MODULE_ID, entry: 'review' }],
+          handle: (ctx: ExitCtx<EnvSetupState, EnvSelectOutput, unknown>) => ({
+            next: {
+              module: ENV_MODULE_ID,
+              entry: 'review',
+              input: { frameId: ctx.output.frameId },
+            },
+            state: { frameId: ctx.output.frameId },
+          }),
+        }),
+      },
+      review: {
+        [ENV_ADVANCE_EXIT]: transition({
+          targets: [{ module: ENV_MODULE_ID, entry: 'preflight' }],
+          handle: (ctx) => ({
+            next: {
+              module: ENV_MODULE_ID,
+              entry: 'preflight',
+              input: { frameId: ctx.state.frameId },
+            },
+          }),
+        }),
+      },
+      preflight: {
+        [ENV_ADVANCE_EXIT]: transition({
+          targets: [{ module: ENV_MODULE_ID, entry: 'save' }],
+          handle: (ctx) => ({
+            next: {
+              module: ENV_MODULE_ID,
+              entry: 'save',
+              input: { frameId: ctx.state.frameId },
+            },
+          }),
+        }),
+      },
+      // `save` advances to journey completion.
+      save: {
+        [ENV_ADVANCE_EXIT]: transition({
+          targets: ['complete'],
+          handle: () => ({ complete: undefined }),
+        }),
+      },
+    },
+  },
+})

package/app/modular/journeys/environmentSetup.ts

@@ -1,6 +1,6 @@
 import { defineModule } from '@modular-vue/core'
 import { defineExit } from '@modular-frontend/core'
-import { defineJourney, defineJourneyHandle } from '@modular-vue/journeys'
+import { defineJourneyHandle } from '@modular-vue/journeys'
 import EnvPickStep from '~/components/environments/steps/EnvPickStep.vue'
 import EnvReviewStep from '~/components/environments/steps/EnvReviewStep.vue'
 import EnvPreflightStep from '~/components/environments/steps/EnvPreflightStep.vue'
@@ -13,9 +13,7 @@ import {
   type EnvSelectOutput,
   type EnvSetupInput,
   type EnvSetupState,
-  envInitialState,
-  envNextAfter,
-  envStartStep,
+  environmentSetupJourney,
 } from '~/modular/journeys/environmentSetup.logic'
 
 /**
@@ -25,6 +23,13 @@ import {
  * with a typed, back/rewind-capable, resumable journey; the per-step data + async
  * actions stay in that Pinia store, driven by the step components below.
  *
+ * This file supplies the step MODULE (it imports the step `.vue` components, so —
+ * like `result-views.ts` — it's registered from the client plugin, keeping the
+ * unit-tested `registry.ts` / `*.logic.ts` import graph free of SFCs) and re-exports
+ * the JOURNEY, whose transition graph + step metadata live in the SFC-free
+ * `environmentSetup.logic.ts` (so `resolveStepSequence` / `useJourneyProgress` and
+ * the ordering test have no `.vue` dependency).
+ *
  * Authoring notes (co-evolution): `defineModule` comes from the `@modular-vue/core`
  * binding, but the exit helper `defineExit` is only exported from the neutral
  * `@modular-frontend/core` engine (a direct dep) — the Vue binding doesn't re-export
@@ -36,10 +41,6 @@ import {
  * pick step and never changes mid-flow, so the snapshot input a transition places is
  * always current — even on `preserve-state` back-navigation — which keeps the module
  * type simple (no `buildInput`-optionality quirk) and the flow fully explicit.
- *
- * This file imports the step `.vue` components, so — like `result-views.ts` — it's
- * registered from the client plugin, keeping the unit-tested `registry.ts` /
- * `*.logic.ts` import graph free of SFCs.
  */
 
 /**
@@ -52,20 +53,20 @@ export const environmentSetupModule = defineModule({
   id: ENV_MODULE_ID,
   version: '1.0.0',
   entryPoints: {
-    pick: { mountKinds: ['journey'] as const, component: EnvPickStep },
+    pick: { mountKinds: ['journey'], component: EnvPickStep },
     review: {
-      mountKinds: ['journey'] as const,
-      allowBack: 'preserve-state' as const,
+      mountKinds: ['journey'],
+      allowBack: 'preserve-state',
       component: EnvReviewStep,
     },
     preflight: {
-      mountKinds: ['journey'] as const,
-      allowBack: 'preserve-state' as const,
+      mountKinds: ['journey'],
+      allowBack: 'preserve-state',
       component: EnvPreflightStep,
     },
     save: {
-      mountKinds: ['journey'] as const,
-      allowBack: 'preserve-state' as const,
+      mountKinds: ['journey'],
+      allowBack: 'preserve-state',
       component: EnvSaveStep,
     },
   },
@@ -75,59 +76,7 @@ export const environmentSetupModule = defineModule({
   },
 })
 
-type EnvModules = { [ENV_MODULE_ID]: typeof environmentSetupModule }
-
-/**
- * The journey definition. `start` skips the picker when a frame was preselected;
- * transitions are the linear pick → review → preflight → save chain, terminating
- * with `complete` off the save step's `advance`. Back-navigation is handled by the
- * entries' `allowBack`, not explicit transitions.
- */
-export const environmentSetupJourney = defineJourney<EnvModules, EnvSetupState>()({
-  id: 'environment-setup',
-  version: '1.0.0',
-  initialState: (input: EnvSetupInput) => envInitialState(input),
-  start: (state, input: EnvSetupInput) =>
-    envStartStep(state, input) === 'review'
-      ? ({ module: ENV_MODULE_ID, entry: 'review', input: { frameId: state.frameId } } as const)
-      : ({ module: ENV_MODULE_ID, entry: 'pick', input: { frameId: state.frameId } } as const),
-  transitions: {
-    [ENV_MODULE_ID]: {
-      pick: {
-        [ENV_SELECT_EXIT]: (ctx) => ({
-          next: {
-            module: ENV_MODULE_ID,
-            entry: 'review',
-            input: { frameId: ctx.output.frameId },
-          } as const,
-          state: { frameId: ctx.output.frameId },
-        }),
-      },
-      review: {
-        [ENV_ADVANCE_EXIT]: (ctx) => ({
-          next: {
-            module: ENV_MODULE_ID,
-            entry: envNextAfter('review'),
-            input: { frameId: ctx.state.frameId },
-          } as const,
-        }),
-      },
-      preflight: {
-        [ENV_ADVANCE_EXIT]: (ctx) => ({
-          next: {
-            module: ENV_MODULE_ID,
-            entry: envNextAfter('preflight'),
-            input: { frameId: ctx.state.frameId },
-          } as const,
-        }),
-      },
-      // `save` advances to `envNextAfter('save') === 'done'`, i.e. journey completion.
-      save: {
-        [ENV_ADVANCE_EXIT]: () => ({ complete: undefined }),
-      },
-    },
-  },
-})
+export { environmentSetupJourney }
 
 /** Typed launch handle — callers `runtime.start(handle, { frameId })`. */
 export const environmentSetupHandle = defineJourneyHandle(environmentSetupJourney)

package/app/stores/pipelines.ts

@@ -24,26 +24,11 @@ function defaultConsensusConfig(): ConsensusStepConfig {
 }
 
 /**
- * Saved, reusable pipelines (the pipeline palette) plus the in-progress draft
- * being assembled in the pipeline builder. Saved pipelines live on the backend;
- * the draft is transient client state. The draft doubles as the EDIT surface: a
- * custom pipeline can be loaded into it (`loadForEdit`) and saved back in place,
- * while a built-in is cloned first (`clonePipeline`) into an editable copy.
+ * The per-step, index-aligned draft arrays. Every one is kept the same length as `draft` and
+ * spliced/reordered in lockstep (see `insertAt` / `removeFromDraft` / `moveUnit`), so grouping
+ * their construction keeps that alignment contract — and its documentation — in one place.
  */
-export const usePipelinesStore = defineStore('pipelines', () => {
-  const api = useApi()
-  const {
-    items: pipelines,
-    upsert: upsertPipeline,
-    remove: dropPipeline,
-  } = useUpsertList<Pipeline>({ key: (p) => p.id })
-  /**
-   * Current built-in catalog versions (`seedPipelines()`), keyed by pipeline id, from the
-   * workspace snapshot. A built-in whose stored `version` is below its catalog value here has
-   * a newer definition available (see `usePipelineHealth`).
-   */
-  const catalogVersions = ref<Record<string, number>>({})
-
+function createDraftStepState() {
   /** The chain currently being assembled in the builder. */
   const draft = ref<AgentKind[]>([])
   /** Per-step approval gates, kept index-aligned with `draft`. */
@@ -79,6 +64,52 @@ export const usePipelinesStore = defineStore('pipelines', () => {
    * default, so an entry exists only when a step opts out of something.
    */
   const draftStepOptions = ref<(StepOptions | null)[]>([])
+  return {
+    draft,
+    draftGates,
+    draftEnabled,
+    draftThresholds,
+    draftConsensus,
+    draftGating,
+    draftFollowUps,
+    draftTesterQuality,
+    draftStepOptions,
+  }
+}
+
+/**
+ * Saved, reusable pipelines (the pipeline palette) plus the in-progress draft
+ * being assembled in the pipeline builder. Saved pipelines live on the backend;
+ * the draft is transient client state. The draft doubles as the EDIT surface: a
+ * custom pipeline can be loaded into it (`loadForEdit`) and saved back in place,
+ * while a built-in is cloned first (`clonePipeline`) into an editable copy.
+ */
+export const usePipelinesStore = defineStore('pipelines', () => {
+  const api = useApi()
+  const {
+    items: pipelines,
+    upsert: upsertPipeline,
+    remove: dropPipeline,
+  } = useUpsertList<Pipeline>({ key: (p) => p.id })
+  /**
+   * Current built-in catalog versions (`seedPipelines()`), keyed by pipeline id, from the
+   * workspace snapshot. A built-in whose stored `version` is below its catalog value here has
+   * a newer definition available (see `usePipelineHealth`).
+   */
+  const catalogVersions = ref<Record<string, number>>({})
+
+  // The per-step, index-aligned draft arrays (kept in lockstep — see `createDraftStepState`).
+  const {
+    draft,
+    draftGates,
+    draftEnabled,
+    draftThresholds,
+    draftConsensus,
+    draftGating,
+    draftFollowUps,
+    draftTesterQuality,
+    draftStepOptions,
+  } = createDraftStepState()
   /** Organizational labels for the pipeline being assembled/edited. */
   const draftLabels = ref<string[]>([])
   /**