motia 0.14.0-beta.165-285707 → 0.15.0-beta.165

package/dist/esm/cursor-rules/dot-files/.cursor/rules/motia/virtual-steps.mdc

@@ -1,251 +0,0 @@
----
-description: Connecting nodes virtually and creating a smooth flow in Workbench
-globs: steps/**/*.step.ts,steps/**/*.step.js,steps/**/*_step.py
-alwaysApply: false
----
-
-# Virtual Steps Guide
-
-Virtual Steps are useful for creating a smooth flow in Workbench.
-
-They offer two ways to connect nodes virtually:
-- NOOP Steps: Used mostly when we want to override the workflow to add buttons or show UI elements.
-- Virtual Connections between steps: Used when we want to connect virtually two steps, with 
-or without NOOP Steps.
-
-## Creating NOOP Steps
-
-Steps need to be created in the `steps` folder, it can be in subfolders.
-
-- Steps in TS and JS should end with `.step.ts` and `.step.js` respectively.
-- Steps in Python should end with `_step.py`.
-
-### Configuration
-
-#### TypeScript Example
-
-```typescript
-import { NoopConfig } from 'motia'
-
-export const config: NoopConfig = {
-  /**
-   * Should always be noop
-   */
-  type: 'noop',
-
-  /**
-   * A unique name for this noop step, used internally and for linking handlers.
-   */
-  name: 'manual-trigger',
-
-  /**
-   * A description for this noop step, used for documentation and UI.
-   */
-  description: 'Manual trigger point for workflow',
-
-  /**
-   * An array of topics this step can emit events to.
-   */
-  virtualEmits: ['workflow.start'],
-
-  /**
-   * An array of topics this step can subscribe to.
-   */
-  virtualSubscribes: ['manual.trigger'],
-
-  /**
-   * An array of flow names this step belongs to.
-   */
-  flows: ['my-workflow']
-}
-
-// NOOP steps don't need handlers - they're purely for Workbench workflow connections
-```
-
-#### Python Example
-
-```python
-config = {
-    "type": "noop",
-    "name": "manual-trigger",
-    "description": "Manual trigger point for workflow",
-    "virtualEmits": ["workflow.start"],
-    "virtualSubscribes": ["manual.trigger"],
-    "flows": ["my-workflow"]
-}
-
-# NOOP steps don't need handlers - they're purely for Workbench workflow connections
-```
-
-### Common Use Cases
-
-#### Workflow Starter
-
-This NOOP step will create a flow node in Workbench, then as a UI Step, we will override it
-to show a button.
-
-**TypeScript:**
-```typescript
-export const config: NoopConfig = {
-  type: 'noop',
-  name: 'flow-starter',
-  description: 'Start point for the workflow',
-  virtualEmits: ['process.begin'],
-  virtualSubscribes: [],
-  flows: ['main-flow']
-}
-```
-
-**Python:**
-```python
-config = {
-    "type": "noop",
-    "name": "flow-starter",
-    "description": "Start point for the workflow",
-    "virtualEmits": ["process.begin"],
-    "virtualSubscribes": [],
-    "flows": ["main-flow"]
-}
-```
-
-### Manual Approval Point
-
-This NOOP step will create a flow node in Workbench, it's important just to connect
-a previous Step to the step where it will have a manual approval button.
-
-Example:
-
-```mermaid
-graph LR
-    A[Submit Article]
-    C[Approve Article]
-    D[Reject Article]
-```
-
-Without this NOOP Step, the steps A->C and A->D would all appear disconnected in Workbench.
-
-**TypeScript:**
-```typescript
-export const config: NoopConfig = {
-  type: 'noop',
-  name: 'approval-gate',
-  description: 'Manual approval required',
-  virtualEmits: ['approved'],
-  virtualSubscribes: ['pending.approval'],
-  flows: ['approval-flow']
-}
-```
-
-**Python:**
-```python
-config = {
-    "type": "noop",
-    "name": "approval-gate",
-    "description": "Manual approval required",
-    "virtualEmits": ["approved"],
-    "virtualSubscribes": ["pending.approval"],
-    "flows": ["approval-flow"]
-}
-```
-
-## How it works
-
-It uses the `virtualEmits` and `virtualSubscribes` to connect to the previous and next steps.
-
-In `Submit Article` Step, it must have a `virtualEmits: ['approved']` to connect to the `Manual Approval` Step.
-
-In `Approve Article` Step, it must have a `virtualSubscribes: ['pending.approval']` to connect to the `Submit Article` Step.
-
-It's also possible to connect two Steps without NOOP just by connecting them directly.
-It's also possible to use labels in connections.
-
-**TypeScript Examples:**
-```typescript
-export const config: ApiRouteConfig = {
-  type: 'api',
-  name: 'CreateArticle',
-  path: '/articles',
-  method: 'POST',
-  description: 'Creates an article',
-  virtualEmits: [{ topic: 'approval.required', label: 'Requires approval' }],
-  emits: [],
-  flows: ['article']
-}
-
-export const config: ApiRouteConfig = {
-  type: 'api',
-  name: 'ApproveArticle',
-  path: '/articles/:id/approve',
-  method: 'POST',
-  description: 'Approves an article',
-  virtualSubscribes: ['approval.required'],
-  emits: [],
-  flows: ['article']
-}
-
-export const config: ApiRouteConfig = {
-  type: 'api',
-  name: 'RejectArticle',
-  path: '/articles/:id/reject',
-  method: 'POST',
-  description: 'Rejects an article',
-  virtualSubscribes: ['approval.required'],
-  emits: [],
-  flows: ['article']
-}
-```
-
-**Python Examples:**
-```python
-# create_article_step.py
-config = {
-    "type": "api",
-    "name": "CreateArticle",
-    "path": "/articles",
-    "method": "POST",
-    "description": "Creates an article",
-    "virtualEmits": [{"topic": "approval.required", "label": "Requires approval"}],
-    "emits": [],
-    "flows": ["article"]
-}
-
-# approve_article_step.py
-config = {
-    "type": "api",
-    "name": "ApproveArticle",
-    "path": "/articles/:id/approve",
-    "method": "POST",
-    "description": "Approves an article",
-    "virtualSubscribes": ["approval.required"],
-    "emits": [],
-    "flows": ["article"]
-}
-
-# reject_article_step.py
-config = {
-    "type": "api",
-    "name": "RejectArticle",
-    "path": "/articles/:id/reject",
-    "method": "POST",
-    "description": "Rejects an article",
-    "virtualSubscribes": ["approval.required"],
-    "emits": [],
-    "flows": ["article"]
-}
-```
-
-This will create connection to two API Steps.
-
-
-```mermaid
-graph LR
-    A[Create Article] --> B[Requires Approval]
-    B --> C[Approve Article]
-    B --> D[Reject Article]
-```
-
-## When to Use NOOP Steps
-- Testing workflow connections
-- Manual trigger points
-- Workflow visualization
-- Placeholder for future steps

