bun-workspaces 0.1.0-alpha-test-publish-0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Scott Morse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# bun-workspaces
+
+This is a CLI meant to help manage [Bun workspaces](https://bun.sh/docs/install/workspaces).
+
+This was created primarily due to issues and limitations with Bun's `--filter` option for running commands from workspaces.
+
+## Installation
+
+You can install the CLI in your project or simply use `bunx bun-workspaces`.
+
+```bash
+$ bun add --dev bun-workspaces
+$ bunx bun-workspaces --help
+```
+
+### Examples
+
+You might consider making a shorter alias in your `.bashrc`, `.zshrc`, or similar shell configuration file, such as `alias bw="bunx bun-workspaces"`, for convenience.
+
+```bash
+alias bw="bunx bun-workspaces"
+
+# List all workspaces
+bw list-workspaces
+bw ls
+# List workspace names only
+bw list-workspaces --name-only
+
+# List all workspace scripts
+bw list-scripts
+# List script names only
+bw list-scripts --name-only
+
+# Get info about a workspace
+bw workspace-info my-workspace
+bw info my-workspace
+
+# Get info about a script
+bw script-info my-script
+# Only print list of workspace names that have the script
+bw script-info my-script --workspaces-only
+
+# Run a script for all
+# workspaces that have it
+# in their `scripts` field
+bw run-script my-script
+
+# Run a script for a specific workspace
+bw run-script my-script my-workspace
+
+# Run a script for multiple workspaces
+bw run-script my-script workspace-a workspace-b
+
+# Run script in parallel for all workspaces
+bw run-script my-script --parallel
+
+# Append args to each script call
+bw run-script my-script --args "--my --args"
+
+# Help (--help can also be passed to any command)
+bw help
+bw --help
+
+# Pass --cwd to any command
+bw --cwd /path/to/your/project ls
+bw --cwd /path/to/your/project run-script my-script
+```

package/bin/cli.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { createCli } from "bun-workspaces";
+
+createCli().run();

package/eslint.config.mjs

@@ -0,0 +1,45 @@
+import js from "@eslint/js";
+import importPlugin from "eslint-plugin-import";
+import typescriptEslint from "typescript-eslint";
+
+export default [
+  ...typescriptEslint.config(
+    js.configs.recommended,
+    typescriptEslint.configs.recommended,
+  ),
+  {
+    plugins: {
+      import: importPlugin,
+    },
+    rules: {
+      "@typescript-eslint/no-empty-interface": "off",
+      "@typescript-eslint/no-empty-function": "off",
+      "no-empty": "warn",
+      "@typescript-eslint/no-extra-semi": "off",
+      "@typescript-eslint/no-explicit-any": "off",
+
+      "@typescript-eslint/no-unused-vars": [
+        "warn",
+        {
+          varsIgnorePattern: "^_",
+          argsIgnorePattern: "^_",
+          destructuredArrayIgnorePattern: "^_",
+          caughtErrorsIgnorePattern: "^_",
+        },
+      ],
+
+      eqeqeq: "error",
+      "prefer-const": "error",
+
+      "import/order": [
+        "warn",
+        {
+          alphabetize: {
+            order: "asc",
+            caseInsensitive: true,
+          },
+        },
+      ],
+    },
+  },
+];

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "bun-workspaces",
+  "version": "0.1.0-alpha-test-publish-0",
+  "main": "src/index.ts",
+  "bin": {
+    "bun-workspaces": "NODE_ENV=production ./bin/cli.js"
+  },
+  "custom": {
+    "bunVersion": {
+      "build": "1.1.38",
+      "libraryConsumer": "^1.1.x"
+    }
+  },
+  "scripts": {
+    "cli": "NODE_ENV=production bun run bin/cli.js",
+    "cli:dev": "NODE_ENV=development bun run bin/cli.js",
+    "type-check": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format-check": "prettier --check ."
+  },
+  "devDependencies": {
+    "@types/bun": "^1.1.14",
+    "@typescript-eslint/eslint-plugin": "^8.17.0",
+    "@typescript-eslint/parser": "^8.17.0",
+    "bun-workspaces": "file:.",
+    "eslint": "^9.16.0",
+    "eslint-plugin-import": "^2.31.0",
+    "prettier": "^3.4.2",
+    "typescript-eslint": "^8.17.0"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "pino": "^9.5.0",
+    "pino-pretty": "^13.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  }
+}

package/src/cli/cli.ts

@@ -0,0 +1,92 @@
+import { createCommand, Command } from "commander";
+import packageJson from "../../package.json";
+import {
+  getRequiredBunVersion,
+  validateCurrentBunVersion,
+} from "../internal/bunVersion";
+import { logger } from "../internal/logger";
+import { initializeWithGlobalOptions } from "./globalOptions";
+import { defineProjectCommands } from "./projectCommands";
+import { OUTPUT_CONFIG } from "./output";
+
+export interface RunCliOptions {
+  argv?: string | string[];
+}
+
+export interface CliProgram {
+  run: (options?: RunCliOptions) => Promise<void>;
+}
+
+export interface CreateCliProgramOptions {
+  writeOut?: (s: string) => void;
+  writeErr?: (s: string) => void;
+  handleError?: (error: Error) => void;
+  postInit?: (program: Command) => unknown;
+  defaultCwd?: string;
+}
+
+export const createCliProgram = ({
+  writeOut = OUTPUT_CONFIG.writeOut,
+  writeErr = OUTPUT_CONFIG.writeErr,
+  handleError,
+  postInit,
+  defaultCwd = process.cwd(),
+}: CreateCliProgramOptions = {}): CliProgram => {
+  const run = async ({ argv = process.argv }: RunCliOptions = {}) => {
+    const errorListener =
+      handleError ??
+      ((error) => {
+        logger.error(error);
+        logger.error("Unhandled rejection");
+        process.exit(1);
+      });
+
+    process.on("unhandledRejection", errorListener);
+
+    try {
+      const program = createCommand("bunx bun-workspaces")
+        .description("CLI for utilities for Bun workspaces")
+        .version(packageJson.version)
+        .configureOutput({
+          writeOut,
+          writeErr,
+        });
+
+      postInit?.(program);
+
+      if (!validateCurrentBunVersion()) {
+        logger.error(
+          `Bun version mismatch. Required: ${getRequiredBunVersion()}, Found: ${
+            Bun.version
+          }`,
+        );
+        process.exit(1);
+      }
+
+      const args = typeof argv === "string" ? argv.split(" ") : argv;
+
+      const { project } = initializeWithGlobalOptions(
+        program,
+        args,
+        defaultCwd,
+      );
+      if (!project) return;
+
+      defineProjectCommands({
+        program,
+        project,
+        printLines: (...lines: string[]) => writeOut(lines.join("\n") + "\n"),
+      });
+
+      await program.parseAsync(args);
+    } catch (error) {
+      errorListener(error as Error);
+    } finally {
+      process.off("unhandledRejection", errorListener);
+    }
+  };
+
+  return {
+    run,
+  };
+};

package/src/cli/globalOptions.ts

@@ -0,0 +1,84 @@
+import path from "path";
+import { type Command, Option } from "commander";
+import { logger } from "../internal/logger";
+import { createProject } from "../project";
+
+const LOG_LEVELS = ["silent", "error", "warn", "info", "debug"] as const;
+
+export type LogLevel = (typeof LOG_LEVELS)[number];
+
+export interface CliGlobalOptions {
+  logLevel: LogLevel;
+  cwd: string;
+}
+
+export type CliGlobalOptionName = keyof CliGlobalOptions;
+
+const defineGlobalOptions = (program: Command, defaultCwd: string) => {
+  const globalOptions: {
+    [K in CliGlobalOptionName]: {
+      shortName: string;
+      description: string;
+      defaultValue: CliGlobalOptions[K];
+      values?: readonly CliGlobalOptions[K][];
+      param?: string;
+    };
+  } = {
+    logLevel: {
+      shortName: "l",
+      description: "Log levels",
+      defaultValue: logger.level as LogLevel,
+      values: LOG_LEVELS,
+      param: "level",
+    },
+    cwd: {
+      shortName: "d",
+      description: "Working directory",
+      defaultValue: defaultCwd ?? process.cwd(),
+      param: "dir",
+    },
+  };
+
+  Object.entries(globalOptions).forEach(
+    ([name, { shortName, description, defaultValue, param, values }]) => {
+      const option = new Option(
+        `-${shortName} --${name}${param ? ` <${param}>` : ""}`,
+        description,
+      ).default(defaultValue);
+
+      program.addOption(values?.length ? option.choices(values) : option);
+    },
+  );
+};
+
+const applyGlobalOptions = (options: CliGlobalOptions) => {
+  logger.level = options.logLevel;
+  logger.debug("Log level: " + options.logLevel);
+
+  const project = createProject({
+    rootDir: options.cwd,
+  });
+
+  logger.debug(
+    `Project: ${JSON.stringify(project.name)} (${
+      project.workspaces.length
+    } workspace${project.workspaces.length === 1 ? "" : "s"})`,
+  );
+  logger.debug("Project root: " + path.resolve(project.rootDir));
+
+  return { project };
+};
+
+export const initializeWithGlobalOptions = (
+  program: Command,
+  args: string[],
+  defaultCwd: string,
+) => {
+  defineGlobalOptions(program, defaultCwd);
+
+  program.allowUnknownOption(true);
+  program.parseOptions(args);
+  program.allowUnknownOption(false);
+
+  return applyGlobalOptions(program.opts() as CliGlobalOptions);
+};

package/src/cli/index.ts

@@ -0,0 +1 @@
+export { createCliProgram as createCli } from "./cli";

package/src/cli/output.ts

@@ -0,0 +1,6 @@
+import { IS_TEST } from "../internal/env";
+
+export const OUTPUT_CONFIG = {
+  writeOut: (s: string) => !IS_TEST && process.stdout.write(s),
+  writeErr: (s: string) => !IS_TEST && process.stderr.write(s),
+};

package/src/cli/projectCommands.ts

@@ -0,0 +1,283 @@
+import { type Command } from "commander";
+import { logger } from "../internal/logger";
+import type { Project } from "../project";
+import type { Workspace } from "../workspaces";
+
+export interface ProjectCommandsContext {
+  project: Project;
+  program: Command;
+  printLines: (...lines: string[]) => void;
+}
+
+const createWorkspaceInfoLines = (workspace: Workspace) => [
+  `Workspace: ${workspace.name}`,
+  ` - Path: ${workspace.path}`,
+  ` - Glob Match: ${workspace.matchPattern}`,
+  ` - Scripts: ${Object.keys(workspace.packageJson.scripts).sort().join(", ")}`,
+];
+
+const createScriptInfoLines = (script: string, workspaces: Workspace[]) => [
+  `Script: ${script}`,
+  ...workspaces.map((workspace) => ` - ${workspace.name}`),
+];
+
+const listWorkspaces = ({
+  program,
+  project,
+  printLines,
+}: ProjectCommandsContext) => {
+  program
+    .command("list-workspaces")
+    .aliases(["ls", "list"])
+    .description("List all workspaces")
+    .option("--name-only", "Only show workspace names")
+    .action((options) => {
+      logger.debug("Command: List workspaces");
+
+      if (options.more) {
+        logger.debug("Showing more metadata");
+      }
+
+      const lines: string[] = [];
+      project.workspaces.forEach((workspace) => {
+        if (options.nameOnly) {
+          lines.push(workspace.name);
+        } else {
+          lines.push(...createWorkspaceInfoLines(workspace));
+        }
+      });
+
+      if (!lines.length) {
+        lines.push("No workspaces found");
+      }
+
+      printLines(...lines);
+    });
+};
+
+const listScripts = ({
+  program,
+  project,
+  printLines,
+}: ProjectCommandsContext) => {
+  program
+    .command("list-scripts")
+    .description("List all scripts available with their workspaces")
+    .option("--name-only", "Only show script names")
+    .action((options) => {
+      logger.debug("Command: List scripts");
+
+      const scripts = project.listScriptsWithWorkspaces();
+      const lines: string[] = [];
+      Object.values(scripts)
+        .sort(({ name: nameA }, { name: nameB }) => nameA.localeCompare(nameB))
+        .forEach(({ name, workspaces }) => {
+          if (options.nameOnly) {
+            lines.push(name);
+          } else {
+            lines.push(...createScriptInfoLines(name, workspaces));
+          }
+        });
+
+      if (!lines.length) {
+        lines.push("No scripts found");
+      }
+
+      printLines(...lines);
+    });
+};
+
+const workspaceInfo = ({
+  program,
+  project,
+  printLines,
+}: ProjectCommandsContext) => {
+  program
+    .command("workspace-info <workspace>")
+    .aliases(["info"])
+    .description("Show information about a workspace")
+    .action((workspaceName) => {
+      logger.debug(`Command: Workspace info for ${workspaceName}`);
+
+      const workspace = project.findWorkspaceByName(workspaceName);
+      if (!workspace) {
+        logger.error(`Workspace not found: ${JSON.stringify(workspaceName)}`);
+        return;
+      }
+
+      printLines(...createWorkspaceInfoLines(workspace));
+    });
+};
+
+const scriptInfo = ({
+  program,
+  project,
+  printLines,
+}: ProjectCommandsContext) => {
+  program
+    .command("script-info <script>")
+    .description("Show information about a script")
+    .option("--workspaces-only", "Only show script's workspace names")
+    .action((script, options) => {
+      logger.debug(`Command: Script info for ${script}`);
+
+      const scripts = project.listScriptsWithWorkspaces();
+      const scriptMetadata = scripts[script];
+      if (!scriptMetadata) {
+        printLines(
+          `Script not found: ${JSON.stringify(
+            script,
+          )} (available: ${Object.keys(scripts).join(", ")})`,
+        );
+        return;
+      }
+      printLines(
+        ...(options.workspacesOnly
+          ? scriptMetadata.workspaces.map(({ name }) => name)
+          : createScriptInfoLines(script, scriptMetadata.workspaces)),
+      );
+    });
+};
+
+const runScript = ({
+  program,
+  project,
+  printLines,
+}: ProjectCommandsContext) => {
+  program
+    .command("run <script> [workspaces...]")
+    .description("Run a script in all workspaces")
+    .option("--parallel", "Run the scripts in parallel")
+    .option("--args <args>", "Args to append to the script command", "")
+    .action(async (script: string, workspaces: string[], options) => {
+      logger.debug(
+        `Command: Run script ${JSON.stringify(script)} for ${
+          workspaces.length
+            ? "workspaces " + workspaces.join(", ")
+            : "all workspaces"
+        } (parallel: ${!!options.parallel}, method: ${JSON.stringify(
+          options.method,
+        )}, args: ${JSON.stringify(options.args)})`,
+      );
+
+      workspaces = workspaces.length
+        ? workspaces
+        : project.listWorkspacesWithScript(script).map(({ name }) => name);
+
+      if (!workspaces.length) {
+        program.error(
+          `No workspaces found for script ${JSON.stringify(script)}`,
+        );
+      }
+
+      let scriptCommands: ReturnType<typeof project.createScriptCommand>[];
+      try {
+        scriptCommands = workspaces.map((workspaceName) =>
+          project.createScriptCommand({
+            scriptName: script,
+            workspaceName,
+            method: "cd",
+            args: options.args.replace(/<workspace>/g, workspaceName),
+          }),
+        );
+      } catch (error) {
+        program.error((error as Error).message);
+        throw error;
+      }
+
+      const runCommand = async ({
+        command,
+        scriptName,
+        workspace,
+      }: (typeof scriptCommands)[number]) => {
+        const splitCommand = command.command.split(/\s+/g);
+
+        logger.debug(
+          `Running script ${scriptName} in workspace ${workspace.name} (cwd: ${
+            command.cwd
+          }): ${splitCommand.join(" ")}`,
+        );
+
+        const silent = logger.level === "silent";
+
+        if (!silent) {
+          printLines(
+            `Running script ${JSON.stringify(
+              scriptName,
+            )} in workspace ${JSON.stringify(workspace.name)}`,
+          );
+        }
+
+        const proc = Bun.spawn(command.command.split(/\s+/g), {
+          cwd: command.cwd,
+          env: process.env,
+          stdout: silent ? "ignore" : "inherit",
+          stderr: silent ? "ignore" : "inherit",
+        });
+
+        await proc.exited;
+
+        return {
+          scriptName,
+          workspace,
+          command,
+          success: proc.exitCode === 0,
+        };
+      };
+
+      const handleError = (error: unknown, workspace: string) => {
+        logger.error(error);
+        program.error(
+          `Script failed in ${workspace} (error: ${JSON.stringify((error as Error).message ?? error)})`,
+        );
+      };
+
+      const handleResult = ({
+        scriptName,
+        workspace,
+        success,
+      }: (typeof scriptCommands)[number] & { success: boolean }) => {
+        logger.info(
+          `${success ? "✅" : "❌"} ${workspace.name}: ${scriptName}`,
+        );
+        if (!success) {
+          program.error(
+            `Script ${scriptName} failed in workspace ${workspace.name}`,
+          );
+        }
+      };
+
+      if (options.parallel) {
+        let i = 0;
+        for await (const result of await Promise.allSettled(
+          scriptCommands.map(runCommand),
+        )) {
+          if (result.status === "rejected") {
+            handleError(result.reason, workspaces[i]);
+          } else {
+            handleResult(result.value);
+          }
+          i++;
+        }
+      } else {
+        let i = 0;
+        for (const command of scriptCommands) {
+          try {
+            const result = await runCommand(command);
+            handleResult(result);
+          } catch (error) {
+            handleError(error, workspaces[i]);
+          }
+        }
+        i++;
+      }
+    });
+};
+
+export const defineProjectCommands = (context: ProjectCommandsContext) => {
+  listWorkspaces(context);
+  listScripts(context);
+  workspaceInfo(context);
+  scriptInfo(context);
+  runScript(context);
+};

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from "./workspaces";
+export * from "./project";
+export * from "./cli";

package/src/internal/bunVersion.ts

@@ -0,0 +1,24 @@
+import rootPackageJson from "../../package.json";
+
+export const LIBRARY_CONSUMER_BUN_VERSION =
+  rootPackageJson.custom.bunVersion.libraryConsumer;
+
+export const BUILD_BUN_VERSION = rootPackageJson.custom.bunVersion.build;
+
+export const getRequiredBunVersion = (build?: boolean) =>
+  build ? BUILD_BUN_VERSION : LIBRARY_CONSUMER_BUN_VERSION;
+
+/**
+ * Validates that the provided version satisfies the required Bun version
+ * specified in the root `package.json`.
+ */
+export const validateBunVersion = (version: string, build?: boolean) =>
+  Bun.semver.satisfies(version, getRequiredBunVersion(build));
+
+/**
+ *
+ * Validates that the Bun version of the current script satisfies the
+ * required Bun version specified in the root `package.json`.
+ */
+export const validateCurrentBunVersion = (build?: boolean) =>
+  validateBunVersion(Bun.version, build);

package/src/internal/env.ts

@@ -0,0 +1 @@
+export const IS_TEST = process.env.NODE_ENV === "test";

package/src/internal/error.ts

@@ -0,0 +1,38 @@
+export class BunWorkspacesError extends Error {
+  name = "BunWorkspacesError";
+}
+
+export type DefinedErrors<ErrorName extends string> = {
+  [name in ErrorName]: typeof BunWorkspacesError;
+};
+
+export const defineErrors = <ErrorName extends string>(
+  ...errors: ErrorName[]
+): DefinedErrors<ErrorName> =>
+  errors.reduce((acc, error) => {
+    acc[error] = class extends BunWorkspacesError {
+      constructor(message?: string) {
+        super(message);
+        this.name = error;
+      }
+      name = error;
+    };
+
+    Object.defineProperty(acc[error].prototype.constructor, "name", {
+      value: error,
+    });
+
+    Object.defineProperty(acc[error].constructor, "name", {
+      value: error,
+    });
+
+    Object.defineProperty(acc[error].prototype, "name", {
+      value: error,
+    });
+
+    Object.defineProperty(acc[error], "name", {
+      value: error,
+    });
+
+    return acc;
+  }, {} as DefinedErrors<ErrorName>);

package/src/internal/logger.ts

@@ -0,0 +1,17 @@
+import createLogger from "pino";
+
+export const logger = createLogger({
+  msgPrefix: "[bun-workspaces] ",
+  level:
+    process.env.NODE_ENV === "test"
+      ? "silent"
+      : process.env.NODE_ENV === "development"
+        ? "debug"
+        : "info",
+  transport: {
+    target: "pino-pretty",
+    options: {
+      color: true,
+    },
+  },
+});

package/src/project/errors.ts

@@ -0,0 +1,6 @@
+import { defineErrors } from "../internal/error";
+
+export const ERRORS = defineErrors(
+  "ProjectWorkspaceNotFound",
+  "WorkspaceScriptDoesNotExist",
+);

package/src/project/index.ts

@@ -0,0 +1,6 @@
+export {
+  type Project,
+  type CreateProjectOptions,
+  type CreateProjectScriptCommandOptions,
+  createProject,
+} from "./project";

package/src/project/project.ts

@@ -0,0 +1,122 @@
+import path from "path";
+import { findWorkspacesFromPackage, type Workspace } from "../workspaces";
+import { ERRORS } from "./errors";
+import {
+  createScriptCommand,
+  type CreateScriptCommandOptions,
+  type ScriptCommand,
+} from "./scriptCommand";
+
+export interface ScriptMetadata {
+  name: string;
+  workspaces: Workspace[];
+}
+
+export type CreateProjectScriptCommandOptions = Omit<
+  CreateScriptCommandOptions,
+  "workspace" | "rootDir"
+> & {
+  workspaceName: string;
+};
+
+export interface CreateProjectScriptCommandResult {
+  command: ScriptCommand;
+  scriptName: string;
+  workspace: Workspace;
+}
+
+export interface Project {
+  name: string;
+  rootDir: string;
+  workspaces: Workspace[];
+  listWorkspacesWithScript(scriptName: string): Workspace[];
+  listScriptsWithWorkspaces(): Record<string, ScriptMetadata>;
+  findWorkspaceByName(workspaceName: string): Workspace | null;
+  createScriptCommand(
+    options: CreateProjectScriptCommandOptions,
+  ): CreateProjectScriptCommandResult;
+}
+
+export interface CreateProjectOptions {
+  rootDir: string;
+}
+
+class _Project implements Project {
+  public readonly rootDir: string;
+  public readonly workspaces: Workspace[];
+  public readonly name: string;
+  constructor(private options: CreateProjectOptions) {
+    this.rootDir = options.rootDir;
+    const { name, workspaces } = findWorkspacesFromPackage({
+      rootDir: options.rootDir,
+    });
+    this.name = name;
+    this.workspaces = workspaces;
+  }
+
+  listWorkspacesWithScript(scriptName: string): Workspace[] {
+    return this.workspaces.filter(
+      (workspace) => workspace.packageJson.scripts?.[scriptName],
+    );
+  }
+
+  listScriptsWithWorkspaces(): Record<string, ScriptMetadata> {
+    const scripts = new Set<string>();
+    this.workspaces.forEach((workspace) => {
+      Object.keys(workspace.packageJson.scripts ?? {}).forEach((script) =>
+        scripts.add(script),
+      );
+    });
+    return Array.from(scripts)
+      .map((name) => ({
+        name,
+        workspaces: this.listWorkspacesWithScript(name),
+      }))
+      .reduce(
+        (acc, { name, workspaces }) => ({
+          ...acc,
+          [name]: { name, workspaces },
+        }),
+        {} as Record<string, ScriptMetadata>,
+      );
+  }
+
+  findWorkspaceByName(workspaceName: string): Workspace | null {
+    return (
+      this.workspaces.find((workspace) => workspace.name === workspaceName) ??
+      null
+    );
+  }
+
+  createScriptCommand(
+    options: CreateProjectScriptCommandOptions,
+  ): CreateProjectScriptCommandResult {
+    const workspace = this.findWorkspaceByName(options.workspaceName);
+    if (!workspace) {
+      throw new ERRORS.ProjectWorkspaceNotFound(
+        `Workspace not found: ${JSON.stringify(options.workspaceName)}`,
+      );
+    }
+    if (!workspace.packageJson.scripts?.[options.scriptName]) {
+      throw new ERRORS.WorkspaceScriptDoesNotExist(
+        `Script not found in workspace ${JSON.stringify(
+          workspace.name,
+        )}: ${JSON.stringify(options.scriptName)} (available: ${
+          Object.keys(workspace.packageJson.scripts).join(", ") || "none"
+        }`,
+      );
+    }
+    return {
+      workspace,
+      scriptName: options.scriptName,
+      command: createScriptCommand({
+        ...options,
+        workspace,
+        rootDir: path.resolve(this.rootDir),
+      }),
+    };
+  }
+}
+
+export const createProject = (options: CreateProjectOptions): Project =>
+  new _Project(options);

package/src/project/scriptCommand.ts

@@ -0,0 +1,40 @@
+import path from "path";
+import type { Workspace } from "../workspaces";
+
+export const SCRIPT_COMMAND_METHODS = ["cd", "filter"] as const;
+
+export type ScriptCommandMethod = (typeof SCRIPT_COMMAND_METHODS)[number];
+
+export interface CreateScriptCommandOptions {
+  method: ScriptCommandMethod;
+  scriptName: string;
+  args: string;
+  workspace: Workspace;
+  rootDir: string;
+}
+
+const spaceArgs = (args: string) => (args ? ` ${args.trim()}` : "");
+
+export interface ScriptCommand {
+  command: string;
+  cwd: string;
+}
+
+const METHODS: Record<
+  ScriptCommandMethod,
+  (options: CreateScriptCommandOptions) => ScriptCommand
+> = {
+  cd: ({ scriptName, workspace, rootDir, args }) => ({
+    cwd: path.resolve(rootDir, workspace.path),
+    command: `bun --silent run ${scriptName}${spaceArgs(args)}`,
+  }),
+  filter: ({ scriptName, workspace, args, rootDir }) => ({
+    cwd: rootDir,
+    command: `bun --silent run --filter=${JSON.stringify(
+      workspace.name,
+    )} ${scriptName}${spaceArgs(args)}`,
+  }),
+};
+
+export const createScriptCommand = (options: CreateScriptCommandOptions) =>
+  METHODS[options.method](options);

package/src/workspaces/errors.ts

@@ -0,0 +1,11 @@
+import { defineErrors } from "../internal/error";
+
+export const ERRORS = defineErrors(
+  "PackageNotFound",
+  "InvalidPackageJson",
+  "DuplicateWorkspaceName",
+  "NoWorkspaceName",
+  "InvalidScripts",
+  "InvalidWorkspaces",
+  "InvalidWorkspacePattern",
+);

package/src/workspaces/findWorkspaces.ts

@@ -0,0 +1,111 @@
+import fs from "fs";
+import path from "path";
+import { Glob } from "bun";
+import { logger } from "../internal/logger";
+import { ERRORS } from "./errors";
+import {
+  resolvePackageJsonContent,
+  resolvePackageJsonPath,
+  scanWorkspaceGlob,
+} from "./packageJson";
+import type { Workspace } from "./workspace";
+
+export interface FindWorkspacesOptions {
+  rootDir: string;
+  workspaceGlobs: string[];
+}
+
+const validatePattern = (pattern: string) => {
+  if (pattern.startsWith("!")) {
+    logger.warn(
+      `Negation patterns are not supported by Bun workspaces: ${JSON.stringify(
+        pattern,
+      )}`,
+    );
+    return false;
+  }
+  return true;
+};
+
+const validateWorkspace = (workspace: Workspace, workspaces: Workspace[]) => {
+  if (workspaces.find((ws) => ws.path === workspace.path)) {
+    return false;
+  }
+
+  if (workspaces.find((ws) => ws.name === workspace.name)) {
+    throw new ERRORS.DuplicateWorkspaceName(
+      `Duplicate workspace name found: ${JSON.stringify(workspace.name)}`,
+    );
+  }
+
+  return true;
+};
+
+export const findWorkspaces = ({
+  rootDir,
+  workspaceGlobs,
+}: FindWorkspacesOptions) => {
+  rootDir = path.resolve(rootDir);
+
+  const workspaces: Workspace[] = [];
+
+  for (const pattern of workspaceGlobs) {
+    if (!validatePattern(pattern)) continue;
+
+    const glob = new Glob(pattern);
+    for (const item of scanWorkspaceGlob(glob, rootDir)) {
+      const packageJsonPath = resolvePackageJsonPath(item);
+      if (packageJsonPath) {
+        const packageJsonContent = resolvePackageJsonContent(
+          packageJsonPath,
+          rootDir,
+          ["name", "scripts"],
+        );
+
+        const workspace: Workspace = {
+          name: packageJsonContent.name ?? "",
+          matchPattern: pattern,
+          path: path.relative(rootDir, path.dirname(packageJsonPath)),
+          packageJson: packageJsonContent,
+        };
+
+        if (validateWorkspace(workspace, workspaces)) {
+          workspaces.push(workspace);
+        }
+      }
+    }
+  }
+
+  workspaces.sort(
+    (a, b) => a.name.localeCompare(b.name) || a.path.localeCompare(b.path),
+  );
+
+  return { workspaces };
+};
+
+export interface FindWorkspacesFromPackageOptions {
+  rootDir: string;
+}
+
+export const findWorkspacesFromPackage = ({
+  rootDir,
+}: FindWorkspacesFromPackageOptions) => {
+  const packageJsonPath = path.join(rootDir, "package.json");
+  if (!fs.existsSync(packageJsonPath)) {
+    throw new ERRORS.PackageNotFound(
+      `No package.json found at ${packageJsonPath}`,
+    );
+  }
+
+  const packageJson = resolvePackageJsonContent(packageJsonPath, rootDir, [
+    "workspaces",
+  ]);
+
+  return {
+    ...findWorkspaces({
+      rootDir,
+      workspaceGlobs: packageJson.workspaces ?? [],
+    }),
+    name: packageJson.name ?? "",
+  };
+};

package/src/workspaces/index.ts

@@ -0,0 +1,8 @@
+export {
+  findWorkspaces,
+  findWorkspacesFromPackage,
+  type FindWorkspacesFromPackageOptions,
+  type FindWorkspacesOptions,
+} from "./findWorkspaces";
+export { type Workspace } from "./workspace";
+export type { ResolvedPackageJsonContent } from "./packageJson";

package/src/workspaces/packageJson.ts

@@ -0,0 +1,158 @@
+import fs from "fs";
+import path from "path";
+import { Glob } from "bun";
+import { logger } from "../internal/logger";
+import { ERRORS } from "./errors";
+
+export const resolvePackageJsonPath = (directoryItem: string) => {
+  if (path.basename(directoryItem) === "package.json") {
+    return directoryItem;
+  }
+  if (fs.existsSync(path.join(directoryItem, "package.json"))) {
+    return path.join(directoryItem, "package.json");
+  }
+  return "";
+};
+
+export type ResolvedPackageJsonContent = {
+  name: string;
+  workspaces: string[];
+  scripts: Record<string, string>;
+} & Record<string, unknown>;
+
+type UnknownPackageJson = Record<string, unknown>;
+
+export const scanWorkspaceGlob = (glob: Glob, rootDir: string) =>
+  glob.scanSync({
+    cwd: rootDir,
+    onlyFiles: false,
+    absolute: true,
+  });
+
+const validateJsonRoot = (json: UnknownPackageJson) => {
+  if (!json || typeof json !== "object" || Array.isArray(json)) {
+    throw new ERRORS.InvalidPackageJson(
+      `Expected package.json to be an object, got ${typeof json}`,
+    );
+  }
+};
+
+const validateName = (json: UnknownPackageJson) => {
+  if (typeof json.name !== "string") {
+    throw new ERRORS.NoWorkspaceName(
+      `Expected package.json to have a string "name" field${
+        json.name !== undefined ? ` (Received ${json.name})` : ""
+      }`,
+    );
+  }
+
+  return json.name;
+};
+
+const validateWorkspacePattern = (
+  workspacePattern: string,
+  rootDir: string,
+) => {
+  if (typeof workspacePattern !== "string") {
+    throw new ERRORS.InvalidWorkspacePattern(
+      `Expected workspace pattern to be a string, got ${typeof workspacePattern}`,
+    );
+  }
+
+  if (!workspacePattern.trim()) {
+    return false;
+  }
+
+  const absolutePattern = path.resolve(rootDir, workspacePattern);
+  if (!absolutePattern.startsWith(rootDir)) {
+    throw new ERRORS.InvalidWorkspacePattern(
+      `Cannot resolve workspace pattern outside of root directory ${rootDir}: ${absolutePattern}`,
+    );
+  }
+
+  return true;
+};
+
+const validateWorkspacePatterns = (
+  json: UnknownPackageJson,
+  rootDir: string,
+) => {
+  const workspaces: string[] = [];
+  if (json.workspaces) {
+    if (!Array.isArray(json.workspaces)) {
+      throw new ERRORS.InvalidWorkspaces(
+        `Expected package.json to have an array "workspaces" field`,
+      );
+    }
+
+    for (const workspacePattern of json.workspaces) {
+      if (validateWorkspacePattern(workspacePattern, rootDir)) {
+        workspaces.push(workspacePattern);
+      }
+    }
+  }
+
+  return workspaces;
+};
+
+const validateScripts = (json: UnknownPackageJson) => {
+  if (
+    json.scripts &&
+    (typeof json.scripts !== "object" || Array.isArray(json.scripts))
+  ) {
+    throw new ERRORS.InvalidScripts(
+      `Expected package.json to have an object "scripts" field`,
+    );
+  }
+
+  if (json.scripts) {
+    for (const value of Object.values(json.scripts)) {
+      if (typeof value !== "string") {
+        throw new ERRORS.InvalidScripts(
+          `Expected workspace "${json.name}" script "${
+            json.scripts
+          }" to be a string, got ${typeof value}`,
+        );
+      }
+    }
+  }
+
+  return {
+    ...(json.scripts as Record<string, string>),
+  };
+};
+
+export const resolvePackageJsonContent = (
+  packageJsonPath: string,
+  rootDir: string,
+  validations: ("workspaces" | "name" | "scripts")[],
+): ResolvedPackageJsonContent => {
+  rootDir = path.resolve(rootDir);
+
+  let json: UnknownPackageJson = {};
+  try {
+    json = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+  } catch (error) {
+    logger.error(error);
+    throw new ERRORS.InvalidPackageJson(
+      `Failed to read and parse package.json at ${packageJsonPath}: ${
+        (error as Error).message
+      }`,
+    );
+  }
+
+  validateJsonRoot(json);
+
+  return {
+    ...json,
+    name: validations.includes("name")
+      ? validateName(json)
+      : ((json.name as string) ?? ""),
+    workspaces: validations.includes("workspaces")
+      ? validateWorkspacePatterns(json, rootDir)
+      : ((json?.workspaces ?? []) as string[]),
+    scripts: validations.includes("scripts")
+      ? validateScripts(json)
+      : ((json.scripts ?? {}) as Record<string, string>),
+  };
+};

package/src/workspaces/workspace.ts

@@ -0,0 +1,12 @@
+import type { ResolvedPackageJsonContent } from "./packageJson";
+
+export interface Workspace {
+  /** The name of the workspace from its `package.json` */
+  name: string;
+  /** The relative path to the workspace from the root `package.json` */
+  path: string;
+  /** The pattern from `"workspaces"` in the root `package.json`that this workspace was matched from*/
+  matchPattern: string;
+  /** The contents of the workspace's package.json, with `"workspaces"` and `"scripts"` resolved */
+  packageJson: ResolvedPackageJsonContent;
+}

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    // Enable latest features
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  },
+  "include": ["src", "bin"]
+}