@antora/run-command-helper - npm Package Compare versions

Comparing version 1.0.0-rc.5 to 1.0.0

package.json

 {
   "name": "@antora/run-command-helper",
-  "version": "1.0.0-rc.5",
+  "version": "1.0.0",
   "description": "Provides a helper function to run an external command uniformly across platforms with numerous options to control how stdio is handled.",
@@ -5,0 +5,0 @@ "license": "MPL-2.0",

README.md

 # @antora/run-command-helper
 
-![npm package](https://img.shields.io/npm/v/@antora/run-command-helper.svg)
-![CI Status (GitLab CI)](https://gitlab.com/antora/run-command-helper/badges/main/pipeline.svg)
-
 A Node.js module that provides a helper function to run an external command consistently across platforms.
@@ -96,7 +93,31 @@ This function is a Promise-based wrapper around the spawn function in Node.js.
 
+**📌 NOTE**\
+This function does its own PATHEXT resolution on Windows.
+It never passes an extensionless command to spawn to ensure its behavior is predictable and within the documented parameters.
+
 On Windows, the shell will be used under the covers (even when not specified) to run batch scripts due to a [security restriction in Node.js](https://nodejs.org/en/blog/vulnerability/april-2024-security-releases-2#command-injection-via-args-parameter-of-child_processspawn-without-shell-option-enabled-on-windows-cve-2024-27980---high).
 The function hides this detail by automatically escaping the arguments and thus does not impose additional escaping requirements when the shell option is `false` or not set.
+The function escapes the following characters using a double quote enclosure: `" <>&%^|`.
 
+**🔥 CAUTION**\
+There’s still a risk that a batch script cannot read argument values correctly.
+This is due to limitations in how a batch script processes arguments.
+For example, a batch script could cause a child batch script to not be able to handle the sequence `="&` depending on how arguments are forwarded to the child script.
+
 On Windows, builtins like `dir` and `set` can only be used when `shell: true` (this is a limitation of Node.js’ spawn function).
 
+In order to use non-ASCII characters in argument values on Windows (particularly when using the shell), it may be necessary to [enable UTF-8 support](https://learn.microsoft.com/en-us/windows/apps/design/globalizing/use-utf8-code-page#set-a-process-code-page-to-utf-8).
+Here’s an example to test whether UTF-8 support is properly configured:
+
+```js
+const runCommand = require('@antora/run-command-helper')
+
+;(async () => {
+  await runCommand('echo', ['ACME\u2122'], { stdout: 'print', stderr: 'print', shell: true })
+})()
+//=> ACME™
+```
+
+If that still don’t work, try setting `chcp 65001` as well.
+
 ## Usage
@@ -103,0 +124,0 @@

Fixed alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

39860

increased by2.72%

Number of low quality alerts

0

decreased by-100%

Number of lines in readme file

216

increased by10.77%

No dependency changes