backlog.md 0.1.0

package/src/ui/checklist.ts

@@ -0,0 +1,103 @@
+/* Checklist alignment utilities for consistent checkbox display */
+
+export interface ChecklistItem {
+	text: string;
+	checked: boolean;
+}
+
+/**
+ * Regex patterns for detecting checkbox markdown
+ */
+export const CHECKBOX_PATTERNS = {
+	// Matches "- [ ] text" or "- [x] text" with optional leading whitespace
+	CHECKBOX_LINE: /^\s*-\s*\[([ x])\]\s*(.*)$/,
+	// Matches just the checkbox part
+	CHECKBOX_PREFIX: /^-\s*\[([ x])\]\s*/,
+} as const;
+
+/**
+ * Parse a line to extract checkbox state and text
+ */
+export function parseCheckboxLine(line: string): ChecklistItem | null {
+	const match = line.match(CHECKBOX_PATTERNS.CHECKBOX_LINE);
+	if (!match) return null;
+
+	const [, checkState, text] = match;
+	return {
+		text: text.trim(),
+		checked: checkState === "x",
+	};
+}
+
+/**
+ * Format a checklist item with aligned checkbox display
+ */
+export function formatChecklistItem(
+	item: ChecklistItem,
+	options: {
+		padding?: string;
+		checkedSymbol?: string;
+		uncheckedSymbol?: string;
+	} = {},
+): string {
+	const { padding = " ", checkedSymbol = "[x]", uncheckedSymbol = "[ ]" } = options;
+
+	const checkbox = item.checked ? checkedSymbol : uncheckedSymbol;
+	return `${padding}${checkbox} ${item.text}`;
+}
+
+/**
+ * Process acceptance criteria section and align checkboxes
+ */
+export function alignAcceptanceCriteria(criteriaSection: string): string[] {
+	if (!criteriaSection) return [];
+
+	return criteriaSection
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0)
+		.map((line) => {
+			const item = parseCheckboxLine(line);
+			if (item) {
+				return formatChecklistItem(item);
+			}
+			// Return non-checkbox lines as-is with minimal padding
+			return ` ${line}`;
+		});
+}
+
+/**
+ * Extract and format acceptance criteria from markdown content
+ */
+export function extractAndFormatAcceptanceCriteria(content: string): string[] {
+	const criteriaSection = extractSection(content, "Acceptance Criteria");
+	if (!criteriaSection) return [];
+
+	return alignAcceptanceCriteria(criteriaSection);
+}
+
+/**
+ * Extract a section from markdown content
+ */
+function extractSection(content: string, sectionTitle: string): string | undefined {
+	const regex = new RegExp(`## ${sectionTitle}\\s*\\n([\\s\\S]*?)(?=\\n## |$)`, "i");
+	const match = content.match(regex);
+	return match?.[1]?.trim();
+}
+
+/**
+ * Format multiple checklist items with consistent alignment
+ */
+export function formatChecklist(items: ChecklistItem[]): string[] {
+	return items.map((item) => formatChecklistItem(item));
+}
+
+/**
+ * Parse multiple checkbox lines from text
+ */
+export function parseCheckboxLines(text: string): ChecklistItem[] {
+	return text
+		.split("\n")
+		.map((line) => parseCheckboxLine(line))
+		.filter((item): item is ChecklistItem => item !== null);
+}

package/src/ui/code-path.ts

