@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/skills/cursor/xstate-testing-patterns/SKILL.md

@@ -0,0 +1,173 @@
+# XState Testing Patterns
+
+> Test XState machines with direct state transition assertions and model-based testing for path coverage
+
+## When to Use
+
+- Verifying that a machine transitions correctly for all expected event sequences
+- Testing guards, actions, and context updates in isolation
+- Generating exhaustive test paths from a machine definition
+- Integration testing React components backed by XState machines
+
+## Instructions
+
+1. **Direct transition testing:** Create an actor, send events, and assert on the resulting state. This is the simplest approach.
+2. **Test the machine, not the framework.** Focus on: correct transitions, guard behavior, context updates, and final states. Do not test that XState itself works.
+3. **Extract and unit test guards and actions separately** as pure functions before testing the full machine.
+4. **For integration tests,** use `@xstate/test` to generate test paths that cover all states and transitions.
+5. **Mock services** by overriding them in the machine config rather than mocking fetch globally.
+6. Test for illegal transitions — events that should NOT cause a transition in a given state.
+
+```typescript
+// auth.machine.test.ts — direct transition testing
+import { createActor } from 'xstate'; // v5
+import { authMachine } from './auth.machine';
+
+describe('auth machine', () => {
+  it('transitions from idle to authenticating on LOGIN', () => {
+    const actor = createActor(authMachine).start();
+    actor.send({ type: 'LOGIN', email: 'a@b.com', password: '123' });
+    expect(actor.getSnapshot().matches('authenticating')).toBe(true);
+    actor.stop();
+  });
+
+  it('ignores LOGOUT in idle state', () => {
+    const actor = createActor(authMachine).start();
+    actor.send({ type: 'LOGOUT' });
+    expect(actor.getSnapshot().matches('idle')).toBe(true);
+    actor.stop();
+  });
+
+  it('stores user on successful authentication', async () => {
+    const testMachine = authMachine.provide({
+      actors: {
+        authenticate: fromPromise(async () => ({ id: '1', name: 'Alice' })),
+      },
+    });
+    const actor = createActor(testMachine).start();
+    actor.send({ type: 'LOGIN', email: 'a@b.com', password: '123' });
+
+    // Wait for the invoke to complete
+    await new Promise((resolve) => {
+      actor.subscribe((snapshot) => {
+        if (snapshot.matches('authenticated')) resolve(undefined);
+      });
+    });
+
+    expect(actor.getSnapshot().context.user).toEqual({ id: '1', name: 'Alice' });
+    actor.stop();
+  });
+});
+```
+
+```typescript
+// Testing guards in isolation
+import { canRetry } from './auth.guards';
+
+describe('canRetry guard', () => {
+  it('allows retry when retries < 3', () => {
+    expect(canRetry({ context: { retries: 2 } })).toBe(true);
+  });
+
+  it('blocks retry when retries >= 3', () => {
+    expect(canRetry({ context: { retries: 3 } })).toBe(false);
+  });
+});
+```
+
+## Details
+
+**v4 testing style:**
+
+```typescript
+import { interpret } from 'xstate';
+
+const service = interpret(machine).start();
+service.send('LOGIN');
+expect(service.state.matches('authenticating')).toBe(true);
+service.stop();
+```
+
+**@xstate/test model-based testing:** Generates test paths that cover all reachable states:
+
+```typescript
+import { createTestModel, createTestMachine } from '@xstate/test';
+
+const testMachine = createTestMachine({
+  initial: 'idle',
+  states: {
+    idle: {
+      on: { LOGIN: 'loading' },
+      meta: {
+        test: async (page) => {
+          await expect(page.getByText('Sign in')).toBeVisible();
+        },
+      },
+    },
+    loading: {
+      on: { SUCCESS: 'dashboard' },
+      meta: {
+        test: async (page) => {
+          await expect(page.getByText('Loading')).toBeVisible();
+        },
+      },
+    },
+    dashboard: {
+      meta: {
+        test: async (page) => {
+          await expect(page.getByText('Welcome')).toBeVisible();
+        },
+      },
+    },
+  },
+});
+
+const model = createTestModel(testMachine);
+const paths = model.getShortestPaths();
+
+paths.forEach((path) => {
+  it(path.description, async () => {
+    await path.test({
+      /* page or test context */
+    });
+  });
+});
+```
+
+**What to test for each machine:**
+
+- Happy path transitions (idle -> loading -> success)
+- Error paths (idle -> loading -> error -> retry -> loading -> success)
+- Guard rejections (event sent but transition blocked)
+- Context updates after each transition
+- Final state reachability
+- Events that should be ignored in certain states
+
+**Mocking services in v5:**
+
+```typescript
+const testMachine = machine.provide({
+  actors: { fetchData: fromPromise(async () => mockData) },
+  actions: { logAnalytics: () => {} }, // No-op in tests
+});
+```
+
+## Source
+
+https://stately.ai/docs/testing
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/xstate-testing-patterns/skill.yaml

