handoff-app 1.2.2-7 → 2.0.0-1

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

@@ -0,0 +1,348 @@
+import { and, eq } from 'drizzle-orm';
+import type { RegistryDatabase } from '@handoff/registry/db/client';
+import {
+  buildMetadata,
+  componentFiles,
+  components,
+  docsArtifacts,
+  pageFiles,
+  pages,
+  patternFiles,
+  patterns,
+  type RegistryReviewMetadata,
+} from '@handoff/registry/db/schema';
+import type { ComponentListObject, PageListObject, PatternListObject } from '@handoff/transformers/preview/types';
+import { mergeReviewMetadata, type ManagedEntityKind, type ValidatedMetadataWrite } from './allowlist';
+import type { ValidatedFile } from './files';
+import { resolveBuildMeta, type RegistryBuildMeta } from './meta';
+
+/**
+ * Database operations behind the registry management API.
+ *
+ * Reads return the normalized record merged with registry-only review metadata; writes are limited
+ * to the metadata allowlist and the text-file record groups. Crucially, metadata create/update
+ * never touches `docs_artifacts` or `build_metadata` — published artifacts and build state are only
+ * changed by transfer/publish. Entity deletion removes only that entity's owned
+ * artifacts; shared/global artifacts (owned by `asset`) are preserved.
+ */
+
+/** A registry record as served by the management API: the normalized record plus review metadata. */
+export type RegistryEntityData = Record<string, unknown> & { metadata: RegistryReviewMetadata | null };
+
+/** A single entity read result: its served data plus build/artifact state. */
+export interface EntityReadResult {
+  data: RegistryEntityData;
+  build: RegistryBuildMeta;
+}
+
+/** Binds an entity kind to its tables and the conventions used to build/store its records. */
+interface EntitySpec {
+  table: typeof components | typeof patterns | typeof pages;
+  filesTable: typeof componentFiles | typeof patternFiles | typeof pageFiles;
+  fileFkColumn: typeof componentFiles.componentId;
+  fileFkName: 'componentId' | 'patternId' | 'pageId';
+  pathPrefix: string;
+}
+
+const ENTITY: Record<ManagedEntityKind, EntitySpec> = {
+  component: {
+    table: components,
+    filesTable: componentFiles,
+    fileFkColumn: componentFiles.componentId,
+    fileFkName: 'componentId',
+    pathPrefix: 'component',
+  },
+  pattern: {
+    table: patterns,
+    filesTable: patternFiles as unknown as typeof componentFiles,
+    fileFkColumn: patternFiles.patternId as unknown as typeof componentFiles.componentId,
+    fileFkName: 'patternId',
+    pathPrefix: 'pattern',
+  },
+  page: {
+    table: pages,
+    filesTable: pageFiles as unknown as typeof componentFiles,
+    fileFkColumn: pageFiles.pageId as unknown as typeof componentFiles.componentId,
+    fileFkName: 'pageId',
+    pathPrefix: 'page',
+  },
+};
+
+const asString = (value: unknown): string | undefined => (typeof value === 'string' ? value : undefined);
+const asStringArray = (value: unknown): string[] | undefined => (Array.isArray(value) ? (value as string[]) : undefined);
+
+/** Attach review metadata to a normalized record for serving. */
+const withMetadata = (record: unknown, metadata: RegistryReviewMetadata | null | undefined): RegistryEntityData => ({
+  ...(record as Record<string, unknown>),
+  metadata: metadata ?? null,
+});
+
+/** Build a minimal, valid metadata-only component record from allowlisted fields. */
+const buildComponentRecord = (id: string, path: string, fields: Record<string, unknown>): ComponentListObject => ({
+  id,
+  path,
+  title: asString(fields.title) ?? id,
+  description: asString(fields.description) ?? '',
+  image: '',
+  group: asString(fields.group) ?? '',
+  type: '',
+  properties: {},
+  previews: {},
+  ...(asStringArray(fields.tags) ? { tags: asStringArray(fields.tags) } : {}),
+  ...(asStringArray(fields.categories) ? { categories: asStringArray(fields.categories) } : {}),
+});
+
+/** Build a minimal, valid metadata-only pattern record from allowlisted fields. */
+const buildPatternRecord = (id: string, path: string, fields: Record<string, unknown>): PatternListObject => ({
+  id,
+  path,
+  title: asString(fields.title) ?? id,
+  description: asString(fields.description) ?? '',
+  group: asString(fields.group) ?? '',
+  components: [],
+  ...(asStringArray(fields.tags) ? { tags: asStringArray(fields.tags) } : {}),
+});
+
+/** Build a minimal, valid metadata-only page record from allowlisted fields. */
+const buildPageRecord = (id: string, path: string, fields: Record<string, unknown>): PageListObject => ({
+  id,
+  path,
+  title: asString(fields.title) ?? id,
+  description: asString(fields.description) ?? '',
+  group: asString(fields.group) ?? '',
+});
+
+/** Whether an entity exists by id. */
+export const entityExists = async (db: RegistryDatabase, kind: ManagedEntityKind, id: string): Promise<boolean> => {
+  const spec = ENTITY[kind];
+  const rows = await db.select({ id: spec.table.id }).from(spec.table).where(eq(spec.table.id, id)).limit(1);
+  return Boolean(rows[0]);
+};
+
+/** List all entities of a kind, each merged with its review metadata. */
+export const listEntities = async (db: RegistryDatabase, kind: ManagedEntityKind): Promise<RegistryEntityData[]> => {
+  const spec = ENTITY[kind];
+  const rows = await db.select({ record: spec.table.record, metadata: spec.table.metadata }).from(spec.table);
+  return rows.map((row) => withMetadata(row.record, row.metadata));
+};
+
+/** Read a single entity with its build/artifact state, or `null` when absent. */
+export const getEntity = async (db: RegistryDatabase, kind: ManagedEntityKind, id: string): Promise<EntityReadResult | null> => {
+  const spec = ENTITY[kind];
+  const rows = await db
+    .select({ record: spec.table.record, metadata: spec.table.metadata })
+    .from(spec.table)
+    .where(eq(spec.table.id, id))
+    .limit(1);
+  const row = rows[0];
+  if (!row) {
+    return null;
+  }
+  return { data: withMetadata(row.record, row.metadata), build: await resolveBuildMeta(db, kind, id) };
+};
+
+/** Create a metadata-only entity record. Returns `null` when an entity with that id already exists. */
+export const createEntity = async (
+  db: RegistryDatabase,
+  kind: ManagedEntityKind,
+  write: ValidatedMetadataWrite
+): Promise<EntityReadResult | null> => {
+  const spec = ENTITY[kind];
+  const id = write.id as string;
+  const path = `${spec.pathPrefix}/${id}`;
+  const { fields } = write;
+  const metadata = write.metadata ?? null;
+  const record =
+    kind === 'component'
+      ? buildComponentRecord(id, path, fields)
+      : kind === 'pattern'
+        ? buildPatternRecord(id, path, fields)
+        : buildPageRecord(id, path, fields);
+
+  // `tags` is promoted on components/patterns only; the pages table has no such column.
+  const baseValues = {
+    id,
+    path,
+    title: asString(fields.title),
+    description: asString(fields.description),
+    group: asString(fields.group),
+    record,
+    metadata,
+  };
+  const values =
+    kind === 'component'
+      ? { ...baseValues, tags: asStringArray(fields.tags), type: '', categories: asStringArray(fields.categories) }
+      : kind === 'pattern'
+        ? { ...baseValues, tags: asStringArray(fields.tags), components: [] }
+        : baseValues;
+
+  const inserted = await db
+    .insert(spec.table)
+    .values(values as any)
+    .onConflictDoNothing({ target: spec.table.id })
+    .returning({ id: spec.table.id });
+  if (inserted.length === 0) {
+    return null;
+  }
+  return { data: withMetadata(record, metadata), build: await resolveBuildMeta(db, kind, id) };
+};
+
+/**
+ * Apply an allowlisted metadata update: allowlisted top-level fields are written to both the
+ * normalized record and their promoted columns, and review metadata is merged over the existing
+ * value. Artifacts and build state are deliberately untouched. Returns `null` when absent.
+ */
+export const updateEntityMetadata = async (
+  db: RegistryDatabase,
+  kind: ManagedEntityKind,
+  id: string,
+  write: ValidatedMetadataWrite
+): Promise<EntityReadResult | null> => {
+  const spec = ENTITY[kind];
+  const rows = await db
+    .select({ record: spec.table.record, metadata: spec.table.metadata })
+    .from(spec.table)
+    .where(eq(spec.table.id, id))
+    .limit(1);
+  const row = rows[0];
+  if (!row) {
+    return null;
+  }
+
+  const record = { ...(row.record as Record<string, unknown>) };
+  const { fields } = write;
+  const promoted: Record<string, unknown> = { updatedAt: new Date() };
+
+  if ('title' in fields) {
+    record.title = fields.title;
+    promoted.title = fields.title;
+  }
+  if ('description' in fields) {
+    record.description = fields.description;
+    promoted.description = fields.description;
+  }
+  if ('group' in fields) {
+    record.group = fields.group;
+    promoted.group = fields.group;
+  }
+  if ('tags' in fields) {
+    record.tags = fields.tags;
+    promoted.tags = fields.tags;
+  }
+  if (kind === 'component' && 'categories' in fields) {
+    record.categories = fields.categories;
+    promoted.categories = fields.categories;
+  }
+
+  const metadata = mergeReviewMetadata(row.metadata, write.metadata);
+  promoted.record = record;
+  promoted.metadata = metadata;
+
+  await db
+    .update(spec.table)
+    .set(promoted as any)
+    .where(eq(spec.table.id, id));
+  return { data: withMetadata(record, metadata), build: await resolveBuildMeta(db, kind, id) };
+};
+
+/**
+ * Delete an entity and only the artifacts it owns. Cascade removes its text-file records; shared
+ * artifacts owned by `asset` are preserved. Returns `false` when the entity does not exist.
+ */
+export const deleteEntity = async (db: RegistryDatabase, kind: ManagedEntityKind, id: string): Promise<boolean> => {
+  return db.transaction(async (tx) => {
+    const transactionalDb = tx as unknown as RegistryDatabase;
+    const spec = ENTITY[kind];
+    if (!(await entityExists(transactionalDb, kind, id))) {
+      return false;
+    }
+    await transactionalDb.delete(docsArtifacts).where(and(eq(docsArtifacts.entityKind, kind), eq(docsArtifacts.entityId, id)));
+    if (kind !== 'page') {
+      await transactionalDb.delete(docsArtifacts).where(and(eq(docsArtifacts.ownerKind, kind), eq(docsArtifacts.ownerId, id)));
+    }
+    await transactionalDb.delete(buildMetadata).where(and(eq(buildMetadata.entityKind, kind), eq(buildMetadata.entityId, id)));
+    await transactionalDb.delete(spec.table).where(eq(spec.table.id, id));
+    return true;
+  });
+};
+
+/** List an entity's text-file records (inline content only). */
+export const listEntityFiles = async (db: RegistryDatabase, kind: ManagedEntityKind, id: string): Promise<ValidatedFile[]> => {
+  const spec = ENTITY[kind];
+  const rows = await db
+    .select({
+      path: spec.filesTable.path,
+      kind: spec.filesTable.kind,
+      content: spec.filesTable.content,
+      contentType: spec.filesTable.contentType,
+    })
+    .from(spec.filesTable)
+    .where(eq(spec.fileFkColumn, id));
+  return rows
+    .filter((row) => row.content != null)
+    .map((row) => ({ path: row.path, kind: row.kind, content: row.content as string, contentType: row.contentType }));
+};
+
+/** Read one text-file record by path, or `null` when absent (or stored without inline content). */
+export const getEntityFile = async (
+  db: RegistryDatabase,
+  kind: ManagedEntityKind,
+  id: string,
+  filePath: string
+): Promise<ValidatedFile | null> => {
+  const spec = ENTITY[kind];
+  const rows = await db
+    .select({
+      path: spec.filesTable.path,
+      kind: spec.filesTable.kind,
+      content: spec.filesTable.content,
+      contentType: spec.filesTable.contentType,
+    })
+    .from(spec.filesTable)
+    .where(and(eq(spec.fileFkColumn, id), eq(spec.filesTable.path, filePath)))
+    .limit(1);
+  const row = rows[0];
+  if (!row || row.content == null) {
+    return null;
+  }
+  return { path: row.path, kind: row.kind, content: row.content, contentType: row.contentType };
+};
+
+/** Insert or update a text-file record for an entity. */
+export const upsertEntityFile = async (
+  db: RegistryDatabase,
+  kind: ManagedEntityKind,
+  id: string,
+  file: ValidatedFile
+): Promise<ValidatedFile> => {
+  const spec = ENTITY[kind];
+  await db
+    .insert(spec.filesTable)
+    .values({
+      [spec.fileFkName]: id,
+      path: file.path,
+      kind: file.kind,
+      content: file.content,
+      contentType: file.contentType,
+    } as any)
+    .onConflictDoUpdate({
+      target: [spec.fileFkColumn, spec.filesTable.path],
+      set: { kind: file.kind, content: file.content, contentType: file.contentType, updatedAt: new Date() },
+    });
+  return file;
+};
+
+/** Delete a text-file record by path. Returns `false` when no such file exists. */
+export const deleteEntityFile = async (db: RegistryDatabase, kind: ManagedEntityKind, id: string, filePath: string): Promise<boolean> => {
+  const spec = ENTITY[kind];
+  const rows = await db
+    .select({ path: spec.filesTable.path })
+    .from(spec.filesTable)
+    .where(and(eq(spec.fileFkColumn, id), eq(spec.filesTable.path, filePath)))
+    .limit(1);
+  if (!rows[0]) {
+    return false;
+  }
+  await db.delete(spec.filesTable).where(and(eq(spec.fileFkColumn, id), eq(spec.filesTable.path, filePath)));
+  return true;
+};

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

