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

package/README.md

@@ -1,6 +1,6 @@
 # itsaplan-cli
 
-It's a Plan 的獨立 CLI，入口為 `iap` 與 `itsaplan`。Node.js 22+；API 基線 1.9.0。公開 npm 套件為 `@dac-tech-team-tw/itsaplan-cli`，原始碼維持 private；目前採本機手動發布，GitHub Actions 負責 CI。
+It's a Plan 的獨立 CLI，入口為 `iap` 與 `itsaplan`。Node.js 22+；API 基線 1.10.0，現行規格為 [OpenAPI 1.10.0](its-a-plan-api-v1.10.0.yaml)，[1.9.0](its-a-plan-api-1.yaml) 僅供歷史比較。公開 npm 套件為 `@dac-tech-team-tw/itsaplan-cli`，原始碼維持 private；目前採本機手動發布，GitHub Actions 負責 CI。
 
 ## 安裝
 
@@ -109,6 +109,8 @@ iap issue view MKT-42 --project acme.MKT --fields identifier,title,priority --js
 
 `--fields` 為資料相對點路徑：list／feed 作用於每個 item，view／resolve 作用於 data；巢狀陣列維持原形，例如 `columns.id,columns.name`。欄位名稱依各命令的固定 schema 驗證，空集合仍能抓到錯字；未知或不安全路徑於 API 請求前拒絕。整個已知欄位（如 `customFields`）可直接選取；未支援的新 server 欄位請用完整輸出。`meta.output` 標明模式、選取欄位（適用）與 `missing` 路徑：已選但 server 未提供的欄位不補 null；null 保留原意，未選欄位不出現在資料中。
 
+Issue 詳情完整輸出保留伺服器提供的 `shareExpiresAt`；它是分享設定的到期時間，不是憑證。既有 `shareToken`／`shareExtended` 仍依輸出策略移除。
+
 選取不會移除 envelope、分頁游標及既有 meta。Issue list 的 `meta.scope` 描述本次專案與搜尋／負責人範圍；取得 setup 時使用其 canonical ref，否則保留請求 ref。其餘 issue 讀取的 scope 保留 issueId、identifier、projectId 及可得 projectRef；view 即使只指定 `--id`，也保留後續取得的 canonical projectRef。Issue view 的 `meta.read.comments` 區分 `not_read` 與 `read_page`，後者另附 nextCursor；其 limit、returned、completeness 統一讀取 `meta.comments`。附件為 `metadata_only`、`contentRead:false`。Comments／activity 的 `meta.read.entries` 描述 status、contentRead、filter 與輸入／下一頁游標，筆數與完整性統一讀取既有 `meta.limit/returned/completeness`，其 attachments 為 `not_read`。`--fields` 不能移除這些讀取範圍標記。`nextCursor:null` 仍不代表 issue list 完整。
 
 Issue list 摘要或選取 `state`／`state.*`，會共用最多一次額外 project setup GET；搭配負責人篩選則重用既有 setup。List 的 state 僅支援 id/name/stateType/unavailable；color、WIP 等完整欄位請用 project view 或 issue view 查詢。未知 columnId 保留 ID 並標示 `unavailable:true`，不猜測狀態；即使只選 `state.name`，仍保留診斷用 id/unavailable，且將 name 標為 missing。只選其他欄位不增加這項請求。投影不改變其他既有讀取流程，不代表減少 HTTP payload，也不新增持久快取。多票共用同一份已讀 workflow 上下文即可；修改前仍須讀取最新相關資訊，既有寫入 preflight 不使用該上下文取代查證。
@@ -134,6 +136,21 @@ Edit 支援 title、body、state/state-type/column-id、assignee/remove-assignee
 
 Dry-run 可以讀取驗證但不寫入，顯示身份、request 與 diff；權限/WIP 等仍以真正寫入為準。正常寫入不再詢問 y/n。寫入不重試；timeout/5xx/回應損壞可能已套用，須先讀 issue/feed 查證，不能直接重送。
 
