handoff-app 1.2.2-7 → 2.0.0-0

package/src/app/components/util/useCollectionAssets.ts

@@ -0,0 +1,125 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import type { Types as CoreTypes } from 'handoff-core';
+import type { AssetMetadata } from '@handoff/store';
+
+/**
+ * Client-side hydration for asset pages (icons grid, icon detail, logos). Asset routes are static, so
+ * their `getStaticProps` data is build-time only (empty in a registry build). In registry mode these
+ * hooks fetch the metadata-only list from the docs read API on mount (and, for detail, one SVG body),
+ * so a publish surfaces without a rebuild; workspace/static returns the build-time props unchanged.
+ */
+
+const isRegistry = process.env.HANDOFF_RUNTIME_MODE === 'registry';
+const basePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
+
+/** A grid/detail-renderable asset: inline SVG body (workspace) or a content URL (registry). */
+export interface DisplayableAsset {
+  /** Stable id used for the detail route + sprite symbol. */
+  icon: string;
+  /** Searchable index string. */
+  index: string;
+  name: string;
+  /** Logical path within the collection (registry) or the asset path (workspace). */
+  path: string;
+  size?: number;
+  /** Optional asset description (logos). */
+  description?: string;
+  /** Inline SVG body (workspace, or a fetched single-asset body). */
+  data?: string;
+  /** Individual asset content URL (registry). */
+  src?: string;
+}
+
+const contentUrl = (collection: string, logicalPath: string): string => `${basePath}/api/docs/assets/${collection}/${logicalPath}`;
+
+const fromWorkspace = (assets?: CoreTypes.IAssetObject[]): DisplayableAsset[] =>
+  (assets ?? []).map((asset) => ({
+    icon: asset.icon,
+    index: asset.index,
+    name: asset.name,
+    path: asset.path,
+    size: asset.size,
+    description: asset.description,
+    data: asset.data,
+  }));
+
+/** Map registry metadata rows (individual assets only) to displayable assets. */
+const fromRegistry = (collection: string, rows: AssetMetadata[]): DisplayableAsset[] => {
+  const prefix = `assets/${collection}/`;
+  return (rows ?? [])
+    .filter((row) => typeof row.path === 'string' && row.path.startsWith(prefix))
+    .map((row) => ({
+      icon: (row.metadata?.icon as string) ?? row.path.slice(prefix.length).replace(/\.[^.]+$/, ''),
+      index: (row.metadata?.index as string) ?? row.name ?? '',
+      name: row.name,
+      path: row.path,
+      size: row.size,
+      description: row.metadata?.description as string | undefined,
+      src: contentUrl(collection, row.path),
+    }));
+};
+
+/** Hydrate a collection's asset list (metadata only), used by the icon grid and logo views. */
+export const useCollectionAssets = (collection: 'icons' | 'logos', initial?: CoreTypes.IAssetObject[]): DisplayableAsset[] => {
+  const [assets, setAssets] = useState<DisplayableAsset[]>(() => fromWorkspace(initial));
+
+  useEffect(() => {
+    if (!isRegistry) {
+      return;
+    }
+    let active = true;
+    fetch(`${basePath}/api/docs/assets/${collection}`)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data) => {
+        if (active && data?.assets) setAssets(fromRegistry(collection, data.assets));
+      })
+      .catch(() => {});
+    return () => {
+      active = false;
+    };
+  }, [collection]);
+
+  return assets;
+};
+
+/** Hydrate a single asset (with its SVG body) by id, used by the icon detail view. */
+export const useSingleAsset = (
+  collection: 'icons' | 'logos',
+  iconId: string | undefined,
+  initial?: CoreTypes.IAssetObject
+): DisplayableAsset | null => {
+  const [asset, setAsset] = useState<DisplayableAsset | null>(() =>
+    initial
+      ? { icon: initial.icon, index: initial.index, name: initial.name, path: initial.path, size: initial.size, data: initial.data }
+      : null
+  );
+
+  useEffect(() => {
+    if (!isRegistry || !iconId) {
+      return;
+    }
+    let active = true;
+    (async () => {
+      const listRes = await fetch(`${basePath}/api/docs/assets/${collection}`);
+      if (!listRes.ok) return;
+      const data = await listRes.json();
+      const entry = fromRegistry(collection, data?.assets ?? []).find((candidate) => candidate.icon === iconId);
+      if (!entry) return;
+      let body: string | undefined;
+      try {
+        const bodyRes = await fetch(entry.src as string);
+        if (bodyRes.ok) body = await bodyRes.text();
+      } catch {
+        // Preview falls back to the <img> src if the body cannot be fetched.
+      }
+      if (active) setAsset({ ...entry, data: body });
+    })().catch(() => {});
+    return () => {
+      active = false;
+    };
+  }, [collection, iconId]);
+
+  return asset;
+};

