handoff-app 1.2.2-7 → 2.0.0-0

package/src/store/filesystem.ts

@@ -0,0 +1,237 @@
+/**
+ * Filesystem-backed implementation of the normalized store abstraction.
+ *
+ * It is a thin read view over the already-resolved `runtimeConfig.entries`, so the records it
+ * returns are the same normalized component/pattern records the build consumes today — discovery
+ * and normalization (modern `*.handoff.*` + legacy `{dirname}.*`, react/handlebars/csf/plain-object
+ * declarations, CSF story discovery, `entries` resolution) all happen upstream in
+ * `initRuntimeConfig`. The store adds the source-location and related-source-files accessors
+ * without changing how anything is discovered or built.
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { resolveTokenTransformers, tokenArtifactPathsForSet } from '../pipeline/token-transformers';
+import { deriveTokenSets, isComponentSet, setNameForId } from '../registry/tokens/sets';
+import type { ComponentListObject, PageListObject, PatternListObject } from '../transformers/preview/types';
+import type { Config, RuntimeConfig } from '../types/config';
+import { getRelatedSourceFilesForRecord, sourceContentTypeForPath } from './source-files';
+import type {
+  ComponentStore,
+  PageStore,
+  PatternStore,
+  SourceReference,
+  TextFileResource,
+  TokenArtifactResource,
+  TokenSetRecord,
+  TokenStore,
+} from './types';
+
+/**
+ * Minimal context needed to back the filesystem store. A `Handoff` instance satisfies this (it
+ * carries `runtimeConfig`/`config` and the token path accessors), so the store stays a thin read
+ * view without importing the `Handoff` class.
+ */
+export interface FilesystemStoreContext {
+  runtimeConfig?: RuntimeConfig | null;
+  config?: Config | null;
+  /** Workspace root (`Handoff.workingPath`), holding `public/` and `fonts/`. */
+  workingPath?: string;
+  /** Absolute path to the generated `tokens.json` (`Handoff.getTokensFilePath()`). */
+  getTokensFilePath?(): string;
+  /** Absolute path to the generated tokens output dir (`Handoff.getVariablesFilePath()`). */
+  getVariablesFilePath?(): string;
+  /** Absolute path to the docs API root `public/api` (`Handoff.getAssetsApiPath()`). */
+  getAssetsApiPath?(): string;
+  /** Absolute path of `icons.zip` (`Handoff.getIconsZipFilePath()`). */
+  getIconsZipFilePath?(): string;
+  /** Absolute path of `logos.zip` (`Handoff.getLogosZipFilePath()`). */
+  getLogosZipFilePath?(): string;
+}
+
+const readSourceByReference = (ref: SourceReference): TextFileResource | null => {
+  const { absolutePath } = ref;
+  try {
+    if (!absolutePath || !fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+      return null;
+    }
+    return {
+      path: absolutePath,
+      absolutePath,
+      kind: 'other',
+      content: fs.readFileSync(absolutePath, 'utf8'),
+      contentType: sourceContentTypeForPath(absolutePath),
+    };
+  } catch {
+    return null;
+  }
+};
+
+export class FilesystemComponentStore implements ComponentStore {
+  constructor(private readonly context: FilesystemStoreContext) {}
+
+  private get records(): Record<string, ComponentListObject> {
+    return this.context.runtimeConfig?.entries?.components ?? {};
+  }
+
+  list(): ComponentListObject[] {
+    return Object.values(this.records);
+  }
+
+  get(id: string): ComponentListObject | null {
+    return this.records[id] ?? null;
+  }
+
+  getSource(ref: SourceReference): TextFileResource | null {
+    return readSourceByReference(ref);
+  }
+
+  getRelatedSourceFiles(id: string): TextFileResource[] {
+    const record = this.records[id];
+    if (!record) return [];
+    return getRelatedSourceFilesForRecord(record);
+  }
+}
+
+export class FilesystemPatternStore implements PatternStore {
+  constructor(private readonly context: FilesystemStoreContext) {}
+
+  private get records(): Record<string, PatternListObject> {
+    return this.context.runtimeConfig?.entries?.patterns ?? {};
+  }
+
+  list(): PatternListObject[] {
+    return Object.values(this.records);
+  }
+
+  get(id: string): PatternListObject | null {
+    return this.records[id] ?? null;
+  }
+
+  getSource(ref: SourceReference): TextFileResource | null {
+    return readSourceByReference(ref);
+  }
+
+  getRelatedSourceFiles(id: string): TextFileResource[] {
+    const record = this.records[id];
+    if (!record) return [];
+    return getRelatedSourceFilesForRecord(record);
+  }
+}
+
+/**
+ * Read a page's verbatim source `.md` as a registry-safe `markdown` resource. The registry-safe path
+ * is `${id}.md` (id may contain slashes for nested pages), which is also where checkout writes it.
+ */
+const readPageSource = (record: PageListObject): TextFileResource | null => {
+  const absolutePath = record.sourcePath;
+  try {
+    if (!absolutePath || !fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+      return null;
+    }
+    return {
+      path: `${record.id}.md`,
+      absolutePath,
+      kind: 'markdown',
+      content: fs.readFileSync(absolutePath, 'utf8'),
+      contentType: 'text/markdown; charset=utf-8',
+    };
+  } catch {
+    return null;
+  }
+};
+
+export class FilesystemPageStore implements PageStore {
+  constructor(private readonly context: FilesystemStoreContext) {}
+
+  private get records(): Record<string, PageListObject> {
+    return this.context.runtimeConfig?.entries?.pages ?? {};
+  }
+
+  list(): PageListObject[] {
+    return Object.values(this.records);
+  }
+
+  get(id: string): PageListObject | null {
+    return this.records[id] ?? null;
+  }
+
+  getSource(ref: SourceReference): TextFileResource | null {
+    return readSourceByReference(ref);
+  }
+
+  getRelatedSourceFiles(id: string): TextFileResource[] {
+    const record = this.records[id];
+    if (!record) return [];
+    const resource = readPageSource(record);
+    return resource ? [resource] : [];
+  }
+}
+
+/** Content type for a generated token artifact, keyed by extension. */
+const CONTENT_TYPE_BY_EXT: Record<string, string> = {
+  '.css': 'text/css; charset=utf-8',
+  '.scss': 'text/x-scss; charset=utf-8',
+  '.sass': 'text/x-sass; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+};
+
+export const tokenArtifactContentType = (artifactPath: string): string =>
+  CONTENT_TYPE_BY_EXT[path.extname(artifactPath).toLowerCase()] ?? 'text/plain; charset=utf-8';
+
+/**
+ * Filesystem-backed token store. Derives logical sets from the generated `tokens.json` and reads
+ * their generated artifacts from the tokens output dir using the shared transformer layout, so the
+ * paths it reads are exactly the ones `buildStyles` writes.
+ */
+export class FilesystemTokenStore implements TokenStore {
+  constructor(private readonly context: FilesystemStoreContext) {}
+
+  private readDocument(): ReturnType<typeof deriveTokenSets> {
+    const tokensFilePath = this.context.getTokensFilePath?.();
+    if (!tokensFilePath || !fs.existsSync(tokensFilePath)) {
+      return [];
+    }
+    try {
+      const doc = JSON.parse(fs.readFileSync(tokensFilePath, 'utf8'));
+      return deriveTokenSets(doc);
+    } catch {
+      return [];
+    }
+  }
+
+  listSets(): TokenSetRecord[] {
+    return this.readDocument().map(({ id, kind, record }) => ({ id, kind, record }));
+  }
+
+  getSet(id: string): TokenSetRecord | null {
+    return this.listSets().find((set) => set.id === id) ?? null;
+  }
+
+  getArtifacts(id: string): TokenArtifactResource[] {
+    const baseDir = this.context.getVariablesFilePath?.();
+    if (!baseDir || !this.getSet(id)) {
+      return [];
+    }
+    const transformers = resolveTokenTransformers(this.context);
+    const layouts = tokenArtifactPathsForSet(transformers, setNameForId(id), isComponentSet(id));
+    const resources: TokenArtifactResource[] = [];
+    for (const layout of layouts) {
+      const absolutePath = path.resolve(baseDir, ...layout.path.split('/'));
+      if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+        continue;
+      }
+      resources.push({
+        path: layout.path,
+        format: layout.format,
+        content: fs.readFileSync(absolutePath, 'utf8'),
+        contentType: tokenArtifactContentType(layout.path),
+      });
+    }
+    return resources;
+  }
+
+  getArtifact(id: string, format: string): TokenArtifactResource | null {
+    return this.getArtifacts(id).find((artifact) => artifact.format === format) ?? null;
+  }
+}

