handoff-app 1.2.2-7 → 2.0.0-0

package/src/app/lib/registry-api/entity-routes.ts

@@ -0,0 +1,197 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { isSafePathSegment, isSafeRelativePath, normalizeRelativePath } from '@handoff/registry/path';
+import { joinedQueryValue, singleQueryValue } from '../api/query';
+import type { ManagedEntityKind } from './allowlist';
+import { validateMetadataWrite } from './allowlist';
+import { sendRegistryError } from './errors';
+import { validateFileBody } from './files';
+import { handleRegistryRoute, sendRegistryData } from './handler';
+import { buildMeta } from './meta';
+import { revalidateEntityPages } from './revalidate';
+import {
+  createEntity,
+  deleteEntity,
+  deleteEntityFile,
+  entityExists,
+  getEntity,
+  getEntityFile,
+  listEntities,
+  listEntityFiles,
+  updateEntityMetadata,
+  upsertEntityFile,
+} from './store';
+
+/**
+ * Entity-kind-parameterized route bodies for the registry management API.
+ *
+ * Components and patterns expose the identical CRUD + files surface, so the four `/api/registry/*`
+ * route shapes are implemented once here and bound to a kind by the thin page route files. Each runs
+ * behind {@link handleRegistryRoute}, which applies the runtime-mode, method, bearer-token, and
+ * database guards before the body executes.
+ */
+
+const label = (kind: ManagedEntityKind): string => (kind === 'component' ? 'Component' : 'Pattern');
+
+const rejectionDetails = (rejectedFields: string[]) => (rejectedFields.length ? { rejectedFields } : undefined);
+
+/** `GET` (list) + `POST` (create metadata-only record) for a collection. */
+export const handleEntityCollection = (req: NextApiRequest, res: NextApiResponse, kind: ManagedEntityKind): Promise<void> =>
+  handleRegistryRoute(req, res, ['GET', 'POST'], async ({ db, method }) => {
+    if (method === 'GET') {
+      sendRegistryData(res, 200, await listEntities(db, kind));
+      return;
+    }
+    const validation = validateMetadataWrite(req.body, kind, { allowId: true });
+    if (!validation.ok) {
+      sendRegistryError(res, 'bad_request', validation.message, rejectionDetails(validation.rejectedFields));
+      return;
+    }
+    const result = await createEntity(db, kind, validation.value);
+    if (!result) {
+      sendRegistryError(res, 'bad_request', `A ${kind} with id "${validation.value.id}" already exists.`);
+      return;
+    }
+    // A new entity appears in the system index; regenerate it on demand.
+    await revalidateEntityPages(res, kind, validation.value.id);
+    sendRegistryData(res, 201, result.data, buildMeta(result.build));
+  });
+
+/** `GET` (detail) + `PUT` (allowlisted metadata update) + `DELETE` for a single entity. */
+export const handleEntityItem = (req: NextApiRequest, res: NextApiResponse, kind: ManagedEntityKind): Promise<void> =>
+  handleRegistryRoute(req, res, ['GET', 'PUT', 'DELETE'], async ({ db, method }) => {
+    const id = singleQueryValue(req.query.id);
+    if (!id) {
+      sendRegistryError(res, 'not_found', `Missing ${kind} id.`);
+      return;
+    }
+    if (!isSafePathSegment(id)) {
+      sendRegistryError(res, 'bad_request', `${label(kind)} id must be a registry-safe relative path.`, {
+        rejectedFields: ['id'],
+      });
+      return;
+    }
+
+    if (method === 'GET') {
+      const result = await getEntity(db, kind, id);
+      if (!result) {
+        sendRegistryError(res, 'not_found', `${label(kind)} "${id}" was not found.`);
+        return;
+      }
+      sendRegistryData(res, 200, result.data, buildMeta(result.build));
+      return;
+    }
+
+    if (method === 'PUT') {
+      const validation = validateMetadataWrite(req.body, kind);
+      if (!validation.ok) {
+        sendRegistryError(res, 'bad_request', validation.message, rejectionDetails(validation.rejectedFields));
+        return;
+      }
+      const result = await updateEntityMetadata(db, kind, id, validation.value);
+      if (!result) {
+        sendRegistryError(res, 'not_found', `${label(kind)} "${id}" was not found.`);
+        return;
+      }
+      // A metadata edit (e.g. title/description) changes the server-rendered detail page; regenerate.
+      await revalidateEntityPages(res, kind, id);
+      sendRegistryData(res, 200, result.data, buildMeta(result.build));
+      return;
+    }
+
+    const deleted = await deleteEntity(db, kind, id);
+    if (!deleted) {
+      sendRegistryError(res, 'not_found', `${label(kind)} "${id}" was not found.`);
+      return;
+    }
+    // The entity is gone; regenerate so the detail page 404s and the index drops it.
+    await revalidateEntityPages(res, kind, id);
+    sendRegistryData(res, 200, { id, deleted: true });
+  });
+
+/** `GET` (list files) + `POST` (create/replace a file record) for an entity's files. */
+export const handleEntityFilesCollection = (req: NextApiRequest, res: NextApiResponse, kind: ManagedEntityKind): Promise<void> =>
+  handleRegistryRoute(req, res, ['GET', 'POST'], async ({ db, method }) => {
+    const id = singleQueryValue(req.query.id);
+    if (!id) {
+      sendRegistryError(res, 'not_found', `Missing ${kind} id.`);
+      return;
+    }
+    if (!isSafePathSegment(id)) {
+      sendRegistryError(res, 'bad_request', `${label(kind)} id must be a registry-safe relative path.`, {
+        rejectedFields: ['id'],
+      });
+      return;
+    }
+    if (!(await entityExists(db, kind, id))) {
+      sendRegistryError(res, 'not_found', `${label(kind)} "${id}" was not found.`);
+      return;
+    }
+
+    if (method === 'GET') {
+      sendRegistryData(res, 200, await listEntityFiles(db, kind, id));
+      return;
+    }
+
+    const validation = validateFileBody(req.body);
+    if (!validation.ok) {
+      sendRegistryError(res, 'bad_request', validation.message, rejectionDetails(validation.rejectedFields));
+      return;
+    }
+    sendRegistryData(res, 201, await upsertEntityFile(db, kind, id, validation.value));
+  });
+
+/** `GET` + `PUT` + `DELETE` for a single text-file record addressed by its relative path. */
+export const handleEntityFileItem = (req: NextApiRequest, res: NextApiResponse, kind: ManagedEntityKind): Promise<void> =>
+  handleRegistryRoute(req, res, ['GET', 'PUT', 'DELETE'], async ({ db, method }) => {
+    const id = singleQueryValue(req.query.id);
+    const rawPath = joinedQueryValue(req.query.filePath);
+    if (!id || !rawPath) {
+      sendRegistryError(res, 'not_found', `Missing ${kind} id or file path.`);
+      return;
+    }
+    if (!isSafePathSegment(id)) {
+      sendRegistryError(res, 'bad_request', `${label(kind)} id must be a registry-safe relative path.`, {
+        rejectedFields: ['id'],
+      });
+      return;
+    }
+    if (!isSafeRelativePath(rawPath)) {
+      sendRegistryError(res, 'bad_request', 'File path must be a registry-safe relative path.', {
+        rejectedFields: ['path'],
+      });
+      return;
+    }
+    const filePath = normalizeRelativePath(rawPath);
+
+    if (!(await entityExists(db, kind, id))) {
+      sendRegistryError(res, 'not_found', `${label(kind)} "${id}" was not found.`);
+      return;
+    }
+
+    if (method === 'GET') {
+      const file = await getEntityFile(db, kind, id, filePath);
+      if (!file) {
+        sendRegistryError(res, 'not_found', `File "${filePath}" was not found for ${kind} "${id}".`);
+        return;
+      }
+      sendRegistryData(res, 200, file);
+      return;
+    }
+
+    if (method === 'PUT') {
+      const validation = validateFileBody(req.body, { pathFromRoute: filePath });
+      if (!validation.ok) {
+        sendRegistryError(res, 'bad_request', validation.message, rejectionDetails(validation.rejectedFields));
+        return;
+      }
+      sendRegistryData(res, 200, await upsertEntityFile(db, kind, id, validation.value));
+      return;
+    }
+
+    const deleted = await deleteEntityFile(db, kind, id, filePath);
+    if (!deleted) {
+      sendRegistryError(res, 'not_found', `File "${filePath}" was not found for ${kind} "${id}".`);
+      return;
+    }
+    sendRegistryData(res, 200, { path: filePath, deleted: true });
+  });

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

