@crombolo/backoffice-host 0.0.0-stage → 0.9.1

package/plugin/umbraco-package.json

@@ -0,0 +1,298 @@
+{
+  "$schema": "../../backoffice-dist/dist/umbraco-package-schema.json",
+  "name": "Crombolo",
+  "id": "Crombolo.Core",
+  "version": "0.9.1",
+  "allowPublicAccess": false,
+  "extensions": [
+    {
+      "type": "sectionView",
+      "alias": "Crombolo.SectionView.Bundles.Marketplace",
+      "name": "Crombolo Packages Marketplace",
+      "element": "/crombolo-plugin/bundles-marketplace.js",
+      "weight": 300,
+      "overwrites": ["Umb.SectionView.Packages.Marketplace"],
+      "meta": {
+        "label": "Marketplace",
+        "pathname": "packages",
+        "icon": "icon-cloud"
+      },
+      "conditions": [
+        {
+          "alias": "Umb.Condition.SectionAlias",
+          "match": "Umb.Section.Packages"
+        }
+      ]
+    },
+    {
+      "type": "sectionView",
+      "alias": "Crombolo.SectionView.Bundles.Created",
+      "name": "Crombolo Created Bundles",
+      "element": "/crombolo-plugin/bundles-created.js",
+      "weight": 100,
+      "overwrites": ["Umb.SectionView.Packages.Builder"],
+      "meta": {
+        "label": "Created",
+        "pathname": "created",
+        "icon": "icon-files"
+      },
+      "conditions": [
+        {
+          "alias": "Umb.Condition.SectionAlias",
+          "match": "Umb.Section.Packages"
+        }
+      ]
+    },
+    {
+      "type": "sectionView",
+      "alias": "Crombolo.SectionView.Bundles.Installed",
+      "name": "Crombolo Installed Packages",
+      "element": "/crombolo-plugin/bundles-installed.js",
+      "weight": 200,
+      "overwrites": ["Umb.SectionView.Packages.Installed"],
+      "meta": {
+        "label": "Installed",
+        "pathname": "installed",
+        "icon": "icon-box"
+      },
+      "conditions": [
+        {
+          "alias": "Umb.Condition.SectionAlias",
+          "match": "Umb.Section.Packages"
+        }
+      ]
+    },
+    {
+      "type": "dashboard",
+      "alias": "Crombolo.Dashboard.Changes",
+      "name": "Crombolo Changes Dashboard",
+      "element": "/crombolo-plugin/changes-dashboard.js",
+      "weight": 5,
+      "meta": {
+        "label": "Changes",
+        "pathname": "changes"
+      },
+      "conditions": [
+        {
+          "alias": "Umb.Condition.SectionAlias",
+          "match": "Umb.Section.Settings"
+        }
+      ]
+    },
+    {
+      "type": "dashboard",
+      "alias": "Crombolo.Dashboard.Welcome",
+      "name": "Crombolo Welcome Dashboard",
+      "element": "/crombolo-plugin/welcome-dashboard.js",
+      "weight": 20,
+      "overwrites": ["Umb.Dashboard.UmbracoNews"],
+      "meta": {
+        "label": "Welcome",
+        "pathname": "welcome"
+      },
+      "conditions": [
+        {
+          "alias": "Umb.Condition.SectionAlias",
+          "match": "Umb.Section.Content"
+        }
+      ]
+    },
+    {
+      "type": "dashboard",
+      "alias": "Crombolo.Dashboard.Settings",
+      "name": "Crombolo Settings Dashboard",
+      "element": "/crombolo-plugin/settings-dashboard.js",
+      "weight": 500,
+      "overwrites": ["Umb.Dashboard.SettingsWelcome"],
+      "meta": {
+        "label": "Welcome",
+        "pathname": "welcome"
+      },
+      "conditions": [
+        {
+          "alias": "Umb.Condition.SectionAlias",
+          "match": "Umb.Section.Settings"
+        }
+      ]
+    },
+    {
+      "type": "backofficeEntryPoint",
+      "alias": "Crombolo.EntryPoint.TsxEditors",
+      "name": "Crombolo TSX Template and Partial View Editors",
+      "js": "/crombolo-plugin/tsx-editors.js"
+    },
+    {
+      "type": "headerApp",
+      "alias": "Crombolo.HeaderApp.ReadOnly",
+      "name": "Crombolo Read-only Banner",
+      "element": "/crombolo-plugin/read-only-banner.js",
+      "weight": 1000
+    },
+    {
+      "type": "workspaceFooterApp",
+      "alias": "Crombolo.WorkspaceFooterApp.ElementTypeHint",
+      "name": "Crombolo Element Type Library Hint",
+      "element": "/crombolo-plugin/element-type-hint.js",
+      "weight": 900,
+      "conditions": [
+        {
+          "alias": "Umb.Condition.WorkspaceAlias",
+          "match": "Umb.Workspace.DocumentType"
+        }
+      ]
+    },
+    {
+      "type": "localization",
+      "alias": "Crombolo.Localization.EN",
+      "name": "Crombolo English Overrides",
+      "weight": 0,
+      "meta": {
+        "culture": "en"
+      },
+      "js": "/crombolo-plugin/branding/localization-en.js"
+    },
+    {
+      "type": "localization",
+      "alias": "Crombolo.Localization.EN_US",
+      "name": "Crombolo English (United States) Overrides",
+      "weight": 0,
+      "meta": {
+        "culture": "en-us"
+      },
+      "js": "/crombolo-plugin/branding/localization-en.js"
+    },
+    {
+      "type": "backofficeEntryPoint",
+      "alias": "Crombolo.EntryPoint.Branding",
+      "name": "Crombolo Branding",
+      "js": "/crombolo-plugin/branding/branding.js"
+    },
+    {
+      "type": "backofficeEntryPoint",
+      "alias": "Crombolo.EntryPoint.HelpMenu",
+      "name": "Crombolo Help Menu",
+      "js": "/crombolo-plugin/branding/help-menu.js"
+    },
+    {
+      "type": "backofficeEntryPoint",
+      "alias": "Crombolo.EntryPoint.Sysinfo",
+      "name": "Crombolo System Information Branding",
+      "js": "/crombolo-plugin/branding/sysinfo.js"
+    },
+    {
+      "type": "section",
+      "alias": "Crombolo.Section.Forms",
+      "name": "Crombolo Forms Section",
+      "weight": 50,
+      "meta": {
+        "label": "Forms",
+        "pathname": "forms"
+      }
+    },
+    {
+      "type": "sectionView",
+      "alias": "Crombolo.SectionView.Forms.Overview",
+      "name": "Crombolo Forms Overview",
+      "element": "/crombolo-plugin/forms-overview.js",
+      "weight": 200,
+      "meta": {
+        "label": "Forms",
+        "pathname": "forms",
+        "icon": "icon-notepad"
+      },
+      "conditions": [
+        {
+          "alias": "Umb.Condition.SectionAlias",
+          "match": "Crombolo.Section.Forms"
+        }
+      ]
+    },
+    {
+      "type": "sectionView",
+      "alias": "Crombolo.SectionView.Forms.Entries",
+      "name": "Crombolo Forms Entries",
+      "element": "/crombolo-plugin/forms-entries.js",
+      "weight": 100,
+      "meta": {
+        "label": "Entries",
+        "pathname": "entries",
+        "icon": "icon-inbox"
+      },
+      "conditions": [
+        {
+          "alias": "Umb.Condition.SectionAlias",
+          "match": "Crombolo.Section.Forms"
+        }
+      ]
+    },
+    {
+      "type": "propertyEditorSchema",
+      "name": "Form Picker",
+      "alias": "Crombolo.FormPicker",
+      "meta": {
+        "defaultPropertyEditorUiAlias": "Crombolo.PropertyEditorUi.FormPicker"
+      }
+    },
+    {
+      "type": "propertyEditorUi",
+      "alias": "Crombolo.PropertyEditorUi.FormPicker",
+      "name": "Form Picker",
+      "element": "/crombolo-plugin/form-picker.js",
+      "meta": {
+        "label": "Form Picker",
+        "icon": "icon-notepad",
+        "group": "pickers",
+        "propertyEditorSchemaAlias": "Crombolo.FormPicker"
+      }
+    },
+    {
+      "type": "backofficeEntryPoint",
+      "alias": "Crombolo.EntryPoint.ClientCredentials",
+      "name": "Crombolo Client Credential Prefix",
+      "js": "/crombolo-plugin/branding/client-credentials.js"
+    },
+    {
+      "type": "backofficeEntryPoint",
+      "alias": "Crombolo.EntryPoint.BundleBuilderLabels",
+      "name": "Crombolo Bundle Builder Labels",
+      "js": "/crombolo-plugin/branding/bundle-builder-labels.js"
+    },
+    {
+      "type": "backofficeEntryPoint",
+      "alias": "Crombolo.EntryPoint.ComponentsTree",
+      "name": "Crombolo Components Tree",
+      "js": "/crombolo-plugin/branding/components-tree.js"
+    },
+    {
+      "type": "backofficeEntryPoint",
+      "alias": "Crombolo.EntryPoint.ContentTypeLabels",
+      "name": "Crombolo Content Type Labels",
+      "js": "/crombolo-plugin/branding/content-type-labels.js"
+    },
+    {
+      "type": "backofficeEntryPoint",
+      "alias": "Crombolo.EntryPoint.QueryBuilder",
+      "name": "Crombolo Query Builder Language",
+      "js": "/crombolo-plugin/branding/query-builder.js"
+    },
+    {
+      "type": "backofficeEntryPoint",
+      "alias": "Crombolo.EntryPoint.SignIn",
+      "name": "Crombolo Sign-in Button",
+      "js": "/crombolo-plugin/branding/sign-in.js"
+    },
+    {
+      "type": "backofficeEntryPoint",
+      "alias": "Crombolo.EntryPoint.LogViewerMenu",
+      "name": "Crombolo Log Viewer Search Menu",
+      "js": "/crombolo-plugin/branding/log-viewer-menu.js"
+    },
+    {
+      "type": "globalContext",
+      "alias": "Crombolo.GlobalContext.Icons",
+      "name": "Crombolo Icons Context",
+      "overwrites": ["Umb.GlobalContext.Icons"],
+      "api": "/crombolo-plugin/branding/icon-registry.js"
+    }
+  ]
+}

