bun-workspaces 1.1.0 → 1.1.2

package/README.md

@@ -65,9 +65,6 @@ 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
@@ -75,6 +72,9 @@ bw run lint --dep-order
 # Continue running scripts even if a dependency fails
 bw run lint --dep-order --ignore-dep-failure
 
+bw run lint "my-workspace-*" # Run for matching workspace names
+bw run lint "alias:my-alias-pattern-*" "path:my-glob/**/*" # Use matching specifiers
+
 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
 
@@ -90,7 +90,7 @@ bw run lint --parallel=50% # Run in parallel with a max of 50% of the "auto" lim
 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=auto
 bw run my-script --output-style=grouped --grouped-lines=10
 
 # Use simple script output with workspace prefixes (default when not on a TTY)
@@ -140,14 +140,22 @@ 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
+
+    // Optional. Arguments to add to the command
+    // Can be a string or an array of strings
+    // If string, the argv will be parsed POSIX-style
+    args: ["--my", "--appended", "--args"],
+
+    // Optional. Whether to ignore all output from the script.
+    // This saves memory when you don't need script output.
+    ignoreOutput: false,
   });
 
   // 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
+    // console.log(chunk); // The output chunk's content (string)
+    // console.log(metadata.streamName); // The output stream, "stdout" or "stderr"
+    // console.log(metadata.workspace); // The target Workspace
   }
 
   // Get data about the script execution after it exits
