handoff-app 1.2.2-7 → 2.0.0-0

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

@@ -0,0 +1,34 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { redactSecrets } from '../api/redact';
+import { resolveDocsBackend, type DocsBackend } from './backend';
+import { ensureGet, sendDocsError } from './errors';
+
+/** Write a successful docs read API JSON response, redacting any accidentally-stored secrets. */
+export const sendDocsData = (res: NextApiResponse, status: number, data: unknown): void => {
+  res.status(status).json(redactSecrets(data));
+};
+
+/**
+ * Shared entry point for every `/api/docs/*` route.
+ *
+ * Applies the GET-only guard, resolves the mode-aware {@link DocsBackend}, and runs the route's
+ * logic against it — translating any thrown failure (e.g. a database that is unreachable in
+ * registry mode) into the docs read API's `unexpected_error` envelope. Routes stay thin and never
+ * need to know which backing serves them.
+ */
+export const handleDocsRoute = async (
+  req: NextApiRequest,
+  res: NextApiResponse,
+  handler: (backend: DocsBackend) => Promise<void>
+): Promise<void> => {
+  if (!ensureGet(req, res)) {
+    return;
+  }
+  try {
+    const backend = await resolveDocsBackend();
+    await handler(backend);
+  } catch (error) {
+    console.error('Docs read API request failed.', error);
+    sendDocsError(res, 'unexpected_error', 'Unexpected docs read API error.');
+  }
+};

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

@@ -0,0 +1,7 @@
+/** Route facing docs API helpers. Backend and filesystem details stay in their own modules. */
+
+export { ensureGet, idFromJsonParam, sendDocsError, type DocsErrorCode } from './errors';
+export { serveArtifactBySegments } from './serve';
+export { handleDocsRoute, sendDocsData } from './handler';
+export { resolveDocsBackend } from './backend';
+export { getServerRuntimeConfig, type ServerRuntimeConfig } from './runtime-config';

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

