handoff-app 2.0.0-8 → 2.0.0

package/dist/app-builder/vercel-output.js

@@ -50,7 +50,7 @@ const resolveBasePath = (rawBasePath) => {
  * no functions, no database.
  *
  * @param exportDir Absolute path of the materialized static export (the same content the static
- *   target writes to `out/<projectId>`).
+ *   target writes to `out/static`).
  */
 const writeStaticVercelOutput = (handoff, exportDir) => __awaiter(void 0, void 0, void 0, function* () {
     var _a, _b;
@@ -77,10 +77,11 @@ exports.writeStaticVercelOutput = writeStaticVercelOutput;
 /**
  * Node.js runtime identifier baked into the registry function's `.vc-config.json`. The `pg` driver
  * (and the Neon serverless driver in its Node fallback) need the Node.js runtime, not the edge
- * runtime — this is the required baseline. Vercel resolves the patch
- * version within this major; pinning the major keeps the artifact stable.
+ * runtime. The major matches the package `engines` minimum, and the Vercel project's Node.js setting
+ * does not override it. Vercel resolves the patch version within this major; pinning the major keeps
+ * the artifact stable.
  */
-const VERCEL_NODE_RUNTIME = 'nodejs20.x';
+const VERCEL_NODE_RUNTIME = 'nodejs22.x';
 /** Name (sans `.func`) of the single registry function. Served at `/` and the catch-all route. */
 const REGISTRY_FUNCTION_NAME = 'index';
 /** Handler file the Node launcher executes; wraps the Next standalone server as a request listener. */

package/dist/cache/build-cache.d.ts

@@ -1,10 +1,11 @@
 import Handoff from '../index';
+import { BuildInputs } from './build-inputs';
 import { FileState } from './file-state';
 /**
  * Cache entry for a single component
  */
 export interface ComponentCacheEntry {
-    /** File states for all source files of this component */
+    /** File states for the declared source files of this component and every file its last build read */
     files: Record<string, FileState>;
     /** States for template directory files (if templates is a directory) */
     templateDirFiles?: Record<string, FileState>;
@@ -21,6 +22,18 @@ export interface GlobalDepsState {
     globalScss?: FileState;
     /** Global JS entry file state */
     globalJs?: FileState;
+    /** Main config file state. The build hooks are declared there */
+    mainConfig?: FileState;
+    /** Profile config file state */
+    profileConfig?: FileState;
+    /** Selected profile. All profiles write to the same output, so a switch invalidates all of it */
+    profile?: string;
+    /** Lockfile state. It stands in for the files under `node_modules`, which the cache does not track */
+    lockfile?: FileState;
+    /** handoff-app version that built the output */
+    version?: string;
+    /** Base path written into the generated HTML */
+    basePath?: string;
 }
 /**
  * Complete build cache structure
@@ -70,12 +83,22 @@ export declare function computeComponentFileStates(handoff: Handoff, componentId
     templateDirFiles?: Record<string, FileState>;
 }>;
 /**
- * Checks if a component needs to be rebuilt based on file states
+ * Checks if a component needs to be rebuilt based on file states. This also compares the files that
+ * the last build read with their current state on disk.
  */
 export declare function hasComponentChanged(cached: ComponentCacheEntry | null | undefined, current: {
     files: Record<string, FileState>;
     templateDirFiles?: Record<string, FileState>;
-}): boolean;
+}): Promise<boolean>;
+/**
+ * File states for every file that the builds of a component read, or `null` when that list is
+ * incomplete and the component must not be cached.
+ *
+ * Previews compile their sources with esbuild inside a Vite plugin, so Rollup does not see those
+ * imports. The esbuild graph of each script entry supplies them. The lockfile covers the files under
+ * `node_modules`, so they are skipped, together with the generated files in the output directory.
+ */
+export declare function computeBuildInputStates(handoff: Handoff, componentId: string, inputs: BuildInputs): Promise<Record<string, FileState> | null>;
 /**
  * Checks if the component output files exist
  */
@@ -90,7 +113,7 @@ export declare function createEmptyCache(): BuildCache;
 export declare function updateComponentCacheEntry(cache: BuildCache, componentId: string, fileStates: {
     files: Record<string, FileState>;
     templateDirFiles?: Record<string, FileState>;
-}): void;
+}, inputStates: Record<string, FileState>): void;
 /**
  * Removes components from cache that are no longer in runtime config
  */

package/dist/cache/build-cache.js

