@vltpkg/cli-sdk 1.0.10 → 1.1.1

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

@@ -0,0 +1,27 @@
+/**
+ * With `--save-config`, save registry and git host config given on the
+ * command line or via `VLT_*` env to `install` / `update`, so that the
+ * config files plus the lockfile can reproduce the install.
+ * @module
+ */
+import type { WhichConfig } from '@vltpkg/vlt-json';
+import type { ConfigFileData, LoadedConfig } from './config/index.ts';
+/** The config fields that change how specs are parsed. */
+export declare const specConfigFields: readonly ["registry", "registries", "default-registry-alias", "scoped-registries", "jsr-registries", "git-hosts", "git-host-archives"];
+export type SpecConfigPersistPlan = {
+    which: WhichConfig;
+    values: ConfigFileData;
+};
+/**
+ * The spec config set on the cli / env that the target config file (the
+ * project `vlt.json`, unless `--config=user`) should get. `undefined`
+ * unless `--save-config` is set. Values already in effect from a config
+ * file or builtin are left alone. Throws `ECONFIG` when the target file
+ * (or its `command.<cmd>` block) sets a value to something else, or a
+ * value is invalid.
+ *
+ * Call before installing, write the result after it succeeds.
+ */
+export declare const planSpecConfigPersist: (conf: LoadedConfig) => SpecConfigPersistPlan | undefined;
+/** `field=value` / `field.key=value` lines for a plan's values. */
+export declare const persistedEntries: (values: ConfigFileData) => string[];

package/dist/persist-spec-config.js

