Исторический документ из исходной ревизии 61e75e9. Этот план реализации сохранён для справки и не является актуальной инструкцией по реализации. Исходный документ.

Техническое задание: CLI okf для OKF v0.2

1. Цель

Сделать все интерфейсы чтения и записи CLI учитывающими версию, показывать сигналы v0.2 и подключить единый планировщик миграции без доменной логики в main.go.

Зависимости: task09.md–task15.md.

2. Архитектура

Оставить cmd/okf/main.go точкой запуска. Вынести координацию команд в internal/okfcli:

• диспетчеризация, аргументы, справка и версия;
• validate/info/parse/fmt/index/graph/migrate;
• стабильные DTO и средства формирования текстового и JSON-вывода.

Разрешение версии, доверие, устаревание, происхождение, граф и миграция обеспечиваются доменными пакетами. CLI не обходит сырой YAML.

3. Общий селектор

Для команд, работающих с набором:

--spec auto|0.1|0.2

Значение по умолчанию — auto; разрешение версии следует task09. Явный селектор, противоречащий объявленной версии, означает ошибку/несоответствие утверждения, а не незаметное переопределение.

4. Команды

version

Текстовый вывод сообщает версию CLI отдельно от поддерживаемых спецификаций OKF и спецификации по умолчанию. Добавить --json:

{
  "cli_version": "vX.Y.Z",
  "okf_spec_default": "0.2",
  "okf_spec_supported": ["0.1", "0.2"]
}

validate

Сохранить существующие флаги и поля вывода, дополнительно добавить:

• объявленную/эффективную версию;
• разрешение версии/совместимость;
• явный --as-of YYYY-MM-DD для строгой проверки устаревания;
• стабильные коды диагностики и пути к полям.

Для v0.2 не должно быть ложных срабатываний по timestamp/Citations.

info

Добавить детерминированные счётчики:

• уровни доверия;
• статус жизненного цикла;
• устаревшие на дату --as-of;
• источники;
• аттестованные вычисления (Attested Computation);
• ошибки разбора;
• объявленная/эффективная версия.

parse

Типизированное представление в тексте/JSON:

• generated/verified/доверие;
• статус/устаревание;
• источники/атрибуция;
• маркер резервного чтения старого формата;
• сводка контракта вычисления.

Одиночная форма verified и список дают одинаковый результат.

fmt

Остаётся разбором и канонической сериализацией:

• не мигрирует timestamp/Citations;
• сохраняет неизвестные ключи;
• не добавляет generated/version;
• не выполняет скрытую запись без -w.

index

• сохраняет версию 0.1/0.2/будущую версию корневого индекса;
• не проставляет и не повышает версию;
• вложенные индексы не содержат YAML-метаданные.

graph

Передаёт явный профиль проекции и параметры пакету graph; stdout содержит только выбранные данные графа. Сохраняется прежний --dot.

migrate

okf migrate <bundle> --to 0.2
  [--from auto|0.1]
  [--actor <actor>]
  [--write]
  [--format text|json]

По умолчанию — пробный запуск без записи. Делегирует планировщику task15 и не выполняет собственных изменений YAML/файлов. Применение использует атомарную фиксацию в хранилище, привязанную к ревизии и дайджесту.

5. stdout/stderr/код завершения

• 0: успешная команда, соответствие при валидации, корректный пробный запуск/применение.
• 1: несоответствие, блокирующая проблема миграции, ошибка использования/выполнения.
• Отчёты/данные → stdout.
• Ошибки использования/ввода-вывода → stderr с error:.
• Режим JSON → один JSON-документ без баннеров/ANSI.
• Успешная команда ничего не пишет в stderr.
• Пробный запуск миграции с различиями возвращает 0.

6. Тесты

Все тесты следуют AAA.

• Версия в тексте/JSON.
• Объявленная 0.1/0.2, отсутствующая, будущая версия, явный конфликт.
• Строгая проверка v0.2 без предупреждения о timestamp.
• Резервное чтение старого формата.
• Граница доверия/статуса/устаревания.
• Детерминированный текст/JSON.
• Чистота stdout/stderr при JSON-выводе.
• Семантическая сохранность при цикле fmt v0.2 + неизвестные ключи.
• Сохранение версий индексом.
• Выбор профиля графа.
• Порядок флагов, --, неизвестные/повторяющиеся/лишние аргументы.
• Миграция: пробный запуск/отсутствие изменений/конфликт/один некорректный файл/атомарное восстановление.
• Сквозные тесты бинарного файла на канонических фикстурах.

7. Критерии приёмки

• CLI корректно сообщает поддерживаемые спецификации и спецификацию по умолчанию.
• Все команды для наборов используют единый контракт разрешения версии.
• v0.1 остаётся доступной для чтения.
• info/parse показывают сигналы v0.2.
• fmt/index не выполняют скрытую миграцию.
• migrate транзакционна и идемпотентна.
• main.go не содержит доменной логики.
• go test ./... и сквозные тесты бинарного файла проходят.

8. Вне рамок задачи

Среда исполнения/аттестации, преобразование произвольных SQL/текста с помощью LLM и изменение пользовательских relations.