bun-workspaces 1.0.0-alpha.3 → 1.0.0-alpha.30

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,167 @@
-# bun-workspaces
+<img src="./packages/doc-website/src/docs/public/images/png/bwunster_64x70.png" alt="bun-workspaces" width="45" />
 
-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
+# bun-workspaces
 
-You can install the CLI in your project or simply use `bunx bun-workspaces`.
+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.
 
-```bash
-$ bun add --dev bun-workspaces
-$ bunx bun-workspaces --help
-```
+- 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 ⌨️
 
-### Config file
+This tool lets you decide the complexity of how you use it.
+To get started, all you need is a normal project using [Bun's native workspaces](https://bun.sh/docs/install/workspaces) feature 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.
+Think of this as a power suit you can snap onto native workspaces, rather than another 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.
-
-### 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
 
-# Filter list of workspaces with wildcard
-bw list-workspaces "my-*"
+# ls is an alias for list-workspaces
+bw ls --json --pretty # Output as formatted JSON
 
-# List all workspace scripts
-bw list-scripts
+# Run the lint script for all workspaces
+# that have it in their package.json "scripts" field
+bw run-script lint
 
-# List script names only
-bw list-scripts --name-only
+# 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
+bw run "bun build" --inline --inline-name=build # Run an inline command
 
-# Get info about a workspace
-bw workspace-info my-workspace
-bw info my-workspace
+# Show usage (you can pass --help to any command)
+bw help
+bw --help
 
-# Get info about a script
-bw script-info my-script
+# Show version
+bw --version
 
-# 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 chunk of output) {
+    console.log(chunk.raw); // The raw output content (Uint8Array)
+    console.log(chunk.decode()); // The output chunk's content (string)
+    console.log(chunk.decode({ stripAnsi: true })); // Text with ANSI codes sanitized
+    console.log(chunk.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.raw); // The raw output content (Uint8Array)
+    console.log(outputChunk.decode()); // the output chunk's content (string)
+    console.log(outputChunk.decode({ stripAnsi: true })); // 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 Anthropic. 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,34 @@
 {
   "name": "bun-workspaces",
-  "version": "1.0.0-alpha.3",
-  "main": "src/index.ts",
-  "homepage": "https://github.com/ScottMorse/bun-workspaces#readme",
+  "version": "1.0.0-alpha.30",
+  "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"
+  ],
   "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.4",
+      "libraryConsumer": "^1.2.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"
+    "commander": "^12.1.0"
   }
 }

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

@@ -0,0 +1,41 @@
+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;
+};
+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,59 @@
+import { Option } from "commander";
+import { createLogger, logger } from "../../internal/logger/index.mjs";
+import { getCliCommandConfig } from "./commandsConfig.mjs"; // CONCATENATED MODULE: external "commander"
+// CONCATENATED MODULE: external "../../internal/logger/index.mjs"
+// CONCATENATED MODULE: external "./commandsConfig.mjs"
+// CONCATENATED MODULE: ./src/cli/commands/commandHandlerUtils.ts
+
+const createWorkspaceInfoLines = (workspace) => [
+  `Workspace: ${workspace.name}`,
+  ` - Aliases: ${workspace.aliases.join(", ")}`,
+  ` - Path: ${workspace.path}`,
+  ` - Glob Match: ${workspace.matchPattern}`,
+  ` - Scripts: ${workspace.scripts.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((...actionArgs) => handler(context, ...actionArgs));
+  return program;
+};
+const handleGlobalCommand = (commandName, handler) => (context) =>
+  handleCommand(commandName, handler)(context);
+const handleProjectCommand = (commandName, handler) => (context) =>
+  handleCommand(commandName, (context, ...actionArgs) => {
+    const { projectError } = context;
+    if (projectError) {
+      logger.error(projectError.message);
+      process.exit(1);
+    }
+    handler(context, ...actionArgs);
+  })(context);
+
+export {
+  commandOutputLogger,
+  createJsonLines,
+  createScriptInfoLines,
+  createWorkspaceInfoLines,
+  handleGlobalCommand,
+  handleProjectCommand,
+};

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 { runScript } from "./handleRunScript.mjs";
+import {
+  doctor,
+  listScripts,
+  listWorkspaces,
+  scriptInfo,
+  workspaceInfo,
+} from "./handleSimpleCommands.mjs"; // CONCATENATED MODULE: external "./handleRunScript.mjs"
+// CONCATENATED MODULE: external "./handleSimpleCommands.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 };