@nghyane/arcane 0.1.0

package/src/commit/prompts/summary-system.md

@@ -0,0 +1,38 @@
+You are commit message specialist generating precise, informative descriptions.
+<context>
+Output: ONLY description after "{{ commit_type }}{{ scope_prefix }}:"; max {{ chars }} chars; no trailing period; no type prefix.
+</context>
+
+<instructions>
+1. Start with lowercase past-tense verb (not "{{ commit_type }}")
+2. Name specific subsystem/component affected
+3. Include WHY when clarifies intent
+4. One focused concept per message
+</instructions>
+
+<verb_reference>
+|Type|Use|
+|---|---|
+|feat|added, introduced, implemented, enabled|
+|fix|corrected, resolved, patched, addressed|
+|refactor|restructured, reorganized, migrated, simplified|
+|perf|optimized, reduced, eliminated, accelerated|
+|docs|documented, clarified, expanded|
+|build|upgraded, pinned, configured|
+|chore|cleaned, removed, renamed, organized|
+</verb_reference>
+<examples>
+feat | TLS encryption added to HTTP client for MITM prevention
+-> added TLS support to prevent man-in-the-middle attacks
+refactor | Consolidated HTTP transport into unified builder pattern
+-> migrated HTTP transport to unified builder API
+fix | Race condition in connection pool causing exhaustion under load
+-> corrected race condition causing connection pool exhaustion
+perf | Batch processing optimized to reduce memory allocations
+-> eliminated allocation overhead in batch processing
+build | Updated serde to fix CVE-2024-1234
+-> upgraded serde to 1.0.200 for CVE-2024-1234
+</examples>
+<banned_words>
+comprehensive, various, several, improved, enhanced, quickly, simply, basically, this change, this commit, now
+</banned_words>

package/src/commit/prompts/summary-user.md

