@powerformer/refly-cli 0.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@powerformer/refly-cli",
+  "version": "0.1.0",
+  "description": "Refly CLI - Command-line interface for Refly workflow orchestration",
+  "bin": {
+    "refly": "./dist/bin/refly.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "build:test": "REFLY_BUILD_ENV=test tsup",
+    "build:staging": "REFLY_BUILD_ENV=staging tsup",
+    "build:prod": "REFLY_BUILD_ENV=production tsup",
+    "dev": "tsup --watch",
+    "clean": "rimraf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm run build"
+  },
+  "keywords": ["refly", "cli", "workflow", "automation"],
+  "author": "Refly AI",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0",
+    "zod": "^3.23.8",
+    "open": "^10.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.0",
+    "rimraf": "^6.0.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.9"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": ["dist", "skill"]
+}

package/skill/SKILL.md

@@ -0,0 +1,247 @@
+---
+name: refly
+description: |
+  Refly workflow orchestration via local CLI (secure). Use this skill when the user asks to:
+  - Create / edit / run workflows (DAG/pipeline/工作流/编排/automation)
+  - Run or debug workflow nodes (node.run, 单节点调试)
+  - Build multi-step document pipelines (parse/summarize/translate/export)
+  - Manage workflow runs (status/abort/logs)
+  Triggers: refly, workflow, DAG, pipeline, 自动化流程, 多步骤任务, 编排任务, 创建工作流, 运行流程.
+  Requires: @refly/cli installed and authenticated.
+---
+
+# Refly Skill (CLI-first, Secure, DAG-native)
+
+## 0) Mandatory Execution Rules (NON-NEGOTIABLE)
+
+When this skill is triggered:
+
+1. MUST use Refly CLI for all actions.
+   - Do NOT call Refly API directly.
+   - Do NOT fabricate API calls, workflow IDs, run IDs, node IDs, or outputs.
+
+2. MUST rely only on CLI JSON output for state.
+   - Never assume a workflow exists unless CLI returned it.
+
+3. MUST keep token private.
+   - Never print, request, or infer tokens.
+   - If auth fails, instruct the user to run `refly login` or `refly init`.
+
+4. MUST present results based on verified CLI JSON fields.
+
+If any rule cannot be satisfied, STOP and tell the user exactly what to run next.
+
+---
+
+## 1) Preconditions / Environment Check
+
+Before any operation:
+
+```bash
+refly status
+```
+
+- If `ok=false` and `error.code=AUTH_REQUIRED`: run `refly login` (or `refly init`).
+- If `error.code=CLI_NOT_FOUND`: install `npm i -g @refly/cli` and rerun.
+
+---
+
+## 2) Output Contract (STRICT)
+
+Success:
+```json
+{ "ok": true, "type": "workflow.create", "version": "1.0", "payload": {} }
+```
+
+Error:
+```json
+{ "ok": false, "type": "error", "version": "1.0", "error": { "code": "AUTH_REQUIRED", "message": "...", "hint": "refly login" } }
+```
+
+Rules:
+- Only trust `payload`.
+- If `ok=false`, do NOT proceed. Show `hint`.
+
+---
+
+## 3) Core Commands
+
+### Authentication
+```bash
+refly init                    # Initialize and install skill
+refly login                   # Authenticate with API key
+refly logout                  # Remove credentials
+refly status                  # Check CLI and auth status
+refly whoami                  # Show current user
+```
+
+### Workflow CRUD
+```bash
+refly workflow create --name "<name>" --spec '<json>'
+refly workflow generate --query "<natural language description>"  # AI-powered workflow generation
+refly workflow edit <workflowId> --ops '<json>'
+refly workflow get <workflowId>
+refly workflow list
+refly workflow delete <workflowId>
+```
+
+### Workflow Run & Monitoring
+```bash
+refly workflow run <workflowId> --input '<json>'
+refly workflow status <runId>                    # Get detailed execution status
+refly workflow status <runId> --watch            # Watch until completion (polls every 2s)
+refly workflow run detail <runId>                # Full workflow execution detail
+refly workflow run node <runId> <nodeId>         # Single node execution result
+refly workflow run toolcalls <runId>             # All tool calls in workflow
+refly workflow abort <runId>
+```
+
+### Node Operations
+```bash
+refly node types                                 # List available node types
+refly node run --type "<nodeType>" --input '<json>'  # Run a node for debugging
+refly node result <resultId>                     # Get node execution result
+refly node result <resultId> --include-tool-calls    # Include tool call details
+```
+
+### Tool Inspection
+```bash
+refly tool calls --result-id <resultId>          # Get tool execution results for a node
+refly tool get <callId>                          # Get single tool call detail
+```
+
+### Action Result
+```bash
+refly action result <resultId>                   # Action result with default sanitization
+refly action result <resultId> --version <n>     # Specific version
+refly action result <resultId> --raw             # Disable sanitization/truncation
+refly action result <resultId> --include-files   # Include related files
+```
+
+### File Operations
+```bash
+refly file list                                  # List files
+refly file list --canvas-id <id>                 # Filter by canvas
+refly file get <fileId>                          # Get file metadata and content
+refly file download <fileId> -o ./output.txt     # Download file to local filesystem
+```
+
+---
+
+## 4) AI Workflow Generation
+
+Use `workflow generate` to create workflows from natural language:
+
+```bash
+# Basic generation
+refly workflow generate --query "Parse PDF, summarize content, translate to Chinese"
+
+# With options
+refly workflow generate \
+  --query "Research topic, write article, export to markdown" \
+  --model-id <modelId> \
+  --locale zh \
+  --timeout 300000
+
+# With predefined variables
+refly workflow generate \
+  --query "Process documents from input folder" \
+  --variables '[{"variableId":"v1","name":"inputFolder","variableType":"string"}]'
+```
+
+The generate command:
+- Invokes AI to parse the natural language query
+- Creates a workflow plan with tasks
+- Builds the DAG with appropriate nodes and edges
+- Returns workflowId, planId, and task details
+
+---
+
+## 5) DAG Rules (STRICT)
+
+- Unique node ids.
+- No cycles.
+- Dependencies reference existing nodes only.
+- Insert X between A→B by rewiring dependencies.
+
+---
+
+## 6) Workflow Spec Schema (v1)
+
+```json
+{
+  "version": 1,
+  "name": "string",
+  "description": "string?",
+  "nodes": [
+    {
+      "id": "string",
+      "type": "string",
+      "input": {},
+      "dependsOn": ["string"]
+    }
+  ],
+  "metadata": {
+    "tags": ["string"],
+    "owner": "string?"
+  }
+}
+```
+
+---
+
+## 7) Error Codes
+
+| Code | Description | Hint |
+|------|-------------|------|
+| AUTH_REQUIRED | Not authenticated | refly login |
+| CLI_NOT_FOUND | CLI not installed | npm i -g @refly/cli |
+| NETWORK_ERROR | API unreachable | Check connection |
+| NOT_FOUND | Resource not found | Verify ID |
+| CONFLICT | State conflict | Check status |
+| INTERNAL_ERROR | Unexpected error | Report issue |
+
+---
+
+## 8) References
+
+- `references/workflow-schema.md` - Full schema documentation
+- `references/node-types.md` - Available node types
+- `references/api-errors.md` - Complete error reference
+
+## 9) Execution Results Workflow (Recommended)
+
+Use this flow when tracking a running workflow and extracting results:
+
+1. **Start run**: `refly workflow run <workflowId> --input '<json>'`
+2. **Monitor status**: `refly workflow status <runId> --watch`
+3. **On node finish**: `refly workflow run node <runId> <nodeId>`
+4. **Tool calls** (optional): `refly workflow run toolcalls <runId>` or `refly tool get <callId>`
+5. **Raw output** for debugging: add `--raw` to disable sanitization
+
+## 10) CLI Backend API Reference (Workflow/Node/Tool)
+
+Workflow:
+- `POST /v1/cli/workflow` create
+- `POST /v1/cli/workflow/generate` AI generate
+- `GET /v1/cli/workflow` list
+- `GET /v1/cli/workflow/:id` detail
+- `PATCH /v1/cli/workflow/:id` update
+- `DELETE /v1/cli/workflow/:id` delete
+- `POST /v1/cli/workflow/:id/run` start run
+- `GET /v1/cli/workflow/run/:runId` run status
+- `POST /v1/cli/workflow/run/:runId/abort` abort run
+- `GET /v1/cli/workflow/run/:runId/detail` run detail
+- `GET /v1/cli/workflow/run/:runId/node/:nodeId` node result (workflow scope)
+- `GET /v1/cli/workflow/run/:runId/toolcalls` tool calls (workflow scope)
+
+Node:
+- `GET /v1/cli/node/types` list node types
+- `POST /v1/cli/node/run` run a single node (not implemented yet)
+
+Tool:
+- `GET /v1/cli/toolcall?resultId=<id>&version=<n>` tool calls for action result
+- `GET /v1/cli/toolcall/:callId` single tool call detail
+
+Action (related):
+- `GET /v1/cli/action/result?resultId=<id>&version=<n>&sanitizeForDisplay=<bool>&includeFiles=<bool>`

