printable-shell-command 0.1.0-pre1

package/README.md

@@ -0,0 +1,100 @@
+# `printable-shell-command`
+
+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 being 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. 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.
+
+## 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
+// example.ts
+import { PrintableShellCommand } from "printable-shell-command";
+
+export 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();
+```
+
+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";
+
+const command = new PrintableShellCommand(/* … */);
+const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`
+
+// or directly
+await command.spawnNode().success;
+await command.spawnNodeInherit().success;
+```
+
+### Spawn a process in `bun`
+
+```typescript
+import { PrintableShellCommand } from "printable-shell-command";
+import { spawn } from "bun";
+
+const command = new PrintableShellCommand(/* … */);
+await spawn(command.toFlatCommand()).exited;
+
+// or directly
+await command.spawnBun().success;
+await command.spawnBunInherit().success;
+```
+
+## Protections
+
+Any command or argument containing the following characters is quoted and escaped:
+
+- <code> </code> (space character)
+- `"` (double quote)
+- `'` (single quote)
+- <code>`</code> (backtick)
+- `|`
+- `$`
+- `*`
+- `?`
+- `>`
+- `<`
+- `(`
+- `)`
+- `[`
+- `]`
+- `{`
+- `}`
+- `&`
+- `\`
+- `;`
+
+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/dist/lib/printable-shell-command/index.d.ts

@@ -0,0 +1,73 @@
+import type { ChildProcess as NodeChildProcess, SpawnOptions as NodeSpawnOptions, SpawnOptionsWithStdioTuple as NodeSpawnOptionsWithStdioTuple, SpawnOptionsWithoutStdio as NodeSpawnOptionsWithoutStdio, StdioNull as NodeStdioNull, StdioPipe as NodeStdioPipe } from "node:child_process";
+import type { SpawnOptions as BunSpawnOptions, Subprocess as BunSubprocess } from "bun";
+type SingleArgument = string;
+type FlagArgumentPair = [string, string];
+type ArgsEntry = SingleArgument | FlagArgumentPair;
+type Args = ArgsEntry[];
+export interface PrintOptions {
+    mainIndentation?: string;
+    argIndentation?: string;
+    quoting?: "auto" | "extra-safe";
+    argumentLineWrapping?: "by-entry" | "nested-by-entry" | "by-argument" | "inline";
+}
+export declare class PrintableShellCommand {
+    #private;
+    private args;
+    constructor(commandName: string, args?: Args);
+    get commandName(): string;
+    toFlatCommand(): string[];
+    forBun(): string[];
+    toCommandWithFlatArgs(): [string, string[]];
+    forNode(): [string, string[]];
+    getPrintableCommand(options?: PrintOptions): string;
+    print(options?: PrintOptions): PrintableShellCommand;
+    /**
+     * The returned child process includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
+     */
+    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 & {
+        success: Promise<void>;
+    };
+    /** 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). */
+    spawnNodeInherit(options?: Omit<NodeSpawnOptions, "stdio">): NodeChildProcess & {
+        success: Promise<void>;
+    };
+    /** Equivalent to:
+     *
+     * ```
+     *     await this.print().spawnNodeInherit().success;
+     * ```
+     */
+    shellOutNode(options?: Omit<NodeSpawnOptions, "stdio">): Promise<void>;
+    /**
+     * The returned subprocess includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
+     */
+    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>;
+    };
+    /**
+     * 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).
+     */
+    spawnBunInherit(options?: Omit<Omit<BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">, "cmd">, "stdio">): BunSubprocess<"inherit", "inherit", "inherit"> & {
+        success: Promise<void>;
+    };
+    /** Equivalent to:
+     *
+     * ```
+     *     new Response(this.spawnBun(options).stdout);
+     * ```
+     */
+    spawnBunStdout(options?: Omit<Omit<BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">, "cmd">, "stdio">): Response;
+    /** Equivalent to:
+     *
+     * ```
+     *     await this.print().spawnBunInherit().success;
+     * ```
+     */
+    shellOutBun(options?: Omit<Omit<BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">, "cmd">, "stdio">): Promise<void>;
+}
+export {};

package/dist/lib/printable-shell-command/index.js

@@ -0,0 +1,305 @@
+// src/index.ts
+var DEFAULT_MAIN_INDENTATION = "";
+var DEFAULT_ARG_INDENTATION = "  ";
+var DEFAULT_ARGUMENT_LINE_WRAPPING = "by-entry";
+var INLINE_SEPARATOR = " ";
+var LINE_WRAP_LINE_END = " \\\n";
+function isString(s) {
+  return typeof s === "string";
+}
+var SPECIAL_SHELL_CHARACTERS = /* @__PURE__ */ new Set([
+  " ",
+  '"',
+  "'",
+  "`",
+  "|",
+  "$",
+  "*",
+  "?",
+  ">",
+  "<",
+  "(",
+  ")",
+  "[",
+  "]",
+  "{",
+  "}",
+  "&",
+  "\\",
+  ";"
+]);
+var SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND = (
+  // biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)
+  SPECIAL_SHELL_CHARACTERS.union(/* @__PURE__ */ new Set(["="]))
+);
+var PrintableShellCommand = class {
+  constructor(commandName, args = []) {
+    this.args = args;
+    if (!isString(commandName)) {
+      throw new Error("Command name is not a string:", commandName);
+    }
+    this.#commandName = commandName;
+    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}`);
+    }
+  }
+  #commandName;
+  get commandName() {
+    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;
+  //
+  toFlatCommand() {
+    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;
+  //
+  forBun() {
+    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 `...`
+  //
+  toCommandWithFlatArgs() {
+    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()`.
+  forNode() {
+    return this.toCommandWithFlatArgs();
+  }
+  #escapeArg(arg, isMainCommand, options) {
+    const argCharacters = new Set(arg);
+    const specialShellCharacters = isMainCommand ? SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND : SPECIAL_SHELL_CHARACTERS;
+    if (options?.quoting === "extra-safe" || // biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)
+    argCharacters.intersection(specialShellCharacters).size > 0) {
+      const escaped = arg.replaceAll("\\", "\\\\").replaceAll("'", "\\'");
+      return `'${escaped}'`;
+    }
+    return arg;
+  }
+  #mainIndentation(options) {
+    return options?.mainIndentation ?? DEFAULT_MAIN_INDENTATION;
+  }
+  #argIndentation(options) {
+    return this.#mainIndentation(options) + (options?.argIndentation ?? DEFAULT_ARG_INDENTATION);
+  }
+  #lineWrapSeparator(options) {
+    return LINE_WRAP_LINE_END + this.#argIndentation(options);
+  }
+  #argPairSeparator(options) {
+    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) {
+    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.");
+    }
+  }
+  getPrintableCommand(options) {
+    options ??= {};
+    const serializedEntries = [];
+    serializedEntries.push(
+      this.#mainIndentation(options) + this.#escapeArg(this.commandName, true, options)
+    );
+    for (let i = 0; i < this.args.length; i++) {
+      const argsEntry = this.args[i];
+      if (isString(argsEntry)) {
+        serializedEntries.push(this.#escapeArg(argsEntry, false, options));
+      } else {
+        const [part1, part2] = argsEntry;
+        serializedEntries.push(
+          this.#escapeArg(part1, false, options) + this.#argPairSeparator(options) + this.#escapeArg(part2, false, options)
+        );
+      }
+    }
+    return serializedEntries.join(this.#entrySeparator(options));
+  }
+  print(options) {
+    console.log(this.getPrintableCommand(options));
+    return this;
+  }
+  /**
+   * The returned child process includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
+   */
+  spawnNode(options) {
+    const { spawn } = process.getBuiltinModule("node:child_process");
+    const subprocess = spawn(...this.forNode(), options);
+    Object.defineProperty(subprocess, "success", {
+      get() {
+        return new Promise(
+          (resolve, reject) => this.addListener(
+            "exit",
+            (exitCode) => {
+              if (exitCode === 0) {
+                resolve();
+              } else {
+                reject(`Command failed with non-zero exit code: ${exitCode}`);
+              }
+            }
+          )
+        );
+      },
+      enumerable: false
+    });
+    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). */
+  spawnNodeInherit(options) {
+    if (options && "stdio" in options) {
+      throw new Error("Unexpected `stdio` field.");
+    }
+    return this.spawnNode({ ...options, stdio: "inherit" });
+  }
+  /** Equivalent to:
+   *
+   * ```
+   *     await this.print().spawnNodeInherit().success;
+   * ```
+   */
+  async shellOutNode(options) {
+    await this.print().spawnNodeInherit(options).success;
+  }
+  /**
+   * The returned subprocess includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
+   */
+  spawnBun(options) {
+    if (options && "cmd" in options) {
+      throw new Error("Unexpected `cmd` field.");
+    }
+    const { spawn } = process.getBuiltinModule("bun");
+    const subprocess = spawn({
+      ...options,
+      cmd: this.forBun()
+    });
+    Object.defineProperty(subprocess, "success", {
+      get() {
+        return new Promise(
+          (resolve, reject) => this.exited.then((exitCode) => {
+            if (exitCode === 0) {
+              resolve();
+            } else {
+              reject(
+                new Error(
+                  `Command failed with non-zero exit code: ${exitCode}`
+                )
+              );
+            }
+          }).catch(reject)
+        );
+      },
+      enumerable: false
+    });
+    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).
+   */
+  spawnBunInherit(options) {
+    if (options && "stdio" in options) {
+      throw new Error("Unexpected `stdio` field.");
+    }
+    return this.spawnBun({
+      ...options,
+      stdio: ["inherit", "inherit", "inherit"]
+    });
+  }
+  /** Equivalent to:
+   *
+   * ```
+   *     new Response(this.spawnBun(options).stdout);
+   * ```
+   */
+  spawnBunStdout(options) {
+    return new Response(this.spawnBun(options).stdout);
+  }
+  /** Equivalent to:
+   *
+   * ```
+   *     await this.print().spawnBunInherit().success;
+   * ```
+   */
+  async shellOutBun(options) {
+    await this.print().spawnBunInherit(options).success;
+  }
+};
+export {
+  PrintableShellCommand
+};
+//# sourceMappingURL=index.js.map

package/dist/lib/printable-shell-command/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/index.ts"],
+  "sourcesContent": ["import type {\n\tChildProcess as NodeChildProcess,\n\tSpawnOptions as NodeSpawnOptions,\n\tSpawnOptionsWithStdioTuple as NodeSpawnOptionsWithStdioTuple,\n\tSpawnOptionsWithoutStdio as NodeSpawnOptionsWithoutStdio,\n\tStdioNull as NodeStdioNull,\n\tStdioPipe as NodeStdioPipe,\n} from \"node:child_process\";\nimport type {\n\tSpawnOptions as BunSpawnOptions,\n\tSubprocess as BunSubprocess,\n} from \"bun\";\n\nconst DEFAULT_MAIN_INDENTATION = \"\";\nconst DEFAULT_ARG_INDENTATION = \"  \";\nconst DEFAULT_ARGUMENT_LINE_WRAPPING = \"by-entry\";\n\nconst INLINE_SEPARATOR = \" \";\nconst LINE_WRAP_LINE_END = \" \\\\\\n\";\n\n// biome-ignore lint/suspicious/noExplicitAny: This is the correct type nere.\nfunction isString(s: any): s is string {\n\treturn typeof s === \"string\";\n}\n\n// TODO: allow `.toString()`ables?\ntype SingleArgument = string;\ntype FlagArgumentPair = [string, string];\ntype ArgsEntry = SingleArgument | FlagArgumentPair;\ntype Args = ArgsEntry[];\n\nexport interface PrintOptions {\n\tmainIndentation?: string; // Defaults to \"\"\n\targIndentation?: string; // Defaults to \"  \"\n\t// - \"auto\": Quote only arguments that need it for safety. This tries to be\n\t//   portable and safe across shells, but true safety and portability is hard\n\t//   to guarantee.\n\t// - \"extra-safe\": Quote all arguments, even ones that don't need it. This is\n\t//   more likely to be safe under all circumstances.\n\tquoting?: \"auto\" | \"extra-safe\";\n\t// Line wrapping to use between arguments. Defaults to `\"by-entry\"`.\n\targumentLineWrapping?:\n\t\t| \"by-entry\"\n\t\t| \"nested-by-entry\"\n\t\t| \"by-argument\"\n\t\t| \"inline\";\n}\n\n// https://mywiki.wooledge.org/BashGuide/SpecialCharacters\nconst SPECIAL_SHELL_CHARACTERS = new Set([\n\t\" \",\n\t'\"',\n\t\"'\",\n\t\"`\",\n\t\"|\",\n\t\"$\",\n\t\"*\",\n\t\"?\",\n\t\">\",\n\t\"<\",\n\t\"(\",\n\t\")\",\n\t\"[\",\n\t\"]\",\n\t\"{\",\n\t\"}\",\n\t\"&\",\n\t\"\\\\\",\n\t\";\",\n]);\n\n// https://mywiki.wooledge.org/BashGuide/SpecialCharacters\nconst SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND =\n\t// biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)\n\t(SPECIAL_SHELL_CHARACTERS as unknown as any).union(new Set([\"=\"]));\n\nexport class PrintableShellCommand {\n\t#commandName: string;\n\tconstructor(\n\t\tcommandName: string,\n\t\tprivate args: Args = [],\n\t) {\n\t\tif (!isString(commandName)) {\n\t\t\t// biome-ignore lint/suspicious/noExplicitAny: We want to print this, no matter what it is.\n\t\t\tthrow new Error(\"Command name is not a string:\", commandName as any);\n\t\t}\n\t\tthis.#commandName = commandName;\n\t\tif (typeof args === \"undefined\") {\n\t\t\treturn;\n\t\t}\n\t\tif (!Array.isArray(args)) {\n\t\t\tthrow new Error(\"Command arguments are not an array\");\n\t\t}\n\t\tfor (let i = 0; i < args.length; i++) {\n\t\t\tconst argEntry = args[i];\n\t\t\tif (typeof argEntry === \"string\") {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (\n\t\t\t\tArray.isArray(argEntry) &&\n\t\t\t\targEntry.length === 2 &&\n\t\t\t\tisString(argEntry[0]) &&\n\t\t\t\tisString(argEntry[1])\n\t\t\t) {\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tthrow new Error(`Invalid arg entry at index: ${i}`);\n\t\t}\n\t}\n\n\tget commandName(): string {\n\t\treturn this.#commandName;\n\t}\n\n\t// For use with `bun`.\n\t//\n\t// Usage example:\n\t//\n\t//     import { PrintableShellCommand } from \"printable-shell-command\";\n\t//     import { spawn } from \"bun\";\n\t//\n\t//     const command = new PrintableShellCommand(/* \u2026 */);\n\t//     await spawn(command.toFlatCommand()).exited;\n\t//\n\tpublic toFlatCommand(): string[] {\n\t\treturn [this.commandName, ...this.args.flat()];\n\t}\n\n\t// Convenient alias for `toFlatCommand()`.\n\t//\n\t// Usage example:\n\t//\n\t//     import { PrintableShellCommand } from \"printable-shell-command\";\n\t//     import { spawn } from \"bun\";\n\t//\n\t//     const command = new PrintableShellCommand(/* \u2026 */);\n\t//     await spawn(command.forBun()).exited;\n\t//\n\tpublic forBun(): string[] {\n\t\treturn this.toFlatCommand();\n\t}\n\n\t// For use with `node:child_process`\n\t//\n\t// Usage example:\n\t//\n\t//     import { PrintableShellCommand } from \"printable-shell-command\";\n\t//    import { spawn } from \"node:child_process\";\n\t//\n\t//    const command = new PrintableShellCommand(/* \u2026 */);\n\t//    const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`\n\t//\n\tpublic toCommandWithFlatArgs(): [string, string[]] {\n\t\treturn [this.commandName, this.args.flat()];\n\t}\n\n\t// For use with `node:child_process`\n\t//\n\t// Usage example:\n\t//\n\t//     import { PrintableShellCommand } from \"printable-shell-command\";\n\t//    import { spawn } from \"node:child_process\";\n\t//\n\t//    const command = new PrintableShellCommand(/* \u2026 */);\n\t//    const child_process = spawn(...command.forNode()); // Note the `...`\n\t//\n\t// Convenient alias for `toCommandWithFlatArgs()`.\n\tpublic forNode(): [string, string[]] {\n\t\treturn this.toCommandWithFlatArgs();\n\t}\n\n\t#escapeArg(\n\t\targ: string,\n\t\tisMainCommand: boolean,\n\t\toptions: PrintOptions,\n\t): string {\n\t\tconst argCharacters = new Set(arg);\n\t\tconst specialShellCharacters = isMainCommand\n\t\t\t? SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND\n\t\t\t: SPECIAL_SHELL_CHARACTERS;\n\t\tif (\n\t\t\toptions?.quoting === \"extra-safe\" ||\n\t\t\t// biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)\n\t\t\t(argCharacters as unknown as any).intersection(specialShellCharacters)\n\t\t\t\t.size > 0\n\t\t) {\n\t\t\t// Use single quote to reduce the need to escape (and therefore reduce the chance for bugs/security issues).\n\t\t\tconst escaped = arg.replaceAll(\"\\\\\", \"\\\\\\\\\").replaceAll(\"'\", \"\\\\'\");\n\t\t\treturn `'${escaped}'`;\n\t\t}\n\t\treturn arg;\n\t}\n\n\t#mainIndentation(options: PrintOptions): string {\n\t\treturn options?.mainIndentation ?? DEFAULT_MAIN_INDENTATION;\n\t}\n\n\t#argIndentation(options: PrintOptions): string {\n\t\treturn (\n\t\t\tthis.#mainIndentation(options) +\n\t\t\t(options?.argIndentation ?? DEFAULT_ARG_INDENTATION)\n\t\t);\n\t}\n\n\t#lineWrapSeparator(options: PrintOptions): string {\n\t\treturn LINE_WRAP_LINE_END + this.#argIndentation(options);\n\t}\n\n\t#argPairSeparator(options: PrintOptions): string {\n\t\tswitch (options?.argumentLineWrapping ?? DEFAULT_ARGUMENT_LINE_WRAPPING) {\n\t\t\tcase \"by-entry\": {\n\t\t\t\treturn INLINE_SEPARATOR;\n\t\t\t}\n\t\t\tcase \"nested-by-entry\": {\n\t\t\t\treturn this.#lineWrapSeparator(options) + this.#argIndentation(options);\n\t\t\t}\n\t\t\tcase \"by-argument\": {\n\t\t\t\treturn this.#lineWrapSeparator(options);\n\t\t\t}\n\t\t\tcase \"inline\": {\n\t\t\t\treturn INLINE_SEPARATOR;\n\t\t\t}\n\t\t\tdefault:\n\t\t\t\tthrow new Error(\"Invalid argument line wrapping argument.\");\n\t\t}\n\t}\n\n\t#entrySeparator(options: PrintOptions): string {\n\t\tswitch (options?.argumentLineWrapping ?? DEFAULT_ARGUMENT_LINE_WRAPPING) {\n\t\t\tcase \"by-entry\": {\n\t\t\t\treturn LINE_WRAP_LINE_END + this.#argIndentation(options);\n\t\t\t}\n\t\t\tcase \"nested-by-entry\": {\n\t\t\t\treturn LINE_WRAP_LINE_END + this.#argIndentation(options);\n\t\t\t}\n\t\t\tcase \"by-argument\": {\n\t\t\t\treturn LINE_WRAP_LINE_END + this.#argIndentation(options);\n\t\t\t}\n\t\t\tcase \"inline\": {\n\t\t\t\treturn INLINE_SEPARATOR;\n\t\t\t}\n\t\t\tdefault:\n\t\t\t\tthrow new Error(\"Invalid argument line wrapping argument.\");\n\t\t}\n\t}\n\n\tpublic getPrintableCommand(options?: PrintOptions): string {\n\t\t// TODO: Why in the world does TypeScript not give the `options` arg the type of `PrintOptions | undefined`???\n\t\t// biome-ignore lint/style/noParameterAssign: We want a default assignment without affecting the signature.\n\t\toptions ??= {};\n\t\tconst serializedEntries: string[] = [];\n\n\t\tserializedEntries.push(\n\t\t\tthis.#mainIndentation(options) +\n\t\t\t\tthis.#escapeArg(this.commandName, true, options),\n\t\t);\n\n\t\tfor (let i = 0; i < this.args.length; i++) {\n\t\t\tconst argsEntry = this.args[i];\n\n\t\t\tif (isString(argsEntry)) {\n\t\t\t\tserializedEntries.push(this.#escapeArg(argsEntry, false, options));\n\t\t\t} else {\n\t\t\t\tconst [part1, part2] = argsEntry;\n\t\t\t\tserializedEntries.push(\n\t\t\t\t\tthis.#escapeArg(part1, false, options) +\n\t\t\t\t\t\tthis.#argPairSeparator(options) +\n\t\t\t\t\t\tthis.#escapeArg(part2, false, options),\n\t\t\t\t);\n\t\t\t}\n\t\t}\n\n\t\treturn serializedEntries.join(this.#entrySeparator(options));\n\t}\n\n\tpublic print(options?: PrintOptions): PrintableShellCommand {\n\t\tconsole.log(this.getPrintableCommand(options));\n\t\treturn this;\n\t}\n\n\t/**\n\t * The returned child process includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313\n\t */\n\tpublic spawnNode<\n\t\tStdin extends NodeStdioNull | NodeStdioPipe,\n\t\tStdout extends NodeStdioNull | NodeStdioPipe,\n\t\tStderr extends NodeStdioNull | NodeStdioPipe,\n\t>(\n\t\toptions?:\n\t\t\t| NodeSpawnOptions\n\t\t\t| NodeSpawnOptionsWithoutStdio\n\t\t\t| NodeSpawnOptionsWithStdioTuple<Stdin, Stdout, Stderr>,\n\t): // TODO: figure out how to return `ChildProcessByStdio<\u2026>` without duplicating fragile boilerplate.\n\tNodeChildProcess & { success: Promise<void> } {\n\t\tconst { spawn } = process.getBuiltinModule(\"node:child_process\");\n\t\t// @ts-ignore: The TypeScript checker has trouble reconciling the optional (i.e. potentially `undefined`) `options` with the third argument.\n\t\tconst subprocess = spawn(...this.forNode(), options) as NodeChildProcess & {\n\t\t\tsuccess: Promise<void>;\n\t\t};\n\t\tObject.defineProperty(subprocess, \"success\", {\n\t\t\tget() {\n\t\t\t\treturn new Promise<void>((resolve, reject) =>\n\t\t\t\t\tthis.addListener(\n\t\t\t\t\t\t\"exit\",\n\t\t\t\t\t\t(exitCode: number /* we only use the first arg */) => {\n\t\t\t\t\t\t\tif (exitCode === 0) {\n\t\t\t\t\t\t\t\tresolve();\n\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\treject(`Command failed with non-zero exit code: ${exitCode}`);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t},\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t},\n\t\t\tenumerable: false,\n\t\t});\n\t\treturn subprocess;\n\t}\n\n\t/** A wrapper for `.spawnNode(\u2026)` that sets stdio to `\"inherit\"` (common for\n\t * invoking commands from scripts whose output and interaction should be\n\t * surfaced to the user). */\n\tpublic spawnNodeInherit(\n\t\toptions?: Omit<NodeSpawnOptions, \"stdio\">,\n\t): NodeChildProcess & { success: Promise<void> } {\n\t\tif (options && \"stdio\" in options) {\n\t\t\tthrow new Error(\"Unexpected `stdio` field.\");\n\t\t}\n\t\treturn this.spawnNode({ ...options, stdio: \"inherit\" });\n\t}\n\n\t/** Equivalent to:\n\t *\n\t * ```\n\t *     await this.print().spawnNodeInherit().success;\n\t * ```\n\t */\n\tpublic async shellOutNode(\n\t\toptions?: Omit<NodeSpawnOptions, \"stdio\">,\n\t): Promise<void> {\n\t\tawait this.print().spawnNodeInherit(options).success;\n\t}\n\n\t/**\n\t * The returned subprocess includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313\n\t */\n\tpublic spawnBun<\n\t\tconst In extends BunSpawnOptions.Writable = \"ignore\",\n\t\tconst Out extends BunSpawnOptions.Readable = \"pipe\",\n\t\tconst Err extends BunSpawnOptions.Readable = \"inherit\",\n\t>(\n\t\toptions?: Omit<BunSpawnOptions.OptionsObject<In, Out, Err>, \"cmd\">,\n\t): BunSubprocess<In, Out, Err> & { success: Promise<void> } {\n\t\tif (options && \"cmd\" in options) {\n\t\t\tthrow new Error(\"Unexpected `cmd` field.\");\n\t\t}\n\t\tconst { spawn } = process.getBuiltinModule(\"bun\") as typeof import(\"bun\");\n\t\tconst subprocess = spawn({\n\t\t\t...options,\n\t\t\tcmd: this.forBun(),\n\t\t}) as BunSubprocess<In, Out, Err> & { success: Promise<void> };\n\t\tObject.defineProperty(subprocess, \"success\", {\n\t\t\tget() {\n\t\t\t\treturn new Promise<void>((resolve, reject) =>\n\t\t\t\t\tthis.exited\n\t\t\t\t\t\t.then((exitCode: number) => {\n\t\t\t\t\t\t\tif (exitCode === 0) {\n\t\t\t\t\t\t\t\tresolve();\n\t\t\t\t\t\t\t} else {\n\t\t\t\t\t\t\t\treject(\n\t\t\t\t\t\t\t\t\tnew Error(\n\t\t\t\t\t\t\t\t\t\t`Command failed with non-zero exit code: ${exitCode}`,\n\t\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t})\n\t\t\t\t\t\t.catch(reject),\n\t\t\t\t);\n\t\t\t},\n\t\t\tenumerable: false,\n\t\t});\n\t\treturn subprocess;\n\t}\n\n\t/**\n\t * A wrapper for `.spawnBunInherit(\u2026)` that sets stdio to `\"inherit\"` (common\n\t * for invoking commands from scripts whose output and interaction should be\n\t * surfaced to the user).\n\t */\n\tpublic spawnBunInherit(\n\t\toptions?: Omit<\n\t\t\tOmit<\n\t\t\t\tBunSpawnOptions.OptionsObject<\"inherit\", \"inherit\", \"inherit\">,\n\t\t\t\t\"cmd\"\n\t\t\t>,\n\t\t\t\"stdio\"\n\t\t>,\n\t): BunSubprocess<\"inherit\", \"inherit\", \"inherit\"> & {\n\t\tsuccess: Promise<void>;\n\t} {\n\t\tif (options && \"stdio\" in options) {\n\t\t\tthrow new Error(\"Unexpected `stdio` field.\");\n\t\t}\n\t\treturn this.spawnBun({\n\t\t\t...options,\n\t\t\tstdio: [\"inherit\", \"inherit\", \"inherit\"],\n\t\t});\n\t}\n\n\t/** Equivalent to:\n\t *\n\t * ```\n\t *     new Response(this.spawnBun(options).stdout);\n\t * ```\n\t */\n\tpublic spawnBunStdout(\n\t\toptions?: Omit<\n\t\t\tOmit<\n\t\t\t\tBunSpawnOptions.OptionsObject<\"inherit\", \"inherit\", \"inherit\">,\n\t\t\t\t\"cmd\"\n\t\t\t>,\n\t\t\t\"stdio\"\n\t\t>,\n\t): Response {\n\t\t// biome-ignore lint/suspicious/noExplicitAny: Avoid breaking the lib check when used without `@types/bun`.\n\t\treturn new Response((this.spawnBun(options) as any).stdout);\n\t}\n\n\t/** Equivalent to:\n\t *\n\t * ```\n\t *     await this.print().spawnBunInherit().success;\n\t * ```\n\t */\n\tpublic async shellOutBun(\n\t\toptions?: Omit<\n\t\t\tOmit<\n\t\t\t\tBunSpawnOptions.OptionsObject<\"inherit\", \"inherit\", \"inherit\">,\n\t\t\t\t\"cmd\"\n\t\t\t>,\n\t\t\t\"stdio\"\n\t\t>,\n\t): Promise<void> {\n\t\tawait this.print().spawnBunInherit(options).success;\n\t}\n}\n"],
+  "mappings": ";AAaA,IAAM,2BAA2B;AACjC,IAAM,0BAA0B;AAChC,IAAM,iCAAiC;AAEvC,IAAM,mBAAmB;AACzB,IAAM,qBAAqB;AAG3B,SAAS,SAAS,GAAqB;AACtC,SAAO,OAAO,MAAM;AACrB;AA0BA,IAAM,2BAA2B,oBAAI,IAAI;AAAA,EACxC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACD,CAAC;AAGD,IAAM;AAAA;AAAA,EAEJ,yBAA4C,MAAM,oBAAI,IAAI,CAAC,GAAG,CAAC,CAAC;AAAA;AAE3D,IAAM,wBAAN,MAA4B;AAAA,EAElC,YACC,aACQ,OAAa,CAAC,GACrB;AADO;AAER,QAAI,CAAC,SAAS,WAAW,GAAG;AAE3B,YAAM,IAAI,MAAM,iCAAiC,WAAkB;AAAA,IACpE;AACA,SAAK,eAAe;AACpB,QAAI,OAAO,SAAS,aAAa;AAChC;AAAA,IACD;AACA,QAAI,CAAC,MAAM,QAAQ,IAAI,GAAG;AACzB,YAAM,IAAI,MAAM,oCAAoC;AAAA,IACrD;AACA,aAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACrC,YAAM,WAAW,KAAK,CAAC;AACvB,UAAI,OAAO,aAAa,UAAU;AACjC;AAAA,MACD;AACA,UACC,MAAM,QAAQ,QAAQ,KACtB,SAAS,WAAW,KACpB,SAAS,SAAS,CAAC,CAAC,KACpB,SAAS,SAAS,CAAC,CAAC,GACnB;AACD;AAAA,MACD;AACA,YAAM,IAAI,MAAM,+BAA+B,CAAC,EAAE;AAAA,IACnD;AAAA,EACD;AAAA,EA/BA;AAAA,EAiCA,IAAI,cAAsB;AACzB,WAAO,KAAK;AAAA,EACb;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYO,gBAA0B;AAChC,WAAO,CAAC,KAAK,aAAa,GAAG,KAAK,KAAK,KAAK,CAAC;AAAA,EAC9C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYO,SAAmB;AACzB,WAAO,KAAK,cAAc;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYO,wBAA4C;AAClD,WAAO,CAAC,KAAK,aAAa,KAAK,KAAK,KAAK,CAAC;AAAA,EAC3C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAaO,UAA8B;AACpC,WAAO,KAAK,sBAAsB;AAAA,EACnC;AAAA,EAEA,WACC,KACA,eACA,SACS;AACT,UAAM,gBAAgB,IAAI,IAAI,GAAG;AACjC,UAAM,yBAAyB,gBAC5B,4CACA;AACH,QACC,SAAS,YAAY;AAAA,IAEpB,cAAiC,aAAa,sBAAsB,EACnE,OAAO,GACR;AAED,YAAM,UAAU,IAAI,WAAW,MAAM,MAAM,EAAE,WAAW,KAAK,KAAK;AAClE,aAAO,IAAI,OAAO;AAAA,IACnB;AACA,WAAO;AAAA,EACR;AAAA,EAEA,iBAAiB,SAA+B;AAC/C,WAAO,SAAS,mBAAmB;AAAA,EACpC;AAAA,EAEA,gBAAgB,SAA+B;AAC9C,WACC,KAAK,iBAAiB,OAAO,KAC5B,SAAS,kBAAkB;AAAA,EAE9B;AAAA,EAEA,mBAAmB,SAA+B;AACjD,WAAO,qBAAqB,KAAK,gBAAgB,OAAO;AAAA,EACzD;AAAA,EAEA,kBAAkB,SAA+B;AAChD,YAAQ,SAAS,wBAAwB,gCAAgC;AAAA,MACxE,KAAK,YAAY;AAChB,eAAO;AAAA,MACR;AAAA,MACA,KAAK,mBAAmB;AACvB,eAAO,KAAK,mBAAmB,OAAO,IAAI,KAAK,gBAAgB,OAAO;AAAA,MACvE;AAAA,MACA,KAAK,eAAe;AACnB,eAAO,KAAK,mBAAmB,OAAO;AAAA,MACvC;AAAA,MACA,KAAK,UAAU;AACd,eAAO;AAAA,MACR;AAAA,MACA;AACC,cAAM,IAAI,MAAM,0CAA0C;AAAA,IAC5D;AAAA,EACD;AAAA,EAEA,gBAAgB,SAA+B;AAC9C,YAAQ,SAAS,wBAAwB,gCAAgC;AAAA,MACxE,KAAK,YAAY;AAChB,eAAO,qBAAqB,KAAK,gBAAgB,OAAO;AAAA,MACzD;AAAA,MACA,KAAK,mBAAmB;AACvB,eAAO,qBAAqB,KAAK,gBAAgB,OAAO;AAAA,MACzD;AAAA,MACA,KAAK,eAAe;AACnB,eAAO,qBAAqB,KAAK,gBAAgB,OAAO;AAAA,MACzD;AAAA,MACA,KAAK,UAAU;AACd,eAAO;AAAA,MACR;AAAA,MACA;AACC,cAAM,IAAI,MAAM,0CAA0C;AAAA,IAC5D;AAAA,EACD;AAAA,EAEO,oBAAoB,SAAgC;AAG1D,gBAAY,CAAC;AACb,UAAM,oBAA8B,CAAC;AAErC,sBAAkB;AAAA,MACjB,KAAK,iBAAiB,OAAO,IAC5B,KAAK,WAAW,KAAK,aAAa,MAAM,OAAO;AAAA,IACjD;AAEA,aAAS,IAAI,GAAG,IAAI,KAAK,KAAK,QAAQ,KAAK;AAC1C,YAAM,YAAY,KAAK,KAAK,CAAC;AAE7B,UAAI,SAAS,SAAS,GAAG;AACxB,0BAAkB,KAAK,KAAK,WAAW,WAAW,OAAO,OAAO,CAAC;AAAA,MAClE,OAAO;AACN,cAAM,CAAC,OAAO,KAAK,IAAI;AACvB,0BAAkB;AAAA,UACjB,KAAK,WAAW,OAAO,OAAO,OAAO,IACpC,KAAK,kBAAkB,OAAO,IAC9B,KAAK,WAAW,OAAO,OAAO,OAAO;AAAA,QACvC;AAAA,MACD;AAAA,IACD;AAEA,WAAO,kBAAkB,KAAK,KAAK,gBAAgB,OAAO,CAAC;AAAA,EAC5D;AAAA,EAEO,MAAM,SAA+C;AAC3D,YAAQ,IAAI,KAAK,oBAAoB,OAAO,CAAC;AAC7C,WAAO;AAAA,EACR;AAAA;AAAA;AAAA;AAAA,EAKO,UAKN,SAK6C;AAC7C,UAAM,EAAE,MAAM,IAAI,QAAQ,iBAAiB,oBAAoB;AAE/D,UAAM,aAAa,MAAM,GAAG,KAAK,QAAQ,GAAG,OAAO;AAGnD,WAAO,eAAe,YAAY,WAAW;AAAA,MAC5C,MAAM;AACL,eAAO,IAAI;AAAA,UAAc,CAAC,SAAS,WAClC,KAAK;AAAA,YACJ;AAAA,YACA,CAAC,aAAqD;AACrD,kBAAI,aAAa,GAAG;AACnB,wBAAQ;AAAA,cACT,OAAO;AACN,uBAAO,2CAA2C,QAAQ,EAAE;AAAA,cAC7D;AAAA,YACD;AAAA,UACD;AAAA,QACD;AAAA,MACD;AAAA,MACA,YAAY;AAAA,IACb,CAAC;AACD,WAAO;AAAA,EACR;AAAA;AAAA;AAAA;AAAA,EAKO,iBACN,SACgD;AAChD,QAAI,WAAW,WAAW,SAAS;AAClC,YAAM,IAAI,MAAM,2BAA2B;AAAA,IAC5C;AACA,WAAO,KAAK,UAAU,EAAE,GAAG,SAAS,OAAO,UAAU,CAAC;AAAA,EACvD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAa,aACZ,SACgB;AAChB,UAAM,KAAK,MAAM,EAAE,iBAAiB,OAAO,EAAE;AAAA,EAC9C;AAAA;AAAA;AAAA;AAAA,EAKO,SAKN,SAC2D;AAC3D,QAAI,WAAW,SAAS,SAAS;AAChC,YAAM,IAAI,MAAM,yBAAyB;AAAA,IAC1C;AACA,UAAM,EAAE,MAAM,IAAI,QAAQ,iBAAiB,KAAK;AAChD,UAAM,aAAa,MAAM;AAAA,MACxB,GAAG;AAAA,MACH,KAAK,KAAK,OAAO;AAAA,IAClB,CAAC;AACD,WAAO,eAAe,YAAY,WAAW;AAAA,MAC5C,MAAM;AACL,eAAO,IAAI;AAAA,UAAc,CAAC,SAAS,WAClC,KAAK,OACH,KAAK,CAAC,aAAqB;AAC3B,gBAAI,aAAa,GAAG;AACnB,sBAAQ;AAAA,YACT,OAAO;AACN;AAAA,gBACC,IAAI;AAAA,kBACH,2CAA2C,QAAQ;AAAA,gBACpD;AAAA,cACD;AAAA,YACD;AAAA,UACD,CAAC,EACA,MAAM,MAAM;AAAA,QACf;AAAA,MACD;AAAA,MACA,YAAY;AAAA,IACb,CAAC;AACD,WAAO;AAAA,EACR;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,gBACN,SASC;AACD,QAAI,WAAW,WAAW,SAAS;AAClC,YAAM,IAAI,MAAM,2BAA2B;AAAA,IAC5C;AACA,WAAO,KAAK,SAAS;AAAA,MACpB,GAAG;AAAA,MACH,OAAO,CAAC,WAAW,WAAW,SAAS;AAAA,IACxC,CAAC;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQO,eACN,SAOW;AAEX,WAAO,IAAI,SAAU,KAAK,SAAS,OAAO,EAAU,MAAM;AAAA,EAC3D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,MAAa,YACZ,SAOgB;AAChB,UAAM,KAAK,MAAM,EAAE,gBAAgB,OAAO,EAAE;AAAA,EAC7C;AACD;",
+  "names": []
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+	"name": "printable-shell-command",
+	"version": "0.1.0-pre1",
+	"main": "./src/index.ts",
+	"devDependencies": {
+		"@biomejs/biome": "^1.9.4",
+		"@cubing/dev-config": "^0.1.2",
+		"@types/bun": "^1.2.11",
+		"@types/node": "^22.15.3",
+		"esbuild": "^0.25.3"
+	},
+	"optionalDependencies": {
+		"@types/bun": "^1.2.11",
+		"@types/node": "^22.15.3"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/lib/printable-shell-command/index.js",
+			"import": "./dist/lib/printable-shell-command/index.d.ts"
+		}
+	},
+	"files": [
+		"./dist/",
+		"./src/"
+	],
+	"type": "module"
+}