@@ -0,0 +1,189 @@
+import fs from 'fs-extra';
+import matter from 'gray-matter';
+import path from 'path';
+import { Types as CoreTypes } from 'handoff-core';
+import { normalizePageDeclaration } from '@handoff/config/normalizers/page';
+import { deriveTokenSets, emptyTokenDocument, setNameForId } from '@handoff/registry/tokens/sets';
+import type { TokenArtifactResource } from '@handoff/store';
+import type { ComponentListObject, PageListObject, PatternListObject } from '@handoff/transformers/preview/types';
+import type { ArtifactBuildStatus } from '@handoff/artifacts/types';
+import { getArtifactRoot } from './artifacts';
+import type { TokenSetDetail, TokenSetListItem } from './backend';
+
+/**
+ * Workspace-mode metadata reads for the docs read API.
+ *
+ * List/detail metadata is served from the generated `components.json`/`patterns.json` summaries and
+ * the per-entity `component/{id}.json`/`pattern/{id}.json` artifacts — the same files the build
+ * produces from the normalized store records. The shapes returned here (`ComponentListObject` /
+ * `PatternListObject`) are exactly what the store exposes, so registry mode can serve the
+ * same shapes at the same URLs from the database. HTML/asset artifacts are served separately
+ * through the canonical artifact route.
+ */
+
+/** Detail metadata carries the entity record plus a build state derived from artifact presence. */
+export type ComponentDetail = ComponentListObject & { build: { status: ArtifactBuildStatus } };
+export type PatternDetail = PatternListObject & { build: { status: ArtifactBuildStatus } };
+/** A page's normalized record plus its rendered markdown body. */
+export type PageDetail = PageListObject & { content: string };
+
+const readJsonFile = <T>(absolutePath: string): T | null => {
+  try {
+    if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+      return null;
+    }
+    return JSON.parse(fs.readFileSync(absolutePath, 'utf8')) as T;
+  } catch {
+    return null;
+  }
+};
+
+/** Whether the entity's primary detail artifact has been generated. */
+const detailArtifactExists = (relativePath: string): boolean => {
+  const absolutePath = path.resolve(getArtifactRoot(), relativePath);
+  return fs.existsSync(absolutePath) && fs.statSync(absolutePath).isFile();
+};
+
+/**
+ * Build state for an entity in workspace mode. State is derived from artifact presence: `current`
+ * when the entity's detail artifact exists, otherwise `missing` (a metadata-only record that is
+ * still listable while its preview/asset routes report missing-artifact state).
+ */
+const deriveBuildStatus = (detailRelativePath: string): ArtifactBuildStatus =>
+  detailArtifactExists(detailRelativePath) ? 'current' : 'missing';
+
+export const listComponents = (): ComponentListObject[] =>
+  readJsonFile<ComponentListObject[]>(path.resolve(getArtifactRoot(), 'components.json')) ?? [];
+
+export const listPatterns = (): PatternListObject[] =>
+  readJsonFile<PatternListObject[]>(path.resolve(getArtifactRoot(), 'patterns.json')) ?? [];
+
+export const getComponentDetail = (id: string): ComponentDetail | null => {
+  const record = listComponents().find((component) => component.id === id);
+  if (!record) {
+    return null;
+  }
+  return { ...record, build: { status: deriveBuildStatus(path.join('component', `${id}.json`)) } };
+};
+
+export const getPatternDetail = (id: string): PatternDetail | null => {
+  const record = listPatterns().find((pattern) => pattern.id === id);
+  if (!record) {
+    return null;
+  }
+  return { ...record, build: { status: deriveBuildStatus(path.join('pattern', `${id}.json`)) } };
+};
+
+/**
+ * Workspace-mode page reads. These scan `<workingPath>/pages/` directly (there is no generated page
+ * summary). Vestigial in practice — workspace nav is baked and the catch-all reads markdown through
+ * `fetchDocPageMarkdown` — but implemented honestly so the {@link DocsBackend} contract holds.
+ */
+const workingPagesRoot = (): string => path.resolve(process.env.HANDOFF_WORKING_PATH ?? '', 'pages');
+
+/** Recursively collect page slug segments under `root` (every `.md` except `index.md`). */
+const collectPageSlugs = (root: string, parts: string[] = []): string[][] => {
+  if (!fs.existsSync(root)) return [];
+  const out: string[][] = [];
+  for (const entry of fs.readdirSync(root)) {
+    const full = path.join(root, entry);
+    if (fs.statSync(full).isDirectory()) {
+      out.push(...collectPageSlugs(full, [...parts, entry]));
+    } else if (entry.endsWith('.md') && entry !== 'index.md') {
+      out.push([...parts, entry.replace(/\.md$/, '')]);
+    }
+  }
+  return out;
+};
+
+export const listPages = (): PageListObject[] => {
+  const root = workingPagesRoot();
+  return collectPageSlugs(root).map((segments) => {
+    const slug = segments.join('/');
+    const sourcePath = path.resolve(root, `${slug}.md`);
+    const { data } = matter(fs.readFileSync(sourcePath, 'utf8'));
+    return normalizePageDeclaration(data, { id: slug, routePath: `/${slug}`, sourcePath });
+  });
+};
+
+export const getPageDetail = (id: string): PageDetail | null => {
+  const root = workingPagesRoot();
+  const segments = collectPageSlugs(root).find((candidate) => candidate.join('/') === id);
+  if (!segments) {
+    return null;
+  }
+  const slug = segments.join('/');
+  const sourcePath = path.resolve(root, `${slug}.md`);
+  const { data, content } = matter(fs.readFileSync(sourcePath, 'utf8'));
+  return { ...normalizePageDeclaration(data, { id: slug, routePath: `/${slug}`, sourcePath }), content };
+};
+
+/**
+ * Workspace-mode token reads. The generated `tokens.json` and token style files are read straight
+ * from the export dir (`HANDOFF_EXPORT_PATH`, else `<cwd>/<HANDOFF_OUTPUT_DIR>`), mirroring the
+ * build-time `getTokens`/`fetchTokensString` readers so token behavior is identical to today's. The
+ * generated-file layout mirrors `fetchTokensString` (sass/types/sd/css) to preserve current
+ * semantics; custom transformer outputs are only surfaced through the registry backing.
+ */
+const tokensExportRoot = (): string =>
+  process.env.HANDOFF_EXPORT_PATH
+    ? path.resolve(process.env.HANDOFF_EXPORT_PATH)
+    : path.resolve(process.cwd(), process.env.HANDOFF_OUTPUT_DIR ?? 'exported');
+
+const readTokensDocument = (): CoreTypes.IDocumentationObject => {
+  const filePath = path.resolve(tokensExportRoot(), 'tokens.json');
+  if (!fs.existsSync(filePath)) {
+    return emptyTokenDocument();
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8')) as CoreTypes.IDocumentationObject;
+  } catch {
+    return emptyTokenDocument();
+  }
+};
+
+const readTokenFile = (relativePath: string): string | null => {
+  const absolutePath = path.resolve(tokensExportRoot(), 'tokens', relativePath);
+  if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+    return null;
+  }
+  try {
+    return fs.readFileSync(absolutePath, 'utf8');
+  } catch {
+    return null;
+  }
+};
+
+/** Read the four core generated formats for a set name, mirroring `fetchTokensString`'s layout. */
+const readCoreTokenArtifacts = (name: string): TokenArtifactResource[] => {
+  const candidates: { path: string; format: string; contentType: string }[] = [
+    { path: `sass/${name}.scss`, format: 'scss', contentType: 'text/x-scss; charset=utf-8' },
+    { path: `types/${name}.scss`, format: 'types', contentType: 'text/x-scss; charset=utf-8' },
+    { path: `css/${name}.css`, format: 'css', contentType: 'text/css; charset=utf-8' },
+    { path: `sd/tokens/${name}.tokens.json`, format: 'styleDictionary', contentType: 'application/json; charset=utf-8' },
+    { path: `sd/tokens/${name}/${name}.tokens.json`, format: 'styleDictionary', contentType: 'application/json; charset=utf-8' },
+  ];
+  const artifacts: TokenArtifactResource[] = [];
+  const seenFormats = new Set<string>();
+  for (const candidate of candidates) {
+    if (seenFormats.has(candidate.format)) {
+      continue;
+    }
+    const content = readTokenFile(candidate.path);
+    if (content != null) {
+      artifacts.push({ path: candidate.path, format: candidate.format, content, contentType: candidate.contentType });
+      seenFormats.add(candidate.format);
+    }
+  }
+  return artifacts;
+};
+
+export const listTokenSets = (): TokenSetListItem[] => deriveTokenSets(readTokensDocument()).map(({ id, kind }) => ({ id, kind }));
+
+export const getTokenSetDetail = (id: string): TokenSetDetail | null => {
+  const set = deriveTokenSets(readTokensDocument()).find((candidate) => candidate.id === id);
+  if (!set) {
+    return null;
+  }
+  return { id: set.id, kind: set.kind, record: set.record, artifacts: readCoreTokenArtifacts(setNameForId(id)) };
+};

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

