Step Switch

Step Switch convierte un flujo de trabajo empresarial finito en datos ejecutables. Dado un Machine Spec, una instantánea y un evento, acepta o rechaza determinísticamente la transición, devuelve la siguiente instantánea y emite intenciones de efectos simbólicos. Nunca ejecuta esos efectos.

El repositorio incluye un núcleo TypeScript compartido, una CLI, seis herramientas MCP de solo lectura en un plugin de Codex y un editor/simulador de navegador.

Intencionadamente se mantiene más pequeño que un runtime de statechart completo: los guards son hechos explícitos proporcionados por el llamador, los efectos son intenciones simbólicas, las entradas del Agent son en línea y de mundo cerrado, y ninguna superficie evalúa código de usuario.

Instalar el plugin de Codex

El canal público de distribución de código fuente es el marketplace del repositorio de GitHub. Después de que la versión v0.1.0 esté disponible:

codex plugin marketplace add tetracoralla/state-machine --ref v0.1.0
codex plugin add state-machine@state-machine

Reinicia ChatGPT o Codex, abre una nueva tarea y usa un Machine Spec concreto. Por ejemplo, pídele que valide examples/order.machine.yaml, que pruebe si un evento es legal desde una instantánea, o que simule una secuencia de eventos. Una solicitud normal admitida debería requerir una llamada a la herramienta machine.*.

El repositorio incluye .agents/plugins/marketplace.json y el servidor precompilado confirmado, por lo que los usuarios del plugin no necesitan npm, TypeScript ni un paso de compilación. Consulta la documentación actual de empaquetado de plugins de OpenAI para conocer el comportamiento del marketplace y del host.

Desarrollar desde el código fuente

npm ci
npm run check

Se requieren Node.js 22 o posterior y npm 10 o posterior. El paquete de Node es intencionadamente privado y no es un canal de distribución de npm.

Ejecutar el editor

npm ci
npm run build
npm run start:ui

Abre http://127.0.0.1:4317. El espacio de trabajo incluye un ejemplo de ciclo de vida de pedido. Edita la definición YAML, inspecciona la validación y la topología, elige resultados de guard explícitos, ejecuta eventos, inspecciona el rastro y las intenciones de efectos, encuentra una ruta a un estado objetivo e importa o exporta la especificación.

Para desarrollo con recarga en vivo:

npm run dev:ui

Usar la CLI

npm run build

node dist/node/adapters/cli.js validate examples/order.machine.yaml --pretty

node dist/node/adapters/cli.js step examples/order.machine.yaml \
  --event '{"type":"PAYMENT_SUCCESS","payload":{"amount":128,"payment_id":"pay_1024"}}' \
  --guards '{"payment_amount_matches":true}' \
  --pretty

node dist/node/adapters/cli.js simulate \
  examples/order.machine.yaml \
  examples/order.events.yaml \
  --pretty

node dist/node/adapters/cli.js path \
  examples/order.machine.yaml \
  completed \
  --pretty

La CLI también admite inspect y diff. Ejecútala sin argumentos para obtener el resumen completo de comandos. El código de salida 0 significa que la operación se completó, incluyendo rechazos de transición ordinarios y rutas inalcanzables. El código de salida 1 significa que la máquina o el resultado de la operación no es válido; el código de salida 2 está reservado para errores de uso de comando, archivo o JSON. Cada resultado se emite igualmente como JSON.

Usar las herramientas del Agent

El plugin compilado es plugins/state-machine. Contiene el servidor MCP stdio incluido, el manifiesto y la Skill use-state-machine. Este repositorio no modifica un marketplace personal ni se instala automáticamente. Los contribuyentes pueden añadir un checkout local para pruebas previas al lanzamiento:

codex plugin marketplace add /absolute/path/to/state-machine
codex plugin add state-machine@state-machine

Reinicia el host y prueba en una nueva tarea después de instalar o actualizar.

Herramientas públicas:

Todas las herramientas aceptan datos en línea, no realizan cambios externos y publican esquemas de entrada estrictos. Los resultados se verifican contra los esquemas de salida ejecutables antes de salir del servidor. El catálogo de descubrimiento de seis herramientas está limitado a 36 KiB por el contrato de runtime. Una solicitud normal debería usar una llamada directa a una herramienta.

Machine Spec

El formato canónico es YAML o JSON con version: "0.1", un estado initial, campos de contexto y evento declarados, guards con nombre y un mapa de estados. Cada par estado/evento posee como máximo una transición. La asignación de contexto usa solo fuentes de valor etiquetadas literal, event o context. Los efectos contienen solo un type simbólico y fuentes de valor de entrada.

Consulta Machine Spec v0.1, el machine-spec.schema.json generado y el order.machine.yaml incluido.

Verificar el proyecto

npm run check

Esto ejecuta comprobaciones de tipos, pruebas del núcleo, comprobaciones de desviación de esquemas, todas las compilaciones, pruebas de CLI y MCP stdio compiladas, una instalación de paquete aislada, interacción con el navegador y regresiones responsivas, y comprobaciones de plugin/contrato. La aceptación visual y empresarial general sigue siendo el juicio del propietario sobre el runtime renderizado; su ruta actual se registra en docs/REVIEW_CONTRACT.md.

Los detalles de contribución y lanzamiento están en CONTRIBUTING.md y docs/RELEASE.md. Los identificadores públicos estables se registran en docs/PRODUCT_IDENTITY.md.

Límite

v0.1 excluye intencionadamente las semánticas de statechart jerárquicas, paralelas, de historial, diferidas, de actor y sin eventos. También excluye la evaluación de expresiones, la ejecución de efectos, la orquestación de producción, las reglas de negocio generadas por IA y las afirmaciones de compatibilidad con XState/SCXML. El límite actual del producto se mantiene en docs/PRODUCT_MODEL.md.

Licencia

Step Switch está licenciado bajo la Apache License 2.0. Consulta LICENSE y NOTICE. El plugin independiente incluye sus propias copias más el texto de licencia y atribución para el software incluido en las distribuciones de navegador y MCP.