@@ -0,0 +1,51 @@
+import type { NextApiResponse } from 'next';
+import { redactSecrets } from '../api/redact';
+import { buildMeta, type RegistryMeta } from './meta';
+
+/**
+ * Registry management API error contract.
+ *
+ * Every response — including errors — uses the `{ error, meta }` envelope (the docs read API, by
+ * contrast, uses a bare `{ error }`). `details.rejectedFields` carries field-level rejection detail
+ * for allowlist/file-kind failures.
+ */
+export type RegistryErrorCode =
+  | 'bad_request'
+  | 'unauthorized'
+  | 'not_found'
+  | 'method_not_allowed'
+  | 'runtime_mode_conflict'
+  | 'token_not_configured'
+  | 'database_unavailable'
+  | 'unexpected_error';
+
+const STATUS_BY_CODE: Record<RegistryErrorCode, number> = {
+  bad_request: 400,
+  unauthorized: 401,
+  not_found: 404,
+  method_not_allowed: 405,
+  runtime_mode_conflict: 409,
+  token_not_configured: 503,
+  database_unavailable: 503,
+  unexpected_error: 500,
+};
+
+/** Optional structured error details. `rejectedFields` names the fields that failed validation. */
+export interface RegistryErrorDetails {
+  rejectedFields?: string[];
+  [key: string]: unknown;
+}
+
+/** Write a registry API error response with the status mapped from its code, plus the `meta` envelope. */
+export const sendRegistryError = (
+  res: NextApiResponse,
+  code: RegistryErrorCode,
+  message: string,
+  details?: RegistryErrorDetails,
+  meta: RegistryMeta = buildMeta()
+): void => {
+  res.status(STATUS_BY_CODE[code]).json({
+    error: { code, message, ...(details ? { details: redactSecrets(details) } : {}) },
+    meta,
+  });
+};

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

