@nghyane/arcane-natives 0.1.0

package/src/grep/types.ts

@@ -0,0 +1,185 @@
+/**
+ * Types for grep/search operations.
+ */
+
+import type { Cancellable, TsFunc } from "../bindings";
+
+/** Options for searching files. */
+export interface GrepOptions extends Cancellable {
+	/** Regex pattern to search for */
+	pattern: string;
+	/** Directory or file to search */
+	path: string;
+	/** Glob filter for filenames (e.g., "*.ts") */
+	glob?: string;
+	/** Filter by file type (e.g., "js", "py", "rust") */
+	type?: string;
+	/** Case-insensitive search */
+	ignoreCase?: boolean;
+	/** Enable multiline matching */
+	multiline?: boolean;
+	/** Include hidden files (default: true) */
+	hidden?: boolean;
+	/** Enable shared filesystem scan cache (default: false). */
+	cache?: boolean;
+	/** Maximum number of matches to return */
+	maxCount?: number;
+	/** Skip first N matches */
+	offset?: number;
+	/** Lines of context before matches */
+	contextBefore?: number;
+	/** Lines of context after matches */
+	contextAfter?: number;
+	/** Lines of context before/after matches (legacy) */
+	context?: number;
+	/** Truncate lines longer than this (characters) */
+	maxColumns?: number;
+	/** Output mode */
+	mode?: "content" | "filesWithMatches" | "count";
+}
+
+/** A context line returned around a match. */
+export interface ContextLine {
+	/** 1-indexed line number. */
+	lineNumber: number;
+	/** Line content (trimmed line ending). */
+	line: string;
+}
+
+/** A single grep match or per-file count entry. */
+export interface GrepMatch {
+	/** File path for the match (relative for directory searches). */
+	path: string;
+	/** 1-indexed line number (0 for count-only entries). */
+	lineNumber: number;
+	/** Matched line content (empty for count-only entries). */
+	line: string;
+	/** Context lines before the match. */
+	contextBefore?: ContextLine[];
+	/** Context lines after the match. */
+	contextAfter?: ContextLine[];
+	/** Whether the line was truncated. */
+	truncated?: boolean;
+	/** Per-file match count (count mode only). */
+	matchCount?: number;
+}
+
+/** Summary stats for a grep run. */
+export interface GrepSummary {
+	/** Total matches across all files. */
+	totalMatches: number;
+	/** Number of files with at least one match. */
+	filesWithMatches: number;
+	/** Number of files searched. */
+	filesSearched: number;
+	/** Whether the limit/offset stopped the search early. */
+	limitReached?: boolean;
+}
+
+/** Full grep result including matches and summary counts. */
+export interface GrepResult extends GrepSummary {
+	/** Matches or per-file counts, depending on mode. */
+	matches: GrepMatch[];
+}
+
+/** Options for searching in-memory content. */
+export interface SearchOptions {
+	/** Regex pattern to search for */
+	pattern: string;
+	/** Case-insensitive search */
+	ignoreCase?: boolean;
+	/** Enable multiline matching */
+	multiline?: boolean;
+	/** Maximum number of matches to return */
+	maxCount?: number;
+	/** Skip first N matches */
+	offset?: number;
+	/** Lines of context before matches */
+	contextBefore?: number;
+	/** Lines of context after matches */
+	contextAfter?: number;
+	/** Lines of context before/after matches (legacy) */
+	context?: number;
+	/** Truncate lines longer than this (characters) */
+	maxColumns?: number;
+	/** Output mode */
+	mode?: "content" | "count";
+}
+
+/** A single content match. */
+export interface SearchMatch {
+	/** 1-indexed line number. */
+	lineNumber: number;
+	/** Matched line content. */
+	line: string;
+	/** Context lines before the match. */
+	contextBefore?: ContextLine[];
+	/** Context lines after the match. */
+	contextAfter?: ContextLine[];
+	/** Whether the line was truncated. */
+	truncated?: boolean;
+}
+
+/** Result of searching in-memory content. */
+export interface SearchResult {
+	/** All matches found. */
+	matches: SearchMatch[];
+	/** Total number of matches (may exceed `matches.length`). */
+	matchCount: number;
+	/** Whether the limit was reached. */
+	limitReached: boolean;
+	/** Error message, if any. */
+	error?: string;
+}
+
+/** Options for fuzzy file path search. */
+export interface FuzzyFindOptions extends Cancellable {
+	/** Fuzzy query to match against file paths (case-insensitive). */
+	query: string;
+	/** Directory to search. */
+	path: string;
+	/** Include hidden files (default: false). */
+	hidden?: boolean;
+	/** Respect .gitignore (default: true). */
+	gitignore?: boolean;
+	/** Enable shared filesystem scan cache (default: false). */
+	cache?: boolean;
+	/** Maximum number of matches to return (default: 100). */
+	maxResults?: number;
+}
+
+/** A single match in fuzzy find results. */
+export interface FuzzyFindMatch {
+	/** Relative path from the search root (uses `/` separators). */
+	path: string;
+	/** Whether this entry is a directory. */
+	isDirectory: boolean;
+	/** Match quality score (higher is better). */
+	score: number;
+}
+
+/** Result of fuzzy file path search. */
+export interface FuzzyFindResult {
+	/** Matched entries (up to `maxResults`). */
+	matches: FuzzyFindMatch[];
+	/** Total number of matches found (may exceed `matches.length`). */
+	totalMatches: number;
+}
+
+declare module "../bindings" {
+	interface NativeBindings {
+		/** Fuzzy file path search for autocomplete. */
+		fuzzyFind(options: FuzzyFindOptions): Promise<FuzzyFindResult>;
+		/** Search files for a regex pattern. */
+		grep(options: GrepOptions, onMatch?: TsFunc<GrepMatch>): Promise<GrepResult>;
+		/** Search in-memory content for a regex pattern. */
+		search(content: string | Uint8Array, options: SearchOptions): SearchResult;
+		/** Quick check if content matches a pattern. */
+		hasMatch(
+			content: string | Uint8Array,
+			pattern: string | Uint8Array,
+			ignoreCase: boolean,
+			multiline: boolean,
+		): boolean;
+	}
+}

