nx 23.3.0 → 24.0.0-beta.0

package/dist/src/hasher/native-task-hasher-impl.js

@@ -98,7 +98,7 @@ function taskGraphFingerprint(taskGraph, ultracacheConfigurations) {
     ];
     for (const id of Object.keys(taskGraph.tasks).sort()) {
         const task = taskGraph.tasks[id];
-        parts.push(id, task.target.project, task.target.target, task.target.configuration ?? '', (task.outputs ?? []).join(','), (taskGraph.dependencies[id] ?? []).join(','), (taskGraph.continuousDependencies[id] ?? []).join(','));
+        parts.push(id, task.target.project, task.target.target, task.target.configuration ?? '', (task.outputs ?? []).join(','), (taskGraph.dependencies[id] ?? []).join(','), (taskGraph.continuousDependencies[id] ?? []).join(','), (taskGraph.continuousDependenciesWithoutInputs?.[id] ?? []).join(','));
     }
     return (0, native_1.hashArray)(parts);
 }

package/dist/src/migrations/update-24-0-0/find-custom-hashers.d.ts

@@ -0,0 +1,3 @@
+import type { MigrationReturnObject } from '../../config/misc-interfaces';
+import type { Tree } from '../../generators/tree';
+export default function findCustomHashers(tree: Tree): Promise<MigrationReturnObject>;

