Веб-интерфейс

polyrepo ui запускает небольшой веб-сервер на вашей машине и открывает страницу в браузере. Страница запускает те же команды, что и терминал, но с формами, таблицами, отчётами и диалогами вместо флагов и вопросов: сразу видно все пакеты и что с каждым не так, пакеты выбираются галочками, запуск идёт в живую, на вопросы команды отвечаешь в диалоге, а каждое изменение репозиториев нужно подтвердить заранее. Ничего не уходит с вашей машины.

polyrepo ui

polyrepo ui is running at http://127.0.0.1:52144/?token=5f3c…
Press Ctrl+C to stop.

Браузер сам откроется по этому адресу. В меню слева пять разделов: Пакеты, Команды, Релиз, Запуски и Настройки.

Запуск

Команду можно запускать откуда угодно. Она читает тот же polyrepo.config.json, что и остальные команды (другой файл выбирается через --config <path> перед командой), так что папка, настроенная через polyrepo setup, работает как есть. При первом запуске, если пакетов не найдено, раздел «Пакеты» предложит выбрать папку и покажет, какие инструменты (git, npm, gh) найдены.

По умолчанию сервер берёт свободный порт (--port <n> задаёт свой) и слушает 127.0.0.1, так что достучаться до него можно только с этой машины. --no-open только печатает адрес. Ctrl+C останавливает сервер и все ещё идущие запуски.

Интерфейс входит в пакет, ничего дополнительно ставить не нужно. Команда, запущенная со страницы, работает ровно так же, как в терминале и по тем же правилам: чтение идёт параллельно, всё, что меняет репозиторий, — по одному репозиторию за раз.

Безопасность по умолчанию

• Только эта машина. Сервер слушает 127.0.0.1. Адрес, который печатается при старте, содержит одноразовый токен: открытие адреса ставит cookie, и каждый следующий запрос обязан её нести. Запрос с чужим заголовком Host или Origin отклоняется.
• Изменения требуют подтверждения. Команду, которая меняет репозитории, или опцию, которая их меняет (например, очистку веток в doctor), нельзя запустить без явного подтверждения в запросе. Сначала страница показывает сводку: команду, пакеты и опции.
• Предпросмотр в один клик. У каждой команды с пробным запуском в подтверждении есть Preview (dry run). Завершённый предпросмотр предлагает Run for real…, который снова открывает форму с теми же настройками.
• Опасные опции предупреждают. Опция, которая отбрасывает работу, например сброс локальных изменений, выделена красным, показывает предупреждение сразу после отметки и повторяется в подтверждении.
• Секреты не сохраняются. Одноразовый пароль, введённый для npm publish, уходит в команду и никогда не пишется в историю запусков; в напечатанной команде он тоже скрыт.

Пакеты

Обзор всего, что находит конфиг. Check packages запускает list (галочка Quick пропускает сетевые проверки) и показывает его таблицу. Отчёт сохраняется, поэтому страница показывает последний с его возрастом и через четверть часа помечает как устаревший.

• Needs attention считает пакеты с проблемой; каждый счётчик — фильтр, по которому можно кликнуть: локальные изменения, не на основной ветке, нет в npm или отстаёт от него, отличается от origin, устаревшие зависимости.
• Монорепозитории — блоки. Репозиторий с несколькими пакетами — это один цветной блок со своим заголовком, а одиночные репозитории собраны вместе в одном блоке выше. Заголовок сворачивает блок и выбирает сразу все его пакеты; цвета берутся из диапазона, который выбирается в Настройках.
• Статусы чипами. Ветка, состояние git, релиз, состояние в npm и рассинхронизация зависимостей показаны цветными чипами, так что проблема заметна в длинном списке.
• Сортировка, фильтр и выбор. Клик по колонке сортирует её, текст фильтрует, пакеты отмечаются галочками, а Select all и Unselect выбирают и снимают сразу всё. При включённом фильтре Select all берёт только подходящие строки.
• Действия над выбранным. Bump, Publish, Tag, Sync deps, Switch branch и Run command открывают форму этой команды с уже отмеченными пакетами. Release… открывает мастер.

Страница показывает возраст отчёта, а не живое состояние, намеренно: полная проверка ходит в сеть по каждому пакету, поэтому она запускается по кнопке. После команды, меняющей репозитории, в фоне обновляются только затронутые ею пакеты (см. «Пакеты остаются актуальными»).

Команды

У каждой команды CLI есть форма: Packages, Outdated dependencies, Security audit, Open pull requests и Doctor в группе Inspect; Switch to default branch, Sync local dependency ranges, Commit changes, Run a command и Clone missing repos в группе Sync; Bump version, Publish to npm, Tag current version и Create releases в группе Release. Карточки окрашены по группам и показывают, какие команды что-то меняют.

