@crafter/cli-tree 0.1.3 → 0.2.1

package/dist/miner/cross-cli.d.ts

@@ -0,0 +1,55 @@
+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;
+}
+/**
+ * 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 declare function mineCrossCli(options?: CrossCliOptions): Promise<CrossCliResult>;
+/**
+ * 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 declare function crossCliToFlowWorkflow(workflow: CrossCliWorkflow): {
+    name: string;
+    description: string;
+    cli: string;
+    nodes: {
+        id: string;
+        command: string[];
+        label: string;
+    }[];
+    edges: {
+        from: string;
+        to: string;
+    }[];
+};

package/dist/miner/index.d.ts

@@ -5,9 +5,12 @@ 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 { parseHistory, readHistoryFile, defaultHistoryPath, tokenize, detectHistoryFormat, segmentSessions, filterByCli, buildTransitions, normalizeTransitions, extractSubcommand, extractSubcommandPath, extractPaths, clusterIntoWorkflows, computeStats, suggestSkills, minedToFlowWorkflow, };
+export type { HistoryEntry, Session, Transition, MinedWorkflow, CliUsageStats, MineOptions, SkillSuggestion, ActivityProfile, CrossCliOptions, CrossCliResult, CrossCliWorkflow, CrossCliStep, };
+export { parseHistory, readHistoryFile, defaultHistoryPath, tokenize, detectHistoryFormat, segmentSessions, filterByCli, buildTransitions, normalizeTransitions, extractSubcommand, extractSubcommandPath, extractPaths, clusterIntoWorkflows, computeStats, suggestSkills, minedToFlowWorkflow, computeActivity, formatTimeRange, sparkline, labeledSparkline, mineCrossCli, crossCliToFlowWorkflow, };
 export interface MineResult {
     cli: string;
     stats: CliUsageStats;
@@ -15,5 +18,6 @@ export interface MineResult {
     workflows: MinedWorkflow[];
     suggestions: SkillSuggestion[];
     sessionsAnalyzed: number;
+    activity: ActivityProfile;
 }
 export declare function mineCli(cli: string, options?: MineOptions): Promise<MineResult>;

package/dist/miner/index.js

@@ -1,40 +1,52 @@
 import {
   buildTransitions,
   clusterIntoWorkflows,
+  computeActivity,
   computeStats,
+  crossCliToFlowWorkflow,
   defaultHistoryPath,
   detectHistoryFormat,
   extractPaths,
   extractSubcommand,
   extractSubcommandPath,
   filterByCli,
+  formatTimeRange,
+  labeledSparkline,
   mineCli,
+  mineCrossCli,
   minedToFlowWorkflow,
   normalizeTransitions,
   parseHistory,
   readHistoryFile,
   segmentSessions,
+  sparkline,
   suggestSkills,
   tokenize
-} from "../chunk-dnq2rnr7.js";
+} from "../chunk-e8jgr5p6.js";
 export {
   tokenize,
   suggestSkills,
+  sparkline,
   segmentSessions,
   readHistoryFile,
   parseHistory,
   normalizeTransitions,
   minedToFlowWorkflow,
+  mineCrossCli,
   mineCli,
+  labeledSparkline,
+  formatTimeRange,
   filterByCli,
   extractSubcommandPath,
   extractSubcommand,
   extractPaths,
   detectHistoryFormat,
   defaultHistoryPath,
+  crossCliToFlowWorkflow,
   computeStats,
+  computeActivity,
   clusterIntoWorkflows,
   buildTransitions
 };
 
-//# debugId=34A9477E11B0A64764756E2164756E21
+//# debugId=3F080486405E782764756E2164756E21

package/dist/miner/index.js.map

@@ -4,6 +4,6 @@
   "sourcesContent": [
   ],
   "mappings": "",
-  "debugId": "34A9477E11B0A64764756E2164756E21",
+  "debugId": "3F080486405E782764756E2164756E21",
   "names": []
 }

package/dist/miner/sparkline.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+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 declare function sparkline(data: number[], opts?: SparklineOptions): string;
+/**
+ * Render a labeled row like "Mon ▁▃▅█▇▅▃▂" — used for day-of-week activity.
+ */
+export declare function labeledSparkline(label: string, data: number[], labelWidth?: number): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crafter/cli-tree",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Explore and map any CLI tool deeply. Parse --help trees, mine shell history for repeated workflows, surface hidden flags via LLM archaeology, and suggest new agent skills from your usage patterns.",
   "type": "module",
   "main": "./dist/index.js",

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", "safe-help"]);
+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 ?? ""))) {
@@ -23,6 +31,7 @@ if (isHelpFlag) {
 	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);
 }
