@vltpkg/cli-sdk 1.0.6 → 1.0.8

package/dist/commands/bugs.js

@@ -1,10 +1,10 @@
 import { error } from '@vltpkg/error-cause';
 import { PackageInfoClient } from '@vltpkg/package-info';
 import { Spec } from '@vltpkg/spec';
-import { urlOpen } from '@vltpkg/url-open';
 import { actual } from '@vltpkg/graph';
 import { Query } from '@vltpkg/query';
 import { SecurityArchive } from '@vltpkg/security-archive';
+import { openUrl } from "../open-url.js";
 import { createHostContextsMap } from "../query-host-contexts.js";
 import { commandUsage } from "../config/usage.js";
 import hostedGitInfo from 'hosted-git-info';
@@ -138,7 +138,7 @@ export const command = async (conf) => {
             if (!result) {
                 throw error('Unexpected empty result');
             }
-            await urlOpen(result.url);
+            await openUrl(result.url);
             return result;
         }
         // Multiple results, return the list
@@ -158,6 +158,6 @@ export const command = async (conf) => {
     }
     /* c8 ignore stop */
     // Open the URL
-    await urlOpen(url);
+    await openUrl(url);
     return { url, name };
 };

package/dist/commands/docs.js

@@ -1,10 +1,10 @@
 import { error } from '@vltpkg/error-cause';
 import { PackageInfoClient } from '@vltpkg/package-info';
 import { Spec } from '@vltpkg/spec';
-import { urlOpen } from '@vltpkg/url-open';
 import { actual } from '@vltpkg/graph';
 import { Query } from '@vltpkg/query';
 import { SecurityArchive } from '@vltpkg/security-archive';
+import { openUrl } from "../open-url.js";
 import { createHostContextsMap } from "../query-host-contexts.js";
 import { commandUsage } from "../config/usage.js";
 import hostedGitInfo from 'hosted-git-info';
@@ -128,7 +128,7 @@ export const command = async (conf) => {
             if (!result) {
                 throw error('Unexpected empty result');
             }
-            await urlOpen(result.url);
+            await openUrl(result.url);
             return result;
         }
         // Multiple results, return the list
@@ -148,6 +148,6 @@ export const command = async (conf) => {
     }
     /* c8 ignore stop */
     // Open the URL
-    await urlOpen(url);
+    await openUrl(url);
     return { url, name };
 };

package/dist/commands/list.js

@@ -4,6 +4,7 @@ import { SecurityArchive } from '@vltpkg/security-archive';
 import { error } from '@vltpkg/error-cause';
 import { commandUsage } from "../config/usage.js";
 import { createHostContextsMap } from "../query-host-contexts.js";
