@maz-ui/node 5.0.0-beta.24 → 5.0.0-beta.26

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import { ExecOptions } from 'node:child_process';
 import * as consola from 'consola';
 import { ConsolaOptions, InputLogObject, ConsolaReporter, ConsolaInstance } from 'consola';
 export { ConsolaOptions } from 'consola';
@@ -51,28 +52,88 @@ interface CustomLogger {
     warn: (message: string, ...args: any[]) => void;
     debug: (message: string, ...args: any[]) => void;
 }
-declare function execPromise(command: string, { logger, packageName, noSuccess, noStdout, noStderr, noError, logLevel, cwd, }?: {
+/**
+ * Options for {@link execPromise}.
+ *
+ * The following fields are forwarded as-is to `child_process.exec`:
+ * - `cwd` - working directory of the command. Defaults to the current one.
+ * - `env` - environment variables, **merged on top of `process.env`**.
+ * - `timeout` - maximum run time in milliseconds before the command is killed. No timeout by default.
+ * - `maxBuffer` - maximum bytes allowed on stdout/stderr before the command is killed. Defaults to `1024 * 1024` (1 MiB).
+ * - `killSignal` - signal used to kill the command on timeout or abort. Defaults to `'SIGTERM'`.
+ * - `shell` - shell used to run the command. Defaults to `/bin/sh` (Unix) or `cmd.exe` (Windows).
+ * - `signal` - an `AbortSignal` that, once aborted, kills the command and rejects the promise.
+ */
+type ExecPromiseOptions = Pick<ExecOptions, 'cwd' | 'timeout' | 'env' | 'maxBuffer' | 'killSignal' | 'shell' | 'signal'> & {
+    /**
+     * Custom logger used for every output. Falls back to the package logger.
+     */
     logger?: CustomLogger;
+    /**
+     * Prefix added to every log line, formatted as `[packageName]: `.
+     */
     packageName?: string;
     /**
-     * Don't log success message
+     * Don't log the success message.
+     * @default false
      */
     noSuccess?: boolean;
     /**
-     * Don't log stdout
+     * Don't log stdout.
+     * @default false
      */
     noStdout?: boolean;
     /**
-     * Don't log stderr
+     * Don't log stderr.
+     * @default false
      */
     noStderr?: boolean;
     /**
-     * Don't log error
+     * Don't log the error when the command fails.
+     * @default false
      */
     noError?: boolean;
+    /**
+     * Logging level applied to the default logger before running the command.
+     */
     logLevel?: LogLevel;
-    cwd?: string;
-}): Promise<{
+};
+/**
+ * Runs a shell command and resolves with its `stdout` and `stderr`.
+ *
+ * Secrets (npm auth tokens, `--token`/`--password` flags, provider tokens,
+ * JWTs, basic-auth URLs) are automatically masked in every log line and in the
+ * rejected error via {@link redactSecrets}. The resolved `stdout`/`stderr` are
+ * returned untouched.
+ *
+ * @param command - The shell command to execute.
+ * @returns A promise resolving with the command `stdout` and `stderr`.
+ * @throws If the command exits with a non-zero code, times out, is aborted, or
+ * exceeds `maxBuffer`. The rejected error is redacted.
+ *
+ * @example Basic usage
+ * ```ts
+ * const { stdout } = await execPromise('node --version')
+ * ```
+ *
+ * @example Fail the command after 5 seconds
+ * ```ts
+ * await execPromise('pnpm install', { timeout: 5000 })
+ * ```
+ *
+ * @example Inject environment variables (merged on top of `process.env`)
+ * ```ts
+ * await execPromise('node build.mjs', { env: { NODE_ENV: 'production' } })
+ * ```
+ *
+ * @example Cancel the command with an `AbortController`
+ * ```ts
+ * const controller = new AbortController()
+ * const promise = execPromise('long-task', { signal: controller.signal })
+ * controller.abort()
+ * ```
+ */
+declare function execPromise(command: string, { logger, packageName, noSuccess, noStdout, noStderr, noError, logLevel, cwd, timeout, env, maxBuffer, killSignal, shell, signal, }?: ExecPromiseOptions): Promise<{
     stdout: string;
     stderr: string;
 }>;
@@ -88,5 +149,24 @@ declare function printBanner({ name, version, options, }: {
     };
 }): void;
 