@@ -0,0 +1,39 @@
+name: xstate-testing-patterns
+version: '1.0.0'
+description: Test XState machines with model-based testing and direct state assertions
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.machine.ts'
+  - '**/*.test.ts'
+  - '**/machines/**'
+related_skills:
+  - xstate-machine-definition
+  - xstate-guards-actions
+  - xstate-react-integration
+stack_signals:
+  - xstate
+  - typescript
+  - react
+keywords:
+  - testing
+  - model-based
+  - state-assertions
+  - createTestModel
+  - machine-testing
+metadata:
+  author: community
+  upstream: 'xstate/docs/testing'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/xstate-typegen/SKILL.md

@@ -0,0 +1,168 @@
+# XState Typegen
+
+> Generate full type safety for XState machines with typegen (v4) and the setup pattern (v5)
+
+## When to Use
+
+- Getting TypeScript errors about missing event types in guards or actions
+- Wanting autocompletion for state names, event types, and action names
+- Ensuring type safety between machine definition and service implementations
+- Setting up a new XState project with strict typing from the start
+
+## Instructions
+
+### XState v5 (recommended): setup pattern
+
+1. Use `setup()` to declare all types, actions, guards, actors, and delays before creating the machine.
+2. Define `types` with TypeScript `as` assertion for context, events, input, and output.
+3. All actions, guards, and actors referenced in the machine must be declared in `setup()` — runtime errors if missing.
+4. The machine is fully typed from the `setup()` declaration — no separate code generation step.
+
+```typescript
+// auth.machine.ts (v5)
+import { setup, assign, fromPromise } from 'xstate';
+
+interface AuthContext {
+  user: { id: string; name: string } | null;
+  error: string | null;
+}
+
+type AuthEvent = { type: 'LOGIN'; email: string; password: string } | { type: 'LOGOUT' };
+
+const authMachine = setup({
+  types: {} as {
+    context: AuthContext;
+    events: AuthEvent;
+    input: { redirectUrl?: string };
+  },
+  actors: {
+    authenticate: fromPromise(async ({ input }: { input: { email: string; password: string } }) => {
+      const res = await fetch('/api/login', {
+        method: 'POST',
+        body: JSON.stringify(input),
+      });
+      if (!res.ok) throw new Error('Auth failed');
+      return res.json() as Promise<{ id: string; name: string }>;
+    }),
+  },
+  actions: {
+    setUser: assign({
+      user: (_, params: { id: string; name: string }) => params,
+    }),
+    clearUser: assign({ user: null, error: null }),
+    setError: assign({
+      error: (_, params: { message: string }) => params.message,
+    }),
+  },
+  guards: {
+    isAuthenticated: ({ context }) => context.user !== null,
+  },
+}).createMachine({
+  id: 'auth',
+  initial: 'idle',
+  context: ({ input }) => ({
+    user: null,
+    error: null,
+  }),
+  states: {
+    idle: {
+      on: { LOGIN: 'authenticating' },
+    },
+    authenticating: {
+      invoke: {
+        src: 'authenticate',
+        input: ({ event }) => ({
+          email: (event as { email: string }).email,
+          password: (event as { password: string }).password,
+        }),
+        onDone: {
+          target: 'authenticated',
+          actions: { type: 'setUser', params: ({ event }) => event.output },
+        },
+        onError: {
+          target: 'error',
+          actions: {
+            type: 'setError',
+            params: ({ event }) => ({ message: (event.error as Error).message }),
+          },
+        },
+      },
+    },
+    authenticated: {
+      on: { LOGOUT: { target: 'idle', actions: 'clearUser' } },
+    },
+    error: {
+      on: { LOGIN: 'authenticating' },
+    },
+  },
+});
+```
+
+### XState v4: typegen
+
+1. Install `@xstate/cli`: `npm install -D @xstate/cli`.
+2. Add `tsTypes: {}` to the machine config to enable typegen.
+3. Run `xstate typegen "src/**/*.machine.ts"` to generate `.typegen.ts` files.
+4. The generated file provides exact types for which events are valid in which states, which services are invoked, and which actions/guards are used.
+
+```typescript
+// v4 with typegen
+import { createMachine } from 'xstate';
+
+const machine = createMachine({
+  tsTypes: {} as import('./auth.machine.typegen').Typegen0,
+  schema: {
+    context: {} as AuthContext,
+    events: {} as AuthEvent,
+    services: {} as { authenticate: { data: User } },
+  },
+  // ...
+});
+```
+
+## Details
+
+**v5 setup benefits over v4 typegen:**
+
+- No code generation step — types flow from `setup()` directly
+- Actions and guards must exist at declaration time — catches typos immediately
+- Actor input/output types are inferred from `fromPromise`, `fromCallback`, etc.
+- No `.typegen.ts` files to maintain or commit
+
+**Typing event narrowing in actions:** In v5, action implementations receive the full event union. Narrow when needed:
+
+```typescript
+actions: {
+  handleLogin: ({ event }) => {
+    if (event.type === 'LOGIN') {
+      console.log(event.email); // Typed correctly
+    }
+  },
+},
+```
+
+**Common type issues:**
+
+- `Type 'string' is not assignable to type 'never'` in transitions — usually means the event is not listed in the events type
+- Missing action/guard in `setup()` — v5 requires all referenced names to be declared upfront
+- Circular type inference — break cycles by explicitly typing `context` function return
+
+## Source
+
+https://stately.ai/docs/typescript
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/xstate-typegen/skill.yaml

