pi-ghwebhook 0.0.0-stage → 0.1.0

package/dist/types/payload.d.ts

@@ -0,0 +1,28 @@
+import type { components } from "@octokit/openapi-webhooks-types";
+export type WebhookSchemas = components["schemas"];
+export type WorkflowRunCompletedPayload = WebhookSchemas["webhook-workflow-run-completed"];
+export type WorkflowRunInProgressPayload = WebhookSchemas["webhook-workflow-run-in-progress"];
+export type WorkflowRunRequestedPayload = WebhookSchemas["webhook-workflow-run-requested"];
+export type WorkflowRunPayload = WorkflowRunCompletedPayload | WorkflowRunInProgressPayload | WorkflowRunRequestedPayload;
+export type PullRequestReviewSubmittedPayload = WebhookSchemas["webhook-pull-request-review-submitted"];
+export type PullRequestReviewEditedPayload = WebhookSchemas["webhook-pull-request-review-edited"];
+export type PullRequestReviewDismissedPayload = WebhookSchemas["webhook-pull-request-review-dismissed"];
+export type PullRequestReviewPayload = PullRequestReviewSubmittedPayload | PullRequestReviewEditedPayload | PullRequestReviewDismissedPayload;
+export type PullRequestReviewCommentCreatedPayload = WebhookSchemas["webhook-pull-request-review-comment-created"];
+export type PullRequestReviewCommentEditedPayload = WebhookSchemas["webhook-pull-request-review-comment-edited"];
+export type PullRequestReviewCommentDeletedPayload = WebhookSchemas["webhook-pull-request-review-comment-deleted"];
+export type PullRequestReviewCommentPayload = PullRequestReviewCommentCreatedPayload | PullRequestReviewCommentEditedPayload | PullRequestReviewCommentDeletedPayload;
+export type CheckSuiteCompletedPayload = WebhookSchemas["webhook-check-suite-completed"];
+export type CheckSuiteRequestedPayload = WebhookSchemas["webhook-check-suite-requested"];
+export type CheckSuiteRerequestedPayload = WebhookSchemas["webhook-check-suite-rerequested"];
+export type CheckSuitePayload = CheckSuiteCompletedPayload | CheckSuiteRequestedPayload | CheckSuiteRerequestedPayload;
+export type IssueCommentCreatedPayload = WebhookSchemas["webhook-issue-comment-created"];
+export type IssueCommentEditedPayload = WebhookSchemas["webhook-issue-comment-edited"];
+export type IssueCommentDeletedPayload = WebhookSchemas["webhook-issue-comment-deleted"];
+export type IssueCommentPayload = IssueCommentCreatedPayload | IssueCommentEditedPayload | IssueCommentDeletedPayload;
+export type SupportedWebhookPayload = WorkflowRunPayload | PullRequestReviewPayload | PullRequestReviewCommentPayload | CheckSuitePayload | IssueCommentPayload;
+/**
+ * Fallback generic webhook payload structure for unknown or untyped events.
+ */
+export type WebhookPayload = Record<string, any>;
+//# sourceMappingURL=payload.d.ts.map

