@aiaiai-pt/manda-cli 0.0.0-stage → 0.1.0

package/dist/commands.js

@@ -0,0 +1,710 @@
+import { randomUUID } from "node:crypto";
+import { api, exitCodeForStatus } from "./client.js";
+import { isJsonMode, printJson, printError, printTable, printKeyValue, readStdin, } from "./output.js";
+function die(status, message, current) {
+    const exit = exitCodeForStatus(status);
+    printError(status, message, exit, current);
+    process.exit(exit);
+}
+async function handleError(res, refetchCurrent) {
+    if (!res.ok) {
+        let current;
+        if (res.status === 409 && refetchCurrent) {
+            try {
+                const fresh = await refetchCurrent();
+                current = fresh;
+            }
+            catch {
+                /* best effort */
+            }
+        }
+        die(res.status, res.message, current);
+    }
+    // TypeScript: this should never be reached
+    throw new Error("unreachable");
+}
+// stdin can feed exactly one flag per invocation: a second "-" would wait on a stream
+// that is already closed and never settle.
+let stdinConsumed = false;
+async function resolveText(value) {
+    if (value !== "-")
+        return value;
+    if (stdinConsumed) {
+        printError(0, "stdin (-) can feed only one flag per call", 1);
+        process.exit(1);
+    }
+    stdinConsumed = true;
+    return (await readStdin()).trim();
+}
+// Fetch current revision for a resource, unless --revision is given
+async function getRevision(config, path, flags) {
+    const explicit = flags["revision"];
+    if (explicit !== undefined)
+        return Number(explicit);
+    const res = await api(config, path);
+    if (!res.ok)
+        die(res.status, res.message);
+    const data = res.data;
+    // submissions have .submission.revision, topics have .topic.revision
+    if (typeof data === "object" && data !== null) {
+        if ("submission" in data)
+            return data.submission.revision;
+        if ("topic" in data)
+            return data.topic.revision;
+        if ("revision" in data)
+            return data.revision;
+    }
+    return 0;
+}
+function refetchSubmission(config, id) {
+    return async () => {
+        const r = await api(config, `/api/agent/v1/submissions/${id}`);
+        return r.ok ? r.data : undefined;
+    };
+}
+function refetchTopic(config, id) {
+    return async () => {
+        const r = await api(config, `/api/agent/v1/topics/${id}`);
+        return r.ok ? r.data : undefined;
+    };
+}
+// --- whoami ---
+export async function whoami(config, flags) {
+    const res = await api(config, "/api/agent/v1/me");
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags)) {
+        printJson(res.data);
+    }
+    else {
+        const d = res.data;
+        const agent = d.agent;
+        printKeyValue([
+            ["email", d.email],
+            ["domain", d.domain],
+            ["agent", agent.name],
+        ]);
+    }
+}
+// --- projects ---
+export async function projects(config, flags) {
+    const res = await api(config, "/api/agent/v1/projects");
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags)) {
+        printJson(res.data);
+    }
+    else {
+        printTable(res.data.projects, [
+            { key: "id", label: "ID", width: 38 },
+            { key: "name", label: "NAME" },
+        ]);
+    }
+}
+// --- inbox ---
+export async function inbox(config, flags) {
+    const query = {};
+    if (flags["project"])
+        query["project_id"] = String(flags["project"]);
+    if (flags["state"])
+        query["review_state"] = String(flags["state"]);
+    if (flags["page"])
+        query["page"] = String(flags["page"]);
+    if (flags["limit"])
+        query["limit"] = String(flags["limit"]);
+    if (flags["q"])
+        query["q"] = String(flags["q"]);
+    let assignee = flags["assignee"] ? String(flags["assignee"]) : undefined;
+    if (assignee === "me") {
+        const meRes = await api(config, "/api/agent/v1/me");
+        if (!meRes.ok)
+            return handleError(meRes);
+        assignee = meRes.data.email;
+    }
+    if (assignee)
+        query["assignee_email"] = assignee;
+    const res = await api(config, "/api/agent/v1/submissions", { query });
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags)) {
+        printJson(res.data);
+    }
+    else {
+        printTable(res.data.submissions, [
+            { key: "id", label: "ID", width: 38 },
+            { key: "type", label: "TYPE", width: 8 },
+            { key: "status", label: "STATUS", width: 14 },
+            { key: "message", label: "MESSAGE" },
+        ]);
+    }
+}
+// --- next ---
+export async function next(config, flags) {
+    const query = {};
+    if (flags["project"])
+        query["project_id"] = String(flags["project"]);
+    const res = await api(config, "/api/agent/v1/next", { query });
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags)) {
+        printJson(res.data);
+    }
+    else {
+        printTable(res.data.items.map((item) => ({
+            ...item,
+            owner: item.assignee_email ?? "unassigned",
+            topic: item.topics.map((t) => t.title).join(", ") || "-",
+        })), [
+            { key: "id", label: "ID", width: 38 },
+            { key: "review_state", label: "STATE", width: 12 },
+            { key: "owner", label: "OWNER", width: 24 },
+            { key: "topic", label: "TOPIC", width: 32 },
+            { key: "message", label: "MESSAGE" },
+        ]);
+    }
+}
+// --- instructions ---
+/** A block for CLAUDE.md or AGENTS.md: the loop a harness runs with manda as its coordination layer. */
+export const INSTRUCTIONS = `## Manda: customer feedback and work coordination
+
+Manda is the ledger of what customers reported and what they have been told. Use the \`manda\`
+CLI (\`npm i -g @aiaiai-pt/manda-cli\`, \`MANDA_TOKEN\` set) as the coordination layer while
+working in this codebase, alone or with a person. Every call prints JSON when piped; exit codes:
+0 ok, 1 usage, 2 auth, 3 conflict (reload and decide again), 4 not found, 5 other.
+
+The loop:
+
+1. \`manda next --json\` lists open reports you own or nobody owns, in priority order. Take the first.
+2. \`manda report show <id> --json\` reads the report and its timeline. \`manda report assign <id> --to me\` takes it
+   (owned reports rank first in \`next\`; an unowned one you are working on will sink below fresh reports), then
+   \`manda report ack <id>\` starts review.
+3. Group it: \`manda topic list --json\` to find the topic it belongs to, then
+   \`manda topic link-report <topic> --report <id>\`; or \`manda topic create --project <project> --title "<customer intent>"\`
+   and \`manda topic transition <topic> plan\` then \`start\` when you begin.
+4. Do the work in the repository. Put \`Manda-Report: <id>\` and \`Manda-Topic: <topic>\` as commit trailers
+   and \`manda topic link-work <topic> --tracker github --issue <pr number> --issue-url <pr url>\` once a PR exists.
+5. Tell the customer only when it is true: \`manda report comment <id> --audience customer --outcome resolved --body "<what changed, in their words>"\`.
+   Internal notes use \`--audience internal\`. Never resolve without a customer-facing explanation.
+6. \`manda topic transition <topic> complete\` when the change is available to customers; \`manda topic announce <topic> --body "<progress>"\` for public progress.
+
+Rules: read before you write (every write checks the revision); do not reprioritise by editing reports, reorder topics
+(\`manda topic reorder\`) with the person who owns the roadmap; a 3 exit means someone else changed it, re-read and decide again.
+`;
+export function instructions() {
+    process.stdout.write(INSTRUCTIONS);
+}
+// --- report ---
+export async function reportShow(config, id, flags) {
+    const res = await api(config, `/api/agent/v1/submissions/${id}`);
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags)) {
+        printJson(res.data);
+    }
+    else {
+        const d = res.data;
+        const s = d.submission;
+        printKeyValue([
+            ["id", s.id],
+            ["type", s.type],
+            ["status", s.status],
+            ["message", s.message],
+            ["revision", s.revision],
+        ]);
+        const updates = d.updates;
+        if (updates && updates.length > 0) {
+            process.stdout.write("\nUpdates:\n");
+            printTable(updates, [
+                { key: "kind", label: "KIND", width: 14 },
+                { key: "author_email", label: "AUTHOR", width: 30 },
+                { key: "body", label: "BODY" },
+            ]);
+        }
+    }
+}
+export async function reportCapture(config, flags) {
+    const projectId = flags["project"];
+    const type = flags["type"];
+    const message = await resolveText(flags["message"]);
+    if (!projectId || !type || !message) {
+        printError(0, "Missing required flag: --project, --type, --message", 1);
+        process.exit(1);
+    }
+    const body = {
+        project_id: String(projectId),
+        type: String(type),
+        message,
+    };
+    if (flags["name"])
+        body.user_name = String(flags["name"]);
+    if (flags["email"])
+        body.user_email = String(flags["email"]);
+    if (flags["source-label"])
+        body.source_label = String(flags["source-label"]);
+    const res = await api(config, "/api/agent/v1/submissions", {
+        method: "POST",
+        body,
+    });
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags)) {
+        printJson(res.data);
+    }
+    else {
+        const d = res.data;
+        process.stdout.write(`Created report ${d.id}\n`);
+    }
+}
+export async function reportAssign(config, id, flags) {
+    let to = flags["to"];
+    if (to === undefined) {
+        printError(0, "Missing required flag: --to", 1);
+        process.exit(1);
+    }
+    if (to === "me") {
+        const meRes = await api(config, "/api/agent/v1/me");
+        if (!meRes.ok)
+            return handleError(meRes);
+        to = meRes.data.email;
+    }
+    else if (to === "none") {
+        to = undefined; // null means unassign
+    }
+    const revision = await getRevision(config, `/api/agent/v1/submissions/${id}`, flags);
+    const body = {
+        revision,
+        action: "assign",
+        assignee_email: to === undefined ? null : String(to),
+    };
+    const res = await api(config, `/api/agent/v1/submissions/${id}`, {
+        method: "PATCH",
+        body,
+    });
+    if (!res.ok)
+        return handleError(res, refetchSubmission(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Assigned ${id}\n`);
+}
+export async function reportAck(config, id, flags) {
+    const revision = await getRevision(config, `/api/agent/v1/submissions/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/submissions/${id}`, {
+        method: "PATCH",
+        body: { revision, action: "acknowledge" },
+    });
+    if (!res.ok)
+        return handleError(res, refetchSubmission(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Acknowledged ${id}\n`);
+}
+export async function reportResolve(config, id, flags) {
+    const resolution = await resolveText(flags["resolution"]);
+    if (!resolution) {
+        printError(0, "Missing required flag: --resolution", 1);
+        process.exit(1);
+    }
+    const revision = await getRevision(config, `/api/agent/v1/submissions/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/submissions/${id}`, {
+        method: "PATCH",
+        body: { revision, action: "resolve", resolution },
+    });
+    if (!res.ok)
+        return handleError(res, refetchSubmission(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Resolved ${id}\n`);
+}
+export async function reportReopen(config, id, flags) {
+    const revision = await getRevision(config, `/api/agent/v1/submissions/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/submissions/${id}`, {
+        method: "PATCH",
+        body: { revision, action: "reopen" },
+    });
+    if (!res.ok)
+        return handleError(res, refetchSubmission(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Reopened ${id}\n`);
+}
+export async function reportLink(config, id, flags) {
+    const url = flags["work-url"];
+    const none = flags["none"];
+    if (!url && !none) {
+        printError(0, "Missing required flag: --work-url or --none", 1);
+        process.exit(1);
+    }
+    const revision = await getRevision(config, `/api/agent/v1/submissions/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/submissions/${id}`, {
+        method: "PATCH",
+        body: {
+            revision,
+            action: "link",
+            manual_work_url: none ? null : String(url),
+        },
+    });
+    if (!res.ok)
+        return handleError(res, refetchSubmission(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Linked ${id}\n`);
+}
+export async function reportComment(config, id, flags) {
+    const body = await resolveText(flags["body"]);
+    if (!body) {
+        printError(0, "Missing required flag: --body", 1);
+        process.exit(1);
+    }
+    const requestId = flags["request-id"]
+        ? String(flags["request-id"])
+        : randomUUID();
+    const revision = await getRevision(config, `/api/agent/v1/submissions/${id}`, flags);
+    const payload = {
+        revision,
+        audience: flags["audience"] || "internal",
+        body,
+        request_id: requestId,
+    };
+    if (flags["outcome"])
+        payload.outcome = String(flags["outcome"]);
+    const res = await api(config, `/api/agent/v1/submissions/${id}/updates`, {
+        method: "POST",
+        body: payload,
+    });
+    if (!res.ok)
+        return handleError(res, refetchSubmission(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Comment added to ${id}\n`);
+}
+// --- topic ---
+export async function topicList(config, flags) {
+    const query = {};
+    if (flags["project"])
+        query["project_id"] = String(flags["project"]);
+    const res = await api(config, "/api/agent/v1/topics", { query });
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags)) {
+        printJson(res.data);
+    }
+    else {
+        printTable(res.data.topics, [
+            { key: "id", label: "ID", width: 38 },
+            { key: "state", label: "STATE", width: 14 },
+            { key: "title", label: "TITLE" },
+        ]);
+    }
+}
+export async function topicShow(config, id, flags) {
+    const res = await api(config, `/api/agent/v1/topics/${id}`);
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags)) {
+        printJson(res.data);
+    }
+    else {
+        const d = res.data;
+        const t = d.topic;
+        printKeyValue([
+            ["id", t.id],
+            ["title", t.title],
+            ["state", t.state],
+            ["revision", t.revision],
+        ]);
+    }
+}
+export async function topicCreate(config, flags) {
+    const projectId = flags["project"];
+    const title = await resolveText(flags["title"]);
+    if (!projectId || !title) {
+        printError(0, "Missing required flag: --project, --title", 1);
+        process.exit(1);
+    }
+    const body = {
+        project_id: String(projectId),
+        title,
+    };
+    const description = await resolveText(flags["description"]);
+    if (description)
+        body.description = description;
+    const res = await api(config, "/api/agent/v1/topics", {
+        method: "POST",
+        body,
+    });
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags)) {
+        printJson(res.data);
+    }
+    else {
+        const d = res.data;
+        process.stdout.write(`Created topic ${d.id}\n`);
+    }
+}
+export async function topicTransition(config, id, event, flags) {
+    const revision = await getRevision(config, `/api/agent/v1/topics/${id}`, flags);
+    const body = {
+        revision,
+        action: "transition",
+        event,
+    };
+    const text = await resolveText(flags["body"]);
+    if (text)
+        body.body = text;
+    const res = await api(config, `/api/agent/v1/topics/${id}`, {
+        method: "PATCH",
+        body,
+    });
+    if (!res.ok)
+        return handleError(res, refetchTopic(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Transitioned ${id} via ${event}\n`);
+}
+export async function topicNote(config, id, flags) {
+    const body = await resolveText(flags["body"]);
+    if (!body) {
+        printError(0, "Missing required flag: --body", 1);
+        process.exit(1);
+    }
+    const revision = await getRevision(config, `/api/agent/v1/topics/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/topics/${id}`, {
+        method: "PATCH",
+        body: { revision, action: "note", body },
+    });
+    if (!res.ok)
+        return handleError(res, refetchTopic(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Note added to ${id}\n`);
+}
+export async function topicEdit(config, id, flags) {
+    const title = await resolveText(flags["title"]);
+    const description = await resolveText(flags["description"]);
+    if (!title || description === undefined) {
+        printError(0, "Missing required flag: --title, --description", 1);
+        process.exit(1);
+    }
+    const revision = await getRevision(config, `/api/agent/v1/topics/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/topics/${id}`, {
+        method: "PATCH",
+        body: { revision, action: "edit", title, description: description || "" },
+    });
+    if (!res.ok)
+        return handleError(res, refetchTopic(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Edited ${id}\n`);
+}
+export async function topicLinkReport(config, id, flags) {
+    const reportId = flags["report"];
+    if (!reportId) {
+        printError(0, "Missing required flag: --report", 1);
+        process.exit(1);
+    }
+    const revision = await getRevision(config, `/api/agent/v1/topics/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/topics/${id}`, {
+        method: "PATCH",
+        body: { revision, action: "link_report", submission_id: String(reportId) },
+    });
+    if (!res.ok)
+        return handleError(res, refetchTopic(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Linked report ${reportId} to ${id}\n`);
+}
+export async function topicUnlinkReport(config, id, flags) {
+    const reportId = flags["report"];
+    if (!reportId) {
+        printError(0, "Missing required flag: --report", 1);
+        process.exit(1);
+    }
+    const revision = await getRevision(config, `/api/agent/v1/topics/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/topics/${id}`, {
+        method: "PATCH",
+        body: {
+            revision,
+            action: "unlink_report",
+            submission_id: String(reportId),
+        },
+    });
+    if (!res.ok)
+        return handleError(res, refetchTopic(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Unlinked report ${reportId} from ${id}\n`);
+}
+export async function topicLinkWork(config, id, flags) {
+    const tracker = flags["tracker"];
+    const issue = flags["issue"];
+    const url = flags["issue-url"];
+    if (!tracker || !issue || !url) {
+        printError(0, "Missing required flag: --tracker, --issue, --issue-url", 1);
+        process.exit(1);
+    }
+    const revision = await getRevision(config, `/api/agent/v1/topics/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/topics/${id}`, {
+        method: "PATCH",
+        body: {
+            revision,
+            action: "link_work",
+            tracker: String(tracker),
+            issue_id: String(issue),
+            issue_url: String(url),
+        },
+    });
+    if (!res.ok)
+        return handleError(res, refetchTopic(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Linked work to ${id}\n`);
+}
+export async function topicUnlinkWork(config, id, flags) {
+    const tracker = flags["tracker"];
+    const issue = flags["issue"];
+    if (!tracker || !issue) {
+        printError(0, "Missing required flag: --tracker, --issue", 1);
+        process.exit(1);
+    }
+    const revision = await getRevision(config, `/api/agent/v1/topics/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/topics/${id}`, {
+        method: "PATCH",
+        body: {
+            revision,
+            action: "unlink_work",
+            tracker: String(tracker),
+            issue_id: String(issue),
+        },
+    });
+    if (!res.ok)
+        return handleError(res, refetchTopic(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Unlinked work from ${id}\n`);
+}
+export async function topicPublish(config, id, flags) {
+    const revision = await getRevision(config, `/api/agent/v1/topics/${id}`, flags);
+    const body = { revision, action: "publish" };
+    const publicTitle = await resolveText(flags["public-title"]);
+    const publicSummary = await resolveText(flags["public-summary"]);
+    if (publicTitle)
+        body.public_title = publicTitle;
+    if (publicSummary)
+        body.public_summary = publicSummary;
+    const res = await api(config, `/api/agent/v1/topics/${id}`, {
+        method: "PATCH",
+        body,
+    });
+    if (!res.ok)
+        return handleError(res, refetchTopic(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Published ${id}\n`);
+}
+export async function topicUnpublish(config, id, flags) {
+    const revision = await getRevision(config, `/api/agent/v1/topics/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/topics/${id}`, {
+        method: "PATCH",
+        body: { revision, action: "unpublish" },
+    });
+    if (!res.ok)
+        return handleError(res, refetchTopic(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Unpublished ${id}\n`);
+}
+export async function topicEditPublic(config, id, flags) {
+    const publicTitle = await resolveText(flags["public-title"]);
+    const publicSummary = await resolveText(flags["public-summary"]);
+    if (!publicTitle || publicSummary === undefined) {
+        printError(0, "Missing required flag: --public-title, --public-summary", 1);
+        process.exit(1);
+    }
+    const revision = await getRevision(config, `/api/agent/v1/topics/${id}`, flags);
+    const res = await api(config, `/api/agent/v1/topics/${id}`, {
+        method: "PATCH",
+        body: {
+            revision,
+            action: "edit_public",
+            public_title: publicTitle,
+            public_summary: publicSummary || "",
+        },
+    });
+    if (!res.ok)
+        return handleError(res, refetchTopic(config, id));
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Edited public view of ${id}\n`);
+}
+export async function topicReorder(config, topicIds, flags) {
+    const projectId = flags["project"];
+    if (!projectId) {
+        printError(0, "Missing required flag: --project", 1);
+        process.exit(1);
+    }
+    if (topicIds.length === 0) {
+        printError(0, "At least one topic ID is required", 1);
+        process.exit(1);
+    }
+    const res = await api(config, "/api/agent/v1/topics", {
+        method: "PATCH",
+        body: { project_id: String(projectId), topic_ids: topicIds },
+    });
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Reordered ${topicIds.length} topics\n`);
+}
+export async function topicAnnounce(config, id, flags) {
+    const body = await resolveText(flags["body"]);
+    if (!body) {
+        printError(0, "Missing required flag: --body", 1);
+        process.exit(1);
+    }
+    const res = await api(config, `/api/agent/v1/topics/${id}/announcements`, {
+        method: "POST",
+        body: { body },
+    });
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Announcement added to ${id}\n`);
+}
+export async function topicUnannounce(config, id, flags) {
+    const announcementId = flags["announcement"];
+    if (!announcementId) {
+        printError(0, "Missing required flag: --announcement", 1);
+        process.exit(1);
+    }
+    const res = await api(config, `/api/agent/v1/topics/${id}/announcements`, {
+        method: "DELETE",
+        body: { announcement_id: announcementId },
+    });
+    if (!res.ok)
+        return handleError(res);
+    if (isJsonMode(flags))
+        printJson(res.data);
+    else
+        process.stdout.write(`Announcement ${announcementId} removed from ${id}\n`);
+}