docs: add JSDoc for CLI command infrastructure

ryoppippi · ryoppippi · commit a41bb2d1745e · 2025-06-17T19:19:51.000+01:00
Add JSDoc documentation for command line interface:
- Main command setup and subcommand mapping in commands/index.ts
- Session blocks command with formatting and parsing utilities
- Constants for display thresholds and terminal width handling

These command modules provide the user-facing CLI interface with
responsive display formatting and comprehensive usage reporting.
diff --git a/src/commands/blocks.ts b/src/commands/blocks.ts
@@ -14,12 +14,32 @@ import { sharedCommandConfig } from '../shared-args.internal.ts';
 import { formatCurrency, formatModelsDisplay, formatNumber } from '../utils.internal.ts';
 import { ResponsiveTable } from '../utils.table.ts';
 
-// Constants for configurable values
+/**
+ * Default number of recent days to show in blocks view
+ */
 const RECENT_DAYS_DEFAULT = 3;
+
+/**
+ * Threshold percentage for showing usage warnings (80%)
+ */
 const WARNING_THRESHOLD = 0.8;
+
+/**
+ * Terminal width threshold for switching to compact display mode
+ */
 const COMPACT_WIDTH_THRESHOLD = 120;
+
+/**
+ * Default terminal width when stdout.columns is not available
+ */
 const DEFAULT_TERMINAL_WIDTH = 120;
 
+/**
+ * Formats the time display for a session block
+ * @param block - Session block to format
+ * @param compact - Whether to use compact formatting for narrow terminals
+ * @returns Formatted time string with duration and status information
+ */
 function formatBlockTime(block: SessionBlock, compact = false): string {
 	const start = compact
 		? block.startTime.toLocaleString(undefined, {
@@ -71,6 +91,12 @@ function formatBlockTime(block: SessionBlock, compact = false): string {
 	return `${start} (${mins}m)`;
 }
 
+/**
+ * Formats the list of models used in a block for display
+ * @param models - Array of model names
+ * @param compact - Whether to use compact formatting (unused currently)
+ * @returns Formatted model names string
+ */
 function formatModels(models: string[], compact = false): string {
 	if (models.length === 0) {
 		return '-';
@@ -79,6 +105,12 @@ function formatModels(models: string[], compact = false): string {
 	return compact ? formatModelsDisplay(models) : formatModelsDisplay(models);
 }
 
+/**
+ * Parses token limit argument, supporting 'max' keyword
+ * @param value - Token limit string value
+ * @param maxFromAll - Maximum token count found in all blocks
+ * @returns Parsed token limit or undefined if invalid
+ */
 function parseTokenLimit(value: string | undefined, maxFromAll: number): number | undefined {
 	if (value == null || value === '') {
 		return undefined;
diff --git a/src/commands/index.ts b/src/commands/index.ts
@@ -7,14 +7,19 @@ import { mcpCommand } from './mcp.ts';
 import { monthlyCommand } from './monthly.ts';
 import { sessionCommand } from './session.ts';
 
-// Create subcommands map
+/**
+ * Map of available CLI subcommands
+ */
 const subCommands = new Map();
 subCommands.set('daily', dailyCommand);
 subCommands.set('monthly', monthlyCommand);
 subCommands.set('session', sessionCommand);
 subCommands.set('blocks', blocksCommand);
 subCommands.set('mcp', mcpCommand);
 
+/**
+ * Default command when no subcommand is specified (defaults to daily)
+ */
 const mainCommand = dailyCommand;
 
 // eslint-disable-next-line antfu/no-top-level-await
