@vltpkg/cli-sdk 1.4.0 → 1.6.0

package/dist/commands/install.js

@@ -1,9 +1,14 @@
 import { commandUsage } from "../config/usage.js";
 import { install } from '@vltpkg/graph';
+import { saveAllowSkills } from "../allow-skills.js";
 import { parseAddArgs } from "../parse-add-remove-args.js";
+import { assertGlobalOptions, linkGlobalBins, parseGlobalAddArgs, removeGlobalWorkspaces, } from "../global.js";
+import { resolveGlobalBinDir } from "../global-bin-dir.js";
+import { deferSelfRemove, runningStoreDep, selfUpdate, } from "../self-update.js";
 import { planSpecConfigPersist } from "../persist-spec-config.js";
 import { asUnknownSpecPrefix } from "../require-registry.js";
 import { addTypesDeps } from "../save-types.js";
+import { migrateWorkspaces } from "../migrate-workspaces.js";
 import { trackInstall } from "../telemetry.js";
 import { lazyView } from "../view.js";
 export const needsRegistry = true;
@@ -39,6 +44,9 @@ export const usage = () => commandUsage({
         '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.',
         },
+        'no-migrate-workspaces': {
+            description: "Don't save workspaces read from package.json or pnpm-workspace.yaml to vlt.json.",
+        },
         workspace: {
             value: '<path|glob>',
             description: 'Limit installation targets to matching workspaces.',
@@ -60,10 +68,24 @@ export const usage = () => commandUsage({
             value: '<query>',
             description: 'Filter which packages are allowed to run lifecycle scripts using DSS query syntax.',
         },
+        'allow-skills': {
+            value: '<query>',
+            description: "Link agent skills of packages matching this DSS query into the project's agent skill dirs. Saved to vlt.json.",
+        },
+        global: {
+            description: 'Install packages globally, each in its own workspace of the global project, linking their bins. `vlt install -g vlt` updates vlt itself.',
+        },
     },
 });
