@formlm/cli 0.1.3 → 0.2.0

package/README.md

@@ -20,13 +20,43 @@ With `formlm-cli`, you can control FormLM directly from your terminal or plug it
 
 ---
 
-## Features
+## What's New in v0.2.0
 
-- **Dual-mode**: run as a terminal CLI *or* as an MCP Server for AI Agents
-- **20 built-in tools** covering full Auth / App / Field / Share lifecycle
-- **Multi-profile support** — manage multiple accounts or environments
-- **Token auth** — simple and secure, stored locally with 600 permissions
-- **MCP-ready** — plug into Claude Desktop, Cursor, or any MCP-compatible client out of the box
+The MCP architecture has been completely redesigned from the ground up:
+
+- **34 flat tools → 9 layered tools + 6 knowledge resources**
+- **Intelligence Layer**: `formlm_create` / `formlm_modify` wrap the server-side AssessAgent/BuilderAgent pipeline
+- **Chat-only Risk Confirmation**: `formlm_confirm` executes medium/high-risk `formlm_modify` plans after user approval — no web UI needed
+- **Domain Knowledge**: 6 MCP resources expose SKILL.md files directly to AI agents
+- **State Awareness**: `formlm_snapshot` aggregates all module states in one call
+- **P0 Constraints**: Embedded directly in command descriptions — AI sees them every time
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│         AI Agent (any MCP Client: Claude / Cursor /       │
+│           Codex CLI / Windsurf / Cline / ...)             │
+├─────────────────────────────────────────────────────────┤
+│  Tier 0: auth_login, auth_status                         │
+│  Tier 1: formlm_plan, formlm_create,                     │
+│          formlm_modify, formlm_confirm ← Smart Pipeline  │
+│  Tier 2: formlm_snapshot, formlm_skill ← State + Knowledge│
+│  Tier 3: formlm_exec                    ← Direct Commands │
+├─────────────────────────────────────────────────────────┤
+│  Resources: formlm://skills/{form,scale,connect,        │
+│              report,expert,share}                        │
+├─────────────────────────────────────────────────────────┤
+│               formlm-cli MCP Server                      │
+├─────────────────────────────────────────────────────────┤
+│            FormLM Server (McpV1Api)                      │
+│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐    │
+│  │AssessAgent│ │BuilderAgent│ │CliService│ │SKILL.md  │    │
+│  │ (Plan+   │ │ (Think+  │ │ (picocli │ │ (domain  │    │
+│  │  Execute) │ │  Reflect)│ │  dispatch)│ │  rules)  │    │
+│  └──────────┘ └──────────┘ └──────────┘ └──────────┘    │
+└─────────────────────────────────────────────────────────┘
+```
 
 ---
 
@@ -38,7 +68,7 @@ npm install -g @formlm/cli
 
 Requires Node.js ≥ 18.
 
-For a detailed step-by-step guide (including MCP setup for Claude / Cursor), see **[INSTALL.md](INSTALL.md)**.
+For a detailed step-by-step guide (including MCP setup for Claude Desktop / Cursor / Codex CLI / Windsurf / Cline), see **[INSTALL.md](INSTALL.md)**.
 
 ---
 
@@ -52,42 +82,94 @@ formlm-cli auth login
 formlm-cli auth login --token <your-token>
 ```
 
