@stackwright-pro/workflow

Zod schema and prebuild compiler for the Stackwright workflow.yml DSL.

What it provides

• WorkflowFileSchema — Zod validator for workflow.yml
• validateWorkflowSemantics() — graph-level checks: orphaned transitions, missing terminal states, invalid initial_step, invalid step cross-references
• parseWorkflowFile() — combined parse + validate helper returning a discriminated union (success: true | false)
• WorkflowPlugin / createWorkflowPlugin() — prebuild plugin that compiles workflow.yml → XState v5 machine definitions

Compilation output

For each pages/*/workflow.yml, the plugin emits into src/generated/workflow/{id}/:

| File | Contents | | ------------ | ----------------------------------------------------------------------------------------------- | | machine.ts | XState v5 createMachine() with guards for conditional branching | | types.ts | StepId union, TerminalState union, Context interface, WORKFLOW_SERVICES_CONFIGURED flag | | index.ts | Barrel re-export |

Persistence tiers

| Value | Behaviour | | ------------------------ | --------------------------------------------------------------------------------------------- | | persistence: session | sessionStorage (default) — state lost on tab close | | persistence: memory | In-memory only — state lost on navigation | | persistence: service:* | Requires @stackwright-pro/services — falls back to sessionStorage with a build-time warning |

Usage

// In your prebuild config
import { createWorkflowPlugin } from '@stackwright-pro/workflow';

export default {
  plugins: [createWorkflowPlugin()],
};