package/dist/types/payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.d.ts","sourceRoot":"","sources":["../../src/types/payload.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAElE,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,SAAS,CAAC,CAAC;AAGnD,MAAM,MAAM,2BAA2B,GACrC,cAAc,CAAC,gCAAgC,CAAC,CAAC;AACnD,MAAM,MAAM,4BAA4B,GACtC,cAAc,CAAC,kCAAkC,CAAC,CAAC;AACrD,MAAM,MAAM,2BAA2B,GACrC,cAAc,CAAC,gCAAgC,CAAC,CAAC;AACnD,MAAM,MAAM,kBAAkB,GAC1B,2BAA2B,GAC3B,4BAA4B,GAC5B,2BAA2B,CAAC;AAGhC,MAAM,MAAM,iCAAiC,GAC3C,cAAc,CAAC,uCAAuC,CAAC,CAAC;AAC1D,MAAM,MAAM,8BAA8B,GACxC,cAAc,CAAC,oCAAoC,CAAC,CAAC;AACvD,MAAM,MAAM,iCAAiC,GAC3C,cAAc,CAAC,uCAAuC,CAAC,CAAC;AAC1D,MAAM,MAAM,wBAAwB,GAChC,iCAAiC,GACjC,8BAA8B,GAC9B,iCAAiC,CAAC;AAGtC,MAAM,MAAM,sCAAsC,GAChD,cAAc,CAAC,6CAA6C,CAAC,CAAC;AAChE,MAAM,MAAM,qCAAqC,GAC/C,cAAc,CAAC,4CAA4C,CAAC,CAAC;AAC/D,MAAM,MAAM,sCAAsC,GAChD,cAAc,CAAC,6CAA6C,CAAC,CAAC;AAChE,MAAM,MAAM,+BAA+B,GACvC,sCAAsC,GACtC,qCAAqC,GACrC,sCAAsC,CAAC;AAG3C,MAAM,MAAM,0BAA0B,GACpC,cAAc,CAAC,+BAA+B,CAAC,CAAC;AAClD,MAAM,MAAM,0BAA0B,GACpC,cAAc,CAAC,+BAA+B,CAAC,CAAC;AAClD,MAAM,MAAM,4BAA4B,GACtC,cAAc,CAAC,iCAAiC,CAAC,CAAC;AACpD,MAAM,MAAM,iBAAiB,GACzB,0BAA0B,GAC1B,0BAA0B,GAC1B,4BAA4B,CAAC;AAGjC,MAAM,MAAM,0BAA0B,GACpC,cAAc,CAAC,+BAA+B,CAAC,CAAC;AAClD,MAAM,MAAM,yBAAyB,GACnC,cAAc,CAAC,8BAA8B,CAAC,CAAC;AACjD,MAAM,MAAM,0BAA0B,GACpC,cAAc,CAAC,+BAA+B,CAAC,CAAC;AAClD,MAAM,MAAM,mBAAmB,GAC3B,0BAA0B,GAC1B,yBAAyB,GACzB,0BAA0B,CAAC;AAE/B,MAAM,MAAM,uBAAuB,GAC/B,kBAAkB,GAClB,wBAAwB,GACxB,+BAA+B,GAC/B,iBAAiB,GACjB,mBAAmB,CAAC;AAExB;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC"}

package/dist/types/payload.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=payload.js.map

package/dist/types/payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../src/types/payload.ts"],"names":[],"mappings":""}

package/dist/types/schema.d.ts

@@ -0,0 +1,59 @@
+import { Type, type Static } from "typebox";
+export declare const FilterSchema: Type.TObject<{
+    branch: Type.TOptional<Type.TString>;
+    conclusion: Type.TOptional<Type.TString>;
+    workflow: Type.TOptional<Type.TString>;
+    state: Type.TOptional<Type.TString>;
+    senders: Type.TOptional<Type.TArray<Type.TString>>;
+    isBot: Type.TOptional<Type.TBoolean>;
+    match: Type.TOptional<Type.TRecord<"^.*$", Type.TUnion<[Type.TString, Type.TNumber, Type.TBoolean]>>>;
+}>;
+export type FilterConfig = Static<typeof FilterSchema>;
+export declare const ActionSchema: Type.TObject<{
+    prompt: Type.TString;
+    deliverAs: Type.TOptional<Type.TUnion<[Type.TLiteral<"steer">, Type.TLiteral<"followUp">]>>;
+}>;
+export type ActionConfig = Static<typeof ActionSchema>;
+export declare const SubscriptionRuleSchema: Type.TObject<{
+    event: Type.TOptional<Type.TString>;
+    topic: Type.TOptional<Type.TString>;
+    filters: Type.TOptional<Type.TObject<{
+        branch: Type.TOptional<Type.TString>;
+        conclusion: Type.TOptional<Type.TString>;
+        workflow: Type.TOptional<Type.TString>;
+        state: Type.TOptional<Type.TString>;
+        senders: Type.TOptional<Type.TArray<Type.TString>>;
+        isBot: Type.TOptional<Type.TBoolean>;
+        match: Type.TOptional<Type.TRecord<"^.*$", Type.TUnion<[Type.TString, Type.TNumber, Type.TBoolean]>>>;
+    }>>;
+    action: Type.TObject<{
+        prompt: Type.TString;
+        deliverAs: Type.TOptional<Type.TUnion<[Type.TLiteral<"steer">, Type.TLiteral<"followUp">]>>;
+    }>;
+}>;
+export type SubscriptionRule = Static<typeof SubscriptionRuleSchema>;
+export declare const ConfigSchema: Type.TObject<{
+    version: Type.TLiteral<1>;
+    enabled: Type.TBoolean;
+    repo: Type.TOptional<Type.TString>;
+    secret: Type.TOptional<Type.TString>;
+    subscriptions: Type.TArray<Type.TObject<{
+        event: Type.TOptional<Type.TString>;
+        topic: Type.TOptional<Type.TString>;
+        filters: Type.TOptional<Type.TObject<{
+            branch: Type.TOptional<Type.TString>;
+            conclusion: Type.TOptional<Type.TString>;
+            workflow: Type.TOptional<Type.TString>;
+            state: Type.TOptional<Type.TString>;
+            senders: Type.TOptional<Type.TArray<Type.TString>>;
+            isBot: Type.TOptional<Type.TBoolean>;
+            match: Type.TOptional<Type.TRecord<"^.*$", Type.TUnion<[Type.TString, Type.TNumber, Type.TBoolean]>>>;
+        }>>;
+        action: Type.TObject<{
+            prompt: Type.TString;
+            deliverAs: Type.TOptional<Type.TUnion<[Type.TLiteral<"steer">, Type.TLiteral<"followUp">]>>;
+        }>;
+    }>>;
+}>;
+export type GhWebhookConfig = Static<typeof ConfigSchema>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/types/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/types/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,KAAK,MAAM,EAAE,MAAM,SAAS,CAAC;AAE5C,eAAO,MAAM,YAAY;;;;;;;;EAuCxB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEvD,eAAO,MAAM,YAAY;;;EAaxB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAEvD,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;EAkBlC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAErE,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;EAkBxB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC"}

