handoff-app 1.2.2-6 → 2.0.0-0

package/dist/commands/publish/index.d.ts

@@ -0,0 +1,21 @@
+import { CommandModule } from 'yargs';
+import { SharedArgs } from '../types';
+/** Entity kinds publishable from a connected workspace. */
+declare const ENTITY_KINDS: readonly ["component", "pattern", "page", "tokens", "assets"];
+export interface PublishArgs extends SharedArgs {
+    type: (typeof ENTITY_KINDS)[number];
+    id?: string;
+}
+/**
+ * `handoff-app publish <component|pattern|page> <id>` — fresh targeted local build + upload of the
+ * selected entity to the connected registry.
+ *
+ * `handoff-app publish tokens [setId]` — fresh token build + upload of every logical token set, or
+ * only the named set (`foundation/colors`, `component/button`).
+ *
+ * `handoff-app publish assets [collection]` runs a fresh build and uploads every asset collection, or
+ * only the named one (`icons`, `logos`, `fonts`). Available only from a connected workspace
+ * (`runtime.mode: workspace` + a configured `registryConnection`).
+ */
+declare const command: CommandModule<{}, PublishArgs>;
+export default command;

package/dist/commands/publish/index.js

@@ -0,0 +1,68 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const __1 = __importDefault(require("../../"));
+const logger_1 = require("../../utils/logger");
+const utils_1 = require("../utils");
+/** Entity kinds publishable from a connected workspace. */
+const ENTITY_KINDS = ['component', 'pattern', 'page', 'tokens', 'assets'];
+/**
+ * `handoff-app publish <component|pattern|page> <id>` — fresh targeted local build + upload of the
+ * selected entity to the connected registry.
+ *
+ * `handoff-app publish tokens [setId]` — fresh token build + upload of every logical token set, or
+ * only the named set (`foundation/colors`, `component/button`).
+ *
+ * `handoff-app publish assets [collection]` runs a fresh build and uploads every asset collection, or
+ * only the named one (`icons`, `logos`, `fonts`). Available only from a connected workspace
+ * (`runtime.mode: workspace` + a configured `registryConnection`).
+ */
+const command = {
+    command: 'publish <type> [id]',
+    describe: 'Build and publish a component, pattern, page, design tokens, or assets to the connected registry',
+    builder: (yargs) => {
+        return (0, utils_1.getSharedOptions)(yargs)
+            .positional('type', {
+            describe: 'The kind of entity to publish',
+            choices: ENTITY_KINDS,
+            type: 'string',
+        })
+            .positional('id', {
+            describe: 'The stable id of the entity (component/pattern/page id, token set id, or asset collection); optional for tokens/assets',
+            type: 'string',
+        });
+    },
+    handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
+        const handoff = new __1.default(args.debug, args.force);
+        try {
+            if (args.type === 'tokens') {
+                yield handoff.publishTokens(args.id);
+                return;
+            }
+            if (args.type === 'assets') {
+                yield handoff.publishAssets(args.id);
+                return;
+            }
+            if (!args.id) {
+                throw new Error(`An id is required to publish a ${args.type} (e.g. "handoff-app publish ${args.type} <id>").`);
+            }
+            yield handoff.publish(args.type, args.id);
+        }
+        catch (error) {
+            logger_1.Logger.error(error instanceof Error ? error.message : String(error));
+            process.exitCode = 1;
+        }
+    }),
+};
+exports.default = command;

package/dist/config/defaults.js

