Публичные CLI¶
Требования применяются к разработке, тестированию и сборке command-line
interface (CLI), поставляемого независимым пользователям или проектам. Уровни
обязательности определены в корневом README.md.
DEV-CLI-001. Стабильный интерфейс команды¶
Уровень: MUST
Применяется к: имени команды, subcommands, options, аргументам и exit codes
CLI должен иметь версионируемый контракт команд. Удаление или переименование команды либо option, изменение значения по умолчанию, формата вывода для машин или смысла exit code является несовместимым изменением.
Обоснование¶
CLI используется скриптами, где текстовая поверхность является API.
Проверка¶
- snapshot или schema test help и machine output;
- compatibility test предыдущего invocation;
- проверка exit code каждого класса результата.
Исключения¶
Свободный человекочитаемый текст может меняться, если он не объявлен машинно-читаемым контрактом.
DEV-CLI-002. Разделение вывода и диагностики¶
Уровень: MUST
Применяется к: stdout, stderr и machine-readable output
Успешный машинно-читаемый результат должен выводиться в stdout, диагностика —
в stderr. Режим машинного вывода должен иметь версионируемую схему и не
содержать progress, цветовые escape sequence или локализованный текст вне
схемы. Неуспех должен возвращать ненулевой стабильный exit code.
Обоснование¶
Смешанный вывод нельзя надёжно использовать в pipeline.
Проверка¶
- contract-тест потоков и exit codes;
- schema validation machine output;
- запуск без TTY и с перенаправлением потоков.
Исключения¶
Интерактивная команда может использовать terminal control только при обнаруженном TTY и должна иметь неинтерактивный эквивалент.
DEV-CLI-003. Неинтерактивность и отмена¶
Уровень: MUST
Применяется к: использованию CLI в CI и скриптах
Каждый обязательный ввод должен приниматься аргументом, stdin или явно
объявленным environment input. В неинтерактивном режиме CLI не должен ожидать
prompt. Получение сигнала отмены должно прекращать запуск с ненулевым exit code
и не оставлять частично записанный локальный output как успешный результат.
Обоснование¶
Скрытый prompt блокирует pipeline, а частичный output может быть принят за готовый артефакт.
Проверка¶
- запуск без TTY и обязательного input;
- тест сигнала отмены во время записи;
- проверка атомарности создаваемого файла.
Исключения¶
Команда, предназначенная исключительно для интерактивного использования, должна явно отклонять запуск без TTY.
DEV-CLI-004. Защита credentials¶
Уровень: MUST
Применяется к: CLI, принимающему credential или секрет
Credential не должен приниматься обычным аргументом командной строки,
выводиться в shell completion, history, лог или сообщение ошибки. CLI должен
использовать ввод и маскирование по SEC-SCRT-002.
Обоснование¶
Аргументы и история shell доступны другим процессам и сохраняются дольше выполнения команды.
Проверка¶
- проверка process listing и shell history;
- тест marker-секрета во всех потоках;
- review completion scripts.
Исключения¶
Не допускаются для секрета.