docs: publish a static registry for vuetify add (#721)

* docs: publish a static registry for vuetify add

v0 ships a real package, so a consumer can already install it — what they
cannot get is a working, styled file, because a bare import of a headless
primitive renders nothing. This publishes the docs examples as a registry a
CLI can read, so `vuetify add dialog` writes a runnable demo.

The source of truth is the `::: gn-example` directive already present on every
feature page: it declares an ordered file manifest, external `@import`
dependencies, a title, and prose. Building on it means the registry inherits
the curation instead of guessing from a directory listing, and it picks up the
supporting `.ts` files that `examples.json` drops today.

Emits `registry/index.json` (a 30 KB catalog, versus the 521 KB examples.json
blob, so resolving a name is cheap), `registry/{type}/{name}.json` per item,
and `registry/tokens.json` carrying the semantic token contract plus the
UnoCSS and Tailwind snippets that map it — one source of truth the CLI reads
rather than a copy that drifts.

Examples may only use tokens the create-vuetify0 templates map, since anything
else renders unstyled once copied out of the docs site. Generation now fails a
production build on a violation; `bg-accent` in two observer examples is
swapped for portable colors accordingly.

* refactor(theme): move the semantic color contract into packages/0

The list of semantic colors was declared in the docs registry builder, but the
guarantee is the theme layer's — those are the names `createThemePlugin` emits
and a consumer maps onto utility classes. Leaving it in `apps/docs/build`
implied the docs site owned it, when the docs site is one of three consumers
alongside the create-vuetify0 templates and the CLI, all synced by hand.

It moves to `packages/0/src/theme/tokens.ts`, imported by the builder the same
way `maturity.json` already is. The generation itself stays in `apps/docs` —
it reads `src/pages` and `src/examples`, so hoisting it into a package would
have a package reaching up into an app to read its content.

Deliberately not exported from `@vuetify/v0/theme`. Nothing outside this repo
consumes it, and making it public is a minor bump that belongs with the change
that gives the templates a reason to import it.

Emitted registry is unchanged: 93 items, 144 examples, 20 tokens.

* docs(registry): harden vuetify add portability

Warn on case-colliding basenames (fatal in prod), skip incomplete multi-file
blocks, invalidate the dev memo on page/example edits, and surface Uno icon
utilities as soft deps. Rename six PascalCase/entry pairs that collided on
case-insensitive filesystems.

* docs(registry): close review gaps in the add registry builder

Derive example ids and dirs from the entry file, join multi-line prose,
skip fence-local paths, confine reads to the examples root, reload
maturity/package.json per build, and broaden dev-cache invalidation.

* docs(registry): shape icons as collections for install soft-deps

Emit icons.collections (lucide, mdi, …) as the actionable install unit and
keep classes for audit. Frame the module as the official seed catalog for
the local component-library lifecycle.

* docs(registry): include Plugin and Transformer docs pages

features.category Plugin/Transformer were skipped (only Component/Composable
matched), so useTheme and the rest of the plugins family never entered the
seed catalog. Map them onto the composables bucket where their examples live.

* docs(registry): plugin install recipes and CORS for playground

Emit install recipes (factory/label/file) on plugin items so the CLI
can wire create*Plugin without a hard-coded map, include install-only
plugins with zero examples, and allow cross-origin /registry/* reads
from the playground.

* docs(registry): harden path confinement and install recipe shape

Reject path segments (..), resolve examples through realpath so git
symlinks cannot smuggle host files into the payload, validate feature
names and create*Plugin install recipes before emit, and restrict the
dev /registry middleware to GET (+ OPTIONS).

* docs(registry): tighten install label and catalog integrity

Sanitize plugin install labels to plain identifiers, warn on duplicate
type/name keys, align nginx CORS headers with the dev middleware, and
drop a stale comment about reflected 404 paths.

Author: johnleider

apps/docs/build/generate-registry.ts

@@ -0,0 +1,169 @@
+/**
+ * Vite plugin to publish the official seed registry for `vuetify add`.
+ *
+ * Serves `/registry/*` in dev and emits the same files as build assets so the
+ * CLI can read a plain static origin. This is the first-party catalog of docs
+ * examples — not a user's library (that is `vuetify.json` + optional self-hosted
+ * registries later).
+ *
+ * Endpoints:
+ * - `/registry/index.json`         slim catalog (names, types, example ids)
+ * - `/registry/tokens.json`        semantic token contract + config snippets
+ * - `/registry/{type}/{name}.json` one item, file contents included
+ */
+
+import { build, contract } from './registry'
+
+// Types
+import type { Registry } from './registry'
+import type { Plugin } from 'vite'
+
+/**
+ * Docs-only tokens in an example render unstyled once copied into a consumer
+ * project, so they fail the production build rather than shipping broken. Dev
+ * only warns — an author mid-edit should not be blocked.
+ */
+function report (warnings: string[], fatal: boolean) {
+  if (warnings.length === 0) return
+
+  for (const warning of warnings) console.warn(warning)
+
+  if (fatal) {
+    throw new Error(
+      `[generate-registry] ${warnings.length} registry problem(s). `
+      + `See warnings above (missing files, case collisions, docs-only tokens, …).`,
+    )
+  }
+}
+
+export default function generateRegistryPlugin (): Plugin {
+  let registry: Registry | null = null
+  let pending: Promise<Registry> | null = null
+  let dev = false
+
+  async function get () {
+    if (registry) return registry
+    pending ??= (async () => {
+      try {
+        const result = await build()
+        console.log(`[generate-registry] ${result.items.length} items`)
+        report(result.warnings, !dev)
+        return result
+      } catch (error) {
+        pending = null
+        throw error
+      }
+    })()
+
+    registry = await pending
+    return registry
+  }
+
+  return {
+    name: 'generate-registry',
+
+    configureServer (server) {
+      dev = true
+
+      // Mirror generate-nav / generate-llms-full: drop the memo when source
+      // pages or examples change so a local CLI against the dev origin sees
+      // fresh bodies without a server restart. `add`/`unlink` matter when an
+      // author creates or deletes an example file mid-session.
+      function invalidate (file: string) {
+        // Vite may report Windows paths with `\`; normalize before matching.
+        const normalized = file.replaceAll('\\', '/')
+        const data = normalized.endsWith('maturity.json')
+          || normalized.endsWith('package.json')
+          || normalized.endsWith('uno.config.ts')
+        const docs = (normalized.includes('/pages/') || normalized.includes('/examples/'))
+          && (normalized.endsWith('.md') || normalized.endsWith('.vue') || normalized.endsWith('.ts'))
+        if (!data && !docs) return
+        registry = null
+        pending = null
+      }
+
+      for (const event of ['change', 'add', 'unlink'] as const) {
+        server.watcher.on(event, invalidate)
+      }
+
+      server.middlewares.use(async (req, res, next) => {
+        const url = req.url?.split('?')[0]
+        if (!url?.startsWith('/registry/') || !url.endsWith('.json')) return next()
+
+        // Playground (v0play / localhost) fetches this origin cross-site.
+        res.setHeader('Access-Control-Allow-Origin', '*')
+        res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS')
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type')
+        res.setHeader('Allow', 'GET, OPTIONS')
+
+        if (req.method === 'OPTIONS') {
+          res.statusCode = 204
+          res.end()
+          return
+        }
+
+        if (req.method !== 'GET') {
+          res.statusCode = 405
+          res.end('Method Not Allowed')
+          return
+        }
+
+        try {
+          const data = await get()
+          const path = url.slice('/registry/'.length, -'.json'.length)
+
+          const body = path === 'index'
+            ? data.index
+            : (path === 'tokens'
+                ? contract()
+                : data.items.find(item => `${item.type}/${item.name}` === path))
+
+          if (!body) {
+            res.statusCode = 404
+            res.end('Unknown registry item')
+            return
+          }
+
+          res.setHeader('Content-Type', 'application/json; charset=utf-8')
+          res.end(JSON.stringify(body))
+        } catch (error) {
+          console.error('[generate-registry] Error:', error)
+          res.statusCode = 500
+          res.end('Error generating registry')
+        }
+      })
+    },
+
+    async generateBundle (_, bundle) {
+      // Skip if this is the main entry (avoid duplicate emission)
+      if (Object.keys(bundle).some(k => k.includes('main.mjs'))) return
+
+      const data = await get()
+
+      this.emitFile({
+        type: 'asset',
+        fileName: 'registry/index.json',
+        source: JSON.stringify(data.index),
+      })
+
+      this.emitFile({
+        type: 'asset',
+        fileName: 'registry/tokens.json',
+        source: JSON.stringify(contract()),
+      })
+
+      for (const item of data.items) {
+        this.emitFile({
+          type: 'asset',
+          fileName: `registry/${item.type}/${item.name}.json`,
+          source: JSON.stringify(item),
+        })
+      }
+    },
+
+    buildEnd () {
+      registry = null
+      pending = null
+    },
+  }
+}