package/src/highlight/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Syntax highlighting powered by native syntect bindings.
+ */
+
+import { native } from "../native";
+
+export type { HighlightColors } from "./types";
+
+export const { highlightCode, supportsLanguage, getSupportedLanguages } = native;

package/src/highlight/types.ts

@@ -0,0 +1,56 @@
+/**
+ * Types for syntax highlighting.
+ */
+
+/**
+ * Theme colors for syntax highlighting.
+ * Each color should be an ANSI escape sequence (e.g., "\x1b[38;2;255;0;0m").
+ */
+export interface HighlightColors {
+	/** ANSI color for comments. */
+	comment: string;
+	/** ANSI color for keywords. */
+	keyword: string;
+	/** ANSI color for function names. */
+	function: string;
+	/** ANSI color for variables and identifiers. */
+	variable: string;
+	/** ANSI color for string literals. */
+	string: string;
+	/** ANSI color for numeric literals. */
+	number: string;
+	/** ANSI color for type identifiers. */
+	type: string;
+	/** ANSI color for operators. */
+	operator: string;
+	/** ANSI color for punctuation tokens. */
+	punctuation: string;
+	/** Color for diff inserted lines (+). */
+	inserted?: string;
+	/** Color for diff deleted lines (-). */
+	deleted?: string;
+}
+
+declare module "../bindings" {
+	interface NativeBindings {
+		/**
+		 * Highlight code with syntax coloring.
+		 * @param code Source code to highlight.
+		 * @param lang Language name, extension, or null for plain text.
+		 * @param colors ANSI color palette for semantic scopes.
+		 * @returns Highlighted code with ANSI color codes.
+		 */
+		highlightCode(code: string, lang: string | null | undefined, colors: HighlightColors): string;
+		/**
+		 * Check if a language is supported for highlighting.
+		 * @param lang Language name or extension to test.
+		 * @returns True when highlighting is available.
+		 */
+		supportsLanguage(lang: string): boolean;
+		/**
+		 * Get list of all supported languages.
+		 * @returns Syntect language names supported by the native highlighter.
+		 */
+		getSupportedLanguages(): string[];
+	}
+}

package/src/html/index.ts

@@ -0,0 +1,19 @@
+/**
+ * HTML to Markdown conversion powered by native bindings.
+ */
+
+import { native } from "../native";
+import type { HtmlToMarkdownOptions } from "./types";
+
+export type { HtmlToMarkdownOptions } from "./types";
+
+/**
+ * Convert HTML to Markdown.
+ *
+ * @param html - HTML content to convert
+ * @param options - Conversion options
+ * @returns Markdown text
+ */
+export async function htmlToMarkdown(html: string, options?: HtmlToMarkdownOptions): Promise<string> {
+	return native.htmlToMarkdown(html, options);
+}

package/src/html/types.ts

@@ -0,0 +1,24 @@
+/**
+ * Types for HTML to Markdown conversion.
+ */
+
+/** Options controlling HTML preprocessing and output. */
+export interface HtmlToMarkdownOptions {
+	/** Remove navigation elements, forms, headers, and footers. */
+	cleanContent?: boolean;
+	/** Skip images during conversion. */
+	skipImages?: boolean;
+}
+
+declare module "../bindings" {
+	/** Native HTML utilities exposed by the Rust bindings. */
+	interface NativeBindings {
+		/**
+		 * Convert HTML to Markdown.
+		 * @param html HTML source to convert.
+		 * @param options Optional conversion settings.
+		 * @returns Markdown output.
+		 */
+		htmlToMarkdown(html: string, options?: HtmlToMarkdownOptions | null): Promise<string>;
+	}
+}

