powershell-utils 0.1.0 → 0.2.1

package/index.d.ts

@@ -1,12 +1,31 @@
-import type {ExecFileOptions} from 'node:child_process';
+import type {ExecFileOptions, ExecFileSyncOptions} from 'node:child_process';
 
-export type ExecutePowerShellOptions = ExecFileOptions & {
+export type ExecutePowerShellOptions = Omit<ExecFileOptions, 'shell'> & {
 	/**
 	Path to PowerShell executable.
 
 	@default powerShellPath()
 	*/
 	readonly powerShellPath?: string;
+
+	/**
+	Not supported. PowerShell is always executed directly to prevent shell injection.
+	*/
+	readonly shell?: never;
+};
+
+export type ExecutePowerShellSyncOptions = Omit<ExecFileSyncOptions, 'shell'> & {
+	/**
+	Path to PowerShell executable.
+
+	@default powerShellPath()
+	*/
+	readonly powerShellPath?: string;
+
+	/**
+	Not supported. PowerShell is always executed directly to prevent shell injection.
+	*/
+	readonly shell?: never;
 };
 
 export type ExecutePowerShellResult = {
@@ -70,17 +89,9 @@ export function executePowerShell(
 
 export namespace executePowerShell {
 	/**
-	Standard PowerShell arguments that prefix the encoded command.
+	Standard PowerShell arguments that prefix the encoded command: `['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand']`
 
-	Use these when manually building PowerShell execution arguments for `spawn()`, `execFile()`, etc.
-
-	@example
-	```
-	import {executePowerShell} from 'powershell-utils';
-
-	const arguments_ = [...executePowerShell.argumentsPrefix, encodedCommand];
-	childProcess.spawn(powerShellPath(), arguments_);
-	```
+	Exposed for debugging or for advanced use cases where you need to customize the arguments. For most cases, use `createArguments()` instead.
 	*/
 	export const argumentsPrefix: readonly string[];
 
@@ -104,6 +115,10 @@ export namespace executePowerShell {
 	/**
 	Escape a string argument for use in PowerShell single-quoted strings.
 
+	This makes a value safe as a PowerShell string literal, not as an argument to a native program. PowerShell removes the outer quotes before passing a value onwards, and the receiving process then re-splits it under its own command-line rules, where spaces and double quotes are delimiters. For example, `Start-Process -ArgumentList` receives `'a b'` as two arguments rather than one.
+
+	Escaping also does not make an untrusted value safe to use as the program that `Start-Process` runs. Validate such values against an allowlist.
+
 	@param value - The value to escape.
 	@returns Escaped and quoted string ready for PowerShell.
 
@@ -119,4 +134,42 @@ export namespace executePowerShell {
 	```
 	*/
 	export function escapeArgument(value: unknown): string;
+
+	/**
+	Create the full arguments array for PowerShell execution.
+
+	Combines `argumentsPrefix` with the encoded command. Useful when using `spawn()`, `execFile()`, or other process execution methods.
+
+	@param command - The PowerShell command.
+	@returns Array of arguments ready to pass to a process spawner.
+
+	@example
+	```
+	import {spawn} from 'node:child_process';
+	import {powerShellPath, executePowerShell} from 'powershell-utils';
+
+	const args = executePowerShell.createArguments('Get-Process');
+	spawn(powerShellPath(), args);
+	```
+	*/
+	export function createArguments(command: string): string[];
 }
+
+/**
+Execute a PowerShell command synchronously.
+
+@param command - The PowerShell command to execute.
+@returns The stdout output as a string.
+
+@example
+```
+import {executePowerShellSync} from 'powershell-utils';
+
+const stdout = executePowerShellSync('Get-Process');
+console.log(stdout);
+```
+*/
+export function executePowerShellSync(
+	command: string,
+	options?: ExecutePowerShellSyncOptions
+): string;

package/index.js

@@ -24,35 +24,56 @@ export const canAccessPowerShell = async () => {
 	return canAccessCache;
 };
 
+const argumentsPrefix = [
+	'-NoProfile',
+	'-NonInteractive',
+	'-ExecutionPolicy',
+	'Bypass',
+	'-EncodedCommand',
+];
+
+const encodeCommand = command => Buffer.from(command, 'utf16le').toString('base64');
+
+/*
+PowerShell's tokenizer treats the typographic single quotes U+2018, U+2019, U+201A, and U+201B as string delimiters, exactly like the ASCII one, and it does not require the closing quote to match the opening quote. Escaping only the ASCII quote would let any of the others terminate the string and inject a statement. Doubling works for all of them.
+*/
+const escapeArgument = value => `'${String(value).replaceAll(/['‘’‚‛]/g, match => match + match)}'`;
+
+const createArguments = command => [...argumentsPrefix, encodeCommand(command)];
+
+const createExecFileOptions = options => ({
+	encoding: 'utf8',
+	...options,
+	shell: false,
+});
+
 export const executePowerShell = async (command, options = {}) => {
 	const {
 		powerShellPath: psPath,
 		...execFileOptions
 	} = options;
 
-	const encodedCommand = executePowerShell.encodeCommand(command);
-
 	return execFile(
 		psPath ?? powerShellPath(),
-		[
-			...executePowerShell.argumentsPrefix,
-			encodedCommand,
-		],
-		{
-			encoding: 'utf8',
-			...execFileOptions,
-		},
+		createArguments(command),
+		createExecFileOptions(execFileOptions),
 	);
 };
 
-executePowerShell.argumentsPrefix = [
-	'-NoProfile',
-	'-NonInteractive',
-	'-ExecutionPolicy',
-	'Bypass',
-	'-EncodedCommand',
-];
+executePowerShell.argumentsPrefix = argumentsPrefix;
+executePowerShell.encodeCommand = encodeCommand;
+executePowerShell.escapeArgument = escapeArgument;
+executePowerShell.createArguments = createArguments;
 
-executePowerShell.encodeCommand = command => Buffer.from(command, 'utf16le').toString('base64');
+export const executePowerShellSync = (command, options = {}) => {
+	const {
+		powerShellPath: psPath,
+		...execFileOptions
+	} = options;
 
-executePowerShell.escapeArgument = value => `'${String(value).replaceAll('\'', '\'\'')}'`;
+	return childProcess.execFileSync(
+		psPath ?? powerShellPath(),
+		createArguments(command),
+		createExecFileOptions(execFileOptions),
+	);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "powershell-utils",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"description": "Utilities for executing PowerShell commands",
 	"license": "MIT",
 	"repository": "sindresorhus/powershell-utils",

package/readme.md

@@ -13,11 +13,9 @@ npm install powershell-utils
 ```js
 import {executePowerShell, powerShellPath} from 'powershell-utils';
 
-// Execute a PowerShell command
 const {stdout} = await executePowerShell('Get-Process');
 console.log(stdout);
 
-// Get PowerShell path
 console.log(powerShellPath());
 //=> 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'
 ```
@@ -64,7 +62,6 @@ Execute a PowerShell command.
 ```js
 import {executePowerShell} from 'powershell-utils';
 
-// Execute a PowerShell command
 const {stdout} = await executePowerShell('Get-Process');
 console.log(stdout);
 ```
@@ -79,7 +76,7 @@ The PowerShell command to execute.
 
 Type: `object`
 
-The below option and also all options in Node.js [`child_process.execFile()`](https://nodejs.org/api/child_process.html#child_processexecfilefile-args-options-callback) are supported.
+The below option and all options except `shell` in Node.js [`child_process.execFile()`](https://nodejs.org/api/child_process.html#child_processexecfilefile-args-options-callback) are supported. PowerShell is always executed directly to prevent shell injection.
 
 ##### powerShellPath
 
@@ -99,16 +96,9 @@ Character encoding for stdout and stderr.
 
 Type: `string[]`
 
-Standard PowerShell arguments that prefix the encoded command.
+Standard PowerShell arguments that prefix the encoded command: `['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand']`
 
-Use these when manually building PowerShell execution arguments for `spawn()`, `execFile()`, etc.
-
-```js
-import {executePowerShell} from 'powershell-utils';
-
-const arguments_ = [...executePowerShell.argumentsPrefix, encodedCommand];
-childProcess.spawn(powerShellPath(), arguments_);
-```
+Exposed for debugging or for advanced use cases where you need to customize the arguments. For most cases, use `createArguments()` instead.
 
 ### executePowerShell.encodeCommand(command)
 
@@ -136,6 +126,11 @@ Returns: `string`
 
 Escape a string argument for use in PowerShell single-quoted strings.
 
+> [!IMPORTANT]
+> This makes a value safe as a PowerShell string literal, not as an argument to a native program. PowerShell removes the outer quotes before passing a value onwards, and the receiving process then re-splits it under its own command-line rules, where spaces and double quotes are delimiters. For example, `Start-Process -ArgumentList` receives `'a b'` as two arguments rather than one.
+>
+> Escaping also does not make an untrusted value safe to use as the program that `Start-Process` runs. Validate such values against an allowlist.
+
 #### value
 
 Type: `unknown`
@@ -151,3 +146,64 @@ const escaped = executePowerShell.escapeArgument("it's a test");
 // Use in command building
 const command = `Start-Process ${executePowerShell.escapeArgument(appName)}`;
 ```
+
+### executePowerShell.createArguments(command)
+
+Returns: `string[]`
+
+Create the full arguments array for PowerShell execution.
+
+Combines `argumentsPrefix` with the encoded command. Useful when using `spawn()`, `execFile()`, or other process execution methods.
+
+#### command
+
+Type: `string`
+
+The PowerShell command.
+
+```js
+import {spawn} from 'node:child_process';
+import {powerShellPath, executePowerShell} from 'powershell-utils';
+
+const args = executePowerShell.createArguments('Get-Process');
+spawn(powerShellPath(), args);
+```
+
+### executePowerShellSync(command, options?)
+
+Returns: `string`
+
+Execute a PowerShell command synchronously.
+
+```js
+import {executePowerShellSync} from 'powershell-utils';
+
+const stdout = executePowerShellSync('Get-Process');
+console.log(stdout);
+```
+
+#### command
+
+Type: `string`
+
+The PowerShell command to execute.
+
+#### options
+
+Type: `object`
+
+The below option and all options except `shell` in Node.js [`child_process.execFileSync()`](https://nodejs.org/api/child_process.html#child_processexecfilesyncfile-args-options) are supported. PowerShell is always executed directly to prevent shell injection.
+
+##### powerShellPath
+
+Type: `string`\
+Default: `powerShellPath()`
+
+Path to PowerShell executable.
+
+##### encoding
+
+Type: `string`\
+Default: `'utf8'`
+
+Character encoding for the output.