@jini-ai/platform 0.1.0

package/dist/process.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @module process
+ *
+ * OS process lifecycle and stamp primitives: encode/decode `--flag=value`
+ * process stamps and match them against a contract, spawn background and logged
+ * child processes, probe liveness, enumerate process snapshots (POSIX `ps` /
+ * Windows `Get-CimInstance`), walk a process tree, and stop a set of PIDs with
+ * SIGTERM-then-SIGKILL escalation.
+ *
+ * Depends on the `command` module for invocation construction; keeps a private
+ * `errorCode` copy so it owns no cross-module runtime surface.
+ */
+import { type ChildProcess } from "node:child_process";
+import { type CommandInvocationRequest } from "./command.js";
+export type ProcessStampShape = object;
+export type ProcessStampField<TStamp extends ProcessStampShape> = Extract<keyof TStamp, string>;
+export type ProcessStampContract<TStamp extends ProcessStampShape, TCriteria extends Partial<TStamp> = Partial<TStamp>> = {
+    normalizeStamp(input: unknown): TStamp;
+    normalizeStampCriteria(input?: unknown): TCriteria;
+    stampFields: readonly ProcessStampField<TStamp>[];
+    stampFlags: {
+        readonly [K in ProcessStampField<TStamp>]: string;
+    };
+};
+export type SpawnProcessRequest = CommandInvocationRequest & {
+    cwd?: string;
+    detached?: boolean;
+    logFd?: number | null;
+};
+export type ProcessSnapshot = {
+    command: string;
+    pid: number;
+    ppid: number;
+};
+export type StampedProcessMatchCriteria<TStamp extends ProcessStampShape> = Partial<TStamp>;
+export type StopProcessesResult = {
+    alreadyStopped: boolean;
+    forcedPids: number[];
+    matchedPids: number[];
+    remainingPids: number[];
+    stoppedPids: number[];
+};
+/**
+ * Serialize a process stamp into `--flag=value` CLI arguments per the contract.
+ * Every stamp field must normalize to a string or an error is thrown.
+ *
+ * @param stamp - The stamp object to encode.
+ * @param contract - The stamp contract providing field list, flags, and normalization.
+ * @returns The `--flag=value` argument strings, one per stamp field.
+ */
+export declare function createProcessStampArgs<TStamp extends ProcessStampShape>(stamp: TStamp, contract: ProcessStampContract<TStamp>): string[];
+/**
+ * Read the value of a CLI flag from an argument list, supporting both the
+ * `--flag value` and inline `--flag=value` forms.
+ *
+ * @param args - The argument list to search.
+ * @param flagName - The flag name (including any leading dashes).
+ * @returns The flag's value, or `null` when the flag is absent.
+ */
+export declare function readFlagValue(args: readonly string[], flagName: string): string | null;
+/**
+ * Decode a process stamp from a raw argument list per the contract, returning
+ * `null` when normalization fails (e.g. a required field is missing).
+ *
+ * @param args - The process argument list to read stamp flags from.
+ * @param contract - The stamp contract providing field list, flags, and normalization.
+ * @returns The decoded stamp, or `null` when it cannot be normalized.
+ */
+export declare function readProcessStamp<TStamp extends ProcessStampShape>(args: readonly string[], contract: ProcessStampContract<TStamp>): TStamp | null;
+/**
+ * Decode a process stamp from a full command-line string by tokenizing it first.
+ *
+ * @param command - The full command line to read stamp flags from.
+ * @param contract - The stamp contract providing field list, flags, and normalization.
+ * @returns The decoded stamp, or `null` when it cannot be normalized.
+ */
+export declare function readProcessStampFromCommand<TStamp extends ProcessStampShape>(command: string, contract: ProcessStampContract<TStamp>): TStamp | null;
+/**
+ * Test whether a stamp matches criteria: every criterion field that is set must
+ * equal the corresponding normalized stamp field; unset criteria fields match
+ * anything.
+ *
+ * @param stamp - The stamp to test.
+ * @param criteria - The partial criteria to match against (undefined matches all).
+ * @param contract - The stamp contract providing field list and normalization.
+ * @returns `true` when every specified criterion matches the stamp.
+ */
+export declare function matchesProcessStamp<TStamp extends ProcessStampShape, TCriteria extends Partial<TStamp> = Partial<TStamp>>(stamp: TStamp, criteria: TCriteria | undefined, contract: ProcessStampContract<TStamp, TCriteria>): boolean;
+/**
+ * Test whether a process snapshot's command line carries a stamp matching the
+ * criteria. Combines stamp decoding from the command with `matchesProcessStamp`.
+ *
+ * @param processInfo - A snapshot exposing at least the `command` string.
+ * @param criteria - The partial criteria to match against (undefined matches all).
+ * @param contract - The stamp contract providing field list and normalization.
+ * @returns `true` when the command carries a decodable stamp that matches.
+ */
+export declare function matchesStampedProcess<TStamp extends ProcessStampShape, TCriteria extends Partial<TStamp> = Partial<TStamp>>(processInfo: Pick<ProcessSnapshot, "command">, criteria: TCriteria | undefined, contract: ProcessStampContract<TStamp, TCriteria>): boolean;
+/**
+ * Spawn a detached background process, wait for it to actually start, then
+ * `unref` it so the parent can exit independently.
+ *
+ * @param request - The command/args/env plus cwd, detached, and log-fd options.
+ * @returns The spawned child's `{ pid }`.
+ * @throws If the child fails to spawn or reports no pid.
+ */
+export declare function spawnBackgroundProcess(request: SpawnProcessRequest): Promise<{
+    pid: number;
+}>;
+/**
+ * Spawn a (by default non-detached) child process with stdout/stderr routed to
+ * an optional log fd, waiting for it to start before returning the handle.
+ *
+ * @param request - The command/args/env plus cwd, detached, and log-fd options.
+ * @returns The live `ChildProcess` handle.
+ * @throws If the child fails to spawn or reports no pid.
+ */
+export declare function spawnLoggedProcess(request: SpawnProcessRequest): Promise<ChildProcess>;
+/**
+ * Probe whether a process is alive via a signal-0 `process.kill`. Treats
+ * `ESRCH` as dead and any other error (e.g. `EPERM`) as alive.
+ *
+ * @param pid - The PID to probe (non-number values are treated as dead).
+ * @returns `true` when the process appears to exist.
+ */
+export declare function isProcessAlive(pid: number | null | undefined): boolean;
+/**
+ * Poll until a process exits or the timeout elapses.
+ *
+ * @param pid - The PID to wait on.
+ * @param timeoutMs - Maximum time to wait, in milliseconds (default 5000).
+ * @returns `true` if the process is gone by the deadline, otherwise `false`.
+ */
+export declare function waitForProcessExit(pid: number | null | undefined, timeoutMs?: number): Promise<boolean>;
+/**
+ * Enumerate all running processes as `{ pid, ppid, command }` snapshots, using
+ * the platform-appropriate backend. Returns an empty list on any failure.
+ *
+ * @returns The current process snapshots (empty on error).
+ */
+export declare function listProcessSnapshots(): Promise<ProcessSnapshot[]>;
+/**
+ * Collect the transitive set of descendant PIDs (including the roots) from a
+ * process snapshot list, returned sorted descending so children precede parents.
+ *
+ * @param processes - The full process snapshot list to walk.
+ * @param rootPids - The root PIDs whose subtrees to collect (non-numbers ignored).
+ * @returns The unique PIDs of the roots and all their descendants, descending.
+ */
+export declare function collectProcessTreePids(processes: ProcessSnapshot[], rootPids: Array<number | null | undefined>): number[];
+/**
+ * Stop a set of PIDs with escalation: SIGTERM, wait, then SIGKILL any
+ * survivors. Excludes the current process and de-duplicates the input.
+ *
+ * @param pids - The PIDs to stop (non-numbers and the current PID are ignored).
+ * @returns A result describing matched, stopped, force-killed, and remaining PIDs.
+ */
+export declare function stopProcesses(pids: Array<number | null | undefined>): Promise<StopProcessesResult>;
+//# sourceMappingURL=process.d.ts.map