package/src/app/components/util/useFoundationTokens.ts

@@ -0,0 +1,67 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import type { Types as CoreTypes } from 'handoff-core';
+
+/**
+ * Client-side hydration for foundation token pages.
+ *
+ * Foundation routes are static, so their `getStaticProps` data is build-time only — which is empty in
+ * a registry build (no local `tokens.json`). In registry mode this hook fetches the mutable token data
+ * from the docs read API on mount (mirroring `NavProvider`'s client fetch), so a publish surfaces
+ * without a rebuild/redeploy. In workspace/static mode it returns the build-time props unchanged.
+ */
+
+const isRegistry = process.env.HANDOFF_RUNTIME_MODE === 'registry';
+const basePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
+
+export interface FoundationTokensState {
+  design: CoreTypes.IDocumentationObject['localStyles'];
+  css: string;
+  scss: string;
+  styleDictionary: string;
+  types: string;
+}
+
+const emptyDesign = (): CoreTypes.IDocumentationObject['localStyles'] =>
+  ({ color: [], typography: [], effect: [] }) as CoreTypes.IDocumentationObject['localStyles'];
+
+export const useFoundationTokens = (
+  type: 'colors' | 'typography' | 'effects',
+  initial: Partial<FoundationTokensState>
+): FoundationTokensState => {
+  const [state, setState] = useState<FoundationTokensState>({
+    design: initial.design ?? emptyDesign(),
+    css: initial.css ?? '',
+    scss: initial.scss ?? '',
+    styleDictionary: initial.styleDictionary ?? '',
+    types: initial.types ?? '',
+  });
+
+  useEffect(() => {
+    if (!isRegistry) {
+      return;
+    }
+    let active = true;
+    fetch(`${basePath}/api/docs/tokens/foundations/${type}.json`)
+      .then((res) => (res.ok ? res.json() : null))
+      .then((data) => {
+        if (!active || !data) {
+          return;
+        }
+        setState((prev) => ({
+          design: { ...prev.design, ...(data.design ?? {}) },
+          css: data.css ?? '',
+          scss: data.scss ?? '',
+          styleDictionary: data.styleDictionary ?? '',
+          types: data.types ?? '',
+        }));
+      })
+      .catch(() => {});
+    return () => {
+      active = false;
+    };
+  }, [type]);
+
+  return state;
+};

package/src/app/generated/default-pages.json

@@ -0,0 +1 @@
+{}

package/src/app/generated/nav-shell.json

@@ -0,0 +1 @@
+[]

package/src/app/lib/api/query.ts

@@ -0,0 +1,6 @@
+export type QueryValue = string | string[] | undefined;
+
+export const singleQueryValue = (value: QueryValue): string | undefined => (Array.isArray(value) ? value[0] : value);
+
+export const joinedQueryValue = (value: QueryValue): string | undefined =>
+  Array.isArray(value) ? (value.length > 0 ? value.join('/') : undefined) : value;

package/src/app/lib/api/redact.ts

