@floh-solutions/pharos-cli 0.1.0

package/dist/commands/comment.js

@@ -0,0 +1,236 @@
+import { emit, usageError } from "../output.js";
+import { approve } from "../session.js";
+import { describeTarget, parseTarget } from "../target.js";
+/**
+ * `pharos comment …` — the discussion, on either surface.
+ *
+ * **Wiki comments exist in no other tool.** The Azure DevOps MCP server ships
+ * none of these verbs for a wiki page — not list, not add, not edit, not
+ * delete, not react — verified by enumerating its tools. For work item
+ * comments it has add and update only, so delete and reactions are also
+ * reachable from nowhere else.
+ *
+ * The two surfaces behave differently in ways that would bite a caller writing
+ * this by hand, and each difference is handled on its own side rather than
+ * assumed away:
+ *
+ * | | work item | wiki page |
+ * |---|---|---|
+ * | keyed on | the work item id | the page's NUMERIC id, not its path |
+ * | `includeDeleted` | honoured | ignored — deleted comments come back regardless |
+ * | second delete | 404 | 500 |
+ * | reactions api-version | `7.2-preview.1` | `7.1-preview.1` |
+ *
+ * Both are `swallowed`/`filtered`/`pinned` inside `ado-core`; the table is here
+ * because the temptation when reading this file is to unify the two branches.
+ */
+const REACTIONS = [
+    "like",
+    "dislike",
+    "heart",
+    "hooray",
+    "smile",
+    "confused",
+];
+export async function runComment(io, session, positionals, input) {
+    const verb = positionals[0];
+    if (verb === undefined) {
+        throw usageError("`pharos comment <list|add|edit|delete|react|unreact> <target> …`.");
+    }
+    const rawTarget = positionals[1];
+    if (rawTarget === undefined) {
+        throw usageError(`Which thing? \`pharos comment ${verb} <target>\` — a work item id (210) or a wiki page `
+            + "path (/Plans/Foo).");
+    }
+    const target = parseTarget(rawTarget);
+    const rest = positionals.slice(2);
+    switch (verb) {
+        case "list":
+            return list(io, session, target);
+        case "add":
+            return add(io, session, target, textFrom(rest[0], input.text));
+        case "edit":
+            return edit(io, session, target, commentId(rest[0]), textFrom(rest[1], input.text));
+        case "delete":
+            return remove(io, session, target, commentId(rest[0]));
+        case "react":
+            return react(io, session, target, commentId(rest[0]), reactionType(rest[1]), true);
+        case "unreact":
+            return react(io, session, target, commentId(rest[0]), reactionType(rest[1]), false);
+        case "reactors":
+            return reactors(io, session, target, commentId(rest[0]), reactionType(rest[1]));
+        default:
+            throw usageError(`Unknown comment verb "${verb}". Try list, add, edit, delete, react, unreact or reactors.`);
+    }
+}
+async function list(io, session, target) {
+    if (target.kind === "workItem") {
+        const comments = await session.client.comments.listAll(target.id, { expand: "all" });
+        return emit(io, comments.map((comment) => ({
+            id: comment.id,
+            text: comment.text,
+            createdBy: comment.createdBy?.displayName,
+            createdDate: comment.createdDate,
+            modifiedDate: comment.modifiedDate,
+            version: comment.version,
+        })));
+    }
+    const page = await wikiPage(session, target.path);
+    // Already filtered of deleted comments — see WikiApi.listComments. Counting
+    // the array is correct; the response's totalCount is not.
+    const comments = await session.wiki.listComments(page.wiki, page.pageId);
+    return emit(io, comments.map((comment) => ({
+        id: comment.id,
+        text: comment.text,
+        createdBy: comment.createdBy?.displayName,
+        createdDate: comment.createdDate,
+        modifiedDate: comment.modifiedDate,
+        version: comment.version,
+        reactions: comment.reactions?.map((reaction) => ({
+            type: reaction.type,
+            count: reaction.count,
+        })),
+    })));
+}
+async function add(io, session, target, text) {
+    if (target.kind === "workItem") {
+        const comment = await session.client.comments.add(target.id, text);
+        return emit(io, { applied: true, target: describeTarget(target), commentId: comment.id });
+    }
+    const page = await wikiPage(session, target.path);
+    const comment = await session.wiki.addComment(page.wiki, page.pageId, text);
+    return emit(io, {
+        applied: true,
+        target: describeTarget(target),
+        pageId: page.pageId,
+        commentId: comment.id,
+    });
+}
+async function edit(io, session, target, id, text) {
+    if (target.kind === "workItem") {
+        const comment = await session.client.comments.update(target.id, id, text);
+        return emit(io, {
+            applied: true,
+            target: describeTarget(target),
+            commentId: comment.id,
+            version: comment.version,
+        });
+    }
+    const page = await wikiPage(session, target.path);
+    const comment = await session.wiki.editComment(page.wiki, page.pageId, id, text);
+    return emit(io, {
+        applied: true,
+        target: describeTarget(target),
+        commentId: comment.id,
+        version: comment.version,
+    });
+}
+async function remove(io, session, target, id) {
+    const stop = approve(io, session, {
+        what: `delete comment ${id} on ${describeTarget(target)}`,
+        would: { action: "deleteComment", target: describeTarget(target), commentId: id },
+    });
+    if (stop !== undefined)
+        return stop;
+    if (target.kind === "workItem") {
+        await session.client.comments.delete(target.id, id);
+    }
+    else {
+        const page = await wikiPage(session, target.path);
+        await session.wiki.deleteComment(page.wiki, page.pageId, id);
+    }
+    // Both surfaces treat "already gone" as done — a 404 on one and a 500 on the
+    // other — so this is true whether or not the comment was there to start with.
+    return emit(io, { applied: true, action: "deleted", target: describeTarget(target), commentId: id });
+}
+async function react(io, session, target, id, type, on) {
+    if (target.kind === "workItem") {
+        const reaction = on
+            ? await session.client.comments.react(target.id, id, type)
+            : await session.client.comments.unreact(target.id, id, type);
+        return emit(io, {
+            applied: true,
+            target: describeTarget(target),
+            commentId: id,
+            type,
+            count: reaction.count,
+            isCurrentUserEngaged: reaction.isCurrentUserEngaged,
+        });
+    }
+    const page = await wikiPage(session, target.path);
+    if (!on) {
+        await session.wiki.unreact(page.wiki, page.pageId, id, type);
+        return emit(io, { applied: true, target: describeTarget(target), commentId: id, type, count: 0 });
+    }
+    const reaction = await session.wiki.react(page.wiki, page.pageId, id, type);
+    return emit(io, {
+        applied: true,
+        target: describeTarget(target),
+        commentId: id,
+        type,
+        count: reaction.count,
+        isCurrentUserEngaged: reaction.isCurrentUserEngaged,
+    });
+}
+/** A count is not a name — "three people liked this" needs this second call. */
+async function reactors(io, session, target, id, type) {
+    const identities = target.kind === "workItem"
+        ? await session.client.comments.reactors(target.id, id, type)
+        : await (async () => {
+            const page = await wikiPage(session, target.path);
+            return session.wiki.reactors(page.wiki, page.pageId, id, type);
+        })();
+    return emit(io, identities.map((identity) => ({
+        displayName: identity.displayName,
+        uniqueName: identity.uniqueName,
+    })));
+}
+/**
+ * A wiki page path becomes the numeric id the comment routes need.
+ *
+ * The single-page GET carries the id, so this is one call and not two — worth
+ * knowing, because the page-TREE endpoint does not carry ids and the obvious
+ * route from a path to an id looks like it goes through there.
+ */
+async function wikiPage(session, path) {
+    const wiki = await session.wikiIdentifier();
+    const page = await session.wiki.readPage(wiki, path);
+    if (page.page.id === undefined) {
+        throw usageError(`The wiki page ${path} has no id, so its comments cannot be addressed.`);
+    }
+    return { wiki, pageId: page.page.id };
+}
+function commentId(raw) {
+    if (raw === undefined || !/^\d+$/.test(raw)) {
+        throw usageError(`Which comment? Expected a comment id, got ${raw === undefined ? "nothing" : `"${raw}"`}.`);
+    }
+    return Number(raw);
+}
+function reactionType(raw) {
+    if (raw === undefined) {
+        throw usageError(`Which reaction? One of: ${REACTIONS.join(", ")}.`);
+    }
+    const found = REACTIONS.find((type) => type === raw);
+    if (found === undefined) {
+        throw usageError(`"${raw}" is not a reaction. One of: ${REACTIONS.join(", ")}.`, {
+            reactions: REACTIONS,
+        });
+    }
+    return found;
+}
+/**
+ * Comment text, from wherever it came.
+ *
+ * A positional wins over `--text`/`--file`/`--stdin` only if it is there;
+ * otherwise the flag content is used. Long comments — a plan, a review — do not
+ * belong on a command line, and an agent shelling out with an unescaped
+ * multi-line string is a mangled comment at best.
+ */
+function textFrom(positional, provided) {
+    const text = positional ?? provided;
+    if (text === undefined || text.trim() === "") {
+        throw usageError("No comment text. Pass it as an argument, or use --text/--file/--stdin for anything long.");
+    }
+    return text;
+}
+//# sourceMappingURL=comment.js.map

