CLI, сборка и дистрибуция

На этой странице перечислены команды CLI для плагинов bb, описаны типы установки, отслеживание версий, проверка совместимости, откаты, маркетплейсы, публикация и расположение бинарника bb при десктопной установке.

Справочник bb plugin *

Команда	Флаги	What it does
plugin search <query>	--json	ищет по всему, что есть в сторе (из поставки bb + bb-community + добавленные маркетплейсы); колонка Marketplace указывает источник
plugin list	--json	установленные плагины и их статус, а также сервисы, расписания, тайминги обработчиков и добавленные команды bb
plugin source <id>	--json	разрешённый источник и его история: подкаталог, semver-диапазон + префикс тега + разрешённый тег, диапазоны engines, время установки, целостность, история активаций
plugin install <source>	--subdirectory · --plugin · --tag-prefix · --yes · --json	запись в каталоге по имени или <entry>@<marketplace>, URL Git-репозитория, локальный путь, builtin:<name>, git:<url>[@<ref|semver>], npm:<name>@<version>
plugin outdated	--json	проверяет совместимые обновления; также сообщает о новых релизах, которые заблокированы из-за несовместимости
plugin update [id]	--all · --yes	применяет только совместимые кандидаты; запрашивает такое же подтверждение на полное доверие, как при установке; без TTY и флага --yes завершается ошибкой
plugin new <name>	нет	генерирует шаблон плагина в ./bb-plugin-<name>; принимает @scope/bb-plugin-<name>
plugin types [path]	--check	синхронизирует поверхность SDK с запущенным bb: обновляет пин SDK в devDependency и type-only devDeps для shim-пакетов; --check ничего не записывает
plugin migrate [path]	--yes	переводит плагин с вендорной папки types/ на npm-пакет: фиксирует devDependency, удаляет маппинг путей в tsconfig и вендорные декларации, переписывает импорты @bb/plugin-sdk; печатает план и запрашивает подтверждение
plugin build [path]	нет	собирает в dist/: серверный бандл всегда, клиентский — если есть bb.app, самодостаточный хост — если есть bb.host; запущенный сервер не требуется
plugin dev [path]	нет	watch-режим: пересобирает фронтенд (без минификации), хост и бандлы provider-bridge, затем перезагружает плагин при каждом изменении
plugin reload [id]	--json	перезагружает один плагин или все; выходит с кодом 1, если перезагруженный плагин не поднялся
plugin enable / disable <id>	--json	включает / выключает плагин (код выгружается)
plugin config <id> [action] [key] [value]	--json	показывает настройки, либо config <id> set <key> <value> / unset <key>; булевы значения и числа приводятся к объявленным типам
plugin token <id>	--rotate · --json	печатает HTTP-токен плагина (для маршрутов с auth: "token")
plugin run <id> [args...]	passThroughOptions	явная форма вызова bb <command>, исключающая конфликты имён
plugin logs <id>	-n/--lines (100) · -f/--follow	логи плагина (вывод bb.log); режим follow опрашивает раз в секунду
plugin remove <id> (alias uninstall)	--json · скрытый --yes	удаляет плагин и его настройки, секреты и расписания; управляемые файлы git/npm удаляются, источники из локальных путей остаются на диске
plugin rpc list [plugin-id]	--method · --json	обнаруживаемые RPC-методы запущенных плагинов
plugin rpc inspect <plugin-id> [method]	--json	описание регистрации и методов плюс JSON Schema для входа/выхода
plugin rpc call <plugin-id> <method>	--input-file · --json	вызывает метод с серверной валидацией схемы; если файл не передан, отправляется JSON null (файл позволяет не светить секреты в argv)

Рядом: bb marketplace add|list|refresh|remove; bb theme list|set|show (показывает палитры плагинов как plugin:<plugin-id>:<id>); bb settings keyboard (команды плагинов переназначаются как plugin:<plugin-id>/<command-id>); и bb diagnostics cli-errors (статистика неудачных вызовов bb; записывает путь команды и код ошибки, но никогда — значения аргументов; отключается через BB_CLI_ERROR_LOG=0).

Типы установки и отслеживание