@@ -0,0 +1,46 @@
+/**
+ * Defensive secret redaction for registry and docs API responses.
+ *
+ * Config stores only env-var *names*, never secret values, so well-formed records should never
+ * carry a token or connection string. This is a belt-and-braces final pass over every response
+ * body: any string property whose key looks like a secret has its value replaced with
+ * `[redacted]`, so an accidentally-stored secret can never leak through the API.
+ */
+
+const SECRET_KEY_PATTERN =
+  /(token|secret|password|passwd|api[_-]?key|access[_-]?token|connection[_-]?string|database[_-]?url|authorization|bearer|credential)/i;
+
+const REDACTED = '[redacted]';
+
+/**
+ * Recursively clone `value`, replacing string values whose keys look secret with `[redacted]`.
+ * Arrays and nested objects are cloned, and cycles are replaced with a serializable marker.
+ */
+export const redactSecrets = <T>(value: T, ancestors: WeakSet<object> = new WeakSet()): T => {
+  if (Array.isArray(value)) {
+    if (ancestors.has(value)) {
+      return '[circular]' as T;
+    }
+    ancestors.add(value);
+    const result = value.map((item) => redactSecrets(item, ancestors));
+    ancestors.delete(value);
+    return result as T;
+  }
+  if (value && typeof value === 'object') {
+    if (ancestors.has(value as object)) {
+      return '[circular]' as T;
+    }
+    ancestors.add(value as object);
+    const result: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+      if (typeof val === 'string' && SECRET_KEY_PATTERN.test(key)) {
+        result[key] = REDACTED;
+      } else {
+        result[key] = redactSecrets(val, ancestors);
+      }
+    }
+    ancestors.delete(value as object);
+    return result as T;
+  }
+  return value;
+};

package/src/app/lib/asset-storage.ts

@@ -0,0 +1,81 @@
+/**
+ * Server-only asset storage runtime. Resolves the active provider from the baked server runtime
+ * config and lazily builds/memoizes adapter instances. Writes use the active adapter; reads resolve
+ * by each blob's recorded provider id, so DB-backed (`database`, inline bytea) and object-backed
+ * blobs coexist and old blobs stay readable after the active provider changes. `database` is the
+ * inline default with no adapter (bytes live directly in `asset_blobs.content`).
+ *
+ * Imported exclusively by registry API route handlers and the registry store.
+ */
+
+import { createVercelBlobStorage } from '@handoff/registry/asset-storage/adapters/vercel-blob';
+import { resolveAssetStorageSettings, type ResolvedAssetStorage } from '@handoff/registry/asset-storage/resolve';
+import type { AssetStorage, AssetStorageFactory } from '@handoff/registry/asset-storage/types';
+import type { AssetStorageProvider } from '@handoff/registry/db/schema';
+import { getServerRuntimeConfig } from './docs-api/runtime-config';
+
+let activeCache: ResolvedAssetStorage | null = null;
+const adapterCache = new Map<string, AssetStorage | null>();
+
+/** The active, fully-resolved asset storage settings for new uploads. */
+export const getActiveAssetStorage = (): ResolvedAssetStorage => {
+  if (!activeCache) {
+    activeCache = resolveAssetStorageSettings(getServerRuntimeConfig().assetStorage);
+  }
+  return activeCache;
+};
+
+/** Load a custom adapter module and coerce its default export (adapter object or factory) to an adapter. */
+const loadCustomAdapter = async (active: ResolvedAssetStorage): Promise<AssetStorage> => {
+  if (!active.module) {
+    throw new Error('A custom asset storage adapter is selected but no module path is configured.');
+  }
+  // Traced into the registry bundle at build time; resolved by Node at runtime (see build tracing).
+  const mod: any = await import(/* webpackIgnore: true */ active.module);
+  const exported = mod?.default ?? mod;
+  const adapter: unknown = typeof exported === 'function' ? await (exported as AssetStorageFactory)({ options: active.options, env: process.env }) : exported;
+  const candidate = adapter as Partial<AssetStorage> | null;
+  if (!candidate || typeof candidate.put !== 'function' || typeof candidate.get !== 'function' || typeof candidate.delete !== 'function') {
+    throw new Error(`Custom asset storage module "${active.module}" must default-export a defineAssetStorage adapter.`);
+  }
+  return candidate as AssetStorage;
+};
+
+/**
+ * Resolve the {@link AssetStorage} adapter for a provider id, or `null` when the provider is the
+ * inline `database` default (there is no adapter; content lives in the DB row). Reading a blob whose
+ * provider is no longer configured throws an actionable error rather than silently failing.
+ */
+export const getAssetStorageAdapter = async (provider: AssetStorageProvider): Promise<AssetStorage | null> => {
+  if (provider === 'database') {
+    return null;
+  }
+  if (adapterCache.has(provider)) {
+    return adapterCache.get(provider) ?? null;
+  }
+
+  const active = getActiveAssetStorage();
+  let adapter: AssetStorage;
+  if (provider === 'vercel-blob') {
+    adapter = createVercelBlobStorage({ tokenEnv: active.tokenEnv, options: active.options });
+  } else if (active.adapterKind === 'custom' && active.provider === provider) {
+    adapter = await loadCustomAdapter(active);
+  } else {
+    throw new Error(
+      `No asset storage adapter is configured for provider "${provider}". A blob was stored by that ` +
+        'provider but it is no longer selected. Restore its configuration (or migrate its objects) to read it.'
+    );
+  }
+
+  adapterCache.set(provider, adapter);
+  return adapter;
+};
+
+/** The adapter for the active provider (used for new uploads), or `null` for the inline database default. */
+export const getActiveAssetStorageAdapter = (): Promise<AssetStorage | null> => getAssetStorageAdapter(getActiveAssetStorage().provider);
+
+/** Reset memoized state (test seam only). */
+export const __resetAssetStorageCache = (): void => {
+  activeCache = null;
+  adapterCache.clear();
+};