package/dist/process.d.ts.map

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

package/dist/process.js

@@ -0,0 +1,362 @@
+/**
+ * @module process
+ *
+ * OS process lifecycle and stamp primitives: encode/decode `--flag=value`
+ * process stamps and match them against a contract, spawn background and logged
+ * child processes, probe liveness, enumerate process snapshots (POSIX `ps` /
+ * Windows `Get-CimInstance`), walk a process tree, and stop a set of PIDs with
+ * SIGTERM-then-SIGKILL escalation.
+ *
+ * Depends on the `command` module for invocation construction; keeps a private
+ * `errorCode` copy so it owns no cross-module runtime surface.
+ */
+import { execFile, spawn } from "node:child_process";
+import { setTimeout as sleep } from "node:timers/promises";
+import { createCommandInvocation } from "./command.js";
+/** @internal Extract a Node `error.code` as a string, or `null` when the value carries no code. */
+function errorCode(error) {
+    if (typeof error !== "object" || error == null || !("code" in error))
+        return null;
+    const code = error.code;
+    return code == null ? null : String(code);
+}
+/**
+ * Serialize a process stamp into `--flag=value` CLI arguments per the contract.
+ * Every stamp field must normalize to a string or an error is thrown.
+ *
+ * @param stamp - The stamp object to encode.
+ * @param contract - The stamp contract providing field list, flags, and normalization.
+ * @returns The `--flag=value` argument strings, one per stamp field.
+ */
+export function createProcessStampArgs(stamp, contract) {
+    const normalized = contract.normalizeStamp(stamp);
+    return contract.stampFields.map((field) => {
+        const value = normalized[field];
+        if (typeof value !== "string") {
+            throw new Error(`process stamp field ${field} must normalize to a string`);
+        }
+        return `${contract.stampFlags[field]}=${value}`;
+    });
+}
+/** @internal Split a command line string into whitespace-separated argument tokens. */
+function commandArgs(command) {
+    return command.trim().split(/\s+/).filter((part) => part.length > 0);
+}
+/**
+ * Read the value of a CLI flag from an argument list, supporting both the
+ * `--flag value` and inline `--flag=value` forms.
+ *
+ * @param args - The argument list to search.
+ * @param flagName - The flag name (including any leading dashes).
+ * @returns The flag's value, or `null` when the flag is absent.
+ */
+export function readFlagValue(args, flagName) {
+    const inlinePrefix = `${flagName}=`;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === flagName)
+            return args[index + 1] ?? null;
+        if (typeof argument === "string" && argument.startsWith(inlinePrefix)) {
+            return argument.slice(inlinePrefix.length);
+        }
+    }
+    return null;
+}
+/**
+ * Decode a process stamp from a raw argument list per the contract, returning
+ * `null` when normalization fails (e.g. a required field is missing).
+ *
+ * @param args - The process argument list to read stamp flags from.
+ * @param contract - The stamp contract providing field list, flags, and normalization.
+ * @returns The decoded stamp, or `null` when it cannot be normalized.
+ */
+export function readProcessStamp(args, contract) {
+    try {
+        const input = Object.fromEntries(contract.stampFields.map((field) => [field, readFlagValue(args, contract.stampFlags[field])]));
+        return contract.normalizeStamp(input);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decode a process stamp from a full command-line string by tokenizing it first.
+ *
+ * @param command - The full command line to read stamp flags from.
+ * @param contract - The stamp contract providing field list, flags, and normalization.
+ * @returns The decoded stamp, or `null` when it cannot be normalized.
+ */
+export function readProcessStampFromCommand(command, contract) {
+    return readProcessStamp(commandArgs(command), contract);
+}
+/**
+ * Test whether a stamp matches criteria: every criterion field that is set must
+ * equal the corresponding normalized stamp field; unset criteria fields match
+ * anything.
+ *
+ * @param stamp - The stamp to test.
+ * @param criteria - The partial criteria to match against (undefined matches all).
+ * @param contract - The stamp contract providing field list and normalization.
+ * @returns `true` when every specified criterion matches the stamp.
+ */
+export function matchesProcessStamp(stamp, criteria, contract) {
+    const normalizedStamp = contract.normalizeStamp(stamp);
+    const normalizedCriteria = contract.normalizeStampCriteria(criteria ?? {});
+    return contract.stampFields.every((field) => {
+        const expected = normalizedCriteria[field];
+        return expected == null || normalizedStamp[field] === expected;
+    });
+}
+/**
+ * Test whether a process snapshot's command line carries a stamp matching the
+ * criteria. Combines stamp decoding from the command with `matchesProcessStamp`.
+ *
+ * @param processInfo - A snapshot exposing at least the `command` string.
+ * @param criteria - The partial criteria to match against (undefined matches all).
+ * @param contract - The stamp contract providing field list and normalization.
+ * @returns `true` when the command carries a decodable stamp that matches.
+ */
+export function matchesStampedProcess(processInfo, criteria, contract) {
+    const stamp = readProcessStampFromCommand(processInfo.command, contract);
+    return stamp != null && matchesProcessStamp(stamp, criteria, contract);
+}
+/** @internal Build the stdio triple for a spawned process, routing stdout/stderr to a log fd when provided. */
+function createLoggedStdio(logFd) {
+    return logFd == null ? ["ignore", "ignore", "ignore"] : ["ignore", logFd, logFd];
+}
+/** @internal Resolve once the child emits `spawn`, or reject on the child's `error` event. */
+async function waitForChildSpawn(child) {
+    await new Promise((resolveSpawn, rejectSpawn) => {
+        child.once("error", rejectSpawn);
+        child.once("spawn", resolveSpawn);
+    });
+}
+/**
+ * Spawn a detached background process, wait for it to actually start, then
+ * `unref` it so the parent can exit independently.
+ *
+ * @param request - The command/args/env plus cwd, detached, and log-fd options.
+ * @returns The spawned child's `{ pid }`.
+ * @throws If the child fails to spawn or reports no pid.
+ */
+export async function spawnBackgroundProcess(request) {
+    const invocation = createCommandInvocation(request);
+    const child = spawn(invocation.command, invocation.args, {
+        cwd: request.cwd,
+        detached: request.detached ?? true,
+        env: request.env,
+        stdio: createLoggedStdio(request.logFd),
+        windowsHide: process.platform === "win32",
+        windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+    });
+    await waitForChildSpawn(child);
+    if (child.pid == null)
+        throw new Error(`failed to spawn background process: ${invocation.command}`);
+    child.unref();
+    return { pid: child.pid };
+}
+/**
+ * Spawn a (by default non-detached) child process with stdout/stderr routed to
+ * an optional log fd, waiting for it to start before returning the handle.
+ *
+ * @param request - The command/args/env plus cwd, detached, and log-fd options.
+ * @returns The live `ChildProcess` handle.
+ * @throws If the child fails to spawn or reports no pid.
+ */
+export async function spawnLoggedProcess(request) {
+    const invocation = createCommandInvocation(request);
+    const child = spawn(invocation.command, invocation.args, {
+        cwd: request.cwd,
+        detached: request.detached ?? false,
+        env: request.env,
+        stdio: createLoggedStdio(request.logFd),
+        windowsHide: process.platform === "win32",
+        windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+    });
+    await waitForChildSpawn(child);
+    if (child.pid == null)
+        throw new Error(`failed to spawn process: ${invocation.command}`);
+    return child;
+}
+/**
+ * Probe whether a process is alive via a signal-0 `process.kill`. Treats
+ * `ESRCH` as dead and any other error (e.g. `EPERM`) as alive.
+ *
+ * @param pid - The PID to probe (non-number values are treated as dead).
+ * @returns `true` when the process appears to exist.
+ */
+export function isProcessAlive(pid) {
+    if (typeof pid !== "number")
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "ESRCH")
+            return false;
+        return true;
+    }
+}
+/**
+ * Poll until a process exits or the timeout elapses.
+ *
+ * @param pid - The PID to wait on.
+ * @param timeoutMs - Maximum time to wait, in milliseconds (default 5000).
+ * @returns `true` if the process is gone by the deadline, otherwise `false`.
+ */
+export async function waitForProcessExit(pid, timeoutMs = 5000) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        if (!isProcessAlive(pid))
+            return true;
+        await sleep(100);
+    }
+    return !isProcessAlive(pid);
+}
+/** @internal Parse `ps -axo pid=,ppid=,command=` output into process snapshots. */
+function parsePsOutput(stdout) {
+    return stdout
+        .split(/\r?\n/)
+        .map((line) => {
+        const match = line.match(/^\s*(\d+)\s+(\d+)\s+(.+)$/);
+        if (!match)
+            return null;
+        return { pid: Number(match[1]), ppid: Number(match[2]), command: match[3] };
+    })
+        .filter((snapshot) => snapshot != null);
+}
+/** @internal Enumerate process snapshots on POSIX via `ps`. */
+async function listPosixProcessSnapshots() {
+    const stdout = await new Promise((resolveList, rejectList) => {
+        execFile("ps", ["-axo", "pid=,ppid=,command="], { encoding: "utf8", maxBuffer: 8 * 1024 * 1024 }, (error, out) => {
+            if (error)
+                rejectList(error);
+            else
+                resolveList(out);
+        });
+    });
+    return parsePsOutput(stdout);
+}
+/** @internal Enumerate process snapshots on Windows via `Get-CimInstance Win32_Process` JSON. */
+async function listWindowsProcessSnapshots() {
+    const command = [
+        "$ErrorActionPreference = 'Stop'",
+        "Get-CimInstance Win32_Process | Select-Object ProcessId, ParentProcessId, CommandLine | ConvertTo-Json -Compress",
+    ].join("; ");
+    const stdout = await new Promise((resolveList, rejectList) => {
+        execFile("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", command], { encoding: "utf8", maxBuffer: 8 * 1024 * 1024 }, (error, out) => {
+            if (error)
+                rejectList(error);
+            else
+                resolveList(out);
+        });
+    });
+    const payload = stdout.trim();
+    if (!payload)
+        return [];
+    const records = JSON.parse(payload);
+    return (Array.isArray(records) ? records : [records])
+        .map((record) => {
+        const pid = Number(record.ProcessId);
+        const ppid = Number(record.ParentProcessId);
+        const commandLine = record.CommandLine?.trim();
+        if (!commandLine || Number.isNaN(pid) || Number.isNaN(ppid))
+            return null;
+        return { command: commandLine, pid, ppid };
+    })
+        .filter((snapshot) => snapshot != null);
+}
+/**
+ * Enumerate all running processes as `{ pid, ppid, command }` snapshots, using
+ * the platform-appropriate backend. Returns an empty list on any failure.
+ *
+ * @returns The current process snapshots (empty on error).
+ */
+export async function listProcessSnapshots() {
+    try {
+        return process.platform === "win32"
+            ? await listWindowsProcessSnapshots()
+            : await listPosixProcessSnapshots();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Collect the transitive set of descendant PIDs (including the roots) from a
+ * process snapshot list, returned sorted descending so children precede parents.
+ *
+ * @param processes - The full process snapshot list to walk.
+ * @param rootPids - The root PIDs whose subtrees to collect (non-numbers ignored).
+ * @returns The unique PIDs of the roots and all their descendants, descending.
+ */
+export function collectProcessTreePids(processes, rootPids) {
+    const queue = [...new Set(rootPids.filter((pid) => typeof pid === "number"))];
+    const visited = new Set();
+    const childrenByParent = new Map();
+    for (const processInfo of processes) {
+        const children = childrenByParent.get(processInfo.ppid) ?? [];
+        children.push(processInfo.pid);
+        childrenByParent.set(processInfo.ppid, children);
+    }
+    while (queue.length > 0) {
+        const pid = queue.shift();
+        if (pid == null || visited.has(pid))
+            continue;
+        visited.add(pid);
+        for (const childPid of childrenByParent.get(pid) ?? []) {
+            if (!visited.has(childPid))
+                queue.push(childPid);
+        }
+    }
+    return [...visited].sort((left, right) => right - left);
+}
+/** @internal Send a signal to each PID, ignoring `ESRCH` (already-dead) but rethrowing other errors. */
+function signalProcesses(pids, signal) {
+    for (const pid of pids) {
+        try {
+            process.kill(pid, signal);
+        }
+        catch (error) {
+            if (errorCode(error) !== "ESRCH")
+                throw error;
+        }
+    }
+}
+/** @internal Poll until all PIDs exit or the timeout elapses; returns the PIDs still alive. */
+async function waitForProcessesToExit(pids, timeoutMs = 5000) {
+    const startedAt = Date.now();
+    while (Date.now() - startedAt < timeoutMs) {
+        const remaining = pids.filter(isProcessAlive);
+        if (remaining.length === 0)
+            return [];
+        await sleep(100);
+    }
+    return pids.filter(isProcessAlive);
+}
+/**
+ * Stop a set of PIDs with escalation: SIGTERM, wait, then SIGKILL any
+ * survivors. Excludes the current process and de-duplicates the input.
+ *
+ * @param pids - The PIDs to stop (non-numbers and the current PID are ignored).
+ * @returns A result describing matched, stopped, force-killed, and remaining PIDs.
+ */
+export async function stopProcesses(pids) {
+    const uniquePids = [...new Set(pids)]
+        .filter((pid) => typeof pid === "number" && pid !== process.pid)
+        .sort((left, right) => right - left);
+    if (uniquePids.length === 0) {
+        return { alreadyStopped: true, forcedPids: [], matchedPids: [], remainingPids: [], stoppedPids: [] };
+    }
+    signalProcesses(uniquePids, "SIGTERM");
+    const remainingAfterTerm = await waitForProcessesToExit(uniquePids);
+    if (remainingAfterTerm.length === 0) {
+        return { alreadyStopped: false, forcedPids: [], matchedPids: uniquePids, remainingPids: [], stoppedPids: uniquePids };
+    }
+    signalProcesses(remainingAfterTerm, "SIGKILL");
+    const remainingAfterKill = await waitForProcessesToExit(remainingAfterTerm);
+    const stoppedPids = uniquePids.filter((pid) => !remainingAfterKill.includes(pid));
+    return { alreadyStopped: false, forcedPids: remainingAfterTerm, matchedPids: uniquePids, remainingPids: remainingAfterKill, stoppedPids };
+}
+//# sourceMappingURL=process.js.map

package/dist/process.js.map

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

package/dist/proxy-env.d.ts

@@ -0,0 +1,50 @@
+export type SystemProxyCommandRunner = (command: string, args: string[]) => string;
+export type ResolveSystemProxyEnvOptions = {
+    platform?: NodeJS.Platform;
+    runCommand?: SystemProxyCommandRunner;
+};
+/**
+ * Merge multiple env sources into one proxy-consistent environment. Proxy
+ * variables are collapsed to their canonical spelling (preferring lowercase
+ * inputs), non-proxy keys pass through, and `NODE_USE_ENV_PROXY=1` is set when
+ * a proxy endpoint is present but the flag is not.
+ *
+ * @param platform - Target platform, controlling lowercase-alias emission.
+ * @param sources - Env sources merged left-to-right (later sources win).
+ * @returns A new merged environment with normalized proxy variables.
+ */
+export declare function mergeProxyAwareEnv(platform: NodeJS.Platform, ...sources: Array<NodeJS.ProcessEnv | Record<string, string | undefined>>): NodeJS.ProcessEnv;
+/**
+ * Parse macOS `scutil --proxy` output into a normalized proxy environment.
+ * Honors the HTTP/HTTPS/SOCKS enable flags, exception list, and the
+ * "exclude simple hostnames" toggle.
+ *
+ * @param stdout - Raw `scutil --proxy` output.
+ * @param platform - Target platform for env normalization (defaults to `"darwin"`).
+ * @returns A normalized proxy environment (empty when no proxy is enabled).
+ */
+export declare function parseMacosScutilProxyOutput(stdout: string, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+/**
+ * Parse Windows Internet Settings proxy registry output into a normalized proxy
+ * environment. Handles both the per-protocol (`http=…;https=…`) and shared
+ * single-endpoint `ProxyServer` forms, and the `ProxyOverride` bypass list.
+ *
+ * @param input - Raw `reg query` output for `ProxyEnable`, and optionally `ProxyServer` / `ProxyOverride`.
+ * @param platform - Target platform for env normalization (defaults to `"win32"`).
+ * @returns A normalized proxy environment (empty when proxying is disabled or unset).
+ */
+export declare function parseWindowsInternetSettingsProxyOutput(input: {
+    proxyEnable: string;
+    proxyOverride?: string;
+    proxyServer?: string;
+}, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
+/**
+ * Resolve the OS-level proxy configuration into a normalized proxy environment.
+ * Shells out to `scutil` on macOS and `reg query` on Windows (swallowing per-
+ * command failures), and returns an empty env on other platforms or on error.
+ *
+ * @param options - Optional platform override and command runner (for testing).
+ * @returns A normalized proxy environment, or `{}` when no proxy is configured.
+ */
+export declare function resolveSystemProxyEnv(options?: ResolveSystemProxyEnvOptions): NodeJS.ProcessEnv;
+//# sourceMappingURL=proxy-env.d.ts.map

package/dist/proxy-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy-env.d.ts","sourceRoot":"","sources":["../src/proxy-env.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,wBAAwB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,MAAM,CAAC;AAEnF,MAAM,MAAM,4BAA4B,GAAG;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC3B,UAAU,CAAC,EAAE,wBAAwB,CAAC;CACvC,CAAC;AAiDF;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,GAAG,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GACxE,MAAM,CAAC,UAAU,CA4BnB;AAyID;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAAM,CAAC,QAAmB,GACnC,MAAM,CAAC,UAAU,CAgDnB;AAQD;;;;;;;;GAQG;AACH,wBAAgB,uCAAuC,CACrD,KAAK,EAAE;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAC5E,QAAQ,GAAE,MAAM,CAAC,QAAkB,GAClC,MAAM,CAAC,UAAU,CAkCnB;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,GAAE,4BAAiC,GAAG,MAAM,CAAC,UAAU,CAoDnG"}