package/skill/references/api-errors.md

@@ -0,0 +1,120 @@
+# API Errors Reference
+
+All CLI errors use stable error codes for reliable error handling.
+
+## Error Response Format
+
+```json
+{
+  "ok": false,
+  "type": "error",
+  "version": "1.0",
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable description",
+    "details": { },
+    "hint": "Suggested action"
+  }
+}
+```
+
+## Error Codes
+
+### Authentication Errors
+
+| Code | Description | Hint |
+|------|-------------|------|
+| AUTH_REQUIRED | Not authenticated or token expired | Run `refly login` |
+| AUTH_INVALID | Invalid credentials | Check API key |
+| AUTH_EXPIRED | Token has expired | Run `refly login` |
+
+### CLI Errors
+
+| Code | Description | Hint |
+|------|-------------|------|
+| CLI_NOT_FOUND | CLI not installed or not in PATH | Run `npm i -g @refly/cli` |
+| CONFIG_ERROR | Configuration file corrupted | Run `refly init` |
+| VERSION_MISMATCH | CLI version incompatible with API | Run `npm update -g @refly/cli` |
+
+### Builder Errors
+
+| Code | Description | Hint |
+|------|-------------|------|
+| BUILDER_NOT_STARTED | No active builder session | Run `refly builder start` |
+| BUILDER_ALREADY_STARTED | Builder session already exists | Run `refly builder abort` first |
+| VALIDATION_REQUIRED | Must validate before commit | Run `refly builder validate` |
+| VALIDATION_ERROR | DAG validation failed | See error details |
+| DUPLICATE_NODE_ID | Node ID already exists | Use unique node ID |
+| NODE_NOT_FOUND | Referenced node does not exist | Check node ID |
+| CYCLE_DETECTED | Circular dependency in DAG | Remove cycle |
+| INVALID_STATE | Invalid state transition | Check `refly builder status` |
+
+### Workflow Errors
+
+| Code | Description | Hint |
+|------|-------------|------|
+| WORKFLOW_NOT_FOUND | Workflow does not exist | Check workflow ID |
+| WORKFLOW_EXISTS | Workflow name already taken | Use different name |
+| RUN_NOT_FOUND | Workflow run does not exist | Check run ID |
+| RUN_FAILED | Workflow execution failed | Check run details |
+| RUN_ABORTED | Workflow was aborted | - |
+
+### Node Errors
+
+| Code | Description | Hint |
+|------|-------------|------|
+| INVALID_NODE_TYPE | Unknown node type | Run `refly node types` |
+| INVALID_NODE_INPUT | Node input validation failed | Check input schema |
+| NODE_EXECUTION_ERROR | Node execution failed | See error details |
+
+### Network Errors
+
+| Code | Description | Hint |
+|------|-------------|------|
+| NETWORK_ERROR | Cannot connect to API | Check internet connection |
+| TIMEOUT | Request timed out | Retry later |
+| API_ERROR | API returned error | See error message |
+
+### General Errors
+
+| Code | Description | Hint |
+|------|-------------|------|
+| NOT_FOUND | Resource not found | Verify resource ID |
+| CONFLICT | Resource conflict | Refresh and retry |
+| PERMISSION_DENIED | Insufficient permissions | Check access rights |
+| INVALID_INPUT | Invalid input data | Check input format |
+| INTERNAL_ERROR | Unexpected error | Report issue |
+
+## Handling Errors
+
+### In Claude Code
+
+When `ok=false`:
+1. Do NOT proceed with the operation
+2. Show the user the `error.message`
+3. Suggest the action in `error.hint`
+4. If `error.details` exists, include relevant information
+
+### Example Error Handling
+
+```bash
+# Check status before operations
+result=$(refly status)
+if [ "$(echo $result | jq -r '.ok')" = "false" ]; then
+  code=$(echo $result | jq -r '.error.code')
+  hint=$(echo $result | jq -r '.error.hint')
+  echo "Error: $code. Try: $hint"
+  exit 1
+fi
+```
+
+## Exit Codes
+
+| Exit Code | Meaning |
+|-----------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Authentication error |
+| 3 | Validation error |
+| 4 | Network error |
+| 5 | Not found |