package/src/app/lib/docs-api/artifacts.ts

@@ -0,0 +1,116 @@
+import fs from 'fs-extra';
+import path from 'path';
+
+/**
+ * Canonical artifact resolution for the workspace-mode docs read API.
+ *
+ * Logical artifact paths (e.g. `component/badge-primary.html`, `pattern/hero.html`,
+ * `component/main.css`) map onto files generated by the build under the app's mirrored
+ * `public/api` directory. This module owns the single safe mapping from a logical path to a file
+ * on disk: it rejects traversal/malformed paths up front, resolves the content type by extension,
+ * and never escapes the generated artifact root.
+ *
+ * Server-only: imported exclusively by API route handlers.
+ */
+
+/** Outcome of validating a logical artifact path segment list. */
+export interface ArtifactPathValidation {
+  ok: boolean;
+  /** Decoded, safe path segments when `ok`; empty otherwise. */
+  segments: string[];
+  /** Human-readable rejection reason when not `ok`. */
+  reason?: string;
+}
+
+/**
+ * Content type served for an artifact, keyed by file extension.
+ * A stored content type would win when present; in workspace mode the extension is authoritative.
+ */
+const CONTENT_TYPE_BY_EXT: Record<string, string> = {
+  '.json': 'application/json',
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+};
+
+const DEFAULT_CONTENT_TYPE = 'text/plain; charset=utf-8';
+
+/** Resolve the content type for an artifact path by its extension, defaulting to text/plain. */
+export const contentTypeForArtifactPath = (artifactPath: string): string => {
+  const ext = path.extname(artifactPath).toLowerCase();
+  return CONTENT_TYPE_BY_EXT[ext] ?? DEFAULT_CONTENT_TYPE;
+};
+
+/** Whether a single decoded path segment is structurally safe (no traversal, no separators). */
+const isSafeSegment = (segment: string): boolean =>
+  segment.length > 0 && segment !== '.' && segment !== '..' && !segment.includes('/') && !segment.includes('\\');
+
+/**
+ * Validate the catch-all `artifactPath` segments coming from the route. Rejects:
+ * zero segments; any segment that is empty / `.` / `..` / contains a path separator — checked both
+ * raw and after `decodeURIComponent` (so encoded `%2E%2E` is rejected too); or any segment that
+ * fails to decode.
+ */
+export const validateArtifactSegments = (rawSegments: string[] | undefined): ArtifactPathValidation => {
+  if (!rawSegments || rawSegments.length === 0) {
+    return { ok: false, segments: [], reason: 'Artifact path has no segments.' };
+  }
+
+  const decoded: string[] = [];
+  for (const raw of rawSegments) {
+    if (!isSafeSegment(raw)) {
+      return { ok: false, segments: [], reason: `Unsafe artifact path segment "${raw}".` };
+    }
+    let decodedSegment: string;
+    try {
+      decodedSegment = decodeURIComponent(raw);
+    } catch {
+      return { ok: false, segments: [], reason: `Artifact path segment "${raw}" could not be decoded.` };
+    }
+    if (!isSafeSegment(decodedSegment)) {
+      return { ok: false, segments: [], reason: `Unsafe artifact path segment "${raw}".` };
+    }
+    decoded.push(decodedSegment);
+  }
+
+  return { ok: true, segments: decoded };
+};
+
+/**
+ * Absolute path of the generated artifact root (`public/api`) for the running app. Artifacts are
+ * mirrored into the app's own public directory by the build (`syncPublicFiles`), so the app reads
+ * them from its module-local `.handoff/{projectId}/public/api` — the same location the rest of the
+ * app already reads `components.json`/`patterns.json` from.
+ */
+export const getArtifactRoot = (): string =>
+  path.resolve(
+    process.env.HANDOFF_MODULE_PATH ?? '',
+    '.handoff',
+    process.env.HANDOFF_PROJECT_ID ?? '',
+    'public',
+    'api'
+  );
+
+/** A resolved artifact ready to serve. */
+export interface ResolvedArtifact {
+  absolutePath: string;
+  contentType: string;
+}
+
+/**
+ * Resolve already-validated logical artifact segments to a readable file under the artifact root,
+ * or `null` when the artifact does not exist. The resolved path is re-checked to be contained
+ * within the root as defense in depth, even though segments are pre-validated.
+ */
+export const resolveArtifactFile = (segments: string[]): ResolvedArtifact | null => {
+  const root = getArtifactRoot();
+  const absolutePath = path.resolve(root, ...segments);
+  const relative = path.relative(root, absolutePath);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    return null;
+  }
+  if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+    return null;
+  }
+  return { absolutePath, contentType: contentTypeForArtifactPath(absolutePath) };
+};

