@nghyane/arcane 0.1.0

package/src/commands/ssh.ts

@@ -0,0 +1,60 @@
+/**
+ * Manage SSH host configurations.
+ */
+import { Args, Command, Flags } from "@nghyane/arcane-utils/cli";
+import { runSSHCommand, type SSHAction, type SSHCommandArgs } from "../cli/ssh-cli";
+import { initTheme } from "../modes/theme/theme";
+
+const ACTIONS: SSHAction[] = ["add", "remove", "list"];
+
+export default class SSH extends Command {
+	static description = "Manage SSH host configurations";
+
+	static args = {
+		action: Args.string({
+			description: "SSH action",
+			required: false,
+			options: ACTIONS,
+		}),
+		targets: Args.string({
+			description: "Host name or arguments",
+			required: false,
+			multiple: true,
+		}),
+	};
+
+	static flags = {
+		json: Flags.boolean({ description: "Output JSON" }),
+		host: Flags.string({ description: "Host address" }),
+		user: Flags.string({ description: "Username" }),
+		port: Flags.string({ description: "Port number" }),
+		key: Flags.string({ description: "Identity key path" }),
+		desc: Flags.string({ description: "Host description" }),
+		compat: Flags.boolean({ description: "Enable compatibility mode" }),
+		scope: Flags.string({ description: "Config scope (project|user)", options: ["project", "user"] }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(SSH);
+		const action = (args.action ?? "list") as SSHAction;
+		const targets = Array.isArray(args.targets) ? args.targets : args.targets ? [args.targets] : [];
+
+		const cmd: SSHCommandArgs = {
+			action,
+			args: targets,
+			flags: {
+				json: flags.json,
+				host: flags.host,
+				user: flags.user,
+				port: flags.port,
+				key: flags.key,
+				desc: flags.desc,
+				compat: flags.compat,
+				scope: flags.scope as "project" | "user" | undefined,
+			},
+		};
+
+		await initTheme();
+		await runSSHCommand(cmd);
+	}
+}

package/src/commands/stats.ts

@@ -0,0 +1,29 @@
+/**
+ * View usage statistics dashboard.
+ */
+import { Command, Flags } from "@nghyane/arcane-utils/cli";
+import { runStatsCommand, type StatsCommandArgs } from "../cli/stats-cli";
+import { initTheme } from "../modes/theme/theme";
+
+export default class Stats extends Command {
+	static description = "View usage statistics";
+
+	static flags = {
+		port: Flags.integer({ char: "p", description: "Port for the dashboard server", default: 3847 }),
+		json: Flags.boolean({ char: "j", description: "Output stats as JSON", default: false }),
+		summary: Flags.boolean({ char: "s", description: "Print summary to console", default: false }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Stats);
+
+		const cmd: StatsCommandArgs = {
+			port: flags.port,
+			json: flags.json,
+			summary: flags.summary,
+		};
+
+		await initTheme();
+		await runStatsCommand(cmd);
+	}
+}

package/src/commands/update.ts

@@ -0,0 +1,21 @@
+/**
+ * Check for and install updates.
+ */
+import { Command, Flags } from "@nghyane/arcane-utils/cli";
+import { runUpdateCommand } from "../cli/update-cli";
+import { initTheme } from "../modes/theme/theme";
+
+export default class Update extends Command {
+	static description = "Check for and install updates";
+
+	static flags = {
+		force: Flags.boolean({ char: "f", description: "Force update", default: false }),
+		check: Flags.boolean({ char: "c", description: "Check for updates without installing", default: false }),
+	};
+
+	async run(): Promise<void> {
+		const { flags } = await this.parse(Update);
+		await initTheme();
+		await runUpdateCommand({ force: flags.force, check: flags.check });
+	}
+}

package/src/commands/web-search.ts

@@ -0,0 +1,42 @@
+/**
+ * Test web search providers.
+ */
+import { Args, Command, Flags } from "@nghyane/arcane-utils/cli";
+import { runSearchCommand, type SearchCommandArgs } from "../cli/web-search-cli";
+import { SEARCH_PROVIDER_ORDER } from "../web/search/provider";
+
+const PROVIDERS: Array<string> = ["auto", ...SEARCH_PROVIDER_ORDER];
+
+const RECENCY: NonNullable<SearchCommandArgs["recency"]>[] = ["day", "week", "month", "year"];
+
+export default class Search extends Command {
+	static description = "Test web search providers";
+
+	static aliases = ["q"];
+
+	static args = {
+		query: Args.string({ description: "Search query text", required: false, multiple: true }),
+	};
+
+	static flags = {
+		provider: Flags.string({ description: "Search provider", options: PROVIDERS }),
+		recency: Flags.string({ description: "Recency filter", options: RECENCY }),
+		limit: Flags.integer({ char: "l", description: "Max results to return" }),
+		compact: Flags.boolean({ description: "Render condensed output" }),
+	};
+
+	async run(): Promise<void> {
+		const { args, flags } = await this.parse(Search);
+		const query = Array.isArray(args.query) ? args.query.join(" ") : (args.query ?? "");
+
+		const cmd: SearchCommandArgs = {
+			query,
+			provider: flags.provider as SearchCommandArgs["provider"],
+			recency: flags.recency as SearchCommandArgs["recency"],
+			limit: flags.limit,
+			expanded: !flags.compact,
+		};
+
+		await runSearchCommand(cmd);
+	}
+}

package/src/commit/agentic/agent.ts

@@ -0,0 +1,311 @@
+import type { Api, Model } from "@nghyane/arcane-ai";
+import { Markdown } from "@nghyane/arcane-tui";
+import chalk from "chalk";
+import type { ControlledGit } from "../../commit/git";
+import typesDescriptionPrompt from "../../commit/prompts/types-description.md" with { type: "text" };
+import type { ModelRegistry } from "../../config/model-registry";
+import { renderPromptTemplate } from "../../config/prompt-templates";
+import type { Settings } from "../../config/settings";
+import { getMarkdownTheme } from "../../modes/theme/theme";
+import { createAgentSession } from "../../sdk";
+import type { AgentSessionEvent } from "../../session/agent-session";
+import type { AuthStorage } from "../../session/auth-storage";
+import agentUserPrompt from "./prompts/session-user.md" with { type: "text" };
+import agentSystemPrompt from "./prompts/system.md" with { type: "text" };
+import type { CommitAgentState } from "./state";
+import { createCommitTools } from "./tools";
+
+export interface CommitAgentInput {
+	cwd: string;
+	git: ControlledGit;
+	model: Model<Api>;
+	settings: Settings;
+	modelRegistry: ModelRegistry;
+	authStorage: AuthStorage;
+	userContext?: string;
+	contextFiles?: Array<{ path: string; content: string }>;
+	changelogTargets: string[];
+	requireChangelog: boolean;
+	diffText?: string;
+	existingChangelogEntries?: ExistingChangelogEntries[];
+}
+
+export interface ExistingChangelogEntries {
+	path: string;
+	sections: Array<{ name: string; items: string[] }>;
+}
+
+export async function runCommitAgentSession(input: CommitAgentInput): Promise<CommitAgentState> {
+	const typesDescription = renderPromptTemplate(typesDescriptionPrompt);
+	const systemPrompt = renderPromptTemplate(agentSystemPrompt, {
+		types_description: typesDescription,
+	});
+	const state: CommitAgentState = { diffText: input.diffText };
+	const spawns = "quick_task";
+	const tools = createCommitTools({
+		cwd: input.cwd,
+		git: input.git,
+		authStorage: input.authStorage,
+		modelRegistry: input.modelRegistry,
+		settings: input.settings,
+		spawns,
+		state,
+		changelogTargets: input.changelogTargets,
+		enableAnalyzeFiles: true,
+	});
+
+	const { session } = await createAgentSession({
+		cwd: input.cwd,
+		authStorage: input.authStorage,
+		modelRegistry: input.modelRegistry,
+		settings: input.settings,
+		model: input.model,
+		systemPrompt,
+		customTools: tools,
+		enableLsp: false,
+		enableMCP: false,
+		hasUI: false,
+		spawns,
+		toolNames: ["__none__"],
+		contextFiles: input.contextFiles,
+		disableExtensionDiscovery: true,
+		skills: [],
+		promptTemplates: [],
+		slashCommands: [],
+	});
+	let toolCalls = 0;
+	let messageCount = 0;
+	let isThinking = false;
+	let thinkingLineActive = false;
+	const toolArgsById = new Map<string, { name: string; args?: Record<string, unknown> }>();
+	const writeThinkingLine = (text: string) => {
+		const line = chalk.dim(`… ${text}`);
+		process.stdout.write(`\r\x1b[2K${line}`);
+		thinkingLineActive = true;
+	};
+	const clearThinkingLine = () => {
+		if (!thinkingLineActive) return;
+		process.stdout.write("\r\x1b[2K");
+		thinkingLineActive = false;
+	};
+	const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+		switch (event.type) {
+			case "message_start":
+				if (event.message.role === "assistant") {
+					isThinking = true;
+					thinkingLineActive = false;
+				}
+				break;
+			case "message_update": {
+				if (event.message?.role !== "assistant") break;
+				const preview = extractMessagePreview(event.message?.content ?? []);
+				if (!preview) break;
+				writeThinkingLine(preview);
+				break;
+			}
+			case "tool_execution_start":
+				toolCalls += 1;
+				toolArgsById.set(event.toolCallId, { name: event.toolName, args: event.args });
+				break;
+			case "message_end": {
+				const role = event.message?.role;
+				if (role === "assistant") {
+					messageCount += 1;
+					isThinking = false;
+					clearThinkingLine();
+					const assistantMessage = event.message as { stopReason?: string; errorMessage?: string };
+					if (assistantMessage.stopReason === "error" && assistantMessage.errorMessage) {
+						writeStdout(`● Error: ${assistantMessage.errorMessage}`);
+					}
+					const messageText = extractMessageText(event.message?.content ?? []);
+					if (messageText) {
+						writeAssistantMessage(messageText);
+					}
+				}
+				break;
+			}
+			case "tool_execution_end": {
+				const stored = toolArgsById.get(event.toolCallId) ?? { name: event.toolName };
+				toolArgsById.delete(event.toolCallId);
+				clearThinkingLine();
+				const toolLabel = formatToolLabel(stored.name);
+				const symbol = event.isError ? "" : "";
+				writeStdout(`${symbol} ${toolLabel}`);
+				const argsLines = formatToolArgs(stored.args);
+				if (argsLines.length > 0) {
+					writeStdout(formatToolArgsBlock(argsLines));
+				}
+				break;
+			}
+			case "agent_end":
+				if (isThinking) {
+					isThinking = false;
+				}
+				writeStdout(`● agent finished (${messageCount} messages, ${toolCalls} tools)`);
+				break;
+			default:
+				break;
+		}
+	});
+
+	try {
+		const prompt = renderPromptTemplate(agentUserPrompt, {
+			user_context: input.userContext,
+			changelog_targets: input.changelogTargets.length > 0 ? input.changelogTargets.join("\n") : undefined,
+			existing_changelog_entries: input.existingChangelogEntries,
+		});
+		const MAX_RETRIES = 3;
+		let retryCount = 0;
+		const needsChangelog = input.requireChangelog && input.changelogTargets.length > 0;
+
+		await session.prompt(prompt, { expandPromptTemplates: false });
+		while (retryCount < MAX_RETRIES && !isProposalComplete(state, needsChangelog)) {
+			retryCount += 1;
+			const reminder = buildReminderMessage(state, needsChangelog, retryCount, MAX_RETRIES);
+			await session.prompt(reminder, { expandPromptTemplates: false });
+		}
+
+		return state;
+	} finally {
+		unsubscribe();
+		await session.dispose();
+	}
+}
+
+function writeStdout(message: string): void {
+	process.stdout.write(`${message}\n`);
+}
+
+function extractMessagePreview(content: Array<{ type: string; text?: string }>): string | null {
+	const textBlocks = content
+		.filter(block => block.type === "text" && typeof block.text === "string")
+		.map(block => block.text?.trim())
+		.filter((value): value is string => Boolean(value));
+	if (textBlocks.length === 0) return null;
+	const combined = textBlocks.join(" ").replace(/\s+/g, " ").trim();
+	return truncateToolArg(combined);
+}
+
+function extractMessageText(content: Array<{ type: string; text?: string }>): string | null {
+	const textBlocks = content
+		.filter(block => block.type === "text" && typeof block.text === "string")
+		.map(block => block.text ?? "")
+		.filter(value => value.trim().length > 0);
+	if (textBlocks.length === 0) return null;
+	return textBlocks.join("\n").trim();
+}
+
+function writeAssistantMessage(message: string): void {
+	const lines = renderMarkdownLines(message);
+	if (lines.length === 0) return;
+	let firstContentIndex = lines.findIndex(line => line.trim().length > 0);
+	if (firstContentIndex === -1) {
+		firstContentIndex = 0;
+	}
+	for (const [index, line] of lines.entries()) {
+		const prefix = index === firstContentIndex ? "● " : "  ";
+		writeStdout(`${prefix}${line}`.trimEnd());
+	}
+}
+
+function renderMarkdownLines(message: string): string[] {
+	const width = Math.max(40, process.stdout.columns ?? 100);
+	const markdown = new Markdown(message, 0, 0, getMarkdownTheme());
+	return markdown.render(width);
+}
+
+function formatToolLabel(toolName: string): string {
+	const displayName = toolName
+		.split(/[_-]/)
+		.map(segment => segment.charAt(0).toUpperCase() + segment.slice(1))
+		.join("");
+	return displayName;
+}
+
+function formatToolArgs(args?: Record<string, unknown>): string[] {
+	if (!args || Object.keys(args).length === 0) return [];
+	const lines: string[] = [];
+	const visit = (value: unknown, keyPath: string) => {
+		if (value === null || value === undefined) return;
+		if (Array.isArray(value)) {
+			if (value.length === 0) return;
+			const rendered = value.map(item => renderPrimitive(item)).filter(Boolean);
+			if (rendered.length > 0) {
+				lines.push(`${keyPath}: ${rendered.join(", ")}`);
+			}
+			return;
+		}
+		if (typeof value === "object") {
+			const entries = Object.entries(value as Record<string, unknown>);
+			if (entries.length === 0) return;
+			for (const [childKey, childValue] of entries) {
+				visit(childValue, `${keyPath}.${childKey}`);
+			}
+			return;
+		}
+		const rendered = renderPrimitive(value);
+		if (rendered) {
+			lines.push(`${keyPath}: ${rendered}`);
+		}
+	};
+	for (const [key, value] of Object.entries(args)) {
+		visit(value, key);
+	}
+	return lines;
+}
+
+function renderPrimitive(value: unknown): string | null {
+	if (value === null || value === undefined) return null;
+	if (typeof value === "string") {
+		const trimmed = value.trim();
+		return trimmed.length > 0 ? trimmed : null;
+	}
+	if (typeof value === "number" || typeof value === "boolean") {
+		return String(value);
+	}
+	return null;
+}
+
+function formatToolArgsBlock(lines: string[]): string {
+	return lines
+		.map((line, index) => {
+			if (index === 0) return `  ⎿ ${line}`;
+			const branch = index === lines.length - 1 ? "└" : "├";
+			return `    ${branch} ${line}`;
+		})
+		.join("\n");
+}
+
+function isProposalComplete(state: CommitAgentState, requireChangelog: boolean): boolean {
+	const hasCommit = Boolean(state.proposal ?? state.splitProposal);
+	const hasChangelog = !requireChangelog || Boolean(state.changelogProposal);
+	return hasCommit && hasChangelog;
+}
+
+function buildReminderMessage(
+	state: CommitAgentState,
+	requireChangelog: boolean,
+	retryCount: number,
+	maxRetries: number,
+): string {
+	const missing: string[] = [];
+	if (!state.proposal && !state.splitProposal) {
+		missing.push("commit proposal (propose_commit or split_commit)");
+	}
+	if (requireChangelog && !state.changelogProposal) {
+		missing.push("changelog entries (propose_changelog)");
+	}
+	return `<system-reminder>
+CRITICAL: You must call the required tools before finishing.
+
+Missing: ${missing.join(", ") || "none"}.
+Reminder ${retryCount} of ${maxRetries}.
+
+Call the missing tool(s) now.
+</system-reminder>`;
+}
+
+function truncateToolArg(value: string): string {
+	if (value.length <= 40) return value;
+	return `${value.slice(0, 39)}…`;
+}

