@akagilnc/pi-workflow-roles 0.1.3572 → 0.1.3621

package/dist/collector-github.js

@@ -0,0 +1,527 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(value, label) {
+    if (typeof value !== "string") {
+        throw new Error(`GitHub payload missing string ${label}`);
+    }
+    return value;
+}
+function requireNumber(value, label) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`GitHub payload missing number ${label}`);
+    }
+    return value;
+}
+function optionalString(value) {
+    return typeof value === "string" ? value : null;
+}
+function parseLinkNext(linkHeader) {
+    if (linkHeader === undefined || linkHeader.length === 0)
+        return undefined;
+    for (const part of linkHeader.split(",")) {
+        const match = part.trim().match(/^<([^>]+)>\s*;\s*rel="next"$/i);
+        if (match?.[1])
+            return match[1];
+    }
+    return undefined;
+}
+function parseJson(text, label) {
+    try {
+        return JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`GitHub ${label} returned malformed JSON`, { cause: error });
+    }
+}
+let commentFailureEvidence = 0;
+function commentFailureCause(error) {
+    return {
+        name: error instanceof Error ? error.name : typeof error,
+        message: error instanceof Error ? error.message : String(error),
+        evidenceId: `github-comment-failure-${++commentFailureEvidence}`,
+    };
+}
+/** Authenticated /user requires a login; throws when absent. */
+function requireUserLogin(raw) {
+    if (!isRecord(raw) || typeof raw["login"] !== "string") {
+        throw new Error("GitHub payload missing user.login");
+    }
+    return raw["login"];
+}
+/**
+ * Surface authors may be tombstoned only as literal JSON null (`user: null`).
+ * Preserve that case with null login; every other shape fails closed.
+ */
+function optionalUserLogin(raw) {
+    if (raw === null)
+        return null;
+    if (!isRecord(raw) || typeof raw["login"] !== "string") {
+        throw new Error("GitHub payload missing user.login");
+    }
+    return raw["login"];
+}
+function machineIdentity(raw) {
+    const user = raw["user"];
+    if (!isRecord(user) || typeof user["type"] !== "string" || typeof user["id"] !== "number") {
+        return null;
+    }
+    const app = raw["performed_via_github_app"];
+    const appId = isRecord(app) && typeof app["id"] === "number" ? app["id"] : undefined;
+    return {
+        userType: user["type"],
+        userId: user["id"],
+        ...(appId === undefined ? {} : { appId }),
+    };
+}
+export function normalizePullRequest(raw) {
+    if (!isRecord(raw))
+        throw new Error("GitHub pull request payload must be an object");
+    const head = raw["head"];
+    if (!isRecord(head) || typeof head["sha"] !== "string" || head["sha"].length === 0) {
+        throw new Error("GitHub pull request payload missing head.sha");
+    }
+    const number = requireNumber(raw["number"], "number");
+    const state = requireString(raw["state"], "state").toUpperCase();
+    const htmlUrl = typeof raw["html_url"] === "string"
+        ? raw["html_url"]
+        : `https://github.com/unknown/unknown/pull/${number}`;
+    return {
+        number,
+        state: state === "OPEN" || state === "open" ? "OPEN" : state,
+        headOid: head["sha"],
+        ...(typeof raw["updated_at"] === "string" ? { updatedAt: raw["updated_at"] } : {}),
+        url: htmlUrl,
+        raw,
+    };
+}
+export function normalizePullRequestReaction(raw) {
+    if (!isRecord(raw))
+        throw new Error("GitHub reaction payload must be an object");
+    return {
+        id: requireNumber(raw["id"], "reaction.id"),
+        userLogin: optionalUserLogin(raw["user"]),
+        machineIdentity: machineIdentity(raw),
+        content: requireString(raw["content"], "reaction.content"),
+        createdAt: requireString(raw["created_at"], "reaction.created_at"),
+        raw,
+    };
+}
+export function normalizeReview(raw) {
+    if (!isRecord(raw))
+        throw new Error("GitHub review payload must be an object");
+    return {
+        id: requireNumber(raw["id"], "review.id"),
+        ...(typeof raw["node_id"] === "string" ? { nodeId: raw["node_id"] } : {}),
+        userLogin: optionalUserLogin(raw["user"]),
+        machineIdentity: machineIdentity(raw),
+        state: requireString(raw["state"], "review.state").toUpperCase(),
+        body: typeof raw["body"] === "string" ? raw["body"] : "",
+        commitId: optionalString(raw["commit_id"]),
+        submittedAt: optionalString(raw["submitted_at"]),
+        htmlUrl: typeof raw["html_url"] === "string" ? raw["html_url"] : "",
+        raw,
+    };
+}
+export function normalizeIssueComment(raw) {
+    if (!isRecord(raw))
+        throw new Error("GitHub issue comment payload must be an object");
+    return {
+        id: requireNumber(raw["id"], "comment.id"),
+        userLogin: optionalUserLogin(raw["user"]),
+        machineIdentity: machineIdentity(raw),
+        body: typeof raw["body"] === "string" ? raw["body"] : "",
+        createdAt: requireString(raw["created_at"], "comment.created_at"),
+        updatedAt: requireString(raw["updated_at"], "comment.updated_at"),
+        htmlUrl: typeof raw["html_url"] === "string" ? raw["html_url"] : "",
+        raw,
+    };
+}
+export function normalizeReviewComment(raw) {
+    if (!isRecord(raw))
+        throw new Error("GitHub review comment payload must be an object");
+    return {
+        id: requireNumber(raw["id"], "review_comment.id"),
+        pullRequestReviewId: typeof raw["pull_request_review_id"] === "number"
+            ? raw["pull_request_review_id"]
+            : null,
+        userLogin: optionalUserLogin(raw["user"]),
+        machineIdentity: machineIdentity(raw),
+        body: typeof raw["body"] === "string" ? raw["body"] : "",
+        path: requireString(raw["path"], "review_comment.path"),
+        line: typeof raw["line"] === "number" ? raw["line"] : null,
+        originalLine: typeof raw["original_line"] === "number" ? raw["original_line"] : null,
+        side: optionalString(raw["side"]),
+        position: typeof raw["position"] === "number" ? raw["position"] : null,
+        originalPosition: typeof raw["original_position"] === "number"
+            ? raw["original_position"]
+            : null,
+        commitId: optionalString(raw["commit_id"]),
+        originalCommitId: optionalString(raw["original_commit_id"]),
+        createdAt: requireString(raw["created_at"], "review_comment.created_at"),
+        updatedAt: requireString(raw["updated_at"], "review_comment.updated_at"),
+        htmlUrl: typeof raw["html_url"] === "string" ? raw["html_url"] : "",
+        raw,
+    };
+}
+export function createGhApiRunner(options = {}) {
+    const spawnImpl = options.spawnImpl ?? spawn;
+    return async (args, runOptions = {}) => {
+        return await new Promise((resolve, reject) => {
+            const signal = runOptions.signal;
+            if (signal?.aborted) {
+                reject(signal.reason ?? new Error("aborted"));
+                return;
+            }
+            const child = spawnImpl("gh", args, {
+                env: options.env ?? process.env,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            let stdout = "";
+            let stderr = "";
+            let settled = false;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (signal !== undefined) {
+                    signal.removeEventListener("abort", onAbort);
+                }
+                fn();
+            };
+            const onAbort = () => {
+                try {
+                    child.kill("SIGTERM");
+                }
+                catch (error) {
+                    settle(() => reject(error));
+                    return;
+                }
+                settle(() => {
+                    reject(signal?.reason ?? new Error("aborted"));
+                });
+            };
+            if (signal !== undefined) {
+                signal.addEventListener("abort", onAbort, { once: true });
+            }
+            child.stdout.setEncoding("utf8").on("data", (chunk) => {
+                stdout += chunk;
+            });
+            child.stderr.setEncoding("utf8").on("data", (chunk) => {
+                stderr += chunk;
+            });
+            child.on("error", (error) => {
+                settle(() => reject(error));
+            });
+            // Attach before write/end so early child exit cannot raise uncaught EPIPE.
+            child.stdin.on("error", (error) => {
+                settle(() => {
+                    if (signal?.aborted) {
+                        reject(signal.reason ?? new Error("aborted"));
+                        return;
+                    }
+                    const err = error instanceof Error ? error : new Error(String(error));
+                    reject(Object.assign(err, { ambiguousGhFailure: true }));
+                });
+            });
+            if (runOptions.stdin !== undefined) {
+                child.stdin.write(runOptions.stdin);
+            }
+            child.stdin.end();
+            child.on("close", (code, signal) => {
+                settle(() => {
+                    // gh api --include prints: HTTP/ headers blank-line body
+                    const match = stdout.match(/^HTTP\/[\d.]+\s+(\d+)[^\n]*\r?\n([\s\S]*?)\r?\n\r?\n([\s\S]*)$/);
+                    if (match) {
+                        const status = Number(match[1]);
+                        const headerText = match[2] ?? "";
+                        const bodyText = match[3] ?? "";
+                        const headers = {};
+                        for (const line of headerText.split(/\r?\n/)) {
+                            const idx = line.indexOf(":");
+                            if (idx === -1)
+                                continue;
+                            const name = line.slice(0, idx).trim().toLowerCase();
+                            const value = line.slice(idx + 1).trim();
+                            headers[name] = value;
+                        }
+                        resolve({ status, headers, bodyText });
+                        return;
+                    }
+                    if (code === 0) {
+                        resolve({ status: 200, headers: {}, bodyText: stdout });
+                        return;
+                    }
+                    // Ambiguous: process failed without parseable HTTP response
+                    const failure = new Error(`gh api failed without a parseable HTTP response (code=${String(code)}): ${stderr || stdout}`, { cause: { code, signal, stderr, stdout } });
+                    reject(Object.assign(failure, { ambiguousGhFailure: true, stderr, stdout, code, signal }));
+                });
+            });
+        });
+    };
+}
+function isAmbiguousGhFailure(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        error.ambiguousGhFailure === true);
+}
+/** gh binary missing or otherwise unable to launch — ticket-authorized soft unavailable. */
+function isGhProcessStartFailure(error) {
+    if (typeof error !== "object" || error === null)
+        return false;
+    const code = error.code;
+    if (code === "ENOENT")
+        return true;
+    const syscall = error.syscall;
+    return typeof syscall === "string" && (syscall === "spawn" || syscall.startsWith("spawn "));
+}
+/**
+ * Sole shared issue-body fetch + projection over createGhApiRunner.
+ * Soft and hard callers only map this result; they do not duplicate argv/parse.
+ */
+export async function projectGhIssueBody(runner, input) {
+    const path = `repos/${input.owner}/${input.repo}/issues/${input.ticketNumber}`;
+    let response;
+    try {
+        response = await runner(["api", "--hostname", "github.com", "--include", "-X", "GET", path], input.signal === undefined ? {} : { signal: input.signal });
+    }
+    catch (error) {
+        // Transport ambiguity / gh never started → unavailable. Other failures keep true cause as throw.
+        if (isAmbiguousGhFailure(error) || isGhProcessStartFailure(error)) {
+            return { status: "unavailable", reason: "transport", cause: error };
+        }
+        throw error;
+    }
+    if (response.status < 200 || response.status >= 300) {
+        return {
+            status: "unavailable",
+            reason: "http-non-2xx",
+            httpStatus: response.status,
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(response.bodyText);
+    }
+    catch (error) {
+        return { status: "invalid", reason: "not-json", cause: error };
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return { status: "invalid", reason: "not-object" };
+    }
+    // Issues endpoint also returns PRs. Own-key presence of pull_request → not an issue face.
+    if (Object.hasOwn(parsed, "pull_request")) {
+        return { status: "unavailable", reason: "pull-request" };
+    }
+    // Match former gh --jq `(.body // "")`: null/missing body projects to empty string.
+    const bodyRaw = parsed.body;
+    if (bodyRaw !== undefined && bodyRaw !== null && typeof bodyRaw !== "string") {
+        return { status: "invalid", reason: "body-invalid" };
+    }
+    const body = typeof bodyRaw === "string" ? bodyRaw : "";
+    return { status: "available", body };
+}
+/**
+ * Production issue-fetch capability owned by the shared gh execution seam.
+ * Reuses projectGhIssueBody. Softens only ticket-authorized unavailable results
+ * (tracker unreachable / issue not found / gh cannot start / PR marker);
+ * invalid payload shapes propagate with true cause.
+ */
+export function createGhIssueSoftFetcher(runner = createGhApiRunner()) {
+    return async (input) => {
+        const projected = await projectGhIssueBody(runner, input);
+        if (projected.status === "available") {
+            return Object.freeze({ body: projected.body });
+        }
+        if (projected.status === "unavailable") {
+            return undefined;
+        }
+        // invalid — keep true cause (historical soft-fetcher contract).
+        if (projected.reason === "not-json") {
+            throw new Error("GitHub issue payload is not JSON", {
+                cause: projected.cause,
+            });
+        }
+        if (projected.reason === "not-object") {
+            throw new Error("GitHub issue payload must be a JSON object");
+        }
+        throw new Error("GitHub issue payload body must be string or null");
+    };
+}
+export function createGhCollectorGitHubTransport(runner = createGhApiRunner()) {
+    const hostnameArgs = ["api", "--hostname", "github.com", "--include"];
+    async function apiGet(path, signal) {
+        return await runner([...hostnameArgs, "-X", "GET", path], signal === undefined ? {} : { signal });
+    }
+    async function paginate(path, mapItem, options = {}) {
+        const { signal, retainPage } = options;
+        const items = [];
+        const pages = [];
+        let nextPath = path;
+        let page = 1;
+        const seen = new Set();
+        while (nextPath !== undefined) {
+            if (signal?.aborted) {
+                throw signal.reason ?? new Error("aborted");
+            }
+            if (seen.has(nextPath)) {
+                throw new Error(`GitHub pagination repeated page: ${nextPath}`);
+            }
+            seen.add(nextPath);
+            const response = await apiGet(nextPath, signal);
+            const diagnostics = {
+                path: nextPath,
+                page,
+                status: response.status,
+                itemCount: 0,
+                ...(response.headers["link"] === undefined
+                    ? {}
+                    : { linkHeader: response.headers["link"] }),
+            };
+            if (response.status === 429) {
+                throw Object.assign(new Error(`GitHub API rate limited on ${nextPath} (HTTP 429)`), { githubStatus: 429, page: diagnostics });
+            }
+            if (response.status < 200 || response.status >= 300) {
+                throw Object.assign(new Error(`GitHub API ${nextPath} failed with HTTP ${response.status}`), { githubStatus: response.status, page: diagnostics });
+            }
+            const parsed = parseJson(response.bodyText, nextPath);
+            if (!Array.isArray(parsed)) {
+                throw new Error(`GitHub API ${nextPath} did not return a JSON array`);
+            }
+            diagnostics.itemCount = parsed.length;
+            pages.push(diagnostics);
+            const pageItems = parsed.map((entry) => mapItem(entry));
+            // Observation budget hook: charge before aggregate append / next-page fetch.
+            retainPage?.(pageItems);
+            for (const item of pageItems)
+                items.push(item);
+            const nextUrl = parseLinkNext(response.headers["link"]);
+            if (nextUrl === undefined) {
+                nextPath = undefined;
+            }
+            else {
+                // Accept absolute or path-style next links; normalize to API path + query.
+                if (nextUrl.startsWith("/")) {
+                    nextPath = nextUrl;
+                }
+                else {
+                    const url = new URL(nextUrl);
+                    if (url.hostname !== "api.github.com" && url.hostname !== "github.com") {
+                        throw new Error(`unexpected pagination host ${url.hostname}`);
+                    }
+                    nextPath = `${url.pathname}${url.search}`;
+                    if (nextPath.startsWith("/api/v3/")) {
+                        nextPath = nextPath.slice("/api/v3".length);
+                    }
+                }
+            }
+            page += 1;
+        }
+        return { items, pages };
+    }
+    return {
+        async getAuthenticatedUser(options = {}) {
+            const response = await apiGet("/user", options.signal);
+            if (response.status < 200 || response.status >= 300) {
+                throw new Error(`GitHub /user failed with HTTP ${response.status}`, { cause: { endpoint: "/user", status: response.status, headers: response.headers, body: response.bodyText } });
+            }
+            const raw = parseJson(response.bodyText, "/user");
+            return { login: requireUserLogin(raw).toLowerCase(), raw };
+        },
+        async getPullRequest(input) {
+            const path = `/repos/${input.owner}/${input.repo}/pulls/${input.prNumber}`;
+            const response = await apiGet(path, input.signal);
+            if (response.status < 200 || response.status >= 300) {
+                throw new Error(`GitHub ${path} failed with HTTP ${response.status}`, { cause: { endpoint: path, status: response.status, headers: response.headers, body: response.bodyText } });
+            }
+            return normalizePullRequest(parseJson(response.bodyText, path));
+        },
+        async listPullRequestReviews(input) {
+            const path = `/repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/reviews?per_page=100`;
+            return await paginate(path, normalizeReview, {
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+                ...(input.retainPage === undefined ? {} : { retainPage: input.retainPage }),
+            });
+        },
+        async listPullRequestReactions(input) {
+            const path = `/repos/${input.owner}/${input.repo}/issues/${input.prNumber}/reactions?per_page=100`;
+            return await paginate(path, normalizePullRequestReaction, {
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+                ...(input.retainPage === undefined ? {} : { retainPage: input.retainPage }),
+            });
+        },
+        async listIssueComments(input) {
+            const path = `/repos/${input.owner}/${input.repo}/issues/${input.prNumber}/comments?per_page=100`;
+            return await paginate(path, normalizeIssueComment, {
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+                ...(input.retainPage === undefined ? {} : { retainPage: input.retainPage }),
+            });
+        },
+        async listReviewComments(input) {
+            const path = `/repos/${input.owner}/${input.repo}/pulls/${input.prNumber}/comments?per_page=100`;
+            return await paginate(path, normalizeReviewComment, {
+                ...(input.signal === undefined ? {} : { signal: input.signal }),
+                ...(input.retainPage === undefined ? {} : { retainPage: input.retainPage }),
+            });
+        },
+        async createIssueComment(input) {
+            const path = `/repos/${input.owner}/${input.repo}/issues/${input.prNumber}/comments`;
+            try {
+                const response = await runner([...hostnameArgs, "-X", "POST", path, "--input", "-"], input.signal === undefined
+                    ? { stdin: JSON.stringify({ body: input.body }) }
+                    : { stdin: JSON.stringify({ body: input.body }), signal: input.signal });
+                if (response.status >= 200 && response.status < 300) {
+                    // Contract: README.md#Collector — a successful write with unreadable response is recoverable only as an observable ambiguous result.
+                    // 2xx means the comment may already exist; parse/normalize failure is
+                    // ambiguous_loss so ledger marker recovery can resolve without repost.
+                    try {
+                        return {
+                            kind: "success",
+                            comment: normalizeIssueComment(parseJson(response.bodyText, path)),
+                        };
+                    }
+                    catch (error) {
+                        const cause = commentFailureCause(error);
+                        return { kind: "ambiguous_loss", diagnostics: cause.message, cause };
+                    }
+                }
+                return {
+                    kind: "rejected",
+                    status: response.status,
+                    diagnostics: `HTTP ${response.status}: ${response.bodyText.slice(0, 500)}`,
+                };
+            }
+            catch (error) {
+                // Signal state is authoritative cancel; rethrow exact caught value.
+                if (input.signal?.aborted) {
+                    throw error;
+                }
+                // Non-aborted transport tag only (after signal).
+                if (isRecord(error) && error["ambiguousGhFailure"] === true) {
+                    const cause = commentFailureCause(error);
+                    return { kind: "ambiguous_loss", diagnostics: cause.message, cause };
+                }
+                // Non-signal AbortError belt only (after tag).
+                if (isRecord(error) && error["name"] === "AbortError") {
+                    throw error;
+                }
+                throw error;
+            }
+        },
+    };
+}
+export function buildCollectorRequestMarker(input) {
+    const prefix = input.manifestDigest.slice(0, 12);
+    const requestMarkerId = createHash("sha256").update(input.requestId).digest("hex");
+    return `<!-- ak-collector:v1 manifest=${prefix} request=${requestMarkerId} head=${input.headOid} -->`;
+}
+export function buildCollectorRequestBody(input) {
+    const marker = buildCollectorRequestMarker(input);
+    // Preserve configured body byte-for-byte; append marker on its own line.
+    const body = input.configuredBody.endsWith("\n")
+        ? `${input.configuredBody}${marker}\n`
+        : `${input.configuredBody}\n${marker}\n`;
+    return { body, marker };
+}