+## Initiative 管理
+
+```sh
+iap initiative list --project acme.MKT --status active --page 1 --limit 25 --json
+iap initiative view 301 --project acme.MKT --json
+iap initiative create --project acme.MKT --title '產品規劃' --body-file plan.md --owner @me --agent codex --dry-run --json
+printf '更新後的規劃\n' | iap initiative edit 301 --project acme.MKT --body-file - --add-label Roadmap --agent codex --dry-run --json
+```
+
+Initiative 使用內部正整數 ID，不是 `KEY-42`。List/create 依既有專案來源優先序解析專案；view/edit 核對選定專案的 numeric projectId。List 使用伺服器原生 `--page` 與 `--limit`（1–100，預設 25），支援 `--status`、`--search`、`--sort`、`--dir`；結果保留 `total`、`page`、`pageSize`、`nextPage`，依 `nextPage` 繼續查詢，不提供 cursor 或 `--all`。`--summary`／`--fields` 不支援 initiative。
+
+Create/edit 支援 title、description、status、owner、priority、startDate、targetDate 與 labels；`--body` 與 `--body-file` 互斥，`--body-file -` 明確讀 stdin。Owner 可使用 `@me`；owner、priority 與日期可用對應 `--remove-*` 清空，不能同時設定與清空。Edit 的 `--add-label`／`--remove-label` 保留既有集合，但讀改寫並非原子操作。名稱必須精確且不歧義。
+
+所有寫入及 dry-run 均要求 actor。只有明確提供 description 才處理署名；未提供 description 的 create 不會產生只有署名的正文。Dry-run 只讀，列出 identity、request 與適用 diff；實際權限由伺服器裁定。寫入不自動重送；`unknown` 或 `applied/failed` 時先查證並保留已取得的 initiativeId，同名 initiative 不足以證明建立成功。不提供 delete、活動、附件或跨資源關聯操作。
+
 ## 文件發布與 ticket 關聯
 
 ```sh
@@ -181,23 +198,25 @@ iap api /projects/acme.MKT --method GET --json
 iap api /some-resource --method POST --input payload.json --dry-run --json
 ```
 
-共用可信 endpoint、認證、redaction 與結果契約。禁止 raw 寫入 `/issues`、`/projects/{project}/issues` 及其子路徑，也禁止 `/comments`、`/checklists`、`/worklogs`、`/attachments` 等 issue 子資源寫入；包含 move、archive、fields 與 bulk labels。另禁止 `/projects/{project}/documents` 及其子路徑的 raw 寫入，避免文件發布及關聯繞過來源宣告。請走高階指令；尚未提供的上述 mutation 暫不支援，GET／HEAD 仍可用。其他 raw write 不保證 agent footer，僅在使用者明確授權該操作時執行。
+共用可信 endpoint、認證、redaction 與結果契約。禁止 raw 寫入 `/issues`、`/projects/{project}/issues` 及其子路徑，也禁止 `/comments`、`/checklists`、`/worklogs`、`/attachments` 等 issue 子資源寫入；包含 move、archive、fields 與 bulk labels。另禁止 `/projects/{project}/documents`、`/projects/{project}/initiatives`、`/initiatives`、`/initiative-attachments` 及其子路徑的 raw 寫入，避免繞過來源宣告。請走高階指令；尚未提供的上述 mutation 暫不支援，GET／HEAD 仍可用。其他 raw write 不保證 agent footer，僅在使用者明確授權該操作時執行。
 
 ## JSON 契約
 
 `--json` 可放在指令前後；stdout 恰一個 JSON 文件，診斷走 stderr。所有家族用 CLI envelope，非直接 API pass-through；raw `data` 是移除敏感欄位後的 API 回應。
 
 ```json
-{"ok":true,"data":{"id":123,"identifier":"MKT-42"},"meta":{"schemaVersion":1,"apiVersion":"1.9.0"}}
+{"ok":true,"data":{"id":123,"identifier":"MKT-42"},"meta":{"schemaVersion":1,"apiVersion":"1.10.0"}}
 ```
 
-列表 `data` 為 `{ "items": [], "nextCursor": null }`，`meta` 包含 returned、completeness 及適用的 limit。PR 清單改用真實 `nextPage`，不提供假 cursor；`null` cursor 不等於所有列表皆完整。doctor/auth/config/init/project/issue/document/api 全部遵循相同 envelope；上方各家族命令可直接加 `--json`。
+一般列表 `data` 為 `{ "items": [], "nextCursor": null }`，`meta` 包含 returned、completeness 及適用的 limit。PR 與 initiative 清單使用真實 `nextPage`，不提供假 cursor；`null` cursor 不等於所有列表皆完整。doctor/auth/config/init/project/issue/initiative/document/api 全部遵循相同 envelope；上方各家族命令可直接加 `--json`。
+
+一般命令的 `meta.apiVersion` 是 CLI 契約基線，不是部署版本探測；doctor 成功取得版本時則回報 server 實際版本。Doctor 的 `baselineStatus: "tested"` 僅表示版本與基線相符（允許 `v` 前綴），不代表全部 API 均已實測；不同版本標記 `unverified`，不因此拒絕連線。
 
 ```json
 {"ok":false,"error":{"code":"ACTOR_REQUIRED","message":"Provide --agent or --human","retryable":false},"outcome":"not_applied","verification":"not_run","data":null,"meta":{"schemaVersion":1}}
 ```
 
