@floh-solutions/pharos-cli 0.3.0 → 0.12.0

package/dist/commands/link.d.ts

@@ -0,0 +1,40 @@
+import { type ExitCode, type Io } from "../output.js";
+import type { Session } from "../session.js";
+/**
+ * `pharos link` and `pharos unlink` — the relations between work items.
+ *
+ * **`az boards work-item relation add|remove` already exists, so this is only
+ * worth building for the guard** — which is the scope test (#590) applied
+ * honestly rather than a claim of coverage.
+ *
+ * The guard is not decoration. Azure DevOps removes a relation by its POSITION
+ * in the array (`/relations/3`), so an index from a stale read removes a
+ * DIFFERENT link, the request succeeds, and nothing anywhere says so. `unlink`
+ * therefore reads the item, finds the relation by identity, and applies the
+ * removal under a `test` op on the revision that read came from — so if the
+ * array moved in between, the whole patch aborts instead of cutting the wrong
+ * link. `ado-core`'s `removeRelationPatch` is where that lives, and it throws
+ * rather than returning an empty patch when the relation is absent: "already
+ * gone" and "your read was wrong" are different answers and a caller needs to
+ * know which it got.
+ */
+/**
+ * The link kinds, and the direction each one means **from the item named on the
+ * command line**.
+ *
+ * The forward/reverse naming is Azure DevOps' and it is a reliable source of
+ * mistakes: on item X, a `Hierarchy-Reverse` relation points at X's PARENT.
+ * Naming the flags after the relationship rather than the direction is what
+ * stops somebody linking a child where they meant a parent.
+ */
+export declare const LINK_KINDS: Record<string, {
+    rel: string;
+    describes: string;
+}>;
+export interface LinkCommandOptions {
+    kinds: Record<string, number | undefined>;
+    comment: string | undefined;
+}
+export declare function runLink(io: Io, session: Session, positionals: readonly string[], options: LinkCommandOptions): Promise<ExitCode>;
+export declare function runUnlink(io: Io, session: Session, positionals: readonly string[], options: LinkCommandOptions): Promise<ExitCode>;
+//# sourceMappingURL=link.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"link.d.ts","sourceRoot":"","sources":["../../src/commands/link.ts"],"names":[],"mappings":"AAQA,OAAO,EAAuC,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAOzE,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IAC1C,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B;AA6BD,wBAAsB,OAAO,CAC3B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,QAAQ,CAAC,CAyDnB;AAED,wBAAsB,SAAS,CAC7B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,QAAQ,CAAC,CA+BnB"}

package/dist/commands/link.js

