@crafter/cli-tree 0.1.0

package/src/cli.ts

@@ -0,0 +1,451 @@
+#!/usr/bin/env bun
+import { parseHelpRecursive, parseHelp } from "./parse";
+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 } 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 isHelpFlag = args.includes("--help") || args.includes("-h");
+
+if (!subcommand || (isHelpFlag && !HELP_SUBCOMMANDS.has(subcommand ?? ""))) {
+	printMainHelp();
+	process.exit(0);
+}
+
+if (isHelpFlag) {
+	if (subcommand === "flow") printFlowHelp();
+	else if (subcommand === "mine") printMineHelp();
+	else if (subcommand === "archaeology") printArchaeologyHelp();
+	else printMainHelp();
+	process.exit(0);
+}
+
+if (subcommand === "flow") {
+	await runFlow(args.slice(1));
+} else if (subcommand === "mine") {
+	await runMine(args.slice(1));
+} else if (subcommand === "archaeology") {
+	await runArchaeologyCmd(args.slice(1));
+} else {
+	await runTree(args);
+}
+
+function printMainHelp() {
+	console.log(`
+  clitree — Visualize and explore any CLI
+
+  Usage:
+    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 archaeology <binary> [options]  Full analysis: tree + mining + (LLM)
+
+  Examples:
+    clitree docker                          # basic tree
+    clitree mine git                        # "what workflows do I repeat with git?"
+    clitree archaeology bun                 # tree + mining + LLM archaeology
+
+  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
+    archaeology   Run full analysis (tree + mine + LLM proposals when available)
+
+  Help for a subcommand: clitree <subcommand> --help
+`);
+}
+
+function printMineHelp() {
+	console.log(`
+  cli-tree mine — Mine your shell history for CLI workflows
+
+  Usage:
+    cli-tree mine <binary> [options]
+
+  Examples:
+    cli-tree mine git
+    cli-tree mine docker --min-support 5
+    cli-tree mine bun --format json > bun-flows.json
+
+  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)
+    -h, --help           Show this help
+`);
+}
+
+function printArchaeologyHelp() {
+	console.log(`
+  cli-tree archaeology — Full CLI analysis: tree + mining + LLM archaeology
+
+  Usage:
+    cli-tree archaeology <binary> [options]
+
+  When run from the command line without a delegate, only the deterministic
+  phases run (help parsing + shell history mining). LLM archaeology requires
+  running inside the clitree skill (see ./skill/SKILL.md).
+
+  Examples:
+    cli-tree archaeology git                  # help + history
+    cli-tree archaeology docker --no-cache    # bypass cache
+    cli-tree archaeology bun --format json    # JSON output
+
+  Options:
+    --no-cache           Skip cache, always re-run
+    --max-depth <n>      Max --help recursion depth (default: 2)
+    --format <fmt>       Output format: ansi (default), json
+    -h, --help           Show this help
+`);
+}
+
+function printFlowHelp() {
+	console.log(`
+  cli-tree flow — Render a CLI workflow YAML as a DAG
+
+  Usage:
+    cli-tree flow <file> [options]
+
+  Examples:
+    cli-tree flow workflows/git-pr-flow.yml
+    cli-tree flow my-workflow.yml --format html > flow.html
+    cli-tree flow workflows/docker-deploy.yml --compact --no-color
+
+  Options:
+    --compact          Hide description and legend
+    --no-color         Disable colors
+    --format <fmt>     Output format: ansi (default), string, html
+    --no-validate      Skip validation
+    -h, --help         Show this help
+`);
+}
+
+async function runTree(args: string[]) {
+	const opts: TreeOptions = {
+		color: true,
+		showFlags: true,
+		showArgs: true,
+		showDescriptions: true,
+		showTypes: true,
+		showDefaults: true,
+		compact: false,
+	};
+
+	let depth = 2;
+	let format: "ansi" | "string" | "html" | "json" = "ansi";
+	let stdinName: string | null = null;
+	let binary: string | null = null;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]!;
+		if (arg === "--depth" && args[i + 1]) {
+			depth = Number.parseInt(args[++i]!, 10);
+		} else if (arg === "--compact") {
+			opts.compact = true;
+			opts.showDescriptions = false;
+		} else if (arg === "--no-flags") {
+			opts.showFlags = false;
+		} else if (arg === "--no-args") {
+			opts.showArgs = false;
+		} else if (arg === "--no-color") {
+			opts.color = false;
+		} else if (arg === "--format" && args[i + 1]) {
+			format = args[++i] as "ansi" | "string" | "html" | "json";
+		} else if (arg === "--stdin" && args[i + 1]) {
+			stdinName = args[++i]!;
+		} else if (!arg.startsWith("-")) {
+			binary = arg;
+		}
+	}
+
+	try {
+		let tree;
+		if (stdinName) {
+			const input = await readStdin();
+			tree = parseHelp(stdinName, input);
+		} else if (binary) {
+			tree = await parseHelpRecursive(binary, [], depth);
+		} else {
+			console.error("Error: provide a binary name or use --stdin <name>");
+			process.exit(1);
+		}
+
+		if (format === "json") {
+			console.log(JSON.stringify(tree, null, 2));
+		} else if (format === "html") {
+			console.log(treeToHtml(tree, opts));
+		} else if (format === "string") {
+			console.log(treeToString(tree, opts));
+		} else {
+			printTree(tree, opts);
+		}
+	} catch (err: any) {
+		console.error(`Error: ${err.message}`);
+		process.exit(1);
+	}
+}
+
+async function runFlow(args: string[]) {
+	const opts: FlowRenderOptions = {
+		color: true,
+		showDescriptions: true,
+		showCommands: true,
+		compact: false,
+	};
+
+	let format: "ansi" | "string" | "html" = "ansi";
+	let file: string | null = null;
+	let skipValidate = false;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]!;
+		if (arg === "--compact") {
+			opts.compact = true;
+			opts.showDescriptions = false;
+		} else if (arg === "--no-color") {
+			opts.color = false;
+		} else if (arg === "--no-validate") {
+			skipValidate = true;
+		} else if (arg === "--format" && args[i + 1]) {
+			format = args[++i] as "ansi" | "string" | "html";
+		} else if (!arg.startsWith("-")) {
+			file = arg;
+		}
+	}
+
+	if (!file) {
+		console.error("Error: provide a workflow YAML file");
+		console.error("Run 'cli-tree flow --help' for usage");
+		process.exit(1);
+	}
+
+	try {
+		const text = await Bun.file(file).text();
+		const workflow = parseWorkflow(text);
+
+		if (!skipValidate) {
+			const result = validateWorkflow(workflow);
+			for (const err of result.errors) {
+				const prefix = err.severity === "error" ? "\x1b[31m✗" : "\x1b[33m⚠";
+				const reset = "\x1b[0m";
+				const location = err.node ? ` [${err.node}]` : err.edge ? ` [${err.edge.from}→${err.edge.to}]` : "";
+				console.error(`${prefix}${location} ${err.message}${reset}`);
+			}
+			if (!result.valid) process.exit(1);
+		}
+
+		if (format === "html") {
+			console.log(flowToHtml(workflow, opts));
+		} else if (format === "string") {
+			console.log(flowToString(workflow, opts));
+		} else {
+			console.log(flowToAnsi(workflow, opts));
+		}
+	} catch (err: any) {
+		console.error(`Error: ${err.message}`);
+		process.exit(1);
+	}
+}
+
+async function readStdin(): Promise<string> {
+	const chunks: Buffer[] = [];
+	for await (const chunk of process.stdin) {
+		chunks.push(chunk as Buffer);
+	}
+	return Buffer.concat(chunks).toString("utf-8");
+}
+
+async function runMine(args: string[]) {
+	let binary: string | null = null;
+	let minSupport = 3;
+	let historyPath: string | undefined;
+	let format: "ansi" | "json" = "ansi";
+	let maxPaths = 10;
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]!;
+		if (arg === "--min-support" && args[i + 1]) {
+			minSupport = Number.parseInt(args[++i]!, 10);
+		} else if (arg === "--history-path" && args[i + 1]) {
+			historyPath = args[++i]!;
+		} else if (arg === "--format" && args[i + 1]) {
+			format = args[++i] as "ansi" | "json";
+		} else if (arg === "--max-paths" && args[i + 1]) {
+			maxPaths = Number.parseInt(args[++i]!, 10);
+		} else if (!arg.startsWith("-")) {
+			binary = arg;
+		}
+	}
+
+	if (!binary) {
+		console.error("Error: provide a binary name");
+		console.error("Run 'cli-tree mine --help' for usage");
+		process.exit(1);
+	}
+
+	try {
+		const result = await mineCli(binary, { minSupport, historyPath });
+
+		if (format === "json") {
+			console.log(JSON.stringify(result, null, 2));
+			return;
+		}
+
+		const C = {
+			reset: "\x1b[0m",
+			bold: "\x1b[1m",
+			dim: "\x1b[2m",
+			cyan: "\x1b[36m",
+			green: "\x1b[32m",
+			yellow: "\x1b[33m",
+			magenta: "\x1b[35m",
+			gray: "\x1b[90m",
+		};
+
+		console.log(`\n${C.bold}${C.magenta}${binary}${C.reset} ${C.gray}— shell history analysis${C.reset}\n`);
+		console.log(`${C.bold}Usage:${C.reset}`);
+		console.log(`  ${C.dim}Invocations:${C.reset}  ${C.cyan}${result.stats.totalInvocations}${C.reset}`);
+		console.log(`  ${C.dim}Subcommands:${C.reset}  ${C.cyan}${result.stats.uniqueSubcommands}${C.reset}`);
+		console.log(`  ${C.dim}Sessions:${C.reset}     ${C.cyan}${result.sessionsAnalyzed}${C.reset}\n`);
+
+		if (result.stats.topSubcommands.length > 0) {
+			console.log(`${C.bold}Top subcommands:${C.reset}`);
+			const max = result.stats.topSubcommands[0]!.count;
+			for (const { subcommand, count } of result.stats.topSubcommands.slice(0, 5)) {
+				const bar = "█".repeat(Math.max(1, Math.round((count / max) * 30)));
+				console.log(`  ${C.green}${subcommand.padEnd(20)}${C.reset} ${C.cyan}${bar}${C.reset} ${C.dim}${count}${C.reset}`);
+			}
+			console.log();
+		}
+
+		if (result.workflows.length > 0) {
+			console.log(`${C.bold}Discovered workflows:${C.reset}`);
+			for (const wf of result.workflows.slice(0, maxPaths)) {
+				const chain = wf.path[0]!.map(p => `${C.green}${p}${C.reset}`).join(` ${C.gray}→${C.reset} `);
+				console.log(`  ${chain} ${C.dim}(${wf.support}×)${C.reset}`);
+			}
+			console.log();
+		}
+
+		if (result.suggestions.length > 0) {
+			console.log(`${C.bold}${C.yellow}💡 Skill suggestions:${C.reset}`);
+			for (const s of result.suggestions.slice(0, 3)) {
+				const badge =
+					s.priority === "high"
+						? `${C.green}[HIGH]${C.reset}`
+						: s.priority === "medium"
+							? `${C.yellow}[MED]${C.reset}`
+							: `${C.dim}[LOW]${C.reset}`;
+				console.log(`\n  ${badge} ${C.bold}/${s.name}${C.reset} — ${s.description}`);
+				console.log(`    ${C.dim}${s.reason}${C.reset}`);
+				console.log(`    ${C.dim}${s.commands.join(" && ")}${C.reset}`);
+			}
+			console.log();
+		}
+	} catch (err: any) {
+		console.error(`Error: ${err.message}`);
+		process.exit(1);
+	}
+}
+
+async function runArchaeologyCmd(args: string[]) {
+	let binary: string | null = null;
+	let skipCache = false;
+	let maxDepth = 2;
+	let format: "ansi" | "json" = "ansi";
+
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]!;
+		if (arg === "--no-cache") {
+			skipCache = true;
+		} else if (arg === "--max-depth" && args[i + 1]) {
+			maxDepth = Number.parseInt(args[++i]!, 10);
+		} else if (arg === "--format" && args[i + 1]) {
+			format = args[++i] as "ansi" | "json";
+		} else if (!arg.startsWith("-")) {
+			binary = arg;
+		}
+	}
+
+	if (!binary) {
+		console.error("Error: provide a binary name");
+		console.error("Run 'cli-tree archaeology --help' for usage");
+		process.exit(1);
+	}
+
+	const C = {
+		reset: "\x1b[0m",
+		bold: "\x1b[1m",
+		dim: "\x1b[2m",
+		cyan: "\x1b[36m",
+		green: "\x1b[32m",
+		yellow: "\x1b[33m",
+		red: "\x1b[31m",
+		magenta: "\x1b[35m",
+		gray: "\x1b[90m",
+	};
+
+	try {
+		console.error(`${C.dim}⚠  LLM archaeology requires running inside the clitree skill.${C.reset}`);
+		console.error(`${C.dim}   Running deterministic phases only (help + history mining).${C.reset}`);
+		console.error("");
+
+		const [arch, mine] = await Promise.all([
+			runArchaeology(binary, new NullDelegate(), { skipCache, maxHelpDepth: maxDepth }),
+			mineCli(binary, { minSupport: 3 }).catch(() => null),
+		]);
+
+		if (format === "json") {
+			console.log(JSON.stringify({ archaeology: arch, mining: mine }, null, 2));
+			return;
+		}
+
+		console.log(`${C.bold}${C.magenta}${binary}${C.reset}`);
+		if (arch.tree.description) {
+			console.log(`${C.gray}${arch.tree.description}${C.reset}`);
+		}
+		console.log();
+
+		console.log(`${C.bold}Tree:${C.reset}`);
+		console.log(`  ${C.dim}Commands:${C.reset}  ${C.cyan}${arch.stats.helpCommands}${C.reset}`);
+		console.log(`  ${C.dim}Cached:${C.reset}    ${arch.fromCache ? `${C.green}yes${C.reset}` : `${C.dim}no${C.reset}`}`);
+		console.log();
+
+		if (mine) {
+			console.log(`${C.bold}Usage from shell history:${C.reset}`);
+			console.log(`  ${C.dim}Invocations:${C.reset}  ${C.cyan}${mine.stats.totalInvocations}${C.reset}`);
+			console.log(`  ${C.dim}Subcommands:${C.reset}  ${C.cyan}${mine.stats.uniqueSubcommands}${C.reset}`);
+
+			if (mine.workflows.length > 0) {
+				console.log(`\n${C.bold}Workflows you repeat:${C.reset}`);
+				for (const wf of mine.workflows.slice(0, 5)) {
+					const chain = wf.path[0]!.map(p => `${C.green}${p}${C.reset}`).join(` ${C.gray}→${C.reset} `);
+					console.log(`  ${chain} ${C.dim}(${wf.support}×)${C.reset}`);
+				}
+			}
+
+			if (mine.suggestions.length > 0) {
+				console.log(`\n${C.bold}${C.yellow}💡 Skill suggestions:${C.reset}`);
+				for (const s of mine.suggestions.slice(0, 3)) {
+					console.log(`  ${C.bold}/${s.name}${C.reset} — ${s.description}`);
+					console.log(`    ${C.dim}${s.reason}${C.reset}`);
+				}
+			}
+		}
+
+		console.log();
+		console.log(`${C.dim}Install the clitree skill for full LLM archaeology:${C.reset}`);
+		console.log(`${C.dim}  bash ./skill/install.sh${C.reset}`);
+		console.log();
+	} catch (err: any) {
+		console.error(`${C.red}Error: ${err.message}${C.reset}`);
+		process.exit(1);
+	}
+}

package/src/encoders/ansi.ts

@@ -0,0 +1,32 @@
+import type { Grid } from "../grid";
+import { ANSI_COLORS, ANSI_RESET, type AnsiColor } from "../types";
+
+export function encodeAnsi(grid: Grid): string {
+	const lines: string[] = [];
+
+	for (let y = 0; y < grid.height; y++) {
+		let line = "";
+		let currentFg: string | null = null;
+
+		for (let x = 0; x < grid.width; x++) {
+			const cell = grid.get(x, y);
+			if (!cell) continue;
+
+			if (cell.fg !== currentFg) {
+				if (currentFg !== null) line += ANSI_RESET;
+				if (cell.fg !== null) line += ANSI_COLORS[cell.fg as AnsiColor] ?? "";
+				currentFg = cell.fg;
+			}
+			line += cell.char;
+		}
+
+		if (currentFg !== null) line += ANSI_RESET;
+		lines.push(line.trimEnd());
+	}
+
+	while (lines.length > 0 && lines[lines.length - 1] === "") {
+		lines.pop();
+	}
+
+	return lines.join("\n");
+}

package/src/encoders/html.ts

@@ -0,0 +1,78 @@
+import type { Grid } from "../grid";
+
+const COLOR_TO_CSS: Record<string, string> = {
+	red: "#ef4444",
+	green: "#22c55e",
+	yellow: "#eab308",
+	blue: "#3b82f6",
+	magenta: "#d946ef",
+	cyan: "#06b6d4",
+	white: "#e8e0d4",
+	gray: "#6b7c72",
+};
+
+export interface HtmlEncodeOptions {
+	wrap?: boolean;
+	background?: string;
+	foreground?: string;
+	fontFamily?: string;
+	fontSize?: string;
+	padding?: string;
+}
+
+export function encodeHtml(grid: Grid, opts: HtmlEncodeOptions = {}): string {
+	const wrap = opts.wrap ?? true;
+	const lines: string[] = [];
+
+	for (let y = 0; y < grid.height; y++) {
+		let line = "";
+		let currentFg: string | null = null;
+
+		for (let x = 0; x < grid.width; x++) {
+			const cell = grid.get(x, y);
+			if (!cell) continue;
+
+			if (cell.fg !== currentFg) {
+				if (currentFg !== null) line += "</span>";
+				if (cell.fg !== null) {
+					const css = COLOR_TO_CSS[cell.fg] ?? cell.fg;
+					line += `<span style="color:${css}">`;
+				}
+				currentFg = cell.fg;
+			}
+
+			const ch = cell.char;
+			if (ch === "<") line += "&lt;";
+			else if (ch === ">") line += "&gt;";
+			else if (ch === "&") line += "&amp;";
+			else line += ch;
+		}
+
+		if (currentFg !== null) line += "</span>";
+		lines.push(line);
+	}
+
+	const body = lines.join("\n");
+	if (!wrap) return body;
+
+	const bg = opts.background ?? "#0a0a0a";
+	const fg = opts.foreground ?? "#e8e0d4";
+	const font = opts.fontFamily ?? '"JetBrains Mono", "Fira Code", "SF Mono", Menlo, Monaco, Consolas, monospace';
+	const size = opts.fontSize ?? "14px";
+	const pad = opts.padding ?? "24px";
+
+	const style = [
+		`background: ${bg}`,
+		`color: ${fg}`,
+		`font-family: ${font}`,
+		`font-size: ${size}`,
+		`line-height: 1.3`,
+		`padding: ${pad}`,
+		`margin: 0`,
+		`white-space: pre`,
+		`overflow-x: auto`,
+		`border-radius: 8px`,
+	].join("; ");
+
+	return `<pre style="${style}">${body}</pre>`;
+}

