@vltpkg/cli-sdk 1.5.0 → 1.6.1

package/dist/commands/build.d.ts

@@ -1,8 +1,13 @@
 import type { BuildResult } from '@vltpkg/graph';
+import type { GlobalBins } from '../global.ts';
 import type { CommandFn, CommandUsage } from '../index.ts';
+export type BuildCommandResult = BuildResult & {
+    global?: GlobalBins;
+};
 export declare const views: {
-    readonly human: (result: BuildResult) => string;
-    readonly json: (result: BuildResult) => {
+    readonly human: (result: BuildCommandResult) => string;
+    readonly json: (result: BuildCommandResult) => {
+        global?: GlobalBins | undefined;
         message: string;
         skipped?: {
             id: import("@vltpkg/dep-id").DepID;
@@ -28,4 +33,4 @@ export declare const usage: CommandUsage;
  * Build command implementation. Runs any required "postinstall"
  * lifecycle scripts and binary linking.
  */
-export declare const command: CommandFn<BuildResult>;
+export declare const command: CommandFn<BuildCommandResult>;

package/dist/commands/build.js

@@ -1,6 +1,8 @@
-import { build } from '@vltpkg/graph';
+import { actual, build } from '@vltpkg/graph';
 import { error } from '@vltpkg/error-cause';
 import { commandUsage } from "../config/usage.js";
+import { globalBinsLines, linkGlobalBins } from "../global.js";
+import { resolveGlobalBinDir } from "../global-bin-dir.js";
 import { isErrorWithCause } from '@vltpkg/types';
 const skippedMessage = (count, reason) => `${count} package${count === 1 ? '' : 's'} not built, ${reason === 'unscanned' ?
     'Socket has not scanned them yet'
@@ -23,6 +25,8 @@ export const views = {
         if (skippedCount > 0) {
             messages.push(`⏳ ${skippedMessage(skippedCount, result.skippedReason)}`);
         }
+        if (result.global)
+            messages.push(...globalBinsLines(result.global));
         return messages.join('\n');
     },
     json: (result) => {
@@ -45,6 +49,7 @@ export const views = {
                 : skippedList.length ?
                     skippedMessage(skippedList.length, result.skippedReason)
                     : 'No packages needed building.',
+            ...(result.global ? { global: result.global } : null),
         };
     },
 };
@@ -68,6 +73,9 @@ export const usage = () => commandUsage({
             value: '<query>',
             description: 'Query selector to filter packages using DSS syntax.',
         },
+        global: {
+            description: 'Build packages installed in the global project.',
+        },
     },
 });
 const isGraphRunError = (error) => typeof error === 'object' &&
@@ -81,6 +89,8 @@ const isGraphRunError = (error) => typeof error === 'object' &&
  */
 export const command = async (conf) => {
     const { options, projectRoot } = conf;
+    const binDir = conf.globalRoot ? await resolveGlobalBinDir(conf) : undefined;
+    let result;
     try {
         // Get target from option or first positional, default to all scripts
         const targetOption = conf.get('target');
@@ -89,7 +99,7 @@ export const command = async (conf) => {
             targetPositional ||
             ':scripts:not(:built):not(:malware)';
         // Run the build process using the graph build function
-        const result = await build({
+        result = await build({
             ...options,
             projectRoot,
             packageJson: options.packageJson,
@@ -97,7 +107,6 @@ export const command = async (conf) => {
             scurry: options.scurry,
             target,
         });
-        return result;
     }
     catch (cause) {
         const graphRunError = isErrorWithCause(cause) && isGraphRunError(cause.cause) ?
@@ -109,4 +118,23 @@ export const command = async (conf) => {
         }
         throw error('Build failed', { cause });
     }
+    if (!binDir)
+        return result;
+    // relink global bins, targets may be new
+    const graph = actual.load({
+        ...options,
+        projectRoot,
+        mainManifest: options.packageJson.read(projectRoot),
+        monorepo: options.monorepo,
+        scurry: options.scurry,
+        loadManifests: true,
+    });
+    const global = await linkGlobalBins(graph, {
+        projectRoot,
+        scurry: options.scurry,
+        force: options.force,
+        binDir,
+        fallback: () => resolveGlobalBinDir(conf, { selfUnwritable: true }),
+    });
+    return { ...result, global };
 };

package/dist/commands/ci.d.ts

@@ -6,6 +6,6 @@ export declare const needsNpmRegistry = true;
 export declare const usage: CommandUsage;
 export declare const views: {
     readonly json: (i: CIResult) => import("@vltpkg/graph").LockfileData;
-    readonly human: import("../view.ts").LazyView<InstallResult>;
+    readonly human: import("../view.ts").LazyView<Partial<InstallResult>>;
 };
 export declare const command: CommandFn<CIResult>;

package/dist/commands/create.d.ts

@@ -1,9 +1,10 @@
 import type { PromptFn } from '@vltpkg/vlx';
 import type { ExecResult } from '../exec-command.ts';
 import type { CommandFn, CommandUsage } from '../index.ts';
+import { prettyPath } from '../shell.ts';
 export { views } from '../exec-command.ts';
 export declare const needsRegistry = true;
 export declare const usage: CommandUsage;
-export declare const prettyPath: (path: string) => string;
+export { prettyPath };
 export declare const promptFn: PromptFn;
 export declare const command: CommandFn<ExecResult>;

package/dist/commands/create.js

@@ -1,10 +1,10 @@
 import { exec, execFG } from '@vltpkg/run';
 import * as vlx from '@vltpkg/vlx';
-import { homedir } from 'node:os';
 import { createInterface } from 'node:readline/promises';
 import { commandUsage } from "../config/usage.js";
 import { ExecCommand } from "../exec-command.js";
 import { styleTextStdout } from "../output.js";
+import { prettyPath } from "../shell.js";
 export { views } from "../exec-command.js";
 export const needsRegistry = true;
 export const usage = () => commandUsage({
@@ -47,8 +47,7 @@ export const usage = () => commandUsage({
         },
     },
 });
-const HOME = homedir();
-export const prettyPath = (path) => path.startsWith(HOME) ? `~${path.substring(HOME.length)}` : path;
+export { prettyPath };
 export const promptFn = async (pkgSpec, path, resolution) => {
     const response = await createInterface(process.stdin, process.stdout).question(`About to install: ${styleTextStdout(['bgWhiteBright', 'black', 'bold'], String(pkgSpec))}
 from: ${styleTextStdout(['bgWhiteBright', 'black', 'bold'], resolution)}

package/dist/commands/exec.d.ts

@@ -1,10 +1,11 @@
 import type { PromptFn } from '@vltpkg/vlx';
 import type { ExecResult } from '../exec-command.ts';
 import type { CommandFn, CommandUsage } from '../index.ts';
+import { prettyPath } from '../shell.ts';
 export { views } from '../exec-command.ts';
 export declare const needsRegistry = true;
 export declare const needsNpmRegistry = true;
 export declare const usage: CommandUsage;
-export declare const prettyPath: (path: string) => string;
+export { prettyPath };
 export declare const promptFn: PromptFn;
 export declare const command: CommandFn<ExecResult>;

package/dist/commands/exec.js

@@ -1,11 +1,11 @@
 import { exec, execFG } from '@vltpkg/run';
 import * as vlx from '@vltpkg/vlx';
-import { homedir } from 'node:os';
 import { env, platform } from 'node:process';
 import { createInterface } from 'node:readline/promises';
 import { commandUsage } from "../config/usage.js";
 import { ExecCommand } from "../exec-command.js";
 import { styleTextStdout } from "../output.js";
+import { prettyPath } from "../shell.js";
 export { views } from "../exec-command.js";
 export const needsRegistry = true;
 export const needsNpmRegistry = true;
@@ -113,8 +113,7 @@ export const usage = () => commandUsage({
         },
     },
 });
-const HOME = homedir();
-export const prettyPath = (path) => path.startsWith(HOME) ? `~${path.substring(HOME.length)}` : path;
+export { prettyPath };
 export const promptFn = async (pkgSpec, path, resolution) => {
     const response = await createInterface(process.stdin, process.stdout).question(`About to install: ${styleTextStdout(['bgWhiteBright', 'black', 'bold'], String(pkgSpec))}
 from: ${styleTextStdout(['bgWhiteBright', 'black', 'bold'], resolution)}

package/dist/commands/init.js

@@ -76,7 +76,7 @@ export const command = async (conf) => {
             // create the folder in case it's missing
             mkdirSync(cwd, { recursive: true });
             // run the initialization script and collect results
-            results.push(await init({ cwd }));
+            results.push(await init({ cwd, packageJson: conf.options.packageJson }));
             // Check if this workspace path is covered by existing workspace patterns
             const isMatched = Object.values(parsedWSConfig).some((group) => {
                 const { patterns, ignore } = splitNegatedPatterns(group);
@@ -136,7 +136,10 @@ export const command = async (conf) => {
         await install({ ...conf.options, allowScripts });
         return results;
     }
-    const result = await init({ cwd: process.cwd() });
+    const result = await init({
+        cwd: process.cwd(),
+        packageJson: conf.options.packageJson,
+    });
     // run install to set up node_modules and vlt-lock.json
     await install({ ...conf.options, allowScripts });
     return result;

package/dist/commands/install/reporter.d.ts

@@ -3,7 +3,7 @@ import type { InstallResult } from '../install.ts';
 export declare class InstallReporter extends ViewClass {
     #private;
     start(): void;
-    done(_result: InstallResult, { time }: {
+    done(_result: Partial<InstallResult>, { time }: {
         time: number;
     }): Promise<undefined>;
     error(err: unknown): void;

package/dist/commands/install/reporter.js

@@ -4,8 +4,11 @@ import Spinner from 'ink-spinner';
 import { createElement as $, Fragment, useEffect, useState, } from 'react';
 import { ViewClass } from "../../view.js";
 import { asError } from '@vltpkg/types';
+import { isSelfUpdateArgs, selfUpdateLines, } from "../../self-update.js";
 import { persistedEntries } from "../../persist-spec-config.js";
 import { keptLine, savedLine, unmatchedLines, unscannedLines, } from "../../allow-skills.js";
+import { globalBinsLines } from "../../global.js";
+import { offerPathSetup } from "../../shell-setup/index.js";
 const labels = {
     build: 'resolving dependencies',
     actual: '',
@@ -75,6 +78,7 @@ const App = ({ trailer }) => {
 };
 export class InstallReporter extends ViewClass {
     #instance = null;
+    #plain = false;
     start() {
         // Ink measures the terminal on every render, and when stdout has no
         // width (a pipe, a CI log) it does so by spawning `tput cols` and
@@ -87,17 +91,35 @@ export class InstallReporter extends ViewClass {
             process.stdout.columns ||=
                 Number.isInteger(cols) && cols > 0 ? cols : 80;
         }
+        // npm may write to the terminal: no live view
+        if (isSelfUpdateArgs(this.config)) {
+            this.#plain = true;
+            return;
+        }
         this.#instance = render($(App));
     }
     async done(_result, { time }) {
-        let out = `Done in ${time}ms`;
+        const { self } = _result;
+        let out = self && !_result.graph ? '' : `Done in ${time}ms`;
         // prints a very complete message explaining users the next steps
         // in case there are packages to be built
+        const g = _result.global ? ' -g' : '';
         if (_result.buildQueue?.length) {
             out += `\n\n📦 ${_result.buildQueue.length} packages have install scripts defined & were not fully built\n`;
-            out += '🔎 Run `vlt query :scripts` to list them\n';
-            out +=
-                '🔨 Run `vlt build` to run all required scripts to build installed packages.\n';
+            out += `🔎 Run \`vlt query${g} :scripts\` to list them\n`;
+            out += `🔨 Run \`vlt build${g}\` to run all required scripts to build installed packages.\n`;
+        }
+        if (self) {
+            for (const l of selfUpdateLines(self))
+                out += out ? `\n${l}` : l;
+        }
+        if (_result.global) {
+            // the self-update line says why
+            const bins = self?.status === 'updated' && self.case === 'bootstrap' ?
+                { ..._result.global, notWritable: undefined }
+                : _result.global;
+            for (const l of globalBinsLines(bins))
+                out += `\n${l}`;
         }
         const { linked = [], removed = [], conflicts = [], skipped = [], gitignore = [], unmatched = [], } = _result.skills ?? {};
         const s = (n) => (n === 1 ? '' : 's');
@@ -139,7 +161,25 @@ export class InstallReporter extends ViewClass {
             out += `\n${keptLine(a.stored)}`;
         else if (a)
             out += `\n${savedLine(a.query, 'project')}`;
-        this.#instance?.rerender($(App, { trailer: out }));
+        // failed: npm already said why
+        if (!out)
+            return undefined;
+        if (this.#plain)
+            this.#instance = render($(Text, null, out));
+        else
+            this.#instance?.rerender($(App, { trailer: out }));
+        if (_result.global) {
+            await offerPathSetup(_result.global, {
+                globalDir: this.config.projectRoot,
+                yes: !!this.config.get('yes'),
+                noModifyPath: !!this.config.get('no-modify-path'),
+                // ink owns the terminal until unmounted
+                beforeOutput: () => {
+                    this.#instance?.unmount();
+                    this.#instance = null;
+                },
+            });
+        }
         return undefined;
     }
     error(err) {

package/dist/commands/install.d.ts

@@ -1,4 +1,6 @@
 import type { AllowSkillsSave } from '../allow-skills.ts';
+import type { GlobalBins } from '../global.ts';
+import type { SelfUpdate } from '../self-update.ts';
 import type { MigratedWorkspaces } from '../migrate-workspaces.ts';
 import type { SpecConfigPersistPlan } from '../persist-spec-config.ts';
 import type { DepID } from '@vltpkg/dep-id';
@@ -37,12 +39,28 @@ export type InstallResult = {
      * is stored.
      */
     allowSkills?: AllowSkillsSave;
+    /**
+     * Bins linked by a `--global` install.
+     */
+    global?: GlobalBins;
+    /**
+     * `vlt install -g vlt`
+     */
+    self?: SelfUpdate;
+};
+/** self-update handed off or nothing to do */
+export type InstallCommandResult = InstallResult | {
+    self: SelfUpdate;
 };
 export declare const needsRegistry = true;
 export declare const needsNpmRegistry = true;
 export declare const usage: CommandUsage;
 export declare const views: {
-    readonly json: (i: InstallResult) => {
+    readonly json: (i: InstallCommandResult) => {
+        self: SelfUpdate;
+    } | {
+        self?: SelfUpdate | undefined;
+        global?: GlobalBins | undefined;
         allowSkills?: AllowSkillsSave | undefined;
         skills?: {
             unscanned?: string[];
@@ -76,6 +94,6 @@ export declare const views: {
         }[];
         removed: number;
     };
-    readonly human: import("../view.ts").LazyView<InstallResult>;
+    readonly human: import("../view.ts").LazyView<Partial<InstallResult>>;
 };
-export declare const command: CommandFn<InstallResult>;
+export declare const command: CommandFn<InstallCommandResult>;

package/dist/commands/install.js

@@ -2,6 +2,9 @@ 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";
@@ -69,6 +72,9 @@ export const usage = () => commandUsage({
             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
@@ -78,6 +84,8 @@ const skillsJson = ({ linked, unchanged: _, ...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.
@@ -131,7 +139,7 @@ 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 ?
@@ -142,6 +150,8 @@ export const views = {
                 : 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),
@@ -149,42 +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 */
-    const allowSkills = conf.get('allow-skills');
+    // 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, skills } = await install({
-        ...conf.options,
-        frozenLockfile,
-        expectLockfile,
-        allowScripts,
-        allowSkills,
-        skillsDirs: conf.get('skills-dir'),
-        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 = frozenLockfile || expectLockfile ? undefined : (migrateWorkspaces(conf));
+    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 = lockfileOnly ? undefined : await saveAllowSkills(conf);
+    const allowSkillsSave = conf.options['lockfile-only'] ?
+        undefined
+        : await saveAllowSkills(conf);
     /* c8 ignore next 9 - telemetry is best-effort */
     try {
         trackInstall({
@@ -201,5 +221,39 @@ export const command = async (conf) => {
         ...(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

@@ -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({

package/dist/commands/query.js

@@ -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({

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>;