package/dist/esm/cursor-rules/dot-files/AGENTS.md

@@ -1,215 +0,0 @@
-# AGENTS.md
-
-> AI Development Guide for Motia Projects
-
-This file provides context and instructions for AI coding assistants working on Motia projects.
-
-## Project Overview
-
-This is a **Motia** application - a framework for building event-driven, type-safe backend systems with:
-- HTTP API endpoints (API Steps)
-- Background event processing (Event Steps)  
-- Scheduled tasks (Cron Steps)
-- Real-time streaming capabilities
-- Built-in state management
-- Visual workflow designer (Workbench)
-
-## Quick Start Commands
-
-```bash
-# Install dependencies
-npm install
-
-# Start development server (with hot reload)
-npm run dev
-
-# Start production server (without hot reload)
-npm run start
-
-# Generate TypeScript types from steps
-npx motia generate-types
-```
-
-## 📚 Comprehensive Guides
-
-**This project includes detailed Cursor rules in `.cursor/rules/` that contain comprehensive patterns and examples.**
-
-These guides are written in markdown and can be read by any AI coding tool. The sections below provide quick reference, but **always consult the detailed guides in `.cursor/` for complete patterns and examples.**
-
-### Available Guides
-
-Read these files in `.cursor/rules/motia/` for detailed patterns:
-
-- **`api-steps.mdc`** - Creating HTTP endpoints with schemas, validation, and middleware
-- **`event-steps.mdc`** - Background task processing and event-driven workflows
-- **`cron-steps.mdc`** - Scheduled tasks with cron expressions
-- **`state-management.mdc`** - State/cache management across steps
-- **`middlewares.mdc`** - Request/response middleware patterns
-- **`realtime-streaming.mdc`** - WebSocket and SSE patterns
-- **`virtual-steps.mdc`** - Visual flow connections in Workbench
-- **`ui-steps.mdc`** - Custom visual components for Workbench
-
-Architecture guides in `.cursor/architecture/`:
-
-- **`architecture.mdc`** - Project structure, naming conventions, DDD patterns
-- **`error-handling.mdc`** - Error handling best practices
-
-**Read these guides before writing code.** They contain complete examples, type definitions, and best practices.
-
-## Quick Reference
-
-> **⚠️ Important**: The sections below are brief summaries. **Always read the full guides in `.cursor/rules/` for complete patterns, examples, and type definitions.**
-
-### Project Structure
-
-```
-project/
-├── .cursor/rules/   # DETAILED GUIDES - Read these first!
-├── steps/           # All step definitions
-│   ├── api/        # API endpoints
-│   │   └── api.step.ts
-│   │   └── api.step.js
-│   │   └── api_step.py
-│   ├── events/     # Events
-│   │   └── events.step.ts
-│   │   └── events.step.js
-│   │   └── events_step.py
-│   └── cron/       # Scheduled tasks
-│   │   └── cron.step.ts
-│   │   └── cron.step.js
-│   │   └── cron_step.py
-├── middlewares/    # Reusable middleware
-│   └── middleware.middleware.ts
-├── src/
-│   ├── services/   # Business logic
-│   └── utils/      # Utilities
-├── config.yml      # Motia configuration
-└── types.d.ts      # Auto-generated types
-```
-
-### Step Naming Conventions
-
-**TypeScript/JavaScript:** `my-step.step.ts` (kebab-case)  
-**Python:** `my_step_step.py` (snake_case)
-
-See `.cursor/architecture/architecture.mdc` for complete naming rules.
-
-### Creating Steps - Quick Start
-
-Every step needs two exports:
-
-1. **`config`** - Defines type, routing, schemas, emits
-2. **`handler`** - Async function with processing logic
-
-**For complete examples and type definitions, read:**
-- `.cursor/rules/motia/api-steps.mdc` - HTTP endpoints
-- `.cursor/rules/motia/event-steps.mdc` - Background tasks
-- `.cursor/rules/motia/cron-steps.mdc` - Scheduled tasks
-
-## Detailed Guides by Topic
-
-> **📖 Read the cursor rules for complete information**
-
-### Step Types
-- **API Steps** → Read `.cursor/rules/motia/api-steps.mdc`
-  - HTTP endpoints, schemas, middleware, emits
-  - Complete TypeScript and Python examples
-  - When to use emits vs direct processing
-
-- **Event Steps** → Read `.cursor/rules/motia/event-steps.mdc`
-  - Background processing, topic subscriptions
-  - Retry mechanisms, error handling
-  - Chaining events for complex workflows
-
-- **Cron Steps** → Read `.cursor/rules/motia/cron-steps.mdc`
-  - Scheduled tasks with cron expressions
-  - Idempotent execution patterns
-  - Integration with event emits
-
-### Architecture
-- **Project Structure** → Read `.cursor/architecture/architecture.mdc`
-  - File organization, naming conventions
-  - Domain-Driven Design patterns (services, repositories)
-  - Code style guidelines for TypeScript, JavaScript, Python
-
-- **Error Handling** → Read `.cursor/architecture/error-handling.mdc`
-  - ZodError middleware patterns
-  - Logging best practices
-  - HTTP status codes
-
-### Advanced Features
-- **State Management** → Read `.cursor/rules/motia/state-management.mdc`
-  - Caching strategies, TTL configuration
-  - When to use state vs database
-  - Complete API reference
-
-- **Middlewares** → Read `.cursor/rules/motia/middlewares.mdc`
-  - Authentication, validation, error handling
-  - Creating reusable middleware
-  - Middleware composition
-
-- **Real-time Streaming** → Read `.cursor/rules/motia/realtime-streaming.mdc`
-  - Server-Sent Events (SSE) patterns
-  - WebSocket support
-  - Client-side integration
-
-- **Virtual Steps** → Read `.cursor/rules/motia/virtual-steps.mdc`
-  - Visual flow connections in Workbench
-  - Documenting API chains
-  - Flow organization
-
-- **UI Steps** → Read `.cursor/rules/motia/ui-steps.mdc`
-  - Custom Workbench visualizations
-  - Available components (EventNode, ApiNode, etc.)
-  - Styling with Tailwind
-
-## Workflow for AI Coding Assistants
-
-When working on Motia projects, follow this pattern:
-
-1. **Read the relevant guide** in `.cursor/rules/` for the task
-   - Creating API? Read `api-steps.mdc`
-   - Background task? Read `event-steps.mdc`
-   - Scheduled job? Read `cron-steps.mdc`
-
-2. **Check the architecture guide** in `.cursor/architecture/architecture.mdc`
-   - Understand project structure
-   - Follow naming conventions
-   - Apply DDD patterns
-
-3. **Implement following the patterns** from the guides
-   - Use the examples as templates
-   - Follow type definitions exactly
-   - Apply best practices
-
-4. **Generate types** after changes
-   ```bash
-   npx motia generate-types
-   ```
-
-5. **Test in Workbench** to verify connections
-   ```bash
-   npx motia dev
-   ```
-
-## Critical Rules
-
-- **ALWAYS** read `.cursor/rules/` guides before writing step code
-- **ALWAYS** run `npx motia generate-types` after modifying configs
-- **ALWAYS** list emits in config before using them in handlers
-- **ALWAYS** follow naming conventions (`*.step.ts` or `*_step.py`)
-- **NEVER** use API steps for background work (use Event steps)
-- **NEVER** skip middleware for ZodError handling in multi-step projects
-- **NEVER** implement rate limiting/CORS in code (infrastructure handles this)
-
-## Resources
-
-- **Detailed Guides**: `.cursor/rules/motia/*.mdc` (in this project)
-- **Architecture**: `.cursor/architecture/*.mdc` (in this project)
-- **Documentation**: [motia.dev/docs](https://motia.dev/docs)
-- **Examples**: [motia.dev/docs/examples](https://motia.dev/docs/examples)
-- **GitHub**: [github.com/MotiaDev/motia](https://github.com/MotiaDev/motia)
-
----
-
-**Remember**: This AGENTS.md is a quick reference. The `.cursor/rules/` directory contains the comprehensive, authoritative guides with complete examples and type definitions. Always consult those guides when implementing Motia patterns.

package/dist/esm/cursor-rules/dot-files/CLAUDE.md

@@ -1,58 +0,0 @@
-# Motia Project Guide for Claude Code & Claude AI
-
-This project uses **Motia** - a framework for building event-driven, type-safe backend systems.
-
-## 📚 Important: Read the Comprehensive Guides
-
-This project has detailed development guides in **`.cursor/rules/`** directory. These markdown files (`.mdc`) contain complete patterns, examples, and type definitions.
-
-**Before writing any Motia code, read the relevant guides from `.cursor/rules/`**
-
-### For Claude Code Users
-
-**A pre-configured subagent is ready!** 
-
-The `motia-developer` subagent in `.claude/agents/` automatically references all 10 cursor rules when coding.
-
-Use it: `/agents` → select `motia-developer`
-
-Learn more: [Claude Code Subagents Docs](https://docs.claude.com/en/docs/claude-code/sub-agents)
-
-### For Claude AI Assistant (Chat)
-
-Explicitly reference cursor rules in your prompts:
-
-```
-Read .cursor/rules/motia/api-steps.mdc and create an API endpoint 
-for user registration following the patterns shown.
-```
-
-## Available Guides (10 Comprehensive Files)
-
-All guides in `.cursor/rules/` with **TypeScript, JavaScript, and Python** examples:
-
-**Step Types** (`.cursor/rules/motia/`):
-- `api-steps.mdc`, `event-steps.mdc`, `cron-steps.mdc`
-
-**Features** (`.cursor/rules/motia/`):
-- `state-management.mdc`, `middlewares.mdc`, `realtime-streaming.mdc`
-- `virtual-steps.mdc`, `ui-steps.mdc`
-
-**Architecture** (`.cursor/architecture/`):
-- `architecture.mdc`, `error-handling.mdc`
-
-## Quick Reference
-
-See `AGENTS.md` in this directory for a quick overview and links to specific guides.
-
-## Key Commands
-
-```bash
-npm run dev              # Start development server (with hot reload)
-npm run start            # Start production server (without hot reload)
-npx motia generate-types # Regenerate TypeScript types
-```
-
----
-
-**Remember**: The `.cursor/rules/` directory is your primary reference. Read the relevant guide before implementing any Motia pattern.

package/dist/esm/cursor-rules/dot-files/opencode.json

@@ -1,18 +0,0 @@
-{
-  "name": "Motia Project",
-  "description": "Motia event-driven backend framework project",
-  "rules": ["AGENTS.md"],
-  "context": [
-    ".cursor/rules/motia/api-steps.mdc",
-    ".cursor/rules/motia/event-steps.mdc",
-    ".cursor/rules/motia/cron-steps.mdc",
-    ".cursor/rules/motia/realtime-streaming.mdc",
-    ".cursor/rules/motia/virtual-steps.mdc",
-    ".cursor/rules/motia/ui-steps.mdc",
-    ".cursor/rules/motia/state-management.mdc",
-    ".cursor/rules/motia/middlewares.mdc",
-    ".cursor/architecture/architecture.mdc",
-    ".cursor/architecture/error-handling.mdc"
-  ],
-  "notes": "Read AGENTS.md first - it references all detailed guides in .cursor/rules/ directory"
-}

package/dist/esm/dev-watchers.d.ts

@@ -1,5 +0,0 @@
-import { type CronManager, type LockedData, type MotiaEventManager, type MotiaServer } from '@motiadev/core';
-export declare const createDevWatchers: (lockedData: LockedData, server: MotiaServer, eventHandler: MotiaEventManager, cronManager: CronManager) => {
-    stop: () => Promise<void>;
-};
-//# sourceMappingURL=dev-watchers.d.ts.map

package/dist/esm/dev-watchers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dev-watchers.d.ts","sourceRoot":"","sources":["../../src/dev-watchers.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,EAIhB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAGjB,MAAM,gBAAgB,CAAA;AAwFvB,eAAO,MAAM,iBAAiB,GAC5B,YAAY,UAAU,EACtB,QAAQ,WAAW,EACnB,cAAc,iBAAiB,EAC/B,aAAa,WAAW;;CAoBzB,CAAA"}

package/dist/esm/dev-watchers.js

@@ -1,94 +0,0 @@
-import { isApiStep, isCronStep, isEventStep, trackEvent, } from '@motiadev/core';
-import { existsSync } from 'fs';
-import path from 'path';
-import { Watcher } from './watcher';
-const setupWatcherHandlers = (watcher, lockedData, server, eventHandler, cronManager) => {
-    watcher.onStreamChange((oldStream, stream) => {
-        trackEvent('stream_updated', {
-            streamName: stream.config.name,
-            type: stream.config.baseConfig.storageType,
-        });
-        return lockedData.updateStream(oldStream, stream);
-    });
-    watcher.onStreamCreate((stream) => {
-        trackEvent('stream_created', {
-            streamName: stream.config.name,
-            type: stream.config.baseConfig.storageType,
-        });
-        return lockedData.createStream(stream);
-    });
-    watcher.onStreamDelete((stream) => {
-        trackEvent('stream_deleted', {
-            streamName: stream.config.name,
-            type: stream.config.baseConfig.storageType,
-        });
-        return lockedData.deleteStream(stream);
-    });
-    watcher.onStepChange((oldStep, newStep) => {
-        if (isApiStep(oldStep))
-            server.removeRoute(oldStep);
-        if (isCronStep(oldStep))
-            cronManager.removeCronJob(oldStep);
-        if (isEventStep(oldStep))
-            eventHandler.removeHandler(oldStep);
-        const isUpdated = lockedData.updateStep(oldStep, newStep);
-        if (isUpdated) {
-            trackEvent('step_updated', {
-                stepName: newStep.config.name,
-                type: newStep.config.type,
-            });
-            if (isCronStep(newStep))
-                cronManager.createCronJob(newStep);
-            if (isEventStep(newStep))
-                eventHandler.createHandler(newStep);
-            if (isApiStep(newStep))
-                server.addRoute(newStep);
-        }
-    });
-    watcher.onStepCreate((step) => {
-        const isCreated = lockedData.createStep(step);
-        if (isCreated) {
-            trackEvent('step_created', {
-                stepName: step.config.name,
-                type: step.config.type,
-            });
-            if (isApiStep(step))
-                server.addRoute(step);
-            if (isEventStep(step))
-                eventHandler.createHandler(step);
-            if (isCronStep(step))
-                cronManager.createCronJob(step);
-        }
-    });
-    watcher.onStepDelete((step) => {
-        trackEvent('step_deleted', {
-            stepName: step.config.name,
-            type: step.config.type,
-        });
-        if (isApiStep(step))
-            server.removeRoute(step);
-        if (isEventStep(step))
-            eventHandler.removeHandler(step);
-        if (isCronStep(step))
-            cronManager.removeCronJob(step);
-        lockedData.deleteStep(step);
-    });
-};
-export const createDevWatchers = (lockedData, server, eventHandler, cronManager) => {
-    const baseDir = process.cwd();
-    const dirs = [path.join(baseDir, 'steps'), path.join(baseDir, 'src')];
-    const watchers = [];
-    dirs.forEach((dir) => {
-        if (existsSync(dir)) {
-            const watcher = new Watcher(dir, lockedData);
-            setupWatcherHandlers(watcher, lockedData, server, eventHandler, cronManager);
-            watcher.init();
-            watchers.push(watcher);
-        }
-    });
-    return {
-        stop: async () => {
-            await Promise.all(watchers.map((watcher) => watcher.stop()));
-        },
-    };
-};

package/dist/esm/dev.d.ts

@@ -1,2 +0,0 @@
-export declare const dev: (port: number, hostname: string, disableVerbose: boolean, enableMermaid: boolean, motiaFileStorageDir?: string) => Promise<void>;
-//# sourceMappingURL=dev.d.ts.map

package/dist/esm/dev.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../src/dev.ts"],"names":[],"mappings":"AA+BA,eAAO,MAAM,GAAG,GACd,MAAM,MAAM,EACZ,UAAU,MAAM,EAChB,gBAAgB,OAAO,EACvB,eAAe,OAAO,EACtB,sBAAsB,MAAM,KAC3B,OAAO,CAAC,IAAI,CA4Hd,CAAA"}