handoff-app 2.0.0-7 → 2.0.0-9

package/README.md

@@ -74,17 +74,19 @@ The declaration supplies stable identity, documentation metadata, source entries
 
 ### React
 
-Handoff finds the implementation file from its import, so you do not need to repeat the path.
+Handoff finds the implementation file from its import, so you do not need to repeat the path, and
+builds the item's CSS from the stylesheets that import chain pulls in, descendants included.
 Previews are named exports. `Preview<typeof item>` gives them the implementation's argument type.
 
 ```tsx
 // components/example/Component.tsx
 export type ComponentProps = {
   label: string;
+  onSelect?: () => void;
 };
 
-export default function Component({ label }: ComponentProps) {
-  return <div>{label}</div>;
+export default function Component({ label, onSelect }: ComponentProps) {
+  return <div onClick={onSelect}>{label}</div>;
 }
 ```
 
@@ -112,6 +114,20 @@ export const Default = {
 
 The export name is the preview name. Use `name` to set a different display title.
 
+Arguments are serialized, so a preview that needs an icon, a callback, JSX children, or its own
+state declares `render` instead. It renders as a component, so a capitalized name lets it use hooks, and the item keeps
+documenting the implementation rather than a wrapper. Name a declaration that holds JSX
+`example.handoff.tsx`.
+
+```tsx
+export const Interactive = {
+  render: function Interactive() {
+    const [label, setLabel] = useState('Example');
+    return <Component label={label} onSelect={() => setLabel('Selected')} />;
+  },
+} satisfies ComponentPreview;
+```
+
 ### Handlebars
 
 The implementation is the path to the template. Arguments are `Record<string, unknown>` by default;
@@ -359,12 +375,12 @@ runtime variables listed above are supplied through the deployment environment.
 
 #### Neon PostgreSQL
 
-The Neon connection driver is selected in `handoff.config.ts`:
+Import `fromEnv` from `handoff-app`. Select the Neon connection driver in `handoff.config.ts`:
 
 ```ts
 runtime: {
   registry: {
-    databaseUrlEnv: 'DATABASE_URL',
+    databaseUrl: fromEnv('DATABASE_URL'),
     database: {
       driver: 'neon',
     },
@@ -404,6 +420,12 @@ should not be left unattended before installation is complete.
 
 ### 4. Workspace authorization
 
+A workspace reaches a registry with a registry URL and an access token. There
+are two ways to supply them. Both use the same kind of token, and both are
+listed and revoked under Account → Access tokens in the registry.
+
+#### Device login
+
 CLI authorization is started from the source workspace with:
 
 ```bash
@@ -411,9 +433,48 @@ npm run login -- --url http://localhost:4000
 ```
 
 Registry sign-in, entry of the displayed device code, and CLI approval are
-completed in the browser. The revocable credential is saved in
+completed in the browser. The issued credential is saved in
 `.handoff/cli-auth.json` for that exact registry URL.
 
+One credential is saved per profile, so a workspace can stay signed in to
+several registries at the same time:
+
+```bash
+npm run login -- --profile staging --url https://staging.example.com
+npm run publish -- all --profile staging
+```
+
+A login profile name is free. It needs no `handoff.config.<name>.*` file, and
+`login` is the only command that accepts a new name. A profile without its own
+login falls back to the default login, so one `npm run login` is still enough
+for a workspace with one registry.
+
+`npm run logout` revokes and removes the login of the selected profile. The
+`--all` option removes every saved login.
+
+#### Environment variables
+
+A token is created in the registry under Account → Access tokens. Read and
+write access is required to publish; read access is enough to check out. The
+token and the registry URL are then set in `.env`:
+
+```dotenv
+HANDOFF_REGISTRY_URL=http://localhost:4000
+HANDOFF_REGISTRY_ACCESS_TOKEN=hnd_...
+```
+
+No configuration file entry is needed, because these two variables are the
+defaults for `runtime.registryConnection`. A selected profile reads
+`.env.<profile>` on top of `.env`, so one workspace can address a different
+registry per profile. In CI, the job environment supplies the same two
+variables instead of a file.
+
+Environment values win over a saved device login, so a CI job stays
+deterministic on a machine where a developer is signed in. A token is only used
+for the registry URL it was issued for. If the environment names a different
+registry than the login of the selected profile, publish and checkout report
+which login was skipped and why.
+
 ### 5. Content publishing
 
 Every kind in the workspace is published in dependency order with:
@@ -462,13 +523,18 @@ After the registry is reloaded, the published catalog items and foundations are
 visible. Published database records are read by registry pages; the local
 workspace is never read directly.
 
-For CI, a registry connection and user-issued token are configured:
+For CI, supply `HANDOFF_REGISTRY_URL` and `HANDOFF_REGISTRY_ACCESS_TOKEN`
+through the job environment, as described under
+[Workspace authorization](#4-workspace-authorization). A connection block in
+`handoff.config.ts` is needed only to pin the URL in the repository, or to read
+the values from differently named variables (`fromEnv` is imported from
+`handoff-app`):
 
 ```ts
 runtime: {
   registryConnection: {
     url: 'https://registry.example.com',
-    accessTokenEnv: 'HANDOFF_REGISTRY_ACCESS_TOKEN',
+    accessToken: fromEnv('HANDOFF_REGISTRY_ACCESS_TOKEN'),
   },
 },
 ```
@@ -521,17 +587,19 @@ for Claude Code, Cursor and VS Code behind the plug icon in the header. By hand:
 ## Configuration
 
 Configuration is read from `handoff.config.ts`, `.js`, `.cjs`, or `.json`, in
-that order. `defineConfig` provides typed authoring. A partial `runtime` block
-is deep-merged with defaults.
+that order. `defineConfig` provides typed authoring. Values merge onto the
+defaults: plain objects merge recursively, and arrays, scalars, `null`, and
+functions replace.
 
 Useful environment variables:
 
 | Variable | Purpose |
 | --- | --- |
+| `HANDOFF_PROFILE` | Config profile merged onto the base config |
 | `HANDOFF_FIGMA_PROJECT_ID` | Figma file ID used by `fetch` |
 | `HANDOFF_DEV_ACCESS_TOKEN` | Figma personal access token used by `fetch` |
 | `HANDOFF_REGISTRY_URL` | Connected workspace registry URL |
-| `HANDOFF_REGISTRY_ACCESS_TOKEN` | User-issued CI token |
+| `HANDOFF_REGISTRY_ACCESS_TOKEN` | Registry access token used by a connected workspace |
 | `HANDOFF_SYNC_SECRET` | Optional deployment-wide registry credential |
 | `DATABASE_URL` | Registry PostgreSQL connection string |
 | `AUTH_SECRET` | Registry session-signing secret, at least 32 characters |
@@ -550,6 +618,52 @@ Vercel Blob or a custom adapter can be selected through
 selected through `runtime.registry.database.driver`; PostgreSQL is used by
 both.
 
+## Profiles
+
+A profile is a sidecar config file that merges onto the base config. It holds
+only what changes between environments, so a project keeps one shared config
+instead of a second complete copy of it.
+
+- The base config is `handoff.config.ts`, `.js`, `.cjs`, or `.json`. It is the
+  only config file loaded when no profile is selected.
+- A profile file is `handoff.config.<profile>.*`, with the same four
+  extensions.
+- Select a profile with `--profile <name>` or with `HANDOFF_PROFILE`.
+  `--profile` takes precedence over `HANDOFF_PROFILE`.
+- Profile names are not predefined. A name can contain lowercase letters,
+  numbers, and hyphens.
+- A selected profile must exist. If no `handoff.config.<name>.*` file is found,
+  the command stops with an error.
+- `login`, `logout`, `publish`, and `checkout` also accept a profile that has
+  only a saved registry login, because there the profile selects the registry.
+  Every other command still needs the config file.
+- Layers resolve as defaults, base config, profile, then programmatic config,
+  with the merge rules described under [Configuration](#configuration).
+- A selected profile also reads `.env.<profile>` on top of `.env`, when that
+  file exists. Both are read from the directory the command runs in, and a
+  variable already set in the environment beats both files.
+
+```bash
+npx handoff-app build --target registry --profile registry
+```
+
+`build --target registry` always packages a registry-mode application, so a
+profile does not need to set `runtime.mode`. This makes a profile a good place
+for the registry build settings: the database driver, the database
+environment-variable name, the asset storage, and whether MCP is enabled. A
+hosting provider or a CI job selects the profile through `HANDOFF_PROFILE`.
+
+`defineConfig` types a profile as well as a base config. The generated
+`.gitignore` lists `handoff.config.local.*`, which makes `local` the usual name
+for a profile that stays on one machine.
+
+Arrays replace, so a profile that declares `catalog.include` also decides what
+`make` and `checkout` register.
+
+`.env.<profile>` is read once at startup rather than watched.
+`HANDOFF_WORKING_PATH` cannot be set from it, because the working path is
+resolved before any profile is known.
+
 ## CLI reference
 
 | Command | Description |
@@ -563,10 +677,12 @@ both.
 | `npm run validate` | Configured components are validated |
 | `npm run publish -- <kind\|all> [id...]` | Catalog items, pages, tokens, or assets are published |
 | `npm run checkout -- <kind\|all> [id...]` | Published content is pulled into a workspace |
-| `npm run login -- --url <url>` | The CLI is authorized through the registry device flow |
-| `npm run logout -- [--url <url>]` | A saved CLI credential is revoked and removed |
+| `npm run login -- [--profile <name>] --url <url>` | The CLI is authorized through the registry device flow |
+| `npm run logout -- [--profile <name>] [--all]` | Saved CLI credentials are revoked and removed |
 
-`publish` and `checkout` additionally accept `--dry-run`, and `publish` accepts `--no-build`.
+Every command except `init` accepts `-c, --config`, `--profile`, `-d, --debug`,
+and `-f, --force`. `publish` and `checkout` additionally accept `--dry-run`, and
+`publish` accepts `--no-build`.
 
 Arguments after `--` are forwarded to the local CLI. Exact options can be shown
 by adding `--help` after the separator. Advanced configuration and hooks are

package/UPGRADE.md

@@ -18,10 +18,30 @@ Each feature section identifies the affected projects and the required changes.
 
 | Change | Affected projects |
 | --- | --- |
+| [Figma token environment references](#figma-token-environment-references) | Projects that put a Figma token directly in config |
 | [Catalog items](#catalog-items) | Projects with component or pattern declarations |
 
 <!-- Add future breaking changes as feature sections before "Verify the upgrade". Add each section to this table. -->
 
+### Figma token environment references
+
+`devAccessToken` and its legacy spelling `dev_access_token` now accept only an environment reference.
+A literal token throws `HandoffConfigError`, including in JavaScript and JSON configs.
+Move the token to the environment and replace the literal:
+
+```ts
+import { defineConfig, fromEnv } from 'handoff-app';
+
+export default defineConfig({
+  devAccessToken: fromEnv('HANDOFF_DEV_ACCESS_TOKEN'),
+});
+```
+
+For JSON, use `"devAccessToken": { "$env": "HANDOFF_DEV_ACCESS_TOKEN" }`.
+If you already use `HANDOFF_DEV_ACCESS_TOKEN` and omit the config property, no change is required.
+Environment references resolve after profile merging. Higher-layer literals still override default
+environment seeds for properties that allow literals, such as output directories.
+
 ### Catalog items
 
 #### Affected projects

package/dist/app-builder/build.js

@@ -377,13 +377,21 @@ After migrations and deployment, open \`/install\` immediately and create the in
 The installer verifies the deployment but never changes the schema. An exposed, uninstalled registry
 can be claimed by its first visitor, so do not leave this step unattended.
 
-Once installation completes, sign in and authorize a workspace:
+Once installation completes, sign in and authorize a workspace. Either approve the CLI in the
+browser:
 
 \`\`\`bash
 handoff-app login --url https://registry.example.com
 \`\`\`
 
-The browser approval issues a revocable, user-owned credential. The former
+or create a token under Account > Access tokens and set it in the workspace environment:
+
+\`\`\`bash
+HANDOFF_REGISTRY_URL=https://registry.example.com
+HANDOFF_REGISTRY_ACCESS_TOKEN=hnd_…
+\`\`\`
+
+Both produce the same revocable, user-owned credential. The former
 \`HANDOFF_REGISTRY_API_TOKEN\` fixed server secret is no longer accepted.
 
 ## Run it (self-hosting)

package/dist/app-builder/client-config.js

@@ -95,7 +95,9 @@ const persistClientConfig = (handoff_1, ...args_1) => __awaiter(void 0, [handoff
     // even when packaged from a connected project. Otherwise a workspace is connected whenever a
     // registry URL resolves — from config/env or a saved device login — so `login` alone surfaces
     // the publish/checkout UI without also requiring HANDOFF_REGISTRY_URL.
-    const connected = mode === 'registry' ? false : Boolean((yield (0, connection_1.resolveAuthenticatedRegistryConnection)(handoff.config, handoff.workingPath)).url);
+    const connected = mode === 'registry'
+        ? false
+        : Boolean((yield (0, connection_1.resolveAuthenticatedRegistryConnection)(handoff.config, handoff.workingPath, handoff.getProfile())).url);
     clientConfig.runtime = Object.assign(Object.assign({}, clientConfig.runtime), { mode, connected });
     yield fs_extra_1.default.writeJson(path_1.default.resolve(appPath, 'client.config.json'), { config: clientConfig }, { spaces: 2 });
     yield fs_extra_1.default.writeJson(path_1.default.resolve(appPath, 'runtime.server.json'), buildServerRuntimeConfig(handoff.config, options.runtimeModeOverride), { spaces: 2 });

package/dist/app-builder/watchers.js

@@ -264,17 +264,27 @@ const watchRuntimeConfiguration = (handoff, state) => {
                             const entryBefore = handoff.getConfigFileEntry(changedFile);
                             const strategy = entryBefore ? (0, config_diff_1.getStrategy)(entryBefore.kind) : undefined;
                             const handle = entryBefore && strategy ? strategy.capture(handoff, entryBefore.entityId) : undefined;
-                            handoff.reload();
-                            yield (0, client_config_1.persistClientConfig)(handoff);
+                            let reloadFailed = false;
+                            try {
+                                handoff.reload();
+                                yield (0, client_config_1.persistClientConfig)(handoff);
+                            }
+                            catch (e) {
+                                // A failed reload leaves the last config that loaded on the instance, so the
+                                // re-arm below still names the file that just broke. Without it the file drops
+                                // out of the watch set - chokidar stops tracking a watched file once it is
+                                // deleted - and a later valid save is never seen.
+                                reloadFailed = true;
+                                logger_1.Logger.error('Error reloading runtime configuration:', e);
+                            }
                             (0, exports.watchRuntimeComponents)(handoff, state, (0, component_1.getRuntimeComponentsPathsToWatch)(handoff));
                             (0, exports.watchRuntimeConfiguration)(handoff, state);
+                            if (reloadFailed) {
+                                return;
+                            }
                             const entryAfter = handoff.getConfigFileEntry(changedFile);
-                            const normalizedChanged = (0, path_2.normalizePathForCompare)(changedFile);
-                            const normalizedMainConfig = handoff.getMainConfigFilePath()
-                                ? (0, path_2.normalizePathForCompare)(handoff.getMainConfigFilePath())
-                                : undefined;
                             const kindChanged = !!entryBefore && !!entryAfter && entryBefore.kind !== entryAfter.kind;
-                            if (normalizedMainConfig && normalizedChanged === normalizedMainConfig) {
+                            if (handoff.isMainConfigFile(changedFile)) {
                                 yield (0, builder_1.default)(handoff);
                             }
                             else if (kindChanged) {

package/dist/cache/build-cache.js

@@ -35,7 +35,11 @@ const CACHE_VERSION = '1.0.0';
  * Gets the path to the build cache file
  */
 function getCachePath(handoff) {
-    return path_1.default.resolve(handoff.modulePath, '.handoff', handoff.getProjectId(), '.cache', 'build-cache.json');
+    // Two profiles share one project id and can build different output, so the profile has to name
+    // the cache file. One shared cache would serve the other profile's components.
+    const profile = handoff.getProfile();
+    const fileName = profile ? `build-cache.${profile}.json` : 'build-cache.json';
+    return path_1.default.resolve(handoff.modulePath, '.handoff', handoff.getProjectId(), '.cache', fileName);
 }
 /**
  * Loads the build cache from disk

package/dist/catalog/normalize.js

@@ -88,6 +88,9 @@ const normalizeCatalogItem = (moduleExports, options) => {
     entries[entryKey] = path_1.default.resolve(directory, source.file);
     // Existing builders consume template as the primary build input for every renderer.
     entries.template = entries[entryKey];
+    // The renderer and the hydration bundle both read a preview `render` from the declaration.
+    if (options.declarationPath)
+        entries.declaration = options.declarationPath;
     // A wrong renderer builds a broken preview without failing on its own, so a mismatch is fatal.
     // `config/runtime.ts` turns the throw into a skipped item that retries on the next save.
     const claim = (0, renderers_1.sourceForFile)(source.file);

package/dist/catalog/previews.js

@@ -8,16 +8,17 @@ const fs_extra_1 = __importDefault(require("fs-extra"));
 const lodash_1 = require("lodash");
 /**
  * A declaration module exports more than previews: the item itself, the implementation it
- * re-exports, helper values. Accept only a plain object that owns `args` or `name`, so an exported
- * component or helper is never mistaken for a preview.
+ * re-exports, helper values. Accept only a plain object that owns one of the preview fields, so an
+ * exported component or helper is never mistaken for a preview.
  *
  * `getCsfStoryEntries` does not fit here: on a CSF file every named export is a story, and on a
  * declaration file it is not.
  */
+const PREVIEW_KEYS = ['args', 'name', 'render'];
 const isPreviewDeclaration = (value) => {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
-    return Object.prototype.hasOwnProperty.call(value, 'args') || Object.prototype.hasOwnProperty.call(value, 'name');
+    return PREVIEW_KEYS.some((key) => Object.prototype.hasOwnProperty.call(value, key));
 };
 /** Matches an exported binding, an export list, or a CommonJS export assignment. */
 const EXPORT_PATTERNS = [
@@ -99,7 +100,7 @@ const createCatalogPreviews = (moduleExports, declarationPath) => {
             throw new Error(`Preview "${exportName}" uses removed fields. Use args and name. See UPGRADE.md#catalog-items.`);
         }
         const preview = value;
