meegle-cli 0.1.0

package/README.md

@@ -0,0 +1,215 @@
+# meegle-cli (plugin-only)
+
+基于 `project-oapi-sdk-typescript` 的命令行工具。  
+当前模式：仅支持 `plugin_access_token / virtual_plugin_token`，不支持 `user_access_token`。
+
+## 安装
+
+对外用户安装：
+
+```bash
+npm install -g meegle-cli
+meegle --help
+```
+
+仓库内开发安装：
+
+```bash
+cd /Users/linmi/conductor/repos/meego-client/meegle-cli
+npm install
+```
+
+## 构建
+
+```bash
+npm run build
+```
+
+## 发布
+
+发布说明见 [RELEASE.md](/Users/linmi/conductor/repos/meego-client/meegle-cli/RELEASE.md)。
+
+## 初始化
+
+```bash
+node dist/index.js auth init \
+  --target-profile default \
+  --plugin-id MII_xxx \
+  --plugin-secret xxx \
+  --base-url https://project.feishu.cn \
+  --token-type 0 \
+  --default-user-key 123456
+```
+
+也可以先放环境变量，再直接初始化：
+
+```bash
+export MEEGLE_PLUGIN_ID=MII_xxx
+export MEEGLE_PLUGIN_SECRET=xxx
+export MEEGLE_USER_KEY=123456
+
+node dist/index.js auth init --target-profile default
+```
+
+## 入参约定
+
+- 常用查询优先走直接参数，不再强制写 JSON 文件
+- 常用写操作也优先走直接参数，例如 `--name`、`--desc`、`--content`
+- 复杂请求体仍可使用 `--body <json>` 或 `--body-file <path>`
+- 复杂查询参数仍可使用 `--query-file <path>`
+- 大多数命令要求 `userKey`：`--user-key` 或 `auth init --default-user-key`
+- 如果 profile 里没存 `defaultUserKey`，运行时也会读取 `MEEGLE_USER_KEY`
+- 自定义字段统一使用 `--field field_key=value`；对象/数组值直接传 JSON
+- 排期参数统一支持 `--start/--end`，可传毫秒时间戳或可解析日期，如 `2025-01-01`
+
+## 命令总览
+
+- `auth`: `init`, `status`
+- `space`: `list`, `get`, `types`, `team-members`
+- `workitem`: `get`, `meta`, `create`, `update`, `remove`, `freeze`, `unfreeze`, `abort`, `restore`, `op-records`, `update-compound`
+- `workitem search`: `filter`, `filter-across`, `by-params`, `by-relation`, `compositive`, `universal`
+- `workflow`: `query`, `state-change`, `node-operate`, `node-update`, `required-info`, `wbs`
+- `comment`: `list`, `add`, `update`, `remove`
+- `subtask`: `list`, `search`, `create`, `update`, `remove`, `operate`
+- `attachment`: `upload-file`, `upload`, `download`, `delete`
+- `workhour`: `list`, `create`, `update`, `delete`
+- `view`: `list`, `fix-items`, `panoramic-items`, `create-fix`, `update-fix`, `delete`, `create-condition`, `update-condition`
+- `measure`: `charts`, `chart-data`
+- `tenant`: `info`, `entitlement`, `spaces`
+- `user`: `query`, `search`（会被拒绝）
+- `user group`: `create`, `update-members`, `query-members`（会被拒绝）
+
+## 真实环境 Smoke（可选）
+
+执行：
+
+```bash
+npm run test:smoke:real
+```
+
+必填环境变量：
+
+- `MEEGLE_SMOKE_PLUGIN_ID`
+- `MEEGLE_SMOKE_PLUGIN_SECRET`
+- `MEEGLE_SMOKE_USER_KEY`
+- `MEEGLE_SMOKE_PROJECT_KEY`
+
+可选环境变量：
+
+- `MEEGLE_SMOKE_BASE_URL`（默认 `https://project.feishu.cn`）
+- `MEEGLE_SMOKE_WORK_ITEM_TYPE_KEY`（不填时自动取 `space types` 第一项）
+- `MEEGLE_SMOKE_WORK_ITEM_ID`（填了会额外做 `workitem get`）
+
+测试链路：
+
+- `auth init -> auth status -> space list -> space get -> user query --self -> space types -> workitem meta`
+- 若提供 `MEEGLE_SMOKE_WORK_ITEM_ID`，再执行 `workitem get`
+- 最后验证 user-only 接口在 plugin-only 下被拒绝
+
+`MEEGLE_SMOKE_USER_KEY` 获取建议：
+
+- 文档建议可在飞书项目空间双击头像获取 `user_key`
+- 如果你在插件前端里调试，JS SDK 文档里有 `window.JSSDK.utils.getAuthCode()`；虽然该方法用于 user token 流程，但同一套文档章节也包含用户身份相关取值指引
+
+## plugin-only 拒绝列表（denylist）
+
+- `POST /open_api/user/search`
+- `POST /open_api/:project_key/user_group`
+- `PATCH /open_api/:project_key/user_group/members`
+- `POST /open_api/:project_key/user_groups/members/page`
+
+## 示例
+
+```bash
+# 1) 校验凭证
+node dist/index.js --profile default auth status --json
+
+# 2) 列出空间
+node dist/index.js --profile default space list --json
+
+# 3) 获取空间详情
+node dist/index.js --profile default space get \
+  --project-key your_project \
+  --json
+
+# 4) 查询当前 userKey 对应的用户
+node dist/index.js --profile default user query \
+  --self \
+  --json
+
+# 5) 查询工作项，常见场景直接传 ID
+node dist/index.js --profile default workitem get \
+  --project-key your_project \
+  --type story \
+  --id 6300034462 \
+  --json
+
+# 6) 创建工作项，常见字段直接写
+node dist/index.js --profile default workitem create \
+  --project-key your_project \
+  --type story \
+  --name "登录优化" \
+  --desc "补齐错误提示" \
+  --owner your_user_key \
+  --priority P2 \
+  --json
+
+# 7) 更新工作项，改单个字段不需要写 update_fields
+node dist/index.js --profile default workitem update \
+  --project-key your_project \
+  --type story \
+  --id 6300034462 \
+  --name "登录优化（已排期）" \
+  --json
+
+# 8) 添加评论，支持直接写文本或从文件读
+node dist/index.js --profile default comment add \
+  --project-key your_project \
+  --type story \
+  --id 6300034462 \
+  --content "收到，开始处理" \
+  --json
+
+# 9) 创建子任务
+node dist/index.js --profile default subtask create \
+  --project-key your_project \
+  --type story \
+  --id 6300034462 \
+  --node-id doing \
+  --name "需求分析" \
+  --note "补齐边界条件" \
+  --assignee your_user_key \
+  --points 3 \
+  --start 2025-01-01 \
+  --end 2025-01-02 \
+  --json
+
+# 10) 状态流转
+node dist/index.js --profile default workflow state-change \
+  --project-key your_project \
+  --type story \
+  --id 6300034462 \
+  --transition-id 12345 \
+  --field description="流转补充说明" \
+  --json
+
+# 11) 节点完成/回滚
+node dist/index.js --profile default workflow node-operate \
+  --project-key your_project \
+  --type story \
+  --id 6300034462 \
+  --node-id dev \
+  --action rollback \
+  --rollback-reason "需要返工" \
+  --json
+
+# 12) 复杂场景再回退到原始请求体
+node dist/index.js --profile default workitem get \
+  --project-key your_project \
+  --type story \
+  --body '{"work_item_ids":[6300034462],"fields":["name","priority"]}' \
+  --json
+
+# 13) user-only 接口会被直接拒绝
+node dist/index.js user search --query test
+```

