plugins say what they are for, and their checkouts stop lying about themselves

two things, and the second is why the first was painful.

TAGS. the marketplace is going to be browsed rather than scrolled: tags on the
left, the plugins carrying one on the right. a plugin declares its own in the
manifest and the catalogue caches it on sync, exactly as it already does for
label and summary — the alternative is editing a table every time a plugin
ships, and a plugin that cannot say what it is.

the vocabulary is CLOSED (PLUGIN_TAGS) because free text becomes homelab,
home-lab, Home Lab and selfhosted inside a month, and a filter list of synonyms
is worse than no filter. an unknown tag is refused at discovery BY NAME, so the
author is told which tag rather than which array index.

all 21 are tagged, each with a one-line note saying why, so a later disagreement
is with a stated reason rather than a mystery. every tag has at least three
plugins behind it — no filter opens onto an empty page.

PLUGINS:CHECK. getting one commit into 21 repositories failed seven times and
none of the reasons were about the commit: six remotes were HTTPS and cannot
authenticate unattended, three checkouts were behind their remote, one URL had
no .git suffix so the catalogue published a clone URL unlike every other, and
offscale's fetch refspec named a branch that does not exist.

that last one is why this is a script and not a habit. every command reported on
a phantom — `git push` said "Everything up-to-date" while the branch looked
diverged — and the repository was fine the whole time. twenty minutes spent in a
repo with nothing wrong with it.

none of it is visible until you try to push, which is the worst moment to learn
it: mid-task, across 21 repositories, and every failure looks like it is about
your change.

so it checks the facts with one right answer — remote URL, fetch refspec,
branch, upstream, dirty tree, ahead/behind — and exits non-zero. `--fix` is a
separate flag so running the check can never be what changes your tree, and
divergence is never auto-repaired because it needs a decision about content.

verified by breaking each case on purpose and watching it catch them.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Officer-Session: 656f5c85-e49a-4f1f-b9f3-042a04b4d043

scripts/marketplace-sync.ts

