@metaphorli/pingcode-cli 0.3.2 → 0.3.3

package/README.md

@@ -15,10 +15,12 @@ npx @metaphorli/pingcode-cli@latest
 ~/.codex/skills/pingcode/references/auth.md
 ~/.codex/skills/pingcode/references/ctx.md
 ~/.codex/skills/pingcode/references/workitem.md
+~/.codex/skills/pingcode/references/comment.md
 ~/.config/opencode/skills/pingcode
 ~/.config/opencode/skills/pingcode/references/auth.md
 ~/.config/opencode/skills/pingcode/references/ctx.md
 ~/.config/opencode/skills/pingcode/references/workitem.md
+~/.config/opencode/skills/pingcode/references/comment.md
 ```
 
 默认会进入交互式安装，先选择“全局 / 项目级”，再选择要安装的 Agent；在 CI 或脚本中可以使用 `--non-interactive` 保持旧的静默自动安装行为。任何一个已选择目录写入失败（权限、磁盘等问题）不会阻断其他目录，安装结束时会打印每个目录的成功/失败/跳过摘要。
@@ -120,9 +122,12 @@ npx @metaphorli/pingcode-cli@latest --target ".opencode/skills" --force
 - 查询项目、迭代、看板、工作项类型、状态、优先级
 - 查询、创建、更新工作项（含状态更新，支持 `--dry-run` 试运行）
 - 在故事下创建子工作项（通过 `--parent`）
-- 通过子命令（`context *`, `workitem *`, `auth *`）调用 PingCode API
+- 创建、查看、删除工作项评论（通过 `--reply-to` 支持回复）
+- 查询、创建、更新需求（idea）
+- 查询产品列表和产品详情（`product list / get`）
+- 通过子命令（`context *`, `workitem *`, `auth *`, `comment *`, `idea *`, `product *`）调用 PingCode API
 
-以上能力由同一个 `pingcode` skill 统一提供，并通过 `references/` 下的 `auth.md`、`ctx.md`、`workitem.md` 分别补充用户令牌登录、工作区上下文初始化、工作项操作的详细参考。
+以上能力由同一个 `pingcode` skill 统一提供，并通过 `references/` 下的 `auth.md`、`ctx.md`、`workitem.md`、`comment.md` 分别补充用户令牌登录、工作区上下文初始化、工作项操作、评论操作的详细参考。
 
 ## Skill 结构
 
@@ -133,7 +138,10 @@ npx @metaphorli/pingcode-cli@latest --target ".opencode/skills" --force
 | `pingcode/SKILL.md` | 路由入口，统一提供 PingCode CLI 的各项能力 |
 | `pingcode/references/auth.md` | 用户令牌登录：`pingcode auth login`、grant-type 自动识别与覆盖、令牌类型说明 |
 | `pingcode/references/ctx.md` | 工作区上下文初始化：在 Agent 前台按编号选择当前项目、迭代、用户并写入缓存 |
-| `pingcode/references/workitem.md` | 工作项操作：`workitem list / create / show / get / update` 子命令及完整参数；含共享安全规则 |
+| `pingcode/references/workitem.md` | 工作项操作：`workitem list / create / get / update` 子命令及完整参数；含共享安全规则 |
+| `pingcode/references/idea.md` | 需求操作：`idea list / create / update / get / search` 等子命令及安全规则 |
+| `pingcode/references/product.md` | 产品操作：`product list / get` 子命令及安全规则 |
+| `pingcode/references/comment.md` | 评论操作：`comment create / list / get / delete` 子命令及安全规则 |
 
 ## 子命令
 
@@ -144,7 +152,7 @@ PingCode CLI 通过子命令管理配置和工作项。
 | 子命令 | 说明 | 示例 |
 |---|---|---|
 | `context init` | 交互式初始化工作区上下文 | `pingcode context init` |
-| `context list` | 显示当前偏好和字典摘要 | `pingcode context list` |
+| `context list` | 以 JSON 输出当前偏好和字典条目数量 | `pingcode context list` |
 | `context set-current-user <id>` | 设置当前用户 | `pingcode context set-current-user @me` |
 | `context set-current-project <id>` | 设置当前项目 | `pingcode context set-current-project PROJECT_ID` |
 | `context set-current-sprint <id>` | 设置当前迭代 | `pingcode context set-current-sprint SPRINT_ID` |
@@ -166,8 +174,7 @@ pingcode context set-current-project my-project
 |---|---|---|
 | `workitem list` | 列出工作项（自动加当前用户/项目/迭代过滤） | `pingcode workitem list --assignee @me --state 进行中` |
 | `workitem create` | 创建工作项 | `pingcode workitem create --title "新任务" --type task` |
-| `workitem show <id>` | 查看单个工作项（通过列表接口按 id 或 identifier 查询） | `pingcode workitem show SCR-123` |
-| `workitem get <id|identifier>` | 获取单个工作项（官方单个工作项接口；identifier 会先解析为 id） | `pingcode workitem get WORK_ITEM_ID` |
+| `workitem get <id|identifier>` | 获取单个工作项（官方单个工作项接口；identifier 会先解析为 id） | `pingcode workitem get SCR-123` |
 | `workitem update <id>` | 更新工作项 | `pingcode workitem update SCR-123 --state 已完成` |
 
 ```bash
