pi-ghwebhook 0.1.0 → 0.2.0

package/schemas/ghwebhook.schema.json

@@ -0,0 +1,225 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://raw.githubusercontent.com/xifan2333/pi-ghwebhook/main/schemas/ghwebhook.schema.json",
+  "title": "Pi GitHub Webhook Workflow Configuration",
+  "description": "GitHub Actions Workflow-compatible event automation configuration for Pi coding agent",
+  "type": "object",
+  "required": ["on", "jobs"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "URL of the JSON schema for validation and autocompletion"
+    },
+    "name": {
+      "type": "string",
+      "description": "Optional display name for this event automation workflow"
+    },
+    "repo": {
+      "type": "string",
+      "default": "auto",
+      "description": "Target GitHub repository in 'owner/repo' format, or 'auto' to detect from git remote"
+    },
+    "secret": {
+      "type": "string",
+      "description": "Optional Webhook HMAC SHA-256 verification secret"
+    },
+    "on": {
+      "description": "GitHub event triggers, matching GitHub Actions 'on' specification",
+      "oneOf": [
+        {
+          "type": "string",
+          "description": "Single GitHub event name, e.g. 'push' or 'workflow_run'"
+        },
+        {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "List of GitHub event names, e.g. ['push', 'pull_request']"
+        },
+        {
+          "type": "object",
+          "description": "Map of event names to their trigger filtering criteria",
+          "properties": {
+            "workflow_run": {
+              "type": "object",
+              "properties": {
+                "types": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["completed", "requested", "in_progress"]
+                  },
+                  "description": "Activity types that trigger the workflow"
+                },
+                "branches": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Branches to filter on (supports '@current' and globs like 'main', 'feat/*')"
+                },
+                "workflows": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Workflow names to filter on (e.g. ['CI'])"
+                }
+              },
+              "additionalProperties": false
+            },
+            "pull_request": {
+              "type": "object",
+              "properties": {
+                "types": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": [
+                      "opened",
+                      "edited",
+                      "closed",
+                      "reopened",
+                      "synchronize",
+                      "ready_for_review"
+                    ]
+                  }
+                },
+                "branches": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              },
+              "additionalProperties": false
+            },
+            "pull_request_review": {
+              "type": "object",
+              "properties": {
+                "types": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["submitted", "edited", "dismissed"]
+                  }
+                },
+                "branches": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              },
+              "additionalProperties": false
+            },
+            "pull_request_review_comment": {
+              "type": "object",
+              "properties": {
+                "types": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["created", "edited", "deleted"]
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            "check_suite": {
+              "type": "object",
+              "properties": {
+                "types": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["completed", "requested", "rerequested"]
+                  }
+                },
+                "branches": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              },
+              "additionalProperties": false
+            },
+            "issues": {
+              "type": "object",
+              "properties": {
+                "types": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": [
+                      "opened",
+                      "edited",
+                      "deleted",
+                      "closed",
+                      "reopened",
+                      "assigned",
+                      "labeled"
+                    ]
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            "issue_comment": {
+              "type": "object",
+              "properties": {
+                "types": {
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": ["created", "edited", "deleted"]
+                  }
+                }
+              },
+              "additionalProperties": false
+            },
+            "push": {
+              "type": "object",
+              "properties": {
+                "branches": {
+                  "type": "array",
+                  "items": { "type": "string" }
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": {
+            "type": "object",
+            "properties": {
+              "types": { "type": "array", "items": { "type": "string" } },
+              "branches": { "type": "array", "items": { "type": "string" } },
+              "workflows": { "type": "array", "items": { "type": "string" } }
+            },
+            "additionalProperties": true
+          }
+        }
+      ]
+    },
+    "jobs": {
+      "type": "object",
+      "description": "Map of jobs to execute when matching events arrive",
+      "additionalProperties": {
+        "type": "object",
+        "required": ["prompt"],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Optional job title"
+          },
+          "if": {
+            "type": "string",
+            "description": "Conditional expression, e.g. \"github.event.workflow_run.conclusion == 'failure'\""
+          },
+          "prompt": {
+            "type": "string",
+            "description": "Prompt template sent to Pi Agent, supporting {{ branch }}, {{ run_url }}, etc."
+          },
+          "deliverAs": {
+            "type": "string",
+            "enum": ["followUp", "steer"],
+            "default": "followUp",
+            "description": "Pi message delivery mode: 'followUp' (wait for agent to finish) or 'steer' (interrupt turn)"
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/skills/setup-ghwebhook/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: setup-ghwebhook
+description: Set up and configure declarative GitHub Webhook automation (.pi/ghwebhook.json) for the current repository. Use when configuring CI/CD event-driven agent triggers, setting up webhook forwarders, or enabling automated CI-fix and PR-review loops in Pi.
+---
+
+# Setup GitHub Webhook Automation
+
+Configure zero-polling, event-driven GitHub Webhook automation for the current repository using the official GitHub Actions Workflow specification (`on` + `jobs`). When events occur (such as CI failures or review submissions), `pi-ghwebhook` intercepts them via a local reverse tunnel and wakes up the agent via `pi.sendUserMessage()` to close the loop automatically.
+
+## Work Loop
+
+Follow these steps in sequence. Do not proceed to the next step until the current step satisfies its completion criterion.
+
+### Step 1: Verify prerequisites and auto-heal
+
+1. Check GitHub CLI installation and authentication:
+   ```bash
+   gh auth status
+   ```
+   If unauthenticated, instruct the human to log in with `gh auth login`.
+2. Check if the official GitHub Webhook extension is installed:
+   ```bash
+   gh extension list
+   ```
+   If `cli/gh-webhook` (or `gh-webhook`) is missing, install it immediately:
+   ```bash
+   gh extension install cli/gh-webhook
+   ```
+3. Verify the current working directory is a Git repository with a GitHub remote:
+   ```bash
+   git remote get-url origin
+   ```
+   Ensure the remote URL points to a GitHub repository (`github.com`).
+
+_Completion criterion_: `gh` is authenticated, `cli/gh-webhook` extension is verified installed, and the repository remote is confirmed on GitHub.
+
+### Step 2: Sense repository context
+
+Inspect the repository to tailor the subscription rules:
+
+1. Discover GitHub Actions workflows under `.github/workflows/`:
+   ```bash
+   ls .github/workflows/*.yml .github/workflows/*.yaml 2>/dev/null || true
+   ```
+   Inspect workflow names (such as `CI`, `Build`, `Test`, `Release`). If an obvious main CI workflow exists, record its name for the `workflows` filter.
+2. Check for AI code review bot integrations:
+   - Check if `.coderabbit.yaml` or `.coderabbit.yml` exists.
+   - Check for Greptile, Copilot, or other review bot configurations.
+
+_Completion criterion_: Identified primary CI workflow name (or determined to match all workflows) and identified whether review bot subscriptions are needed.
+
+### Step 3: Scaffold `.pi/ghwebhook.json`
+
+Write `.pi/ghwebhook.json` in the repository root. Include the `$schema` property for IDE autocompletion and validation:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/xifan2333/pi-ghwebhook/main/schemas/ghwebhook.schema.json",
+  "name": "CI & Review Automation",
+  "on": {
+    "workflow_run": {
+      "types": ["completed"],
+      "branches": ["@current"]
+    },
+    "pull_request_review": {
+      "types": ["submitted"],
+      "branches": ["@current"]
+    }
+  },
+  "jobs": {
+    "ci-failure": {
+      "if": "github.event.workflow_run.conclusion == 'failure'",
+      "prompt": "CI run failed on branch {{ branch }}.\n\nRun URL: {{ run_url }}\nCommit: {{ head_sha }}\n\nPlease run `gh run view {{ run_id }} --log-failed` to diagnose the error and prepare a fix.",
+      "deliverAs": "followUp"
+    },
+    "ci-success": {
+      "if": "github.event.workflow_run.conclusion == 'success'",
+      "prompt": "Remote CI has passed on branch {{ branch }}.\n\nRun URL: {{ run_url }}\n\nPlease check PR checks status and verify if it is ready to merge.",
+      "deliverAs": "followUp"
+    },
+    "review-bot": {
+      "if": "github.event.review.user.type == 'Bot'",
+      "prompt": "Received review comments from {{ sender }}:\n\nState: {{ review_state }}\nDetails:\n{{ review_body }}\n\nPlease evaluate these comments critically: triage true issues to fix, and refute false positives.",
+      "deliverAs": "steer"
+    }
+  }
+}
+```
+
+If specific workflows were identified in Step 2 (e.g. `CI`), add `"workflows": ["CI"]` under `on.workflow_run`.
+
+_Completion criterion_: `.pi/ghwebhook.json` exists in repository root, references `$schema`, is valid JSON, and contains tailored `on` and `jobs`.
+
+### Step 4: Verify and activate
+
+1. If running inside an active interactive Pi session, instruct the user to reload:
+   ```text
+   /reload
+   ```
+2. On session start, `pi-ghwebhook` automatically detects `.pi/ghwebhook.json`, binds an ephemeral local port on `127.0.0.1:0`, spawns `gh webhook forward --events=*`, and displays an info notification in TUI.
+
+_Completion criterion_: Explained activation method to the user and confirmed configuration ready for incoming events.
+
+---
+
+## Reference
+
+### Schema and Autocompletion
+
+Add `$schema` at the top of `.pi/ghwebhook.json`:
+
+```json
+"$schema": "https://raw.githubusercontent.com/xifan2333/pi-ghwebhook/main/schemas/ghwebhook.schema.json"
+```
+
+### Supported Trigger Keys under `on.<event>`
+
+- `types`: Activity types filtering `payload.action` (e.g. `["completed"]`, `["submitted"]`, `["opened"]`).
+- `branches`: Branches filter supporting `@current` and globs (e.g. `["@current", "main", "feat/*"]`).
+- `workflows`: Workflow names filter (e.g. `["CI"]`).
+
+### Conditions under `jobs.<job_id>.if`
+
+Supports standard comparison expressions without arbitrary code execution:
+
+- `github.event.workflow_run.conclusion == 'failure'`
+- `github.event.workflow_run.conclusion == 'success'`
+- `github.event.review.user.type == 'Bot'`
+- `github.event.sender.login == 'coderabbitai[bot]'`
+- Glob matching: `github.event.sender.login == '*[bot]'`
+
+### Template Variables
+
+- `{{ branch }}`: Current head branch.
+- `{{ head_sha }}`: Commit SHA.
+- `{{ commit_message }}`: Head commit message.
+- `{{ repo }}`: Repository full name (`owner/repo`).
+- `{{ repo_url }}`: Repository HTML URL.
+- `{{ run_id }}`: Workflow run ID.
+- `{{ run_url }}`: Workflow run HTML URL.
+- `{{ workflow }}`: Workflow name.
+- `{{ conclusion }}`: Workflow conclusion.
+- `{{ pr_number }}`: Pull request number.
+- `{{ pr_title }}`: Pull request title.
+- `{{ pr_url }}`: Pull request HTML URL.
+- `{{ review_state }}`: Review state (`approved`, `changes_requested`, `commented`).
+- `{{ review_body }}`: Review body text.
+- `{{ sender }}`: Actor username or bot login.
+- `{{ action }}`: Raw event action string.

package/skills/setup-ghwebhook/assets/default-config.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://raw.githubusercontent.com/xifan2333/pi-ghwebhook/main/schemas/ghwebhook.schema.json",
+  "name": "CI & Review Automation",
+  "on": {
+    "workflow_run": {
+      "types": ["completed"],
+      "branches": ["@current"]
+    },
+    "pull_request_review": {
+      "types": ["submitted"],
+      "branches": ["@current"]
+    }
+  },
+  "jobs": {
+    "ci-failure": {
+      "if": "github.event.workflow_run.conclusion == 'failure'",
+      "prompt": "CI run failed on branch {{ branch }}.\n\nRun URL: {{ run_url }}\nCommit: {{ head_sha }}\n\nPlease run `gh run view {{ run_id }} --log-failed` to diagnose the error and prepare a fix.",
+      "deliverAs": "followUp"
+    },
+    "ci-success": {
+      "if": "github.event.workflow_run.conclusion == 'success'",
+      "prompt": "Remote CI has passed on branch {{ branch }}.\n\nRun URL: {{ run_url }}\n\nPlease check PR checks status and verify if it is ready to merge.",
+      "deliverAs": "followUp"
+    },
+    "review-bot": {
+      "if": "github.event.review.user.type == 'Bot'",
+      "prompt": "Received review comments from {{ sender }}:\n\nState: {{ review_state }}\nDetails:\n{{ review_body }}\n\nPlease evaluate these comments critically: triage true issues to fix, and refute false positives.",
+      "deliverAs": "steer"
+    }
+  }
+}

package/src/bus/event-bus.ts

@@ -1,70 +1,62 @@
-import type { SubscriptionRule } from "../types/schema.js";
+import type { GhWebhookWorkflow, EventTriggerConfig } from "../types/schema.js";
 import type { WebhookPayload } from "../types/payload.js";
-import { evaluateGuards } from "./guards.js";
-import { normalizeEventKey, resolveIncomingEventKeys } from "./normalizer.js";
+import { isTriggerMatched, evaluateCondition } from "./matcher.js";
 import { extractVariables, renderTemplate } from "../template/renderer.js";
 
 export interface ActionPlan {
   prompt: string;
   deliverAs: "steer" | "followUp";
-  event: string;
+  jobId: string;
 }
 
 export class WebhookEventBus {
-  private readonly routes = new Map<string, SubscriptionRule[]>();
+  constructor(private readonly workflow: GhWebhookWorkflow) {}
 
-  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);
+  private getTriggerForEvent(
+    incomingEvent: string,
+  ): EventTriggerConfig | null | undefined {
+    const on = this.workflow.on;
+    if (typeof on === "string") {
+      return on === incomingEvent ? null : undefined;
     }
-  }
-
-  getEvents(): string[] {
-    return Array.from(this.routes.keys());
+    if (Array.isArray(on)) {
+      return on.includes(incomingEvent) ? null : undefined;
+    }
+    if (typeof on === "object" && on !== null) {
+      if (Object.prototype.hasOwnProperty.call(on, incomingEvent)) {
+        return on[incomingEvent] as EventTriggerConfig | null;
+      }
+    }
+    return undefined;
   }
 
   dispatch(
-    event: string,
+    incomingEvent: 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);
-        }
-      }
+    const trigger = this.getTriggerForEvent(incomingEvent);
+    if (trigger === undefined) {
+      return [];
     }
 
-    if (matchedRules.length === 0) {
+    if (!isTriggerMatched(trigger, payload, currentBranch)) {
       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,
-        });
+    for (const [jobId, job] of Object.entries(this.workflow.jobs)) {
+      if (!evaluateCondition(job.if, payload, currentBranch)) {
+        continue;
       }
+
+      plans.push({
+        prompt: renderTemplate(job.prompt, vars),
+        deliverAs: job.deliverAs ?? "followUp",
+        jobId,
+      });
     }
 
     return plans;

package/src/bus/matcher.ts

@@ -0,0 +1,164 @@
+import type { WebhookPayload } from "../types/payload.js";
+import type { EventTriggerConfig } from "../types/schema.js";
+
+export function globMatch(pattern: string, text: string): boolean {
+  if (pattern === text || pattern === "*") return true;
+  const escaped = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, ".*")
+    .replace(/\*/g, ".*");
+  const regex = new RegExp(`^${escaped}$`);
+  return regex.test(text);
+}
+
+export 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 matchBranches(
+  branches: string[],
+  actualBranch: string,
+  currentBranch: string,
+): boolean {
+  for (const pattern of branches) {
+    if (pattern === "@current" && actualBranch === currentBranch) {
+      return true;
+    }
+    if (globMatch(pattern, actualBranch)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function matchTypes(types: string[] | undefined, action: unknown): boolean {
+  if (!Array.isArray(types) || types.length === 0) return true;
+  const actionStr = typeof action === "string" ? action : "";
+  return types.includes(actionStr);
+}
+
+function matchBranchFilter(
+  branches: string[] | undefined,
+  payload: WebhookPayload,
+  currentBranch: string,
+): boolean {
+  if (!Array.isArray(branches) || branches.length === 0) return true;
+  const actualBranch = resolvePayloadBranch(payload);
+  return Boolean(
+    actualBranch && matchBranches(branches, actualBranch, currentBranch),
+  );
+}
+
+function matchWorkflows(
+  workflows: string[] | undefined,
+  payload: WebhookPayload,
+): boolean {
+  if (!Array.isArray(workflows) || workflows.length === 0) return true;
+  const workflowName =
+    payload.workflow_run?.name ?? payload.workflow_job?.workflow_name ?? "";
+  return workflows.some((w) => globMatch(w, workflowName));
+}
+
+export function isTriggerMatched(
+  trigger: EventTriggerConfig | null | undefined,
+  payload: WebhookPayload,
+  currentBranch: string,
+): boolean {
+  if (!trigger) return true;
+  return (
+    matchTypes(trigger.types, payload.action) &&
+    matchBranchFilter(trigger.branches, payload, currentBranch) &&
+    matchWorkflows(trigger.workflows, payload)
+  );
+}
+
+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;
+}
+
+function resolveContextValue(
+  path: string,
+  payload: WebhookPayload,
+  currentBranch: string,
+): unknown {
+  const cleanPath = path
+    .replace(/^github\.event\./, "")
+    .replace(/^event\./, "")
+    .trim();
+
+  // Special shortcuts
+  if (cleanPath === "branch")
+    return resolvePayloadBranch(payload) ?? currentBranch;
+  if (cleanPath === "conclusion")
+    return payload.workflow_run?.conclusion ?? payload.check_suite?.conclusion;
+  if (cleanPath === "sender")
+    return payload.sender?.login ?? payload.review?.user?.login;
+  if (cleanPath === "isBot") {
+    const senderType = payload.review?.user?.type ?? payload.sender?.type;
+    const login = payload.review?.user?.login ?? payload.sender?.login ?? "";
+    return senderType === "Bot" || login.endsWith("[bot]");
+  }
+
+  return getNestedValue(payload, cleanPath);
+}
+
+function parseLiteral(literal: string): string | number | boolean | null {
+  const trimmed = literal.trim();
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "null") return null;
+  if (/^['"].*['"]$/.test(trimmed)) {
+    return trimmed.slice(1, -1);
+  }
+  const num = Number(trimmed);
+  if (!Number.isNaN(num)) return num;
+  return trimmed;
+}
+
+export function evaluateCondition(
+  expr: string | undefined,
+  payload: WebhookPayload,
+  currentBranch: string,
+): boolean {
+  if (!expr || !expr.trim()) return true;
+
+  const match = expr.match(/^(.+?)\s*(===|!==|==|!=)\s*(.+)$/);
+  if (!match) {
+    const val = resolveContextValue(expr.trim(), payload, currentBranch);
+    return Boolean(val);
+  }
+
+  const [, leftRaw, op, rightRaw] = match;
+  const leftVal = resolveContextValue(leftRaw.trim(), payload, currentBranch);
+  const rightVal = parseLiteral(rightRaw.trim());
+
+  const isEqualOp = op === "==" || op === "===";
+
+  if (
+    typeof rightVal === "string" &&
+    typeof leftVal === "string" &&
+    rightVal.includes("*")
+  ) {
+    const matchesGlob = globMatch(rightVal, leftVal);
+    return isEqualOp ? matchesGlob : !matchesGlob;
+  }
+
+  const areEqual = leftVal === rightVal;
+  return isEqualOp ? areEqual : !areEqual;
+}