Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions .github/workflows/claude-code-review.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/claude.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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."
11 changes: 6 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<!-- plugins:start -->` and `<!-- plugins:end -->` 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 `<!-- plugins:start -->` and `<!-- plugins:end -->` 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=<url or file:///path> npm run sync-plugins`.
- The site updates when it's rebuilt after a `patch-it-plugins` release.

## llms.txt

Expand Down
1 change: 1 addition & 0 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
118 changes: 80 additions & 38 deletions scripts/sync-plugins.mjs
Original file line number Diff line number Diff line change
@@ -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 <!-- plugins:start --> and <!-- plugins:end -->; 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 <!-- plugins:start --> and <!-- plugins:end -->
// 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 = '<!-- plugins:start -->';
const END = '<!-- plugins: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<small>${counts}, from patch-it-plugins${version}.</small>`;
}

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();
2 changes: 1 addition & 1 deletion src/content/docs/supported-apis/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
Loading
Loading