Skip to content

Decompose the wizard store + session into composable, program-defined slices #768

Open

Description

@gewenyu99

Problem

The global WizardSession and the TUI store have become a catch-all. Every program's state lives flat on one shared object, so the core keeps growing and infrastructure code carries product knowledge it shouldn't.

Today:

  • src/lib/wizard-session.ts — 404 lines, ~164 fields/members on the session interface.
  • src/ui/tui/store.ts — 944 lines, 29 explicit setters (each must remember to call emitChange()).
  • Program-specific state is flat on the shared session regardless of which program is running, e.g. mcpComplete / mcpOutcome / mcpInstalledClients / mcpSuggestedPromptsDismissed, slackStepDismissed / slackConnected, skillsComplete / skillId, … These exist on the session for an audit or revenue-analytics run that never touches MCP or Slack.

This violates the repo's own design discipline (AGENTS.md: product knowledge never enters infrastructure code). The store/session are machinery, but they currently know about MCP, Slack, skills, etc. Adding a program means widening the shared session and adding setters to the shared store — the bloat compounds.

Goal

Make the store and session composable and driven by program definitions (src/lib/programs/), so:

  • The core session holds only program-agnostic state (install dir, credentials, detected framework, run phase, current screen).
  • Each program contributes its own typed state slice (e.g. mcp, slack, skills) declared alongside its program definition, mounted only when that program runs.
  • The store composes setters/selectors from the active program's slices instead of hardcoding all 29.
  • Screens read/write their program's slice, not a flat global.

Sketch (not prescriptive)

  • A program definition declares an optional state: { initial, setters } slice with a typed shape.
  • buildSession() composes core + the active program's slices; the store derives its setter surface from them (so emitChange() is wired once, generically).
  • Migrate the obvious clusters first: mcp*, slack*, skill* → owned by the programs that use them.

Acceptance criteria

  • Core WizardSession no longer references program-specific concepts (MCP/Slack/skills/etc.).
  • At least the MCP, Slack, and skills state are program-owned slices, mounted only for programs that declare them.
  • Store setter/selector surface is composed from active slices, not a flat hardcoded list; emitChange() stays centralized.
  • Adding a new program needs no edits to the core session/store — only its own definition + slice.
  • pnpm build && pnpm test green; router/screen-resolution behavior unchanged.

Notes

  • Read .claude/skills/wizard-development/SKILL.md + references/ARCHITECTURE.md first — this is a structural change to the pipeline's core.
  • Keep the nanostore single-shallow-copy + explicit-setter invariant; the change is about where slices are defined and composed, not how mutation/emit works.

Activity

  1. self-assigned this
    on Jun 30, 2026
  2. gewenyu99 commented on Jun 30, 2026

    @gewenyu99
    CollaboratorAuthor

    Context from the self-driving runner work (#760): the composition seam is the step list / screens, not just the program id.

    The runner now walks a program's step list and advances each step itself — auth authenticates, a run step runs its agent, a screen waits for the user (advanceStep in run-wizard.ts). State should compose the same way: a program's slice is the union of what its screens read and write, and the step list already declares which screens a program mounts. So the screen set is the natural key for which slices to mount.

    This is compounding in real time. Self-driving just added flat fields to the shared session — integrate, selfDrivingHandoffConfirmed, completedRuns (plus cloudRegion/apiProject for auth reuse) — each used by exactly one of its screens. An audit or revenue-analytics run now carries self-driving's handoff flag for no reason. Every new program widens the global a bit more.

    So the slice should hang off the screen/step that owns it:

    • integration-check ↔ { integrate }
    • integration-detect ↔ the picked integration + path
    • self-driving-handoff ↔ { selfDrivingHandoffConfirmed }
    • the composed run ↔ { completedRuns }

    buildSession() mounts the slices for the screens in the active program's step list; the store derives its setters from them; screens read their own slice instead of a flat global. Same "compose from program definitions" goal, keyed on the screens each program declares.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions