@nghyane/arcane 0.1.0

package/src/utils/image-convert.ts

@@ -0,0 +1,27 @@
+import { ImageFormat, PhotonImage } from "@nghyane/arcane-natives";
+
+/**
+ * Convert image to PNG format for terminal display.
+ * Kitty graphics protocol requires PNG format (f=100).
+ */
+export async function convertToPng(
+	base64Data: string,
+	mimeType: string,
+): Promise<{ data: string; mimeType: string } | null> {
+	// Already PNG, no conversion needed
+	if (mimeType === "image/png") {
+		return { data: base64Data, mimeType };
+	}
+
+	try {
+		const image = await PhotonImage.parse(new Uint8Array(Buffer.from(base64Data, "base64")));
+		const pngBuffer = await image.encode(ImageFormat.PNG, 100);
+		return {
+			data: Buffer.from(pngBuffer).toBase64(),
+			mimeType: "image/png",
+		};
+	} catch {
+		// Conversion failed
+		return null;
+	}
+}

package/src/utils/image-resize.ts

@@ -0,0 +1,236 @@
+import type { ImageContent } from "@nghyane/arcane-ai";
+import { ImageFormat, PhotonImage, SamplingFilter } from "@nghyane/arcane-natives";
+
+export interface ImageResizeOptions {
+	maxWidth?: number; // Default: 2000
+	maxHeight?: number; // Default: 2000
+	maxBytes?: number; // Default: 4.5MB (below Anthropic's 5MB limit)
+	jpegQuality?: number; // Default: 80
+}
+
+export interface ResizedImage {
+	buffer: Uint8Array;
+	mimeType: string;
+	originalWidth: number;
+	originalHeight: number;
+	width: number;
+	height: number;
+	wasResized: boolean;
+	get data(): string;
+}
+
+// 4.5MB - provides headroom below Anthropic's 5MB limit
+const DEFAULT_MAX_BYTES = 4.5 * 1024 * 1024;
+
+const DEFAULT_OPTIONS: Required<ImageResizeOptions> = {
+	maxWidth: 2000,
+	maxHeight: 2000,
+	maxBytes: DEFAULT_MAX_BYTES,
+	jpegQuality: 80,
+};
+
+/** Helper to pick the smaller of two buffers */
+function pickSmaller(
+	a: { buffer: Uint8Array; mimeType: string },
+	b: { buffer: Uint8Array; mimeType: string },
+): { buffer: Uint8Array; mimeType: string } {
+	return a.buffer.length <= b.buffer.length ? a : b;
+}
+
+/** Polyfill for Buffer.toBase64, technically since it derives from Uint8Array it should exist but Bun reasons... */
+Buffer.prototype.toBase64 = function (this: Buffer) {
+	return new Uint8Array(this.buffer, this.byteOffset, this.byteLength).toBase64();
+};
+
+/**
+ * Resize an image to fit within the specified max dimensions and file size.
+ * Returns the original image if it already fits within the limits.
+ *
+ * Uses Photon for image processing. If Photon is not available,
+ * returns the original image unchanged.
+ *
+ * Strategy for staying under maxBytes:
+ * 1. First resize to maxWidth/maxHeight
+ * 2. Try both PNG and JPEG formats, pick the smaller one
+ * 3. If still too large, try JPEG with decreasing quality
+ * 4. If still too large, progressively reduce dimensions
+ */
+export async function resizeImage(img: ImageContent, options?: ImageResizeOptions): Promise<ResizedImage> {
+	const opts = { ...DEFAULT_OPTIONS, ...options };
+	const inputBuffer = Buffer.from(img.data, "base64");
+
+	try {
+		const image = await PhotonImage.parse(inputBuffer);
+
+		const originalWidth = image.width;
+		const originalHeight = image.height;
+		const format = img.mimeType?.split("/")[1] ?? "png";
+
+		// Check if already within all limits (dimensions AND size)
+		const originalSize = inputBuffer.length;
+		if (originalWidth <= opts.maxWidth && originalHeight <= opts.maxHeight && originalSize <= opts.maxBytes) {
+			return {
+				buffer: inputBuffer,
+				mimeType: img.mimeType ?? `image/${format}`,
+				originalWidth,
+				originalHeight,
+				width: originalWidth,
+				height: originalHeight,
+				wasResized: false,
+				get data() {
+					return img.data;
+				},
+			};
+		}
+
+		// Calculate initial dimensions respecting max limits
+		let targetWidth = originalWidth;
+		let targetHeight = originalHeight;
+
+		if (targetWidth > opts.maxWidth) {
+			targetHeight = Math.round((targetHeight * opts.maxWidth) / targetWidth);
+			targetWidth = opts.maxWidth;
+		}
+		if (targetHeight > opts.maxHeight) {
+			targetWidth = Math.round((targetWidth * opts.maxHeight) / targetHeight);
+			targetHeight = opts.maxHeight;
+		}
+
+		// Helper to resize and encode in both formats, returning the smaller one
+		async function tryBothFormats(
+			width: number,
+			height: number,
+			quality: number,
+		): Promise<{ buffer: Uint8Array; mimeType: string }> {
+			const resized = await image.resize(width, height, SamplingFilter.Lanczos3);
+
+			const [pngBuffer, jpegBuffer] = await Promise.all([
+				resized.encode(ImageFormat.PNG, quality),
+				resized.encode(ImageFormat.JPEG, quality),
+			]);
+
+			return pickSmaller(
+				{ buffer: pngBuffer, mimeType: "image/png" },
+				{ buffer: jpegBuffer, mimeType: "image/jpeg" },
+			);
+		}
+
+		// Try to produce an image under maxBytes
+		const qualitySteps = [85, 70, 55, 40];
+		const scaleSteps = [1.0, 0.75, 0.5, 0.35, 0.25];
+
+		let best: { buffer: Uint8Array; mimeType: string };
+		let finalWidth = targetWidth;
+		let finalHeight = targetHeight;
+
+		// First attempt: resize to target dimensions, try both formats
+		best = await tryBothFormats(targetWidth, targetHeight, opts.jpegQuality);
+
+		if (best.buffer.length <= opts.maxBytes) {
+			return {
+				buffer: best.buffer,
+				mimeType: best.mimeType,
+				originalWidth,
+				originalHeight,
+				width: finalWidth,
+				height: finalHeight,
+				wasResized: true,
+				get data() {
+					return best.buffer.toBase64();
+				},
+			};
+		}
+
+		// Still too large - try JPEG with decreasing quality
+		for (const quality of qualitySteps) {
+			best = await tryBothFormats(targetWidth, targetHeight, quality);
+
+			if (best.buffer.length <= opts.maxBytes) {
+				return {
+					buffer: best.buffer,
+					mimeType: best.mimeType,
+					originalWidth,
+					originalHeight,
+					width: finalWidth,
+					height: finalHeight,
+					wasResized: true,
+					get data() {
+						return best.buffer.toBase64();
+					},
+				};
+			}
+		}
+
+		// Still too large - reduce dimensions progressively
+		for (const scale of scaleSteps) {
+			finalWidth = Math.round(targetWidth * scale);
+			finalHeight = Math.round(targetHeight * scale);
+
+			if (finalWidth < 100 || finalHeight < 100) {
+				break;
+			}
+
+			for (const quality of qualitySteps) {
+				best = await tryBothFormats(finalWidth, finalHeight, quality);
+
+				if (best.buffer.length <= opts.maxBytes) {
+					return {
+						buffer: best.buffer,
+						mimeType: best.mimeType,
+						originalWidth,
+						originalHeight,
+						width: finalWidth,
+						height: finalHeight,
+						wasResized: true,
+						get data() {
+							return best.buffer.toBase64();
+						},
+					};
+				}
+			}
+		}
+
+		// Last resort: return smallest version we produced
+		return {
+			buffer: best.buffer,
+			mimeType: best.mimeType,
+			originalWidth,
+			originalHeight,
+			width: finalWidth,
+			height: finalHeight,
+			wasResized: true,
+			get data() {
+				return best.buffer.toBase64();
+			},
+		};
+	} catch {
+		// Failed to load image
+		return {
+			buffer: inputBuffer,
+			mimeType: img.mimeType,
+			originalWidth: 0,
+			originalHeight: 0,
+			width: 0,
+			height: 0,
+			wasResized: false,
+			get data() {
+				return img.data;
+			},
+		};
+	}
+}
+
+/**
+ * Format a dimension note for resized images.
+ * This helps the model understand the coordinate mapping.
+ */
+export function formatDimensionNote(result: ResizedImage): string | undefined {
+	if (!result.wasResized) {
+		return undefined;
+	}
+
+	const scale = result.originalWidth / result.width;
+	return `[Image: original ${result.originalWidth}x${result.originalHeight}, displayed at ${result.width}x${
+		result.height
+	}. Multiply coordinates by ${scale.toFixed(2)} to map to original image.]`;
+}

