handoff-app 2.0.0-7 → 2.0.0-9

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

@@ -1,4 +1,5 @@
 import esbuild from 'esbuild';
+import { STYLE_IMPORT_LOADERS } from '../transformers/utils/build';
 import fs from 'fs-extra';
 import { createRequire } from 'module';
 import path from 'path';
@@ -14,7 +15,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 +27,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;
 }
@@ -35,7 +36,8 @@ type DeclarationResolution = {
   fileName: string;
 };
 
-const DECLARATION_EXTENSIONS = ['ts', 'js', 'cjs'] as const;
+/** `.tsx`/`.jsx` are accepted so a preview can write its `render` as JSX. */
+const DECLARATION_EXTENSIONS = ['tsx', 'ts', 'jsx', 'js', 'cjs'] as const;
 
 const getDeclarationFiles = (componentBaseName: string): string[] =>
   DECLARATION_EXTENSIONS.map((ext) => `${componentBaseName}.handoff.${ext}`);
@@ -46,7 +48,7 @@ const findPreferredDeclaration = (componentDir: string, componentBaseName: strin
   if (exactMatch) return exactMatch;
 
   const allFiles = fs.existsSync(componentDir) ? fs.readdirSync(componentDir) : [];
-  const declarationFiles = allFiles.filter((file) => /\.handoff\.(ts|js|cjs)$/.test(file)).sort((a, b) => a.localeCompare(b));
+  const declarationFiles = allFiles.filter((file) => /\.handoff\.(tsx|ts|jsx|js|cjs)$/.test(file)).sort((a, b) => a.localeCompare(b));
 
   if (!declarationFiles.length) return undefined;
 
@@ -74,6 +76,7 @@ const evaluateDeclaration = (filePath: string, handoffModulePath: string): any =
     logLevel: 'silent',
     jsx: 'automatic',
     external: ['react', 'react-dom', 'handoff-app'],
+    loader: STYLE_IMPORT_LOADERS,
   });
 
   const code = buildResult.outputFiles?.[0]?.text;
