@fuzdev/fuz_util 0.46.0 → 0.48.0

package/dist/args.d.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+/**
+ * CLI arguments container.
+ * Positional arguments stored in `_`, named flags/options as string keys.
+ * Produced by `argv_parse` or external parsers (mri, minimist, etc.).
+ */
+export interface Args {
+    _?: Array<string>;
+    [key: string]: ArgValue;
+}
+/**
+ * Parsed CLI arguments with guaranteed positionals array.
+ * Returned by `argv_parse` which always initializes `_`.
+ */
+export interface ParsedArgs extends Args {
+    _: Array<string>;
+}
+/**
+ * Value types supported in CLI arguments.
+ */
+export type ArgValue = string | number | boolean | undefined | Array<string | number | boolean>;
+/**
+ * Schema description for help text generation.
+ * Not used by args_parse/args_serialize directly - provided for consumers
+ * building CLI help output.
+ */
+export interface ArgSchema {
+    type: string;
+    default: ArgValue;
+    description: string;
+}
+/**
+ * Result of alias extraction from a schema.
+ * Includes canonical keys for downstream conflict detection.
+ */
+export interface ArgsAliasesResult {
+    aliases: Map<string, string>;
+    canonical_keys: Set<string>;
+}
+/**
+ * Validates a zod schema for CLI arg usage.
+ *
+ * Checks for:
+ * - Alias conflicts with canonical keys
+ * - Duplicate aliases across different keys
+ *
+ * Results are cached per schema (WeakMap). Safe to call multiple times.
+ *
+ * @param schema Zod object schema with optional alias metadata
+ * @returns Validation result with success flag and optional error
+ */
+export declare const args_validate_schema: (schema: z.ZodType) => {
+    success: true;
+} | {
+    success: false;
+    error: z.ZodError;
+};
+/**
+ * Validates parsed CLI args against a zod schema.
+ *
+ * Handles CLI-specific concerns before validation:
+ * 1. Validates schema (cached) - returns error if alias conflicts exist
+ * 2. Expands aliases defined in schema `.meta({aliases: ['v']})`
+ * 3. Strips alias keys (required for strictObject schemas)
+ * 4. Validates with zod
+ * 5. After validation, syncs `no-` prefixed boolean flags with their base keys
+ *
+ * Schema analysis is cached per schema (WeakMap) for performance.
+ *
+ * @param unparsed_args Args object from CLI parser (mri, minimist, etc.)
+ * @param schema Zod object schema with optional alias metadata
+ * @returns Zod SafeParseResult with expanded/synced data on success
+ */
+export declare const args_parse: <TOutput extends Record<string, ArgValue> = Args>(unparsed_args: Args, schema: z.ZodType<TOutput>) => z.ZodSafeParseResult<TOutput>;
+/**
+ * Serializes Args to CLI string array for subprocess forwarding.
+ *
+ * Handles CLI conventions:
+ * - Positionals first, then flags
+ * - Single-char keys get single dash, multi-char get double dash
+ * - Boolean `true` becomes bare flag, `false` is skipped
+ * - `undefined` values are skipped
+ * - `no-` prefixed keys skipped when base key is truthy (avoid contradiction)
+ * - When schema provided, extracts aliases and prefers shortest form
+ *
+ * Schema analysis is cached per schema (WeakMap) for performance.
+ *
+ * @param args Args object to serialize
+ * @param schema Optional zod schema to extract aliases for short form preference
+ * @returns Array of CLI argument strings
+ */
+export declare const args_serialize: (args: Args, schema?: z.ZodType) => Array<string>;
+/**
+ * Extracts alias mappings and canonical keys from a zod schema's metadata.
+ *
+ * Useful for consumers building custom tooling (help generators, conflict detection, etc.).
+ * Results are cached per schema (WeakMap).
+ *
+ * Note: Returns copies of the cached data to prevent mutation of internal cache.
+ *
+ * @param schema Zod object schema with optional `.meta({aliases})` on fields
+ * @returns Object with aliases map and canonical_keys set
+ */
+export declare const args_extract_aliases: (schema: z.ZodType) => ArgsAliasesResult;
+/**
+ * Parses raw CLI argv array into an Args object.
+ *
+ * A lightweight, dependency-free alternative to mri/minimist with compatible behavior.
+ *
+ * Features:
+ * - `--flag` → `{flag: true}`
+ * - `--flag value` → `{flag: 'value'}` or `{flag: 123}` (numeric coercion)
+ * - `--flag=value` → equals syntax
+ * - `--flag=` → `{flag: ''}` (empty string, differs from mri which returns true)
+ * - `-f` → `{f: true}` (short flag)
+ * - `-f value` → `{f: 'value'}`
+ * - `-abc` → `{a: true, b: true, c: true}` (combined short flags)
+ * - `-abc value` → `{a: true, b: true, c: 'value'}` (last flag gets value)
+ * - `--no-flag` → `{flag: false}` (negation prefix)
+ * - `--` → stops flag parsing, rest become positionals
+ * - Positionals collected in `_` array
+ * - Repeated flags become arrays
+ *
+ * Intentional differences from mri:
+ * - `--flag=` returns `''` (mri returns `true`)
+ * - `--flag= next` returns `{flag: '', _: ['next']}` (mri takes `next` as the value)
+ * - `---flag` returns `{'-flag': true}` (mri strips all dashes)
+ * - `['--flag', '']` preserves `''` (mri coerces to `0`)
+ * - `--__proto__` works as a normal key (mri silently fails)
+ *
+ * The returned object uses `Object.create(null)` to prevent prototype pollution
+ * and allow any key name including `__proto__` and `constructor`.
+ *
+ * @param argv Raw argument array (typically process.argv.slice(2))
+ * @returns Parsed Args object with guaranteed `_` array (null prototype)
+ */
+export declare const argv_parse: (argv: Array<string>) => ParsedArgs;
+//# sourceMappingURL=args.d.ts.map