@@ -0,0 +1,150 @@
+import { RelationNotFoundError, addRelation, removeRelationPatch, } from "@floh-solutions/ado-core";
+import { emit, emitText, refusal, usageError } from "../output.js";
+/**
+ * `pharos link` and `pharos unlink` — the relations between work items.
+ *
+ * **`az boards work-item relation add|remove` already exists, so this is only
+ * worth building for the guard** — which is the scope test (#590) applied
+ * honestly rather than a claim of coverage.
+ *
+ * The guard is not decoration. Azure DevOps removes a relation by its POSITION
+ * in the array (`/relations/3`), so an index from a stale read removes a
+ * DIFFERENT link, the request succeeds, and nothing anywhere says so. `unlink`
+ * therefore reads the item, finds the relation by identity, and applies the
+ * removal under a `test` op on the revision that read came from — so if the
+ * array moved in between, the whole patch aborts instead of cutting the wrong
+ * link. `ado-core`'s `removeRelationPatch` is where that lives, and it throws
+ * rather than returning an empty patch when the relation is absent: "already
+ * gone" and "your read was wrong" are different answers and a caller needs to
+ * know which it got.
+ */
+/**
+ * The link kinds, and the direction each one means **from the item named on the
+ * command line**.
+ *
+ * The forward/reverse naming is Azure DevOps' and it is a reliable source of
+ * mistakes: on item X, a `Hierarchy-Reverse` relation points at X's PARENT.
+ * Naming the flags after the relationship rather than the direction is what
+ * stops somebody linking a child where they meant a parent.
+ */
+export const LINK_KINDS = {
+    parent: { rel: "System.LinkTypes.Hierarchy-Reverse", describes: "the parent of" },
+    child: { rel: "System.LinkTypes.Hierarchy-Forward", describes: "a child of" },
+    related: { rel: "System.LinkTypes.Related", describes: "related to" },
+    predecessor: { rel: "System.LinkTypes.Dependency-Reverse", describes: "a predecessor of" },
+    successor: { rel: "System.LinkTypes.Dependency-Forward", describes: "a successor of" },
+    duplicate: { rel: "System.LinkTypes.Duplicate-Forward", describes: "a duplicate of" },
+};
+/** Exactly one link kind, or a refusal that lists them. */
+function soleKind(kinds) {
+    const given = Object.entries(kinds).filter(([, id]) => id !== undefined);
+    if (given.length === 0) {
+        throw usageError(`Which relationship? One of ${Object.keys(LINK_KINDS)
+            .map((kind) => `--${kind} <id>`)
+            .join(", ")}.`);
+    }
+    if (given.length > 1) {
+        // Not silently applied one at a time: each is its own revision, so a
+        // partial failure would leave half the links made and no way to tell which.
+        throw usageError(`One relationship at a time; got ${given.map(([flag]) => `--${flag}`).join(" and ")}.`);
+    }
+    const [flag, target] = given[0];
+    return { flag, target: target };
+}
+function id(raw, usage) {
+    if (raw === undefined)
+        throw usageError(usage);
+    if (!/^\d+$/.test(raw))
+        throw usageError(`"${raw}" is not a work item id.`, { given: raw });
+    return Number(raw);
+}
+export async function runLink(io, session, positionals, options) {
+    const from = id(positionals[0], "Which work item? `pharos link <id> --parent <id>`.");
+    const { flag, target } = soleKind(options.kinds);
+    const kind = LINK_KINDS[flag];
+    if (target === from) {
+        throw usageError(`A work item cannot be ${kind.describes} itself (#${from}).`);
+    }
+    // Resolved rather than composed: `addRelation` wants the target's canonical
+    // url, and a target that does not exist fails here by name instead of as an
+    // opaque 400 about a relation.
+    const to = await session.client.workItems.get(target);
+    const url = to.url;
+    if (typeof url !== "string" || url === "") {
+        throw usageError(`Work item #${target} did not report a url, so it cannot be linked.`);
+    }
+    const item = await session.client.workItems.get(from, { expand: "relations" });
+    const existing = relationsOf(item).find((relation) => relation.rel === kind.rel && relation.url === url);
+    if (existing !== undefined) {
+        return report(io, session, {
+            applied: false,
+            unchanged: true,
+            from,
+            to: target,
+            relationship: flag,
+            message: `#${target} is already ${kind.describes} #${from}.`,
+        });
+    }
+    if (session.previewOnly) {
+        return report(io, session, { applied: false, dryRun: true, from, to: target, relationship: flag });
+    }
+    await session.client.workItems.updateWithRev(from, item.rev, [
+        addRelation(kind.rel, url, options.comment === undefined ? undefined : { comment: options.comment }),
+    ], { suppressNotifications: true });
+    return report(io, session, {
+        applied: true,
+        from,
+        to: target,
+        relationship: flag,
+        title: titleOf(to),
+    });
+}
+export async function runUnlink(io, session, positionals, options) {
+    const from = id(positionals[0], "Which work item? `pharos unlink <id> --parent <id>`.");
+    const { flag, target } = soleKind(options.kinds);
+    const kind = LINK_KINDS[flag];
+    const item = await session.client.workItems.get(from, { expand: "relations" });
+    let ops;
+    try {
+        ops = removeRelationPatch(relationsOf(item), item.rev, {
+            kind: "workItem",
+            id: target,
+            rel: kind.rel,
+        });
+    }
+    catch (error) {
+        if (error instanceof RelationNotFoundError) {
+            // Exit 3 rather than 1: nothing is wrong with the connection or the call,
+            // a guard here declined to act on an assumption. The message already says
+            // why removing by position would be worse.
+            throw refusal(error.message, { from, to: target, relationship: flag });
+        }
+        throw error;
+    }
+    if (session.previewOnly) {
+        return report(io, session, { applied: false, dryRun: true, from, to: target, relationship: flag });
+    }
+    await session.client.workItems.update(from, ops, { suppressNotifications: true });
+    return report(io, session, { applied: true, removed: true, from, to: target, relationship: flag });
+}
+function relationsOf(item) {
+    const relations = item.relations;
+    return relations ?? [];
+}
+function titleOf(item) {
+    const title = item.fields?.["System.Title"];
+    return typeof title === "string" ? title : null;
+}
+function report(io, session, result) {
+    if (!session.pretty)
+        return emit(io, result);
+    // The unchanged case carries its own sentence and must use it. Falling through
+    // to the verb table produced "#224 is would be a predecessor of #331", which
+    // is the kind of line that makes somebody doubt what actually happened.
+    if (typeof result["message"] === "string")
+        return emitText(io, result["message"]);
+    const describes = LINK_KINDS[result.relationship]?.describes ?? result.relationship;
+    const verb = result["removed"] === true ? "no longer" : result.applied ? "now" : "would be";
+    return emitText(io, `#${result.to} is ${verb} ${describes} #${result.from}`);
+}
+//# sourceMappingURL=link.js.map

