@somewhatabstract/x 0.0.1 → 0.1.0

package/dist/x.mjs

@@ -1,12 +1,287 @@
 #!/usr/bin/env node
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import { getPackages } from "@manypkg/get-packages";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as path$1 from "node:path";
+import path from "node:path";
+import { findRoot } from "@manypkg/find-root";
+
+//#region src/errors.ts
+/**
+* Error class for known/expected errors that should be displayed to the user
+* without a stack trace.
+*/
+var HandledError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "HandledError";
+	}
+};
+
+//#endregion
+//#region src/discover-packages.ts
+/**
+* Discover all packages in the workspace using @manypkg/get-packages.
+* Supports multiple package managers: npm, yarn, pnpm, lerna, bun, rush.
+*
+* @param workspaceRoot - The absolute path to the workspace root
+* @returns Array of package information
+* @throws {HandledError} If package discovery fails
+*/
+async function discoverPackages(workspaceRoot) {
+	try {
+		return (await getPackages(workspaceRoot)).packages.map((pkg) => ({
+			name: pkg.packageJson.name,
+			path: pkg.dir,
+			version: pkg.packageJson.version || "unknown"
+		}));
+	} catch (error) {
+		if (error instanceof HandledError) throw error;
+		throw new HandledError(`Failed to discover packages`, { cause: error });
+	}
+}
+
+//#endregion
+//#region src/build-environment.ts
+/**
+* Build environment variables for script execution that mimics npm/pnpm behavior.
+* The environment is set as if the package were installed at the workspace root.
+*
+* @param workspaceRoot - Path to the workspace root
+* @param currentEnv - Current environment variables (usually process.env)
+* @returns Environment object to pass to child_process.spawn
+*/
+async function buildEnvironment(workspaceRoot, currentEnv) {
+	let workspacePackageJson = {};
+	try {
+		const packageJsonPath = path$1.join(workspaceRoot, "package.json");
+		const content = await fs.readFile(packageJsonPath, "utf-8");
+		workspacePackageJson = JSON.parse(content);
+	} catch {}
+	let ourPackageVersion = "0.0.0-development";
+	try {
+		const ownPackageJsonPath = path$1.join(__dirname, "..", "package.json");
+		const ownPackageJsonContent = await fs.readFile(ownPackageJsonPath, "utf-8");
+		const ownPackageJson = JSON.parse(ownPackageJsonContent);
+		if (typeof ownPackageJson.version === "string") ourPackageVersion = ownPackageJson.version;
+	} catch {}
+	const env = {
+		...currentEnv,
+		PATH: [path$1.join(workspaceRoot, "node_modules", ".bin"), currentEnv.PATH].filter(Boolean).join(path$1.delimiter),
+		npm_command: "exec",
+		npm_execpath: process.execPath,
+		npm_node_execpath: process.execPath,
+		NODE: process.execPath,
+		INIT_CWD: process.cwd(),
+		npm_config_user_agent: `x/${ourPackageVersion} node/${process.version} ${process.platform} ${process.arch}`
+	};
+	if (workspacePackageJson.name) env.npm_package_name = workspacePackageJson.name;
+	if (workspacePackageJson.version) env.npm_package_version = workspacePackageJson.version;
+	if (workspacePackageJson.description) env.npm_package_description = workspacePackageJson.description;
+	for (const field of [
+		"author",
+		"license",
+		"homepage",
+		"repository",
+		"bugs",
+		"keywords"
+	]) if (workspacePackageJson[field]) {
+		const value = workspacePackageJson[field];
+		env[`npm_package_${field}`] = typeof value === "string" ? value : JSON.stringify(value);
+	}
+	return env;
+}
+
+//#endregion
+//#region src/is-node-executable.ts
+/**
+* Determine if a bin file should be invoked via the Node executable,
+* based on its file extension (case-insensitive).
+* Matches npm's behavior for .js, .mjs, and .cjs files.
+*
+* @param binPath - The path to the bin file
+* @returns True if the file should be invoked via node
+*/
+function isNodeExecutable(binPath) {
+	const lower = binPath.toLowerCase();
+	return lower.endsWith(".js") || lower.endsWith(".mjs") || lower.endsWith(".cjs");
+}
+
+//#endregion
+//#region src/execute-script.ts
+/**
+* Execute a bin script with the given arguments.
+* Executes the script as if the package were installed at the workspace root,
+* with npm/pnpm-style environment variables.
+*
+* @param bin - The bin info to execute
+* @param args - Arguments to pass to the script
+* @param workspaceRoot - Path to the workspace root
+* @returns A promise that resolves with the exit code
+*/
+async function executeScript(bin, args, workspaceRoot) {
+	const env = await buildEnvironment(workspaceRoot, process.env);
+	const [executable, spawnArgs] = isNodeExecutable(bin.binPath) ? [process.execPath, [bin.binPath, ...args]] : [bin.binPath, args];
+	return new Promise((resolve) => {
+		const child = spawn(executable, spawnArgs, {
+			stdio: "inherit",
+			env
+		});
+		child.on("error", (_) => {
+			resolve(1);
+		});
+		child.on("exit", (code, signal) => {
+			if (signal) resolve(1);
+			else resolve(code ?? 1);
+		});
+	});
+}
+
+//#endregion
+//#region src/resolve-bin-path.ts
+/**
+* Resolve a bin script to the actual file path.
+*
+* This function ensures that the resolved bin path is within the package
+* directory to prevent path traversal issues.
+*
+* @param pkg - The package information containing the path to the package
+* @param bin - The bin entry from package.json, which can be a string or an
+* object
+* @param binName - The name of the bin as specified in package.json
+* @returns The resolved absolute path to the bin script, or null if invalid
+
+*/
+function resolveBinPath(pkg, bin, binName) {
+	const binPath = !bin ? null : typeof bin === "string" && pkg.name === binName ? bin : typeof bin === "object" && bin[binName] ? bin[binName] : null;
+	if (!binPath) return null;
+	const packageDir = path.resolve(pkg.path);
+	const resolvedBinPath = path.resolve(pkg.path, binPath);
+	if (resolvedBinPath !== packageDir && !resolvedBinPath.startsWith(packageDir + path.sep)) return null;
+	return resolvedBinPath;
+}
+
+//#endregion
+//#region src/find-matching-bins.ts
+/**
+* Find all packages that have a bin script matching the given name.
+*
+* @param packages - List of packages from discoverPackages
+* @param binName - Name of the bin script to find
+* @returns Array of matching bin information
+*/
+async function findMatchingBins(packages, binName) {
+	const matches = [];
+	for (const pkg of packages) try {
+		const packageJsonPath = path$1.join(pkg.path, "package.json");
+		const packageJsonContent = await fs.readFile(packageJsonPath, "utf-8");
+		const bin = JSON.parse(packageJsonContent).bin;
+		const resolvedBinPath = resolveBinPath(pkg, bin, binName);
+		if (!resolvedBinPath) continue;
+		matches.push({
+			packageName: pkg.name,
+			packagePath: pkg.path,
+			binName,
+			binPath: resolvedBinPath
+		});
+	} catch (error) {
+		if (error instanceof SyntaxError) console.warn(`Warning: Failed to parse package.json for package "${pkg.name}" at "${pkg.path}": invalid JSON.`);
+		else if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {} else console.warn(`Warning: Could not read package.json for package "${pkg.name}" at "${pkg.path}":`, error);
+	}
+	return matches;
+}
+
+//#endregion
+//#region src/find-workspace-root.ts
+/**
+* Find the workspace root using @manypkg/find-root.
+* Supports multiple package managers: npm, yarn, pnpm, lerna, bun, rush.
+*
+* @param startDir - Directory to start searching from (defaults to cwd)
+* @returns The absolute path to the workspace root
+* @throws {HandledError} If workspace root cannot be found
+*/
+async function findWorkspaceRoot(startDir = process.cwd()) {
+	try {
+		return (await findRoot(startDir)).rootDir;
+	} catch (error) {
+		throw new HandledError("Could not find workspace root. Make sure you're in a monorepo workspace.", { cause: error });
+	}
+}
+
+//#endregion
 //#region src/x-impl.ts
