@sentenel/node-utils 0.1.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@sentenel/node-utils",
+  "version": "0.1.0",
+  "description": "Reusable Node utilities for Sentenel (paths, dotenv helpers)",
+  "license": "MIT",
+  "author": "aarya11 <arpitarya@users.noreply.github.com>",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js",
+      "types": "./dist/types/index.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "sentenel",
+    "node",
+    "utils",
+    "paths",
+    "dotenv"
+  ],
+  "devDependencies": {
+    "@biomejs/biome": "2.3.14",
+    "@rstest/core": "0.8.3",
+    "@types/node": "25.2.1",
+    "chalk": "5.6.2",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "dotenv": "17.2.4",
+    "dotenv-expand": "12.0.3"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "dev": "rslib dev",
+    "test": "rstest"
+  }
+}

package/src/dotenv/dotenv.async.ts

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+
+const { NODE_ENV } = process.env;
+
+async function asyncExpandDotEnv(path: string): Promise<void> {
+  // https://github.com/bkeepers/dotenv#what-other-env-files-can-i-use
+  const dotenvFiles = [
+    `${path}.${NODE_ENV}.local`,
+    `${path}.${NODE_ENV}`,
+    // Don't include `.env.local` for `test` environment to avoid
+    // polluting test environments with local development settings
+    NODE_ENV !== "test" ? `${path}.local` : null,
+    path,
+  ].filter(Boolean) as string[];
+
+  // Load environment variables from .env* files in order
+  // https://github.com/motdotla/dotenv
+  // https://github.com/motedotla/dotenv-expand
+  await Promise.all(
+    dotenvFiles.map(async (dotenvFile) => {
+      if (existsSync(dotenvFile)) {
+        import("dotenv-expand").then(async () => {
+          import("dotenv").then((config) => {
+            config.config({ path: dotenvFile });
+          });
+        });
+      }
+    }),
+  );
+}
+
+export { asyncExpandDotEnv };

package/src/dotenv/dotenv.sync.ts

@@ -0,0 +1,28 @@
+import { existsSync } from "node:fs";
+import { config } from "dotenv";
+import { expand } from "dotenv-expand";
+
+const { NODE_ENV } = process.env;
+
+async function syncExpandDotEnv(path: string): Promise<void> {
+  // https://github.com/bkeepers/dotenv#what-other-env-files-can-i-use
+  const dotenvFiles = [
+    `${path}.${NODE_ENV}.local`,
+    `${path}.${NODE_ENV}`,
+    // Don't include `.env.local` for `test` environment to avoid
+    // polluting test environments with local development settings
+    NODE_ENV !== "test" ? `${path}.local` : null,
+    path,
+  ].filter(Boolean) as string[];
+
+  // Load environment variables from .env* files in order
+  // https://github.com/motdotla/dotenv
+  // https://github.com/motedotla/dotenv-expand
+  dotenvFiles.map(async (dotenvFile) => {
+    if (existsSync(dotenvFile)) {
+      expand(config({ path: dotenvFile }));
+    }
+  });
+}
+
+export { syncExpandDotEnv };

package/src/dotenv/index.ts

@@ -0,0 +1,2 @@
+export * from './dotenv.async';
+export * from './dotenv.sync';

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./dotenv";
+export * from "./paths";

package/src/paths/index.ts

@@ -0,0 +1 @@
+export * from "./paths";

package/src/paths/paths.test.ts

