handoff-app 2.0.0-7 → 2.0.0-8

package/dist/config/loader.js

@@ -3,31 +3,32 @@ 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 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({
@@ -75,6 +76,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 +107,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/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/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';

package/dist/index.js

@@ -35,18 +35,19 @@ 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.defineAssetStorage = exports.defineConfig = void 0;
-require("dotenv/config");
+exports.CoreTypes = exports.CoreTransformerUtils = exports.CoreTransformers = exports.defineAssetStorage = exports.fromEnv = exports.defineConfig = void 0;
+require("./config/env");
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const handoff_core_1 = require("handoff-core");
 const path_1 = __importDefault(require("path"));
 const app_builder_1 = __importStar(require("./app-builder"));
 const eject_1 = require("./cli/eject");
 const make_1 = require("./cli/make");
+const store_1 = require("./cli/auth/store");
 const config_1 = require("./config");
 const pipeline_1 = __importStar(require("./pipeline"));
 const content_kinds_1 = require("./registry/content-kinds");
-const store_1 = require("./store");
+const store_2 = require("./store");
 const builder_1 = __importStar(require("./transformers/preview/component/builder"));
 const logger_1 = require("./utils/logger");
 const path_2 = require("./utils/path");
@@ -114,7 +115,7 @@ class Handoff {
      */
     get store() {
         if (!this._store) {
-            this._store = (0, store_1.createFilesystemStore)(this);
+            this._store = (0, store_2.createFilesystemStore)(this);
         }
         return this._store;
     }
@@ -134,24 +135,52 @@ class Handoff {
         this.construct(options);
     }
     construct(options) {
-        var _a, _b, _c, _d;
-        this.config = null;
-        this.debug = (_a = options.debug) !== null && _a !== void 0 ? _a : false;
-        this.force = (_b = options.force) !== null && _b !== void 0 ? _b : false;
-        this.dryRun = (_c = options.dryRun) !== null && _c !== void 0 ? _c : false;
-        this.skipBuild = (_d = options.skipBuild) !== null && _d !== void 0 ? _d : false;
+        var _a, _b, _c, _d, _e;
+        // Ahead of `Logger.init` so a profile env file can set `HANDOFF_LOG_LEVEL` and `HANDOFF_LOG_SCOPES`.
+        (0, config_1.loadProfileEnv)((_a = (0, config_1.resolveProfileSelection)(options.profile)) === null || _a === void 0 ? void 0 : _a.name);
+        this.debug = (_b = options.debug) !== null && _b !== void 0 ? _b : false;
+        this.force = (_c = options.force) !== null && _c !== void 0 ? _c : false;
+        this.dryRun = (_d = options.dryRun) !== null && _d !== void 0 ? _d : false;
+        this.skipBuild = (_e = options.skipBuild) !== null && _e !== void 0 ? _e : false;
         logger_1.Logger.init({ debug: this.debug });
         this.init(options.config);
     }
+    /**
+     * 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.
+     */
+    profilesWithoutConfig() {
+        var _a;
+        const selected = (_a = (0, config_1.resolveProfileSelection)(this._options.profile)) === null || _a === void 0 ? void 0 : _a.name;
+        if (!selected) {
+            return {};
+        }
+        const accepts = this._options.profileWithoutConfig;
+        const names = (0, store_1.loginProfileNames)(this.workingPath);
+        if (!accepts) {
+            return names.includes(selected)
+                ? {
+                    profileNotFoundHint: 'A saved registry login uses that name, but only login, logout, publish, and checkout accept a profile without a config file.',
+                }
+                : {};
+        }
+        return {
+            knownProfiles: accepts === 'any' ? [...names, selected] : names,
+            profileNotFoundHint: 'No saved registry login uses that name either. Run `handoff-app login --profile <name> --url <registry-url>` to create one.',
+        };
+    }
     init(configOverride) {
         var _a, _b, _c;
-        const configResult = (0, config_1.initConfigWithMetadata)(configOverride !== null && configOverride !== void 0 ? configOverride : {}, {
-            workingPath: this.workingPath,
-            configPath: this._options.configPath,
-        });
+        // Resolved before anything is assigned: a reload that throws - a deleted profile file, a
+        // broken config - then leaves the last good state in place for the watchers holding this
+        // instance.
+        const configResult = (0, config_1.initConfigWithMetadata)(configOverride !== null && configOverride !== void 0 ? configOverride : {}, Object.assign({ workingPath: this.workingPath, configPath: this._options.configPath, profile: this._options.profile }, this.profilesWithoutConfig()));
         const config = configResult.config;
         this.config = config;
         this._mainConfigFilePath = configResult.configPath;
+        this._profileConfigFilePath = configResult.profileConfigPath;
+        this._profile = configResult.profile;
         this.exportsDirectory = (_a = config.exportsOutputDirectory) !== null && _a !== void 0 ? _a : this.exportsDirectory;
         this.sitesDirectory = (_b = config.sitesOutputDirectory) !== null && _b !== void 0 ? _b : this.exportsDirectory;
         [this.runtimeConfig, this._configFilePaths, this._configFileIndex] = (0, config_1.initRuntimeConfig)(this);
@@ -569,8 +598,8 @@ class Handoff {
      * @returns {string[]} Array of absolute paths to config files
      */
     getConfigFilePaths() {
-        const combined = this._mainConfigFilePath ? [this._mainConfigFilePath, ...this._configFilePaths] : this._configFilePaths;
-        return Array.from(new Set(combined));
+        const mainPaths = [this._mainConfigFilePath, this._profileConfigFilePath].filter(Boolean);
+        return Array.from(new Set([...mainPaths, ...this._configFilePaths]));
     }
     /**
      * Gets the selected main config file path if one exists.
@@ -578,6 +607,19 @@ class Handoff {
     getMainConfigFilePath() {
         return this._mainConfigFilePath;
     }
+    getProfile() {
+        return this._profile;
+    }
+    /**
+     * 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) {
+        const normalized = (0, path_2.normalizePathForCompare)(filePath);
+        return [this._mainConfigFilePath, this._profileConfigFilePath]
+            .filter(Boolean)
+            .some((mainPath) => (0, path_2.normalizePathForCompare)(mainPath) === normalized);
+    }
     getConfigFileEntry(configPath) {
         return this._configFileIndex.get((0, path_2.normalizePathForCompare)(configPath));
     }
@@ -606,6 +648,8 @@ class Handoff {
 }
 var config_2 = require("./config");
 Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return config_2.defineConfig; } });
+var from_env_1 = require("./config/from-env");
+Object.defineProperty(exports, "fromEnv", { enumerable: true, get: function () { return from_env_1.fromEnv; } });
 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

package/dist/pipeline/index.d.ts

@@ -1,4 +1,4 @@
-import 'dotenv/config';
+import '../config/env';
 import Handoff from '..';
 export { readPrevJSONFile, zip, zipAssets } from './archive';
 export { buildComponents } from './components';

package/dist/pipeline/index.js

@@ -13,7 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildPatterns = exports.buildComponents = exports.zipAssets = exports.zip = exports.readPrevJSONFile = void 0;
-require("dotenv/config");
+require("../config/env");
 const app_builder_1 = __importDefault(require("../app-builder"));
 const logger_1 = require("../utils/logger");
 const figma_1 = require("./figma");

package/dist/registry/asset-storage/adapters/vercel-blob.js

@@ -52,7 +52,7 @@ const createVercelBlobStorage = (params) => {
         const token = (_a = process.env[params.tokenEnv]) === null || _a === void 0 ? void 0 : _a.trim();
         if (!token) {
             throw new Error(`Vercel Blob storage is configured but the token env var "${params.tokenEnv}" is not set. ` +
-                'Set it to a Blob read/write token, or change runtime.registry.assetStorage.tokenEnv.');
+                'Set it to a Blob read/write token, or change runtime.registry.assetStorage.token.');
         }
         return token;
     };