@crafter/cli-tree 0.1.0

package/src/flow/yaml.ts

@@ -0,0 +1,235 @@
+export type YamlValue = string | number | boolean | null | YamlValue[] | { [key: string]: YamlValue };
+
+export function parseYaml(text: string): YamlValue {
+	const lines = text.split("\n");
+	const cleaned: { indent: number; content: string; lineNum: number }[] = [];
+
+	for (let i = 0; i < lines.length; i++) {
+		const raw = lines[i]!;
+		const commentIdx = findCommentStart(raw);
+		const withoutComment = commentIdx >= 0 ? raw.slice(0, commentIdx) : raw;
+		const trimmed = withoutComment.trimEnd();
+		if (!trimmed.trim()) continue;
+
+		const indent = trimmed.length - trimmed.trimStart().length;
+		cleaned.push({ indent, content: trimmed.trim(), lineNum: i + 1 });
+	}
+
+	const result = parseBlock(cleaned, 0, 0);
+	return result.value;
+}
+
+function findCommentStart(line: string): number {
+	let inString: string | null = null;
+	for (let i = 0; i < line.length; i++) {
+		const ch = line[i];
+		if (inString) {
+			if (ch === inString && line[i - 1] !== "\\") inString = null;
+		} else {
+			if (ch === '"' || ch === "'") inString = ch;
+			else if (ch === "#" && (i === 0 || line[i - 1] === " " || line[i - 1] === "\t")) {
+				return i;
+			}
+		}
+	}
+	return -1;
+}
+
+interface ParseState {
+	value: YamlValue;
+	nextIdx: number;
+}
+
+function parseBlock(
+	lines: { indent: number; content: string; lineNum: number }[],
+	startIdx: number,
+	baseIndent: number,
+): ParseState {
+	if (startIdx >= lines.length) return { value: null, nextIdx: startIdx };
+
+	const first = lines[startIdx]!;
+	if (first.indent < baseIndent) return { value: null, nextIdx: startIdx };
+
+	if (first.content.startsWith("- ") || first.content === "-") {
+		return parseList(lines, startIdx, first.indent);
+	}
+
+	if (first.content.includes(":")) {
+		return parseMap(lines, startIdx, first.indent);
+	}
+
+	return { value: parseScalar(first.content), nextIdx: startIdx + 1 };
+}
+
+function parseList(
+	lines: { indent: number; content: string; lineNum: number }[],
+	startIdx: number,
+	listIndent: number,
+): ParseState {
+	const items: YamlValue[] = [];
+	let i = startIdx;
+
+	while (i < lines.length) {
+		const line = lines[i]!;
+		if (line.indent < listIndent) break;
+		if (line.indent > listIndent) {
+			i++;
+			continue;
+		}
+		if (!line.content.startsWith("- ") && line.content !== "-") break;
+
+		const itemContent = line.content === "-" ? "" : line.content.slice(2);
+
+		if (!itemContent) {
+			const childIndent = listIndent + 2;
+			const next = parseBlock(lines, i + 1, childIndent);
+			items.push(next.value);
+			i = next.nextIdx;
+		} else if (itemContent.includes(":") && !isFlowScalar(itemContent)) {
+			const inlineIndent = listIndent + 2;
+			const synthetic = [
+				{ indent: inlineIndent, content: itemContent, lineNum: line.lineNum },
+				...lines.slice(i + 1),
+			];
+			const mapResult = parseMap(synthetic, 0, inlineIndent);
+			items.push(mapResult.value);
+			i = i + 1 + (mapResult.nextIdx - 1);
+		} else {
+			items.push(parseScalar(itemContent));
+			i++;
+		}
+	}
+
+	return { value: items, nextIdx: i };
+}
+
+function parseMap(
+	lines: { indent: number; content: string; lineNum: number }[],
+	startIdx: number,
+	mapIndent: number,
+): ParseState {
+	const map: { [key: string]: YamlValue } = {};
+	let i = startIdx;
+
+	while (i < lines.length) {
+		const line = lines[i]!;
+		if (line.indent < mapIndent) break;
+		if (line.indent > mapIndent) {
+			i++;
+			continue;
+		}
+
+		const colonIdx = findUnquotedColon(line.content);
+		if (colonIdx < 0) break;
+
+		const key = line.content.slice(0, colonIdx).trim().replace(/^["']|["']$/g, "");
+		const rest = line.content.slice(colonIdx + 1).trim();
+
+		if (!rest) {
+			const next = parseBlock(lines, i + 1, mapIndent + 1);
+			map[key] = next.value;
+			i = next.nextIdx;
+		} else if (rest.startsWith("[") && rest.endsWith("]")) {
+			map[key] = parseInlineList(rest);
+			i++;
+		} else if (rest.startsWith("{") && rest.endsWith("}")) {
+			map[key] = parseInlineMap(rest);
+			i++;
+		} else {
+			map[key] = parseScalar(rest);
+			i++;
+		}
+	}
+
+	return { value: map, nextIdx: i };
+}
+
+function findUnquotedColon(text: string): number {
+	let inString: string | null = null;
+	let bracket = 0;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i];
+		if (inString) {
+			if (ch === inString && text[i - 1] !== "\\") inString = null;
+		} else {
+			if (ch === '"' || ch === "'") inString = ch;
+			else if (ch === "[" || ch === "{") bracket++;
+			else if (ch === "]" || ch === "}") bracket--;
+			else if (ch === ":" && bracket === 0) return i;
+		}
+	}
+	return -1;
+}
+
+function parseScalar(text: string): YamlValue {
+	const trimmed = text.trim();
+	if (trimmed === "" || trimmed === "null" || trimmed === "~") return null;
+	if (trimmed === "true") return true;
+	if (trimmed === "false") return false;
+
+	if ((trimmed.startsWith('"') && trimmed.endsWith('"')) || (trimmed.startsWith("'") && trimmed.endsWith("'"))) {
+		return trimmed.slice(1, -1).replace(/\\"/g, '"').replace(/\\'/g, "'");
+	}
+
+	const num = Number(trimmed);
+	if (!Number.isNaN(num) && /^-?\d+(\.\d+)?$/.test(trimmed)) return num;
+
+	return trimmed;
+}
+
+function isFlowScalar(text: string): boolean {
+	return text.startsWith("[") || text.startsWith("{") || text.startsWith('"') || text.startsWith("'");
+}
+
+function parseInlineList(text: string): YamlValue[] {
+	const inner = text.slice(1, -1).trim();
+	if (!inner) return [];
+	return splitTopLevel(inner, ",").map(item => parseScalar(item.trim()));
+}
+
+function parseInlineMap(text: string): { [key: string]: YamlValue } {
+	const inner = text.slice(1, -1).trim();
+	if (!inner) return {};
+	const result: { [key: string]: YamlValue } = {};
+	for (const pair of splitTopLevel(inner, ",")) {
+		const colonIdx = findUnquotedColon(pair);
+		if (colonIdx < 0) continue;
+		const key = pair.slice(0, colonIdx).trim().replace(/^["']|["']$/g, "");
+		const val = pair.slice(colonIdx + 1).trim();
+		result[key] = parseScalar(val);
+	}
+	return result;
+}
+
+function splitTopLevel(text: string, sep: string): string[] {
+	const parts: string[] = [];
+	let depth = 0;
+	let inString: string | null = null;
+	let current = "";
+
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i]!;
+		if (inString) {
+			if (ch === inString && text[i - 1] !== "\\") inString = null;
+			current += ch;
+		} else {
+			if (ch === '"' || ch === "'") {
+				inString = ch;
+				current += ch;
+			} else if (ch === "[" || ch === "{") {
+				depth++;
+				current += ch;
+			} else if (ch === "]" || ch === "}") {
+				depth--;
+				current += ch;
+			} else if (ch === sep && depth === 0) {
+				parts.push(current);
+				current = "";
+			} else {
+				current += ch;
+			}
+		}
+	}
+	if (current) parts.push(current);
+	return parts;
+}

