Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

Use XState machines for designing and explaining complex state

Abierto
  • ¿Algo no está bien?
#14 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
35/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
node.js, typescript
Área
developer-experience

Línea de trabajo

Start by reading the architect, interrogate, how, and teach entry points and the repository’s existing reference files. Then resolve the listed questions about Stately login, privacy, sketch format, and tooling before drafting state-machines.md and updating the relevant phases. Done means the guidance and edits cover the agreed workflow and its fallback; the issue does not name tests to run.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

enhancement grilling

Problem

When agents design or explain parts of a system, everything comes back as prose. Lifecycle and protocol state (auth flows, sync, retry/cancel/timeout, wizards, connection handling) is hard to review that way. Impossible states hide in boolean flags, and nobody can check that the code still matches the agreed design.

Idea

Use XState machines as the notation for complex state. An agent writes the machine as code, the human reviews it as a diagram, and the same machine yields a test plan and a check for drift. Use the Stately CLI (statelyai) for the tooling.

Draft placement:

Where What
New state-machines.md reference When to reach for XState: lifecycle or protocol state, async flows with cancel/retry/timeout, or several booleans that can combine into impossible states. When not to: simple toggles and plain data transforms.
architect Phase A statelyai scan --json to find existing machines while grounding.
architect Phase B For state-heavy work, the sketch includes a machine next to the types.
architect Phase C At a checkpoint, statelyai open gives the human an editable diagram.
architect Phase D statelyai diff checks the implementation against the agreed machine. @xstate/graph paths become the test plan for tdd.
interrogate statelyai diff against the base when a diff touches a machine.
how / teach Offer open when a subsystem already has a machine.

Default to using the machine as a design document: the sketch lives outside the project's source, and the project gains no dependency. Adding xstate to the app is a separate architect candidate. It's labelled as adding a dependency and goes ahead only on approval, or when scan shows the project already uses xstate.

Tldraw is out of scope for now. It would need its own bridge into Claude Code, and the Stately CLI already covers the state-machine case.

Findings (tested 2026-10-22)

Probes ran in throwaway folders with no package.json or node_modules.

  • The CLI needs no xstate in the target project. It reads the source as text and never imports xstate.
    • scan --json found the machines with no config and no login.
    • diff a.ts b.ts --fail-on-changes works on two local files. It reported Added edges: root.closed->SLAM->root.open, exiting 1 when the machines differ and 0 when they match.
  • [email protected] (latest) doesn't install. It depends on @statelyai/[email protected], which isn't on npm (404). 0.14.3 works. Pin an exact version.
  • A JSON machine compares equal to the same machine in TS. diff door.machine.ts door.json reported no changes. A plain .json sketch would avoid the problem of an import 'xstate' line breaking the project's typecheck. scan only listed the .ts file, though.
  • diff can't read Mermaid. It fails on .mmd with a JSON parse error, even though the CLI's file pattern includes .mmd/.mermaid.
  • open needs a Stately account. The CLI starts a local server, but the editor is an iframe from editor.stately.ai. Its access endpoint (/api/editor-sync/access) returns 401 AUTH_INVALID: A valid Stately credential is required for editor sync without a credential. Write-back to the source file is not verified.
  • Path generation works outside the project. @xstate/[email protected] with [email protected] and tsx, installed in a scratch folder, produced shortest paths as event sequences. Example: FETCH → REJECT → RETRY → RESOLVE.
  • Sketches with stubbed actions give misleading paths. In a retry machine whose bumpRetries action was named but not implemented, the retry count never changed, and gaveUp was never reached. With bumpRetries implemented as an assign, it was reached via FETCH, REJECT, RETRY, REJECT, RETRY, REJECT, RETRY, along with 13 paths in all. Implementing the action also showed that CANCEL doesn't reset the retry count. That's the kind of design gap this approach should surface.

Open questions

  • Stately account. Is a login acceptable for the visual part, and does the free tier cover editor sync? Without one, gstack gets scan, diff and test paths, but no diagram editing.
  • Privacy. With open, the machine is shown in a page hosted by Stately. Does the machine content leave the machine (i.e. reach Stately's servers)? Is that OK for private repos?
  • Write-back. Once logged in, do edits in open land cleanly in a .ts sketch? What about a .json one? And what does --source-update preserve|rewrite do to formatting?
  • Fallback diagram. Without an account, what do we show? Options: a Mermaid stateDiagram written by the agent, or one generated from the machine.
  • Sketch format and location. .ts (scan finds it, but it imports xstate) or .json (no import, diff works, scan doesn't list it)? Scratchpad or a committed planning folder?
  • Stubbed implementations. Should architect require real assigns for context the guards read? Or should paths only be generated from an implemented machine?
  • Path explosion. Context values multiply the states the path search explores. What limits do we set before we feed the paths to tdd?
  • Tooling dependency. gstack would need Node, npx and network access to fetch pinned packages. Is that acceptable for a skill, and what's the fallback when they're missing?
  • Trigger. How does architect decide that work is "state-heavy" without asking every time?

Next step

Grill the open questions, starting with the Stately account and privacy questions. Then write state-machines.md and the architect edits.

Lenguaje dominante
TypeScript
Estrellas
0
Forks
0
Merge medio
3 h 33 min
PR fusionados (30 d)
13

Preparar el entorno

Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de gregogun/gstack

Todos los issues de gregogun/gstack

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.