package/plugin/welcome-dashboard.js

@@ -0,0 +1,106 @@
+/**
+ * The Welcome dashboard in the Content section. Its manifest declares
+ * `overwrites: ['Umb.Dashboard.UmbracoNews']`, which takes the place of
+ * Umbraco's news dashboard without mutating the registry while the backoffice
+ * is rendering — the hazard the TSX entry point documents.
+ */
+// UmbLitElement, not plain LitElement: a dashboard is used as a controller host,
+// and a plain element fails with `controllerHost.provideContext is not a function`.
+import { css, html } from '@umbraco-cms/backoffice/external/lit'
+import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element'
+
+const STEPS = [
+  {
+    title: 'Model the content',
+    body: html`Open <strong>Settings → Content Types</strong> and describe a page: its
+      properties, its tabs, and which types may sit beneath it. This is the same
+      editor Umbraco ships, so anything you know about Umbraco document types applies.`,
+  },
+  {
+    title: 'Write a template',
+    body: html`Templates are <strong>TSX</strong>, not Razor. A template is a file in
+      <code>Views/</code> that default-exports a component and receives the page as
+      <code>model</code>; <code>export const layout = 'alias'</code> names its master.
+      The editor under Settings → Templates writes that shape for you.`,
+  },
+  {
+    title: 'Create and publish',
+    body: html`Back in <strong>Content</strong>, create a page from your content type, fill it
+      in and publish. Publishing is per culture, and the published version is what the
+      site renders — drafts stay invisible until you say otherwise.`,
+  },
+  {
+    title: 'Keep the schema in the repository',
+    body: html`Content types, data types and templates are also files:
+      <code>schema/*.toml</code>. <code>crombolo schema sync</code> writes changes made in
+      the backoffice back out, and <code>crombolo schema check</code> tells you whether a
+      database matches. Schema travels through Git, not a database export.`,
+  },
+]
+
+export default class CromboloWelcomeDashboardElement extends UmbLitElement {
+  render() {
+    return html`
+      <uui-box headline="Welcome to Crombolo">
+        <p class="lede">
+          Crombolo is a content management system that runs on
+          <strong>Bun and TypeScript</strong>. It serves the real Umbraco backoffice you
+          are looking at now and follows Umbraco's API contract, so the editing
+          experience is Umbraco's — while the server, the templates and the schema are
+          TypeScript, and the database is SQLite or Postgres.
+        </p>
+        <p class="lede">
+          There is no .NET anywhere in it: templates are TSX rather than Razor, and a
+          site's schema lives in TOML files beside its code.
+        </p>
+      </uui-box>
+
+      <uui-box headline="Getting started">
+        <ol>
+          ${STEPS.map(
+            (step) => html`<li>
+              <h4>${step.title}</h4>
+              <p>${step.body}</p>
+            </li>`,
+          )}
+        </ol>
+      </uui-box>
+
+      <uui-box headline="Worth knowing">
+        <ul>
+          <li>
+            The <strong>Settings</strong> section holds templates, partial views,
+            stylesheets and scripts — all served from your site's folders.
+          </li>
+          <li>
+            <strong>Upgrade</strong>, also under Settings, reports anything a version
+            change needs from you before it will run.
+          </li>
+          <li>
+            The log viewer under Settings reads the server's own structured logs, so a
+            failed publish or a broken template is searchable rather than guessed at.
+          </li>
+        </ul>
+      </uui-box>
+    `
+  }
+
+  static styles = css`
+    :host { display: block; padding: var(--uui-size-layout-1); }
+    uui-box { margin-bottom: var(--uui-size-layout-1); }
+    .lede { max-width: 70ch; line-height: 1.6; }
+    ol { margin: 0; padding-left: var(--uui-size-layout-1); }
+    ol li { margin-bottom: var(--uui-size-space-5); max-width: 70ch; }
+    ol h4 { margin: 0 0 var(--uui-size-space-2); }
+    ol p { margin: 0; line-height: 1.6; }
+    ul { margin: 0; padding-left: var(--uui-size-layout-1); }
+    ul li { margin-bottom: var(--uui-size-space-3); max-width: 70ch; line-height: 1.6; }
+    code {
+      background: var(--uui-color-surface-alt);
+      padding: 0 var(--uui-size-space-1);
+      border-radius: var(--uui-border-radius);
+    }
+  `
+}
+
+customElements.define('crombolo-welcome-dashboard', CromboloWelcomeDashboardElement)

