nx 23.0.0-beta.17 → 23.0.0-beta.19

package/dist/bin/init-local.js

@@ -30,13 +30,18 @@ async function initLocal(workspace) {
             handleAngularCLIFallbacks(workspace);
             return;
         }
-        // Ensure NxConsole is installed if the user has it configured.
-        try {
-            await ensureNxConsoleInstalledViaDaemon();
+        // Skip per-TAB shell completion calls — those must not spawn the daemon.
+        if (!process.env.NX_COMPLETE) {
+            try {
+                await ensureNxConsoleInstalledViaDaemon();
+            }
+            catch { }
         }
-        catch { }
         const command = process.argv[2];
-        if (command === 'run' || command === 'g' || command === 'generate') {
+        if (command === 'completion' ||
+            command === 'run' ||
+            command === 'g' ||
+            command === 'generate') {
             nx_commands_1.commandsObject.parse(process.argv.slice(2));
         }
         else if (isKnownCommand(command)) {
@@ -110,14 +115,7 @@ function isKnownCommand(command) {
 }
 function shouldDelegateToAngularCLI() {
     const command = process.argv[2];
-    const commands = [
-        'analytics',
-        'cache',
-        'completion',
-        'config',
-        'doc',
-        'update',
-    ];
+    const commands = ['analytics', 'cache', 'config', 'doc', 'update'];
     return commands.indexOf(command) > -1;
 }
 async function ensureNxConsoleInstalledViaDaemon() {
@@ -169,13 +167,6 @@ function handleAngularCLIFallbacks(workspace) {
         console.log(`Running "ng update" can still be useful in some dev workflows, so we aren't planning to remove it.`);
         console.log(`If you need to use it, run "FORCE_NG_UPDATE=true ng update".`);
     }
-    else if (process.argv[2] === 'completion') {
-        if (!process.argv[3]) {
-            console.log(`"ng completion" is not natively supported by Nx.
-  Instead, you could try an Nx Editor Plugin for a visual tool to run Nx commands. If you're using VSCode, you can use the Nx Console plugin, or if you're using WebStorm, you could use one of the available community plugins.
-  For more information, see https://nx.dev/getting-started/editor-setup`);
-        }
-    }
     else if (process.argv[2] === 'cache') {
         console.log(`"ng cache" is not natively supported by Nx.
 To clear the cache, you can delete the ".angular/cache" directory (or the directory configured by "cli.cache.path" in the "nx.json" file).

package/dist/bin/nx.js

@@ -29,10 +29,32 @@ require("../src/utils/perf-logging");
 const isTsExt = (0, path_1.extname)(__filename).endsWith('.ts');
 const pathToPkgJson = isTsExt ? '../package.json' : '../../package.json';
 async function main() {
+    // Tab-completion fast path. Bare env-var read so nothing runs before
+    // the try/catch — a throw here would splice a stack trace into the
+    // user's command line.
+    if (process.env.NX_COMPLETE) {
+        try {
+            perf_hooks_1.performance.mark('init-local');
+            const { tryValueCompletion } = await import('nx/src/command-line/completion/value-completions');
+            if (tryValueCompletion())
+                return;
+            const { tryCommandSurfaceCompletion } = await import('nx/src/command-line/completion/command-completions');
+            tryCommandSurfaceCompletion();
+        }
+        catch (e) {
+            // Swallow: a broken completion must produce no suggestions, not a
+            // stack trace. NX_VERBOSE_LOGGING surfaces the cause to stderr.
+            if (process.env.NX_VERBOSE_LOGGING) {
+                console.error(e);
+            }
+        }
+        return;
+    }
     if (process.argv[2] !== 'report' &&
         process.argv[2] !== '--version' &&
         process.argv[2] !== '--help' &&
-        process.argv[2] !== 'reset') {
+        process.argv[2] !== 'reset' &&
+        process.argv[2] !== 'completion') {
         const { assertSupportedPlatform } = await import('../src/native/assert-supported-platform.js');
         assertSupportedPlatform();
     }
@@ -55,6 +77,7 @@ async function main() {
         process.argv[2] === 'init' ||
         process.argv[2] === 'configure-ai-agents' ||
         process.argv[2] === 'mcp' ||
+        process.argv[2] === 'completion' ||
         (process.argv[2] === 'graph' && !workspace)) {
         process.env.NX_DAEMON = 'false';
         (await import('nx/src/command-line/nx-commands')).commandsObject.argv;
@@ -213,7 +236,7 @@ function handleMissingLocalInstallation(detectedWorkspaceRoot) {
  * Warns if out of date by 1 major version or more.
  */
 function warnIfUsingOutdatedGlobalInstall(globalNxVersion, localNxVersion) {
-    // Never display this warning if Nx is already running via Nx
+    // Skip when Nx is recursively invoking itself.
     if (process.env.NX_CLI_SET) {
         return;
     }

package/dist/src/command-line/add/completion.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/command-line/add/completion.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const metadata_1 = require("../completion/metadata");
+const nx_package_group_1 = require("../../utils/nx-package-group");
+// Same list `nx report` uses. Filter to first-party plugins and sort.
+const FIRST_PARTY_PLUGINS = (0, nx_package_group_1.readNxPackageGroup)()
+    .filter((p) => p.startsWith('@nx/'))
+    .sort();
+(0, metadata_1.registerCompletion)('add', {
+    positionals: [
+        {
+            complete: (current) => FIRST_PARTY_PLUGINS.filter((p) => p.startsWith(current)),
+        },
+    ],
+});

package/dist/src/command-line/affected/completion.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/command-line/affected/completion.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const metadata_1 = require("../completion/metadata");
+const completion_providers_1 = require("../completion/completion-providers");
+// Aliases are written out; the fast path runs before yargs can resolve them.
+(0, metadata_1.registerCompletion)('affected', {
+    flags: {
+        projects: completion_providers_1.getProjectNameCompletions,
+        p: completion_providers_1.getProjectNameCompletions,
+        exclude: completion_providers_1.getProjectNameCompletions,
+        targets: completion_providers_1.getTargetNameCompletions,
+        target: completion_providers_1.getTargetNameCompletions,
+        t: completion_providers_1.getTargetNameCompletions,
+    },
+});

package/dist/src/command-line/completion/argv-layout.d.ts

@@ -0,0 +1,6 @@
+export interface ParsedCompletionArgs {
+    tokens: string[];
+    current: string;
+    previousToken: string;
+}
+export declare function parseCompletionArgs(argv?: readonly string[]): ParsedCompletionArgs | null;

package/dist/src/command-line/completion/argv-layout.js

@@ -0,0 +1,19 @@
+"use strict";
+// Wrappers must invoke nx with argv: [node, nx-bin, ...tokens, currentPartial].
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCompletionArgs = parseCompletionArgs;
+function parseCompletionArgs(argv = process.argv) {
+    const tail = argv.slice(2);
+    // Wrappers usually prepend the literal 'nx' (from COMP_WORDS /
+    // commandline -cop / etc.). They sometimes don't — most notably the
+    // `.nx/installation` wrapper invokes the real bin directly without the
+    // 'nx' token, and manual invocations like `NX_COMPLETE=fish nx show
+    // target in` for dev testing skip it too. Strip when present, otherwise
+    // take the args as-is.
+    const tokens = tail[0] === 'nx' ? tail.slice(1) : tail;
+    if (tokens.length === 0)
+        return null;
+    const current = tokens[tokens.length - 1] ?? '';
+    const previousToken = tokens.length >= 2 ? tokens[tokens.length - 2] : '';
+    return { tokens, current, previousToken };
+}

package/dist/src/command-line/completion/command-completions.d.ts

@@ -0,0 +1,19 @@
+/** Slow-path entry point. Returns true if anything was emitted. */
+export declare function tryCommandSurfaceCompletion(argv?: readonly string[]): boolean;
+/** Top-level command names. Unions yargs handlers with the completion
+ *  registry's single-token paths (infix targets). */
+export declare function getTopLevelCommands(current: string, withDesc: boolean): string[] | null;
+/**
+ * Enumerates subcommands + options of a matched top-level command. Returns
+ * null when no top-level command name is matched in `args`.
+ */
+export declare function getCommandCompletions(current: string, args: string[]): string[] | null;
+/** value\tdescription separator. TAB because completion values can contain
+ *  colons (`my-app:build`); descriptions get TABs collapsed. */
+export declare const DESC_SEPARATOR = "\t";
+/** Strip the y18n marker yargs prepends to its built-in --help / --version
+ *  descriptions, and collapse stray TABs so they can't forge the
+ *  value/description separator. */
+export declare function formatDescription(raw: string | undefined): string;
+/** zsh (compadd -d) and fish (complete -a) parse `value\tdescription`. */
+export declare function shellRendersDescriptions(): boolean;

package/dist/src/command-line/completion/command-completions.js

@@ -0,0 +1,120 @@
+"use strict";
+// Slow-path completion: command/subcommand/flag names. Runs after
+// tryValueCompletion has nothing to offer.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DESC_SEPARATOR = void 0;
+exports.tryCommandSurfaceCompletion = tryCommandSurfaceCompletion;
+exports.getTopLevelCommands = getTopLevelCommands;
+exports.getCommandCompletions = getCommandCompletions;
+exports.formatDescription = formatDescription;
+exports.shellRendersDescriptions = shellRendersDescriptions;
+const trigger_1 = require("./trigger");
+const argv_layout_1 = require("./argv-layout");
+const metadata_1 = require("./metadata");
+const command_handlers_1 = require("./command-handlers");
+/** Slow-path entry point. Returns true if anything was emitted. */
+function tryCommandSurfaceCompletion(argv = process.argv) {
+    const parsed = (0, argv_layout_1.parseCompletionArgs)(argv);
+    if (parsed === null)
+        return false;
+    const matched = getCommandCompletions(parsed.current, parsed.tokens);
+    const completions = matched !== null
+        ? matched
+        : getTopLevelCommands(parsed.current, shellRendersDescriptions());
+    if (completions === null || completions.length === 0)
+        return false;
+    for (const line of completions) {
+        console.log(line);
+    }
+    return true;
+}
+/** Top-level command names. Unions yargs handlers with the completion
+ *  registry's single-token paths (infix targets). */
+function getTopLevelCommands(current, withDesc) {
+    const handlers = (0, command_handlers_1.getNxCommandHandlers)();
+    const seen = new Set();
+    const completions = [];
+    for (const name of Object.keys(handlers)) {
+        if (name === '$0' || name.startsWith('_'))
+            continue;
+        if (current && !name.startsWith(current))
+            continue;
+        const handler = handlers[name];
+        if (handler?.description === false)
+            continue; // hidden
+        seen.add(name);
+        const desc = withDesc ? formatDescription(handler?.description) : '';
+        completions.push(desc ? `${name}${exports.DESC_SEPARATOR}${desc}` : name);
+    }
+    // Infix targets + any other top-level completion-only paths.
+    for (const name of (0, metadata_1.getRegisteredTopLevelPaths)()) {
+        if (seen.has(name))
+            continue;
+        if (current && !name.startsWith(current))
+            continue;
+        seen.add(name);
+        completions.push(name);
+    }
+    return completions;
+}
+/**
+ * Enumerates subcommands + options of a matched top-level command. Returns
+ * null when no top-level command name is matched in `args`.
+ */
+function getCommandCompletions(current, args) {
+    const handlers = (0, command_handlers_1.getNxCommandHandlers)();
+    const cmdName = args.find((a) => handlers[a]);
+    if (!cmdName) {
+        return null;
+    }
+    const handler = handlers[cmdName];
+    // Once we recognize a top-level command in `args`, we own the slot —
+    // return [] (not null) for the "found a command but can't enumerate its
+    // surface" case so the caller doesn't fall back to top-level commands
+    // (which would mis-offer e.g. `exec` for `nx g c ex`).
+    if (typeof handler.builder !== 'function') {
+        return [];
+    }
+    const intro = (0, command_handlers_1.introspectBuilder)(handler.builder);
+    if (!intro)
+        return [];
+    const completions = [];
+    const isFlagPrefix = current.startsWith('-');
+    const withDesc = shellRendersDescriptions();
+    if (!isFlagPrefix) {
+        for (const [name, desc] of intro.subcommands) {
+            const formatted = withDesc ? formatDescription(desc) : '';
+            completions.push(formatted ? `${name}${exports.DESC_SEPARATOR}${formatted}` : name);
+        }
+    }
+    for (const [name, desc] of intro.options) {
+        const formatted = withDesc ? formatDescription(desc) : '';
+        completions.push(formatted ? `--${name}${exports.DESC_SEPARATOR}${formatted}` : `--${name}`);
+    }
+    if (!current) {
+        return completions;
+    }
+    const flagName = current.replace(/^-+/, '');
+    return completions.filter((c) => {
+        if (isFlagPrefix) {
+            return c.startsWith(`--${flagName}`);
+        }
+        return c.startsWith(current);
+    });
+}
+/** value\tdescription separator. TAB because completion values can contain
+ *  colons (`my-app:build`); descriptions get TABs collapsed. */
+exports.DESC_SEPARATOR = '\t';
+/** Strip the y18n marker yargs prepends to its built-in --help / --version
+ *  descriptions, and collapse stray TABs so they can't forge the
+ *  value/description separator. */
+function formatDescription(raw) {
+    if (!raw)
+        return '';
+    return raw.replace(/^__yargsString__:/, '').replace(/\t/g, ' ');
+}
+/** zsh (compadd -d) and fish (complete -a) parse `value\tdescription`. */
+function shellRendersDescriptions() {
+    const shell = (0, trigger_1.getCompletionShell)();
+    return shell === 'zsh' || shell === 'fish';
+}

package/dist/src/command-line/completion/command-handlers.d.ts

@@ -0,0 +1,30 @@
+/** A single entry from yargs' `getCommandHandlers()`. */
+export interface CommandHandler {
+    description?: string | false;
+    builder?: (yargs: any) => any;
+}
+export type CommandHandlers = Record<string, CommandHandler>;
+/**
+ * Reach into the yargs commandsObject to enumerate registered command
+ * handlers. Lazy-required: nx-commands pulls in the full command tree
+ * and is only needed on the slow path.
+ *
+ * Yargs only keys handlers by canonical name. We mirror each alias to its
+ * canonical handler reference so lookups like `handlers['g']` resolve to
+ * the same entry as `handlers['generate']`.
+ */
+export declare function getNxCommandHandlers(): CommandHandlers;
+/** Subcommand name → description, visible-option name → description, and
+ *  canonical option name → its yargs-declared aliases (e.g. projects → [p]). */
+export interface BuilderIntrospection {
+    subcommands: Map<string, string | undefined>;
+    options: Map<string, string | undefined>;
+    aliases: Map<string, string[]>;
+}
+/**
+ * Run a yargs builder against a throwaway instance and return its declared
+ * subcommands, visible options, and option-alias groups. Returns null if
+ * the builder throws. Does NOT call `.argv` — would trigger parse and the
+ * help-printing path we're avoiding.
+ */
+export declare function introspectBuilder(builder: (yargs: any) => any): BuilderIntrospection | null;

package/dist/src/command-line/completion/command-handlers.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNxCommandHandlers = getNxCommandHandlers;
+exports.introspectBuilder = introspectBuilder;
+/**
+ * Reach into the yargs commandsObject to enumerate registered command
+ * handlers. Lazy-required: nx-commands pulls in the full command tree
+ * and is only needed on the slow path.
+ *
+ * Yargs only keys handlers by canonical name. We mirror each alias to its
+ * canonical handler reference so lookups like `handlers['g']` resolve to
+ * the same entry as `handlers['generate']`.
+ */
+function getNxCommandHandlers() {
+    const { commandsObject } = require('../nx-commands');
+    const internal = commandsObject.getInternalMethods();
+    const handlers = { ...internal.getCommandInstance().getCommandHandlers() };
+    for (const row of internal.getUsageInstance().getCommands()) {
+        // usage.getCommands() rows: [usagePattern, description, isDefault, aliases, deprecated]
+        const usagePattern = String(row[0] ?? '');
+        const aliases = Array.isArray(row[3]) ? row[3] : [];
+        const canonical = usagePattern.split(/\s+/)[0];
+        const handler = handlers[canonical];
+        if (!handler)
+            continue;
+        for (const alias of aliases) {
+            if (!handlers[alias])
+                handlers[alias] = handler;
+        }
+    }
+    return handlers;
+}
+/**
+ * Run a yargs builder against a throwaway instance and return its declared
+ * subcommands, visible options, and option-alias groups. Returns null if
+ * the builder throws. Does NOT call `.argv` — would trigger parse and the
+ * help-printing path we're avoiding.
+ */
+function introspectBuilder(builder) {
+    const yargs = require('yargs');
+    const temp = yargs();
+    try {
+        builder(temp);
+    }
+    catch {
+        return null;
+    }
+    const usage = temp.getInternalMethods().getUsageInstance();
+    const subcommands = new Map();
+    for (const [usagePattern, desc] of usage.getCommands()) {
+        const name = String(usagePattern).split(/\s+/)[0];
+        if (name === '$0')
+            continue;
+        subcommands.set(name, desc);
+    }
+    const opts = temp.getOptions();
+    const descriptions = usage.getDescriptions();
+    const options = new Map();
+    for (const k of Object.keys(opts.key ?? {})) {
+        if ((opts.hiddenOptions ?? []).includes(k))
+            continue;
+        options.set(k, descriptions[k]);
+    }
+    const aliases = new Map();
+    for (const [canonical, list] of Object.entries(opts.alias ?? {})) {
+        aliases.set(canonical, list);
+    }
+    return { subcommands, options, aliases };
+}

package/dist/src/command-line/completion/command-object.d.ts

@@ -0,0 +1,10 @@
+import { CommandModule } from 'yargs';
+declare const SHELL_CHOICES: readonly ["bash", "zsh", "fish", "powershell"];
+type Shell = (typeof SHELL_CHOICES)[number];
+interface CompletionArgs {
+    shell?: Shell;
+    force?: boolean;
+    stdout?: boolean;
+}
+export declare const yargsCompletionCommand: CommandModule<{}, CompletionArgs>;
+export {};

package/dist/src/command-line/completion/command-object.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.yargsCompletionCommand = void 0;
+const enquirer_1 = require("enquirer");
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const handle_import_1 = require("../../utils/handle-import");
+const SHELL_CHOICES = ['bash', 'zsh', 'fish', 'powershell'];
+exports.yargsCompletionCommand = {
+    command: 'completion [shell]',
+    describe: 'Install shell completion for bash, zsh, fish, or powershell. Omit the shell to pick interactively.',
+    builder: (yargs) => yargs
+        .positional('shell', {
+        type: 'string',
+        choices: SHELL_CHOICES,
+        describe: 'Shell to install completion for.',
+    })
+        .option('force', {
+        type: 'boolean',
+        default: false,
+        describe: 'Install the completion script even if `nx` is not found on PATH.',
+    })
+        .option('stdout', {
+        type: 'boolean',
+        default: false,
+        describe: 'Print the completion script to stdout instead of writing to the shell rc file.',
+    })
+        .example('$0 completion bash', 'Install bash completion to ~/.bashrc')
+        .example('$0 completion', 'Pick shells interactively and install completion for each')
+        .example('$0 completion bash --stdout >> ~/.bash_profile', 'Print to stdout for a custom rc location'),
+    handler: async (args) => {
+        const scripts = await (0, handle_import_1.handleImport)('./scripts.js', __dirname);
+        const shells = args.shell ? [args.shell] : await pickShellsInteractively();
+        if (shells.length === 0) {
+            console.warn('nx: no shells selected — nothing installed.');
+            process.exit(0);
+        }
+        if (args.stdout && shells.length > 1) {
+            console.warn('nx: --stdout only makes sense with one shell — concatenating two wrapper scripts to stdout is never useful.');
+            process.exit(1);
+        }
+        const emit = args.stdout
+            ? scripts.printCompletionScript
+            : scripts.installCompletionScript;
+        // Fire the PATH-advisory once, before any per-shell emit.
+        if (!args.force)
+            scripts.maybeWarnNxNotOnPath();
+        for (const shell of shells)
+            emit(shell);
+        process.exit(0);
+    },
+};
+async function pickShellsInteractively() {
+    if (!process.stdin.isTTY || !process.stderr.isTTY) {
+        console.warn('nx: please specify a shell — `nx completion <bash|zsh|fish|powershell>`.');
+        process.exit(1);
+    }
+    const detected = detectAvailableShells();
+    const answer = (await (0, enquirer_1.prompt)({
+        type: 'multiselect',
+        name: 'shells',
+        message: 'Install nx completion for which shell(s)?',
+        choices: SHELL_CHOICES.map((name) => ({
+            name,
+            value: name,
+            // Pre-check shells we can detect on this machine.
+            enabled: detected.has(name),
+        })),
+    }));
+    return answer.shells ?? [];
+}
+/** Best-effort detect-which-shells-the-user-has. Pre-checks the multiselect.
+ *  Signals: $SHELL basename, presence of conventional rc files, $PSModulePath
+ *  for PowerShell. False positives are fine — the user can uncheck. */
+function detectAvailableShells() {
+    const found = new Set();
+    const home = (0, os_1.homedir)();
+    const shellEnv = (process.env.SHELL ?? '').replace(/\\/g, '/');
+    const shellName = shellEnv.split('/').pop() ?? '';
+    if (shellName === 'bash' || (0, fs_1.existsSync)((0, path_1.join)(home, '.bashrc'))) {
+        found.add('bash');
+    }
+    if (shellName === 'zsh' || (0, fs_1.existsSync)((0, path_1.join)(home, '.zshrc'))) {
+        found.add('zsh');
+    }
+    if (shellName === 'fish' ||
+        (0, fs_1.existsSync)((0, path_1.join)(home, '.config', 'fish', 'config.fish'))) {
+        found.add('fish');
+    }
+    if (process.env.PSModulePath || process.platform === 'win32') {
+        found.add('powershell');
+    }
+    return found;
+}

package/dist/src/command-line/completion/completion-providers.d.ts

@@ -0,0 +1,21 @@
+/** Project names matching `current`. */
+export declare function getProjectNameCompletions(current: string): string[];
+/** Projects that declare `targetName`, matching `current`. */
+export declare function getProjectNamesWithTarget(current: string, targetName: string): string[];
+/** Two-stage `project[:target]` — stage 1 emits `project:` (nospace), stage 2 emits `project:target`. */
+export declare function completeProjectTarget(current: string): string[];
+/** Generator completion. Stage 1 (`nx g <TAB>`) emits plugin names (with `:`)
+ *  and bare generator names (for `nx g application`); stage 2 emits
+ *  `plugin:generator`. */
+export declare function completeGenerator(current: string): string[];
+/** Plugin names matching `current` — installed npm plugins + workspace-local
+ *  plugin projects, only those declaring a generator collection. */
+export declare function getGeneratorPluginCompletions(current: string): string[];
+/** Generator names in a single plugin, matching `current`. */
+export declare function getGeneratorsForPlugin(pluginName: string, current: string): string[];
+/** Unique target names across the workspace, matching `current`. */
+export declare function getTargetNameCompletions(current: string): string[];
+/** Target names for a single project, matching `current`. Falls back to
+ *  workspace-wide if the project isn't in the graph — covers the
+ *  `project:t<TAB>` case where the user is still typing the project name. */
+export declare function getTargetNamesForProject(current: string, projectName: string): string[];