package/src/grid.ts

@@ -0,0 +1,59 @@
+export interface Cell {
+	char: string;
+	fg: string | null;
+}
+
+export interface Grid {
+	width: number;
+	height: number;
+	cells: Cell[][];
+	set(x: number, y: number, char: string, fg?: string | null): void;
+	get(x: number, y: number): Cell | undefined;
+	addRow(): void;
+}
+
+export function createGrid(width: number): Grid {
+	const cells: Cell[][] = [];
+
+	return {
+		get width() {
+			return width;
+		},
+		get height() {
+			return cells.length;
+		},
+		cells,
+		set(x: number, y: number, char: string, fg?: string | null) {
+			while (y >= cells.length) {
+				const row: Cell[] = [];
+				for (let i = 0; i < width; i++) {
+					row.push({ char: " ", fg: null });
+				}
+				cells.push(row);
+			}
+			if (x < 0 || x >= width) return;
+			const cell = cells[y]?.[x];
+			if (!cell) return;
+			cell.char = char;
+			if (fg !== undefined) cell.fg = fg ?? null;
+		},
+		get(x: number, y: number) {
+			return cells[y]?.[x];
+		},
+		addRow() {
+			const row: Cell[] = [];
+			for (let i = 0; i < width; i++) {
+				row.push({ char: " ", fg: null });
+			}
+			cells.push(row);
+		},
+	};
+}
+
+export function writeText(grid: Grid, x: number, y: number, text: string, fg?: string | null): number {
+	for (let i = 0; i < text.length; i++) {
+		if (x + i >= grid.width) break;
+		grid.set(x + i, y, text[i]!, fg);
+	}
+	return x + text.length;
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+import { renderTree } from "./render";
+import { encodeAnsi } from "./encoders/ansi";
+import { encodeString } from "./encoders/string";
+import { encodeHtml } from "./encoders/html";
+import type { CLINode, Flag, Arg, TreeOptions, AnsiColor } from "./types";
+
+export type { CLINode, Flag, Arg, TreeOptions, AnsiColor };
+export { parseHelp, parseHelpRecursive } from "./parse";
+
+export function treeToAnsi(root: CLINode, opts?: TreeOptions): string {
+	return encodeAnsi(renderTree(root, opts));
+}
+
+export function treeToString(root: CLINode, opts?: TreeOptions): string {
+	return encodeString(renderTree(root, opts));
+}
+
+export function treeToHtml(root: CLINode, opts?: TreeOptions): string {
+	return encodeHtml(renderTree(root, opts));
+}
+
+export function printTree(root: CLINode, opts?: TreeOptions): void {
+	console.log(treeToAnsi(root, opts));
+}

package/src/miner/history.ts

@@ -0,0 +1,156 @@
+import type { HistoryEntry } from "./types";
+
+export async function readHistoryFile(path: string): Promise<string> {
+	return await Bun.file(path).text();
+}
+
+export function detectHistoryFormat(text: string): "zsh-extended" | "bash" | "fish" | "unknown" {
+	const firstNonEmpty = text.split("\n").find(l => l.trim().length > 0);
+	if (!firstNonEmpty) return "unknown";
+	if (/^: \d+:\d+;/.test(firstNonEmpty)) return "zsh-extended";
+	if (/^- cmd: /.test(firstNonEmpty)) return "fish";
+	return "bash";
+}
+
+export function parseHistory(text: string): HistoryEntry[] {
+	const format = detectHistoryFormat(text);
+	switch (format) {
+		case "zsh-extended":
+			return parseZshExtended(text);
+		case "fish":
+			return parseFishHistory(text);
+		case "bash":
+		default:
+			return parseBashHistory(text);
+	}
+}
+
+function parseZshExtended(text: string): HistoryEntry[] {
+	const entries: HistoryEntry[] = [];
+	const lines = text.split("\n");
+
+	let pending: { timestamp: number; cmd: string } | null = null;
+
+	for (const rawLine of lines) {
+		const match = rawLine.match(/^: (\d+):\d+;(.*)$/);
+		if (match) {
+			if (pending) {
+				entries.push(buildEntry(pending.timestamp, pending.cmd));
+			}
+			pending = { timestamp: Number.parseInt(match[1]!, 10), cmd: match[2]! };
+		} else if (pending) {
+			pending.cmd += "\n" + rawLine;
+		}
+	}
+
+	if (pending) {
+		entries.push(buildEntry(pending.timestamp, pending.cmd));
+	}
+
+	return entries.filter(e => e.argv.length > 0);
+}
+
+function parseBashHistory(text: string): HistoryEntry[] {
+	const entries: HistoryEntry[] = [];
+	const lines = text.split("\n");
+	let currentTimestamp = 0;
+
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+
+		if (/^#\d+$/.test(trimmed)) {
+			currentTimestamp = Number.parseInt(trimmed.slice(1), 10);
+			continue;
+		}
+
+		entries.push(buildEntry(currentTimestamp, trimmed));
+	}
+
+	return entries.filter(e => e.argv.length > 0);
+}
+
+function parseFishHistory(text: string): HistoryEntry[] {
+	const entries: HistoryEntry[] = [];
+	const blocks = text.split(/\n(?=- cmd: )/);
+
+	for (const block of blocks) {
+		const cmdMatch = block.match(/- cmd: (.*)/);
+		const whenMatch = block.match(/when: (\d+)/);
+		if (!cmdMatch) continue;
+		const timestamp = whenMatch ? Number.parseInt(whenMatch[1]!, 10) : 0;
+		entries.push(buildEntry(timestamp, cmdMatch[1]!));
+	}
+
+	return entries.filter(e => e.argv.length > 0);
+}
+
+function buildEntry(timestamp: number, rawCmd: string): HistoryEntry {
+	const cleaned = stripContinuations(rawCmd).trim();
+	const argv = tokenize(cleaned);
+	return { timestamp, raw: cleaned, argv };
+}
+
+function stripContinuations(cmd: string): string {
+	return cmd.replace(/\\\n/g, " ").replace(/\n\s*/g, " ");
+}
+
+export function tokenize(cmd: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let inSingle = false;
+	let inDouble = false;
+	let escape = false;
+
+	for (let i = 0; i < cmd.length; i++) {
+		const ch = cmd[i]!;
+		if (escape) {
+			current += ch;
+			escape = false;
+			continue;
+		}
+		if (ch === "\\" && !inSingle) {
+			escape = true;
+			continue;
+		}
+		if (ch === "'" && !inDouble) {
+			inSingle = !inSingle;
+			continue;
+		}
+		if (ch === '"' && !inSingle) {
+			inDouble = !inDouble;
+			continue;
+		}
+		if (/\s/.test(ch) && !inSingle && !inDouble) {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			continue;
+		}
+		if ((ch === "|" || ch === ";" || ch === "&") && !inSingle && !inDouble) {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			return tokens;
+		}
+		current += ch;
+	}
+
+	if (current) tokens.push(current);
+	return tokens;
+}
+
+export function defaultHistoryPath(): string | null {
+	const home = process.env.HOME ?? "";
+	if (!home) return null;
+
+	const candidates = [
+		`${home}/.zsh_history`,
+		`${home}/.bash_history`,
+		`${home}/.config/fish/fish_history`,
+	];
+
+	return candidates[0] ?? null;
+}

