@dura-run/cli 0.1.5 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dura-run/cli",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "CLI for the dura.run managed automation platform",
   "license": "MIT",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist/dura.js",
+    "skills/",
     "README.md",
     "LICENSE"
   ],
@@ -43,8 +44,12 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   },
+  "dependencies": {
+    "tsx": "^4.21.0"
+  },
   "devDependencies": {
     "@dura/shared": "workspace:*",
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "esbuild": "^0.28.0"
   }
 }

package/skills/dura-debug.md

@@ -0,0 +1,360 @@
+# Dura.run — Debugging Guide
+
+> This skill teaches an AI agent how to trigger automations, read logs, run diagnostics, replay executions, and use snapshot tests for debugging and quality assurance.
+
+## Triggering Automations
+
+### `dura run <name>` — Manual Trigger
+
+Manually trigger any automation in your project:
+
+```bash
+# Trigger the "hello" automation
+dura run hello --project proj_abc123
+
+# Trigger with a JSON payload
+dura run process-webhook --project proj_abc123 \
+  --payload '{"event": "user.created", "userId": "u_456"}'
+```
+
+**Output:**
+
+```
+executionId  exec_abc123
+status       completed
+duration     142ms
+```
+
+This is useful for:
+- Testing automations without waiting for their trigger
+- Debugging failed cron jobs by re-running them manually
+- Running one-off automations with `{ "type": "manual" }` triggers
+
+## Reading Logs
+
+### `dura logs` — View Execution Logs
+
+```bash
+# List recent executions
+dura logs --project proj_abc123
+
+# View logs for a specific execution
+dura logs exec_abc123 --project proj_abc123
+
+# Filter by log level
+dura logs --project proj_abc123 --filter 'level=error'
+
+# Filter by automation name
+dura logs --project proj_abc123 --filter 'automation=sync-users'
+
+# Text search in log messages
+dura logs --project proj_abc123 --filter 'text=payment'
+
+# Structured field query
+dura logs --project proj_abc123 --filter 'field.orderId=ord_789'
+
+# Logs from the last hour
+dura logs --project proj_abc123 --last 1h
+
+# Logs from the last 7 days
+dura logs --project proj_abc123 --last 7d
+```
+
+### `dura logs -f` — Live Tail
+
+Stream logs in real time:
+
+```bash
+# Tail all logs
+dura logs --project proj_abc123 -f
+
+# Tail only errors
+dura logs --project proj_abc123 -f --filter 'level=error'
+
+# Tail a specific automation
+dura logs --project proj_abc123 -f --filter 'automation=process-webhook'
+```
+
+Live tail uses WebSocket to stream log entries as they happen. Press `Ctrl+C` to stop.
+
+### Understanding Log Entries
+
+Each log entry includes:
+
+| Field | Description |
+|-------|-------------|
+| `timestamp` | When the log was emitted |
+| `level` | `debug`, `info`, `warn`, or `error` |
+| `message` | The log message string |
+| `data` | Optional structured metadata (from `dura.log.info("msg", data)`) |
+| `executionId` | Which execution produced this log |
+| `automationName` | Which automation was running |
+
+### Writing Effective Logs
+
+Structure your logs for easy debugging:
+
+```typescript
+// Bad — hard to search and filter
+dura.log.info("done");
+
+// Good — descriptive message with structured data
+dura.log.info("User sync completed", {
+  syncedCount: 42,
+  failedCount: 3,
+  durationMs: 1523,
+  source: "salesforce",
+});
+```
+
+Use log levels consistently:
+
+- **debug** — Detailed diagnostic info (hidden by default in production)
+- **info** — Normal operational events (request handled, job completed)
+- **warn** — Something unexpected but recoverable (retry triggered, rate limit approaching)
+- **error** — Something failed and needs attention (API call failed, validation error)
+
+## AI-Powered Diagnostics
+
+### `dura diagnose` — Root Cause Analysis
+
+When an execution fails, `dura diagnose` uses AI to analyze the failure, identify the root cause, and suggest a fix:
+
+```bash
+# Diagnose a specific execution
+dura diagnose exec_abc123 --project proj_abc123
+
+# Diagnose the most recent failure
+dura diagnose --latest --project proj_abc123
+
+# Include a wider lookback window for pattern detection
+dura diagnose exec_abc123 --project proj_abc123 --lookback 48h
+
+# Force regeneration (ignore cached diagnosis)
+dura diagnose exec_abc123 --project proj_abc123 --force
+```
+
+**Output:**
+
+```
+Root Cause: External API timeout (87% confidence)
+
+  The handler at routes/sync-users.ts timed out waiting for a response from
+  https://api.salesforce.com/v2/users. The API returned HTTP 504 after 10.2s,
+  exceeding the automation's 10s timeout.
+
+Evidence:
+  • [log:14] dura.fetch("https://api.salesforce.com/v2/users") started at T+0.1s
+  • [log:15] No response received before timeout at T+10.0s
+  • [metric] p99 latency for this API endpoint: 8.7s (last 24h)
+
+Suggested Fix:
+  Increase the automation timeout and add a retry with exponential backoff.
+  File: dura.json
+  - "timeout": 10000
+  + "timeout": 30000
+
+Related: exec_abc121, exec_abc119 (same error)
+
+Prevention: Add circuit breaker logic for the Salesforce API call.
+```
+
+### Diagnosis Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--project <id>` | Project ID (required) | — |
+| `--latest` | Diagnose the most recent failed execution | — |
+| `--lookback <duration>` | Window for finding related failures (`24h`, `7d`) | `24h` |
+| `--force` | Regenerate diagnosis even if cached | `false` |
+
+## Replaying Executions
+
+### `dura replay <execution-id>` — Replay an Execution
+
+Re-run a past execution with its original inputs:
+
+```bash
+# Replay with original inputs
+dura replay exec_abc123 --project proj_abc123
+
+# Replay with a modified body
+dura replay exec_abc123 --project proj_abc123 \
+  --body '{"event": "user.updated", "userId": "u_456"}'
+
+# Dry run — show payload without executing
+dura replay exec_abc123 --project proj_abc123 --dry-run
+```
+
+**Use cases:**
+- Retry a failed execution after fixing a bug
+- Test a fix by replaying the exact input that caused a failure
+- Compare behavior between deployments
+
+### `dura replays <execution-id>` — List Replays
+
+View all replays of a specific execution:
+
+```bash
+dura replays exec_abc123 --project proj_abc123
+```
+
+## Snapshot Testing
+
+### `dura test --snapshots` — Snapshot Tests
+
+Snapshot tests record automation responses and compare future runs against the stored snapshots:
+
+```bash
+# Run snapshot tests
+dura test --snapshots
+
+# Update snapshots to match current output
+dura test --update-snapshots
+```
+
+### How Snapshot Tests Work
+
+1. **First run** — Executes each automation with test inputs and saves the response to `__snapshots__/*.snap.json`
+2. **Subsequent runs** — Executes again and compares the response to the stored snapshot
+3. **Mismatch** — If the response differs, the test fails and shows a diff
+4. **Update** — Use `--update-snapshots` to accept new output as the expected baseline
+
+### Snapshot File Location
+
+```
+my-project/
+├── routes/
+│   ├── hello.ts
+│   └── __snapshots__/
+│       └── hello.snap.json
+├── jobs/
+│   ├── cleanup.ts
+│   └── __snapshots__/
+│       └── cleanup.snap.json
+```
+
+## Running Tests
+
+### `dura test` — Full Test Suite
+
+```bash
+# Run all tests
+dura test
+
+# Run tests in a specific directory
+dura test --dir ./my-project
+
+# Run with snapshot mode
+dura test --snapshots
+
+# Update snapshots
+dura test --update-snapshots
+```
+
+### What `dura test` Does
+
+1. Sets `DURA_ENV=test` and `NODE_ENV=test`
+2. Loads `.env.local` secrets
+3. Discovers test files matching `*.test.{ts,js}` or `*.spec.{ts,js}`
+4. Spawns the test runner (vitest by default)
+
+### Writing Tests for Automations
+
+Create test files adjacent to your handlers:
+
+```typescript
+// routes/hello.test.ts
+import { describe, it, expect } from "vitest";
+
+// Import your handler directly
+import handler from "./hello";
+
+describe("hello handler", () => {
+  it("returns a greeting", async () => {
+    const response = await handler({
+      method: "GET",
+      path: "/hello",
+      headers: {},
+      query: {},
+      body: null,
+    });
+
+    expect(response.status).toBe(200);
+    expect(response.body).toEqual({ message: "Hello from Dura!" });
+  });
+});
+```
+
+## Debugging Workflow — Step by Step
+
+When an automation fails, follow this workflow:
+
+### 1. Check Recent Logs
+
+```bash
+dura logs --project proj_abc123 --filter 'level=error' --last 1h
+```
+
+### 2. Find the Failed Execution
+
+```bash
+dura logs --project proj_abc123 --filter 'level=error'
+# Note the execution ID from the output
+```
+
+### 3. View Full Execution Logs
+
+```bash
+dura logs exec_abc123 --project proj_abc123
+```
+
+### 4. Run AI Diagnosis
+
+```bash
+dura diagnose exec_abc123 --project proj_abc123
+```
+
+### 5. Fix and Replay
+
+After fixing the bug:
+
+```bash
+# Replay the failed execution to verify the fix
+dura replay exec_abc123 --project proj_abc123
+
+# Or redeploy and test
+dura deploy --project proj_abc123 --env staging
+dura run my-automation --project proj_abc123
+```
+
+### 6. Add a Test
+
+Write a test that reproduces the failure to prevent regressions:
+
+```typescript
+// routes/my-automation.test.ts
+it("handles empty payload gracefully", async () => {
+  const response = await handler({
+    method: "POST",
+    path: "/webhook",
+    headers: {},
+    query: {},
+    body: {},  // The input that caused the failure
+  });
+
+  expect(response.status).toBe(400);
+  expect(response.body).toHaveProperty("error");
+});
+```
+
+## JSON Output Mode
+
+All debugging commands support `--json` for machine-readable output:
+
+```bash
+dura run hello --project proj_abc123 --json
+dura logs --project proj_abc123 --json
+dura diagnose --latest --project proj_abc123 --json
+dura replay exec_abc123 --project proj_abc123 --json
+```