-寫入根層 `outcome`：applied／not_applied／unknown；`verification`：passed／failed／not_run。Dry-run 成功是 not_applied/not_run。已知寫入但驗證失敗為 applied/failed、`ok:false` 並保留已取得 ID。未知結果為 unknown/not_run，applied/unknown 的 retryable 永遠 false。寫入 `data` 回報 action、issueId、commentId／documentId／linkId（適用）、changed 與可得 updatedAt；預覽另有 dryRun、request 及適用的 diff，`meta.actor` 記錄來源。
+寫入根層 `outcome`：applied／not_applied／unknown；`verification`：passed／failed／not_run。Dry-run 成功是 not_applied/not_run。已知寫入但驗證失敗為 applied/failed、`ok:false` 並保留已取得 ID。未知結果為 unknown/not_run，applied/unknown 的 retryable 永遠 false。寫入 `data` 回報 action、issueId、initiativeId、commentId／documentId／linkId（適用）、changed 與可得 updatedAt；預覽另有 dryRun、request 及適用的 diff，`meta.actor` 記錄來源。
 
 Raw 與高階 issue 寫入共用失敗分類，不以其他 HTTP status 推翻 transport 明確回報的 `unknown`。例如 410／412 未被判定為確定拒絕時，維持 `unknown`／exit 6，而不是同時宣稱未套用。
 
@@ -225,6 +244,11 @@ npm pack --dry-run --json
 
 ### 已執行驗證
 
+- #17：build、型別檢查與 37 個 initiative／raw API 相關測試通過；本機 HTTP fixture 實際執行 list、view、create 預覽、create、edit、view，並驗證 stdin 與預覽不寫入。未呼叫正式 API 或發布 npm 套件。
+- PR #19 第一輪 review 修正：`pnpm build` 與 `pnpm exec tsx --test test/cli.test.ts test/initiatives-cli.test.ts` 通過（4 個測試）。實際 CLI 驗證缺少 edit ID、create 未知選項會回報 `not_applied/not_run`，list/view 的輸入錯誤不標成寫入；無需 API 即可執行該 regression。
+
+- #16：build、型別檢查與 88 個 doctor／output／issues／實際 CLI 相關測試通過。本機 HTTP fixture 驗證 doctor 的 server 版本、list/search 的 parent 投影及 view 的 `shareExpiresAt`；`npm pack --dry-run --ignore-scripts --json` 僅包含 README、package.json 與 dist。未呼叫正式 API 或發布 npm 套件。
+
 - #11／#12（含 PR #15 review 修正）：build、型別檢查與 63 個相關 output／issue／實際 CLI 測試通過，涵蓋 internal ID view 的 canonical 專案範圍、list state 欄位驗證與未知狀態巢狀投影診斷。Linux 本機 HTTP fixture 的相同雙票流程（compact JSON，含 LF）完整輸出累計 28531 bytes、11 次 API／5 次 CLI；分階段輸出 18825 bytes、12 次 API／5 次 CLI。正文、自訂欄位、checklists、討論及附件 metadata 保持一致；多一次 API 為搜尋可讀狀態的 setup GET。未量測 tokenizer／model token，未呼叫正式 API 或發布 npm 套件。
 
 - #10 help 繁體中文化：打包安裝檢查不再依賴英文 `Usage:` 文案；Linux 隔離安裝 tarball 後，`iap`／`itsaplan` 的 help、version 與無認證 doctor JSON 驗證通過，未發布 npm 套件或呼叫正式 API。

package/dist/cli.js

@@ -7,6 +7,7 @@ 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 { runInitiative } from "./initiatives.js";
 import { runProjectConfig } from "./project-config.js";
 import { validateOutput, projectOutput, needsIssueStates, } from "./output.js";
 const program = new Command()
@@ -96,7 +97,8 @@ const wrap = (handler) => async (...args) => {
             "logout",
             "init",
         ].includes(command.name()) ||
-            (command.parent?.name() === "document" && command.name() === "create") ||
+            (["document", "initiative"].includes(command.parent?.name() ?? "") &&
+                command.name() === "create") ||
             (command.name() === "project" &&
                 ["set", "unset"].includes(command.parent?.name() ?? "") &&
                 command.parent?.parent?.name() === "config") ||
@@ -295,6 +297,67 @@ issue
     project: globals(c).project,
     ...issueOutputOptions(c),
 })));
