bun-workspaces 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-workspaces",
-  "version": "1.0.0",
+  "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",

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

@@ -1,15 +1,19 @@
 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 interface GlobalCommandContext {
+export type GlobalCommandContext = {
   program: Command;
   postTerminatorArgs: string[];
-}
+  middleware: CliMiddleware;
+  outputWriters: Required<WriteOutputOptions>;
+};
 export type ProjectCommandContext = GlobalCommandContext & {
   project: FileSystemProject;
   projectError: Error | null;

package/src/cli/commands/commandHandlerUtils.mjs

@@ -47,8 +47,17 @@ const handleCommand = (commandName, handler) => (context) => {
   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);
@@ -64,6 +73,7 @@ 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);
     }

package/src/cli/commands/runScript/handleRunScript.mjs

@@ -28,7 +28,7 @@ import { renderPlainOutput } from "./output/renderPlainOutput.mjs"; // CONCATENA
 const runScript = handleProjectCommand(
   "runScript",
   async (
-    { project, postTerminatorArgs },
+    { project, postTerminatorArgs, outputWriters },
     positionalScript,
     positionalWorkspacePatterns,
     options,
@@ -146,14 +146,15 @@ const runScript = handleProjectCommand(
           summary,
           scriptEventTarget,
           groupedLines,
+          outputWriters,
         ),
       prefixed: () =>
-        renderPlainOutput(output, {
+        renderPlainOutput(output, outputWriters, {
           prefix: true,
           stripDisruptiveControls,
         }),
       plain: () =>
-        renderPlainOutput(output, {
+        renderPlainOutput(output, outputWriters, {
           prefix: false,
           stripDisruptiveControls,
         }),
@@ -241,8 +242,6 @@ const runScript = handleProjectCommand(
     }
     if (exitResults.failureCount) {
       process.exit(1);
-    } else {
-      process.exit(0);
     }
   },
 );

package/src/cli/commands/runScript/output/renderGroupedOutput.d.ts

@@ -12,6 +12,7 @@ import type {
   ScriptEventName,
 } from "../../../../runScript";
 import type { Workspace } from "../../../../workspaces";
+import type { WriteOutputOptions } from "../../../createCli";
 type ScriptEvent = TypedEvent<
   ScriptEventName,
   {
@@ -67,5 +68,6 @@ export declare const renderGroupedOutput: (
   summary: Promise<RunScriptsSummary<RunWorkspaceScriptMetadata>>,
   scriptEventTarget: ScriptEventTarget,
   activeScriptLines: number | "all",
+  outputWriters: Required<WriteOutputOptions>,
 ) => Promise<void>;
 export {};

package/src/cli/commands/runScript/output/renderGroupedOutput.mjs

@@ -70,6 +70,7 @@ const renderGroupedOutput = async (
   summary,
   scriptEventTarget,
   activeScriptLines,
+  outputWriters,
 ) => {
   const workspaceState = workspaces.reduce((acc, workspace) => {
     acc[workspace.name] = {
@@ -87,7 +88,7 @@ const renderGroupedOutput = async (
     }
     isInitialized = true;
     logger.debug("Initializing TUI state");
-    process.stdout.write(cursorOps.hide());
+    outputWriters.stdout(cursorOps.hide());
     process.stdin.setRawMode?.(true);
   };
   let isReset = false;
@@ -97,7 +98,7 @@ const renderGroupedOutput = async (
     }
     isReset = true;
     logger.debug("Resetting TUI state");
-    process.stdout.write(cursorOps.show());
+    outputWriters.stdout(cursorOps.show());
     process.stdin.unref();
     process.stdin.setRawMode?.(false);
   };
@@ -192,24 +193,24 @@ const renderGroupedOutput = async (
     });
     if (previousHeight > 0) {
       // clear previous frame
-      process.stdout.write(cursorOps.up(previousHeight));
+      outputWriters.stdout(cursorOps.up(previousHeight));
       for (let i = 0; i < previousHeight; i++) {
-        process.stdout.write(cursorOps.toColumn(1));
-        process.stdout.write(lineOps.clearFull());
-        process.stdout.write("\n");
+        outputWriters.stdout(cursorOps.toColumn(1));
+        outputWriters.stdout(lineOps.clearFull());
+        outputWriters.stdout("\n");
       }
-      process.stdout.write(cursorOps.up(previousHeight));
+      outputWriters.stdout(cursorOps.up(previousHeight));
     }
     for (const line of linesToWrite) {
       if (isFinal && line.type === "scriptOutput") {
-        process.stdout.write(line.text.replace(/\n?$/, "\n"));
+        outputWriters.stdout(line.text.replace(/\n?$/, "\n"));
       } else {
         const visibleLength = calculateVisibleLength(line.text);
         const truncated =
           visibleLength > width
             ? truncateTerminalString(line.text, width - 2) + "\x1b[0m…"
             : line.text;
-        process.stdout.write(truncated.replace(/\n?$/, "\n"));
+        outputWriters.stdout(truncated.replace(/\n?$/, "\n"));
       }
     }
     previousHeight = linesToWrite.length;
@@ -261,7 +262,7 @@ const renderGroupedOutput = async (
   runOnExit((reason) => {
     try {
       if (typeof reason === "string" && reason.startsWith("SIG")) {
-        process.stdout.write("\r" + lineOps.clearFull());
+        outputWriters.stdout("\r" + lineOps.clearFull());
       }
       Object.keys(workspaceState).forEach((workspaceName) => {
         handleExitResult({

package/src/cli/commands/runScript/output/renderPlainOutput.d.ts

@@ -1,4 +1,5 @@
 import type { RunScriptAcrossWorkspacesOutput } from "../../../../project";
+import type { WriteOutputOptions } from "../../../createCli";
 export type RenderPlainOutputOptions = {
   stripDisruptiveControls?: boolean;
   prefix?: boolean;
@@ -18,5 +19,6 @@ export declare function generatePlainOutputLines(
 >;
 export declare const renderPlainOutput: (
   output: RunScriptAcrossWorkspacesOutput,
+  outputWriters: Required<WriteOutputOptions>,
   { stripDisruptiveControls, prefix }: RenderPlainOutputOptions,
 ) => Promise<void>;

package/src/cli/commands/runScript/output/renderPlainOutput.mjs

@@ -30,13 +30,14 @@ async function* generatePlainOutputLines(
 }
 const renderPlainOutput = async (
   output,
+  outputWriters,
   { stripDisruptiveControls = true, prefix = false },
 ) => {
   for await (const { line, metadata } of generatePlainOutputLines(output, {
     stripDisruptiveControls,
     prefix,
   })) {
-    process[metadata.streamName].write(line + "\n");
+    outputWriters[metadata.streamName](line + "\n");
   }
 };
 

package/src/cli/createCli.d.ts

@@ -1,19 +1,25 @@
-import { type Command } from "commander";
+import { type CliMiddlewareOptions } from "./middleware";
+export interface WriteOutputOptions {
+  stdout?: (...args: Parameters<typeof process.stdout.write>) => void;
+  stderr?: (...args: Parameters<typeof process.stderr.write>) => void;
+}
 export interface RunCliOptions {
-  argv?: string | string[];
+  argv?: string[];
   /** Should be `true` if args do not include the binary name (e.g. `bunx bun-workspaces`) */
   programmatic?: true;
+  middleware?: CliMiddlewareOptions;
+  writeOutput?: WriteOutputOptions;
+  terminalWidth?: number;
 }
 export interface CLI {
   run: (options?: RunCliOptions) => Promise<void>;
 }
 export interface CreateCliOptions {
-  handleError?: (error: Error) => void;
-  postInit?: (program: Command) => unknown;
   defaultCwd?: string;
+  /** Always handled when the result `.run()` is called */
+  defaultMiddleware?: CliMiddlewareOptions;
 }
 export declare const createCli: ({
-  handleError,
-  postInit,
   defaultCwd,
+  defaultMiddleware,
 }?: CreateCliOptions) => CLI;

package/src/cli/createCli.mjs

@@ -7,49 +7,84 @@ import {
   defineGlobalCommands,
   defineProjectCommands,
 } from "./commands/index.mjs";
+import { commandOutputLogger } from "./commands/commandHandlerUtils.mjs";
 import { fatalErrorLogger } from "./fatalErrorLogger.mjs";
-import { initializeWithGlobalOptions } from "./globalOptions/index.mjs"; // CONCATENATED MODULE: external "commander"
+import { initializeWithGlobalOptions } from "./globalOptions/index.mjs";
+import { resolveMiddleware } from "./middleware.mjs"; // CONCATENATED MODULE: external "commander"
 // CONCATENATED MODULE: external "../../package.json"
 // CONCATENATED MODULE: external "../internal/bun/index.mjs"
 // CONCATENATED MODULE: external "../internal/core/index.mjs"
 // CONCATENATED MODULE: external "../internal/logger/index.mjs"
 // CONCATENATED MODULE: external "./commands/index.mjs"
+// CONCATENATED MODULE: external "./commands/commandHandlerUtils.mjs"
 // CONCATENATED MODULE: external "./fatalErrorLogger.mjs"
 // CONCATENATED MODULE: external "./globalOptions/index.mjs"
+// CONCATENATED MODULE: external "./middleware.mjs"
 // CONCATENATED MODULE: ./src/cli/createCli.ts
 
-const createCli = ({
-  handleError,
-  postInit,
-  defaultCwd = process.cwd(),
-} = {}) => {
+const createCli = ({ defaultCwd = process.cwd(), defaultMiddleware } = {}) => {
   logger.debug(`Creating CLI with default cwd: ${defaultCwd}`);
-  const run = async ({ argv = process.argv, programmatic } = {}) => {
-    const errorListener =
-      handleError ??
-      ((error) => {
-        fatalErrorLogger.error(error);
-        process.exit(1);
-      });
+  const run = async ({
+    argv = process.argv,
+    programmatic,
+    middleware: _runMiddleware,
+    writeOutput,
+    terminalWidth,
+  } = {}) => {
+    const middleware = resolveMiddleware(
+      defaultMiddleware ?? {},
+      _runMiddleware ?? {},
+    );
+    const outputWriters = {
+      stdout: (...args) => process.stdout.write(...args),
+      stderr: (...args) => process.stderr.write(...args),
+      ...writeOutput,
+    };
+    logger.setPrintStdout(outputWriters.stdout);
+    logger.setPrintStderr(outputWriters.stderr);
+    commandOutputLogger.setPrintStdout(outputWriters.stdout);
+    commandOutputLogger.setPrintStderr(outputWriters.stderr);
+    const errorListener = (error) => {
+      middleware.catchError(error);
+      fatalErrorLogger.error(error);
+      process.exit(1);
+    };
     process.on("unhandledRejection", errorListener);
     try {
       const program = createCommand("bun-workspaces")
         .description("A CLI on top of native Bun workspaces")
         .version(package_0.version)
-        .showHelpAfterError(true);
-      postInit?.(program);
-      const rawArgs = typeof argv === "string" ? argv.split(/s+/) : argv;
+        .showHelpAfterError(true)
+        .configureOutput({
+          writeOut: outputWriters.stdout,
+          writeErr: outputWriters.stderr,
+          ...(terminalWidth
+            ? {
+                getOutHelpWidth: () => terminalWidth,
+                getErrHelpWidth: () => terminalWidth,
+              }
+            : {}),
+        });
+      const defaultContext = {
+        commanderProgram: program,
+      };
+      middleware.initProgram({
+        ...defaultContext,
+        argv,
+      });
       const { args, postTerminatorArgs } = (() => {
-        const terminatorIndex = rawArgs.findIndex((arg) => arg === "--");
+        const terminatorIndex = argv.findIndex((arg) => arg === "--");
         return {
-          args:
-            terminatorIndex !== -1
-              ? rawArgs.slice(0, terminatorIndex)
-              : rawArgs,
+          args: terminatorIndex !== -1 ? argv.slice(0, terminatorIndex) : argv,
           postTerminatorArgs:
-            terminatorIndex !== -1 ? rawArgs.slice(terminatorIndex + 1) : [],
+            terminatorIndex !== -1 ? argv.slice(terminatorIndex + 1) : [],
         };
       })();
+      middleware.processArgv({
+        ...defaultContext,
+        args,
+        postTerminatorArgs,
+      });
       const bunVersionError = validateCurrentBunVersion();
       if (bunVersionError) {
         fatalErrorLogger.error(bunVersionError.message);
@@ -60,6 +95,11 @@ const createCli = ({
         args,
         defaultCwd,
       );
+      middleware.findProject({
+        ...defaultContext,
+        project,
+        projectError,
+      });
       if (postTerminatorArgs.length) {
         logger.debug("Has post-terminator args");
       }
@@ -69,15 +109,31 @@ const createCli = ({
         project,
         projectError,
         postTerminatorArgs,
+        middleware,
+        outputWriters,
       });
       defineGlobalCommands({
         program,
         postTerminatorArgs,
+        middleware,
+        outputWriters,
       });
       logger.debug(`Commands initialized. Parsing args...`);
+      middleware.preParse({
+        ...defaultContext,
+        args,
+        project,
+        projectError,
+      });
       await program.parseAsync(args, {
         from: programmatic ? "user" : "node",
       });
+      middleware.postParse({
+        ...defaultContext,
+        args,
+        project,
+        projectError,
+      });
     } catch (error) {
       if (error instanceof BunWorkspacesError) {
         logger.debug(error);

package/src/cli/middleware.d.ts

@@ -0,0 +1,72 @@
+import type { Command as CommanderProgram } from "commander";
+import type { FileSystemProject } from "../project";
+import type { CliCommandName, CliGlobalCommandName } from "./commands";
+import type {
+  GlobalCommandContext,
+  ProjectCommandContext,
+} from "./commands/commandHandlerUtils";
+export type InitProgramContext = {
+  commanderProgram: CommanderProgram;
+  argv: string[];
+};
+export type ProcessArgvContext = {
+  args: string[];
+  postTerminatorArgs: string[];
+};
+export type FindProjectContext = {
+  commanderProgram: CommanderProgram;
+  project: FileSystemProject;
+  projectError: Error | null;
+};
+export type PreParseContext = {
+  commanderProgram: CommanderProgram;
+  args: string[];
+  project: FileSystemProject;
+  projectError: Error | null;
+};
+export type PostParseContext = {
+  commanderProgram: CommanderProgram;
+  args: string[];
+  project: FileSystemProject;
+  projectError: Error | null;
+};
+export type CommandMiddlewareContext<C extends CliCommandName> = {
+  commanderProgram: CommanderProgram;
+  commandName: C;
+  commandContext: C extends CliGlobalCommandName
+    ? GlobalCommandContext
+    : ProjectCommandContext;
+  commanderActionArgs: unknown[];
+};
+export type CommandMiddleware = <C extends CliCommandName>(
+  context: CommandMiddlewareContext<C>,
+) => CommanderProgram;
+export type PostCleanupContext = {
+  commanderProgram: CommanderProgram;
+  args: string[];
+  project: FileSystemProject;
+  projectError: Error | null;
+};
+export type CliMiddleware = {
+  /** The first callback when the Commander program is created */
+  initProgram: (context: InitProgramContext) => CommanderProgram;
+  /** Before the true parsing, just splitting the argv into args and post-terminator args */
+  processArgv: (context: ProcessArgvContext) => CommanderProgram;
+  /** After the project has been initialized from global options */
+  findProject: (context: FindProjectContext) => CommanderProgram;
+  /** Before the Commander program parses the args */
+  preParse: (context: PreParseContext) => CommanderProgram;
+  /** After the Commander program has parsed the args (runs in finally block) */
+  postParse: (context: PostParseContext) => CommanderProgram;
+  /** Before a command is handled */
+  preHandleCommand: CommandMiddleware;
+  /** After a command is handled */
+  postHandleCommand: CommandMiddleware;
+  /** After the program has been parsed */
+  catchError: (error: Error) => unknown;
+};
+export type CliMiddlewareOptions = Partial<CliMiddleware>;
+export declare const resolveMiddleware: (
+  defaultMiddleware: CliMiddlewareOptions,
+  runMiddleware: CliMiddlewareOptions,
+) => CliMiddleware;

package/src/cli/middleware.mjs

@@ -0,0 +1,38 @@
+import { defineErrors } from "../internal/core/index.mjs";
+import { logger } from "../internal/logger/index.mjs"; // CONCATENATED MODULE: external "../internal/core/index.mjs"
+// CONCATENATED MODULE: external "../internal/logger/index.mjs"
+// CONCATENATED MODULE: ./src/cli/middleware.ts
+
+const MIDDLEWARE_ERRORS = defineErrors("MiddlewareHandlerFailed");
+const resolveMiddleware = (defaultMiddleware, runMiddleware) =>
+  Object.keys({
+    catchError: null,
+    initProgram: null,
+    processArgv: null,
+    findProject: null,
+    preParse: null,
+    postParse: null,
+    preHandleCommand: null,
+    postHandleCommand: null,
+  }).reduce((acc, _key) => {
+    const key = _key;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    acc[key] = (ctx) => {
+      try {
+        let result = defaultMiddleware?.[key]?.(ctx);
+        result = runMiddleware?.[key]?.(ctx);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return result;
+      } catch (error) {
+        logger.error(
+          new MIDDLEWARE_ERRORS.MiddlewareHandlerFailed(
+            `Error in middleware handler "${key}"`,
+          ),
+        );
+        throw error;
+      }
+    };
+    return acc;
+  }, {});
+
+export { resolveMiddleware };

package/src/internal/logger/logger.d.ts

@@ -24,6 +24,12 @@ export type Logger = {
     metadata?: Metadata,
   ): Log<Message, Metadata>;
   printLevel: LogLevelSetting;
+  setPrintStdout: (
+    stdout: (...args: Parameters<typeof process.stdout.write>) => void,
+  ) => void;
+  setPrintStderr: (
+    stderr: (...args: Parameters<typeof process.stderr.write>) => void,
+  ) => void;
 } & {
   [Level in LogLevel]: <
     Message extends string | Error = string,

package/src/internal/logger/logger.mjs

@@ -17,6 +17,13 @@ const validateLogLevel = (level) => {
 const createLogger = (name) => new _Logger(name);
 const YELLOW = "\x1b[0;33m";
 const NC = "\x1b[0m";
+const RED = "\x1b[0;31m";
+const LEVEL_OUTPUT_TARGETS = {
+  debug: "stderr",
+  info: "stdout",
+  warn: "stderr",
+  error: "stderr",
+};
 class _Logger {
   name;
   constructor(name) {
@@ -42,27 +49,25 @@ class _Logger {
             },
           ]
         : [];
-      if (level === "debug") {
-        // debug goes to stderr (console.debug goes to stdout which messes with machine-readable output etc.)
-        process.stderr.write(
-          (typeof mainMessage === "string"
-            ? mainMessage
-            : Bun.inspect(mainMessage, {
+      this[
+        LEVEL_OUTPUT_TARGETS[level] === "stderr"
+          ? "_printStderr"
+          : "_printStdout"
+      ](
+        (typeof mainMessage === "string"
+          ? mainMessage
+          : Bun.inspect(mainMessage, {
+              colors: true,
+            })) +
+          metadataMessages
+            .map((m) =>
+              Bun.inspect(m, {
                 colors: true,
-              })) +
-            metadataMessages
-              .map((m) =>
-                Bun.inspect(m, {
-                  colors: true,
-                }),
-              )
-              .join("\n") +
-            "\n",
-        );
-      } else {
-        // eslint-disable-next-line no-console
-        console[level](mainMessage, ...metadataMessages);
-      }
+              }),
+            )
+            .join("\n") +
+          "\n",
+      );
     }
     return log;
   }
@@ -92,13 +97,25 @@ class _Logger {
       level === "debug" || level === "warn"
         ? `[${this.name} ${level.toUpperCase()}]: ${content}`
         : content;
-    return level === "warn" ? `${YELLOW}${prefixed}${NC}` : prefixed;
+    return level === "warn"
+      ? `${YELLOW}${prefixed}${NC}`
+      : level === "error"
+        ? `${RED}${prefixed}${NC}`
+        : prefixed;
   }
   _printLevel = IS_TEST ? "error" : "info";
   shouldPrint(level) {
     if (this.printLevel === "silent") return false;
     return getLevelNumber(level) >= getLevelNumber(this.printLevel);
   }
+  _printStdout = (...args) => process.stdout.write(...args);
+  _printStderr = (...args) => process.stderr.write(...args);
+  setPrintStdout(stdout) {
+    this._printStdout = stdout;
+  }
+  setPrintStderr(stderr) {
+    this._printStderr = stderr;
+  }
 }
 const logger = createLogger("bun-workspaces");
 /** Set the global logging level. Defaults to "info" or "error" when `NODE_ENV` is "test" */ const setLogLevel =