-        previews[exportName] = Object.assign({ title: preview.name || (0, lodash_1.startCase)(exportName), values: Object.assign({}, ((_a = preview.args) !== null && _a !== void 0 ? _a : {})), url: (_b = preview.url) !== null && _b !== void 0 ? _b : '' }, (preview.usage ? { usage: preview.usage } : {}));
+        previews[exportName] = Object.assign(Object.assign({ title: preview.name || (0, lodash_1.startCase)(exportName), values: Object.assign({}, ((_a = preview.args) !== null && _a !== void 0 ? _a : {})), url: (_b = preview.url) !== null && _b !== void 0 ? _b : '' }, (preview.usage ? { usage: preview.usage } : {})), (typeof preview.render === 'function' ? { render: preview.render } : {}));
     }
     return declarationPath ? (0, exports.orderPreviews)(previews, (0, exports.readExportOrder)(declarationPath)) : previews;
 };

package/dist/catalog/types.d.ts

@@ -43,6 +43,14 @@ export type CatalogPreview<TArgs = Record<string, unknown>> = {
     args?: TArgs;
     usage?: string;
     url?: string;
+    /**
+     * Renders this preview in place of the implementation, for props it cannot carry as data: an icon
+     * component, a callback, JSX children, or state the preview owns.
+     *
+     * Rendered as a component with `args`, so it can use hooks. The item still documents the
+     * implementation, so a wrapper never becomes the published API.
+     */
+    render?: (args: TArgs) => unknown;
 };
 /**
  * `__args` exists only in the type system so `Preview<typeof item>` can infer the preview argument type.

package/dist/cli/auth/device.d.ts

@@ -1,8 +1,13 @@
 import { type CliAuth } from './store';
 export interface LoginOptions {
     openBrowser?: boolean;
+    /** Profile the issued credential is saved under. Omitted, it is the default profile. */
+    profile?: string;
 }