package/src/image/index.ts

@@ -0,0 +1,13 @@
+/**
+ * Image processing via native bindings.
+ */
+
+import { native } from "../native";
+
+export { ImageFormat, type PhotonImageConstructor, SamplingFilter } from "./types";
+
+/** PhotonImage class for image manipulation. Use PhotonImage.parse() to create instances. */
+export const PhotonImage = native.PhotonImage;
+
+/** PhotonImage instance type. */
+export type PhotonImage = import("./types").PhotonImage;

package/src/image/types.ts

@@ -0,0 +1,65 @@
+/**
+ * Types for image processing.
+ */
+
+/** Output format for image encoding. */
+export const enum ImageFormat {
+	/** PNG encoded bytes. */
+	PNG = 0,
+	/** JPEG encoded bytes. */
+	JPEG = 1,
+	/** WebP encoded bytes. */
+	WEBP = 2,
+	/** GIF encoded bytes. */
+	GIF = 3,
+}
+
+/** Sampling filter for resize operations. */
+export const enum SamplingFilter {
+	/** Nearest-neighbor sampling (fast, low quality). */
+	Nearest = 1,
+	/** Triangle filter (linear interpolation). */
+	Triangle = 2,
+	/** Catmull-Rom filter with sharper edges. */
+	CatmullRom = 3,
+	/** Gaussian filter for smoother results. */
+	Gaussian = 4,
+	/** Lanczos3 filter for high-quality downscaling. */
+	Lanczos3 = 5,
+}
+
+/** Image container for native image operations. */
+export interface PhotonImage {
+	/** Image width in pixels. */
+	get width(): number;
+	/** Image height in pixels. */
+	get height(): number;
+	/**
+	 * Encode the image using the requested format and quality.
+	 * Returns the encoded image bytes.
+	 */
+	encode(format: ImageFormat, quality: number): Promise<Uint8Array>;
+	/**
+	 * Resize the image to the requested dimensions with the filter.
+	 * Returns a new image instance.
+	 */
+	resize(width: number, height: number, filter: SamplingFilter): Promise<PhotonImage>;
+}
+
+/** Static entrypoints for creating `PhotonImage` instances. */
+export interface PhotonImageConstructor {
+	/** Parse image bytes (PNG, JPEG, WebP, GIF) into a native image. */
+	parse(bytes: Uint8Array): Promise<PhotonImage>;
+	/** Instance prototype reference. */
+	prototype: PhotonImage;
+}
+
+declare module "../bindings" {
+	/** Native bindings for image operations. */
+	interface NativeBindings {
+		/** Sampling filters exposed by the native module. */
+		SamplingFilter: typeof SamplingFilter;
+		/** Photon image constructor exposed by the native module. */
+		PhotonImage: PhotonImageConstructor;
+	}
+}

package/src/index.ts

