@nghyane/arcane-natives 0.1.0

package/src/native.ts

@@ -0,0 +1,278 @@
+/**
+ * Native addon loader and bindings.
+ *
+ * Each module extends NativeBindings via declaration merging in its types.ts.
+ */
+import * as fs from "node:fs";
+import { createRequire } from "node:module";
+import * as os from "node:os";
+import * as path from "node:path";
+import { $env } from "@nghyane/arcane-utils";
+import { getNativesDir } from "@nghyane/arcane-utils/dirs";
+import packageJson from "../package.json";
+import type { NativeBindings } from "./bindings";
+import { embeddedAddon } from "./embedded-addon";
+import "./clipboard/types";
+import "./glob/types";
+import "./grep/types";
+import "./highlight/types";
+import "./html/types";
+import "./image/types";
+import "./keys/types";
+import "./ps/types";
+import "./pty/types";
+import "./shell/types";
+import "./text/types";
+import "./work/types";
+
+export type { NativeBindings, TsFunc } from "./bindings";
+
+type CpuVariant = "modern" | "baseline";
+const require = createRequire(import.meta.url);
+const platformTag = `${process.platform}-${process.arch}`;
+const packageVersion = (packageJson as { version: string }).version;
+const nativeDir = path.join(import.meta.dir, "..", "native");
+const execDir = path.dirname(process.execPath);
+const versionedDir = path.join(getNativesDir(), packageVersion);
+const userDataDir =
+	process.platform === "win32"
+		? path.join(Bun.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local"), "arcane")
+		: path.join(os.homedir(), ".local", "bin");
+const isCompiledBinary =
+	Bun.env.ARCANE_COMPILED ||
+	import.meta.url.includes("$bunfs") ||
+	import.meta.url.includes("~BUN") ||
+	import.meta.url.includes("%7EBUN");
+const SUPPORTED_PLATFORMS = ["linux-x64", "linux-arm64", "darwin-x64", "darwin-arm64", "win32-x64"];
+
+const variantOverride = getVariantOverride();
+const selectedVariant = resolveCpuVariant(variantOverride);
+const addonFilenames = getAddonFilenames(platformTag, selectedVariant);
+const addonLabel = selectedVariant ? `${platformTag} (${selectedVariant})` : platformTag;
+
+const debugCandidates = [
+	path.join(nativeDir, "arcane_natives.dev.node"),
+	path.join(execDir, "arcane_natives.dev.node"),
+];
+const baseReleaseCandidates = addonFilenames.flatMap(filename => [
+	path.join(nativeDir, filename),
+	path.join(execDir, filename),
+]);
+const compiledCandidates = addonFilenames.flatMap(filename => [
+	path.join(versionedDir, filename),
+	path.join(userDataDir, filename),
+]);
+const releaseCandidates = isCompiledBinary ? [...compiledCandidates, ...baseReleaseCandidates] : baseReleaseCandidates;
+const candidates = $env.ARCANE_DEV ? [...debugCandidates, ...releaseCandidates] : releaseCandidates;
+const dedupedCandidates = [...new Set(candidates)];
+
+function runCommand(command: string, args: string[]): string | null {
+	try {
+		const result = Bun.spawnSync([command, ...args], { stdout: "pipe", stderr: "pipe" });
+		if (result.exitCode !== 0) return null;
+		return result.stdout.toString("utf-8").trim();
+	} catch {
+		return null;
+	}
+}
+
+function getVariantOverride(): CpuVariant | null {
+	const value = Bun.env.ARCANE_NATIVE_VARIANT;
+	if (!value) return null;
+	if (value === "modern" || value === "baseline") return value;
+	return null;
+}
+
+function detectAvx2Support(): boolean {
+	if (process.arch !== "x64") {
+		return false;
+	}
+
+	if (process.platform === "linux") {
+		try {
+			const cpuInfo = fs.readFileSync("/proc/cpuinfo", "utf8");
+			return /\bavx2\b/i.test(cpuInfo);
+		} catch {
+			return false;
+		}
+	}
+
+	if (process.platform === "darwin") {
+		const leaf7 = runCommand("sysctl", ["-n", "machdep.cpu.leaf7_features"]);
+		if (leaf7 && /\bAVX2\b/i.test(leaf7)) {
+			return true;
+		}
+		const features = runCommand("sysctl", ["-n", "machdep.cpu.features"]);
+		return Boolean(features && /\bAVX2\b/i.test(features));
+	}
+
+	if (process.platform === "win32") {
+		const output = runCommand("powershell.exe", [
+			"-NoProfile",
+			"-NonInteractive",
+			"-Command",
+			"[System.Runtime.Intrinsics.X86.Avx2]::IsSupported",
+		]);
+		return output?.toLowerCase() === "true";
+	}
+
+	return false;
+}
+
+function resolveCpuVariant(override: CpuVariant | null): CpuVariant | null {
+	if (process.arch !== "x64") return null;
+	if (override) return override;
+	return detectAvx2Support() ? "modern" : "baseline";
+}
+
+function getAddonFilenames(tag: string, variant: CpuVariant | null): string[] {
+	const defaultFilename = `arcane_natives.${tag}.node`;
+	if (process.arch !== "x64" || !variant) return [defaultFilename];
+	const baselineFilename = `arcane_natives.${tag}-baseline.node`;
+	const modernFilename = `arcane_natives.${tag}-modern.node`;
+	if (variant === "modern") {
+		return [modernFilename, baselineFilename, defaultFilename];
+	}
+	return [baselineFilename, defaultFilename];
+}
+
+function selectEmbeddedAddonFile(): { filename: string; filePath: string } | null {
+	if (!embeddedAddon) return null;
+	const defaultFile = embeddedAddon.files.find(file => file.variant === "default") ?? null;
+	if (process.arch !== "x64") return defaultFile ?? embeddedAddon.files[0] ?? null;
+	if (selectedVariant === "modern") {
+		return (
+			embeddedAddon.files.find(file => file.variant === "modern") ??
+			embeddedAddon.files.find(file => file.variant === "baseline") ??
+			null
+		);
+	}
+	return embeddedAddon.files.find(file => file.variant === "baseline") ?? null;
+}
+function maybeExtractEmbeddedAddon(errors: string[]): string | null {
+	if (!isCompiledBinary || !embeddedAddon) return null;
+	if (embeddedAddon.platformTag !== platformTag || embeddedAddon.version !== packageVersion) return null;
+
+	const selectedEmbeddedFile = selectEmbeddedAddonFile();
+	if (!selectedEmbeddedFile) return null;
+	const targetPath = path.join(versionedDir, selectedEmbeddedFile.filename);
+
+	try {
+		fs.mkdirSync(versionedDir, { recursive: true });
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		errors.push(`embedded addon dir: ${message}`);
+		return null;
+	}
+
+	if (fs.existsSync(targetPath)) {
+		return targetPath;
+	}
+
+	try {
+		const buffer = fs.readFileSync(selectedEmbeddedFile.filePath);
+		fs.writeFileSync(targetPath, buffer);
+		return targetPath;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		errors.push(`embedded addon write (${selectedEmbeddedFile.filename}): ${message}`);
+		return null;
+	}
+}
+function loadNative(): NativeBindings {
+	const errors: string[] = [];
+	const embeddedCandidate = maybeExtractEmbeddedAddon(errors);
+	const runtimeCandidates = embeddedCandidate ? [embeddedCandidate, ...dedupedCandidates] : dedupedCandidates;
+	for (const candidate of runtimeCandidates) {
+		try {
+			const bindings = require(candidate) as NativeBindings;
+			validateNative(bindings, candidate);
+			if ($env.ARCANE_DEV) {
+				console.log(`Loaded native addon from ${candidate}`);
+			}
+			return bindings;
+		} catch (err) {
+			if ($env.ARCANE_DEV) {
+				console.error(`Error loading native addon from ${candidate}:`, err);
+			}
+			const message = err instanceof Error ? err.message : String(err);
+			errors.push(`${candidate}: ${message}`);
+		}
+	}
+	// Check if this is an unsupported platform
+	if (!SUPPORTED_PLATFORMS.includes(platformTag)) {
+		throw new Error(
+			`Unsupported platform: ${platformTag}\n` +
+				`Supported platforms: ${SUPPORTED_PLATFORMS.join(", ")}\n` +
+				"If you need support for this platform, please open an issue.",
+		);
+	}
+	const details = errors.map(error => `- ${error}`).join("\n");
+	let helpMessage: string;
+	if (isCompiledBinary) {
+		const expectedPaths = addonFilenames.map(filename => `  ${path.join(versionedDir, filename)}`).join("\n");
+		const downloadHints = addonFilenames
+			.map(filename => {
+				const downloadUrl = `https://github.com/nghyane/arcane/releases/latest/download/${filename}`;
+				const targetPath = path.join(versionedDir, filename);
+				return `  curl -fsSL "${downloadUrl}" -o "${targetPath}"`;
+			})
+			.join("\n");
+		helpMessage =
+			`The compiled binary should extract one of:\n${expectedPaths}\n\n` +
+			`If missing, delete ${versionedDir} and re-run, or download manually:\n${downloadHints}`;
+	} else {
+		helpMessage =
+			"If installed via npm/bun, try reinstalling: bun install @nghyane/arcane-natives\n" +
+			"If developing locally, build with: bun --cwd=packages/natives run build:native\n" +
+			"Optional x64 variants: TARGET_VARIANT=baseline|modern bun --cwd=packages/natives run build:native";
+	}
+
+	throw new Error(
+		`Failed to load arcane_natives native addon for ${addonLabel}.\n\nTried:\n${details}\n\n${helpMessage}`,
+	);
+}
+function validateNative(bindings: NativeBindings, source: string): void {
+	const missing: string[] = [];
+	const checkFn = (name: keyof NativeBindings) => {
+		if (typeof bindings[name] !== "function") {
+			missing.push(name);
+		}
+	};
+	checkFn("copyToClipboard");
+	checkFn("readImageFromClipboard");
+	checkFn("glob");
+	checkFn("fuzzyFind");
+	checkFn("grep");
+	checkFn("search");
+	checkFn("hasMatch");
+	checkFn("htmlToMarkdown");
+	checkFn("highlightCode");
+	checkFn("supportsLanguage");
+	checkFn("getSupportedLanguages");
+	checkFn("truncateToWidth");
+	checkFn("sanitizeText");
+	checkFn("wrapTextWithAnsi");
+	checkFn("sliceWithWidth");
+	checkFn("extractSegments");
+	checkFn("matchesKittySequence");
+	checkFn("executeShell");
+	checkFn("PtySession");
+	checkFn("Shell");
+	checkFn("parseKey");
+	checkFn("matchesLegacySequence");
+	checkFn("parseKittySequence");
+	checkFn("matchesKey");
+	checkFn("visibleWidth");
+	checkFn("killTree");
+	checkFn("listDescendants");
+	checkFn("getWorkProfile");
+	checkFn("invalidateFsScanCache");
+	if (missing.length) {
+		throw new Error(
+			`Native addon missing exports (${source}). Missing: ${missing.join(", ")}. ` +
+				"Rebuild with `bun --cwd=packages/natives run build:native`.",
+		);
+	}
+}
+export const native = loadNative();

package/src/ps/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Process management utilities.
+ */
+
+import { setNativeKillTree } from "@nghyane/arcane-utils";
+import { native } from "../native";
+
+setNativeKillTree(native.killTree);
+
+export const { killTree, listDescendants } = native;

package/src/ps/types.ts

@@ -0,0 +1,24 @@
+/**
+ * Types for process management.
+ */
+
+export {};
+
+declare module "../bindings" {
+	/** Native process-management bindings implemented in arcane-natives. */
+	interface NativeBindings {
+		/**
+		 * Kill a process and all its descendants using platform-native APIs.
+		 * @param pid Root process id.
+		 * @param signal Signal number (ignored on Windows).
+		 * @returns Number of processes successfully killed.
+		 */
+		killTree(pid: number, signal: number): number;
+		/**
+		 * List all descendant PIDs of a process (children, grandchildren, etc.).
+		 * @param pid Root process id.
+		 * @returns Empty array when the process has no children or doesn't exist.
+		 */
+		listDescendants(pid: number): number[];
+	}
+}

package/src/pty/index.ts

@@ -0,0 +1,10 @@
+/**
+ * PTY-backed interactive execution.
+ */
+
+import { native } from "../native";
+
+export type { PtyRunResult, PtySessionConstructor, PtyStartOptions } from "./types";
+
+export const { PtySession } = native;
+export type PtySession = import("./types").PtySession;

package/src/pty/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Types for PTY-backed interactive execution.
+ */
+
+import type { Cancellable, TsFunc } from "../bindings";
+
+/**
+ * Options for starting a command in a pseudo-terminal session.
+ */
+export interface PtyStartOptions extends Cancellable {
+	/** Command to execute. */
+	command: string;
+	/** Working directory for command execution. */
+	cwd?: string;
+	/** Environment variables for this command. */
+	env?: Record<string, string>;
+	/** PTY column count. */
+	cols?: number;
+	/** PTY row count. */
+	rows?: number;
+}
+
+/**
+ * Result of a PTY command run.
+ */
+export interface PtyRunResult {
+	/** Exit code of the command, if available. */
+	exitCode?: number;
+	/** Whether the command was cancelled by abort signal or kill request. */
+	cancelled: boolean;
+	/** Whether the command timed out. */
+	timedOut: boolean;
+}
+
+/** Stateful PTY session instance. */
+export interface PtySession {
+	/** Start command execution and stream output while it runs. */
+	start(options: PtyStartOptions, onChunk?: TsFunc<string>): Promise<PtyRunResult>;
+	/** Write raw input bytes to PTY stdin. */
+	write(data: string): void;
+	/** Resize active PTY. */
+	resize(cols: number, rows: number): void;
+	/** Force-kill active command. */
+	kill(): void;
+}
+
+/** Native PTY session constructor. */
+export interface PtySessionConstructor {
+	new (): PtySession;
+}
+
+declare module "../bindings" {
+	interface NativeBindings {
+		/** Stateful PTY session constructor for interactive terminal passthrough. */
+		PtySession: PtySessionConstructor;
+	}
+}

package/src/shell/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Native shell execution via brush-core.
+ */
+
+import { native } from "../native";
+import type { ShellExecuteOptions, ShellExecuteResult } from "./types";
+
+export type { ShellExecuteOptions, ShellExecuteResult, ShellOptions, ShellRunOptions, ShellRunResult } from "./types";
+
+export const { Shell } = native;
+export type Shell = import("./types").Shell;
+
+/**
+ * Execute a shell command using brush-core.
+ *
+ * @param options - Execution options including command, cwd, env, timeout
+ * @param onChunk - Optional callback for streaming output chunks
+ * @returns Promise resolving to execution result with exit code and status
+ */
+export async function executeShell(
+	options: ShellExecuteOptions,
+	onChunk?: (chunk: string) => void,
+): Promise<ShellExecuteResult> {
+	const wrappedCallback = onChunk ? (err: Error | null, chunk: string) => !err && onChunk(chunk) : undefined;
+	return native.executeShell(options, wrappedCallback);
+}

package/src/shell/types.ts

@@ -0,0 +1,100 @@
+/**
+ * Types for shell execution via brush-core.
+ */
+
+import type { Cancellable, TsFunc } from "../bindings";
+
+/**
+ * Configuration for a persistent brush-core shell session.
+ */
+export interface ShellOptions {
+	/** Environment variables to set once per session. */
+	sessionEnv?: Record<string, string>;
+	/** Optional snapshot path to source for bash sessions. */
+	snapshotPath?: string;
+}
+
+/**
+ * Options for running a single shell command.
+ */
+export interface ShellRunOptions extends Cancellable {
+	/** The command to execute. */
+	command: string;
+	/** Working directory for command execution. */
+	cwd?: string;
+	/** Environment variables to apply for this command. */
+	env?: Record<string, string>;
+}
+
+/**
+ * Result of running a shell command via brush-core.
+ */
+export interface ShellRunResult {
+	/** Exit code of the command (undefined if cancelled or timed out). */
+	exitCode?: number;
+	/** Whether the command was cancelled via abort. */
+	cancelled: boolean;
+	/** Whether the command timed out. */
+	timedOut: boolean;
+}
+
+/**
+ * Internal options for the native brush-core binding.
+ */
+export interface ShellExecuteOptions extends Cancellable {
+	/** The command to execute. */
+	command: string;
+	/** Working directory for command execution. */
+	cwd?: string;
+	/** Environment variables to apply for this command. */
+	env?: Record<string, string>;
+	/** Environment variables to set once per session. */
+	sessionEnv?: Record<string, string>;
+	/** Optional snapshot path to source for bash sessions. */
+	snapshotPath?: string;
+}
+
+/**
+/** Internal result from the native brush-core binding. */
+export interface ShellExecuteResult extends ShellRunResult {}
+
+/** Native Shell class instance. */
+export interface Shell {
+	/**
+	 * Run a command in the shell.
+	 * @param options Command execution options.
+	 * @param onChunk Optional callback for streamed output.
+	 * @returns Promise resolving to the command result.
+	 */
+	run(options: ShellRunOptions, onChunk?: TsFunc<string>): Promise<ShellRunResult>;
+	/**
+	 * Abort all running commands in this session.
+	 * @param reason Optional reason for the abort.
+	 */
+	abort(reason?: string): void;
+}
+
+/** Native Shell class constructor. */
+export interface ShellConstructor {
+	/**
+	 * Create a new shell session.
+	 * @param options Optional session configuration.
+	 */
+	new (options?: ShellOptions): Shell;
+}
+
+declare module "../bindings" {
+	/** Native bindings exposed by the shell module. */
+	interface NativeBindings {
+		/**
+		 * Execute a shell command with explicit session metadata.
+		 * @param options Execution options including session identifiers.
+		 * @param onChunk Optional callback for streamed output.
+		 * @returns Promise resolving to the command result.
+		 */
+		executeShell(options: ShellExecuteOptions, onChunk?: TsFunc<string>): Promise<ShellExecuteResult>;
+
+		/** Shell class constructor for creating sessions. */
+		Shell: ShellConstructor;
+	}
+}

package/src/text/index.ts

@@ -0,0 +1,44 @@
+/**
+ * ANSI-aware text utilities powered by native bindings.
+ */
+
+import { Ellipsis, type SliceWithWidthResult } from "@nghyane/arcane-natives";
+import { native } from "../native";
+
+export type { ExtractSegmentsResult, SliceWithWidthResult } from "./types";
+export { Ellipsis } from "./types";
+
+/**
+ * Truncate text to fit within a maximum visible width, adding ellipsis if needed.
+ * Optionally pad with spaces to reach exactly maxWidth.
+ * Properly handles ANSI escape codes (they don't count toward width).
+ *
+ * @param text - Text to truncate (may contain ANSI codes)
+ * @param maxWidth - Maximum visible width
+ * @param ellipsis - Ellipsis kind to append when truncating (default: Unicode "…")
+ * @param pad - If true, pad result with spaces to exactly maxWidth (default: false)
+ * @returns Truncated text, optionally padded to exactly maxWidth
+ */
+export function truncateToWidth(
+	text: string,
+	maxWidth: number,
+	ellipsis: Ellipsis = Ellipsis.Unicode,
+	pad = false,
+): string {
+	return native.truncateToWidth(text, maxWidth, ellipsis, pad);
+}
+
+/**
+ * Slice a range of visible columns from a line.
+ * @param line - The line to slice
+ * @param startCol - The starting column
+ * @param length - The length of the slice
+ * @param strict - Whether to strictly enforce the length
+ * @returns The sliced line
+ */
+export function sliceWithWidth(line: string, startCol: number, length: number, strict = false): SliceWithWidthResult {
+	if (length <= 0) return { text: "", width: 0 };
+	return native.sliceWithWidth(line, startCol, length, strict);
+}
+
+export const { wrapTextWithAnsi, visibleWidth, extractSegments, sanitizeText } = native;

package/src/text/types.ts

@@ -0,0 +1,84 @@
+/**
+ * Types for ANSI-aware text utilities.
+ */
+
+/** Result of slicing a line by visible columns. */
+export interface SliceWithWidthResult {
+	/** UTF-16 slice containing the selected text. */
+	text: string;
+	/** Visible width of the slice in terminal cells. */
+	width: number;
+}
+
+/** Result of extracting before/after overlay segments. */
+export interface ExtractSegmentsResult {
+	/** UTF-16 content before the overlay region. */
+	before: string;
+	/** Visible width of the `before` segment. */
+	beforeWidth: number;
+	/** UTF-16 content after the overlay region. */
+	after: string;
+	/** Visible width of the `after` segment. */
+	afterWidth: number;
+}
+
+/** Ellipsis strategy for truncation. */
+export const enum Ellipsis {
+	/** Use a single Unicode ellipsis character ("…"). */
+	Unicode = 0,
+	/** Use three ASCII dots ("..."). */
+	Ascii = 1,
+	/** Omit ellipsis entirely. */
+	Omit = 2,
+}
+
+declare module "../bindings" {
+	interface NativeBindings {
+		/**
+		 * Truncate text to a visible width, optionally padding with spaces.
+		 * @param text UTF-16 input text.
+		 * @param maxWidth Maximum visible width in terminal cells.
+		 * @param ellipsisKind Ellipsis strategy (see {@link Ellipsis}).
+		 * @param pad Whether to pad the output to `maxWidth`.
+		 */
+		truncateToWidth(text: string, maxWidth: number, ellipsisKind: number, pad: boolean): string;
+		/**
+		 * Sanitize text output: strip ANSI codes, remove binary garbage, normalize line endings.
+		 */
+		sanitizeText(text: string): string;
+
+		/**
+		 * Wrap text to a visible width, preserving ANSI codes across line breaks.
+		 * @param text UTF-16 input text with optional ANSI escapes.
+		 * @param width Maximum visible width per line.
+		 */
+		wrapTextWithAnsi(text: string, width: number): string[];
+		/**
+		 * Slice a range of visible columns from a line.
+		 * @param line UTF-16 input line with optional ANSI escapes.
+		 * @param startCol Starting column in terminal cells.
+		 * @param length Number of visible cells to include.
+		 * @param strict Whether to drop graphemes that overflow the range.
+		 */
+		sliceWithWidth(line: string, startCol: number, length: number, strict: boolean): SliceWithWidthResult;
+		/**
+		 * Measure the visible width of text (excluding ANSI codes).
+		 * @param text UTF-16 input text with optional ANSI escapes.
+		 */
+		visibleWidth(text: string): number;
+		/** Extract before/after segments around an overlay region.
+		 * @param line UTF-16 input line with optional ANSI escapes.
+		 * @param beforeEnd Column where the "before" segment ends.
+		 * @param afterStart Column where the "after" segment starts.
+		 * @param afterLen Visible width of the "after" segment.
+		 * @param strictAfter Whether to drop graphemes that overflow `afterLen`.
+		 */
+		extractSegments(
+			line: string,
+			beforeEnd: number,
+			afterStart: number,
+			afterLen: number,
+			strictAfter: boolean,
+		): ExtractSegmentsResult;
+	}
+}

package/src/work/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Work scheduling profiling via native instrumentation.
+ *
+ * Always-on profiling - samples are collected into a circular buffer.
+ * Call `getWorkProfile()` to retrieve recent activity.
+ */
+
+import { native } from "../native";
+
+export type { WorkProfile } from "./types";
+export const { getWorkProfile } = native;

package/src/work/types.ts

@@ -0,0 +1,31 @@
+/**
+ * Types for work scheduling profiling.
+ */
+
+/**
+ * Profiling results from work scheduling instrumentation.
+ */
+export interface WorkProfile {
+	/** Folded stack format for flamegraph tools. */
+	folded: string;
+	/** Markdown summary of profiling results. */
+	summary: string;
+	/** SVG flamegraph (if generation succeeded). */
+	svg: string | null;
+	/** Total work time in milliseconds. */
+	totalMs: number;
+	/** Number of samples collected. */
+	sampleCount: number;
+}
+
+declare module "../bindings" {
+	interface NativeBindings {
+		/**
+		 * Get work profile data from the last N seconds.
+		 *
+		 * Always-on profiling - samples are collected into a circular buffer.
+		 * Call this to retrieve recent activity.
+		 */
+		getWorkProfile(lastSeconds: number): WorkProfile;
+	}
+}