@nghyane/arcane 0.1.0

package/src/tui/output-block.ts

@@ -0,0 +1,144 @@
+/**
+ * Bordered output container with optional header and sections.
+ */
+import { padding, visibleWidth } from "@nghyane/arcane-tui";
+import type { Theme } from "../modes/theme/theme";
+import type { State } from "./types";
+import type { RenderCache } from "./utils";
+import { getStateBgColor, Hasher, padToWidth, truncateToWidth } from "./utils";
+
+export interface OutputBlockOptions {
+	header?: string;
+	headerMeta?: string;
+	state?: State;
+	sections?: Array<{ label?: string; lines: string[] }>;
+	width: number;
+	applyBg?: boolean;
+}
+
+export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): string[] {
+	const { header, headerMeta, state, sections = [], width, applyBg = true } = options;
+	const h = theme.boxSharp.horizontal;
+	const v = theme.boxSharp.vertical;
+	const cap = h.repeat(3);
+	const lineWidth = Math.max(0, width);
+	// Border colors: running/pending use accent, success uses dim (gray), error/warning keep their colors
+	const borderColor: "error" | "warning" | "accent" | "dim" =
+		state === "error"
+			? "error"
+			: state === "warning"
+				? "warning"
+				: state === "running" || state === "pending"
+					? "accent"
+					: "dim";
+	const border = (text: string) => theme.fg(borderColor, text);
+	const bgFn = (() => {
+		if (!state || !applyBg) return undefined;
+		const bgAnsi = theme.getBgAnsi(getStateBgColor(state));
+		// Keep block background stable even if inner content contains SGR resets (e.g. "\x1b[0m"),
+		// which would otherwise clear the outer background mid-line.
+		return (text: string) => {
+			const stabilized = text
+				.replace(/\x1b\[(?:0)?m/g, m => `${m}${bgAnsi}`)
+				.replace(/\x1b\[49m/g, m => `${m}${bgAnsi}`);
+			return `${bgAnsi}${stabilized}\x1b[49m`;
+		};
+	})();
+
+	const buildBarLine = (leftChar: string, rightChar: string, label?: string, meta?: string): string => {
+		const left = border(`${leftChar}${cap}`);
+		const right = border(rightChar);
+		if (lineWidth <= 0) return left + right;
+		const labelText = [label, meta].filter(Boolean).join(theme.sep.dot);
+		const rawLabel = labelText ? ` ${labelText} ` : " ";
+		const leftWidth = visibleWidth(left);
+		const rightWidth = visibleWidth(right);
+		const maxLabelWidth = Math.max(0, lineWidth - leftWidth - rightWidth);
+		const trimmedLabel = truncateToWidth(rawLabel, maxLabelWidth);
+		const labelWidth = visibleWidth(trimmedLabel);
+		const fillCount = Math.max(0, lineWidth - leftWidth - labelWidth - rightWidth);
+		return `${left}${trimmedLabel}${border(h.repeat(fillCount))}${right}`;
+	};
+
+	const contentPrefix = border(`${v} `);
+	const contentSuffix = border(v);
+	const contentWidth = Math.max(0, lineWidth - visibleWidth(contentPrefix) - visibleWidth(contentSuffix));
+	const lines: string[] = [];
+
+	lines.push(
+		padToWidth(buildBarLine(theme.boxSharp.topLeft, theme.boxSharp.topRight, header, headerMeta), lineWidth, bgFn),
+	);
+
+	const hasSections = sections.length > 0;
+	const normalizedSections = hasSections ? sections : [{ lines: [] }];
+
+	for (let i = 0; i < normalizedSections.length; i++) {
+		const section = normalizedSections[i];
+		if (section.label) {
+			lines.push(
+				padToWidth(buildBarLine(theme.boxSharp.teeRight, theme.boxSharp.teeLeft, section.label), lineWidth, bgFn),
+			);
+		}
+		const allLines = section.lines.flatMap(l => l.split("\n"));
+		for (const line of allLines) {
+			// Sections may receive content that was already padded to terminal width
+			// (e.g. from Text.render()). Trailing spaces would trigger truncateToWidth()
+			// to append an ellipsis even when the *semantic* content fits.
+			const text = truncateToWidth(line.trimEnd(), contentWidth);
+			const innerPadding = padding(Math.max(0, contentWidth - visibleWidth(text)));
+			const fullLine = `${contentPrefix}${text}${innerPadding}${contentSuffix}`;
+			lines.push(padToWidth(fullLine, lineWidth, bgFn));
+		}
+	}
+
+	const bottomLeft = border(`${theme.boxSharp.bottomLeft}${cap}`);
+	const bottomRight = border(theme.boxSharp.bottomRight);
+	const bottomFillCount = Math.max(0, lineWidth - visibleWidth(bottomLeft) - visibleWidth(bottomRight));
+	const bottomLine = `${bottomLeft}${border(h.repeat(bottomFillCount))}${bottomRight}`;
+	lines.push(padToWidth(bottomLine, lineWidth, bgFn));
+
+	return lines;
+}
+
+/**
+ * Cached wrapper around `renderOutputBlock`.
+ *
+ * Since output blocks are re-rendered on every frame (via `render(width)` closures),
+ * but their content rarely changes, this cache avoids redundant `visibleWidth()` and
+ * `padding()` computations on ~99% of render calls.
+ */
+export class CachedOutputBlock {
+	#cache?: RenderCache;
+
+	/** Render with caching. Returns cached result if options haven't changed. */
+	render(options: OutputBlockOptions, theme: Theme): string[] {
+		const key = this.#buildKey(options);
+		if (this.#cache?.key === key) return this.#cache.lines;
+		const lines = renderOutputBlock(options, theme);
+		this.#cache = { key, lines };
+		return lines;
+	}
+
+	/** Invalidate the cache, forcing a rebuild on next render. */
+	invalidate(): void {
+		this.#cache = undefined;
+	}
+
+	#buildKey(options: OutputBlockOptions): bigint {
+		const h = new Hasher();
+		h.u32(options.width);
+		h.optional(options.header);
+		h.optional(options.headerMeta);
+		h.optional(options.state);
+		h.bool(options.applyBg ?? true);
+		if (options.sections) {
+			for (const s of options.sections) {
+				h.optional(s.label);
+				for (const line of s.lines) {
+					h.str(line);
+				}
+			}
+		}
+		return h.digest();
+	}
+}

package/src/tui/status-line.ts

@@ -0,0 +1,39 @@
+/**
+ * Standardized status header rendering for tool output.
+ */
+import type { Theme, ThemeColor } from "../modes/theme/theme";
+import type { IconType } from "./types";
+import { getStateIcon } from "./utils";
+
+export interface StatusLineOptions {
+	icon?: IconType;
+	spinnerFrame?: number;
+	title: string;
+	titleColor?: ThemeColor;
+	description?: string;
+	badge?: { label: string; color: ThemeColor };
+	meta?: string[];
+}
+
+export function renderStatusLine(options: StatusLineOptions, theme: Theme): string {
+	const icon = options.icon ? getStateIcon(options.icon, theme, options.spinnerFrame) : "";
+	const titleColor = options.titleColor ?? "accent";
+	const title = theme.fg(titleColor, options.title);
+	let line = icon ? `${icon} ${title}` : title;
+
+	if (options.description) {
+		line += `: ${theme.fg("muted", options.description)}`;
+	}
+
+	if (options.badge) {
+		const { label, color } = options.badge;
+		line += ` ${theme.fg(color, `${theme.format.bracketLeft}${label}${theme.format.bracketRight}`)}`;
+	}
+
+	const meta = options.meta?.filter(value => value.trim().length > 0) ?? [];
+	if (meta.length > 0) {
+		line += ` ${theme.fg("dim", meta.join(theme.sep.dot))}`;
+	}
+
+	return line;
+}

package/src/tui/tree-list.ts

@@ -0,0 +1,53 @@
+/**
+ * Hierarchical tree list rendering helper.
+ */
+import type { Theme } from "../modes/theme/theme";
+import { formatMoreItems, replaceTabs } from "../tools/render-utils";
+import type { TreeContext } from "./types";
+import { getTreeBranch, getTreeContinuePrefix } from "./utils";
+
+export interface TreeListOptions<T> {
+	items: T[];
+	expanded?: boolean;
+	maxCollapsed?: number;
+	itemType?: string;
+	renderItem: (item: T, context: TreeContext) => string | string[];
+}
+
+export function renderTreeList<T>(options: TreeListOptions<T>, theme: Theme): string[] {
+	const { items, expanded = false, maxCollapsed = 8, itemType = "item", renderItem } = options;
+	const lines: string[] = [];
+	const maxItems = expanded ? items.length : Math.min(items.length, maxCollapsed);
+
+	for (let i = 0; i < maxItems; i++) {
+		const isLast = i === maxItems - 1 && (expanded || items.length <= maxCollapsed);
+		const branch = getTreeBranch(isLast, theme);
+		const prefix = `${theme.fg("dim", branch)} `;
+		const continuePrefix = `${theme.fg("dim", getTreeContinuePrefix(isLast, theme))}`;
+		const context: TreeContext = {
+			index: i,
+			isLast,
+			depth: 0,
+			theme,
+			prefix,
+			continuePrefix,
+		};
+		const rendered = renderItem(items[i], context);
+		if (Array.isArray(rendered)) {
+			if (rendered.length === 0) continue;
+			lines.push(`${prefix}${replaceTabs(rendered[0])}`);
+			for (let j = 1; j < rendered.length; j++) {
+				lines.push(`${continuePrefix}${replaceTabs(rendered[j])}`);
+			}
+		} else {
+			lines.push(`${prefix}${replaceTabs(rendered)}`);
+		}
+	}
+
+	if (!expanded && items.length > maxItems) {
+		const remaining = items.length - maxItems;
+		lines.push(`${theme.fg("dim", theme.tree.last)} ${theme.fg("muted", formatMoreItems(remaining, itemType))}`);
+	}
+
+	return lines;
+}

package/src/tui/types.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared types for TUI rendering components.
+ */
+import type { Theme } from "../modes/theme/theme";
+
+export type State = "pending" | "running" | "success" | "error" | "warning";
+export type IconType = "success" | "error" | "running" | "pending" | "warning" | "info";
+
+export interface TreeContext {
+	index: number;
+	isLast: boolean;
+	depth: number;
+	theme: Theme;
+	prefix: string;
+	continuePrefix: string;
+}

package/src/tui/utils.ts

@@ -0,0 +1,116 @@
+/**
+ * Shared helpers for tool-rendered UI components.
+ */
+import { padding, visibleWidth } from "@nghyane/arcane-tui";
+import type { Theme, ThemeBg } from "../modes/theme/theme";
+import type { IconType, State } from "./types";
+
+export { Ellipsis, truncateToWidth } from "@nghyane/arcane-tui";
+
+/** Cached typed-array scratch space for hashing non-string primitives. */
+const hashBuf = new ArrayBuffer(8);
+const hashView = new DataView(hashBuf);
+const hashBytes1 = new Uint8Array(hashBuf, 0, 1);
+const hashBytes4 = new Uint8Array(hashBuf, 0, 4);
+const hashBytes8 = new Uint8Array(hashBuf, 0, 8);
+
+/**
+ * Incremental xxHash64 key builder.
+ *
+ * Chains `Bun.hash.xxHash64` calls via seeding — each fed value
+ * mixes into the running hash without intermediate string allocations.
+ * Accepts strings, numbers (u32), booleans, bigints, and `undefined`/`null`
+ * (hashed as a sentinel byte) natively.
+ */
+export class Hasher {
+	#h = 0n;
+
+	/** Feed a string. */
+	str(s: string): this {
+		hashView.setUint32(0, s.length);
+		this.#h = Bun.hash.xxHash64(hashBytes4, this.#h);
+		this.#h = Bun.hash.xxHash64(s, this.#h);
+		return this;
+	}
+
+	/** Feed an unsigned 32-bit integer. */
+	u32(n: number): this {
+		hashView.setUint32(0, n);
+		this.#h = Bun.hash.xxHash64(hashBytes4, this.#h);
+		return this;
+	}
+
+	/** Feed a 64-bit bigint. */
+	u64(n: bigint): this {
+		hashView.setBigUint64(0, n);
+		this.#h = Bun.hash.xxHash64(hashBytes8, this.#h);
+		return this;
+	}
+
+	/** Feed a boolean (single byte: 1 = true, 0 = false). */
+	bool(b: boolean): this {
+		hashView.setUint8(0, b ? 1 : 0);
+		this.#h = Bun.hash.xxHash64(hashBytes1, this.#h);
+		return this;
+	}
+
+	/** Feed a value that may be `undefined` or `null` (hashed as a 0xFF sentinel byte). */
+	optional(v: string | undefined | null): this {
+		if (v == null) {
+			hashView.setUint8(0, 0xff);
+			this.#h = Bun.hash.xxHash64(hashBytes1, this.#h);
+		} else {
+			this.#h = Bun.hash.xxHash64(v, this.#h);
+		}
+		return this;
+	}
+
+	/** Return the final hash digest. */
+	digest(): bigint {
+		return this.#h;
+	}
+}
+
+/** Render-cache entry used by tool renderers. */
+export interface RenderCache {
+	key: bigint;
+	lines: string[];
+}
+
+export function buildTreePrefix(ancestors: boolean[], theme: Theme): string {
+	return ancestors.map(hasNext => (hasNext ? `${theme.tree.vertical}  ` : "   ")).join("");
+}
+
+export function getTreeBranch(isLast: boolean, theme: Theme): string {
+	return isLast ? theme.tree.last : theme.tree.branch;
+}
+
+export function getTreeContinuePrefix(isLast: boolean, theme: Theme): string {
+	return isLast ? "   " : `${theme.tree.vertical}  `;
+}
+
+export function padToWidth(text: string, width: number, bgFn?: (s: string) => string): string {
+	if (width <= 0) return bgFn ? bgFn(text) : text;
+	const paddingNeeded = Math.max(0, width - visibleWidth(text));
+	const padded = paddingNeeded > 0 ? text + padding(paddingNeeded) : text;
+	return bgFn ? bgFn(padded) : padded;
+}
+
+export function getStateBgColor(state: State): ThemeBg {
+	if (state === "success") return "toolSuccessBg";
+	if (state === "error") return "toolErrorBg";
+	return "toolPendingBg";
+}
+
+export function getStateIcon(icon: IconType, theme: Theme, spinnerFrame?: number): string {
+	if (icon === "success") return theme.styledSymbol("status.success", "success");
+	if (icon === "error") return theme.styledSymbol("status.error", "error");
+	if (icon === "warning") return theme.styledSymbol("status.warning", "warning");
+	if (icon === "info") return theme.styledSymbol("status.info", "accent");
+	if (icon === "pending") return theme.styledSymbol("status.pending", "accent");
+	if (spinnerFrame !== undefined) {
+		const frames = theme.spinnerFrames;
+		return frames[spinnerFrame % frames.length];
+	}
+	return theme.styledSymbol("status.running", "accent");
+}

package/src/utils/changelog.ts

@@ -0,0 +1,98 @@
+import { isEnoent, logger } from "@nghyane/arcane-utils";
+
+export interface ChangelogEntry {
+	major: number;
+	minor: number;
+	patch: number;
+	content: string;
+}
+
+/**
+ * Parse changelog entries from CHANGELOG.md
+ * Scans for ## lines and collects content until next ## or EOF
+ */
+export async function parseChangelog(changelogPath: string): Promise<ChangelogEntry[]> {
+	try {
+		const content = await Bun.file(changelogPath).text();
+		const lines = content.split("\n");
+		const entries: ChangelogEntry[] = [];
+
+		let currentLines: string[] = [];
+		let currentVersion: { major: number; minor: number; patch: number } | null = null;
+
+		for (const line of lines) {
+			// Check if this is a version header (## [x.y.z] ...)
+			if (line.startsWith("## ")) {
+				// Save previous entry if exists
+				if (currentVersion && currentLines.length > 0) {
+					entries.push({
+						...currentVersion,
+						content: currentLines.join("\n").trim(),
+					});
+				}
+
+				// Try to parse version from this line
+				const versionMatch = line.match(/##\s+\[?(\d+)\.(\d+)\.(\d+)\]?/);
+				if (versionMatch) {
+					currentVersion = {
+						major: Number.parseInt(versionMatch[1], 10),
+						minor: Number.parseInt(versionMatch[2], 10),
+						patch: Number.parseInt(versionMatch[3], 10),
+					};
+					currentLines = [line];
+				} else {
+					// Reset if we can't parse version
+					currentVersion = null;
+					currentLines = [];
+				}
+			} else if (currentVersion) {
+				// Collect lines for current version
+				currentLines.push(line);
+			}
+		}
+
+		// Save last entry
+		if (currentVersion && currentLines.length > 0) {
+			entries.push({
+				...currentVersion,
+				content: currentLines.join("\n").trim(),
+			});
+		}
+
+		return entries;
+	} catch (error) {
+		if (isEnoent(error)) {
+			return [];
+		}
+		logger.error(`Warning: Could not parse changelog: ${error}`);
+		return [];
+	}
+}
+
+/**
+ * Compare versions. Returns: -1 if v1 < v2, 0 if v1 === v2, 1 if v1 > v2
+ */
+export function compareVersions(v1: ChangelogEntry, v2: ChangelogEntry): number {
+	if (v1.major !== v2.major) return v1.major - v2.major;
+	if (v1.minor !== v2.minor) return v1.minor - v2.minor;
+	return v1.patch - v2.patch;
+}
+
+/**
+ * Get entries newer than lastVersion
+ */
+export function getNewEntries(entries: ChangelogEntry[], lastVersion: string): ChangelogEntry[] {
+	// Parse lastVersion
+	const parts = lastVersion.split(".").map(Number);
+	const last: ChangelogEntry = {
+		major: parts[0] || 0,
+		minor: parts[1] || 0,
+		patch: parts[2] || 0,
+		content: "",
+	};
+
+	return entries.filter(entry => compareVersions(entry, last) > 0);
+}
+
+// Re-export getChangelogPath from paths.ts for convenience
+export { getChangelogPath } from "../config";

package/src/utils/event-bus.ts

@@ -0,0 +1,33 @@
+import { logger } from "@nghyane/arcane-utils";
+
+export class EventBus {
+	readonly #listeners = new Map<string, Set<(data: unknown) => void>>();
+
+	emit(channel: string, data: unknown): void {
+		const handlers = this.#listeners.get(channel);
+		if (handlers) {
+			for (const handler of handlers) {
+				handler(data);
+			}
+		}
+	}
+
+	on(channel: string, handler: (data: unknown) => void): () => void {
+		if (!this.#listeners.has(channel)) {
+			this.#listeners.set(channel, new Set());
+		}
+		const safeHandler = async (data: unknown) => {
+			try {
+				await handler(data);
+			} catch (err) {
+				logger.error("Event handler error", { channel, error: String(err) });
+			}
+		};
+		this.#listeners.get(channel)!.add(safeHandler);
+		return () => this.#listeners.get(channel)?.delete(safeHandler);
+	}
+
+	clear(): void {
+		this.#listeners.clear();
+	}
+}

package/src/utils/external-editor.ts

@@ -0,0 +1,59 @@
+/**
+ * Utilities for launching an external text editor ($VISUAL / $EDITOR).
+ */
+import { spawn } from "node:child_process";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { $env, Snowflake } from "@nghyane/arcane-utils";
+
+/** Returns the user's preferred editor command, or undefined if not configured. */
+export function getEditorCommand(): string | undefined {
+	return $env.VISUAL || $env.EDITOR || undefined;
+}
+
+export interface OpenInEditorOptions {
+	/** File extension for the temp file (default: ".md"). */
+	extension?: string;
+	/** Custom stdio configuration (default: all "inherit"). */
+	stdio?: [number | "inherit", number | "inherit", number | "inherit"];
+}
+
+/**
+ * Opens `content` in the user's external editor and returns the edited text.
+ * Returns `null` if the editor exits with a non-zero code.
+ *
+ * The caller is responsible for stopping/starting the TUI around this call.
+ */
+export async function openInEditor(
+	editorCmd: string,
+	content: string,
+	options?: OpenInEditorOptions,
+): Promise<string | null> {
+	const ext = options?.extension ?? ".md";
+	const tmpFile = path.join(os.tmpdir(), `arc-editor-${Snowflake.next()}${ext}`);
+
+	try {
+		await Bun.write(tmpFile, content);
+
+		const [editor, ...editorArgs] = editorCmd.split(" ");
+		const stdio = options?.stdio ?? ["inherit", "inherit", "inherit"];
+
+		const child = spawn(editor, [...editorArgs, tmpFile], { stdio });
+		const exitCode = await new Promise<number>((resolve, reject) => {
+			child.once("exit", (code, signal) => resolve(code ?? (signal ? -1 : 0)));
+			child.once("error", error => reject(error));
+		});
+
+		if (exitCode === 0) {
+			return (await Bun.file(tmpFile).text()).replace(/\n$/, "");
+		}
+		return null;
+	} finally {
+		try {
+			await fs.rm(tmpFile, { force: true });
+		} catch {
+			// Ignore cleanup errors
+		}
+	}
+}

package/src/utils/file-display-mode.ts

@@ -0,0 +1,36 @@
+/**
+ * Resolve line-display mode for file-like outputs (read, grep, @file mentions).
+ */
+
+export interface FileDisplayMode {
+	lineNumbers: boolean;
+	hashLines: boolean;
+}
+
+/** Session-like object providing settings and tool availability for display mode resolution. */
+export interface FileDisplayModeSession {
+	/** Whether the edit tool is available. Hashlines are suppressed without it. */
+	hasEditTool?: boolean;
+	settings: {
+		get(key: "readLineNumbers" | "readHashLines" | "edit.mode"): unknown;
+	};
+}
+
+/**
+ * Computes effective line display mode from session settings/env.
+ * Hashline mode takes precedence and implies line-addressed output everywhere.
+ * Hashlines are suppressed when the edit tool is not available (e.g. explore agents).
+ */
+export function resolveFileDisplayMode(session: FileDisplayModeSession): FileDisplayMode {
+	const { settings } = session;
+	const hasEditTool = session.hasEditTool ?? true;
+	const hashLines =
+		hasEditTool &&
+		(settings.get("readHashLines") === true ||
+			settings.get("edit.mode") === "hashline" ||
+			Bun.env.ARCANE_EDIT_VARIANT === "hashline");
+	return {
+		hashLines,
+		lineNumbers: hashLines || settings.get("readLineNumbers") === true,
+	};
+}