@crafter/cli-tree 0.1.0

package/src/flow/layout.ts

@@ -0,0 +1,150 @@
+import type { Workflow, WorkflowNode, WorkflowEdge } from "./types";
+
+export interface LayoutNode {
+	id: string;
+	node: WorkflowNode;
+	col: number;
+	row: number;
+	width: number;
+	height: number;
+	x: number;
+	y: number;
+}
+
+export interface LayoutEdge {
+	from: string;
+	to: string;
+	edge: WorkflowEdge;
+}
+
+export interface Layout {
+	nodes: LayoutNode[];
+	edges: LayoutEdge[];
+	totalWidth: number;
+	totalHeight: number;
+}
+
+export interface LayoutOptions {
+	boxPaddingX?: number;
+	colGap?: number;
+	rowGap?: number;
+	minBoxWidth?: number;
+}
+
+export function computeLayout(workflow: Workflow, opts: LayoutOptions = {}): Layout {
+	const boxPaddingX = opts.boxPaddingX ?? 2;
+	const colGap = opts.colGap ?? 4;
+	const rowGap = opts.rowGap ?? 2;
+	const minBoxWidth = opts.minBoxWidth ?? 8;
+
+	const ranks = computeRanks(workflow);
+	const byRank = groupByRank(workflow.nodes, ranks);
+	const maxRank = Math.max(0, ...Array.from(ranks.values()));
+
+	const allWidths = workflow.nodes.map(n => boxWidthFor(n, boxPaddingX, minBoxWidth));
+	const uniformWidth = Math.max(...allWidths);
+
+	const maxPerRank = Math.max(
+		1,
+		...Array.from(byRank.values()).map(v => v.length),
+	);
+	const totalRowWidth = maxPerRank * uniformWidth + (maxPerRank - 1) * colGap;
+
+	const layoutNodes: LayoutNode[] = [];
+	const boxHeight = 3;
+
+	let currentY = 0;
+	for (let r = 0; r <= maxRank; r++) {
+		const rankNodes = byRank.get(r) ?? [];
+		const count = rankNodes.length;
+		const rowWidth = count * uniformWidth + (count - 1) * colGap;
+		const startX = Math.floor((totalRowWidth - rowWidth) / 2);
+
+		for (let i = 0; i < rankNodes.length; i++) {
+			const node = rankNodes[i]!;
+			const x = startX + i * (uniformWidth + colGap);
+			layoutNodes.push({
+				id: node.id,
+				node,
+				col: i,
+				row: r,
+				width: uniformWidth,
+				height: boxHeight,
+				x,
+				y: currentY,
+			});
+		}
+
+		currentY += boxHeight + rowGap;
+	}
+
+	const totalWidth = Math.max(
+		0,
+		...layoutNodes.map(n => n.x + n.width),
+	);
+	const totalHeight = Math.max(
+		0,
+		...layoutNodes.map(n => n.y + n.height),
+	);
+
+	const edges: LayoutEdge[] = workflow.edges.map(e => ({
+		from: e.from,
+		to: e.to,
+		edge: e,
+	}));
+
+	return { nodes: layoutNodes, edges, totalWidth, totalHeight };
+}
+
+function computeRanks(workflow: Workflow): Map<string, number> {
+	const ranks = new Map<string, number>();
+	const inEdges = new Map<string, string[]>();
+	for (const node of workflow.nodes) {
+		ranks.set(node.id, 0);
+		inEdges.set(node.id, []);
+	}
+	for (const edge of workflow.edges) {
+		inEdges.get(edge.to)?.push(edge.from);
+	}
+
+	const visiting = new Set<string>();
+	function visit(id: string): number {
+		if (visiting.has(id)) return ranks.get(id) ?? 0;
+		visiting.add(id);
+		const parents = inEdges.get(id) ?? [];
+		if (parents.length === 0) {
+			ranks.set(id, 0);
+		} else {
+			const maxParent = Math.max(...parents.map(p => visit(p)));
+			ranks.set(id, maxParent + 1);
+		}
+		visiting.delete(id);
+		return ranks.get(id)!;
+	}
+
+	for (const node of workflow.nodes) {
+		visit(node.id);
+	}
+
+	return ranks;
+}
+
+function groupByRank(nodes: WorkflowNode[], ranks: Map<string, number>): Map<number, WorkflowNode[]> {
+	const byRank = new Map<number, WorkflowNode[]>();
+	for (const node of nodes) {
+		const r = ranks.get(node.id) ?? 0;
+		if (!byRank.has(r)) byRank.set(r, []);
+		byRank.get(r)!.push(node);
+	}
+	return byRank;
+}
+
+function boxWidthFor(node: WorkflowNode, padding: number, minWidth: number): number {
+	const label = node.label ?? node.id;
+	const contentWidth = label.length;
+	return Math.max(minWidth, contentWidth + padding * 2 + 2);
+}
+
+export function findNode(layout: Layout, id: string): LayoutNode | undefined {
+	return layout.nodes.find(n => n.id === id);
+}