package/dist/commands/comment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"comment.js","sourceRoot":"","sources":["../../src/commands/comment.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,IAAI,EAAE,UAAU,EAA0B,MAAM,cAAc,CAAC;AACxE,OAAO,EAAE,OAAO,EAAgB,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,cAAc,EAAE,WAAW,EAAe,MAAM,cAAc,CAAC;AAExE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,MAAM,SAAS,GAA+B;IAC5C,MAAM;IACN,SAAS;IACT,OAAO;IACP,QAAQ;IACR,OAAO;IACP,UAAU;CACX,CAAC;AAEF,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,EAAM,EACN,OAAgB,EAChB,WAA8B,EAC9B,KAAoC;IAEpC,MAAM,IAAI,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,MAAM,UAAU,CAAC,mEAAmE,CAAC,CAAC;IACxF,CAAC;IAED,MAAM,SAAS,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;IACjC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,MAAM,UAAU,CACd,iCAAiC,IAAI,oDAAoD;cACrF,oBAAoB,CACzB,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAElC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QACnC,KAAK,KAAK;YACR,OAAO,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACjE,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACtF,KAAK,QAAQ;YACX,OAAO,MAAM,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACzD,KAAK,OAAO;YACV,OAAO,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;QACrF,KAAK,SAAS;YACZ,OAAO,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QACtF,KAAK,UAAU;YACb,OAAO,QAAQ,CAAC,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAClF;YACE,MAAM,UAAU,CACd,yBAAyB,IAAI,6DAA6D,CAC3F,CAAC;IACN,CAAC;AACH,CAAC;AAED,KAAK,UAAU,IAAI,CAAC,EAAM,EAAE,OAAgB,EAAE,MAAc;IAC1D,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QACrF,OAAO,IAAI,CACT,EAAE,EACF,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACzB,EAAE,EAAE,OAAO,CAAC,EAAE;YACd,IAAI,EAAE,OAAO,CAAC,IAAI;YAClB,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,WAAW;YACzC,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC,CACJ,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAClD,4EAA4E;IAC5E,0DAA0D;IAC1D,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IACzE,OAAO,IAAI,CACT,EAAE,EACF,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;QACzB,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,WAAW;QACzC,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YAC/C,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,KAAK,EAAE,QAAQ,CAAC,KAAK;SACtB,CAAC,CAAC;KACJ,CAAC,CAAC,CACJ,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,GAAG,CAChB,EAAM,EACN,OAAgB,EAChB,MAAc,EACd,IAAY;IAEZ,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACnE,OAAO,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5F,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC5E,OAAO,IAAI,CAAC,EAAE,EAAE;QACd,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC;QAC9B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,SAAS,EAAE,OAAO,CAAC,EAAE;KACtB,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,IAAI,CACjB,EAAM,EACN,OAAgB,EAChB,MAAc,EACd,EAAU,EACV,IAAY;IAEZ,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QAC1E,OAAO,IAAI,CAAC,EAAE,EAAE;YACd,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC;YAC9B,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,OAAO,EAAE,OAAO,CAAC,OAAO;SACzB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;IACjF,OAAO,IAAI,CAAC,EAAE,EAAE;QACd,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC;QAC9B,SAAS,EAAE,OAAO,CAAC,EAAE;QACrB,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;AACL,CAAC;AAED,KAAK,UAAU,MAAM,CAAC,EAAM,EAAE,OAAgB,EAAE,MAAc,EAAE,EAAU;IACxE,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,EAAE,OAAO,EAAE;QAChC,IAAI,EAAE,kBAAkB,EAAE,OAAO,cAAc,CAAC,MAAM,CAAC,EAAE;QACzD,KAAK,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE;KAClF,CAAC,CAAC;IACH,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAEpC,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;IACtD,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QAClD,MAAM,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,6EAA6E;IAC7E,8EAA8E;IAC9E,OAAO,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,CAAC,CAAC;AACvG,CAAC;AAED,KAAK,UAAU,KAAK,CAClB,EAAM,EACN,OAAgB,EAChB,MAAc,EACd,EAAU,EACV,IAAqB,EACrB,EAAW;IAEX,IAAI,MAAM,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QAC/B,MAAM,QAAQ,GAAG,EAAE;YACjB,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC;YAC1D,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QAC/D,OAAO,IAAI,CAAC,EAAE,EAAE;YACd,OAAO,EAAE,IAAI;YACb,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC;YAC9B,SAAS,EAAE,EAAE;YACb,IAAI;YACJ,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,oBAAoB,EAAE,QAAQ,CAAC,oBAAoB;SACpD,CAAC,CAAC;IACL,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;IAClD,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,MAAM,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC,CAAC;IACpG,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;IAC5E,OAAO,IAAI,CAAC,EAAE,EAAE;QACd,OAAO,EAAE,IAAI;QACb,MAAM,EAAE,cAAc,CAAC,MAAM,CAAC;QAC9B,SAAS,EAAE,EAAE;QACb,IAAI;QACJ,KAAK,EAAE,QAAQ,CAAC,KAAK;QACrB,oBAAoB,EAAE,QAAQ,CAAC,oBAAoB;KACpD,CAAC,CAAC;AACL,CAAC;AAED,gFAAgF;AAChF,KAAK,UAAU,QAAQ,CACrB,EAAM,EACN,OAAgB,EAChB,MAAc,EACd,EAAU,EACV,IAAqB;IAErB,MAAM,UAAU,GACd,MAAM,CAAC,IAAI,KAAK,UAAU;QACxB,CAAC,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,CAAC;QAC7D,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE;YAChB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;YAClD,OAAO,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,IAAI,CAAC,CAAC;QACjE,CAAC,CAAC,EAAE,CAAC;IAEX,OAAO,IAAI,CACT,EAAE,EACF,UAAU,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAC5B,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,UAAU,EAAE,QAAQ,CAAC,UAAU;KAChC,CAAC,CAAC,CACJ,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,QAAQ,CACrB,OAAgB,EAChB,IAAY;IAEZ,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,CAAC;IAC5C,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACrD,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;QAC/B,MAAM,UAAU,CAAC,iBAAiB,IAAI,kDAAkD,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;AACxC,CAAC;AAED,SAAS,SAAS,CAAC,GAAuB;IACxC,IAAI,GAAG,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5C,MAAM,UAAU,CAAC,6CAA6C,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,GAAG,CAAC,CAAC;IAC/G,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;AACrB,CAAC;AAED,SAAS,YAAY,CAAC,GAAuB;IAC3C,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,MAAM,UAAU,CAAC,2BAA2B,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC;IACrD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,UAAU,CAAC,IAAI,GAAG,gCAAgC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;YAC/E,SAAS,EAAE,SAAS;SACrB,CAAC,CAAC;IACL,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,QAAQ,CAAC,UAA8B,EAAE,QAA4B;IAC5E,MAAM,IAAI,GAAG,UAAU,IAAI,QAAQ,CAAC;IACpC,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC7C,MAAM,UAAU,CACd,0FAA0F,CAC3F,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/commands/task.d.ts

@@ -0,0 +1,23 @@
+import { type ExitCode, type Io } from "../output.js";
+import type { Session } from "../session.js";
+/**
+ * `pharos task <id>` — everything about one work item, in one call.
+ *
+ * **This is the command the CLI exists for.** Everything else here wraps an
+ * endpoint; this one answers the question an agent actually starts with — *what
+ * am I being asked to do, and what do I already know about it?*
+ *
+ * Assembled by hand it is five or six round trips across two tools, and one of
+ * them is impossible: the Azure DevOps MCP server has no wiki comment support
+ * at all. So the plan a colleague wrote on a linked wiki page, the discussion
+ * under it, and the dependency saying this cannot start yet are each a separate
+ * thing to remember to fetch — and anything forgotten is context an agent
+ * silently works without.
+ */
+export interface TaskOptions {
+    wikiContent: boolean;
+    wikiComments: boolean;
+    relatedTitles: boolean;
+}
+export declare function runTask(io: Io, session: Session, positionals: readonly string[], options: TaskOptions): Promise<ExitCode>;
+//# sourceMappingURL=task.d.ts.map

package/dist/commands/task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.d.ts","sourceRoot":"","sources":["../../src/commands/task.ts"],"names":[],"mappings":"AAEA,OAAO,EAA8B,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,WAAW;IAC1B,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,wBAAsB,OAAO,CAC3B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,QAAQ,CAAC,CAcnB"}

package/dist/commands/task.js

@@ -0,0 +1,112 @@
+import { taskContext } from "@floh-solutions/ado-core";
+import { emit, emitText, usageError } from "../output.js";
+export async function runTask(io, session, positionals, options) {
+    const raw = positionals[0];
+    if (raw === undefined)
+        throw usageError("Which work item? `pharos task <id>`.");
+    if (!/^\d+$/.test(raw)) {
+        throw usageError(`"${raw}" is not a work item id.`, { given: raw });
+    }
+    const context = await taskContext(session.client, Number(raw), {
+        includeWikiContent: options.wikiContent,
+        includeWikiComments: options.wikiComments,
+        includeRelatedTitles: options.relatedTitles,
+    });
+    return session.pretty ? emitText(io, render(context)) : emit(io, context);
+}
+/**
+ * The human rendering.
+ *
+ * Ordered the way somebody picking the work up reads it: what it is, then what
+ * was said about it, then what it depends on, then the plan. `problems` is
+ * LAST and never omitted — a context with a silent hole in it is worse than no
+ * context, because it is reasoned from confidently.
+ */
+function render(context) {
+    const field = (name) => {
+        const value = context.fields[name];
+        return typeof value === "string" && value.trim() !== "" ? value : undefined;
+    };
+    const identity = (name) => {
+        const value = context.fields[name];
+        if (typeof value === "string")
+            return value;
+        if (typeof value === "object" && value !== null) {
+            const display = value.displayName;
+            if (typeof display === "string")
+                return display;
+        }
+        return undefined;
+    };
+    const lines = [];
+    const type = field("System.WorkItemType") ?? "Work item";
+    const state = field("System.State") ?? "?";
+    lines.push(`#${context.id} · ${type} · ${state} — ${field("System.Title") ?? "(untitled)"}`);
+    const meta = [
+        ["assigned", identity("System.AssignedTo")],
+        ["area", field("System.AreaPath")],
+        ["iteration", field("System.IterationPath")],
+        ["tags", field("System.Tags")],
+    ].filter((pair) => pair[1] !== undefined);
+    if (meta.length > 0) {
+        lines.push(meta.map(([key, value]) => `${key}: ${value}`).join("   "));
+    }
+    const description = field("System.Description");
+    if (description !== undefined)
+        lines.push("", "## Description", "", description);
+    lines.push("", `## Comments (${context.comments.length})`);
+    if (context.comments.length === 0)
+        lines.push("", "none");
+    for (const comment of context.comments) {
+        lines.push("", `— ${comment.createdBy ?? "someone"}${comment.createdDate === undefined ? "" : ` · ${comment.createdDate}`} · #${comment.id}`, comment.text);
+    }
+    if (context.related.length > 0) {
+        lines.push("", `## Related (${context.related.length})`);
+        for (const item of context.related) {
+            const suffix = item.title === undefined ? " (unreadable from here)" : ` ${item.title}`;
+            lines.push(`  ${shortRel(item.rel).padEnd(12)} #${String(item.id).padEnd(6)} ${(item.state ?? "").padEnd(12)}${suffix}`);
+        }
+    }
+    if (context.attachments.length > 0) {
+        lines.push("", `## Attachments (${context.attachments.length})`);
+        for (const attachment of context.attachments) {
+            const size = attachment.size === undefined ? "" : ` (${attachment.size} bytes)`;
+            lines.push(`  ${attachment.name}${size}`);
+        }
+    }
+    for (const page of context.wikiPages) {
+        lines.push("", `## Wiki: ${page.path}  [${page.wikiName}]`);
+        if (page.problem !== undefined) {
+            lines.push("", `could not be read: ${page.problem}`);
+            continue;
+        }
+        if (page.content !== undefined)
+            lines.push("", page.content);
+        if (page.comments !== undefined && page.comments.length > 0) {
+            lines.push("", `### Page comments (${page.comments.length})`);
+            for (const comment of page.comments) {
+                lines.push("", `— ${comment.createdBy?.displayName ?? "someone"} · #${comment.id}`, comment.text);
+            }
+        }
+    }
+    if (context.problems.length > 0) {
+        lines.push("", "## Problems — this context is INCOMPLETE");
+        for (const problem of context.problems)
+            lines.push(`  - ${problem}`);
+    }
+    return lines.join("\n");
+}
+/** `System.LinkTypes.Hierarchy-Forward` reads as `Child`. */
+function shortRel(rel) {
+    const known = {
+        "System.LinkTypes.Hierarchy-Forward": "Child",
+        "System.LinkTypes.Hierarchy-Reverse": "Parent",
+        "System.LinkTypes.Dependency-Forward": "Successor",
+        "System.LinkTypes.Dependency-Reverse": "Predecessor",
+        "System.LinkTypes.Related": "Related",
+        "System.LinkTypes.Duplicate-Forward": "Duplicate",
+        "System.LinkTypes.Duplicate-Reverse": "Duplicated by",
+    };
+    return known[rel] ?? rel;
+}
+//# sourceMappingURL=task.js.map

package/dist/commands/task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"task.js","sourceRoot":"","sources":["../../src/commands/task.ts"],"names":[],"mappings":"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"}