@@ -0,0 +1,130 @@
+import { and, eq, inArray } from 'drizzle-orm';
+import matter from 'gray-matter';
+import type { ArtifactBuildStatus } from '@handoff/artifacts/types';
+import type { RegistryDatabase } from '@handoff/registry/db/client';
+import { buildMetadata, docsArtifacts } from '@handoff/registry/db/schema';
+import { createRegistryStore } from '@handoff/store/registry';
+import { contentTypeForArtifactPath } from './artifacts';
+import type { DocsBackend, ResolvedArtifactBody } from './backend';
+import { getRegistryConnection } from '../registry-connection';
+import { getAssetStorageAdapter } from '../asset-storage';
+
+/**
+ * Registry-mode backing for the docs read API.
+ *
+ * Everything here resolves from the registry database: normalized records through the DB-backed
+ * store, build state from the `build_metadata` table, and content artifacts from
+ * the `docs_artifacts` table. No read path materializes source files or runs the build pipeline.
+ * The database connection is created once per server process and reused across requests.
+ *
+ * Server-only: dynamically imported by {@link resolveDocsBackend} only when `runtime.mode` is
+ * `registry`, so the Drizzle/Postgres driver code never loads in workspace dev/build.
+ */
+
+/**
+ * Resolve a content artifact from the registry by logical path. Returns `null` (→ `artifact_not_found`)
+ * when the artifact is absent, when its content is stored externally (a future object-storage
+ * reference with no inline content), or when a **required** structured reference it depends on is
+ * not present — an HTML artifact must never be served with a missing required dependency.
+ */
+const resolveRegistryArtifact = async (db: RegistryDatabase, segments: string[]): Promise<ResolvedArtifactBody | null> => {
+  const artifactPath = segments.join('/');
+  const rows = await db.select().from(docsArtifacts).where(eq(docsArtifacts.path, artifactPath)).limit(1);
+  const artifact = rows[0];
+  if (!artifact || artifact.content == null) {
+    return null;
+  }
+
+  const requiredPaths = Array.from(
+    new Set((artifact.references ?? []).filter((reference) => reference.required).map((reference) => reference.path))
+  );
+  if (requiredPaths.length > 0) {
+    const rows = await db
+      .select({ path: docsArtifacts.path, content: docsArtifacts.content })
+      .from(docsArtifacts)
+      .where(inArray(docsArtifacts.path, requiredPaths));
+    if (rows.filter(({ content }) => content != null).length !== requiredPaths.length) {
+      return null;
+    }
+  }
+
+  const contentType = artifact.contentType || contentTypeForArtifactPath(artifactPath);
+  return { contentType, body: artifact.content };
+};
+
+/** Build state for an entity: the stored status, or `missing` for a metadata-only record. */
+const buildStatusFor = async (
+  db: RegistryDatabase,
+  entityKind: 'component' | 'pattern',
+  entityId: string
+): Promise<ArtifactBuildStatus> => {
+  const rows = await db
+    .select({ status: buildMetadata.status })
+    .from(buildMetadata)
+    .where(and(eq(buildMetadata.entityKind, entityKind), eq(buildMetadata.entityId, entityId)))
+    .limit(1);
+  return rows[0]?.status ?? 'missing';
+};
+
+/** Construct the registry-mode docs backend over a live database connection. */
+export const createRegistryDocsBackend = async (): Promise<DocsBackend> => {
+  const connection = await getRegistryConnection();
+  const { db } = connection;
+  // Inject the storage-adapter resolver so object-backed asset content resolves by provider id.
+  const store = createRegistryStore({ db, resolveAssetAdapter: getAssetStorageAdapter });
+
+  return {
+    async listComponents() {
+      return store.components.list();
+    },
+    async listPatterns() {
+      return store.patterns.list();
+    },
+    async listPages() {
+      return store.pages.list();
+    },
+    async getComponentDetail(id: string) {
+      const record = await store.components.get(id);
+      if (!record) {
+        return null;
+      }
+      return { ...record, build: { status: await buildStatusFor(db, 'component', id) } };
+    },
+    async getPatternDetail(id: string) {
+      const record = await store.patterns.get(id);
+      if (!record) {
+        return null;
+      }
+      return { ...record, build: { status: await buildStatusFor(db, 'pattern', id) } };
+    },
+    async getPageDetail(id: string) {
+      const record = await store.pages.get(id);
+      if (!record) {
+        return null;
+      }
+      // The markdown body travels as the page's single source file; parse it to drop the frontmatter.
+      const files = await store.pages.getRelatedSourceFiles(id);
+      const { content } = matter(files[0]?.content ?? '');
+      return { ...record, content };
+    },
+    async resolveArtifact(segments: string[]) {
+      return resolveRegistryArtifact(db, segments);
+    },
+    async listTokenSets() {
+      return (await store.tokens.listSets()).map(({ id, kind }) => ({ id, kind }));
+    },
+    async getTokenSetDetail(id: string) {
+      const set = await store.tokens.getSet(id);
+      if (!set) {
+        return null;
+      }
+      return { id: set.id, kind: set.kind, record: set.record, artifacts: await store.tokens.getArtifacts(id) };
+    },
+    async listAssets(collection: string) {
+      return store.assets.listAssets(collection);
+    },
+    async getAssetContent(collection: string, assetPath: string) {
+      return store.assets.getAssetContent(collection, assetPath);
+    },
+  };
+};

