printable-shell-command 0.1.3 → 0.2.0

package/.github/workflows/CI.yaml

@@ -0,0 +1,14 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v1
+      - run: make setup
+      - run: make lint
+      - run: make test-js

package/Makefile

@@ -1,3 +1,6 @@
+.PHONY: test
+test: lint test-js
+
 .PHONY: lint
 lint: setup
 	bun x @biomejs/biome check
@@ -6,6 +9,10 @@ lint: setup
 format: setup
 	bun x @biomejs/biome check --write
 
+.PHONY: test-js
+test-js: setup
+	bun test
+
 # https://github.com/lgarron/repo
 REPO_COMMANDS = publish
 
@@ -18,3 +25,11 @@ ${REPO_COMMANDS}:
 .PHONY: setup
 setup:
 	bun install --frozen-lockfile
+
+.PHONY: clean
+clean:
+	# No-op
+
+.PHONY: reset
+reset: clean
+	rm -rf ./node_modules

package/README.md

@@ -34,10 +34,10 @@ This prints:
 
 ```shell
 ffmpeg \
-    -i './test/My video.mp4' \
-    -filter:v 'setpts=2.0*PTS' \
-    -filter:a atempo=0.5 \
-    './test/My video (slow-mo).mov'
+  -i './test/My video.mp4' \
+  -filter:v 'setpts=2.0*PTS' \
+  -filter:a atempo=0.5 \
+  './test/My video (slow-mo).mov'
 ```
 
 ### Spawn a process in `node`

package/bun.lock

@@ -3,10 +3,12 @@
   "workspaces": {
     "": {
       "name": "printable-shell-command",
+      "dependencies": {
+        "@types/bun": "^1.2.11",
+        "@types/node": "^22.15.3",
+      },
       "devDependencies": {
         "@biomejs/biome": "^1.9.4",
-        "@types/bun": "^1.1.14",
-        "@types/node": "^22.10.2",
       },
     },
   },
@@ -29,14 +31,16 @@
 
     "@biomejs/cli-win32-x64": ["@biomejs/cli-win32-x64@1.9.4", "", { "os": "win32", "cpu": "x64" }, "sha512-8Y5wMhVIPaWe6jw2H+KlEm4wP/f7EW3810ZLmDlrEEy5KvBsb9ECEfu/kMWD484ijfQ8+nIi0giMgu9g1UAuuA=="],
 
-    "@types/bun": ["@types/bun@1.2.4", "", { "dependencies": { "bun-types": "1.2.4" } }, "sha512-QtuV5OMR8/rdKJs213iwXDpfVvnskPXY/S0ZiFbsTjQZycuqPbMW8Gf/XhLfwE5njW8sxI2WjISURXPlHypMFA=="],
+    "@types/bun": ["@types/bun@1.2.11", "", { "dependencies": { "bun-types": "1.2.11" } }, "sha512-ZLbbI91EmmGwlWTRWuV6J19IUiUC5YQ3TCEuSHI3usIP75kuoA8/0PVF+LTrbEnVc8JIhpElWOxv1ocI1fJBbw=="],
+
+    "@types/node": ["@types/node@22.15.3", "", { "dependencies": { "undici-types": "~6.21.0" } }, "sha512-lX7HFZeHf4QG/J7tBZqrCAXwz9J5RD56Y6MpP0eJkka8p+K0RY/yBTW7CYFJ4VGCclxqOLKmiGP5juQc6MKgcw=="],
 