package/src/index.ts

@@ -0,0 +1,446 @@
+import type {
+	ChildProcess as NodeChildProcess,
+	SpawnOptions as NodeSpawnOptions,
+	SpawnOptionsWithStdioTuple as NodeSpawnOptionsWithStdioTuple,
+	SpawnOptionsWithoutStdio as NodeSpawnOptionsWithoutStdio,
+	StdioNull as NodeStdioNull,
+	StdioPipe as NodeStdioPipe,
+} 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_LINE_END = " \\\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";
+	// 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
+const SPECIAL_SHELL_CHARACTERS = new Set([
+	" ",
+	'"',
+	"'",
+	"`",
+	"|",
+	"$",
+	"*",
+	"?",
+	">",
+	"<",
+	"(",
+	")",
+	"[",
+	"]",
+	"{",
+	"}",
+	"&",
+	"\\",
+	";",
+]);
+
+// https://mywiki.wooledge.org/BashGuide/SpecialCharacters
+const SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND =
+	// biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)
+	(SPECIAL_SHELL_CHARACTERS as unknown as any).union(new Set(["="]));
+
+export class PrintableShellCommand {
+	#commandName: string;
+	constructor(
+		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;
+		}
+		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}`);
+		}
+	}
+
+	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,
+		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" ||
+			// biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)
+			(argCharacters as unknown as any).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;
+	}
+
+	#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);
+	}
+
+	#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 {
+		// 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[] = [];
+
+		serializedEntries.push(
+			this.#mainIndentation(options) +
+				this.#escapeArg(this.commandName, true, options),
+		);
+
+		for (let i = 0; i < this.args.length; i++) {
+			const argsEntry = this.args[i];
+
+			if (isString(argsEntry)) {
+				serializedEntries.push(this.#escapeArg(argsEntry, false, options));
+			} else {
+				const [part1, part2] = argsEntry;
+				serializedEntries.push(
+					this.#escapeArg(part1, false, options) +
+						this.#argPairSeparator(options) +
+						this.#escapeArg(part2, false, options),
+				);
+			}
+		}
+
+		return serializedEntries.join(this.#entrySeparator(options));
+	}
+
+	public print(options?: PrintOptions): PrintableShellCommand {
+		console.log(this.getPrintableCommand(options));
+		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,
+		Stderr extends NodeStdioNull | NodeStdioPipe,
+	>(
+		options?:
+			| NodeSpawnOptions
+			| NodeSpawnOptionsWithoutStdio
+			| NodeSpawnOptionsWithStdioTuple<Stdin, Stdout, Stderr>,
+	): // 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>;
+		};
+		Object.defineProperty(subprocess, "success", {
+			get() {
+				return new Promise<void>((resolve, reject) =>
+					this.addListener(
+						"exit",
+						(exitCode: number /* we only use the first arg */) => {
+							if (exitCode === 0) {
+								resolve();
+							} else {
+								reject(`Command failed with non-zero exit code: ${exitCode}`);
+							}
+						},
+					),
+				);
+			},
+			enumerable: false,
+		});
+		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). */
+	public spawnNodeInherit(
+		options?: Omit<NodeSpawnOptions, "stdio">,
+	): NodeChildProcess & { success: Promise<void> } {
+		if (options && "stdio" in options) {
+			throw new Error("Unexpected `stdio` field.");
+		}
+		return this.spawnNode({ ...options, stdio: "inherit" });
+	}
+
+	/** Equivalent to:
+	 *
+	 * ```
+	 *     await this.print().spawnNodeInherit().success;
+	 * ```
+	 */
+	public async shellOutNode(
+		options?: Omit<NodeSpawnOptions, "stdio">,
+	): Promise<void> {
+		await this.print().spawnNodeInherit(options).success;
+	}
+
+	/**
+	 * 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> } {
+		if (options && "cmd" in options) {
+			throw new Error("Unexpected `cmd` field.");
+		}
+		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(
+									new Error(
+										`Command failed with non-zero exit code: ${exitCode}`,
+									),
+								);
+							}
+						})
+						.catch(reject),
+				);
+			},
+			enumerable: false,
+		});
+		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).
+	 */
+	public spawnBunInherit(
+		options?: Omit<
+			Omit<
+				BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">,
+				"cmd"
+			>,
+			"stdio"
+		>,
+	): BunSubprocess<"inherit", "inherit", "inherit"> & {
+		success: Promise<void>;
+	} {
+		if (options && "stdio" in options) {
+			throw new Error("Unexpected `stdio` field.");
+		}
+		return this.spawnBun({
+			...options,
+			stdio: ["inherit", "inherit", "inherit"],
+		});
+	}
+
+	/** Equivalent to:
+	 *
+	 * ```
+	 *     new Response(this.spawnBun(options).stdout);
+	 * ```
+	 */
+	public spawnBunStdout(
+		options?: Omit<
+			Omit<
+				BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">,
+				"cmd"
+			>,
+			"stdio"
+		>,
+	): Response {
+		// biome-ignore lint/suspicious/noExplicitAny: Avoid breaking the lib check when used without `@types/bun`.
+		return new Response((this.spawnBun(options) as any).stdout);
+	}
+
+	/** Equivalent to:
+	 *
+	 * ```
+	 *     await this.print().spawnBunInherit().success;
+	 * ```
+	 */
+	public async shellOutBun(
+		options?: Omit<
+			Omit<
+				BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">,
+				"cmd"
+			>,
+			"stdio"
+		>,
+	): Promise<void> {
+		await this.print().spawnBunInherit(options).success;
+	}
+}