-export { createLogger, execPromise, logger, printBanner };
-export type { LogLevel, Logger, LoggerOptions };
+/**
+ * Masks secrets that have a recognizable syntactic context inside a string.
+ *
+ * Only deterministic patterns are redacted (npm auth tokens, named secret flags
+ * such as `--token`/`--password`, prefixed provider tokens like `npm_`/`ghp_`,
+ * JWTs, and basic-auth credentials in URLs). Context-free random strings are left
+ * untouched because they cannot be detected without false positives.
+ *
+ * Tokens long enough (>= 16 chars) keep their first and last 4 characters visible
+ * (e.g. `npm_***J1iF`) so the right credential can still be recognized; shorter
+ * secrets are fully masked.
+ */
+declare function redactSecrets(input: string): string;
+/**
+ * Returns the given error with its `message`, `cmd` and `stack` redacted via
+ * {@link redactSecrets}, so a thrown command never carries secrets to callers.
+ */
+declare function redactError<T>(error: T): T;
+
+export { createLogger, execPromise, logger, printBanner, redactError, redactSecrets };
+export type { ExecPromiseOptions, LogLevel, Logger, LoggerOptions };

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { ExecOptions } from 'node:child_process';
 import * as consola from 'consola';
 import { ConsolaOptions, InputLogObject, ConsolaReporter, ConsolaInstance } from 'consola';
 export { ConsolaOptions } from 'consola';
@@ -51,28 +52,88 @@ interface CustomLogger {
     warn: (message: string, ...args: any[]) => void;
     debug: (message: string, ...args: any[]) => void;
 }
-declare function execPromise(command: string, { logger, packageName, noSuccess, noStdout, noStderr, noError, logLevel, cwd, }?: {
+/**
+ * Options for {@link execPromise}.
+ *
+ * The following fields are forwarded as-is to `child_process.exec`:
+ * - `cwd` - working directory of the command. Defaults to the current one.
+ * - `env` - environment variables, **merged on top of `process.env`**.
+ * - `timeout` - maximum run time in milliseconds before the command is killed. No timeout by default.
+ * - `maxBuffer` - maximum bytes allowed on stdout/stderr before the command is killed. Defaults to `1024 * 1024` (1 MiB).
+ * - `killSignal` - signal used to kill the command on timeout or abort. Defaults to `'SIGTERM'`.
+ * - `shell` - shell used to run the command. Defaults to `/bin/sh` (Unix) or `cmd.exe` (Windows).
+ * - `signal` - an `AbortSignal` that, once aborted, kills the command and rejects the promise.
+ */
+type ExecPromiseOptions = Pick<ExecOptions, 'cwd' | 'timeout' | 'env' | 'maxBuffer' | 'killSignal' | 'shell' | 'signal'> & {
+    /**
+     * Custom logger used for every output. Falls back to the package logger.
+     */
     logger?: CustomLogger;
+    /**
+     * Prefix added to every log line, formatted as `[packageName]: `.
+     */
     packageName?: string;
     /**
-     * Don't log success message
+     * Don't log the success message.
+     * @default false
      */
     noSuccess?: boolean;
     /**
-     * Don't log stdout
+     * Don't log stdout.
+     * @default false
      */
     noStdout?: boolean;
     /**
-     * Don't log stderr
+     * Don't log stderr.
+     * @default false
      */
     noStderr?: boolean;
     /**
-     * Don't log error
+     * Don't log the error when the command fails.
+     * @default false
      */
     noError?: boolean;
+    /**
+     * Logging level applied to the default logger before running the command.
+     */
     logLevel?: LogLevel;
-    cwd?: string;
-}): Promise<{
+};
+/**
+ * Runs a shell command and resolves with its `stdout` and `stderr`.
+ *
+ * Secrets (npm auth tokens, `--token`/`--password` flags, provider tokens,
+ * JWTs, basic-auth URLs) are automatically masked in every log line and in the
+ * rejected error via {@link redactSecrets}. The resolved `stdout`/`stderr` are
+ * returned untouched.
+ *
+ * @param command - The shell command to execute.
+ * @returns A promise resolving with the command `stdout` and `stderr`.
+ * @throws If the command exits with a non-zero code, times out, is aborted, or
+ * exceeds `maxBuffer`. The rejected error is redacted.
+ *
+ * @example Basic usage
+ * ```ts
+ * const { stdout } = await execPromise('node --version')
+ * ```
+ *
+ * @example Fail the command after 5 seconds
+ * ```ts
+ * await execPromise('pnpm install', { timeout: 5000 })
+ * ```
+ *
+ * @example Inject environment variables (merged on top of `process.env`)
+ * ```ts
+ * await execPromise('node build.mjs', { env: { NODE_ENV: 'production' } })
+ * ```
+ *
+ * @example Cancel the command with an `AbortController`
+ * ```ts
+ * const controller = new AbortController()
+ * const promise = execPromise('long-task', { signal: controller.signal })
+ * controller.abort()
+ * ```
+ */
+declare function execPromise(command: string, { logger, packageName, noSuccess, noStdout, noStderr, noError, logLevel, cwd, timeout, env, maxBuffer, killSignal, shell, signal, }?: ExecPromiseOptions): Promise<{
     stdout: string;
     stderr: string;
 }>;
@@ -88,5 +149,24 @@ declare function printBanner({ name, version, options, }: {
     };
 }): void;
 
