TextNLPClassifierApp/specs/005-convert-json-markdown/contracts/cli-contract.md

CLI Contract: convert_article_to_markdown.py

Feature: 005-convert-json-markdown | Date: 2026-08-21

1. Script Signature

python scripts/convert_article_to_markdown.py -i <input_path> [-o <output_path>]

2. Command-Line Arguments

Flag	Long Option	Type	Required	Default	Description
-i	--input	String / Path	Yes	—	Path to the source JSON file containing exactly one article object.
-o	--output	String / Path	No	<input_stem>.md	Destination path for the generated Markdown file.

3. Exit Codes

Exit Code	Meaning	Standard Streams Behavior
0	Success: Article converted and Markdown written atomically.	Diagnostic info on stderr, clean execution.
1	Runtime / Validation Error: Malformed JSON, root articles array, missing mandatory fields (title, original URL, body), invalid selected extractor, or write failure.	Descriptive error message printed to stderr. Pre-existing target file unmodified.
2	Argument Error: Missing required -i/--input argument, unrecognized arguments, or invalid CLI usage.	Standard argparse usage and error output printed to stderr.

4. Standard Stream Behavior

• stdout: Reserved. No Markdown text is dumped to stdout when generating file output.
• stderr: Receives progress/error diagnostics, e.g.:
  • [INFO] Converted 'out/article_001.json' -> 'out/article_001.md' (extractor: trafilatura)
  • [ERROR] Invalid input: JSON contains batch 'articles' array. Only single article JSON files are accepted.