@crafter/cli-tree 0.1.3 → 0.2.1

package/src/miner/cross-cli.ts

@@ -0,0 +1,216 @@
+import type { HistoryEntry, Session } from "./types";
+import { segmentSessions } from "./sessions";
+import { parseHistory, readHistoryFile, defaultHistoryPath } from "./history";
+
+export interface CrossCliStep {
+	cli: string;
+	subcommand: string;
+}
+
+export interface CrossCliWorkflow {
+	path: CrossCliStep[];
+	support: number;
+	signature: string;
+	uniqueCLIs: number;
+}
+
+export interface CrossCliOptions {
+	historyPath?: string;
+	sessionGapMinutes?: number;
+	minSupport?: number;
+	minPathLength?: number;
+	maxPathLength?: number;
+	topK?: number;
+	/** Only include workflows that cross at least this many distinct CLIs */
+	minDistinctCLIs?: number;
+	/** If non-empty, only consider entries whose cli[0] is in this set */
+	allowedCLIs?: string[];
+	/** Ignore CLIs that add noise (ls, cd, etc.) */
+	ignoreCLIs?: string[];
+}
+
+export interface CrossCliResult {
+	workflows: CrossCliWorkflow[];
+	sessionsAnalyzed: number;
+	distinctCLIs: string[];
+	totalTransitions: number;
+}
+
+const DEFAULT_IGNORE = new Set([
+	"ls",
+	"cd",
+	"pwd",
+	"echo",
+	"cat",
+	"clear",
+	"exit",
+	"env",
+	"export",
+	"which",
+	"source",
+	".",
+	"sudo",
+	"man",
+	"open",
+]);
+
+function entryToStep(entry: HistoryEntry, ignore: Set<string>): CrossCliStep | null {
+	const [raw, ...rest] = entry.argv;
+	if (!raw) return null;
+
+	// Skip absolute paths, relative paths, and variables being used as the "cli"
+	if (raw.startsWith("/") || raw.startsWith("./") || raw.startsWith("../") || raw.startsWith("$")) return null;
+
+	// CLI names must look like program names: alphanumeric start, no slashes
+	if (!/^[a-zA-Z0-9_-]+$/.test(raw)) return null;
+
+	if (ignore.has(raw)) return null;
+
+	const sub =
+		rest.find(arg => !arg.startsWith("-") && !arg.startsWith("$") && /^[a-z]/i.test(arg)) ?? "(root)";
+	return { cli: raw, subcommand: sub };
+}
+
+function dedupeConsecutive(steps: CrossCliStep[]): CrossCliStep[] {
+	const out: CrossCliStep[] = [];
+	for (const s of steps) {
+		const last = out[out.length - 1];
+		if (!last || last.cli !== s.cli || last.subcommand !== s.subcommand) {
+			out.push(s);
+		}
+	}
+	return out;
+}
+
+function stepKey(step: CrossCliStep): string {
+	return `${step.cli} ${step.subcommand}`;
+}
+
+function pathSignature(path: CrossCliStep[]): string {
+	return path.map(stepKey).join(" → ");
+}
+
+function countDistinctCLIs(path: CrossCliStep[]): number {
+	return new Set(path.map(s => s.cli)).size;
+}
+
+/**
+ * Mine workflows that cross multiple CLIs. Unlike `mineCli`, this does NOT filter
+ * to a single binary up front. It looks at every command in a session and detects
+ * recurring sequences that weave between tools — e.g. `git push → gh pr create`,
+ * `docker build → docker push → kubectl apply`, `bun test → git commit → git push`.
+ */
+export async function mineCrossCli(options: CrossCliOptions = {}): Promise<CrossCliResult> {
+	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 sessions = segmentSessions(entries, options.sessionGapMinutes ?? 10);
+
+	const ignore = new Set(options.ignoreCLIs ?? Array.from(DEFAULT_IGNORE));
+	const allowed = options.allowedCLIs && options.allowedCLIs.length > 0 ? new Set(options.allowedCLIs) : null;
+
+	const minSupport = options.minSupport ?? 3;
+	const minLen = options.minPathLength ?? 2;
+	const maxLen = options.maxPathLength ?? 5;
+	const minDistinctCLIs = options.minDistinctCLIs ?? 2;
+
+	const pathCounts = new Map<string, { path: CrossCliStep[]; count: number }>();
+	const distinctCLIs = new Set<string>();
+	let totalTransitions = 0;
+
+	for (const session of sessions) {
+		const steps: CrossCliStep[] = [];
+		for (const entry of session.entries) {
+			const step = entryToStep(entry, ignore);
+			if (!step) continue;
+			if (allowed && !allowed.has(step.cli)) continue;
+			distinctCLIs.add(step.cli);
+			steps.push(step);
+		}
+
+		const deduped = dedupeConsecutive(steps);
+		if (deduped.length >= 2) totalTransitions += deduped.length - 1;
+
+		for (let start = 0; start < deduped.length; start++) {
+			const maxEnd = Math.min(start + maxLen, deduped.length);
+			for (let end = start + minLen; end <= maxEnd; end++) {
+				const slice = deduped.slice(start, end);
+				if (countDistinctCLIs(slice) < minDistinctCLIs) continue;
+				const sig = pathSignature(slice);
+				const existing = pathCounts.get(sig);
+				if (existing) {
+					existing.count += 1;
+				} else {
+					pathCounts.set(sig, { path: slice, count: 1 });
+				}
+			}
+		}
+	}
+
+	const clusters = Array.from(pathCounts.entries())
+		.map(([signature, { path, count }]) => ({
+			signature,
+			path,
+			support: count,
+			uniqueCLIs: countDistinctCLIs(path),
+		}))
+		.filter(c => c.support >= minSupport)
+		.sort((a, b) => {
+			// Prefer more-distinct, then longer, then higher-support
+			if (b.uniqueCLIs !== a.uniqueCLIs) return b.uniqueCLIs - a.uniqueCLIs;
+			if (b.path.length !== a.path.length) return b.path.length - a.path.length;
+			return b.support - a.support;
+		});
+
+	// Remove subpaths fully contained in longer kept paths
+	const keptPaths: CrossCliWorkflow[] = [];
+	for (const cluster of clusters) {
+		const coveredBy = keptPaths.find(
+			k => k.signature !== cluster.signature && k.signature.includes(cluster.signature) && k.support >= cluster.support * 0.7,
+		);
+		if (!coveredBy) {
+			keptPaths.push({
+				path: cluster.path,
+				support: cluster.support,
+				signature: cluster.signature,
+				uniqueCLIs: cluster.uniqueCLIs,
+			});
+		}
+	}
+
+	const topK = options.topK ?? 10;
+
+	return {
+		workflows: keptPaths.slice(0, topK),
+		sessionsAnalyzed: sessions.length,
+		distinctCLIs: Array.from(distinctCLIs).sort(),
+		totalTransitions,
+	};
+}
+
+/**
+ * Convert a CrossCliWorkflow into a Workflow suitable for the flow renderer.
+ * Each node is labeled with "<cli> <sub>" so the DAG makes the cross-CLI nature obvious.
+ */
+export function crossCliToFlowWorkflow(workflow: CrossCliWorkflow) {
+	const nodes = workflow.path.map((step, idx) => ({
+		id: `n${idx}`,
+		command: [step.cli, step.subcommand],
+		label: `${step.cli} ${step.subcommand}`,
+	}));
+	const edges = [];
+	for (let i = 0; i < nodes.length - 1; i++) {
+		edges.push({ from: nodes[i]!.id, to: nodes[i + 1]!.id });
+	}
+	return {
+		name: workflow.signature,
+		description: `Cross-CLI workflow seen ${workflow.support}× (${workflow.uniqueCLIs} tools)`,
+		cli: workflow.path[0]?.cli ?? "multi",
+		nodes,
+		edges,
+	};
+}