package/src/encoders/string.ts

@@ -0,0 +1,20 @@
+import type { Grid } from "../grid";
+
+export function encodeString(grid: Grid): string {
+	const lines: string[] = [];
+
+	for (let y = 0; y < grid.height; y++) {
+		let line = "";
+		for (let x = 0; x < grid.width; x++) {
+			const cell = grid.get(x, y);
+			line += cell?.char ?? " ";
+		}
+		lines.push(line.trimEnd());
+	}
+
+	while (lines.length > 0 && lines[lines.length - 1] === "") {
+		lines.pop();
+	}
+
+	return lines.join("\n");
+}

package/src/flow/encode.ts

@@ -0,0 +1,21 @@
+import { encodeAnsi } from "../encoders/ansi";
+import { encodeString } from "../encoders/string";
+import { encodeHtml } from "../encoders/html";
+import { renderFlow } from "./render";
+import type { Workflow, FlowRenderOptions } from "./types";
+
+export function flowToAnsi(workflow: Workflow, opts?: FlowRenderOptions): string {
+	return encodeAnsi(renderFlow(workflow, opts));
+}
+
+export function flowToString(workflow: Workflow, opts?: FlowRenderOptions): string {
+	return encodeString(renderFlow(workflow, opts));
+}
+
+export function flowToHtml(workflow: Workflow, opts?: FlowRenderOptions): string {
+	return encodeHtml(renderFlow(workflow, opts));
+}
+
+export function printFlow(workflow: Workflow, opts?: FlowRenderOptions): void {
+	console.log(flowToAnsi(workflow, opts));
+}

package/src/flow/index.ts

@@ -0,0 +1,15 @@
+export { parseWorkflow } from "./parse";
+export { parseYaml } from "./yaml";
+export { validateWorkflow } from "./validate";
+export { computeLayout } from "./layout";
+export { renderFlow } from "./render";
+export { flowToAnsi, flowToString, flowToHtml, printFlow } from "./encode";
+export type {
+	Workflow,
+	WorkflowNode,
+	WorkflowEdge,
+	FlowRenderOptions,
+	ValidationError,
+	ValidationResult,
+} from "./types";
+export type { Layout, LayoutNode, LayoutEdge, LayoutOptions } from "./layout";