В форме сначала идут опции команды (те же, что флаги, с теми же значениями по умолчанию), а ниже пакеты. Там, где команда принимает пакеты, список везде одинаковый:

• Сгруппирован как обзор. Одиночные репозитории в одном блоке, каждый монорепозиторий в своём цветном блоке с заголовком, который выбирает весь блок.
• Полезные колонки. Текущая ветка (жёлтая, если это не master и не main), есть ли в репозитории локальные изменения и версия.
• Фильтры. Текстовый фильтр, Only with local changes и Hide private.
• Обновление. Кнопка Refresh над списком заново читает ветки, состояние git и версии без перезагрузки страницы; отмеченные пакеты остаются отмеченными.
• Где пакет на npm. В форме Publish и в мастере релиза версия делится на Local и On npm. Номер на npm зелёный, если совпадает с локальным, жёлтый и жирный, если локальная версия новее (можно публиковать), и красный, если на npm версия новее; пакет, которого на npm ещё нет, показывает not published, а у приватного колонка пустая. Фильтр Only ahead of npm оставляет только пакеты, которые стоит публиковать. Версии запрашиваются у npm при открытии формы (для длинного списка это несколько секунд, остальным списком можно пользоваться сразу) и заново после каждого запуска, так что устаревшими не остаются.
• Подсвеченные строки. Строка окрашена красным, если в репозитории есть локальные изменения, жёлтым, если локальная версия новее, чем на npm, и акцентным цветом, если пакета на npm нет вообще. Цветная полоска у левого края остаётся и у отмеченной строки. У пакета с локальными изменениями, который к тому же новее, видны обе полоски.
• Сохранённые наборы. Save as set запоминает текущий выбор под именем, а Saved sets… применяет сохранённый. Наборами можно управлять в Настройках.

Если оставить список пустым, команда сама спросит пакеты в диалоге, точно как в терминале; для отчёта, который только читает, пустой список означает все пакеты.

Кнопка Review and run закреплена внизу страницы, так что она под рукой при любой длине списка. Она проверяет форму (незаполненное обязательное поле отмечается прямо у поля) и показывает сводку, описанную в разделе «Безопасность по умолчанию». Всё, что команда спрашивает во время работы (какие пакеты переключить, продолжать ли), приходит диалогом на странице запуска; закрытие диалога отменяет запуск.

Одноразовый пароль

В форме Publish и в мастере релиза есть поле для одноразового пароля npm-аккаунта с двухфакторной аутентификацией. Код действует около тридцати секунд, так что вводите его прямо перед запуском. Интерфейс никогда не выполняет npm login: войдите один раз в терминале.

Вход по ссылке, ключу или passkey

Ссылку для входа, ключ безопасности или passkey npm запрашивает только в настоящем терминале; запущенный из интерфейса, он этого не умеет, и публикация останавливается с ошибкой про одноразовый пароль. Когда публикация падает так, отчёт предлагает Publish in a terminal: в папке пакета открывается окно терминала с npm publish (pnpm publish для участника pnpm-workspace) и тем же dist-tag, что был у запуска, так что npm может показать ссылку, открыть браузер и принять ключ или код. Завершите вход там, затем нажмите Run again или откройте Publish to npm: колонка On npm заново спросит реестр. Одновременно открывается не больше пяти окон, по одному на пакет.

В Windows и macOS используется системный терминал; в Linux первый найденный из x-terminal-emulator, gnome-terminal, konsole, xfce4-terminal и xterm. Если открыть терминал не удалось, команда копируется, и интерфейс об этом говорит: запустите её сами. Другой путь — гранулярный токен доступа с правом публикации и обходом двухфакторной проверки, который хранится в вашей конфигурации npm: тогда публикация вообще не требует кода.

Мастер релиза

Четыре шага для релиза, который проходит через ветку, pull request, merge и тег, а при желании и публикацию. Мастер запускает bump с вашими ответами.

• Packages. Тот же список, что и везде. Если открыть мастер из раздела «Пакеты» с выбранными пакетами, этот шаг пропускается.
• Version. Patch, minor, major, prerelease (с идентификатором вроде alpha) или точная версия, для которой нужен ровно один пакет. Для каждого вида показан пример, как меняется версия.
• Options. Ждать CI-проверки каждого pull request'а перед merge и публиковать в npm сразу после тега.
• Review. Сводка, затем Preview (dry run), который проходит все шаги, ничего не пуша, не мёрджа и не тегируя, или Release.

Запуски

Каждая запущенная команда становится запуском: страницей с отчётом и логом и записью в истории.

Отчёт

