handoff-app 2.0.0-7 → 2.0.0-9

package/src/config/README.md

@@ -7,10 +7,15 @@ Handles loading, validation, and resolution of handoff configuration.
 | File | Purpose |
 |------|---------|
 | `defaults.ts` | Default config values and `getClientConfig()` for the Next.js app |
-| `loader.ts` | `initConfig()` — reads `handoff.config.ts/.js/.cjs/.json` (in that order), warns on conflicts, and merges overrides |
+| `from-env.ts` | JSON-compatible environment markers and public types |
+| `resolve-env.ts` | Resolves merged environment references and guards reference-only properties |
+| `errors.ts` | Shared `HandoffConfigError` |
+| `env.ts` | Reads `.env` at load, then `loadProfileEnv()` applies `.env.<profile>` on top |
+| `loader.ts` | `initConfig()` — reads `handoff.config.ts/.js/.cjs/.json` (in that order) plus the selected profile sidecar, warns on conflicts, and merges every layer |
 | `runtime.ts` | `initRuntimeConfig()` — one pass over every registered catalog directory: loads each declaration, normalizes it into a component or pattern record, skips a declaration with a taken id, resolves SCSS/JS paths and transformer options |
 | `catalog-include.ts` | `isIncluded()` / `addToCatalog()` — registers a directory under `catalog.include` |
 | `validator.ts` | `validateConfig()` — ensures required Figma credentials are present |
+| `helpers.ts` | `defineConfig()` — typed authoring; maps camelCase keys to the runtime keys |
 | `index.ts` | Barrel re-exports |
 
 ## Usage
@@ -31,3 +36,58 @@ When multiple main config files exist in the project root, Handoff picks the fir
 2. `handoff.config.js`
 3. `handoff.config.cjs`
 4. `handoff.config.json`
+
+## Profiles
+
+`--profile <name>`, or `HANDOFF_PROFILE` when the flag is absent, adds one sidecar file. It sits beside the resolved 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.<name>.*`, and a config named through `-c` keeps its own name. The same four extensions are probed in the same order. A selected profile that does not resolve is a `HandoffConfigError`.
+
+`ConfigLoadContext.knownProfiles` widens what resolving means: a listed name loads the base config unchanged instead of failing. The CLI passes the saved registry login names for `login`, `logout`, `publish`, and `checkout`, where a profile selects the registry rather than a config layer. `profileNotFoundHint` is the caller's sentence for a name that matches neither. Everything else keeps the strict rule, so a typo cannot silently run with the base config.
+
+## Environment Files
+
+`.env` is read once when `env.ts` loads, before the first `Handoff` is constructed. A selected profile then adds an optional `.env.<profile>` from the same directory. Precedence is the process environment, then the profile env file, then `.env`. The keys present at startup are recorded before `.env` is read and are never overwritten, so an inline `VAR=… handoff-app …` still wins.
+
+`loadProfileEnv()` runs twice: in `Handoff.construct()` before `Logger.init()`, so the log level can come from a profile, and in `initConfigWithMetadata()` before the merged environment references resolve. Applying it twice changes nothing.
+
+## Layer Precedence
+
+Every loaded file is normalized, then the layers are merged in this order:
+
+1. `defaultConfig()`
+2. Base config file
+3. Profile file
+4. Programmatic override (`HandoffOptions.config`)
+
+Plain objects merge recursively. Arrays, scalars, `null`, and functions replace. `undefined` is skipped.
+
+## Environment references
+
+Import `fromEnv` from `handoff-app`. `fromEnv('OUTPUT_DIR', { default: 'exported' })` creates
+`{ $env: 'OUTPUT_DIR', default: 'exported' }` without reading the environment. JSON configs use
+that same object. Without a default, an unset variable raises `HandoffConfigError` with the
+property path, variable name, and active profile. Invalid names and rejected literals are never echoed.
+
+`EnvValue<T>` accepts a literal or reference. `EnvSecret<T>` accepts only a reference and resolves
+at config load. Secret defaults can only be empty or null, for optional credentials.
+`RuntimeEnvReference<T>` accepts only a reference with no default. Its name survives config loading and
+is read in the deployed process. Database URLs and asset-storage tokens are deferred.
+
+The loader resolves references once after all layers merge, before other config guards.
+References replace whole values, including earlier references and their defaults. A profile can
+replace an ordinary reference with a literal. Functions in hooks and pipeline remain functions.
+Defaults retain the existing `HANDOFF_*` seeds: a higher-layer literal beats a seed, and an explicit
+reference beats every lower layer. Only the winning reference reads the environment.
+
+Environment values are strings. A numeric or boolean default selects conversion; the built-in
+numeric and boolean properties also retain their default's conversion when a reference omits its
+fallback. Booleans are true only for `true`. Numbers must be finite. A lower-layer fallback never
+becomes the fallback for a replacement reference.
+
+`runtime.registry.assetStorage.options` is for non-secret values only. Its resolved contents are
+JSON-encoded into the bundle, so the loader rejects an environment reference anywhere inside it
+(`BAKED_PATHS`). For custom adapter secrets, put a variable name in options and read it through the
+adapter factory's `env` argument at runtime. A per-environment literal belongs in a profile.
+
+`ResolvedConfig` narrows eager properties by hand. Adding an eager property requires its `Config`
+member and resolved narrowing. A secret also needs a `SECRET_PATHS` entry for untyped configs.
+Adding a deferred property requires its member and a `DEFERRED_PATHS` entry.

package/src/config/catalog-include.ts

@@ -14,13 +14,13 @@
 
 import fs from 'fs-extra';
 import path from 'path';
-import { Config } from '../types/config';
+import { ResolvedConfig } from '../types/config';
 import { arePathsEqual } from '../utils/path';
 import { getComponentsForPath } from './runtime';
 
 /** Minimal handoff shape needed here; avoids importing the full Handoff class (circular dep). */
 interface ConfigContext {
-  config?: Config;
+  config?: ResolvedConfig;
   workingPath: string;
 }
 

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,20 @@
 import esbuild from 'esbuild';
+import { STYLE_IMPORT_LOADERS } from '../transformers/utils/build';
 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 +24,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 +43,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],
@@ -49,6 +68,7 @@ const evaluateTypeScriptConfig = (filePath: string, handoffModulePath: string):
     target: 'node16',
     logLevel: 'silent',
     external: ['handoff-app'],
+    loader: STYLE_IMPORT_LOADERS,
   });
 
   const code = buildResult.outputFiles?.[0]?.text;
@@ -91,6 +111,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 +163,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 +280,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;
 };