@@ -183,8 +190,8 @@ pingcode workitem list --keywords "登录页面" --compact
 # 创建工作项（默认负责人为当前用户）
 pingcode workitem create --title "实现登录页面" --type task --project "Core" --sprint "Sprint 1"
 
-# 通过编号查看工作项
-pingcode workitem show SCR-123
+# 通过编号获取工作项
+pingcode workitem get SCR-123
 
 # 通过 id 获取单个工作项（官方单个工作项接口）
 pingcode workitem get WORK_ITEM_ID
@@ -203,6 +210,58 @@ pingcode workitem create --title "test" --type task --dry-run
 pingcode workitem update SCR-123 --state 已完成 --dry-run
 ```
 
+### 产品管理 (`product`)
+
+| 子命令 | 说明 | 示例 |
+|---|---|---|
+| `product list` | 列出产品 | `pingcode product list --compact` |
+| `product get <id>` | 获取单个产品详情 | `pingcode product get PRODUCT_ID` |
+
+```bash
+# 查看产品列表
+pingcode product list --compact
+
+# 按关键词搜索产品
+pingcode product list --keywords "核心产品" --compact
+
+# 获取产品详情
+pingcode product get PRODUCT_ID
+
+# 试运行（预览 API 请求，不发送）
+pingcode product list --dry-run
+pingcode product get PRODUCT_ID --dry-run
+```
+
+### 评论管理 (`comment`)
+
+| 子命令 | 说明 | 示例 |
+|---|---|---|
+| `comment create <id\|identifier>` | 创建工作项评论 | `pingcode comment create SCR-123 --content "需要优化性能"` |
+| `comment list <id\|identifier>` | 列出工作项评论 | `pingcode comment list SCR-123 --compact` |
+| `comment get <comment-id> <id\|identifier>` | 获取单条评论 | `pingcode comment get cmt-456 SCR-123` |
+| `comment delete <comment-id> <id\|identifier>` | 删除评论 | `pingcode comment delete cmt-456 SCR-123` |
+
+```bash
+# 创建工作项评论
+pingcode comment create SCR-123 --content "这个工作项需要考虑性能优化"
+
+# 创建回复评论
+pingcode comment create SCR-123 --content "已确认，稍后处理" --reply-to cmt-456
+
+# 查看评论列表
+pingcode comment list SCR-123 --compact
+
+# 获取单条评论
+pingcode comment get cmt-456 SCR-123
+
+# 删除评论
+pingcode comment delete cmt-456 SCR-123
+
+# 试运行（预览 API 请求，不发送）
+pingcode comment create SCR-123 --content "hello" --dry-run
+pingcode comment delete cmt-456 SCR-123 --dry-run
+```
+
 ## 凭证配置
 
 在 PingCode 企业后台创建应用，配置数据访问范围，然后设置环境变量：
@@ -231,9 +290,12 @@ export PINGCODE_USER_ID="你的 PingCode 用户 ID"
 除了 `client_credentials` 企业令牌，CLI 也支持通过 OAuth2 `authorization_code` 获取用户令牌。用户令牌代表具体的人类用户，适合需要以个人身份操作 PingCode 的场景。
 
 ```bash