package/src/branding.ts

@@ -0,0 +1,59 @@
+/**
+ * The brand as data: the marks, and the palette behind them.
+ *
+ * The back office serves these as files, by path (`graphics.ts`). This exports
+ * the same bytes to anything that has to *draw* the brand rather than serve it
+ * — the enterprise console, which is a separate product surface in another
+ * repository and reaches the CMS only through the `@crombolo/crombolo` umbrella.
+ *
+ * Imported as text rather than duplicated as string literals, so the `.svg`
+ * and `.css` files stay the one source of truth and a new logo is one file to
+ * change. Bun inlines a text import at bundle time, so this works in a browser
+ * bundle as well as on the server — which matters, because the console that
+ * consumes it is a client-side app and could not read a file at runtime.
+ */
+/// <reference path="./text-imports.d.ts" />
+import faviconText from '../plugin/branding/favicon.svg' with { type: 'text' }
+import logoText from '../plugin/branding/logo-header.svg' with { type: 'text' }
+import themeText from '../plugin/branding/theme.css' with { type: 'text' }
+
+/** The mark and wordmark, for a header or a sign-in card. */
+export const logoSvg: string = logoText.trim()
+
+/** The mark alone, square, for a tab icon. */
+export const faviconSvg: string = faviconText.trim()
+
+/**
+ * The palette, read out of `theme.css` rather than restated here.
+ *
+ * The theme is what the back office is actually painted with, so parsing it is
+ * what makes a consumer's colours the same colours rather than a copy that was
+ * the same once. Only the `--crombolo-*` tokens are ours; everything else in
+ * that file is an Umbraco variable being pointed at one of them.
+ */
+export interface BrandPalette {
+  orange: string
+  orangeLight: string
+  orangeDeep: string
+  orangeText: string
+  cocoa: string
+  cream: string
+}
+
+/** `--crombolo-orange-deep` → `orangeDeep`. */
+const camel = (name: string) =>
+  name.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase())
+
+export function paletteFrom(css: string): BrandPalette {
+  const found: Record<string, string> = {}
+  for (const [, name, value] of css.matchAll(/--crombolo-([a-z-]+)\s*:\s*([^;]+);/g))
+    found[camel(name as string)] = (value as string).trim()
+  const wanted = ['orange', 'orangeLight', 'orangeDeep', 'orangeText', 'cocoa', 'cream']
+  const missing = wanted.filter((key) => found[key] === undefined)
+  // A theme that stopped declaring one of these would otherwise hand a
+  // consumer `undefined` and paint something invisible.
+  if (missing.length > 0) throw new Error(`theme.css declares no ${missing.join(', ')}.`)
+  return Object.fromEntries(wanted.map((key) => [key, found[key]])) as unknown as BrandPalette
+}
+
+export const brandPalette: BrandPalette = paletteFrom(themeText)