package/RELEASE.md

@@ -0,0 +1,77 @@
+# meegle-cli Release
+
+## 当前结论
+
+- 包名：`meegle-cli`
+- 可执行命令：`meegle`
+- 2026-03-17 验证结果：
+  - `meeglesdk@0.1.7` 已存在于 npm registry
+  - `meegle-cli` 当前未在 npm registry 上占用
+
+## 发布前检查
+
+```bash
+cd /Users/linmi/conductor/repos/meego-client/meegle-cli
+npm install
+npm run release:check
+```
+
+`release:check` 会执行：
+
+1. `npm test`
+2. `npm run build`
+3. `npm pack --dry-run`
+
+目标是确保：
+
+- 测试通过
+- 发布包只包含 `dist/README.md/RELEASE.md`
+- 不再携带 `src/` 和测试产物
+
+## 首次发布
+
+```bash
+cd /Users/linmi/conductor/repos/meego-client/meegle-cli
+npm login
+npm publish
+```
+
+发布成功后，外部用户安装方式：
+
+```bash
+npm install -g meegle-cli
+meegle --help
+```
+
+## 后续版本发布
+
+```bash
+cd /Users/linmi/conductor/repos/meego-client/meegle-cli
+npm version patch
+npm publish
+```
+
+也可以把 `patch` 改成 `minor` 或 `major`。
+
+## 本地联调 SDK
+
+对外发布时，CLI 依赖的是 npm 上的 `meeglesdk@0.1.7`。  
+如果你在本仓库内同时修改 SDK 和 CLI，建议显式切回本地安装：
+
+```bash
+cd /Users/linmi/conductor/repos/meego-client/meegle-cli
+npm install ../project-oapi-sdk-typescript
+```
+
+联调结束后，发布前再恢复：
+
+```bash
+cd /Users/linmi/conductor/repos/meego-client/meegle-cli
+npm install meeglesdk@0.1.7
+```
+
+## 风险提醒
+
+- `pluginId/pluginSecret` 不能写进 README 示例或测试默认环境变量
+- `test:smoke:real` 依赖真实凭证，不能挂到 `prepublishOnly`
+- 如果后续需要私有 scope，再补 `publishConfig.access=public`

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function buildCli(): Command;