diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml index 3bd8caa..de6542b 100644 --- a/.github/workflows/claude-code-review.yml +++ b/.github/workflows/claude-code-review.yml @@ -113,9 +113,11 @@ jobs: details, links to private repos, dashboards or tickets, customer or user names, unsourced numbers, prices, roadmap dates, and links to AI sessions. Internal details belong in the private handbook, not here. - 5. GENERATED PARTS. The table in supported-apis/plugins.md comes from - patch-it-plugins' docs/plugins.md: a hand edit between the plugins markers is - blocking. A new page needs the frontmatter (title, description, sidebar + 5. GENERATED PARTS. The list in supported-apis/plugins.md is rendered at + build time from patch-it-plugins' latest release (plugins.json); between the + plugins markers the committed page holds only the "temporarily unavailable" + note. A committed list there, or any hand-kept list of providers elsewhere, + is blocking. A new page needs the frontmatter (title, description, sidebar order where the folder needs it); llms.txt picks pages up by itself. 6. VOICE. Calm, sharp, wry; in docs, clear first, at most a dry aside in an intro, never in steps. Always lowercase "patch-it". Name the real thing diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index f72cd85..2315096 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -68,4 +68,4 @@ jobs: --permission-mode default --allowedTools "mcp__github_inline_comment__create_inline_comment,Read,Grep,Glob,Bash(gh pr view:*),Bash(gh pr diff:*),Bash(gh issue view:*)" --disallowedTools "Edit,Write,MultiEdit,NotebookEdit,WebFetch,WebSearch,Bash(git push:*),Bash(git commit:*),Bash(git add:*),Bash(git rm:*),mcp__github_file_ops__commit_files,mcp__github_file_ops__delete_files" - --append-system-prompt "This is patch-it-docs, the public docs at docs.patch-it.dev (Astro Starlight; pages in src/content/docs/). Everything you write is public. You can only read and comment; you can't change files or run code, so if asked to, say so and describe the change instead. When asked to review a pull request (for example '@claude review'), check: (1) accuracy: the patch-it CLI and GitHub Action are the reference, which you can't read from here, so flag contradictions with the rest of these docs (configuration/, guides/cli.md, guides/github-action.md, api-reference/) and list behavior claims the PR body doesn't back with a link to the client change under 'Needs a maintainer to confirm'; unshipped features stay a Coming soon note; (2) links resolve: site links like /guides/cli/ match a page under src/content/docs/, anchors match a heading, relative links and images point at real files; (3) nothing internal: no credentials, internal hostnames, internal APIs or services, architecture or runbook details, links to private repos or tickets, customer names, unsourced numbers, prices, roadmap dates, or links to AI sessions; (4) the plugin table in supported-apis/plugins.md is generated from patch-it-plugins, so a hand edit between its markers is blocking; (5) voice, non-blocking: calm, sharp, wry, clear first; always lowercase patch-it; no emoji, exclamation marks or hype words (revolutionary, seamless, AI-powered, leverage, effortless, magic, supercharge, unlock, empower); say fix, breaking change, pull request. You can't run the build. Start with one verdict line ('✅ Ready to merge', '⚠️ Merge after fixes' or '❌ Not ready'), then accuracy, links, public, and clearly marked non-blocking suggestions. Be kind and specific: many authors are outside contributors. Never include a Claude session ID or claude.ai link." + --append-system-prompt "This is patch-it-docs, the public docs at docs.patch-it.dev (Astro Starlight; pages in src/content/docs/). Everything you write is public. You can only read and comment; you can't change files or run code, so if asked to, say so and describe the change instead. When asked to review a pull request (for example '@claude review'), check: (1) accuracy: the patch-it CLI and GitHub Action are the reference, which you can't read from here, so flag contradictions with the rest of these docs (configuration/, guides/cli.md, guides/github-action.md, api-reference/) and list behavior claims the PR body doesn't back with a link to the client change under 'Needs a maintainer to confirm'; unshipped features stay a Coming soon note; (2) links resolve: site links like /guides/cli/ match a page under src/content/docs/, anchors match a heading, relative links and images point at real files; (3) nothing internal: no credentials, internal hostnames, internal APIs or services, architecture or runbook details, links to private repos or tickets, customer names, unsourced numbers, prices, roadmap dates, or links to AI sessions; (4) the plugin list in supported-apis/plugins.md is rendered at build time from patch-it-plugins' latest release, so a committed list between its markers, or a hand-kept list of providers anywhere, is blocking; (5) voice, non-blocking: calm, sharp, wry, clear first; always lowercase patch-it; no emoji, exclamation marks or hype words (revolutionary, seamless, AI-powered, leverage, effortless, magic, supercharge, unlock, empower); say fix, breaking change, pull request. You can't run the build. Start with one verdict line ('✅ Ready to merge', '⚠️ Merge after fixes' or '❌ Not ready'), then accuracy, links, public, and clearly marked non-blocking suggestions. Be kind and specific: many authors are outside contributors. Never include a Claude session ID or claude.ai link." diff --git a/README.md b/README.md index 86e14ab..a3862f9 100644 --- a/README.md +++ b/README.md @@ -34,12 +34,13 @@ Keep internal details out of here: internal APIs, architecture and runbooks belo ## The list of plugins -[Supported APIs → All plugins](src/content/docs/supported-apis/plugins.md) is built from [`docs/plugins.md`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/docs/plugins.md) in the public `patch-it-plugins` repo, the one list of supported plugins. Don't edit the table on this site; change it there. +[Supported APIs → All plugins](src/content/docs/supported-apis/plugins.md) shows every provider and source patch-it watches, grouped by category. The only list is the plugin registry in the public `patch-it-plugins` code; nothing here or there keeps one by hand. Each `patch-it-plugins` release attaches it as `plugins.json`. -- `npm run build` first runs `scripts/sync-plugins.mjs` (npm's `prebuild`): it downloads that file from `main` (raw.githubusercontent.com, no token) and copies the table between `` and `` into the page, between the same markers. -- **Offline or GitHub down:** it prints a warning and keeps the committed table, so the build never fails on it. -- **Refresh the committed copy** with `npm run sync-plugins` and commit the page; a build that changed the table leaves it as a diff in your working tree. -- The site updates when it's rebuilt: a change merged in `patch-it-plugins` shows up on the next docs deploy. +- `npm run build` and `npm run dev` first run `scripts/sync-plugins.mjs` (npm's `prebuild` / `predev`): it downloads `https://github.com/patch-it-dev/patch-it-plugins/releases/latest/download/plugins.json` (no token) and writes the list, one table per category, between `` and `` in the page. +- **Offline, GitHub down, or no asset:** it prints a warning and writes "the list is temporarily unavailable" there instead, so the build never fails on it and never shows an old copy. +- **Don't commit a rendered list.** The committed page holds the "unavailable" note; a local build leaves the rendered list as a diff in your working tree: discard it (`git checkout src/content/docs/supported-apis/plugins.md`). +- Preview another list with `PLUGINS_JSON_URL= npm run sync-plugins`. +- The site updates when it's rebuilt after a `patch-it-plugins` release. ## llms.txt diff --git a/package.json b/package.json index d487bf5..b3f556a 100644 --- a/package.json +++ b/package.json @@ -4,6 +4,7 @@ "version": "0.1.0", "private": true, "scripts": { + "predev": "node scripts/sync-plugins.mjs", "dev": "astro dev", "sync-plugins": "node scripts/sync-plugins.mjs", "prebuild": "node scripts/sync-plugins.mjs", diff --git a/scripts/sync-plugins.mjs b/scripts/sync-plugins.mjs index 2d41ea1..c982a4a 100644 --- a/scripts/sync-plugins.mjs +++ b/scripts/sync-plugins.mjs @@ -1,60 +1,102 @@ -// Copies the list of supported plugins from patch-it-plugins into the "All plugins" page. +// Renders the list of providers and sources patch-it watches into the "All plugins" page. // -// The source of truth is docs/plugins.md on patch-it-plugins' main branch (a public repo, so no -// token). Its table sits between and ; this script -// puts that table between the same markers in src/content/docs/supported-apis/plugins.md. +// The only list is the plugin registry in patch-it-plugins' code. Each release of that public +// repo carries it as an asset, plugins.json (printed by `go run ./cmd/list-plugins`), so this +// script reads the latest release's copy: no token, no committed list anywhere. It groups the +// providers by category and writes them between and +// in src/content/docs/supported-apis/plugins.md. // -// Runs before every build (npm's "prebuild"). If GitHub can't be reached, or the file has no -// table, it leaves the committed page alone: that copy is the fallback, so the build never fails -// offline. Run `npm run sync-plugins` and commit the page to refresh the fallback. +// Runs before every build and dev server (npm's "prebuild" and "predev"). If GitHub can't be +// reached, or the asset is missing or malformed, it writes a short "temporarily unavailable" +// note instead, never an old copy, and the build goes on. The committed page holds that note: +// don't commit a rendered list. import { readFileSync, writeFileSync } from 'node:fs'; +import { fileURLToPath } from 'node:url'; -// PLUGINS_LIST_URL overrides it, e.g. to preview a patch-it-plugins branch. -const SOURCE = process.env.PLUGINS_LIST_URL || 'https://raw.githubusercontent.com/patch-it-dev/patch-it-plugins/main/docs/plugins.md'; +// PLUGINS_JSON_URL overrides it, e.g. a file:// path or another release's asset to preview. +const SOURCE = + process.env.PLUGINS_JSON_URL || + 'https://github.com/patch-it-dev/patch-it-plugins/releases/latest/download/plugins.json'; const PAGE = new URL('../src/content/docs/supported-apis/plugins.md', import.meta.url); const START = ''; const END = ''; -/** The table between the markers: only Markdown table rows, so nothing else can reach the page. */ -export function extractTable(markdown) { - const start = markdown.indexOf(START); - const end = markdown.indexOf(END, start); - if (start < 0 || end < 0) return null; - const rows = markdown - .slice(start + START.length, end) - .split('\n') - .map((line) => line.trim()) - .filter((line) => line.startsWith('|')); - // A header, the |---| line, and at least one plugin. - return rows.length >= 3 ? rows.join('\n') : null; +export const UNAVAILABLE = + ':::note\nThe list is temporarily unavailable. It is read from the latest [patch-it-plugins release](https://github.com/patch-it-dev/patch-it-plugins/releases/latest) when these docs are built; it will be back on the next build.\n:::'; + +// How a category id reads as a heading; any other id is capitalized. +const TITLES = { ai: 'AI', crm: 'CRM', devtools: 'Developer tools' }; + +export function title(category) { + return TITLES[category] || category.charAt(0).toUpperCase() + category.slice(1); +} + +/** A table cell: one line, no pipe that would split it. */ +function cell(text) { + return String(text ?? '').replace(/\s+/g, ' ').replace(/\|/g, '\\|').trim(); +} + +function host(url) { + try { + const u = new URL(url); + return u.hostname + (u.pathname === '/' ? '' : u.pathname); + } catch { + return url; + } } -export function replaceTable(page, table) { +/** Markdown for a plugins.json document: one section per category, in the list's order. */ +export function render(list) { + if (!list || !Array.isArray(list.providers) || list.providers.length === 0) { + throw new Error('no providers in the list'); + } + const order = Array.isArray(list.categories) ? [...list.categories] : []; + for (const p of list.providers) if (!order.includes(p.category)) order.push(p.category); + const sections = []; + for (const category of order) { + const providers = list.providers.filter((p) => p.category === category); + if (providers.length === 0) continue; + const rows = ['| Provider | Source | Layer | What it watches | Reads |', '|---|---|---|---|---|']; + for (const p of providers) { + for (const s of p.sources || []) { + const reads = (s.urls || []).slice(0, 1).map((u) => `[${cell(host(u))}](${u})`).join(''); + rows.push( + `| [${cell(p.name)}](${p.homepage}) | [\`${cell(s.id)}\`](${s.page}) | ${cell(s.layer)} | ${cell(s.watches)} | ${reads} |`, + ); + } + } + sections.push(`### ${title(category)}\n\n${rows.join('\n')}`); + } + const version = list.version ? ` (${cell(list.version)})` : ''; + const counts = `${list.provider_count ?? list.providers.length} providers, ${list.source_count ?? ''} sources`.replace(', ,', ','); + return `${sections.join('\n\n')}\n\n${counts}, from patch-it-plugins${version}.`; +} + +export function replaceBetweenMarkers(page, body) { const start = page.indexOf(START); const end = page.indexOf(END, start); if (start < 0 || end < 0) throw new Error(`${PAGE.pathname} lost its ${START} / ${END} markers`); - return `${page.slice(0, start + START.length)}\n${table}\n${page.slice(end)}`; + return `${page.slice(0, start + START.length)}\n${body}\n${page.slice(end)}`; +} + +async function load(source) { + if (source.startsWith('file:')) return JSON.parse(readFileSync(new URL(source), 'utf-8')); + const res = await fetch(source, { signal: AbortSignal.timeout(10_000), redirect: 'follow' }); + if (!res.ok) throw new Error(`HTTP ${res.status}`); + return res.json(); } async function main() { - let table = null; + let body = UNAVAILABLE; try { - const res = await fetch(SOURCE, { signal: AbortSignal.timeout(10_000) }); - if (!res.ok) throw new Error(`HTTP ${res.status}`); - table = extractTable(await res.text()); - if (!table) throw new Error('no plugin table between the markers'); + body = render(await load(SOURCE)); } catch (err) { - console.warn(`sync-plugins: kept the committed plugin list (${SOURCE}: ${err.message})`); - return; + console.warn(`sync-plugins: the list is unavailable (${SOURCE}: ${err.message}); the page says so`); } const page = readFileSync(PAGE, 'utf-8'); - const next = replaceTable(page, table); - if (next === page) { - console.log('sync-plugins: plugin list is up to date'); - return; - } - writeFileSync(PAGE, next); - console.log(`sync-plugins: updated the plugin list from ${SOURCE} (${table.split('\n').length - 2} plugins)`); + const next = replaceBetweenMarkers(page, body); + if (next !== page) writeFileSync(PAGE, next); + if (body !== UNAVAILABLE) console.log(`sync-plugins: rendered the list from ${SOURCE}`); } -await main(); +if (process.argv[1] === fileURLToPath(import.meta.url)) await main(); diff --git a/src/content/docs/supported-apis/overview.md b/src/content/docs/supported-apis/overview.md index b647ae5..d01c364 100644 --- a/src/content/docs/supported-apis/overview.md +++ b/src/content/docs/supported-apis/overview.md @@ -14,7 +14,7 @@ sidebar: | Runtimes | Building | | CI platforms | Next | -Each source is one plugin. [All plugins](/supported-apis/plugins/) lists every one: what it watches and where it reads it. +Each provider has one or more sources, each read by a plugin. [All plugins](/supported-apis/plugins/) lists them, grouped by category: what each watches and where it reads it. ## What counts as a change diff --git a/src/content/docs/supported-apis/plugins.md b/src/content/docs/supported-apis/plugins.md index f654dbe..8cdd7e9 100644 --- a/src/content/docs/supported-apis/plugins.md +++ b/src/content/docs/supported-apis/plugins.md @@ -1,29 +1,18 @@ --- title: All plugins -description: Every source patch-it watches today, one plugin each, with what it reports and where it reads it. +description: Every provider and source patch-it watches, grouped by category, with what each reports and where it reads it. sidebar: order: 2 --- -Every source patch-it watches is one plugin: it reads the provider's own page, spec or feed and turns each change into an event with a link and a quote. This is the full list. Plugins are open source in [patch-it-plugins](https://github.com/patch-it-dev/patch-it-plugins) (Apache-2.0), and this table is copied from its [`docs/plugins.md`](https://github.com/patch-it-dev/patch-it-plugins/blob/main/docs/plugins.md) whenever these docs are built. +patch-it watches providers (Stripe, OpenAI, GitHub…), each through one or more sources: the provider's own spec, changelog, deprecations page or feed, read so that each change becomes an event with a link and a quote. A source's id is `provider/source`, like `stripe/api`. The plugins are open source in [patch-it-plugins](https://github.com/patch-it-dev/patch-it-plugins) (Apache-2.0), where each source is registered in code; this list is built from the `plugins.json` attached to its latest release, every time these docs are built. -| Plugin (`--api`) | Provider | What it watches | Format plugin | Source | Status | -|---|---|---|---|---|---| -| `stripe` | Stripe | REST API changes between OpenAPI spec releases (removed and renamed endpoints, parameters and fields), with migration hints from Stripe's API changelog | `openapi` | [stripe/openapi](https://github.com/stripe/openapi) | live | -| `datadog` | Datadog | API v2 changes between OpenAPI spec releases | `openapi` | [DataDog/datadog-api-client-python](https://github.com/DataDog/datadog-api-client-python) (`.generator/schemas/v2/openapi.yaml`) | live | -| `github` | GitHub | REST API changes between dated API versions | `openapi` | [github/rest-api-description](https://github.com/github/rest-api-description) | live | -| `gitlab` | GitLab | REST API changes between releases, request side only (what callers send) | `openapi` | [gitlab-org/gitlab `doc/api/openapi`](https://gitlab.com/gitlab-org/gitlab/-/tree/master/doc/api/openapi) | live | -| `openai-models` | OpenAI | Model deprecations and shutdown dates (Chat Completions and Responses text models) | `retirements` | [OpenAI deprecations](https://developers.openai.com/api/docs/deprecations) | live | -| `anthropic-models` | Anthropic | Model deprecations and retirement dates (Messages API models) | `retirements` | [Anthropic model deprecations](https://platform.claude.com/docs/en/about-claude/model-deprecations) | live | -| `anthropic` | Anthropic | Parameters removed from `messages.create()` and friends in the Python SDK 1.0 | `migrationguide` | [anthropic-sdk-python MIGRATION.md](https://github.com/anthropics/anthropic-sdk-python/blob/v1.0.0/MIGRATION.md) | live | -| `numpy` | NumPy | Members removed or renamed in the main namespace in NumPy 2.0 | `removedmembers` | [NumPy 2.0 migration guide](https://github.com/numpy/numpy/blob/v2.0.0/doc/source/numpy_2_0_migration_guide.rst) | live | -| `textual` | Textual | Removals and breaking changes in release 0.86.0 | `changelog` | [Textualize/textual CHANGELOG.md](https://github.com/Textualize/textual/blob/v0.86.0/CHANGELOG.md) | live | -| `urllib3` | urllib3 | Removals and deprecations in release 2.0.0 | `changelog` | [urllib3/urllib3 CHANGES.rst](https://github.com/urllib3/urllib3/blob/2.0.0/CHANGES.rst) | live | -| `github-actions` | GitHub | GitHub Actions retirements, such as runner images and the `runs-on` labels they remove | `feed` | [GitHub changelog, Actions label (RSS)](https://github.blog/changelog/label/actions/feed/) | live | -| `vertex-ai-models` | Google | Generative AI model deprecations on Vertex AI | `feed` | [Vertex AI generative AI release notes (Atom)](https://docs.cloud.google.com/feeds/generative-ai-on-vertex-ai-release-notes.xml) | live | +:::note +The list is temporarily unavailable. It is read from the latest [patch-it-plugins release](https://github.com/patch-it-dev/patch-it-plugins/releases/latest) when these docs are built; it will be back on the next build. +::: -**Format plugin** is the shared reader a plugin is built on: `openapi` diffs a spec per release, `retirements` reads a deprecations page, `migrationguide` and `removedmembers` read migration guides, `changelog` reads a release changelog, `feed` reads an RSS or Atom feed. **Live** means it runs every day. +**Layer** is which part of your stack a source covers: `api`, `sdk`, `package`, `runtime`, `ci`, `ai-models` or `infra`. Every source listed is read on a schedule, with no one triggering it. Missing a provider? [Request it](/supported-apis/request-an-api/), or [write the plugin](https://github.com/patch-it-dev/patch-it-plugins/blob/main/CONTRIBUTING.md).