printable-shell-command 0.1.0 → 0.1.1

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

@@ -5,3 +5,9 @@ lint:
 .PHONY: format
 format:
 	bun x @biomejs/biome check --write
+
+# https://github.com/lgarron/repo
+REPO_COMMANDS = setup publish
+
+${REPO_COMMANDS}:
+	repo $@

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.
 
-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,43 @@ 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 { command } from "./example";
 import { spawn } from "node:child_process";
 
 // Note the `...`
 const child_process = spawn(...command.toCommandWithFlatArgs());
 ```
 
-### With `bun`
+### Spawn a process in `bun`
 
 ```typescript
+import { command } from "./example";
 import { spawn } from "bun";
 
-await spawn({ cmd: command.toFlatCommand() }).exited;
+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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "printable-shell-command",
-	"version": "v0.1.0",
+	"version": "0.1.1",
 	"main": "./src/index.ts",
 	"type": "module",
 	"exports": {

package/src/index.ts

@@ -87,11 +87,20 @@ export class PrintableShellCommand {
 		return [this.commandName, ...this.args.flat()];
 	}
 
+	// Convenient alias for `toFlatCommand()`.
+	public forBun(): string[] {
+		return this.toFlatCommand();
+	}
 	// For use with `node:child_process`
 	public toCommandWithFlatArgs(): [string, string[]] {
 		return [this.commandName, this.args.flat()];
 	}
 
+	// 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;