handoff-app 2.0.0-7 → 2.0.0-9

package/dist/config/loader.d.ts

@@ -1,11 +1,12 @@
-import { Config } from '../types/config';
-/** Raised when an explicitly requested config file cannot be used. */
-export declare class HandoffConfigError extends Error {
-    constructor(message: string);
-}
+import { Config, ResolvedConfig } from '../types/config';
+export declare const CONFIG_FILE_PREFERENCE: readonly ["handoff.config.ts", "handoff.config.js", "handoff.config.cjs", "handoff.config.json"];
+export { HandoffConfigError } from './errors';
 type ConfigLoadResult = {
-    config: Config;
+    config: ResolvedConfig;
     configPath?: string;
+    profile?: string;
+    /** The profile file merged onto the base config. */
+    profileConfigPath?: string;
 };
 /** Where to look for the config: the working directory, plus an optional explicit file. */
 export type ConfigLoadContext = {
@@ -13,7 +14,24 @@ export type ConfigLoadContext = {
     workingPath?: string;
     /** Explicit config file (the CLI's `-c, --config`), replacing discovery entirely. */
     configPath?: string;
+    /** Profile to merge onto the base config (the CLI's `--profile`), overriding `HANDOFF_PROFILE`. */
+    profile?: string;
+    /**
+     * Profile names that resolve without a `handoff.config.<profile>.*` file, leaving the base config
+     * unchanged. Registry commands pass the names of saved logins, because there a profile selects the
+     * registry rather than a config layer.
+     */
+    knownProfiles?: string[];
+    /** Sentence appended when a selected profile matches neither a config file nor `knownProfiles`. */
+    profileNotFoundHint?: string;
 };
+/** Which selector picked the profile, so an error can name the one the user set. */
+type ProfileSelection = {
+    name: string;
+    source: '--profile' | 'HANDOFF_PROFILE';
+};
+/** `--profile` wins over `HANDOFF_PROFILE`, and an empty value counts as unset. */
+export declare const resolveProfileSelection: (requestedProfile?: string) => ProfileSelection | undefined;
 /**
  * Loads the handoff configuration for the given working directory and returns metadata.
  */
@@ -22,12 +40,12 @@ export declare const initConfigWithMetadata: (configOverride?: Partial<Config>,
  * Loads the handoff configuration for the given working directory.
  *
  * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json,
- * unless `context.configPath` names one explicitly. Merges file config with any provided overrides,
- * then applies defaults for missing values.
+ * unless `context.configPath` names one explicitly. A selected profile adds a `handoff.config.<profile>.*` sidecar,
+ * which only `context.knownProfiles` makes optional.
+ * Layers resolve as defaults, base config, profile, then the given overrides, merging plain objects recursively.
  *
  * @param configOverride - Optional partial config to override file-loaded values.
- * @param context - Optional working directory and explicit config file to load.
+ * @param context - Optional working directory, explicit config file, and profile to load.
  * @returns The fully resolved Config object.
  */
-export declare const initConfig: (configOverride?: Partial<Config>, context?: ConfigLoadContext) => Config;
-export {};
+export declare const initConfig: (configOverride?: Partial<Config>, context?: ConfigLoadContext) => ResolvedConfig;

package/dist/config/loader.js

@@ -3,31 +3,33 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.initConfig = exports.initConfigWithMetadata = exports.HandoffConfigError = void 0;
+exports.initConfig = exports.initConfigWithMetadata = exports.resolveProfileSelection = exports.HandoffConfigError = exports.CONFIG_FILE_PREFERENCE = void 0;
 const esbuild_1 = __importDefault(require("esbuild"));
+const build_1 = require("../transformers/utils/build");
 const fs_extra_1 = __importDefault(require("fs-extra"));
-const merge_1 = __importDefault(require("lodash/merge"));
+const mergeWith_1 = __importDefault(require("lodash/mergeWith"));
 const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("../utils/logger");
 const path_2 = require("../utils/path");
 const defaults_1 = require("./defaults");
-const CONFIG_FILE_PREFERENCE = [
+const env_1 = require("./env");
+const helpers_1 = require("./helpers");
+const errors_1 = require("./errors");
+const from_env_1 = require("./from-env");
+const resolve_env_1 = require("./resolve-env");
+exports.CONFIG_FILE_PREFERENCE = [
     'handoff.config.ts',
     'handoff.config.js',
     'handoff.config.cjs',
     'handoff.config.json',
 ];
 /** Extensions the loader knows how to evaluate, derived from the discoverable file names. */
-const SUPPORTED_CONFIG_EXTENSIONS = Array.from(new Set(CONFIG_FILE_PREFERENCE.map((fileName) => path_1.default.extname(fileName))));
-/** Raised when an explicitly requested config file cannot be used. */
-class HandoffConfigError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'HandoffConfigError';
-    }
-}
-exports.HandoffConfigError = HandoffConfigError;
+const SUPPORTED_CONFIG_EXTENSIONS = Array.from(new Set(exports.CONFIG_FILE_PREFERENCE.map((fileName) => path_1.default.extname(fileName))));
+/** A profile name becomes part of a file name, so it stays lowercase letters, numbers, and hyphens. */
+const PROFILE_NAME_PATTERN = /^[a-z0-9-]+$/;
+var errors_2 = require("./errors");
+Object.defineProperty(exports, "HandoffConfigError", { enumerable: true, get: function () { return errors_2.HandoffConfigError; } });
 const evaluateTypeScriptConfig = (filePath, handoffModulePath) => {
     var _a, _b;
     const buildResult = esbuild_1.default.buildSync({
@@ -39,6 +41,7 @@ const evaluateTypeScriptConfig = (filePath, handoffModulePath) => {
         target: 'node16',
         logLevel: 'silent',
         external: ['handoff-app'],
+        loader: build_1.STYLE_IMPORT_LOADERS,
     });
     const code = (_b = (_a = buildResult.outputFiles) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.text;
     if (!code) {
@@ -75,6 +78,28 @@ const loadConfigFile = (configPath) => {
     const importedConfig = require(configPath);
     return (importedConfig.default || importedConfig);
 };
+/**
+ * Normalize here and not only in `defineConfig`: a `.json` config, or a profile that skips the
+ * helper, would otherwise keep its camelCase keys. The rest of the codebase reads the runtime keys,
+ * so a later layer could not override an earlier one.
+ */
+const loadConfigLayer = (configPath) => (0, helpers_1.normalizeConfig)(loadConfigFile(configPath));
+const pickExisting = (candidates) => {
+    const existing = candidates.filter((filePath) => fs_extra_1.default.existsSync(filePath));
+    if (!existing.length) {
+        return { selected: undefined, ignored: [] };
+    }
+    const [selected, ...ignored] = existing;
+    return { selected, ignored };
+};
+const warnIgnored = (selected, ignored) => {
+    if (!selected || ignored.length === 0) {
+        return;
+    }
+    logger_1.Logger.warn(`Multiple config files found. Using "${path_1.default.basename(selected)}" and ignoring: ${ignored
+        .map((filePath) => `"${path_1.default.basename(filePath)}"`)
+        .join(', ')}.`);
+};
 /**
  * Picks the config file to load. An explicitly requested file replaces discovery - it is resolved
  * from `workingPath` and must exist in a format the loader can evaluate. Otherwise every known
@@ -84,70 +109,120 @@ const resolveConfigFilePath = (workingPath, requestedPath) => {
     if (requestedPath) {
         const selected = path_1.default.resolve(workingPath, requestedPath);
         if (!fs_extra_1.default.existsSync(selected)) {
-            throw new HandoffConfigError(`Config file not found: "${requestedPath}" (resolved to ${selected})`);
+            throw new errors_1.HandoffConfigError(`Config file not found: "${requestedPath}" (resolved to ${selected})`);
         }
         if (!SUPPORTED_CONFIG_EXTENSIONS.includes(path_1.default.extname(selected))) {
-            throw new HandoffConfigError(`Unsupported config file "${path_1.default.basename(selected)}". Supported extensions: ${SUPPORTED_CONFIG_EXTENSIONS.join(', ')}`);
+            throw new errors_1.HandoffConfigError(`Unsupported config file "${path_1.default.basename(selected)}". Supported extensions: ${SUPPORTED_CONFIG_EXTENSIONS.join(', ')}`);
         }
         return { selected, ignored: [] };
     }
-    const existing = CONFIG_FILE_PREFERENCE
-        .map((fileName) => path_1.default.resolve(workingPath, fileName))
-        .filter((filePath) => fs_extra_1.default.existsSync(filePath));
-    if (!existing.length) {
-        return { selected: undefined, ignored: [] };
+    return pickExisting(exports.CONFIG_FILE_PREFERENCE.map((fileName) => path_1.default.resolve(workingPath, fileName)));
+};
+/** `--profile` wins over `HANDOFF_PROFILE`, and an empty value counts as unset. */
+const resolveProfileSelection = (requestedProfile) => {
+    var _a;
+    const fromOption = requestedProfile === null || requestedProfile === void 0 ? void 0 : requestedProfile.trim();
+    if (fromOption) {
+        return { name: fromOption, source: '--profile' };
     }
-    const [selected, ...ignored] = existing;
-    return { selected, ignored };
+    const fromEnvironment = (_a = process.env.HANDOFF_PROFILE) === null || _a === void 0 ? void 0 : _a.trim();
+    if (fromEnvironment) {
+        return { name: fromEnvironment, source: 'HANDOFF_PROFILE' };
+    }
+    return undefined;
+};
+exports.resolveProfileSelection = resolveProfileSelection;
+/**
+ * Picks the profile file for a selected profile. It sits beside the base config: the base file name
+ * without its extension, then the profile name, then any config extension. So `handoff.config.ts`
+ * pairs with `handoff.config.local.*`, and a config named through `-c` keeps its own name. A selected
+ * profile has to resolve - silently falling back to the base config would deploy the wrong settings.
+ * A name listed in `knownProfiles` resolves without a file, because it names something else that
+ * exists, such as a saved registry login.
+ */
+const resolveProfileFilePath = (workingPath, baseConfigPath, selection, context) => {
+    var _a;
+    if (!PROFILE_NAME_PATTERN.test(selection.name)) {
+        throw new errors_1.HandoffConfigError(`Invalid config profile "${selection.name}" (from ${selection.source}). ` +
+            `A profile name can contain lowercase letters, numbers, and hyphens.`);
+    }
+    const baseName = baseConfigPath
+        ? path_1.default.join(path_1.default.dirname(baseConfigPath), path_1.default.basename(baseConfigPath, path_1.default.extname(baseConfigPath)))
+        : path_1.default.resolve(workingPath, 'handoff.config');
+    const candidates = SUPPORTED_CONFIG_EXTENSIONS.map((extension) => `${baseName}.${selection.name}${extension}`);
+    const { selected, ignored } = pickExisting(candidates);
+    if (!selected) {
+        if ((_a = context.knownProfiles) === null || _a === void 0 ? void 0 : _a.includes(selection.name)) {
+            return undefined;
+        }
+        throw new errors_1.HandoffConfigError(`Config profile "${selection.name}" (from ${selection.source}) not found. ` +
+            `Create one of: ${candidates.map((candidate) => path_1.default.basename(candidate)).join(', ')} in ${path_1.default.dirname(candidates[0])}.` +
+            (context.profileNotFoundHint ? ` ${context.profileNotFoundHint}` : ''));
+    }
+    warnIgnored(selected, ignored);
+    return selected;
+};
+/**
+ * Arrays and environment references are whole values: a later layer replaces them, including
+ * any reference default. Everything else keeps lodash semantics: plain
+ * objects merge recursively, scalars, `null` and functions replace, and `undefined` is skipped.
+ */
+const replaceValues = (destination, source) => {
+    if (source === undefined)
+        return undefined;
+    return Array.isArray(source) || (0, from_env_1.isEnvReference)(source) || (0, from_env_1.isEnvReference)(destination) ? source : undefined;
 };
 /**
  * Loads the handoff configuration for the given working directory and returns metadata.
  */
 const initConfigWithMetadata = (configOverride, context) => {
     var _a, _b, _c;
-    let config = {};
-    const { selected: configPath, ignored } = resolveConfigFilePath((_a = context === null || context === void 0 ? void 0 : context.workingPath) !== null && _a !== void 0 ? _a : (0, path_2.resolveWorkingPath)(), context === null || context === void 0 ? void 0 : context.configPath);
-    if (ignored.length > 0 && configPath) {
-        logger_1.Logger.warn(`Multiple config files found. Using "${path_1.default.basename(configPath)}" and ignoring: ${ignored
-            .map((filePath) => `"${path_1.default.basename(filePath)}"`)
-            .join(', ')}.`);
-    }
+    const workingPath = (_a = context === null || context === void 0 ? void 0 : context.workingPath) !== null && _a !== void 0 ? _a : (0, path_2.resolveWorkingPath)();
+    const { selected: configPath, ignored } = resolveConfigFilePath(workingPath, context === null || context === void 0 ? void 0 : context.configPath);
+    warnIgnored(configPath, ignored);
+    const profileSelection = (0, exports.resolveProfileSelection)(context === null || context === void 0 ? void 0 : context.profile);
+    const profileConfigPath = profileSelection ? resolveProfileFilePath(workingPath, configPath, profileSelection, context !== null && context !== void 0 ? context : {}) : undefined;
+    // Profile environment values must be present before the merged references resolve.
+    (0, env_1.loadProfileEnv)(profileSelection === null || profileSelection === void 0 ? void 0 : profileSelection.name);
+    const layers = [(0, defaults_1.defaultConfig)()];
     if (configPath) {
-        config = loadConfigFile(configPath);
+        layers.push(loadConfigLayer(configPath));
+    }
+    if (profileConfigPath) {
+        layers.push(loadConfigLayer(profileConfigPath));
     }
-    // Apply overrides if provided
     if (configOverride) {
-        Object.entries(configOverride).forEach(([key, value]) => {
-            if (value !== undefined) {
-                config[key] = value;
-            }
-        });
+        layers.push((0, helpers_1.normalizeConfig)(configOverride));
     }
+    const profileLabel = profileSelection
+        ? `"${profileSelection.name}" (from ${profileSelection.source})${profileConfigPath ? '' : ' - no config file, the base config is used unchanged'}`
+        : 'none selected';
+    logger_1.Logger.debug(`Config profile: ${profileLabel}`);
+    logger_1.Logger.debug(`Config files loaded: ${[configPath, profileConfigPath].filter(Boolean).join(', ') || 'none, using defaults'}`);
+    const merged = (0, mergeWith_1.default)({}, ...layers, replaceValues);
+    const config = (0, resolve_env_1.resolveConfigEnv)(merged, profileSelection === null || profileSelection === void 0 ? void 0 : profileSelection.name, layers[0]);
+    // Guards run on the resolved config so a profile cannot slip a removed setting past them.
     const entries = config.entries;
     if (entries && ('components' in entries || 'patterns' in entries)) {
-        throw new HandoffConfigError('entries.components and entries.patterns were removed. Use catalog.include. See UPGRADE.md#catalog-items.');
+        throw new errors_1.HandoffConfigError('entries.components and entries.patterns were removed. Use catalog.include. See UPGRADE.md#catalog-items.');
     }
     const format = (_c = (_b = config.runtime) === null || _b === void 0 ? void 0 : _b.workspace) === null || _c === void 0 ? void 0 : _c.declarationFormat;
     if (format !== undefined && !['ts', 'js', 'cjs'].includes(format)) {
-        throw new HandoffConfigError('Item declarations support ts, js, and cjs. Convert JSON declarations to defineCatalogItem. See UPGRADE.md#catalog-items.');
+        throw new errors_1.HandoffConfigError('Item declarations support ts, js, and cjs. Convert JSON declarations to defineCatalogItem. See UPGRADE.md#catalog-items.');
     }
-    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 };
+    return { config, configPath, profile: profileSelection === null || profileSelection === void 0 ? void 0 : profileSelection.name, profileConfigPath };
 };
 exports.initConfigWithMetadata = initConfigWithMetadata;
 /**
  * Loads the handoff configuration for the given working directory.
  *
  * Searches for config files in order: handoff.config.ts, handoff.config.js, handoff.config.cjs, handoff.config.json,
- * unless `context.configPath` names one explicitly. Merges file config with any provided overrides,
- * then applies defaults for missing values.
+ * unless `context.configPath` names one explicitly. A selected profile adds a `handoff.config.<profile>.*` sidecar,
+ * which only `context.knownProfiles` makes optional.
+ * Layers resolve as defaults, base config, profile, then the given overrides, merging plain objects recursively.
  *
  * @param configOverride - Optional partial config to override file-loaded values.
- * @param context - Optional working directory and explicit config file to load.
+ * @param context - Optional working directory, explicit config file, and profile to load.
  * @returns The fully resolved Config object.
  */
 const initConfig = (configOverride, context) => {

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

@@ -0,0 +1,5 @@
+import type { Config, ResolvedConfig } from '../types/config';
+export declare const DEFERRED_PATHS: Set<string>;
+export declare const configEnvName: (config: ResolvedConfig | null | undefined, path: string) => string | undefined;
+/** Resolve only the merged winner. Functions and non-plain objects retain their identity. */
+export declare const resolveConfigEnv: (config: Config, profile?: string, defaults?: Config) => ResolvedConfig;

package/dist/config/resolve-env.js

@@ -0,0 +1,102 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveConfigEnv = exports.configEnvName = exports.DEFERRED_PATHS = void 0;
+const isPlainObject_1 = __importDefault(require("lodash/isPlainObject"));
+const logger_1 = require("../utils/logger");
+const from_env_1 = require("./from-env");
+const errors_1 = require("./errors");
+exports.DEFERRED_PATHS = new Set(['runtime.registry.databaseUrl', 'runtime.registry.assetStorage.token']);
+const SECRET_PATHS = new Set(['dev_access_token', 'devAccessToken', 'runtime.registryConnection.accessToken']);
+/** Path prefixes whose resolved contents are JSON-baked into the bundle, so a reference would bake its value. */
+const BAKED_PATHS = ['runtime.registry.assetStorage.options'];
+const isBaked = (path) => BAKED_PATHS.some((baked) => path === baked || path.startsWith(`${baked}.`));
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ALIASES = {
+    HANDOFF_REGISTRY_URL: 'HANDOFF_CLOUD_URL',
+    HANDOFF_REGISTRY_ACCESS_TOKEN: 'HANDOFF_CLOUD_TOKEN',
+};
+const warnedAliases = new Set();
+const referenceNames = new WeakMap();
+const configEnvName = (config, path) => { var _a; return (_a = referenceNames.get(config)) === null || _a === void 0 ? void 0 : _a.get(path); };
+exports.configEnvName = configEnvName;
+const readEnv = (name) => {
+    const value = process.env[name];
+    const alias = ALIASES[name];
+    if (!alias || (value === null || value === void 0 ? void 0 : value.trim()))
+        return value;
+    const inherited = process.env[alias];
+    if (!(inherited === null || inherited === void 0 ? void 0 : inherited.trim()))
+        return value;
+    if (!warnedAliases.has(alias)) {
+        warnedAliases.add(alias);
+        logger_1.Logger.warn(`${alias} is deprecated and will be removed in a future release; set ${name} instead.`);
+    }
+    return inherited;
+};
+/** Resolve only the merged winner. Functions and non-plain objects retain their identity. */
+const resolveConfigEnv = (config, profile, defaults) => {
+    const names = new Map();
+    const fail = (path, message) => {
+        throw new errors_1.HandoffConfigError(`Config "${path}" (profile "${profile !== null && profile !== void 0 ? profile : 'default'}"): ${message}`);
+    };
+    const walk = (value, path, seed) => {
+        var _a;
+        const deferred = exports.DEFERRED_PATHS.has(path);
+        const secret = SECRET_PATHS.has(path);
+        if ((secret || deferred) && value !== undefined && !(0, from_env_1.isEnvReference)(value)) {
+            fail(path, 'Expected an environment reference, such as { $env: "VARIABLE_NAME" }. Literal values are not allowed.');
+        }
+        if ((0, from_env_1.isEnvReference)(value)) {
+            // Checked before the name, so the message names the supported pattern instead of the reference shape.
+            if (isBaked(path)) {
+                fail(path, 'Environment references are not allowed here because the resolved value is baked into the build. ' +
+                    "Put the variable name in options and read it through the adapter factory's `env` argument.");
+            }
+            if (typeof value.$env !== 'string' || !ENV_NAME.test(value.$env)) {
+                fail(path, 'Invalid environment variable name. Use letters, digits, and underscores, starting with a letter or underscore.');
+            }
+            const name = value.$env;
+            names.set(path, name);
+            if (Object.keys(value).some((key) => key !== '$env' && key !== 'default')) {
+                fail(path, `Environment variable "${name}" has an invalid reference shape.`);
+            }
+            if (deferred) {
+                if ('default' in value)
+                    fail(path, `Environment variable "${name}" cannot have a default because it is read by the deployed app.`);
+                return { $env: name };
+            }
+            // Secret defaults can mark an optional credential, but cannot embed a credential value.
+            if (secret && value.default !== undefined && value.default !== null && value.default !== '') {
+                fail(path, `Environment variable "${name}" cannot have a literal secret default.`);
+            }
+            const raw = readEnv(name);
+            if (raw === undefined) {
+                if (Object.prototype.hasOwnProperty.call(value, 'default'))
+                    return secret ? value.default : walk(value.default, path, seed);
+                fail(path, `Environment variable "${name}" is not set and has no default.`);
+            }
+            const typeHint = (_a = value.default) !== null && _a !== void 0 ? _a : ((0, from_env_1.isEnvReference)(seed) ? seed.default : seed);
+            if (typeof typeHint === 'boolean')
+                return raw === 'true';
+            if (typeof typeHint === 'number') {
+                const number = Number(raw);
+                if (!Number.isFinite(number))
+                    fail(path, `Environment variable "${name}" must contain a finite number.`);
+                return number;
+            }
+            return raw;
+        }
+        if (Array.isArray(value))
+            return value.map((entry, index) => walk(entry, `${path}.${index}`, seed === null || seed === void 0 ? void 0 : seed[index]));
+        if (!(0, isPlainObject_1.default)(value))
+            return value;
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, walk(entry, path ? `${path}.${key}` : key, seed === null || seed === void 0 ? void 0 : seed[key])]));
+    };
+    const resolved = walk(config, '', defaults);
+    referenceNames.set(resolved, names);
+    return resolved;
+};
+exports.resolveConfigEnv = resolveConfigEnv;

package/dist/config/runtime.d.ts

@@ -1,10 +1,10 @@
-import { Config, ConfigFileEntry, RuntimeConfig } from '../types/config';
+import { ResolvedConfig, ConfigFileEntry, RuntimeConfig } from '../types/config';
 /**
  * Handoff instance shape needed by initRuntimeConfig.
  * Avoids importing the full Handoff class to prevent circular deps.
  */
 interface HandoffContext {
-    config: Config;
+    config: ResolvedConfig;
     workingPath: string;
     modulePath: string;
 }
@@ -15,7 +15,7 @@ export declare const resolveComponentDeclaration: (componentDir: string, compone
 /**
  * Expands catalog.include into item directories and removes duplicate paths.
  */
-export declare const getCatalogItemDirectories: (config: Config, workingPath: string) => string[];
+export declare const getCatalogItemDirectories: (config: ResolvedConfig, workingPath: string) => string[];
 /**
  * Initializes the runtime configuration by resolving component entries,
  * SCSS/JS paths, and transformer options from the handoff config.

package/dist/config/runtime.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toLowerCaseKeysAndValues = exports.getComponentsForPath = exports.isComponentDirectory = exports.initRuntimeConfig = exports.getCatalogItemDirectories = exports.resolveComponentDeclaration = void 0;
 const esbuild_1 = __importDefault(require("esbuild"));
+const build_1 = require("../transformers/utils/build");
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const module_1 = require("module");
 const path_1 = __importDefault(require("path"));
@@ -17,7 +18,8 @@ const markdown_1 = require("../utils/markdown");
 const pages_1 = require("../utils/pages");
 const path_2 = require("../utils/path");
 const page_1 = require("./normalizers/page");
-const DECLARATION_EXTENSIONS = ['ts', 'js', 'cjs'];
+/** `.tsx`/`.jsx` are accepted so a preview can write its `render` as JSX. */
+const DECLARATION_EXTENSIONS = ['tsx', 'ts', 'jsx', 'js', 'cjs'];
 const getDeclarationFiles = (componentBaseName) => DECLARATION_EXTENSIONS.map((ext) => `${componentBaseName}.handoff.${ext}`);
 const findPreferredDeclaration = (componentDir, componentBaseName) => {
     const exactCandidates = getDeclarationFiles(componentBaseName);
@@ -25,7 +27,7 @@ const findPreferredDeclaration = (componentDir, componentBaseName) => {
     if (exactMatch)
         return exactMatch;
     const allFiles = fs_extra_1.default.existsSync(componentDir) ? fs_extra_1.default.readdirSync(componentDir) : [];
-    const declarationFiles = allFiles.filter((file) => /\.handoff\.(ts|js|cjs)$/.test(file)).sort((a, b) => a.localeCompare(b));
+    const declarationFiles = allFiles.filter((file) => /\.handoff\.(tsx|ts|jsx|js|cjs)$/.test(file)).sort((a, b) => a.localeCompare(b));
     if (!declarationFiles.length)
         return undefined;
     for (const ext of DECLARATION_EXTENSIONS) {
@@ -52,6 +54,7 @@ const evaluateDeclaration = (filePath, handoffModulePath) => {
         logLevel: 'silent',
         jsx: 'automatic',
         external: ['react', 'react-dom', 'handoff-app'],
+        loader: build_1.STYLE_IMPORT_LOADERS,
     });
     const code = (_b = (_a = buildResult.outputFiles) === null || _a === void 0 ? void 0 : _a[0]) === null || _b === void 0 ? void 0 : _b.text;
     if (!code) {
@@ -178,7 +181,7 @@ const initRuntimeConfig = (handoff) => {
         const declaration = (0, exports.resolveComponentDeclaration)(itemPath, itemBaseName);
         if (!declaration) {
             const declarationFiles = getDeclarationFiles(itemBaseName);
-            logger_1.Logger.warn(`Missing catalog declaration (use .handoff.ts, .handoff.js, or .handoff.cjs; see UPGRADE.md#catalog-items): ${path_1.default.resolve(itemPath, declarationFiles.join(' or '))}`);
+            logger_1.Logger.warn(`Missing catalog declaration (use .handoff.tsx, .handoff.ts, .handoff.jsx, .handoff.js, or .handoff.cjs; see UPGRADE.md#catalog-items): ${path_1.default.resolve(itemPath, declarationFiles.join(' or '))}`);
             continue;
         }
         const declarationPath = path_1.default.resolve(itemPath, declaration.fileName);
@@ -361,8 +364,8 @@ const injectPatternPreviews = (result) => {
             }
             // Case 3: args present (with or without preview base) -> create synthetic preview
             let resolvedValues = {};
+            const basePreview = ref.preview ? (_b = component.previews) === null || _b === void 0 ? void 0 : _b[ref.preview] : undefined;
             if (ref.preview) {
-                const basePreview = (_b = component.previews) === null || _b === void 0 ? void 0 : _b[ref.preview];
                 if (basePreview) {
                     resolvedValues = Object.assign({}, basePreview.values);
                 }
@@ -374,12 +377,7 @@ const injectPatternPreviews = (result) => {
             resolvedValues = Object.assign(Object.assign({}, resolvedValues), ref.args);
             const syntheticKey = `__pattern_${patternId}_${i}`;
             component.internalPatternPreviews = component.internalPatternPreviews || {};
-            component.internalPatternPreviews[syntheticKey] = {
-                title: syntheticKey,
-                values: resolvedValues,
-                url: '',
-                sourcePreview: ref.preview,
-            };
+            component.internalPatternPreviews[syntheticKey] = Object.assign({ title: syntheticKey, values: resolvedValues, url: '', sourcePreview: ref.preview }, ((basePreview === null || basePreview === void 0 ? void 0 : basePreview.render) ? { render: basePreview.render } : {}));
             ref.resolvedPreview = syntheticKey;
             if (ref.resolved === undefined) {
                 ref.resolved = true;

package/dist/config/validator.d.ts

@@ -1,4 +1,4 @@
-import { Config } from '../types/config';
+import { ResolvedConfig } from '../types/config';
 /**
  * Validates that the configuration has the required Figma credentials.
  *
@@ -6,4 +6,4 @@ import { Config } from '../types/config';
  * @returns The validated config (same reference).
  * @throws {Error} If required Figma credentials are missing.
  */
-export declare const validateConfig: (config: Config) => Config;
+export declare const validateConfig: (config: ResolvedConfig) => ResolvedConfig;

package/dist/config/validator.js

@@ -11,13 +11,11 @@ const logger_1 = require("../utils/logger");
  */
 const validateConfig = (config) => {
     // TODO: Check to see if the exported folder exists before we run start
-    if (!config.figma_project_id && !process.env.HANDOFF_FIGMA_PROJECT_ID) {
-        // check to see if we can get this from the env
+    if (!config.figma_project_id) {
         logger_1.Logger.error('Figma Project ID missing. Please set HANDOFF_FIGMA_PROJECT_ID or run "handoff-app fetch".');
         throw new Error('Cannot initialize configuration');
     }
-    if (!config.dev_access_token && !process.env.HANDOFF_DEV_ACCESS_TOKEN) {
-        // check to see if we can get this from the env
+    if (!config.dev_access_token) {
         logger_1.Logger.error('Figma Access Token missing. Please set HANDOFF_DEV_ACCESS_TOKEN or run "handoff-app fetch".');
         throw new Error('Cannot initialize configuration');
     }

package/dist/handlebars.d.ts

@@ -1,5 +1,13 @@
-import type { CatalogItem, CatalogItemMeta } from './catalog/types';
-export type { CatalogItem, CatalogItemMeta, CatalogPreview, CompositionRef, Preview, SourceDescriptor } from './catalog/types';
+import type { CatalogItem, CatalogItemMeta, CatalogPreview as RendererPreview } from './catalog/types';
+export type { CatalogItem, CatalogItemMeta, CompositionRef, SourceDescriptor } from './catalog/types';
+/** A template renderer never calls a preview `render`, so declaring one is an error, not a no-op. */
+export type CatalogPreview<TArgs = Record<string, unknown>> = Omit<RendererPreview<TArgs>, 'render'> & {
+    render?: never;
+};
+/** Preview type for a Handlebars catalog item, with its argument type applied. */
+export type Preview<TItem> = TItem extends {
+    readonly __args?: infer TArgs;
+} ? CatalogPreview<Partial<NonNullable<TArgs>>> : never;
 /**
  * Declares a Handlebars catalog item. `implementation` is the path to its `.hbs` template. The
  * renderer comes from this module, so the build fails an item whose file does not match it.

package/dist/index.d.ts

@@ -1,10 +1,10 @@
-import 'dotenv/config';
+import './config/env';
 import { Types as CoreTypes, Handoff as HandoffRunner } from 'handoff-core';
 import { type BuildPackage, type BuildTarget } from './app-builder';
 import { type RegistryEntityKind } from './registry/content-kinds';
 import type { TransferEntityKind } from './registry/transfer';
 import { type HandoffStore } from './store';
-import { Config, ConfigFileEntry, RuntimeConfig } from './types/config';
+import { Config, ResolvedConfig, ConfigFileEntry, RuntimeConfig } from './types/config';
 /** How a {@link Handoff} instance is set up. */
 export interface HandoffOptions {
     debug?: boolean;
@@ -21,6 +21,19 @@ export interface HandoffOptions {
     config?: Partial<Config>;
     /** Explicit config file (the CLI's `-c, --config`), resolved from the working path. */
     configPath?: string;
+    /**
+     * Config profile to merge onto the base config (the CLI's `--profile`). It overrides
+     * `HANDOFF_PROFILE`, and a selected profile has to resolve to a `handoff.config.<profile>.*` file
+     * unless {@link profileWithoutConfig} widens that.
+     */
+    profile?: string;
+    /**
+     * What a selected profile may resolve to when it has no config file. `'saved-login'` accepts a name
+     * a saved registry login uses, so publish and checkout can address a registry that no config file
+     * describes. `'any'` accepts any valid name, for the `login` command that creates the login. Unset,
+     * a profile must name a config file, so a typo cannot silently run with the base config.
+     */
+    profileWithoutConfig?: 'saved-login' | 'any';
 }
 /**
  * A content kind to act on, optionally narrowed to specific ids. The plain form is the common case
@@ -31,7 +44,7 @@ export type ContentTarget = RegistryEntityKind | {
     ids?: string[];
 };
 declare class Handoff {
-    config: Config | null;
+    config: ResolvedConfig | null;
     debug: boolean;
     force: boolean;
     dryRun: boolean;
@@ -56,10 +69,18 @@ declare class Handoff {
     private _configFilePaths;
     private _configFileIndex;
     private _mainConfigFilePath?;
+    private _profileConfigFilePath?;
+    private _profile?;
     private _documentationObjectCache?;
     private _handoffRunner?;
     constructor(options?: HandoffOptions);
     private construct;
+    /**
+     * What a selected profile may resolve to besides a config file, and how to explain a name that
+     * resolves to nothing. A command that does not accept a login still names one it found, so the
+     * difference between the two kinds of profile is visible rather than puzzling.
+     */
+    private profilesWithoutConfig;
     init(configOverride?: Partial<Config>): Handoff;
     reload(): Handoff;
     preRunner(validate?: boolean): Handoff;
@@ -215,6 +236,12 @@ declare class Handoff {
      * Gets the selected main config file path if one exists.
      */
     getMainConfigFilePath(): string | undefined;
+    getProfile(): string | undefined;
+    /**
+     * True for the base config file and for the profile file merged onto it. Both carry project-wide
+     * settings, so a change to either one invalidates every entity rather than a single declaration.
+     */
+    isMainConfigFile(filePath: string): boolean;
     getConfigFileEntry(configPath: string): ConfigFileEntry | undefined;
     /**
      * Clears all cached data
@@ -228,8 +255,10 @@ declare class Handoff {
      */
     private readJsonFile;
 }
-export type { Config, RegisterHandlebarsHelpersContext } from './types/config';
+export type { Config, ResolvedConfig, RegisterHandlebarsHelpersContext } from './types/config';
 export { defineConfig } from './config';
+export { fromEnv } from './config/from-env';
+export type { EnvValue, EnvSecret, RuntimeEnvReference } from './config/from-env';
 export type { CatalogItem, CatalogItemEntries, CatalogItemInput, CatalogItemMeta, CatalogPreview, CompositionRef, Preview, SourceDescriptor, SourceFormat, RendererKind, } from './catalog';
 export { defineAssetStorage } from './registry/asset-storage/define';
 export type { AssetStorage, AssetStorageContext, AssetStorageFactory, AssetStorageInput, AssetStorageReadResult, } from './registry/asset-storage/types';