@@ -0,0 +1,107 @@
+import { afterEach, beforeEach, describe, expect, it } from "@rstest/core";
+import { resolveRootPath, resolveWorkspaceDirectory } from "./paths";
+
+describe("Paths Utilities", () => {
+  const originalEnv = process.env;
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  describe("resolveRootPath", () => {
+    it("should resolve a relative path against the root working directory", () => {
+      process.env.ROOT_WORKING_DIRECTORY = "/home/user/projects/sentenel";
+      const result = resolveRootPath("src/index.ts");
+      expect(result).toContain("src/index.ts");
+    });
+
+    it("should handle absolute paths correctly", () => {
+      process.env.ROOT_WORKING_DIRECTORY = "/home/user/projects/sentenel";
+      const result = resolveRootPath("packages/node-utils");
+      expect(result).toContain("packages/node-utils");
+    });
+
+    it("should throw error when root working directory is not defined", () => {
+      // Note: rootWorkingDirectory falls back to currentWorkingDirectory,
+      // so it will never be undefined. This test documents that behavior.
+      process.env.ROOT_WORKING_DIRECTORY = "/home/user/projects/sentenel";
+      const result = resolveRootPath("src/index.ts");
+      expect(result).toContain("src/index.ts");
+    });
+
+    it("should handle empty relative path", () => {
+      process.env.ROOT_WORKING_DIRECTORY = "/home/user/projects/sentenel";
+      const result = resolveRootPath("");
+      expect(result).toContain("sentenel");
+    });
+
+    it("should handle nested relative paths", () => {
+      process.env.ROOT_WORKING_DIRECTORY = "/home/user/projects/sentenel";
+      const result = resolveRootPath("packages/node-utils/src/index.ts");
+      expect(result).toContain("packages/node-utils/src/index.ts");
+    });
+
+    it("should handle paths with .. navigation", () => {
+      process.env.ROOT_WORKING_DIRECTORY = "/home/user/projects/sentenel";
+      const result = resolveRootPath("packages/../src");
+      expect(result).toContain("src");
+    });
+  });
+
+  describe("resolveWorkspaceDirectory", () => {
+    it("should resolve a relative path against the current working directory", () => {
+      const result = resolveWorkspaceDirectory("src/index.ts");
+      expect(result).toContain("src/index.ts");
+    });
+
+    it("should handle absolute paths correctly", () => {
+      const result = resolveWorkspaceDirectory("packages/node-utils");
+      expect(result).toContain("packages/node-utils");
+    });
+
+    it("should throw error when current working directory is not defined", () => {
+      expect(() => {
+        resolveWorkspaceDirectory("src/index.ts");
+      }).not.toThrow();
+    });
+
+    it("should handle empty relative path", () => {
+      const result = resolveWorkspaceDirectory("");
+      expect(result).toBeTruthy();
+    });
+
+    it("should handle nested relative paths", () => {
+      const result = resolveWorkspaceDirectory("packages/node-utils/src/index.ts");
+      expect(result).toContain("packages/node-utils/src/index.ts");
+    });
+
+    it("should handle paths with .. navigation", () => {
+      const result = resolveWorkspaceDirectory("packages/../src");
+      expect(result).toContain("src");
+    });
+  });
+
+  describe("Path resolution integration", () => {
+    it("should resolve different paths consistently when environment is set", () => {
+      process.env.ROOT_WORKING_DIRECTORY = "/home/user/projects/sentenel";
+
+      const rootPath1 = resolveRootPath("src/utils");
+      const rootPath2 = resolveRootPath("src/utils");
+
+      expect(rootPath1).toBe(rootPath2);
+    });
+
+    it("should normalize paths correctly", () => {
+      process.env.ROOT_WORKING_DIRECTORY = "/home/user/projects/sentenel";
+
+      const result1 = resolveRootPath("./src/index.ts");
+      const result2 = resolveRootPath("src/index.ts");
+
+      expect(result1).toBe(result2);
+    });
+  });
+});

package/src/paths/paths.ts

@@ -0,0 +1,33 @@
+import { realpathSync } from "node:fs";
+import * as path from "node:path";
+import { ProcessEnvProp } from "./root.path.global";
+
+const currentWorkingDirectory: string = realpathSync(process.cwd());
+const rootWorkingDirectory: string = realpathSync(
+  process.env[ProcessEnvProp.RootWorkingDirectory] || currentWorkingDirectory,
+);
+
+function resolveRootPath(relativePath: string): string {
+  if (!rootWorkingDirectory) {
+    console.log(
+      `Define "process.env[ProcessEnvProp.WorkingDirLogsLevel]"='none' | 'info' | 'verbose' to enable logging of the working directory resolution process.`,
+    );
+    throw new Error(
+      `Root working directory is not defined. Please set the environment variable ${ProcessEnvProp.RootWorkingDirectory} to the desired root working directory path.`,
+    );
+  }
+
+  return path.resolve(rootWorkingDirectory, relativePath);
+}
+
+function resolveWorkspaceDirectory(relativePath: string): string {
+  if (!currentWorkingDirectory) {
+    throw new Error(
+      `Current working directory is not defined. Please set the environment variable ${ProcessEnvProp.RootWorkingDirectory} to the desired root working directory path.`,
+    );
+  }
+
+  return path.resolve(currentWorkingDirectory, relativePath);
+}
+
+export { resolveRootPath, resolveWorkspaceDirectory };

package/src/paths/root.path.global.ts

