@floh-solutions/pharos-cli 0.1.0

package/README.md

@@ -0,0 +1,148 @@
+# `pharos`
+
+Azure DevOps from a headless shell, built for an agent to drive.
+
+```bash
+npm i -g @floh-solutions/pharos-cli
+export ADO_ORG=your-org ADO_PROJECT=YourProject ADO_PAT=…
+pharos task 210
+```
+
+## Why it exists
+
+Microsoft's `@azure-devops/mcp` server is missing capabilities that matter once
+Claude is doing real work on a board. Enumerated against its shipped tool list,
+not assumed:
+
+| | |
+|---|---|
+| wiki comments — list, add, edit, delete, react | **no tool at all** |
+| work item comments — delete, react/unreact | absent (it has add and update only) |
+| wiki page delete | absent |
+| service hook subscriptions | absent |
+
+And it authenticates with an **interactive browser login**, so an unattended
+agent blocks on a modal nobody is there to answer.
+
+## The command it exists for
+
+```bash
+pharos task 210
+```
+
+One call returns the work item, its fields, its comments, its attachments, its
+relations **with their titles**, and the full content of every linked wiki page
+**plus the discussion on those pages**.
+
+Assembled by hand that is five or six round trips across two different tools,
+and one of them is impossible. It is what an agent needs in order to *start*:
+the plan a colleague wrote on a wiki page, the argument underneath it, and the
+dependency that says this cannot begin yet. Anything forgotten is context the
+agent silently works without.
+
+It gathers; it does not summarise or rank. Whatever could not be fetched lands
+in `problems[]` rather than being quietly dropped — a context with an invisible
+hole in it is worse than a short one, because it gets reasoned from
+confidently.
+
+Add `--pretty` for a human-readable brief.
+
+## The output is the interface
+
+**Success is JSON on stdout. Failure is JSON on stderr with a non-zero exit.**
+An empty array and exit 0 is a query that matched nothing; that is a different
+fact from a 403, and prose makes it a guess.
+
+| exit | meaning | what to do |
+|---|---|---|
+| `0` | it worked | carry on |
+| `1` | the call failed | maybe retry — check `kind`, and `retryAfterMs` if rate-limited |
+| `2` | called wrong, or not configured | **never** retry unchanged |
+| `3` | refused by a guard here | re-run with `--yes`, or raise `--max-writes` |
+
+Errors carry what you need to act:
+
+```json
+{ "error": { "kind": "conflict", "expectedRev": 4, "actualRev": 5,
+             "hint": "Re-read the item and re-apply…" } }
+```
+
+A bad token exits **2**, not 1 — retrying it is pure noise. A conflict carries
+both revisions, and says out loud that posting a comment bumps `System.Rev`, so
+a rev mismatch is *not* proof that somebody edited the same field.
+
+## Guards
+
+Every verb here is one an agent can call in a loop against a board real people
+depend on.
+
+**Destructive verbs refuse by default.**
+
+```bash
+pharos wiki delete /Plans/Old        # exit 3, nothing changed, preview attached
+pharos wiki delete /Plans/Old --dry-run   # exit 0 — the preview IS the request
+pharos wiki delete /Plans/Old --yes       # done
+```
+
+The bare form exits **non-zero on purpose**. Exiting 0 with `"applied": false`
+reads as success to anything that checks only the status, and an agent that
+quietly does less looks identical to one that succeeded. `--dry-run` beats
+`--yes`: the safe reading of a contradiction is the one that changes nothing.
+
+**Replacing a wiki page needs `--yes`; creating one does not.** Creating adds,
+replacing can destroy somebody's text. The read that decides which is also
+where the `If-Match` version comes from, so the concurrency guard is not
+something a caller can skip.
+
+**A write budget, counted at the transport.** Default 20 per invocation, so a
+runaway loop becomes a clean refusal rather than 500 work items. `--max-writes 0`
+is read-only: reads work, every write is refused before it is sent.
+
+It is **not security** — anything that can run this holds the token and can make
+the same REST calls directly. It shapes intent and catches accidents. A
+capability that must be impossible has to be withheld at the token.
+
+## Commands
+
+```
+task <id>                             the whole context, in one call
+wiki list | tree | read | write | delete
+comment list | add | edit | delete | react | unreact | reactors
+plan <file>                           an implementation plan becomes a work item tree
+```
+
+`comment` takes either kind of target: a work item is its number (`210`), a wiki
+page is an **absolute path** (`/Plans/Foo`). The leading slash is required by
+the wiki API itself — it answers 404 without one — so the spelling that tells
+them apart is also the only spelling that works.
+
+Long text does not belong on a command line:
+
+```bash
+pharos comment add 210 --file review.md
+pharos wiki write /Plans/Sprint-4 --stdin < plan.md
+```
+
+## Configuration
+
+| | |
+|---|---|
+| `ADO_ORG` | your organisation — the first path component of your `dev.azure.com` URL |
+| `ADO_PROJECT` | the project inside it |
+| `ADO_PAT` | a Personal Access Token |
+
+**From the environment, and nowhere else.** No keychain, no credential helper,
+no config file — that is what lets this run headless, in CI, or under an agent
+with nobody there to answer a prompt. There is deliberately no built-in
+organisation either: a default would let a misconfigured run succeed quietly
+against somebody else's board.
+
+Scopes are separate and both are needed for full use: `vso.work_write` for work
+items, `vso.wiki_write` for the wiki.
+
+**Every person uses their own token.** Board attribution is per-person, and a
+shared token makes everyone's work read as one account.
+
+## Requirements
+
+Node 22 or later.

