@dac-tech-team-tw/itsaplan-cli 0.1.0 → 0.3.0

package/dist/initiatives.js

@@ -0,0 +1,241 @@
+import { isDeepStrictEqual } from "node:util";
+import { CliError } from "./contracts.js";
+import { getProject, integer, me, object, objects, positive, projectRef, publicData, readBody } from "./issues.js";
+import { applied, preview, verificationFailed, withWrite, writeFailure } from "./writes.js";
+const statuses = ["proposed", "planned", "active", "completed", "canceled"];
+const record = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function unsupported(message) {
+    throw new CliError("UNSUPPORTED_RESPONSE", message);
+}
+function selectedRef(ctx, options) {
+    const ref = options.project ?? ctx.options.project ?? ctx.project;
+    return ref === undefined ? undefined : projectRef(ref);
+}
+async function selectedProject(ctx, options) {
+    const ref = selectedRef(ctx, options);
+    if (ref === undefined)
+        throw new CliError("PROJECT_REQUIRED", "Provide --project team.KEY or configure a project");
+    return getProject(ctx, ref);
+}
+function initiative(value, id) {
+    const item = object(value, "initiative");
+    if (!positive(item.id) || !positive(item.projectId))
+        unsupported("Initiative response is missing stable identifiers");
+    if (id !== undefined && item.id !== id)
+        unsupported("Initiative response has a different ID");
+    return item;
+}
+async function projectFor(ctx, options, item) {
+    let ref = selectedRef(ctx, options);
+    if (ref === undefined) {
+        const projects = objects(await ctx.client.request("/projects"), "projects");
+        const matches = projects.filter((project) => project.id === item.projectId);
+        if (matches.length !== 1 || typeof matches[0].ref !== "string")
+            unsupported("Cannot resolve the initiative project; provide --project team.KEY");
+        ref = matches[0].ref;
+    }
+    const setup = await getProject(ctx, ref);
+    if (setup.project.id !== item.projectId)
+        throw new CliError("PROJECT_CONFLICT", "The initiative does not belong to the selected project");
+    return setup;
+}
+function canonical(setup) {
+    return projectRef(String(setup.project.ref));
+}
+function validateStatus(value, multiple) {
+    const values = multiple ? value.split(",") : [value];
+    if (!values.length || values.some((entry) => !statuses.includes(entry)))
+        throw new CliError("INVALID_STATUS", `--status must be ${statuses.join("|")}${multiple ? " or a comma-separated subset" : ""}`);
+}
+function labelId(setup, input) {
+    const matches = setup.labels.filter((entry) => entry.name === input || String(entry.id) === input);
+    if (!matches.length)
+        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`);
+    return Number(matches[0].id);
+}
+async function ownerId(ctx, setup, value) {
+    const input = value === "@me" ? String((await me(ctx)).id) : value.replace(/^@/, "");
+    const matches = setup.assignees.filter((entry) => entry.kind === "member" && (entry.userId === input || entry.username === input));
+    if (!matches.length)
+        throw new CliError("VALUE_NOT_FOUND", `Owner ${JSON.stringify(value)} is not available in this project`);
+    if (matches.length !== 1)
+        throw new CliError("AMBIGUOUS_VALUE", `Owner ${JSON.stringify(value)} is ambiguous`);
+    return String(matches[0].userId);
+}
+function signedDescription(body, actor, editing) {
+    let value = body;
+    if (actor.kind === "agent") {
+        value = value.trimEnd();
+        const footer = /(?:^|\r?\n[ \t]*\r?\n)— (?:by|last edited by) (?:Codex|Claude) via iap$/u;
+        while (footer.test(value))
+            value = value.replace(footer, "").trimEnd();
+        value = `${value}\n\n— ${editing ? "last edited by" : "by"} ${actor.name === "codex" ? "Codex" : "Claude"} via iap`;
+    }
+    return value;
+}
+function date(value, flag) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00Z`)) || new Date(`${value}T00:00:00Z`).toISOString().slice(0, 10) !== value)
+        throw new CliError("INVALID_DATE", `${flag} must be a valid YYYY-MM-DD date`);
+    return value;
+}
+async function fields(ctx, setup, options, actor, item) {
+    for (const [value, remove, flag] of [
+        [options.owner, options.removeOwner, "owner"],
+        [options.priority, options.removePriority, "priority"],
+        [options.startDate, options.removeStartDate, "start-date"],
+        [options.targetDate, options.removeTargetDate, "target-date"],
+    ]) {
+        if (value !== undefined && remove)
+            throw new CliError("CONFLICTING_ARGUMENTS", `--${flag} and --remove-${flag} conflict`);
+    }
+    const body = {};
+    if (options.title !== undefined) {
+        if (!options.title.trim())
+            throw new CliError("INVALID_TITLE", "--title must not be empty");
+        body.title = options.title;
+    }
+    const description = await readBody(options);
+    if (description !== undefined)
+        body.description = signedDescription(description, actor, item !== undefined);
+    if (options.status !== undefined) {
+        validateStatus(options.status, false);
+        body.status = options.status;
+    }
+    if (options.owner !== undefined)
+        body.ownerUserId = await ownerId(ctx, setup, options.owner);
+    if (options.removeOwner)
+        body.ownerUserId = 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");
+        body.priority = options.priority;
+    }
+    if (options.removePriority)
+        body.priority = null;
+    if (options.startDate !== undefined)
+        body.startDate = date(options.startDate, "--start-date");
+    if (options.removeStartDate)
+        body.startDate = null;
+    if (options.targetDate !== undefined)
+        body.targetDate = date(options.targetDate, "--target-date");
+    if (options.removeTargetDate)
+        body.targetDate = null;
+    const add = [...(options.label ?? []), ...(options.addLabel ?? [])].map((name) => labelId(setup, name));
+    const remove = (options.removeLabel ?? []).map((name) => labelId(setup, name));
+    if (add.some((id) => remove.includes(id)))
+        throw new CliError("CONFLICTING_ARGUMENTS", "The same label cannot be added and removed");
+    if (add.length || remove.length) {
+        if (item && (!Array.isArray(item.labelIds) || !item.labelIds.every(positive)))
+            unsupported("Initiative response is missing labelIds; cannot preserve existing labels");
+        body.labelIds = [...new Set([...(item ? item.labelIds.filter((id) => !remove.includes(id)) : []), ...add])];
+    }
+    return body;
+}
+function matches(value, id, projectId, body) {
+    if (!record(value) || !positive(value.id) || value.id !== id || value.projectId !== projectId)
+        return false;
+    return Object.entries(body).every(([key, expected]) => {
+        const actual = value[key];
+        if (key === "labelIds" && Array.isArray(actual) && Array.isArray(expected))
+            return actual.every(positive) && isDeepStrictEqual([...actual].sort((a, b) => a - b), [...expected].sort((a, b) => a - b));
+        return isDeepStrictEqual(actual, expected);
+    });
+}
+async function list(ctx, options) {
+    const page = integer(options.page ?? 1, "--page");
+    const pageSize = integer(options.limit ?? 25, "--limit", 100);
+    if (options.status !== undefined)
+        validateStatus(options.status, true);
+    if (options.sort !== undefined && !["title", "priority", "targetDate", "owner"].includes(options.sort))
+        throw new CliError("INVALID_SORT", "--sort must be title|priority|targetDate|owner");
+    if (options.dir !== undefined && !["asc", "desc"].includes(options.dir))
+        throw new CliError("INVALID_DIRECTION", "--dir must be asc|desc");
+    const setup = await selectedProject(ctx, options);
+    const response = object(await ctx.client.request(`/projects/${encodeURIComponent(canonical(setup))}/initiatives`, { query: { page, pageSize, status: options.status, search: options.search, sort: options.sort, dir: options.dir } }), "initiative page");
+    const items = objects(response.items, "initiative items");
+    if (!Number.isSafeInteger(response.total) || response.total < 0 || response.page !== page || response.pageSize !== pageSize || items.length > pageSize || items.some((item) => !positive(item.id) || item.projectId !== setup.project.id))
+        unsupported("Invalid initiative page or foreign initiative");
+    const total = response.total;
+    const offset = (page - 1) * pageSize;
+    if (!Number.isSafeInteger(offset))
+        unsupported("Initiative page offset is invalid");
+    const nextPage = offset + pageSize < total ? page + 1 : null;
+    return { data: { items: publicData(items), total, page, pageSize, nextPage }, meta: { scope: { projectId: setup.project.id, projectRef: canonical(setup) }, limit: pageSize, returned: items.length, completeness: page === 1 && items.length === total ? "complete" : "partial" } };
+}
+async function writeInitiative(ctx, action, identifier, options, actor) {
+    const editing = action === "edit";
+    if (!editing && identifier !== undefined)
+        throw new CliError("CONFLICTING_ARGUMENTS", "initiative create does not accept an ID");
+    let item;
+    let setup;
+    if (editing) {
+        if (identifier === undefined)
+            throw new CliError("INITIATIVE_REQUIRED", "Provide a numeric initiative ID");
+        const id = integer(identifier, "initiative ID");
+        item = initiative(await ctx.client.request(`/initiatives/${id}`), id);
+        setup = await projectFor(ctx, options, item);
+    }
+    else
+        setup = await selectedProject(ctx, options);
+    const body = await fields(ctx, setup, options, actor, item);
+    if (!editing && body.title === undefined)
+        throw new CliError("TITLE_REQUIRED", "Provide --title");
+    if (editing && Object.keys(body).length === 0)
+        throw new CliError("NO_CHANGES", "Provide at least one initiative edit field");
+    if (item)
+        for (const key of Object.keys(body))
+            if (!(key in item))
+                unsupported(`Initiative response is missing ${key}; cannot build a trustworthy diff`);
+    const path = editing ? `/initiatives/${item.id}` : `/projects/${encodeURIComponent(canonical(setup))}/initiatives`;
+    const method = editing ? "PATCH" : "POST";
+    const diff = Object.fromEntries(Object.entries(body).map(([key, value]) => [key, { before: item ? item[key] : null, after: value }]));
+    const data = { action, projectId: setup.project.id, projectRef: canonical(setup), ...(item ? { initiativeId: item.id } : {}), changed: false, diff };
+    if (options.dryRun)
+        return preview(ctx, actor, data, path, body, [], method);
+    let response;
+    try {
+        response = await ctx.client.request(path, { method, body });
+    }
+    catch (error) {
+        return writeFailure(error, data, actor, "initiative");
+    }
+    data.changed = true;
+    if (!editing && record(response) && positive(response.id))
+        data.initiativeId = response.id;
+    if (matches(response, data.initiativeId, setup.project.id, body))
+        return applied(data, actor);
+    if (positive(data.initiativeId)) {
+        try {
+            if (matches(await ctx.client.request(`/initiatives/${data.initiativeId}`), data.initiativeId, setup.project.id, body))
+                return applied(data, actor);
+        }
+        catch { /* The accepted write retains its ID even if verification fails. */ }
+    }
+    return verificationFailed(data, actor, "initiative");
+}
+export async function runInitiative(ctx, action, initiativeId, options) {
+    if (action === "list") {
+        if (initiativeId !== undefined)
+            throw new CliError("CONFLICTING_ARGUMENTS", "initiative list does not accept an ID");
+        return list(ctx, options);
+    }
+    if (action === "view") {
+        if (initiativeId === undefined)
+            throw new CliError("INITIATIVE_REQUIRED", "Provide a numeric initiative ID");
+        const id = integer(initiativeId, "initiative ID");
+        const item = initiative(await ctx.client.request(`/initiatives/${id}`), id);
+        const setup = await projectFor(ctx, options, item);
+        return { data: { initiative: publicData(item), projectRef: canonical(setup) }, meta: { scope: { initiativeId: id, projectId: setup.project.id, projectRef: canonical(setup) } } };
+    }
+    if (action === "create" || action === "edit") {
+        const result = await withWrite(options, (actor) => writeInitiative(ctx, action, initiativeId, options, actor));
+        if (record(result.data)) {
+            const { initiativeId: id, projectId, projectRef: ref } = result.data;
+            result.meta = { ...result.meta, scope: { ...(id !== undefined ? { initiativeId: id } : {}), projectId, projectRef: ref } };
+        }
+        return result;
+    }
+    throw new CliError("INVALID_ARGUMENT", "Unknown initiative action");
+}

package/dist/issues.d.ts

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

package/dist/issues.js

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

package/dist/output.d.ts

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