npm - @iwonz/ywtc - Versions diffs - 4.1.0 → 4.1.2 - Mend

@iwonz/ywtc 4.1.0 → 4.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/CHANGELOG.md +30 -0
package/README.md +189 -244
package/dist/clients/confluence-cloud.js +45 -38
package/dist/clients/confluence-cloud.js.map +1 -1
package/dist/clients/confluence-response.d.ts +226 -0
package/dist/clients/confluence-response.js +205 -0
package/dist/clients/confluence-response.js.map +1 -0
package/dist/clients/confluence.js +51 -40
package/dist/clients/confluence.js.map +1 -1
package/dist/connection-verifier.js +6 -1
package/dist/connection-verifier.js.map +1 -1
package/dist/doctor.js +3 -1
package/dist/doctor.js.map +1 -1
package/dist/http.js +28 -2
package/dist/http.js.map +1 -1
package/dist/migrator.js +4 -2
package/dist/migrator.js.map +1 -1
package/dist/report-ui/index.html +7 -7
package/docs/assets/readme-header.png +0 -0
package/docs/assets/report-header-transparent.png +0 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -4,48 +4,24 @@
 # ywtc
-## Описание
-`ywtc` — CLI для переноса страниц между Yandex Wiki и Confluence и экспорта в Markdown или автономный HTML. Утилита сохраняет структуру, ссылки и вложения, явно отмечает деградации и продолжает прерванные операции по state-файлу. Исходные данные и страницы назначения автоматически не удаляются.
+`ywtc` — CLI для переноса страниц между Yandex Wiki и Confluence и экспорта в Markdown или автономный HTML. Он сохраняет иерархию и доступное содержимое, проверяет результат, продолжает прерванные операции и ничего не удаляет автоматически.
 Требуются Node.js `>=24` и npm `>=11.5.1`. Лицензия — [MIT](LICENSE).
-## Возможности
-| Исходный материал | Как переносится |
-| --- | --- |
-| Страницы и структура | Одна страница, полное структурное поддерево или граф связанных страниц. Иерархия восстанавливается, циклы обрабатываются без повторного переноса. Пустая страница-раздел переносится как корректная пустая страница, а не как fallback. |
-| Текст и оформление | Заголовки, абзацы, жирное/курсивное/зачёркнутое и цветное начертание, списки и задачи, цитаты, разделители, inline/preformatted code с языком и обычные таблицы преобразуются в нативную или семантически эквивалентную разметку destination. |
-| Секции и колонки | YFM `layout/block` и Confluence page layouts сохраняются нативными секциями и колонками в Yandex Wiki и Confluence. HTML использует адаптивную сетку; Markdown сохраняет все ячейки по порядку и отмечает линеаризацию как adaptation без ухудшения статуса. |
-| Ссылки и якоря | Ссылки между выбранными страницами переписываются на destination, якоря сохраняются. Внешние ссылки и ссылки за пределы выбранного набора остаются исходными. |
-| Вложения | Переносятся все доступные через API для скачивания файлы, включая PNG/JPEG/GIF/WebP/SVG, PDF, ZIP, DOC/DOCX, XLS/XLSX и PPT/PPTX. Файлы передаются потоково, совпадения имён разрешаются стабильно, размер и SHA-256 проверяются. |
-| Изображения | Прикреплённые изображения становятся attachments destination или локальными файлами экспорта. Внешние изображения остаются внешними; подписи и размеры сохраняются, если destination это поддерживает. |
-| Специальная разметка | В обе стороны сопоставляются notes ↔ `info`/`tip`/`warning`/`note`, cuts ↔ `expand`, tree ↔ `children`, задачи, code, anchors, page/attachment links и изображения. Tabs становятся статическими секциями, Grid — проверяемой статической таблицей. Такие полные эквивалентные представления считаются adaptation и остаются `complete`. Безопасный Storage Format и YFM сохраняются нативно при переносе внутри одного провайдера. |
-| Комментарии | По умолчанию все доступные комментарии страницы собираются в один архивный комментарий: отдельные раскрываемые ветки сохраняют участников, авторов, даты, статусы, inline-контекст, удалённые записи и вложенность ответов. Вложения, на которые есть ссылки в тексте комментариев, складываются в один проверяемый ZIP с hash-prefixed именами и manifest. Для Markdown/HTML создаются локальные секции и ZIP. |
-| Конструкции без точного эквивалента | Создаётся читаемый fallback и при необходимости raw snapshot. Если весь payload представлен и проверен, это adaptation со статусом `complete`; только потеря данных, значимой структуры или невозможность проверки дают degradation и `partial`. |
-### Не переносится
-| Ограничение | Поведение ywtc |
-| --- | --- |
-| История версий | Переносится только актуальное содержимое страницы. |
-| Реакции на комментарии | Не копируются и не влияют на список участников архива. |
-| Комментарии непосредственно к attachments, blog posts и custom content | Не входят в архив страницы; читаются только footer/inline page comments. |
-| Пользовательские сущности, watchers, права и ограничения доступа | Не создаются; исходное авторство комментариев сохраняется в архивном тексте, а destination-объекты создаются пользователем текущего токена и наследуют права destination. |
-| Удалённые, недоступные или не возвращённые source API страницы | Не восстанавливаются; недоступность и пропуски фиксируются в state и отчёте. |
-| Точная пиксельная геометрия, произвольный CSS и активные скрипты | Не исполняются и не обещают визуальную идентичность. Содержимое и поддерживаемая структура сохраняются нативно или статически; неподдерживаемая часть получает читаемый fallback и raw snapshot. |
-| Сторонние и неизвестные macros/виджеты | Не подменяются приблизительным macro без доказанного эквивалента: сохраняются безопасным статическим представлением и raw snapshot с явной degradation. |
-| Внешние файлы и изображения, не принадлежащие source | Не копируются; абсолютный URL, подпись и доступные размеры сохраняются как external reference без ухудшения статуса. Недоступный source-managed ресурс считается неполным переносом. |
-| Активные скрипты, iframe, формы и интерактивное поведение embed-объектов | Не исполняются в destination; вместо них сохраняется безопасное статическое представление или raw snapshot. |
-| Пиксельная идентичность и поведение vendor-specific элементов без эквивалента | Используется ближайшее семантическое представление; различия явно отмечаются в отчёте. |
-## Установка
+## Быстрый старт
 ```bash
-# npm
 npm install -g @iwonz/ywtc
+ywtc init --interactive
+ywtc migrate --interactive
+```
-# npx без глобальной установки
+Первый мастер создаёт рабочий каталог, настраивает Yandex Wiki и Confluence и проверяет соединения. Второй собирает параметры переноса и по умолчанию выполняет dry-run; live-запуск начинается только после подтверждения.
+Другие способы запуска:
+```bash
+# Без глобальной установки
 npx @iwonz/ywtc@latest --version
 # Homebrew
@@ -54,261 +30,230 @@ brew trust --tap iwonz/ywtc
 brew install ywtc
 ```