-/** Complete the device grant and persist the one-time plaintext access token for this workspace. */
+/**
+ * Complete the device grant and persist the one-time plaintext access token for this workspace,
+ * under the selected profile.
+ */
 export declare const loginWithDevice: (workingPath: string, remoteUrl: string, options?: LoginOptions) => Promise<CliAuth>;
 /**
  * Best-effort remote revocation. The caller must clear the local credential regardless of failure.

package/dist/cli/auth/device.js

@@ -53,7 +53,10 @@ const shouldOpenBrowser = (options) => {
     return process.env.HANDOFF_LOGIN_NO_BROWSER !== '1' && process.env.HANDOFF_LOGIN_NO_BROWSER !== 'true';
 };
 const positiveNumberOr = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
-/** Complete the device grant and persist the one-time plaintext access token for this workspace. */
+/**
+ * Complete the device grant and persist the one-time plaintext access token for this workspace,
+ * under the selected profile.
+ */
 const loginWithDevice = (workingPath_1, remoteUrl_1, ...args_1) => __awaiter(void 0, [workingPath_1, remoteUrl_1, ...args_1], void 0, function* (workingPath, remoteUrl, options = {}) {
     const baseUrl = (0, store_1.normalizeRegistryUrl)(remoteUrl);
     let deviceResponse;
@@ -115,7 +118,7 @@ const loginWithDevice = (workingPath_1, remoteUrl_1, ...args_1) => __awaiter(voi
                 accessToken: token.access_token,
                 expiresAtMs: Date.now() + expiresIn * 1000,
             };
-            yield (0, store_1.writeCliAuth)(workingPath, auth);
+            yield (0, store_1.writeCliAuth)(workingPath, auth, options.profile);
             return auth;
         }
         const failure = responseError(token);

package/dist/cli/auth/store.d.ts

@@ -5,6 +5,8 @@ export interface CliAuth {
     /** Epoch milliseconds after which the token must not be used. */
     expiresAtMs: number;
 }
+/** Name a login is saved under when no profile is selected. */
+export declare const DEFAULT_LOGIN_PROFILE = "default";
 /**
  * Canonicalize a registry URL for both HTTP requests and exact credential matching.
  * Base paths are retained; query strings, fragments, credentials, and trailing slashes are not.
@@ -17,13 +19,20 @@ export declare const normalizeRegistryUrl: (value: string) => string;
  */
 export declare const assertRegistryOriginUrl: (baseUrl: string, candidate: string) => string;
 export declare const cliAuthFilePath: (workingPath: string) => string;
-/** Invalid or partial credential files are treated as unauthenticated. */
-export declare const readCliAuth: (workingPath: string) => Promise<CliAuth | null>;
+/** Every saved login, keyed by profile name. A missing or unreadable file reads as no logins. */
+export declare const readCliLogins: (workingPath: string) => Promise<Record<string, CliAuth>>;
+/** The login saved under one profile name. Never falls back to another profile. */
+export declare const readCliAuth: (workingPath: string, profile?: string) => Promise<CliAuth | null>;
 /**
- * Atomically replace the credential file. Restrictive permissions are best-effort on platforms
- * whose filesystems do not support POSIX modes.
+ * Profile names that have a saved login. Synchronous because config loading is, and the loader needs
+ * these names to decide whether a selected profile resolves.
  */
-export declare const writeCliAuth: (workingPath: string, auth: CliAuth) => Promise<void>;
-export declare const clearCliAuth: (workingPath: string) => Promise<void>;
+export declare const loginProfileNames: (workingPath: string) => string[];
+/** Save the login for one profile and leave the other profiles in place. */
+export declare const writeCliAuth: (workingPath: string, auth: CliAuth, profile?: string) => Promise<void>;
+/** Remove the login for one profile, and the file itself once no login is left. */
+export declare const clearCliAuth: (workingPath: string, profile?: string) => Promise<void>;
+/** Remove every saved login. */
+export declare const clearAllCliAuth: (workingPath: string) => Promise<void>;
 export declare const cliAuthMatchesRegistry: (auth: CliAuth | null, remoteUrl: string) => boolean;
 export declare const cliAuthTokenIsValid: (auth: CliAuth | null, skewMs?: number) => boolean;

package/dist/cli/auth/store.js

@@ -12,9 +12,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.cliAuthTokenIsValid = exports.cliAuthMatchesRegistry = exports.clearCliAuth = exports.writeCliAuth = exports.readCliAuth = exports.cliAuthFilePath = exports.assertRegistryOriginUrl = exports.normalizeRegistryUrl = void 0;
+exports.cliAuthTokenIsValid = exports.cliAuthMatchesRegistry = exports.clearAllCliAuth = exports.clearCliAuth = exports.writeCliAuth = exports.loginProfileNames = exports.readCliAuth = exports.readCliLogins = exports.cliAuthFilePath = exports.assertRegistryOriginUrl = exports.normalizeRegistryUrl = exports.DEFAULT_LOGIN_PROFILE = void 0;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
+/** Name a login is saved under when no profile is selected. */
+exports.DEFAULT_LOGIN_PROFILE = 'default';
 const AUTH_DIRECTORY = '.handoff';
 const AUTH_FILE = 'cli-auth.json';
 /**
@@ -63,38 +65,71 @@ const assertRegistryOriginUrl = (baseUrl, candidate) => {
 exports.assertRegistryOriginUrl = assertRegistryOriginUrl;
 const cliAuthFilePath = (workingPath) => path_1.default.resolve(workingPath, AUTH_DIRECTORY, AUTH_FILE);
 exports.cliAuthFilePath = cliAuthFilePath;
-const isCliAuth = (value) => {
+/** An invalid or partial entry reads as no login, so one bad entry cannot hide the others. */
+const toCliAuth = (value) => {
     if (!value || typeof value !== 'object')
-        return false;
+        return null;
     const auth = value;
-    return (typeof auth.remoteUrl === 'string' &&
-        typeof auth.accessToken === 'string' &&
-        auth.accessToken.length > 0 &&
-        typeof auth.expiresAtMs === 'number' &&
-        Number.isFinite(auth.expiresAtMs));
-};
-/** Invalid or partial credential files are treated as unauthenticated. */
-const readCliAuth = (workingPath) => __awaiter(void 0, void 0, void 0, function* () {
+    if (typeof auth.remoteUrl !== 'string')
+        return null;
+    if (typeof auth.accessToken !== 'string' || auth.accessToken.length === 0)
+        return null;
+    if (typeof auth.expiresAtMs !== 'number' || !Number.isFinite(auth.expiresAtMs))
+        return null;
     try {
-        const value = (yield fs_extra_1.default.readJson((0, exports.cliAuthFilePath)(workingPath)));
-        if (!isCliAuth(value))
-            return null;
-        return Object.assign(Object.assign({}, value), { remoteUrl: (0, exports.normalizeRegistryUrl)(value.remoteUrl) });
+        return { remoteUrl: (0, exports.normalizeRegistryUrl)(auth.remoteUrl), accessToken: auth.accessToken, expiresAtMs: auth.expiresAtMs };
     }
     catch (_a) {
         return null;
     }
+};
+const toLogins = (value) => {
+    const logins = value === null || value === void 0 ? void 0 : value.logins;
+    if (!logins || typeof logins !== 'object')
+        return {};
+    const result = {};
+    for (const [profile, entry] of Object.entries(logins)) {
+        const auth = toCliAuth(entry);
+        if (auth)
+            result[profile] = auth;
+    }
+    return result;
+};
+/** Every saved login, keyed by profile name. A missing or unreadable file reads as no logins. */
+const readCliLogins = (workingPath) => __awaiter(void 0, void 0, void 0, function* () {
+    try {
+        return toLogins((yield fs_extra_1.default.readJson((0, exports.cliAuthFilePath)(workingPath))));
+    }
+    catch (_a) {
+        return {};
+    }
 });
+exports.readCliLogins = readCliLogins;
+/** The login saved under one profile name. Never falls back to another profile. */
+const readCliAuth = (workingPath_1, ...args_1) => __awaiter(void 0, [workingPath_1, ...args_1], void 0, function* (workingPath, profile = exports.DEFAULT_LOGIN_PROFILE) { var _a; return (_a = (yield (0, exports.readCliLogins)(workingPath))[profile]) !== null && _a !== void 0 ? _a : null; });
 exports.readCliAuth = readCliAuth;
+/**
+ * Profile names that have a saved login. Synchronous because config loading is, and the loader needs
+ * these names to decide whether a selected profile resolves.
+ */
+const loginProfileNames = (workingPath) => {
+    try {
+        return Object.keys(toLogins(fs_extra_1.default.readJsonSync((0, exports.cliAuthFilePath)(workingPath))));
+    }
+    catch (_a) {
+        return [];
+    }
+};
+exports.loginProfileNames = loginProfileNames;
 /**
  * Atomically replace the credential file. Restrictive permissions are best-effort on platforms
  * whose filesystems do not support POSIX modes.
  */
-const writeCliAuth = (workingPath, auth) => __awaiter(void 0, void 0, void 0, function* () {
+const writeCliLogins = (workingPath, logins) => __awaiter(void 0, void 0, void 0, function* () {
     const filePath = (0, exports.cliAuthFilePath)(workingPath);
     const directory = path_1.default.dirname(filePath);
     const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-    const value = Object.assign(Object.assign({}, auth), { remoteUrl: (0, exports.normalizeRegistryUrl)(auth.remoteUrl) });
+    const value = { logins };
     yield fs_extra_1.default.ensureDir(directory, 0o700);
     try {
         yield fs_extra_1.default.chmod(directory, 0o700);
@@ -123,14 +158,32 @@ const writeCliAuth = (workingPath, auth) => __awaiter(void 0, void 0, void 0, fu
         throw error;
     }
 });
+/** Save the login for one profile and leave the other profiles in place. */
+const writeCliAuth = (workingPath_1, auth_1, ...args_1) => __awaiter(void 0, [workingPath_1, auth_1, ...args_1], void 0, function* (workingPath, auth, profile = exports.DEFAULT_LOGIN_PROFILE) {
+    const logins = yield (0, exports.readCliLogins)(workingPath);
+    logins[profile] = Object.assign(Object.assign({}, auth), { remoteUrl: (0, exports.normalizeRegistryUrl)(auth.remoteUrl) });
+    yield writeCliLogins(workingPath, logins);
+});
 exports.writeCliAuth = writeCliAuth;
-const clearCliAuth = (workingPath) => __awaiter(void 0, void 0, void 0, function* () {
+/** Remove the login for one profile, and the file itself once no login is left. */
+const clearCliAuth = (workingPath_1, ...args_1) => __awaiter(void 0, [workingPath_1, ...args_1], void 0, function* (workingPath, profile = exports.DEFAULT_LOGIN_PROFILE) {
+    const logins = yield (0, exports.readCliLogins)(workingPath);
+    delete logins[profile];
+    if (Object.keys(logins).length === 0) {
+        yield (0, exports.clearAllCliAuth)(workingPath);
+        return;
+    }
+    yield writeCliLogins(workingPath, logins);
+});
+exports.clearCliAuth = clearCliAuth;
+/** Remove every saved login. */
+const clearAllCliAuth = (workingPath) => __awaiter(void 0, void 0, void 0, function* () {
     const filePath = (0, exports.cliAuthFilePath)(workingPath);
     if (yield fs_extra_1.default.pathExists(filePath)) {
         yield fs_extra_1.default.remove(filePath);
     }
 });
-exports.clearCliAuth = clearCliAuth;
+exports.clearAllCliAuth = clearAllCliAuth;
 const cliAuthMatchesRegistry = (auth, remoteUrl) => {
     if (!auth)
         return false;

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

@@ -4,5 +4,10 @@ export interface LoginArgs extends SharedArgs {
     url?: string;
     browser?: boolean;
 }
+/**
+ * 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.
+ */
 declare const command: CommandModule<{}, LoginArgs>;
 export default command;