+// link mounts; `unchanged` left out
+const skillsJson = ({ linked, unchanged: _, ...rest }) => ({
+    linked: linked.map(s => s.mount),
+    ...rest,
+});
 export const views = {
     json: i => {
+        if (!('graph' in i))
+            return { self: i.self };
         const added = i.diff?.nodes.add ?? new Set();
         const deleted = i.diff?.nodes.delete ?? new Set();
         // The actual (from) graph represents what was on disk before the install.
@@ -117,12 +139,19 @@ export const views = {
             ...(i.buildQueue?.length ?
                 {
                     buildQueue: i.buildQueue,
-                    message: `${i.buildQueue.length} packages that will need to be built, run "vlt build" to complete the install.`,
+                    message: `${i.buildQueue.length} packages that will need to be built, run "vlt build${i.global ? ' -g' : ''}" to complete the install.`,
                 }
                 : null),
             ...(i.persistedConfig ?
                 { persistedConfig: i.persistedConfig }
                 : null),
+            ...(i.migratedWorkspaces ?
+                { migratedWorkspaces: i.migratedWorkspaces }
+                : null),
+            ...(i.skills ? { skills: skillsJson(i.skills) } : null),
+            ...(i.allowSkills ? { allowSkills: i.allowSkills } : null),
+            ...(i.global ? { global: i.global } : null),
+            ...(i.self ? { self: i.self } : null),
         };
     },
     human: lazyView(async () => (await import('./install/reporter.ts')).InstallReporter),
@@ -130,36 +159,52 @@ export const views = {
 export const command = async (conf) => {
     // TODO: we should probably throw an error if the user
     // tries to install using view=mermaid
-    const monorepo = conf.options.monorepo;
-    const scurry = conf.options.scurry;
-    const { add } = parseAddArgs(conf, scurry, monorepo);
+    if (conf.globalRoot)
+        assertGlobalOptions(conf);
+    // throws before any global ws dir is created
     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'];
-    const saveExact = conf.values['save-exact'];
-    const savePrefix = conf.values['save-prefix'];
-    /* c8 ignore start */
-    const allowScripts = conf.get('allow-scripts') ?
-        String(conf.get('allow-scripts'))
-        : ':not(*)';
-    /* c8 ignore stop */
+    // vlt i -g vlt: before any global ws or bin dir is created
+    const selfPlan = await selfUpdate(conf);
+    if (selfPlan && 'done' in selfPlan)
+        return { self: selfPlan.done };
+    const binDir = conf.globalRoot ?
+        await resolveGlobalBinDir(conf, {
+            selfUnwritable: !!selfPlan?.selfUnwritable,
+        })
+        : undefined;
+    // before reading options, it may reset them
+    const globalAdd = conf.globalRoot ? await parseGlobalAddArgs(conf) : undefined;
+    // never removed from under itself
+    const keep = conf.globalRoot ?
+        await runningStoreDep(conf.globalRoot)
+        : undefined;
     const installStart = Date.now();
-    const { buildQueue, graph, diff } = await install({
-        ...conf.options,
-        frozenLockfile,
-        expectLockfile,
-        allowScripts,
-        lockfileOnly,
-        saveExact,
-        savePrefix,
-    }, add).catch((er) => {
+    const { buildQueue, graph, diff, skills } = await runInstall(conf, globalAdd?.add, keep).catch(async (er) => {
+        if (globalAdd)
+            await removeGlobalWorkspaces(globalAdd.created);
         throw asUnknownSpecPrefix(er);
     });
+    const migrated = (conf.options['frozen-lockfile'] ||
+        conf.options['expect-lockfile']) ?
+        undefined
+        : migrateWorkspaces(conf);
+    if (conf.globalRoot)
+        await deferSelfRemove(conf.globalRoot, graph, keep);
+    const global = globalAdd &&
+        binDir &&
+        (await linkGlobalBins(graph, {
+            projectRoot: conf.options.projectRoot,
+            scurry: conf.options.scurry,
+            force: conf.options.force,
+            binDir,
+            fallback: () => resolveGlobalBinDir(conf, { selfUnwritable: true }),
+        }, globalAdd.importers));
     if (persist)
         await conf.addConfigToFile(persist.which, persist.values);
+    // nothing linked on --lockfile-only
+    const allowSkillsSave = conf.options['lockfile-only'] ?
+        undefined
+        : await saveAllowSkills(conf);
     /* c8 ignore next 9 - telemetry is best-effort */
     try {
         trackInstall({
@@ -173,5 +218,42 @@ export const command = async (conf) => {
         graph,
         diff,
         ...(persist ? { persistedConfig: persist } : null),
+        ...(migrated ? { migratedWorkspaces: migrated } : null),
+        ...(skills ? { skills } : null),
+        ...(allowSkillsSave ? { allowSkills: allowSkillsSave } : null),
+        ...(global ? { global } : null),
+        ...(selfPlan ? { self: await selfPlan.finish(global) } : null),
     };
 };
+// async, so any throw rolls back global ws dirs
+const runInstall = async (conf, globalAdd, keep) => {
+    const monorepo = conf.options.monorepo;
+    const scurry = conf.options.scurry;
+    const add = globalAdd ?? parseAddArgs(conf, scurry, monorepo).add;
+    // global ws has only the package as dep
+    if (conf.values['save-types'] && !globalAdd)
+        await addTypesDeps(conf, add);
+    const frozenLockfile = conf.options['frozen-lockfile'];
+    const expectLockfile = conf.options['expect-lockfile'];
+    const lockfileOnly = conf.options['lockfile-only'];
+    const saveExact = conf.values['save-exact'];
+    const savePrefix = conf.values['save-prefix'];
+    /* c8 ignore start */
+    const allowScripts = conf.get('allow-scripts') ?
+        String(conf.get('allow-scripts'))
+        : ':not(*)';
+    /* c8 ignore stop */
+    const allowSkills = conf.get('allow-skills');
+    return install({
+        ...conf.options,
+        frozenLockfile,
+        expectLockfile,
+        allowScripts,
+        allowSkills,
+        skillsDirs: conf.get('skills-dir'),
+        lockfileOnly,
+        saveExact,
+        savePrefix,
+        ...(keep ? { keepNodes: new Set([keep]) } : null),
+    }, add);
+};

package/dist/commands/list.js

@@ -1,4 +1,4 @@
-import { actual, asNode, humanReadableOutput, jsonOutput, mermaidOutput, GraphModifier, } from '@vltpkg/graph';
+import { actual, asNode, hasSkills, humanReadableOutput, jsonOutput, mermaidOutput, GraphModifier, } from '@vltpkg/graph';
 import { Query } from '@vltpkg/query';
 import { SecurityArchive } from '@vltpkg/security-archive';
 import { error } from '@vltpkg/error-cause';
@@ -63,6 +63,9 @@ export const usage = () => commandUsage({
             value: '[human | json | mermaid | svg | png | count]',
             description: 'Output format. Defaults to human-readable or json if no tty. Use svg or png to render the dependency graph as an image and open it. Count outputs the number of dependency relationships in the result.',
         },
+        global: {
+            description: 'List globally installed packages.',
+        },
     },
 });
 export const views = {
@@ -101,7 +104,8 @@ export const command = async (conf) => {
     const usesHostContext = [queryString, scopeQueryString].some(q => q?.includes(':host('));
     // optionally load the cwd graph if we found a package.json file
     if (mainManifest) {
-        if (!usesHostContext) {
+        // the global project is always vlt managed
+        if (!usesHostContext && !conf.globalRoot) {
             assertVltInstalled(conf.options.projectRoot, 'ls');
         }
         graph = actual.load({
@@ -138,6 +142,7 @@ export const command = async (conf) => {
             securityArchive,
             hostContexts,
             getAuthHeader,
+            hasSkills,
         });
         const { nodes: resultNodes } = await scopeQuery.search(scopeQueryString, {
             signal: new AbortController().signal,
@@ -190,6 +195,7 @@ export const command = async (conf) => {
         securityArchive,
         hostContexts,
         getAuthHeader,
+        hasSkills,
     });
     const query = queryString ||
         /* c8 ignore next */

package/dist/commands/publish.d.ts

@@ -1,5 +1,4 @@
 import type { CommandFn, CommandUsage } from '../index.ts';
-export declare const needsRegistry = true;
 export declare const usage: CommandUsage;
 export type CommandResultSingle = {
     id: string;

package/dist/commands/publish.js

@@ -14,14 +14,17 @@ import { sortScopeLocations } from "../sort-scope-locations.js";
 import { minimatch } from 'minimatch';
 import { resolveRegistry } from "../require-registry.js";
 import { stderr } from "../output.js";
-export const needsRegistry = true;
+import { getPublishConfig } from "../publish-config.js";
 export const usage = () => commandUsage({
     command: 'publish',
     usage: '',
     description: `Create a tarball from a package and publish it to the configured registry.
     
     This command will pack the package in the current directory or specified folder,
-    and then upload it to the configured registry.`,
+    and then upload it to the configured registry.
+
+    The registry is the package's \`publishConfig.registry\` if set (no other
+    registry config needed), else \`--registry\`, else a configured alias.`,
     options: {
         tag: {
             description: 'Publish the package with the given tag',
@@ -143,22 +146,34 @@ export const command = async (conf) => {
         single = options.packageJson.find(process.cwd()) ?? projectRoot;
     }
     if (single) {
-        return commandSingle(single, conf);
+        const [target] = await resolveTargets([single], conf);
+        assert(target);
+        return commandSingle(target, conf);
     }
     assert(locations.length > 0, error('No workspaces or query results found'));
     const results = [];
-    for (const location of locations) {
-        results.push(await commandSingle(location, conf));
+    for (const target of await resolveTargets(locations, conf)) {
+        results.push(await commandSingle(target, conf));
     }
     return results;
 };
-const getPublishConfig = (manifest) => {
-    const pc = manifest
-        .publishConfig;
-    if (pc && typeof pc === 'object') {
-        return pc;
+/**
+ * Registry of every target, before anything runs or publishes.
+ * The configured one is only resolved (or prompted for) once.
+ */
+const resolveTargets = async (locations, conf) => {
+    let fallback;
+    const targets = [];
+    for (const location of locations) {
+        const manifestPath = conf.options.packageJson.find(location);
+        assert(manifestPath, 'No package.json found');
+        const manifestDir = dirname(manifestPath);
+        const manifest = conf.options.packageJson.read(manifestDir);
+        const registry = getPublishConfig(manifest)?.registry ??
+            (await (fallback ??= resolveRegistry(conf)));
+        targets.push({ manifestDir, registry });
     }
-    return undefined;
+    return targets;
 };
 /** Of several readmes at the package root, npm prefers the markdown one. */
 const README_MARKDOWN_EXTENSION = /\.(?:md|markdown|mdown|mdwn|mkd|mkdn)$/i;
@@ -182,17 +197,13 @@ const readPublishReadme = (packDir, files) => {
         readmeFilename,
     };
 };
-const commandSingle = async (location, conf) => {
-    const manifestPath = conf.options.packageJson.find(location);
-    assert(manifestPath, 'No package.json found');
-    const manifestDir = dirname(manifestPath);
+const commandSingle = async ({ manifestDir, registry }, conf) => {
     const manifest = conf.options.packageJson.read(manifestDir);
     assert(!manifest.private, error('Package has been marked as private'));
     const { 'dry-run': dry = false, otp } = conf.options;
     const publishConfig = getPublishConfig(manifest);
     const tag = publishConfig?.tag ?? conf.options.tag;
     const access = publishConfig?.access ?? conf.options.access;
-    const registry = publishConfig?.registry ?? (await resolveRegistry(conf));
     const registryUrl = new URL(registryBase(registry));
     const runOptions = {
         cwd: manifestDir,

package/dist/commands/query.js

@@ -1,4 +1,4 @@
-import { actual, asNode, humanReadableOutput, jsonOutput, mermaidOutput, GraphModifier, } from '@vltpkg/graph';
+import { actual, asNode, hasSkills, humanReadableOutput, jsonOutput, mermaidOutput, GraphModifier, } from '@vltpkg/graph';
 import { Query } from '@vltpkg/query';
 import { stdout } from "../output.js";
 import { error } from '@vltpkg/error-cause';
@@ -80,6 +80,9 @@ export const usage = () => commandUsage({
             value: '[human | json | mermaid | svg | png | count]',
             description: 'Output format. Defaults to human-readable or json if no tty. Use svg or png to render the dependency graph as an image and open it. Count outputs the number of dependency relationships in the result.',
         },
+        global: {
+            description: 'Query the global project.',
+        },
     },
 });
 const validateExpectedResult = (conf, edges) => {
@@ -128,7 +131,8 @@ export const command = async (conf) => {
     const usesHostContext = [queryString, scopeQueryString].some(q => q?.includes(':host('));
     // optionally load the cwd graph if we found a package.json file
     if (mainManifest) {
-        if (!usesHostContext) {
+        // the global project is always vlt managed
+        if (!usesHostContext && !conf.globalRoot) {
             assertVltInstalled(conf.options.projectRoot, 'query');
         }
         graph = actual.load({
@@ -166,6 +170,7 @@ export const command = async (conf) => {
             hostContexts,
             diffFiles,
             getAuthHeader,
+            hasSkills,
         });
         const { nodes: resultNodes } = await scopeQuery.search(scopeQueryString, {
             signal: new AbortController().signal,
@@ -231,6 +236,7 @@ export const command = async (conf) => {
         hostContexts,
         diffFiles,
         getAuthHeader,
+        hasSkills,
     });
     const query = queryString ||
         (graph ? defaultProjectQueryString : defaultLocalScopeQueryString);

package/dist/commands/setup.d.ts

@@ -1,3 +1,5 @@
+import type { Shell } from '../shell.ts';
+import type { PathSetupFile } from '../shell-setup/index.ts';
 import type { CommandFn, CommandUsage } from '../index.ts';
 /** Where users sign up for / log into a vlt.io account. */
 export declare const VLT_SIGNUP_URL = "https://www.vlt.io";
@@ -29,9 +31,33 @@ export type SetupResult = {
      * the project's `vlt.json`, so the result won't take effect here.
      */
     shadowedByProject?: boolean;
+    /**
+     * PATH step outcome; absent when skipped (--yes, no terminal,
+     * no-modify-path)
+     */
+    path?: SetupPathResult['path'] | SetupPathFailed;
+};
+export type SetupPathFailed = {
+    status: 'failed';
+    /** why; may hold the manual line */
+    message: string;
+};
+export type SetupPathResult = {
+    path: {
+        status: 'added' | 'unchanged' | 'in-path' | 'disabled' | 'cancelled';
+        /** canonical dir added to the PATH */
+        dir: string;
+        shell: Shell;
+        files: PathSetupFile[];
+        backups: string[];
+        /** manual line for the shell */
+        command: string;
+        /** loads it in the current shell */
+        source: string;
+    };
 };
 export declare const views: {
-    readonly human: (result: SetupResult) => string;
+    readonly human: (result: SetupResult | SetupPathResult) => string;
 };
 export declare const usage: CommandUsage;
-export declare const command: CommandFn<SetupResult>;
+export declare const command: CommandFn<SetupResult | SetupPathResult>;

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 {