@gtkx/utils 1.6.0 → 2.0.0-beta.2

package/dist/process/spawn-with-parent-death-signal.js

@@ -4,12 +4,16 @@ import { Socket } from "node:net";
 import { dirname, extname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { killMarkedProcesses, PROCESS_MARKER } from "./kill-marked-processes.js";
+import { cleanupDirectoryIdentity, killProcessGroup, processGroupIdentity, removeCleanupDirectory, } from "./kill-process-group.js";
 import { resolveExecutable } from "./resolve-executable.js";
 const MODULE_PATH = fileURLToPath(import.meta.url);
 const GUARD_PATH = join(dirname(MODULE_PATH), `process-guard${extname(MODULE_PATH)}`);
 const RUN_ID = randomBytes(8).toString("hex");
 const RUN_PREFIX = `${PROCESS_MARKER}=${RUN_ID}/`;
-const guard = {};
+const guard = { jobs: new Map() };
+const writeGuardCommand = (child, operation, job) => {
+    child.stdin?.write(`${operation}${JSON.stringify(job)}\n`);
+};
 const releaseGuard = (child) => {
     child.unref();
     const { stdin } = child;
@@ -26,23 +30,82 @@ const startGuard = () => {
         stdio: ["pipe", "ignore", "ignore"],
     });
     child.on("error", () => {
-        guard.child = undefined;
+        if (guard.child === child) {
+            guard.child = undefined;
+        }
+    });
+    child.on("exit", () => {
+        if (guard.child === child) {
+            guard.child = undefined;
+        }
+    });
+    child.stdin.on("error", () => {
+        if (guard.child === child) {
+            guard.child = undefined;
+        }
     });
     guard.child = child;
+    for (const job of guard.jobs.values()) {
+        writeGuardCommand(child, "+", job);
+    }
     releaseGuard(child);
 };
+const registerJob = (job) => {
+    guard.jobs.set(job.marker, job);
+    if (guard.child) {
+        writeGuardCommand(guard.child, "+", job);
+    }
+};
+const unregisterJob = (job) => {
+    guard.jobs.delete(job.marker);
+    if (guard.child) {
+        writeGuardCommand(guard.child, "-", job);
+    }
+};
+const rollbackSpawn = ({ child, marker, processGroup, cleanupDirectories = [] }) => {
+    if (processGroup === undefined) {
+        child.kill("SIGKILL");
+    }
+    else {
+        killProcessGroup(processGroup);
+    }
+    killMarkedProcesses(marker);
+    for (const identity of cleanupDirectories) {
+        removeCleanupDirectory(identity);
+    }
+};
 function spawnWithParentDeathSignal(command, args, options = {}) {
     const executable = resolveExecutable(command);
     const setpriv = resolveExecutable("setpriv");
     const jobValue = `${RUN_ID}/${randomBytes(4).toString("hex")}`;
+    const marker = `${PROCESS_MARKER}=${jobValue}`;
     startGuard();
     const child = spawn(setpriv, ["--pdeathsig", "SIGKILL", executable, ...args], {
         detached: true,
         stdio: options.stdio ?? "ignore",
         env: { ...(options.env ?? process.env), [PROCESS_MARKER]: jobValue },
     });
+    const processGroupId = child.pid;
+    const group = processGroupId === undefined ? undefined : processGroupIdentity(processGroupId);
+    if (group === undefined) {
+        rollbackSpawn({ child, marker });
+        throw new Error(`Failed to identify process group for ${command}`);
+    }
+    const cleanupDirectories = (options.cleanupDirectories ?? []).map((path) => cleanupDirectoryIdentity(path));
+    if (cleanupDirectories.includes(undefined)) {
+        const captured = cleanupDirectories.filter((identity) => identity !== undefined);
+        rollbackSpawn({ child, marker, processGroup: group, cleanupDirectories: captured });
+        throw new Error(`Failed to identify a cleanup directory for ${command}`);
+    }
+    const job = {
+        marker,
+        processGroup: group,
+        cleanupDirectories: cleanupDirectories.filter((identity) => identity !== undefined),
+    };
+    registerJob(job);
     child.on("exit", () => {
-        killMarkedProcesses(`${PROCESS_MARKER}=${jobValue}`);
+        killMarkedProcesses(job.marker);
+        unregisterJob(job);
     });
     return child;
 }