@@ -0,0 +1,113 @@
+/* Code path detection and styling utilities */
+
+/**
+ * Regex patterns for detecting code paths in backticks
+ */
+export const CODE_PATH_PATTERNS = {
+	// Matches `src/cli.ts`, `package.json`, `/full/path/file.ts`
+	BACKTICKED_PATH: /`([^`]+)`/g,
+	// Matches file extensions
+	FILE_EXTENSION: /\.[a-zA-Z0-9]+$/,
+	// Matches path separators
+	PATH_SEPARATOR: /[\/\\]/,
+} as const;
+
+/**
+ * Detect if a backticked string is likely a file path
+ */
+export function isCodePath(content: string): boolean {
+	// Has file extension OR contains path separator
+	return CODE_PATH_PATTERNS.FILE_EXTENSION.test(content) || CODE_PATH_PATTERNS.PATH_SEPARATOR.test(content);
+}
+
+/**
+ * Extract all code paths from text
+ */
+export function extractCodePaths(text: string): string[] {
+	const matches = text.match(CODE_PATH_PATTERNS.BACKTICKED_PATH);
+	if (!matches) return [];
+
+	return matches
+		.map((match) => match.slice(1, -1)) // Remove backticks
+		.filter(isCodePath);
+}
+
+/**
+ * Style a code path for blessed display
+ */
+export function styleCodePath(path: string): string {
+	return `{gray-fg}\`${path}\`{/gray-fg}`;
+}
+
+/**
+ * Transform text to style code paths and place them on separate lines
+ */
+export function transformCodePaths(text: string): string {
+	if (!text) return text;
+
+	// Split into lines to preserve existing line breaks
+	const lines = text.split("\n");
+	const result: string[] = [];
+
+	for (const line of lines) {
+		let transformedLine = line;
+		const codePaths = extractCodePaths(line);
+
+		if (codePaths.length === 0) {
+			// No code paths, add line as-is
+			result.push(transformedLine);
+			continue;
+		}
+
+		// Check if line contains only a code path (possibly with minimal surrounding text)
+		const lineWithoutPaths = line.replace(/`[^`]+`/g, "").trim();
+		const isIsolatedPath = codePaths.length === 1 && lineWithoutPaths.length < 10;
+
+		if (isIsolatedPath) {
+			// Style the code path in place
+			for (const path of codePaths) {
+				transformedLine = transformedLine.replace(`\`${path}\``, styleCodePath(path));
+			}
+			result.push(transformedLine);
+		} else {
+			// Extract code paths to separate lines
+			let workingLine = transformedLine;
+			const pathsToExtract: string[] = [];
+
+			for (const path of codePaths) {
+				const backticked = `\`${path}\``;
+				if (workingLine.includes(backticked)) {
+					// Remove from line and collect for separate placement, clean up extra spaces
+					workingLine = workingLine.replace(backticked, " ").replace(/\s+/g, " ").trim();
+					pathsToExtract.push(path);
+				}
+			}
+
+			// Add the line without code paths (if not empty)
+			if (workingLine.length > 0) {
+				result.push(workingLine);
+			}
+
+			// Add each code path on its own line
+			for (const path of pathsToExtract) {
+				result.push(styleCodePath(path));
+			}
+		}
+	}
+
+	return result.join("\n");
+}
+
+/**
+ * Simple styling for plain text (without blessed tags)
+ */
+export function transformCodePathsPlain(text: string): string {
+	if (!text) return text;
+
+	return text.replace(CODE_PATH_PATTERNS.BACKTICKED_PATH, (match, path) => {
+		if (isCodePath(path)) {
+			return `\`${path}\``;
+		}
+		return match;
+	});
+}

package/src/ui/heading.ts