-Homebrew 7 требует доверить сторонний tap; команда `brew trust` относится только к `iwonz/ywtc`.
+Обновление: `ywtc update` проверяет версию, `ywtc update --install` обновляет через обнаруженный канал, `--via npm|brew` выбирает канал явно.
-Обновление:
+## Возможности
-```bash
-ywtc update                       # только проверка
-ywtc update --install             # канал текущей установки
-ywtc update --install --via brew  # явно через Homebrew
-```
+| Материал | Результат |
+| --- | --- |
+| Страницы и структура | `page`, полное `subtree` или рекурсивный граф `linked`. Иерархия восстанавливается, циклы не создают повторов, пустая страница-раздел остаётся корректной пустой страницей. |
+| Текст и таблицы | Сохраняются заголовки, начертания и цвет, списки и задачи, цитаты, разделители, inline/preformatted code с языком и обычные таблицы. Destination получает нативную или семантически эквивалентную разметку. |
+| Секции и колонки | YFM `layout/block` и Confluence layouts преобразуются в нативные секции и колонки. HTML использует адаптивную сетку; Markdown сохраняет содержимое ячеек в исходном порядке. |
+| Ссылки и якоря | Ссылки внутри выбранного набора переписываются на destination; якоря сохраняются. Внешние ссылки и переходы за границу набора остаются исходными. |
+| Файлы и изображения | Доступные через API вложения передаются потоково с проверкой размера и SHA-256. Поддерживаются любые скачиваемые файлы, включая PNG/JPEG/GIF/WebP/SVG, PDF, ZIP, DOCX, XLSX и PPTX. Коллизии имён разрешаются стабильно. |
+| Специальная разметка | Notes ↔ callout macros, cuts ↔ expand, tree ↔ children, задачи, code, anchors, page/attachment links и изображения получают ближайший эквивалент. Tabs становятся секциями, Grid — проверяемой статической таблицей. |
+| Комментарии | По умолчанию footer/inline page comments архивируются с авторами, датами, статусами и иерархией ответов. Явно упомянутые вложения собираются в проверяемый ZIP с hash-prefixed именами и manifest. |
+| Надёжность содержимого | Новая страница сразу создаётся с полным source-derived body, а не placeholder. Ошибка отдельного ресурса не блокирует текст: остаётся source-ссылка и повторяемый outcome. После записи destination перечитывается и проверяется. |
+| Различия платформ | Безопасная normalization и полная adaptation считаются `complete`. Если эквивалента нет, ywtc сохраняет читаемый fallback и при необходимости raw snapshot; недоказанная полнота становится degradation. |
+### Ограничения
+| Не переносится как исходная сущность | Что сохраняется |
+| --- | --- |
+| История версий | Текущее содержимое; последующие обновления destination образуют его обычную историю версий. |
+| Реакции; комментарии к attachments, blog posts и custom content | Только footer/inline comments страницы. |
+| Пользователи, watchers, права и ограничения доступа | Авторство комментариев остаётся в архивном тексте; новые объекты создаёт владелец токена и они наследуют права destination. |
+| Недоступные или не возвращённые API страницы | Причина и незавершённая ветка фиксируются в state и отчёте. |
+| Произвольный CSS, scripts и неизвестные интерактивные widgets/macros | Безопасное статическое представление, fallback или raw snapshot; тихой потери быть не должно. |
+| Внешние файлы и изображения | Исходный абсолютный URL, alt и доступные размеры; внешние данные не скачиваются. Недоступный source-managed ресурс считается неполным переносом. |
-## Минимальный сценарий
+## Совместимость
-- [ ] Установите `ywtc` одним из способов выше.
-- [ ] Выполните `ywtc init --interactive`.
-- [ ] Выполните `ywtc migrate --interactive`.
+| Source | Destination |
+| --- | --- |
+| Yandex Wiki | Confluence, Yandex Wiki, Markdown, HTML |
+| Confluence | Yandex Wiki, Confluence, Markdown, HTML |
+| Система | Поддерживаемый контракт | Авторизация |
+| --- | --- | --- |
+| Yandex Wiki | Public API v1; новые необязательные поля допускаются | OAuth или пользовательский IAM; `X-Org-Id`/`X-Cloud-Org-Id` |
+| Confluence Data Center | 7.9+ без искусственной верхней границы | Bearer PAT |
+| Confluence Cloud | REST v2 для страниц, REST v1 для attachments | Email + API token |
+Confluence Server, Data Center Basic Auth и OAuth app-flow не поддерживаются. Перед чтением страниц и записью `doctor`/`migrate` проверяет готовность REST API: startup/maintenance HTML и неполный JSON останавливают операцию без создания state или destination-объектов. После восстановления Confluence повторите команду; если сервер исправен, проверьте `baseUrl` и `deployment`. Контрактные тесты не заменяют live-сертификацию каждой patch-версии.
 ## Конфигурация
