@dac-tech-team-tw/itsaplan-cli 0.0.0-stage → 0.2.0

package/dist/cli.js

@@ -0,0 +1,444 @@
+#!/usr/bin/env node
+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";
+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：探索專案、讀取工作項目、預覽並執行已授權的寫入操作")
+    .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))
+        throw new CliError("INTERNAL_ERROR", "Missing command context", 1);
+    activeWrite =
+        [
+            "edit",
+            "comment",
+            "link-document",
+            "link-pr",
+            "login",
+            "logout",
+            "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(kind ? projectOutput(kind, result, selection) : result, command);
+};
+function emit(result, command) {
+    const envelope = redact({
+        ok: !result.error,
+        ...(result.outcome
+            ? { outcome: result.outcome, verification: result.verification }
+            : {}),
+        data: result.data,
+        ...(result.error ? { error: result.error } : {}),
+        meta: { schemaVersion: 1, apiVersion: API_BASELINE, ...result.meta },
+    });
+    if (process.argv.includes("--json"))
+        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
+            : JSON.stringify(envelope, null, 2));
+    process.exitCode = result.exitCode ?? (result.error ? 1 : 0);
+}
+program.configureOutput({
+    writeErr: (text) => {
+        if (!process.argv.includes("--json"))
+            process.stderr.write(String(redact(text)));
+    },
+});
+program
+    .command("doctor")
+    .description("診斷設定、認證、連線狀態與 API 版本")
+    .action(wrap((c) => runDoctor(globals(c))));
+const auth = program
+    .command("auth")
+    .description("管理綁定 API 服務網址的個人 API 金鑰憑證");
+auth
+    .command("login")
+    .description("驗證並儲存個人 API 金鑰；隱藏輸入或明確從標準輸入讀取")
+    .option("--with-token", "從標準輸入讀取 API 金鑰")
+    .addOption(new Option("--storage <kind>", "憑證儲存方式；file 明確選用明文檔案").choices(["file", "keyring"]))
+    .action(wrap((c) => runAuth("login", {
+    ...globals(c),
+    ...c.opts(),
+})));
+for (const action of ["status", "logout"])
+    auth
+        .command(action)
+        .description(action === "status"
+        ? "顯示生效中的認證來源與身份，不顯示金鑰"
+        : "移除選取的本機憑證；不會撤銷環境變數中的金鑰")
+        .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("驗證 --project <team.KEY>，並只在此目錄儲存 project_ref")
+    .action(wrap(async (c) => {
+    const options = globals(c);
+    if (!options.project) {
+        throw new CliError("PROJECT_REQUIRED", "Provide --project <team.KEY> to initialize this directory.", 2);
+    }
+    return runInit(await createContext(options), options.project);
+}));
+const project = program
+    .command("project")
+    .description("探索專案並檢視工作流程值");
+project
+    .command("list")
+    .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("讀取欄、標籤、成員、類型與自訂欄位")
+    .action(wrap(async (c) => runProject(await createContext(globals(c)), "view", c.args[0])));
+const issue = program
+    .command("issue")
+    .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",
+    "activity",
+    "comments",
+    "edit",
+    "comment",
+]) {
+    const command = issue
+        .command(action)
+        .description({
+        resolve: "直接解析識別碼並取得穩定工作項目 ID",
+        view: "讀取完整工作項目背景與專案名稱",
+        activity: "讀取有分頁游標筆數上限的工作項目活動動態",
+        comments: "讀取有分頁游標筆數上限且包含回覆的討論",
+        edit: "只更新明確指定的工作項目欄位",
+        comment: "發布一則留言或回覆",
+    }[action] ?? action)
+        .argument("[identifier]", "KEY-42 或專案範圍內的序號")
+        .option("--id <id>", "內部工作項目 ID；不可與 identifier 同時使用");
+    if (action === "view")
+        command
+            .option("--comments", "包含最新 25 個留言討論串及下一個分頁游標")
+            .addHelpText("after", issueReadExamples);
+    if (action === "activity" || action === "comments")
+        command
+            .option("--limit <number>", "頂層項目數量上限", "25")
+            .option("--cursor <cursor>", "此 CLI 回傳的不透明分頁游標");
+    if (action === "edit" || action === "comment") {
+        command
+            .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>", "回覆此工作項目的留言");
+        else
+            command
+                .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", "清除優先級")
+                .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("列出或搜尋專案工作項目；僅支援有筆數上限的查詢，不提供接續分頁；完整性未知（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("發布 Markdown 文件；專案可見不等於網際網路公開");
+document
+    .command("create")
+    .description("建立明確設定 private 或 project 可見範圍的文件頁面")
+    .requiredOption("--title <text>", "文件標題（1–255 個字元）")
+    .addOption(new Option("--visibility <scope>", "project：專案可見，並非網際網路公開；private：僅擁有者可見")
+    .choices(["project", "private"])
+    .makeOptionMandatory())
+    .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,
+})));
+for (const action of ["view", "issues"]) {
+    document
+        .command(`${action} <document-id>`)
+        .description(action === "view"
+        ? "依穩定 ID 讀取可見文件"
+        : "列出連結至此文件的工作項目")
+        .action(wrap(async (c) => runDocument(await createContext(globals(c)), action, c.args[0], {
+        project: globals(c).project,
+    })));
+}
+for (const action of ["documents", "link-document"]) {
+    const command = issue
+        .command(`${action} [identifier]`)
+        .description(action === "documents"
+        ? "列出連結至工作項目的可見文件"
+        : "將同專案文件連結至工作項目；已存在連結時不執行操作")
+        .option("--id <id>", "內部工作項目 ID；不可與 identifier 同時使用");
+    if (action === "link-document")
+        command
+            .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,
+    })));
+}
+for (const action of [
+    "repositories",
+    "pull-requests",
+    "link-pr",
+    "development",
+]) {
+    const descriptions = {
+        repositories: "探索可供工作項目使用的已連接儲存庫",
+        "pull-requests": "列出已連接儲存庫的現有 PR/MR（單頁）",
+        "link-pr": "依已連接儲存庫 ID 與編號連結現有 PR/MR；不會建立 PR",
+        development: "列出工作項目現有的開發連結",
+    };
+    const command = issue
+        .command(`${action} [identifier]`)
+        .description(descriptions[action])
+        .option("--id <id>", "內部工作項目 ID；不可與 identifier 同時使用");
+    if (action === "pull-requests" || action === "link-pr")
+        command.requiredOption("--repository <id>", "由 iap issue repositories 列出的已連接儲存庫 ID");
+    if (action === "pull-requests")
+        command
+            .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>", "現有 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,
+    })));
+}
+program
+    .command("api <relative-path>")
+    .description("原始 API 入口；工作項目與文件寫入必須使用高階指令")
+    .addOption(new Option("--method <method>", "HTTP 方法")
+    .choices(["GET", "HEAD", "POST", "PATCH", "PUT", "DELETE"])
+    .default("GET"))
+    .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();
+}
+catch (error) {
+    if (error instanceof CommanderError && error.exitCode === 0)
+        process.exitCode = 0;
+    else {
+        const known = error instanceof CliError
+            ? error
+            : new CliError(error instanceof CommanderError
+                ? "INVALID_INPUT"
+                : "UNEXPECTED_ERROR", error instanceof Error ? error.message : "Unexpected failure", error instanceof CommanderError ? 2 : 1);
+        const words = process.argv.slice(2);
+        const rawMethod = words
+            .find((word) => word.startsWith("--method="))
+            ?.slice("--method=".length) ??
+            (words.indexOf("--method") >= 0
+                ? words[words.indexOf("--method") + 1]
+                : "GET");
+        const writing = activeWrite ??
+            ((words.includes("issue") &&
+                ["edit", "comment", "link-document", "link-pr"].some((action) => words.includes(action))) ||
+                (words.includes("document") && words.includes("create")) ||
+                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;
+        emit({
+            data: data ?? null,
+            meta: typeof meta === "object" && meta !== null && !Array.isArray(meta)
+                ? Object.fromEntries(Object.entries(meta))
+                : undefined,
+            error: {
+                code: known.code,
+                message: known.message,
+                retryable: false,
+                ...details,
+            },
+            exitCode: known.exitCode,
+            ...(writing
+                ? {
+                    outcome: outcome === "applied" || outcome === "unknown"
+                        ? outcome
+                        : "not_applied",
+                    verification: verification === "passed" || verification === "failed"
+                        ? verification
+                        : "not_run",
+                }
+                : {}),
+        });
+    }
+}

package/dist/commands.d.ts

@@ -0,0 +1,15 @@
+import { type Context, type GlobalOptions, type Result } from "./contracts.js";
+export declare function runDoctor(options: GlobalOptions): Promise<Result>;
+export declare function runAuth(action: string, options: GlobalOptions & {
+    withToken?: boolean;
+    storage?: string;
+}): Promise<Result>;
+export declare function runProject(ctx: Context, action: string, ref?: string, options?: {
+    limit?: number;
+}): Promise<Result>;
+export declare function runInit(ctx: Context, project: string): Promise<Result>;
+export declare function runApi(ctx: Context, path: string, options: {
+    method?: string;
+    input?: string;
+    dryRun?: boolean;
+}): Promise<Result>;