printable-shell-command 2.7.4 → 3.0.1

package/dist/lib/printable-shell-command/index.d.ts

@@ -1,5 +1,5 @@
-import type { ChildProcessByStdio, ChildProcess as NodeChildProcess, SpawnOptions as NodeSpawnOptions } from "node:child_process";
-import { Writable } from "node:stream";
+import type { ChildProcessByStdio, SpawnOptions as NodeSpawnOptions } from "node:child_process";
+import { Readable, Writable } from "node:stream";
 import type { WriteStream } from "node:tty";
 import { styleText } from "node:util";
 import type { SpawnOptions as BunSpawnOptions, Subprocess as BunSubprocess, SpawnOptions } from "bun";
@@ -55,6 +55,15 @@ type BunCwd = SpawnOptions.OptionsObject<any, any, any>["cwd"] | Path;
 type BunWithCwd<T extends {
     cwd?: SpawnOptions.OptionsObject<any, any, any>["cwd"] | Path;
 }> = SetFieldType<T, "cwd", BunCwd | undefined>;
+export type StdinSource = {
+    text: string;
+} | {
+    json: any;
+} | {
+    path: string | Path;
+} | {
+    stream: Readable | ReadableStream;
+};
 export declare class PrintableShellCommand {
     #private;
     private args;
@@ -130,6 +139,15 @@ export declare class PrintableShellCommand {
      *
      */
     print(options?: StreamPrintOptions): PrintableShellCommand;
+    /**
+     * Send data to `stdin` of the subprocess.
+     *
+     * Note that this will overwrite:
+     *
+     * - Any previous value set using {@link PrintableShellCommand.stdin | `.stdin(…)`}.
+     * - Any value set for `stdin` using the `"stdio"` field of {@link PrintableShellCommand.spawn | `.spawn(…)`}.
+     */
+    stdin(source: StdinSource): PrintableShellCommand;
     /**
      * The returned child process includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
      */
@@ -143,8 +161,6 @@ export declare class PrintableShellCommand {
      * in its stead.
      */
     spawnTransparently(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>): ChildProcessByStdio<null, null, null> & WithSuccess;
-    /** @deprecated: Use `.spawnTransparently(…)`. */
-    spawnInherit(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>): NodeChildProcess & WithSuccess;
     /**
      * A wrapper for {@link PrintableShellCommand.spawn | `.spawn(…)`} that:
      *
@@ -153,27 +169,10 @@ export declare class PrintableShellCommand {
      * - calls `.unref()`, and
      * - does not wait for the process to exit.
      *
-     * This is similar to starting a command int he background and disowning it (in a shell).
-     *
-     * The `stdio` field is left overridable. To capture `stdout` and `stderr`, connect them to output files like this:
-     *
-     * ```
-     * import { open } from "node:fs/promises";
-     * import { Path } from "path-class";
-     * import { PrintableShellCommand } from "printable-shell-command";
-     *
-     * const tempDir = await Path.makeTempDir();
-     * console.log(`Temp dir: ${tempDir}`);
-     * const stdout = await open(tempDir.join("stdout.log").path, "a");
-     * const stderr = await open(tempDir.join("stderr.log").path, "a");
-     *
-     * new PrintableShellCommand("echo", ["hi"]).spawnDetached({
-     *   stdio: ["ignore", stdout.fd, stderr.fd],
-     * });
-     * ```
+     * This is similar to starting a command in the background and disowning it (in a shell).
      *
      */
-    spawnDetached(options?: NodeWithCwd<Omit<NodeSpawnOptions, "detached">>): void;
+    spawnDetached(options?: NodeWithCwd<Omit<Omit<NodeSpawnOptions, "stdio">, "detached">>): void;
     stdout(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>): Response;
     /**
      * Convenience function for:
@@ -191,6 +190,18 @@ export declare class PrintableShellCommand {
      * This can make some simple invocations easier to read and/or fit on a single line.
      */
     json<T>(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>): Promise<T>;
+    /**
+     * Parse `stdout` into a generator of string values using a NULL delimiter.
+     *
+     * A trailing NULL delimiter from `stdout` is required and removed.
+     */
+    text0(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>): AsyncGenerator<string>;
+    /**
+     * Parse `stdout` into a generator of JSON values using a NULL delimiter.
+     *
+     * A trailing NULL delimiter from `stdout` is required and removed.
+     */
+    json0(options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>): AsyncGenerator<any>;
     /** Equivalent to:
      *
      * ```
@@ -226,4 +237,5 @@ export declare class PrintableShellCommand {
         shellOutBun: (options?: BunWithCwd<Omit<BunSpawnOptions.OptionsObject<"inherit", "inherit", "inherit">, "cmd" | "stdio">>) => Promise<void>;
     };
 }
+export declare function escapeArg(arg: string, isMainCommand: boolean, options: PrintOptions): string;
 export {};

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

@@ -1,4 +1,6 @@
 // src/index.ts
+import assert from "node:assert";
+import { createReadStream } from "node:fs";
 import { stderr } from "node:process";
 import { Readable, Writable } from "node:stream";
 import { styleText } from "node:util";
@@ -50,6 +52,7 @@ 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 STDIN_SOURCE_KEYS = ["text", "json", "path", "stream"];
 var PrintableShellCommand = class {
   constructor(commandName, args = []) {
     this.args = args;
@@ -148,16 +151,6 @@ var PrintableShellCommand = class {
   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;
   }
@@ -214,16 +207,14 @@ var PrintableShellCommand = class {
     for (let i = 0; i < this.args.length; i++) {
       const argsEntry = stringifyIfPath(this.args[i]);
       if (isString(argsEntry)) {
-        serializedEntries.push(this.#escapeArg(argsEntry, false, options));
+        serializedEntries.push(escapeArg(argsEntry, false, options));
       } else {
         serializedEntries.push(
-          argsEntry.map(
-            (part) => this.#escapeArg(stringifyIfPath(part), false, options)
-          ).join(this.#argPairSeparator(options))
+          argsEntry.map((part) => escapeArg(stringifyIfPath(part), false, options)).join(this.#argPairSeparator(options))
         );
       }
     }
-    let text = this.#mainIndentation(options) + this.#escapeArg(this.commandName, true, options) + this.#separatorAfterCommand(options, serializedEntries.length) + serializedEntries.join(this.#intraEntrySeparator(options));
+    let text = this.#mainIndentation(options) + escapeArg(this.commandName, true, options) + this.#separatorAfterCommand(options, serializedEntries.length) + serializedEntries.join(this.#intraEntrySeparator(options));
     if (options?.styleTextFormat) {
       text = styleText(options.styleTextFormat, text);
     }
@@ -247,12 +238,38 @@ var PrintableShellCommand = class {
     writable.write("\n");
     return this;
   }
+  #stdinSource;
+  /**
+   * Send data to `stdin` of the subprocess.
+   *
+   * Note that this will overwrite:
+   *
+   * - Any previous value set using {@link PrintableShellCommand.stdin | `.stdin(…)`}.
+   * - Any value set for `stdin` using the `"stdio"` field of {@link PrintableShellCommand.spawn | `.spawn(…)`}.
+   */
+  stdin(source) {
+    const [key, ...moreKeys] = Object.keys(source);
+    assert.equal(moreKeys.length, 0);
+    assert(STDIN_SOURCE_KEYS.includes(key));
+    this.#stdinSource = source;
+    return this;
+  }
   /**
    * The returned child process includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
    */
   spawn = ((options) => {
     const { spawn } = process.getBuiltinModule("node:child_process");
     const cwd = stringifyIfPath(options?.cwd);
+    if (this.#stdinSource) {
+      options ??= {};
+      if (typeof options.stdio === "undefined") {
+        options.stdio = "pipe";
+      }
+      if (typeof options.stdio === "string") {
+        options.stdio = new Array(3).fill(options.stdio);
+      }
+      options.stdio[0] = "pipe";
+    }
     const subprocess = spawn(...this.forNode(), {
       ...options,
       cwd
@@ -274,6 +291,47 @@ var PrintableShellCommand = class {
       },
       enumerable: false
     });
+    if (subprocess.stdout) {
+      const s = subprocess;
+      s.stdout.response = () => new Response(Readable.from(this.#generator(s.stdout, s.success)));
+      s.stdout.text = () => s.stdout.response().text();
+      const thisCached = this;
+      s.stdout.text0 = async function* () {
+        yield* thisCached.#split0(thisCached.#generator(s.stdout, s.success));
+      };
+      s.stdout.json = () => s.stdout.response().json();
+    }
+    if (subprocess.stderr) {
+      const s = subprocess;
+      s.stderr.response = () => new Response(Readable.from(this.#generator(s.stderr, s.success)));
+      s.stderr.text = () => s.stderr.response().text();
+      const thisCached = this;
+      s.stderr.text0 = async function* () {
+        yield* thisCached.#split0(thisCached.#generator(s.stderr, s.success));
+      };
+      s.stderr.json = () => s.stderr.response().json();
+    }
+    if (this.#stdinSource) {
+      const { stdin } = subprocess;
+      assert(stdin);
+      if ("text" in this.#stdinSource) {
+        stdin.write(this.#stdinSource.text);
+        stdin.end();
+      } else if ("json" in this.#stdinSource) {
+        stdin.write(JSON.stringify(this.#stdinSource.json));
+        stdin.end();
+      } else if ("path" in this.#stdinSource) {
+        createReadStream(stringifyIfPath(this.#stdinSource.path)).pipe(stdin);
+      } else if ("stream" in this.#stdinSource) {
+        const stream = (() => {
+          const { stream: stream2 } = this.#stdinSource;
+          return stream2 instanceof Readable ? stream2 : Readable.fromWeb(stream2);
+        })();
+        stream.pipe(stdin);
+      } else {
+        throw new Error("Invalid `.stdin(\u2026)` source?");
+      }
+    }
     return subprocess;
   });
   /** A wrapper for `.spawn(…)` that sets stdio to `"inherit"` (common for
@@ -290,10 +348,6 @@ var PrintableShellCommand = class {
     }
     return this.spawn({ ...options, stdio: "inherit" });
   }
-  /** @deprecated: Use `.spawnTransparently(…)`. */
-  spawnInherit(options) {
-    return this.spawnTransparently(options);
-  }
   /**
    * A wrapper for {@link PrintableShellCommand.spawn | `.spawn(…)`} that:
    *
@@ -302,29 +356,16 @@ var PrintableShellCommand = class {
    * - calls `.unref()`, and
    * - does not wait for the process to exit.
    *
-   * This is similar to starting a command int he background and disowning it (in a shell).
-   *
-   * The `stdio` field is left overridable. To capture `stdout` and `stderr`, connect them to output files like this:
-   *
-   * ```
-   * import { open } from "node:fs/promises";
-   * import { Path } from "path-class";
-   * import { PrintableShellCommand } from "printable-shell-command";
-   *
-   * const tempDir = await Path.makeTempDir();
-   * console.log(`Temp dir: ${tempDir}`);
-   * const stdout = await open(tempDir.join("stdout.log").path, "a");
-   * const stderr = await open(tempDir.join("stderr.log").path, "a");
-   *
-   * new PrintableShellCommand("echo", ["hi"]).spawnDetached({
-   *   stdio: ["ignore", stdout.fd, stderr.fd],
-   * });
-   * ```
+   * This is similar to starting a command in the background and disowning it (in a shell).
    *
    */
   spawnDetached(options) {
-    if (options && "detached" in options) {
-      throw new Error("Unexpected `detached` field.");
+    if (options) {
+      for (const field of ["stdio", "detached"]) {
+        if (field in options) {
+          throw new Error(`Unexpected \`${field}\` field.`);
+        }
+      }
     }
     const childProcess = this.spawn({
       stdio: "ignore",
@@ -333,7 +374,15 @@ var PrintableShellCommand = class {
     });
     childProcess.unref();
   }
-  stdout(options) {
+  #generator(readable, successPromise) {
+    return (async function* () {
+      for await (const chunk of readable) {
+        yield chunk;
+      }
+      await successPromise;
+    })();
+  }
+  #stdoutSpawnGenerator(options) {
     if (options && "stdio" in options) {
       throw new Error("Unexpected `stdio` field.");
     }
@@ -341,7 +390,24 @@ var PrintableShellCommand = class {
       ...options,
       stdio: ["ignore", "pipe", "inherit"]
     });
-    return new Response(Readable.toWeb(subprocess.stdout));
+    return this.#generator(subprocess.stdout, subprocess.success);
+  }
+  stdout(options) {
+    return new Response(Readable.from(this.#stdoutSpawnGenerator(options)));
+  }
+  async *#split0(generator) {
+    let pending = "";
+    for await (const chunk of generator) {
+      pending += chunk;
+      const newChunks = pending.split("\0");
+      pending = newChunks.splice(-1)[0];
+      yield* newChunks;
+    }
+    if (pending !== "") {
+      throw new Error(
+        "Missing a trailing NUL character at the end of a NUL-delimited stream."
+      );
+    }
   }
   /**
    * Convenience function for:
@@ -363,6 +429,26 @@ var PrintableShellCommand = class {
   json(options) {
     return this.stdout(options).json();
   }
+  /**
+   * Parse `stdout` into a generator of string values using a NULL delimiter.
+   *
+   * A trailing NULL delimiter from `stdout` is required and removed.
+   */
+  async *text0(options) {
+    yield* this.#split0(this.#stdoutSpawnGenerator(options));
+  }
+  /**
+   * Parse `stdout` into a generator of JSON values using a NULL delimiter.
+   *
+   * A trailing NULL delimiter from `stdout` is required and removed.
+   */
+  async *json0(options) {
+    for await (const part of this.#split0(
+      this.#stdoutSpawnGenerator(options)
+    )) {
+      yield JSON.parse(part);
+    }
+  }
   /** Equivalent to:
    *
    * ```
@@ -445,7 +531,18 @@ var PrintableShellCommand = class {
     shellOutBun: this.#shellOutBun.bind(this)
   };
 };
+function 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;
+}
 export {
-  PrintableShellCommand
+  PrintableShellCommand,
+  escapeArg
 };
 //# sourceMappingURL=index.js.map

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/index.ts"],
-  "sourcesContent": ["import type {\n  ChildProcessByStdio,\n  ChildProcess as NodeChildProcess,\n  SpawnOptions as NodeSpawnOptions,\n} from \"node:child_process\";\nimport { stderr } from \"node:process\";\nimport { Readable, Writable } from \"node:stream\";\nimport type { WriteStream } from \"node:tty\";\nimport { styleText } from \"node:util\";\nimport type {\n  SpawnOptions as BunSpawnOptions,\n  Subprocess as BunSubprocess,\n  SpawnOptions,\n} from \"bun\";\nimport { Path, stringifyIfPath } from \"path-class\";\nimport type { SetFieldType } from \"type-fest\";\nimport type { NodeWithCwd, spawnType, WithSuccess } from \"./spawn\";\n\n// TODO: does this import work?\n/**\n * @import { stdout } from \"node:process\"\n */\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\ntype StyleTextFormat = Parameters<typeof styleText>[0];\n\nconst TTY_AUTO_STYLE: StyleTextFormat = [\"gray\", \"bold\"];\n\n// biome-ignore lint/suspicious/noExplicitAny: This is the correct type nere.\nfunction isString(s: any): s is string {\n  return typeof s === \"string\";\n}\n\n// biome-ignore lint/suspicious/noExplicitAny: This is the correct type here.\nfunction isValidArgsEntryArray(entries: any[]): entries is SingleArgument[] {\n  for (const entry of entries) {\n    if (isString(entry)) {\n      continue;\n    }\n    if (entry instanceof Path) {\n      continue;\n    }\n    return false;\n  }\n  return true;\n}\n\n// TODO: allow `.toString()`ables?\ntype SingleArgument = string | Path;\ntype ArgsEntry = SingleArgument | SingleArgument[];\ntype Args = ArgsEntry[];\n\nexport interface PrintOptions {\n  /** Defaults to \"\" */\n  mainIndentation?: string;\n  /** Defaults to \"  \" */\n  argIndentation?: string;\n  /**\n   * - `\"auto\"`: Quote only arguments that need it for safety. This tries to be\n   *   portable and safe across shells, but true safety and portability is hard\n   *   to guarantee.\n   * - `\"extra-safe\"`: Quote all arguments, even ones that don't need it. This is\n   *   more likely to be safe under all circumstances.\n   */\n  quoting?: \"auto\" | \"extra-safe\";\n  /** Line wrapping to use between arguments. Defaults to `\"by-entry\"`. */\n  argumentLineWrapping?:\n    | \"by-entry\"\n    | \"nested-by-entry\"\n    | \"by-argument\"\n    | \"inline\";\n  /** Include the first arg (or first arg group) on the same line as the command, regardless of the `argumentLineWrapping` setting. */\n  skipLineWrapBeforeFirstArg?: true | false;\n  /**\n   * Style text using `node`'s {@link styleText | `styleText(\u2026)`}.\n   *\n   * Example usage:\n   *\n   * ```\n   * new PrintableShellCommand(\"echo\", [\"hi\"]).print({\n   *   styleTextFormat: [\"green\", \"underline\"],\n   * });\n   * */\n  styleTextFormat?: StyleTextFormat;\n}\n\nexport interface StreamPrintOptions extends PrintOptions {\n  /**\n   * Auto-style the text when:\n   *\n   * - the output stream is detected to be a TTY\n   * - `styleTextFormat` is not specified.\n   *\n   * The current auto style is: `[\"gray\", \"bold\"]`\n   */\n  autoStyle?: \"tty\" | \"never\";\n  // This would be a `WritableStream` (open web standard), but `WriteStream` allows us to query `.isTTY`.\n  stream?: WriteStream | Writable;\n}\n\n// https://mywiki.wooledge.org/BashGuide/SpecialCharacters\nconst SPECIAL_SHELL_CHARACTERS = new Set([\n  \" \",\n  '\"',\n  \"'\",\n  \"`\",\n  \"|\",\n  \"$\",\n  \"*\",\n  \"?\",\n  \">\",\n  \"<\",\n  \"(\",\n  \")\",\n  \"[\",\n  \"]\",\n  \"{\",\n  \"}\",\n  \"&\",\n  \"\\\\\",\n  \";\",\n  \"#\",\n]);\n\n// https://mywiki.wooledge.org/BashGuide/SpecialCharacters\nconst SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND =\n  // biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)\n  (SPECIAL_SHELL_CHARACTERS as unknown as any).union(new Set([\"=\"]));\n\n// biome-ignore lint/suspicious/noExplicitAny: Just matching\ntype BunCwd = SpawnOptions.OptionsObject<any, any, any>[\"cwd\"] | Path;\ntype BunWithCwd<\n  // biome-ignore lint/suspicious/noExplicitAny: Just matching\n  T extends { cwd?: SpawnOptions.OptionsObject<any, any, any>[\"cwd\"] | Path },\n> = SetFieldType<T, \"cwd\", BunCwd | undefined>;\n\nexport class PrintableShellCommand {\n  #commandName: string | Path;\n  constructor(\n    commandName: string | Path,\n    private args: Args = [],\n  ) {\n    if (!isString(commandName) && !(commandName instanceof Path)) {\n      // biome-ignore lint/suspicious/noExplicitAny: We want to print this, no matter what it is.\n      throw new Error(\"Command name is not a string:\", commandName as any);\n    }\n    this.#commandName = commandName;\n    if (typeof args === \"undefined\") {\n      return;\n    }\n    if (!Array.isArray(args)) {\n      throw new Error(\"Command arguments are not an array\");\n    }\n    for (let i = 0; i < args.length; i++) {\n      const argEntry = args[i];\n      if (typeof argEntry === \"string\") {\n        continue;\n      }\n      if (argEntry instanceof Path) {\n        continue;\n      }\n      if (Array.isArray(argEntry) && isValidArgsEntryArray(argEntry)) {\n        continue;\n      }\n      throw new Error(`Invalid arg entry at index: ${i}`);\n    }\n  }\n\n  get commandName(): string {\n    return stringifyIfPath(this.#commandName);\n  }\n\n  /** For use with `bun`.\n   *\n   * Usage example:\n   *\n   * ```\n   * import { PrintableShellCommand } from \"printable-shell-command\";\n   * import { spawn } from \"bun\";\n   *\n   * const command = new PrintableShellCommand( \u2026 );\n   * await spawn(command.toFlatCommand()).exited;\n   * ```\n   */\n  public toFlatCommand(): string[] {\n    return [this.commandName, ...this.args.flat().map(stringifyIfPath)];\n  }\n\n  /**\n   * Convenient alias for {@link PrintableShellCommand.toFlatCommand | `.toFlatCommand()`}.\n   *\n   * Usage example:\n   *\n   * ```\n   * import { PrintableShellCommand } from \"printable-shell-command\";\n   * import { spawn } from \"bun\";\n   *\n   * const command = new PrintableShellCommand( \u2026 );\n   * await spawn(command.forBun()).exited;\n   * ```\n   *\n   * */\n  public forBun(): string[] {\n    return this.toFlatCommand();\n  }\n\n  /**\n   * For use with `node:child_process`\n   *\n   * Usage example:\n   *\n   * ```\n   * import { PrintableShellCommand } from \"printable-shell-command\";\n   * import { spawn } from \"node:child_process\";\n   *\n   * const command = new PrintableShellCommand( \u2026 );\n   * const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`\n   * ```\n   *\n   */\n  public toCommandWithFlatArgs(): [string, string[]] {\n    return [this.commandName, this.args.flat().map(stringifyIfPath)];\n  }\n\n  /**\n   * For use with `node:child_process`\n   *\n   * Usage example:\n   *\n   * ```\n   * import { PrintableShellCommand } from \"printable-shell-command\";\n   * import { spawn } from \"node:child_process\";\n   *\n   * const command = new PrintableShellCommand( \u2026 );\n   * const child_process = spawn(...command.forNode()); // Note the `...`\n   * ```\n   *\n   * Convenient alias for {@link PrintableShellCommand.toCommandWithFlatArgs | `toCommandWithFlatArgs()`}.\n   */\n  public forNode(): [string, string[]] {\n    return this.toCommandWithFlatArgs();\n  }\n\n  #escapeArg(\n    arg: string,\n    isMainCommand: boolean,\n    options: PrintOptions,\n  ): string {\n    const argCharacters = new Set(arg);\n    const specialShellCharacters = isMainCommand\n      ? SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND\n      : SPECIAL_SHELL_CHARACTERS;\n    if (\n      options?.quoting === \"extra-safe\" ||\n      // biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)\n      (argCharacters as unknown as any).intersection(specialShellCharacters)\n        .size > 0\n    ) {\n      // Use single quote to reduce the need to escape (and therefore reduce the chance for bugs/security issues).\n      const escaped = arg.replaceAll(\"\\\\\", \"\\\\\\\\\").replaceAll(\"'\", \"\\\\'\");\n      return `'${escaped}'`;\n    }\n    return arg;\n  }\n\n  #mainIndentation(options: PrintOptions): string {\n    return options?.mainIndentation ?? DEFAULT_MAIN_INDENTATION;\n  }\n\n  #argIndentation(options: PrintOptions): string {\n    return (\n      this.#mainIndentation(options) +\n      (options?.argIndentation ?? DEFAULT_ARG_INDENTATION)\n    );\n  }\n\n  #lineWrapSeparator(options: PrintOptions): string {\n    return LINE_WRAP_LINE_END + this.#argIndentation(options);\n  }\n\n  #argPairSeparator(options: PrintOptions): string {\n    switch (options?.argumentLineWrapping ?? DEFAULT_ARGUMENT_LINE_WRAPPING) {\n      case \"by-entry\": {\n        return INLINE_SEPARATOR;\n      }\n      case \"nested-by-entry\": {\n        return this.#lineWrapSeparator(options) + this.#argIndentation(options);\n      }\n      case \"by-argument\": {\n        return this.#lineWrapSeparator(options);\n      }\n      case \"inline\": {\n        return INLINE_SEPARATOR;\n      }\n      default:\n        throw new Error(\"Invalid argument line wrapping argument.\");\n    }\n  }\n\n  #intraEntrySeparator(options: PrintOptions): string {\n    switch (options?.argumentLineWrapping ?? DEFAULT_ARGUMENT_LINE_WRAPPING) {\n      case \"by-entry\":\n      case \"nested-by-entry\":\n      case \"by-argument\": {\n        return LINE_WRAP_LINE_END + this.#argIndentation(options);\n      }\n      case \"inline\": {\n        return INLINE_SEPARATOR;\n      }\n      default:\n        throw new Error(\"Invalid argument line wrapping argument.\");\n    }\n  }\n\n  #separatorAfterCommand(\n    options: PrintOptions,\n    numFollowingEntries: number,\n  ): string {\n    if (numFollowingEntries === 0) {\n      return \"\";\n    }\n    if (options.skipLineWrapBeforeFirstArg ?? false) {\n      return INLINE_SEPARATOR;\n    }\n    return this.#intraEntrySeparator(options);\n  }\n\n  public getPrintableCommand(options?: PrintOptions): string {\n    // TODO: Why in the world does TypeScript not give the `options` arg the type of `PrintOptions | undefined`???\n    options ??= {};\n    const serializedEntries: string[] = [];\n\n    for (let i = 0; i < this.args.length; i++) {\n      const argsEntry = stringifyIfPath(this.args[i]);\n\n      if (isString(argsEntry)) {\n        serializedEntries.push(this.#escapeArg(argsEntry, false, options));\n      } else {\n        serializedEntries.push(\n          argsEntry\n            .map((part) =>\n              this.#escapeArg(stringifyIfPath(part), false, options),\n            )\n            .join(this.#argPairSeparator(options)),\n        );\n      }\n    }\n\n    let text =\n      this.#mainIndentation(options) +\n      this.#escapeArg(this.commandName, true, options) +\n      this.#separatorAfterCommand(options, serializedEntries.length) +\n      serializedEntries.join(this.#intraEntrySeparator(options));\n    if (options?.styleTextFormat) {\n      text = styleText(options.styleTextFormat, text);\n    }\n    return text;\n  }\n\n  /**\n   * Print the shell command to {@link stderr} (default) or a specified stream.\n   *\n   * By default, this will be auto-styled (as bold gray) when `.isTTY` is true\n   * for the stream. `.isTTY` is populated for the {@link stderr} and\n   * {@link stdout} objects. Pass `\"autoStyle\": \"never\"` or an explicit\n   * `styleTextFormat` to disable this.\n   *\n   */\n  public print(options?: StreamPrintOptions): PrintableShellCommand {\n    const stream = options?.stream ?? stderr;\n    // Note: we only need to modify top-level fields, so `structuredClone(\u2026)`\n    // would be overkill and can only cause performance issues.\n    const optionsCopy = { ...options };\n    optionsCopy.styleTextFormat ??=\n      options?.autoStyle !== \"never\" &&\n      (stream as { isTTY?: boolean }).isTTY === true\n        ? TTY_AUTO_STYLE\n        : undefined;\n    const writable =\n      stream instanceof Writable ? stream : Writable.fromWeb(stream);\n    writable.write(this.getPrintableCommand(optionsCopy));\n    writable.write(\"\\n\");\n    return this;\n  }\n\n  /**\n   * The returned child process includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313\n   */\n  public spawn: typeof spawnType = ((\n    options?: Parameters<typeof spawnType>[0],\n  ) => {\n    const { spawn } = process.getBuiltinModule(\"node:child_process\");\n    const cwd = stringifyIfPath(options?.cwd);\n    // biome-ignore lint/suspicious/noTsIgnore: We don't want linting to depend on *broken* type checking.\n    // @ts-ignore: The TypeScript checker has trouble reconciling the optional (i.e. potentially `undefined`) `options` with the third argument.\n    const subprocess = spawn(...this.forNode(), {\n      ...(options as object),\n      cwd,\n    }) as NodeChildProcess & {\n      success: Promise<void>;\n    };\n    Object.defineProperty(subprocess, \"success\", {\n      get() {\n        return new Promise<void>((resolve, reject) =>\n          this.addListener(\n            \"exit\",\n            (exitCode: number /* we only use the first arg */) => {\n              if (exitCode === 0) {\n                resolve();\n              } else {\n                reject(`Command failed with non-zero exit code: ${exitCode}`);\n              }\n            },\n          ),\n        );\n      },\n      enumerable: false,\n    });\n    return subprocess;\n    // biome-ignore lint/suspicious/noExplicitAny: Type wrangling\n  }) as any;\n\n  /** A wrapper for `.spawn(\u2026)` that sets stdio to `\"inherit\"` (common for\n   * invoking commands from scripts whose output and interaction should be\n   * surfaced to the user).\n   *\n   * If there is no other interaction with the shell from the calling process,\n   * then it acts \"transparent\" and allows user to interact with the subprocess\n   * in its stead.\n   */\n  public spawnTransparently(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): ChildProcessByStdio<null, null, null> & WithSuccess {\n    if (options && \"stdio\" in options) {\n      throw new Error(\"Unexpected `stdio` field.\");\n    }\n\n    // biome-ignore lint/suspicious/noExplicitAny: Type wrangling.\n    return this.spawn({ ...options, stdio: \"inherit\" }) as any;\n  }\n\n  /** @deprecated: Use `.spawnTransparently(\u2026)`. */\n  public spawnInherit(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): NodeChildProcess & WithSuccess {\n    return this.spawnTransparently(options);\n  }\n\n  /**\n   * A wrapper for {@link PrintableShellCommand.spawn | `.spawn(\u2026)`} that:\n   *\n   * - sets `detached` to `true`,\n   * - sets stdio to `\"inherit\"`,\n   * - calls `.unref()`, and\n   * - does not wait for the process to exit.\n   *\n   * This is similar to starting a command int he background and disowning it (in a shell).\n   *\n   * The `stdio` field is left overridable. To capture `stdout` and `stderr`, connect them to output files like this:\n   *\n   * ```\n   * import { open } from \"node:fs/promises\";\n   * import { Path } from \"path-class\";\n   * import { PrintableShellCommand } from \"printable-shell-command\";\n   *\n   * const tempDir = await Path.makeTempDir();\n   * console.log(`Temp dir: ${tempDir}`);\n   * const stdout = await open(tempDir.join(\"stdout.log\").path, \"a\");\n   * const stderr = await open(tempDir.join(\"stderr.log\").path, \"a\");\n   *\n   * new PrintableShellCommand(\"echo\", [\"hi\"]).spawnDetached({\n   *   stdio: [\"ignore\", stdout.fd, stderr.fd],\n   * });\n   * ```\n   *\n   */\n  public spawnDetached(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"detached\">>,\n  ): void {\n    if (options && \"detached\" in options) {\n      throw new Error(\"Unexpected `detached` field.\");\n    }\n    const childProcess = this.spawn({\n      stdio: \"ignore\",\n      ...options,\n      detached: true,\n    });\n    childProcess.unref();\n  }\n\n  public stdout(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): Response {\n    if (options && \"stdio\" in options) {\n      throw new Error(\"Unexpected `stdio` field.\");\n    }\n    const subprocess = this.spawn({\n      ...options,\n      stdio: [\"ignore\", \"pipe\", \"inherit\"],\n    });\n\n    return new Response(Readable.toWeb(subprocess.stdout));\n  }\n\n  /**\n   * Convenience function for:\n   *\n   *     .stdout(options).text()\n   *\n   * This can make some simple invocations easier to read and/or fit on a single line.\n   */\n  public text(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): Promise<string> {\n    return this.stdout(options).text();\n  }\n\n  /**\n   * Convenience function for:\n   *\n   *     .stdout(options).json()\n   *\n   * This can make some simple invocations easier to read and/or fit on a single line.\n   */\n  public json<T>(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): Promise<T> {\n    return this.stdout(options).json() as Promise<T>;\n  }\n\n  /** Equivalent to:\n   *\n   * ```\n   * await this.print().spawnTransparently(\u2026).success;\n   * ```\n   */\n  public async shellOut(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): Promise<void> {\n    await this.print().spawnTransparently(options).success;\n  }\n\n  /**\n   * The returned subprocess includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313\n   */\n  #spawnBun<\n    const In extends BunSpawnOptions.Writable = \"ignore\",\n    const Out extends BunSpawnOptions.Readable = \"pipe\",\n    const Err extends BunSpawnOptions.Readable = \"inherit\",\n  >(\n    options?: BunWithCwd<\n      Omit<BunSpawnOptions.OptionsObject<In, Out, Err>, \"cmd\">\n    >,\n  ): BunSubprocess<In, Out, Err> & { success: Promise<void> } {\n    if (options && \"cmd\" in options) {\n      throw new Error(\"Unexpected `cmd` field.\");\n    }\n    const { spawn } = process.getBuiltinModule(\"bun\") as typeof import(\"bun\");\n    const cwd = stringifyIfPath(options?.cwd);\n    const subprocess = spawn({\n      ...options,\n      cwd,\n      cmd: this.forBun(),\n    }) as BunSubprocess<In, Out, Err> & { success: Promise<void> };\n    Object.defineProperty(subprocess, \"success\", {\n      get() {\n        return new Promise<void>((resolve, reject) =>\n          this.exited\n            .then((exitCode: number) => {\n              if (exitCode === 0) {\n                resolve();\n              } else {\n                reject(\n                  new Error(\n                    `Command failed with non-zero exit code: ${exitCode}`,\n                  ),\n                );\n              }\n            })\n            .catch(reject),\n        );\n      },\n      enumerable: false,\n    });\n    return subprocess;\n  }\n\n  #spawnBunInherit(\n    options?: BunWithCwd<\n      Omit<\n        BunSpawnOptions.OptionsObject<\"inherit\", \"inherit\", \"inherit\">,\n        \"cmd\" | \"stdio\"\n      >\n    >,\n  ): BunSubprocess<\"inherit\", \"inherit\", \"inherit\"> & {\n    success: Promise<void>;\n  } {\n    if (options && \"stdio\" in options) {\n      throw new Error(\"Unexpected `stdio` field.\");\n    }\n    return this.bun.spawnBun({\n      ...options,\n      stdio: [\"inherit\", \"inherit\", \"inherit\"],\n    });\n  }\n\n  #spawnBunStdout(\n    options?: BunWithCwd<\n      Omit<\n        BunSpawnOptions.OptionsObject<\"inherit\", \"inherit\", \"inherit\">,\n        \"cmd\" | \"stdio\"\n      >\n    >,\n  ): Response {\n    // biome-ignore lint/suspicious/noExplicitAny: Avoid breaking the lib check when used without `@types/bun`.\n    return new Response((this.bun.spawnBun(options) as any).stdout);\n  }\n\n  async #shellOutBun(\n    options?: BunWithCwd<\n      Omit<\n        BunSpawnOptions.OptionsObject<\"inherit\", \"inherit\", \"inherit\">,\n        \"cmd\" | \"stdio\"\n      >\n    >,\n  ): Promise<void> {\n    await this.print().bun.spawnBunInherit(options).success;\n  }\n\n  bun = {\n    /** Equivalent to:\n     *\n     * ```\n     * await this.print().bun.spawnBunInherit(\u2026).success;\n     * ```\n     */\n    spawnBun: this.#spawnBun.bind(this),\n    /**\n     * A wrapper for `.spawnBunInherit(\u2026)` that sets stdio to `\"inherit\"` (common\n     * for invoking commands from scripts whose output and interaction should be\n     * surfaced to the user).\n     */\n    spawnBunInherit: this.#spawnBunInherit.bind(this),\n    /** Equivalent to:\n     *\n     * ```\n     * new Response(this.bun.spawnBun(\u2026).stdout);\n     * ```\n     */\n    spawnBunStdout: this.#spawnBunStdout.bind(this),\n    shellOutBun: this.#shellOutBun.bind(this),\n  };\n}\n"],
-  "mappings": "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",
-  "names": []
+  "sourcesContent": ["import assert from \"node:assert\";\nimport type {\n  ChildProcessByStdio,\n  ChildProcess as NodeChildProcess,\n  SpawnOptions as NodeSpawnOptions,\n} from \"node:child_process\";\nimport { createReadStream } from \"node:fs\";\nimport { stderr } from \"node:process\";\nimport { Readable, Writable } from \"node:stream\";\nimport type { WriteStream } from \"node:tty\";\nimport { styleText } from \"node:util\";\nimport type {\n  SpawnOptions as BunSpawnOptions,\n  Subprocess as BunSubprocess,\n  SpawnOptions,\n} from \"bun\";\nimport { Path, stringifyIfPath } from \"path-class\";\nimport type { SetFieldType } from \"type-fest\";\nimport type {\n  NodeWithCwd,\n  spawnType,\n  WithStderrResponse,\n  WithStdoutResponse,\n  WithSuccess,\n} from \"./spawn\";\n\n// TODO: does this import work?\n/**\n * @import { stdout } from \"node:process\"\n */\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\ntype StyleTextFormat = Parameters<typeof styleText>[0];\n\nconst TTY_AUTO_STYLE: StyleTextFormat = [\"gray\", \"bold\"];\n\n// biome-ignore lint/suspicious/noExplicitAny: This is the correct type nere.\nfunction isString(s: any): s is string {\n  return typeof s === \"string\";\n}\n\n// biome-ignore lint/suspicious/noExplicitAny: This is the correct type here.\nfunction isValidArgsEntryArray(entries: any[]): entries is SingleArgument[] {\n  for (const entry of entries) {\n    if (isString(entry)) {\n      continue;\n    }\n    if (entry instanceof Path) {\n      continue;\n    }\n    return false;\n  }\n  return true;\n}\n\n// TODO: allow `.toString()`ables?\ntype SingleArgument = string | Path;\ntype ArgsEntry = SingleArgument | SingleArgument[];\ntype Args = ArgsEntry[];\n\nexport interface PrintOptions {\n  /** Defaults to \"\" */\n  mainIndentation?: string;\n  /** Defaults to \"  \" */\n  argIndentation?: string;\n  /**\n   * - `\"auto\"`: Quote only arguments that need it for safety. This tries to be\n   *   portable and safe across shells, but true safety and portability is hard\n   *   to guarantee.\n   * - `\"extra-safe\"`: Quote all arguments, even ones that don't need it. This is\n   *   more likely to be safe under all circumstances.\n   */\n  quoting?: \"auto\" | \"extra-safe\";\n  /** Line wrapping to use between arguments. Defaults to `\"by-entry\"`. */\n  argumentLineWrapping?:\n    | \"by-entry\"\n    | \"nested-by-entry\"\n    | \"by-argument\"\n    | \"inline\";\n  /** Include the first arg (or first arg group) on the same line as the command, regardless of the `argumentLineWrapping` setting. */\n  skipLineWrapBeforeFirstArg?: true | false;\n  /**\n   * Style text using `node`'s {@link styleText | `styleText(\u2026)`}.\n   *\n   * Example usage:\n   *\n   * ```\n   * new PrintableShellCommand(\"echo\", [\"hi\"]).print({\n   *   styleTextFormat: [\"green\", \"underline\"],\n   * });\n   * */\n  styleTextFormat?: StyleTextFormat;\n}\n\nexport interface StreamPrintOptions extends PrintOptions {\n  /**\n   * Auto-style the text when:\n   *\n   * - the output stream is detected to be a TTY\n   * - `styleTextFormat` is not specified.\n   *\n   * The current auto style is: `[\"gray\", \"bold\"]`\n   */\n  autoStyle?: \"tty\" | \"never\";\n  // This would be a `WritableStream` (open web standard), but `WriteStream` allows us to query `.isTTY`.\n  stream?: WriteStream | Writable;\n}\n\n// https://mywiki.wooledge.org/BashGuide/SpecialCharacters\nconst SPECIAL_SHELL_CHARACTERS = new Set([\n  \" \",\n  '\"',\n  \"'\",\n  \"`\",\n  \"|\",\n  \"$\",\n  \"*\",\n  \"?\",\n  \">\",\n  \"<\",\n  \"(\",\n  \")\",\n  \"[\",\n  \"]\",\n  \"{\",\n  \"}\",\n  \"&\",\n  \"\\\\\",\n  \";\",\n  \"#\",\n]);\n\n// https://mywiki.wooledge.org/BashGuide/SpecialCharacters\nconst SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND =\n  // biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)\n  (SPECIAL_SHELL_CHARACTERS as unknown as any).union(new Set([\"=\"]));\n\n// biome-ignore lint/suspicious/noExplicitAny: Just matching\ntype BunCwd = SpawnOptions.OptionsObject<any, any, any>[\"cwd\"] | Path;\ntype BunWithCwd<\n  // biome-ignore lint/suspicious/noExplicitAny: Just matching\n  T extends { cwd?: SpawnOptions.OptionsObject<any, any, any>[\"cwd\"] | Path },\n> = SetFieldType<T, \"cwd\", BunCwd | undefined>;\n\n// TODO: Is there an idiomatic ways to check that all potential fields of\n// `StdinSource` satisfy `(typeof STDIN_SOURCE_KEYS)[number]`, without adding\n// extra indirection for type wrangling?\nconst STDIN_SOURCE_KEYS = [\"text\", \"json\", \"path\", \"stream\"] as const;\nexport type StdinSource =\n  | { text: string }\n  // biome-ignore lint/suspicious/noExplicitAny: `any` is the correct type for JSON data.\n  | { json: any }\n  | { path: string | Path }\n  | { stream: Readable | ReadableStream };\n\nexport class PrintableShellCommand {\n  #commandName: string | Path;\n  constructor(\n    commandName: string | Path,\n    private args: Args = [],\n  ) {\n    if (!isString(commandName) && !(commandName instanceof Path)) {\n      // biome-ignore lint/suspicious/noExplicitAny: We want to print this, no matter what it is.\n      throw new Error(\"Command name is not a string:\", commandName as any);\n    }\n    this.#commandName = commandName;\n    if (typeof args === \"undefined\") {\n      return;\n    }\n    if (!Array.isArray(args)) {\n      throw new Error(\"Command arguments are not an array\");\n    }\n    for (let i = 0; i < args.length; i++) {\n      const argEntry = args[i];\n      if (typeof argEntry === \"string\") {\n        continue;\n      }\n      if (argEntry instanceof Path) {\n        continue;\n      }\n      if (Array.isArray(argEntry) && isValidArgsEntryArray(argEntry)) {\n        continue;\n      }\n      throw new Error(`Invalid arg entry at index: ${i}`);\n    }\n  }\n\n  get commandName(): string {\n    return stringifyIfPath(this.#commandName);\n  }\n\n  /** For use with `bun`.\n   *\n   * Usage example:\n   *\n   * ```\n   * import { PrintableShellCommand } from \"printable-shell-command\";\n   * import { spawn } from \"bun\";\n   *\n   * const command = new PrintableShellCommand( \u2026 );\n   * await spawn(command.toFlatCommand()).exited;\n   * ```\n   */\n  public toFlatCommand(): string[] {\n    return [this.commandName, ...this.args.flat().map(stringifyIfPath)];\n  }\n\n  /**\n   * Convenient alias for {@link PrintableShellCommand.toFlatCommand | `.toFlatCommand()`}.\n   *\n   * Usage example:\n   *\n   * ```\n   * import { PrintableShellCommand } from \"printable-shell-command\";\n   * import { spawn } from \"bun\";\n   *\n   * const command = new PrintableShellCommand( \u2026 );\n   * await spawn(command.forBun()).exited;\n   * ```\n   *\n   * */\n  public forBun(): string[] {\n    return this.toFlatCommand();\n  }\n\n  /**\n   * For use with `node:child_process`\n   *\n   * Usage example:\n   *\n   * ```\n   * import { PrintableShellCommand } from \"printable-shell-command\";\n   * import { spawn } from \"node:child_process\";\n   *\n   * const command = new PrintableShellCommand( \u2026 );\n   * const child_process = spawn(...command.toCommandWithFlatArgs()); // Note the `...`\n   * ```\n   *\n   */\n  public toCommandWithFlatArgs(): [string, string[]] {\n    return [this.commandName, this.args.flat().map(stringifyIfPath)];\n  }\n\n  /**\n   * For use with `node:child_process`\n   *\n   * Usage example:\n   *\n   * ```\n   * import { PrintableShellCommand } from \"printable-shell-command\";\n   * import { spawn } from \"node:child_process\";\n   *\n   * const command = new PrintableShellCommand( \u2026 );\n   * const child_process = spawn(...command.forNode()); // Note the `...`\n   * ```\n   *\n   * Convenient alias for {@link PrintableShellCommand.toCommandWithFlatArgs | `toCommandWithFlatArgs()`}.\n   */\n  public forNode(): [string, string[]] {\n    return this.toCommandWithFlatArgs();\n  }\n\n  #mainIndentation(options: PrintOptions): string {\n    return options?.mainIndentation ?? DEFAULT_MAIN_INDENTATION;\n  }\n\n  #argIndentation(options: PrintOptions): string {\n    return (\n      this.#mainIndentation(options) +\n      (options?.argIndentation ?? DEFAULT_ARG_INDENTATION)\n    );\n  }\n\n  #lineWrapSeparator(options: PrintOptions): string {\n    return LINE_WRAP_LINE_END + this.#argIndentation(options);\n  }\n\n  #argPairSeparator(options: PrintOptions): string {\n    switch (options?.argumentLineWrapping ?? DEFAULT_ARGUMENT_LINE_WRAPPING) {\n      case \"by-entry\": {\n        return INLINE_SEPARATOR;\n      }\n      case \"nested-by-entry\": {\n        return this.#lineWrapSeparator(options) + this.#argIndentation(options);\n      }\n      case \"by-argument\": {\n        return this.#lineWrapSeparator(options);\n      }\n      case \"inline\": {\n        return INLINE_SEPARATOR;\n      }\n      default:\n        throw new Error(\"Invalid argument line wrapping argument.\");\n    }\n  }\n\n  #intraEntrySeparator(options: PrintOptions): string {\n    switch (options?.argumentLineWrapping ?? DEFAULT_ARGUMENT_LINE_WRAPPING) {\n      case \"by-entry\":\n      case \"nested-by-entry\":\n      case \"by-argument\": {\n        return LINE_WRAP_LINE_END + this.#argIndentation(options);\n      }\n      case \"inline\": {\n        return INLINE_SEPARATOR;\n      }\n      default:\n        throw new Error(\"Invalid argument line wrapping argument.\");\n    }\n  }\n\n  #separatorAfterCommand(\n    options: PrintOptions,\n    numFollowingEntries: number,\n  ): string {\n    if (numFollowingEntries === 0) {\n      return \"\";\n    }\n    if (options.skipLineWrapBeforeFirstArg ?? false) {\n      return INLINE_SEPARATOR;\n    }\n    return this.#intraEntrySeparator(options);\n  }\n\n  public getPrintableCommand(options?: PrintOptions): string {\n    // TODO: Why in the world does TypeScript not give the `options` arg the type of `PrintOptions | undefined`???\n    options ??= {};\n    const serializedEntries: string[] = [];\n\n    for (let i = 0; i < this.args.length; i++) {\n      const argsEntry = stringifyIfPath(this.args[i]);\n\n      if (isString(argsEntry)) {\n        serializedEntries.push(escapeArg(argsEntry, false, options));\n      } else {\n        serializedEntries.push(\n          argsEntry\n            .map((part) => escapeArg(stringifyIfPath(part), false, options))\n            .join(this.#argPairSeparator(options)),\n        );\n      }\n    }\n\n    let text =\n      this.#mainIndentation(options) +\n      escapeArg(this.commandName, true, options) +\n      this.#separatorAfterCommand(options, serializedEntries.length) +\n      serializedEntries.join(this.#intraEntrySeparator(options));\n    if (options?.styleTextFormat) {\n      text = styleText(options.styleTextFormat, text);\n    }\n    return text;\n  }\n\n  /**\n   * Print the shell command to {@link stderr} (default) or a specified stream.\n   *\n   * By default, this will be auto-styled (as bold gray) when `.isTTY` is true\n   * for the stream. `.isTTY` is populated for the {@link stderr} and\n   * {@link stdout} objects. Pass `\"autoStyle\": \"never\"` or an explicit\n   * `styleTextFormat` to disable this.\n   *\n   */\n  public print(options?: StreamPrintOptions): PrintableShellCommand {\n    const stream = options?.stream ?? stderr;\n    // Note: we only need to modify top-level fields, so `structuredClone(\u2026)`\n    // would be overkill and can only cause performance issues.\n    const optionsCopy = { ...options };\n    optionsCopy.styleTextFormat ??=\n      options?.autoStyle !== \"never\" &&\n      (stream as { isTTY?: boolean }).isTTY === true\n        ? TTY_AUTO_STYLE\n        : undefined;\n    const writable =\n      stream instanceof Writable ? stream : Writable.fromWeb(stream);\n    writable.write(this.getPrintableCommand(optionsCopy));\n    writable.write(\"\\n\");\n    return this;\n  }\n\n  #stdinSource: StdinSource | undefined;\n  /**\n   * Send data to `stdin` of the subprocess.\n   *\n   * Note that this will overwrite:\n   *\n   * - Any previous value set using {@link PrintableShellCommand.stdin | `.stdin(\u2026)`}.\n   * - Any value set for `stdin` using the `\"stdio\"` field of {@link PrintableShellCommand.spawn | `.spawn(\u2026)`}.\n   */\n  stdin(source: StdinSource): PrintableShellCommand {\n    const [key, ...moreKeys] = Object.keys(source);\n    assert.equal(moreKeys.length, 0);\n    // TODO: validate values?\n    assert((STDIN_SOURCE_KEYS as unknown as string[]).includes(key));\n\n    this.#stdinSource = source;\n    return this;\n  }\n\n  /**\n   * The returned child process includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313\n   */\n  public spawn: typeof spawnType = ((\n    options?: Parameters<typeof spawnType>[0],\n  ) => {\n    const { spawn } = process.getBuiltinModule(\"node:child_process\");\n    const cwd = stringifyIfPath(options?.cwd);\n    if (this.#stdinSource) {\n      options ??= {};\n      if (typeof options.stdio === \"undefined\") {\n        options.stdio = \"pipe\";\n      }\n      if (typeof options.stdio === \"string\") {\n        options.stdio = new Array(3).fill(options.stdio);\n      }\n      options.stdio[0] = \"pipe\";\n    }\n    // biome-ignore lint/suspicious/noTsIgnore: We don't want linting to depend on *broken* type checking.\n    // @ts-ignore: The TypeScript checker has trouble reconciling the optional (i.e. potentially `undefined`) `options` with the third argument.\n    const subprocess = spawn(...this.forNode(), {\n      ...(options as object),\n      cwd,\n    }) as NodeChildProcess & {\n      success: Promise<void>;\n    };\n    // TODO: define properties on prototypes instead.\n    Object.defineProperty(subprocess, \"success\", {\n      get() {\n        return new Promise<void>((resolve, reject) =>\n          this.addListener(\n            \"exit\",\n            (exitCode: number /* we only use the first arg */) => {\n              if (exitCode === 0) {\n                resolve();\n              } else {\n                reject(`Command failed with non-zero exit code: ${exitCode}`);\n              }\n            },\n          ),\n        );\n      },\n      enumerable: false,\n    });\n    if (subprocess.stdout) {\n      // TODO: dedupe\n      const s = subprocess as unknown as Readable &\n        WithStdoutResponse &\n        WithSuccess;\n      s.stdout.response = () =>\n        new Response(Readable.from(this.#generator(s.stdout, s.success)));\n      s.stdout.text = () => s.stdout.response().text();\n      const thisCached = this; // TODO: make this type-check using `.bind(\u2026)`\n      s.stdout.text0 = async function* () {\n        yield* thisCached.#split0(thisCached.#generator(s.stdout, s.success));\n      };\n      s.stdout.json = <T>() => s.stdout.response().json() as Promise<T>;\n    }\n    if (subprocess.stderr) {\n      // TODO: dedupe\n      const s = subprocess as unknown as Readable &\n        WithStderrResponse &\n        WithSuccess;\n      s.stderr.response = () =>\n        new Response(Readable.from(this.#generator(s.stderr, s.success)));\n      s.stderr.text = () => s.stderr.response().text();\n      const thisCached = this; // TODO: make this type-check using `.bind(\u2026)`\n      s.stderr.text0 = async function* () {\n        yield* thisCached.#split0(thisCached.#generator(s.stderr, s.success));\n      };\n      s.stderr.json = <T>() => s.stderr.response().json() as Promise<T>;\n    }\n    if (this.#stdinSource) {\n      const { stdin } = subprocess;\n      assert(stdin);\n      if (\"text\" in this.#stdinSource) {\n        stdin.write(this.#stdinSource.text);\n        stdin.end();\n      } else if (\"json\" in this.#stdinSource) {\n        stdin.write(JSON.stringify(this.#stdinSource.json));\n        stdin.end();\n      } else if (\"path\" in this.#stdinSource) {\n        createReadStream(stringifyIfPath(this.#stdinSource.path)).pipe(stdin);\n      } else if (\"stream\" in this.#stdinSource) {\n        const stream = (() => {\n          const { stream } = this.#stdinSource;\n          return stream instanceof Readable ? stream : Readable.fromWeb(stream);\n        })();\n        stream.pipe(stdin);\n      } else {\n        throw new Error(\"Invalid `.stdin(\u2026)` source?\");\n      }\n    }\n    return subprocess;\n    // biome-ignore lint/suspicious/noExplicitAny: Type wrangling\n  }) as any;\n\n  /** A wrapper for `.spawn(\u2026)` that sets stdio to `\"inherit\"` (common for\n   * invoking commands from scripts whose output and interaction should be\n   * surfaced to the user).\n   *\n   * If there is no other interaction with the shell from the calling process,\n   * then it acts \"transparent\" and allows user to interact with the subprocess\n   * in its stead.\n   */\n  public spawnTransparently(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): ChildProcessByStdio<null, null, null> & WithSuccess {\n    if (options && \"stdio\" in options) {\n      throw new Error(\"Unexpected `stdio` field.\");\n    }\n\n    // biome-ignore lint/suspicious/noExplicitAny: Type wrangling.\n    return this.spawn({ ...options, stdio: \"inherit\" }) as any;\n  }\n\n  /**\n   * A wrapper for {@link PrintableShellCommand.spawn | `.spawn(\u2026)`} that:\n   *\n   * - sets `detached` to `true`,\n   * - sets stdio to `\"inherit\"`,\n   * - calls `.unref()`, and\n   * - does not wait for the process to exit.\n   *\n   * This is similar to starting a command in the background and disowning it (in a shell).\n   *\n   */\n  public spawnDetached(\n    options?: NodeWithCwd<Omit<Omit<NodeSpawnOptions, \"stdio\">, \"detached\">>,\n  ): void {\n    if (options) {\n      for (const field of [\"stdio\", \"detached\"]) {\n        if (field in options) {\n          throw new Error(`Unexpected \\`${field}\\` field.`);\n        }\n      }\n    }\n    const childProcess = this.spawn({\n      stdio: \"ignore\",\n      ...options,\n      detached: true,\n    });\n    childProcess.unref();\n  }\n\n  #generator(\n    readable: Readable,\n    successPromise: Promise<void>,\n  ): AsyncGenerator<string> {\n    // TODO: we'd make this a `ReadableStream`, but `ReadableStream.from(\u2026)` is\n    // not implemented in `bun`: https://github.com/oven-sh/bun/issues/3700\n    return (async function* () {\n      for await (const chunk of readable) {\n        yield chunk;\n      }\n      await successPromise;\n    })();\n  }\n\n  #stdoutSpawnGenerator(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): AsyncGenerator<string> {\n    if (options && \"stdio\" in options) {\n      throw new Error(\"Unexpected `stdio` field.\");\n    }\n    const subprocess = this.spawn({\n      ...options,\n      stdio: [\"ignore\", \"pipe\", \"inherit\"],\n    });\n    return this.#generator(subprocess.stdout, subprocess.success);\n  }\n\n  public stdout(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): Response {\n    // TODO: Use `ReadableStream.from(\u2026)` once `bun` implements it: https://github.com/oven-sh/bun/pull/21269\n    return new Response(Readable.from(this.#stdoutSpawnGenerator(options)));\n  }\n\n  async *#split0(generator: AsyncGenerator<string>): AsyncGenerator<string> {\n    let pending = \"\";\n    for await (const chunk of generator) {\n      pending += chunk;\n      const newChunks = pending.split(\"\\x00\");\n      pending = newChunks.splice(-1)[0];\n      yield* newChunks;\n    }\n    if (pending !== \"\") {\n      throw new Error(\n        \"Missing a trailing NUL character at the end of a NUL-delimited stream.\",\n      );\n    }\n  }\n\n  /**\n   * Convenience function for:\n   *\n   *     .stdout(options).text()\n   *\n   * This can make some simple invocations easier to read and/or fit on a single line.\n   */\n  public text(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): Promise<string> {\n    return this.stdout(options).text();\n  }\n\n  /**\n   * Convenience function for:\n   *\n   *     .stdout(options).json()\n   *\n   * This can make some simple invocations easier to read and/or fit on a single line.\n   */\n  public json<T>(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): Promise<T> {\n    return this.stdout(options).json() as Promise<T>;\n  }\n\n  /**\n   * Parse `stdout` into a generator of string values using a NULL delimiter.\n   *\n   * A trailing NULL delimiter from `stdout` is required and removed.\n   */\n  public async *text0(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): AsyncGenerator<string> {\n    yield* this.#split0(this.#stdoutSpawnGenerator(options));\n  }\n\n  /**\n   * Parse `stdout` into a generator of JSON values using a NULL delimiter.\n   *\n   * A trailing NULL delimiter from `stdout` is required and removed.\n   */\n  public async *json0(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): // biome-ignore lint/suspicious/noExplicitAny: `any` is the correct type for JSON\n  AsyncGenerator<any> {\n    for await (const part of this.#split0(\n      this.#stdoutSpawnGenerator(options),\n    )) {\n      yield JSON.parse(part);\n    }\n  }\n\n  /** Equivalent to:\n   *\n   * ```\n   * await this.print().spawnTransparently(\u2026).success;\n   * ```\n   */\n  public async shellOut(\n    options?: NodeWithCwd<Omit<NodeSpawnOptions, \"stdio\">>,\n  ): Promise<void> {\n    await this.print().spawnTransparently(options).success;\n  }\n\n  /**\n   * The returned subprocess includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313\n   */\n  #spawnBun<\n    const In extends BunSpawnOptions.Writable = \"ignore\",\n    const Out extends BunSpawnOptions.Readable = \"pipe\",\n    const Err extends BunSpawnOptions.Readable = \"inherit\",\n  >(\n    options?: BunWithCwd<\n      Omit<BunSpawnOptions.OptionsObject<In, Out, Err>, \"cmd\">\n    >,\n  ): BunSubprocess<In, Out, Err> & { success: Promise<void> } {\n    if (options && \"cmd\" in options) {\n      throw new Error(\"Unexpected `cmd` field.\");\n    }\n    const { spawn } = process.getBuiltinModule(\"bun\") as typeof import(\"bun\");\n    const cwd = stringifyIfPath(options?.cwd);\n    const subprocess = spawn({\n      ...options,\n      cwd,\n      cmd: this.forBun(),\n    }) as BunSubprocess<In, Out, Err> & { success: Promise<void> };\n    Object.defineProperty(subprocess, \"success\", {\n      get() {\n        return new Promise<void>((resolve, reject) =>\n          this.exited\n            .then((exitCode: number) => {\n              if (exitCode === 0) {\n                resolve();\n              } else {\n                reject(\n                  new Error(\n                    `Command failed with non-zero exit code: ${exitCode}`,\n                  ),\n                );\n              }\n            })\n            .catch(reject),\n        );\n      },\n      enumerable: false,\n    });\n    return subprocess;\n  }\n\n  #spawnBunInherit(\n    options?: BunWithCwd<\n      Omit<\n        BunSpawnOptions.OptionsObject<\"inherit\", \"inherit\", \"inherit\">,\n        \"cmd\" | \"stdio\"\n      >\n    >,\n  ): BunSubprocess<\"inherit\", \"inherit\", \"inherit\"> & {\n    success: Promise<void>;\n  } {\n    if (options && \"stdio\" in options) {\n      throw new Error(\"Unexpected `stdio` field.\");\n    }\n    return this.bun.spawnBun({\n      ...options,\n      stdio: [\"inherit\", \"inherit\", \"inherit\"],\n    });\n  }\n\n  #spawnBunStdout(\n    options?: BunWithCwd<\n      Omit<\n        BunSpawnOptions.OptionsObject<\"inherit\", \"inherit\", \"inherit\">,\n        \"cmd\" | \"stdio\"\n      >\n    >,\n  ): Response {\n    // biome-ignore lint/suspicious/noExplicitAny: Avoid breaking the lib check when used without `@types/bun`.\n    return new Response((this.bun.spawnBun(options) as any).stdout);\n  }\n\n  async #shellOutBun(\n    options?: BunWithCwd<\n      Omit<\n        BunSpawnOptions.OptionsObject<\"inherit\", \"inherit\", \"inherit\">,\n        \"cmd\" | \"stdio\"\n      >\n    >,\n  ): Promise<void> {\n    await this.print().bun.spawnBunInherit(options).success;\n  }\n\n  bun = {\n    /** Equivalent to:\n     *\n     * ```\n     * await this.print().bun.spawnBunInherit(\u2026).success;\n     * ```\n     */\n    spawnBun: this.#spawnBun.bind(this),\n    /**\n     * A wrapper for `.spawnBunInherit(\u2026)` that sets stdio to `\"inherit\"` (common\n     * for invoking commands from scripts whose output and interaction should be\n     * surfaced to the user).\n     */\n    spawnBunInherit: this.#spawnBunInherit.bind(this),\n    /** Equivalent to:\n     *\n     * ```\n     * new Response(this.bun.spawnBun(\u2026).stdout);\n     * ```\n     */\n    spawnBunStdout: this.#spawnBunStdout.bind(this),\n    shellOutBun: this.#shellOutBun.bind(this),\n  };\n}\n\nexport function escapeArg(\n  arg: string,\n  isMainCommand: boolean,\n  options: PrintOptions,\n): string {\n  const argCharacters = new Set(arg);\n  const specialShellCharacters = isMainCommand\n    ? SPECIAL_SHELL_CHARACTERS_FOR_MAIN_COMMAND\n    : SPECIAL_SHELL_CHARACTERS;\n  if (\n    options?.quoting === \"extra-safe\" ||\n    // biome-ignore lint/suspicious/noExplicitAny: Workaround to make this package easier to use in a project that otherwise only uses ES2022.)\n    (argCharacters as unknown as any).intersection(specialShellCharacters)\n      .size > 0\n  ) {\n    // Use single quote to reduce the need to escape (and therefore reduce the chance for bugs/security issues).\n    const escaped = arg.replaceAll(\"\\\\\", \"\\\\\\\\\").replaceAll(\"'\", \"\\\\'\");\n    return `'${escaped}'`;\n  }\n  return arg;\n}\n"],
+  "mappings": "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",
+  "names": ["stream"]
 }

package/dist/lib/printable-shell-command/spawn.d.ts

@@ -9,13 +9,25 @@ export type NodeWithCwd<T extends {
 export interface WithSuccess {
     success: Promise<void>;
 }
+export interface WithResponse {
+    response: () => Response;
+    text: () => Promise<string>;
+    text0: () => AsyncGenerator<string>;
+    json: <T>() => Promise<T>;
+}
+export interface WithStdoutResponse {
+    stdout: Readable & WithResponse;
+}
+export interface WithStderrResponse {
+    stderr: Readable & WithResponse;
+}
 export declare function spawnType(options?: NodeWithCwd<SpawnOptionsWithoutStdio>): ChildProcessWithoutNullStreams & WithSuccess;
-export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioPipe>>): ChildProcessByStdio<Writable, Readable, Readable> & WithSuccess;
-export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioNull>>): ChildProcessByStdio<Writable, Readable, null> & WithSuccess;
-export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioPipe>>): ChildProcessByStdio<Writable, null, Readable> & WithSuccess;
-export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>>): ChildProcessByStdio<null, Readable, Readable> & WithSuccess;
+export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioPipe>>): ChildProcessByStdio<Writable, Readable, Readable> & WithSuccess & WithStdoutResponse & WithStderrResponse;
+export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioNull>>): ChildProcessByStdio<Writable, Readable, null> & WithSuccess & WithStdoutResponse;
+export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioPipe>>): ChildProcessByStdio<Writable, null, Readable> & WithSuccess & WithStderrResponse;
+export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>>): ChildProcessByStdio<null, Readable, Readable> & WithSuccess & WithStdoutResponse & WithStderrResponse;
 export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioNull>>): ChildProcessByStdio<Writable, null, null> & WithSuccess;
-export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioNull>>): ChildProcessByStdio<null, Readable, null> & WithSuccess;
-export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioPipe>>): ChildProcessByStdio<null, null, Readable> & WithSuccess;
+export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioNull>>): ChildProcessByStdio<null, Readable, null> & WithSuccess & WithStdoutResponse;
+export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioPipe>>): ChildProcessByStdio<null, null, Readable> & WithSuccess & WithStderrResponse;
 export declare function spawnType(options: NodeWithCwd<SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioNull>>): ChildProcessByStdio<null, null, null> & WithSuccess;
 export declare function spawnType(options: NodeWithCwd<SpawnOptions>): ChildProcess & WithSuccess;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "printable-shell-command",
