printable-shell-command 0.1.0

package/Makefile

@@ -0,0 +1,7 @@
+.PHONY: lint
+lint:
+	bun x @biomejs/biome check
+
+.PHONY: format
+format:
+	bun x @biomejs/biome check --write

package/README.md

@@ -0,0 +1,78 @@
+# `printable-shell-command`
+
+A helper class to construct shell command in a way that allows printing them.
+
+The goal is to make it easy to print commands that are bring run by a program, in a way that makes it easy and safe for a user to copy-and-paste.
+
+Goals:
+
+1. Security — the printed commands should be possible to use in all shells without injection vulnerabilities.
+2. Fidelity — The printed command must match the arguments provided.
+3.
+
+Point 1 is difficult, and maybe even impossible. This library will do its best, but what you don't know can hurt you.
+
+## Usage
+
+Construct a command by providing a command string and a list of arguments. Each argument can either be an individual string, or a "pair" list containing two strings (usually a command flag and its argument). Pairs do not affect the semantics of the command, but they affect pretty-printing.
+
+```typescript
+import { PrintableShellCommand } from "printable-shell-command";
+
+const command = new PrintableShellCommand("ffmpeg", [
+  ["-i", "./test/My video.mp4"],
+  ["-filter:v", "setpts=2.0*PTS"],
+  ["-filter:a", "atempo=0.5"],
+  "./test/My video (slow-mo).mov",
+]);
+
+command.print();
+```
+
+### In `node`
+
+```typescript
+import { spawn } from "node:child_process";
+
+// Note the `...`
+const child_process = spawn(...command.toCommandWithFlatArgs());
+```
+
+### With `bun`
+
+```typescript
+import { spawn } from "bun";
+
+await spawn({ cmd: command.toFlatCommand() }).exited;
+```
+
+## Protections
+
+Any command or argument containing the following characters is quoted and escaped:
+
+- space character
+- `"`
+- `'`
+- `\``
+- `|`
+- `$`
+- `*`
+- `?`
+- `>`
+- `<`
+- `(`
+- `)`
+- `[`
+- `]`
+- `{`
+- `}`
+- `&`
+- `\`
+- `;`
+
+Additionally, a command is escaped if it contains an `=`.
+
+Escaping is done as follows:
+
+- The command is single-quoted.
+- Backslashes and single quotes are escaped.

package/biome.json

@@ -0,0 +1,12 @@
+{
+	"$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
+	"files": {
+		"ignore": ["./dist", "./package.json", "./target"]
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true
+		}
+	}
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+	"name": "printable-shell-command",
+	"version": "v0.1.0",
+	"main": "./src/index.ts",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./src/index.ts",
+			"import": "./src/index.ts"
+		}
+	},
+	"dependencies": {
+		"@biomejs/biome": "^1.9.4",
+		"@types/bun": "^1.1.14",
+		"@types/node": "^22.10.2"
+	}
+}

package/src/index.ts

@@ -0,0 +1,160 @@
+const INLINE_SEPARATOR = " ";
+const LINE_WRAP_SEPARATOR = " \\\n  ";
+
+// biome-ignore lint/suspicious/noExplicitAny: This is the correct type nere.
+function isString(s: any): s is string {
+	return typeof s === "string";
+}
+
+// TODO: allow `.toString()`ables?
+type SingleArgument = string;
+type FlagArgumentPair = [string, string];
+type ArgsEntry = SingleArgument | FlagArgumentPair;
+type Args = ArgsEntry[];
+
+export interface PrintOptions {
+	mainIndentation?: string; // Defaults to ""
+	argIndentation?: string; // Defaults to "  "
+	// - "auto": Quote only arguments that need it for safety. This tries to be
+	//   portable and safe across shells, but true safety and portability is hard
+	//   to guarantee.
+	// - "extra-safe": Quote all arguments, even ones that don't need it. This is
+	//   more likely to be safe under all circumstances.
+	quoting?: "auto" | "extra-safe";
+	lineWrap?: "none" | "by-entry";
+}
+
+// https://mywiki.wooledge.org/BashGuide/SpecialCharacters
+const SPECIAL_SHELL_CHARACTERS = new Set([
+	" ",
+	'"',
+	"'",
+	"`",
+	"|",
+	"$",
+	"*",
+	"?",
+	">",
+	"<",
+	"(",
+	")",
+	"[",
+	"]",
+	"{",
+	"}",
+	"&",
+	"\\",
+	";",
+]);
+
+// https://mywiki.wooledge.org/BashGuide/SpecialCharacters
+const SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND =
+	SPECIAL_SHELL_CHARACTERS.union(new Set(["="]));
+
+export class PrintableShellCommand {
+	constructor(
+		private commandName: string,
+		private args: Args = [],
+	) {
+		if (!isString(commandName)) {
+			// biome-ignore lint/suspicious/noExplicitAny: We want to print this, no matter what it is.
+			throw new Error("Command name is not a string:", commandName as any);
+		}
+		if (typeof args === "undefined") {
+			return;
+		}
+		if (!Array.isArray(args)) {
+			throw new Error("Command arguments are not an array");
+		}
+		for (let i = 0; i < args.length; i++) {
+			const argEntry = args[i];
+			if (typeof argEntry === "string") {
+				continue;
+			}
+			if (
+				Array.isArray(argEntry) &&
+				argEntry.length === 2 &&
+				isString(argEntry[0]) &&
+				isString(argEntry[1])
+			) {
+				continue;
+			}
+			throw new Error(`Invalid arg entry at index: ${i}`);
+		}
+	}
+
+	public toFlatCommand(): string[] {
+		return [this.commandName, ...this.args.flat()];
+	}
+
+	// For use with `node:child_process`
+	public toCommandWithFlatArgs(): [string, string[]] {
+		return [this.commandName, this.args.flat()];
+	}
+
+	#escapeArg(
+		arg: string,
+		isMainCommand: boolean,
+		options: PrintOptions,
+	): string {
+		const argCharacters = new Set(arg);
+		const specialShellCharacters = isMainCommand
+			? SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND
+			: SPECIAL_SHELL_CHARACTERS;
+		if (
+			options?.quoting === "extra-safe" ||
+			argCharacters.intersection(specialShellCharacters).size > 0
+		) {
+			// Use single quote to reduce the need to escape (and therefore reduce the chance for bugs/security issues).
+			const escaped = arg.replaceAll("\\", "\\\\").replaceAll("'", "\\'");
+			return `'${escaped}'`;
+		}
+		return arg;
+	}
+
+	#smallIndent(s: string, options?: PrintOptions): string {
+		return (options?.mainIndentation ?? "") + s;
+	}
+
+	#bigIndent(s: string, options?: PrintOptions): string {
+		return this.#smallIndent((options?.argIndentation ?? "  ") + s, options);
+	}
+
+	public getPrintableCommand(options?: PrintOptions): string {
+		const lines: string[] = [];
+
+		lines.push(
+			this.#smallIndent(
+				this.#escapeArg(this.commandName, true, options),
+				options,
+			),
+		);
+
+		// let pendingNewlineAfterPart = options?.separateLines === "dash-heuristic";
+		for (let i = 0; i < this.args.length; i++) {
+			const argsEntry = this.args[i];
+
+			if (isString(argsEntry)) {
+				lines.push(
+					this.#bigIndent(this.#escapeArg(argsEntry, false, options), options),
+				);
+			} else {
+				const [part1, part2] = argsEntry;
+
+				lines.push(
+					this.#bigIndent(
+						this.#escapeArg(part1, false, options) +
+							INLINE_SEPARATOR +
+							this.#escapeArg(part2, false, options),
+						options,
+					),
+				);
+			}
+		}
+		return lines.join(LINE_WRAP_SEPARATOR);
+	}
+
+	public print(options?: PrintOptions): void {
+		console.log(this.getPrintableCommand(options));
+	}
+}

