Merge branch 'main' into fix/normalize-cli-command-quotes

Author: gustavohenke

README.md

@@ -97,20 +97,22 @@ Check out documentation and other usage examples in the [`docs` directory](./doc
 - `options` (optional): an object containing any of the below:
   - `cwd`: the working directory to be used by all commands. Can be overridden per command.
     Default: `process.cwd()`.
+  - `shell`: shell executable used to run command strings. When unset, uses `npm_config_script_shell` if present (for example when run via `npm run`), otherwise `cmd.exe` on Windows or `/bin/sh` elsewhere. See [shell resolution](./docs/shell-resolution.md).
   - `defaultInputTarget`: the default input target when reading from `inputStream`.
     Default: `0`.
   - `handleInput`: when `true`, reads input from `process.stdin`.
-  - `inputStream`: a [`Readable` stream](https://nodejs.org/dist/latest-v10.x/docs/api/stream.html#stream_readable_streams)
+  - `inputStream`: a [`Readable` stream](https://nodejs.org/docs/latest/api/stream.html#readable-streams)
     to read the input from. Should only be used in the rare instance you would like to stream anything other than `process.stdin`. Overrides `handleInput`.
   - `pauseInputStreamOnFinish`: by default, pauses the input stream (`process.stdin` when `handleInput` is enabled, or `inputStream` if provided) when all of the processes have finished. If you need to read from the input stream after `concurrently` has finished, set this to `false`. ([#252](https://github.com/kimmobrunfeldt/concurrently/issues/252)).
   - `killOthersOn`: once the first command exits with one of these statuses, kill other commands.
     Can be an array containing the strings `success` (status code zero) and/or `failure` (non-zero exit status).
   - `maxProcesses`: how many processes should run at once.
-  - `outputStream`: a [`Writable` stream](https://nodejs.org/dist/latest-v10.x/docs/api/stream.html#stream_writable_streams)
+  - `outputStream`: a [`Writable` stream](https://nodejs.org/docs/latest/api/stream.html#writable-streams)
     to write logs to. Default: `process.stdout`.
   - `prefix`: the prefix type to use when logging processes output.
     Possible values: `index`, `pid`, `time`, `command`, `name`, `none`, or a template (eg `[{time} process: {pid}]`).
     Default: the name of the process, or its index if no name is set.
+    Templates can wrap any portion of the prefix with `{color}` and `{/color}` to restrict coloring to that region (eg `[{color}{name}{/color}]` colors only the name, leaving the brackets uncolored). If either marker is omitted the missing side is implicit, so a template with no markers is colored in full.
   - `prefixColors`: a list of colors or a string as supported by [Chalk](https://www.npmjs.com/package/chalk) and additional style `auto` for an automatically picked color.
     Supports all Chalk color functions: `#RRGGBB`, `bg#RRGGBB`, `hex()`, `bgHex()`, `rgb()`, `bgRgb()`, `ansi256()`, `bgAnsi256()`.
     Functions and modifiers can be chained (e.g., `rgb(255,136,0).bold`, `black.bgHex(#00FF00).dim`).
@@ -221,16 +223,16 @@ It contains the following properties:
 
 ## FAQ
 
-- Process exited with code _null_?
+- Process exited with code `null`?
 
-  From [Node child_process documentation](http://nodejs.org/api/child_process.html#child_process_event_exit), `exit` event:
+  From [Node child_process documentation](https://nodejs.org/docs/latest/api/child_process.html#event-exit), `exit` event:
 
   > This event is emitted after the child process ends. If the process
   > terminated normally, code is the final exit code of the process,
   > otherwise null. If the process terminated due to receipt of a signal,
   > signal is the string name of the signal, otherwise null.
 
-  So _null_ means the process didn't terminate normally. This will make **concurrently**
+  So `null` means the process didn't terminate normally. This will make **concurrently**
   to return non-zero exit code too.
 
 - Does this work with the npm-replacements [yarn](https://yarnpkg.com/), [pnpm](https://pnpm.io/), or [Bun](https://bun.sh/)?

bin/index.spec.ts

@@ -58,6 +58,9 @@ const run = (args: string, ctrlcWrapper?: boolean) => {
         cwd: __dirname,
         env: {
             ...process.env,
+            // VS Code extension might allow colors, but this breaks assertions.
+            // Force colors to be disabled to avoid that.
+            FORCE_COLOR: '0',
         },
     });
 
@@ -294,15 +297,6 @@ describe('--names', () => {
             expect(lines).toContainEqual(expect.stringContaining('[bar] bar'));
         });
     });
-
-    it('is split using --name-separator arg', async () => {
-        const lines = await run(
-            '--names "foo|bar" --name-separator "|" "echo foo" "echo bar"',
-        ).getLogLines();
-
-        expect(lines).toContainEqual(expect.stringContaining('[foo] foo'));
-        expect(lines).toContainEqual(expect.stringContaining('[bar] bar'));
-    });
 });
 
 describe('specifies custom prefix', () => {

bin/index.ts

@@ -4,7 +4,6 @@ import process from 'node:process';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
-import { assertDeprecated } from '../lib/assert.js';
 import * as defaults from '../lib/defaults.js';
 import { concurrently } from '../lib/index.js';
 import { castArray, splitOutsideParens } from '../lib/utils.js';
@@ -47,12 +46,6 @@ const program = yargs(hideBin(process.argv))
                 'Example names: "main,browser,server"',
             type: 'string',
         },
-        'name-separator': {
-            describe:
-                'The character to split <names> on. Example usage:\n' +
-                '-n "styles|scripts|server" --name-separator "|"',
-            default: defaults.nameSeparator,
-        },
         success: {
             alias: 's',
             describe:
@@ -97,6 +90,11 @@ const program = yargs(hideBin(process.argv))
             type: 'boolean',
             default: defaults.timings,
         },
+        shell: {
+            describe:
+                'Shell to run commands with. Defaults to cmd.exe on Windows and /bin/sh elsewhere.',
+            type: 'string',
+        },
         'passthrough-arguments': {
             alias: 'P',
             describe:
@@ -210,7 +208,7 @@ const program = yargs(hideBin(process.argv))
         },
     })
     .group(
-        ['m', 'n', 'name-separator', 's', 'r', 'no-color', 'hide', 'g', 'timings', 'P', 'teardown'],
+        ['m', 'n', 's', 'r', 'no-color', 'hide', 'g', 'timings', 'shell', 'P', 'teardown'],
         'General',
     )
     .group(['p', 'c', 'l', 't', 'pad-prefix'], 'Prefix styling')
@@ -220,14 +218,8 @@ const program = yargs(hideBin(process.argv))
     .epilogue(epilogue);
 
 const args = program.parseSync();
-assertDeprecated(
-    args.nameSeparator === defaults.nameSeparator,
-    'name-separator',
-    'Use commas as name separators instead.',
-);
 
-// Get names of commands by the specified separator
-const names = (args.names || '').split(args.nameSeparator);
+const names = (args.names || '').split(',');
 
 const additionalArguments = castArray(args['--'] ?? []).map(String);
 const commands = args.passthroughArguments ? args._ : args._.concat(additionalArguments);
@@ -266,6 +258,7 @@ concurrently(
         successCondition: args.success,
         timestampFormat: args.timestampFormat,
         timings: args.timings,
+        shell: args.shell,
         teardown: args.teardown,
         additionalArguments: args.passthroughArguments ? additionalArguments : undefined,
     },

docs/README.md

@@ -1,5 +1,11 @@
 # Concurrently Documentation
 
+## General
+
+These articles apply when using either concurrently's CLI or API:
+
+- [Shell Resolution](./shell-resolution.md)
+
 ## CLI
 
 These articles cover using concurrently through CLI:

docs/cli/prefixing.md

@@ -56,10 +56,10 @@ $ concurrently --prefix '{index}-{pid}' 'echo Hello there' 'echo General Kenobi!
 
 ## Prefix Colors
 
-By default, there are no colors applied to concurrently prefixes, and they just use whatever the terminal's defaults are.
+By default, concurrently automatically assigns colors to each command's prefix, cycling through `cyan`, `magenta`, `green`, `yellow`, and `blue` (the same palette and order used by turborepo).
 
 This can be changed by using the `--prefix-colors`/`-c` flag, which takes a comma-separated list of colors to use.<br/>
-The available values are color names (e.g. `green`, `magenta`, `gray`, etc), a hex value (such as `#23de43`), or `auto`, to automatically select a color.
+The available values are color names (e.g. `green`, `magenta`, `gray`, etc), a hex value (such as `#23de43`), `auto` to automatically select a color, or `reset` to disable coloring.
 
 ```bash
 $ concurrently -c red,blue 'echo Hello there' 'echo General Kenobi!'
@@ -146,6 +146,18 @@ $ concurrently -c 'rgb(255,136,0).bold,black.bgRgb(100,100,255)' 'echo Orange' '
 $ concurrently -c 'ansi256(199),ansi256(50).bgAnsi256(17)' 'echo Pink' 'echo Cyan on blue'
 ```
 
+### Scoping the Color to Part of a Template
+
+By default, the entire prefix is colored. When using a template, you can restrict coloring to a specific region by wrapping it with the `{color}` and `{/color}` markers — anything outside the markers is rendered without color.
+
+```bash
+$ concurrently -c red,blue --prefix '[{color}{name}{/color}] {pid}' --names one,two 'echo Hello there' 'echo General Kenobi!'
+```
+
+In the example above, only `one` and `two` are colored — the surrounding brackets and the PID stay in the terminal's default color.
+
+If only one of the markers is present, the missing side is implicit: an `{color}` without a matching `{/color}` colors everything from the opener to the end of the prefix, and a `{/color}` without a preceding `{color}` colors everything from the start of the prefix up to the closer. A template with neither marker is colored in full, matching the previous behavior.
+
 ## Prefix Length
 
 When using the `command` prefix style, it's possible that it'll be too long.<br/>

docs/shell-resolution.md

@@ -0,0 +1,48 @@
+# Shell Resolution
+
+Each command runs inside a shell, not as a bare executable.
+By default, concurrently uses `cmd.exe` on Windows and `/bin/sh` elsewhere.
+
+## Using a different shell
+
+If the default shell isn't suitable, it's possible to instruct concurrently to use a specific shell in a few ways.
+
+This is useful, for example, to use Unix-style syntax (for example `BROWSER=none npm start`) on Windows, if you set concurrently shell to e.g. Git Bash.
+
+### Via explicit override
+
+An explicit shell override takes precedence over every other configuration.
+To do that, pass the `--shell` flag to the CLI:
+
+```bash
+concurrently --shell "C:\Program Files\Git\bin\bash.exe" "echo Hello world | xargs -n 1 echo"
+```
+
+Or via the API:
+
+```js
+concurrently(['echo Hello world | xargs -n 1 echo'], {
+  shell: 'C:\\Program Files\\Git\\bin\\bash.exe',
+});
+```
+
+### Via npm/pnpm/yarn v1
+
+When using npm, pnpm or yarn v1 to run concurrently via a `package.json` script, the
+[`script-shell` configuration](https://docs.npmjs.com/cli/v6/using-npm/config#script-shell) is inherited and used to spawn commands.
+
+```bash
+npm config set script-shell /bin/bash
+npm dev # Runs the dev script on bash. Concurrently will also run commands using bash.
+```
+
+## Supported shells
+
+If you've specified a different shell, concurrently detects its kind and spawns commands
+using the right syntax for that shell.
+
+The following shell types are supported:
+
+- Windows `cmd.exe`
+- Powershell
+- Any POSIX compliant shells (bash, zsh, dash, etc)

lib/concurrently.ts

@@ -22,11 +22,11 @@ import { FlowController } from './flow-control/flow-controller.js';
 import { Logger } from './logger.js';
 import { OutputWriter } from './output-writer.js';
 import { PrefixColorSelector } from './prefix-color-selector.js';
-import { getSpawnOpts, spawn } from './spawn.js';
+import { createSpawn, getSpawnOpts } from './spawn.js';
 import { castArray } from './utils.js';
 
 const defaults: ConcurrentlyOptions = {
-    spawn,
+    spawn: createSpawn(),
     kill: treeKill,
     raw: false,
     controllers: [],

lib/defaults.ts

@@ -21,11 +21,6 @@ export const maxProcesses = 0;
  */
 export const hide = '';
 
-/**
- * The character to split <names> on.
- */
-export const nameSeparator = ',';
-
 /**
  * Which prefix style to use when logging processes output.
  */
@@ -35,7 +30,7 @@ export const prefix = '';
  * Default prefix color.
  * @see https://www.npmjs.com/package/chalk
  */
-export const prefixColors = 'reset';
+export const prefixColors = 'auto';
 
 /**
  * How many bytes we'll show on the command prefix.

lib/flow-control/logger-padding.spec.ts

@@ -42,6 +42,15 @@ it('sets prefix length to the longest prefix of all commands', () => {
     expect(logger.setPrefixLength).toHaveBeenCalledWith(6);
 });
 
+it('ignores color markers when measuring prefix length', () => {
+    logger.getPrefixContent
+        .mockReturnValueOnce({ type: 'template', value: '{color}foo{/color}' })
+        .mockReturnValueOnce({ type: 'template', value: '{color}abcd{/color}' });
+
+    controller.handle(commands);
+    expect(logger.setPrefixLength).toHaveBeenCalledWith(4);
+});
+
 it('does not shorten the prefix length', () => {
     logger.getPrefixContent
         .mockReturnValueOnce({ type: 'default', value: '100' })

lib/flow-control/logger-padding.ts

@@ -1,7 +1,11 @@
 import { Command } from '../command.js';
-import { Logger } from '../logger.js';
+import { COLOR_MARKER_RE, Logger } from '../logger.js';
 import { FlowController } from './flow-controller.js';
 
+function visibleLength(value: string | undefined): number {
+    return value ? value.replace(COLOR_MARKER_RE, '').length : 0;
+}
+
 export class LoggerPadding implements FlowController {
     private readonly logger: Logger;
 
@@ -14,7 +18,7 @@ export class LoggerPadding implements FlowController {
         // Compute the prefix length now, which works for all styles but those with a PID.
         let length = commands.reduce((length, command) => {
             const content = this.logger.getPrefixContent(command);
-            return Math.max(length, content?.value.length || 0);
+            return Math.max(length, visibleLength(content?.value));
         }, 0);
         this.logger.setPrefixLength(length);
 
@@ -25,7 +29,7 @@ export class LoggerPadding implements FlowController {
             command.timer.subscribe((event) => {
                 if (!event.endDate) {
                     const content = this.logger.getPrefixContent(command);
-                    length = Math.max(length, content?.value.length || 0);
+                    length = Math.max(length, visibleLength(content?.value));
                     this.logger.setPrefixLength(length);
                 }
             }),