@vltpkg/cli-sdk 1.0.5 → 1.0.7

package/dist/commands/deprecate.js

@@ -127,7 +127,7 @@ export const command = async (conf) => {
             cause: asError(err),
         });
     }
-    if (response.statusCode !== 200 && response.statusCode !== 201) {
+    if (response.statusCode < 200 || response.statusCode >= 300) {
         throw error('failed to update deprecation status', {
             url: packageUrl,
             response,

package/dist/commands/login.js

@@ -1,4 +1,5 @@
 import { RegistryClient } from '@vltpkg/registry-client';
+import { configWriteTarget } from "../config/index.js";
 import { commandUsage } from "../config/usage.js";
 import { missingRegistryError } from "../require-registry.js";
 export const usage = () => commandUsage({
@@ -10,7 +11,9 @@ export const usage = () => commandUsage({
                   There is no default registry, so a registry must either
                   already be configured or be provided with
                   \`--registry=<url>\`. On success the registry is written to
-                  the project's \`vlt.json\`.`,
+                  the project's \`vlt.json\`, so that it applies to this
+                  project only. Pass \`--config=user\` to configure it for
+                  every project instead.`,
     options: {
         registry: {
             value: '<url>',
@@ -20,6 +23,11 @@ export const usage = () => commandUsage({
             value: '<name>',
             description: 'Identity namespace used to store auth tokens.',
         },
+        config: {
+            value: '<user | project>',
+            description: 'Which config file to write the registry to. Defaults to ' +
+                '`project`.',
+        },
     },
 });
 export const command = async (conf) => {
@@ -31,5 +39,7 @@ export const command = async (conf) => {
     const rc = new RegistryClient(conf.options);
     await rc.login(registry);
     // persist the registry so subsequent commands are configured
-    await conf.addConfigToFile('project', { registry });
+    await conf.addConfigToFile(configWriteTarget(conf, 'project'), {
+        registry,
+    });
 };

package/dist/commands/publish.js

@@ -13,6 +13,7 @@ import { createHostContextsMap } from "../query-host-contexts.js";
 import { minimatch } from 'minimatch';
 import { resolveRegistry } from "../require-registry.js";
 import { registryErrorMessage } from "../registry-error-message.js";
+import { stderr } from "../output.js";
 export const needsRegistry = true;
 export const usage = () => commandUsage({
     command: 'publish',
@@ -264,7 +265,10 @@ const commandSingle = async (location, conf) => {
                 cause: asError(err),
             });
         }
-        if (response.statusCode !== 200 && response.statusCode !== 201) {
+        // Any 2xx response is a successful publish. The npm registry may
+        // respond with a 202 Accepted when processing is deferred (e.g. for
+        // publish-time malware scanning).
+        if (response.statusCode < 200 || response.statusCode >= 300) {
             let advice = '';
             if (response.statusCode === 409) {
                 advice = `\n⚠️ ${name}@${version} already exists in the registry. Bump the version and try again.`;
@@ -278,6 +282,12 @@ const commandSingle = async (location, conf) => {
                 response,
             });
         }
+        // On deferred publishes the registry explains the delay in an
+        // npm-notice header, e.g. "Your package is being processed and may
+        // take a few minutes to become available."
+        const notice = response.getHeaderString('npm-notice');
+        if (notice)
+            stderr(`⚠️ ${notice}`);
     }
     await run({
         ...runOptions,

package/dist/commands/setup.d.ts

@@ -17,6 +17,11 @@ export type SetupResult = {
     which: 'user' | 'project';
     /** the alias -> url map that was staged into config */
     registries: Record<string, string>;
+    /**
+     * set when the config we wrote to is outranked for registry selection by
+     * the project's `vlt.json`, so the result won't take effect here.
+     */
+    shadowedByProject?: boolean;
 };
 export declare const views: {
     readonly human: (result: SetupResult) => string;

package/dist/commands/setup.js

@@ -2,6 +2,8 @@ import { error } from '@vltpkg/error-cause';
 import { RegistryClient } from '@vltpkg/registry-client';
 import { defaultRegistries } from '@vltpkg/spec';
 import { createInterface } from 'node:readline/promises';
+import { configWriteTarget } from "../config/index.js";
+import { registrySelectionFields } from "../config/merge-layers.js";
 import { commandUsage } from "../config/usage.js";
 import { stdout } from "../output.js";
 /** Where users sign up for / log into a vlt.io account. */
@@ -13,17 +15,6 @@ export const VLT_REGISTRY_BASE = 'https://registry.vlt.io';
  * `npm` is the {@link https://docs.vlt.sh | default bare-spec alias}.
  */
 export const accountRegistries = ['npm', 'main'];
-/**
- * What each account registry is, in the order {@link accountRegistries}
- * is authenticated. Every registry has its own credentials, so the
- * web-login flow opens the browser once per registry -- naming what is
- * being authenticated keeps the second prompt from reading like a repeat
- * of the first.
- */
-const accountRegistryAuthPrompts = {
-    npm: `First, let's authenticate your public npm registry mirror`,
-    main: `Now let's authenticate your private registry`,
-};
 /** Build the per-account registry URL for a given registry name. */
 export const accountRegistryURL = (account, name) => `${VLT_REGISTRY_BASE}/${encodeURIComponent(account)}/${name}/`;
 /** Ensure a registry URL ends with a single trailing slash. */
@@ -38,6 +29,9 @@ export const views = {
         for (const [name, url] of Object.entries(result.registries)) {
             lines.push(`  ${name} -> ${url}`);
         }
+        if (result.shadowedByProject) {
+            lines.push('', `Note: this project's vlt.json configures its own registries, and`, 'project config takes precedence. Re-run with `--config=project`', 'to configure this project instead.');
+        }
         lines.push('', 'You can now install packages, e.g.:', '  vlt install <pkg>');
         return lines.join('\n');
     },
@@ -71,7 +65,7 @@ export const usage = () => commandUsage({
 });
 export const command = async (conf) => {
     const yes = !!conf.get('yes');
-    const which = conf.get('config') === 'project' ? 'project' : 'user';
+    const which = configWriteTarget(conf, 'user');
     let rl;
     const ask = async (question) => {
         rl ??= createInterface(process.stdin, process.stdout);
@@ -96,11 +90,19 @@ export const command = async (conf) => {
         for (const name of accountRegistries) {
             registries[name] = accountRegistryURL(account, name);
         }
-        // 3. merge any user-supplied registry aliases (skip built-in defaults)
+        // 3. merge in registry aliases supplied for this invocation. aliases
+        // that came from a config file are left where they are: copying them
+        // would turn a project-local alias into a global one (or vice versa).
         const builtinRegistries = defaultRegistries;
+        const fileRegistries = {
+            ...conf.layers.user?.registries,
+            ...conf.layers.project?.registries,
+        };
         for (const [name, url] of Object.entries(conf.options.registries)) {
             if (builtinRegistries[name] === url)
                 continue;
+            if (fileRegistries[name] === url)
+                continue;
             registries[name] = normalizeRegistryURL(url);
         }
         const rc = new RegistryClient(conf.options);
@@ -108,12 +110,10 @@ export const command = async (conf) => {
         if (!yes) {
             const doAuth = await ask('Authenticate with your vlt.io account now? (Y/n) ');
             if (!/^n/i.test(doAuth)) {
-                stdout('Each registry is authenticated separately, so the browser ' +
-                    'opens once per registry.');
-                for (const name of accountRegistries) {
-                    stdout(`${accountRegistryAuthPrompts[name]} ("${name}")...`);
-                    await rc.login(accountRegistryURL(account, name));
-                }
+                // one token covers every registry on the account, so the browser
+                // opens once and the token is stored for all of them.
+                stdout(`Authenticating your account registries (${accountRegistries.join(', ')})...`);
+                await rc.login(accountRegistries.map(name => accountRegistryURL(account, name)));
             }
             // 5. offer to add further custom aliases
             for (;;) {
@@ -144,7 +144,17 @@ export const command = async (conf) => {
         }
         // 6. persist the staged registries (merged, not clobbered)
         await conf.addConfigToFile(which, { registries });
-        return { account, which, registries };
+        // writing the user config from inside a project that configures its own
+        // registries has no effect here, so say so rather than looking like it
+        // worked.
+        const shadowedByProject = which === 'user' &&
+            registrySelectionFields.some(f => f in (conf.layers.project ?? {}));
+        return {
+            account,
+            which,
+            registries,
+            ...(shadowedByProject ? { shadowedByProject } : undefined),
+        };
     }
     finally {
         if (rl) {

package/dist/commands/unpublish.js

@@ -141,7 +141,7 @@ export const command = async (conf) => {
                 cause: asError(err),
             });
         }
-        if (response.statusCode !== 200 && response.statusCode !== 201) {
+        if (response.statusCode < 200 || response.statusCode >= 300) {
             throw error('Failed to unpublish package version', {
                 url: putUrl,
                 response,
@@ -188,7 +188,7 @@ export const command = async (conf) => {
                 cause: asError(err),
             });
         }
-        if (response.statusCode !== 200 && response.statusCode !== 201) {
+        if (response.statusCode < 200 || response.statusCode >= 300) {
             throw error('Failed to unpublish package', {
                 url: deleteUrl,
                 response,

package/dist/config/definition.d.ts

@@ -454,5 +454,16 @@ export declare const definition: import("jackspeak").Jack<{
     help: import("jackspeak").ConfigOption<"boolean", false, undefined>;
     all: import("jackspeak").ConfigOption<"boolean", false, undefined>;
 }>;
+/**
+ * The pristine `default` of every known config field, captured here at
+ * module load, before anything can call `jack.setConfigValues()`.
+ *
+ * Config layers are applied by overwriting jackspeak's defaults, and
+ * `setConfigValues()` can only set them. So when a layer stops setting a
+ * field (or removes it with `null`), the definitional default has to be
+ * put back explicitly, otherwise a value left behind by a previous apply
+ * would leak through.
+ */
+export declare const defaultValues: Record<string, unknown>;
 export declare const getSortedCliOptions: () => string[];
 export declare const getSortedKeys: () => string[];

package/dist/config/definition.js

@@ -132,14 +132,22 @@ export const definition = j
      * Definition of all configuration values used by vlt.
      */
     .heading('Configuration')
-    .description(`If a \`vlt.json\` file is present in the root of the current project,
-     then that will be used as a source of configuration information.
-
-     Next, the \`vlt.json\` file in the XDG specified config directory
-     will be checked, and loaded for any fields not set in the local project.
-
-     Object type values will be merged together. Set a field to \`null\` in
-     the JSON configuration to explicitly remove it.
+    .description(`The \`vlt.json\` file in the XDG specified config directory is loaded
+     first, and then the \`vlt.json\` file in the root of the current
+     project, if present, is layered on top of it.
+
+     Scalar values are overridden by the innermost layer that sets them.
+     Object type values are merged together key by key. Set a field, or a
+     key within an object field, to \`null\` in the JSON configuration to
+     explicitly remove it.
+
+     Registry *selection* is an exception, since \`--registry\` outranks any
+     \`--registries\` alias. A layer that sets any of \`registry\`,
+     \`registries\`, or \`default-registry-alias\` owns selection: the
+     \`registry\` and \`default-registry-alias\` it does *not* set are
+     dropped, rather than inherited from an outer layer. So a project that
+     configures its own registry is never sent to the user-level one, while
+     the aliases in the user config stay addressable by name.
 
      Command-specific fields may be set in a nested \`command\` object that
      overrides any options defined at the top level.
@@ -750,6 +758,20 @@ export const definition = j
         description: 'Show all commands, bins, and flags',
     },
 });
+/**
+ * The pristine `default` of every known config field, captured here at
+ * module load, before anything can call `jack.setConfigValues()`.
+ *
+ * Config layers are applied by overwriting jackspeak's defaults, and
+ * `setConfigValues()` can only set them. So when a layer stops setting a
+ * field (or removes it with `null`), the definitional default has to be
+ * put back explicitly, otherwise a value left behind by a previous apply
+ * would leak through.
+ */
+export const defaultValues = Object.fromEntries(Object.entries(definition.toJSON()).map(([field, def]) => [
+    field,
+    def.default,
+]));
 export const getSortedCliOptions = () => {
     const defs = definition.toJSON();
     return getSortedKeys().map((k) => {

package/dist/config/index.d.ts

@@ -2,8 +2,8 @@
  * Module that handles all vlt configuration needs
  *
  * Project-level configs are set in a `vlt.json` file in the local project
- * if present. This will override the user-level configs in the appropriate
- * XDG config path.
+ * if present, and are layered over the user-level configs in the appropriate
+ * XDG config path. See `./merge-layers.ts` for the layering rules.
  *
  * Command-specific configuration can be specified by putting options in a
  * field in the `command` object. For example:
@@ -38,6 +38,11 @@ export type PairsAsRecords = ConfigOptionsNoExtras & {
         [k in keyof Commands]?: ConfigOptionsNoExtras;
     };
 };
+/**
+ * One `vlt.json` file's `config` object, in record form. Every field is
+ * optional, since a config file only sets what it sets.
+ */
+export type ConfigFileLayer = Partial<PairsAsRecords>;
 export declare const pairsToRecords: (obj: NonNullable<ConfigFileData> | OptionsResults<ConfigDefinitions>) => PairsAsRecords;
 export declare const recordsToPairs: (obj: RecordPairs) => RecordPairs;
 export type ConfigDataNoCommand = {
@@ -169,6 +174,14 @@ export declare class Config {
      * in the config file.
      */
     addConfigToFile(this: LoadedConfig, which: WhichConfig, values: NonNullable<ConfigFileData>): Promise<void>;
+    /**
+     * The raw config data from each `vlt.json` file, normalized to record
+     * form, before the layers are merged together. `undefined` for a layer
+     * with no file, or a file with no `config` field.
+     */
+    get layers(): Readonly<{
+        [k in WhichConfig]?: ConfigFileLayer;
+    }>;
     /**
      * Deletes the specified config fields from the named file
      * Returns `true` if anything was changed.
@@ -216,3 +229,11 @@ export type ParsedConfig = Config & {
  * A fully loaded {@link Config} object
  */
 export type LoadedConfig = ParsedConfig;
+/**
+ * Which `vlt.json` a command that persists settings should write to.
+ *
+ * `--config=user` and `--config=project` are explicit. Anything else means
+ * the caller's own default, since `--config` also takes `all` (its default,
+ * meaningful only for `vlt config` reads).
+ */
+export declare const configWriteTarget: (conf: Pick<LoadedConfig, "get">, fallback: WhichConfig) => WhichConfig;

package/dist/config/index.js

@@ -2,8 +2,8 @@
  * Module that handles all vlt configuration needs
  *
  * Project-level configs are set in a `vlt.json` file in the local project
- * if present. This will override the user-level configs in the appropriate
- * XDG config path.
+ * if present, and are layered over the user-level configs in the appropriate
+ * XDG config path. See `./merge-layers.ts` for the layering rules.
  *
  * Command-specific configuration can be specified by putting options in a
  * field in the `command` object. For example:
@@ -31,8 +31,9 @@ import { Monorepo } from '@vltpkg/workspaces';
 import { readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import { PathScurry } from 'path-scurry';
-import { commands, definition, getCommand, isRecordField, recordFields, } from "./definition.js";
+import { commands, definition, defaultValues, getCommand, isRecordField, recordFields, } from "./definition.js";
 import { merge } from "./merge.js";
+import { cloneLayer, mergeLayers } from "./merge-layers.js";
 export { commands, definition, isRecordField, recordFields, };
 export const kCustomInspect = Symbol.for('nodejs.util.inspect.custom');
 // turn a set of pairs into a Record object.
@@ -53,6 +54,25 @@ const reducePairs = (pairs) => {
 };
 const isRecordFieldValue = (k, v) => Array.isArray(v) &&
     recordFields.includes(k);
+/**
+ * `registries` alias names are used as spec prefixes, where `~` is
+ * reserved, and an empty name has nothing to prefix with.
+ */
+const assertRegistryKeys = (registries, file) => {
+    if (!registries || typeof registries !== 'object')
+        return;
+    const obj = Array.isArray(registries) ?
+        reducePairs(registries)
+        : registries;
+    for (const key of Object.keys(obj)) {
+        if (key === '' || key.includes('~')) {
+            throw error('Reserved character found in registries name', {
+                path: file,
+                found: key,
+            });
+        }
+    }
+};
 export const pairsToRecords = (obj) => {
     return Object.fromEntries(Object.entries(obj).map(([k, v]) => [
         k,
@@ -75,7 +95,12 @@ export const recordsToPairs = (obj) => {
         .map(([k, v]) => [
         k,
         k === 'command' && v && typeof v === 'object' ?
-            recordsToPairs(v)
+            // each command's own block gets converted too, mirroring
+            // pairsToRecords
+            Object.fromEntries(Object.entries(v).map(([k, v]) => [
+                k,
+                recordsToPairs(v),
+            ]))
             : (!v ||
                 typeof v !== 'object' ||
                 Array.isArray(v) ||
@@ -277,7 +302,10 @@ export class Config {
      * in the config file.
      */
     async addConfigToFile(which, values) {
-        return this.writeConfigFile(which, merge((await this.#maybeLoadConfigFile(which)) ?? {}, values));
+        // normalize both sides to record form first, so that a record field
+        // written as a `key=value` list in an existing file is still merged key
+        // by key, rather than replaced wholesale.
+        return this.writeConfigFile(which, merge(pairsToRecords((await this.#maybeLoadConfigFile(which)) ?? {}), pairsToRecords(values)));
     }
     // called in this weird bound way so that it can be used by the
     // vlt-json config loading module.
@@ -292,53 +320,92 @@ export class Config {
                 wanted: 'ConfigFileData',
             });
         }
-        const { command, ...values } = recordsToPairs(c);
-        // Validate registries keys don't contain reserved ~ character
-        const registries = c.registries;
-        if (registries && typeof registries === 'object') {
-            const registriesObj = Array.isArray(registries) ?
-                reducePairs(registries)
-                : registries;
-            for (const key of Object.keys(registriesObj)) {
-                if (key === '' || key.includes('~')) {
-                    throw error('Reserved character found in registries name', {
-                        path: file,
-                        found: key,
-                    });
+        const { command, ...values } = c;
+        assertRegistryKeys(values.registries, file);
+        if (command && typeof command === 'object') {
+            for (const opts of Object.values(command)) {
+                if (opts && typeof opts === 'object') {
+                    assertRegistryKeys(opts.registries, file);
                 }
             }
         }
-        if (command) {
-            for (const [c, opts] of Object.entries(command)) {
-                const cmd = getCommand(c);
-                if (cmd && opts && typeof opts === 'object') {
-                    // Validate registries in command-specific config
-                    const cmdRegistries = opts.registries;
-                    if (cmdRegistries && typeof cmdRegistries === 'object') {
-                        const cmdRegistriesObj = Array.isArray(cmdRegistries) ?
-                            reducePairs(cmdRegistries)
-                            : cmdRegistries;
-                        for (const key of Object.keys(cmdRegistriesObj)) {
-                            if (key === '' || key.includes('~')) {
-                                throw error('Reserved character found in registries name', {
-                                    path: file,
-                                    found: key,
-                                });
-                            }
-                        }
-                    }
-                    this.commandValues[cmd] = merge(this.commandValues[cmd] ?? {}, opts);
-                }
+        // validate this layer on its own, so that an invalid value is blamed on
+        // the file it actually came from. `mergeLayers` on a single layer just
+        // strips the `null`s, which mean "remove this field" rather than being
+        // a value jack should ever see.
+        const layer = cloneLayer(pairsToRecords(c));
+        const { command: _cmd, ...single } = mergeLayers([layer]);
+        try {
+            this.jack.validate(recordsToPairs(single));
+        }
+        catch (er) {
+            /* c8 ignore next - for TS */
+            if (er instanceof Error) {
+                // jack only attaches the source path when going through
+                // setConfigValues(), and the CLI's "Problem in Config File" banner
+                // keys off it.
+                /* c8 ignore next - jack always throws with a cause object */
+                const cause = typeof er.cause === 'object' ? er.cause : {};
+                er.cause = { ...cause, path: file };
+            }
+            throw er;
+        }
+        this.#layers[file === find('user') ? 'user' : 'project'] = layer;
+        this.#applyLayers();
+    }
+    /**
+     * The raw config data from each `vlt.json` file, normalized to record
+     * form, before the layers are merged together. `undefined` for a layer
+     * with no file, or a file with no `config` field.
+     */
+    get layers() {
+        return this.#layers;
+    }
+    #layers = {};
+    /**
+     * Recompute the jack defaults and {@link Config#commandValues} from
+     * {@link Config#layers}.
+     *
+     * Everything is derived from `#layers`, and every known field is applied,
+     * so this is idempotent: re-reading a config file (which
+     * `addConfigToFile` and `deleteConfigKeys` both do) can't stack the user
+     * layer back on top of the project layer, and a field a layer stopped
+     * setting goes back to its definitional default.
+     */
+    #applyLayers() {
+        const { command, ...values } = mergeLayers([
+            this.#layers.user,
+            this.#layers.project,
+        ]);
+        this.commandValues = {};
+        for (const [c, opts] of Object.entries(command ?? {})) {
+            const cmd = getCommand(c);
+            if (cmd && opts && typeof opts === 'object') {
+                this.commandValues[cmd] = opts;
             }
         }
-        this.jack.setConfigValues(values, file);
+        const pairs = recordsToPairs(values);
+        const applied = {};
+        for (const [field, dflt] of Object.entries(defaultValues)) {
+            applied[field] = field in pairs ? pairs[field] : dflt;
+        }
+        this.jack.setConfigValues(applied);
+        this.#options = undefined;
     }
     /**
      * if the file exists, parse and load it. returns object if data was
      * loaded, or undefined if not.
      */
     async #maybeLoadConfigFile(whichConfig) {
-        return load('config', this.#validator, whichConfig);
+        const data = load('config', this.#validator, whichConfig);
+        if (data === undefined &&
+            this.#layers[whichConfig] !== undefined) {
+            // the file (or its `config` field) went away, so the validator never
+            // ran. drop the layer it left behind.
+            delete this.#layers[whichConfig];
+            this.#applyLayers();
+        }
+        return data;
     }
     /**
      * Deletes the specified config fields from the named file
@@ -493,3 +560,14 @@ export class Config {
     }
 }
 const isParsed = (c) => !!(c.values && c.positionals && c.command);
+/**
+ * Which `vlt.json` a command that persists settings should write to.
+ *
+ * `--config=user` and `--config=project` are explicit. Anything else means
+ * the caller's own default, since `--config` also takes `all` (its default,
+ * meaningful only for `vlt config` reads).
+ */
+export const configWriteTarget = (conf, fallback) => {
+    const which = conf.get('config');
+    return which === 'user' || which === 'project' ? which : fallback;
+};

package/dist/config/merge-layers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Merge the `config` objects found in the user and project `vlt.json`
+ * files into the single set of values that gets applied to the
+ * {@link https://npmjs.com/jackspeak | jackspeak} definition.
+ *
+ * Layers are supplied outermost first (user, then project), and follow the
+ * rules documented in `vlt help` and at
+ * <https://docs.vlt.sh/cli/configuring>:
+ *
+ * - Scalar fields come from the innermost layer that sets them.
+ * - Object (`key=value` record) fields are merged key by key.
+ * - A `null` value removes a field, or a single key within a record field.
+ * - Registry *selection* belongs to a single layer, see
+ *   {@link registrySelectionFields}.
+ *
+ * Note that this operates on the record form of a config object (the shape
+ * it has in `vlt.json`), not on jackspeak's `key=value` string lists, so
+ * record fields can be merged per key. Run values through
+ * `pairsToRecords` first.
+ * @module
+ */
+/** One config layer, in record (not `key=value` pair) form. */
+export type ConfigLayer = Record<string, unknown>;
+/**
+ * The fields that *select* which registry is used, as opposed to the
+ * catalogs of aliases that can be selected from.
+ */
+export declare const registrySelectors: readonly ["registry", "default-registry-alias"];
+/**
+ * When a layer sets any of these, that layer owns registry selection: the
+ * {@link registrySelectors} it does *not* set are removed from the merged
+ * result, rather than inherited from an outer layer.
+ *
+ * Without this, a `registry` in the user `vlt.json` would outrank a
+ * project's `registries.npm`, since the `registry` scalar beats any alias
+ * in `requireRegistry()`. The alias catalogs are still merged, so aliases
+ * configured at the user level stay addressable by name.
+ *
+ * Deliberately narrow: `scoped-registries` and `jsr-registries` are purely
+ * additive, so adding one of those in a project must not drop the user's
+ * default registry.
+ */
+export declare const registrySelectionFields: readonly ["registry", "registries", "default-registry-alias"];
+export declare const cloneLayer: <T>(data: T) => T;
+/**
+ * Merge config layers, outermost first. Layers are never mutated.
+ */
+export declare const mergeLayers: (layers: (ConfigLayer | undefined)[]) => ConfigLayer;

package/dist/config/merge-layers.js

@@ -0,0 +1,138 @@
+/**
+ * Merge the `config` objects found in the user and project `vlt.json`
+ * files into the single set of values that gets applied to the
+ * {@link https://npmjs.com/jackspeak | jackspeak} definition.
+ *
+ * Layers are supplied outermost first (user, then project), and follow the
+ * rules documented in `vlt help` and at
+ * <https://docs.vlt.sh/cli/configuring>:
+ *
+ * - Scalar fields come from the innermost layer that sets them.
+ * - Object (`key=value` record) fields are merged key by key.
+ * - A `null` value removes a field, or a single key within a record field.
+ * - Registry *selection* belongs to a single layer, see
+ *   {@link registrySelectionFields}.
+ *
+ * Note that this operates on the record form of a config object (the shape
+ * it has in `vlt.json`), not on jackspeak's `key=value` string lists, so
+ * record fields can be merged per key. Run values through
+ * `pairsToRecords` first.
+ * @module
+ */
+import { isRecordField } from "./definition.js";
+/**
+ * The fields that *select* which registry is used, as opposed to the
+ * catalogs of aliases that can be selected from.
+ */
+export const registrySelectors = [
+    'registry',
+    'default-registry-alias',
+];
+/**
+ * When a layer sets any of these, that layer owns registry selection: the
+ * {@link registrySelectors} it does *not* set are removed from the merged
+ * result, rather than inherited from an outer layer.
+ *
+ * Without this, a `registry` in the user `vlt.json` would outrank a
+ * project's `registries.npm`, since the `registry` scalar beats any alias
+ * in `requireRegistry()`. The alias catalogs are still merged, so aliases
+ * configured at the user level stay addressable by name.
+ *
+ * Deliberately narrow: `scoped-registries` and `jsr-registries` are purely
+ * additive, so adding one of those in a project must not drop the user's
+ * default registry.
+ */
+export const registrySelectionFields = [
+    'registry',
+    'registries',
+    'default-registry-alias',
+];
+const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/**
+ * Deep copy of a config layer, preserving `null` values.
+ *
+ * Layers are held onto for the life of the `Config` object, but the objects
+ * nested in them are shared with the `@vltpkg/vlt-json` cache, which
+ * `deleteConfigKeys` mutates in place. Copying keeps a stored layer an
+ * accurate snapshot of what was read.
+ */
+const cloneValue = (v) => Array.isArray(v) ? v.map(x => cloneValue(x))
+    : isObj(v) ?
+        Object.fromEntries(Object.entries(v).map(([k, x]) => [k, cloneValue(x)]))
+        : v;
+export const cloneLayer = (data) => cloneValue(data);
+/**
+ * Fold one record field's keys into the value from the outer layers.
+ * `null` removes a key. Returns `undefined` when nothing is left, so that
+ * the field falls back to its definitional default instead of applying an
+ * empty record.
+ */
+const mergeRecord = (base, add) => {
+    const result = isObj(base) ? { ...base } : {};
+    for (const [k, v] of Object.entries(add)) {
+        if (v === null)
+            delete result[k];
+        else
+            result[k] = v;
+    }
+    return Object.keys(result).length ? result : undefined;
+};
+/**
+ * Fold the `command` object in, merging each command's block with the same
+ * rules as the top level.
+ */
+const mergeCommands = (base, add) => {
+    const result = isObj(base) ? { ...base } : {};
+    for (const [cmd, opts] of Object.entries(add)) {
+        if (opts === null)
+            delete result[cmd];
+        else if (isObj(opts)) {
+            result[cmd] = mergeLayers([
+                isObj(result[cmd]) ? result[cmd] : undefined,
+                opts,
+            ]);
+        }
+    }
+    return Object.keys(result).length ? result : undefined;
+};
+/**
+ * Merge config layers, outermost first. Layers are never mutated.
+ */
+export const mergeLayers = (layers) => {
+    const result = {};
+    for (const layer of layers) {
+        if (!isObj(layer))
+            continue;
+        for (const [k, v] of Object.entries(layer)) {
+            if (k === 'command') {
+                const merged = isObj(v) ? mergeCommands(result.command, v) : undefined;
+                if (merged)
+                    result.command = merged;
+                else
+                    delete result.command;
+            }
+            else if (v === null) {
+                delete result[k];
+            }
+            else if (isRecordField(k) && isObj(v)) {
+                const merged = mergeRecord(result[k], v);
+                if (merged)
+                    result[k] = merged;
+                else
+                    delete result[k];
+            }
+            else {
+                result[k] = v;
+            }
+        }
+        // the innermost layer that configures a registry at all owns which
+        // registry is selected.
+        if (registrySelectionFields.some(f => f in layer)) {
+            for (const f of registrySelectors) {
+                if (!(f in layer))
+                    delete result[f];
+            }
+        }
+    }
+    return result;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/cli-sdk",
   "description": "The source for the vlt CLI",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/vltpkg/vltpkg.git",
@@ -14,30 +14,30 @@
   },
   "dependencies": {
     "@resvg/resvg-wasm": "^2.6.2",
-    "@vltpkg/config": "1.0.5",
-    "@vltpkg/dep-id": "1.0.5",
-    "@vltpkg/dot-prop": "1.0.5",
-    "@vltpkg/error-cause": "1.0.5",
-    "@vltpkg/git": "1.0.5",
-    "@vltpkg/graph": "1.0.5",
-    "@vltpkg/graph-run": "1.0.5",
-    "@vltpkg/init": "1.0.5",
-    "@vltpkg/output": "1.0.5",
-    "@vltpkg/package-info": "1.0.5",
-    "@vltpkg/package-json": "1.0.5",
-    "@vltpkg/promise-spawn": "1.0.5",
-    "@vltpkg/query": "1.0.5",
-    "@vltpkg/registry-client": "1.0.5",
-    "@vltpkg/rollback-remove": "1.0.5",
-    "@vltpkg/run": "1.0.5",
-    "@vltpkg/security-archive": "1.0.5",
-    "@vltpkg/spec": "1.0.5",
-    "@vltpkg/types": "1.0.5",
-    "@vltpkg/url-open": "1.0.5",
-    "@vltpkg/vlt-json": "1.0.5",
-    "@vltpkg/vlx": "1.0.5",
-    "@vltpkg/workspaces": "1.0.5",
-    "@vltpkg/xdg": "1.0.5",
+    "@vltpkg/config": "1.0.7",
+    "@vltpkg/dep-id": "1.0.7",
+    "@vltpkg/dot-prop": "1.0.7",
+    "@vltpkg/error-cause": "1.0.7",
+    "@vltpkg/git": "1.0.7",
+    "@vltpkg/graph": "1.0.7",
+    "@vltpkg/graph-run": "1.0.7",
+    "@vltpkg/init": "1.0.7",
+    "@vltpkg/output": "1.0.7",
+    "@vltpkg/package-info": "1.0.7",
+    "@vltpkg/package-json": "1.0.7",
+    "@vltpkg/promise-spawn": "1.0.7",
+    "@vltpkg/query": "1.0.7",
+    "@vltpkg/registry-client": "1.0.7",
+    "@vltpkg/rollback-remove": "1.0.7",
+    "@vltpkg/run": "1.0.7",
+    "@vltpkg/security-archive": "1.0.7",
+    "@vltpkg/spec": "1.0.7",
+    "@vltpkg/types": "1.0.7",
+    "@vltpkg/url-open": "1.0.7",
+    "@vltpkg/vlt-json": "1.0.7",
+    "@vltpkg/vlx": "1.0.7",
+    "@vltpkg/workspaces": "1.0.7",
+    "@vltpkg/xdg": "1.0.7",
     "ansi-to-pre": "^1.0.6",
     "beautiful-mermaid": "^1.1.3",
     "chalk": "^5.6.2",