package/src/utils/mime.ts

@@ -0,0 +1,30 @@
+import * as fs from "node:fs/promises";
+import { fileTypeFromBuffer } from "file-type";
+
+const IMAGE_MIME_TYPES = new Set(["image/jpeg", "image/png", "image/gif", "image/webp"]);
+
+const FILE_TYPE_SNIFF_BYTES = 4100;
+
+export async function detectSupportedImageMimeTypeFromFile(filePath: string): Promise<string | null> {
+	const fileHandle = await fs.open(filePath, "r");
+	try {
+		const buffer = Buffer.allocUnsafe(FILE_TYPE_SNIFF_BYTES);
+		const { bytesRead } = await fileHandle.read(buffer, 0, FILE_TYPE_SNIFF_BYTES, 0);
+		if (bytesRead === 0) {
+			return null;
+		}
+
+		const fileType = await fileTypeFromBuffer(buffer.subarray(0, bytesRead));
+		if (!fileType) {
+			return null;
+		}
+
+		if (!IMAGE_MIME_TYPES.has(fileType.mime)) {
+			return null;
+		}
+
+		return fileType.mime;
+	} finally {
+		await fileHandle.close();
+	}
+}

package/src/utils/open.ts

@@ -0,0 +1,20 @@
+/** Open a URL or file path in the default browser/application. Best-effort, never throws. */
+export function openPath(urlOrPath: string): void {
+	let cmd: string[];
+	switch (process.platform) {
+		case "darwin":
+			cmd = ["open", urlOrPath];
+			break;
+		case "win32":
+			cmd = ["rundll32", "url.dll,FileProtocolHandler", urlOrPath];
+			break;
+		default:
+			cmd = ["xdg-open", urlOrPath];
+			break;
+	}
+	try {
+		Bun.spawn(cmd, { stdout: "ignore", stderr: "ignore", windowsHide: true });
+	} catch {
+		// Best-effort: browser opening is non-critical
+	}
+}

