bun-workspaces 1.4.0 → 1.5.0

package/src/internal/docs/apiQuickstart.mjs

@@ -0,0 +1,132 @@
+// CONCATENATED MODULE: ./src/internal/docs/apiQuickstart.ts
+const RUN_WORKSPACE_SCRIPT_EXAMPLE = `
+const { output, exit } = project.runWorkspaceScript({
+  workspaceNameOrAlias: "my-workspace",
+  script: "my-script",
+
+  // 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 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
+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)
+
+`.trim();
+const RUN_SCRIPT_ACROSS_WORKSPACES_EXAMPLE = `
+
+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 (same as for runWorkspaceScript)
+  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. 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"
+  }
+});
+
+// Get a stream of script output
+for await (const { chunk, metadata } of output.text()) {
+  // 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
+}
+
+// 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)
+}
+`.trim();
+const API_QUICKSTART = `
+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 () => {
+  ${RUN_WORKSPACE_SCRIPT_EXAMPLE.split("\n").join("\n  ")}
+}
+
+// Run a script in all workspaces that have it in their package.json "scripts" field
+const runManyScripts = async () => {
+  ${RUN_SCRIPT_ACROSS_WORKSPACES_EXAMPLE.split("\n").join("\n  ")}
+}
+`.trim();
+
+export {
+  API_QUICKSTART,
+  RUN_SCRIPT_ACROSS_WORKSPACES_EXAMPLE,
+  RUN_WORKSPACE_SCRIPT_EXAMPLE,
+};

package/src/internal/docs/cliQuickstart.d.ts

@@ -0,0 +1,2 @@
+export declare const CLI_QUICKSTART: string;
+export declare const INLINE_SCRIPT_EXAMPLE: string;

package/src/internal/docs/cliQuickstart.mjs

@@ -0,0 +1,86 @@
+// CONCATENATED MODULE: ./src/internal/docs/cliQuickstart.ts
+const CLI_QUICKSTART = `
+# 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 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)
+
+# 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 "my-workspace-*" # Run for matching workspace names
+bw run lint "alias:my-alias-*" "path:my-glob/**/*" "tag:my-tag" # Use matching specifiers
+bw run lint "*" "not:path:my-path/*" # Run for all workspaces not in my-path/
+
+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
+bw run lint --parallel=50% # Run in parallel with a max of 50% of the "auto" limit
+
+# 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=auto
+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
+
+# Silence all output of the run command
+bw --log-level=silent run my-script --output-style=none
+
+# 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 my-script
+
+# Pass --log-level to any command (debug, info, warn, error, or silent)
+bw --log-level=debug ls
+`.trim();
+const INLINE_SCRIPT_EXAMPLE = `
+# Run an inline command from the workspace directory
+bw run "bun run build" --inline
+`.trim();
+
+export { CLI_QUICKSTART, INLINE_SCRIPT_EXAMPLE };

package/src/internal/docs/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./cliQuickstart";
+export * from "./apiQuickstart";

package/src/internal/docs/index.mjs

@@ -0,0 +1,2 @@
+export * from "./cliQuickstart.mjs";
+export * from "./apiQuickstart.mjs"; // CONCATENATED MODULE: ./src/internal/docs/index.ts

package/src/internal/generated/aiDocs/docs.d.ts

