handoff-app 2.0.0-8 → 2.0.0

package/src/app/lib/mcp/tokens.ts

@@ -0,0 +1,334 @@
+import type { TokenArtifactResource } from '@handoff/store';
+import type { DocsBackend, TokenSetDetail } from '../docs-api/backend';
+import { fail, ok, read } from './result';
+import { defineTool, type McpTool } from './tool';
+
+/** The token tool, and the reshaping that turns stored token sets into variables an agent can emit. */
+
+type TokenFormat = 'css' | 'scss' | 'styleDictionary' | 'types';
+
+export const tokenTools: McpTool[] = [
+  defineTool<{ set?: string; kind?: 'foundation' | 'component'; format?: TokenFormat }>(
+    {
+      name: 'handoff_get_tokens',
+      title: 'Get design tokens',
+      description:
+        'Design tokens. With no arguments: the list of token sets, plus all foundation tokens (colors, ' +
+        'typography, effects). With `set`: one set. With `set` and `format`: the generated file for ' +
+        'that set. A foundation token has `css` and `value`, or `cssPrefix` and `properties` (each ' +
+        'variable is `{cssPrefix}-{property}`). A component set has `variants`: the axis values of each ' +
+        'variant and the variables it sets. Use the CSS variable, not the literal value, unless no ' +
+        'stylesheet is available.',
+      annotations: { readOnlyHint: true, openWorldHint: false },
+      inputSchema: {
+        type: 'object',
+        properties: {
+          set: { type: 'string', description: 'Token set id from the list, for example "foundation/colors".' },
+          kind: {
+            type: 'string',
+            enum: ['foundation', 'component'],
+            description: 'Without `set`: list only sets of this kind. `component` leaves out the foundation tokens.',
+          },
+          format: {
+            type: 'string',
+            enum: ['css', 'scss', 'styleDictionary', 'types'] satisfies TokenFormat[],
+            description: 'With `set`: return the generated file in this format.',
+          },
+        },
+      },
+    },
+    async ({ set, kind, format }) =>
+      read(set ? `token set "${set}"` : 'the token catalog', async (backend) => {
+        if (!set) {
+          if (format) {
+            return fail('`format` needs a `set`. Call handoff_get_tokens with no arguments to list the available sets.');
+          }
+          return ok(await listTokens(backend, kind));
+        }
+
+        const detail = await backend.getTokenSetDetail(set);
+        if (!detail) {
+          return fail(`Token set "${set}" was not found. Call handoff_get_tokens with no arguments to list the available sets.`);
+        }
+        if (!format) {
+          return ok({ id: detail.id, kind: detail.kind, formats: availableFormats(detail.artifacts), ...tokenPayload(detail) });
+        }
+
+        const artifact = detail.artifacts.find((candidate) => candidate.format === format);
+        if (!artifact) {
+          const formats = availableFormats(detail.artifacts);
+          return fail(
+            `Token set "${set}" has no "${format}" output. ${formats.length ? `Available formats: ${formats.join(', ')}.` : 'It has no generated output.'}`
+          );
+        }
+        return ok({ id: detail.id, kind: detail.kind, format, path: artifact.path, content: artifact.content });
+      })
+  ),
+];
+
+/**
+ * A token set's payload, under a key naming which of the four forms it is, so the agent never has to
+ * guess: `tokens` for a foundation, `variants` for a component, or one of the two fallbacks.
+ *
+ * When neither reshape is possible we degrade rather than fail. The generated `stylesheet` still
+ * lets an agent write correct code, and the raw `record` is the last resort, which is what a
+ * workspace with unbuilt tokens gets.
+ */
+const tokenPayload = (detail: TokenSetDetail): Record<string, unknown> => {
+  const reshaped =
+    detail.kind === 'foundation'
+      ? synthesizeFoundationTokens(detail.record, detail.artifacts)
+      : synthesizeComponentTokens(detail.artifacts);
+  if (reshaped) {
+    return detail.kind === 'foundation' ? { tokens: reshaped } : { variants: reshaped };
+  }
+  const stylesheet = detail.artifacts.find((a) => a.format === 'css') ?? detail.artifacts.find((a) => a.format === 'scss');
+  if (stylesheet) {
+    return { format: stylesheet.format, stylesheet: stylesheet.content };
+  }
+  return { record: stripFigmaIds(detail.record) };
+};
+
+/**
+ * The token catalog. Foundation tokens are inlined because they are what an agent needs before it
+ * writes anything. Component sets are listed by id and fetched one at a time, since inlining them
+ * all would be most of the design system in one response.
+ */
+const listTokens = async (backend: DocsBackend, kind?: 'foundation' | 'component') => {
+  const sets = (await backend.listTokenSets()).filter((candidate) => !kind || candidate.kind === kind);
+  if (kind === 'component') {
+    return { sets };
+  }
+
+  const foundations: Record<string, unknown> = {};
+  for (const candidate of sets.filter((entry) => entry.kind === 'foundation')) {
+    const detail = await backend.getTokenSetDetail(candidate.id);
+    if (detail) {
+      foundations[candidate.id] = tokenPayload(detail);
+    }
+  }
+  return { sets, foundations };
+};
+
+/**
+ * Drop the Figma node id from every token record.
+ *
+ * Colors, typography, effects and component instances each carry an `id` that is a Figma node
+ * reference, which an agent cannot use. Everything else (`sass`, `reference`, `machineName`,
+ * `values`, `parts`, `variantProperties`) survives, so nothing that affects generated code is lost.
+ */
+export const stripFigmaIds = (record: unknown): unknown => {
+  if (Array.isArray(record)) return record.map(stripFigmaIds);
+  if (record && typeof record === 'object') {
+    const { id: _id, ...rest } = record as Record<string, unknown>;
+    return Object.fromEntries(Object.entries(rest).map(([key, value]) => [key, stripFigmaIds(value)]));
+  }
+  return record;
+};
+
+/** The generated formats available for a token set, deduped and in artifact order. */
+export const availableFormats = (artifacts: TokenArtifactResource[]): string[] =>
+  Array.from(new Set(artifacts.map((artifact) => artifact.format)));
+
+/**
+ * Foundation tokens, reshaped into what an agent needs to write code.
+ *
+ * Neither the stored record nor the generated stylesheet is usable on its own. The record says a type
+ * style is called `Heading 1` but nothing in it yields the variable to emit: its `reference` is
+ * `typography--heading-1` while the real variables are `--typography-heading-1-font-size` and
+ * friends, and it carries raw Figma fields (`textAutoResize`, three competing `lineHeight*`
+ * encodings) that never become CSS. The stylesheet has the right names and resolved values but has
+ * flattened away the human name and the grouping.
+ *
+ * So the two are joined. Names and values come from the generated CSS, token identity from the
+ * generated `types` list, and `name`/`group` from the record. Nothing is reconstructed from a naming
+ * rule of our own, since the rule differs per set and typography would come out wrong.
+ *
+ * Foundations only. Component sets are multi-axis (part x state x theme x property) and their
+ * `types` artifact lists axes rather than token names, so there is no honest join to make.
+ */
+
+/** One foundation token: a single value, or a bundle of properties under a shared variable prefix. */
+export interface FoundationToken {
+  /** Human-facing name from the record, when it could be matched unambiguously. */
+  name?: string;
+  /** Record group (e.g. `primary`, `shadow`), when set. */
+  group?: string;
+  /** The CSS custom property, for a single-value token. */
+  css?: string;
+  /** Resolved value, for a single-value token. */
+  value?: string;
+  /** Shared variable prefix, for a bundled token: each property is `{cssPrefix}-{property}`. */
+  cssPrefix?: string;
+  /** Resolved values keyed by CSS property, for a bundled token. */
+  properties?: Record<string, string>;
+}
+
+/** One `--name: value;` line of a generated stylesheet. */
+const CSS_DECLARATION = /^\s*--([\w-]+)\s*:\s*(.+?);\s*$/;
+
+/** Parse `--name: value;` declarations out of a generated stylesheet. */
+export const cssVariables = (content: string): Record<string, string> => {
+  const variables: Record<string, string> = {};
+  for (const line of content.split('\n')) {
+    const match = CSS_DECLARATION.exec(line);
+    if (match) {
+      variables[match[1]] = match[2].trim();
+    }
+  }
+  return variables;
+};
+
+/**
+ * Token names from a generated `types` artifact, read out of its quoted string list (`$color-names`,
+ * `$type-sizes`, `$effects`). Without it there is no telling whether `--color-primary-blue-darker`
+ * is a `darker` property of `primary-blue` or a token in its own right. It is the latter, and only
+ * this list says so.
+ */
+export const tokenNamesFromTypes = (content: string): string[] =>
+  // `[^"]*` not `[^"]+`: the list can carry an empty entry (`$color-groups` ends with `""`), and a
+  // pattern that cannot match it pairs that entry's closing quote with the next entry's opening one,
+  // knocking every later name out of alignment. Empty names are dropped after matching, not during.
+  Array.from(new Set(Array.from(content.matchAll(/"([^"]*)"/g), (match) => match[1]))).filter(Boolean);
+
+/**
+ * Assign a CSS variable to the longest token name that matches, returning the leftover as a property.
+ * Longest first is what keeps `primary-blue-darker` from being read as `primary-blue` + `darker`.
+ */
+const claimVariable = (variable: string, namesByLength: string[]): { token: string; property?: string } | null => {
+  for (const token of namesByLength) {
+    if (variable === token || variable.endsWith(`-${token}`)) {
+      return { token };
+    }
+    const at = variable.indexOf(`-${token}-`);
+    if (at >= 0) {
+      return { token, property: variable.slice(at + token.length + 2) };
+    }
+    if (variable.startsWith(`${token}-`)) {
+      return { token, property: variable.slice(token.length + 1) };
+    }
+  }
+  return null;
+};
+
+/** A foundation record, as far as the join cares. */
+type FoundationRecord = { name?: string; group?: string; reference?: string; machineName?: string; machine_name?: string };
+
+/**
+ * The record describing one token. Matched on `reference`, which ends with the token name across all
+ * three foundation kinds. More than one candidate means it is ambiguous, so nothing is attached: a
+ * token without its label beats a token with the wrong one.
+ */
+const recordFor = (token: string, records: FoundationRecord[]): FoundationRecord | null => {
+  const matches = records.filter(
+    (record) =>
+      record?.reference === token ||
+      record?.reference?.endsWith(`-${token}`) ||
+      record?.machineName === token ||
+      record?.machine_name === token
+  );
+  return matches.length === 1 ? matches[0] : null;
+};
+
+/**
+ * Reshape a foundation set. Returns `null` when the inputs are missing (no CSS or `types` artifact,
+ * or nothing parsed out of them) so the caller can fall back to the stylesheet or the record.
+ */
+export const synthesizeFoundationTokens = (record: unknown, artifacts: TokenArtifactResource[]): Record<string, FoundationToken> | null => {
+  const css = artifacts.find((artifact) => artifact.format === 'css');
+  const types = artifacts.find((artifact) => artifact.format === 'types');
+  if (!css || !types) {
+    return null;
+  }
+
+  const variables = cssVariables(css.content);
+  const namesByLength = tokenNamesFromTypes(types.content).sort((a, b) => b.length - a.length);
+  if (Object.keys(variables).length === 0 || namesByLength.length === 0) {
+    return null;
+  }
+
+  const records: FoundationRecord[] = Array.isArray(record) ? record : [];
+  const tokens: Record<string, FoundationToken> = {};
+
+  for (const [variable, value] of Object.entries(variables)) {
+    const claim = claimVariable(variable, namesByLength);
+    if (!claim) {
+      continue;
+    }
+    const entry = (tokens[claim.token] ??= {});
+    if (!entry.name) {
+      const matched = recordFor(claim.token, records);
+      if (matched?.name) entry.name = matched.name;
+      if (matched?.group) entry.group = matched.group;
+    }
+    if (claim.property) {
+      entry.cssPrefix = `--${variable.slice(0, variable.length - claim.property.length - 1)}`;
+      (entry.properties ??= {})[claim.property] = value;
+    } else {
+      entry.css = `--${variable}`;
+      entry.value = value;
+    }
+  }
+
+  return Object.keys(tokens).length > 0 ? tokens : null;
+};
+
+/** One variant of a component: the axis values it applies to, and the variables it sets. */
+export interface ComponentTokenVariant {
+  /** Axis values, e.g. `{ state: 'disabled', theme: 'dark' }`. Empty for a component with no variants. */
+  variant: Record<string, string>;
+  /** Full CSS custom property names to resolved values. */
+  variables: Record<string, string>;
+}
+
+/**
+ * Component tokens, grouped by the variant they belong to.
+ *
+ * A component set is keyed by part x variant x property and the variable name runs them together
+ * (`--select-additional-disabled-dark-border-color`) with no boundary that can be split on safely.
+ * The generated stylesheet already labels each group, though: `getComponentCommentBlock` emits
+ * `/* Select, state: disabled, theme: dark *\/` ahead of every block, built from the instance's
+ * `variantProperties`. So the grouping is read off the generator's own output and variables are kept
+ * whole rather than split by a guessed rule.
+ *
+ * No axes are advertised and nothing is resolved per brand or scheme. The variants already exist in
+ * the build output; this only groups them.
+ */
+export const synthesizeComponentTokens = (artifacts: TokenArtifactResource[]): ComponentTokenVariant[] | null => {
+  const css = artifacts.find((artifact) => artifact.format === 'css');
+  if (!css) {
+    return null;
+  }
+
+  const variants: ComponentTokenVariant[] = [];
+  let current: ComponentTokenVariant | null = null;
+
+  for (const line of css.content.split('\n')) {
+    const comment = /^\s*\/\*\s*(.+?)\s*\*\/\s*$/.exec(line);
+    if (comment) {
+      // The first comma-separated part is the component name; the rest are `key: value` axis pairs.
+      const variant: Record<string, string> = {};
+      for (const part of comment[1].split(',').slice(1)) {
+        const [key, ...rest] = part.split(':');
+        if (rest.length > 0) {
+          variant[key.trim().toLowerCase()] = rest.join(':').trim();
+        }
+      }
+      current = { variant, variables: {} };
+      variants.push(current);
+      continue;
+    }
+    const declaration = CSS_DECLARATION.exec(line);
+    if (declaration) {
+      // A component with no variants emits no header, so open an unlabelled group for it.
+      if (!current) {
+        current = { variant: {}, variables: {} };
+        variants.push(current);
+      }
+      current.variables[`--${declaration[1]}`] = declaration[2].trim();
+    }
+  }
+
+  const populated = variants.filter((entry) => Object.keys(entry.variables).length > 0);
+  return populated.length > 0 ? populated : null;
+};

package/src/app/lib/mcp/tool.ts

@@ -0,0 +1,19 @@
+import type { CallToolResult, Tool } from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * One MCP tool: its listing, with a plain JSON Schema for its input, and its handler.
+ *
+ * Plain JSON Schema keeps Zod out of the app. The Next build type-checks this code against the
+ * consumer's `node_modules`, where a second Zod copy makes the SDK's Zod types incompatible with ours.
+ */
+export interface McpTool {
+  definition: Tool;
+  /** Runs with arguments already validated against `definition.inputSchema`. */
+  run: (args: unknown) => Promise<CallToolResult>;
+}
+
+/** `Args` must match `definition.inputSchema`; the server validates against the schema before `run`. */
+export const defineTool = <Args>(definition: Tool, run: (args: Args) => Promise<CallToolResult>): McpTool => ({
+  definition,
+  run: run as McpTool['run'],
+});

package/src/app/lib/registry-api/asset-transfer.ts

@@ -1,12 +1,14 @@
 import crypto from 'crypto';
+import type { Readable } from 'stream';
 import type { NextApiRequest, NextApiResponse } from 'next';
 import { eq, inArray } from 'drizzle-orm';
 import type { RegistryDatabase } from '@handoff/registry/db/client';
 import { assetBlobs, assetCollections, assets } from '@handoff/registry/db/schema';
 import { isAssetCollection, type AssetCollection } from '@handoff/registry/assets/sets';
 import type { AssetCollectionTransferPackage, AssetManifestEntry } from '@handoff/registry/assets/transfer';
+import type { StorageProvider } from '@handoff/registry/asset-storage/types';
 import { singleQueryValue } from '../api/query';
-import { getActiveAssetStorage, getActiveAssetStorageAdapter, getAssetStorageAdapter } from '../asset-storage';
+import { getActiveAssetStorage, getActiveStorageProvider, getStorageProvider } from '../asset-storage';
 import { sendRegistryError } from './errors';
 import { buildMeta } from './meta';
 import { handleRegistryRoute, sendRegistryData } from './handler';
@@ -36,6 +38,10 @@ import {
  * - `PUT  /api/registry/transfer/assets/blobs/:hash` stores one content-addressed blob (binary body)
  *   through the active storage provider (inline `bytea` by default). Idempotent by hash.
  * - `GET  /api/registry/transfer/assets/blobs/:hash` returns/redirects to one blob's bytes.
+ * - `POST /api/registry/transfer/assets/blobs/:hash/upload` returns a signed URL for a direct upload
+ *   to storage, or `null` when the active provider cannot take one (the client then uses `PUT`).
+ * - `POST /api/registry/transfer/assets/blobs/:hash/complete` records a directly uploaded blob after
+ *   it confirms the stored object exists.
  *
  * Runs behind {@link handleRegistryRoute}: runtime-mode, method, bearer-token (on mutations), and
  * database guards apply before any of this executes.
@@ -312,7 +318,7 @@ export const handleAssetBlobRoute = (req: NextApiRequest, res: NextApiResponse):
         'application/octet-stream';
       const active = getActiveAssetStorage();
 
-      let storageProvider = active.provider;
+      const storageProvider = active.provider;
       let content: Buffer | null = null;
       let storageRef: string | null = null;
       if (active.provider === 'database') {
@@ -326,13 +332,12 @@ export const handleAssetBlobRoute = (req: NextApiRequest, res: NextApiResponse):
         }
         content = bytes;
       } else {
-        const adapter = await getActiveAssetStorageAdapter();
-        if (!adapter) {
-          sendRegistryError(res, 'unexpected_error', `No storage adapter is available for provider "${active.provider}".`);
+        const storage = await getActiveStorageProvider();
+        if (!storage) {
+          sendRegistryError(res, 'unexpected_error', `No asset storage is available for provider "${active.provider}".`);
           return;
         }
-        ({ storageRef } = await adapter.put({ hash, bytes, contentType, size: bytes.length }));
-        storageProvider = active.provider;
+        ({ storageRef } = await storage.put({ hash, bytes, contentType, size: bytes.length }));
       }
 
       await db
@@ -371,12 +376,12 @@ export const handleAssetBlobRoute = (req: NextApiRequest, res: NextApiResponse):
       sendRegistryError(res, 'not_found', `Blob "${hash}" has no resolvable content.`);
       return;
     }
-    const adapter = await getAssetStorageAdapter(blob.storageProvider);
-    if (!adapter) {
-      sendRegistryError(res, 'unexpected_error', `No storage adapter is available for provider "${blob.storageProvider}".`);
+    const storage = await getStorageProvider(blob.storageProvider);
+    if (!storage) {
+      sendRegistryError(res, 'unexpected_error', `No asset storage is available for provider "${blob.storageProvider}".`);
       return;
     }
-    const result = await adapter.get(blob.storageRef);
+    const result = await storage.get(blob.storageRef);
     if (result.kind === 'redirect') {
       res.redirect(302, result.url);
       return;
@@ -388,3 +393,106 @@ export const handleAssetBlobRoute = (req: NextApiRequest, res: NextApiResponse):
     }
     result.stream.pipe(res);
   });
+
+/** The active provider when it supports direct uploads, otherwise `null` (the client then uses `PUT`). */
+const getDirectUploadProvider = async (): Promise<StorageProvider | null> => {
+  if (getActiveAssetStorage().provider === 'database') {
+    return null;
+  }
+  const storage = await getActiveStorageProvider();
+  return storage?.createUpload ? storage : null;
+};
+
+const readDirectUploadRequest = (req: NextApiRequest, res: NextApiResponse): { hash: string; size: number; contentType: string } | null => {
+  const hash = (singleQueryValue(req.query.hash) ?? '').toLowerCase();
+  if (!isSha256Hash(hash)) {
+    sendRegistryError(res, 'bad_request', 'Blob hash must be a SHA-256 hex string.');
+    return null;
+  }
+  const body = isPlainObject(req.body) ? req.body : {};
+  const size = body.size;
+  if (typeof size !== 'number' || !Number.isInteger(size) || size < 0) {
+    sendRegistryError(res, 'bad_request', '`size` must be a non-negative integer.', { rejectedFields: ['size'] });
+    return null;
+  }
+  return { hash, size, contentType: asString(body.contentType) || 'application/octet-stream' };
+};
+
+/**
+ * Throw unless `storageRef` resolves to a stored object. A redirect is checked with a one-byte
+ * ranged `GET`, because a signed read URL usually rejects `HEAD`.
+ */
+const assertStored = async (storage: StorageProvider, storageRef: string, size: number): Promise<void> => {
+  const result = await storage.get(storageRef);
+  if (result.kind === 'bytes') {
+    if (result.bytes.length !== size) {
+      throw new Error(`stored size ${result.bytes.length} does not match ${size}`);
+    }
+    return;
+  }
+  if (result.kind === 'stream') {
+    (result.stream as Readable).destroy?.();
+    return;
+  }
+  const response = await fetch(result.url, { headers: { Range: 'bytes=0-0' } });
+  await response.body?.cancel();
+  if (!response.ok) {
+    throw new Error(`storage answered ${response.status}`);
+  }
+};
+
+/** `POST /api/registry/transfer/assets/blobs/:hash/upload`: a signed URL for a direct upload to storage. */
+export const handleAssetBlobUploadRoute = (req: NextApiRequest, res: NextApiResponse): Promise<void> =>
+  handleRegistryRoute(req, res, ['POST'], async ({ db }) => {
+    const input = readDirectUploadRequest(req, res);
+    if (!input) return;
+
+    const existing = await db.select({ hash: assetBlobs.hash }).from(assetBlobs).where(eq(assetBlobs.hash, input.hash)).limit(1);
+    if (existing.length > 0) {
+      sendRegistryData(res, 200, { upload: null, stored: true }, buildMeta());
+      return;
+    }
+    const storage = await getDirectUploadProvider();
+    const upload = storage?.createUpload ? await storage.createUpload(input) : null;
+    sendRegistryData(res, 200, { upload }, buildMeta());
+  });
+
+/** `POST /api/registry/transfer/assets/blobs/:hash/complete`: record a directly uploaded blob once it is stored. */
+export const handleAssetBlobCompleteRoute = (req: NextApiRequest, res: NextApiResponse): Promise<void> =>
+  handleRegistryRoute(req, res, ['POST'], async ({ db }) => {
+    const input = readDirectUploadRequest(req, res);
+    if (!input) return;
+    const storageRef = asString(isPlainObject(req.body) ? req.body.storageRef : undefined)?.trim();
+    if (!storageRef) {
+      sendRegistryError(res, 'bad_request', '`storageRef` is required.', { rejectedFields: ['storageRef'] });
+      return;
+    }
+
+    const storage = await getDirectUploadProvider();
+    if (!storage) {
+      sendRegistryError(res, 'bad_request', 'The active asset storage provider does not accept direct uploads.');
+      return;
+    }
+    try {
+      await assertStored(storage, storageRef, input.size);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      sendRegistryError(res, 'bad_request', `Blob "${input.hash}" was not found in storage (${reason}).`, {
+        rejectedFields: ['storageRef'],
+      });
+      return;
+    }
+
+    await db
+      .insert(assetBlobs)
+      .values({
+        hash: input.hash,
+        storageProvider: getActiveAssetStorage().provider,
+        content: null,
+        storageRef,
+        contentType: input.contentType,
+        size: input.size,
+      } as any)
+      .onConflictDoNothing({ target: assetBlobs.hash });
+    sendRegistryData(res, 200, { hash: input.hash, stored: true }, buildMeta());
+  });

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

@@ -16,6 +16,7 @@ export type RegistryErrorCode =
   | 'method_not_allowed'
   | 'runtime_mode_conflict'
   | 'database_unavailable'
+  | 'storage_unavailable'
   | 'unexpected_error';
 
 const STATUS_BY_CODE: Record<RegistryErrorCode, number> = {
@@ -26,6 +27,7 @@ const STATUS_BY_CODE: Record<RegistryErrorCode, number> = {
   method_not_allowed: 405,
   runtime_mode_conflict: 409,
   database_unavailable: 503,
+  storage_unavailable: 503,
   unexpected_error: 500,
 };
 

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

@@ -1,6 +1,7 @@
 import type { NextApiRequest, NextApiResponse } from 'next';
 import type { RegistryDatabase } from '@handoff/registry/db/client';
 import type { RegistryPrincipal } from '@handoff/registry/auth';
+import { AssetStorageError } from '../asset-storage';
 import { getServerRuntimeConfig } from '../docs-api/runtime-config';
 import { getRegistryConnection, RegistryConnectionError } from '../registry-connection';
 import { authorizeRegistryRequest, requiredScopeForMethod } from './auth';
@@ -15,7 +16,8 @@ import { buildMeta, type RegistryMeta } from './meta';
  * (`405 method_not_allowed`); database resolution (`503 database_unavailable`); and scoped credential
  * authorization on every request: reads require `registry:read`, mutations require `registry:write`
  * (`400 bad_request` / `401 unauthorized` / `403 forbidden`). The route body then runs against a live
- * connection, with any thrown failure mapped to `unexpected_error`.
+ * connection. A thrown asset storage configuration problem maps to `503 storage_unavailable` with
+ * its message, and any other thrown failure maps to `unexpected_error`.
  *
  * The database is resolved before authorization because that is the only guard needing a connection,
  * so a request that would fail auth against a registry with a down database reports
@@ -94,6 +96,10 @@ export const handleRegistryRoute = async (
     await body({ req, res, db, method, principal });
   } catch (error) {
     console.error('Registry API request failed.', error);
+    if (error instanceof AssetStorageError) {
+      sendRegistryError(res, 'storage_unavailable', error.message);
+      return;
+    }
     sendRegistryError(res, 'unexpected_error', 'Unexpected registry API error.');
   }
 };

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

@@ -10,7 +10,7 @@ import {
   patternFiles,
   patterns,
 } from '@handoff/registry/db/schema';
-import { isSafePathSegment, isSafeRelativePath } from '@handoff/registry/path';
+import { isSafePathSegment, isSafeRelativePath, isWorkspaceRelativePath } from '@handoff/registry/path';
 import type { TransferArtifact, TransferBuild, TransferEntityKind, TransferFile, TransferPackage } from '@handoff/registry/transfer';
 import { and, eq, inArray } from 'drizzle-orm';
 import type { NextApiRequest, NextApiResponse } from 'next';
@@ -90,6 +90,14 @@ const validatePackage = (body: unknown, kind: TransferEntityKind, id: string): P
     return invalid(`Package item id "${itemId}" does not match the publish target "${id}".`, { rejectedFields: ['item.id'] });
   }
 