-    "@types/node": ["@types/node@22.13.9", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-acBjXdRJ3A6Pb3tqnw9HZmyR3Fiol3aGxRCK1x3d+6CDAMjl7I649wpSd+yNURCjbOUGu9tqtLKnTGxmK6CyGw=="],
+    "bun-types": ["bun-types@1.2.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-dbkp5Lo8HDrXkLrONm6bk+yiiYQSntvFUzQp0v3pzTAsXk6FtgVMjdQ+lzFNVAmQFUkPQZ3WMZqH5tTo+Dp/IA=="],
 
-    "@types/ws": ["@types/ws@8.5.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-bd/YFLW+URhBzMXurx7lWByOu+xzU9+kb3RboOteXYDfW+tr+JZa99OyNmPINEGB/ahzKrEuc8rcv4gnpJmxTw=="],
+    "undici-types": ["undici-types@6.21.0", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
 
-    "bun-types": ["bun-types@1.2.4", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-nDPymR207ZZEoWD4AavvEaa/KZe/qlrbMSchqpQwovPZCKc7pwMoENjEtHgMKaAjJhy+x6vfqSBA1QU3bJgs0Q=="],
+    "bun-types/@types/node": ["@types/node@22.13.9", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-acBjXdRJ3A6Pb3tqnw9HZmyR3Fiol3aGxRCK1x3d+6CDAMjl7I649wpSd+yNURCjbOUGu9tqtLKnTGxmK6CyGw=="],
 
-    "undici-types": ["undici-types@6.20.0", "", {}, "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="],
+    "bun-types/@types/node/undici-types": ["undici-types@6.20.0", "", {}, "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="],
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "printable-shell-command",
-	"version": "0.1.3",
+	"version": "0.2.0",
 	"main": "./src/index.ts",
 	"type": "module",
 	"exports": {
@@ -9,9 +9,11 @@
 			"import": "./src/index.ts"
 		}
 	},
+	"dependencies": {
+		"@types/bun": "^1.2.11",
+		"@types/node": "^22.15.3"
+	},
 	"devDependencies": {
-		"@biomejs/biome": "^1.9.4",
-		"@types/bun": "^1.1.14",
-		"@types/node": "^22.10.2"
+		"@biomejs/biome": "^1.9.4"
 	}
 }

package/src/index.ts

@@ -1,5 +1,22 @@
+import type {
+	ChildProcess as NodeChildProcess,
+	SpawnOptionsWithStdioTuple as NodeSpawnOptionsWithStdioTuple,
+	StdioNull as NodeStdioNull,
+	StdioPipe as NodeStdioPipe,
+	SpawnOptions as NodeSpawnOptions,
+SpawnOptionsWithoutStdio as NodeSpawnOptionsWithoutStdio,
+} from "node:child_process";
+import type {
+	SpawnOptions as BunSpawnOptions,
+	Subprocess as BunSubprocess,
+} from "bun";
+
+const DEFAULT_MAIN_INDENTATION = "";
+const DEFAULT_ARG_INDENTATION = "  ";
+const DEFAULT_ARGUMENT_LINE_WRAPPING = "by-entry";
+
 const INLINE_SEPARATOR = " ";
-const LINE_WRAP_SEPARATOR = " \\\n  ";
+const LINE_WRAP_LINE_END = " \\\n";
 
 // biome-ignore lint/suspicious/noExplicitAny: This is the correct type nere.
 function isString(s: any): s is string {
@@ -21,7 +38,12 @@ export interface PrintOptions {
 	// - "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";
+	// Line wrapping to use between arguments. Defaults to `"by-entry"`.
+	argumentLineWrapping?:
+		| "by-entry"
+		| "nested-by-entry"
+		| "by-argument"
+		| "inline";
 }
 
 // https://mywiki.wooledge.org/BashGuide/SpecialCharacters
@@ -150,7 +172,7 @@ export class PrintableShellCommand {
 	#escapeArg(
 		arg: string,
 		isMainCommand: boolean,
-		options?: PrintOptions,
+		options: PrintOptions,
 	): string {
 		const argCharacters = new Set(arg);
 		const specialShellCharacters = isMainCommand
@@ -169,49 +191,134 @@ export class PrintableShellCommand {
 		return arg;
 	}
 
-	#smallIndent(s: string, options?: PrintOptions): string {
-		return (options?.mainIndentation ?? "") + s;
+	#mainIndentation(options: PrintOptions): string {
+		return options?.mainIndentation ?? DEFAULT_MAIN_INDENTATION;
+	}
+
+	#argIndentation(options: PrintOptions): string {
+		return (
+			this.#mainIndentation(options) +
+			(options?.argIndentation ?? DEFAULT_ARG_INDENTATION)
+		);
+	}
+
+	#lineWrapSeparator(options: PrintOptions): string {
+		return LINE_WRAP_LINE_END + this.#argIndentation(options);
 	}
 
-	#bigIndent(s: string, options?: PrintOptions): string {
-		return this.#smallIndent((options?.argIndentation ?? "  ") + s, options);
+	#argPairSeparator(options: PrintOptions): string {
+		switch (options?.argumentLineWrapping ?? DEFAULT_ARGUMENT_LINE_WRAPPING) {
+			case "by-entry": {
+				return INLINE_SEPARATOR;
+			}
+			case "nested-by-entry": {
+				return this.#lineWrapSeparator(options) + this.#argIndentation(options);
+			}
+			case "by-argument": {
+				return this.#lineWrapSeparator(options);
+			}
+			case "inline": {
+				return INLINE_SEPARATOR;
+			}
+			default:
+				throw new Error("Invalid argument line wrapping argument.");
+		}
+	}
+
+	#entrySeparator(options: PrintOptions): string {
+		switch (options?.argumentLineWrapping ?? DEFAULT_ARGUMENT_LINE_WRAPPING) {
+			case "by-entry": {
+				return LINE_WRAP_LINE_END + this.#argIndentation(options);
+			}
+			case "nested-by-entry": {
+				return LINE_WRAP_LINE_END + this.#argIndentation(options);
+			}
+			case "by-argument": {
+				return LINE_WRAP_LINE_END + this.#argIndentation(options);
+			}
+			case "inline": {
+				return INLINE_SEPARATOR;
+			}
+			default:
+				throw new Error("Invalid argument line wrapping argument.");
+		}
 	}
 
 	public getPrintableCommand(options?: PrintOptions): string {
-		const lines: string[] = [];
+		// TODO: Why in the world does TypeScript not give the `options` arg the type of `PrintOptions | undefined`???
+		// biome-ignore lint/style/noParameterAssign: We want a default assignment without affecting the signature.
+		options ??= {};
+		const serializedEntries: string[] = [];
 
-		lines.push(
-			this.#smallIndent(
+		serializedEntries.push(
+			this.#mainIndentation(options) +
 				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),
-				);
+				serializedEntries.push(this.#escapeArg(argsEntry, false, options));
 			} else {
 				const [part1, part2] = argsEntry;
-
-				lines.push(
-					this.#bigIndent(
-						this.#escapeArg(part1, false, options) +
-							INLINE_SEPARATOR +
-							this.#escapeArg(part2, false, options),
-						options,
-					),
+				serializedEntries.push(
+					this.#escapeArg(part1, false, options) +
+						this.#argPairSeparator(options) +
+						this.#escapeArg(part2, false, options),
 				);
 			}
 		}
