@crombolo/backoffice-host 0.0.0-stage → 0.10.0

package/src/bundle-package.ts

@@ -0,0 +1,266 @@
+/**
+ * A bundle is an npm package whose `package.json` carries the bundle manifest in
+ * its `crombolo` field. `docs/bundles.md`.
+ *
+ * This is the one place that field is read and validated, so discovery, the
+ * marketplace, the server half and the installer cannot disagree about what a
+ * bundle is.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import { dirname, isAbsolute, join, normalize, sep } from 'node:path'
+import type { PackageManifestImportmap } from './manifests.ts'
+
+/** The package a bundle declares its peer range on. */
+export const CORE_PACKAGE = '@crombolo/crombolo'
+
+/**
+ * A bundle's id: its route segment, its log name, and the prefix of anything
+ * else it owns. Lowercase, no dots or slashes, so it cannot climb out of a
+ * namespace however it is spelled.
+ */
+export const BUNDLE_ID = /^[a-z][a-z0-9-]{1,38}$/
+
+/** The `content` payload: always `bundle.json` inside the named directory. */
+export const PAYLOAD_MANIFEST = 'bundle.json'
+
+/** An exported binding name: what a site imports to wire the server half. */
+const EXPORT_NAME = /^[A-Za-z_$][A-Za-z0-9_$]*$/
+
+/** The `crombolo` field, as a bundle declares it. */
+export interface CromboloField {
+  id: string
+  name?: string
+  allowPublicAccess?: boolean
+  allowTelemetry?: boolean
+  /** The backoffice half: Umbraco extension manifests. */
+  extensions?: unknown[]
+  importmap?: PackageManifestImportmap
+  /** A directory inside the package holding a `bundle.json` payload. */
+  content?: string
+  /** The factory the package exports for the server half. Never imported by core. */
+  server?: string
+  /**
+   * What this release's table steps promise a running site, for a bundle that
+   * owns tables: `breaking` exactly when it ships a contract.
+   */
+  migrations?: 'compatible' | 'breaking'
+}
+
+/** A bundle as read from its package. */
+export interface BundlePackage {
+  packageName: string
+  version: string
+  directory: string
+  id: string
+  name: string
+  /** `peerDependencies["@crombolo/crombolo"]`. */
+  peerRange: string
+  private: boolean
+  field: CromboloField
+  /** Absolute path of the payload directory, when the bundle carries content. */
+  contentDir: string | undefined
+  carries: { extensions: boolean; content: boolean; server: boolean }
+}
+
+export interface PackageJson {
+  name?: string
+  version?: string
+  private?: boolean
+  dependencies?: Record<string, string>
+  peerDependencies?: Record<string, string>
+  crombolo?: unknown
+}
+
+export function readPackageJson(file: string): PackageJson | undefined {
+  try {
+    const parsed = JSON.parse(readFileSync(file, 'utf8')) as unknown
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as PackageJson)
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether a package's `crombolo` field declares a bundle at all.
+ *
+ * Core's own umbrella package carries a `crombolo` field too — its release
+ * declaration — so the core package is never a bundle, whatever it holds.
+ */
+export function declaresBundle(json: PackageJson | undefined): boolean {
+  return Boolean(json?.crombolo) && json?.name !== CORE_PACKAGE
+}
+
+/** A relative path that stays inside the package. */
+function insidePackage(directory: string, relative: string): string | undefined {
+  if (relative === '' || isAbsolute(relative) || relative.includes('\0')) return undefined
+  const root = directory.endsWith(sep) ? directory : `${directory}${sep}`
+  const target = normalize(join(directory, relative))
+  return target === normalize(directory) || target.startsWith(root) ? target : undefined
+}
+
+/**
+ * Every reason a package's manifest is not a bundle, reported together.
+ *
+ * `directory` is where the package lives, so `content` can be checked against
+ * what is really there; a packument read from the registry has none, and only
+ * the declaration is checked.
+ */
+export function validateBundlePackage(json: PackageJson, directory?: string): string[] {
+  const problems: string[] = []
+  const field = json.crombolo
+  if (!field || typeof field !== 'object' || Array.isArray(field))
+    return ['its package.json has no "crombolo" field, so it is not a bundle']
+  const f = field as Record<string, unknown>
+
+  if (typeof f.id !== 'string' || !BUNDLE_ID.test(f.id))
+    problems.push(
+      `"crombolo.id" must be 2–39 lowercase letters, digits and hyphens starting with a letter${
+        typeof f.id === 'string' ? `, not "${f.id}"` : ''
+      }`,
+    )
+  if (f.name !== undefined && (typeof f.name !== 'string' || f.name.trim() === ''))
+    problems.push('"crombolo.name" must be a non-empty string')
+  if (typeof json.name !== 'string' || json.name === '')
+    problems.push('its package.json has no "name"')
+  if (typeof json.version !== 'string' || json.version === '')
+    problems.push('its package.json has no "version"')
+
+  if (f.extensions !== undefined && !Array.isArray(f.extensions))
+    problems.push('"crombolo.extensions" must be a list of extension manifests')
+  if (f.migrations !== undefined && f.migrations !== 'compatible' && f.migrations !== 'breaking')
+    problems.push('"crombolo.migrations" is "compatible" or "breaking"')
+  if (f.server !== undefined && (typeof f.server !== 'string' || !EXPORT_NAME.test(f.server)))
+    problems.push('"crombolo.server" must name the factory the package exports')
+  if (f.content !== undefined) {
+    if (typeof f.content !== 'string') problems.push('"crombolo.content" must be a directory')
+    else if (directory) {
+      const target = insidePackage(directory, f.content)
+      if (!target) problems.push(`"crombolo.content" (${f.content}) is outside the package`)
+      else if (!existsSync(join(target, PAYLOAD_MANIFEST)))
+        problems.push(`"crombolo.content" (${f.content}) holds no ${PAYLOAD_MANIFEST}`)
+    } else if (isAbsolute(f.content) || f.content.split(/[\\/]/).includes('..'))
+      problems.push(`"crombolo.content" (${f.content}) is outside the package`)
+  }
+
+  const hasExtensions = Array.isArray(f.extensions) && f.extensions.length > 0
+  if (!hasExtensions && f.content === undefined && f.server === undefined)
+    problems.push(
+      'it declares no "extensions", "content" or "server", so it is a bundle that does nothing',
+    )
+
+  const peer = json.peerDependencies?.[CORE_PACKAGE]
+  if (typeof peer !== 'string' || peer.trim() === '')
+    problems.push(`its package.json declares no peerDependencies["${CORE_PACKAGE}"]`)
+  return problems
+}
+
+/**
+ * The package at a directory, read as a bundle.
+ *
+ * `undefined` with no problems means the package is not a bundle at all — an
+ * ordinary dependency. Problems mean it claims to be one and is malformed.
+ */
+export function readBundlePackage(directory: string): {
+  bundle: BundlePackage | undefined
+  problems: string[]
+} {
+  const json = readPackageJson(join(directory, 'package.json'))
+  if (!declaresBundle(json)) return { bundle: undefined, problems: [] }
+  const problems = validateBundlePackage(json as PackageJson, directory)
+  if (problems.length > 0) return { bundle: undefined, problems }
+  const pkg = json as Required<Pick<PackageJson, 'name' | 'version'>> & PackageJson
+  const field = pkg.crombolo as CromboloField
+  return {
+    bundle: {
+      packageName: pkg.name,
+      version: pkg.version,
+      directory,
+      id: field.id,
+      name: field.name ?? pkg.name,
+      peerRange: pkg.peerDependencies?.[CORE_PACKAGE] as string,
+      private: pkg.private === true,
+      field,
+      contentDir: field.content ? insidePackage(directory, field.content) : undefined,
+      carries: {
+        extensions: Array.isArray(field.extensions) && field.extensions.length > 0,
+        content: field.content !== undefined,
+        server: field.server !== undefined,
+      },
+    },
+    problems: [],
+  }
+}
+
+const COMPARATOR = /^(?:[~^]|[<>]=?|=)?v?(?:\d+|[xX*])(?:\.(?:\d+|[xX*])){0,2}(?:-[0-9A-Za-z.-]+)?$/
+
+/** A semver range, token by token: Bun's own matcher accepts nonsense and matches it. */
+export function isSemverRange(range: string): boolean {
+  const tokens = range.trim().split(/\s+/)
+  return tokens.length > 0 && tokens.every((t) => t === '||' || t === '-' || COMPARATOR.test(t))
+}
+
+/** Whether a bundle's peer range admits a core version; a reason when it does not. */
+export function peerRangeProblem(bundle: BundlePackage, coreVersion: string): string | undefined {
+  // A workspace link is resolved to this very tree, so it is this version by construction.
+  if (bundle.peerRange.startsWith('workspace:')) return undefined
+  const satisfied =
+    isSemverRange(bundle.peerRange) && Bun.semver.satisfies(coreVersion, bundle.peerRange)
+  return satisfied
+    ? undefined
+    : `${bundle.packageName} (${bundle.id}) is written for ${CORE_PACKAGE} ${bundle.peerRange}, and this site runs ${coreVersion}`
+}
+
+/**
+ * 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
+  }
+}
+
+export interface DiscoveredBundles {
+  bundles: BundlePackage[]
+  /** A declared dependency that claims to be a bundle and is not a valid one. */
+  problems: { packageName: string; problems: string[] }[]
+}
+
+/**
+ * Every declared dependency of the site that is a bundle.
+ *
+ * Only declared dependencies are read, never a walk of `node_modules`, so a
+ * transitive dependency cannot claim to be a bundle the site never asked for.
+ */
+export function discoverBundles(siteDir: string): DiscoveredBundles {
+  const json = readPackageJson(join(siteDir, 'package.json'))
+  const found: DiscoveredBundles = { bundles: [], problems: [] }
+  if (!json?.dependencies) return found
+  for (const name of Object.keys(json.dependencies).sort()) {
+    const directory = resolvePackageDir(siteDir, name)
+    if (!directory) continue
+    const read = readBundlePackage(directory)
+    if (read.bundle) found.bundles.push(read.bundle)
+    else if (read.problems.length > 0)
+      found.problems.push({ packageName: name, problems: read.problems })
+  }
+  return found
+}
+
+/** Whether a path is a directory, for telling a package path from a package name. */
+export function isDirectory(path: string): boolean {
+  try {
+    return statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}

package/src/extensions.ts

@@ -0,0 +1,189 @@
+/**
+ * Backoffice extensions as npm dependencies. `docs/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 { join, normalize, sep } from 'node:path'
+import {
+  type BundlePackage,
+  type DiscoveredBundles,
+  discoverBundles,
+  readBundlePackage,
+} from './bundle-package.ts'
+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'
+
+/** A bundle's backoffice half, as the manifest endpoint serves it. */
+export interface InstalledExtension {
+  /** The npm package name, which is also its segment in the asset path. */
+  packageName: string
+  version: string
+  directory: string
+  manifest: PackageManifest
+  bundle: BundlePackage
+}
+
+/**
+ * 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'])
+
+/** `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 }
+}
+
+/** A bundle's backoffice half, or undefined when it declares no extensions. */
+export function extensionOf(bundle: BundlePackage): InstalledExtension | undefined {
+  const field = bundle.field
+  if (!bundle.carries.extensions) return undefined
+  const packageName = bundle.packageName
+  return {
+    packageName,
+    version: bundle.version,
+    directory: bundle.directory,
+    bundle,
+    manifest: {
+      name: bundle.name,
+      id: bundle.id,
+      version: bundle.version,
+      allowPublicAccess: field.allowPublicAccess ?? false,
+      allowTelemetry: field.allowTelemetry ?? false,
+      extensions: (field.extensions ?? []).map((extension) =>
+        rewriteAssets(extension, packageName),
+      ),
+      importmap: rewriteImportmap(field.importmap, packageName),
+    },
+  }
+}
+
+/** One dependency's backoffice half, or undefined when it is no bundle or declares no extensions. */
+export function readExtension(directory: string): InstalledExtension | undefined {
+  const { bundle } = readBundlePackage(directory)
+  return bundle ? extensionOf(bundle) : undefined
+}
+
+/** Every declared dependency of the site that is a bundle with a backoffice half. */
+export function discoverExtensions(siteDir: string): InstalledExtension[] {
+  return discoverBundles(siteDir).bundles.flatMap((bundle) => extensionOf(bundle) ?? [])
+}
+
+/**
+ * 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[]
+  /** Every bundle the site depends on, whatever it carries, and the ones that are malformed. */
+  bundles(): DiscoveredBundles
+  /** 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: DiscoveredBundles | undefined
+  const cache = options.cache ?? true
+  const discovered = () => {
+    if (!cache) return discoverBundles(siteDir)
+    cached ??= discoverBundles(siteDir)
+    return cached
+  }
+  return {
+    list: () => discovered().bundles.flatMap((bundle) => extensionOf(bundle) ?? []),
+    bundles: discovered,
+    invalidate() {
+      cached = undefined
+    },
+  }
+}

package/src/graphics.ts

@@ -0,0 +1,87 @@
+/**
+ * The login/back-office branding images. These live on Umbraco's
+ * BackOfficeGraphicsController, which is excluded from the OpenAPI document, so
+ * they cannot be routed through the contract-first router.
+ */
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { MANAGEMENT_API_PATH } from '@crombolo/core'
+import type { BackOfficePaths } from './paths.ts'
+
+export const GRAPHICS_PREFIX = `${MANAGEMENT_API_PATH}/security/back-office/graphics`
+
+/**
+ * Crombolo's own marks, as Umbraco's names them. The plain names are the ones
+ * the client asks for on the header bar, which the theme paints orange, so they
+ * get the cocoa mark; the `-alternative` ones sit on white surfaces and get the
+ * orange one.
+ *
+ * `login-background` fills the illustration panel of the client's own sign-in
+ * screen (`umb-auth-view`), which a session timing out puts in front of an
+ * editor. Our login page has no background of its own — it draws a card rather
+ * than Umbraco's split screen — so this is the only request for it, and leaving
+ * it unanswered left that panel an empty rounded rectangle.
+ */
+const GRAPHICS: Record<string, string> = {
+  logo: 'branding/logo-header.svg',
+  'logo-alternative': 'branding/logo-surface.svg',
+  'login-logo': 'branding/logo-header.svg',
+  'login-logo-alternative': 'branding/logo-surface.svg',
+  'login-background': 'branding/backdrop.svg',
+}
+
+/**
+ * Vendored asset paths served as crombolo's instead.
+ *
+ * These are Umbraco's own marks and artwork, which MIT does not license:
+ * MIT grants copyright permission and says nothing about trademarks. Each is
+ * requested by a vendored element that hard-codes its path, so the substitution
+ * happens here rather than by patching the client, and the originals are no
+ * longer committed under `backoffice-dist/upstream-static/`.
+ *
+ * `resolveStaticFile` consults this before falling back to `vendorDir`, on both
+ * the hashed and the plain prefix, so there is no path left that reaches an
+ * Umbraco mark.
+ *
+ * - `favicon.svg` — the Umbraco "U" roundel, requested by the shells
+ * - `umbraco-logo.svg` — the wordmark, requested by the header popover
+ * - `installer-illustration.svg` — the backdrop of `app-error.element.js`, which
+ *   is a real runtime path, so this needs a replacement rather than a deletion
+ */
+export const BRANDED_ASSETS: Readonly<Record<string, string>> = {
+  'assets/favicon.svg': 'branding/favicon.svg',
+  'assets/umbraco-logo.svg': 'branding/logo-surface.svg',
+  'assets/installer-illustration.svg': 'branding/backdrop.svg',
+}
+
+/**
+ * The same substitution for a file the bundler names after its contents, where
+ * an exact path would be right until the next `vendor:backoffice` and then
+ * quietly wrong.
+ *
+ * `icon-umbraco.js` is the "U" roundel as a registry icon.
+ * `branding/icon-registry.js` keeps that name out of the icon picker, but the
+ * registry is addressed by name and any element may render one, so the glyph
+ * behind the name is ours as well. The bundled app — the one the shells load —
+ * asks for it as `chunks/icon-umbraco-<hash>.js`, while the unbundled tree has
+ * it under `packages/core/icon-registry/icons/`. Both are the one glyph.
+ */
+const BRANDED_PATTERNS: readonly (readonly [RegExp, string])[] = [
+  [/(?:^|\/)icon-umbraco(?:-[0-9a-z]+)?\.js$/, 'branding/icon-mark.js'],
+]
+
+/** The crombolo file to serve in place of a vendored one, by vendor-relative path. */
+export function brandedAsset(relative: string): string | undefined {
+  return (
+    BRANDED_ASSETS[relative] ?? BRANDED_PATTERNS.find(([pattern]) => pattern.test(relative))?.[1]
+  )
+}
+
+export function resolveGraphic(paths: BackOfficePaths, pathname: string): string | undefined {
+  const prefix = `${GRAPHICS_PREFIX}/`
+  if (!pathname.startsWith(prefix)) return undefined
+  const graphic = GRAPHICS[pathname.slice(prefix.length)]
+  if (!graphic) return undefined
+  const file = join(paths.pluginDir, graphic)
+  return existsSync(file) ? file : undefined
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './bundle-package.ts'
+export * from './extensions.ts'
+export * from './graphics.ts'
+export * from './login-assets.ts'
+export * from './manifests.ts'
+export * from './paths.ts'
+export * from './shell.ts'
+export * from './static.ts'

package/src/login-assets.ts

@@ -0,0 +1,18 @@
+/**
+ * The login page's client module.
+ *
+ * It is a plain `.js` asset rather than compiled TypeScript because it imports
+ * bare `@umbraco-cms/backoffice/*` specifiers that only resolve in the browser,
+ * through the import map the page embeds.
+ */
+import { join } from 'node:path'
+
+export const LOGIN_ASSET_DIR = join(import.meta.dir, '../assets')
+
+export function resolveLoginAsset(backOfficePath: string, pathname: string): string | undefined {
+  const prefix = `${backOfficePath}/login/`
+  if (!pathname.startsWith(prefix)) return undefined
+  const name = pathname.slice(prefix.length)
+  // Only the files we ship; no traversal, no directory listing.
+  return name === 'login.js' ? join(LOGIN_ASSET_DIR, 'login.js') : undefined
+}