@@ -0,0 +1,10 @@
+export declare const DOC_OVERVIEW =
+  '## Project Overview\n\nbun-workspaces is a CLI and TypeScript API to help manage Bun monorepos. It reads `bun.lock` to find all workspaces in the project. It is referred to as "bw" for short, which is also the recommended CLI alias. The overall goal is a monorepo tool that is more lightweight than others, with still powerful comparable features, requiring no special config to get started, only a standard Bun repo using workspaces.\n\nThree main domain terms to know:\n\n- Project: generally represents a monorepo and is defined by the root `package.json` file\n- Workspace: a nested package within a project. The root package.json can count as a workspace as well, but by default, only nested packages are considered workspaces.\n- Script: an entry in the `scripts` field of a workspace\'s `package.json` file. bw can also run one-off commands known as "inline scripts," which can use the Bun shell or system shell (`sh -c` or `cmd /d /s /c` for windows).';
+export declare const DOC_CONCEPTS =
+  '## Concepts\n\n### Workspace patterns\n\nMany features accept a list of workspace patterns to match a subset of workspaces.\n\nBy default, a pattern matches the workspace name or alias: `my-workspace-name` or `my-alias-name`. Aliases are defined in config explained below.\n\nPatterns can include a wildcard to match only by workspace name: `my-workspace-*`.\n\n- Alias pattern specifier: `alias:my-alias-*`.\n- Path pattern specifier (supports glob): `path:packages/**/*`.\n- Name pattern specifier: `name:my-workspace-*`.\n- Tag pattern specifier: `tag:my-tag`.\n- Special root workspace selector: `@root`.\n- Any pattern can start with `not:` to negate the pattern. (e.g. "not:my-workspace-name", "not:tag:my-tag-\\*") This excludes workspaces that match any other present patterns from a result.\n\n### Script runtime metadata\n\nScripts ran via bw can access metadata via env vars. This same metadata can be interpolated into inline scripts and appended args.\n\n```typescript\n// in a script\nconst projectPath = process.env.BW_PROJECT_PATH;\nconst workspaceName = process.env.BW_WORKSPACE_NAME;\nconst workspacePath = process.env.BW_WORKSPACE_PATH;\nconst workspaceRelativePath = process.env.BW_WORKSPACE_RELATIVE_PATH;\nconst scriptName = process.env.BW_SCRIPT_NAME;\n```\n\n```bash\n# interpolated\nbw run "bun <projectPath>/my-script.ts" --inline \\\n  --inline-name="my-script-name" \\\n  --args="<workspaceName> <workspacePath>"\n```';
+export declare const DOC_CLI =
+  '### CLI examples:\n\n```bash\nalias bw="bunx bun-workspaces"\n\nbw list-workspaces # human-readable output\nbw ls --json --pretty # ls is alias for list-workspaces\nbw ls "name:my-workspace-*" "alias:my-alias-*" "path:packages/**/*" # accepts workspace patterns\n\n# info includes the name, aliases, path, etc.\nbw workspace-info my-workspace\nbw info my-workspace --json --pretty # info is alias for workspace-info\n\n# info includes the script name and workspaces that have it in their package.json "scripts" field\nbw script-info my-script --json --pretty\n\n# run the package.json "lint" script for all workspaces that have it\nbw run-script lint\n\n# run is alias for run-script\n# run the package.json "lint" script for workspaces using matching specifiers\nbw run lint my-workspace-name "alias:my-alias-pattern-*" "path:my-glob/**/*" # accepts workspace patterns\n\n# A workspace\'s script will wait until any workspaces it depends on have completed\n# Similar to Bun\'s --filter behavior\nbw run lint --dep-order\n\n# Continue running scripts even if a dependency fails\nbw run lint --dep-order --ignore-dep-failure\n\n# special root workspace selector (works even if root workspace is not included)\nbw run lint @root\n\n# Scripts run in parallel by default\nbw run lint --parallel=false # Run in series\n\n# Default can be overridden by config or env var BW_PARALLEL_MAX_DEFAULT\nbw run lint --parallel # default "auto", os.availableParallelism()\nbw run lint --parallel=2 # Run in parallel with a max of 2 concurrent scripts\nbw run lint --parallel=50% # 50% of os.availableParallelism()\nbw run lint --parallel=unbounded # run all in one batch\n\n# add args to the script command\nbw run lint --args="--my-arg=value"\nbw run lint --args="--my-arg=<workspaceName>" # use the workspace name in args\n\n# run the script as an inline command from the workspace directory\nbw run "bun build" --inline\nbw run "bun build" --inline --inline-name="my-script"\nbw run "bun build" --inline --shell=system # use the system shell\n\n# Use the grouped output style (default when on a TTY)\nbw run my-script --output-style=grouped\n\n# Set the max preview lines for script output in grouped output style\nbw run my-script --output-style=grouped --grouped-lines=auto\nbw run my-script --output-style=grouped --grouped-lines=10\n\n# Use simple script output with workspace prefixes (default when not on a TTY)\nbw run my-script --output-style=prefixed\n\n# Use the plain output style (no workspace prefixes)\nbw run my-script --output-style=plain\n\n### Global Options ###\n# Root directory of project:\nbw --cwd=/path/to/project ls\nbw -d /path/to/project ls\n\n# Include root workspace as a normal workspace (default false):\nbw --include-root ls\nbw -r ls\nbw --no-include-root ls # override config/env var setting\n\n# Log level (debug|info|warn|error|silent, default info)\nbw --log-level=silent ls\nbw -l silent ls\n```';
+export declare const DOC_API =
+  '### API examples:\n\nThe API is held in close parity with the CLI. It is developed first so that the CLI is a thin wrapper around the API.\n\n```typescript\nimport { createFileSystemProject } from "bun-workspaces";\n\nconst project = createFileSystemProject({\n  // the options object itself and its properties are optional\n  rootDirectory: "path/to/your/project",\n  includeRootWorkspace: false,\n});\nproject.workspaces; // array of all workspaces in the project\nproject.rootWorkspace; // the root workspace (available even when not included in the workspaces array)\nproject.findWorkspaceByName("my-workspace"); // find a workspace by name\nproject.findWorkspaceByAlias("my-alias"); // find a workspace by alias\nproject.findWorkspaceByNameOrAlias("my-workspace-or-alias"); // find a workspace by name or alias\nproject.findWorkspacesByPattern(\n  "my-workspace-name",\n  "my-workspace-alias",\n  "my-name-pattern-*",\n  "alias:my-alias-*",\n  "path:my-glob/**/*",\n); // find workspaces by pattern like the CLI\nproject.runWorkspaceScript({\n  workspaceNameOrAlias: "my-workspace",\n  script: "lint",\n  inline: true,\n  // args can be a string or an array of strings\n  // if string, the argv will be parsed POSIX-style\n  args: "--my-arg=value",\n});\nproject.runScriptAcrossWorkspaces({\n  script: "lint",\n  workspacePatterns: [\n    "alias:my-alias-pattern-*",\n    "path:my-glob/**/*",\n    "workspace-name-a",\n    "workspace-alias-b",\n  ],\n  parallel: true, // also could be { max: 2 }, max taking same options as seen in CLI examples above (e.g. "50%", "auto", etc.)\n  dependencyOrder: true,\n  ignoreDependencyFailure: true,\n  // same as for runWorkspaceScript\n  args: ["--my", "--appended", "--args"],\n  // Optional, callback when script starts, skips, or exits\n  onScriptEvent: (event, { workspace, exitResult }) => {\n    // event: "start", "skip", "exit"\n  },\n});\n```\n\n## The Workspace object\n\n```jsonc\n{\n  // The name of the workspace from its package.json\n  "name": "my-workspace",\n  // Whether the workspace is the root workspace\n  "isRoot": false,\n  // The relative path to the workspace from the project root\n  "path": "my/workspace/path",\n  // The glob pattern from the root package.json "workspaces" field\n  // that this workspace was matched from\n  "matchPattern": "my/workspace/pattern/*",\n  // The scripts available in the workspace\'s package.json\n  "scripts": ["my-script"],\n  // Aliases defined in workspace configuration (bw.workspace.jsonc/bw.workspace.json)\n  "aliases": ["my-alias"],\n  // Names of other workspaces that this workspace depends on\n  "dependencies": ["my-dependency"],\n  // Names of other workspaces that depend on this workspace\n  "dependents": ["my-dependent"],\n}\n```';
+export declare const DOC_CONFIG =
+  '## Root config\n\nOptional project config can be placed in `bw.root.jsonc`/`bw.root.json` in the root directory.\n\nConfig defaults here take precedence over environment variables that can set defaults.\nExplicit arguments to the CLI or API take precedence over all other settings.\n\n```jsonc\n{\n  "defaults": {\n    "parallelMax": 5, // same options as seen in CLI examples above\n    "shell": "system", // "bun" or "system" (default "bun")\n    "includeRootWorkspace": true, // treat root package.json as a normal workspace\n  },\n}\n```\n\n## Workspace config\n\nOptional config can be placed in `bw.workspace.jsonc`/`bw.workspace.json` in a workspace directory.\n\nAliases must be unique to each workspace and to not clash with other workspaces\' `package.json` names.\n\nTags are strings to group workspaces together that therefore don\'t need to be unique to each workspace.\n\n```jsonc\n{\n  "alias": "my-alias", // can be array\n  "tags": ["my-tag"],\n  "scripts": {\n    "lint": {\n      // set optional sorting order for scripts\n      "order": 1,\n    },\n  },\n  "rules": {\n    "workspaceDependencies": {\n      // use workspace patterns to allow or deny other workspaces as dependencies\n      "allowPatterns": ["my-allow-pattern-*"],\n      // or\n      // "denyPatterns": ["my-deny-pattern-*"],\n    },\n  },\n}\n```\n\n### Workspace Dependency Rules\n\nUsing the `rules.workspaceDependencies` field, you can define rules for which workspaces are allowed to be dependencies,\nusing either `allowPatterns` or `denyPatterns`.\n\nWorkspace Patterns are used to match workspaces.\n\nYou can\'t use both `allowPatterns` and `denyPatterns` at the same time, but you can use\n\n## TypeScript/JSON Config Files\n\nYou can use TypeScript/JSON config files to define your workspace configuration.\n\n### TypeScript\n\n`bw.workspace.ts`\n\n```ts\nimport { defineWorkspaceConfig } from "bun-workspaces/config";\n\nexport default defineWorkspaceConfig({\n  alias: "my-alias",\n  tags: ["my-tag"],\n});\n```\n\n`bw.root.ts`\n\n```ts\nimport { defineRootConfig } from "bun-workspaces/config";\n\nexport default defineRootConfig({\n  defaults: {\n    parallelMax: 5,\n  },\n});\n```';