-export { createLogger, execPromise, logger, printBanner };
-export type { LogLevel, Logger, LoggerOptions };
+/**
+ * Masks secrets that have a recognizable syntactic context inside a string.
+ *
+ * Only deterministic patterns are redacted (npm auth tokens, named secret flags
+ * such as `--token`/`--password`, prefixed provider tokens like `npm_`/`ghp_`,
+ * JWTs, and basic-auth credentials in URLs). Context-free random strings are left
+ * untouched because they cannot be detected without false positives.
+ *
+ * Tokens long enough (>= 16 chars) keep their first and last 4 characters visible
+ * (e.g. `npm_***J1iF`) so the right credential can still be recognized; shorter
+ * secrets are fully masked.
+ */
+declare function redactSecrets(input: string): string;
+/**
+ * Returns the given error with its `message`, `cmd` and `stack` redacted via
+ * {@link redactSecrets}, so a thrown command never carries secrets to callers.
+ */
+declare function redactError<T>(error: T): T;
+
+export { createLogger, execPromise, logger, printBanner, redactError, redactSecrets };
+export type { ExecPromiseOptions, LogLevel, Logger, LoggerOptions };

package/dist/index.mjs

@@ -53,6 +53,43 @@ function createLogger(options) {
 }
 const logger = createLogger();
 
