handoff-app 1.2.2-7 → 2.0.0-0

package/dist/store/filesystem.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 type { ComponentListObject, PageListObject, PatternListObject } from '../transformers/preview/types';
+import type { Config, RuntimeConfig } from '../types/config';
+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;
+}
+export declare class FilesystemComponentStore implements ComponentStore {
+    private readonly context;
+    constructor(context: FilesystemStoreContext);
+    private get records();
+    list(): ComponentListObject[];
+    get(id: string): ComponentListObject | null;
+    getSource(ref: SourceReference): TextFileResource | null;
+    getRelatedSourceFiles(id: string): TextFileResource[];
+}
+export declare class FilesystemPatternStore implements PatternStore {
+    private readonly context;
+    constructor(context: FilesystemStoreContext);
+    private get records();
+    list(): PatternListObject[];
+    get(id: string): PatternListObject | null;
+    getSource(ref: SourceReference): TextFileResource | null;
+    getRelatedSourceFiles(id: string): TextFileResource[];
+}
+export declare class FilesystemPageStore implements PageStore {
+    private readonly context;
+    constructor(context: FilesystemStoreContext);
+    private get records();
+    list(): PageListObject[];
+    get(id: string): PageListObject | null;
+    getSource(ref: SourceReference): TextFileResource | null;
+    getRelatedSourceFiles(id: string): TextFileResource[];
+}
+export declare const tokenArtifactContentType: (artifactPath: string) => string;
+/**
+ * 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 declare class FilesystemTokenStore implements TokenStore {
+    private readonly context;
+    constructor(context: FilesystemStoreContext);
+    private readDocument;
+    listSets(): TokenSetRecord[];
+    getSet(id: string): TokenSetRecord | null;
+    getArtifacts(id: string): TokenArtifactResource[];
+    getArtifact(id: string, format: string): TokenArtifactResource | null;
+}

package/dist/store/filesystem.js

@@ -0,0 +1,208 @@
+"use strict";
+/**
+ * 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.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilesystemTokenStore = exports.tokenArtifactContentType = exports.FilesystemPageStore = exports.FilesystemPatternStore = exports.FilesystemComponentStore = void 0;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const token_transformers_1 = require("../pipeline/token-transformers");
+const sets_1 = require("../registry/tokens/sets");
+const source_files_1 = require("./source-files");
+const readSourceByReference = (ref) => {
+    const { absolutePath } = ref;
+    try {
+        if (!absolutePath || !fs_extra_1.default.existsSync(absolutePath) || !fs_extra_1.default.statSync(absolutePath).isFile()) {
+            return null;
+        }
+        return {
+            path: absolutePath,
+            absolutePath,
+            kind: 'other',
+            content: fs_extra_1.default.readFileSync(absolutePath, 'utf8'),
+            contentType: (0, source_files_1.sourceContentTypeForPath)(absolutePath),
+        };
+    }
+    catch (_a) {
+        return null;
+    }
+};
+class FilesystemComponentStore {
+    constructor(context) {
+        this.context = context;
+    }
+    get records() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.context.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.components) !== null && _c !== void 0 ? _c : {};
+    }
+    list() {
+        return Object.values(this.records);
+    }
+    get(id) {
+        var _a;
+        return (_a = this.records[id]) !== null && _a !== void 0 ? _a : null;
+    }
+    getSource(ref) {
+        return readSourceByReference(ref);
+    }
+    getRelatedSourceFiles(id) {
+        const record = this.records[id];
+        if (!record)
+            return [];
+        return (0, source_files_1.getRelatedSourceFilesForRecord)(record);
+    }
+}
+exports.FilesystemComponentStore = FilesystemComponentStore;
+class FilesystemPatternStore {
+    constructor(context) {
+        this.context = context;
+    }
+    get records() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.context.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.patterns) !== null && _c !== void 0 ? _c : {};
+    }
+    list() {
+        return Object.values(this.records);
+    }
+    get(id) {
+        var _a;
+        return (_a = this.records[id]) !== null && _a !== void 0 ? _a : null;
+    }
+    getSource(ref) {
+        return readSourceByReference(ref);
+    }
+    getRelatedSourceFiles(id) {
+        const record = this.records[id];
+        if (!record)
+            return [];
+        return (0, source_files_1.getRelatedSourceFilesForRecord)(record);
+    }
+}
+exports.FilesystemPatternStore = FilesystemPatternStore;
+/**
+ * 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) => {
+    const absolutePath = record.sourcePath;
+    try {
+        if (!absolutePath || !fs_extra_1.default.existsSync(absolutePath) || !fs_extra_1.default.statSync(absolutePath).isFile()) {
+            return null;
+        }
+        return {
+            path: `${record.id}.md`,
+            absolutePath,
+            kind: 'markdown',
+            content: fs_extra_1.default.readFileSync(absolutePath, 'utf8'),
+            contentType: 'text/markdown; charset=utf-8',
+        };
+    }
+    catch (_a) {
+        return null;
+    }
+};
+class FilesystemPageStore {
+    constructor(context) {
+        this.context = context;
+    }
+    get records() {
+        var _a, _b, _c;
+        return (_c = (_b = (_a = this.context.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entries) === null || _b === void 0 ? void 0 : _b.pages) !== null && _c !== void 0 ? _c : {};
+    }
+    list() {
+        return Object.values(this.records);
+    }
+    get(id) {
+        var _a;
+        return (_a = this.records[id]) !== null && _a !== void 0 ? _a : null;
+    }
+    getSource(ref) {
+        return readSourceByReference(ref);
+    }
+    getRelatedSourceFiles(id) {
+        const record = this.records[id];
+        if (!record)
+            return [];
+        const resource = readPageSource(record);
+        return resource ? [resource] : [];
+    }
+}
+exports.FilesystemPageStore = FilesystemPageStore;
+/** Content type for a generated token artifact, keyed by extension. */
+const CONTENT_TYPE_BY_EXT = {
+    '.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',
+};
+const tokenArtifactContentType = (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'; };
+exports.tokenArtifactContentType = tokenArtifactContentType;
+/**
+ * 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.
+ */
+class FilesystemTokenStore {
+    constructor(context) {
+        this.context = context;
+    }
+    readDocument() {
+        var _a, _b;
+        const tokensFilePath = (_b = (_a = this.context).getTokensFilePath) === null || _b === void 0 ? void 0 : _b.call(_a);
+        if (!tokensFilePath || !fs_extra_1.default.existsSync(tokensFilePath)) {
+            return [];
+        }
+        try {
+            const doc = JSON.parse(fs_extra_1.default.readFileSync(tokensFilePath, 'utf8'));
+            return (0, sets_1.deriveTokenSets)(doc);
+        }
+        catch (_c) {
+            return [];
+        }
+    }
+    listSets() {
+        return this.readDocument().map(({ id, kind, record }) => ({ id, kind, record }));
+    }
+    getSet(id) {
+        var _a;
+        return (_a = this.listSets().find((set) => set.id === id)) !== null && _a !== void 0 ? _a : null;
+    }
+    getArtifacts(id) {
+        var _a, _b;
+        const baseDir = (_b = (_a = this.context).getVariablesFilePath) === null || _b === void 0 ? void 0 : _b.call(_a);
+        if (!baseDir || !this.getSet(id)) {
+            return [];
+        }
+        const transformers = (0, token_transformers_1.resolveTokenTransformers)(this.context);
+        const layouts = (0, token_transformers_1.tokenArtifactPathsForSet)(transformers, (0, sets_1.setNameForId)(id), (0, sets_1.isComponentSet)(id));
+        const resources = [];
+        for (const layout of layouts) {
+            const absolutePath = path_1.default.resolve(baseDir, ...layout.path.split('/'));
+            if (!fs_extra_1.default.existsSync(absolutePath) || !fs_extra_1.default.statSync(absolutePath).isFile()) {
+                continue;
+            }
+            resources.push({
+                path: layout.path,
+                format: layout.format,
+                content: fs_extra_1.default.readFileSync(absolutePath, 'utf8'),
+                contentType: (0, exports.tokenArtifactContentType)(layout.path),
+            });
+        }
+        return resources;
+    }
+    getArtifact(id, format) {
+        var _a;
+        return (_a = this.getArtifacts(id).find((artifact) => artifact.format === format)) !== null && _a !== void 0 ? _a : null;
+    }
+}
+exports.FilesystemTokenStore = FilesystemTokenStore;

package/dist/store/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 { type FilesystemStoreContext } from './filesystem';
+import type { HandoffStore } from './types';
+/**
+ * Build the filesystem-backed store set for a runtime context (a `Handoff` instance satisfies
+ * {@link FilesystemStoreContext}).
+ */
+export declare const createFilesystemStore: (context: FilesystemStoreContext) => HandoffStore;

package/dist/store/index.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createFilesystemStore = exports.sourceContentTypeForPath = exports.isWorkspaceOnlyFile = exports.isRegistrySourceFile = exports.getRelatedSourceFilesForRecord = exports.FilesystemAssetStore = exports.FilesystemTokenStore = exports.FilesystemPatternStore = exports.FilesystemPageStore = exports.FilesystemComponentStore = void 0;
+var filesystem_1 = require("./filesystem");
+Object.defineProperty(exports, "FilesystemComponentStore", { enumerable: true, get: function () { return filesystem_1.FilesystemComponentStore; } });
+Object.defineProperty(exports, "FilesystemPageStore", { enumerable: true, get: function () { return filesystem_1.FilesystemPageStore; } });
+Object.defineProperty(exports, "FilesystemPatternStore", { enumerable: true, get: function () { return filesystem_1.FilesystemPatternStore; } });
+Object.defineProperty(exports, "FilesystemTokenStore", { enumerable: true, get: function () { return filesystem_1.FilesystemTokenStore; } });
+var filesystem_assets_1 = require("./filesystem-assets");
+Object.defineProperty(exports, "FilesystemAssetStore", { enumerable: true, get: function () { return filesystem_assets_1.FilesystemAssetStore; } });
+var source_files_1 = require("./source-files");
+Object.defineProperty(exports, "getRelatedSourceFilesForRecord", { enumerable: true, get: function () { return source_files_1.getRelatedSourceFilesForRecord; } });
+Object.defineProperty(exports, "isRegistrySourceFile", { enumerable: true, get: function () { return source_files_1.isRegistrySourceFile; } });
+Object.defineProperty(exports, "isWorkspaceOnlyFile", { enumerable: true, get: function () { return source_files_1.isWorkspaceOnlyFile; } });
+Object.defineProperty(exports, "sourceContentTypeForPath", { enumerable: true, get: function () { return source_files_1.sourceContentTypeForPath; } });
+const filesystem_2 = require("./filesystem");
+const filesystem_assets_2 = require("./filesystem-assets");
+/**
+ * Build the filesystem-backed store set for a runtime context (a `Handoff` instance satisfies
+ * {@link FilesystemStoreContext}).
+ */
+const createFilesystemStore = (context) => ({
+    components: new filesystem_2.FilesystemComponentStore(context),
+    patterns: new filesystem_2.FilesystemPatternStore(context),
+    pages: new filesystem_2.FilesystemPageStore(context),
+    tokens: new filesystem_2.FilesystemTokenStore(context),
+    assets: new filesystem_assets_2.FilesystemAssetStore(context),
+});
+exports.createFilesystemStore = createFilesystemStore;

package/dist/store/registry.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 type { AssetStorage } from '../registry/asset-storage/types';
+import type { RegistryDatabase } from '../registry/db/client';
+import { type AssetStorageProvider } from '../registry/db/schema';
+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>;
+}
+export declare class RegistryComponentStore implements ComponentStore {
+    private readonly context;
+    constructor(context: RegistryStoreContext);
+    list(): Promise<ComponentListObject[]>;
+    get(id: string): Promise<ComponentListObject | 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}.
+     */
+    getSource(_ref: SourceReference): Promise<TextFileResource | null>;
+    getRelatedSourceFiles(id: string): Promise<TextFileResource[]>;
+}
+export declare class RegistryPatternStore implements PatternStore {
+    private readonly context;
+    constructor(context: RegistryStoreContext);
+    list(): Promise<PatternListObject[]>;
+    get(id: string): Promise<PatternListObject | null>;
+    getSource(_ref: SourceReference): Promise<TextFileResource | null>;
+    getRelatedSourceFiles(id: string): Promise<TextFileResource[]>;
+}
+export declare class RegistryPageStore implements PageStore {
+    private readonly context;
+    constructor(context: RegistryStoreContext);
+    list(): Promise<PageListObject[]>;
+    get(id: string): Promise<PageListObject | null>;
+    getSource(_ref: SourceReference): Promise<TextFileResource | null>;
+    getRelatedSourceFiles(id: string): Promise<TextFileResource[]>;
+}
+export declare class RegistryTokenStore implements TokenStore {
+    private readonly context;
+    constructor(context: RegistryStoreContext);
+    listSets(): Promise<TokenSetRecord[]>;
+    getSet(id: string): Promise<TokenSetRecord | null>;
+    getArtifacts(id: string): Promise<TokenArtifactResource[]>;
+    getArtifact(id: string, format: string): Promise<TokenArtifactResource | null>;
+}
+export declare class RegistryAssetStore implements AssetStore {
+    private readonly context;
+    constructor(context: RegistryStoreContext);
+    listCollections(): Promise<string[]>;
+    listAssets(collection: string): Promise<AssetMetadata[]>;
+    getAsset(collection: string, assetPath: string): Promise<AssetMetadata | null>;
+    getAssetContent(collection: string, assetPath: string): Promise<AssetContentResource | null>;
+}
+/** Build the database-backed store set for a registry database connection. */
+export declare const createRegistryStore: (context: RegistryStoreContext) => HandoffStore;