-# 在浏览器中完成授权
+# 默认行为：打印授权 URL 并提示粘贴授权码
 pingcode auth login --client-id ID --client-secret SECRET
 
+# 自动打开浏览器完成授权
+pingcode auth login --client-id ID --client-secret SECRET --browser
+
 # 使用用户令牌查询工作项
 # --grant-type 会自动从缓存中识别，且 workitem list 不再默认按当前用户过滤
 pingcode workitem list --state 进行中 --compact
@@ -290,5 +352,6 @@ pingcode context init
 - 用户令牌登录：[skills/pingcode/references/auth.md](skills/pingcode/references/auth.md)
 - 工作区上下文：[skills/pingcode/references/ctx.md](skills/pingcode/references/ctx.md)
 - 工作项操作：[skills/pingcode/references/workitem.md](skills/pingcode/references/workitem.md)
+- 评论操作：[skills/pingcode/references/comment.md](skills/pingcode/references/comment.md)
 - 官方文档：https://open.pingcode.com/
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaphorli/pingcode-cli",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "PingCode CLI and Codex skill, written in Node.js.",
   "license": "MIT",
   "publishConfig": {
@@ -26,7 +26,7 @@
     "bin/install.js"
   ],
   "scripts": {
-    "test": "node --test tests/test_pingcode.js tests/test_install.js tests/test_context.js tests/test_workitem.js tests/test_auth.js",
+    "test": "node --test tests/test_pingcode.js tests/test_install.js tests/test_context.js tests/test_workitem.js tests/test_auth.js tests/test_comment.js tests/test_idea.js tests/test_product.js",
     "pack:check": "npm pack --dry-run"
   },
   "engines": {

package/scripts/commands/auth.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const crypto = require('node:crypto');
+const fs = require('node:fs');
 const os = require('node:os');
 const readline = require('node:readline');
 const { spawn } = require('node:child_process');
@@ -16,7 +17,7 @@ const DEFAULT_PORT = 8765;
 // ── Flag maps ──────────────────────────────────────────────────────────
 
 const BOOLEAN_FLAGS = new Set([
-  '--no-browser', '--no-token-cache', '--no-workspace-cache', '--dry-run',
+  '--browser', '--no-token-cache', '--no-workspace-cache', '--dry-run',
 ]);
 
 const STRING_FLAGS = {
@@ -31,6 +32,20 @@ const STRING_FLAGS = {
   '--workspace-cache': 'workspace_cache',
 };
 
+const STATUS_BOOLEAN_FLAGS = new Set([
+  '--no-token-cache', '--no-workspace-cache', '--dry-run', '--compact',
+]);
+
+const STATUS_STRING_FLAGS = {
+  '--grant-type': 'grant_type',
+  '--client-id': 'client_id',
+  '--client-secret': 'client_secret',
+  '--base-url': 'base_url',
+  '--token-cache': 'token_cache',
+  '--workspace-cache': 'workspace_cache',
+  '--token': 'token',
+};
+
 // ── Parser ─────────────────────────────────────────────────────────────
 
 function parseLoginArgs(tokens) {
@@ -46,7 +61,7 @@ function parseLoginArgs(tokens) {
     base_url: process.env.PINGCODE_BASE_URL || core.DEFAULT_BASE_URL,
     token_cache: process.env.PINGCODE_TOKEN_CACHE || core.DEFAULT_TOKEN_CACHE,
     workspace_cache: process.env.PINGCODE_WORKSPACE_CACHE || core.DEFAULT_WORKSPACE_CACHE,
-    no_browser: false,
+    browser: true,
     no_token_cache: false,
     no_workspace_cache: false,
     dry_run: false,
@@ -60,6 +75,10 @@ function parseLoginArgs(tokens) {
       helpRequested = true;
       continue;
     }
+    if (arg === '--no-browser') {
+      opts.browser = false;
+      continue;
+    }
     if (BOOLEAN_FLAGS.has(arg)) {
       const key = arg.replace(/^--/, '').replace(/-/g, '_');
       opts[key] = true;
@@ -104,6 +123,64 @@ function parseLoginArgs(tokens) {
   return { opts, helpRequested };
 }
 
+function parseStatusArgs(tokens) {
+  const opts = {
+    base_url: process.env.PINGCODE_BASE_URL || core.DEFAULT_BASE_URL,
+    client_id: process.env.PINGCODE_CLIENT_ID || null,
+    client_secret: process.env.PINGCODE_CLIENT_SECRET || null,
+    grant_type: process.env.PINGCODE_GRANT_TYPE || 'auto',
+    token_cache: process.env.PINGCODE_TOKEN_CACHE || core.DEFAULT_TOKEN_CACHE,
+    workspace_cache: process.env.PINGCODE_WORKSPACE_CACHE || core.DEFAULT_WORKSPACE_CACHE,
+    token: process.env.PINGCODE_ACCESS_TOKEN || null,
+    no_token_cache: false,
+    no_workspace_cache: false,
+    dry_run: false,
+    compact: false,
+  };
+
+  let helpRequested = false;
+
+  for (let i = 0; i < tokens.length; i++) {
+    const arg = tokens[i];
+    if (arg === '--help' || arg === '-h') {
+      helpRequested = true;
+      continue;
+    }
+    if (STATUS_BOOLEAN_FLAGS.has(arg)) {
+      const key = arg.replace(/^--/, '').replace(/-/g, '_');
+      opts[key] = true;
+      continue;
+    }
+    if (arg.startsWith('--')) {
+      const eqIndex = arg.indexOf('=');
+      let flag, value;
+      if (eqIndex !== -1) {
+        flag = arg.slice(0, eqIndex);
+        value = arg.slice(eqIndex + 1);
+      } else {
+        flag = arg;
+        if (!(flag in STATUS_STRING_FLAGS)) {
+          throw new core.PingCodeError(`Unknown option: ${flag}`);
+        }
+        if (i + 1 < tokens.length) {
+          value = tokens[i + 1];
+          i += 1;
+        } else {
+          throw new core.PingCodeError(`Flag ${flag} requires a value`);
+        }
+      }
+      if (!(flag in STATUS_STRING_FLAGS)) {
+        throw new core.PingCodeError(`Unknown option: ${flag}`);
+      }
+      opts[STATUS_STRING_FLAGS[flag]] = value;
+      continue;
+    }
+    throw new core.PingCodeError(`Unexpected argument: ${arg}. Use auth status --help for usage.`);
+  }
+
+  return { opts, helpRequested };
+}
+
 // ── Client ─────────────────────────────────────────────────────────────
 
 function createClient(opts) {
@@ -113,6 +190,7 @@ function createClient(opts) {
     base_url: opts.base_url,
     client_id: opts.client_id,
     client_secret: opts.client_secret,
+    token: opts.token || null,
     token_cache: tokenCache,
     workspace_cache: workspaceCache,
     grant_type: opts.grant_type,
@@ -121,7 +199,7 @@ function createClient(opts) {
 
 // ── Browser opening ────────────────────────────────────────────────────
 
-function openBrowser(url) {
+function openBrowser(url, spawner = spawn) {
   const platform = os.platform();
   let command, args;
 
@@ -137,17 +215,20 @@ function openBrowser(url) {
   }
 
   return new Promise((resolve, reject) => {
-    const child = spawn(command, args, {
+    let settled = false;
+    const child = spawner(command, args, {
       stdio: 'ignore',
       detached: true,
     });
-    child.on('error', (err) => reject(err));
-    child.on('close', (code) => {
-      if (code === 0) {
-        resolve(true);
-      } else {
-        reject(new Error(`Browser process exited with code ${code}`));
-      }
+    child.on('error', (err) => {
+      if (settled) return;
+      settled = true;
+      reject(err);
+    });
+    child.on('spawn', () => {
+      if (settled) return;
+      settled = true;
+      resolve(true);
     });
     child.unref();
   });
@@ -163,6 +244,7 @@ function printHelp() {
     '',
     'Subcommands:',
     '  login    Authenticate with your PingCode user account (OAuth2 authorization_code)',
+    '  status   Show current authentication status',
     '',
     'Run `pingcode auth <subcommand> --help` for subcommand-specific usage.',
   ].join('\n'));
@@ -178,7 +260,8 @@ function printLoginHelp() {
     '  --redirect-uri URI         Redirect URI for OAuth callback',
     `                            (default: ${DEFAULT_REDIRECT_URI})`,
     `  --port PORT                Local callback server port (default: ${DEFAULT_PORT})`,
-    '  --no-browser              Print the authorization URL and prompt for code',
+    '  --browser                 Open browser for authorization (default: true)',
+    '  --no-browser              Print the authorization URL and prompt for code instead of opening browser',
     '  --code CODE               Authorization code (skip browser and callback)',
     '  --grant-type TYPE         OAuth grant type (default: authorization_code)',
     '  --client-id ID            OAuth client ID',
@@ -202,6 +285,36 @@ function printLoginHelp() {
   ].join('\n'));
 }
 
+function printStatusHelp() {
+  console.log([
+    'PingCode auth status — Show current authentication status',
+    '',
+    'Usage: pingcode auth status [options]',
+    '',
+    'Options:',
+    '  --grant-type TYPE         OAuth grant type (default: auto)',
+    '  --client-id ID            OAuth client ID',
+    '  --client-secret SECRET    OAuth client secret',
+    '  --base-url URL            PingCode base URL',
+    '  --token-cache PATH        Token cache file path',
+    '  --no-token-cache          Disable token cache',
+    '  --workspace-cache PATH    Workspace cache file path',
+    '  --no-workspace-cache      Disable workspace cache',
+    '  --token TOKEN             Use an explicit access token (not saved)',
+    '  --dry-run                 Show planned actions without executing',
+    '  --compact                 Show compact output',
+    '  --help                    Show this help',
+    '',
+    'Credentials can also be set via environment variables:',
+    '  PINGCODE_CLIENT_ID        OAuth client ID',
+    '  PINGCODE_CLIENT_SECRET    OAuth client secret',
+    '  PINGCODE_BASE_URL         PingCode base URL',
+    '  PINGCODE_ACCESS_TOKEN     Explicit access token (not saved)',
+    '  PINGCODE_TOKEN_CACHE      Token cache file path',
+    '  PINGCODE_WORKSPACE_CACHE  Workspace cache file path',
+  ].join('\n'));
+}
+
 // ── Helper: prompt for code from stdin ──────────────────────────────────
 
 function promptForCode(inputFunc) {
@@ -254,8 +367,10 @@ function buildDryRunExchange(opts, code) {
 
 // ── Main ────────────────────────────────────────────────────────────────
 
-async function runLogin(argv, inputFunc) {
+async function runLogin(argv, inputFunc, deps = {}) {
   const tokens = argv || [];
+  const openBrowserImpl = deps.openBrowser || openBrowser;
+  const startAuthCallbackServerImpl = deps.startAuthCallbackServer || core.startAuthCallbackServer;
 
   // No args → help
   if (tokens.length === 0) {
@@ -314,7 +429,7 @@ async function runLogin(argv, inputFunc) {
   const authUrl = client.buildAuthorizationUrl(opts.redirect_uri, state);
   const callbackPath = extractCallbackPath(opts.redirect_uri);
 
-  if (opts.no_browser) {
+  if (!opts.browser) {
     // Print URL and prompt for code
     console.log('Open this URL in your browser to authorize:');
     console.log(authUrl);
@@ -330,7 +445,7 @@ async function runLogin(argv, inputFunc) {
   // Try to open the browser; fall back to URL + prompt on failure
   let browserOpened = false;
   try {
-    await openBrowser(authUrl);
+    await openBrowserImpl(authUrl);
     browserOpened = true;
   } catch (_) {
     // Browser spawn failed; fall back to printing the URL
@@ -348,19 +463,94 @@ async function runLogin(argv, inputFunc) {
 
   if (browserOpened) {
     // Start callback server and wait for the redirect
-    const result = await core.startAuthCallbackServer({
+    const result = await startAuthCallbackServerImpl({
       port: opts.port,
       path: callbackPath,
       state: state,
     });
+    console.log('Authorization code received; exchanging for token...');
     await client.exchangeAuthorizationCode(result.code, opts.redirect_uri);
     console.log(`User token saved for grant_type ${opts.grant_type}`);
   }
 }
 
+// ── Status ───────────────────────────────────────────────────────────────
+
+async function runStatus(argv) {
+  const tokens = argv || [];
+
+  if (tokens.length === 1 && (tokens[0] === '--help' || tokens[0] === '-h')) {
+    printStatusHelp();
+    return;
+  }
+
+  const { opts, helpRequested } = parseStatusArgs(tokens);
+
+  if (helpRequested) {
+    printStatusHelp();
+    return;
+  }
+
+  const client = createClient(opts);
+  const tokenCachePath = client.tokenCache;
+  const workspaceCachePath = client.workspaceCachePath;
+
+  let rawToken = null;
+  let validToken = null;
+  if (tokenCachePath) {
+    rawToken = core.readRawTokenCache(tokenCachePath);
+    validToken = core.loadCachedToken(tokenCachePath);
+  }
+
+  const hasExplicitToken = typeof opts.token === 'string' && opts.token;
+  const tokenValid = !!hasExplicitToken || (validToken !== null);
+  const tokenCacheExists = tokenCachePath ? fs.existsSync(tokenCachePath) : false;
+  const workspaceCacheExists = workspaceCachePath ? fs.existsSync(workspaceCachePath) : false;
+
+  const grantType = tokenValid
+    ? client.resolveGrantType()
+    : (rawToken && typeof rawToken.grant_type === 'string' ? rawToken.grant_type : opts.grant_type);
+
+  const expiresAt = rawToken && typeof rawToken.expires_at === 'number' ? rawToken.expires_at : null;
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const expiresIn = expiresAt && expiresAt > nowSeconds ? expiresAt - nowSeconds : null;
+
+  const result = {
+    authenticated: tokenValid,
+    grant_type: grantType,
+    base_url: client.baseUrl,
+    token_cache: tokenCachePath,
+    token_cache_exists: tokenCacheExists,
+    token_valid: tokenValid,
+    token_expires_at: expiresAt,
+    token_expires_in: expiresIn,
+    credentials: {
+      client_id_configured: !!(opts.client_id),
+      client_secret_configured: !!(opts.client_secret),
+    },
+    workspace_cache: workspaceCachePath,
+    workspace_cache_exists: workspaceCacheExists,
+  };
+
+  if (opts.dry_run) {
+    result.dry_run = true;
+  }
+
+  if (opts.compact) {
+    core.printJson({
+      authenticated: result.authenticated,
+      grant_type: result.grant_type,
+      token_valid: result.token_valid,
+      credentials: result.credentials,
+    });
+  } else {
+    core.printJson(result);
+  }
+}
+
 // ── Register ───────────────────────────────────────────────────────────
 
-const SUBCOMMANDS = ['login'];
+const SUBCOMMANDS = ['login', 'status'];
 
 async function run(argv, inputFunc) {
   const tokens = argv || [];
@@ -371,13 +561,20 @@ async function run(argv, inputFunc) {
     return;
   }
 
-  if (subcommand !== 'login') {
-    throw new core.PingCodeError(
-      `Unknown auth subcommand: ${subcommand}. Valid subcommands: ${SUBCOMMANDS.join(', ')}.`
-    );
-  }
+  const remaining = tokens.slice(1);
 
-  await runLogin(tokens.slice(1), inputFunc);
+  switch (subcommand) {
+    case 'login':
+      await runLogin(remaining, inputFunc);
+      return;
+    case 'status':
+      await runStatus(remaining);
+      return;
+    default:
+      throw new core.PingCodeError(
+        `Unknown auth subcommand: ${subcommand}. Use auth --help for usage.`
+      );
+  }
 }
 
 shared.registerModule('auth', {
@@ -386,4 +583,4 @@ shared.registerModule('auth', {
   run,
 });
 
-module.exports = { run, runLogin, printHelp, printLoginHelp, parseLoginArgs, createClient, buildDryRunExchange };
+module.exports = { run, runLogin, runStatus, printHelp, printLoginHelp, printStatusHelp, parseLoginArgs, parseStatusArgs, createClient, buildDryRunExchange, openBrowser };