powershell-utils 0.1.0

package/index.d.ts

@@ -0,0 +1,122 @@
+import type {ExecFileOptions} from 'node:child_process';
+
+export type ExecutePowerShellOptions = ExecFileOptions & {
+	/**
+	Path to PowerShell executable.
+
+	@default powerShellPath()
+	*/
+	readonly powerShellPath?: string;
+};
+
+export type ExecutePowerShellResult = {
+	readonly stdout: string;
+	readonly stderr: string;
+};
+
+/**
+Get the PowerShell executable path on Windows.
+
+@returns The path to the PowerShell executable.
+
+@example
+```
+import {powerShellPath} from 'powershell-utils';
+
+const psPath = powerShellPath();
+//=> 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'
+```
+*/
+export function powerShellPath(): string;
+
+/**
+Check if PowerShell is accessible on Windows.
+
+This checks if the PowerShell executable exists and has execute permissions. Useful for detecting restricted environments where PowerShell may be disabled by administrators.
+
+@returns A promise that resolves to true if PowerShell is accessible, false otherwise.
+
+@example
+```
+import {canAccessPowerShell} from 'powershell-utils';
+
+if (await canAccessPowerShell()) {
+	console.log('PowerShell is available');
+} else {
+	console.log('PowerShell is not accessible');
+}
+```
+*/
+export function canAccessPowerShell(): Promise<boolean>;
+
+/**
+Execute a PowerShell command.
+
+@param command - The PowerShell command to execute.
+@returns A promise that resolves to the command output.
+
+@example
+```
+import {executePowerShell} from 'powershell-utils';
+
+const {stdout} = await executePowerShell('Get-Process');
+console.log(stdout);
+```
+*/
+export function executePowerShell(
+	command: string,
+	options?: ExecutePowerShellOptions
+): Promise<ExecutePowerShellResult>;
+
+export namespace executePowerShell {
+	/**
+	Standard PowerShell arguments that prefix the encoded command.
+
+	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_);
+	```
+	*/
+	export const argumentsPrefix: readonly string[];
+
+	/**
+	Encode a PowerShell command as Base64 UTF-16LE.
+
+	This encoding prevents shell escaping issues and ensures complex commands with special characters are executed reliably.
+
+	@param command - The PowerShell command to encode.
+	@returns Base64-encoded command.
+
+	@example
+	```
+	import {executePowerShell} from 'powershell-utils';
+
+	const encoded = executePowerShell.encodeCommand('Get-Process');
+	```
+	*/
+	export function encodeCommand(command: string): string;
+
+	/**
+	Escape a string argument for use in PowerShell single-quoted strings.
+
+	@param value - The value to escape.
+	@returns Escaped and quoted string ready for PowerShell.
+
+	@example
+	```
+	import {executePowerShell} from 'powershell-utils';
+
+	const escaped = executePowerShell.escapeArgument("it's a test");
+	//=> "'it''s a test'"
+
+	// Use in command building
+	const command = `Start-Process ${executePowerShell.escapeArgument(appName)}`;
+	```
+	*/
+	export function escapeArgument(value: unknown): string;
+}

package/index.js

@@ -0,0 +1,58 @@
+import process from 'node:process';
+import {Buffer} from 'node:buffer';
+import {promisify} from 'node:util';
+import childProcess from 'node:child_process';
+import fs, {constants as fsConstants} from 'node:fs/promises';
+
+const execFile = promisify(childProcess.execFile);
+
+export const powerShellPath = () => `${process.env.SYSTEMROOT || process.env.windir || String.raw`C:\Windows`}\\System32\\WindowsPowerShell\\v1.0\\powershell.exe`;
+
+// Cache for PowerShell accessibility check
+let canAccessCache;
+
+export const canAccessPowerShell = async () => {
+	canAccessCache ??= (async () => {
+		try {
+			await fs.access(powerShellPath(), fsConstants.X_OK);
+			return true;
+		} catch {
+			return false;
+		}
+	})();
+
+	return canAccessCache;
+};
+
+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,
+		},
+	);
+};
+
+executePowerShell.argumentsPrefix = [
+	'-NoProfile',
+	'-NonInteractive',
+	'-ExecutionPolicy',
+	'Bypass',
+	'-EncodedCommand',
+];
+
+executePowerShell.encodeCommand = command => Buffer.from(command, 'utf16le').toString('base64');
+
+executePowerShell.escapeArgument = value => `'${String(value).replaceAll('\'', '\'\'')}'`;