+import { createGetAuthHeader } from "../query-auth.js";
 import { MermaidImageView } from "../mermaid-image-view.js";
 export const needsRegistry = true;
 export const usage = () => commandUsage({
@@ -104,6 +105,7 @@ export const command = async (conf) => {
     const projectQueryString = ':workspace, :project > *';
     const selectImporters = [];
     const hostContexts = await createHostContextsMap(conf);
+    const getAuthHeader = createGetAuthHeader(conf);
     const importers = new Set();
     const scopeIDs = [];
     // handle --scope option to add scope nodes as importers
@@ -123,6 +125,7 @@ export const command = async (conf) => {
             importers,
             securityArchive,
             hostContexts,
+            getAuthHeader,
         });
         const { nodes: resultNodes } = await scopeQuery.search(scopeQueryString, {
             signal: new AbortController().signal,
@@ -174,6 +177,7 @@ export const command = async (conf) => {
         importers: importers_,
         securityArchive,
         hostContexts,
+        getAuthHeader,
     });
     const query = queryString ||
         /* c8 ignore next */

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/query.js

@@ -6,6 +6,7 @@ import { createDiffFilesProvider } from "../query-diff-files.js";
 import { SecurityArchive } from '@vltpkg/security-archive';
 import { commandUsage } from "../config/usage.js";
 import { createHostContextsMap } from "../query-host-contexts.js";
+import { createGetAuthHeader } from "../query-auth.js";
 import { MermaidImageView } from "../mermaid-image-view.js";
 export const needsRegistry = true;
 export const usage = () => commandUsage({
@@ -130,6 +131,7 @@ export const command = async (conf) => {
     const queryString = targetQueryString || positionalQueryString;
     const hostContexts = await createHostContextsMap(conf);
     const diffFiles = createDiffFilesProvider(conf.options.projectRoot);
+    const getAuthHeader = createGetAuthHeader(conf);
     const importers = new Set();
     const scopeIDs = [];
     // Handle --scope option to add scope nodes as importers
@@ -150,6 +152,7 @@ export const command = async (conf) => {
             securityArchive,
             hostContexts,
             diffFiles,
+            getAuthHeader,
         });
         const { nodes: resultNodes } = await scopeQuery.search(scopeQueryString, {
             signal: new AbortController().signal,
@@ -214,6 +217,7 @@ export const command = async (conf) => {
         securityArchive,
         hostContexts,
         diffFiles,
+        getAuthHeader,
     });
     const query = queryString ||
         (graph ? defaultProjectQueryString : defaultLocalScopeQueryString);

package/dist/commands/repo.js

@@ -1,10 +1,10 @@
 import { error } from '@vltpkg/error-cause';
 import { PackageInfoClient } from '@vltpkg/package-info';
 import { Spec } from '@vltpkg/spec';
-import { urlOpen } from '@vltpkg/url-open';
 import { actual } from '@vltpkg/graph';
 import { Query } from '@vltpkg/query';
 import { SecurityArchive } from '@vltpkg/security-archive';
+import { openUrl } from "../open-url.js";
 import { createHostContextsMap } from "../query-host-contexts.js";
 import { commandUsage } from "../config/usage.js";
 import hostedGitInfo from 'hosted-git-info';
@@ -132,7 +132,7 @@ export const command = async (conf) => {
             if (!result) {
                 throw error('Unexpected empty result');
             }
-            await urlOpen(result.url);
+            await openUrl(result.url);
             return result;
         }
         // Multiple results, return the list
@@ -152,6 +152,6 @@ export const command = async (conf) => {
     }
     /* c8 ignore stop */
     // Open the URL
-    await urlOpen(url);
+    await openUrl(url);
     return { url, name };
 };

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/uninstall.js

@@ -18,6 +18,9 @@ export const usage = () => commandUsage({
             value: '<name>',
             description: 'Limit uninstall targets to workspace groups.',
         },
+        'lockfile-only': {
+            description: 'Only update lockfile and package.json files; skip node_modules operations.',
+        },
         'allow-scripts': {
             value: '<query>',
             description: 'Filter which packages are allowed to run lifecycle scripts using DSS query syntax.',
@@ -36,6 +39,10 @@ export const command = async (conf) => {
         String(conf.get('allow-scripts'))
         : ':not(*)';
     /* c8 ignore stop */
-    const { graph } = await uninstall({ ...conf.options, allowScripts }, remove);
+    const { graph } = await uninstall({
+        ...conf.options,
+        allowScripts,
+        lockfileOnly: conf.options['lockfile-only'],
+    }, remove);
     return { graph };
 };

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/dist/index.js

@@ -3,7 +3,7 @@ import { asRootError } from '@vltpkg/output/error';
 import { loadPackageJson } from 'package-json-from-dist';
 import { getSortedCliOptions, getSortedKeys, } from "./config/definition.js";
 import { Config } from "./config/index.js";
-import { outputCommand, stderr, stdout } from "./output.js";
+import { flushAndExit, outputCommand, stderr, stdout, } from "./output.js";
 import { indent } from "./print-err.js";
 import { loadCommand } from "./load-command.js";
 const { version } = loadPackageJson(import.meta.filename, process.env.__VLT_INTERNAL_CLI_PACKAGE_JSON);
@@ -35,7 +35,7 @@ const loadVlt = async (cwd, argv) => {
             stderr(indent(validOptions.join('\n'), 4));
         }
         stderr(indent(`Run 'vlt help' for more information about available options.`));
-        return process.exit(process.exitCode || 1);
+        return flushAndExit(process.exitCode || 1);
     }
 };
 const run = async () => {
@@ -64,7 +64,7 @@ const run = async () => {
         if (vlt.get('workspace-group')) {
             stderr(indent(`Workspace Group: ${format(vlt.get('workspace-group'))}`));
         }
-        return process.exit(process.exitCode || 1);
+        return flushAndExit(process.exitCode || 1);
     }
     if (vlt.command === 'registry') {
         const { dispatchRegistry } = await import("./commands/registry.js");

package/dist/mermaid-image-view.js

@@ -1,5 +1,5 @@
 import { mermaidOutput } from '@vltpkg/graph';
-import { urlOpen } from '@vltpkg/url-open';
+import { openUrl } from "./open-url.js";
 import { stderr } from "./output.js";
 import { ViewClass } from "./view.js";
 /**
@@ -24,13 +24,13 @@ export class MermaidImageView extends ViewClass {
             stderr(`Generating PNG image...`);
             const filePath = await renderMermaidToPng(mermaidText);
             stderr(`Image saved to: ${filePath}`);
-            await urlOpen(filePath);
+            await openUrl(filePath);
         }
         else {
             stderr(`Generating SVG image...`);
             const filePath = await renderMermaidToFile(mermaidText);
             stderr(`Image saved to: ${filePath}`);
-            await urlOpen(filePath);
+            await openUrl(filePath);
         }
     }
 }

package/dist/open-url.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Open a url in the system browser, without failing the command if the
+ * opener does. The opener command may exist but still be unable to launch
+ * anything, e.g: `xdg-open` on a headless server. The url was already
+ * printed, so the user can open it manually.
+ */
+export declare const openUrl: (url: string) => Promise<void>;

package/dist/open-url.js

@@ -0,0 +1,16 @@
+import { urlOpen } from '@vltpkg/url-open';
+import { stderr } from "./output.js";
+/**
+ * Open a url in the system browser, without failing the command if the
+ * opener does. The opener command may exist but still be unable to launch
+ * anything, e.g: `xdg-open` on a headless server. The url was already
+ * printed, so the user can open it manually.
+ */
+export const openUrl = async (url) => {
+    try {
+        await urlOpen(url);
+    }
+    catch {
+        stderr(`Could not open a browser. Please open ${url} manually.`);
+    }
+};

package/dist/output.d.ts

@@ -4,6 +4,26 @@ import type { Command } from './index.ts';
 import type { View, Views } from './view.ts';
 export declare const stdout: (...args: unknown[]) => void;
 export declare const stderr: (...args: unknown[]) => void;
+/** the part of a stdio stream that {@link flushStream} waits on */
+export type FlushableStream = {
+    writableLength: number;
+    write: (chunk: string, cb: () => void) => boolean;
+};
+/**
+ * Resolve once everything already handed to `stream` has reached the
+ * other end. A zero length write is enough: writes complete in order,
+ * so its callback cannot run ahead of the ones already queued.
+ */
+export declare const flushStream: (stream: FlushableStream) => Promise<void>;
+/**
+ * Exit, but only once stdout and stderr have drained.
+ *
+ * Writes to a pipe are async, and `process.exit()` throws away whatever
+ * is still queued for one. Piped output is exactly what CI gives us, so
+ * exiting right after printing crops the output at the 64k pipe buffer,
+ * and since the error is printed last, the error is what gets lost.
+ */
+export declare const flushAndExit: (code?: Parameters<typeof process.exit>[0]) => Promise<never>;
 type StyleTextFn = (format: Parameters<typeof utilStyleText>[0], s: string) => string;
 export declare let styleTextStdout: StyleTextFn;
 export declare let styleTextStderr: StyleTextFn;

package/dist/output.js

@@ -27,6 +27,31 @@ const supportsColor = (stream) => {
 export const stdout = (...args) => console.log(...args);
 // eslint-disable-next-line no-console
 export const stderr = (...args) => console.error(...args);
+/**
+ * Resolve once everything already handed to `stream` has reached the
+ * other end. A zero length write is enough: writes complete in order,
+ * so its callback cannot run ahead of the ones already queued.
+ */
+export const flushStream = (stream) => new Promise(res => {
+    if (!stream.writableLength)
+        return res();
+    stream.write('', () => res());
+});
+/**
+ * Exit, but only once stdout and stderr have drained.
+ *
+ * Writes to a pipe are async, and `process.exit()` throws away whatever
+ * is still queued for one. Piped output is exactly what CI gives us, so
+ * exiting right after printing crops the output at the 64k pipe buffer,
+ * and since the error is printed last, the error is what gets lost.
+ */
+export const flushAndExit = async (code) => {
+    await Promise.all([
+        flushStream(process.stdout),
+        flushStream(process.stderr),
+    ]);
+    return process.exit(code);
+};
 /* c8 ignore start */
 const styleText = (f, s) => utilStyleText(f, s, { validateStream: false });
 /* c8 ignore stop */
@@ -202,6 +227,6 @@ export const outputCommand = async (cliCommand, conf, { start, vltVersion } = {
             ...formatOptions,
             colors: stderrColor,
         });
-        process.exit(process.exitCode);
+        await flushAndExit(process.exitCode);
     }
 };

package/dist/parse-add-remove-args.js

@@ -1,4 +1,4 @@
-import { asDependency } from '@vltpkg/graph';
+import { addKey, asDependency } from '@vltpkg/graph';
 import { joinDepIDTuple, splitDepID } from '@vltpkg/dep-id';
 import { Spec } from '@vltpkg/spec';
 import { isAbsolute, relative, resolve } from 'node:path';
@@ -85,10 +85,6 @@ export const parseAddArgs = (config, scurry, monorepo) => {
     const type = getType(config.values);
     const importers = getWorkspaceImporters(config.values, monorepo);
     const specOptions = config.options;
-    // nameless spec definitions will need to use their full
-    // stringified spec result instead of their name in order
-    // to have an unique key name in the resulting Map
-    const getName = (s) => s.name === '(unknown)' ? s.spec : s.name;
     // parses each positional argument into a Spec and
     // adds it to the new dependencies Map
     const parsedItems = [];
@@ -110,7 +106,7 @@ export const parseAddArgs = (config, scurry, monorepo) => {
             const importerDeps = new Map();
             for (const { spec, type: depType } of parsedItems) {
                 const rebased = rebaseFileSpec(spec, importerPath, scurryCwd, specOptions, monorepo);
-                importerDeps.set(getName(rebased), asDependency({ spec: rebased, type: depType }));
+                importerDeps.set(addKey(rebased), asDependency({ spec: rebased, type: depType }));
             }
             add.set(importer, importerDeps);
         }
@@ -118,7 +114,7 @@ export const parseAddArgs = (config, scurry, monorepo) => {
     else {
         const newDependencies = new Map();
         for (const { spec, type: depType } of parsedItems) {
-            newDependencies.set(getName(spec), asDependency({ spec, type: depType }));
+            newDependencies.set(addKey(spec), asDependency({ spec, type: depType }));
         }
         for (const importer of importers) {
             add.set(importer, newDependencies);

package/dist/query-auth.d.ts

@@ -0,0 +1,8 @@
+import type { GetAuthHeader } from '@vltpkg/query';
+import type { LoadedConfig } from './config/index.ts';
+/**
+ * Returns a {@link GetAuthHeader} implementation that looks up
+ * authorization tokens from the local keychain / env, used by
+ * network-reliant query selectors, e.g: `:outdated()`.
+ */
+export declare const createGetAuthHeader: (conf: LoadedConfig) => GetAuthHeader;

package/dist/query-auth.js

@@ -0,0 +1,7 @@
+import { getTokenByURL } from '@vltpkg/registry-client';
+/**
+ * Returns a {@link GetAuthHeader} implementation that looks up
+ * authorization tokens from the local keychain / env, used by
+ * network-reliant query selectors, e.g: `:outdated()`.
+ */
+export const createGetAuthHeader = (conf) => async (url) => getTokenByURL(url, conf.options.identity);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vltpkg/cli-sdk",
   "description": "The source for the vlt CLI",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "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.6",
-    "@vltpkg/dep-id": "1.0.6",
-    "@vltpkg/dot-prop": "1.0.6",
-    "@vltpkg/error-cause": "1.0.6",
-    "@vltpkg/git": "1.0.6",
-    "@vltpkg/graph": "1.0.6",
-    "@vltpkg/graph-run": "1.0.6",
-    "@vltpkg/init": "1.0.6",
-    "@vltpkg/output": "1.0.6",
-    "@vltpkg/package-info": "1.0.6",
-    "@vltpkg/package-json": "1.0.6",
-    "@vltpkg/promise-spawn": "1.0.6",
-    "@vltpkg/query": "1.0.6",
-    "@vltpkg/registry-client": "1.0.6",
-    "@vltpkg/rollback-remove": "1.0.6",
-    "@vltpkg/run": "1.0.6",
-    "@vltpkg/security-archive": "1.0.6",
-    "@vltpkg/spec": "1.0.6",
-    "@vltpkg/types": "1.0.6",
-    "@vltpkg/url-open": "1.0.6",
-    "@vltpkg/vlt-json": "1.0.6",
-    "@vltpkg/vlx": "1.0.6",
-    "@vltpkg/workspaces": "1.0.6",
-    "@vltpkg/xdg": "1.0.6",
+    "@vltpkg/config": "1.0.8",
+    "@vltpkg/dep-id": "1.0.8",
+    "@vltpkg/dot-prop": "1.0.8",
+    "@vltpkg/error-cause": "1.0.8",
+    "@vltpkg/git": "1.0.8",
+    "@vltpkg/graph": "1.0.8",
+    "@vltpkg/graph-run": "1.0.8",
+    "@vltpkg/init": "1.0.8",
+    "@vltpkg/output": "1.0.8",
+    "@vltpkg/package-info": "1.0.8",
+    "@vltpkg/package-json": "1.0.8",
+    "@vltpkg/promise-spawn": "1.0.8",
+    "@vltpkg/query": "1.0.8",
+    "@vltpkg/registry-client": "1.0.8",
+    "@vltpkg/rollback-remove": "1.0.8",
+    "@vltpkg/run": "1.0.8",
+    "@vltpkg/security-archive": "1.0.8",
+    "@vltpkg/spec": "1.0.8",
+    "@vltpkg/types": "1.0.8",
+    "@vltpkg/url-open": "1.0.8",
+    "@vltpkg/vlt-json": "1.0.8",
+    "@vltpkg/vlx": "1.0.8",
+    "@vltpkg/workspaces": "1.0.8",
+    "@vltpkg/xdg": "1.0.8",
     "ansi-to-pre": "^1.0.6",
     "beautiful-mermaid": "^1.1.3",
     "chalk": "^5.6.2",