package/src/store/index.ts

@@ -0,0 +1,62 @@
+/**
+ * Normalized store abstraction.
+ *
+ * The workspace (filesystem) store is exported here. The registry (database) store implements the
+ * same interface in `./registry`, but is intentionally **not** re-exported from this barrel so the
+ * Drizzle/Postgres dependencies it pulls in stay out of the workspace/static path — registry
+ * consumers import `@handoff/store/registry` directly (and lazily). Consumers depend only on the
+ * interfaces exported here so they remain storage-agnostic.
+ */
+
+export type {
+  AssetContentResource,
+  AssetMetadata,
+  AssetStore,
+  Awaitable,
+  ComponentStore,
+  HandoffStore,
+  PageStore,
+  PatternStore,
+  RegistryTextFileKind,
+  RegistryTextFileResource,
+  SourceReference,
+  TextFileKind,
+  TextFileResource,
+  TokenArtifactResource,
+  TokenSetRecord,
+  TokenStore,
+} from './types';
+
+export {
+  FilesystemComponentStore,
+  FilesystemPageStore,
+  FilesystemPatternStore,
+  FilesystemTokenStore,
+  type FilesystemStoreContext,
+} from './filesystem';
+
+export { FilesystemAssetStore } from './filesystem-assets';
+
+export { getRelatedSourceFilesForRecord, isRegistrySourceFile, isWorkspaceOnlyFile, sourceContentTypeForPath } from './source-files';
+
+import {
+  FilesystemComponentStore,
+  FilesystemPageStore,
+  FilesystemPatternStore,
+  FilesystemTokenStore,
+  type FilesystemStoreContext,
+} from './filesystem';
+import { FilesystemAssetStore } from './filesystem-assets';
+import type { HandoffStore } from './types';
+
+/**
+ * Build the filesystem-backed store set for a runtime context (a `Handoff` instance satisfies
+ * {@link FilesystemStoreContext}).
+ */
+export const createFilesystemStore = (context: FilesystemStoreContext): HandoffStore => ({
+  components: new FilesystemComponentStore(context),
+  patterns: new FilesystemPatternStore(context),
+  pages: new FilesystemPageStore(context),
+  tokens: new FilesystemTokenStore(context),
+  assets: new FilesystemAssetStore(context),
+});