package/dist/commands/link.js.map

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

package/dist/commands/people.d.ts

@@ -0,0 +1,39 @@
+import { type ExitCode, type Io } from "../output.js";
+import type { Session } from "../session.js";
+/**
+ * `pharos people [query]` — who can be mentioned, and the form that mentions
+ * them.
+ *
+ * ## Why this exists, and why its absence was invisible
+ *
+ * **A mention's wire form is `@<{guid}>` and NOTHING ELSE NOTIFIES.** Writing
+ * `@Ada Lovelace` into a comment produces text that reads exactly like a mention
+ * to every human who sees it, links to nobody, and sends no notification. There
+ * is no error and no warning — the comment posts, looks right, and quietly
+ * reaches no one.
+ *
+ * So a session that wanted to mention somebody had two ways to fail and no way
+ * to succeed: guess the guid, or write the readable form and never learn it did
+ * nothing. This verb is the missing half.
+ *
+ * ## Where the names come from
+ *
+ * **The board's own work items**, not an identity endpoint. That is deliberate:
+ * the identity APIs live on a different host (`vssps.dev.azure.com`) and want
+ * scopes a work-scoped PAT does not have, so a `pharos` configured exactly as
+ * the setup instructions say would get a 401 from a verb that looks like it
+ * should work. Every person who has been assigned work, created it or changed it
+ * is already in the items themselves, at no extra scope and no extra call
+ * beyond the query.
+ *
+ * The consequence is worth stating rather than discovering: **somebody who has
+ * never touched an item on this board will not be listed.** For mentioning
+ * people about work, that is nearly always the right set — and when it is not,
+ * the guid from any Azure DevOps url works just as well in `@<…>`.
+ */
+export interface PeopleCommandOptions {
+    /** Cap the items scanned. More items, more people, slower. */
+    top: number | undefined;
+}
+export declare function runPeople(io: Io, session: Session, positionals: readonly string[], options: PeopleCommandOptions): Promise<ExitCode>;
+//# sourceMappingURL=people.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"people.d.ts","sourceRoot":"","sources":["../../src/commands/people.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,MAAM,WAAW,oBAAoB;IACnC,8DAA8D;IAC9D,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACzB;AAYD,wBAAsB,SAAS,CAC7B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAmDnB"}

package/dist/commands/people.js

@@ -0,0 +1,64 @@
+import { emit, emitText } from "../output.js";
+export async function runPeople(io, session, positionals, options) {
+    const query = positionals[0]?.trim().toLowerCase() ?? "";
+    const top = options.top ?? 200;
+    // Every item, including finished work: a person who closed everything they
+    // ever had is still a person worth mentioning.
+    const ids = await session.client.wiql.queryIds(`SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project `
+        + `ORDER BY [System.ChangedDate] DESC`);
+    const wanted = ids.slice(0, top);
+    const found = new Map();
+    if (wanted.length > 0) {
+        const items = await session.client.workItems.getBatch(wanted, {
+            fields: ["System.AssignedTo", "System.CreatedBy", "System.ChangedBy"],
+        });
+        for (const item of items) {
+            record(found, item.fields?.["System.AssignedTo"], "assigned");
+            record(found, item.fields?.["System.CreatedBy"], "created");
+            record(found, item.fields?.["System.ChangedBy"], "changed");
+        }
+    }
+    const people = [...found.values()]
+        .filter((person) => query === ""
+        || person.displayName.toLowerCase().includes(query)
+        || person.uniqueName.toLowerCase().includes(query))
+        .sort((a, b) => a.displayName.localeCompare(b.displayName));
+    if (session.pretty) {
+        if (people.length === 0) {
+            emitText(io, query === "" ? "Nobody on this board yet." : `Nobody matching "${query}".`);
+            return 0;
+        }
+        for (const person of people) {
+            emitText(io, `${person.mention}  ${person.displayName} <${person.uniqueName}>`);
+        }
+        emitText(io, "");
+        emitText(io, "Paste the @<…> form into a comment or a description. The readable form "
+            + "(@Name) notifies nobody.");
+        return 0;
+    }
+    emit(io, { scanned: wanted.length, people });
+    return 0;
+}
+/** One identity field, folded into the set. */
+function record(into, value, seenAs) {
+    if (value === null || typeof value !== "object")
+        return;
+    const identity = value;
+    const id = identity.id;
+    if (id === undefined || id === "")
+        return;
+    const existing = into.get(id);
+    if (existing !== undefined) {
+        if (!existing.seenAs.includes(seenAs))
+            existing.seenAs.push(seenAs);
+        return;
+    }
+    into.set(id, {
+        displayName: identity.displayName ?? id,
+        uniqueName: identity.uniqueName ?? "",
+        id,
+        mention: `@<${id}>`,
+        seenAs: [seenAs],
+    });
+}
+//# sourceMappingURL=people.js.map

