pm-github 2026.10.25 → 2026.10.26

package/dist/index.js

@@ -1,19 +1,7 @@
-// pm-github — GitHub Issues + Projects v2 sync for pm-cli
-//
-// Capabilities (see manifest.json):
-//   commands   — `pm gh-issues import` (legacy) + `pm github sync` +
-//                `pm github gate` (fail-closed pre-push privacy gate) +
-//                `pm github project list|fields|import|sync` (Projects v2)
-//   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 /
-//                github_author / github_created_at / github_updated_at item fields
-//   hooks      — afterCommand: actionable sync hint for github-linked items
-//   preflight  — local guard for mutating github commands (token presence)
-//
-// Issues use the REST API; Projects v2 is GraphQL-only (see the Projects v2
-// section below and the pure plan/mapping logic in ./projects.ts).
+import { ownValue } from "./own-record.js";
 import { CloseoutUsageError, compactCloseoutReport, runCloseout } from "./closeout.js";
+import { compileIssueForm, completeIssueForm, readRepositoryIssueForm, refuseIssueForm } from "./issue-forms.js";
+export { compileIssueForm, completeIssueForm, readRepositoryIssueForm } from "./issue-forms.js";
 import { AmbiguousCitationError, buildImportFidelity, fetchImportTimeline, importFidelityFields, matchImportedIssue, persistImportFidelity, readImportReleases, selectImportContextIndex, validateImportLifetime, } from "./import-fidelity.js";
 import { refreshChanges, runRefresh } from "./refresh.js";
 import { exploreGithubIdentities, planGithubIdentityRepair, applyGithubIdentityRepair } from "./identity.js";