package/dist/types/schema.js

@@ -0,0 +1,49 @@
+import { Type } from "typebox";
+export const FilterSchema = Type.Object({
+    branch: Type.Optional(Type.String({ description: "Target branch name or '@current'" })),
+    conclusion: Type.Optional(Type.String({
+        description: "Conclusion filter (e.g. 'failure', 'success')",
+    })),
+    workflow: Type.Optional(Type.String({ description: "Workflow name filter (e.g. 'CI')" })),
+    state: Type.Optional(Type.String({
+        description: "Review or PR state filter (e.g. 'changes_requested', 'approved')",
+    })),
+    senders: Type.Optional(Type.Array(Type.String(), { description: "Allowed sender logins" })),
+    isBot: Type.Optional(Type.Boolean({
+        description: "Filter for bot (true) or human (false) senders",
+    })),
+    match: Type.Optional(Type.Record(Type.String(), Type.Union([Type.String(), Type.Number(), Type.Boolean()]), {
+        description: "Arbitrary field matching on payload (dot-separated path)",
+    })),
+}, { additionalProperties: false });
+export const ActionSchema = Type.Object({
+    prompt: Type.String({
+        description: "Template string to dispatch to agent",
+    }),
+    deliverAs: Type.Optional(Type.Union([Type.Literal("steer"), Type.Literal("followUp")], {
+        description: "Delivery urgency: steer interrupts turn, followUp queues next",
+    })),
+}, { additionalProperties: false });
+export const SubscriptionRuleSchema = Type.Object({
+    event: Type.Optional(Type.String({
+        description: "Upstream GitHub Webhook event identifier (e.g. 'workflow_run.completed', 'push', 'issues.opened')",
+    })),
+    topic: Type.Optional(Type.String({
+        description: "Alias for 'event' (e.g. 'workflow_run.completed' or 'github.workflow_run.completed')",
+    })),
+    filters: Type.Optional(FilterSchema),
+    action: ActionSchema,
+}, { additionalProperties: false });
+export const ConfigSchema = Type.Object({
+    version: Type.Literal(1, { description: "Schema version" }),
+    enabled: Type.Boolean({ default: true }),
+    repo: Type.Optional(Type.String({
+        default: "auto",
+        description: "Target GitHub repo (owner/repo or 'auto')",
+    })),
+    secret: Type.Optional(Type.String({ description: "Optional Webhook HMAC secret" })),
+    subscriptions: Type.Array(SubscriptionRuleSchema, {
+        description: "List of declarative webhook event subscriptions",
+    }),
+}, { additionalProperties: false });
+//# sourceMappingURL=schema.js.map

package/dist/types/schema.js.map

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

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "pi-ghwebhook",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Universal GitHub Webhook event bus and wake-up engine for Pi coding agent",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "pi-extension",
+    "extension",
+    "github",
+    "webhook",
+    "event-bus",
+    "automation"
+  ],
+  "homepage": "https://github.com/xifan2333/pi-ghwebhook#readme",
+  "bugs": {
+    "url": "https://github.com/xifan2333/pi-ghwebhook/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xifan2333/pi-ghwebhook.git"
+  },
+  "license": "MIT",
+  "author": "xifan",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "README_zh.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "check": "mise run check",
+    "prepublishOnly": "npm run check && npm test",
+    "test": "mise run test"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.5.0",
+    "@octokit/openapi-webhooks-types": "^12.2.0",
+    "@types/node": "^22.13.0",
+    "typebox": "^1.3.27",
+    "typescript": "^5.8.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  }
+}

