@dura-run/cli 0.1.5 → 0.2.1

package/skills/dura-develop.md

@@ -0,0 +1,379 @@
+# dura.run — Development Guide
+
+> This skill teaches an AI agent how to scaffold projects, write automation handlers, use SDK globals, and run locally with `dura dev`.
+
+## Scaffolding a New Project
+
+### `dura new <name>` — Create a New Project
+
+Creates a new directory with the full project skeleton:
+
+```bash
+# Create a project called "my-api"
+dura new my-api
+
+# Create in a specific parent directory
+dura new my-api --dir ~/projects
+
+# Create from a template
+dura new my-api --template rest-api --org org_abc123
+```
+
+**What gets created:**
+
+```
+my-api/
+├── dura.json           # Manifest with a "hello" automation
+├── routes/
+│   └── hello.ts        # Starter HTTP handler
+├── jobs/               # Empty directory for cron/event handlers
+└── .gitignore          # Ignores .env.local, node_modules, .dura, dist
+```
+
+**Project name rules:** Must start with a letter, can contain letters, numbers, hyphens, and underscores.
+
+### `dura init` — Initialize an Existing Directory
+
+Use `dura init` when you already have a directory and want to turn it into a dura project:
+
+```bash
+cd my-existing-project
+dura init
+```
+
+This creates `dura.json`, starter files, and installs AI agent skills.
+
+## Writing Automation Handlers
+
+### Handler Signature
+
+Every automation handler is a default-exported async function:
+
+```typescript
+import type { DuraRequest, DuraResponse } from "@dura/sdk";
+
+export default async function handler(req: DuraRequest): Promise<DuraResponse> {
+  // Your logic here
+  return {
+    status: 200,
+    headers: { "content-type": "application/json" },
+    body: { result: "success" },
+  };
+}
+```
+
+### DuraRequest Shape
+
+The `req` object contains:
+
+```typescript
+interface DuraRequest {
+  method: string;           // HTTP method (GET, POST, etc.)
+  path: string;             // Request path
+  headers: Record<string, string>;
+  query: Record<string, string>;
+  body: unknown;            // Parsed JSON body (or raw string)
+}
+```
+
+### DuraResponse Shape
+
+Return an object with:
+
+```typescript
+interface DuraResponse {
+  status: number;                       // HTTP status code
+  headers?: Record<string, string>;     // Response headers
+  body?: unknown;                       // JSON-serializable response body
+}
+```
+
+### Example: REST API Handler
+
+```typescript
+import type { DuraRequest, DuraResponse } from "@dura/sdk";
+
+export default async function handler(req: DuraRequest): Promise<DuraResponse> {
+  if (req.method === "GET") {
+    const users = await dura.kv.get("users") as string[] ?? [];
+    return {
+      status: 200,
+      headers: { "content-type": "application/json" },
+      body: { users },
+    };
+  }
+
+  if (req.method === "POST") {
+    const { name, email } = req.body as { name: string; email: string };
+    if (!name || !email) {
+      return { status: 400, body: { error: "name and email are required" } };
+    }
+
+    const users = await dura.kv.get("users") as string[] ?? [];
+    users.push(name);
+    await dura.kv.set("users", users);
+
+    dura.log.info("User created", { name, email });
+    return { status: 201, body: { created: true, name } };
+  }
+
+  return { status: 405, body: { error: "Method not allowed" } };
+}
+```
+
+### Example: Cron Job Handler
+
+```typescript
+import type { DuraRequest, DuraResponse } from "@dura/sdk";
+
+export default async function handler(req: DuraRequest): Promise<DuraResponse> {
+  dura.log.info("Starting daily cleanup");
+
+  const response = await dura.fetch("https://api.example.com/stale-records", {
+    method: "DELETE",
+    headers: { Authorization: `Bearer ${dura.env.get("API_TOKEN")}` },
+  });
+
+  const result = await response.json();
+  dura.log.info("Cleanup complete", { deleted: result.count });
+
+  return { status: 200, body: { deleted: result.count } };
+}
+```
+
+### Example: Chained Automation
+
+```typescript
+// routes/process-order.ts
+import type { DuraRequest, DuraResponse } from "@dura/sdk";
+
+export default async function handler(req: DuraRequest): Promise<DuraResponse> {
+  const order = req.body as { orderId: string; items: string[] };
+
+  // Process the order...
+  dura.log.info("Order processed", { orderId: order.orderId });
+
+  // Trigger the notification automation (fire-and-forget)
+  await dura.trigger("send-notification", {
+    type: "order_complete",
+    orderId: order.orderId,
+  });
+
+  // Or wait for the result
+  const result = await dura.triggerAndWait("calculate-shipping", {
+    items: order.items,
+  });
+
+  return { status: 200, body: { orderId: order.orderId, shipping: result?.body } };
+}
+```
+
+## SDK Globals Reference
+
+Inside automation handlers, the `dura` global object is always available. You do not need to import it — it is injected by the runtime.
+
+### `dura.log` — Structured Logging
+
+```typescript
+dura.log.debug("Debug message");
+dura.log.info("Processing request", { userId: "123" });
+dura.log.warn("Rate limit approaching", { current: 95, max: 100 });
+dura.log.error("Payment failed", { error: err.message, orderId });
+```
+
+All log calls accept `(message: string, data?: unknown)`. The `data` argument is included as structured metadata in log entries, searchable via `dura logs --filter`.
+
+### `dura.fetch` — HTTP Client
+
+```typescript
+// Works exactly like the standard fetch API
+const res = await dura.fetch("https://api.example.com/data", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ key: "value" }),
+});
+const data = await res.json();
+```
+
+In production, `dura.fetch` routes through the executor's network sandbox. In local dev (`dura dev`), it uses the standard `fetch` directly.
+
+### `dura.env` — Environment Variables
+
+```typescript
+const dbUrl = dura.env.get("DATABASE_URL");
+const apiKey = dura.env.get("STRIPE_SECRET_KEY");
+
+if (!dbUrl) {
+  dura.log.error("DATABASE_URL is not set");
+  return { status: 500, body: { error: "Configuration error" } };
+}
+```
+
+In local dev, env vars are loaded from `.env.local`. In production, they come from the environment's secret store (managed via `dura secrets`).
+
+### `dura.kv` — Key-Value Store
+
+```typescript
+// Set a value
+await dura.kv.set("user:123", { name: "Alice", role: "admin" });
+
+// Set with TTL (seconds)
+await dura.kv.set("session:abc", { token: "xyz" }, { ttl: 3600 });
+
+// Get a value
+const user = await dura.kv.get("user:123");
+
+// Check existence
+const exists = await dura.kv.has("user:123");
+
+// Delete
+await dura.kv.delete("user:123");
+
+// List keys by prefix
+const userKeys = await dura.kv.list("user:");
+
+// Atomic increment
+await dura.kv.incr("page-views", 1);
+```
+
+In local dev, KV is backed by an in-memory Map (resets when the dev server restarts). In production, it uses Redis.
+
+### `dura.trigger` / `dura.triggerAndWait` — Chain Automations
+
+```typescript
+// Fire-and-forget — trigger another automation without waiting
+await dura.trigger("send-email", { to: "user@example.com", subject: "Hello" });
+
+// Trigger and wait for the result
+const result = await dura.triggerAndWait("validate-address", {
+  street: "123 Main St",
+  city: "Springfield",
+});
+// result = { status: 200, body: { valid: true } }
+```
+
+## Local Development with `dura dev`
+
+### Starting the Dev Server
+
+```bash
+# Start in the current directory on port 3000 (default)
+dura dev
+
+# Specify a different directory or port
+dura dev --dir ./my-project --port 8080
+```
+
+### What `dura dev` Does
+
+1. **Reads `dura.json`** — discovers all automations and their triggers
+2. **Loads `.env.local`** — injects secrets into the dev environment
+3. **Starts HTTP server** — maps HTTP triggers to handler files
+4. **Starts cron scheduler** — schedules cron triggers locally
+5. **Starts file watcher** — watches `routes/`, `jobs/`, `lib/` for hot-reload
+6. **Installs SDK globals** — sets up `dura.log`, `dura.fetch`, `dura.env`, `dura.kv`, `dura.trigger`
+
+### Testing Locally
+
+Once the dev server is running:
+
+```bash
+# Test an HTTP handler
+curl http://localhost:3000/hello
+
+# Test a POST handler
+curl -X POST http://localhost:3000/webhook \
+  -H "Content-Type: application/json" \
+  -d '{"event": "user.created"}'
+
+# Manually trigger any automation
+dura run hello --project local
+```
+
+### Local Environment File
+
+Create `.env.local` in the project root for local secrets:
+
+```
+DATABASE_URL=postgres://localhost:5432/mydb
+API_TOKEN=sk_test_abc123
+SLACK_WEBHOOK_URL=https://hooks.slack.com/...
+```
+
+This file is gitignored by default. These values are accessible via `dura.env.get("DATABASE_URL")` in your handlers.
+
+## Registering Automations in `dura.json`
+
+### Adding an HTTP Automation
+
+```json
+{
+  "name": "get-users",
+  "entrypoint": "routes/users.ts",
+  "triggers": [
+    { "type": "http", "method": "GET", "path": "/users" }
+  ]
+}
+```
+
+### Adding a Cron Job
+
+```json
+{
+  "name": "daily-report",
+  "entrypoint": "jobs/daily-report.ts",
+  "triggers": [
+    { "type": "cron", "schedule": "0 9 * * *" }
+  ],
+  "config": {
+    "timeout": 60000,
+    "retries": 2
+  }
+}
+```
+
+### Adding a Chained Automation
+
+```json
+{
+  "name": "send-notification",
+  "entrypoint": "routes/notify.ts",
+  "triggers": [
+    { "type": "chain", "from": "process-order" }
+  ]
+}
+```
+
+### Adding a Manual-Only Automation
+
+```json
+{
+  "name": "migrate-data",
+  "entrypoint": "jobs/migrate.ts",
+  "triggers": [
+    { "type": "manual" }
+  ],
+  "config": {
+    "timeout": 120000,
+    "memory": 512
+  }
+}
+```
+
+### Project-Level Config
+
+Set defaults that apply to all automations:
+
+```json
+{
+  "name": "my-project",
+  "automations": [...],
+  "config": {
+    "timeout": 15000,
+    "memory": 128,
+    "concurrency": 10
+  }
+}
+```
+
+Per-automation `config` overrides project-level `config`.