package/dist/process/spawn-with-parent-death-signal.js.map

@@ -1 +1 @@
-{"version":3,"file":"spawn-with-parent-death-signal.js","sourceRoot":"","sources":["../../src/process/spawn-with-parent-death-signal.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ChildProcess, spawn, type StdioOptions } from \"node:child_process\";\nimport { randomBytes } from \"node:crypto\";\nimport { Socket } from \"node:net\";\nimport { dirname, extname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { killMarkedProcesses, PROCESS_MARKER } from \"./kill-marked-processes.ts\";\nimport { resolveExecutable } from \"./resolve-executable.ts\";\n\ntype ParentDeathSpawnOptions = {\n    stdio?: StdioOptions;\n    env?: NodeJS.ProcessEnv;\n};\n\ntype GuardState = {\n    child?: ChildProcess | undefined;\n};\n\nconst MODULE_PATH = fileURLToPath(import.meta.url);\nconst GUARD_PATH = join(dirname(MODULE_PATH), `process-guard${extname(MODULE_PATH)}`);\nconst RUN_ID = randomBytes(8).toString(\"hex\");\nconst RUN_PREFIX = `${PROCESS_MARKER}=${RUN_ID}/`;\nconst guard: GuardState = {};\n\nconst releaseGuard = (child: ChildProcess): void => {\n    child.unref();\n    const { stdin } = child;\n\n    if (stdin instanceof Socket) {\n        stdin.unref();\n    }\n};\n\nconst startGuard = (): void => {\n    if (guard.child) {\n        return;\n    }\n\n    const child = spawn(process.execPath, [GUARD_PATH, RUN_PREFIX], {\n        detached: true,\n        stdio: [\"pipe\", \"ignore\", \"ignore\"],\n    });\n\n    child.on(\"error\", () => {\n        guard.child = undefined;\n    });\n\n    guard.child = child;\n    releaseGuard(child);\n};\n\nfunction spawnWithParentDeathSignal(\n    command: string,\n    args: string[],\n    options: ParentDeathSpawnOptions = {},\n): ChildProcess {\n    const executable = resolveExecutable(command);\n    const setpriv = resolveExecutable(\"setpriv\");\n    const jobValue = `${RUN_ID}/${randomBytes(4).toString(\"hex\")}`;\n    startGuard();\n\n    const child = spawn(setpriv, [\"--pdeathsig\", \"SIGKILL\", executable, ...args], {\n        detached: true,\n        stdio: options.stdio ?? \"ignore\",\n        env: { ...(options.env ?? process.env), [PROCESS_MARKER]: jobValue },\n    });\n\n    child.on(\"exit\", () => {\n        killMarkedProcesses(`${PROCESS_MARKER}=${jobValue}`);\n    });\n\n    return child;\n}\n\nexport { spawnWithParentDeathSignal };\n"]}
+{"version":3,"file":"spawn-with-parent-death-signal.js","sourceRoot":"","sources":["../../src/process/spawn-with-parent-death-signal.ts"],"names":[],"mappings":"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","sourcesContent":["import { type ChildProcess, spawn, type StdioOptions } from \"node:child_process\";\nimport { randomBytes } from \"node:crypto\";\nimport { Socket } from \"node:net\";\nimport { dirname, extname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { killMarkedProcesses, PROCESS_MARKER } from \"./kill-marked-processes.ts\";\nimport {\n    type CleanupDirectoryIdentity,\n    cleanupDirectoryIdentity,\n    killProcessGroup,\n    type ProcessGroupIdentity,\n    processGroupIdentity,\n    removeCleanupDirectory,\n} from \"./kill-process-group.ts\";\nimport { resolveExecutable } from \"./resolve-executable.ts\";\n\ntype ParentDeathSpawnOptions = {\n    stdio?: StdioOptions;\n    env?: NodeJS.ProcessEnv;\n    cleanupDirectories?: string[];\n};\n\ntype GuardJob = {\n    marker: string;\n    processGroup: ProcessGroupIdentity;\n    cleanupDirectories: CleanupDirectoryIdentity[];\n};\n\ntype GuardState = {\n    child?: ChildProcess | undefined;\n    jobs: Map<string, GuardJob>;\n};\n\ntype SpawnRollback = {\n    child: ChildProcess;\n    marker: string;\n    processGroup?: ProcessGroupIdentity | undefined;\n    cleanupDirectories?: CleanupDirectoryIdentity[] | undefined;\n};\n\nconst MODULE_PATH = fileURLToPath(import.meta.url);\nconst GUARD_PATH = join(dirname(MODULE_PATH), `process-guard${extname(MODULE_PATH)}`);\nconst RUN_ID = randomBytes(8).toString(\"hex\");\nconst RUN_PREFIX = `${PROCESS_MARKER}=${RUN_ID}/`;\nconst guard: GuardState = { jobs: new Map() };\n\nconst writeGuardCommand = (child: ChildProcess, operation: \"+\" | \"-\", job: GuardJob): void => {\n    child.stdin?.write(`${operation}${JSON.stringify(job)}\\n`);\n};\n\nconst releaseGuard = (child: ChildProcess): void => {\n    child.unref();\n    const { stdin } = child;\n\n    if (stdin instanceof Socket) {\n        stdin.unref();\n    }\n};\n\nconst startGuard = (): void => {\n    if (guard.child) {\n        return;\n    }\n\n    const child = spawn(process.execPath, [GUARD_PATH, RUN_PREFIX], {\n        detached: true,\n        stdio: [\"pipe\", \"ignore\", \"ignore\"],\n    });\n\n    child.on(\"error\", () => {\n        if (guard.child === child) {\n            guard.child = undefined;\n        }\n    });\n\n    child.on(\"exit\", () => {\n        if (guard.child === child) {\n            guard.child = undefined;\n        }\n    });\n\n    child.stdin.on(\"error\", () => {\n        if (guard.child === child) {\n            guard.child = undefined;\n        }\n    });\n\n    guard.child = child;\n\n    for (const job of guard.jobs.values()) {\n        writeGuardCommand(child, \"+\", job);\n    }\n\n    releaseGuard(child);\n};\n\nconst registerJob = (job: GuardJob): void => {\n    guard.jobs.set(job.marker, job);\n\n    if (guard.child) {\n        writeGuardCommand(guard.child, \"+\", job);\n    }\n};\n\nconst unregisterJob = (job: GuardJob): void => {\n    guard.jobs.delete(job.marker);\n\n    if (guard.child) {\n        writeGuardCommand(guard.child, \"-\", job);\n    }\n};\n\nconst rollbackSpawn = ({ child, marker, processGroup, cleanupDirectories = [] }: SpawnRollback): void => {\n    if (processGroup === undefined) {\n        child.kill(\"SIGKILL\");\n    } else {\n        killProcessGroup(processGroup);\n    }\n\n    killMarkedProcesses(marker);\n\n    for (const identity of cleanupDirectories) {\n        removeCleanupDirectory(identity);\n    }\n};\n\nfunction spawnWithParentDeathSignal(\n    command: string,\n    args: string[],\n    options: ParentDeathSpawnOptions = {},\n): ChildProcess {\n    const executable = resolveExecutable(command);\n    const setpriv = resolveExecutable(\"setpriv\");\n    const jobValue = `${RUN_ID}/${randomBytes(4).toString(\"hex\")}`;\n    const marker = `${PROCESS_MARKER}=${jobValue}`;\n    startGuard();\n\n    const child = spawn(setpriv, [\"--pdeathsig\", \"SIGKILL\", executable, ...args], {\n        detached: true,\n        stdio: options.stdio ?? \"ignore\",\n        env: { ...(options.env ?? process.env), [PROCESS_MARKER]: jobValue },\n    });\n\n    const processGroupId = child.pid;\n    const group = processGroupId === undefined ? undefined : processGroupIdentity(processGroupId);\n\n    if (group === undefined) {\n        rollbackSpawn({ child, marker });\n        throw new Error(`Failed to identify process group for ${command}`);\n    }\n\n    const cleanupDirectories = (options.cleanupDirectories ?? []).map((path) => cleanupDirectoryIdentity(path));\n\n    if (cleanupDirectories.includes(undefined)) {\n        const captured = cleanupDirectories.filter(\n            (identity): identity is CleanupDirectoryIdentity => identity !== undefined,\n        );\n        rollbackSpawn({ child, marker, processGroup: group, cleanupDirectories: captured });\n        throw new Error(`Failed to identify a cleanup directory for ${command}`);\n    }\n\n    const job: GuardJob = {\n        marker,\n        processGroup: group,\n        cleanupDirectories: cleanupDirectories.filter((identity) => identity !== undefined),\n    };\n    registerJob(job);\n\n    child.on(\"exit\", () => {\n        killMarkedProcesses(job.marker);\n        unregisterJob(job);\n    });\n\n    return child;\n}\n\nexport { spawnWithParentDeathSignal };\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtkx/utils",
-  "version": "1.6.0",
+  "version": "2.0.0-beta.2",
   "description": "Shared utilities for the GTK toolchain: logging, errors, strings.",
   "keywords": [
     "gtkx",
@@ -26,6 +26,8 @@
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": null,
       "default": "./dist/index.js"
     }
   },
@@ -45,10 +47,14 @@
     }
   },
   "dependencies": {
-    "picocolors": "^1.1.1"
+    "picocolors": "^1.1.1",
+    "which": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/which": "^3.0.4"
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=26.7.0"
   },
   "scripts": {
     "release": "tsx ../../scripts/release-package.ts"

package/src/index.ts

@@ -2,8 +2,8 @@ export * from "./array/index.ts";
 export * from "./class/index.ts";
 export * from "./error/index.ts";
 export * from "./log/index.ts";
-export * from "./map/index.ts";
 export * from "./object/index.ts";
+export * from "./path.ts";
 export * from "./predicate/index.ts";
 export * from "./process/index.ts";
 export * from "./set/index.ts";

package/src/path.ts

@@ -0,0 +1,17 @@
+import { isAbsolute, relative, sep } from "node:path";
+
+const isOutsidePath = (path: string): boolean =>
+    path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path);
+
+const isPathInside = (parent: string, candidate: string): boolean => {
+    const path = relative(parent, candidate);
+
+    return path !== "" && !isOutsidePath(path);
+};
+
+const isPathWithin = (parent: string, candidate: string): boolean =>
+    !isOutsidePath(relative(parent, candidate));
+
+const toPosixPath = (path: string): string => path.replaceAll("\\", "/");
+
+export { isPathInside, isPathWithin, toPosixPath };

