@j-o-r/sh 1.1.29 → 1.1.32

package/lib/SH.js

@@ -11,16 +11,16 @@
 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 // See the License for the specific language governing permissions and
 // limitations under the License.
-// 
+//
 //
 // Original Source: zx
 // Link to Original Source: https://github.com/google/zx
-// Reason for Using This Code: 
-// The core functionality of this code is highly beneficial. However, certain parts of the original code 
-// were overwriting the global namespace with core libraries and variables. This was causing conflicts with 
+// Reason for Using This Code:
+// The core functionality of this code is highly beneficial. However, certain parts of the original code
+// were overwriting the global namespace with core libraries and variables. This was causing conflicts with
 // other packages (for instance, fetch) and introducing unexpected elements into my code base.
 // The main $/SH method is all there is left, with barebone Promises and readable code.
-// Changes Made: 
+// Changes Made:
 // - The code has been or is being reformatted to comply with ES2020 standards.
 // - Some methods were added and existing ones were modified or deleted to enhance usability.
 // - The namespace has been changed from '$' to 'SH'.
@@ -29,28 +29,17 @@
 import assert from 'node:assert';
 import readline from 'node:readline/promises';
 import SHDispatch from './SHDispatch.js';
-import Test from './Test.js'
-import AsyncTracker from './AsyncTracker.js'
-
-/**
- * @typedef {Object.<string, string>} ArgsObject
- * @property {string[]} _ - Array of strings, unnamed parameters
- * @property {string} [key: string] - Any string key maps to a string value
- * @description Parsed parameters result.
- */
+import Test from './Test.js';
+import AsyncTracker from './AsyncTracker.js';
+import { defaultOptions, defaultOptionKeys, clearCwdOverride, parseDuration } from './internal.js';
 
 /**
- * @typedef {Function} RejectCallback
- * @param {Error} error - The error object passed to the callback.
- */
-
-/**
- * @typedef {Function} ResolveCallback
- * @param {any} [param] - Optional callback any value
- */
-
-/**
- * @typedef {import('./SHDispatch.js').SHOptions} SHOptions
+ * Parsed command-line arguments.
+ *
+ * Named options map to their string value, or `true` when no value is supplied.
+ * Bare positional arguments are collected in `_`.
+ *
+ * @typedef {{_: string[]} & Object.<string, string|true>} ArgsObject
  */
 
 /**
@@ -60,124 +49,126 @@ import AsyncTracker from './AsyncTracker.js'
  */
 
 /**
- * @typedef {Object} ExpBackoffGenerator
- * @generator
- * @yields {number} Backoff time in ms.
+ * Generator that yields retry delay durations in milliseconds.
+ *
+ * @typedef {Generator<number, void, unknown>} ExpBackoffGenerator
  */
 
 /**
  * Utility to determine the JavaScript type of a value.
  *
- * @param {any} fn - Any value to inspect.
+ * Uses `Object.prototype.toString`, so `jsType(null)` returns `'Null'`;
+ * `undefined` is special-cased to `'undefined'`. Plain objects report their
+ * constructor name, or `'Object'` when there is none (null-prototype objects).
+ *
+ * @param {unknown} value - Any value to inspect.
  * @returns {string} The "real" object type name (e.g., 'Array', 'Promise') or primitive typeof.
  * @example
  * jsType([]); // 'Array'
  * jsType(Promise.resolve()); // 'Promise'
+ * jsType(null); // 'Null'
+ * jsType(undefined); // 'undefined'
  */