@@ -0,0 +1,135 @@
+import type { RegistryTextFileKind } from '@handoff/store/types';
+import { isSafeRelativePath, normalizeRelativePath } from '@handoff/registry/path';
+import { isPlainObject } from './validation';
+
+/**
+ * Registry text-file record validation.
+ *
+ * Text file records are checkout/inspection/management only and **exclude declaration files** —
+ * declarations are a workspace-only concern (synthesized on checkout). File bodies must carry a
+ * supported kind and a registry-safe relative path; `declaration`, unknown kinds, and unsafe paths
+ * are rejected with `400 bad_request`.
+ */
+
+/** Supported registry file kinds (the store kinds minus the workspace-only `declaration`). */
+const ALLOWED_FILE_KINDS: readonly RegistryTextFileKind[] = [
+  'component',
+  'template',
+  'style',
+  'script',
+  'story',
+  'docs',
+  'markdown',
+  'schema',
+  'other',
+];
+
+const CONTENT_TYPE_BY_EXT: Record<string, string> = {
+  ts: 'text/typescript; charset=utf-8',
+  tsx: 'text/typescript; charset=utf-8',
+  js: 'application/javascript; charset=utf-8',
+  jsx: 'application/javascript; charset=utf-8',
+  cjs: 'application/javascript; charset=utf-8',
+  mjs: 'application/javascript; charset=utf-8',
+  json: 'application/json; charset=utf-8',
+  css: 'text/css; charset=utf-8',
+  scss: 'text/x-scss; charset=utf-8',
+  sass: 'text/x-sass; charset=utf-8',
+  hbs: 'text/x-handlebars-template; charset=utf-8',
+  md: 'text/markdown; charset=utf-8',
+  html: 'text/html; charset=utf-8',
+};
+
+const contentTypeForPath = (filePath: string): string => {
+  const lastDot = filePath.lastIndexOf('.');
+  const ext = lastDot >= 0 ? filePath.slice(lastDot + 1).toLowerCase() : '';
+  return CONTENT_TYPE_BY_EXT[ext] ?? 'text/plain; charset=utf-8';
+};
+
+/** A validated, persistable registry file record. */
+export interface ValidatedFile {
+  path: string;
+  kind: RegistryTextFileKind;
+  content: string;
+  contentType: string;
+}
+
+/**
+ * Result of {@link validateFileBody}. Flat (not a discriminated union) because the app compiles with
+ * `strictNullChecks` off — `ok` decides, with `value` set on success and `rejectedFields`/`message`
+ * on failure.
+ */
+export interface FileValidation {
+  ok: boolean;
+  value?: ValidatedFile;
+  rejectedFields?: string[];
+  message?: string;
+}
+
+export interface ValidateFileOptions {
+  /**
+   * Path supplied by the route (e.g. the `[...filePath]` segment for PUT). When set, the body path,
+   * if present, must match it; the route path is authoritative.
+   */
+  pathFromRoute?: string;
+}
+
+/**
+ * Validate a registry file record body (`{ path, kind, content, contentType }`). Rejects the
+ * `declaration` kind, unknown kinds, unsafe paths, and missing content with field-level detail.
+ */
+export const validateFileBody = (body: unknown, options: ValidateFileOptions = {}): FileValidation => {
+  if (!isPlainObject(body)) {
+    return { ok: false, rejectedFields: [], message: 'Request body must be a JSON object.' };
+  }
+
+  const rejectedFields: string[] = [];
+
+  const rawPath = options.pathFromRoute ?? (typeof body.path === 'string' ? body.path : undefined);
+  if (!rawPath || !isSafeRelativePath(rawPath)) {
+    rejectedFields.push('path');
+  } else if (
+    options.pathFromRoute &&
+    typeof body.path === 'string' &&
+    normalizeRelativePath(body.path) !== normalizeRelativePath(options.pathFromRoute)
+  ) {
+    // A body path that disagrees with the route path is ambiguous; reject rather than guess.
+    rejectedFields.push('path');
+  }
+
+  const kind = body.kind;
+  if (typeof kind !== 'string' || !ALLOWED_FILE_KINDS.includes(kind as RegistryTextFileKind)) {
+    // `declaration` (workspace-only) and any unknown kind land here.
+    rejectedFields.push('kind');
+  }
+
+  if (typeof body.content !== 'string') {
+    rejectedFields.push('content');
+  }
+
+  if (body.contentType !== undefined && typeof body.contentType !== 'string') {
+    rejectedFields.push('contentType');
+  }
+
+  if (rejectedFields.length > 0) {
+    const declarationAttempted = kind === 'declaration';
+    return {
+      ok: false,
+      rejectedFields,
+      message: declarationAttempted
+        ? 'Declaration files are workspace-only and are never stored as registry source records.'
+        : 'Invalid file record: a supported kind, a registry-safe relative path, and string content are required.',
+    };
+  }
+
+  const path = normalizeRelativePath(rawPath as string);
+  return {
+    ok: true,
+    value: {
+      path,
+      kind: kind as RegistryTextFileKind,
+      content: body.content as string,
+      contentType: (body.contentType as string) || contentTypeForPath(path),
+    },
+  };
+};

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