package/test/simple-test-bun.ts

@@ -0,0 +1,12 @@
+import { spawn } from "bun";
+import { PrintableShellCommand } from "../src";
+
+const command = new PrintableShellCommand("ffmpeg", [
+	["-i", "./test/My video.mp4"],
+	["-filter:v", "setpts=2.0*PTS"],
+	["-filter:a", "atempo=0.5"],
+	"./test/My video (slow-mo).mov",
+]);
+
+command.print();
+await spawn({ cmd: command.toFlatCommand() }).exited;

package/test/simple-test-node.ts

@@ -0,0 +1,14 @@
+import { spawn } from "node:child_process";
+import { PrintableShellCommand } from "../src";
+
+const command = new PrintableShellCommand("ffmpeg", [
+	["-i", "./test/My video.mp4"],
+	["-filter:v", "setpts=2.0*PTS"],
+	["-filter:a", "atempo=0.5"],
+	"./test/My video (slow-mo).mov",
+]);
+
+command.print();
+await new Promise((resolve, reject) => {
+	spawn(...command.toCommandWithFlatArgs()).addListener("exit", resolve);
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+	"compilerOptions": {
+		"lib": ["esnext", "DOM"],
+		"module": "es2022",
+		"target": "es2022",
+		"moduleResolution": "bundler"
+	}
+}