@nghyane/arcane-natives 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @nghyane/arcane-natives
+
+Native Rust functionality via N-API.
+
+## What's Inside
+
+- **Grep**: Regex-based search powered by ripgrep's engine with native file walking and matching
+- **Find**: Glob-based file/directory discovery with gitignore support (pure TypeScript via `globPaths`)
+- **Image**: Image processing via photon-rs (resize, format conversion) exposed through N-API
+
+## Usage
+
+```typescript
+import { grep, find, PhotonImage, SamplingFilter, ImageFormat } from "@nghyane/arcane-natives";
+
+// Grep for a pattern
+const results = await grep({
+	pattern: "TODO",
+	path: "/path/to/project",
+	glob: "*.ts",
+	context: 2,
+});
+
+// Find files
+const files = await find({
+	pattern: "*.rs",
+	path: "/path/to/project",
+	fileType: "file",
+});
+
+// Image processing
+const image = await PhotonImage.parse(bytes);
+const resized = await image.resize(800, 600, SamplingFilter.Lanczos3);
+const pngBytes = await resized.encode(ImageFormat.PNG, 100);
+```
+
+## Building
+
+```bash
+# Build native addon from workspace root (requires Rust)
+bun run build:native
+
+# Type check
+bun run check
+```
+
+## Architecture
+
+```
+crates/arcane-natives/       # Rust source (workspace member)
+  src/lib.rs             # N-API exports
+  src/image.rs           # Image processing (photon-rs)
+  Cargo.toml             # Rust dependencies
+native/                  # Native addon binaries
+  arcane_natives.<platform>-<arch>-modern.node   # x64 modern ISA (AVX2)
+  arcane_natives.<platform>-<arch>-baseline.node # x64 baseline ISA
+  arcane_natives.<platform>-<arch>.node          # non-x64 build artifact
+src/                     # TypeScript wrappers
+  native.ts              # Native addon loader
+  index.ts               # Public API
+```

package/package.json

