nx 22.7.8 → 22.7.9

package/dist/src/utils/owned-private-dir.d.ts

@@ -0,0 +1,132 @@
+declare const safeSharedRootBrand: unique symbol;
+declare const sharedRootEstablishedBrand: unique symbol;
+declare const ownedRealDirBrand: unique symbol;
+declare const ownedPrivateDirBrand: unique symbol;
+/** Verified safe to keep an owner-only directory under. Not created. */
+export type SafeSharedRoot = string & {
+    readonly [safeSharedRootBrand]: true;
+};
+/** Created if absent, then verified safe as above. */
+export type EstablishedSharedRoot = string & {
+    readonly [sharedRootEstablishedBrand]: true;
+};
+/** An existing real directory owned by us. Mode is *not* checked. */
+export type OwnedRealDir = string & {
+    readonly [ownedRealDirBrand]: true;
+};
+/**
+ * POSIX: created if absent, owned by us, and carrying no group or other bits —
+ * re-locked first if it was looser. The mode is checked on whichever branch
+ * produced it, so the brand does not depend on who created the directory.
+ *
+ * Windows: only *is a real directory*. `getuid` is unavailable there, so
+ * neither ownership nor mode is checked; `%TMP%` is already per-account.
+ */
+export type OwnedPrivateDir = string & {
+    readonly [ownedPrivateDirBrand]: true;
+};
+/** Why a guard refused a directory. Data, not a sentence: `remedyFor` decides on it. */
+export type DirRefusal = {
+    kind: 'not-created';
+    dir: string;
+    code?: string;
+} | {
+    kind: 'not-inspectable';
+    dir: string;
+    code?: string;
+} | {
+    kind: 'not-a-directory';
+    dir: string;
+    symlink?: true;
+} | {
+    kind: 'foreign-owner';
+    dir: string;
+    uid: number;
+} | {
+    kind: 'foreign-shared-container';
+    dir: string;
+    uid: number;
+} | {
+    kind: 'not-tightenable';
+    dir: string;
+    mode: number;
+} | {
+    kind: 'peer-writable-not-sticky';
+    dir: string;
+    mode: number;
+};
+/** A guard's verdict. */
+export type GuardResult<T> = {
+    status: 'ok';
+    path: T;
+} | {
+    status: 'refused';
+    refusal: DirRefusal;
+};
+/** The user-facing sentence for a refusal. The only place wording is decided. */
+export declare function describeRefusal(r: DirRefusal): string;
+/** What the user can do about a refusal, or `undefined` when there is nothing. */
+export declare function remedyFor(r: DirRefusal): string | undefined;
+/** One refusal as an `Error`, so several can travel in an `AggregateError`. */
+export declare class DirectoryRefusedError extends Error {
+    readonly refusal: DirRefusal;
+    constructor(refusal: DirRefusal);
+}
+/**
+ * Whether a shared container is safe to keep an owner-only directory under.
+ *
+ * On POSIX, a container writable by other users must be sticky, and it must be
+ * owned by either root or the current user. Windows short-circuits after the
+ * directory test — the OS temp root is already scoped to one account, so there
+ * is no shared level whose ownership could matter.
+ *
+ * Sticky directories still let the directory's own owner rename entries, so a
+ * container owned by another unprivileged user could replace a previously
+ * verified private directory beneath it.
+ */
+export declare function isSafeSharedRoot(dir: string): GuardResult<SafeSharedRoot>;
+/**
+ * Whether other users on this machine can write into `dir`. Gates whether a
+ * refusal message may cite other users, so it must not over-report: `false` on
+ * Windows, where libuv synthesizes `st_mode` from the READONLY attribute and
+ * reports an ordinary per-account directory as `0666`, and `false` on a path
+ * that cannot be inspected.
+ *
+ * `statSync`, not `lstatSync`: the question is about the directory that will be
+ * used, not the link pointing at it. Link modes mislead in both directions —
+ * Linux creates symlinks `0777`, macOS applies the umask. Nothing here decides
+ * whether a path is accepted, so following the link costs nothing the guards
+ * do not already re-check.
+ */
+export declare function isPeerWritable(dir: string): boolean;
+/**
+ * Create a shared container as sticky + world-writable if it does not exist,
+ * and report whether the resulting path is safe for the current user.
+ *
+ * **A container that already exists is never modified — only judged.** Do not
+ * chmod before deciding trust: `CAP_FOWNER` (root's default in Docker and most
+ * CI images) can chmod a directory it does not own, so a peer-owned root would
+ * be widened to `1777` and then refused, and an operator who deliberately
+ * tightened this root would have it re-widened on every `nx` process.
+ */
+export declare function ensureSafeSharedRoot(dir: string): GuardResult<EstablishedSharedRoot>;
+/**
+ * Whether `dir` is an existing real directory owned by us. Unlike
+ * `ensureOwnedPrivateDir` it creates nothing and repairs nothing — for callers
+ * that only want to know whether a path is safe to act on, such as deleting.
+ */
+export declare function isOwnedRealDirectory(dir: string): OwnedRealDir | null;
+/** The path segment separating one user's Nx runtime state from another's. */
+export declare function getUserSegment(): string;
+/**
+ * Ensure `dir` exists, is a real directory owned by us, and carries no group or
+ * other bits at all — read and search alone reach a socket inside it, so 0755 is
+ * re-locked rather than accepted. A `refused` status carries which check said
+ * no — usually `foreign-owner` for a directory another user planted, but also
+ * `not-created`/`not-inspectable` for a filesystem error, `not-a-directory`, or
+ * `not-tightenable` when the re-lock did not land.
+ *
+ * Node builtins only: reached from the native binding loader.
+ */
+export declare function ensureOwnedPrivateDir(dir: string): GuardResult<OwnedPrivateDir>;
+export {};