@@ -0,0 +1,13 @@
+{{#if user_context}}
+<user_context>
+{{ user_context }}
+</user_context>
+{{/if}}
+
+<detail_points>
+{{ details }}
+</detail_points>
+
+<diff_stat>
+{{ stat }}
+</diff_stat>

package/src/commit/prompts/types-description.md

@@ -0,0 +1,2 @@
+Types: feat, fix, refactor, perf, docs, test, build, ci, chore, style, revert.
+Format: <type>(<scope>): <summary> with past-tense summary.

package/src/commit/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Types for the arcane commit pipeline.
+ */
+
+export type CommitType =
+	| "feat"
+	| "fix"
+	| "refactor"
+	| "perf"
+	| "docs"
+	| "test"
+	| "build"
+	| "ci"
+	| "chore"
+	| "style"
+	| "revert";
+
+export type ChangelogCategory =
+	| "Breaking Changes"
+	| "Added"
+	| "Changed"
+	| "Deprecated"
+	| "Removed"
+	| "Fixed"
+	| "Security";
+
+export interface CommitCommandArgs {
+	/** Push after commit */
+	push: boolean;
+	/** Preview without committing */
+	dryRun: boolean;
+	/** Skip changelog updates */
+	noChangelog: boolean;
+	/** Use legacy deterministic pipeline */
+	legacy?: boolean;
+	/** Additional user context for the model */
+	context?: string;
+	/** Override the model selection */
+	model?: string;
+}
+
+export interface NumstatEntry {
+	path: string;
+	additions: number;
+	deletions: number;
+}
+
+export interface ConventionalDetail {
+	text: string;
+	changelogCategory?: ChangelogCategory;
+	userVisible: boolean;
+}
+
+export interface ConventionalAnalysis {
+	type: CommitType;
+	scope: string | null;
+	details: ConventionalDetail[];
+	issueRefs: string[];
+}
+
+export interface CommitSummary {
+	summary: string;
+}
+
+export interface FileObservation {
+	file: string;
+	observations: string[];
+	additions: number;
+	deletions: number;
+}
+
+export interface FileDiff {
+	filename: string;
+	content: string;
+	additions: number;
+	deletions: number;
+	isBinary: boolean;
+}
+
+export interface DiffHunk {
+	index: number;
+	header: string;
+	oldStart: number;
+	oldLines: number;
+	newStart: number;
+	newLines: number;
+	content: string;
+}
+
+export interface FileHunks {
+	filename: string;
+	isBinary: boolean;
+	hunks: DiffHunk[];
+}
+
+export interface ChangelogBoundary {
+	changelogPath: string;
+	files: string[];
+}
+
+export interface UnreleasedSection {
+	startLine: number;
+	endLine: number;
+	entries: Record<string, string[]>;
+}
+
+export interface ChangelogGenerationResult {
+	entries: Record<string, string[]>;
+}

package/src/commit/utils/exclusions.ts

@@ -0,0 +1,42 @@
+const EXCLUDED_FILES = [
+	"Cargo.lock",
+	"package-lock.json",
+	"npm-shrinkwrap.json",
+	"yarn.lock",
+	"pnpm-lock.yaml",
+	"shrinkwrap.yaml",
+	"bun.lock",
+	"bun.lockb",
+	"deno.lock",
+	"composer.lock",
+	"Gemfile.lock",
+	"poetry.lock",
+	"Pipfile.lock",
+	"pdm.lock",
+	"uv.lock",
+	"go.sum",
+	"flake.lock",
+	"pubspec.lock",
+	"Podfile.lock",
+	"Packages.resolved",
+	"mix.lock",
+	"packages.lock.json",
+	"config.yml.lock",
+	"config.yaml.lock",
+	"settings.yml.lock",
+	"settings.yaml.lock",
+];
+
+const EXCLUDED_SUFFIXES = [".lock.yml", ".lock.yaml", "-lock.yml", "-lock.yaml"];
+
+export function isExcludedFile(path: string): boolean {
+	const lower = path.toLowerCase();
+	if (EXCLUDED_FILES.some(name => lower.endsWith(name.toLowerCase()))) {
+		return true;
+	}
+	return EXCLUDED_SUFFIXES.some(suffix => lower.endsWith(suffix));
+}
+
+export function filterExcludedFiles<T extends { filename: string }>(files: T[]): T[] {
+	return files.filter(file => !isExcludedFile(file.filename));
+}

package/src/config/file-lock.ts

@@ -0,0 +1,121 @@
+import * as fs from "node:fs/promises";
+import { isEnoent } from "@nghyane/arcane-utils";
+
+export interface FileLockOptions {
+	staleMs?: number;
+	retries?: number;
+	retryDelayMs?: number;
+}
+
+const DEFAULT_OPTIONS: Required<FileLockOptions> = {
+	staleMs: 10_000,
+	retries: 50,
+	retryDelayMs: 100,
+};
+
+interface LockInfo {
+	pid: number;
+	timestamp: number;
+}
+
+function getLockPath(filePath: string): string {
+	return `${filePath}.lock`;
+}
+
+async function writeLockInfo(lockPath: string): Promise<void> {
+	const info: LockInfo = { pid: process.pid, timestamp: Date.now() };
+	await Bun.write(`${lockPath}/info`, JSON.stringify(info));
+}
+
+async function readLockInfo(lockPath: string): Promise<LockInfo | null> {
+	try {
+		const content = await fs.readFile(`${lockPath}/info`, "utf-8");
+		return JSON.parse(content) as LockInfo;
+	} catch {
+		return null;
+	}
+}
+
+function isProcessAlive(pid: number): boolean {
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function isLockStale(lockPath: string, staleMs: number): Promise<boolean> {
+	const info = await readLockInfo(lockPath);
+	if (!info) return true;
+
+	if (!isProcessAlive(info.pid)) return true;
+
+	if (Date.now() - info.timestamp > staleMs) return true;
+
+	return false;
+}
+
+async function tryAcquireLock(lockPath: string): Promise<boolean> {
+	try {
+		await fs.mkdir(lockPath);
+		await writeLockInfo(lockPath);
+		return true;
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+			return false;
+		}
+		throw error;
+	}
+}
+
+async function releaseLock(lockPath: string): Promise<void> {
+	try {
+		await fs.rm(lockPath, { recursive: true });
+	} catch {
+		// Ignore errors on release
+	}
+}
+
+async function lockExists(lockPath: string): Promise<boolean> {
+	try {
+		await fs.stat(lockPath);
+		return true;
+	} catch (err) {
+		if (isEnoent(err)) return false;
+		throw err;
+	}
+}
+
+async function acquireLock(filePath: string, options: FileLockOptions = {}): Promise<() => Promise<void>> {
+	const opts = { ...DEFAULT_OPTIONS, ...options };
+	const lockPath = getLockPath(filePath);
+
+	for (let attempt = 0; attempt < opts.retries; attempt++) {
+		if (await tryAcquireLock(lockPath)) {
+			return () => releaseLock(lockPath);
+		}
+
+		if ((await lockExists(lockPath)) && (await isLockStale(lockPath, opts.staleMs))) {
+			await releaseLock(lockPath);
+			continue;
+		}
+
+		await Bun.sleep(opts.retryDelayMs);
+	}
+
+	throw new Error(`Failed to acquire lock for ${filePath} after ${opts.retries} attempts`);
+}
+
+export async function withFileLock<T>(
+	filePath: string,
+	fn: () => Promise<T>,
+	options: FileLockOptions = {},
+): Promise<T> {
+	const release = await acquireLock(filePath, options);
+	try {
+		return await fn();
+	} finally {
+		await release();
+	}
+}

package/src/config/keybindings.ts

@@ -0,0 +1,280 @@
+import * as path from "node:path";
+import {
+	DEFAULT_EDITOR_KEYBINDINGS,
+	type EditorAction,
+	type EditorKeybindingsConfig,
+	EditorKeybindingsManager,
+	type KeyId,
+	matchesKey,
+	setEditorKeybindings,
+} from "@nghyane/arcane-tui";
+import { isEnoent, logger } from "@nghyane/arcane-utils";
+import { getAgentDir } from "@nghyane/arcane-utils/dirs";
+
+/**
+ * Application-level actions (coding agent specific).
+ */
+export type AppAction =
+	| "interrupt"
+	| "clear"
+	| "exit"
+	| "suspend"
+	| "cycleThinkingLevel"
+	| "cycleModelForward"
+	| "cycleModelBackward"
+	| "selectModel"
+	| "expandTools"
+	| "toggleThinking"
+	| "toggleSessionNamedFilter"
+	| "externalEditor"
+	| "historySearch"
+	| "followUp"
+	| "dequeue"
+	| "pasteImage"
+	| "newSession"
+	| "tree"
+	| "fork"
+	| "resume"
+	| "toggleSTT";
+
+/**
+ * All configurable actions.
+ */
+export type KeyAction = AppAction | EditorAction;
+
+/**
+ * Full keybindings configuration (app + editor actions).
+ */
+export type KeybindingsConfig = {
+	[K in KeyAction]?: KeyId | KeyId[];
+};
+
+/**
+ * Default application keybindings.
+ */
+export const DEFAULT_APP_KEYBINDINGS: Record<AppAction, KeyId | KeyId[]> = {
+	interrupt: "escape",
+	clear: "ctrl+c",
+	exit: "ctrl+d",
+	suspend: "ctrl+z",
+	cycleThinkingLevel: "shift+tab",
+	cycleModelForward: "ctrl+p",
+	cycleModelBackward: "shift+ctrl+p",
+	selectModel: "ctrl+l",
+	historySearch: "ctrl+r",
+	expandTools: "ctrl+o",
+	toggleThinking: "ctrl+t",
+	toggleSessionNamedFilter: "ctrl+n",
+	externalEditor: "ctrl+g",
+	followUp: "ctrl+enter",
+	dequeue: "alt+up",
+	pasteImage: "ctrl+v",
+	newSession: [],
+	tree: [],
+	fork: [],
+	resume: [],
+	toggleSTT: "alt+h",
+};
+
+/**
+ * All default keybindings (app + editor).
+ */
+export const DEFAULT_KEYBINDINGS: Required<KeybindingsConfig> = {
+	...DEFAULT_EDITOR_KEYBINDINGS,
+	...DEFAULT_APP_KEYBINDINGS,
+};
+
+// App actions list for type checking
+const APP_ACTIONS: AppAction[] = [
+	"interrupt",
+	"clear",
+	"exit",
+	"suspend",
+	"cycleThinkingLevel",
+	"cycleModelForward",
+	"cycleModelBackward",
+	"selectModel",
+	"historySearch",
+	"expandTools",
+	"toggleThinking",
+	"toggleSessionNamedFilter",
+	"externalEditor",
+	"followUp",
+	"dequeue",
+	"pasteImage",
+	"newSession",
+	"tree",
+	"fork",
+	"resume",
+	"toggleSTT",
+];
+
+function isAppAction(action: string): action is AppAction {
+	return APP_ACTIONS.includes(action as AppAction);
+}
+
+/**
+ * Key hint formatting utilities for UI labels.
+ */
+const MODIFIER_LABELS: Record<string, string> = {
+	ctrl: "Ctrl",
+	shift: "Shift",
+	alt: "Alt",
+};
+
+const KEY_LABELS: Record<string, string> = {
+	esc: "Esc",
+	escape: "Esc",
+	enter: "Enter",
+	return: "Enter",
+	space: "Space",
+	tab: "Tab",
+	backspace: "Backspace",
+	delete: "Delete",
+	home: "Home",
+	end: "End",
+	pageup: "PgUp",
+	pagedown: "PgDn",
+	up: "Up",
+	down: "Down",
+	left: "Left",
+	right: "Right",
+};
+
+const normalizeKeyId = (key: KeyId): KeyId => key.toLowerCase() as KeyId;
+
+function formatKeyPart(part: string): string {
+	const lower = part.toLowerCase();
+	const modifier = MODIFIER_LABELS[lower];
+	if (modifier) return modifier;
+	const label = KEY_LABELS[lower];
+	if (label) return label;
+	if (part.length === 1) return part.toUpperCase();
+	return `${part.charAt(0).toUpperCase()}${part.slice(1)}`;
+}
+
+export function formatKeyHint(key: KeyId): string {
+	return key.split("+").map(formatKeyPart).join("+");
+}
+
+export function formatKeyHints(keys: KeyId | KeyId[]): string {
+	const list = Array.isArray(keys) ? keys : [keys];
+	return list.map(formatKeyHint).join("/");
+}
+
+/**
+ * Manages all keybindings (app + editor).
+ */
+export class KeybindingsManager {
+	#appActionToKeys: Map<AppAction, KeyId[]>;
+
+	private constructor(private readonly config: KeybindingsConfig) {
+		this.#appActionToKeys = new Map();
+		this.#buildMaps();
+	}
+
+	/**
+	 * Create from config file and set up editor keybindings.
+	 */
+	static async create(agentDir: string = getAgentDir()): Promise<KeybindingsManager> {
+		const configPath = path.join(agentDir, "keybindings.json");
+		const config = await KeybindingsManager.#loadFromFile(configPath);
+		const manager = new KeybindingsManager(config);
+
+		// Set up editor keybindings globally
+		const editorConfig: EditorKeybindingsConfig = {};
+		for (const [action, keys] of Object.entries(config)) {
+			if (!isAppAction(action)) {
+				editorConfig[action as EditorAction] = keys;
+			}
+		}
+		setEditorKeybindings(new EditorKeybindingsManager(editorConfig));
+
+		return manager;
+	}
+
+	/**
+	 * Create in-memory.
+	 */
+	static inMemory(config: KeybindingsConfig = {}): KeybindingsManager {
+		return new KeybindingsManager(config);
+	}
+
+	static async #loadFromFile(path: string): Promise<KeybindingsConfig> {
+		try {
+			return await Bun.file(path).json();
+		} catch (error) {
+			if (isEnoent(error)) return {};
+			logger.warn("Failed to parse keybindings config", { path, error: String(error) });
+			return {};
+		}
+	}
+
+	#buildMaps(): void {
+		this.#appActionToKeys.clear();
+
+		// Set defaults for app actions
+		for (const [action, keys] of Object.entries(DEFAULT_APP_KEYBINDINGS)) {
+			const keyArray = Array.isArray(keys) ? keys : [keys];
+			this.#appActionToKeys.set(
+				action as AppAction,
+				keyArray.map(key => normalizeKeyId(key as KeyId)),
+			);
+		}
+
+		// Override with user config (app actions only)
+		for (const [action, keys] of Object.entries(this.config)) {
+			if (keys === undefined || !isAppAction(action)) continue;
+			const keyArray = Array.isArray(keys) ? keys : [keys];
+			this.#appActionToKeys.set(
+				action,
+				keyArray.map(key => normalizeKeyId(key as KeyId)),
+			);
+		}
+	}
+
+	/**
+	 * Check if input matches an app action.
+	 */
+	matches(data: string, action: AppAction): boolean {
+		const keys = this.#appActionToKeys.get(action);
+		if (!keys) return false;
+		for (const key of keys) {
+			if (matchesKey(data, key)) return true;
+		}
+		return false;
+	}
+
+	/**
+	 * Get keys bound to an app action.
+	 */
+	getKeys(action: AppAction): KeyId[] {
+		return this.#appActionToKeys.get(action) ?? [];
+	}
+
+	/**
+	 * Get display string for an action.
+	 */
+	getDisplayString(action: AppAction): string {
+		const keys = this.getKeys(action);
+		if (keys.length === 0) return "";
+		if (keys.length === 1) return keys[0]!;
+		return keys.join("/");
+	}
+
+	/**
+	 * Get the full effective config.
+	 */
+	getEffectiveConfig(): Required<KeybindingsConfig> {
+		const result = { ...DEFAULT_KEYBINDINGS };
+		for (const [action, keys] of Object.entries(this.config)) {
+			if (keys !== undefined) {
+				(result as KeybindingsConfig)[action as KeyAction] = keys;
+			}
+		}
+		return result;
+	}
+}
+
+// Re-export for convenience
+export type { EditorAction, KeyId };