@theholocron/fs-utils 1.15.0 → 1.16.0

package/README.md

@@ -17,6 +17,7 @@ import {
   findRoot,
   findUpward,
   hasGitEntry,
+  isWorkspaceRoot,
   walkFilesSync,
 } from "@theholocron/fs-utils";
 
@@ -33,6 +34,9 @@ const configDir = await findUpward(
 
 // a plain boundary check, usable as `findUpward`'s `stop` or on its own
 await hasGitEntry("/path/to/dir"); // true if a .git entry (file or folder) exists there
+
+// decide whether a pnpm command needs -w at this directory
+await isWorkspaceRoot(repoRoot ?? process.cwd());
 ```
 
 ### `findUpward(startDir, check, stop?)`
@@ -113,6 +117,13 @@ checkout, a file in a worktree/submodule (existence is all that matters).
 A common `stop` boundary for `findUpward`: treat the nearest `.git` as
 the project root, searched but not walked past.
 
+### `isWorkspaceRoot(dir)`
+
+Returns `true` when `dir` has a `pnpm-workspace.yaml` — the file that marks
+a pnpm workspace root. Several pnpm CLI commands (`pnpm add` among them)
+behave differently at a workspace root than in a plain package, so a caller
+shelling out to pnpm can check this before deciding which flags to pass.
+
 ## Documentation
 
 Check out [The Holocron Archive](https://docs.theholocron.dev/projects/utils/) for more information.

package/dist/index.d.mts

@@ -89,6 +89,25 @@ export declare function findUpward<T>(startDir: string, check: (dir: string) =>
  */
 export declare function hasGitEntry(dir: string): Promise<boolean>;
 //#endregion
+//#region src/is-workspace-root.d.ts
+/**
+ * `true` when `dir` has a `pnpm-workspace.yaml` regular file — the marker
+ * of a pnpm workspace root. Several pnpm CLI commands (`pnpm add` among
+ * them) behave differently at a workspace root than in a plain package,
+ * so callers shelling out to pnpm need this check before deciding which
+ * flags to pass.
+ *
+ * `dir` is resolved to an absolute path up front — a relative `dir`
+ * resolved lazily inside the `stat` call could end up checking a
+ * different directory if `process.chdir()` runs on another task while
+ * this one is pending. A directory or symlink-to-directory named
+ * `pnpm-workspace.yaml` doesn't count (pnpm never creates one of those);
+ * only `stat`'s `ENOENT` means "not there" — any other error (`EACCES`,
+ * a transient I/O failure) propagates rather than silently reading as
+ * "not a workspace."
+ */
+export declare function isWorkspaceRoot(dir: string): Promise<boolean>;
+//#endregion
 //#region src/walk-files.d.ts
 export interface WalkFilesOptions {
   /** Directory names not descended into, at any depth (files with these names are still listed). Defaults to `.git` and `node_modules`. */

package/dist/index.mjs

@@ -190,6 +190,32 @@ function findRootSync(startDir, marker, options = {}) {
 	}
 }
 //#endregion
+//#region src/is-workspace-root.ts
+/**
+* `true` when `dir` has a `pnpm-workspace.yaml` regular file — the marker
+* of a pnpm workspace root. Several pnpm CLI commands (`pnpm add` among
+* them) behave differently at a workspace root than in a plain package,
+* so callers shelling out to pnpm need this check before deciding which
+* flags to pass.
+*
+* `dir` is resolved to an absolute path up front — a relative `dir`
+* resolved lazily inside the `stat` call could end up checking a
+* different directory if `process.chdir()` runs on another task while
+* this one is pending. A directory or symlink-to-directory named
+* `pnpm-workspace.yaml` doesn't count (pnpm never creates one of those);
+* only `stat`'s `ENOENT` means "not there" — any other error (`EACCES`,
+* a transient I/O failure) propagates rather than silently reading as
+* "not a workspace."
+*/
+async function isWorkspaceRoot(dir) {
+	try {
+		return (await stat(join(resolve(dir), "pnpm-workspace.yaml"))).isFile();
+	} catch (err) {
+		if (err.code === "ENOENT") return false;
+		throw err;
+	}
+}
+//#endregion
 //#region src/walk-files.ts
 const DEFAULT_SKIP = [".git", "node_modules"];
 /** The entry's type, asking the filesystem when the platform's directory listing couldn't say. */
@@ -239,4 +265,4 @@ function walkFilesSync(dir, options = {}) {
 	return files;
 }
 //#endregion
-export { findExecutable, findExecutableSync, findRoot, findRootSync, findUpward, hasGitEntry, walkFilesSync };
+export { findExecutable, findExecutableSync, findRoot, findRootSync, findUpward, hasGitEntry, isWorkspaceRoot, walkFilesSync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theholocron/fs-utils",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Walk a directory tree upward to find the nearest match or project root.",
   "keywords": [
     "filesystem",