@somewhatabstract/x 0.0.1 → 0.1.0

package/src/__tests__/x.test.ts

@@ -0,0 +1,236 @@
+import {afterEach, beforeEach, describe, expect, it, vi} from "vitest";
+
+// Utility to wait for all pending promises and timers to settle
+const flushPromises = () =>
+    new Promise<void>((resolve) => setTimeout(resolve, 0));
+
+// Build a mock yargs chain that returns the given parsed args from parseSync
+const buildYargsMock = (parsedArgs: Record<string, unknown>) => {
+    const yargsChain: Record<string, unknown> = {
+        usage: vi.fn().mockReturnThis(),
+        option: vi.fn().mockReturnThis(),
+        help: vi.fn().mockReturnThis(),
+        alias: vi.fn().mockReturnThis(),
+        version: vi.fn().mockReturnThis(),
+        example: vi.fn().mockReturnThis(),
+        strict: vi.fn().mockReturnThis(),
+        parseSync: vi.fn().mockReturnValue(parsedArgs),
+        // Needed when the command builder callback calls yargs.positional()
+        positional: vi.fn().mockReturnThis(),
+    };
+    // Invoke the builder callback so its body is exercised
+    yargsChain.command = vi
+        .fn()
+        .mockImplementation(
+            (_name: unknown, _desc: unknown, builder: unknown) => {
+                if (typeof builder === "function") {
+                    builder(yargsChain);
+                }
+                return yargsChain;
+            },
+        );
+    return {default: vi.fn().mockReturnValue(yargsChain)};
+};
+
+describe("bin/x", () => {
+    let processExitSpy: ReturnType<typeof vi.spyOn>;
+
+    beforeEach(() => {
+        vi.resetModules();
+        processExitSpy = vi
+            .spyOn(process, "exit")
+            .mockImplementation(() => undefined as never);
+        vi.spyOn(console, "error").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it("should call xImpl with the script name from argv", async () => {
+        // Arrange
+        const xImplMock = vi.fn().mockResolvedValue({exitCode: 0});
+        vi.doMock("../x-impl", () => ({xImpl: xImplMock}));
+        vi.doMock("yargs", () =>
+            buildYargsMock({
+                "script-name": "my-script",
+                _: [],
+                "dry-run": false,
+            }),
+        );
+
+        // Act
+        await import("../bin/x");
+        await flushPromises();
+
+        // Assert
+        expect(xImplMock).toHaveBeenCalledWith(
+            "my-script",
+            expect.any(Array),
+            expect.any(Object),
+        );
+    });
+
+    it("should call xImpl with args from argv underscore field", async () => {
+        // Arrange
+        const xImplMock = vi.fn().mockResolvedValue({exitCode: 0});
+        vi.doMock("../x-impl", () => ({xImpl: xImplMock}));
+        vi.doMock("yargs", () =>
+            buildYargsMock({
+                "script-name": "my-script",
+                _: ["--flag", "value"],
+                "dry-run": false,
+            }),
+        );
+
+        // Act
+        await import("../bin/x");
+        await flushPromises();
+
+        // Assert
+        expect(xImplMock).toHaveBeenCalledWith(
+            expect.any(String),
+            ["--flag", "value"],
+            expect.any(Object),
+        );
+    });
+
+    it("should call xImpl with dryRun true when dry-run argv is true", async () => {
+        // Arrange
+        const xImplMock = vi.fn().mockResolvedValue({exitCode: 0});
+        vi.doMock("../x-impl", () => ({xImpl: xImplMock}));
+        vi.doMock("yargs", () =>
+            buildYargsMock({
+                "script-name": "my-script",
+                _: [],
+                "dry-run": true,
+            }),
+        );
+
+        // Act
+        await import("../bin/x");
+        await flushPromises();
+
+        // Assert
+        expect(xImplMock).toHaveBeenCalledWith(
+            expect.any(String),
+            expect.any(Array),
+            {dryRun: true},
+        );
+    });
+
+    it("should call xImpl with dryRun false when dry-run argv is false", async () => {
+        // Arrange
+        const xImplMock = vi.fn().mockResolvedValue({exitCode: 0});
+        vi.doMock("../x-impl", () => ({xImpl: xImplMock}));
+        vi.doMock("yargs", () =>
+            buildYargsMock({
+                "script-name": "my-script",
+                _: [],
+                "dry-run": false,
+            }),
+        );
+
+        // Act
+        await import("../bin/x");
+        await flushPromises();
+
+        // Assert
+        expect(xImplMock).toHaveBeenCalledWith(
+            expect.any(String),
+            expect.any(Array),
+            {dryRun: false},
+        );
+    });
+
+    it("should default to empty array when argv underscore field is falsy", async () => {
+        // Arrange
+        const xImplMock = vi.fn().mockResolvedValue({exitCode: 0});
+        vi.doMock("../x-impl", () => ({xImpl: xImplMock}));
+        vi.doMock("yargs", () =>
+            buildYargsMock({
+                "script-name": "my-script",
+                _: null,
+                "dry-run": false,
+            }),
+        );
+
+        // Act
+        await import("../bin/x");
+        await flushPromises();
+
+        // Assert
+        expect(xImplMock).toHaveBeenCalledWith(
+            expect.any(String),
+            [],
+            expect.any(Object),
+        );
+    });
+
+    it("should exit with the exit code returned by xImpl", async () => {
+        // Arrange
+        vi.doMock("../x-impl", () => ({
+            xImpl: vi.fn().mockResolvedValue({exitCode: 42}),
+        }));
+        vi.doMock("yargs", () =>
+            buildYargsMock({
+                "script-name": "my-script",
+                _: [],
+                "dry-run": false,
+            }),
+        );
+
+        // Act
+        await import("../bin/x");
+        await flushPromises();
+
+        // Assert
+        expect(processExitSpy).toHaveBeenCalledWith(42);
+    });
+
+    it("should exit with 1 when xImpl throws an unexpected error", async () => {
+        // Arrange
+        vi.doMock("../x-impl", () => ({
+            xImpl: vi.fn().mockRejectedValue(new Error("Unexpected")),
+        }));
+        vi.doMock("yargs", () =>
+            buildYargsMock({
+                "script-name": "my-script",
+                _: [],
+                "dry-run": false,
+            }),
+        );
+
+        // Act
+        await import("../bin/x");
+        await flushPromises();
+
+        // Assert
+        expect(processExitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it("should log error details when xImpl throws an unexpected error", async () => {
+        // Arrange
+        const unexpectedError = new Error("Something went wrong");
+        vi.doMock("../x-impl", () => ({
+            xImpl: vi.fn().mockRejectedValue(unexpectedError),
+        }));
+        vi.doMock("yargs", () =>
+            buildYargsMock({
+                "script-name": "my-script",
+                _: [],
+                "dry-run": false,
+            }),
+        );
+
+        // Act
+        await import("../bin/x");
+        await flushPromises();
+
+        // Assert
+        expect(console.error).toHaveBeenCalledWith(
+            "Unexpected error:",
+            unexpectedError,
+        );
+    });
+});

package/src/bin/x.ts

@@ -1,3 +1,57 @@
 #!/usr/bin/env node
+import yargs from "yargs";
+import {hideBin} from "yargs/helpers";
 import {xImpl} from "../x-impl";
-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();
+
+// Extract script name and args
+const scriptName = argv["script-name"] as string;
+const args = (argv._ as string[]) || [];
+const options = {
+    dryRun: argv["dry-run"] as boolean,
+};
+
+// Run the implementation and exit with the appropriate code
+xImpl(scriptName, args, options)
+    .then((result) => {
+        process.exit(result.exitCode);
+    })
+    .catch((error) => {
+        console.error("Unexpected error:", error);
+        process.exit(1);
+    });

package/src/build-environment.ts

@@ -0,0 +1,98 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+/**
+ * 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
+ */
+export async function buildEnvironment(
+    workspaceRoot: string,
+    currentEnv: NodeJS.ProcessEnv,
+): Promise<NodeJS.ProcessEnv> {
+    // Read workspace root's package.json for metadata
+    let workspacePackageJson: Record<string, unknown> = {};
+    try {
+        const packageJsonPath = path.join(workspaceRoot, "package.json");
+        const content = await fs.readFile(packageJsonPath, "utf-8");
+        workspacePackageJson = JSON.parse(content);
+    } catch {
+        // If we can't read package.json, continue with empty metadata
+    }
+
+    // Get our own package version for user agent
+    let ourPackageVersion = "0.0.0-development";
+    try {
+        const ownPackageJsonPath = path.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 {
+        // If we can't read our own package.json, continue with fallback version
+    }
+
+    // Build the environment
+    const env: NodeJS.ProcessEnv = {
+        // Preserve all existing environment variables
+        ...currentEnv,
+
+        // PATH: Prepend workspace root's node_modules/.bin
+        PATH: [
+            path.join(workspaceRoot, "node_modules", ".bin"),
+            currentEnv.PATH,
+        ]
+            .filter(Boolean)
+            .join(path.delimiter),
+
+        // npm lifecycle variables
+        npm_command: "exec",
+        npm_execpath: process.execPath,
+        npm_node_execpath: process.execPath,
+        NODE: process.execPath,
+        INIT_CWD: process.cwd(),
+
+        // User agent
+        npm_config_user_agent: `x/${ourPackageVersion} node/${process.version} ${process.platform} ${process.arch}`,
+    };
+
+    // Add npm_package_* variables from workspace root's package.json
+    if (workspacePackageJson.name) {
+        env.npm_package_name = workspacePackageJson.name as string;
+    }
+    if (workspacePackageJson.version) {
+        env.npm_package_version = workspacePackageJson.version as string;
+    }
+    if (workspacePackageJson.description) {
+        env.npm_package_description =
+            workspacePackageJson.description as string;
+    }
+
+    // Add other common package.json fields
+    const commonFields = [
+        "author",
+        "license",
+        "homepage",
+        "repository",
+        "bugs",
+        "keywords",
+    ];
+
+    for (const field of commonFields) {
+        if (workspacePackageJson[field]) {
+            const value = workspacePackageJson[field];
+            // Convert objects to JSON strings
+            env[`npm_package_${field}`] =
+                typeof value === "string" ? value : JSON.stringify(value);
+        }
+    }
+
+    return env;
+}

package/src/discover-packages.ts

@@ -0,0 +1,35 @@
+import {getPackages} from "@manypkg/get-packages";
+import {HandledError} from "./errors";
+
+export interface PackageInfo {
+    name: string;
+    path: string;
+    version: string;
+}
+
+/**
+ * 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
+ */
+export async function discoverPackages(
+    workspaceRoot: string,
+): Promise<PackageInfo[]> {
+    try {
+        const result = await getPackages(workspaceRoot);
+
+        return result.packages.map((pkg) => ({
+            name: pkg.packageJson.name,
+            path: pkg.dir,
+            version: pkg.packageJson.version || "unknown",
+        }));
+    } catch (error: unknown) {
+        if (error instanceof HandledError) {
+            throw error;
+        }
+        throw new HandledError(`Failed to discover packages`, {cause: error});
+    }
+}

package/src/errors.ts

@@ -0,0 +1,10 @@
+/**
+ * Error class for known/expected errors that should be displayed to the user
+ * without a stack trace.
+ */
+export class HandledError extends Error {
+    constructor(message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = "HandledError";
+    }
+}

package/src/execute-script.ts

@@ -0,0 +1,56 @@
+import {spawn} from "node:child_process";
+import {buildEnvironment} from "./build-environment";
+import type {BinInfo} from "./find-matching-bins";
+import {isNodeExecutable} from "./is-node-executable";
+
+/**
+ * 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
+ */
+export async function executeScript(
+    bin: BinInfo,
+    args: string[],
+    workspaceRoot: string,
+): Promise<number> {
+    // Build environment with npm/pnpm-style variables
+    const env = await buildEnvironment(workspaceRoot, process.env);
+
+    // For .js/.mjs/.cjs files, invoke via node (matching npm behavior).
+    // The original binPath casing is preserved in the spawn call.
+    const [executable, spawnArgs] = isNodeExecutable(bin.binPath)
+        ? [process.execPath, [bin.binPath, ...args]]
+        : [bin.binPath, args];
+
+    return new Promise((resolve) => {
+        const child = spawn(executable, spawnArgs, {
+            // Don't change directory - execute in current directory
+            // as if the bin were installed at workspace root
+            stdio: "inherit",
+            env,
+        });
+
+        child.on("error", (_) => {
+            // Handle spawn errors (ENOENT, EACCES, etc.)
+            resolve(1);
+        });
+
+        child.on("exit", (code, signal) => {
+            // If killed by signal, we could use exit code 128 + signal number,
+            // (a common convention), however, for simplicity, we'll just
+            // return 1 for any signal-based termination as it's not clear
+            // that we need to distinguish between different signals in this
+            // context.
+            if (signal) {
+                resolve(1);
+            } else {
+                resolve(code ?? 1);
+            }
+        });
+    });
+}

package/src/find-matching-bins.ts

@@ -0,0 +1,72 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type {PackageInfo} from "./discover-packages";
+import {resolveBinPath} from "./resolve-bin-path";
+
+export interface BinInfo {
+    packageName: string;
+    packagePath: string;
+    binName: string;
+    binPath: string;
+}
+
+/**
+ * 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
+ */
+export async function findMatchingBins(
+    packages: PackageInfo[],
+    binName: string,
+): Promise<BinInfo[]> {
+    const matches: BinInfo[] = [];
+
+    for (const pkg of packages) {
+        try {
+            const packageJsonPath = path.join(pkg.path, "package.json");
+            const packageJsonContent = await fs.readFile(
+                packageJsonPath,
+                "utf-8",
+            );
+            const packageJson = JSON.parse(packageJsonContent);
+
+            const bin = packageJson.bin;
+            const resolvedBinPath = resolveBinPath(pkg, bin, binName);
+            if (!resolvedBinPath) {
+                continue;
+            }
+
+            matches.push({
+                packageName: pkg.name,
+                packagePath: pkg.path,
+                binName: binName,
+                binPath: resolvedBinPath,
+            });
+        } catch (error: unknown) {
+            // Skip packages that can't be read. Log malformed JSON so it can be diagnosed.
+            if (error instanceof SyntaxError) {
+                // Invalid JSON in package.json
+                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"
+            ) {
+                // package.json not found - this can be expected for some paths
+            } else {
+                // Other unexpected errors when reading package.json
+                console.warn(
+                    `Warning: Could not read package.json for package "${pkg.name}" at "${pkg.path}":`,
+                    error,
+                );
+            }
+        }
+    }
+
+    return matches;
+}

package/src/find-workspace-root.ts

@@ -0,0 +1,24 @@
+import {findRoot} from "@manypkg/find-root";
+import {HandledError} from "./errors";
+
+/**
+ * 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
+ */
+export async function findWorkspaceRoot(
+    startDir: string = process.cwd(),
+): Promise<string> {
+    try {
+        const result = await findRoot(startDir);
+        return result.rootDir;
+    } catch (error: unknown) {
+        throw new HandledError(
+            "Could not find workspace root. Make sure you're in a monorepo workspace.",
+            {cause: error},
+        );
+    }
+}

package/src/is-node-executable.ts

@@ -0,0 +1,16 @@
+/**
+ * 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
+ */
+export function isNodeExecutable(binPath: string): boolean {
+    const lower = binPath.toLowerCase();
+    return (
+        lower.endsWith(".js") ||
+        lower.endsWith(".mjs") ||
+        lower.endsWith(".cjs")
+    );
+}

package/src/resolve-bin-path.ts

@@ -0,0 +1,48 @@
+import path from "node:path";
+import type {PackageInfo} from "./discover-packages";
+
+/**
+ * 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
+
+ */
+export function resolveBinPath(
+    pkg: PackageInfo,
+    bin: string | undefined | null | Record<string, string>,
+    binName: string,
+): string | null {
+    // bin can be a string or an object
+    const binPath: string | null = !bin
+        ? null
+        : typeof bin === "string" && pkg.name === binName
+          ? // If bin is a string, the bin name is the package name
+            bin
+          : // If bin is an object, check if it has the requested bin name
+            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);
+    // Ensure the bin path stays within the package directory
+    if (
+        resolvedBinPath !== packageDir &&
+        !resolvedBinPath.startsWith(packageDir + path.sep)
+    ) {
+        return null;
+    }
+
+    return resolvedBinPath;
+}