-Для рабочих команд каталог выбирается в порядке: `--workdir` → текущий каталог, если непосредственно в нём есть `ywtc.config.yaml` → `~/.ywtc`. Поиск по родительским каталогам не выполняется. `ywtc init --interactive` предлагает путь с default `~/.ywtc`; переданный `--workdir` становится редактируемым начальным значением. `migrate` автоматически инициализирует отсутствующий workspace.
+Рабочий каталог выбирается в порядке `--workdir` → `ywtc.config.yaml` непосредственно в текущем каталоге → `~/.ywtc`. Родительские каталоги не просматриваются.
 ```text
 ~/.ywtc/
-├── ywtc.config.yaml        # подключения, настройки и токены; mode 0600 при создании
-└── .states/                # state, cache и отчёты
+├── ywtc.config.yaml   # подключения, настройки и токены
+└── .states/           # state, cache, backups и отчёты
 ```
-`ywtc init --interactive` требует TTY, проводит через обязательные настройки обоих провайдеров, скрывает токены и делает только read-only connection probes. Проверка подтверждает API и авторизацию, но не права конкретных страниц: они проверяются `doctor` или `migrate`. Для существующего workspace доступны изменение выбранных профилей, выход без изменений и настройка с нуля с backup прежнего YAML в `.states/backups/`; state не удаляется.
-`ywtc migrate --interactive` использует тот же порядок выбора workspace, последовательно настраивает source, destination, scope, комментарии и файловый ZIP, а затем по умолчанию запускает dry-run. После него можно открыть отчёт, изменить параметры, повторить проверку или явно начать live-перенос. При неполном inventory, root error, `failed`, `blocked` или настоящем `conflict` live-действие скрывается.
-Обычный `ywtc init` без wizard создаёт безопасный пустой шаблон для автоматизации или ручного управления. Полный пример с Yandex Wiki, Confluence Data Center, Confluence Cloud и сетевыми лимитами: [`ywtc.config.example.yaml`](ywtc.config.example.yaml).
+`ywtc init --interactive` настраивает и проверяет оба провайдера; `ywtc init` создаёт пустой шаблон для автоматизации. `migrate` создаёт отсутствующий workspace, но до API-запросов требует заполнить обязательные поля. Проверка мастера подтверждает API и авторизацию, но не права конкретных страниц: их проверяют `doctor` или `migrate`. Конфигурация строгая, неизвестные поля отклоняются; process environment её не переопределяет. Локальный файл игнорируется Git, новый создаётся с mode `0600`, секреты маскируются в выводе. Полный шаблон: [`ywtc.config.example.yaml`](ywtc.config.example.yaml).
-### Поля профилей
+### Поля `ywtc.config.yaml`
-| Поле | Для кого | Обязательность / значения | Назначение |
+| Поле | Профиль | Значения / default | Назначение |
 | --- | --- | --- | --- |