package/src/internal/generated/aiDocs/docs.mjs

@@ -0,0 +1,285 @@
+// CONCATENATED MODULE: ./src/internal/generated/aiDocs/docs.ts
+// This file is generated by scripts/generateMcpDocs.ts. Do not edit manually.
+const DOC_OVERVIEW = `## Project Overview
+
+bun-workspaces is a CLI and TypeScript API to help manage Bun monorepos. It reads \`bun.lock\` to find all workspaces in the project. It is referred to as "bw" for short, which is also the recommended CLI alias. The overall goal is a monorepo tool that is more lightweight than others, with still powerful comparable features, requiring no special config to get started, only a standard Bun repo using workspaces.
+
+Three main domain terms to know:
+
+- Project: generally represents a monorepo and is defined by the root \`package.json\` file
+- Workspace: a nested package within a project. The root package.json can count as a workspace as well, but by default, only nested packages are considered workspaces.
+- Script: an entry in the \`scripts\` field of a workspace's \`package.json\` file. bw can also run one-off commands known as "inline scripts," which can use the Bun shell or system shell (\`sh -c\` or \`cmd /d /s /c\` for windows).`;
+const DOC_CONCEPTS = `## Concepts
+
+### Workspace patterns
+
+Many features accept a list of workspace patterns to match a subset of workspaces.
+
+By default, a pattern matches the workspace name or alias: \`my-workspace-name\` or \`my-alias-name\`. Aliases are defined in config explained below.
+
+Patterns can include a wildcard to match only by workspace name: \`my-workspace-*\`.
+
+- Alias pattern specifier: \`alias:my-alias-*\`.
+- Path pattern specifier (supports glob): \`path:packages/**/*\`.
+- Name pattern specifier: \`name:my-workspace-*\`.
+- Tag pattern specifier: \`tag:my-tag\`.
+- Special root workspace selector: \`@root\`.
+- Any pattern can start with \`not:\` to negate the pattern. (e.g. "not:my-workspace-name", "not:tag:my-tag-\\*") This excludes workspaces that match any other present patterns from a result.
+
+### Script runtime metadata
+
+Scripts ran via bw can access metadata via env vars. This same metadata can be interpolated into inline scripts and appended args.
+
+\`\`\`typescript
+// in a script
+const projectPath = process.env.BW_PROJECT_PATH;
+const workspaceName = process.env.BW_WORKSPACE_NAME;
+const workspacePath = process.env.BW_WORKSPACE_PATH;
+const workspaceRelativePath = process.env.BW_WORKSPACE_RELATIVE_PATH;
+const scriptName = process.env.BW_SCRIPT_NAME;
+\`\`\`
+
+\`\`\`bash
+# interpolated
+bw run "bun <projectPath>/my-script.ts" --inline \\
+  --inline-name="my-script-name" \\
+  --args="<workspaceName> <workspacePath>"
+\`\`\``;
+const DOC_CLI = `### CLI examples:
+
+\`\`\`bash
+alias bw="bunx bun-workspaces"
+
+bw list-workspaces # human-readable output
+bw ls --json --pretty # ls is alias for list-workspaces
+bw ls "name:my-workspace-*" "alias:my-alias-*" "path:packages/**/*" # accepts workspace patterns
+
+# info includes the name, aliases, path, etc.
+bw workspace-info my-workspace
+bw info my-workspace --json --pretty # info is alias for workspace-info
+
+# info includes the script name and workspaces that have it in their package.json "scripts" field
+bw script-info my-script --json --pretty
+
+# run the package.json "lint" script for all workspaces that have it
+bw run-script lint
+
+# run is alias for run-script
+# run the package.json "lint" script for workspaces using matching specifiers
+bw run lint my-workspace-name "alias:my-alias-pattern-*" "path:my-glob/**/*" # accepts workspace patterns
+
+# 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
+
+# special root workspace selector (works even if root workspace is not included)
+bw run lint @root
+
+# Scripts run in parallel by default
+bw run lint --parallel=false # Run in series
+
+# Default can be overridden by config or env var BW_PARALLEL_MAX_DEFAULT
+bw run lint --parallel # default "auto", os.availableParallelism()
+bw run lint --parallel=2 # Run in parallel with a max of 2 concurrent scripts
+bw run lint --parallel=50% # 50% of os.availableParallelism()
+bw run lint --parallel=unbounded # run all in one batch
+
+# add args to the script command
+bw run lint --args="--my-arg=value"
+bw run lint --args="--my-arg=<workspaceName>" # use the workspace name in args
+
+# run the script as an inline command from the workspace directory
+bw run "bun build" --inline
+bw run "bun build" --inline --inline-name="my-script"
+bw run "bun build" --inline --shell=system # use the system shell
+
+# 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=auto
+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
+
+### Global Options ###
+# Root directory of project:
+bw --cwd=/path/to/project ls
+bw -d /path/to/project ls
+
+# Include root workspace as a normal workspace (default false):
+bw --include-root ls
+bw -r ls
+bw --no-include-root ls # override config/env var setting
+
+# Log level (debug|info|warn|error|silent, default info)
+bw --log-level=silent ls
+bw -l silent ls
+\`\`\``;
+const DOC_API = `### API examples:
+
+The API is held in close parity with the CLI. It is developed first so that the CLI is a thin wrapper around the API.
+
+\`\`\`typescript
+import { createFileSystemProject } from "bun-workspaces";
+
+const project = createFileSystemProject({
+  // the options object itself and its properties are optional
+  rootDirectory: "path/to/your/project",
+  includeRootWorkspace: false,
+});
+project.workspaces; // array of all workspaces in the project
+project.rootWorkspace; // the root workspace (available even when not included in the workspaces array)
+project.findWorkspaceByName("my-workspace"); // find a workspace by name
+project.findWorkspaceByAlias("my-alias"); // find a workspace by alias
+project.findWorkspaceByNameOrAlias("my-workspace-or-alias"); // find a workspace by name or alias
+project.findWorkspacesByPattern(
+  "my-workspace-name",
+  "my-workspace-alias",
+  "my-name-pattern-*",
+  "alias:my-alias-*",
+  "path:my-glob/**/*",
+); // find workspaces by pattern like the CLI
+project.runWorkspaceScript({
+  workspaceNameOrAlias: "my-workspace",
+  script: "lint",
+  inline: true,
+  // args can be a string or an array of strings
+  // if string, the argv will be parsed POSIX-style
+  args: "--my-arg=value",
+});
+project.runScriptAcrossWorkspaces({
+  script: "lint",
+  workspacePatterns: [
+    "alias:my-alias-pattern-*",
+    "path:my-glob/**/*",
+    "workspace-name-a",
+    "workspace-alias-b",
+  ],
+  parallel: true, // also could be { max: 2 }, max taking same options as seen in CLI examples above (e.g. "50%", "auto", etc.)
+  dependencyOrder: true,
+  ignoreDependencyFailure: true,
+  // same as for runWorkspaceScript
+  args: ["--my", "--appended", "--args"],
+  // Optional, callback when script starts, skips, or exits
+  onScriptEvent: (event, { workspace, exitResult }) => {
+    // event: "start", "skip", "exit"
+  },
+});
+\`\`\`
+
+## The Workspace object
+
+\`\`\`jsonc
+{
+  // The name of the workspace from its package.json
+  "name": "my-workspace",
+  // Whether the workspace is the root workspace
+  "isRoot": false,
+  // The relative path to the workspace from the project root
+  "path": "my/workspace/path",
+  // The glob pattern from the root package.json "workspaces" field
+  // that this workspace was matched from
+  "matchPattern": "my/workspace/pattern/*",
+  // The scripts available in the workspace's package.json
+  "scripts": ["my-script"],
+  // Aliases defined in workspace configuration (bw.workspace.jsonc/bw.workspace.json)
+  "aliases": ["my-alias"],
+  // Names of other workspaces that this workspace depends on
+  "dependencies": ["my-dependency"],
+  // Names of other workspaces that depend on this workspace
+  "dependents": ["my-dependent"],
+}
+\`\`\``;
+const DOC_CONFIG = `## Root config
+
+Optional project config can be placed in \`bw.root.jsonc\`/\`bw.root.json\` in the root directory.
+
+Config defaults here take precedence over environment variables that can set defaults.
+Explicit arguments to the CLI or API take precedence over all other settings.
+
+\`\`\`jsonc
+{
+  "defaults": {
+    "parallelMax": 5, // same options as seen in CLI examples above
+    "shell": "system", // "bun" or "system" (default "bun")
+    "includeRootWorkspace": true, // treat root package.json as a normal workspace
+  },
+}
+\`\`\`
+
+## Workspace config
+
+Optional config can be placed in \`bw.workspace.jsonc\`/\`bw.workspace.json\` in a workspace directory.
+
+Aliases must be unique to each workspace and to not clash with other workspaces' \`package.json\` names.
+
+Tags are strings to group workspaces together that therefore don't need to be unique to each workspace.
+
+\`\`\`jsonc
+{
+  "alias": "my-alias", // can be array
+  "tags": ["my-tag"],
+  "scripts": {
+    "lint": {
+      // set optional sorting order for scripts
+      "order": 1,
+    },
+  },
+  "rules": {
+    "workspaceDependencies": {
+      // use workspace patterns to allow or deny other workspaces as dependencies
+      "allowPatterns": ["my-allow-pattern-*"],
+      // or
+      // "denyPatterns": ["my-deny-pattern-*"],
+    },
+  },
+}
+\`\`\`
+
+### Workspace Dependency Rules
+
+Using the \`rules.workspaceDependencies\` field, you can define rules for which workspaces are allowed to be dependencies,
+using either \`allowPatterns\` or \`denyPatterns\`.
+
+Workspace Patterns are used to match workspaces.
+
+You can't use both \`allowPatterns\` and \`denyPatterns\` at the same time, but you can use
+
+## TypeScript/JSON Config Files
+
+You can use TypeScript/JSON config files to define your workspace configuration.
+
+### TypeScript
+
+\`bw.workspace.ts\`
+
+\`\`\`ts
+import { defineWorkspaceConfig } from "bun-workspaces/config";
+
+export default defineWorkspaceConfig({
+  alias: "my-alias",
+  tags: ["my-tag"],
+});
+\`\`\`
+
+\`bw.root.ts\`
+
+\`\`\`ts
+import { defineRootConfig } from "bun-workspaces/config";
+
+export default defineRootConfig({
+  defaults: {
+    parallelMax: 5,
+  },
+});
+\`\`\``;
+
+export { DOC_API, DOC_CLI, DOC_CONCEPTS, DOC_CONFIG, DOC_OVERVIEW };

