Output Formatting System

Relevant source files

The following files were used as context for generating this wiki page:

• src/output.ts
• tests/output.test.ts
• CLAUDE.md
• src/commands/songs.ts
• src/commands/content/templatesCommand.ts
• src/commands/content/createCommand.ts
• src/commands/content/validateCommand.ts

The Output Formatting System is a core utility module within the Recoup CLI designed to provide consistent, readable, and flexible data presentation to the end user. It serves as the final layer of the CLI application, transforming raw API responses into structured visual formats such as aligned tables, pretty-printed JSON, or standardized error messages.

The system is architected to support two primary modes of operation: a human-readable plain text default (often utilizing tables or lists) and a machine-readable JSON output toggled via a global --json flag. This dual-mode approach ensures that the CLI is equally effective for manual terminal use and for integration into automated scripts or CI/CD pipelines.
Sources: CLAUDE.md:14-14, src/output.ts:1-41

Core Components and Architecture

The system is centralized in src/output.ts and exported as a set of functional utilities used across all command groups. By following a Single Responsibility Principle (SRP), each function handles a specific type of data transformation.

Primary Functions

Function	Purpose	Input Type	Output Destination
printJson	Formats and prints raw objects.	unknown	stdout
printTable	Renders data in column-aligned rows.	Record<string, unknown>[]	stdout
printError	Standardizes error reporting and exits.	string	stderr

Sources: src/output.ts:1-41, CLAUDE.md:27-27

Data Flow Diagram

This diagram illustrates how data flows from an API response through the formatting logic before being presented to the user.

Formatting Implementations

Tabular Output (printTable)

The printTable function dynamically calculates column widths based on both the header labels and the maximum length of the stringified content in each row. It ensures alignment by padding strings to match the calculated width. If no data is provided, it defaults to printing "No results."

• Logic:
  1. Determine maximum width for each column index.
  2. Generate header string with padding.
  3. Generate separator line using hyphens.
  4. Iterate through rows and pad each cell to match column width.
     Sources: src/output.ts:7-36, tests/output.test.ts:22-44

JSON Output (printJson)

The system utilizes JSON.stringify(data, null, 2) to provide pretty-printed, indented JSON blocks. This is used whenever the --json flag is detected in command options.
Sources: src/output.ts:1-3, src/commands/songs.ts:24-25

Error Handling (printError)

Standardized error reporting prepends the string "Error: " to the message and sends it to console.error. Crucially, this function also triggers process.exit(1) to signal a non-zero exit code to the shell, ensuring robust script integration.
Sources: src/output.ts:38-41, tests/output.test.ts:53-61

Integration Patterns

Different commands implement the formatting system based on the nature of their data.

1. Simple Lists

Used for templates where data is a simple key-value pair.

for (const template of templates) {
  console.log(`- ${template.name}: ${template.description}`);
}

Sources: src/commands/content/templatesCommand.ts:25-27

2. Status Reports

Used in song analysis where responses can be multi-section reports. The logic iterates through the report object and prints formatted sections with separators.

3. Conditional Validation

Used for the content validation pipeline to show readiness status and a list of missing requirements if applicable.
Sources: src/commands/content/validateCommand.ts:19-27

Summary

The Output Formatting System provides the necessary abstraction to keep command implementations focused on business logic while ensuring the CLI output remains professional and consistent. By centralizing table generation and error exit logic, the system reduces code duplication and provides a predictable interface for both human users and automated tools.