package/dist/args.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/args.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAEtB;;;;GAIG;AACH,MAAM,WAAW,IAAI;IACpB,CAAC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,UAAW,SAAQ,IAAI;IACvC,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;AAEhG;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,QAAQ,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,cAAc,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC5B;AAsID;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAChC,QAAQ,CAAC,CAAC,OAAO,KACf;IAAC,OAAO,EAAE,IAAI,CAAA;CAAC,GAAG;IAAC,OAAO,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC,QAAQ,CAAA;CAMtD,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,SAAS,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,IAAI,EACzE,eAAe,IAAI,EACnB,QAAQ,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,KACxB,CAAC,CAAC,kBAAkB,CAAC,OAAO,CA6C9B,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,cAAc,GAAI,MAAM,IAAI,EAAE,SAAS,CAAC,CAAC,OAAO,KAAG,KAAK,CAAC,MAAM,CA2D3E,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,GAAI,QAAQ,CAAC,CAAC,OAAO,KAAG,iBAMxD,CAAC;AAgCF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,UAAU,GAAI,MAAM,KAAK,CAAC,MAAM,CAAC,KAAG,UAyHhD,CAAC"}

package/dist/args.js

@@ -0,0 +1,447 @@
+import { z } from 'zod';
+// WeakMap cache for schema analysis - avoids redundant reflection
+const schema_cache = new WeakMap();
+// Internal: Unwrap nested schema types (Optional, Default, Transform, Pipe)
+const unwrap_schema = (def) => {
+    if ('innerType' in def)
+        return def.innerType; // Optional, Nullable
+    if ('in' in def)
+        return def.in; // Pipe
+    if ('schema' in def)
+        return def.schema; // Default, Transform
+    return undefined;
+};
+// Internal: Check if schema type is boolean (recursing through wrappers)
+const is_boolean_field = (schema) => {
+    const def = schema._zod.def;
+    if (def.type === 'boolean')
+        return true;
+    const inner = unwrap_schema(def);
+    if (inner)
+        return is_boolean_field(inner);
+    return false;
+};
+// Internal: Analyze schema for aliases, canonical keys, boolean keys, and conflicts
+const analyze_schema = (schema) => {
+    const aliases = new Map();
+    const canonical_keys = new Set();
+    const boolean_keys = new Set();
+    const errors = [];
+    const def = schema._zod.def;
+    // Unwrap to get object def (handle wrapped types like optional, default, etc.)
+    let obj_def = def;
+    while (!('shape' in obj_def)) {
+        const inner = unwrap_schema(obj_def);
+        if (!inner)
+            return { aliases, canonical_keys, boolean_keys, errors };
+        obj_def = inner._zod.def;
+    }
+    const shape = obj_def.shape;
+    // First pass: collect all canonical keys
+    for (const key of Object.keys(shape)) {
+        canonical_keys.add(key);
+    }
+    // Second pass: process fields for aliases and booleans
+    for (const [key, field] of Object.entries(shape)) {
+        const field_schema = field;
+        // Track boolean fields for no- prefix sync
+        if (is_boolean_field(field_schema)) {
+            boolean_keys.add(key);
+        }
+        const meta = field_schema.meta();
+        if (meta?.aliases) {
+            for (const alias of meta.aliases) {
+                // Check for alias-canonical conflict
+                if (canonical_keys.has(alias)) {
+                    errors.push({
+                        type: 'alias_canonical_conflict',
+                        alias,
+                        canonical: key,
+                        conflict_with: alias,
+                    });
+                }
+                // Check for duplicate alias
+                else if (aliases.has(alias)) {
+                    errors.push({
+                        type: 'duplicate_alias',
+                        alias,
+                        canonical: key,
+                        conflict_with: aliases.get(alias),
+                    });
+                }
+                else {
+                    aliases.set(alias, key);
+                }
+            }
+        }
+    }
+    return { aliases, canonical_keys, boolean_keys, errors };
+};
+// Internal: Convert analysis errors to ZodError for consistent API
+const to_conflict_error = (errors) => {
+    return new z.ZodError(errors.map((err) => ({
+        code: 'custom',
+        path: [err.alias],
+        message: err.type === 'alias_canonical_conflict'
+            ? `Alias '${err.alias}' for '${err.canonical}' conflicts with canonical key '${err.conflict_with}'`
+            : `Alias '${err.alias}' is used by both '${err.canonical}' and '${err.conflict_with}'`,
+    })));
+};
+// Internal: Get or create cache entry for schema
+const get_schema_cache = (schema) => {
+    let entry = schema_cache.get(schema);
+    if (!entry) {
+        const analysis = analyze_schema(schema);
+        entry = {
+            aliases: analysis.aliases,
+            canonical_keys: analysis.canonical_keys,
+            boolean_keys: analysis.boolean_keys,
+            conflict_error: analysis.errors.length > 0 ? to_conflict_error(analysis.errors) : null,
+        };
+        schema_cache.set(schema, entry);
+    }
+    return entry;
+};
+/**
+ * Validates a zod schema for CLI arg usage.
+ *
+ * Checks for:
+ * - Alias conflicts with canonical keys
+ * - Duplicate aliases across different keys
+ *
+ * Results are cached per schema (WeakMap). Safe to call multiple times.
+ *
+ * @param schema Zod object schema with optional alias metadata
+ * @returns Validation result with success flag and optional error
+ */
+export const args_validate_schema = (schema) => {
+    const cache = get_schema_cache(schema);
+    if (cache.conflict_error) {
+        return { success: false, error: cache.conflict_error };
+    }
+    return { success: true };
+};
+/**
+ * Validates parsed CLI args against a zod schema.
+ *
+ * Handles CLI-specific concerns before validation:
+ * 1. Validates schema (cached) - returns error if alias conflicts exist
+ * 2. Expands aliases defined in schema `.meta({aliases: ['v']})`
+ * 3. Strips alias keys (required for strictObject schemas)
+ * 4. Validates with zod
+ * 5. After validation, syncs `no-` prefixed boolean flags with their base keys
+ *
+ * Schema analysis is cached per schema (WeakMap) for performance.
+ *
+ * @param unparsed_args Args object from CLI parser (mri, minimist, etc.)
+ * @param schema Zod object schema with optional alias metadata
+ * @returns Zod SafeParseResult with expanded/synced data on success
+ */
+export const args_parse = (unparsed_args, schema) => {
+    const cache = get_schema_cache(schema);
+    // Return conflict error if schema has issues
+    if (cache.conflict_error) {
+        return { success: false, error: cache.conflict_error };
+    }
+    // Build expanded args - copy canonical, expand aliases, strip alias keys
+    const expanded = {};
+    for (const [key, value] of Object.entries(unparsed_args)) {
+        if (cache.aliases.has(key)) {
+            const canonical = cache.aliases.get(key);
+            // Only expand if canonical not already present (canonical takes precedence)
+            if (!(canonical in expanded) && !(canonical in unparsed_args)) {
+                expanded[canonical] = value;
+            }
+            // Don't copy alias key (strip it)
+        }
+        else {
+            expanded[key] = value;
+        }
+    }
+    // Validate with zod
+    const parsed = schema.safeParse(expanded);
+    if (parsed.success) {
+        // Mutate data with the correct source of truth for no- prefixed args
+        const data = parsed.data;
+        for (const key in data) {
+            if (key.startsWith('no-')) {
+                const base_key = key.substring(3);
+                // Only sync if both keys are booleans in the schema
+                if (cache.boolean_keys.has(key) && cache.boolean_keys.has(base_key)) {
+                    if (!(key in unparsed_args) && !(key in expanded)) {
+                        data[key] = !data[base_key];
+                    }
+                    else if (!(base_key in unparsed_args) && !(base_key in expanded)) {
+                        data[base_key] = !data[key];
+                    }
+                }
+            }
+        }
+    }
+    return parsed;
+};
+/**
+ * Serializes Args to CLI string array for subprocess forwarding.
+ *
+ * Handles CLI conventions:
+ * - Positionals first, then flags
+ * - Single-char keys get single dash, multi-char get double dash
+ * - Boolean `true` becomes bare flag, `false` is skipped
+ * - `undefined` values are skipped
+ * - `no-` prefixed keys skipped when base key is truthy (avoid contradiction)
+ * - When schema provided, extracts aliases and prefers shortest form
+ *
+ * Schema analysis is cached per schema (WeakMap) for performance.
+ *
+ * @param args Args object to serialize
+ * @param schema Optional zod schema to extract aliases for short form preference
+ * @returns Array of CLI argument strings
+ */
+export const args_serialize = (args, schema) => {
+    const result = [];
+    // Build reverse map (canonical → shortest alias) if schema provided
+    let shortest_names;
+    if (schema) {
+        const cache = get_schema_cache(schema);
+        shortest_names = new Map();
+        // Group aliases by canonical key
+        const aliases_by_canonical = new Map();
+        for (const [alias, canonical] of cache.aliases) {
+            if (!aliases_by_canonical.has(canonical)) {
+                aliases_by_canonical.set(canonical, []);
+            }
+            aliases_by_canonical.get(canonical).push(alias);
+        }
+        // Find shortest for each canonical
+        for (const [canonical, aliases] of aliases_by_canonical) {
+            const all_names = [canonical, ...aliases];
+            const shortest = all_names.reduce((a, b) => (a.length <= b.length ? a : b));
+            shortest_names.set(canonical, shortest);
+        }
+    }
+    const add_value = (name, value) => {
+        if (value === undefined)
+            return;
+        if (value === false)
+            return; // Can't represent false as bare flag
+        result.push(name);
+        if (typeof value !== 'boolean') {
+            result.push(value + '');
+        }
+    };
+    let positionals = null;
+    for (const [key, value] of Object.entries(args)) {
+        if (key === '_') {
+            positionals = value ? value.map((v) => v + '') : [];
+        }
+        else {
+            // Skip no-X if X exists and is truthy
+            if (key.startsWith('no-')) {
+                const base = key.substring(3);
+                if (base in args && args[base]) {
+                    continue; // Skip redundant no- flag
+                }
+            }
+            // Determine the name to use (prefer shortest if schema provided)
+            const use_key = shortest_names?.get(key) ?? key;
+            const name = `${use_key.length === 1 ? '-' : '--'}${use_key}`;
+            if (Array.isArray(value)) {
+                for (const v of value)
+                    add_value(name, v);
+            }
+            else {
+                add_value(name, value);
+            }
+        }
+    }
+    return positionals ? [...positionals, ...result] : result;
+};
+/**
+ * Extracts alias mappings and canonical keys from a zod schema's metadata.
+ *
+ * Useful for consumers building custom tooling (help generators, conflict detection, etc.).
+ * Results are cached per schema (WeakMap).
+ *
+ * Note: Returns copies of the cached data to prevent mutation of internal cache.
+ *
+ * @param schema Zod object schema with optional `.meta({aliases})` on fields
+ * @returns Object with aliases map and canonical_keys set
+ */
+export const args_extract_aliases = (schema) => {
+    const cache = get_schema_cache(schema);
+    return {
+        aliases: new Map(cache.aliases),
+        canonical_keys: new Set(cache.canonical_keys),
+    };
+};
+// Internal: Try to coerce a string value to number if it looks numeric
+const coerce_value = (value) => {
+    // Handle empty string
+    if (value === '')
+        return value;
+    // Try to parse as number
+    const num = Number(value);
+    // Return number if valid and finite, otherwise keep as string
+    // This matches mri behavior: "123" -> 123, "12.5" -> 12.5, "1e5" -> 100000
+    // But "123abc" -> "123abc", "NaN" -> "NaN", "Infinity" -> "Infinity"
+    if (!Number.isNaN(num) && Number.isFinite(num) && value.trim() !== '') {
+        return num;
+    }
+    return value;
+};
+// Internal: Set a value on args, handling arrays for repeated flags
+const set_arg = (args, key, value) => {
+    if (key in args) {
+        // Convert to array or push to existing array
+        const existing = args[key];
+        if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else {
+            args[key] = [existing, value];
+        }
+    }
+    else {
+        args[key] = value;
+    }
+};
+/**
+ * Parses raw CLI argv array into an Args object.
+ *
+ * A lightweight, dependency-free alternative to mri/minimist with compatible behavior.
+ *
+ * Features:
+ * - `--flag` → `{flag: true}`
+ * - `--flag value` → `{flag: 'value'}` or `{flag: 123}` (numeric coercion)
+ * - `--flag=value` → equals syntax
+ * - `--flag=` → `{flag: ''}` (empty string, differs from mri which returns true)
+ * - `-f` → `{f: true}` (short flag)
+ * - `-f value` → `{f: 'value'}`
+ * - `-abc` → `{a: true, b: true, c: true}` (combined short flags)
+ * - `-abc value` → `{a: true, b: true, c: 'value'}` (last flag gets value)
+ * - `--no-flag` → `{flag: false}` (negation prefix)
+ * - `--` → stops flag parsing, rest become positionals
+ * - Positionals collected in `_` array
+ * - Repeated flags become arrays
+ *
+ * Intentional differences from mri:
+ * - `--flag=` returns `''` (mri returns `true`)
+ * - `--flag= next` returns `{flag: '', _: ['next']}` (mri takes `next` as the value)
+ * - `---flag` returns `{'-flag': true}` (mri strips all dashes)
+ * - `['--flag', '']` preserves `''` (mri coerces to `0`)
+ * - `--__proto__` works as a normal key (mri silently fails)
+ *
+ * The returned object uses `Object.create(null)` to prevent prototype pollution
+ * and allow any key name including `__proto__` and `constructor`.
+ *
+ * @param argv Raw argument array (typically process.argv.slice(2))
+ * @returns Parsed Args object with guaranteed `_` array (null prototype)
+ */
+export const argv_parse = (argv) => {
+    // Use Object.create(null) to allow __proto__ as a normal key
+    // This prevents prototype pollution and makes all key names work
+    const args = Object.create(null);
+    args._ = [];
+    const positionals = args._;
+    let i = 0;
+    let flags_done = false; // Set to true after seeing --
+    while (i < argv.length) {
+        const arg = argv[i];
+        // After --, everything is a positional
+        if (flags_done) {
+            positionals.push(arg);
+            i++;
+            continue;
+        }
+        // -- stops flag parsing
+        if (arg === '--') {
+            flags_done = true;
+            i++;
+            continue;
+        }
+        // Long flag: --flag or --flag=value or --no-flag
+        if (arg.startsWith('--')) {
+            const rest = arg.slice(2);
+            // Handle --flag=value
+            const equals_index = rest.indexOf('=');
+            if (equals_index !== -1) {
+                const key = rest.slice(0, equals_index);
+                const value = rest.slice(equals_index + 1);
+                // Empty value after = becomes empty string (explicit value assignment)
+                // This differs from mri which treats it as boolean true
+                set_arg(args, key, coerce_value(value));
+                i++;
+                continue;
+            }
+            // Handle --no-flag (negation) - includes --no- which sets '' to false
+            if (rest.startsWith('no-')) {
+                const key = rest.slice(3); // May be empty string for --no-
+                args[key] = false;
+                i++;
+                continue;
+            }
+            // Handle --flag or --flag value
+            const key = rest;
+            const next = argv[i + 1];
+            // If next arg exists and doesn't look like a flag, it's the value
+            if (next !== undefined && !next.startsWith('-')) {
+                set_arg(args, key, coerce_value(next));
+                i += 2;
+            }
+            else {
+                // Boolean flag
+                args[key] = true;
+                i++;
+            }
+            continue;
+        }
+        // Single dash is ignored (matches mri)
+        if (arg === '-') {
+            i++;
+            continue;
+        }
+        // Short flag(s): -f or -abc or -f value
+        if (arg.startsWith('-') && arg.length > 1) {
+            const chars = arg.slice(1);
+            // Handle -f=value (short flag with equals)
+            const equals_index = chars.indexOf('=');
+            if (equals_index !== -1) {
+                const key = chars.slice(0, equals_index);
+                const value = chars.slice(equals_index + 1);
+                // For -abc=value, set a and b to true, c gets value
+                for (let j = 0; j < key.length - 1; j++) {
+                    args[key[j]] = true;
+                }
+                if (key.length > 0) {
+                    set_arg(args, key[key.length - 1], coerce_value(value));
+                }
+                i++;
+                continue;
+            }
+            // Handle combined flags: -abc means -a -b -c
+            // Last flag can take a value if next arg isn't a flag
+            const next = argv[i + 1];
+            const has_value = next !== undefined && !next.startsWith('-');
+            for (let j = 0; j < chars.length; j++) {
+                const char = chars[j];
+                const is_last = j === chars.length - 1;
+                if (is_last && has_value) {
+                    // Last char gets the value
+                    set_arg(args, char, coerce_value(next));
+                    i += 2;
+                }
+                else {
+                    // Boolean flag
+                    args[char] = true;
+                    if (is_last)
+                        i++;
+                }
+            }
+            continue;
+        }
+        // Positional argument
+        positionals.push(arg);
+        i++;
+    }
+    return args;
+};