package/src/miner/index.ts

@@ -0,0 +1,76 @@
+import { parseHistory, readHistoryFile, defaultHistoryPath, tokenize, detectHistoryFormat } from "./history";
+import { segmentSessions, filterByCli } from "./sessions";
+import { buildTransitions, normalizeTransitions, extractSubcommand, extractSubcommandPath } from "./transitions";
+import { extractPaths, clusterIntoWorkflows } from "./workflows";
+import { computeStats } from "./stats";
+import { suggestSkills, type SkillSuggestion } from "./suggest";
+import type { HistoryEntry, Session, Transition, MinedWorkflow, CliUsageStats, MineOptions } from "./types";
+
+export type { HistoryEntry, Session, Transition, MinedWorkflow, CliUsageStats, MineOptions, SkillSuggestion };
+export {
+	parseHistory,
+	readHistoryFile,
+	defaultHistoryPath,
+	tokenize,
+	detectHistoryFormat,
+	segmentSessions,
+	filterByCli,
+	buildTransitions,
+	normalizeTransitions,
+	extractSubcommand,
+	extractSubcommandPath,
+	extractPaths,
+	clusterIntoWorkflows,
+	computeStats,
+	suggestSkills,
+};
+
+export interface MineResult {
+	cli: string;
+	stats: CliUsageStats;
+	transitions: Transition[];
+	workflows: MinedWorkflow[];
+	suggestions: SkillSuggestion[];
+	sessionsAnalyzed: number;
+}
+
+export async function mineCli(cli: string, options: MineOptions = {}): Promise<MineResult> {
+	const path = options.historyPath ?? defaultHistoryPath();
+	if (!path) {
+		throw new Error("Could not determine shell history path. Pass historyPath explicitly.");
+	}
+
+	const text = await readHistoryFile(path);
+	const entries = parseHistory(text);
+	const allSessions = segmentSessions(entries, options.sessionGapMinutes ?? 10);
+	const cliSessions = filterByCli(allSessions, cli);
+
+	const stats = computeStats(entries, allSessions, cli);
+
+	const rawTransitions = buildTransitions(cliSessions);
+	const transitions = normalizeTransitions(
+		rawTransitions,
+		options.minSupport ?? 3,
+		options.minConfidence ?? 0.2,
+	);
+
+	const paths = extractPaths(
+		cliSessions,
+		options.minPathLength ?? 2,
+		options.maxPathLength ?? 6,
+	);
+	const workflows = clusterIntoWorkflows(paths, cli, {
+		minSupport: options.minSupport ?? 3,
+	});
+
+	const suggestions = suggestSkills(workflows, stats);
+
+	return {
+		cli,
+		stats,
+		transitions,
+		workflows,
+		suggestions,
+		sessionsAnalyzed: cliSessions.length,
+	};
+}