@@ -0,0 +1,125 @@
+/**
+ * Native utilities powered by N-API.
+ */
+
+// =============================================================================
+// Clipboard
+// =============================================================================
+
+export { type ClipboardImage, copyToClipboard, readImageFromClipboard } from "./clipboard";
+
+// =============================================================================
+// Grep (ripgrep-based regex search)
+// =============================================================================
+
+export {
+	type ContextLine,
+	type FuzzyFindMatch,
+	type FuzzyFindOptions,
+	type FuzzyFindResult,
+	fuzzyFind,
+	type GrepMatch,
+	type GrepOptions,
+	type GrepResult,
+	type GrepSummary,
+	grep,
+	hasMatch,
+	searchContent,
+} from "./grep";
+
+// =============================================================================
+// Glob (file discovery)
+// =============================================================================
+
+export {
+	FileType,
+	type GlobMatch,
+	type GlobOptions,
+	type GlobResult,
+	glob,
+	invalidateFsScanCache,
+} from "./glob";
+
+// =============================================================================
+// Image processing (photon-compatible API)
+// =============================================================================
+
+export { ImageFormat, PhotonImage, SamplingFilter } from "./image";
+
+// =============================================================================
+// Text utilities
+// =============================================================================
+
+export {
+	Ellipsis,
+	type ExtractSegmentsResult,
+	extractSegments,
+	type SliceWithWidthResult,
+	sanitizeText,
+	sliceWithWidth,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "./text";
+
+// =============================================================================
+// Syntax highlighting
+// =============================================================================
+
+export {
+	getSupportedLanguages,
+	type HighlightColors,
+	highlightCode,
+	supportsLanguage,
+} from "./highlight";
+
+// =============================================================================
+// Keyboard sequence helpers
+// =============================================================================
+
+export {
+	type KeyEventType,
+	matchesKey,
+	matchesKittySequence,
+	matchesLegacySequence,
+	type ParsedKittyResult,
+	parseKey,
+	parseKittySequence,
+} from "./keys";
+
+// =============================================================================
+// HTML to Markdown
+// =============================================================================
+
+export { type HtmlToMarkdownOptions, htmlToMarkdown } from "./html";
+
+// =============================================================================
+// Shell execution (brush-core)
+// =============================================================================
+
+export {
+	executeShell,
+	Shell,
+	type ShellExecuteOptions,
+	type ShellExecuteResult,
+	type ShellOptions,
+	type ShellRunOptions,
+	type ShellRunResult,
+} from "./shell";
+
+// =============================================================================
+// PTY execution
+// =============================================================================
+
+export { type PtyRunResult, PtySession, type PtyStartOptions } from "./pty";
+// =============================================================================
+// Process management
+// =============================================================================
+
+export { killTree, listDescendants } from "./ps";
+
+// =============================================================================
+// Work profiling
+// =============================================================================
+
+export { getWorkProfile, type WorkProfile } from "./work";

package/src/keys/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Keyboard sequence utilities powered by native bindings.
+ */
+
+import { native } from "../native";
+
+export type { KeyEventType, ParsedKittyResult } from "./types";
+
+export const { matchesKittySequence, parseKey, matchesLegacySequence, parseKittySequence, matchesKey } = native;

package/src/keys/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Types for keyboard sequence handling.
+ */
+
+/**
+ * Event types from Kitty keyboard protocol (flag 2).
+ * 1 = key press, 2 = key repeat, 3 = key release.
+ */
+export const enum KeyEventType {
+	/** Key press event. */
+	Press = 1,
+	/** Key repeat event. */
+	Repeat = 2,
+	/** Key release event. */
+	Release = 3,
+}
+
+/** Parsed Kitty keyboard protocol sequence result. */
+export interface ParsedKittyResult {
+	/** Primary codepoint associated with the key. */
+	codepoint: number;
+	/** Optional shifted key codepoint from the sequence. */
+	shiftedKey?: number;
+	/** Optional base layout key codepoint from the sequence. */
+	baseLayoutKey?: number;
+	/** Modifier bitmask (shift/alt/ctrl), excluding lock bits. */
+	modifier: number;
+	/** Optional event type from the sequence. */
+	eventType?: KeyEventType;
+}
+
+declare module "../bindings" {
+	interface NativeBindings {
+		/**
+		 * Match Kitty protocol sequences for a codepoint and modifier mask.
+		 * @param data Raw terminal input data.
+		 * @param expectedCodepoint Codepoint to compare against the parsed sequence.
+		 * @param expectedModifier Modifier mask (shift/alt/ctrl).
+		 * @returns True when the sequence matches the expected codepoint and modifiers.
+		 */
+		matchesKittySequence(data: string, expectedCodepoint: number, expectedModifier: number): boolean;
+		/**
+		 * Parse terminal input and return a normalized key identifier.
+		 * Returns key names like "escape", "ctrl+c", "shift+tab", "alt+enter".
+		 * Returns null if the input is not a recognized key sequence.
+		 * @param data Raw terminal input data.
+		 * @param kittyProtocolActive Whether Kitty disambiguation is enabled.
+		 * @returns The normalized key id or null when unrecognized.
+		 */
+		parseKey(data: string, kittyProtocolActive: boolean): string | null;
+		/**
+		 * Check if input matches a legacy escape sequence for a specific key.
+		 * @param data Raw terminal input data.
+		 * @param keyName Key identifier to match (e.g. "home").
+		 * @returns True when the sequence maps to the given key name.
+		 */
+		matchesLegacySequence(data: string, keyName: string): boolean;
+		/**
+		 * Parse a Kitty keyboard protocol sequence.
+		 * @param data Raw terminal input data.
+		 * @returns Parsed sequence info or null if not a Kitty sequence.
+		 */
+		parseKittySequence(data: string): ParsedKittyResult | null;
+		/**
+		 * Match input data against a key identifier string.
+		 * Supports: escape, tab, enter, backspace, delete, home, end, space,
+		 * arrows (up/down/left/right), ctrl+X, shift+X, alt+X, combined modifiers.
+		 * @param data Raw terminal input data.
+		 * @param keyId Key identifier string to match (e.g. "ctrl+c").
+		 * @param kittyProtocolActive Whether Kitty disambiguation is enabled.
+		 * @returns True when the input matches the key identifier.
+		 */
+		matchesKey(data: string, keyId: string, kittyProtocolActive: boolean): boolean;
+	}
+}