first commit

Author: mark-hingston

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npm run typecheck
+
+      - name: Run tests
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+      - name: Verify build output
+        run: |
+          test -f dist/index.js || (echo "Build output missing: dist/index.js" && exit 1)
+          test -f dist/index.d.ts || (echo "Build output missing: dist/index.d.ts" && exit 1)

.gitignore

@@ -0,0 +1,31 @@
+# Dependencies
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Build output
+dist/
+build/
+*.tsbuildinfo
+
+# Environment variables
+.env
+.env.local
+.env.*.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+coverage/
+.nyc_output/
+
+# Misc
+*.log
+.cache/

README.md

@@ -0,0 +1,300 @@
+# opencode-workflows
+
+Workflow automation plugin for OpenCode using the Mastra workflow engine. Define deterministic, multi-step processes that agents can trigger to perform complex tasks reliably.
+
+## Features
+
+- **Deterministic Automation**: Define rigid, multi-step processes (DAGs) in JSON
+- **Agentic Triggering**: Agents can call workflows as tools
+- **Hybrid Execution**: Mix shell commands, API calls, and LLM prompts
+- **Human-in-the-Loop**: Suspend workflows for human approval
+- **Parallel Execution**: Run independent steps concurrently
+
+## Installation
+
+```bash
+npm install opencode-workflows
+```
+
+## Configuration
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-workflows"]
+}
+```
+
+### Plugin Options
+
+```json
+{
+  "plugin": [
+    ["opencode-workflows", {
+      "workflowDirs": [".opencode/workflows"],
+      "dbPath": ".opencode/data/workflows.db",
+      "verbose": false
+    }]
+  ]
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `workflowDirs` | `string[]` | `[".opencode/workflows"]` | Directories to scan for workflow JSON files |
+| `dbPath` | `string` | `".opencode/data/workflows.db"` | Path to SQLite database for persisting workflow runs |
+| `verbose` | `boolean` | `false` | Enable verbose logging |
+
+### Persistence
+
+Workflow runs are automatically persisted to a LibSQL (SQLite) database. This enables:
+
+- **Crash Recovery**: Active runs are restored on plugin restart
+- **Run History**: Query past workflow executions via `/workflow runs`
+- **Suspend/Resume**: Suspended workflows survive session restarts
+
+The database is created automatically at the configured `dbPath`.
+
+## Workflow Definitions
+
+Create workflow definitions in `.opencode/workflows/` as JSON files:
+
+```json
+{
+  "id": "deploy-prod",
+  "description": "Deploys the application to production",
+  "inputs": {
+    "version": "string"
+  },
+  "steps": [
+    {
+      "id": "check-git",
+      "type": "shell",
+      "command": "git status --porcelain",
+      "description": "Ensure git is clean"
+    },
+    {
+      "id": "run-tests",
+      "type": "shell",
+      "command": "npm test",
+      "after": ["check-git"]
+    },
+    {
+      "id": "ask-approval",
+      "type": "suspend",
+      "description": "Wait for user to approve deployment",
+      "after": ["run-tests"]
+    },
+    {
+      "id": "deploy-script",
+      "type": "shell",
+      "command": "npm run deploy -- --tag {{inputs.version}}",
+      "after": ["ask-approval"]
+    }
+  ]
+}
+```
+
+## Step Types
+
+### Shell Step
+Execute shell commands:
+```json
+{
+  "id": "build",
+  "type": "shell",
+  "command": "npm run build",
+  "cwd": "./packages/app",
+  "env": { "NODE_ENV": "production" },
+  "failOnError": true
+}
+```
+
+### Tool Step
+Invoke OpenCode tools:
+```json
+{
+  "id": "send-notification",
+  "type": "tool",
+  "tool": "slack_send",
+  "args": {
+    "channel": "#releases",
+    "text": "Deployed {{inputs.version}}"
+  }
+}
+```
+
+### Agent Step
+Prompt an LLM:
+```json
+{
+  "id": "generate-changelog",
+  "type": "agent",
+  "prompt": "Generate a changelog for version {{inputs.version}}",
+  "model": "gpt-4",
+  "maxTokens": 1000
+}
+```
+
+### Suspend Step
+Pause for human input:
+```json
+{
+  "id": "approval",
+  "type": "suspend",
+  "message": "Ready to deploy. Resume to continue.",
+  "description": "Wait for deployment approval"
+}
+```
+
+### HTTP Step
+Make HTTP requests:
+```json
+{
+  "id": "notify-slack",
+  "type": "http",
+  "method": "POST",
+  "url": "https://hooks.slack.com/services/xxx",
+  "headers": {
+    "Content-Type": "application/json"
+  },
+  "body": {
+    "text": "Deployed {{inputs.version}}"
+  },
+  "failOnError": true
+}
+```
+
+HTTP step output includes:
+- `body` - Parsed JSON response, or `null` if response is not valid JSON
+- `text` - Raw response text (useful for non-JSON responses or debugging)
+- `status` - HTTP status code
+- `headers` - Response headers
+
+### File Step
+Read, write, or delete files:
+```json
+{
+  "id": "write-version",
+  "type": "file",
+  "action": "write",
+  "path": "./version.txt",
+  "content": "{{inputs.version}}"
+}
+```
+
+```json
+{
+  "id": "read-config",
+  "type": "file",
+  "action": "read",
+  "path": "./config.json"
+}
+```
+
+## Commands
+
+Use the `/workflow` command:
+
+- `/workflow list` - List available workflows
+- `/workflow show <id>` - Show workflow details
+- `/workflow run <id> [param=value ...]` - Run a workflow
+- `/workflow status <runId>` - Check run status
+- `/workflow resume <runId> [data]` - Resume a suspended workflow
+- `/workflow cancel <runId>` - Cancel a running workflow
+- `/workflow runs [workflowId]` - List recent runs
+
+### Parameter Type Inference
+
+When passing parameters via `/workflow run`, values are automatically converted to their appropriate types:
+
+| Input | Parsed As |
+|-------|-----------|
+| `count=5` | `number` (5) |
+| `ratio=3.14` | `number` (3.14) |
+| `enabled=true` | `boolean` (true) |
+| `debug=false` | `boolean` (false) |
+| `name=hello` | `string` ("hello") |
+| `url=http://example.com?foo=bar` | `string` (preserved) |
+
+This ensures workflow inputs match their expected schema types without manual conversion.
+
+## Agent Tool
+
+Agents can trigger workflows using the `workflow` tool:
+
+```typescript
+// List workflows
+workflow({ mode: "list" })
+
+// Run a workflow
+workflow({ 
+  mode: "run", 
+  workflowId: "deploy-prod",
+  params: { version: "1.2.0" }
+})
+
+// Check status
+workflow({ mode: "status", runId: "abc-123" })
+
+// Resume suspended workflow
+workflow({ 
+  mode: "resume", 
+  runId: "abc-123",
+  resumeData: { approved: true }
+})
+```
+
+## Template Interpolation
+
+Use `{{expression}}` syntax to reference:
+- `{{inputs.paramName}}` - Workflow input parameters
+- `{{steps.stepId.stdout}}` - Shell step stdout
+- `{{steps.stepId.response}}` - Agent step response
+- `{{steps.stepId.result}}` - Tool step result
+- `{{steps.stepId.body}}` - HTTP step response body (parsed JSON or null)
+- `{{steps.stepId.text}}` - HTTP step raw response text
+- `{{steps.stepId.content}}` - File step content (read action)
+- `{{env.VAR_NAME}}` - Environment variables
+- `{{run.id}}` - Current workflow run ID
+- `{{run.workflowId}}` - Workflow definition ID
+- `{{run.startedAt}}` - ISO timestamp when run started
+
+### Type Preservation
+
+When a template contains only a single variable reference (e.g., `"{{inputs.count}}"`), the original type is preserved. This means:
+- `"{{inputs.count}}"` with `count=42` returns the number `42`, not the string `"42"`
+- `"Count: {{inputs.count}}"` returns `"Count: 42"` (string interpolation)
+
+### Conditional Execution
+
+Steps can include a `condition` to control execution:
+```json
+{
+  "id": "deploy-prod",
+  "type": "shell",
+  "command": "deploy.sh",
+  "condition": "{{inputs.environment}}"
+}
+```
+The step is skipped if the condition evaluates to `"false"`, `"0"`, or `""`.
+
+## Dependencies
+
+Steps can declare dependencies using `after`:
+
+```json
+{
+  "id": "deploy",
+  "type": "shell",
+  "command": "deploy.sh",
+  "after": ["build", "test"]
+}
+```
+
+Steps at the same dependency level run in parallel.
+
+## License
+
+MIT