@@ -20,26 +20,29 @@ exports.haveGlobalDepsChanged = haveGlobalDepsChanged;
 exports.getComponentFilePaths = getComponentFilePaths;
 exports.computeComponentFileStates = computeComponentFileStates;
 exports.hasComponentChanged = hasComponentChanged;
+exports.computeBuildInputStates = computeBuildInputStates;
 exports.checkOutputExists = checkOutputExists;
 exports.createEmptyCache = createEmptyCache;
 exports.updateComponentCacheEntry = updateComponentCacheEntry;
 exports.pruneRemovedComponents = pruneRemovedComponents;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+const build_1 = require("../transformers/utils/build");
 const logger_1 = require("../utils/logger");
 const path_2 = require("../utils/path");
 const file_state_1 = require("./file-state");
 /** Current cache format version - bump when structure changes */
-const CACHE_VERSION = '1.0.0';
+const CACHE_VERSION = '2.0.0';
+const GLOBAL_FILE_DEPS = ['tokens', 'globalScss', 'globalJs', 'mainConfig', 'profileConfig', 'lockfile'];
+const GLOBAL_VALUE_DEPS = ['profile', 'version', 'basePath'];
+const LOCKFILE_NAMES = ['package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb'];
 /**
  * Gets the path to the build cache file
  */
 function getCachePath(handoff) {
-    // Two profiles share one project id and can build different output, so the profile has to name
-    // the cache file. One shared cache would serve the other profile's components.
-    const profile = handoff.getProfile();
-    const fileName = profile ? `build-cache.${profile}.json` : 'build-cache.json';
-    return path_1.default.resolve(handoff.modulePath, '.handoff', handoff.getProjectId(), '.cache', fileName);
+    // The cache describes the output in the working directory, so it lives there too. A build deletes
+    // the staged app under the package, so a cache there would not survive.
+    return path_1.default.resolve(handoff.workingPath, '.handoff', '.cache', 'build-cache.json');
 }
 /**
  * Loads the build cache from disk
@@ -99,7 +102,7 @@ function saveBuildCache(handoff, cache) {
  */
 function computeGlobalDepsState(handoff) {
     return __awaiter(this, void 0, void 0, function* () {
-        var _a, _b, _c, _d, _e, _f, _g;
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
         const result = {};
         // tokens.json
         const tokensPath = handoff.getTokensFilePath();
@@ -112,27 +115,61 @@ function computeGlobalDepsState(handoff) {
         if ((_f = (_e = handoff.runtimeConfig) === null || _e === void 0 ? void 0 : _e.entries) === null || _f === void 0 ? void 0 : _f.js) {
             result.globalJs = (_g = (yield (0, file_state_1.computeFileState)(handoff.runtimeConfig.entries.js))) !== null && _g !== void 0 ? _g : undefined;
         }
+        const mainConfigPath = handoff.getMainConfigFilePath();
+        if (mainConfigPath) {
+            result.mainConfig = (_h = (yield (0, file_state_1.computeFileState)(mainConfigPath))) !== null && _h !== void 0 ? _h : undefined;
+        }
+        const profileConfigPath = handoff.getProfileConfigFilePath();
+        if (profileConfigPath) {
+            result.profileConfig = (_j = (yield (0, file_state_1.computeFileState)(profileConfigPath))) !== null && _j !== void 0 ? _j : undefined;
+        }
+        result.profile = handoff.getProfile();
+        const lockfilePath = findLockfile(handoff.workingPath);
+        if (lockfilePath) {
+            result.lockfile = (_k = (yield (0, file_state_1.computeFileState)(lockfilePath))) !== null && _k !== void 0 ? _k : undefined;
+        }
+        result.version = yield readPackageVersion(handoff);
+        result.basePath = (_l = process.env.HANDOFF_APP_BASE_PATH) !== null && _l !== void 0 ? _l : '';
         return result;
     });
 }
+/** The nearest lockfile, searched up from the working directory so that a monorepo root lockfile is found. */
+function findLockfile(fromDirectory) {
+    for (let directory = path_1.default.resolve(fromDirectory);; directory = path_1.default.dirname(directory)) {
+        const lockfile = LOCKFILE_NAMES.map((name) => path_1.default.join(directory, name)).find((file) => fs_extra_1.default.existsSync(file));
+        if (lockfile)
+            return lockfile;
+        if (path_1.default.dirname(directory) === directory)
+            return undefined;
+    }
+}
+function readPackageVersion(handoff) {
+    return __awaiter(this, void 0, void 0, function* () {
+        try {
+            return (yield fs_extra_1.default.readJson(path_1.default.resolve(handoff.modulePath, 'package.json'))).version;
+        }
+        catch (_a) {
+            return undefined;
+        }
+    });
+}
 /**
  * Checks if global dependencies have changed
  */
 function haveGlobalDepsChanged(cached, current) {
     if (!cached)
         return true;
-    // Check each global dependency
-    if (!(0, file_state_1.statesMatch)(cached.tokens, current.tokens)) {
-        logger_1.Logger.debug('Global dependency changed: tokens.json');
-        return true;
-    }
-    if (!(0, file_state_1.statesMatch)(cached.globalScss, current.globalScss)) {
-        logger_1.Logger.debug('Global dependency changed: global SCSS entry');
-        return true;
+    for (const key of GLOBAL_FILE_DEPS) {
+        if (!(0, file_state_1.statesMatch)(cached[key], current[key])) {
+            logger_1.Logger.debug(`Global dependency changed: ${key}`);
+            return true;
+        }
     }
-    if (!(0, file_state_1.statesMatch)(cached.globalJs, current.globalJs)) {
-        logger_1.Logger.debug('Global dependency changed: global JS entry');
-        return true;
+    for (const key of GLOBAL_VALUE_DEPS) {
+        if (cached[key] !== current[key]) {
+            logger_1.Logger.debug(`Global dependency changed: ${key}`);
+            return true;
+        }
     }
     return false;
 }
@@ -243,37 +280,67 @@ function computeComponentFileStates(handoff, componentId) {
     });
 }
 /**
- * Checks if a component needs to be rebuilt based on file states
+ * Checks if a component needs to be rebuilt based on file states. This also compares the files that
+ * the last build read with their current state on disk.
  */
 function hasComponentChanged(cached, current) {
-    if (!cached) {
-        return true; // No cache entry means new component
-    }
-    // Check regular files
-    const cachedFiles = Object.keys(cached.files);
-    const currentFiles = Object.keys(current.files);
-    // Check if file count changed
-    if (cachedFiles.length !== currentFiles.length) {
-        return true;
-    }
-    // Check if any files were added or removed
-    const cachedSet = new Set(cachedFiles);
-    for (const file of currentFiles) {
-        if (!cachedSet.has(file)) {
-            return true;
+    return __awaiter(this, void 0, void 0, function* () {
+        if (!cached) {
+            return true; // No cache entry means new component
         }
-    }
-    // Check if any file states changed
-    for (const file of cachedFiles) {
-        if (!(0, file_state_1.statesMatch)(cached.files[file], current.files[file])) {
-            return true;
+        for (const [file, state] of Object.entries(current.files)) {
+            if (!(0, file_state_1.statesMatch)(cached.files[file], state)) {
+                return true;
+            }
         }
-    }
-    // Check template directory files if applicable
-    if (!(0, file_state_1.directoryStatesMatch)(cached.templateDirFiles, current.templateDirFiles)) {
-        return true;
-    }
-    return false;
+        for (const [file, state] of Object.entries(cached.files)) {
+            if (!(file in current.files) && !(0, file_state_1.statesMatch)(state, yield (0, file_state_1.computeFileState)(file))) {
+                return true;
+            }
+        }
+        return !(0, file_state_1.directoryStatesMatch)(cached.templateDirFiles, current.templateDirFiles);
+    });
+}
+const SCRIPT_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs', '.mts', '.cts']);
+/**
+ * File states for every file that the builds of a component read, or `null` when that list is
+ * incomplete and the component must not be cached.
+ *
+ * Previews compile their sources with esbuild inside a Vite plugin, so Rollup does not see those
+ * imports. The esbuild graph of each script entry supplies them. The lockfile covers the files under
+ * `node_modules`, so they are skipped, together with the generated files in the output directory.
+ */
+function computeBuildInputStates(handoff, componentId, inputs) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        if (inputs.failed) {
+            return null;
+        }
+        const files = new Set(inputs.files);
+        const entries = (_b = (_a = handoff.runtimeConfig) === null || _a === void 0 ? void 0 : _a.entities.components[componentId]) === null || _b === void 0 ? void 0 : _b.entries;
+        const scriptEntries = new Set(Object.values(entries !== null && entries !== void 0 ? entries : {}).filter((entry) => !!entry && SCRIPT_EXTENSIONS.has(path_1.default.extname(entry))));
+        for (const entry of scriptEntries) {
+            const moduleInputs = yield (0, build_1.collectModuleInputs)(entry, handoff);
+            if (!moduleInputs) {
+                return null;
+            }
+            for (const file of moduleInputs)
+                files.add(file);
+        }
+        const outputDirectory = path_1.default.resolve(handoff.workingPath, 'public/api/component');
+        const states = {};
+        for (const id of files) {
+            const file = id.split('?')[0];
+            if (!path_1.default.isAbsolute(file) || file.split(path_1.default.sep).includes('node_modules') || file.startsWith(outputDirectory + path_1.default.sep)) {
+                continue;
+            }
+            const state = yield (0, file_state_1.computeFileState)(file);
+            if (state) {
+                states[path_1.default.resolve(file)] = state;
+            }
+        }
+        return states;
+    });
 }
 /**
  * Checks if the component output files exist
@@ -323,9 +390,9 @@ function createEmptyCache() {
 /**
  * Updates cache entry for a specific component
  */
