@lark-project/meegle 0.0.16 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [v1.0.0] - 2026-04-22
+
+Initial public release of Meegle CLI, published on npm as `@lark-project/meegle`.
+
+### Highlights
+
+- **Broad coverage** — 12 business domains and 40+ commands across work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, and project
+- **Agent-native** — bundled AI Agent Skill for Trae, Claude Code, Cursor, Windsurf, Gemini CLI, and Copilot; structured JSON output designed for both humans and agents
+- **Two-layer parameters** — ergonomic `--flag-name` for everyday use, with a `--params <json>` fallback for complex payloads
+- **Flexible output** — `json` / `table` / `ndjson` / `raw` formats, with `--select` dot-path projection for piping to other tools
+- **Non-interactive auth** — OAuth browser login plus a `--device-code` flow for CI and agent shells
+- **Dry-run previews** — `--dry-run` on mutation commands to inspect the exact payload before sending
+- **Secure by default** — OS keychain credential storage, `${VAR}` env-var templating so secrets stay out of config files, and multi-profile switching for staging / production

package/README.md

@@ -1,21 +1,62 @@
 # Meegle CLI
 
-> **DEV** — Currently in developer preview. APIs and commands may change.
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D16-brightgreen.svg)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/@lark-project/meegle.svg)](https://www.npmjs.com/package/@lark-project/meegle)
+
+[English](./README.md) | [简体中文](./README.zh-CN.md)
 
 Command-line tool for [Meegle](https://meegle.com?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli) ([Lark Project](https://project.feishu.cn?utm_source=github&utm_medium=readme&utm_campaign=meegle_cli)). Manage work items, schedules, and data from your terminal — no browser needed.
 
+[Install](#installation) · [Quick Start](#quick-start-human-users) · [Agent Skill](#ai-agent-skill) · [Commands](#commands) · [Auth](#authentication) · [Config](#configuration) · [Security](#security--risk-warnings) · [Contributing](#contributing)
+
+## Why Meegle CLI?
+
+- **Agent-Native** — Ships a bundled [AI Agent Skill](#ai-agent-skill) that teaches Trae, Claude Code, Cursor, Windsurf, Gemini CLI and other agents how to drive Meegle with one command. Every CLI command is designed for both humans and agents, with structured JSON output, `--dry-run` previews, and `--device-code` flows for non-TTY environments
+- **Broad Coverage** — 12 business domains (work items, workflow, subtasks, comments, work hours, relations, my-work, views, charts, team, user, project) and 40+ commands mapping to Meegle's core capabilities
+- **Two-Layer Parameters** — Ergonomic `--flag-name` for everyday use, fallback `--params <json>` for complex payloads like `fields[]` — pick the right granularity per call
+- **Flexible Output** — `json` / `table` / `ndjson` / `raw`, with `--select` dot-path projection for piping to other tools
+- **Secure by Default** — OS keychain credential storage, `${VAR}` env-var templating so secrets never land in config files, multi-profile switching for staging / prod
+
+## Features
+
+| Category                                           | Capabilities                                                                                   |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 📋 [Work Items](#workitem--work-items)             | Create, read, update, batch-read, query (MQL), list operation records, inspect metadata        |
+| 🔀 [Workflow](#workflow--workflow)                 | Transition nodes & states, update node fields, list available transitions and required fields |
+| ✅ [Subtasks](#subtask--subtasks)                  | Create, update, complete, rollback subtasks                                                    |
+| 💬 [Comments](#comment--comments)                  | Add and list comments on work items                                                            |
+| ⏱️ [Work Hours](#workhour--work-hours)             | List work hour records, view team-member schedules                                             |
+| 🔗 [Relations](#relation--relations)               | List related work items, inspect relation-type definitions                                     |
+| 📌 [My Work](#mywork--my-work)                     | View this week / overdue / completed to-dos                                                    |
+| 👁️ [Views](#view--views)                           | Create and update fixed views, search views by name                                            |
+| 📊 [Charts](#chart--charts)                        | List charts under a view, fetch chart details                                                  |
+| 👥 [Team & User](#team--user--people)              | List teams, team members, search users, view current login                                     |
+| 🗂️ [Projects](#project--projects)                  | Search projects by keyword                                                                     |
+| 🔐 [Auth & Config](#authentication)                | OAuth login, device-code flow, multi-profile config, env-var injection                         |
+| 🤖 [Agent Skill](#ai-agent-skill)                  | Pre-built skill for Trae / Claude Code / Cursor / Windsurf / Gemini CLI / Copilot              |
+
 ## Installation
 
+### Requirements
+
+- Node.js >= 16 (ships with `npm` / `npx`)
+
+### Install
+
 ```bash
 npm install -g @lark-project/meegle
 ```
 
-Requires Node.js >= 16.
+## Quick Start (Human Users)
 
-## Quick Start
+> **Note for AI assistants:** if you are an AI Agent helping the user set this up, jump directly to [Quick Start (AI Agent)](#quick-start-ai-agent--ci--headless) — it contains the non-interactive steps you need.
 
 ```bash
-# 1. Log in
+# (Optional) Persist the host so future logins skip the arrow-key picker
+meegle config set host <host>
+
+# 1. Log in (arrow-key host picker + browser OAuth)
 meegle auth login
 
 # 2. View this week's to-dos
@@ -29,6 +70,85 @@ meegle workitem --help
 meegle inspect workitem.create
 ```
 
+## Quick Start (AI Agent / CI / Headless)
+
+The default `meegle auth login` uses an arrow-key host picker plus a browser OAuth callback — both require a real TTY, so they will hang or fail in CI runners, pipes, and agent shells like Claude Code. Use the Device Code flow instead: it prints an authorization URL that the user opens in any browser.
+
+**Step 1 — Install the CLI**
+
+```bash
+npm install -g @lark-project/meegle
+```
+
+**Step 2 — Persist the host**
+
+```bash
+meegle config set host <host>
+```
+
+Examples of `<host>`: `project.feishu.cn`, `meegle.com`, or your self-hosted tenant domain such as `your-tenant.example.com`.
+
+**Step 3 — Log in with Device Code**
+
+> Run this command in the background. It prints an authorization URL — extract it and send it to the user. The command exits automatically once the user completes authorization in the browser.
+
+```bash
+meegle auth login --device-code
+```
+
+Alternatively, pass the host inline each time without persisting it:
+
+```bash
+meegle auth login --device-code --host <host>
+```
+
+**Step 4 — Verify**
+
+```bash
+meegle auth status
+```
+
+For fully unattended CI (no human-in-the-loop), inject a token via environment variables instead — see [Sandbox / CI](#sandbox--ci-direct-environment-variable-injection).
+
+## AI Agent Skill
+
+`skills/meegle/` is a drop-in **skill** that teaches AI Agents — Trae, Claude Code, Cursor, Windsurf, Gemini CLI, GitHub Copilot CLI — how to operate Meegle through this CLI. It bundles the command catalog, MQL syntax, field-value conventions, rich-text Markdown rules, and standard operating procedures for common write flows.
+
+### Install
+
+```bash
+# Install the CLI first (the skill calls `meegle` under the hood)
+npm install -g @lark-project/meegle
+
+# Then add the skill — auto-detects installed agents and registers in each
+npx skills add larksuite/meegle-cli -y -g
+```
+
+`npx skills add` reads `skills/meegle/SKILL.md` from the repo and drops it into the skill directory of every agent CLI it finds on the machine. Re-run any time to pick up updates.
+
+### What it covers
+
+- **Command reference** — every `meegle` resource / method with required parameters and examples
+- **MQL search** — syntax for `workitem query`, operators, scope keywords
+- **Field values** — how to shape complex field payloads (arrays, nested JSON, date ranges)
+- **Rich text** — Markdown subset supported by Meegle's rich-text editor
+- **SOPs** — step-by-step playbooks for creating work items, transitioning nodes, transitioning states, and updating fields
+- **Auth guard** — the skill refuses to run business commands until `meegle auth status` succeeds
+
+See [skills/meegle/SKILL.md](./skills/meegle/SKILL.md) and [skills/meegle/references/](./skills/meegle/references/) for the full contents.
+
+### Usage
+
+Once installed, just ask the agent in natural language. For example, in Trae:
+
+```
+Show me this week's P0 stories in the PROJ space.
+```
+
+The agent consults the skill, picks the right `meegle` commands, and runs them for you. Pair with `--dry-run` (see [Security](#security--risk-warnings)) to preview side-effectful operations before the agent commits them.
+
+> Heads up: the skill name `meegle` is the same string as the CLI binary. When documentation refers to "the **`meegle` skill**" it means the files in `skills/meegle/`; when it refers to "the **`meegle` CLI**" it means the `meegle` command on your PATH.
+
 ## Commands
 
 ### workitem — Work Items
@@ -37,6 +157,7 @@ meegle inspect workitem.create
 |---------|-------------|
 | `workitem create` | Create a work item |
 | `workitem get` | View work item details |
+| `workitem +batch-get` | Batch-read work items by IDs (client-side fan-out over `workitem get`; `+` marks scenario/sugar commands) |
 | `workitem update` | Update work item fields |
 | `workitem query` | Search work items using MQL |
 | `workitem list-op-records` | View operation records |
@@ -172,18 +293,57 @@ meegle workitem get --work-item-id 12345
 meegle workflow get-node --work-item-id 12345 --need-sub-task
 ```
 
+### Batch Reading Work Items
+
+`workitem +batch-get` fans out to `workitem get` for each ID and aggregates the
+results into one response. Shared flags (e.g. `--project-key`) apply to every
+per-item call. The `+` prefix marks it as a scenario/sugar command with no 1:1
+MCP tool behind it — the CLI composes multiple `get` calls client-side.
+
+```bash
+# Comma-separated IDs in one invocation
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346,12347"
+
+# Read IDs from a file (one per line; lines starting with '#' are comments)
+meegle workitem +batch-get --project-key PROJ --ids-file ./ids.txt
+
+# Stream one JSON row per item; summary row is emitted last
+meegle workitem +batch-get --project-key PROJ --work-item-ids "12345,12346" -o ndjson
+```
+
+Response envelope (JSON):
+
+```json
+{
+  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
+  "results": [
+    { "work_item_id": 12345, "data": { /* ... */ } },
+    { "work_item_id": 12346, "data": { /* ... */ } },
+    { "work_item_id": 12347, "error": { "code": "...", "message": "..." } }
+  ]
+}
+```
+
+Constraints: up to 200 IDs per invocation, 3 concurrent workers (fixed).
+Partial failures do **not** abort the batch — check `summary.failed` or the
+per-item `error` field. A 401 from the server aborts the whole run.
+
 ### Creating Work Items
 
 ```bash
-# Use --set to set fields
+# Pass fields[] via --params (JSON)
 meegle workitem create --project-key PROJ --work-item-type story \
-  --set name="Optimize login flow" \
-  --set priority=P1
+  --params '{"fields":[
+    {"field_key":"name","field_value":"Optimize login flow"},
+    {"field_key":"priority","field_value":"P1"}
+  ]}'
 
-# Pass JSON values for complex fields
+# Complex field values (arrays, nested JSON) also go through --params
 meegle workitem create --project-key PROJ --work-item-type story \
-  --set name="Scheduled task" \
-  --set schedule='[1722182400000,1722355199999]'
+  --params '{"fields":[
+    {"field_key":"name","field_value":"Scheduled task"},
+    {"field_key":"schedule","field_value":[1722182400000,1722355199999]}
+  ]}'
 ```
 
 ### Updating Fields
@@ -191,12 +351,14 @@ meegle workitem create --project-key PROJ --work-item-type story \
 ```bash
 # Update work item name
 meegle workitem update --work-item-id 12345 \
-  --set name="New title"
+  --params '{"fields":[{"field_key":"name","field_value":"New title"}]}'
 
 # Update multiple fields at once
 meegle workitem update --work-item-id 12345 \
-  --set name="New title" \
-  --set priority=P0
+  --params '{"fields":[
+    {"field_key":"name","field_value":"New title"},
+    {"field_key":"priority","field_value":"P0"}
+  ]}'
 ```
 
 ### MQL Search
@@ -232,19 +394,31 @@ Each command takes parameters via `--flag-name`:
 meegle workitem get --work-item-id 12345 --project-key PROJ
 ```
 
-### --set key=value (Write Commands)
+### Writing `fields[]` (Write Commands)
 
-`workitem create`, `workitem update`, `workflow update-node`, and `subtask update` support `--set` for convenient field assignment:
+`workitem create`, `workitem update`, `workflow update-node`, and `subtask update` expect the `fields[]` payload. Pass it through `--params`:
 
 ```bash
---set name="Title"              # String
---set points=5                  # Number
---set is_urgent=true            # Boolean
---set schedule='[1,2]'          # JSON array
---set role='{"role":"RD"}'      # JSON object
+--params '{"fields":[
+  {"field_key":"name","field_value":"Title"},
+  {"field_key":"priority","field_value":"P1"}
+]}'
 ```
 
-`--set` can be repeated to set multiple fields at once.
+### --set key=value (Generic)
+
+`--set` is an alternate syntax for writing **top-level** parameters — `--set key=value` is equivalent to typing `--key value`. Useful when scripting with a uniform `key=value` form, or for writing nested top-level params via dot-path. Values are auto-typed (int / float / bool / string).
+
+```bash
+# These two are equivalent:
+meegle mywork todo --action this_week --page-num 1
+meegle mywork todo --set action=this_week --set page_num=1
+
+# Dot-path builds nested maps (rarely used in Meegle, but supported):
+--set extra.flag=true          # becomes {"extra":{"flag":true}}
+```
+
+`--set` only writes **top-level** parameters. To write a work item's `fields[]`, use `--params '{"fields":[...]}'` (see below).
 
 ### --params JSON (Fallback)
 
@@ -259,8 +433,8 @@ meegle workitem create --project-key PROJ --work-item-type story \
 
 When `--set`, `--params`, and regular flags are used together:
 
-1. `--set` overrides fields with the same name in `--params`
-2. Regular flags (e.g. `--project-key`) override top-level keys in `--params`
+1. Regular CLI flags beat `--params` / `--set` for the same top-level key
+2. `--set` overrides the same top-level key from `--params`
 
 ### Array Parameters
 
@@ -283,7 +457,7 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 
 | Flag | Short | Description |
 |------|-------|-------------|
-| `--format` | `-o` | Output format: `json` (default), `table`, `ndjson`, `yaml`, `markdown`, `raw` |
+| `--format` | `-o` | Output format: `json` (default), `table`, `ndjson`, `raw` |
 | `--select` | | Field projection with dot paths |
 | `--set` | | Set nested parameters (repeatable) |
 | `--params` | `-P` | Full JSON parameter body |
@@ -291,47 +465,71 @@ meegle workflow get-node --work-item-id 12345 --need-sub-task
 | `--verbose` | `-v` | Verbose output |
 | `--profile` | | Use a specific configuration profile |
 
-## Output Formats
+## Advanced Usage
+
+### Output Formats
 
 ```bash
 # JSON (default)
 meegle workitem get --work-item-id 12345
 
-# Select output properties (supports dot paths)
-meegle workitem get --work-item-id 12345 --select "id,name,status"
-meegle mywork todo --action done --page-num 1 --select "list.work_item_info.work_item_name"
-
 # NDJSON (suitable for piping)
 meegle mywork todo --action this_week --page-num 1 -o ndjson
 
 # Table
 meegle mywork todo --action this_week --page-num 1 -o table
+```
+
+### Field Projection with `--select`
 
-# YAML
-meegle workitem get --work-item-id 12345 -o yaml
+`--select` projects fields using `.` notation. A segment after an array
+broadcasts the remaining path over every record of the array and
+collects the results while preserving the enclosing structure.
 
-# Markdown table
-meegle mywork todo --action this_week --page-num 1 -o markdown
+| Expression | Response | Projection |
+|---|---|---|
+| `list` | `{"list":[{"a":1}], "total":1}` | `{"list":[{"a":1}]}` |
+| `list.a` | `{"list":[{"a":1,"b":2},{"a":3,"b":4}]}` | `{"list":[{"a":1},{"a":3}]}` |
+| `list.a,list.b` | same as above | `{"list":[{"a":1,"b":2},{"a":3,"b":4}]}` (merged per index) |
+| `list.work_item_info.work_item_name` | `{"list":[{"work_item_info":{"work_item_name":"x"}}]}` | `{"list":[{"work_item_info":{"work_item_name":"x"}}]}` |
+| `nodes.0` | `{"nodes":[{"id":"a"},{"id":"b"}]}` | `{"nodes":{"0":{"id":"a"}}}` (numeric = index) |
 
-# Dry run (preview request without sending)
-meegle workitem create --project-key PROJ --work-item-type story --set name="Test" --dry-run
+```bash
+# Top-level selection
+meegle workitem get --work-item-id 12345 --select "id,name,status"
+
+# Broadcast across arrays — extract fields from nested records
+meegle mywork todo --action done --page-num 1 \
+  --select "list.work_item_info.work_item_name,list.state_info.end_state_key_name"
+
+# Mix top-level metadata with broadcast — total is retained alongside projected list items
+meegle mywork todo --action done --page-num 1 \
+  --select "total,list.work_item_info.work_item_name"
 ```
 
-### --select Dot Paths
+### Metadata preservation
 
-`--select` supports `.` notation for nested properties, automatically traversing arrays:
+The default render preserves the full response shape across every
+`--format`: list endpoints return `{"list":[...], "total":N,
+"pagination":{...}}` verbatim — you see `total` / `pagination` even
+when you do not project them. Drill into records explicitly via
+`--select` (and the broadcast syntax above). Under `--format table`
+and `--format ndjson`, a single-key wrapper like `{"list":[...]}`
+(no sibling metadata) is still peeled into rows — the peel is
+loss-less.
 
-```bash
-# Extract fields from nested structures
---select "list.work_item_info.work_item_name,list.state_info.end_state_key_name"
+### Dry Run
 
-# Mix top-level and nested
---select "total,list.work_item_info.work_item_name"
+For commands with side effects, preview the rendered request with `--dry-run` before executing:
+
+```bash
+meegle workitem create --project-key PROJ --work-item-type story \
+  --params '{"fields":[{"field_key":"name","field_value":"Test"}]}' --dry-run
 ```
 
-## Command Introspection
+### Command Introspection
 
-Use `inspect` to view full parameter information for a command:
+Use `inspect` to view full parameter information for any command:
 
 ```bash
 # List all commands
@@ -394,6 +592,57 @@ Main config options:
 | Field | Description | Examples |
 |-------|-------------|----------|
 | `host` | Site domain | `project.feishu.cn`, `meegle.com` |
+| `user_access_token` | User access token; use `${VAR}` to read from an environment variable | `${CI_MEEGLE_TOKEN}` |
+| `access_token_header` | Custom HTTP header name that carries the token; empty falls back to default `Authorization: Bearer <token>` | `x-meegle-auth` |
+| `user_agent` | Caller suffix appended to the default `User-Agent` (form: `meegle-cli/<ver> <user_agent>`); supports `${VAR}` template; overridden by the `MEEGLE_USER_AGENT` env var | `my-service/1.0` |
+
+### Sandbox / CI: Direct Environment-Variable Injection
+
+Two well-known environment variables are read directly at CLI startup and override the matching profile fields without requiring any `config set`:
+
+```bash
+export MEEGLE_HOST=project.feishu.cn
+export MEEGLE_USER_ACCESS_TOKEN=<your-user-token>
+export MEEGLE_USER_AGENT=ci-runner  # optional; appended to User-Agent, highest priority over config.user_agent
+meegle workitem get-brief --work_item_id 123
+```
+
+Either variable may be set independently. When this path is taken, the CLI bypasses the keychain and does not attempt to refresh on 401 — the caller is responsible for rotating the env value.
+
+### Custom Auth Header
+
+By default the token is sent via the standard `Authorization: Bearer <token>` header. If the backend requires a different header (and rejects requests that carry `Authorization`), opt in with `access_token_header`:
+
+```bash
+meegle config set access_token_header x-meegle-auth
+```
+
+Or override at runtime via env var:
+
+```bash
+export MEEGLE_ACCESS_TOKEN_HEADER=x-meegle-auth
+```
+
+When enabled the CLI sends `<header>: <token>` with the raw token (no `Bearer ` prefix) and **omits `Authorization` entirely** — suitable for backends that reject requests carrying both headers.
+
+### Environment Variable Templates
+
+If your runtime exposes a variable with a name other than `MEEGLE_*`, bind it through `config.json` using a `${VAR}` placeholder. The placeholder is resolved against the process environment at runtime. This keeps secrets out of `config.json` while adapting to whatever variable name your runtime (Docker, Kubernetes, CI system) already injects.
+
+```json
+{
+  "current": "prod",
+  "profiles": {
+    "prod":    { "host": "project.feishu.cn", "user_access_token": "${PROD_CI_TOKEN}" },
+    "staging": { "host": "staging.feishu.cn", "user_access_token": "${STAGING_CI_TOKEN}" }
+  }
+}
+```
+
+Rules:
+- Only whole-string placeholders are recognized. `"${X}"` is expanded; `"Bearer ${X}"` is treated as a literal.
+- When a referenced variable is unset or empty, the CLI fails fast and reports the field path and variable name.
+- When `user_access_token` is configured, it takes precedence over any token stored locally by `meegle auth login`. Because this mode has no refresh path, rotate the environment value yourself when the server returns 401.
 
 ### Multi-Environment Profiles
 
@@ -431,6 +680,34 @@ meegle auth login
 
 The command list is cached automatically and refreshed silently in the background when expired.
 
+## Security & Risk Warnings
+
+This tool is designed to be called by AI Agents to automate Meegle operations, which carries inherent risks — model hallucinations, unpredictable execution, and prompt injection. Once you authorize Meegle permissions, the Agent will act under your user identity within the granted scope, and may perform high-impact actions (field updates, status transitions, work item creation) on your behalf. Use with care.
+
+Recommended safeguards:
+
+- Preview side-effectful commands with `--dry-run` before running them
+- Use a dedicated profile (`meegle config profile create`) for Agent-driven sessions so you can audit and revoke independently
+- For CI / shared environments, prefer short-lived env-var token injection (`MEEGLE_USER_ACCESS_TOKEN`) and rotate on 401 — do not relax default security settings
+
+By using this tool you are deemed to voluntarily assume all related responsibilities.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=larksuite/meegle-cli&type=Date)](https://star-history.com/#larksuite/meegle-cli&Date)
+
+## Contributing
+
+Community contributions are welcome. For bugs and feature requests, open an [Issue](https://github.com/larksuite/meegle-cli/issues) or [Pull Request](https://github.com/larksuite/meegle-cli/pulls). For major changes, please start a discussion via an Issue first.
+
 ## License
 
-MIT © Lark Technologies Pte. Ltd.
+This project is licensed under the **MIT License**.
+
+When running, it calls Lark/Feishu Open Platform APIs. To use these APIs, you must comply with the following agreements and privacy policies:
+
+- [Feishu User Terms of Service](https://www.feishu.cn/terms)
+- [Feishu Privacy Policy](https://www.feishu.cn/privacy)
+- [Feishu Open Platform App Service Provider Security Management Specifications](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/management-practice/app-service-provider-security-management-specifications)
+- [Lark User Terms of Service](https://www.larksuite.com/user-terms-of-service)
+- [Lark Privacy Policy](https://www.larksuite.com/privacy-policy)