@nghyane/arcane 0.1.0

package/src/debug/profiler.ts

@@ -0,0 +1,158 @@
+/**
+ * CPU and heap profiling wrappers for debug reports.
+ */
+
+export interface CpuProfile {
+	data: string;
+	markdown: string;
+}
+
+export interface ProfilerSession {
+	/** Stop profiling and return the profile data */
+	stop(): Promise<CpuProfile>;
+}
+
+/** V8 CPU Profile node structure */
+interface CpuProfileNode {
+	id: number;
+	callFrame?: {
+		functionName?: string;
+		url?: string;
+		lineNumber?: number;
+	};
+	hitCount?: number;
+	children?: number[];
+}
+
+/** V8 CPU Profile structure */
+interface CpuProfileData {
+	nodes?: CpuProfileNode[];
+	samples?: number[];
+	timeDeltas?: number[];
+	startTime?: number;
+	endTime?: number;
+}
+
+/**
+ * Format CPU profile data as markdown for LLM analysis.
+ * Extracts top functions by self time and call counts.
+ */
+function formatProfileAsMarkdown(profileJson: string): string {
+	try {
+		const profile = JSON.parse(profileJson) as CpuProfileData;
+		const nodes = profile.nodes ?? [];
+
+		interface NodeInfo {
+			id: number;
+			functionName: string;
+			url: string;
+			lineNumber: number;
+			selfTime: number;
+			hitCount: number;
+		}
+
+		const nodeMap = new Map<number, NodeInfo>();
+		for (const node of nodes) {
+			nodeMap.set(node.id, {
+				id: node.id,
+				functionName: node.callFrame?.functionName ?? "(anonymous)",
+				url: node.callFrame?.url ?? "",
+				lineNumber: node.callFrame?.lineNumber ?? 0,
+				selfTime: 0,
+				hitCount: node.hitCount ?? 0,
+			});
+		}
+
+		// Distribute sample times to nodes
+		const samples = profile.samples ?? [];
+		const timeDeltas = profile.timeDeltas ?? [];
+		for (let i = 0; i < samples.length; i++) {
+			const nodeId = samples[i];
+			const info = nodeId !== undefined ? nodeMap.get(nodeId) : undefined;
+			const delta = timeDeltas[i] ?? 0;
+			if (info) {
+				info.selfTime += delta;
+			}
+		}
+
+		// Sort by self time and get top functions
+		const sorted = Array.from(nodeMap.values())
+			.filter(n => n.selfTime > 0 && n.functionName !== "(root)" && n.functionName !== "(idle)")
+			.sort((a, b) => b.selfTime - a.selfTime)
+			.slice(0, 30);
+
+		if (sorted.length === 0) {
+			return "# CPU Profile Summary\n\nNo significant CPU activity recorded.";
+		}
+
+		const totalTime = sorted.reduce((sum, n) => sum + n.selfTime, 0);
+
+		const lines = ["# CPU Profile Summary", ""];
+		lines.push(`Total profiled time: ${(totalTime / 1000).toFixed(1)}ms`);
+		lines.push("");
+		lines.push("## Top Functions by Self Time");
+		lines.push("");
+		lines.push("| Function | Self Time (ms) | % | Location |");
+		lines.push("|----------|----------------|---|----------|");
+
+		for (const node of sorted) {
+			const selfMs = (node.selfTime / 1000).toFixed(1);
+			const pct = ((node.selfTime / totalTime) * 100).toFixed(1);
+			const location = node.url ? `${node.url}:${node.lineNumber}` : "-";
+			lines.push(`| ${node.functionName} | ${selfMs} | ${pct}% | ${location} |`);
+		}
+
+		return lines.join("\n");
+	} catch {
+		return "# CPU Profile Summary\n\nFailed to parse profile data.";
+	}
+}
+
+/**
+ * Start CPU profiling.
+ * Returns a session that can be stopped to get the profile data.
+ */
+export async function startCpuProfile(): Promise<ProfilerSession> {
+	const v8 = await import("node:v8");
+	v8.setFlagsFromString("--allow-natives-syntax");
+
+	const { Session } = await import("node:inspector/promises");
+	const session = new Session();
+	session.connect();
+
+	await session.post("Profiler.enable");
+	await session.post("Profiler.start");
+
+	return {
+		async stop(): Promise<CpuProfile> {
+			const result = await session.post("Profiler.stop");
+			await session.post("Profiler.disable");
+			session.disconnect();
+
+			const data = JSON.stringify(result.profile, null, 2);
+			const markdown = formatProfileAsMarkdown(data);
+
+			return { data, markdown };
+		},
+	};
+}
+
+export interface HeapSnapshot {
+	data: string;
+}
+
+/**
+ * Generate a heap snapshot.
+ * Uses Bun's built-in generateHeapSnapshot.
+ */
+export function generateHeapSnapshotData(): HeapSnapshot {
+	// Force GC before snapshot
+	Bun.gc(true);
+
+	// Use V8 format for Chrome DevTools compatibility
+	const snapshot = Bun.generateHeapSnapshot("v8");
+
+	return {
+		data: snapshot,
+	};
+}