-		return lines.join(LINE_WRAP_SEPARATOR);
+
+		return serializedEntries.join(this.#entrySeparator(options));
 	}
 
 	public print(options?: PrintOptions): void {
 		console.log(this.getPrintableCommand(options));
 	}
+
+	public spawnNode<
+		Stdin extends NodeStdioNull | NodeStdioPipe,
+		Stdout extends NodeStdioNull | NodeStdioPipe,
+		Stderr extends NodeStdioNull | NodeStdioPipe,
+	>(
+		options: NodeSpawnOptions
+		| NodeSpawnOptionsWithoutStdio | NodeSpawnOptionsWithStdioTuple<Stdin, Stdout, Stderr>,
+	): // TODO: figure out how to return `ChildProcessByStdio<…>` without duplicating fragile boilerplate.
+	NodeChildProcess {
+		const { spawn } = process.getBuiltinModule("node:child_process");
+		return spawn(...this.forNode(), options);
+	}
+
+	// The returned subprocess includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
+	public spawnBun<
+		const In extends BunSpawnOptions.Writable = "ignore",
+		const Out extends BunSpawnOptions.Readable = "pipe",
+		const Err extends BunSpawnOptions.Readable = "inherit",
+	>(
+		options?: Omit<BunSpawnOptions.OptionsObject<In, Out, Err>, "cmd">,
+	): BunSubprocess<In, Out, Err> & { success: Promise<void> } {
+		const { spawn } = process.getBuiltinModule("bun") as typeof import("bun");
+		const subprocess = spawn({
+			...options,
+			cmd: this.forBun(),
+		}) as BunSubprocess<In, Out, Err> & { success: Promise<void> };
+		Object.defineProperty(subprocess, "success", {
+			get() {
+				return new Promise<void>((resolve, reject) =>
+					this.exited
+						.then((exitCode: number) => {
+							if (exitCode === 0) {
+								resolve();
+							} else {
+								reject("Command failed.");
+							}
+						})
+						.catch(reject),
+				);
+			},
+			enumerable: false,
+		});
+		return subprocess;
+	}
 }

package/test/index.test.ts