@@ -109,6 +109,11 @@ async function syncOne(dir: string): Promise<Sync | null> {
     platform: String(manifest.platform ?? '>=1.0.0'),
     label: String(manifest.label ?? appName),
     summary: String(manifest.summary ?? ''),
+    // Taken verbatim, NOT validated here. `manifestProblems` already refuses a tag outside the
+    // vocabulary at discovery, so anything reaching this point is either valid or belongs to a plugin
+    // the platform would not load anyway — and a sync that silently dropped a tag would be a catalogue
+    // quietly disagreeing with the repository it claims to mirror.
+    tags: Array.isArray(manifest.tags) ? manifest.tags : [],
     color: (manifest.color as string) ?? null,
     tile: (manifest.tile as string) ?? null,
     // Artwork lives in the repo, so the URL is built from the remote rather than stored by hand. Only

scripts/plugins-check.ts

@@ -0,0 +1,127 @@
+/*
+  Is every plugin checkout still a well-formed clone of its own repository?
+
+  ── Why a script and not care ──
+
+  On 2026-08-27 one commit had to go into all twenty-one plugin repos. Seven pushes failed, each for a
+  different reason, and none of the reasons had anything to do with the commit:
+
+    · six remotes were HTTPS, which cannot authenticate non-interactively — they simply hung and failed
+    · three checkouts were behind their published remote, so the push was rejected as non-fast-forward
+    · one (`offscale`) had a fetch refspec and an upstream naming a branch called `main` that does not
+      exist on the remote. That one is the reason this file exists: every command reported on a phantom.
+      `git push` said "Everything up-to-date" while `git status` said the branch had diverged, and the
+      repository was actually fine. Twenty minutes went into a repo with nothing wrong with it.
+    · one remote URL had no `.git` suffix, so the catalogue published a clone URL unlike every other
+
+  None of that is visible until you try to push, which is the worst possible moment to find out — you are
+  mid-task, across twenty-one repositories, and the failures look like they are about your change.
+
+  ── What it checks, and what it deliberately does not ──
+
+  Only mechanical facts with one right answer: the remote's URL form, the fetch refspec, the branch, its
+  upstream, and whether the checkout has diverged. It does not judge content, does not fetch by default
+  (that would make a local check depend on the network), and never writes — `--fix` is a separate flag so
+  that running the check can never be the thing that changes your tree.
+*/
+
+import { readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const PLUGINS_DIR = join(import.meta.dir, '..', 'plugins');
+const HOST = 'git@gitea.officer.dev';
+const BRANCH = 'master';
+const REFSPEC = '+refs/heads/*:refs/remotes/origin/*';
+
+const FIX = process.argv.includes('--fix');
+const FETCH = process.argv.includes('--fetch');
+
+const git = (dir: string, args: string[]): string | null => {
+  const p = Bun.spawnSync(['git', '-C', dir, ...args], { stdout: 'pipe', stderr: 'pipe' });
+  return p.exitCode === 0 ? p.stdout.toString().trim() : null;
+};
+
+type Problem = { plugin: string; what: string; fix?: () => void };
+const problems: Problem[] = [];
+
+const dirs = readdirSync(PLUGINS_DIR, { withFileTypes: true })
+  .filter((e) => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules')
+  .map((e) => e.name)
+  .filter((name) => existsSync(join(PLUGINS_DIR, name, '.git')))
+  .sort();
+
+for (const name of dirs) {
+  const dir = join(PLUGINS_DIR, name);
+  const expected = `${HOST}:plugins/${name}.git`;
+
+  // 1. The remote, exactly. SSH because that is what can push unattended, and `.git` because a URL unlike
+  //    every other is the one an installer trips over.
+  const url = git(dir, ['remote', 'get-url', 'origin']);
+  if (url !== expected) {
+    problems.push({
+      plugin: name,
+      what: `remote is ${url ?? 'missing'}, expected ${expected}`,
+      fix: () => void git(dir, ['remote', 'set-url', 'origin', expected]),
+    });
+  }
+
+  // 2. The fetch refspec. A narrowed one (a --single-branch clone) hides every other branch; a WRONG one
+  //    makes git report on a branch that does not exist, which is the failure that cost the most time.
+  const refspecs = (git(dir, ['config', '--get-all', 'remote.origin.fetch']) ?? '').split('\n').filter(Boolean);
+  if (refspecs.length !== 1 || refspecs[0] !== REFSPEC) {
+    problems.push({
+      plugin: name,
+      what: `fetch refspec is ${refspecs.join(' + ') || 'unset'}, expected ${REFSPEC}`,
+      fix: () => {
+        git(dir, ['config', '--unset-all', 'remote.origin.fetch']);
+        git(dir, ['config', '--add', 'remote.origin.fetch', REFSPEC]);
+      },
+    });
+  }
+
+  // 3. The branch, and what it tracks.
+  const branch = git(dir, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  if (branch !== BRANCH) {
+    problems.push({ plugin: name, what: `on branch ${branch ?? '?'}, expected ${BRANCH}` });
+    continue; // the checks below are all about this branch
+  }
+  const upstream = git(dir, ['config', '--get', `branch.${BRANCH}.merge`]);
+  if (upstream !== `refs/heads/${BRANCH}`) {
+    problems.push({
+      plugin: name,
+      what: `${BRANCH} tracks ${upstream ?? 'nothing'}, expected refs/heads/${BRANCH}`,
+      fix: () => void git(dir, ['branch', `--set-upstream-to=origin/${BRANCH}`, BRANCH]),
+    });
+  }
+
+  // 4. Uncommitted work, and divergence. Not fixable here — both need a human decision about the content.
+  const dirty = git(dir, ['status', '--porcelain']);
+  if (dirty) problems.push({ plugin: name, what: `${dirty.split('\n').length} uncommitted file(s)` });
+
+  if (FETCH) git(dir, ['fetch', '-q', 'origin']);
+  const counts = git(dir, ['rev-list', '--left-right', '--count', `origin/${BRANCH}...HEAD`]);
+  if (counts) {
+    const [behind, ahead] = counts.split(/\s+/).map(Number);
+    if (behind) problems.push({ plugin: name, what: `${behind} commit(s) behind origin/${BRANCH}` });
+    if (ahead) problems.push({ plugin: name, what: `${ahead} commit(s) NOT PUSHED` });
+  }
+}
+
+if (!problems.length) {
+  console.log(`plugins:check — ${dirs.length} plugin repositories, all well-formed`);
+  process.exit(0);
+}
+
+for (const p of problems) console.error(`  ${p.plugin}: ${p.what}`);
+
+if (FIX) {
+  const fixable = problems.filter((p) => p.fix);
+  for (const p of fixable) p.fix!();
+  console.error(`\nplugins:check --fix — repaired ${fixable.length} of ${problems.length}; re-run to confirm.`);
+  console.error('Divergence and uncommitted work are never repaired here: both need a decision about content.');
+} else {
+  console.error(
+    `\nplugins:check — ${problems.length} problem(s). \`bun run plugins:check --fix\` repairs the mechanical ones.`,
+  );
+}
+process.exit(1);