@vltpkg/cli-sdk 1.0.10 → 1.1.1

package/dist/commands/setup.js

@@ -1,11 +1,12 @@
 import { error } from '@vltpkg/error-cause';
-import { RegistryClient } from '@vltpkg/registry-client';
+import { getKC, normalizeRegistryKey, RegistryClient, } from '@vltpkg/registry-client';
 import { defaultRegistries } from '@vltpkg/spec';
 import { asError, isErrorWithCause, isObject } from '@vltpkg/types';
 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 { normalizeRegistryURL } from "../require-registry.js";
 import { stdout } from "../output.js";
 /** Where users sign up for / log into a vlt.io account. */
 export const VLT_SIGNUP_URL = 'https://www.vlt.io';
@@ -18,6 +19,27 @@ export const VLT_REGISTRY_BASE = 'https://registry.vlt.io';
 export const accountRegistries = ['npm', 'main'];
 /** Build the per-account registry URL for a given registry name. */
 export const accountRegistryURL = (account, name) => `${VLT_REGISTRY_BASE}/${encodeURIComponent(account)}/${name}/`;
+/**
+ * Path-scoped keychain keys do not match sibling registries
+ * (`…/<account>/main` vs `…/<account>/npm`). One account token covers
+ * both, so when the keychain holds it for only one alias, copy it to
+ * the other.
+ */
+export const persistAccountTokens = async (account, identity) => {
+    // keychain only: getToken() also returns env/runtime tokens
+    const kc = getKC(identity);
+    const keys = accountRegistries.map(name => normalizeRegistryKey(accountRegistryURL(account, name)));
+    const tokens = await Promise.all(keys.map(k => kc.get(k)));
+    const token = tokens.find(Boolean);
+    if (!token)
+        return;
+    // fill gaps only: never overwrite an existing (maybe newer) token
+    for (const [i, key] of keys.entries()) {
+        if (!tokens[i])
+            kc.set(key, token);
+    }
+    await kc.save();
+};
 /**
  * The account registries live at `${VLT_REGISTRY_BASE}/<account>/<name>/`, so
  * an account slug that doesn't exist is a 404 from the login endpoint. Say
@@ -36,8 +58,6 @@ const accountAuthError = (account, er) => (isErrorWithCause(er) &&
         `organization at ${VLT_SIGNUP_URL}, then run \`vlt setup\` again.`,
     ].join('\n'), { code: 'ECONFIG', cause: er })
     : asError(er);
-/** Ensure a registry URL ends with a single trailing slash. */
-const normalizeRegistryURL = (url) => url.endsWith('/') ? url : `${url}/`;
 export const views = {
     human: (result) => {
         const lines = [
@@ -62,9 +82,10 @@ export const usage = () => commandUsage({
                   that \`vlt install\` and \`vlx\` work out of the box.
 
                   Sign up or log in at ${VLT_SIGNUP_URL} first. The wizard
-                  authenticates against your account and writes the
-                  \`npm\` and \`main\` registry aliases (and any additional
-                  aliases you add) to your user \`vlt.json\`.`,
+                  authenticates against your account, stores the token
+                  for both the \`npm\` and \`main\` registries, and writes
+                  those aliases (and any additional aliases you add) to
+                  your user \`vlt.json\`.`,
     options: {
         config: {
             value: '<user | project>',
@@ -129,8 +150,8 @@ 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)) {
-                // one token covers every registry on the account, so the browser
-                // opens once and the token is stored for all of them.
+                // one login covers both account registries; the token is stored
+                // for each of them so path-scoped keychain lookups match.
                 stdout(`Authenticating your account registries (${accountRegistries.join(', ')})...`);
                 try {
                     await rc.login(accountRegistries.map(name => accountRegistryURL(account, name)));
@@ -168,6 +189,10 @@ export const command = async (conf) => {
         }
         // 6. persist the staged registries (merged, not clobbered)
         await conf.addConfigToFile(which, { registries });
+        // 7. fill a missing `npm`/`main` keychain entry from the other.
+        // no-op after login(), which already wrote both. runs after the
+        // config write so a keychain failure can't block it.
+        await persistAccountTokens(account, conf.options.identity);
         // 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.

package/dist/commands/token.js

@@ -77,7 +77,9 @@ const formatRegistryTokens = (r) => {
         lines.push('  (skipped remote query — no auth token)');
     }
     else if (r.error) {
-        lines.push(`  error: ${r.error}`);
+        // messages now carry advice on a second line; keep it indented
+        // under the registry heading rather than dedented to column 0.
+        lines.push(`  error: ${r.error.replaceAll('\n', '\n  ')}`);
     }
     else if (r.tokens.length === 0) {
         lines.push('  (no remote tokens found)');

package/dist/commands/unpublish.js

@@ -1,7 +1,6 @@
 import { error } from '@vltpkg/error-cause';
-import { RegistryClient } from '@vltpkg/registry-client';
+import { RegistryClient, assertOk, requestError, } from '@vltpkg/registry-client';
 import { Spec } from '@vltpkg/spec';
-import { asError } from '@vltpkg/types';
 import { commandUsage } from "../config/usage.js";
 import { resolveRegistry } from "../require-registry.js";
 export const needsRegistry = true;
@@ -87,16 +86,18 @@ export const command = async (conf) => {
             });
         }
         catch (err) {
-            throw error('Failed to fetch package metadata', {
-                cause: asError(err),
-            });
-        }
-        if (packumentResponse.statusCode !== 200) {
-            throw error('Package not found on the registry', {
+            throw requestError(err, {
+                message: 'Failed to fetch package metadata',
                 url: packumentUrl,
-                response: packumentResponse,
             });
         }
+        assertOk(packumentResponse, {
+            message: 'Failed to fetch package metadata',
+            url: packumentUrl,
+            advice: statusCode => statusCode === 404 ?
+                `${name} was not found on this registry.`
+                : undefined,
+        });
         const packument = packumentResponse.json();
         const versions = packument.versions;
         const distTags = packument['dist-tags'];
@@ -137,16 +138,17 @@ export const command = async (conf) => {
             });
         }
         catch (err) {
-            throw error('Failed to unpublish package version', {
-                cause: asError(err),
-            });
-        }
-        if (response.statusCode < 200 || response.statusCode >= 300) {
-            throw error('Failed to unpublish package version', {
+            throw requestError(err, {
+                message: 'Failed to unpublish package version',
                 url: putUrl,
-                response,
+                method: 'PUT',
             });
         }
+        assertOk(response, {
+            message: 'Failed to unpublish package version',
+            url: putUrl,
+            method: 'PUT',
+        });
     }
     else {
         // Unpublish entire package — DELETE the packument
@@ -159,16 +161,18 @@ export const command = async (conf) => {
             });
         }
         catch (err) {
-            throw error('Failed to fetch package metadata', {
-                cause: asError(err),
-            });
-        }
-        if (packumentResponse.statusCode !== 200) {
-            throw error('Package not found on the registry', {
+            throw requestError(err, {
+                message: 'Failed to fetch package metadata',
                 url: packumentUrl,
-                response: packumentResponse,
             });
         }
+        assertOk(packumentResponse, {
+            message: 'Failed to fetch package metadata',
+            url: packumentUrl,
+            advice: statusCode => statusCode === 404 ?
+                `${name} was not found on this registry.`
+                : undefined,
+        });
         const packument = packumentResponse.json();
         const deleteUrl = new URL(`${encodedName}/-rev/${packument._rev}`, registryUrl);
         let response;
@@ -184,16 +188,17 @@ export const command = async (conf) => {
             });
         }
         catch (err) {
-            throw error('Failed to unpublish package', {
-                cause: asError(err),
-            });
-        }
-        if (response.statusCode < 200 || response.statusCode >= 300) {
-            throw error('Failed to unpublish package', {
+            throw requestError(err, {
+                message: 'Failed to unpublish package',
                 url: deleteUrl,
-                response,
+                method: 'DELETE',
             });
         }
+        assertOk(response, {
+            message: 'Failed to unpublish package',
+            url: deleteUrl,
+            method: 'DELETE',
+        });
     }
     return {
         name,

package/dist/commands/update.d.ts

@@ -5,6 +5,7 @@ export declare const needsNpmRegistry = true;
 export declare const usage: CommandUsage;
 export declare const views: {
     readonly json: (i: InstallResult) => {
+        persistedConfig?: import("../persist-spec-config.ts").SpecConfigPersistPlan | undefined;
         graph: import("@vltpkg/graph").LockfileData;
         buildQueue?: import("@vltpkg/dep-id").DepID[] | undefined;
         message?: string | undefined;

package/dist/commands/update.js

@@ -1,6 +1,8 @@
 import { update } from '@vltpkg/graph';
 import { error } from '@vltpkg/error-cause';
 import { commandUsage } from "../config/usage.js";
+import { planSpecConfigPersist } from "../persist-spec-config.js";
+import { asUnknownSpecPrefix } from "../require-registry.js";
 import { lazyView } from "../view.js";
 export const needsRegistry = true;
 export const needsNpmRegistry = true;
@@ -10,6 +12,9 @@ export const usage = () => commandUsage({
     description: `Update dependencies to their latest in-range versions.
                   Discards the lockfile and resolves dependencies from scratch.`,
     options: {
+        '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.',
+        },
         'allow-scripts': {
             value: '<query>',
             description: 'Filter which packages are allowed to run lifecycle scripts using DSS query syntax.',
@@ -25,6 +30,9 @@ export const views = {
             }
             : null),
         graph: i.graph.toJSON(),
+        ...(i.persistedConfig ?
+            { persistedConfig: i.persistedConfig }
+            : null),
     }),
     human: lazyView(async () => (await import('./install/reporter.ts')).InstallReporter),
 };
@@ -35,6 +43,7 @@ export const command = async (conf) => {
             code: 'EUSAGE',
         });
     }
+    const persist = planSpecConfigPersist(conf);
     /* c8 ignore start */
     const allowScripts = conf.get('allow-scripts') ?
         String(conf.get('allow-scripts'))
@@ -43,6 +52,14 @@ export const command = async (conf) => {
     const { buildQueue, graph } = await update({
         ...conf.options,
         allowScripts,
+    }).catch((er) => {
+        throw asUnknownSpecPrefix(er);
     });
-    return { buildQueue, graph };
+    if (persist)
+        await conf.addConfigToFile(persist.which, persist.values);
+    return {
+        buildQueue,
+        graph,
+        ...(persist ? { persistedConfig: persist } : null),
+    };
 };

package/dist/commands/whoami.js

@@ -1,4 +1,5 @@
-import { RegistryClient } from '@vltpkg/registry-client';
+import { error } from '@vltpkg/error-cause';
+import { RegistryClient, assertOk } from '@vltpkg/registry-client';
 import { commandUsage } from "../config/usage.js";
 import { resolveRegistry } from "../require-registry.js";
 export const needsRegistry = true;
@@ -27,7 +28,24 @@ export const views = {
 };
 export const command = async (conf) => {
     const rc = new RegistryClient(conf.options);
-    const response = await rc.request(new URL('-/whoami', await resolveRegistry(conf)), { useCache: false });
+    const url = new URL('-/whoami', await resolveRegistry(conf));
+    const response = await rc.request(url, { useCache: false });
+    assertOk(response, {
+        message: 'Failed to look up the current user',
+        url,
+        advice: statusCode => statusCode === 401 || statusCode === 403 ?
+            `Not logged in to ${url.origin}. Run \`vlt login\` and try again.`
+            : undefined,
+    });
     const { username } = response.json();
+    if (typeof username !== 'string' || !username) {
+        throw error('Registry did not report a username', {
+            code: 'EREQUEST',
+            url,
+            wanted: 'a `username` string',
+            found: username,
+            response,
+        });
+    }
     return { username };
 };

package/dist/config/definition.d.ts

@@ -355,12 +355,16 @@ export declare const definition: import("jackspeak").Jack<{
         short: string;
         description: string;
     };
+    'save-config': {
+        description: string;
+    };
 } & {
     'save-dev': import("jackspeak").ConfigOption<"boolean", false, undefined>;
     'save-exact': import("jackspeak").ConfigOption<"boolean", false, undefined>;
     '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-config': import("jackspeak").ConfigOption<"boolean", false, undefined>;
 } & {
     'save-prefix': {
         description: string;

package/dist/config/definition.js

@@ -151,6 +151,10 @@ export const definition = j
 
      Command-specific fields may be set in a nested \`command\` object that
      overrides any options defined at the top level.
+
+     Object type values given in the environment or on the command line
+     are merged key by key over the config files (command line wins over
+     environment); other values replace them.
     `)
     .flag({
     color: {
@@ -216,6 +220,12 @@ export const definition = j
                     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.
+
+                    Aliases given on the command line or in
+                    \`VLT_REGISTRIES\` (newline-delimited) merge with the
+                    configured ones, later sources winning per key. Pass
+                    \`--save-config\` to \`install\`, \`add\` or
+                    \`update\` to save them to \`vlt.json\`.
                     `,
     },
     'scoped-registries': {
@@ -656,6 +666,17 @@ export const definition = j
                     devDependencies or optionalDependencies, but you want to
                     move it to be a non-optional production dependency.`,
     },
+    'save-config': {
+        description: `Save the registry and git host options given on the
+                    command line or via \`VLT_*\` env (\`--registry\`,
+                    \`--registries\`, \`--default-registry-alias\`,
+                    \`--scoped-registries\`, \`--jsr-registries\`,
+                    \`--git-hosts\`, \`--git-host-archives\`) to the
+                    project \`vlt.json\` (or the user one with
+                    \`--config=user\`) after a successful \`install\`,
+                    \`add\` or \`update\`. Values a config file already
+                    has are left alone.`,
+    },
 })
     .opt({
     'save-prefix': {

package/dist/config/index.d.ts

@@ -43,6 +43,11 @@ export type PairsAsRecords = ConfigOptionsNoExtras & {
  * optional, since a config file only sets what it sets.
  */
 export type ConfigFileLayer = Partial<PairsAsRecords>;
+/**
+ * `registries` alias names are used as spec prefixes, where `~` is
+ * reserved, and an empty name has nothing to prefix with.
+ */
+export declare const assertRegistryKeys: (registries: unknown, file: string) => void;
 export declare const pairsToRecords: (obj: NonNullable<ConfigFileData> | OptionsResults<ConfigDefinitions>) => PairsAsRecords;
 export declare const recordsToPairs: (obj: RecordPairs) => RecordPairs;
 export type ConfigDataNoCommand = {
@@ -145,6 +150,15 @@ export declare class Config {
      * Parse the arguments and set configuration and positionals accordingly.
      */
     parse(args?: string[]): this & ParsedConfig;
+    /**
+     * Values set on the command line or via `VLT_*` env for this run.
+     * Record fields hold only those `key=value` pairs, not the ones from
+     * config files.
+     *
+     * `VLT_*` env left as a parent vlt process wrote it only counts for
+     * what was explicit in that parent.
+     */
+    explicit: ConfigData;
     /**
      * Get a `key=value` list option value as an object.
      *

package/dist/config/index.js

@@ -25,7 +25,7 @@ import { PackageInfoClient } from '@vltpkg/package-info';
 import { PackageJson } from '@vltpkg/package-json';
 import { resetCaches } from '@vltpkg/dep-id';
 import { getOptions } from '@vltpkg/spec';
-import { assertRecordStringString, assertRecordStringT, isRecordStringString, } from '@vltpkg/types';
+import { assertRecordStringString, assertRecordStringT, isObject, isRecordStringString, } from '@vltpkg/types';
 import { find, load, reload, save } from '@vltpkg/vlt-json';
 import { Monorepo } from '@vltpkg/workspaces';
 import { readFile, rm, writeFile } from 'node:fs/promises';
@@ -58,7 +58,7 @@ const isRecordFieldValue = (k, v) => Array.isArray(v) &&
  * `registries` alias names are used as spec prefixes, where `~` is
  * reserved, and an empty name has nothing to prefix with.
  */
-const assertRegistryKeys = (registries, file) => {
+export const assertRegistryKeys = (registries, file) => {
     if (!registries || typeof registries !== 'object')
         return;
     const obj = Array.isArray(registries) ?
@@ -67,6 +67,7 @@ const assertRegistryKeys = (registries, file) => {
     for (const key of Object.keys(obj)) {
         if (key === '' || key.includes('~')) {
             throw error('Reserved character found in registries name', {
+                code: 'ECONFIG',
                 path: file,
                 found: key,
             });
@@ -110,6 +111,35 @@ export const recordsToPairs = (obj) => {
     ]));
 };
 const kRecord = Symbol('parsed key=value record');
+// jackspeak's env var name for a field
+const envKey = (k) => `VLT_${k.replace(/[^a-zA-Z0-9]+/g, '_').toUpperCase()}`;
+// `parse()` writes every resolved value to `VLT_*`, so a nested vlt
+// can't tell inherited env from env set for it. this holds the
+// parent's explicit values and the `VLT_*` env it wrote.
+const kParentEnv = '__VLT_INTERNAL_EXPLICIT';
+const parentEnv = () => {
+    try {
+        const p = JSON.parse(process.env[kParentEnv] ?? '');
+        return (isObject(p) &&
+            isObject(p.explicit) &&
+            Object.entries(p.explicit).every(([k, v]) => isRecordField(k) ?
+                Array.isArray(v) && v.every(x => typeof x === 'string')
+                : !isObject(v)) &&
+            isRecordStringString(p.env)) ?
+            p
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+// last pair per key wins, keeping the first one's position
+const dedupePairs = (pairs) => [
+    ...new Map(pairs.map(p => {
+        const eq = p.indexOf('=');
+        return [eq === -1 ? p : p.substring(0, eq), p];
+    })).values(),
+];
 /**
  * Class that handles configuration for vlt.
  *
@@ -220,18 +250,63 @@ export class Config {
             return this;
         // Store the original args for potential reload
         this.#originalArgs = [...args];
+        const envKeys = Object.keys(defaultValues).filter(k => process.env[envKey(k)] !== undefined);
+        const parent = parentEnv();
+        // file layer values, before env replaces them
+        const fileValues = this.#defaults();
         this.jack.loadEnvDefaults();
+        const envValues = this.#defaults();
         const p = this.jack.parseRaw(args);
+        const cliKeys = Object.keys(p.values);
         const fallback = getCommand(p.values['fallback-command']);
         this.command = getCommand(p.positionals[0]);
         const cmdOrFallback = this.command ?? fallback;
         const cmdSpecific = cmdOrFallback && this.commandValues[cmdOrFallback];
-        if (cmdSpecific) {
-            this.jack.setConfigValues(recordsToPairs(cmdSpecific));
-        }
+        const cmdPairs = cmdSpecific ? recordsToPairs(cmdSpecific) : {};
+        if (cmdSpecific)
+            this.jack.setConfigValues(cmdPairs);
         // ok, applied cmd-specific defaults, do rest of the parse
         this.jack.applyDefaults(p);
+        // 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.
+        const values = p.values;
+        const explicit = {};
+        for (const k of new Set([...envKeys, ...cliKeys])) {
+            const cli = cliKeys.includes(k) ? values[k] : undefined;
+            const env = this.#explicitEnv(k, envValues[k], parent);
+            if (isRecordField(k)) {
+                const pairs = [
+                    ...(env ?? []),
+                    ...(cli ?? []),
+                ];
+                if (pairs.length)
+                    explicit[k] = dedupePairs(pairs);
+            }
+            else if (cli !== undefined)
+                explicit[k] = cli;
+            // a command block beats env for scalars
+            else if (env !== undefined && !(k in cmdPairs))
+                explicit[k] = env;
+        }
+        this.explicit = explicit;
+        // record fields merge per key: file (or command block) -> env -> cli
+        for (const k of recordFields) {
+            const env = envKeys.includes(k) ? envValues[k] : [];
+            const cli = cliKeys.includes(k) ? values[k] : [];
+            const pairs = [...env, ...cli];
+            if (!pairs.length)
+                continue;
+            const base = (k in cmdPairs ? cmdPairs[k] : fileValues[k]) ?? [];
+            values[k] = dedupePairs([...base, ...pairs]);
+        }
         this.jack.writeEnv(p);
+        process.env[kParentEnv] = JSON.stringify({
+            explicit,
+            env: Object.fromEntries(Object.keys(defaultValues).flatMap(k => {
+                const v = process.env[envKey(k)];
+                return v === undefined ? [] : [[envKey(k), v]];
+            })),
+        });
         if (this.command)
             p.positionals.shift();
         else
@@ -249,6 +324,36 @@ export class Config {
         /* c8 ignore stop */
         return this;
     }
+    /**
+     * Values set on the command line or via `VLT_*` env for this run.
+     * Record fields hold only those `key=value` pairs, not the ones from
+     * config files.
+     *
+     * `VLT_*` env left as a parent vlt process wrote it only counts for
+     * what was explicit in that parent.
+     */
+    explicit = {};
+    // a field's explicit env value: all of it at the top level, the new
+    // pairs (or changed scalar) when inherited from a parent vlt. once a
+    // script changes a record var, the parent's explicit pairs are dropped.
+    #explicitEnv(k, value, parent) {
+        const cur = process.env[envKey(k)];
+        if (cur === undefined)
+            return undefined;
+        const written = parent?.env[envKey(k)];
+        if (cur === written)
+            return parent?.explicit[k];
+        if (!isRecordField(k) || written === undefined)
+            return value;
+        const old = new Set(written.split('\n'));
+        return value.filter(p => !old.has(p));
+    }
+    // the current jack defaults, ie config file (+ env, once loaded) values
+    #defaults() {
+        const d = { values: {}, positionals: [] };
+        this.jack.applyDefaults(d);
+        return d.values;
+    }
     /**
      * Get a `key=value` list option value as an object.
      *

package/dist/is-vlt-installed.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Whether `node_modules` in `projectRoot` was built by `vlt install`.
+ *
+ * The store dir `node_modules/.vlt` is only ever created by reify, so it
+ * is the primary marker. A dependency-less install creates no store, so
+ * the hidden lockfile it writes is accepted as the fallback. Outside
+ * of reify, the `actual.load` fs walk and `vlt build` only write that
+ * file when the store exists, so a project installed by another client
+ * never gains either.
+ */
+export declare const isVltInstalled: (projectRoot: string) => boolean;
+/**
+ * Throws when `node_modules` was not installed by vlt. Without a vlt
+ * install `actual.load` walks a foreign `node_modules`, recognizes
+ * nothing and reports every dependency as missing - an empty answer
+ * that looks like a real one.
+ */
+export declare const assertVltInstalled: (projectRoot: string, command: string) => void;

package/dist/is-vlt-installed.js

@@ -0,0 +1,46 @@
+import { lstatSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { error } from '@vltpkg/error-cause';
+// `throwIfNoEntry: false` only covers ENOENT: a `node_modules` that is a
+// file (ENOTDIR) or unreadable (EACCES) still throws, and neither of
+// those is a vlt install.
+const lstat = (path) => {
+    try {
+        return lstatSync(path, { throwIfNoEntry: false });
+    }
+    catch {
+        return undefined;
+    }
+};
+const isDir = (path) => !!lstat(path)?.isDirectory();
+const isFile = (path) => !!lstat(path)?.isFile();
+/**
+ * Whether `node_modules` in `projectRoot` was built by `vlt install`.
+ *
+ * The store dir `node_modules/.vlt` is only ever created by reify, so it
+ * is the primary marker. A dependency-less install creates no store, so
+ * the hidden lockfile it writes is accepted as the fallback. Outside
+ * of reify, the `actual.load` fs walk and `vlt build` only write that
+ * file when the store exists, so a project installed by another client
+ * never gains either.
+ */
+export const isVltInstalled = (projectRoot) => isDir(resolve(projectRoot, 'node_modules/.vlt')) ||
+    isFile(resolve(projectRoot, 'node_modules/.vlt-lock.json'));
+/**
+ * Throws when `node_modules` was not installed by vlt. Without a vlt
+ * install `actual.load` walks a foreign `node_modules`, recognizes
+ * nothing and reports every dependency as missing - an empty answer
+ * that looks like a real one.
+ */
+export const assertVltInstalled = (projectRoot, command) => {
+    if (isVltInstalled(projectRoot))
+        return;
+    const nodeModules = resolve(projectRoot, 'node_modules');
+    const hint = isDir(nodeModules) ?
+        `run \`vlt install\` to rebuild it before running \`vlt ${command}\``
+        : `run \`vlt install\` before running \`vlt ${command}\``;
+    throw error(`No vlt install found in ${nodeModules}\n\n  ${hint}`, {
+        code: 'EQUERY',
+        path: nodeModules,
+    });
+};

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

@@ -2,6 +2,7 @@ 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';
+import { asUnknownSpecPrefix } from "./require-registry.js";
 const rootDepID = joinDepIDTuple(['file', '.']);
 /**
  * Compute a DepID for the current working directory relative to the project
@@ -76,6 +77,18 @@ const rebaseFileSpec = (spec, importerPath, scurryCwd, specOptions, monorepo) =>
         return spec;
     return Spec.parseArgs(rebasedPath, specOptions);
 };
+/**
+ * Parse a positional arg, turning an unknown `name:` prefix into an
+ * `ECONFIG` that says how to define it.
+ */
+const parseArg = (item, options) => {
+    try {
+        return Spec.parseArgs(item, options);
+    }
+    catch (er) {
+        throw asUnknownSpecPrefix(er);
+    }
+};
 /**
  * Parses the positional arguments into {@link AddImportersDependenciesMap}.
  */
@@ -90,7 +103,7 @@ export const parseAddArgs = (config, scurry, monorepo) => {
     const parsedItems = [];
     let hasFileSpecs = false;
     for (const item of items) {
-        const spec = Spec.parseArgs(item, specOptions);
+        const spec = parseArg(item, specOptions);
         parsedItems.push({ spec, type });
         if (spec.type === 'file')
             hasFileSpecs = true;