@@ -0,0 +1,96 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import type { RegistryDatabase } from '@handoff/registry/db/client';
+import { getServerRuntimeConfig } from '../docs-api/runtime-config';
+import { getRegistryConnection, RegistryConnectionError } from '../registry-connection';
+import { authorizeMutation } from './auth';
+import { sendRegistryError } from './errors';
+import { buildMeta, type RegistryMeta } from './meta';
+import { redactSecrets } from '../api/redact';
+
+/**
+ * Shared orchestration for every `/api/registry/*` route.
+ *
+ * Enforces, in order: the registry-runtime guard (management APIs exist only when
+ * `runtime.mode: registry`, else `409 runtime_mode_conflict`); the per-route method allowlist
+ * (`405 method_not_allowed`); the bearer-token guard for mutations (`503 token_not_configured` /
+ * `401 unauthorized`); and database resolution (`503 database_unavailable`). The route body then
+ * runs against a live connection, with any thrown failure mapped to `unexpected_error`.
+ */
+
+/** Methods that mutate state and therefore require the bearer token. */
+const MUTATION_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+/** Context handed to a registry route body once all guards pass. */
+export interface RegistryRouteContext {
+  req: NextApiRequest;
+  res: NextApiResponse;
+  db: RegistryDatabase;
+  method: string;
+}
+
+/**
+ * Guard that the active runtime is `registry`. Writes `409 runtime_mode_conflict` and returns
+ * `false` in workspace mode. Used by routes (like health) that do not need a database connection.
+ */
+export const ensureRegistryMode = (res: NextApiResponse): boolean => {
+  if (getServerRuntimeConfig().mode === 'registry') {
+    return true;
+  }
+  sendRegistryError(res, 'runtime_mode_conflict', 'The registry management API is available only when runtime.mode is "registry".');
+  return false;
+};
+
+/** Write a successful registry API response with the `{ data, meta }` envelope (data redacted). */
+export const sendRegistryData = (res: NextApiResponse, status: number, data: unknown, meta: RegistryMeta = buildMeta()): void => {
+  res.status(status).json({ data: redactSecrets(data), meta });
+};
+
+/**
+ * Run a registry route body behind the full guard stack. `methods` is the route's allowlist (e.g.
+ * `['GET', 'POST']`); the body branches on `ctx.method`.
+ */
+export const handleRegistryRoute = async (
+  req: NextApiRequest,
+  res: NextApiResponse,
+  methods: string[],
+  body: (ctx: RegistryRouteContext) => Promise<void>
+): Promise<void> => {
+  if (!ensureRegistryMode(res)) {
+    return;
+  }
+
+  const method = (req.method ?? 'GET').toUpperCase();
+  if (!methods.includes(method)) {
+    res.setHeader('Allow', methods.join(', '));
+    sendRegistryError(res, 'method_not_allowed', `Method ${method} not allowed for this registry endpoint.`);
+    return;
+  }
+
+  if (MUTATION_METHODS.has(method)) {
+    const auth = authorizeMutation(req);
+    if (!auth.ok) {
+      sendRegistryError(res, auth.code, auth.message);
+      return;
+    }
+  }
+
+  let db: RegistryDatabase;
+  try {
+    ({ db } = await getRegistryConnection());
+  } catch (error) {
+    if (error instanceof RegistryConnectionError) {
+      sendRegistryError(res, 'database_unavailable', error.message);
+      return;
+    }
+    console.error('Registry connection resolution failed.', error);
+    sendRegistryError(res, 'unexpected_error', 'Unexpected registry API error.');
+    return;
+  }
+
+  try {
+    await body({ req, res, db, method });
+  } catch (error) {
+    console.error('Registry API request failed.', error);
+    sendRegistryError(res, 'unexpected_error', 'Unexpected registry API error.');
+  }
+};

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

