printable-shell-command 0.1.0 → 0.1.2

package/.github/workflows/publish-github-release.yaml

@@ -0,0 +1,13 @@
+name: Publish GitHub release
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  Publish:
+    permissions:
+      contents: write
+    if: startsWith(github.ref, 'refs/tags/v')
+    uses: cubing/actions-workflows/.github/workflows/publish-github-release.yaml@main

package/Makefile

@@ -1,7 +1,20 @@
 .PHONY: lint
-lint:
+lint: setup
 	bun x @biomejs/biome check
 
 .PHONY: format
-format:
+format: setup
 	bun x @biomejs/biome check --write
+
+# https://github.com/lgarron/repo
+REPO_COMMANDS = publish
+
+publish: setup
+
+.PHONY: ${REPO_COMMANDS}
+${REPO_COMMANDS}:
+	repo $@
+
+.PHONY: setup
+setup:
+	bun install --frozen-lockfile

package/README.md

@@ -1,14 +1,14 @@
 # `printable-shell-command`
 
-A helper class to construct shell command in a way that allows printing them.
+A helper class to construct shell commands 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.
+The goal is to make it easy to print commands that are being run by a program, in a way that makes it easy and safe for a user to copy-and-paste.
 
-Goals:
+## 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.
+2. Fidelity — the printed command must match the arguments provided.
+3. Aesthetics — the command is pretty-printed to make it easy to read and to avoid escaping/quoting simple arguments where humans usually would not.
 
 Point 1 is difficult, and maybe even impossible. This library will do its best, but what you don't know can hurt you.
 
@@ -17,9 +17,10 @@ Point 1 is difficult, and maybe even impossible. This library will do its best,
 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
+// example.ts
 import { PrintableShellCommand } from "printable-shell-command";
 
