handoff-app 2.0.0-7 → 2.0.0-9

package/dist/commands/login/index.js

@@ -14,6 +14,11 @@ const store_1 = require("../../cli/auth/store");
 const connection_1 = require("../../registry/connection");
 const logger_1 = require("../../utils/logger");
 const utils_1 = require("../utils");
+/**
+ * Saves one registry credential per profile, so a workspace can hold a login for every registry it
+ * publishes to. The name is independent of the config profiles, and `login` is the one command that
+ * accepts a profile nothing else knows yet.
+ */
 const command = {
     command: 'login',
     describe: 'Sign in to a registry using browser device authorization',
@@ -28,17 +33,24 @@ const command = {
         describe: 'Open the approval URL in the default browser (disable with --no-browser)',
     }),
     handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
-        var _a;
-        const handoff = (0, utils_1.createHandoff)(args);
+        var _a, _b;
+        const handoff = (0, utils_1.createHandoff)(args, { profileWithoutConfig: 'any' });
+        const profile = (_a = handoff.getProfile()) !== null && _a !== void 0 ? _a : store_1.DEFAULT_LOGIN_PROFILE;
         try {
             const configured = (0, connection_1.resolveRegistryConnection)(handoff.config);
-            const remoteUrl = ((_a = args.url) === null || _a === void 0 ? void 0 : _a.trim()) || configured.url;
+            // Resolved in the order publish and checkout use, so a login always targets the registry those
+            // commands would reach.
+            const saved = yield (0, store_1.readCliAuth)(handoff.workingPath, profile);
+            const remoteUrl = ((_b = args.url) === null || _b === void 0 ? void 0 : _b.trim()) || configured.url || (saved === null || saved === void 0 ? void 0 : saved.remoteUrl);
             if (!remoteUrl) {
                 throw new Error(`Pass --url <registry-url>, configure runtime.registryConnection.url, or set "${configured.urlEnv}".`);
             }
-            yield (0, device_1.loginWithDevice)(handoff.workingPath, remoteUrl, { openBrowser: args.browser !== false });
-            logger_1.Logger.success(`Logged in. Credentials saved to ${(0, store_1.cliAuthFilePath)(handoff.workingPath)}.`);
-            logger_1.Logger.info('Publish and checkout commands will use this login for the matching registry URL.');
+            yield (0, device_1.loginWithDevice)(handoff.workingPath, remoteUrl, { openBrowser: args.browser !== false, profile });
+            const named = profile === store_1.DEFAULT_LOGIN_PROFILE ? '' : ` under profile "${profile}"`;
+            logger_1.Logger.success(`Logged in. Credentials saved to ${(0, store_1.cliAuthFilePath)(handoff.workingPath)}${named}.`);
+            logger_1.Logger.info(profile === store_1.DEFAULT_LOGIN_PROFILE
+                ? 'Publish and checkout commands will use this login for the matching registry URL.'
+                : `Publish and checkout commands will use this login when they run with --profile ${profile}.`);
         }
         catch (error) {
             logger_1.Logger.error(error instanceof Error ? error.message : String(error));

package/dist/commands/logout/index.d.ts

@@ -2,6 +2,11 @@ import { CommandModule } from 'yargs';
 import { SharedArgs } from '../types';
 export interface LogoutArgs extends SharedArgs {
     url?: string;
+    all?: boolean;
 }
+/**
+ * `handoff-app logout` removes the login of the selected profile, leaving every other profile signed
+ * in. `--all` removes them all.
+ */
 declare const command: CommandModule<{}, LogoutArgs>;
 export default command;

package/dist/commands/logout/index.js

@@ -13,33 +13,72 @@ const device_1 = require("../../cli/auth/device");
 const store_1 = require("../../cli/auth/store");
 const logger_1 = require("../../utils/logger");
 const utils_1 = require("../utils");
+/** Remote revocation is best effort: the local credential goes either way. */
+const revoke = (auth) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        yield (0, device_1.revokeAccessToken)(auth);
+    }
+    catch (error) {
+        logger_1.Logger.warn(`Could not revoke the registry token for ${auth.remoteUrl} (${error instanceof Error ? error.message : String(error)}). ` +
+            'It will still be removed from this workspace.');
+    }
+});
+/**
+ * `handoff-app logout` removes the login of the selected profile, leaving every other profile signed
+ * in. `--all` removes them all.
+ */
 const command = {
     command: 'logout',
     describe: 'Revoke and remove saved registry credentials',
-    builder: (yargs) => (0, utils_1.getSharedOptions)(yargs).option('url', {
+    builder: (yargs) => (0, utils_1.getSharedOptions)(yargs)
+        .option('url', {
         type: 'string',
         describe: 'Revoke credentials only when they belong to this exact registry URL',
-    }),
+    })
+        .option('all', {
+        type: 'boolean',
+        describe: 'Revoke and remove the saved credentials for every profile',
+    })
+        .conflicts('all', 'url'),
     handler: (args) => __awaiter(void 0, void 0, void 0, function* () {
-        const handoff = (0, utils_1.createHandoff)(args);
-        const auth = yield (0, store_1.readCliAuth)(handoff.workingPath);
-        if (args.url && auth && !(0, store_1.cliAuthMatchesRegistry)(auth, args.url)) {
-            logger_1.Logger.error(`The saved login belongs to ${auth.remoteUrl}, not ${(0, store_1.normalizeRegistryUrl)(args.url)}. No credentials were changed.`);
-            process.exitCode = 1;
-            return;
-        }
-        if (auth) {
+        var _a;
+        const handoff = (0, utils_1.createHandoff)(args, { profileWithoutConfig: 'saved-login' });
+        const profile = (_a = handoff.getProfile()) !== null && _a !== void 0 ? _a : store_1.DEFAULT_LOGIN_PROFILE;
+        const named = profile === store_1.DEFAULT_LOGIN_PROFILE ? '' : ` for profile "${profile}"`;
+        if (args.all) {
+            const logins = yield (0, store_1.readCliLogins)(handoff.workingPath);
+            const names = Object.keys(logins);
+            if (!names.length) {
+                logger_1.Logger.info('No saved logins.');
+                return;
+            }
+            for (const name of names) {
+                yield revoke(logins[name]);
+            }
             try {
-                yield (0, device_1.revokeAccessToken)(auth);
+                yield (0, store_1.clearAllCliAuth)(handoff.workingPath);
+                logger_1.Logger.success(`Logged out of every saved profile: ${names.join(', ')}. Removed ${(0, store_1.cliAuthFilePath)(handoff.workingPath)}.`);
             }
             catch (error) {
-                logger_1.Logger.warn(`Could not revoke the registry token remotely (${error instanceof Error ? error.message : String(error)}). ` +
-                    'It will still be removed from this workspace.');
+                logger_1.Logger.error(`Could not remove saved credentials: ${error instanceof Error ? error.message : String(error)}`);
+                process.exitCode = 1;
             }
+            return;
+        }
+        const auth = yield (0, store_1.readCliAuth)(handoff.workingPath, profile);
+        if (!auth) {
+            logger_1.Logger.info(`No saved login${named}.`);
+            return;
+        }
+        if (args.url && !(0, store_1.cliAuthMatchesRegistry)(auth, args.url)) {
+            logger_1.Logger.error(`The saved login${named} belongs to ${auth.remoteUrl}, not ${(0, store_1.normalizeRegistryUrl)(args.url)}. No credentials were changed.`);
+            process.exitCode = 1;
+            return;
         }
+        yield revoke(auth);
         try {
-            yield (0, store_1.clearCliAuth)(handoff.workingPath);
-            logger_1.Logger.success(`Logged out. Removed ${(0, store_1.cliAuthFilePath)(handoff.workingPath)}.`);
+            yield (0, store_1.clearCliAuth)(handoff.workingPath, profile);
+            logger_1.Logger.success(`Logged out of ${auth.remoteUrl}${named}. Removed the saved credentials.`);
         }
         catch (error) {
             logger_1.Logger.error(`Could not remove saved credentials: ${error instanceof Error ? error.message : String(error)}`);

package/dist/commands/types.d.ts

@@ -2,6 +2,8 @@ import { Arguments } from 'yargs';
 export interface SharedArgs extends Arguments {
     /** Explicit config file, replacing the usual `handoff.config.*` lookup. */
     config?: string;
+    /** Config profile merged onto the base config; overrides `HANDOFF_PROFILE`. */
+    profile?: string;
     force?: boolean;
     debug?: boolean;
     /**

package/dist/commands/utils.d.ts

@@ -1,5 +1,5 @@
 import { Argv } from 'yargs';
-import Handoff from '../';
+import Handoff, { HandoffOptions } from '../';
 import { SharedArgs } from './types';
 /**
  * The `type` argument accepted by publish and checkout, or `all` for every kind. `catalog` covers
@@ -15,13 +15,15 @@ export type RegistryTargetKind = (typeof REGISTRY_TARGET_KINDS)[number];
  */
 export declare const COMPAT_TARGET_KINDS: readonly ["components", "patterns", "pages", "tokens", "assets", "all"];
 export type CompatTargetKind = (typeof COMPAT_TARGET_KINDS)[number];
-export declare const createHandoff: (args: SharedArgs) => Handoff;
+export declare const createHandoff: (args: SharedArgs, options?: Pick<HandoffOptions, "profileWithoutConfig">) => Handoff;
 /**
- * Run a registry command against a fresh Handoff. Registry failures are the user's to act on, so they
- * surface as one actionable line and a non-zero exit rather than a stack trace.
+ * Run a registry command against a fresh Handoff. A selected profile may name a saved login instead
+ * of a config file, because here the profile selects the registry. Registry failures are the
+ * user's to act on, so they surface as one actionable line and a non-zero exit rather than a stack
+ * trace.
  */
 export declare const runRegistryCommand: (args: SharedArgs, run: (handoff: Handoff) => Promise<unknown>) => Promise<void>;
-export declare const getSharedOptions: (yargs: Argv) => Argv<import("yargs").Omit<{}, "debug" | "config" | "force"> & import("yargs").InferredOptionTypes<{
+export declare const getSharedOptions: (yargs: Argv) => Argv<import("yargs").Omit<{}, "debug" | "config" | "profile" | "force"> & import("yargs").InferredOptionTypes<{
     config: {
         alias: string;
         type: "string";
@@ -37,9 +39,13 @@ export declare const getSharedOptions: (yargs: Argv) => Argv<import("yargs").Omi
         type: "boolean";
         description: string;
     };
+    profile: {
+        type: "string";
+        description: string;
+    };
 }>>;
 /** Shared options plus the transfer options: publish and its compatibility aliases use these. */
-export declare const getPublishOptions: (yargs: Argv) => Argv<import("yargs").Omit<import("yargs").Omit<{}, "debug" | "config" | "force"> & import("yargs").InferredOptionTypes<{
+export declare const getPublishOptions: (yargs: Argv) => Argv<import("yargs").Omit<import("yargs").Omit<{}, "debug" | "config" | "profile" | "force"> & import("yargs").InferredOptionTypes<{
     config: {
         alias: string;
         type: "string";
@@ -55,6 +61,10 @@ export declare const getPublishOptions: (yargs: Argv) => Argv<import("yargs").Om
         type: "boolean";
         description: string;
     };
+    profile: {
+        type: "string";
+        description: string;
+    };
 }>, "build" | "dry-run"> & import("yargs").InferredOptionTypes<{
     'dry-run': {
         type: "boolean";
@@ -67,7 +77,7 @@ export declare const getPublishOptions: (yargs: Argv) => Argv<import("yargs").Om
     };
 }>>;
 /** Shared options plus `--dry-run`: checkout and its compatibility aliases use these. */
-export declare const getCheckoutOptions: (yargs: Argv) => Argv<import("yargs").Omit<import("yargs").Omit<{}, "debug" | "config" | "force"> & import("yargs").InferredOptionTypes<{
+export declare const getCheckoutOptions: (yargs: Argv) => Argv<import("yargs").Omit<import("yargs").Omit<{}, "debug" | "config" | "profile" | "force"> & import("yargs").InferredOptionTypes<{
     config: {
         alias: string;
         type: "string";
@@ -83,6 +93,10 @@ export declare const getCheckoutOptions: (yargs: Argv) => Argv<import("yargs").O
         type: "boolean";
         description: string;
     };
+    profile: {
+        type: "string";
+        description: string;
+    };
 }>, "dry-run"> & import("yargs").InferredOptionTypes<{
     'dry-run': {
         type: "boolean";

package/dist/commands/utils.js

@@ -28,21 +28,18 @@ exports.REGISTRY_TARGET_KINDS = ['catalog', 'pages', 'tokens', 'assets', 'all'];
  * not take, and omits `catalog`, which the docs do not describe.
  */
 exports.COMPAT_TARGET_KINDS = [...content_kinds_1.REGISTRY_ENTITY_KINDS, 'all'];
-const createHandoff = (args) => new __1.default({
-    debug: args.debug,
-    force: args.force,
-    configPath: args.config,
-    dryRun: args.dryRun,
+const createHandoff = (args, options = {}) => new __1.default(Object.assign({ debug: args.debug, force: args.force, configPath: args.config, profile: args.profile, dryRun: args.dryRun, 
     // yargs gives `--no-build` as `build: false`; anything else leaves the build in place.
-    skipBuild: args.build === false,
-});
+    skipBuild: args.build === false }, options));
 exports.createHandoff = createHandoff;
 /**
- * Run a registry command against a fresh Handoff. Registry failures are the user's to act on, so they
- * surface as one actionable line and a non-zero exit rather than a stack trace.
+ * Run a registry command against a fresh Handoff. A selected profile may name a saved login instead
+ * of a config file, because here the profile selects the registry. Registry failures are the
+ * user's to act on, so they surface as one actionable line and a non-zero exit rather than a stack
+ * trace.
  */
 const runRegistryCommand = (args, run) => __awaiter(void 0, void 0, void 0, function* () {
-    const handoff = (0, exports.createHandoff)(args);
+    const handoff = (0, exports.createHandoff)(args, { profileWithoutConfig: 'saved-login' });
     try {
         yield run(handoff);
     }
@@ -69,6 +66,10 @@ const getSharedOptions = (yargs) => {
             type: 'boolean',
             description: 'Enable debug mode',
         },
+        profile: {
+            type: 'string',
+            description: 'Config profile merged onto the base config (handoff.config.<profile>.*), and the saved login that registry commands use; overrides HANDOFF_PROFILE',
+        },
     });
 };
 exports.getSharedOptions = getSharedOptions;

package/dist/config/catalog-include.d.ts

@@ -11,10 +11,10 @@
  * A workspace registers items under `catalog.include`. Discovery expands collection directories;
  * the writer appends unlisted paths in JSON, TypeScript, JavaScript, and CommonJS project configs.
  */
-import { Config } from '../types/config';
+import { ResolvedConfig } from '../types/config';
 /** Minimal handoff shape needed here; avoids importing the full Handoff class (circular dep). */
 interface ConfigContext {
-    config?: Config;
+    config?: ResolvedConfig;
     workingPath: string;
 }
 /** Outcome of {@link addToCatalog}: `added` on success, `unsupported` when the config couldn't be edited. */

package/dist/config/defaults.d.ts

@@ -1,4 +1,4 @@
-import { ClientConfig, Config } from '../types/config';
+import { ClientConfig, Config, ResolvedConfig } from '../types/config';
 export interface ImageStyle {
     name: string;
     style: string;
@@ -7,7 +7,7 @@ export interface ImageStyle {
     description: string;
 }
 /** Whether the MCP endpoint is served. On unless `runtime.mcp` is explicitly `false`. */
-export declare const isMcpEnabled: (config: Config | null | undefined) => boolean;
+export declare const isMcpEnabled: (config: Pick<Config, "runtime"> | Pick<ResolvedConfig, "runtime"> | null | undefined) => boolean;
 export declare const defaultConfig: () => Config;
 /**
  * Retrieves the client configuration from the provided handoff configuration.
@@ -15,4 +15,4 @@ export declare const defaultConfig: () => Config;
  * @param config - The full handoff Config object.
  * @returns The client configuration object.
  */
-export declare const getClientConfig: (config: Config) => ClientConfig;
+export declare const getClientConfig: (config: ResolvedConfig) => ClientConfig;

package/dist/config/defaults.js

@@ -1,60 +1,66 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getClientConfig = exports.defaultConfig = exports.isMcpEnabled = void 0;
+const from_env_1 = require("./from-env");
 const connection_1 = require("../registry/connection");
 /** Whether the MCP endpoint is served. On unless `runtime.mcp` is explicitly `false`. */
 const isMcpEnabled = (config) => { var _a; return ((_a = config === null || config === void 0 ? void 0 : config.runtime) === null || _a === void 0 ? void 0 : _a.mcp) !== false; };
 exports.isMcpEnabled = isMcpEnabled;
-const defaultConfig = () => {
-    var _a, _b, _c, _d;
-    return ({
-        dev_access_token: (_a = process.env.HANDOFF_DEV_ACCESS_TOKEN) !== null && _a !== void 0 ? _a : null,
-        figma_project_id: (_b = process.env.HANDOFF_FIGMA_PROJECT_ID) !== null && _b !== void 0 ? _b : null,
-        runtime: {
-            mode: 'workspace',
+const defaultConfig = () => ({
+    dev_access_token: (0, from_env_1.fromEnv)('HANDOFF_DEV_ACCESS_TOKEN', { default: null }),
+    figma_project_id: (0, from_env_1.fromEnv)('HANDOFF_FIGMA_PROJECT_ID', { default: null }),
+    runtime: {
+        mode: 'workspace',
+        registryConnection: {
+            url: (0, from_env_1.fromEnv)('HANDOFF_REGISTRY_URL', { default: '' }),
+            accessToken: (0, from_env_1.fromEnv)('HANDOFF_REGISTRY_ACCESS_TOKEN', { default: '' }),
         },
-        exportsOutputDirectory: (_c = process.env.HANDOFF_OUTPUT_DIR) !== null && _c !== void 0 ? _c : 'exported',
-        sitesOutputDirectory: (_d = process.env.HANDOFF_SITES_DIR) !== null && _d !== void 0 ? _d : 'out',
-        useVariables: process.env.HANDOFF_USE_VARIABLES === 'true',
-        reactDocgen: {
-            maxDepth: 7,
-            excludeDirectories: ['dist', 'build', '.next'],
+        registry: {
+            databaseUrl: (0, from_env_1.fromEnv)('DATABASE_URL'),
+            assetStorage: { token: (0, from_env_1.fromEnv)('BLOB_READ_WRITE_TOKEN') },
         },
-        app: {
-            theme: 'default',
-            title: 'Convertiv Design System',
-            client: 'Convertiv',
-            google_tag_manager: null,
-            attribution: true,
-            type_copy: 'Almost before we knew it, we had left the ground.',
-            type_sort: [
-                'Heading 1',
-                'Heading 2',
-                'Heading 3',
-                'Heading 4',
-                'Heading 5',
-                'Heading 6',
-                'Paragraph',
-                'Subheading',
-                'Blockquote',
-                'Input Labels',
-                'Link',
-            ],
-            color_sort: ['primary', 'secondary', 'extra', 'system'],
-            component_sort: ['primary', 'secondary', 'transparent'],
-            base_path: '',
-            breakpoints: {
-                mobile: { size: 400, name: 'Mobile' },
-                tablet: { size: 800, name: 'Medium' },
-                desktop: { size: 1100, name: 'Large' },
-            },
-            ports: {
-                app: Number(process.env.HANDOFF_APP_PORT) || 3000,
-                websocket: Number(process.env.HANDOFF_WEBSOCKET_PORT) || 3001
-            }
+    },
+    exportsOutputDirectory: (0, from_env_1.fromEnv)('HANDOFF_OUTPUT_DIR', { default: 'exported' }),
+    sitesOutputDirectory: (0, from_env_1.fromEnv)('HANDOFF_SITES_DIR', { default: 'out' }),
+    useVariables: (0, from_env_1.fromEnv)('HANDOFF_USE_VARIABLES', { default: false }),
+    reactDocgen: {
+        maxDepth: 7,
+        excludeDirectories: ['dist', 'build', '.next'],
+    },
+    app: {
+        theme: 'default',
+        title: 'Handoff Design System',
+        client: 'Handoff',
+        google_tag_manager: null,
+        attribution: true,
+        type_copy: 'Almost before we knew it, we had left the ground.',
+        type_sort: [
+            'Heading 1',
+            'Heading 2',
+            'Heading 3',
+            'Heading 4',
+            'Heading 5',
+            'Heading 6',
+            'Paragraph',
+            'Subheading',
+            'Blockquote',
+            'Input Labels',
+            'Link',
+        ],
+        color_sort: ['primary', 'secondary', 'extra', 'system'],
+        component_sort: ['primary', 'secondary', 'transparent'],
+        base_path: '',
+        breakpoints: {
+            mobile: { size: 400, name: 'Mobile' },
+            tablet: { size: 800, name: 'Medium' },
+            desktop: { size: 1100, name: 'Large' },
         },
-    });
-};
+        ports: {
+            app: (0, from_env_1.fromEnv)('HANDOFF_APP_PORT', { default: 3000 }),
+            websocket: (0, from_env_1.fromEnv)('HANDOFF_WEBSOCKET_PORT', { default: 3001 }),
+        },
+    },
+});
 exports.defaultConfig = defaultConfig;
 /**
  * Retrieves the client configuration from the provided handoff configuration.
@@ -64,7 +70,7 @@ exports.defaultConfig = defaultConfig;
  */
 const getClientConfig = (config) => {
     var _a;
-    const { app, exportsOutputDirectory, sitesOutputDirectory, assets_zip_links = { icons: null, logos: null }, useVariables, runtime, } = Object.assign(Object.assign({}, (0, exports.defaultConfig)()), config);
+    const { app, exportsOutputDirectory, sitesOutputDirectory, assets_zip_links = { icons: null, logos: null }, useVariables, runtime, } = config;
     const mode = (_a = runtime === null || runtime === void 0 ? void 0 : runtime.mode) !== null && _a !== void 0 ? _a : 'workspace';
     // Connected-workspace affordance: only a workspace with a resolvable registry URL is "connected".
     // URL-only threshold (no token required) so the publish hint surfaces before the access token is

package/dist/config/env.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 declare const loadProfileEnv: (profile?: string, directory?: string) => void;

package/dist/config/env.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadProfileEnv = void 0;
+const dotenv_1 = __importDefault(require("dotenv"));
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("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_1.default.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.
+ */
+const loadProfileEnv = (profile, directory = process.cwd()) => {
+    if (!profile) {
+        return;
+    }
+    const envPath = path_1.default.resolve(directory, `.env.${profile}`);
+    if (!fs_extra_1.default.existsSync(envPath)) {
+        return;
+    }
+    const parsed = dotenv_1.default.parse(fs_extra_1.default.readFileSync(envPath));
+    for (const [key, value] of Object.entries(parsed)) {
+        if (processEnvKeys.has(key)) {
+            continue;
+        }
+        process.env[key] = value;
+    }
+};
+exports.loadProfileEnv = loadProfileEnv;

package/dist/config/errors.d.ts

@@ -0,0 +1,4 @@
+/** Raised when configuration cannot be loaded or resolved. */
+export declare class HandoffConfigError extends Error {
+    constructor(message: string);
+}

package/dist/config/errors.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandoffConfigError = void 0;
+/** Raised when configuration cannot be loaded or resolved. */
+class HandoffConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HandoffConfigError';
+    }
+}
+exports.HandoffConfigError = HandoffConfigError;

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

@@ -0,0 +1,24 @@
+/** 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 declare const fromEnv: <T = string>(name: string, options?: {
+    default: T;
+}) => EnvReference<T>;
+export declare const isEnvReference: (value: unknown) => value is EnvReference<unknown>;

package/dist/config/from-env.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEnvReference = exports.fromEnv = void 0;
+const fromEnv = (name, options) => options === undefined ? { $env: name } : { $env: name, default: options.default };
+exports.fromEnv = fromEnv;
+const isEnvReference = (value) => value !== null && typeof value === 'object' && Object.prototype.hasOwnProperty.call(value, '$env');
+exports.isEnvReference = isEnvReference;

package/dist/config/helpers.d.ts

@@ -3,5 +3,7 @@ export declare 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 declare const defineConfig: (config: Config) => Config;

package/dist/config/helpers.js

@@ -20,12 +20,14 @@ const normalizeAppConfig = (app) => {
 };
 const normalizeConfig = (config) => {
     const { devAccessToken, figmaProjectId, assetsZipLinks, app } = config, rest = __rest(config, ["devAccessToken", "figmaProjectId", "assetsZipLinks", "app"]);
-    return Object.assign(Object.assign({}, rest), { dev_access_token: devAccessToken !== null && devAccessToken !== void 0 ? devAccessToken : config.dev_access_token, figma_project_id: figmaProjectId !== null && figmaProjectId !== void 0 ? figmaProjectId : config.figma_project_id, assets_zip_links: assetsZipLinks !== null && assetsZipLinks !== void 0 ? assetsZipLinks : config.assets_zip_links, app: normalizeAppConfig(app) });
+    return Object.assign(Object.assign({}, rest), { dev_access_token: devAccessToken !== undefined ? devAccessToken : config.dev_access_token, figma_project_id: figmaProjectId !== undefined ? figmaProjectId : config.figma_project_id, assets_zip_links: assetsZipLinks !== null && assetsZipLinks !== void 0 ? assetsZipLinks : config.assets_zip_links, app: normalizeAppConfig(app) });
 };
 exports.normalizeConfig = normalizeConfig;
 /**
  * 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.
  */
 const defineConfig = (config) => (0, exports.normalizeConfig)(config);
 exports.defineConfig = defineConfig;

package/dist/config/index.d.ts

@@ -1,6 +1,7 @@
 export { defaultConfig, getClientConfig, isMcpEnabled } from './defaults';
 export type { ImageStyle } from './defaults';
-export { HandoffConfigError, initConfig, initConfigWithMetadata } from './loader';
+export { loadProfileEnv } from './env';
+export { CONFIG_FILE_PREFERENCE, HandoffConfigError, initConfig, initConfigWithMetadata, resolveProfileSelection } from './loader';
 export type { ConfigLoadContext } from './loader';
 export { defineConfig } from './helpers';
 export { initRuntimeConfig } from './runtime';

package/dist/config/index.js

@@ -1,16 +1,21 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isIncluded = exports.addToCatalog = exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.initConfigWithMetadata = exports.initConfig = exports.HandoffConfigError = exports.isMcpEnabled = exports.getClientConfig = exports.defaultConfig = void 0;
+exports.isIncluded = exports.addToCatalog = exports.validateConfig = exports.initRuntimeConfig = exports.defineConfig = exports.resolveProfileSelection = exports.initConfigWithMetadata = exports.initConfig = exports.HandoffConfigError = exports.CONFIG_FILE_PREFERENCE = exports.loadProfileEnv = exports.isMcpEnabled = exports.getClientConfig = exports.defaultConfig = void 0;
 // Config defaults and client config
 var defaults_1 = require("./defaults");
 Object.defineProperty(exports, "defaultConfig", { enumerable: true, get: function () { return defaults_1.defaultConfig; } });
 Object.defineProperty(exports, "getClientConfig", { enumerable: true, get: function () { return defaults_1.getClientConfig; } });
 Object.defineProperty(exports, "isMcpEnabled", { enumerable: true, get: function () { return defaults_1.isMcpEnabled; } });
+// Environment files
+var env_1 = require("./env");
+Object.defineProperty(exports, "loadProfileEnv", { enumerable: true, get: function () { return env_1.loadProfileEnv; } });
 // Config file loading
 var loader_1 = require("./loader");
+Object.defineProperty(exports, "CONFIG_FILE_PREFERENCE", { enumerable: true, get: function () { return loader_1.CONFIG_FILE_PREFERENCE; } });
 Object.defineProperty(exports, "HandoffConfigError", { enumerable: true, get: function () { return loader_1.HandoffConfigError; } });
 Object.defineProperty(exports, "initConfig", { enumerable: true, get: function () { return loader_1.initConfig; } });
 Object.defineProperty(exports, "initConfigWithMetadata", { enumerable: true, get: function () { return loader_1.initConfigWithMetadata; } });
+Object.defineProperty(exports, "resolveProfileSelection", { enumerable: true, get: function () { return loader_1.resolveProfileSelection; } });
 // Config helpers
 var helpers_1 = require("./helpers");
 Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return helpers_1.defineConfig; } });