+  if (body.sourceDir !== undefined && (kind === 'page' || !isWorkspaceRelativePath(body.sourceDir))) {
+    return invalid(
+      kind === 'page' ? 'Page publishes cannot contain `sourceDir`.' : '`sourceDir` must be a normalized workspace-relative path.',
+      { rejectedFields: ['sourceDir'] }
+    );
+  }
+  const sourceDir = body.sourceDir as string | undefined;
+
   const rawFiles = body.files ?? [];
   if (!Array.isArray(rawFiles)) {
     return invalid('`files` must be an array.', { rejectedFields: ['files'] });
@@ -275,7 +283,7 @@ const validatePackage = (body: unknown, kind: TransferEntityKind, id: string): P
     return invalid(buildValidation.message, buildValidation.details);
   }
 
-  return { ok: true, value: { item, files, artifacts, build: buildValidation.value } };
+  return { ok: true, value: { item, sourceDir, files, artifacts, build: buildValidation.value } };
 };
 
 /**
@@ -321,7 +329,8 @@ const upsertEntityRecord = async (
   db: RegistryDatabase,
   kind: TransferEntityKind,
   id: string,
-  item: Record<string, unknown>
+  item: Record<string, unknown>,
+  sourceDir: string | undefined
 ): Promise<void> => {
   const spec = ENTITY[kind];
   const record = { ...item, id };
@@ -346,9 +355,15 @@ const upsertEntityRecord = async (
           // Drizzle omits an `undefined` column from the UPDATE, so only null clears a source format the item no longer has.
           sourceFormat: asString(item.sourceFormat) ?? null,
           categories: asStringArray(item.categories),
+          sourceDir: sourceDir ?? null,
         }
       : kind === 'pattern'
-        ? { ...base, tags: asStringArray(item.tags), components: Array.isArray(item.components) ? item.components : [] }
+        ? {
+            ...base,
+            tags: asStringArray(item.tags),
+            components: Array.isArray(item.components) ? item.components : [],
+            sourceDir: sourceDir ?? null,
+          }
         : { ...base, weight: typeof item.weight === 'number' ? item.weight : null };
 
   if (existing[0]) {
@@ -473,6 +488,12 @@ export const handleEntitySummaryRoute = (req: NextApiRequest, res: NextApiRespon
     sendRegistryData(res, 200, { entities }, buildMeta());
   });
 
+const readSourceDir = async (db: RegistryDatabase, kind: 'component' | 'pattern', id: string): Promise<string | undefined> => {
+  const table = ENTITY[kind].table;
+  const rows = await db.select({ sourceDir: table.sourceDir }).from(table).where(eq(table.id, id)).limit(1);
+  return rows[0]?.sourceDir ?? undefined;
+};
+
 /**
  * Handle `GET /api/registry/transfer/{component|pattern}/:id` — checkout read. Returns the
  * normalized record plus its registry-safe source files so a connected workspace can reconstruct
@@ -504,8 +525,9 @@ export const handleCheckoutRoute = (req: NextApiRequest, res: NextApiResponse, k
     // Declarations are workspace-only and are never persisted as registry file records (their kind
     // is excluded from `RegistryTextFileKind`), so the stored files are already declaration-free.
     const files = await listEntityFiles(db, kind, id);
+    const sourceDir = kind === 'page' ? undefined : await readSourceDir(db, kind, id);
 
-    sendRegistryData(res, 200, { kind, item: entity.data, files }, buildMeta(entity.build));
+    sendRegistryData(res, 200, { kind, item: entity.data, sourceDir, files }, buildMeta(entity.build));
   });
 
 /**
@@ -536,7 +558,7 @@ export const applyEntityPackage = async (
 
   await db.transaction(async (tx) => {
     const transactionalDb = tx as unknown as RegistryDatabase;
-    await upsertEntityRecord(transactionalDb, kind, id, pkg.item);
+    await upsertEntityRecord(transactionalDb, kind, id, pkg.item, pkg.sourceDir);
     await replaceEntityFiles(transactionalDb, kind, id, pkg.files);
     await ingestArtifacts(transactionalDb, kind, id, pkg.artifacts);
     await upsertBuildMetadata(transactionalDb, kind, id, pkg.build);