package/src/commit/agentic/fallback.ts

@@ -0,0 +1,96 @@
+import * as path from "node:path";
+import type { CommitType, ConventionalAnalysis, NumstatEntry } from "../../commit/types";
+import type { CommitProposal } from "./state";
+
+const TEST_PATTERNS = ["/test/", "/tests/", "/__tests__/", "_test.", ".test.", ".spec.", "_spec."];
+const DOC_EXTENSIONS = new Set([".md", ".txt", ".rst", ".adoc"]);
+const CONFIG_EXTENSIONS = new Set([".json", ".yaml", ".yml", ".toml", ".xml", ".ini", ".cfg"]);
+const STYLE_EXTENSIONS = new Set([".css", ".scss", ".less", ".sass"]);
+
+function inferTypeFromFiles(numstat: NumstatEntry[]): CommitType {
+	if (numstat.length === 0) return "chore";
+
+	let hasTests = false;
+	let hasDocs = false;
+	let hasConfig = false;
+	let hasStyle = false;
+	let hasSource = false;
+
+	for (const entry of numstat) {
+		const lowerPath = entry.path.toLowerCase();
+		const ext = getExtension(entry.path);
+
+		if (TEST_PATTERNS.some(pattern => lowerPath.includes(pattern))) {
+			hasTests = true;
+		} else if (DOC_EXTENSIONS.has(ext)) {
+			hasDocs = true;
+		} else if (CONFIG_EXTENSIONS.has(ext)) {
+			hasConfig = true;
+		} else if (STYLE_EXTENSIONS.has(ext)) {
+			hasStyle = true;
+		} else {
+			hasSource = true;
+		}
+	}
+
+	if (hasTests && !hasSource && !hasDocs) return "test";
+	if (hasDocs && !hasSource && !hasTests) return "docs";
+	if (hasStyle && !hasSource && !hasTests) return "style";
+	if (hasConfig && !hasSource && !hasTests && !hasDocs) return "chore";
+	return "refactor";
+}
+
+function getExtension(filePath: string): string {
+	const name = path.basename(filePath);
+	const dotIndex = name.lastIndexOf(".");
+	return dotIndex >= 0 ? name.slice(dotIndex).toLowerCase() : "";
+}
+
+export function generateFallbackAnalysis(numstat: NumstatEntry[]): ConventionalAnalysis {
+	const type = inferTypeFromFiles(numstat);
+	const details = numstat.slice(0, 3).map(e => ({
+		text: `Updated ${path.basename(e.path)}`,
+		userVisible: false,
+	}));
+
+	return {
+		type,
+		scope: null,
+		details,
+		issueRefs: [],
+	};
+}
+
+export function generateFallbackSummary(type: CommitType, numstat: NumstatEntry[]): string {
+	const verbMap: Record<string, string> = {
+		test: "updated tests for",
+		docs: "updated documentation for",
+		refactor: "refactored",
+		style: "formatted",
+		chore: "updated",
+		feat: "updated",
+		fix: "updated",
+		perf: "updated",
+		build: "updated",
+		ci: "updated",
+		revert: "reverted changes in",
+	};
+	const verb = verbMap[type] ?? "updated";
+	const file = path.basename(numstat[0]?.path ?? "files");
+
+	if (numstat.length === 1) {
+		return `${verb} ${file}`;
+	}
+	return `${verb} ${file} and ${numstat.length - 1} other${numstat.length === 2 ? "" : "s"}`;
+}
+
+export function generateFallbackProposal(numstat: NumstatEntry[]): CommitProposal {
+	const analysis = generateFallbackAnalysis(numstat);
+	const summary = generateFallbackSummary(analysis.type, numstat);
+
+	return {
+		analysis,
+		summary,
+		warnings: ["Commit generated using fallback due to agent failure"],
+	};
+}