docs(json): avec --json, l'erreur sort sur stderr et stdout reste vide #352

Le cas

Avec --json, quand une commande échoue, l'objet d'erreur JSON sort sur stderr et stdout reste vide.

En mots simples : un programme a deux « tuyaux » de sortie. stdout (sortie normale) sert aux données. stderr (sortie d'erreur) sert aux messages, avertissements et erreurs. Un agent qui lit seulement stdout pour analyser le JSON ne voit rien en cas d'échec ; il n'a que le code de sortie (exit 2).

Pascal ne veut pas régler ça tout de suite ; à trier plus tard.

Trouvé pendant l'UAT v4 de #346, le 28 oct. 2026, sur le Mac mini et sur om1.

Reproduire

printf 'pas une video\n' > faux.mp4
ncly video convert faux.mp4 --json --no-input 2>/dev/null   # rien ne s'affiche, exit 2
ncly video convert faux.mp4 --json --no-input 1>/dev/null   # l'objet d'erreur s'affiche

Obtenu

• exit 2, stdout vide.
• L'objet JSON complet (code VIDEO_CONVERT_UNREADABLE, message, hint) est sur stderr.

Ce que dit le contrat

docs/north-star/contract/output.md est explicite :

stdout carries data. stderr carries progress, warnings, and errors.

On failure, stdout stays empty and the object ends stderr.

Le comportement observé est donc conforme au contrat. Ce n'est pas un défaut de l'extension.

Attendu / question à trancher

Décider si on garde ce choix (et le documenter plus clairement pour les agents, par exemple dans le skill nicely : « en cas d'échec, lire le JSON sur stderr »), ou si on change le contrat pour mettre l'objet d'erreur sur stdout.

Pourquoi c'est important

Un agent qui parse --json doit savoir où chercher l'erreur. Sinon il voit une sortie vide et doit deviner à partir du code de sortie.

Gravité

Cosmétique / documentation. Rien n'est cassé.

Environnement

• Mac mini (m4mini), HandBrakeCLI 1.11.2 ; om1 (Arch Linux)
• ncly v0.23.1, extension ncly-video-convert v0.1.2 (0b790fd)

Correctif probable

Plutôt dans la documentation de nicely (contrat et skill nicely), pas dans pascalandy/ncly-video-convert, qui suit déjà le contrat.

Fait quand

Pascal a tranché : soit la doc pour agents dit clairement où lire l'erreur JSON, soit le contrat change et les extensions suivent.

Related to #346 · Part of #333

by Grok Bot pour Pascal