casement-lite-cli 0.0.1

package/dist/index.js

@@ -0,0 +1,1863 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { spawn } from "child_process";
+import { createInterface } from "readline/promises";
+import { stdin as input, stdout as output } from "process";
+var APP_DIR = join(homedir(), ".casement-lite");
+var SESSION_FILE = join(APP_DIR, "session.json");
+var DEFAULT_BASE_URL = "https://casement.scredit.io";
+function toText(v) {
+  if (v === void 0 || v === null) return "";
+  return String(v).trim();
+}
+function toBool(v, fallback) {
+  const s = toText(v).toLowerCase();
+  if (!s) return fallback;
+  return ["1", "true", "yes", "y", "on"].includes(s);
+}
+function toPositiveInt(v, fallback) {
+  const n = Number(v);
+  if (!Number.isFinite(n) || n <= 0) return fallback;
+  return Math.floor(n);
+}
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+function normalizeBaseUrl(url) {
+  const raw = toText(url) || DEFAULT_BASE_URL;
+  const u = raw.startsWith("http://") || raw.startsWith("https://") ? raw : `https://${raw}`;
+  return u.replace(/\/$/, "");
+}
+function parseGlobalArgv(argv) {
+  const args = argv.slice(2);
+  const filtered = [];
+  let json = false;
+  for (const arg of args) {
+    if (arg === "--json") {
+      json = true;
+      continue;
+    }
+    filtered.push(arg);
+  }
+  return {
+    command: filtered[0] || null,
+    args: filtered.slice(1),
+    options: { json }
+  };
+}
+function parseFlags(args) {
+  const positionals = [];
+  const flags = {};
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith("--")) {
+      positionals.push(arg);
+      continue;
+    }
+    const body = arg.slice(2);
+    if (!body) continue;
+    if (body.includes("=")) {
+      const [k, ...rest] = body.split("=");
+      flags[k] = rest.join("=");
+      continue;
+    }
+    const next = args[i + 1];
+    if (next !== void 0 && !next.startsWith("--")) {
+      flags[body] = next;
+      i += 1;
+    } else {
+      flags[body] = true;
+    }
+  }
+  return { positionals, flags };
+}
+function getFlag(flags, ...keys) {
+  for (const k of keys) {
+    if (Object.prototype.hasOwnProperty.call(flags, k)) {
+      return toText(flags[k]);
+    }
+  }
+  return "";
+}
+function printResult(data, options) {
+  const spacing = options.json ? 0 : 2;
+  console.log(JSON.stringify(data, null, spacing));
+}
+function ensureSessionDir() {
+  if (!existsSync(APP_DIR)) {
+    mkdirSync(APP_DIR, { recursive: true });
+  }
+}
+function loadSession() {
+  if (!existsSync(SESSION_FILE)) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(SESSION_FILE, "utf-8"));
+    if (!parsed || typeof parsed !== "object") return null;
+    const baseUrl = normalizeBaseUrl(parsed.baseUrl || DEFAULT_BASE_URL);
+    return {
+      baseUrl,
+      token: toText(parsed.token) || void 0,
+      cookie: toText(parsed.cookie) || void 0,
+      updatedAt: parsed.updatedAt || (/* @__PURE__ */ new Date()).toISOString()
+    };
+  } catch {
+    return null;
+  }
+}
+function saveSession(session) {
+  ensureSessionDir();
+  writeFileSync(SESSION_FILE, `${JSON.stringify(session, null, 2)}
+`, "utf-8");
+}
+function removeSession() {
+  if (existsSync(SESSION_FILE)) rmSync(SESSION_FILE);
+}
+async function prompt(question, mask = false) {
+  const rl = createInterface({ input, output, terminal: true });
+  if (!mask) {
+    const ans = await rl.question(question);
+    rl.close();
+    return ans.trim();
+  }
+  const previousRaw = input.isRaw;
+  if (typeof input.setRawMode === "function") {
+    input.setRawMode(true);
+  }
+  output.write(question);
+  let value = "";
+  await new Promise((resolve) => {
+    const onData = (chunk) => {
+      const str = chunk.toString("utf8");
+      if (str === "\r" || str === "\n") {
+        output.write("\n");
+        input.off("data", onData);
+        resolve();
+        return;
+      }
+      if (str === "") {
+        input.off("data", onData);
+        rl.close();
+        process.exit(1);
+      }
+      if (str === "\x7F") {
+        if (value.length > 0) {
+          value = value.slice(0, -1);
+          output.write("\b \b");
+        }
+        return;
+      }
+      value += str;
+      output.write("*");
+    };
+    input.on("data", onData);
+  });
+  if (typeof input.setRawMode === "function") {
+    input.setRawMode(Boolean(previousRaw));
+  }
+  rl.close();
+  return value.trim();
+}
+function openUrl(url) {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    spawn("open", [url], { stdio: "ignore", detached: true }).unref();
+    return;
+  }
+  if (platform === "win32") {
+    spawn("cmd", ["/c", "start", "", url], { stdio: "ignore", detached: true }).unref();
+    return;
+  }
+  spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function tokenFromCookieHeader(cookieHeader) {
+  const raw = toText(cookieHeader);
+  if (!raw) return "";
+  const wanted = /* @__PURE__ */ new Set([
+    "casement_login_token",
+    "CASEMENT_LOGIN_TOKEN",
+    "token",
+    "access_token",
+    "authorization",
+    "Authorization"
+  ]);
+  const chunks = raw.split(";");
+  for (const one of chunks) {
+    const [k, ...rest] = one.split("=");
+    const key = toText(k);
+    if (!key || !wanted.has(key)) continue;
+    const value = toText(rest.join("="));
+    if (!value) continue;
+    if (/^bearer\s+/i.test(value)) return value.replace(/^bearer\s+/i, "").trim();
+    return value;
+  }
+  return "";
+}
+function maybeDecodeURIComponent(text) {
+  const raw = toText(text);
+  if (!raw) return "";
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+async function captureSessionFromBrowser(args) {
+  const startedAt = Date.now();
+  const timeoutMs = Math.max(30, args.timeoutSec) * 1e3;
+  const deadline = startedAt + timeoutMs;
+  let attempts = 0;
+  let playwrightModule;
+  try {
+    const dynamicImport = new Function("m", "return import(m)");
+    playwrightModule = await dynamicImport("playwright");
+  } catch {
+    return {
+      ok: false,
+      token: "",
+      cookie: "",
+      error: "\u7F3A\u5C11 playwright \u4F9D\u8D56\u3002\u8BF7\u5148\u6267\u884C: corepack pnpm install",
+      attempts,
+      elapsedMs: Date.now() - startedAt
+    };
+  }
+  const chromium = playwrightModule?.chromium;
+  if (!chromium || typeof chromium.launch !== "function") {
+    return {
+      ok: false,
+      token: "",
+      cookie: "",
+      error: "playwright.chromium \u4E0D\u53EF\u7528",
+      attempts,
+      elapsedMs: Date.now() - startedAt
+    };
+  }
+  let browser = null;
+  try {
+    const launchOptions = { headless: args.headless };
+    if (args.channel) launchOptions.channel = args.channel;
+    try {
+      browser = await chromium.launch(launchOptions);
+    } catch (launchErr) {
+      if (args.channel) {
+        browser = await chromium.launch({ headless: args.headless });
+      } else {
+        throw launchErr;
+      }
+    }
+    const context = await browser.newContext();
+    const page = await context.newPage();
+    await page.goto(args.loginUrl, { waitUntil: "domcontentloaded", timeout: 12e4 });
+    if (!args.json) {
+      console.log(`\u5DF2\u6253\u5F00\u6D4F\u89C8\u5668\u767B\u5F55\u9875: ${args.loginUrl}`);
+      console.log("\u8BF7\u5728\u8BE5\u7A97\u53E3\u5B8C\u6210\u767B\u5F55\uFF0CCLI \u5C06\u81EA\u52A8\u91C7\u96C6 token/cookie\u3002");
+    }
+    while (Date.now() < deadline) {
+      attempts += 1;
+      const cookies = await context.cookies(args.baseUrl);
+      const cookieHeader = cookies.map((c) => `${c.name}=${c.value}`).join("; ");
+      const storageToken = await page.evaluate(() => {
+        const g = globalThis;
+        const keyCandidates = [
+          "CASEMENT_LOGIN_TOKEN",
+          "casement_login_token",
+          "caseMent_login_token",
+          "login_token",
+          "access_token",
+          "token",
+          "Authorization",
+          "authorization"
+        ];
+        const stores = [g.localStorage, g.sessionStorage];
+        for (const store of stores) {
+          for (const key of keyCandidates) {
+            const v = store.getItem(key);
+            if (v) return v;
+          }
+        }
+        return "";
+      }).catch(() => "");
+      const cookieToken = tokenFromCookieHeader(cookieHeader);
+      const token = toText(maybeDecodeURIComponent(storageToken || cookieToken));
+      const cookie = toText(cookieHeader);
+      if (token || cookie) {
+        const probeSession = {
+          baseUrl: args.baseUrl,
+          token: token || void 0,
+          cookie: cookie || void 0,
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+        };
+        const probe = await new CasementClient(probeSession).post("/casement/project/list", {
+          showTotal: true,
+          projectStatus: 1
+        });
+        if (probe.ok) {
+          return {
+            ok: true,
+            token,
+            cookie,
+            error: null,
+            attempts,
+            elapsedMs: Date.now() - startedAt
+          };
+        }
+      }
+      await sleep(args.pollMs);
+    }
+    return {
+      ok: false,
+      token: "",
+      cookie: "",
+      error: `\u8D85\u65F6\u672A\u68C0\u6D4B\u5230\u6709\u6548\u767B\u5F55\u4F1A\u8BDD\uFF08>${args.timeoutSec}s\uFF09`,
+      attempts,
+      elapsedMs: Date.now() - startedAt
+    };
+  } catch (e) {
+    const msg = toText(e);
+    const hint = /Executable doesn't exist|Please run the following command/i.test(msg) ? "\u6D4F\u89C8\u5668\u8FD0\u884C\u65F6\u7F3A\u5931\uFF0C\u53EF\u6267\u884C: npx playwright install chromium" : "";
+    return {
+      ok: false,
+      token: "",
+      cookie: "",
+      error: hint ? `${msg}
+${hint}` : String(e),
+      attempts,
+      elapsedMs: Date.now() - startedAt
+    };
+  } finally {
+    if (browser) {
+      await browser.close().catch(() => {
+      });
+    }
+  }
+}
+var CasementClient = class {
+  baseUrl;
+  token;
+  cookie;
+  constructor(session) {
+    this.baseUrl = normalizeBaseUrl(session.baseUrl || DEFAULT_BASE_URL);
+    this.token = toText(session.token) || void 0;
+    this.cookie = toText(session.cookie) || void 0;
+  }
+  getSessionSummary() {
+    return {
+      baseUrl: this.baseUrl,
+      hasToken: !!this.token,
+      hasCookie: !!this.cookie
+    };
+  }
+  async post(path, body) {
+    const url = `${this.baseUrl}${path.startsWith("/") ? path : `/${path}`}`;
+    const headers = {
+      accept: "application/json",
+      "content-type": "application/json;charset=UTF-8"
+    };
+    if (this.token) headers.authorization = `Bearer ${this.token}`;
+    if (this.cookie) headers.cookie = this.cookie;
+    const resp = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body || {})
+    });
+    const text = await resp.text();
+    const parsed = safeJsonParse(text);
+    const raw = parsed ?? { code: resp.ok ? 0 : resp.status, msg: text };
+    const code = raw && typeof raw === "object" && "code" in raw ? Number(raw.code) : null;
+    const msg = raw && typeof raw === "object" ? toText(raw.msg || raw.message) || null : null;
+    const result = raw && typeof raw === "object" && "result" in raw ? raw.result : null;
+    return {
+      ok: code === 0,
+      code,
+      msg,
+      httpStatus: resp.status,
+      result,
+      raw
+    };
+  }
+};
+function ensureClientOrThrow() {
+  const session = loadSession();
+  if (!session) {
+    throw new Error("\u672A\u627E\u5230\u767B\u5F55\u4F1A\u8BDD\u3002\u8BF7\u5148\u6267\u884C: casement auth login");
+  }
+  if (!toText(session.token) && !toText(session.cookie)) {
+    throw new Error("\u4F1A\u8BDD\u65E0 token/cookie\u3002\u8BF7\u91CD\u65B0\u6267\u884C: casement auth login");
+  }
+  return new CasementClient(session);
+}
+function phaseNameFromCode(code) {
+  const n = Number(code);
+  const m = {
+    0: "TODO",
+    10: "DEV",
+    20: "TEST",
+    30: "UAT",
+    40: "LIVE",
+    99: "DONE"
+  };
+  return m[n] || `PHASE_${String(code)}`;
+}
+function normalizePhaseTimeline(versionPhase) {
+  const src = versionPhase && typeof versionPhase === "object" ? versionPhase : {};
+  const preferred = ["devTd", "devIntegration", "dev", "test", "uat", "live"];
+  const keys = [.../* @__PURE__ */ new Set([...preferred, ...Object.keys(src)])];
+  const map = {};
+  const timeline = keys.map((k) => {
+    const node = src[k] && typeof src[k] === "object" ? src[k] : {};
+    const item = {
+      phase: k,
+      startTime: toText(node.startTime) || null,
+      endTime: toText(node.endTime) || null
+    };
+    map[k] = { startTime: item.startTime, endTime: item.endTime };
+    return item;
+  });
+  return { timeline, map };
+}
+function inferCheckpointStage(currentPhase) {
+  const n = Number(currentPhase);
+  const m = {
+    0: "TodoToDev",
+    10: "DevToTest",
+    20: "TestToUAT",
+    30: "UATToLive",
+    40: "LiveToComplete",
+    99: "Complete"
+  };
+  return m[n] || null;
+}
+function checkStatusName(code) {
+  const n = Number(code);
+  const m = {
+    1: "PASS",
+    2: "FAILURE",
+    3: "WARNING",
+    4: "SKIPPED"
+  };
+  return m[n] || `STATUS_${String(code)}`;
+}
+function normalizeAssignee(v) {
+  const raw = toText(v);
+  if (!raw) return "";
+  const at = raw.indexOf("@");
+  return at > 0 ? raw.slice(0, at) : raw;
+}
+function normalizePriority(v) {
+  const raw = toText(v);
+  if (!raw) return "";
+  const s = raw.toLowerCase();
+  const table = {
+    p0: "Highest",
+    highest: "Highest",
+    critical: "Highest",
+    blocker: "Highest",
+    p1: "High",
+    high: "High",
+    p2: "Medium",
+    medium: "Medium",
+    normal: "Medium",
+    p3: "Low",
+    low: "Low",
+    p4: "Lowest",
+    lowest: "Lowest",
+    trivial: "Lowest"
+  };
+  return table[s] || raw;
+}
+function normalizeRequirementType(v) {
+  const raw = toText(v);
+  if (!raw) return "";
+  const norm = raw.toLowerCase();
+  const rtMap = {
+    "on_call_incident_handling": "On_call_Incident_Handling",
+    "on-call & incident handling / \u503C\u73ED & \u6545\u969C\u5904\u7406": "On_call_Incident_Handling",
+    "business_support_collaboration": "Business_Support_Collaboration",
+    "business support & collaboration / \u4E1A\u52A1\u652F\u6301 & \u534F\u4F5C": "Business_Support_Collaboration",
+    "leave_vacation": "Leave_Vacation",
+    "leave & vacation / \u8BF7\u5047 & \u4F11\u5047": "Leave_Vacation",
+    "team_other_tasks": "Team_Other_Tasks",
+    "team & other tasks / \u56E2\u961F & \u5176\u4ED6\u5DE5\u4F5C": "Team_Other_Tasks"
+  };
+  return rtMap[norm] || raw;
+}
+function normalizeFieldName(rawField) {
+  const norm = toText(rawField).toLowerCase();
+  const table = {
+    summary: "summary",
+    title: "summary",
+    status: "status",
+    storypoints: "storyPoints",
+    storypoint: "storyPoints",
+    story_points: "storyPoints",
+    sp: "storyPoints",
+    priority: "priority",
+    assignee: "assignee",
+    owner: "assignee",
+    pic: "assignee",
+    phase: "phase",
+    stage: "phase",
+    startdate: "startDate",
+    start_date: "startDate",
+    duedate: "dueDate",
+    due_date: "dueDate",
+    description: "description",
+    desc: "description",
+    requirementtype: "requirementType",
+    requirement_type: "requirementType",
+    subtasktype: "requirementType",
+    subtask_type: "requirementType",
+    jirasubtasktype: "requirementType"
+  };
+  return table[norm] || toText(rawField);
+}
+function buildAssigneeFallbackCandidates(rawAssigneeInput, normalizedAssignee) {
+  const raw = toText(rawAssigneeInput);
+  const normalized = toText(normalizedAssignee);
+  if (!normalized || normalized.includes("@")) return [];
+  const out = [];
+  if (raw && raw.includes("@")) out.push(raw);
+  out.push(`${normalized}@shopee.com`);
+  out.push(`${normalized}@sea.com`);
+  const uniq = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const one of out) {
+    const key = toText(one).toLowerCase();
+    if (!key || key === normalized.toLowerCase()) continue;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    uniq.push(one);
+  }
+  return uniq;
+}
+async function authLogin(args, options) {
+  const parsed = parseFlags(args);
+  const flags = parsed.flags;
+  const fromFile = getFlag(flags, "from", "file");
+  let token = getFlag(flags, "token") || toText(process.env.CASEMENT_LOGIN_TOKEN);
+  let cookie = getFlag(flags, "cookie") || toText(process.env.CASEMENT_COOKIE);
+  const baseUrl = normalizeBaseUrl(getFlag(flags, "baseUrl", "base-url") || DEFAULT_BASE_URL);
+  const mode = toText(getFlag(flags, "mode")).toLowerCase();
+  const autoCapture = mode ? mode === "auto" : toBool(getFlag(flags, "auto"), true);
+  const autoOpen = toBool(flags.open, true);
+  const headlessFlag = toBool(flags.headless, false);
+  const headless = false;
+  const timeoutSec = toPositiveInt(getFlag(flags, "timeout", "timeoutSec", "timeout-sec"), 300);
+  const pollMs = Math.max(500, toPositiveInt(getFlag(flags, "pollMs", "poll-ms"), 2e3));
+  const browserChannel = toText(getFlag(flags, "browser", "channel") || "chrome");
+  const loginUrl = toText(getFlag(flags, "loginUrl", "login-url") || `${baseUrl}/workspace`);
+  const askInput = toBool(flags.interactive, true);
+  let loginMethod = "flags/env";
+  let autoCaptureDetail = null;
+  if (fromFile) {
+    try {
+      const obj = JSON.parse(readFileSync(fromFile, "utf-8"));
+      token = token || toText(obj.token || obj.CASEMENT_LOGIN_TOKEN);
+      cookie = cookie || toText(obj.cookie || obj.COOKIE || obj.cookieHeader);
+      loginMethod = "file";
+    } catch (e) {
+      printResult({ ok: false, error: `\u65E0\u6CD5\u8BFB\u53D6 --from \u6587\u4EF6: ${String(e)}` }, options);
+      process.exit(1);
+    }
+  }
+  if (!token && !cookie && autoCapture) {
+    const auto = await captureSessionFromBrowser({
+      baseUrl,
+      loginUrl,
+      headless,
+      timeoutSec,
+      pollMs,
+      channel: browserChannel,
+      json: options.json
+    });
+    autoCaptureDetail = {
+      ok: auto.ok,
+      error: auto.error,
+      attempts: auto.attempts,
+      elapsedMs: auto.elapsedMs,
+      channel: browserChannel,
+      headless,
+      requestedHeadless: headlessFlag,
+      timeoutSec
+    };
+    if (auto.ok) {
+      token = toText(token || auto.token);
+      cookie = toText(cookie || auto.cookie);
+      loginMethod = "auto-browser";
+    } else if (!options.json) {
+      console.log(`\u81EA\u52A8\u91C7\u96C6\u5931\u8D25: ${toText(auto.error) || "unknown"}`);
+      console.log("\u5C06\u56DE\u9000\u5230\u624B\u52A8\u8F93\u5165\u6A21\u5F0F\u3002");
+    }
+  }
+  if (!token && !cookie && askInput) {
+    if (autoOpen) {
+      openUrl(loginUrl);
+    }
+    if (!options.json) {
+      console.log("\u8BF7\u5728\u6D4F\u89C8\u5668\u5B8C\u6210\u767B\u5F55\u540E\uFF0C\u7C98\u8D34 token/cookie\uFF08\u53EF\u7A7A\u4E00\u9879\uFF0C\u81F3\u5C11\u8981\u6709\u4E00\u9879\uFF09\u3002");
+    }
+    token = token || await prompt("CASEMENT_LOGIN_TOKEN (\u53EF\u7559\u7A7A): ", true);
+    cookie = cookie || await prompt("Cookie (\u53EF\u7559\u7A7A): ");
+    loginMethod = "manual-input";
+  }
+  token = toText(token);
+  cookie = toText(cookie);
+  if (cookie.toLowerCase().startsWith("cookie:")) {
+    cookie = cookie.slice(7).trim();
+  }
+  if (!token && !cookie) {
+    printResult({
+      ok: false,
+      error: "\u7F3A\u5C11 token/cookie\uFF0C\u65E0\u6CD5\u521B\u5EFA\u4F1A\u8BDD",
+      hint: "\u53EF\u7528: casement auth login --token <TOKEN> --cookie '<k=v; ...>'",
+      autoCapture: autoCaptureDetail
+    }, options);
+    process.exit(1);
+  }
+  const session = {
+    baseUrl,
+    token: token || void 0,
+    cookie: cookie || void 0,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  saveSession(session);
+  const client = new CasementClient(session);
+  const probe = await client.post("/casement/project/list", { showTotal: true, projectStatus: 1 });
+  printResult({
+    ok: true,
+    saved: SESSION_FILE,
+    method: loginMethod,
+    session: {
+      baseUrl,
+      hasToken: !!session.token,
+      hasCookie: !!session.cookie,
+      updatedAt: session.updatedAt
+    },
+    autoCapture: autoCaptureDetail,
+    verify: {
+      ok: probe.ok,
+      code: probe.code,
+      msg: probe.msg,
+      httpStatus: probe.httpStatus
+    },
+    hint: probe.ok ? "\u767B\u5F55\u4F1A\u8BDD\u53EF\u7528" : "\u4F1A\u8BDD\u5DF2\u4FDD\u5B58\uFF0C\u4F46\u6821\u9A8C\u5931\u8D25\uFF0C\u53EF\u7A0D\u540E\u7528 casement auth status \u590D\u67E5"
+  }, options);
+}
+async function authStatus(options) {
+  const session = loadSession();
+  if (!session) {
+    printResult({ ok: false, exists: false, sessionFile: SESSION_FILE, hint: "\u5148\u6267\u884C casement auth login" }, options);
+    return;
+  }
+  const client = new CasementClient(session);
+  const probe = await client.post("/casement/project/list", { showTotal: true, projectStatus: 1 });
+  printResult({
+    ok: probe.ok,
+    exists: true,
+    sessionFile: SESSION_FILE,
+    session: {
+      baseUrl: session.baseUrl,
+      hasToken: !!session.token,
+      hasCookie: !!session.cookie,
+      updatedAt: session.updatedAt
+    },
+    verify: {
+      ok: probe.ok,
+      code: probe.code,
+      msg: probe.msg,
+      httpStatus: probe.httpStatus
+    }
+  }, options);
+}
+function authLogout(options) {
+  removeSession();
+  printResult({ ok: true, removed: SESSION_FILE }, options);
+}
+async function cmdProjects(args, options) {
+  const client = ensureClientOrThrow();
+  const parsed = parseFlags(args);
+  let keyword = getFlag(parsed.flags, "keyword") || toText(parsed.positionals[0]);
+  const limit = toPositiveInt(getFlag(parsed.flags, "limit") || parsed.positionals[1], 50);
+  let projectStatus = toPositiveInt(getFlag(parsed.flags, "projectStatus"), 1);
+  if (!getFlag(parsed.flags, "projectStatus") && keyword && /^\d+$/.test(keyword)) {
+    projectStatus = toPositiveInt(keyword, 1);
+    keyword = "";
+  }
+  const groupIdRaw = getFlag(parsed.flags, "groupId");
+  const groupId = groupIdRaw ? Number(groupIdRaw) : null;
+  const includeRaw = toBool(parsed.flags.raw, false);
+  const resp = await client.post("/casement/project/list", {
+    showTotal: true,
+    projectStatus
+  });
+  const result = resp.result || {};
+  let rows = Array.isArray(result.data) ? result.data : [];
+  if (Number.isFinite(groupId)) {
+    rows = rows.filter((x) => Number(x.groupId) === Number(groupId));
+  }
+  if (keyword) {
+    const q = keyword.toLowerCase();
+    rows = rows.filter((p) => [p.projectName, p.jiraLibraryKey, p.principal, p.groupName, p.relatedWiseskylarkProject].filter(Boolean).join(" ").toLowerCase().includes(q));
+  }
+  const projects = rows.map((p) => ({
+    id: p.id,
+    projectName: p.projectName,
+    jiraLibraryKey: p.jiraLibraryKey,
+    principal: p.principal,
+    groupId: p.groupId,
+    groupName: p.groupName,
+    projectStatus: p.projectStatus,
+    projectGrayStatus: p.projectGrayStatus,
+    relatedWiseskylarkProject: p.relatedWiseskylarkProject,
+    createTime: p.createTime,
+    updateTime: p.updateTime,
+    raw: includeRaw ? p : void 0
+  }));
+  printResult({
+    ok: resp.ok,
+    code: resp.code,
+    msg: resp.msg,
+    projectStatus,
+    keyword: keyword || null,
+    groupId,
+    total: result.total || rows.length,
+    filteredTotal: projects.length,
+    count: Math.min(projects.length, limit),
+    projects: projects.slice(0, limit)
+  }, options);
+}
+async function cmdProjectDetail(args, options) {
+  const client = ensureClientOrThrow();
+  const parsed = parseFlags(args);
+  const projectId = Number(getFlag(parsed.flags, "projectId") || parsed.positionals[0]);
+  if (!Number.isFinite(projectId) || projectId <= 0) {
+    printResult({ ok: false, error: "Missing or invalid projectId" }, options);
+    process.exit(1);
+  }
+  const includeMembers = toBool(getFlag(parsed.flags, "includeMembers") || parsed.positionals[1], false);
+  const includeVersions = toBool(getFlag(parsed.flags, "includeVersions") || parsed.positionals[2], false);
+  const includeRaw = toBool(parsed.flags.raw, false);
+  const memberPageSize = toPositiveInt(getFlag(parsed.flags, "memberPageSize"), 50);
+  const versionPageSize = toPositiveInt(getFlag(parsed.flags, "versionPageSize"), 20);
+  const detail = await client.post("/casement/project/detail", { projectId });
+  if (!detail.ok) {
+    printResult({ ok: false, error: detail.msg || "Failed to fetch project detail", code: detail.code, httpStatus: detail.httpStatus }, options);
+    return;
+  }
+  let members = null;
+  let membersTotal = null;
+  if (includeMembers) {
+    const m = await client.post("/casement/project-member/list", { projectId, current: 1, pageSize: memberPageSize });
+    if (m.ok) {
+      const rows = Array.isArray(m.result?.data) ? m.result.data : [];
+      membersTotal = Number(m.result?.total || rows.length);
+      members = rows.map((x) => ({
+        userId: x.userId,
+        email: x.email,
+        team: x.team,
+        roles: Array.isArray(x.roles) ? x.roles.map((r) => r.roleName || r.roleId) : [],
+        raw: includeRaw ? x : void 0
+      }));
+    }
+  }
+  let versions = null;
+  let versionsTotal = null;
+  if (includeVersions) {
+    const v = await client.post("/casement/project_version/get_project_version_list", {
+      projectId,
+      current: 1,
+      pageSize: versionPageSize
+    });
+    if (v.ok) {
+      const rows = Array.isArray(v.result?.data) ? v.result.data : [];
+      versionsTotal = Number(v.result?.total || rows.length);
+      versions = rows.map((x) => ({
+        id: x.id,
+        versionName: x.versionName,
+        currentPhase: x.currentPhase,
+        startTime: x.startTime,
+        endTime: x.endTime,
+        pic: x.pic,
+        publishWindowStatus: x.publishWindowStatus,
+        raw: includeRaw ? x : void 0
+      }));
+    }
+  }
+  const p = detail.result || {};
+  printResult({
+    ok: detail.ok,
+    code: detail.code,
+    msg: detail.msg,
+    projectId,
+    project: {
+      id: p.id,
+      projectName: p.projectName,
+      projectDesc: p.projectDesc,
+      groupId: p.groupId,
+      groupName: p.groupName,
+      projectStatus: p.projectStatus,
+      projectGrayStatus: p.projectGrayStatus,
+      jiraLibraryKey: p.jiraLibraryKey,
+      principal: p.principal,
+      createTime: p.createTime,
+      updateTime: p.updateTime,
+      relatedWiseskylarkProject: p.relatedWiseskylarkProject,
+      raw: includeRaw ? p : void 0
+    },
+    includeMembers,
+    membersTotal,
+    members,
+    includeVersions,
+    versionsTotal,
+    versions
+  }, options);
+}
+async function cmdProjectMembers(args, options) {
+  const client = ensureClientOrThrow();
+  const parsed = parseFlags(args);
+  const projectId = Number(getFlag(parsed.flags, "projectId") || parsed.positionals[0]);
+  if (!Number.isFinite(projectId) || projectId <= 0) {
+    printResult({ ok: false, error: "Missing or invalid projectId" }, options);
+    process.exit(1);
+  }
+  const page = toPositiveInt(getFlag(parsed.flags, "page") || parsed.positionals[1], 1);
+  const pageSize = toPositiveInt(getFlag(parsed.flags, "pageSize") || parsed.positionals[2], 50);
+  const keyword = (getFlag(parsed.flags, "keyword") || parsed.positionals[3] || "").toLowerCase();
+  const limit = toPositiveInt(getFlag(parsed.flags, "limit") || parsed.positionals[4], pageSize);
+  const includeRaw = toBool(parsed.flags.raw, false);
+  const resp = await client.post("/casement/project-member/list", {
+    projectId,
+    current: page,
+    pageSize
+  });
+  const result = resp.result || {};
+  let rows = Array.isArray(result.data) ? result.data : [];
+  if (keyword) {
+    rows = rows.filter((m) => [m.email, m.team].filter(Boolean).join(" ").toLowerCase().includes(keyword));
+  }
+  const members = rows.map((m) => ({
+    userId: m.userId,
+    projectId: m.projectId,
+    email: m.email,
+    team: m.team,
+    roleConstraints: m.roleConstraints,
+    roles: Array.isArray(m.roles) ? m.roles.map((r) => ({ roleId: r.roleId, roleName: r.roleName })) : [],
+    raw: includeRaw ? m : void 0
+  }));
+  printResult({
+    ok: resp.ok,
+    code: resp.code,
+    msg: resp.msg,
+    projectId,
+    page,
+    pageSize,
+    keyword: keyword || null,
+    total: result.total || members.length,
+    filteredTotal: members.length,
+    count: Math.min(members.length, limit),
+    members: members.slice(0, limit)
+  }, options);
+}
+async function cmdVersions(args, options) {
+  const client = ensureClientOrThrow();
+  const parsed = parseFlags(args);
+  const projectId = Number(getFlag(parsed.flags, "projectId") || parsed.positionals[0]);
+  if (!Number.isFinite(projectId) || projectId <= 0) {
+    printResult({ ok: false, error: "Missing or invalid projectId" }, options);
+    process.exit(1);
+  }
+  const page = toPositiveInt(getFlag(parsed.flags, "page") || parsed.positionals[1], 1);
+  const pageSize = toPositiveInt(getFlag(parsed.flags, "pageSize") || parsed.positionals[2], 20);
+  const keywordRaw = getFlag(parsed.flags, "keyword") || parsed.positionals[3] || "";
+  const keyword = keywordRaw.toLowerCase();
+  const limitOrOwnerPos = parsed.positionals[4] || "";
+  const ownerPos = parsed.positionals[5] || "";
+  const owner = (getFlag(parsed.flags, "owner") || ownerPos || (limitOrOwnerPos && !/^\d+$/.test(limitOrOwnerPos) ? limitOrOwnerPos : "")).toLowerCase();
+  const limit = toPositiveInt(getFlag(parsed.flags, "limit") || (/^\d+$/.test(limitOrOwnerPos) ? limitOrOwnerPos : ""), pageSize);
+  const filterAliases = {
+    undone: "undone",
+    not_done: "undone",
+    notdone: "undone",
+    active: "undone",
+    doing: "undone",
+    inprogress: "undone",
+    done: "done",
+    completed: "done",
+    complete: "done",
+    closed: "done"
+  };
+  const phaseFilter = filterAliases[keyword] || null;
+  const resp = await client.post("/casement/project_version/get_project_version_list", {
+    projectId,
+    current: page,
+    pageSize
+  });
+  const result = resp.result || {};
+  let rows = Array.isArray(result.data) ? result.data : [];
+  if (phaseFilter === "undone") rows = rows.filter((v) => Number(v.currentPhase) !== 99);
+  else if (phaseFilter === "done") rows = rows.filter((v) => Number(v.currentPhase) === 99);
+  else if (keyword) rows = rows.filter((v) => toText(v.versionName).toLowerCase().includes(keyword));
+  if (owner) rows = rows.filter((v) => toText(v.pic).toLowerCase().includes(owner));
+  const includeRaw = toBool(parsed.flags.raw, false);
+  const versions = rows.map((v) => {
+    const phase = normalizePhaseTimeline(v.versionPhase);
+    return {
+      id: v.id,
+      versionName: v.versionName,
+      projectId: v.projectId,
+      jiraVersionId: v.jiraVersionId,
+      currentPhase: v.currentPhase,
+      currentPhaseName: phaseNameFromCode(v.currentPhase),
+      isDone: Number(v.currentPhase) === 99,
+      status: {
+        currentPhase: v.currentPhase,
+        currentPhaseName: phaseNameFromCode(v.currentPhase),
+        isDone: Number(v.currentPhase) === 99,
+        publishWindowStatus: v.publishWindowStatus || null,
+        publishWindowName: v.publishWindowName || null
+      },
+      startTime: v.startTime,
+      endTime: v.endTime,
+      phaseTimeline: phase.timeline,
+      phaseTimelineMap: phase.map,
+      pic: v.pic,
+      publishWindowId: v.publishWindowId,
+      publishWindowStatus: v.publishWindowStatus,
+      publishWindowName: v.publishWindowName,
+      pfb: v.pfb,
+      raw: includeRaw ? v : void 0
+    };
+  });
+  printResult({
+    ok: resp.ok,
+    code: resp.code,
+    msg: resp.msg,
+    projectId,
+    page,
+    pageSize,
+    keyword: keyword || null,
+    phaseFilter,
+    owner: owner || null,
+    total: result.total || versions.length,
+    filteredTotal: versions.length,
+    count: Math.min(versions.length, limit),
+    versions: versions.slice(0, limit)
+  }, options);
+}
+function normalizeCheckpointRows(rows, detailLimit, includeRaw) {
+  const cap = Math.max(1, detailLimit);
+  return (Array.isArray(rows) ? rows : []).slice(0, cap).map((r) => ({
+    jiraKey: r.jiraKey || null,
+    issueType: r.issueType || r.type || null,
+    summary: r.summary || null,
+    reporter: r.reporter || null,
+    assignee: r.assignee || null,
+    status: r.status || null,
+    financialRisk: r.financialRisk || null,
+    nonComplianceContent: r.nonComplianceContent || r.rcSignoffMsg || r.message || null,
+    rcSignOff: r.rcSignOff || null,
+    message: r.message || null,
+    raw: includeRaw ? r : void 0
+  }));
+}
+function normalizeCheckpointDetails(item, detailLimit, includeRaw) {
+  const details = item && item.result && item.result.details && typeof item.result.details === "object" ? item.result.details : {};
+  return Object.entries(details).map(([key, val]) => {
+    const one = val && typeof val === "object" ? val : {};
+    const more = one.moreDetails && typeof one.moreDetails === "object" ? one.moreDetails : {};
+    const sourceRows = Array.isArray(more.dataSource) ? more.dataSource : [];
+    return {
+      key,
+      pass: one.pass,
+      actual: one.actual,
+      expect: one.expect,
+      message: one.message || null,
+      total: Number(more.total || sourceRows.length || 0),
+      rows: normalizeCheckpointRows(sourceRows, detailLimit, includeRaw),
+      hasMoreRows: sourceRows.length > detailLimit
+    };
+  });
+}
+async function cmdVersionDetail(args, options) {
+  const client = ensureClientOrThrow();
+  const parsed = parseFlags(args);
+  const versionId = Number(getFlag(parsed.flags, "versionId") || parsed.positionals[0]);
+  if (!Number.isFinite(versionId) || versionId <= 0) {
+    printResult({ ok: false, error: "Missing or invalid versionId" }, options);
+    process.exit(1);
+  }
+  const includeProject = toBool(getFlag(parsed.flags, "includeProject") || parsed.positionals[1], true);
+  const includeTasks = toBool(getFlag(parsed.flags, "includeTasks") || parsed.positionals[2], true);
+  const taskPage = toPositiveInt(getFlag(parsed.flags, "taskPage") || parsed.positionals[3], 1);
+  const taskPageSize = Math.min(200, toPositiveInt(getFlag(parsed.flags, "taskPageSize") || parsed.positionals[4], 50));
+  const includeCheckpoint = toBool(getFlag(parsed.flags, "includeCheckpoint") || parsed.positionals[5], true);
+  const checkpointStageArg = getFlag(parsed.flags, "checkpointStage") || parsed.positionals[6] || "";
+  const checkpointDetailLimit = Math.min(100, toPositiveInt(getFlag(parsed.flags, "checkpointDetailLimit") || parsed.positionals[7], 20));
+  const includeRaw = toBool(parsed.flags.raw, false);
+  const detailResp = await client.post("/casement/project_version/get_project_version_detail", { id: versionId });
+  if (!detailResp.ok) {
+    printResult({ ok: false, error: detailResp.msg || "Failed to fetch version detail", code: detailResp.code, httpStatus: detailResp.httpStatus }, options);
+    return;
+  }
+  const version = detailResp.result || {};
+  const phase = normalizePhaseTimeline(version.versionPhase);
+  let project = null;
+  if (includeProject && Number.isFinite(Number(version.projectId)) && Number(version.projectId) > 0) {
+    const p = await client.post("/casement/project/detail", { projectId: Number(version.projectId) });
+    if (p.ok) {
+      const one = p.result || {};
+      project = {
+        id: one.id,
+        projectName: one.projectName,
+        groupId: one.groupId,
+        groupName: one.groupName,
+        jiraLibraryKey: one.jiraLibraryKey,
+        principal: one.principal,
+        projectStatus: one.projectStatus,
+        raw: includeRaw ? one : void 0
+      };
+    }
+  }
+  let tasks = null;
+  if (includeTasks && Number.isFinite(Number(version.projectId)) && Number(version.projectId) > 0 && version.versionName) {
+    const taskPayload = {
+      projectId: Number(version.projectId),
+      fixVersions: String(version.versionName),
+      current: taskPage,
+      pageSize: taskPageSize
+    };
+    const taskResp = await client.post("/casement/jira-task/v2/default_list", taskPayload);
+    if (taskResp.ok) {
+      const taskResult = taskResp.result || {};
+      const rows = Array.isArray(taskResult.data) ? taskResult.data : [];
+      tasks = {
+        ok: true,
+        page: taskPage,
+        pageSize: taskPageSize,
+        total: Number(taskResult.total || 0),
+        count: rows.length,
+        list: rows.map((t) => ({
+          id: t.id,
+          jiraId: t.jiraId,
+          jiraKey: t.jiraKey,
+          summary: t.summary,
+          status: t.status,
+          currentPhase: t.currentPhase,
+          currentPhaseName: phaseNameFromCode(t.currentPhase),
+          priority: t.priority,
+          assignee: t.assignee,
+          developer: t.developer,
+          qa: t.qa,
+          reporter: t.reporter,
+          creator: t.creator,
+          fixVersions: t.fixVersions,
+          fixVersionId: t.fixVersionId,
+          requirementType: t.requirementType,
+          country: t.country,
+          business: t.business,
+          childrenCount: t.childrenCount,
+          createTime: t.createTime,
+          updateTime: t.updateTime,
+          resolvedDate: t.resolvedDate,
+          raw: includeRaw ? t : void 0
+        }))
+      };
+    } else {
+      tasks = {
+        ok: false,
+        page: taskPage,
+        pageSize: taskPageSize,
+        error: taskResp.msg || "Failed to fetch version tasks",
+        code: taskResp.code,
+        httpStatus: taskResp.httpStatus
+      };
+    }
+  }
+  let checkpoint = null;
+  if (includeCheckpoint && Number.isFinite(Number(version.projectId)) && Number(version.projectId) > 0 && Number.isFinite(Number(version.publishWindowId)) && Number(version.publishWindowId) > 0) {
+    const checkpointStage = checkpointStageArg || inferCheckpointStage(version.currentPhase);
+    if (checkpointStage) {
+      const checkpointPayload = {
+        appId: -1,
+        versionId: Number(version.id || versionId),
+        windowId: Number(version.publishWindowId),
+        projectId: Number(version.projectId),
+        sceneType: "VersionPhaseChange",
+        stage: checkpointStage
+      };
+      const cp = await client.post("/casement/workflow-scene-record/get_precheck_result", checkpointPayload);
+      if (cp.ok) {
+        const checkpointResult = cp.result || {};
+        const rows = Array.isArray(checkpointResult.cicdResults) ? checkpointResult.cicdResults : [];
+        const checks = rows.map((item) => {
+          const detailEntries = normalizeCheckpointDetails(item, checkpointDetailLimit, includeRaw);
+          const hasDetailIssue = detailEntries.some((d) => Number(d.total || 0) > 0 || !!d.message);
+          const hasIssue = Number(item.checkStatus) !== 1 || String(item.runStatus || "").toLowerCase() === "failure" || hasDetailIssue;
+          return {
+            category: item.category || null,
+            displayName: item.displayName || item.taskName || null,
+            taskName: item.taskName || null,
+            taskDesc: item.taskDesc || null,
+            runStatus: item.runStatus || null,
+            taskStatus: item.taskStatus || null,
+            checkStatus: item.checkStatus,
+            checkStatusName: checkStatusName(item.checkStatus),
+            skippable: item.skippable,
+            operator: item.operator || null,
+            updateTime: item.updateTime || null,
+            hasIssue,
+            details: detailEntries,
+            raw: includeRaw ? item : void 0
+          };
+        });
+        const financialRiskChecks = checks.filter((c) => c.category === "FinancialRisk");
+        const financialRiskIssues = financialRiskChecks.filter((c) => c.hasIssue);
+        const allIssues = checks.filter((c) => c.hasIssue);
+        checkpoint = {
+          ok: true,
+          sceneType: "VersionPhaseChange",
+          stage: checkpointStage,
+          isPass: !!checkpointResult.isPass,
+          existing: !!checkpointResult.existing,
+          totalChecks: checks.length,
+          issueCount: allIssues.length,
+          checks,
+          issues: allIssues,
+          financialRisk: {
+            totalChecks: financialRiskChecks.length,
+            issueCount: financialRiskIssues.length,
+            issues: financialRiskIssues
+          }
+        };
+      } else {
+        checkpoint = {
+          ok: false,
+          stage: checkpointStage,
+          error: cp.msg || "Failed to fetch checkpoint result",
+          code: cp.code,
+          httpStatus: cp.httpStatus
+        };
+      }
+    }
+  }
+  printResult({
+    ok: detailResp.ok,
+    code: detailResp.code,
+    msg: detailResp.msg,
+    versionId,
+    version: {
+      id: version.id,
+      versionName: version.versionName,
+      projectId: version.projectId,
+      jiraVersionId: version.jiraVersionId,
+      currentPhase: version.currentPhase,
+      currentPhaseName: phaseNameFromCode(version.currentPhase),
+      isDone: Number(version.currentPhase) === 99,
+      status: {
+        currentPhase: version.currentPhase,
+        currentPhaseName: phaseNameFromCode(version.currentPhase),
+        isDone: Number(version.currentPhase) === 99,
+        publishWindowStatus: version.publishWindowStatus || null,
+        publishWindowName: version.publishWindowName || null
+      },
+      startTime: version.startTime,
+      endTime: version.endTime,
+      phaseTimeline: phase.timeline,
+      phaseTimelineMap: phase.map,
+      pic: version.pic,
+      publishWindowId: version.publishWindowId,
+      publishWindowStatus: version.publishWindowStatus,
+      publishWindowName: version.publishWindowName,
+      raw: includeRaw ? version : void 0
+    },
+    includeProject,
+    includeTasks,
+    includeCheckpoint,
+    taskPage,
+    taskPageSize,
+    checkpointDetailLimit,
+    tasks,
+    checkpoint,
+    project
+  }, options);
+}
+async function cmdTasks(args, options) {
+  const client = ensureClientOrThrow();
+  const parsed = parseFlags(args);
+  const type = getFlag(parsed.flags, "type") || parsed.positionals[0] || "assignToMe";
+  const email = getFlag(parsed.flags, "email") || parsed.positionals[1] || "";
+  const page = toPositiveInt(getFlag(parsed.flags, "page") || parsed.positionals[2], 1);
+  const pageSize = toPositiveInt(getFlag(parsed.flags, "pageSize") || parsed.positionals[3], 20);
+  const payload = { type, current: page, pageSize };
+  if (email) payload.email = email;
+  const resp = await client.post("/casement/workspace/task_list", payload);
+  const result = resp.result || {};
+  const rows = Array.isArray(result.data) ? result.data : Array.isArray(result.list) ? result.list : [];
+  const tasks = rows.map((t) => ({
+    jiraKey: t.jiraKey || t.jira_key || t.key,
+    summary: t.summary || t.title,
+    status: t.status || t.taskStatus,
+    fixVersions: t.fixVersions || t.fixVersion || [],
+    projectName: t.projectName,
+    raw: t
+  }));
+  printResult({
+    ok: resp.ok,
+    code: resp.code,
+    msg: resp.msg,
+    page,
+    pageSize,
+    type,
+    total: result.total || tasks.length,
+    count: tasks.length,
+    tasks
+  }, options);
+}
+async function cmdSubtasks(args, options) {
+  const client = ensureClientOrThrow();
+  const parsed = parseFlags(args);
+  const typeInput = getFlag(parsed.flags, "type") || parsed.positionals[0] || "undone";
+  const typeMap = {
+    thisWeek: "weekly_done",
+    week: "weekly_done",
+    lastWeek: "lastWeek_done",
+    nextWeek: "nextWeek_done",
+    overdue: "past_due",
+    mine: "createdByMe"
+  };
+  const type = typeMap[typeInput] || typeInput;
+  const email = getFlag(parsed.flags, "email") || parsed.positionals[1] || "";
+  const page = toPositiveInt(getFlag(parsed.flags, "page") || parsed.positionals[2], 1);
+  const pageSize = toPositiveInt(getFlag(parsed.flags, "pageSize") || parsed.positionals[3], 20);
+  const payload = { type, current: page, pageSize };
+  if (email) payload.email = email;
+  const resp = await client.post("/casement/workspace/subTask_list", payload);
+  const result = resp.result || {};
+  const rows = Array.isArray(result.data) ? result.data : Array.isArray(result.list) ? result.list : [];
+  const subtasks = rows.map((t) => ({
+    jiraSubtask: t.jiraSubtask || t.jiraKey || t.jira_key || t.key,
+    parentJiraKey: t.parentJiraKey || t.parentJiraTask || t.jiraTask,
+    summary: t.summary || t.title,
+    dueDate: t.dueDate || t.planFinishTime,
+    storyPoints: t.storyPoints,
+    status: t.status || t.taskStatus,
+    stage: t.stage || t.jiraSubtaskStage,
+    fixVersions: t.parentFixVersions || t.fixVersions || [],
+    raw: t
+  }));
+  printResult({
+    ok: resp.ok,
+    code: resp.code,
+    msg: resp.msg,
+    page,
+    pageSize,
+    type,
+    total: result.total || subtasks.length,
+    count: subtasks.length,
+    subtasks
+  }, options);
+}
+async function cmdCreateSubtask(args, options) {
+  const client = ensureClientOrThrow();
+  const parsed = parseFlags(args);
+  const parentJiraKey = getFlag(parsed.flags, "parentJiraKey") || parsed.positionals[0];
+  if (!parentJiraKey) {
+    printResult({ ok: false, error: "Missing argument: parentJiraKey" }, options);
+    process.exit(1);
+  }
+  const summaryOrJson = parsed.positionals[1] || "";
+  const requirementTypePos = parsed.positionals[2] || "";
+  const payloadRaw = getFlag(parsed.flags, "payload") || (summaryOrJson.startsWith("{") ? summaryOrJson : "");
+  let body = { parentJiraKey };
+  if (payloadRaw) {
+    const parsedPayload = safeJsonParse(payloadRaw);
+    if (!parsedPayload) {
+      printResult({ ok: false, error: "Invalid payload JSON" }, options);
+      process.exit(1);
+    }
+    body = { ...parsedPayload, parentJiraKey };
+  } else {
+    const summary = getFlag(parsed.flags, "summary") || (summaryOrJson && !summaryOrJson.startsWith("{") ? summaryOrJson : "");
+    const assignee = getFlag(parsed.flags, "assignee");
+    const phase = getFlag(parsed.flags, "phase", "stage");
+    const priority = getFlag(parsed.flags, "priority");
+    const storyPoints = getFlag(parsed.flags, "storyPoints", "story_points");
+    const startDate = getFlag(parsed.flags, "startDate", "start_date");
+    const dueDate = getFlag(parsed.flags, "dueDate", "due_date");
+    const description = getFlag(parsed.flags, "description");
+    const requirementType = getFlag(parsed.flags, "requirementType", "subtaskType", "jiraSubtaskType") || requirementTypePos;
+    if (summary) body.summary = summary;
+    if (assignee) body.assignee = normalizeAssignee(assignee);
+    if (phase) body.phase = phase;
+    if (priority) body.priority = normalizePriority(priority);
+    if (storyPoints && Number.isFinite(Number(storyPoints))) body.storyPoints = Number(storyPoints);
+    if (startDate) body.startDate = startDate;
+    if (dueDate) body.dueDate = dueDate;
+    if (description) body.description = description;
+    if (requirementType) body.requirementType = normalizeRequirementType(requirementType);
+  }
+  const send = async (oneBody) => {
+    const resp = await client.post("/casement/jira-subtask/add-v2", oneBody);
+    const result2 = resp.result || {};
+    return {
+      ok: resp.ok,
+      code: resp.code,
+      msg: resp.msg,
+      httpStatus: resp.httpStatus,
+      result: result2,
+      jiraSubtask: result2.jiraSubtask || result2.jiraKey || result2.key || null
+    };
+  };
+  let finalBody = { ...body };
+  let result = await send(finalBody);
+  let fallback = { assigneeTried: false, assigneeUsed: null };
+  if (!result.ok && /User\s+'.+'\s+does not exist/i.test(toText(result.msg))) {
+    const assignee = toText(finalBody.assignee);
+    if (assignee && !assignee.includes("@")) {
+      const candidates = buildAssigneeFallbackCandidates(body.assignee, assignee);
+      for (const candidate of candidates) {
+        fallback.assigneeTried = true;
+        const retryBody = { ...finalBody, assignee: candidate };
+        const retry = await send(retryBody);
+        if (retry.ok || !/User\s+'.+'\s+does not exist/i.test(toText(retry.msg))) {
+          finalBody = retryBody;
+          result = retry;
+          fallback.assigneeUsed = candidate;
+          break;
+        }
+      }
+    }
+  }
+  printResult({
+    ok: result.ok,
+    code: result.code,
+    msg: result.msg,
+    httpStatus: result.httpStatus,
+    parentJiraKey,
+    jiraSubtask: result.jiraSubtask,
+    result: result.result,
+    requestBody: finalBody,
+    fallback
+  }, options);
+}
+async function cmdUpdateStatus(args, options) {
+  const client = ensureClientOrThrow();
+  const parsed = parseFlags(args);
+  const jiraKey = getFlag(parsed.flags, "jiraKey") || parsed.positionals[0];
+  const statusRaw = getFlag(parsed.flags, "status") || parsed.positionals[1];
+  if (!jiraKey) {
+    printResult({ ok: false, error: "Missing argument: jiraKey" }, options);
+    process.exit(1);
+  }
+  if (!statusRaw) {
+    printResult({ ok: false, error: "Missing argument: status" }, options);
+    process.exit(1);
+  }
+  const statusMap = {
+    "to do": "TO DO",
+    todo: "TO DO",
+    doing: "Doing",
+    done: "Done",
+    closed: "Closed"
+  };
+  const normalized = statusRaw.toLowerCase();
+  const statusId = statusMap[normalized];
+  if (!statusId) {
+    printResult({ ok: false, error: `Invalid status: ${statusRaw}`, hint: "Use one of: To Do, Doing, Done, Closed" }, options);
+    process.exit(1);
+  }
+  async function setStatus(nextStatusName) {
+    return client.post("/casement/jira-subtask/update_field", {
+      jiraKey,
+      field: "status",
+      value: nextStatusName
+    });
+  }
+  const first = await setStatus(statusId);
+  if (!first.ok && normalized === "done") {
+    const stepDoing = await setStatus(statusMap.doing);
+    const stepDone = stepDoing.ok ? await setStatus(statusId) : null;
+    printResult({
+      ok: !!(stepDone && stepDone.ok),
+      code: stepDone ? stepDone.code : first.code,
+      msg: stepDone ? stepDone.msg : first.msg,
+      jiraKey,
+      status: statusRaw,
+      statusId,
+      autoTransition: true,
+      transitions: [
+        { status: "Doing", statusId: statusMap.doing, ok: stepDoing.ok, code: stepDoing.code, msg: stepDoing.msg, httpStatus: stepDoing.httpStatus },
+        { status: "Done", statusId, ok: stepDone ? stepDone.ok : false, code: stepDone ? stepDone.code : null, msg: stepDone ? stepDone.msg : "Skip because Doing failed" }
+      ],
+      result: stepDone ? stepDone.result : first.result
+    }, options);
+    return;
+  }
+  printResult({
+    ok: first.ok,
+    code: first.code,
+    msg: first.msg,
+    jiraKey,
+    status: statusRaw,
+    statusId,
+    httpStatus: first.httpStatus,
+    result: first.result
+  }, options);
+}
+async function cmdUpdateSubtask(args, options) {
+  const client = ensureClientOrThrow();
+  const parsed = parseFlags(args);
+  const jiraKey = getFlag(parsed.flags, "jiraKey") || parsed.positionals[0];
+  if (!jiraKey) {
+    printResult({ ok: false, error: "Missing argument: jiraKey" }, options);
+    process.exit(1);
+  }
+  const secondPos = parsed.positionals[1] || "";
+  const thirdPos = parsed.positionals[2] || "";
+  const payloadRaw = getFlag(parsed.flags, "payload") || (secondPos.startsWith("{") ? secondPos : "");
+  const updates = [];
+  const payloadObj = payloadRaw ? safeJsonParse(payloadRaw) : null;
+  if (payloadObj && typeof payloadObj === "object") {
+    for (const [k, v] of Object.entries(payloadObj)) {
+      if (v === void 0 || v === null || toText(v) === "") continue;
+      updates.push({ field: k, value: v, source: "payload" });
+    }
+  }
+  if (updates.length === 0) {
+    const field = getFlag(parsed.flags, "field") || secondPos;
+    const value = getFlag(parsed.flags, "value") || thirdPos;
+    if (field && value !== "") {
+      updates.push({ field, value, source: "single" });
+    }
+  }
+  if (updates.length === 0) {
+    const directFields = ["summary", "storyPoints", "priority", "assignee", "phase", "startDate", "dueDate", "description", "requirementType"];
+    for (const key of directFields) {
+      const val = getFlag(parsed.flags, key);
+      if (val !== "") updates.push({ field: key, value: val, source: "direct" });
+    }
+  }
+  if (updates.length === 0) {
+    printResult({ ok: false, error: "No fields to update", hint: "Use <jiraKey> <field> <value> OR JSON payload" }, options);
+    process.exit(1);
+  }
+  const results = [];
+  for (const item of updates) {
+    const canonicalField = normalizeFieldName(item.field);
+    let value = item.value;
+    if (canonicalField === "priority") value = normalizePriority(item.value);
+    else if (canonicalField === "assignee") value = normalizeAssignee(item.value);
+    else if (canonicalField === "requirementType") value = normalizeRequirementType(item.value);
+    else value = toText(item.value);
+    const send = async (v) => client.post("/casement/jira-subtask/update_field", {
+      jiraKey,
+      field: canonicalField,
+      value: v
+    });
+    let response = await send(value);
+    let fallback = { tried: false, used: null };
+    if (canonicalField === "assignee" && !response.ok && /User\s+'.+'\s+does not exist/i.test(toText(response.msg))) {
+      const candidates = buildAssigneeFallbackCandidates(item.value, value);
+      for (const candidate of candidates) {
+        fallback.tried = true;
+        const retry = await send(candidate);
+        if (retry.ok || !/User\s+'.+'\s+does not exist/i.test(toText(retry.msg))) {
+          response = retry;
+          fallback.used = candidate;
+          value = candidate;
+          break;
+        }
+      }
+    }
+    results.push({
+      field: canonicalField,
+      inputField: item.field,
+      inputValue: item.value,
+      value,
+      source: item.source,
+      ok: response.ok,
+      code: response.code,
+      msg: response.msg,
+      httpStatus: response.httpStatus,
+      fallback,
+      result: response.result
+    });
+  }
+  const successCount = results.filter((x) => x.ok).length;
+  printResult({
+    ok: successCount === results.length,
+    jiraKey,
+    total: results.length,
+    successCount,
+    failCount: results.length - successCount,
+    updates: results
+  }, options);
+}
+function inferArgType(name, description) {
+  const n = name.toLowerCase();
+  const d = description.toLowerCase();
+  if (n.includes("include") || d.includes("true/false") || d.includes("\u662F\u5426")) return "boolean";
+  if (n.includes("stage")) return "string";
+  const rawName = toText(name);
+  const isNumberName = /Id$/.test(rawName) || /Page$/.test(rawName) || /PageSize$/.test(rawName) || /Limit$/.test(rawName) || /^storyPoints?$/i.test(rawName);
+  if (isNumberName) return "number";
+  return "string";
+}
+function extractDefaultValue(description) {
+  const text = toText(description);
+  if (!text) return null;
+  const m = text.match(/默认\s*([^\s，,）)]+)/);
+  return m ? m[1] : null;
+}
+function tokenizePositionalUsage(positionalUsage, args) {
+  const tokens = positionalUsage.match(/<[^>]+>|\[[^\]]+\]/g) || [];
+  return tokens.map((raw, idx) => {
+    const required = raw.startsWith("<");
+    const body = raw.slice(1, -1).trim();
+    const enumValues = body.includes("|") ? body.split("|").map((x) => x.trim()).filter(Boolean) : [];
+    const name = enumValues[0] || body;
+    const description = args[name] || null;
+    const inferredType = inferArgType(name, description || "");
+    return {
+      index: idx,
+      raw,
+      name,
+      required,
+      inferredType,
+      enumValues,
+      default: extractDefaultValue(description || ""),
+      description
+    };
+  });
+}
+function buildAgentCommandContract(name, cmd) {
+  const positionalArgs = tokenizePositionalUsage(cmd.positionalUsage, cmd.args);
+  const positionalArgNames = new Set(positionalArgs.map((x) => x.name));
+  const namedArgs = Object.entries(cmd.args).filter(([k]) => !positionalArgNames.has(k)).map(([k, v]) => ({
+    name: k,
+    description: v,
+    inferredType: inferArgType(k, v),
+    default: extractDefaultValue(v)
+  }));
+  return {
+    command: name,
+    readOnly: cmd.readOnly,
+    positionalArgs,
+    namedArgs,
+    parseRules: [
+      "\u4F18\u5148\u6309 positionalUsage \u7684\u987A\u5E8F\u4F20\u4F4D\u7F6E\u53C2\u6570\u3002",
+      "\u590D\u6742\u5185\u5BB9\u4F18\u5148\u4F20 JSON \u5B57\u7B26\u4E32\uFF0C\u907F\u514D shell \u89E3\u6790\u6B67\u4E49\u3002",
+      "\u672A\u63D0\u4F9B\u53EF\u9009\u53C2\u6570\u65F6\uFF0C\u6309\u547D\u4EE4\u5185\u90E8\u9ED8\u8BA4\u503C\u6267\u884C\u3002"
+    ],
+    successSignal: cmd.readOnly ? "\u8FD4\u56DE ok=true \u4E14\u5305\u542B\u5217\u8868/\u8BE6\u60C5\u5B57\u6BB5" : "\u8FD4\u56DE ok=true\uFF0C\u4E14 successCount==total\uFF08\u6279\u91CF\u66F4\u65B0\u573A\u666F\uFF09",
+    examples: cmd.examples
+  };
+}
+var HELP_COMMANDS = {
+  projects: {
+    title: "casement projects",
+    purpose: "\u67E5\u8BE2\u9879\u76EE\u5217\u8868",
+    positionalUsage: "casement projects [keyword] [limit]",
+    readOnly: true,
+    args: {
+      keyword: "\u9879\u76EE\u5173\u952E\u5B57\uFF08projectName/jiraLibraryKey/principal/groupName\uFF09",
+      limit: "\u6700\u591A\u8FD4\u56DE\u6761\u6570\uFF0C\u9ED8\u8BA4 50",
+      projectStatus: "\u9879\u76EE\u72B6\u6001\uFF08\u9ED8\u8BA4 1\uFF09",
+      groupId: "\u6309 groupId \u8FC7\u6EE4\uFF08\u53EF\u9009\uFF09"
+    },
+    examples: ["casement projects credit 20"]
+  },
+  "project-detail": {
+    title: "casement project-detail",
+    purpose: "\u67E5\u8BE2\u9879\u76EE\u8BE6\u60C5",
+    positionalUsage: "casement project-detail <projectId> [includeMembers] [includeVersions]",
+    readOnly: true,
+    args: {
+      projectId: "\u9879\u76EE ID\uFF08\u5FC5\u586B\uFF09",
+      includeMembers: "true/false\uFF0C\u662F\u5426\u5E26\u6210\u5458",
+      includeVersions: "true/false\uFF0C\u662F\u5426\u5E26\u7248\u672C\u6458\u8981",
+      memberPageSize: "\u6210\u5458\u5206\u9875\u5927\u5C0F\uFF0C\u9ED8\u8BA4 50",
+      versionPageSize: "\u7248\u672C\u5206\u9875\u5927\u5C0F\uFF0C\u9ED8\u8BA4 20"
+    },
+    examples: ["casement project-detail 6 true true"]
+  },
+  versions: {
+    title: "casement versions",
+    purpose: "\u67E5\u8BE2\u9879\u76EE\u7248\u672C",
+    positionalUsage: "casement versions <projectId> [page] [pageSize] [keyword|undone|done] [limit|owner] [owner]",
+    readOnly: true,
+    args: {
+      projectId: "\u9879\u76EE ID\uFF08\u5FC5\u586B\uFF09",
+      page: "\u9875\u7801\uFF0C\u9ED8\u8BA4 1",
+      pageSize: "\u6BCF\u9875\u6570\u91CF\uFF0C\u9ED8\u8BA4 20",
+      keyword: "\u7248\u672C\u5173\u952E\u5B57\uFF1B\u6216\u4F20 undone/done",
+      owner: "\u6309\u8D1F\u8D23\u4EBA\u8FC7\u6EE4\uFF08\u90AE\u7BB1\u6216\u524D\u7F00\uFF09",
+      limit: "\u6700\u591A\u8FD4\u56DE\u6761\u6570"
+    },
+    examples: ["casement versions 6 1 100 undone", "casement versions 6 1 100 undone shipeng.chen"]
+  },
+  "version-detail": {
+    title: "casement version-detail",
+    purpose: "\u67E5\u8BE2\u7248\u672C\u8BE6\u60C5\uFF08\u53EF\u5E26 tasks/checkpoint\uFF09",
+    positionalUsage: "casement version-detail <versionId> [includeProject] [includeTasks] [taskPage] [taskPageSize] [includeCheckpoint] [checkpointStage] [checkpointDetailLimit]",
+    readOnly: true,
+    args: {
+      versionId: "\u7248\u672C ID\uFF08\u5FC5\u586B\uFF09",
+      includeProject: "\u662F\u5426\u9644\u5E26\u9879\u76EE\u4FE1\u606F\uFF0C\u9ED8\u8BA4 true",
+      includeTasks: "\u662F\u5426\u9644\u5E26\u7248\u672C\u4EFB\u52A1\uFF0C\u9ED8\u8BA4 true",
+      taskPageSize: "\u4EFB\u52A1\u5206\u9875\u5927\u5C0F\uFF0C\u9ED8\u8BA4 50",
+      includeCheckpoint: "\u662F\u5426\u9644\u5E26 checkpoint\uFF0C\u9ED8\u8BA4 true",
+      checkpointStage: "\u624B\u52A8\u6307\u5B9A stage\uFF08\u5982 DevToTest\uFF09"
+    },
+    examples: ["casement version-detail 9099", "casement version-detail 9179 true true 1 50 true DevToTest 50"]
+  },
+  "project-members": {
+    title: "casement project-members",
+    purpose: "\u67E5\u8BE2\u9879\u76EE\u6210\u5458",
+    positionalUsage: "casement project-members <projectId> [page] [pageSize] [keyword] [limit]",
+    readOnly: true,
+    args: {
+      projectId: "\u9879\u76EE ID\uFF08\u5FC5\u586B\uFF09",
+      page: "\u9875\u7801\uFF0C\u9ED8\u8BA4 1",
+      pageSize: "\u6BCF\u9875\u6570\u91CF\uFF0C\u9ED8\u8BA4 50",
+      keyword: "\u6309\u90AE\u7BB1/team \u8FC7\u6EE4",
+      limit: "\u6700\u591A\u8FD4\u56DE\u6761\u6570"
+    },
+    examples: ["casement project-members 6 1 100"]
+  },
+  tasks: {
+    title: "casement tasks",
+    purpose: "\u67E5\u8BE2 workspace my task",
+    positionalUsage: "casement tasks [type] [email] [page] [pageSize]",
+    readOnly: true,
+    args: {
+      type: "assignToMe | creatorByMe | relatedToMe",
+      email: "\u76EE\u6807\u90AE\u7BB1\uFF08\u9ED8\u8BA4\u5F53\u524D\u767B\u5F55\u7528\u6237\uFF09",
+      page: "\u9875\u7801\uFF0C\u9ED8\u8BA4 1",
+      pageSize: "\u6BCF\u9875\u6570\u91CF\uFF0C\u9ED8\u8BA4 20"
+    },
+    examples: ["casement tasks assignToMe"]
+  },
+  subtasks: {
+    title: "casement subtasks",
+    purpose: "\u67E5\u8BE2 workspace my subtask",
+    positionalUsage: "casement subtasks [type] [email] [page] [pageSize]",
+    readOnly: true,
+    args: {
+      type: "undone/weekly_done/lastWeek_done/nextWeek_done/past_due/all/createdByMe",
+      email: "\u76EE\u6807\u90AE\u7BB1\uFF08\u9ED8\u8BA4\u5F53\u524D\u767B\u5F55\u7528\u6237\uFF09",
+      page: "\u9875\u7801\uFF0C\u9ED8\u8BA4 1",
+      pageSize: "\u6BCF\u9875\u6570\u91CF\uFF0C\u9ED8\u8BA4 20"
+    },
+    examples: ["casement subtasks undone"]
+  },
+  "create-subtask": {
+    title: "casement create-subtask",
+    purpose: "\u521B\u5EFA subtask",
+    positionalUsage: "casement create-subtask <parentJiraKey> [summary-or-json]",
+    readOnly: false,
+    args: {
+      parentJiraKey: "\u7236\u4EFB\u52A1 key\uFF08\u5FC5\u586B\uFF09",
+      summary: "\u6807\u9898",
+      assignee: "\u6307\u6D3E\u4EBA\uFF08\u90AE\u7BB1\u4F1A\u81EA\u52A8\u8F6C\u77ED\u540D\uFF09",
+      phase: "\u9636\u6BB5\uFF08Dev/Test/UAT/Live\uFF09",
+      priority: "Highest/High/Medium/Low/Lowest\uFF08\u652F\u6301 P0~P4\uFF09",
+      storyPoints: "\u6545\u4E8B\u70B9",
+      startDate: "\u5F00\u59CB\u65E5\u671F YYYY-MM-DD",
+      dueDate: "\u622A\u6B62\u65E5\u671F YYYY-MM-DD",
+      requirementType: "\u5B50\u4EFB\u52A1\u7C7B\u578B",
+      description: "\u63CF\u8FF0",
+      payload: "\u539F\u59CB JSON"
+    },
+    notes: ["\u63A8\u8350\u7B2C 2 \u4E2A\u4F4D\u7F6E\u53C2\u6570\u76F4\u63A5\u4F20 JSON"],
+    examples: [
+      `casement create-subtask SPSK-245038 '{"summary":"[BE] demo","assignee":"shipeng.chen","priority":"High"}'`
+    ]
+  },
+  "update-status": {
+    title: "casement update-status",
+    purpose: "\u66F4\u65B0 subtask \u72B6\u6001",
+    positionalUsage: "casement update-status <jiraKey> <status>",
+    readOnly: false,
+    args: {
+      jiraKey: "\u5B50\u4EFB\u52A1 key\uFF08\u5FC5\u586B\uFF09",
+      status: "To Do | Doing | Done | Closed"
+    },
+    examples: ["casement update-status SPSK-273098 Doing"]
+  },
+  "update-subtask": {
+    title: "casement update-subtask",
+    purpose: "\u66F4\u65B0 subtask \u5B57\u6BB5\uFF08summary/storyPoints/priority/assignee...\uFF09",
+    positionalUsage: "casement update-subtask <jiraKey> <field|json> [value]",
+    readOnly: false,
+    args: {
+      jiraKey: "\u5B50\u4EFB\u52A1 key\uFF08\u5FC5\u586B\uFF09",
+      field: "\u5B57\u6BB5\u540D",
+      value: "\u5B57\u6BB5\u503C",
+      payload: "\u6279\u91CF JSON",
+      summary: "\u76F4\u63A5\u66F4\u65B0 summary",
+      storyPoints: "\u76F4\u63A5\u66F4\u65B0 storyPoints",
+      priority: "\u76F4\u63A5\u66F4\u65B0 priority\uFF08\u652F\u6301 P0~P4\uFF09",
+      assignee: "\u76F4\u63A5\u66F4\u65B0 assignee\uFF08\u652F\u6301\u90AE\u7BB1/\u7528\u6237\u540D\uFF09",
+      phase: "\u76F4\u63A5\u66F4\u65B0 phase",
+      startDate: "\u76F4\u63A5\u66F4\u65B0 startDate",
+      dueDate: "\u76F4\u63A5\u66F4\u65B0 dueDate",
+      description: "\u76F4\u63A5\u66F4\u65B0 description",
+      requirementType: "\u76F4\u63A5\u66F4\u65B0 requirementType"
+    },
+    examples: [
+      "casement update-subtask SPSK-273096 summary '[BE] new title'",
+      "casement update-subtask SPSK-273096 storyPoints 2.5",
+      `casement update-subtask SPSK-273096 '{"summary":"new","storyPoints":2.5,"priority":"High"}'`
+    ]
+  },
+  auth: {
+    title: "casement auth",
+    purpose: "\u767B\u5F55\u4F1A\u8BDD\u7BA1\u7406",
+    positionalUsage: "casement auth <login|status|logout>",
+    readOnly: false,
+    args: {
+      login: "\u4FDD\u5B58 token/cookie \u5230\u672C\u5730\u4F1A\u8BDD",
+      status: "\u68C0\u67E5\u4F1A\u8BDD\u53EF\u7528\u6027",
+      logout: "\u6E05\u9664\u672C\u5730\u4F1A\u8BDD",
+      token: "CASEMENT_LOGIN_TOKEN",
+      cookie: "\u6D4F\u89C8\u5668 Cookie \u5B57\u7B26\u4E32",
+      from: "\u4ECE JSON \u6587\u4EF6\u5BFC\u5165 token/cookie",
+      mode: "\u767B\u5F55\u6A21\u5F0F\uFF1Aauto(\u9ED8\u8BA4) | manual",
+      auto: "\u662F\u5426\u542F\u7528\u81EA\u52A8\u6D4F\u89C8\u5668\u91C7\u96C6\uFF08\u9ED8\u8BA4 true\uFF09",
+      browser: "Playwright \u6D4F\u89C8\u5668\u901A\u9053\uFF08\u9ED8\u8BA4 chrome\uFF09",
+      timeout: "\u81EA\u52A8\u91C7\u96C6\u8D85\u65F6\u79D2\u6570\uFF08\u9ED8\u8BA4 300\uFF09",
+      open: "\u662F\u5426\u81EA\u52A8\u6253\u5F00\u767B\u5F55\u9875\uFF08\u9ED8\u8BA4 true\uFF09"
+    },
+    examples: [
+      "casement auth login",
+      "casement auth login --mode manual",
+      "casement auth login --token <TOKEN> --cookie 'a=b; c=d'",
+      "casement auth status",
+      "casement auth logout"
+    ]
+  }
+};
+function showHelp(target, options) {
+  const order = [
+    "auth",
+    "projects",
+    "project-detail",
+    "versions",
+    "version-detail",
+    "project-members",
+    "tasks",
+    "subtasks",
+    "create-subtask",
+    "update-subtask",
+    "update-status"
+  ];
+  if (target) {
+    const cmd = HELP_COMMANDS[target];
+    if (!cmd) {
+      printResult({ ok: false, error: `Unknown command: ${target}`, availableCommands: order }, options);
+      return;
+    }
+    printResult({
+      project: "casement-lite",
+      command: target,
+      detail: cmd,
+      agentContract: buildAgentCommandContract(target, cmd),
+      usageGuide: [
+        "\u63A8\u8350\u4F18\u5148\u7528\u4F4D\u7F6E\u53C2\u6570\uFF1B\u590D\u6742\u66F4\u65B0\u5EFA\u8BAE\u4F20 JSON\u3002",
+        "\u5148\u6267\u884C `casement auth login` \u5EFA\u7ACB\u4F1A\u8BDD\u3002",
+        "`auth login` \u9ED8\u8BA4\u81EA\u52A8\u62C9\u8D77\u53D7\u63A7\u6D4F\u89C8\u5668\u5E76\u91C7\u96C6 token/cookie\uFF1B\u53EF\u7528 `--mode manual` \u6539\u4E3A\u624B\u52A8\u8F93\u5165\u3002"
+      ]
+    }, options);
+    return;
+  }
+  printResult({
+    project: "casement-lite",
+    description: "Casement \u8F7B\u91CF CLI\uFF08\u76F4\u63A5\u901A\u8FC7\u63A5\u53E3\u8C03\u7528\uFF09",
+    helpFormat: "agent-friendly-json-v1",
+    sessionFile: SESSION_FILE,
+    availableCommands: order,
+    commands: order.map((k) => ({
+      name: k,
+      title: HELP_COMMANDS[k].title,
+      purpose: HELP_COMMANDS[k].purpose,
+      readOnly: HELP_COMMANDS[k].readOnly,
+      positionalUsage: HELP_COMMANDS[k].positionalUsage,
+      positionalSpec: tokenizePositionalUsage(HELP_COMMANDS[k].positionalUsage, HELP_COMMANDS[k].args),
+      examples: HELP_COMMANDS[k].examples
+    })),
+    agentGuide: {
+      recommendedFlow: [
+        "1) \u5148\u6267\u884C `casement auth login` \u5EFA\u7ACB\u4F1A\u8BDD",
+        "2) \u5148\u67E5\u8BE2 projects \u62FF\u5230 projectId",
+        "3) \u518D\u67E5\u8BE2 versions/version-detail",
+        "4) \u9700\u8981\u4FEE\u6539\u65F6\u518D\u6267\u884C create-subtask/update-*"
+      ],
+      readOnlyCommands: order.filter((k) => HELP_COMMANDS[k].readOnly),
+      writeCommands: order.filter((k) => !HELP_COMMANDS[k].readOnly),
+      commandContracts: order.reduce((acc, k) => {
+        acc[k] = buildAgentCommandContract(k, HELP_COMMANDS[k]);
+        return acc;
+      }, {})
+    },
+    quickStart: [
+      "casement auth login",
+      "casement projects credit 10",
+      "casement versions 6 1 100 undone",
+      "casement version-detail 9099"
+    ]
+  }, options);
+}
+async function runCommand(command, args, options) {
+  const cmd = command ? command.replace(/^casement\//, "") : command;
+  const rest = args;
+  if (!cmd || cmd === "help" || cmd === "-h" || cmd === "--help") {
+    showHelp(rest[0] || null, options);
+    return;
+  }
+  if (cmd === "auth") {
+    const sub = rest[0] || "";
+    const subArgs = rest.slice(1);
+    if (!sub || sub === "help") {
+      showHelp("auth", options);
+      return;
+    }
+    if (sub === "login") return authLogin(subArgs, options);
+    if (sub === "status") return authStatus(options);
+    if (sub === "logout") return authLogout(options);
+    printResult({ ok: false, error: `Unknown auth subcommand: ${sub}`, available: ["login", "status", "logout"] }, options);
+    process.exit(1);
+  }
+  if (cmd === "projects") return cmdProjects(rest, options);
+  if (cmd === "project-detail") return cmdProjectDetail(rest, options);
+  if (cmd === "project-members") return cmdProjectMembers(rest, options);
+  if (cmd === "versions") return cmdVersions(rest, options);
+  if (cmd === "version-detail") return cmdVersionDetail(rest, options);
+  if (cmd === "tasks") return cmdTasks(rest, options);
+  if (cmd === "subtasks") return cmdSubtasks(rest, options);
+  if (cmd === "create-subtask") return cmdCreateSubtask(rest, options);
+  if (cmd === "update-status") return cmdUpdateStatus(rest, options);
+  if (cmd === "update-subtask") return cmdUpdateSubtask(rest, options);
+  printResult({ ok: false, error: `Unknown command: ${cmd}`, hint: "Use: casement help" }, options);
+  process.exit(1);
+}
+async function main() {
+  const parsed = parseGlobalArgv(process.argv);
+  await runCommand(parsed.command, parsed.args, parsed.options);
+}
+main().catch((err) => {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(JSON.stringify({ ok: false, error: msg }, null, 2));
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map