@@ -0,0 +1,212 @@
+/**
+ * With `--save-config`, save registry and git host config given on the
+ * command line or via `VLT_*` env to `install` / `update`, so that the
+ * config files plus the lockfile can reproduce the install.
+ * @module
+ */
+import { error } from '@vltpkg/error-cause';
+import { defaultGitHostArchives, defaultGitHosts, defaultJsrRegistries, defaultRegistries, defaultRegistryName, } from '@vltpkg/spec';
+import { isObject } from '@vltpkg/types';
+import { find } from '@vltpkg/vlt-json';
+import { assertRegistryKeys, configWriteTarget, isRecordField, pairsToRecords, } from "./config/index.js";
+import { getCommand } from "./config/definition.js";
+import { registrySelectionFields, registrySelectors, } from "./config/merge-layers.js";
+import { normalizeRegistryURL } from "./require-registry.js";
+/** The config fields that change how specs are parsed. */
+export const specConfigFields = [
+    'registry',
+    'registries',
+    'default-registry-alias',
+    'scoped-registries',
+    'jsr-registries',
+    'git-hosts',
+    'git-host-archives',
+];
+const builtins = {
+    registries: defaultRegistries,
+    'jsr-registries': defaultJsrRegistries,
+    'git-hosts': defaultGitHosts,
+    'git-host-archives': defaultGitHostArchives,
+};
+// git host templates are not urls
+const urlFields = new Set([
+    'registry',
+    'registries',
+    'scoped-registries',
+    'jsr-registries',
+]);
+const norm = (field, v) => urlFields.has(field) ? normalizeRegistryURL(v) : v;
+// printed values end up in CI logs, and a url can carry a token
+const redact = (value) => {
+    if (!URL.canParse(value))
+        return value;
+    const url = new URL(value);
+    if (!url.username && !url.password)
+        return value;
+    url.username = '';
+    url.password = '';
+    return url.href.replace('://', '://***@');
+};
+// a layer's (or command block's) value, `null` meaning absent
+const fromLayer = (layer, field, key) => {
+    const v = layer?.[field];
+    const r = key === undefined ? v
+        : v && typeof v === 'object' ? v[key]
+            : undefined;
+    return typeof r === 'string' ? r : undefined;
+};
+// set to `null`, removing the value from outer layers
+const isNulled = (layer, field, key) => {
+    const v = layer?.[field];
+    return key === undefined ?
+        v === null
+        : isObject(v) && v[key] === null;
+};
+const conflictError = (field, key, current, wanted, file, block) => {
+    const name = (block ? `command.${block}.` : '') +
+        (key === undefined ? field : `${field}.${key}`);
+    const cur = redact(current);
+    const flag = key === undefined ?
+        `--${field}=${cur}`
+        : `--${field} ${key}=${cur}`;
+    return error([
+        `${name} is already set to ${cur} in ${file}.`,
+        '',
+        `Pass \`${flag}\`${key === undefined ? '' : ', use another name,'} or run`,
+        block ?
+            '`vlt config edit` to change it first.'
+            : `\`vlt config set ${name}=${redact(wanted)}\` first.`,
+    ].join('\n'), { code: 'ECONFIG', found: wanted, wanted: current });
+};
+const ownsSelection = (layer) => registrySelectionFields.some(f => f in (layer ?? {}));
+/**
+ * The spec config set on the cli / env that the target config file (the
+ * project `vlt.json`, unless `--config=user`) should get. `undefined`
+ * unless `--save-config` is set. Values already in effect from a config
+ * file or builtin are left alone. Throws `ECONFIG` when the target file
+ * (or its `command.<cmd>` block) sets a value to something else, or a
+ * value is invalid.
+ *
+ * Call before installing, write the result after it succeeds.
+ */
+export const planSpecConfigPersist = (conf) => {
+    if (!conf.get('save-config'))
+        return undefined;
+    const explicit = pairsToRecords(conf.explicit);
+    if (!specConfigFields.some(f => f in explicit))
+        return undefined;
+    const which = configWriteTarget(conf, 'project');
+    const target = conf.layers[which];
+    const other = conf.layers[which === 'project' ? 'user' : 'project'];
+    // a project that owns selection drops the user's selectors
+    const otherSelectors = which === 'user' || !ownsSelection(target);
+    // a command block beats the top level for its command (names like
+    // `add` canonicalized, last wins). a record field in the block replaces
+    // the top level one, so keys it lacks go in the block.
+    const blocks = (target?.command ?? {});
+    const blockName = Object.keys(blocks)
+        .filter(n => getCommand(n) === conf.command)
+        .at(-1);
+    const block = blockName ? blocks[blockName] : undefined;
+    const staged = {};
+    for (const field of specConfigFields) {
+        const v = explicit[field];
+        if (v === undefined)
+            continue;
+        const entries = isRecordField(field) ?
+            Object.entries(v)
+            : [[undefined, v]];
+        for (const [key, raw] of entries) {
+            if (key === '') {
+                throw error(`${field} has an entry with no name.`, {
+                    code: 'ECONFIG',
+                    found: `=${raw}`,
+                    wanted: `<name>=${raw}`,
+                });
+            }
+            if (key !== undefined && field === 'registries') {
+                assertRegistryKeys({ [key]: raw }, `--${field}`);
+            }
+            if (key !== undefined && !raw) {
+                throw error(`${field}.${key} has no value.`, {
+                    code: 'ECONFIG',
+                    found: key,
+                    wanted: `${key}=<value>`,
+                });
+            }
+            // eg an empty VLT_REGISTRY
+            if (!raw)
+                continue;
+            const value = norm(field, raw);
+            const inBlock = fromLayer(block, field, key);
+            if (inBlock !== undefined) {
+                if (norm(field, inBlock) === value)
+                    continue;
+                throw conflictError(field, key, inBlock, value, find(which), blockName);
+            }
+            const toBlock = key !== undefined && isObject(block?.[field]) ?
+                blockName
+                : undefined;
+            const current = toBlock === undefined ?
+                fromLayer(target, field, key)
+                : undefined;
+            if (current !== undefined) {
+                if (norm(field, current) === value)
+                    continue;
+                throw conflictError(field, key, current, value, find(which));
+            }
+            // in effect without saving: the other file's value, unless the
+            // target drops it, else the builtin
+            const inOther = (toBlock !== undefined ||
+                isNulled(target, field, key) ||
+                (key === undefined && !otherSelectors)) ?
+                undefined
+                : fromLayer(other, field, key);
+            const builtin = key !== undefined ? builtins[field]?.[key]
+                : field === 'default-registry-alias' ? defaultRegistryName
+                    : undefined;
+            const inEffect = inOther ?? builtin;
+            if (inEffect !== undefined && norm(field, inEffect) === value) {
+                continue;
+            }
+            let dest = staged;
+            if (toBlock !== undefined) {
+                const cmds = (staged.command ??= {});
+                dest = cmds[toBlock] ??= {};
+            }
+            if (key === undefined)
+                dest[field] = value;
+            else {
+                const rec = (dest[field] ??= {});
+                rec[key] = value;
+            }
+        }
+    }
+    if (!Object.keys(staged).length)
+        return undefined;
+    // a project layer that sets any selection field owns selection, which
+    // would drop the user's registry / default-registry-alias. keep them,
+    // with the alias url, so the project file is self contained.
+    const { user } = conf.layers;
+    if (which === 'project' &&
+        ownsSelection(staged) &&
+        !ownsSelection(target)) {
+        for (const f of registrySelectors) {
+            const v = fromLayer(user, f);
+            if (v !== undefined && !(f in staged))
+                staged[f] = v;
+        }
+        const alias = staged['default-registry-alias'];
+        const url = alias && fromLayer(user, 'registries', alias);
+        const regs = (staged.registries ?? {});
+        if (url && !(alias in regs)) {
+            staged.registries = { ...regs, [alias]: url };
+        }
+    }
+    return { which, values: staged };
+};
+const entries = (path, v) => isObject(v) ?
+    Object.entries(v).flatMap(([k, x]) => entries(`${path}.${k}`, x))
+    : [`${path}=${redact(String(v))}`];
+/** `field=value` / `field.key=value` lines for a plan's values. */
+export const persistedEntries = (values) => Object.entries(values).flatMap(([f, v]) => entries(f, v));