package/dist/commands/wiki.d.ts

@@ -0,0 +1,20 @@
+import { type ExitCode, type Io } from "../output.js";
+import { type Session } from "../session.js";
+/**
+ * `pharos wiki …` — the pages.
+ *
+ * Two things here are not thin wrappers, because a thin wrapper would be wrong:
+ *
+ *   - **`write` always reads first.** The page version arrives only as an ETag,
+ *     and a save without `If-Match` overwrites whatever a colleague saved with
+ *     nothing anywhere reporting it. The read is also how this knows whether it
+ *     is creating or replacing, which is what decides whether `--yes` is needed.
+ *   - **`tree` joins two calls.** The page-tree endpoint returns structure and
+ *     no ids; the flat list returns ids and no structure. Comments are keyed on
+ *     the id, so anything that wants to walk a wiki and then talk about a page
+ *     needs both — done once here rather than by every caller.
+ */
+export declare function runWiki(io: Io, session: Session, positionals: readonly string[], input: {
+    content?: string | undefined;
+}): Promise<ExitCode>;
+//# sourceMappingURL=wiki.d.ts.map

package/dist/commands/wiki.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki.d.ts","sourceRoot":"","sources":["../../src/commands/wiki.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;;;;;;;;;GAaG;AAEH,wBAAsB,OAAO,CAC3B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACtC,OAAO,CAAC,QAAQ,CAAC,CAoBnB"}