package/src/flow/parse.ts

@@ -0,0 +1,100 @@
+import { parseYaml, type YamlValue } from "./yaml";
+import type { Workflow, WorkflowNode, WorkflowEdge } from "./types";
+
+export function parseWorkflow(yamlText: string): Workflow {
+	const raw = parseYaml(yamlText);
+	if (!isObject(raw)) {
+		throw new Error("Workflow YAML must be a map at the top level");
+	}
+
+	const name = asString(raw.name, "name");
+	const cli = asString(raw.cli, "cli");
+	const description = raw.description ? asString(raw.description, "description") : undefined;
+	const version = raw.version ? asString(raw.version, "version") : undefined;
+
+	const nodes = parseNodes(raw.nodes);
+	const edges = parseEdges(raw.edges, nodes);
+
+	const workflow: Workflow = { name, cli, nodes, edges };
+	if (description) workflow.description = description;
+	if (version) workflow.version = version;
+	return workflow;
+}
+
+function parseNodes(raw: YamlValue): WorkflowNode[] {
+	if (!Array.isArray(raw)) {
+		throw new Error("'nodes' must be a list");
+	}
+
+	return raw.map((item, idx) => {
+		if (!isObject(item)) {
+			throw new Error(`nodes[${idx}] must be a map`);
+		}
+
+		const id = asString(item.id, `nodes[${idx}].id`);
+		const cmdRaw = item.command;
+
+		let command: string[];
+		if (typeof cmdRaw === "string") {
+			command = cmdRaw.split(/\s+/).filter(Boolean);
+		} else if (Array.isArray(cmdRaw)) {
+			command = cmdRaw.map(c => String(c));
+		} else {
+			throw new Error(`nodes[${idx}].command must be a string or list`);
+		}
+
+		const node: WorkflowNode = { id, command };
+		if (typeof item.label === "string") node.label = item.label;
+		if (typeof item.description === "string") node.description = item.description;
+		if (typeof item.optional === "boolean") node.optional = item.optional;
+		return node;
+	});
+}
+
+function parseEdges(raw: YamlValue, nodes: WorkflowNode[]): WorkflowEdge[] {
+	if (!raw) return inferSequentialEdges(nodes);
+	if (!Array.isArray(raw)) {
+		throw new Error("'edges' must be a list");
+	}
+
+	return raw.map((item, idx) => {
+		if (typeof item === "string") {
+			const parts = item.split("->").map(s => s.trim());
+			if (parts.length !== 2) {
+				throw new Error(`edges[${idx}] string must be "from -> to"`);
+			}
+			return { from: parts[0]!, to: parts[1]! };
+		}
+
+		if (!isObject(item)) {
+			throw new Error(`edges[${idx}] must be a map or string`);
+		}
+
+		const edge: WorkflowEdge = {
+			from: asString(item.from, `edges[${idx}].from`),
+			to: asString(item.to, `edges[${idx}].to`),
+		};
+		if (typeof item.condition === "string") edge.condition = item.condition;
+		if (typeof item.label === "string") edge.label = item.label;
+		return edge;
+	});
+}
+
+function inferSequentialEdges(nodes: WorkflowNode[]): WorkflowEdge[] {
+	const edges: WorkflowEdge[] = [];
+	for (let i = 0; i < nodes.length - 1; i++) {
+		edges.push({ from: nodes[i]!.id, to: nodes[i + 1]!.id });
+	}
+	return edges;
+}
+
+function isObject(value: YamlValue): value is { [key: string]: YamlValue } {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function asString(value: YamlValue, field: string): string {
+	if (typeof value !== "string") {
+		throw new Error(`${field} must be a string`);
+	}
+	return value;
+}

package/src/flow/render.ts

@@ -0,0 +1,186 @@
+import { createGrid, writeText, type Grid } from "../grid";
+import { computeLayout, findNode, type Layout, type LayoutNode } from "./layout";
+import type { Workflow, FlowRenderOptions } from "./types";
+
+const BOX = {
+	topLeft: "┌",
+	topRight: "┐",
+	botLeft: "└",
+	botRight: "┘",
+	horiz: "─",
+	vert: "│",
+	arrowDown: "▼",
+	arrowRight: "►",
+	junctionDown: "┬",
+	junctionUp: "┴",
+	junctionLeft: "┤",
+	junctionRight: "├",
+	cross: "┼",
+};
+
+const COLOR = {
+	boxFrame: "gray",
+	label: "cyan",
+	optional: "yellow",
+	arrow: "gray",
+	title: "magenta",
+	description: "gray",
+};
+
+export function renderFlow(workflow: Workflow, opts: FlowRenderOptions = {}): Grid {
+	const useColor = opts.color ?? true;
+	const showDescriptions = opts.showDescriptions ?? true;
+	const compact = opts.compact ?? false;
+
+	const layout = computeLayout(workflow);
+
+	const titleLines = buildTitle(workflow, showDescriptions && !compact);
+	const titleOffset = titleLines.length;
+	const flowHeight = layout.totalHeight;
+	const legendLines = compact ? [] : buildLegend(workflow);
+	const legendOffset = legendLines.length > 0 ? legendLines.length + 1 : 0;
+
+	const totalHeight = titleOffset + flowHeight + legendOffset + 1;
+	const totalWidth = Math.max(layout.totalWidth, maxLineLength(titleLines), maxLineLength(legendLines)) + 2;
+
+	const grid = createGrid(totalWidth);
+	for (let i = 0; i < totalHeight; i++) grid.addRow();
+
+	let row = 0;
+	for (const line of titleLines) {
+		writeText(grid, 0, row, line.text, useColor ? line.color : null);
+		row++;
+	}
+
+	for (const node of layout.nodes) {
+		drawBox(grid, node, row + node.y, useColor);
+	}
+
+	for (const edge of layout.edges) {
+		const from = findNode(layout, edge.from);
+		const to = findNode(layout, edge.to);
+		if (!from || !to) continue;
+		drawEdge(grid, from, to, row, useColor);
+	}
+
+	if (legendLines.length > 0) {
+		let legendRow = row + flowHeight + 1;
+		for (const line of legendLines) {
+			writeText(grid, 0, legendRow, line.text, useColor ? line.color : null);
+			legendRow++;
+		}
+	}
+
+	return grid;
+}
+
+interface TextLine {
+	text: string;
+	color: string | null;
+}
+
+function buildTitle(workflow: Workflow, showDescription: boolean): TextLine[] {
+	const lines: TextLine[] = [];
+	const title = `${workflow.cli} · ${workflow.name}`;
+	lines.push({ text: title, color: COLOR.title });
+	if (showDescription && workflow.description) {
+		lines.push({ text: workflow.description, color: COLOR.description });
+	}
+	lines.push({ text: "", color: null });
+	return lines;
+}
+
+function buildLegend(workflow: Workflow): TextLine[] {
+	const hasOptional = workflow.nodes.some(n => n.optional);
+	if (!hasOptional) return [];
+	return [
+		{ text: "  ─── required   ┈┈┈ optional", color: COLOR.description },
+	];
+}
+
+function maxLineLength(lines: TextLine[]): number {
+	return lines.reduce((max, l) => Math.max(max, l.text.length), 0);
+}
+
+function drawBox(grid: Grid, node: LayoutNode, rowOffset: number, useColor: boolean): void {
+	const y = rowOffset;
+	const x = node.x;
+	const w = node.width;
+	const label = node.node.label ?? node.node.id;
+	const isOptional = node.node.optional;
+	const labelColor = useColor ? (isOptional ? COLOR.optional : COLOR.label) : null;
+	const frameColor = useColor ? COLOR.boxFrame : null;
+
+	const horizChar = isOptional ? "┈" : BOX.horiz;
+	const vertChar = isOptional ? "┊" : BOX.vert;
+	const tlChar = isOptional ? "┌" : BOX.topLeft;
+	const trChar = isOptional ? "┐" : BOX.topRight;
+	const blChar = isOptional ? "└" : BOX.botLeft;
+	const brChar = isOptional ? "┘" : BOX.botRight;
+
+	writeText(grid, x, y, tlChar, frameColor);
+	for (let i = 1; i < w - 1; i++) {
+		writeText(grid, x + i, y, horizChar, frameColor);
+	}
+	writeText(grid, x + w - 1, y, trChar, frameColor);
+
+	writeText(grid, x, y + 1, vertChar, frameColor);
+	const labelStart = x + Math.floor((w - label.length) / 2);
+	writeText(grid, labelStart, y + 1, label, labelColor);
+	writeText(grid, x + w - 1, y + 1, vertChar, frameColor);
+
+	writeText(grid, x, y + 2, blChar, frameColor);
+	for (let i = 1; i < w - 1; i++) {
+		writeText(grid, x + i, y + 2, horizChar, frameColor);
+	}
+	writeText(grid, x + w - 1, y + 2, brChar, frameColor);
+}
+
+function drawEdge(grid: Grid, from: LayoutNode, to: LayoutNode, rowOffset: number, useColor: boolean): void {
+	const color = useColor ? COLOR.arrow : null;
+
+	const fromCenterX = from.x + Math.floor(from.width / 2);
+	const toCenterX = to.x + Math.floor(to.width / 2);
+	const fromBottomY = rowOffset + from.y + from.height - 1;
+	const toTopY = rowOffset + to.y;
+
+	if (to.row > from.row) {
+		if (fromCenterX === toCenterX) {
+			for (let y = fromBottomY + 1; y < toTopY - 1; y++) {
+				writeText(grid, fromCenterX, y, BOX.vert, color);
+			}
+			writeText(grid, fromCenterX, toTopY - 1, BOX.arrowDown, color);
+		} else {
+			const midY = fromBottomY + 1;
+			writeText(grid, fromCenterX, midY, BOX.vert, color);
+
+			const bendY = midY + 1;
+			const startX = Math.min(fromCenterX, toCenterX);
+			const endX = Math.max(fromCenterX, toCenterX);
+			for (let x = startX + 1; x < endX; x++) {
+				writeText(grid, x, bendY, BOX.horiz, color);
+			}
+
+			if (fromCenterX < toCenterX) {
+				writeText(grid, fromCenterX, bendY, "└", color);
+				writeText(grid, toCenterX, bendY, "┐", color);
+			} else {
+				writeText(grid, fromCenterX, bendY, "┘", color);
+				writeText(grid, toCenterX, bendY, "┌", color);
+			}
+
+			for (let y = bendY + 1; y < toTopY - 1; y++) {
+				writeText(grid, toCenterX, y, BOX.vert, color);
+			}
+			writeText(grid, toCenterX, toTopY - 1, BOX.arrowDown, color);
+		}
+	} else if (to.row === from.row) {
+		const y = rowOffset + from.y + Math.floor(from.height / 2);
+		const startX = from.x + from.width;
+		const endX = to.x;
+		for (let x = startX; x < endX - 1; x++) {
+			writeText(grid, x, y, BOX.horiz, color);
+		}
+		writeText(grid, endX - 1, y, BOX.arrowRight, color);
+	}
+}

package/src/flow/types.ts

@@ -0,0 +1,45 @@
+import type { CLINode } from "../types";
+
+export interface Workflow {
+	name: string;
+	description?: string;
+	cli: string;
+	version?: string;
+	nodes: WorkflowNode[];
+	edges: WorkflowEdge[];
+}
+
+export interface WorkflowNode {
+	id: string;
+	command: string[];
+	label?: string;
+	description?: string;
+	optional?: boolean;
+	ref?: CLINode;
+}
+
+export interface WorkflowEdge {
+	from: string;
+	to: string;
+	condition?: string;
+	label?: string;
+}
+
+export interface FlowRenderOptions {
+	color?: boolean;
+	showDescriptions?: boolean;
+	showCommands?: boolean;
+	compact?: boolean;
+}
+
+export interface ValidationError {
+	node?: string;
+	edge?: { from: string; to: string };
+	message: string;
+	severity: "error" | "warning";
+}
+
+export interface ValidationResult {
+	valid: boolean;
+	errors: ValidationError[];
+}

package/src/flow/validate.ts

@@ -0,0 +1,111 @@
+import type { CLINode } from "../types";
+import type { Workflow, ValidationError, ValidationResult } from "./types";
+
+export function validateWorkflow(workflow: Workflow, tree?: CLINode): ValidationResult {
+	const errors: ValidationError[] = [];
+	const nodeIds = new Set(workflow.nodes.map(n => n.id));
+
+	if (nodeIds.size !== workflow.nodes.length) {
+		errors.push({ severity: "error", message: "Duplicate node IDs found" });
+	}
+
+	for (const node of workflow.nodes) {
+		if (node.command.length === 0) {
+			errors.push({ node: node.id, severity: "error", message: `Node "${node.id}" has empty command` });
+		}
+		if (node.command[0] !== workflow.cli) {
+			errors.push({
+				node: node.id,
+				severity: "warning",
+				message: `Node "${node.id}" command "${node.command[0]}" does not match workflow cli "${workflow.cli}"`,
+			});
+		}
+	}
+
+	for (const edge of workflow.edges) {
+		if (!nodeIds.has(edge.from)) {
+			errors.push({
+				edge: { from: edge.from, to: edge.to },
+				severity: "error",
+				message: `Edge references unknown node "${edge.from}"`,
+			});
+		}
+		if (!nodeIds.has(edge.to)) {
+			errors.push({
+				edge: { from: edge.from, to: edge.to },
+				severity: "error",
+				message: `Edge references unknown node "${edge.to}"`,
+			});
+		}
+	}
+
+	if (hasCycle(workflow)) {
+		errors.push({ severity: "error", message: "Workflow contains a cycle — DAGs only" });
+	}
+
+	if (tree) {
+		for (const node of workflow.nodes) {
+			const subcommand = node.command.slice(1).filter(arg => !arg.startsWith("-") && !arg.startsWith("$") && /^[a-z]/i.test(arg));
+			if (subcommand.length === 0) {
+				node.ref = tree;
+				continue;
+			}
+
+			const firstMatch = tree.subcommands?.find(s => s.name === subcommand[0] || s.aliases?.includes(subcommand[0]!));
+			if (!firstMatch) {
+				errors.push({
+					node: node.id,
+					severity: "warning",
+					message: `Command "${node.command.join(" ")}" not found in ${workflow.cli} tree`,
+				});
+			} else {
+				node.ref = findInTree(tree, subcommand);
+			}
+		}
+	}
+
+	return {
+		valid: errors.filter(e => e.severity === "error").length === 0,
+		errors,
+	};
+}
+
+function hasCycle(workflow: Workflow): boolean {
+	const adj = new Map<string, string[]>();
+	for (const node of workflow.nodes) adj.set(node.id, []);
+	for (const edge of workflow.edges) {
+		adj.get(edge.from)?.push(edge.to);
+	}
+
+	const WHITE = 0, GRAY = 1, BLACK = 2;
+	const color = new Map<string, number>();
+	for (const node of workflow.nodes) color.set(node.id, WHITE);
+
+	function visit(u: string): boolean {
+		color.set(u, GRAY);
+		for (const v of adj.get(u) ?? []) {
+			const c = color.get(v);
+			if (c === GRAY) return true;
+			if (c === WHITE && visit(v)) return true;
+		}
+		color.set(u, BLACK);
+		return false;
+	}
+
+	for (const node of workflow.nodes) {
+		if (color.get(node.id) === WHITE && visit(node.id)) return true;
+	}
+	return false;
+}
+
+function findInTree(tree: CLINode, path: string[]): CLINode | undefined {
+	let current: CLINode | undefined = tree;
+	for (const segment of path) {
+		const child: CLINode | undefined = current?.subcommands?.find(
+			(s) => s.name === segment || s.aliases?.includes(segment),
+		);
+		if (!child) return current;
+		current = child;
+	}
+	return current;
+}