-const jsType = (fn) => {
-	if (fn === undefined) return 'undefined';
-	const type = Object.prototype.toString.call(fn).slice(8, -1);
-	return type === 'Object' ? fn.constructor.name : type;
+const jsType = (value) => {
+	if (value === undefined) return 'undefined';
+	const type = Object.prototype.toString.call(value).slice(8, -1);
+	// Null-prototype objects have no constructor; fall back to 'Object'.
+	return type === 'Object' ? (/** @type {any} */ (value).constructor?.name ?? 'Object') : type;
 };
 
 /**
- * Checks if an object has a specific own property (code-safe).
+ * Checks if an object has a specific own property. Safe for null-prototype
+ * objects and objects shadowing `hasOwnProperty`.
  *
  * @param {any} o - Object to examine.
  * @param {string} p - Property name to check.
  * @returns {boolean} True if the object has the own property.
  */
 const hasProp = (o, p) => {
-  if (o == null) return false;
-  return Object.prototype.hasOwnProperty.call(o, p);
+	if (o == null) return false;
+	return Object.hasOwn(o, p);
 };
 
 /**
- * Parses a human-readable duration string or number into milliseconds.
+ * Quotes a value as one POSIX shell argument.
  *
- * Supports: '5s' (5000ms), '100ms' (100ms), plain numbers (ms).
+ * The `SH` template tag interpolates values as raw shell source by default. Use
+ * this helper when a JavaScript value must be passed as data instead of shell
+ * syntax. The returned string is single-quoted and preserves the exact string
+ * value, including leading/trailing whitespace, empty strings, quotes,
+ * semicolons, glob characters, tabs, and newlines.
  *
- * @param {number|string} d - Duration as number (ms) or string ('5s', '100ms').
- * @returns {number} Duration in milliseconds.
- * @throws {Error} If invalid duration format.
+ * @param {unknown} x - Value to quote as a single shell argument.
+ * @returns {string} POSIX-shell-quoted argument string.
+ * @example
+ * await SH`printf '%s\n' ${bashEscape(userInput)}`.run();
  */
-const parseDuration = (d) => {
-	if (typeof d == 'number') {
-		if (isNaN(d) || d < 0)
-			throw new Error(`Invalid duration: "${d}".`);
-		return d;
-	}
-	else if (/\d+s/.test(d)) {
-		return +d.slice(0, -1) * 1000;
-	}
-	else if (/\d+ms/.test(d)) {
-		return +d.slice(0, -2);
-	}
-	throw new Error(`Unknown duration: "${d}".`);
-}
+const bashEscape = (x) => `'${String(x).replace(/'/g, `'\\''`)}'`;
 
 /**
- * Escapes a string for safe use as a bash command-line argument.
+ * Proxy traps for the SH template tag and global option defaults.
  *
- * Handles quotes, backticks, $, newlines, etc.
- *
- * @param {string} x - Input string to escape.
- * @returns {string} Bash-escaped string.
+ * Reads and writes are symmetric: only the known default option keys
+ * (`defaultOptionKeys`, derived from `defaultOptions` in `lib/internal.js`)
+ * are routed to the shared defaults. Assigning an unknown key throws a
+ * `TypeError` listing the known keys (decision D1) — this catches typos like
+ * `SH.timout = 1` instead of silently storing junk keys that read back as
+ * `undefined` and leak into every command's options. Reads of unknown keys
+ * keep normal function-proxy behavior (usually `undefined`).
  */
-const bashEscape = (x) => {
-	let str = String(x).trim();
-	// the trick is to double escape escape vars first
-	str = str.replace(/\\/g, '\\\\');
-	// then add escaping for oddities
-	// Replace literal escape sequences like \n, \t, \r in quoted strings
-	str = str.replace(/(['"])\\(.)\1/g, '$1\\\\$2$1');
-	// escape $ (is a BASH var)
-	str = str.replace(/\$/g, '\\$');
-	// Escape backticks
-	str = str.replace(/`/g, '\\`');
-	// Escape quotes
-	str = str.replace(/"/g, '\\"');
-	return str;
-}
-
-/** Default options applied to all SH commands unless overridden. */
-const defaultOptions = {
-	cwd: process.cwd(),
-	env: process.env,
-	shell: 'bash',
-	stdio: ['inherit', 'pipe', 'pipe'],
-	timeout: 0, // when 0 there is no timeout
+const defaultOptionHandler = {
+	get(target, prop, receiver) {
+		if (defaultOptionKeys.has(prop)) {
+			return defaultOptions[prop];
+		}
+		return Reflect.get(target, prop, receiver);
+	},
+	set(target, prop, value) {
+		if (!defaultOptionKeys.has(prop)) {
+			throw new TypeError(`Unknown SH option: "${String(prop)}". Known options: ${[...defaultOptionKeys].join(', ')}.`);
+		}
+		defaultOptions[prop] = value;
+		return true;
+	}
 };
 
-/** Proxy set trap for dynamically updating defaultOptions via SH.prop = value */
-const setHandler = {
-  set(target, prop, value) {
-    defaultOptions[prop] = value;
-    return true;
-  }
-}
-
 /**
  * Template tag for building and executing shell commands.
  *
  * Returns an {@link SHDispatch} instance for configuration (.options()) and execution (.run(), .runSync()).
  *
- * Interpolation rules:
- * - Arrays: Elements trimmed, newlines/tabs escaped, shell-special chars single-quoted with '\'' escape.
- * - Other values: String(value) inserted as-is (NOT auto-escaped; use {@link bashEscape} for safety).
+ * Interpolation rules are raw-by-default:
+ * - Arrays: Each element is converted with `String(value)` and joined with one space.
+ * - Other values: `String(value)` is inserted directly into the shell source.
  *
- * SH acts as both template tag and options setter: `SH.timeout = 5000; SH`cmd``
+ * Raw interpolation allows trusted shell fragments such as pipes, redirects, and
+ * command separators. It is not safe for untrusted input. Wrap untrusted values
+ * with {@link bashEscape} before interpolating them.
+ *
+ * SH also acts as a global options setter (see the last example). Global
+ * defaults are captured when each command is created, not when it runs — see
+ * the "defaults captured at creation time" note in {@link SHDispatch#options}.
+ * Only the known option keys (cwd, env, shell, stdio, timeout, maxBuffer,
+ * detached) may be assigned; assigning anything else throws a TypeError
+ * listing the known keys (typo guard, decision D1).
  *
  * @param {TemplateStringsArray} pieces - String literals from template.
- * @param {...unknown[]} args - Values to interpolate.
+ * @param {...unknown} args - Values to interpolate.
  * @returns {SHDispatch} Command dispatcher.
  * @throws {Error} If pieces contain undefined.
  * @example
  * const cmd = SH`echo ${'Hello'}`;
  * await cmd.run(); // Executes: echo Hello
  *
- * // Array interpolation
- * SH`ls ${['-la', '/']}`.run(); // ls '-la' '/'
+ * // Array interpolation is raw and joins with spaces
+ * SH`ls ${['-la', '/']}`.run(); // Executes: ls -la /
+ *
+ * // Quote untrusted values explicitly
+ * SH`printf '%s\n' ${bashEscape('semi; colon')}`.run();
+ *
+ * // Set global defaults for subsequently created commands
+ * SH.timeout = 5000;
+ * await SH`cmd`.run();
  */
 const SH = new Proxy(function(pieces, ...args) {
 	if (pieces.some((p) => p == undefined)) {
@@ -186,32 +177,25 @@ const SH = new Proxy(function(pieces, ...args) {
 	let cmd = pieces[0], i = 0;
 	while (i < args.length) {
 		let s;
-		
+
 		if (Array.isArray(args[i])) {
-			// @ts-ignore
-			s = args[i].map(/** @param {string} x */(x) => {
-				// Trim every element
-				let str = String(x).trim();
-        str = str.replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t');
-				// If the string contains special characters, wrap in single quotes
-				if (str.match(/[ "'$`(){}[\]]/)) {
-					// Escape single quotes within the string
-					return `'${str.replace(/'/g, `'\\''`)}'`;
-				}
-				return str;
-			}).join(' ');
+			s = args[i].map((x) => String(x)).join(' ');
 		} else {
 			s = String(args[i]);
 		}
 		cmd += s + pieces[++i];
 	}
 	return new SHDispatch(cmd, defaultOptions);
-}, setHandler);
+}, defaultOptionHandler);
 
 /**
- * Executes a callback in a new async context (fresh callstack).
+ * Awaits `callback()` and returns its result.
  *
- * Useful for parallel operations without nesting.
+ * Despite the historical name, this is currently a thin wrapper: no new async
+ * context or fresh callstack is created — the callback runs in the current
+ * one. It is kept as an intent marker for grouping async work (and for API
+ * compatibility); real isolation via AsyncLocalStorage is a pending decision
+ * (see the project TODO, decision D2).
  *
  * @param {() => Promise<any>} callback - Async function to execute.
  * @returns {Promise<any>} Result of callback.
@@ -222,29 +206,51 @@ const SH = new Proxy(function(pieces, ...args) {
  */
 const within = async (callback) => {
 	return await callback();
-}
+};
 
 /**
  * Reads entire stdin as UTF-8 string. Resolves to empty string if TTY (no pipe).
  *
- * @returns {Promise<string|undefined>} Stdin content or undefined if TTY.
+ * Side effect: permanently sets the `process.stdin` encoding to utf8 and
+ * switches it to flowing mode.
+ *
+ * @returns {Promise<string>} Stdin content, or an empty string if TTY.
  * @example
  * const input = await readIn(); // Use in piped scripts
  */
 const readIn = async () => {
-	if (process.stdin.isTTY) return;
+	if (process.stdin.isTTY) return '';
 	let buf = '';
 	process.stdin.setEncoding('utf8');
 	for await (const chunk of process.stdin) {
 		buf += chunk;
 	}
 	return buf;
-}
+};
+
+/**
+ * Minimum stdin chunk length (containing a newline) that {@link userIn}
+ * treats as a paste instead of typed input.
+ */
+const PASTE_MIN_CHUNK = 4;
+
+/**
+ * Debounce delay after the last 'line' event or paste before {@link userIn}
+ * auto-resolves with the accumulated input.
+ */
+const SUBMIT_DEBOUNCE_MS = 50;
 
 /**
  * Prompts user for input on stdin with custom prompt.
  *
- * Supports aborting input collection.
+ * Submit heuristics (non-obvious): each 'line' event is accumulated into a
+ * multi-line buffer and (re)starts a debounce timer
+ * ({@link SUBMIT_DEBOUNCE_MS}); when the timer fires without further input,
+ * the promise auto-resolves with the accumulated text plus any partially
+ * typed readline line. A paste — a stdin chunk longer than
+ * {@link PASTE_MIN_CHUNK} chars containing a newline — (re)starts the same
+ * timer, so pasted multi-line text resolves as one input. `abort()` resolves
+ * the promise with `undefined`.
  *
  * @param {string} prompt - Prompt text to display.
  * @returns {AbortableInput} Object with input Promise and abort function.
@@ -254,107 +260,122 @@ const readIn = async () => {
  * // abort(); // Cancel anytime
  */
 const userIn = (prompt) => {
-  let resolvePromise;
-  const input = new Promise((resolve) => { resolvePromise = resolve; });
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  let buffer = '';
-  let timer;
-  /** @param {string} chunk */
-  const onData = (chunk) => {
-    if (chunk.length > 4 && chunk.includes('\n')) {
-      clearTimeout(timer);
-      timer = setTimeout(resolveFunc, 50);
-    }
-  };
-
-  const resolveFunc = () => {
-    let fullText = buffer;
-    if (rl.line) fullText += rl.line;
-    cleanup();
-    resolvePromise(fullText);
-  };
-
-  const cleanup = () => {
-    process.stdin.removeListener('data', onData);
-    // @ts-ignore
-    rl.removeAllListeners('line');
-    clearTimeout(timer);
-    rl.close();
-  };
-  // @ts-ignore
-  rl.on('line', (line) => {
-    buffer += line + '\n';
-    clearTimeout(timer);
-    timer = setTimeout(resolveFunc, 50);
-  });
-  process.stdin.on('data', onData);
-
-  rl.setPrompt(prompt);
-  rl.prompt();
-
-  return {
-    input,
-    abort: () => {
-      cleanup();
-      resolvePromise();
-    }
-  };
+	let resolvePromise;
+	const input = new Promise((resolve) => { resolvePromise = resolve; });
+	const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+	let buffer = '';
+	let timer;
+	/** @param {string} chunk */
+	const onData = (chunk) => {
+		if (chunk.length > PASTE_MIN_CHUNK && chunk.includes('\n')) {
+			clearTimeout(timer);
+			timer = setTimeout(resolveFunc, SUBMIT_DEBOUNCE_MS);
+		}
+	};
+
+	const resolveFunc = () => {
+		let fullText = buffer;
+		if (rl.line) fullText += rl.line;
+		cleanup();
+		resolvePromise(fullText);
+	};
+
+	const cleanup = () => {
+		process.stdin.removeListener('data', onData);
+		rl.removeAllListeners('line');
+		clearTimeout(timer);
+		rl.close();
+	};
+	rl.on('line', (line) => {
+		buffer += line + '\n';
+		clearTimeout(timer);
+		timer = setTimeout(resolveFunc, SUBMIT_DEBOUNCE_MS);
+	});
+	process.stdin.on('data', onData);
+
+	rl.setPrompt(prompt);
+	rl.prompt();
+
+	return {
+		input,
+		abort: () => {
+			cleanup();
+			resolvePromise();
+		}
+	};
 };
 
+/**
+ * Checks whether a value is a generator-like retry delay source.
+ *
+ * @param {unknown} value - Value to inspect.
+ * @returns {boolean} True when value has a callable `next()` method.
+ */
+const isDelayGenerator = (value) => value != null && typeof value == 'object' && typeof value.next == 'function';
+
 /**
  * Retries an async function up to N times with optional delays.
  *
- * Delay can be fixed ('1s'), generator (expBackoff()), or none.
+ * Delay precedence: when `delayOrCallback` is a function it is the retried
+ * callback and there is no delay between attempts. Otherwise it is a static
+ * duration ('1s', 100) or a delay generator (e.g. {@link expBackoff}), and
+ * `callback` is the retried function. A generator yield of `undefined`
+ * (exhausted generator) or `0` means "no further delay" — the next attempt
+ * runs immediately.
  *
- * @param {number} count - Number of attempts.
- * @param {string|number|ExpBackoffGenerator|Function} delayOrFn - Delay or callback if no separate fn.
- * @param {Function} [fn] - Callback to retry (if delayOrFn not function).
+ * @param {number} count - Positive integer number of attempts.
+ * @param {string|number|Iterator<number|string>|(() => (Promise<any>|any))} delayOrCallback - Delay, delay generator, or the callback when no separate callback is supplied.
+ * @param {() => (Promise<any>|any)} [callback] - Callback to retry when a delay is supplied.
  * @returns {Promise<any>} Successful result.
- * @throws {Error} Last error if all attempts fail.
+ * @throws {Error} If arguments are invalid, or the last callback error if all attempts fail.
  * @example
  * await retry(3, '1s', () => SH`curl http://unreliable`.run());
  * await retry(3, expBackoff(), () => flakyOp());
  */
-const retry = async (count, a, b) => {
-	let callback;
+const retry = async (count, delayOrCallback, callback) => {
+	if (!Number.isInteger(count) || count < 1) {
+		throw new Error(`Invalid retry count: "${count}". Expected a positive integer.`);
+	}
+
+	let retryCallback;
 	let delayStatic = 0;
 	let delayGen;
-	// @ts-ignore
-	if (typeof a == 'function') {
-		callback = a;
+
+	if (typeof delayOrCallback == 'function') {
+		retryCallback = delayOrCallback;
 	}
 	else {
-		if (typeof a == 'object') {
-			delayGen = a;
+		if (typeof callback != 'function') {
+			throw new Error(`Invalid retry callback: expected a function.`);
+		}
+		retryCallback = callback;
+
+		if (isDelayGenerator(delayOrCallback)) {
+			delayGen = delayOrCallback;
+		}
+		else if (delayOrCallback != null && typeof delayOrCallback == 'object') {
+			throw new Error(`Invalid retry delay generator: expected an object with next().`);
 		}
 		else {
-			delayStatic = parseDuration(a);
+			delayStatic = parseDuration(delayOrCallback);
 		}
-		assert(b);
-		callback = b;
 	}
-	let lastErr;
-	let attempt = 0;
-	while (count-- > 0) {
-		attempt++;
+
+	for (let attempt = 1; attempt <= count; attempt++) {
 		try {
-			return await callback();
+			return await retryCallback();
 		}
 		catch (err) {
-			let delay = 0;
-			if (delayStatic > 0)
-				delay = delayStatic;
-			// @ts-ignore
-			if (delayGen) delay = delayGen.next().value;
-			lastErr = err;
-			if (count == 0)
-				break;
-			if (delay)
+			if (attempt == count) {
+				throw err;
+			}
+			const delay = delayGen ? delayGen.next().value : delayStatic;
+			if (delay) {
 				await sleep(delay);
+			}
 		}
 	}
-	throw lastErr;
-}
+};
 
 /**
  * Sleeps for a specified duration.
@@ -368,19 +389,23 @@ const sleep = (duration) => {
 	return new Promise((resolve) => {
 		setTimeout(resolve, parseDuration(duration));
 	});
-}
+};
 
 /**
  * Changes the current working directory.
  *
+ * Affects the cwd of subsequent `SH` commands: default options capture
+ * `process.cwd()` lazily when each command is created. Also clears any
+ * `SH.cwd` override, so the most recent cwd change always wins.
+ *
  * @param {string} dir - Path to new directory.
  * @example
  * cd('/tmp');
  */
 const cd = (dir) => {
-	// @ts-ignore
 	process.chdir(dir);
-}
+	clearCwdOverride();
+};
 
 /**
  * Generator for exponential backoff delays with jitter.
@@ -389,6 +414,7 @@ const cd = (dir) => {
  * @param {string} [max='60s'] - Max backoff duration.
  * @param {string} [rand='100ms'] - Max jitter.
  * @yields {number} Next backoff ms.
+ * @returns {ExpBackoffGenerator} Infinite generator of backoff delays in ms.
  * @example
  * const backoff = expBackoff();
  * await sleep(backoff.next().value);
@@ -403,11 +429,39 @@ function* expBackoff(max = '60s', rand = '100ms') {
 	}
 }
 
+/**
+ * Matches negative number tokens that should be parsed as values, not options.
+ *
+ * Supports decimal and exponent forms such as `-1`, `-0.5`, `-.5`, and `-1e3`.
+ *
+ * @param {string} arg - CLI argument token.
+ * @returns {boolean} True when the token is a negative numeric value.
+ */
+const isNegativeNumberArg = (arg) => /^-(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(arg);
+
+/**
+ * Checks whether a token should be parsed as an option.
+ *
+ * Negative numeric values are intentionally excluded so calls like
+ * `parseArgs(['--n', '-1'])` parse `-1` as the value for `--n`. A lone `-`
+ * is not an option either; it is parsed as a positional (the stdin
+ * convention). The `--` end-of-options terminator is handled separately in
+ * {@link parseArgs}.
+ *
+ * @param {string} arg - CLI argument token.
+ * @returns {boolean} True when the token should be parsed as an option.
+ */
+const isOptionArg = (arg) => arg.length > 1 && arg.startsWith('-') && !isNegativeNumberArg(arg);
+
 /**
  * Parses CLI arguments into an object.
  *
  * Supports --key value, -k value (no shorts grouped).
  * Bares go to _[]. Duplicates error. No = syntax.
+ * Negative number tokens such as -1, -0.5, and -1e3 are parsed as values or
+ * positionals, not options. A lone `-` is a positional (stdin convention).
+ * `--` is the conventional end-of-options terminator: every token after it
+ * goes into `_`, even option-looking ones.
  *
  * Defaults to process.argv.slice(2).
  *
@@ -416,23 +470,36 @@ function* expBackoff(max = '60s', rand = '100ms') {
  * @throws {Error} On invalid/dupe args.
  * @example
  * parseArgs(['--port', '8080', 'file.txt']); // { port: '8080', _: ['file.txt'] }
+ * parseArgs(['--n', '-1']); // { n: '-1', _: [] }
+ * parseArgs(['-', '--port', '1']); // { port: '1', _: ['-'] }
+ * parseArgs(['--', '--x']); // { _: ['--x'] }
  */
 const parseArgs = (args) => {
 	if (!args) args = process.argv.slice(2);
-	const result = { _: [] };
+	// @ts-ignore — '_: string[]' is the intended exception to the 'string|true' index signature of ArgsObject.
+	const result = /** @type {ArgsObject} */ ({ _: [] });
 	const seenKeys = new Set();
 	for (let i = 0; i < args.length; i++) {
-		if (args[i].startsWith('--') || args[i].startsWith('-')) {
-			if (args[i].startsWith('-') && !args[i].startsWith('--') && args[i].length > 2) {
-				throw new Error(`Invalid argument: ${args[i]}. Use '--' for long options.`);
+		const arg = args[i];
+
+		if (arg === '--') {
+			// End-of-options terminator: all remaining tokens are positionals.
+			result._.push(...args.slice(i + 1));
+			break;
+		}
+
+		if (isOptionArg(arg)) {
+			if (arg.startsWith('-') && !arg.startsWith('--') && arg.length > 2) {
+				throw new Error(`Invalid argument: ${arg}. Use '--' for long options.`);
 			}
-			const key = args[i].startsWith('--') ? args[i].substring(2) : args[i].substring(1);
+			const key = arg.startsWith('--') ? arg.substring(2) : arg.substring(1);
 			if (seenKeys.has(key)) {
-				throw new Error(`Duplicate argument: ${args[i]}`);
+				throw new Error(`Duplicate argument: ${arg}`);
 			}
 			seenKeys.add(key);
+			/** @type {string|true} */
 			let value;
-			if (args[i + 1] && !args[i + 1].startsWith('-')) {
+			if (i + 1 < args.length && !isOptionArg(args[i + 1])) {
 				value = args[i + 1];
 				i++; // Skip next element as it is a value
 			} else {
@@ -440,10 +507,9 @@ const parseArgs = (args) => {
 			}
 			result[key] = value;
 		} else {
-			result._.push(args[i]);
+			result._.push(arg);
 		}
 	}
-	// @ts-ignore
 	return result;
 };
 
@@ -463,4 +529,4 @@ export {
 	assert,
 	AsyncTracker,
 	bashEscape
-}
+};