@@ -216,7 +204,7 @@ function requestOnce(method, url, token, payload, redirectsLeft = 5) {
  */
 export function computeBackoffMs(headers, attempt, nowMs = Date.now()) {
     const get = (k) => {
-        const v = headers[k] ?? headers[k.toLowerCase()];
+        const v = ownValue(headers, k) ?? ownValue(headers, k.toLowerCase());
         return Array.isArray(v) ? v[0] : v;
     };
     const cap = 60_000;
@@ -245,11 +233,11 @@ export function parseRateLimit(headers, lowThreshold = 10) {
     // Node lowercases response header names, but be defensive: scan
     // case-insensitively so a mixed-case key (e.g. from a different runtime or a
     // mocked response) is still found.
-    const lower = {};
+    const lower = new Map();
     for (const [hk, hv] of Object.entries(headers))
-        lower[hk.toLowerCase()] = hv;
+        lower.set(hk.toLowerCase(), hv);
     const get = (k) => {
-        const v = lower[k.toLowerCase()];
+        const v = lower.get(k.toLowerCase());
         return Array.isArray(v) ? v[0] : v;
     };
     const num = (s) => {
@@ -310,11 +298,11 @@ export function isRetryableStatus(status, headers) {
         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 v = ownValue(headers, "x-ratelimit-remaining") ?? ownValue(headers, "X-RateLimit-Remaining");
         const remaining = Array.isArray(v) ? v[0] : v;
         if (remaining === "0")
             return true;
-        if (headers["retry-after"] ?? headers["Retry-After"])
+        if (ownValue(headers, "retry-after") ?? ownValue(headers, "Retry-After"))
             return true;
     }
     return false;
@@ -373,7 +361,7 @@ export function mapState(state, stateReason) {
 // key depending on runtime normalization, so check every candidate.
 export function optionEnabled(options, ...keys) {
     return keys.some((k) => {
-        const v = options[k];
+        const v = ownValue(options, k);
         return v === true || v === "true" || v === "1";
     });
 }
@@ -381,7 +369,7 @@ export function optionEnabled(options, ...keys) {
 // (kebab- or camel-case) keys; returns undefined when none are set.
 export function optionString(options, ...keys) {
     for (const k of keys) {
-        const v = options[k];
+        const v = ownValue(options, k);
         if (typeof v === "string" && v.trim().length > 0)
             return v.trim();
     }
@@ -453,7 +441,7 @@ export function applyLabelMap(labels, labelMap) {
 export function optionCsv(options, ...keys) {
     const rawChunks = [];
     for (const k of keys) {
-        const v = options[k];
+        const v = ownValue(options, k);
         if (typeof v === "string") {
             rawChunks.push(v);
             continue;
@@ -679,7 +667,7 @@ export function decodeCompletePmItems(parsed) {
         || !readOutput.requested_dimensions.includes("cost")) {
         throw new CommandError("Refusing unverifiable pm list --all output: read_output.requested_dimensions must include include, amount, and cost.");
     }
-    if ("output_budget_truncation" in parsed || "output_budget_exceeded" in parsed) {
+    if (Object.hasOwn(parsed, "output_budget_truncation") || Object.hasOwn(parsed, "output_budget_exceeded")) {
         throw new CommandError("Refusing unverifiable pm list --all output: a budget truncation or omission disclosure was present.");
     }
     if (!Number.isSafeInteger(parsed.count) || parsed.count < 0) {
@@ -832,7 +820,7 @@ export function searchDocumentToItem(document) {
     const wrapped = document.metadata;
     if (wrapped && typeof wrapped === "object")
         return wrapped;
-    return "id" in document ? document : undefined;
+    return Object.hasOwn(document, "id") ? document : undefined;
 }
 /**
  * Resolve the corpus the search provider matches remote hits against.
@@ -3453,14 +3441,12 @@ 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.
- */
+/** Resolve explicit CLI selection and files through the package's read-only REST client. */
+async function selectedIssueForm(ctx) {
+    const token = resolveGitHubToken();
+    return readRepositoryIssueForm({ repo: optionString(ctx.options, "repo") ?? "", ref: optionString(ctx.options, "form-ref", "formRef") ?? "", path: optionString(ctx.options, "form") ?? "" }, url => fetchJSON(url, token), githubApiBase(), { answers: optionString(ctx.options, "form-answers", "formAnswers"), bindings: optionString(ctx.options, "form-bindings", "formBindings") });
+}
+/** Re-read all selected form answers before constructing or applying the export. */
 async function runExport(ctx) {
     const options = ctx.options;
     const jsonMode = ctx.global.json === true;
@@ -3473,8 +3459,28 @@ async function runExport(ctx) {
     if (idsProvided && scopedIds.length === 0) {
         throw new CommandError("--ids requires at least one pm item id (comma-separated), e.g. --ids pm-123,pm-456.", EXIT_CODE.USAGE);
     }
-    const selected = requireRequestedItems(readPmItems(ctx.pm_root), scopedIds);
+    const items = optionProvided(options, "form")
+        ? decodeCompletePmItems(certifyCompleteListResult(await listAllComplete({ includeBody: true }, { pmRoot: ctx.pm_root })))
+        : readPmItems(ctx.pm_root);
+    const selected = requireRequestedItems(items, scopedIds);
+    const completions = [];
+    if (optionProvided(options, "form")) {
+        const source = await selectedIssueForm(ctx);
+        compileIssueForm(source);
+        for (const item of selected)
+            completions.push(await completeIssueForm(ctx.pm_root, { ...source, item: item.id }));
+        const repairs = completions.flatMap(completion => completion.report.checklist.map(repair => ({ ...repair, field: `${completion.report.item}:${repair.field}` })));
+        if (repairs.length)
+            refuseIssueForm("incomplete_answers", repairs, completions.reduce((sum, completion) => sum + completion.report.omitted, 0));
+    }
+    else if (["form-ref", "formRef", "form-answers", "formAnswers", "form-bindings", "formBindings"].some(flag => optionProvided(options, flag))) {
+        refuseIssueForm("invalid_form_input", [{ field: "form", reason: "selection", remedy: "Pass --form with --repo and --form-ref to enforce an issue-form contract." }]);
+    }
     const plan = buildExportPlan(selected, repo, labelMap);
+    for (const [index, completion] of completions.entries()) {
+        plan[index].payload.body = completion.body;
+        plan[index].payload.labels = [...new Set([...plan[index].payload.labels, ...completion.report.contract.labels])];
+    }
     const creates = plan.filter((e) => e.action === "create").length;
     const updates = plan.filter((e) => e.action === "update").length;
     if (!apply) {
@@ -3980,12 +3986,12 @@ export async function fetchBlockerReferenceStates(refs, transport) {
                 states.set(entry.ref.key, { ...entry.ref, state: "error", error: "GitHub rejected blocker state access." });
                 continue;
             }
-            const repoBlock = response.data?.[entry.repoAlias];
-            if (repoBlock === undefined || (repoBlock !== null && (repoBlock[entry.issueAlias] === undefined || repoBlock[entry.pullAlias] === undefined))) {
+            const repoBlock = ownValue(response.data, entry.repoAlias);
+            if (repoBlock === undefined || (repoBlock !== null && (ownValue(repoBlock, entry.issueAlias) === undefined || ownValue(repoBlock, entry.pullAlias) === undefined))) {
                 states.set(entry.ref.key, { ...entry.ref, state: "error", error: "Incomplete GitHub blocker state response." });
                 continue;
             }
-            states.set(entry.ref.key, mapBlockerReferenceNode(entry.ref, repoBlock?.[entry.issueAlias], repoBlock?.[entry.pullAlias]));
+            states.set(entry.ref.key, mapBlockerReferenceNode(entry.ref, ownValue(repoBlock, entry.issueAlias), ownValue(repoBlock, entry.pullAlias)));
         }
     }
     return states;
@@ -5246,6 +5252,10 @@ const IMPORT_FLAGS = [
     { long: "--type", value_name: "type", description: "Override pm item type (default: Issue)" },
 ];
 const EXPORT_FLAGS = [
+    { long: "--form", value_name: "path", description: "Enforce a selected repository issue form before any export writes" },
+    { long: "--form-ref", value_name: "revision", description: "Explicit repository revision containing the selected form" },
+    { long: "--form-answers", value_name: "json", description: "JSON map of form answer IDs to strings or string arrays" },
+    { long: "--form-bindings", value_name: "json", description: "JSON map of form answer IDs to native pm field names" },
     { long: "--repo", value_name: "owner/repo", description: "Target GitHub repo (required for --apply; enables upsert of linked issues)" },
     { long: "--ids", value_name: "pm-1,pm-2", description: "Only export these pm item IDs (comma-separated)" },
     { long: "--apply", description: "Write to GitHub (default is a safe dry-run preview)" },
@@ -5307,7 +5317,7 @@ const PROJECT_SYNC_FLAGS = [
 const defineExtension = (module) => module;
 export default defineExtension({
     name: "pm-github",
-    version: "2026.10.25",
+    version: "2026.10.26",
     activate(api) {
         // -----------------------------------------------------------------------
         // schema — declare the GitHub provenance fields so the workspace knows them
@@ -5416,6 +5426,23 @@ export default defineExtension({
                 "Use --ids <pm-1,pm-2> to scope export; unknown IDs fail fast.",
             ],
         });
+        api.registerCommand({
+            name: "github form",
+            description: "Compile and check an explicitly selected repository issue form against current SDK item state. Read-only; returns a compact contract and bounded repair checklist.",
+            flags: [...EXPORT_FLAGS.filter(flag => ["--repo", "--form", "--form-ref", "--form-answers", "--form-bindings"].includes(flag.long)),
+                { long: "--compile", description: "Only compile requirements, validators and bindings; do not check completion" },
+                { long: "--item", value_name: "id", description: "Read current native pm fields through the SDK for explicit bindings" }],
+            examples: ["pm github form --repo owner/repo --form .github/ISSUE_TEMPLATE/bug.yml --form-ref main --item pm-1 --form-bindings bindings.json --json"],
+            async run(ctx) {
+                const source = await selectedIssueForm(ctx);
+                if (ctx.options.compile === true)
+                    return compileIssueForm(source);
+                const completion = await completeIssueForm(ctx.pm_root, { ...source, item: optionString(ctx.options, "item") });
+                if (!completion.report.ok)
+                    refuseIssueForm("incomplete_answers", completion.report.checklist, completion.report.omitted);
+                return completion.report;
+            },
+        });
         // -----------------------------------------------------------------------
         // search — reach GitHub from `pm search` for imported items.
         // Guarded by a capability check so it is a no-op on runtimes that predate