@akagilnc/pi-workflow-roles 0.1.3749 → 0.1.3771

package/src/collector-target.ts

@@ -0,0 +1,207 @@
+/**
+ * #676 D1: Collector admission target recognition on structured git context.
+ * Explicit PR wins (no association queries). Otherwise gather online candidates
+ * from structured upstream head and HEAD commit association only. Deduped unique
+ * → bind; many → require explicit --pr; zero → unbound so the role can decide
+ * from task materials via the bind-target business tool. No task-text scrape,
+ * no second state machine. Git/config/transport failures keep true cause.
+ */
+import { execFileSync } from "node:child_process";
+
+import type { CollectorRepository } from "./collector-config.ts";
+import {
+  createGhApiRunner,
+  listPullRequestNumbersByCommit,
+  listPullRequestNumbersByHead,
+} from "./collector-github.ts";
+import { CliUsageError } from "./public-cli/cli-errors.ts";
+import {
+  ownerFromGitHubRemoteUrl,
+  ownerRepoFromGitHubRemoteUrl,
+} from "./public-cli/github-remote.ts";
+
+export type ResolveCollectorTargetInput = {
+  readonly projectRoot: string;
+  readonly repository: CollectorRepository;
+  /** Caller-provided PR number when already explicit. */
+  readonly explicitPrNumber?: number;
+};
+
+export type CollectorTargetResolution =
+  | { readonly kind: "bound"; readonly prNumber: number }
+  | { readonly kind: "unbound" };
+
+function ambiguousTarget(detail: string, cause?: unknown): never {
+  throw new CliUsageError(
+    `collector target is ambiguous: ${detail}; pass an explicit --pr`,
+    cause === undefined ? undefined : { cause },
+  );
+}
+
+/** Real git failure — not target ambiguity. Propagates with true cause on exit 1. */
+function gitFailure(detail: string, cause: unknown): never {
+  throw new Error(`collector git failed: ${detail}`, {
+    cause: cause instanceof Error ? cause : new Error(String(cause)),
+  });
+}
+
+function gitText(projectRoot: string, args: readonly string[]): string {
+  return execFileSync("git", [...args], {
+    cwd: projectRoot,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  }).trim();
+}
+
+/** git config --get exit 1 = key absent; other failures keep true cause. */
+function isGitConfigMissing(error: unknown): boolean {
+  if (typeof error !== "object" || error === null) return false;
+  const status = (error as { status?: unknown }).status;
+  return status === 1;
+}
+
+function readCurrentBranch(projectRoot: string): string {
+  try {
+    return gitText(projectRoot, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  } catch (error) {
+    gitFailure("cannot read current git branch", error);
+  }
+}
+
+function readHeadSha(projectRoot: string): string {
+  try {
+    return gitText(projectRoot, ["rev-parse", "HEAD"]);
+  } catch (error) {
+    gitFailure("cannot read current HEAD", error);
+  }
+}
+
+/**
+ * Head ref short name from branch.<name>.merge (refs/heads/<ref> or bare ref).
+ * Non-heads merge forms are not a structured head binding.
+ */
+function headRefFromMerge(merge: string): string | undefined {
+  const trimmed = merge.trim();
+  if (trimmed.length === 0) return undefined;
+  if (trimmed.startsWith("refs/heads/")) {
+    const ref = trimmed.slice("refs/heads/".length);
+    return ref.length > 0 ? ref : undefined;
+  }
+  // Reject other refs/* (e.g. refs/remotes/…) — not a PR head ref binding.
+  if (trimmed.startsWith("refs/")) return undefined;
+  return trimmed;
+}
+
+/**
+ * Real upstream head owner + head ref from branch.<name>.remote/merge when configured.
+ * Missing config keys = not configured (undefined). Config/remote execution failures
+ * throw with true cause — never swallowed as "no upstream, keep fallback".
+ */
+function readUpstreamHeadBinding(
+  projectRoot: string,
+  branch: string,
+): { readonly headOwner: string; readonly headRef: string } | undefined {
+  let remote: string | undefined;
+  try {
+    remote = gitText(projectRoot, ["config", "--get", `branch.${branch}.remote`]);
+  } catch (error) {
+    if (isGitConfigMissing(error)) remote = undefined;
+    else gitFailure(`cannot read branch.${branch}.remote`, error);
+  }
+  if (remote === undefined || remote.length === 0) return undefined;
+
+  let merge: string | undefined;
+  try {
+    merge = gitText(projectRoot, ["config", "--get", `branch.${branch}.merge`]);
+  } catch (error) {
+    if (isGitConfigMissing(error)) merge = undefined;
+    else gitFailure(`cannot read branch.${branch}.merge`, error);
+  }
+  if (merge === undefined || merge.length === 0) return undefined;
+
+  const headRef = headRefFromMerge(merge);
+  if (headRef === undefined) return undefined;
+
+  let remoteUrl: string;
+  try {
+    remoteUrl = gitText(projectRoot, ["remote", "get-url", remote]);
+  } catch (error) {
+    gitFailure(`cannot read remote URL for ${remote}`, error);
+  }
+  const headOwner = ownerFromGitHubRemoteUrl(remoteUrl);
+  if (headOwner === undefined) return undefined;
+  return { headOwner, headRef };
+}
+
+/**
+ * Resolve the Collector PR target without guessing from task text.
+ * - Explicit `--pr` → that number (no association queries).
+ * - Otherwise: full online candidates (upstream head + HEAD commit), deduped.
+ * - Exactly 1 → bound. >1 → require explicit `--pr`. 0 → unbound (role bind tool).
+ * - Git/config/transport/HTTP/JSON failures propagate with true cause.
+ */
+export async function resolveCollectorTarget(
+  input: ResolveCollectorTargetInput,
+): Promise<CollectorTargetResolution> {
+  if (input.explicitPrNumber !== undefined) {
+    return { kind: "bound", prNumber: input.explicitPrNumber };
+  }
+
+  const branch = readCurrentBranch(input.projectRoot);
+  const detached = branch.length === 0 || branch === "HEAD";
+
+  // Detached HEAD cannot associate via branch head; commit association still runs.
+  const runner = createGhApiRunner();
+  const { owner, repo } = input.repository;
+  const numbers: number[] = [];
+
+  if (!detached) {
+    const headSha = readHeadSha(input.projectRoot);
+    const upstream = readUpstreamHeadBinding(input.projectRoot, branch);
+
+    // Prefer structured head owner:ref from real upstream merge binding (fork-safe).
+    if (upstream !== undefined) {
+      numbers.push(
+        ...(await listPullRequestNumbersByHead(runner, {
+          owner,
+          repo,
+          headOwner: upstream.headOwner,
+          headRef: upstream.headRef,
+        })),
+      );
+    }
+    // Always also take commit association — never let a sole upstream hit hide a conflict.
+    numbers.push(
+      ...(await listPullRequestNumbersByCommit(runner, {
+        owner,
+        repo,
+        commitSha: headSha,
+      })),
+    );
+  } else {
+    // Detached: commit association only (no branch head).
+    const headSha = readHeadSha(input.projectRoot);
+    numbers.push(
+      ...(await listPullRequestNumbersByCommit(runner, {
+        owner,
+        repo,
+        commitSha: headSha,
+      })),
+    );
+  }
+
+  const unique = [...new Set(numbers)];
+
+  if (unique.length === 1) {
+    return { kind: "bound", prNumber: unique[0]! };
+  }
+  if (unique.length > 1) {
+    ambiguousTarget(
+      `multiple PRs associated with context: ${unique.join(", ")}`,
+    );
+  }
+  // Zero structured git hits — leave unbound so the role can decide from materials.
+  return { kind: "unbound" };
+}
+
+export { ownerRepoFromGitHubRemoteUrl, ownerFromGitHubRemoteUrl };

package/src/collector-tool-schemas.ts

@@ -1,5 +1,6 @@
 import { Type, type Static } from "typebox";
 import { COLLECTOR_ELIGIBILITY_MS } from "./collector-evidence.ts";
+import { openToolObject } from "./open-tool-schema.ts";
 import { withInfrastructureFailureDeclaration } from "./package-contracts/terminating-infrastructure.ts";
 
 export const collectorObserveArgsSchema = Type.Object({}, { additionalProperties: false });
@@ -15,31 +16,77 @@ export const collectorWaitArgsSchema = Type.Object({
 }, { additionalProperties: false });
 
 /**
- * #641 chain①: the collector LLM does the splitting/classification (#245:
- * 他自己就是llm为什么不能读不能拆). Findings are submitted as pointer refs into
- * the stored evidence; the runtime enriches each with the machine pointer
- * (repo/PR/comment id/url/author/kind/时间) and validates resolvability.
- * Category is a short LLM classification label, never a body transcription.
+ * #676 A: role-decided target bind. The model judges task materials and submits
+ * the chosen PR and/or issue identity; runtime only performs online association
+ * for the role-chosen ticket — never scrapes task text to lock a target.
  */
-export const collectorFindingArgsSchema = Type.Object({
-  evidenceId: Type.String({ minLength: 1, description: "observe 返回的材料证据 id（evidenceId）" }),
-  category: Type.Optional(Type.String({ minLength: 1, maxLength: 200, description: "该 finding 的简短归类标签；需要头部之外的正文时先用 ak_collector_read 开卷再判读，不得誊写评论正文" })),
-}, { additionalProperties: false });
-
-export const collectorOutputBaseSchema = Type.Object({
-  findings: Type.Optional(Type.Array(collectorFindingArgsSchema, {
-    description: "本次收集到的逐条 findings；零 finding 的模板通知不得进入。正常完工无 finding 时省略。",
+export const collectorBindTargetArgsSchema = Type.Object({
+  prNumber: Type.Optional(Type.Unknown({
+    description: "角色判定的本仓 PR 号（正整数）。与 issueNumber 二选一或同指唯一目标。形状指引，非 schema 闸。",
   })),
-}, { additionalProperties: true, description: "正常完工提交空对象 {}；仅在基础设施真实失败时才填写 infrastructureFailure，无失败时必须省略该字段。" });
+  issueNumber: Type.Optional(Type.Unknown({
+    description: "角色判定的本仓 issue 号（正整数）；runtime 经线上关联解析唯一 PR。形状指引，非 schema 闸。",
+  })),
+}, { additionalProperties: true });
+
+/**
+ * #641 chain① / #676 C / ADR 0057: nested finding item declarations for model
+ * guidance. Host must not pure-shape-reject the envelope (第 0 条). Runtime binds
+ * resolvable evidence pointers only; unprojected content stays distinguishable.
+ */
+const collectorFindingItemDeclaration = (() => {
+  // Nested declarations for model guidance only — open required so host cannot
+  // pure-shape-reject missing optional fields (第 0 条 / ADR 0057 / #676 C).
+  const item = Type.Object(
+    {
+      evidenceId: Type.Unknown({
+        description: "observe 返回的材料指针（必填语义）",
+      }),
+      category: Type.Unknown({
+        description: "简短归类标签，不是摘要",
+      }),
+      summary: Type.Unknown({
+        description: "哪个 bot、什么问题的摘要；不誊抄正文",
+      }),
+    },
+    {
+      additionalProperties: true,
+      description:
+        "单条 finding 指针：evidenceId + 可选 category/summary。形状指引，非 schema 闸。",
+    },
+  );
+  (item as unknown as { required: string[] }).required = [];
+  return item;
+})();
+
+/**
+ * Field declarations + descriptions are guidance for the model — host must not
+ * pure-shape-reject the envelope (第 0 条 / ADR 0057).
+ */
+export const collectorOutputBaseSchema = openToolObject(
+  Type.Object({
+    // No root type:array — host must not shape-reject non-array findings (#676 C).
+    // Nested item declarations ride `items` for registration preservation (ADR 0057).
+    findings: Type.Unsafe({
+      description:
+        "本次收集到的逐条 findings（指针数组为规范形）。零 finding 的模板通知不得进入；正常完工无 finding 时省略。形状指引，非 schema 闸。",
+      items: collectorFindingItemDeclaration,
+    }),
+    unfinishedReasons: Type.Unknown({
+      description:
+        "未完成原因字符串数组（额度/故障/等待届满等现场依据）；不得把未完成表述为无问题。无可报告时省略。形状指引，非 schema 闸。",
+    }),
+  }),
+);
 
 /** Runtime owns the observed evidence; the model submits findings and signals sole-final submission. */
 export const collectorOutputArgsSchema = withInfrastructureFailureDeclaration(
   collectorOutputBaseSchema,
 );
-(collectorOutputArgsSchema as unknown as { required: string[] }).required = [];
 
 export type CollectorObserveArgs = Static<typeof collectorObserveArgsSchema>;
 export type CollectorRequestArgs = Static<typeof collectorRequestArgsSchema>;
 export type CollectorReadArgs = Static<typeof collectorReadArgsSchema>;
 export type CollectorWaitArgs = Static<typeof collectorWaitArgsSchema>;
+export type CollectorBindTargetArgs = Static<typeof collectorBindTargetArgsSchema>;
 export type CollectorOutputArgs = Static<typeof collectorOutputArgsSchema>;

package/src/host-contracts.ts

@@ -103,7 +103,8 @@ export type RoleTurnActivation =
   | {
       readonly role: "collector";
       readonly repo: string;
-      readonly pr: string;
+      /** Bound PR when known at admission; omit when role will bind from materials. */
+      readonly pr?: string;
       readonly requestManifestPath?: string;
     }
   | { readonly role: "doctor"; readonly casePath: string }

package/src/package-contracts/collector-output.ts

@@ -59,10 +59,29 @@ export type CollectorEvidenceRecord = {
   authoritativeTime?: string | null;
 };
 
+/**
+ * #676 C: sole structured projection-fact type (builder + package leaf).
+ * Builder always emits the full object; package leaf keeps it optional so old
+ * volumes without the field stay readable — missing is unknown, never defaulted.
+ */
+export type CollectorSubmissionProjection = {
+  findingsSource: "absent" | "array" | "unreadable";
+  findingsProjectedCount: number;
+  findingsUnprojected: boolean;
+  unfinishedReasonsSource: "absent" | "array" | "unreadable";
+  unfinishedReasonsProjectedCount: number;
+  unfinishedReasonsUnprojected: boolean;
+};
+
 export type CollectorReceipt = {
   host: "github.com";
   repository: string;
   prNumber: number;
+  /**
+   * Final observed PR state; non-OPEN still delivers materials (#676 D6).
+   * Absent/unreadable on old volumes is unknown — never defaulted to OPEN.
+   */
+  prState?: string;
   manifestDigest: string;
   activationTime: string;
   deadlineTime: string;
@@ -70,6 +89,13 @@ export type CollectorReceipt = {
   finalSnapshotId: string;
   targetHead: string;
   groups: CollectorIdentityGroup[];
+  unfinishedReasons?: string[];
+  /**
+   * Distinguishes readable-empty from unprojected original submission content (#676 C).
+   * Package leaf may carry a partial projection when some sibling keys are unreadable —
+   * missing keys stay absent (never defaulted false/0/OPEN).
+   */
+  submissionProjection?: Partial<CollectorSubmissionProjection>;
   requestAttempts: CollectorRequestAttempt[];
   snapshots: CollectorSnapshot[];
   evidenceRecords: CollectorEvidenceRecord[];
@@ -97,10 +123,18 @@ export function validateAcceptedCollectorReceipt(value: unknown): CollectorRecei
     materials: records(safeGet(group, "materials")),
     findings: records(safeGet(group, "findings")),
   }));
+  const unfinishedRaw = safeGet(value, "unfinishedReasons");
+  const unfinishedReasons = strings(unfinishedRaw);
+  // #676 C: project readable submissionProjection fields independently — do not
+  // drop the whole block when one sibling key is the wrong type (left-拾遗1).
+  const submissionProjection = projectSubmissionProjection(safeGet(value, "submissionProjection"));
+  const prStateRaw = safeGet(value, "prState");
+  const prState = typeof prStateRaw === "string" ? prStateRaw : undefined;
   return {
     host: safeGet(value, "host") as "github.com",
     repository: safeGet(value, "repository") as string,
     prNumber: safeGet(value, "prNumber") as number,
+    ...(prState === undefined ? {} : { prState }),
     manifestDigest: safeGet(value, "manifestDigest") as string,
     activationTime: safeGet(value, "activationTime") as string,
     deadlineTime: safeGet(value, "deadlineTime") as string,
@@ -108,6 +142,8 @@ export function validateAcceptedCollectorReceipt(value: unknown): CollectorRecei
     finalSnapshotId: safeGet(value, "finalSnapshotId") as string,
     targetHead: safeGet(value, "targetHead") as string,
     groups,
+    ...(unfinishedReasons.length > 0 ? { unfinishedReasons } : {}),
+    ...(submissionProjection === undefined ? {} : { submissionProjection }),
     requestAttempts: records(safeGet(value, "requestAttempts")) as unknown as CollectorRequestAttempt[],
     snapshots: records(safeGet(value, "snapshots")).map((snapshot) => ({
       snapshotId: safeGet(snapshot, "snapshotId"), observedAt: safeGet(snapshot, "observedAt"), completedAt: safeGet(snapshot, "completedAt"), completedMono: safeGet(snapshot, "completedMono"), host: safeGet(snapshot, "host"), repository: safeGet(snapshot, "repository"), prNumber: safeGet(snapshot, "prNumber"), prState: safeGet(snapshot, "prState"), headOid: safeGet(snapshot, "headOid"), complete: safeGet(snapshot, "complete"), evidenceIds: strings(safeGet(snapshot, "evidenceIds")), pageDiagnostics: records(safeGet(snapshot, "pageDiagnostics")), normalizedByteLength: safeGet(snapshot, "normalizedByteLength"),
@@ -115,3 +151,39 @@ export function validateAcceptedCollectorReceipt(value: unknown): CollectorRecei
     evidenceRecords: records(safeGet(value, "evidenceRecords")).map((record) => ({ evidenceId: safeGet(record, "evidenceId"), kind: safeGet(record, "kind"), versionId: safeGet(record, "versionId"), contentDigest: safeGet(record, "contentDigest"), firstObservedAt: safeGet(record, "firstObservedAt"), githubId: safeGet(record, "githubId"), authorLogin: safeGet(record, "authorLogin"), htmlUrl: safeGet(record, "htmlUrl"), authoritativeTime: safeGet(record, "authoritativeTime") } as CollectorEvidenceRecord)),
   };
 }
+
+/** Readable projection facts only; omit keys that are the wrong type — never fabricate defaults. */
+function projectSubmissionProjection(
+  raw: unknown,
+): Partial<CollectorSubmissionProjection> | undefined {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const p = raw as Record<string, unknown>;
+  const out: Partial<CollectorSubmissionProjection> = {};
+  if (
+    p["findingsSource"] === "absent" ||
+    p["findingsSource"] === "array" ||
+    p["findingsSource"] === "unreadable"
+  ) {
+    out.findingsSource = p["findingsSource"];
+  }
+  if (typeof p["findingsProjectedCount"] === "number") {
+    out.findingsProjectedCount = p["findingsProjectedCount"];
+  }
+  if (typeof p["findingsUnprojected"] === "boolean") {
+    out.findingsUnprojected = p["findingsUnprojected"];
+  }
+  if (
+    p["unfinishedReasonsSource"] === "absent" ||
+    p["unfinishedReasonsSource"] === "array" ||
+    p["unfinishedReasonsSource"] === "unreadable"
+  ) {
+    out.unfinishedReasonsSource = p["unfinishedReasonsSource"];
+  }
+  if (typeof p["unfinishedReasonsProjectedCount"] === "number") {
+    out.unfinishedReasonsProjectedCount = p["unfinishedReasonsProjectedCount"];
+  }
+  if (typeof p["unfinishedReasonsUnprojected"] === "boolean") {
+    out.unfinishedReasonsUnprojected = p["unfinishedReasonsUnprojected"];
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}

package/src/package-contracts/terminating-infrastructure.ts

@@ -18,21 +18,32 @@ export const INFRASTRUCTURE_FAILURE_DECLARATION_KEY =
   "infrastructureFailure" as const;
 export const INFRASTRUCTURE_FAILURE_DIAGNOSTIC_KEY = "diagnostic" as const;
 
-/** Shared typed declaration fragment: `infrastructureFailure.diagnostic` = non-empty string. */
+/**
+ * Shared declaration fragment for model guidance (#541 / #676 C / ADR 0057).
+ * Nested field declarations + descriptions only — host must not pure-shape-reject
+ * the envelope (第 0 条). Runtime `failOnInfrastructureFailureDeclaration` still
+ * recognizes a real non-empty diagnostic string as the failure declaration.
+ * No required/minLength/type host gates on the declaration fragment.
+ */
+const infrastructureFailureNested = Type.Object(
+  {
+    [INFRASTRUCTURE_FAILURE_DIAGNOSTIC_KEY]: Type.Unknown({
+      description:
+        "非空基础设施失败诊断字符串。无失败时必须省略整个 infrastructureFailure。形状指引，非 schema 闸。",
+    }),
+  },
+  {
+    additionalProperties: true,
+    description:
+      "基础设施真实失败声明（如需）。规范形：{ diagnostic: 非空诊断字符串 }；无失败时必须省略。形状指引，非 schema 闸。",
+  },
+);
+// Open nested required so host cannot pure-shape-reject the declaration fragment.
+(infrastructureFailureNested as unknown as { required: string[] }).required = [];
+
 const infrastructureFailureDeclarationSchema = Type.Object(
   {
-    [INFRASTRUCTURE_FAILURE_DECLARATION_KEY]: Type.Object(
-      {
-        [INFRASTRUCTURE_FAILURE_DIAGNOSTIC_KEY]: Type.String({
-          minLength: 1,
-          description: "非空基础设施失败诊断",
-        }),
-      },
-      {
-        additionalProperties: true,
-        description: "基础设施失败声明",
-      },
-    ),
+    [INFRASTRUCTURE_FAILURE_DECLARATION_KEY]: infrastructureFailureNested,
   },
   { additionalProperties: true },
 );

package/src/pi/role-turn-host.ts

@@ -112,8 +112,7 @@ function buildActivationFlagArgs(activation: RoleTurnActivation): string[] {
         "collector",
         "--ak-collector-repo",
         activation.repo,
-        "--ak-collector-pr",
-        activation.pr,
+        ...(activation.pr === undefined ? [] : ["--ak-collector-pr", activation.pr]),
         ...(activation.requestManifestPath === undefined
           ? []
           : ["--ak-collector-request-manifest", activation.requestManifestPath]),

package/src/public-cli/cli.ts

@@ -149,6 +149,7 @@ import {
 } from "./registry.ts";
 import {
   formatCliDiagnostic,
+  formatErrorCauseDetail,
   presentStructuralRejection,
 } from "./settlement.ts";
 import type { TerminalResult } from "./terminal.ts";
@@ -1620,11 +1621,19 @@ export async function runAkRole(
       return { exitCode: 2 };
     }
     // Unrecognized outer failure: retain actual name/message identity (no wash).
+    // #676 B: cause (HTTP body/headers, git stderr, nested Error) must reach the
+    // caller via the same formatErrorCauseDetail face as structural rejection.
     if (error instanceof Error) {
-      const label =
+      let label =
         error.name !== "" && error.name !== "Error"
           ? `${error.name}: ${error.message}`
           : error.message;
+      if (error.cause !== undefined) {
+        const detail = formatErrorCauseDetail(error.cause);
+        if (detail.trim().length > 0) {
+          label = `${label || error.name || "unrecognized exception"}; cause: ${detail}`;
+        }
+      }
       io.stderr(formatCliDiagnostic(label || error.name || "unrecognized exception"));
       return { exitCode: 1 };
     }

package/src/public-cli/collector-run.ts

@@ -51,7 +51,8 @@ export function buildCollectorTurnRequest(
       activation: {
         role: "collector" as const,
         repo: admitted.repository.display,
-        pr: String(admitted.prNumber),
+        // #676 A: omit pr when unbound — role binds via ak_collector_bind_target.
+        ...(admitted.prNumber === undefined ? {} : { pr: String(admitted.prNumber) }),
         ...(admitted.requestManifestPath === undefined ? {} : { requestManifestPath: admitted.requestManifestPath }),
       },
     },
@@ -76,7 +77,7 @@ export async function runPublicCollector(
       home: env.home,
       principalAuthority: env.principalAuthority,
       cwd: env.cwd,
-      prNumber: parsed.prNumber,
+      ...(parsed.prNumber === undefined ? {} : { prNumber: parsed.prNumber }),
       instruction: parsed.instruction,
       attachmentPaths: parsed.attachmentPaths,
       ...(parsed.project === undefined ? {} : { project: parsed.project }),

package/src/public-cli/github-remote.ts

@@ -0,0 +1,45 @@
+/**
+ * Shared github.com remote URL → owner/repo parse (#676 B/D7).
+ * One authority for collector admission origin and upstream head owner.
+ */
+
+/** Parse owner from a github.com remote URL; undefined when not a GitHub owner/repo remote. */
+export function ownerFromGitHubRemoteUrl(remoteUrl: string): string | undefined {
+  const ownerRepo = ownerRepoFromGitHubRemoteUrl(remoteUrl);
+  if (ownerRepo === undefined) return undefined;
+  return ownerRepo.split("/")[0]!.toLowerCase();
+}
+
+/** Parse owner/repo identity from a github.com remote URL; undefined when not exact. */
+export function ownerRepoFromGitHubRemoteUrl(remoteUrl: string): string | undefined {
+  const trimmed = remoteUrl.trim();
+  // git@github.com:owner/repo.git — exact owner/repo identity only.
+  const scp = /^git@github\.com:([^/\s]+)\/([^/\s]+?)(?:\.git)?$/i.exec(trimmed);
+  if (scp) {
+    return `${scp[1]}/${stripGitSuffix(scp[2]!)}`;
+  }
+  // ssh://git@github.com/owner/repo(.git) — exact owner/repo identity only.
+  const ssh = /^ssh:\/\/git@github\.com\/([^/\s]+)\/([^/\s]+?)(?:\.git)?\/?$/i.exec(
+    trimmed,
+  );
+  if (ssh) {
+    return `${ssh[1]}/${stripGitSuffix(ssh[2]!)}`;
+  }
+  // https://github.com/owner/repo(.git) and git://github.com/... — exact two-segment path.
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return undefined;
+  }
+  if (!/^github\.com$/i.test(parsed.hostname)) return undefined;
+  // Non-identity URL material (query/hash/extra path) is not a repository remote.
+  if (parsed.search !== "" || parsed.hash !== "") return undefined;
+  const parts = parsed.pathname.split("/").filter((p) => p.length > 0);
+  if (parts.length !== 2) return undefined;
+  return `${parts[0]}/${stripGitSuffix(parts[1]!)}`;
+}
+
+function stripGitSuffix(name: string): string {
+  return name.toLowerCase().endsWith(".git") ? name.slice(0, -4) : name;
+}