-> You can also get your token from [formlm.me](https://formlm.me): open DevTools → Application → Cookies → copy the `Authorization` value.
-
-### 2. Use the CLI
+### 2. Smart Pipeline (AI-recommended)
 
 ```bash
-# List all apps
-formlm-cli app list
+# Preview the plan before executing (optional, for user review)
+formlm-cli smart plan --input "Create a workplace stress assessment with 10 questions, 3 dimensions"
 
-# Create a new app
-formlm-cli app create --name "Customer Survey" --description "2024 annual survey"
+# Generate a complete assessment app from natural language
+formlm-cli smart create --input "Create a workplace stress assessment with 10 questions, 3 dimensions, and detailed score interpretations"
 
-# Add a field
-formlm-cli field add --app <appId> --id q1 --name "Your Name" --type input --required
+# Modify an existing app
+formlm-cli smart modify --app <appId> --input "Add a new dimension for workplace social support"
 
-# Add a radio field with scores
-formlm-cli field add --app <appId> --id s1 --type radio --options "Satisfied:3,Neutral:2,Unsatisfied:1"
+# If the change is medium/high risk, smart modify returns a plan preview instead of executing.
+# Show the plan to the user, then confirm and execute it (no web UI needed):
+formlm-cli smart confirm --app <appId> --plan-json '<the exact "plan" JSON returned above>'
+```
 
-# Publish the form
-formlm-cli share publish --app <appId>
+### 3. Direct Commands (for fine-grained control)
 
-# Get the shareable URL
-formlm-cli share url --app <appId>
+```bash
+# Get a snapshot of all module states
+formlm-cli snapshot --app <appId>
+
+# Read a skill document before constructing commands
+formlm-cli skill form
+formlm-cli skill scale
+
+# Scale commands
+formlm-cli scale query --app <appId>
+formlm-cli scale add --app <appId> --id stress --name "Stress Level" --format sum --kbText "..."
+formlm-cli scale keys add --app <appId> --scale stress --fields q1,q2,q3
+formlm-cli scale data add --app <appId> --scale stress --ranges "0-10:Low,11-20:Moderate,21-30:High"
+
+# Report commands
+formlm-cli report query --app <appId>
+formlm-cli report page add --app <appId> --name "Summary" --layout grid
+formlm-cli report widget add --app <appId> --page <pageId> --type chart --chartType bar --name "Score Chart"
+
+# Expert commands
+formlm-cli expert query --app <appId>
+formlm-cli expert config --app <appId> --enableChat true
 ```
 
-### 3. Use as MCP Server
+### 4. Use as MCP Server
 
 ```bash
 formlm-cli mcp
 ```
 
-This starts the MCP Server (stdio transport), ready for AI Agents to connect.
+This starts the MCP Server (stdio transport) with 9 tools + 6 resources, ready for AI Agents to connect.
 
 ---
 
 ## Command Reference
 
+### Smart Pipeline (AI-recommended)
+
+```bash
+# Generate a complete app from natural language
+formlm-cli smart create --input "..." [--plan-type assessment] [--style "温暖亲切"] [--question-count 10-15]
+
+# Modify an existing app
+formlm-cli smart modify --app <appId> --input "..."
+
+# Confirm and execute a medium/high risk plan returned by smart modify (skips Think/Plan, no web UI needed)
+formlm-cli smart confirm --app <appId> --plan-json '<exact plan JSON from smart modify>'
+```
+
+### Snapshot
+
+```bash
+# Get all module states in one call
+formlm-cli snapshot --app <appId>
+formlm-cli snapshot --app <appId> --module scale    # Only scale module
+```
+
+### Skill Documents
+
+```bash
+# Get SKILL.md domain knowledge (P0/P1/P2 constraints, command templates)
+formlm-cli skill form       # Form field rules
+formlm-cli skill scale      # Scale dimension rules
+formlm-cli skill connect    # Page styling rules
+formlm-cli skill report     # Report layout rules
+formlm-cli skill expert     # Expert interpretation rules
+formlm-cli skill share      # Share/publish rules
+```
+
 ### Auth
 
 ```bash
@@ -111,9 +193,9 @@ formlm-cli --profile work app list    # Use a profile for one command
 ```bash
 formlm-cli app list
 formlm-cli app create --name "My Form" --description "..."
-formlm-cli app get --app <appId>
 formlm-cli app update --app <appId> --name "New Name" --theme blue
-formlm-cli app delete --app <appId>
+formlm-cli app remove --app <appId>                        # Delete an app (irreversible)
+formlm-cli app urls --app <appId>                          # Get fill-in / editor / data URLs
 ```
 
 ### Field
@@ -123,83 +205,155 @@ formlm-cli field schema                                         # All supported
 formlm-cli field config --type radio                            # Configurable props for a type
 formlm-cli field list --app <appId>
 formlm-cli field find --app <appId> --id q1                     # Get a single field
-formlm-cli field find --app <appId> --filter "name"             # Search fields by keyword
 formlm-cli field add --app <appId> --id q1 --name "Name" --type input --required
-formlm-cli field add --app <appId> --id n1 --type scale --min 1 --max 10
 formlm-cli field update --app <appId> --id q1 --title "Your Full Name"
 formlm-cli field remove --app <appId> --id q1
 formlm-cli field set-property --app <appId> --id q1 --property options.0.score --value 5
 ```
 
-### Share
+### Scale (Dimensions & Scoring)
 
 ```bash
-formlm-cli share publish --app <appId>      # Publish (each respondent can submit once; unlimited respondents)
-formlm-cli share unpublish --app <appId>    # Unpublish
-formlm-cli share query --app <appId>        # Check publish status
-formlm-cli share url --app <appId>              # Get the shareable URL
+formlm-cli scale query --app <appId>                          # List all dimensions
+formlm-cli scale find --app <appId> --id <scaleId>            # Find a dimension
+formlm-cli scale add --app <appId> --id stress --name "Stress" --format sum --kbText "..."
+formlm-cli scale update --app <appId> --id stress --name "Stress Level"
+formlm-cli scale set --app <appId> --id stress --direction negative
+formlm-cli scale remove --app <appId> --id stress
+formlm-cli scale clear --app <appId>
+formlm-cli scale config --app <appId> --enable-single true
+
+# Associate fields with a dimension
+formlm-cli scale keys add --app <appId> --scale stress --fields q1,q2,q3 [--polarities "q3:negative"]
+formlm-cli scale keys remove --app <appId> --scale stress --fields q1
+formlm-cli scale keys list --app <appId> --scale stress
+formlm-cli scale keys set --app <appId> --scale stress --fields q3 --negScore true
+
+# Configure score ranges
+formlm-cli scale data add --app <appId> --scale stress --ranges "0-10:Low,11-20:High"
+formlm-cli scale data update --app <appId> --scale stress --id <dataId> --value "Moderate"
+formlm-cli scale data remove --app <appId> --scale stress --id <dataId>
+formlm-cli scale data list --app <appId> --scale stress
+formlm-cli scale data clear --app <appId> --scale stress
 ```
 
----
+### Connect (Page Styling & Visual Design)
 
-## MCP Integration
+```bash
+formlm-cli connect query --app <appId> [--type cover|main|final] [--filter <keyword>] --md
+formlm-cli connect find --app <appId> --filter <keyword>
+formlm-cli connect types [--category cover|main|final] --verbose
+formlm-cli connect config --category cover --format rich-text
+
+# Cover page management
+formlm-cli connect cover-page add --app <appId> --id cover_main --name "Welcome" --format text --value "<h1>Hello</h1>"
+formlm-cli connect cover-page update --app <appId> --id cover_main --name "New Title"
+formlm-cli connect cover-page find --app <appId> [--id cover_main]
+formlm-cli connect cover-page remove --app <appId> [--id cover_main]
+
+# Final page management
+formlm-cli connect final-page add --app <appId> --id final_report --name "Thank You" --enable-report true
+formlm-cli connect final-page update --app <appId> --id final_report --name "Done"
+formlm-cli connect final-page find --app <appId> [--id final_report]
+formlm-cli connect final-page remove --app <appId> [--id final_report]
+
+# Main page management
+formlm-cli connect main-page set --app <appId> --format card
+formlm-cli connect main-page set --app <appId> --field X1 --description "<p>Context</p>"
+
+# Visual style
+formlm-cli connect style set --app <appId> --type cover --bg "#f3f3fe" --fg "#ffffff" --font "#01105c"
+formlm-cli connect style query --app <appId> --type cover
+formlm-cli connect style apply --app <appId> --look "deep blue tech, frosted glass cards" [--theme Minimal] [--layout flat]
+formlm-cli connect style apply-all --app <appId> --look "light warm Japanese style" [--theme Minimal] [--layout flat]
+formlm-cli connect style move --app <appId> --id <pageId> --direction up
+```
+
+### Report (Pages & Widgets)
 
-### Claude Desktop
+```bash
+formlm-cli report query --app <appId>                           # List all report pages
+formlm-cli report find --app <appId> --filter <keyword>         # Find report widget
+formlm-cli report update --app <appId> --page <pageId> --name "New Name"
+
+# Page management
+formlm-cli report page add --app <appId> --name "Summary" --layout grid
+formlm-cli report page update --app <appId> --id <pageId> --name "Overview"
+formlm-cli report page remove --app <appId> --id <pageId>
+
+# Widget management
+formlm-cli report widget list --app <appId> --page <pageId>
+formlm-cli report widget find --app <appId> --filter <keyword>
+formlm-cli report widget set --app <appId> --id <widgetId> --value "{{TotalScore}}"
+formlm-cli report widget add --app <appId> --page <pageId> --type chart --chartType bar --name "Score Chart"
+formlm-cli report widget update --app <appId> --id <widgetId> --name "Updated Chart"
+formlm-cli report widget remove --app <appId> --id <widgetId>
+formlm-cli report widget types --category chart
+formlm-cli report widget config --type chart --prop chartType
+
+# Logic rules
+formlm-cli report logic add --app <appId> --page <pageId> --condition "score>20" --action show
+formlm-cli report logic list --app <appId> --page <pageId>
+formlm-cli report logic remove --app <appId> --id <logicId>
+```
 
-Add to your `claude_desktop_config.json`:
+### Expert (AI Interpretation)
 
-```json
-{
-  "mcpServers": {
-    "formlm": {
-      "command": "formlm-cli",
-      "args": ["mcp"]
-    }
-  }
-}
+```bash
+formlm-cli expert query --app <appId>                    # Query expert config
+formlm-cli expert find --app <appId>                     # Find expert details
+formlm-cli expert config --app <appId> --enableChat true # Full configuration
+formlm-cli expert set --app <appId> --key model --value gpt-4
+formlm-cli expert avatar --app <appId> --name "Dr. AI" --avatar <url>
+formlm-cli expert remove --app <appId>
+formlm-cli expert chat --app <appId> --message "Explain my score"
 ```
 
-> **No token? No problem.** If you omit `FORMLM_TOKEN`, the AI will prompt you to authenticate via the `auth_login` tool — just provide your token or email + password directly in the chat.
+### Share
 
-### Cursor / VS Code
+```bash
+formlm-cli share publish --app <appId>      # Publish (each respondent can submit once; unlimited respondents)
+formlm-cli share unpublish --app <appId>    # Unpublish
+formlm-cli share query --app <appId>        # Check publish status
+formlm-cli share url --app <appId>          # Get the shareable URL
+```
 
-Add the same block to `.cursor/mcp.json`.
+---
 
-### Let your AI Agent install it
+## MCP Integration
 
-Paste this into any AI chat:
+FormLM CLI works as a standard MCP Server over stdio and plugs into **any MCP-compatible AI platform** — Claude Desktop, Cursor, Codex CLI, Windsurf, Cline, etc.
 
-```
-Help me install FormLM CLI from https://github.com/formlm/cli,
-then run: formlm-cli auth login
-```
+> **⚠️ macOS/Linux users:** desktop AI clients often launch the MCP server without your full terminal PATH, which can cause `command not found` errors. See **[INSTALL.md → Step 4](INSTALL.md#step-4--connect-to-an-ai-agent-mcp-mode)** for the `env.PATH` fix, per-platform config file locations (including Codex CLI's TOML format), and the full setup guide.
+
+> **No token? No problem.** If you omit `FORMLM_TOKEN`, the AI will prompt you to authenticate via the `auth_login` tool — just provide your email + password (or token) directly in the chat.
 
 ---
 
-## Available MCP Tools (20)
+## Available MCP Tools (9)
 
-| Category | Tool | Description |
+| Tier | Tool | Description |
 |---|---|---|
-| Auth | `auth_login` | Login with token or email + password |
-| Auth | `auth_status` | Check current login status |
-| App | `app_list` | List all apps |
-| App | `app_create` | Create a new app |
-| App | `app_get` | Get app details |
-| App | `app_update` | Update app name / description / theme |
-| App | `app_delete` | Delete an app |
-| Field | `field_schema` | List all supported field types |
-| Field | `field_config` | Get configurable properties for a field type |
-| Field | `field_list` | List all fields in an app |
-| Field | `field_find` | Get a single field by ID or keyword |
-| Field | `field_add` | Add a new field |
-| Field | `field_update` | Update a field |
-| Field | `field_remove` | Remove a field |
-| Field | `field_move` | Move a field to a specific position |
-| Field | `field_set_property` | Fine-grained field property update |
-| Share | `share_publish` | Publish the form (each respondent can submit once; unlimited respondents) |
-| Share | `share_unpublish` | Unpublish the form |
-| Share | `share_query` | Query publish status |
-| Share | `share_url` | Get the form fill-in URL |
+| 0 | `auth_login` | Login with token or email + password |
+| 0 | `auth_status` | Check current login status |
+| 1 | `formlm_plan` | Preview execution plan without executing (for user review before create) |
+| 1 | `formlm_create` | Generate a complete app from natural language (AssessAgent pipeline) |
+| 1 | `formlm_modify` | Modify an existing app via natural language (BuilderAgent pipeline) |
+| 1 | `formlm_confirm` | Confirm and execute a medium/high risk plan returned by `formlm_modify` — no web UI needed |
+| 2 | `formlm_snapshot` | Get aggregated state of all modules (form/scale/connect/report/expert/share) |
+| 2 | `formlm_skill` | Fetch SKILL.md domain knowledge for a skill module |
+| 3 | `formlm_exec` | Execute any whitelisted CLI command directly |
+
+## Available MCP Resources (6)
+
+| Resource URI | Description |
+|---|---|
+| `formlm://skills/form` | Form field SKILL.md — P0 constraints, field types, scoring rules |
+| `formlm://skills/scale` | Scale dimension SKILL.md — range rules, polarity, direction |
+| `formlm://skills/connect` | Connect page SKILL.md — theme modes, layout formats |
+| `formlm://skills/report` | Report layout SKILL.md — widget types, variables, logic |
+| `formlm://skills/expert` | Expert interpretation SKILL.md — AI config, chat rules |
+| `formlm://skills/share` | Share/publish SKILL.md — access types, idempotency |
 
 ---
 

package/dist/commands/connect.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function registerConnectCommand(parent: Command): void;
+//# sourceMappingURL=connect.d.ts.map

package/dist/commands/connect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connect.d.ts","sourceRoot":"","sources":["../../src/commands/connect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,CAsd5D"}