+const MASK = "***";
+const VISIBLE_PREFIX = 4;
+const MIN_LENGTH_TO_REVEAL = 16;
+const SECRET_FLAG_NAMES = "password|passwd|pwd|pass|token|api[-_]?key|secret|authorization|auth[-_]?token|access[-_]?token|refresh[-_]?token|client[-_]?secret|private[-_]?key|credentials?|auth";
+const keepEnds = (value) => value.length < MIN_LENGTH_TO_REVEAL ? MASK : `${value.slice(0, VISIBLE_PREFIX)}${MASK}${value.slice(-4)}`;
+const keepPrefix = (_match, prefix, value) => `${prefix}${keepEnds(value)}`;
+const REDACTION_RULES = [
+  [/(:?_authToken=)([^\s&]+)/gi, keepPrefix],
+  [new RegExp(`(--(?:${SECRET_FLAG_NAMES})=)(\\S+)`, "gi"), keepPrefix],
+  [new RegExp(`(--(?:${SECRET_FLAG_NAMES})\\s+)(?!-)(\\S+)`, "gi"), keepPrefix],
+  [/(\/\/[^/:@\s]+:)([^/@\s]+)@/g, (_match, prefix, value) => `${prefix}${keepEnds(value)}@`],
+  [/npm_[A-Za-z0-9]{10,}/g, keepEnds],
+  [/gh[posru]_[A-Za-z0-9]{20,}/g, keepEnds],
+  [/github_pat_\w{20,}/g, keepEnds],
+  [/glpat-[\w-]{15,}/g, keepEnds],
+  [/xox[baprs]-[A-Za-z0-9-]{10,}/g, keepEnds],
+  [/AKIA[0-9A-Z]{16}/g, keepEnds],
+  [/sk-[\w-]{16,}/g, keepEnds],
+  [/eyJ[\w-]+\.eyJ[\w-]+\.[\w-]+/g, keepEnds]
+];
+const REDACTABLE_ERROR_KEYS = ["message", "cmd", "stack"];
+function redactSecrets(input) {
+  return REDACTION_RULES.reduce((acc, [pattern, replacement]) => acc.replace(pattern, replacement), input);
+}
+function redactError(error) {
+  if (!error || typeof error !== "object") {
+    return error;
+  }
+  for (const key of REDACTABLE_ERROR_KEYS) {
+    const value = error[key];
+    if (typeof value === "string") {
+      error[key] = redactSecrets(value);
+    }
+  }
+  return error;
+}
+
 async function execPromise(command, {
   logger: logger$1,
   packageName,
@@ -61,35 +98,52 @@ async function execPromise(command, {
   noStderr = false,
   noError = false,
   logLevel,
-  cwd
+  cwd,
+  timeout,
+  env,
+  maxBuffer,
+  killSignal,
+  shell,
+  signal
 } = {}) {
   if (logLevel) {
     logger.setLevel(logLevel);
   }
   const internalLogger = logger$1 ?? logger;
   const packageNameStr = packageName ? `[${packageName}]: ` : "";
+  const safeCommand = redactSecrets(command);
   return await new Promise((resolve, reject) => {
-    exec(command, { cwd }, (error, stdout, stderr) => {
+    exec(command, {
+      cwd,
+      timeout,
+      maxBuffer,
+      killSignal,
+      shell,
+      signal,
+      env: env ? { ...process$1.env, ...env } : void 0
+    }, (error, stdout, stderr) => {
       if (stdout) {
-        internalLogger.debug(`${command} - stdout output:`, stdout);
+        internalLogger.debug(`${safeCommand} - stdout output:`, redactSecrets(stdout));
       }
       if (stderr) {
-        internalLogger.debug(`${command} - stderr output:`, stderr);
+        internalLogger.debug(`${safeCommand} - stderr output:`, redactSecrets(stderr));
       }
       if (stdout && !noStdout) {
-        internalLogger.log(`${packageNameStr}stdout -`, stdout.trim());
+        internalLogger.log(`${packageNameStr}stdout -`, redactSecrets(stdout.trim()));
       }
       if (stderr && !noStderr) {
-        internalLogger.log(`${packageNameStr}stderr -`, stderr.trim());
+        internalLogger.log(`${packageNameStr}stderr -`, redactSecrets(stderr.trim()));
       }
       if (error) {
+        const safeError = redactError(error);
         if (!noError) {
-          internalLogger.error(`${packageNameStr}${command} failed`, error);
+          const reason = error.killed && timeout ? `timed out after ${timeout}ms` : "failed";
+          internalLogger.error(`${packageNameStr}${safeCommand} ${reason}`, safeError);
         }
-        reject(error);
+        reject(safeError);
       } else {
         if (!noSuccess) {
-          internalLogger.info(`${packageNameStr}${command} - Success!`);
+          internalLogger.info(`${packageNameStr}${safeCommand} - Success!`);
         }
         resolve({ stdout, stderr });
       }
@@ -126,4 +180,4 @@ function printBanner({
     logger.break();
 }
 
-export { createLogger, execPromise, logger, printBanner };
+export { createLogger, execPromise, logger, printBanner, redactError, redactSecrets };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@maz-ui/node",
   "type": "module",
-  "version": "5.0.0-beta.24",
+  "version": "5.0.0-beta.26",
   "description": "Node utilities for Maz-UI library",
   "author": "Louis Mazel <me@loicmazuel.com>",
   "license": "MIT",