@@ -0,0 +1,231 @@
+import type { NextApiRequest, NextApiResponse } from 'next';
+import { eq } from 'drizzle-orm';
+import type { RegistryDatabase } from '@handoff/registry/db/client';
+import { tokenArtifacts, tokenSets } from '@handoff/registry/db/schema';
+import { isTokenSetId, kindForSetId } from '@handoff/registry/tokens/sets';
+import type { TokenSetTransferArtifact, TokenSetTransferPackage } from '@handoff/registry/tokens/transfer';
+import { joinedQueryValue } from '../api/query';
+import { sendRegistryError } from './errors';
+import { buildMeta } from './meta';
+import { handleRegistryRoute, sendRegistryData } from './handler';
+import {
+  asString,
+  invalidPackage as invalid,
+  isPlainObject,
+  normalizeSafeRelativePath,
+  type PackageValidation,
+  validateTransferBuild,
+} from './validation';
+
+/**
+ * Token-set transfer ingestion for the registry.
+ *
+ * - `GET /api/registry/transfer/tokens` lists set summaries (id + kind + source hash) for the CLI's
+ *   skip-unchanged / bulk-checkout logic.
+ * - `GET /api/registry/transfer/tokens/:setId` is checkout: the set record + its generated artifacts.
+ * - `PUT /api/registry/transfer/tokens/:setId` is publish ingestion: it validates the package and
+ *   atomically upserts the `token_sets` row and replaces its `token_artifacts` in one transaction, so
+ *   a set is never left partially written — either the new version commits or the previous one stays.
+ *   An unchanged set (matching `sourceHash`) is a no-op. Absent sets are never deleted.
+ *
+ * Runs behind {@link handleRegistryRoute}: runtime-mode, method, bearer-token (on PUT), and database
+ * guards apply before any of this executes.
+ */
+
+/** Validate a token-set publish package against the transfer contract. */
+const validateTokenPackage = (body: unknown, setId: string): PackageValidation<TokenSetTransferPackage> => {
+  if (!isPlainObject(body)) {
+    return invalid('Request body must be a JSON object.');
+  }
+  if (!isTokenSetId(setId)) {
+    return invalid(`Unknown token set id "${setId}".`, { rejectedFields: ['id'] });
+  }
+
+  const bodyId = asString(body.id);
+  if (bodyId !== undefined && bodyId !== setId) {
+    return invalid(`Package set id "${bodyId}" does not match the publish target "${setId}".`, { rejectedFields: ['id'] });
+  }
+
+  const expectedKind = kindForSetId(setId);
+  const kind = asString(body.kind) ?? expectedKind;
+  if (kind !== 'foundation' && kind !== 'component') {
+    return invalid('`kind` must be "foundation" or "component".', { rejectedFields: ['kind'] });
+  }
+  if (kind !== expectedKind) {
+    return invalid(`Package kind "${kind}" is inconsistent with set id "${setId}".`, { rejectedFields: ['kind'] });
+  }
+
+  if (body.record === undefined || body.record === null) {
+    return invalid('A token `record` is required to publish.', { rejectedFields: ['record'] });
+  }
+
+  const rawArtifacts = body.artifacts ?? [];
+  if (!Array.isArray(rawArtifacts)) {
+    return invalid('`artifacts` must be an array.', { rejectedFields: ['artifacts'] });
+  }
+  const artifacts: TokenSetTransferArtifact[] = [];
+  const seenPaths = new Set<string>();
+  for (let i = 0; i < rawArtifacts.length; i += 1) {
+    const raw = rawArtifacts[i];
+    const field = (name: string) => `artifacts[${i}].${name}`;
+    if (!isPlainObject(raw)) {
+      return invalid('Each artifact must be an object.', { rejectedFields: [`artifacts[${i}]`] });
+    }
+    const artifactPath = normalizeSafeRelativePath(raw.path);
+    if (!artifactPath) {
+      return invalid('Artifact path must be a registry-safe relative path.', { rejectedFields: [field('path')] });
+    }
+    if (seenPaths.has(artifactPath)) {
+      return invalid(`Duplicate artifact path "${artifactPath}" in package.`, { rejectedFields: [field('path')] });
+    }
+    seenPaths.add(artifactPath);
+    if (typeof raw.content !== 'string') {
+      return invalid(`Artifact "${artifactPath}" is missing string content.`, { rejectedFields: [field('content')] });
+    }
+    const format = asString(raw.format);
+    if (!format) {
+      return invalid(`Artifact "${artifactPath}" is missing a format.`, { rejectedFields: [field('format')] });
+    }
+    artifacts.push({
+      path: artifactPath,
+      format,
+      content: raw.content as string,
+      contentType: asString(raw.contentType) || 'text/plain; charset=utf-8',
+      hash: asString(raw.hash),
+      size: typeof raw.size === 'number' ? raw.size : undefined,
+    });
+  }
+
+  const buildValidation = validateTransferBuild(body.build, {
+    requiredHashField: 'sourceHash',
+    currentMessage: 'A "current" token build requires builtAt, builderVersion, and sourceHash.',
+  });
+  if (!buildValidation.ok) {
+    return invalid(buildValidation.message, buildValidation.details);
+  }
+  const build = buildValidation.value;
+
+  return {
+    ok: true,
+    value: {
+      id: setId,
+      kind,
+      record: body.record,
+      artifacts,
+      build: {
+        status: build.status,
+        builtAt: build.builtAt,
+        builderVersion: build.builderVersion,
+        sourceHash: build.sourceHash,
+      },
+    },
+  };
+};
+
+/** The stored source hash for a set, or `undefined` when the set does not exist yet. */
+const storedSourceHash = async (db: RegistryDatabase, id: string): Promise<string | null | undefined> => {
+  const rows = await db.select({ sourceHash: tokenSets.sourceHash }).from(tokenSets).where(eq(tokenSets.id, id)).limit(1);
+  return rows.length ? rows[0].sourceHash : undefined;
+};
+
+/** Atomically upsert the set row and replace its artifacts in one transaction. */
+const ingestTokenSet = async (db: RegistryDatabase, pkg: TokenSetTransferPackage): Promise<void> => {
+  const setValues = {
+    kind: pkg.kind,
+    record: pkg.record,
+    sourceHash: pkg.build.sourceHash ?? null,
+    status: pkg.build.status,
+    builtAt: pkg.build.builtAt ? new Date(pkg.build.builtAt) : null,
+    builderVersion: pkg.build.builderVersion ?? null,
+    updatedAt: new Date(),
+  };
+
+  await db.transaction(async (tx) => {
+    await tx
+      .insert(tokenSets)
+      .values({ id: pkg.id, metadata: null, ...setValues } as any)
+      .onConflictDoUpdate({ target: tokenSets.id, set: setValues as any });
+
+    await tx.delete(tokenArtifacts).where(eq(tokenArtifacts.tokenSetId, pkg.id));
+    for (const artifact of pkg.artifacts) {
+      await tx.insert(tokenArtifacts).values({
+        tokenSetId: pkg.id,
+        path: artifact.path,
+        format: artifact.format,
+        content: artifact.content,
+        contentType: artifact.contentType,
+        hash: artifact.hash ?? null,
+        size: artifact.size ?? null,
+      } as any);
+    }
+  });
+};
+
+/** `GET /api/registry/transfer/tokens` — list set summaries (unauthenticated read behind the guards). */
+export const handleTokenSummaryRoute = (req: NextApiRequest, res: NextApiResponse): Promise<void> =>
+  handleRegistryRoute(req, res, ['GET'], async ({ db }) => {
+    const rows = await db
+      .select({ id: tokenSets.id, kind: tokenSets.kind, sourceHash: tokenSets.sourceHash, status: tokenSets.status })
+      .from(tokenSets);
+    sendRegistryData(res, 200, { sets: rows }, buildMeta());
+  });
+
+/** `GET /api/registry/transfer/tokens/:setId` — checkout one set's record + generated artifacts. */
+export const handleTokenCheckoutRoute = (req: NextApiRequest, res: NextApiResponse): Promise<void> =>
+  handleRegistryRoute(req, res, ['GET'], async ({ db }) => {
+    const id = joinedQueryValue(req.query.setId) ?? '';
+    if (!id) {
+      sendRegistryError(res, 'not_found', 'Missing token set id.');
+      return;
+    }
+    if (!isTokenSetId(id)) {
+      sendRegistryError(res, 'bad_request', `Unknown or unsafe token set id "${id}".`, {
+        rejectedFields: ['id'],
+      });
+      return;
+    }
+    const rows = await db.select({ kind: tokenSets.kind, record: tokenSets.record }).from(tokenSets).where(eq(tokenSets.id, id)).limit(1);
+    const set = rows[0];
+    if (!set) {
+      sendRegistryError(res, 'not_found', `No token set "${id}" exists in the registry.`);
+      return;
+    }
+    const artifacts = await db
+      .select({
+        path: tokenArtifacts.path,
+        format: tokenArtifacts.format,
+        content: tokenArtifacts.content,
+        contentType: tokenArtifacts.contentType,
+        hash: tokenArtifacts.hash,
+        size: tokenArtifacts.size,
+      })
+      .from(tokenArtifacts)
+      .where(eq(tokenArtifacts.tokenSetId, id));
+    sendRegistryData(res, 200, { id, kind: set.kind, record: set.record, artifacts }, buildMeta());
+  });
+
+/** `PUT /api/registry/transfer/tokens/:setId` — validate + atomically ingest one set. */
+export const handleTokenTransferRoute = (req: NextApiRequest, res: NextApiResponse): Promise<void> =>
+  handleRegistryRoute(req, res, ['PUT'], async ({ db }) => {
+    const id = joinedQueryValue(req.query.setId) ?? '';
+    if (!id) {
+      sendRegistryError(res, 'not_found', 'Missing token set id.');
+      return;
+    }
+
+    const validation = validateTokenPackage(req.body, id);
+    if (!validation.ok) {
+      sendRegistryError(res, 'bad_request', validation.message ?? 'Invalid token set package.', validation.details);
+      return;
+    }
+    const pkg = validation.value;
+
+    const existingHash = await storedSourceHash(db, id);
+    if (existingHash && pkg.build.sourceHash && existingHash === pkg.build.sourceHash) {
+      sendRegistryData(res, 200, { id, kind: pkg.kind, published: false, unchanged: true }, buildMeta());
+      return;
+    }
+
+    await ingestTokenSet(db, pkg);
+    sendRegistryData(res, 200, { id, kind: pkg.kind, published: true, artifacts: pkg.artifacts.length }, buildMeta());
+  });