-const command = new PrintableShellCommand("ffmpeg", [
+export const command = new PrintableShellCommand("ffmpeg", [
   ["-i", "./test/My video.mp4"],
   ["-filter:v", "setpts=2.0*PTS"],
   ["-filter:a", "atempo=0.5"],
@@ -29,31 +30,44 @@ const command = new PrintableShellCommand("ffmpeg", [
 command.print();
 ```
 
-### In `node`
+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'
+```
+
+### Spawn a process in `node`
 
 ```typescript
+import { PrintableShellCommand } from "printable-shell-command";
 import { spawn } from "node:child_process";
 
-// Note the `...`
-const child_process = spawn(...command.toCommandWithFlatArgs());
+const command = new PrintableShellCommand(/* … */);
+const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`
 ```
 
-### With `bun`
+### Spawn a process in `bun`
 
 ```typescript
+import { PrintableShellCommand } from "printable-shell-command";
 import { spawn } from "bun";
 
-await spawn({ cmd: command.toFlatCommand() }).exited;
+const command = new PrintableShellCommand(/* … */);
+await spawn(command.toFlatCommand()).exited;
 ```
 
 ## Protections
 
 Any command or argument containing the following characters is quoted and escaped:
 
-- space character
-- `"`
-- `'`
-- `\``
+- <code> </code> (space character)
+- `"` (double quote)
+- `'` (single quote)
+- <code>`</code> (backtick)
 - `|`
 - `$`
 - `*`

package/bun.lock

@@ -0,0 +1,42 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "printable-shell-command",
+      "devDependencies": {
+        "@biomejs/biome": "^1.9.4",
+        "@types/bun": "^1.1.14",
+        "@types/node": "^22.10.2",
+      },
+    },
+  },
+  "packages": {
+    "@biomejs/biome": ["@biomejs/biome@1.9.4", "", { "optionalDependencies": { "@biomejs/cli-darwin-arm64": "1.9.4", "@biomejs/cli-darwin-x64": "1.9.4", "@biomejs/cli-linux-arm64": "1.9.4", "@biomejs/cli-linux-arm64-musl": "1.9.4", "@biomejs/cli-linux-x64": "1.9.4", "@biomejs/cli-linux-x64-musl": "1.9.4", "@biomejs/cli-win32-arm64": "1.9.4", "@biomejs/cli-win32-x64": "1.9.4" }, "bin": { "biome": "bin/biome" } }, "sha512-1rkd7G70+o9KkTn5KLmDYXihGoTaIGO9PIIN2ZB7UJxFrWw04CZHPYiMRjYsaDvVV7hP1dYNRLxSANLaBFGpog=="],
+
+    "@biomejs/cli-darwin-arm64": ["@biomejs/cli-darwin-arm64@1.9.4", "", { "os": "darwin", "cpu": "arm64" }, "sha512-bFBsPWrNvkdKrNCYeAp+xo2HecOGPAy9WyNyB/jKnnedgzl4W4Hb9ZMzYNbf8dMCGmUdSavlYHiR01QaYR58cw=="],
+
+    "@biomejs/cli-darwin-x64": ["@biomejs/cli-darwin-x64@1.9.4", "", { "os": "darwin", "cpu": "x64" }, "sha512-ngYBh/+bEedqkSevPVhLP4QfVPCpb+4BBe2p7Xs32dBgs7rh9nY2AIYUL6BgLw1JVXV8GlpKmb/hNiuIxfPfZg=="],
+
+    "@biomejs/cli-linux-arm64": ["@biomejs/cli-linux-arm64@1.9.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-fJIW0+LYujdjUgJJuwesP4EjIBl/N/TcOX3IvIHJQNsAqvV2CHIogsmA94BPG6jZATS4Hi+xv4SkBBQSt1N4/g=="],
+
+    "@biomejs/cli-linux-arm64-musl": ["@biomejs/cli-linux-arm64-musl@1.9.4", "", { "os": "linux", "cpu": "arm64" }, "sha512-v665Ct9WCRjGa8+kTr0CzApU0+XXtRgwmzIf1SeKSGAv+2scAlW6JR5PMFo6FzqqZ64Po79cKODKf3/AAmECqA=="],
+
+    "@biomejs/cli-linux-x64": ["@biomejs/cli-linux-x64@1.9.4", "", { "os": "linux", "cpu": "x64" }, "sha512-lRCJv/Vi3Vlwmbd6K+oQ0KhLHMAysN8lXoCI7XeHlxaajk06u7G+UsFSO01NAs5iYuWKmVZjmiOzJ0OJmGsMwg=="],
+
+    "@biomejs/cli-linux-x64-musl": ["@biomejs/cli-linux-x64-musl@1.9.4", "", { "os": "linux", "cpu": "x64" }, "sha512-gEhi/jSBhZ2m6wjV530Yy8+fNqG8PAinM3oV7CyO+6c3CEh16Eizm21uHVsyVBEB6RIM8JHIl6AGYCv6Q6Q9Tg=="],
+
+    "@biomejs/cli-win32-arm64": ["@biomejs/cli-win32-arm64@1.9.4", "", { "os": "win32", "cpu": "arm64" }, "sha512-tlbhLk+WXZmgwoIKwHIHEBZUwxml7bRJgk0X2sPyNR3S93cdRq6XulAZRQJ17FYGGzWne0fgrXBKpl7l4M87Hg=="],
+
+    "@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/node": ["@types/node@22.13.9", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-acBjXdRJ3A6Pb3tqnw9HZmyR3Fiol3aGxRCK1x3d+6CDAMjl7I649wpSd+yNURCjbOUGu9tqtLKnTGxmK6CyGw=="],
+
+    "@types/ws": ["@types/ws@8.5.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-bd/YFLW+URhBzMXurx7lWByOu+xzU9+kb3RboOteXYDfW+tr+JZa99OyNmPINEGB/ahzKrEuc8rcv4gnpJmxTw=="],
+
+    "bun-types": ["bun-types@1.2.4", "", { "dependencies": { "@types/node": "*", "@types/ws": "~8.5.10" } }, "sha512-nDPymR207ZZEoWD4AavvEaa/KZe/qlrbMSchqpQwovPZCKc7pwMoENjEtHgMKaAjJhy+x6vfqSBA1QU3bJgs0Q=="],
+
+    "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": "v0.1.0",
+	"version": "0.1.2",
 	"main": "./src/index.ts",
 	"type": "module",
 	"exports": {
@@ -9,7 +9,7 @@
 			"import": "./src/index.ts"
 		}
 	},
-	"dependencies": {
+	"devDependencies": {
 		"@biomejs/biome": "^1.9.4",
 		"@types/bun": "^1.1.14",
 		"@types/node": "^22.10.2"

package/src/index.ts

@@ -52,14 +52,16 @@ const SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND =
 	SPECIAL_SHELL_CHARACTERS.union(new Set(["="]));
 
 export class PrintableShellCommand {
+	#commandName: string;
 	constructor(
-		private commandName: string,
+		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);
 		}
+		this.#commandName = commandName;
 		if (typeof args === "undefined") {
 			return;
 		}
@@ -83,15 +85,67 @@ export class PrintableShellCommand {
 		}
 	}
 
+	get commandName(): string {
+		return this.#commandName;
+	}
+
+	// For use with `bun`.
+	//
+	// Usage example:
+	//
+	//     import { PrintableShellCommand } from "printable-shell-command";
+	//     import { spawn } from "bun";
+	//
+	//     const command = new PrintableShellCommand(/* … */);
+	//     await spawn(command.toFlatCommand()).exited;
+	//
 	public toFlatCommand(): string[] {
 		return [this.commandName, ...this.args.flat()];
 	}
 
+	// Convenient alias for `toFlatCommand()`.
+	//
+	// Usage example:
+	//
+	//     import { PrintableShellCommand } from "printable-shell-command";
+	//     import { spawn } from "bun";
+	//
+	//     const command = new PrintableShellCommand(/* … */);
+	//     await spawn(command.forBun()).exited;
+	//
+	public forBun(): string[] {
+		return this.toFlatCommand();
+	}
+
 	// For use with `node:child_process`
+	//
+	// Usage example:
+	//
+	//     import { PrintableShellCommand } from "printable-shell-command";
+	//    import { spawn } from "node:child_process";
+	//
+	//    const command = new PrintableShellCommand(/* … */);
+	//    const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`
+	//
 	public toCommandWithFlatArgs(): [string, string[]] {
 		return [this.commandName, this.args.flat()];
 	}
 
+	// For use with `node:child_process`
+	//
+	// Usage example:
+	//
+	//     import { PrintableShellCommand } from "printable-shell-command";
+	//    import { spawn } from "node:child_process";
+	//
+	//    const command = new PrintableShellCommand(/* … */);
+	//    const child_process = spawn(...command.forNode()); // Note the `...`
+	//
+	// Convenient alias for `toCommandWithFlatArgs()`.
+	public forNode(): [string, string[]] {
+		return this.toCommandWithFlatArgs();
+	}
+
 	#escapeArg(
 		arg: string,
 		isMainCommand: boolean,

package/test/simple-test-bun.ts

@@ -9,4 +9,4 @@ const command = new PrintableShellCommand("ffmpeg", [
 ]);
 
 command.print();
-await spawn({ cmd: command.toFlatCommand() }).exited;
+await spawn(command.toFlatCommand()).exited;