@@ -129,7 +132,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>();
@@ -219,7 +222,7 @@ export const initRuntimeConfig = (
     if (!declaration) {
       const declarationFiles = getDeclarationFiles(itemBaseName);
       Logger.warn(
-        `Missing catalog declaration (use .handoff.ts, .handoff.js, or .handoff.cjs; see UPGRADE.md#catalog-items): ${path.resolve(itemPath, declarationFiles.join(' or '))}`
+        `Missing catalog declaration (use .handoff.tsx, .handoff.ts, .handoff.jsx, .handoff.js, or .handoff.cjs; see UPGRADE.md#catalog-items): ${path.resolve(itemPath, declarationFiles.join(' or '))}`
       );
       continue;
     }
@@ -433,9 +436,9 @@ const injectPatternPreviews = (result: RuntimeConfig): void => {
 
       // Case 3: args present (with or without preview base) -> create synthetic preview
       let resolvedValues: Record<string, any> = {};
+      const basePreview = ref.preview ? component.previews?.[ref.preview] : undefined;
 
       if (ref.preview) {
-        const basePreview = component.previews?.[ref.preview];
         if (basePreview) {
           resolvedValues = { ...basePreview.values };
         } else {
@@ -454,6 +457,8 @@ const injectPatternPreviews = (result: RuntimeConfig): void => {
         values: resolvedValues,
         url: '',
         sourcePreview: ref.preview,
+        // The ref overrides arguments, not how the preview renders, so a base `render` still applies.
+        ...(basePreview?.render ? { render: basePreview.render } : {}),
       };
 
       ref.resolvedPreview = syntheticKey;

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/handlebars.ts

@@ -5,9 +5,15 @@
  * an argument type to check previews: `defineCatalogItem<BadgeArgs>`.
  */
 import { createCatalogItem } from './catalog/define';
-import type { CatalogItem, CatalogItemMeta } from './catalog/types';
+import type { CatalogItem, CatalogItemMeta, CatalogPreview as RendererPreview } from './catalog/types';
 
-export type { CatalogItem, CatalogItemMeta, CatalogPreview, CompositionRef, Preview, SourceDescriptor } from './catalog/types';
+export type { CatalogItem, CatalogItemMeta, CompositionRef, SourceDescriptor } from './catalog/types';
+
+/** A template renderer never calls a preview `render`, so declaring one is an error, not a no-op. */
+export type CatalogPreview<TArgs = Record<string, unknown>> = Omit<RendererPreview<TArgs>, 'render'> & { render?: never };
+
+/** Preview type for a Handlebars catalog item, with its argument type applied. */
+export type Preview<TItem> = TItem extends { readonly __args?: infer TArgs } ? CatalogPreview<Partial<NonNullable<TArgs>>> : never;
 
 /**
  * Declares a Handlebars catalog item. `implementation` is the path to its `.hbs` template. The

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;

package/src/index.ts

@@ -1,17 +1,25 @@
-import 'dotenv/config';
+import './config/env';
 import fs from 'fs-extra';
 import { Types as CoreTypes, Handoff as HandoffRunner, Providers } from 'handoff-core';
 import path from 'path';
 import buildApp, { devApp, watchApp, type BuildPackage, type BuildTarget } from './app-builder';
 import { ejectConfig, ejectPages, ejectTheme } from './cli/eject';
 import { makeComponent, makePage } from './cli/make';
-import { initConfigWithMetadata, initRuntimeConfig, validateConfig } from './config';
+import { loginProfileNames } from './cli/auth/store';
+import {
+  type ConfigLoadContext,
+  initConfigWithMetadata,
+  initRuntimeConfig,
+  loadProfileEnv,
+  resolveProfileSelection,
+  validateConfig,
+} from './config';
 import pipeline, { buildComponents, buildPatterns } from './pipeline';
 import { ALL_KIND_ORDER, ENTITY_WIRE_KIND, isRegistryEntityKind, REGISTRY_ENTITY_KINDS, type RegistryEntityKind } from './registry/content-kinds';
 import type { TransferEntityKind } from './registry/transfer';
 import { createFilesystemStore, type HandoffStore } from './store';
 import processComponents, { ComponentSegment } from './transformers/preview/component/builder';
-import { Config, ConfigFileEntry, RuntimeConfig } from './types/config';
+import { Config, ResolvedConfig, ConfigFileEntry, RuntimeConfig } from './types/config';
 import { Logger } from './utils/logger';
 import { normalizePathForCompare, resolveWorkingPath } from './utils/path';
 import { generateFilesystemSafeId } from './utils/path';
@@ -32,6 +40,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';
 }
 
 /**
@@ -109,7 +130,7 @@ const runKinds = async (
 };
 
 class Handoff {
-  config: Config | null;
+  config: ResolvedConfig | null;
   debug: boolean = false;
   force: boolean = false;
   dryRun: boolean = false;
@@ -142,6 +163,8 @@ class Handoff {
   private _configFilePaths: string[] = [];
   private _configFileIndex: Map<string, ConfigFileEntry> = new Map();
   private _mainConfigFilePath?: string;
+  private _profileConfigFilePath?: string;
+  private _profile?: string;
   private _documentationObjectCache?: CoreTypes.IDocumentationObject;
   private _handoffRunner?: ReturnType<typeof HandoffRunner> | null;
 
@@ -151,7 +174,8 @@ class Handoff {
   }
 
   private construct(options: HandoffOptions) {
-    this.config = null;
+    // Ahead of `Logger.init` so a profile env file can set `HANDOFF_LOG_LEVEL` and `HANDOFF_LOG_SCOPES`.
+    loadProfileEnv(resolveProfileSelection(options.profile)?.name);
     this.debug = options.debug ?? false;
     this.force = options.force ?? false;
     this.dryRun = options.dryRun ?? false;
@@ -160,14 +184,50 @@ class Handoff {
     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.
+   */
+  private profilesWithoutConfig(): Pick<ConfigLoadContext, 'knownProfiles' | 'profileNotFoundHint'> {
+    const selected = resolveProfileSelection(this._options.profile)?.name;
+    if (!selected) {
+      return {};
+    }
+
+    const accepts = this._options.profileWithoutConfig;
+    const names = 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?: Partial<Config>): Handoff {
+    // 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 = initConfigWithMetadata(configOverride ?? {}, {
       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 = config.exportsOutputDirectory ?? this.exportsDirectory;
     this.sitesDirectory = config.sitesOutputDirectory ?? this.exportsDirectory;
     [this.runtimeConfig, this._configFilePaths, this._configFileIndex] = initRuntimeConfig(this);
@@ -571,8 +631,8 @@ class Handoff {
    * @returns {string[]} Array of absolute paths to config files
    */
   getConfigFilePaths(): string[] {
-    const combined = this._mainConfigFilePath ? [this._mainConfigFilePath, ...this._configFilePaths] : this._configFilePaths;
-    return Array.from(new Set(combined));
+    const mainPaths = [this._mainConfigFilePath, this._profileConfigFilePath].filter(Boolean) as string[];
+    return Array.from(new Set([...mainPaths, ...this._configFilePaths]));
   }
 
   /**
@@ -582,6 +642,21 @@ class Handoff {
     return this._mainConfigFilePath;
   }
 
+  getProfile(): string | undefined {
+    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: string): boolean {
+    const normalized = normalizePathForCompare(filePath);
+    return [this._mainConfigFilePath, this._profileConfigFilePath]
+      .filter(Boolean)
+      .some((mainPath) => normalizePathForCompare(mainPath as string) === normalized);
+  }
+
   getConfigFileEntry(configPath: string): ConfigFileEntry | undefined {
     return this._configFileIndex.get(normalizePathForCompare(configPath));
   }
@@ -608,8 +683,10 @@ class Handoff {
   }
 }
 
-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,

package/src/pipeline/index.ts

@@ -1,4 +1,4 @@
-import 'dotenv/config';
+import '../config/env';
 import Handoff from '..';
 import buildApp from '../app-builder';
 import { Logger } from '../utils/logger';

package/src/registry/asset-storage/adapters/vercel-blob.ts

@@ -21,7 +21,7 @@ export const createVercelBlobStorage = (params: { tokenEnv: string; options: Rec
     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;

package/src/registry/asset-storage/resolve.ts

@@ -7,7 +7,7 @@
  * env-var *names* are ever persisted; secret *values* are read from `process.env` at request time.
  */
 
-import type { Config } from '../../types/config';
+import type { ResolvedConfig } from '../../types/config';
 import type { AssetStorageProvider } from '../db/schema';
 
 /** Which adapter implementation is active. */
@@ -68,5 +68,8 @@ export const resolveAssetStorageSettings = (settings: AssetStorageSettings | nul
 };
 
 /** Resolve the active asset storage settings from a loaded config (CLI/build side). */
-export const resolveAssetStorageFromConfig = (config: Config | null | undefined): ResolvedAssetStorage =>
-  resolveAssetStorageSettings(config?.runtime?.registry?.assetStorage);
+export const resolveAssetStorageFromConfig = (config: ResolvedConfig | null | undefined): ResolvedAssetStorage =>
+  resolveAssetStorageSettings({
+    ...config?.runtime?.registry?.assetStorage,
+    tokenEnv: config?.runtime?.registry?.assetStorage?.token?.$env,
+  });

package/src/registry/checkout/index.ts

@@ -36,7 +36,7 @@ import Handoff from '../../index';
 import type { DeclarationFormat } from '../../types/config';
 import { Logger } from '../../utils/logger';
 import { createRegistryClient, type RegistryClient, RegistryClientError } from '../client';
-import { resolveAuthenticatedRegistryConnection } from '../connection';
+import { loginCommandHint, resolveAuthenticatedRegistryConnection, unusedLoginNote } from '../connection';
 import { isSafePathSegment, isSafeRelativePath, resolvePathWithin } from '../path';
 import { quoteIds, selectIds, splitCatalogIds } from '../selection';
 import type { CheckoutPayload, TransferEntityKind, TransferFile } from '../transfer';
@@ -76,17 +76,17 @@ export const resolveConnectionOrThrow = async (handoff: Handoff) => {
     );
   }
 
-  const connection = await resolveAuthenticatedRegistryConnection(handoff.config, handoff.workingPath);
+  const connection = await resolveAuthenticatedRegistryConnection(handoff.config, handoff.workingPath, handoff.getProfile());
   if (!connection.url) {
     throw new CheckoutError(
-      `No registry is configured. Run \`handoff-app login --url <registry-url>\`, set runtime.registryConnection.url, ` +
+      `No registry is configured. Run \`${loginCommandHint(connection)}\`, set runtime.registryConnection.url, ` +
         `or set the "${connection.urlEnv}" environment variable to the base URL of the registry to checkout from.`
     );
   }
   if (!connection.accessToken) {
     throw new CheckoutError(
-      `No registry access token is configured. Run \`handoff-app login --url ${connection.url}\`, or set the ` +
-        `"${connection.accessTokenEnv}" environment variable to a user-issued token for CI.`
+      `No registry access token is configured. Run \`${loginCommandHint(connection)}\`, or set the ` +
+        `"${connection.accessTokenEnv}" environment variable to a user-issued token for CI.${unusedLoginNote(connection)}`
     );
   }
   return connection;