@@ -1,11 +1,15 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getClientConfig = exports.defaultConfig = void 0;
+const connection_1 = require("../registry/connection");
 const defaultConfig = () => {
     var _a, _b, _c, _d;
     return ({
         dev_access_token: (_a = process.env.HANDOFF_DEV_ACCESS_TOKEN) !== null && _a !== void 0 ? _a : null,
         figma_project_id: (_b = process.env.HANDOFF_FIGMA_PROJECT_ID) !== null && _b !== void 0 ? _b : null,
+        runtime: {
+            mode: 'workspace',
+        },
         exportsOutputDirectory: (_c = process.env.HANDOFF_OUTPUT_DIR) !== null && _c !== void 0 ? _c : 'exported',
         sitesOutputDirectory: (_d = process.env.HANDOFF_SITES_DIR) !== null && _d !== void 0 ? _d : 'out',
         useVariables: process.env.HANDOFF_USE_VARIABLES === 'true',
@@ -56,13 +60,23 @@ exports.defaultConfig = defaultConfig;
  * @returns The client configuration object.
  */
 const getClientConfig = (config) => {
-    const { app, exportsOutputDirectory, sitesOutputDirectory, assets_zip_links = { icons: null, logos: null }, useVariables, } = Object.assign(Object.assign({}, (0, exports.defaultConfig)()), config);
+    var _a;
+    const { app, exportsOutputDirectory, sitesOutputDirectory, assets_zip_links = { icons: null, logos: null }, useVariables, runtime, } = Object.assign(Object.assign({}, (0, exports.defaultConfig)()), config);
+    const mode = (_a = runtime === null || runtime === void 0 ? void 0 : runtime.mode) !== null && _a !== void 0 ? _a : 'workspace';
+    // Connected-workspace affordance: only a workspace with a resolvable registry URL is "connected".
+    // URL-only threshold (no token required) so the publish hint surfaces before the access token is
+    // set. Never project the URL/token value itself — only this boolean crosses to the browser.
+    const connected = mode === 'workspace' && Boolean((0, connection_1.resolveRegistryConnection)(config).url);
     return {
         app,
         exportsOutputDirectory,
         sitesOutputDirectory,
         assets_zip_links,
         useVariables,
+        runtime: {
+            mode,
+            connected,
+        },
     };
 };
 exports.getClientConfig = getClientConfig;

package/dist/config/loader.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.initConfig = exports.initConfigWithMetadata = void 0;
 const esbuild_1 = __importDefault(require("esbuild"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
+const merge_1 = __importDefault(require("lodash/merge"));
 const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("../utils/logger");
@@ -94,7 +95,11 @@ const initConfigWithMetadata = (configOverride) => {
             }
         });
     }
-    const resolvedConfig = Object.assign(Object.assign({}, (0, defaults_1.defaultConfig)()), config);
+    const defaults = (0, defaults_1.defaultConfig)();
+    // Top-level merge stays shallow to preserve 1.x semantics, except for the `runtime`
+    // block which is deep-merged so a partial user `runtime` (e.g. only `mode`) does not
+    // wipe the defaults supplied for the rest of the block.
+    const resolvedConfig = Object.assign(Object.assign(Object.assign({}, defaults), config), { runtime: (0, merge_1.default)({}, defaults.runtime, config.runtime) });
     return { config: resolvedConfig, configPath };
 };
 exports.initConfigWithMetadata = initConfigWithMetadata;

package/dist/config/normalizers/declaration.js

@@ -114,6 +114,9 @@ const normalizeComponentDeclaration = (raw, options) => {
     }
     const normalizedPreviews = normalizePreviews(normalizedRaw.previews, options.declarationPath, options.warn);
     const explicitId = typeof normalizedRaw.id === 'string' && normalizedRaw.id.trim().length > 0 ? normalizedRaw.id.trim() : undefined;
-    return Object.assign(Object.assign({}, normalizedRaw), { id: explicitId || options.fallbackId, title: normalizedRaw.name || normalizedRaw.title || '', renderer: resolvedRenderer, entries, previews: normalizedPreviews });
+    return Object.assign(Object.assign({}, normalizedRaw), { id: explicitId || options.fallbackId, title: normalizedRaw.name || normalizedRaw.title || '', renderer: resolvedRenderer, entries, previews: normalizedPreviews, 
+        // Source location of the entity (declaration directory), retained so the store can expose a
+        // stable source reference for checkout/publish.
+        path: path_1.default.dirname(options.declarationPath) });
 };
 exports.normalizeComponentDeclaration = normalizeComponentDeclaration;

package/dist/config/normalizers/page.d.ts

