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

package/dist/commands.js

@@ -0,0 +1,681 @@
+import { access, lstat, readFile, rename, rm, writeFile, } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { resolve } from "node:path";
+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";
+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 } };
+}
+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 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 = {
+                source: effective.source,
+                apiUrl: null,
+                tokenAvailable: effective.tokenAvailable,
+                authenticated: false,
+                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", "沒有可用的 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),
+                    exitCode: error instanceof CliError ? error.exitCode : 1,
+                };
+            }
+        }
+        if (action === "logout") {
+            const apiUrl = await resolveApiUrl(options);
+            if (!apiUrl)
+                throw new CliError("MISSING_API_URL", "請以 --api-url 或 ITSAPLAN_URL 指定 API 服務網址。", 2);
+            const removed = await removeAuth(apiUrl);
+            return {
+                data: {
+                    action: "logout",
+                    apiUrl,
+                    ...removed,
+                    serverRevoked: false,
+                    environmentKeyStillActive: Boolean(process.env.ITSAPLAN_API_KEY),
+                    warning: "登出只移除本機憑證，不會撤銷伺服器 key 或清除環境變數。",
+                },
+                outcome: "applied",
+                verification: "passed",
+            };
+        }
+        if (action !== "login")
+            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", "請選擇 --storage file 或 keyring。", 2);
+        const interactive = Boolean(process.stdin.isTTY && process.stderr.isTTY);
+        if (!options.withToken && !interactive)
+            throw new CliError("INTERACTIVE_LOGIN_REQUIRED", "非互動登入須使用 --with-token，並指定可信的 API 服務網址。", 2);
+        let apiUrl = await resolveApiUrl(options);
+        if (!options.withToken && interactive) {
+            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", "非互動登入須以 --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: "個人 API key：", mask: "*" }, { output: process.stderr })).trim();
+        if (!token || /\s/.test(token))
+            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 {
+            data: {
+                action: "login",
+                apiUrl,
+                authenticated: true,
+                storage,
+                user,
+                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",
+            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,
+            },
+        };
+    }
+}