package/src/extensions.ts

@@ -0,0 +1,228 @@
+/**
+ * Backoffice extensions as npm dependencies. `docs/17-bundles.md`.
+ *
+ * A site's extensions are its dependencies: discovery reads the site's own
+ * `package.json`, resolves each dependency through `node_modules`, and takes the
+ * `crombolo` field from the dependency's `package.json`. There is no directory
+ * convention to keep in step, and `bun add` is the install.
+ *
+ * Only declared dependencies are read, never a walk of `node_modules`, so a
+ * transitive dependency cannot put an extension into a backoffice that never
+ * asked for it.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join, normalize, sep } from 'node:path'
+import type { PackageManifest, PackageManifestImportmap } from './manifests.ts'
+
+/** Where an installed bundle's assets are served from. */
+export const EXTENSION_PATH = '/bundles'
+
+/** The npm keyword a bundle publishes so the marketplace can find it. */
+export const EXTENSION_KEYWORD = 'crombolo-bundle'
+
+/**
+ * What a dependency declares to become a backoffice extension. The shape is
+ * Umbraco's manifest minus the parts the server owns — the name and version
+ * come from the package itself.
+ */
+export interface CromboloField {
+  id?: string
+  name?: string
+  allowPublicAccess?: boolean
+  allowTelemetry?: boolean
+  extensions?: unknown[]
+  importmap?: PackageManifestImportmap
+}
+
+export interface InstalledExtension {
+  /** The npm package name, which is also its segment in the asset path. */
+  packageName: string
+  version: string
+  directory: string
+  manifest: PackageManifest
+}
+
+/**
+ * Asset references inside an extension. Only these carry a path; rewriting
+ * every string would corrupt labels and aliases that happen to look like one.
+ */
+const ASSET_KEYS = new Set(['element', 'api', 'js', 'loader'])
+
+interface PackageJson {
+  name?: string
+  version?: string
+  dependencies?: Record<string, string>
+  crombolo?: CromboloField
+}
+
+function readJson(file: string): PackageJson | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as unknown
+    return parsed && typeof parsed === 'object' ? (parsed as PackageJson) : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The directory a dependency resolves to, walking up as Node does, so a
+ * workspace root's hoisted `node_modules` is found from a site inside it.
+ */
+export function resolvePackageDir(from: string, name: string): string | undefined {
+  // A name may not climb out of node_modules, whatever a package.json says.
+  if (name.includes('..') || name.startsWith('/') || name.startsWith('.')) return undefined
+  let dir = normalize(from)
+  for (;;) {
+    const candidate = join(dir, 'node_modules', name)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+    const parent = dirname(dir)
+    if (parent === dir) return undefined
+    dir = parent
+  }
+}
+
+/** `dist/seo.js` inside `@acme/seo` becomes `/bundles/@acme/seo/dist/seo.js`. */
+const assetPath = (packageName: string, target: string): string =>
+  target.startsWith('/') || /^[a-z][a-z0-9+.-]*:/i.test(target)
+    ? target
+    : `${EXTENSION_PATH}/${packageName}/${target.replace(/^\.?\//, '')}`
+
+function rewriteAssets(value: unknown, packageName: string): unknown {
+  if (Array.isArray(value)) return value.map((item) => rewriteAssets(item, packageName))
+  if (!value || typeof value !== 'object') return value
+  const out: Record<string, unknown> = {}
+  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+    out[key] =
+      ASSET_KEYS.has(key) && typeof item === 'string'
+        ? assetPath(packageName, item)
+        : rewriteAssets(item, packageName)
+  }
+  return out
+}
+
+function rewriteImportmap(
+  importmap: PackageManifestImportmap | undefined,
+  packageName: string,
+): PackageManifestImportmap | undefined {
+  if (!importmap) return undefined
+  const imports: Record<string, string> = {}
+  for (const [specifier, target] of Object.entries(importmap.imports ?? {}))
+    imports[specifier] = assetPath(packageName, target)
+  const scopes: Record<string, Record<string, string>> = {}
+  for (const [scope, scopeImports] of Object.entries(importmap.scopes ?? {})) {
+    const rewritten: Record<string, string> = {}
+    for (const [specifier, target] of Object.entries(scopeImports))
+      rewritten[specifier] = assetPath(packageName, target)
+    scopes[assetPath(packageName, scope)] = rewritten
+  }
+  return Object.keys(scopes).length > 0 ? { imports, scopes } : { imports }
+}
+
+/** One dependency's manifest, or undefined when it declares no extensions. */
+export function readExtension(
+  directory: string,
+  packageName: string,
+): InstalledExtension | undefined {
+  const json = readJson(join(directory, 'package.json'))
+  const field = json?.crombolo
+  if (!field || !Array.isArray(field.extensions) || field.extensions.length === 0) return undefined
+  return {
+    packageName,
+    version: json?.version ?? '0.0.0',
+    directory,
+    manifest: {
+      name: field.name ?? packageName,
+      id: field.id ?? packageName,
+      version: json?.version ?? '0.0.0',
+      allowPublicAccess: field.allowPublicAccess ?? false,
+      allowTelemetry: field.allowTelemetry ?? false,
+      extensions: field.extensions.map((extension) => rewriteAssets(extension, packageName)),
+      importmap: rewriteImportmap(field.importmap, packageName),
+    },
+  }
+}
+
+/** Every declared dependency of the site that is a backoffice extension. */
+export function discoverExtensions(siteDir: string): InstalledExtension[] {
+  const json = readJson(join(siteDir, 'package.json'))
+  if (!json?.dependencies) return []
+  const found: InstalledExtension[] = []
+  for (const name of Object.keys(json.dependencies).sort()) {
+    const directory = resolvePackageDir(siteDir, name)
+    if (!directory) continue
+    const extension = readExtension(directory, name)
+    if (extension) found.push(extension)
+  }
+  return found
+}
+
+/**
+ * The package a `/packages/…` request names, and the file inside it.
+ *
+ * The name is matched against the site's own extensions rather than trusted, so
+ * this cannot be used to read an arbitrary file out of `node_modules`; a scoped
+ * name takes two segments, as npm writes it.
+ */
+export function resolveExtensionFile(
+  extensions: readonly InstalledExtension[],
+  pathname: string,
+): string | undefined {
+  const prefix = `${EXTENSION_PATH}/`
+  if (!pathname.startsWith(prefix)) return undefined
+  const rest = pathname.slice(prefix.length)
+  const segments = rest.split('/')
+  const take = rest.startsWith('@') || rest.toLowerCase().startsWith('%40') ? 2 : 1
+  if (segments.length <= take) return undefined
+  // Decoded before matching, so `%40acme/seo` finds the same package the
+  // manifest names. Safe because the name is only compared against the known
+  // extensions, never joined into a path — the file part is what gets joined.
+  let name: string
+  try {
+    name = decodeURIComponent(segments.slice(0, take).join('/'))
+  } catch {
+    return undefined
+  }
+  const relative = segments.slice(take).join('/')
+  const extension = extensions.find((candidate) => candidate.packageName === name)
+  if (!extension || relative.length === 0) return undefined
+
+  const decoded = decodeURIComponent(relative)
+  if (decoded.includes('\0')) return undefined
+  const root = extension.directory.endsWith(sep)
+    ? extension.directory
+    : `${extension.directory}${sep}`
+  const target = normalize(join(extension.directory, decoded))
+  return target.startsWith(root) ? target : undefined
+}
+
+export interface ExtensionRegistry {
+  list(): readonly InstalledExtension[]
+  /** Called after an install or an uninstall, so the next read sees it. */
+  invalidate(): void
+}
+
+/**
+ * Discovery, memoized.
+ *
+ * Reading a handful of `package.json` files on every manifest request would be
+ * wasteful, but the uncached behaviour is load-bearing in development: an author
+ * editing a local extension expects a reload to show it, which is why `cache`
+ * is off there rather than everywhere.
+ */
+export function createExtensionRegistry(
+  siteDir: string,
+  options: { cache?: boolean } = {},
+): ExtensionRegistry {
+  let cached: InstalledExtension[] | undefined
+  const cache = options.cache ?? true
+  return {
+    list() {
+      if (!cache) return discoverExtensions(siteDir)
+      cached ??= discoverExtensions(siteDir)
+      return cached
+    },
+    invalidate() {
+      cached = undefined
+    },
+  }
+}