+const initiative = program
+    .command("initiative")
+    .description("列出、檢視、建立與編輯專案計畫");
+initiative
+    .command("list")
+    .description("列出專案計畫；使用頁碼瀏覽結果")
+    .option("--page <number>", "頁碼，從 1 開始")
+    .option("--limit <number>", "每頁數量，範圍為 1–100")
+    .option("--status <statuses>", "依狀態篩選，多個狀態以逗號分隔")
+    .option("--search <text>", "搜尋標題")
+    .option("--sort <field>", "排序欄位：title、priority、targetDate、owner")
+    .option("--dir <direction>", "排序方向：asc 或 desc")
+    .addHelpText("after", `
+範例使用虛構的專案參照：
+  iap initiative list --project acme.MKT --status active --page 1 --json`)
+    .action(wrap(async (c) => runInitiative(await createContext(globals(c)), "list", undefined, {
+    ...c.opts(),
+    project: globals(c).project,
+})));
+initiative
+    .command("view <initiative-id>")
+    .description("依內部數值 ID 檢視計畫")
+    .addHelpText("after", `
+範例使用虛構 ID：
+  iap initiative view 123 --project acme.MKT --json`)
+    .action(wrap(async (c) => runInitiative(await createContext(globals(c)), "view", c.args[0], {
+    project: globals(c).project,
+})));
+for (const action of ["create", "edit"]) {
+    const command = initiative
+        .command(action === "create" ? "create" : "edit <initiative-id>")
+        .description(action === "create" ? "建立專案計畫" : "只更新明確指定的計畫欄位")
+        .option("--title <text>", "計畫標題")
+        .option("--body <text>", "Markdown 內容")
+        .option("--body-file <file|->", "UTF-8 Markdown 檔案，或明確指定標準輸入 -")
+        .option("--status <status>", "計畫狀態：proposed、planned、active、completed、canceled")
+        .option("--owner <username|@me>", "指派專案成員為負責人")
+        .option("--priority <priority>", "優先級：urgent、high、medium、low")
+        .option("--start-date <date>", "開始日期，格式為 YYYY-MM-DD")
+        .option("--target-date <date>", "目標日期，格式為 YYYY-MM-DD")
+        .option("--agent <name>", "宣告代理：codex 或 claude")
+        .option("--human", "明確宣告人工作業；不可與代理環境變數並用")
+        .option("--dry-run", "只讀取與驗證；顯示確切請求但不寫入");
+    if (action === "create")
+        command.option("--label <name>", "加入精確標籤，可重複指定", (value, previous) => [...previous, value], []);
+    else
+        command
+            .option("--remove-owner", "清除負責人")
+            .option("--remove-priority", "清除優先級")
+            .option("--remove-start-date", "清除開始日期")
+            .option("--remove-target-date", "清除目標日期")
+            .option("--add-label <name>", "加入精確標籤，可重複指定", (value, previous) => [...previous, value], [])
+            .option("--remove-label <name>", "移除精確標籤，可重複指定", (value, previous) => [...previous, value], []);
+    command.addHelpText("after", action === "create"
+        ? "\n範例使用虛構資料：\n  iap initiative create --project acme.MKT --title 計畫 --human --dry-run"
+        : "\n範例使用虛構 ID：\n  iap initiative edit 123 --project acme.MKT --status active --human --dry-run");
+    command.action(wrap(async (c) => runInitiative(await createContext(globals(c)), action, c.args[0], {
+        ...c.opts(),
+        project: globals(c).project,
+    })));
+}
 const document = program
     .command("document")
     .description("發布 Markdown 文件；專案可見不等於網際網路公開");
