@floh-solutions/pharos-cli 0.26.1 → 0.27.0

package/dist/commands/search.js

@@ -0,0 +1,200 @@
+import { AdoSearchQueryError } from "@floh-solutions/ado-core";
+import { emit, emitText, usageError } from "../output.js";
+const DEFAULT_TOP = 25;
+export async function runSearch(io, session, rest, options) {
+    if (options.itemsOnly && options.wikiOnly) {
+        throw usageError("Pass either --items or --wiki, not both. Passing neither searches both, which is the "
+            + "default and almost always what you want.");
+    }
+    // Every remaining positional is a term, so `pharos search wiki import` works
+    // without quoting. Quoting still behaves identically.
+    const terms = rest.join(" ").trim();
+    if (terms === "") {
+        throw usageError('A search needs terms: pharos search "retry backoff". Azure DevOps answers an empty '
+            + "query with 400, so this is refused here rather than paid for as a round trip.");
+    }
+    const filters = {};
+    // PascalCase on the way in, lowercase on the way back — the endpoint's own
+    // asymmetry, absorbed in ado-core. See WorkItemSearchOptions.filters.
+    if (options.types.length > 0)
+        filters["System.WorkItemType"] = options.types;
+    if (options.states.length > 0)
+        filters["System.State"] = options.states;
+    if (options.wikiOnly && (options.types.length > 0 || options.states.length > 0)) {
+        throw usageError("--type and --state filter work items, and --wiki excludes work items — so this search "
+            + "would silently ignore them. Drop --wiki, or drop the filters.");
+    }
+    const top = options.top ?? DEFAULT_TOP;
+    const shared = {
+        top,
+        ...(options.skip === undefined ? {} : { skip: options.skip }),
+        ...(options.org ? { orgWide: true } : {}),
+    };
+    const problems = [];
+    const search = session.client.search;
+    const [items, wiki] = await Promise.all([
+        options.wikiOnly
+            ? undefined
+            : search
+                .workItems(terms, { ...shared, ...(Object.keys(filters).length === 0 ? {} : { filters }) })
+                .catch((error) => {
+                problems.push(`work item search failed: ${describe(error)}`);
+                return undefined;
+            }),
+        options.itemsOnly
+            ? undefined
+            : search.wiki(terms, shared).catch((error) => {
+                problems.push(`wiki search failed: ${describe(error)}`);
+                return undefined;
+            }),
+    ]);
+    // Both halves refused: that is a failed search, not an empty one. Exit
+    // non-zero so a caller checking only the status does not read it as "nothing
+    // is written about this anywhere".
+    if (items === undefined && wiki === undefined && problems.length > 0) {
+        throw usageError(problems.join(" | "));
+    }
+    const result = {
+        terms,
+        scope: options.org ? "organization" : "project",
+        ...(items === undefined
+            ? {}
+            : {
+                workItems: {
+                    count: items.count,
+                    returned: items.results.length,
+                    ...(items.emptyBecause === undefined ? {} : { emptyBecause: items.emptyBecause }),
+                    results: items.results.map(workItemSummary),
+                },
+            }),
+        ...(wiki === undefined
+            ? {}
+            : {
+                wiki: {
+                    count: wiki.count,
+                    returned: wiki.results.length,
+                    ...(wiki.emptyBecause === undefined ? {} : { emptyBecause: wiki.emptyBecause }),
+                    results: wiki.results.map(wikiSummary),
+                },
+            }),
+        // Stated whenever a total exceeds what was returned, because "6 results"
+        // and "6 of 97" are different answers and only one of them is honest.
+        ...(truncationNote(items?.count, items?.results.length, wiki?.count, wiki?.results.length, top) ?? {}),
+        problems,
+    };
+    return session.pretty ? emitText(io, render(result)) : emit(io, result);
+}
+function workItemSummary(result) {
+    return {
+        id: result.id,
+        type: result.type,
+        title: result.title,
+        state: result.state,
+        assignedTo: result.assignedTo,
+        tags: result.tags,
+        changed: result.changed,
+        matched: result.hits.map((hit) => ({ field: hit.field, text: hit.highlights })),
+    };
+}
+function wikiSummary(result) {
+    return {
+        path: result.path,
+        wiki: result.wiki,
+        matched: result.hits.map((hit) => ({ field: hit.field, text: hit.highlights })),
+    };
+}
+/**
+ * Say so when the page is smaller than the total.
+ *
+ * Measured: a broad term reports `count: 97` while returning the `$top` asked
+ * for. A caller that reports the page size as the answer tells somebody there
+ * are three of something when there are ninety-seven.
+ */
+function truncationNote(itemCount, itemReturned, wikiCount, wikiReturned, top) {
+    const truncated = (itemCount !== undefined && itemReturned !== undefined && itemCount > itemReturned)
+        || (wikiCount !== undefined && wikiReturned !== undefined && wikiCount > wikiReturned);
+    if (!truncated)
+        return undefined;
+    return {
+        more: `Showing the first ${top} of each. "count" is the true total — raise --top or page with `
+            + "--skip to see the rest.",
+    };
+}
+function describe(error) {
+    if (error instanceof AdoSearchQueryError)
+        return error.message;
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The human rendering.
+ *
+ * The matching line is the point, so it is indented under its result rather
+ * than summarised away — a list of page paths answers "how many" when the
+ * question was "where".
+ */
+function render(result) {
+    const lines = [`"${result.terms}" across the ${result.scope}`, ""];
+    if (result.workItems !== undefined) {
+        const { count, returned, results } = result.workItems;
+        lines.push(`WORK ITEMS — ${count}${count > returned ? ` (showing ${returned})` : ""}`);
+        if (results.length === 0) {
+            lines.push(`  ${result.workItems.emptyBecause ?? "(nothing matched)"}`);
+        }
+        for (const item of results) {
+            lines.push(`  #${String(item.id ?? "?").padEnd(6)} ${(item.type ?? "").padEnd(10)} `
+                + `${(item.state ?? "").padEnd(12)} ${item.title ?? "(untitled)"}`);
+            for (const line of matchLines(item.matched, (hit, text) => `${hit}: ${text}`)) {
+                lines.push(`      ${line}`);
+            }
+        }
+        lines.push("");
+    }
+    if (result.wiki !== undefined) {
+        const { count, returned, results } = result.wiki;
+        lines.push(`WIKI — ${count}${count > returned ? ` (showing ${returned})` : ""}`);
+        if (results.length === 0) {
+            lines.push(`  ${result.wiki.emptyBecause ?? "(nothing matched)"}`);
+        }
+        for (const page of results) {
+            lines.push(`  ${page.path ?? "(unknown path)"}`);
+            for (const line of matchLines(page.matched, (_hit, text) => text)) {
+                lines.push(`      ${line}`);
+            }
+        }
+        lines.push("");
+    }
+    if (result.more !== undefined)
+        lines.push(result.more);
+    if (result.problems.length > 0) {
+        lines.push("", "problems:");
+        for (const problem of result.problems)
+            lines.push(`  - ${problem}`);
+    }
+    return lines.join("\n").trimEnd();
+}
+/**
+ * At most {@link SHOWN_PER_RESULT} matching lines per result, and it SAYS when
+ * it dropped some.
+ *
+ * A single work item can match on a dozen passages across its description and
+ * its discussion, and one result then fills a screen. The JSON keeps every one
+ * of them — this cap is the human rendering only. It is stated rather than
+ * silent: a reader who cannot tell a complete list from a truncated one has to
+ * re-run the search to find out.
+ */
+const SHOWN_PER_RESULT = 4;
+function matchLines(matched, format) {
+    const all = matched.flatMap((hit) => hit.text.map((text) => format(hit.field, oneLine(text))));
+    if (all.length <= SHOWN_PER_RESULT)
+        return all;
+    return [
+        ...all.slice(0, SHOWN_PER_RESULT),
+        `… and ${all.length - SHOWN_PER_RESULT} more matching lines (the JSON output has all of them)`,
+    ];
+}
+/** Highlights carry real newlines; a match is one line in a list. */
+function oneLine(text) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length > 160 ? `${flat.slice(0, 157)}…` : flat;
+}
+//# sourceMappingURL=search.js.map

