pm-github 2026.10.27 → 2026.10.29

package/dist/workflow-diagnostic.js

@@ -0,0 +1,62 @@
+/** Produce one workflow refusal while keeping raw command output private. */
+import { readFileSync } from "node:fs";
+import { ownValue } from "./own-record.js";
+/** Decode a CLI report or the JSON diagnostic following stderr progress messages. */
+export function decodeWorkflowDiagnostic(text, depth = 0) {
+    try {
+        const value = JSON.parse(text.slice(Math.max(0, text.indexOf("{"))));
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            return {};
+        const report = value;
+        if (typeof report.detail === "string" && depth < 2) {
+            const nested = decodeWorkflowDiagnostic(report.detail, depth + 1);
+            return Object.keys(nested).length ? nested : { reason: report.detail };
+        }
+        return report;
+    }
+    catch {
+        return {};
+    }
+}
+/** Read an optional receipt; missing or malformed files never expose their paths. */
+function receipt(file) {
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+/** Pick one actionable failure; the workflow privacy-scans the resulting text before logging it. */
+export function workflowFailure(report, diff = "") {
+    if (diff) {
+        const item = /\/(?:[^/\s]+\/)*([a-zA-Z0-9_-]+)\.toon\b/.exec(diff)?.[1];
+        const field = /^[+-]([a-z][a-z0-9_]*):/m.exec(diff)?.[1];
+        return `Repeat import changed ${item ?? "tracker state"}${field ? ` field ${field}` : ""}; retry with the current pm-github release and inspect concurrent source changes. No branch was published.`;
+    }
+    if (Array.isArray(report.findings) && report.findings.length) {
+        const finding = decodeWorkflowDiagnostic(JSON.stringify(report.findings[0]));
+        return `Import privacy gate refused item ${finding.item_id}, field ${finding.field}, rule ${finding.rule}; remove the source content or review an explicit gate allowlist entry. No branch was published.`;
+    }
+    if (Array.isArray(report.plan)) {
+        for (const value of report.plan) {
+            const row = decodeWorkflowDiagnostic(JSON.stringify(value));
+            const missing = Array.isArray(row.missing_evidence) ? row.missing_evidence.map(entry => decodeWorkflowDiagnostic(JSON.stringify(entry))) : [];
+            const failed = missing.find(entry => entry.code === "close_failed");
+            if (failed || row.action === "skip" && ["head_evidence_unavailable", "required_checks_unverified", "incomplete_merge"].includes(String(row.code))) {
+                return `Closeout refused item ${row.item}, PR #${row.pr}: ${failed ? failed.reason : row.reason} No branch was published.`;
+            }
+        }
+    }
+    const reason = ownValue(report, "reason");
+    return typeof reason === "string" ? `${reason} No branch was published.`
+        : "Command produced no usable failure receipt; rerun the failed command with --json using the same tracker and token permissions. No branch was published.";
+}
+/** Assemble a private candidate diagnostic from stdout, stderr and an optional repeat-import diff. */
+export function readWorkflowFailure(reportFile, errorFile, diffFile) {
+    const output = decodeWorkflowDiagnostic(receipt(reportFile));
+    const error = decodeWorkflowDiagnostic(receipt(errorFile));
+    const fullFailure = output.command === "github closeout" && typeof output.failed === "number" && output.failed > 0;
+    return { reason: workflowFailure(fullFailure ? output : Object.keys(error).length ? error : output, receipt(diffFile)) };
+}
+//# sourceMappingURL=workflow-diagnostic.js.map

package/dist/workflow-diagnostic.js.map

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

package/dist/workspace.d.ts

@@ -0,0 +1,18 @@
+/** Resolve tracker identity and schema through the same public SDK boundary as host commands. */
+import { type RuntimeStatusRegistry } from "@unbrained/pm-cli/sdk";
+/** Accept a workspace, tracker directory or relative CLI path before reading its schema. */
+export declare function readGithubWorkspace(pmPath: string): Promise<{
+    pmRoot: string;
+    settings: import("@unbrained/pm-cli/sdk").PmSettings;
+    types: import("@unbrained/pm-cli/sdk").ItemTypeRegistry;
+    statuses: RuntimeStatusRegistry;
+}>;
+/** Canonicalize configured aliases using the host's own status input normalizer. */
+export declare function canonicalGithubStatus(value: string | undefined, registry?: RuntimeStatusRegistry): string;
+/** Classify native statuses by configured lifecycle roles for provider transitions. */
+export declare function githubStatusKind(value: string | undefined, registry?: RuntimeStatusRegistry): string;
+/** Include every configured terminal role when mapping native state to a provider. */
+export declare function githubStatusIsTerminal(value: string | undefined, registry?: RuntimeStatusRegistry): boolean;
+/** Public status registry accepted by pure planners and comparison helpers. */
+export type GithubStatusRegistry = RuntimeStatusRegistry;
+//# sourceMappingURL=workspace.d.ts.map

package/dist/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../workspace.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,OAAO,EAAkL,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAKnP,4FAA4F;AAC5F,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM;;;;;GAKvD;AAED,oFAAoF;AACpF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,wBAAkB,GAAG,MAAM,CAEnG;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,wBAAkB,GAAG,MAAM,CAU9F;AAED,sFAAsF;AACtF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,wBAAkB,GAAG,OAAO,CAErG;AAED,+EAA+E;AAC/E,MAAM,MAAM,oBAAoB,GAAG,qBAAqB,CAAC"}

package/dist/workspace.js

@@ -0,0 +1,39 @@
+/** Resolve tracker identity and schema through the same public SDK boundary as host commands. */
+import { getActiveExtensionRegistrations, isTerminalStatus, normalizeStatusInput, readSettings, resolveItemTypeRegistry, resolvePmRoot, resolveRuntimeStatusRegistry, SETTINGS_DEFAULTS } from "@unbrained/pm-cli/sdk";
+/** Built-in contracts preserve pure planner compatibility when no workspace is supplied. */
+const defaultStatuses = resolveRuntimeStatusRegistry(SETTINGS_DEFAULTS.schema);
+/** Accept a workspace, tracker directory or relative CLI path before reading its schema. */
+export async function readGithubWorkspace(pmPath) {
+    const pmRoot = resolvePmRoot(process.cwd(), pmPath);
+    const settings = await readSettings(pmRoot);
+    return { pmRoot, settings, types: resolveItemTypeRegistry(settings, getActiveExtensionRegistrations()),
+        statuses: resolveRuntimeStatusRegistry(settings.schema) };
+}
+/** Canonicalize configured aliases using the host's own status input normalizer. */
+export function canonicalGithubStatus(value, registry = defaultStatuses) {
+    return normalizeStatusInput(value, registry) ?? value ?? registry.open_status;
+}
+/** Classify native statuses by configured lifecycle roles for provider transitions. */
+export function githubStatusKind(value, registry = defaultStatuses) {
+    const status = canonicalGithubStatus(value, registry);
+    if (registry.terminal_done_statuses.has(status))
+        return "closed";
+    if (registry.terminal_canceled_statuses.has(status))
+        return "canceled";
+    if (isTerminalStatus(status, registry))
+        return "closed";
+    if (registry.blocked_statuses.has(status))
+        return "blocked";
+    if (registry.draft_statuses.has(status))
+        return "draft";
+    if (status === registry.in_progress_status)
+        return "in_progress";
+    if (status === registry.open_status)
+        return "open";
+    return status;
+}
+/** Include every configured terminal role when mapping native state to a provider. */
+export function githubStatusIsTerminal(value, registry = defaultStatuses) {
+    return isTerminalStatus(value ?? registry.open_status, registry);
+}
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../workspace.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,OAAO,EAAE,+BAA+B,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,YAAY,EAAE,uBAAuB,EAAE,aAAa,EAAE,4BAA4B,EAAE,iBAAiB,EAA8B,MAAM,uBAAuB,CAAC;AAEnP,4FAA4F;AAC5F,MAAM,eAAe,GAAG,4BAA4B,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC;AAE/E,4FAA4F;AAC5F,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,MAAc;IACtD,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,MAAM,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,MAAM,CAAC,CAAC;IAC5C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,uBAAuB,CAAC,QAAQ,EAAE,+BAA+B,EAAE,CAAC;QACpG,QAAQ,EAAE,4BAA4B,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,qBAAqB,CAAC,KAAyB,EAAE,QAAQ,GAAG,eAAe;IACzF,OAAO,oBAAoB,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,KAAK,IAAI,QAAQ,CAAC,WAAW,CAAC;AAChF,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,gBAAgB,CAAC,KAAyB,EAAE,QAAQ,GAAG,eAAe;IACpF,MAAM,MAAM,GAAG,qBAAqB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IACtD,IAAI,QAAQ,CAAC,sBAAsB,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,QAAQ,CAAC;IACjE,IAAI,QAAQ,CAAC,0BAA0B,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,UAAU,CAAC;IACvE,IAAI,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC;QAAE,OAAO,QAAQ,CAAC;IACxD,IAAI,QAAQ,CAAC,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAC5D,IAAI,QAAQ,CAAC,cAAc,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,OAAO,OAAO,CAAC;IACxD,IAAI,MAAM,KAAK,QAAQ,CAAC,kBAAkB;QAAE,OAAO,aAAa,CAAC;IACjE,IAAI,MAAM,KAAK,QAAQ,CAAC,WAAW;QAAE,OAAO,MAAM,CAAC;IACnD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,sBAAsB,CAAC,KAAyB,EAAE,QAAQ,GAAG,eAAe;IAC1F,OAAO,gBAAgB,CAAC,KAAK,IAAI,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,CAAC;AACnE,CAAC"}

package/docs/discussion-capture-example.json

@@ -0,0 +1,14 @@
+{
+  "repo": "example/project",
+  "issue": 42,
+  "item": "project-context",
+  "selections": [
+    {
+      "comment": 123456,
+      "start": 0,
+      "end": 19,
+      "quote": "Use the native SDK.",
+      "marked": true
+    }
+  ]
+}

package/docs/discussion-capture.md

@@ -0,0 +1,44 @@
+## Selected GitHub discussion decisions
+
+Copy `docs/discussion-capture-example.json`, select an existing native context item and edit the repository, issue, comment ID and exact span. `marked: true` records an explicit selection by the caller. The adapter never infers decisions from prose, labels, imperative language or an entire unselected thread. Empty selections create nothing. Issue body extraction and PR review findings are outside this feature.
+
+```sh
+pm github discussion capture --input selection.json --json
+pm github discussion capture --input selection.json --approve REVIEWED_DIGEST --json
+```
+
+Review the complete first receipt before supplying its `approval`. Each row exposes the proposed native Decision ID, source author ID/login, canonical comment URL, timestamp, SHA-256 revision and exact quoted span. Routine output contains only selected passages. Default pm rendering is compact TOON; `--json` uses the same typed receipt. `created`, `unchanged`, `skipped` and `refused` count row states. A successful envelope can contain independent refused rows: inspect these counters and remedies. A refusal never permits a dependent write.
+
+Offsets are zero-based, half-open UTF-16 code units, matching JavaScript `body.slice(start, end)`. CRLF, Unicode and whitespace are preserved exactly in the JSON evidence body; the SDK still owns native field normalization. Issue, comment and author IDs are positive safe integers; counters are nonnegative integers bounded by the ten-selection limit. Native item selectors and emitted identifiers are 1..512 code units without NUL, CRLF or path separators; the SDK resolves whitespace aliases and canonical item identifiers. Configured status IDs are 1..512 code units without NUL or CRLF and retain the SDK's own status semantics, including Unicode and slash-bearing names. Author logins accept bounded human and bot identities. Offsets are at most 65536, quotes are 1..4096 code units and at most ten dense selections are accepted. Comments are bounded to 65536 code units. No sparse arrays, unknown request keys, nonfinite numbers or implicit coercion are accepted. Output defaults to 65536 JSON bytes; `--max-output-bytes` accepts an integer 1024..131072. Planning reserves space for retry/refusal rows before any create. Split larger captures. Repeated spans in one request are skipped explicitly.
+
+Source revisions hash the ordered tuple of comment ID, exact full body, API issue URL, comment URL, update timestamp, author ID and login. An edit anywhere in that selected comment invalidates the prior approval, even when the selected quote is unchanged. Each source must belong to the selected issue; the HTTP reader verifies the issue is not a pull request. A supplied SDK reader must provide current issue-comment snapshots under that same contract. GitHub access is read-only: only GET requests are issued.
+
+Each capture creates one native `Decision`, parented explicitly to the selected context item, with empty dependencies and no sprint, release, goal or objective. Native linked docs point to the comment and source revision. Evidence is serialized JSON data, never executable instructions, a prompt, markdown expansion or a shell command. The provider author remains separate from the host's audit author. pm-evidence can cite this native Decision body for its own resolution/review workflows; this adapter does not maintain another citation store.
+
+The SDK surface is `captureGithubDiscussion(pmRoot, input, hostSdk, options)`, exported with `DiscussionCaptureInput`, `DiscussionCaptureReport`, `DiscussionDecisionEvidence`, `DiscussionCaptureOptions`, `DiscussionCommentReader` and `DiscussionRefusalCode`. Pass the host-injected `ExtensionCommandSdk`; standalone callers may construct it through public `createExtensionCommandSdk` and `PmClient`. No executable/symlink traversal or eager SDK client acquisition occurs. Public SDK helpers resolve workspace schema and read native history. `validateDiscussionCaptureReport` validates JSON/TOON-decoded producer receipts through the same shared schema. No import/export/sync route bypasses the common capture path; the existing issue importer/exporter is unchanged.
+
+```ts
+import { captureGithubDiscussion, type DiscussionCaptureInput } from "pm-github";
+import { PmClient, createExtensionCommandSdk } from "@unbrained/pm-cli/sdk";
+
+const pmRoot = "tracker";
+const sdk = createExtensionCommandSdk(pmRoot, new PmClient({ pmRoot, author: "reviewer", noExtensions: true }));
+const selection: DiscussionCaptureInput = {
+  repo: "example/project", issue: 42, item: "project-context",
+  selections: [{ comment: 123456, start: 0, end: 19, quote: "Use the native SDK.", marked: true }],
+};
+const plan = await captureGithubDiscussion(pmRoot, selection, sdk);
+// Review plan.item, plan.status, plan.rows and plan.approval before a separate apply.
+```
+
+Semantic planning invokes the SDK's `previewItemMutations` in disposable staging with the same native create options as apply. Configured native create requirements produce an individual `native_refused` row. As documented by that SDK, staging does not validate executable extension hooks, pending migrations or final commit state; those can still yield a retryable `write_failed` row. Planning creates no source tracker journal or items.
+
+Approval binds tracker identity, parent history, schema, selected evidence and existing target revisions. Decision IDs bind canonical parent identity and the entire evidence revision; creation audit markers also bind the expected parent history revision. Retry reads current state and preserves existing or edited records. A normal native edit causes the existing Decision to be skipped with a reason, rather than overwritten or duplicated. A missing document with retained native history is a tombstone, not a fresh target: an old approval becomes stale and a new preview preserves that history without resurrecting the item. A source edit can be captured as a new Decision only after a fresh reviewed preview. Bad source records refuse individually and leave other independent selections reviewable. Completed creates survive later failures, and retry revalidates every remaining target; there is no frozen-plan replay, saved checkpoint, destructive compensation or second observation append.
+
+Immediately before each create the adapter re-reads source, parent history, schema and deterministic target. History length plus exact stream digest detects parent ABA. Peer-created captures are reported as unchanged only when current SDK state and the immutable creation marker agree; foreign or edited targets are skipped. The final read-to-create window remains optimistic: ordinary SDK/CLI writers can change source or parent after the final read. `commitWorkspaceTransaction` does not exclude those writers, so this adapter makes no cross-writer isolation claim. The native SDK's exclusive deterministic create prevents duplicate IDs; it cannot atomically guard a remote comment and a separate parent. All rows are independent, and no dependent evidence is appended after a skipped create.
+
+Typed fatal refusals carry `code` and a bounded `context.required` remedy: `invalid_selection` (fix the strict selection), `host_required` (use a supported injected host), `source_unavailable` (restore issue/comment read access), `source_changed` (reselect exact bytes), `target_unavailable` (restore native history), `stale_plan` (review a fresh preview), and `invalid_output` (fix the budget or split the request). Per-row `write_failed` remedies preserve prior successes and request a tracker health check. Foreign records are retained with `foreign_or_edited` rather than throwing.
+
+## Without git
+
+Discussion preview and capture work in plain directory trackers and invoke no git executable. A GitHub repository identity is a remote source locator; it does not require a local git repository. Existing GitHub operations that inspect a proposed git diff still require git, or their documented explicit diff input.

package/manifest.json

@@ -1,10 +1,10 @@
 {
   "name": "pm-github",
-  "version": "2026.10.27",
+  "version": "2026.10.29",
   "description": "GitHub Issues + Projects v2 integration. Imports issues as pm items (`pm github import`), exports pm items as GitHub issues, syncs issue state, and bidirectionally syncs pm items with a GitHub Projects v2 board (`pm github project import/sync/list/fields`) — mapping pm status to the board Status column with idempotent, no-data-loss provenance.",
   "author": "@unbraind",
   "entry": "./dist/index.js",
-  "pm_min_version": "2026.10.5",
+  "pm_min_version": "2026.10.17",
   "priority": 50,
   "capabilities": [
     "commands",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pm-github",
-  "version": "2026.10.27",
+  "version": "2026.10.29",
   "description": "GitHub Issues importer extension for pm-cli",
   "repository": {
     "type": "git",
@@ -17,12 +17,14 @@
     "dist/",
     "manifest.json",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "docs/discussion-capture.md",
+    "docs/discussion-capture-example.json"
   ],
   "scripts": {
     "build": "tsc",
     "build:test": "tsc -p tsconfig.test.json",
-    "test": "npm run build && npm run build:test && node --test test/*.test.ts",
+    "test": "npm run build && npm run build:test && node --test --test-concurrency=2 test/*.test.ts",
     "prepack": "npm run build",
     "typecheck": "tsc --noEmit",
     "check": "npm run typecheck",
@@ -41,22 +43,23 @@
     "privacy": "node scripts/privacy-gate.ts",
     "lint": "eslint .",
     "duplication": "node scripts/duplication-gate.ts",
-    "test:bun": "bun_status=0; for test_file in test/*.test.ts; do bun test --timeout 600000 \"$test_file\" || bun_status=1; done; exit \"$bun_status\""
+    "test:bun": "bun_status=0; for test_file in test/*.test.ts; do bun test --timeout 600000 \"$test_file\" || bun_status=1; done; exit \"$bun_status\"",
+    "test:minimum-sdk": "npm run build && node --test --test-concurrency=1 test/minimum-sdk-consumer.test.ts"
   },
   "peerDependencies": {
-    "@unbrained/pm-cli": ">=2026.10.5"
+    "@unbrained/pm-cli": ">=2026.10.17"
   },
   "devDependencies": {
     "@babel/eslint-parser": "8.0.7",
     "@babel/plugin-syntax-typescript": "8.0.3",
     "@toon-format/toon": "4.4.0",
     "@types/node": "26.6.5",
-    "@unbrained/pm-cli": "2026.10.20",
+    "@unbrained/pm-cli": ">=2026.10.17",
     "c8": "12.0.0",
     "eslint": "10.13.0",
     "jscpd": "5.4.2",
-    "pm-changelog": "2026.10.20",
-    "pm-ops": "2026.10.20",
+    "pm-changelog": "2026.10.24",
+    "pm-ops": "2026.10.24",
     "typescript": "7.0.2"
   },
   "keywords": [
@@ -100,10 +103,12 @@
     },
     "docs": [
       "README.md",
-      "CHANGELOG.md"
+      "CHANGELOG.md",
+      "docs/discussion-capture.md"
     ],
     "examples": [
-      "README.md"
+      "README.md",
+      "docs/discussion-capture-example.json"
     ]
   },
   "publishConfig": {