package/src/debug/report-bundle.ts

@@ -0,0 +1,366 @@
+/**
+ * Debug report bundle creation.
+ *
+ * Creates a .tar.gz archive with session data, logs, system info, and optional profiling data.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import type { WorkProfile } from "@nghyane/arcane-natives";
+import { isEnoent } from "@nghyane/arcane-utils";
+import { APP_NAME, getLogPath, getLogsDir, getReportsDir } from "@nghyane/arcane-utils/dirs";
+import type { CpuProfile, HeapSnapshot } from "./profiler";
+import { collectSystemInfo, sanitizeEnv } from "./system-info";
+
+/** Maximum number of log lines to load into memory at once. */
+const MAX_LOG_LINES = 5000;
+
+/** Maximum bytes to read from the tail of a log file (2 MB). */
+const MAX_LOG_BYTES = 2 * 1024 * 1024;
+/** Read last N lines from a file, reading at most `maxBytes` from the tail. */
+async function readLastLines(filePath: string, n: number, maxBytes = MAX_LOG_BYTES): Promise<string> {
+	try {
+		const file = Bun.file(filePath);
+		const size = file.size;
+		const start = Math.max(0, size - maxBytes);
+		const content = start > 0 ? await file.slice(start, size).text() : await file.text();
+		const lines = content.split("\n");
+		// If we sliced mid-file, drop the first (partial) line
+		if (start > 0 && lines.length > 0) {
+			lines.shift();
+		}
+		return lines.slice(-n).join("\n");
+	} catch (err) {
+		if (isEnoent(err)) return "";
+		throw err;
+	}
+}
+
+export interface ReportBundleOptions {
+	/** Session file path */
+	sessionFile: string | undefined;
+	/** Settings to include */
+	settings?: Record<string, unknown>;
+	/** CPU profile (for performance reports) */
+	cpuProfile?: CpuProfile;
+	/** Heap snapshot (for memory reports) */
+	heapSnapshot?: HeapSnapshot;
+	/** Work profile (for work scheduling reports) */
+	workProfile?: WorkProfile;
+}
+
+export interface ReportBundleResult {
+	path: string;
+	files: string[];
+}
+
+export interface DebugLogSource {
+	getInitialText(): Promise<string>;
+	hasOlderLogs(): boolean;
+	loadOlderLogs(limitDays?: number): Promise<string>;
+}
+
+/**
+ * Create a debug report bundle.
+ *
+ * Bundle contents:
+ * - session.jsonl: Current session transcript
+ * - artifacts/: Session artifacts directory
+ * - subagents/: Subagent sessions + artifacts
+ * - logs.txt: Recent log entries
+ * - system.json: OS, arch, CPU, memory, versions
+ * - env.json: Sanitized environment variables
+ * - config.json: Resolved settings
+ * - profile.cpuprofile: CPU profile (performance report only)
+ * - profile.md: Markdown CPU profile (performance report only)
+ * - heap.heapsnapshot: Heap snapshot (memory report only)
+ * - work.folded: Work profile folded stacks (work report only)
+ * - work.md: Work profile summary (work report only)
+ * - work.svg: Work profile flamegraph (work report only)
+ */
+export async function createReportBundle(options: ReportBundleOptions): Promise<ReportBundleResult> {
+	const reportsDir = getReportsDir();
+	await fs.mkdir(reportsDir, { recursive: true });
+
+	const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+	const outputPath = path.join(reportsDir, `arc-report-${timestamp}.tar.gz`);
+
+	const data: Record<string, string> = {};
+	const files: string[] = [];
+
+	// Collect system info
+	const systemInfo = await collectSystemInfo();
+	data["system.json"] = JSON.stringify(systemInfo, null, 2);
+	files.push("system.json");
+
+	// Sanitized environment
+	data["env.json"] = JSON.stringify(sanitizeEnv(Bun.env as Record<string, string>), null, 2);
+	files.push("env.json");
+
+	// Settings/config
+	if (options.settings) {
+		data["config.json"] = JSON.stringify(options.settings, null, 2);
+		files.push("config.json");
+	}
+
+	// Recent logs (last 1000 lines)
+	const logPath = getLogPath();
+	const logs = await readLastLines(logPath, 1000);
+	if (logs) {
+		data["logs.txt"] = logs;
+		files.push("logs.txt");
+	}
+
+	// Session file
+	if (options.sessionFile) {
+		try {
+			const sessionContent = await Bun.file(options.sessionFile).text();
+			data["session.jsonl"] = sessionContent;
+			files.push("session.jsonl");
+		} catch {
+			// Session file might not exist yet
+		}
+
+		// Artifacts directory (same path without .jsonl)
+		const artifactsDir = options.sessionFile.slice(0, -6);
+		await addDirectoryToArchive(data, files, artifactsDir, "artifacts");
+
+		// Look for subagent sessions in the same directory
+		const sessionDir = path.dirname(options.sessionFile);
+		const sessionBasename = path.basename(options.sessionFile, ".jsonl");
+		await addSubagentSessions(data, files, sessionDir, sessionBasename);
+	}
+
+	// CPU profile
+	if (options.cpuProfile) {
+		data["profile.cpuprofile"] = options.cpuProfile.data;
+		files.push("profile.cpuprofile");
+		data["profile.md"] = options.cpuProfile.markdown;
+		files.push("profile.md");
+	}
+
+	// Heap snapshot
+	if (options.heapSnapshot) {
+		data["heap.heapsnapshot"] = options.heapSnapshot.data;
+		files.push("heap.heapsnapshot");
+	}
+
+	// Work profile
+	if (options.workProfile) {
+		data["work.folded"] = options.workProfile.folded;
+		files.push("work.folded");
+		data["work.md"] = options.workProfile.summary;
+		files.push("work.md");
+		if (options.workProfile.svg) {
+			data["work.svg"] = options.workProfile.svg;
+			files.push("work.svg");
+		}
+	}
+
+	// Write archive
+	await Bun.Archive.write(outputPath, data, { compress: "gzip" });
+
+	return { path: outputPath, files };
+}
+
+/** Add all files from a directory to the archive */
+async function addDirectoryToArchive(
+	data: Record<string, string>,
+	files: string[],
+	dirPath: string,
+	archivePrefix: string,
+): Promise<void> {
+	try {
+		const entries = await fs.readdir(dirPath, { withFileTypes: true });
+		for (const entry of entries) {
+			if (!entry.isFile()) continue;
+			const filePath = path.join(dirPath, entry.name);
+			const archivePath = `${archivePrefix}/${entry.name}`;
+			try {
+				const content = await Bun.file(filePath).text();
+				data[archivePath] = content;
+				files.push(archivePath);
+			} catch {
+				// Skip files we can't read
+			}
+		}
+	} catch {
+		// Directory doesn't exist
+	}
+}
+
+/** Find and add subagent session files */
+async function addSubagentSessions(
+	data: Record<string, string>,
+	files: string[],
+	sessionDir: string,
+	parentBasename: string,
+): Promise<void> {
+	// Subagent sessions are named with task IDs in the same directory
+	// They follow the pattern: {timestamp}_{sessionId}.jsonl
+	// We look for any sessions created after the parent session
+	try {
+		const entries = await fs.readdir(sessionDir, { withFileTypes: true });
+		const sessionFiles = entries
+			.filter(e => e.isFile() && e.name.endsWith(".jsonl") && e.name !== `${parentBasename}.jsonl`)
+			.map(e => e.name);
+
+		// Limit to most recent 10 subagent sessions
+		const sortedFiles = sessionFiles.sort().slice(-10);
+
+		for (const filename of sortedFiles) {
+			const filePath = path.join(sessionDir, filename);
+			const archivePath = `subagents/${filename}`;
+			try {
+				const content = await Bun.file(filePath).text();
+				data[archivePath] = content;
+				files.push(archivePath);
+
+				// Also add artifacts for this subagent session
+				const artifactsDir = filePath.slice(0, -6);
+				await addDirectoryToArchive(data, files, artifactsDir, `subagents/${filename.slice(0, -6)}`);
+			} catch {
+				// Skip files we can't read
+			}
+		}
+	} catch {
+		// Directory doesn't exist
+	}
+}
+
+/** Get recent log entries for display (tail-limited to avoid OOM on large files). */
+export async function getLogText(): Promise<string> {
+	return readLastLines(getLogPath(), MAX_LOG_LINES);
+}
+
+const LOG_FILE_PATTERN = new RegExp(`^${APP_NAME}\\.(\\d{4}-\\d{2}-\\d{2})\\.log$`);
+
+export async function createDebugLogSource(): Promise<DebugLogSource> {
+	const logsDir = getLogsDir();
+	const todayPath = getLogPath();
+	const todayName = path.basename(todayPath);
+	let olderFiles: string[] = [];
+	try {
+		const entries = await fs.readdir(logsDir, { withFileTypes: true });
+		const datedFiles = entries
+			.filter(entry => entry.isFile())
+			.map(entry => {
+				const match = LOG_FILE_PATTERN.exec(entry.name);
+				return match ? { name: entry.name, date: match[1] } : undefined;
+			})
+			.filter((entry): entry is { name: string; date: string } => entry !== undefined)
+			.filter(entry => entry.name !== todayName)
+			.sort((a, b) => b.date.localeCompare(a.date));
+		olderFiles = datedFiles.map(entry => entry.name);
+	} catch {
+		olderFiles = [];
+	}
+
+	let cursor = 0;
+
+	const getInitialText = async (): Promise<string> => {
+		return readLastLines(todayPath, MAX_LOG_LINES);
+	};
+
+	const hasOlderLogs = (): boolean => cursor < olderFiles.length;
+
+	const loadOlderLogs = async (limitDays: number = 1): Promise<string> => {
+		if (!hasOlderLogs()) {
+			return "";
+		}
+		const count = Math.max(1, limitDays);
+		const slice = olderFiles.slice(cursor, cursor + count);
+		cursor += slice.length;
+		const chunks: string[] = [];
+		for (const filename of slice.reverse()) {
+			const filePath = path.join(logsDir, filename);
+			try {
+				const content = await readLastLines(filePath, MAX_LOG_LINES);
+				if (content.length > 0) {
+					chunks.push(content);
+				}
+			} catch (err) {
+				if (!isEnoent(err)) {
+					throw err;
+				}
+			}
+		}
+		return chunks.filter(chunk => chunk.length > 0).join("\n");
+	};
+
+	return {
+		getInitialText,
+		hasOlderLogs,
+		loadOlderLogs,
+	};
+}
+
+/** Calculate total size of artifact cache */
+export async function getArtifactCacheStats(
+	sessionsDir: string,
+): Promise<{ count: number; totalSize: number; oldestDate: Date | null }> {
+	let count = 0;
+	let totalSize = 0;
+	let oldestDate: Date | null = null;
+
+	try {
+		const sessions = await fs.readdir(sessionsDir, { withFileTypes: true });
+
+		for (const session of sessions) {
+			// Artifact directories don't have .jsonl extension
+			if (session.isDirectory()) {
+				const dirPath = path.join(sessionsDir, session.name);
+				try {
+					const stat = await fs.stat(dirPath);
+					const files = await fs.readdir(dirPath);
+					for (const file of files) {
+						const filePath = path.join(dirPath, file);
+						const fileStat = await fs.stat(filePath);
+						if (fileStat.isFile()) {
+							count++;
+							totalSize += fileStat.size;
+						}
+					}
+					if (!oldestDate || stat.mtime < oldestDate) {
+						oldestDate = stat.mtime;
+					}
+				} catch {
+					// Skip inaccessible directories
+				}
+			}
+		}
+	} catch {
+		// Directory doesn't exist
+	}
+
+	return { count, totalSize, oldestDate };
+}
+
+/** Clear artifact cache older than N days */
+export async function clearArtifactCache(sessionsDir: string, daysOld: number = 30): Promise<{ removed: number }> {
+	const cutoff = new Date();
+	cutoff.setDate(cutoff.getDate() - daysOld);
+	let removed = 0;
+
+	try {
+		const sessions = await fs.readdir(sessionsDir, { withFileTypes: true });
+
+		for (const session of sessions) {
+			if (session.isDirectory()) {
+				const dirPath = path.join(sessionsDir, session.name);
+				try {
+					const stat = await fs.stat(dirPath);
+					if (stat.mtime < cutoff) {
+						await fs.rm(dirPath, { recursive: true, force: true });
+						removed++;
+					}
+				} catch {
+					// Skip inaccessible directories
+				}
+			}
+		}
+	} catch {
+		// Directory doesn't exist
+	}
+
+	return { removed };
+}

