@loom-framework/core 0.1.0-alpha.151 → 0.1.0-alpha.152

package/builtin-skills/app-skill/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: {{projectName}}-data
+name: {{projectName}}
 description: |
   ⚠️ TODO: 根据下方 [TODO] 标记补全触发短语。阅读 references/models.md 中的数据模型和 AI 按钮定义，
-  编写触发短语，包含：用户语言中的常见增删改查动词、各数据模型相关的操作、AI 按钮的标签。
+  编写触发短语，包含：用户语言中的常见增删改查动词、各数据模型相关的操作、AI 按钮的标签<!-- AUTH_DESC --><!-- EVENTS_DESC --><!-- PROCESS_DESC -->
   格式："This skill should be used when the user asks to '短语1', '短语2',
   or any request about <此项目管理的内容> in the {{projectName}} project."
 version: 1.0.0
@@ -10,24 +10,34 @@ version: 1.0.0
 
 # {{projectName}} — App Skill
 
-> **此文件由 `loom generate capabilities` 生成。标记为 [TODO] 的部分需要手动编辑补全。** 
+> **此文件由 `loom generate capabilities` 生成。标记为 [TODO] 的部分需要手动编辑补全。**
 > references/models.md 和 references/data-semantics.md 会每次重新生成，无需手动编辑。
 
 ## Overview
 
 [TODO: 阅读 references/models.md，用2-3句话描述项目做什么、管理哪些数据模型、用户如何通过 AI 对话与数据交互。]
+<!-- AUTH_OVERVIEW -->
+<!-- EVENTS_OVERVIEW -->
+<!-- PROCESS_OVERVIEW -->
 
 ## Usage Scenarios
 
 **必须加载 references/models.md 和 references/data-semantics.md**，这两个文件包含从 loom.config.ts 动态注入的项目特定信息，不加载则无法生成正确内容：
 - models.md — 当前项目的数据模型字段表（字段名、类型、enum 取值、默认值）、AI 按钮定义（id、label、prompt、placement）、CLI 命令语法（read/write/update/delete，不要使用 create/list 等不存在的命令）。
 - data-semantics.md — 当前项目的数据模型名称列表、write 的 --data JSON 构造规则（字段类型格式、enum 取值约束、贴合业务的真实示例值）、read 的 --filter JSON 构造规则（优先用 enum/boolean 字段筛选、跨模型关联查询）。
+<!-- AUTH_SCENARIOS_LOAD -->
+<!-- PROCESS_SCENARIOS_LOAD -->
 
-[TODO: 生成8-10个典型用户请求，每个格式：用户说的话 → 对应的 `loom data` CLI 命令。每个数据模型至少包含一个场景。]
+[TODO: 生成5-10个典型用户请求，每个格式：用户说的话 → 对应的 `loom data` CLI 命令。每个数据模型至少包含一个场景。]
+<!-- AUTH_SCENARIOS -->
+<!-- EVENTS_SCENARIOS -->
+<!-- PROCESS_SCENARIOS -->
 
 ## Technical Reference
 
+<!-- CLI_AUTH -->
 - 数据模型结构、CLI 语法和操作规范：**references/models.md**
 - 语义引导（示例数据生成、筛选选择、关系推断）：**references/data-semantics.md**
 <!-- AUTH_REF -->
-<!-- EVENTS_REF -->
+<!-- EVENTS_REF -->
+<!-- PROCESS_REF -->

package/builtin-skills/app-skill/references/auth.md

@@ -1,19 +1,5 @@
 # Auth Commands Reference
 
-## CLI Authentication
-
-CLI commands require authentication when auth is enabled. Provide token via:
-
-1. **`--token` flag**: `loom data read <model> --token <jwt>`
-2. **`LOOM_TOKEN` env**: `LOOM_TOKEN=<jwt> loom data read <model>`
-
-When auth is not enabled, CLI commands use local DataAdapter without token.
-
-### AI Chat Sessions
-
-When using AI chat (web UI), `LOOM_TOKEN` is automatically set in the AI's environment.
-AI can run `loom data read`, `loom user list`, etc. directly — the token matches the logged-in user's identity and permissions.
-
 ## Authentication Commands
 
 ### Login
