handoff-app 1.2.2-7 → 2.0.0-0

package/src/registry/db/migrate.ts

@@ -0,0 +1,56 @@
+/**
+ * Registry migration runner.
+ *
+ * `handoff-app db:migrate` reads the consuming project's config + DB env vars, resolves the same
+ * `runtime.registry.database.adapter` used at runtime/build, and applies the package-owned
+ * migration set with the bundled Drizzle migrator. Migrations are resolved relative to the
+ * installed package (not the consuming project), so the schema is versioned with the tool. This
+ * runs independently of `build`.
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import type Handoff from '../../';
+import { Logger } from '../../utils/logger';
+import { resolveRegistryDatabase } from './adapter';
+import { createRegistryDbConnection } from './client';
+
+/**
+ * Absolute path to the package-owned migrations folder. Resolved relative to the installed
+ * `handoff-app` package root (`<package>/drizzle`) via {@link Handoff.modulePath} so it is
+ * independent of the consuming project's working directory.
+ */
+export const getMigrationsFolder = (handoff: Handoff): string => path.resolve(handoff.modulePath, 'drizzle');
+
+/**
+ * Run the package-owned registry migrations against the configured database.
+ *
+ * @throws when Handoff is uninitialized, the database URL env var is unset, or the packaged
+ *   migrations are missing — each with an actionable message.
+ */
+export const runRegistryMigrations = async (handoff: Handoff): Promise<void> => {
+  if (!handoff.config) {
+    throw new Error('Handoff is not initialized; cannot resolve registry database configuration.');
+  }
+
+  const { adapter, databaseUrlEnv, connectionString } = resolveRegistryDatabase(handoff.config);
+
+  const migrationsFolder = getMigrationsFolder(handoff);
+  const journalPath = path.join(migrationsFolder, 'meta', '_journal.json');
+  if (!fs.existsSync(journalPath)) {
+    throw new Error(
+      `Packaged registry migrations were not found at "${migrationsFolder}". This indicates a broken ` +
+        `handoff-app installation — reinstall the package to restore the bundled migration set.`
+    );
+  }
+
+  Logger.info(`Running registry migrations (adapter: "${adapter}", database url from "${databaseUrlEnv}").`);
+
+  const connection = await createRegistryDbConnection({ adapter, connectionString });
+  try {
+    await connection.migrate(migrationsFolder);
+    Logger.success('Registry migrations applied successfully.');
+  } finally {
+    await connection.close();
+  }
+};

package/src/registry/db/schema.ts

