pm-github 2026.8.7 → 2026.8.15

package/dist/index.js

@@ -43,10 +43,16 @@ export function resolveGitHubToken() {
     return undefined;
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-// Decide whether the Authorization token may be forwarded to a redirect target.
-// Only same-origin (scheme + host + port) redirects keep the credential; any
-// origin change drops it to avoid leaking the token. Exported for
-// unit testing.
+/**
+ * Decide whether the Authorization token may be forwarded across a redirect.
+ *
+ * Only same-origin (scheme + host + port) redirects keep the credential; any
+ * origin change drops it so the bearer token can never leak to a third party.
+ *
+ * @param fromUrl - The URL the redirect originated from.
+ * @param toUrl - The redirect target URL.
+ * @returns True when both URLs share an origin.
+ */
 export function sameOrigin(fromUrl, toUrl) {
     try {
         return new URL(fromUrl).origin.toLowerCase() === new URL(toUrl).origin.toLowerCase();
@@ -102,9 +108,14 @@ export function githubApiBase() {
     // Strip a trailing slash so `${base}/repos/...` cannot produce `//repos/...`.
     return raw.replace(/\/+$/, "");
 }
-// One low-level request, no retry/backoff (that lives in `request`). Follows up
-// to `redirectsLeft` redirects; a cycle or an over-long chain rejects instead of
-// overflowing the stack, and the token is only forwarded to same-host targets.
+/**
+ * One low-level HTTP request, with no retry or backoff.
+ *
+ * That orchestration lives in the surrounding {@link request} wrapper. This
+ * function follows up to `redirectsLeft` redirects, rejecting on a cycle or an
+ * over-long chain rather than overflowing the stack, and forwards the bearer
+ * token only to same-origin targets via {@link sameOrigin}.
+ */
 function requestOnce(method, url, token, payload, redirectsLeft = 5) {
     return new Promise((resolve, reject) => {
         const headers = {
@@ -170,10 +181,20 @@ function requestOnce(method, url, token, payload, redirectsLeft = 5) {
         req.end();
     });
 }
-// How long (ms) to wait before retrying a rate-limited / transient response.
-// Honors Retry-After (seconds) and the primary-rate-limit reset window
-// (X-RateLimit-Remaining: 0 + X-RateLimit-Reset epoch), then falls back to
-// exponential backoff. Capped so we never hang a CLI run indefinitely.
+/**
+ * Compute how long (ms) to wait before retrying a rate-limited or transient
+ * response.
+ *
+ * Honors `Retry-After` (seconds) and the primary rate-limit reset window
+ * (`X-RateLimit-Remaining: 0` + `X-RateLimit-Reset` epoch), then falls back to
+ * exponential backoff. The result is capped so a CLI run is never hung
+ * indefinitely.
+ *
+ * @param headers - Response headers to read the retry hints from.
+ * @param attempt - Zero-based retry index feeding the exponential backoff floor.
+ * @param nowMs - Current epoch ms, used to measure the reset window's remaining time.
+ * @returns The capped wait in milliseconds.
+ */
 export function computeBackoffMs(headers, attempt, nowMs = Date.now()) {
     const get = (k) => {
         const v = headers[k] ?? headers[k.toLowerCase()];
@@ -449,7 +470,17 @@ export const EXIT_CODE = {
     USAGE: 2,
     NOT_FOUND: 3,
 };
+/**
+ * Error that carries a semantic process exit code.
+ *
+ * pm's command runtime treats a thrown error as a cleanly handled non-zero exit
+ * only when it exposes a numeric `exitCode`; a plain `Error` instead falls
+ * through to the "unhandled" path, which re-invokes the handler (doubling side
+ * effects such as a second GitHub fetch) and exits with a generic code. Throwing
+ * this routes a failure to a clean, single exit at the chosen code.
+ */
 export class CommandError extends Error {
+    /** Numeric exit code the runtime propagates to the shell (one of {@link EXIT_CODE}). */
     exitCode;
     constructor(message, exitCode = EXIT_CODE.GENERIC_FAILURE) {
         super(message);
@@ -460,24 +491,46 @@ export class CommandError extends Error {
 // ---------------------------------------------------------------------------
 // Provenance — link a pm item back to a specific GitHub issue
 // ---------------------------------------------------------------------------
-// Provenance lives in a machine-parseable tag (`gh:owner/repo#123`) AND in the
-// declared schema fields/description. The tag is the idempotency key: it
-// round-trips losslessly through `pm create --tags` / `pm list --json`, so a
-// re-import can find the existing item and UPDATE it instead of duplicating.
+/**
+ * Build the `gh:owner/repo#N` provenance tag linking a pm item to a GitHub issue.
+ *
+ * The tag is the idempotency key: it round-trips losslessly through
+ * `pm create --tags` / `pm list --json`, so a re-import can find the existing
+ * item and UPDATE it instead of duplicating. Provenance also rides on declared
+ * schema fields and the description, but the tag is what matching keys on.
+ *
+ * @param repo - `owner/repo`, lowercased into the tag.
+ * @param issueNumber - The issue/PR number.
+ * @returns The provenance tag string.
+ */
 export function provenanceTag(repo, issueNumber) {
     return `gh:${repo.toLowerCase()}#${issueNumber}`;
 }
-// Parse a `gh:owner/repo#number` provenance tag into its repo + issue number;
-// returns undefined for non-provenance tags.
+/**
+ * Parse a `gh:owner/repo#N` provenance tag back into its repo and issue number.
+ *
+ * Returns `undefined` for anything that is not a provenance tag, so a caller
+ * scanning a tag list can skip foreign tags without a try/catch.
+ *
+ * @param tag - The candidate tag string.
+ * @returns The parsed repo (lowercased) and number, or `undefined`.
+ */
 export function parseProvenanceTag(tag) {
     const m = /^gh:([^#\s]+)#(\d+)$/.exec(tag.trim());
     if (!m)
         return undefined;
     return { repo: m[1].toLowerCase(), number: Number(m[2]) };
 }
-// Surface the GitHub issue author as a machine-readable tag (`github_author:login`)
-// — consistent with how provenance rides on tags. Returns undefined when the
-// API did not include a usable login (so we never emit an empty tag).
+/**
+ * Build the `github_author:login` tag recording who opened a GitHub issue.
+ *
+ * Mirrors how provenance rides on tags so the author survives a round-trip.
+ * Returns `undefined` when the API supplied no usable login, so an empty tag is
+ * never emitted.
+ *
+ * @param issue - The issue whose author to tag.
+ * @returns The author tag, or `undefined`.
+ */
 export function authorTag(issue) {
     const login = issue.user?.login?.trim();
     if (!login)
@@ -937,11 +990,19 @@ export function composeBody(issue, comments) {
 //     reports "degraded" and proceeds unlocked with a warning, matching the
 //     pre-lock best-effort behavior.
 export const IMPORT_LOCK_TTL_MS_DEFAULT = 5 * 60_000;
+/** Default total budget a caller waits to acquire a contended comment-sync lock before giving up and skipping that item's sync. */
 export const IMPORT_LOCK_WAIT_MS_DEFAULT = 30_000;
-// Resolve the pm data dir (the dir holding settings.json and locks/) from the
-// pmRoot the extension host hands the command, which may be either the
-// workspace root (the dir containing .agents/pm) or the data dir itself — the
-// pm CLI accepts both for --path, and tests pass the workspace root.
+/**
+ * Resolve the pm data dir from the `pmRoot` a command handler receives.
+ *
+ * The host may hand either the workspace root (the dir containing `.agents/pm`)
+ * or the data dir itself — the pm CLI accepts both for `--path`. This returns
+ * the dir that actually holds `settings.json` and `locks/`, defaulting to
+ * `pmRoot` unchanged when no nested `.agents/pm` exists.
+ *
+ * @param pmRoot - The path supplied by the extension host.
+ * @returns The resolved pm data directory.
+ */
 export function resolvePmDataDir(pmRoot) {
     const nested = path.join(pmRoot, ".agents", "pm");
     try {
@@ -953,13 +1014,31 @@ export function resolvePmDataDir(pmRoot) {
     }
     return pmRoot;
 }
-// Absolute lock file path for one item's comment-sync critical section. The
-// item id is sanitized defensively (pm ids are already filename-safe, but the
-// lock path must never become a traversal vector if that ever changes).
+/**
+ * Absolute lock file path for one item's comment-sync critical section.
+ *
+ * The item id is sanitized defensively: pm ids are already filename-safe, but
+ * the lock path must never become a directory-traversal vector if that ever
+ * changes.
+ *
+ * @param pmRoot - Workspace root or pm data dir.
+ * @param itemId - The pm item id to serialize.
+ * @returns Absolute path under the data dir's `locks/` directory.
+ */
 export function importCommentSyncLockPath(pmRoot, itemId) {
     const safe = itemId.replace(/[^A-Za-z0-9._-]/g, "_");
     return path.join(resolvePmDataDir(pmRoot), "locks", `pm-github.comment-sync.${safe}.lock`);
 }
+/**
+ * Read and parse a lock file's payload.
+ *
+ * Returns `undefined` when the file is absent or holds non-JSON / non-object
+ * content (e.g. caught mid-write then abandoned), so the caller treats an
+ * unreadable lock as owner-less rather than crashing.
+ *
+ * @param lockPath - Absolute lock file path.
+ * @returns The parsed payload, or `undefined`.
+ */
 function readImportLockPayload(lockPath) {
     let raw;
     try {
@@ -978,6 +1057,16 @@ function readImportLockPayload(lockPath) {
         return undefined;
     }
 }
+/**
+ * Whether the process holding a lock is still running.
+ *
+ * Signals the PID with signal 0 (no effect); `EPERM` means the process exists
+ * but belongs to another user (still alive), while `ESRCH` means it is gone.
+ * Non-numeric or non-positive PIDs are treated as not-alive.
+ *
+ * @param pid - The recorded owner PID (untyped at the call site).
+ * @returns True when the PID names a live process.
+ */
 function isLockOwnerAlive(pid) {
     if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
         return false;
@@ -1005,6 +1094,22 @@ function isLockOwnerAlive(pid) {
 // same-pid payload that is legitimately ours (in-process contention → wait)
 // from a leftover written by a dead process whose PID we inherited (→ break).
 const heldImportLocks = new Set();
+/**
+ * Decide whether a held lock is stale and why.
+ *
+ * Returns a human-readable reason when the lock should be broken, or
+ * `undefined` when it is still legitimately held. A lock is stale only when its
+ * owner is provably gone: the recorded PID is dead, or it equals our own PID on
+ * a path this process does not hold (a recycled PID). A LIVE owner is never
+ * age-broken; only a missing/unparseable payload falls back to the TTL, aged
+ * from `created_at` or the file mtime.
+ *
+ * @param lockPath - Absolute lock file path (also tracked in {@link heldImportLocks}).
+ * @param payload - Parsed lock payload, or `undefined` when unreadable.
+ * @param mtimeMs - File mtime, the age fallback base.
+ * @param ttlMs - Maximum age before an owner-less lock is considered stale.
+ * @returns The staleness reason, or `undefined` when the lock is live.
+ */
 function importLockStaleReason(lockPath, payload, mtimeMs, ttlMs) {
     const pid = payload?.pid;
     if (typeof pid === "number" && Number.isInteger(pid) && pid > 0) {
@@ -1028,20 +1133,29 @@ function importLockStaleReason(lockPath, payload, mtimeMs, ttlMs) {
 const IMPORT_LOCK_INITIAL_BACKOFF_MS = 25;
 const IMPORT_LOCK_MAX_BACKOFF_MS = 200;
 const IMPORT_LOCK_MAX_STALE_BREAKS = 3;
-// A breaker's critical section is a handful of syscalls (re-stat, re-read,
-// unlink) — a crashed breaker's sidecar goes stale in seconds, not minutes.
+/**
+ * Staleness TTL for a breaker election sidecar, in ms.
+ *
+ * A breaker's critical section is a handful of syscalls (re-stat, re-read,
+ * unlink), so a crashed breaker's sidecar goes stale in seconds, not minutes;
+ * this short window lets a contender clear and re-run a dead election.
+ */
 export const IMPORT_LOCK_BREAKER_TTL_MS = 10_000;
-// Break a stale lock under a breaker election so the unlink can never race
-// another breaker: two contenders may both judge the same file stale, but
-// without mutual exclusion the slower one would execute its unlink AFTER the
-// winner already re-created a fresh, live lock — silently unlinking that
-// replacement and letting both proceed (the exact double-acquire this module
-// exists to prevent). The election is an O_EXCL sidecar (`<lock>.break`):
-// only its single winner may unlink, and it re-verifies staleness under the
-// mutex first, so a lock that became live since the caller's check survives.
-// Returns true when the stale lock was removed (caller should retry acquire
-// immediately), false when the election was lost or the lock is live again
-// (caller should fall through to the normal wait/backoff).
+/**
+ * Break a stale lock under a breaker election.
+ *
+ * Two contenders may both judge the same file stale; without mutual exclusion
+ * the slower unlink would remove a fresh, live lock the winner had just
+ * re-created — the exact double-acquire this module exists to prevent. The
+ * election is an O_EXCL sidecar (`<lock>.break`): only its single winner may
+ * unlink, and it re-verifies staleness under that mutex first, so a lock that
+ * became live since the caller's check survives.
+ *
+ * @param lockPath - Absolute path of the lock judged stale.
+ * @param ttlMs - Staleness TTL handed to {@link importLockStaleReason} on re-check.
+ * @param reason - Human-readable staleness reason, surfaced in the break warning.
+ * @returns True when the stale lock was removed (retry acquire now); false when the election was lost or the lock is live again.
+ */
 function breakStaleImportLock(lockPath, ttlMs, reason) {
     const breakerPath = `${lockPath}.break`;
     let bfd;
@@ -1096,9 +1210,19 @@ function breakStaleImportLock(lockPath, ttlMs, reason) {
         }
     }
 }
-// Acquire the cross-process comment-sync lock for one item. Never throws:
-// every failure mode maps to one of the three acquisition statuses so the
-// caller can decide how to degrade. `ttlMs`/`waitMs` are injectable for tests.
+/**
+ * Acquire the cross-process comment-sync lock for one item.
+ *
+ * Never throws: every failure mode maps to one of the three acquisition
+ * statuses (`acquired`, `contended`, `degraded`) so the caller decides how to
+ * degrade. `ttlMs`/`waitMs` are injectable so the wait and staleness windows
+ * can be exercised without real timing in tests.
+ *
+ * @param pmRoot - Workspace root or pm data dir passed to {@link resolvePmDataDir}.
+ * @param itemId - The pm item whose comment critical section is serialized.
+ * @param opts - Optional overrides for the staleness TTL and wait budget.
+ * @returns The acquisition outcome.
+ */
 export async function acquireImportLock(pmRoot, itemId, opts = {}) {
     const ttlMs = opts.ttlMs ?? IMPORT_LOCK_TTL_MS_DEFAULT;
     const waitMs = opts.waitMs ?? IMPORT_LOCK_WAIT_MS_DEFAULT;
@@ -1221,18 +1345,35 @@ export async function acquireImportLock(pmRoot, itemId, opts = {}) {
 // the GitHub comment id (`<!-- pm-github:comment:N -->`). On re-import the
 // already-synced ids are read back and skipped, so re-running import never
 // duplicates a comment.
-// Hidden HTML comment marker carrying the GitHub comment id. HTML comments are
-// invisible in rendered markdown but survive `pm comments` storage verbatim.
+/**
+ * Matches the hidden HTML-comment marker carrying a synced GitHub comment id.
+ *
+ * HTML comments are invisible in rendered markdown but survive `pm comments`
+ * storage verbatim, so the id embedded in the marker is the stable dedupe key.
+ */
 export const COMMENT_MARKER_REGEX = /<!--\s*pm-github:comment:(\d+)\s*-->/;
-// Build the text for a single native pm comment from a GitHub comment. The
-// marker is appended so re-sync can de-duplicate on the GitHub comment id.
+/**
+ * Build the text for one native pm comment from a GitHub comment.
+ *
+ * Appends the marker so a later re-sync can de-duplicate on the GitHub comment
+ * id (see {@link COMMENT_MARKER_REGEX}).
+ *
+ * @param comment - The GitHub comment to render.
+ * @returns The comment text with the trailing id marker.
+ */
 export function buildCommentText(comment) {
     const body = (comment.body || "").trim() || "(empty comment)";
     return `${body}\n\n<!-- pm-github:comment:${comment.id} -->`;
 }
-// Read the GitHub comment ids already synced into an item's native comments,
-// by scanning each stored comment's text for the stable marker. Returns the set
-// of synced ids (empty when none match, e.g. for hand-written pm comments).
+/**
+ * Collect the GitHub comment ids already synced into an item's native comments.
+ *
+ * Scans each stored comment's text for the stable marker. Returns the set of
+ * synced ids (empty when none match, e.g. for hand-written pm comments).
+ *
+ * @param stored - The item's existing native comments (each may carry marker text).
+ * @returns The set of already-synced GitHub comment ids.
+ */
 export function extractSyncedCommentIds(stored) {
     const ids = new Set();
     for (const entry of stored) {
@@ -1263,6 +1404,17 @@ export function extractSyncedCommentIds(stored) {
 //
 // Returns undefined when the output genuinely cannot be parsed, so callers fall
 // back to a safe skip-with-warning instead of crashing the whole import.
+/**
+ * Extract the newly-created item id from `pm create --json` stdout.
+ *
+ * The CLI emits a FLAT envelope (`{ "id": "pm-xxxx", … }`) with no `item`
+ * wrapper, so this reads `parsed.id` directly. Returns `undefined` when the
+ * output genuinely cannot be parsed, so callers skip-with-warning instead of
+ * crashing the whole import.
+ *
+ * @param stdout - Raw `pm create --json` output.
+ * @returns The created item id, or `undefined`.
+ */
 export function parseCreatedItemId(stdout) {
     try {
         const parsed = JSON.parse(stdout);
@@ -1292,6 +1444,21 @@ export function parseCreatedItemId(stdout) {
 // (never run unlocked, so a wedged peer can cost a sync — recoverable on the
 // next import — but never cause a duplicate); if the lock mechanism itself is
 // unavailable the sync proceeds unlocked as before, also with a warning.
+/**
+ * Sync GitHub issue comments into a pm item's native comments collection.
+ *
+ * Idempotent: comments already present (matched by their marker id) are skipped,
+ * so re-running import never duplicates. Each GitHub comment becomes one pm
+ * comment authored by the GitHub login. Failures are logged and never abort the
+ * import; a contended or unavailable lock degrades gracefully (see
+ * {@link acquireImportLock}).
+ *
+ * @param itemId - The pm item to append comments to.
+ * @param comments - The GitHub comments to sync.
+ * @param pmRoot - Workspace root or pm data dir.
+ * @param issueNumber - The source issue number (for log prefixes).
+ * @returns How many comments were added and how many skipped as duplicates.
+ */
 export async function syncGithubCommentsToAnnotations(itemId, comments, pmRoot, issueNumber) {
     if (comments.length === 0)
         return { added: 0, skipped: 0 };
@@ -1337,12 +1504,29 @@ export async function syncGithubCommentsToAnnotations(itemId, comments, pmRoot,
         release();
     }
 }
-// A draft PR is an issue that is both a pull request and flagged `draft: true`.
-// (Plain issues are never drafts.)
+/**
+ * Whether a GitHub issue node is a draft pull request.
+ *
+ * A draft PR is an issue that is BOTH a pull request and flagged `draft: true`;
+ * plain issues are never drafts.
+ *
+ * @param issue - The issue node to test.
+ * @returns True only for draft pull requests.
+ */
 export function isDraftPr(issue) {
     return Boolean(issue.pull_request) && issue.draft === true;
 }
-// Apply the client-side filters (PRs, drafts, milestone-by-title).
+/**
+ * Apply the client-side import filters the REST API cannot express.
+ *
+ * Drops pull requests (unless `includePrs`), draft PRs (when `skipDrafts`), and
+ * items whose milestone title does not match (the API keys milestones by number,
+ * not title). Returns the surviving issues in input order.
+ *
+ * @param issues - Fetched issues to narrow.
+ * @param opts - Import options carrying the filter flags.
+ * @returns The filtered issue list.
+ */
 export function applyClientFilters(issues, opts) {
     let result = issues;
     if (!opts.includePrs)
@@ -1356,8 +1540,17 @@ export function applyClientFilters(issues, opts) {
     }
     return result;
 }
-// Normalize CLI options into ImportOptions (state filter, labels, assignee,
-// milestone, since-window, PR inclusion, draft skipping, comment fetching).
+/**
+ * Normalize the raw CLI flag bag into a typed {@link ImportOptions}.
+ *
+ * Resolves the state filter, labels, assignee, milestone, the `--since` window,
+ * PR inclusion, draft skipping, and the comment-fetching mode, throwing a
+ * {@link CommandError} with a usage code on a malformed `--since` or
+ * `--comments-mode`.
+ *
+ * @param options - The raw option object from the command handler.
+ * @returns The normalized import options.
+ */
 export function parseImportOptions(options) {
     // --state takes precedence; --all is the legacy shorthand for "all".
     const stateOpt = optionString(options, "state");
@@ -1430,6 +1623,16 @@ const DEP_REF_STICKY = /(?:([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+))?#(\d+)/y;
 // ("#1, #2 and #3"). Sticky and can match empty, so the ref loop always
 // terminates: the next sticky ref match is what decides whether to continue.
 const DEP_GLUE_STICKY = /[\s,]*(?:and\b[\s,]*)?/y;
+/**
+ * Map a dependency phrase captured from an issue body to its pm edge kind.
+ *
+ * Collapses spacing/hyphen variants and returns both the canonical
+ * {@link DepRefKind} and a normalized human phrase ("blocks", "depends on", or
+ * "blocked by") for audit messages.
+ *
+ * @param raw - The raw phrase matched by the dependency-phrase regex.
+ * @returns The resolved kind and normalized phrase.
+ */
 function phraseToKind(raw) {
     const compact = raw.toLowerCase().replace(/[\s-]/g, "");
     if (compact === "blocks")
@@ -1548,12 +1751,17 @@ export function countDependencyRefCandidates(repo, issues) {
         n += parseDependencyReferences(issue.body ?? "", repoLc).length;
     return n;
 }
-// Build the default `DepLinkSdk` from the top-level SDK imports so the
-// --link-deps second pass never needs a dynamic import. `listAllItemMetadata`
-// returns full `ItemMetadata` objects; we project to the `DepLinkSnapshotItem`
-// structural subset the link pass actually reads. The SDK's cycle detector
-// reads only id/tags/dependencies off each item; `DepLinkSnapshotItem` is that
-// structural subset, so the cast on `collectNewOrderingCycleWarnings` is sound.
+/**
+ * Build the default SDK-backed dependency-link collaborators.
+ *
+ * Wires the `--link-deps` second pass to the top-level SDK imports so it never
+ * needs a dynamic import. `listAllItemMetadata` returns full `ItemMetadata`
+ * objects, projected here to the {@link DepLinkSnapshotItem} structural subset
+ * the link pass reads; the SDK cycle detector reads only id/tags/dependencies,
+ * so the cast on `collectNewOrderingCycleWarnings` is sound.
+ *
+ * @returns The default SDK collaborators.
+ */
 function defaultDepLinkSdk() {
     return {
         listAllItemMetadata: async (pmRoot) => {
@@ -1567,6 +1775,17 @@ function defaultDepLinkSdk() {
         collectNewOrderingCycleWarnings: sdkCollectNewOrderingCycleWarnings,
     };
 }
+/**
+ * Default edge applier: spawn `pm update --dep` for one resolved edge.
+ *
+ * Records the source issue and the matching phrase in the mutation message so
+ * the resulting dependency is auditable. Returns the ok/stderr shape every edge
+ * applier shares, never throwing.
+ *
+ * @param edge - The resolved workspace edge to write.
+ * @param pmRoot - Workspace root for the `pm` invocation.
+ * @returns Whether the write succeeded and any stderr.
+ */
 function defaultApplyDependencyLink(edge, pmRoot) {
     const res = pmRun([
         "--path", pmRoot, "update", edge.sourceId,
@@ -1644,6 +1863,21 @@ export async function linkImportedDependencies(repo, issues, pmRoot, deps = {})
     }
     return { linked, unresolved, orderingCycleWarnings: [...warnings], failures };
 }
+/**
+ * Render one GitHub issue into the import-ready desired state.
+ *
+ * Computes the title, status, provenance/author tags, description, body (with
+ * optional embedded comments), and the comment list for native sync. Returns
+ * `undefined` for an issue with no usable title so the caller counts it skipped.
+ *
+ * @param issue - The fetched issue to render.
+ * @param repo - `owner/repo`, baked into the provenance tag.
+ * @param opts - Import options governing body/comments.
+ * @param token - GitHub token for the comment fetch.
+ * @param match - The existing pm item linked to this issue, if any (drives update vs create).
+ * @param fetchIssueComments - Injectable comment fetcher (defaults to {@link fetchComments}).
+ * @returns The prepared import entry, or `undefined` when the issue has no title.
+ */
 async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueComments = fetchComments) {
     const title = issue.title.trim();
     if (!title)
@@ -1686,9 +1920,20 @@ async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueCo
         match,
     };
 }
-// Run the full import flow. Idempotent: items already linked (provenance tag)
-// to a fetched issue are UPDATEd; new issues are created. Returns a structured
-// result; throws CommandError (with a semantic exitCode) on failure.
+/**
+ * Run the full GitHub issue import flow.
+ *
+ * Idempotent: items already linked (by provenance tag) to a fetched issue are
+ * UPDATEd; new issues are created. Honors `--atomic` (one crash-resumable
+ * transaction) versus the per-item `pm` mutation path, optional `--link-deps`,
+ * and `--dry-run`. Returns a structured result and throws {@link CommandError}
+ * (with a semantic exit code) on failure.
+ *
+ * @param repoArg - The `owner/repo` to import from.
+ * @param pmRoot - Workspace root or pm data dir.
+ * @param opts - Normalized import options.
+ * @param deps - Injectable collaborators (token resolver, fetchers, etc.) for tests.
+ */
 export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
     if (!repoArg || !repoArg.includes("/")) {
         throw new CommandError("Usage: pm github import <owner/repo> [--all|--state open|closed|all] " +
@@ -1976,8 +2221,13 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
     reportDepLink(depLink);
     return { imported, updated, skipped, ...depLinkResultFields(depLink) };
 }
-// Emit the human-readable --link-deps summary to stderr (import writes its
-// progress there; stdout is reserved for the structured result).
+/**
+ * Emit the human-readable `--link-deps` summary to stderr.
+ *
+ * Import progress is written to stderr so stdout stays reserved for the
+ * structured result; this prints the linked-edge count, unresolved refs, and
+ * any ordering-cycle warnings or per-edge failures.
+ */
 function reportDepLink(result) {
     if (!result)
         return;
@@ -1990,8 +2240,12 @@ function reportDepLink(result) {
     for (const failure of result.failures)
         console.error(`  ✗ link failed: ${failure}`);
 }
-// The public, JSON-serializable slice of a --link-deps result. Kept flat and
-// omitted entirely when the pass did not run so the default result is unchanged.
+/**
+ * The public, JSON-serializable slice of a `--link-deps` result.
+ *
+ * Kept flat and omitted entirely when the pass did not run, so the default
+ * import result is unchanged.
+ */
 function depLinkResultFields(result) {
     if (!result)
         return {};
@@ -2174,13 +2428,15 @@ export function exportWillApply(options) {
         return true;
     return optionEnabled(options, "apply", "push");
 }
-// Apply a (already-built) export plan to GitHub, one issue at a time.
-//
-// CRITICAL: each create/update is isolated. A single failed write (e.g. a 422
-// for a label that does not exist on the repo) is recorded and the loop
-// CONTINUES with the remaining items — it never abandons the rest of the batch.
-// This mirrors the per-item isolation already used by the import/sync paths.
-// Pure aside from the injected `requestFn`, so it is directly unit-testable.
+/**
+ * Apply an already-built export plan to GitHub, one issue at a time.
+ *
+ * Each create/update is isolated: a single failed write (e.g. a 422 for a label
+ * that does not exist on the repo) is recorded and the loop CONTINUES with the
+ * remaining items — it never abandons the rest of the batch. Pure aside from the
+ * injected `requestFn`, so the per-item isolation is directly unit-testable
+ * without real network I/O.
+ */
 export async function applyExportPlan(plan, repo, token, requestFn) {
     let created = 0;
     let updated = 0;
@@ -2235,6 +2491,19 @@ export async function applyExportPlan(plan, repo, token, requestFn) {
 //   - any creates/updates landed (partial or full)     → success (per-item
 //     failures are already reported; the batch still wrote real changes)
 //   - non-empty plan, nothing written, >=1 failure     → GENERIC_FAILURE
+/**
+ * Decide the exit status of a completed `export --apply` batch.
+ *
+ * Per-item continuation is intentional (one bad item never aborts the batch),
+ * but the batch as a whole must still report honestly: a non-empty plan that
+ * wrote NOTHING while recording at least one failure is a total failure, so it
+ * returns a {@link CommandError} to throw; otherwise `undefined` (exit 0).
+ *
+ * @param plan - The plan that was applied.
+ * @param result - What the apply loop actually wrote.
+ * @param repo - Target repo, included in the failure message.
+ * @returns A `CommandError` to throw on total failure, else `undefined`.
+ */
 export function applyOutcomeError(plan, result, repo) {
     if (plan.length > 0 && result.created === 0 && result.updated === 0 && result.failed > 0) {
         return new CommandError(`All ${result.failed} item(s) failed to apply to ${repo}; ` +
@@ -2255,6 +2524,14 @@ export function applyOutcomeError(plan, result, repo) {
 // stdout in JSON mode (pm renders the return value). Used by both the
 // `registerExporter("github", ...)` entry point and the `pm github export`
 // command so the surface stays consistent.
+/**
+ * Shared handler for the `pm github export` exporter and command.
+ *
+ * Export is SAFE BY DEFAULT: it previews the create/update plan and writes
+ * nothing unless the user opts in with `--apply` (plus a token and `--repo`).
+ * Items already linked to an issue in `--repo` are upserted rather than
+ * duplicated; `--label-map` translates pm tags to GitHub labels.
+ */
 async function runExport(ctx) {
     const options = ctx.options || {};
     const jsonMode = ctx.global?.json === true;
@@ -2366,16 +2643,32 @@ async function runExport(ctx) {
 // repo match the query, then returns hits for the pm items that are already
 // imported from those issues (matched by the `gh:repo#N` provenance tag).
 // Semantics: "find my imported pm items whose upstream GitHub issue matches Q".
-// Build the GitHub Search-API URL for issues in a repo matching the free-text
-// query. Restricted to `type:issue repo:<repo>` so it never leaks across repos.
+/**
+ * Build the GitHub Search-API URL for issues in one repo matching a free-text query.
+ *
+ * Restricted to `type:issue repo:<repo>` so a search never leaks across repos.
+ *
+ * @param repo - The `owner/repo` to search within.
+ * @param query - Free-text query string.
+ * @returns The encoded search URL.
+ */
 export function buildSearchUrl(repo, query) {
     const q = `${query} repo:${repo} type:issue`;
     return `${githubApiBase()}/search/issues?q=${encodeURIComponent(q)}&per_page=100`;
 }
-// Map GitHub search results to local pm-item hits. For every returned issue
-// number we look up the pm item carrying the matching `gh:repo#N` provenance
-// tag; only locally-present items become hits (the runtime would drop the rest
-// anyway). Score is GitHub's relevance score, normalized into a sane range.
+/**
+ * Map GitHub search result numbers to local pm-item hits.
+ *
+ * For every returned issue number, looks up the pm item carrying the matching
+ * `gh:repo#N` provenance tag; only locally-present items become hits (the
+ * runtime would drop the rest anyway). Score preserves GitHub's ranking,
+ * normalized into `(0, 1]` so hits clear pm's default threshold.
+ *
+ * @param matchedNumbers - Issue numbers GitHub returned, best-first.
+ * @param repo - The repo the search ran against.
+ * @param itemsByProvenance - Local items keyed `owner/repo#N`.
+ * @returns One hit per locally-present matching item.
+ */
 export function mapSearchHits(matchedNumbers, repo, itemsByProvenance) {
     const repoLc = repo.toLowerCase();
     const hits = [];
@@ -2399,8 +2692,15 @@ export function mapSearchHits(matchedNumbers, repo, itemsByProvenance) {
     }
     return hits;
 }
-// Resolve the search target repo: an explicit option wins, then the
-// PM_GITHUB_REPO env var (so a workspace can pin its upstream).
+/**
+ * Resolve the search target repo for the GitHub search provider.
+ *
+ * An explicit option wins, then the `PM_GITHUB_REPO` env var so a workspace can
+ * pin its upstream. Returns `undefined` when neither yields an `owner/repo`.
+ *
+ * @param options - The raw option object from the search context.
+ * @returns The resolved `owner/repo`, or `undefined`.
+ */
 export function resolveSearchRepo(options) {
     const opt = optionString(options, "repo", "github-repo", "githubRepo");
     if (opt && opt.includes("/"))
@@ -2543,9 +2843,18 @@ const STATUS_FIELD_GQL = `
   statusField: field(name: "Status") {
     ... on ProjectV2SingleSelectField { id name options { id name } }
   }`;
-// Resolve owner/number → project id + Status field. The owner may be a user or
-// an org and GraphQL requires us to pick, so we ask both in one request and use
-// whichever resolves.
+/**
+ * Resolve a project reference into its GraphQL id and Status field.
+ *
+ * The owner may be a user or an org, and GraphQL requires us to pick which
+ * owner-type field to query, so this asks both in one request and keeps
+ * whichever connection resolves. Throws {@link CommandError} (NOT_FOUND) when
+ * neither resolves (wrong owner, wrong number, or missing project scope).
+ *
+ * @param ref - The `owner/number` board reference.
+ * @param token - GitHub token (the GraphQL call requires one).
+ * @returns The board metadata including its Status field, if any.
+ */
 async function resolveProject(ref, token) {
     const query = `
     query($owner:String!,$number:Int!){
@@ -2565,9 +2874,16 @@ async function resolveProject(ref, token) {
     const statusField = sf && sf.id ? { id: sf.id, name: sf.name, options: sf.options ?? [] } : undefined;
     return { id: node.id, title: node.title ?? "", url: node.url ?? "", ownerType, statusField };
 }
-// Normalize a raw GraphQL project-item node into the ProjectItem model,
-// tolerating null/undefined nodes and missing content (defensive against
-// partial GraphQL errors / inaccessible items).
+/**
+ * Normalize a raw GraphQL project-item node into the {@link ProjectItem} model.
+ *
+ * Tolerates null/undefined nodes and missing content, returning a placeholder
+ * `Unknown` content for redacted or unmodeled item types so they are counted but
+ * never mutated.
+ *
+ * @param n - The raw GraphQL node (may be null).
+ * @returns The normalized project item.
+ */
 function normalizeProjectItemNode(n) {
     const c = n?.content ?? { __typename: "Unknown" };
     const tn = c.__typename;
@@ -2609,7 +2925,17 @@ function normalizeProjectItemNode(n) {
         content,
     };
 }
-// Fetch every item on the board (paginated, 100/page).
+/**
+ * Fetch every item on a board, paging through the connection at 100/page.
+ *
+ * Walks the GraphQL cursor until `hasNextPage` is false, normalizing each node
+ * via {@link normalizeProjectItemNode}. Stops cleanly when a page reports no
+ * connection so the loop never truncates silently nor spins on a missing cursor.
+ *
+ * @param projectId - GraphQL node id of the board.
+ * @param token - GitHub token.
+ * @returns Every item on the board, in page order.
+ */
 async function fetchProjectItems(projectId, token) {
     const query = `
     query($id:ID!,$cursor:String){
@@ -2649,7 +2975,15 @@ async function fetchProjectItems(projectId, token) {
     }
     return items;
 }
-// Add a DraftIssue to a Projects v2 board and return the new project item id.
+/**
+ * Add a draft issue to a Projects v2 board and return the new project-item id.
+ *
+ * @param projectId - GraphQL node id of the board.
+ * @param title - Draft issue title.
+ * @param body - Draft issue body (empty string when absent).
+ * @param token - GitHub token.
+ * @returns The newly created project-item id.
+ */
 async function gqlAddDraft(projectId, title, body, token) {
     const q = `mutation($p:ID!,$t:String!,$b:String){ addProjectV2DraftIssue(input:{projectId:$p,title:$t,body:$b}){ projectItem{ id } } }`;
     const d = await githubGraphQL(token, q, { p: projectId, t: title, b: body ?? "" });
@@ -2658,8 +2992,14 @@ async function gqlAddDraft(projectId, title, body, token) {
         throw new CommandError("addProjectV2DraftIssue returned no item id.");
     return id;
 }
-// Link an existing repository issue/PR to a Projects v2 board and return the
-// new project item id.
+/**
+ * Link an existing repo issue/PR to a board and return the new project-item id.
+ *
+ * @param projectId - GraphQL node id of the board.
+ * @param contentId - GraphQL node id of the issue/PR to attach.
+ * @param token - GitHub token.
+ * @returns The newly created project-item id.
+ */
 async function gqlAddIssue(projectId, contentId, token) {
     const q = `mutation($p:ID!,$c:ID!){ addProjectV2ItemById(input:{projectId:$p,contentId:$c}){ item{ id } } }`;
     const d = await githubGraphQL(token, q, { p: projectId, c: contentId });
@@ -2673,8 +3013,14 @@ async function gqlSetStatus(projectId, itemId, fieldId, optionId, token) {
     const q = `mutation($p:ID!,$i:ID!,$f:ID!,$o:String!){ updateProjectV2ItemFieldValue(input:{projectId:$p,itemId:$i,fieldId:$f,value:{singleSelectOptionId:$o}}){ projectV2Item{ id } } }`;
     await githubGraphQL(token, q, { p: projectId, i: itemId, f: fieldId, o: optionId });
 }
-// Resolve the GraphQL node id of a repo's issue or PR by number, returning
-// undefined when the item is not found or the repo ref is malformed.
+/**
+ * Resolve the GraphQL node id of a repo's issue or PR by number.
+ *
+ * @param repo - `owner/repo` to look up in.
+ * @param number - The issue/PR number.
+ * @param token - GitHub token.
+ * @returns The node id, or `undefined` when not found or the repo ref is malformed.
+ */
 async function gqlResolveIssueNodeId(repo, number, token) {
     const [owner, name] = repo.split("/");
     if (!owner || !name)
@@ -2683,8 +3029,6 @@ async function gqlResolveIssueNodeId(repo, number, token) {
     const d = await githubGraphQL(token, q, { o: owner, n: name, num: number });
     return d.repository?.issueOrPullRequest?.id ?? undefined;
 }
-// Compose a human-readable + provenance-bearing description for an imported
-// project item (parallels the issue-import description).
 /** Build a factual close reason for a project-import item entering `closed`. */
 function projectImportCloseReason(ref, c) {
     if (c.repo && typeof c.number === "number") {
@@ -2692,6 +3036,17 @@ function projectImportCloseReason(ref, c) {
     }
     return `GitHub project ${ref.owner}/${ref.number} item closed`;
 }
+/**
+ * Compose a human-readable, provenance-bearing description for an imported
+ * project item.
+ *
+ * Parallels the issue-import description: joins the board ref, item kind, issue
+ * link, URL, and state into one summary string written to the pm item.
+ *
+ * @param ref - The board the item came from.
+ * @param c - The item's resolved content.
+ * @returns The composed description line.
+ */
 function projectItemDescription(ref, c) {
     const parts = [`GH project item ${ref.owner}/${ref.number}`];
     if (c.typename === "DraftIssue")
@@ -2731,12 +3086,18 @@ export async function collectProjectsV2Pages(fetchPage) {
     }
     return out;
 }
-// Resolve + paginate the projectsV2 connection for a user-or-org owner using an
-// injected GraphQL transport. A login is either a user or an organization,
-// never both; querying both in one request lets us resolve the owner type
-// without a round-trip, then we keep paginating the connection that actually
-// exists so owners with more than 50/100 projects are fully listed instead of
-// silently truncated (Greptile 2006f478). Returns raw connection nodes.
+/**
+ * Resolve and paginate the `projectsV2` connection for a user-or-org owner.
+ *
+ * A login is either a user or an organization, never both; querying both in one
+ * request resolves the owner type without an extra round-trip, then this keeps
+ * paginating the connection that actually exists so owners with more than 100
+ * projects are fully listed instead of silently truncated.
+ *
+ * @param owner - The user or org login.
+ * @param graphQL - Injectable transport (query + variables → data), for tests.
+ * @returns Every project-summary node for the owner.
+ */
 export async function listOwnerProjectsV2Nodes(owner, graphQL) {
     let ownerType = null;
     return collectProjectsV2Pages(async (cursor) => {
@@ -2755,6 +3116,11 @@ export async function listOwnerProjectsV2Nodes(owner, graphQL) {
         return ownerType === "organization" ? d.organization?.projectsV2 : d.user?.projectsV2;
     });
 }
+/**
+ * Command handler for `pm github project list`: list a user/org's Projects v2.
+ *
+ * @param ctx - The command-handler context.
+ */
 async function runProjectList(ctx) {
     const options = ctx.options || {};
     const owner = optionString(options, "owner") || ctx.args?.[0];
@@ -2784,6 +3150,14 @@ async function runProjectList(ctx) {
     return { owner, projects };
 }
 // --- project fields --------------------------------------------------------
+/**
+ * Command handler for `pm github project fields`: show a board's fields.
+ *
+ * Resolves the board, then lists its fields and (for the Status single-select)
+ * its option names so the caller can build a `--status-map`.
+ *
+ * @param ctx - The command-handler context.
+ */
 async function runProjectFields(ctx) {
     const options = ctx.options || {};
     const ref = parseProjectRef(optionString(options, "project") || ctx.args?.[0]);
@@ -2818,6 +3192,15 @@ async function runProjectFields(ctx) {
     return { project: meta, fields };
 }
 // --- project import --------------------------------------------------------
+/**
+ * Command handler for `pm github project import`: import board items as pm items.
+ *
+ * Idempotent: items already linked (by project tag or wrapped issue) are updated,
+ * the rest are created. Status is refreshed only from an explicit, resolvable
+ * board mapping (never a guess), honoring the no-data-loss invariant.
+ *
+ * @param ctx - The command-handler context.
+ */
 async function runProjectImport(ctx) {
     const options = ctx.options || {};
     const ref = parseProjectRef(optionString(options, "project") || ctx.args?.[0]);
@@ -2938,8 +3321,21 @@ async function runProjectImport(ctx) {
     return { imported, updated, skipped, project: `${ref.owner}/${ref.number}`, planned: plan.length };
 }
 // --- project sync (bidirectional) ------------------------------------------
-// Push a pm item's status onto its (existing) board item, tolerating a missing
-// target option. Returns true on a real change.
+/**
+ * Push one pm item's status onto its board item.
+ *
+ * Tolerates a missing target option (writes the item but skips the Status set).
+ * Returns whether a real change was made and an optional error string so the
+ * caller can continue the batch per-item.
+ *
+ * @param entry - The push-plan entry to execute.
+ * @param meta - The board metadata (id, Status field).
+ * @param ref - The board reference (for the provenance tag).
+ * @param pmById - Local pm items keyed by id (for body lookup and tagging).
+ * @param pmRoot - Workspace root for the `pm` tag write.
+ * @param token - GitHub token for the GraphQL calls.
+ * @returns Whether the item changed, plus an optional error message.
+ */
 async function applyPushEntry(entry, meta, ref, pmById, pmRoot, token) {
     try {
         let itemId = entry.itemId;
@@ -3001,6 +3397,18 @@ async function applyPushEntry(entry, meta, ref, pmById, pmRoot, token) {
 // and fail for terminal→canceled transitions. Recording `--close-reason` on the
 // `pm update` keeps the distinction AND the lifecycle metadata, and works for
 // active→canceled and terminal→canceled alike.
+/**
+ * Build the `pm` CLI argv that applies one pull (project → pm) status transition.
+ *
+ * Pure so the pm lifecycle contract is unit-testable without spawning `pm`:
+ * `closed` goes through `pm close`; `canceled` keeps its distinct terminal state
+ * via `pm update --status canceled` with `--close-reason`; everything else is a
+ * plain `pm update --status`. See the long note above for the pm CLI contracts.
+ *
+ * @param entry - The pull-plan entry to render argv for.
+ * @param pmRoot - Workspace root for the `pm` invocation.
+ * @returns The argv array.
+ */
 export function buildPullEntryArgs(entry, pmRoot) {
     const reason = `GitHub project status → ${entry.toStatus}`;
     if (entry.toStatus === "closed") {
@@ -3028,8 +3436,15 @@ function applyPullEntry(entry, pmRoot) {
     const res = pmRun(buildPullEntryArgs(entry, pmRoot));
     return res.ok ? { changed: true } : { changed: false, error: res.stderr };
 }
-// Command handler for `pm github project sync`: preview (default) or apply the
-// bidirectional Projects v2 sync plan, honoring --push/--pull/--apply/--ids.
+/**
+ * Command handler for `pm github project sync`: preview or apply the
+ * bidirectional Projects v2 sync plan.
+ *
+ * Honors `--push`/`--pull` (default previews both), `--apply`, `--ids`, and the
+ * `--prefer` conflict winner when both directions touch the same linked item.
+ *
+ * @param ctx - The command-handler context.
+ */
 async function runProjectSync(ctx) {
     const options = ctx.options || {};
     const ref = parseProjectRef(optionString(options, "project") || ctx.args?.[0]);
@@ -3158,8 +3573,16 @@ async function runProjectSync(ctx) {
     }
     return result;
 }
-// Report whether a github subcommand mutates GitHub (for the host CLI's
-// "mutating command" guard), accounting for --dry-run / --apply overrides.
+/**
+ * Report whether a github subcommand will mutate GitHub.
+ *
+ * Feeds the host CLI's "mutating command" guard, accounting for the `--dry-run`
+ * and `--apply` overrides that turn an otherwise-mutating command into a preview.
+ *
+ * @param command - The subcommand string (e.g. `github sync`).
+ * @param options - The raw option object from the command handler.
+ * @returns True when the command will perform real GitHub writes.
+ */
 export function isMutatingGithubCommand(command, options) {
     const cmd = (command || "").toLowerCase();
     const dryRun = optionEnabled(options, "dry-run", "dryRun");
@@ -3251,7 +3674,7 @@ const PROJECT_SYNC_FLAGS = [
 const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-github",
-    version: "2026.8.7",
+    version: "2026.8.15",
     activate(api) {
         // -----------------------------------------------------------------------
         // schema — declare the GitHub provenance fields so the workspace knows them
@@ -3265,21 +3688,36 @@ export default defineExtension({
             { name: "github_updated_at", type: "string", optional: true },
         ]);
         // -----------------------------------------------------------------------
-        // preflight — safe, local guard for mutating github commands.
-        // Runs before pm core commands; it does NOT make network calls (that would
-        // be a surprise side effect on every command) and cannot hard-block (the
-        // runtime swallows preflight throws). It only surfaces a clear, early
-        // warning when a github mutation is requested without a resolvable token;
-        // the authoritative validation + non-zero exit lives in the handlers.
+        // preflight — safe, local guard for mutating github commands. Scoped to
+        // the command paths pm-github owns (the mutating github/gh-issues paths
+        // isMutatingGithubCommand recognizes) so it cannot contend with another
+        // package's preflight override; an unscoped (global) override collides
+        // pairwise with every other installed package's override (pm health reports
+        // extension_preflight_override_collision). It runs before those commands;
+        // it does NOT make network calls (that would be a surprise side effect on
+        // every command) and cannot hard-block (the runtime swallows preflight
+        // throws). It only surfaces a clear, early warning when a github mutation
+        // is requested without a resolvable token; the authoritative validation +
+        // non-zero exit lives in the handlers.
         // -----------------------------------------------------------------------
-        api.registerPreflight((ctx) => {
-            if (isMutatingGithubCommand(ctx.command, ctx.options || {})) {
-                if (!resolveGitHubToken()) {
-                    console.error("[pm-github preflight] this github command mutates remote state but no GitHub " +
-                        "token is resolvable (GITHUB_TOKEN/GH_TOKEN or `gh auth login`). It will fail.");
+        api.registerPreflight({
+            commands: [
+                "github sync",
+                "github export",
+                "github import",
+                "gh-issues import",
+                "github project import",
+                "github project sync",
+            ],
+            run: (ctx) => {
+                if (isMutatingGithubCommand(ctx.command, ctx.options || {})) {
+                    if (!resolveGitHubToken()) {
+                        console.error("[pm-github preflight] this github command mutates remote state but no GitHub " +
+                            "token is resolvable (GITHUB_TOKEN/GH_TOKEN or `gh auth login`). It will fail.");
+                    }
                 }
-            }
-            return {};
+                return {};
+            },
         });
         // -----------------------------------------------------------------------
         // importer — `pm github import <owner/repo>` (idempotent native pipeline)