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

package/dist/http.js

@@ -0,0 +1,306 @@
+import { CliError } from "./contracts.js";
+const secrets = new Set();
+export function registerSecret(token) {
+    if (token)
+        secrets.add(token);
+}
+export function redact(value) {
+    const currentSecrets = new Set(secrets);
+    if (process.env.ITSAPLAN_API_KEY)
+        currentSecrets.add(process.env.ITSAPLAN_API_KEY);
+    for (let index = 0; index < process.argv.length; index++) {
+        const arg = process.argv[index];
+        if (arg === "--api-key" && process.argv[index + 1])
+            currentSecrets.add(process.argv[index + 1]);
+        else if (arg?.startsWith("--api-key="))
+            currentSecrets.add(arg.slice("--api-key=".length));
+    }
+    const ordered = [...currentSecrets]
+        .filter(Boolean)
+        .sort((a, b) => b.length - a.length);
+    const seen = new WeakSet();
+    function visit(entry) {
+        if (typeof entry === "string") {
+            let text = entry;
+            for (const token of ordered)
+                text = text.split(token).join("[REDACTED]");
+            return text;
+        }
+        if (entry === null || typeof entry !== "object")
+            return entry;
+        if (seen.has(entry))
+            return "[Circular]";
+        seen.add(entry);
+        let result;
+        if (Array.isArray(entry))
+            result = entry.map(visit);
+        else {
+            const object = {};
+            for (const [key, content] of Object.entries(entry)) {
+                const name = key.replace(/[-_\s]/gu, "").toLowerCase();
+                const safeKey = String(visit(key));
+                const availability = typeof content === "boolean" &&
+                    /^(?:tokenavailable|hastoken|apikeyavailable|apikeypresent|keypresent)$/u.test(name);
+                Object.defineProperty(object, safeKey, {
+                    value: !availability &&
+                        /token|secret|password|credential|authorization|cookie|apikey|privatekey/u.test(name)
+                        ? "[REDACTED]"
+                        : visit(content),
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                });
+            }
+            result = object;
+        }
+        seen.delete(entry);
+        return result;
+    }
+    return visit(value);
+}
+export function validateRelativePath(input) {
+    if (!input ||
+        /^[a-z][a-z0-9+.-]*:/iu.test(input) ||
+        input.startsWith("//") ||
+        /[\\\u0000-\u0020\u007f#]/u.test(input))
+        throw new CliError("INVALID_API_PATH", "Use a relative API path without an origin, fragment, whitespace, or backslash.");
+    const queryAt = input.indexOf("?");
+    const pathname = queryAt < 0 ? input : input.slice(0, queryAt);
+    let decoded = pathname;
+    try {
+        for (let iteration = 0; iteration < 16; iteration++) {
+            if (/%(?:2f|5c)/iu.test(decoded) ||
+                /[\\\u0000-\u0020\u007f]/u.test(decoded) ||
+                decoded.startsWith("//") ||
+                decoded
+                    .split("/")
+                    .some((segment) => segment === "." || segment === "..") ||
+                /^[a-z][a-z0-9+.-]*:/iu.test(decoded))
+                throw new Error("Unsafe path");
+            const next = decodeURIComponent(decoded);
+            if (next === decoded)
+                break;
+            decoded = next;
+            if (iteration === 15)
+                throw new Error("Excessive encoding");
+        }
+        if (queryAt >= 0) {
+            const query = decodeURIComponent(input.slice(queryAt + 1));
+            if (/[\u0000-\u001f\u007f]/u.test(query))
+                throw new Error("Unsafe query");
+        }
+    }
+    catch {
+        throw new CliError("INVALID_API_PATH", "API path contains traversal, encoded separators, controls, or malformed percent encoding.");
+    }
+    return input.startsWith("/") ? input : `/${input}`;
+}
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const rejectedStatuses = new Set([
+    400, 401, 403, 404, 405, 409, 413, 415, 422, 429,
+]);
+export function classifyWriteFailure(error) {
+    const details = error instanceof CliError ? error.details : {};
+    if (details.outcome !== undefined)
+        return details.outcome === "not_applied" ? "not_applied" : "unknown";
+    return typeof details.status === "number" &&
+        rejectedStatuses.has(details.status)
+        ? "not_applied"
+        : "unknown";
+}
+export class HttpClient {
+    apiUrl;
+    token;
+    constructor(apiUrl, token) {
+        this.apiUrl = apiUrl;
+        this.token = token;
+        if (token)
+            registerSecret(token);
+    }
+    async request(input, options = {}) {
+        const method = (options.method ?? "GET").toUpperCase();
+        const write = !["GET", "HEAD"].includes(method);
+        let url;
+        let headers;
+        let body;
+        try {
+            if (!["GET", "HEAD", "POST", "PATCH", "PUT", "DELETE"].includes(method))
+                throw new CliError("INVALID_HTTP_METHOD", "Supported methods: GET, HEAD, POST, PATCH, PUT, DELETE.");
+            const path = validateRelativePath(input);
+            const base = new URL(this.apiUrl);
+            if (base.username ||
+                base.password ||
+                base.search ||
+                base.hash ||
+                !["https:", "http:"].includes(base.protocol))
+                throw new CliError("INVALID_API_URL", "Invalid API base URL.");
+            const local = ["localhost", "127.0.0.1", "[::1]"].includes(base.hostname);
+            if (base.protocol !== "https:" && !local)
+                throw new CliError("INVALID_API_URL", "HTTPS is required except on localhost.");
+            url = new URL(`${base.toString().replace(/\/+$/u, "")}${path}`);
+            if (url.origin !== base.origin ||
+                !url.pathname.startsWith(`${base.pathname.replace(/\/+$/u, "")}/`))
+                throw new CliError("INVALID_API_PATH", "API path must remain inside the configured endpoint.");
+            for (const [key, value] of Object.entries(options.query ?? {}))
+                if (value !== undefined)
+                    url.searchParams.set(key, String(value));
+            headers = new Headers({ accept: "application/json" });
+            if (this.token !== undefined) {
+                if (!this.token || /[\r\n\0]/u.test(this.token))
+                    throw new CliError("INVALID_TOKEN", "API key must be nonempty and contain no line breaks.");
+                headers.set("x-api-key", this.token);
+            }
+            if (options.body !== undefined) {
+                if (!write)
+                    throw new CliError("INVALID_REQUEST_BODY", "GET and HEAD requests do not accept a body.");
+                body = JSON.stringify(options.body);
+                if (body === undefined)
+                    throw new CliError("INVALID_REQUEST_BODY", "Request body must be JSON serializable.");
+                headers.set("content-type", "application/json");
+            }
+        }
+        catch (error) {
+            if (error instanceof CliError) {
+                if (write)
+                    Object.assign(error.details, {
+                        outcome: "not_applied",
+                        verification: "not_run",
+                        retryable: false,
+                    });
+                throw error;
+            }
+            throw new CliError("INVALID_REQUEST", "Cannot construct a valid HTTP request.", 2, write
+                ? {
+                    outcome: "not_applied",
+                    verification: "not_run",
+                    retryable: false,
+                }
+                : {});
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 30_000);
+        try {
+            const response = await fetch(url, {
+                method,
+                headers,
+                body,
+                redirect: "manual",
+                signal: controller.signal,
+            });
+            if (response.status >= 300 && response.status < 400)
+                throw new CliError(write ? "WRITE_OUTCOME_UNKNOWN" : "REDIRECT_REJECTED", "API redirects are not followed; confirm the configured API URL.", write ? 6 : 1, {
+                    status: response.status,
+                    retryable: false,
+                    ...(write ? { outcome: "unknown", verification: "not_run" } : {}),
+                });
+            let data;
+            const text = method === "HEAD" ? "" : await response.text();
+            if (text) {
+                try {
+                    data = JSON.parse(text);
+                }
+                catch {
+                    if (response.ok)
+                        throw new CliError(write ? "WRITE_OUTCOME_UNKNOWN" : "INVALID_API_RESPONSE", write
+                            ? "Write response is not valid JSON; inspect the resource or feed before resending."
+                            : "API response is not valid JSON.", write ? 6 : 1, {
+                            status: response.status,
+                            retryable: false,
+                            ...(write
+                                ? { outcome: "unknown", verification: "not_run" }
+                                : {}),
+                        });
+                }
+            }
+            else
+                data = null;
+            if (!response.ok) {
+                const refusal = rejectedStatuses.has(response.status);
+                const errorData = record(data) && record(data.error) ? data.error : data;
+                const apiCode = record(errorData) && typeof errorData.code === "string"
+                    ? errorData.code
+                    : undefined;
+                const rawMessage = record(errorData) && typeof errorData.message === "string"
+                    ? errorData.message
+                    : record(data) && typeof data.error === "string"
+                        ? data.error
+                        : `API returned HTTP ${response.status}.`;
+                // Upstream has no ambiguity code; recognize only its exact bare-key
+                // lookup response, never unrelated 409s or a provider-coded conflict.
+                const projectPath = response.status === 409 && method === "GET" && apiCode === undefined
+                    ? /^\/?projects\/([^/?]+)(?:\/|\?|$)/u.exec(input)
+                    : null;
+                const projectRef = projectPath
+                    ? decodeURIComponent(projectPath[1])
+                    : undefined;
+                const ambiguousProject = projectRef !== undefined &&
+                    !projectRef.includes(".") &&
+                    rawMessage ===
+                        `Several of your teams have a project '${projectRef}'. Name it with its team, as '<team>.${projectRef}'.`;
+                const statusExit = response.status === 401
+                    ? 3
+                    : response.status === 403
+                        ? 4
+                        : ambiguousProject
+                            ? 2
+                            : response.status === 409
+                                ? 5
+                                : response.status === 400 || response.status === 422
+                                    ? 2
+                                    : 1;
+                const code = response.status === 401
+                    ? "AUTHENTICATION_FAILED"
+                    : response.status === 403
+                        ? "PERMISSION_DENIED"
+                        : ambiguousProject
+                            ? "AMBIGUOUS_PROJECT"
+                            : response.status === 409
+                                ? "CONFLICT"
+                                : response.status === 400 || response.status === 422
+                                    ? "INVALID_API_INPUT"
+                                    : "API_ERROR";
+                throw new CliError(write && !refusal ? "WRITE_OUTCOME_UNKNOWN" : code, String(redact(rawMessage)), write && !refusal ? 6 : statusExit, {
+                    status: response.status,
+                    ...(apiCode ? { apiCode: redact(apiCode) } : {}),
+                    retryable: !write && (response.status === 429 || response.status >= 500),
+                    ...(write
+                        ? {
+                            outcome: refusal ? "not_applied" : "unknown",
+                            verification: "not_run",
+                        }
+                        : {}),
+                });
+            }
+            if (url.pathname.replace(/\/$/u, "") ===
+                `${new URL(this.apiUrl).pathname.replace(/\/$/u, "")}/me`) {
+                if (record(data) && data.authenticated === false)
+                    throw new CliError("AUTHENTICATION_FAILED", "API key was not accepted or the account is inactive.", 3, { status: response.status, retryable: false });
+                if (!record(data) || data.authenticated !== true || !record(data.user))
+                    throw new CliError("UNSUPPORTED_API_RESPONSE", "The /me response does not contain an authenticated identity.", 1, { status: response.status, retryable: false });
+            }
+            return redact(data);
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            const timeout = controller.signal.aborted ||
+                (error instanceof Error &&
+                    ["TimeoutError", "AbortError"].includes(error.name));
+            throw new CliError(write
+                ? "WRITE_OUTCOME_UNKNOWN"
+                : timeout
+                    ? "REQUEST_TIMEOUT"
+                    : "NETWORK_ERROR", write
+                ? "Write outcome is unknown; inspect the resource or feed before resending."
+                : timeout
+                    ? "API request timed out."
+                    : "API request failed; check network access and the configured API URL.", write ? 6 : 1, {
+                retryable: !write,
+                ...(write ? { outcome: "unknown", verification: "not_run" } : {}),
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/issues.d.ts

@@ -0,0 +1,63 @@
+import { type Actor, type Context, type ObjectData, type Result } from "./contracts.js";
+export interface IssueOptions {
+    id?: string;
+    project?: string;
+    comments?: boolean;
+    includeState?: boolean;
+    outputSelected?: boolean;
+    limit?: string | number;
+    cursor?: string;
+    search?: string;
+    assignee?: string;
+    title?: string;
+    body?: string;
+    bodyFile?: string;
+    state?: string;
+    stateType?: string;
+    columnId?: string;
+    removeAssignee?: boolean;
+    priority?: string;
+    removePriority?: boolean;
+    type?: string;
+    removeType?: boolean;
+    addLabel?: string[];
+    removeLabel?: string[];
+    replyTo?: string;
+    agent?: string;
+    human?: boolean;
+    dryRun?: boolean;
+}
+type RecordValue = Record<string, unknown>;
+interface Issue extends RecordValue {
+    id: number;
+    projectId: number;
+    identifier: string;
+    sequenceNumber: number;
+}
+interface Project {
+    project: RecordValue;
+    columns: RecordValue[];
+    issueTypes: RecordValue[];
+    labels: RecordValue[];
+    assignees: RecordValue[];
+    customFields: RecordValue[];
+}
+declare const positive: (value: unknown) => value is number;
+declare function object(value: unknown, name: string): RecordValue;
+declare function objects(value: unknown, name: string): RecordValue[];
+declare function integer(value: string | number, name: string, max?: number): number;
+declare function projectRef(value: string): string;
+declare function publicData(value: unknown): unknown;
+declare function getProject(ctx: Context, ref: string): Promise<Project>;
+declare function resolve(ctx: Context, identifier: string | undefined, options: IssueOptions): Promise<{
+    item: Issue;
+    ref: string | undefined;
+}>;
+declare function setupFor(ctx: Context, item: Issue, ref: string | undefined): Promise<Project>;
+declare function actorFor(options: IssueOptions): Actor;
+declare function readBody(options: IssueOptions): Promise<string | undefined>;
+declare function me(ctx: Context): Promise<RecordValue>;
+declare function writeFailure(error: unknown, data: ObjectData, actor: Actor, resource?: string): Result;
+declare function verificationFailed(data: ObjectData, actor: Actor, resource?: string): Result;
+export declare function runIssue(ctx: Context, action: string, identifier: string | undefined, options: IssueOptions): Promise<Result>;
+export { actorFor, readBody, me, integer, object, objects, positive, projectRef, publicData, getProject, resolve, setupFor, writeFailure, verificationFailed, type Project, };