package/dist/process.d.ts

@@ -8,6 +8,8 @@ export interface SpawnResultError {
     ok: false;
     child: ChildProcess;
     error: Error;
+    code: null;
+    signal: null;
 }
 /**
  * Process ran and exited with a code.
@@ -16,6 +18,7 @@ export interface SpawnResultError {
 export interface SpawnResultExited {
     ok: boolean;
     child: ChildProcess;
+    error: null;
     code: number;
     signal: null;
 }
@@ -25,6 +28,7 @@ export interface SpawnResultExited {
 export interface SpawnResultSignaled {
     ok: false;
     child: ChildProcess;
+    error: null;
     code: null;
     signal: NodeJS.Signals;
 }

package/dist/process.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"process.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/process.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"process.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/process.ts"],"names":[],"mappings":"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"}

package/dist/process.js

@@ -10,15 +10,15 @@ const log = new Logger('process');
 /**
  * Type guard for spawn errors (process failed to start).
  */
-export const spawn_result_is_error = (result) => 'error' in result;
+export const spawn_result_is_error = (result) => result.error !== null;
 /**
  * Type guard for signal termination.
  */
-export const spawn_result_is_signaled = (result) => 'signal' in result && result.signal !== null;
+export const spawn_result_is_signaled = (result) => result.signal !== null;
 /**
  * Type guard for normal exit with code.
  */