Первое, что показывает завершённый запуск. Пока команда работает, показывается лог.

• Счётчики. Сколько проверок прошло, сколько предупреждений и ошибок, а у команд, работающих по пакетам, ещё и сколько пакетов.
• Needs attention. Все предупреждения и ошибки одним списком, у каждой указан раздел, откуда она. Клик открывает лог на этой строке. Пакет, названный в сообщении, становится ссылкой на него в разделе «Пакеты», а сообщение, которого не было в предыдущем запуске той же команды, помечается как new; число проблем, которые ушли, тоже отмечено.
• Разделы и карточки. Проверка из нескольких частей, как doctor, — это по карточке на часть: часть, где всё прошло, свёрнута, а с проблемами — раскрыта, и её строки подсвечены. Команда, работающая по пакетам, как bump или exec, даёт по карточке на пакет, с выводом команды, свёрнутым под ней (короткий вывод раскрыт).
• Таблицы. Таблицы команд, которые только читают, с той же сортировкой, фильтром и блоками монорепозиториев, что в обзоре. В отчётах outdated и audit по цветному блоку на пакет, с числом находок по критичности в заголовке и одной заметной кнопкой, Update dependencies… или Fix vulnerabilities…, которая после подтверждения запускает npm update или npm audit fix для этого пакета. См. «Что делать с найденным».

Лог

Полный вывод с цветами, сгруппированный по секции на пакет. По нему можно искать, показывать только секции с проблемами, сворачивать секции, держать последнюю строку в поле зрения кнопкой Follow, копировать и сохранять весь лог текстом. Строки команд, в том числе выполняемые за вас, показаны со знаком $, а пробный запуск их помечает.

Запуск, который ждёт ответа, отмечен в меню и в заголовке вкладки, завершённый может прислать системное уведомление (включается в Настройках), а Cancel run останавливает запуск и всё, что он успел запустить.

История

Список запусков, новые сверху, по дням, с командой, результатом в паре слов (2 packages · 1 failed), временем и длительностью. Фильтруйте по тексту или показывайте только идущие, с проблемами или завершённые без них. Keep last 20 удаляет более старые завершённые запуски. Run again у запуска открывает его форму с теми же пакетами и опциями.

Запуск, который шёл в момент остановки интерфейса, показывается как неудачный, с пометкой, а не остаётся «идущим» навсегда.

Что делать с найденным

Отчёт не останавливается на проблеме: рядом с каждой страница предлагает, что с ней можно сделать, так что гадать не приходится.

Аудит безопасности

В отчёте аудита по блоку на пакет, окрашенному по диапазону из Настроек, с числом уязвимостей по критичности и кнопкой Fix vulnerabilities…. Кнопка просит подтверждение, в котором названы точная команда (npm audit fix) и пакет, и сразу запускает её: форму заполнять не нужно.

Если npm audit fix починил всё, что можно безопасно, но оставил то, для чего нужно обновление с breaking change, запуск показывается как Partly done, а не как неудача, и карточка говорит, что осталось:

• What is left группирует оставшиеся уязвимости по обновлению, которое их исправит (например, tinypool и @vitest/mocker оба закрываются vitest@5.0.3), с критичностью, затронутым диапазоном и ссылкой на каждый advisory.
• Update only this… после подтверждения ставит только это одно обновление, а не всё подряд.
• Preview --force запускает npm audit fix --force --dry-run и показывает, что изменилось бы, ничего не меняя.
• Production only запускает npm audit --omit=dev, чтобы увидеть, какие находки доходят до пользователей пакета, а какие живут только в инструментах разработки.
• Apply --force… применяет все обновления с breaking change после подтверждения, которое предупреждает об этом красным.

Изменения, которые сделал запуск

После команды, меняющей зависимости (npm install, npm update, npm audit fix и подобные), в карточке пакета показано, что изменилось в package.json и lock-файлах: число добавленных и удалённых строк и изменение package.json в виде диффа. Сам по себе ничего не коммитится.

• Commit… открывает диалог коммита (ниже).
• Discard… после подтверждения возвращает файлы к последнему коммиту. Установленные пакеты в node_modules не затрагиваются; чтобы они снова совпадали, выполните npm ci.
• Run tests сразу запускает npm test в пакете.

Диалог коммита читает правила ветки, на которой вы находитесь, до того как вы выберете. На feature-ветке коммит ложится туда. На основной ветке он показывает, принимает ли хостинг прямые коммиты, и рекомендует маршрут: новая ветка и pull/merge request, когда нужно ревью или правила прочитать не удалось, иначе прямой коммит. Это можно переопределить; прямой коммит, который хостинг отклонил, переносится в ветку автоматически. Тот же сценарий — команда polyrepo commit, а запущенный запуск заканчивается ссылкой на pull request.