@@ -0,0 +1,18 @@
+import { PageListObject } from '../../transformers/preview/types';
+type RawPageFrontmatter = Record<string, any>;
+type NormalizePageOptions = {
+    /** The page id — its slug path (e.g. `guides/setup`), derived from the file location. */
+    id: string;
+    /** Logical route the page is served at (e.g. `/guides/setup`). */
+    routePath: string;
+    /** Absolute filesystem path of the source `.md` (workspace-only, stripped on publish). */
+    sourcePath: string;
+};
+/**
+ * Normalize a page's parsed markdown frontmatter into a {@link PageListObject}. Pages have no
+ * required authored fields (a bare `.md` is valid); the title falls back to a humanized last slug
+ * segment. The id is always the slug path (a page is addressed by its URL, so id ≡ route): the file
+ * location is the single source of identity for both filesystem and registry serving.
+ */
+export declare const normalizePageDeclaration: (raw: RawPageFrontmatter, options: NormalizePageOptions) => PageListObject;
+export {};

package/dist/config/normalizers/page.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizePageDeclaration = void 0;
+/** Humanize a slug segment (`getting-started` → `Getting Started`) for a default title. */
+const humanize = (segment) => segment
+    .replace(/[-_]/g, ' ')
+    .replace(/\b\w/g, (c) => c.toUpperCase())
+    .trim();
+/**
+ * Normalize a page's parsed markdown frontmatter into a {@link PageListObject}. Pages have no
+ * required authored fields (a bare `.md` is valid); the title falls back to a humanized last slug
+ * segment. The id is always the slug path (a page is addressed by its URL, so id ≡ route): the file
+ * location is the single source of identity for both filesystem and registry serving.
+ */
+const normalizePageDeclaration = (raw, options) => {
+    var _a;
+    const lastSegment = (_a = options.id.split('/').pop()) !== null && _a !== void 0 ? _a : options.id;
+    return {
+        id: options.id,
+        path: options.routePath,
+        sourcePath: options.sourcePath,
+        title: typeof raw.title === 'string' && raw.title.trim() ? raw.title : humanize(lastSegment),
+        description: typeof raw.description === 'string' ? raw.description : undefined,
+        group: typeof raw.group === 'string' ? raw.group : undefined,
+        weight: typeof raw.weight === 'number' ? raw.weight : undefined,
+        menuTitle: typeof raw.menuTitle === 'string' ? raw.menuTitle : undefined,
+        metaTitle: typeof raw.metaTitle === 'string' ? raw.metaTitle : undefined,
+        metaDescription: typeof raw.metaDescription === 'string' ? raw.metaDescription : undefined,
+        enabled: typeof raw.enabled === 'boolean' ? raw.enabled : undefined,
+        external: typeof raw.external === 'string' || typeof raw.external === 'boolean' ? raw.external : undefined,
+        menu: raw.menu && typeof raw.menu === 'object' ? raw.menu : undefined,
+    };
+};
+exports.normalizePageDeclaration = normalizePageDeclaration;

package/dist/config/normalizers/pattern.js

