NPM Suite Console: своя консоль для линейки npm-пакетов
Идея
У меня набралась линейка из нескольких npm-пакетов под общим неймспейсом macrulez — не один проект, а целая группа небольших библиотек, которые живут своей жизнью: у каждой свой репозиторий на GitHub, свой package.json, свой собственный темп релизов. По отдельности с любой из них всё просто: открыл репозиторий, поправил код, поднял версию, опубликовал. Проблемы начинались не на уровне одного пакета, а на уровне линейки целиком.
Перед тем как куда-то сесть и поправить очередной пакет, я обычно хотел знать простую вещь: а что вообще происходит во всех пакетах одновременно? У какого локальная версия в package.json обогнала то, что лежит в npm, и значит пора публиковать? У какого описание и topics на GitHub разъехались с тем, что написано в самом package.json («About drift» — когда поменял описание в коде, а на странице репозитория всё ещё старый текст)? У какого пакета нет GitHub-релиза под текущую версию — версия в коде выросла, а тег и релиз на GitHub за ней не подтянулись? И отдельный, более тонкий случай: пакеты линейки иногда зависят друг от друга, и если один пакет давно не публиковался, другой может тащить в зависимостях его устаревшую версию — в обычном npm outdated это не видно, потому что технически зависимость разрешается, версия просто не самая свежая внутри собственной же линейки.
Раньше ответ на каждый из этих вопросов означал — открыть GitHub, открыть npmjs.com, сравнить руками, повторить для каждого пакета. С ростом числа пакетов в линейке это начало занимать больше времени, чем сама разработка: пять минут на проверку статуса перед тем, как десять секунд что-то поправить в коде.
Концепция, из которой выросла программа: package.json каждого пакета — единственный источник правды, и из него же выводятся остальные системы записи. Описание и topics в GitHub About, факт существования релиза, версия, опубликованная в npm — всё это производные значения, которые должны быть синхронизированы с тем, что написано в файле пакета, а не самостоятельные сущности, которые можно поправить в одном месте и забыть про остальные. Задача инструмента — в любой момент честно показать, где эта синхронизация разошлась, и дать восстановить её одним действием, а не заставлять помнить, какое поле где когда менялось.
Экраны приложения
Дашборд
Стартовый экран — сводка по всей линейке одним взглядом, без необходимости куда-либо кликать. Пока данные ещё не пришли при первом открытии — на месте контента крупный спиннер с подписью «Загрузка дашборда…», а не пустой экран и не моргающие нули.
Сверху, и только если есть, о чём предупредить, появляется блок алертов: ошибка последней загрузки статуса красным, и отдельно — два предупреждения жёлтым, если GitHub или npm не авторизованы, с прямой ссылкой на экран настроек и подсказкой выполнить gh auth login или npm login, если так привычнее. Если всё в порядке, блока просто нет — он не занимает место «на всякий случай».
Дальше — пять плиток метрик в одну строку, у каждой своя иконка слева (коробка, синхронизация, тег, облако с загрузкой, скачивание): количество найденных пакетов по настроенным путям, About в синхроне (дробь — сколько из скольких), число релизов под текущие версии (тоже дробь), сколько пакетов ждут публикации и суммарные загрузки npm за неделю по всей линейке. Любая плитка, где значение хуже идеального (не все About синхронны, не у всех есть релиз, есть что публиковать), подсвечивается отдельным предупреждающим цветом фона — не нужно вглядываться в цифры, достаточно увидеть, какая плитка «горит».
Под плитками — отдельная панель на всю ширину контента с графиком суммарных загрузок npm за последние 30 дней по всей линейке сразу, она появляется только когда данные по тренду действительно загрузились, без пустого графика-заглушки. Ниже — сетка из четырёх панелей. «Требуют внимания» — до шести пакетов, у которых что-то не синхронизировано, с тегами прямо в строке: жёлтый «ждёт publish», жёлтый «About drift», красный «нет релиза» — у одного пакета может быть сразу несколько тегов. «Недавно обновлялись» — пять пакетов, отсортированные по дате последнего git-коммита, с самой датой рядом. «Топ по загрузкам» — пять пакетов с наибольшим количеством загрузок за всё время, с разбивкой «всего / за неделю». «Последняя активность» — пять самых свежих фоновых задач с цветным статусом (зелёный успех, красный ошибка, синий «в процессе») и ссылкой «Смотреть все» на полный журнал. Любая ссылка на имя пакета в любой из этих панелей сразу ведёт на его карточку — дашборд работает и как сводка, и как навигационный хаб.
Технический штрих, который не виден напрямую, но влияет на ощущение: при первом открытии приложения данные могут прийти из кэша, который сервер уже отдал, но в фоне ещё обновляет. Через восемь секунд после первой загрузки дашборд тихо перезапрашивает данные ещё раз — если за это время кэш на сервере успел обновиться, цифры на экране досчитываются сами, без необходимости жать «Обновить» руками.
Пакеты
Главная рабочая таблица — все найденные пакеты в одном месте, с поиском, фильтрами и массовыми операциями. Верхняя строка инструментов — поле поиска по имени пакета (фильтрует список мгновенно, при наборе) и две кнопки массовой синхронизации, «Синхронизировать About» и «Синхронизировать релизы», которые одним кликом проходят по всей линейке сразу, без необходимости заходить в каждый пакет по отдельности.
Под ней — ряд фильтр-чипов по статусу: About drift, ждёт publish, нет релиза, дрейф зависимостей. Каждый чип можно включить или выключить кликом, активные залиты цветом своей категории (жёлтый, синий, красный, фиолетовый), неактивные — просто с цветной обводкой. Фильтры комбинируются через «или»: если включено несколько, в таблице остаются пакеты, подходящие хотя бы под один из выбранных критериев.
Сама таблица: чекбокс выбора в первой колонке, имя пакета как ссылка, версия (локальная и опубликованная в npm бок о бок, чтобы сразу видеть, кто кого обгоняет), статус About (тег «in sync» зелёным или «drift» жёлтым), статус релиза (галочка и номер версии, если релиз есть, иначе красный тег «missing»), список устаревших внутренних зависимостей — если пакет тянет старую версию другого пакета линейки macrulez, имена показаны жёлтым тегом с подсказкой по наведению, иначе просто прочерк. Дальше — колонка загрузок: мини-график (sparkline) за 30 дней, если данные уже подгрузились, серый скелетон-плейсхолдер на месте графика пока запрос ещё летит, и текстом «всего N · за нед. M» рядом. Последняя колонка с данными — дата последнего коммита, и в самом конце — контекстная кнопка «Publish (dry-run)» (видна только если пакет реально ждёт публикации) и «Открыть» для перехода на карточку.
Отметив несколько строк чекбоксами, над таблицей появляется панель массовых действий: счётчик выбранных пакетов, кнопка-сплит «Bump patch (выбранные)» с выпадающим списком minor/major у стрелочки рядом, кнопка «Publish dry-run (выбранные)» и «Снять выделение». Настоящая публикация в массовые действия осознанно не вошла — слишком рискованно публиковать сразу несколько пакетов в npm одним кликом без построчного подтверждения по каждому. Реальный publish остался поштучным действием на странице конкретного пакета, с отдельным диалогом подтверждения.
Карточка пакета
Если «Пакеты» — это обзор, то карточка отдельного пакета — это место, где реально что-то делается, и самый насыщенный экран приложения, собранный из последовательности панелей.
Первая — «Действия»: dry-run публикации (безопасный прогон без реальной отправки в registry), настоящий publish — кнопка красная, и клик сразу открывает диалог подтверждения с текстом «Опубликовать имя в npm? Это необратимое внешнее действие», bump версии через сплит-кнопку (patch по умолчанию, minor/major в выпадающем списке, тоже с подтверждением и явным упоминанием, что это изменит package.json), и отдельно — синхронизация About и синхронизация релиза.
Если по пакету накопилась история загрузок, следующая панель — график за последние 90 дней с суммой за период в шапке панели; пока данные ещё грузятся, на этом месте — панель с надписью «Загрузка статистики…» и инлайн-спиннером, а не пропавший кусок интерфейса.
«Метаданные» — самая насыщенная по функциям панель. Сверху — три колонки: версия (с тегом, опубликована она уже в npm или ещё нет — зелёным «npm in sync» либо жёлтым с фактической версией в registry), лицензия, и статистика загрузок «всего / за неделю». Ниже — описание, keywords и website для GitHub About, причём всё это можно редактировать прямо тут: иконка карандаша в шапке панели переключает блок в режим правки — текстовое поле для описания, теги-чипсы для keywords (можно добавлять и убирать по одному), отдельное поле для website. По кнопке «Сохранить и синхронизировать» оба запроса (метаданные пакета и website) уходят параллельно, а сразу после успеха автоматически запускается задача синхронизации с GitHub About — никакого отдельного шага руками. Чуть ниже, если есть устаревшие внутренние зависимости, отдельный список: имя зависимости, что заявлено в package.json и какая версия на самом деле актуальна у пакета-источника. Внизу панели — кнопки-ссылки на репозиторий и домашнюю страницу пакета, если она указана.
Дальше — таблица «GitHub About vs package.json» построчно по трём полям: description, website, topics. В каждой строке — то, что сейчас реально стоит на GitHub, и тег статуса: зелёное «ok», если совпадает с тем, что выводится из package.json, жёлтое «drift», если разошлось. Если репозиторий недоступен (нет токена, нет доступа), вместо таблицы — текстовая заглушка об этом, без падения экрана.
Панель «Релизы»: если под текущую версию релиза ещё нет, сверху кнопка «Создать релиз vX.Y.Z» — по клику запрашивается у GitHub предзаполненный текст релиза, сгенерированный из коммитов и PR с прошлого тега, и открывается диалог с этим текстом в редактируемом textarea на 14 строк — можно дополнить или переписать перед публикацией, кнопка «Опубликовать релиз» создаёт его с уже отредактированным текстом. Ниже — список существующих релизов, каждый как ссылка-кнопка с тегом версии и датой публикации.
«Безопасность» — кнопка «Проверить (npm audit)» запускает реальный npm audit по зависимостям пакета и показывает результат: цветные теги по каждому уровню серьёзности, которые реально нашлись (critical и high — красным, moderate — жёлтым, low — синим, остальное — серым), и если уязвимостей вообще нет — отдельный зелёный тег «уязвимостей не найдено» вместо пустой таблицы. Если что-то найдено — таблица с именем пакета-зависимости, тегом severity и ссылкой на advisory, если она есть в данных аудита.
Дальше — список последних коммитов репозитория (хэш, сообщение, автор, дата), и в самом низу — свёрнутая по умолчанию панель с README, отрендеренным из markdown в HTML — разворачивается по клику на заголовок панели, чтобы не растягивать страницу пакета содержимым документации каждый раз при открытии.
Активность
Журнал всех фоновых задач, которые когда-либо выполнялись через интерфейс или CLI — publish (и dry-run, и настоящий), bump, синхронизации About и релизов, поштучные и массовые. В каждой строке — иконка по типу действия (облако со стрелкой для publish, стрелка вверх для bump, синхронизация для sync-about, тег для релизов), затрагиваемый пакет, цветной статус (зелёный успех, красный ошибка, синий «выполняется»), время начала и завершения. Кнопка «Лог» у любой строки открывает диалог с полным текстовым выводом конкретного запуска — тот же поток, что шёл бы в реальном времени во время выполнения, только постфактум и целиком.
Настройки
Экран конфигурации, разбитый на отдельные панели по смыслу. «Расположение пакетов» — два независимых списка: каталоги для рекурсивного сканирования и отдельные одиночные пути к пакетам, которые могут лежать вообще где угодно на диске, причём каждый одиночный пакет можно временно выключить чекбоксом без удаления из списка — он просто не будет участвовать в дашборде и таблице, пока не включишь обратно. Добавление и каталога, и одиночного пакета идёт через системный диалог выбора папки, а не через ручной ввод пути.
«Публикация в npm» — поле для токена с явным указанием, зачем он нужен: подставляется через временный .npmrc на время самой команды публикации и нигде не сохраняется в открытом виде, что снимает необходимость в npm login и связанные с ним протухающие сессии; рядом тег, есть ли токен сейчас вообще.
«GitHub-аккаунты» — список аккаунтов с токенами; можно завести несколько (например, личный и рабочий) и переключать активный одним кликом — у активного зелёная кнопка «Активен», у остальных серая «Сделать активным». Тут же выбор провайдера операций: «Авто» (REST по токену, если он задан, иначе gh CLI), «REST + токен» (только HTTP API, не зависит от установленного gh) или «gh CLI» (через сам gh). Отдельным предупреждением честно сказано, что токены сейчас лежат в обычном JSON-файле конфигурации, а не в системном хранилище секретов — это в списке будущих доработок.
«Приложение» — кнопка создания ярлыка на рабочем столе для лёгкого launcher-режима без Electron (поднимает локальный сервер, если он ещё не запущен, и открывает интерфейс в обычном окне браузера), чекбокс системных уведомлений о завершении задач и блок «О приложении» с номером версии и ссылкой на репозиторий.
Онбординг
Шестишаговый сценарий первого запуска, который показывается только до того, как базовая конфигурация заведена, и больше никогда не всплывает сам — дальше всё то же самое редактируется в обычных настройках. Шаг 1 — диагностика окружения: установлен ли Node, git, gh CLI и сам npm, авторизован ли он, с явной оговоркой, что gh не обязателен — без него всё работает через REST по токену. Шаг 2 — добавление GitHub-аккаунта с токеном, с немедленной проверкой авторизации и читаемым статусом. Шаг 3 — npm-токен для публикации, тоже с моментальной проверкой через npm whoami. Шаг 4 — расположение пакетов: можно сначала просканировать каталог и увидеть, сколько пакетов реально нашлось, прежде чем добавлять его в постоянный список. Шаг 5 — выбор провайдера операций с GitHub, тот же выбор, что и в настройках. Шаг 6 — финальный экран с кнопкой «Открыть дашборд». Любой шаг можно пропустить кнопкой «Далее» без заполнения — приложение работает и без части настроек, просто соответствующие действия (публикация, операции с About) будут недоступны, пока токен не появится.
Помощь
Встроенная справка прямо в приложении, а не отдельный файл в репозитории, который нужно отдельно искать: слева навигация по темам, справа — содержимое конкретной страницы, отрендеренное из markdown. Сделано так, чтобы объяснение того, откуда брать GitHub- и npm-токены или что означает конкретный статус на дашборде, было ровно там же, где сама программа, а не в соседнем окне браузера.
Сквозные элементы интерфейса
Несколько вещей видны на любом экране, а не только на конкретной странице. Боковая панель слева — навигация по пяти разделам и переключатель темы в подвале: светлая, тёмная или «как в системе», причём системный режим живо реагирует на переключение темы в самой ОС, без необходимости перезапускать приложение. Глобальная шапка сверху — заголовок текущего экрана (для карточки пакета — его имя, и левее кнопка «назад к пакетам» со стрелкой), статус авторизации в GitHub и npm в виде иконок с подсказкой по наведению, и кнопка «Обновить» там, где обновление имеет смысл.
Отдельно — плавающая консоль задач, которая всплывает снизу экрана в момент запуска любого действия (publish, bump, синхронизация, что угодно) и стримит вывод команды построчно в реальном времени по WebSocket, не дожидаясь завершения и не требуя перехода на экран «Активность» — видно прямо там, где кликнул кнопку. Если включены системные уведомления, по завершении задачи (успешному или с ошибкой) дополнительно показывается обычное системное уведомление ОС — стандартный браузерный Web Notification API, который одинаково работает и в окне Electron, и при запуске через лёгкий ярлык в обычном браузере, поэтому отдельный код под Electron для этого не понадобился.
Резюме
В итоге получился инструмент, который закрывает исходную задачу полностью: вместо того чтобы вручную сверять GitHub, npm и package.json по каждому пакету линейки macrulez, я открываю один дашборд и сразу вижу, что разошлось. Большинство рутинных действий — синхронизация About, проверка релизов, dry-run перед публикацией, проверка зависимостей на устаревшие внутренние версии — теперь занимают один клик вместо похода по нескольким сайтам и сравнения вручную. Там, где раньше я держал в голове, у какого пакета пора бампать версию и у какого разошлось описание на GitHub, теперь просто открываю «Пакеты» и вижу список с тегами прямо в строке.
Помимо самих экранов, в основу заложено несколько вещей, которые не видны напрямую, но определяют, насколько инструменту можно доверять: общий слой бизнес-логики между CLI и UI, чтобы поведение никогда не расходилось; кэширование статусов с фоновым обновлением, чтобы не дёргать GitHub и npm на каждый клик, но и не показывать заведомо устаревшие данные дольше необходимого; повторные попытки на нестабильных запросах к npm registry, чтобы единичный сетевой сбой не превращался в неверный «0» на несколько минут; и безопасный режим для desktop-сборки, где локальный API защищён собственным токеном, чтобы другой процесс на той же машине не мог дёргать публикацию пакетов через локальный порт.
Отдельно стоит сказать про внешний вид. На данный момент дизайн интерфейса — чисто технический: стандартная тема компонентной библиотеки PrimeVue, плотная компоновка, минимум визуальной иерархии сверх того, что нужно для читаемости таблиц и панелей. Это осознанный порядок работы — сначала довести до конца функциональность и архитектуру (общий core для CLI и сервера, кэширование, потоковые логи фоновых задач, безопасный режим с токеном для desktop-сборки), и только после этого заниматься внешним видом. Так что дальше в планах — отдельный проход по UI: более продуманная визуальная иерархия, своя цветовая схема вместо дефолтной темы компонентной библиотеки, и в целом более «дожатый» вид у экранов, которые сейчас выглядят как добротный рабочий прототип.