-function updateComponentCacheEntry(cache, componentId, fileStates) {
+function updateComponentCacheEntry(cache, componentId, fileStates, inputStates) {
     cache.components[componentId] = {
-        files: fileStates.files,
+        files: Object.assign(Object.assign({}, inputStates), fileStates.files),
         templateDirFiles: fileStates.templateDirFiles,
         buildTimestamp: Date.now(),
     };

package/dist/cache/build-inputs.d.ts

@@ -0,0 +1,13 @@
+import type { InlineConfig } from 'vite';
+/**
+ * The files that the builds of one component read, so the build cache can tell when an imported
+ * file changes. A failed build can stop before it reads the file that broke it, so its list is
+ * incomplete and must not be cached.
+ */
+export interface BuildInputs {
+    files: Set<string>;
+    failed: boolean;
+}
+export declare const createBuildInputs: () => BuildInputs;
+/** Call after the consumer hooks, so that a hook that replaces `plugins` cannot drop the collector. */
+export declare const withBuildInputs: (config: InlineConfig, inputs?: BuildInputs) => InlineConfig;

package/dist/cache/build-inputs.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withBuildInputs = exports.createBuildInputs = void 0;
+const createBuildInputs = () => ({ files: new Set(), failed: false });
+exports.createBuildInputs = createBuildInputs;
+/**
+ * Records every file that a Vite build loaded, Sass partials included. The Vite CSS plugin registers
+ * partials with `addWatchFile`, and Rollup keeps this list in every build, not only in watch mode.
+ */
+const collectBuildInputs = (inputs) => ({
+    name: 'handoff:collect-build-inputs',
+    buildEnd() {
+        for (const file of this.getWatchFiles())
+            inputs.files.add(file);
+    },
+});
+/** Call after the consumer hooks, so that a hook that replaces `plugins` cannot drop the collector. */
+const withBuildInputs = (config, inputs) => { var _a; return inputs ? Object.assign(Object.assign({}, config), { plugins: [...((_a = config.plugins) !== null && _a !== void 0 ? _a : []), collectBuildInputs(inputs)] }) : config; };
+exports.withBuildInputs = withBuildInputs;

package/dist/cache/index.d.ts

@@ -1,2 +1,3 @@
 export { computeDirectoryState, computeFileState, directoryStatesMatch, statesMatch, type FileState } from './file-state';
-export { checkOutputExists, computeComponentFileStates, computeGlobalDepsState, createEmptyCache, getCachePath, hasComponentChanged, haveGlobalDepsChanged, loadBuildCache, pruneRemovedComponents, saveBuildCache, updateComponentCacheEntry, type BuildCache, type ComponentCacheEntry, type GlobalDepsState, } from './build-cache';
+export { checkOutputExists, computeBuildInputStates, computeComponentFileStates, computeGlobalDepsState, createEmptyCache, getCachePath, hasComponentChanged, haveGlobalDepsChanged, loadBuildCache, pruneRemovedComponents, saveBuildCache, updateComponentCacheEntry, type BuildCache, type ComponentCacheEntry, type GlobalDepsState, } from './build-cache';
+export { createBuildInputs, type BuildInputs } from './build-inputs';

package/dist/cache/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.updateComponentCacheEntry = exports.saveBuildCache = exports.pruneRemovedComponents = exports.loadBuildCache = exports.haveGlobalDepsChanged = exports.hasComponentChanged = exports.getCachePath = exports.createEmptyCache = exports.computeGlobalDepsState = exports.computeComponentFileStates = exports.checkOutputExists = exports.statesMatch = exports.directoryStatesMatch = exports.computeFileState = exports.computeDirectoryState = void 0;
+exports.createBuildInputs = exports.updateComponentCacheEntry = exports.saveBuildCache = exports.pruneRemovedComponents = exports.loadBuildCache = exports.haveGlobalDepsChanged = exports.hasComponentChanged = exports.getCachePath = exports.createEmptyCache = exports.computeGlobalDepsState = exports.computeComponentFileStates = exports.computeBuildInputStates = exports.checkOutputExists = exports.statesMatch = exports.directoryStatesMatch = exports.computeFileState = exports.computeDirectoryState = void 0;
 // File state utilities
 var file_state_1 = require("./file-state");
 Object.defineProperty(exports, "computeDirectoryState", { enumerable: true, get: function () { return file_state_1.computeDirectoryState; } });
@@ -10,6 +10,7 @@ Object.defineProperty(exports, "statesMatch", { enumerable: true, get: function
 // Build cache utilities
 var build_cache_1 = require("./build-cache");
 Object.defineProperty(exports, "checkOutputExists", { enumerable: true, get: function () { return build_cache_1.checkOutputExists; } });
+Object.defineProperty(exports, "computeBuildInputStates", { enumerable: true, get: function () { return build_cache_1.computeBuildInputStates; } });
 Object.defineProperty(exports, "computeComponentFileStates", { enumerable: true, get: function () { return build_cache_1.computeComponentFileStates; } });
 Object.defineProperty(exports, "computeGlobalDepsState", { enumerable: true, get: function () { return build_cache_1.computeGlobalDepsState; } });
 Object.defineProperty(exports, "createEmptyCache", { enumerable: true, get: function () { return build_cache_1.createEmptyCache; } });
@@ -20,3 +21,6 @@ Object.defineProperty(exports, "loadBuildCache", { enumerable: true, get: functi
 Object.defineProperty(exports, "pruneRemovedComponents", { enumerable: true, get: function () { return build_cache_1.pruneRemovedComponents; } });
 Object.defineProperty(exports, "saveBuildCache", { enumerable: true, get: function () { return build_cache_1.saveBuildCache; } });
 Object.defineProperty(exports, "updateComponentCacheEntry", { enumerable: true, get: function () { return build_cache_1.updateComponentCacheEntry; } });
+// Build input collection
+var build_inputs_1 = require("./build-inputs");
+Object.defineProperty(exports, "createBuildInputs", { enumerable: true, get: function () { return build_inputs_1.createBuildInputs; } });

package/dist/catalog/normalize.js

@@ -88,6 +88,9 @@ const normalizeCatalogItem = (moduleExports, options) => {
     entries[entryKey] = path_1.default.resolve(directory, source.file);
     // Existing builders consume template as the primary build input for every renderer.
     entries.template = entries[entryKey];
+    // The renderer and the hydration bundle both read a preview `render` from the declaration.
+    if (options.declarationPath)
+        entries.declaration = options.declarationPath;
     // A wrong renderer builds a broken preview without failing on its own, so a mismatch is fatal.
     // `config/runtime.ts` turns the throw into a skipped item that retries on the next save.
     const claim = (0, renderers_1.sourceForFile)(source.file);

package/dist/catalog/previews.js

@@ -8,16 +8,17 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const lodash_1 = require("lodash");
 /**
  * A declaration module exports more than previews: the item itself, the implementation it
- * re-exports, helper values. Accept only a plain object that owns `args` or `name`, so an exported
- * component or helper is never mistaken for a preview.
+ * re-exports, helper values. Accept only a plain object that owns one of the preview fields, so an
+ * exported component or helper is never mistaken for a preview.
  *
  * `getCsfStoryEntries` does not fit here: on a CSF file every named export is a story, and on a
  * declaration file it is not.
  */
+const PREVIEW_KEYS = ['args', 'name', 'render'];
 const isPreviewDeclaration = (value) => {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
-    return Object.prototype.hasOwnProperty.call(value, 'args') || Object.prototype.hasOwnProperty.call(value, 'name');
+    return PREVIEW_KEYS.some((key) => Object.prototype.hasOwnProperty.call(value, key));
 };
 /** Matches an exported binding, an export list, or a CommonJS export assignment. */
 const EXPORT_PATTERNS = [
@@ -99,7 +100,7 @@ const createCatalogPreviews = (moduleExports, declarationPath) => {
             throw new Error(`Preview "${exportName}" uses removed fields. Use args and name. See UPGRADE.md#catalog-items.`);
         }
         const preview = value;
-        previews[exportName] = Object.assign({ title: preview.name || (0, lodash_1.startCase)(exportName), values: Object.assign({}, ((_a = preview.args) !== null && _a !== void 0 ? _a : {})), url: (_b = preview.url) !== null && _b !== void 0 ? _b : '' }, (preview.usage ? { usage: preview.usage } : {}));
+        previews[exportName] = Object.assign(Object.assign({ title: preview.name || (0, lodash_1.startCase)(exportName), values: Object.assign({}, ((_a = preview.args) !== null && _a !== void 0 ? _a : {})), url: (_b = preview.url) !== null && _b !== void 0 ? _b : '' }, (preview.usage ? { usage: preview.usage } : {})), (typeof preview.render === 'function' ? { render: preview.render } : {}));
     }
     return declarationPath ? (0, exports.orderPreviews)(previews, (0, exports.readExportOrder)(declarationPath)) : previews;
 };

package/dist/catalog/types.d.ts

@@ -43,6 +43,14 @@ export type CatalogPreview<TArgs = Record<string, unknown>> = {
     args?: TArgs;
     usage?: string;
     url?: string;
+    /**
+     * Renders this preview in place of the implementation, for props it cannot carry as data: an icon
+     * component, a callback, JSX children, or state the preview owns.
+     *
+     * Rendered as a component with `args`, so it can use hooks. The item still documents the
+     * implementation, so a wrapper never becomes the published API.
+     */
+    render?: (args: TArgs) => unknown;
 };
 /**
  * `__args` exists only in the type system so `Preview<typeof item>` can infer the preview argument type.

package/dist/cli/create.js

@@ -130,8 +130,7 @@ const renderTemplate = (content, data) => {
     });
 };
 const getDependenciesToInstall = (options) => {
-    // TODO: switch back to `handoff-app@latest` before the 2.0 stable release.
-    const dependencies = ['handoff-app@next'];
+    const dependencies = ['handoff-app@latest'];
     const devDependencies = [];
     if (options.includeExamples) {
         dependencies.push('react', 'react-dom');

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

@@ -10,7 +10,7 @@ export interface BuildArgs extends SharedArgs {
  * `handoff-app build [--target static|registry] [--package standalone|vercel]` — builds the
  * documentation site for the resolved target and packages it for the resolved deliverable.
  * `--target` selects *what* is built; the optional, additive `--package` selects *how* it is
- * packaged. Bare `build` resolves to the static target with the `out/<projectId>` export;
+ * packaged. Bare `build` resolves to the static target with the `out/static` export;
  * `--package` never implies a `--target`.
  */
 declare const command: CommandModule<{}, BuildArgs>;

package/dist/commands/build/index.js

@@ -18,7 +18,7 @@ const BUILD_PACKAGES = ['standalone', 'vercel'];
  * `handoff-app build [--target static|registry] [--package standalone|vercel]` — builds the
  * documentation site for the resolved target and packages it for the resolved deliverable.
  * `--target` selects *what* is built; the optional, additive `--package` selects *how* it is
- * packaged. Bare `build` resolves to the static target with the `out/<projectId>` export;
+ * packaged. Bare `build` resolves to the static target with the `out/static` export;
  * `--package` never implies a `--target`.
  */
 const command = {

package/dist/commands/utils.d.ts

@@ -23,7 +23,7 @@ export declare const createHandoff: (args: SharedArgs, options?: Pick<HandoffOpt
  * trace.
  */
 export declare const runRegistryCommand: (args: SharedArgs, run: (handoff: Handoff) => Promise<unknown>) => Promise<void>;
-export declare const getSharedOptions: (yargs: Argv) => Argv<import("yargs").Omit<{}, "debug" | "config" | "profile" | "force"> & import("yargs").InferredOptionTypes<{
+export declare const getSharedOptions: (yargs: Argv) => Argv<import("yargs").Omit<{}, "debug" | "profile" | "config" | "force"> & import("yargs").InferredOptionTypes<{
     config: {
         alias: string;
         type: "string";
@@ -45,7 +45,7 @@ export declare const getSharedOptions: (yargs: Argv) => Argv<import("yargs").Omi
     };
 }>>;
 /** Shared options plus the transfer options: publish and its compatibility aliases use these. */
-export declare const getPublishOptions: (yargs: Argv) => Argv<import("yargs").Omit<import("yargs").Omit<{}, "debug" | "config" | "profile" | "force"> & import("yargs").InferredOptionTypes<{
+export declare const getPublishOptions: (yargs: Argv) => Argv<import("yargs").Omit<import("yargs").Omit<{}, "debug" | "profile" | "config" | "force"> & import("yargs").InferredOptionTypes<{
     config: {
         alias: string;
         type: "string";
@@ -77,7 +77,7 @@ export declare const getPublishOptions: (yargs: Argv) => Argv<import("yargs").Om
     };
 }>>;
 /** Shared options plus `--dry-run`: checkout and its compatibility aliases use these. */
-export declare const getCheckoutOptions: (yargs: Argv) => Argv<import("yargs").Omit<import("yargs").Omit<{}, "debug" | "config" | "profile" | "force"> & import("yargs").InferredOptionTypes<{
+export declare const getCheckoutOptions: (yargs: Argv) => Argv<import("yargs").Omit<import("yargs").Omit<{}, "debug" | "profile" | "config" | "force"> & import("yargs").InferredOptionTypes<{
     config: {
         alias: string;
         type: "string";

package/dist/config/defaults.js

@@ -7,8 +7,12 @@ const connection_1 = require("../registry/connection");
 const isMcpEnabled = (config) => { var _a; return ((_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.mcp) !== false; };
 exports.isMcpEnabled = isMcpEnabled;
 const defaultConfig = () => ({
-    dev_access_token: (0, from_env_1.fromEnv)('HANDOFF_DEV_ACCESS_TOKEN', { default: null }),
-    figma_project_id: (0, from_env_1.fromEnv)('HANDOFF_FIGMA_PROJECT_ID', { default: null }),
+    integrations: {
+        figma: {
+            projectId: (0, from_env_1.fromEnv)('HANDOFF_FIGMA_PROJECT_ID', { default: null }),
+            accessToken: (0, from_env_1.fromEnv)('HANDOFF_DEV_ACCESS_TOKEN', { default: null }),
+        },
+    },
     runtime: {
         mode: 'workspace',
         registryConnection: {
@@ -16,8 +20,7 @@ const defaultConfig = () => ({
             accessToken: (0, from_env_1.fromEnv)('HANDOFF_REGISTRY_ACCESS_TOKEN', { default: '' }),
         },
         registry: {
-            databaseUrl: (0, from_env_1.fromEnv)('DATABASE_URL'),
-            assetStorage: { token: (0, from_env_1.fromEnv)('BLOB_READ_WRITE_TOKEN') },
+            database: { url: (0, from_env_1.fromEnv)('DATABASE_URL') },
         },
     },
     exportsOutputDirectory: (0, from_env_1.fromEnv)('HANDOFF_OUTPUT_DIR', { default: 'exported' }),

package/dist/config/from-env.d.ts

@@ -22,3 +22,7 @@ export declare const fromEnv: <T = string>(name: string, options?: {
     default: T;
 }) => EnvReference<T>;
 export declare const isEnvReference: (value: unknown) => value is EnvReference<unknown>;
+/** Replace each reference nested in `options` with its value from `env`. An unset or empty variable becomes `undefined`. */
+export declare const resolveEnvReferences: (options: Record<string, unknown>, env: NodeJS.ProcessEnv) => Record<string, unknown>;
+/** The variable names that the references nested in `options` use, for deployment instructions. */
+export declare const envReferenceNames: (options: Record<string, unknown>) => string[];

package/dist/config/from-env.js

@@ -1,7 +1,44 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isEnvReference = exports.fromEnv = void 0;
+exports.envReferenceNames = exports.resolveEnvReferences = exports.isEnvReference = exports.fromEnv = void 0;
 const fromEnv = (name, options) => options === undefined ? { $env: name } : { $env: name, default: options.default };
 exports.fromEnv = fromEnv;
 const isEnvReference = (value) => value !== null && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, '$env');
 exports.isEnvReference = isEnvReference;
+const isPlainRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Replace each reference nested in `options` with its value from `env`. An unset or empty variable becomes `undefined`. */
+const resolveEnvReferences = (options, env) => {
+    const resolve = (value) => {
+        var _a;
+        if ((0, exports.isEnvReference)(value)) {
+            const resolved = typeof value.$env === 'string' ? (_a = env[value.$env]) === null || _a === void 0 ? void 0 : _a.trim() : undefined;
+            return resolved || undefined;
+        }
+        if (Array.isArray(value))
+            return value.map(resolve);
+        if (isPlainRecord(value))
+            return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, resolve(entry)]));
+        return value;
+    };
+    return resolve(options);
+};
+exports.resolveEnvReferences = resolveEnvReferences;
+/** The variable names that the references nested in `options` use, for deployment instructions. */
+const envReferenceNames = (options) => {
+    const names = new Set();
+    const collect = (value) => {
+        if ((0, exports.isEnvReference)(value)) {
+            if (typeof value.$env === 'string')
+                names.add(value.$env);
+        }
+        else if (Array.isArray(value)) {
+            value.forEach(collect);
+        }
+        else if (isPlainRecord(value)) {
+            Object.values(value).forEach(collect);
+        }
+    };
+    collect(options);
+    return [...names];
+};
+exports.envReferenceNames = envReferenceNames;

package/dist/config/helpers.js

@@ -19,8 +19,8 @@ const normalizeAppConfig = (app) => {
     return Object.assign(Object.assign({}, rest), { google_tag_manager: googleTagManager !== null && googleTagManager !== void 0 ? googleTagManager : app.google_tag_manager, type_copy: typeCopy !== null && typeCopy !== void 0 ? typeCopy : app.type_copy, type_sort: typeSort !== null && typeSort !== void 0 ? typeSort : app.type_sort, color_sort: colorSort !== null && colorSort !== void 0 ? colorSort : app.color_sort, component_sort: componentSort !== null && componentSort !== void 0 ? componentSort : app.component_sort, base_path: basePath !== null && basePath !== void 0 ? basePath : app.base_path });
 };
 const normalizeConfig = (config) => {
-    const { devAccessToken, figmaProjectId, assetsZipLinks, app } = config, rest = __rest(config, ["devAccessToken", "figmaProjectId", "assetsZipLinks", "app"]);
-    return Object.assign(Object.assign({}, rest), { dev_access_token: devAccessToken !== undefined ? devAccessToken : config.dev_access_token, figma_project_id: figmaProjectId !== undefined ? figmaProjectId : config.figma_project_id, assets_zip_links: assetsZipLinks !== null && assetsZipLinks !== void 0 ? assetsZipLinks : config.assets_zip_links, app: normalizeAppConfig(app) });
+    const { assetsZipLinks, app } = config, rest = __rest(config, ["assetsZipLinks", "app"]);
+    return Object.assign(Object.assign({}, rest), { assets_zip_links: assetsZipLinks !== null && assetsZipLinks !== void 0 ? assetsZipLinks : config.assets_zip_links, app: normalizeAppConfig(app) });
 };
 exports.normalizeConfig = normalizeConfig;
 /**

package/dist/config/index.d.ts

@@ -5,6 +5,5 @@ export { CONFIG_FILE_PREFERENCE, HandoffConfigError, initConfig, initConfigWithM
 export type { ConfigLoadContext } from './loader';
 export { defineConfig } from './helpers';
 export { initRuntimeConfig } from './runtime';
-export { validateConfig } from './validator';
 export { addToCatalog, isIncluded } from './catalog-include';
 export type { AddToCatalogResult } from './catalog-include';

package/dist/config/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isIncluded = exports.addToCatalog = exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.resolveProfileSelection = exports.initConfigWithMetadata = exports.initConfig = exports.HandoffConfigError = exports.CONFIG_FILE_PREFERENCE = exports.loadProfileEnv = exports.isMcpEnabled = exports.getClientConfig = exports.defaultConfig = void 0;
+exports.isIncluded = exports.addToCatalog = exports.initRuntimeConfig = exports.defineConfig = exports.resolveProfileSelection = exports.initConfigWithMetadata = exports.initConfig = exports.HandoffConfigError = exports.CONFIG_FILE_PREFERENCE = exports.loadProfileEnv = exports.isMcpEnabled = exports.getClientConfig = exports.defaultConfig = void 0;
 // Config defaults and client config
 var defaults_1 = require("./defaults");
 Object.defineProperty(exports, "defaultConfig", { enumerable: true, get: function () { return defaults_1.defaultConfig; } });
@@ -22,9 +22,6 @@ Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function
 // Runtime config resolution
 var runtime_1 = require("./runtime");
 Object.defineProperty(exports, "initRuntimeConfig", { enumerable: true, get: function () { return runtime_1.initRuntimeConfig; } });
-// Config validation
-var validator_1 = require("./validator");
-Object.defineProperty(exports, "validateConfig", { enumerable: true, get: function () { return validator_1.validateConfig; } });
 // Registering catalog item directories under `catalog.include`
 var catalog_include_1 = require("./catalog-include");
 Object.defineProperty(exports, "addToCatalog", { enumerable: true, get: function () { return catalog_include_1.addToCatalog; } });