nx 23.0.0-beta.2 → 23.0.0-beta.20

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.d.ts

@@ -1,2 +1,3 @@
 #!/usr/bin/env node
+import '../src/utils/enable-compile-cache';
 import '../src/utils/perf-logging';

package/dist/bin/nx.js

@@ -8,6 +8,8 @@ if (process.env.FORCE_COLOR === '0') {
     process.env.NO_COLOR = '1';
     delete process.env.FORCE_COLOR;
 }
+// Must be the first import — see enable-compile-cache.ts.
+require("../src/utils/enable-compile-cache");
 const find_workspace_root_1 = require("../src/utils/find-workspace-root");
 const pc = tslib_1.__importStar(require("picocolors"));
 const output_1 = require("../src/utils/output");
@@ -27,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();
     }
@@ -52,6 +76,8 @@ async function main() {
         process.argv[2] === '_migrate' ||
         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;
@@ -210,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/plugins/package-json.js

@@ -8,6 +8,7 @@ const cache_directory_1 = require("../src/utils/cache-directory");
 const path_1 = require("path");
 const fileutils_1 = require("../src/utils/fileutils");
 const plugin_cache_utils_1 = require("../src/utils/plugin-cache-utils");
+const package_manager_1 = require("../src/utils/package-manager");
 const cachePath = (0, path_1.join)(cache_directory_1.workspaceDataDirectory, 'package-json.hash');
 let packageJsonPluginCache = null;
 function readPackageJsonConfigurationCache() {
@@ -16,7 +17,7 @@ function readPackageJsonConfigurationCache() {
 }
 function writeCache() {
     if (packageJsonPluginCache) {
-        packageJsonPluginCache.writeToDisk(cachePath);
+        packageJsonPluginCache.writeToDisk();
     }
 }
 const plugin = {
@@ -27,7 +28,8 @@ const plugin = {
             const cache = readPackageJsonConfigurationCache();
             const patterns = (0, package_json_1.buildPackageJsonPatterns)(context.workspaceRoot, (f) => (0, fileutils_1.readJsonFile)((0, path_1.join)(context.workspaceRoot, f)));
             const isInPackageJsonWorkspaces = (0, package_json_1.buildPackageJsonWorkspacesMatcher)(patterns);
-            const result = (0, plugins_1.createNodesFromFiles)((packageJsonPath) => (0, package_json_1.createNodeFromPackageJson)(packageJsonPath, workspace_root_1.workspaceRoot, cache, isInPackageJsonWorkspaces(packageJsonPath)), configFiles, options, context);
+            const packageManagerCommand = (0, package_manager_1.getPackageManagerCommand)((0, package_manager_1.detectPackageManager)(context.workspaceRoot), context.workspaceRoot);
+            const result = (0, plugins_1.createNodesFromFiles)((packageJsonPath) => (0, package_json_1.createNodeFromPackageJson)(packageJsonPath, workspace_root_1.workspaceRoot, cache, isInPackageJsonWorkspaces(packageJsonPath), packageManagerCommand), configFiles, options, context);
             writeCache();
             return result;
         },

package/dist/src/adapter/ngcli-adapter.d.ts

@@ -3,7 +3,7 @@ import { FileBuffer } from '@angular-devkit/core/src/virtual-fs/host/interface';
 import { Observable } from 'rxjs';
 import type { GenerateOptions } from '../command-line/generate/generate';
 import { ProjectConfiguration } from '../config/workspace-json-project-json';
-import { Tree } from '../generators/tree';
+import { FileChange, Tree } from '../generators/tree';
 import type { ProjectGraph } from '../config/project-graph';
 import { ExecutorContext, GeneratorCallback } from '../config/misc-interfaces';
 export declare function createBuilderContext(builderInfo: {
@@ -59,6 +59,7 @@ export declare class NxScopeHostUsedForWrappedSchematics extends NxScopedHost {
 export declare function generate(root: string, opts: GenerateOptions, projects: Record<string, ProjectConfiguration>, verbose: boolean, projectGraph: ProjectGraph): Promise<number>;
 export declare function runMigration(root: string, packageName: string, migrationName: string, projects: Record<string, ProjectConfiguration>, isVerbose: boolean, projectGraph: ProjectGraph): Promise<{
     loggingQueue: string[];
+    changes: FileChange[];
     madeChanges: boolean;
 }>;
 /**

package/dist/src/adapter/ngcli-adapter.js

@@ -239,20 +239,38 @@ async function createRecorder(host, record, logger) {
         }
         else if (event.kind === 'update') {
             record.loggingQueue.push(core_1.tags.oneLine `${pc.white('UPDATE')} ${eventPath}`);
+            record.changes?.push(emptyFileChange('UPDATE', eventPath));
         }
         else if (event.kind === 'create') {
             record.loggingQueue.push(core_1.tags.oneLine `${pc.green('CREATE')} ${eventPath}`);
+            record.changes?.push(emptyFileChange('CREATE', eventPath));
         }
         else if (event.kind === 'delete') {
             record.loggingQueue.push(`${pc.yellow('DELETE')} ${eventPath}`);
+            record.changes?.push({ type: 'DELETE', path: eventPath, content: null });
         }
         else if (event.kind === 'rename') {
             record.loggingQueue.push(`${pc.blue('RENAME')} ${eventPath} => ${event.to}`);
+            // Surface as DELETE source + CREATE destination so downstream consumers
+            // (e.g. the agentic validation prompt's `<files_changed>` block) see
+            // both endpoints.
+            const toPath = event.to.startsWith('/') ? event.to.slice(1) : event.to;
+            record.changes?.push({ type: 'DELETE', path: eventPath, content: null });
+            record.changes?.push(emptyFileChange('CREATE', toPath));
         }
     };
 }
+// Empty content for non-DELETE FileChange entries: the Angular workflow has
+// already flushed bytes to disk, and our only downstream consumer (agentic
+// prompt builders) reads `path` + `type` only. `null` is reserved for DELETE.
+function emptyFileChange(type, path) {
+    return { type, path, content: Buffer.alloc(0) };
+}
 async function runSchematic(host, root, workflow, logger, opts, schematic, printDryRunMessage = true, recorder = null) {
-    const record = { loggingQueue: [], error: false };
+    const record = {
+        loggingQueue: [],
+        error: false,
+    };
     workflow.reporter.subscribe(recorder || (await createRecorder(host, record, logger)));
     try {
         await workflow
@@ -643,7 +661,11 @@ async function runMigration(root, packageName, migrationName, projects, isVerbos
     const fsHost = new NxScopeHostUsedForWrappedSchematics(root, new tree_1.FsTree(root, isVerbose, `ng-cli migration: ${packageName}:${migrationName}`), projectGraph);
     const workflow = createWorkflow(fsHost, root, {}, projects);
     const collection = resolveMigrationsCollection(packageName);
-    const record = { loggingQueue: [], error: false };
+    const record = {
+        loggingQueue: [],
+        changes: [],
+        error: false,
+    };
     workflow.reporter.subscribe(await createRecorder(fsHost, record, logger));
     await workflow
         .execute({
@@ -656,6 +678,7 @@ async function runMigration(root, packageName, migrationName, projects, isVerbos
         .toPromise();
     return {
         loggingQueue: record.loggingQueue,
+        changes: record.changes,
         madeChanges: record.loggingQueue.length > 0,
     };
 }

package/dist/src/ai/clone-ai-config-repo.js

@@ -125,14 +125,31 @@ function cleanupOldCaches(currentCommitHash) {
 function getAiConfigRepoPath() {
     // 1. Get latest commit hash (first 10 chars)
     const commitHash = getLatestCommitHash();
-    // 2. Check if cached version exists
+    // 2. Reuse cached version if it still has content (macOS may have
+    // swept its files but left the directory tree).
     const cachedPath = (0, path_1.join)(CACHE_DIR, commitHash);
-    if ((0, fs_1.existsSync)(cachedPath)) {
+    if (hasRootFile(cachedPath)) {
         return cachedPath;
     }
-    // 3. Clone fresh
+    // 3. Wipe any empty skeleton, then clone fresh
+    if ((0, fs_1.existsSync)(cachedPath)) {
+        (0, fs_1.rmSync)(cachedPath, { recursive: true, force: true });
+    }
     cloneRepo(cachedPath);
     // 4. Clean up old cached versions
     cleanupOldCaches(commitHash);
     return cachedPath;
 }
+/**
+ * The repo always has at least one regular file at its root (e.g. README).
+ * If everything at the root is a directory, the cache was swept by macOS
+ * tmp cleanup and we should re-clone.
+ */
+function hasRootFile(dir) {
+    try {
+        return (0, fs_1.readdirSync)(dir, { withFileTypes: true }).some((e) => e.isFile());
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/analytics/analytics.js

@@ -16,6 +16,7 @@ const native_1 = require("../native");
 const package_manager_1 = require("../utils/package-manager");
 const semver_1 = require("semver");
 const os = tslib_1.__importStar(require("os"));
+const crypto_1 = require("crypto");
 const machine_id_cache_1 = require("../utils/machine-id-cache");
 const is_ci_1 = require("../utils/is-ci");
 const analytics_prompt_1 = require("../utils/analytics-prompt");
@@ -56,7 +57,7 @@ async function startAnalytics() {
         return;
     }
     const isNxCloud = !!(nxJson?.nxCloudId ?? nxJson?.nxCloudAccessToken);
-    const userId = await (0, machine_id_cache_1.getCurrentMachineId)();
+    const userId = await getTelemetryUserId(workspaceId);
     const packageManagerInfo = getPackageManagerInfo();
     const nodeVersion = (0, semver_1.parse)(process.version);
     const nodeVersionString = nodeVersion
@@ -225,3 +226,11 @@ function isAnalyticsEnabled() {
     const nxJson = (0, nx_json_1.readNxJson)(workspace_root_1.workspaceRoot);
     return nxJson?.analytics === true;
 }
+// Mix workspace id in: shared Docker images (Gitpod, Cypress, etc.) bake
+// in /etc/machine-id, so machine-id alone collapses many users into one.
+async function getTelemetryUserId(workspaceId) {
+    const machineId = await (0, machine_id_cache_1.getCurrentMachineId)();
+    return (0, crypto_1.createHash)('sha256')
+        .update(`${machineId}|${workspaceId}`)
+        .digest('hex');
+}

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