@@ -0,0 +1,152 @@
+import { expect, test } from "bun:test";
+import { PrintableShellCommand } from "../src";
+
+const rsyncCommand = new PrintableShellCommand("rsync", [
+	"-avz",
+	["--exclude", ".DS_Store"],
+	["--exclude", ".git"],
+	"./dist/web/experiments.cubing.net/test/deploy/",
+	"experiments.cubing.net:~/experiments.cubing.net/test/deploy/",
+]);
+
+test("args for commands", () => {
+	expect(rsyncCommand.toCommandWithFlatArgs()).toEqual([
+		"rsync",
+		[
+			"-avz",
+			"--exclude",
+			".DS_Store",
+			"--exclude",
+			".git",
+			"./dist/web/experiments.cubing.net/test/deploy/",
+			"experiments.cubing.net:~/experiments.cubing.net/test/deploy/",
+		],
+	]);
+	expect(rsyncCommand.toFlatCommand()).toEqual([
+		"rsync",
+		"-avz",
+		"--exclude",
+		".DS_Store",
+		"--exclude",
+		".git",
+		"./dist/web/experiments.cubing.net/test/deploy/",
+		"experiments.cubing.net:~/experiments.cubing.net/test/deploy/",
+	]);
+	expect(rsyncCommand.toCommandWithFlatArgs()).toEqual(rsyncCommand.forNode());
+	expect(rsyncCommand.toFlatCommand()).toEqual(rsyncCommand.forBun());
+});
+
+test("default formatting", () => {
+	expect(rsyncCommand.getPrintableCommand()).toEqual(
+		`rsync \\
+  -avz \\
+  --exclude .DS_Store \\
+  --exclude .git \\
+  ./dist/web/experiments.cubing.net/test/deploy/ \\
+  experiments.cubing.net:~/experiments.cubing.net/test/deploy/`,
+	);
+	expect(
+		rsyncCommand.getPrintableCommand({
+			quoting: "auto",
+			argumentLineWrapping: "by-entry",
+		}),
+	).toEqual(rsyncCommand.getPrintableCommand());
+});
+
+test("extra-safe quoting", () => {
+	expect(rsyncCommand.getPrintableCommand({ quoting: "extra-safe" })).toEqual(
+		`'rsync' \\
+  '-avz' \\
+  '--exclude' '.DS_Store' \\
+  '--exclude' '.git' \\
+  './dist/web/experiments.cubing.net/test/deploy/' \\
+  'experiments.cubing.net:~/experiments.cubing.net/test/deploy/'`,
+	);
+});
+
+test("indentation", () => {
+	expect(
+		rsyncCommand.getPrintableCommand({ argIndentation: "\t   \t" }),
+	).toEqual(
+		`rsync \\
+	   	-avz \\
+	   	--exclude .DS_Store \\
+	   	--exclude .git \\
+	   	./dist/web/experiments.cubing.net/test/deploy/ \\
+	   	experiments.cubing.net:~/experiments.cubing.net/test/deploy/`,
+	);
+	expect(rsyncCommand.getPrintableCommand({ argIndentation: "↪ " })).toEqual(
+		`rsync \\
+↪ -avz \\
+↪ --exclude .DS_Store \\
+↪ --exclude .git \\
+↪ ./dist/web/experiments.cubing.net/test/deploy/ \\
+↪ experiments.cubing.net:~/experiments.cubing.net/test/deploy/`,
+	);
+	expect(rsyncCommand.getPrintableCommand({ mainIndentation: "  " })).toEqual(
+		`  rsync \\
+    -avz \\
+    --exclude .DS_Store \\
+    --exclude .git \\
+    ./dist/web/experiments.cubing.net/test/deploy/ \\
+    experiments.cubing.net:~/experiments.cubing.net/test/deploy/`,
+	);
+	expect(
+		rsyncCommand.getPrintableCommand({
+			mainIndentation: "🙈",
+			argIndentation: "🙉",
+		}),
+	).toEqual(
+		`🙈rsync \\
+🙈🙉-avz \\
+🙈🙉--exclude .DS_Store \\
+🙈🙉--exclude .git \\
+🙈🙉./dist/web/experiments.cubing.net/test/deploy/ \\
+🙈🙉experiments.cubing.net:~/experiments.cubing.net/test/deploy/`,
+	);
+});
+
+test("line wrapping", () => {
+	expect(
+		rsyncCommand.getPrintableCommand({ argumentLineWrapping: "by-entry" }),
+	).toEqual(rsyncCommand.getPrintableCommand());
+	expect(
+		rsyncCommand.getPrintableCommand({
+			argumentLineWrapping: "nested-by-entry",
+		}),
+	).toEqual(`rsync \\
+  -avz \\
+  --exclude \\
+    .DS_Store \\
+  --exclude \\
+    .git \\
+  ./dist/web/experiments.cubing.net/test/deploy/ \\
+  experiments.cubing.net:~/experiments.cubing.net/test/deploy/`);
+	expect(
+		rsyncCommand.getPrintableCommand({ argumentLineWrapping: "by-argument" }),
+	).toEqual(`rsync \\
+  -avz \\
+  --exclude \\
+  .DS_Store \\
+  --exclude \\
+  .git \\
+  ./dist/web/experiments.cubing.net/test/deploy/ \\
+  experiments.cubing.net:~/experiments.cubing.net/test/deploy/`);
+	expect(
+		rsyncCommand.getPrintableCommand({
+			argumentLineWrapping: "inline",
+		}),
+	).toEqual(
+		"rsync -avz --exclude .DS_Store --exclude .git ./dist/web/experiments.cubing.net/test/deploy/ experiments.cubing.net:~/experiments.cubing.net/test/deploy/",
+	);
+});
+
+test("command with space is escaped by default", () => {
+	const command = new PrintableShellCommand(
+		"/Applications/My App.app/Contents/Resources/my-app",
+	);
+
+	expect(command.getPrintableCommand()).toEqual(
+		`'/Applications/My App.app/Contents/Resources/my-app'`,
+	);
+});