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

src/databases/marketplace_db/src/plugins/queries.ts

@@ -17,6 +17,8 @@ export type CatalogueEntry = {
   platform: string;
   label: string;
   summary: string;
+  /** What it is for. Always present, `[]` for a plugin that declares none, so callers need no guard. */
+  tags: string[];
   color: string;
   tile?: 'badge' | 'bare';
   iconUrl?: string;
@@ -53,6 +55,9 @@ function toCatalogueEntry(row: Row): CatalogueEntry | null {
     platform: m.platform,
     label: m.label,
     summary: m.summary,
+    // Normalised to an array here rather than at every call site: the column is nullable because it
+    // arrived after the rows did, and null vs [] is a distinction no consumer of this wants to carry.
+    tags: Array.isArray(m.tags) ? (m.tags as string[]) : [],
     color: m.color ?? '#94a3b8',
     ...(m.tile ? { tile: m.tile as 'badge' | 'bare' } : {}),
     ...(m.iconUrl ? { iconUrl: m.iconUrl } : {}),

src/databases/marketplace_db/src/plugins/schema.ts

@@ -85,6 +85,20 @@ export const pluginMetadata = pgTable(
     /** A lucide glyph NAME, for a plugin that ships no artwork. `iconUrl` wins where both are given. */
     icon: text('icon'),
 
+    /**
+     * What the plugin is for — the store's filter, and the only field here that exists for BROWSING
+     * rather than for installing.
+     *
+     * jsonb like the shapes below it, and for the same reason: it is read as a unit and rendered as a
+     * unit. A join table would buy filtering in SQL, which matters at a scale a hand-curated catalogue of
+     * twenty-one is nowhere near — and it would cost a migration every time the vocabulary changes, which
+     * is exactly the thing expected to change.
+     *
+     * Nullable because it arrived after the rows did. Null and `[]` mean the same thing here: no filter
+     * shows it.
+     */
+    tags: jsonb('tags'),
+
     permissions: jsonb('permissions').notNull(),
     osDependencies: jsonb('os_dependencies'),
     /** `{ api, schema, sidecar, web }` — what the plugin ships. */