feat(ci): required validate check with V2 probe, and pull_request_target triage

validate-pr.yml now runs on every PR (README-only PRs previously got no feedback), drops tj-actions/changed-files, runs unit tests, scripts/check-pr.js and a README/registry generation dry run, and supports workflow_dispatch so bot branches get the check. New plugin entries that are V1-only are blocked; declared compat must match what is detected. triage.yml labels PRs (ready, needs-v2, needs-metadata, needs-human, category) and keeps one results comment, using base-branch code only and reading PR files as data. The README workflow uses full history and Node 24.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

scripts/utils/compat.js

@@ -0,0 +1,265 @@
+/**
+ * OpenCode V1/V2 compatibility probe.
+ *
+ * V2 marker: any dependency on an @opencode/* package (@opencode/plugin, client, sdk, theme, core),
+ * including npm aliases like "plugin-v2": "npm:@opencode/[email protected]". The V2 API also shipped as
+ * pre-releases under the old name before the rename (@opencode-ai/[email protected]*, @next, @beta,
+ * and @opencode-ai/client, which only exists in the V2 era); those count as V2 too. Packages that
+ * depend on both generations are dual-support and count as V2.
+ * V1 marker: @opencode-ai/plugin or @opencode-ai/sdk at a 1.x (or unpinned) version, with no V2 marker.
+ *
+ * Sources, in order: the entry's npm package (latest version), then package.json files in the repo
+ * (at `path`, the root, and workspace packages under packages/ or plugins/), then source text for
+ * gists. Anything else is "unknown" and needs a human look.
+ */
+
+const zlib = require('zlib');
+const { getFiles, getNpmLatest, getToken, rest } = require('./github');
+const { parseRepoUrl } = require('./catalog');
+
+const SOURCE_FILE_RE = /\.(m?[jt]sx?|cjs|cts)$/;
+const SKIP_DIR_RE = /(^|\/)(node_modules|\.git|vendor|fixtures?|__tests__|test|tests|examples?)\//;
+const MAX_TARBALL_BYTES = 30 * 1024 * 1024;
+// Legacy V1 plugin shape: an exported async function receiving { client, project, directory, $, ... }
+// and returning hooks such as event, chat.params or tool.execute.before
+const V1_HOOK_RE = /["']?(chat\.params|chat\.message|tool\.execute\.(before|after)|permission\.ask|shell\.env)["']?\s*:\s*async|\bevent\s*:\s*async\s*\(\s*\{\s*event\b/;
+// V2 plugin contract without the helper: an object with an id and a setup(ctx) entry point
+// (Plugin.define is an identity function, so dependency-free V2 plugins export this directly)
+const V2_OBJECT_RE = /\{[^{}]*\bid\s*:\s*[\w"'`][^{}]*\b(async\s+)?setup\s*[:,(}]/;
+const V1_EXPORT_RE = /export\s+(const|default)\s+(\w+\s*(:\s*Plugin\s*)?=\s*)?async\s*(function\s*\w*\s*)?\(\s*\{[^}]*\b(client|project|directory|worktree|\$)\b/;
+
+const DEP_FIELDS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+const V1_PACKAGES = ['@opencode-ai/plugin', '@opencode-ai/sdk'];
+const V2_ERA_PACKAGES = ['@opencode-ai/client'];
+const V2_PRERELEASE_SPEC = /^(?:[\^~]|>=?\s*)?(?:0\.0\.0-(?:beta|next|tui-v2)|beta$|next$)/;
+const WORKSPACE_DIRS = ['packages', 'plugins'];
+const MAX_WORKSPACE_PACKAGES = 25;
+
+/**
+ * Resolve each dependency (key or npm: alias target) to the real package name and version spec.
+ * @param {object} manifest - package.json contents
+ * @returns {{name: string, spec: string}[]}
+ */
+function dependencies(manifest) {
+  const deps = [];
+  for (const field of DEP_FIELDS) {
+    for (const [key, raw] of Object.entries((manifest && manifest[field]) || {})) {
+      const spec = typeof raw === 'string' ? raw : '';
+      const alias = spec.match(/^npm:((?:@[^/@]+\/)?[^@]+)(?:@(.*))?$/);
+      deps.push(alias ? { name: alias[1], spec: alias[2] || '' } : { name: key, spec });
+    }
+  }
+  return deps;
+}
+
+/**
+ * Markers found in one manifest.
+ * @param {object} manifest
+ * @returns {{v2: string[], v1: string[]}}
+ */
+function manifestMarkers(manifest) {
+  const v2 = new Set();
+  const v1 = new Set();
+  for (const { name, spec } of dependencies(manifest)) {
+    if (name.startsWith('@opencode/')) v2.add(name);
+    else if (V2_ERA_PACKAGES.includes(name)) v2.add(`${name} (V2 pre-release)`);
+    else if (V1_PACKAGES.includes(name) && V2_PRERELEASE_SPEC.test(spec.trim())) v2.add(`${name}@${spec} (V2 pre-release)`);
+    else if (V1_PACKAGES.includes(name)) v1.add(spec ? `${name}@${spec}` : name);
+  }
+  return { v2: [...v2], v1: [...v1] };
+}
+
+/**
+ * Markers found in source text (import/require specifiers).
+ * @param {string} text
+ * @returns {{v2: string[], v1: string[], define: boolean}}
+ */
+function sourceMarkers(text) {
+  const specs = [...String(text).matchAll(/(?:from\s+|require\(\s*|import\(\s*)["'](@opencode(?:-ai)?\/[a-z0-9-]+)/g)].map(m => m[1]);
+  return {
+    v2: [...new Set(specs.filter(s => s.startsWith('@opencode/')))],
+    v1: [...new Set(specs.filter(s => V1_PACKAGES.includes(s)))],
+    define: /Plugin\.define\s*\(/.test(text),
+    v2Signature: V2_OBJECT_RE.test(text),
+    v1Signature: V1_HOOK_RE.test(text) || V1_EXPORT_RE.test(text)
+  };
+}
+
+/**
+ * Turn collected markers into a verdict.
+ * @param {{source: string, v2: string[], v1: string[]}[]} findings
+ * @returns {{compat: 'v2'|'v1'|'unknown', evidence: string[]}}
+ */
+function verdict(findings) {
+  const evidence = findings
+    .filter(f => f.v2.length || f.v1.length)
+    .map(f => `${f.source}: ${[...f.v2, ...f.v1].join(', ')}`);
+  const hasV2 = findings.some(f => f.v2.length);
+  const hasV1 = findings.some(f => f.v1.length);
+  if (hasV2) return { compat: 'v2', evidence: hasV1 ? [...evidence, 'dual V1/V2 support'] : evidence };
+  if (hasV1) return { compat: 'v1', evidence };
+  return { compat: 'unknown', evidence: findings.length ? [`no @opencode/* or @opencode-ai/* dependency in ${findings.map(f => f.source).join(', ')}`] : ['no package.json or npm package found'] };
+}
+
+function safeJson(text) {
+  try { return JSON.parse(text); } catch { return null; }
+}
+
+/**
+ * Iterate regular files in a tar archive buffer.
+ * @param {Buffer} tar
+ * @returns {Generator<{name: string, data: Buffer}>}
+ */
+function* tarFiles(tar) {
+  let offset = 0;
+  let longName = null;
+  while (offset + 512 <= tar.length) {
+    const header = tar.subarray(offset, offset + 512);
+    if (header.every(b => b === 0)) break;
+    const field = (start, len) => header.subarray(start, start + len).toString('utf8').replace(/\0.*$/s, '');
+    const size = parseInt(field(124, 12).trim() || '0', 8);
+    const type = String.fromCharCode(header[156] || 48);
+    const prefix = field(345, 155);
+    let name = longName || (prefix ? `${prefix}/${field(0, 100)}` : field(0, 100));
+    const data = tar.subarray(offset + 512, offset + 512 + size);
+    longName = null;
+    if (type === 'L') longName = data.toString('utf8').replace(/\0.*$/s, '');
+    else if (type === 'x') {
+      const pathRecord = data.toString('utf8').match(/\d+ path=([^\n]+)\n/);
+      if (pathRecord) longName = pathRecord[1];
+    } else if (type === '0' || type === '\0') {
+      name = name.replace(/^[^/]+\//, ''); // strip the "owner-repo-sha/" top folder
+      yield { name, data };
+    }
+    offset += 512 + Math.ceil(size / 512) * 512;
+  }
+}
+
+/**
+ * Scan a GitHub repo's source for V1/V2 markers by downloading its tarball.
+ * @param {{owner: string, name: string}} repo
+ * @param {string} [subPath] - restrict to a monorepo folder
+ * @returns {Promise<{source: string, v2: string[], v1: string[]}|null>}
+ */
+async function scanSource(repo, subPath) {
+  const res = await fetch(`https://api.github.com/repos/${repo.owner}/${repo.name}/tarball`, {
+    headers: { 'User-Agent': 'awesome-opencode-bot', ...(getToken() ? { Authorization: `Bearer ${getToken()}` } : {}) },
+    redirect: 'follow'
+  }).catch(() => null);
+  if (!res || !res.ok) return null;
+  const gz = Buffer.from(await res.arrayBuffer());
+  if (gz.length > MAX_TARBALL_BYTES) return null;
+  let tar;
+  try { tar = zlib.gunzipSync(gz); } catch { return null; }
+
+  const v2 = new Set();
+  const v1 = new Set();
+  let define = false;
+  let v1Signature = false;
+  let v2Signature = false;
+  let scanned = 0;
+  const prefix = subPath ? `${subPath.replace(/\/+$/, '')}/` : '';
+  for (const file of tarFiles(tar)) {
+    if (!file.name.startsWith(prefix) || !SOURCE_FILE_RE.test(file.name) || SKIP_DIR_RE.test(file.name) || file.data.length > 2 * 1024 * 1024) continue;
+    scanned++;
+    const markers = sourceMarkers(file.data.toString('utf8'));
+    markers.v2.forEach(m => v2.add(m));
+    markers.v1.forEach(m => v1.add(m));
+    define = define || markers.define;
+    v1Signature = v1Signature || markers.v1Signature;
+    v2Signature = v2Signature || markers.v2Signature;
+  }
+  // Plugin.define / an { id, setup } export is the V2 entry point; a bare V1 import without it is a V1 plugin
+  if (define && v2.size === 0) v2.add('Plugin.define');
+  if (!define && v2Signature && v2.size === 0) v2.add('V2 plugin object (id + setup)');
+  define = define || v2Signature;
+  if (define && v1.size) return { source: 'source', v2: [...v2, ...[...v1].map(m => `${m} (with Plugin.define)`)], v1: [] };
+  return { source: `source (${scanned} files)`, v2: [...v2], v1: [...v1], scanned, define, v1Signature };
+}
+
+/**
+ * Probe many entries at once. Network calls are batched.
+ * @param {{key: string, repo: string, path?: string, npm?: string, plugin?: boolean}[]} targets
+ *        plugin: true lets a legacy V1 hook signature in source (without Plugin.define) count as V1
+ * @param {object} [options]
+ * @param {boolean} [options.deep=true] - for still-unknown GitHub repos, download the tarball and scan source
+ * @returns {Promise<Map<string, {compat: string, evidence: string[]}>>}
+ */
+async function probeCompat(targets, { deep = true } = {}) {
+  const findings = new Map(targets.map(t => [t.key, []]));
+
+  // 1. npm packages
+  await Promise.all(targets.filter(t => t.npm).map(async t => {
+    try {
+      const doc = await getNpmLatest(t.npm);
+      if (doc) findings.get(t.key).push({ source: `npm ${t.npm}@${doc.version}`, ...manifestMarkers(doc) });
+    } catch { /* registry hiccup: fall through to repo sources */ }
+  }));
+
+  // 2. package.json files in GitHub repos
+  const github = targets
+    .map(t => ({ t, parsed: parseRepoUrl(t.repo) }))
+    .filter(({ parsed }) => parsed && parsed.host === 'github.com');
+
+  const firstRound = [];
+  for (const { t, parsed } of github) {
+    const base = t.path ? `${t.path.replace(/\/+$/, '')}/` : '';
+    firstRound.push({ key: t.key, owner: parsed.owner, name: parsed.name, path: `${base}package.json` });
+    if (!t.path) {
+      for (const dir of WORKSPACE_DIRS) firstRound.push({ key: t.key, owner: parsed.owner, name: parsed.name, path: dir, tree: true });
+    }
+  }
+  const files = await getFiles(firstRound);
+
+  const secondRound = [];
+  for (const req of firstRound) {
+    const obj = files.get(`${req.owner}/${req.name}:${req.path}`);
+    if (!obj) continue;
+    if (req.tree) {
+      (obj.entries || []).filter(e => e.type === 'tree').slice(0, MAX_WORKSPACE_PACKAGES).forEach(e => {
+        secondRound.push({ key: req.key, owner: req.owner, name: req.name, path: `${req.path}/${e.name}/package.json` });
+      });
+    } else if (obj.text) {
+      const manifest = safeJson(obj.text);
+      if (manifest) findings.get(req.key).push({ source: req.path, ...manifestMarkers(manifest) });
+    }
+  }
+  const workspaceFiles = await getFiles(secondRound);
+  for (const req of secondRound) {
+    const obj = workspaceFiles.get(`${req.owner}/${req.name}:${req.path}`);
+    const manifest = obj && obj.text && safeJson(obj.text);
+    if (manifest) findings.get(req.key).push({ source: req.path, ...manifestMarkers(manifest) });
+  }
+
+  // 3. Gists: read the source files directly
+  for (const t of targets) {
+    const gist = String(t.repo).match(/^https:\/\/gist\.github\.com\/[^/]+\/([0-9a-f]+)/);
+    if (!gist) continue;
+    const { status, data } = await rest(`/gists/${gist[1]}`);
+    if (status !== 200 || !data || !data.files) continue;
+    for (const [name, file] of Object.entries(data.files)) {
+      const markers = name === 'package.json' ? manifestMarkers(safeJson(file.content) || {}) : sourceMarkers(file.content || '');
+      findings.get(t.key).push({ source: `gist ${name}`, v2: markers.v2, v1: markers.v1 });
+    }
+  }
+
+  // 4. Deep scan of source for anything not yet confirmed V2 (a V1 types dependency can sit next to a
+  //    dependency-free V2 setup export, so V1 verdicts are re-checked too)
+  if (deep) {
+    for (const { t, parsed } of github) {
+      if (verdict(findings.get(t.key)).compat === 'v2') continue;
+      const scanned = await scanSource(parsed, t.path);
+      if (!scanned) continue;
+      if (t.plugin && !scanned.v2.length && !scanned.v1.length && scanned.v1Signature && verdict(findings.get(t.key)).compat === 'unknown') {
+        scanned.v1 = ['legacy V1 plugin function/hooks without Plugin.define'];
+      }
+      findings.get(t.key).push(scanned);
+    }
+  }
+
+  const results = new Map();
+  for (const t of targets) results.set(t.key, verdict(findings.get(t.key)));
+  return results;
+}
+
+module.exports = { dependencies, manifestMarkers, probeCompat, scanSource, sourceMarkers, tarFiles, verdict };

scripts/utils/github.js

@@ -0,0 +1,168 @@
+/**
+ * Minimal GitHub and npm API helpers (Node 20+ global fetch, no extra dependencies).
+ *
+ * Auth: GITHUB_TOKEN or GH_TOKEN, falling back to `gh auth token` for local runs.
+ */
+
+const { execFileSync } = require('child_process');
+
+let cachedToken;
+
+function getToken() {
+  if (cachedToken !== undefined) return cachedToken;
+  cachedToken = process.env.GITHUB_TOKEN || process.env.GH_TOKEN || '';
+  if (!cachedToken) {
+    try {
+      cachedToken = execFileSync('gh', ['auth', 'token'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    } catch {
+      cachedToken = '';
+    }
+  }
+  return cachedToken;
+}
+
+function headers(extra = {}) {
+  const token = getToken();
+  return {
+    'User-Agent': 'awesome-opencode-bot',
+    Accept: 'application/vnd.github+json',
+    ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    ...extra
+  };
+}
+
+async function fetchWithRetry(url, options = {}, attempts = 5) {
+  for (let attempt = 1; ; attempt++) {
+    try {
+      const res = await fetch(url, options);
+      if ([429, 502, 503, 504].includes(res.status) && attempt < attempts) {
+        const retryAfter = Number(res.headers.get('retry-after'));
+        await new Promise(r => setTimeout(r, (retryAfter > 0 ? retryAfter : 2 ** attempt) * 1000));
+        continue;
+      }
+      return res;
+    } catch (err) {
+      if (attempt >= attempts) throw err;
+      await new Promise(r => setTimeout(r, 1000 * attempt));
+    }
+  }
+}
+
+/**
+ * Run a GraphQL query. Partial data is returned even when some aliases error (e.g. repo not found).
+ * @param {string} query
+ * @param {object} [variables]
+ * @returns {Promise<object>} data
+ */
+async function graphql(query, variables = {}) {
+  const res = await fetchWithRetry('https://api.github.com/graphql', {
+    method: 'POST',
+    headers: headers({ 'Content-Type': 'application/json' }),
+    body: JSON.stringify({ query, variables })
+  });
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok && !body.data) {
+    throw new Error(`GitHub GraphQL ${res.status}: ${body.message || JSON.stringify(body.errors || body)}`);
+  }
+  const fatal = (body.errors || []).filter(e => e.type !== 'NOT_FOUND' && e.type !== 'FORBIDDEN');
+  if (!body.data && fatal.length) {
+    throw new Error(`GitHub GraphQL error: ${fatal.map(e => e.message).join('; ')}`);
+  }
+  return body.data || {};
+}
+
+/**
+ * GitHub REST request.
+ * @param {string} route - e.g. "/repos/o/r" or a full URL
+ * @param {object} [options] - { method, body }
+ * @returns {Promise<{status: number, data: any}>}
+ */
+async function rest(route, { method = 'GET', body } = {}) {
+  const url = route.startsWith('http') ? route : `https://api.github.com${route}`;
+  const res = await fetchWithRetry(url, {
+    method,
+    headers: headers(body ? { 'Content-Type': 'application/json' } : {}),
+    body: body ? JSON.stringify(body) : undefined
+  });
+  const text = await res.text();
+  let data = text;
+  try { data = text ? JSON.parse(text) : null; } catch { /* non-JSON body */ }
+  return { status: res.status, data };
+}
+
+const gqlString = s => JSON.stringify(String(s));
+
+/**
+ * Fetch repository metadata for many repos in batched GraphQL queries.
+ * @param {{owner: string, name: string}[]} repos
+ * @returns {Promise<Map<string, object|null>>} keyed by "owner/name" (as given); null when not found
+ */
+async function getRepos(repos, { batchSize = 60 } = {}) {
+  const result = new Map();
+  const unique = [...new Map(repos.map(r => [`${r.owner}/${r.name}`, r])).values()];
+  for (let i = 0; i < unique.length; i += batchSize) {
+    const chunk = unique.slice(i, i + batchSize);
+    const fields = chunk.map((r, j) => `r${j}: repository(owner: ${gqlString(r.owner)}, name: ${gqlString(r.name)}) {
+      nameWithOwner url isArchived isFork isPrivate pushedAt stargazerCount description
+      licenseInfo { spdxId } defaultBranchRef { name }
+    }`).join('\n');
+    const data = await graphql(`query { ${fields} }`);
+    chunk.forEach((r, j) => result.set(`${r.owner}/${r.name}`, data[`r${j}`] || null));
+  }
+  return result;
+}
+
+/**
+ * Read text files from repos at HEAD in batched GraphQL queries.
+ * @param {{owner: string, name: string, path: string}[]} requests
+ * @returns {Promise<Map<string, {text?: string, entries?: {name: string, type: string}[]}|null>>}
+ *          keyed by "owner/name:path"; tree paths return entries
+ */
+async function getFiles(requests, { batchSize = 60 } = {}) {
+  const result = new Map();
+  for (let i = 0; i < requests.length; i += batchSize) {
+    const chunk = requests.slice(i, i + batchSize);
+    const fields = chunk.map((r, j) => `f${j}: repository(owner: ${gqlString(r.owner)}, name: ${gqlString(r.name)}) {
+      object(expression: ${gqlString(`HEAD:${r.path}`)}) {
+        ... on Blob { text isTruncated }
+        ... on Tree { entries { name type } }
+      }
+    }`).join('\n');
+    const data = await graphql(`query { ${fields} }`);
+    chunk.forEach((r, j) => {
+      const obj = data[`f${j}`] && data[`f${j}`].object;
+      result.set(`${r.owner}/${r.name}:${r.path}`, obj || null);
+    });
+  }
+  return result;
+}
+
+/**
+ * Fetch the latest published version document of an npm package.
+ * @param {string} pkg
+ * @returns {Promise<object|null>} null when the package does not exist
+ */
+async function getNpmLatest(pkg) {
+  const res = await fetchWithRetry(`https://registry.npmjs.org/${pkg.replace('/', '%2F')}/latest`, {
+    headers: { 'User-Agent': 'awesome-opencode-bot', Accept: 'application/json' }
+  });
+  if (res.status === 404) return null;
+  if (!res.ok) throw new Error(`npm registry ${res.status} for ${pkg}`);
+  return res.json();
+}
+
+/**
+ * Weekly downloads for an npm package (0 when unknown).
+ * @param {string} pkg
+ * @returns {Promise<number>}
+ */
+async function getNpmWeeklyDownloads(pkg) {
+  const res = await fetchWithRetry(`https://api.npmjs.org/downloads/point/last-week/${pkg}`, {
+    headers: { 'User-Agent': 'awesome-opencode-bot' }
+  });
+  if (!res.ok) return 0;
+  const body = await res.json().catch(() => ({}));
+  return body.downloads || 0;
+}
+
+module.exports = { getFiles, getNpmLatest, getNpmWeeklyDownloads, getRepos, getToken, graphql, rest };

scripts/utils/pr-checks.js

@@ -0,0 +1,152 @@
+/**
+ * Pull request analysis shared by:
+ *   - scripts/check-pr.js  (the required "validate" check; runs the PR's own code)
+ *   - scripts/triage.js    (pull_request_target; trusted base code, PR files read via the API)
+ *   - scripts/reprobe.js   (nightly re-check of PRs held for V2 migration)
+ */
+
+const path = require('path');
+const yaml = require('js-yaml');
+const { CATEGORIES, canonicalKey, checkCatalog } = require('./catalog');
+const { probeCompat } = require('./compat');
+
+// Generated files a PR must never edit by hand
+const GENERATED_FILES = ['README.md', 'dist/registry.json'];
+const DATA_FILE_RE = new RegExp(`^data/(${CATEGORIES.join('|')})/[^/]+\\.yaml$`);
+
+const LABELS = {
+  needsV2: 'needs-v2',
+  needsMetadata: 'needs-metadata',
+  needsHuman: 'needs-human',
+  ready: 'ready'
+};
+
+/**
+ * Analyze a PR's changes.
+ * @param {object} input
+ * @param {{path: string, status: string, content?: string, baseContent?: string}[]} input.changes
+ *        status is one of added | modified | removed | renamed; content is the new file text for data files
+ * @param {object[]} input.baseEntries - catalog entries on the base branch (from loadCatalog)
+ * @param {boolean} [input.probe=true] - run the network V2 probe for plugin entries
+ * @returns {Promise<{errors: object[], warnings: object[], entries: object[], labels: string[], categories: string[], dataChanged: boolean}>}
+ */
+async function analyzePullRequest({ changes, baseEntries, probe = true }) {
+  const errors = [];
+  const warnings = [];
+
+  for (const change of changes) {
+    if (GENERATED_FILES.includes(change.path) && change.status !== 'removed') {
+      errors.push({
+        file: change.path,
+        kind: 'metadata',
+        message: `${change.path} is generated from data/ and must not be edited by hand. Add or edit data/<category>/<name>.yaml instead (see contributing.md, or use the "Add an entry" issue form).`
+      });
+    }
+  }
+
+  // Overlay the PR's data changes onto the base catalog
+  const head = new Map(baseEntries.map(e => [e.file, e]));
+  const changed = [];
+  for (const change of changes.filter(c => DATA_FILE_RE.test(c.path))) {
+    head.delete(change.path);
+    if (change.status === 'removed') continue;
+    const [, category, fileName] = change.path.split('/');
+    let data;
+    try {
+      data = yaml.load(change.content || '');
+    } catch (err) {
+      errors.push({ file: change.path, kind: 'metadata', message: `invalid YAML: ${err.reason || err.message}. Quote values that contain ": " (e.g. tagline: "A: B").` });
+      continue;
+    }
+    if (!data || typeof data !== 'object' || Array.isArray(data)) {
+      errors.push({ file: change.path, kind: 'metadata', message: 'file is empty or not a YAML mapping' });
+      continue;
+    }
+    const entry = { category, id: fileName.replace(/\.yaml$/, ''), file: change.path, data, status: change.status };
+    head.set(change.path, entry);
+    changed.push(entry);
+
+    if (change.status === 'modified' && change.baseContent) {
+      try {
+        const before = yaml.load(change.baseContent);
+        if (before && before.repo && data.repo && canonicalKey(before) !== canonicalKey(data)) {
+          warnings.push({ file: change.path, kind: 'human', message: `changes this entry's target from ${before.repo} to ${data.repo}. If this is a different project, add a new file instead of reusing an existing filename.` });
+        }
+      } catch { /* base file was already broken */ }
+    }
+  }
+
+  // YAML files outside data/<category>/
+  for (const change of changes) {
+    if (change.path.startsWith('data/') && change.path.endsWith('.yaml') && !DATA_FILE_RE.test(change.path) && !change.path.startsWith('data/examples/') && change.status !== 'removed') {
+      errors.push({ file: change.path, kind: 'metadata', message: `entries must live in data/<category>/<name>.yaml where category is one of: ${CATEGORIES.join(', ')}` });
+    }
+    if (change.path.startsWith('data/') && !change.path.endsWith('.yaml') && !change.path.endsWith('.json') && !change.path.endsWith('.md') && change.status !== 'removed') {
+      errors.push({ file: change.path, kind: 'metadata', message: 'entry files must use the .yaml extension' });
+    }
+  }
+
+  // Schema and cross-entry rules, reported for the files this PR touches
+  const touched = new Set(changed.map(e => e.file));
+  for (const problem of checkCatalog([...head.values()])) {
+    if (touched.has(problem.file) || [...touched].some(f => problem.message.includes(f))) {
+      errors.push({ ...problem, kind: 'metadata' });
+    }
+  }
+
+  // V2 compatibility for plugin entries
+  const plugins = changed.filter(e => e.category === 'plugins' && e.data.repo);
+  if (probe && plugins.length) {
+    const results = await probeCompat(plugins.map(e => ({ key: e.file, repo: e.data.repo, path: e.data.path, npm: e.data.npm, plugin: true })));
+    for (const entry of plugins) {
+      const { compat, evidence } = results.get(entry.file);
+      entry.probe = { compat, evidence };
+      const detail = evidence.length ? ` (${evidence.join('; ')})` : '';
+      if (compat === 'v1' && entry.status === 'added') {
+        errors.push({ file: entry.file, kind: 'v2', message: `targets the legacy V1 plugin API${detail}. New plugins must be built on OpenCode V2: depend on @opencode/plugin and export Plugin.define({ id, setup(ctx) }). This PR is re-checked nightly and unblocks itself once the repo is migrated.` });
+      } else if (compat !== 'unknown' && entry.data.compat && entry.data.compat !== compat) {
+        errors.push({ file: entry.file, kind: compat === 'v1' ? 'v2' : 'metadata', message: `declares compat: ${entry.data.compat} but the package was detected as ${compat}${detail}. Set compat: ${compat}.` });
+      } else if (compat === 'unknown') {
+        warnings.push({ file: entry.file, kind: 'human', message: `could not verify V2 compatibility automatically${detail}. Set \`npm\` (package name) or \`path\` (monorepo folder) so the check can find package.json; otherwise a maintainer will verify by hand.` });
+      }
+    }
+  }
+
+  const categories = [...new Set(changes.filter(c => DATA_FILE_RE.test(c.path)).map(c => c.path.split('/')[1]))];
+  const labels = [];
+  if (errors.some(e => e.kind === 'v2')) labels.push(LABELS.needsV2);
+  if (errors.some(e => e.kind === 'metadata')) labels.push(LABELS.needsMetadata);
+  if (warnings.length) labels.push(LABELS.needsHuman);
+  if (!errors.length && !warnings.length && changed.length) labels.push(LABELS.ready);
+
+  return { errors, warnings, entries: changed, labels, categories, dataChanged: categories.length > 0 };
+}
+
+/**
+ * Markdown report for a job summary or PR comment.
+ * @param {object} result - analyzePullRequest() result
+ * @returns {string}
+ */
+function formatReport(result) {
+  const lines = [];
+  if (!result.dataChanged && !result.errors.length) {
+    return '✅ No catalog entries changed.';
+  }
+  lines.push(result.errors.length ? '### ❌ Catalog checks failed' : result.warnings.length ? '### ⚠️ Catalog checks passed with notes' : '### ✅ Catalog checks passed');
+  const section = (title, items) => {
+    if (!items.length) return;
+    lines.push('', `**${title}**`, '');
+    for (const item of items) lines.push(`- \`${item.file}\`: ${item.message}`);
+  };
+  section('Must fix', result.errors);
+  section('Needs a maintainer', result.warnings);
+  const verified = result.entries.filter(e => e.probe);
+  if (verified.length) {
+    lines.push('', '**V2 compatibility**', '', '| Entry | Detected | Evidence |', '| :--- | :--- | :--- |');
+    for (const e of verified) lines.push(`| \`${path.basename(e.file)}\` | ${e.probe.compat} | ${e.probe.evidence.join('; ').replace(/\|/g, '\\|') || '—'} |`);
+  }
+  lines.push('', '<sub>Entry format: [contributing.md](https://github.com/Heretek-AI/awesome-opencode/blob/main/contributing.md) · Catalog policy: [docs/policy.md](https://github.com/Heretek-AI/awesome-opencode/blob/main/docs/policy.md)</sub>');
+  return lines.join('\n');
+}
+
+module.exports = { DATA_FILE_RE, GENERATED_FILES, LABELS, analyzePullRequest, formatReport };

scripts/utils/repo.js

@@ -0,0 +1,157 @@
+/**
+ * Helpers for acting on this repository's issues and pull requests via the GitHub REST API.
+ */
+
+const { rest } = require('./github');
+
+const REPO = process.env.GITHUB_REPOSITORY || 'Heretek-AI/awesome-opencode';
+
+// Labels the bots manage: name -> [color, description]
+const BOT_LABELS = {
+  'needs-v2': ['d93f0b', 'Plugin targets the legacy V1 API; re-checked nightly'],
+  'needs-metadata': ['fbca04', 'Entry fails schema or catalog rules'],
+  'needs-human': ['c5def5', 'Automated checks could not decide; maintainer review needed'],
+  ready: ['0e8a16', 'All automated checks pass'],
+  submission: ['1d76db', 'Entry submitted through the issue form'],
+  scout: ['5319e7', 'Weekly discovery of V2 plugin candidates'],
+  health: ['b60205', 'Catalog link-rot and maintenance tracking'],
+  'v1-sunset': ['e99695', 'V1-only plugin scheduled for removal at the sunset date'],
+  'category: plugins': ['bfdadc', 'Touches data/plugins'],
+  'category: themes': ['bfdadc', 'Touches data/themes'],
+  'category: agents': ['bfdadc', 'Touches data/agents'],
+  'category: projects': ['bfdadc', 'Touches data/projects'],
+  'category: resources': ['bfdadc', 'Touches data/resources']
+};
+
+const TRIAGE_LABELS = ['needs-v2', 'needs-metadata', 'needs-human', 'ready'];
+
+async function check(promise, what) {
+  const res = await promise;
+  if (res.status >= 300) throw new Error(`${what} failed: HTTP ${res.status} ${JSON.stringify(res.data).slice(0, 300)}`);
+  return res.data;
+}
+
+/**
+ * Create any missing bot labels.
+ */
+async function ensureLabels(names = Object.keys(BOT_LABELS)) {
+  for (const name of names) {
+    const [color, description] = BOT_LABELS[name] || ['ededed', ''];
+    const res = await rest(`/repos/${REPO}/labels`, { method: 'POST', body: { name, color, description } });
+    if (res.status !== 201 && res.status !== 422) throw new Error(`create label ${name}: HTTP ${res.status}`);
+  }
+}
+
+/**
+ * Make the triage labels on an issue/PR exactly `wanted` (other labels untouched).
+ */
+async function setTriageLabels(number, wanted, current) {
+  const have = new Set(current);
+  const add = wanted.filter(l => !have.has(l));
+  const remove = TRIAGE_LABELS.filter(l => have.has(l) && !wanted.includes(l));
+  if (add.length) await ensureLabels(add);
+  if (add.length) await check(rest(`/repos/${REPO}/issues/${number}/labels`, { method: 'POST', body: { labels: add } }), 'add labels');
+  for (const label of remove) {
+    await rest(`/repos/${REPO}/issues/${number}/labels/${encodeURIComponent(label)}`, { method: 'DELETE' });
+  }
+  return { add, remove };
+}
+
+async function addLabels(number, labels) {
+  if (!labels.length) return;
+  await ensureLabels(labels.filter(l => BOT_LABELS[l]));
+  await check(rest(`/repos/${REPO}/issues/${number}/labels`, { method: 'POST', body: { labels } }), 'add labels');
+}
+
+async function listComments(number) {
+  const comments = [];
+  for (let page = 1; ; page++) {
+    const batch = await check(rest(`/repos/${REPO}/issues/${number}/comments?per_page=100&page=${page}`), 'list comments');
+    comments.push(...batch);
+    if (batch.length < 100) return comments;
+  }
+}
+
+/**
+ * Create or update the single bot comment identified by `marker`.
+ */
+async function upsertComment(number, marker, body) {
+  const full = `${marker}\n${body}`;
+  const existing = (await listComments(number)).find(c => c.body && c.body.startsWith(marker));
+  if (existing) {
+    if (existing.body === full) return existing;
+    return check(rest(`/repos/${REPO}/issues/comments/${existing.id}`, { method: 'PATCH', body: { body: full } }), 'update comment');
+  }
+  return check(rest(`/repos/${REPO}/issues/${number}/comments`, { method: 'POST', body: { body: full } }), 'create comment');
+}
+
+async function comment(number, body) {
+  return check(rest(`/repos/${REPO}/issues/${number}/comments`, { method: 'POST', body: { body } }), 'create comment');
+}
+
+/**
+ * All open pull requests (with head repo/ref/sha and labels).
+ */
+async function listOpenPulls() {
+  const pulls = [];
+  for (let page = 1; ; page++) {
+    const batch = await check(rest(`/repos/${REPO}/pulls?state=open&per_page=100&page=${page}`), 'list pulls');
+    pulls.push(...batch);
+    if (batch.length < 100) return pulls;
+  }
+}
+
+/**
+ * Files changed in a PR, with the new text of data files read at the PR head.
+ * @returns {Promise<{path: string, status: string, content?: string, baseContent?: string}[]>}
+ */
+async function pullChanges(pull, { wantContent = p => p.startsWith('data/') && p.endsWith('.yaml') } = {}) {
+  const files = [];
+  for (let page = 1; ; page++) {
+    const batch = await check(rest(`/repos/${REPO}/pulls/${pull.number}/files?per_page=100&page=${page}`), 'list PR files');
+    files.push(...batch);
+    if (batch.length < 100) break;
+  }
+  const headRepo = (pull.head.repo && pull.head.repo.full_name) || REPO;
+  const changes = [];
+  for (const f of files) {
+    if (f.status === 'renamed') {
+      changes.push({ path: f.previous_filename, status: 'removed' });
+      changes.push({ path: f.filename, status: 'added' });
+    } else {
+      changes.push({ path: f.filename, status: f.status === 'changed' ? 'modified' : f.status });
+    }
+  }
+  for (const change of changes) {
+    if (change.status === 'removed' || !wantContent(change.path)) continue;
+    change.content = await fileText(headRepo, change.path, pull.head.sha);
+    if (change.status === 'modified') change.baseContent = await fileText(REPO, change.path, pull.base.sha);
+  }
+  return changes;
+}
+
+async function fileText(repo, filePath, ref) {
+  const res = await rest(`/repos/${repo}/contents/${filePath.split('/').map(encodeURIComponent).join('/')}?ref=${ref}`);
+  if (res.status !== 200 || !res.data || typeof res.data.content !== 'string') return undefined;
+  return Buffer.from(res.data.content, 'base64').toString('utf8');
+}
+
+/**
+ * Re-run the latest "validate" workflow run for a commit, or dispatch one on a same-repo branch.
+ */
+async function revalidate(pull) {
+  const runs = await check(rest(`/repos/${REPO}/actions/workflows/validate-pr.yml/runs?head_sha=${pull.head.sha}&per_page=5`), 'list runs');
+  const run = runs.workflow_runs && runs.workflow_runs[0];
+  if (run && run.status === 'completed') {
+    return rest(`/repos/${REPO}/actions/runs/${run.id}/rerun`, { method: 'POST' });
+  }
+  if (!run && pull.head.repo && pull.head.repo.full_name === REPO) {
+    return rest(`/repos/${REPO}/actions/workflows/validate-pr.yml/dispatches`, { method: 'POST', body: { ref: pull.head.ref } });
+  }
+  return null;
+}
+
+module.exports = {
+  BOT_LABELS, REPO, TRIAGE_LABELS,
+  addLabels, comment, ensureLabels, fileText, listComments, listOpenPulls, pullChanges, revalidate, setTriageLabels, upsertComment
+};