@@ -0,0 +1,121 @@
+/* Heading helper component for consistent terminal UI styling */
+
+import { createRequire } from "node:module";
+
+// Load blessed dynamically
+// biome-ignore lint/suspicious/noExplicitAny: blessed is dynamically loaded
+async function loadBlessed(): Promise<any | null> {
+	try {
+		const require = createRequire(import.meta.url);
+		const blessed = require("blessed");
+		return blessed;
+	} catch {
+		try {
+			// biome-ignore lint/suspicious/noExplicitAny: dynamic import
+			const mod = (await import("blessed")) as any;
+			return mod.default ?? mod;
+		} catch {
+			return null;
+		}
+	}
+}
+
+export type HeadingLevel = 1 | 2 | 3;
+
+/**
+ * Get the styling for a heading level
+ */
+export function getHeadingStyle(level: HeadingLevel): { color: string; bold: boolean } {
+	switch (level) {
+		case 1:
+			return { color: "bright-white", bold: true };
+		case 2:
+			return { color: "cyan", bold: false };
+		case 3:
+			return { color: "white", bold: false };
+		default:
+			return { color: "white", bold: false };
+	}
+}
+
+/**
+ * Format heading text with appropriate blessed tags
+ */
+export function formatHeading(text: string, level: HeadingLevel): string {
+	const style = getHeadingStyle(level);
+	const colorTag = style.color.replace("-", "");
+
+	if (style.bold) {
+		return `{bold}{${colorTag}-fg}${text}{/${colorTag}-fg}{/bold}`;
+	}
+	return `{${colorTag}-fg}${text}{/${colorTag}-fg}`;
+}
+
+/**
+ * Create a heading box with proper styling and spacing
+ */
+export async function createHeading(
+	// biome-ignore lint/suspicious/noExplicitAny: blessed types
+	parent: any,
+	text: string,
+	level: HeadingLevel,
+	options: {
+		top?: number | string;
+		left?: number | string;
+		width?: number | string;
+	} = {},
+	// biome-ignore lint/suspicious/noExplicitAny: blessed element type
+): Promise<any | null> {
+	const blessed = await loadBlessed();
+	if (!blessed) return null;
+
+	const style = getHeadingStyle(level);
+
+	return blessed.box({
+		parent,
+		content: formatHeading(text, level),
+		top: options.top || 0,
+		left: options.left || 0,
+		width: options.width || "100%",
+		height: 1,
+		tags: true,
+		style: {
+			fg: style.color,
+			bold: style.bold,
+		},
+	});
+}
+
+/**
+ * Add a heading with automatic spacing (blank line before)
+ */
+export async function addHeadingWithSpacing(
+	// biome-ignore lint/suspicious/noExplicitAny: blessed types
+	parent: any,
+	text: string,
+	level: HeadingLevel,
+	currentTop: number,
+	options: {
+		left?: number | string;
+		width?: number | string;
+	} = {},
+	// biome-ignore lint/suspicious/noExplicitAny: blessed element type
+): Promise<{ element: any; nextTop: number }> {
+	const blessed = await loadBlessed();
+	if (!blessed) return { element: null, nextTop: currentTop };
+
+	// Add blank line before heading (except if it's the very first element)
+	const actualTop = currentTop === 0 ? 0 : currentTop + 1;
+
+	const heading = await createHeading(parent, text, level, {
+		top: actualTop,
+		left: options.left,
+		width: options.width,
+	});
+
+	// Return next available position (heading + 1 line for spacing after)
+	return {
+		element: heading,
+		nextTop: actualTop + 1,
+	};
+}

package/src/ui/loading.ts