package/src/app/lib/docs-api/backend.ts

@@ -0,0 +1,151 @@
+import fs from 'fs-extra';
+import path from 'path';
+import type { ComponentListObject, PageListObject, PatternListObject } from '@handoff/transformers/preview/types';
+import type { TokenSetKind } from '@handoff/registry/tokens/sets';
+import { FilesystemAssetStore } from '@handoff/store/filesystem-assets';
+import type { AssetContentResource, AssetMetadata, TokenArtifactResource } from '@handoff/store';
+import { getArtifactRoot, resolveArtifactFile } from './artifacts';
+import {
+  getComponentDetail as getWorkspaceComponentDetail,
+  getPageDetail as getWorkspacePageDetail,
+  getPatternDetail as getWorkspacePatternDetail,
+  getTokenSetDetail as getWorkspaceTokenSetDetail,
+  listComponents as listWorkspaceComponents,
+  listPages as listWorkspacePages,
+  listPatterns as listWorkspacePatterns,
+  listTokenSets as listWorkspaceTokenSets,
+  type ComponentDetail,
+  type PageDetail,
+  type PatternDetail,
+} from './records';
+import { getServerRuntimeConfig } from './runtime-config';
+
+/**
+ * Mode-aware data source for the docs read API.
+ *
+ * The `/api/docs/*` routes depend only on this interface, so they return the *same stable shapes at
+ * the same URLs* regardless of which backing resolves them. Workspace mode reads generated
+ * filesystem artifacts; registry mode reads the DB-backed docs read-model artifacts
+ * published to the registry. The registry backing is loaded lazily so its Drizzle/Postgres
+ * dependencies never enter the workspace/static path.
+ */
+
+/** A resolved artifact ready to write to the response: its content type and raw body. */
+export interface ResolvedArtifactBody {
+  contentType: string;
+  body: Buffer | string;
+}
+
+/** A minimal token-set listing item (id + kind) for navigation. */
+export interface TokenSetListItem {
+  id: string;
+  kind: TokenSetKind;
+}
+
+/** A token set's detail: its extracted record slice + every generated artifact, served byte-for-byte. */
+export interface TokenSetDetail {
+  id: string;
+  kind: TokenSetKind;
+  /** `IColorObject[]`/…/`IFileComponentObject` — interpreted by the route per `kind`. */
+  record: unknown;
+  artifacts: TokenArtifactResource[];
+}
+
+/** The data operations every docs read API route is expressed in terms of. */
+export interface DocsBackend {
+  listComponents(): Promise<ComponentListObject[]>;
+  listPatterns(): Promise<PatternListObject[]>;
+  /**
+   * List published pages. The real consumer is registry-mode navigation; the workspace impl is
+   * vestigial (workspace nav is baked at build time and the catch-all reads markdown directly).
+   */
+  listPages(): Promise<PageListObject[]>;
+  getComponentDetail(id: string): Promise<ComponentDetail | null>;
+  getPatternDetail(id: string): Promise<PatternDetail | null>;
+  /** A page's record + rendered markdown body, or `null` when absent. Read by the catch-all route. */
+  getPageDetail(id: string): Promise<PageDetail | null>;
+  /** Resolve an already-validated logical artifact path, or `null` when it cannot be served. */
+  resolveArtifact(segments: string[]): Promise<ResolvedArtifactBody | null>;
+  /** List logical token sets (id + kind). The real consumer is registry-mode token navigation. */
+  listTokenSets(): Promise<TokenSetListItem[]>;
+  /** A token set's record + generated artifacts by stable id, or `null` when absent. */
+  getTokenSetDetail(id: string): Promise<TokenSetDetail | null>;
+  /** Lightweight metadata for every asset in a collection (never binary bodies). */
+  listAssets(collection: string): Promise<AssetMetadata[]>;
+  /** One asset's resolved content (bytes or a provider redirect), or `null` when absent. */
+  getAssetContent(collection: string, assetPath: string): Promise<AssetContentResource | null>;
+}
+
+/**
+ * Workspace asset store over the app's mirrored `public/api` tree + copied archives. Registry mode
+ * serves assets from the database; this best-effort filesystem view keeps the {@link DocsBackend}
+ * contract honest (workspace pages themselves read assets directly, not through this API).
+ */
+const appPublicRoot = (): string =>
+  path.resolve(process.env.HANDOFF_MODULE_PATH ?? '', '.handoff', process.env.HANDOFF_PROJECT_ID ?? '', 'public');
+
+let workspaceAssetStore: FilesystemAssetStore | null = null;
+const getWorkspaceAssetStore = (): FilesystemAssetStore => {
+  if (!workspaceAssetStore) {
+    workspaceAssetStore = new FilesystemAssetStore({
+      workingPath: appPublicRoot(),
+      getAssetsApiPath: () => getArtifactRoot(),
+      getIconsZipFilePath: () => path.join(appPublicRoot(), 'icons.zip'),
+      getLogosZipFilePath: () => path.join(appPublicRoot(), 'logos.zip'),
+    });
+  }
+  return workspaceAssetStore;
+};
+
+/** Workspace backing: generated filesystem artifacts under the app's mirrored `public/api` root. */
+const workspaceBackend: DocsBackend = {
+  async listComponents() {
+    return listWorkspaceComponents();
+  },
+  async listPatterns() {
+    return listWorkspacePatterns();
+  },
+  async listPages() {
+    return listWorkspacePages();
+  },
+  async getComponentDetail(id: string) {
+    return getWorkspaceComponentDetail(id);
+  },
+  async getPatternDetail(id: string) {
+    return getWorkspacePatternDetail(id);
+  },
+  async getPageDetail(id: string) {
+    return getWorkspacePageDetail(id);
+  },
+  async resolveArtifact(segments: string[]) {
+    const resolved = resolveArtifactFile(segments);
+    if (!resolved) {
+      return null;
+    }
+    return { contentType: resolved.contentType, body: fs.readFileSync(resolved.absolutePath) };
+  },
+  async listTokenSets() {
+    return listWorkspaceTokenSets();
+  },
+  async getTokenSetDetail(id: string) {
+    return getWorkspaceTokenSetDetail(id);
+  },
+  async listAssets(collection: string) {
+    return getWorkspaceAssetStore().listAssets(collection);
+  },
+  async getAssetContent(collection: string, assetPath: string) {
+    return getWorkspaceAssetStore().getAssetContent(collection, assetPath);
+  },
+};
+
+/**
+ * Resolve the docs backend for the active runtime mode. Registry mode dynamically imports the
+ * DB-backed backing so workspace dev/build never loads the database driver code.
+ */
+export const resolveDocsBackend = async (): Promise<DocsBackend> => {
+  if (getServerRuntimeConfig().mode === 'registry') {
+    const { createRegistryDocsBackend } = await import('./registry');
+    return createRegistryDocsBackend();
+  }
+  return workspaceBackend;
+};

