@arcgis/node-toolkit 5.2.0-next.41 → 5.2.0-next.42

package/dist/file.d.ts

@@ -1,4 +1,4 @@
-import { ExecSyncOptionsWithStringEncoding, SpawnSyncOptionsWithStringEncoding } from 'node:child_process';
+import { ExecSyncOptionsWithStringEncoding, SpawnOptions, SpawnSyncOptionsWithStringEncoding } from 'node:child_process';
 /**
  * Asynchronously check if a file or directory exists.
  * Using un-promisified version because promises version creates exceptions
@@ -7,16 +7,49 @@ import { ExecSyncOptionsWithStringEncoding, SpawnSyncOptionsWithStringEncoding }
 export declare const existsAsync: (file: string) => Promise<boolean>;
 /**
  * Synchronously execute a shell command and return the output.
+ *
+ * Prefer {@link sp} for most use cases. {@link sh} goes through a shell,
+ * which requires careful escaping and can mis-handle dynamic input with spaces
+ * or shell metacharacters.
+ *
+ * Use {@link sh} only when shell features are intentionally required, such as
+ * pipes, redirects, `&&`, or command substitution.
  */
 export declare function sh(command: string, options?: Partial<ExecSyncOptionsWithStringEncoding>): string;
 /**
  * Asynchronously execute a shell command and return the output.
+ *
+ * Prefer {@link asyncSp} for most use cases. {@link asyncSh} executes through
+ * a shell, so callers must handle shell escaping and quoting correctly.
+ *
+ * Use {@link asyncSh} only when shell syntax is intentionally needed.
  */
 export declare function asyncSh(command: string, options?: Partial<ExecSyncOptionsWithStringEncoding>): Promise<string>;
 /**
  * Synchronously execute a command without shell interpolation and return the output.
+ *
+ * This is usually safer than {@link sh} because arguments are passed as
+ * discrete tokens, which avoids most shell escaping issues and command
+ * injection pitfalls.
+ *
+ * Example:
+ * `sp("git", ["show", `${baseRef}:pnpm-workspace.yaml`])`
+ *
+ * Avoid {@link sp} only when you explicitly need shell features.
  */
 export declare function sp(command: string, args: string[], options?: Partial<SpawnSyncOptionsWithStringEncoding>): string;
+/**
+ * Asynchronously execute a command without shell interpolation and return the output.
+ *
+ * This is usually safer than {@link asyncSh} because arguments are not parsed
+ * by a shell.
+ *
+ * Example:
+ * `await asyncSp("pnpm", ["--filter=@arcgis/map-components", "list", "@arcgis/core", "--json"])`
+ *
+ * Prefer {@link asyncSp} by default for external command execution.
+ */
+export declare function asyncSp(command: string, args: string[], options?: Partial<SpawnOptions>): Promise<string>;
 /**
  * Create a file with the specified content if it does not already exist.
  */

package/dist/file.js

@@ -2,7 +2,7 @@ import { access, existsSync } from "node:fs";
 import { constants, mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve, sep, join } from "path";
 import { fileURLToPath } from "node:url";
-import { execSync, exec, spawnSync } from "node:child_process";
+import { execSync, exec, spawnSync, spawn } from "node:child_process";
 import { styleText } from "node:util";
 const existsAsync = async (file) => (
   //#endregion existsAsync
@@ -46,6 +46,36 @@ ${output}`.trim()
   }
   return output;
 }
+async function asyncSp(command, args, options = {}) {
+  const child = spawn(command, args, options);
+  const stdoutChunks = [];
+  const stderrChunks = [];
+  child.stdout?.on(
+    "data",
+    (chunk) => stdoutChunks.push(Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk))
+  );
+  child.stderr?.on(
+    "data",
+    (chunk) => stderrChunks.push(Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk))
+  );
+  return await new Promise((resolve2, reject) => {
+    child.on("error", (error) => reject(error));
+    child.on("close", (code) => {
+      const output = `${stdoutChunks.join("")}${stderrChunks.join("")}`.trim();
+      const exitCode = code ?? 0;
+      if (exitCode !== 0) {
+        reject(
+          new Error(
+            `Command failed with exit code ${String(exitCode)}: ${command} ${args.join(" ")}
+${output}`.trim()
+          )
+        );
+        return;
+      }
+      resolve2(output);
+    });
+  });
+}
 function makeExecErrorReadable(error) {
   if (error instanceof Error && error.stack && "output" in error && Array.isArray(error.output) && "status" in error) {
     const stackIndex = error.stack.indexOf("\n    at ");
@@ -105,6 +135,7 @@ async function asyncFindPath(target, startDirectory = process.cwd()) {
 export {
   asyncFindPath,
   asyncSh,
+  asyncSp,
   createFileIfNotExists,
   existsAsync,
   findPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcgis/node-toolkit",
-  "version": "5.2.0-next.41",
+  "version": "5.2.0-next.42",
   "description": "Collection of common internal build-time patterns and utilities for ArcGIS Maps SDK for JavaScript components.",
   "homepage": "https://developers.arcgis.com/javascript/latest/",
   "type": "module",