bb plugin install ./bb-plugin-notes                            # path
bb plugin install path:. --plugin notes                        # path + a collection entry
bb plugin install npm:bb-plugin-notes@^1.0.0                   # npm: range / dist-tag / exact version
bb plugin install https://github.com/acme/bb-plugin-notes      # bare URL → the default branch
bb plugin install git:https://github.com/acme/x.git@main       # an explicit branch (tracking)
bb plugin install git:https://github.com/acme/x.git@^1.2.0     # semver over vX.Y.Z tags
bb plugin install builtin:<name>                               # a local copy from the application bundle
bb plugin install <entry-id>@<marketplace>                     # a marketplace entry

Отслеживание против пина

• npm: если версия не указана, отслеживаются совместимые стабильные релизы; диапазоны и dist-теги отслеживают обновления, точные версии ставят пин.
• git: если ссылка не указана, отслеживается ветка по умолчанию; явные ветки отслеживают обновления, теги и коммиты ставят пин.
• Semver-диапазон git разрешается по тегам vX.Y.Z, выбирая максимальное совпадение, при этом пререлизы исключаются, если они не указаны в диапазоне явно. Флаг --tag-prefix позволяет задавать теги для каждого плагина в монорепозитории.
• bb записывает выбранный тег вместе с его коммитом и отказывается разрешать этот тег заново, если он сдвинулся (урок go.sum). Фиксы публикуйте как новые версии, а не перевешиванием тегов.
• Спецификатор без префикса, читающийся как диапазон, разрешается по тегам только если нет ветки и тега с таким буквальным именем. Если есть и то, и другое, установка падает, и вам нужно явно указать @semver:<range> или @ref:<name>.

Поведение сборки в зависимости от типа

• path: загружает TypeScript-файл bb.server напрямую, без сборки. bb.app собирается во время установки из уже установленных зависимостей. Установка локального пути для id, который уже установлен из другого локального пути, перемещает плагин и сохраняет его настройки, секреты и расписания.
• git: сначала запускает npm install --omit=dev --omit=optional --ignore-scripts, сохраняя node_modules (сборка не может заинлайнить файлы данных, читаемые в рантайме), затем собирает объявленные app/server/host и валидирует метаданные. Требуется установленный git; npm и Node в PATH не нужны, так как bb поставляется с npm.
• npm: должен поставлять готовую и валидную папку dist/, содержащую app.js + app.meta.json, если объявлен bb.app, и бандл хоста с его метаданными, если объявлен bb.host.
• builtin: копируется из бандла приложения, без обращений к сети.
• Переустановка уже установленного управляемого плагина отклоняется; используйте bb plugin update. Изменение закреплённого источника git:/npm: требует команды remove (с потерей настроек) и чистой установки.

Проверка совместимости, откаты, маркетплейсы

• Обновления выбирают только совместимые кандидаты, удовлетворяющие engines.bb и engines.bbPluginSdk. Более новые несовместимые релизы отображаются как заблокированные, а не применяются. Для dev-сборок отмечается, что engines.bb не проверялся.
• Откат: неудачная активация восстанавливает предыдущий снимок состояния и записывает ошибку для пользователя.

• Плагин из локального пути никогда не удаляется для изменения: редактируйте его на месте и выполняйте bb plugin reload <id>, или запустите bb plugin install path:<new dir>. Оба варианта сохраняют конфигурацию.
• Удаление маркетплейса оставляет все его плагины работать как прямые установки с полным исходным намерением и точным разрешением, поэтому outdated/update продолжают работать.
• Маркетплейс — это один файл marketplace.json. Он перечисляет плагины с брендингом стора и npm/git-источником, и никогда не хостит код. Схема строгая: неизвестное поле бракует весь документ, и продолжает обслуживаться последний валидный каталог. Имена bb-official и bb-community зарезервированы, их нельзя ни добавить, ни удалить. В листинге не указывается совместимость: engines читаются из собственного package.json плагина.
• Перед установкой из любого маркетплейса, кроме bb-community, bb разрешает и показывает реальный источник (включая точный тег релиза и коммит, на который указывает диапазон), а также сам маркетплейс и автора записи. Установка прерывается, если листинг или разрешённый коммит изменились после подтверждения.
• bb-official описывает каждый плагин из поставки bb сгенерированным документом v2, указывающим на локальный путь, и никогда не обращается к сети. bb-community перечитывается при запуске и каждые два часа с https://getbb.app/marketplace/v2/marketplace.json (с одним откатом к v1 при 404; переопределяется через BB_MARKETPLACE_URL, который читается только при запуске). Счётчики установок берутся из stats.json рядом с курируемым манифестом и «undercount by construction»: это только те установки, о которых bb знает.

