@oh-my-pi/pi-utils 18.3.1 → 18.3.3

package/dist/types/postmortem.d.ts

@@ -119,6 +119,25 @@ export declare function registerWorkerIpcFaultHandler(handler: (err: Error) => v
  * when the last registrant unregisters.
  */
 export declare function registerStdioDisconnectHandling(): () => void;
+/**
+ * Fail a process entry whose event loop drains while `work` is still pending.
+ *
+ * The CLI starts from a floating `runCli()` call because top-level await breaks
+ * `--bytecode` builds. When a one-shot command awaits a promise that never
+ * settles and holds no live handle, the loop drains and Bun exits 0 without
+ * output: an unfinished command reported as success. `beforeExit` fires in
+ * exactly that state; explicit exits (`process.exit`, {@link quit},
+ * {@link exitProcess}, the signal handlers) never emit it.
+ *
+ * The report runs once and only sets `process.exitCode`, so later `beforeExit`
+ * listeners (LSP shutdown) still run before the process exits 1. It starts no
+ * work of its own beyond the log write; `once` keeps the second `beforeExit`
+ * that any drained follow-up work triggers from reporting again.
+ *
+ * `describe` names what was running (e.g. the resolved subcommand) at report
+ * time; it must return only a command name, never user arguments.
+ */
+export declare function reportUnsettledEntry(work: Promise<unknown>, describe?: () => string | undefined): void;
 /**
  * Mark an error as expected cleanup fallout so the global fatal handlers
  * downgrade it to a log line instead of tearing down the process. Use for

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-utils",
-	"version": "18.3.1",
+	"version": "18.3.3",
 	"description": "Shared utilities for pi packages",
 	"keywords": [
 		"cli",
@@ -57,7 +57,7 @@
 		"fmt": "oxfmt --no-error-on-unmatched-pattern 'src/**/*.{ts,tsx}' '{test,bench,examples,scripts}/**/*.ts' '*.ts'"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "18.3.1"
+		"@oh-my-pi/pi-natives": "18.3.3"
 	},
 	"devDependencies": {
 		"@types/bun": "^1.3.14"

package/src/postmortem.ts

@@ -7,6 +7,7 @@
  */
 
 import * as fs from "node:fs";
+import { APP_NAME } from "./dirs";
 import * as logger from "./logger";
 import { restoreTerminalStderr } from "./stderr-guard";
 
@@ -368,6 +369,44 @@ export function registerStdioDisconnectHandling(): () => void {
 	};
 }
 
+/**
+ * Fail a process entry whose event loop drains while `work` is still pending.
+ *
+ * The CLI starts from a floating `runCli()` call because top-level await breaks
+ * `--bytecode` builds. When a one-shot command awaits a promise that never
+ * settles and holds no live handle, the loop drains and Bun exits 0 without
+ * output: an unfinished command reported as success. `beforeExit` fires in
+ * exactly that state; explicit exits (`process.exit`, {@link quit},
+ * {@link exitProcess}, the signal handlers) never emit it.
+ *
+ * The report runs once and only sets `process.exitCode`, so later `beforeExit`
+ * listeners (LSP shutdown) still run before the process exits 1. It starts no
+ * work of its own beyond the log write; `once` keeps the second `beforeExit`
+ * that any drained follow-up work triggers from reporting again.
+ *
+ * `describe` names what was running (e.g. the resolved subcommand) at report
+ * time; it must return only a command name, never user arguments.
+ */
+export function reportUnsettledEntry(work: Promise<unknown>, describe?: () => string | undefined): void {
+	let pending = true;
+	const settled = (): void => {
+		pending = false;
+	};
+	// Observe both outcomes without claiming the rejection: the caller's `.catch` still owns it.
+	void work.then(settled, settled);
+	process.once("beforeExit", () => {
+		if (!pending) return;
+		const command = describe?.();
+		const subject = command ? `\`${APP_NAME} ${command}\`` : "command";
+		const message = `${subject} ended before completing: the event loop drained while it was still pending (rerun with PI_DEBUG_STARTUP=1 to see the last phase reached)`;
+		try {
+			fs.writeSync(2, `${APP_NAME}: ${message}\n`);
+		} catch {}
+		logger.error(message, { command });
+		process.exitCode = 1;
+	});
+}
+
 // Well-known key marking an error as an *expected* teardown artifact (e.g. a
 // browser run-scope abort at normal run end). `Symbol.for` so the marker
 // survives duplicate module instances across bundles/realms.