@@ -173,8 +181,8 @@ const runManyScripts = async () => {
     // Required. The package.json "scripts" field name to run
     script: "my-script",
 
-    // Optional. Arguments to add to the command
-    args: "--my --appended --args",
+    // Optional. Arguments to add to the command (same as for runWorkspaceScript)
+    args: ["--my", "--appended", "--args"],
 
     // Optional. Whether to run the scripts in parallel (default: true)
     parallel: true,
@@ -187,6 +195,10 @@ const runManyScripts = async () => {
     // continue running scripts even if a dependency fails
     ignoreDependencyFailure: false,
 
+    // Optional. Whether to ignore all output from the scripts.
+    // This saves memory when you don't need script output.
+    ignoreOutput: false,
+
     // Optional, callback when script starts, skips, or exits
     onScriptEvent: (event, { workspace, exitResult }) => {
       // event: "start", "skip", "exit"
@@ -195,9 +207,9 @@ const runManyScripts = async () => {
 
   // Get a stream of script output
   for await (const { chunk, metadata } of output.text()) {
-    // console.log(chunk); // the content (string)
+    // console.log(chunk); // the output chunk's content (string)
     // console.log(metadata.streamName); // "stdout" or "stderr"
-    // console.log(metadata.workspace); // the workspace that the output came from
+    // console.log(metadata.workspace); // the Workspace that the output came from
   }
 
   // Get final summary data and script exit details after all scripts have completed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-workspaces",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "A monorepo management tool for Bun, with a CLI and API to enhance Bun's native workspaces.",
   "license": "MIT",
   "main": "src/index.mjs",
@@ -32,6 +32,7 @@
     }
   },
   "dependencies": {
-    "commander": "^12.1.0"
+    "commander": "^12.1.0",
+    "shell-quote": "^1.8.3"
   }
 }

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

@@ -14,6 +14,7 @@ export type GlobalCommandContext = {
   middleware: CliMiddleware;
   outputWriters: Required<WriteOutputOptions>;
   terminalWidth: number;
+  terminalHeight: number;
 };
 export type ProjectCommandContext = GlobalCommandContext & {
   project: FileSystemProject;

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

@@ -26,7 +26,6 @@ export type CliProjectCommandName = Exclude<
   CliGlobalCommandName
 >;
 export declare const JSON_FLAGS: readonly ["-j", "--json"];
-export declare const DEFAULT_GROUPED_LINES = 20;
 export declare const CLI_COMMANDS_CONFIG: {
   readonly doctor: {
     readonly command: "doctor";
@@ -153,7 +152,7 @@ export declare const CLI_COMMANDS_CONFIG: {
       };
       readonly groupedLines: {
         readonly flags: ["-L", "--grouped-lines <count>"];
-        readonly description: 'With "grouped" output, the max preview lines (number or "all", default 20)';
+        readonly description: 'With grouped output, the max preview lines (number or "auto", default "auto")';
       };
       readonly noPrefix: {
         readonly flags: ["-N", "--no-prefix"];
@@ -314,7 +313,7 @@ export declare const getCliCommandConfig: (commandName: CliCommandName) =>
         };
         readonly groupedLines: {
           readonly flags: ["-L", "--grouped-lines <count>"];
-          readonly description: 'With "grouped" output, the max preview lines (number or "all", default 20)';
+          readonly description: 'With grouped output, the max preview lines (number or "auto", default "auto")';
         };
         readonly noPrefix: {
           readonly flags: ["-N", "--no-prefix"];

package/src/cli/commands/commandsConfig.mjs

@@ -4,7 +4,6 @@ import { OUTPUT_STYLE_VALUES } from "./runScript/output/outputStyle.mjs"; // CON
 // CONCATENATED MODULE: ./src/cli/commands/commandsConfig.ts
 
 const JSON_FLAGS = ["-j", "--json"];
-const DEFAULT_GROUPED_LINES = 20;
 const CLI_COMMANDS_CONFIG = {
   doctor: {
     command: "doctor",
@@ -133,7 +132,7 @@ const CLI_COMMANDS_CONFIG = {
       },
       groupedLines: {
         flags: ["-L", "--grouped-lines <count>"],
-        description: `With "grouped" output, the max preview lines (number or "all", default ${DEFAULT_GROUPED_LINES})`,
+        description: `With grouped output, the max preview lines (number or "auto", default "auto")`,
       },
       noPrefix: {
         flags: ["-N", "--no-prefix"],
@@ -176,7 +175,6 @@ const getCliCommandNames = () => Object.keys(CLI_COMMANDS_CONFIG);
 
 export {
   CLI_COMMANDS_CONFIG,
-  DEFAULT_GROUPED_LINES,
   JSON_FLAGS,
   getCliCommandConfig,
   getCliCommandNames,

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

@@ -1,11 +1,11 @@
 import fs from "fs";
 import path from "path";
+import { expandHomePath } from "../../../internal/core/index.mjs";
 import { logger } from "../../../internal/logger/index.mjs";
 import {
   handleProjectCommand,
   splitWorkspacePatterns,
 } from "../commandHandlerUtils.mjs";
-import { DEFAULT_GROUPED_LINES } from "../commandsConfig.mjs";
 import {
   getDefaultOutputStyle,
   validateOutputStyle,
@@ -17,9 +17,9 @@ import {
 } from "./output/renderGroupedOutput.mjs";
 import { renderPlainOutput } from "./output/renderPlainOutput.mjs"; // CONCATENATED MODULE: external "fs"
 // CONCATENATED MODULE: external "path"
+// CONCATENATED MODULE: external "../../../internal/core/index.mjs"
 // CONCATENATED MODULE: external "../../../internal/logger/index.mjs"
 // CONCATENATED MODULE: external "../commandHandlerUtils.mjs"
-// CONCATENATED MODULE: external "../commandsConfig.mjs"
 // CONCATENATED MODULE: external "./output/outputStyle.mjs"
 // CONCATENATED MODULE: external "./output/renderGroupedOutput.mjs"
 // CONCATENATED MODULE: external "./output/renderPlainOutput.mjs"
@@ -28,7 +28,13 @@ import { renderPlainOutput } from "./output/renderPlainOutput.mjs"; // CONCATENA
 const runScript = handleProjectCommand(
   "runScript",
   async (
-    { project, postTerminatorArgs, outputWriters, terminalWidth },
+    {
+      project,
+      postTerminatorArgs,
+      outputWriters,
+      terminalWidth,
+      terminalHeight,
+    },
     positionalScript,
     positionalWorkspacePatterns,
     options,
@@ -52,7 +58,7 @@ const runScript = handleProjectCommand(
       process.exit(1);
     }
     const scriptArgs = postTerminatorArgs.length
-      ? postTerminatorArgs.join(" ")
+      ? postTerminatorArgs
       : options.args;
     if (positionalWorkspacePatterns.length && options.workspacePatterns) {
       logger.error(
@@ -114,10 +120,12 @@ const runScript = handleProjectCommand(
     logger.debug(`Script name: ${scriptName}`);
     const stripDisruptiveControls = workspaces.length > 1 || !!options.parallel;
     logger.debug(`Strip disruptive controls: ${stripDisruptiveControls}`);
-    let groupedLines = DEFAULT_GROUPED_LINES;
+    let groupedLines = "auto";
     if (options.groupedLines) {
       if (options.groupedLines === "all") {
         groupedLines = "all";
+      } else if (options.groupedLines === "auto") {
+        groupedLines = "auto";
       } else {
         const parsedGroupedLines = parseInt(options.groupedLines);
         if (parsedGroupedLines <= 0 || isNaN(parsedGroupedLines)) {
@@ -148,6 +156,7 @@ const runScript = handleProjectCommand(
           groupedLines,
           outputWriters,
           terminalWidth,
+          terminalHeight,
         ),
       prefixed: () =>
         renderPlainOutput(output, outputWriters, {
@@ -196,7 +205,7 @@ const runScript = handleProjectCommand(
     if (options.jsonOutfile) {
       const fullOutputPath = path.resolve(
         project.rootDirectory,
-        options.jsonOutfile,
+        expandHomePath(options.jsonOutfile),
       );
       // Check if can make directory
       const jsonOutputDir = path.dirname(fullOutputPath);

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

@@ -67,8 +67,9 @@ export declare const renderGroupedOutput: (
   output: RunScriptAcrossWorkspacesOutput,
   summary: Promise<RunScriptsSummary<RunWorkspaceScriptMetadata>>,
   scriptEventTarget: ScriptEventTarget,
-  activeScriptLines: number | "all",
+  activeScriptLines: number | "all" | "auto",
   outputWriters: Required<WriteOutputOptions>,
   terminalWidth: number,
+  terminalHeight: number,
 ) => Promise<void>;
 export {};

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

@@ -55,7 +55,7 @@ const textOps = {
 };
 const STATUS_COLORS = {
   pending: "gray",
-  running: "intenseCyan",
+  running: "intenseMagenta",
   skipped: "gray",
   success: "intenseGreen",
   failure: "intenseRed",
@@ -63,7 +63,8 @@ const STATUS_COLORS = {
   cancelled: "gray",
   killed: "intenseRed",
 };
-const BORDER_COLOR = "blue";
+const BORDER_COLOR = "intenseCyan";
+const HEADER_ROWS_PER_WORKSPACE = 2;
 const renderGroupedOutput = async (
   workspaces,
   output,
@@ -72,6 +73,7 @@ const renderGroupedOutput = async (
   activeScriptLines,
   outputWriters,
   terminalWidth,
+  terminalHeight,
 ) => {
   const workspaceState = workspaces.reduce((acc, workspace) => {
     acc[workspace.name] = {
@@ -112,7 +114,26 @@ const renderGroupedOutput = async (
     if (isFinal) {
       didFinalRender = true;
     }
-    const width = Math.max(2, terminalWidth || process.stdout.columns);
+    const width = Math.max(2, terminalWidth || process.stdout.columns || 2);
+    const height = Math.max(1, terminalHeight || process.stdout.rows || 1);
+    // Compute the max script lines to show per workspace based on terminal
+    // height, so the live TUI never exceeds the visible viewport (cursor up
+    // is clamped and cannot recover from overflow). Each workspace occupies
+    // HEADER_ROWS_PER_WORKSPACE rows plus one row for the hidden-lines
+    // indicator, with one additional safety row to prevent scroll on the
+    // final newline. The user's activeScriptLines acts as a ceiling if lower.
+    const availableRows = Math.max(
+      1,
+      height - 1 - workspaces.length * (HEADER_ROWS_PER_WORKSPACE + 1),
+    );
+    const computedScriptLines = Math.max(
+      1,
+      Math.floor(availableRows / workspaces.length),
+    );
+    const effectiveScriptLines =
+      activeScriptLines === "all" || activeScriptLines === "auto"
+        ? computedScriptLines
+        : Math.min(activeScriptLines, computedScriptLines);
     const linesToWrite = [];
     const workspaceBoxContents = {};
     workspaces.forEach((workspace) => {
@@ -134,69 +155,51 @@ const renderGroupedOutput = async (
       } else if (exitState === "signal") {
         statusText += ` (signal: ${state.signal})`;
       }
-      const workspaceLine = "Workspace: " + textOps.bold(workspace.name);
+      const workspaceLine =
+        textOps[BORDER_COLOR]("Workspace: ") + textOps.bold(workspace.name);
       const statusLine =
-        "   Status: " + textOps[STATUS_COLORS[state.status]](statusText);
+        textOps[BORDER_COLOR]("   Status: ") +
+        textOps[STATUS_COLORS[state.status]](statusText);
       workspaceBoxContents[workspace.name] = {
         name: workspaceLine,
         status: statusLine,
       };
     });
     const padding = 4; // left border, spaces, right border
-    const workspaceBoxWidth = Math.min(
-      width,
-      Math.max(
-        ...Object.values(workspaceBoxContents).map((content) =>
-          Math.max(
-            calculateVisibleLength(content.name),
-            calculateVisibleLength(content.status),
-          ),
-        ),
-      ) + padding,
-    );
     workspaces.forEach((workspace) => {
       const state = workspaceState[workspace.name];
       const { name: workspaceNameContent, status: statusTextContent } =
         workspaceBoxContents[workspace.name];
-      linesToWrite.push({
-        text: textOps[BORDER_COLOR](
-          "┌" + "─".repeat(workspaceBoxWidth - 2) + "┐",
-        ),
-        type: "border",
-      });
-      const borderText = (text) => {
+      const borderText = (text, top, headerWidth) => {
         const visibleLength = calculateVisibleLength(text);
         const truncated =
           visibleLength > width - padding
             ? truncateTerminalString(text, width - padding - 1) + "\x1b[0m…"
             : text;
         return (
-          textOps[BORDER_COLOR]("│ ") +
+          textOps[BORDER_COLOR](top ? "┌ " : "└ ") +
           truncated +
-          " ".repeat(Math.max(0, workspaceBoxWidth - visibleLength - padding)) +
-          textOps[BORDER_COLOR](" │")
+          " ".repeat(Math.max(0, headerWidth - visibleLength - padding)) +
+          textOps[BORDER_COLOR](top ? " ┐" : " ┘")
         );
       };
+      const headerWidth = Math.min(
+        width,
+        Math.max(
+          Bun.stripANSI(workspaceNameContent).length,
+          Bun.stripANSI(statusTextContent).length,
+        ) + padding,
+      );
       linesToWrite.push({
-        text: borderText(workspaceNameContent),
+        text: borderText(workspaceNameContent, true, headerWidth),
         type: "borderedContent",
       });
       linesToWrite.push({
-        text: borderText(statusTextContent),
+        text: borderText(statusTextContent, false, headerWidth),
         type: "borderedContent",
       });
-      linesToWrite.push({
-        text: textOps[BORDER_COLOR](
-          "└" + "─".repeat(workspaceBoxWidth - 2) + "┘",
-        ),
-        type: "border",
-      });
-      if (
-        activeScriptLines !== "all" &&
-        state.lines.length > activeScriptLines &&
-        !isFinal
-      ) {
-        const hiddenLines = state.lines.length - activeScriptLines;
+      if (state.lines.length > effectiveScriptLines && !isFinal) {
+        const hiddenLines = state.lines.length - effectiveScriptLines;
         linesToWrite.push({
           text: textOps.gray(
             `(${hiddenLines} line${hiddenLines === 1 ? "" : "s"} hidden until exit)`,
@@ -206,7 +209,7 @@ const renderGroupedOutput = async (
       }
       linesToWrite.push(
         ...state.lines
-          .slice(isFinal ? undefined : -activeScriptLines)
+          .slice(isFinal ? undefined : -effectiveScriptLines)
           .map((line) => ({
             text: line.text,
             type: "scriptOutput",
@@ -214,6 +217,12 @@ const renderGroupedOutput = async (
       );
       return linesToWrite;
     });
+    if (isFinal) {
+      linesToWrite.push({
+        text: textOps[BORDER_COLOR]("─ Summary ─"),
+        type: "borderedContent",
+      });
+    }
     if (previousHeight > 0) {
       // clear previous frame
       outputWriters.stdout(cursorOps.up(previousHeight));

package/src/cli/createCli.d.ts

@@ -10,6 +10,7 @@ export interface RunCliOptions {
   middleware?: CliMiddlewareOptions;
   writeOutput?: WriteOutputOptions;
   terminalWidth?: number;
+  terminalHeight?: number;
 }
 export interface CLI {
   run: (options?: RunCliOptions) => Promise<void>;

package/src/cli/createCli.mjs

@@ -30,6 +30,7 @@ const createCli = ({ defaultCwd = process.cwd(), defaultMiddleware } = {}) => {
     middleware: _runMiddleware,
     writeOutput,
     terminalWidth = process.stdout.columns,
+    terminalHeight = process.stdout.rows,
   } = {}) => {
     const middleware = resolveMiddleware(
       defaultMiddleware ?? {},
@@ -112,6 +113,7 @@ const createCli = ({ defaultCwd = process.cwd(), defaultMiddleware } = {}) => {
         middleware,
         outputWriters,
         terminalWidth,
+        terminalHeight,
       });
       defineGlobalCommands({
         program,
@@ -119,6 +121,7 @@ const createCli = ({ defaultCwd = process.cwd(), defaultMiddleware } = {}) => {
         middleware,
         outputWriters,
         terminalWidth,
+        terminalHeight,
       });
       logger.debug(`Commands initialized. Parsing args...`);
       middleware.preParse({

package/src/cli/globalOptions/globalOptions.mjs

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { Option } from "commander";
-import { defineErrors } from "../../internal/core/index.mjs";
+import { defineErrors, expandHomePath } from "../../internal/core/index.mjs";
 import { logger } from "../../internal/logger/index.mjs";
 import {
   createFileSystemProject,
@@ -90,8 +90,9 @@ const defineGlobalOptions = (program, args, middleware) => {
     program,
     args,
   );
-  const cwd =
-    cwdOption || (workspaceRootOption ? findRootFromCwd() : process.cwd());
+  const cwd = expandHomePath(
+    cwdOption || (workspaceRootOption ? findRootFromCwd() : process.cwd()),
+  );
   const exists = fs.existsSync(cwd);
   const isDirectory = exists ? fs.statSync(cwd).isDirectory() : false;
   middleware.processWorkingDirectory({

package/src/internal/core/runtime/os.d.ts

@@ -2,3 +2,5 @@ export declare const IS_WINDOWS: boolean;
 export declare const IS_MACOS: boolean;
 export declare const IS_LINUX: boolean;
 export declare const IS_POSIX: boolean;
+/** Expands a leading `~` or `~/` to the user's home directory */
+export declare const expandHomePath: (filePath: string) => string;

package/src/internal/core/runtime/os.mjs

@@ -1,7 +1,19 @@
+import os from "os";
+import path from "path"; // CONCATENATED MODULE: external "os"
+// CONCATENATED MODULE: external "path"
 // CONCATENATED MODULE: ./src/internal/core/runtime/os.ts
+
 const IS_WINDOWS = process.platform === "win32";
 const IS_MACOS = process.platform === "darwin";
 const IS_LINUX = process.platform === "linux";
 const IS_POSIX = IS_MACOS || IS_LINUX;
+/** Expands a leading `~` or `~/` to the user's home directory */ const expandHomePath =
+  (filePath) => {
+    if (filePath === "~") return os.homedir();
+    if (filePath.startsWith("~/") || filePath.startsWith("~\\")) {
+      return path.join(os.homedir(), filePath.slice(2));
+    }
+    return filePath;
+  };
 
-export { IS_LINUX, IS_MACOS, IS_POSIX, IS_WINDOWS };
+export { IS_LINUX, IS_MACOS, IS_POSIX, IS_WINDOWS, expandHomePath };

package/src/project/implementations/fileSystemProject.d.ts

@@ -39,8 +39,8 @@ export type RunWorkspaceScriptOptions = {
   script: string;
   /** Whether to run the script as an inline command */
   inline?: boolean | InlineScriptOptions;
-  /** The arguments to append to the script command */
-  args?: string;
+  /** The arguments to append to the script command. If passed as a string, the argv will be parsed POSIX-style */
+  args?: string | string[];
   /** Set to `true` to ignore all output from the script. This saves memory when you don't need script output. */
   ignoreOutput?: boolean;
 };
@@ -89,8 +89,8 @@ export type RunScriptAcrossWorkspacesOptions = {
   script: string;
   /** Whether to run the script as an inline command */
   inline?: boolean | InlineScriptOptions;
-  /** The arguments to append to the script command. `<workspaceName>` will be replaced with the workspace name */
-  args?: string;
+  /** The arguments to append to the script command. If passed as a string, the argv will be parsed POSIX-style */
+  args?: string | string[];
   /** Whether to run the scripts in parallel (default: `true`). Pass `false` to run in series. */
   parallel?: ParallelOption;
   /** When `true`, run scripts so that dependent workspaces run only after their dependencies */

package/src/project/implementations/fileSystemProject.mjs

@@ -1,10 +1,15 @@
 import fs from "fs";
 import path from "path";
+import { parse, quote } from "shell-quote/";
 import { loadRootConfig } from "../../config/index.mjs";
 import { getUserEnvVar } from "../../config/userEnvVars/index.mjs";
 import {
   DEFAULT_TEMP_DIR,
+  IS_WINDOWS,
+  InvalidJSTypeError,
+  expandHomePath,
   isPlainObject,
+  validateJSArray,
   validateJSTypes,
 } from "../../internal/core/index.mjs";
 import { logger } from "../../internal/logger/index.mjs";
@@ -26,6 +31,7 @@ import {
   resolveWorkspacePath,
 } from "./projectBase.mjs"; // CONCATENATED MODULE: external "fs"
 // CONCATENATED MODULE: external "path"
+// CONCATENATED MODULE: external "shell-quote/"
 // CONCATENATED MODULE: external "../../config/index.mjs"
 // CONCATENATED MODULE: external "../../config/userEnvVars/index.mjs"
 // CONCATENATED MODULE: external "../../internal/core/index.mjs"
@@ -39,6 +45,41 @@ import {
 // CONCATENATED MODULE: external "./projectBase.mjs"
 // CONCATENATED MODULE: ./src/project/implementations/fileSystemProject.ts
 
+const quoteArg = (arg, shell) =>
+  IS_WINDOWS && shell === "system"
+    ? `"${arg.replace(/"/g, '""')}"`
+    : quote([arg]);
+const serializeArgs = (args, metadata, shell) => {
+  if (!args || args.length === 0) return "";
+  if (Array.isArray(args)) {
+    return args
+      .map((arg) =>
+        quoteArg(interpolateScriptRuntimeMetadata(arg, metadata, shell), shell),
+      )
+      .join(" ");
+  }
+  const interpolated = interpolateScriptRuntimeMetadata(args, metadata, shell);
+  // Escape backslashes in interpolated values before POSIX parse on Windows,
+  // so that path separators survive parse's escape processing (\\→\)
+  const parseInput =
+    IS_WINDOWS && shell === "system"
+      ? interpolated.replace(/\\/g, "\\\\")
+      : interpolated;
+  return parse(parseInput)
+    .flatMap((entry) => {
+      if (typeof entry === "string") {
+        return [quoteArg(entry, shell)];
+      }
+      if ("comment" in entry) {
+        return [];
+      }
+      if ("pattern" in entry) {
+        return [entry.pattern];
+      }
+      return [entry.op];
+    })
+    .join(" ");
+};
 class _FileSystemProject extends ProjectBase {
   rootDirectory;
   workspaces;
@@ -76,7 +117,7 @@ class _FileSystemProject extends ProjectBase {
     }
     this.rootDirectory = path.resolve(
       process.cwd(),
-      options.rootDirectory ?? "",
+      expandHomePath(options.rootDirectory ?? ""),
     );
     const rootConfig = loadRootConfig(this.rootDirectory);
     const { workspaces, workspaceMap, rootWorkspace } = findWorkspaces({
@@ -121,11 +162,6 @@ class _FileSystemProject extends ProjectBase {
           typeofName: ["boolean", "object"],
           optional: true,
         },
-        "args option": {
-          value: options.args,
-          typeofName: "string",
-          optional: true,
-        },
         "ignoreOutput option": {
           value: options.ignoreOutput,
           typeofName: "boolean",
@@ -136,6 +172,23 @@ class _FileSystemProject extends ProjectBase {
         throw: true,
       },
     );
+    if (options.args !== undefined) {
+      if (typeof options.args !== "string" && !Array.isArray(options.args)) {
+        throw new InvalidJSTypeError(
+          `Type error: args option expects type string | string[], received ${typeof options.args}`,
+        );
+      }
+      if (Array.isArray(options.args)) {
+        const argsError = validateJSArray({
+          value: options.args,
+          valueLabel: "args option",
+          itemOptions: {
+            typeofName: "string",
+          },
+        });
+        if (argsError) throw argsError;
+      }
+    }
     if (isPlainObject(options.inline)) {
       validateJSTypes(
         {
@@ -184,11 +237,7 @@ class _FileSystemProject extends ProjectBase {
       workspaceName: workspace.name,
       scriptName: options.inline ? inlineScriptName : options.script,
     };
-    const args = interpolateScriptRuntimeMetadata(
-      options.args ?? "",
-      scriptRuntimeMetadata,
-      shell,
-    );
+    const args = serializeArgs(options.args, scriptRuntimeMetadata, shell);
     const script = options.inline
       ? interpolateScriptRuntimeMetadata(
           options.script,
@@ -242,11 +291,6 @@ class _FileSystemProject extends ProjectBase {
           typeofName: ["boolean", "object"],
           optional: true,
         },
-        "args option": {
-          value: options.args,
-          typeofName: "string",
-          optional: true,
-        },
         "parallel option": {
           value: options.parallel,
           typeofName: ["boolean", "object"],
@@ -296,6 +340,23 @@ class _FileSystemProject extends ProjectBase {
         },
       );
     }
+    if (options.args !== undefined) {
+      if (typeof options.args !== "string" && !Array.isArray(options.args)) {
+        throw new InvalidJSTypeError(
+          `Type error: args option expects type string | string[], received ${typeof options.args}`,
+        );
+      }
+      if (Array.isArray(options.args)) {
+        const argsError = validateJSArray({
+          value: options.args,
+          valueLabel: "args option",
+          itemOptions: {
+            typeofName: "string",
+          },
+        });
+        if (argsError) throw argsError;
+      }
+    }
     if (isPlainObject(options.parallel)) {
       validateJSTypes(
         {
@@ -383,11 +444,7 @@ class _FileSystemProject extends ProjectBase {
           workspaceName: workspace.name,
           scriptName: options.inline ? inlineScriptName : options.script,
         };
-        const args = interpolateScriptRuntimeMetadata(
-          options.args ?? "",
-          scriptRuntimeMetadata,
-          shell,
-        );
+        const args = serializeArgs(options.args, scriptRuntimeMetadata, shell);
         const script = options.inline
           ? interpolateScriptRuntimeMetadata(
               options.script,