-| `defaults.timeoutMs` | файл | `1000..300000`, default `30000` | Таймаут HTTP-запроса |
-| `defaults.concurrency` | файл | `1..64`, default `4` | Общая параллельность операции |
-| `connections.<name>` | файл | минимум один; имя `[a-z0-9._-]+` | Именованное подключение |
-| `type` | все профили | `yandex-wiki` или `confluence` | Тип провайдера |
-| `token` | все профили | непустой для используемого профиля | OAuth, IAM, PAT или API token |
-| `apiUrl` | Yandex Wiki | URL Public API v1 | API endpoint |
-| `webUrl` | Yandex Wiki | URL | Базовый адрес Wiki для ссылок и выбора профиля |
-| `authType` | Yandex Wiki | `oauth` (default) или `iam` | Схема авторизации |
-| `organization.type` | Yandex Wiki | `yandex360` (default) или `cloud` | Заголовок `X-Org-Id` или `X-Cloud-Org-Id` |
-| `organization.id` | Yandex Wiki | непустая строка | ID организации |
-| `deployment` | Confluence | `data-center` или `cloud` | Тип развёртывания |
-| `baseUrl` | Confluence | URL | Адрес инстанса, включая context path |
-| `authType` | Confluence | `pat` для Data Center; `api-token` для Cloud | Схема авторизации |
-| `email` | Confluence Cloud | непустой для используемого профиля | Email Atlassian-аккаунта |
-| `limits.readConcurrency` | все профили | `1..64`, default `4` | Параллельные чтения |
-| `limits.writeConcurrency` | все профили | `1..32`, default `2` | Параллельные записи |
-| `limits.downloadConcurrency` | все профили | `1..32`, default `2` | Параллельные скачивания |
-| `limits.uploadConcurrency` | все профили | `1..32`, default `2` | Параллельные загрузки |
-| `limits.requestsPerSecond` | все профили | `1..1000`, default `8` | Средняя частота запросов |
-| `limits.burst` | все профили | `1..1000`, default `8` | Допустимый кратковременный burst |
-Конфигурация строгая: неизвестные поля считаются ошибкой. Все значения, включая токены, email, таймауты и лимиты, читаются только из `ywtc.config.yaml`; process environment их не переопределяет. Файл рабочего каталога игнорируется Git, а токены маскируются в диагностике и отчётах.
-## Направления и совместимость
-| Source | Destination | Поддержка |
-| --- | --- | --- |
-| Yandex Wiki | Confluence | Да |
-| Yandex Wiki | Yandex Wiki | Да, включая другой профиль или инстанс |
-| Confluence | Yandex Wiki | Да |
-| Confluence | Confluence | Да, включая другой профиль или инстанс |
-| Yandex Wiki или Confluence | Markdown | Да |
-| Yandex Wiki или Confluence | статический HTML | Да |
-| Система | Контракт | Авторизация |
-| --- | --- | --- |
-| Yandex Wiki | Public API v1; новые необязательные поля принимаются | OAuth или пользовательский IAM; `X-Org-Id`/`X-Cloud-Org-Id` |
-| Confluence Data Center | 7.9+ без верхней границы; capabilities проверяются до записи | Bearer PAT |
-| Confluence Cloud | REST v2 для страниц и REST v1 для attachments | Email + API token |
-Confluence Server, Data Center Basic Auth и OAuth app-flow не поддерживаются. Совместимость определяется preflight-проверкой необходимых API/capabilities, а не сертификацией каждой patch-версии.
-## Как получить токены
-### Yandex Wiki
-- [ ] Создайте приложение в [Яндекс OAuth](https://oauth.yandex.ru/).
-- [ ] Выдайте права Wiki на чтение; для destination также нужны права записи.
-- [ ] Получите OAuth-токен пользователя с доступом к страницам. Для федеративного пользователя Yandex Cloud допустим IAM-токен и `authType: iam`.
-- [ ] Найдите ID организации в **Yandex Tracker → Администрирование → Организации**.
-- [ ] Укажите `organization.type: yandex360` для Яндекс 360 или `cloud` для Cloud Organization.
-- [ ] Запишите токен в `connections.<name>.token` выбранного профиля.
-### Confluence Data Center
-- [ ] Откройте **Avatar → Settings → Personal access tokens → Create token**.
-- [ ] Создайте PAT и запишите его в `connections.<name>.token`.
-- [ ] Используйте `deployment: data-center` и `authType: pat`.
-- [ ] Проверьте права на чтение source и создание/изменение страниц и вложений destination.
-### Confluence Cloud
-- [ ] Создайте [Atlassian API token](https://id.atlassian.com/manage-profile/security/api-tokens).
-- [ ] Используйте `deployment: cloud`, `authType: api-token`, `token` и `email`.
-- [ ] Запишите API token и email аккаунта непосредственно в выбранный профиль.
-- [ ] Проверьте доступ аккаунта к source и destination spaces.
-## Параметры
+| `defaults.timeoutMs` | общий | `1000..300000`; `30000` | Таймаут HTTP-запроса |
+| `defaults.concurrency` | общий | `1..64`; `4` | Общая параллельность операции |
+| `connections.<name>` | общий | имя `[a-z0-9._-]+` | Именованное подключение |
+| `type` | любой | `yandex-wiki` или `confluence` | Провайдер |
+| `token` | любой | непустой | OAuth, IAM, PAT или API token |
+| `apiUrl` / `webUrl` | Yandex Wiki | URL API v1 / базовый web URL | API-запросы, ссылки и выбор профиля |
+| `authType` | Yandex Wiki | `oauth` или `iam`; `oauth` | Схема авторизации; IAM допустим только с Cloud Organization |
+| `organization.type` | Yandex Wiki | `yandex360` или `cloud`; `yandex360` | Выбирает `X-Org-Id` или `X-Cloud-Org-Id` |
+| `organization.id` | Yandex Wiki | непустой | ID организации |
+| `deployment` | Confluence | `data-center` или `cloud` | Тип инстанса |
+| `baseUrl` | Confluence | URL, включая context path | Базовый адрес API и web |
+| `authType` | Confluence | `pat` или `api-token` | PAT для Data Center; API token для Cloud |
+| `email` | Confluence Cloud | непустой | Atlassian account email для Basic Auth |
+| `limits.readConcurrency` | любой | `1..64`; `4` | Параллельные чтения |
+| `limits.writeConcurrency` | любой | `1..32`; `2` | Параллельные записи |
+| `limits.downloadConcurrency` / `uploadConcurrency` | любой | `1..32`; `2` | Параллельные передачи файлов |
+| `limits.requestsPerSecond` | любой | `1..1000`; `8` | Устойчивая частота запросов |
+| `limits.burst` | любой | `1..1000`; Yandex `8`, Confluence `10` | Кратковременный burst |
+### Токены
+#### Yandex Wiki
+1. Создайте приложение в [Яндекс OAuth](https://oauth.yandex.ru/) и выдайте ему [права Wiki](https://yandex.ru/support/wiki/ru/api-ref/access) на чтение, а для destination — на запись.
+2. Получите OAuth-токен пользователя с доступом к нужным страницам. Для федеративного пользователя Yandex Cloud допустим IAM-токен.
+3. Найдите ID в **Yandex Tracker → Администрирование → Организации** и выберите `organization.type: yandex360` либо `cloud`.
+4. Запишите значения в Yandex-профиль; для IAM используйте `authType: iam` и Cloud Organization.
+#### Confluence Data Center
+1. Откройте **Avatar → Settings → Personal access tokens → Create token**; порядок действий описан в [документации Atlassian](https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html).
+2. Запишите PAT в профиль с `deployment: data-center` и `authType: pat`.
+3. Убедитесь, что пользователь может читать source и создавать страницы и attachments в destination.
+#### Confluence Cloud
+1. Создайте [Atlassian API token](https://id.atlassian.com/manage-profile/security/api-tokens).
+2. Используйте `deployment: cloud`, `authType: api-token`, `email` и `token`; аккаунту нужен доступ к исходному и целевому spaces.
+## CLI
 ### Команды
 | Команда | Назначение |
 | --- | --- |
-| `ywtc init [--workdir <path>] [--interactive]` | Создать шаблон либо настроить и проверить подключения в TTY wizard |
-| `ywtc doctor [options]` | Проверить workspace; с source и destination выполнить read-only preflight |
-| `ywtc migrate --interactive` | Выбрать параметры, выполнить dry-run и явно продолжить live-перенос в TTY wizard |
-| `ywtc migrate --source <locator> --destination <locator\|directory> [options]` | Неинтерактивно перенести или экспортировать выбранный граф страниц |
-| `ywtc reports list [--workdir <path>]` | Показать локальные отчёты от новых к старым |
-| `ywtc reports open [run-id\|last] [--workdir <path>]` | Открыть выбранный отчёт; `last` или отсутствие аргумента открывает последний корректный |
-| `ywtc update [--install] [--via npm\|brew]` | Проверить или установить обновление безопасным для текущего канала способом |
-| `ywtc --help`, `ywtc <command> --help` | Показать общую или командную справку |
-| `ywtc --version` | Показать версию |
+| `ywtc init [-i] [-w <path>]` | Создать workspace или настроить оба подключения в TTY-мастере |
+| `ywtc doctor [options]` | Проверить workspace; с source и destination — выполнить read-only preflight |
+| `ywtc migrate -i` | Выбрать параметры, выполнить dry-run и при допустимом результате явно перейти к live |
+| `ywtc migrate -s <locator> -d <locator\|directory> [options]` | Неинтерактивный перенос или экспорт |
+| `ywtc reports list [-w <path>]` | Показать локальные отчёты от новых к старым |
+| `ywtc reports open [run-id\|last] [-w <path>]` | Открыть выбранный или последний корректный отчёт |
+| `ywtc update [-i] [-c npm\|brew]` | Проверить или установить обновление безопасным для текущего канала способом |
 ### Опции
-| Полная опция | Short | Команды | Обязательность / значения | Назначение |
-| --- | --- | --- | --- | --- |
-| `--interactive` | `-i` | `init`, `migrate` | требует stdin/stdout TTY | Запустить обязательный мастер настройки или миграции |
-| `--workdir <path>` | `-w` | `init`, `doctor`, `migrate`, `reports` | config в CWD или `~/.ywtc` | Явно выбрать workspace; поддерживается `~/...` |
-| `--source <value>` | `-s` | `doctor`, `migrate` | обязательно для неинтерактивного `migrate`; в `doctor` вместе с destination | URL, page ID или Yandex slug |
-| `--destination <value>` | `-d` | `doctor`, `migrate` | обязательно для неинтерактивного `migrate`; в `doctor` вместе с source | Родительская страница или каталог экспорта |
-| `--source-profile <name>` | `-S` | `doctor`, `migrate` | при неоднозначном коротком locator | Профиль source из `connections` |
-| `--destination-profile <name>` | `-D` | `doctor`, `migrate` | при неоднозначном remote locator | Профиль destination; несовместим с файловым экспортом |
-| `--scope <mode>` | `-m` | `doctor`, `migrate` | `page`, `subtree` (default), `linked` | Граница выбора страниц |
-| `--source-status <status>` | `-t` | `doctor`, `migrate` | `all` (default) или `current` | Статус автоматически обнаруживаемых страниц; явно заданный root включается всегда |
-| `--comments` / `--no-comments` | `-C` / `-N` | `doctor`, `migrate` | комментарии включены по умолчанию | Архивировать page comments или полностью отключить их чтение и запись |
-| `--format <format>` | `-f` | `doctor`, `migrate` | `markdown` или `html` | Делает destination файловым каталогом |
-| `--archive` | `-a` | `migrate` | только с файловым destination | Дополнительно создать ZIP рядом с каталогом |
-| `--dry-run` | `-n` | `migrate` | default `false`; default-действие wizard | Discovery и план без записи в destination |
-| `--fresh` | `-F` | `migrate` | default `false` | Игнорировать mappings текущего state |
-| `--open-report` | `-o` | `migrate` | default `false` | Открыть итоговый HTML-отчёт; ошибка браузера не меняет результат миграции |
-| `--concurrency <n>` | `-j` | `migrate` | `1..64`; иначе config default | Общая параллельность; профильные лимиты сохраняются |
-| `--state <path>` | `-r` | `migrate` | внутри workspace | Явный state вместо автоматического |
-| `--install` | `-i` | `update` | default `false` | Установить найденное обновление |
-| `--via <channel>` | `-c` | `update` | `npm` или `brew` | Явно выбрать совместимый канал обновления |
-| `--help` | `-h` | CLI и команды | необязательно | Справка |
-| `--version` | `-v` | CLI | необязательно | Версия |
-Одинаковые short-алиасы относятся только к своей команде: например, `migrate -i` запускает wizard, а `update -i` устанавливает обновление. В интерактивном режиме переданные опции становятся редактируемыми начальными значениями; без него `source` и `destination` обязательны.
-### Локаторы
-- Yandex Wiki: полный URL, числовой page ID или slug, например `team/start`.
-- Confluence: числовой page ID, URL с `pageId=<id>` либо URL с `/pages/<id>` или `/content/<id>`.
-- Полный URL автоматически выбирает профиль по нормализованному base URL.
-- Короткий ID/slug выбирается автоматически только при единственном подходящем профиле; иначе нужен `--source-profile` или `--destination-profile`.
-- Каталог является файловой destination только вместе с `--format`.
-### Scope
-- `page` — только исходная страница.
-- `subtree` — страница и все доступные структурные потомки до последнего уровня; default. С `all` Yandex Wiki включает `actual` и `obsolete`, а с `current` — только `actual`. Confluence переносит страницы, доступные через hierarchy API; archived, trashed и historical versions могут не возвращаться этим API.
-- `linked` — детерминированный BFS по внутренним ссылкам и page/include references до фиксированной точки. Циклы завершаются безопасно, каждая страница обрабатывается один раз; внешние и недоступные ссылки не обходятся и попадают в отчёт.
-## Частые примеры
+| Полная / short | Команды | Значения и назначение |
+| --- | --- | --- |
+| `--interactive`, `-i` | `init`, `migrate` | TTY-мастер; в `migrate` переданные опции становятся редактируемыми defaults |
+| `--workdir`, `-w` | `init`, `doctor`, `migrate`, `reports` | Явный workspace; поддерживается `~/...` |
+| `--source`, `-s` | `doctor`, `migrate` | URL, page ID или Yandex slug; обязателен в неинтерактивном `migrate` |
+| `--destination`, `-d` | `doctor`, `migrate` | Родительская страница или каталог; обязателен в неинтерактивном `migrate` |
+| `--source-profile`, `-S` | `doctor`, `migrate` | Имя source-профиля при неоднозначном коротком locator |
+| `--destination-profile`, `-D` | `doctor`, `migrate` | Имя remote destination-профиля; запрещён для файлового экспорта |
+| `--scope`, `-m` | `doctor`, `migrate` | `page`, `subtree` (default), `linked` |
+| `--source-status`, `-t` | `doctor`, `migrate` | `all` (default) или `current`; root включается всегда |
+| `--comments`, `-C` / `--no-comments`, `-N` | `doctor`, `migrate` | Комментарии включены по умолчанию; `-N` исключает все comment API calls |
+| `--format`, `-f` | `doctor`, `migrate` | `markdown` или `html`; делает destination файловым |
+| `--archive`, `-a` | `migrate` | Дополнительный ZIP для файлового экспорта |
+| `--dry-run`, `-n` | `migrate` | Полный discovery/render без destination writes |
+| `--fresh`, `-F` | `migrate` | Игнорировать mappings; существующий live-state сохранить как backup |
+| `--open-report`, `-o` | `migrate` | Открыть итоговый HTML; ошибка opener не меняет outcome переноса |
+| `--concurrency`, `-j` | `migrate` | `1..64`; иначе `defaults.concurrency` |
+| `--state`, `-r` | `migrate` | Явный state path внутри workspace |
+| `--install`, `-i` | `update` | Установить найденное обновление |
+| `--via`, `-c` | `update` | `npm` или `brew` |
+| `--help`, `-h` / `--version`, `-v` | CLI | Справка / версия |
+Short-алиасы локальны для команды: `migrate -i` запускает мастер, `update -i` устанавливает обновление.
+### Locators и выбор страниц
+- Yandex Wiki: полный URL, числовой page ID или slug вида `team/start`.
+- Confluence: числовой page ID, URL с `pageId=<id>`, `/pages/<id>` или `/content/<id>`.
+- Полный URL выбирает профиль по нормализованному base URL. Для неоднозначного ID/slug укажите профиль явно.
+- Каталог считается destination только с `--format`.
+| Scope | Выбор |
+| --- | --- |
+| `page` | Только root |
+| `subtree` | Root и все доступные структурные descendants до последнего уровня; default |
+| `linked` | Детерминированный BFS по внутренним ссылкам и page/include references; циклы завершаются безопасно |
+`--source-status all` включает все доступные descendants: в Yandex Wiki — `actual` и `obsolete`; `current` оставляет только `actual/current`. Confluence зависит от hierarchy API и может не возвращать archived, trashed и historical versions.
+### Примеры
 ```bash
-# Перенести всё структурное поддерево
-ywtc migrate --source https://wiki.example.com/team/start \
-  --destination https://confluence.example.com/confluence/pages/viewpage.action?pageId=123
+# Перенести структурное поддерево
+ywtc migrate -s https://wiki.example.com/team/start \
+  -d https://confluence.example.com/confluence/pages/viewpage.action?pageId=123
-# Перенести граф рекурсивно связанных страниц
-ywtc migrate --source https://wiki.example.com/team/start \
-  --destination https://confluence.example.com/confluence/pages/viewpage.action?pageId=123 \
-  --scope linked
+# Перенести рекурсивно связанные страницы
+ywtc migrate -s https://wiki.example.com/team/start \
+  -d https://confluence.example.com/confluence/pages/viewpage.action?pageId=123 \
+  -m linked
-# Создать автономный HTML-экспорт и ZIP
-ywtc migrate --source https://wiki.example.com/team/start \
-  --destination ./exports/knowledge-base \
-  --format html --archive
+# Создать автономный HTML и ZIP
+ywtc migrate -s https://wiki.example.com/team/start \
+  -d ./exports/knowledge-base -f html -a
 # Открыть последний корректный отчёт
 ywtc reports open last
 ```
-Wizard проверяет только доступность API и авторизацию без страниц и внешних записей. `doctor` принимает те же endpoints, profiles, `scope`, `source-status` и `format`: без endpoints он проверяет workspace, конфигурацию и секреты, а с обоими endpoints выполняет page-specific read-only capability-preflight.
 ## Файловый экспорт
-Markdown создаёт `index.md`, `pages/`, `attachments/`, `.ywtc-export.json` и, при деградациях, `_source/`. HTML создаёт автономный адаптивный сайт с локальным `assets/site.css`; он работает через `file://` и на static hosting без CDN или внешнего runtime.
-При включённых комментариях каждая страница получает секцию `Комментарии` с раскрываемыми ветками. Связанные из комментариев файлы находятся в одном ZIP рядом с attachments страницы; `manifest.json` внутри ZIP связывает source comment ID, исходную ссылку, исходное и архивное имя, размер и SHA-256.
-Экспорт сначала строится в staging-каталоге. Существующий каталог заменяется только при строгом актуальном manifest с `tool: ywtc` и той же canonical identity, а прежний каталог сохраняется как timestamped backup. `--archive` оставляет каталог и создаёт новый ZIP, не перезаписывая существующий архив.
-## State
+Markdown создаёт `index.md`, `pages/`, `attachments/` и `.ywtc-export.json`. HTML создаёт автономный адаптивный сайт с локальным CSS, который работает через `file://` и на static hosting без CDN или внешнего runtime. `_source/` появляется только для страниц, которым нужен raw snapshot.
-По умолчанию state хранится в `<workdir>/.states/<automatic-id>.json`. ID строится из канонических профилей и ID source/destination, а для файлового экспорта также из формата; форма locator, `scope` и `source-status` на ID не влияют. State имеет единственный строгий актуальный формат без поля версии. Несоответствующий файл не преобразуется и не изменяется. Относительный `--state` разрешается внутри workspace, выход за его границы запрещён. Live-run получает exclusive lock этого state: параллельный процесс останавливается до записей в destination, а доказанно stale локальный lock восстанавливается автоматически.
+Внутренние ссылки и resources становятся относительными. Комментарии входят в страницу раскрываемыми ветками; явно связанные с ними файлы находятся в одном ZIP с `manifest.json`.
-### Повторные запуски
+Экспорт строится в соседнем staging-каталоге. Существующий каталог заменяется только при актуальном manifest с `tool: ywtc` и той же canonical identity; предыдущая версия сохраняется как timestamped backup. `--archive` оставляет каталог и создаёт новый ZIP, не перезаписывая существующий.
-- Одинаковые source и destination автоматически подхватывают один state независимо от формы URL/ID/slug.
-- Переключение `current → all` расширяет тот же state новыми страницами без дубликатов; обратное переключение не удаляет mappings вне текущего выбора.
-- Подтверждённая state-mapping означает, что source авторитетен: отличающийся body, title или parent mapped-страницы обновляется поверх актуальной destination-версии, а прежнее содержимое остаётся в истории провайдера.
-- Если ранее страница была создана под временно ближайшим выбранным предком, повторный запуск перемещает mapped-страницу под найденного родителя до обработки потомков независимо от изменений её body.
-- Уже сопоставленные страницы и вложения сверяются по ID, фактическому размеру и SHA-256; проверенный cache повторно не скачивается.
-- Неудачные mappings вложений автоматически получают безопасные уникальные имена и повторяются без `--fresh`.
-- Временный `404` подтверждённой destination-страницы повторяется с backoff; устойчиво пропавшая mapping восстанавливается под ожидаемым родителем с сохранением прежнего ID в state.
-- Страница с прежним неизменённым служебным placeholder ywtc автоматически получает полноценный source-derived контент.
-- Ошибка отдельного файла оставляет полный текст и source-ссылку, фиксирует `partial` и повторяет ресурс при следующем запуске.
-- Неизменённые архивы комментариев и ZIP проверяются и переиспользуются без дубликатов. Mapped Confluence-архив обновляется новой версией из source, а Yandex Wiki получает новую архивную ревизию, поскольку Public API не предоставляет update comments.
-- Удалённый mapped-комментарий создаётся заново. Исчезнувшие из доступного source API комментарии отмечаются `stale` и автоматически не удаляются.
-- Запуск с `--no-comments` не обращается к comment API и не удаляет ранее созданные архивы; следующий обычный запуск дополнит тот же state.
-- `conflict` используется только при доказанной неоднозначности immutable ownership/identity: несколько source mappings на один destination ID, несовпадение возвращённого immutable ID или несколько равноправных ownership-кандидатов. Версия, title, URL, slug, parent, fingerprint, HTTP `409`, слово `conflict` в сообщении и коллизия имени сами по себе конфликтом не являются.
-- `--fresh` игнорирует mappings; перед live-run прежний state сохраняется как backup, а destination может получить новые объекты.
-- Удалённые из source объекты автоматически не удаляются из destination.
+## State и повторные запуски
-При SIGINT/SIGTERM новые задачи не ставятся, активные безопасные операции завершаются, state и отчёт сохраняются. Коды выхода: `0` — completed; `1` — partial или verification failure; `2` — usage/config/preflight; `130`/`143` — остановка сигналом.
+State находится в `<workdir>/.states/<automatic-id>.json`. ID зависит от канонических профилей и page IDs, а для экспорта — ещё от формата; URL/ID/slug, `scope` и `source-status` его не меняют. Относительный `--state` разрешается только внутри workspace.
-## Отчёты
+- Повтор одинакового направления подхватывает mappings, cache и незавершённые операции без дубликатов.
+- Для доказанной mapping source авторитетен: body, title и parent обновляются поверх текущей destination-версии, а прежнее содержимое остаётся в истории. Unmapped и неоднозначно принадлежащие объекты не перезаписываются.
+- Неверная иерархия исправляется сверху вниз; временные `404` повторяются, пропавшая mapped-страница восстанавливается под ожидаемым родителем без удаления старого объекта.
+- Файлы согласуются по immutable ID, размеру и SHA-256; проверенный cache переиспользуется, занятые имена получают стабильный суффикс.
+- Комментарии и их ZIP проверяются и переиспользуются. Confluence-архив обновляется версией, Yandex Wiki получает новую ревизию; исчезнувший source-архив сохраняется как stale.
+- `current → all` расширяет тот же state; обратное переключение не удаляет прежние mappings. Удаление в source также не удаляет destination.
+- `--fresh` игнорирует mappings и сохраняет прежний state как backup; destination при этом может получить новые объекты.
-Каждый запуск создаёт `<workdir>/.states/reports/<run-id>/index.html` и очищенный `report.json`, затем печатает run ID, `file://` URL и команду повторного открытия. `--open-report` открывает отчёт сразу; `ywtc reports list` показывает историю, `ywtc reports open <run-id>` — выбранный запуск, а `ywtc reports open last` или `ywtc reports open` — последний корректный.
+Live-run использует exclusive lock; stale lock восстанавливается. При SIGINT/SIGTERM новые задачи не запускаются, безопасные активные операции завершаются, state и отчёт сохраняются. Коды выхода: `0` — completed, `1` — partial/verification failure, `2` — usage/config/preflight, `130`/`143` — сигнал.
-Автономный HTML-отчёт работает без сети. Компактный Mantine-интерфейс объединяет статус, progress, source/destination-сводку и ссылки на результат, state и `report.json`. Нулевые необязательные счётчики, пустые секции сводки и пустые вкладки деталей скрываются; обязательные totals, статусы и идентификаторы остаются видимыми.
+## Отчёты и статусы
-Ниже находится раскрытое дерево исходной иерархии, включая исключённые страницы; доступны поиск, фильтры проблем и прямые ссылки на source/destination. Строка страницы открывает только доступные вкладки файлов, комментариев, сравнения и проблем. Ошибки и зависимые `blocked` объекты подсвечиваются в дереве и объясняются в деталях. RU/EN и system/light/dark переключаются иконками; выбор сохраняется локально. Интерфейс адаптирован для мобильного экрана.
+Каждый запуск создаёт `<workdir>/.states/reports/<run-id>/index.html` и очищенный `report.json`, затем печатает URL и команду открытия. Используйте `--open-report`, `ywtc reports list` или `ywtc reports open [run-id|last]`; без selector `open` также выбирает последний корректный отчёт.
-HTML/JSON, итог терминала и `reports list` используют одинаковые счётчики. Известный source volume отделён от подтверждённых transferred bytes; неизвестные размеры отмечены явно. `report.json` не содержит содержимое страниц, тексты комментариев или preview HTML — они остаются только в локальном `index.html`.
+Автономный отчёт показывает только ненулевые показатели, канонические source/destination, исходную иерархию, исключённые страницы и проблемы. Дерево поддерживает поиск и фильтры; детали страницы содержат доступные files, comments, side-by-side comparison и диагностику. RU/EN и system/light/dark переключаются иконками. `report.json` не содержит body страниц, тексты комментариев или preview HTML.
-Качество преобразования учитывается отдельно: normalization — безопасная разница сериализации; adaptation — полное эквивалентное представление, например Grid → static table или колонки другой ширины; degradation — доказанная неполнота, влияющая на `partial`; preserved external reference — исходный внешний URL, который и должен остаться внешним. Normalization и adaptation не увеличивают warnings и не переводят запуск в `completed-with-warnings`.
+### Outcomes объектов
-### Статусы переноса
-Статусы страниц:
-| Статус | Смысл | Данные записаны | Что делать |
-|---|---|---:|---|
-| `complete` | Страница и связанные объекты записаны и проверены | Да | Ничего |
-| `partial` | Часть данных, managed-ресурсов, комментариев или значимой структуры отсутствует либо результат не проверен | Да | Посмотреть degradation в отчёте; повторить запуск для retryable-проблем |
-| `failed` | Операция страницы началась, но корректная запись или проверка не удалась | Возможно частично | Исправить root error и повторить ту же миграцию |
-| `blocked` | Страница не запускалась из-за недоступного failed/conflict родителя или другой зависимости | Нет в этом запуске | Исправить указанную upstream-ошибку и повторить запуск |
-| `conflict` | Immutable ownership/identity destination доказанно неоднозначна, в отчёте перечислены кандидаты | Нет автоматической перезаписи | Проверить candidate IDs и устранить неоднозначное сопоставление |
-| `planned` | Объект рассчитан в `--dry-run`; запись не выполнялась | Нет | Убрать `--dry-run` для переноса |
-| `not-started` | Live-run остановился до начала независимой операции | Нет | Повторить ту же миграцию |
-Статусы файлов:
+| Outcome | Объекты | Значение и действие |
+| --- | --- | --- |
+| `complete` | страницы, файлы, comment archives | Записано и проверено; действий не требуется |
+| `partial` | страницы, файлы, comment archives | Основное представление доступно, но часть данных отсутствует или не проверена; изучить degradation и повторить retryable-операцию |
+| `failed` | все | Операция началась, но корректная запись или проверка не получилась; исправить root error и повторить запуск |
+| `blocked` | страницы, файлы, comment archives | Операция не начиналась из-за недоступного parent/dependency; сначала исправить upstream failure/conflict |
+| `conflict` | mapped-объекты | Immutable ownership/identity неоднозначна; проверить candidate IDs. Обычная новая версия, ручное изменение, title collision или HTTP `409` конфликтом не считаются |
+| `planned` | все | Объект рассчитан в dry-run, записи не было; запустить live |
+| `not-started` | все | Live-run остановился до независимой операции; повторить запуск |
-| Статус | Смысл | Данные записаны | Что делать |
-|---|---|---:|---|
-| `complete` | Файл загружен и проверен | Да | Ничего |
-| `partial` | Файл доступен через сохранённый fallback, но нативная передача неполна | Частично | Проверить fallback и повторить retryable-операцию |
-| `failed` | Download, upload или verification файла выполнялся и завершился ошибкой | Возможно частично | Проверить причину и повторить запуск |
-| `blocked` | Файл не обрабатывался, потому что destination-страница недоступна | Нет в этом запуске | Сначала устранить указанную ошибку страницы |
-| `planned` | Файл только запланирован в `--dry-run` | Нет | Запустить без `--dry-run` |
-| `not-started` | Live-run прерван до начала обработки файла | Нет | Повторить ту же миграцию |
+### Качество преобразования
-`failed` означает неудавшуюся попытку самого объекта; `blocked` — сознательно не начатую операцию из-за upstream-зависимости. Поэтому зависимые блокировки показываются отдельно и не увеличивают число root errors.
+| Категория | Влияние |
+| --- | --- |
+| Normalization | Безопасная разница сериализации или нативный эквивалент; остаётся `complete` |
+| Adaptation | Другое представление с проверенной полнотой, например Grid → static table; остаётся `complete` |
+| Preserved external reference | Внешний URL сохранён как внешний и не требует копирования; остаётся `complete` |
+| Degradation | Данные или значимая структура отсутствуют либо полнота не доказана; даёт `partial` |
+| Warning | Требует внимания, но сам по себе не доказывает потерю |
+| Error | Неудавшаяся API/record/verification операция; итог зависит от сохранности полного body и объекта |
-Итоговый статус запуска: `completed`, `completed-with-warnings`, `partial`, `failed`, `cancelled` или `interrupted`. Provider-aware verification допускает безопасные различия сериализации и полные adaptations. Только потеря текста, ссылки, ячейки таблицы, кода, managed-изображения, вложения, комментария, anchor или невозможность доказать полноту ухудшает статус. Технический статус `skeleton-created` уже содержит source-derived bootstrap, а не progress-placeholder.
+Итог запуска: `completed`, `completed-with-warnings`, `partial`, `failed`, `cancelled` или `interrupted`. HTML, JSON, terminal summary и `reports list` используют одинаковые totals; зависимые `blocked` объекты не считаются отдельными root errors.
 ## Разработка
@@ -320,6 +265,6 @@ npm run workspace:init
 npm run check
 ```
-`npm run check` запускает проверку репозитория и секретов, production audit уровня high/critical, TypeScript, Biome, Knip, тесты, сборку, проверку npm-пакета и строгую OpenSpec-валидацию. Любое изменение проходит полный OpenSpec-цикл из [`AGENTS.md`](AGENTS.md).
+`npm run check` запускает release hygiene и security audit, TypeScript, Biome, Knip, Vitest, Playwright, сборку, package smoke-test и строгую OpenSpec-валидацию. Любое изменение проходит цикл из [`AGENTS.md`](AGENTS.md).
-Release Please рассчитывает SemVer из Conventional Commits. После merge release PR GitHub Actions проверяет релиз, публикует GitHub Release и npm-пакет через OIDC provenance, затем обновляет и проверяет Homebrew-формулу. Версии и changelog вручную не изменяются.
+Release Please рассчитывает SemVer из Conventional Commits. После merge release PR GitHub Actions публикует GitHub Release и npm-пакет с OIDC provenance, затем генерирует, устанавливает и тестирует Homebrew-формулу.