package/src/store/registry.ts

@@ -0,0 +1,334 @@
+/**
+ * Database-backed implementation of the normalized store abstraction.
+ *
+ * Registry mode serves only what was published to it: this store reads normalized component and
+ * pattern records — and their checkout/inspection source files — straight from the registry
+ * database. It is the registry counterpart to {@link FilesystemComponentStore},
+ * so the docs read API and other consumers stay storage-agnostic.
+ *
+ * Two invariants hold here that the filesystem store does not enforce:
+ * - Filesystem workspace declarations are never loaded as registry content; declarations are
+ *   workspace-only (synthesized on checkout) and the registry text-file tables reject the
+ *   `declaration` kind at the schema level, so they can never surface through this store.
+ * - Reads never materialize source files or run the build pipeline — every record and file is
+ *   returned exactly as it was published.
+ */
+
+import { and, eq } from 'drizzle-orm';
+import type { AssetStorage, AssetStorageReadResult } from '../registry/asset-storage/types';
+import type { RegistryDatabase } from '../registry/db/client';
+import {
+  assetBlobs,
+  assetCollections,
+  assets,
+  componentFiles,
+  components,
+  pageFiles,
+  pages,
+  patternFiles,
+  patterns,
+  tokenArtifacts,
+  tokenSets,
+  type AssetStorageProvider,
+} from '../registry/db/schema';
+import type { TokenSetKind } from '../registry/tokens/sets';
+import type { ComponentListObject, PageListObject, PatternListObject } from '../transformers/preview/types';
+import type {
+  AssetContentResource,
+  AssetMetadata,
+  AssetStore,
+  ComponentStore,
+  HandoffStore,
+  PageStore,
+  PatternStore,
+  SourceReference,
+  TextFileResource,
+  TokenArtifactResource,
+  TokenSetRecord,
+  TokenStore,
+} from './types';
+
+/** Minimal context needed to back a registry store: a live, typed Drizzle database. */
+export interface RegistryStoreContext {
+  db: RegistryDatabase;
+  /**
+   * Resolve the {@link AssetStorage} adapter for a blob's recorded provider (or `null` for the inline
+   * `database` provider). Injected by the app runtime so `src/store` stays free of app-side imports;
+   * when omitted, only inline DB-backed asset content is resolvable.
+   */
+  resolveAssetAdapter?: (provider: AssetStorageProvider) => Promise<AssetStorage | null>;
+}
+
+/** A persisted text-file row, as selected from `component_files`/`pattern_files`. */
+type RegistryFileRow = {
+  path: string;
+  kind: TextFileResource['kind'];
+  content: string | null;
+  contentType: string;
+};
+
+/**
+ * Map a persisted file row to a {@link TextFileResource}. Rows whose content is stored externally
+ * (a future object-storage `storageRef` with no inline `content`) are skipped — there is nothing to
+ * return inline for them yet. Registry records have no filesystem location, so `absolutePath` is
+ * empty (it is documented as workspace-store-only on the type).
+ */
+const toTextFileResource = (row: RegistryFileRow): TextFileResource | null => {
+  if (row.content == null) {
+    return null;
+  }
+  return {
+    path: row.path,
+    absolutePath: '',
+    kind: row.kind,
+    content: row.content,
+    contentType: row.contentType,
+  };
+};
+
+export class RegistryComponentStore implements ComponentStore {
+  constructor(private readonly context: RegistryStoreContext) {}
+
+  async list(): Promise<ComponentListObject[]> {
+    const rows = await this.context.db.select({ record: components.record }).from(components);
+    return rows.map((row) => row.record);
+  }
+
+  async get(id: string): Promise<ComponentListObject | null> {
+    const rows = await this.context.db
+      .select({ record: components.record })
+      .from(components)
+      .where(eq(components.id, id))
+      .limit(1);
+    return rows[0]?.record ?? null;
+  }
+
+  /**
+   * Registry source files are keyed by `(entity, path)`, not by an absolute filesystem path, so the
+   * filesystem-shaped {@link SourceReference} has no resolvable target here. Related files are read
+   * through {@link getRelatedSourceFiles}.
+   */
+  async getSource(_ref: SourceReference): Promise<TextFileResource | null> {
+    return null;
+  }
+
+  async getRelatedSourceFiles(id: string): Promise<TextFileResource[]> {
+    const rows = await this.context.db
+      .select({
+        path: componentFiles.path,
+        kind: componentFiles.kind,
+        content: componentFiles.content,
+        contentType: componentFiles.contentType,
+      })
+      .from(componentFiles)
+      .where(eq(componentFiles.componentId, id));
+    return rows.map(toTextFileResource).filter((file): file is TextFileResource => file !== null);
+  }
+}
+
+export class RegistryPatternStore implements PatternStore {
+  constructor(private readonly context: RegistryStoreContext) {}
+
+  async list(): Promise<PatternListObject[]> {
+    const rows = await this.context.db.select({ record: patterns.record }).from(patterns);
+    return rows.map((row) => row.record);
+  }
+
+  async get(id: string): Promise<PatternListObject | null> {
+    const rows = await this.context.db
+      .select({ record: patterns.record })
+      .from(patterns)
+      .where(eq(patterns.id, id))
+      .limit(1);
+    return rows[0]?.record ?? null;
+  }
+
+  async getSource(_ref: SourceReference): Promise<TextFileResource | null> {
+    return null;
+  }
+
+  async getRelatedSourceFiles(id: string): Promise<TextFileResource[]> {
+    const rows = await this.context.db
+      .select({
+        path: patternFiles.path,
+        kind: patternFiles.kind,
+        content: patternFiles.content,
+        contentType: patternFiles.contentType,
+      })
+      .from(patternFiles)
+      .where(eq(patternFiles.patternId, id));
+    return rows.map(toTextFileResource).filter((file): file is TextFileResource => file !== null);
+  }
+}
+
+export class RegistryPageStore implements PageStore {
+  constructor(private readonly context: RegistryStoreContext) {}
+
+  async list(): Promise<PageListObject[]> {
+    const rows = await this.context.db.select({ record: pages.record }).from(pages);
+    return rows.map((row) => row.record);
+  }
+
+  async get(id: string): Promise<PageListObject | null> {
+    const rows = await this.context.db.select({ record: pages.record }).from(pages).where(eq(pages.id, id)).limit(1);
+    return rows[0]?.record ?? null;
+  }
+
+  async getSource(_ref: SourceReference): Promise<TextFileResource | null> {
+    return null;
+  }
+
+  async getRelatedSourceFiles(id: string): Promise<TextFileResource[]> {
+    const rows = await this.context.db
+      .select({
+        path: pageFiles.path,
+        kind: pageFiles.kind,
+        content: pageFiles.content,
+        contentType: pageFiles.contentType,
+      })
+      .from(pageFiles)
+      .where(eq(pageFiles.pageId, id));
+    return rows.map(toTextFileResource).filter((file): file is TextFileResource => file !== null);
+  }
+}
+
+export class RegistryTokenStore implements TokenStore {
+  constructor(private readonly context: RegistryStoreContext) {}
+
+  async listSets(): Promise<TokenSetRecord[]> {
+    const rows = await this.context.db.select({ id: tokenSets.id, kind: tokenSets.kind, record: tokenSets.record }).from(tokenSets);
+    return rows.map((row) => ({ id: row.id, kind: row.kind as TokenSetKind, record: row.record }));
+  }
+
+  async getSet(id: string): Promise<TokenSetRecord | null> {
+    const rows = await this.context.db
+      .select({ id: tokenSets.id, kind: tokenSets.kind, record: tokenSets.record })
+      .from(tokenSets)
+      .where(eq(tokenSets.id, id))
+      .limit(1);
+    const row = rows[0];
+    return row ? { id: row.id, kind: row.kind as TokenSetKind, record: row.record } : null;
+  }
+
+  async getArtifacts(id: string): Promise<TokenArtifactResource[]> {
+    const rows = await this.context.db
+      .select({ path: tokenArtifacts.path, format: tokenArtifacts.format, content: tokenArtifacts.content, contentType: tokenArtifacts.contentType })
+      .from(tokenArtifacts)
+      .where(eq(tokenArtifacts.tokenSetId, id));
+    return rows
+      .filter((row) => row.content != null)
+      .map((row) => ({ path: row.path, format: row.format, content: row.content as string, contentType: row.contentType }));
+  }
+
+  async getArtifact(id: string, format: string): Promise<TokenArtifactResource | null> {
+    return (await this.getArtifacts(id)).find((artifact) => artifact.format === format) ?? null;
+  }
+}
+
+const readableToBuffer = async (stream: NodeJS.ReadableStream): Promise<Buffer> => {
+  const chunks: Buffer[] = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : typeof chunk === 'string' ? Buffer.from(chunk) : Buffer.from(chunk as unknown as Uint8Array));
+  }
+  return Buffer.concat(chunks);
+};
+
+export class RegistryAssetStore implements AssetStore {
+  constructor(private readonly context: RegistryStoreContext) {}
+
+  async listCollections(): Promise<string[]> {
+    const rows = await this.context.db.select({ collection: assetCollections.collection }).from(assetCollections);
+    return rows.map((row) => row.collection);
+  }
+
+  async listAssets(collection: string): Promise<AssetMetadata[]> {
+    const rows = await this.context.db
+      .select({
+        collection: assets.collection,
+        path: assets.path,
+        name: assets.name,
+        contentType: assets.contentType,
+        size: assets.size,
+        contentHash: assets.contentHash,
+        metadata: assets.metadata,
+      })
+      .from(assets)
+      .where(eq(assets.collection, collection));
+    return rows.map((row) => ({
+      collection: row.collection,
+      path: row.path,
+      name: row.name,
+      contentType: row.contentType,
+      size: row.size ?? 0,
+      contentHash: row.contentHash,
+      metadata: (row.metadata as Record<string, unknown> | null) ?? null,
+    }));
+  }
+
+  async getAsset(collection: string, assetPath: string): Promise<AssetMetadata | null> {
+    return (await this.listAssets(collection)).find((asset) => asset.path === assetPath) ?? null;
+  }
+
+  async getAssetContent(collection: string, assetPath: string): Promise<AssetContentResource | null> {
+    const rows = await this.context.db
+      .select({
+        name: assets.name,
+        contentType: assets.contentType,
+        size: assets.size,
+        contentHash: assets.contentHash,
+        metadata: assets.metadata,
+        blobContent: assetBlobs.content,
+        storageRef: assetBlobs.storageRef,
+        storageProvider: assetBlobs.storageProvider,
+      })
+      .from(assets)
+      .innerJoin(assetBlobs, eq(assets.blobHash, assetBlobs.hash))
+      .where(and(eq(assets.collection, collection), eq(assets.path, assetPath)))
+      .limit(1);
+    const row = rows[0];
+    if (!row) {
+      return null;
+    }
+
+    const base: AssetMetadata = {
+      collection,
+      path: assetPath,
+      name: row.name,
+      contentType: row.contentType,
+      size: row.size ?? 0,
+      contentHash: row.contentHash,
+      metadata: (row.metadata as Record<string, unknown> | null) ?? null,
+    };
+
+    // Inline (bytea, `database` provider) - return bytes directly.
+    if (row.blobContent != null) {
+      return { ...base, body: Buffer.from(row.blobContent as unknown as Uint8Array) };
+    }
+
+    // Object-backed - resolve through the provider that stored it.
+    if (!row.storageRef || !this.context.resolveAssetAdapter) {
+      return null;
+    }
+    const adapter = await this.context.resolveAssetAdapter(row.storageProvider);
+    if (!adapter) {
+      return null;
+    }
+    const result: AssetStorageReadResult = await adapter.get(row.storageRef);
+    if (result.kind === 'redirect') {
+      return { ...base, redirectUrl: result.url };
+    }
+    if (result.kind === 'bytes') {
+      return { ...base, body: result.bytes };
+    }
+    return { ...base, body: await readableToBuffer(result.stream) };
+  }
+}
+
+/** Build the database-backed store set for a registry database connection. */
+export const createRegistryStore = (context: RegistryStoreContext): HandoffStore => ({
+  components: new RegistryComponentStore(context),
+  patterns: new RegistryPatternStore(context),
+  pages: new RegistryPageStore(context),
+  tokens: new RegistryTokenStore(context),
+  assets: new RegistryAssetStore(context),
+});