package/dist/commands/wiki.js

@@ -0,0 +1,163 @@
+import { AdoNotFoundError } from "@floh-solutions/ado-core";
+import { emit, usageError } from "../output.js";
+import { approve } from "../session.js";
+/**
+ * `pharos wiki …` — the pages.
+ *
+ * Two things here are not thin wrappers, because a thin wrapper would be wrong:
+ *
+ *   - **`write` always reads first.** The page version arrives only as an ETag,
+ *     and a save without `If-Match` overwrites whatever a colleague saved with
+ *     nothing anywhere reporting it. The read is also how this knows whether it
+ *     is creating or replacing, which is what decides whether `--yes` is needed.
+ *   - **`tree` joins two calls.** The page-tree endpoint returns structure and
+ *     no ids; the flat list returns ids and no structure. Comments are keyed on
+ *     the id, so anything that wants to walk a wiki and then talk about a page
+ *     needs both — done once here rather than by every caller.
+ */
+export async function runWiki(io, session, positionals, input) {
+    const verb = positionals[0];
+    const rest = positionals.slice(1);
+    switch (verb) {
+        case "list":
+            return listWikis(io, session);
+        case "tree":
+            return tree(io, session);
+        case "read":
+            return read(io, session, rest);
+        case "write":
+            return write(io, session, rest, input.content);
+        case "delete":
+            return remove(io, session, rest);
+        case undefined:
+            throw usageError("`pharos wiki <list|tree|read|write|delete>`.");
+        default:
+            throw usageError(`Unknown wiki verb "${verb}". Try list, tree, read, write or delete.`);
+    }
+}
+async function listWikis(io, session) {
+    const wikis = await session.wiki.listWikis();
+    return emit(io, wikis.map((wiki) => ({
+        name: wiki.name,
+        id: wiki.id,
+        type: wiki.type,
+        projectId: wiki.projectId,
+        // The only route to a git.push service-hook subscription — the git
+        // repositories endpoint does not list wiki repos at all (needed by #567).
+        repositoryId: wiki.repositoryId,
+    })));
+}
+/**
+ * The page tree, with ids.
+ *
+ * The join is on `path`, which is the only key both responses share.
+ */
+async function tree(io, session) {
+    const name = await session.wikiIdentifier();
+    const [structure, idByPath] = await Promise.all([
+        session.wiki.pageTree(name),
+        session.wiki.pageIdsByPath(name),
+    ]);
+    const shape = (page) => ({
+        path: page.path,
+        id: idByPath.get(page.path),
+        ...(page.subPages === undefined || page.subPages.length === 0
+            ? {}
+            : { subPages: page.subPages.map(shape) }),
+    });
+    return emit(io, { wiki: name, tree: shape(structure) });
+}
+async function read(io, session, positionals) {
+    const path = requirePath(positionals[0]);
+    const name = await session.wikiIdentifier();
+    const page = await session.wiki.readPage(name, path);
+    return emit(io, {
+        wiki: name,
+        path: page.page.path,
+        id: page.page.id,
+        // Carry it: a subsequent write must send this back as If-Match, and making
+        // the caller re-read to get it is how stale-version writes happen.
+        version: page.version,
+        content: page.page.content ?? "",
+    });
+}
+/**
+ * Create or replace a page.
+ *
+ * **Replacing an existing page needs `--yes`; creating a new one does not.**
+ * The asymmetry is the point: creating adds, replacing can silently destroy
+ * somebody's text, and that is exactly the class §2.2 of the plan puts behind
+ * an explicit flag. The preview says how many bytes are at stake.
+ */
+async function write(io, session, positionals, content) {
+    const path = requirePath(positionals[0]);
+    if (content === undefined) {
+        throw usageError("No content. Pass --text <string>, --file <path>, or --stdin to read it from the pipe.");
+    }
+    const name = await session.wikiIdentifier();
+    const existing = await readIfPresent(session, name, path);
+    if (existing !== undefined) {
+        const stop = approve(io, session, {
+            what: `replace the ${existing.bytes}-byte wiki page ${path}`,
+            would: {
+                action: "replace",
+                wiki: name,
+                path,
+                currentBytes: existing.bytes,
+                newBytes: Buffer.byteLength(content, "utf8"),
+                version: existing.version,
+            },
+        });
+        if (stop !== undefined)
+            return stop;
+        // The version from the read above — this is the guard, and it is why the
+        // read is not an optimisation that could be skipped.
+        const page = await session.wiki.writePage(name, path, content, existing.version);
+        return emit(io, { applied: true, action: "replaced", wiki: name, path: page.path });
+    }
+    const page = await session.wiki.writePage(name, path, content);
+    return emit(io, { applied: true, action: "created", wiki: name, path: page.path });
+}
+async function remove(io, session, positionals) {
+    const path = requirePath(positionals[0]);
+    const name = await session.wikiIdentifier();
+    const existing = await readIfPresent(session, name, path);
+    if (existing === undefined) {
+        // Already gone is the outcome that was asked for. Saying so beats an error
+        // that sends a retry loop round again.
+        return emit(io, { applied: false, action: "alreadyAbsent", wiki: name, path });
+    }
+    const stop = approve(io, session, {
+        what: `delete the wiki page ${path}`,
+        would: { action: "delete", wiki: name, path, bytes: existing.bytes },
+    });
+    if (stop !== undefined)
+        return stop;
+    await session.wiki.deletePage(name, path, existing.version);
+    return emit(io, { applied: true, action: "deleted", wiki: name, path });
+}
+async function readIfPresent(session, wiki, path) {
+    try {
+        const page = await session.wiki.readPage(wiki, path);
+        return {
+            version: page.version,
+            bytes: Buffer.byteLength(page.page.content ?? "", "utf8"),
+        };
+    }
+    catch (error) {
+        if (error instanceof AdoNotFoundError)
+            return undefined;
+        throw error;
+    }
+}
+function requirePath(value) {
+    if (value === undefined || value === "") {
+        throw usageError("Which page? Paths are absolute, e.g. /Plans/Sprint-3.");
+    }
+    if (!value.startsWith("/")) {
+        throw usageError(`Wiki paths are absolute: "/${value}", not "${value}". The API answers 404 without the `
+            + "leading slash, so this is the API's rule rather than a house style.", { given: value });
+    }
+    return value;
+}
+//# sourceMappingURL=wiki.js.map