package/dist/src/utils/owned-private-dir.js

@@ -0,0 +1,323 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DirectoryRefusedError = void 0;
+exports.describeRefusal = describeRefusal;
+exports.remedyFor = remedyFor;
+exports.isSafeSharedRoot = isSafeSharedRoot;
+exports.isPeerWritable = isPeerWritable;
+exports.ensureSafeSharedRoot = ensureSafeSharedRoot;
+exports.isOwnedRealDirectory = isOwnedRealDirectory;
+exports.getUserSegment = getUserSegment;
+exports.ensureOwnedPrivateDir = ensureOwnedPrivateDir;
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+// A string discriminant, not a boolean `ok`: this repo compiles with
+// `strict: false`, where TypeScript does not narrow a union on a boolean literal.
+const allow = (path) => ({ status: 'ok', path });
+const deny = (refusal) => ({
+    status: 'refused',
+    refusal,
+});
+const notADirectory = (dir, stats) => stats.isSymbolicLink()
+    ? { kind: 'not-a-directory', dir, symlink: true }
+    : { kind: 'not-a-directory', dir };
+// Four octal digits, so a sticky container reads `1777` and a plain directory
+// `0755` — the notation `chmod` and `ls` use. Prefixing a literal `0` instead
+// renders sticky modes as `01777`, which is not a form anyone writes.
+const asMode = (mode) => (mode & 0o7777).toString(8).padStart(4, '0');
+/** The user-facing sentence for a refusal. The only place wording is decided. */
+function describeRefusal(r) {
+    switch (r.kind) {
+        case 'not-created':
+            return `${r.dir} could not be created${r.code ? ` (${r.code})` : ''}`;
+        case 'not-inspectable':
+            return `${r.dir} could not be inspected${r.code ? ` (${r.code})` : ''}`;
+        case 'not-a-directory':
+            return r.symlink
+                ? `${r.dir} is a symlink, not a real directory — something replaced the path Nx expected to create`
+                : `${r.dir} exists and is not a directory`;
+        case 'foreign-owner':
+            return `${r.dir} is owned by uid ${r.uid}, not by you`;
+        case 'foreign-shared-container':
+            return `${r.dir} belongs to another user (uid ${r.uid}) rather than to you or to root`;
+        case 'not-tightenable':
+            return `${r.dir} is reachable by other users (mode ${asMode(r.mode)}) and could not be tightened to 0700`;
+        case 'peer-writable-not-sticky':
+            return `${r.dir} is writable by other users but not sticky (mode ${asMode(r.mode)}), so a peer could replace directories inside it`;
+        default: {
+            // This repo sets `strict: false` and leaves `noImplicitReturns` unset, so
+            // a new DirRefusal member would otherwise compile here and render as
+            // `undefined` inside the aggregate message. Assignability to `never` still
+            // holds under these settings, so this is a real compile-time guard.
+            const unhandled = r;
+            throw new Error(`Unhandled directory refusal: ${unhandled.kind}`);
+        }
+    }
+}
+/** Single-quoted for a shell, so a path with a space or quote survives a paste. */
+const shellQuote = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+/** What the user can do about a refusal, or `undefined` when there is nothing. */
+function remedyFor(r) {
+    switch (r.kind) {
+        case 'not-a-directory':
+            return r.symlink
+                ? `${r.dir} is a symlink where Nx expects a directory. If you did not create it, treat it as hostile: remove the link itself (not what it points at) and run the command again.`
+                : undefined;
+        case 'foreign-owner':
+            return `${r.dir} belongs to another user on this machine, so Nx cannot keep its own directory there. Set NX_SOCKET_DIR to a short directory your user owns, or move it aside — which you can do yourself if you own the directory it sits in, and otherwise needs an administrator.`;
+        case 'not-tightenable':
+            // Both producers reach here having already established that the directory
+            // is ours, so `chmod` is the user's to run. Names no cause: one producer
+            // is a mount that discards the mode, the other is any `chmod` failure.
+            return `${r.dir} is reachable by other users (mode ${asMode(r.mode)}) and Nx could not restrict it. Run \`chmod 0700 ${shellQuote(r.dir)}\` and try again; if the mode does not stick, set NX_SOCKET_DIR to a short directory on a filesystem that keeps POSIX permissions.`;
+        case 'foreign-shared-container':
+            // Unreachable today: `isSafeSharedRoot` denies with this kind only when
+            // `stats.uid !== 0`, so a root-owned container never reaches here.
+            if (r.uid === 0) {
+                return undefined;
+            }
+            const q = shellQuote(r.dir);
+            return `${r.dir} belongs to another user on this machine, so Nx cannot keep a private directory beneath it. Ask an administrator to hand it to root with \`sudo chown root ${q} && sudo chmod 1777 ${q}\`; every user can then keep their own directory under it.`;
+        case 'not-created':
+        case 'not-inspectable':
+        case 'peer-writable-not-sticky':
+            return undefined;
+        default: {
+            // Matches `describeRefusal`'s arm, so a new kind cannot ship with a
+            // sentence and no advice — which is how `not-tightenable` went unadvised.
+            const unhandled = r;
+            return undefined;
+        }
+    }
+}
+/** One refusal as an `Error`, so several can travel in an `AggregateError`. */
+class DirectoryRefusedError extends Error {
+    constructor(refusal) {
+        super(describeRefusal(refusal));
+        this.refusal = refusal;
+        this.name = 'DirectoryRefusedError';
+    }
+}
+exports.DirectoryRefusedError = DirectoryRefusedError;
+/**
+ * chmod a path only if it is a real directory, never following a symlink at its
+ * final component — `chmodSync` follows them, retargeting the mode change. The
+ * directory check is on the descriptor, not the errno: a deny-list fails *open*
+ * on codes it does not know. `O_NONBLOCK` stops a planted FIFO blocking `openSync`.
+ */
+function chmodRealDirectory(path, mode) {
+    let fd;
+    try {
+        fd = (0, node_fs_1.openSync)(path, node_fs_1.constants.O_RDONLY | node_fs_1.constants.O_NOFOLLOW | node_fs_1.constants.O_NONBLOCK);
+    }
+    catch {
+        return false;
+    }
+    try {
+        if (!(0, node_fs_1.fstatSync)(fd).isDirectory()) {
+            return false;
+        }
+        (0, node_fs_1.fchmodSync)(fd, mode);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+}
+/**
+ * Sticky. Restricts rename and unlink in a writable directory to the owner of
+ * each entry — plus the directory's own owner, which is why the ownership check
+ * below is not redundant with this one.
+ */
+const S_ISVTX = 0o1000;
+/**
+ * Whether a shared container is safe to keep an owner-only directory under.
+ *
+ * On POSIX, a container writable by other users must be sticky, and it must be
+ * owned by either root or the current user. Windows short-circuits after the
+ * directory test — the OS temp root is already scoped to one account, so there
+ * is no shared level whose ownership could matter.
+ *
+ * Sticky directories still let the directory's own owner rename entries, so a
+ * container owned by another unprivileged user could replace a previously
+ * verified private directory beneath it.
+ */
+function isSafeSharedRoot(dir) {
+    try {
+        const stats = (0, node_fs_1.lstatSync)(dir);
+        if (!stats.isDirectory()) {
+            return deny(notADirectory(dir, stats));
+        }
+        if (process.platform === 'win32') {
+            // The OS temp root is already scoped to the current Windows user.
+            return allow(dir);
+        }
+        if (typeof process.getuid === 'function' &&
+            stats.uid !== process.getuid() &&
+            stats.uid !== 0) {
+            return deny({ kind: 'foreign-shared-container', dir, uid: stats.uid });
+        }
+        return !(stats.mode & 0o022) || !!(stats.mode & S_ISVTX)
+            ? allow(dir)
+            : deny({ kind: 'peer-writable-not-sticky', dir, mode: stats.mode });
+    }
+    catch (e) {
+        return deny({ kind: 'not-inspectable', dir, code: e?.code });
+    }
+}
+/**
+ * Whether other users on this machine can write into `dir`. Gates whether a
+ * refusal message may cite other users, so it must not over-report: `false` on
+ * Windows, where libuv synthesizes `st_mode` from the READONLY attribute and
+ * reports an ordinary per-account directory as `0666`, and `false` on a path
+ * that cannot be inspected.
+ *
+ * `statSync`, not `lstatSync`: the question is about the directory that will be
+ * used, not the link pointing at it. Link modes mislead in both directions —
+ * Linux creates symlinks `0777`, macOS applies the umask. Nothing here decides
+ * whether a path is accepted, so following the link costs nothing the guards
+ * do not already re-check.
+ */
+function isPeerWritable(dir) {
+    if (process.platform === 'win32') {
+        return false;
+    }
+    try {
+        return !!((0, node_fs_1.statSync)(dir).mode & 0o022);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create a shared container as sticky + world-writable if it does not exist,
+ * and report whether the resulting path is safe for the current user.
+ *
+ * **A container that already exists is never modified — only judged.** Do not
+ * chmod before deciding trust: `CAP_FOWNER` (root's default in Docker and most
+ * CI images) can chmod a directory it does not own, so a peer-owned root would
+ * be widened to `1777` and then refused, and an operator who deliberately
+ * tightened this root would have it re-widened on every `nx` process.
+ */
+function ensureSafeSharedRoot(dir) {
+    if (process.platform === 'win32') {
+        try {
+            (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+            return allow(dir);
+        }
+        catch (e) {
+            return deny({ kind: 'not-created', dir, code: e?.code });
+        }
+    }
+    try {
+        (0, node_fs_1.mkdirSync)(dir, { mode: 0o1777 });
+        // Ours, created a statement ago. Load-bearing on macOS: XNU strips S_ISVTX
+        // at mkdir, so the sticky bit exists solely because of this call.
+        chmodRealDirectory(dir, 0o1777);
+    }
+    catch (e) {
+        if (e?.code !== 'EEXIST') {
+            return deny({ kind: 'not-created', dir, code: e?.code });
+        }
+    }
+    // One verdict for both branches: the chmod above can fail and leave a
+    // peer-writable non-sticky container, which trusting the creation would brand
+    // safe.
+    const verdict = isSafeSharedRoot(dir);
+    return verdict.status === 'ok'
+        ? allow(dir)
+        : deny(verdict.refusal);
+}
+/**
+ * Whether `dir` is an existing real directory owned by us. Unlike
+ * `ensureOwnedPrivateDir` it creates nothing and repairs nothing — for callers
+ * that only want to know whether a path is safe to act on, such as deleting.
+ */
+function isOwnedRealDirectory(dir) {
+    try {
+        const stats = (0, node_fs_1.lstatSync)(dir);
+        if (!stats.isDirectory()) {
+            return null;
+        }
+        return typeof process.getuid !== 'function' ||
+            stats.uid === process.getuid()
+            ? dir
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The path segment separating one user's Nx runtime state from another's. */
+function getUserSegment() {
+    try {
+        if (typeof process.getuid === 'function') {
+            return String(process.getuid());
+        }
+    }
+    catch { }
+    try {
+        const { username } = (0, node_os_1.userInfo)();
+        if (username) {
+            return username;
+        }
+    }
+    catch { }
+    return 'unknown';
+}
+/**
+ * Ensure `dir` exists, is a real directory owned by us, and carries no group or
+ * other bits at all — read and search alone reach a socket inside it, so 0755 is
+ * re-locked rather than accepted. A `refused` status carries which check said
+ * no — usually `foreign-owner` for a directory another user planted, but also
+ * `not-created`/`not-inspectable` for a filesystem error, `not-a-directory`, or
+ * `not-tightenable` when the re-lock did not land.
+ *
+ * Node builtins only: reached from the native binding loader.
+ */
+function ensureOwnedPrivateDir(dir) {
+    try {
+        (0, node_fs_1.mkdirSync)(dir, { mode: 0o700 });
+    }
+    catch (e) {
+        if (e?.code !== 'EEXIST') {
+            return deny({ kind: 'not-created', dir, code: e?.code });
+        }
+    }
+    // One verdict for both branches, as in `ensureSafeSharedRoot`: mounts that
+    // ignore the mode argument can land a directory Nx asked for at 0700 on 0777,
+    // so the creation path is judged like any other.
+    try {
+        const stats = (0, node_fs_1.lstatSync)(dir);
+        // Before the Windows short-circuit: "is a real directory" holds on every
+        // platform.
+        if (!stats.isDirectory()) {
+            return deny(notADirectory(dir, stats));
+        }
+        if (typeof process.getuid !== 'function') {
+            // Windows: the roots there are per-user OS temp dirs, not a shared /tmp.
+            return allow(dir);
+        }
+        if (stats.uid !== process.getuid()) {
+            return deny({ kind: 'foreign-owner', dir, uid: stats.uid });
+        }
+        if (stats.mode & 0o077) {
+            if (!chmodRealDirectory(dir, 0o700)) {
+                return deny({ kind: 'not-tightenable', dir, mode: stats.mode });
+            }
+            // Read the mode back rather than trusting the chmod's return: mounts that
+            // ignore modes report success and change nothing.
+            const after = (0, node_fs_1.lstatSync)(dir);
+            if (after.mode & 0o077) {
+                return deny({ kind: 'not-tightenable', dir, mode: after.mode });
+            }
+        }
+        return allow(dir);
+    }
+    catch (e) {
+        return deny({ kind: 'not-inspectable', dir, code: e?.code });
+    }
+}

package/dist/src/utils/safe-spawn.d.ts

@@ -0,0 +1,24 @@
+import { ChildProcess, ExecFileSyncOptions, SpawnOptions } from 'child_process';
+/**
+ * Spawn a binary that may be a Windows `.cmd`/`.bat` shim, without letting its
+ * arguments become shell syntax.
+ *
+ * Off Windows, and for a `.exe`, no shell is involved at all. Where one is —
+ * a shim or a bare name — the binary and every argument are quoted for cmd.exe.
+ *
+ * Not a complete guarantee: cmd.exe expands `%VAR%` in the binary or any
+ * argument whether or not it is quoted, so a caller with untrusted arguments
+ * inherits that gap (NXC-4798). See the note on `LINE_BREAK` above.
+ *
+ * @throws on Windows when the binary or an argument contains a line break, or a
+ * literal `"` (via `quoteShellArg`). Those are the only refusals — the `%`
+ * expansion above is not one of them.
+ */
+export declare function safeSpawn(binary: string, args: readonly string[], options?: Omit<SpawnOptions, 'shell'>): ChildProcess;
+/**
+ * Synchronous {@link safeSpawn}, returning the child's stdout.
+ *
+ * Carries the same Windows caveats: `%VAR%` is expanded quoted or not
+ * (NXC-4798), and a line break or literal `"` throws.
+ */
+export declare function safeExecFileSync(binary: string, args: readonly string[], options?: Omit<ExecFileSyncOptions, 'encoding' | 'shell'>): string;

package/dist/src/utils/safe-spawn.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.safeSpawn = safeSpawn;
+exports.safeExecFileSync = safeExecFileSync;
+const child_process_1 = require("child_process");
+const path_1 = require("path");
+const shell_quoting_1 = require("./shell-quoting");
+// Node refuses to launch a Windows `.cmd`/`.bat` shim without a shell
+// (CVE-2024-27980). A bare name takes the shell for the same reason, one step
+// removed: libuv walks PATH and PATHEXT itself, so no shell is needed to *find*
+// the binary — but the walk may land on a `.cmd`/`.bat`, and this cannot know
+// which in advance, so it is deliberately conservative. Everything else,
+// including a `.exe`, spawns directly, so the shell and the quoting below reach
+// only the invocations that cannot do without them.
+//
+// Deliberately a function: a module-level const is fixed at import time, which
+// would make the Windows branch untestable.
+function needsShell(binary) {
+    if (process.platform !== 'win32') {
+        return false;
+    }
+    // win32.extname, not the platform default: this branch only runs on Windows,
+    // where `path` is win32 anyway, and pinning it lets a test model the real
+    // parse rather than posix's (which reads `C:\ws\my.app\gradlew` as `.app\gradlew`).
+    const ext = path_1.win32.extname(binary).toLowerCase();
+    return ext === '' || ext === '.cmd' || ext === '.bat';
+}
+// A line break ends the command line whatever the quoting, so nothing can carry
+// one.
+//
+// `%` is deliberately NOT refused, and this is a known gap rather than a safe
+// case. cmd.exe expands `%VAR%` whether or not the value is quoted — see
+// `quoteShellArg`'s own docstring in ./shell-quoting, which says so and pins it
+// with a test — so quoting contains nothing here. It applies to the binary path
+// as much as to the arguments, and an expansion yielding a `"` defeats the
+// literal-quote refusal below, because that inspects the pre-expansion bytes.
+// `bin/nx.ts` loads the workspace's own `.env` before the graph is built, so a
+// repo can set the variable too.
+//
+// Refusing `%` is what an earlier revision did, and it made any workspace under
+// a `%` path — a legal Windows directory name — fail graph construction. The gap
+// is bounded by the argument that bounds this whole class: a repo that can reach
+// here already has `mvnw` / `pom.xml` executing on its behalf. Closing it
+// properly is tracked as NXC-4798.
+const LINE_BREAK = /[\r\n]/;
+/**
+ * Spawn a binary that may be a Windows `.cmd`/`.bat` shim, without letting its
+ * arguments become shell syntax.
+ *
+ * Off Windows, and for a `.exe`, no shell is involved at all. Where one is —
+ * a shim or a bare name — the binary and every argument are quoted for cmd.exe.
+ *
+ * Not a complete guarantee: cmd.exe expands `%VAR%` in the binary or any
+ * argument whether or not it is quoted, so a caller with untrusted arguments
+ * inherits that gap (NXC-4798). See the note on `LINE_BREAK` above.
+ *
+ * @throws on Windows when the binary or an argument contains a line break, or a
+ * literal `"` (via `quoteShellArg`). Those are the only refusals — the `%`
+ * expansion above is not one of them.
+ */
+function safeSpawn(binary, args, options = {}) {
+    const shell = needsShell(binary);
+    return (0, child_process_1.spawn)(quoteBinary(binary, shell), quoteArgs(args, shell), {
+        ...options,
+        windowsHide: true,
+        shell,
+    });
+}
+/**
+ * Synchronous {@link safeSpawn}, returning the child's stdout.
+ *
+ * Carries the same Windows caveats: `%VAR%` is expanded quoted or not
+ * (NXC-4798), and a line break or literal `"` throws.
+ */
+function safeExecFileSync(binary, args, options = {}) {
+    const shell = needsShell(binary);
+    return (0, child_process_1.execFileSync)(quoteBinary(binary, shell), quoteArgs(args, shell), {
+        stdio: 'pipe',
+        ...options,
+        windowsHide: true,
+        shell,
+        encoding: 'utf-8',
+    });
+}
+// The binary needs quoting too: Node joins it into the same command line, so a
+// path holding a space or an `&` would split there.
+function quoteBinary(binary, shell) {
+    if (!shell) {
+        return binary;
+    }
+    return quoteForCmd(binary, `the path ${JSON.stringify(binary)}`);
+}
+function quoteForCmd(value, described, remedy = '') {
+    if (LINE_BREAK.test(value)) {
+        throw new Error(`Cannot pass ${described} to cmd.exe: a line break inside it would end the command line before cmd.exe reached the rest of it.${remedy}`);
+    }
+    return (0, shell_quoting_1.quoteShellArg)(value);
+}
+function quoteArgs(args, shell) {
+    if (!shell) {
+        return [...args];
+    }
+    return args.map((arg) => quoteForCmd(arg, `the argument ${JSON.stringify(arg)}`, ' Remove it from your Nx configuration and try again.'));
+}

package/dist/src/utils/shell-quoting.d.ts

@@ -8,3 +8,18 @@ export declare function needsShellQuoting(str: string): boolean;
  * Check if a string is already wrapped in matching quotes (single or double).
  */
 export declare function isAlreadyQuoted(str: string): boolean;
+/**
+ * Quote a string so it survives being interpolated into a shell command line
+ * as a single argument.
+ *
+ * On Windows the safety boundary is one unbroken double-quoted run: it keeps
+ * `^`, `&`, `|`, `<` and `>` literal through cmd.exe's parse and a `.cmd`
+ * shim's re-parse of `%*`, but not `%`, which cmd.exe expands inside double
+ * quotes too.
+ *
+ * @throws on Windows when the argument contains a double quote, which ends that
+ * run, since cmd.exe recognizes no backslash escape. Carrying one means
+ * caret-escaping every metacharacter instead, doubled for a `.cmd` shim, which
+ * this path does not implement.
+ */
+export declare function quoteShellArg(arg: string): string;

package/dist/src/utils/shell-quoting.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.needsShellQuoting = needsShellQuoting;
 exports.isAlreadyQuoted = isAlreadyQuoted;
+exports.quoteShellArg = quoteShellArg;
 /**
  * Shell metacharacters that have special meaning and require quoting.
  *
@@ -39,3 +40,37 @@ function isAlreadyQuoted(str) {
         ((str[0] === "'" && str[str.length - 1] === "'") ||
             (str[0] === '"' && str[str.length - 1] === '"')));
 }
+/**
+ * Quote a string so it survives being interpolated into a shell command line
+ * as a single argument.
+ *
+ * On Windows the safety boundary is one unbroken double-quoted run: it keeps
+ * `^`, `&`, `|`, `<` and `>` literal through cmd.exe's parse and a `.cmd`
+ * shim's re-parse of `%*`, but not `%`, which cmd.exe expands inside double
+ * quotes too.
+ *
+ * @throws on Windows when the argument contains a double quote, which ends that
+ * run, since cmd.exe recognizes no backslash escape. Carrying one means
+ * caret-escaping every metacharacter instead, doubled for a `.cmd` shim, which
+ * this path does not implement.
+ */
+function quoteShellArg(arg) {
+    const isWindows = process.platform === 'win32';
+    if (isWindows && arg.includes('"')) {
+        throw new Error(`Cannot safely pass ${arg} to cmd.exe as a single argument: a double quote inside it would end the quoting and leave the rest of the argument to be read as commands. Remove the double quote and run the command again.`);
+    }
+    if (arg === '') {
+        // an unquoted empty string would vanish when joined into a command line
+        return isWindows ? '""' : "''";
+    }
+    // `^` is cmd.exe syntax rather than shell syntax, so it earns quoting only
+    // where cmd.exe parses the command line.
+    if (!needsShellQuoting(arg) && !(isWindows && arg.includes('^'))) {
+        return arg;
+    }
+    return isWindows
+        ? // MSVCRT reads the backslashes that precede the closing quote as escapes,
+            // so they have to be doubled to survive as themselves.
+            `"${arg.replace(/(\\+)$/, '$1$1')}"`
+        : `'${arg.replace(/'/g, `'\\''`)}'`;
+}

package/dist/src/utils/wait-for-socket-connection.d.ts

@@ -12,4 +12,15 @@ export declare function waitForSocketConnection(socketPath: string | (() => stri
     signal?: AbortSignal;
     maxAttempts?: number;
     delayMs?: number;
+    /**
+     * Called with the errno of each failed connect and the path it was made
+     * against. Return `true` to stop polling: a permission refusal does not
+     * heal by retrying, and without a way out the caller waits the full budget
+     * and then cannot say why.
+     *
+     * The path is passed rather than left to the caller to recompute — with a
+     * resolver it can differ per attempt, and the caller that reports the
+     * refusal may no longer be able to resolve one at all.
+     */
+    onConnectError?: (error: NodeJS.ErrnoException, socketPath: string) => boolean | void;
 }): Promise<Socket | null>;