package/dist/commands/people.js.map

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

package/dist/commands/query.d.ts

@@ -0,0 +1,43 @@
+import { type ExitCode, type Io } from "../output.js";
+import type { Session } from "../session.js";
+/**
+ * `pharos query` — the verb whose absence made every session start with `curl`.
+ *
+ * A real session was asked what was assigned to @user. It spent 1m16s and five
+ * calls — two on `--help`, one checking environment variables setup had already
+ * written, two more on per-command help — and then gave up on this CLI and hit
+ * the WIQL endpoint directly, because `task` takes one id and nothing here
+ * answered "what is assigned to me". That is the most common opening question
+ * anybody asks a board.
+ *
+ * ## Why the output is hydrated items rather than ids
+ *
+ * WIQL returns **references only** — ids, never field values, however many
+ * columns the SELECT names. The curl recipe this replaces therefore handed back
+ * sixteen bare numbers, which is not an answer to any question somebody asked.
+ * `queryAndFetch` runs the query and then hydrates through `workitemsbatch` in
+ * pages of 200; both routes are read-shaped POSTs and neither counts against
+ * the write budget.
+ *
+ * ## Why it says how it decided "open"
+ *
+ * Because the answer is uninterpretable without it. "12 open" means nothing
+ * until you know which states were counted as finished, and Azure DevOps lets a
+ * process template rename every one of them. See {@link Openness}.
+ */
+export interface QueryCommandOptions {
+    mine: boolean;
+    assignee: string | undefined;
+    states: readonly string[];
+    types: readonly string[];
+    sprint: string | undefined;
+    area: string | undefined;
+    tags: readonly string[];
+    all: boolean;
+    team: string | undefined;
+    top: number | undefined;
+    /** The escape hatch: a statement written by hand, used verbatim. */
+    wiql: string | undefined;
+}
+export declare function runQuery(io: Io, session: Session, options: QueryCommandOptions): Promise<ExitCode>;
+//# sourceMappingURL=query.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/commands/query.ts"],"names":[],"mappings":"AAEA,OAAO,EAA8B,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAG7C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,oEAAoE;IACpE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1B;AAgBD,wBAAsB,QAAQ,CAC5B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAsEnB"}

package/dist/commands/query.js