package/src/app/lib/docs-api/errors.ts

@@ -0,0 +1,52 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { singleQueryValue } from '../api/query';
+import { redactSecrets } from '../api/redact';
+
+/**
+ * Docs read API error contract.
+ *
+ * Unlike the registry management API, docs read responses carry a bare `{ error: { code, message } }`
+ * envelope (no `meta`). Codes are deliberately narrow: a malformed/traversal/missing route param or
+ * record is `not_found`; a missing content artifact (or a missing required HTML reference) is
+ * `artifact_not_found`; everything else maps to `method_not_allowed` or `unexpected_error`.
+ */
+export type DocsErrorCode = 'not_found' | 'artifact_not_found' | 'method_not_allowed' | 'unexpected_error';
+
+const STATUS_BY_CODE: Record<DocsErrorCode, number> = {
+  not_found: 404,
+  artifact_not_found: 404,
+  method_not_allowed: 405,
+  unexpected_error: 500,
+};
+
+/** Write a docs read API error response with the status mapped from its code. */
+export const sendDocsError = (res: NextApiResponse, code: DocsErrorCode, message: string): void => {
+  res.status(STATUS_BY_CODE[code]).json(redactSecrets({ error: { code, message } }));
+};
+
+/**
+ * Guard a GET-only docs route. Returns `true` when the request is a GET and the handler should
+ * proceed; otherwise it writes a `405 method_not_allowed` response and returns `false`.
+ */
+export const ensureGet = (req: NextApiRequest, res: NextApiResponse): boolean => {
+  if (req.method === 'GET') {
+    return true;
+  }
+  res.setHeader('Allow', 'GET');
+  sendDocsError(res, 'method_not_allowed', `Method ${req.method ?? 'unknown'} not allowed; docs read API is GET-only.`);
+  return false;
+};
+
+/**
+ * Resolve an entity id from a dynamic route param that carries an explicit `.json` extension
+ * (metadata reads use explicit `.json` URLs). Returns the id without the
+ * extension, or `undefined` when the param is missing or not a `.json` request.
+ */
+export const idFromJsonParam = (value: string | string[] | undefined): string | undefined => {
+  const raw = singleQueryValue(value);
+  if (!raw || !raw.endsWith('.json')) {
+    return undefined;
+  }
+  const id = raw.slice(0, -'.json'.length);
+  return id.length > 0 ? id : undefined;
+};