nx 20.8.4 → 22.7.7

package/dist/src/command-line/import/utils/ai-output.d.ts

@@ -0,0 +1,93 @@
+/**
+ * AI Agent NDJSON Output Utilities for nx import
+ *
+ * Extends the shared base with import-specific types and builders.
+ */
+import { writeAiOutput, logProgress, writeErrorLog, type DetectedPlugin, type UserNextSteps } from '../../ai/ai-output';
+export { writeAiOutput, logProgress, writeErrorLog };
+export type ImportProgressStage = 'starting' | 'cloning' | 'filtering' | 'merging' | 'detecting-plugins' | 'installing' | 'installing-plugins' | 'complete' | 'error' | 'needs_input';
+export type NxImportErrorCode = 'UNCOMMITTED_CHANGES' | 'CLONE_FAILED' | 'SOURCE_NOT_FOUND' | 'DESTINATION_NOT_EMPTY' | 'INVALID_DESTINATION' | 'FILTER_FAILED' | 'MERGE_FAILED' | 'PACKAGE_INSTALL_ERROR' | 'PLUGIN_INIT_ERROR' | 'UNKNOWN';
+interface ImportOptionInfo {
+    description: string;
+    flag: string;
+    required: boolean;
+}
+export interface ImportNeedsOptionsResult {
+    stage: 'needs_input';
+    success: false;
+    inputType: 'import_options';
+    message: string;
+    missingFields: string[];
+    availableOptions: Record<string, ImportOptionInfo>;
+    exampleCommand: string;
+}
+export interface ImportNeedsPluginSelectionResult {
+    stage: 'needs_input';
+    success: false;
+    inputType: 'plugins';
+    message: string;
+    detectedPlugins: DetectedPlugin[];
+    options: string[];
+    recommendedOption: string;
+    recommendedReason: string;
+    exampleCommand: string;
+    result: {
+        sourceRepository: string;
+        ref: string;
+        source: string;
+        destination: string;
+    };
+}
+export interface ImportSuccessResult {
+    stage: 'complete';
+    success: true;
+    result: {
+        sourceRepository: string;
+        ref: string;
+        source: string;
+        destination: string;
+        pluginsInstalled: string[];
+    };
+    warnings?: ImportWarning[];
+    userNextSteps: UserNextSteps;
+    docs: {
+        gettingStarted: string;
+        nxImport: string;
+    };
+}
+export interface ImportWarning {
+    type: 'package_manager_mismatch' | 'config_path_mismatch' | 'missing_root_deps' | 'install_failed' | 'plugin_install_failed';
+    message: string;
+    hint: string;
+}
+export interface ImportErrorResult {
+    stage: 'error';
+    success: false;
+    errorCode: NxImportErrorCode;
+    error: string;
+    hints: string[];
+    errorLogPath?: string;
+}
+export type ImportAiOutputMessage = {
+    stage: ImportProgressStage;
+    message: string;
+} | ImportNeedsOptionsResult | ImportNeedsPluginSelectionResult | ImportSuccessResult | ImportErrorResult;
+export declare function buildImportNeedsOptionsResult(missingFields: string[], sourceRepository?: string): ImportNeedsOptionsResult;
+export declare function buildImportNeedsPluginSelectionResult(options: {
+    detectedPlugins: DetectedPlugin[];
+    sourceRepository: string;
+    ref: string;
+    source: string;
+    destination: string;
+}): ImportNeedsPluginSelectionResult;
+export declare function buildImportSuccessResult(options: {
+    sourceRepository: string;
+    ref: string;
+    source: string;
+    destination: string;
+    pluginsInstalled: string[];
+    warnings?: ImportWarning[];
+}): ImportSuccessResult;
+export declare function buildImportErrorResult(error: string, errorCode: NxImportErrorCode, errorLogPath?: string): ImportErrorResult;
+export declare function getImportErrorHints(errorCode: NxImportErrorCode): string[];
+export declare function determineImportErrorCode(error: Error | unknown): NxImportErrorCode;

package/dist/src/command-line/import/utils/ai-output.js