package/src/utils/shell-snapshot.ts

@@ -0,0 +1,199 @@
+/**
+ * Shell environment snapshot for preserving user aliases, functions, and options.
+ *
+ * Creates a snapshot file that captures the user's shell environment from their
+ * .bashrc/.zshrc, which can be sourced before each command to provide a familiar
+ * shell experience.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { postmortem } from "@nghyane/arcane-utils";
+
+const cachedSnapshotPaths = new Map<string, string>();
+const SNAPSHOT_TIMEOUT_MS = 2_000;
+
+function sanitizeSnapshotEnv(env: Record<string, string | undefined>): Record<string, string | undefined> {
+	const sanitized = { ...env };
+	delete sanitized.BASH_ENV;
+	delete sanitized.ENV;
+	return sanitized;
+}
+
+/**
+ * Get the user's shell config file path.
+ */
+function getShellConfigFile(shell: string): string {
+	const home = os.homedir();
+	if (shell.includes("zsh")) return path.join(home, ".zshrc");
+	if (shell.includes("bash")) return path.join(home, ".bashrc");
+	return path.join(home, ".profile");
+}
+
+/**
+ * Generate the snapshot creation script.
+ * This script sources the user's rc file and extracts functions, aliases, and options.
+ * Matches Claude Code's snapshot generation logic.
+ */
+function generateSnapshotScript(shell: string, snapshotPath: string, rcFile: string): string {
+	const hasRcFile = fs.existsSync(rcFile);
+	const isZsh = shell.includes("zsh");
+	const commonToolsRegex =
+		"^(ls|dir|vdir|cat|head|tail|less|more|grep|egrep|fgrep|rg|find|fd|locate|sed|awk|perl|cp|mv|rm|mkdir|rmdir|touch|chmod|chown|ln|pwd|readlink|stat|cut|sort|uniq|xargs|tee|tr|basename|dirname)$";
+
+	// Escape the snapshot path for shell
+	const escapedPath = snapshotPath.replace(/'/g, "'\\''");
+
+	// Function extraction differs between bash and zsh
+	const functionScript = isZsh
+		? `
+echo "# Functions" >> "$SNAPSHOT_FILE"
+# Force autoload all functions first
+typeset -f > /dev/null 2>&1
+# Get user function names - filter system/private ones
+typeset +f 2>/dev/null | grep -vE '^(_|__)' | grep -vE '${commonToolsRegex}' | while read func; do
+   typeset -f "$func" >> "$SNAPSHOT_FILE" 2>/dev/null
+done
+`
+		: `
+echo "# Functions" >> "$SNAPSHOT_FILE"
+# Force autoload all functions first
+declare -f > /dev/null 2>&1
+# Get user function names - filter system/private ones, use base64 for special chars
+declare -F 2>/dev/null | cut -d' ' -f3 | grep -vE '^(_|__)' | grep -vE '${commonToolsRegex}' | while read func; do
+   encoded_func=$(declare -f "$func" | base64)
+   echo "eval \\"\\$(echo '$encoded_func' | base64 -d)\\" > /dev/null 2>&1" >> "$SNAPSHOT_FILE"
+done
+`;
+
+	// Shell options extraction
+	const optionsScript = isZsh
+		? `
+echo "# Shell Options" >> "$SNAPSHOT_FILE"
+setopt 2>/dev/null | sed 's/^/setopt /' | head -n 1000 >> "$SNAPSHOT_FILE"
+`
+		: `
+echo "# Shell Options" >> "$SNAPSHOT_FILE"
+shopt -p 2>/dev/null | head -n 1000 >> "$SNAPSHOT_FILE"
+set -o 2>/dev/null | awk '$2 == "on" && $1 !~ /^(onecmd|monitor|restricted)$/ {print "set -o " $1}' | head -n 1000 >> "$SNAPSHOT_FILE"
+echo "shopt -s expand_aliases" >> "$SNAPSHOT_FILE"
+`;
+
+	return `
+SNAPSHOT_FILE='${escapedPath}'
+
+# Source user's rc file if it exists
+${hasRcFile ? `source "${rcFile}" < /dev/null 2>/dev/null` : "# No user config file to source"}
+
+# Create/clear the snapshot file
+echo "# Shell snapshot - generated by arcane agent" >| "$SNAPSHOT_FILE"
+
+# Unalias everything first to avoid conflicts when sourced
+echo "unalias -a 2>/dev/null || true" >> "$SNAPSHOT_FILE"
+
+${functionScript}
+
+${optionsScript}
+
+# Export aliases (limit to 1000)
+echo "# Aliases" >> "$SNAPSHOT_FILE"
+# Filter out winpty aliases on Windows to avoid "stdin is not a tty" errors
+if [[ "$OSTYPE" == "msys" ]] || [[ "$OSTYPE" == "cygwin" ]]; then
+   alias 2>/dev/null | grep -v "='winpty " | grep -vE '^alias (${commonToolsRegex})=' | sed 's/^alias //g' | sed 's/^/alias -- /' | head -n 1000 >> "$SNAPSHOT_FILE"
+else
+   alias 2>/dev/null | grep -vE '^alias (${commonToolsRegex})=' | sed 's/^alias //g' | sed 's/^/alias -- /' | head -n 1000 >> "$SNAPSHOT_FILE"
+fi
+
+# Export PATH
+echo "export PATH='$PATH'" >> "$SNAPSHOT_FILE"
+
+# Verify snapshot was created
+if [ ! -f "$SNAPSHOT_FILE" ]; then
+   echo "Error: Snapshot file was not created" >&2
+   exit 1
+fi
+`.trim();
+}
+
+/**
+ * Create a shell snapshot, caching the result.
+ * Returns the path to the snapshot file, or null if creation failed.
+ */
+export async function getOrCreateSnapshot(
+	shell: string,
+	env: Record<string, string | undefined>,
+): Promise<string | null> {
+	const cacheKey = shell;
+	// Return cached snapshot if valid
+	const cached = cachedSnapshotPaths.get(cacheKey);
+	if (cached && fs.existsSync(cached)) {
+		return cached;
+	}
+	if (cached) {
+		cachedSnapshotPaths.delete(cacheKey);
+	}
+
+	// Skip on Windows (no .bashrc in standard location)
+	if (process.platform === "win32") {
+		return null;
+	}
+
+	const rcFile = getShellConfigFile(shell);
+
+	// Create snapshot directory
+	const snapshotDir = path.join(os.tmpdir(), "arc-shell-snapshots");
+	fs.mkdirSync(snapshotDir, { recursive: true });
+
+	// Generate unique snapshot path
+	const shellName = shell.includes("zsh") ? "zsh" : shell.includes("bash") ? "bash" : "sh";
+	const snapshotPath = path.join(snapshotDir, `snapshot-${shellName}-${crypto.randomUUID()}.sh`);
+
+	// Generate and execute snapshot script
+	const script = generateSnapshotScript(shell, snapshotPath, rcFile);
+
+	try {
+		const snapshotEnv = sanitizeSnapshotEnv(env);
+		const spawnEnv: Record<string, string> = {};
+		for (const [key, value] of Object.entries(snapshotEnv)) {
+			if (value !== undefined) {
+				spawnEnv[key] = value;
+			}
+		}
+		const child = Bun.spawn([shell, "-c", script], {
+			env: spawnEnv,
+			stdin: "ignore",
+			stdout: "ignore",
+			stderr: "ignore",
+			timeout: SNAPSHOT_TIMEOUT_MS,
+			killSignal: "SIGKILL",
+		});
+
+		await child.exited;
+		if (child.exitCode === 0 && fs.existsSync(snapshotPath)) {
+			cachedSnapshotPaths.set(cacheKey, snapshotPath);
+			return snapshotPath;
+		}
+	} catch {
+		// Snapshot creation failed, proceed without it
+	}
+
+	return null;
+}
+
+/**
+ * Get the command prefix to source the snapshot.
+ * Returns empty string if no snapshot available.
+ */
+export function getSnapshotSourceCommand(snapshotPath: string | null): string {
+	if (!snapshotPath) return "";
+	// Escape for shell
+	const escaped = snapshotPath.replace(/'/g, "'\\''");
+	return `source '${escaped}' 2>/dev/null && `;
+}
+
+postmortem.register("shell-snapshot", () => {
+	for (const snapshotPath of cachedSnapshotPaths.values()) {
+		fs.unlinkSync(snapshotPath);
+	}
+	cachedSnapshotPaths.clear();
+});

package/src/utils/timings.ts

@@ -0,0 +1,26 @@
+/**
+ * Central timing instrumentation for startup profiling.
+ * Enable with ARCANE_TIMING=1 environment variable.
+ */
+import { $env } from "@nghyane/arcane-utils";
+
+const ENABLED = $env.ARCANE_TIMING === "1";
+const timings: Array<{ label: string; ms: number }> = [];
+let lastTime = Date.now();
+
+export function time(label: string): void {
+	if (!ENABLED) return;
+	const now = Date.now();
+	timings.push({ label, ms: now - lastTime });
+	lastTime = now;
+}
+
+export function printTimings(): void {
+	if (!ENABLED || timings.length === 0) return;
+	console.error("\n--- Startup Timings ---");
+	for (const t of timings) {
+		console.error(`  ${t.label}: ${t.ms}ms`);
+	}
+	console.error(`  TOTAL: ${timings.reduce((a, b) => a + b.ms, 0)}ms`);
+	console.error("------------------------\n");
+}