@@ -0,0 +1,163 @@
+{
+  "type": "module",
+  "name": "@nghyane/arcane-natives",
+  "version": "0.1.0",
+  "description": "Native Rust bindings for grep, clipboard, image processing, syntax highlighting, PTY, and shell operations via N-API",
+  "homepage": "https://github.com/nghyane/arcane",
+  "author": "Can Bölük",
+  "license": "GPL-3.0-or-later",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nghyane/arcane.git",
+    "directory": "packages/natives"
+  },
+  "bugs": {
+    "url": "https://github.com/nghyane/arcane/issues"
+  },
+  "keywords": [
+    "napi",
+    "rust",
+    "native",
+    "grep",
+    "text-processing",
+    "clipboard",
+    "image",
+    "pty",
+    "shell",
+    "syntax-highlighting"
+  ],
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "scripts": {
+    "build:native": "bun scripts/build-native.ts",
+    "dev:native": "bun scripts/build-native.ts --dev",
+    "embed:native": "bun scripts/embed-native.ts",
+    "check": "biome check . && tsgo -p tsconfig.json",
+    "fix": "biome check --write --unsafe .",
+    "test": "bun run build:native && bun test",
+    "bench": "bun bench/grep.ts"
+  },
+  "dependencies": {
+    "@nghyane/arcane-utils": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.9"
+  },
+  "engines": {
+    "bun": ">=1.3.7"
+  },
+  "files": [
+    "src",
+    "native",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./*": {
+      "types": "./src/*.ts",
+      "import": "./src/*.ts"
+    },
+    "./clipboard": {
+      "types": "./src/clipboard/index.ts",
+      "import": "./src/clipboard/index.ts"
+    },
+    "./clipboard/*": {
+      "types": "./src/clipboard/*.ts",
+      "import": "./src/clipboard/*.ts"
+    },
+    "./glob": {
+      "types": "./src/glob/index.ts",
+      "import": "./src/glob/index.ts"
+    },
+    "./glob/*": {
+      "types": "./src/glob/*.ts",
+      "import": "./src/glob/*.ts"
+    },
+    "./grep": {
+      "types": "./src/grep/index.ts",
+      "import": "./src/grep/index.ts"
+    },
+    "./grep/*": {
+      "types": "./src/grep/*.ts",
+      "import": "./src/grep/*.ts"
+    },
+    "./highlight": {
+      "types": "./src/highlight/index.ts",
+      "import": "./src/highlight/index.ts"
+    },
+    "./highlight/*": {
+      "types": "./src/highlight/*.ts",
+      "import": "./src/highlight/*.ts"
+    },
+    "./html": {
+      "types": "./src/html/index.ts",
+      "import": "./src/html/index.ts"
+    },
+    "./html/*": {
+      "types": "./src/html/*.ts",
+      "import": "./src/html/*.ts"
+    },
+    "./image": {
+      "types": "./src/image/index.ts",
+      "import": "./src/image/index.ts"
+    },
+    "./image/*": {
+      "types": "./src/image/*.ts",
+      "import": "./src/image/*.ts"
+    },
+    "./keys": {
+      "types": "./src/keys/index.ts",
+      "import": "./src/keys/index.ts"
+    },
+    "./keys/*": {
+      "types": "./src/keys/*.ts",
+      "import": "./src/keys/*.ts"
+    },
+    "./ps": {
+      "types": "./src/ps/index.ts",
+      "import": "./src/ps/index.ts"
+    },
+    "./ps/*": {
+      "types": "./src/ps/*.ts",
+      "import": "./src/ps/*.ts"
+    },
+    "./pty": {
+      "types": "./src/pty/index.ts",
+      "import": "./src/pty/index.ts"
+    },
+    "./pty/*": {
+      "types": "./src/pty/*.ts",
+      "import": "./src/pty/*.ts"
+    },
+    "./shell": {
+      "types": "./src/shell/index.ts",
+      "import": "./src/shell/index.ts"
+    },
+    "./shell/*": {
+      "types": "./src/shell/*.ts",
+      "import": "./src/shell/*.ts"
+    },
+    "./text": {
+      "types": "./src/text/index.ts",
+      "import": "./src/text/index.ts"
+    },
+    "./text/*": {
+      "types": "./src/text/*.ts",
+      "import": "./src/text/*.ts"
+    },
+    "./work": {
+      "types": "./src/work/index.ts",
+      "import": "./src/work/index.ts"
+    },
+    "./work/*": {
+      "types": "./src/work/*.ts",
+      "import": "./src/work/*.ts"
+    }
+  }
+}

package/src/bindings.ts

@@ -0,0 +1,23 @@
+/**
+ * Base types for native bindings.
+ * Modules extend this interface via declaration merging.
+ */
+
+/** Callback type for threadsafe functions from N-API. */
+export type TsFunc<T> = (error: Error | null, value: T) => void;
+
+/** Options for cancellable operations. */
+export interface Cancellable {
+	/** Timeout in milliseconds for the operation. */
+	timeoutMs?: number;
+	/** Abort signal for cancelling the operation. */
+	signal?: AbortSignal;
+}
+
+/**
+ * Native bindings interface.
+ * Extended by each module via declaration merging.
+ */
+export interface NativeBindings {
+	cancelWork(id: number): void;
+}

package/src/clipboard/index.ts

@@ -0,0 +1,92 @@
+/**
+ * Clipboard helpers backed by native arboard bindings.
+ *
+ * Adds OSC 52 fallback for SSH/mosh, Termux support, and headless guards
+ * on top of the native arboard layer.
+ */
+
+import { execSync } from "node:child_process";
+
+import { native } from "../native";
+
+import type { ClipboardImage } from "./types";
+
+export type { ClipboardImage } from "./types";
+
+/** Whether a display server is available on Linux. */
+const hasDisplay = process.platform !== "linux" || Boolean(process.env.DISPLAY || process.env.WAYLAND_DISPLAY);
+
+/**
+ * Copy text to the system clipboard.
+ *
+ * Emits OSC 52 first when running in a real terminal (works over SSH/mosh),
+ * then attempts native clipboard copy as best-effort for local sessions.
+ * On Termux, tries `termux-clipboard-set` before native.
+ *
+ * @param text - UTF-8 text to place on the clipboard.
+ */
+export async function copyToClipboard(text: string): Promise<void> {
+	if (process.stdout.isTTY) {
+		const encoded = Buffer.from(text).toString("base64");
+		const osc52 = `\x1b]52;c;${encoded}\x07`;
+		const onError = (err: unknown) => {
+			process.stdout.off("error", onError);
+			// Prevent unhandled 'error' from crashing the process when stdout is a closed pipe.
+			if ((err as NodeJS.ErrnoException | null | undefined)?.code === "EPIPE") {
+				return;
+			}
+		};
+		try {
+			process.stdout.on("error", onError);
+			process.stdout.write(osc52, err => {
+				process.stdout.off("error", onError);
+				// If stdout is closed (e.g. piped to a process that exits early),
+				// ignore EPIPE and proceed with native clipboard best-effort.
+				if ((err as NodeJS.ErrnoException | null | undefined)?.code === "EPIPE") {
+					return;
+				}
+			});
+		} catch (err) {
+			process.stdout.off("error", onError);
+			if ((err as NodeJS.ErrnoException | null | undefined)?.code !== "EPIPE") {
+				// Ignore all write failures (OSC 52 is best-effort).
+			}
+		}
+	}
+
+	// Also try native tools (best effort for local sessions)
+	try {
+		if (process.env.TERMUX_VERSION) {
+			try {
+				execSync("termux-clipboard-set", { input: text, timeout: 5000 });
+				return;
+			} catch {
+				// Fall through to native
+			}
+		}
+
+		await native.copyToClipboard(text);
+	} catch {
+		// Ignore — clipboard copy is best-effort
+	}
+}
+
+/**
+ * Read an image from the system clipboard.
+ *
+ * Returns null on Termux (no image clipboard support) or when no display
+ * server is available (headless/SSH without forwarding).
+ *
+ * @returns PNG payload or null when no image is available.
+ */
+export async function readImageFromClipboard(): Promise<ClipboardImage | null> {
+	if (process.env.TERMUX_VERSION) {
+		return null;
+	}
+
+	if (!hasDisplay) {
+		return null;
+	}
+
+	return native.readImageFromClipboard();
+}

package/src/clipboard/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Types for clipboard operations.
+ */
+
+/** PNG-encoded clipboard image payload. */
+export interface ClipboardImage {
+	/** PNG image bytes. */
+	data: Uint8Array;
+	/** MIME type for the PNG payload. */
+	mimeType: string;
+}
+
+declare module "../bindings" {
+	/** Native clipboard operations exposed by the bindings layer. */
+	interface NativeBindings {
+		/**
+		 * Copy text to the system clipboard.
+		 * @param text - UTF-8 text to place on the clipboard.
+		 */
+		copyToClipboard(text: string): Promise<void>;
+		/**
+		 * Read an image from the clipboard.
+		 * @returns PNG payload or null when no image is available.
+		 */
+		readImageFromClipboard(): Promise<ClipboardImage | null>;
+	}
+}

package/src/embedded-addon.ts

@@ -0,0 +1,15 @@
+export type EmbeddedAddonVariant = "modern" | "baseline" | "default";
+
+export interface EmbeddedAddonFile {
+	variant: EmbeddedAddonVariant;
+	filename: string;
+	filePath: string;
+}
+
+export interface EmbeddedAddon {
+	platformTag: string;
+	version: string;
+	files: EmbeddedAddonFile[];
+}
+
+export const embeddedAddon: EmbeddedAddon | null = null;

package/src/glob/index.ts

@@ -0,0 +1,43 @@
+/**
+ * File discovery API powered by globset + ignore crate.
+ */
+
+import * as path from "node:path";
+import { native } from "../native";
+import type { GlobMatch, GlobOptions, GlobResult } from "./types";
+
+export type { GlobMatch, GlobOptions, GlobResult } from "./types";
+export { FileType } from "./types";
+
+/**
+ * Find files matching a glob pattern.
+ * Respects .gitignore by default.
+ */
+export async function glob(options: GlobOptions, onMatch?: (match: GlobMatch) => void): Promise<GlobResult> {
+	const searchPath = path.resolve(options.path);
+	const pattern = options.pattern || "*";
+	// napi-rs ThreadsafeFunction passes (error, value) - skip callback on error
+	const cb = onMatch ? (err: Error | null, m: GlobMatch) => !err && onMatch(m) : undefined;
+
+	return native.glob(
+		{
+			...options,
+			path: searchPath,
+			pattern,
+			hidden: options.hidden ?? false,
+			gitignore: options.gitignore ?? true,
+			recursive: options.recursive ?? true,
+		},
+		cb,
+	);
+}
+
+/**
+ * Invalidate the filesystem scan cache.
+ *
+ * When called with a path, removes entries for roots containing that path.
+ * When called without a path, clears the entire cache.
+ */
+export function invalidateFsScanCache(path?: string): void {
+	native.invalidateFsScanCache(path);
+}

package/src/glob/types.ts

@@ -0,0 +1,69 @@
+/**
+ * Types for native find API.
+ */
+
+import type { Cancellable, TsFunc } from "../bindings";
+
+export const enum FileType {
+	/** A regular file. */
+	File = 1,
+	/** A directory. */
+	Dir = 2,
+	/** A symlink. */
+	Symlink = 3,
+}
+
+/** Options for discovering files and directories. */
+export interface GlobOptions extends Cancellable {
+	/** Glob pattern to match (e.g., `*.ts`). */
+	pattern: string;
+	/** Directory to search. */
+	path: string;
+	/** Filter by file type: "file", "dir", or "symlink". Symlinks match file/dir filters when their target type matches. */
+	fileType?: FileType;
+	/** Match simple patterns recursively by default (example: *.ts -> recursive match). Set false to keep patterns relative to the search root only. */
+	recursive?: boolean;
+	/** Include hidden files (default: false). */
+	hidden?: boolean;
+	/** Maximum number of results to return. */
+	maxResults?: number;
+	/** Respect .gitignore files (default: true). */
+	gitignore?: boolean;
+	/** Enable shared filesystem scan cache (default: false). */
+	cache?: boolean;
+	/** Sort results by mtime (most recent first) before applying limit. */
+	sortByMtime?: boolean;
+	/** Include node_modules entries even when pattern does not mention node_modules. */
+	includeNodeModules?: boolean;
+}
+
+/** A single filesystem match. */
+export interface GlobMatch {
+	/** Relative path from the search root. */
+	path: string;
+	/** Resolved filesystem type for the match (for fileType=file/dir filters, symlink targets are reported as file/dir). */
+	fileType: FileType;
+	/** Modification time in milliseconds since epoch, if available. */
+	mtime?: number;
+}
+
+/** Result of a find operation. */
+export interface GlobResult {
+	/** Matched filesystem entries. */
+	matches: GlobMatch[];
+	/** Number of matches returned after limits are applied. */
+	totalMatches: number;
+}
+
+declare module "../bindings" {
+	interface NativeBindings {
+		/**
+		 * Find filesystem entries matching a glob pattern.
+		 * @param options Search options that control globbing and filters.
+		 * @param onMatch Optional callback for streaming matches as they are found.
+		 */
+		glob(options: GlobOptions, onMatch?: TsFunc<GlobMatch>): Promise<GlobResult>;
+		/** Invalidate the filesystem scan cache for the given path (or all caches if omitted). */
+		invalidateFsScanCache(path?: string): void;
+	}
+}

package/src/grep/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Native ripgrep wrapper using N-API.
+ */
+
+import { native } from "../native";
+import type {
+	ContextLine,
+	FuzzyFindMatch,
+	FuzzyFindOptions,
+	FuzzyFindResult,
+	GrepMatch,
+	GrepOptions,
+	GrepResult,
+	GrepSummary,
+	SearchOptions,
+	SearchResult,
+} from "./types";
+
+export type {
+	ContextLine,
+	FuzzyFindMatch,
+	FuzzyFindOptions,
+	FuzzyFindResult,
+	GrepMatch,
+	GrepOptions,
+	GrepResult,
+	GrepSummary,
+	SearchOptions,
+	SearchResult,
+};
+
+/**
+ * Search files for a regex pattern with optional streaming callback.
+ */
+export async function grep(options: GrepOptions, onMatch?: (match: GrepMatch) => void): Promise<GrepResult> {
+	// napi-rs ThreadsafeFunction passes (error, value) - skip callback on error
+	const cb = onMatch ? (err: Error | null, m: GrepMatch) => !err && onMatch(m) : undefined;
+	return native.grep(options, cb);
+}
+
+/**
+ * Search a single file's content for a pattern.
+ * Lower-level API for when you already have file content.
+ *
+ * Accepts `Uint8Array`/`Buffer` for zero-copy when content is already UTF-8 encoded.
+ */
+export function searchContent(content: string | Uint8Array, options: SearchOptions): SearchResult {
+	return native.search(content, options);
+}
+
+/**
+ * Quick check if content contains a pattern match.
+ *
+ * Accepts `Uint8Array`/`Buffer` for zero-copy when content/pattern are already UTF-8 encoded.
+ */
+export function hasMatch(
+	content: string | Uint8Array,
+	pattern: string | Uint8Array,
+	options?: { ignoreCase?: boolean; multiline?: boolean },
+): boolean {
+	return native.hasMatch(content, pattern, options?.ignoreCase ?? false, options?.multiline ?? false);
+}
+
+/**
+ * Fuzzy file path search for autocomplete.
+ *
+ * Searches for files and directories whose paths contain the query substring
+ * (case-insensitive). Respects .gitignore by default.
+ */
+export async function fuzzyFind(options: FuzzyFindOptions): Promise<FuzzyFindResult> {
+	return native.fuzzyFind(options);
+}