@crafter/cli-tree 0.1.2 → 0.2.0

package/src/cli.ts

@@ -4,13 +4,21 @@ import { printTree, treeToString, treeToHtml } from "./index";
 import type { TreeOptions } from "./types";
 import { parseWorkflow, validateWorkflow, flowToAnsi, flowToString, flowToHtml } from "./flow";
 import type { FlowRenderOptions } from "./flow/types";
-import { mineCli, minedToFlowWorkflow } from "./miner";
+import {
+	mineCli,
+	minedToFlowWorkflow,
+	mineCrossCli,
+	crossCliToFlowWorkflow,
+	sparkline,
+	labeledSparkline,
+	formatTimeRange,
+} from "./miner";
 import { runArchaeology, NullDelegate } from "./archaeology";
 
 const args = process.argv.slice(2);
 const subcommand = args[0];
 
-const HELP_SUBCOMMANDS = new Set(["flow", "mine", "archaeology"]);
+const HELP_SUBCOMMANDS = new Set(["flow", "mine", "archaeology", "safe-help", "cross"]);
 const isHelpFlag = args.includes("--help") || args.includes("-h");
 
 if (!subcommand || (isHelpFlag && !HELP_SUBCOMMANDS.has(subcommand ?? ""))) {
@@ -22,6 +30,8 @@ if (isHelpFlag) {
 	if (subcommand === "flow") printFlowHelp();
 	else if (subcommand === "mine") printMineHelp();
 	else if (subcommand === "archaeology") printArchaeologyHelp();
+	else if (subcommand === "safe-help") printSafeHelpHelp();
+	else if (subcommand === "cross") printCrossHelp();
 	else printMainHelp();
 	process.exit(0);
 }
@@ -32,6 +42,10 @@ if (subcommand === "flow") {
 	await runMine(args.slice(1));
 } else if (subcommand === "archaeology") {
 	await runArchaeologyCmd(args.slice(1));
+} else if (subcommand === "safe-help") {
+	await runSafeHelp(args.slice(1));
+} else if (subcommand === "cross") {
+	await runCross(args.slice(1));
 } else {
 	await runTree(args);
 }
@@ -44,23 +58,101 @@ function printMainHelp() {
     clitree <binary> [options]              Render command tree from --help
     clitree flow <file> [options]           Render a workflow YAML as a DAG
     clitree mine <binary> [options]         Mine shell history for workflows
+    clitree cross [options]                 Detect cross-CLI workflows (git + gh, docker + kubectl)
     clitree archaeology <binary> [options]  Full analysis: tree + mining + (LLM)
+    clitree safe-help <binary> [sub...]     Fetch clean help for any CLI (no pager, no overstriking)
 
   Examples:
     clitree docker                          # basic tree
     clitree mine git                        # "what workflows do I repeat with git?"
+    clitree cross                           # cross-CLI flows across your history
     clitree archaeology bun                 # tree + mining + LLM archaeology
+    clitree safe-help git commit            # avoid the git man-page pager trap
 
   Subcommands:
     tree          Parse --help output (default; passing a binary name invokes this)
     flow          Render a workflow YAML file as an ASCII DAG
-    mine          Discover workflows from your shell history
+    mine          Discover workflows from your shell history (single CLI)
+    cross         Discover workflows that span multiple CLIs (e.g. git → gh)
     archaeology   Run full analysis (tree + mine + LLM proposals when available)
+    safe-help     Return inline help for any CLI, handling pager/overstrike edge cases
 
   Help for a subcommand: clitree <subcommand> --help
 `);
 }
 
+function printCrossHelp() {
+	console.log(`
+  clitree cross — Mine cross-CLI workflows from your shell history
+
+  Usage:
+    clitree cross [options]
+
+  This is mineCli's bigger sibling. Instead of filtering history to a single
+  binary, it looks at every command in a session and finds sequences that weave
+  between tools — e.g.:
+
+    git push → gh pr create
+    docker build → docker push → kubectl apply
+    bun test → git commit → git push
+
+  These patterns are invisible to 'clitree mine <cli>' because they cross boundaries.
+
+  Examples:
+    clitree cross                           # top 10 cross-CLI workflows
+    clitree cross --top-k 5                 # just the top 5
+    clitree cross --only git,gh,docker      # restrict to a set of CLIs
+    clitree cross --format json             # raw data
+
+  Options:
+    --top-k <n>             Max workflows to return (default: 10)
+    --min-support <n>       Minimum occurrences (default: 3)
+    --min-path-length <n>   Minimum chain length (default: 2)
+    --max-path-length <n>   Maximum chain length (default: 5)
+    --min-distinct-clis <n> Require at least this many distinct CLIs (default: 2)
+    --only <csv>            Whitelist: only include these CLIs (comma-separated)
+    --format <fmt>          ansi (default) or json
+    --no-color              Disable ANSI colors
+    --no-flow               Skip DAG rendering of the top workflow
+    -h, --help              Show this help
+`);
+}
+
+function printSafeHelpHelp() {
+	console.log(`
+  clitree safe-help — Fetch clean help output for any CLI
+
+  Usage:
+    clitree safe-help <binary> [subcommand...] [options]
+
+  Why this exists:
+    Running '<cli> --help' directly is a minefield on agents and scripts:
+      - 'git commit --help' opens a pager in a TTY and hangs
+      - Piping 'git <sub> --help' returns nroff with overstrike (ffiixxuupp)
+      - Some CLIs use 'help <sub>' instead of '<sub> --help'
+      - macOS man pages emit \\b sequences that need col -bx
+
+    safe-help tries the right variants in order, cleans overstrikes, and
+    returns plain text every time.
+
+  Strategy (in order):
+    1. <cli> <sub> -h                        — short inline help
+    2. <cli> <sub> --help                    — long help (captured, overstrike-stripped)
+    3. <cli> help <sub>                      — alternate syntax
+    4. MANPAGER=cat man <cli>-<sub> | col -bx — final man fallback
+
+  Examples:
+    clitree safe-help git commit
+    clitree safe-help docker run
+    clitree safe-help kubectl get pods
+    clitree safe-help bun install
+
+  Options:
+    --no-color           Disable ANSI codes (auto-detects non-TTY)
+    -h, --help           Show this help
+`);
+}
+
 function printMineHelp() {
 	console.log(`
   clitree mine — Mine your shell history for CLI workflows
@@ -70,22 +162,26 @@ function printMineHelp() {
 
   Examples:
     clitree mine git
+    clitree mine git --top-k 3                    # render top 3 workflows as DAGs
     clitree mine docker --min-support 5 --with-flow
     clitree mine bun --format json > bun-flows.json
     clitree mine git --no-color | tee report.txt
+    clitree mine git --no-activity                # skip temporal sparklines
 
   Options:
     --min-support <n>    Minimum occurrences to count as a workflow (default: 3)
     --history-path <p>   Custom shell history path (default: ~/.zsh_history)
     --format <fmt>       Output format: ansi (default), json
-    --max-paths <n>      Max workflows to show (default: 10)
-    --with-flow          Always render the top workflow as an ASCII DAG
-    --no-flow            Never render the DAG (overrides auto-detect)
+    --max-paths <n>      Max workflows to show in text list (default: 10)
+    --top-k <n>          Render top N workflows as DAGs (default: 1)
+    --with-flow          Include 2-step workflows in DAG rendering
+    --no-flow            Skip DAG rendering entirely
+    --no-activity        Skip hour/day/30-day activity sparklines
     --no-color           Disable ANSI colors (also auto-disabled when stdout is not a TTY)
     -h, --help           Show this help
 
-  By default, the top workflow is rendered as a DAG only when it has 3+ steps.
-  Use --with-flow to force it on even for 2-step chains, or --no-flow to skip.
+  By default, the top 3+ step workflow is rendered as a DAG.
+  --top-k bumps that to N distinct workflows stacked on top of each other.
 `);
 }
 
@@ -272,6 +368,138 @@ async function readStdin(): Promise<string> {
 	return Buffer.concat(chunks).toString("utf-8");
 }
 
+function stripOverstrike(text: string): string {
+	// Strip nroff bold via char\bchar, underline via _\bchar, and stray control chars.
+	// This is what `col -bx` does.
+	return text
+		.replace(/(.)\b\1/g, "$1")
+		.replace(/_\b(.)/g, "$1")
+		.replace(/\b/g, "")
+		.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "");
+}
+
+function looksLikeHelp(text: string): boolean {
+	if (!text.trim()) return false;
+	if (text.length < 40) return false;
+	const firstChunk = text.slice(0, 200).toLowerCase();
+	// Error messages from unknown subcommands or unsupported flags
+	if (/(unknown|invalid|no such|not a \w+ command|flag needs an argument|unrecognized)/.test(firstChunk)) {
+		return false;
+	}
+	// "Run '... --help' for more information" is a hint, not the help itself
+	if (/run '.+' for more information/.test(firstChunk)) return false;
+	return true;
+}
+
+async function tryHelpVariant(binary: string, argv: string[], timeoutMs = 5000): Promise<string | null> {
+	try {
+		const proc = Bun.spawn([binary, ...argv], {
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, PAGER: "cat", MANPAGER: "cat", GIT_PAGER: "cat" },
+		});
+
+		const timer = setTimeout(() => proc.kill(), timeoutMs);
+
+		const [stdout, stderr] = await Promise.all([
+			new Response(proc.stdout).text(),
+			new Response(proc.stderr).text(),
+		]);
+		clearTimeout(timer);
+		await proc.exited;
+
+		const combined = stdout || stderr;
+		if (!looksLikeHelp(combined)) return null;
+		return stripOverstrike(combined);
+	} catch {
+		return null;
+	}
+}
+
+async function tryManPage(binary: string, subPath: string[], timeoutMs = 5000): Promise<string | null> {
+	// Try 'man binary-sub' (git-commit), then 'man binary sub' as a fallback.
+	const candidates = [
+		subPath.length > 0 ? [`${binary}-${subPath.join("-")}`] : [binary],
+		[binary, ...subPath],
+	];
+
+	for (const args of candidates) {
+		try {
+			const proc = Bun.spawn(["man", ...args], {
+				stdout: "pipe",
+				stderr: "pipe",
+				env: { ...process.env, MANPAGER: "cat", PAGER: "cat" },
+			});
+
+			const timer = setTimeout(() => proc.kill(), timeoutMs);
+			const [stdout] = await Promise.all([
+				new Response(proc.stdout).text(),
+				new Response(proc.stderr).text(),
+			]);
+			clearTimeout(timer);
+			await proc.exited;
+
+			if (looksLikeHelp(stdout)) return stripOverstrike(stdout);
+		} catch {}
+	}
+	return null;
+}
+
+async function runSafeHelp(args: string[]) {
+	let binary: string | null = null;
+	const subPath: string[] = [];
+
+	for (const arg of args) {
+		if (arg === "--no-color" || arg === "--help" || arg === "-h") continue;
+		if (!binary) {
+			binary = arg;
+		} else {
+			subPath.push(arg);
+		}
+	}
+
+	if (!binary) {
+		console.error("Error: provide a binary name");
+		console.error("Run 'clitree safe-help --help' for usage");
+		process.exit(1);
+	}
+
+	// Strategy in order of preference:
+	// 1. `<cli> <sub> -h`  — short inline help, no pager
+	// 2. `<cli> <sub> --help` — long form, overstrike-stripped
+	// 3. `<cli> help <sub>` — alternate syntax (git, go, bun)
+	// 4. `man <cli>-<sub>` or `man <cli> <sub>` — final fallback
+	const variants: Array<{ label: string; args: string[] }> = [
+		{ label: "short help (-h)", args: [...subPath, "-h"] },
+		{ label: "long help (--help)", args: [...subPath, "--help"] },
+	];
+
+	if (subPath.length > 0) {
+		variants.push({ label: "help subcommand", args: ["help", ...subPath] });
+	}
+
+	for (const variant of variants) {
+		const output = await tryHelpVariant(binary, variant.args);
+		if (output) {
+			process.stdout.write(output);
+			if (!output.endsWith("\n")) process.stdout.write("\n");
+			return;
+		}
+	}
+
+	// Last resort: man page
+	const manOutput = await tryManPage(binary, subPath);
+	if (manOutput) {
+		process.stdout.write(manOutput);
+		if (!manOutput.endsWith("\n")) process.stdout.write("\n");
+		return;
+	}
+
+	console.error(`Error: could not fetch help for ${binary} ${subPath.join(" ")}`);
+	console.error("Tried: -h, --help, help subcommand, and man page.");
+	process.exit(1);
+}
+
 function shouldUseColor(args: string[]): boolean {
 	if (args.includes("--no-color")) return false;
 	if (process.env.NO_COLOR) return false;
@@ -303,6 +531,8 @@ async function runMine(args: string[]) {
 	let format: "ansi" | "json" = "ansi";
 	let maxPaths = 10;
 	let withFlow: "auto" | "on" | "off" = "auto";
+	let topK = 1;
+	let showActivity = true;
 
 	for (let i = 0; i < args.length; i++) {
 		const arg = args[i]!;
@@ -314,10 +544,15 @@ async function runMine(args: string[]) {
 			format = args[++i] as "ansi" | "json";
 		} else if (arg === "--max-paths" && args[i + 1]) {
 			maxPaths = Number.parseInt(args[++i]!, 10);
+		} else if (arg === "--top-k" && args[i + 1]) {
+			topK = Number.parseInt(args[++i]!, 10);
+			if (withFlow === "auto") withFlow = "on";
 		} else if (arg === "--with-flow" || arg === "--flow") {
 			withFlow = "on";
 		} else if (arg === "--no-flow") {
 			withFlow = "off";
+		} else if (arg === "--no-activity") {
+			showActivity = false;
 		} else if (arg !== "--no-color" && !arg.startsWith("-")) {
 			binary = arg;
 		}
@@ -355,6 +590,10 @@ async function runMine(args: string[]) {
 			console.log();
 		}
 
+		if (showActivity && result.activity.total > 0) {
+			renderActivitySection(result.activity, C);
+		}
+
 		if (result.workflows.length > 0) {
 			console.log(`${C.bold}Discovered workflows:${C.reset}`);
 			for (const wf of result.workflows.slice(0, maxPaths)) {
@@ -380,19 +619,23 @@ async function runMine(args: string[]) {
 			console.log();
 		}
 
-		// Pick the top workflow worth visualizing as a DAG.
-		// In "auto" mode, prefer the highest-support workflow with 3+ steps —
-		// 2-step chains are more readable as text than as boxed diagrams.
-		// In "on" mode, render whatever is the top regardless of length.
-		// In "off" mode, skip.
+		// Pick the top-K workflows worth visualizing as DAGs.
+		// Auto mode renders only the first 3+ step workflow.
+		// `--top-k N` renders up to N distinct workflows (skipping shorter 2-step ones by default).
 		if (withFlow !== "off") {
 			const minSteps = withFlow === "on" ? 2 : 3;
-			const topForFlow = pickWorkflowForFlow(result.workflows, minSteps);
-			if (topForFlow) {
-				const flowWorkflow = minedToFlowWorkflow(topForFlow);
-				const rendered = shouldUseColor(args) ? flowToAnsi(flowWorkflow) : flowToString(flowWorkflow);
-				console.log(`${C.bold}Top workflow (visualized):${C.reset}`);
-				console.log(rendered);
+			const topK_effective = Math.max(1, topK);
+			const candidates = pickWorkflowsForFlow(result.workflows, minSteps, topK_effective);
+
+			if (candidates.length > 0) {
+				const header = candidates.length === 1 ? "Top workflow (visualized):" : `Top ${candidates.length} workflows (visualized):`;
+				console.log(`${C.bold}${header}${C.reset}`);
+				for (let i = 0; i < candidates.length; i++) {
+					if (i > 0) console.log(`${C.gray}${"─".repeat(60)}${C.reset}`);
+					const flowWorkflow = minedToFlowWorkflow(candidates[i]!);
+					const rendered = shouldUseColor(args) ? flowToAnsi(flowWorkflow) : flowToString(flowWorkflow);
+					console.log(rendered);
+				}
 				console.log();
 			}
 		}
@@ -402,15 +645,152 @@ async function runMine(args: string[]) {
 	}
 }
 
+function renderActivitySection(
+	activity: { hourOfDay: number[]; dayOfWeek: number[]; last30Days: number[]; firstSeen: number; lastSeen: number; total: number },
+	C: ReturnType<typeof makeColors>,
+) {
+	// Only show if we have timestamp data
+	if (activity.firstSeen === 0) return;
+
+	const dayNames = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+	console.log(`${C.bold}Activity:${C.reset}`);
+
+	const range = formatTimeRange(activity.firstSeen, activity.lastSeen);
+	console.log(`  ${C.dim}Tracked over:${C.reset} ${C.cyan}${range}${C.reset}`);
+
+	// Hour-of-day sparkline (24 chars wide)
+	const hourSpark = sparkline(activity.hourOfDay);
+	console.log(`  ${C.dim}Hour of day: ${C.reset}${C.cyan}${hourSpark}${C.reset} ${C.dim}(0h → 23h)${C.reset}`);
+
+	// Day-of-week mini bars
+	const dowMax = Math.max(...activity.dayOfWeek);
+	if (dowMax > 0) {
+		console.log(`  ${C.dim}Day of week:${C.reset}`);
+		for (let i = 0; i < 7; i++) {
+			const count = activity.dayOfWeek[i]!;
+			const barLen = dowMax > 0 ? Math.round((count / dowMax) * 20) : 0;
+			const bar = "█".repeat(Math.max(count > 0 ? 1 : 0, barLen));
+			console.log(`    ${C.gray}${dayNames[i]}${C.reset} ${C.cyan}${bar}${C.reset} ${C.dim}${count}${C.reset}`);
+		}
+	}
+
+	// Last 30 days sparkline
+	if (activity.last30Days.some(v => v > 0)) {
+		const monthSpark = sparkline(activity.last30Days);
+		console.log(`  ${C.dim}Last 30 days:${C.reset} ${C.cyan}${monthSpark}${C.reset} ${C.dim}(30d ago → today)${C.reset}`);
+	}
+	console.log();
+}
+
 function pickWorkflowForFlow<T extends { path: string[][]; support: number }>(
 	workflows: T[],
 	minSteps = 3,
 ): T | null {
+	const picked = pickWorkflowsForFlow(workflows, minSteps, 1);
+	return picked[0] ?? null;
+}
+
+function pickWorkflowsForFlow<T extends { path: string[][]; support: number }>(
+	workflows: T[],
+	minSteps: number,
+	topK: number,
+): T[] {
+	const result: T[] = [];
+	const signatures = new Set<string>();
 	for (const wf of workflows) {
 		const len = wf.path[0]?.length ?? 0;
-		if (len >= minSteps) return wf;
+		if (len < minSteps) continue;
+		const sig = wf.path[0]!.join(" → ");
+		if (signatures.has(sig)) continue;
+		signatures.add(sig);
+		result.push(wf);
+		if (result.length >= topK) break;
+	}
+	return result;
+}
+
+async function runCross(args: string[]) {
+	let format: "ansi" | "json" = "ansi";
+	let topK = 10;
+	let minSupport = 3;
+	let minPathLength = 2;
+	let maxPathLength = 5;
+	let minDistinctCLIs = 2;
+	let onlyList: string[] = [];
+	let withFlow = true;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]!;
+		if (arg === "--top-k" && args[i + 1]) {
+			topK = Number.parseInt(args[++i]!, 10);
+		} else if (arg === "--min-support" && args[i + 1]) {
+			minSupport = Number.parseInt(args[++i]!, 10);
+		} else if (arg === "--min-path-length" && args[i + 1]) {
+			minPathLength = Number.parseInt(args[++i]!, 10);
+		} else if (arg === "--max-path-length" && args[i + 1]) {
+			maxPathLength = Number.parseInt(args[++i]!, 10);
+		} else if (arg === "--min-distinct-clis" && args[i + 1]) {
+			minDistinctCLIs = Number.parseInt(args[++i]!, 10);
+		} else if (arg === "--only" && args[i + 1]) {
+			onlyList = args[++i]!.split(",").map(s => s.trim()).filter(Boolean);
+		} else if (arg === "--format" && args[i + 1]) {
+			format = args[++i] as "ansi" | "json";
+		} else if (arg === "--no-flow") {
+			withFlow = false;
+		}
+	}
+
+	try {
+		const result = await mineCrossCli({
+			topK,
+			minSupport,
+			minPathLength,
+			maxPathLength,
+			minDistinctCLIs,
+			allowedCLIs: onlyList.length > 0 ? onlyList : undefined,
+		});
+
+		if (format === "json") {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+
+		const C = makeColors(shouldUseColor(args));
+
+		console.log(`\n${C.bold}${C.magenta}cross-CLI workflow analysis${C.reset}\n`);
+		console.log(`${C.bold}Scope:${C.reset}`);
+		console.log(`  ${C.dim}Sessions analyzed:${C.reset}  ${C.cyan}${result.sessionsAnalyzed}${C.reset}`);
+		console.log(`  ${C.dim}Distinct CLIs:${C.reset}      ${C.cyan}${result.distinctCLIs.length}${C.reset}`);
+		console.log(`  ${C.dim}Transitions:${C.reset}        ${C.cyan}${result.totalTransitions}${C.reset}\n`);
+
+		if (result.workflows.length === 0) {
+			console.log(`${C.dim}No cross-CLI workflows found. Try lowering --min-support or --min-distinct-clis.${C.reset}\n`);
+			return;
+		}
+
+		console.log(`${C.bold}Cross-CLI workflows (top ${result.workflows.length}):${C.reset}`);
+		for (let i = 0; i < result.workflows.length; i++) {
+			const wf = result.workflows[i]!;
+			const chain = wf.path
+				.map(s => `${C.green}${s.cli}${C.reset} ${C.cyan}${s.subcommand}${C.reset}`)
+				.join(` ${C.gray}→${C.reset} `);
+			console.log(`  ${C.dim}${(i + 1).toString().padStart(2)}.${C.reset} ${chain}`);
+			console.log(`      ${C.dim}seen ${wf.support}×, ${wf.uniqueCLIs} distinct CLIs${C.reset}`);
+		}
+		console.log();
+
+		if (withFlow && result.workflows.length > 0) {
+			const top = result.workflows[0]!;
+			const flowWorkflow = crossCliToFlowWorkflow(top);
+			const rendered = shouldUseColor(args) ? flowToAnsi(flowWorkflow) : flowToString(flowWorkflow);
+			console.log(`${C.bold}Top cross-CLI workflow (visualized):${C.reset}`);
+			console.log(rendered);
+			console.log();
+		}
+	} catch (err: any) {
+		console.error(`Error: ${err.message}`);
+		process.exit(1);
 	}
-	return null;
 }
 
 async function runArchaeologyCmd(args: string[]) {

package/src/miner/activity.ts

@@ -0,0 +1,71 @@
+import type { HistoryEntry } from "./types";
+
+export interface ActivityProfile {
+	/** Total invocations considered */
+	total: number;
+	/** Count per hour of day (0-23) */
+	hourOfDay: number[];
+	/** Count per day of week (0=Sun, 6=Sat) */
+	dayOfWeek: number[];
+	/** Count per day over the last N days (most recent last) */
+	last30Days: number[];
+	/** The earliest timestamp observed (unix seconds) */
+	firstSeen: number;
+	/** The latest timestamp observed (unix seconds) */
+	lastSeen: number;
+}
+
+/**
+ * Compute temporal activity histograms from a list of history entries.
+ * Assumes entries have unix-second timestamps; entries with timestamp 0 are ignored.
+ */
+export function computeActivity(entries: HistoryEntry[], now: Date = new Date()): ActivityProfile {
+	const hourOfDay = new Array(24).fill(0);
+	const dayOfWeek = new Array(7).fill(0);
+	const last30Days = new Array(30).fill(0);
+
+	let first = Infinity;
+	let last = 0;
+	let total = 0;
+
+	const nowMs = now.getTime();
+	const dayMs = 24 * 60 * 60 * 1000;
+
+	for (const entry of entries) {
+		if (!entry.timestamp || entry.timestamp <= 0) continue;
+
+		total += 1;
+		if (entry.timestamp < first) first = entry.timestamp;
+		if (entry.timestamp > last) last = entry.timestamp;
+
+		const date = new Date(entry.timestamp * 1000);
+		hourOfDay[date.getHours()] += 1;
+		dayOfWeek[date.getDay()] += 1;
+
+		const ageDays = Math.floor((nowMs - date.getTime()) / dayMs);
+		if (ageDays >= 0 && ageDays < 30) {
+			// Index 29 = today, 0 = 29 days ago
+			last30Days[29 - ageDays] += 1;
+		}
+	}
+
+	return {
+		total,
+		hourOfDay,
+		dayOfWeek,
+		last30Days,
+		firstSeen: first === Infinity ? 0 : first,
+		lastSeen: last,
+	};
+}
+
+export function formatTimeRange(firstSeen: number, lastSeen: number): string {
+	if (!firstSeen || !lastSeen) return "no data";
+	const first = new Date(firstSeen * 1000);
+	const last = new Date(lastSeen * 1000);
+	const days = Math.round((last.getTime() - first.getTime()) / (24 * 60 * 60 * 1000));
+	if (days < 1) return "less than a day";
+	if (days < 30) return `${days} days`;
+	if (days < 365) return `${Math.round(days / 30)} months`;
+	return `${(days / 365).toFixed(1)} years`;
+}