@@ -1,6 +1,10 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizePatternDeclaration = void 0;
+const path_1 = __importDefault(require("path"));
 const normalizePatternDeclaration = (raw, options) => {
     if (!raw.name || typeof raw.name !== 'string') {
         throw new Error(`Pattern "${options.fallbackId}" in "${options.declarationPath}" is missing a required "name" field.`);
@@ -29,7 +33,9 @@ const normalizePatternDeclaration = (raw, options) => {
         group: typeof raw.group === 'string' ? raw.group : undefined,
         tags: Array.isArray(raw.tags) ? raw.tags.filter((t) => typeof t === 'string') : undefined,
         components,
-        path: '',
+        // Source location of the pattern (declaration directory), retained so the store can expose a
+        // stable source reference for checkout/publish.
+        path: path_1.default.dirname(options.declarationPath),
     };
 };
 exports.normalizePatternDeclaration = normalizePatternDeclaration;

package/dist/config/runtime.d.ts

@@ -8,6 +8,10 @@ interface HandoffContext {
     workingPath: string;
     modulePath: string;
 }
+type DeclarationResolution = {
+    fileName: string;
+};
+export declare const resolveComponentDeclaration: (componentDir: string, componentBaseName: string) => DeclarationResolution | null;
 /**
  * Initializes the runtime configuration by resolving component entries,
  * SCSS/JS paths, and transformer options from the handoff config.

package/dist/config/runtime.js

@@ -3,9 +3,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toLowerCaseKeysAndValues = exports.getItemsForPath = exports.getComponentsForPath = exports.initRuntimeConfig = void 0;
+exports.toLowerCaseKeysAndValues = exports.getItemsForPath = exports.getComponentsForPath = exports.initRuntimeConfig = exports.resolveComponentDeclaration = void 0;
 const esbuild_1 = __importDefault(require("esbuild"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
+const gray_matter_1 = __importDefault(require("gray-matter"));
 const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
 const csf_1 = require("../transformers/utils/csf");
@@ -13,6 +14,7 @@ const module_2 = require("../transformers/utils/module");
 const logger_1 = require("../utils/logger");
 const path_2 = require("../utils/path");
 const declaration_1 = require("./normalizers/declaration");
+const page_1 = require("./normalizers/page");
 const pattern_1 = require("./normalizers/pattern");
 const MODERN_EXTENSIONS = ['ts', 'js', 'cjs', 'json'];
 const getLegacyDeclarationFiles = (componentBaseName) => [
@@ -54,6 +56,7 @@ const resolveComponentDeclaration = (componentDir, componentBaseName) => {
     }
     return null;
 };
+exports.resolveComponentDeclaration = resolveComponentDeclaration;
 const evaluateTypeScriptDeclaration = (filePath, handoffModulePath) => {
     var _a, _b;
     const buildResult = esbuild_1.default.buildSync({
@@ -137,6 +140,7 @@ const initRuntimeConfig = (handoff) => {
             js: undefined,
             components: {},
             patterns: {},
+            pages: {},
         },
     };
     if (!!((_a = handoff.config.entries) === null || _a === void 0 ? void 0 : _a.scss)) {
@@ -150,7 +154,7 @@ const initRuntimeConfig = (handoff) => {
         for (const componentPath of componentPaths) {
             const resolvedComponentPath = path_1.default.resolve(handoff.workingPath, componentPath);
             const componentBaseName = path_1.default.basename(resolvedComponentPath);
-            const declaration = resolveComponentDeclaration(resolvedComponentPath, componentBaseName);
+            const declaration = (0, exports.resolveComponentDeclaration)(resolvedComponentPath, componentBaseName);
             if (!declaration) {
                 const modernFiles = getModernDeclarationFiles(componentBaseName);
                 const legacyFiles = getLegacyDeclarationFiles(componentBaseName);
@@ -201,7 +205,7 @@ const initRuntimeConfig = (handoff) => {
         for (const patternPath of patternPaths) {
             const resolvedPatternPath = path_1.default.resolve(handoff.workingPath, patternPath);
             const patternBaseName = path_1.default.basename(resolvedPatternPath);
-            const declaration = resolveComponentDeclaration(resolvedPatternPath, patternBaseName);
+            const declaration = (0, exports.resolveComponentDeclaration)(resolvedPatternPath, patternBaseName);
             if (!declaration) {
                 const modernFiles = getModernDeclarationFiles(patternBaseName);
                 const legacyFiles = getLegacyDeclarationFiles(patternBaseName);
@@ -220,7 +224,12 @@ const initRuntimeConfig = (handoff) => {
                 });
             }
             catch (err) {
-                logger_1.Logger.error(`Failed to read or parse pattern config: ${resolvedPatternConfigPath}`, err);
+                // Treat as a warning rather than an error: the file may be empty or
+                // mid-edit. It is already tracked in configFiles above, so
+                // watchRuntimeConfiguration will pick it up once the file is saved
+                // with valid content.
+                logger_1.Logger.warn(`Pattern config skipped (incomplete or invalid) — will retry on next save: ${resolvedPatternConfigPath}`);
+                logger_1.Logger.debug(`Pattern parse detail:`, err);
                 continue;
             }
             configFileIndex.set((0, path_2.normalizePathForCompare)(resolvedPatternConfigPath), { kind: 'pattern', entityId: pattern.id });
@@ -228,12 +237,51 @@ const initRuntimeConfig = (handoff) => {
         }
     }
     // -------------------------------------------------------------------------
+    // Discover markdown pages
+    // -------------------------------------------------------------------------
+    // Working pages under `<workingPath>/pages/` are first-class registry entities (publish/checkout).
+    // Discovery mirrors the catch-all/static-path walk: every `.md` except `index.md` becomes a page
+    // keyed by its slug path. Package `config/docs` defaults are NOT entities (they ship with the tool).
+    const pagesRoot = path_1.default.resolve(handoff.workingPath, 'pages');
+    for (const segments of collectPageMarkdownPaths(pagesRoot)) {
+        const slug = segments.join('/');
+        const sourcePath = path_1.default.resolve(pagesRoot, `${slug}.md`);
+        try {
+            const { data: frontmatter } = (0, gray_matter_1.default)(fs_extra_1.default.readFileSync(sourcePath, 'utf-8'));
+            const page = (0, page_1.normalizePageDeclaration)(frontmatter, { id: slug, routePath: `/${slug}`, sourcePath });
+            result.entries.pages[page.id] = page;
+        }
+        catch (err) {
+            logger_1.Logger.warn(`Page skipped (unreadable or invalid frontmatter): ${sourcePath}`);
+            logger_1.Logger.debug(`Page parse detail:`, err);
+        }
+    }
+    // -------------------------------------------------------------------------
     // Inject synthetic previews from patterns onto components
     // -------------------------------------------------------------------------
     injectPatternPreviews(result);
     return [result, Array.from(configFiles), configFileIndex];
 };
 exports.initRuntimeConfig = initRuntimeConfig;
+/**
+ * Recursively collect `.md` files under a root, returning slug segments (relative path without the
+ * `.md`). `index.md` is excluded — section index content is served by dedicated/home routes.
+ */
+const collectPageMarkdownPaths = (rootDir, relativeParts = []) => {
+    if (!fs_extra_1.default.existsSync(rootDir))
+        return [];
+    const results = [];
+    for (const entry of fs_extra_1.default.readdirSync(rootDir)) {
+        const fullPath = path_1.default.join(rootDir, entry);
+        if (fs_extra_1.default.lstatSync(fullPath).isDirectory()) {
+            results.push(...collectPageMarkdownPaths(fullPath, [...relativeParts, entry]));
+        }
+        else if (entry.endsWith('.md') && entry !== 'index.md') {
+            results.push([...relativeParts, entry.replace(/\.md$/, '')]);
+        }
+    }
+    return results;
+};
 /**
  * Returns a list of component directories for a given path.
  *
@@ -249,7 +297,7 @@ exports.initRuntimeConfig = initRuntimeConfig;
  */
 const getComponentsForPath = (searchPath) => {
     const dirName = path_1.default.basename(searchPath);
-    const hasOwnConfig = !!resolveComponentDeclaration(searchPath, dirName);
+    const hasOwnConfig = !!(0, exports.resolveComponentDeclaration)(searchPath, dirName);
     // Check if searchPath itself is a component directory (has a config file named after the directory)
     if (hasOwnConfig) {
         // This directory is a single component

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 import 'dotenv/config';
 import { Types as CoreTypes, Handoff as HandoffRunner } from 'handoff-core';
+import { type BuildPackage, type BuildTarget } from './app-builder';
+import { type HandoffStore } from './store';
 import { Config, ConfigFileEntry, RuntimeConfig } from './types/config';
 declare class Handoff {
     config: Config | null;
@@ -15,6 +17,12 @@ declare class Handoff {
         effects: {};
         typography: {};
     };
+    private _store?;
+    /**
+     * Normalized store over the current workspace runtime for components, patterns, pages, tokens,
+     * and assets. It is created lazily and reads live from `runtimeConfig`.
+     */
+    get store(): HandoffStore;
     private _initialArgs;
     private _configFilePaths;
     private _configFileIndex;
@@ -29,7 +37,55 @@ declare class Handoff {
     fetch(): Promise<Handoff>;
     component(name: string | null): Promise<Handoff>;
     pattern(): Promise<Handoff>;
-    build(skipComponents?: boolean): Promise<Handoff>;
+    build(target?: BuildTarget, skipComponents?: boolean, buildPackage?: BuildPackage): Promise<Handoff>;
+    /**
+     * Runs the package-owned registry database migrations against the configured PostgreSQL/Neon
+     * database. Independent of {@link build} — it only reads config + DB env vars and applies the
+     * bundled migration set.
+     */
+    dbMigrate(): Promise<Handoff>;
+    /**
+     * Publish a single component, pattern, or page from this connected workspace to the configured
+     * remote registry. Components and patterns receive a fresh targeted build before upload. Pages
+     * upload their record and markdown source because they render at runtime. The publish module is
+     * loaded lazily so the registry client and build code never enter the docs app bundle.
+     */
+    publish(kind: 'component' | 'pattern' | 'page', id: string): Promise<Handoff>;
+    /**
+     * Checkout a single component, pattern, or page from the connected remote registry. The checkout
+     * module is loaded lazily so the registry client never enters the docs app bundle.
+     */
+    checkout(kind: 'component' | 'pattern' | 'page', id: string): Promise<Handoff>;
+    /**
+     * Publish design token sets from this connected workspace to the configured remote registry. Runs a
+     * fresh token build (Figma extract + style transformers), discovers the logical sets, and uploads
+     * each changed set (its extracted record + generated artifacts). Publishes every set when `setId` is
+     * omitted, or only the named set (`foundation/colors`, `component/<id>`). Loaded lazily so the
+     * registry client/build code never enters the docs app bundle.
+     */
+    publishTokens(setId?: string): Promise<Handoff>;
+    /**
+     * Checkout design token sets from the connected remote registry into this workspace: reconstruct
+     * the canonical local `tokens.json` and restore the generated token files to their configured output
+     * paths. Checks out every published set when `setId` is omitted, or only the named set. Loaded lazily
+     * so the registry client never enters the docs app bundle.
+     */
+    checkoutTokens(setId?: string): Promise<Handoff>;
+    /**
+     * Publish asset collections (icons/logos/fonts) from this connected workspace to the configured
+     * remote registry. Runs a fresh build (Figma extract + asset generation), discovers the collections,
+     * uploads only content hashes the registry lacks, and finalizes each collection manifest atomically.
+     * Publishes every collection when `collection` is omitted, or only the named one. Loaded lazily so
+     * the registry client/build code never enters the docs app bundle.
+     */
+    publishAssets(collection?: string): Promise<Handoff>;
+    /**
+     * Checkout asset collections from the connected remote registry into this workspace: recreate the
+     * standard workspace asset files, collection JSON, icon sprite/manifest, and downloadable archives.
+     * Checks out every published collection when `collection` is omitted, or only the named one. Loaded
+     * lazily so the registry client never enters the docs app bundle.
+     */
+    checkoutAssets(collection?: string): Promise<Handoff>;
     ejectConfig(): Promise<Handoff>;
     ejectPages(): Promise<Handoff>;
     ejectTheme(): Promise<Handoff>;
@@ -70,6 +126,12 @@ declare class Handoff {
      * @returns {string} The absolute path to the tokens directory
      */
     getVariablesFilePath(): string;
+    /**
+     * Gets the generated docs API root (`<workingPath>/public/api`) — the tree holding the asset
+     * collection JSON, per-asset icon/logo bodies, and the icon sprite + manifest.
+     * @returns {string} The absolute path to the public docs API directory
+     */
+    getAssetsApiPath(): string;
     /**
      * Gets the path to the icons.zip file
      * @returns {string} The absolute path to the icons.zip file
@@ -106,6 +168,8 @@ export type { ComponentObject as Component } from './transformers/preview/types'
 export type { Config, RegisterHandlebarsHelpersContext } from './types/config';
 export { defineConfig } from './config';
 export { defineComponent, defineCsfComponent, defineHandlebarsComponent, definePattern, defineReactComponent, } from './declarations';
+export { defineAssetStorage } from './registry/asset-storage/define';
+export type { AssetStorage, AssetStorageContext, AssetStorageFactory, AssetStorageInput, AssetStorageReadResult, } from './registry/asset-storage/types';
 export type { CsfDeclarationConfig, DeclarationPreview, GenericDeclarationConfig, GenericPatternDeclarationConfig, HandlebarsDeclarationConfig, PatternComponentRef, ReactDeclarationConfig, RendererKind, } from './declarations';
 export { Transformers as CoreTransformers, TransformerUtils as CoreTransformerUtils, Types as CoreTypes } from 'handoff-core';
 export default Handoff;

package/dist/index.js

@@ -35,7 +35,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CoreTypes = exports.CoreTransformerUtils = exports.CoreTransformers = exports.defineReactComponent = exports.definePattern = exports.defineHandlebarsComponent = exports.defineCsfComponent = exports.defineComponent = exports.defineConfig = void 0;
+exports.CoreTypes = exports.CoreTransformerUtils = exports.CoreTransformers = exports.defineAssetStorage = exports.defineReactComponent = exports.definePattern = exports.defineHandlebarsComponent = exports.defineCsfComponent = exports.defineComponent = exports.defineConfig = void 0;
 require("dotenv/config");
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const handoff_core_1 = require("handoff-core");
@@ -45,11 +45,22 @@ const eject_1 = require("./cli/eject");
 const make_1 = require("./cli/make");
 const config_1 = require("./config");
 const pipeline_1 = __importStar(require("./pipeline"));
+const store_1 = require("./store");
 const builder_1 = __importStar(require("./transformers/preview/component/builder"));
 const logger_1 = require("./utils/logger");
 const path_2 = require("./utils/path");
 const path_3 = require("./utils/path");
 class Handoff {
+    /**
+     * Normalized store over the current workspace runtime for components, patterns, pages, tokens,
+     * and assets. It is created lazily and reads live from `runtimeConfig`.
+     */
+    get store() {
+        if (!this._store) {
+            this._store = (0, store_1.createFilesystemStore)(this);
+        }
+        return this._store;
+    }
     constructor(debug, force, config) {
         this.debug = false;
         this.force = false;
@@ -125,10 +136,109 @@ class Handoff {
             return this;
         });
     }
-    build(skipComponents) {
+    build() {
+        return __awaiter(this, arguments, void 0, function* (target = 'static', skipComponents, buildPackage) {
+            this.preRunner();
+            yield (0, app_builder_1.default)(this, target, skipComponents, buildPackage);
+            return this;
+        });
+    }
+    /**
+     * Runs the package-owned registry database migrations against the configured PostgreSQL/Neon
+     * database. Independent of {@link build} — it only reads config + DB env vars and applies the
+     * bundled migration set.
+     */
+    dbMigrate() {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!this.config) {
+                throw Error('Handoff not initialized');
+            }
+            const { runRegistryMigrations } = yield Promise.resolve().then(() => __importStar(require('./registry/db/migrate')));
+            yield runRegistryMigrations(this);
+            return this;
+        });
+    }
+    /**
+     * Publish a single component, pattern, or page from this connected workspace to the configured
+     * remote registry. Components and patterns receive a fresh targeted build before upload. Pages
+     * upload their record and markdown source because they render at runtime. The publish module is
+     * loaded lazily so the registry client and build code never enter the docs app bundle.
+     */
+    publish(kind, id) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.preRunner();
+            const { publishEntity } = yield Promise.resolve().then(() => __importStar(require('./registry/publish')));
+            yield publishEntity(this, kind, id);
+            return this;
+        });
+    }
+    /**
+     * Checkout a single component, pattern, or page from the connected remote registry. The checkout
+     * module is loaded lazily so the registry client never enters the docs app bundle.
+     */
+    checkout(kind, id) {
         return __awaiter(this, void 0, void 0, function* () {
             this.preRunner();
-            yield (0, app_builder_1.default)(this, skipComponents);
+            const { checkoutEntity } = yield Promise.resolve().then(() => __importStar(require('./registry/checkout')));
+            yield checkoutEntity(this, kind, id);
+            return this;
+        });
+    }
+    /**
+     * Publish design token sets from this connected workspace to the configured remote registry. Runs a
+     * fresh token build (Figma extract + style transformers), discovers the logical sets, and uploads
+     * each changed set (its extracted record + generated artifacts). Publishes every set when `setId` is
+     * omitted, or only the named set (`foundation/colors`, `component/<id>`). Loaded lazily so the
+     * registry client/build code never enters the docs app bundle.
+     */
+    publishTokens(setId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.preRunner();
+            const { publishTokens } = yield Promise.resolve().then(() => __importStar(require('./registry/publish/tokens')));
+            yield publishTokens(this, setId);
+            return this;
+        });
+    }
+    /**
+     * Checkout design token sets from the connected remote registry into this workspace: reconstruct
+     * the canonical local `tokens.json` and restore the generated token files to their configured output
+     * paths. Checks out every published set when `setId` is omitted, or only the named set. Loaded lazily
+     * so the registry client never enters the docs app bundle.
+     */
+    checkoutTokens(setId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.preRunner();
+            const { checkoutTokens } = yield Promise.resolve().then(() => __importStar(require('./registry/checkout/tokens')));
+            yield checkoutTokens(this, setId);
+            return this;
+        });
+    }
+    /**
+     * Publish asset collections (icons/logos/fonts) from this connected workspace to the configured
+     * remote registry. Runs a fresh build (Figma extract + asset generation), discovers the collections,
+     * uploads only content hashes the registry lacks, and finalizes each collection manifest atomically.
+     * Publishes every collection when `collection` is omitted, or only the named one. Loaded lazily so
+     * the registry client/build code never enters the docs app bundle.
+     */
+    publishAssets(collection) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.preRunner();
+            const { publishAssets } = yield Promise.resolve().then(() => __importStar(require('./registry/publish/assets')));
+            yield publishAssets(this, collection);
+            return this;
+        });
+    }
+    /**
+     * Checkout asset collections from the connected remote registry into this workspace: recreate the
+     * standard workspace asset files, collection JSON, icon sprite/manifest, and downloadable archives.
+     * Checks out every published collection when `collection` is omitted, or only the named one. Loaded
+     * lazily so the registry client never enters the docs app bundle.
+     */
+    checkoutAssets(collection) {
+        return __awaiter(this, void 0, void 0, function* () {
+            this.preRunner();
+            const { checkoutAssets } = yield Promise.resolve().then(() => __importStar(require('./registry/checkout/assets')));
+            yield checkoutAssets(this, collection);
             return this;
         });
     }
