@oh-my-pi/pi-natives 9.6.4 → 9.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oh-my-pi/pi-natives",
-	"version": "9.6.4",
+	"version": "9.7.0",
 	"description": "Native Rust functionality via N-API",
 	"type": "module",
 	"main": "./src/index.ts",
@@ -17,6 +17,7 @@
 	],
 	"scripts": {
 		"build:native": "bun scripts/build-native.ts",
+		"dev:native": "bun scripts/build-native.ts --dev",
 		"check": "biome check . && tsgo -p tsconfig.json",
 		"fix": "biome check --write --unsafe .",
 		"test": "bun run build:native && bun test",
@@ -30,7 +31,7 @@
 		"directory": "packages/natives"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-utils": "9.6.4"
+		"@oh-my-pi/pi-utils": "9.7.0"
 	},
 	"devDependencies": {
 		"@types/node": "^25.0.10"

package/src/index.ts

@@ -3,9 +3,12 @@
  */
 
 import * as path from "node:path";
+import { setNativeKillTree } from "@oh-my-pi/pi-utils";
 import type { FindMatch, FindOptions, FindResult } from "./find/types";
 import { native } from "./native";
 
+setNativeKillTree(native.killTree);
+
 // =============================================================================
 // Grep (ripgrep-based regex search)
 // =============================================================================
@@ -97,7 +100,15 @@ export {
 // Keyboard sequence helpers
 // =============================================================================
 
-export { matchesKittySequence } from "./keys/index";
+export {
+	type KeyEventType,
+	matchesKey,
+	matchesKittySequence,
+	matchesLegacySequence,
+	type ParsedKittyResult,
+	parseKey,
+	parseKittySequence,
+} from "./keys/index";
 
 // =============================================================================
 // HTML to Markdown
@@ -108,4 +119,32 @@ export {
 	htmlToMarkdown,
 } from "./html/index";
 
-export type { RequestOptions } from "./request-options";
+// =============================================================================
+// Process management
+// =============================================================================
+
+/**
+ * Kill a process and all its descendants.
+ *
+ * Uses platform-native APIs for efficiency:
+ * - Linux: /proc/{pid}/children
+ * - macOS: libproc (proc_listchildpids)
+ * - Windows: CreateToolhelp32Snapshot
+ *
+ * @param pid - Process ID to kill
+ * @param signal - Signal number (e.g., 9 for SIGKILL). Ignored on Windows.
+ * @returns Number of processes successfully killed
+ */
+export function killTree(pid: number, signal: number): number {
+	return native.killTree(pid, signal);
+}
+
+/**
+ * List all descendant PIDs of a process.
+ *
+ * @param pid - Process ID to query
+ * @returns Array of descendant PIDs (children, grandchildren, etc.)
+ */
+export function listDescendants(pid: number): number[] {
+	return native.listDescendants(pid);
+}

package/src/keys/index.ts

@@ -2,9 +2,63 @@
  * Keyboard sequence utilities powered by native bindings.
  */
 
-import { native } from "../native";
+import { type KeyEventType, native, type ParsedKittyResult } from "../native";
+
+export type { KeyEventType, ParsedKittyResult };
 
 /** Match Kitty protocol sequences for codepoint and modifier. */
 export function matchesKittySequence(data: string, expectedCodepoint: number, expectedModifier: number): boolean {
 	return native.matchesKittySequence(data, expectedCodepoint, expectedModifier);
 }
+
+/**
+ * Parse a Kitty keyboard protocol sequence.
+ *
+ * @param data - Raw escape sequence from terminal
+ * @returns Parsed sequence with codepoint, modifier, and event type, or undefined if not a valid Kitty sequence
+ */
+export function parseKittySequence(data: string): ParsedKittyResult | undefined {
+	return native.parseKittySequence(data) ?? undefined;
+}
+
+/**
+ * Parse terminal input and return a normalized key identifier.
+ *
+ * Returns key names like "escape", "ctrl+c", "shift+tab", "alt+enter".
+ * Returns undefined if the input is not a recognized key sequence.
+ *
+ * @param data - Raw input data from terminal
+ * @param kittyProtocolActive - Whether Kitty keyboard protocol is active
+ */
+export function parseKey(data: string, kittyProtocolActive: boolean): string | undefined {
+	return native.parseKey(data, kittyProtocolActive) ?? undefined;
+}
+
+/**
+ * Check if input matches a legacy escape sequence for a specific key.
+ *
+ * @param data - Raw input data from terminal
+ * @param keyName - Key name to match (e.g., "up", "f1", "ctrl+up")
+ */
+export function matchesLegacySequence(data: string, keyName: string): boolean {
+	return native.matchesLegacySequence(data, keyName);
+}
+
+/**
+ * Match input data against a key identifier string.
+ *
+ * Supported key identifiers:
+ * - Single keys: "escape", "tab", "enter", "backspace", "delete", "home", "end", "space"
+ * - Arrow keys: "up", "down", "left", "right"
+ * - Ctrl combinations: "ctrl+c", "ctrl+z", etc.
+ * - Shift combinations: "shift+tab", "shift+enter"
+ * - Alt combinations: "alt+enter", "alt+backspace"
+ * - Combined modifiers: "shift+ctrl+p", "ctrl+alt+x"
+ *
+ * @param data - Raw input data from terminal
+ * @param keyId - Key identifier (e.g., "ctrl+c", "escape")
+ * @param kittyProtocolActive - Whether Kitty keyboard protocol is active
+ */
+export function matchesKey(data: string, keyId: string, kittyProtocolActive: boolean): boolean {
+	return native.matchesKey(data, keyId, kittyProtocolActive);
+}

package/src/native.ts

@@ -13,6 +13,26 @@ import type { HighlightColors } from "./highlight/index";
 import type { HtmlToMarkdownOptions } from "./html/types";
 import type { ExtractSegmentsResult, SliceWithWidthResult } from "./text/index";
 
+export type { RequestOptions } from "./request-options";
+
+/**
+ * Event types from Kitty keyboard protocol (flag 2)
+ * 1 = key press, 2 = key repeat, 3 = key release
+ */
+export const enum KeyEventType {
+	Press = 1,
+	Repeat = 2,
+	Release = 3,
+}
+/** Parsed Kitty keyboard protocol sequence result. */
+export interface ParsedKittyResult {
+	codepoint: number;
+	shiftedKey?: number;
+	baseLayoutKey?: number;
+	modifier: number;
+	eventType?: KeyEventType;
+}
+
 export interface NativePhotonImage {
 	getWidth(): number;
 	getHeight(): number;
@@ -66,6 +86,12 @@ export interface NativeBindings {
 		strictAfter: boolean,
 	): ExtractSegmentsResult;
 	matchesKittySequence(data: string, expectedCodepoint: number, expectedModifier: number): boolean;
+	parseKey(data: string, kittyProtocolActive: boolean): string | null;
+	matchesLegacySequence(data: string, keyName: string): boolean;
+	parseKittySequence(data: string): ParsedKittyResult | null;
+	matchesKey(data: string, keyId: string, kittyProtocolActive: boolean): boolean;
+	killTree(pid: number, signal: number): number;
+	listDescendants(pid: number): number[];
 }
 
 const require = createRequire(import.meta.url);
@@ -76,15 +102,19 @@ const execDir = path.dirname(process.execPath);
 
 const SUPPORTED_PLATFORMS = ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "win32-x64"];
 
-const candidates = [
-	path.join(repoRoot, "target", "release", "pi_natives.node"),
-	path.join(repoRoot, "crates", "pi-natives", "target", "release", "pi_natives.node"),
+const debugCandidates = [path.join(nativeDir, "pi_natives.dev.node"), path.join(execDir, "pi_natives.dev.node")];
+
+const releaseCandidates = [
+	// Platform-tagged builds (preferred - always correct platform)
 	path.join(nativeDir, `pi_natives.${platformTag}.node`),
-	path.join(nativeDir, "pi_natives.node"),
 	path.join(execDir, `pi_natives.${platformTag}.node`),
+	// Fallback untagged (only created for native builds, not cross-compilation)
+	path.join(nativeDir, "pi_natives.node"),
 	path.join(execDir, "pi_natives.node"),
 ];
 
+const candidates = process.env.OMP_DEV ? [...debugCandidates, ...releaseCandidates] : releaseCandidates;
+
 function loadNative(): NativeBindings {
 	const errors: string[] = [];
 
@@ -92,8 +122,15 @@ function loadNative(): NativeBindings {
 		try {
 			const bindings = require(candidate) as NativeBindings;
 			validateNative(bindings, candidate);
+			if (process.env.OMP_DEV) {
+				console.log(`Loaded native addon from ${candidate}`);
+				console.log(` - Root: ${repoRoot}`);
+			}
 			return bindings;
 		} catch (err) {
+			if (process.env.OMP_DEV) {
+				console.error(`Error loading native addon from ${candidate}:`, err);
+			}
 			const message = err instanceof Error ? err.message : String(err);
 			errors.push(`${candidate}: ${message}`);
 		}
@@ -138,6 +175,13 @@ function validateNative(bindings: NativeBindings, source: string): void {
 	checkFn("sliceWithWidth");
 	checkFn("extractSegments");
 	checkFn("matchesKittySequence");
+	checkFn("parseKey");
+	checkFn("matchesLegacySequence");
+	checkFn("parseKittySequence");
+	checkFn("matchesKey");
+	checkFn("visibleWidth");
+	checkFn("killTree");
+	checkFn("listDescendants");
 
 	if (missing.length) {
 		throw new Error(