@vltpkg/cli-sdk 1.4.0 → 1.6.0

package/dist/index.js

@@ -1,5 +1,7 @@
 import { format } from 'node:util';
 import { asRootError, findRootError } from '@vltpkg/output/error';
+import { isError } from '@vltpkg/types';
+import { setVltJsonOnly } from '@vltpkg/workspaces';
 import { loadPackageJson } from 'package-json-from-dist';
 import { getSortedCliOptions, getSortedKeys, } from "./config/definition.js";
 import { Config } from "./config/index.js";
@@ -14,7 +16,7 @@ const loadVlt = async (cwd, argv) => {
     catch (e) {
         const code = findRootError(e, { code: 'ECONFIG' }) ? 'ECONFIG' : 'JACKSPEAK';
         const err = asRootError(e, { code });
-        const { found, path, wanted, name } = err.cause;
+        const { found, path, wanted, name, cause } = err.cause;
         const isConfigFile = typeof path === 'string';
         const msg = isConfigFile ? `Problem in Config File ${path}`
             : code === 'ECONFIG' ? 'Config Error'
@@ -31,6 +33,9 @@ const loadVlt = async (cwd, argv) => {
         }
         if (wanted)
             stderr(indent(`Wanted: ${format(wanted)}`));
+        // eg the global project can't be created
+        if (isError(cause))
+            stderr(indent(`Cause: ${cause.message}`));
         if (validOptions) {
             stderr(indent('Valid Options:'));
             stderr(indent(validOptions.join('\n'), 4));
@@ -49,9 +54,12 @@ const run = async () => {
     if (vlt.get('version')) {
         return stdout(version);
     }
+    // ci reads workspaces from vlt.json only; set before options load
+    setVltJsonOnly(vlt.command === 'ci');
     const { monorepo } = vlt.options;
     // Infer the workspace by being in that directory.
-    if (vlt.get('workspace') === undefined) {
+    // Not for the global project, cwd is unrelated to it.
+    if (vlt.get('workspace') === undefined && !vlt.globalRoot) {
         const ws = monorepo?.get(cwd);
         if (ws) {
             vlt.values.workspace = [ws.path];
@@ -61,7 +69,10 @@ 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, the "workspaces" field of the root package.json, or the "packages" list of pnpm-workspace.yaml contains the correct workspaces.`);
+        const where = vlt.command === 'ci' ?
+            'the vlt.json config (vlt ci ignores package.json and pnpm-workspace.yaml)'
+            : 'the vlt.json config, the "workspaces" field of the root package.json, or the "packages" list of pnpm-workspace.yaml';
+        stderr(`Error: No matching workspaces found. Make sure ${where} contains the correct workspaces.`);
         if (vlt.get('workspace')) {
             stderr(indent(`Workspace: ${format(vlt.get('workspace'))}`));
         }

package/dist/install-receipt.d.ts

@@ -0,0 +1,40 @@
+export declare const receiptName = "install-receipt.json";
+/**
+ * Written by the official installer, in vlt's config dir or next to
+ * (or one dir above) the `vlt` it installed. vlt only updates
+ * `version` and `installedAt`.
+ */
+export type ReceiptData = {
+    receiptVersion: 1;
+    /** 'npm' | 'standalone', anything else is a newer installer */
+    method: string;
+    /** absolute dir holding the entry points */
+    binDir: string;
+    installer?: {
+        name?: string;
+        version?: string;
+    };
+    version?: string;
+    /** dist-tag or version asked for */
+    channel?: string;
+    /** `<os>-<arch>[-<libc>]` of a standalone build */
+    target?: string;
+    binaries?: string[];
+    /** rc files the installer edited */
+    modifiedPath?: string[];
+    installedAt?: string;
+};
+export type InstallReceipt = {
+    file: string;
+    data: ReceiptData;
+};
+/**
+ * The receipt covering the `vlt` found at `found`: valid, and its
+ * `binDir` is the dir of `found`.
+ */
+export declare const readInstallReceipt: (found: string, configDir?: string) => Promise<InstallReceipt | undefined>;
+/** set `version` and `installedAt`, keeping all other fields */
+export declare const writeInstallReceipt: (file: string, update: {
+    version: string;
+    installedAt?: string;
+}) => Promise<void>;

package/dist/install-receipt.js

@@ -0,0 +1,69 @@
+import { error } from '@vltpkg/error-cause';
+import { isObject } from '@vltpkg/types';
+import { XDG } from '@vltpkg/xdg';
+import { readFile, realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, resolve } from 'node:path';
+import { samePath } from "./global-project.js";
+import { writeJsonAtomic } from "./global-state.js";
+const xdg = new XDG('vlt');
+export const receiptName = 'install-receipt.json';
+const isStr = (v) => typeof v === 'string';
+const optStr = (v) => v === undefined || isStr(v);
+const optStrs = (v) => v === undefined || (Array.isArray(v) && v.every(isStr));
+const isReceipt = (d) => isObject(d) &&
+    d.receiptVersion === 1 &&
+    isStr(d.method) &&
+    !!d.method &&
+    isStr(d.binDir) &&
+    isAbsolute(d.binDir) &&
+    (d.installer === undefined ||
+        (isObject(d.installer) &&
+            optStr(d.installer.name) &&
+            optStr(d.installer.version))) &&
+    optStr(d.version) &&
+    optStr(d.channel) &&
+    optStr(d.target) &&
+    optStrs(d.binaries) &&
+    optStrs(d.modifiedPath) &&
+    optStr(d.installedAt);
+/**
+ * The receipt covering the `vlt` found at `found`: valid, and its
+ * `binDir` is the dir of `found`.
+ */
+export const readInstallReceipt = async (found, configDir = xdg.config()) => {
+    const dir = dirname(found);
+    const real = await realpath(dir).catch(() => undefined);
+    if (!real)
+        return;
+    for (const file of [
+        resolve(configDir, receiptName),
+        resolve(dir, receiptName),
+        resolve(dir, '..', receiptName),
+    ]) {
+        try {
+            const data = JSON.parse(await readFile(file, 'utf8'));
+            if (isReceipt(data) &&
+                samePath(await realpath(data.binDir), real))
+                return { file, data };
+        }
+        catch { }
+    }
+};
+/** set `version` and `installedAt`, keeping all other fields */
+export const writeInstallReceipt = async (file, update) => {
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (cause) {
+        throw error('Invalid install receipt', { path: file, cause });
+    }
+    if (!isReceipt(raw)) {
+        throw error('Invalid install receipt', { path: file });
+    }
+    await writeJsonAtomic(file, {
+        ...raw,
+        version: update.version,
+        installedAt: update.installedAt ?? new Date().toISOString(),
+    });
+};

package/dist/load-command.d.ts

@@ -15,6 +15,8 @@ export type Command<T> = {
      * Set to `true` by commands that hit a registry or resolve registry
      * specs. There is no default registry, so `outputCommand()` fails
      * early with an `ECONFIG` error when one of these runs unconfigured.
+     * `publish`/`unpublish` check in-command instead, since
+     * `publishConfig.registry` may suffice.
      */
     needsRegistry?: boolean;
     /**

package/dist/migrate-workspaces.d.ts

@@ -0,0 +1,16 @@
+import type { WorkspaceConfigSource } from '@vltpkg/workspaces';
+import type { LoadedConfig } from './config/index.ts';
+export type MigratedWorkspaces = {
+    source: WorkspaceConfigSource;
+    workspaces: string[];
+};
+/**
+ * Save workspaces read from `package.json` or `pnpm-workspace.yaml` to
+ * the project `vlt.json`, unless `--no-migrate-workspaces`.
+ */
+export declare const migrateWorkspaces: (conf: LoadedConfig) => MigratedWorkspaces | undefined;
+/**
+ * Warn when workspaces are declared only outside `vlt.json`, which
+ * `vlt ci` ignores.
+ */
+export declare const warnIgnoredWorkspaces: (conf: LoadedConfig) => void;

package/dist/migrate-workspaces.js

@@ -0,0 +1,44 @@
+import { save } from '@vltpkg/vlt-json';
+import { migratableWSConfig, resolveWSConfig, } from '@vltpkg/workspaces';
+import { stderr } from "./output.js";
+// workspaces declared outside vlt.json, if any
+const found = (conf) => {
+    const resolved = resolveWSConfig(conf.options.projectRoot, conf.options.packageJson, false);
+    const workspaces = migratableWSConfig(resolved);
+    const { source } = resolved;
+    if (!workspaces?.length || !source)
+        return;
+    return { source, workspaces };
+};
+/**
+ * Save workspaces read from `package.json` or `pnpm-workspace.yaml` to
+ * the project `vlt.json`, unless `--no-migrate-workspaces`.
+ */
+export const migrateWorkspaces = (conf) => {
+    if (!conf.options['migrate-workspaces'])
+        return;
+    const migrated = found(conf);
+    if (migrated)
+        save('workspaces', migrated.workspaces);
+    return migrated;
+};
+/**
+ * Warn when workspaces are declared only outside `vlt.json`, which
+ * `vlt ci` ignores.
+ */
+export const warnIgnoredWorkspaces = (conf) => {
+    const { loglevel } = conf.values;
+    if (loglevel === 'silent' || loglevel === 'error')
+        return;
+    let migrated;
+    try {
+        migrated = found(conf);
+    }
+    catch {
+        // invalid workspaces config: nothing to suggest
+        return;
+    }
+    if (!migrated)
+        return;
+    stderr(`Warning: vlt ci reads workspaces from vlt.json only; ignoring ${migrated.source}, its workspaces are not installed. Run \`vlt install\` to save them to vlt.json, or add them there.`);
+};

package/dist/output.js

@@ -1,6 +1,9 @@
+import { error } from '@vltpkg/error-cause';
 import { formatWithOptions, styleText as utilStyleText, } from 'node:util';
 import { createSupportsColor } from 'supports-color';
 import { defaultView } from "./config/definition.js";
+import { globalCommands } from "./global-project.js";
+import { sweepPendingRemove } from "./global-state.js";
 import { printErr, formatOptions } from "./print-err.js";
 import { hasConfiguredRegistry, hasNpmRegistry, missingNpmRegistryError, missingRegistryError, } from "./require-registry.js";
 import { isLazyView, isViewClass, loadLazyView } from "./view.js";
@@ -158,6 +161,14 @@ export const outputCommand = async (cliCommand, conf, { start, vltVersion } = {
     const telemetryEnabled = conf.values.telemetry;
     const commandName = conf.command;
     try {
+        // explicit only: `global` in the user config is ignored here
+        if (conf.explicit.global && !conf.globalRoot) {
+            throw error(`\`vlt ${conf.command}\` does not support --global`, {
+                code: 'EUSAGE',
+                found: conf.command,
+                validOptions: [...globalCommands],
+            });
+        }
         // checked here rather than in run() so that the missing-registry
         // error is rendered, tracked and exited like any other command
         // error, and so that the `--help` return above still works when
@@ -168,6 +179,8 @@ export const outputCommand = async (cliCommand, conf, { start, vltVersion } = {
         if (needsNpmRegistry && !hasNpmRegistry(conf)) {
             throw missingNpmRegistryError(conf.options['default-registry-alias']);
         }
+        if (conf.globalRoot)
+            await sweepPendingRemove(conf.globalRoot);
         const output = await onDone(await command(conf));
         stopRequestLog();
         const duration_ms = Date.now() - start;

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

@@ -2,7 +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";
+import { parseSpecArg } from "./require-registry.js";
 const rootDepID = joinDepIDTuple(['file', '.']);
 /**
  * Compute a DepID for the current working directory relative to the project
@@ -77,18 +77,6 @@ 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}.
  */
@@ -103,7 +91,7 @@ export const parseAddArgs = (config, scurry, monorepo) => {
     const parsedItems = [];
     let hasFileSpecs = false;
     for (const item of items) {
-        const spec = parseArg(item, specOptions);
+        const spec = parseSpecArg(item, specOptions);
         parsedItems.push({ spec, type });
         if (spec.type === 'file')
             hasFileSpecs = true;

package/dist/print-err.js

@@ -223,8 +223,11 @@ const printCode = (err, usage, stderr, format) => {
             return {};
         }
         case 'ECONFIG': {
-            const { found, wanted, validOptions } = err.cause;
+            const { found, wanted, validOptions, from } = err.cause;
             stderr(`Config Error: ${err.message}`);
+            if (from) {
+                stderr(indent(`From: ${format(from)}`));
+            }
             if (found) {
                 stderr(indent(`Found: ${format(found)}`));
             }

package/dist/publish-config.d.ts

@@ -0,0 +1,9 @@
+import type { NormalizedManifest } from '@vltpkg/types';
+type PublishConfig = {
+    directory?: string;
+    registry?: string;
+    access?: string;
+    tag?: string;
+};
+export declare const getPublishConfig: (manifest: NormalizedManifest) => PublishConfig | undefined;
+export {};

package/dist/publish-config.js

@@ -0,0 +1,8 @@
+export const getPublishConfig = (manifest) => {
+    const pc = manifest
+        .publishConfig;
+    if (pc && typeof pc === 'object') {
+        return pc;
+    }
+    return undefined;
+};

package/dist/query-auth.d.ts

@@ -3,7 +3,8 @@ import type { LoadedConfig } from './config/index.ts';
 /**
  * Returns a {@link GetAuthHeader} implementation that looks up
  * authorization tokens from the local keychain / env (incl.
- * `VLT_TOKEN_<key>` for configured registries), used by
- * network-reliant query selectors, e.g: `:outdated()`.
+ * `VLT_TOKEN` for the default registry and `VLT_TOKEN_<key>` for
+ * configured registries), used by network-reliant query selectors,
+ * e.g: `:outdated()`.
  */
 export declare const createGetAuthHeader: (conf: LoadedConfig) => GetAuthHeader;

package/dist/query-auth.js

@@ -1,11 +1,13 @@
-import { getTokenByURL, registryKeys } from '@vltpkg/registry-client';
+import { defaultRegistryKey, getTokenByURL, registryKeys, } from '@vltpkg/registry-client';
 /**
  * Returns a {@link GetAuthHeader} implementation that looks up
  * authorization tokens from the local keychain / env (incl.
- * `VLT_TOKEN_<key>` for configured registries), used by
- * network-reliant query selectors, e.g: `:outdated()`.
+ * `VLT_TOKEN` for the default registry and `VLT_TOKEN_<key>` for
+ * configured registries), used by network-reliant query selectors,
+ * e.g: `:outdated()`.
  */
 export const createGetAuthHeader = (conf) => {
     const keys = registryKeys(conf.options);
-    return async (url) => getTokenByURL(url, conf.options.identity, keys);
+    const def = defaultRegistryKey(conf.options);
+    return async (url) => getTokenByURL(url, conf.options.identity, keys, def);
 };

package/dist/reload-config.js

@@ -7,5 +7,6 @@ export const reloadConfig = async (folder) => {
     }
     catch { }
     const { Config } = await import("./config/index.js");
-    return Config.load(folder, process.argv, true);
+    // host contexts never switch to the global project
+    return Config.load(folder, process.argv, true, false);
 };

package/dist/require-registry.d.ts

@@ -1,3 +1,5 @@
+import { Spec } from '@vltpkg/spec';
+import type { SpecOptions } from '@vltpkg/spec';
 import type { RegistryCandidate } from './select-registry.ts';
 import type { LoadedConfig } from './config/index.ts';
 /**
@@ -17,6 +19,11 @@ export declare const unknownSpecPrefixError: (prefix: string, spec: string, vali
  * {@link unknownSpecPrefixError}. Other values are returned as is.
  */
 export declare const asUnknownSpecPrefix: (er: unknown) => unknown;
+/**
+ * Parse a positional arg, turning an unknown `name:` prefix into an
+ * `ECONFIG` that says how to define it.
+ */
+export declare const parseSpecArg: (item: string, options: SpecOptions) => Spec;
 /**
  * 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,6 +1,6 @@
 import { error } from '@vltpkg/error-cause';
 import { isErrorWithCause, isObject } from '@vltpkg/types';
-import { defaultRegistries, defaultRegistryName } from '@vltpkg/spec';
+import { defaultRegistries, defaultRegistryName, Spec, } from '@vltpkg/spec';
 import { selectRegistry } from "./select-registry.js";
 /**
  * There is no default registry. This is the single message used
@@ -41,6 +41,18 @@ export const asUnknownSpecPrefix = (er) => {
         unknownSpecPrefixError(found.slice(0, -1), spec, validOptions)
         : er;
 };
+/**
+ * Parse a positional arg, turning an unknown `name:` prefix into an
+ * `ECONFIG` that says how to define it.
+ */
+export const parseSpecArg = (item, options) => {
+    try {
+        return Spec.parseArgs(item, options);
+    }
+    catch (er) {
+        throw asUnknownSpecPrefix(er);
+    }
+};
 /**
  * Install-related commands need the alias that bare specs resolve
  * through (not merely some other configured registry) so packages and

package/dist/self-update.d.ts

@@ -0,0 +1,74 @@
+import type { DepID } from '@vltpkg/dep-id';
+import type { Graph } from '@vltpkg/graph';
+import type { LoadedConfig } from './config/index.ts';
+import type { GlobalBins } from './global.ts';
+export type SelfUpdateCase = 'standalone' | 'npm' | 'global-project' | 'bootstrap';
+/** `vlt install -g vlt` that ran, or had nothing to do */
+export type SelfUpdated = {
+    case: SelfUpdateCase;
+    status: 'updated' | 'up-to-date' | 'newer-running' | 'failed';
+    /** running version */
+    from: string;
+    /** resolved version */
+    to: string;
+    /** dir of the updated vlt */
+    dir: string;
+    /** newer-running: dist-tag of the implicit spec */
+    tag?: string;
+    /** bootstrap: the dir that is not writable */
+    notWritable?: string;
+    /** bootstrap: PATH dir whose vlt still runs first */
+    shadowedBy?: string;
+};
+/** vlt can't update this vlt, `message` says how to */
+export type SelfRefused = {
+    status: 'refused';
+    /** running version */
+    from: string;
+    /** dir of the running vlt */
+    dir: string;
+    message: string;
+};
+/** result of `vlt install -g vlt` */
+export type SelfUpdate = SelfUpdated | SelfRefused;
+export type SelfUpdatePlan = {
+    done: SelfUpdate;
+}
+/** caller runs the -g install, then `finish` */
+ | {
+    selfUnwritable: boolean;
+    finish: (global?: GlobalBins) => Promise<SelfUpdated>;
+};
+/** `checksum` of the file written to `dest`, `sha512-<base64>` */
+export type Release = {
+    checksum: string;
+};
+/** download one standalone entry point to `dest` */
+export type FetchRelease = (o: {
+    version: string;
+    target: string;
+    channel?: string;
+    bin: string;
+    dest: string;
+}) => Promise<Release>;
+/** `vlt install -g vlt...`, for the human view */
+export declare const isSelfUpdateArgs: (conf: Pick<LoadedConfig, "command" | "globalRoot" | "positionals">) => boolean;
+/**
+ * `vlt install -g vlt`: update the vlt on the PATH the way it was
+ * installed. Undefined when vlt is not a positional.
+ */
+export declare const selfUpdate: (conf: LoadedConfig, { fetchRelease }?: {
+    fetchRelease?: FetchRelease;
+}) => Promise<SelfUpdatePlan | undefined>;
+/** `vlt uninstall -g vlt` of a vlt that is not a global package */
+export declare const refuseSelfUninstall: (conf: LoadedConfig) => Promise<SelfRefused | undefined>;
+/** store id of the running vlt, when it runs from the global project */
+export declare const runningStoreDep: (root: string) => Promise<DepID | undefined>;
+/**
+ * Record the running vlt's store dir for removal by a later -g
+ * command when the graph no longer has it, and forget listed dirs
+ * the graph has again.
+ */
+export declare const deferSelfRemove: (root: string, graph: Pick<Graph, "nodes">, keep?: DepID) => Promise<void>;
+/** human lines for a self-update */
+export declare const selfUpdateLines: (s: SelfUpdate) => string[];