@dac-tech-team-tw/itsaplan-cli 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command, CommanderError, Option } from "commander";
+import { Command, CommanderError, Help, Option } from "commander";
 import { CliError, CLI_VERSION, API_BASELINE, } from "./contracts.js";
 import { createContext } from "./config.js";
 import { redact } from "./http.js";
@@ -7,20 +7,81 @@ import { runIssue } from "./issues.js";
 import { runDoctor, runAuth, runProject, runInit, runApi } from "./commands.js";
 import { runDocument, runIssueDocument, } from "./documents.js";
 import { runDevelopment } from "./development.js";
+import { runProjectConfig } from "./project-config.js";
+import { validateOutput, projectOutput, needsIssueStates, } from "./output.js";
 const program = new Command()
     .name("itsaplan")
-    .description("It's a Plan: discover projects, read issues, preview and perform authorized writes")
-    .version(CLI_VERSION)
-    .option("--json", "Emit one stable JSON envelope")
-    .option("--api-url <url>", "Trusted API base URL (HTTPS except localhost)")
-    .option("--api-key <key>", "One-off key; prefer env/config; requires explicit endpoint")
-    .option("--project <team.KEY>", "Project ref; overrides env and directory configuration")
+    .description("It's a Plan：探索專案、讀取工作項目、預覽並執行已授權的寫入操作")
+    .version(CLI_VERSION, "-V, --version", "顯示版本")
+    .helpOption("-h, --help", "顯示指令說明")
+    .helpCommand("help [command]", "顯示指令說明")
+    .configureHelp({
+    showGlobalOptions: true,
+    styleTitle(title) {
+        return ({
+            "Usage:": "用法：",
+            "Arguments:": "引數：",
+            "Options:": "選項：",
+            "Global Options:": "全域選項：",
+            "Commands:": "指令：",
+        }[title] ?? title);
+    },
+    optionDescription(option) {
+        if (option.long === "--help")
+            return "顯示指令說明";
+        if (option.long === "--version")
+            return "顯示版本";
+        const description = Help.prototype.optionDescription.call(this, option);
+        return description
+            .replace(/\bchoices:/g, "可選值：")
+            .replace(/\bdefault:/g, "預設值：")
+            .replace(/\bpreset:/g, "預設參數：");
+    },
+})
+    .addHelpText("afterAll", `
+全域選項可放在子指令之前或之後；完整說明請見 iap --help。
+指令說明：iap <command> <subcommand> --help。
+專案來源優先序：--project > ITSAPLAN_PROJECT > 最近的 .itsaplan.toml
+  > 目前 API 服務網址（含基底路徑）的使用者預設值。
+使用 iap init --project <team.KEY> 為此目錄設定專案。
+使用者預設值：iap config set project <team.KEY>；
+  使用 iap config get project 檢視，或以 iap config unset project 清除。`)
+    .option("--json", "輸出單一固定格式的 JSON 結果封裝")
+    .option("--summary", "精簡 project／issue 讀取資料；不截斷正文，不支援寫入")
+    .option("--fields <paths>", "選取 project／issue 讀取欄位（逗號分隔點路徑）；與 --summary 互斥")
+    .option("--api-url <url>", "API 服務網址（部署網域，含 https://；非網頁登入網址）")
+    .option("--api-key <key>", "一次性金鑰；建議使用環境變數／設定檔；必須明確指定 API 服務網址")
+    .option("--project <team.KEY>", "專案參照；優先於環境變數、目錄與使用者設定")
     .showHelpAfterError()
     .exitOverride();
 let activeWrite;
 function globals(command) {
     return command.optsWithGlobals();
 }
