pcli/openspec/specs/output-formatting/spec.md

ADDED Requirements

Requirement: JSON output envelope

The system SHALL wrap all successful command output in a JSON envelope with the structure {"data": <result>, "error": null}. The system SHALL wrap all error output in a JSON envelope with the structure {"data": null, "error": "<message>"}. The envelope SHALL be written to stdout. The data field SHALL contain the direct result of the command (object or array). The error field SHALL be null on success and a string message on failure.

Scenario: Successful command output

• WHEN a command completes successfully in JSON format
• THEN stdout SHALL contain {"data": <result>, "error": null}
• AND the process SHALL exit with code 0

Scenario: Error command output

• WHEN a command fails in JSON format
• THEN stdout SHALL contain {"data": null, "error": "<message>"}
• AND the process SHALL exit with code 1

Scenario: Envelope structure is consistent

• WHEN any command is executed in JSON format
• THEN the output SHALL always contain exactly the keys data and error at the top level

Requirement: Table format output

The system SHALL support a --format=table flag that outputs results as human-readable tabular text. Table output SHALL be written to stdout. Table output SHALL NOT use the JSON envelope. When table format is active and an error occurs, the error message SHALL be written to stderr (not stdout). Each resource type SHALL define its own column set for table rendering.

Scenario: Table output for a list of items

• WHEN a list command is executed with --format=table
• THEN stdout SHALL contain a header row followed by one row per item
• AND columns SHALL be aligned and separated by whitespace

Scenario: Table output for a single item

• WHEN a get command is executed with --format=table
• THEN stdout SHALL contain a key-value representation of the item

Scenario: Error in table format

• WHEN a command fails with --format=table
• THEN the error message SHALL be written to stderr
• AND the process SHALL exit with code 1

Requirement: Format flag default

The system SHALL default to JSON format when no --format flag is provided. The --format flag SHALL accept values json and table. Any other value SHALL cause an error and exit with code 1.

Scenario: Default format is JSON

• WHEN a command is executed without --format
• THEN the output SHALL be in JSON envelope format

Scenario: Explicit JSON format

• WHEN a command is executed with --format=json
• THEN the output SHALL be in JSON envelope format

Scenario: Explicit table format

• WHEN a command is executed with --format=table
• THEN the output SHALL be in table format

Scenario: Invalid format value

• WHEN a command is executed with --format=xml
• THEN the system SHALL print an error and exit with code 1

Requirement: Log output separation

All log output SHALL be written to stderr using structured JSON via log/slog. Log output SHALL never appear on stdout. This ensures that stdout contains only the command's data output (JSON envelope or table) and is safe to pipe or parse programmatically.

Scenario: Logs do not pollute stdout

• WHEN a command is executed with --log-level=debug
• THEN all log entries SHALL appear on stderr
• AND stdout SHALL contain only the command's data output

Scenario: Logs are structured JSON

• WHEN a log entry is emitted
• THEN it SHALL be a valid JSON object with at minimum time, level, and msg fields