bun-workspaces 1.0.0-alpha.9 → 1.0.0

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,39 +1,232 @@
-<img src="./packages/doc-website/src/docs/public/bw-eye.png" alt="bun-workspaces" width="50" />
+<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 that works 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.
+### [**See Full Documentation Here**: _https://bunworkspaces.com_](https://bunworkspaces.com)
 
-### **[See Full Documentation Here](https://bunworkspaces.com)**
+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.
+
+- 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 🐚
+
+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.
+
+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.
+
+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.
+
+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.
 
 ## Quick Start
 
-You can install the CLI in your project or simply use `bunx bun-workspaces`.
+Installation:
 
 ```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
 ```
 
+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.
+
+### CLI
+
+[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"
 
-# Usage (--help can also be passed to any command)
+# List all workspaces in your project
+bw list-workspaces
+
+# 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 --json --pretty # info is alias for workspace-info
+
+# Get info about a script, such as the workspaces that have it
+bw script-info my-script
+
+# 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)
+
+bw run lint "my-workspace-*" # Run for matching workspace names
+bw run lint "alias:my-alias-pattern-*" "path:my-glob/**/*" # Use matching specifiers
+
+# 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
+
+# Continue running scripts even if a dependency fails
+bw run lint --dep-order --ignore-dep-failure
+
+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
+
+bw run "bun build" --inline # Run an inline command via the Bun shell
+
+# 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
+
+# Use the grouped output style (default when on a TTY)
+bw run my-script --output-style=grouped
+
+# 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
+
+# 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
 
-# Get JSON metadata
-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
-
-# Run scripts across workspaces
-bw run my-script
-bw run my-script my-workspace
-bw run my-script workspace-a workspace-b
-bw run my-script "my-workspace-*"
-bw run my-script --parallel
-bw run my-script --args "--my --args"
-bw run my-script --args "--my --args=<workspace>"
+# Show version
+bw --version
+
+# Pass --cwd to any command
+bw --cwd=/path/to/your/project ls
+bw --cwd=/path/to/your/project run my-script
+
+# Pass --log-level to any command (debug, info, warn, error, or silent)
+bw --log-level=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,3 +1,3 @@
 #!/usr/bin/env bun
-import { createCli } from "bun-workspaces";
+import { createCli } from "bun-workspaces/src/cli";
 createCli().run();

package/package.json

@@ -1,21 +1,37 @@
 {
   "name": "bun-workspaces",
-  "version": "1.0.0-alpha.9",
+  "version": "1.0.0",
+  "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.3.0",
-      "libraryConsumer": "^1.1.x"
+      "build": "1.3.5",
+      "libraryConsumer": "^1.2.0"
     }
   },
   "dependencies": {
-    "commander": "^12.1.0",
-    "glob": "^11.0.3"
+    "commander": "^12.1.0"
   }
-}
+}

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

@@ -0,0 +1,45 @@
+import { type Command } from "commander";
+import type { FileSystemProject } from "../../project/implementations/fileSystemProject";
+import type { Workspace } from "../../workspaces";
+import {
+  type CliGlobalCommandName,
+  type CliProjectCommandName,
+} from "./commandsConfig";
+/** @todo DRY use of output text in cases such as having no workspaces/scripts */
+export interface GlobalCommandContext {
+  program: Command;
+  postTerminatorArgs: string[];
+}
+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,81 @@
+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}`);
+      await handler(context, ...actionArgs);
+    } catch (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) {
+      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 };