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

package/dist/issues.js

@@ -0,0 +1,709 @@
+import { readFile } from "node:fs/promises";
+import { isDeepStrictEqual } from "node:util";
+import { CliError, } from "./contracts.js";
+import { classifyWriteFailure } from "./http.js";
+const states = ["backlog", "unstarted", "started", "completed", "canceled"];
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const positive = (value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+function unsupported(message) {
+    throw new CliError("UNSUPPORTED_RESPONSE", message, 2);
+}
+function object(value, name) {
+    if (!record(value))
+        unsupported(`Expected ${name} object from API`);
+    return value;
+}
+function objects(value, name) {
+    if (!Array.isArray(value) || !value.every(record))
+        unsupported(`Expected ${name} array from API`);
+    return value;
+}
+function issue(value) {
+    const item = object(value, "issue");
+    if (!positive(item.id) ||
+        !positive(item.projectId) ||
+        !positive(item.sequenceNumber) ||
+        typeof item.identifier !== "string")
+        unsupported("Issue response is missing stable identifiers");
+    return item;
+}
+function integer(value, name, max = Number.MAX_SAFE_INTEGER) {
+    if ((typeof value === "string" && !/^[1-9]\d*$/.test(value)) ||
+        !positive(Number(value)) ||
+        Number(value) > max)
+        throw new CliError("INVALID_ARGUMENT", `${name} must be an integer between 1 and ${max}`);
+    return Number(value);
+}
+function projectRef(value) {
+    if (!/^(?:[A-Za-z0-9_-]+\.)?[A-Za-z][A-Za-z0-9_-]*$/.test(value))
+        throw new CliError("INVALID_PROJECT", "Use a project key or team.KEY project ref");
+    return value;
+}
+function keyOf(ref) {
+    return ref.slice(ref.lastIndexOf(".") + 1);
+}
+function publicData(value) {
+    if (Array.isArray(value))
+        return value.map(publicData);
+    if (!record(value))
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => !/^(shareToken|shareExtended|token|apiKey|password|secret)$/i.test(key))
+        .map(([key, item]) => [key, publicData(item)]));
+}
+async function getProject(ctx, ref) {
+    const result = object(await ctx.client.request(`/projects/${encodeURIComponent(projectRef(ref))}`), "project setup");
+    const metadata = object(result.project, "project");
+    if (!positive(metadata.id) ||
+        typeof metadata.ref !== "string" ||
+        typeof metadata.key !== "string")
+        unsupported("Project response is missing id, key, or ref");
+    const setup = {
+        project: metadata,
+        columns: objects(result.columns, "columns"),
+        issueTypes: objects(result.issueTypes, "issueTypes"),
+        labels: objects(result.labels, "labels"),
+        assignees: objects(result.assignees, "assignees"),
+        customFields: objects(result.customFields, "customFields"),
+    };
+    for (const [name, values] of [
+        ["columns", setup.columns],
+        ["issueTypes", setup.issueTypes],
+        ["labels", setup.labels],
+        ["customFields", setup.customFields],
+    ]) {
+        if (values.some((item) => !positive(item.id) || typeof item.name !== "string"))
+            unsupported(`Invalid ${name} in project response`);
+        if (values.some((item) => item.projectId !== undefined && item.projectId !== metadata.id))
+            unsupported(`Project response contains foreign ${name}`);
+    }
+    if (setup.columns.some((item) => typeof item.stateType !== "string") ||
+        setup.assignees.some((item) => typeof item.userId !== "string" ||
+            (item.username !== null && typeof item.username !== "string") ||
+            !["member", "agent"].includes(String(item.kind))))
+        unsupported("Invalid columns or assignees in project response");
+    return setup;
+}
+async function resolve(ctx, identifier, options) {
+    if (identifier !== undefined && options.id !== undefined)
+        throw new CliError("CONFLICTING_ARGUMENTS", "An issue identifier and --id are mutually exclusive");
+    const selected = options.project ?? ctx.options.project ?? ctx.project;
+    const ref = selected === undefined ? undefined : projectRef(selected);
+    if (options.id !== undefined) {
+        const item = issue(await ctx.client.request(`/issues/${integer(options.id, "--id")}`));
+        if (ref !== undefined) {
+            const project = await getProject(ctx, ref);
+            if (project.project.id !== item.projectId)
+                throw new CliError("PROJECT_CONFLICT", "The issue does not belong to the selected project");
+        }
+        return { item, ref };
+    }
+    if (identifier === undefined)
+        throw new CliError("ISSUE_REQUIRED", "Provide KEY-42, a project-scoped number, or --id");
+    let key;
+    let sequence;
+    if (/^[0-9]+$/.test(identifier)) {
+        if (ref === undefined)
+            throw new CliError("PROJECT_REQUIRED", "A numeric issue number requires --project or configured project");
+        key = keyOf(ref);
+        sequence = integer(identifier, "issue number");
+    }
+    else {
+        const match = /^([A-Za-z][A-Za-z0-9_-]*)-([1-9]\d*)$/.exec(identifier);
+        if (!match)
+            throw new CliError("INVALID_IDENTIFIER", "Use KEY-42, a project-scoped number, or --id; issue URLs are not supported");
+        key = match[1];
+        sequence = integer(match[2], "issue number");
+        if (ref !== undefined && keyOf(ref) !== key)
+            throw new CliError("PROJECT_CONFLICT", "The issue key conflicts with the selected project");
+    }
+    const target = ref ?? key;
+    const item = issue(await ctx.client.request(`/projects/${encodeURIComponent(target)}/issues/${sequence}`));
+    // Moved identifiers may resolve to a different project. An explicitly selected scope must not silently change.
+    if (ref !== undefined && keyOf(ref) !== item.identifier.replace(/-\d+$/, ""))
+        throw new CliError("PROJECT_CONFLICT", "The resolved issue belongs to a different project");
+    return { item, ref: target };
+}
+async function setupFor(ctx, item, ref) {
+    if (ref !== undefined) {
+        const setup = await getProject(ctx, ref);
+        if (setup.project.id !== item.projectId)
+            throw new CliError("PROJECT_CONFLICT", "The issue does not belong to the selected project");
+        return setup;
+    }
+    // Internal IDs have no project key. Discover only after the exact ID lookup, and match the numeric project ID.
+    const projects = objects(await ctx.client.request("/projects"), "projects");
+    const matches = projects.filter((value) => value.id === item.projectId);
+    if (matches.length !== 1 || typeof matches[0].ref !== "string")
+        unsupported("Cannot resolve the issue project; provide --project team.KEY");
+    return getProject(ctx, matches[0].ref);
+}
+function cursorValue(value) {
+    const item = object(value, "feed cursor");
+    if (typeof item.ts !== "string" ||
+        !item.ts ||
+        !positive(item.id) ||
+        Object.keys(item).some((key) => key !== "ts" && key !== "id"))
+        unsupported("Invalid API feed cursor");
+    return { ts: item.ts, id: item.id };
+}
+function encodeCursor(cursor) {
+    return cursor === null
+        ? null
+        : Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeCursor(value) {
+    if (value === undefined)
+        return undefined;
+    try {
+        if (!/^[A-Za-z0-9_-]+$/.test(value))
+            throw new Error();
+        const buffer = Buffer.from(value, "base64url");
+        if (buffer.toString("base64url") !== value)
+            throw new Error();
+        return JSON.stringify(cursorValue(JSON.parse(buffer.toString("utf8"))));
+    }
+    catch {
+        throw new CliError("INVALID_CURSOR", "Use the opaque nextCursor returned by this CLI");
+    }
+}
+async function feed(ctx, id, limit, cursor, comments) {
+    const data = object(await ctx.client.request(`/issues/${id}/feed`, {
+        query: { limit, cursor, filter: comments ? "comments" : undefined },
+    }), "feed");
+    const items = objects(data.items, "feed items");
+    if (items.some((item) => !positive(item.id) ||
+        item.issueId !== id ||
+        typeof item.kind !== "string"))
+        unsupported("Invalid or foreign issue feed entries");
+    if (!("nextCursor" in data))
+        unsupported("Feed response is missing nextCursor");
+    return {
+        items,
+        nextCursor: data.nextCursor === null ? null : cursorValue(data.nextCursor),
+    };
+}
+async function findComment(ctx, issueId, commentId) {
+    let cursor;
+    const seen = new Set();
+    for (;;) {
+        const page = await feed(ctx, issueId, 100, cursor, true);
+        const found = page.items.find((item) => item.id === commentId && item.kind === "comment");
+        if (found)
+            return found;
+        if (page.nextCursor === null)
+            return undefined;
+        cursor = JSON.stringify(page.nextCursor);
+        if (seen.has(cursor))
+            unsupported("Feed returned a repeated cursor; reply ownership cannot be established");
+        seen.add(cursor);
+    }
+}
+function actorFor(options) {
+    const env = process.env.ITSAPLAN_AGENT;
+    if (options.human && (options.agent !== undefined || Boolean(env)))
+        throw new CliError("ACTOR_CONFLICT", "--human conflicts with --agent or ITSAPLAN_AGENT; clear the environment declaration");
+    if (env && env !== "codex" && env !== "claude")
+        throw new CliError("INVALID_ACTOR", "ITSAPLAN_AGENT must be codex or claude");
+    if (options.agent !== undefined &&
+        options.agent !== "codex" &&
+        options.agent !== "claude")
+        throw new CliError("INVALID_ACTOR", "--agent must be codex or claude");
+    if (options.human)
+        return { kind: "human", source: "flag" };
+    const name = options.agent ?? env;
+    if (name !== "codex" && name !== "claude")
+        throw new CliError("ACTOR_REQUIRED", "Provide --agent codex|claude or --human");
+    return {
+        kind: "agent",
+        name,
+        source: options.agent !== undefined ? "flag" : "env",
+    };
+}
+async function readBody(options) {
+    if (options.body !== undefined && options.bodyFile !== undefined)
+        throw new CliError("CONFLICTING_ARGUMENTS", "--body and --body-file are mutually exclusive");
+    if (options.bodyFile === undefined)
+        return options.body;
+    if (options.bodyFile !== "-") {
+        try {
+            return await readFile(options.bodyFile, "utf8");
+        }
+        catch {
+            throw new CliError("BODY_READ_FAILED", "Cannot read --body-file as UTF-8");
+        }
+    }
+    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");
+}
+function signedBody(body, actor, comment) {
+    let value = body;
+    if (actor.kind === "agent") {
+        if (!comment) {
+            value = value.trimEnd();
+            const footer = /(?:^|\r?\n[ \t]*\r?\n)— last edited by (?:Codex|Claude) via iap$/u;
+            while (footer.test(value))
+                value = value.replace(footer, "").trimEnd();
+        }
+        const name = actor.name === "codex" ? "Codex" : "Claude";
+        value = `${value.trimEnd()}\n\n— ${comment ? "by" : "last edited by"} ${name} via iap`;
+    }
+    if (value.length > 50000 || (comment && !value.trim()))
+        throw new CliError("BODY_LENGTH", "The final body including its footer must be 1–50000 characters for comments, or at most 50000 for descriptions");
+    return value;
+}
+async function me(ctx) {
+    const response = object(await ctx.client.request("/me"), "identity");
+    if (response.authenticated !== true)
+        throw new CliError("AUTHENTICATION_FAILED", "The API key is not authenticated", 3);
+    const user = object(response.user, "current user");
+    if (typeof user.id !== "string" || !user.id)
+        unsupported("Current user response is missing id");
+    return Object.fromEntries(["id", "name", "username", "isAgent"]
+        .filter((key) => user[key] !== undefined)
+        .map((key) => [key, user[key]]));
+}
+function one(values, label, input, predicate) {
+    const matches = values.filter(predicate);
+    if (matches.length === 0)
+        throw new CliError("VALUE_NOT_FOUND", `${label} ${JSON.stringify(input)} is not available in this project`);
+    if (matches.length > 1)
+        throw new CliError("AMBIGUOUS_VALUE", `${label} ${JSON.stringify(input)} is ambiguous`, 2, {
+            candidates: matches.map((item) => ({
+                id: item.id ?? item.userId,
+                name: item.name,
+                username: item.username,
+            })),
+        });
+    return matches[0];
+}
+async function assignee(ctx, setup, value) {
+    const input = value === "@me" ? String((await me(ctx)).id) : value.replace(/^@/, "");
+    const member = one(setup.assignees, "Assignee", value, (entry) => entry.kind === "member" &&
+        (entry.userId === input || entry.username === input));
+    return String(member.userId);
+}
+function exclusive(values, message) {
+    if (values.filter((value) => value !== undefined && value !== false).length > 1)
+        throw new CliError("CONFLICTING_ARGUMENTS", message);
+}
+async function patchFor(ctx, item, setup, options, actor) {
+    exclusive([options.state, options.stateType, options.columnId], "Use only one of --state, --state-type, --column-id");
+    exclusive([options.assignee, options.removeAssignee], "--assignee and --remove-assignee conflict");
+    exclusive([options.priority, options.removePriority], "--priority and --remove-priority conflict");
+    exclusive([options.type, options.removeType], "--type and --remove-type conflict");
+    const patch = {};
+    if (options.title !== undefined) {
+        if (!options.title.trim())
+            throw new CliError("INVALID_TITLE", "--title must not be empty");
+        patch.title = options.title;
+    }
+    const body = await readBody(options);
+    if (body !== undefined)
+        patch.description = signedBody(body, actor, false);
+    if (options.stateType !== undefined && !states.includes(options.stateType))
+        throw new CliError("INVALID_STATE_TYPE", `--state-type must be ${states.join("|")}`);
+    if (options.columnId !== undefined ||
+        options.state !== undefined ||
+        options.stateType !== undefined) {
+        const id = options.columnId === undefined
+            ? undefined
+            : integer(options.columnId, "--column-id");
+        const value = options.columnId ?? options.state ?? options.stateType;
+        patch.columnId = one(setup.columns, "State", value, (entry) => id !== undefined
+            ? entry.id === id
+            : options.state !== undefined
+                ? entry.name === options.state
+                : entry.stateType === options.stateType).id;
+    }
+    if (options.type !== undefined)
+        patch.typeId = one(setup.issueTypes, "Issue type", options.type, (entry) => entry.name === options.type || String(entry.id) === options.type).id;
+    if (options.removeType)
+        patch.typeId = null;
+    if (options.assignee !== undefined)
+        patch.assigneeUserId = await assignee(ctx, setup, options.assignee);
+    if (options.removeAssignee)
+        patch.assigneeUserId = null;
+    if (options.priority !== undefined) {
+        if (!["urgent", "high", "medium", "low"].includes(options.priority))
+            throw new CliError("INVALID_PRIORITY", "--priority must be urgent|high|medium|low");
+        patch.priority = options.priority;
+    }
+    if (options.removePriority)
+        patch.priority = null;
+    const add = options.addLabel ?? [];
+    const remove = options.removeLabel ?? [];
+    if (add.length || remove.length) {
+        if (!Array.isArray(item.labelIds) || !item.labelIds.every(positive))
+            unsupported("Issue response is missing labelIds; cannot preserve existing labels");
+        const resolveLabel = (name) => Number(one(setup.labels, "Label", name, (entry) => entry.name === name || String(entry.id) === name).id);
+        const addIds = add.map(resolveLabel), removeIds = remove.map(resolveLabel);
+        if (addIds.some((id) => removeIds.includes(id)))
+            throw new CliError("CONFLICTING_ARGUMENTS", "The same label cannot be added and removed");
+        patch.labelIds = [
+            ...new Set([
+                ...item.labelIds.filter((id) => !removeIds.includes(id)),
+                ...addIds,
+            ]),
+        ];
+    }
+    if (Object.keys(patch).length === 0)
+        throw new CliError("NO_CHANGES", "Provide at least one issue edit field");
+    for (const key of Object.keys(patch))
+        if (!(key in item))
+            unsupported(`Issue response is missing ${key}; cannot build a trustworthy diff`);
+    return patch;
+}
+function matchesPatch(value, item, patch) {
+    if (!record(value) ||
+        value.id !== item.id ||
+        value.projectId !== item.projectId)
+        return false;
+    return Object.entries(patch).every(([key, expected]) => {
+        const actual = value[key];
+        return key === "labelIds" &&
+            Array.isArray(actual) &&
+            Array.isArray(expected)
+            ? isDeepStrictEqual([...actual].sort(), [...expected].sort())
+            : isDeepStrictEqual(actual, expected);
+    });
+}
+function writeFailure(error, data, actor, resource = "issue/feed") {
+    const detail = error instanceof CliError ? error.details : {};
+    const status = typeof detail.status === "number" ? detail.status : undefined;
+    const rejected = classifyWriteFailure(error) === "not_applied";
+    return {
+        data,
+        meta: { actor },
+        outcome: rejected ? "not_applied" : "unknown",
+        verification: "not_run",
+        exitCode: rejected && error instanceof CliError ? error.exitCode : 6,
+        error: {
+            code: rejected && error instanceof CliError
+                ? error.code
+                : "WRITE_OUTCOME_UNKNOWN",
+            message: rejected && error instanceof CliError
+                ? error.message
+                : `The write outcome is unknown. Read the ${resource} before deciding whether to resend.`,
+            ...(status === undefined ? {} : { status }),
+            ...(typeof detail.apiCode === "string"
+                ? { apiCode: detail.apiCode }
+                : {}),
+            retryable: false,
+        },
+    };
+}
+function verificationFailed(data, actor, resource = "issue/feed") {
+    return {
+        data,
+        meta: { actor },
+        outcome: "applied",
+        verification: "failed",
+        exitCode: 6,
+        error: {
+            code: "VERIFICATION_FAILED",
+            message: `The write was accepted but verification failed. Read the ${resource}; do not resend.`,
+            retryable: false,
+        },
+    };
+}
+async function writeIssue(ctx, action, identifier, options, actor) {
+    const { item, ref } = await resolve(ctx, identifier, options);
+    const setup = action === "edit" ? await setupFor(ctx, item, ref) : undefined;
+    let requestBody;
+    if (action === "edit")
+        requestBody = await patchFor(ctx, item, setup, options, actor);
+    else {
+        const body = await readBody(options);
+        if (body === undefined || !body.trim())
+            throw new CliError("BODY_REQUIRED", "Provide nonempty --body or --body-file");
+        requestBody = { body: signedBody(body, actor, true) };
+        if (options.replyTo !== undefined) {
+            const replyToId = integer(options.replyTo, "--reply-to");
+            if (!(await findComment(ctx, item.id, replyToId)))
+                throw new CliError("REPLY_NOT_FOUND", "The reply target is not a comment belonging to this issue");
+            requestBody.replyToId = replyToId;
+        }
+    }
+    const method = action === "edit" ? "PATCH" : "POST";
+    const path = `/issues/${item.id}${action === "comment" ? "/comments" : ""}`;
+    const data = {
+        action,
+        issueId: item.id,
+        identifier: item.identifier,
+    };
+    if (options.dryRun) {
+        const identity = await me(ctx);
+        const diff = action === "edit"
+            ? Object.fromEntries(Object.entries(requestBody).map(([key, value]) => [
+                key,
+                { before: item[key], after: value },
+            ]))
+            : { body: { before: null, after: requestBody.body } };
+        return {
+            data: {
+                ...data,
+                dryRun: true,
+                identity,
+                request: { method, path, body: requestBody },
+                diff,
+                warnings: [
+                    "Preview does not validate server permissions, WIP limits, or concurrent edits.",
+                    ...(requestBody.labelIds === undefined
+                        ? []
+                        : [
+                            "Label replacement is a read-modify-write operation, not an atomic add/remove.",
+                        ]),
+                ],
+            },
+            meta: { actor },
+            outcome: "not_applied",
+            verification: "not_run",
+        };
+    }
+    let response;
+    try {
+        response = await ctx.client.request(path, { method, body: requestBody });
+    }
+    catch (error) {
+        return writeFailure(error, data, actor);
+    }
+    data.changed = true;
+    if (record(response) && typeof response.updatedAt === "string")
+        data.updatedAt = response.updatedAt;
+    if (action === "edit") {
+        if (matchesPatch(response, item, requestBody))
+            return {
+                data,
+                meta: { actor },
+                outcome: "applied",
+                verification: "passed",
+            };
+        try {
+            const verified = await ctx.client.request(`/issues/${item.id}`);
+            if (matchesPatch(verified, item, requestBody)) {
+                if (typeof verified.updatedAt === "string")
+                    data.updatedAt = verified.updatedAt;
+                return {
+                    data,
+                    meta: { actor },
+                    outcome: "applied",
+                    verification: "passed",
+                };
+            }
+        }
+        catch {
+            /* The accepted write must remain applied when verification fails. */
+        }
+    }
+    else {
+        if (record(response) && positive(response.id))
+            data.commentId = response.id;
+        const matches = (entry) => entry.issueId === item.id &&
+            entry.kind === "comment" &&
+            entry.body === requestBody.body &&
+            entry.replyToId === (requestBody.replyToId ?? null);
+        if (record(response) && positive(response.id) && matches(response))
+            return {
+                data,
+                meta: { actor },
+                outcome: "applied",
+                verification: "passed",
+            };
+        if (typeof data.commentId === "number") {
+            try {
+                const entry = await findComment(ctx, item.id, data.commentId);
+                if (entry && matches(entry))
+                    return {
+                        data,
+                        meta: { actor },
+                        outcome: "applied",
+                        verification: "passed",
+                    };
+            }
+            catch {
+                /* Preserve the applied resource ID. */
+            }
+        }
+    }
+    return verificationFailed(data, actor);
+}
+function enriched(item, setup) {
+    if (typeof item.title !== "string" ||
+        typeof item.description !== "string" ||
+        !positive(item.columnId) ||
+        !Array.isArray(item.labelIds) ||
+        !item.labelIds.every(positive))
+        unsupported("Issue view is missing title, description, state, or labels");
+    const namedIssue = (value) => ({
+        ...value,
+        state: setup.columns.find((entry) => entry.id === value.columnId) ?? null,
+        type: setup.issueTypes.find((entry) => entry.id === value.typeId) ?? null,
+    });
+    const data = namedIssue(item);
+    if (item.parent !== undefined && item.parent !== null)
+        data.parent = namedIssue(object(item.parent, "parent issue"));
+    if (item.subtasks !== undefined)
+        data.subtasks = objects(item.subtasks, "subtasks").map(namedIssue);
+    if (item.links !== undefined)
+        data.links = objects(item.links, "issue links").map((link) => ({
+            ...link,
+            issue: namedIssue(object(link.issue, "linked issue")),
+        }));
+    if (item.fieldValues !== undefined) {
+        data.fieldValues = objects(item.fieldValues, "field values").map((field) => {
+            if (!positive(field.fieldId) ||
+                !Array.isArray(field.optionIds) ||
+                !field.optionIds.every(positive))
+                unsupported("Invalid custom field value identifiers");
+            const definition = setup.customFields.find((entry) => entry.id === field.fieldId);
+            const options = definition?.options === undefined
+                ? []
+                : objects(definition.options, "custom field options");
+            return {
+                ...field,
+                name: definition?.name ?? null,
+                fieldType: definition?.fieldType ?? null,
+                options: field.optionIds.map((id) => options.find((option) => option.id === id) ?? {
+                    id,
+                    unavailable: true,
+                }),
+            };
+        });
+    }
+    return publicData({
+        ...data,
+        project: setup.project,
+        assignee: setup.assignees.find((entry) => entry.userId === item.assigneeUserId) ??
+            null,
+        delegate: setup.assignees.find((entry) => entry.userId === item.delegateUserId) ??
+            null,
+        labels: item.labelIds.map((id) => setup.labels.find((entry) => entry.id === id) ?? {
+            id,
+            unavailable: true,
+        }),
+        customFields: setup.customFields,
+    });
+}
+export async function runIssue(ctx, action, identifier, options) {
+    if (action === "edit" || action === "comment") {
+        let actor;
+        try {
+            actor = actorFor(options);
+            return await writeIssue(ctx, action, identifier, options, actor);
+        }
+        catch (error) {
+            if (error instanceof CliError) {
+                error.details = {
+                    ...error.details,
+                    outcome: "not_applied",
+                    verification: "not_run",
+                    ...(actor ? { meta: { actor } } : {}),
+                    retryable: false,
+                };
+                throw error;
+            }
+            throw new CliError("ISSUE_PREFLIGHT_FAILED", "Issue write preflight failed; no write was sent", 1, {
+                outcome: "not_applied",
+                verification: "not_run",
+                ...(actor ? { meta: { actor } } : {}),
+                retryable: false,
+            });
+        }
+    }
+    if (action === "list") {
+        if (identifier !== undefined || options.id !== undefined)
+            throw new CliError("CONFLICTING_ARGUMENTS", "issue list does not accept an issue identifier or --id");
+        if (options.cursor !== undefined)
+            throw new CliError("UNSUPPORTED_PAGINATION", "Issue list/search only supports a bounded limit, not a cursor");
+        const ref = options.project ?? ctx.options.project ?? ctx.project;
+        if (ref === undefined)
+            throw new CliError("PROJECT_REQUIRED", "Provide --project team.KEY or configure a project");
+        projectRef(ref);
+        const limit = options.limit === undefined ? 30 : integer(options.limit, "--limit", 500);
+        if (options.search !== undefined && options.assignee !== undefined)
+            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 items = objects(await ctx.client.request(`/projects/${encodeURIComponent(ref)}/issues${options.search !== undefined ? "/search" : ""}`, {
+            query: {
+                limit,
+                ...(options.search === undefined
+                    ? { assigneeUserId }
+                    : { q: options.search }),
+            },
+        }), "issues");
+        if (items.some((entry) => !positive(entry.id) ||
+            typeof entry.identifier !== "string" ||
+            typeof entry.title !== "string"))
+            unsupported("List response is missing issue identifiers or titles");
+        return {
+            data: { items: publicData(items), nextCursor: null },
+            meta: { limit, returned: items.length, completeness: "unknown" },
+        };
+    }
+    if (!["resolve", "view", "activity", "comments"].includes(action))
+        throw new CliError("UNKNOWN_ACTION", `Unsupported issue action: ${action}`);
+    const { item, ref } = await resolve(ctx, identifier, options);
+    if (action === "resolve")
+        return {
+            data: publicData({
+                id: item.id,
+                issueId: item.id,
+                projectId: item.projectId,
+                identifier: item.identifier,
+                sequenceNumber: item.sequenceNumber,
+                ...(ref ? { projectRef: ref } : {}),
+            }),
+        };
+    if (action === "activity" || action === "comments") {
+        const limit = options.limit === undefined ? 25 : integer(options.limit, "--limit", 100);
+        const page = await feed(ctx, item.id, limit, decodeCursor(options.cursor), action === "comments");
+        return {
+            data: {
+                items: publicData(page.items),
+                nextCursor: encodeCursor(page.nextCursor),
+            },
+            meta: {
+                limit,
+                returned: page.items.length,
+                completeness: page.nextCursor === null ? "complete" : "partial",
+            },
+        };
+    }
+    const setup = await setupFor(ctx, item, 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" ||
+        typeof entry.contentType !== "string" ||
+        typeof entry.sizeBytes !== "number"))
+        unsupported("Invalid attachment metadata");
+    const data = object(enriched(item, setup), "enriched issue");
+    data.attachments = publicData(attachments);
+    if (options.comments) {
+        const page = await feed(ctx, item.id, 25, undefined, true);
+        data.comments = {
+            items: publicData(page.items),
+            nextCursor: encodeCursor(page.nextCursor),
+        };
+        return {
+            data,
+            meta: {
+                comments: {
+                    limit: 25,
+                    returned: page.items.length,
+                    completeness: page.nextCursor === null ? "complete" : "partial",
+                },
+                attachmentsContentRead: false,
+            },
+        };
+    }
+    return { data, meta: { attachmentsContentRead: false } };
+}
+// 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, };