Standardize CLI output into a pipeline-friendly envelope

[roshan2004]

What

Makes CLI output predictable for scripting. Every --json command now wraps its payload in one common envelope, so a downstream tool reads the same keys no matter which command produced the JSON:

{
  "tool": "molscope", "version": "0.16.0", "command": "qc",
  "input": "3ptb.pdb",        // path/id, or a list for batch commands
  "parser": "pdb",            // reader chosen from the extension
  "backends": ["scipy"],      // optional packages this run engaged
  "warnings": [ ... ],
  "result": { ... }           // command-specific payload
}

Applied to qc, structure-report, compare, preflight, presets.

Batch run manifests

analyze and export gain --manifest PATH, which writes the same envelope alongside the outputs with:

• feature_names — the CSV descriptor columns (analyze) / graph node+edge feature names (export)
• skipped — one {input, error} per file that failed (previously only printed to stderr)
• n_inputs / n_written, plus output/out_dir/to/preset

molscope analyze "data/*.pdb" --out features.csv --manifest run.json
molscope export "data/*.cif" --to pyg -o graphs/ --manifest run.json

The analyze/export workers now return structured (path, result, error) outcomes so skips are captured, not just logged.

Honest backends

backends is computed by snapshotting sys.modules at the handler entry and reporting which optional packages (rdkit, gemmi, scipy, torch, torch_geometric, dgl, networkx, ...) were imported during the run — an accurate "engaged this run" signal in a one-shot CLI process, and snapshot-diffed so it stays correct in the long-lived test process too.

⚠️ Breaking (CLI output only)

The five --json commands now emit the envelope instead of the bare report; previous top-level fields move under result (e.g. payload["ligands"] → payload["result"]["ligands"], and presets --json is now an object, not a bare list). Documented under Changed in the CHANGELOG. No Python API changes.

Scope

Covers the inspection --json commands and the two feature-producing batch commands — where feature_names/skipped actually apply. The docking-triage and select/binding-site CSV commands keep their established multi-file outputs (their file columns already carry the input path); a manifest for those is a natural follow-up.

Tests & docs

• New tests/test_cli_output.py (helpers + end-to-end envelope + manifests, incl. all-skipped and partial-skip cases); cli_output.py 98% covered. Updated the 5 tests that asserted the old flat shape.
• Full suite: 926 passed, 21 skipped; ruff check clean.
• Docs: a "Pipeline-friendly output" section in the README + CHANGELOG (Added + Breaking).

[codecov]

Codecov Report

❌ Patch coverage is 98.93617% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
molscope/cli_output.py	97.14%	0 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!