package/src/process/index.ts

@@ -1,4 +1,9 @@
 export { exitCodeForSignal } from "./exit-code-for-signal.ts";
 export { installGracefulShutdown } from "./install-graceful-shutdown.ts";
+export {
+    killProcessGroup,
+    type ProcessGroupIdentity,
+    processGroupIdentity,
+} from "./kill-process-group.ts";
 export { resolveExecutable, tryResolveExecutable } from "./resolve-executable.ts";
 export { spawnWithParentDeathSignal } from "./spawn-with-parent-death-signal.ts";

package/src/process/kill-marked-processes.ts

@@ -1,44 +1,93 @@
 import { readdirSync, readFileSync } from "node:fs";
 
+type ProcessIdentity = {
+    pid: number;
+    sessionId: number;
+    startTime: string;
+};
+
+type MarkerMatcher = (assignment: string) => boolean;
+
 const PROCESS_MARKER = "GTKX_PROCESS_GUARD";
 const MAX_KILL_PASSES = 8;
+const JOB_ID_PATTERN = /^[0-9a-f]{8}$/;
 
-const isMarked = (pid: number, prefix: string): boolean => {
+const processIdentity = (pid: number): ProcessIdentity | undefined => {
+    try {
+        const stat = readFileSync(`/proc/${String(pid)}/stat`, "utf8");
+        const fields = stat.slice(stat.lastIndexOf(") ") + 2).split(" ");
+        const sessionId = Number(fields[3]);
+        const startTime = fields[19];
+
+        return startTime !== undefined && Number.isSafeInteger(sessionId)
+            ? { pid, sessionId, startTime }
+            : undefined;
+    } catch {
+        return undefined;
+    }
+};
+
+const isMarked = (pid: number, isMatch: MarkerMatcher): boolean => {
     try {
         return readFileSync(`/proc/${String(pid)}/environ`, "utf8")
             .split("\0")
-            .some((assignment) => assignment.startsWith(prefix));
+            .some((assignment) => isMatch(assignment));
     } catch {
         return false;
     }
 };
 
-const markedPids = (prefix: string): number[] =>
+const markedProcesses = (isMatch: MarkerMatcher): ProcessIdentity[] =>
     readdirSync("/proc")
         .map(Number)
         .filter((pid) => Number.isSafeInteger(pid) && pid > 1 && pid !== process.pid)
-        .filter((pid) => isMarked(pid, prefix));
+        .filter((pid) => isMarked(pid, isMatch))
+        .map((pid) => processIdentity(pid))
+        .filter((identity): identity is ProcessIdentity => identity !== undefined);
+
+const killProcess = (identity: ProcessIdentity, isMatch: MarkerMatcher): void => {
+    if (!isMarked(identity.pid, isMatch)) {
+        return;
+    }
+
+    const current = processIdentity(identity.pid);
+
+    if (
+        current?.sessionId !== identity.sessionId ||
+        current.startTime !== identity.startTime
+    ) {
+        return;
+    }
 
-const killPid = (pid: number): void => {
     try {
-        process.kill(pid, "SIGKILL");
+        process.kill(identity.pid, "SIGKILL");
     } catch {
         return;
     }
 };
 
-function killMarkedProcesses(prefix: string): void {
+const killMatchingProcesses = (isMatch: MarkerMatcher): void => {
     for (let pass = 0; pass < MAX_KILL_PASSES; pass += 1) {
-        const pids = markedPids(prefix);
+        const processes = markedProcesses(isMatch);
 
-        if (pids.length === 0) {
+        if (processes.length === 0) {
             return;
         }
 
-        for (const pid of pids) {
-            killPid(pid);
+        for (const identity of processes) {
+            killProcess(identity, isMatch);
         }
     }
-}
+};
+
+const killMarkedProcesses = (marker: string): void => {
+    killMatchingProcesses((assignment) => assignment === marker);
+};
+
+const killMarkedProcessRun = (runPrefix: string): void => {
+    killMatchingProcesses((assignment) =>
+        assignment.startsWith(runPrefix) && JOB_ID_PATTERN.test(assignment.slice(runPrefix.length)),
+    );
+};
 
-export { PROCESS_MARKER, killMarkedProcesses };
+export { PROCESS_MARKER, killMarkedProcessRun, killMarkedProcesses };

package/src/process/kill-process-group.ts

@@ -0,0 +1,104 @@
+import { lstatSync, readFileSync, rmSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+
+type ProcessGroupIdentity = {
+    processGroupId: number;
+    leaderStartTime: string;
+};
+
+type CleanupDirectoryIdentity = {
+    path: string;
+    device: string;
+    inode: string;
+    userId: string;
+};
+
+const isProcessGroupId = (value: number): boolean => Number.isSafeInteger(value) && value > 1;
+
+const processGroupIdentity = (processGroupId: number): ProcessGroupIdentity | undefined => {
+    if (!isProcessGroupId(processGroupId)) {
+        return undefined;
+    }
+
+    try {
+        const stat = readFileSync(`/proc/${String(processGroupId)}/stat`, "utf8");
+        const fields = stat.slice(stat.lastIndexOf(") ") + 2).split(" ");
+        const actualProcessGroupId = Number(fields[2]);
+        const sessionId = Number(fields[3]);
+        const leaderStartTime = fields[19];
+
+        return actualProcessGroupId === processGroupId && sessionId === processGroupId && leaderStartTime !== undefined
+            ? { processGroupId, leaderStartTime }
+            : undefined;
+    } catch {
+        return undefined;
+    }
+};
+
+const isCurrentProcessGroup = (identity: ProcessGroupIdentity): boolean => {
+    const current = processGroupIdentity(identity.processGroupId);
+
+    return current?.leaderStartTime === identity.leaderStartTime;
+};
+
+const killProcessGroup = (identity: ProcessGroupIdentity): void => {
+    if (!isCurrentProcessGroup(identity)) {
+        return;
+    }
+
+    try {
+        process.kill(-identity.processGroupId, "SIGKILL");
+    } catch {
+        return;
+    }
+};
+
+const cleanupDirectoryIdentity = (path: string): CleanupDirectoryIdentity | undefined => {
+    const absolutePath = resolve(path);
+
+    if (absolutePath === "/" || !isAbsolute(path)) {
+        return undefined;
+    }
+
+    try {
+        const entry = lstatSync(absolutePath, { bigint: true });
+
+        return entry.isDirectory()
+            ? {
+                    path: absolutePath,
+                    device: entry.dev.toString(),
+                    inode: entry.ino.toString(),
+                    userId: entry.uid.toString(),
+                }
+            : undefined;
+    } catch {
+        return undefined;
+    }
+};
+
+const removeCleanupDirectory = (identity: CleanupDirectoryIdentity): void => {
+    const current = cleanupDirectoryIdentity(identity.path);
+
+    if (
+        current?.device !== identity.device ||
+        current.inode !== identity.inode ||
+        current.userId !== identity.userId
+    ) {
+        return;
+    }
+
+    try {
+        rmSync(identity.path, { recursive: true, force: true });
+    } catch {
+        return;
+    }
+};
+
+export {
+    type CleanupDirectoryIdentity,
+    cleanupDirectoryIdentity,
+    killProcessGroup,
+    type ProcessGroupIdentity,
+    processGroupIdentity,
+    removeCleanupDirectory,
+};

package/src/process/process-guard.ts

@@ -1,17 +1,121 @@
-import { killMarkedProcesses } from "./kill-marked-processes.ts";
+import { killMarkedProcesses, killMarkedProcessRun } from "./kill-marked-processes.ts";
+import {
+    type CleanupDirectoryIdentity,
+    killProcessGroup,
+    type ProcessGroupIdentity,
+    removeCleanupDirectory,
+} from "./kill-process-group.ts";
 
 const GUARD_PREFIX = process.argv[2] ?? "";
 const WATCHED_SIGNALS = ["SIGTERM", "SIGINT", "SIGHUP"] as const satisfies NodeJS.Signals[];
+type GuardJob = {
+    marker: string;
+    processGroup: ProcessGroupIdentity;
+    cleanupDirectories: CleanupDirectoryIdentity[];
+};
+
+const state: { bufferedCommands: string; isSweeping: boolean; jobs: Map<string, GuardJob> } = {
+    bufferedCommands: "",
+    isSweeping: false,
+    jobs: new Map(),
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+    typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isProcessGroupIdentity = (value: unknown): value is ProcessGroupIdentity =>
+    isRecord(value) &&
+    typeof value.processGroupId === "number" &&
+    Number.isSafeInteger(value.processGroupId) &&
+    value.processGroupId > 1 &&
+    typeof value.leaderStartTime === "string" &&
+    /^\d+$/.test(value.leaderStartTime);
+
+const isCleanupDirectoryIdentity = (value: unknown): value is CleanupDirectoryIdentity =>
+    isRecord(value) &&
+    typeof value.path === "string" &&
+    typeof value.device === "string" &&
+    typeof value.inode === "string" &&
+    typeof value.userId === "string";
+
+const isGuardJob = (value: unknown): value is GuardJob =>
+    isRecord(value) &&
+    typeof value.marker === "string" &&
+    isProcessGroupIdentity(value.processGroup) &&
+    Array.isArray(value.cleanupDirectories) &&
+    value.cleanupDirectories.every(isCleanupDirectoryIdentity);
+
+const applyCommand = (command: string): void => {
+    const operation = command[0];
+    let value: unknown;
+
+    try {
+        value = JSON.parse(command.slice(1));
+    } catch {
+        return;
+    }
+
+    if (!isGuardJob(value)) {
+        return;
+    }
+
+    if (operation === "+") {
+        state.jobs.set(value.marker, value);
+    } else if (operation === "-") {
+        state.jobs.delete(value.marker);
+    }
+};
+
+const receiveCommands = (chunk: Buffer | string): void => {
+    state.bufferedCommands += chunk.toString();
+    const commands = state.bufferedCommands.split("\n");
+    state.bufferedCommands = commands.pop() ?? "";
+
+    for (const command of commands) {
+        applyCommand(command);
+    }
+};
+
+const killJobs = (): void => {
+    for (const job of state.jobs.values()) {
+        killProcessGroup(job.processGroup);
+        killMarkedProcesses(job.marker);
+    }
+};
+
+const removeCleanupDirectories = (): void => {
+    const cleanupDirectories: Map<string, CleanupDirectoryIdentity> = new Map();
+
+    for (const job of state.jobs.values()) {
+        for (const identity of job.cleanupDirectories) {
+            cleanupDirectories.set(`${identity.device}:${identity.inode}`, identity);
+        }
+    }
+
+    for (const identity of cleanupDirectories.values()) {
+        removeCleanupDirectory(identity);
+    }
+};
 
 const sweep = (): void => {
+    if (state.isSweeping) {
+        return;
+    }
+
+    state.isSweeping = true;
+    applyCommand(state.bufferedCommands);
+    killJobs();
+
     if (GUARD_PREFIX.length > 0) {
-        killMarkedProcesses(GUARD_PREFIX);
+        killMarkedProcessRun(GUARD_PREFIX);
     }
 
+    removeCleanupDirectories();
     process.exit(0);
 };
 
 process.stdin.resume();
+process.stdin.on("data", receiveCommands);
 process.stdin.on("end", sweep);
 process.stdin.on("error", sweep);
 

package/src/process/resolve-executable.ts

@@ -1,50 +1,8 @@
-import { accessSync, constants, statSync } from "node:fs";
-import { delimiter, isAbsolute, join, resolve } from "node:path";
+import which from "which";
 
-const isExecutable = (path: string): boolean => {
-    try {
-        accessSync(path, constants.X_OK);
+const tryResolveExecutable = (command: string): string | undefined =>
+    which.sync(command, { nothrow: true }) ?? undefined;
 
-        return statSync(path).isFile();
-    } catch {
-        return false;
-    }
-};
-
-const findOnPath = (command: string): string | undefined => {
-    const searchPaths = (process.env.PATH ?? "").split(delimiter).filter((entry) => entry.length > 0);
-
-    for (const directory of searchPaths) {
-        const candidate = join(directory, command);
-
-        if (isExecutable(candidate)) {
-            return candidate;
-        }
-    }
-
-    return undefined;
-};
-
-function tryResolveExecutable(command: string): string | undefined {
-    if (isAbsolute(command)) {
-        return command;
-    }
-
-    if (command.includes("/")) {
-        return resolve(command);
-    }
-
-    return findOnPath(command);
-}
-
-function resolveExecutable(command: string): string {
-    const found = tryResolveExecutable(command);
-
-    if (found === undefined) {
-        throw new Error(`Cannot find the "${command}" executable on PATH`);
-    }
-
-    return found;
-}
+const resolveExecutable = (command: string): string => which.sync(command);
 
 export { resolveExecutable, tryResolveExecutable };