pi-ghwebhook 0.0.0-stage → 0.1.0

package/src/template/renderer.ts

@@ -0,0 +1,145 @@
+import type { WebhookPayload } from "../types/payload.js";
+
+const VARIABLE_PATTERN = /\{\{\s*([a-zA-Z0-9_]+)\s*\}\}/g;
+
+function extractRepoVars(
+  payload: WebhookPayload,
+  vars: Record<string, string>,
+): void {
+  if (payload.repository?.full_name) {
+    vars.repo = String(payload.repository.full_name);
+    vars.repo_url = String(payload.repository.html_url ?? "");
+  }
+}
+
+function extractBranchVars(
+  payload: WebhookPayload,
+  vars: Record<string, string>,
+  fallbackBranch: string,
+): void {
+  const branch =
+    payload.workflow_run?.head_branch ??
+    payload.pull_request?.head?.ref ??
+    payload.check_suite?.head_branch ??
+    payload.workflow_job?.head_branch ??
+    fallbackBranch;
+  if (branch) vars.branch = String(branch);
+
+  const headSha =
+    payload.workflow_run?.head_sha ??
+    payload.pull_request?.head?.sha ??
+    payload.check_suite?.head_sha ??
+    payload.after ??
+    payload.head_commit?.id;
+  if (headSha) vars.head_sha = String(headSha);
+
+  if (payload.head_commit?.message) {
+    vars.commit_message = String(payload.head_commit.message);
+  }
+}
+
+function extractWorkflowVars(
+  payload: WebhookPayload,
+  vars: Record<string, string>,
+): void {
+  const wf = payload.workflow_run;
+  if (!wf) return;
+  if (wf.id != null) vars.run_id = String(wf.id);
+  if (wf.html_url) vars.run_url = String(wf.html_url);
+  if (wf.name) {
+    vars.workflow = String(wf.name);
+    vars.workflow_name = String(wf.name);
+  }
+  if (wf.conclusion) vars.conclusion = String(wf.conclusion);
+  if (wf.run_number != null) vars.run_number = String(wf.run_number);
+  if (wf.run_attempt != null) vars.run_attempt = String(wf.run_attempt);
+}
+
+function extractPullRequestVars(
+  payload: WebhookPayload,
+  vars: Record<string, string>,
+): void {
+  const pr = payload.pull_request;
+  if (!pr) return;
+  if (pr.number != null) vars.pr_number = String(pr.number);
+  if (pr.title) vars.pr_title = String(pr.title);
+  if (pr.html_url) vars.pr_url = String(pr.html_url);
+  if (pr.state) vars.pr_state = String(pr.state);
+}
+
+function extractIssueVars(
+  payload: WebhookPayload,
+  vars: Record<string, string>,
+): void {
+  const iss = payload.issue;
+  if (!iss) return;
+  if (iss.number != null) vars.issue_number = String(iss.number);
+  if (iss.title) vars.issue_title = String(iss.title);
+  if (iss.html_url) vars.issue_url = String(iss.html_url);
+  if (iss.body != null) vars.issue_body = String(iss.body);
+}
+
+function extractReviewAndCommentVars(
+  payload: WebhookPayload,
+  vars: Record<string, string>,
+): void {
+  if (payload.review) {
+    const rev = payload.review;
+    if (rev.state) vars.review_state = String(rev.state);
+    if (rev.body != null) vars.review_body = String(rev.body);
+    if (rev.html_url) vars.review_url = String(rev.html_url);
+  }
+
+  if (payload.comment) {
+    const c = payload.comment;
+    if (c.body != null) vars.comment_body = String(c.body);
+    if (c.html_url) vars.comment_url = String(c.html_url);
+  }
+}
+
+function extractSenderVars(
+  payload: WebhookPayload,
+  vars: Record<string, string>,
+): void {
+  const senderLogin =
+    payload.sender?.login ??
+    payload.review?.user?.login ??
+    payload.comment?.user?.login;
+  if (senderLogin) vars.sender = String(senderLogin);
+
+  const senderType =
+    payload.sender?.type ??
+    payload.review?.user?.type ??
+    payload.comment?.user?.type;
+  if (senderType) vars.sender_type = String(senderType);
+}
+
+export function extractVariables(
+  payload: WebhookPayload,
+  fallbackBranch = "",
+): Record<string, string> {
+  const vars: Record<string, string> = {};
+
+  if (payload.action) {
+    vars.action = String(payload.action);
+  }
+
+  extractRepoVars(payload, vars);
+  extractBranchVars(payload, vars, fallbackBranch);
+  extractWorkflowVars(payload, vars);
+  extractPullRequestVars(payload, vars);
+  extractIssueVars(payload, vars);
+  extractReviewAndCommentVars(payload, vars);
+  extractSenderVars(payload, vars);
+
+  return vars;
+}
+
+export function renderTemplate(
+  template: string,
+  vars: Record<string, string>,
+): string {
+  return template.replace(VARIABLE_PATTERN, (match, key: string) => {
+    return Object.prototype.hasOwnProperty.call(vars, key) ? vars[key] : match;
+  });
+}

