pm-github 2026.6.1 → 2026.6.3

package/dist/index.js

@@ -1,4 +1,12 @@
-// pm-github — GitHub Issues importer for pm-cli
+// pm-github — GitHub Issues sync (importer / exporter / sync) for pm-cli
+//
+// Capabilities (see manifest.json):
+//   commands   — `pm gh-issues import` (legacy) + `pm github sync`
+//   importers  — `pm github import <owner/repo>` (idempotent native import)
+//   exporters  — `pm github export` (render pm items as a GitHub-issues payload)
+//   schema     — declares github_url / github_number / github_state item fields
+//   hooks      — afterCommand: actionable sync hint for github-linked items
+//   preflight  — local guard for mutating github commands (token presence)
 import https from "node:https";
 import { spawnSync } from "node:child_process";
 const defineExtension = ((extension) => extension);
@@ -22,36 +30,115 @@ export function resolveGitHubToken() {
     }
     return undefined;
 }
-function fetchJSON(url, token) {
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// One low-level request, no retry/backoff (that lives in `request`).
+function requestOnce(method, url, token, payload) {
     return new Promise((resolve, reject) => {
         const headers = {
             "User-Agent": "pm-github",
             Accept: "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
         };
         if (token)
             headers.Authorization = `Bearer ${token}`;
-        const req = https.get(url, { headers }, (res) => {
+        if (payload) {
+            headers["Content-Type"] = "application/json";
+            headers["Content-Length"] = String(Buffer.byteLength(payload));
+        }
+        const req = https.request(url, { method, headers }, (res) => {
             const status = res.statusCode ?? 0;
             if (status >= 300 && status < 400 && res.headers.location) {
-                fetchJSON(res.headers.location, token).then(resolve, reject);
-                return;
-            }
-            if (status !== 200) {
-                res.resume();
-                reject(new Error(`GitHub API returned HTTP ${status}`));
+                requestOnce(method, res.headers.location, token, payload).then(resolve, reject);
                 return;
             }
             const chunks = [];
             res.on("data", (c) => chunks.push(c));
-            res.on("end", () => resolve({
-                body: Buffer.concat(chunks).toString("utf-8"),
-                linkHeader: typeof res.headers.link === "string" ? res.headers.link : undefined,
-            }));
+            res.on("end", () => {
+                resolve({
+                    status,
+                    body: Buffer.concat(chunks).toString("utf-8"),
+                    headers: res.headers,
+                    linkHeader: typeof res.headers.link === "string" ? res.headers.link : undefined,
+                });
+            });
         });
         req.on("error", reject);
-        req.setTimeout(30000, () => { req.destroy(); reject(new Error("timeout")); });
+        req.setTimeout(30000, () => {
+            req.destroy(new Error("request timed out after 30s"));
+        });
+        if (payload)
+            req.write(payload);
+        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.
+export function computeBackoffMs(headers, attempt, nowMs = Date.now()) {
+    const get = (k) => {
+        const v = headers[k] ?? headers[k.toLowerCase()];
+        return Array.isArray(v) ? v[0] : v;
+    };
+    const cap = 60_000;
+    const retryAfter = get("retry-after");
+    if (retryAfter) {
+        const secs = Number(retryAfter);
+        if (Number.isFinite(secs) && secs >= 0)
+            return Math.min(secs * 1000, cap);
+    }
+    const remaining = get("x-ratelimit-remaining");
+    const reset = get("x-ratelimit-reset");
+    if (remaining === "0" && reset) {
+        const resetMs = Number(reset) * 1000;
+        if (Number.isFinite(resetMs)) {
+            const wait = resetMs - nowMs;
+            if (wait > 0)
+                return Math.min(wait + 1000, cap);
+        }
+    }
+    // Exponential backoff: 1s, 2s, 4s … capped.
+    return Math.min(1000 * 2 ** attempt, cap);
+}
+function isRetryableStatus(status, headers) {
+    if (status === 429)
+        return true;
+    if (status >= 500)
+        return true;
+    // Secondary/primary rate limit surfaces as 403 with remaining=0.
+    if (status === 403) {
+        const v = headers["x-ratelimit-remaining"] ?? headers["X-RateLimit-Remaining"];
+        const remaining = Array.isArray(v) ? v[0] : v;
+        if (remaining === "0")
+            return true;
+        if (headers["retry-after"] ?? headers["Retry-After"])
+            return true;
+    }
+    return false;
+}
+// Request with rate-limit/backoff handling. Retries on 429/5xx and GitHub
+// rate-limit 403s, honoring Retry-After / X-RateLimit-Reset. Throws on a
+// non-retryable error status so callers can map it to a semantic exit code.
+async function request(method, url, token, payload, maxRetries = 4) {
+    let attempt = 0;
+    for (;;) {
+        const res = await requestOnce(method, url, token, payload);
+        if (res.status >= 200 && res.status < 300)
+            return res;
+        if (attempt < maxRetries && isRetryableStatus(res.status, res.headers)) {
+            const wait = computeBackoffMs(res.headers, attempt);
+            console.error(`GitHub returned HTTP ${res.status}; retrying in ${Math.round(wait / 1000)}s ` +
+                `(attempt ${attempt + 1}/${maxRetries})…`);
+            await sleep(wait);
+            attempt++;
+            continue;
+        }
+        throw new Error(`GitHub API returned HTTP ${res.status}`);
+    }
+}
+function fetchJSON(url, token) {
+    return request("GET", url, token);
+}
 // Follow GitHub's RFC 5988 Link header so repos with more than one page of
 // issues are fully imported instead of silently truncated at per_page.
 export function parseNextLink(linkHeader) {
@@ -105,149 +192,873 @@ 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.
+export function provenanceTag(repo, issueNumber) {
+    return `gh:${repo.toLowerCase()}#${issueNumber}`;
+}
+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]) };
+}
+function readPmItems(pmRoot) {
+    // `list-all` (NOT `list`) so CLOSED items are included: `pm list` returns only
+    // active items, which would make the idempotency index miss every closed
+    // issue and re-create it as a DUPLICATE on re-import. `--full --include-body`
+    // so tags and body survive the read instead of the brief projection.
+    const result = spawnSync("pm", ["--path", pmRoot, "--json", "list-all", "--full", "--include-body", "--limit", "10000"], { encoding: "utf-8" });
+    if (result.status !== 0) {
+        throw new CommandError(result.stderr || "pm list-all failed");
+    }
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const items = Array.isArray(parsed) ? parsed : parsed.items ?? parsed.results ?? [];
+        return items;
+    }
+    catch {
+        throw new CommandError("Could not parse `pm list-all --json` output.");
+    }
+}
+// Index existing pm items by their GitHub provenance tag for O(1) idempotent
+// matching on re-import.
+export function indexByProvenance(items) {
+    const index = new Map();
+    for (const item of items) {
+        for (const tag of item.tags ?? []) {
+            const p = parseProvenanceTag(tag);
+            if (p && item.id)
+                index.set(`${p.repo}#${p.number}`, item);
+        }
+    }
+    return index;
+}
+// ---------------------------------------------------------------------------
+// Shared import core (used by both the legacy command and the importer)
+// ---------------------------------------------------------------------------
+// Build the GitHub issues list URL. `since`, `assignee`, `labels` and `state`
+// are honored server-side; `milestone` is filtered client-side (the REST API
+// keys milestones by number, not title).
+export function buildIssuesUrl(repo, opts) {
+    let url = `https://api.github.com/repos/${repo}/issues?state=${opts.state}&per_page=100`;
+    if (opts.labels)
+        url += `&labels=${encodeURIComponent(opts.labels)}`;
+    if (opts.since)
+        url += `&since=${encodeURIComponent(opts.since)}`;
+    if (opts.assignee)
+        url += `&assignee=${encodeURIComponent(opts.assignee)}`;
+    return url;
+}
+async function fetchAllIssues(repo, opts, token) {
+    const issues = [];
+    let nextUrl = buildIssuesUrl(repo, opts);
+    while (nextUrl) {
+        const { body, linkHeader } = await fetchJSON(nextUrl, token);
+        let page;
+        try {
+            page = JSON.parse(body);
+        }
+        catch {
+            throw new Error("Invalid JSON response from GitHub.");
+        }
+        if (!Array.isArray(page)) {
+            throw new Error("Unexpected GitHub API response (expected an array of issues).");
+        }
+        issues.push(...page);
+        nextUrl = parseNextLink(linkHeader);
+    }
+    return issues;
+}
+async function fetchComments(issue, repo, token) {
+    if (!issue.comments || issue.comments <= 0)
+        return [];
+    const comments = [];
+    let nextUrl = issue.comments_url ||
+        `https://api.github.com/repos/${repo}/issues/${issue.number}/comments?per_page=100`;
+    while (nextUrl) {
+        const { body, linkHeader } = await fetchJSON(nextUrl, token);
+        let page;
+        try {
+            page = JSON.parse(body);
+        }
+        catch {
+            break;
+        }
+        if (!Array.isArray(page))
+            break;
+        comments.push(...page);
+        nextUrl = parseNextLink(linkHeader);
+    }
+    return comments;
+}
+// Compose the pm item body for an issue, optionally appending its comments.
+export function composeBody(issue, comments) {
+    let body = issue.body || "";
+    if (comments.length > 0) {
+        const rendered = comments
+            .map((c) => {
+            const who = c.user?.login ?? "unknown";
+            const when = c.created_at ? ` (${c.created_at})` : "";
+            return `> **@${who}**${when}\n>\n${(c.body || "").split("\n").map((l) => `> ${l}`).join("\n")}`;
+        })
+            .join("\n\n");
+        body = `${body}\n\n---\n\n### GitHub comments (${comments.length})\n\n${rendered}`.trim();
+    }
+    return body;
+}
+// Apply the client-side filters (PRs, milestone-by-title).
+export function applyClientFilters(issues, opts) {
+    let result = issues;
+    if (!opts.includePrs)
+        result = result.filter((i) => !i.pull_request);
+    if (opts.milestone) {
+        result = result.filter((i) => i.milestone?.title === opts.milestone);
+    }
+    return result;
+}
+export function parseImportOptions(options) {
+    // --state takes precedence; --all is the legacy shorthand for "all".
+    const stateOpt = optionString(options, "state");
+    const includeAll = optionEnabled(options, "all");
+    const state = stateOpt && ["open", "closed", "all"].includes(stateOpt)
+        ? stateOpt
+        : includeAll
+            ? "all"
+            : "open";
+    return {
+        state,
+        labels: optionString(options, "labels"),
+        since: optionString(options, "since"),
+        assignee: optionString(options, "assignee"),
+        milestone: optionString(options, "milestone"),
+        includePrs: optionEnabled(options, "include-prs", "includePrs"),
+        withComments: optionEnabled(options, "with-comments", "withComments"),
+        itemType: optionString(options, "type") || "Issue",
+        dryRun: optionEnabled(options, "dry-run", "dryRun"),
+    };
+}
+function pmRun(args) {
+    const result = spawnSync("pm", args, { encoding: "utf-8" });
+    return { ok: result.status === 0, stderr: result.stderr || "", stdout: result.stdout || "" };
+}
+// 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.
+async function runImport(repoArg, pmRoot, opts) {
+    if (!repoArg || !repoArg.includes("/")) {
+        throw new CommandError("Usage: pm github import <owner/repo> [--all|--state open|closed|all] " +
+            "[--labels bug,enhancement] [--since <iso>] [--assignee <login>] " +
+            "[--milestone <name>] [--include-prs] [--with-comments]", EXIT_CODE.USAGE);
+    }
+    const repo = repoArg;
+    const token = resolveGitHubToken();
+    console.error(`Fetching issues from ${repo}…${token ? "" : " (unauthenticated — 60 req/hr)"}`);
+    let fetched;
+    try {
+        fetched = await fetchAllIssues(repo, opts, token);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const hint = !token && /HTTP 403/.test(msg)
+            ? " — set GITHUB_TOKEN/GH_TOKEN or run `gh auth login` to raise the rate limit (60→5000/hr) and reach private repos"
+            : "";
+        const exitCode = /HTTP 404/.test(msg) ? EXIT_CODE.NOT_FOUND : EXIT_CODE.GENERIC_FAILURE;
+        throw new CommandError(`Failed to fetch issues from ${repo}: ${msg}${hint}`, exitCode);
+    }
+    const filtered = applyClientFilters(fetched, opts);
+    if (filtered.length === 0) {
+        console.error("No issues found.");
+        return { imported: 0, updated: 0, skipped: 0 };
+    }
+    console.error(`Found ${filtered.length} issue(s).`);
+    // Build the idempotency index once up-front.
+    const existing = opts.dryRun ? new Map() : indexByProvenance(readPmItems(pmRoot));
+    let imported = 0;
+    let updated = 0;
+    let skipped = 0;
+    for (const issue of filtered) {
+        const title = issue.title.trim();
+        if (!title) {
+            skipped++;
+            continue;
+        }
+        const kind = issue.pull_request ? "PR" : "issue";
+        const labels = issue.labels.map((l) => l.name).filter(Boolean);
+        const tag = provenanceTag(repo, issue.number);
+        const tags = [...labels, tag];
+        const status = mapState(issue.state);
+        const assignee = issue.assignee?.login;
+        const milestone = issue.milestone?.title;
+        const key = `${repo.toLowerCase()}#${issue.number}`;
+        const match = existing.get(key);
+        // GitHub provenance lives in the description (human-readable) and the
+        // declared schema fields (github_url/github_number/github_state).
+        const description = `GH ${kind} #${issue.number}: ${issue.html_url}`;
+        let comments = [];
+        if (opts.withComments) {
+            try {
+                comments = await fetchComments(issue, repo, token);
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                console.error(`#${issue.number}: failed to fetch comments — ${msg}`);
+            }
+        }
+        const body = composeBody(issue, comments);
+        if (opts.dryRun) {
+            console.error(`  [dry-run] #${issue.number} ${title} (${status}, ${labels.join(",")})`);
+            imported++;
+            continue;
+        }
+        if (match?.id) {
+            // Idempotent update — never duplicate. Status transitions go through the
+            // proper command (close requires a reason; reopen via update --status).
+            const updArgs = [
+                "--path", pmRoot, "update", match.id,
+                "--title", title,
+                "--description", description,
+                "--body", body,
+                "--tags", tags.join(","),
+                "--message", `Re-imported from GitHub #${issue.number}`,
+            ];
+            if (assignee)
+                updArgs.push("--assignee", assignee);
+            if (milestone)
+                updArgs.push("--sprint", milestone);
+            const upd = pmRun(updArgs);
+            if (!upd.ok) {
+                console.error(`#${issue.number}: update failed — ${upd.stderr}`);
+                skipped++;
+                continue;
+            }
+            // Reconcile status separately.
+            if (status === "closed" && match.status !== "closed") {
+                const close = pmRun(["--path", pmRoot, "close", match.id, "--reason", `GitHub issue #${issue.number} closed`]);
+                if (!close.ok) {
+                    console.error(`#${issue.number}: close reconciliation failed — ${close.stderr}`);
+                    skipped++;
+                    continue;
+                }
+            }
+            else if (status === "open" && match.status === "closed") {
+                const reopen = pmRun(["--path", pmRoot, "update", match.id, "--status", "open", "--message", `GitHub issue #${issue.number} reopened`]);
+                if (!reopen.ok) {
+                    console.error(`#${issue.number}: reopen reconciliation failed — ${reopen.stderr}`);
+                    skipped++;
+                    continue;
+                }
+            }
+            updated++;
+            continue;
+        }
+        const createArgs = [
+            "--path", pmRoot, "create",
+            "--title", title,
+            "--type", opts.itemType,
+            "--status", status,
+            "--description", description,
+            "--body", body,
+            "--tags", tags.join(","),
+            "--message", `Imported from GitHub #${issue.number}`,
+        ];
+        if (assignee)
+            createArgs.push("--assignee", assignee);
+        if (milestone)
+            createArgs.push("--sprint", milestone);
+        const created = pmRun(createArgs);
+        if (!created.ok) {
+            console.error(`#${issue.number}: create failed — ${created.stderr}`);
+            skipped++;
+            continue;
+        }
+        imported++;
+    }
+    if (opts.dryRun) {
+        console.error(`[dry-run] Would import ${imported}, skip ${skipped}.`);
+        return { dryRun: true, wouldImport: imported, wouldSkip: skipped };
+    }
+    console.error(`Imported ${imported} new, updated ${updated} existing, skipped ${skipped}.`);
+    if (imported === 0 && updated === 0 && skipped > 0) {
+        throw new CommandError(`Imported 0 issue(s); ${skipped} failed.`);
+    }
+    return { imported, updated, skipped };
+}
+// ---------------------------------------------------------------------------
+// Sync core — push pm status changes back to GitHub (close / reopen)
+// ---------------------------------------------------------------------------
+function pmStatusToGithubState(status) {
+    return status === "closed" || status === "canceled" ? "closed" : "open";
+}
+export function planSync(items, repo) {
+    const plan = [];
+    const repoLc = repo.toLowerCase();
+    for (const item of items) {
+        if (!item.id)
+            continue;
+        for (const tag of item.tags ?? []) {
+            const p = parseProvenanceTag(tag);
+            if (!p || p.repo !== repoLc)
+                continue;
+            const desired = pmStatusToGithubState(item.status);
+            plan.push({
+                id: item.id,
+                number: p.number,
+                title: item.title ?? "(untitled)",
+                // `from` is unknown without a fetch; the planner records desired state
+                // and the executor only PATCHes when GitHub disagrees.
+                from: desired === "open" ? "closed" : "open",
+                to: desired,
+            });
+        }
+    }
+    return plan;
+}
+async function runSync(ctx) {
+    const options = ctx.options || {};
+    const repo = optionString(options, "repo") || ctx.args?.[0];
+    const dryRun = optionEnabled(options, "dry-run", "dryRun");
+    if (!repo || !repo.includes("/")) {
+        throw new CommandError("Usage: pm github sync --repo <owner/repo> [--dry-run]  " +
+            "(pushes pm item status to the linked GitHub issue: close/reopen)", EXIT_CODE.USAGE);
+    }
+    const token = resolveGitHubToken();
+    if (!token && !dryRun) {
+        throw new CommandError("pm github sync needs a GitHub token to mutate issues " +
+            "(set GITHUB_TOKEN/GH_TOKEN or run `gh auth login`). Use --dry-run to preview without a token.", EXIT_CODE.USAGE);
+    }
+    const items = readPmItems(ctx.pm_root);
+    const plan = planSync(items, repo);
+    if (plan.length === 0) {
+        console.error(`No pm items linked to ${repo} (no \`gh:${repo.toLowerCase()}#N\` provenance tags).`);
+        return { synced: 0, skipped: 0, planned: 0 };
+    }
+    let synced = 0;
+    let skipped = 0;
+    for (const entry of plan) {
+        // Fetch current state so we only PATCH on a genuine divergence.
+        let current;
+        try {
+            const { body } = await fetchJSON(`https://api.github.com/repos/${repo}/issues/${entry.number}`, token);
+            current = JSON.parse(body);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`#${entry.number}: could not read upstream state — ${msg}`);
+            skipped++;
+            continue;
+        }
+        if (current.state === entry.to) {
+            skipped++;
+            continue;
+        }
+        if (dryRun) {
+            console.error(`  [dry-run] #${entry.number} "${entry.title}": ${current.state} → ${entry.to}`);
+            synced++;
+            continue;
+        }
+        try {
+            await request("PATCH", `https://api.github.com/repos/${repo}/issues/${entry.number}`, token, JSON.stringify({ state: entry.to }));
+            console.error(`#${entry.number} "${entry.title}": ${current.state} → ${entry.to}`);
+            synced++;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            console.error(`#${entry.number}: PATCH failed — ${msg}`);
+            skipped++;
+        }
+    }
+    if (dryRun) {
+        console.error(`[dry-run] Would update ${synced} issue(s) on ${repo}; ${skipped} already in sync/failed.`);
+        return { dryRun: true, wouldSync: synced, skipped, planned: plan.length };
+    }
+    console.error(`Synced ${synced} issue(s) on ${repo}; skipped ${skipped}.`);
+    return { synced, skipped, planned: plan.length };
+}
+function itemToGithubPayload(item) {
+    return {
+        title: item.title ?? "(untitled)",
+        body: item.body || item.description || "",
+        // Drop our internal provenance tags from exported labels.
+        labels: (item.tags ?? []).filter((t) => !parseProvenanceTag(t)),
+        state: item.status === "closed" || item.status === "canceled" ? "closed" : "open",
+    };
+}
+// Build the create/update plan. `repo` (lowercased) decides which provenance
+// tags count as an "already exported to THIS repo" link → update; everything
+// else is a create. Pure + side-effect free so it can be unit-tested and
+// printed verbatim in --dry-run.
+export function buildExportPlan(items, repo) {
+    const repoLc = repo?.toLowerCase();
+    const plan = [];
+    for (const item of items) {
+        const payload = itemToGithubPayload(item);
+        let number;
+        if (repoLc) {
+            for (const tag of item.tags ?? []) {
+                const p = parseProvenanceTag(tag);
+                if (p && p.repo === repoLc) {
+                    number = p.number;
+                    break;
+                }
+            }
+        }
+        plan.push({
+            id: item.id,
+            action: number === undefined ? "create" : "update",
+            ...(number === undefined ? {} : { number }),
+            payload,
+        });
+    }
+    return plan;
+}
+// Export is SAFE BY DEFAULT: it only performs real GitHub writes when the user
+// explicitly opts in (--apply / --no-dry-run, or the legacy --push alias) AND
+// has not also passed --dry-run (which always wins). Anything else is a
+// preview that prints the plan without touching GitHub.
+export function exportWillApply(options) {
+    if (optionEnabled(options, "dry-run", "dryRun"))
+        return false;
+    if (optionEnabled(options, "no-dry-run", "noDryRun"))
+        return true;
+    return optionEnabled(options, "apply", "push");
+}
+// ---------------------------------------------------------------------------
+// Search provider — reach GitHub from `pm search` for imported items
+// ---------------------------------------------------------------------------
+//
+// The pm search runtime maps a provider's hits back to LOCAL item documents by
+// id and DROPS any hit whose id is not a local item (see
+// normalizeExtensionProviderHits in @unbrained/pm-cli). So this provider cannot
+// surface arbitrary remote issues; instead it asks GitHub which issues in the
+// 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.
+export function buildSearchUrl(repo, query) {
+    const q = `${query} repo:${repo} type:issue`;
+    return `https://api.github.com/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.
+export function mapSearchHits(matchedNumbers, repo, itemsByProvenance) {
+    const repoLc = repo.toLowerCase();
+    const hits = [];
+    const seen = new Set();
+    let rank = matchedNumbers.length;
+    for (const number of matchedNumbers) {
+        const item = itemsByProvenance.get(`${repoLc}#${number}`);
+        if (!item?.id || seen.has(item.id)) {
+            rank--;
+            continue;
+        }
+        seen.add(item.id);
+        // Preserve GitHub's ranking: earlier results score higher. Normalize to
+        // (0, 1] so hits clear pm's default score threshold.
+        hits.push({
+            id: item.id,
+            score: matchedNumbers.length > 0 ? rank / matchedNumbers.length : 1,
+            matched_fields: [`github:${repoLc}#${number}`],
+        });
+        rank--;
+    }
+    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).
+export function resolveSearchRepo(options) {
+    const opt = optionString(options, "repo", "github-repo", "githubRepo");
+    if (opt && opt.includes("/"))
+        return opt;
+    const env = process.env.PM_GITHUB_REPO;
+    if (env && env.includes("/"))
+        return env.trim();
+    return undefined;
+}
+function detectGhCli() {
+    try {
+        const r = spawnSync("gh", ["--version"], { encoding: "utf-8" });
+        return r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+function detectTokenSource() {
+    if ((process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "").trim())
+        return "env";
+    const token = resolveGitHubToken();
+    return token ? "gh" : "none";
+}
+async function runValidate(ctx) {
+    const options = ctx.options || {};
+    const repo = optionString(options, "repo") || ctx.args?.[0];
+    const gh_cli = detectGhCli();
+    const token_source = detectTokenSource();
+    const token = resolveGitHubToken();
+    const report = {
+        ok: true,
+        gh_cli,
+        token: Boolean(token),
+        token_source,
+        messages: [],
+    };
+    if (!token) {
+        report.messages.push("No GitHub token resolvable (GITHUB_TOKEN/GH_TOKEN or `gh auth login`); " +
+            "reads are capped at 60 req/hr and private repos are unreachable.");
+    }
+    else {
+        report.messages.push(`GitHub token resolved via ${token_source === "env" ? "environment" : "gh CLI"}.`);
+    }
+    if (!gh_cli)
+        report.messages.push("`gh` CLI not found on PATH (optional; only used to borrow a token).");
+    if (repo) {
+        if (!repo.includes("/")) {
+            report.ok = false;
+            report.messages.push(`Invalid --repo "${repo}" (expected owner/repo).`);
+        }
+        else {
+            report.repo = repo;
+            try {
+                const res = await fetchJSON(`https://api.github.com/repos/${repo}`, token);
+                report.repo_accessible = res.status >= 200 && res.status < 300;
+                report.repo_status = res.status;
+                const rem = res.headers["x-ratelimit-remaining"] ?? res.headers["X-RateLimit-Remaining"];
+                const remStr = Array.isArray(rem) ? rem[0] : rem;
+                if (remStr !== undefined)
+                    report.rate_limit_remaining = Number(remStr);
+                if (report.repo_accessible) {
+                    report.messages.push(`Repo ${repo} is accessible (HTTP ${res.status}).`);
+                }
+                else {
+                    report.ok = false;
+                    report.messages.push(`Repo ${repo} returned HTTP ${res.status}.`);
+                }
+            }
+            catch (err) {
+                report.ok = false;
+                report.repo_accessible = false;
+                report.messages.push(`Repo ${repo} check failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    else {
+        report.messages.push("No --repo given; skipped repo accessibility check.");
+    }
+    return report;
+}
+// ---------------------------------------------------------------------------
+// Preflight — local guard for mutating github commands (no network in-hook)
+// ---------------------------------------------------------------------------
+// Returns true if the command/args describe a github operation that will MUTATE
+// state (a write import, an export --push, or a non-dry-run sync).
+export function isMutatingGithubCommand(command, options) {
+    const cmd = (command || "").toLowerCase();
+    const dryRun = optionEnabled(options, "dry-run", "dryRun");
+    if (cmd === "github sync")
+        return !dryRun;
+    // Export is dry-run by default; it only mutates with an explicit apply
+    // (--apply / --no-dry-run / legacy --push) AND no --dry-run override.
+    if (cmd === "github export")
+        return exportWillApply(options);
+    if (cmd === "github import" || cmd === "gh-issues import")
+        return !dryRun;
+    return false;
+}
+// ---------------------------------------------------------------------------
 // Extension
 // ---------------------------------------------------------------------------
+const IMPORT_FLAGS = [
+    { long: "--all", description: "Include closed issues (shorthand for --state all)" },
+    { long: "--state", value_name: "state", description: "Issue state: open | closed | all (default: open)" },
+    { long: "--labels", value_name: "labels", description: "Comma-separated label filter" },
+    { long: "--since", value_name: "iso", description: "Only issues updated after this ISO timestamp (incremental sync)" },
+    { long: "--assignee", value_name: "login", description: "Filter by assignee login" },
+    { long: "--milestone", value_name: "name", description: "Filter by milestone title" },
+    { long: "--include-prs", description: "Include pull requests (default: skip PRs)" },
+    { long: "--with-comments", description: "Fetch issue comments and append them to the item body" },
+    { long: "--dry-run", description: "Preview without writing" },
+    { long: "--type", value_name: "type", description: "Override pm item type (default: Issue)" },
+];
+const SYNC_FLAGS = [
+    { long: "--repo", value_name: "owner/repo", description: "Target GitHub repo (required)" },
+    { long: "--dry-run", description: "Preview the close/reopen plan without mutating GitHub" },
+];
+const VALIDATE_FLAGS = [
+    { long: "--repo", value_name: "owner/repo", description: "Also check this repo is accessible with the resolved token" },
+];
 export default defineExtension({
     name: "pm-github",
-    version: "2026.6.1",
+    version: "2026.6.3",
     activate(api) {
         // -----------------------------------------------------------------------
-        // Command: pm gh-issues import <owner/repo>
+        // schema — declare the GitHub provenance fields so the workspace knows them
+        // -----------------------------------------------------------------------
+        api.registerItemFields([
+            { name: "github_url", type: "string", optional: true },
+            { name: "github_number", type: "number", optional: true },
+            { name: "github_state", 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.
+        // -----------------------------------------------------------------------
+        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.");
+                }
+            }
+            return {};
+        });
+        // -----------------------------------------------------------------------
+        // importer — `pm github import <owner/repo>` (idempotent native pipeline)
+        // -----------------------------------------------------------------------
+        api.registerImporter("github", async (ctx) => {
+            return runImport(ctx.args?.[0], ctx.pm_root, parseImportOptions(ctx.options || {}));
+        });
+        // -----------------------------------------------------------------------
+        // exporter — `pm github export` (pm items → GitHub issues)
+        // SAFE BY DEFAULT: previews the create/update plan and writes NOTHING.
+        // Real writes happen only with --apply (or --no-dry-run / legacy --push)
+        // AND a token AND --repo <owner/repo>. With --repo, items already linked to
+        // an issue in that repo (via the `gh:repo#N` provenance tag) are UPDATEd
+        // (upsert) rather than duplicated. --json returns the plan object; we never
+        // write our own stdout in JSON mode (pm renders the return value).
+        // -----------------------------------------------------------------------
+        api.registerExporter("github", async (ctx) => {
+            const options = ctx.options || {};
+            const jsonMode = ctx.global?.json === true;
+            const format = optionString(options, "format") || "json";
+            const repo = optionString(options, "repo") || ctx.args?.[0];
+            const apply = exportWillApply(options);
+            const items = readPmItems(ctx.pm_root);
+            const plan = buildExportPlan(items, repo);
+            const creates = plan.filter((e) => e.action === "create").length;
+            const updates = plan.filter((e) => e.action === "update").length;
+            if (!apply) {
+                // Dry-run (default). Emit the plan; in JSON mode return it silently.
+                if (!jsonMode) {
+                    if (format === "md" || format === "markdown") {
+                        const md = plan
+                            .map((e) => {
+                            const head = e.action === "update" ? `## [update #${e.number}] ${e.payload.title}` : `## [create] ${e.payload.title}`;
+                            return `${head}\n\n${e.payload.body}\n\n_labels: ${e.payload.labels.join(", ")} · state: ${e.payload.state}_\n`;
+                        })
+                            .join("\n");
+                        console.log(md);
+                    }
+                    else {
+                        console.log(JSON.stringify(plan, null, 2));
+                    }
+                    console.error(`[dry-run] Would create ${creates} and update ${updates} issue(s)` +
+                        `${repo ? ` on ${repo}` : " (no --repo: all treated as create)"}. ` +
+                        "Re-run with --apply --repo <owner/repo> to write to GitHub.");
+                }
+                return { dry_run: true, plan, would_create: creates, would_update: updates, repo };
+            }
+            // --apply path: real writes. Require token + repo.
+            const token = resolveGitHubToken();
+            if (!token) {
+                throw new CommandError("--apply requires a GitHub token (set GITHUB_TOKEN/GH_TOKEN or run `gh auth login`).", EXIT_CODE.USAGE);
+            }
+            if (!repo || !repo.includes("/")) {
+                throw new CommandError("--apply requires --repo <owner/repo>.", EXIT_CODE.USAGE);
+            }
+            let created = 0;
+            let updated = 0;
+            for (const entry of plan) {
+                const p = entry.payload;
+                if (entry.action === "update" && entry.number !== undefined) {
+                    await request("PATCH", `https://api.github.com/repos/${repo}/issues/${entry.number}`, token, JSON.stringify({ title: p.title, body: p.body, labels: p.labels, state: p.state }));
+                    updated++;
+                }
+                else {
+                    await request("POST", `https://api.github.com/repos/${repo}/issues`, token, JSON.stringify({ title: p.title, body: p.body, labels: p.labels }));
+                    created++;
+                }
+            }
+            if (!jsonMode)
+                console.error(`Created ${created} and updated ${updated} issue(s) on ${repo}.`);
+            return { applied: true, created, updated, repo };
+        });
+        // -----------------------------------------------------------------------
+        // search — reach GitHub from `pm search` for imported items.
+        // Guarded by a capability check so it is a no-op on runtimes that predate
+        // search providers. The provider asks GitHub which issues in the configured
+        // repo match the query, then returns hits for the LOCAL pm items imported
+        // from those issues (the runtime drops hits that aren't local documents).
+        // Activates in semantic/hybrid mode: `pm search "<q>" --semantic`.
+        // -----------------------------------------------------------------------
+        if (typeof api.registerSearchProvider === "function") {
+            api.registerSearchProvider({
+                name: "github",
+                async query(qctx) {
+                    const repo = resolveSearchRepo(qctx.options || {});
+                    if (!repo)
+                        return [];
+                    const token = resolveGitHubToken();
+                    let matchedNumbers;
+                    try {
+                        const { body } = await fetchJSON(buildSearchUrl(repo, qctx.query), token);
+                        const parsed = JSON.parse(body);
+                        matchedNumbers = (parsed.items ?? [])
+                            .map((i) => i.number)
+                            .filter((n) => typeof n === "number");
+                    }
+                    catch {
+                        // Network/parse failure → no remote hits; pm degrades to keyword.
+                        return [];
+                    }
+                    // Map remote matches back to local items via provenance tags. Prefer
+                    // the runtime-provided documents (already the current corpus); fall
+                    // back to a fresh read if absent.
+                    const docs = Array.isArray(qctx.documents)
+                        ? qctx.documents.map((d) => (d?.metadata ? d.metadata : d))
+                        : readPmItems(qctx.pm_root || ".agents/pm");
+                    const index = indexByProvenance(docs);
+                    return mapSearchHits(matchedNumbers, repo, index);
+                },
+            });
+        }
+        // -----------------------------------------------------------------------
+        // hooks — actionable sync reminder for github-linked items.
+        // Safe + no network: only emits a hint, gated on PM_GITHUB_SYNC, and names
+        // the exact command to run. Triggers only when a github-linked item (one
+        // carrying a `gh:owner/repo#N` provenance tag) is closed/reopened.
+        // -----------------------------------------------------------------------
+        api.hooks.afterCommand((ctx) => {
+            if (!process.env.PM_GITHUB_SYNC)
+                return;
+            if (!ctx.ok)
+                return;
+            if (ctx.command !== "close" && ctx.command !== "update")
+                return;
+            // Only nudge for items that are actually linked to GitHub.
+            const id = ctx.args?.[0];
+            if (!id || !ctx.pm_root)
+                return;
+            const res = spawnSync("pm", ["--path", ctx.pm_root, "--json", "show", id], { encoding: "utf-8" });
+            if (res.status !== 0)
+                return;
+            let repo;
+            try {
+                const item = JSON.parse(res.stdout);
+                for (const tag of item?.tags ?? []) {
+                    const p = parseProvenanceTag(String(tag));
+                    if (p) {
+                        repo = p.repo;
+                        break;
+                    }
+                }
+            }
+            catch {
+                return;
+            }
+            if (!repo)
+                return;
+            console.error(`[pm-github] ${id} is linked to ${repo}; run \`pm github sync --repo ${repo}\` ` +
+                "to push this status change upstream (or --dry-run to preview).");
+        });
+        // -----------------------------------------------------------------------
+        // command — `pm github sync` (push pm status → GitHub close/reopen)
+        // -----------------------------------------------------------------------
+        api.registerCommand({
+            name: "github sync",
+            description: "Push pm item status changes back to GitHub: close/reopen the linked " +
+                "issue (matched by the `gh:owner/repo#N` provenance tag) to match the pm " +
+                "item's status. Requires a GitHub token and explicit --repo. Use --dry-run " +
+                "to preview the plan without mutating anything.",
+            intent: "sync pm item status to the linked GitHub issue state",
+            examples: [
+                "pm github sync --repo unbraind/pm-cli --dry-run",
+                "pm github sync --repo unbraind/pm-cli",
+            ],
+            flags: SYNC_FLAGS,
+            failure_hints: [
+                "Set GITHUB_TOKEN/GH_TOKEN or run `gh auth login` (sync mutates remote issues).",
+                "Pass --repo <owner/repo> explicitly; sync never guesses the target repo.",
+                "Items must carry a `gh:owner/repo#N` tag — import with `pm github import` first.",
+                "Use --dry-run to preview the close/reopen plan before pushing.",
+            ],
+            async run(ctx) {
+                return runSync(ctx);
+            },
+        });
+        // -----------------------------------------------------------------------
+        // command — legacy `pm gh-issues import <owner/repo>` (delegates to core)
         // -----------------------------------------------------------------------
         api.registerCommand({
             name: "gh-issues import",
-            description: "Fetch GitHub issues from a repo and create pm items. " +
-                "Skips pull requests by default. Uses GITHUB_TOKEN/GH_TOKEN (or the " +
-                "authenticated gh CLI) when available for 5000 req/hr and private repos; " +
-                "falls back to the unauthenticated API (60 req/hr).",
+            description: "Fetch GitHub issues from a repo and create/update pm items (idempotent " +
+                "on re-import via the `gh:owner/repo#N` provenance tag). Skips pull " +
+                "requests by default. Uses GITHUB_TOKEN/GH_TOKEN (or the authenticated " +
+                "gh CLI) when available for 5000 req/hr and private repos; falls back to " +
+                "the unauthenticated API (60 req/hr). Equivalent to `pm github import`.",
             intent: "import GitHub issues as pm items",
             examples: [
                 "pm gh-issues import unbraind/pm-cli",
                 "pm gh-issues import unbraind/pm-cli --all",
                 "pm gh-issues import unbraind/pm-cli --labels bug,enhancement",
-                "pm gh-issues import owner/repo --dry-run",
+                "pm gh-issues import unbraind/pm-cli --since 2026-01-01T00:00:00Z",
+                "pm github import owner/repo --with-comments",
+                "pm github import owner/repo --dry-run",
             ],
-            flags: [
-                { long: "--all", description: "Include closed issues (default: open only)" },
-                { long: "--labels", value_name: "labels", description: "Comma-separated label filter" },
-                { long: "--dry-run", description: "Preview without writing" },
-                { long: "--type", value_name: "type", description: "Override pm item type (default: Issue)" },
+            flags: IMPORT_FLAGS,
+            failure_hints: [
+                "Pass <owner/repo>, e.g. `pm gh-issues import unbraind/pm-cli`.",
+                "Set GITHUB_TOKEN/GH_TOKEN or run `gh auth login` for private repos / 5000 req/hr.",
+                "Re-running is safe: existing items are updated, not duplicated.",
             ],
             async run(ctx) {
-                const repoArg = ctx.args[0];
-                if (!repoArg || !repoArg.includes("/")) {
-                    // Throw with a USAGE exit code so the CLI exits non-zero AND the
-                    // runtime treats the command as handled (a returned { error } reads
-                    // as success; a plain Error triggers a second handler invocation).
-                    throw new CommandError("Usage: pm gh-issues import <owner/repo> [--all] [--labels bug,enhancement]", EXIT_CODE.USAGE);
-                }
-                const includeAll = optionEnabled(ctx.options, "all");
-                const labelsFilter = optionString(ctx.options, "labels");
-                // Read both kebab and camelCase keys — the runtime may normalize
-                // "--dry-run" to "dryRun", and reading only "dry-run" silently ignored
-                // the flag (writing items even in preview mode).
-                const dryRun = optionEnabled(ctx.options, "dry-run", "dryRun");
-                const itemType = optionString(ctx.options, "type") || "Issue";
-                const state = includeAll ? "all" : "open";
-                let url = `https://api.github.com/repos/${repoArg}/issues?state=${state}&per_page=100`;
-                if (labelsFilter) {
-                    url += `&labels=${encodeURIComponent(labelsFilter)}`;
-                }
-                const token = resolveGitHubToken();
-                console.error(`Fetching issues from ${repoArg}…${token ? "" : " (unauthenticated — 60 req/hr)"}`);
-                const issues = [];
-                let nextUrl = url;
-                try {
-                    while (nextUrl) {
-                        const { body, linkHeader } = await fetchJSON(nextUrl, token);
-                        let page;
-                        try {
-                            page = JSON.parse(body);
-                        }
-                        catch {
-                            throw new Error("Invalid JSON response from GitHub.");
-                        }
-                        if (!Array.isArray(page)) {
-                            throw new Error("Unexpected GitHub API response (expected an array of issues).");
-                        }
-                        issues.push(...page);
-                        nextUrl = parseNextLink(linkHeader);
-                    }
-                }
-                catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    const hint = !token && /HTTP 403/.test(msg)
-                        ? " — set GITHUB_TOKEN/GH_TOKEN or run `gh auth login` to raise the rate limit (60→5000/hr) and reach private repos"
-                        : "";
-                    // Throw so the CLI exits non-zero on a failed fetch. A 404 maps to
-                    // NOT_FOUND; everything else (403, 5xx, timeouts) is a generic failure.
-                    const exitCode = /HTTP 404/.test(msg) ? EXIT_CODE.NOT_FOUND : EXIT_CODE.GENERIC_FAILURE;
-                    throw new CommandError(`Failed to fetch issues from ${repoArg}: ${msg}${hint}`, exitCode);
-                }
-                // Filter out PRs
-                const filtered = issues.filter((i) => !i.pull_request);
-                if (filtered.length === 0) {
-                    console.error("No issues found.");
-                    return { imported: 0, skipped: 0 };
-                }
-                console.error(`Found ${filtered.length} issue(s).`);
-                let imported = 0;
-                let skipped = 0;
-                for (const issue of filtered) {
-                    const title = issue.title.trim();
-                    if (!title) {
-                        skipped++;
-                        continue;
-                    }
-                    const tags = issue.labels.map((l) => l.name);
-                    const status = mapState(issue.state);
-                    const body = issue.body || "";
-                    const description = `GH #${issue.number}: ${issue.html_url}`;
-                    const assignee = issue.assignee?.login;
-                    const milestone = issue.milestone?.title;
-                    if (dryRun) {
-                        console.error(`  [dry-run] #${issue.number} ${title} (${status}, ${tags.join(",")})`);
-                        imported++;
-                        continue;
-                    }
-                    try {
-                        const spawnArgs = [
-                            "--path", ctx.pm_root,
-                            "create",
-                            "--title", title,
-                            "--type", itemType,
-                            "--status", status,
-                            "--description", description,
-                            "--body", body,
-                            "--tags", tags.join(","),
-                            "--message", `Imported from GitHub #${issue.number}`,
-                        ];
-                        if (assignee)
-                            spawnArgs.push("--assignee", assignee);
-                        if (milestone)
-                            spawnArgs.push("--sprint", milestone);
-                        const result = spawnSync("pm", spawnArgs, { encoding: "utf-8" });
-                        if (result.status !== 0) {
-                            throw new Error(result.stderr || "pm create failed");
-                        }
-                        imported++;
-                    }
-                    catch (err) {
-                        const msg = err instanceof Error ? err.message : String(err);
-                        console.error(`#${issue.number}: create failed — ${msg}`);
-                        skipped++;
-                    }
-                }
-                if (dryRun) {
-                    console.error(`[dry-run] Would import ${imported}, skip ${skipped}.`);
-                    return { dryRun: true, wouldImport: imported, wouldSkip: skipped };
+                return runImport(ctx.args[0], ctx.pm_root, parseImportOptions(ctx.options));
+            },
+        });
+        // -----------------------------------------------------------------------
+        // command — `pm github validate` (diagnostics: gh/token/repo reachability)
+        // -----------------------------------------------------------------------
+        api.registerCommand({
+            name: "github validate",
+            description: "Diagnose the GitHub integration: whether the `gh` CLI is present, " +
+                "whether a token is resolvable (and from where), and—if --repo is " +
+                "given—whether that repo is accessible with the resolved token. " +
+                "Read-only; never mutates anything. Use --json for machine output.",
+            intent: "check gh/token availability and repo accessibility",
+            examples: [
+                "pm github validate",
+                "pm github validate --repo unbraind/pm-cli",
+                "pm github validate --repo unbraind/pm-cli --json",
+            ],
+            flags: VALIDATE_FLAGS,
+            failure_hints: [
+                "Set GITHUB_TOKEN/GH_TOKEN or run `gh auth login` to raise the rate limit and reach private repos.",
+                "Pass --repo <owner/repo> to verify a specific repo is reachable.",
+            ],
+            async run(ctx) {
+                const report = await runValidate(ctx);
+                const jsonMode = ctx.global?.json === true;
+                if (!jsonMode) {
+                    for (const line of report.messages)
+                        console.error(line);
                 }
-                console.error(`Imported ${imported} issue(s), skipped ${skipped}.`);
-                if (imported === 0 && skipped > 0) {
-                    // Every create failed — surface as a non-zero exit for automation.
-                    throw new CommandError(`Imported 0 issue(s); ${skipped} failed.`);
+                if (!report.ok) {
+                    // Surface a non-zero exit for scripts; the report still returns so
+                    // --json consumers get structured detail.
+                    throw new CommandError(report.messages.join(" "), report.repo && report.repo_accessible === false ? EXIT_CODE.NOT_FOUND : EXIT_CODE.GENERIC_FAILURE);
                 }
-                return { imported, skipped };
+                return report;
             },
         });
     },