@@ -0,0 +1,202 @@
+import { authenticatedIdentity } from "@floh-solutions/ado-core";
+import { emit, emitText, usageError } from "../output.js";
+import { buildWiql, opennessFor } from "../wiql-build.js";
+/** What the hydrate step asks for. Anything a type does not have is simply absent. */
+const FIELDS = [
+    "System.Id",
+    "System.WorkItemType",
+    "System.Title",
+    "System.State",
+    "System.AssignedTo",
+    "System.IterationPath",
+    "System.AreaPath",
+    "System.Tags",
+    "System.ChangedDate",
+    "Microsoft.VSTS.Common.Priority",
+];
+export async function runQuery(io, session, options) {
+    if (options.mine && options.assignee !== undefined) {
+        throw usageError("Pass either --mine or --assignee, not both — they filter the same field and would AND "
+            + "together into a query that can never match.");
+    }
+    const filters = {
+        mine: options.mine,
+        assignee: options.assignee,
+        states: options.states,
+        types: options.types,
+        sprint: options.sprint,
+        area: options.area,
+        tags: options.tags,
+        all: options.all,
+        ...(session.client.project === undefined ? {} : { project: session.client.project }),
+    };
+    let statement;
+    let openness;
+    if (options.wiql !== undefined) {
+        if (describesFilters(options)) {
+            throw usageError("--wiql is the whole statement, so the other filters would be silently ignored. Pass "
+                + "--wiql alone, or drop it and use the flags.");
+        }
+        statement = options.wiql;
+        openness = { source: "none", terminal: [], note: "Your statement, used verbatim." };
+    }
+    else {
+        // Only read the catalogue when the answer depends on it. `--all` and an
+        // explicit `--state` both decide openness without asking the project, and a
+        // request nobody needs is a request that can fail for nobody's benefit.
+        let catalog;
+        let failure;
+        if (!options.all && options.states.length === 0) {
+            try {
+                catalog = await session.client.workItemTypes.states();
+            }
+            catch (error) {
+                // NOT fatal. A token without the work-item-type read still queries fine;
+                // it just cannot be told what "finished" means here, and saying so and
+                // guessing beats refusing to answer at all.
+                failure = error instanceof Error ? error.message : String(error);
+            }
+        }
+        openness = opennessFor(filters, catalog, failure);
+        statement = buildWiql(filters, openness, catalog);
+    }
+    const items = await session.client.wiql.queryAndFetch(statement, {
+        fields: FIELDS,
+        ...(options.top === undefined ? {} : { top: options.top }),
+        ...(options.team === undefined ? {} : { team: options.team }),
+    });
+    const result = {
+        count: items.length,
+        ...(items.length === 0 ? { emptyBecause: silentFilters(options) } : {}),
+        // Emitted so a caller can see exactly what ran — and edit it into --wiql
+        // when the flags do not reach far enough.
+        wiql: statement,
+        openness,
+        assignedTo: options.mine ? await resolveMe(session) : (options.assignee ?? null),
+        items: items.map(summarise),
+    };
+    return session.pretty ? emitText(io, render(result)) : emit(io, result);
+}
+/**
+ * Which filters could have emptied this result **without anybody being told**.
+ *
+ * An empty list and exit 0 is a successful query that matched nothing, and a
+ * session reports it as a fact about the board. That is right for most filters
+ * and dangerous for the ones Azure DevOps does not validate:
+ *
+ * - `--sprint` and `--area` are SAFE and it is worth saying so, because it is
+ *   the opposite of what you would guess: a path that does not exist answers
+ *   `TF51011` naming the path, so a wrong one fails loudly. Measured.
+ * - `--assignee` is the silent one. An identity Azure DevOps has never heard of
+ *   is not an error — it simply matches nothing, so "0 items assigned to
+ *   ada@contoso.com" and "you spelt it wrong" are the same output.
+ * - `--tag` is a substring match against a semicolon-joined string, so a
+ *   plausible-looking tag that is not on anything reads the same way.
+ * - `--state` is checked on `update` but not here, because a query naming
+ *   several states across several types is legitimate.
+ *
+ * Named rather than counted: telling somebody "this might be wrong" without
+ * saying which flag is the one to re-read is a warning they cannot act on.
+ */
+function silentFilters(options) {
+    const suspects = [];
+    if (options.assignee !== undefined) {
+        suspects.push(`--assignee "${options.assignee}" — Azure DevOps does not reject an identity it does not `
+            + "know; it matches nothing. `pharos whoami` shows the form your own identity takes.");
+    }
+    for (const tag of options.tags) {
+        suspects.push(`--tag "${tag}" — a substring match; no error if nothing carries it.`);
+    }
+    for (const state of options.states) {
+        suspects.push(`--state "${state}" — run \`pharos types\` to see what each type accepts.`);
+    }
+    return suspects.length === 0 ? undefined : suspects;
+}
+/** Whether anything other than `--wiql` was asked for. */
+function describesFilters(options) {
+    return (options.mine
+        || options.assignee !== undefined
+        || options.states.length > 0
+        || options.types.length > 0
+        || options.tags.length > 0
+        || options.sprint !== undefined
+        || options.area !== undefined);
+}
+/**
+ * Who `@Me` actually was.
+ *
+ * The macro resolves server-side against whoever owns `ADO_PAT`, which is not
+ * necessarily the person reading the output — a shared or service token makes
+ * "assigned to me" quietly mean somebody else. One GET, and it never fails the
+ * query: an unnameable identity is reported as such.
+ */
+async function resolveMe(session) {
+    try {
+        const identity = await authenticatedIdentity(session.client.http);
+        return identity.displayName ?? identity.uniqueName ?? "@Me (unnamed)";
+    }
+    catch {
+        return "@Me — whoever owns ADO_PAT; the identity could not be read";
+    }
+}
+function summarise(item) {
+    const fields = item.fields ?? {};
+    const text = (name) => {
+        const value = fields[name];
+        return typeof value === "string" && value !== "" ? value : undefined;
+    };
+    const tags = text("System.Tags");
+    const priority = fields["Microsoft.VSTS.Common.Priority"];
+    return {
+        id: item.id,
+        type: text("System.WorkItemType"),
+        title: text("System.Title"),
+        state: text("System.State"),
+        assignedTo: displayName(fields["System.AssignedTo"]),
+        iteration: text("System.IterationPath"),
+        tags: tags === undefined ? [] : tags.split(";").map((tag) => tag.trim()).filter((tag) => tag !== ""),
+        priority: typeof priority === "number" ? priority : undefined,
+        changed: text("System.ChangedDate"),
+    };
+}
+/** `null` rather than absent: unassigned is an answer, and a common one. */
+function displayName(value) {
+    if (typeof value === "string" && value !== "")
+        return value;
+    if (typeof value === "object" && value !== null) {
+        const display = value.displayName;
+        if (typeof display === "string")
+            return display;
+    }
+    return null;
+}
+/**
+ * The human rendering.
+ *
+ * The openness note is at the BOTTOM rather than the top: it is the thing to
+ * check when the list looks wrong, and putting a paragraph of caveat above the
+ * answer buries the answer.
+ */
+function render(result) {
+    const lines = [];
+    const who = result.assignedTo === null ? "" : ` assigned to ${result.assignedTo}`;
+    lines.push(`${result.count} work item${result.count === 1 ? "" : "s"}${who}`, "");
+    if (result.items.length === 0) {
+        lines.push("  (nothing matched — this is a successful query, not a failure)");
+        for (const suspect of result.emptyBecause ?? [])
+            lines.push(`  ${suspect}`);
+    }
+    for (const item of result.items) {
+        const assignee = item.assignedTo ?? "unassigned";
+        lines.push(`  #${String(item.id ?? "?").padEnd(6)} ${(item.type ?? "").padEnd(10)} `
+            + `${(item.state ?? "").padEnd(12)} ${(item.title ?? "(untitled)").slice(0, 60).padEnd(60)} ${assignee}`);
+    }
+    if (result.openness.note !== undefined) {
+        lines.push("", `openness: ${result.openness.note}`);
+    }
+    if (result.openness.terminal.length > 0) {
+        lines.push(`treated as finished: ${result.openness.terminal.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+//# sourceMappingURL=query.js.map

package/dist/commands/query.js.map

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

package/dist/commands/recycle.d.ts

@@ -0,0 +1,10 @@
+import { type ExitCode, type Io } from "../output.js";
+import { type Session } from "../session.js";
+export declare function runDelete(io: Io, session: Session, positionals: readonly string[]): Promise<ExitCode>;
+export declare function runRestore(io: Io, session: Session, positionals: readonly string[]): Promise<ExitCode>;
+export interface DeletedCommandOptions {
+    /** How many to name. The bin is not usually small. */
+    top: number;
+}
+export declare function runDeleted(io: Io, session: Session, options: DeletedCommandOptions): Promise<ExitCode>;
+//# sourceMappingURL=recycle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"recycle.d.ts","sourceRoot":"","sources":["../../src/commands/recycle.ts"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,QAAQ,EAAE,KAAK,EAAE,EAAE,MAAM,cAAc,CAAC;AAClF,OAAO,EAAW,KAAK,OAAO,EAAE,MAAM,eAAe,CAAC;AA0CtD,wBAAsB,SAAS,CAC7B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,QAAQ,CAAC,CA8BnB;AAED,wBAAsB,UAAU,CAC9B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,WAAW,EAAE,SAAS,MAAM,EAAE,GAC7B,OAAO,CAAC,QAAQ,CAAC,CAYnB;AAED,MAAM,WAAW,qBAAqB;IACpC,sDAAsD;IACtD,GAAG,EAAE,MAAM,CAAC;CACb;AAED,wBAAsB,UAAU,CAC9B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,QAAQ,CAAC,CAyCnB"}