@vltpkg/cli-sdk 1.5.0 → 1.6.1

package/dist/commands/setup.js

@@ -8,6 +8,10 @@ import { registrySelectionFields } from "../config/merge-layers.js";
 import { commandUsage } from "../config/usage.js";
 import { normalizeRegistryURL } from "../require-registry.js";
 import { stdout } from "../output.js";
+import { resolveGlobalBinDir } from "../global-bin-dir.js";
+import { detectShell, prettyPath, shellPathCommand, } from "../shell.js";
+import { applyPathSetup, ask as askLine, pathSetupChanged, pathSetupFiles, pathSetupLines, planPathSetup, rcList, sourceCommand, } from "../shell-setup/index.js";
+import { editPathHint } from "../shell-setup/windows.js";
 /** Where users sign up for / log into a vlt.io account. */
 export const VLT_SIGNUP_URL = 'https://www.vlt.io';
 /** Base URL that per-account registries live under. */
@@ -58,8 +62,47 @@ const accountAuthError = (account, er) => (isErrorWithCause(er) &&
         `organization at ${VLT_SIGNUP_URL}, then run \`vlt setup\` again.`,
     ].join('\n'), { code: 'ECONFIG', cause: er })
     : asError(er);
+const pathView = (r, wizard = false) => {
+    if (r.status === 'failed') {
+        return `⚠️  Could not add the global bin folder to your PATH: ${r.message}`;
+    }
+    const dir = prettyPath(r.dir);
+    const rcs = rcList(r.files);
+    // the command lasts one session
+    const keep = process.platform === 'win32' ?
+        [`  To keep it: ${editPathHint}`]
+        : [];
+    switch (r.status) {
+        case 'added':
+            return pathSetupLines(r, r.source).join('\n');
+        case 'unchanged':
+            return [
+                `✅ ${dir} is already added to your PATH in ${rcs}`,
+                `   Open a new terminal, or run: ${r.source}`,
+            ].join('\n');
+        case 'in-path':
+            return wizard ? '' : `✅ ${dir} is already on your PATH`;
+        case 'disabled':
+            return [
+                `ℹ️  no-modify-path is set, so nothing was changed. To add ${dir} to your PATH, run:`,
+                `  ${r.command}`,
+                ...keep,
+            ].join('\n');
+        case 'cancelled':
+            if (wizard) {
+                return `ℹ️  Skipped. Run \`vlt setup --path\` later to add ${dir} to your PATH.`;
+            }
+            return [
+                `Nothing changed. To add ${dir} to your PATH, run:`,
+                `  ${r.command}`,
+                ...keep,
+            ].join('\n');
+    }
+};
 export const views = {
     human: (result) => {
+        if (!('account' in result))
+            return pathView(result.path);
         const lines = [
             `Configured ${Object.keys(result.registries).length} registry ${Object.keys(result.registries).length === 1 ?
                 'alias'
@@ -71,13 +114,19 @@ export const views = {
         if (result.shadowedByProject) {
             lines.push('', `Note: this project's vlt.json configures its own registries, and`, 'project config takes precedence. Re-run with `--config=project`', 'to configure this project instead.');
         }
+        const path = result.path && pathView(result.path, true);
+        if (path)
+            lines.push('', path);
         lines.push('', 'You can now install packages, e.g.:', '  vlt install <pkg>');
         return lines.join('\n');
     },
 };
 export const usage = () => commandUsage({
     command: 'setup',
-    usage: '[<account>]',
+    usage: [
+        '[<account>]',
+        '--path [--yes] [--global-bin-dir=<path>]',
+    ],
     description: `Configure the registry aliases for your vlt.io account so
                   that \`vlt install\` and \`vlx\` work out of the box.
 
@@ -85,7 +134,19 @@ export const usage = () => commandUsage({
                   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\`.`,
+                  your user \`vlt.json\`.
+
+                  In a terminal, if the global bin folder isn't on
+                  your \`PATH\` or set up yet, it ends by asking
+                  \`Setup PATH for global installs? (Y/n)\`: yes adds
+                  it (same as \`--path\`), no skips it. Run
+                  \`vlt setup --path\` later to do just that step.
+
+                  With \`--path\`, add the global bin folder
+                  (\`--global-bin-dir\`) to your \`PATH\` instead: writes
+                  \`<global-dir>/env\` and a marked section that loads
+                  it into your shell config. On Windows it adds it to
+                  your user \`Path\` (\`HKCU\\Environment\`).`,
     options: {
         config: {
             value: '<user | project>',
@@ -99,11 +160,129 @@ export const usage = () => commandUsage({
         },
         yes: {
             description: 'Skip interactive prompts (requires <account> and does not ' +
-                'open a browser for authentication).',
+                'open a browser for authentication). With --path: edit ' +
+                'without asking. Without --path: skips the PATH prompt.',
+        },
+        path: {
+            description: 'Only add the global bin folder to your PATH via your ' +
+                'shell config (user Path on Windows).',
+        },
+        'global-bin-dir': {
+            value: '<path>',
+            description: 'The folder to add to your PATH.',
         },
     },
 });
+const runPathSetup = async (o) => {
+    const root = o.globalDir;
+    const bin = await resolveGlobalBinDir({
+        projectRoot: root,
+        globalBinDir: o.globalBinDir,
+    });
+    const shell = detectShell();
+    const base = {
+        dir: bin.dir,
+        shell,
+        files: [],
+        backups: [],
+        command: shellPathCommand(shell, bin.dir),
+        source: sourceCommand(shell, root, bin.dir),
+    };
+    if (bin.inPath) {
+        return { ...base, status: 'in-path' };
+    }
+    // scripted installers must not fail
+    if (o.noModifyPath) {
+        return { ...base, status: 'disabled' };
+    }
+    const opts = { globalDir: root, dir: bin.dir, shell };
+    let plan = await planPathSetup(opts);
+    const files = pathSetupFiles(plan);
+    if (!pathSetupChanged(plan)) {
+        return { ...base, status: 'unchanged', files };
+    }
+    if (!o.yes) {
+        if (!process.stdin.isTTY) {
+            throw error('Not a terminal: pass --yes to add it to your PATH', {
+                code: 'EUSAGE',
+            });
+        }
+        const answer = await (o.ask ?? askLine)(o.question({ dir: prettyPath(bin.dir), rcs: rcList(files) })).catch((er) => {
+            // Ctrl-C
+            if (asError(er).name !== 'AbortError')
+                throw er;
+            process.stdout.write('\n');
+            return 'n';
+        });
+        if (/^n/i.test(answer)) {
+            return { ...base, status: 'cancelled', files };
+        }
+        // rc files may have changed while asking
+        plan = await planPathSetup(opts);
+    }
+    const r = await applyPathSetup(plan);
+    return {
+        ...base,
+        status: 'added',
+        files: r.files,
+        backups: r.backups,
+    };
+};
+const setupPath = async (conf, root) => {
+    if (conf.positionals.length) {
+        throw error('`vlt setup --path` takes no arguments', {
+            code: 'EUSAGE',
+            found: conf.positionals[0],
+        });
+    }
+    return {
+        path: await runPathSetup({
+            globalDir: root,
+            globalBinDir: conf.globalBinDir,
+            yes: !!conf.get('yes'),
+            noModifyPath: !!conf.get('no-modify-path'),
+            question: ({ dir, rcs }) => `Add ${dir} to your PATH in ${rcs}? (Y/n) `,
+        }),
+    };
+};
+// end of the wizard, in a terminal only
+const offerPath = async (conf, yes, ask) => {
+    if (yes || !process.stdin.isTTY || conf.get('no-modify-path')) {
+        return;
+    }
+    const g = conf.globalProject();
+    if (!g)
+        return;
+    try {
+        return await runPathSetup({
+            globalDir: g.root,
+            globalBinDir: g.binDir,
+            question: () => 'Setup PATH for global installs? (Y/n) ',
+            ask,
+        });
+    }
+    catch (er) {
+        // registries are already saved
+        const e = asError(er);
+        // e.g. the global-bin-dir that could not be created
+        const found = (isErrorWithCause(e) &&
+            isObject(e.cause) &&
+            typeof e.cause.found === 'string') ?
+            prettyPath(e.cause.found)
+            : undefined;
+        return {
+            status: 'failed',
+            message: found && !e.message.includes(found) ?
+                `${e.message}: ${found}`
+                : e.message,
+        };
+    }
+};
 export const command = async (conf) => {
+    // set only by --path, see Config#globalProject
+    const root = conf.globalRoot;
+    if (root)
+        return setupPath(conf, root);
     const yes = !!conf.get('yes');
     const which = configWriteTarget(conf, 'user');
     let rl;
@@ -198,11 +377,14 @@ export const command = async (conf) => {
         // worked.
         const shadowedByProject = which === 'user' &&
             registrySelectionFields.some(f => f in (conf.layers.project ?? {}));
+        // 8. offer PATH setup for global installs
+        const path = await offerPath(conf, yes, ask);
         return {
             account,
             which,
             registries,
             ...(shadowedByProject ? { shadowedByProject } : undefined),
+            ...(path ? { path } : undefined),
         };
     }
     finally {

package/dist/commands/skills.js

@@ -21,9 +21,8 @@ export const usage = () => commandUsage({
       \`.agents/skills\`, plus \`<folder>/skills\` for each agent folder
       at the project root (e.g. \`.claude/\`), or the \`skills-dir\`
       config. When packages ship skills with the same name, one is
-      linked and the others are reported. Only links made by vlt
-      (pointing into \`node_modules/.vlt\`) are ever replaced or
-      removed; anything else in the way is skipped.
+      linked and the others are reported. Only links made by vlt are
+      ever replaced or removed; anything else in the way is skipped.
 
       Use --target or a query after the subcommand to select packages
       using DSS query syntax. End a selector with

package/dist/commands/token.js

@@ -105,7 +105,7 @@ export const views = {
     },
 };
 const listTokens = async (rc, registry, identity, alias) => {
-    const localTok = await getToken(normalizeRegistryKey(registry), identity);
+    const localTok = await getToken(normalizeRegistryKey(registry), identity, rc.defaultRegistryKey);
     if (!localTok) {
         return { registry, alias, tokens: [] };
     }

package/dist/commands/uninstall.d.ts

@@ -1,5 +1,6 @@
 import type { Graph, LinkSkillsResult } from '@vltpkg/graph';
 import type { CommandFn, CommandUsage } from '../index.ts';
+import type { SelfRefused } from '../self-update.ts';
 export type UninstallResult = {
     /**
      * The resulting graph structure at the end of an uninstall.
@@ -10,11 +11,17 @@ export type UninstallResult = {
      */
     skills?: LinkSkillsResult;
 };
+/** `vlt uninstall -g vlt` of a vlt that is not a global package */
+export type UninstallCommandResult = UninstallResult | {
+    self: SelfRefused;
+};
 export declare const needsRegistry = true;
 export declare const needsNpmRegistry = true;
 export declare const usage: CommandUsage;
 export declare const views: {
-    readonly json: (i: UninstallResult) => import("@vltpkg/graph").LockfileData;
-    readonly human: import("../view.ts").LazyView<import("./install.ts").InstallResult>;
+    readonly json: (i: UninstallCommandResult) => import("@vltpkg/graph").LockfileData | {
+        self: SelfRefused;
+    };
+    readonly human: import("../view.ts").LazyView<Partial<import("./install.ts").InstallResult>>;
 };
-export declare const command: CommandFn<UninstallResult>;
+export declare const command: CommandFn<UninstallCommandResult>;

package/dist/commands/uninstall.js

@@ -1,6 +1,9 @@
 import { uninstall } from '@vltpkg/graph';
 import { commandUsage } from "../config/usage.js";
 import { parseRemoveArgs } from "../parse-add-remove-args.js";
+import { assertGlobalOptions, parseGlobalRemoveArgs, removeGlobalPackages, } from "../global.js";
+import { resolveGlobalBinDir } from "../global-bin-dir.js";
+import { deferSelfRemove, refuseSelfUninstall, runningStoreDep, } from "../self-update.js";
 import { lazyView } from "../view.js";
 export const needsRegistry = true;
 export const needsNpmRegistry = true;
@@ -25,26 +28,49 @@ export const usage = () => commandUsage({
             value: '<query>',
             description: 'Filter which packages are allowed to run lifecycle scripts using DSS query syntax.',
         },
+        global: {
+            description: 'Uninstall global packages, removing their workspace and bins.',
+        },
     },
 });
 export const views = {
-    json: i => i.graph.toJSON(),
+    json: i => ('graph' in i ? i.graph.toJSON() : { self: i.self }),
     human: lazyView(async () => (await import('./install/reporter.ts')).InstallReporter),
 };
 export const command = async (conf) => {
+    if (conf.globalRoot) {
+        assertGlobalOptions(conf);
+        const refused = await refuseSelfUninstall(conf);
+        if (refused)
+            return { self: refused };
+    }
     const { monorepo, scurry } = conf.options;
-    const { remove } = parseRemoveArgs(conf, scurry, monorepo);
+    const global = conf.globalRoot ? parseGlobalRemoveArgs(conf) : undefined;
+    // only swept, so a bad --global-bin-dir must not block it
+    const binDir = global ?
+        await resolveGlobalBinDir(conf).catch(() => undefined)
+        : undefined;
+    const { remove } = global ?? parseRemoveArgs(conf, scurry, monorepo);
     /* c8 ignore start */
     const allowScripts = conf.get('allow-scripts') ?
         String(conf.get('allow-scripts'))
         : ':not(*)';
     /* c8 ignore stop */
+    // never removed from under itself
+    const keep = conf.globalRoot ?
+        await runningStoreDep(conf.globalRoot)
+        : undefined;
     const { graph, skills } = await uninstall({
         ...conf.options,
         allowScripts,
         allowSkills: conf.get('allow-skills'),
         skillsDirs: conf.get('skills-dir'),
         lockfileOnly: conf.options['lockfile-only'],
+        ...(keep ? { keepNodes: new Set([keep]) } : null),
     }, remove);
+    if (global) {
+        await deferSelfRemove(conf.projectRoot, graph, keep);
+        await removeGlobalPackages(conf.projectRoot, global.dirs, binDir?.dir ?? conf.globalBinDir);
+    }
     return { graph, ...(skills ? { skills } : null) };
 };

package/dist/commands/update.d.ts

@@ -22,6 +22,6 @@ export declare const views: {
         buildQueue?: import("@vltpkg/dep-id").DepID[] | undefined;
         message?: string | undefined;
     };
-    readonly human: import("../view.ts").LazyView<InstallResult>;
+    readonly human: import("../view.ts").LazyView<Partial<InstallResult>>;
 };
 export declare const command: CommandFn<InstallResult>;

package/dist/config/definition.d.ts

@@ -236,6 +236,38 @@ export declare const definition: import("jackspeak").Jack<{
 } & {
     workspace: import("jackspeak").ConfigOption<"string", true, readonly string[] | undefined>;
     'workspace-group': import("jackspeak").ConfigOption<"string", true, readonly string[] | undefined>;
+} & {
+    global: {
+        short: string;
+        description: string;
+    };
+} & {
+    global: import("jackspeak").ConfigOption<"boolean", false, undefined>;
+} & {
+    'global-dir': {
+        hint: string;
+        default: string;
+        description: string;
+    };
+} & {
+    'global-dir': import("jackspeak").ConfigOption<"string", false, readonly string[] | undefined>;
+} & {
+    'global-bin-dir': {
+        hint: string;
+        description: string;
+    };
+} & {
+    'global-bin-dir': import("jackspeak").ConfigOption<"string", false, readonly string[] | undefined>;
+} & {
+    path: {
+        description: string;
+    };
+    'no-modify-path': {
+        description: string;
+    };
+} & {
+    path: import("jackspeak").ConfigOption<"boolean", false, undefined>;
+    'no-modify-path': import("jackspeak").ConfigOption<"boolean", false, undefined>;
 } & {
     scope: {
         short: string;

package/dist/config/definition.js

@@ -474,6 +474,66 @@ export const definition = j
         description: `Specify named workspace group names to load and operate on
                     when doing recursive operations on workspaces.`,
     },
+})
+    .flag({
+    global: {
+        short: 'g',
+        description: `Operate on the global project instead of the current
+                    one. Supported by \`install\`, \`uninstall\`, \`list\`,
+                    \`query\` and \`build\`.
+
+                    Each global package is installed in its own workspace of
+                    the project in \`--global-dir\`, and its bins are linked
+                    into \`--global-bin-dir\`.`,
+    },
+})
+    .opt({
+    'global-dir': {
+        hint: 'path',
+        default: xdg.data('global'),
+        description: `Location of the global project used by \`--global\`.
+                    Defaults to \`vlt/global\` in the XDG data directory.
+
+                    Only read from the command line, environment or the user
+                    config, never from a project \`vlt.json\`. A leading
+                    \`~\` is the home directory. Must be absolute in the
+                    user config.`,
+    },
+})
+    .opt({
+    'global-bin-dir': {
+        hint: 'path',
+        description: `Folder where bins of global packages are linked.
+
+                    Defaults to the folder of the \`vlt\` found in your
+                    \`PATH\` when it is writable, so bins run right away.
+                    If it is not writable, \`~/.local/bin\` is used when
+                    it is in your \`PATH\` (not on Windows). Otherwise
+                    \`<global-dir>/bin\`.
+
+                    Only read from the command line, environment or the
+                    user config, never from a project \`vlt.json\`. A
+                    leading \`~\` is the home directory. Must be absolute
+                    in the user config.`,
+    },
+})
+    .flag({
+    path: {
+        description: `With \`vlt setup\`, add the global bin folder
+                    (\`--global-bin-dir\`) to your \`PATH\` by editing
+                    your shell config (your user \`Path\` on Windows).
+                    Asks first, unless \`--yes\`. Command line only.`,
+    },
+    'no-modify-path': {
+        description: `Never edit shell config files (or the user
+                    \`Path\` on Windows) to add a folder to your
+                    \`PATH\`: turns off \`vlt setup --path\` edits
+                    and the \`vlt install -g\` offer (printing the line
+                    to add instead), and the \`vlt setup\` PATH prompt.
+                    Set \`VLT_NO_MODIFY_PATH=1\` (any value but \`0\`)
+                    in images or on machines whose dotfiles are
+                    managed elsewhere.`,
+    },
 })
     .opt({
     scope: {

package/dist/config/index.d.ts

@@ -77,7 +77,7 @@ export type ConfigFileData = ConfigFileDataNoCommand & {
 export type ConfigOptionsNoExtras = {
     [k in keyof OptionsResults<ConfigDefinitions>]: k extends (RecordField) ? RecordString : k extends 'command' ? never : OptionsResults<ConfigDefinitions>[k];
 };
-export type ConfigOptions = ConfigOptionsNoExtras & Pick<SpecOptions, 'catalog' | 'catalogs'> & {
+export type ConfigOptions = Omit<ConfigOptionsNoExtras, 'path'> & Pick<SpecOptions, 'catalog' | 'catalogs'> & {
     packageJson: PackageJson;
     scurry: PathScurry;
     projectRoot: string;
@@ -142,6 +142,24 @@ export declare class Config {
      * `~/projects/xyz`, then the highest dir it will check is `~/projects`
      */
     projectRoot: string;
+    /**
+     * Global project root, set when `--global` switched to it.
+     */
+    globalRoot?: string;
+    /**
+     * `--global-bin-dir` from cli, env or user config, set with
+     * `globalRoot`.
+     */
+    globalBinDir?: string;
+    /**
+     * The global project (`--global-dir`, `--global-bin-dir`: cli > env >
+     * user config, never a project `vlt.json`): the one switched to by
+     * `--global`, or the one `vlt setup` offers PATH setup for.
+     */
+    globalProject(): {
+        root: string;
+        binDir?: string;
+    } | undefined;
     /**
      * `Record<alias, canonical name>` to dereference command aliases.
      */
@@ -221,8 +239,11 @@ export declare class Config {
     /**
      * Find the local config file and load both it and the user-level config in
      * the XDG config home.
+     *
+     * When `args` select a `--global` command, the global project is used
+     * instead of the current one.
      */
-    loadConfigFile(): Promise<this>;
+    loadConfigFile(args?: string[]): Promise<this>;
     /**
      * Force a complete reload of config files from disk.
      * This clears all caches and re-reads config files.
@@ -238,7 +259,9 @@ export declare class Config {
      * only used in tests, resets the memoization
      * @internal
      */
-    reload?: boolean): Promise<LoadedConfig>;
+    reload?: boolean, 
+    /** switch to the global project on `--global` */
+    allowGlobal?: boolean): Promise<LoadedConfig>;
 }
 export type ParsedConfig = Config & {
     command: NonNullable<Config['command']>;