package/skill/references/node-types.md

@@ -0,0 +1,91 @@
+# Node Types Reference
+
+This document describes the available node types for Refly workflows.
+
+## Fetching Node Types
+
+Use the CLI to get the current list of supported node types:
+
+```bash
+refly node types
+```
+
+Response:
+```json
+{
+  "ok": true,
+  "type": "node.types",
+  "version": "1.0",
+  "payload": {
+    "types": [
+      {
+        "name": "document.parse",
+        "description": "Parse document content",
+        "inputSchema": { ... },
+        "outputSchema": { ... }
+      }
+    ]
+  }
+}
+```
+
+## Node Type Cache
+
+- Location: `~/.refly/cache/node-types.json`
+- TTL: 24 hours
+- Force refresh: `refly node types --refresh`
+
+## Common Node Categories
+
+### Document Processing
+- `document.parse` - Parse various document formats
+- `document.export` - Export to different formats
+- `document.split` - Split document into chunks
+
+### LLM Operations
+- `llm.summarize` - Summarize text content
+- `llm.translate` - Translate content
+- `llm.generate` - Generate content from prompt
+- `llm.chat` - Interactive chat completion
+
+### Data Operations
+- `data.input` - Accept external input
+- `data.output` - Produce workflow output
+- `data.merge` - Merge multiple inputs
+- `data.filter` - Filter data by criteria
+- `data.transform` - Transform data structure
+
+### Control Flow
+- `control.condition` - Conditional branching
+- `control.loop` - Iterate over items
+- `control.parallel` - Parallel execution
+
+## Testing Nodes
+
+Run a single node for debugging:
+
+```bash
+refly node run --type "llm.summarize" --input '{"text": "Long text here..."}'
+```
+
+Response:
+```json
+{
+  "ok": true,
+  "type": "node.run",
+  "version": "1.0",
+  "payload": {
+    "result": { ... },
+    "metrics": {
+      "durationMs": 1234,
+      "tokensUsed": 500
+    }
+  }
+}
+```
+
+## Notes
+
+- Node types depend on your Refly backend configuration
+- Some nodes may require specific permissions
+- Input/output schemas are validated at runtime

