@3leaps/sysprims 0.1.7

package/LICENSE

@@ -0,0 +1,6 @@
+MIT OR Apache-2.0
+
+This package is part of the sysprims repository.
+See the repository root for full license texts:
+- LICENSE-MIT
+- LICENSE-APACHE

package/README.md

@@ -0,0 +1,31 @@
+# sysprims (TypeScript bindings)
+
+TypeScript/Node.js bindings for sysprims using a Node-API (N-API) native addon (napi-rs).
+
+## Platform support
+
+Supported:
+- macOS: arm64
+- Linux: glibc and musl (Alpine)
+- Windows: x64, arm64 (msvc)
+
+## Local development
+
+The native addon is built from Rust:
+
+```bash
+npm install
+npm run build
+npm run build:native
+npm run test:ci
+```
+
+## API (minimal)
+
+- `procGet(pid)` → returns parsed JSON from `sysprims_proc_get`
+- `selfPGID()` → calls `sysprims_self_getpgid`
+- `selfSID()` → calls `sysprims_self_getsid`
+
+## Safety
+
+These bindings call into a process-control library. Do not use dangerous PIDs.

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+export declare const SysprimsErrorCode: {
+    readonly Ok: 0;
+    readonly InvalidArgument: 1;
+    readonly SpawnFailed: 2;
+    readonly Timeout: 3;
+    readonly PermissionDenied: 4;
+    readonly NotFound: 5;
+    readonly NotSupported: 6;
+    readonly GroupCreationFailed: 7;
+    readonly System: 8;
+    readonly Internal: 99;
+};
+export type SysprimsErrorCode = (typeof SysprimsErrorCode)[keyof typeof SysprimsErrorCode];
+export declare class SysprimsError extends Error {
+    readonly code: SysprimsErrorCode;
+    readonly codeName: string;
+    constructor(code: SysprimsErrorCode, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB;;;;;;;;;;;CAWpB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAM3F,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAgB,IAAI,EAAE,iBAAiB,CAAC;IACxC,SAAgB,QAAQ,EAAE,MAAM,CAAC;gBAErB,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM;CAMrD"}

package/dist/errors.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SysprimsError = exports.SysprimsErrorCode = void 0;
+exports.SysprimsErrorCode = {
+    Ok: 0,
+    InvalidArgument: 1,
+    SpawnFailed: 2,
+    Timeout: 3,
+    PermissionDenied: 4,
+    NotFound: 5,
+    NotSupported: 6,
+    GroupCreationFailed: 7,
+    System: 8,
+    Internal: 99,
+};
+const errorCodeNames = Object.fromEntries(Object.entries(exports.SysprimsErrorCode).map(([k, v]) => [v, k]));
+class SysprimsError extends Error {
+    code;
+    codeName;
+    constructor(code, message) {
+        super(message);
+        this.name = "SysprimsError";
+        this.code = code;
+        this.codeName = errorCodeNames[code] ?? `Unknown(${code})`;
+    }
+}
+exports.SysprimsError = SysprimsError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAAa,QAAA,iBAAiB,GAAG;IAC/B,EAAE,EAAE,CAAC;IACL,eAAe,EAAE,CAAC;IAClB,WAAW,EAAE,CAAC;IACd,OAAO,EAAE,CAAC;IACV,gBAAgB,EAAE,CAAC;IACnB,QAAQ,EAAE,CAAC;IACX,YAAY,EAAE,CAAC;IACf,mBAAmB,EAAE,CAAC;IACtB,MAAM,EAAE,CAAC;IACT,QAAQ,EAAE,EAAE;CACJ,CAAC;AAIX,MAAM,cAAc,GAA2B,MAAM,CAAC,WAAW,CAC/D,MAAM,CAAC,OAAO,CAAC,yBAAiB,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAC1D,CAAC;AAEF,MAAa,aAAc,SAAQ,KAAK;IACtB,IAAI,CAAoB;IACxB,QAAQ,CAAS;IAEjC,YAAY,IAAuB,EAAE,OAAe;QAClD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,QAAQ,GAAG,cAAc,CAAC,IAAI,CAAC,IAAI,WAAW,IAAI,GAAG,CAAC;IAC7D,CAAC;CACF;AAVD,sCAUC"}

package/dist/ffi.d.ts

@@ -0,0 +1,34 @@
+export declare function loadSysprims(): SysprimsLib;
+export type SysprimsCallJsonResult = {
+    code: number;
+    json?: string;
+    message?: string;
+};
+export type SysprimsCallU32Result = {
+    code: number;
+    value?: number;
+    message?: string;
+};
+export type SysprimsCallVoidResult = {
+    code: number;
+    message?: string;
+};
+export type SysprimsLib = {
+    sysprimsAbiVersion: () => number;
+    sysprimsProcGet: (pid: number) => SysprimsCallJsonResult;
+    sysprimsProcList: (filterJson: string) => SysprimsCallJsonResult;
+    sysprimsProcListeningPorts: (filterJson: string) => SysprimsCallJsonResult;
+    sysprimsProcWaitPid: (pid: number, timeoutMs: number) => SysprimsCallJsonResult;
+    sysprimsSelfGetpgid: () => SysprimsCallU32Result;
+    sysprimsSelfGetsid: () => SysprimsCallU32Result;
+    sysprimsSignalSend: (pid: number, signal: number) => SysprimsCallVoidResult;
+    sysprimsSignalSendGroup: (pgid: number, signal: number) => SysprimsCallVoidResult;
+    sysprimsTerminate: (pid: number) => SysprimsCallVoidResult;
+    sysprimsForceKill: (pid: number) => SysprimsCallVoidResult;
+    sysprimsTerminateTree: (pid: number, configJson: string) => SysprimsCallJsonResult;
+    sysprimsSpawnInGroup: (configJson: string) => SysprimsCallJsonResult;
+};
+export declare function callJsonReturn(fn: () => SysprimsCallJsonResult): unknown;
+export declare function callU32Out(fn: () => SysprimsCallU32Result): number;
+export declare function callVoid(fn: () => SysprimsCallVoidResult): void;
+//# sourceMappingURL=ffi.d.ts.map

package/dist/ffi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffi.d.ts","sourceRoot":"","sources":["../src/ffi.ts"],"names":[],"mappings":"AASA,wBAAgB,YAAY,IAAI,WAAW,CAQ1C;AAcD,MAAM,MAAM,sBAAsB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACvF,MAAM,MAAM,qBAAqB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AACvF,MAAM,MAAM,sBAAsB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExE,MAAM,MAAM,WAAW,GAAG;IACxB,kBAAkB,EAAE,MAAM,MAAM,CAAC;IAGjC,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,sBAAsB,CAAC;IACzD,gBAAgB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,sBAAsB,CAAC;IACjE,0BAA0B,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,sBAAsB,CAAC;IAC3E,mBAAmB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,sBAAsB,CAAC;IAGhF,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;IACjD,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;IAGhD,kBAAkB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,sBAAsB,CAAC;IAC5E,uBAAuB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,sBAAsB,CAAC;IAClF,iBAAiB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,sBAAsB,CAAC;IAC3D,iBAAiB,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,sBAAsB,CAAC;IAG3D,qBAAqB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,sBAAsB,CAAC;IAGnF,oBAAoB,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,sBAAsB,CAAC;CACtE,CAAC;AAUF,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,sBAAsB,GAAG,OAAO,CAMxE;AAED,wBAAgB,UAAU,CAAC,EAAE,EAAE,MAAM,qBAAqB,GAAG,MAAM,CAMlE;AAED,wBAAgB,QAAQ,CAAC,EAAE,EAAE,MAAM,sBAAsB,GAAG,IAAI,CAK/D"}

package/dist/ffi.js

@@ -0,0 +1,60 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSysprims = loadSysprims;
+exports.callJsonReturn = callJsonReturn;
+exports.callU32Out = callU32Out;
+exports.callVoid = callVoid;
+const errors_1 = require("./errors");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const native_1 = require("./native");
+let cached = null;
+function loadSysprims() {
+    if (cached)
+        return cached;
+    const packageRoot = findPackageRoot(__dirname);
+    const api = (0, native_1.loadNativeBinding)(packageRoot);
+    cached = api;
+    return cached;
+}
+function findPackageRoot(startDir) {
+    let current = startDir;
+    for (let i = 0; i < 8; i++) {
+        const candidate = node_path_1.default.join(current, "package.json");
+        if (node_fs_1.default.existsSync(candidate))
+            return current;
+        const parent = node_path_1.default.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    throw new Error("Could not locate package root (package.json not found)");
+}
+function raiseSysprimsError(code, message) {
+    const codeNameSuffix = ` (code=${code})`;
+    throw new errors_1.SysprimsError(code, message && message.length > 0 ? message : `sysprims error${codeNameSuffix}`);
+}
+function callJsonReturn(fn) {
+    const r = fn();
+    if (r.code !== errors_1.SysprimsErrorCode.Ok) {
+        raiseSysprimsError(r.code, r.message);
+    }
+    return JSON.parse(r.json);
+}
+function callU32Out(fn) {
+    const r = fn();
+    if (r.code !== errors_1.SysprimsErrorCode.Ok) {
+        raiseSysprimsError(r.code, r.message);
+    }
+    return r.value >>> 0;
+}
+function callVoid(fn) {
+    const r = fn();
+    if (r.code !== errors_1.SysprimsErrorCode.Ok) {
+        raiseSysprimsError(r.code, r.message);
+    }
+}
+//# sourceMappingURL=ffi.js.map

package/dist/ffi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ffi.js","sourceRoot":"","sources":["../src/ffi.ts"],"names":[],"mappings":";;;;;AASA,oCAQC;AAoDD,wCAMC;AAED,gCAMC;AAED,4BAKC;AA1FD,qCAA4D;AAE5D,sDAAyB;AACzB,0DAA6B;AAE7B,qCAA6C;AAE7C,IAAI,MAAM,GAAuB,IAAI,CAAC;AAEtC,SAAgB,YAAY;IAC1B,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,MAAM,WAAW,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;IAE/C,MAAM,GAAG,GAAgB,IAAA,0BAAiB,EAAC,WAAW,CAAC,CAAC;IACxD,MAAM,GAAG,GAAG,CAAC;IACb,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,eAAe,CAAC,QAAgB;IACvC,IAAI,OAAO,GAAG,QAAQ,CAAC;IACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,mBAAI,CAAC,IAAI,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;QACrD,IAAI,iBAAE,CAAC,UAAU,CAAC,SAAS,CAAC;YAAE,OAAO,OAAO,CAAC;QAC7C,MAAM,MAAM,GAAG,mBAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,MAAM,KAAK,OAAO;YAAE,MAAM;QAC9B,OAAO,GAAG,MAAM,CAAC;IACnB,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;AAC5E,CAAC;AAgCD,SAAS,kBAAkB,CAAC,IAAY,EAAE,OAAgB;IACxD,MAAM,cAAc,GAAG,UAAU,IAAI,GAAG,CAAC;IACzC,MAAM,IAAI,sBAAa,CACrB,IAAyB,EACzB,OAAO,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,iBAAiB,cAAc,EAAE,CAC5E,CAAC;AACJ,CAAC;AAED,SAAgB,cAAc,CAAC,EAAgC;IAC7D,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC;IACf,IAAI,CAAC,CAAC,IAAI,KAAK,0BAAiB,CAAC,EAAE,EAAE,CAAC;QACpC,kBAAkB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAc,CAAC,CAAC;AACtC,CAAC;AAED,SAAgB,UAAU,CAAC,EAA+B;IACxD,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC;IACf,IAAI,CAAC,CAAC,IAAI,KAAK,0BAAiB,CAAC,EAAE,EAAE,CAAC;QACpC,kBAAkB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;IACD,OAAQ,CAAC,CAAC,KAAgB,KAAK,CAAC,CAAC;AACnC,CAAC;AAED,SAAgB,QAAQ,CAAC,EAAgC;IACvD,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC;IACf,IAAI,CAAC,CAAC,IAAI,KAAK,0BAAiB,CAAC,EAAE,EAAE,CAAC;QACpC,kBAAkB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;IACxC,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+import { SysprimsError, SysprimsErrorCode } from "./errors";
+import type { PortBindingsSnapshot, PortFilter, ProcessFilter, ProcessInfo, ProcessSnapshot, WaitPidResult, TerminateTreeConfig, TerminateTreeResult, SpawnInGroupConfig, SpawnInGroupResult } from "./types";
+export { SysprimsError, SysprimsErrorCode };
+export type { PortBinding, PortBindingsSnapshot, PortFilter, ProcessFilter, ProcessInfo, ProcessSnapshot, ProcessState, Protocol, WaitPidResult, TerminateTreeConfig, TerminateTreeResult, SpawnInGroupConfig, SpawnInGroupResult, } from "./types";
+/**
+ * Get information about a specific process by PID.
+ *
+ * @param pid - Process ID to query
+ * @returns Process information including name, state, CPU, memory usage
+ * @throws {SysprimsError} NotFound if process does not exist
+ * @throws {SysprimsError} PermissionDenied if access is denied
+ */
+export declare function procGet(pid: number): ProcessInfo;
+/**
+ * List running processes with optional filtering.
+ *
+ * Filter fields use snake_case to match FFI/schema conventions:
+ * - `name_contains`: substring match (case-insensitive)
+ * - `name_equals`: exact name match
+ * - `user_equals`: exact username match
+ * - `pid_in`: array of PIDs to include
+ * - `state_in`: array of states to include
+ * - `cpu_above`: minimum CPU percentage (0-100)
+ * - `memory_above_kb`: minimum memory in KB
+ *
+ * @param filter - Optional filter criteria (all fields are AND-ed)
+ * @returns Snapshot of matching processes
+ *
+ * @example
+ * // List all processes
+ * const all = processList();
+ *
+ * @example
+ * // Filter by name substring
+ * const nginx = processList({ name_contains: "nginx" });
+ *
+ * @example
+ * // Filter by multiple criteria
+ * const heavy = processList({ cpu_above: 50, memory_above_kb: 100000 });
+ */
+export declare function processList(filter?: ProcessFilter): ProcessSnapshot;
+/**
+ * List listening network ports with optional filtering.
+ *
+ * Results are best-effort: some platforms may not provide full process attribution,
+ * and elevated privileges may be required for complete visibility. Check the
+ * `warnings` array in the result for any limitations encountered.
+ *
+ * Filter fields use snake_case to match FFI/schema conventions:
+ * - `protocol`: "tcp" or "udp"
+ * - `local_port`: specific port number
+ *
+ * @param filter - Optional filter criteria
+ * @returns Snapshot of listening ports (may be empty if no ports are listening)
+ *
+ * @example
+ * // List all listening ports
+ * const ports = listeningPorts();
+ *
+ * @example
+ * // Filter by protocol
+ * const tcpPorts = listeningPorts({ protocol: "tcp" });
+ *
+ * @example
+ * // Find specific port
+ * const http = listeningPorts({ local_port: 8080 });
+ */
+export declare function listeningPorts(filter?: PortFilter): PortBindingsSnapshot;
+/**
+ * Wait for a PID to exit up to the provided timeout (milliseconds).
+ *
+ * Best-effort behavior:
+ * - Unix: polling strategy (we are not necessarily the parent)
+ * - Windows: process wait APIs when available
+ */
+export declare function waitPID(pid: number, timeoutMs: number): WaitPidResult;
+/**
+ * Get the process group ID of the current process.
+ *
+ * @returns Process group ID (PGID)
+ * @throws {SysprimsError} NotSupported on Windows (POSIX concept)
+ */
+export declare function selfPGID(): number;
+/**
+ * Get the session ID of the current process.
+ *
+ * @returns Session ID (SID)
+ * @throws {SysprimsError} NotSupported on Windows (POSIX concept)
+ */
+export declare function selfSID(): number;
+/**
+ * Send a signal to a process.
+ *
+ * On Unix: sends the specified POSIX signal (e.g., 15=SIGTERM, 9=SIGKILL).
+ * On Windows: only signal 0 (existence check) and termination signals are
+ * meaningful; other signals may return NotSupported.
+ *
+ * @param pid - Target process ID
+ * @param signal - Signal number (Unix semantics)
+ * @throws {SysprimsError} NotFound if process does not exist
+ * @throws {SysprimsError} PermissionDenied if access is denied
+ * @throws {SysprimsError} NotSupported if signal is not supported on this platform
+ *
+ * @example
+ * // Check if process exists (signal 0)
+ * signalSend(1234, 0);
+ *
+ * @example
+ * // Send SIGTERM
+ * signalSend(1234, 15);
+ */
+export declare function signalSend(pid: number, signal: number): void;
+/**
+ * Send a signal to a process group.
+ *
+ * On Unix: sends the signal to all processes in the group.
+ * On Windows: NotSupported (no process group concept).
+ *
+ * @param pgid - Target process group ID
+ * @param signal - Signal number (Unix semantics)
+ * @throws {SysprimsError} NotFound if process group does not exist
+ * @throws {SysprimsError} PermissionDenied if access is denied
+ * @throws {SysprimsError} NotSupported on Windows
+ */
+export declare function signalSendGroup(pgid: number, signal: number): void;
+/**
+ * Terminate a process gracefully.
+ *
+ * On Unix: sends SIGTERM.
+ * On Windows: calls TerminateProcess.
+ *
+ * @param pid - Target process ID
+ * @throws {SysprimsError} NotFound if process does not exist
+ * @throws {SysprimsError} PermissionDenied if access is denied
+ */
+export declare function terminate(pid: number): void;
+/**
+ * Force kill a process immediately.
+ *
+ * On Unix: sends SIGKILL (cannot be caught or ignored).
+ * On Windows: calls TerminateProcess.
+ *
+ * @param pid - Target process ID
+ * @throws {SysprimsError} NotFound if process does not exist
+ * @throws {SysprimsError} PermissionDenied if access is denied
+ */
+export declare function forceKill(pid: number): void;
+/**
+ * Terminate a process with escalation (TERM -> wait -> KILL).
+ *
+ * This is intended for supervisor stop flows.
+ *
+ * Note: this is a PID-only API. On Unix, if `pid` is a process group leader,
+ * sysprims may use group kill for better coverage.
+ */
+export declare function terminateTree(pid: number, config?: TerminateTreeConfig): TerminateTreeResult;
+export declare function spawnInGroup(config: SpawnInGroupConfig): SpawnInGroupResult;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAE5D,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,WAAW,EACX,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EACnB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,CAAC;AAC5C,YAAY,EACV,WAAW,EACX,oBAAoB,EACpB,UAAU,EACV,aAAa,EACb,WAAW,EACX,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,SAAS,CAAC;AAMjB;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAIhD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,eAAe,CAKnE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,oBAAoB,CAKxE;AAMD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,aAAa,CAIrE;AAMD;;;;;GAKG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAGjC;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,IAAI,MAAM,CAGhC;AAMD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAG5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAGlE;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAG3C;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAG3C;AAMD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,mBAAmB,GAAG,mBAAmB,CAiB5F;AAMD,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAS3E"}

package/dist/index.js

@@ -0,0 +1,246 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SysprimsErrorCode = exports.SysprimsError = void 0;
+exports.procGet = procGet;
+exports.processList = processList;
+exports.listeningPorts = listeningPorts;
+exports.waitPID = waitPID;
+exports.selfPGID = selfPGID;
+exports.selfSID = selfSID;
+exports.signalSend = signalSend;
+exports.signalSendGroup = signalSendGroup;
+exports.terminate = terminate;
+exports.forceKill = forceKill;
+exports.terminateTree = terminateTree;
+exports.spawnInGroup = spawnInGroup;
+const errors_1 = require("./errors");
+Object.defineProperty(exports, "SysprimsError", { enumerable: true, get: function () { return errors_1.SysprimsError; } });
+Object.defineProperty(exports, "SysprimsErrorCode", { enumerable: true, get: function () { return errors_1.SysprimsErrorCode; } });
+const ffi_1 = require("./ffi");
+// -----------------------------------------------------------------------------
+// Process Inspection
+// -----------------------------------------------------------------------------
+/**
+ * Get information about a specific process by PID.
+ *
+ * @param pid - Process ID to query
+ * @returns Process information including name, state, CPU, memory usage
+ * @throws {SysprimsError} NotFound if process does not exist
+ * @throws {SysprimsError} PermissionDenied if access is denied
+ */
+function procGet(pid) {
+    const lib = (0, ffi_1.loadSysprims)();
+    const result = (0, ffi_1.callJsonReturn)(() => lib.sysprimsProcGet(pid >>> 0));
+    return result;
+}
+/**
+ * List running processes with optional filtering.
+ *
+ * Filter fields use snake_case to match FFI/schema conventions:
+ * - `name_contains`: substring match (case-insensitive)
+ * - `name_equals`: exact name match
+ * - `user_equals`: exact username match
+ * - `pid_in`: array of PIDs to include
+ * - `state_in`: array of states to include
+ * - `cpu_above`: minimum CPU percentage (0-100)
+ * - `memory_above_kb`: minimum memory in KB
+ *
+ * @param filter - Optional filter criteria (all fields are AND-ed)
+ * @returns Snapshot of matching processes
+ *
+ * @example
+ * // List all processes
+ * const all = processList();
+ *
+ * @example
+ * // Filter by name substring
+ * const nginx = processList({ name_contains: "nginx" });
+ *
+ * @example
+ * // Filter by multiple criteria
+ * const heavy = processList({ cpu_above: 50, memory_above_kb: 100000 });
+ */
+function processList(filter) {
+    const lib = (0, ffi_1.loadSysprims)();
+    const filterJson = filter ? JSON.stringify(filter) : "";
+    const result = (0, ffi_1.callJsonReturn)(() => lib.sysprimsProcList(filterJson));
+    return result;
+}
+/**
+ * List listening network ports with optional filtering.
+ *
+ * Results are best-effort: some platforms may not provide full process attribution,
+ * and elevated privileges may be required for complete visibility. Check the
+ * `warnings` array in the result for any limitations encountered.
+ *
+ * Filter fields use snake_case to match FFI/schema conventions:
+ * - `protocol`: "tcp" or "udp"
+ * - `local_port`: specific port number
+ *
+ * @param filter - Optional filter criteria
+ * @returns Snapshot of listening ports (may be empty if no ports are listening)
+ *
+ * @example
+ * // List all listening ports
+ * const ports = listeningPorts();
+ *
+ * @example
+ * // Filter by protocol
+ * const tcpPorts = listeningPorts({ protocol: "tcp" });
+ *
+ * @example
+ * // Find specific port
+ * const http = listeningPorts({ local_port: 8080 });
+ */
+function listeningPorts(filter) {
+    const lib = (0, ffi_1.loadSysprims)();
+    const filterJson = filter ? JSON.stringify(filter) : "";
+    const result = (0, ffi_1.callJsonReturn)(() => lib.sysprimsProcListeningPorts(filterJson));
+    return result;
+}
+// -----------------------------------------------------------------------------
+// Wait
+// -----------------------------------------------------------------------------
+/**
+ * Wait for a PID to exit up to the provided timeout (milliseconds).
+ *
+ * Best-effort behavior:
+ * - Unix: polling strategy (we are not necessarily the parent)
+ * - Windows: process wait APIs when available
+ */
+function waitPID(pid, timeoutMs) {
+    const lib = (0, ffi_1.loadSysprims)();
+    const result = (0, ffi_1.callJsonReturn)(() => lib.sysprimsProcWaitPid(pid >>> 0, timeoutMs));
+    return result;
+}
+// -----------------------------------------------------------------------------
+// Self Introspection
+// -----------------------------------------------------------------------------
+/**
+ * Get the process group ID of the current process.
+ *
+ * @returns Process group ID (PGID)
+ * @throws {SysprimsError} NotSupported on Windows (POSIX concept)
+ */
+function selfPGID() {
+    const lib = (0, ffi_1.loadSysprims)();
+    return (0, ffi_1.callU32Out)(() => lib.sysprimsSelfGetpgid());
+}
+/**
+ * Get the session ID of the current process.
+ *
+ * @returns Session ID (SID)
+ * @throws {SysprimsError} NotSupported on Windows (POSIX concept)
+ */
+function selfSID() {
+    const lib = (0, ffi_1.loadSysprims)();
+    return (0, ffi_1.callU32Out)(() => lib.sysprimsSelfGetsid());
+}
+// -----------------------------------------------------------------------------
+// Signal Operations
+// -----------------------------------------------------------------------------
+/**
+ * Send a signal to a process.
+ *
+ * On Unix: sends the specified POSIX signal (e.g., 15=SIGTERM, 9=SIGKILL).
+ * On Windows: only signal 0 (existence check) and termination signals are
+ * meaningful; other signals may return NotSupported.
+ *
+ * @param pid - Target process ID
+ * @param signal - Signal number (Unix semantics)
+ * @throws {SysprimsError} NotFound if process does not exist
+ * @throws {SysprimsError} PermissionDenied if access is denied
+ * @throws {SysprimsError} NotSupported if signal is not supported on this platform
+ *
+ * @example
+ * // Check if process exists (signal 0)
+ * signalSend(1234, 0);
+ *
+ * @example
+ * // Send SIGTERM
+ * signalSend(1234, 15);
+ */
+function signalSend(pid, signal) {
+    const lib = (0, ffi_1.loadSysprims)();
+    (0, ffi_1.callVoid)(() => lib.sysprimsSignalSend(pid >>> 0, signal | 0));
+}
+/**
+ * Send a signal to a process group.
+ *
+ * On Unix: sends the signal to all processes in the group.
+ * On Windows: NotSupported (no process group concept).
+ *
+ * @param pgid - Target process group ID
+ * @param signal - Signal number (Unix semantics)
+ * @throws {SysprimsError} NotFound if process group does not exist
+ * @throws {SysprimsError} PermissionDenied if access is denied
+ * @throws {SysprimsError} NotSupported on Windows
+ */
+function signalSendGroup(pgid, signal) {
+    const lib = (0, ffi_1.loadSysprims)();
+    (0, ffi_1.callVoid)(() => lib.sysprimsSignalSendGroup(pgid >>> 0, signal | 0));
+}
+/**
+ * Terminate a process gracefully.
+ *
+ * On Unix: sends SIGTERM.
+ * On Windows: calls TerminateProcess.
+ *
+ * @param pid - Target process ID
+ * @throws {SysprimsError} NotFound if process does not exist
+ * @throws {SysprimsError} PermissionDenied if access is denied
+ */
+function terminate(pid) {
+    const lib = (0, ffi_1.loadSysprims)();
+    (0, ffi_1.callVoid)(() => lib.sysprimsTerminate(pid >>> 0));
+}
+/**
+ * Force kill a process immediately.
+ *
+ * On Unix: sends SIGKILL (cannot be caught or ignored).
+ * On Windows: calls TerminateProcess.
+ *
+ * @param pid - Target process ID
+ * @throws {SysprimsError} NotFound if process does not exist
+ * @throws {SysprimsError} PermissionDenied if access is denied
+ */
+function forceKill(pid) {
+    const lib = (0, ffi_1.loadSysprims)();
+    (0, ffi_1.callVoid)(() => lib.sysprimsForceKill(pid >>> 0));
+}
+// -----------------------------------------------------------------------------
+// Terminate Tree
+// -----------------------------------------------------------------------------
+/**
+ * Terminate a process with escalation (TERM -> wait -> KILL).
+ *
+ * This is intended for supervisor stop flows.
+ *
+ * Note: this is a PID-only API. On Unix, if `pid` is a process group leader,
+ * sysprims may use group kill for better coverage.
+ */
+function terminateTree(pid, config) {
+    const lib = (0, ffi_1.loadSysprims)();
+    if (!config) {
+        return (0, ffi_1.callJsonReturn)(() => lib.sysprimsTerminateTree(pid >>> 0, ""));
+    }
+    const cfg = {
+        schema_id: config.schema_id ||
+            "https://schemas.3leaps.dev/sysprims/process/v1.0.0/terminate-tree-config.schema.json",
+        ...config,
+    };
+    return (0, ffi_1.callJsonReturn)(() => lib.sysprimsTerminateTree(pid >>> 0, JSON.stringify(cfg)));
+}
+// -----------------------------------------------------------------------------
+// Spawn In Group
+// -----------------------------------------------------------------------------
+function spawnInGroup(config) {
+    const lib = (0, ffi_1.loadSysprims)();
+    const cfg = {
+        schema_id: config.schema_id ||
+            "https://schemas.3leaps.dev/sysprims/process/v1.0.0/spawn-in-group-config.schema.json",
+        ...config,
+    };
+    return (0, ffi_1.callJsonReturn)(() => lib.sysprimsSpawnInGroup(JSON.stringify(cfg)));
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/native/index.d.ts

@@ -0,0 +1,32 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+export interface SysprimsCallJsonResult {
+  code: number
+  json?: string
+  message?: string
+}
+export interface SysprimsCallU32Result {
+  code: number
+  value?: number
+  message?: string
+}
+export interface SysprimsCallVoidResult {
+  code: number
+  message?: string
+}
+export declare function sysprimsAbiVersion(): number
+export declare function sysprimsProcGet(pid: number): SysprimsCallJsonResult
+export declare function sysprimsProcList(filterJson: string): SysprimsCallJsonResult
+export declare function sysprimsProcListeningPorts(filterJson: string): SysprimsCallJsonResult
+export declare function sysprimsProcWaitPid(pid: number, timeoutMs: number): SysprimsCallJsonResult
+export declare function sysprimsSelfGetpgid(): SysprimsCallU32Result
+export declare function sysprimsSelfGetsid(): SysprimsCallU32Result
+export declare function sysprimsSignalSend(pid: number, signal: number): SysprimsCallVoidResult
+export declare function sysprimsSignalSendGroup(pgid: number, signal: number): SysprimsCallVoidResult
+export declare function sysprimsTerminate(pid: number): SysprimsCallVoidResult
+export declare function sysprimsForceKill(pid: number): SysprimsCallVoidResult
+export declare function sysprimsTerminateTree(pid: number, configJson: string): SysprimsCallJsonResult
+export declare function sysprimsSpawnInGroup(configJson: string): SysprimsCallJsonResult