package/src/app/lib/docs-api/runtime-config.ts

@@ -0,0 +1,173 @@
+import fs from 'fs-extra';
+import path from 'path';
+import type { RuntimeMode } from '@handoff/types/config';
+import {
+  DEFAULT_DATABASE_URL_ENV,
+  DEFAULT_REGISTRY_ADAPTER,
+  DEFAULT_REGISTRY_API_TOKEN_ENV,
+  type RegistryDatabaseAdapter,
+} from '@handoff/registry/db/adapter';
+import { DEFAULT_ASSET_STORAGE_ADAPTER, type AssetStorageSettings } from '@handoff/registry/asset-storage/resolve';
+
+/**
+ * Server-side runtime resolution for the docs read API.
+ *
+ * The docs read API is mode-aware: workspace mode resolves artifacts from generated filesystem
+ * files, registry mode resolves them from the database. The browser-facing `client.config.json`
+ * carries only the resolved {@link RuntimeMode} (no connection details), so the server needs its
+ * own non-secret source for the registry connection *inputs* — the selected adapter and the *name*
+ * of the env var holding the database URL. The build persists these to `runtime.server.json`
+ * alongside `client.config.json`; this module reads them back, never crossing secrets to the
+ * browser (the connection-string value is resolved from the env var at request time, not here).
+ *
+ * Server-only: imported exclusively by API route handlers and their helpers.
+ */
+
+/** Non-secret registry connection inputs resolved on the server. */
+export interface ServerRegistryRuntimeConfig {
+  /** Selected built-in database adapter. */
+  adapter: RegistryDatabaseAdapter;
+  /** Name of the env var holding the database connection string (value resolved at request time). */
+  databaseUrlEnv: string;
+  /**
+   * Name of the env var holding the registry management API bearer token. The token *value* is
+   * resolved from the environment at request time by the management API guard — never persisted.
+   */
+  apiTokenEnv: string;
+}
+
+/** Resolved server-side runtime configuration for the docs read API. */
+export interface ServerRuntimeConfig {
+  mode: RuntimeMode;
+  registry: ServerRegistryRuntimeConfig;
+  /**
+   * Asset storage selection for registry mode (provider + non-secret options + env-var names). Secret
+   * values are resolved from `process.env` at request time, never persisted here.
+   */
+  assetStorage: AssetStorageSettings;
+}
+
+let cached: ServerRuntimeConfig | null = null;
+
+/** Safe defaults: workspace mode with the default Postgres adapter + `DATABASE_URL` env var. */
+const defaults = (): ServerRuntimeConfig => ({
+  mode: 'workspace',
+  registry: {
+    adapter: DEFAULT_REGISTRY_ADAPTER,
+    databaseUrlEnv: DEFAULT_DATABASE_URL_ENV,
+    apiTokenEnv: DEFAULT_REGISTRY_API_TOKEN_ENV,
+  },
+  assetStorage: { adapter: DEFAULT_ASSET_STORAGE_ADAPTER },
+});
+
+/** Parse the baked asset-storage selection from env (names/selectors only; JSON options tolerated). */
+const assetStorageFromEnv = (): AssetStorageSettings => {
+  const adapter = process.env.HANDOFF_ASSET_STORAGE_ADAPTER?.trim();
+  let options: Record<string, unknown> | undefined;
+  const rawOptions = process.env.HANDOFF_ASSET_STORAGE_OPTIONS?.trim();
+  if (rawOptions) {
+    try {
+      const parsed = JSON.parse(rawOptions);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) options = parsed as Record<string, unknown>;
+    } catch {
+      // Ignore malformed baked options rather than crash the server.
+    }
+  }
+  const maxInline = Number(process.env.HANDOFF_ASSET_STORAGE_MAX_INLINE_BYTES);
+  return {
+    adapter: adapter === 'vercel-blob' || adapter === 'custom' ? adapter : DEFAULT_ASSET_STORAGE_ADAPTER,
+    module: process.env.HANDOFF_ASSET_STORAGE_MODULE?.trim() || undefined,
+    tokenEnv: process.env.HANDOFF_ASSET_STORAGE_TOKEN_ENV?.trim() || undefined,
+    maxInlineBytes: Number.isFinite(maxInline) && maxInline > 0 ? maxInline : undefined,
+    options,
+  };
+};
+
+/** Absolute path of the server-only runtime config persisted next to `client.config.json`. */
+const serverRuntimeConfigPath = (): string =>
+  path.resolve(
+    process.env.HANDOFF_MODULE_PATH ?? '',
+    '.handoff',
+    process.env.HANDOFF_PROJECT_ID ?? '',
+    'runtime.server.json'
+  );
+
+/**
+ * Resolve the server-side runtime config from the values baked into the bundle at build time
+ * (`HANDOFF_RUNTIME_MODE` + registry connection inputs). Returns `null` when no mode was baked, so
+ * the file-based path can take over for apps built before env baking existed.
+ *
+ * This is the resolution path for the packaged registry app: its deploy host has none of
+ * the build-machine paths `runtime.server.json` is keyed on, so mode + the DB env-var *name* are
+ * carried in the bundle instead. Mode stays config-only — these were derived from `runtime.*` at
+ * build, never inferred from the deploy environment.
+ */
+const fromEnv = (): ServerRuntimeConfig | null => {
+  const mode = process.env.HANDOFF_RUNTIME_MODE?.trim();
+  if (!mode) {
+    return null;
+  }
+  const databaseUrlEnv = process.env.HANDOFF_REGISTRY_DATABASE_URL_ENV?.trim() || DEFAULT_DATABASE_URL_ENV;
+  const apiTokenEnv = process.env.HANDOFF_REGISTRY_API_TOKEN_ENV?.trim() || DEFAULT_REGISTRY_API_TOKEN_ENV;
+  return {
+    mode: mode === 'registry' ? 'registry' : 'workspace',
+    registry: {
+      adapter: process.env.HANDOFF_REGISTRY_ADAPTER?.trim() === 'neon' ? 'neon' : 'pg',
+      databaseUrlEnv,
+      apiTokenEnv,
+    },
+    assetStorage: assetStorageFromEnv(),
+  };
+};
+
+/**
+ * Resolve the server-side runtime config, preferring the values baked into the bundle, then reading
+ * `runtime.server.json` when present, and falling back to safe workspace defaults otherwise (so an
+ * app built before either source existed keeps behaving as a workspace). The result is cached for
+ * the lifetime of the server process.
+ */
+export const getServerRuntimeConfig = (): ServerRuntimeConfig => {
+  if (cached) {
+    return cached;
+  }
+
+  const envConfig = fromEnv();
+  if (envConfig) {
+    cached = envConfig;
+    return cached;
+  }
+
+  try {
+    const file = serverRuntimeConfigPath();
+    if (fs.existsSync(file)) {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8')) as Partial<ServerRuntimeConfig>;
+      const databaseUrlEnv =
+        typeof parsed?.registry?.databaseUrlEnv === 'string' && parsed.registry.databaseUrlEnv.trim()
+          ? parsed.registry.databaseUrlEnv.trim()
+          : DEFAULT_DATABASE_URL_ENV;
+      const apiTokenEnv =
+        typeof parsed?.registry?.apiTokenEnv === 'string' && parsed.registry.apiTokenEnv.trim()
+          ? parsed.registry.apiTokenEnv.trim()
+          : DEFAULT_REGISTRY_API_TOKEN_ENV;
+      const assetStorage: AssetStorageSettings =
+        parsed?.assetStorage && typeof parsed.assetStorage === 'object'
+          ? parsed.assetStorage
+          : { adapter: DEFAULT_ASSET_STORAGE_ADAPTER };
+      cached = {
+        mode: parsed?.mode === 'registry' ? 'registry' : 'workspace',
+        registry: {
+          adapter: parsed?.registry?.adapter === 'neon' ? 'neon' : 'pg',
+          databaseUrlEnv,
+          apiTokenEnv,
+        },
+        assetStorage,
+      };
+      return cached;
+    }
+  } catch {
+    // Fall through to defaults on any read/parse failure.
+  }
+
+  cached = defaults();
+  return cached;
+};

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