package/src/internal/generated/ajv/validateWorkspaceConfig.mjs

@@ -1 +1 @@
-"use strict";module.exports = validate10;module.exports.default = validate10;const schema11 = {"type":"object","additionalProperties":false,"properties":{"alias":{"type":["string","array"],"items":{"type":"string"},"uniqueItems":true},"tags":{"type":"array","items":{"type":"string"},"uniqueItems":true},"scripts":{"type":"object","additionalProperties":{"type":"object","properties":{"order":{"type":"number"}},"additionalProperties":false}}}};function validate10(data, {instancePath="", parentData, parentDataProperty, rootData=data}={}){let vErrors = null;let errors = 0;if(errors === 0){if(data && typeof data == "object" && !Array.isArray(data)){const _errs1 = errors;for(const key0 in data){if(!(((key0 === "alias") || (key0 === "tags")) || (key0 === "scripts"))){validate10.errors = [{instancePath,schemaPath:"#/additionalProperties",keyword:"additionalProperties",params:{additionalProperty: key0},message:"must NOT have additional properties"}];return false;break;}}if(_errs1 === errors){if(data.alias !== undefined){let data0 = data.alias;const _errs2 = errors;if((typeof data0 !== "string") && (!(Array.isArray(data0)))){validate10.errors = [{instancePath:instancePath+"/alias",schemaPath:"#/properties/alias/type",keyword:"type",params:{type: schema11.properties.alias.type},message:"must be string,array"}];return false;}if(errors === _errs2){if(Array.isArray(data0)){var valid1 = true;const len0 = data0.length;for(let i0=0; i0<len0; i0++){const _errs4 = errors;if(typeof data0[i0] !== "string"){validate10.errors = [{instancePath:instancePath+"/alias/" + i0,schemaPath:"#/properties/alias/items/type",keyword:"type",params:{type: "string"},message:"must be string"}];return false;}var valid1 = _errs4 === errors;if(!valid1){break;}}if(valid1){let i1 = data0.length;let j0;if(i1 > 1){const indices0 = {};for(;i1--;){let item0 = data0[i1];if(typeof item0 !== "string"){continue;}if(typeof indices0[item0] == "number"){j0 = indices0[item0];validate10.errors = [{instancePath:instancePath+"/alias",schemaPath:"#/properties/alias/uniqueItems",keyword:"uniqueItems",params:{i: i1, j: j0},message:"must NOT have duplicate items (items ## "+j0+" and "+i1+" are identical)"}];return false;break;}indices0[item0] = i1;}}}}}var valid0 = _errs2 === errors;}else {var valid0 = true;}if(valid0){if(data.tags !== undefined){let data2 = data.tags;const _errs6 = errors;if(errors === _errs6){if(Array.isArray(data2)){var valid3 = true;const len1 = data2.length;for(let i2=0; i2<len1; i2++){const _errs8 = errors;if(typeof data2[i2] !== "string"){validate10.errors = [{instancePath:instancePath+"/tags/" + i2,schemaPath:"#/properties/tags/items/type",keyword:"type",params:{type: "string"},message:"must be string"}];return false;}var valid3 = _errs8 === errors;if(!valid3){break;}}if(valid3){let i3 = data2.length;let j1;if(i3 > 1){const indices1 = {};for(;i3--;){let item1 = data2[i3];if(typeof item1 !== "string"){continue;}if(typeof indices1[item1] == "number"){j1 = indices1[item1];validate10.errors = [{instancePath:instancePath+"/tags",schemaPath:"#/properties/tags/uniqueItems",keyword:"uniqueItems",params:{i: i3, j: j1},message:"must NOT have duplicate items (items ## "+j1+" and "+i3+" are identical)"}];return false;break;}indices1[item1] = i3;}}}}else {validate10.errors = [{instancePath:instancePath+"/tags",schemaPath:"#/properties/tags/type",keyword:"type",params:{type: "array"},message:"must be array"}];return false;}}var valid0 = _errs6 === errors;}else {var valid0 = true;}if(valid0){if(data.scripts !== undefined){let data4 = data.scripts;const _errs10 = errors;if(errors === _errs10){if(data4 && typeof data4 == "object" && !Array.isArray(data4)){for(const key1 in data4){let data5 = data4[key1];const _errs13 = errors;if(errors === _errs13){if(data5 && typeof data5 == "object" && !Array.isArray(data5)){const _errs15 = errors;for(const key2 in data5){if(!(key2 === "order")){validate10.errors = [{instancePath:instancePath+"/scripts/" + key1.replace(/~/g, "~0").replace(/\//g, "~1"),schemaPath:"#/properties/scripts/additionalProperties/additionalProperties",keyword:"additionalProperties",params:{additionalProperty: key2},message:"must NOT have additional properties"}];return false;break;}}if(_errs15 === errors){if(data5.order !== undefined){let data6 = data5.order;if(!((typeof data6 == "number") && (isFinite(data6)))){validate10.errors = [{instancePath:instancePath+"/scripts/" + key1.replace(/~/g, "~0").replace(/\//g, "~1")+"/order",schemaPath:"#/properties/scripts/additionalProperties/properties/order/type",keyword:"type",params:{type: "number"},message:"must be number"}];return false;}}}}else {validate10.errors = [{instancePath:instancePath+"/scripts/" + key1.replace(/~/g, "~0").replace(/\//g, "~1"),schemaPath:"#/properties/scripts/additionalProperties/type",keyword:"type",params:{type: "object"},message:"must be object"}];return false;}}var valid5 = _errs13 === errors;if(!valid5){break;}}}else {validate10.errors = [{instancePath:instancePath+"/scripts",schemaPath:"#/properties/scripts/type",keyword:"type",params:{type: "object"},message:"must be object"}];return false;}}var valid0 = _errs10 === errors;}else {var valid0 = true;}}}}}else {validate10.errors = [{instancePath,schemaPath:"#/type",keyword:"type",params:{type: "object"},message:"must be object"}];return false;}}validate10.errors = vErrors;return errors === 0;}
+"use strict";module.exports = validate10;module.exports.default = validate10;const schema11 = {"type":"object","additionalProperties":false,"properties":{"alias":{"type":["string","array"],"items":{"type":"string"},"uniqueItems":true},"tags":{"type":"array","items":{"type":"string"},"uniqueItems":true},"scripts":{"type":"object","additionalProperties":{"type":"object","properties":{"order":{"type":"number"}},"additionalProperties":false}},"rules":{"type":"object","additionalProperties":false,"properties":{"workspaceDependencies":{"type":"object","properties":{"allowPatterns":{"type":"array","items":{"type":"string"}},"denyPatterns":{"type":"array","items":{"type":"string"}}},"additionalProperties":false}}}}};function validate10(data, {instancePath="", parentData, parentDataProperty, rootData=data}={}){let vErrors = null;let errors = 0;if(errors === 0){if(data && typeof data == "object" && !Array.isArray(data)){const _errs1 = errors;for(const key0 in data){if(!((((key0 === "alias") || (key0 === "tags")) || (key0 === "scripts")) || (key0 === "rules"))){validate10.errors = [{instancePath,schemaPath:"#/additionalProperties",keyword:"additionalProperties",params:{additionalProperty: key0},message:"must NOT have additional properties"}];return false;break;}}if(_errs1 === errors){if(data.alias !== undefined){let data0 = data.alias;const _errs2 = errors;if((typeof data0 !== "string") && (!(Array.isArray(data0)))){validate10.errors = [{instancePath:instancePath+"/alias",schemaPath:"#/properties/alias/type",keyword:"type",params:{type: schema11.properties.alias.type},message:"must be string,array"}];return false;}if(errors === _errs2){if(Array.isArray(data0)){var valid1 = true;const len0 = data0.length;for(let i0=0; i0<len0; i0++){const _errs4 = errors;if(typeof data0[i0] !== "string"){validate10.errors = [{instancePath:instancePath+"/alias/" + i0,schemaPath:"#/properties/alias/items/type",keyword:"type",params:{type: "string"},message:"must be string"}];return false;}var valid1 = _errs4 === errors;if(!valid1){break;}}if(valid1){let i1 = data0.length;let j0;if(i1 > 1){const indices0 = {};for(;i1--;){let item0 = data0[i1];if(typeof item0 !== "string"){continue;}if(typeof indices0[item0] == "number"){j0 = indices0[item0];validate10.errors = [{instancePath:instancePath+"/alias",schemaPath:"#/properties/alias/uniqueItems",keyword:"uniqueItems",params:{i: i1, j: j0},message:"must NOT have duplicate items (items ## "+j0+" and "+i1+" are identical)"}];return false;break;}indices0[item0] = i1;}}}}}var valid0 = _errs2 === errors;}else {var valid0 = true;}if(valid0){if(data.tags !== undefined){let data2 = data.tags;const _errs6 = errors;if(errors === _errs6){if(Array.isArray(data2)){var valid3 = true;const len1 = data2.length;for(let i2=0; i2<len1; i2++){const _errs8 = errors;if(typeof data2[i2] !== "string"){validate10.errors = [{instancePath:instancePath+"/tags/" + i2,schemaPath:"#/properties/tags/items/type",keyword:"type",params:{type: "string"},message:"must be string"}];return false;}var valid3 = _errs8 === errors;if(!valid3){break;}}if(valid3){let i3 = data2.length;let j1;if(i3 > 1){const indices1 = {};for(;i3--;){let item1 = data2[i3];if(typeof item1 !== "string"){continue;}if(typeof indices1[item1] == "number"){j1 = indices1[item1];validate10.errors = [{instancePath:instancePath+"/tags",schemaPath:"#/properties/tags/uniqueItems",keyword:"uniqueItems",params:{i: i3, j: j1},message:"must NOT have duplicate items (items ## "+j1+" and "+i3+" are identical)"}];return false;break;}indices1[item1] = i3;}}}}else {validate10.errors = [{instancePath:instancePath+"/tags",schemaPath:"#/properties/tags/type",keyword:"type",params:{type: "array"},message:"must be array"}];return false;}}var valid0 = _errs6 === errors;}else {var valid0 = true;}if(valid0){if(data.scripts !== undefined){let data4 = data.scripts;const _errs10 = errors;if(errors === _errs10){if(data4 && typeof data4 == "object" && !Array.isArray(data4)){for(const key1 in data4){let data5 = data4[key1];const _errs13 = errors;if(errors === _errs13){if(data5 && typeof data5 == "object" && !Array.isArray(data5)){const _errs15 = errors;for(const key2 in data5){if(!(key2 === "order")){validate10.errors = [{instancePath:instancePath+"/scripts/" + key1.replace(/~/g, "~0").replace(/\//g, "~1"),schemaPath:"#/properties/scripts/additionalProperties/additionalProperties",keyword:"additionalProperties",params:{additionalProperty: key2},message:"must NOT have additional properties"}];return false;break;}}if(_errs15 === errors){if(data5.order !== undefined){let data6 = data5.order;if(!((typeof data6 == "number") && (isFinite(data6)))){validate10.errors = [{instancePath:instancePath+"/scripts/" + key1.replace(/~/g, "~0").replace(/\//g, "~1")+"/order",schemaPath:"#/properties/scripts/additionalProperties/properties/order/type",keyword:"type",params:{type: "number"},message:"must be number"}];return false;}}}}else {validate10.errors = [{instancePath:instancePath+"/scripts/" + key1.replace(/~/g, "~0").replace(/\//g, "~1"),schemaPath:"#/properties/scripts/additionalProperties/type",keyword:"type",params:{type: "object"},message:"must be object"}];return false;}}var valid5 = _errs13 === errors;if(!valid5){break;}}}else {validate10.errors = [{instancePath:instancePath+"/scripts",schemaPath:"#/properties/scripts/type",keyword:"type",params:{type: "object"},message:"must be object"}];return false;}}var valid0 = _errs10 === errors;}else {var valid0 = true;}if(valid0){if(data.rules !== undefined){let data7 = data.rules;const _errs18 = errors;if(errors === _errs18){if(data7 && typeof data7 == "object" && !Array.isArray(data7)){const _errs20 = errors;for(const key3 in data7){if(!(key3 === "workspaceDependencies")){validate10.errors = [{instancePath:instancePath+"/rules",schemaPath:"#/properties/rules/additionalProperties",keyword:"additionalProperties",params:{additionalProperty: key3},message:"must NOT have additional properties"}];return false;break;}}if(_errs20 === errors){if(data7.workspaceDependencies !== undefined){let data8 = data7.workspaceDependencies;const _errs21 = errors;if(errors === _errs21){if(data8 && typeof data8 == "object" && !Array.isArray(data8)){const _errs23 = errors;for(const key4 in data8){if(!((key4 === "allowPatterns") || (key4 === "denyPatterns"))){validate10.errors = [{instancePath:instancePath+"/rules/workspaceDependencies",schemaPath:"#/properties/rules/properties/workspaceDependencies/additionalProperties",keyword:"additionalProperties",params:{additionalProperty: key4},message:"must NOT have additional properties"}];return false;break;}}if(_errs23 === errors){if(data8.allowPatterns !== undefined){let data9 = data8.allowPatterns;const _errs24 = errors;if(errors === _errs24){if(Array.isArray(data9)){var valid9 = true;const len2 = data9.length;for(let i4=0; i4<len2; i4++){const _errs26 = errors;if(typeof data9[i4] !== "string"){validate10.errors = [{instancePath:instancePath+"/rules/workspaceDependencies/allowPatterns/" + i4,schemaPath:"#/properties/rules/properties/workspaceDependencies/properties/allowPatterns/items/type",keyword:"type",params:{type: "string"},message:"must be string"}];return false;}var valid9 = _errs26 === errors;if(!valid9){break;}}}else {validate10.errors = [{instancePath:instancePath+"/rules/workspaceDependencies/allowPatterns",schemaPath:"#/properties/rules/properties/workspaceDependencies/properties/allowPatterns/type",keyword:"type",params:{type: "array"},message:"must be array"}];return false;}}var valid8 = _errs24 === errors;}else {var valid8 = true;}if(valid8){if(data8.denyPatterns !== undefined){let data11 = data8.denyPatterns;const _errs28 = errors;if(errors === _errs28){if(Array.isArray(data11)){var valid10 = true;const len3 = data11.length;for(let i5=0; i5<len3; i5++){const _errs30 = errors;if(typeof data11[i5] !== "string"){validate10.errors = [{instancePath:instancePath+"/rules/workspaceDependencies/denyPatterns/" + i5,schemaPath:"#/properties/rules/properties/workspaceDependencies/properties/denyPatterns/items/type",keyword:"type",params:{type: "string"},message:"must be string"}];return false;}var valid10 = _errs30 === errors;if(!valid10){break;}}}else {validate10.errors = [{instancePath:instancePath+"/rules/workspaceDependencies/denyPatterns",schemaPath:"#/properties/rules/properties/workspaceDependencies/properties/denyPatterns/type",keyword:"type",params:{type: "array"},message:"must be array"}];return false;}}var valid8 = _errs28 === errors;}else {var valid8 = true;}}}}else {validate10.errors = [{instancePath:instancePath+"/rules/workspaceDependencies",schemaPath:"#/properties/rules/properties/workspaceDependencies/type",keyword:"type",params:{type: "object"},message:"must be object"}];return false;}}}}}else {validate10.errors = [{instancePath:instancePath+"/rules",schemaPath:"#/properties/rules/type",keyword:"type",params:{type: "object"},message:"must be object"}];return false;}}var valid0 = _errs18 === errors;}else {var valid0 = true;}}}}}}else {validate10.errors = [{instancePath,schemaPath:"#/type",keyword:"type",params:{type: "object"},message:"must be object"}];return false;}}validate10.errors = vErrors;return errors === 0;}

package/src/runScript/subprocesses.mjs

@@ -24,6 +24,7 @@ runOnExit((codeOrSignal) => {
   options,
 ) => {
   const subprocess = Bun.spawn(argv, options);
+  logger.debug(`Subprocess spawned with pid ${subprocess.pid}`);
   SUBPROCESS_REGISTRY[subprocess.pid] = subprocess;
   subprocess.exited.finally(() => {
     delete SUBPROCESS_REGISTRY[subprocess.pid];

package/src/workspaces/dependencyGraph/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./cycles";
 export * from "./resolveDependencies";
+export * from "./validateDependencyRules";

package/src/workspaces/dependencyGraph/index.mjs

@@ -1,2 +1,3 @@
 export * from "./cycles.mjs";
-export * from "./resolveDependencies.mjs"; // CONCATENATED MODULE: ./src/workspaces/dependencyGraph/index.ts
+export * from "./resolveDependencies.mjs";
+export * from "./validateDependencyRules.mjs"; // CONCATENATED MODULE: ./src/workspaces/dependencyGraph/index.ts

package/src/workspaces/dependencyGraph/validateDependencyRules.d.ts

@@ -0,0 +1,7 @@
+import type { WorkspaceMap } from "./resolveDependencies";
+export type ValidateWorkspaceDependencyRulesOptions = {
+  workspaceMap: WorkspaceMap;
+};
+export declare const validateWorkspaceDependencyRules: ({
+  workspaceMap,
+}: ValidateWorkspaceDependencyRulesOptions) => void;