@@ -0,0 +1,4 @@
+/** Route facing registry API helpers. Internal validation and persistence stay in their own modules. */
+
+export { ensureRegistryMode, handleRegistryRoute } from './handler';
+export { sendRegistryError } from './errors';

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

@@ -0,0 +1,87 @@
+import { and, eq, sql } from 'drizzle-orm';
+import type { RuntimeMode } from '@handoff/types/config';
+import type { RegistryDatabase } from '@handoff/registry/db/client';
+import { buildMetadata, docsArtifacts } from '@handoff/registry/db/schema';
+import { getServerRuntimeConfig } from '../docs-api/runtime-config';
+
+/**
+ * Response-envelope `meta` for the registry management API.
+ *
+ * Every registry API response — success or error — carries `{ data, meta }`, where `meta` describes
+ * the serving runtime and (for single-entity reads) the entity's build/artifact state. The build
+ * block lets a reviewer see whether an entity has published artifacts without fetching them.
+ */
+
+/** Build/artifact state summary for a single entity. */
+export interface RegistryBuildMeta {
+  /** `not_built` when no build-metadata row exists yet; otherwise the stored status. */
+  status: 'current' | 'stale' | 'missing' | 'error' | 'not_built';
+  entityKind: 'component' | 'pattern' | 'page';
+  entityId: string;
+  builtAt: string | null;
+  artifactHash: string | null;
+  /** Number of entity-owned docs read-model artifacts stored. */
+  ingestedArtifacts: number;
+  /** Number of shared/global artifacts stored (path-keyed, owned by `asset`). */
+  sharedArtifacts: number;
+}
+
+/** Standard registry API response meta. */
+export interface RegistryMeta {
+  runtime: RuntimeMode;
+  source: 'database';
+  generatedAt: string;
+  build?: RegistryBuildMeta;
+}
+
+/** Build the base response meta, optionally carrying a single entity's build state. */
+export const buildMeta = (build?: RegistryBuildMeta): RegistryMeta => ({
+  runtime: getServerRuntimeConfig().mode,
+  source: 'database',
+  generatedAt: new Date().toISOString(),
+  ...(build ? { build } : {}),
+});
+
+/** Count rows matching a where-clause (used for artifact tallies). */
+const countWhere = async (db: RegistryDatabase, where: ReturnType<typeof eq>): Promise<number> => {
+  const rows = await db
+    .select({ value: sql<number>`count(*)::int` })
+    .from(docsArtifacts)
+    .where(where);
+  return rows[0]?.value ?? 0;
+};
+
+/**
+ * Resolve the build/artifact state for an entity from `build_metadata` + `docs_artifacts`. Reads
+ * only — never triggers a build. A metadata-only entity (no build row) reports `not_built`.
+ */
+export const resolveBuildMeta = async (
+  db: RegistryDatabase,
+  entityKind: 'component' | 'pattern' | 'page',
+  entityId: string
+): Promise<RegistryBuildMeta> => {
+  const [rows, ingestedArtifacts, sharedArtifacts] = await Promise.all([
+    db
+      .select({
+        status: buildMetadata.status,
+        builtAt: buildMetadata.builtAt,
+        artifactHash: buildMetadata.artifactHash,
+      })
+      .from(buildMetadata)
+      .where(and(eq(buildMetadata.entityKind, entityKind), eq(buildMetadata.entityId, entityId)))
+      .limit(1),
+    countWhere(db, and(eq(docsArtifacts.entityKind, entityKind), eq(docsArtifacts.entityId, entityId))),
+    countWhere(db, eq(docsArtifacts.entityKind, 'asset')),
+  ]);
+  const row = rows[0];
+
+  return {
+    status: row?.status ?? 'not_built',
+    entityKind,
+    entityId,
+    builtAt: row?.builtAt ? new Date(row.builtAt).toISOString() : null,
+    artifactHash: row?.artifactHash ?? null,
+    ingestedArtifacts,
+    sharedArtifacts,
+  };
+};

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