@@ -0,0 +1,216 @@
+/**
+ * Loading screen utilities for blessed-based terminal UI
+ */
+
+import { createRequire } from "node:module";
+
+// biome-ignore lint/suspicious/noExplicitAny: blessed is dynamically loaded
+async function loadBlessed(): Promise<any | null> {
+	try {
+		const require = createRequire(import.meta.url);
+		return require("blessed");
+	} catch {
+		try {
+			// biome-ignore lint/suspicious/noExplicitAny: dynamic import
+			const mod = await import("blessed" as any);
+			return mod.default ?? mod;
+		} catch {
+			return null;
+		}
+	}
+}
+
+export interface LoadingScreen {
+	update: (message: string) => void;
+	close: () => void;
+}
+
+/**
+ * Show a loading screen while an async operation runs.
+ * Falls back to console.log if blessed is not available.
+ */
+export async function withLoadingScreen<T>(message: string, operation: () => Promise<T>): Promise<T> {
+	const blessed = await loadBlessed();
+
+	if (!blessed) {
+		// Fallback: just log the message
+		console.log(`${message}...`);
+		return operation();
+	}
+
+	const screen = blessed.screen({
+		smartCSR: true,
+		title: "Loading...",
+	});
+
+	// Create loading box
+	const loadingBox = blessed.box({
+		parent: screen,
+		top: "center",
+		left: "center",
+		width: "50%",
+		height: 7,
+		border: "line",
+		label: " Loading ",
+		padding: 1,
+		style: {
+			border: { fg: "cyan" },
+		},
+	});
+
+	// Loading message
+	const messageText = blessed.text({
+		parent: loadingBox,
+		top: 0,
+		left: "center",
+		content: message,
+		style: { fg: "white" },
+	});
+
+	// Spinner
+	const spinnerChars = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+	let spinnerIndex = 0;
+
+	const spinner = blessed.text({
+		parent: loadingBox,
+		top: 2,
+		left: "center",
+		content: spinnerChars[0],
+		style: { fg: "cyan" },
+	});
+
+	// Start spinner animation
+	const spinnerInterval = setInterval(() => {
+		spinnerIndex = (spinnerIndex + 1) % spinnerChars.length;
+		spinner.setContent(spinnerChars[spinnerIndex]);
+		screen.render();
+	}, 100);
+
+	// Allow escape to cancel (though operation continues)
+	let cancelled = false;
+	screen.key(["escape", "C-c"], () => {
+		cancelled = true;
+		clearInterval(spinnerInterval);
+		screen.destroy();
+	});
+
+	screen.render();
+
+	try {
+		const result = await operation();
+
+		// Clean up
+		clearInterval(spinnerInterval);
+		if (!cancelled) {
+			screen.destroy();
+		}
+
+		return result;
+	} catch (error) {
+		// Clean up on error
+		clearInterval(spinnerInterval);
+		if (!cancelled) {
+			screen.destroy();
+		}
+		throw error;
+	}
+}
+
+/**
+ * Create a loading screen that can be updated with progress messages.
+ * Useful for multi-step operations.
+ */
+export async function createLoadingScreen(initialMessage: string): Promise<LoadingScreen | null> {
+	const blessed = await loadBlessed();
+
+	if (!blessed) {
+		// Fallback: return a simple console logger
+		console.log(`${initialMessage}...`);
+		return {
+			update: (msg) => console.log(`  ${msg}...`),
+			close: () => {},
+		};
+	}
+
+	const screen = blessed.screen({
+		smartCSR: true,
+		title: "Loading...",
+	});
+
+	const loadingBox = blessed.box({
+		parent: screen,
+		top: "center",
+		left: "center",
+		width: "60%",
+		height: 10,
+		border: "line",
+		label: " Loading ",
+		padding: 1,
+		scrollable: true,
+		alwaysScroll: true,
+		style: {
+			border: { fg: "cyan" },
+		},
+	});
+
+	// Progress messages area
+	const messages = blessed.log({
+		parent: loadingBox,
+		top: 0,
+		left: 0,
+		width: "100%-2",
+		height: "100%-2",
+		tags: true,
+		style: { fg: "white" },
+	});
+
+	// Add initial message
+	messages.log(initialMessage);
+
+	// Spinner at bottom
+	const spinnerChars = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+	let spinnerIndex = 0;
+
+	const spinner = blessed.text({
+		parent: screen,
+		bottom: 1,
+		left: "center",
+		content: spinnerChars[0],
+		style: { fg: "cyan" },
+	});
+
+	// Start spinner animation
+	const spinnerInterval = setInterval(() => {
+		spinnerIndex = (spinnerIndex + 1) % spinnerChars.length;
+		spinner.setContent(spinnerChars[spinnerIndex]);
+		screen.render();
+	}, 100);
+
+	// Allow escape to close
+	let closed = false;
+	screen.key(["escape", "C-c"], () => {
+		if (!closed) {
+			closed = true;
+			clearInterval(spinnerInterval);
+			screen.destroy();
+		}
+	});
+
+	screen.render();
+
+	return {
+		update: (message: string) => {
+			if (!closed) {
+				messages.log(message);
+				screen.render();
+			}
+		},
+		close: () => {
+			if (!closed) {
+				closed = true;
+				clearInterval(spinnerInterval);
+				screen.destroy();
+			}
+		},
+	};
+}

package/src/ui/status-icon.ts

@@ -0,0 +1,53 @@
+/* Status icon and color mappings for consistent UI display */
+
+export interface StatusStyle {
+	icon: string;
+	color: string;
+}
+
+/**
+ * Get the icon and color for a given status
+ * @param status - The task status
+ * @returns The icon and color for the status
+ */
+export function getStatusStyle(status: string): StatusStyle {
+	const statusMap: Record<string, StatusStyle> = {
+		Done: { icon: "✔", color: "green" },
+		"In Progress": { icon: "◒", color: "yellow" },
+		Blocked: { icon: "●", color: "red" },
+		"To Do": { icon: "○", color: "white" },
+		Review: { icon: "◆", color: "blue" },
+		Testing: { icon: "▣", color: "cyan" },
+	};
+
+	// Return the mapped style or default for unknown statuses
+	return statusMap[status] || { icon: "○", color: "white" };
+}
+
+/**
+ * Get just the color for a status (for backward compatibility)
+ * @param status - The task status
+ * @returns The color for the status
+ */
+export function getStatusColor(status: string): string {
+	return getStatusStyle(status).color;
+}
+
+/**
+ * Get just the icon for a status
+ * @param status - The task status
+ * @returns The icon for the status
+ */
+export function getStatusIcon(status: string): string {
+	return getStatusStyle(status).icon;
+}
+
+/**
+ * Format a status with its icon
+ * @param status - The task status
+ * @returns The formatted status string with icon
+ */
+export function formatStatusWithIcon(status: string): string {
+	const style = getStatusStyle(status);
+	return `${style.icon} ${status}`;
+}