package/dist/bin.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=bin.d.ts.map

package/dist/bin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/bin.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+const code = await run({
+    argv: process.argv.slice(2),
+    cwd: process.cwd(),
+    env: process.env,
+    stdout: (line) => process.stdout.write(`${line}\n`),
+    stderr: (line) => process.stderr.write(`${line}\n`),
+}).catch((error) => {
+    // `run` maps everything it can into the structured error contract; this is
+    // only reached if the mapping itself broke. Keep the shape anyway, so a
+    // consumer never has to parse two different things off stderr.
+    process.stderr.write(`${JSON.stringify({
+        error: { kind: "internal", message: error instanceof Error ? error.message : String(error) },
+    })}\n`);
+    return 1;
+});
+process.exitCode = code;
+//# sourceMappingURL=bin.js.map

package/dist/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC;AAE/B,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC;IACrB,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3B,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE;IAClB,GAAG,EAAE,OAAO,CAAC,GAAG;IAChB,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;IACnD,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC;CACpD,CAAC,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC1B,2EAA2E;IAC3E,wEAAwE;IACxE,+DAA+D;IAC/D,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,GAAG,IAAI,CAAC,SAAS,CAAC;QAChB,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;KAC7F,CAAC,IAAI,CACP,CAAC;IACF,OAAO,CAAC,CAAC;AACX,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC"}

package/dist/budget.d.ts

@@ -0,0 +1,43 @@
+import type { FetchLike } from "@floh-solutions/ado-core";
+/**
+ * A cap on how many writes one invocation may perform.
+ *
+ * ## Why it is counted at the transport and not at the call sites
+ *
+ * An agent in a loop can create five hundred work items before anybody notices.
+ * The cap is what turns that from an incident into a refusal — so the one thing
+ * it must not be is *optional to remember*. Counting inside each command means
+ * every new command is a chance to forget, and the command that forgets is the
+ * one nobody tested against a runaway.
+ *
+ * Counting requests as they leave means a write cannot avoid the budget by not
+ * declaring itself, including writes made by code this package merely calls —
+ * `plan-to-board` creates a whole work item tree and knows nothing about any of
+ * this.
+ *
+ * ## What it is not
+ *
+ * **It is not security.** Anything that can run this CLI holds the PAT and can
+ * make the same REST calls directly. This shapes intent and catches accidents,
+ * which is most of the real value, but a capability that must be *impossible*
+ * has to be withheld at the token — see `docs/pharos-cli-plan.md` §2.5.
+ */
+/** Deliberately small. A single invocation doing twenty writes is unusual. */
+export declare const DEFAULT_WRITE_BUDGET = 20;
+export declare function isWriteRequest(method: string, url: string): boolean;
+export declare class WriteBudget {
+    #private;
+    readonly limit: number;
+    constructor(limit?: number);
+    get spent(): number;
+    get remaining(): number;
+    /**
+     * Wrap a fetch so every write is counted, and the one that would exceed the
+     * cap is **refused before it is sent** rather than reported after.
+     *
+     * A retried write counts once per attempt, deliberately: a run that is
+     * retrying hard is exactly when a cap should bite sooner rather than later.
+     */
+    wrap(inner: FetchLike): FetchLike;
+}
+//# sourceMappingURL=budget.d.ts.map