package/dist/commands/search.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floh-solutions/pharos-cli",
-  "version": "0.26.1",
+  "version": "0.27.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",
@@ -24,8 +24,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@floh-solutions/ado-core": "0.10.0",
-    "@floh-solutions/gh-core": "0.2.1",
+    "@floh-solutions/ado-core": "0.11.0",
+    "@floh-solutions/gh-core": "0.3.0",
     "@floh-solutions/plan-to-board": "0.1.1"
   },
   "devDependencies": {

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pharos
-description: "Use for AZURE DEVOPS work — when the user says Azure DevOps, ADO or dev.azure.com, or names an ADO work item by number (\"pick up 4821\", \"what's on 210\"). Covers reading or updating an ADO work item, ticket, bug, story or epic; the ADO board, backlog, sprint or iteration; what is assigned to you; reading or writing an ADO wiki page and its comments; linking a plan to an epic; attaching a file to a work item or taking one off; inline images in a field or wiki page; @mentioning somebody so they are notified; importing Markdown, Word or PDF as wiki pages; and whether a failed call is retryable. ALSO the GITHUB ISSUE ↔ work item EDGE: adopting an issue as a work item linked at both ends, bulk-adopting a repo, one reply reaching reporter and board, where they have drifted, closing both ends together, and changing a comment that ALREADY EXISTS: editing, deleting, reacting, hiding, pinning. NOT a GitHub CLI: listing or viewing an issue, or POSTING a comment, is `gh`'s job. NOT for other trackers — Argus, Jira, Linear."
+description: "Use for AZURE DEVOPS work — when the user says Azure DevOps, ADO or dev.azure.com, or names an ADO work item by number (\"pick up 4821\"). Covers reading or updating a work item, bug, story or epic; the board, backlog, sprint or iteration; what is assigned to you; reading or writing a wiki page and its comments; searching the board and wiki for a phrase; linking a plan to an epic; attaching a file to a work item or taking one off; inline images in a field or page; @mentioning somebody so they are notified; importing Markdown, Word or PDF as pages; and whether a call is retryable. ALSO the GITHUB ISSUE ↔ work item EDGE: adopting an issue as a work item linked at both ends, bulk-adopting a repo, one reply reaching both, where they drifted, closing both ends together, a PULL REQUEST and its work item, and changing a comment that ALREADY EXISTS: editing, deleting, reacting, hiding, pinning. NOT a GitHub CLI: listing or viewing an issue, or POSTING a comment, is `gh`'s job. NOT for other trackers — Argus, Jira, Linear."
 license: Proprietary
 ---
 
@@ -17,6 +17,12 @@ whoami                         who ADO_PAT belongs to. @Me resolves to this
 types                          what --state and --type will ACCEPT, per type
 query                          WHICH work items — assigned to you, in a sprint,
                                of a type, still open. Hydrated items, not ids.
+search <terms...>              WHERE something is WRITTEN — full text across
+                               work items AND wiki pages, in one call. Reaches
+                               descriptions, discussion and page bodies, which
+                               `query` cannot. Each result carries the MATCHING
+                               LINE. --items / --wiki to narrow, --org for the
+                               whole organisation, --top (default 25)
 task <id>                      one work item, whole: fields, comments,
                                attachments, relations WITH titles, and the
                                content + discussion of every linked wiki page
@@ -78,6 +84,13 @@ issue say <owner/name#45>      ONE message, TWO audiences: the whole of it to
                                comment's URL to the board. --summary
 issue trail <id|owner/name#45> the whole trail from EITHER end, with the
                                evidence for each half. Read-only
+pr <owner/name#123>            a PULL REQUEST and the work it belongs to:
+                               state, draft, review verdict, WHICH CHECKS ARE
+                               RED, the issues it closes, and the work items it
+                               reaches — via AB#123 in the body OR via an
+                               adopted issue named by "Fixes #45". Also where
+                               the pull request and the board DISAGREE
+                               --no-work-items  skip the transitive lookup
 issue drift                    where the two platforms DISAGREE — the report no
                                other tool can produce. --repo --limit --wiql
 issue backfill <owner/name>    bulk adopt every issue the board does not link
@@ -188,6 +201,135 @@ It parses, returns 200, and matches **everything** — `IN GROUP` covers work it
 TYPE categories only, and an unknown group resolves to the empty set with no
 error. Measured, 2026-08-05.
 
+## After adoption, the work becomes code: `pharos pr`
+
+`issue trail` follows filing -> adoption -> close. It stops at the moment the
+work becomes a branch. `pharos pr` is the part that does not.
+
+```bash
+pharos pr contoso/widgets#123              # the pull request AND the board
+pharos pr contoso/widgets#123 --pretty
+pharos pr contoso/widgets#123 --no-work-items   # skip the transitive lookup
+```
+
+One call replaces `gh pr view` + `gh pr checks` + a WIQL query + a relations
+read, across two credentials — and answers one question none of them can.
+
+**Two paths reach a work item, and the implicit one is the one that fires:**
+
+| | |
+|---|---|
+| `AB#4821` in the body | explicit. What Azure Boards' own app reads |
+| `Fixes #45`, where #45 is adopted | **the one that actually happens** |
+
+The second costs one read per closed issue (its comments, where the `pharos:v1`
+trailer lives) and is why `--no-work-items` exists for when you do not need it.
+
+### `disagreements` is the part nothing else can produce
+
+```jsonc
+{
+  "pullRequest": { "number": 123, "state": "MERGED", "merged": true,
+                   "review": "APPROVED", "checks": "FAILURE",
+                   "failingChecks": [ { "name": "e2e-tests", "conclusion": "FAILURE" } ] },
+  "closesIssues": [45],
+  "workItems": [ { "id": 4821, "type": "Issue", "state": "To Do", "title": "…" } ],
+  "disagreements": [
+    "#4821 is \"To Do\" but this pull request is already MERGED — the work shipped and the board never moved."
+  ],
+  "problems": []
+}
+```
+
+Azure DevOps cannot see the pull request and GitHub does not know the work item
+exists, so **neither system will ever report this**. An empty `disagreements`
+means they agree; it is silent when there is nothing to say.
+
+Three things about the shape:
+
+- **`checks` is the rollup and it is authoritative. `failingChecks` names the
+  red ones** — found by filtering every context, not by showing the first few.
+  Measured: real pull requests report a `FAILURE` rollup while their first
+  several contexts all read `SUCCESS`, because the red one is further down.
+- **`NONE` is not `SUCCESS`.** A pull request with no checks configured reports
+  `NONE`, and a still-running one is `PENDING`, not a failure.
+- **`state` has three values** — `OPEN`, `CLOSED`, `MERGED`. Merged is its own
+  state, not a kind of closed, and `merged: true` is the field to test.
+
+Posting a comment on a pull request is still `gh`'s job, exactly as it is for an
+issue. This verb reads; it does not write.
+
+## Finding where it is WRITTEN: `pharos search`
+
+`query` answers *which work items*. `search` answers *where has this been
+written about* — and they are not the same question.
+
+```bash
+pharos search "retry backoff"              # work items AND wiki, one call
+pharos search retry backoff                # quoting is optional
+pharos search "sprint policy" --wiki       # pages only
+pharos search "flaky" --items --type Bug   # work items only, filtered
+pharos search "onboarding" --org           # the whole organisation
+```
+
+**This is the only way to reach text nobody linked.** `pharos task <id>` returns
+the content of every wiki page **linked** to the item — and you can only follow
+a link somebody already made. A design written on a page and never attached to
+the work item is invisible to every other verb here. That is what this finds.
+
+It is also full text. `query --wiql … CONTAINS` matches **titles**; this matches
+descriptions, the discussion, and page bodies.
+
+### What it returns
+
+```jsonc
+{
+  "terms": "retry backoff",
+  "scope": "project",                  // or "organization" with --org
+  "workItems": {
+    "count": 97,                       // the TRUE TOTAL, not what was returned
+    "returned": 25,
+    "results": [
+      { "id": 373, "type": "Issue", "state": "Doing",
+        "title": "…", "assignedTo": "Ada Lovelace", "tags": ["api"],
+        "matched": [                   // WHY this matched — the line itself
+          { "field": "System.Description",
+            "text": ["the backoff doubles each attempt"] } ] }
+    ]
+  },
+  "wiki": {
+    "count": 8, "returned": 8,
+    "results": [
+      { "path": "/Roadmap.md", "wiki": "Contoso.wiki",
+        "matched": [ { "field": "content", "text": ["…one page per feature."] } ] }
+    ]
+  },
+  "more": "Showing the first 25 of each…",   // only when count > returned
+  "problems": []
+}
+```
+
+Four things about that shape, because guessing any of them costs a failed parse:
+
+- **`count` is the total, `returned` is what you got.** They differ constantly —
+  a broad term reports 97 and hands you 25. Reporting `count` as "results I can
+  see" is wrong; reporting `returned` as the total is worse.
+- **`matched[].text` is plain text.** The API wraps hits in `<highlighthit>`
+  markers; they are stripped before you see them.
+- **Field names are normalised to `System.Description`**, the casing everything
+  else here uses. The endpoint itself answers `system.description`.
+- **A surface that failed lands in `problems[]`** and the other still returns —
+  a token that reads the wiki but not work items gets the wiki half. If
+  `problems` is non-empty, say so before reasoning from the result. Both halves
+  failing is a non-zero exit, not an empty answer.
+
+### Code search is NOT here
+
+It needs the Code Search extension installed on the organisation, which a token
+cannot grant. Asking for it would return an empty result that means "not
+provisioned" rather than "no matches", so the verb does not offer it at all.
+`pharos doctor` reports whether this organisation has it.
+
 ## Changing a work item
 
 ```bash