@vltpkg/cli-sdk 1.3.8 → 1.4.0

package/dist/commands/cache.d.ts

@@ -56,8 +56,8 @@ declare const usageDef: {
             readonly description: "Check global store entries against their cached\n                    tarballs (file list, contents, exec bits) and remove\n                    any that differ or have no cached tarball, e.g. after\n                    a file in `node_modules` was edited in place.";
         };
         readonly 'prune-store': {
-            readonly usage: "";
-            readonly description: "Remove global store entries that no `node_modules`\n                    folder links to. Entries ever copied from (install\n                    scripts, `store-linker=copy`, a cache on another\n                    drive) stay: copies do not show use.";
+            readonly usage: "[<date>]";
+            readonly description: "Remove global store entries that no `node_modules`\n                    folder links to. Copies do not show use: an entry\n                    copied or cloned from (install scripts,\n                    `store-linker=copy`, macOS, a cache on another\n                    drive) stays if that last happened after\n                    `<date>`, or in the last 30 days\n                    without one.";
         };
     };
     readonly examples: {

package/dist/commands/cache.js

@@ -1,7 +1,7 @@
 import { error } from '@vltpkg/error-cause';
 import { CacheEntry, assertOk } from '@vltpkg/registry-client';
 import { Spec } from '@vltpkg/spec';
-import { removeStoreEntry, storeEntryCopied, storeEntryLinked, storeEntryNames, storeEntryTime, verifyStoreEntry, } from '@vltpkg/tar/store-entry';
+import { removeStoreEntry, storeEntryCopied, storeEntryLastCopied, storeEntryLinked, storeEntryNames, storeEntryTime, verifyStoreEntry, } from '@vltpkg/tar/store-entry';
 import { readStoreIndex } from '@vltpkg/tar/store-index';
 import { integrityHex } from '@vltpkg/types';
 import { readFileSync } from 'node:fs';
@@ -24,6 +24,8 @@ export class CacheView extends ViewClass {
 export const views = {
     human: CacheView,
 };
+/** `prune-store`: days a copied entry stays, by default */
+const pruneDays = 30;
 const usageDef = {
     command: 'cache',
     usage: '<command> [flags]',
@@ -76,11 +78,14 @@ const usageDef = {
                     a file in \`node_modules\` was edited in place.`,
         },
         'prune-store': {
-            usage: '',
+            usage: '[<date>]',
             description: `Remove global store entries that no \`node_modules\`
-                    folder links to. Entries ever copied from (install
-                    scripts, \`store-linker=copy\`, a cache on another
-                    drive) stay: copies do not show use.`,
+                    folder links to. Copies do not show use: an entry
+                    copied or cloned from (install scripts,
+                    \`store-linker=copy\`, macOS, a cache on another
+                    drive) stays if that last happened after
+                    \`<date>\`, or in the last ${pruneDays} days
+                    without one.`,
         },
     },
     examples: {
@@ -335,14 +340,24 @@ const verify = async (conf, specs, view) => {
         ...(!all && { missing }),
     };
 };
-const pruneStore = async (conf, _, view) => {
+const pruneStore = async (conf, args, view) => {
+    const since = args.length ?
+        new Date(args.join(' ')).getTime()
+        : Date.now() - pruneDays * 24 * 60 * 60 * 1000;
+    if (Number.isNaN(since)) {
+        throw error('Invalid date', {
+            code: 'EUSAGE',
+            found: args.join(' '),
+        });
+    }
     const { storeRoot } = conf.options;
     const names = storeEntryNames(storeRoot);
     const removed = {};
     for (const hex of names) {
         const entry = resolve(storeRoot, hex);
         const index = readStoreIndex(entry);
-        if (storeEntryCopied(entry, index) ||
+        if ((storeEntryCopied(entry, index) &&
+            storeEntryLastCopied(entry) >= since) ||
             storeEntryLinked(entry, index)) {
             continue;
         }

package/dist/commands/init.js

@@ -60,13 +60,11 @@ export const command = async (conf) => {
         const { config: parsedWSConfig, source } = resolveWSConfig(conf.options.projectRoot, conf.options.packageJson);
         // what gets written back to vlt.json. The raw vlt.json value is
         // reused as-is so its existing shape is preserved. When the
-        // definitions live in package.json instead, seed vlt.json with them
-        // first -- otherwise adding a `workspaces` field here would shadow
-        // every workspace package.json already declares.
+        // definitions live in package.json or pnpm-workspace.yaml instead,
+        // seed vlt.json with them first -- otherwise adding a `workspaces`
+        // field here would shadow every workspace already declared there.
         const workspacesConfig = load('workspaces', assertWSConfig) ??
-            (source === 'package.json' ?
-                Object.values(parsedWSConfig).flat()
-                : undefined);
+            (source ? Object.values(parsedWSConfig).flat() : undefined);
         const results = [];
         const addToConfig = [];
         // create a new package.json file for every workspace

package/dist/commands/install.js

@@ -3,6 +3,7 @@ import { install } from '@vltpkg/graph';
 import { parseAddArgs } from "../parse-add-remove-args.js";
 import { planSpecConfigPersist } from "../persist-spec-config.js";
 import { asUnknownSpecPrefix } from "../require-registry.js";
+import { addTypesDeps } from "../save-types.js";
 import { trackInstall } from "../telemetry.js";
 import { lazyView } from "../view.js";
 export const needsRegistry = true;
@@ -32,6 +33,9 @@ export const usage = () => commandUsage({
         'save-prod': {
             description: 'Save installed packages to package.json as dependencies.',
         },
+        'save-types': {
+            description: 'Also save matching @types/* packages to devDependencies for added packages that ship no types.',
+        },
         'save-config': {
             description: 'Save registry and git host options given on the command line or via env (e.g. `--registries name=url`) to the project vlt.json, or the user vlt.json with --config=user.',
         },
@@ -130,6 +134,8 @@ export const command = async (conf) => {
     const scurry = conf.options.scurry;
     const { add } = parseAddArgs(conf, scurry, monorepo);
     const persist = planSpecConfigPersist(conf);
+    if (conf.values['save-types'])
+        await addTypesDeps(conf, add);
     const frozenLockfile = conf.options['frozen-lockfile'];
     const expectLockfile = conf.options['expect-lockfile'];
     const lockfileOnly = conf.options['lockfile-only'];

package/dist/commands/pack.js

@@ -9,6 +9,7 @@ import { actual } from '@vltpkg/graph';
 import { Query } from '@vltpkg/query';
 import { error } from '@vltpkg/error-cause';
 import { createHostContextsMap } from "../query-host-contexts.js";
+import { sortScopeLocations } from "../sort-scope-locations.js";
 import { minimatch } from 'minimatch';
 export const needsRegistry = true;
 export const usage = () => commandUsage({
@@ -97,7 +98,7 @@ const scopeLocations = async (queryString, conf) => {
         }));
         locations.push(resolve(projectRoot, location));
     }
-    return locations;
+    return sortScopeLocations(locations, options.monorepo);
 };
 export const command = async (conf) => {
     const { options, projectRoot } = conf;

package/dist/commands/pkg.js

@@ -9,6 +9,7 @@ import { SecurityArchive } from '@vltpkg/security-archive';
 import { views as initViews } from "./init.js";
 import { commandUsage } from "../config/usage.js";
 import { createHostContextsMap } from "../query-host-contexts.js";
+import { sortScopeLocations } from "../sort-scope-locations.js";
 import { minimatch } from 'minimatch';
 export const views = {
     human: (results, _, config) => {
@@ -129,15 +130,17 @@ export const command = async (conf) => {
         const { nodes: resultNodes } = await query.search(queryString, {
             signal: new AbortController().signal,
         });
+        const found = [];
         for (const node of resultNodes) {
             const location = node.location;
             assert(location, error(`node ${node.id} has no location`, {
                 found: node,
             }));
             if (node.id !== VIRTUAL_ROOT_ID) {
-                locations.push(resolve(node.projectRoot, location));
+                found.push(resolve(node.projectRoot, location));
             }
         }
+        locations.push(...sortScopeLocations(found, options.monorepo));
     }
     else if (paths?.length || groups?.length || recursive) {
         for (const workspace of options.monorepo ?? []) {

package/dist/commands/publish.js

@@ -10,6 +10,7 @@ import prettyBytes from 'pretty-bytes';
 import { actual } from '@vltpkg/graph';
 import { Query } from '@vltpkg/query';
 import { createHostContextsMap } from "../query-host-contexts.js";
+import { sortScopeLocations } from "../sort-scope-locations.js";
 import { minimatch } from 'minimatch';
 import { resolveRegistry } from "../require-registry.js";
 import { stderr } from "../output.js";
@@ -114,13 +115,15 @@ export const command = async (conf) => {
         const { nodes } = await query.search(queryString, {
             signal: new AbortController().signal,
         });
+        const found = [];
         for (const node of nodes) {
             const { location } = node.toJSON();
             assert(location, error(`node ${node.id} has no location`, {
                 found: node,
             }));
-            locations.push(resolve(projectRoot, location));
+            found.push(resolve(projectRoot, location));
         }
+        locations.push(...sortScopeLocations(found, options.monorepo));
     }
     else if (paths?.length || groups?.length || recursive) {
         for (const workspace of options.monorepo ?? []) {

package/dist/commands/version.js

@@ -8,6 +8,7 @@ import assert from 'node:assert';
 import { actual } from '@vltpkg/graph';
 import { Query } from '@vltpkg/query';
 import { createHostContextsMap } from "../query-host-contexts.js";
+import { sortScopeLocations } from "../sort-scope-locations.js";
 import { minimatch } from 'minimatch';
 /**
  * `--no-git-tag-version` skips the whole git dance, matching npm.
@@ -223,13 +224,15 @@ export const command = async (conf) => {
         const { nodes } = await query.search(queryString, {
             signal: new AbortController().signal,
         });
+        const found = [];
         for (const node of nodes) {
             const location = node.location;
             assert(location, error(`node ${node.id} has no location`, {
                 found: node,
             }));
-            locations.push(resolve(node.projectRoot, location));
+            found.push(resolve(node.projectRoot, location));
         }
+        locations.push(...sortScopeLocations(found, options.monorepo));
     }
     else if (paths?.length || groups?.length || recursive) {
         for (const workspace of options.monorepo ?? []) {

package/dist/config/definition.d.ts

@@ -75,7 +75,7 @@ export declare const recordFields: readonly ["git-hosts", "registries", "git-hos
 export type RecordField = (typeof recordFields)[number];
 export declare const isRecordField: (s: string) => s is RecordField;
 /** Valid `store-linker` values. */
-export declare const storeLinkers: readonly ["auto", "hardlink", "copy", "unpack"];
+export declare const storeLinkers: readonly ["auto", "hardlink", "clone", "copy", "unpack"];
 export declare const definition: import("jackspeak").Jack<{
     color: {
         short: string;
@@ -139,7 +139,7 @@ export declare const definition: import("jackspeak").Jack<{
     'store-linker': {
         hint: string;
         description: string;
-        validOptions: readonly ["auto", "hardlink", "copy", "unpack"];
+        validOptions: readonly ["auto", "hardlink", "clone", "copy", "unpack"];
         default: string;
     };
     tag: {
@@ -365,6 +365,9 @@ export declare const definition: import("jackspeak").Jack<{
         short: string;
         description: string;
     };
+    'save-types': {
+        description: string;
+    };
     'save-config': {
         description: string;
     };
@@ -374,6 +377,7 @@ export declare const definition: import("jackspeak").Jack<{
     'save-optional': import("jackspeak").ConfigOption<"boolean", false, undefined>;
     'save-peer': import("jackspeak").ConfigOption<"boolean", false, undefined>;
     'save-prod': import("jackspeak").ConfigOption<"boolean", false, undefined>;
+    'save-types': import("jackspeak").ConfigOption<"boolean", false, undefined>;
     'save-config': import("jackspeak").ConfigOption<"boolean", false, undefined>;
 } & {
     'save-prefix': {

package/dist/config/definition.js

@@ -114,6 +114,7 @@ export const isRecordField = (s) => recordFields.includes(s);
 export const storeLinkers = [
     'auto',
     'hardlink',
+    'clone',
     'copy',
     'unpack',
 ];
@@ -226,8 +227,11 @@ export const definition = j
 
                     There is **no** built-in \`npm\` registry URL; the \`npm\`
                     alias must be configured (e.g. via \`vlt setup\`) before it
-                    can be used. The \`gh\` and \`jsr\` aliases have built-in
-                    defaults that can be overridden here.
+                    can be used. The \`gh\` alias has a built-in default
+                    that can be overridden here. A name used by
+                    \`--jsr-registries\` or \`--git-hosts\` (e.g. \`jsr\`,
+                    \`github\`), or a built-in protocol (e.g. \`file\`), is
+                    an error.
 
                     Aliases given on the command line or in
                     \`VLT_REGISTRIES\` (newline-delimited) merge with the
@@ -317,28 +321,35 @@ export const definition = j
         default: cacheDir,
     },
     'store-linker': {
-        hint: 'auto | hardlink | copy | unpack',
+        hint: 'auto | hardlink | clone | copy | unpack',
         description: `How packages are placed in \`node_modules\`. Every
                     linker but \`unpack\` fills a global store under
                     \`cache\` in the background, then places packages
                     from it.
 
                     - auto: Default. On Linux, hardlink from the global
-                      store, copying any file that cannot be linked.
-                      Elsewhere, same as \`unpack\`: a hardlink is the
-                      slowest way to place a file on APFS, so macOS and
-                      Windows unpack by default.
+                      store, copying any file that cannot be linked. On
+                      macOS, clone from it, on a Node with \`node:ffi\`
+                      (26.1 and later, and \`--allow-ffi\` under
+                      \`--permission\`); a hardlink is the slowest way
+                      to place a file on APFS, so macOS without it, and
+                      Windows, unpack by default.
                     - hardlink: Hardlink from the global store on every
                       platform.
+                    - clone: Clone each package directory from the
+                      global store copy-on-write (\`clonefile\`, macOS
+                      on APFS). Files share storage with the store
+                      until edited, so editing in place is safe.
+                      Unpacks where cloning fails.
                     - copy: Copy from the global store. Use this when
                       editing files in \`node_modules\` in place, since
                       a hardlink shares its content with every project.
                     - unpack: Unpack each package tarball, skipping the
                       global store.
 
-                    A package is copied right before its install
-                    scripts run, so they don't change its files in the
-                    store.
+                    A hardlinked package is copied right before its
+                    install scripts run, so they don't change its files
+                    in the store; a cloned one needs no copy.
                     An invalid \`VLT_STORE_LINKER\` warns and uses
                     \`unpack\`.`,
         validOptions: storeLinkers,
@@ -702,6 +713,11 @@ export const definition = j
                     devDependencies or optionalDependencies, but you want to
                     move it to be a non-optional production dependency.`,
     },
+    'save-types': {
+        description: `Also save the matching \`@types/*\` package as a
+                    devDependency for each added registry package that
+                    ships no TypeScript types of its own.`,
+    },
     'save-config': {
         description: `Save the registry and git host options given on the
                     command line or via \`VLT_*\` env (\`--registry\`,

package/dist/config/index.d.ts

@@ -85,6 +85,8 @@ export type ConfigOptions = ConfigOptionsNoExtras & Pick<SpecOptions, 'catalog'
     storeRoot: string;
     monorepo?: Monorepo;
     packageInfo: PackageInfoClient;
+    /** aborted when the command fails */
+    signal: AbortSignal;
 };
 /**
  * The base config definition set as a type
@@ -125,6 +127,8 @@ export declare class Config {
      * to recalculate the options.
      */
     resetOptions(projectRoot?: string): void;
+    /** Abort requests still in flight */
+    abort(): void;
     /**
      * positional arguments to the vlt process
      */

package/dist/config/index.js

@@ -24,6 +24,7 @@ import { error } from '@vltpkg/error-cause';
 import { PackageInfoClient } from '@vltpkg/package-info';
 import { PackageJson } from '@vltpkg/package-json';
 import { storeRoot } from '@vltpkg/registry-client/store-root';
+import { cloneAvailable } from '@vltpkg/tar/clonefile';
 import { resetCaches } from '@vltpkg/dep-id';
 import { getOptions } from '@vltpkg/spec';
 import { assertRecordStringString, assertRecordStringT, isObject, isRecordStringString, } from '@vltpkg/types';
@@ -35,6 +36,7 @@ import { PathScurry } from 'path-scurry';
 import { commands, definition, defaultValues, getCommand, isRecordField, recordFields, storeLinkers, } from "./definition.js";
 import { merge } from "./merge.js";
 import { cloneLayer, mergeLayers } from "./merge-layers.js";
+import { assertSpecAliases } from "./spec-aliases.js";
 export { commands, definition, isRecordField, recordFields, };
 export const kCustomInspect = Symbol.for('nodejs.util.inspect.custom');
 // turn a set of pairs into a Record object.
@@ -172,6 +174,7 @@ export class Config {
         const asRecords = pairsToRecords(this.parse().values);
         const extras = {
             projectRoot: this.projectRoot,
+            signal: this.#abort.signal,
             storeRoot: storeRoot(asRecords.cache),
             scurry,
             packageJson,
@@ -197,7 +200,8 @@ export class Config {
                 return Object.fromEntries(Object.entries(options).filter(([k]) => k !== 'monorepo' &&
                     k !== 'scurry' &&
                     k !== 'packageJson' &&
-                    k !== 'packageInfo'));
+                    k !== 'packageInfo' &&
+                    k !== 'signal'));
             },
         });
         return this.#options;
@@ -213,6 +217,11 @@ export class Config {
     }
     // memoized options() getter value
     #options;
+    #abort = new AbortController();
+    /** Abort requests still in flight */
+    abort() {
+        this.#abort.abort();
+    }
     /**
      * positional arguments to the vlt process
      */
@@ -277,13 +286,16 @@ export class Config {
         // ok, applied cmd-specific defaults, do rest of the parse
         this.jack.applyDefaults(p);
         // `auto` only hardlinks from the global store on linux: on APFS a
-        // hardlink is the slowest way to place a file, so darwin and win32
-        // unpack by default. the env layer is rewritten too, so `explicit`
-        // records the resolved value.
+        // hardlink is the slowest way to place a file, so darwin clones
+        // instead, when its node can load `node:ffi` to call clonefile(2)
+        // with, and win32 (and darwin without it) unpack by default. the
+        // env layer is rewritten too, so `explicit` records the resolved
+        // value.
         if (p.values['store-linker'] === 'auto' &&
             process.platform !== 'linux') {
-            p.values['store-linker'] = 'unpack';
-            envValues['store-linker'] = 'unpack';
+            const linker = cloneAvailable() ? 'clone' : 'unpack';
+            p.values['store-linker'] = linker;
+            envValues['store-linker'] = linker;
         }
         // what was set on the cli or env for this run. record fields hold
         // only those pairs, env then cli, so later ones win per key.
@@ -317,6 +329,10 @@ export class Config {
             const base = (k in cmdPairs ? cmdPairs[k] : fileValues[k]) ?? [];
             values[k] = dedupePairs([...base, ...pairs]);
         }
+        // skipped for `vlt config`, so a bad alias can be removed
+        if (cmdOrFallback !== 'config') {
+            assertSpecAliases(pairsToRecords(p.values));
+        }
         this.jack.writeEnv(p);
         process.env[kParentEnv] = JSON.stringify({
             explicit,

package/dist/config/spec-aliases.d.ts

@@ -0,0 +1,22 @@
+declare const builtins: {
+    registries: {
+        gh: string;
+    };
+    'jsr-registries': {
+        jsr: string;
+    };
+    'git-hosts': {
+        github: string;
+        bitbucket: string;
+        gitlab: string;
+        gist: string;
+    };
+};
+type SpecAliasField = keyof typeof builtins;
+/**
+ * Throw `ECONFIG` if a spec prefix alias is in more than one of
+ * `registries` / `jsr-registries` / `git-hosts` (built-ins included),
+ * or is a built-in protocol. Overriding a built-in in its own field is ok.
+ */
+export declare const assertSpecAliases: (values: Partial<Record<SpecAliasField, Record<string, string>>>) => void;
+export {};

package/dist/config/spec-aliases.js

@@ -0,0 +1,47 @@
+import { error } from '@vltpkg/error-cause';
+import { builtinProtocols, defaultGitHosts, defaultJsrRegistries, defaultRegistries, } from '@vltpkg/spec';
+const builtins = {
+    registries: defaultRegistries,
+    'jsr-registries': defaultJsrRegistries,
+    'git-hosts': defaultGitHosts,
+};
+const fields = Object.keys(builtins);
+/**
+ * Throw `ECONFIG` if a spec prefix alias is in more than one of
+ * `registries` / `jsr-registries` / `git-hosts` (built-ins included),
+ * or is a built-in protocol. Overriding a built-in in its own field is ok.
+ */
+export const assertSpecAliases = (values) => {
+    const owners = new Map();
+    for (const field of fields) {
+        for (const key of Object.keys(builtins[field])) {
+            if (values[field]?.[key] === undefined) {
+                owners.set(key, { field, builtin: true });
+            }
+        }
+    }
+    for (const field of fields) {
+        for (const key of Object.keys(values[field] ?? {})) {
+            const name = `${field}.${key}`;
+            if (builtinProtocols.has(key)) {
+                throw error(`${name} shadows the built-in \`${key}:\` protocol`, {
+                    code: 'ECONFIG',
+                    name,
+                    found: key,
+                    wanted: 'a name that is not a built-in protocol',
+                });
+            }
+            const owner = owners.get(key);
+            if (owner) {
+                const where = `${owner.field}.${key}${owner.builtin ? ' (built-in)' : ''}`;
+                throw error(`\`${key}:\` spec prefix defined in both ${where} and ${name}`, {
+                    code: 'ECONFIG',
+                    name,
+                    found: key,
+                    wanted: `a ${field} name not used by ${owner.field}`,
+                });
+            }
+            owners.set(key, { field, builtin: false });
+        }
+    }
+};

package/dist/exec-command.js

@@ -14,6 +14,7 @@ import { stderr, stdout, styleTextStdout } from "./output.js";
 import assert from 'node:assert';
 import { resolve } from 'node:path';
 import { createHostContextsMap } from "./query-host-contexts.js";
+import { sortScopeLocations } from "./sort-scope-locations.js";
 const isScriptSet = (o) => {
     if (!o || typeof o !== 'object')
         return false;
@@ -98,11 +99,13 @@ export class ExecCommand {
             this.#defaultIgnoreMissing = true;
             const mainManifest = conf.options.packageJson.maybeRead(this.projectRoot);
             let graph;
+            let monorepo;
             if (mainManifest) {
+                monorepo = Monorepo.load(this.projectRoot);
                 graph = actual.load({
                     ...conf.options,
                     mainManifest,
-                    monorepo: Monorepo.load(this.projectRoot),
+                    monorepo,
                     loadManifests: false,
                 });
             }
@@ -120,14 +123,15 @@ export class ExecCommand {
             const { nodes } = await query.search(queryString, {
                 signal: new AbortController().signal,
             });
-            this.#nodes = [];
+            const locations = [];
             for (const node of nodes) {
                 const { location } = node.toJSON();
                 assert(location, error(`node ${node.id} has no location`, {
                     found: node,
                 }));
-                this.#nodes.push(location);
+                locations.push(location);
             }
+            this.#nodes = sortScopeLocations(locations, monorepo);
         }
         else if (paths?.length || groups?.length || recursive) {
             this.#defaultIgnoreMissing = true;
@@ -163,8 +167,9 @@ export class ExecCommand {
         }
         // run across workspaces
         let failed = false;
-        const runInDir = async (cwd, label) => {
-            const result = await this.bg(this.bgArg(cwd)).catch((er) => {
+        const runInDir = async (cwd, label, signal) => {
+            const arg = { ...this.bgArg(cwd), signal };
+            const result = await this.bg(arg).catch((er) => {
                 if (isErrorWithCause(er) && isRunResult(er.cause)) {
                     this.printResult(label, er.cause);
                 }
@@ -189,7 +194,8 @@ export class ExecCommand {
             }
         }
         else if (this.#monorepo) {
-            const wsResultMap = await this.#monorepo.run(ws => runInDir(ws.fullpath, ws.path));
+            // aborted on the first failure, killing the rest
+            const wsResultMap = await this.#monorepo.run((ws, signal) => runInDir(ws.fullpath, ws.path, signal));
             for (const [ws, result] of wsResultMap) {
                 if (result)
                     resultMap.set(ws.path, result);

package/dist/index.js

@@ -1,5 +1,5 @@
 import { format } from 'node:util';
-import { asRootError } from '@vltpkg/output/error';
+import { asRootError, findRootError } from '@vltpkg/output/error';
 import { loadPackageJson } from 'package-json-from-dist';
 import { getSortedCliOptions, getSortedKeys, } from "./config/definition.js";
 import { Config } from "./config/index.js";
@@ -12,13 +12,14 @@ const loadVlt = async (cwd, argv) => {
         return await Config.load(cwd, argv);
     }
     catch (e) {
-        const err = asRootError(e, { code: 'JACKSPEAK' });
+        const code = findRootError(e, { code: 'ECONFIG' }) ? 'ECONFIG' : 'JACKSPEAK';
+        const err = asRootError(e, { code });
         const { found, path, wanted, name } = err.cause;
         const isConfigFile = typeof path === 'string';
-        const msg = isConfigFile ?
-            `Problem in Config File ${path}`
-            : 'Invalid Option Flag';
-        const validOptions = wanted ? undefined
+        const msg = isConfigFile ? `Problem in Config File ${path}`
+            : code === 'ECONFIG' ? 'Config Error'
+                : 'Invalid Option Flag';
+        const validOptions = wanted || code === 'ECONFIG' ? undefined
             : isConfigFile ? getSortedKeys()
                 : getSortedCliOptions();
         stderr(msg);
@@ -34,7 +35,10 @@ const loadVlt = async (cwd, argv) => {
             stderr(indent('Valid Options:'));
             stderr(indent(validOptions.join('\n'), 4));
         }
-        stderr(indent(`Run 'vlt help' for more information about available options.`));
+        // `vlt help` would fail the same way
+        if (code !== 'ECONFIG') {
+            stderr(indent(`Run 'vlt help' for more information about available options.`));
+        }
         return flushAndExit(process.exitCode || 1);
     }
 };
@@ -57,7 +61,7 @@ const run = async () => {
     if (vlt.command !== 'init' &&
         (vlt.get('workspace') || vlt.get('workspace-group')) &&
         ![...(monorepo?.values() ?? [])].length) {
-        stderr(`Error: No matching workspaces found. Make sure the vlt.json config, or the "workspaces" field of the root package.json, contains the correct workspaces.`);
+        stderr(`Error: No matching workspaces found. Make sure the vlt.json config, the "workspaces" field of the root package.json, or the "packages" list of pnpm-workspace.yaml contains the correct workspaces.`);
         if (vlt.get('workspace')) {
             stderr(indent(`Workspace: ${format(vlt.get('workspace'))}`));
         }

package/dist/output.js

@@ -227,6 +227,7 @@ export const outputCommand = async (cliCommand, conf, { start, vltVersion } = {
             ...formatOptions,
             colors: stderrColor,
         });
-        await flushAndExit(process.exitCode);
+        // stop pending requests, so the process can exit on its own
+        conf.abort();
     }
 };

package/dist/save-types.d.ts

@@ -0,0 +1,20 @@
+import type { AddImportersDependenciesMap } from '@vltpkg/graph';
+import type { Manifest } from '@vltpkg/types';
+import type { LoadedConfig } from './config/index.ts';
+type TypedManifest = Pick<Manifest, 'exports'> & {
+    types?: unknown;
+    typings?: unknown;
+    typesVersions?: unknown;
+};
+/** `foo` → `@types/foo`, `@scope/foo` → `@types/scope__foo` */
+export declare const typesName: (name: string) => string;
+/** Does the manifest declare its own TypeScript types? */
+export declare const hasOwnTypes: (m: TypedManifest) => boolean;
+/**
+ * For each added registry package that ships no types, add the newest
+ * non-deprecated `@types/*` package in the same major (major.minor for
+ * 0.x), else its older-major `latest`, to that importer's
+ * devDependencies.
+ */
+export declare const addTypesDeps: (conf: LoadedConfig, add: AddImportersDependenciesMap) => Promise<void>;
+export {};

package/dist/save-types.js

@@ -0,0 +1,105 @@
+import { splitDepID } from '@vltpkg/dep-id';
+import { addKey, asDependency } from '@vltpkg/graph';
+import { parse } from '@vltpkg/semver';
+import { Spec } from '@vltpkg/spec';
+import { isErrorWithCause, isObject, longDependencyTypes, } from '@vltpkg/types';
+import { resolve } from 'node:path';
+/** `foo` → `@types/foo`, `@scope/foo` → `@types/scope__foo` */
+export const typesName = (name) => `@types/${name.startsWith('@') ? name.slice(1).replace('/', '__') : name}`;
+const exportsHaveTypes = (e) => !!e &&
+    typeof e === 'object' &&
+    Object.entries(e).some(([k, v]) => k === 'types' || k.startsWith('types@') || exportsHaveTypes(v));
+// root entry only: typed subpaths don't type `import 'pkg'`
+const rootExport = (e) => isObject(e) && Object.keys(e).some(k => k.startsWith('.')) ?
+    e['.']
+    : e;
+/** Does the manifest declare its own TypeScript types? */
+export const hasOwnTypes = (m) => !!(m.types || m.typings || m.typesVersions) ||
+    exportsHaveTypes(rootExport(m.exports));
+const isResolveError = (er) => isErrorWithCause(er) &&
+    isObject(er.cause) &&
+    er.cause.code === 'ERESOLVE';
+/**
+ * For each added registry package that ships no types, add the newest
+ * non-deprecated `@types/*` package in the same major (major.minor for
+ * 0.x), else its older-major `latest`, to that importer's
+ * devDependencies.
+ */
+export const addTypesDeps = async (conf, add) => {
+    const { options } = conf;
+    const { packageInfo, packageJson, projectRoot } = options;
+    const exact = conf.values['save-exact'];
+    const prefix = conf.values['save-prefix'];
+    const lookups = new Map();
+    const lookup = async (spec, name) => {
+        const types = (range) => packageInfo.manifest(Spec.parse(name, range, options));
+        try {
+            const m = await packageInfo.manifest(spec);
+            const { version = '' } = m;
+            const v = parse(version);
+            if (!v || hasOwnTypes(m))
+                return;
+            let tm;
+            try {
+                // @types track lib major (major.minor for 0.x); x-range, `^0`
+                // would only match 0.0.0
+                tm = await types(v.major ? String(v.major) : `0.${v.minor}`);
+            }
+            catch (er) {
+                if (!isResolveError(er))
+                    throw er;
+                // @types often lag lib majors: take `latest` if older
+                tm = await types('latest');
+                if (!parse(tm.version ?? '')?.lessThan(v))
+                    return;
+            }
+            if (!tm.version || tm.deprecated)
+                return;
+            // abbreviated packuments omit types fields: recheck on full one
+            const { versions } = await packageInfo.packument(spec, {
+                full: true,
+            });
+            if (hasOwnTypes({ ...versions[version] }))
+                return;
+            return Spec.parse(name, exact ? tm.version : `${prefix}${tm.version}`, options);
+        }
+        catch (er) {
+            if (isResolveError(er))
+                return;
+            throw er;
+        }
+    };
+    await Promise.all([...add].map(async ([importer, deps]) => {
+        const mani = packageJson.maybeRead(resolve(projectRoot, splitDepID(importer)[1])) ?? {};
+        const found = await Promise.all([...deps.values()].map(async ({ spec }) => {
+            const { final } = spec;
+            const name = typesName(spec.name);
+            if (final.type !== 'registry' ||
+                final.name !== spec.name ||
+                spec.name.startsWith('@types/') ||
+                deps.has(name) ||
+                [...longDependencyTypes].some(t => mani[t]?.[name] !== undefined) ||
+                // other registry: its @types/<name> is a different pkg
+                final.registry !==
+                    Spec.parse(name, '', options).final.registry) {
+                return;
+            }
+            const key = String(spec);
+            let p = lookups.get(key);
+            if (!p)
+                lookups.set(key, (p = lookup(spec, name)));
+            return p;
+        }));
+        const types = found.filter(s => s !== undefined);
+        if (!types.length)
+            return;
+        // fresh Map: importers may share one deps Map
+        add.set(importer, new Map([
+            ...deps,
+            ...types.map(spec => [
+                addKey(spec),
+                asDependency({ spec, type: 'dev' }),
+            ]),
+        ]));
+    }));
+};

package/dist/sort-scope-locations.d.ts

@@ -0,0 +1,11 @@
+import type { Monorepo } from '@vltpkg/workspaces';
+/**
+ * Reorder `--scope` target locations so each workspace follows the
+ * workspaces it depends on (directly or via unmatched workspaces),
+ * matching --workspace/--recursive. Ties broken by query order (a dep
+ * may move ahead of unrelated matches); cycles broken
+ * deterministically. Non-workspace
+ * locations (root, installed deps) keep their index. Accepts absolute
+ * or projectRoot-relative locations; returns the original strings.
+ */
+export declare const sortScopeLocations: (locations: string[], monorepo?: Monorepo) => string[];

package/dist/sort-scope-locations.js

@@ -0,0 +1,57 @@
+import { resolve } from 'node:path';
+import { graphRunSync } from '@vltpkg/graph-run';
+/**
+ * Reorder `--scope` target locations so each workspace follows the
+ * workspaces it depends on (directly or via unmatched workspaces),
+ * matching --workspace/--recursive. Ties broken by query order (a dep
+ * may move ahead of unrelated matches); cycles broken
+ * deterministically. Non-workspace
+ * locations (root, installed deps) keep their index. Accepts absolute
+ * or projectRoot-relative locations; returns the original strings.
+ */
+export const sortScopeLocations = (locations, monorepo) => {
+    if (!monorepo || locations.length < 2)
+        return locations;
+    // resolve first: workspaces are also keyed by name and rel path
+    const wsAt = (loc) => monorepo.get(resolve(monorepo.projectRoot, loc));
+    const slots = locations.map(loc => [loc, wsAt(loc)]);
+    const locOf = new Map();
+    for (const [loc, ws] of slots) {
+        if (ws && !locOf.has(ws))
+            locOf.set(ws, loc);
+    }
+    const [first, ...rest] = locOf.keys();
+    if (!first || !rest.length)
+        return locations;
+    // matched deps, walking through unmatched workspaces
+    const getDeps = (ws) => {
+        const found = [];
+        const seen = new Set([ws]);
+        const queue = monorepo.getDeps(ws);
+        for (const dep of queue) {
+            if (seen.has(dep))
+                continue;
+            seen.add(dep);
+            if (locOf.has(dep))
+                found.push(dep);
+            else
+                queue.push(...monorepo.getDeps(dep));
+        }
+        return found;
+    };
+    // DFS post-order: deps first, ties in query order
+    const sorted = graphRunSync({
+        graph: [first, ...rest],
+        getDeps,
+        visit: () => { },
+    }).keys();
+    const placed = new Set();
+    return slots.map(([loc, ws]) => {
+        if (!ws || placed.has(ws))
+            return loc;
+        placed.add(ws);
+        const next = sorted.next().value;
+        /* c8 ignore next - same count as placed slots */
+        return (next && locOf.get(next)) ?? loc;
+    });
+};

package/package.json

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