@@ -0,0 +1,37 @@
+import type { NextApiResponse } from 'next';
+import { validateArtifactSegments } from './artifacts';
+import type { DocsBackend } from './backend';
+import { sendDocsError } from './errors';
+
+/**
+ * Serve a logical artifact by its path segments, applying the docs read API contract end to end:
+ *
+ * - traversal/malformed segments → `404 not_found`
+ * - an artifact the backend cannot serve → `404 artifact_not_found`
+ * - otherwise the raw body with the resolved `Content-Type`
+ *
+ * Segment validation is mode-independent and stays here; the actual artifact lookup is delegated to
+ * the active {@link DocsBackend} (filesystem in workspace mode, database in registry mode), so the
+ * canonical artifact route and the convenience preview/inspect/asset routes all produce identical
+ * responses regardless of which URL or which mode reached them.
+ */
+export const serveArtifactBySegments = async (
+  res: NextApiResponse,
+  rawSegments: string[] | undefined,
+  backend: DocsBackend
+): Promise<void> => {
+  const validation = validateArtifactSegments(rawSegments);
+  if (!validation.ok) {
+    sendDocsError(res, 'not_found', validation.reason ?? 'Invalid artifact path.');
+    return;
+  }
+
+  const resolved = await backend.resolveArtifact(validation.segments);
+  if (!resolved) {
+    sendDocsError(res, 'artifact_not_found', `Artifact "${validation.segments.join('/')}" was not found.`);
+    return;
+  }
+
+  res.setHeader('Content-Type', resolved.contentType);
+  res.status(200).send(resolved.body);
+};

package/src/app/lib/docs-api/token-detail.ts

@@ -0,0 +1,19 @@
+import type { TokenArtifactResource } from '@handoff/store';
+
+/**
+ * Pick the four UI-known download strings (css/scss/styleDictionary/types) from a token set's
+ * generated artifacts, defaulting to empty strings. The full artifact list (including custom
+ * transformer outputs) is served alongside; these named strings back the existing `DownloadTokens`
+ * component without changing its shape.
+ */
+export const tokenFormatStrings = (
+  artifacts: TokenArtifactResource[]
+): { css: string; scss: string; styleDictionary: string; types: string } => {
+  const byFormat = (format: string): string => artifacts.find((artifact) => artifact.format === format)?.content ?? '';
+  return {
+    css: byFormat('css'),
+    scss: byFormat('scss'),
+    styleDictionary: byFormat('styleDictionary'),
+    types: byFormat('types'),
+  };
+};