package/skills/dura-deploy.md

@@ -0,0 +1,272 @@
+# Dura.run — Deployment Guide
+
+> This skill teaches an AI agent how to deploy automations, manage deployments, handle rollbacks, and configure multi-environment workflows.
+
+## Deploying Your Project
+
+### `dura deploy` — Bundle and Deploy
+
+The deploy command handles the full pipeline: bundle, upload, validate, activate.
+
+```bash
+# Deploy to the default environment (production)
+dura deploy --project proj_abc123
+
+# Deploy to a specific environment
+dura deploy --project proj_abc123 --env staging
+
+# Deploy from a specific directory
+dura deploy --project proj_abc123 --dir ./my-project
+```
+
+**What happens during deploy:**
+
+1. **Bundle** — All automation entrypoints are bundled into a single archive
+2. **Upload** — The bundle is uploaded to Dura's object storage via presigned URL
+3. **Validate** — The control plane validates the manifest and bundle integrity
+4. **Activate** — If validation passes, the new deployment becomes `active`
+
+**Output:**
+
+```
+Bundling project...
+Bundle created: 42381 bytes
+Requesting upload URL...
+Deployment dep_xyz789 created
+Uploading bundle...
+Validating and activating...
+deploymentId  dep_xyz789
+status        active
+activatedAt   2026-04-05T14:30:00.000Z
+bundleSize    42381
+automations   3
+```
+
+### Deploy Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--project <id>` | Project ID (required) | — |
+| `--env <name>` | Target environment | `production` |
+| `--dir <path>` | Project directory | `.` (current dir) |
+| `--api-url <url>` | API base URL | From config |
+| `--token <token>` | Auth token | From config |
+
+### Authentication Requirement
+
+You must be logged in before deploying:
+
+```bash
+# Login first
+dura login
+
+# Or use an API key
+dura login --api-key dura_k_your_key_here
+```
+
+## Managing Deployments
+
+### `dura deployments list` — View Deployment History
+
+```bash
+dura deployments list --project proj_abc123
+```
+
+**Output:**
+
+```
+ID              STATUS      CREATED
+dep_xyz789      active      2026-04-05T14:30:00Z
+dep_xyz788      superseded  2026-04-04T10:15:00Z
+dep_xyz787      superseded  2026-04-03T09:00:00Z
+dep_xyz786      failed      2026-04-02T16:45:00Z
+```
+
+### `dura deployments get` — Deployment Details
+
+```bash
+dura deployments get --id dep_xyz789 --project proj_abc123
+```
+
+Shows detailed information about a specific deployment including status, bundle size, validation results, and activation timestamp.
+
+### `dura rollback` — Revert to a Previous Deployment
+
+```bash
+# Rollback to the previous deployment (auto-selected)
+dura rollback --project proj_abc123
+
+# Rollback to a specific deployment
+dura rollback --project proj_abc123 --to dep_xyz787
+```
+
+This deactivates the current deployment and reactivates the target. The current deployment's status becomes `rolled_back`.
+
+## Environment Management
+
+### `dura env create <name>` — Create an Environment
+
+```bash
+# Create a staging environment
+dura env create staging --project proj_abc123 --type staging
+
+# Create with options
+dura env create preview-pr-42 \
+  --project proj_abc123 \
+  --type preview \
+  --inherit-secrets staging \
+  --auto-deploy
+```
+
+### `dura env list` — List Environments
+
+```bash
+dura env list --project proj_abc123
+```
+
+**Output:**
+
+```
+NAME        TYPE        SLUG        AUTO-DEPLOY
+production  production  production  false
+staging     staging     staging     true
+preview-42  preview     preview-42  true
+```
+
+### `dura env delete <name>` — Delete an Environment
+
+```bash
+# Requires --confirm for safety
+dura env delete preview-42 --project proj_abc123 --confirm
+```
+
+### `dura env diff <env1> <env2>` — Compare Environments
+
+```bash
+dura env diff staging production --project proj_abc123
+```
+
+Shows differences in deployed version, secrets, and configuration between two environments.
+
+## Promoting Between Environments
+
+### `dura promote <source> <target>` — Promote a Deployment
+
+```bash
+# Promote staging deployment to production
+dura promote staging production --project proj_abc123
+
+# This deploys the currently active deployment from staging
+# into the production environment
+```
+
+The promote command is a safe way to move a tested deployment from one environment to another without re-building.
+
+## Canary Deployments
+
+### `dura canary status` — Check Canary Progress
+
+```bash
+dura canary status --project proj_abc123
+```
+
+Shows the active canary deployment progress including traffic split percentage, error rates, and health checks.
+
+### `dura canary complete` — Complete a Canary
+
+```bash
+dura canary complete --project proj_abc123
+```
+
+Shifts 100% of traffic to the canary version and marks it as the active deployment.
+
+### `dura canary rollback` — Rollback a Canary
+
+```bash
+# Requires --confirm
+dura canary rollback --project proj_abc123 --confirm
+```
+
+Reverts traffic to the previous deployment and cancels the canary.
+
+## Secrets Management
+
+### `dura secrets set` — Set a Secret
+
+```bash
+# Set a secret for the default environment
+dura secrets set DATABASE_URL "postgres://..." --project proj_abc123
+
+# Set for a specific environment
+dura secrets set API_KEY "sk_live_..." --project proj_abc123 --env production
+```
+
+### `dura secrets list` — List Secret Names
+
+```bash
+dura secrets list --project proj_abc123
+```
+
+Lists secret names (not values) for the project.
+
+### `dura secrets remove` — Remove a Secret
+
+```bash
+dura secrets remove OLD_API_KEY --project proj_abc123 --confirm
+```
+
+## Deployment Workflow — Step by Step
+
+Here is the recommended workflow for deploying a Dura project:
+
+### 1. Develop and Test Locally
+
+```bash
+dura dev                          # Start local dev server
+curl http://localhost:3000/hello  # Test your handlers
+dura test                         # Run the test suite
+```
+
+### 2. Deploy to Staging
+
+```bash
+dura deploy --project proj_abc123 --env staging
+```
+
+### 3. Verify in Staging
+
+```bash
+dura logs --project proj_abc123 --filter 'level=error'
+dura run hello --project proj_abc123  # Manual trigger test
+```
+
+### 4. Promote to Production
+
+```bash
+dura promote staging production --project proj_abc123
+```
+
+### 5. Monitor
+
+```bash
+dura logs --project proj_abc123 -f   # Live tail logs
+dura status --project proj_abc123    # Check health
+```
+
+### 6. Rollback If Needed
+
+```bash
+dura rollback --project proj_abc123
+```
+
+## JSON Output Mode
+
+All deployment commands support `--json` for machine-readable output:
+
+```bash
+dura deploy --project proj_abc123 --json
+dura deployments list --project proj_abc123 --json
+dura rollback --project proj_abc123 --json
+```
+
+JSON output wraps responses in `{ "status": "success", "data": {...} }` or `{ "status": "error", "code": "...", "message": "..." }`.