@crafter/cli-tree 0.1.0

package/src/miner/suggest.ts

@@ -0,0 +1,101 @@
+import type { MinedWorkflow, CliUsageStats } from "./types";
+
+export interface SkillSuggestion {
+	name: string;
+	description: string;
+	cli: string;
+	commands: string[];
+	frequency: number;
+	reason: string;
+	priority: "high" | "medium" | "low";
+}
+
+export function suggestSkills(
+	workflows: MinedWorkflow[],
+	stats: CliUsageStats,
+): SkillSuggestion[] {
+	const suggestions: SkillSuggestion[] = [];
+
+	for (const wf of workflows) {
+		const path = wf.path[0] ?? [];
+		if (path.length < 2) continue;
+
+		const suggestion = workflowToSuggestion(wf, stats);
+		if (suggestion) suggestions.push(suggestion);
+	}
+
+	return suggestions.sort((a, b) => {
+		const priorityOrder = { high: 0, medium: 1, low: 2 };
+		if (priorityOrder[a.priority] !== priorityOrder[b.priority]) {
+			return priorityOrder[a.priority] - priorityOrder[b.priority];
+		}
+		return b.frequency - a.frequency;
+	});
+}
+
+function workflowToSuggestion(wf: MinedWorkflow, stats: CliUsageStats): SkillSuggestion | null {
+	const path = wf.path[0] ?? [];
+	if (path.length < 2) return null;
+
+	const commands = path.map(sub => `${wf.cli} ${sub}`);
+	const frequency = wf.support;
+
+	const priority = scorePriority(frequency, path.length, stats.totalInvocations);
+
+	const name = generateSkillName(wf.cli, path);
+	const description = generateDescription(wf.cli, path);
+	const reason = generateReason(frequency, path, stats);
+
+	return { name, description, cli: wf.cli, commands, frequency, reason, priority };
+}
+
+function scorePriority(frequency: number, pathLength: number, totalInvocations: number): "high" | "medium" | "low" {
+	const ratio = frequency / totalInvocations;
+	const score = frequency * pathLength * (ratio + 0.1);
+
+	if (score > 50) return "high";
+	if (score > 15) return "medium";
+	return "low";
+}
+
+function generateSkillName(cli: string, path: string[]): string {
+	const knownPatterns: Record<string, string> = {
+		"add,commit": "ship",
+		"add,commit,push": "ship",
+		"commit,push": "push-latest",
+		"install,dev": "start",
+		"install,run": "start",
+		"login,publish": "release",
+		"publish,tag": "release",
+		"checkout,pull": "sync",
+		"fetch,pull": "sync",
+		"build,push": "deploy",
+		"build,run": "test-build",
+		"compose,compose": "compose-iterate",
+	};
+
+	const key = path.join(",");
+	if (knownPatterns[key]) return knownPatterns[key]!;
+
+	return path.join("-");
+}
+
+function generateDescription(cli: string, path: string[]): string {
+	return `Run ${cli} ${path.join(", then ")} as one command`;
+}
+
+function generateReason(frequency: number, path: string[], stats: CliUsageStats): string {
+	const ratio = frequency / stats.totalInvocations;
+	const pct = (ratio * 100).toFixed(0);
+
+	if (ratio > 0.1) {
+		return `You run this exact sequence ${frequency} times (${pct}% of all your ${stats.cli} usage)`;
+	}
+	if (frequency >= 50) {
+		return `You run this exact sequence ${frequency} times — that's a lot of repetition`;
+	}
+	if (frequency >= 20) {
+		return `You run this exact sequence ${frequency} times`;
+	}
+	return `Detected ${frequency} times in your shell history`;
+}

package/src/miner/transitions.ts