@@ -35,6 +44,8 @@ if (subcommand === "flow") {
 	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);
 }
@@ -47,19 +58,22 @@ 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
 
@@ -67,6 +81,43 @@ function printMainHelp() {
 `);
 }
 
+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
@@ -111,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.
 `);
 }
 
@@ -476,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]!;
@@ -487,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;
 		}
@@ -528,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)) {
@@ -553,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();
 			}
 		}
@@ -575,15 +645,174 @@ async function runMine(args: string[]) {
 	}
 }
 
+function renderActivitySection(
+	activity: {
+		hourOfDay: number[];
+		dayOfWeek: number[];
+		last30Days: number[];
+		last52Weeks: number[];
+		firstSeen: number;
+		lastSeen: number;
+		total: number;
+		daysWithActivity: 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} ${C.dim}(blank = no data)${C.reset}`);
+
+	const range = formatTimeRange(activity.firstSeen, activity.lastSeen);
+	console.log(`  ${C.dim}Tracked over:${C.reset}  ${C.cyan}${range}${C.reset}  ${C.dim}(${activity.daysWithActivity} active days)${C.reset}`);
+
+	// Hour-of-day sparkline (24 chars wide — one per hour)
+	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}`);
+		}
+		console.log();
+	}
+
+	// Last 30 days — one character per day, · marks days with zero activity
+	if (activity.last30Days.some(v => v > 0)) {
+		const activeDays = activity.last30Days.filter(v => v > 0).length;
+		const totalLast30 = activity.last30Days.reduce((a, b) => a + b, 0);
+		const monthSpark = sparkline(activity.last30Days);
+		console.log(`  ${C.dim}Last 30 days:${C.reset} ${C.cyan}${monthSpark}${C.reset}`);
+		console.log(`  ${C.dim}              └── 1 char per day · ${activeDays}/30 active · ${totalLast30} total${C.reset}`);
+	}
+
+	// Last 52 weeks — gives context for heavy-history users (1+ year of tracking)
+	if (activity.last52Weeks.some(v => v > 0)) {
+		const activeWeeks = activity.last52Weeks.filter(v => v > 0).length;
+		const weekSpark = sparkline(activity.last52Weeks);
+		console.log(`  ${C.dim}Last 52 weeks:${C.reset} ${C.cyan}${weekSpark}${C.reset}`);
+		console.log(`  ${C.dim}               └── 1 char per week · ${activeWeeks}/52 active weeks${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,90 @@
+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 30 days (most recent last) */
+	last30Days: number[];
+	/** Count per ISO week over the last 52 weeks (most recent last) */
+	last52Weeks: number[];
+	/** The earliest timestamp observed (unix seconds) */
+	firstSeen: number;
+	/** The latest timestamp observed (unix seconds) */
+	lastSeen: number;
+	/** How many distinct days had at least one invocation */
+	daysWithActivity: 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);
+	const last52Weeks = new Array(52).fill(0);
+
+	let first = Infinity;
+	let last = 0;
+	let total = 0;
+
+	const nowMs = now.getTime();
+	const dayMs = 24 * 60 * 60 * 1000;
+	const weekMs = 7 * dayMs;
+
+	const distinctDays = new Set<number>();
+
+	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 dayKey = Math.floor(date.getTime() / dayMs);
+		distinctDays.add(dayKey);
+
+		const ageDays = Math.floor((nowMs - date.getTime()) / dayMs);
+		if (ageDays >= 0 && ageDays < 30) {
+			// Index 29 = today, 0 = 29 days ago
+			last30Days[29 - ageDays] += 1;
+		}
+
+		const ageWeeks = Math.floor((nowMs - date.getTime()) / weekMs);
+		if (ageWeeks >= 0 && ageWeeks < 52) {
+			// Index 51 = this week, 0 = 51 weeks ago
+			last52Weeks[51 - ageWeeks] += 1;
+		}
+	}
+
+	return {
+		total,
+		hourOfDay,
+		dayOfWeek,
+		last30Days,
+		last52Weeks,
+		firstSeen: first === Infinity ? 0 : first,
+		lastSeen: last,
+		daysWithActivity: distinctDays.size,
+	};
+}
+
+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`;
+}