package/src/transport/forwarder.ts

@@ -0,0 +1,92 @@
+import { spawn, type ChildProcess } from "node:child_process";
+
+export interface ForwarderOptions {
+  repo: string;
+  url: string;
+  events?: string[];
+  secret?: string;
+  onLog?: (line: string) => void;
+  onError?: (err: Error) => void;
+}
+
+export class GhForwarder {
+  private child: ChildProcess | null = null;
+  private readonly options: ForwarderOptions;
+  private isStopping = false;
+
+  constructor(options: ForwarderOptions) {
+    this.options = options;
+  }
+
+  isRunning(): boolean {
+    return this.child !== null && !this.child.killed;
+  }
+
+  start(): void {
+    if (this.child) return;
+
+    // Default to '*' to listen to ALL events from the repository
+    const eventsArg =
+      this.options.events && this.options.events.length > 0
+        ? this.options.events.join(",")
+        : "*";
+
+    const args = [
+      "webhook",
+      "forward",
+      `--repo=${this.options.repo}`,
+      `--url=${this.options.url}`,
+      `--events=${eventsArg}`,
+    ];
+
+    if (this.options.secret) {
+      args.push(`--secret=${this.options.secret}`);
+    }
+
+    try {
+      this.child = spawn("gh", args, {
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+
+      this.child.stdout?.on("data", (data: Buffer) => {
+        const text = data.toString("utf8").trim();
+        if (text && this.options.onLog) {
+          this.options.onLog(text);
+        }
+      });
+
+      this.child.stderr?.on("data", (data: Buffer) => {
+        const text = data.toString("utf8").trim();
+        if (text && !this.isStopping && this.options.onLog) {
+          this.options.onLog(text);
+        }
+      });
+
+      this.child.on("error", (err) => {
+        if (!this.isStopping && this.options.onError) {
+          this.options.onError(err);
+        }
+      });
+
+      this.child.on("exit", () => {
+        this.child = null;
+      });
+    } catch (err) {
+      if (this.options.onError && err instanceof Error) {
+        this.options.onError(err);
+      }
+    }
+  }
+
+  stop(): void {
+    this.isStopping = true;
+    if (this.child) {
+      try {
+        this.child.kill("SIGTERM");
+      } catch {
+        // Child process may already be dead
+      }
+      this.child = null;
+    }
+  }
+}

package/src/transport/loopback.ts

@@ -0,0 +1,130 @@
+import {
+  createServer,
+  type Server,
+  type IncomingMessage,
+  type ServerResponse,
+} from "node:http";
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type { WebhookPayload } from "../types/payload.js";
+
+export type WebhookEventHandler = (
+  event: string,
+  payload: WebhookPayload,
+) => void | Promise<void>;
+
+export interface LoopbackOptions {
+  secret?: string;
+  onEvent: WebhookEventHandler;
+}
+
+export class LoopbackServer {
+  private server: Server | null = null;
+  private port = 0;
+  private readonly secret?: string;
+  private readonly onEvent: WebhookEventHandler;
+
+  constructor(options: LoopbackOptions) {
+    this.secret = options.secret;
+    this.onEvent = options.onEvent;
+  }
+
+  getPort(): number {
+    return this.port;
+  }
+
+  getUrl(): string {
+    return `http://127.0.0.1:${this.port}/webhook`;
+  }
+
+  async start(): Promise<number> {
+    this.server = createServer((req, res) => {
+      this.handleRequest(req, res);
+    });
+
+    return new Promise((resolve, reject) => {
+      this.server!.once("error", reject);
+      this.server!.listen(0, "127.0.0.1", () => {
+        const addr = this.server!.address();
+        if (typeof addr === "object" && addr !== null) {
+          this.port = addr.port;
+          resolve(this.port);
+        } else {
+          reject(new Error("Failed to get loopback server port"));
+        }
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    if (!this.server) return;
+    const s = this.server;
+    this.server = null;
+    return new Promise((resolve) => {
+      s.close(() => resolve());
+    });
+  }
+
+  private handleRequest(req: IncomingMessage, res: ServerResponse): void {
+    if (req.method !== "POST") {
+      res.writeHead(405, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Method Not Allowed" }));
+      return;
+    }
+
+    const event = req.headers["x-github-event"];
+    if (typeof event !== "string") {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing X-GitHub-Event header" }));
+      return;
+    }
+
+    const signature = req.headers["x-hub-signature-256"];
+    const chunks: Buffer[] = [];
+
+    req.on("data", (chunk: Buffer) => {
+      chunks.push(chunk);
+    });
+
+    req.on("end", () => {
+      const rawBody = Buffer.concat(chunks);
+
+      if (this.secret && !this.verifySignature(rawBody, signature)) {
+        res.writeHead(401, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Invalid signature" }));
+        return;
+      }
+
+      res.writeHead(200, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ received: true }));
+
+      try {
+        const payload = JSON.parse(rawBody.toString("utf8")) as WebhookPayload;
+        Promise.resolve(this.onEvent(event, payload)).catch((err) => {
+          console.error("[pi-ghwebhook] Error handling event:", err);
+        });
+      } catch (err) {
+        console.error("[pi-ghwebhook] Failed to parse JSON body:", err);
+      }
+    });
+  }
+
+  private verifySignature(
+    rawBody: Buffer,
+    signature: string | string[] | undefined,
+  ): boolean {
+    if (typeof signature !== "string" || !signature.startsWith("sha256=")) {
+      return false;
+    }
+
+    const hmac = createHmac("sha256", this.secret!)
+      .update(rawBody)
+      .digest("hex");
+    const expected = `sha256=${hmac}`;
+
+    if (signature.length !== expected.length) {
+      return false;
+    }
+
+    return timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+  }
+}

package/src/types/enums.ts

@@ -0,0 +1,42 @@
+/**
+ * Standard GitHub Webhook Event names as sent in the `X-GitHub-Event` HTTP header.
+ */
+export enum GitHubEvent {
+  WorkflowRun = "workflow_run",
+  WorkflowJob = "workflow_job",
+  PullRequest = "pull_request",
+  PullRequestReview = "pull_request_review",
+  PullRequestReviewComment = "pull_request_review_comment",
+  CheckSuite = "check_suite",
+  CheckRun = "check_run",
+  IssueComment = "issue_comment",
+  Issues = "issues",
+  Push = "push",
+  Release = "release",
+}
+
+/**
+ * Standard conclusions for GitHub Actions workflow runs and check suites,
+ * aligned with GitHub OpenAPI specification (@octokit/openapi-webhooks-types).
+ */
+export enum WorkflowConclusion {
+  Success = "success",
+  Failure = "failure",
+  Cancelled = "cancelled",
+  TimedOut = "timed_out",
+  Neutral = "neutral",
+  ActionRequired = "action_required",
+  Skipped = "skipped",
+  Stale = "stale",
+  StartupFailure = "startup_failure",
+}
+
+/**
+ * Review state for pull request reviews.
+ */
+export enum ReviewState {
+  Approved = "approved",
+  ChangesRequested = "changes_requested",
+  Commented = "commented",
+  Dismissed = "dismissed",
+}

package/src/types/payload.ts

@@ -0,0 +1,75 @@
+import type { components } from "@octokit/openapi-webhooks-types";
+
+export type WebhookSchemas = components["schemas"];
+
+// Workflow Run
+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;
+
+// Pull Request Review
+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;
+
+// Pull Request Review Comment
+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;
+
+// Check Suite
+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;
+
+// Issue Comment
+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>;

package/src/types/schema.ts

@@ -0,0 +1,105 @@
+import { Type, type Static } 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 type FilterConfig = Static<typeof FilterSchema>;
+
+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 type ActionConfig = Static<typeof ActionSchema>;
+
+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 type SubscriptionRule = Static<typeof SubscriptionRuleSchema>;
+
+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 },
+);
+
+export type GhWebhookConfig = Static<typeof ConfigSchema>;