@dac-tech-team-tw/itsaplan-cli 0.1.0 → 0.2.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",

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/issues.d.ts

@@ -3,6 +3,8 @@ export interface IssueOptions {
     id?: string;
     project?: string;
     comments?: boolean;
+    includeState?: boolean;
+    outputSelected?: boolean;
     limit?: string | number;
     cursor?: string;
     search?: string;

package/dist/issues.js

@@ -627,9 +627,12 @@ export async function runIssue(ctx, action, identifier, options) {
             throw new CliError("UNSUPPORTED_FILTER_COMBINATION", "--search cannot be combined with --assignee");
         if (options.search !== undefined && !options.search.trim())
             throw new CliError("INVALID_SEARCH", "--search must not be empty");
-        let assigneeUserId;
-        if (options.assignee !== undefined)
-            assigneeUserId = await assignee(ctx, await getProject(ctx, ref), options.assignee);
+        const setup = options.assignee !== undefined || options.includeState
+            ? await getProject(ctx, ref)
+            : undefined;
+        const assigneeUserId = options.assignee !== undefined && setup
+            ? await assignee(ctx, setup, options.assignee)
+            : undefined;
         const items = objects(await ctx.client.request(`/projects/${encodeURIComponent(ref)}/issues${options.search !== undefined ? "/search" : ""}`, {
             query: {
                 limit,
@@ -642,14 +645,57 @@ export async function runIssue(ctx, action, identifier, options) {
             typeof entry.identifier !== "string" ||
             typeof entry.title !== "string"))
             unsupported("List response is missing issue identifiers or titles");
+        let selectedItems = items;
+        if (options.includeState && setup) {
+            if (items.some((entry) => !positive(entry.columnId)))
+                unsupported("List response is missing issue state identifiers");
+            const columns = new Map(setup.columns.map(({ id, name, stateType }) => [
+                id,
+                { id, name, stateType },
+            ]));
+            selectedItems = items.map((entry) => ({
+                ...entry,
+                state: columns.get(entry.columnId) ?? {
+                    id: entry.columnId,
+                    unavailable: true,
+                },
+            }));
+        }
         return {
-            data: { items: publicData(items), nextCursor: null },
-            meta: { limit, returned: items.length, completeness: "unknown" },
+            data: { items: publicData(selectedItems), nextCursor: null },
+            meta: {
+                limit,
+                returned: items.length,
+                completeness: "unknown",
+                ...(options.outputSelected
+                    ? {
+                        scope: {
+                            projectRef: setup?.project.ref ?? ref,
+                            ...(options.search !== undefined
+                                ? { search: options.search }
+                                : {}),
+                            ...(options.assignee !== undefined
+                                ? { assignee: options.assignee, assigneeUserId }
+                                : {}),
+                        },
+                    }
+                    : {}),
+            },
         };
     }
     if (!["resolve", "view", "activity", "comments"].includes(action))
         throw new CliError("UNKNOWN_ACTION", `Unsupported issue action: ${action}`);
     const { item, ref } = await resolve(ctx, identifier, options);
+    const selectedMeta = options.outputSelected
+        ? {
+            scope: {
+                issueId: item.id,
+                identifier: item.identifier,
+                ...(ref ? { projectRef: ref } : {}),
+                projectId: item.projectId,
+            },
+        }
+        : {};
     if (action === "resolve")
         return {
             data: publicData({
@@ -660,6 +706,7 @@ export async function runIssue(ctx, action, identifier, options) {
                 sequenceNumber: item.sequenceNumber,
                 ...(ref ? { projectRef: ref } : {}),
             }),
+            ...(options.outputSelected ? { meta: selectedMeta } : {}),
         };
     if (action === "activity" || action === "comments") {
         const limit = options.limit === undefined ? 25 : integer(options.limit, "--limit", 100);
@@ -673,10 +720,27 @@ export async function runIssue(ctx, action, identifier, options) {
                 limit,
                 returned: page.items.length,
                 completeness: page.nextCursor === null ? "complete" : "partial",
+                ...selectedMeta,
+                ...(options.outputSelected
+                    ? {
+                        read: {
+                            entries: {
+                                status: "read_page",
+                                contentRead: true,
+                                filter: action === "comments" ? "comments" : "all",
+                                cursor: options.cursor ?? null,
+                                nextCursor: encodeCursor(page.nextCursor),
+                            },
+                            attachments: { status: "not_read", contentRead: false },
+                        },
+                    }
+                    : {}),
             },
         };
     }
     const setup = await setupFor(ctx, item, ref);
+    if (selectedMeta.scope)
+        selectedMeta.scope.projectRef = String(setup.project.ref);
     const attachments = objects(await ctx.client.request(`/issues/${item.id}/attachments`), "attachments");
     if (attachments.some((entry) => typeof entry.id !== "string" ||
         typeof entry.filename !== "string" ||
@@ -685,6 +749,18 @@ export async function runIssue(ctx, action, identifier, options) {
         unsupported("Invalid attachment metadata");
     const data = object(enriched(item, setup), "enriched issue");
     data.attachments = publicData(attachments);
+    const read = options.outputSelected
+        ? {
+            read: {
+                comments: { status: "not_read" },
+                attachments: {
+                    status: "metadata_only",
+                    returned: attachments.length,
+                    contentRead: false,
+                },
+            },
+        }
+        : {};
     if (options.comments) {
         const page = await feed(ctx, item.id, 25, undefined, true);
         data.comments = {
@@ -694,16 +770,31 @@ export async function runIssue(ctx, action, identifier, options) {
         return {
             data,
             meta: {
+                ...selectedMeta,
                 comments: {
                     limit: 25,
                     returned: page.items.length,
                     completeness: page.nextCursor === null ? "complete" : "partial",
                 },
                 attachmentsContentRead: false,
+                ...(options.outputSelected
+                    ? {
+                        read: {
+                            ...read.read,
+                            comments: {
+                                status: "read_page",
+                                nextCursor: encodeCursor(page.nextCursor),
+                            },
+                        },
+                    }
+                    : {}),
             },
         };
     }
-    return { data, meta: { attachmentsContentRead: false } };
+    return {
+        data,
+        meta: { attachmentsContentRead: false, ...selectedMeta, ...read },
+    };
 }
 // Shared resource workflows use the same identity, scope, input and outcome rules.
 export { actorFor, readBody, me, integer, object, objects, positive, projectRef, publicData, getProject, resolve, setupFor, writeFailure, verificationFailed, };

package/dist/output.d.ts

@@ -0,0 +1,12 @@
+import { type Result } from "./contracts.js";
+export type OutputKind = "project.list" | "project.view" | "issue.list" | "issue.view" | "issue.resolve" | "issue.comments" | "issue.activity";
+export interface OutputOptions {
+    summary?: boolean;
+    fields?: string;
+}
+/** Validate against command schemas even when the eventual result is empty. */
+export declare function validateOutput(kind: OutputKind, options: OutputOptions): void;
+/** Only opt-in issue list state output needs project state lookup enrichment. */
+export declare function needsIssueStates(kind: OutputKind, options: OutputOptions): boolean;
+/** Shape data only: serialization, redaction and fetching belong to callers. */
+export declare function projectOutput(kind: OutputKind, result: Result, options: OutputOptions): Result;