feat: Add JSON (Human Readable) Output

[SudoBrendan]

Add JSON Output Support with Field Filtering

What does this PR solve?

Adds comprehensive JSON output support for jira issue list and jira issue view commands with three complementary features:

1. Human-readable field names (--json)
2. Output-level precision filtering (--json-filter)
3. API-level optimized field filtering (--api-fields)

While each of these is a feature in their own right - I think they belong together in a single PR since they build on each other. For simpler review, each of these is implemented in a distinct and self-contained commit. If you'd like me to restructure it - please ask :)

Try It

# 1. Start with --json to see all fields with readable names rather than customfield_*
$ jira issue view PROJ-123 --json

# 2. Use --json-filter for precise output control
$ jira issue view PROJ-123 --json \
  --json-filter "key,fields.summary,fields.storyPoints,fields.assignee.displayName"

# 3. Optimize API calls with --api-fields when you know what you need
$ jira issue view PROJ-123 --json \
  --api-fields "key,summary,Story Points,assignee" \
  --json-filter "key,fields.summary,fields.storyPoints,fields.assignee.displayName"

Problem 1: Illegible JSON with Custom Field IDs

Jira's --raw API returns custom fields with IDs like customfield_123123123 instead of meaningful names like storyPoints, making the JSON difficult to parse for humans, scripts, and AI agents.

Solution: New --json flag that:

• Converts customfield_xxxxxx into readable camelCase names (e.g., "Story Points" → storyPoints, "Developer" → developer)
• Preserves all data types and values
• Uses custom field mappings from your existing ~/.config/.jira/.config.yml

Example:

# Before: raw output with custom field IDs
$ jira issue view PROJ-123 --raw
{"fields":{"customfield_12310243":5,"customfield_12316544":{"value":"Yes"},...}}

# After: translated custom fields
$ jira issue view PROJ-123 --json
{"fields":{"storyPoints":5,"blocked":{"value":"Yes"},...}}

Problem 2: Custom Field Name Collisions and Imprecise Output Filtering

Multiple custom fields with similar names can conflict in camelCase output (e.g., "My Chapter" and "My-Chapter" both become myChapter). Additionally, you may want to filter to specific nested fields (e.g., just status.statusCategory.name) rather than the entire status object.

Solution: New --json-filter flag with smart collision handling:

• Filters final JSON output using precise dot-notation paths (e.g., fields.status.statusCategory.name)
• Works on nested fields at any depth
• Automatically detects and skips colliding fields with helpful warnings
• When you explicitly filter by a custom field ID, it's included and transformed to human-readable name
• Includes null values when explicitly requested

Examples:

# Filter to specific nested fields
$ jira issue view PROJ-123 --json --json-filter "key,fields.summary,fields.status.statusCategory.name"

# Collision detected - helpful warning with solution
$ jira issue view PROJ-123 --json
Skipping fields with naming collision 'chapter': [fields.customfield_1001 fields.customfield_1002]. 
Use --json-filter to explicitly select one, e.g.: --json-filter "key,fields.customfield_1002"

# Explicitly select one colliding field by ID
$ jira issue view PROJ-123 --json --json-filter "key,fields.customfield_1002"
{"key":"PROJ-123","fields":{"chapter":"Engineering"}}

# Suppress collision warnings when you don't care
$ jira issue view PROJ-123 --json --no-warnings

Problem 3: Inefficient API Calls

By default, Jira returns ALL fields for an issue, which is slow and wasteful when you only need a few specific fields.

Solution: New --api-fields flag that:

• Fetches only specified fields from Jira API (improves performance)
• Translates human-readable names to custom field IDs automatically (e.g., "Story Points" → customfield_12310243)
• Supports standard fields (key, summary), custom field names, custom field IDs, and wildcards (*navigable, *all)
• Works with both --json and --raw output formats
• Can be combined with --json-filter for maximum efficiency and precision

Examples:

# Fetch only specific fields from API
$ jira issue view PROJ-123 --json --api-fields "key,summary,Story Points,assignee"

# Works with raw output too
$ jira issue view PROJ-123 --raw --api-fields "key,summary,customfield_12310243"

# Combine both for optimal performance and precision
$ jira issue view PROJ-123 --json \
  --api-fields "key,summary,status" \
  --json-filter "key,fields.summary,fields.status.statusCategory.name"

# Works with list too
$ jira issue list --json --api-fields "key,summary,status" \
  --json-filter "key,fields.summary,fields.status.name"

Note: For jira issue list, the --api-fields parameter can only reduce fields returned by the Jira search API, not add new ones (Jira API limitation).

Known Issues

While developing this feature, I discovered that jira epic list and jira sprint list inherit the --json and --raw flags due to how commands are structured, but these flags don't work correctly for those commands. This is an existing bug that also affects --raw. I'm not fixing it here to keep the PR focused.

Credits

This PR was co-authored by Claude AI.

[SudoBrendan]

I've re-opened this, implementation is complete. Thanks for a review!

[SudoBrendan]

cc @ankitpokhrel for awareness. I have really appreciated this tool and use it daily! As I and others in my org have attempted to integrate more with AI, we discovered a few limitations I hope that this PR can address to make interactions with Jira more performant and legible as context to AI agents and people. Thank you!