# Спека `.vibe/commands.json` — команды проекта

> Скопируйте этот файл целиком своей LLM и попросите собрать `.vibe/commands.json` для вашего проекта:
> «вот спека, вот мой проект — сделай команды для сборки, тестов и запуска».
> Всё, что нужно для валидного файла, — здесь; читать исходники VibeIDE и выходить в интернет не нужно.

## Что это

Команды проекта — рутинные консольные команды, которые запускаются кликом, а не набираются руками.
Файл `.vibe/commands.json` лежит в репозитории, поэтому у коллег команды появляются сами.

Где их видно:
- Меню **«Команды»** в заголовке окна, левее иконки мозга: закреплённые команды, запуск, закрепить, править, удалить
- Выбор из списка всех команд: команда `vibeide.commands.runFromPalette`, она же кнопка «Запустить» в настройках команд
- Горячие клавиши `Ctrl+Shift+Alt+1…9` — первые девять закреплённых по порядку

Команда — не агент: к модели она не обращается, а запускает процесс в терминале.

## Формат файла

JSON; комментарии `//` и поля, начинающиеся с `_comment`, допустимы и игнорируются.

```jsonc
{
  "vibeVersion": "1.0.0",   // обязательно, любая непустая строка
  "commands": [ /* объекты команд, см. ниже */ ]
}
```

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

## Поля команды

| Поле | Обязательно | Тип | Что значит |
|---|---|---|---|
| `id` | да | строка | Латиница в нижнем регистре, цифры, дефис; начинается с буквы или цифры; до 64 символов; уникален в файле |
| `name` | да | строка | Подпись в меню |
| `command` | да | строка | Программа или первая часть строки запуска: `npm`, `./gradlew`, `docker` |
| `args` | нет | массив строк | Аргументы по одному элементу: `["run", "build"]` |
| `description` | нет | строка | Подсказка |
| `cwd` | нет | строка | Папка запуска; относительный путь считается от корня проекта (первой папки рабочей области), абсолютный — как есть; без поля — корень проекта. Выход за пределы проекта через `..` отклоняется |
| `env` | нет | объект строка→строка | Переменные окружения процесса |
| `terminal` | нет | `integrated` / `background` / `external` | `integrated` (по умолчанию) — встроенный терминал на переднем плане; `background` — терминал в панели, не выходя вперёд; `external` — отдельное окно терминала системы |
| `pinned` | нет | булево | `true` — команда в меню «Команды» и в горячих клавишах |
| `order` | нет | число | Место во всех списках, по возрастанию; без поля — в конце, затем по `name` |
| `color` | нет | строка | **Имя цвета темы**, например `terminal.ansiBlue`, `terminal.ansiGreen`, `charts.red`: полоса-акцент в меню. Не HEX: имя цвета темы переживает переключение светлой и тёмной темы |
| `icon` | нет | строка | Имя значка codicon, например `tools`, `play`, `beaker` |
| `confirm` | нет | булево | `true` — спрашивать подтверждение при **каждом** запуске (для деплоя, миграций) |
| `singleton` | нет | булево | `true` — не запускать второй экземпляр, пока первый работает |
| `shell` | нет | булево | `true` — разрешить в `args` метасимволы оболочки (`|`, `;`, `&&`, `>`, `$( )`). Без него такой аргумент — причина отказа в запуске |
| `workflowId` | нет | строка | Вместо команды запустить сценарий из `.vibe/workflows` с этим id |

## Подстановки

В `command`, `args`, `cwd` и `env` работают:
- `${env:NAME}` — переменная окружения системы
- `${secret:KEY}` — секрет из хранилища секретов IDE (ключ `vibeide.commands.secret.KEY`); значение не попадает ни в журнал аудита, ни в индексаторы

Не нашлось значения подстановки — запуск не происходит, и IDE называет, чего не хватило.
Пароли и токены прямо в файле писать нельзя: IDE предупреждает о похожих на секрет значениях.

## Безопасность

- **Первый запуск и любая правка команды требуют явного разрешения.** Разрешение хранится в хранилище IDE (профиль),
  по папке проекта, а не в репозитории: файл внутри репозитория приезжает с тем же пулл-реквестом, что и команда,
  и одобрил бы её сам. Привязано к отпечатку команды — SHA-256 от `id`, программы, аргументов, папки, окружения и `shell`;
  изменили любое из этого — спросит снова. Прежний файл `.vibe/commands.trust.json` не читается и не переносится
- **В папке без доверия** (Workspace Trust) спрашивает при каждом запуске и ничего не запоминает
- Перед запуском команда проверяется: невидимые символы и символы смены направления текста, управляющие символы,
  метасимволы оболочки без `shell: true`, выход `cwd` за проект, ограничения `.vibe/constraints.json`.
  Нашлось — запуск отклоняется с объяснением
- Запуск и завершение пишутся в журнал аудита, секреты — замаскированными

## Где ещё лежат команды

Кроме `.vibe/commands.json` проекта, команды читаются из файлов, перечисленных в настройке `vibeide.commands.globalPaths`
(тот же формат). При совпадении `id` побеждает команда проекта.
Импорт из `.vscode/tasks.json` — команда `vibeide.commands.importTasksJson` (кнопка в настройках команд): показывает, что добавится, и пишет в `.vibe/commands.json` после подтверждения.

## Пример

```jsonc
{
  "vibeVersion": "1.0.0",
  "commands": [
    {
      "id": "build",
      "name": "Сборка",
      "command": "npm",
      "args": ["run", "build"],
      "pinned": true,
      "order": 1,
      "color": "terminal.ansiBlue",
      "icon": "tools",
      "singleton": true
    },
    {
      "id": "test",
      "name": "Тесты",
      "command": "npm",
      "args": ["test"],
      "pinned": true,
      "order": 2,
      "color": "terminal.ansiGreen",
      "icon": "beaker"
    },
    {
      "id": "dev-server",
      "name": "Дев-сервер",
      "command": "npm",
      "args": ["run", "dev"],
      "terminal": "background",
      "singleton": true,
      "pinned": true,
      "order": 3
    },
    {
      "id": "deploy-stage",
      "name": "Деплой на стенд",
      "command": "./scripts/deploy.sh",
      "args": ["stage"],
      "env": { "DEPLOY_TOKEN": "${secret:DEPLOY_TOKEN}" },
      "confirm": true,
      "color": "charts.red"
    },
    {
      "id": "logs",
      "name": "Логи с фильтром",
      "command": "docker",
      "args": ["logs", "app", "2>&1", "|", "grep", "ERROR"],
      "shell": true
    }
  ]
}
```

Проверка, что файл верный: закреплённые команды появились в меню «Команды», а все — в списке `vibeide.commands.runFromPalette`.
Не появились — смотрите журнал вывода VibeIDE: там причина, например `commands[2]:id-invalid`.