+function outputKind(command) {
+    const key = `${command.parent?.name()}.${command.name()}`;
+    return [
+        "project.list",
+        "project.view",
+        "issue.list",
+        "issue.view",
+        "issue.resolve",
+        "issue.comments",
+        "issue.activity",
+    ].includes(key)
+        ? key
+        : undefined;
+}
+function issueOutputOptions(command) {
+    const options = command.optsWithGlobals();
+    const kind = outputKind(command);
+    if (!kind)
+        return { outputSelected: false, includeState: false };
+    return {
+        outputSelected: options.summary === true || options.fields !== undefined,
+        includeState: needsIssueStates(kind, options),
+    };
+}
 const wrap = (handler) => async (...args) => {
     const command = args.at(-1);
     if (!(command instanceof Command))
@@ -36,12 +97,22 @@ const wrap = (handler) => async (...args) => {
             "init",
         ].includes(command.name()) ||
             (command.parent?.name() === "document" && command.name() === "create") ||
+            (command.name() === "project" &&
+                ["set", "unset"].includes(command.parent?.name() ?? "") &&
+                command.parent?.parent?.name() === "config") ||
             (command.name() === "api" &&
                 !["GET", "HEAD"].includes(command.opts().method));
+    const selection = command.optsWithGlobals();
+    const kind = outputKind(command);
+    if (selection.summary || selection.fields !== undefined) {
+        if (!kind)
+            throw new CliError("UNSUPPORTED_OUTPUT", "--summary and --fields only support project list/view and issue list/view/resolve/comments/activity");
+        validateOutput(kind, selection);
+    }
     const result = await handler(command);
-    emit(result);
+    emit(kind ? projectOutput(kind, result, selection) : result, command);
 };
