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

package/dist/commands.js

@@ -0,0 +1,521 @@
+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 { stringify } from "smol-toml";
+import { API_BASELINE, CLI_VERSION, CliError, } from "./contracts.js";
+import { createContext, getConfigPaths, normalizeApiUrl, readUserConfig, removeAuth, resolveApiUrl, saveAuth, } from "./config.js";
+import { HttpClient, classifyWriteFailure, redact, validateRelativePath, } from "./http.js";
+function object(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new CliError("UNSUPPORTED_RESPONSE", `The server returned an unsupported ${label} response.`, 2);
+    }
+    return value;
+}
+function identity(value) {
+    const me = object(value, "identity");
+    if (me.authenticated === false)
+        throw new CliError("AUTHENTICATION_FAILED", "The API key was not authenticated.", 3);
+    if (me.authenticated !== true)
+        throw new CliError("UNSUPPORTED_RESPONSE", "The identity response lacks authenticated:true.", 2);
+    const user = object(me.user, "user");
+    if (typeof user.id !== "string" || typeof user.name !== "string") {
+        throw new CliError("UNSUPPORTED_RESPONSE", "The identity response lacks a user id or name.", 2);
+    }
+    return object(redact(user), "user");
+}
+function errorInfo(error) {
+    if (error instanceof CliError) {
+        const details = { ...error.details };
+        for (const field of [
+            "ok",
+            "data",
+            "meta",
+            "outcome",
+            "verification",
+            "exitCode",
+            "error",
+        ])
+            delete details[field];
+        return object(redact({
+            ...details,
+            code: error.code,
+            message: error.message,
+            retryable: false,
+        }), "error");
+    }
+    return {
+        code: "UNEXPECTED_ERROR",
+        message: "The operation failed unexpectedly.",
+        retryable: false,
+    };
+}
+function preflightError(error) {
+    if (error instanceof CliError) {
+        throw new CliError(error.code, error.message, error.exitCode, {
+            outcome: "not_applied",
+            verification: "not_run",
+            ...error.details,
+            retryable: false,
+        });
+    }
+    throw new CliError("LOCAL_OPERATION_FAILED", "The local operation failed; no API write was sent.", 1, { outcome: "not_applied", verification: "not_run", retryable: false });
+}
+async function stdinText() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk)));
+    return Buffer.concat(chunks).toString("utf8");
+}
+async function inputText(path) {
+    if (path === "-")
+        return stdinText();
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        throw new CliError("INPUT_UNREADABLE", "Cannot read the specified UTF-8 input file.", 2);
+    }
+}
+function projectRef(ref, full = false) {
+    if (!ref ||
+        !/^[A-Za-z0-9_-]+(?:\.[A-Za-z0-9_-]+)?$/.test(ref) ||
+        (full && !ref.includes("."))) {
+        throw new CliError("INVALID_PROJECT", `Provide ${full ? "a full project ref, --project <team.KEY>" : "a project key or full <team.KEY> ref"}.`, 2);
+    }
+    return ref;
+}
+function projectSummary(value) {
+    const project = object(value, "project");
+    if (typeof project.id !== "number" ||
+        !Number.isSafeInteger(project.id) ||
+        project.id <= 0 ||
+        typeof project.ref !== "string" ||
+        typeof project.key !== "string" ||
+        typeof project.name !== "string") {
+        throw new CliError("UNSUPPORTED_RESPONSE", "The project response lacks a valid id, ref, key or name.", 2);
+    }
+    projectRef(project.ref, true);
+    return project;
+}
+function projectSetup(value) {
+    const setup = object(value, "project setup");
+    projectSummary(setup.project);
+    for (const field of [
+        "columns",
+        "labels",
+        "issueTypes",
+        "assignees",
+        "customFields",
+    ]) {
+        const entries = setup[field];
+        if (!Array.isArray(entries))
+            throw new CliError("UNSUPPORTED_RESPONSE", `The project setup lacks ${field}.`, 2);
+        for (const entry of entries) {
+            const row = object(entry, field);
+            if (field === "assignees") {
+                if (typeof row.userId !== "string" || typeof row.name !== "string") {
+                    throw new CliError("UNSUPPORTED_RESPONSE", "A project assignee lacks a user id or name.", 2);
+                }
+            }
+            else if (typeof row.id !== "number" ||
+                !Number.isSafeInteger(row.id) ||
+                row.id <= 0 ||
+                typeof row.name !== "string") {
+                throw new CliError("UNSUPPORTED_RESPONSE", `A project ${field} entry lacks a valid id or name.`, 2);
+            }
+            if (field === "columns" &&
+                (typeof row.stateType !== "string" ||
+                    ![
+                        "backlog",
+                        "unstarted",
+                        "started",
+                        "completed",
+                        "canceled",
+                    ].includes(row.stateType))) {
+                throw new CliError("UNSUPPORTED_RESPONSE", "A project column has an unsupported stateType.", 2);
+            }
+            if (field === "customFields" &&
+                (typeof row.fieldType !== "string" || !Array.isArray(row.options))) {
+                throw new CliError("UNSUPPORTED_RESPONSE", "A custom field lacks its type or options.", 2);
+            }
+        }
+    }
+    return object(redact(setup), "project setup");
+}
+export async function runDoctor(options) {
+    const diagnostics = {
+        cliVersion: CLI_VERSION,
+        apiBaseline: API_BASELINE,
+        serverVersion: null,
+        baselineStatus: "not_checked",
+        config: { status: "not_checked" },
+        auth: { source: "missing", tokenAvailable: false, authenticated: false },
+        checks: {},
+    };
+    const checks = diagnostics.checks;
+    const failures = [];
+    try {
+        const path = getConfigPaths().config;
+        await readUserConfig();
+        const present = await access(path).then(() => true, () => false);
+        diagnostics.config = {
+            path,
+            status: present ? "passed" : "missing",
+            optional: true,
+        };
+    }
+    catch (error) {
+        failures.push(error);
+        diagnostics.config = { status: "failed", error: errorInfo(error) };
+    }
+    let ctx;
+    try {
+        ctx = await createContext(options);
+        diagnostics.apiUrl = ctx.auth.apiUrl;
+        diagnostics.auth = { ...ctx.auth, authenticated: false };
+        if (!ctx.auth.tokenAvailable)
+            failures.push(new CliError("AUTHENTICATION_REQUIRED", "No API key is available; use auth login or an explicit endpoint and ITSAPLAN_API_KEY.", 3));
+    }
+    catch (error) {
+        failures.push(error);
+        diagnostics.auth = {
+            source: process.env.ITSAPLAN_API_KEY
+                ? "env"
+                : options.apiKey
+                    ? "flag"
+                    : "missing",
+            tokenAvailable: Boolean(process.env.ITSAPLAN_API_KEY || options.apiKey),
+            authenticated: false,
+            error: errorInfo(error),
+        };
+    }
+    if (ctx) {
+        const context = ctx;
+        await Promise.all([
+            (async () => {
+                try {
+                    const user = identity(await context.client.request("/me"));
+                    diagnostics.auth = { ...context.auth, authenticated: true, user };
+                    checks.identity = { status: "passed" };
+                }
+                catch (error) {
+                    failures.push(error);
+                    checks.identity = { status: "failed", error: errorInfo(error) };
+                }
+            })(),
+            (async () => {
+                try {
+                    const version = object(await context.client.request("/settings/version"), "version");
+                    if (typeof version.version !== "string" || !version.version)
+                        throw new CliError("UNSUPPORTED_RESPONSE", "The server did not return a version.", 2);
+                    diagnostics.serverVersion = version.version;
+                    diagnostics.baselineStatus =
+                        version.version.replace(/^v/, "") === API_BASELINE
+                            ? "tested"
+                            : "unverified";
+                    checks.version = { status: "passed" };
+                }
+                catch (error) {
+                    failures.push(error);
+                    checks.version = { status: "failed", error: errorInfo(error) };
+                }
+            })(),
+        ]);
+    }
+    else {
+        checks.identity = {
+            status: "skipped",
+            reason: "Resolve configuration and endpoint errors first.",
+        };
+        checks.version = {
+            status: "skipped",
+            reason: "Resolve configuration and endpoint errors first.",
+        };
+    }
+    if (failures.length) {
+        const first = failures[0];
+        return {
+            data: diagnostics,
+            exitCode: first instanceof CliError ? first.exitCode : 1,
+            error: {
+                code: "DOCTOR_FAILED",
+                message: "One or more diagnostics failed; inspect data for setup instructions.",
+                retryable: false,
+            },
+        };
+    }
+    return { data: diagnostics, meta: { apiVersion: diagnostics.serverVersion } };
+}
+export async function runAuth(action, options) {
+    try {
+        if (action === "status") {
+            const ctx = await createContext(options);
+            const status = {
+                ...ctx.auth,
+                authenticated: false,
+                ...(ctx.auth.source === "env"
+                    ? {
+                        warning: "ITSAPLAN_API_KEY overrides stored credentials and --api-key.",
+                    }
+                    : {}),
+            };
+            try {
+                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);
+                const user = identity(await ctx.client.request("/me"));
+                return { data: { ...status, authenticated: true, user } };
+            }
+            catch (error) {
+                return {
+                    data: status,
+                    error: errorInfo(error),
+                    exitCode: error instanceof CliError ? error.exitCode : 1,
+                };
+            }
+        }
+        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);
+            const removed = await removeAuth(apiUrl);
+            return {
+                data: {
+                    action: "logout",
+                    apiUrl,
+                    ...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.",
+                },
+                outcome: "applied",
+                verification: "passed",
+            };
+        }
+        if (action !== "login")
+            throw new CliError("INVALID_ACTION", "Use auth login, status or logout.", 2);
+        if (options.storage !== undefined &&
+            options.storage !== "file" &&
+            options.storage !== "keyring")
+            throw new CliError("INVALID_STORAGE", "Choose --storage file or 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);
+        let apiUrl = await resolveApiUrl(options);
+        if (!options.withToken && interactive) {
+            const answer = await input({ message: "API URL:", ...(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);
+        const token = (options.withToken
+            ? await stdinText()
+            : await password({ message: "Personal 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"));
+        const storage = options.storage === "file" ? "file" : "keyring";
+        await saveAuth(apiUrl, token, storage);
+        return {
+            data: {
+                action: "login",
+                apiUrl,
+                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.",
+                    }
+                    : {}),
+            },
+            outcome: "applied",
+            verification: "passed",
+        };
+    }
+    catch (error) {
+        if (action === "login" || action === "logout")
+            preflightError(error);
+        throw error;
+    }
+}
+export async function runProject(ctx, action, ref, options = {}) {
+    if (action === "view") {
+        const target = projectRef(ref ?? ctx.project);
+        return {
+            data: projectSetup(await ctx.client.request(`/projects/${encodeURIComponent(target)}`)),
+        };
+    }
+    if (action !== "list")
+        throw new CliError("INVALID_ACTION", "Use project list or view.", 2);
+    const limit = options.limit;
+    if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1))
+        throw new CliError("INVALID_LIMIT", "Limit must be a positive safe integer.", 2);
+    const response = await ctx.client.request("/projects");
+    if (!Array.isArray(response))
+        throw new CliError("UNSUPPORTED_RESPONSE", "The server did not return a project list.", 2);
+    const all = response.map(projectSummary);
+    const items = limit === undefined ? all : all.slice(0, limit);
+    return {
+        data: { items: redact(items), nextCursor: null },
+        meta: {
+            ...(limit === undefined ? {} : { limit }),
+            returned: items.length,
+            completeness: items.length < all.length ? "partial" : "complete",
+        },
+    };
+}
+async function validateProjectConfigTarget(path) {
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            throw new CliError("UNSAFE_PROJECT_CONFIG", "Refusing to replace a symlink or non-regular .itsaplan.toml.", 2);
+        }
+    }
+    catch (error) {
+        if (error !== null &&
+            typeof error === "object" &&
+            "code" in error &&
+            error.code === "ENOENT")
+            return;
+        throw error;
+    }
+}
+export async function runInit(ctx, project) {
+    let temporary;
+    try {
+        const target = projectRef(project, true);
+        const path = resolve(".itsaplan.toml");
+        await validateProjectConfigTarget(path);
+        const setup = projectSetup(await ctx.client.request(`/projects/${encodeURIComponent(target)}`));
+        const selected = projectSummary(setup.project);
+        if (selected.ref !== target)
+            throw new CliError("PROJECT_MISMATCH", "The API returned a different project ref; local configuration was not changed.", 2);
+        temporary = `${path}.${randomUUID()}.tmp`;
+        await writeFile(temporary, stringify({ project_ref: target }), {
+            encoding: "utf8",
+            mode: 0o600,
+            flag: "wx",
+        });
+        await validateProjectConfigTarget(path);
+        await rename(temporary, path);
+        temporary = undefined;
+        return {
+            data: { action: "init", projectRef: target, path, changed: true },
+            outcome: "applied",
+            verification: "passed",
+        };
+    }
+    catch (error) {
+        return preflightError(error);
+    }
+    finally {
+        if (temporary !== undefined)
+            await rm(temporary, { force: true });
+    }
+}
+function protectedResourceWrite(path) {
+    let pathname = path.split("?")[0] ?? "";
+    for (;;) {
+        const decoded = decodeURIComponent(pathname);
+        if (decoded === pathname)
+            break;
+        pathname = decoded;
+    }
+    // Match decoded namespace boundaries, including repeated separators, before any write.
+    pathname = pathname.replace(/\/+/g, "/");
+    if (/^\/(?:issues|comments|checklists|worklogs|attachments)(?:\/|$)/i.test(pathname) ||
+        /^\/projects\/[^/]+\/issues(?:\/|$)/i.test(pathname))
+        return "issue";
+    if (/^\/projects\/[^/]+\/documents(?:\/|$)/i.test(pathname))
+        return "document";
+    return undefined;
+}
+export async function runApi(ctx, path, options) {
+    const method = (options.method ?? "GET").toUpperCase();
+    const write = method !== "GET" && method !== "HEAD";
+    let sent = false;
+    try {
+        if (!["GET", "HEAD", "POST", "PATCH", "PUT", "DELETE"].includes(method))
+            throw new CliError("INVALID_METHOD", "Use GET, HEAD, POST, PATCH, PUT or DELETE.", 2);
+        const safePath = validateRelativePath(path);
+        const resource = write ? protectedResourceWrite(safePath) : undefined;
+        if (resource)
+            throw new CliError(resource === "issue"
+                ? "RAW_ISSUE_WRITE_FORBIDDEN"
+                : "RAW_DOCUMENT_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);
+        if (!write && options.input !== undefined)
+            throw new CliError("INPUT_NOT_SUPPORTED", "GET and HEAD do not accept --input.", 2);
+        let body;
+        if (options.input !== undefined) {
+            const text = await inputText(options.input);
+            try {
+                body = JSON.parse(text);
+            }
+            catch {
+                throw new CliError("INVALID_JSON", "The input must contain valid JSON.", 2);
+            }
+        }
+        if (options.dryRun) {
+            const user = identity(await ctx.client.request("/me"));
+            return {
+                data: {
+                    action: "api",
+                    dryRun: true,
+                    identity: user,
+                    request: {
+                        method,
+                        path: safePath,
+                        ...(body === undefined ? {} : { body: redact(body) }),
+                    },
+                    warning: "No write was sent. Server-side permissions and validation are not guaranteed by this preview.",
+                },
+                ...(write
+                    ? {
+                        outcome: "not_applied",
+                        verification: "not_run",
+                    }
+                    : {}),
+            };
+        }
+        sent = true;
+        const data = await ctx.client.request(safePath, {
+            method,
+            ...(body === undefined ? {} : { body }),
+        });
+        return {
+            data: redact(data),
+            ...(write
+                ? { outcome: "applied", verification: "passed" }
+                : {}),
+        };
+    }
+    catch (error) {
+        if (!write)
+            throw error;
+        const outcome = sent ? classifyWriteFailure(error) : "not_applied";
+        const info = errorInfo(error);
+        return {
+            data: { action: "api", method },
+            outcome,
+            verification: "not_run",
+            exitCode: outcome === "unknown"
+                ? 6
+                : error instanceof CliError
+                    ? error.exitCode
+                    : 1,
+            error: {
+                ...info,
+                ...(outcome === "unknown"
+                    ? {
+                        code: "WRITE_OUTCOME_UNKNOWN",
+                        message: "The raw write outcome is unknown; inspect the resource before resending.",
+                    }
+                    : {}),
+                retryable: false,
+            },
+        };
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,23 @@
+import { type Context, type GlobalOptions } from "./contracts.js";
+export type Storage = "keyring" | "file";
+export interface UserConfig {
+    api_url?: string;
+    credentials?: Record<string, {
+        storage: Storage;
+    }>;
+}
+export declare function getConfigPaths(): {
+    directory: string;
+    config: string;
+    credentials: string;
+};
+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 declare function saveAuth(input: string, token: string, storage?: Storage): Promise<void>;
+export declare function removeAuth(input: string): Promise<{
+    removed: boolean;
+    storage?: string;
+}>;
+export declare function createContext(options: GlobalOptions): Promise<Context>;