@@ -379,7 +442,7 @@ for (const action of [
 }
 program
     .command("api <relative-path>")
-    .description("原始 API 入口；工作項目與文件寫入必須使用高階指令")
+    .description("原始 API 入口；工作項目、文件與計畫寫入必須使用高階指令")
     .addOption(new Option("--method <method>", "HTTP 方法")
     .choices(["GET", "HEAD", "POST", "PATCH", "PUT", "DELETE"])
     .default("GET"))
@@ -409,6 +472,8 @@ catch (error) {
             ((words.includes("issue") &&
                 ["edit", "comment", "link-document", "link-pr"].some((action) => words.includes(action))) ||
                 (words.includes("document") && words.includes("create")) ||
+                (words.includes("initiative") &&
+                    ["create", "edit"].includes(words.slice(words.indexOf("initiative") + 1).find((word) => ["list", "view", "create", "edit"].includes(word)) ?? "")) ||
                 words.includes("init") ||
                 (words.includes("auth") &&
                     (words.includes("login") || words.includes("logout"))) ||

package/dist/commands.js

@@ -589,6 +589,9 @@ function protectedResourceWrite(path) {
         return "issue";
     if (/^\/projects\/[^/]+\/documents(?:\/|$)/i.test(pathname))
         return "document";
+    if (/^\/(?:initiatives|initiative-attachments)(?:\/|$)/i.test(pathname) ||
+        /^\/projects\/[^/]+\/initiatives(?:\/|$)/i.test(pathname))
+        return "initiative";
     return undefined;
 }
 export async function runApi(ctx, path, options) {
@@ -603,9 +606,13 @@ export async function runApi(ctx, path, options) {
         if (resource)
             throw new CliError(resource === "issue"
                 ? "RAW_ISSUE_WRITE_FORBIDDEN"
-                : "RAW_DOCUMENT_WRITE_FORBIDDEN", resource === "issue"
+                : resource === "document"
+                    ? "RAW_DOCUMENT_WRITE_FORBIDDEN"
+                    : "RAW_INITIATIVE_WRITE_FORBIDDEN", resource === "issue"
                 ? "Raw writes to issues and their child resources are disabled; use supported issue commands. Other issue mutations are not yet supported."
-                : "Raw Docs writes are disabled; use supported document and issue link-document commands. Other Docs mutations are not yet supported.", 2);
+                : resource === "document"
+                    ? "Raw Docs writes are disabled; use supported document and issue link-document commands. Other Docs mutations are not yet supported."
+                    : "Raw initiative writes are disabled; use supported initiative commands. Other initiative mutations are not yet supported.", 2);
         if (!write && options.input !== undefined)
             throw new CliError("INPUT_NOT_SUPPORTED", "GET and HEAD do not accept --input.", 2);
         let body;

package/dist/contracts.d.ts

@@ -44,4 +44,4 @@ export interface Context {
     };
 }
 export declare const CLI_VERSION: string;
-export declare const API_BASELINE = "1.9.0";
+export declare const API_BASELINE = "1.10.0";

package/dist/contracts.js

@@ -11,4 +11,4 @@ export class CliError extends Error {
     }
 }
 export const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
-export const API_BASELINE = "1.9.0";
+export const API_BASELINE = "1.10.0";

package/dist/initiatives.d.ts

@@ -0,0 +1,16 @@
+import { type Context, type Result } from "./contracts.js";
+import { type IssueOptions } from "./issues.js";
+export interface InitiativeOptions extends IssueOptions {
+    page?: string | number;
+    status?: string;
+    sort?: string;
+    dir?: string;
+    owner?: string;
+    removeOwner?: boolean;
+    startDate?: string;
+    removeStartDate?: boolean;
+    targetDate?: string;
+    removeTargetDate?: boolean;
+    label?: string[];
+}
+export declare function runInitiative(ctx: Context, action: string, initiativeId: string | undefined, options: InitiativeOptions): Promise<Result>;

package/dist/initiatives.js

@@ -0,0 +1,241 @@
+import { isDeepStrictEqual } from "node:util";
+import { CliError } from "./contracts.js";
+import { getProject, integer, me, object, objects, positive, projectRef, publicData, readBody } from "./issues.js";
+import { applied, preview, verificationFailed, withWrite, writeFailure } from "./writes.js";
+const statuses = ["proposed", "planned", "active", "completed", "canceled"];
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function unsupported(message) {
+    throw new CliError("UNSUPPORTED_RESPONSE", message);
+}
+function selectedRef(ctx, options) {
+    const ref = options.project ?? ctx.options.project ?? ctx.project;
+    return ref === undefined ? undefined : projectRef(ref);
+}
+async function selectedProject(ctx, options) {
+    const ref = selectedRef(ctx, options);
+    if (ref === undefined)
+        throw new CliError("PROJECT_REQUIRED", "Provide --project team.KEY or configure a project");
+    return getProject(ctx, ref);
+}
+function initiative(value, id) {
+    const item = object(value, "initiative");
+    if (!positive(item.id) || !positive(item.projectId))
+        unsupported("Initiative response is missing stable identifiers");
+    if (id !== undefined && item.id !== id)
+        unsupported("Initiative response has a different ID");
+    return item;
+}
+async function projectFor(ctx, options, item) {
+    let ref = selectedRef(ctx, options);
+    if (ref === undefined) {
+        const projects = objects(await ctx.client.request("/projects"), "projects");
+        const matches = projects.filter((project) => project.id === item.projectId);
+        if (matches.length !== 1 || typeof matches[0].ref !== "string")
+            unsupported("Cannot resolve the initiative project; provide --project team.KEY");
+        ref = matches[0].ref;
+    }
+    const setup = await getProject(ctx, ref);
+    if (setup.project.id !== item.projectId)
+        throw new CliError("PROJECT_CONFLICT", "The initiative does not belong to the selected project");
+    return setup;
+}
+function canonical(setup) {
+    return projectRef(String(setup.project.ref));
+}
+function validateStatus(value, multiple) {
+    const values = multiple ? value.split(",") : [value];
+    if (!values.length || values.some((entry) => !statuses.includes(entry)))
+        throw new CliError("INVALID_STATUS", `--status must be ${statuses.join("|")}${multiple ? " or a comma-separated subset" : ""}`);
+}
+function labelId(setup, input) {
+    const matches = setup.labels.filter((entry) => entry.name === input || String(entry.id) === input);
+    if (!matches.length)
+        throw new CliError("VALUE_NOT_FOUND", `Label ${JSON.stringify(input)} is not available in this project`);
+    if (matches.length !== 1)
+        throw new CliError("AMBIGUOUS_VALUE", `Label ${JSON.stringify(input)} is ambiguous`);
+    return Number(matches[0].id);
+}
+async function ownerId(ctx, setup, value) {
+    const input = value === "@me" ? String((await me(ctx)).id) : value.replace(/^@/, "");
+    const matches = setup.assignees.filter((entry) => entry.kind === "member" && (entry.userId === input || entry.username === input));
+    if (!matches.length)
+        throw new CliError("VALUE_NOT_FOUND", `Owner ${JSON.stringify(value)} is not available in this project`);
+    if (matches.length !== 1)
+        throw new CliError("AMBIGUOUS_VALUE", `Owner ${JSON.stringify(value)} is ambiguous`);
+    return String(matches[0].userId);
+}
+function signedDescription(body, actor, editing) {
+    let value = body;
+    if (actor.kind === "agent") {
+        value = value.trimEnd();
+        const footer = /(?:^|\r?\n[ \t]*\r?\n)— (?:by|last edited by) (?:Codex|Claude) via iap$/u;
+        while (footer.test(value))
+            value = value.replace(footer, "").trimEnd();
+        value = `${value}\n\n— ${editing ? "last edited by" : "by"} ${actor.name === "codex" ? "Codex" : "Claude"} via iap`;
+    }
+    return value;
+}
+function date(value, flag) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00Z`)) || new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) !== value)
+        throw new CliError("INVALID_DATE", `${flag} must be a valid YYYY-MM-DD date`);
+    return value;
+}
+async function fields(ctx, setup, options, actor, item) {
+    for (const [value, remove, flag] of [
+        [options.owner, options.removeOwner, "owner"],
+        [options.priority, options.removePriority, "priority"],
+        [options.startDate, options.removeStartDate, "start-date"],
+        [options.targetDate, options.removeTargetDate, "target-date"],
+    ]) {
+        if (value !== undefined && remove)
+            throw new CliError("CONFLICTING_ARGUMENTS", `--${flag} and --remove-${flag} conflict`);
+    }
+    const body = {};
+    if (options.title !== undefined) {
+        if (!options.title.trim())
+            throw new CliError("INVALID_TITLE", "--title must not be empty");
+        body.title = options.title;
+    }
+    const description = await readBody(options);
+    if (description !== undefined)
+        body.description = signedDescription(description, actor, item !== undefined);
+    if (options.status !== undefined) {
+        validateStatus(options.status, false);
+        body.status = options.status;
+    }
+    if (options.owner !== undefined)
+        body.ownerUserId = await ownerId(ctx, setup, options.owner);
+    if (options.removeOwner)
+        body.ownerUserId = null;
+    if (options.priority !== undefined) {
+        if (!["urgent", "high", "medium", "low"].includes(options.priority))
+            throw new CliError("INVALID_PRIORITY", "--priority must be urgent|high|medium|low");
+        body.priority = options.priority;
+    }
+    if (options.removePriority)
+        body.priority = null;
+    if (options.startDate !== undefined)
+        body.startDate = date(options.startDate, "--start-date");
+    if (options.removeStartDate)
+        body.startDate = null;
+    if (options.targetDate !== undefined)
+        body.targetDate = date(options.targetDate, "--target-date");
+    if (options.removeTargetDate)
+        body.targetDate = null;
+    const add = [...(options.label ?? []), ...(options.addLabel ?? [])].map((name) => labelId(setup, name));
+    const remove = (options.removeLabel ?? []).map((name) => labelId(setup, name));
+    if (add.some((id) => remove.includes(id)))
+        throw new CliError("CONFLICTING_ARGUMENTS", "The same label cannot be added and removed");
+    if (add.length || remove.length) {
+        if (item && (!Array.isArray(item.labelIds) || !item.labelIds.every(positive)))
+            unsupported("Initiative response is missing labelIds; cannot preserve existing labels");
+        body.labelIds = [...new Set([...(item ? item.labelIds.filter((id) => !remove.includes(id)) : []), ...add])];
+    }
+    return body;
+}
+function matches(value, id, projectId, body) {
+    if (!record(value) || !positive(value.id) || value.id !== id || value.projectId !== projectId)
+        return false;
+    return Object.entries(body).every(([key, expected]) => {
+        const actual = value[key];
+        if (key === "labelIds" && Array.isArray(actual) && Array.isArray(expected))
+            return actual.every(positive) && isDeepStrictEqual([...actual].sort((a, b) => a - b), [...expected].sort((a, b) => a - b));
+        return isDeepStrictEqual(actual, expected);
+    });
+}
+async function list(ctx, options) {
+    const page = integer(options.page ?? 1, "--page");
+    const pageSize = integer(options.limit ?? 25, "--limit", 100);
+    if (options.status !== undefined)
+        validateStatus(options.status, true);
+    if (options.sort !== undefined && !["title", "priority", "targetDate", "owner"].includes(options.sort))
+        throw new CliError("INVALID_SORT", "--sort must be title|priority|targetDate|owner");
+    if (options.dir !== undefined && !["asc", "desc"].includes(options.dir))
+        throw new CliError("INVALID_DIRECTION", "--dir must be asc|desc");
+    const setup = await selectedProject(ctx, options);
+    const response = object(await ctx.client.request(`/projects/${encodeURIComponent(canonical(setup))}/initiatives`, { query: { page, pageSize, status: options.status, search: options.search, sort: options.sort, dir: options.dir } }), "initiative page");
+    const items = objects(response.items, "initiative items");
+    if (!Number.isSafeInteger(response.total) || response.total < 0 || response.page !== page || response.pageSize !== pageSize || items.length > pageSize || items.some((item) => !positive(item.id) || item.projectId !== setup.project.id))
+        unsupported("Invalid initiative page or foreign initiative");
+    const total = response.total;
+    const offset = (page - 1) * pageSize;
+    if (!Number.isSafeInteger(offset))
+        unsupported("Initiative page offset is invalid");
+    const nextPage = offset + pageSize < total ? page + 1 : null;
+    return { data: { items: publicData(items), total, page, pageSize, nextPage }, meta: { scope: { projectId: setup.project.id, projectRef: canonical(setup) }, limit: pageSize, returned: items.length, completeness: page === 1 && items.length === total ? "complete" : "partial" } };
+}
+async function writeInitiative(ctx, action, identifier, options, actor) {
+    const editing = action === "edit";
+    if (!editing && identifier !== undefined)
+        throw new CliError("CONFLICTING_ARGUMENTS", "initiative create does not accept an ID");
+    let item;
+    let setup;
+    if (editing) {
+        if (identifier === undefined)
+            throw new CliError("INITIATIVE_REQUIRED", "Provide a numeric initiative ID");
+        const id = integer(identifier, "initiative ID");
+        item = initiative(await ctx.client.request(`/initiatives/${id}`), id);
+        setup = await projectFor(ctx, options, item);
+    }
+    else
+        setup = await selectedProject(ctx, options);
+    const body = await fields(ctx, setup, options, actor, item);
+    if (!editing && body.title === undefined)
+        throw new CliError("TITLE_REQUIRED", "Provide --title");
+    if (editing && Object.keys(body).length === 0)
+        throw new CliError("NO_CHANGES", "Provide at least one initiative edit field");
+    if (item)
+        for (const key of Object.keys(body))
+            if (!(key in item))
+                unsupported(`Initiative response is missing ${key}; cannot build a trustworthy diff`);
+    const path = editing ? `/initiatives/${item.id}` : `/projects/${encodeURIComponent(canonical(setup))}/initiatives`;
+    const method = editing ? "PATCH" : "POST";
+    const diff = Object.fromEntries(Object.entries(body).map(([key, value]) => [key, { before: item ? item[key] : null, after: value }]));
+    const data = { action, projectId: setup.project.id, projectRef: canonical(setup), ...(item ? { initiativeId: item.id } : {}), changed: false, diff };
+    if (options.dryRun)
+        return preview(ctx, actor, data, path, body, [], method);
+    let response;
+    try {
+        response = await ctx.client.request(path, { method, body });
+    }
+    catch (error) {
+        return writeFailure(error, data, actor, "initiative");
+    }
+    data.changed = true;
+    if (!editing && record(response) && positive(response.id))
+        data.initiativeId = response.id;
+    if (matches(response, data.initiativeId, setup.project.id, body))
+        return applied(data, actor);
+    if (positive(data.initiativeId)) {
+        try {
+            if (matches(await ctx.client.request(`/initiatives/${data.initiativeId}`), data.initiativeId, setup.project.id, body))
+                return applied(data, actor);
+        }
+        catch { /* The accepted write retains its ID even if verification fails. */ }
+    }
+    return verificationFailed(data, actor, "initiative");
+}
+export async function runInitiative(ctx, action, initiativeId, options) {
+    if (action === "list") {
+        if (initiativeId !== undefined)
+            throw new CliError("CONFLICTING_ARGUMENTS", "initiative list does not accept an ID");
+        return list(ctx, options);
+    }
+    if (action === "view") {
+        if (initiativeId === undefined)
+            throw new CliError("INITIATIVE_REQUIRED", "Provide a numeric initiative ID");
+        const id = integer(initiativeId, "initiative ID");
+        const item = initiative(await ctx.client.request(`/initiatives/${id}`), id);
+        const setup = await projectFor(ctx, options, item);
+        return { data: { initiative: publicData(item), projectRef: canonical(setup) }, meta: { scope: { initiativeId: id, projectId: setup.project.id, projectRef: canonical(setup) } } };
+    }
+    if (action === "create" || action === "edit") {
+        const result = await withWrite(options, (actor) => writeInitiative(ctx, action, initiativeId, options, actor));
+        if (record(result.data)) {
+            const { initiativeId: id, projectId, projectRef: ref } = result.data;
+            result.meta = { ...result.meta, scope: { ...(id !== undefined ? { initiativeId: id } : {}), projectId, projectRef: ref } };
+        }
+        return result;
+    }
+    throw new CliError("INVALID_ARGUMENT", "Unknown initiative action");
+}

package/dist/output.js

@@ -54,6 +54,7 @@ const schemas = {
     },
     "issue.list": {
         ...issueFields,
+        parent: scalarFields("id identifier title"),
         state: scalarFields("id name stateType unavailable"),
     },
     "issue.resolve": scalarFields("id issueId projectId identifier sequenceNumber projectRef"),

package/dist/writes.d.ts

@@ -2,7 +2,7 @@ import { type Actor, type Context, type ObjectData, type Result } from "./contra
 import { type IssueOptions } from "./issues.js";
 /** Preflight failures are never mistaken for a write with an unknown outcome. */
 export declare function withWrite(options: IssueOptions, operation: (actor: Actor) => Promise<Result>): Promise<Result>;
-export declare function preview(ctx: Context, actor: Actor, data: ObjectData, path: string, body: ObjectData, warnings?: string[]): Promise<Result>;
-export declare function writeFailure(error: unknown, data: ObjectData, actor: Actor): Result;
-export declare function verificationFailed(data: ObjectData, actor: Actor): Result;
+export declare function preview(ctx: Context, actor: Actor, data: ObjectData, path: string, body: ObjectData, warnings?: string[], method?: string): Promise<Result>;
+export declare function writeFailure(error: unknown, data: ObjectData, actor: Actor, resource?: string): Result;
+export declare function verificationFailed(data: ObjectData, actor: Actor, resource?: string): Result;
 export declare function applied(data: ObjectData, actor: Actor): Result;

package/dist/writes.js

@@ -26,13 +26,13 @@ export async function withWrite(options, operation) {
         });
     }
 }
-export async function preview(ctx, actor, data, path, body, warnings = []) {
+export async function preview(ctx, actor, data, path, body, warnings = [], method = "POST") {
     return {
         data: {
             ...data,
             dryRun: true,
             identity: await me(ctx),
-            request: { method: "POST", path, body },
+            request: { method, path, body },
             warnings: [
                 "Preview sends no writes and does not guarantee server permissions or concurrent state.",
                 ...warnings,
@@ -43,14 +43,14 @@ export async function preview(ctx, actor, data, path, body, warnings = []) {
         verification: "not_run",
     };
 }
-export function writeFailure(error, data, actor) {
-    const result = issueWriteFailure(error, data, actor, "document or relation");
+export function writeFailure(error, data, actor, resource = "document or relation") {
+    const result = issueWriteFailure(error, data, actor, resource);
     if (result.outcome === "unknown")
         delete data.changed;
     return result;
 }
-export function verificationFailed(data, actor) {
-    return issueVerificationFailed(data, actor, "document or relation");
+export function verificationFailed(data, actor, resource = "document or relation") {
+    return issueVerificationFailed(data, actor, resource);
 }
 export function applied(data, actor) {
     return { data, meta: { actor }, outcome: "applied", verification: "passed" };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dac-tech-team-tw/itsaplan-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Composable It's a Plan CLI for humans and coding agents",
   "type": "module",
   "repository": {