package/src/debug/system-info.ts

@@ -0,0 +1,112 @@
+/**
+ * System information collection for debug reports.
+ */
+import * as os from "node:os";
+import { getProjectDir, VERSION } from "@nghyane/arcane-utils/dirs";
+
+export interface SystemInfo {
+	os: string;
+	arch: string;
+	cpu: string;
+	memory: {
+		total: number;
+		free: number;
+	};
+	versions: {
+		app: string;
+		bun: string;
+		node: string;
+	};
+	cwd: string;
+	shell: string;
+	terminal: string | undefined;
+}
+
+/** Map Darwin kernel major version to macOS marketing name. */
+function macosMarketingName(release: string): string | undefined {
+	const major = Number.parseInt(release.split(".")[0] ?? "", 10);
+	if (Number.isNaN(major)) return undefined;
+	const names: Record<number, string> = {
+		25: "Tahoe",
+		24: "Sequoia",
+		23: "Sonoma",
+		22: "Ventura",
+		21: "Monterey",
+		20: "Big Sur",
+	};
+	return names[major];
+}
+
+/** Collect system information */
+export async function collectSystemInfo(): Promise<SystemInfo> {
+	const cpus = os.cpus();
+	const cpuModel = cpus[0]?.model ?? "Unknown CPU";
+
+	// Try to get shell from environment
+	const shell = Bun.env.SHELL ?? Bun.env.ComSpec ?? "unknown";
+	const terminal = Bun.env.TERM_PROGRAM ?? Bun.env.TERM ?? undefined;
+
+	let osStr = `${os.type()} ${os.release()} (${os.platform()})`;
+	if (os.platform() === "darwin") {
+		const name = macosMarketingName(os.release());
+		if (name) osStr = `${osStr} ${name}`;
+	}
+
+	return {
+		os: osStr,
+		arch: os.arch(),
+		cpu: cpuModel,
+		memory: {
+			total: os.totalmem(),
+			free: os.freemem(),
+		},
+		versions: {
+			app: VERSION,
+			bun: Bun.version,
+			node: process.version,
+		},
+		cwd: getProjectDir(),
+		shell,
+		terminal,
+	};
+}
+
+/** Format bytes to human-readable string */
+function formatBytes(bytes: number): string {
+	const gb = bytes / (1024 * 1024 * 1024);
+	return `${gb.toFixed(1)} GB`;
+}
+
+/** Format system info for display */
+export function formatSystemInfo(info: SystemInfo): string {
+	const lines = [
+		"System Information",
+		"━━━━━━━━━━━━━━━━━━",
+		`OS:      ${info.os}`,
+		`Arch:    ${info.arch}`,
+		`CPU:     ${info.cpu}`,
+		`Memory:  ${formatBytes(info.memory.total)} (${formatBytes(info.memory.free)} free)`,
+		`Bun:     ${info.versions.bun}`,
+		`App:     arcane ${info.versions.app}`,
+		`Node:    ${info.versions.node} (compat)`,
+		`CWD:     ${info.cwd}`,
+		`Shell:   ${info.shell}`,
+	];
+	if (info.terminal) {
+		lines.push(`Terminal: ${info.terminal}`);
+	}
+	return lines.join("\n");
+}
+
+/** Sanitize environment variables by redacting sensitive values */
+export function sanitizeEnv(env: Record<string, string | undefined>): Record<string, string> {
+	const SENSITIVE_PATTERNS = [/key/i, /secret/i, /token/i, /pass/i, /auth/i, /credential/i, /api/i, /private/i];
+
+	const result: Record<string, string> = {};
+	for (const [k, v] of Object.entries(env)) {
+		if (v === undefined) continue;
+		const isSensitive = SENSITIVE_PATTERNS.some(p => p.test(k));
+		result[k] = isSensitive ? "[REDACTED]" : v;
+	}
+	return result;
+}

