# Добавьте свой инструмент в WireCat (/ru/docs/build-list-tool)

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

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

## Кто может добавить инструмент [#кто-может-добавить-инструмент]

Инструменты WireCat читают сообщения, почту и файлы людей. Поэтому мы не берем инструменты у всех подряд. Инструменты
приходят от одобренных авторов, которые подают заявку или получают приглашение, и для каждого нужно доказательство,
что наши проверки на нем прошли, и одобрение человека из команды в конце. Прием заявок пока не открыт. Чтобы спросить,
откройте issue в [cli-docs](https://github.com/WireCatLabs/cli-docs/issues).

## Что нужно инструменту [#что-нужно-инструменту]

- **Он собран из шаблона или отвечает тому же стандарту.** Начните с [Создайте свой CLI](/llms.mdx/docs/ru/build-create-cli/content.md).
  Все проверки «Done when» из
  [чек-листа нового CLI](https://github.com/WireCatLabs/cli-base/blob/main/docs/standards/new-cli.md#done-when)
  проходят в 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`, где они перечислены. Сайт копирует страницы оттуда.

## Попросите о включении в список [#попросите-о-включении-в-список]

1. **Выпустите версию, которую хотите показать.** Поставьте тег `vX.Y.Z`, и `release.yml` опубликует ее.
2. **Откройте pull request в [cli-docs](https://github.com/WireCatLabs/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`:

```json
{
  "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.

## Что мы проверяем [#что-мы-проверяем]

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

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

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

**Человек из команды одобряет**, следуя
[списку проверки инструментов сообщества](https://github.com/WireCatLabs/cli-docs/blob/main/docs/REVIEWING.md#community-tools).
Пока запланированных проверок нет, он проверяет это вручную:

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

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

## После слияния [#после-слияния]

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

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

## Обновления [#обновления]

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

## Снятие из списка [#снятие-из-списка]

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

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

## Попробуйте до включения в список [#попробуйте-до-включения-в-список]

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

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

Desktop читает манифест инструмента, `contracts/wirecat.json`, из пакета в npm, поэтому инструмент должен его
содержать ([Создайте свой CLI](/llms.mdx/docs/ru/build-create-cli/content.md)). Инструмент из закрытого репозитория можно добавить так, но
нельзя включить в список. Все экраны и что значит каждый отказ показывает страница [Добавить свой инструмент](/llms.mdx/docs/ru/desktop/own-tools/content.md).

## Что дальше [#что-дальше]

1. [Создайте свой CLI](/llms.mdx/docs/ru/build-create-cli/content.md), чтобы начать инструмент из шаблона.
2. [Вход и соответствие стандартам](/llms.mdx/docs/ru/build-sign-in/content.md) о правилах, которым следует каждый инструмент.