Добавьте свой инструмент в WireCat

Вы сделали инструмент командной строки и хотите, чтобы его находили рядом с инструментами WireCat. Эта страница для авторов вне WireCatLabs. Она показывает, что нужно вашему инструменту, как попросить о включении в список, что мы проверяем и что происходит после слияния. Инструмент из списка появляется на wirecat.dev в группе «Инструменты сообщества», а в WireCat Desktop у тех, кто включил инструменты сообщества.

Список не делает ваш инструмент частью WireCat. У него остаются ваше название, ваше пространство имен npm и ваш репозиторий. Вы и дальше сами его делаете и выпускаете.

Кто может добавить инструментCopy Anchor Link

Инструменты WireCat читают сообщения, почту и файлы людей. Поэтому мы не берем инструменты у всех подряд. Инструменты приходят от одобренных авторов, которые подают заявку или получают приглашение, и для каждого нужно доказательство, что наши проверки на нем прошли, и одобрение человека из команды в конце. Прием заявок пока не открыт. Чтобы спросить, откройте issue в cli-docs.

Что нужно инструментуCopy Anchor Link

• Он собран из шаблона или отвечает тому же стандарту. Начните с Создайте свой CLI. Все проверки «Done when» из чек-листа нового CLI проходят в CI вашего инструмента.
• Каждая команда называет профиль. Профиль это имя одного из ваших аккаунтов, например personal. Инструмент никогда не выбирает аккаунт сам, а без профиля выдает ошибку со списком вариантов. Это касается каждой команды, примера, справки и страницы.
• Его репозиторий публичный. Для пакета из приватного репозитория npm не делает запись provenance, и мы не можем проверить код, который не видим. Инструмент из приватного репозитория можно добавить только на своем компьютере, как непроверенный.
• Он публикуется в npm из GitHub Actions через trusted publishing. Релиз запускается из release.yml в репозитории самого инструмента, на ветке main. WireCat Desktop проверяет npm provenance каждого релиза, то есть подписанную запись о том, где npm собрал пакет. Приложение отказывается ставить релиз, если запись не указывает на этот workflow в вашем репозитории. Шаблон настраивает это за вас.
• В планах: публикация через наш workflow релиза. Ваш release.yml будет вызывать закрепленную версию workflow WireCatLabs, который запускает наши проверки стандартов и потом публикует пакет. Тогда запись provenance называет наш workflow тем, что собрал пакет, и любой видит, что наши проверки на этом релизе прошли.
• У него свое название. Публикуйте в своем пространстве имен npm, например @example/acme-cli. @wirecat и название «WireCat» остаются нашими. Не берите имя, которое WireCat оставил за своими инструментами, например tg, max или mail.
• У него есть тег релиза и страницы. Тег vX.Y.Z, совпадающий с версией в npm, и на этом теге папка docs с вашими страницами и meta.json, где они перечислены. Сайт копирует страницы оттуда.

Попросите о включении в списокCopy Anchor Link

1. Выпустите версию, которую хотите показать. Поставьте тег vX.Y.Z, и release.yml опубликует ее.
2. Откройте pull request в cli-docs. Добавьте инструмент в tools.json с "community": true. Добавьте его имя и в content/docs/meta.json, meta.ru.json и meta.es.json.
3. Добавьте переводы, если их нет. Сайт на английском, русском и испанском. Страницы на двух других языках кладутся в translations/<name>/ в cli-docs, а pnpm docs:translation accept их записывает.
4. Приложите доказательства в pull request. Зеленый прогон CI на коммите с тегом и результат проверки свежим агентом, которую описывает чек-лист нового CLI.

Вот полная запись для инструмента acme:

{
  "name": "acme",
  "displayName": "Acme Notes",
  "repo": "example/acme-cli",
  "package": "@example/acme-cli",
  "lang": "en",
  "summary": {
    "en": "Your Acme notes on your computer, searchable offline.",
    "ru": "Ваши заметки Acme на вашем компьютере, с поиском без сети.",
    "es": "Tus notas de Acme en tu ordenador, con búsqueda sin conexión."
  },
  "docsRef": "v1.0.0",
  "community": true,
  "desktop": {
    "tagline": "Acme notes, searchable with your WireCat data",
    "bin": "acme",
    "profiles": { "args": ["profile", "list", "--json", "--no-record"], "shape": "items" },
    "doctor": ["{profile}", "doctor", "--json", "--record"],
    "runs": null,
    "search": null,
    "setup": ["{profile}", "setup"],
    "signIn": { "gives": "your Acme notes", "asks": "an Acme API token", "guide": "https://example.com/acme/token" },
    "skill": null,
    "mcp": null,
    "mcpServer": null,
    "tasks": null,
    "sync": null,
    "storeInfo": null,
    "storeTables": null,
    "storeTableSizes": null,
    "storeCheck": null,
    "storeBackup": null,
    "storeBackupEncrypted": null,
    "storage": { "app": "acme-cli", "env": "ACME" },
    "settings": null
  }
}

Поля:

• name это команда, которую набирают люди. Для приложения это от 2 до 16 строчных латинских букв.
• repo это owner/name на GitHub, вне WireCatLabs. package это имя в npm с пространством имен.
• lang это язык ваших страниц. summary это одна строка на каждом из трех языков.
• docsRef это тег релиза, с которого сайт копирует ваши страницы.
• desktop это то, что нужно WireCat Desktop, чтобы установить, проверить и подключить ваш инструмент. Без него инструмент будет только на сайте. tagline не длиннее 55 символов. bin это программа, которую ставит npm. storage это имя папки и префикс переменных окружения, которые ваш инструмент передает в resolvePaths из cli-base. Пишите null для команды, которой у инструмента нет.
• В каждом списке только простые слова команды. Буквы, цифры и ._:=,/+@-, не больше двух дефисов в начале и места для подстановки вроде {profile}. Без пробелов, кавычек и знаков оболочки.

Запись сообщества не может задавать partOf, commandPrefix, memory, taskBoard, bot, storeReset, storeResetPreview, configRepair и signIn.command. Они только для инструментов самого WireCat.

Что мы проверяемCopy Anchor Link

Проверки идут по порядку. Сначала автоматические, а последним одобряет человек.

Автоматически, в pull request:

• Уже есть: тесты в cli-docs запускают те же правила записи, что и приложение, так что плохая запись desktop не пройдет pull request.
• В планах: provenance релиза называет ваш репозиторий, а когда он появится, и наш workflow релиза.
• В планах: наши проверки стандартов запускаются заново на исходниках с вашего тега релиза.
• В планах: пакет из npm проверяется на секреты и вредоносный код.
• В планах: свежий агент проверяет инструмент в CI, получив только наш справочник и ваш репозиторий.

Человек из команды одобряет, следуя списку проверки инструментов сообщества. Пока запланированных проверок нет, он проверяет это вручную:

1. Чек-лист нового CLI зеленый в вашем CI, на коммите с тегом.
2. Проверка свежим агентом не нашла открытых пробелов.
3. Каждая команда, пример, справка и страница называют профиль.
4. Ничто не использует @wirecat и название «WireCat».
5. На релизе с тегом команды doctor и setup из записи работают как написано для нового профиля, и каждая другая команда из записи существует.
6. Папка данных из storage принадлежит только вашему инструменту.

Ревью проверяет, как инструмент собран и выпущен. Оно не проверяет все, что инструмент делает.

После слиянияCopy Anchor Link

• Сайт показывает его в группе «Инструменты сообщества», со страницами с тега docsRef.
• Список для приложения пересобирается. При каждом обновлении сайта собирается и подписывается список инструментов сообщества для WireCat Desktop. Сайт обновляется при каждом слиянии и раз в день.
• Пользователи приложения видят его, только если сами захотели. Инструмент появляется, когда человек в настройках включает «Включить инструменты сообщества» и перезапускает приложение. У него значок Сообщество, а до установки подпись «Сделано <owner>, не WireCat. Приложение проверяет, где npm собрал пакет, но не что он делает.»
• Каждая установка проверяется. Перед установкой приложение проверяет, что npm собрал этот релиз из release.yml вашего репозитория на main.

Сайт собирает и подписывает список для приложения, и WireCat Desktop читает его, когда включено Включить инструменты сообщества.

ОбновленияCopy Anchor Link

• Новые версии. Как новые версии проверяются и доходят до пользователей, сейчас продумывается.
• Страницы на сайте берутся с тега docsRef. Ежедневная проверка открывает issue в cli-docs, когда выходит новый релиз. Pull request, который переносит docsRef на новый тег, обновляет ваши страницы после ревью. Его можно открыть и самому.
• Изменения записи desktop, например новая команда, идут через pull request и то же ревью.

Снятие из спискаCopy Anchor Link

Мы снимаем инструмент, когда он нарушает правила выше или когда об этом просит автор. Запись уходит из tools.json, и следующее обновление сайта публикует список без нее.

• На сайте инструмент пропадает из группы «Инструменты сообщества».
• В приложении инструмент больше не предлагается, начиная со следующего запуска после получения нового списка. Приложение никогда не удаляет копию, которую человек установил.
• В планах: приложение показывает снятый, но установленный инструмент как «Больше нет в списке», с кнопкой удаления.

Попробуйте до включения в списокCopy Anchor Link

Свой инструмент можно добавить в WireCat Desktop до любой проверки. Тогда у него метка Не проверен.

1. В настройках включите Разрешить инструменты, которые WireCat не проверял и подтвердите предупреждение кнопкой Разрешить.
2. На странице «Инструменты» нажмите Добавить свой инструмент, вверху рядом с Проверить снова. Введите имя пакета в npm и нажмите Проверить пакет. WireCat только читает npm: пока ничего не устанавливается.
3. Экран проверки показывает издателя, репозиторий, версию, где npm его собрал и что он запрашивает. Нажмите Добавить, затем Установить и запустить во втором вопросе.

Desktop читает манифест инструмента, contracts/wirecat.json, из пакета в npm, поэтому инструмент должен его содержать (Создайте свой CLI). Инструмент из закрытого репозитория можно добавить так, но нельзя включить в список. Все экраны и что значит каждый отказ показывает страница Добавить свой инструмент.

Что дальшеCopy Anchor Link

1. Создайте свой CLI, чтобы начать инструмент из шаблона.
2. Вход и соответствие стандартам о правилах, которым следует каждый инструмент.