package/skills/dura-overview.md

@@ -0,0 +1,196 @@
+# dura.run — Platform Overview
+
+> This skill teaches an AI agent the core concepts, project structure, and deployment lifecycle of the dura.run automation platform.
+
+## What Is dura.run?
+
+dura.run is a managed automation platform where developers build, deploy, and debug JavaScript/TypeScript automations. Automations run in secure V8 isolates on the dura cloud — you write handler functions, define triggers, and dura handles execution, scaling, logging, and monitoring.
+
+Think of it as "serverless functions with built-in observability and an automation-first developer experience."
+
+## Core Concepts
+
+### Automations
+
+An automation is a single unit of work — a TypeScript function that receives a request and returns a response. Each automation has:
+
+- **Name** — unique identifier within a project (e.g., `sync-users`, `process-payment`)
+- **Entrypoint** — path to the handler file (e.g., `routes/sync-users.ts`)
+- **Triggers** — how the automation gets invoked (HTTP, cron, event, manual, chain)
+- **Config** — optional overrides for timeout, memory, concurrency, and retries
+
+### Triggers
+
+Automations can be triggered in five ways:
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `http` | Incoming HTTP request at a specific path and method | `GET /api/users` |
+| `cron` | Scheduled execution on a cron expression | `0 */6 * * *` (every 6 hours) |
+| `event` | Fired when an external event source emits a matching event | Webhook relay events |
+| `manual` | Triggered explicitly via CLI (`dura run`) or API | One-off tasks, debugging |
+| `chain` | Triggered by another automation completing | Multi-step pipelines |
+
+### Projects
+
+A project is a collection of related automations deployed together. Every project has:
+
+- An organization owner
+- A `dura.json` manifest defining all automations and their triggers
+- One or more environments (production, staging, preview, custom)
+- A deployment history with rollback capability
+
+### Organizations
+
+Organizations own projects and manage team access. Each user gets a personal workspace (organization) on signup. Organizations have:
+
+- Members with roles: `owner`, `admin`, `member`
+- API keys scoped to the org
+- Usage quotas and billing (free, pro, enterprise plans)
+
+### Environments
+
+Environments isolate deployments. A project can have multiple environments:
+
+- **production** — live traffic, default deployment target
+- **staging** — pre-production testing
+- **preview** — ephemeral environments for branch previews
+- **custom** — user-defined environments
+
+Each environment has its own secrets, deployment state, and URL.
+
+## Project Structure
+
+A dura project is a directory with this layout:
+
+```
+my-project/
+├── dura.json          # Project manifest — defines automations and triggers
+├── routes/            # HTTP-triggered automation handlers
+│   ├── hello.ts
+│   └── users.ts
+├── jobs/              # Cron and event-triggered handlers
+│   └── cleanup.ts
+├── lib/               # Shared utilities (imported by handlers)
+│   └── db.ts
+├── .env.local         # Local secrets (never committed)
+├── .gitignore
+└── node_modules/
+```
+
+### `dura.json` — The Project Manifest
+
+The manifest is the single source of truth for what a project contains. Example:
+
+```json
+{
+  "name": "my-project",
+  "automations": [
+    {
+      "name": "hello",
+      "entrypoint": "routes/hello.ts",
+      "triggers": [
+        { "type": "http", "method": "GET", "path": "/hello" }
+      ]
+    },
+    {
+      "name": "sync-users",
+      "entrypoint": "jobs/sync-users.ts",
+      "triggers": [
+        { "type": "cron", "schedule": "0 */6 * * *" }
+      ],
+      "config": {
+        "timeout": 30000,
+        "retries": 3
+      }
+    },
+    {
+      "name": "process-webhook",
+      "entrypoint": "routes/webhook.ts",
+      "triggers": [
+        { "type": "http", "method": "POST", "path": "/webhook" }
+      ]
+    }
+  ],
+  "env": [
+    { "name": "DATABASE_URL", "required": true, "description": "Postgres connection string" },
+    { "name": "SLACK_TOKEN", "required": false }
+  ],
+  "config": {
+    "timeout": 10000,
+    "memory": 128
+  }
+}
+```
+
+**Manifest fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Project name — letters, numbers, hyphens, underscores |
+| `automations` | Yes | Array of automation definitions (at least one) |
+| `automations[].name` | Yes | Automation name — must start with a letter |
+| `automations[].entrypoint` | Yes | Path to the handler file (relative to project root) |
+| `automations[].triggers` | No | Array of trigger configurations |
+| `automations[].config` | No | Per-automation overrides (timeout, memory, concurrency, retries) |
+| `env` | No | Declared environment variables the project uses |
+| `config` | No | Project-level defaults for timeout, memory, concurrency |
+
+### Handler File Format
+
+Every handler file must export a default async function:
+
+```typescript
+import type { DuraRequest, DuraResponse } from "@dura/sdk";
+
+export default async function handler(req: DuraRequest): Promise<DuraResponse> {
+  return {
+    status: 200,
+    headers: { "content-type": "application/json" },
+    body: { message: "Hello from Dura!" },
+  };
+}
+```
+
+## Deployment Lifecycle
+
+1. **Develop** — Write handlers locally, test with `dura dev`
+2. **Bundle** — `dura deploy` bundles all automations into a deployable archive
+3. **Upload** — Bundle is uploaded to Dura's object storage via a presigned URL
+4. **Validate** — The control plane validates the manifest and bundle integrity
+5. **Activate** — If validation passes, the deployment becomes active
+6. **Execute** — Incoming triggers invoke automation handlers in V8 isolates
+7. **Monitor** — Execution logs, metrics, and diagnostics are available in real time
+
+### Deployment States
+
+| Status | Meaning |
+|--------|---------|
+| `pending` | Deployment created, awaiting bundle upload |
+| `building` | Bundle uploaded, being processed |
+| `deploying` | Validation passed, activating |
+| `active` | Live — serving traffic |
+| `failed` | Validation or activation failed |
+| `rolled_back` | Was active, replaced by a rollback |
+| `superseded` | Was active, replaced by a newer deployment |
+
+## CLI Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `dura login` | Authenticate with the dura control plane |
+| `dura init` | Initialize a dura project in the current directory |
+| `dura new <name>` | Scaffold a new dura project in a new directory |
+| `dura dev` | Start local development server with hot-reload |
+| `dura deploy` | Bundle and deploy to an environment |
+| `dura run <name>` | Manually trigger an automation |
+| `dura logs` | View execution logs |
+| `dura diagnose` | AI-powered root cause analysis of failed executions |
+| `dura replay <id>` | Replay a past execution |
+| `dura test` | Run the project test suite |
+| `dura rollback` | Revert to a previous deployment |
+| `dura env` | Manage project environments |
+| `dura secrets` | Manage project secrets |
+| `dura deployments` | View deployment history |
+| `dura status` | Show project and automation status |
+| `dura config` | Manage CLI configuration |