pm-github 2026.7.22 → 2026.7.25

package/dist/index.js

@@ -444,11 +444,23 @@ export function scopeItemsByIds(items, ids) {
 // Read every pm item (active + closed) via `pm list-all --full --include-body`
 // so the idempotency index never misses closed issues and re-creates them.
 function readPmItems(pmRoot) {
+    const maxBuffer = pmJsonMaxBuffer();
     // `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" });
+    const result = spawnSync("pm", ["--path", pmRoot, "--json", "list-all", "--full", "--include-body", "--limit", "10000"], { encoding: "utf-8", maxBuffer });
+    // A buffer overrun kills the child with status null and no stderr, so name the
+    // real cause instead of reporting an unexplained failure.
+    if (result.error) {
+        const code = result.error.code;
+        if (code === "ENOBUFS") {
+            throw new CommandError(`pm list-all output exceeded the ${maxBuffer} byte read buffer. ` +
+                "The workspace is larger than this read limit; narrow the import " +
+                "(for example --labels or --since) or raise the PM_JSON_MAX_BUFFER env var.");
+        }
+        throw new CommandError(`pm list-all failed: ${result.error.message}`);
+    }
     if (result.status !== 0) {
         throw new CommandError(result.stderr || "pm list-all failed");
     }
@@ -477,6 +489,23 @@ export function indexByProvenance(items) {
 // ---------------------------------------------------------------------------
 // Atomic GitHub issue import (pm-cli >= 2026.7.20 commitItemMutations)
 // ---------------------------------------------------------------------------
+// Node's spawnSync defaults to a 1 MiB stdout cap. A mature tracker's full JSON
+// dump (`pm list-all --full --include-body`) passes that at a few hundred items,
+// and the child is then killed with ENOBUFS, status null and EMPTY stderr — which
+// surfaced as a bare "pm list-all failed" with nothing to diagnose. Reproduced on
+// a real 443-item workspace at 1,052,859 bytes. 64 MiB matches the cap the sibling
+// pm packages settled on (pm-changelog, pm-context, pm-brief).
+/** Read-buffer cap for `pm` output, in bytes. 64 MiB by default; override with the
+ * `PM_JSON_MAX_BUFFER` env var. Resolved per call so the override takes effect
+ * without an import-order dependency. Invalid or non-positive values fall back to
+ * the default rather than silently disabling the guard. */
+function pmJsonMaxBuffer() {
+    // Number(), not parseInt(): parseInt("64MiB") silently yields 64, which would
+    // impose a 64-BYTE cap and break every ordinary read while appearing to honor
+    // the documented invalid-value fallback. Number() rejects the whole string.
+    const raw = Number(process.env.PM_JSON_MAX_BUFFER);
+    return Number.isSafeInteger(raw) && raw > 0 ? raw : 64 * 1024 * 1024;
+}
 const ATOMIC_IMPORT_PREFIX = "github-import-";
 let cachedCommitItemMutations;
 function assertSdkFunction(fn, exportName) {
@@ -1257,15 +1286,263 @@ export function parseImportOptions(options) {
         itemType: optionString(options, "type") || "Issue",
         dryRun: optionEnabled(options, "dry-run", "dryRun"),
         atomic: optionEnabled(options, "atomic"),
+        linkDeps: optionEnabled(options, "link-deps", "linkDeps"),
     };
 }
 // Spawn the `pm` CLI with the given argv and return a normalized ok/stdout/stderr
 // result (ok = exit code 0). Centralizes every pm mutation so callers share one
 // error-handling shape.
 function pmRun(args) {
-    const result = spawnSync("pm", args, { encoding: "utf-8" });
+    const maxBuffer = pmJsonMaxBuffer();
+    const result = spawnSync("pm", args, { encoding: "utf-8", maxBuffer });
     return { ok: result.status === 0, stderr: result.stderr || "", stdout: result.stdout || "" };
 }
+// Strip fenced (```…```) and inline (`…`) code so `#123` mentions inside code
+// samples never masquerade as declared dependencies.
+function stripCodeSpans(body) {
+    return body
+        .replace(/```[\s\S]*?```/g, " ")
+        .replace(/`[^`]*`/g, " ");
+}
+// A dependency phrase at a word boundary, plus trailing separator. Global +
+// case-insensitive; each match anchors where the reference run begins.
+const DEP_PHRASE_RE = /\b(blocked[\s-]?by|depends[\s-]?on|blocks)\b[\s:]*/gi;
+// One `owner/repo#N` or bare `#N` reference, matched STICKILY (`y`) so it only
+// succeeds at the exact scan position — no scanning ahead, no backtracking.
+const DEP_REF_STICKY = /(?:([A-Za-z0-9._-]+\/[A-Za-z0-9._-]+))?#(\d+)/y;
+// Comma/whitespace glue with an optional "and" between consecutive refs
+// ("#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;
+function phraseToKind(raw) {
+    const compact = raw.toLowerCase().replace(/[\s-]/g, "");
+    if (compact === "blocks")
+        return { kind: "blocks", phrase: "blocks" };
+    if (compact === "dependson")
+        return { kind: "blocked_by", phrase: "depends on" };
+    return { kind: "blocked_by", phrase: "blocked by" };
+}
+/**
+ * Parse dependency references from one issue body. Pure. Bare `#N` refs resolve
+ * against `sourceRepo` (lowercased); `owner/repo#N` refs keep their explicit
+ * repo (lowercased). References are de-duplicated within the body by
+ * repo+number+kind so a body repeating a link yields one ref.
+ *
+ * Scanning is linear: each dependency phrase is found once, then references are
+ * consumed one at a time with sticky (`y`) regexes anchored at the exact scan
+ * position. There is no nested quantifier or look-ahead over unbounded input,
+ * so the parser cannot backtrack catastrophically on adversarial bodies.
+ */
+export function parseDependencyReferences(body, sourceRepo) {
+    if (!body)
+        return [];
+    const text = stripCodeSpans(body);
+    const repoLc = sourceRepo.toLowerCase();
+    const out = [];
+    const seen = new Set();
+    for (const m of text.matchAll(DEP_PHRASE_RE)) {
+        const { kind, phrase } = phraseToKind(m[1]);
+        let pos = m.index + m[0].length;
+        // Consume the run of references immediately following the phrase.
+        for (;;) {
+            DEP_REF_STICKY.lastIndex = pos;
+            const ref = DEP_REF_STICKY.exec(text);
+            if (!ref)
+                break;
+            const repo = (ref[1] ? ref[1] : repoLc).toLowerCase();
+            const number = Number.parseInt(ref[2], 10);
+            if (Number.isSafeInteger(number) && number > 0) {
+                const key = `${repo}#${number}|${kind}`;
+                if (!seen.has(key)) {
+                    seen.add(key);
+                    out.push({ repo, number, kind, phrase });
+                }
+            }
+            pos = DEP_REF_STICKY.lastIndex;
+            // Skip separator glue; if no further ref follows, the next iteration's
+            // sticky match fails at `pos` and the run ends.
+            DEP_GLUE_STICKY.lastIndex = pos;
+            DEP_GLUE_STICKY.exec(text);
+            pos = DEP_GLUE_STICKY.lastIndex;
+        }
+    }
+    return out;
+}
+/** Build a `repo#number` → pm item id index from an item-metadata snapshot. */
+export function buildProvenanceIndexFromMetadata(items) {
+    const index = new Map();
+    for (const item of items) {
+        if (!item.id)
+            continue;
+        for (const tag of item.tags ?? []) {
+            const p = parseProvenanceTag(tag);
+            // First writer wins: a provenance tag is a 1:1 issue↔item link, and the
+            // import guarantees uniqueness; guarding keeps a hand-edited duplicate
+            // deterministic rather than order-dependent.
+            if (p && !index.has(`${p.repo}#${p.number}`)) {
+                index.set(`${p.repo}#${p.number}`, item.id);
+            }
+        }
+    }
+    return index;
+}
+/**
+ * Resolve parsed references into concrete workspace edges. Skips references
+ * whose source or target issue is not present in the workspace (counted as
+ * `unresolved`), self-references, and duplicates. Pure.
+ */
+export function planDependencyLinks(repo, issues, provenance) {
+    const repoLc = repo.toLowerCase();
+    const edges = [];
+    const seen = new Set();
+    let unresolved = 0;
+    for (const issue of issues) {
+        const sourceKey = `${repoLc}#${issue.number}`;
+        const sourceId = provenance.get(sourceKey);
+        // Source not in the workspace (e.g. its own import was skipped): its edges
+        // have nowhere to attach; leave them for a later re-run rather than count
+        // them as unresolved targets.
+        if (!sourceId)
+            continue;
+        for (const ref of parseDependencyReferences(issue.body ?? "", repoLc)) {
+            const targetKey = `${ref.repo}#${ref.number}`;
+            if (targetKey === sourceKey)
+                continue; // self-reference by provenance
+            const targetId = provenance.get(targetKey);
+            if (!targetId) {
+                unresolved++;
+                continue;
+            }
+            if (targetId === sourceId)
+                continue; // self-reference by resolved id
+            const dedupeKey = `${sourceId}|${targetId}|${ref.kind}`;
+            if (seen.has(dedupeKey))
+                continue;
+            seen.add(dedupeKey);
+            edges.push({ sourceId, targetId, kind: ref.kind, sourceIssue: issue.number, phrase: ref.phrase });
+        }
+    }
+    return { edges, unresolved };
+}
+/** Count candidate references across issues without resolving them (dry-run preview). */
+export function countDependencyRefCandidates(repo, issues) {
+    const repoLc = repo.toLowerCase();
+    let n = 0;
+    for (const issue of issues)
+        n += parseDependencyReferences(issue.body ?? "", repoLc).length;
+    return n;
+}
+// Lazy-load the two SDK primitives --link-deps needs. Mirrors loadPmComments /
+// loadAtomicSdk: a missing export degrades to a clear upgrade error instead of
+// killing extension load on older hosts.
+async function loadDepLinkSdk() {
+    let mod;
+    try {
+        mod = (await import("@unbrained/pm-cli/sdk"));
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new CommandError(`--link-deps requires @unbrained/pm-cli>=2026.7.20, but the SDK could not be imported: ${msg}.`, EXIT_CODE.USAGE);
+    }
+    const listFn = mod.listAllItemMetadata;
+    const collectFn = mod.collectNewOrderingCycleWarnings;
+    if (typeof listFn !== "function" || typeof collectFn !== "function") {
+        throw new CommandError("--link-deps requires @unbrained/pm-cli>=2026.7.20 with the SDK exports " +
+            "listAllItemMetadata + collectNewOrderingCycleWarnings. Upgrade @unbrained/pm-cli.", EXIT_CODE.USAGE);
+    }
+    return {
+        listAllItemMetadata: async (pmRoot) => {
+            const raw = (await listFn(pmRoot));
+            return raw.map((i) => ({
+                id: String(i.id),
+                tags: Array.isArray(i.tags) ? i.tags : [],
+                dependencies: Array.isArray(i.dependencies)
+                    ? i.dependencies
+                    : undefined,
+            }));
+        },
+        // The SDK's cycle detector reads only id/tags/dependencies off each item;
+        // DepLinkSnapshotItem is that structural subset, so the cast is sound.
+        collectNewOrderingCycleWarnings: collectFn,
+    };
+}
+function defaultApplyDependencyLink(edge, pmRoot) {
+    const res = pmRun([
+        "--path", pmRoot, "update", edge.sourceId,
+        "--dep", `id=${edge.targetId},kind=${edge.kind}`,
+        "--message", `Linked from GitHub #${edge.sourceIssue} body ("${edge.phrase}" reference)`,
+    ]);
+    return { ok: res.ok, stderr: res.stderr };
+}
+/**
+ * The `--link-deps` second pass. Snapshots the workspace, resolves body
+ * references to edges, applies them idempotently, then re-snapshots and asks the
+ * SDK which ordering cycles the batch newly introduced. Never throws for an
+ * individual edge; a resolution/SDK failure surfaces through the returned
+ * `failures`/warnings so the import result stays truthful.
+ */
+export async function linkImportedDependencies(repo, issues, pmRoot, deps = {}) {
+    const applyEdge = deps.applyDependencyLink ?? defaultApplyDependencyLink;
+    const failures = [];
+    // Resolve the SDK-backed helpers and take the pre-edge snapshot. This runs
+    // AFTER the import has already committed, so a failure here (a host whose CLI
+    // predates the required SDK exports, or an unreadable workspace) must never
+    // reject and discard the successful import result — degrade to a reported
+    // failure and skip linking, honoring the "a failure never fails the import"
+    // contract for infra errors, not just per-edge errors.
+    let listMeta;
+    let collect;
+    let before;
+    try {
+        const needsSdk = !deps.listItemMetadata || !deps.collectOrderingCycleWarnings;
+        const sdk = needsSdk ? await loadDepLinkSdk() : undefined;
+        listMeta = deps.listItemMetadata ?? ((r) => sdk.listAllItemMetadata(r));
+        collect = deps.collectOrderingCycleWarnings ?? sdk.collectNewOrderingCycleWarnings;
+        before = await listMeta(pmRoot);
+    }
+    catch (err) {
+        return {
+            linked: 0,
+            unresolved: 0,
+            orderingCycleWarnings: [],
+            failures: [`dependency linking skipped: ${err instanceof Error ? err.message : String(err)}`],
+        };
+    }
+    const provenance = buildProvenanceIndexFromMetadata(before);
+    const { edges, unresolved } = planDependencyLinks(repo, issues, provenance);
+    if (edges.length === 0) {
+        return { linked: 0, unresolved, orderingCycleWarnings: [], failures };
+    }
+    const changedSources = new Set();
+    let linked = 0;
+    for (const edge of edges) {
+        const res = applyEdge(edge, pmRoot);
+        if (res.ok) {
+            linked++;
+            changedSources.add(edge.sourceId);
+        }
+        else {
+            failures.push(`#${edge.sourceIssue} ${edge.sourceId} —(${edge.kind})→ ${edge.targetId}: ${res.stderr.trim()}`);
+        }
+    }
+    // The ordering-cycle advisory is likewise best-effort: a re-snapshot or
+    // detector failure must not discard the edges already written, so it degrades
+    // to a reported note rather than throwing.
+    const warnings = new Set();
+    if (changedSources.size > 0) {
+        try {
+            const after = await listMeta(pmRoot);
+            for (const id of changedSources) {
+                for (const w of collect(before, after, id))
+                    warnings.add(w);
+            }
+        }
+        catch (err) {
+            failures.push(`ordering-cycle advisory skipped: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return { linked, unresolved, orderingCycleWarnings: [...warnings], failures };
+}
 async function prepareGithubImport(issue, repo, opts, token, match, fetchIssueComments = fetchComments) {
     const title = issue.title.trim();
     if (!title)
@@ -1347,11 +1624,12 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         return { imported: 0, updated: 0, skipped: 0 };
     }
     console.error(`Found ${filtered.length} issue(s).`);
-    // Build the idempotency index once up-front.
-    const shouldMatchExisting = !opts.dryRun || opts.atomic;
-    const existing = shouldMatchExisting
-        ? indexByProvenance((dependencies.readItems ?? readPmItems)(pmRoot))
-        : new Map();
+    // Build the idempotency index once up-front — including for a dry run. Skipping
+    // it on a non-atomic dry run made every issue look like a create, so the preview
+    // reported "would import N, skip 0" where the real run performs updates for
+    // already-linked issues. A preview that overstates creates reads as "this will
+    // duplicate my whole tracker" and is the one thing --dry-run exists to rule out.
+    const existing = indexByProvenance((dependencies.readItems ?? readPmItems)(pmRoot));
     let imported = 0;
     let updated = 0;
     let skipped = 0;
@@ -1386,12 +1664,17 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
                 console.error(`  [dry-run][atomic] #${entry.issueNumber} ${action} ${entry.title} (${entry.status})`);
             }
             console.error(`[dry-run] Atomic plan would import ${imported}, update ${updated}, skip ${skipped}.`);
+            if (opts.linkDeps) {
+                console.error(`[dry-run] --link-deps: ${countDependencyRefCandidates(repo, filtered)} candidate reference(s) parsed; ` +
+                    `resolution + edge writes run only on a real import.`);
+            }
             return {
                 dryRun: true,
                 wouldImport: imported,
                 wouldUpdate: updated,
                 wouldSkip: skipped,
                 atomic: true,
+                ...(opts.linkDeps ? { wouldLinkDependencyCandidates: countDependencyRefCandidates(repo, filtered) } : {}),
             };
         }
         const result = await (dependencies.commitAtomic ?? importGithubAtomic)(pmRoot, repo, prepared);
@@ -1409,6 +1692,10 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         else {
             console.error(`Atomically imported ${result.imported} new, updated ${result.updated} existing, skipped ${skipped}.`);
         }
+        const atomicDepLink = opts.linkDeps
+            ? await linkImportedDependencies(repo, filtered, pmRoot, dependencies)
+            : undefined;
+        reportDepLink(atomicDepLink);
         // itemIds is an internal post-commit routing map for native comments. Maps
         // serialize as `{}` in JSON, so keep it out of the public command result.
         return {
@@ -1419,6 +1706,7 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
             ...(result.recoveredItems !== undefined ? { recoveredItems: result.recoveredItems } : {}),
             skipped,
             atomic: true,
+            ...depLinkResultFields(atomicDepLink),
         };
     }
     for (const issue of filtered) {
@@ -1430,8 +1718,12 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         const labels = issue.labels.map((l) => l.name).filter(Boolean);
         const { title, status, assignee, milestone, match, description, body, tags, comments, syncAnnotations, } = prepared;
         if (opts.dryRun) {
-            console.error(`  [dry-run] #${issue.number} ${title} (${status}, ${labels.join(",")})`);
-            imported++;
+            const action = match?.id ? "update" : "import";
+            console.error(`  [dry-run] #${issue.number} ${action} ${title} (${status}, ${labels.join(",")})`);
+            if (match?.id)
+                updated++;
+            else
+                imported++;
             continue;
         }
         if (match?.id) {
@@ -1514,19 +1806,55 @@ export async function runImport(repoArg, pmRoot, opts, dependencies = {}) {
         imported++;
     }
     if (opts.dryRun) {
-        console.error(`[dry-run] Would import ${imported}, skip ${skipped}.`);
+        console.error(`[dry-run] Would import ${imported}, update ${updated}, skip ${skipped}.`);
+        if (opts.linkDeps) {
+            console.error(`[dry-run] --link-deps: ${countDependencyRefCandidates(repo, filtered)} candidate reference(s) parsed; ` +
+                `resolution + edge writes run only on a real import.`);
+        }
         return {
             dryRun: true,
             wouldImport: imported,
+            wouldUpdate: updated,
             wouldSkip: skipped,
             ...(opts.atomic ? { atomic: true } : {}),
+            ...(opts.linkDeps ? { wouldLinkDependencyCandidates: countDependencyRefCandidates(repo, filtered) } : {}),
         };
     }
     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 };
+    const depLink = opts.linkDeps
+        ? await linkImportedDependencies(repo, filtered, pmRoot, dependencies)
+        : undefined;
+    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).
+function reportDepLink(result) {
+    if (!result)
+        return;
+    const parts = [`linked ${result.linked} dependency edge(s)`];
+    if (result.unresolved > 0)
+        parts.push(`${result.unresolved} unresolved ref(s)`);
+    console.error(`--link-deps: ${parts.join(", ")}.`);
+    for (const warning of result.orderingCycleWarnings)
+        console.error(`  ⚠ ${warning}`);
+    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.
+function depLinkResultFields(result) {
+    if (!result)
+        return {};
+    return {
+        linkedDependencies: result.linked,
+        unresolvedDependencyRefs: result.unresolved,
+        orderingCycleWarnings: result.orderingCycleWarnings,
+        ...(result.failures.length > 0 ? { dependencyLinkFailures: result.failures } : {}),
+    };
 }
 // ---------------------------------------------------------------------------
 // Sync core — push pm status changes back to GitHub (close / reopen)
@@ -2675,6 +3003,7 @@ const IMPORT_FLAGS = [
     { long: "--include-comments", description: "Alias for --with-comments" },
     { long: "--comments-mode", value_name: "body|annotations|both", description: "How to persist fetched GitHub comments: `body` (default, embed in item body), `annotations` (sync to the pm item's native comments collection), or `both`. `annotations`/`both` are idempotent on re-import (dedupe by GitHub comment id)" },
     { long: "--atomic", description: "Commit the complete import as one workspace-writer-locked, crash-resumable transaction (pm-cli >=2026.7.20); compensate applied mutations on failure and report incomplete compensation" },
+    { long: "--link-deps", description: "After import, map dependency references in issue bodies (`Blocked by #N`, `Depends on owner/repo#N`, `Blocks #N`) to pm dependency edges between the linked items. Idempotent; skips self- and unresolved references; ordering cycles are reported (via the SDK ordering-cycle advisory), not rejected" },
     { long: "--dry-run", description: "Preview without writing" },
     { long: "--type", value_name: "type", description: "Override pm item type (default: Issue)" },
 ];
@@ -2721,7 +3050,7 @@ const PROJECT_SYNC_FLAGS = [
 ];
 export default defineExtension({
     name: "pm-github",
-    version: "2026.7.22",
+    version: "2026.7.25",
     activate(api) {
         // -----------------------------------------------------------------------
         // schema — declare the GitHub provenance fields so the workspace knows them
@@ -2770,6 +3099,7 @@ export default defineExtension({
                 "pm github import owner/repo --include-comments",
                 "pm github import owner/repo --comments-mode annotations",
                 "pm github import owner/repo --atomic",
+                "pm github import owner/repo --link-deps",
                 "pm github import owner/repo --dry-run",
             ],
             flags: IMPORT_FLAGS,
@@ -2865,7 +3195,7 @@ export default defineExtension({
             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" });
+            const res = spawnSync("pm", ["--path", ctx.pm_root, "--json", "show", id], { encoding: "utf-8", maxBuffer: pmJsonMaxBuffer() });
             if (res.status !== 0)
                 return;
             let repo;
@@ -2936,6 +3266,7 @@ export default defineExtension({
                 "pm github import owner/repo --with-comments",
                 "pm github import owner/repo --comments-mode annotations",
                 "pm github import owner/repo --atomic",
+                "pm github import owner/repo --link-deps",
                 "pm github import owner/repo --dry-run",
             ],
             flags: IMPORT_FLAGS,