From 5b3cacf72eadf6bd33377b9b84a6be75019bc606 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 11:36:42 +0000 Subject: [PATCH 1/2] Guard doc-sourced samples: edit them in webhook-registry Doc-sourced samples (files with a `source` key) come from webhook-registry's samples-doc through its sync workflow, on the registry-sync branch. A new check fails any other pull request that adds, changes or deletes one, so fixes land in the registry and the hub and Inspect stop drifting apart. Captures are unaffected, and a capture replacing a doc sample passes. ordinal and polytomic, whose doc samples are maintained here, are exempt. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Mp6yzxrVELJ8wYUxdn1aRi --- .github/doc-samples-guard.json | 4 +++ .github/scripts/guard-doc-samples.mjs | 45 +++++++++++++++++++++++++ .github/workflows/doc-samples-guard.yml | 21 ++++++++++++ README.md | 9 +++++ 4 files changed, 79 insertions(+) create mode 100644 .github/doc-samples-guard.json create mode 100644 .github/scripts/guard-doc-samples.mjs create mode 100644 .github/workflows/doc-samples-guard.yml diff --git a/.github/doc-samples-guard.json b/.github/doc-samples-guard.json new file mode 100644 index 00000000..62539da1 --- /dev/null +++ b/.github/doc-samples-guard.json @@ -0,0 +1,4 @@ +{ + "_doc": "Providers whose doc-sourced samples are maintained in this repo rather than in hookdeck/webhook-registry samples-doc (see .github/scripts/guard-doc-samples.mjs).", + "upstream_owned": ["ordinal", "polytomic"] +} diff --git a/.github/scripts/guard-doc-samples.mjs b/.github/scripts/guard-doc-samples.mjs new file mode 100644 index 00000000..b32ba9d9 --- /dev/null +++ b/.github/scripts/guard-doc-samples.mjs @@ -0,0 +1,45 @@ +// Doc-sourced samples (files with a `source` key) are edited in +// hookdeck/webhook-registry's samples-doc/ and arrive here through its sync +// workflow on the `registry-sync` branch. An edit made here directly is overwritten +// by the next sync, and between 2026-11-04 and 2026-11-19 edits made on either side +// left the hub and Inspect showing different events and values (#92-#94). +// +// This fails a pull request that adds, changes or deletes a doc-sourced file unless +// it comes from `registry-sync`. Captures (no `source` key) are unaffected, and a +// capture replacing a doc sample is allowed: a capture always wins. +import { execFileSync } from "node:child_process"; +import { readFileSync } from "node:fs"; + +const base = process.argv[2]; +const headRef = process.env.HEAD_REF || ""; +const exempt = new Set(JSON.parse(readFileSync(".github/doc-samples-guard.json", "utf8")).upstream_owned); + +if (headRef === "registry-sync") { + console.log("registry-sync branch: doc-sourced edits allowed."); + process.exit(0); +} + +const git = (...a) => execFileSync("git", a, { encoding: "utf8", maxBuffer: 1 << 28 }); +const read = (rev, path) => { + try { return JSON.parse(git("show", `${rev}:${path}`)); } catch { return null; } +}; +const isDoc = (d) => d !== null && typeof d === "object" && !Array.isArray(d) && "source" in d; + +const changed = git("diff", "--name-status", "--no-renames", `${base}...HEAD`) + .split("\n").filter(Boolean).map((l) => l.split("\t")); +const bad = []; +for (const [status, path] of changed) { + const m = path.match(/^providers\/([^/]+)\/[^/]+\/[^/]+\.json$/); + if (!m || exempt.has(m[1])) continue; + const before = read(base, path); + const after = status === "D" ? null : read("HEAD", path); + if (isDoc(after)) bad.push(`${status === "A" ? "adds" : "changes"} ${path}`); + else if (after === null && isDoc(before)) bad.push(`deletes ${path}`); +} +if (bad.length) { + console.log(`::error::This PR edits ${bad.length} doc-sourced sample(s). Make the change in hookdeck/webhook-registry samples-doc/; its sync workflow brings it here.`); + for (const b of bad.slice(0, 50)) console.log(` ${b}`); + if (bad.length > 50) console.log(` ... and ${bad.length - 50} more`); + process.exit(1); +} +console.log("No doc-sourced samples edited outside registry-sync."); diff --git a/.github/workflows/doc-samples-guard.yml b/.github/workflows/doc-samples-guard.yml new file mode 100644 index 00000000..13a5b8f7 --- /dev/null +++ b/.github/workflows/doc-samples-guard.yml @@ -0,0 +1,21 @@ +name: Doc samples guard + +on: + pull_request: + paths: + - providers/** + +jobs: + guard: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: actions/setup-node@v4 + with: + node-version: 22 + - name: Doc-sourced samples come from webhook-registry + env: + HEAD_REF: ${{ github.head_ref }} + run: node .github/scripts/guard-doc-samples.mjs "origin/${{ github.base_ref }}" diff --git a/README.md b/README.md index 5e9c5330..7e86b0cd 100644 --- a/README.md +++ b/README.md @@ -162,6 +162,15 @@ Two things follow from the marking: They come from [hookdeck/webhook-registry](https://github.com/hookdeck/webhook-registry) (`samples-doc/`), which records where each example was read and when. +**Edit them there, not here.** webhook-registry's `sync-samples` workflow mirrors +`samples-doc/` into this repo as a rolling pull request from the `registry-sync` +branch after every registry merge, and the *Doc samples guard* check fails any other +pull request that adds, changes or deletes a file with a `source` key. Captures are +never touched by the sync, and a capture replacing a doc sample passes the guard. +Personal data is scrubbed in the registry before export (its `verify.py` fails on +non-placeholder emails and public IPs). The few providers whose doc samples are +maintained here instead are listed in `.github/doc-samples-guard.json`. + ## Using the data The data is packaged into JSON files that are distributed over http. The files can be found on https://samples.hookdeck.com From dd57c206065863502ffbe45ce53fa96ed2a42c0d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 19 Nov 2026 11:42:41 +0000 Subject: [PATCH 2/2] Guard: no fork bypass, label captures that replace doc samples - The registry-sync exemption now also requires the PR's head repo to be this repo, so a fork's registry-sync branch doesn't pass. - Replacing a doc sample with a capture (dropping the `source` key) now needs the PR labelled `capture`; otherwise an edited doc file could pass as a capture and the sync would leave it alone for good. The check re-runs on label changes. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Mp6yzxrVELJ8wYUxdn1aRi --- .github/scripts/guard-doc-samples.mjs | 14 +++++++++++--- .github/workflows/doc-samples-guard.yml | 4 ++++ README.md | 3 ++- 3 files changed, 17 insertions(+), 4 deletions(-) diff --git a/.github/scripts/guard-doc-samples.mjs b/.github/scripts/guard-doc-samples.mjs index b32ba9d9..3b7ec79f 100644 --- a/.github/scripts/guard-doc-samples.mjs +++ b/.github/scripts/guard-doc-samples.mjs @@ -5,16 +5,23 @@ // left the hub and Inspect showing different events and values (#92-#94). // // This fails a pull request that adds, changes or deletes a doc-sourced file unless -// it comes from `registry-sync`. Captures (no `source` key) are unaffected, and a -// capture replacing a doc sample is allowed: a capture always wins. +// it comes from this repo's own `registry-sync` branch (a fork's branch of that name +// doesn't count). Captures (no `source` key) are unaffected. +// +// Replacing a doc sample with a capture is allowed, because a capture always wins, +// but only on a PR labelled `capture`: dropping the `source` key from a doc file and +// editing it would otherwise pass as a capture, and the sync would then leave it +// alone for good. import { execFileSync } from "node:child_process"; import { readFileSync } from "node:fs"; const base = process.argv[2]; const headRef = process.env.HEAD_REF || ""; +const fromThisRepo = (process.env.HEAD_REPO || "") === (process.env.REPO || "-"); +const labelled = (process.env.PR_LABELS || "").split(",").includes("capture"); const exempt = new Set(JSON.parse(readFileSync(".github/doc-samples-guard.json", "utf8")).upstream_owned); -if (headRef === "registry-sync") { +if (headRef === "registry-sync" && fromThisRepo) { console.log("registry-sync branch: doc-sourced edits allowed."); process.exit(0); } @@ -35,6 +42,7 @@ for (const [status, path] of changed) { const after = status === "D" ? null : read("HEAD", path); if (isDoc(after)) bad.push(`${status === "A" ? "adds" : "changes"} ${path}`); else if (after === null && isDoc(before)) bad.push(`deletes ${path}`); + else if (isDoc(before) && !labelled) bad.push(`replaces doc sample ${path} with a capture (label the PR \`capture\` if it is one)`); } if (bad.length) { console.log(`::error::This PR edits ${bad.length} doc-sourced sample(s). Make the change in hookdeck/webhook-registry samples-doc/; its sync workflow brings it here.`); diff --git a/.github/workflows/doc-samples-guard.yml b/.github/workflows/doc-samples-guard.yml index 13a5b8f7..0b5c43ab 100644 --- a/.github/workflows/doc-samples-guard.yml +++ b/.github/workflows/doc-samples-guard.yml @@ -2,6 +2,7 @@ name: Doc samples guard on: pull_request: + types: [opened, synchronize, reopened, labeled, unlabeled] paths: - providers/** @@ -18,4 +19,7 @@ jobs: - name: Doc-sourced samples come from webhook-registry env: HEAD_REF: ${{ github.head_ref }} + HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }} + REPO: ${{ github.repository }} + PR_LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }} run: node .github/scripts/guard-doc-samples.mjs "origin/${{ github.base_ref }}" diff --git a/README.md b/README.md index 7e86b0cd..c207675c 100644 --- a/README.md +++ b/README.md @@ -166,7 +166,8 @@ They come from [hookdeck/webhook-registry](https://github.com/hookdeck/webhook-r `samples-doc/` into this repo as a rolling pull request from the `registry-sync` branch after every registry merge, and the *Doc samples guard* check fails any other pull request that adds, changes or deletes a file with a `source` key. Captures are -never touched by the sync, and a capture replacing a doc sample passes the guard. +never touched by the sync. A capture replacing a doc sample passes the guard on a pull +request labelled `capture`. Personal data is scrubbed in the registry before export (its `verify.py` fails on non-placeholder emails and public IPs). The few providers whose doc samples are maintained here instead are listed in `.github/doc-samples-guard.json`.