-export const spawn_result_is_exited = (result) => 'code' in result && result.code !== null;
+export const spawn_result_is_exited = (result) => result.code !== null;
 //
 // Internal Helpers
 //
@@ -37,17 +37,17 @@ const create_closed_promise = (child) => {
         if (resolved)
             return;
         resolved = true;
-        resolve({ ok: false, child, error: err });
+        resolve({ ok: false, child, error: err, code: null, signal: null });
     });
     child.once('close', (code, signal) => {
         if (resolved)
             return;
         resolved = true;
         if (signal !== null) {
-            resolve({ ok: false, child, code: null, signal });
+            resolve({ ok: false, child, error: null, code: null, signal });
         }
         else {
-            resolve({ ok: code === 0, child, code: code ?? 0, signal: null });
+            resolve({ ok: code === 0, child, error: null, code: code ?? 0, signal: null });
         }
     });
     return closed;
@@ -190,6 +190,7 @@ export class ProcessRegistry {
             return {
                 ok: child.exitCode === 0,
                 child,
+                error: null,
                 code: child.exitCode,
                 signal: null,
             };
@@ -199,6 +200,7 @@ export class ProcessRegistry {
             return {
                 ok: false,
                 child,
+                error: null,
                 code: null,
                 signal: child.signalCode,
             };