bun-workspaces 1.0.0-alpha.2 → 1.0.0-alpha.20

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Scott Morse
+Copyright (c) 2025 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

package/README.md

@@ -1,113 +1,158 @@
-# bun-workspaces
-
-This is a CLI meant to help manage [Bun workspaces](https://bun.sh/docs/install/workspaces).
+<img src="./packages/doc-website/src/docs/public/bw-eye.png" alt="bun-workspaces" width="50" />
 
-## Installation
+# bun-workspaces
 
-You can install the CLI in your project or simply use `bunx bun-workspaces`.
+### [**See Full Documentation Here:** _https://bunworkspaces.com_](https://bunworkspaces.com)
 
-```bash
-$ bun add --dev bun-workspaces
-$ bunx bun-workspaces --help
-```
+**_New: [An API is now officially released!](https://bunworkspaces.com/api)_**
 
-### Config file
+This is a CLI and API that help you manage your monorepo on top of native [Bun workspaces](https://bun.sh/docs/install/workspaces), with no additional setup required. Get metadata about your workspaces and scripts, and run scripts across your workspaces.
 
-You can create a config file at `bw.json` in your project root, or you can pass a config file to the CLI with the `--configFile` (or `-c`) option.
+<a href="https://buymeacoffee.com/scottmorse">
+<img src="./packages/doc-website/src/docs/public/bmac-logo-circle.png" alt="Link to Buy Me A Coffee" width="60" />
+</a>
 
-#### Example config
+## Quick Start
 
-In this config, "app-a" is an alias for package "@my-org/application-a" and "app-b" is an alias for package "@my-org/application-b".
+Installation:
 
-CLI log levels are `debug`, `info`, `warn`, and `error` or `silent`. The default log level is `info`. Commands that are intended to print specific output will still print at `silent`, such as `list-workspaces`, `list-scripts`, `workspace-info`, `script-info`, etc., but other logs will be suppressed.
-
-```json
-{
-  "workspaceAliases": {
-    "app-a": "@my-org/application-a",
-    "app-b": "@my-org/application-b"
-  },
-  "cli": {
-    "logLevel": "warn"
-  }
-}
+```bash
+$ # Install to use the API and/or lock your CLI version for your project
+$ bun add --dev bun-workspaces
+$ # Start using the CLI with or without the installation step
+$ bunx bun-workspaces --help
 ```
 
-You can also pass a config file to the CLI with the `-c` or `--configFile` option.
-
-### Examples
+### CLI
 
-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.
+[Full CLI documentation here](https://bunworkspaces.com/cli)
 
 ```bash
-alias bw="bunx bun-workspaces"
+alias bw="bunx bun-workspaces" # can place in .zshrc, .bashrc, or similar
 
-# List all workspaces
+# List all workspaces in your project
 bw list-workspaces
-bw ls
 
-# List workspace names only
-bw list-workspaces --name-only
+# ls is an alias for list-workspaces
+bw ls --json --pretty # Output as formatted JSON
 
-# Filter list of workspaces with wildcard
-bw list-workspaces "my-*"
+# Run the lint script for all workspaces
+# that have it in their "scripts" field
+bw run-script lint
 
-# List all workspace scripts
-bw list-scripts
+# run is an alias for run-script
+bw run lint my-workspace # Run for a single workspace
+bw run lint my-workspace-a my-workspace-b # Run for multiple workspaces
+bw run lint "my-workspace-*" # Run for matching workspace names
+bw run lint --parallel # Run at the same time
+bw run lint --args="--my-appended-args" # Add args to each script call
+bw run lint --args="--my-arg=<workspaceName>" # Use the workspace name in args
 
-# List script names only
-bw list-scripts --name-only
+# Run an inline command from the workspace directory
+bw run "echo 'this is my inline script for <workspaceName>'" --inline
 
-# Get info about a workspace
-bw workspace-info my-workspace
-bw info my-workspace
-
-# Get info about a script
-bw script-info my-script
+# Show usage (you can pass --help to any command)
+bw help
+bw --help
 
-# Only print list of workspace names that have the script
-bw script-info my-script --workspaces-only
+# Pass --cwd to any command
+bw --cwd=/path/to/your/project ls
+bw --cwd=/path/to/your/project run my-script
 
-# Get JSON output
-bw list-workspaces --json --pretty # optionally pretty print JSON
-bw list-scripts --json
-bw workspace-info my-workspace --json
-bw script-info my-script --json
+# Pass --log-level to any command (debug, info, warn, error, or silent)
+bw --log-level=silent run my-script
+```
 
-# Run a script for all
-# workspaces that have it
-# in their `scripts` field
-bw run my-script
+### API
 
-# Run a script for a specific workspace by its package.json name or alias from the config
-bw run my-script my-workspace
+[Full API documentation here](https://bunworkspaces.com/api)
 
-# Run a script for multiple workspaces
-bw run my-script workspace-a workspace-b
+```typescript
+import { createFileSystemProject } from "bun-workspaces";
 
-# Run a script for workspaces using wildcard (does not take into account workspace aliases)
-bw run my-script "my-workspace-*"
+// A Project contains the core functionality of bun-workspaces.
+const project = createFileSystemProject({
+  rootDirectory: "path/to/your/project",
+});
 
-# Run script in parallel for all workspaces
-bw run my-script --parallel
+// A Workspace that matches the name or alias "my-workspace"
+const myWorkspace = project.findWorkspaceByNameOrAlias("my-workspace");
 
-# Append args to each script call
-bw run my-script --args "--my --args"
+// Array of workspaces whose names match the wildcard pattern
+const wildcardWorkspaces = project.findWorkspacesByPattern("my-workspace-*");
 
-# Use the workspace name in args
-bw run my-script --args "--my --args=<workspace>"
+// Array of workspaces that have "my-script" in their package.json "scripts"
+const workspacesWithScript = project.listWorkspacesWithScript("my-script");
 
-# Help (--help can also be passed to any command)
-bw help
-bw --help
+// Run a script in a workspace
+const runSingleScript = async () => {
+  const { output, exit } = project.runWorkspaceScript({
+    workspaceNameOrAlias: "my-workspace",
+    script: "my-script",
+    args: "--my --appended --args", // optional, arguments to add to the command
+  });
 
-# Pass --cwd to any command
-bw --cwd /path/to/your/project ls
-bw --cwd /path/to/your/project run-script my-script
+  // Get a stream of the script subprocess's output
+  for await (const { text, textNoAnsi, streamName } of output) {
+    console.log(text); // The output chunk's content (string)
+    console.log(textNoAnsi); // Text with ANSI codes sanitized (string)
+    console.log(streamName); // The output stream, "stdout" or "stderr"
+  }
 
-# Pass --configFile to any command
-bw --configFile /path/to/your/config.json ls
+  // Get data about the script execution after it exits
+  const exitResult = await exit;
+
+  console.log(exitResult.exitCode); // The exit code (number)
+  console.log(exitResult.signal); // The exit signal (string), or null
+  console.log(exitResult.success); // true if exit code was 0
+  console.log(exitResult.startTimeISO); // Start time (string)
+  console.log(exitResult.endTimeISO); // End time (string)
+  console.log(exitResult.durationMs); // Duration in milliseconds (number)
+  console.log(exitResult.metadata.workspace); // The target workspace (Workspace)
+};
+
+// Run a script in all workspaces that have it in their package.json "scripts" field
+const runManyScripts = async () => {
+  const { output, summary } = project.runScriptAcrossWorkspaces({
+    workspacePatterns: ["*"], // this will run in all workspaces that have my-script
+    script: "my-script", // the package.json "scripts" field name to run
+    args: "--my --appended --args", // optional, arguments to add to the command
+    parallel: true, // optional, run the scripts in parallel
+  });
+
+  // Get a stream of script output
+  for await (const { outputChunk, scriptMetadata } of output) {
+    console.log(outputChunk.text); // the output chunk's content (string)
+    console.log(outputChunk.textNoAnsi); // text with ANSI codes sanitized (string)
+    console.log(outputChunk.streamName); // "stdout" or "stderr"
+
+    // The metadata can distinguish which workspace script
+    // the current output chunk came from
+    console.log(scriptMetadata.workspace); // Workspace object
+  }
 
-# Pass --logLevel to any command (debug, info, warn, error, or silent)
-bw --logLevel silent run my-script
+  // Get final summary data and script exit details after all scripts have completed
+  const summaryResult = await summary;
+
+  console.log(summaryResult.totalCount); // Total number of scripts
+  console.log(summaryResult.allSuccess); // true if all scripts succeeded
+  console.log(summaryResult.successCount); // Number of scripts that succeeded
+  console.log(summaryResult.failureCount); // Number of scripts that failed
+  console.log(summaryResult.startTimeISO); // Start time (string)
+  console.log(summaryResult.endTimeISO); // End time (string)
+  console.log(summaryResult.durationMs); // Total duration in milliseconds (number)
+
+  // The exit details of each workspace script
+  for (const exitResult of summaryResult.scriptResults) {
+    console.log(exitResult.exitCode); // The exit code (number)
+    console.log(exitResult.signal); // The exit signal (string), or null
+    console.log(exitResult.success); // true if exit code was 0
+    console.log(exitResult.startTimeISO); // Start time (ISO string)
+    console.log(exitResult.endTimeISO); // End time (ISO string)
+    console.log(exitResult.durationMs); // Duration in milliseconds (number)
+    console.log(exitResult.metadata.workspace); // The target workspace (Workspace)
+  }
+};
 ```
+
+_`bun-workspaces` is independent from the [Bun](https://bun.sh) project and is not affiliated with or endorsed by Oven. This project aims to enhance enhance the experience of Bun for its users._

package/bin/cli.js

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

package/package.json

@@ -1,40 +1,26 @@
 {
   "name": "bun-workspaces",
-  "version": "1.0.0-alpha.2",
-  "main": "src/index.ts",
-  "homepage": "https://github.com/ScottMorse/bun-workspaces#readme",
+  "version": "1.0.0-alpha.20",
+  "license": "MIT",
+  "main": "src/index.mjs",
+  "types": "src/index.d.ts",
+  "homepage": "https://bunworkspaces.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ScottMorse/bun-workspaces.git"
+  },
   "bin": {
-    "bun-workspaces": "bin/cli.js"
+    "bun-workspaces": "bin/cli.js",
+    "bw": "bin/cli.js"
   },
   "custom": {
     "bunVersion": {
-      "build": "1.2.22",
+      "build": "1.3.1",
       "libraryConsumer": "^1.1.x"
     }
   },
-  "scripts": {
-    "cli": "bun run bin/cli.js",
-    "cli:dev": "_BW_RUNTIME_MODE=development bun run bin/cli.js",
-    "type-check": "tsc --noEmit",
-    "lint": "eslint .",
-    "format": "prettier --write .",
-    "format-check": "prettier --check ."
-  },
-  "devDependencies": {
-    "@types/bun": "^1.2.22",
-    "@typescript-eslint/eslint-plugin": "^8.44.1",
-    "@typescript-eslint/parser": "^8.44.1",
-    "bun-workspaces": "file:.",
-    "eslint": "^9.36.0",
-    "eslint-plugin-import": "^2.32.0",
-    "prettier": "^3.6.2",
-    "typescript-eslint": "^8.44.1"
-  },
   "dependencies": {
     "commander": "^12.1.0",
-    "glob": "^11.0.3"
-  },
-  "peerDependencies": {
-    "typescript": "^5.9.2"
+    "glob": "^11.1.0"
   }
 }

package/src/cli/createCli.d.ts

@@ -0,0 +1,19 @@
+import { type Command } from "commander";
+export interface RunCliOptions {
+  argv?: string | string[];
+  /** Should be `true` if args do not include the binary name (e.g. `bunx bun-workspaces`) */
+  programmatic?: true;
+}
+export interface CLI {
+  run: (options?: RunCliOptions) => Promise<void>;
+}
+export interface CreateCliOptions {
+  handleError?: (error: Error) => void;
+  postInit?: (program: Command) => unknown;
+  defaultCwd?: string;
+}
+export declare const createCli: ({
+  handleError,
+  postInit,
+  defaultCwd,
+}?: CreateCliOptions) => CLI;

package/src/cli/createCli.mjs

@@ -0,0 +1,99 @@
+import { createCommand } from "commander";
+import package_0 from "../../package.json";
+import {
+  getRequiredBunVersion,
+  validateCurrentBunVersion,
+} from "../internal/bunVersion.mjs";
+import { BunWorkspacesError } from "../internal/error.mjs";
+import { logger } from "../internal/logger.mjs";
+import { fatalErrorLogger } from "./fatalErrorLogger.mjs";
+import { initializeWithGlobalOptions } from "./globalOptions/index.mjs";
+import { defineProjectCommands } from "./projectCommands/index.mjs"; // CONCATENATED MODULE: external "commander"
+// CONCATENATED MODULE: external "../../package.json"
+// CONCATENATED MODULE: external "../internal/bunVersion.mjs"
+// CONCATENATED MODULE: external "../internal/error.mjs"
+// CONCATENATED MODULE: external "../internal/logger.mjs"
+// CONCATENATED MODULE: external "./fatalErrorLogger.mjs"
+// CONCATENATED MODULE: external "./globalOptions/index.mjs"
+// CONCATENATED MODULE: external "./projectCommands/index.mjs"
+// CONCATENATED MODULE: ./src/cli/createCli.ts
+
+const createCli = ({
+  handleError,
+  postInit,
+  defaultCwd = process.cwd(),
+} = {}) => {
+  const run = async ({ argv = process.argv, programmatic } = {}) => {
+    const errorListener =
+      handleError ??
+      ((error) => {
+        fatalErrorLogger.error(error);
+        process.exit(1);
+      });
+    process.on("unhandledRejection", errorListener);
+    try {
+      const program = createCommand("bunx bun-workspaces")
+        .description("A CLI on top of native Bun workspaces")
+        .version(package_0.version)
+        .showHelpAfterError(true);
+      postInit?.(program);
+      if (!validateCurrentBunVersion()) {
+        fatalErrorLogger.error(
+          `Bun version mismatch. Required: ${getRequiredBunVersion()}, Found: ${Bun.version}`,
+        );
+        process.exit(1);
+      }
+      const args = tempFixCamelCaseOptions(
+        typeof argv === "string" ? argv.split(/s+/) : argv,
+      );
+      const { project, error } = initializeWithGlobalOptions(
+        program,
+        args,
+        defaultCwd,
+      );
+      defineProjectCommands({
+        program,
+        project,
+        projectError: error,
+      });
+      await program.parseAsync(args, {
+        from: programmatic ? "user" : "node",
+      });
+      if (error) throw error;
+    } catch (error) {
+      if (error instanceof BunWorkspacesError) {
+        logger.debug(error);
+        fatalErrorLogger.error(error.message);
+        process.exit(1);
+      } else {
+        errorListener(error);
+      }
+    } finally {
+      process.off("unhandledRejection", errorListener);
+    }
+  };
+  return {
+    run,
+  };
+};
+/**
+ * @todo
+ * ! Temp backwards support for deprecated camel case options
+ * ! Added October 2025, drop support in some reasonable future release
+ */ const tempOptions = {
+  "--nameOnly": "--name-only",
+  "--noPrefix": "--no-prefix",
+  "--configFile": "--config-file",
+  "--logLevel": "--log-level",
+};
+const tempFixCamelCaseOptions = (args) =>
+  args.map((arg) => {
+    for (const [camel, kebab] of Object.entries(tempOptions)) {
+      if (arg.startsWith(camel)) {
+        return arg.replace(camel, kebab);
+      }
+    }
+    return arg;
+  });
+
+export { createCli };

package/src/cli/fatalErrorLogger.d.ts

@@ -0,0 +1 @@
+export declare const fatalErrorLogger: import("../internal/logger").Logger;

package/src/cli/fatalErrorLogger.mjs

@@ -0,0 +1,7 @@
+import { createLogger } from "../internal/logger.mjs"; // CONCATENATED MODULE: external "../internal/logger.mjs"
+// CONCATENATED MODULE: ./src/cli/fatalErrorLogger.ts
+
+const fatalErrorLogger = createLogger("fatalError");
+fatalErrorLogger.printLevel = "error";
+
+export { fatalErrorLogger };

package/src/cli/globalOptions/globalOptions.d.ts

@@ -0,0 +1,38 @@
+import { type Command } from "commander";
+export declare const initializeWithGlobalOptions: (
+  program: Command,
+  args: string[],
+  defaultCwd: string,
+) => {
+  project: import("../../internal/types").Simplify<{
+    readonly rootDirectory: string;
+    readonly workspaces: import("../..").Workspace[];
+    readonly name: string;
+    readonly sourceType: "fileSystem";
+    runWorkspaceScript(
+      options: import("../..").RunWorkspaceScriptOptions,
+    ): import("../..").RunWorkspaceScriptResult;
+    runScriptAcrossWorkspaces(
+      options: import("../..").RunScriptAcrossWorkspacesOptions,
+    ): import("../..").RunScriptAcrossWorkspacesResult;
+    listWorkspacesWithScript(scriptName: string): import("../..").Workspace[];
+    mapScriptsToWorkspaces(): Record<
+      string,
+      import("../..").WorkspaceScriptMetadata
+    >;
+    findWorkspaceByName(
+      workspaceName: string,
+    ): import("../..").Workspace | null;
+    findWorkspaceByAlias(alias: string): import("../..").Workspace | null;
+    findWorkspaceByNameOrAlias(
+      nameOrAlias: string,
+    ): import("../..").Workspace | null;
+    findWorkspacesByPattern(
+      workspacePattern: string,
+    ): import("../..").Workspace[];
+    createScriptCommand(
+      options: import("../..").CreateProjectScriptCommandOptions,
+    ): import("../..").CreateProjectScriptCommandResult;
+  }>;
+  error: Error | null;
+};

package/src/cli/globalOptions/globalOptions.mjs

@@ -0,0 +1,120 @@
+import node_fs from "node:fs";
+import node_path from "node:path";
+import { Option } from "commander";
+import {
+  DEFAULT_CONFIG_FILE_PATH,
+  loadConfigFile,
+} from "../../config/index.mjs";
+import { defineErrors } from "../../internal/error.mjs";
+import { logger } from "../../internal/logger.mjs";
+import {
+  _internalCreateFileSystemProject,
+  createMemoryProject,
+} from "../../project/index.mjs";
+import { getCliGlobalOptionConfig } from "./globalOptionsConfig.mjs"; // CONCATENATED MODULE: external "node:fs"
+// CONCATENATED MODULE: external "node:path"
+// CONCATENATED MODULE: external "commander"
+// CONCATENATED MODULE: external "../../config/index.mjs"
+// CONCATENATED MODULE: external "../../internal/error.mjs"
+// CONCATENATED MODULE: external "../../internal/logger.mjs"
+// CONCATENATED MODULE: external "../../project/index.mjs"
+// CONCATENATED MODULE: external "./globalOptionsConfig.mjs"
+// CONCATENATED MODULE: ./src/cli/globalOptions/globalOptions.ts
+
+const ERRORS = defineErrors(
+  "WorkingDirectoryNotFound",
+  "WorkingDirectoryNotADirectory",
+);
+const addGlobalOption = (program, optionName, defaultOverride) => {
+  const { mainOption, shortOption, description, param, values, defaultValue } =
+    getCliGlobalOptionConfig(optionName);
+  let option = new Option(
+    `${shortOption} ${mainOption}${param ? ` <${param}>` : ""}`,
+    description,
+  );
+  const effectiveDefaultValue = defaultOverride ?? defaultValue;
+  if (effectiveDefaultValue) {
+    option = option.default(effectiveDefaultValue);
+  }
+  if (values?.length) {
+    option = option.choices(values);
+  }
+  program.addOption(option);
+};
+const getWorkingDirectoryFromArgs = (program, args, defaultCwd) => {
+  addGlobalOption(program, "cwd", defaultCwd);
+  program.parseOptions(args);
+  return program.opts().cwd;
+};
+const getConfigFileFromArgs = (program, args) => {
+  addGlobalOption(program, "configFile");
+  program.parseOptions(args);
+  return program.opts().configFile;
+};
+const defineGlobalOptions = (program, args, defaultCwd) => {
+  const cwd = getWorkingDirectoryFromArgs(program, args, defaultCwd);
+  if (!node_fs.existsSync(cwd)) {
+    throw new ERRORS.WorkingDirectoryNotFound(
+      `Working directory not found at path "${cwd}"`,
+    );
+  }
+  if (!node_fs.statSync(cwd).isDirectory()) {
+    throw new ERRORS.WorkingDirectoryNotADirectory(
+      `Working directory is not a directory at path "${cwd}"`,
+    );
+  }
+  const configFilePath = getConfigFileFromArgs(program, args);
+  const config = loadConfigFile(configFilePath, cwd);
+  if (config) {
+    logger.warn(
+      // TODO link to docs
+      `Using the config file at ${configFilePath || DEFAULT_CONFIG_FILE_PATH} is deprecated. Migrate to the new workspace config file.`,
+    );
+  }
+  addGlobalOption(program, "logLevel");
+  return {
+    cwd,
+    config,
+  };
+};
+const applyGlobalOptions = (options, config) => {
+  logger.printLevel = options.logLevel;
+  logger.debug("Log level: " + options.logLevel);
+  let project;
+  let error = null;
+  try {
+    project = _internalCreateFileSystemProject({
+      rootDirectory: options.cwd,
+      workspaceAliases: config?.project?.workspaceAliases ?? {},
+    });
+    logger.debug(
+      `Project: ${JSON.stringify(project.name)} (${project.workspaces.length} workspace${project.workspaces.length === 1 ? "" : "s"})`,
+    );
+    logger.debug("Project root: " + node_path.resolve(project.rootDirectory));
+  } catch (_error) {
+    error = _error;
+    project = createMemoryProject({
+      workspaces: [],
+    });
+  }
+  return {
+    project,
+    error,
+  };
+};
+const initializeWithGlobalOptions = (program, args, defaultCwd) => {
+  program.allowUnknownOption(true);
+  const { cwd, config } = defineGlobalOptions(program, args, defaultCwd);
+  program.parseOptions(args);
+  program.allowUnknownOption(false);
+  const options = program.opts();
+  return applyGlobalOptions(
+    {
+      ...options,
+      cwd,
+    },
+    config,
+  );
+};
+
+export { initializeWithGlobalOptions };

package/src/cli/globalOptions/globalOptionsConfig.d.ts

@@ -0,0 +1,43 @@
+import { type LogLevelSetting } from "../../internal/logger";
+export interface CliGlobalOptions {
+  logLevel: LogLevelSetting;
+  cwd: string;
+  configFile?: string;
+}
+export interface CliGlobalOptionConfig {
+  mainOption: string;
+  shortOption: string;
+  description: string;
+  defaultValue: string;
+  values: LogLevelSetting[] | null;
+  param: string;
+}
+export type CliGlobalOptionName = keyof CliGlobalOptions;
+export declare const getCliGlobalOptionConfig: (
+  optionName: CliGlobalOptionName,
+) =>
+  | {
+      readonly mainOption: "--log-level";
+      readonly shortOption: "-l";
+      readonly description: "Log levels";
+      readonly defaultValue: "info";
+      readonly values: ["debug", "info", "warn", "error", "silent"];
+      readonly param: "level";
+    }
+  | {
+      readonly mainOption: "--cwd";
+      readonly shortOption: "-d";
+      readonly description: "Working directory";
+      readonly defaultValue: ".";
+      readonly values: null;
+      readonly param: "path";
+    }
+  | {
+      readonly mainOption: "--config-file";
+      readonly shortOption: "-c";
+      readonly description: "(DEPRECATED) Config file";
+      readonly defaultValue: "";
+      readonly values: null;
+      readonly param: "path";
+    };
+export declare const getCliGlobalOptionNames: () => CliGlobalOptionName[];