-function xImpl() {
-	console.log("Hello, world!");
+/**
+* Main implementation of the x command.
+* Finds and executes a bin script from any package in the workspace.
+*
+* @param scriptName - Name of the bin script to execute
+* @param args - Arguments to pass to the script
+* @param options - Additional options
+* @returns Result object with exit code
+*/
+async function xImpl(scriptName, args = [], options = {}) {
+	try {
+		if (!scriptName || !scriptName.trim()) throw new HandledError("Script name cannot be empty");
+		if (scriptName.includes("/") || scriptName.includes("\\")) throw new HandledError("Script name cannot contain path separators");
+		const workspaceRoot = await findWorkspaceRoot();
+		const packages = await discoverPackages(workspaceRoot);
+		if (packages.length === 0) throw new HandledError("No packages found in workspace. Is this a valid monorepo?");
+		const matchingBins = await findMatchingBins(packages, scriptName);
+		if (matchingBins.length === 0) throw new HandledError(`No bin script named "${scriptName}" found in any workspace package.`);
+		if (matchingBins.length > 1) {
+			console.error(`Multiple packages provide bin "${scriptName}". Please be more specific.`);
+			console.error("\nMatching packages:");
+			matchingBins.forEach((bin) => {
+				console.error(`  - ${bin.packageName} (${bin.packagePath})`);
+			});
+			throw new HandledError(`Ambiguous bin name "${scriptName}". Found ${matchingBins.length} matches.`);
+		}
+		const bin = matchingBins[0];
+		if (options.dryRun) {
+			console.log(`Would execute: ${bin.binName} from ${bin.packageName}`);
+			console.log(`  Binary: ${bin.binPath}`);
+			console.log(`  Arguments: ${args.join(" ")}`);
+			return { exitCode: 0 };
+		}
+		return { exitCode: await executeScript(bin, args, workspaceRoot) };
+	} catch (error) {
+		if (error instanceof HandledError) {
+			console.error(`Error: ${error.message}`);
+			return { exitCode: 1 };
+		}
+		throw error;
+	}
 }
 
 //#endregion
 //#region src/bin/x.ts
-xImpl();
+const argv = yargs(hideBin(process.argv)).usage("Usage: $0 <script-name> [...args]").command("$0 <script-name> [args..]", "Execute a bin script from any package in the workspace", (yargs) => {
+	return yargs.positional("script-name", {
+		describe: "Name of the bin script to execute",
+		type: "string",
+		demandOption: true
+	}).positional("args", {
+		describe: "Arguments to pass to the script",
+		type: "string",
+		array: true,
+		default: []
+	});
+}).option("dry-run", {
+	alias: "d",
+	describe: "Show what would be executed without running it",
+	type: "boolean",
+	default: false
+}).help().alias("help", "h").version().alias("version", "v").example("$0 tsc --noEmit", "Run TypeScript compiler from any package").example("$0 eslint src/", "Run ESLint from any package that provides it").example("$0 --dry-run jest", "Preview which jest would be executed").strict().parseSync();
+const scriptName = argv["script-name"];
+xImpl(scriptName, argv._ || [], { dryRun: argv["dry-run"] }).then((result) => {
+	process.exit(result.exitCode);
+}).catch((error) => {
+	console.error("Unexpected error:", error);
+	process.exit(1);
+});
 
 //#endregion
 export {  };

package/package.json

@@ -2,12 +2,14 @@
   "name": "@somewhatabstract/x",
   "private": false,
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "bin": {
     "x": "./dist/x.mjs"
   },
-  "version": "0.0.1",
+  "type": "module",
+  "version": "0.1.0",
   "description": "Execute any bin defined by any package in a monorepo without needing to install that package",
   "bugs": {
     "url": "https://github.com/somewhatabstract/x/issues"
@@ -22,18 +24,26 @@
     "yarn": "please-use-pnpm"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.3",
     "@changesets/cli": "^2.29.8",
     "@codecov/rollup-plugin": "^1.9.1",
     "@types/node": "^20.19.29",
+    "@types/yargs": "^17.0.35",
     "@vitest/coverage-v8": "^4.0.17",
-    "tsdown": "0.20.0-beta.3",
+    "tsdown": "0.20.3",
     "typescript": "^5.9.3",
     "vitest": "^4.0.17"
   },
+  "dependencies": {
+    "@manypkg/find-root": "^3.1.0",
+    "@manypkg/get-packages": "^3.1.0",
+    "yargs": "^18.0.0"
+  },
   "scripts": {
     "build": "tsdown",
     "dev": "tsdown --watch",
-    "lint": "echo \"No linting configured\"",
+    "lint": "biome check",
+    "lint:fix": "biome check --write --unsafe",
     "typecheck": "tsc --noEmit --project tsconfig.json",
     "typewatch": "pnpm typecheck --watch",
     "test": "vitest",

package/src/__tests__/build-environment.test.ts

@@ -0,0 +1,285 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import {beforeEach, describe, expect, it, vi} from "vitest";
+import {buildEnvironment} from "../build-environment";
+
+// Mock the fs module
+vi.mock("node:fs/promises", () => ({
+    readFile: vi.fn(),
+}));
+
+describe("buildEnvironment", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it("should preserve existing environment variables", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {
+            EXISTING_VAR: "existing-value",
+            PATH: "/usr/bin:/bin",
+        };
+
+        vi.mocked(fs.readFile).mockResolvedValue(
+            JSON.stringify({
+                name: "test-workspace",
+                version: "1.0.0",
+            }),
+        );
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.EXISTING_VAR).toBe("existing-value");
+    });
+
+    it("should prepend workspace node_modules/.bin to PATH", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {
+            PATH: "/usr/bin:/bin",
+        };
+
+        vi.mocked(fs.readFile).mockResolvedValue(
+            JSON.stringify({
+                name: "test-workspace",
+            }),
+        );
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        const expectedPath = path.join(workspaceRoot, "node_modules", ".bin");
+        expect(env.PATH).toContain(expectedPath);
+    });
+
+    it("should set npm_command to exec", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify({}));
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.npm_command).toBe("exec");
+    });
+
+    it("should set INIT_CWD to current working directory", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+        const expectedCwd = process.cwd();
+
+        vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify({}));
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.INIT_CWD).toBe(expectedCwd);
+    });
+
+    it("should set npm_package_name from workspace package.json", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockResolvedValue(
+            JSON.stringify({
+                name: "my-workspace",
+                version: "2.5.0",
+            }),
+        );
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.npm_package_name).toBe("my-workspace");
+    });
+
+    it("should set npm_package_version from workspace package.json", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockResolvedValue(
+            JSON.stringify({
+                name: "my-workspace",
+                version: "2.5.0",
+            }),
+        );
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.npm_package_version).toBe("2.5.0");
+    });
+
+    it("should set npm_execpath to node executable path", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify({}));
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.npm_execpath).toBe(process.execPath);
+    });
+
+    it("should include package name in npm_config_user_agent", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify({}));
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.npm_config_user_agent).toContain("x/");
+    });
+
+    it("should include node version in npm_config_user_agent", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockResolvedValue(JSON.stringify({}));
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.npm_config_user_agent).toContain("node/");
+    });
+
+    it("should set npm_command to exec when package.json is missing", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockRejectedValue(
+            new Error("ENOENT: no such file"),
+        );
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.npm_command).toBe("exec");
+    });
+
+    it("should set INIT_CWD when package.json is missing", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockRejectedValue(
+            new Error("ENOENT: no such file"),
+        );
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.INIT_CWD).toBe(process.cwd());
+    });
+
+    it("should include npm_package_description if present", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockResolvedValue(
+            JSON.stringify({
+                name: "my-workspace",
+                description: "A test workspace",
+            }),
+        );
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.npm_package_description).toBe("A test workspace");
+    });
+
+    it("should convert object fields to JSON strings", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockResolvedValue(
+            JSON.stringify({
+                name: "my-workspace",
+                repository: {
+                    type: "git",
+                    url: "https://github.com/test/repo",
+                },
+            }),
+        );
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.npm_package_repository).toBe(
+            JSON.stringify({
+                type: "git",
+                url: "https://github.com/test/repo",
+            }),
+        );
+    });
+
+    it("should set npm_package_license from workspace package.json", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockResolvedValue(
+            JSON.stringify({
+                name: "my-workspace",
+                license: "MIT",
+                author: "John Doe",
+            }),
+        );
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.npm_package_license).toBe("MIT");
+    });
+
+    it("should set npm_package_author from workspace package.json", async () => {
+        // Arrange
+        const workspaceRoot = "/test/workspace";
+        const currentEnv = {PATH: "/usr/bin"};
+
+        vi.mocked(fs.readFile).mockResolvedValue(
+            JSON.stringify({
+                name: "my-workspace",
+                license: "MIT",
+                author: "John Doe",
+            }),
+        );
+
+        // Act
+        const env = await buildEnvironment(workspaceRoot, currentEnv);
+
+        // Assert
+        expect(env.npm_package_author).toBe("John Doe");
+    });
+});