@@ -283,6 +393,14 @@ class Handoff {
     getVariablesFilePath() {
         return path_1.default.join(this.getOutputPath(), 'tokens');
     }
+    /**
+     * Gets the generated docs API root (`<workingPath>/public/api`) — the tree holding the asset
+     * collection JSON, per-asset icon/logo bodies, and the icon sprite + manifest.
+     * @returns {string} The absolute path to the public docs API directory
+     */
+    getAssetsApiPath() {
+        return path_1.default.resolve(this.workingPath, 'public', 'api');
+    }
     /**
      * Gets the path to the icons.zip file
      * @returns {string} The absolute path to the icons.zip file
@@ -345,6 +463,8 @@ Object.defineProperty(exports, "defineCsfComponent", { enumerable: true, get: fu
 Object.defineProperty(exports, "defineHandlebarsComponent", { enumerable: true, get: function () { return declarations_1.defineHandlebarsComponent; } });
 Object.defineProperty(exports, "definePattern", { enumerable: true, get: function () { return declarations_1.definePattern; } });
 Object.defineProperty(exports, "defineReactComponent", { enumerable: true, get: function () { return declarations_1.defineReactComponent; } });
+var define_1 = require("./registry/asset-storage/define");
+Object.defineProperty(exports, "defineAssetStorage", { enumerable: true, get: function () { return define_1.defineAssetStorage; } });
 // Export transformers and types from handoff-core
 var handoff_core_2 = require("handoff-core");
 Object.defineProperty(exports, "CoreTransformers", { enumerable: true, get: function () { return handoff_core_2.Transformers; } });