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

package/dist/commands.js

@@ -1,7 +1,7 @@
 import { access, lstat, readFile, rename, rm, writeFile, } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
-import { input, password } from "@inquirer/prompts";
+import { input, password, select } from "@inquirer/prompts";
 import { stringify } from "smol-toml";
 import { API_BASELINE, CLI_VERSION, CliError, } from "./contracts.js";
 import { createContext, getConfigPaths, normalizeApiUrl, readUserConfig, removeAuth, resolveApiUrl, saveAuth, } from "./config.js";
@@ -247,26 +247,142 @@ export async function runDoctor(options) {
     }
     return { data: diagnostics, meta: { apiVersion: diagnostics.serverVersion } };
 }
+function environmentAuthWarning() {
+    const endpoint = process.env.ITSAPLAN_URL
+        ? "後續仍使用 ITSAPLAN_URL 指向的環境憑證，身份可能與已存登入不同。"
+        : "缺少 ITSAPLAN_URL，後續未帶 --api-url 的指令仍會失敗（EXPLICIT_ENDPOINT_REQUIRED）。";
+    const remedy = process.platform === "win32"
+        ? "如要使用已存登入，請在目前 shell 移除 ITSAPLAN_API_KEY 與 ITSAPLAN_URL，再執行 iap auth status。"
+        : "如要暫時使用已存登入：env -u ITSAPLAN_API_KEY -u ITSAPLAN_URL iap auth status";
+    return `ITSAPLAN_API_KEY 仍優先於已儲存的登入。\n${endpoint}\n${remedy}`;
+}
+async function loginEffectiveAuth(apiUrl, user) {
+    const effective = {
+        source: process.env.ITSAPLAN_API_KEY !== undefined ? "env" : "unresolved",
+        apiUrl: null,
+        tokenAvailable: process.env.ITSAPLAN_API_KEY !== undefined
+            ? Boolean(process.env.ITSAPLAN_API_KEY)
+            : null,
+        authenticated: false,
+        usable: null,
+        verification: "not_run",
+    };
+    try {
+        // Describe the next unqualified command, not the flags used for this login.
+        if (process.env.ITSAPLAN_URL !== undefined)
+            effective.apiUrl = normalizeApiUrl(process.env.ITSAPLAN_URL);
+        const ctx = await createContext({});
+        Object.assign(effective, ctx.auth);
+        if (!ctx.auth.tokenAvailable) {
+            effective.usable = false;
+            effective.error = errorInfo(new CliError("AUTHENTICATION_REQUIRED", "目前生效的 API 服務網址沒有可用的 API key。", 3));
+        }
+        else if (ctx.auth.source === "config" && ctx.auth.apiUrl === apiUrl) {
+            Object.assign(effective, {
+                authenticated: true,
+                usable: true,
+                verification: "passed",
+                user,
+            });
+        }
+    }
+    catch (error) {
+        effective.usable = false;
+        effective.error = errorInfo(error);
+    }
+    return effective;
+}
 export async function runAuth(action, options) {
     try {
         if (action === "status") {
-            const ctx = await createContext(options);
+            const config = await readUserConfig();
+            const storage = config.api_url
+                ? config.credentials?.[config.api_url]?.storage
+                : undefined;
+            const saved = {
+                apiUrl: config.api_url ?? null,
+                configured: storage !== undefined,
+                storage: storage ?? null,
+                tokenAvailable: null,
+                authenticated: false,
+                verification: "not_run",
+                credentials: Object.entries(config.credentials ?? {}).map(([apiUrl, entry]) => ({ apiUrl, storage: entry.storage })),
+            };
+            const envDefined = process.env.ITSAPLAN_API_KEY !== undefined;
+            const effective = {
+                source: envDefined
+                    ? "env"
+                    : options.apiKey !== undefined
+                        ? "flag"
+                        : storage
+                            ? "config"
+                            : "missing",
+                apiUrl: null,
+                tokenAvailable: envDefined
+                    ? Boolean(process.env.ITSAPLAN_API_KEY)
+                    : options.apiKey !== undefined
+                        ? Boolean(options.apiKey)
+                        : null,
+                authenticated: false,
+                usable: false,
+                verification: "not_run",
+            };
             const status = {
-                ...ctx.auth,
+                source: effective.source,
+                apiUrl: null,
+                tokenAvailable: effective.tokenAvailable,
                 authenticated: false,
-                ...(ctx.auth.source === "env"
-                    ? {
-                        warning: "ITSAPLAN_API_KEY overrides stored credentials and --api-key.",
-                    }
-                    : {}),
+                saved,
+                effective,
+                ...(envDefined ? { warning: environmentAuthWarning() } : {}),
             };
+            let checkingSaved = false;
+            let verificationStarted = false;
             try {
+                const explicitUrl = options.apiUrl ?? process.env.ITSAPLAN_URL;
+                if (explicitUrl !== undefined)
+                    effective.apiUrl = normalizeApiUrl(explicitUrl);
+                else if (!envDefined && options.apiKey === undefined)
+                    effective.apiUrl = config.api_url ?? null;
+                const ctx = await createContext(options);
+                Object.assign(effective, ctx.auth);
+                Object.assign(status, ctx.auth);
+                checkingSaved =
+                    ctx.auth.source === "config" && ctx.auth.apiUrl === saved.apiUrl;
+                if (!envDefined &&
+                    ctx.auth.apiUrl === saved.apiUrl &&
+                    ctx.auth.storage === saved.storage)
+                    saved.tokenAvailable = ctx.auth.tokenAvailable;
                 if (!ctx.auth.tokenAvailable)
-                    throw new CliError("AUTHENTICATION_REQUIRED", "No API key is available; use auth login or ITSAPLAN_API_KEY with an explicit endpoint.", 3);
+                    throw new CliError("AUTHENTICATION_REQUIRED", "沒有可用的 API key；請執行 auth login，或為 ITSAPLAN_API_KEY 明確指定 API 服務網址。", 3);
+                verificationStarted = true;
                 const user = identity(await ctx.client.request("/me"));
+                Object.assign(effective, {
+                    authenticated: true,
+                    usable: true,
+                    verification: "passed",
+                    user,
+                });
+                if (checkingSaved)
+                    Object.assign(saved, {
+                        authenticated: true,
+                        verification: "passed",
+                        user,
+                    });
                 return { data: { ...status, authenticated: true, user } };
             }
             catch (error) {
+                effective.error = errorInfo(error);
+                if (verificationStarted) {
+                    effective.verification = "failed";
+                    if (checkingSaved)
+                        saved.verification = "failed";
+                }
+                Object.assign(status, {
+                    source: effective.source,
+                    apiUrl: effective.apiUrl,
+                    tokenAvailable: effective.tokenAvailable,
+                });
                 return {
                     data: status,
                     error: errorInfo(error),
@@ -277,7 +393,7 @@ export async function runAuth(action, options) {
         if (action === "logout") {
             const apiUrl = await resolveApiUrl(options);
             if (!apiUrl)
-                throw new CliError("MISSING_API_URL", "Select the API URL with --api-url or ITSAPLAN_URL.", 2);
+                throw new CliError("MISSING_API_URL", "請以 --api-url 或 ITSAPLAN_URL 指定 API 服務網址。", 2);
             const removed = await removeAuth(apiUrl);
             return {
                 data: {
@@ -286,34 +402,70 @@ export async function runAuth(action, options) {
                     ...removed,
                     serverRevoked: false,
                     environmentKeyStillActive: Boolean(process.env.ITSAPLAN_API_KEY),
-                    warning: "Logout removes local credentials only; it does not revoke the server key or clear environment variables.",
+                    warning: "登出只移除本機憑證，不會撤銷伺服器 key 或清除環境變數。",
                 },
                 outcome: "applied",
                 verification: "passed",
             };
         }
         if (action !== "login")
-            throw new CliError("INVALID_ACTION", "Use auth login, status or logout.", 2);
+            throw new CliError("INVALID_ACTION", "請使用 auth login、status 或 logout。", 2);
         if (options.storage !== undefined &&
             options.storage !== "file" &&
             options.storage !== "keyring")
-            throw new CliError("INVALID_STORAGE", "Choose --storage file or keyring.", 2);
+            throw new CliError("INVALID_STORAGE", "請選擇 --storage file 或 keyring。", 2);
         const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
         if (!options.withToken && !interactive)
-            throw new CliError("INTERACTIVE_LOGIN_REQUIRED", "Non-interactive login requires --with-token and a trusted API URL.", 2);
+            throw new CliError("INTERACTIVE_LOGIN_REQUIRED", "非互動登入須使用 --with-token，並指定可信的 API 服務網址。", 2);
         let apiUrl = await resolveApiUrl(options);
         if (!options.withToken && interactive) {
-            const answer = await input({ message: "API URL:", ...(apiUrl ? { default: apiUrl } : {}) }, { output: process.stderr });
+            const source = options.apiUrl !== undefined
+                ? "--api-url"
+                : process.env.ITSAPLAN_URL !== undefined
+                    ? "ITSAPLAN_URL"
+                    : "已儲存設定";
+            const answer = await input({
+                message: `API 服務網址（API 部署網域，非網頁網址；含 https://${apiUrl ? `；預設來自 ${source}` : ""}）：`,
+                ...(apiUrl ? { default: apiUrl } : {}),
+            }, { output: process.stderr });
             apiUrl = normalizeApiUrl(answer);
         }
         if (!apiUrl)
-            throw new CliError("MISSING_API_URL", "Provide --api-url or ITSAPLAN_URL for non-interactive login.", 2);
+            throw new CliError("MISSING_API_URL", "非互動登入須以 --api-url 或 ITSAPLAN_URL 指定 API 服務網址。", 2);
+        if (!options.withToken &&
+            interactive &&
+            process.env.ITSAPLAN_API_KEY !== undefined) {
+            const proceed = await select({
+                message: environmentAuthWarning(),
+                choices: [
+                    {
+                        name: "取消，不讀取或儲存新的 key",
+                        value: false,
+                    },
+                    {
+                        name: "繼續儲存，但不改變環境憑證的優先序",
+                        value: true,
+                    },
+                ],
+                default: false,
+            }, { output: process.stderr });
+            if (!proceed)
+                throw new CliError("LOGIN_CANCELLED", "已取消登入；未讀取或儲存 key，也未變更環境設定。", 2);
+        }
         const token = (options.withToken
             ? await stdinText()
-            : await password({ message: "Personal API key:", mask: "*" }, { output: process.stderr })).trim();
+            : await password({ message: "個人 API key：", mask: "*" }, { output: process.stderr })).trim();
         if (!token || /\s/.test(token))
-            throw new CliError("INVALID_TOKEN", "Provide exactly one non-empty API key.", 2);
-        const user = identity(await new HttpClient(apiUrl, token).request("/me"));
+            throw new CliError("INVALID_TOKEN", "請提供一組非空白且不含空白字元的 API key。", 2);
+        let user;
+        try {
+            user = identity(await new HttpClient(apiUrl, token).request("/me"));
+        }
+        catch (error) {
+            if (error instanceof CliError && error.code === "REDIRECT_REJECTED")
+                throw new CliError(error.code, "此網址回傳重新導向，可能是網頁登入網址，而非 API 服務網址。CLI 不會跟隨重新導向，key 也未轉送。請向管理者確認 API 部署網域，再以 iap auth login --api-url <API_URL> 重試。這不代表 key 無效；同一網頁網址即使手動輸入仍會被拒絕。", error.exitCode, error.details);
+            throw error;
+        }
         const storage = options.storage === "file" ? "file" : "keyring";
         await saveAuth(apiUrl, token, storage);
         return {
@@ -323,10 +475,18 @@ export async function runAuth(action, options) {
                 authenticated: true,
                 storage,
                 user,
-                ...(process.env.ITSAPLAN_API_KEY
-                    ? {
-                        warning: "Login validated the supplied key. ITSAPLAN_API_KEY still overrides this stored credential for subsequent commands.",
-                    }
+                saved: {
+                    apiUrl,
+                    configured: true,
+                    storage,
+                    tokenAvailable: true,
+                    authenticated: true,
+                    verification: "passed",
+                    user,
+                },
+                effective: await loginEffectiveAuth(apiUrl, user),
+                ...(process.env.ITSAPLAN_API_KEY !== undefined
+                    ? { warning: environmentAuthWarning() }
                     : {}),
             },
             outcome: "applied",
@@ -429,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) {
@@ -443,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/config.d.ts

@@ -5,6 +5,7 @@ export interface UserConfig {
     credentials?: Record<string, {
         storage: Storage;
     }>;
+    project_defaults?: Record<string, string>;
 }
 export declare function getConfigPaths(): {
     directory: string;
@@ -15,6 +16,14 @@ export declare function normalizeApiUrl(input: string): string;
 export declare function readUserConfig(): Promise<UserConfig>;
 export declare function resolveApiUrl(options: GlobalOptions): Promise<string | undefined>;
 export declare function resolveProject(options: GlobalOptions): Promise<string | undefined>;
+export interface ProjectSelection {
+    projectRef?: string;
+    source: "flag" | "env" | "directory" | "user" | "missing";
+}
+export declare function resolveProjectSelection(options: GlobalOptions): Promise<ProjectSelection>;
+export declare function saveUserProject(input: string, projectRef: string | undefined): Promise<{
+    changed: boolean;
+}>;
 export declare function saveAuth(input: string, token: string, storage?: Storage): Promise<void>;
 export declare function removeAuth(input: string): Promise<{
     removed: boolean;

package/dist/config.js

@@ -99,6 +99,20 @@ export async function readUserConfig() {
             config.credentials[normalized] = { storage: entry.storage };
         }
     }
+    if (raw.project_defaults !== undefined) {
+        if (!object(raw.project_defaults))
+            throw new CliError("INVALID_CONFIG", "Project defaults must be a table.");
+        config.project_defaults = {};
+        for (const [url, ref] of Object.entries(raw.project_defaults)) {
+            if (typeof ref !== "string" ||
+                !/^[A-Za-z0-9_-]+\.[A-Za-z][A-Za-z0-9_-]*$/u.test(ref))
+                throw new CliError("INVALID_CONFIG", "Saved project defaults must be full team.KEY refs.");
+            const normalized = normalizeApiUrl(url);
+            if (Object.hasOwn(config.project_defaults, normalized))
+                throw new CliError("INVALID_CONFIG", "Duplicate normalized API project endpoints.");
+            config.project_defaults[normalized] = ref;
+        }
+    }
     return config;
 }
 export async function resolveApiUrl(options) {
@@ -119,6 +133,9 @@ async function exists(path) {
     }
 }
 export async function resolveProject(options) {
+    return (await resolveProjectSelection(options)).projectRef;
+}
+export async function resolveProjectSelection(options) {
     const cwd = process.cwd();
     const home = resolve(homedir());
     let boundary = cwd;
@@ -159,11 +176,25 @@ export async function resolveProject(options) {
             break;
         current = dirname(current);
     }
-    const chosen = options.project ?? process.env.ITSAPLAN_PROJECT ?? project;
+    let chosen = options.project ?? process.env.ITSAPLAN_PROJECT ?? project;
+    let source = options.project !== undefined
+        ? "flag"
+        : process.env.ITSAPLAN_PROJECT !== undefined
+            ? "env"
+            : project !== undefined
+                ? "directory"
+                : "missing";
+    if (chosen === undefined) {
+        const apiUrl = await resolveApiUrl(options);
+        if (apiUrl !== undefined)
+            chosen = (await readUserConfig()).project_defaults?.[apiUrl];
+        if (chosen !== undefined)
+            source = "user";
+    }
     if (chosen !== undefined &&
         !/^(?:[A-Za-z0-9_-]+\.)?[A-Za-z][A-Za-z0-9_-]*$/u.test(chosen))
         throw new CliError("INVALID_PROJECT", "Use a project key or team.KEY ref.");
-    return chosen;
+    return { projectRef: chosen, source };
 }
 async function windowsSid() {
     try {
@@ -275,6 +306,35 @@ async function atomicWrite(path, content) {
         await prepared.discard();
     }
 }
+export async function saveUserProject(input, projectRef) {
+    const apiUrl = normalizeApiUrl(input);
+    if (projectRef !== undefined &&
+        !/^[A-Za-z0-9_-]+\.[A-Za-z][A-Za-z0-9_-]*$/u.test(projectRef))
+        throw new CliError("INVALID_PROJECT", "Use a full team.KEY project ref.");
+    const config = await readUserConfig();
+    if (config.project_defaults?.[apiUrl] === projectRef)
+        return { changed: false };
+    if (projectRef === undefined) {
+        delete config.project_defaults?.[apiUrl];
+        if (Object.keys(config.project_defaults ?? {}).length === 0)
+            delete config.project_defaults;
+    }
+    else
+        config.project_defaults = {
+            ...config.project_defaults,
+            [apiUrl]: projectRef,
+        };
+    await prepareDirectory();
+    const prepared = await prepareAtomicWrite(getConfigPaths().config, stringify(config));
+    try {
+        await prepared.commit();
+    }
+    catch (error) {
+        await prepared.discard().catch(() => { });
+        throw error;
+    }
+    return { changed: true };
+}
 async function readCredentials() {
     const { directory, credentials } = getConfigPaths();
     if (!(await exists(credentials)))

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>;