@floh-solutions/pharos-cli 0.1.0

package/dist/output.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The output contract.
+ *
+ * **The consumer is a program**, so the shape of what comes out is part of the
+ * interface and not a presentation detail. Two rules, and everything else
+ * follows from them:
+ *
+ *   1. **Success goes to stdout as JSON. Failure goes to stderr as JSON, with a
+ *      non-zero exit.** An agent must be able to tell "no results" from "the
+ *      call failed" without reading prose, and text output makes that a guess.
+ *      An empty list on stdout and exit 0 is a *successful* query that matched
+ *      nothing; that is a different fact from a 403.
+ *   2. **The exit code says what KIND of wrong it went**, because the three
+ *      kinds want three different responses and an agent that cannot tell them
+ *      apart retries the one thing that will never work.
+ */
+/**
+ * | code | meaning | what an agent should do |
+ * |---|---|---|
+ * | 0 | it worked | carry on |
+ * | 1 | the call failed | possibly retry — check `kind` and `retryAfterMs` |
+ * | 2 | you called it wrong, or it is not configured | **never** retry unchanged |
+ * | 3 | refused by a guard here | re-run with `--yes`, or raise `--max-writes` |
+ */
+export declare const EXIT_OK = 0;
+export declare const EXIT_FAILED = 1;
+export declare const EXIT_USAGE = 2;
+export declare const EXIT_REFUSED = 3;
+export type ExitCode = 0 | 1 | 2 | 3;
+export type ErrorKind = "usage" | "config" | "auth" | "refused" | "conflict" | "notFound" | "rateLimit" | "network" | "ado" | "internal";
+export interface Io {
+    stdout: (line: string) => void;
+    stderr: (line: string) => void;
+}
+/**
+ * An error this CLI raised itself, as opposed to one Azure DevOps returned.
+ *
+ * `detail` is merged into the emitted error object, so a refusal can carry the
+ * numbers that explain it (the budget and what was spent) rather than only
+ * prose about them.
+ */
+export declare class CliError extends Error {
+    readonly kind: ErrorKind;
+    readonly exitCode: ExitCode;
+    readonly detail: Record<string, unknown>;
+    /**
+     * Read by `ado-core`'s transport when this is thrown from inside an injected
+     * `fetch` — the write budget does exactly that. It means "a decision, not a
+     * connection failure": rethrow me as I am and do not replay the request.
+     * Without it a refusal comes back as `kind: "network"` with exit 1, and an
+     * agent retries a cap that will never lift.
+     */
+    readonly noRetry = true;
+    constructor(message: string, kind: ErrorKind, exitCode: ExitCode, detail?: Record<string, unknown>);
+}
+/** Called wrong. Exit 2 — an agent must change the call, not repeat it. */
+export declare function usageError(message: string, detail?: Record<string, unknown>): CliError;
+/**
+ * A guard here said no. Exit 3, distinct from every other failure **because it
+ * is the only one the caller can clear by asking again more explicitly** — and
+ * an agent that cannot see that difference either gives up on work it was
+ * allowed to do, or hammers a 403 forever.
+ */
+export declare function refusal(message: string, detail?: Record<string, unknown>): CliError;
+/** Success. One JSON object, indented — a transcript gets read by people too. */
+export declare function emit(io: Io, value: unknown): ExitCode;
+/** Human output. Only ever reached via `--pretty`. */
+export declare function emitText(io: Io, text: string): ExitCode;
+/**
+ * Turn anything thrown into the structured error an agent can act on, and
+ * return the exit code that goes with it.
+ *
+ * The mapping is the useful part. Azure DevOps failures arrive as a wall of
+ * status codes that all mean "no"; these are the distinctions that change what
+ * to do next:
+ *
+ *   - **conflict** — somebody else wrote first. The work is still valid; re-read
+ *     and re-apply. Carries both revisions so a caller can diff rather than
+ *     guess, and says out loud that a bare comment bumps `System.Rev`, which is
+ *     why a rev mismatch is not proof of an edit collision.
+ *   - **auth** — exit 2, not 1. A bad PAT is a configuration fault and retrying
+ *     it is pure noise.
+ *   - **rateLimit** — carries `retryAfterMs`, the only case where waiting and
+ *     repeating the identical call is correct.
+ */
+export declare function reportError(io: Io, error: unknown): ExitCode;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,OAAO,IAAI,CAAC;AACzB,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,UAAU,IAAI,CAAC;AAC5B,eAAO,MAAM,YAAY,IAAI,CAAC;AAE9B,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAErC,MAAM,MAAM,SAAS,GACjB,OAAO,GACP,QAAQ,GACR,MAAM,GACN,SAAS,GACT,UAAU,GACV,UAAU,GACV,WAAW,GACX,SAAS,GACT,KAAK,GACL,UAAU,CAAC;AAEf,MAAM,WAAW,EAAE;IACjB,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED;;;;;;GAMG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEzC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,QAAQ;gBAGtB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,QAAQ,EAClB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAQvC;AAED,2EAA2E;AAC3E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,QAAQ,CAE1F;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,QAAQ,CAEvF;AAED,iFAAiF;AACjF,wBAAgB,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,QAAQ,CAGrD;AAED,sDAAsD;AACtD,wBAAgB,QAAQ,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,QAAQ,CAGvD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,GAAG,QAAQ,CAI5D"}