@@ -0,0 +1,444 @@
+/**
+ * Drizzle ORM schema for registry storage.
+ *
+ * The registry is database-backed (PostgreSQL, including PG-compatible managed services such as
+ * Neon/Vercel). This schema declares the six record groups the registry persists:
+ *
+ * - `components` / `component_files`
+ * - `patterns` / `pattern_files`
+ * - `docs_artifacts` (docs read-model artifacts)
+ * - `build_metadata` (build/artifact metadata)
+ *
+ * Schema notes:
+ * - Artifact and build-metadata columns mirror the structured artifact model
+ *   (`ArtifactDescriptor`, `ArtifactBuildMetadata`, `ArtifactReference`) so the database can
+ *   validate, serve, and debug an artifact without ever parsing HTML.
+ * - Metadata-only records are supported: a component/pattern row may exist with no
+ *   `docs_artifacts` rows and a `build_metadata` row reporting `status: 'missing'`.
+ * - Text file records (`component_files` / `pattern_files`) cover checkout/inspection/management
+ *   only and **exclude declaration files** — a CHECK constraint rejects `kind = 'declaration'`,
+ *   so declarations have no representation in registry text file records.
+ * - `content` and `storage_ref` are both nullable so the model leaves room for future object
+ *   storage of large/binary assets (a content-reference field) rather than assuming inline content.
+ */
+
+import { sql } from 'drizzle-orm';
+import { check, customType, index, integer, jsonb, pgTable, primaryKey, text, timestamp } from 'drizzle-orm/pg-core';
+import type { ArtifactBuildStatus, ArtifactKind, ArtifactOwnerKind, ArtifactReference } from '../../artifacts/types';
+import type { RegistryTextFileKind } from '../../store/types';
+import type { TokenSetKind } from '../tokens/sets';
+
+/**
+ * PostgreSQL `bytea` column. Drizzle pg-core has no built-in binary type, so declare it once here.
+ * Reads/writes are Node `Buffer`s. The default asset storage adapter keeps small/ordinary asset
+ * bytes inline in this column; larger assets are offloaded to an object-storage `storageRef` instead.
+ */
+const bytea = customType<{ data: Buffer; driverData: Buffer }>({
+  dataType() {
+    return 'bytea';
+  },
+});
+
+/** Where an asset blob's bytes physically live: the default DB adapter, Vercel Blob, or a custom id. */
+export type AssetStorageProvider = 'database' | 'vercel-blob' | (string & {});
+import type { ComponentListObject, PageListObject, PatternComponentEntry, PatternListObject } from '../../transformers/preview/types';
+
+/**
+ * Entity a docs read-model artifact is associated with. `page` is included only for type-compat with
+ * the generic management delete path (which filters `docs_artifacts.entityKind` by kind); pages emit
+ * no artifacts, so no page-owned `docs_artifacts` rows ever exist.
+ */
+export type DocsArtifactEntityKind = 'component' | 'pattern' | 'page' | 'summary' | 'asset';
+
+/** Entity a build-metadata record is associated with. A page publish writes one `build_metadata` row. */
+export type BuildMetadataEntityKind = 'component' | 'pattern' | 'page' | 'asset' | 'summary';
+
+/**
+ * Registry-only review/catalog metadata maintained through the management API.
+ *
+ * These fields are review state, not render/build inputs — the management API's metadata allowlist
+ * is the only writer, and updating them never touches `docs_artifacts` or `build_metadata`. Stored
+ * in a dedicated column rather than the normalized `record` jsonb so the served record stays
+ * identical in shape to what the filesystem store produces.
+ */
+export interface RegistryReviewMetadata {
+  /** Free-form review status (e.g. `draft`, `in-review`, `approved`). */
+  reviewStatus?: string;
+  /** Reviewer notes. */
+  notes?: string;
+  /** Owner identifier (name, handle, or email). */
+  owner?: string;
+}
+
+/** Build status mirrored from {@link import('../../artifacts/types').ArtifactBuildStatus}. */
+export type RegistryBuildStatus = ArtifactBuildStatus;
+
+/**
+ * Components record group. `record` holds the full normalized {@link ComponentListObject} so the
+ * registry serves the same record shape as the filesystem store; the promoted columns exist for
+ * querying/sorting the catalog.
+ */
+export const components = pgTable(
+  'components',
+  {
+    /** Stable component id (explicit `id`, else directory basename). Join key across stores. */
+    id: text('id').primaryKey(),
+    /** Logical docs path for the component. */
+    path: text('path').notNull(),
+    title: text('title'),
+    description: text('description'),
+    group: text('group'),
+    type: text('type'),
+    renderer: text('renderer'),
+    tags: jsonb('tags').$type<string[]>(),
+    categories: jsonb('categories').$type<string[]>(),
+    /** Full normalized component record. */
+    record: jsonb('record').$type<ComponentListObject>().notNull(),
+    /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
+    metadata: jsonb('metadata').$type<RegistryReviewMetadata>(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index('components_group_idx').on(table.group)]
+);
+
+/**
+ * Component source files. Used for checkout/inspection/management only — never to rebuild
+ * previews. Declaration files are rejected at the schema level.
+ */
+export const componentFiles = pgTable(
+  'component_files',
+  {
+    componentId: text('component_id')
+      .notNull()
+      .references(() => components.id, { onDelete: 'cascade' }),
+    /** Registry-safe relative path within the entity (e.g. `Badge.tsx`). */
+    path: text('path').notNull(),
+    kind: text('kind').$type<RegistryTextFileKind>().notNull(),
+    /** Inline content; null when stored externally via `storageRef`. */
+    content: text('content'),
+    /** Reference to externally stored content (future object storage). */
+    storageRef: text('storage_ref'),
+    contentType: text('content_type').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.componentId, table.path] }),
+    check('component_files_kind_not_declaration', sql`${table.kind} <> 'declaration'`),
+  ]
+);
+
+/**
+ * Patterns record group. `record` holds the full normalized {@link PatternListObject};
+ * `components` promotes the pattern's component refs for querying.
+ */
+export const patterns = pgTable(
+  'patterns',
+  {
+    /** Stable pattern id. Join key across stores. */
+    id: text('id').primaryKey(),
+    path: text('path').notNull(),
+    title: text('title'),
+    description: text('description'),
+    group: text('group'),
+    tags: jsonb('tags').$type<string[]>(),
+    /** Pattern component references. */
+    components: jsonb('components').$type<PatternComponentEntry[]>(),
+    /** Full normalized pattern record. */
+    record: jsonb('record').$type<PatternListObject>().notNull(),
+    /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
+    metadata: jsonb('metadata').$type<RegistryReviewMetadata>(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index('patterns_group_idx').on(table.group)]
+);
+
+/**
+ * Pattern source files. Same checkout/inspection/management role as {@link componentFiles};
+ * declaration files are rejected at the schema level.
+ */
+export const patternFiles = pgTable(
+  'pattern_files',
+  {
+    patternId: text('pattern_id')
+      .notNull()
+      .references(() => patterns.id, { onDelete: 'cascade' }),
+    path: text('path').notNull(),
+    kind: text('kind').$type<RegistryTextFileKind>().notNull(),
+    content: text('content'),
+    storageRef: text('storage_ref'),
+    contentType: text('content_type').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.patternId, table.path] }),
+    check('pattern_files_kind_not_declaration', sql`${table.kind} <> 'declaration'`),
+  ]
+);
+
+/**
+ * Pages record group. `record` holds the full normalized {@link PageListObject} (frontmatter
+ * metadata) so the registry serves the same record shape the filesystem store produces; promoted
+ * columns exist for catalog querying/sorting. The markdown body travels as a `page_files` row, not in
+ * the record — see {@link pageFiles}.
+ */
+export const pages = pgTable(
+  'pages',
+  {
+    /** Stable page id (slug path, e.g. `guides/setup`). Join key across stores. */
+    id: text('id').primaryKey(),
+    /** Logical route the page is served at (e.g. `/guides/setup`). */
+    path: text('path').notNull(),
+    title: text('title'),
+    description: text('description'),
+    group: text('group'),
+    /** Sort weight within the nav section. */
+    weight: integer('weight'),
+    /** Full normalized page record. */
+    record: jsonb('record').$type<PageListObject>().notNull(),
+    /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
+    metadata: jsonb('metadata').$type<RegistryReviewMetadata>(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index('pages_group_idx').on(table.group)]
+);
+
+/**
+ * Page source files. A page has a single verbatim `.md` (kind `markdown`) stored for byte-exact
+ * checkout and for resolving the rendered body at request time. Declaration files are rejected at the
+ * schema level (consistent with the other file tables, though pages never carry declarations).
+ */
+export const pageFiles = pgTable(
+  'page_files',
+  {
+    pageId: text('page_id')
+      .notNull()
+      .references(() => pages.id, { onDelete: 'cascade' }),
+    /** Registry-safe relative path within the entity (e.g. `guides/setup.md`). */
+    path: text('path').notNull(),
+    kind: text('kind').$type<RegistryTextFileKind>().notNull(),
+    content: text('content'),
+    storageRef: text('storage_ref'),
+    contentType: text('content_type').notNull(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.pageId, table.path] }),
+    check('page_files_kind_not_declaration', sql`${table.kind} <> 'declaration'`),
+  ]
+);
+
+/**
+ * Docs read-model artifacts. Path-keyed so shared/global artifacts (`component/main.css`,
+ * `component/main.js`, `component/shared.css`) are upserted by stable logical path. Mirrors the
+ * `ArtifactDescriptor` field set.
+ */
+export const docsArtifacts = pgTable(
+  'docs_artifacts',
+  {
+    /** Logical artifact path (e.g. `component/badge-primary.html`). Stable serving key. */
+    path: text('path').primaryKey(),
+    entityKind: text('entity_kind').$type<DocsArtifactEntityKind>().notNull(),
+    entityId: text('entity_id'),
+    artifactKind: text('artifact_kind').$type<ArtifactKind>().notNull(),
+    /** Inline content; null when stored externally via `storageRef`. */
+    content: text('content'),
+    /** Reference to externally stored content (future object storage). */
+    storageRef: text('storage_ref'),
+    contentType: text('content_type').notNull(),
+    ownerKind: text('owner_kind').$type<ArtifactOwnerKind>(),
+    ownerId: text('owner_id'),
+    /** Structured required/optional references (drives validation/serving/dedup). */
+    references: jsonb('references').$type<ArtifactReference[]>(),
+    formatVersion: text('format_version'),
+    buildId: text('build_id'),
+    hash: text('hash'),
+    size: integer('size'),
+    /** Gzipped byte size diagnostic, when measured. */
+    gzipSize: integer('gzip_size'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [
+    index('docs_artifacts_entity_idx').on(table.entityKind, table.entityId),
+    index('docs_artifacts_owner_idx').on(table.ownerKind, table.ownerId),
+  ]
+);
+
+/**
+ * Build/artifact metadata per entity. Mirrors the `ArtifactBuildMetadata` field set.
+ * A successful publish records `status: 'current'` with `builtAt` + `builderVersion` +
+ * `artifactHash`; metadata-only records report `status: 'missing'`.
+ */
+export const buildMetadata = pgTable(
+  'build_metadata',
+  {
+    entityKind: text('entity_kind').$type<BuildMetadataEntityKind>().notNull(),
+    entityId: text('entity_id').notNull(),
+    status: text('status').$type<RegistryBuildStatus>().notNull(),
+    builtAt: timestamp('built_at', { withTimezone: true }),
+    builderVersion: text('builder_version'),
+    artifactHash: text('artifact_hash'),
+    sourceHash: text('source_hash'),
+    warnings: jsonb('warnings').$type<string[]>(),
+    error: text('error'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [primaryKey({ columns: [table.entityKind, table.entityId] })]
+);
+
+/**
+ * Token sets record group. One row per logical token set (`foundation/colors`, `component/<id>`).
+ * `record` holds the exact extracted token slice as JSONB so no token property is lost and new ones
+ * flow through without a migration. Build/publish metadata (status/source_hash/built_at) lives on
+ * this row — tokens are self-contained and do not use the shared `build_metadata` table.
+ */
+export const tokenSets = pgTable(
+  'token_sets',
+  {
+    /** Stable logical set id (`foundation/colors` | `component/button`). Join key across stores. */
+    id: text('id').primaryKey(),
+    /** Set kind (`foundation` | `component`). */
+    kind: text('kind').$type<TokenSetKind>().notNull(),
+    /** Full extracted token slice (`IColorObject[]`/…/`IFileComponentObject`). */
+    record: jsonb('record').notNull(),
+    /** Deterministic content hash over the record + generated artifacts (drives skip-unchanged). */
+    sourceHash: text('source_hash'),
+    /** Build/publish status for the set. */
+    status: text('status').$type<RegistryBuildStatus>(),
+    builtAt: timestamp('built_at', { withTimezone: true }),
+    builderVersion: text('builder_version'),
+    /** Registry-only review/catalog metadata (parity with other entities; management-API only). */
+    metadata: jsonb('metadata').$type<RegistryReviewMetadata>(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [index('token_sets_kind_idx').on(table.kind)]
+);
+
+/**
+ * Generated token artifacts owned by a token set (CSS/SCSS/Style Dictionary/types/custom transformer
+ * output). Served byte-for-byte; the registry never re-runs transformers. Keyed by `(token_set_id,
+ * path)` where `path` is the registry-safe output path relative to `getVariablesFilePath()`.
+ */
+export const tokenArtifacts = pgTable(
+  'token_artifacts',
+  {
+    tokenSetId: text('token_set_id')
+      .notNull()
+      .references(() => tokenSets.id, { onDelete: 'cascade' }),
+    /** Registry-safe relative output path (e.g. `css/colors.css`, `sd/button/button.tokens.json`). */
+    path: text('path').notNull(),
+    /** Logical format label (`css`|`scss`|`types`|`styleDictionary`|custom outDir). */
+    format: text('format').notNull(),
+    /** Inline content; null when stored externally via `storageRef`. */
+    content: text('content'),
+    /** Reference to externally stored content (future object storage). */
+    storageRef: text('storage_ref'),
+    contentType: text('content_type').notNull(),
+    hash: text('hash'),
+    size: integer('size'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [primaryKey({ columns: [table.tokenSetId, table.path] })]
+);
+
+/**
+ * Asset collections. Owns a collection (`icons`|`logos`|`fonts`) and its build/publish metadata
+ * (mirrors {@link tokenSets}): `sourceHash` drives skip-unchanged, and the set of `assets` rows for a
+ * collection is its current manifest. Publish replaces those rows atomically, so readers always see a
+ * complete manifest.
+ */
+export const assetCollections = pgTable(
+  'asset_collections',
+  {
+    /** Stable collection id (`icons`|`logos`|`fonts`). Join key across stores. */
+    collection: text('collection').primaryKey(),
+    /** Deterministic content hash over the collection's `(path, contentHash)` manifest (skip-unchanged). */
+    sourceHash: text('source_hash'),
+    /** Build/publish status for the collection. */
+    status: text('status').$type<RegistryBuildStatus>(),
+    builtAt: timestamp('built_at', { withTimezone: true }),
+    builderVersion: text('builder_version'),
+    /** Registry-only review/catalog metadata (parity with other entities; management-API only). */
+    metadata: jsonb('metadata').$type<RegistryReviewMetadata>(),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  }
+);
+
+/**
+ * Logical asset metadata - the collection manifest. One row per asset (icon/logo SVG, sprite,
+ * sprite manifest, ZIP archive, font archive), keyed by `(collection, path)`. Binary content is not
+ * stored here; `blobHash` references the content-addressed {@link assetBlobs} store, so identical
+ * bytes across paths/collections dedupe to one blob.
+ */
+export const assets = pgTable(
+  'assets',
+  {
+    collection: text('collection')
+      .notNull()
+      .references(() => assetCollections.collection, { onDelete: 'cascade' }),
+    /** Registry-safe logical path within the collection (e.g. `assets/icons/add.svg`, `icons.zip`). */
+    path: text('path').notNull(),
+    /** Human-facing asset name. */
+    name: text('name').notNull(),
+    contentType: text('content_type').notNull(),
+    size: integer('size'),
+    /** SHA-256 of the asset bytes - the blob identity, and the ETag for content responses. */
+    contentHash: text('content_hash').notNull(),
+    /** Free-form asset metadata carried from extraction (icon index, description, …). */
+    metadata: jsonb('metadata'),
+    /** References {@link assetBlobs.hash}; equals `contentHash`. */
+    blobHash: text('blob_hash')
+      .notNull()
+      .references(() => assetBlobs.hash),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (table) => [primaryKey({ columns: [table.collection, table.path] })]
+);
+
+/**
+ * Content-addressed binary blob store, shared across assets/collections (the `hash` is the blob
+ * identity, so an unchanged file re-references the same row). Exactly one location is active per row:
+ * inline `content` (bytea, default DB adapter) or an external `storageRef` resolved through the
+ * recorded `storageProvider`. Both nullable so DB- and object-backed blobs coexist.
+ */
+export const assetBlobs = pgTable('asset_blobs', {
+  /** SHA-256 of the blob bytes (hex). */
+  hash: text('hash').primaryKey(),
+  /** Which storage backed this blob when it was written (`database`|`vercel-blob`|custom id). */
+  storageProvider: text('storage_provider').$type<AssetStorageProvider>().notNull(),
+  /** Inline bytes; null when stored externally via `storageRef`. */
+  content: bytea('content'),
+  /** External object reference/key; null when stored inline in `content`. */
+  storageRef: text('storage_ref'),
+  contentType: text('content_type').notNull(),
+  size: integer('size').notNull(),
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+});
+
+/** All registry tables, for typed Drizzle clients and migration tooling. */
+export const registrySchema = {
+  components,
+  componentFiles,
+  patterns,
+  patternFiles,
+  pages,
+  pageFiles,
+  docsArtifacts,
+  buildMetadata,
+  tokenSets,
+  tokenArtifacts,
+  assetCollections,
+  assets,
+  assetBlobs,
+};

package/src/registry/path.ts

@@ -0,0 +1,26 @@
+import path from 'path';
+
+export const isSafeRelativePath = (value: string): boolean => {
+  if (typeof value !== 'string' || value.trim() === '') {
+    return false;
+  }
+  const normalized = normalizeRelativePath(value);
+  if (normalized.startsWith('/') || /^[a-zA-Z]:/.test(normalized)) {
+    return false;
+  }
+  return normalized.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+};
+
+export const normalizeRelativePath = (value: string): string => value.replace(/\\/g, '/');
+
+export const isSafePathSegment = (value: string): boolean =>
+  typeof value === 'string' && value === value.trim() && isSafeRelativePath(value) && !normalizeRelativePath(value).includes('/');
+
+export const resolvePathWithin = (root: string, value: string): string | null => {
+  if (!isSafeRelativePath(value)) {
+    return null;
+  }
+  const absolutePath = path.resolve(root, ...normalizeRelativePath(value).split('/'));
+  const relativePath = path.relative(root, absolutePath);
+  return relativePath.startsWith('..') || path.isAbsolute(relativePath) ? null : absolutePath;
+};

package/src/registry/publish/artifacts.ts

@@ -0,0 +1,147 @@
+import fs from 'fs-extra';
+import path from 'path';
+import {
+  ARTIFACTS_ROUTE_SEGMENT,
+  SHARED_MAIN_CSS_ARTIFACT_PATH,
+  SHARED_MAIN_JS_ARTIFACT_PATH,
+  SHARED_STYLES_CSS_ARTIFACT_PATH,
+} from '../../artifacts';
+import type { ArtifactKind, ArtifactReference } from '../../artifacts/types';
+import Handoff from '../../index';
+import type { TransferArtifact } from '../transfer';
+
+const SHARED_ARTIFACT_PATHS = new Set([SHARED_MAIN_CSS_ARTIFACT_PATH, SHARED_MAIN_JS_ARTIFACT_PATH, SHARED_STYLES_CSS_ARTIFACT_PATH]);
+
+const CLIENT_ARTIFACT_SUFFIX = '.client.js';
+
+const ARTIFACT_KIND_BY_EXT: Record<string, ArtifactKind> = {
+  '.json': 'json',
+  '.html': 'html',
+  '.css': 'css',
+  '.js': 'javascript',
+};
+
+const CONTENT_TYPE_BY_EXT: Record<string, string> = {
+  '.json': 'application/json',
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'application/javascript; charset=utf-8',
+};
+
+const artifactKindForPath = (artifactPath: string): ArtifactKind =>
+  ARTIFACT_KIND_BY_EXT[path.extname(artifactPath).toLowerCase()] ?? 'other';
+
+const contentTypeForPath = (artifactPath: string): string =>
+  CONTENT_TYPE_BY_EXT[path.extname(artifactPath).toLowerCase()] ?? 'text/plain; charset=utf-8';
+
+/** Absolute path of the generated artifact root the build writes to (`<workspace>/public/api`). */
+export const getArtifactRoot = (handoff: Handoff): string => path.resolve(handoff.workingPath, 'public', 'api');
+
+export const isSharedArtifactPath = (artifactPath: string): boolean => SHARED_ARTIFACT_PATHS.has(artifactPath);
+
+/**
+ * Resolve the owning component id for a file under `public/api/component`, or `null` when it is a
+ * shared artifact or owned by no known component. Exact CSS, JavaScript, JSON, and client bundle
+ * filenames map directly. HTML filenames use the longest known component id prefix, which prevents
+ * a component such as `button group` from being read as `button`.
+ */
+export const resolveComponentArtifactOwner = (fileName: string, componentIds: Set<string>): string | null => {
+  if (isSharedArtifactPath(`component/${fileName}`)) {
+    return null;
+  }
+  if (fileName.endsWith(CLIENT_ARTIFACT_SUFFIX)) {
+    const id = fileName.slice(0, -CLIENT_ARTIFACT_SUFFIX.length);
+    return componentIds.has(id) ? id : null;
+  }
+  const ext = path.extname(fileName).toLowerCase();
+  if (ext === '.css' || ext === '.js' || ext === '.json') {
+    const id = fileName.slice(0, -ext.length);
+    return componentIds.has(id) ? id : null;
+  }
+  if (ext === '.html') {
+    let longest: string | null = null;
+    for (const id of Array.from(componentIds)) {
+      if (fileName.startsWith(`${id}-`) && (!longest || id.length > longest.length)) {
+        longest = id;
+      }
+    }
+    return longest;
+  }
+  return null;
+};
+
+/** Extract the logical artifact paths an HTML document references through the canonical route. */
+const extractReferencedArtifactPaths = (html: string): string[] => {
+  const pattern = new RegExp(`(?:href|src)=["'][^"']*?${ARTIFACTS_ROUTE_SEGMENT}/([^"']+)["']`, 'g');
+  const paths = new Set<string>();
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(html)) !== null) {
+    const encoded = match[1].split(/[?#]/)[0];
+    const segments = encoded.split('/').filter(Boolean);
+    try {
+      const decoded = segments.map((segment) => decodeURIComponent(segment));
+      if (decoded.length > 0) {
+        paths.add(decoded.join('/'));
+      }
+    } catch {
+      paths.add(encoded);
+    }
+  }
+  return Array.from(paths);
+};
+
+/** Build a structured reference for a referenced artifact path (only the client bundle is required). */
+const toArtifactReference = (referencedPath: string): ArtifactReference => {
+  if (referencedPath.endsWith(CLIENT_ARTIFACT_SUFFIX)) {
+    const ownerId = path.basename(referencedPath).slice(0, -CLIENT_ARTIFACT_SUFFIX.length);
+    return { path: referencedPath, kind: 'client', required: true, ownerKind: 'component', ownerId };
+  }
+  if (isSharedArtifactPath(referencedPath)) {
+    return { path: referencedPath, kind: 'shared', required: false, ownerKind: 'asset', ownerId: null };
+  }
+  const ext = path.extname(referencedPath).toLowerCase();
+  if (referencedPath.startsWith('component/') && (ext === '.css' || ext === '.js')) {
+    const ownerId = path.basename(referencedPath, ext);
+    return { path: referencedPath, kind: ext === '.css' ? 'style' : 'script', required: false, ownerKind: 'component', ownerId };
+  }
+  return { path: referencedPath, kind: 'other', required: false };
+};
+
+/** Read a generated artifact file into a {@link TransferArtifact}, or `null` when it does not exist. */
+export const readArtifact = (
+  root: string,
+  artifactPath: string,
+  ownerKind: TransferArtifact['ownerKind'],
+  ownerId: string | null
+): TransferArtifact | null => {
+  const absolutePath = path.resolve(root, ...artifactPath.split('/'));
+  if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+    return null;
+  }
+  const content = fs.readFileSync(absolutePath, 'utf8');
+  const references = artifactPath.endsWith('.html') ? extractReferencedArtifactPaths(content).map(toArtifactReference) : undefined;
+  return {
+    path: artifactPath,
+    artifactKind: artifactKindForPath(artifactPath),
+    content,
+    contentType: contentTypeForPath(artifactPath),
+    ownerKind,
+    ownerId,
+    references,
+    size: Buffer.byteLength(content, 'utf8'),
+  };
+};
+
+/** Add a referenced shared/component artifact to the map when present on disk (deduped by path). */
+export const addReferencedArtifact = (root: string, artifactPath: string, byPath: Map<string, TransferArtifact>): void => {
+  if (byPath.has(artifactPath)) {
+    return;
+  }
+  const reference = toArtifactReference(artifactPath);
+  const ownerKind = reference.ownerKind ?? (isSharedArtifactPath(artifactPath) ? 'asset' : 'component');
+  const ownerId = reference.ownerKind === 'asset' ? null : (reference.ownerId ?? null);
+  const artifact = readArtifact(root, artifactPath, ownerKind, ownerId);
+  if (artifact) {
+    byPath.set(artifactPath, artifact);
+  }
+};