@@ -0,0 +1,62 @@
+import type { Session, Transition, HistoryEntry } from "./types";
+
+export function extractSubcommand(entry: HistoryEntry): string {
+	const [, ...rest] = entry.argv;
+	const sub = rest.find(arg => !arg.startsWith("-") && !arg.startsWith("$") && /^[a-z]/i.test(arg));
+	return sub ?? "(root)";
+}
+
+export function extractSubcommandPath(entry: HistoryEntry, maxDepth = 3): string[] {
+	const [, ...rest] = entry.argv;
+	const path: string[] = [];
+	for (const arg of rest) {
+		if (arg.startsWith("-") || arg.startsWith("$")) continue;
+		if (!/^[a-z]/i.test(arg)) break;
+		path.push(arg);
+		if (path.length >= maxDepth) break;
+	}
+	return path;
+}
+
+export function buildTransitions(sessions: Session[]): Map<string, Map<string, number>> {
+	const transitions = new Map<string, Map<string, number>>();
+
+	for (const session of sessions) {
+		for (let i = 0; i < session.entries.length - 1; i++) {
+			const from = extractSubcommand(session.entries[i]!);
+			const to = extractSubcommand(session.entries[i + 1]!);
+
+			if (!transitions.has(from)) transitions.set(from, new Map());
+			const inner = transitions.get(from)!;
+			inner.set(to, (inner.get(to) ?? 0) + 1);
+		}
+	}
+
+	return transitions;
+}
+
+export function normalizeTransitions(
+	raw: Map<string, Map<string, number>>,
+	minSupport = 3,
+	minConfidence = 0.2,
+): Transition[] {
+	const results: Transition[] = [];
+
+	for (const [from, nexts] of raw.entries()) {
+		const total = Array.from(nexts.values()).reduce((a, b) => a + b, 0);
+		if (total < minSupport) continue;
+
+		for (const [to, count] of nexts.entries()) {
+			if (count < minSupport) continue;
+			const confidence = count / total;
+			if (confidence < minConfidence) continue;
+			results.push({ from, to, count, confidence });
+		}
+	}
+
+	return results.sort((a, b) => b.count - a.count);
+}
+
+export function topTransitions(transitions: Transition[], n = 10): Transition[] {
+	return transitions.slice(0, n);
+}

package/src/miner/types.ts

@@ -0,0 +1,45 @@
+export interface HistoryEntry {
+	timestamp: number;
+	raw: string;
+	argv: string[];
+}
+
+export interface Session {
+	start: number;
+	end: number;
+	entries: HistoryEntry[];
+}
+
+export interface Transition {
+	from: string;
+	to: string;
+	count: number;
+	confidence: number;
+}
+
+export interface MinedWorkflow {
+	name: string;
+	cli: string;
+	path: string[][];
+	support: number;
+	confidence: number;
+	source: "history" | "llm" | "makefile";
+}
+
+export interface CliUsageStats {
+	cli: string;
+	totalInvocations: number;
+	uniqueSubcommands: number;
+	topSubcommands: Array<{ subcommand: string; count: number }>;
+	topFlags: Array<{ flag: string; count: number }>;
+	sessionCount: number;
+}
+
+export interface MineOptions {
+	sessionGapMinutes?: number;
+	minSupport?: number;
+	minConfidence?: number;
+	minPathLength?: number;
+	maxPathLength?: number;
+	historyPath?: string;
+}

package/src/miner/workflows.ts