package/src/miner/index.ts

@@ -5,9 +5,25 @@ import { extractPaths, clusterIntoWorkflows } from "./workflows";
 import { computeStats } from "./stats";
 import { suggestSkills, type SkillSuggestion } from "./suggest";
 import { minedToFlowWorkflow } from "./to-flow";
+import { computeActivity, formatTimeRange, type ActivityProfile } from "./activity";
+import { sparkline, labeledSparkline } from "./sparkline";
+import { mineCrossCli, crossCliToFlowWorkflow, type CrossCliOptions, type CrossCliResult, type CrossCliWorkflow, type CrossCliStep } from "./cross-cli";
 import type { HistoryEntry, Session, Transition, MinedWorkflow, CliUsageStats, MineOptions } from "./types";
 
-export type { HistoryEntry, Session, Transition, MinedWorkflow, CliUsageStats, MineOptions, SkillSuggestion };
+export type {
+	HistoryEntry,
+	Session,
+	Transition,
+	MinedWorkflow,
+	CliUsageStats,
+	MineOptions,
+	SkillSuggestion,
+	ActivityProfile,
+	CrossCliOptions,
+	CrossCliResult,
+	CrossCliWorkflow,
+	CrossCliStep,
+};
 export {
 	parseHistory,
 	readHistoryFile,
@@ -25,6 +41,12 @@ export {
 	computeStats,
 	suggestSkills,
 	minedToFlowWorkflow,
+	computeActivity,
+	formatTimeRange,
+	sparkline,
+	labeledSparkline,
+	mineCrossCli,
+	crossCliToFlowWorkflow,
 };
 
 export interface MineResult {
@@ -34,6 +56,7 @@ export interface MineResult {
 	workflows: MinedWorkflow[];
 	suggestions: SkillSuggestion[];
 	sessionsAnalyzed: number;
+	activity: ActivityProfile;
 }
 
 export async function mineCli(cli: string, options: MineOptions = {}): Promise<MineResult> {
@@ -67,6 +90,9 @@ export async function mineCli(cli: string, options: MineOptions = {}): Promise<M
 
 	const suggestions = suggestSkills(workflows, stats);
 
+	const cliEntries = entries.filter(e => e.argv[0] === cli);
+	const activity = computeActivity(cliEntries);
+
 	return {
 		cli,
 		stats,
@@ -74,5 +100,6 @@ export async function mineCli(cli: string, options: MineOptions = {}): Promise<M
 		workflows,
 		suggestions,
 		sessionsAnalyzed: cliSessions.length,
+		activity,
 	};
 }

package/src/miner/sparkline.ts

@@ -0,0 +1,43 @@
+/**
+ * Minimal Unicode sparkline for a numeric array.
+ *
+ * We could depend on @crafter/charts for this, but keeping zero deps means
+ * clitree stays as a single focused package. The logic is trivial: bucket each
+ * value into one of 8 block characters (▁▂▃▄▅▆▇█), with a distinct marker
+ * for zero values so absence is visible at a glance.
+ */
+
+const BLOCKS = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"] as const;
+
+export interface SparklineOptions {
+	/**
+	 * Character used for zero values. Defaults to "·" (middle dot) so
+	 * zero-days are visually distinct from missing data instead of blank.
+	 */
+	zero?: string;
+}
+
+export function sparkline(data: number[], opts: SparklineOptions = {}): string {
+	if (data.length === 0) return "";
+	const zero = opts.zero ?? "·";
+	const max = Math.max(...data);
+	if (max === 0) return zero.repeat(data.length);
+
+	return data
+		.map(value => {
+			if (value === 0) return zero;
+			const idx = Math.min(
+				BLOCKS.length - 1,
+				Math.max(0, Math.round((value / max) * (BLOCKS.length - 1))),
+			);
+			return BLOCKS[idx];
+		})
+		.join("");
+}
+
+/**
+ * Render a labeled row like "Mon ▁▃▅█▇▅▃▂" — used for day-of-week activity.
+ */
+export function labeledSparkline(label: string, data: number[], labelWidth = 3): string {
+	return `${label.padEnd(labelWidth)} ${sparkline(data)}`;
+}