package/src/miner/sessions.ts

@@ -0,0 +1,39 @@
+import type { HistoryEntry, Session } from "./types";
+
+export function segmentSessions(entries: HistoryEntry[], gapMinutes = 10): Session[] {
+	if (entries.length === 0) return [];
+
+	const sorted = [...entries].sort((a, b) => a.timestamp - b.timestamp);
+	const gapSeconds = gapMinutes * 60;
+	const sessions: Session[] = [];
+
+	let current: HistoryEntry[] = [sorted[0]!];
+	let sessionStart = sorted[0]!.timestamp;
+	let lastTimestamp = sorted[0]!.timestamp;
+
+	for (let i = 1; i < sorted.length; i++) {
+		const entry = sorted[i]!;
+		const gap = entry.timestamp - lastTimestamp;
+
+		if (gap > gapSeconds) {
+			sessions.push({ start: sessionStart, end: lastTimestamp, entries: current });
+			current = [entry];
+			sessionStart = entry.timestamp;
+		} else {
+			current.push(entry);
+		}
+		lastTimestamp = entry.timestamp;
+	}
+
+	sessions.push({ start: sessionStart, end: lastTimestamp, entries: current });
+	return sessions;
+}
+
+export function filterByCli(sessions: Session[], cli: string): Session[] {
+	return sessions
+		.map(session => ({
+			...session,
+			entries: session.entries.filter(e => e.argv[0] === cli),
+		}))
+		.filter(s => s.entries.length > 0);
+}