@@ -65,12 +51,30 @@ loom user delete <id> --token <admin-jwt>
 loom user role <id> <role> --token <admin-jwt>
 ```
 
-## Role Info
+## Role Management
 
 ### List Roles
 ```bash
 loom role list [--token <jwt>]
 ```
+Note: `role list` does not require authentication (the endpoint is public).
+
+### Create Role (admin required)
+```bash
+loom role create <name> -p '[{"model":"*","level":"read"}]' --token <admin-jwt>
+```
+
+### Update Role (admin required)
+```bash
+loom role update <name> -n <new-name> --token <admin-jwt>
+loom role update <name> -p '[{"model":"items","level":"write"}]' --token <admin-jwt>
+```
+
+### Delete Role (admin required)
+```bash
+loom role delete <name> --token <admin-jwt>
+```
+Cannot delete a role that still has assigned users.
 
 ### Permission Levels
 ```bash
@@ -89,8 +93,6 @@ loom data delete <model> --id <id> --token <jwt>
 loom data schema <model> --token <jwt>
 ```
 
-Optional: `--server <url>` (default: http://localhost:3000)
-
 ## Permission Model
 
 ### Levels (hierarchical)
@@ -115,7 +117,6 @@ auth: {
     defaults: {
       read: 'read',
       write: 'write',
-      readIncludesAiButtons: false,  // viewer sees AI buttons?
       writeExcludesDelete: false,     // writer can delete?
     },
   },
@@ -146,7 +147,10 @@ Used by Process automation to execute as the user.
 | POST | /api/v1/auth/logout | Yes | Logout |
 | POST | /api/v1/auth/refresh | No* | Refresh token |
 | GET | /api/v1/auth/whoami | Yes | Current user |
-| GET | /api/v1/auth/roles | Yes | List roles |
+| GET | /api/v1/auth/roles | No | List roles |
+| POST | /api/v1/auth/roles | Admin | Create role |
+| PUT | /api/v1/auth/roles/:role | Admin | Update role |
+| DELETE | /api/v1/auth/roles/:role | Admin | Delete role |
 | GET | /api/v1/auth/users | Admin | List users |
 | POST | /api/v1/auth/users | Admin | Create user |
 | GET | /api/v1/auth/users/:id | Self/Admin | Get user |

package/builtin-skills/app-skill/references/evolution.md

@@ -0,0 +1,90 @@
+# Process Evolution Guide
+
+## Overview
+
+Process Evolution is the practice of iteratively improving automated processes based on execution results. Loom provides the tooling (logs, metrics) for AI to analyze and optimize processes over time.
+
+## How Evolution Works
+
+1. **Monitor**: Review execution logs and metrics
+2. **Analyze**: Identify patterns, failures, and optimization opportunities
+3. **Decide**: Determine what to change (prompt, trigger, references)
+4. **Apply**: Update the process definition or PROCESS.md
+5. **Verify**: Monitor subsequent runs for improvement
+
+## Reading Metrics
+
+```bash
+# Check recent logs
+loom process logs <name> --limit 20
+
+# View process status
+loom process status <name>
+```
+
+### Key Indicators
+
+| Metric | Good | Needs Improvement |
+|--------|------|-------------------|
+| Success rate | > 95% | < 80% |
+| Avg duration | Stable or decreasing | Increasing trend |
+| Timeout rate | 0% | > 5% |
+| Error patterns | Unique errors | Repeated same error |
+
+## Evolution Strategies
+
+### Prompt Optimization
+
+If a process frequently fails or produces low-quality results:
+
+1. Read the current prompt: `loom process export <name>`
+2. Analyze failure patterns in logs
+3. Make the prompt more specific:
+   - Add constraints ("Output must be JSON")
+   - Add examples ("Here's a good output: ...")
+   - Add error handling instructions
+4. Update: `loom process export <name>` → edit → API update
+
+### Trigger Adjustment
+
+If a process runs too often or too rarely:
+
+- Adjust cron frequency
+- Add `--event-debounce` for bursty events
+- Add `--event-filter` for selective triggering
+
+```bash
+# Increase debounce for bursty events
+loom process update <name> --event-debounce 5000
+
+# Add filter to only trigger on specific conditions
+loom process update <name> --event-filter '{"status":"urgent"}'
+```
+
+### Reference Updates
+
+For full processes, update reference files:
+- Outdated API docs → replace with current
+- Missing context → add new reference files
+- Unnecessary references → remove to reduce prompt size
+
+## Safety Constraints
+
+Evolution is limited to these safe operations:
+- **Notify**: Send alerts via events
+- **Data write**: Create/update records via `loom data` CLI
+- **Process update**: Modify process definitions via CLI
+
+Evolution MUST NOT:
+- Delete data without explicit user approval
+- Modify other processes without user consent
+- Change authentication or authorization settings
+- Execute shell commands outside the sandbox
+
+## Monitoring Checklist
+
+After applying evolution changes:
+1. Run manually: `loom process run <name>`
+2. Check result: `loom process logs <name> --limit 1`
+3. Verify metrics improve over next 5-10 scheduled runs
+4. Revert if worse: restore previous definition

package/builtin-skills/app-skill/references/process-builder.md

@@ -0,0 +1,140 @@
+# Process Builder Guide
+
+## Purpose
+
+This guide helps AI assistants create Processes for users. When a user says "I want to automate X" or "run Y every day", use this guide to build a process definition.
+
+## Lightweight vs Full Decision
+
+### Use Lightweight (`--prompt`) when:
+- Single, simple task
+- No reference files needed
+- Prompt fits in a few sentences
+- No metrics dashboard needed
+
+### Use Full (`--process`) when:
+- Multi-step workflow with decision points
+- Reference documentation needed (API docs, data schemas, style guides)
+- Metrics dashboard desired
+- Process may evolve over time (Evolution section)
+
+## Step-by-Step Creation
+
+### 1. Analyze the Request
+
+Identify:
+- **What** the process should do
+- **When** it should run (schedule or event trigger)
+- **Who** owns it (username for service token)
+- **Complexity** (lightweight vs full)
+
+### 2. Choose Trigger
+
+| Need | Use | Example |
+|------|-----|---------|
+| Periodic schedule | `--cron` | `0 9 * * 1-5` (weekdays 9am) |
+| On data change | `--on-event` | `data:create:tasks` |
+| On user action | `--on-event` | `user:created` |
+| Manual only | Neither | Just `loom process run` |
+
+### 3. Create the Process
+
+For lightweight:
+```bash
+loom process add --name "task-summary" \
+  --cron "0 9 * * *" \
+  --prompt "Read all tasks created yesterday, summarize key themes, and post a digest" \
+  --owner admin
+```
+
+For full:
+```bash
+# Step 1: Generate scaffold
+loom process generate weekly-report --description "Weekly analytics report"
+
+# Step 2: Edit PROCESS.md with detailed flow
+# (AI should write the PROCESS.md content)
+
+# Step 3: Add reference files if needed
+# (Copy to .claude/processes/weekly-report/references/)
+
+# Step 4: Register the process
+loom process add --name "weekly-report" \
+  --cron "0 9 * * 1" \
+  --process "weekly-report" \
+  --owner admin
+```
+
+### 4. Verify
+
+```bash
+loom process status <name>
+loom process run <name>  # manual test
+loom process logs <name>  # check result
+```
+
+## PROCESS.md Best Practices
+
+### Structure
+
+```markdown
+# Process: <name>
+
+## Description
+What this process does and why.
+
+## Trigger
+When it runs and what triggers it.
+
+## Flow
+Step-by-step instructions:
+1. Read data from <model>
+2. Analyze <something>
+3. Write results to <model>
+4. Notify <channel>
+
+## Decision Points
+Key decisions the AI should make:
+- If X, do Y
+- If Z, skip to step N
+
+## Metrics
+How success is measured:
+- Execution time < N seconds
+- Error rate < X%
+- Output quality: <criteria>
+
+## Evolution
+How this process should improve:
+- After N runs, review and optimize prompt
+- Track common errors and add handling
+```
+
+### Tips
+- Be specific in Flow steps — AI follows them literally
+- Include data model names and field names
+- Reference CLI commands: `loom data list <model>`, `loom data create <model>`
+- Use `loom data` commands for data operations, not direct file I/O
+- Include error handling in Decision Points
+
+## Common Cron Patterns
+
+| Pattern | Schedule |
+|---------|----------|
+| `*/5 * * * *` | Every 5 minutes |
+| `*/15 * * * *` | Every 15 minutes |
+| `0 * * * *` | Every hour |
+| `0 9 * * *` | Daily at 9 AM |
+| `0 9 * * 1-5` | Weekdays at 9 AM |
+| `0 9 * * 1` | Every Monday at 9 AM |
+| `0 0 1 * *` | First of every month |
+
+## Common Event Patterns
+
+| Pattern | When |
+|---------|------|
+| `data:create:<model>` | New record created |
+| `data:update:<model>` | Record updated |
+| `data:delete:<model>` | Record deleted |
+| `user:created` | New user registered |
+| `process:completed:<name>` | Another process finished |

package/builtin-skills/app-skill/references/process-metrics.md

@@ -0,0 +1,93 @@
+# Process Metrics Reference
+
+## Overview
+
+Process metrics allow you to define dashboard widgets for monitoring process execution. Metrics are served via the `/api/v1/processes/:name/metrics` endpoint and configured per-process.
+
+## Metrics Config
+
+Define metrics using DashboardWidget schema in `--metrics-config <path>` JSON file or via the API.
+
+### Example: metrics-config.json
+
+```json
+[
+  {
+    "type": "stat",
+    "title": "成功率",
+    "model": "__process_metrics",
+    "aggregate": "sum",
+    "field": "completedRuns",
+    "color": "#52c41a"
+  },
+  {
+    "type": "stat",
+    "title": "失败次数",
+    "model": "__process_metrics",
+    "aggregate": "sum",
+    "field": "failedRuns",
+    "color": "#ff4d4f"
+  },
+  {
+    "type": "line",
+    "title": "执行趋势",
+    "model": "__process_metrics",
+    "aggregate": "sum",
+    "field": "totalRuns",
+    "groupBy": "date",
+    "dateInterval": "day"
+  }
+]
+```
+
+### Available Widget Types
+
+| Type | Description | Required Fields |
+|------|-------------|-----------------|
+| `stat` | Single number display | `title`, `model`, `aggregate`, `field` |
+| `line` | Line chart | `title`, `model`, `aggregate`, `field`, `groupBy`, `dateInterval` |
+| `bar` | Bar chart | `title`, `model`, `aggregate`, `field`, `groupBy` |
+| `pie` | Pie chart | `title`, `model`, `field`, `groupBy` |
+| `gauge` | Gauge display | `title`, `model`, `field`, `min`, `max` |
+| `table` | Table view | `title`, `model`, `columns` |
+
+### Available Metrics Fields
+
+From `ProcessMetricsAggregate`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `date` | string | Date (YYYY-MM-DD) |
+| `totalRuns` | number | Total executions |
+| `completedRuns` | number | Successful executions |
+| `failedRuns` | number | Failed executions |
+| `timeoutRuns` | number | Timed out executions |
+| `avgDurationMs` | number | Average duration in ms |
+| `lastRunAt` | string\|null | Last execution timestamp |
+| `lastStatus` | string\|null | Last execution status |
+
+### Setting Metrics Config
+
+```bash
+# During process creation
+loom process add --name "health-check" \
+  --cron "*/30 * * * *" \
+  --prompt "Check system health" \
+  --metrics-config ./health-metrics.json \
+  --owner admin
+
+# Or create the JSON file first
+echo '[
+  {"type":"stat","title":"Success Rate","model":"__process_metrics","aggregate":"sum","field":"completedRuns"},
+  {"type":"stat","title":"Avg Duration","model":"__process_metrics","aggregate":"avg","field":"avgDurationMs"}
+]' > health-metrics.json
+```
+
+### API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/processes/:name/metrics` | GET | Get aggregated metrics data |
+| `/api/v1/processes/:name/metrics-config` | GET | Get widget configuration |
+
+The frontend ProcessManagementPage Metrics tab fetches both endpoints and renders the configured widgets dynamically.

