printable-shell-command 0.3.0 → 0.3.2

package/README.md

@@ -47,7 +47,7 @@ import { PrintableShellCommand } from "printable-shell-command";
 import { spawn } from "node:child_process";
 
 const command = new PrintableShellCommand(/* … */);
-const child_process = spawn(...command.toCommandWithFlatAr()); // Note the `...`
+const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`
 
 // or directly
 await command.spawnNode().success;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "printable-shell-command",
-	"version": "0.3.0",
+	"version": "0.3.2",
 	"main": "./src/index.ts",
 	"type": "module",
 	"exports": {
@@ -17,5 +17,10 @@
 	"optionalDependencies": {
 		"@types/bun": "^1.2.11",
 		"@types/node": "^22.15.3"
-	}
+	},
+	"files": [
+		"README.md",
+		"src",
+		"tsconfig.json"
+	]
 }

package/src/index.ts

@@ -278,6 +278,9 @@ export class PrintableShellCommand {
 		return this;
 	}
 
+	/**
+	 * The returned child process includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
+	 */
 	public spawnNode<
 		Stdin extends NodeStdioNull | NodeStdioPipe,
 		Stdout extends NodeStdioNull | NodeStdioPipe,
@@ -290,6 +293,7 @@ export class PrintableShellCommand {
 	): // TODO: figure out how to return `ChildProcessByStdio<…>` without duplicating fragile boilerplate.
 	NodeChildProcess & { success: Promise<void> } {
 		const { spawn } = process.getBuiltinModule("node:child_process");
+		// @ts-ignore: The TypeScript checker has trouble reconciling the optional (i.e. potentially `undefined`) `options` with the third argument.
 		const subprocess = spawn(...this.forNode(), options) as NodeChildProcess & {
 			success: Promise<void>;
 		};
@@ -313,9 +317,9 @@ export class PrintableShellCommand {
 		return subprocess;
 	}
 
-	// A wrapper for `.spawnNode(…)` that sets stdio to `"inherit"` (common for
-	// invoking commands from scripts whose output and interaction should be
-	// surfaced to the user).
+	/** A wrapper for `.spawnNode(…)` that sets stdio to `"inherit"` (common for
+	 * invoking commands from scripts whose output and interaction should be
+	 * surfaced to the user). */
 	public spawnNodeInherit(
 		options?: Omit<NodeSpawnOptions, "stdio">,
 	): NodeChildProcess & { success: Promise<void> } {
@@ -337,7 +341,9 @@ export class PrintableShellCommand {
 		await this.print().spawnNodeInherit(options).success;
 	}
 
-	// The returned subprocess includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
+	/**
+	 * 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",
@@ -376,9 +382,11 @@ export class PrintableShellCommand {
 		return subprocess;
 	}
 
-	// A wrapper for `.spawnBunInherit(…)` that sets stdio to `"inherit"` (common for
-	// invoking commands from scripts whose output and interaction should be
-	// surfaced to the user).
+	/**
+	 * A wrapper for `.spawnBunInherit(…)` that sets stdio to `"inherit"` (common
+	 * for invoking commands from scripts whose output and interaction should be
+	 * surfaced to the user).
+	 */
 	public spawnBunInherit(
 		options?: Omit<
 			Omit<
@@ -399,6 +407,24 @@ export class PrintableShellCommand {
 		});
 	}
 
+	/** Equivalent to:
+	 *
+	 * ```
+	 *     new Response(this.spawnBun(options).stdout);
+	 * ```
+	 */
+	public spawnBunStdout(
+		options?: Omit<
+			Omit<
+				BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">,
+				"cmd"
+			>,
+			"stdio"
+		>,
+	): Response {
+		return new Response(this.spawnBun(options).stdout);
+	}
+
 	/** Equivalent to:
 	 *
 	 * ```

package/.github/workflows/CI.yaml

@@ -1,14 +0,0 @@
-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/.github/workflows/publish-github-release.yaml

@@ -1,13 +0,0 @@
-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,35 +0,0 @@
-.PHONY: test
-test: lint test-js
-
-.PHONY: lint
-lint: setup
-	bun x @biomejs/biome check
-
-.PHONY: format
-format: setup
-	bun x @biomejs/biome check --write
-
-.PHONY: test-js
-test-js: setup
-	bun test
-
-# https://github.com/lgarron/repo
-REPO_COMMANDS = publish
-
-publish: setup
-
-.PHONY: ${REPO_COMMANDS}
-${REPO_COMMANDS}:
-	repo $@
-
-.PHONY: setup
-setup:
-	bun install --frozen-lockfile
-
-.PHONY: clean
-clean:
-	# No-op
-
-.PHONY: reset
-reset: clean
-	rm -rf ./node_modules

package/biome.json

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

package/bun.lock

@@ -1,46 +0,0 @@
-{
-  "lockfileVersion": 1,
-  "workspaces": {
-    "": {
-      "name": "printable-shell-command",
-      "dependencies": {
-        "@types/bun": "^1.2.11",
-        "@types/node": "^22.15.3",
-      },
-      "devDependencies": {
-        "@biomejs/biome": "^1.9.4",
-      },
-    },
-  },
-  "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.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=="],
-
-    "bun-types": ["bun-types@1.2.11", "", { "dependencies": { "@types/node": "*" } }, "sha512-dbkp5Lo8HDrXkLrONm6bk+yiiYQSntvFUzQp0v3pzTAsXk6FtgVMjdQ+lzFNVAmQFUkPQZ3WMZqH5tTo+Dp/IA=="],
-
-    "undici-types": ["undici-types@6.21.0", "", {}, "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ=="],
-
-    "bun-types/@types/node": ["@types/node@22.13.9", "", { "dependencies": { "undici-types": "~6.20.0" } }, "sha512-acBjXdRJ3A6Pb3tqnw9HZmyR3Fiol3aGxRCK1x3d+6CDAMjl7I649wpSd+yNURCjbOUGu9tqtLKnTGxmK6CyGw=="],
-
-    "bun-types/@types/node/undici-types": ["undici-types@6.20.0", "", {}, "sha512-Ny6QZ2Nju20vw1SRHe3d9jVu6gJ+4e3+MMpqu7pqE5HT6WsTSlce++GQmK5UXS8mzV8DSYHrQH+Xrf2jVcuKNg=="],
-  }
-}

package/test/index.test.ts

@@ -1,152 +0,0 @@
-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'`,
-	);
-});

package/test/simple-test-bun.ts

@@ -1,10 +0,0 @@
-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",
-]);
-
-await command.shellOutBun();

package/test/simple-test-node.ts

@@ -1,10 +0,0 @@
-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().shellOutNode();