# PlugOnce for Raycast

Инструкция для уже полученной локальной копии расширения. Исходники пока доступны в локальном проекте `Extensions/Raycast`; публичный архив не опубликован.

Локальное расширение связывает настоящее избранное PlugOnce, браузер устройства и очередь передач с Raycast. Автор манифеста — `mr.foxset`. Команды работают через существующий Unix socket Agent Bridge; файлы передаёт нативный PlugOnce.

## Команды

| Команда | Возможности |
| --- | --- |
| Open Favorites | Избранное PlugOnce, открытие папки в приложении, отправка файлов сюда, просмотр и поиск, копирование пути/UUID, создание Quicklink |
| Send Files to Switch | Выделение Finder или выбор файлов и папок, избранное либо явное хранилище и путь, предварительный план, последовательная передача |
| Transfer Translation | Проверка одного пакета LayeredFS и отправка `atmosphere` в корень DBI SD Card |
| Browse and Search Device | Просмотр хранилищ и папок, страницы по 200 объектов, поиск во вложенных папках, открытие результата в PlugOnce |
| Transfer Operations | Операции локальной автоматизации, состояние, байты, скорость, ETA, результат проверки и отмена |
| Device Status | Подключение, хранилища, ёмкость и свободное место |

В **Open Favorites** выберите папку и нажмите Enter. Действие **Send Files Here** отправляет выбранные источники именно в эту папку. **Create Quicklink for This Favorite** создаёт ссылку на UUID избранного; назначьте ей alias или hotkey в настройках Raycast. Удалённое избранное и неподключённое хранилище дают ошибку, а не подменяют назначение.

В браузере текст фильтрует текущую страницу. `⌘↵` запускает рекурсивный поиск. Показатель `Partial search` означает, что стоит сузить папку или запрос: обход ограничен 200 результатами, 100 папками, глубиной 32, очередью 1000 папок и бюджетом около 8 секунд между USB-запросами.

## Запуск

1. Установите PlugOnce **0.6.6 (44) или новее** и перезапустите приложение. Одного обновления расширения Raycast недостаточно: старый запущенный `.app` не поддерживает новые методы.
2. В PlugOnce откройте **Settings → Agent Access**. Включите доступ, выберите разрешённые Mac source roots и Switch destination roots. Для доступа ко всему хранилищу нужен корень `/`; для одной папки можно разрешить, например, `/switch`.
3. Разрешите нужные действия: `device.status`, `favorites.list`, `browser.open`, `files.list`, `files.search`, `operations.list`, `operation.get`, `transfer.plan`, `transfer.commit`, `operation.cancel`. Ранее сохранённый список действий после обновления сохраняется: новые действия нужно включить отдельно.
4. Подключите устройство, для Switch запустите DBI MTP responder. Избранное добавляется в самом PlugOnce.
5. Импортируйте расширение локально из каталога `Extensions/Raycast`:

```fish
npm ci
npm run dev
```

`ray develop` импортирует команды в текущий Raycast и следит за исходниками. Его можно остановить после импорта; расширение останется установленным. Повторный запуск обновляет локальный импорт. Публикация в Raycast Store выполняется отдельно.

Выбирайте **Review Transfer Plan**, проверьте источник, устройство, хранилище, назначение, размер и замены. После запуска подтвердите запись в окне PlugOnce, если `plan.requiresConfirmation` требует подтверждения. С 0.6.7 (45) пользователь может отдельно разрешить автономную передачу новых файлов и автономную замену существующих в Agent Access; оба права по умолчанию выключены. В одном запросе можно выбрать до 50 источников; каждый получает собственный план, проверку прав и необходимое подтверждение, затем передаётся по очереди. Закрытие экрана останавливает отправку следующих источников; принятую текущую операцию контролирует PlugOnce.

Файл или папка сохраняют исходное имя. Папка назначения должна существовать. Обычная передача папок использует правила существующего native uploader, включая пропуск скрытых файлов. Символические ссылки в пакетах не принимаются. LayeredFS проверяется существующим валидатором PlugOnce. Завершение отправки в DBI не доказывает установку игры на консоли.

При таймауте или потере ответа проверьте **Transfer Operations** по сохранённому UUID. Расширение не повторяет запись автоматически: операция могла быть принята до потери ответа.

## Если команда не работает

- `UPDATE_REQUIRED`: установлен или ещё запущен PlugOnce старее 0.6.6 (44). Обновите приложение и перезапустите его; затем обновите локальный импорт расширения через `npm run dev`.
- `UNAUTHORIZED`: выполните указанное расширением действие в Settings → Agent Access. После обновления выбранные разрешения сохраняются; расширение не включает новые действия самостоятельно.
- `BUSY`: дождитесь окончания текущего чтения или передачи и нажмите Refresh.
- `NO_DEVICE`: подключите Switch и запустите Run MTP responder в DBI.

Настоящая пустая папка и поиск без совпадений остаются успешными ответами. После пустого поиска доступен Return to Folder Listing; переключение страниц доступно и при пустом результате фильтра. Неизвестный размер отображается как Unknown.

## Raycast v1, v2 и AI

Расширение собирается на `@raycast/api` **1.104.25**, чтобы сохранить API поколения v1. Локальный импорт проверен на установленном Raycast **2.6.2**. Отдельный runtime Raycast v1 здесь не проверялся; это требует запуска на машине с v1. Обычные команды используют тот же socket и не требуют AI.

Для Raycast AI добавлены инструменты `list-favorites`, `open-folder`, `list-files`, `search-files`, `plan-transfer`, `commit-transfer`, `get-operation`, `cancel-operation`, `device-status`. Их доступность зависит от версии и AI-возможностей Raycast. Перед записью AI показывает подтверждение с параметрами плана, а затем PlugOnce проверяет выданные права автономной работы или запрашивает собственное подтверждение.

Примеры запросов:

- «Покажи мои избранные папки PlugOnce и открой roms».
- «Найди main.elf внутри /switch».
- «Подготовь отправку папки сборки в моё избранное tico».
- «Покажи состояние последней передачи и результат проверки».

## Проверки разработки

```fish
npm run lint
npm run check
npm run build
npm test
```

`build` создаёт локальный `dist/`, не публикуя расширение. Тесты протокола проверяют фрагментированные ответы, идентичность запросов, неопределённый результат записи, лимит ответа, отказ доступа, пути и совместимость новых полей. Native-тесты находятся в `Tests/AgentBridgeTests.swift`: избранное, ограничения доступа, поиск, чтение актуального состояния и передача папки через socket с подтверждением и чтением результата на симуляторе.

Контракт для собственных скриптов и интеграций: [Agent Bridge](/AGENT_BRIDGE.md).