package/src/bus/event-bus.ts

@@ -0,0 +1,72 @@
+import type { SubscriptionRule } from "../types/schema.js";
+import type { WebhookPayload } from "../types/payload.js";
+import { evaluateGuards } from "./guards.js";
+import { normalizeEventKey, resolveIncomingEventKeys } from "./normalizer.js";
+import { extractVariables, renderTemplate } from "../template/renderer.js";
+
+export interface ActionPlan {
+  prompt: string;
+  deliverAs: "steer" | "followUp";
+  event: string;
+}
+
+export class WebhookEventBus {
+  private readonly routes = new Map<string, SubscriptionRule[]>();
+
+  constructor(rules: SubscriptionRule[]) {
+    for (const rule of rules) {
+      const rawKey = rule.event ?? rule.topic;
+      if (!rawKey) continue;
+      const normalizedKey = normalizeEventKey(rawKey);
+
+      const existing = this.routes.get(normalizedKey) ?? [];
+      existing.push(rule);
+      this.routes.set(normalizedKey, existing);
+    }
+  }
+
+  getEvents(): string[] {
+    return Array.from(this.routes.keys());
+  }
+
+  dispatch(
+    event: string,
+    payload: WebhookPayload,
+    currentBranch: string,
+  ): ActionPlan[] {
+    const candidateKeys = resolveIncomingEventKeys(event, payload);
+    const seenRules = new Set<SubscriptionRule>();
+    const matchedRules: SubscriptionRule[] = [];
+
+    for (const key of candidateKeys) {
+      const rules = this.routes.get(key);
+      if (!rules) continue;
+      for (const rule of rules) {
+        if (!seenRules.has(rule)) {
+          seenRules.add(rule);
+          matchedRules.push(rule);
+        }
+      }
+    }
+
+    if (matchedRules.length === 0) {
+      return [];
+    }
+
+    const ctx = { currentBranch, payload };
+    const vars = extractVariables(payload, currentBranch);
+    const plans: ActionPlan[] = [];
+
+    for (const rule of matchedRules) {
+      if (evaluateGuards(rule.filters, ctx)) {
+        plans.push({
+          prompt: renderTemplate(rule.action.prompt, vars),
+          deliverAs: rule.action.deliverAs ?? "followUp",
+          event: rule.event ?? rule.topic ?? event,
+        });
+      }
+    }
+
+    return plans;
+  }
+}

package/src/bus/guards.ts