package/dist/print-err.js

@@ -167,15 +167,22 @@ const printCode = (err, usage, stderr, format) => {
             return { file: true };
         }
         case 'ENEEDAUTH': {
-            const { url } = err.cause;
+            const { url, method, status } = err.cause;
             stderr(`Authentication Error: ${err.message}`);
             if (url) {
                 stderr(indent(`URL: ${formatURL(url, format)}`));
             }
+            if (method) {
+                stderr(indent(`Method: ${format(method)}`));
+            }
+            // a 401 and a 403 mean very different things to a user
+            if (status) {
+                stderr(indent(`Status: ${format(status)}`));
+            }
             return {};
         }
         case 'EREQUEST': {
-            const { url, method } = err.cause;
+            const { url, method, status } = err.cause;
             const { code, syscall } = err.cause.cause ?? {};
             stderr(`Request Error: ${err.message}`);
             if (code) {
@@ -190,6 +197,11 @@ const printCode = (err, usage, stderr, format) => {
             if (method) {
                 stderr(indent(`Method: ${format(method)}`));
             }
+            // set whenever the registry actually answered; its absence is
+            // what distinguishes a transport failure from a response.
+            if (status) {
+                stderr(indent(`Status: ${format(status)}`));
+            }
             return { file: true };
         }
         case 'EQUERY': {

package/dist/query-host-contexts.js

@@ -5,6 +5,7 @@ import { reloadConfig } from "./reload-config.js";
 import { actual, createVirtualRoot } from '@vltpkg/graph';
 import { SecurityArchive } from '@vltpkg/security-archive';
 import { error } from '@vltpkg/error-cause';
+import { isVltInstalled } from "./is-vlt-installed.js";
 // In restricted environments (like locked-down Codespaces),
 // homedir() might fail. Fall back to parent directory.
 let foundHome;
@@ -14,11 +15,6 @@ try {
 }
 catch { }
 const home = foundHome ?? posix.dirname(posix.format(parse(process.cwd())));
-const isVltInstalled = (folder) => !!folder.resolve('node_modules/.vlt').lstatSync()?.isDirectory() ||
-    !!folder
-        .resolve('node_modules/.vlt-lock.json')
-        .lstatSync()
-        ?.isFile();
 /**
  * Generates possible project keys for a given folder.
  */
@@ -96,7 +92,7 @@ export const createHostContextsMap = async (conf) => {
             try {
                 const config = await reloadConfig(folder.fullpath());
                 // only include projects that are vlt-installed
-                if (!isVltInstalled(folder)) {
+                if (!isVltInstalled(folder.fullpath())) {
                     continue;
                 }
                 // load each individual graph

package/dist/require-registry.d.ts

@@ -5,6 +5,18 @@ import type { LoadedConfig } from './config/index.ts';
  * everywhere a registry is required but missing.
  */
 export declare const missingRegistryError: () => Error;
+/** Ensure a registry URL ends with a single trailing slash. */
+export declare const normalizeRegistryURL: (url: string) => string;
+/**
+ * A spec used a `name:` prefix that no registry alias or git host
+ * defines.
+ */
+export declare const unknownSpecPrefixError: (prefix: string, spec: string, validOptions?: unknown[]) => Error;
+/**
+ * Turn a spec parse error about an unknown `name:` prefix into
+ * {@link unknownSpecPrefixError}. Other values are returned as is.
+ */
+export declare const asUnknownSpecPrefix: (er: unknown) => unknown;
 /**
  * Install-related commands need the alias that bare specs resolve
  * through (not merely some other configured registry) so packages and

package/dist/require-registry.js

@@ -1,4 +1,5 @@
 import { error } from '@vltpkg/error-cause';
+import { isErrorWithCause, isObject } from '@vltpkg/types';
 import { defaultRegistries, defaultRegistryName } from '@vltpkg/spec';
 import { selectRegistry } from "./select-registry.js";
 /**
@@ -12,6 +13,34 @@ export const missingRegistryError = () => error([
     '',
     'See https://docs.vlt.sh/cli for other ways to set a registry.',
 ].join('\n'), { code: 'ECONFIG' });
+/** Ensure a registry URL ends with a single trailing slash. */
+export const normalizeRegistryURL = (url) => url.replace(/\/*$/, '/');
+/**
+ * A spec used a `name:` prefix that no registry alias or git host
+ * defines.
+ */
+export const unknownSpecPrefixError = (prefix, spec, validOptions) => error([
+    `Unknown spec prefix "${prefix}:" in "${spec}".`,
+    '',
+    `Define it with \`--registries ${prefix}=<url>\` or`,
+    `\`--git-hosts ${prefix}=<template>\` (add \`--save-config\` to keep`,
+    `it in vlt.json), or run \`vlt config set registries.${prefix}=<url>\`.`,
+].join('\n'), { code: 'ECONFIG', found: `${prefix}:`, validOptions });
+/**
+ * Turn a spec parse error about an unknown `name:` prefix into
+ * {@link unknownSpecPrefixError}. Other values are returned as is.
+ */
+export const asUnknownSpecPrefix = (er) => {
+    const { found, spec, validOptions } = (isErrorWithCause(er) && isObject(er.cause) ?
+        er.cause
+        : {});
+    return (typeof found === 'string' &&
+        /^[^:]+:$/.test(found) &&
+        typeof spec === 'string' &&
+        er.message.startsWith('Protocol ')) ?
+        unknownSpecPrefixError(found.slice(0, -1), spec, validOptions)
+        : er;
+};
 /**
  * Install-related commands need the alias that bare specs resolve
  * through (not merely some other configured registry) so packages and

package/package.json

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

package/dist/registry-error-message.d.ts

@@ -1,2 +0,0 @@
-import type { CacheEntry } from '@vltpkg/registry-client';
-export declare const registryErrorMessage: (response: CacheEntry) => string;

package/dist/registry-error-message.js

@@ -1,29 +0,0 @@
-import { STATUS_CODES } from 'node:http';
-export const registryErrorMessage = (response) => {
-    const statusMessage = STATUS_CODES[response.statusCode];
-    const status = `${response.statusCode}${statusMessage ? ` ${statusMessage}` : ''}`;
-    let text;
-    try {
-        text = response.text().trim();
-    }
-    catch {
-        return status;
-    }
-    if (!text)
-        return status;
-    let detail = text;
-    try {
-        const body = JSON.parse(text);
-        if (body &&
-            typeof body === 'object' &&
-            'error' in body &&
-            typeof body.error === 'string' &&
-            body.error) {
-            detail = body.error;
-        }
-    }
-    catch {
-        // A non-JSON response body is itself the most useful error detail.
-    }
-    return `${status} — ${detail}`;
-};