package/dist/commands/wiki.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki.js","sourceRoot":"","sources":["../../src/commands/wiki.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@floh-solutions/pharos-cli` — the `pharos` command, as a library.
+ *
+ * Exported so the MCP adapter (plan §6, phase 5) can be a thin mapping onto
+ * these verbs rather than a second implementation of them. That ordering is
+ * deliberate: putting the logic in a protocol handler first and the CLI second
+ * is the two-sources-of-truth mistake this codebase has already paid for twice.
+ */
+export { run, type RunOptions } from "./cli.js";
+export { CliError, EXIT_FAILED, EXIT_OK, EXIT_REFUSED, EXIT_USAGE, refusal, usageError, type ErrorKind, type ExitCode, type Io, } from "./output.js";
+export { DEFAULT_WRITE_BUDGET, WriteBudget, isWriteRequest } from "./budget.js";
+export { Session, approve, type DestructiveAction, type SessionOptions } from "./session.js";
+export { describeTarget, parseTarget, type Target } from "./target.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,GAAG,EAAE,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAEhD,OAAO,EACL,QAAQ,EACR,WAAW,EACX,OAAO,EACP,YAAY,EACZ,UAAU,EACV,OAAO,EACP,UAAU,EACV,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,EAAE,GACR,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAE7F,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@floh-solutions/pharos-cli` — the `pharos` command, as a library.
+ *
+ * Exported so the MCP adapter (plan §6, phase 5) can be a thin mapping onto
+ * these verbs rather than a second implementation of them. That ordering is
+ * deliberate: putting the logic in a protocol handler first and the CLI second
+ * is the two-sources-of-truth mistake this codebase has already paid for twice.
+ */
+export { run } from "./cli.js";
+export { CliError, EXIT_FAILED, EXIT_OK, EXIT_REFUSED, EXIT_USAGE, refusal, usageError, } from "./output.js";
+export { DEFAULT_WRITE_BUDGET, WriteBudget, isWriteRequest } from "./budget.js";
+export { Session, approve } from "./session.js";
+export { describeTarget, parseTarget } from "./target.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,GAAG,EAAmB,MAAM,UAAU,CAAC;AAEhD,OAAO,EACL,QAAQ,EACR,WAAW,EACX,OAAO,EACP,YAAY,EACZ,UAAU,EACV,OAAO,EACP,UAAU,GAIX,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,oBAAoB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhF,OAAO,EAAE,OAAO,EAAE,OAAO,EAA+C,MAAM,cAAc,CAAC;AAE7F,OAAO,EAAE,cAAc,EAAE,WAAW,EAAe,MAAM,aAAa,CAAC"}