Feature Request: Add `jsight doc json` and `jsight doc yaml` subcommands

[Mephistophillis]

Note: A complete reference implementation is already available in my fork: Mephistophillis/jsight-cli @ llm-support. I'm opening this issue as required by the contributing guidelines before submitting a PR.

Summary

Currently, jsight doc only supports HTML output (jsight doc html). This makes it impossible to programmatically process API documentation in CI/CD pipelines, scripts, or by AI agents.

We propose adding two new subcommands — jsight doc json and jsight doc yaml — that output the native JSight catalog (produced by the internal ToJson() method) in machine-readable formats.

Problem

jsight doc currently supports only HTML output. The existing jsight convert openapi json/yaml is not a solution — it converts to the OpenAPI specification, not the native JSight structure, and it has no --output flag.

Issues with HTML-only output:

1. HTML cannot be consumed by scripts, AI agents, or CI/CD pipelines.
2. The internal IR already holds all the needed data, but it's exposed only through HTML rendering.
3. Tools like jq and yq cannot parse HTML documentation.
4. LLM agents cannot reliably extract structured data from HTML to auto-generate client code or tests.

Proposed Solution

Add two new subcommands under jsight doc:

jsight doc json <file.jst> [--pretty] [--output/-o <file>] [--strict]
jsight doc yaml <file.jst> [--output/-o <file>] [--strict]

The output is the raw JSight catalog from the internal ToJson() method — no field renaming or additional metadata.

Command Tree (after)

jsight
├── doc
│   ├── html    ← existing
│   ├── json    ← NEW
│   └── yaml    ← NEW
├── convert
│   └── openapi
└── version

New Flags

Flag	Description	Default	Commands
--pretty	Indent JSON output with 2 spaces	enabled	json only
--output / -o	Write to file instead of stdout	—	json, yaml
--strict	Non-zero exit code on any warning	disabled	json, yaml

Exit Codes

Code	Situation
0	Success
1	.jst parse error
2	File not found
3	Serialization or file write error
4	Warning present + --strict flag

Use Cases

Use Case	Command
Save doc to file	jsight doc json my-api.jst -o doc.json
CI/CD pipe	jsight doc json my-api.jst | jq '.interactions[].path'
AI agent consumption	jsight doc json my-api.jst (parse stdout)
Breaking change detection	diff <(jsight doc json v1.jst) <(jsight doc json v2.jst)

Backward Compatibility

All existing commands remain unchanged:

• jsight doc html — unchanged
• jsight convert openapi json/yaml — unchanged
• jsight version — unchanged
• All existing tests continue to pass

Implementation Status

All changes are already implemented in the fork and ready for review:

• Implementation of jsight doc json — cmd/doc/json.go
• Implementation of jsight doc yaml — cmd/doc/yaml.go
• DocSerializer interface — internal/serializer/serializer.go
• JSON serializer with --pretty support — internal/serializer/json.go
• YAML serializer — internal/serializer/yaml.go
• Unit tests for JSON and YAML serializers
• README.md updated with new commands
• Maintainer approval
• Integration tests in tests/run-tests.sh (recommended addition)