@@ -0,0 +1,124 @@
+import { readFileSync, realpathSync } from "node:fs";
+import Module from "node:module";
+import chalk from "chalk";
+
+enum ProcessEnvProp {
+  WorkingDirLogsLevel = "ENABLE_WORKING_DIR_LOGS_LEVEL",
+  RootWorkingDirectory = "ROOT_WORKING_DIRECTORY",
+}
+
+enum WorkingDirLogsLevel {
+  None = "none",
+  Info = "info",
+  Verbose = "verbose",
+}
+
+function logInfo(...args: unknown[]): void {
+  console.info("SENTENEL PATH::", chalk.blueBright(...args.map((arg) => String(arg))));
+}
+
+function getRootWorkingDirectory(): string | undefined {
+  const workingDirLogsLevel: WorkingDirLogsLevel =
+    (process.env[ProcessEnvProp.WorkingDirLogsLevel] as WorkingDirLogsLevel) || WorkingDirLogsLevel.None;
+  if (!Object.values(WorkingDirLogsLevel).includes(workingDirLogsLevel)) {
+    console.error(
+      `Invalid value for environment variable ${ProcessEnvProp.WorkingDirLogsLevel}: ${workingDirLogsLevel}. Defaulting to ${WorkingDirLogsLevel.None}.`,
+    );
+  }
+  if (workingDirLogsLevel === WorkingDirLogsLevel.Info || workingDirLogsLevel === WorkingDirLogsLevel.Verbose) {
+    logInfo(`Getting root working directory from environment variable ${ProcessEnvProp.RootWorkingDirectory}...`);
+  }
+
+  const isVerbose = workingDirLogsLevel === WorkingDirLogsLevel.Verbose;
+  const isInfo = workingDirLogsLevel === WorkingDirLogsLevel.Info || isVerbose;
+
+  const currentWorkingDirectory: string = realpathSync(process.cwd());
+
+  const nodeModulesPathList: string[] = (Module as any)._nodeModulePaths(currentWorkingDirectory);
+
+  isVerbose && logInfo("Current working directory:", currentWorkingDirectory);
+  isVerbose && logInfo("Node modules path list:", nodeModulesPathList);
+
+  const packageJsonPathList: string[] = nodeModulesPathList.map((nodeModulesPath: string) => {
+    const packageJsonPath = nodeModulesPath.replace("node_modules", "package.json");
+    return packageJsonPath;
+  });
+
+  isVerbose && logInfo("Package.json path list:", packageJsonPathList);
+
+  const packageJsonExistsPathList: string[] = packageJsonPathList.filter((packageJsonPath: string) => {
+    try {
+      realpathSync(packageJsonPath);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+
+  isVerbose && logInfo("Existing package.json path list:", packageJsonExistsPathList);
+
+  if (packageJsonExistsPathList.length === 0) {
+    isInfo && logInfo("No package.json found in node modules paths.");
+  }
+
+  const workspacePackageJsonList: string[] = packageJsonExistsPathList.filter((packageJsonPath: string) => {
+    const packageJsonBuffer = readFileSync(packageJsonPath);
+
+    //@ts-expect-error
+    const packageJsonContent = JSON.parse(packageJsonBuffer);
+
+    if (packageJsonContent?.workspaces && packageJsonContent?.workspaces.length > 0) {
+      return true;
+    }
+    return false;
+  });
+
+  isVerbose && logInfo("Workspace package.json list:", workspacePackageJsonList);
+
+  if (workspacePackageJsonList.length === 0) {
+    isInfo && logInfo("No workspace package.json found in node modules paths.");
+
+    const rootWorkingDirectory = currentWorkingDirectory;
+    if (!rootWorkingDirectory) {
+      throw new Error(`Environment variable ${ProcessEnvProp.RootWorkingDirectory} is not set.`);
+    }
+
+    isInfo && logInfo(`Current working directory determined: ${currentWorkingDirectory}`);
+    isInfo && logInfo(`Root working directory determined: ${rootWorkingDirectory}`);
+    process.env[ProcessEnvProp.RootWorkingDirectory] = rootWorkingDirectory;
+
+    return rootWorkingDirectory;
+  }
+
+  if (workspacePackageJsonList.length === 1) {
+    isInfo && logInfo(`Single workspace package.json file found: ${workspacePackageJsonList[0]}`);
+
+    const rootPackageJsonPath: string = realpathSync(workspacePackageJsonList[0]);
+    const rootWorkingDirectory: string = rootPackageJsonPath.replace("/package.json", "");
+
+    isInfo && logInfo(`Current working directory determined: ${currentWorkingDirectory}`);
+    isInfo && logInfo(`Root working directory determined: ${rootWorkingDirectory}`);
+    process.env[ProcessEnvProp.RootWorkingDirectory] = rootWorkingDirectory;
+
+    return rootWorkingDirectory;
+  }
+
+  if (workspacePackageJsonList.length > 1) {
+    isInfo && logInfo(`Multiple workspace package.json files found: ${workspacePackageJsonList.join(", ")}`);
+
+    // Fallback (should not reach here)
+    const rootWorkingDirectory = currentWorkingDirectory;
+
+    isInfo && logInfo(`Current working directory determined (fallback): ${currentWorkingDirectory}`);
+    isInfo && logInfo(`Root working directory determined (fallback): ${rootWorkingDirectory}`);
+    process.env[ProcessEnvProp.RootWorkingDirectory] = rootWorkingDirectory;
+
+    return rootWorkingDirectory;
+  }
+
+  console.error("Unable to determine root working directory.");
+}
+
+getRootWorkingDirectory();
+
+export { ProcessEnvProp, WorkingDirLogsLevel, getRootWorkingDirectory };