package/dist/src/migrations/update-24-0-0/find-custom-hashers.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = findCustomHashers;
+const glob_1 = require("../../generators/utils/glob");
+const json_1 = require("../../utils/json");
+const path_1 = require("../../utils/path");
+const node_path_1 = require("node:path");
+const DOCS_URL = 'https://nx.dev/docs/kb/local-executors#replace-a-custom-hasher-with-inputs';
+async function findCustomHashers(tree) {
+    const hits = new Set();
+    const malformed = new Set();
+    const unparseable = [];
+    const visited = new Set();
+    for (const packageJsonPath of await (0, glob_1.globAsync)(tree, ['**/package.json'])) {
+        if (packageJsonPath.split('/').includes('node_modules')) {
+            continue;
+        }
+        const content = tree.read(packageJsonPath, 'utf-8');
+        if (!content.includes('"executors"') && !content.includes('"builders"')) {
+            continue;
+        }
+        const packageJson = tryParse(content);
+        if (!packageJson) {
+            unparseable.push(packageJsonPath);
+            continue;
+        }
+        const packageRoot = node_path_1.posix.dirname(packageJsonPath);
+        // A nameless local plugin is referenced by its relative path.
+        const pluginName = packageJson.name ?? (packageRoot === '.' ? '.' : `./${packageRoot}`);
+        for (const field of [packageJson.executors, packageJson.builders]) {
+            if (typeof field !== 'string') {
+                continue;
+            }
+            const executorsJsonPath = (0, path_1.joinPathFragments)(packageRoot, field);
+            if (visited.has(executorsJsonPath) || !tree.exists(executorsJsonPath)) {
+                continue;
+            }
+            visited.add(executorsJsonPath);
+            const executorsJson = tryParse(tree.read(executorsJsonPath, 'utf-8'));
+            if (!executorsJson) {
+                unparseable.push(executorsJsonPath);
+                continue;
+            }
+            const entries = [];
+            for (const map of [executorsJson.executors, executorsJson.builders]) {
+                if (map === undefined) {
+                    continue;
+                }
+                if (!isPlainObject(map)) {
+                    unparseable.push(executorsJsonPath);
+                    break;
+                }
+                entries.push(...Object.entries(map));
+            }
+            for (const [name, entry] of entries) {
+                if (typeof entry === 'string') {
+                    continue;
+                }
+                if (!isPlainObject(entry) || !isValidHasher(entry.hasher)) {
+                    malformed.add(`Entry "${name}" in "${executorsJsonPath}" is not a valid executor entry. Check it by hand for a "hasher".`);
+                    continue;
+                }
+                if (entry.hasher === undefined) {
+                    continue;
+                }
+                const hasherPath = (0, path_1.joinPathFragments)(node_path_1.posix.dirname(executorsJsonPath), entry.hasher);
+                hits.add(`Executor "${pluginName}:${name}" declares a custom hasher at "${hasherPath}" in "${executorsJsonPath}".`);
+            }
+        }
+    }
+    if (hits.size === 0 && malformed.size === 0 && unparseable.length === 0) {
+        return { skipAgentic: true };
+    }
+    const manualNotes = [
+        ...malformed,
+        ...unparseable.map((path) => `Could not parse "${path}". Check it by hand for executors that declare a "hasher".`),
+    ];
+    return {
+        nextSteps: [
+            `Custom hashers are deprecated and will be removed in Nx 25. Replace each one with target inputs, then remove "hasher" from executors.json. See ${DOCS_URL}`,
+            ...hits,
+            ...manualNotes,
+        ],
+        agentContext: [...hits, ...manualNotes],
+    };
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isValidHasher(hasher) {
+    return hasher === undefined || typeof hasher === 'string';
+}
+function tryParse(content) {
+    try {
+        return (0, json_1.parseJson)(content);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/migrations/update-24-0-0/find-custom-hashers.md

@@ -0,0 +1,63 @@
+#### Move custom executor hashers to target inputs
+
+Custom hashers are deprecated in Nx 24 and will be removed in Nx 25.
+A custom hasher is the `hasher` property of an executor in `executors.json`, pointing at a module that computes the task hash in code.
+Target `inputs` replace them.
+
+This migration finds every local plugin in the workspace whose `executors.json` (or `builders.json`) declares a `hasher`.
+It doesn't edit any files.
+When it finds one, it lists the executor, the hasher module, and the `executors.json` file in the migration's next steps.
+It also lists files and executor entries it can't read, so you can check those by hand.
+Under `nx migrate` with an AI agent, the agent reads each hasher and writes `inputs` that hash the same things.
+A target that declares its own `inputs` doesn't inherit them from `targetDefaults`, so the agent checks every target that uses the executor and adds the inputs where they're missing.
+It removes the `hasher` only once every one of those targets is covered.
+If something the hasher hashes can't be expressed as an input, the agent leaves the hasher in place and tells you why.
+
+Packages installed in `node_modules` aren't scanned.
+If a third-party plugin you use declares a hasher, Nx warns about it when it hashes one of its tasks.
+
+#### Sample code changes
+
+Given a local plugin whose `echo` executor hashes the project, its dependencies, and the `API_URL` environment variable:
+
+##### Before
+
+```json title="tools/my-plugin/executors.json"
+{
+  "executors": {
+    "echo": {
+      "implementation": "./src/executors/echo/executor",
+      "hasher": "./src/executors/echo/hasher",
+      "schema": "./src/executors/echo/schema.json"
+    }
+  }
+}
+```
+
+##### After
+
+```json title="nx.json"
+{
+  "targetDefaults": {
+    "@acme/my-plugin:echo": {
+      "inputs": ["default", "^default", { "env": "API_URL" }]
+    }
+  }
+}
+```
+
+```json title="tools/my-plugin/executors.json"
+{
+  "executors": {
+    "echo": {
+      "implementation": "./src/executors/echo/executor",
+      "schema": "./src/executors/echo/schema.json"
+    }
+  }
+}
+```
+
+#### Reference
+
+- [Replace a custom hasher with inputs](https://nx.dev/docs/kb/local-executors#replace-a-custom-hasher-with-inputs)
+- [Inputs reference](https://nx.dev/docs/reference/inputs)

package/dist/src/migrations/update-24-0-0/move-custom-hashers-to-inputs.md

@@ -0,0 +1,145 @@
+# Move custom executor hashers to target inputs
+
+Custom hashers (the `hasher` property of an executor in `executors.json`) are
+deprecated in Nx 24 and removed in Nx 25. Each one should become target `inputs`
+that hash the same things, so the targets keep caching correctly once the hasher
+is gone.
+
+The generator half of this migration only scans. It edits no files, and it lists
+every executor that declares a hasher in the advisory context, one line each,
+with the executor name, the hasher path, and the `executors.json` path. Lines
+starting with `Could not parse` name files the scan skipped, and lines starting
+with `Entry` name executor entries it could not read.
+
+Do not touch executors that declare no hasher, executors installed from
+`node_modules`, or any other caching configuration.
+
+## First, check whether there is anything to do
+
+Confirm this before changing anything. If it fails, make no changes and stop:
+
+1. The advisory context lists at least one executor that declares a custom
+   hasher, or at least one file or entry it could not read. Read each of those
+   yourself; if it declares no `hasher`, drop it from the list.
+
+## Step 1: Read what each hasher hashes
+
+Open the hasher module named in the advisory context. Work out every value it
+feeds into the hash it returns:
+
+- `context.hasher.hashTask(task, ...)` alone is Nx default hashing.
+- Files it reads, globs it walks, or other projects it hashes.
+- Environment variables it reads.
+- Commands it runs, or data it fetches (a remote API, a registry lookup).
+
+## Step 2: Write equivalent inputs
+
+Map each value to an input:
+
+| What the hasher hashes                                | Input                                                   |
+| ----------------------------------------------------- | ------------------------------------------------------- |
+| The project and its dependencies (Nx default hashing) | `"default"` and `"^default"`                            |
+| Files of specific other projects                      | `{ "input": "default", "projects": ["shared-config"] }` |
+| A subset of the files in the project                  | `{ "fileset": "{projectRoot}/src/**/*.graphql" }`       |
+| A file outside any project                            | `{ "fileset": "{workspaceRoot}/schema.json" }`          |
+| An environment variable                               | `{ "env": "API_URL" }`                                  |
+| The output of a command, such as a tool version       | `{ "runtime": "node --version" }`                       |
+
+If the workspace defines named inputs such as `production`, prefer them over
+`default` where the hasher excluded test files.
+
+### Find every target that uses the executor
+
+Write the resolved project graph and list every target whose `executor` is the
+executor name (`"@acme/my-plugin:echo"`):
+
+```shell
+npx nx graph --file=tmp/custom-hashers-graph.json
+```
+
+Each target in `graph.nodes.<project>.data.targets` there is fully resolved: it
+already reflects `targetDefaults` (including filtered array entries), inferred
+targets, and project-level overrides. Record each consuming target's resolved
+`inputs`. Every one of them must end up covered.
+
+### Place the inputs
+
+A target that declares its own `inputs` replaces the `inputs` from
+`targetDefaults` rather than merging with them. So a `targetDefaults` edit alone
+does not reach a target that already declares `inputs`.
+
+1. Set the inputs in `nx.json` `targetDefaults` under the executor name. If that
+   key already exists, add `inputs` to it, and merge with any `inputs` it already
+   declares rather than replacing them. If its value is an array of filtered
+   entries, add the inputs to every entry that applies to a consuming target.
+2. For every consuming target that declares its own `inputs`, add the
+   replacement inputs to that target as well, keeping the inputs it already has.
+   It is declared in `project.json`, in the `nx.targets` block of
+   `package.json`, or by the plugin that infers the target. For an inferred
+   target, set `inputs` in `project.json` to the full resolved list plus the
+   replacement inputs.
+3. Write the graph again and confirm that every consuming target's resolved
+   `inputs` now contains every replacement input. Fix any that do not.
+
+**Before:**
+
+```json
+// tools/my-plugin/executors.json
+{
+  "executors": {
+    "echo": {
+      "implementation": "./src/executors/echo/executor",
+      "hasher": "./src/executors/echo/hasher",
+      "schema": "./src/executors/echo/schema.json"
+    }
+  }
+}
+```
+
+**After:**
+
+```json
+// nx.json
+{
+  "targetDefaults": {
+    "@acme/my-plugin:echo": {
+      "inputs": ["default", "^default", { "env": "API_URL" }]
+    }
+  }
+}
+```
+
+```json
+// tools/my-plugin/executors.json
+{
+  "executors": {
+    "echo": {
+      "implementation": "./src/executors/echo/executor",
+      "schema": "./src/executors/echo/schema.json"
+    }
+  }
+}
+```
+
+## Step 3: Remove the hasher only when the inputs cover it
+
+Remove `hasher` from `executors.json` and delete the hasher module (and its
+spec) only once the resolved inputs of every consuming target cover everything
+the hasher hashed.
+
+If a value has no file, environment variable, or project to point at, such as
+data fetched from a remote service, use a `runtime` input whose command prints
+that value. If no command can reproduce it, leave the hasher in place and tell
+the user which value blocks the move and why.
+
+## Post-Migration Validation
+
+1. `npx nx show target <project>:<target>` for every consuming target found in
+   Step 2. Confirm each one lists the replacement inputs. After the hasher is
+   removed, `npx nx show target <project>:<target> inputs` also shows the files
+   and values those inputs resolve to.
+2. `npx nx run-many -t <target>` twice for the targets that used the executor.
+   The second run should be a cache hit. Change a file the hasher used to hash
+   and confirm the next run is a cache miss.
+3. `npx nx run-many -t build,test,lint -p <plugin project>` if you deleted hasher
+   files. Fix failures caused by this migration and re-run until green.

package/dist/src/native/index.d.ts

@@ -236,6 +236,10 @@ export declare class RunningTasksService {
   constructor(db: ExternalObject<NxDbConnection>)
   getRunningTasks(ids: Array<string>): Array<string>
   addRunningTask(taskId: string): void
+  /**
+   * Release this process's claim on a task. A row another process has since
+   * taken over is left in place.
+   */
   removeRunningTask(taskId: string): void
 }
 
@@ -282,14 +286,42 @@ export declare class TaskHasher {
   hashPlansFor(hashPlans: ExternalObject<Record<string, Array<HashInstruction>>>, taskIds: Array<string>, perTaskEnvs: Record<string, Record<string, string>>, cwd: string, collectTaskInputs?: boolean | undefined | null): Record<string, HashDetails>
 }
 
+/**
+ * Tracks which tasks each Nx process in a nested process tree is running, so
+ * that a task which re-invokes itself can be reported instead of looping
+ * forever.
+ *
+ * Every process in the tree shares a `root_pid`, but sharing a root does not
+ * imply a parent/child relationship: sibling Nx processes are common and
+ * legitimate (N atomized e2e specs each spawning the same `serve-static` web
+ * server, or two parallel tasks that each shell out to `nx run lib:build`).
+ * Only an invocation belonging to an actual *ancestor* of this process is a
+ * loop, so the check is scoped to `ancestor_pids` rather than to the whole
+ * tree.
+ */
 export declare class TaskInvocationTracker {
-  constructor(db: ExternalObject<NxDbConnection>, rootPid: number)
-  /** Register a task as invoked. Throws if the task was already registered (loop detected). */
-  registerTask(parentPid: number, taskId: string): void
-  /** Remove a task invocation record after task completes. */
-  unregisterTask(taskId: string): void
-  /** Get all invocations for this root_pid, ordered by creation time. */
-  getInvocationChain(): Array<InvocationRecord>
+  constructor(db: ExternalObject<NxDbConnection>, rootPid: number, ancestorPids: Array<number>)
+  /**
+   * Register a task as invoked by the process identified by `pid`.
+   *
+   * Returns the invocation chain when an ancestor process is already running
+   * this task, which is a genuine loop. The chain lists every task invoked
+   * along the ancestry path, outermost first. Returns `null` when the task
+   * was registered, including when a *sibling* process is already running it.
+   *
+   * An ancestor running this task with the *same* overrides is a loop
+   * immediately. An ancestor running it with different overrides is allowed
+   * up to `MAX_ANCESTOR_INVOCATIONS_PER_TASK`, which lets a terminating
+   * `app:build -> app:build --flag` chain through while still bounding a
+   * recursion whose forwarded arguments grow on every hop.
+   */
+  registerTask(pid: number, taskId: string, overridesHash: string): Array<InvocationRecord> | null
+  /**
+   * Remove a task invocation record after the task completes. Scoped to the
+   * registering process so that a sibling finishing the same task does not
+   * drop this process's record.
+   */
+  unregisterTask(pid: number, taskId: string): void
   /** Clean up stale invocations older than 1 day (handles PID recycling). */
   cleanupStale(): void
 }
@@ -886,7 +918,7 @@ export declare function installNxConsole(): Promise<boolean>
 export declare function installNxConsoleForEditor(editor: SupportedEditor): Promise<boolean>
 
 export interface InvocationRecord {
-  parentPid: number
+  pid: number
   taskId: string
 }
 
@@ -1012,6 +1044,14 @@ export interface NxWorkspaceFilesExternals {
   ignoredIndex: ExternalObject<IgnoredIndexReader>
 }
 
+/**
+ * Open `url` in the user's default browser. Returns `true` if an opener
+ * process was spawned, `false` if none could be (e.g. no `xdg-open`) or `url`
+ * isn't `http(s)`, so the caller can tell the user instead of failing
+ * silently. Never throws.
+ */
+export declare function openUrl(url: string): boolean
+
 /** A workspace-relative file with the stamp it was left with. */
 export interface OutputFile {
   path: string
@@ -1078,6 +1118,32 @@ export interface ProjectGraph {
 
 export declare function remove(src: string): void
 
+/**
+ * The daemon's own socket. Per run — the directory name hashes the pid, and
+ * clients read the daemon's path back out of the process cache rather than
+ * deriving it.
+ */
+export declare function resolveDaemonSocketPath(workspaceRoot: string, env?: Record<string, string> | undefined | null): SocketDirDetails
+
+/** A forked task process's socket, in the daemon's per-run directory. */
+export declare function resolveForkedProcessSocketPath(workspaceRoot: string, id: string, env?: Record<string, string> | undefined | null): SocketDirDetails
+
+/**
+ * Where the Nx Console socket lives, for whoever binds or connects to it.
+ *
+ * `env` is for callers that load a workspace `.env` into a copy rather than
+ * into their own environment, and `workspaceRoot` for callers that do not run
+ * inside the workspace — Nx Console is both, since it runs in the editor's
+ * extension host.
+ */
+export declare function resolveNxConsoleSocketPath(workspaceRoot: string, env?: Record<string, string> | undefined | null): SocketDirDetails
+
+/**
+ * Plugin worker sockets get their own workspace-scoped directory rather than
+ * sitting in the shared system temp dir, which cannot be locked down.
+ */
+export declare function resolvePluginSocketPath(workspaceRoot: string, id: string, env?: Record<string, string> | undefined | null): SocketDirDetails
+
 export declare function restoreTerminal(): void
 
 export declare const enum RunMode {
@@ -1089,6 +1155,53 @@ export interface RuntimeInput {
   runtime: string
 }
 
+/**
+ * One resolved socket location, and everything `daemon/tmp-dir.ts` needs to
+ * explain it. Every user-facing sentence is rendered on the TypeScript side,
+ * so this carries facts rather than prose.
+ */
+export interface SocketDirDetails {
+  /** The socket itself, which on Windows is a named pipe rather than a path. */
+  path: string
+  /** The directory holding it, for the caller that deletes it on shutdown. */
+  dir: string
+  /**
+   * Whether `path` exceeds what the platform will bind. Reported rather than
+   * thrown because which advice is correct depends on the other fields.
+   */
+  tooLong: boolean
+  /**
+   * Set when `path` is a directory Nx refuses to *be* the socket directory:
+   * `shared-with-other-users`, `nx-managed`, or `os-temp-root`. The caller
+   * throws on it rather than using `path`.
+   */
+  invalidReason?: string
+  /** The preferred root that was skipped, when a later tier was used. */
+  demotedFrom?: string
+  /**
+   * The default-root directory Nx tried before falling back, when there was
+   * one.
+   */
+  attemptedDir?: string
+  /**
+   * The `NX_SOCKET_DIR` that was refused, when that is why this is a
+   * fallback. Tracked apart from the other reasons so a later length error
+   * stops telling someone to shorten a directory refused for another one.
+   */
+  refusedConfiguredDir?: string
+  /** Why that configured directory was refused. */
+  refusalError?: string
+  /**
+   * Whether this landed in the workspace data dir, which the caller warns
+   * about once per process.
+   */
+  usedWorkspaceFallback: boolean
+  /** Deduplicated advice for the refusals collected along the way. */
+  remedies: Array<string>
+  /** Every refusal as one sentence, for `--verbose`. */
+  refusalDetails?: string
+}
+
 export declare const enum SupportedEditor {
   VSCode = 0,
   VSCodeInsiders = 1,
@@ -1177,6 +1290,11 @@ export interface TaskGraph {
   /** Map of Task IDs to IDs of tasks which the task depends on */
   dependencies: Record<string, Array<string>>
   continuousDependencies: Record<string, Array<string>>
+  /**
+   * The subset of `continuous_dependencies` from `dependsOn` entries with
+   * `inputs: false`: still run, but their inputs are not hashed into the task.
+   */
+  continuousDependenciesWithoutInputs?: Record<string, Array<string>>
 }
 
 /** Details about the composition of a task's hash */
@@ -1346,6 +1464,7 @@ export interface UltracacheDiagnostic {
 export interface UltracacheEligibilityOptions {
   /** Tasks whose executor ships a custom hasher. */
   customHasherTaskIds?: Array<string>
+  continuousTaskIds?: Array<string>
 }
 
 /**

package/dist/src/native/native-bindings.js

@@ -638,8 +638,13 @@ module.exports.locateTouchedProjects = nativeBinding.locateTouchedProjects
 module.exports.logDebug = nativeBinding.logDebug
 module.exports.matchGlobPaths = nativeBinding.matchGlobPaths
 module.exports.matchOutputPaths = nativeBinding.matchOutputPaths
+module.exports.openUrl = nativeBinding.openUrl
 module.exports.parseTaskStatus = nativeBinding.parseTaskStatus
 module.exports.remove = nativeBinding.remove
+module.exports.resolveDaemonSocketPath = nativeBinding.resolveDaemonSocketPath
+module.exports.resolveForkedProcessSocketPath = nativeBinding.resolveForkedProcessSocketPath
+module.exports.resolveNxConsoleSocketPath = nativeBinding.resolveNxConsoleSocketPath
+module.exports.resolvePluginSocketPath = nativeBinding.resolvePluginSocketPath
 module.exports.restoreTerminal = nativeBinding.restoreTerminal
 module.exports.RunMode = nativeBinding.RunMode
 module.exports.SupportedEditor = nativeBinding.SupportedEditor

package/dist/src/native/nx.wasi-browser.js

@@ -124,6 +124,7 @@ export const installNxConsole = __napiModule.exports.installNxConsole
 export const IS_WASM = __napiModule.exports.IS_WASM
 export const isAiAgent = __napiModule.exports.isAiAgent
 export const logDebug = __napiModule.exports.logDebug
+export const openUrl = __napiModule.exports.openUrl
 export const remove = __napiModule.exports.remove
 export const testOnlyTransferFileMap = __napiModule.exports.testOnlyTransferFileMap
 export const transferProjectGraph = __napiModule.exports.transferProjectGraph

package/dist/src/native/nx.wasi.cjs

@@ -154,6 +154,7 @@ module.exports.installNxConsole = __napiModule.exports.installNxConsole
 module.exports.IS_WASM = __napiModule.exports.IS_WASM
 module.exports.isAiAgent = __napiModule.exports.isAiAgent
 module.exports.logDebug = __napiModule.exports.logDebug
+module.exports.openUrl = __napiModule.exports.openUrl
 module.exports.remove = __napiModule.exports.remove
 module.exports.testOnlyTransferFileMap = __napiModule.exports.testOnlyTransferFileMap
 module.exports.transferProjectGraph = __napiModule.exports.transferProjectGraph

package/dist/src/nx-cloud/update-manager.d.ts

@@ -1,7 +1,12 @@
+import { HttpClient } from '../utils/http-client';
 import type { CloudTaskRunnerOptions } from './nx-cloud-tasks-runner-shell';
 import type { ReadUltracacheConfigurationsOptions, ReadUltracacheConfigurationsResult } from '../ultracache/fetch';
 import { TasksRunner } from '../tasks-runner/tasks-runner';
 import { RemoteCacheV2 } from '../tasks-runner/default-tasks-runner';
+interface CloudBundleInstall {
+    version: string;
+    fullPath: string;
+}
 export declare class NxCloudEnterpriseOutdatedError extends Error {
     constructor(url: string);
 }
@@ -24,3 +29,5 @@ export declare function verifyOrUpdateNxCloudClient(options?: {
     version: string;
 } | null>;
 export declare function getBundleInstallDefaultLocation(): string;
+export declare function downloadAndExtractClientBundle(httpClient: HttpClient, version: string, url: string): Promise<CloudBundleInstall>;
+export {};