package/builtin-skills/app-skill/references/process.md

@@ -0,0 +1,222 @@
+# Process CLI Reference
+
+## Overview
+
+Process is Loom's automation engine for scheduling and event-driven AI tasks. Each process has triggers (cron, event, or manual) and executes AI prompts via the Claude Code engine.
+
+## Commands
+
+### `loom process add`
+
+Create a new process definition.
+
+```bash
+# Lightweight process (inline prompt)
+loom process add --name "daily-summary" \
+  --cron "0 9 * * 1-5" \
+  --prompt "Summarize yesterday's data and email the team" \
+  --owner admin
+
+# Full process (with PROCESS.md)
+loom process add --name "weekly-report" \
+  --cron "0 9 * * 1" \
+  --process "weekly-report" \
+  --owner admin \
+  --description "Weekly analytics report"
+
+# Event-triggered process
+loom process add --name "on-task-create" \
+  --on-event "data:create:tasks" \
+  --prompt "Analyze the new task and suggest priorities" \
+  --owner admin \
+  --event-debounce 2000
+
+# With metrics config
+loom process add --name "health-check" \
+  --cron "*/30 * * * *" \
+  --prompt "Check system health" \
+  --metrics-config ./metrics-config.json \
+  --owner bot
+```
+
+**Options:**
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--name` | Yes | Process name (^[a-zA-Z][a-zA-Z0-9_-]*$) |
+| `--prompt` | One of | Inline prompt for lightweight process |
+| `--process` | One of | Full process name (expects .claude/processes/{name}/PROCESS.md) |
+| `--cron` | No | Cron schedule expression |
+| `--cron-timezone` | No | Timezone for cron (e.g., "America/New_York") |
+| `--on-event` | No | EventBus pattern (e.g., "data:create:tasks") |
+| `--event-filter` | No | JSON filter on event payload fields |
+| `--event-debounce` | No | Debounce window in ms (default: 1000) |
+| `--description` | No | Process description |
+| `--owner` | No | Owner username (default: from processes config) |
+| `--owner-token` | No | Direct JWT token (bypasses runtime resolution) |
+| `--metrics-config` | No | Path to metrics DashboardWidget config JSON |
+| `--token` | No | Auth token (or set LOOM_TOKEN) |
+| `--server` | No | Server URL (or set LOOM_SERVER, default: http://localhost:3000) |
+
+### `loom process list`
+
+List all processes.
+
+```bash
+loom process list
+loom process list --status active
+loom process list --status paused
+```
+
+### `loom process status <name>`
+
+Show detailed process status.
+
+```bash
+loom process status daily-summary
+```
+
+### `loom process run <name>`
+
+Manually trigger a process execution.
+
+```bash
+loom process run daily-summary
+loom process run on-task-create --payload '{"model":"tasks","id":"task_123"}'
+```
+
+### `loom process pause <name>`
+
+Pause a process (stops triggers, manual run still works).
+
+```bash
+loom process pause daily-summary
+```
+
+### `loom process resume <name>`
+
+Resume a paused process.
+
+```bash
+loom process resume daily-summary
+```
+
+### `loom process update <name>`
+
+Update an existing process definition.
+
+```bash
+loom process update daily-summary --cron "0 10 * * 1-5"
+loom process update on-task-create --prompt "Updated prompt text"
+loom process update daily-summary --description "Updated description" --cron "0 8 * * 1-5"
+```
+
+**Options:**
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--cron` | No | Update cron schedule expression |
+| `--cron-timezone` | No | Update cron timezone |
+| `--on-event` | No | Update event trigger pattern |
+| `--event-filter` | No | Update event payload filter as JSON |
+| `--event-debounce` | No | Update debounce window in ms |
+| `--prompt` | No | Update inline prompt |
+| `--description` | No | Update description |
+| `--token` | No | Auth token (or set LOOM_TOKEN) |
+| `--server` | No | Server URL (or set LOOM_SERVER, default: http://localhost:3000) |
+
+### `loom process remove <name>`
+
+Remove a process definition. Logs are preserved.
+
+```bash
+loom process remove daily-summary
+```
+
+### `loom process logs <name> [runId]`
+
+View execution logs. When `runId` is provided, shows details for a single run.
+
+```bash
+# List recent logs
+loom process logs daily-summary
+loom process logs daily-summary --limit 50
+loom process logs daily-summary --offset 10
+
+# View a specific run
+loom process logs daily-summary run_abc123
+```
+
+### `loom process generate <name>`
+
+Create PROCESS.md scaffold directory (for full process mode). Called by AI, not directly by users.
+
+```bash
+loom process generate daily-report --description "Daily report generator"
+```
+
+### `loom process export <name>`
+
+Export process definition as JSON.
+
+```bash
+loom process export daily-summary
+```
+
+## Process Modes
+
+### Lightweight Mode (`--prompt`)
+
+- Inline prompt, no PROCESS.md file
+- Best for simple, single-task automations
+- Quick to set up and modify
+
+### Full Mode (`--process`)
+
+- Has PROCESS.md at `.claude/processes/{name}/PROCESS.md`
+- Can include reference files in `.claude/processes/{name}/references/`
+- Best for complex, multi-step workflows
+- Supports Metrics and Evolution sections
+
+## Trigger Types
+
+### Cron
+Standard 5-field cron expression: `minute hour day month weekday`
+```
+*/5 * * * *     — Every 5 minutes
+0 9 * * 1-5     — Weekdays at 9 AM
+0 0 1 * *       — First of every month
+```
+
+### Event
+EventBus pattern matching: `{category}:{action}:{target}`
+```
+data:create:tasks       — When a task is created
+data:update:*           — Any data update
+user:created            — When a user is created
+process:completed:xxx   — When process xxx completes
+```
+
+### Manual
+`loom process run <name>` — immediate execution, works even when paused.
+
+## Service Token Authentication
+
+When auth is enabled, processes need a service token to operate:
+- `--owner <username>`: Runtime resolution via UserStore (recommended)
+- `--owner-token <jwt>`: Direct JWT token (less secure, stored in processes.json)
+
+## Execution Model
+
+1. Trigger fires → entry enqueued
+2. Queue slot available → process starts
+3. AI prompt built (PROCESS.md + references + event context)
+4. Claude Code engine executes with timeout
+5. Result logged to `.loom/process-logs/{name}/{runId}.json`
+6. Event emitted: `process:started`, `process:completed`, or `process:failed`
+
+## Concurrency
+
+Controlled by `processes.maxConcurrent` in loom.config.ts (default: 5). When max is reached, new triggers queue until a slot opens.
+
+## Debounce
+
+Event triggers have `eventDebounceMs` (default: 1000ms). Rapid events within the window are collapsed — only one execution fires with the last event's payload.