-	"version": "2.7.4",
+	"version": "3.0.1",
 	"devDependencies": {
 		"@biomejs/biome": "^2.1.4",
 		"@cubing/dev-config": "^0.3.6",

package/src/index.ts

@@ -1,8 +1,10 @@
+import assert from "node:assert";
 import type {
   ChildProcessByStdio,
   ChildProcess as NodeChildProcess,
   SpawnOptions as NodeSpawnOptions,
 } from "node:child_process";
+import { createReadStream } from "node:fs";
 import { stderr } from "node:process";
 import { Readable, Writable } from "node:stream";
 import type { WriteStream } from "node:tty";
@@ -14,7 +16,13 @@ import type {
 } from "bun";
 import { Path, stringifyIfPath } from "path-class";
 import type { SetFieldType } from "type-fest";
-import type { NodeWithCwd, spawnType, WithSuccess } from "./spawn";
+import type {
+  NodeWithCwd,
+  spawnType,
+  WithStderrResponse,
+  WithStdoutResponse,
+  WithSuccess,
+} from "./spawn";
 
 // TODO: does this import work?
 /**
@@ -140,6 +148,17 @@ type BunWithCwd<
   T extends { cwd?: SpawnOptions.OptionsObject<any, any, any>["cwd"] | Path },
 > = SetFieldType<T, "cwd", BunCwd | undefined>;
 
+// TODO: Is there an idiomatic ways to check that all potential fields of
+// `StdinSource` satisfy `(typeof STDIN_SOURCE_KEYS)[number]`, without adding
+// extra indirection for type wrangling?
+const STDIN_SOURCE_KEYS = ["text", "json", "path", "stream"] as const;
+export type StdinSource =
+  | { text: string }
+  // biome-ignore lint/suspicious/noExplicitAny: `any` is the correct type for JSON data.
+  | { json: any }
+  | { path: string | Path }
+  | { stream: Readable | ReadableStream };
+
 export class PrintableShellCommand {
   #commandName: string | Path;
   constructor(
@@ -247,28 +266,6 @@ export class PrintableShellCommand {
     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;
   }
@@ -340,13 +337,11 @@ export class PrintableShellCommand {
       const argsEntry = stringifyIfPath(this.args[i]);
 
       if (isString(argsEntry)) {
-        serializedEntries.push(this.#escapeArg(argsEntry, false, options));
+        serializedEntries.push(escapeArg(argsEntry, false, options));
       } else {
         serializedEntries.push(
           argsEntry
-            .map((part) =>
-              this.#escapeArg(stringifyIfPath(part), false, options),
-            )
+            .map((part) => escapeArg(stringifyIfPath(part), false, options))
             .join(this.#argPairSeparator(options)),
         );
       }
@@ -354,7 +349,7 @@ export class PrintableShellCommand {
 
     let text =
       this.#mainIndentation(options) +
-      this.#escapeArg(this.commandName, true, options) +
+      escapeArg(this.commandName, true, options) +
       this.#separatorAfterCommand(options, serializedEntries.length) +
       serializedEntries.join(this.#intraEntrySeparator(options));
     if (options?.styleTextFormat) {
@@ -389,6 +384,25 @@ export class PrintableShellCommand {
     return this;
   }
 
+  #stdinSource: StdinSource | undefined;
+  /**
+   * Send data to `stdin` of the subprocess.
+   *
+   * Note that this will overwrite:
+   *
+   * - Any previous value set using {@link PrintableShellCommand.stdin | `.stdin(…)`}.
+   * - Any value set for `stdin` using the `"stdio"` field of {@link PrintableShellCommand.spawn | `.spawn(…)`}.
+   */
+  stdin(source: StdinSource): PrintableShellCommand {
+    const [key, ...moreKeys] = Object.keys(source);
+    assert.equal(moreKeys.length, 0);
+    // TODO: validate values?
+    assert((STDIN_SOURCE_KEYS as unknown as string[]).includes(key));
+
+    this.#stdinSource = source;
+    return this;
+  }
+
   /**
    * The returned child process includes a `.success` `Promise` field, per https://github.com/oven-sh/bun/issues/8313
    */
@@ -397,6 +411,16 @@ export class PrintableShellCommand {
   ) => {
     const { spawn } = process.getBuiltinModule("node:child_process");
     const cwd = stringifyIfPath(options?.cwd);
+    if (this.#stdinSource) {
+      options ??= {};
+      if (typeof options.stdio === "undefined") {
+        options.stdio = "pipe";
+      }
+      if (typeof options.stdio === "string") {
+        options.stdio = new Array(3).fill(options.stdio);
+      }
+      options.stdio[0] = "pipe";
+    }
     // biome-ignore lint/suspicious/noTsIgnore: We don't want linting to depend on *broken* type checking.
     // @ts-ignore: The TypeScript checker has trouble reconciling the optional (i.e. potentially `undefined`) `options` with the third argument.
     const subprocess = spawn(...this.forNode(), {
@@ -405,6 +429,7 @@ export class PrintableShellCommand {
     }) as NodeChildProcess & {
       success: Promise<void>;
     };
+    // TODO: define properties on prototypes instead.
     Object.defineProperty(subprocess, "success", {
       get() {
         return new Promise<void>((resolve, reject) =>
@@ -422,6 +447,55 @@ export class PrintableShellCommand {
       },
       enumerable: false,
     });
+    if (subprocess.stdout) {
+      // TODO: dedupe
+      const s = subprocess as unknown as Readable &
+        WithStdoutResponse &
+        WithSuccess;
+      s.stdout.response = () =>
+        new Response(Readable.from(this.#generator(s.stdout, s.success)));
+      s.stdout.text = () => s.stdout.response().text();
+      const thisCached = this; // TODO: make this type-check using `.bind(…)`
+      s.stdout.text0 = async function* () {
+        yield* thisCached.#split0(thisCached.#generator(s.stdout, s.success));
+      };
+      s.stdout.json = <T>() => s.stdout.response().json() as Promise<T>;
+    }
+    if (subprocess.stderr) {
+      // TODO: dedupe
+      const s = subprocess as unknown as Readable &
+        WithStderrResponse &
+        WithSuccess;
+      s.stderr.response = () =>
+        new Response(Readable.from(this.#generator(s.stderr, s.success)));
+      s.stderr.text = () => s.stderr.response().text();
+      const thisCached = this; // TODO: make this type-check using `.bind(…)`
+      s.stderr.text0 = async function* () {
+        yield* thisCached.#split0(thisCached.#generator(s.stderr, s.success));
+      };
+      s.stderr.json = <T>() => s.stderr.response().json() as Promise<T>;
+    }
+    if (this.#stdinSource) {
+      const { stdin } = subprocess;
+      assert(stdin);
+      if ("text" in this.#stdinSource) {
+        stdin.write(this.#stdinSource.text);
+        stdin.end();
+      } else if ("json" in this.#stdinSource) {
+        stdin.write(JSON.stringify(this.#stdinSource.json));
+        stdin.end();
+      } else if ("path" in this.#stdinSource) {
+        createReadStream(stringifyIfPath(this.#stdinSource.path)).pipe(stdin);
+      } else if ("stream" in this.#stdinSource) {
+        const stream = (() => {
+          const { stream } = this.#stdinSource;
+          return stream instanceof Readable ? stream : Readable.fromWeb(stream);
+        })();
+        stream.pipe(stdin);
+      } else {
+        throw new Error("Invalid `.stdin(…)` source?");
+      }
+    }
     return subprocess;
     // biome-ignore lint/suspicious/noExplicitAny: Type wrangling
   }) as any;
@@ -445,13 +519,6 @@ export class PrintableShellCommand {
     return this.spawn({ ...options, stdio: "inherit" }) as any;
   }
 
-  /** @deprecated: Use `.spawnTransparently(…)`. */
-  public spawnInherit(
-    options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>,
-  ): NodeChildProcess & WithSuccess {
-    return this.spawnTransparently(options);
-  }
-
   /**
    * A wrapper for {@link PrintableShellCommand.spawn | `.spawn(…)`} that:
    *
@@ -460,31 +527,18 @@ export class PrintableShellCommand {
    * - calls `.unref()`, and
    * - does not wait for the process to exit.
    *
-   * This is similar to starting a command int he background and disowning it (in a shell).
-   *
-   * The `stdio` field is left overridable. To capture `stdout` and `stderr`, connect them to output files like this:
-   *
-   * ```
-   * import { open } from "node:fs/promises";
-   * import { Path } from "path-class";
-   * import { PrintableShellCommand } from "printable-shell-command";
-   *
-   * const tempDir = await Path.makeTempDir();
-   * console.log(`Temp dir: ${tempDir}`);
-   * const stdout = await open(tempDir.join("stdout.log").path, "a");
-   * const stderr = await open(tempDir.join("stderr.log").path, "a");
-   *
-   * new PrintableShellCommand("echo", ["hi"]).spawnDetached({
-   *   stdio: ["ignore", stdout.fd, stderr.fd],
-   * });
-   * ```
+   * This is similar to starting a command in the background and disowning it (in a shell).
    *
    */
   public spawnDetached(
-    options?: NodeWithCwd<Omit<NodeSpawnOptions, "detached">>,
+    options?: NodeWithCwd<Omit<Omit<NodeSpawnOptions, "stdio">, "detached">>,
   ): void {
-    if (options && "detached" in options) {
-      throw new Error("Unexpected `detached` field.");
+    if (options) {
+      for (const field of ["stdio", "detached"]) {
+        if (field in options) {
+          throw new Error(`Unexpected \`${field}\` field.`);
+        }
+      }
     }
     const childProcess = this.spawn({
       stdio: "ignore",
@@ -494,9 +548,23 @@ export class PrintableShellCommand {
     childProcess.unref();
   }
 
-  public stdout(
+  #generator(
+    readable: Readable,
+    successPromise: Promise<void>,
+  ): AsyncGenerator<string> {
+    // TODO: we'd make this a `ReadableStream`, but `ReadableStream.from(…)` is
+    // not implemented in `bun`: https://github.com/oven-sh/bun/issues/3700
+    return (async function* () {
+      for await (const chunk of readable) {
+        yield chunk;
+      }
+      await successPromise;
+    })();
+  }
+
+  #stdoutSpawnGenerator(
     options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>,
-  ): Response {
+  ): AsyncGenerator<string> {
     if (options && "stdio" in options) {
       throw new Error("Unexpected `stdio` field.");
     }
@@ -504,8 +572,29 @@ export class PrintableShellCommand {
       ...options,
       stdio: ["ignore", "pipe", "inherit"],
     });
+    return this.#generator(subprocess.stdout, subprocess.success);
+  }
 
-    return new Response(Readable.toWeb(subprocess.stdout));
+  public stdout(
+    options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>,
+  ): Response {
+    // TODO: Use `ReadableStream.from(…)` once `bun` implements it: https://github.com/oven-sh/bun/pull/21269
+    return new Response(Readable.from(this.#stdoutSpawnGenerator(options)));
+  }
+
+  async *#split0(generator: AsyncGenerator<string>): AsyncGenerator<string> {
+    let pending = "";
+    for await (const chunk of generator) {
+      pending += chunk;
+      const newChunks = pending.split("\x00");
+      pending = newChunks.splice(-1)[0];
+      yield* newChunks;
+    }
+    if (pending !== "") {
+      throw new Error(
+        "Missing a trailing NUL character at the end of a NUL-delimited stream.",
+      );
+    }
   }
 
   /**
@@ -534,6 +623,33 @@ export class PrintableShellCommand {
     return this.stdout(options).json() as Promise<T>;
   }
 
+  /**
+   * Parse `stdout` into a generator of string values using a NULL delimiter.
+   *
+   * A trailing NULL delimiter from `stdout` is required and removed.
+   */
+  public async *text0(
+    options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>,
+  ): AsyncGenerator<string> {
+    yield* this.#split0(this.#stdoutSpawnGenerator(options));
+  }
+
+  /**
+   * Parse `stdout` into a generator of JSON values using a NULL delimiter.
+   *
+   * A trailing NULL delimiter from `stdout` is required and removed.
+   */
+  public async *json0(
+    options?: NodeWithCwd<Omit<NodeSpawnOptions, "stdio">>,
+  ): // biome-ignore lint/suspicious/noExplicitAny: `any` is the correct type for JSON
+  AsyncGenerator<any> {
+    for await (const part of this.#split0(
+      this.#stdoutSpawnGenerator(options),
+    )) {
+      yield JSON.parse(part);
+    }
+  }
+
   /** Equivalent to:
    *
    * ```
@@ -657,3 +773,25 @@ export class PrintableShellCommand {
     shellOutBun: this.#shellOutBun.bind(this),
   };
 }
+
+export function 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;
+}

package/src/spawn.ts

@@ -21,6 +21,20 @@ export interface WithSuccess {
   success: Promise<void>;
 }
 
+export interface WithResponse {
+  response: () => Response;
+  text: () => Promise<string>;
+  text0: () => AsyncGenerator<string>;
+  json: <T>() => Promise<T>;
+}
+export interface WithStdoutResponse {
+  stdout: Readable & WithResponse;
+}
+
+export interface WithStderrResponse {
+  stderr: Readable & WithResponse;
+}
+
 export declare function spawnType(
   options?: NodeWithCwd<SpawnOptionsWithoutStdio>,
 ): ChildProcessWithoutNullStreams & WithSuccess;
@@ -28,22 +42,32 @@ export declare function spawnType(
   options: NodeWithCwd<
     SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioPipe>
   >,
-): ChildProcessByStdio<Writable, Readable, Readable> & WithSuccess;
+): ChildProcessByStdio<Writable, Readable, Readable> &
+  WithSuccess &
+  WithStdoutResponse &
+  WithStderrResponse;
 export declare function spawnType(
   options: NodeWithCwd<
     SpawnOptionsWithStdioTuple<StdioPipe, StdioPipe, StdioNull>
   >,
-): ChildProcessByStdio<Writable, Readable, null> & WithSuccess;
+): ChildProcessByStdio<Writable, Readable, null> &
+  WithSuccess &
+  WithStdoutResponse;
 export declare function spawnType(
   options: NodeWithCwd<
     SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioPipe>
   >,
-): ChildProcessByStdio<Writable, null, Readable> & WithSuccess;
+): ChildProcessByStdio<Writable, null, Readable> &
+  WithSuccess &
+  WithStderrResponse;
 export declare function spawnType(
   options: NodeWithCwd<
     SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioPipe>
   >,
-): ChildProcessByStdio<null, Readable, Readable> & WithSuccess;
+): ChildProcessByStdio<null, Readable, Readable> &
+  WithSuccess &
+  WithStdoutResponse &
+  WithStderrResponse;
 export declare function spawnType(
   options: NodeWithCwd<
     SpawnOptionsWithStdioTuple<StdioPipe, StdioNull, StdioNull>
@@ -53,12 +77,12 @@ export declare function spawnType(
   options: NodeWithCwd<
     SpawnOptionsWithStdioTuple<StdioNull, StdioPipe, StdioNull>
   >,
-): ChildProcessByStdio<null, Readable, null> & WithSuccess;
+): ChildProcessByStdio<null, Readable, null> & WithSuccess & WithStdoutResponse;
 export declare function spawnType(
   options: NodeWithCwd<
     SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioPipe>
   >,
-): ChildProcessByStdio<null, null, Readable> & WithSuccess;
+): ChildProcessByStdio<null, null, Readable> & WithSuccess & WithStderrResponse;
 export declare function spawnType(
   options: NodeWithCwd<
     SpawnOptionsWithStdioTuple<StdioNull, StdioNull, StdioNull>