package/dist/output.js

@@ -0,0 +1,194 @@
+import { AdoAuthError, AdoConcurrencyError, AdoConfigError, AdoError, AdoNetworkError, AdoNotFoundError, AdoRateLimitError, } from "@floh-solutions/ado-core";
+/**
+ * The output contract.
+ *
+ * **The consumer is a program**, so the shape of what comes out is part of the
+ * interface and not a presentation detail. Two rules, and everything else
+ * follows from them:
+ *
+ *   1. **Success goes to stdout as JSON. Failure goes to stderr as JSON, with a
+ *      non-zero exit.** An agent must be able to tell "no results" from "the
+ *      call failed" without reading prose, and text output makes that a guess.
+ *      An empty list on stdout and exit 0 is a *successful* query that matched
+ *      nothing; that is a different fact from a 403.
+ *   2. **The exit code says what KIND of wrong it went**, because the three
+ *      kinds want three different responses and an agent that cannot tell them
+ *      apart retries the one thing that will never work.
+ */
+/**
+ * | code | meaning | what an agent should do |
+ * |---|---|---|
+ * | 0 | it worked | carry on |
+ * | 1 | the call failed | possibly retry — check `kind` and `retryAfterMs` |
+ * | 2 | you called it wrong, or it is not configured | **never** retry unchanged |
+ * | 3 | refused by a guard here | re-run with `--yes`, or raise `--max-writes` |
+ */
+export const EXIT_OK = 0;
+export const EXIT_FAILED = 1;
+export const EXIT_USAGE = 2;
+export const EXIT_REFUSED = 3;
+/**
+ * An error this CLI raised itself, as opposed to one Azure DevOps returned.
+ *
+ * `detail` is merged into the emitted error object, so a refusal can carry the
+ * numbers that explain it (the budget and what was spent) rather than only
+ * prose about them.
+ */
+export class CliError extends Error {
+    kind;
+    exitCode;
+    detail;
+    /**
+     * Read by `ado-core`'s transport when this is thrown from inside an injected
+     * `fetch` — the write budget does exactly that. It means "a decision, not a
+     * connection failure": rethrow me as I am and do not replay the request.
+     * Without it a refusal comes back as `kind: "network"` with exit 1, and an
+     * agent retries a cap that will never lift.
+     */
+    noRetry = true;
+    constructor(message, kind, exitCode, detail = {}) {
+        super(message);
+        this.name = "CliError";
+        this.kind = kind;
+        this.exitCode = exitCode;
+        this.detail = detail;
+    }
+}
+/** Called wrong. Exit 2 — an agent must change the call, not repeat it. */
+export function usageError(message, detail = {}) {
+    return new CliError(message, "usage", EXIT_USAGE, detail);
+}
+/**
+ * A guard here said no. Exit 3, distinct from every other failure **because it
+ * is the only one the caller can clear by asking again more explicitly** — and
+ * an agent that cannot see that difference either gives up on work it was
+ * allowed to do, or hammers a 403 forever.
+ */
+export function refusal(message, detail = {}) {
+    return new CliError(message, "refused", EXIT_REFUSED, detail);
+}
+/** Success. One JSON object, indented — a transcript gets read by people too. */
+export function emit(io, value) {
+    io.stdout(JSON.stringify(value, undefined, 2));
+    return EXIT_OK;
+}
+/** Human output. Only ever reached via `--pretty`. */
+export function emitText(io, text) {
+    io.stdout(text);
+    return EXIT_OK;
+}
+/**
+ * Turn anything thrown into the structured error an agent can act on, and
+ * return the exit code that goes with it.
+ *
+ * The mapping is the useful part. Azure DevOps failures arrive as a wall of
+ * status codes that all mean "no"; these are the distinctions that change what
+ * to do next:
+ *
+ *   - **conflict** — somebody else wrote first. The work is still valid; re-read
+ *     and re-apply. Carries both revisions so a caller can diff rather than
+ *     guess, and says out loud that a bare comment bumps `System.Rev`, which is
+ *     why a rev mismatch is not proof of an edit collision.
+ *   - **auth** — exit 2, not 1. A bad PAT is a configuration fault and retrying
+ *     it is pure noise.
+ *   - **rateLimit** — carries `retryAfterMs`, the only case where waiting and
+ *     repeating the identical call is correct.
+ */
+export function reportError(io, error) {
+    const { body, code } = describe(error);
+    io.stderr(JSON.stringify({ error: body }, undefined, 2));
+    return code;
+}
+function describe(error) {
+    if (error instanceof CliError) {
+        return {
+            body: { kind: error.kind, message: error.message, ...error.detail },
+            code: error.exitCode,
+        };
+    }
+    if (error instanceof AdoConcurrencyError) {
+        return {
+            body: {
+                kind: "conflict",
+                message: error.message,
+                status: error.status,
+                workItemId: error.workItemId,
+                expectedRev: error.expectedRev,
+                actualRev: error.actualRev,
+                hint: "Re-read the item and re-apply your change. Diff the fields you actually changed first "
+                    + "— a comment alone bumps System.Rev, so this is not necessarily an edit collision.",
+            },
+            code: EXIT_FAILED,
+        };
+    }
+    if (error instanceof AdoRateLimitError) {
+        return {
+            body: {
+                kind: "rateLimit",
+                message: error.message,
+                status: error.status,
+                retryAfterMs: error.retryAfterMs,
+                hint: "Wait retryAfterMs and repeat the identical call.",
+            },
+            code: EXIT_FAILED,
+        };
+    }
+    // A bad or expired PAT is a CONFIGURATION fault, so it exits 2 with the rest
+    // of the "you cannot fix this by trying again" family.
+    if (error instanceof AdoAuthError) {
+        return {
+            body: {
+                kind: "auth",
+                message: error.message,
+                status: error.status,
+                activityId: error.activityId,
+                hint: "Check ADO_PAT: expired, revoked, or missing a scope. Wiki writes need vso.wiki_write "
+                    + "and work item writes need vso.work_write; they are separate.",
+            },
+            code: EXIT_USAGE,
+        };
+    }
+    if (error instanceof AdoNotFoundError) {
+        return {
+            body: adoBody("notFound", error),
+            code: EXIT_FAILED,
+        };
+    }
+    if (error instanceof AdoError) {
+        return { body: adoBody("ado", error), code: EXIT_FAILED };
+    }
+    if (error instanceof AdoNetworkError) {
+        return {
+            body: {
+                kind: "network",
+                message: error.message,
+                method: error.method,
+                url: error.url,
+            },
+            code: EXIT_FAILED,
+        };
+    }
+    if (error instanceof AdoConfigError) {
+        return { body: { kind: "config", message: error.message }, code: EXIT_USAGE };
+    }
+    return {
+        body: {
+            kind: "internal",
+            message: error instanceof Error ? error.message : String(error),
+        },
+        code: EXIT_FAILED,
+    };
+}
+function adoBody(kind, error) {
+    return {
+        kind,
+        message: error.message,
+        status: error.status,
+        method: error.method,
+        url: error.url,
+        typeKey: error.typeKey,
+        // Quote this at Microsoft support. It is the only handle they accept.
+        activityId: error.activityId,
+    };
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

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

package/dist/session.d.ts

@@ -0,0 +1,77 @@
+import { AdoClient, WikiApi } from "@floh-solutions/ado-core";
+import { WriteBudget } from "./budget.js";
+import { type ExitCode, type Io } from "./output.js";
+/**
+ * One invocation's world: the client, the budget it spends against, the wiki it
+ * resolved, and whether it is allowed to actually write.
+ */
+export interface SessionOptions {
+    env: NodeJS.ProcessEnv;
+    organization?: string | undefined;
+    project?: string | undefined;
+    /** Wiki name or id. Resolved lazily — most commands never need it. */
+    wiki?: string | undefined;
+    budget: WriteBudget;
+    /** `--yes` was passed and `--dry-run` was not. */
+    apply: boolean;
+    /** `--dry-run` was passed: a preview is the requested OUTPUT, not a refusal. */
+    previewOnly: boolean;
+    pretty: boolean;
+    /** Injected by tests; production passes nothing and gets a real client. */
+    client?: AdoClient | undefined;
+}
+export declare class Session {
+    #private;
+    readonly client: AdoClient;
+    readonly wiki: WikiApi;
+    readonly budget: WriteBudget;
+    readonly apply: boolean;
+    readonly previewOnly: boolean;
+    readonly pretty: boolean;
+    constructor(options: SessionOptions);
+    /**
+     * The wiki to act on, resolved once.
+     *
+     * **Ambiguity is refused, not guessed.** A project usually has exactly one
+     * wiki and then there is nothing to decide. When it has several, silently
+     * picking the first means a plan lands in the wrong one and nothing says so —
+     * so the tie is broken only where the answer is unambiguous (a single project
+     * wiki among code wikis, which is the normal mixed case), and otherwise the
+     * names come back with the refusal so the caller can name one.
+     */
+    wikiIdentifier(): Promise<string>;
+    /** The project GUID and wiki id an artifact link must be built from. */
+    wikiForLinking(): Promise<{
+        name: string;
+        wikiId: string;
+        projectId: string;
+    }>;
+}
+/** What a destructive verb is about to do, described before it does it. */
+export interface DestructiveAction {
+    /** Imperative, for the message: "delete wiki page /Plans/Foo". */
+    what: string;
+    /** The structured version, emitted either way so a preview is machine-readable. */
+    would: Record<string, unknown>;
+}
+/**
+ * The gate in front of anything that destroys or overwrites.
+ *
+ * Three outcomes, and the difference between the first two is the whole point:
+ *
+ * | invocation | result | exit |
+ * |---|---|---|
+ * | (no flag) | **refused**, with the preview attached | 3 |
+ * | `--dry-run` | preview on stdout — you asked for exactly this | 0 |
+ * | `--yes` | it happens | 0 |
+ *
+ * A bare invocation exits **non-zero**, and that is deliberate. 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"
+ * is how a half-finished job gets reported as done (`docs/pharos-cli-plan.md`
+ * §2.5). `--dry-run` exits 0 because there the preview IS the deliverable.
+ *
+ * @returns `undefined` to proceed with the write, or the exit code to return.
+ */
+export declare function approve(io: Io, session: Session, action: DestructiveAction): ExitCode | undefined;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAgB,MAAM,0BAA0B,CAAC;AAE5E,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAsC,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAEzF;;;GAGG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,WAAW,CAAC;IACpB,kDAAkD;IAClD,KAAK,EAAE,OAAO,CAAC;IACf,gFAAgF;IAChF,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CAChC;AAED,qBAAa,OAAO;;IAClB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAKb,OAAO,EAAE,cAAc;IAkBnC;;;;;;;;;OASG;IACG,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IAIvC,wEAAwE;IAClE,cAAc,IAAI,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAiDrF;AAED,2EAA2E;AAC3E,MAAM,WAAW,iBAAiB;IAChC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,iBAAiB,GAAG,QAAQ,GAAG,SAAS,CAYjG"}

package/dist/session.js

@@ -0,0 +1,114 @@
+import { AdoClient, WikiApi } from "@floh-solutions/ado-core";
+import { WriteBudget } from "./budget.js";
+import { EXIT_OK, emit, refusal, usageError } from "./output.js";
+export class Session {
+    client;
+    wiki;
+    budget;
+    apply;
+    previewOnly;
+    pretty;
+    #wikiHint;
+    #resolvedWiki;
+    constructor(options) {
+        this.budget = options.budget;
+        this.apply = options.apply;
+        this.previewOnly = options.previewOnly;
+        this.pretty = options.pretty;
+        this.#wikiHint = options.wiki;
+        this.client =
+            options.client
+                ?? AdoClient.fromEnv(options.env, {
+                    ...(options.organization === undefined ? {} : { organization: options.organization }),
+                    ...(options.project === undefined ? {} : { project: options.project }),
+                    // Every write goes through here, whoever issued it.
+                    fetch: options.budget.wrap((input, init) => globalThis.fetch(input, init)),
+                });
+        this.wiki = new WikiApi(this.client.http);
+    }
+    /**
+     * The wiki to act on, resolved once.
+     *
+     * **Ambiguity is refused, not guessed.** A project usually has exactly one
+     * wiki and then there is nothing to decide. When it has several, silently
+     * picking the first means a plan lands in the wrong one and nothing says so —
+     * so the tie is broken only where the answer is unambiguous (a single project
+     * wiki among code wikis, which is the normal mixed case), and otherwise the
+     * names come back with the refusal so the caller can name one.
+     */
+    async wikiIdentifier() {
+        return (await this.#resolveWiki()).name;
+    }
+    /** The project GUID and wiki id an artifact link must be built from. */
+    async wikiForLinking() {
+        const wiki = await this.#resolveWiki();
+        if (wiki.projectId === undefined || wiki.projectId === "") {
+            throw usageError(`The wiki "${wiki.name}" did not report a projectId, so an artifact link cannot be built. `
+                + "A link built with the project NAME is stored by Azure DevOps and resolves for nobody, "
+                + "so this refuses rather than writing one.");
+        }
+        return { name: wiki.name, wikiId: wiki.id, projectId: wiki.projectId };
+    }
+    async #resolveWiki() {
+        if (this.#resolvedWiki !== undefined)
+            return this.#resolvedWiki;
+        const wikis = await this.wiki.listWikis();
+        if (wikis.length === 0) {
+            throw usageError("This project has no wiki.");
+        }
+        if (this.#wikiHint !== undefined && this.#wikiHint !== "") {
+            const hint = this.#wikiHint;
+            const found = wikis.find((candidate) => candidate.name === hint || candidate.id === hint);
+            if (found === undefined) {
+                throw usageError(`No wiki called "${hint}" in this project.`, {
+                    wikis: wikis.map((candidate) => candidate.name),
+                });
+            }
+            this.#resolvedWiki = found;
+            return found;
+        }
+        if (wikis.length === 1) {
+            this.#resolvedWiki = wikis[0];
+            return this.#resolvedWiki;
+        }
+        const projectWikis = wikis.filter((candidate) => candidate.type === "projectWiki");
+        if (projectWikis.length === 1) {
+            this.#resolvedWiki = projectWikis[0];
+            return this.#resolvedWiki;
+        }
+        throw usageError(`This project has ${wikis.length} wikis and no unambiguous default — pass --wiki <name>.`, { wikis: wikis.map((candidate) => candidate.name) });
+    }
+}
+/**
+ * The gate in front of anything that destroys or overwrites.
+ *
+ * Three outcomes, and the difference between the first two is the whole point:
+ *
+ * | invocation | result | exit |
+ * |---|---|---|
+ * | (no flag) | **refused**, with the preview attached | 3 |
+ * | `--dry-run` | preview on stdout — you asked for exactly this | 0 |
+ * | `--yes` | it happens | 0 |
+ *
+ * A bare invocation exits **non-zero**, and that is deliberate. 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"
+ * is how a half-finished job gets reported as done (`docs/pharos-cli-plan.md`
+ * §2.5). `--dry-run` exits 0 because there the preview IS the deliverable.
+ *
+ * @returns `undefined` to proceed with the write, or the exit code to return.
+ */
+export function approve(io, session, action) {
+    if (session.previewOnly) {
+        emit(io, { applied: false, dryRun: true, ...action.would });
+        return EXIT_OK;
+    }
+    if (!session.apply) {
+        throw refusal(`Refusing to ${action.what} without --yes. Nothing was changed.`, {
+            ...action.would,
+            hint: "Re-run with --yes to apply it, or --dry-run to see this without the refusal.",
+        });
+    }
+    return undefined;
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/target.d.ts

@@ -0,0 +1,25 @@
+/**
+ * What a comment verb is addressing: a work item, or a wiki page.
+ *
+ * The two comment surfaces are different APIs with different quirks, but from
+ * where an agent stands they are one idea — "the discussion about this thing" —
+ * so `pharos comment` takes either and the target says which.
+ *
+ * **The rule is that a wiki page is an absolute path, and that is not a
+ * convention invented here.** The Azure DevOps wiki API answers 404 for a page
+ * path without its leading slash; the MCP server's `add_artifact_link` strips
+ * it, which is exactly how links get written that resolve for nobody. So the
+ * spelling that disambiguates is also the only spelling that works, and a
+ * target that omits it is rejected with the reason rather than quietly fixed —
+ * somebody passing `Plans/Foo` has a bug somewhere upstream worth finding.
+ */
+export type Target = {
+    kind: "workItem";
+    id: number;
+} | {
+    kind: "wikiPage";
+    path: string;
+};
+export declare function parseTarget(raw: string): Target;
+export declare function describeTarget(target: Target): string;
+//# sourceMappingURL=target.d.ts.map

package/dist/target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../src/target.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,MAAM,GACd;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAsB/C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/target.js

@@ -0,0 +1,23 @@
+import { usageError } from "./output.js";
+export function parseTarget(raw) {
+    const value = raw.trim();
+    if (/^\d+$/.test(value)) {
+        const id = Number(value);
+        if (id <= 0)
+            throw usageError(`"${raw}" is not a work item id.`, { target: raw });
+        return { kind: "workItem", id };
+    }
+    if (value.startsWith("/")) {
+        if (value === "/") {
+            throw usageError("The wiki root has no comments — name a page.", { target: raw });
+        }
+        return { kind: "wikiPage", path: value };
+    }
+    throw usageError(`Cannot tell what "${raw}" is. 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, not by this tool `
+        + `— it answers 404 without one.`, { target: raw });
+}
+export function describeTarget(target) {
+    return target.kind === "workItem" ? `#${target.id}` : target.path;
+}
+//# sourceMappingURL=target.js.map

package/dist/target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.js","sourceRoot":"","sources":["../src/target.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAqBzC,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAEzB,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACxB,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,EAAE,IAAI,CAAC;YAAE,MAAM,UAAU,CAAC,IAAI,GAAG,0BAA0B,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAClF,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;IAClC,CAAC;IAED,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC1B,IAAI,KAAK,KAAK,GAAG,EAAE,CAAC;YAClB,MAAM,UAAU,CAAC,8CAA8C,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QACpF,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM,UAAU,CACd,qBAAqB,GAAG,oEAAoE;UACxF,4FAA4F;UAC5F,+BAA+B,EACnC,EAAE,MAAM,EAAE,GAAG,EAAE,CAChB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAc;IAC3C,OAAO,MAAM,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC;AACpE,CAAC"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@floh-solutions/pharos-cli",
+  "version": "0.1.0",
+  "description": "Azure DevOps from a headless shell, for an agent: the whole context of a task in one call, and the wiki/comment verbs Microsoft's MCP server does not ship.",
+  "license": "UNLICENSED",
+  "author": "FLOH Solutions",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "pharos": "./dist/bin.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:live": "ADO_LIVE=1 vitest run",
+    "start": "node dist/bin.js"
+  },
+  "dependencies": {
+    "@floh-solutions/ado-core": "workspace:*",
+    "@floh-solutions/plan-to-board": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^3.0.5"
+  }
+}