@gajae-code/utils 0.11.0 → 0.11.2

package/dist/types/dirs.d.ts

@@ -36,6 +36,8 @@ export declare function formatBunRuntimeError(opts: {
 }): string;
 export declare function resolveEquivalentPath(inputPath: string): string;
 export declare function normalizePathForComparison(inputPath: string, platform?: NodeJS.Platform): string;
+/** Return whether a relative path crosses above its root or is unexpectedly absolute. */
+export declare function relativePathEscapesRoot(relative: string): boolean;
 export declare function pathIsWithin(root: string, candidate: string): boolean;
 export declare function relativePathWithinRoot(root: string, candidate: string): string | null;
 /** Get the project directory. */

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.11.0",
+	"version": "0.11.2",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.11.0",
+		"@gajae-code/natives": "0.11.2",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/dirs.ts

@@ -114,11 +114,16 @@ export function normalizePathForComparison(inputPath: string, platform: NodeJS.P
 	return platform === "win32" ? resolvedPath.toLowerCase() : resolvedPath;
 }
 
+/** Return whether a relative path crosses above its root or is unexpectedly absolute. */
+export function relativePathEscapesRoot(relative: string): boolean {
+	return relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative);
+}
+
 export function pathIsWithin(root: string, candidate: string): boolean {
 	const normalizedRoot = normalizePathForComparison(root);
 	const normalizedCandidate = normalizePathForComparison(candidate);
 	const relative = path.relative(normalizedRoot, normalizedCandidate);
-	return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+	return !relativePathEscapesRoot(relative);
 }
 
 export function relativePathWithinRoot(root: string, candidate: string): string | null {

package/src/postmortem.ts

@@ -55,7 +55,11 @@ function runCleanup(reason: Reason, options: CleanupOptions = {}): Promise<void>
 			cleanupStage = "running";
 			break;
 		case "running":
-			if (reason !== Reason.EXIT && !shouldSuppressCleanupLogging(quiet)) {
+			// Exit-bound waiters (signals, fatals, quit) legitimately join the
+			// in-flight cleanup via `cleanupPromise`; only a genuine manual
+			// recursion (a cleanup callback calling cleanup()) is a bug worth a
+			// diagnostic.
+			if (reason === Reason.MANUAL && !shouldSuppressCleanupLogging(quiet)) {
 				logger.error("Cleanup invoked recursively", { stack: new Error().stack });
 			}
 			return Promise.resolve();
@@ -90,9 +94,65 @@ function runCleanup(reason: Reason, options: CleanupOptions = {}): Promise<void>
 	return promise;
 }
 
-async function runCleanupAndWait(reason: Reason, options: CleanupOptions = {}): Promise<void> {
+/**
+ * Finite cleanup-liveness contract for every exit-bound wait.
+ *
+ * Governed waits: signal handlers (SIGINT/SIGTERM/SIGHUP), fatal handlers
+ * (uncaught exception / unhandled rejection), the quiet stdout-EPIPE exit, and
+ * `quit()`. Each waits at most `resolveCleanupDeadlineMs()` for the shared
+ * in-flight cleanup before exiting with its own unchanged exit code (130/143/
+ * 129, 1 for fatals, BROKEN_PIPE_EXIT_CODE, or quit's `code`).
+ *
+ * Ungoverned: `cleanup()` (Reason.MANUAL without exit) is caller-owned and
+ * unbounded, and Reason.EXIT stays fire-and-forget (exit is imminent).
+ *
+ * On expiry the stage is forced to "complete" so late re-entries no-op, a
+ * single diagnostic goes to stderr and the error log (suppressed during quiet
+ * broken-pipe shutdown), and late callback settlement is ignored — rejections
+ * were already routed through Promise.allSettled, so none can become unhandled.
+ *
+ * The deadline defaults to 5000 ms and can be overridden with
+ * `GJC_CLEANUP_DEADLINE_MS` (finite values >= 0; anything else falls back to
+ * the default).
+ */
+const DEFAULT_CLEANUP_DEADLINE_MS = 5_000;
+
+function resolveCleanupDeadlineMs(): number {
+	const raw = process.env.GJC_CLEANUP_DEADLINE_MS;
+	if (raw === undefined || raw.trim() === "") return DEFAULT_CLEANUP_DEADLINE_MS;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed < 0) return DEFAULT_CLEANUP_DEADLINE_MS;
+	return parsed;
+}
+
+async function awaitCleanupWithDeadline(reason: Reason, options: CleanupOptions = {}): Promise<void> {
+	const pending = cleanupPromise;
+	if (!pending || cleanupStage === "complete") return;
+	const deadlineMs = resolveCleanupDeadlineMs();
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const timedOut = await Promise.race([
+		pending.then(() => false),
+		new Promise<boolean>(resolve => {
+			// Deliberately referenced: the timer is also the liveness floor that
+			// keeps the process alive until the bounded wait settles, so an
+			// otherwise-empty event loop cannot exit 0 underneath a governed wait.
+			timer = setTimeout(() => resolve(true), deadlineMs);
+		}),
+	]);
+	if (timer) clearTimeout(timer);
+	if (!timedOut) return;
+	// Force the terminal stage so late settlement and re-entries are no-ops.
+	cleanupStage = "complete";
+	if (!shouldSuppressCleanupLogging(options.quiet === true)) {
+		const diagnostic = `[postmortem] cleanup deadline (${deadlineMs}ms) expired for ${reason}; exiting without waiting for remaining callbacks.\n`;
+		safeStderrWrite(diagnostic);
+		logger.error("Cleanup deadline expired", { reason, deadlineMs });
+	}
+}
+
+async function runCleanupBounded(reason: Reason, options: CleanupOptions = {}): Promise<void> {
 	void runCleanup(reason, options);
-	await (cleanupPromise ?? Promise.resolve());
+	await awaitCleanupWithDeadline(reason, options);
 }
 
 function installProcessStdoutWriteClassifier(): void {
@@ -150,7 +210,7 @@ async function exitQuietlyForAttributableStdoutEpipe(reason: Reason): Promise<vo
 	quietShutdownStarted = true;
 	// Set the observable status before cleanup can await or trigger another error.
 	process.exitCode = BROKEN_PIPE_EXIT_CODE;
-	await runCleanupAndWait(reason, { quiet: true });
+	await runCleanupBounded(reason, { quiet: true });
 	// An ordinary fatal that arrived during quiet cleanup takes precedence.
 	if (process.exitCode === BROKEN_PIPE_EXIT_CODE) process.exit(BROKEN_PIPE_EXIT_CODE);
 }
@@ -173,7 +233,7 @@ async function handleFatalError(label: string, reason: unknown, cleanupReason: R
 			stack: err.stack,
 		});
 	}