-function emit(result) {
+function emit(result, command) {
     const envelope = redact({
         ok: !result.error,
         ...(result.outcome
@@ -55,6 +126,16 @@ function emit(result) {
         console.log(JSON.stringify(envelope));
     else if (result.error)
         console.error(JSON.stringify(envelope, null, 2));
+    else if (command?.name() === "login" && command.parent?.name() === "auth") {
+        const data = result.data;
+        console.log("OK：登入憑證已驗證並儲存。");
+        const warning = data.warning ??
+            (data.effective.usable !== true
+                ? "目前生效的登入尚未確認可用，請執行 iap auth status --json 查詢。"
+                : undefined);
+        if (warning)
+            console.error(`警告：${redact(warning)}`);
+    }
     else
         console.log(typeof result.data === "string"
             ? result.data
@@ -69,16 +150,16 @@ program.configureOutput({
 });
 program
     .command("doctor")
-    .description("Diagnose configuration, authentication, reachability and API version")
+    .description("診斷設定、認證、連線狀態與 API 版本")
     .action(wrap((c) => runDoctor(globals(c))));
 const auth = program
     .command("auth")
-    .description("Manage endpoint-bound personal API key credentials");
+    .description("管理綁定 API 服務網址的個人 API 金鑰憑證");
 auth
     .command("login")
-    .description("Validate and store a key; hidden prompt or explicit stdin")
-    .option("--with-token", "Read API key from stdin")
-    .addOption(new Option("--storage <kind>", "Credential storage; explicit file opts into plaintext").choices(["file", "keyring"]))
+    .description("驗證並儲存個人 API 金鑰；隱藏輸入或明確從標準輸入讀取")
+    .option("--with-token", "從標準輸入讀取 API 金鑰")
+    .addOption(new Option("--storage <kind>", "憑證儲存方式；file 明確選用明文檔案").choices(["file", "keyring"]))
     .action(wrap((c) => runAuth("login", {
     ...globals(c),
     ...c.opts(),
@@ -87,12 +168,30 @@ for (const action of ["status", "logout"])
     auth
         .command(action)
         .description(action === "status"
-        ? "Show effective auth source and identity without the key"
-        : "Remove selected local credentials; does not revoke env keys")
+        ? "顯示生效中的認證來源與身份，不顯示金鑰"
+        : "移除選取的本機憑證；不會撤銷環境變數中的金鑰")
         .action(wrap((c) => runAuth(action, globals(c))));
+const config = program
+    .command("config")
+    .description("管理依 API 服務網址區分的使用者預設值");
+config
+    .command("set")
+    .description("儲存經驗證的使用者預設值")
+    .command("project <ref>")
+    .description("驗證並儲存此 API 服務網址的標準專案參照")
+    .action(wrap((c) => runProjectConfig("set", globals(c), c.args[0])));
+for (const action of ["get", "unset"])
+    config
+        .command(action)
+        .description(action === "get" ? "檢視使用者預設值" : "移除使用者預設值")
+        .command("project")
+        .description(action === "get"
+        ? "不發出請求，顯示已儲存及生效中的專案與來源"
+        : "只移除此 API 服務網址儲存的專案預設值")
+        .action(wrap((c) => runProjectConfig(action, globals(c))));
 program
     .command("init")
-    .description("Validate --project <team.KEY> and save only project_ref in this directory")
+    .description("驗證 --project <team.KEY>，並只在此目錄儲存 project_ref")
     .action(wrap(async (c) => {
     const options = globals(c);
     if (!options.project) {
@@ -102,21 +201,30 @@ program
 }));
 const project = program
     .command("project")
-    .description("Discover projects and inspect workflow values");
+    .description("探索專案並檢視工作流程值");
 project
     .command("list")
-    .description("List available projects (bounded)")
-    .option("--limit <number>", "Maximum projects", "30")
+    .description("列出可用專案（有筆數上限）")
+    .option("--limit <number>", "專案數量上限", "30")
     .action(wrap(async (c) => runProject(await createContext(globals(c)), "list", undefined, {
     limit: Number(c.opts().limit),
 })));
 project
     .command("view <ref>")
-    .description("Read columns, labels, members, types and custom fields")
+    .description("讀取欄、標籤、成員、類型與自訂欄位")
     .action(wrap(async (c) => runProject(await createContext(globals(c)), "view", c.args[0])));
 const issue = program
     .command("issue")
-    .description("Resolve, inspect, search, comment and edit issues");
+    .description("解析、檢視、搜尋、留言與編輯工作項目");
+const issueReadExamples = `
+範例使用虛構識別碼；請從清單中選擇識別碼或內部 ID：
+  iap issue list --project acme.MKT --limit 30 --summary --json
+  iap issue view MKT-42 --project acme.MKT --comments --summary --json
+  iap issue view --id 123 --fields identifier,title,state --json
+選取不改變 --json 序列化；省略 --summary／--fields 取得完整資料。
+--fields 對列表的每個 item 選欄位；保留範圍、完整性與游標。
+MKT-42 使用專案序號 42；--id 123 是內部數值工作項目 ID。
+請明確傳入其中一種：view 不會從標準輸入讀取 list 的 JSON。`;
 for (const action of [
     "resolve",
     "view",
@@ -128,75 +236,80 @@ for (const action of [
     const command = issue
         .command(action)
         .description({
-        resolve: "Resolve an identifier directly to a stable issue ID",
-        view: "Read full issue context and project names",
-        activity: "Read a cursor-bounded issue activity feed",
-        comments: "Read a cursor-bounded discussion with replies",
-        edit: "Update only specified issue fields",
-        comment: "Publish one comment or reply",
+        resolve: "直接解析識別碼並取得穩定工作項目 ID",
+        view: "讀取完整工作項目背景與專案名稱",
+        activity: "讀取有分頁游標筆數上限的工作項目活動動態",
+        comments: "讀取有分頁游標筆數上限且包含回覆的討論",
+        edit: "只更新明確指定的工作項目欄位",
+        comment: "發布一則留言或回覆",
     }[action] ?? action)
-        .argument("[identifier]", "KEY-42 or project-scoped sequence number")
-        .option("--id <id>", "Internal issue ID, mutually exclusive with identifier");
+        .argument("[identifier]", "KEY-42 或專案範圍內的序號")
+        .option("--id <id>", "內部工作項目 ID；不可與 identifier 同時使用");
     if (action === "view")
-        command.option("--comments", "Include latest 25 comment threads and next cursor");
+        command
+            .option("--comments", "包含最新 25 個留言討論串及下一個分頁游標")
+            .addHelpText("after", issueReadExamples);
     if (action === "activity" || action === "comments")
         command
-            .option("--limit <number>", "Maximum top-level entries", "25")
-            .option("--cursor <cursor>", "Opaque cursor returned by this CLI");
+            .option("--limit <number>", "頂層項目數量上限", "25")
+            .option("--cursor <cursor>", "此 CLI 回傳的不透明分頁游標");
     if (action === "edit" || action === "comment") {
         command
-            .option("--body <text>", "Markdown content")
-            .option("--body-file <file|->", "UTF-8 Markdown file, or explicit stdin -")
-            .option("--agent <name>", "Declared agent: codex or claude")
-            .option("--human", "Explicit human source; conflicts with agent env")
-            .option("--dry-run", "Read and validate only; show exact request without writing");
+            .option("--body <text>", "Markdown 內容")
+            .option("--body-file <file|->", "UTF-8 Markdown 檔案，或明確指定標準輸入 -")
+            .option("--agent <name>", "宣告代理：codex 或 claude")
+            .option("--human", "明確宣告人工作業；不可與代理環境變數並用")
+            .option("--dry-run", "只讀取與驗證；顯示確切請求但不寫入");
         if (action === "comment")
-            command.option("--reply-to <id>", "Reply to a comment of this issue");
+            command.option("--reply-to <id>", "回覆此工作項目的留言");
         else
             command
-                .option("--title <text>", "New title")
-                .option("--state <name>", "Exact column name")
-                .option("--state-type <type>", "Unique backlog/unstarted/started/completed/canceled column")
-                .option("--column-id <id>", "Column ID belonging to this project")
-                .option("--assignee <username|@me>", "Assign a project member")
-                .option("--remove-assignee", "Clear assignee")
+                .option("--title <text>", "新標題")
+                .option("--state <name>", "精確欄位名稱")
+                .option("--state-type <type>", "唯一符合的 backlog/unstarted/started/completed/canceled 欄位")
+                .option("--column-id <id>", "屬於此專案的欄位 ID")
+                .option("--assignee <username|@me>", "指派工作項目負責人")
+                .option("--remove-assignee", "清除負責人")
                 .option("--priority <priority>", "urgent/high/medium/low")
-                .option("--remove-priority", "Clear priority")
-                .option("--type <name>", "Exact issue type name")
-                .option("--remove-type", "Clear issue type")
-                .option("--add-label <name>", "Add exact label, repeatable", (value, previous) => [...previous, value], [])
-                .option("--remove-label <name>", "Remove exact label, repeatable", (value, previous) => [...previous, value], []);
+                .option("--remove-priority", "清除優先級")
+                .option("--type <name>", "精確工作項目類型名稱")
+                .option("--remove-type", "清除工作項目類型")
+                .option("--add-label <name>", "加入精確標籤，可重複指定", (value, previous) => [...previous, value], [])
+                .option("--remove-label <name>", "移除精確標籤，可重複指定", (value, previous) => [...previous, value], []);
     }
     command.action(wrap(async (c) => runIssue(await createContext(globals(c)), action, c.args[0], {
         ...c.opts(),
         project: globals(c).project,
+        ...issueOutputOptions(c),
     })));
 }
 issue
     .command("list")
-    .description("List or search project issues; completeness is unknown without pagination")
-    .option("--search <text>", "Project text search; cannot combine with assignee filter")
-    .option("--assignee <username|@me>", "Filter by project member")
-    .option("--limit <number>", "Maximum issues (API bounded)", "30")
+    .description("列出或搜尋專案工作項目；僅支援有筆數上限的查詢，不提供接續分頁；完整性未知（unknown）")
+    .option("--search <text>", "專案文字搜尋；不可與負責人篩選條件並用")
+    .option("--assignee <username|@me>", "依專案成員篩選")
+    .option("--limit <number>", "本地範圍為 1–500；伺服器可能回傳較少項目", "30")
+    .addHelpText("after", issueReadExamples)
     .action(wrap(async (c) => runIssue(await createContext(globals(c)), "list", undefined, {
     ...c.opts(),
     project: globals(c).project,
+    ...issueOutputOptions(c),
 })));
 const document = program
     .command("document")
-    .description("Publish Markdown Docs; project-visible is not internet-public");
+    .description("發布 Markdown 文件；專案可見不等於網際網路公開");
 document
     .command("create")
-    .description("Create a Docs page with explicit private or project visibility")
-    .requiredOption("--title <text>", "Document title (1–255 characters)")
-    .addOption(new Option("--visibility <scope>", "project: project-visible, NOT internet-public; private: owner only")
+    .description("建立明確設定 private 或 project 可見範圍的文件頁面")
+    .requiredOption("--title <text>", "文件標題（1–255 個字元）")
+    .addOption(new Option("--visibility <scope>", "project：專案可見，並非網際網路公開；private：僅擁有者可見")
     .choices(["project", "private"])
     .makeOptionMandatory())
-    .option("--body <text>", "Markdown content")
-    .option("--body-file <file|->", "UTF-8 Markdown file, or explicit stdin -")
-    .option("--agent <name>", "Declared agent: codex or claude")
-    .option("--human", "Explicit human source; conflicts with agent env")
-    .option("--dry-run", "Read and validate only; show exact request without writing")
+    .option("--body <text>", "Markdown 內容")
+    .option("--body-file <file|->", "UTF-8 Markdown 檔案，或明確指定標準輸入 -")
+    .option("--agent <name>", "宣告代理：codex 或 claude")
+    .option("--human", "明確宣告人工作業；不可與代理環境變數並用")
+    .option("--dry-run", "只讀取與驗證；顯示確切請求但不寫入")
     .action(wrap(async (c) => runDocument(await createContext(globals(c)), "create", undefined, {
     ...c.opts(),
     project: globals(c).project,
@@ -205,8 +318,8 @@ for (const action of ["view", "issues"]) {
     document
         .command(`${action} <document-id>`)
         .description(action === "view"
-        ? "Read a visible document by stable ID"
-        : "List tickets linked to this document")
+        ? "依穩定 ID 讀取可見文件"
+        : "列出連結至此文件的工作項目")
         .action(wrap(async (c) => runDocument(await createContext(globals(c)), action, c.args[0], {
         project: globals(c).project,
     })));
@@ -215,15 +328,15 @@ for (const action of ["documents", "link-document"]) {
     const command = issue
         .command(`${action} [identifier]`)
         .description(action === "documents"
-        ? "List visible Docs linked to a ticket"
-        : "Link a same-project document to a ticket; existing link is a no-op")
-        .option("--id <id>", "Internal issue ID, mutually exclusive with identifier");
+        ? "列出連結至工作項目的可見文件"
+        : "將同專案文件連結至工作項目；已存在連結時不執行操作")
+        .option("--id <id>", "內部工作項目 ID；不可與 identifier 同時使用");
     if (action === "link-document")
         command
-            .requiredOption("--document <id>", "Stable document ID in the same project")
-            .option("--agent <name>", "Declared agent: codex or claude")
-            .option("--human", "Explicit human source; conflicts with agent env")
-            .option("--dry-run", "Preview the exact relation without writing");
+            .requiredOption("--document <id>", "同一專案中的穩定文件 ID")
+            .option("--agent <name>", "宣告代理：codex 或 claude")
+            .option("--human", "明確宣告人工作業；不可與代理環境變數並用")
+            .option("--dry-run", "預覽確切關聯內容，不執行寫入");
     command.action(wrap(async (c) => runIssueDocument(await createContext(globals(c)), action, c.args[0], {
         ...c.opts(),
         project: globals(c).project,
@@ -236,29 +349,29 @@ for (const action of [
     "development",
 ]) {
     const descriptions = {
-        repositories: "Discover connected repositories available to a ticket",
-        "pull-requests": "List existing PRs/MRs from a connected repository (one page)",
-        "link-pr": "Link an existing PR/MR by connected repository ID and number; never create a PR",
-        development: "List the ticket's existing development links",
+        repositories: "探索可供工作項目使用的已連接儲存庫",
+        "pull-requests": "列出已連接儲存庫的現有 PR/MR（單頁）",
+        "link-pr": "依已連接儲存庫 ID 與編號連結現有 PR/MR；不會建立 PR",
+        development: "列出工作項目現有的開發連結",
     };
     const command = issue
         .command(`${action} [identifier]`)
         .description(descriptions[action])
-        .option("--id <id>", "Internal issue ID, mutually exclusive with identifier");
+        .option("--id <id>", "內部工作項目 ID；不可與 identifier 同時使用");
     if (action === "pull-requests" || action === "link-pr")
-        command.requiredOption("--repository <id>", "Connected repository ID from issue repositories");
+        command.requiredOption("--repository <id>", "由 iap issue repositories 列出的已連接儲存庫 ID");
     if (action === "pull-requests")
         command
-            .option("--page <number>", "API page (follow nextPage)", "1")
-            .addOption(new Option("--state <state>", "PR state filter")
+            .option("--page <number>", "API 頁碼（依 nextPage 繼續）", "1")
+            .addOption(new Option("--state <state>", "PR 狀態篩選")
             .choices(["open", "all"])
             .default("open"));
     if (action === "link-pr")
         command
-            .requiredOption("--number <number>", "Existing PR/MR number; not an arbitrary URL")
-            .option("--agent <name>", "Declared agent: codex or claude")
-            .option("--human", "Explicit human source; conflicts with agent env")
-            .option("--dry-run", "Preview without linking or creating a PR");
+            .requiredOption("--number <number>", "現有 PR/MR 編號；不是任意 URL")
+            .option("--agent <name>", "宣告代理：codex 或 claude")
+            .option("--human", "明確宣告人工作業；不可與代理環境變數並用")
+            .option("--dry-run", "預覽但不連結或建立 PR");
     command.action(wrap(async (c) => runDevelopment(await createContext(globals(c)), action, c.args[0], {
         ...c.opts(),
         project: globals(c).project,
@@ -266,12 +379,12 @@ for (const action of [
 }
 program
     .command("api <relative-path>")
-    .description("Raw API escape hatch; issue and Docs mutations require high-level commands")
-    .addOption(new Option("--method <method>", "HTTP method")
+    .description("原始 API 入口；工作項目與文件寫入必須使用高階指令")
+    .addOption(new Option("--method <method>", "HTTP 方法")
     .choices(["GET", "HEAD", "POST", "PATCH", "PUT", "DELETE"])
     .default("GET"))
-    .option("--input <file|->", "JSON request body from file or explicit stdin")
-    .option("--dry-run", "Preview without sending writes")
+    .option("--input <file|->", "從檔案或明確指定的標準輸入讀取 JSON 請求本文")
+    .option("--dry-run", "預覽但不送出寫入請求")
     .action(wrap(async (c) => runApi(await createContext(globals(c)), c.args[0] ?? "", c.opts())));
 try {
     await program.parseAsync();
@@ -299,6 +412,8 @@ catch (error) {
                 words.includes("init") ||
                 (words.includes("auth") &&
                     (words.includes("login") || words.includes("logout"))) ||
+                (words.includes("config") &&
+                    (words.includes("set") || words.includes("unset"))) ||
                 (words.includes("api") &&
                     /^(POST|PATCH|PUT|DELETE)$/.test(rawMethod ?? "GET")));
         const { outcome, verification, data, meta, ...details } = known.details;