package/src/miner/stats.ts

@@ -0,0 +1,43 @@
+import type { HistoryEntry, CliUsageStats, Session } from "./types";
+import { extractSubcommand } from "./transitions";
+
+export function computeStats(entries: HistoryEntry[], sessions: Session[], cli: string): CliUsageStats {
+	const cliEntries = entries.filter(e => e.argv[0] === cli);
+	const cliSessions = sessions.filter(s => s.entries.some(e => e.argv[0] === cli));
+
+	const subcommandCounts = new Map<string, number>();
+	const flagCounts = new Map<string, number>();
+
+	for (const entry of cliEntries) {
+		const sub = extractSubcommand(entry);
+		subcommandCounts.set(sub, (subcommandCounts.get(sub) ?? 0) + 1);
+
+		for (const arg of entry.argv.slice(1)) {
+			if (arg.startsWith("--")) {
+				const flag = arg.split("=")[0]!;
+				flagCounts.set(flag, (flagCounts.get(flag) ?? 0) + 1);
+			} else if (arg.startsWith("-") && arg.length === 2) {
+				flagCounts.set(arg, (flagCounts.get(arg) ?? 0) + 1);
+			}
+		}
+	}
+
+	const topSubcommands = Array.from(subcommandCounts.entries())
+		.map(([subcommand, count]) => ({ subcommand, count }))
+		.sort((a, b) => b.count - a.count)
+		.slice(0, 10);
+
+	const topFlags = Array.from(flagCounts.entries())
+		.map(([flag, count]) => ({ flag, count }))
+		.sort((a, b) => b.count - a.count)
+		.slice(0, 10);
+
+	return {
+		cli,
+		totalInvocations: cliEntries.length,
+		uniqueSubcommands: subcommandCounts.size,
+		topSubcommands,
+		topFlags,
+		sessionCount: cliSessions.length,
+	};
+}