package/src/discovery/agents-md.ts

@@ -0,0 +1,68 @@
+/**
+ * AGENTS.md Provider
+ *
+ * Discovers standalone AGENTS.md files by walking up from cwd.
+ * This handles AGENTS.md files that live in project root (not in config directories
+ * like .codex/ or .gemini/, which are handled by their respective providers).
+ */
+import * as path from "node:path";
+import { registerProvider } from "../capability";
+import { type ContextFile, contextFileCapability } from "../capability/context-file";
+import { readFile } from "../capability/fs";
+import type { LoadContext, LoadResult } from "../capability/types";
+import { calculateDepth, createSourceMeta } from "./helpers";
+
+const PROVIDER_ID = "agents-md";
+const DISPLAY_NAME = "AGENTS.md";
+const MAX_DEPTH = 20; // Prevent walking up excessively far from cwd
+
+/**
+ * Load standalone AGENTS.md files.
+ */
+async function loadAgentsMd(ctx: LoadContext): Promise<LoadResult<ContextFile>> {
+	const items: ContextFile[] = [];
+	const warnings: string[] = [];
+
+	// Walk up from cwd looking for AGENTS.md files
+	let current = ctx.cwd;
+	let depth = 0;
+
+	while (depth < MAX_DEPTH) {
+		const candidate = path.join(current, "AGENTS.md");
+		const content = await readFile(candidate);
+
+		if (content !== null) {
+			const parent = path.dirname(candidate);
+			const baseName = parent.split(path.sep).pop() ?? "";
+
+			if (!baseName.startsWith(".")) {
+				const fileDir = path.dirname(candidate);
+				const calculatedDepth = calculateDepth(ctx.cwd, fileDir, path.sep);
+
+				items.push({
+					path: candidate,
+					content,
+					level: "project",
+					depth: calculatedDepth,
+					_source: createSourceMeta(PROVIDER_ID, candidate, "project"),
+				});
+			}
+		}
+
+		// Move to parent directory
+		const parent = path.dirname(current);
+		if (parent === current) break; // Reached filesystem root
+		current = parent;
+		depth++;
+	}
+
+	return { items, warnings };
+}
+
+registerProvider(contextFileCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Standalone AGENTS.md files (Codex/Gemini style)",
+	priority: 10,
+	load: loadAgentsMd,
+});