@@ -0,0 +1,36 @@
+import type { NextApiResponse } from 'next';
+
+/** Entity kinds whose docs pages are statically generated and can be regenerated on demand. */
+type RevalidatableEntityKind = 'component' | 'pattern' | 'page';
+
+/**
+ * Best-effort on-demand revalidation of the statically-generated docs pages affected by a registry
+ * mutation.
+ *
+ * Every registry mutation — publish ingest, allowlisted metadata edit, create, delete — flows
+ * through this running server, so the pages those mutations affect are regenerated the instant
+ * content changes (Next on-demand ISR) instead of waiting for a rebuild or restart: the entity's
+ * detail page (correct `<head>` title, metadata, prev/next) and the system index. The component /
+ * pattern nav submenus are resolved at request time on the client, so they are intentionally not
+ * revalidated here.
+ *
+ * Revalidation is best-effort: the mutation has already persisted, so a revalidation failure (e.g. a
+ * page that has not been generated yet, or a runtime without ISR) must never fail the request — the
+ * page refreshes on its next natural regeneration.
+ */
+export const revalidateEntityPages = async (
+  res: NextApiResponse,
+  kind: RevalidatableEntityKind,
+  id: string
+): Promise<void> => {
+  // Pages are served at their own route (`/<id>`); components/patterns live under `/system`.
+  const paths = kind === 'page' ? [`/${id}/`] : [`/system/${kind}/${id}/`, '/system/'];
+  for (const path of paths) {
+    try {
+      await res.revalidate(path);
+    } catch (error) {
+      // Best-effort: see note above. The entity is persisted regardless of revalidation outcome.
+      console.warn(`Failed to revalidate registry docs path "${path}" after ${kind} "${id}" changed.`, error);
+    }
+  }
+};