@@ -0,0 +1,209 @@
+"use strict";
+/**
+ * AI Agent NDJSON Output Utilities for nx import
+ *
+ * Extends the shared base with import-specific types and builders.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeErrorLog = exports.logProgress = exports.writeAiOutput = void 0;
+exports.buildImportNeedsOptionsResult = buildImportNeedsOptionsResult;
+exports.buildImportNeedsPluginSelectionResult = buildImportNeedsPluginSelectionResult;
+exports.buildImportSuccessResult = buildImportSuccessResult;
+exports.buildImportErrorResult = buildImportErrorResult;
+exports.getImportErrorHints = getImportErrorHints;
+exports.determineImportErrorCode = determineImportErrorCode;
+const ai_output_1 = require("../../ai/ai-output");
+Object.defineProperty(exports, "writeAiOutput", { enumerable: true, get: function () { return ai_output_1.writeAiOutput; } });
+Object.defineProperty(exports, "logProgress", { enumerable: true, get: function () { return ai_output_1.logProgress; } });
+Object.defineProperty(exports, "writeErrorLog", { enumerable: true, get: function () { return ai_output_1.writeErrorLog; } });
+const AVAILABLE_OPTIONS = {
+    sourceRepository: {
+        description: 'URL or path of the repository to import.',
+        flag: '--sourceRepository',
+        required: true,
+    },
+    ref: {
+        description: 'Branch to import from the source repository.',
+        flag: '--ref',
+        required: true,
+    },
+    source: {
+        description: 'Directory within the source repo to import (blank = entire repo).',
+        flag: '--source',
+        required: false,
+    },
+    destination: {
+        description: 'Target directory in this workspace to import into.',
+        flag: '--destination',
+        required: true,
+    },
+};
+function buildImportNeedsOptionsResult(missingFields, sourceRepository) {
+    const exampleRepo = sourceRepository || 'https://github.com/org/repo';
+    return {
+        stage: 'needs_input',
+        success: false,
+        inputType: 'import_options',
+        message: 'Required options missing. Re-invoke with the listed flags.',
+        missingFields,
+        availableOptions: AVAILABLE_OPTIONS,
+        exampleCommand: `nx import ${exampleRepo} --ref=main --source=apps/my-app --destination=apps/my-app`,
+    };
+}
+function buildImportNeedsPluginSelectionResult(options) {
+    const pluginList = options.detectedPlugins.map((p) => p.name).join(',');
+    return {
+        stage: 'needs_input',
+        success: false,
+        inputType: 'plugins',
+        message: 'Import complete. Plugin selection required. Ask the user which plugins to install, then run again with --plugins flag.',
+        detectedPlugins: options.detectedPlugins,
+        options: ['--plugins=skip', '--plugins=all', `--plugins=${pluginList}`],
+        recommendedOption: '--plugins=all',
+        recommendedReason: 'Installing all detected plugins ensures the imported project works correctly with Nx.',
+        exampleCommand: `nx import ${options.sourceRepository} ${options.destination} --ref=${options.ref} --source=${options.source} --plugins=${options.detectedPlugins[0]?.name || '@nx/vite'}`,
+        result: {
+            sourceRepository: options.sourceRepository,
+            ref: options.ref,
+            source: options.source,
+            destination: options.destination,
+        },
+    };
+}
+function buildImportSuccessResult(options) {
+    const steps = [
+        {
+            title: 'Explore your workspace',
+            command: 'nx graph',
+            note: 'Visualize project dependencies including imported projects',
+        },
+        {
+            title: 'List imported projects',
+            command: 'nx show projects',
+            note: 'Verify the imported projects appear in the workspace',
+        },
+        {
+            title: 'Run a task on imported code',
+            command: `nx run <project>:<target>`,
+            note: 'Test that imported projects build and run correctly',
+        },
+    ];
+    const result = {
+        stage: 'complete',
+        success: true,
+        result: {
+            sourceRepository: options.sourceRepository,
+            ref: options.ref,
+            source: options.source,
+            destination: options.destination,
+            pluginsInstalled: options.pluginsInstalled,
+        },
+        userNextSteps: {
+            description: 'Show user these steps to verify the import.',
+            steps,
+        },
+        docs: {
+            gettingStarted: 'https://nx.dev/getting-started/intro',
+            nxImport: 'https://nx.dev/nx-api/nx/documents/import',
+        },
+    };
+    if (options.warnings && options.warnings.length > 0) {
+        result.warnings = options.warnings;
+    }
+    return result;
+}
+function buildImportErrorResult(error, errorCode, errorLogPath) {
+    return {
+        stage: 'error',
+        success: false,
+        errorCode,
+        error,
+        hints: getImportErrorHints(errorCode),
+        errorLogPath,
+    };
+}
+function getImportErrorHints(errorCode) {
+    switch (errorCode) {
+        case 'UNCOMMITTED_CHANGES':
+            return [
+                'Commit or stash your changes before running nx import',
+                'Run "git status" to see uncommitted changes',
+            ];
+        case 'CLONE_FAILED':
+            return [
+                'Check the repository URL is correct and accessible',
+                'Ensure you have the necessary permissions to clone',
+                'For local paths, verify the directory exists',
+            ];
+        case 'SOURCE_NOT_FOUND':
+            return [
+                'The specified source directory does not exist in the source repository',
+                'Check the directory path and branch name',
+                'Omit --source to import the entire repository',
+            ];
+        case 'DESTINATION_NOT_EMPTY':
+            return [
+                'The destination directory already contains files',
+                'Choose a different destination or remove existing files',
+            ];
+        case 'INVALID_DESTINATION':
+            return [
+                'The destination must be a relative path within the workspace',
+                'Do not use absolute paths',
+            ];
+        case 'FILTER_FAILED':
+            return [
+                'Git history filtering failed',
+                'Install git-filter-repo for faster and more reliable filtering: pip install git-filter-repo',
+                'Check that the source repository has valid git history',
+            ];
+        case 'MERGE_FAILED':
+            return [
+                'Merging the imported code failed',
+                'Check for conflicts between source and destination',
+                'Run "git status" to see the current state',
+            ];
+        case 'PACKAGE_INSTALL_ERROR':
+            return [
+                'Package installation failed after import',
+                'Run your package manager install manually',
+                'Check for dependency conflicts between imported and existing packages',
+            ];
+        case 'PLUGIN_INIT_ERROR':
+            return [
+                'One or more plugin initializations failed',
+                'Try running "nx add <plugin>" manually',
+            ];
+        default:
+            return [
+                'An unexpected error occurred during import',
+                'Check the error log for details',
+                'Report issues at https://github.com/nrwl/nx/issues',
+            ];
+    }
+}
+function determineImportErrorCode(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const lower = message.toLowerCase();
+    if (lower.includes('uncommitted'))
+        return 'UNCOMMITTED_CHANGES';
+    if (lower.includes('failed to clone'))
+        return 'CLONE_FAILED';
+    if (lower.includes('does not exist in'))
+        return 'SOURCE_NOT_FOUND';
+    if (lower.includes('is not empty') || lower.includes('destination directory'))
+        return 'DESTINATION_NOT_EMPTY';
+    if (lower.includes('must be a relative path'))
+        return 'INVALID_DESTINATION';
+    if (lower.includes('filter-repo') ||
+        lower.includes('filter-branch') ||
+        lower.includes('filter'))
+        return 'FILTER_FAILED';
+    if (lower.includes('merge'))
+        return 'MERGE_FAILED';
+    if (lower.includes('install'))
+        return 'PACKAGE_INSTALL_ERROR';
+    if (lower.includes('plugin') || lower.includes('generator'))
+        return 'PLUGIN_INIT_ERROR';
+    return 'UNKNOWN';
+}

package/dist/src/command-line/import/utils/merge-remote-source.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeRemoteSource = mergeRemoteSource;
+const createSpinner = require('ora');
+async function mergeRemoteSource(destinationGitClient, sourceRemoteUrl, tempBranch, destination, remoteName, branchName) {
+    const spinner = createSpinner();
+    spinner.start(`Merging ${branchName} from ${sourceRemoteUrl} into ${destination}`);
+    spinner.start(`Fetching ${tempBranch} from ${remoteName}`);
+    await destinationGitClient.fetch(remoteName, tempBranch);
+    spinner.succeed(`Fetched ${tempBranch} from ${remoteName}`);
+    spinner.start(`Merging files and git history from ${branchName} from ${sourceRemoteUrl} into ${destination}`);
+    await destinationGitClient.mergeUnrelatedHistories(`${remoteName}/${tempBranch}`, `feat(repo): merge ${branchName} from ${sourceRemoteUrl}`);
+    spinner.succeed(`Merged files and git history from ${branchName} from ${sourceRemoteUrl} into ${destination}`);
+}

package/dist/src/command-line/import/utils/prepare-source-repo.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareSourceRepo = prepareSourceRepo;
+const createSpinner = require('ora');
+const path_1 = require("path");
+async function prepareSourceRepo(gitClient, ref, source, relativeDestination, tempImportBranch, sourceRemoteUrl) {
+    const spinner = createSpinner().start(`Fetching ${ref} from ${sourceRemoteUrl}`);
+    const relativeSourceDir = (0, path_1.relative)(gitClient.root, (0, path_1.join)(gitClient.root, source));
+    const message = relativeSourceDir.trim()
+        ? `Filtering git history to only include files in ${relativeSourceDir}`
+        : `Filtering git history`;
+    if (await gitClient.hasFilterRepoInstalled()) {
+        spinner.start(message);
+        await gitClient.filterRepo(relativeSourceDir, relativeDestination);
+    }
+    else {
+        spinner.start(`${message} (this might take a few minutes -- install git-filter-repo for faster performance)`);
+        await gitClient.filterBranch(relativeSourceDir, relativeDestination, tempImportBranch);
+    }
+    spinner.succeed(relativeSourceDir.trim()
+        ? `Filtered git history to only include files in ${relativeSourceDir}`
+        : `Filtered git history`);
+    spinner.succeed(`${sourceRemoteUrl} has been prepared to be imported into this workspace on a temporary branch: ${tempImportBranch} in ${gitClient.root}`);
+}
+function wait(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/src/command-line/index.d.ts

@@ -0,0 +1,22 @@
+export * from './add/command-object';
+export * from './affected/command-object';
+export * from './daemon/command-object';
+export * from './exec/command-object';
+export * from './format/command-object';
+export * from './generate/command-object';
+export * from './graph/command-object';
+export * from './import/command-object';
+export * from './init/command-object';
+export * from './list/command-object';
+export * from './migrate/command-object';
+export * from './new/command-object';
+export * from './register/command-object';
+export * from './release/command-object';
+export * from './repair/command-object';
+export * from './report/command-object';
+export * from './reset/command-object';
+export * from './run-many/command-object';
+export * from './run/command-object';
+export * from './show/command-object';
+export * from './sync/command-object';
+export * from './watch/command-object';

package/dist/src/command-line/index.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+// CLI Commands Export File for Documentation
+tslib_1.__exportStar(require("./add/command-object"), exports);
+tslib_1.__exportStar(require("./affected/command-object"), exports);
+tslib_1.__exportStar(require("./daemon/command-object"), exports);
+tslib_1.__exportStar(require("./exec/command-object"), exports);
+tslib_1.__exportStar(require("./format/command-object"), exports);
+tslib_1.__exportStar(require("./generate/command-object"), exports);
+tslib_1.__exportStar(require("./graph/command-object"), exports);
+tslib_1.__exportStar(require("./import/command-object"), exports);
+tslib_1.__exportStar(require("./init/command-object"), exports);
+tslib_1.__exportStar(require("./list/command-object"), exports);
+tslib_1.__exportStar(require("./migrate/command-object"), exports);
+tslib_1.__exportStar(require("./new/command-object"), exports);
+tslib_1.__exportStar(require("./register/command-object"), exports);
+tslib_1.__exportStar(require("./release/command-object"), exports);
+tslib_1.__exportStar(require("./repair/command-object"), exports);
+tslib_1.__exportStar(require("./report/command-object"), exports);
+tslib_1.__exportStar(require("./reset/command-object"), exports);
+tslib_1.__exportStar(require("./run-many/command-object"), exports);
+tslib_1.__exportStar(require("./run/command-object"), exports);
+tslib_1.__exportStar(require("./show/command-object"), exports);
+tslib_1.__exportStar(require("./sync/command-object"), exports);
+tslib_1.__exportStar(require("./watch/command-object"), exports);

package/dist/src/command-line/init/ai-agent-prompts.d.ts

@@ -0,0 +1,2 @@
+import { Agent } from '../../ai/utils';
+export declare function determineAiAgents(aiAgents?: Agent[], interactive?: boolean): Promise<Agent[]>;

package/dist/src/command-line/init/ai-agent-prompts.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.determineAiAgents = determineAiAgents;
+const tslib_1 = require("tslib");
+const enquirer_1 = require("enquirer");
+const is_ci_1 = require("../../utils/is-ci");
+const utils_1 = require("../../ai/utils");
+const detect_ai_agent_1 = require("../../ai/detect-ai-agent");
+const pc = tslib_1.__importStar(require("picocolors"));
+async function determineAiAgents(aiAgents, interactive) {
+    if (interactive === false || (0, is_ci_1.isCI)()) {
+        if (aiAgents) {
+            return aiAgents;
+        }
+        const detected = (0, detect_ai_agent_1.detectAiAgent)();
+        return detected ? [detected] : [];
+    }
+    if (aiAgents) {
+        return aiAgents;
+    }
+    return await aiAgentsPrompt();
+}
+async function aiAgentsPrompt() {
+    const promptConfig = {
+        name: 'agents',
+        message: 'Which AI agents, if any, would you like to set up?',
+        type: 'multiselect',
+        choices: utils_1.supportedAgents.map((a) => ({
+            name: a,
+            message: utils_1.agentDisplayMap[a],
+        })),
+        footer: () => pc.dim('Multiple selections possible. <Space> to select. <Enter> to confirm.'),
+    };
+    return (await (0, enquirer_1.prompt)([promptConfig])).agents;
+}

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

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.yargsInitCommand = void 0;
+const handle_import_1 = require("../../utils/handle-import");
+const shared_options_1 = require("../yargs-utils/shared-options");
+exports.yargsInitCommand = {
+    command: 'init',
+    describe: 'Adds Nx to any type of workspace. It installs nx, creates an nx.json configuration file and optionally sets up remote caching. For more info, check https://nx.dev/recipes/adopting-nx.',
+    builder: async (yargs) => {
+        // Check for --help flag directly since async builder doesn't receive helpOrVersionSet reliably
+        const wantsHelp = process.argv.includes('--help') || process.argv.includes('-h');
+        if (wantsHelp) {
+            const y = await withInitOptions(yargs);
+            y.showHelp();
+            process.exit(0);
+        }
+        return withInitOptions(yargs);
+    },
+    handler: async (args) => {
+        // Node 24 has stricter readline behavior, and enquirer is not checking for closed state
+        // when invoking operations, thus you get an ERR_USE_AFTER_CLOSE error.
+        process.on('uncaughtException', (error) => {
+            if (error &&
+                typeof error === 'object' &&
+                'code' in error &&
+                error['code'] === 'ERR_USE_AFTER_CLOSE')
+                return;
+            throw error;
+        });
+        const useV2 = await isInitV2();
+        if (useV2) {
+            await require('./init-v2').initHandler(args);
+        }
+        else {
+            // v1 path retained for `NX_ADD_PLUGINS=false`; slated for removal.
+            await require('./init-v1').initHandler(args);
+        }
+        process.exit(0);
+    },
+};
+async function isInitV2() {
+    return (process.env['NX_ADD_PLUGINS'] !== 'false' &&
+        (await (0, handle_import_1.handleImport)('../../config/nx-json.js', __dirname)).readNxJson()
+            .useInferencePlugins !== false);
+}
+async function withInitOptions(yargs) {
+    const useV2 = await isInitV2();
+    if (useV2) {
+        return yargs
+            .option('nxCloud', {
+            type: 'boolean',
+            description: 'Set up distributed caching with Nx Cloud.',
+        })
+            .option('interactive', {
+            describe: 'When false disables interactive input prompts for options.',
+            type: 'boolean',
+            default: true,
+        })
+            .option('useDotNxInstallation', {
+            type: 'boolean',
+            description: 'Initialize an Nx workspace setup in the .nx directory of the current repository.',
+            default: false,
+        })
+            .option('aiAgents', {
+            type: 'array',
+            string: true,
+            description: 'List of AI agents to set up.',
+            choices: ['claude', 'codex', 'copilot', 'cursor', 'gemini', 'opencode'],
+        })
+            .option('plugins', {
+            type: 'string',
+            description: 'Plugins to install: "skip" for none, "all" for all detected, or comma-separated list (e.g., @nx/vite,@nx/jest).',
+        })
+            .option('cacheable', {
+            type: 'string',
+            description: 'Comma-separated list of cacheable operations (e.g., build,test,lint).',
+            coerce: shared_options_1.parseCSV,
+        });
+    }
+    else {
+        return yargs
+            .option('nxCloud', {
+            type: 'boolean',
+            description: 'Set up remote caching with Nx Cloud.',
+        })
+            .option('interactive', {
+            describe: 'When false disables interactive input prompts for options.',
+            type: 'boolean',
+            default: true,
+        })
+            .option('integrated', {
+            type: 'boolean',
+            description: 'Migrate to an Nx integrated layout workspace. Only for Angular CLI workspaces.',
+            default: false,
+        })
+            .option('useDotNxInstallation', {
+            type: 'boolean',
+            description: 'Initialize an Nx workspace setup in the .nx directory of the current repository.',
+            default: false,
+        })
+            .option('cacheable', {
+            type: 'string',
+            description: 'Comma-separated list of cacheable operations. Only used for internal testing.',
+            coerce: shared_options_1.parseCSV,
+            hidden: true,
+        });
+    }
+}