-	await runCleanupAndWait(cleanupReason);
+	await runCleanupBounded(cleanupReason);
 	process.exit(1);
 }
 
@@ -181,7 +241,7 @@ if (isMainThread) {
 	installProcessStdoutWriteClassifier();
 	process
 		.on("SIGINT", async () => {
-			await runCleanupAndWait(Reason.SIGINT);
+			await runCleanupBounded(Reason.SIGINT);
 			process.exit(130); // 128 + SIGINT (2)
 		})
 		.on("SIGUSR1", () => {
@@ -201,11 +261,11 @@ if (isMainThread) {
 			void runCleanup(Reason.EXIT); // fire and forget (exit imminent)
 		})
 		.on("SIGTERM", async () => {
-			await runCleanupAndWait(Reason.SIGTERM);
+			await runCleanupBounded(Reason.SIGTERM);
 			process.exit(143); // 128 + SIGTERM (15)
 		})
 		.on("SIGHUP", async () => {
-			await runCleanupAndWait(Reason.SIGHUP);
+			await runCleanupBounded(Reason.SIGHUP);
 			process.exit(129); // 128 + SIGHUP (1)
 		});
 } else {
@@ -296,7 +356,7 @@ export async function quit(code: number = 0): Promise<void> {
 	}
 
 	const exitAfterCleanup = async (): Promise<void> => {
-		await completion;
+		await awaitCleanupWithDeadline(Reason.MANUAL);
 		if (process.stdout.writableLength > 0) {
 			const { promise, resolve } = Promise.withResolvers<void>();
 			process.stdout.once("drain", resolve);