@@ -0,0 +1,39 @@
+name: xstate-typegen
+version: '1.0.0'
+description: Generate full type safety for XState machines with typegen and setup patterns
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.machine.ts'
+  - '**/*.machine.tsx'
+  - '**/machines/**'
+related_skills:
+  - xstate-machine-definition
+  - xstate-guards-actions
+  - xstate-react-integration
+stack_signals:
+  - xstate
+  - typescript
+  - react
+keywords:
+  - typegen
+  - type-safety
+  - setup
+  - typed-events
+  - typed-context
+metadata:
+  author: community
+  upstream: 'xstate/docs/typegen'
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/cursor/xstate-visualization/SKILL.md

@@ -0,0 +1,124 @@
+# XState Visualization
+
+> Visualize and inspect XState machines at design time and runtime with Stately Studio, Inspector, and VS Code extension
+
+## When to Use
+
+- Designing a new state machine and wanting to see the state diagram before coding
+- Debugging runtime state transitions in a running application
+- Sharing machine diagrams with non-technical stakeholders
+- Validating that a machine handles all expected paths
+
+## Instructions
+
+1. **Stately Studio (stately.ai/editor):** Paste machine code or use the visual editor to create machines. Export as code. Best for design-time exploration and sharing.
+2. **@stately/inspect:** Add runtime inspection to see live state transitions in your running app.
+3. **VS Code extension:** Install "XState" extension for inline visualization and code-to-diagram sync.
+4. Use visualization to verify: all states are reachable, no dead-end states exist (unless intentional final states), and all events are handled or explicitly ignored.
+
+```typescript
+// Add runtime inspection to a React app
+import { createBrowserInspector } from '@stately/inspect';
+
+const inspector = createBrowserInspector();
+
+// Option 1: Global inspection (all actors)
+import { useMachine } from '@xstate/react';
+
+const [state, send] = useMachine(myMachine, {
+  inspect: inspector.inspect,
+});
+```
+
+```typescript
+// Option 2: Inspect specific actors (v5)
+import { createActor } from 'xstate';
+
+const actor = createActor(myMachine, {
+  inspect: inspector.inspect,
+});
+actor.start();
+```
+
+```typescript
+// Node.js inspection (opens in browser)
+import { createBrowserInspector } from '@stately/inspect';
+
+const inspector = createBrowserInspector({
+  url: 'https://stately.ai/inspect',
+});
+// Pass inspector.inspect to actor options
+```
+
+## Details
+
+**Stately Studio features:**
+
+- Visual state machine editor with drag-and-drop
+- Import existing machine code via paste or GitHub sync
+- Generate code from visual diagrams
+- Simulate event sequences interactively
+- Share read-only URLs with team members
+- Version history for machine definitions
+
+**@stately/inspect setup:**
+
+```bash
+npm install @stately/inspect
+```
+
+The inspector opens a new browser tab (or panel) showing the live statechart with:
+
+- Current state highlighted
+- Event log showing every dispatched event
+- Context values at each step
+- Timeline of state transitions
+
+**VS Code extension:**
+
+- Install "Stately XState" from the marketplace
+- Hover over `createMachine` to see an inline diagram
+- Cmd+click on state names to jump to their definition
+- Validates machine structure and warns about unreachable states
+
+**Design-first workflow:**
+
+1. Sketch the state diagram in Stately Studio or on a whiteboard
+2. Export the machine code from Studio
+3. Add guards, actions, and services in the codebase
+4. Use the inspector during development to verify runtime behavior
+5. Run model-based tests to ensure coverage
+
+**What to look for in the visualization:**
+
+- States with no outgoing transitions (are they intentional final states?)
+- Events that are never handled in any state (dead events)
+- States that are unreachable from the initial state
+- Transitions that bypass expected intermediate states
+- Guard conditions that could permanently trap the machine in a state
+
+**Production considerations:** Disable the inspector in production builds. Use environment variables:
+
+```typescript
+const inspector = process.env.NODE_ENV === 'development' ? createBrowserInspector() : undefined;
+```
+
+## Source
+
+https://stately.ai/docs/inspector
+
+## Process
+
+1. Read the instructions and examples in this document.
+2. Apply the patterns to your implementation, adapting to your specific context.
+3. Verify your implementation against the details and edge cases listed above.
+
+## Harness Integration
+
+- **Type:** knowledge — this skill is a reference document, not a procedural workflow.
+- **No tools or state** — consumed as context by other skills and agents.
+
+## Success Criteria
+
+- The patterns described in this document are applied correctly in the implementation.
+- Edge cases and anti-patterns listed in this document are avoided.

package/dist/agents/skills/cursor/xstate-visualization/skill.yaml

@@ -0,0 +1,39 @@
+name: xstate-visualization
+version: '1.0.0'
+description: Visualize and inspect XState machines with Stately Inspector and VS Code extension
+cognitive_mode: advisory-guide
+type: knowledge
+tier: 3
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools: []
+paths:
+  - '**/*.machine.ts'
+  - '**/*.machine.tsx'
+  - '**/machines/**'
+related_skills:
+  - xstate-machine-definition
+  - xstate-react-integration
+  - xstate-testing-patterns
+stack_signals:
+  - xstate
+  - typescript
+  - react
+keywords:
+  - visualization
+  - inspector
+  - stately
+  - devtools
+  - state-diagram
+metadata:
+  author: community
+  upstream: 'xstate/docs/inspector'
+state:
+  persistent: false
+  files: []
+depends_on: []