Публикация и релизы версий

При установке из path и git плагин собирается на месте. В npm-пакете должна быть уже собранная и валидная папка dist/: dist/app.js + dist/app.meta.json, если объявлен bb.app, и бандл хоста с его метаданными, если объявлен bb.host. Управляемая установка проверяет метаданные и отклоняет артефакт, чьи pluginId/pluginVersion не совпадают с манифестом, или чей sdkMajor отличается от текущего.

# before publishing
bb plugin types          # re-pin the SDK and type-only devDeps to the current bb
bb plugin types --check  # the same in CI: writes nothing, fails on a mismatch
bb plugin build          # dist/server.js (+ app, + host) and their *.meta.json
npm publish              # the package MUST contain dist/ — the scaffold's .gitignore hides it
                         # from git only, but it has to reach the npm package

Шаблон плагина создаёт .gitignore ровно из двух строк (dist/ и node_modules/) и не создаёт поле files в package.json. Нигде в репозитории не описано (не проверено), что именно нужно перечислить в files (или в .npmignore), чтобы папка dist/ попала в тарбол; проверяйте свой пакет с помощью npm pack --dry-run перед публикацией.

Версионирование против engines

• engines.bb — это диапазон версий приложения; engines.bbPluginSdk читается как нижняя граница, а не потолок. Шаблон пишет >=major.minor текущего bb и точную версию SDK.
• Обновления выбирают только совместимые кандидаты. Более новый релиз, не проходящий проверку engines, отображается в bb plugin outdated как заблокированный, а не применяется. Управляемая установка дополнительно отклоняет плагин, чей SDK новее хостового или имеет другую мажорную версию.
• Публикуйте фиксы как новые версии: bb записывает выбранный тег вместе с его коммитом и отказывается разрешать тег, который сдвинулся.
• Для git-источника semver-диапазон разрешается по тегам vX.Y.Z; в монорепозитории несколько плагинов разделяются флагом --tag-prefix.

Тексты для стора и сабмит в bb-community

• Два текста, оба обязательны для стора: bb.description — одно предложение до ~140 символов для карточки Browse и первого абзаца страницы; и PLUGIN_OVERVIEW.md рядом с package.json — подробное описание в секциях ниже.
• Правила CI для overview: UTF-8, жёсткий лимит в 4000 символов (цельтесь в 700–1800); разрешены только заголовки, абзацы, выделения текста, зачёркивания, инлайн-код, блоки кода, цитаты, списки, разделители и ссылки; никакого сырого HTML, картинок, таблиц, сносок или чек-листов; все ссылки — абсолютные https; секции уровня ##; не начинайте с # и не повторяйте короткое описание первым предложением.
• Сабмит — это отдельный скилл, plugins/bb-guide/skills/submit-a-plugin/: он копирует PLUGIN_OVERVIEW.md в репозиторий маркетплейса как overview/<plugin-id>.md и ссылается на него через поле "overview". Попадание в bb-community — это решение авторов релизов bb, а не часть вашего процесса публикации.
• Ваш собственный маркетплейс — это один файл marketplace.json, добавляемый через bb marketplace add по https URL, из git: или path:. Он не хостит код, а установки проходят через тот же пайплайн.

Бинарник bb при десктопной установке

Портативное решение — переменная окружения BB_CLI, содержащая абсолютный путь к исполняемому файлу под управлением демона: «Prefer bare bb on PATH. When BB_CLI is set, official bb entrypoints re-exec to that absolute binary; you can also invoke "$BB_CLI" directly». Лаунчер задаёт BB_CLI: join(args.context.daemonBundleDir, "bb"), а для пакетной установки daemonBundleDir = <bb-app package root>/host-daemon/dist.

Путь вида bb.app/Contents/Resources/app.asar.unpacked/node_modules/bb-app/host-daemon/dist/bb нигде в репозитории не встречается буквально. Он собран из трёх отдельных фактов и поэтому отмечен как не проверено; используйте $BB_CLI.