package/skill/references/workflow-schema.md

@@ -0,0 +1,95 @@
+# Workflow Schema Reference
+
+This document defines the canonical workflow spec used by `refly workflow create --spec`.
+
+## Spec Shape (v1)
+
+```json
+{
+  "version": 1,
+  "name": "string (required)",
+  "description": "string (optional)",
+  "nodes": [
+    {
+      "id": "string (required, unique)",
+      "type": "string (required, must be valid node type)",
+      "input": "object (required, node-specific configuration)",
+      "dependsOn": "string[] (optional, list of node IDs)"
+    }
+  ],
+  "metadata": {
+    "tags": "string[] (optional)",
+    "owner": "string (optional)"
+  }
+}
+```
+
+## Field Descriptions
+
+### Top-level Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| version | number | Yes | Schema version, currently `1` |
+| name | string | Yes | Workflow name, must be unique per user |
+| description | string | No | Human-readable description |
+| nodes | array | Yes | List of workflow nodes |
+| metadata | object | No | Additional metadata |
+
+### Node Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| id | string | Yes | Unique identifier within workflow |
+| type | string | Yes | Node type from `refly node types` |
+| input | object | Yes | Node-specific input configuration |
+| dependsOn | string[] | No | IDs of nodes that must complete first |
+
+## DAG Rules
+
+1. **Unique IDs**: Each node `id` must be unique within the workflow
+2. **No Cycles**: The dependency graph must be acyclic
+3. **Valid References**: All `dependsOn` entries must reference existing node IDs
+4. **No Self-Reference**: A node cannot depend on itself
+5. **Valid Types**: All `type` values must be in the allowed node types list
+
+## Examples
+
+### Simple Sequential Workflow
+
+```json
+{
+  "version": 1,
+  "name": "document-processor",
+  "nodes": [
+    { "id": "parse", "type": "document.parse", "input": { "format": "pdf" } },
+    { "id": "summarize", "type": "llm.summarize", "input": {}, "dependsOn": ["parse"] },
+    { "id": "export", "type": "document.export", "input": { "format": "md" }, "dependsOn": ["summarize"] }
+  ]
+}
+```
+
+### Parallel Processing
+
+```json
+{
+  "version": 1,
+  "name": "parallel-analysis",
+  "nodes": [
+    { "id": "input", "type": "data.input", "input": {} },
+    { "id": "analyze-a", "type": "analyze.sentiment", "input": {}, "dependsOn": ["input"] },
+    { "id": "analyze-b", "type": "analyze.keywords", "input": {}, "dependsOn": ["input"] },
+    { "id": "merge", "type": "data.merge", "input": {}, "dependsOn": ["analyze-a", "analyze-b"] }
+  ]
+}
+```
+
+## Validation Errors
+
+| Error | Description |
+|-------|-------------|
+| DUPLICATE_NODE_ID | Two nodes have the same ID |
+| INVALID_NODE_TYPE | Node type not in allowed list |
+| MISSING_DEPENDENCY | dependsOn references non-existent node |
+| CYCLE_DETECTED | Circular dependency found |
+| MISSING_REQUIRED_FIELD | Required field is missing |