@@ -0,0 +1,96 @@
+import type { Session, MinedWorkflow } from "./types";
+import { extractSubcommand } from "./transitions";
+
+export interface PathCluster {
+	signature: string;
+	path: string[];
+	occurrences: number;
+}
+
+export function extractPaths(
+	sessions: Session[],
+	minLength = 2,
+	maxLength = 7,
+): PathCluster[] {
+	const pathCounts = new Map<string, { path: string[]; count: number }>();
+
+	for (const session of sessions) {
+		const subcommands = session.entries.map(extractSubcommand);
+		const dedupedConsecutive = dedupeConsecutive(subcommands);
+
+		for (let start = 0; start < dedupedConsecutive.length; start++) {
+			const maxEnd = Math.min(start + maxLength, dedupedConsecutive.length);
+			for (let end = start + minLength; end <= maxEnd; end++) {
+				const slice = dedupedConsecutive.slice(start, end);
+				const sig = slice.join(" → ");
+				const existing = pathCounts.get(sig);
+				if (existing) {
+					existing.count += 1;
+				} else {
+					pathCounts.set(sig, { path: slice, count: 1 });
+				}
+			}
+		}
+	}
+
+	return Array.from(pathCounts.entries())
+		.map(([signature, { path, count }]) => ({
+			signature,
+			path,
+			occurrences: count,
+		}))
+		.sort((a, b) => {
+			if (b.occurrences !== a.occurrences) return b.occurrences - a.occurrences;
+			return b.path.length - a.path.length;
+		});
+}
+
+export function clusterIntoWorkflows(
+	clusters: PathCluster[],
+	cli: string,
+	options: { minSupport?: number; topK?: number } = {},
+): MinedWorkflow[] {
+	const minSupport = options.minSupport ?? 2;
+	const topK = options.topK ?? 10;
+
+	const filtered = clusters.filter(c => c.occurrences >= minSupport);
+	const deduped = removeSubPaths(filtered);
+
+	const totalOccurrences = clusters.reduce((sum, c) => sum + c.occurrences, 0) || 1;
+
+	return deduped.slice(0, topK).map(cluster => ({
+		name: cluster.path.join("-"),
+		cli,
+		path: [cluster.path],
+		support: cluster.occurrences,
+		confidence: cluster.occurrences / totalOccurrences,
+		source: "history" as const,
+	}));
+}
+
+function dedupeConsecutive(items: string[]): string[] {
+	const result: string[] = [];
+	for (const item of items) {
+		if (result.length === 0 || result[result.length - 1] !== item) {
+			result.push(item);
+		}
+	}
+	return result;
+}
+
+function removeSubPaths(clusters: PathCluster[]): PathCluster[] {
+	const sortedByLength = [...clusters].sort((a, b) => b.path.length - a.path.length);
+	const kept: PathCluster[] = [];
+
+	for (const cluster of sortedByLength) {
+		const sig = cluster.signature;
+		const alreadyCoveredBy = kept.find(k =>
+			k.signature.includes(sig) && k.occurrences >= cluster.occurrences * 0.8,
+		);
+		if (!alreadyCoveredBy) {
+			kept.push(cluster);
+		}
+	}
+
+	return kept.sort((a, b) => b.occurrences - a.occurrences);
+}

package/src/parse.ts