package/license

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -0,0 +1,47 @@
+{
+	"name": "powershell-utils",
+	"version": "0.1.0",
+	"description": "Utilities for executing PowerShell commands",
+	"license": "MIT",
+	"repository": "sindresorhus/powershell-utils",
+	"funding": "https://github.com/sponsors/sindresorhus",
+	"author": {
+		"name": "Sindre Sorhus",
+		"email": "sindresorhus@gmail.com",
+		"url": "https://sindresorhus.com"
+	},
+	"type": "module",
+	"exports": {
+		"types": "./index.d.ts",
+		"default": "./index.js"
+	},
+	"sideEffects": false,
+	"engines": {
+		"node": ">=20"
+	},
+	"scripts": {
+		"test": "xo && ava && tsc index.d.ts --skipLibCheck"
+	},
+	"files": [
+		"index.js",
+		"index.d.ts"
+	],
+	"keywords": [
+		"powershell",
+		"windows",
+		"execute",
+		"command",
+		"shell",
+		"console",
+		"terminal",
+		"cli",
+		"spawn",
+		"exec",
+		"utilities"
+	],
+	"devDependencies": {
+		"ava": "^6.4.1",
+		"typescript": "^5.9.3",
+		"xo": "^0.59.0"
+	}
+}

package/readme.md

@@ -0,0 +1,153 @@
+# powershell-utils
+
+> Utilities for executing PowerShell commands
+
+## Install
+
+```sh
+npm install powershell-utils
+```
+
+## Usage
+
+```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'
+```
+
+## API
+
+### powerShellPath()
+
+Returns: `string`
+
+Get the PowerShell executable path on Windows.
+
+```js
+import {powerShellPath} from 'powershell-utils';
+
+const psPath = powerShellPath();
+//=> 'C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe'
+```
+
+### canAccessPowerShell()
+
+Returns: `Promise<boolean>`
+
+Check if PowerShell is accessible on Windows.
+
+This checks if the PowerShell executable exists and has execute permissions. Useful for detecting restricted environments where PowerShell may be disabled by administrators.
+
+```js
+import {canAccessPowerShell} from 'powershell-utils';
+
+if (await canAccessPowerShell()) {
+	console.log('PowerShell is available');
+} else {
+	console.log('PowerShell is not accessible');
+}
+```
+
+### executePowerShell(command, options?)
+
+Returns: `Promise<{stdout: string, stderr: string}>`
+
+Execute a PowerShell command.
+
+```js
+import {executePowerShell} from 'powershell-utils';
+
+// Execute a PowerShell command
+const {stdout} = await executePowerShell('Get-Process');
+console.log(stdout);
+```
+
+#### command
+
+Type: `string`
+
+The PowerShell command to execute.
+
+#### options
+
+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.
+
+##### powerShellPath
+
+Type: `string`\
+Default: `powerShellPath()`
+
+Path to PowerShell executable. Useful when calling from WSL or when PowerShell is in a non-standard location.
+
+##### encoding
+
+Type: `string`\
+Default: `'utf8'`
+
+Character encoding for stdout and stderr.
+
+### executePowerShell.argumentsPrefix
+
+Type: `string[]`
+
+Standard PowerShell arguments that prefix the encoded command.
+
+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_);
+```
+
+### executePowerShell.encodeCommand(command)
+
+Returns: `string`
+
+Encode a PowerShell command as Base64 UTF-16LE.
+
+This encoding prevents shell escaping issues and ensures complex commands with special characters are executed reliably.
+
+#### command
+
+Type: `string`
+
+The PowerShell command to encode.
+
+```js
+import {executePowerShell} from 'powershell-utils';
+
+const encoded = executePowerShell.encodeCommand('Get-Process');
+```
+
+### executePowerShell.escapeArgument(value)
+
+Returns: `string`
+
+Escape a string argument for use in PowerShell single-quoted strings.
+
+#### value
+
+Type: `unknown`
+
+The value to escape.
+
+```js
+import {executePowerShell} from 'powershell-utils';
+
+const escaped = executePowerShell.escapeArgument("it's a test");
+//=> "'it''s a test'"
+
+// Use in command building
+const command = `Start-Process ${executePowerShell.escapeArgument(appName)}`;
+```