Что делать дальше

• После проблемы. Под каждым предупреждением или ошибкой отчёт предлагает следующие шаги для этой ситуации. Для пропущенного бампа из-за грязного дерева: закоммитить или откатить изменения манифеста, показать, что изменилось, отложить всё в stash, запустить бамп снова. Для отклонённой публикации: опубликовать в терминале, проверить вход в npm, опубликовать снова с одноразовым паролем, скопировать npm login. То же для отсутствующего git remote, всё ещё открытого pull request'а, отсутствующего тега перед релизом, ветки не на основной и истёкшего входа. Всё остальное, что падает, предлагает прочитать лог вокруг этой строки и запустить снова.
• После успеха. Завершённый бамп предлагает опубликовать и создать релиз; тег предлагает релиз; публикация предлагает релиз; коммит, который открыл pull request, предлагает открыть его, обновить основную ветку после слияния и поднять версию.
• Когда запуск не завершился. Отменённый запуск или тот, что неожиданно остановился, предлагает запустить снова, прочитать лог и проверить окружение через doctor. Запуск, который завершился, но ничего не сделал, например бамп, пропустивший все пакеты, помечается Needs attention, а не Done.
• Когда сервер пропал. Если polyrepo ui остановили, страница говорит об этом и предлагает перезагрузить её, когда вы запустите его снова; запуски и настройки сохраняются.

Пакеты остаются актуальными

Когда команда, меняющая репозитории, завершается, страница в фоне обновляет только затронутые ею пакеты, так что таблица Packages показывает их новую ветку, версию и состояние git без полной проверки. Пока строки обновляются, они пульсируют. Если затронутые пакеты определить не удалось, таблица сообщает, что данные могли устареть, и предлагает обновить.

Настройки

• Roots, Packages, GitLab hosts. Три списка конфига, правятся на месте. Выбор папки обходит ваш диск и отмечает репозитории. Save записывает polyrepo.config.json, Revert отбрасывает правку. Блок Found packages ниже обновляется по мере ввода, так что сразу видно, что находят настройки.
• Monorepo colors. Два цвета, и каждый монорепозиторий получает оттенок из диапазона между ними по месту в алфавитном списке, поэтому у одного репозитория на всех экранах один и тот же цвет. Предпросмотр показывает оттенки; Reset возвращает диапазон по умолчанию.
• Signed in. Выполнен ли вход в gh, glab и npm, под кем, и команда, которую нужно выполнить, если нет.
• Saved sets. Наборы пакетов, сохранённые из форм, с кнопкой удаления.
• Notifications. Разрешает системные уведомления о запусках, которые завершились, пока вы в другом окне.
• Tools. Версии Node.js, git, npm, pnpm, gh и glab, найденные на этой машине.

Диапазон цветов и сохранённые наборы не входят в конфиг: они лежат рядом с историей запусков.

Командная палитра

Ctrl+K или поле поиска в меню открывает палитру. Введите текст, чтобы найти страницу, команду, один из последних запусков или пакет; Enter открывает найденное, а пакет приводит к обзору с фильтром по нему.

Где что хранится

• ~/.polyrepo/runs/ — история: на каждый запуск небольшой файл с настройками и результатом и второй с полным логом. Хранится около сотни запусков, самые старые удаляются. POLYREPO_HOME переносит ~/.polyrepo в другое место.
• ~/.polyrepo/ui.json — сохранённые наборы и диапазон цветов.
• polyrepo.config.json — как и раньше; «Настройки» — просто ещё один способ его править.

Опции

--port <n>

Порт, на котором слушать. По умолчанию 0 — выбрать свободный.

--host <address>

Адрес, на котором слушать. По умолчанию 127.0.0.1 оставляет интерфейс на этой машине. Любое другое значение делает его доступным из сети по обычному HTTP, под защитой одного лишь токена: не трогайте, если не знаете, зачем это нужно.

--no-open

Только напечатать адрес и не открывать браузер.

--token <value>

Использовать этот токен доступа вместо случайного. Для разработки.

Проблемы и коды выхода

• Порт занят: Port 4000 is already in use — pick another with --port, or leave it out., код выхода 1.
• Порт не является целым числом от 0 до 65535: код выхода 2.
• Любая другая ошибка запуска печатается как Could not start the interface: …, код выхода 1.
• Остановка по Ctrl+C — обычный выход, код 0.
• Если страница больше не достаёт до сервера (его остановили), запустите его снова и откройте напечатанный адрес.
• Если страница сообщает, что интерфейс не собран, выполните npm run build:ui в папке polyrepo-cli; обычная установка его уже содержит.