@@ -0,0 +1,321 @@
+import type { CLINode, Flag, Arg } from "./types";
+
+export function parseHelp(name: string, helpText: string): CLINode {
+	const lines = helpText.split("\n");
+	const node: CLINode = { name };
+
+	const descLine = findDescription(lines);
+	if (descLine) node.description = descLine;
+
+	node.subcommands = parseCommands(lines);
+	node.flags = parseFlags(lines);
+	node.args = parseUsageArgs(lines);
+
+	if (node.subcommands.length === 0) delete node.subcommands;
+	if (node.flags.length === 0) delete node.flags;
+	if (node.args.length === 0) delete node.args;
+
+	return node;
+}
+
+function findDescription(lines: string[]): string | undefined {
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		if (/^(usage|commands|flags|options|available|management|version|\$|the commands)/i.test(trimmed)) continue;
+		if (/^[-\s]/.test(trimmed)) continue;
+		if (/^(USAGE|CORE|GITHUB|ADDITIONAL|HELP|EXTENSION)/i.test(trimmed)) continue;
+		if (trimmed.length > 10 && trimmed.length < 200 && !trimmed.startsWith("--") && !trimmed.startsWith("{")) {
+			return trimmed.replace(/[.:]+$/, "").trim();
+		}
+	}
+	return undefined;
+}
+
+function parseCommands(lines: string[]): CLINode[] {
+	const commands: CLINode[] = [];
+	const seen = new Set<string>();
+	let inSection = false;
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]!;
+		const trimmed = line.trim();
+
+		if (isCommandSectionHeader(trimmed)) {
+			inSection = true;
+			continue;
+		}
+
+		if (isNpmAllCommands(trimmed)) {
+			parseNpmCommandList(lines, i, commands, seen);
+			continue;
+		}
+
+		if (isGoCommandLine(line)) {
+			const match = line.match(/^\t(\S+)\s{2,}(.+)/);
+			if (match && !seen.has(match[1]!)) {
+				seen.add(match[1]!);
+				commands.push({ name: match[1]!, description: match[2]!.trim() });
+			}
+			continue;
+		}
+
+		if (inSection) {
+			if (!trimmed) {
+				inSection = false;
+				continue;
+			}
+
+			if (isNonCommandSection(trimmed)) {
+				inSection = false;
+				continue;
+			}
+
+			const cmd = parseCommandLine(trimmed);
+			if (cmd && !seen.has(cmd.name)) {
+				seen.add(cmd.name);
+				commands.push(cmd);
+			}
+		}
+	}
+
+	return commands;
+}
+
+function isCommandSectionHeader(line: string): boolean {
+	const cleaned = line.replace(/[:\s]+$/, "").toLowerCase();
+	return /^(commands|common commands|management commands|available commands|subcommands|core commands|github actions commands|additional commands|extension commands|help commands|alias commands)/.test(cleaned)
+		|| /^(basic commands|deploy commands|cluster management|troubleshooting|advanced commands|settings commands|configuration|manage your dependencies|review your dependencies|run your scripts|other)/.test(cleaned)
+		|| /^(start a working area|work on the current change|examine the history|grow.*mark.*tweak|collaborate|ancillary commands|interacting with others|low-level commands)/i.test(cleaned);
+}
+
+function isNonCommandSection(line: string): boolean {
+	const cleaned = line.replace(/[:\s]+$/, "").toLowerCase();
+	return /^(flags|options|usage|examples|environment|learn more|global|see '|find more|use "|\$|additional help|inherited)/.test(cleaned);
+}
+
+function parseCommandLine(line: string): CLINode | null {
+	let match = line.match(/^(?:(\w{1,4}),\s+)?(\S+?)[:,]?\s{2,}(.+)/);
+	if (match) {
+		const alias = match[1];
+		const name = match[2]!.replace(/[*:,]+$/, "");
+		const desc = match[3]!.trim();
+		if (name.startsWith("-") || name.length === 0) return null;
+		const node: CLINode = { name, description: desc };
+		if (alias) node.aliases = [alias];
+		return node;
+	}
+
+	match = line.match(/^(\S+)\s{2,}(.+)/);
+	if (match) {
+		const name = match[1]!.replace(/[*:,]+$/, "");
+		if (name.startsWith("-") || name.length === 0) return null;
+		return { name, description: match[2]!.trim() };
+	}
+
+	return null;
+}
+
+function isGoCommandLine(line: string): boolean {
+	return /^\t\S+\s{2,}/.test(line);
+}
+
+function isNpmAllCommands(line: string): boolean {
+	return /^all commands/i.test(line.trim().replace(":", ""));
+}
+
+function parseNpmCommandList(lines: string[], startIdx: number, commands: CLINode[], seen: Set<string>) {
+	let foundAny = false;
+	for (let i = startIdx + 1; i < lines.length; i++) {
+		const line = lines[i]!.trim();
+		if (!line) {
+			if (foundAny) break;
+			continue;
+		}
+		if (/^specify|^more|^configuration|^npm@|^or on/i.test(line)) break;
+		const names = line.split(/[,\s]+/).filter(n => n.length > 0 && !n.startsWith("-") && /^[a-z]/.test(n));
+		for (const name of names) {
+			if (!seen.has(name)) {
+				seen.add(name);
+				commands.push({ name });
+				foundAny = true;
+			}
+		}
+	}
+}
+
+function parseFlags(lines: string[]): Flag[] {
+	const flags: Flag[] = [];
+	const seen = new Set<string>();
+	let inFlagSection = false;
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]!;
+		const trimmed = line.trim();
+
+		if (/^(flags|options|global flags|global options)/i.test(trimmed.replace(/[:\s]+$/, ""))) {
+			inFlagSection = true;
+			continue;
+		}
+
+		if (inFlagSection) {
+			if (!trimmed) {
+				if (i + 1 < lines.length) {
+					const next = lines[i + 1]?.trim() ?? "";
+					if (next && !next.startsWith("-") && !/^\s/.test(lines[i + 1] ?? "")) {
+						inFlagSection = false;
+					}
+				}
+				continue;
+			}
+
+			if (isCommandSectionHeader(trimmed) || isNonCommandSection(trimmed)) {
+				if (!/^(flags|options|global)/i.test(trimmed.replace(/[:\s]+$/, ""))) {
+					inFlagSection = false;
+					continue;
+				}
+			}
+
+			const flag = parseFlagLine(trimmed);
+			if (flag && !seen.has(flag.name)) {
+				seen.add(flag.name);
+				flags.push(flag);
+			}
+		}
+	}
+
+	return flags;
+}
+
+function parseFlagLine(line: string): Flag | null {
+	let match = line.match(/^\s*(-(\w),\s+)?--(\S+?)(?:=<([^>]+)>|[= ]<([^>]+)>|\s+<([^>]+)>)?\s{2,}(.*)/);
+	if (match) {
+		const short = match[2];
+		const name = match[3]!.replace(/[=,]+$/, "");
+		const valHint = match[4] || match[5] || match[6];
+		const desc = match[7]?.trim();
+		return buildFlag(name, short, valHint, desc);
+	}
+
+	match = line.match(/^\s*(-(\w),\s+)?--([\w-]+)\s*(.*)/);
+	if (match) {
+		const short = match[2];
+		const name = match[3]!;
+		const rest = match[4]?.trim() ?? "";
+		const flag: Flag = { name, type: "boolean" };
+		if (short) flag.short = short;
+		if (rest) flag.description = rest;
+		return flag;
+	}
+
+	match = line.match(/^\s*-(\w),\s+--?([\w-]+)\s*(.*)/);
+	if (match) {
+		const short = match[1];
+		const name = match[2]!;
+		const rest = match[3]?.trim() ?? "";
+		const flag: Flag = { name, type: "boolean" };
+		if (short) flag.short = short;
+		if (rest) flag.description = rest;
+		return flag;
+	}
+
+	return null;
+}
+
+function buildFlag(name: string, short?: string, valHint?: string, desc?: string): Flag {
+	let type: Flag["type"] = "boolean";
+	if (valHint) {
+		if (/^(num|int|count)/i.test(valHint)) type = "number";
+		else type = "string";
+	}
+
+	const flag: Flag = { name, type };
+	if (short) flag.short = short;
+	if (desc) flag.description = desc;
+	return flag;
+}
+
+function parseUsageArgs(lines: string[]): Arg[] {
+	const args: Arg[] = [];
+
+	for (const line of lines) {
+		if (!/^usage/i.test(line.trim())) continue;
+
+		const argMatches = line.matchAll(/<(\w+(?:\.\.\.)?)>|\[(\w+(?:\.\.\.)?)\]/g);
+		for (const m of argMatches) {
+			if (m[1]) {
+				const name = m[1].replace("...", "");
+				const variadic = m[1].endsWith("...");
+				if (!isKnownPlaceholder(name)) {
+					args.push({ name, required: true, variadic });
+				}
+			} else if (m[2]) {
+				const name = m[2].replace("...", "");
+				const variadic = m[2].endsWith("...");
+				if (!isKnownPlaceholder(name)) {
+					args.push({ name, required: false, variadic });
+				}
+			}
+		}
+	}
+
+	return args;
+}
+
+function isKnownPlaceholder(name: string): boolean {
+	return /^(path|name|value|envvar|val)$/i.test(name);
+}
+
+export async function parseHelpRecursive(
+	binary: string,
+	args: string[] = [],
+	maxDepth = 3,
+	depth = 0,
+): Promise<CLINode> {
+	const helpText = await runHelp(binary, args);
+	const name = args.length > 0 ? args[args.length - 1]! : binary;
+	const node = parseHelp(name, helpText);
+
+	if (depth >= maxDepth) return node;
+
+	if (node.subcommands) {
+		const resolved: CLINode[] = [];
+		for (const sub of node.subcommands) {
+			try {
+				const child = await parseHelpRecursive(binary, [...args, sub.name], maxDepth, depth + 1);
+				if (sub.description && !child.description) child.description = sub.description;
+				if (sub.aliases) child.aliases = sub.aliases;
+				resolved.push(child);
+			} catch {
+				resolved.push(sub);
+			}
+		}
+		node.subcommands = resolved;
+	}
+
+	return node;
+}
+
+async function runHelp(binary: string, args: string[]): Promise<string> {
+	const proc = Bun.spawn([binary, ...args, "--help"], {
+		stdout: "pipe",
+		stderr: "pipe",
+	});
+
+	const timeout = setTimeout(() => proc.kill(), 5000);
+
+	const [stdout, stderr] = await Promise.all([
+		new Response(proc.stdout).text(),
+		new Response(proc.stderr).text(),
+	]);
+
+	clearTimeout(timeout);
+	await proc.exited;
+
+	const output = stdout || stderr;
+	if (!output.trim()) {
+		throw new Error(`No help output from: ${binary} ${args.join(" ")} --help`);
+	}
+
+	return output;
+}