# process

Starting commands that are `.cmd` shims on Windows, such as `npm`, `npx`, `pnpm` and `yarn`, the same way on every platform.

Node refuses to start a `.cmd` file without a shell, and with a shell it joins an argument array without escaping it and prints the [`DEP0190`](https://nodejs.org/api/deprecations.html#DEP0190) deprecation. [`shimCommand`](https://www.hyperfrontend.dev/docs/libraries/project-scope/core/process/#api-shimCommand) returns the program, arguments and [`shell`](https://www.hyperfrontend.dev/docs/libraries/project-scope/core/process/#api-ShimCommand-prop-shell) option to spread into [`execFileSync`](https://nodejs.org/api/child_process.html#child_processexecfilesyncfile-args-options), [`execFile`](https://nodejs.org/api/child_process.html#child_processexecfilefile-args-options-callback), [`spawn`](https://nodejs.org/api/child_process.html#child_processspawncommand-args-options) or [`spawnSync`](https://nodejs.org/api/child_process.html#child_processspawnsynccommand-args-options): on Windows one command line with every argument passed through [`quoteForCmd`](https://www.hyperfrontend.dev/docs/libraries/project-scope/core/process/#api-quoteForCmd) and no argument array, elsewhere the command and its arguments as given with no shell. An argument holding `"`, `%`, `!` or a line break is refused on Windows, because the shim's batch file expands or splits those whatever the quoting.

```typescript
import { execFileSync } from 'node:child_process'
import { shimCommand } from '@hyperfrontend/project-scope/core/process'

const npm = shimCommand('npm', ['install', 'C:\\My Packages\\lib.tgz'])
execFileSync(npm.file, npm.args, { cwd: consumerDir, shell: npm.shell })
```

## API Reference

### Functions

#### quoteForCmd

```typescript
function quoteForCmd(argument: string): string
```

Quotes one argument for a command line that `cmd.exe` reads before handing it to a `.cmd` shim:
an argument holding anything but word characters and `- . / : = @ + \` is wrapped in double
quotes, a trailing run of backslashes is doubled so it does not escape the closing quote, and
every character `cmd.exe` interprets, the quotes included, is escaped with `^`. The program
receives the argument as written.

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `argument` | `string` | One argument of the command |

**Returns** `string`: The argument as it is written into the command line

**Example: Quoting a path with a space and an ampersand**

```typescript
quoteForCmd('--save-dev') // => '--save-dev'
quoteForCmd('C:\\Tom & Jerry\\lib.tgz') // => '^"C:\\Tom^ ^&^ Jerry\\lib.tgz^"'
```

#### shimCommand

```typescript
function shimCommand(command: string, args: unknown, platform: Platform): ShimCommand
```

How to start `npm`, `npx`, `pnpm`, `yarn` or any other command that is a `.cmd` shim on
Windows. Node refuses to start a `.cmd` file without a shell, and with one it joins an argument
array unescaped and prints `DEP0190`, so on Windows the arguments are quoted for `cmd.exe` and
joined into one command line passed with no array. Everywhere else the command starts directly
with its arguments as given.

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `command` | `string` | The shim's name, such as `npm` |
| `args` | `unknown` | Its arguments |
| `platform` | `Platform` | The platform it starts on, this one by default (default: `process.platform`) |

**Returns** `ShimCommand`: The program, arguments and `shell` option to spawn it with

**Example: Packing a package on every platform**

```typescript
import { execFileSync } from 'node:child_process'

const npm = shimCommand('npm', ['pack', '--json'])
execFileSync(npm.file, npm.args, { cwd: packageDir, shell: npm.shell })
// on Windows npm.file is 'npm pack --json', npm.args is [] and npm.shell is true
```

### Interfaces

#### ShimCommand

How to start a command that is a `.cmd` shim on Windows: the values to spread into
`execFileSync`, `execFile`, `spawn` or `spawnSync` from `node:child_process`.

**Properties**

| Name | Type | Description |
| --- | --- | --- |
| `readonly file` | `string` | The program, or on Windows the whole command line with its arguments quoted for `cmd.exe`. |
| `readonly args` | `unknown` | The arguments, or none on Windows, where they are already part of the line. |
| `readonly shell` | `boolean` | Whether the command starts through the platform shell: only on Windows. |

---

Canonical page: https://www.hyperfrontend.dev/docs/libraries/project-scope/core/process/
This file: https://www.hyperfrontend.dev/docs/libraries/project-scope/core/process.md
Documentation index: https://www.hyperfrontend.dev/llms.txt