@@ -0,0 +1,118 @@
+import type { WebhookPayload } from "../types/payload.js";
+import type { FilterConfig } from "../types/schema.js";
+
+export interface FilterContext {
+  currentBranch: string;
+  payload: WebhookPayload;
+}
+
+export type GuardPredicate = (
+  expectedValue: unknown,
+  ctx: FilterContext,
+) => boolean;
+
+function resolvePayloadBranch(payload: WebhookPayload): string | undefined {
+  return (
+    payload.workflow_run?.head_branch ??
+    payload.pull_request?.head?.ref ??
+    payload.check_suite?.head_branch ??
+    payload.workflow_job?.head_branch ??
+    (typeof payload.ref === "string"
+      ? payload.ref.replace("refs/heads/", "")
+      : undefined)
+  );
+}
+
+function resolvePayloadSender(payload: WebhookPayload): string | undefined {
+  return (
+    payload.sender?.login ??
+    payload.review?.user?.login ??
+    payload.comment?.user?.login
+  );
+}
+
+function getNestedValue(obj: Record<string, any>, path: string): unknown {
+  const parts = path.split(".");
+  let current: any = obj;
+  for (const part of parts) {
+    if (current == null || typeof current !== "object") return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+const branchGuard: GuardPredicate = (expected, { currentBranch, payload }) => {
+  const target = expected === "@current" ? currentBranch : expected;
+  const actualBranch = resolvePayloadBranch(payload);
+  return typeof target === "string" && actualBranch === target;
+};
+
+const conclusionGuard: GuardPredicate = (expected, { payload }) => {
+  const actual =
+    payload.workflow_run?.conclusion ??
+    payload.check_suite?.conclusion ??
+    payload.workflow_job?.conclusion;
+  return typeof expected === "string" && actual === expected;
+};
+
+const workflowGuard: GuardPredicate = (expected, { payload }) => {
+  const workflowName =
+    payload.workflow_run?.name ?? payload.workflow_job?.workflow_name;
+  return typeof expected === "string" && workflowName === expected;
+};
+
+const stateGuard: GuardPredicate = (expected, { payload }) => {
+  const actual = payload.review?.state ?? payload.pull_request?.state;
+  return typeof expected === "string" && actual === expected;
+};
+
+const sendersGuard: GuardPredicate = (allowedList, { payload }) => {
+  if (!Array.isArray(allowedList)) return true;
+  const sender = resolvePayloadSender(payload);
+  return typeof sender === "string" && allowedList.includes(sender);
+};
+
+const isBotGuard: GuardPredicate = (expected, { payload }) => {
+  const senderType = payload.review?.user?.type ?? payload.sender?.type;
+  const login = payload.review?.user?.login ?? payload.sender?.login ?? "";
+  const isBot = senderType === "Bot" || login.endsWith("[bot]");
+  return isBot === Boolean(expected);
+};
+
+const matchGuard: GuardPredicate = (matchObj, { payload }) => {
+  if (!matchObj || typeof matchObj !== "object") return true;
+  for (const [path, expected] of Object.entries(
+    matchObj as Record<string, unknown>,
+  )) {
+    const actual = getNestedValue(payload, path);
+    if (actual !== expected) return false;
+  }
+  return true;
+};
+
+export const GUARDS: ReadonlyMap<keyof FilterConfig, GuardPredicate> = new Map([
+  ["branch", branchGuard],
+  ["conclusion", conclusionGuard],
+  ["workflow", workflowGuard],
+  ["state", stateGuard],
+  ["senders", sendersGuard],
+  ["isBot", isBotGuard],
+  ["match", matchGuard],
+]);
+
+export function evaluateGuards(
+  filters: FilterConfig | undefined,
+  ctx: FilterContext,
+): boolean {
+  if (!filters) return true;
+
+  for (const [key, value] of Object.entries(filters)) {
+    if (value === undefined) continue;
+    const guard = GUARDS.get(key as keyof FilterConfig);
+    if (guard && !guard(value, ctx)) {
+      return false;
+    }
+  }
+
+  return true;
+}

package/src/bus/normalizer.ts

@@ -0,0 +1,32 @@
+import type { WebhookPayload } from "../types/payload.js";
+
+/**
+ * Normalizes an event identifier by stripping optional "github." prefix.
+ * e.g. "github.workflow_run.completed" -> "workflow_run.completed"
+ */
+export function normalizeEventKey(key: string): string {
+  const trimmed = key.trim();
+  return trimmed.startsWith("github.") ? trimmed.slice(7) : trimmed;
+}
+
+/**
+ * Resolves candidate event keys from an incoming GitHub Webhook event and payload.
+ * Upstream convention:
+ * 1. If payload has action: `${event}.${action}` (e.g. "workflow_run.completed", "pull_request.opened")
+ * 2. Wildcard/base event: `${event}` (e.g. "workflow_run", "push", "issues")
+ */
+export function resolveIncomingEventKeys(
+  event: string,
+  payload: WebhookPayload,
+): string[] {
+  const normalizedEvent = normalizeEventKey(event);
+  const action =
+    typeof payload.action === "string" ? payload.action.trim() : undefined;
+
+  const keys: string[] = [];
+  if (action) {
+    keys.push(`${normalizedEvent}.${action}`);
+  }
+  keys.push(normalizedEvent);
+  return keys;
+}

package/src/config/loader.ts

@@ -0,0 +1,80 @@
+import { readFile, access } from "node:fs/promises";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { GhWebhookConfig } from "../types/schema.js";
+
+const execFileAsync = promisify(execFile);
+
+const CONFIG_CANDIDATES = [
+  ".pi/ghwebhook.json",
+  ".agents/ghwebhook.json",
+  "ghwebhook.json",
+];
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function loadProjectConfig(
+  cwd: string,
+): Promise<GhWebhookConfig | null> {
+  for (const relPath of CONFIG_CANDIDATES) {
+    const fullPath = join(cwd, relPath);
+    if (await fileExists(fullPath)) {
+      try {
+        const content = await readFile(fullPath, "utf8");
+        const parsed = JSON.parse(content) as GhWebhookConfig;
+        if (parsed && typeof parsed === "object" && parsed.version === 1) {
+          return parsed;
+        }
+      } catch (err) {
+        console.error(
+          `[pi-ghwebhook] Failed to load config from ${fullPath}:`,
+          err,
+        );
+      }
+    }
+  }
+  return null;
+}
+
+export async function resolveGitBranch(cwd: string): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["rev-parse", "--abbrev-ref", "HEAD"],
+      { cwd },
+    );
+    return stdout.trim();
+  } catch {
+    return "main";
+  }
+}
+
+export function parseGitHubRepo(remoteUrl: string): string | null {
+  const normalized = remoteUrl.trim();
+  const match = normalized.match(
+    /github\.com[:/]([a-zA-Z0-9_.-]+)\/([a-zA-Z0-9_.-]+?)(?:\.git)?$/i,
+  );
+  if (!match) return null;
+  return `${match[1]}/${match[2]}`;
+}
+
+export async function resolveGitRepo(cwd: string): Promise<string | null> {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      ["remote", "get-url", "origin"],
+      { cwd },
+    );
+    return parseGitHubRepo(stdout);
+  } catch {
+    return null;
+  }
+}

