handoff-app 2.0.0-7 → 2.0.0-8

package/src/config/defaults.ts

@@ -1,5 +1,6 @@
+import { fromEnv } from './from-env';
 import { resolveRegistryConnection } from '../registry/connection';
-import { ClientConfig, Config } from '../types/config';
+import { ClientConfig, Config, ResolvedConfig } from '../types/config';
 
 export interface ImageStyle {
   name: string;
@@ -10,25 +11,34 @@ export interface ImageStyle {
 }
 
 /** Whether the MCP endpoint is served. On unless `runtime.mcp` is explicitly `false`. */
-export const isMcpEnabled = (config: Config | null | undefined): boolean => config?.runtime?.mcp !== false;
+export const isMcpEnabled = (config: Pick<Config, 'runtime'> | Pick<ResolvedConfig, 'runtime'> | null | undefined): boolean =>
+  config?.runtime?.mcp !== false;
 
 export const defaultConfig = (): Config => ({
-  dev_access_token: process.env.HANDOFF_DEV_ACCESS_TOKEN ?? null,
-  figma_project_id: process.env.HANDOFF_FIGMA_PROJECT_ID ?? null,
+  dev_access_token: fromEnv('HANDOFF_DEV_ACCESS_TOKEN', { default: null }),
+  figma_project_id: fromEnv('HANDOFF_FIGMA_PROJECT_ID', { default: null }),
   runtime: {
     mode: 'workspace',
+    registryConnection: {
+      url: fromEnv('HANDOFF_REGISTRY_URL', { default: '' }),
+      accessToken: fromEnv('HANDOFF_REGISTRY_ACCESS_TOKEN', { default: '' }),
+    },
+    registry: {
+      databaseUrl: fromEnv('DATABASE_URL'),
+      assetStorage: { token: fromEnv('BLOB_READ_WRITE_TOKEN') },
+    },
   },
-  exportsOutputDirectory: process.env.HANDOFF_OUTPUT_DIR ?? 'exported',
-  sitesOutputDirectory: process.env.HANDOFF_SITES_DIR ?? 'out',
-  useVariables: process.env.HANDOFF_USE_VARIABLES === 'true',
+  exportsOutputDirectory: fromEnv('HANDOFF_OUTPUT_DIR', { default: 'exported' }),
+  sitesOutputDirectory: fromEnv('HANDOFF_SITES_DIR', { default: 'out' }),
+  useVariables: fromEnv('HANDOFF_USE_VARIABLES', { default: false }),
   reactDocgen: {
     maxDepth: 7,
     excludeDirectories: ['dist', 'build', '.next'],
   },
   app: {
     theme: 'default',
-    title: 'Convertiv Design System',
-    client: 'Convertiv',
+    title: 'Handoff Design System',
+    client: 'Handoff',
     google_tag_manager: null,
     attribution: true,
     type_copy: 'Almost before we knew it, we had left the ground.',
@@ -54,9 +64,9 @@ export const defaultConfig = (): Config => ({
       desktop: { size: 1100, name: 'Large' },
     },
     ports: {
-      app: Number(process.env.HANDOFF_APP_PORT) || 3000,
-      websocket: Number(process.env.HANDOFF_WEBSOCKET_PORT) || 3001
-    }
+      app: fromEnv('HANDOFF_APP_PORT', { default: 3000 }),
+      websocket: fromEnv('HANDOFF_WEBSOCKET_PORT', { default: 3001 }),
+    },
   },
 });
 
@@ -66,7 +76,7 @@ export const defaultConfig = (): Config => ({
  * @param config - The full handoff Config object.
  * @returns The client configuration object.
  */
-export const getClientConfig = (config: Config): ClientConfig => {
+export const getClientConfig = (config: ResolvedConfig): ClientConfig => {
   const {
     app,
     exportsOutputDirectory,
@@ -74,7 +84,7 @@ export const getClientConfig = (config: Config): ClientConfig => {
     assets_zip_links = { icons: null, logos: null },
     useVariables,
     runtime,
-  } = { ...defaultConfig(), ...config };
+  } = config;
 
   const mode = runtime?.mode ?? 'workspace';
   // Connected-workspace affordance: only a workspace with a resolvable registry URL is "connected".

package/src/config/env.ts

@@ -0,0 +1,41 @@
+import dotenv from 'dotenv';
+import fs from 'fs-extra';
+import path from 'path';
+
+/**
+ * Environment variables that were already set when the process started. They outrank every `.env`
+ * file, so an inline `DATABASE_URL=… handoff-app db:migrate` wins over what a file says. Recorded
+ * before the base `.env` is read, which is why this module is imported first.
+ */
+const processEnvKeys = new Set(Object.keys(process.env));
+
+// The base `.env`, read from the directory the command runs in, at module load so `process.env` is
+// populated before the first Handoff is constructed.
+dotenv.config();
+
+/**
+ * Apply `.env.<profile>` on top of the base `.env` for the selected profile. The file is optional:
+ * a profile needs a config file, not an env file.
+ *
+ * Precedence is the process environment, then the profile env file, then `.env`. Dotenv's own
+ * `override` option cannot express that - it would replace the values the shell supplied too - so
+ * the keys already present at startup are skipped here.
+ */
+export const loadProfileEnv = (profile?: string, directory: string = process.cwd()): void => {
+  if (!profile) {
+    return;
+  }
+
+  const envPath = path.resolve(directory, `.env.${profile}`);
+  if (!fs.existsSync(envPath)) {
+    return;
+  }
+
+  const parsed = dotenv.parse(fs.readFileSync(envPath));
+  for (const [key, value] of Object.entries(parsed)) {
+    if (processEnvKeys.has(key)) {
+      continue;
+    }
+    process.env[key] = value;
+  }
+};

package/src/config/errors.ts

@@ -0,0 +1,7 @@
+/** Raised when configuration cannot be loaded or resolved. */
+export class HandoffConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'HandoffConfigError';
+  }
+}

package/src/config/from-env.ts

@@ -0,0 +1,26 @@
+/** A JSON-compatible environment reference. Creating one never reads the environment. */
+export type EnvReference<T> = { $env: string; default?: T };
+
+/**
+ * Use for values that can be literals or environment references, such as output directories.
+ * References resolve at config load; ResolvedConfig holds the value.
+ */
+export type EnvValue<T> = T | EnvReference<T>;
+
+/**
+ * Use for credentials the CLI needs, such as the Figma token. Only references are allowed.
+ * References resolve at config load; ResolvedConfig holds the secret value.
+ */
+export type EnvSecret<T> = EnvReference<T>;
+
+/**
+ * Use for values the deployed app reads, such as its database URL. Only references are allowed.
+ * ResolvedConfig keeps the reference; the build stores its name, and the deployed app reads the value at runtime.
+ */
+export type RuntimeEnvReference<T> = EnvReference<T>;
+
+export const fromEnv = <T = string>(name: string, options?: { default: T }): EnvReference<T> =>
+  options === undefined ? { $env: name } : { $env: name, default: options.default };
+
+export const isEnvReference = (value: unknown): value is EnvReference<unknown> =>
+  value !== null && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, '$env');

package/src/config/helpers.ts

@@ -29,8 +29,8 @@ export const normalizeConfig = (config: Config): Config => {
 
   return {
     ...(rest as Config),
-    dev_access_token: devAccessToken ?? config.dev_access_token,
-    figma_project_id: figmaProjectId ?? config.figma_project_id,
+    dev_access_token: devAccessToken !== undefined ? devAccessToken : config.dev_access_token,
+    figma_project_id: figmaProjectId !== undefined ? figmaProjectId : config.figma_project_id,
     assets_zip_links: assetsZipLinks ?? config.assets_zip_links,
     app: normalizeAppConfig(app),
   };
@@ -39,5 +39,7 @@ export const normalizeConfig = (config: Config): Config => {
 /**
  * Optional helper for strongly-typed config authoring.
  * It normalizes modern camelCase keys to legacy runtime keys.
+ *
+ * Every part of `Config` is optional, so this types a profile as well as a base config.
  */
 export const defineConfig = (config: Config): Config => normalizeConfig(config);

package/src/config/index.ts

@@ -2,8 +2,11 @@
 export { defaultConfig, getClientConfig, isMcpEnabled } from './defaults';
 export type { ImageStyle } from './defaults';
 
+// Environment files
+export { loadProfileEnv } from './env';
+
 // Config file loading
-export { HandoffConfigError, initConfig, initConfigWithMetadata } from './loader';
+export { CONFIG_FILE_PREFERENCE, HandoffConfigError, initConfig, initConfigWithMetadata, resolveProfileSelection } from './loader';
 export type { ConfigLoadContext } from './loader';
 
 // Config helpers

package/src/config/loader.ts

@@ -1,14 +1,19 @@
 import esbuild from 'esbuild';
 import fs from 'fs-extra';
-import merge from 'lodash/merge';
+import mergeWith from 'lodash/mergeWith';
 import { createRequire } from 'module';
 import path from 'path';
-import { Config } from '../types/config';
+import { Config, ResolvedConfig } from '../types/config';
 import { Logger } from '../utils/logger';
 import { resolveWorkingPath } from '../utils/path';
 import { defaultConfig } from './defaults';
+import { loadProfileEnv } from './env';
+import { normalizeConfig } from './helpers';
+import { HandoffConfigError } from './errors';
+import { isEnvReference } from './from-env';
+import { resolveConfigEnv } from './resolve-env';
 
-const CONFIG_FILE_PREFERENCE = [
+export const CONFIG_FILE_PREFERENCE = [
   'handoff.config.ts',
   'handoff.config.js',
   'handoff.config.cjs',
@@ -18,17 +23,17 @@ const CONFIG_FILE_PREFERENCE = [
 /** 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.extname(fileName))));
 
-/** Raised when an explicitly requested config file cannot be used. */
-export class HandoffConfigError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'HandoffConfigError';
-  }
-}
+/** A profile name becomes part of a file name, so it stays lowercase letters, numbers, and hyphens. */
+const PROFILE_NAME_PATTERN = /^[a-z0-9-]+$/;
+
+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. */
@@ -37,8 +42,21 @@ 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' };
+
 const evaluateTypeScriptConfig = (filePath: string, handoffModulePath: string): any => {
   const buildResult = esbuild.buildSync({
     entryPoints: [filePath],
@@ -91,6 +109,36 @@ const loadConfigFile = (configPath: string): Config => {
   return (importedConfig.default || importedConfig) as Config;
 };
 
+/**
+ * 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: string): Partial<Config> => normalizeConfig(loadConfigFile(configPath));
+
+const pickExisting = (candidates: string[]): { selected?: string; ignored: string[] } => {
+  const existing = candidates.filter((filePath) => fs.existsSync(filePath));
+
+  if (!existing.length) {
+    return { selected: undefined, ignored: [] };
+  }
+
+  const [selected, ...ignored] = existing;
+  return { selected, ignored };
+};
+
+const warnIgnored = (selected: string | undefined, ignored: string[]): void => {
+  if (!selected || ignored.length === 0) {
+    return;
+  }
+
+  Logger.warn(
+    `Multiple config files found. Using "${path.basename(selected)}" and ignoring: ${ignored
+      .map((filePath) => `"${path.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
@@ -113,46 +161,111 @@ const resolveConfigFilePath = (workingPath: string, requestedPath?: string): { s
     return { selected, ignored: [] };
   }
 
-  const existing = CONFIG_FILE_PREFERENCE
-    .map((fileName) => path.resolve(workingPath, fileName))
-    .filter((filePath) => fs.existsSync(filePath));
+  return pickExisting(CONFIG_FILE_PREFERENCE.map((fileName) => path.resolve(workingPath, fileName)));
+};
 
-  if (!existing.length) {
-    return { selected: undefined, ignored: [] };
+/** `--profile` wins over `HANDOFF_PROFILE`, and an empty value counts as unset. */
+export const resolveProfileSelection = (requestedProfile?: string): ProfileSelection | undefined => {
+  const fromOption = requestedProfile?.trim();
+  if (fromOption) {
+    return { name: fromOption, source: '--profile' };
   }
 
-  const [selected, ...ignored] = existing;
-  return { selected, ignored };
+  const fromEnvironment = process.env.HANDOFF_PROFILE?.trim();
+  if (fromEnvironment) {
+    return { name: fromEnvironment, source: 'HANDOFF_PROFILE' };
+  }
+
+  return undefined;
 };
 
 /**
- * Loads the handoff configuration for the given working directory and returns metadata.
+ * 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.
  */
-export const initConfigWithMetadata = (configOverride?: Partial<Config>, context?: ConfigLoadContext): ConfigLoadResult => {
-  let config: Partial<Config> = {};
-  const { selected: configPath, ignored } = resolveConfigFilePath(context?.workingPath ?? resolveWorkingPath(), context?.configPath);
-
-  if (ignored.length > 0 && configPath) {
-    Logger.warn(
-      `Multiple config files found. Using "${path.basename(configPath)}" and ignoring: ${ignored
-        .map((filePath) => `"${path.basename(filePath)}"`)
-        .join(', ')}.`
+const resolveProfileFilePath = (
+  workingPath: string,
+  baseConfigPath: string | undefined,
+  selection: ProfileSelection,
+  context: ConfigLoadContext
+): string | undefined => {
+  if (!PROFILE_NAME_PATTERN.test(selection.name)) {
+    throw new HandoffConfigError(
+      `Invalid config profile "${selection.name}" (from ${selection.source}). ` +
+        `A profile name can contain lowercase letters, numbers, and hyphens.`
     );
   }
 
-  if (configPath) {
-    config = loadConfigFile(configPath);
+  const baseName = baseConfigPath
+    ? path.join(path.dirname(baseConfigPath), path.basename(baseConfigPath, path.extname(baseConfigPath)))
+    : path.resolve(workingPath, 'handoff.config');
+  const candidates = SUPPORTED_CONFIG_EXTENSIONS.map((extension) => `${baseName}.${selection.name}${extension}`);
+  const { selected, ignored } = pickExisting(candidates);
+
+  if (!selected) {
+    if (context.knownProfiles?.includes(selection.name)) {
+      return undefined;
+    }
+    throw new HandoffConfigError(
+      `Config profile "${selection.name}" (from ${selection.source}) not found. ` +
+        `Create one of: ${candidates.map((candidate) => path.basename(candidate)).join(', ')} in ${path.dirname(candidates[0])}.` +
+        (context.profileNotFoundHint ? ` ${context.profileNotFoundHint}` : '')
+    );
   }
 
-  // Apply overrides if provided
+  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: unknown, source: unknown) => {
+  if (source === undefined) return undefined;
+  return Array.isArray(source) || isEnvReference(source) || isEnvReference(destination) ? source : undefined;
+};
+
+/**
+ * Loads the handoff configuration for the given working directory and returns metadata.
+ */
+export const initConfigWithMetadata = (configOverride?: Partial<Config>, context?: ConfigLoadContext): ConfigLoadResult => {
+  const workingPath = context?.workingPath ?? resolveWorkingPath();
+  const { selected: configPath, ignored } = resolveConfigFilePath(workingPath, context?.configPath);
+  warnIgnored(configPath, ignored);
+
+  const profileSelection = resolveProfileSelection(context?.profile);
+  const profileConfigPath = profileSelection ? resolveProfileFilePath(workingPath, configPath, profileSelection, context ?? {}) : undefined;
+
+  // Profile environment values must be present before the merged references resolve.
+  loadProfileEnv(profileSelection?.name);
+
+  const layers: Partial<Config>[] = [defaultConfig()];
+  if (configPath) {
+    layers.push(loadConfigLayer(configPath));
+  }
+  if (profileConfigPath) {
+    layers.push(loadConfigLayer(profileConfigPath));
+  }
   if (configOverride) {
-    (Object.entries(configOverride) as [keyof Config, Config[keyof Config]][]).forEach(([key, value]) => {
-      if (value !== undefined) {
-        (config as Record<string, unknown>)[key as string] = value;
-      }
-    });
+    layers.push(normalizeConfig(configOverride as Config));
   }
 
+  const profileLabel = profileSelection
+    ? `"${profileSelection.name}" (from ${profileSelection.source})${profileConfigPath ? '' : ' - no config file, the base config is used unchanged'}`
+    : 'none selected';
+  Logger.debug(`Config profile: ${profileLabel}`);
+  Logger.debug(`Config files loaded: ${[configPath, profileConfigPath].filter(Boolean).join(', ') || 'none, using defaults'}`);
+
+  const merged = mergeWith({}, ...layers, replaceValues) as Config;
+  const config = resolveConfigEnv(merged, profileSelection?.name, layers[0]);
+
+  // Guards run on the resolved config so a profile cannot slip a removed setting past them.
   const entries = config.entries as Record<string, unknown> | undefined;
   if (entries && ('components' in entries || 'patterns' in entries)) {
     throw new HandoffConfigError(
@@ -165,29 +278,22 @@ export const initConfigWithMetadata = (configOverride?: Partial<Config>, context
       'Item declarations support ts, js, and cjs. Convert JSON declarations to defineCatalogItem. See UPGRADE.md#catalog-items.'
     );
   }
-  const defaults = 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 = {
-    ...defaults,
-    ...config,
-    runtime: merge({}, defaults.runtime, config.runtime),
-  } as Config;
-  return { config: resolvedConfig, configPath };
+
+  return { config, configPath, profile: profileSelection?.name, profileConfigPath };
 };
 
 /**
  * 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 const initConfig = (configOverride?: Partial<Config>, context?: ConfigLoadContext): Config => {
+export const initConfig = (configOverride?: Partial<Config>, context?: ConfigLoadContext): ResolvedConfig => {
   return initConfigWithMetadata(configOverride, context).config;
 };

package/src/config/resolve-env.ts

@@ -0,0 +1,94 @@
+import isPlainObject from 'lodash/isPlainObject';
+import type { Config, ResolvedConfig } from '../types/config';
+import { Logger } from '../utils/logger';
+import { isEnvReference } from './from-env';
+import { HandoffConfigError } from './errors';
+
+export const 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: string): boolean => BAKED_PATHS.some((baked) => path === baked || path.startsWith(`${baked}.`));
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ALIASES: Record<string, string> = {
+  HANDOFF_REGISTRY_URL: 'HANDOFF_CLOUD_URL',
+  HANDOFF_REGISTRY_ACCESS_TOKEN: 'HANDOFF_CLOUD_TOKEN',
+};
+const warnedAliases = new Set<string>();
+const referenceNames = new WeakMap<ResolvedConfig, Map<string, string>>();
+
+export const configEnvName = (config: ResolvedConfig | null | undefined, path: string): string | undefined =>
+  referenceNames.get(config)?.get(path);
+
+const readEnv = (name: string): string | undefined => {
+  const value = process.env[name];
+  const alias = ALIASES[name];
+  if (!alias || value?.trim()) return value;
+  const inherited = process.env[alias];
+  if (!inherited?.trim()) return value;
+  if (!warnedAliases.has(alias)) {
+    warnedAliases.add(alias);
+    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. */
+export const resolveConfigEnv = (config: Config, profile?: string, defaults?: Config): ResolvedConfig => {
+  const names = new Map<string, string>();
+  const fail = (path: string, message: string): never => {
+    throw new HandoffConfigError(`Config "${path}" (profile "${profile ?? 'default'}"): ${message}`);
+  };
+  const walk = (value: unknown, path: string, seed?: unknown): unknown => {
+    const deferred = DEFERRED_PATHS.has(path);
+    const secret = SECRET_PATHS.has(path);
+    if ((secret || deferred) && value !== undefined && !isEnvReference(value)) {
+      fail(path, 'Expected an environment reference, such as { $env: "VARIABLE_NAME" }. Literal values are not allowed.');
+    }
+    if (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 = value.default ?? (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?.[index]));
+    if (!isPlainObject(value)) return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, walk(entry, path ? `${path}.${key}` : key, seed?.[key])]));
+  };
+  const resolved = walk(config, '', defaults) as ResolvedConfig;
+  referenceNames.set(resolved, names);
+  return resolved;
+};

package/src/config/runtime.ts

@@ -14,7 +14,7 @@ import { HOME_PAGE_ID, HOME_PAGE_PATH } from '../registry/content-kinds';
 import { ComponentListObject } from '../transformers/preview/types';
 import { createCsfStoryPreviews } from '../transformers/utils/csf';
 import { buildAndEvaluateModuleSync } from '../transformers/utils/module';
-import { Config, ConfigFileEntry, RuntimeConfig } from '../types/config';
+import { ResolvedConfig, ConfigFileEntry, RuntimeConfig } from '../types/config';
 import { Logger } from '../utils/logger';
 import { parseMarkdown } from '../utils/markdown';
 import { collectPageSlugSegments } from '../utils/pages';
@@ -26,7 +26,7 @@ import { normalizePageDeclaration } from './normalizers/page';
  * Avoids importing the full Handoff class to prevent circular deps.
  */
 interface HandoffContext {
-  config: Config;
+  config: ResolvedConfig;
   workingPath: string;
   modulePath: string;
 }
@@ -129,7 +129,7 @@ const discoverCsfPreviews = (component: ComponentListObject, handoff: HandoffCon
 /**
  * Expands catalog.include into item directories and removes duplicate paths.
  */
-export const getCatalogItemDirectories = (config: Config, workingPath: string): string[] => {
+export const getCatalogItemDirectories = (config: ResolvedConfig, workingPath: string): string[] => {
   const registered = [...(config.catalog?.include ?? [])];
 
   const seen = new Set<string>();

package/src/config/validator.ts

@@ -1,4 +1,4 @@
-import { Config } from '../types/config';
+import { ResolvedConfig } from '../types/config';
 import { Logger } from '../utils/logger';
 
 /**
@@ -8,15 +8,13 @@ import { Logger } from '../utils/logger';
  * @returns The validated config (same reference).
  * @throws {Error} If required Figma credentials are missing.
  */
-export const validateConfig = (config: Config): Config => {
+export const validateConfig = (config: ResolvedConfig): ResolvedConfig => {
   // 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.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.error('Figma Access Token missing. Please set HANDOFF_DEV_ACCESS_TOKEN or run "handoff-app fetch".');
     throw new Error('Cannot initialize configuration');
   }

package/src/index.d.ts

@@ -1,11 +1,11 @@
 
 import 'dotenv/config';
-import { Config } from './types/config';
+import { ResolvedConfig } from './types/config';
 
 declare module 'handoff-app';
 
 declare class Handoff {
-    config: Config;
+    config: ResolvedConfig;
     modulePath: string;
     workingPath: string;
     force: boolean;