bun-workspaces 1.0.1-alpha → 1.0.1

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2024 Scott Morse
+Copyright (c) 2026 Smorsic Labs, LLC
 
 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,232 @@
+<a href="https://bunworkspaces.com">
+<img src="./packages/doc-website/src/pages/public/images/png/bwunster-bg-banner-wide_3000x900.png" alt="bun-workspaces" width="100%" />
+</a>
+
 # bun-workspaces
 
-This is a CLI meant to help manage [Bun workspaces](https://bun.sh/docs/install/workspaces).
+### [**See Full Documentation Here**: _https://bunworkspaces.com_](https://bunworkspaces.com)
 
-## Installation
+A CLI and API to enhance your monorepo development with Bun's [native workspaces](https://bun.sh/docs/install/workspaces) feature for nested JavaScript/TypeScript packages.
 
-You can install the CLI in your project or simply use `bunx bun-workspaces`.
+- Works right away, with no boilerplate required 🍔🍴
+- Get metadata about your monorepo 🤖
+- Run package.json scripts across workspaces 📋
+- Run inline [Bun Shell](https://bun.com/docs/runtime/shell) scripts in workspaces 🐚
 
-```bash
-$ bun add --dev bun-workspaces
-$ bunx bun-workspaces --help
-```
+This is a tool to help manage a Bun monorepo, offering features beyond what [Bun's --filter feature](https://bun.com/docs/pm/filter) can do. It can be used to get a variety of metadata about your project and run scripts across your workspaces with advanced control.
 
-### Config file
+To get started, all you need is a repo using [Bun's workspaces feature](https://bun.sh/docs/install/workspaces) for nested JavaScript/TypeScript packages.
 
-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.
+This package is unopinionated and works with any project structure you want. Think of this as a power suit you can snap onto native workspaces, rather than whole new monorepo framework.
 
-#### Example config
+Start running some [CLI commands](https://bunworkspaces.com/cli) right away in your repo, or take full advantage of the [scripting API](https://bunworkspaces.com/api) and its features.
 
-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".
+## Quick Start
 
-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.
+Installation:
 
-```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.
+Note that you need to run `bun install` in your project for `bun-workspaces` to find your project's workspaces. This is because it reads `bun.lock`. This also means that if you update your workspaces, such as changing their name, you must run `bun install` for the change to reflect.
 
-### 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
+# You can add this to .bashrc, .zshrc, or similar.
+# You can also invoke "bw" in your root package.json scripts.
 alias bw="bunx bun-workspaces"
 
-# List all workspaces
+# List all workspaces in your project
 bw list-workspaces
-bw ls
 
-# List workspace names only
-bw list-workspaces --name-only
-
-# Filter list of workspaces with wildcard
-bw list-workspaces "my-*"
-
-# List all workspace scripts
-bw list-scripts
-
-# List script names only
-bw list-scripts --name-only
+# ls is an alias for list-workspaces
+bw ls --json --pretty # Output as formatted JSON
 
 # Get info about a workspace
 bw workspace-info my-workspace
-bw info my-workspace
+bw info my-workspace --json --pretty # info is alias for workspace-info
 
-# Get info about a script
+# Get info about a script, such as the workspaces that have it
 bw script-info my-script
 
-# Only print list of workspace names that have the script
-bw script-info my-script --workspaces-only
+# Run the lint script for all workspaces
+# that have it in their package.json "scripts" field
+bw run-script lint
+
+# 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-alias-a my-alias-b # Run by alias (set by optional config)
 
-# 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
+bw run lint "my-workspace-*" # Run for matching workspace names
+bw run lint "alias:my-alias-pattern-*" "path:my-glob/**/*" # Use matching specifiers
 
-# Run a script for all
-# workspaces that have it
-# in their `scripts` field
-bw run my-script
+# A workspace's script will wait until any workspaces it depends on have completed
+# Similar to Bun's --filter behavior
+bw run lint --dep-order
 
-# Run a script for a specific workspace by its package.json name or alias from the config
-bw run my-script my-workspace
+# Continue running scripts even if a dependency fails
+bw run lint --dep-order --ignore-dep-failure
 
-# Run a script for multiple workspaces
-bw run my-script workspace-a workspace-b
+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
 
-# Run a script for workspaces using wildcard (does not take into account workspace aliases)
-bw run my-script "my-workspace-*"
+bw run "bun build" --inline # Run an inline command via the Bun shell
 
-# Run script in parallel for all workspaces
-bw run my-script --parallel
+# Scripts run in parallel by default
+bw run lint --parallel=false # Run in series
+bw run lint --parallel=2 # Run in parallel with a max of 2 concurrent scripts
+bw run lint --parallel=auto # Default, based on number of available logical CPUs
 
-# Append args to each script call
-bw run my-script --args "--my --args"
+# Use the grouped output style (default when on a TTY)
+bw run my-script --output-style=grouped
 
-# Use the workspace name in args
-bw run my-script --args "--my --args=<workspace>"
+# Set the max preview lines for script output in grouped output style
+bw run my-script --output-style=grouped --grouped-lines=all
+bw run my-script --output-style=grouped --grouped-lines=10
 
-# Help (--help can also be passed to any command)
+# Use simple script output with workspace prefixes (default when not on a TTY)
+bw run my-script --output-style=prefixed
+
+# Use the plain output style (no workspace prefixes)
+bw run my-script --output-style=plain
+
+# Show usage (you can pass --help to any command)
 bw help
 bw --help
 
+# Show version
+bw --version
+
 # Pass --cwd to any command
-bw --cwd /path/to/your/project ls
-bw --cwd /path/to/your/project run-script my-script
+bw --cwd=/path/to/your/project ls
+bw --cwd=/path/to/your/project run my-script
 
-# Pass --configFile to any command
-bw --configFile /path/to/your/config.json ls
+# Pass --log-level to any command (debug, info, warn, error, or silent)
+bw --log-level=silent run my-script
+```
 
-# Pass --logLevel to any command (debug, info, warn, error, or silent)
-bw --logLevel silent run my-script
+### API
+
+[Full API documentation here](https://bunworkspaces.com/api)
+
+```typescript
+import { createFileSystemProject } from "bun-workspaces";
+
+// A Project contains the core functionality of bun-workspaces.
+// Below defaults to process.cwd() for the project root directory
+// Pass { rootDirectory: "path/to/your/project" } to use a different root directory
+const project = createFileSystemProject();
+
+// A Workspace that matches the name or alias "my-workspace"
+const myWorkspace = project.findWorkspaceByNameOrAlias("my-workspace");
+
+// Array of workspaces whose names match the wildcard pattern
+const wildcardWorkspaces = project.findWorkspacesByPattern("my-workspace-*");
+
+// Array of workspaces that have "my-script" in their package.json "scripts"
+const workspacesWithScript = project.listWorkspacesWithScript("my-script");
+
+// 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
+  });
+
+  // Get a stream of the script subprocess's output
+  for await (const { chunk, metadata } of output.text()) {
+    // console.log(chunk); // the content (string)
+    // console.log(metadata.streamName); // "stdout" or "stderr"
+    // console.log(metadata.workspace); // the workspace that the output came from
+  }
+
+  // Get data about the script execution after it exits
+  const exitResult = await exit;
+
+  // exitResult.exitCode // The exit code (number)
+  // exitResult.signal // The exit signal (string), or null
+  // exitResult.success // true if exit code was 0
+  // exitResult.startTimeISO // Start time (string)
+  // exitResult.endTimeISO // End time (string)
+  // exitResult.durationMs // Duration in milliseconds (number)
+  // 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({
+    // Optional. This will run in all matching workspaces that have my-script
+    // Accepts same values as the CLI run-script command's workspace patterns
+    // When not provided, all workspaces that have the script will be used.
+    workspacePatterns: ["my-workspace", "my-name-pattern-*"],
+
+    // Required. The package.json "scripts" field name to run
+    script: "my-script",
+
+    // Optional. Arguments to add to the command
+    args: "--my --appended --args",
+
+    // Optional. Whether to run the scripts in parallel (default: true)
+    parallel: true,
+
+    // Optional. When true, a workspace's script will wait
+    // until any workspaces it depends on have completed
+    dependencyOrder: false,
+
+    // Optional. When true and dependencyOrder is true,
+    // continue running scripts even if a dependency fails
+    ignoreDependencyFailure: false,
+
+    // Optional, callback when script starts, skips, or exits
+    onScriptEvent: (event, { workspace, exitResult }) => {
+      // event: "start", "skip", "exit"
+    },
+  });
+
+  // Get a stream of script output
+  for await (const { chunk, metadata } of output.text()) {
+    // console.log(chunk); // the content (string)
+    // console.log(metadata.streamName); // "stdout" or "stderr"
+    // console.log(metadata.workspace); // the workspace that the output came from
+  }
+
+  // Get final summary data and script exit details after all scripts have completed
+  const summaryResult = await summary;
+
+  // summaryResult.totalCount // Total number of scripts
+  // summaryResult.allSuccess // true if all scripts succeeded
+  // summaryResult.successCount // Number of scripts that succeeded
+  // summaryResult.failureCount // Number of scripts that failed
+  // summaryResult.startTimeISO // Start time (string)
+  // summaryResult.endTimeISO // End time (string)
+  // summaryResult.durationMs // Total duration in milliseconds (number)
+
+  // The exit details of each workspace script
+  for (const exitResult of summaryResult.scriptResults) {
+    // exitResult.exitCode // The exit code (number)
+    // exitResult.signal // The exit signal (string), or null
+    // exitResult.success // true if exit code was 0
+    // exitResult.startTimeISO // Start time (ISO string)
+    // exitResult.endTimeISO // End time (ISO string)
+    // exitResult.durationMs // Duration in milliseconds (number)
+    // 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 Anthropic. This project aims to enhance the experience of Bun for its users._
+
+Developed By:
+
+<a href="https://smorsic.io" target="_blank" rel="noopener noreferrer">
+  <img src="./packages/doc-website/src/pages/public/images/png/smorsic-banner_light_803x300.png" alt="Smorsic Labs logo" width="280" />
+</a>

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,37 @@
 {
   "name": "bun-workspaces",
-  "version": "1.0.1-alpha",
-  "main": "src/index.ts",
-  "homepage": "https://github.com/ScottMorse/bun-workspaces#readme",
+  "version": "1.0.1",
+  "description": "A monorepo management tool for Bun, with a CLI and API to enhance Bun's native workspaces.",
+  "license": "MIT",
+  "main": "src/index.mjs",
+  "types": "src/index.d.ts",
+  "homepage": "https://bunworkspaces.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bun-workspaces/bun-workspaces.git"
+  },
+  "keywords": [
+    "bun",
+    "workspace",
+    "workspaces",
+    "monorepo",
+    "cli",
+    "api"
+  ],
+  "engines": {
+    "bun": "^1.2.0"
+  },
   "bin": {
-    "bun-workspaces": "bin/cli.js"
+    "bun-workspaces": "bin/cli.js",
+    "bw": "bin/cli.js"
   },
-  "custom": {
+  "_bwInternal": {
     "bunVersion": {
-      "build": "1.2.22",
-      "libraryConsumer": "^1.1.x"
+      "build": "1.3.5",
+      "libraryConsumer": "^1.2.0"
     }
   },
-  "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"
+    "commander": "^12.1.0"
   }
 }

package/src/cli/commands/commandHandlerUtils.d.ts

@@ -0,0 +1,49 @@
+import { type Command } from "commander";
+import type { FileSystemProject } from "../../project/implementations/fileSystemProject";
+import type { Workspace } from "../../workspaces";
+import type { WriteOutputOptions } from "../createCli";
+import type { CliMiddleware } from "../middleware";
+import {
+  type CliGlobalCommandName,
+  type CliProjectCommandName,
+} from "./commandsConfig";
+/** @todo DRY use of output text in cases such as having no workspaces/scripts */
+export type GlobalCommandContext = {
+  program: Command;
+  postTerminatorArgs: string[];
+  middleware: CliMiddleware;
+  outputWriters: Required<WriteOutputOptions>;
+};
+export type ProjectCommandContext = GlobalCommandContext & {
+  project: FileSystemProject;
+  projectError: Error | null;
+};
+/** Splits workspace patterns by whitespace, but allows escaping spaces via backslash */
+export declare const splitWorkspacePatterns: (
+  workspacePatterns: string,
+) => string[];
+export declare const createWorkspaceInfoLines: (
+  workspace: Workspace,
+) => string[];
+export declare const createScriptInfoLines: (
+  script: string,
+  workspaces: Workspace[],
+) => string[];
+export declare const createJsonLines: (
+  data: unknown,
+  options: {
+    pretty: boolean;
+  },
+) => string[];
+export declare const commandOutputLogger: import("../../internal/logger").Logger;
+export declare const handleGlobalCommand: <ActionArgs extends unknown[]>(
+  commandName: CliGlobalCommandName,
+  handler: (context: GlobalCommandContext, ...actionArgs: ActionArgs) => void,
+) => (context: GlobalCommandContext) => Command;
+export declare const handleProjectCommand: <ActionArgs extends unknown[]>(
+  commandName: CliProjectCommandName,
+  handler: (
+    context: Omit<ProjectCommandContext, "projectError">,
+    ...actionArgs: ActionArgs
+  ) => void,
+) => (context: ProjectCommandContext) => Command;

package/src/cli/commands/commandHandlerUtils.mjs

@@ -0,0 +1,91 @@
+import { Option } from "commander";
+import { BunWorkspacesError } from "../../internal/core/error/index.mjs";
+import { createLogger, logger } from "../../internal/logger/index.mjs";
+import { getCliCommandConfig } from "./commandsConfig.mjs"; // CONCATENATED MODULE: external "commander"
+// CONCATENATED MODULE: external "../../internal/core/error/index.mjs"
+// CONCATENATED MODULE: external "../../internal/logger/index.mjs"
+// CONCATENATED MODULE: external "./commandsConfig.mjs"
+// CONCATENATED MODULE: ./src/cli/commands/commandHandlerUtils.ts
+
+/** Splits workspace patterns by whitespace, but allows escaping spaces via backslash */ const splitWorkspacePatterns =
+  (workspacePatterns) =>
+    workspacePatterns
+      .split(/(?<!\\)\s+/)
+      .filter(Boolean)
+      .map((pattern) => pattern.replace(/\\\s/g, " "));
+const createWorkspaceInfoLines = (workspace) => [
+  `Workspace: ${workspace.name}${workspace.isRoot ? " (root)" : ""}`,
+  ` - Aliases: ${workspace.aliases.join(", ")}`,
+  ` - Path: ${workspace.path}`,
+  ` - Glob Match: ${workspace.matchPattern}`,
+  ` - Scripts: ${workspace.scripts.join(", ")}`,
+  ` - Dependencies: ${workspace.dependencies.join(", ")}`,
+  ` - Dependents: ${workspace.dependents.join(", ")}`,
+];
+const createScriptInfoLines = (script, workspaces) => [
+  `Script: ${script}`,
+  ...workspaces.map((workspace) => ` - ${workspace.name}`),
+];
+const createJsonLines = (data, options) =>
+  JSON.stringify(data, null, options.pretty ? 2 : undefined).split("\n");
+const commandOutputLogger = createLogger("");
+commandOutputLogger.printLevel = "info";
+const handleCommand = (commandName, handler) => (context) => {
+  const config = getCliCommandConfig(commandName);
+  let { program } = context;
+  program = program
+    .command(config.command)
+    .aliases(config.aliases)
+    .description(config.description);
+  for (const { flags, description, values } of Object.values(config.options)) {
+    const option = new Option(flags.join(", "), description);
+    if (values?.length) {
+      option.choices(values);
+    }
+    program.addOption(option);
+  }
+  program = program.action(async (...actionArgs) => {
+    try {
+      logger.debug(`Handling command: ${commandName}`);
+      const middlewareContext = {
+        commanderProgram: program,
+        commandName,
+        commandContext: context,
+        commanderActionArgs: actionArgs,
+      };
+      program = context.middleware.preHandleCommand(middlewareContext);
+      await handler(context, ...actionArgs);
+      program = context.middleware.postHandleCommand(middlewareContext);
+    } catch (error) {
+      context.middleware.catchError(error);
+      if (error instanceof BunWorkspacesError) {
+        logger.error(error.message);
+        process.exit(1);
+      }
+      throw error;
+    }
+  });
+  return program;
+};
+const handleGlobalCommand = (commandName, handler) => (context) =>
+  handleCommand(commandName, handler)(context);
+const handleProjectCommand = (commandName, handler) => (context) =>
+  handleCommand(commandName, async (context, ...actionArgs) => {
+    const { projectError } = context;
+    if (projectError) {
+      context.middleware.catchError(projectError);
+      logger.error(projectError.message);
+      process.exit(1);
+    }
+    await handler(context, ...actionArgs);
+  })(context);
+
+export {
+  commandOutputLogger,
+  createJsonLines,
+  createScriptInfoLines,
+  createWorkspaceInfoLines,
+  handleGlobalCommand,
+  handleProjectCommand,
+  splitWorkspacePatterns,
+};

package/src/cli/commands/commands.d.ts

@@ -0,0 +1,10 @@
+import type {
+  GlobalCommandContext,
+  ProjectCommandContext,
+} from "./commandHandlerUtils";
+export declare const defineGlobalCommands: (
+  context: GlobalCommandContext,
+) => void;
+export declare const defineProjectCommands: (
+  context: ProjectCommandContext,
+) => void;

package/src/cli/commands/commands.mjs

@@ -0,0 +1,23 @@
+import {
+  doctor,
+  listScripts,
+  listWorkspaces,
+  scriptInfo,
+  workspaceInfo,
+} from "./handleSimpleCommands.mjs";
+import { runScript } from "./runScript/index.mjs"; // CONCATENATED MODULE: external "./handleSimpleCommands.mjs"
+// CONCATENATED MODULE: external "./runScript/index.mjs"
+// CONCATENATED MODULE: ./src/cli/commands/commands.ts
+
+const defineGlobalCommands = (context) => {
+  doctor(context);
+};
+const defineProjectCommands = (context) => {
+  listWorkspaces(context);
+  listScripts(context);
+  workspaceInfo(context);
+  scriptInfo(context);
+  runScript(context);
+};
+
+export { defineGlobalCommands, defineProjectCommands };