package/dist/budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.d.ts","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAuBvC,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAInE;AAED,qBAAa,WAAW;;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;gBAGX,KAAK,GAAE,MAA6B;IAIhD,IAAI,KAAK,IAAI,MAAM,CAElB;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,SAAS;CAiBlC"}

package/dist/budget.js

@@ -0,0 +1,92 @@
+import { refusal } from "./output.js";
+/**
+ * A cap on how many writes one invocation may perform.
+ *
+ * ## Why it is counted at the transport and not at the call sites
+ *
+ * An agent in a loop can create five hundred work items before anybody notices.
+ * The cap is what turns that from an incident into a refusal — so the one thing
+ * it must not be is *optional to remember*. Counting inside each command means
+ * every new command is a chance to forget, and the command that forgets is the
+ * one nobody tested against a runaway.
+ *
+ * Counting requests as they leave means a write cannot avoid the budget by not
+ * declaring itself, including writes made by code this package merely calls —
+ * `plan-to-board` creates a whole work item tree and knows nothing about any of
+ * this.
+ *
+ * ## What it is not
+ *
+ * **It is not security.** Anything that can run this CLI holds the PAT and can
+ * make the same REST calls directly. This shapes intent and catches accidents,
+ * which is most of the real value, but a capability that must be *impossible*
+ * has to be withheld at the token — see `docs/pharos-cli-plan.md` §2.5.
+ */
+/** Deliberately small. A single invocation doing twenty writes is unusual. */
+export const DEFAULT_WRITE_BUDGET = 20;
+/**
+ * POSTs that are reads.
+ *
+ * Azure DevOps expresses two of its most common *reads* as POSTs, because the
+ * query does not fit in a URL. Counting them as writes would mean
+ * `pharos task 210` — which writes nothing at all — burning budget, and a
+ * read-only invocation failing with a write-cap error is the kind of nonsense
+ * that teaches people to raise the cap to infinity.
+ *
+ * **Adding a read-shaped POST endpoint means adding it here.** The failure is
+ * not silent, at least: it shows up as a read that spends budget.
+ */
+const READ_SHAPED_POSTS = [
+    "/_apis/wit/workitemsbatch",
+    "/_apis/wit/wiql",
+    // Page ids in bulk. Documented as page-VIEW statistics and shaped like a
+    // write; it is the only route to a wiki page's numeric id short of one
+    // request per page, and `pharos wiki tree` reads it every time.
+    "/pagesbatch",
+];
+export function isWriteRequest(method, url) {
+    if (method.toUpperCase() === "GET")
+        return false;
+    const path = url.toLowerCase();
+    return !READ_SHAPED_POSTS.some((endpoint) => path.includes(endpoint));
+}
+export class WriteBudget {
+    limit;
+    #spent = 0;
+    constructor(limit = DEFAULT_WRITE_BUDGET) {
+        this.limit = limit;
+    }
+    get spent() {
+        return this.#spent;
+    }
+    get remaining() {
+        return Math.max(0, this.limit - this.#spent);
+    }
+    /**
+     * Wrap a fetch so every write is counted, and the one that would exceed the
+     * cap is **refused before it is sent** rather than reported after.
+     *
+     * A retried write counts once per attempt, deliberately: a run that is
+     * retrying hard is exactly when a cap should bite sooner rather than later.
+     */
+    wrap(inner) {
+        return async (input, init) => {
+            const method = init?.method ?? "GET";
+            if (isWriteRequest(method, input)) {
+                if (this.#spent >= this.limit) {
+                    throw refusal(`Write budget of ${this.limit} exhausted; refusing to send ${method} ${redact(input)}. `
+                        + "Raise it with --max-writes if this run genuinely needs more, but check first that "
+                        + "it is not looping.", { limit: this.limit, spent: this.#spent, method, url: redact(input) });
+                }
+                this.#spent += 1;
+            }
+            return inner(input, init);
+        };
+    }
+}
+/** Query strings can carry a continuation token; the path is the useful part. */
+function redact(url) {
+    const cut = url.indexOf("?");
+    return cut === -1 ? url : url.slice(0, cut);
+}
+//# sourceMappingURL=budget.js.map

package/dist/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../src/budget.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,MAAM,iBAAiB,GAAG;IACxB,2BAA2B;IAC3B,iBAAiB;IACjB,yEAAyE;IACzE,uEAAuE;IACvE,gEAAgE;IAChE,aAAa;CACd,CAAC;AAEF,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,GAAW;IACxD,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACjD,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAC/B,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,OAAO,WAAW;IACb,KAAK,CAAS;IACvB,MAAM,GAAG,CAAC,CAAC;IAEX,YAAY,QAAgB,oBAAoB;QAC9C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACH,IAAI,CAAC,KAAgB;QACnB,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE;YAC3B,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,CAAC;YACrC,IAAI,cAAc,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,CAAC;gBAClC,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;oBAC9B,MAAM,OAAO,CACX,mBAAmB,IAAI,CAAC,KAAK,gCAAgC,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI;0BACpF,oFAAoF;0BACpF,oBAAoB,EACxB,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CACtE,CAAC;gBACJ,CAAC;gBACD,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;YACnB,CAAC;YACD,OAAO,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;QAC5B,CAAC,CAAC;IACJ,CAAC;CACF;AAED,iFAAiF;AACjF,SAAS,MAAM,CAAC,GAAW;IACzB,MAAM,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC7B,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AAC9C,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+import type { AdoClient } from "@floh-solutions/ado-core";
+import { type ExitCode } from "./output.js";
+export interface RunOptions {
+    argv: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+    /** Injected by tests. Production reads fd 0. */
+    readStdin?: (() => Promise<string>) | undefined;
+    /** Injected by tests, so the whole router can run against a mock transport. */
+    client?: AdoClient | undefined;
+}
+export declare function run(options: RunOptions): Promise<ExitCode>;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAO1D,OAAO,EAKL,KAAK,QAAQ,EAEd,MAAM,aAAa,CAAC;AA4FrB,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,gDAAgD;IAChD,SAAS,CAAC,EAAE,CAAC,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,SAAS,CAAC;IAChD,+EAA+E;IAC/E,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC;AAED,wBAAsB,GAAG,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAOhE"}

package/dist/cli.js

@@ -0,0 +1,249 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { run as runPlanToBoard } from "@floh-solutions/plan-to-board";
+import { DEFAULT_WRITE_BUDGET, WriteBudget } from "./budget.js";
+import { runComment } from "./commands/comment.js";
+import { runTask } from "./commands/task.js";
+import { runWiki } from "./commands/wiki.js";
+import { EXIT_OK, emitText, reportError, usageError, } from "./output.js";
+import { Session } from "./session.js";
+/**
+ * Flags every command understands.
+ *
+ * `--json` is accepted and does nothing: JSON *is* the default output, and the
+ * flag exists because it is the obvious thing to reach for. Erroring on it
+ * would fail a call that asked for exactly what it was already getting.
+ */
+const GLOBAL_OPTIONS = {
+    pretty: { type: "boolean" },
+    json: { type: "boolean" },
+    yes: { type: "boolean", short: "y" },
+    "dry-run": { type: "boolean" },
+    "max-writes": { type: "string" },
+    org: { type: "string" },
+    project: { type: "string" },
+    wiki: { type: "string" },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean" },
+};
+/** Where long text comes from, for the verbs that take some. */
+const CONTENT_OPTIONS = {
+    text: { type: "string" },
+    file: { type: "string" },
+    stdin: { type: "boolean" },
+};
+const USAGE = `pharos — Azure DevOps from a headless shell, for an agent.
+
+  pharos <command> [options]
+
+COMMANDS
+
+  task <id>                      Everything about one work item in a single call:
+                                 fields, comments, attachments, relations with
+                                 their titles, and the CONTENT of any linked wiki
+                                 pages plus the discussion on them. This is the
+                                 command the rest exists to support.
+      --no-wiki-content          do not fetch linked page content
+      --no-wiki-comments         do not fetch comments on linked pages
+      --no-related-titles        ids only; skip the batch that names them
+
+  wiki list                      Every wiki, with the ids links and hooks need
+  wiki tree                      The page tree, WITH page ids (two calls, joined)
+  wiki read <path>               Content plus the version a write must carry
+  wiki write <path>              Create, or replace (replacing needs --yes)
+  wiki delete <path>             Needs --yes
+
+  comment list <target>          <target> is a work item id (210) or a wiki page
+  comment add <target> [text]    path (/Plans/Foo). Wiki comments are reachable
+  comment edit <target> <id> [text]   through no other tool at all.
+  comment delete <target> <id>   Needs --yes
+  comment react <target> <id> <type>       like dislike heart hooray smile confused
+  comment unreact <target> <id> <type>
+  comment reactors <target> <id> <type>    who reacted, by name
+
+  plan <file> [...]              Turn an implementation plan into a work item
+                                 tree. Passed through to plan-to-board verbatim,
+                                 including its flags and its human output.
+
+TEXT INPUT
+  --text <string>                for anything longer than a shell argument
+  --file <path>                  read it from a file
+  --stdin                        read it from the pipe
+
+GLOBAL
+  --pretty                       human output. Default is JSON on stdout.
+  --yes, -y                      apply destructive changes. Without it they are
+                                 REFUSED (exit 3), not silently skipped.
+  --dry-run                      show what would happen and exit 0. Beats --yes.
+  --max-writes <n>               per-invocation write cap (default ${DEFAULT_WRITE_BUDGET}).
+                                 0 means read-only: reads work, writes refused.
+  --org <name>                   or ADO_ORG
+  --project <name>               or ADO_PROJECT
+  --wiki <name>                  only needed when the project has several
+  --version, --help, -h
+
+EXIT CODES
+  0  it worked                  2  called wrong, or not configured — do not retry
+  1  the call failed            3  refused by a guard here — re-run with --yes
+
+AUTH
+  ADO_PAT from the environment. Nothing else, and never the Keychain: this has
+  to work headless, which is the entire point. Work item writes need the
+  vso.work_write scope; wiki writes need vso.wiki_write, separately.
+`;
+export async function run(options) {
+    const io = { stdout: options.stdout, stderr: options.stderr };
+    try {
+        return await dispatch(io, options);
+    }
+    catch (error) {
+        return reportError(io, error);
+    }
+}
+async function dispatch(io, options) {
+    const command = options.argv.find((argument) => !argument.startsWith("-"));
+    // `plan` is a passthrough and must not have its flags eaten here — it has its
+    // own, they collide (`--wiki` means something different there), and the whole
+    // point of a passthrough is that the delegate keeps its interface.
+    if (command === "plan") {
+        return plan(options);
+    }
+    const extras = command === "task"
+        ? {
+            "no-wiki-content": { type: "boolean" },
+            "no-wiki-comments": { type: "boolean" },
+            "no-related-titles": { type: "boolean" },
+        }
+        : CONTENT_OPTIONS;
+    const { values, positionals } = parse(options.argv, { ...GLOBAL_OPTIONS, ...extras });
+    if (values["version"] === true)
+        return emitText(io, await version(options.cwd));
+    if (values["help"] === true || command === undefined)
+        return emitText(io, USAGE);
+    const session = new Session({
+        env: options.env,
+        organization: asString(values["org"]),
+        project: asString(values["project"]),
+        wiki: asString(values["wiki"]),
+        budget: new WriteBudget(maxWrites(values["max-writes"])),
+        // --dry-run beats --yes on purpose: the safe reading of a contradiction is
+        // the one that changes nothing.
+        apply: values["yes"] === true && values["dry-run"] !== true,
+        previewOnly: values["dry-run"] === true,
+        pretty: values["pretty"] === true,
+        client: options.client,
+    });
+    const rest = positionals.slice(1);
+    switch (command) {
+        case "task":
+            return runTask(io, session, rest, {
+                wikiContent: values["no-wiki-content"] !== true,
+                wikiComments: values["no-wiki-comments"] !== true,
+                relatedTitles: values["no-related-titles"] !== true,
+            });
+        case "wiki":
+            return runWiki(io, session, rest, {
+                content: await content(options, values),
+            });
+        case "comment":
+            return runComment(io, session, rest, {
+                text: await content(options, values),
+            });
+        default:
+            throw usageError(`Unknown command "${command}". Try task, wiki, comment or plan.`, {
+                commands: ["task", "wiki", "comment", "plan"],
+            });
+    }
+}
+/**
+ * `plan` hands the whole tail to `plan-to-board` untouched.
+ *
+ * **Its output is human text, not JSON**, which is the one exception to this
+ * CLI's output contract. Wrapping it would mean either re-implementing its
+ * rendering or emitting a string inside a JSON envelope that no consumer wants;
+ * folding it in properly is worth doing when something actually needs to parse
+ * a plan run, and pretending it already is JSON would be worse than saying so.
+ */
+async function plan(options) {
+    const index = options.argv.indexOf("plan");
+    const code = await runPlanToBoard({
+        argv: options.argv.slice(index + 1),
+        cwd: options.cwd,
+        env: options.env,
+        stdout: options.stdout,
+        stderr: options.stderr,
+        ...(options.client === undefined ? {} : { client: options.client }),
+    });
+    return code === 0 ? EXIT_OK : code;
+}
+function parse(argv, optionsConfig) {
+    try {
+        const parsed = parseArgs({
+            args: [...argv],
+            options: optionsConfig,
+            allowPositionals: true,
+            strict: true,
+        });
+        return { values: parsed.values, positionals: parsed.positionals };
+    }
+    catch (error) {
+        // A typo'd flag must not be ignored: an agent that passed --dryrun and got
+        // a real write would have no way to know that is what happened.
+        throw usageError(error instanceof Error ? error.message : String(error));
+    }
+}
+/** Long text, from a flag, a file, or the pipe. Exactly one source. */
+async function content(options, values) {
+    const sources = ["text", "file", "stdin"].filter((key) => values[key] !== undefined);
+    if (sources.length > 1) {
+        throw usageError(`Pass only one of --text, --file or --stdin; got ${sources.join(" and ")}.`);
+    }
+    const text = asString(values["text"]);
+    if (text !== undefined)
+        return text;
+    const file = asString(values["file"]);
+    if (file !== undefined)
+        return readFile(resolve(options.cwd, file), "utf8");
+    if (values["stdin"] === true) {
+        return (options.readStdin ?? readAllStdin)();
+    }
+    return undefined;
+}
+async function readAllStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * `--max-writes 0` is allowed and means **read-only**: every write is refused,
+ * every read still works. Worth having as more than a test hook — it is the one
+ * setting that makes "this invocation cannot change anything" a property of the
+ * call rather than a promise about which verbs were used.
+ */
+function maxWrites(raw) {
+    if (typeof raw !== "string")
+        return DEFAULT_WRITE_BUDGET;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0) {
+        throw usageError(`--max-writes takes a whole number of 0 or more, not "${raw}". 0 means read-only.`);
+    }
+    return value;
+}
+async function version(cwd) {
+    try {
+        const manifest = await readFile(new URL("../package.json", import.meta.url), "utf8");
+        const parsed = JSON.parse(manifest);
+        return parsed.version ?? "unknown";
+    }
+    catch {
+        // Running from a checkout laid out differently. Not worth failing over.
+        void cwd;
+        return "unknown";
+    }
+}
+function asString(value) {
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/commands/comment.d.ts

@@ -0,0 +1,6 @@
+import { type ExitCode, type Io } from "../output.js";
+import { type Session } from "../session.js";
+export declare function runComment(io: Io, session: Session, positionals: readonly string[], input: {
+    text?: string | undefined;
+}): Promise<ExitCode>;
+//# sourceMappingURL=comment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"comment.d.ts","sourceRoot":"","sources":["../../src/commands/comment.ts"],"names":[],"mappings":"AAEA,OAAO,EAAoB,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AACxE,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AAoCtD,wBAAsB,UAAU,CAC9B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,KAAK,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GACnC,OAAO,CAAC,QAAQ,CAAC,CAoCnB"}