handoff-app 1.2.2-7 → 2.0.0-0

package/dist/registry/db/schema.js

@@ -0,0 +1,347 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registrySchema = exports.assetBlobs = exports.assets = exports.assetCollections = exports.tokenArtifacts = exports.tokenSets = exports.buildMetadata = exports.docsArtifacts = exports.pageFiles = exports.pages = exports.patternFiles = exports.patterns = exports.componentFiles = exports.components = void 0;
+const drizzle_orm_1 = require("drizzle-orm");
+const pg_core_1 = require("drizzle-orm/pg-core");
+/**
+ * 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 = (0, pg_core_1.customType)({
+    dataType() {
+        return 'bytea';
+    },
+});
+/**
+ * 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.
+ */
+exports.components = (0, pg_core_1.pgTable)('components', {
+    /** Stable component id (explicit `id`, else directory basename). Join key across stores. */
+    id: (0, pg_core_1.text)('id').primaryKey(),
+    /** Logical docs path for the component. */
+    path: (0, pg_core_1.text)('path').notNull(),
+    title: (0, pg_core_1.text)('title'),
+    description: (0, pg_core_1.text)('description'),
+    group: (0, pg_core_1.text)('group'),
+    type: (0, pg_core_1.text)('type'),
+    renderer: (0, pg_core_1.text)('renderer'),
+    tags: (0, pg_core_1.jsonb)('tags').$type(),
+    categories: (0, pg_core_1.jsonb)('categories').$type(),
+    /** Full normalized component record. */
+    record: (0, pg_core_1.jsonb)('record').$type().notNull(),
+    /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
+    metadata: (0, pg_core_1.jsonb)('metadata').$type(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [(0, pg_core_1.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.
+ */
+exports.componentFiles = (0, pg_core_1.pgTable)('component_files', {
+    componentId: (0, pg_core_1.text)('component_id')
+        .notNull()
+        .references(() => exports.components.id, { onDelete: 'cascade' }),
+    /** Registry-safe relative path within the entity (e.g. `Badge.tsx`). */
+    path: (0, pg_core_1.text)('path').notNull(),
+    kind: (0, pg_core_1.text)('kind').$type().notNull(),
+    /** Inline content; null when stored externally via `storageRef`. */
+    content: (0, pg_core_1.text)('content'),
+    /** Reference to externally stored content (future object storage). */
+    storageRef: (0, pg_core_1.text)('storage_ref'),
+    contentType: (0, pg_core_1.text)('content_type').notNull(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [
+    (0, pg_core_1.primaryKey)({ columns: [table.componentId, table.path] }),
+    (0, pg_core_1.check)('component_files_kind_not_declaration', (0, drizzle_orm_1.sql) `${table.kind} <> 'declaration'`),
+]);
+/**
+ * Patterns record group. `record` holds the full normalized {@link PatternListObject};
+ * `components` promotes the pattern's component refs for querying.
+ */
+exports.patterns = (0, pg_core_1.pgTable)('patterns', {
+    /** Stable pattern id. Join key across stores. */
+    id: (0, pg_core_1.text)('id').primaryKey(),
+    path: (0, pg_core_1.text)('path').notNull(),
+    title: (0, pg_core_1.text)('title'),
+    description: (0, pg_core_1.text)('description'),
+    group: (0, pg_core_1.text)('group'),
+    tags: (0, pg_core_1.jsonb)('tags').$type(),
+    /** Pattern component references. */
+    components: (0, pg_core_1.jsonb)('components').$type(),
+    /** Full normalized pattern record. */
+    record: (0, pg_core_1.jsonb)('record').$type().notNull(),
+    /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
+    metadata: (0, pg_core_1.jsonb)('metadata').$type(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [(0, pg_core_1.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.
+ */
+exports.patternFiles = (0, pg_core_1.pgTable)('pattern_files', {
+    patternId: (0, pg_core_1.text)('pattern_id')
+        .notNull()
+        .references(() => exports.patterns.id, { onDelete: 'cascade' }),
+    path: (0, pg_core_1.text)('path').notNull(),
+    kind: (0, pg_core_1.text)('kind').$type().notNull(),
+    content: (0, pg_core_1.text)('content'),
+    storageRef: (0, pg_core_1.text)('storage_ref'),
+    contentType: (0, pg_core_1.text)('content_type').notNull(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [
+    (0, pg_core_1.primaryKey)({ columns: [table.patternId, table.path] }),
+    (0, pg_core_1.check)('pattern_files_kind_not_declaration', (0, drizzle_orm_1.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}.
+ */
+exports.pages = (0, pg_core_1.pgTable)('pages', {
+    /** Stable page id (slug path, e.g. `guides/setup`). Join key across stores. */
+    id: (0, pg_core_1.text)('id').primaryKey(),
+    /** Logical route the page is served at (e.g. `/guides/setup`). */
+    path: (0, pg_core_1.text)('path').notNull(),
+    title: (0, pg_core_1.text)('title'),
+    description: (0, pg_core_1.text)('description'),
+    group: (0, pg_core_1.text)('group'),
+    /** Sort weight within the nav section. */
+    weight: (0, pg_core_1.integer)('weight'),
+    /** Full normalized page record. */
+    record: (0, pg_core_1.jsonb)('record').$type().notNull(),
+    /** Registry-only review/catalog metadata (management-API allowlist; never a render input). */
+    metadata: (0, pg_core_1.jsonb)('metadata').$type(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [(0, pg_core_1.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).
+ */
+exports.pageFiles = (0, pg_core_1.pgTable)('page_files', {
+    pageId: (0, pg_core_1.text)('page_id')
+        .notNull()
+        .references(() => exports.pages.id, { onDelete: 'cascade' }),
+    /** Registry-safe relative path within the entity (e.g. `guides/setup.md`). */
+    path: (0, pg_core_1.text)('path').notNull(),
+    kind: (0, pg_core_1.text)('kind').$type().notNull(),
+    content: (0, pg_core_1.text)('content'),
+    storageRef: (0, pg_core_1.text)('storage_ref'),
+    contentType: (0, pg_core_1.text)('content_type').notNull(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [
+    (0, pg_core_1.primaryKey)({ columns: [table.pageId, table.path] }),
+    (0, pg_core_1.check)('page_files_kind_not_declaration', (0, drizzle_orm_1.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.
+ */
+exports.docsArtifacts = (0, pg_core_1.pgTable)('docs_artifacts', {
+    /** Logical artifact path (e.g. `component/badge-primary.html`). Stable serving key. */
+    path: (0, pg_core_1.text)('path').primaryKey(),
+    entityKind: (0, pg_core_1.text)('entity_kind').$type().notNull(),
+    entityId: (0, pg_core_1.text)('entity_id'),
+    artifactKind: (0, pg_core_1.text)('artifact_kind').$type().notNull(),
+    /** Inline content; null when stored externally via `storageRef`. */
+    content: (0, pg_core_1.text)('content'),
+    /** Reference to externally stored content (future object storage). */
+    storageRef: (0, pg_core_1.text)('storage_ref'),
+    contentType: (0, pg_core_1.text)('content_type').notNull(),
+    ownerKind: (0, pg_core_1.text)('owner_kind').$type(),
+    ownerId: (0, pg_core_1.text)('owner_id'),
+    /** Structured required/optional references (drives validation/serving/dedup). */
+    references: (0, pg_core_1.jsonb)('references').$type(),
+    formatVersion: (0, pg_core_1.text)('format_version'),
+    buildId: (0, pg_core_1.text)('build_id'),
+    hash: (0, pg_core_1.text)('hash'),
+    size: (0, pg_core_1.integer)('size'),
+    /** Gzipped byte size diagnostic, when measured. */
+    gzipSize: (0, pg_core_1.integer)('gzip_size'),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [
+    (0, pg_core_1.index)('docs_artifacts_entity_idx').on(table.entityKind, table.entityId),
+    (0, pg_core_1.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'`.
+ */
+exports.buildMetadata = (0, pg_core_1.pgTable)('build_metadata', {
+    entityKind: (0, pg_core_1.text)('entity_kind').$type().notNull(),
+    entityId: (0, pg_core_1.text)('entity_id').notNull(),
+    status: (0, pg_core_1.text)('status').$type().notNull(),
+    builtAt: (0, pg_core_1.timestamp)('built_at', { withTimezone: true }),
+    builderVersion: (0, pg_core_1.text)('builder_version'),
+    artifactHash: (0, pg_core_1.text)('artifact_hash'),
+    sourceHash: (0, pg_core_1.text)('source_hash'),
+    warnings: (0, pg_core_1.jsonb)('warnings').$type(),
+    error: (0, pg_core_1.text)('error'),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [(0, pg_core_1.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.
+ */
+exports.tokenSets = (0, pg_core_1.pgTable)('token_sets', {
+    /** Stable logical set id (`foundation/colors` | `component/button`). Join key across stores. */
+    id: (0, pg_core_1.text)('id').primaryKey(),
+    /** Set kind (`foundation` | `component`). */
+    kind: (0, pg_core_1.text)('kind').$type().notNull(),
+    /** Full extracted token slice (`IColorObject[]`/…/`IFileComponentObject`). */
+    record: (0, pg_core_1.jsonb)('record').notNull(),
+    /** Deterministic content hash over the record + generated artifacts (drives skip-unchanged). */
+    sourceHash: (0, pg_core_1.text)('source_hash'),
+    /** Build/publish status for the set. */
+    status: (0, pg_core_1.text)('status').$type(),
+    builtAt: (0, pg_core_1.timestamp)('built_at', { withTimezone: true }),
+    builderVersion: (0, pg_core_1.text)('builder_version'),
+    /** Registry-only review/catalog metadata (parity with other entities; management-API only). */
+    metadata: (0, pg_core_1.jsonb)('metadata').$type(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [(0, pg_core_1.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()`.
+ */
+exports.tokenArtifacts = (0, pg_core_1.pgTable)('token_artifacts', {
+    tokenSetId: (0, pg_core_1.text)('token_set_id')
+        .notNull()
+        .references(() => exports.tokenSets.id, { onDelete: 'cascade' }),
+    /** Registry-safe relative output path (e.g. `css/colors.css`, `sd/button/button.tokens.json`). */
+    path: (0, pg_core_1.text)('path').notNull(),
+    /** Logical format label (`css`|`scss`|`types`|`styleDictionary`|custom outDir). */
+    format: (0, pg_core_1.text)('format').notNull(),
+    /** Inline content; null when stored externally via `storageRef`. */
+    content: (0, pg_core_1.text)('content'),
+    /** Reference to externally stored content (future object storage). */
+    storageRef: (0, pg_core_1.text)('storage_ref'),
+    contentType: (0, pg_core_1.text)('content_type').notNull(),
+    hash: (0, pg_core_1.text)('hash'),
+    size: (0, pg_core_1.integer)('size'),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [(0, pg_core_1.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.
+ */
+exports.assetCollections = (0, pg_core_1.pgTable)('asset_collections', {
+    /** Stable collection id (`icons`|`logos`|`fonts`). Join key across stores. */
+    collection: (0, pg_core_1.text)('collection').primaryKey(),
+    /** Deterministic content hash over the collection's `(path, contentHash)` manifest (skip-unchanged). */
+    sourceHash: (0, pg_core_1.text)('source_hash'),
+    /** Build/publish status for the collection. */
+    status: (0, pg_core_1.text)('status').$type(),
+    builtAt: (0, pg_core_1.timestamp)('built_at', { withTimezone: true }),
+    builderVersion: (0, pg_core_1.text)('builder_version'),
+    /** Registry-only review/catalog metadata (parity with other entities; management-API only). */
+    metadata: (0, pg_core_1.jsonb)('metadata').$type(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.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.
+ */
+exports.assets = (0, pg_core_1.pgTable)('assets', {
+    collection: (0, pg_core_1.text)('collection')
+        .notNull()
+        .references(() => exports.assetCollections.collection, { onDelete: 'cascade' }),
+    /** Registry-safe logical path within the collection (e.g. `assets/icons/add.svg`, `icons.zip`). */
+    path: (0, pg_core_1.text)('path').notNull(),
+    /** Human-facing asset name. */
+    name: (0, pg_core_1.text)('name').notNull(),
+    contentType: (0, pg_core_1.text)('content_type').notNull(),
+    size: (0, pg_core_1.integer)('size'),
+    /** SHA-256 of the asset bytes - the blob identity, and the ETag for content responses. */
+    contentHash: (0, pg_core_1.text)('content_hash').notNull(),
+    /** Free-form asset metadata carried from extraction (icon index, description, …). */
+    metadata: (0, pg_core_1.jsonb)('metadata'),
+    /** References {@link assetBlobs.hash}; equals `contentHash`. */
+    blobHash: (0, pg_core_1.text)('blob_hash')
+        .notNull()
+        .references(() => exports.assetBlobs.hash),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: (0, pg_core_1.timestamp)('updated_at', { withTimezone: true }).notNull().defaultNow(),
+}, (table) => [(0, pg_core_1.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.
+ */
+exports.assetBlobs = (0, pg_core_1.pgTable)('asset_blobs', {
+    /** SHA-256 of the blob bytes (hex). */
+    hash: (0, pg_core_1.text)('hash').primaryKey(),
+    /** Which storage backed this blob when it was written (`database`|`vercel-blob`|custom id). */
+    storageProvider: (0, pg_core_1.text)('storage_provider').$type().notNull(),
+    /** Inline bytes; null when stored externally via `storageRef`. */
+    content: bytea('content'),
+    /** External object reference/key; null when stored inline in `content`. */
+    storageRef: (0, pg_core_1.text)('storage_ref'),
+    contentType: (0, pg_core_1.text)('content_type').notNull(),
+    size: (0, pg_core_1.integer)('size').notNull(),
+    createdAt: (0, pg_core_1.timestamp)('created_at', { withTimezone: true }).notNull().defaultNow(),
+});
+/** All registry tables, for typed Drizzle clients and migration tooling. */
+exports.registrySchema = {
+    components: exports.components,
+    componentFiles: exports.componentFiles,
+    patterns: exports.patterns,
+    patternFiles: exports.patternFiles,
+    pages: exports.pages,
+    pageFiles: exports.pageFiles,
+    docsArtifacts: exports.docsArtifacts,
+    buildMetadata: exports.buildMetadata,
+    tokenSets: exports.tokenSets,
+    tokenArtifacts: exports.tokenArtifacts,
+    assetCollections: exports.assetCollections,
+    assets: exports.assets,
+    assetBlobs: exports.assetBlobs,
+};

package/dist/registry/path.d.ts

@@ -0,0 +1,4 @@
+export declare const isSafeRelativePath: (value: string) => boolean;
+export declare const normalizeRelativePath: (value: string) => string;
+export declare const isSafePathSegment: (value: string) => boolean;
+export declare const resolvePathWithin: (root: string, value: string) => string | null;

package/dist/registry/path.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolvePathWithin = exports.isSafePathSegment = exports.normalizeRelativePath = exports.isSafeRelativePath = void 0;
+const path_1 = __importDefault(require("path"));
+const isSafeRelativePath = (value) => {
+    if (typeof value !== 'string' || value.trim() === '') {
+        return false;
+    }
+    const normalized = (0, exports.normalizeRelativePath)(value);
+    if (normalized.startsWith('/') || /^[a-zA-Z]:/.test(normalized)) {
+        return false;
+    }
+    return normalized.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..');
+};
+exports.isSafeRelativePath = isSafeRelativePath;
+const normalizeRelativePath = (value) => value.replace(/\\/g, '/');
+exports.normalizeRelativePath = normalizeRelativePath;
+const isSafePathSegment = (value) => typeof value === 'string' && value === value.trim() && (0, exports.isSafeRelativePath)(value) && !(0, exports.normalizeRelativePath)(value).includes('/');
+exports.isSafePathSegment = isSafePathSegment;
+const resolvePathWithin = (root, value) => {
+    if (!(0, exports.isSafeRelativePath)(value)) {
+        return null;
+    }
+    const absolutePath = path_1.default.resolve(root, ...(0, exports.normalizeRelativePath)(value).split('/'));
+    const relativePath = path_1.default.relative(root, absolutePath);
+    return relativePath.startsWith('..') || path_1.default.isAbsolute(relativePath) ? null : absolutePath;
+};
+exports.resolvePathWithin = resolvePathWithin;

package/dist/registry/publish/artifacts.d.ts

@@ -0,0 +1,16 @@
+import Handoff from '../../index';
+import type { TransferArtifact } from '../transfer';
+/** Absolute path of the generated artifact root the build writes to (`<workspace>/public/api`). */
+export declare const getArtifactRoot: (handoff: Handoff) => string;
+export declare const isSharedArtifactPath: (artifactPath: string) => boolean;
+/**
+ * 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 declare const resolveComponentArtifactOwner: (fileName: string, componentIds: Set<string>) => string | null;
+/** Read a generated artifact file into a {@link TransferArtifact}, or `null` when it does not exist. */
+export declare const readArtifact: (root: string, artifactPath: string, ownerKind: TransferArtifact["ownerKind"], ownerId: string | null) => TransferArtifact | null;
+/** Add a referenced shared/component artifact to the map when present on disk (deduped by path). */
+export declare const addReferencedArtifact: (root: string, artifactPath: string, byPath: Map<string, TransferArtifact>) => void;

package/dist/registry/publish/artifacts.js

@@ -0,0 +1,132 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addReferencedArtifact = exports.readArtifact = exports.resolveComponentArtifactOwner = exports.isSharedArtifactPath = exports.getArtifactRoot = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const artifacts_1 = require("../../artifacts");
+const SHARED_ARTIFACT_PATHS = new Set([artifacts_1.SHARED_MAIN_CSS_ARTIFACT_PATH, artifacts_1.SHARED_MAIN_JS_ARTIFACT_PATH, artifacts_1.SHARED_STYLES_CSS_ARTIFACT_PATH]);
+const CLIENT_ARTIFACT_SUFFIX = '.client.js';
+const ARTIFACT_KIND_BY_EXT = {
+    '.json': 'json',
+    '.html': 'html',
+    '.css': 'css',
+    '.js': 'javascript',
+};
+const CONTENT_TYPE_BY_EXT = {
+    '.json': 'application/json',
+    '.html': 'text/html; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+};
+const artifactKindForPath = (artifactPath) => { var _a; return (_a = ARTIFACT_KIND_BY_EXT[path_1.default.extname(artifactPath).toLowerCase()]) !== null && _a !== void 0 ? _a : 'other'; };
+const contentTypeForPath = (artifactPath) => { var _a; return (_a = CONTENT_TYPE_BY_EXT[path_1.default.extname(artifactPath).toLowerCase()]) !== null && _a !== void 0 ? _a : 'text/plain; charset=utf-8'; };
+/** Absolute path of the generated artifact root the build writes to (`<workspace>/public/api`). */
+const getArtifactRoot = (handoff) => path_1.default.resolve(handoff.workingPath, 'public', 'api');
+exports.getArtifactRoot = getArtifactRoot;
+const isSharedArtifactPath = (artifactPath) => SHARED_ARTIFACT_PATHS.has(artifactPath);
+exports.isSharedArtifactPath = isSharedArtifactPath;
+/**
+ * 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`.
+ */
+const resolveComponentArtifactOwner = (fileName, componentIds) => {
+    if ((0, exports.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_1.default.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 = null;
+        for (const id of Array.from(componentIds)) {
+            if (fileName.startsWith(`${id}-`) && (!longest || id.length > longest.length)) {
+                longest = id;
+            }
+        }
+        return longest;
+    }
+    return null;
+};
+exports.resolveComponentArtifactOwner = resolveComponentArtifactOwner;
+/** Extract the logical artifact paths an HTML document references through the canonical route. */
+const extractReferencedArtifactPaths = (html) => {
+    const pattern = new RegExp(`(?:href|src)=["'][^"']*?${artifacts_1.ARTIFACTS_ROUTE_SEGMENT}/([^"']+)["']`, 'g');
+    const paths = new Set();
+    let match;
+    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 (_a) {
+            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) => {
+    if (referencedPath.endsWith(CLIENT_ARTIFACT_SUFFIX)) {
+        const ownerId = path_1.default.basename(referencedPath).slice(0, -CLIENT_ARTIFACT_SUFFIX.length);
+        return { path: referencedPath, kind: 'client', required: true, ownerKind: 'component', ownerId };
+    }
+    if ((0, exports.isSharedArtifactPath)(referencedPath)) {
+        return { path: referencedPath, kind: 'shared', required: false, ownerKind: 'asset', ownerId: null };
+    }
+    const ext = path_1.default.extname(referencedPath).toLowerCase();
+    if (referencedPath.startsWith('component/') && (ext === '.css' || ext === '.js')) {
+        const ownerId = path_1.default.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. */
+const readArtifact = (root, artifactPath, ownerKind, ownerId) => {
+    const absolutePath = path_1.default.resolve(root, ...artifactPath.split('/'));
+    if (!fs_extra_1.default.existsSync(absolutePath) || !fs_extra_1.default.statSync(absolutePath).isFile()) {
+        return null;
+    }
+    const content = fs_extra_1.default.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'),
+    };
+};
+exports.readArtifact = readArtifact;
+/** Add a referenced shared/component artifact to the map when present on disk (deduped by path). */
+const addReferencedArtifact = (root, artifactPath, byPath) => {
+    var _a, _b;
+    if (byPath.has(artifactPath)) {
+        return;
+    }
+    const reference = toArtifactReference(artifactPath);
+    const ownerKind = (_a = reference.ownerKind) !== null && _a !== void 0 ? _a : ((0, exports.isSharedArtifactPath)(artifactPath) ? 'asset' : 'component');
+    const ownerId = reference.ownerKind === 'asset' ? null : ((_b = reference.ownerId) !== null && _b !== void 0 ? _b : null);
+    const artifact = (0, exports.readArtifact)(root, artifactPath, ownerKind, ownerId);
+    if (artifact) {
+        byPath.set(artifactPath, artifact);
+    }
+};
+exports.addReferencedArtifact = addReferencedArtifact;

package/dist/registry/publish/assets.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Connected-workspace asset publish orchestration.
+ *
+ * `publish assets [collection]` runs a fresh build (`handoff.fetch()`), discovers the collections, and
+ * uploads each changed one. A collection is skipped when its deterministic `sourceHash` is unchanged;
+ * content transfers blob-by-blob (only hashes the registry lacks, since content-addressed dedup is the
+ * per-blob skip-unchanged), and the manifest is finalized atomically only after its blobs exist.
+ */
+import Handoff from '../../index';
+/**
+ * Publish all discovered asset collections, or a single collection when `collection` is given. Runs a
+ * fresh build, skips collections whose content is unchanged on the registry, uploads only missing
+ * blobs, and finalizes each manifest atomically. Reports published/unchanged/uploaded/failed counts;
+ * throws at the end if any collection failed.
+ */
+export declare const publishAssets: (handoff: Handoff, collection?: string) => Promise<void>;