Skip to content

Commit a41bb2d

Browse files
committed
docs: add JSDoc for CLI command infrastructure
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.
1 parent 4b4331f commit a41bb2d

File tree

2 files changed

+39
-2
lines changed

2 files changed

+39
-2
lines changed

src/commands/blocks.ts

Lines changed: 33 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,12 +14,32 @@ import { sharedCommandConfig } from '../shared-args.internal.ts';
1414
import { formatCurrency, formatModelsDisplay, formatNumber } from '../utils.internal.ts';
1515
import { ResponsiveTable } from '../utils.table.ts';
1616

17-
// Constants for configurable values
17+
/**
18+
* Default number of recent days to show in blocks view
19+
*/
1820
const RECENT_DAYS_DEFAULT = 3;
21+
22+
/**
23+
* Threshold percentage for showing usage warnings (80%)
24+
*/
1925
const WARNING_THRESHOLD = 0.8;
26+
27+
/**
28+
* Terminal width threshold for switching to compact display mode
29+
*/
2030
const COMPACT_WIDTH_THRESHOLD = 120;
31+
32+
/**
33+
* Default terminal width when stdout.columns is not available
34+
*/
2135
const DEFAULT_TERMINAL_WIDTH = 120;
2236

37+
/**
38+
* Formats the time display for a session block
39+
* @param block - Session block to format
40+
* @param compact - Whether to use compact formatting for narrow terminals
41+
* @returns Formatted time string with duration and status information
42+
*/
2343
function formatBlockTime(block: SessionBlock, compact = false): string {
2444
const start = compact
2545
? block.startTime.toLocaleString(undefined, {
@@ -71,6 +91,12 @@ function formatBlockTime(block: SessionBlock, compact = false): string {
7191
return `${start} (${mins}m)`;
7292
}
7393

94+
/**
95+
* Formats the list of models used in a block for display
96+
* @param models - Array of model names
97+
* @param compact - Whether to use compact formatting (unused currently)
98+
* @returns Formatted model names string
99+
*/
74100
function formatModels(models: string[], compact = false): string {
75101
if (models.length === 0) {
76102
return '-';
@@ -79,6 +105,12 @@ function formatModels(models: string[], compact = false): string {
79105
return compact ? formatModelsDisplay(models) : formatModelsDisplay(models);
80106
}
81107

108+
/**
109+
* Parses token limit argument, supporting 'max' keyword
110+
* @param value - Token limit string value
111+
* @param maxFromAll - Maximum token count found in all blocks
112+
* @returns Parsed token limit or undefined if invalid
113+
*/
82114
function parseTokenLimit(value: string | undefined, maxFromAll: number): number | undefined {
83115
if (value == null || value === '') {
84116
return undefined;

src/commands/index.ts

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,19 @@ import { mcpCommand } from './mcp.ts';
77
import { monthlyCommand } from './monthly.ts';
88
import { sessionCommand } from './session.ts';
99

10-
// Create subcommands map
10+
/**
11+
* Map of available CLI subcommands
12+
*/
1113
const subCommands = new Map();
1214
subCommands.set('daily', dailyCommand);
1315
subCommands.set('monthly', monthlyCommand);
1416
subCommands.set('session', sessionCommand);
1517
subCommands.set('blocks', blocksCommand);
1618
subCommands.set('mcp', mcpCommand);
1719

20+
/**
21+
* Default command when no subcommand is specified (defaults to daily)
22+
*/
1823
const mainCommand = dailyCommand;
1924

2025
// eslint-disable-next-line antfu/no-top-level-await

0 commit comments

Comments
 (0)