package/src/index.ts

@@ -0,0 +1,106 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  loadProjectConfig,
+  resolveGitBranch,
+  resolveGitRepo,
+} from "./config/loader.js";
+import { WebhookEventBus } from "./bus/event-bus.js";
+import { LoopbackServer } from "./transport/loopback.js";
+import { GhForwarder } from "./transport/forwarder.js";
+
+export default function ghWebhookExtension(pi: ExtensionAPI): void {
+  let loopback: LoopbackServer | null = null;
+  let forwarder: GhForwarder | null = null;
+
+  const cleanup = async () => {
+    if (forwarder) {
+      forwarder.stop();
+      forwarder = null;
+    }
+    if (loopback) {
+      await loopback.stop();
+      loopback = null;
+    }
+  };
+
+  process.once("exit", () => {
+    if (forwarder) forwarder.stop();
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    // 1. 工作区探测：若当前项目无 .pi/ghwebhook.json，则静默休眠，零资源占用
+    const config = await loadProjectConfig(ctx.cwd);
+    if (!config || !config.enabled) {
+      return;
+    }
+
+    // 2. 解析当前 Git 分支与远端仓库
+    const currentBranch = await resolveGitBranch(ctx.cwd);
+    const repo =
+      config.repo && config.repo !== "auto"
+        ? config.repo
+        : await resolveGitRepo(ctx.cwd);
+
+    if (!repo) {
+      if (ctx.hasUI) {
+        ctx.ui.notify(
+          "[pi-ghwebhook] 未能检测到当前项目的 GitHub 仓库 (owner/repo)，请在配置中显式指定 'repo' 字段。",
+          "warning",
+        );
+      }
+      return;
+    }
+
+    // 3. 构建表驱动事件总线
+    const bus = new WebhookEventBus(config.subscriptions);
+
+    // 4. 启动随机端口本地回环服务器
+    loopback = new LoopbackServer({
+      secret: config.secret,
+      onEvent: async (event, payload) => {
+        const plans = bus.dispatch(event, payload, currentBranch);
+        for (const plan of plans) {
+          pi.sendUserMessage(plan.prompt, {
+            deliverAs: plan.deliverAs,
+          });
+        }
+      },
+    });
+
+    try {
+      await loopback.start();
+    } catch (err) {
+      console.error("[pi-ghwebhook] 无法启动回环服务:", err);
+      if (ctx.hasUI) {
+        ctx.ui.notify(
+          "[pi-ghwebhook] 无法启动回环服务，事件流未能挂载",
+          "error",
+        );
+      }
+      return;
+    }
+
+    // 5. 托管 gh webhook forward 长连接子进程（默认全量监听 --events=*）
+    forwarder = new GhForwarder({
+      repo,
+      url: loopback.getUrl(),
+      secret: config.secret,
+      onError: (err) => {
+        console.error("[pi-ghwebhook] gh forwarder error:", err);
+      },
+    });
+
+    forwarder.start();
+
+    if (ctx.hasUI) {
+      ctx.ui.notify(
+        `[pi-ghwebhook] 已监听 ${repo} (${currentBranch}) GitHub 事件流 (端口: ${loopback.getPort()})`,
+        "info",
+      );
+    }
+  });
+
+  pi.on("session_shutdown", async () => {
+    await cleanup();
+  });
+}