motia 0.7.2-beta.135-745094 → 0.7.3-beta.136

package/dist/cjs/create/templates/generate.js

@@ -40,7 +40,7 @@ const glob_1 = require("glob");
 const generateTemplateSteps = (templateFolder) => {
     return async (rootDir, context) => {
         const templatePath = path.join(__dirname, templateFolder);
-        const files = (0, glob_1.globSync)('**/*', { absolute: false, cwd: templatePath, dot: true });
+        const files = (0, glob_1.globSync)('**/*', { absolute: false, cwd: templatePath });
         try {
             for (const fileName of files) {
                 const filePath = path.join(templatePath, fileName);
@@ -54,7 +54,7 @@ const generateTemplateSteps = (templateFolder) => {
                     (0, fs_1.mkdirSync)(targetDir, { recursive: true });
                 }
                 if ((0, fs_1.statSync)(filePath).isDirectory()) {
-                    const folderPath = filePath.replace(templatePath, '');
+                    const folderPath = path.basename(filePath);
                     (0, fs_1.mkdirSync)(path.join(rootDir, folderPath), { recursive: true });
                     continue;
                 }

package/dist/cjs/create/templates/generate.ts

@@ -8,7 +8,7 @@ export type Generator = (rootDir: string, context: CliContext) => Promise<void>
 export const generateTemplateSteps = (templateFolder: string): Generator => {
   return async (rootDir: string, context: CliContext): Promise<void> => {
     const templatePath = path.join(__dirname, templateFolder)
-    const files = globSync('**/*', { absolute: false, cwd: templatePath, dot: true })
+    const files = globSync('**/*', { absolute: false, cwd: templatePath })
 
     try {
       for (const fileName of files) {
@@ -24,7 +24,7 @@ export const generateTemplateSteps = (templateFolder: string): Generator => {
         }
 
         if (statSync(filePath).isDirectory()) {
-          const folderPath = filePath.replace(templatePath, '')
+          const folderPath = path.basename(filePath)
           mkdirSync(path.join(rootDir, folderPath), { recursive: true })
           continue
         }

package/dist/cjs/create/templates/nodejs/services/pet-store.ts.txt

@@ -0,0 +1,29 @@
+import { Order, Pet } from './types'
+
+export const petStoreService = {
+  createPet: async (pet: Omit<Pet, 'id'>): Promise<Pet> => {
+    const response = await fetch('https://petstore.swagger.io/v2/pet', {
+      method: 'POST',
+      body: JSON.stringify({
+        name: pet?.name ?? '',
+        photoUrls: [pet?.photoUrl ?? ''],
+        status: 'available',
+      }),
+      headers: { 'Content-Type': 'application/json' },
+    })
+    return response.json()
+  },
+  createOrder: async (order: Omit<Order, 'id'>): Promise<Order> => {
+    const response = await fetch('https://petstore.swagger.io/v2/store/order', {
+      method: 'POST',
+      body: JSON.stringify({
+        quantity: order?.quantity ?? 1,
+        petId: 1,
+        shipDate: order?.shipDate ?? new Date().toISOString(),
+        status: order?.status ?? 'placed',
+      }),
+      headers: { 'Content-Type': 'application/json' },
+    })
+    return response.json()
+  },
+}

package/dist/cjs/create/templates/nodejs/steps/{petstore/api.step.ts-features.json.txt → api.step.ts-features.json.txt}

@@ -4,7 +4,7 @@
     "title": "Step Configuration",
     "description": "All steps should have a defined configuration, this is how you define the step's behavior and how it will be triggered.",
     "lines": [
-      "5-29"
+      "6-30"
     ]
   },
   {
@@ -12,7 +12,7 @@
     "title": "API Step",
     "description": "Definition of an API endpoint",
     "lines": [
-      "11-12"
+      "12-13"
     ]
   },
   {
@@ -20,7 +20,7 @@
     "title": "Request body",
     "description": "Definition of the expected request body. Motia will automatically generate types based on this schema.",
     "lines": [
-      "13-24"
+      "14-25"
     ]
   },
   {
@@ -28,7 +28,7 @@
     "title": "Response Payload",
     "description": "Definition of the expected response payload, Motia will generate the types automatically based on this schema. This is also important to create the Open API spec later.",
     "lines": [
-      "25-27"
+      "26-28"
     ]
   },
   {
@@ -36,8 +36,8 @@
     "title": "Emits",
     "description": "We can define the events that this step will emit, this is how we can trigger other Motia Steps.",
     "lines": [
-      "28",
-      "38-45"
+      "29",
+      "39-46"
     ]
   },
   {
@@ -45,7 +45,7 @@
     "title": "Handler",
     "description": "The handler is the function that will be executed when the step is triggered. This one receives the request body and emits events.",
     "lines": [
-      "31-49"
+      "32-50"
     ]
   },
   {
@@ -53,7 +53,7 @@
     "title": "Logger",
     "description": "The logger is a utility that allows you to log messages to the console. It is available in the handler function. We encourage you to use it instead of console.log. It will automatically be tied to the trace id of the request.",
     "lines": [
-      "32"
+      "33"
     ]
   },
   {
@@ -61,7 +61,7 @@
     "title": "HTTP Response",
     "description": "The handler can return a response to the client. This is how we can return a response to the client. It must comply with the responseSchema defined in the step configuration.",
     "lines": [
-      "48"
+      "49"
     ]
   }
 ]

package/dist/{esm/create/templates/nodejs/steps/petstore → cjs/create/templates/nodejs/steps}/api.step.ts.txt

@@ -1,6 +1,7 @@
 import { ApiRouteConfig, Handlers } from 'motia'
 import { z } from 'zod'
-import { petStoreService, petSchema } from '../../src/services/pet-store'
+import { petStoreService } from '../services/pet-store'
+import { petSchema } from '../services/types'
 
 export const config: ApiRouteConfig = {
   type: 'api',

package/dist/cjs/create/templates/nodejs/steps/{petstore/process-food-order.step.ts.txt → process-food-order.step.ts.txt}

@@ -1,6 +1,6 @@
 import { EventConfig, Handlers } from 'motia'
 import { z } from 'zod'
-import { petStoreService } from '../../src/services/pet-store'
+import { petStoreService } from '../services/pet-store'
 
 export const config: EventConfig = {
   type: 'event',

package/dist/cjs/cursor-rules/dot-files/.claude/CLAUDE.md

@@ -0,0 +1,467 @@
+# Motia Framework Development Assistant
+
+You are helping develop a **Motia project** - a unified backend framework that uses event-driven architecture with multiple programming languages.
+
+## Core Motia Concepts
+
+### Steps Architecture
+
+- **Steps** are the fundamental building blocks - each has `config` and `handler`
+- **API Steps**: HTTP endpoints (`type: 'api'`)
+- **Event Steps**: Event processors (`type: 'event'`)
+- **Cron Steps**: Scheduled tasks (`type: 'cron'`)
+- **Stream Steps**: Real-time data (`type: 'stream'`)
+- **NOOP Steps**: Workflow routing (`type: 'noop'`)
+
+### Event-Driven Communication
+
+- Steps communicate via `emit({ topic: 'event-name', data: {...} })`
+- Subscribe to events: `subscribes: ['topic-name']` in config
+- Creates loose coupling and parallel execution
+
+### State Management
+
+- Persistent state via `state.set(group, key, value)` and `state.get(group, key)`
+- State is scoped by groups ('orders', 'users', etc.) and keys
+- Supports trace-scoped and global persistence
+
+## File Structure
+
+```
+steps/              # All step implementations
+├── *.step.ts      # Step files (config + handler)
+├── *-features.json # Tutorial/workbench metadata
+services/          # Shared business logic
+types.d.ts         # Auto-generated types from step configs
+motia-workbench.json # Visual flow configuration
+```
+
+## Step Implementation Patterns
+
+Motia supports **multiple programming languages** in the same project. Choose the best language for each task:
+
+- **TypeScript/JavaScript**: APIs, web logic, real-time features
+- **Python**: AI/ML, data science, image processing, analytics
+- **Ruby**: Reports, data exports, file processing, templating
+
+### TypeScript API Step
+
+```typescript
+import { z } from 'zod'
+import type { ApiRouteConfig, Handlers } from '@motia/core'
+
+export const config: ApiRouteConfig = {
+  type: 'api',
+  name: 'CreateOrder',
+  method: 'POST',
+  path: '/orders',
+  bodySchema: z.object({
+    productId: z.string(),
+    quantity: z.number(),
+  }),
+  emits: ['order.created'],
+  flows: ['ecommerce'],
+}
+
+export const handler: Handlers['CreateOrder'] = async (req, { logger, emit, state, traceId }) => {
+  const order = { id: crypto.randomUUID(), ...req.body, createdAt: new Date() }
+  await state.set('orders', order.id, order)
+  await emit({ topic: 'order.created', data: order })
+  return { status: 201, body: order }
+}
+```
+
+### JavaScript Event Step
+
+```javascript
+// steps/process-payment.step.js
+exports.config = {
+  type: 'event',
+  name: 'ProcessPayment',
+  subscribes: ['order.created'],
+  emits: ['payment.processed', 'payment.failed'],
+  input: {
+    id: 'string',
+    amount: 'number',
+    currency: 'string',
+  },
+}
+
+exports.handler = async (order, { logger, emit, state }) => {
+  try {
+    logger.info('Processing payment', { orderId: order.id })
+
+    // Simulate payment processing
+    const paymentResult = await processPayment(order)
+
+    await state.set('payments', order.id, paymentResult)
+    await emit({
+      topic: 'payment.processed',
+      data: { orderId: order.id, paymentId: paymentResult.id },
+    })
+  } catch (error) {
+    logger.error('Payment failed', { orderId: order.id, error: error.message })
+    await emit({ topic: 'payment.failed', data: { orderId: order.id, error: error.message } })
+  }
+}
+```
+
+### Python AI/ML Event Step
+
+```python
+# steps/analyze_sentiment.step.py
+import asyncio
+from transformers import pipeline
+
+config = {
+    "type": "event",
+    "name": "AnalyzeSentiment",
+    "subscribes": ["review.submitted"],
+    "emits": ["sentiment.analyzed"],
+    "input": {
+        "reviewId": "string",
+        "text": "string",
+        "userId": "string"
+    }
+}
+
+# Initialize ML model
+sentiment_analyzer = pipeline("sentiment-analysis")
+
+async def handler(review_data, context):
+    logger = context["logger"]
+    emit = context["emit"]
+    state = context["state"]
+
+    try:
+        logger.info(f"Analyzing sentiment for review {review_data['reviewId']}")
+
+        # Run sentiment analysis
+        result = sentiment_analyzer(review_data["text"])
+        sentiment_score = result[0]["score"]
+        sentiment_label = result[0]["label"]
+
+        analysis = {
+            "reviewId": review_data["reviewId"],
+            "sentiment": sentiment_label,
+            "confidence": sentiment_score,
+            "analyzedAt": datetime.now().isoformat()
+        }
+
+        await state.set("sentiment_analyses", review_data["reviewId"], analysis)
+        await emit({
+            "topic": "sentiment.analyzed",
+            "data": analysis
+        })
+
+    except Exception as error:
+        logger.error(f"Sentiment analysis failed: {str(error)}")
+        await emit({
+            "topic": "analysis.failed",
+            "data": {"reviewId": review_data["reviewId"], "error": str(error)}
+        })
+```
+
+### Python Data Processing Step
+
+```python
+# steps/generate_analytics.step.py
+import pandas as pd
+import numpy as np
+from datetime import datetime, timedelta
+
+config = {
+    "type": "cron",
+    "name": "GenerateAnalytics",
+    "cron": "0 0 * * 1",  # Weekly on Monday
+    "emits": ["analytics.generated"]
+}
+
+async def handler(context):
+    logger = context["logger"]
+    emit = context["emit"]
+    state = context["state"]
+
+    try:
+        # Fetch all orders from state
+        orders_data = await state.get_group("orders")
+
+        if not orders_data:
+            logger.info("No orders data available")
+            return
+
+        # Convert to pandas DataFrame for analysis
+        df = pd.DataFrame(list(orders_data.values()))
+        df['createdAt'] = pd.to_datetime(df['createdAt'])
+
+        # Generate analytics
+        last_week = datetime.now() - timedelta(days=7)
+        recent_orders = df[df['createdAt'] >= last_week]
+
+        analytics = {
+            "totalOrders": len(df),
+            "weeklyOrders": len(recent_orders),
+            "averageOrderValue": float(df['amount'].mean()) if 'amount' in df else 0,
+            "topProducts": df['productId'].value_counts().head(5).to_dict(),
+            "generatedAt": datetime.now().isoformat()
+        }
+
+        await state.set("analytics", "weekly", analytics)
+        await emit({"topic": "analytics.generated", "data": analytics})
+
+        logger.info("Analytics generated successfully")
+
+    except Exception as error:
+        logger.error(f"Analytics generation failed: {str(error)}")
+```
+
+### Ruby Report Generation Step
+
+```ruby
+# steps/generate_report.step.rb
+require 'csv'
+require 'json'
+
+def config
+  {
+    type: 'event',
+    name: 'GenerateReport',
+    subscribes: ['analytics.generated'],
+    emits: ['report.generated'],
+    input: {
+      totalOrders: 'number',
+      weeklyOrders: 'number',
+      topProducts: 'object'
+    }
+  }
+end
+
+def handler(analytics_data, context)
+  logger = context[:logger]
+  emit = context[:emit]
+  state = context[:state]
+
+  begin
+    logger.info("Generating CSV report from analytics")
+
+    # Generate CSV report
+    csv_data = CSV.generate do |csv|
+      csv << ['Metric', 'Value']
+      csv << ['Total Orders', analytics_data['totalOrders']]
+      csv << ['Weekly Orders', analytics_data['weeklyOrders']]
+      csv << ['Average Order Value', analytics_data['averageOrderValue']]
+
+      # Add top products
+      analytics_data['topProducts'].each do |product, count|
+        csv << ["Product #{product}", count]
+      end
+    end
+
+    # Generate HTML report
+    html_report = generate_html_template(analytics_data)
+
+    report = {
+      id: SecureRandom.uuid,
+      csv_data: csv_data,
+      html_report: html_report,
+      generated_at: Time.now.iso8601
+    }
+
+    state.set('reports', report[:id], report)
+    emit.call(topic: 'report.generated', data: report)
+
+    logger.info("Report generated successfully", report_id: report[:id])
+
+  rescue => error
+    logger.error("Report generation failed", error: error.message)
+    emit.call(topic: 'report.failed', data: { error: error.message })
+  end
+end
+
+private
+
+def generate_html_template(data)
+  <<~HTML
+    <html>
+    <head><title>Analytics Report</title></head>
+    <body>
+      <h1>Weekly Analytics Report</h1>
+      <p>Total Orders: #{data['totalOrders']}</p>
+      <p>Weekly Orders: #{data['weeklyOrders']}</p>
+      <p>Generated: #{Time.now.strftime('%Y-%m-%d %H:%M:%S')}</p>
+    </body>
+    </html>
+  HTML
+end
+```
+
+## Development Commands
+
+```bash
+# Start development server with workbench UI
+npm run dev
+
+# Run specific step
+motia run step-name
+
+# Build for production
+motia build
+```
+
+## Code Standards
+
+### Multi-Language File Naming
+
+- **TypeScript**: `step-name.step.ts`
+- **JavaScript**: `step-name.step.js`
+- **Python**: `step_name.step.py`
+- **Ruby**: `step-name.step.rb`
+
+### Language-Specific Patterns
+
+#### TypeScript/JavaScript
+
+- Use Zod schemas for validation (TypeScript) or simple objects (JavaScript)
+- Leverage auto-generated types from `types.d.ts` (TypeScript only)
+- Use `async/await` for all async operations
+- Export `config` and `handler` using ES6 modules (TypeScript) or CommonJS (JavaScript)
+
+#### Python
+
+- Use dictionary for config with snake_case keys
+- Use `async def handler()` for async operations
+- Access context via dictionary: `context["logger"]`, `context["emit"]`
+- Use type hints where helpful for clarity
+- Follow PEP 8 naming conventions
+
+#### Ruby
+
+- Use method `config` returning a hash
+- Use method `handler(input, context)`
+- Access context via hash: `context[:logger]`, `context[:emit]`
+- Follow Ruby naming conventions (snake_case)
+- Use proper exception handling with `rescue`
+
+### Universal Naming Conventions
+
+- Step names: `CamelCase` across all languages
+- Topics: `category.action` (e.g., `order.created`, `user.updated`)
+- State groups: `plural-noun` (e.g., `orders`, `users`)
+- File names follow language conventions but descriptive
+
+### Error Handling by Language
+
+#### TypeScript/JavaScript
+
+```typescript
+try {
+  // Step logic
+} catch (error) {
+  logger.error('Operation failed', { error: error.message, traceId })
+  // For API steps: return error response
+  // For Event steps: emit error event or rethrow
+}
+```
+
+#### Python
+
+```python
+try:
+    # Step logic
+    pass
+except Exception as error:
+    logger.error(f"Operation failed: {str(error)}")
+    # Emit error event or re-raise
+    await emit({"topic": "error.occurred", "data": {"error": str(error)}})
+```
+
+#### Ruby
+
+```ruby
+begin
+  # Step logic
+rescue => error
+  logger.error("Operation failed", error: error.message)
+  # Emit error event or re-raise
+  emit.call(topic: 'error.occurred', data: { error: error.message })
+end
+```
+
+### State Management Best Practices
+
+- Use semantic group names for state organization
+- Store complex objects, not just primitives
+- Consider trace-scoped vs global state based on use case
+- Clean up unused state in cron jobs
+
+## Testing & Debugging
+
+### Workbench Features
+
+- Visual flow representation and editing
+- API endpoint testing with real data
+- Real-time logging and tracing
+- State inspection and management
+- Tutorial system integration
+
+### Logging
+
+```typescript
+logger.info('Processing started', { userId, traceId })
+logger.error('Validation failed', { errors, input, traceId })
+```
+
+## Project-Specific Context
+
+This project implements a **pet store ordering system** with:
+
+- API endpoint for pet creation and food orders
+- Event processing for order fulfillment
+- Notification system for order updates
+- Scheduled auditing for overdue orders
+
+When working on this codebase:
+
+- Follow the existing event flow patterns
+- Use the established state groups (`orders`, `pets`)
+- Maintain the tutorial-friendly structure for the workbench
+- Test changes using the development workbench UI
+
+## Multi-Language Workflow Examples
+
+### Complete E-commerce Flow
+
+```
+TypeScript API → JavaScript Payment → Python ML → Ruby Reports
+```
+
+1. **API Endpoint** (TypeScript): Handle orders with validation
+2. **Payment Processing** (JavaScript): Fast payment logic
+3. **Recommendation Engine** (Python): ML-based product recommendations
+4. **Report Generation** (Ruby): Beautiful HTML/PDF reports
+
+### AI-Powered Content Pipeline
+
+```
+JavaScript API → Python AI → Ruby Templates → TypeScript Notifications
+```
+
+1. **Content Upload** (JavaScript): Quick file handling
+2. **AI Processing** (Python): Image recognition, text analysis
+3. **Template Generation** (Ruby): Dynamic content templates
+4. **Real-time Updates** (TypeScript): WebSocket notifications
+
+## Common Tasks
+
+- **Adding API endpoints**: Create API step in TypeScript/JavaScript with validation
+- **Processing background jobs**: Create event steps in the most suitable language
+- **AI/ML tasks**: Use Python steps with appropriate libraries
+- **Data processing**: Use Python for analytics, Ruby for reports
+- **Scheduled maintenance**: Use cron steps for periodic cleanup and auditing
+- **Real-time features**: Use TypeScript/JavaScript for WebSocket handling
+
+## Resources
+
+- Local development: `npm run dev` → http://localhost:5173
+- Motia documentation: https://motia.dev/docs
+- Workbench tutorials: Available in development mode