amxx-builder 1.5.2 → 1.6.0

package/skills/amxb-migration/SKILL.md

@@ -0,0 +1,554 @@
+---
+name: amxb-migration
+description: >-
+  Миграция AMXX-проекта (AMX Mod X, Counter-Strike) на сборщик amxb (amxx-builder):
+  перевод репозитория на amxbuild.yml, подключение зависимостей (deps), настройка
+  .gitignore / CI / MCP, замена старых скриптов сборки. Использовать, когда пользователь
+  просит «настроить сборку через amxb», «перевести/перенести проект на amxb / amxbuild.yml»,
+  «заменить старые bat/ps1/sh-скрипты или CI на amxb», «добавить/дополнить amxbuild.yml»,
+  либо мигрирует проект с ручной компиляции (compile.exe/amxxpc) на автоматическую.
+  Скилл работает в проекте, где amxb ещё не установлен (установка — шаг 0). Триггеры:
+  amxb, amxx-builder, amxbuild.yml, AMX Mod X, AMXX, миграция сборки, build system
+  migration, amxx-builder migration. Use when migrating an AMX Mod X plugin/server
+  project to the amxb builder.
+---
+
+# Миграция AMXX-проекта на amxb
+
+Перевод репозитория AMXX-плагинов на сборщик **amxb** (`amxx-builder`).
+Конфигурация — один файл `amxbuild.yml` в корне проекта. Результат миграции:
+проект собирается командой `amxb build` (или в CI через
+`AmxxModularEcosystem/amxx-builder@v1`) в готовый `.zip`.
+
+## Когда применять / не применять
+
+**Применять**, когда пользователь просит:
+- настроить сборку через amxb / перевести проект на `amxbuild.yml`;
+- заменить старые скрипты сборки (`.bat`/`.ps1`/`.sh`, `config.bat`,
+  `.build-config`) или старый CI на amxb;
+- разобрать существующий `amxbuild.yml`, дополнить его, найти ошибку в deps.
+
+**Не применять**, когда:
+- задача — просто собрать/задеплоить уже настроенный amxb-проект (это
+  обычные команды `amxb build` / `amxb deploy`, скилл не нужен);
+- пользователь хочет писать плагины (это не миграция).
+
+## Стартовое состояние
+
+Проект может находиться в любом из состояний, все они корректны:
+
+- уже есть старая система сборки (`bat`/`ps1`/`sh`-скрипты,
+  `.build-config`, CI со сборкой);
+- есть только CI со списком зависимостей;
+- вообще нет никакой системы сборки — это нормально, просто входных
+  данных меньше.
+
+**Правило (границы доступа):** вся информация берётся **только из папки
+целевого проекта**. Запрещено читать, открывать или иначе исследовать любые
+файлы/папки **вне её** — соседние проекты на диске, sibling-репозитории,
+аналоги пользователя, чужие репозитории. Запрет действует **независимо от
+цели**: и как источник данных, и «просто для понимания экосистемы», и для
+проверки гипотез. Такое чтение нарушает границы задачи и приватность
+(соседний проект может быть приватным/чужим/нерелевантным). Если данных
+не хватает — задаём вопросы пользователю, а не докапываемся самостоятельно.
+
+**Где работать:** все шаги выполняются в корне целевого проекта (там, где
+должен лежать `amxbuild.yml`). Пути в манифесте относительны именно него.
+
+## Что amxb делает «из коробки» (минимальный манифест)
+
+Прежде чем задавать вопросы о структуре пакета — понять, что amxb даёт сам.
+Манифест из одного `name:` уже собирает проект в архив по умолчанию:
+
+```text
+{name}.zip                        ← output.archive_name (default: "{name}.zip")
+├── README.md                     ← output.readme: true (если есть в корне проекта)
+└── {name}/                       ← обёртка: часть output.amxmodx_path / assets_path
+    ├── addons/amxmodx/           ← output.amxmodx_path (default: "{name}/addons/amxmodx")
+    │   ├── configs/...           ← локальная amxmodx/configs (мержится с репо)
+    │   ├── data/... lang/...
+    │   ├── plugins/*.amxx        ← скомпилированные .sma
+    │   └── scripting/...         ← исходники (копируются и компилируются)
+    └── sound/, models/, ...      ← содержимое assets/ → в {name}/ (source: local)
+```
+
+Ключевое: **дефолтная раскладка архива уже совпадает с типовым пакетом
+плагина/сервера** (`{name}/addons/amxmodx/...`) — обычно структуру менять не
+нужно и вопросы про неё не задаются. README попадает в архив только при
+`output.readme: true` (это дефолт). Архив ложится в `output.dir` рядом с
+манифестом (default: `./`).
+
+Точные пути печатает план сборки — см. Шаг 4 (проверка через
+`amxb build --dry-run`), а не догадки о схеме.
+
+## Шаг 0. Убедиться, что amxb доступен
+
+Скилл рассчитан на проект, где amxb может быть ещё **не установлен**.
+
+1. Проверить наличие:
+   ```bash
+   amxb --version
+   ```
+2. Если команды нет — установить (нужен Node.js 18+):
+
+   Глобально через npm:
+   ```bash
+   npm i -g amxx-builder
+   ```
+
+   Или через официальный установщик (не требует npm):
+   ```bash
+   # Windows (PowerShell):
+   irm https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/install.ps1 | iex
+   ```
+   ```bash
+   # Linux / macOS:
+   curl -fsSL https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/install.sh | bash
+   ```
+
+   Для приватных репозиториев во время установки передать `GITHUB_TOKEN`:
+   ```bash
+   GITHUB_TOKEN=ghp_xxx curl -fsSL https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/install.sh | bash
+   ```
+
+   Конкретную версию можно зафиксировать переменной `AMXB_VERSION` (тег `v1.2.3`).
+
+3. Если глобальная установка нежелательна/невозможна — можно запускать любую
+   команду amxb через npx без установки:
+   ```bash
+   npx --yes amxx-builder@latest build --dry-run
+   ```
+   (далее в тексте команды записаны как `amxb ...` — при работе через npx
+   подставлять `npx --yes amxx-builder@latest ...`.)
+
+4. Проверить окружение (Node, доступность GitHub API, кэш, при наличии —
+   валидность манифеста):
+   ```bash
+   amxb doctor
+   ```
+
+> Для самой миграции amxb не нужно добавлять в зависимости проекта —
+> это глобальный CLI (или GitHub Action в CI).
+
+## Шаг 1. Собрать входные данные (только внутри проекта)
+
+1. **Список плагинов**: все `.sma` в `amxmodx/scripting/` (рекурсивно).
+   amxb компилирует `**/*.sma` и сохраняет относительный путь
+   (вложенный `.sma` → `plugins/подпапка/имя.amxx`).
+2. **Используемые include** — по всему `scripting/` (и `.sma`, и `.inc`):
+   ```bash
+   grep -rhoE '^\s*#include\s*[<"][^>"]+[>"]' amxmodx/scripting \
+     --include='*.sma' --include='*.inc' \
+     | sed -E 's/^\s*#include\s*([<"])(.*)/\2/' | sed -E 's/[>"]$//' \
+     | sort | uniq -c | sort -rn
+   ```
+3. **Целевая структура пакета**: если есть старый `*.zip` или каталог
+   `.build/` — распаковать и посмотреть, что входило: `configs/`,
+   `plugins/`, `scripting/`, ini-файлы, `data/lang/`. Это эталон для сверки.
+4. **Подсказки о зависимостях** — что может лежать в проекте. Приоритет — по
+   ценности источника, от самого конкретного к самому общему:
+   1. **CI/workflow** (`.github/workflows/`, `.gitlab-ci.yml` и т.п.) — самый
+      ценный источник: в нём проект когда-то собирался и все версии зафиксированы.
+      Искать конкретику, а не «список зависимостей вообще»:
+      - упоминания репозиториев: `uses: AmxxModularEcosystem/...`, `wget`/`curl`
+        `github.com/<owner>/<repo>`, переменные `REPO=...`, `OWNER/REPO`;
+      - **версии**: `*_TAG=...`, `ref: v...`, `@v...`, теги в URL релизов;
+      - **include-пути**: `INCLUDE_PATH=...`, флаги `-i...`, пути вида
+        `addons/amxmodx/scripting/include`, `amxmodx/scripting/include`;
+      - версию компилятора/AMXX (обычно в той же строке установки include).
+   2. `deps.txt` — список GitHub-репо зависимостей (если есть).
+   3. `.build-config` / `config.bat` / другие скрипты сборки — дают доп.
+      параметры для манифеста (имя пакета, ini-постфикс, defines). В них же
+      могут встречаться пути вида `C:\AmxModX\1.9.0`, имена `amxx190`/`amxxpc`
+      — это указание на линию AMXX, под которую собран проект; значение оно
+      имеет только если линия <= 1.8.3 (см. Шаг 4 — версию компилятора пиним
+      только для этой старой линии).
+   Если CI в проекте есть — он даёт и источники, и версии, и include-пути
+   сразу, и вопросов пользователю может не понадобиться вовсе.
+
+## Шаг 2. Классифицировать include
+
+| Группа | Примеры | Действие |
+|---|---|---|
+| Стандартная библиотека AMXX | `amxmodx`, `fakemeta`, `hamsandwich`, `nvault`, `regex`, `json` | ничего не нужно |
+| Локальные (внутри проекта) | свои `.inc` в `scripting/`, `scripting/include/` | ничего не нужно — amxb сам подключает `scripting/` и `scripting/include/`, а дерево `amxmodx/` мержится в пакет |
+| Внешние | чужие API-библиотеки/модули | запись в `deps:` манифеста |
+
+> Публичные API самого проекта (свои `.inc`, объявляющие natives, которые
+> реализуют плагины проекта) — НЕ deps. deps — только то, что приходит извне.
+
+## Шаг 3. Поиск источников внешних include
+
+Имея только имя инклуда (`<cwapi>`, `<player_prefs>`, `<reapi>`...), агент
+никак не может надёжно определить его источник. Поэтому **источник include
+ищется только внутри проекта или уточняется у пользователя** — поиск по
+GitHub/вебу по имени инклуда запрещён (это чтение чужих репозиториев, см.
+правило выше):
+
+1. **CI/workflow проекта** — самый конкретный источник (см. Шаг 1): репо в
+   `uses:`/URL, версии в `*_TAG=`, include-пути. Если CI есть — начать с него.
+2. `deps.txt` / `.build-config` — если упоминают репозиторий, дающий этот
+   include — берём его.
+3. Чтение шапки `.inc` или места использования внутри проекта: часто инклуд
+   сам включает другие (`#include <reapi>` внутри чужого API → ReAPI нужен
+   отдельным dep).
+4. **Если после разбора CI и скриптов сборки источник не находится — НЕ копаем
+   сами.** Задаём вопрос пользователю: откуда инклуд, в каком репозитории он
+   лежит. Вопрос задаём по каждому неопознанному include, а не по одному
+   самому очевидному.
+
+**Репозиторий «не найден» — это ещё не «репозитория не существует».**
+GitHub отвечает 404 одинаково и для несуществующих, и для приватных (или
+недоступных без токена) репозиториев. Поэтому, если подтверждённый (названный
+пользователем или найденный в CI) репозиторий не резолвится (`amxb deps-tree`
+показывает not found), действуем по порядку:
+
+1. **Сначала пробуем токены из `.env`** рядом с манифестом (если они там
+   есть: `GITHUB_TOKEN`, `GITHUB_TOKEN_*`). Прописываем их в манифест
+   (`github.token_env` / `github.tokens`, см. Шаг 5) и повторяем
+   `amxb deps-tree` — репозиторий мог быть приватным, и токен уже лежит
+   рядом. Не спрашиваем пользователя, пока не проверили имеющиеся токены.
+2. **Если токенов нет или они не помогли** — первая гипотеза: репозиторий
+   приватный. Задаём пользователю вопрос с двумя вариантами:
+   - дать токен для этого владельца (`github.tokens` + `.env`), либо
+   - уточнить имя репозитория — если в CI/запросе была опечатка
+     (`Owner/Repoo` → `Owner/Repo`).
+   Не делаем вывод «репозитория не существует» без подтверждения пользователя.
+
+**Проверка версии у подтверждённого источника — штатными средствами amxb,
+не вручную.** Список релизов/тегов репозитория-источника (после того как
+источник назван пользователем или найден в CI) смотрим командой:
+
+```bash
+amxb releases Owner/Repo        # релизы; --tags для тегов, --limit N
+```
+
+Ту же информацию (и резолв include/деревьев) дают MCP-инструменты
+`amxx-dep-resolver` (`list_releases`, `get_dep_tree`, `resolve_include`) —
+**это инструменты для АГЕНТА: они дают миграции больше данных о проекте без
+ручных запросов**. Но они доступны только если реально видны в текущей
+сессии — MCP подхватывается **после перезапуска opencode, который нужен
+самому агенту** (см. Шаг 9), а не пользователю. Если инструментов в сессии
+нет — не ждём и не молчим, а работаем CLI: `amxb releases` / `amxb deps-tree`
+дают ту же информацию без перезапуска. Ручные запросы к GitHub API/вебу для
+выбора версии не нужны и не делаются — см. «Формат deps» ниже. Чужие/соседние
+репозитории и их содержимое при этом не открываем.
+
+### Формат deps
+
+```yaml
+deps:
+  # git-репо: owner/repo@ref, опционально :путь_до_include_внутри_репо
+  - Owner/Repo@tag
+  - Owner/Repo@tag:нестандартный/путь/до/include
+
+  # модуль из release-архива; ref: latest резолвится в последний релиз,
+  # но в манифест пишем конкретный тег (см. «Выбор версии» ниже)
+  - repo: Owner/Repo
+    ref: 5.29.0.358
+    source: release
+    include_path: путь/внутри/архива/до/include
+
+  # .inc закрытого плагина с fungun.net (магазин без архивов и git-репо):
+  # id — индекс плагина в адресе страницы; можно указать полную ссылку url:
+  - source: fungun
+    id: 106
+```
+
+Источников у deps три: `git` (по умолчанию), `release` (GitHub release-архив)
+и `fungun` (публичный `.inc` со страницы закрытого плагина на fungun.net).
+
+**Что даёт `deps:` и чего не даёт.** `deps:` — это **только заголовочные
+файлы (`.inc`) для компиляции**. amxb **не компилирует и не упаковывает**
+плагины из репозиториев-зависимостей. Для большинства плагинов это
+корректно (модули ставятся на сервер отдельно). Но если мигрируемый проект —
+это сборка, где плагины зависимостей должны **попасть в итоговый пакет**,
+нужны `repos:` (репозитории как часть сборки) и/или `assets:` — а не `deps:`.
+Определить, что нужно, можно по старой системе сборки: если она клонировала
+репозитории и компилировала их `.sma` в один пакет — это `repos:`; если
+только клала их include в папку инклудов — это `deps:`.
+
+**Выбор версии** — под «последней версией» понимается не строка `latest` в
+манифесте, а **получение конкретной версии и её фиксация**. Алгоритм:
+
+1. **Узнать последнюю версию** подтверждённого источника: для `source: release`
+   `ref: latest` резолвится в последний GitHub-релиз, для git-репо — в
+   последний тег. Смотрим штатно: `amxb releases Owner/Repo` (релизы),
+   `amxb releases Owner/Repo --tags` (теги), либо MCP `list_releases`.
+2. **Проверить последнюю версию реальной сборкой** (`amxb deps-tree`, затем
+   `amxb build`), что include резолвится и natives находятся (`--dry-run` план
+   не компилирует и этого не покажет).
+3. **Если последняя версия найдена и подходит — берём её**, в манифест пишем
+   **конкретный тег** (а не строку `latest`) — сборка становится
+   воспроизводимой. `latest` в манифесте оставляем только если политика
+   источника осознанно «всегда последняя» (подтверждена старым CI).
+4. **Если последней версии нет или она не подходит** (свежая линия сменила
+   неймспейс include `<Module>` → `<Namespace/Module>` или префиксы natives
+   `MOD_*` → `NS_MOD_*`) — берём версию, **найденную по проекту** (старый CI:
+   `*_TAG=...`, `ref: v...`; `deps.txt`; README) — с ней проект уже собирался.
+   Её тоже проверяем сборкой.
+5. **Если нет ни того ни другого** — НЕ молчим и НЕ правим код втихую.
+   Формулируем пользователю развилку: **(A)** зафиксировать совместимый старый
+   тег (например rc-линию) — если на серверах стоит именно эта линия, либо
+   **(B)** обновлять код проекта под новое API — отдельная задача за рамками
+   миграции. Без ответа пользователя версию не закрепляем.
+6. Если пользователь не может назвать точные версии (отвечает «latest» /
+   «не знаю») — закрепляем выбранные, но **явно помечаем их как
+   предварительные** и выносим в итоговый отчёт как открытый вопрос, чтобы
+   риск несовместимости был зафиксирован, а не замолчан.
+
+## Шаг 4. Манифест и структура проекта
+
+1. **Сначала написать минимальный манифест и посмотреть план**, а не
+   угадывать структуру/задавать вопросы о ней. Дефолтная раскладка уже
+   совпадает с типовым пакетом (см. «Что amxb делает из коробки» выше), а
+   `amxb build --dry-run` печатает фактические пути:
+   ```bash
+   amxb build --dry-run
+   # ...
+   # Output:
+   #   archive → /abs/path/./{name}.zip
+   #   amxmodx path in archive: {name}/addons/amxmodx/
+   #   assets path: {name}/
+   #   generate_ini: false  |  on_conflict: last_wins
+   ```
+   Вопросы пользователю про структуру задаём **только если** фактическая
+   раскладка отличается от дефолтной и это принципиально (серверная сборка,
+   нестандартное расположение `amxmodx/`).
+2. Если структура проекта отличается от дефолтной для amxb
+   (`amxmodx/scripting/`, `amxmodx/configs/`, `assets/`) — можно предложить
+   привести её к стандарту. **Если пользователь отказывается менять
+   структуру — описываем в манифесте всё, что нужно для работы с текущей**
+   (поля `amxmodx.dir`, пути в deps, `output.*`).
+3. Базовые вопросы при нехватке данных: имя пакета, нужен ли ini со списком
+   плагинов и с каким постфиксом, что входит в пакет.
+4. **Версия компилятора (amxxpc) — всегда последняя.** В манифесте поле
+   `amxmodx.version` **не указываем** — amxb сам берёт последнюю доступную
+   версию. Единственное исключение: если проект таргетит AMXX **1.8.3 или
+   старее** — эта линия достаточно старая и сильно отличается (другой набор
+   инклудов/нативов, поведение компилятора), поэтому её версию пиним явно.
+   Подсказки в старых скриптах (`amxx190`, пути `C:\AmxModX\1.9.0`) — не
+   повод пинить: 1.9 и новее компилируются последним amxxpc. Уточнять у
+   пользователя нужно только одно: не 1.8.x ли у него сервер.
+5. Минимально полезный манифест:
+   ```yaml
+   # yaml-language-server: $schema=https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/schema/amxbuild.schema.json
+
+   name: MyPackage
+
+   # amxmodx.version не указываем — amxb берёт последний компилятор.
+   # Исключение — AMXX 1.8.3 или старее, тогда пиним явно (точное значение
+   # версии согласовать с пользователем — у линии 1.8 своя нумерация):
+   # amxmodx:
+   #   version: "1.8.3"    # строка в кавычках
+
+   deps:
+     - Owner/Repo@tag
+
+   # plugins-*.ini: по умолчанию НЕ генерируется (generate_ini: false).
+   # Если старой сборке ini не нужен — ничего добавлять не надо.
+   # Если нужен (как в старой сборке) — включить генерацию и постфикс:
+   # plugins_ini_postfix: core        # → plugins-core.ini
+   # output:
+   #   generate_ini: true
+   ```
+6. **Правила `plugins:`** — фильтрация локальных плагинов (к репо-плагинам
+   не применяются). Первое совпадение побеждает. Например, исключить из
+   сборки тестовые/легаси `.sma`:
+   ```yaml
+   plugins:
+     - match: "*Test*.sma"
+       enabled: false
+     - match: "utils/*.sma"
+       ini: false          # компилировать, но не включать ни в один INI
+   ```
+7. Помнить особенности amxb:
+   - локальная папка `amxmodx/` всегда выигрывает у файлов из репо
+     (намеренный слой переопределения, предупреждений нет);
+   - `.sma`-файлы **и копируются** в пакет (как любые файлы), **и
+     компилируются**; если исходники не должны попадать в архив — исключить
+     их (для репо — `exclude:`/`exclude_files:` в правиле репозитория);
+   - README.md попадает в архив только при `output.readme: true` (дефолт).
+
+## Шаг 5. Приватные репозитории
+
+**Сигнал приватности — 404.** Если deps/repos не резолвятся (`amxb deps-tree`
+показывает not found), а пользователь уверен, что репозиторий существует, —
+первая гипотеза: репозиторий приватный, а не удалённый и не опечатка
+(GitHub отдаёт 404 одинаково в обоих случаях). Порядок действий:
+
+1. Проверить, нет ли уже токенов в `.env` рядом с манифестом; если есть —
+   подключить (`github.token_env` / `github.tokens`) и повторить `deps-tree`,
+   прежде чем что-либо спрашивать.
+2. Если токенов нет/не помогли — спросить пользователя: дать токен для
+   владельца приватного репо или уточнить имя (вдруг опечатка).
+
+Если приватность подтверждена (или сам проект приватный) — конфигурация
+такая:
+
+```yaml
+github:
+  tokens:
+    OwnerName: GITHUB_TOKEN_OWNER
+```
+
+и рядом с манифестом — `.env`:
+
+```
+GITHUB_TOKEN_OWNER=ghp_...
+```
+
+`.env` обязательно в `.gitignore`! В CI те же переменные прокидываются из
+секретов в `env:` шага с action `AmxxModularEcosystem/amxx-builder@v1`
+(встроенного `GITHUB_TOKEN` для чужих приватных репо недостаточно).
+
+## Шаг 6. .gitignore
+
+За основу берётся шаблон `amxb init --gitignore`. При миграции **свериться
+с исходным `.gitignore`** и сохранить специфичные для проекта строки,
+которых нет в шаблоне. Типовой результат:
+
+```gitignore
+# Артефакты сборки
+*.amxx
+*.zip
+build/
+dist/
+plugins-*.ini
+
+# старый bat-билд (если был)
+.build
+
+# amxb: секреты и кэш
+.env
+.env.local
+.amxb-cache/
+
+# инструменты / редактор
+.omo/
+.codegraph/
+.vscode/
+.claude/
+node_modules/
+```
+
+## Шаг 7. Замена старых скриптов
+
+Мини-чек-лист адаптации (шаблоны `amxb init` не перезаписывают существующие
+файлы — только явный `amxb init --force` перезапишет; всё, что уже есть,
+правим/создаём вручную):
+
+- `amxb init --script` создаёт тонкий `build.bat`/`build.sh` (просто
+  `amxb build`) — только если файлов ещё нет. Если `build.bat`/`build.sh`
+  уже существуют — **заменяем их вручную** тонкими (init их не тронет без
+  `--force`).
+- Старые скрипты сборки (`config.bat`, `build-debug.bat`,
+  `build-release.bat`, `.build-config`, `deps.txt` после переноса данных в
+  манифест, старые `*.zip`, `.build/`) — удаляем.
+- Debug/release — через defines: `amxb build --define DEBUG`.
+- **НЕ создавать тестовые плагины** через `amxb init --plugin <name>` в
+  рамках миграции/отладки: файл создаётся пустым и сам провоцирует
+  `error 100` при компиляции (см. Шаг 10). Проверка идёт по реальным `.sma`
+  проекта.
+
+## Шаг 8. CI
+
+Если CI уже есть — правим существующий файл, не плодим новый. Что учесть:
+
+- ветки и триггеры: сверить с фактической дефолтной веткой репозитория
+  (`main`/`master`) и со старым CI (перенести `paths-ignore`, типы PR и т.п.);
+- секреты токенов для приватных deps — в `env:` шага сборки;
+- dev-артефакт на каждый push + zip в релиз — как в шаблоне
+  `amxb init --workflow` (именование dev: `{name}-{sha}-dev`, релизный zip:
+  `{name}-{ref_name}.zip`);
+- `output.readme: true` работает и при `output.pack: false` — README копируется
+  в каталог артефакта сам, отдельный шаг копирования в publish-джобе не нужен;
+- если в шаблоне CI ветки/триггеры не совпадают с реальностью — правим,
+  шаблон не догма.
+
+## Шаг 9. MCP (опционально)
+
+`amxb init --opencode` создаёт `.opencode/opencode.json` с MCP-сервером
+`amxx-dep-resolver` (`amxb mcp`), дающим агенту инструменты резолва include,
+дерева зависимостей и компиляции. **Это инструменты для АГЕНТА, а не для
+пользователя**: они дают миграции больше данных о проекте (резолв инклудов,
+список релизов, дерево deps) без ручных запросов и ускоряют её. Файл коммитим
+(внутренние `node_modules`/`package*.json` — нет, у них свой `.gitignore`).
+
+**Перезапуск opencode нужен самому агенту, а не пользователю.** Без
+перезапуска инструменты `amxx-dep-resolver` не появятся в сессии агента, и
+миграция лишится MCP-данных о проекте (придётся работать через CLI
+`amxb releases`/`deps-tree` — это работает, но медленнее). Поэтому после
+создания/правки конфига:
+
+1. проверить, появились ли инструменты `amxx-dep-resolver` в текущей сессии;
+2. если не появились (или проверить не удалось) — **явно попросить
+   пользователя перезапустить opencode** (выйти и запустить заново),
+   объяснив, что перезапуск нужен агенту, чтобы получить инструменты для
+   миграции; продолжить миграцию можно и без них, но с MCP она точнее;
+3. не утверждать, что MCP работает, если инструменты не видны, и не молча
+   продолжать без MCP там, где он мог бы дать данные о проекте.
+
+## Шаг 10. Проверка результата
+
+```bash
+amxb validate          # манифест валиден
+amxb deps-tree         # все deps резолвятся (приватные — по токенам)
+amxb build --dry-run   # план: компилятор, deps, архив, ini
+amxb build             # полная сборка
+```
+
+Критерии успеха:
+
+- все плагины компилируются (`OK` по каждому);
+- ini-файл(ы) сгенерированы, если включены;
+- содержимое архива структурно совпадает со старым пакетом (если он был).
+
+Как читать ошибки:
+
+- `fatal error 100: cannot read from file: "<путь>.sma"` — сначала проверить
+  **сам файл**, а не окружение:
+  1. файл существует (`ls -l <путь>.sma`);
+  2. файл **не пустой** — пустой `.sma` (0 байт) даёт ровно ту же ошибку.
+     Пустые `.sma` не должны попадать в сборку: `amxb init --plugin` создаёт
+     пустую заготовку, и если она осталась в `scripting/` — это ложный след.
+     Такие файлы удаляем или исключаем (`plugins:` → `enabled: false`).
+  3. Если файлы на месте и непустые, а ошибка **для всех** файлов при верных
+     путях → проблема окружения, не манифеста (например, WSL: amxxpc
+     32-битный и не читает `/mnt/c`).
+- **WSL (`/mnt/c`) — готовый рецепт полной проверки.** В WSL из `/mnt/c`
+  работают `validate`, `deps-tree`, `--dry-run` (компилятор не запускается),
+  но полный `amxb build` падает на 32-битном amxxpc. Полную сборку выполняем
+  из нативной Linux-папки — кэш общий, повторно ничего не качается:
+  ```bash
+  mkdir -p ~/amxb-build-check && cp -r amxmodx assets amxbuild.yml README.md ~/amxb-build-check/
+  cd ~/amxb-build-check && amxb build
+  # кэш ~/.cache/amxx-builder общий для всех папок — deps/компилятор уже там
+  ```
+  Финальную сборку из `/mnt/c` пользователь выполняет на Windows (`build.bat`)
+  или в CI; в WSL проверяются `validate`/`deps-tree`/`--dry-run`.
+- `unable to open include file` для конкретного инклуда → не хватает dep
+  или неверный путь до include внутри dep.
+- `undefined symbol/native` → несовпадение версии API: include резолвится,
+  но код использует другой неймспейс/префиксы (`MOD_*` vs `NS_MOD_*`) —
+  значит, выбрана не та линия релизов зависимости (см. «Формат deps»).
+  Уточнить у пользователя корректную версию.
+
+## Чек-лист
+
+- [ ] amxb доступен (установлен глобально или вызывается через npx)
+- [ ] НЕ читались файлы/репозитории вне папки целевого проекта (в т.ч. соседние проекты, «для понимания»)
+- [ ] Входные данные собраны только из папки проекта: CI/workflow разобран первым (репо, версии, include-пути)
+- [ ] Внешние include сопоставлены с источниками; не найденные после разбора CI/скриптов — согласованы с пользователем
+- [ ] При «репо не найден» (404): сначала проверены токены из `.env`, затем у пользователя запрошен токен/уточнение имени — вывод «репо не существует» без подтверждения не делался
+- [ ] Дефолтная раскладка проверена `amxb build --dry-run`; вопросы про структуру — только при отличии от дефолта
+- [ ] `amxbuild.yml`: name, deps, ini/постфикс при необходимости; `amxmodx.version` не указан (последний компилятор), кроме AMXX <= 1.8.3
+- [ ] Версии deps: последняя проверена сборкой → иначе версия из проекта/CI → иначе вопрос; в манифесте конкретные теги, не «latest»
+- [ ] Приватные deps: 404 обработан как «приватный/опечатка» → `github.tokens` + `.env` (в .gitignore)
+- [ ] `.gitignore`: шаблон amxb + сохранены специфичные строки проекта
+- [ ] Старые скрипты удалены; существовавший `build.bat`/`build.sh` заменён тонким вручную
+- [ ] Пустые/заглушечные `.sma` (в т.ч. от `init --plugin`) не попадают в сборку
+- [ ] CI обновлён: ветки/триггеры сверены со старым CI и дефолтной веткой; README при `pack=false` не копируется вручную
+- [ ] MCP (если делали): файл создан; если инструменты `amxx-dep-resolver` не подхватились — пользователю сказано перезапустить opencode (перезапуск нужен агенту для доступа к инструментам)
+- [ ] `amxb validate` + `deps-tree` + `build` проходят (в WSL из `/mnt/c` — полная сборка из нативной Linux-папки)
+- [ ] Архив структурно совпадает со старым пакетом

package/src/build-plan.js

@@ -41,8 +41,10 @@ function buildPlanData(manifest, options = {}) {
     })),
     globalDeps: manifest.globalDeps.map((d) => ({
       source: d.source,
-      repo: d.repo,
+      repo: d.source === 'fungun' ? null : d.repo,
       ref: d.ref,
+      id: d.id ?? null,
+      url: d.url ?? null,
       include_path: d.include_path || null,
       asset: d.asset ?? null,
     })),

package/src/cli.js

@@ -248,6 +248,7 @@ program
   .option('--opencode',      'Create .opencode/opencode.json with MCP config (amxb mcp)')
   .option('--deploy',        'Create .env with deploy stubs (AMXB_DEPLOY_*)')
   .option('--script',        'Create build.bat and build.sh quick-build scripts')
+  .option('-f, --force',     'Overwrite existing files instead of skipping them')
   .option('-i, --interactive', 'Interactive mode with prompts')
   .action(async (options) => {
     try {

package/src/commands/deps-tree.js

@@ -56,7 +56,10 @@ function printNode(node, prefix, isLast) {
   const childPrefix = isLast ? '    ' : '│   ';
 
   const tag = buildNodeTag(node);
-  logger.dim(`${prefix}${connector}${node.repo}@${node.ref || 'HEAD'}${tag}`);
+  const label = node.source === 'fungun'
+    ? `[fungun] plugin #${node.id}`
+    : `${node.repo}@${node.ref || 'HEAD'}`;
+  logger.dim(`${prefix}${connector}${label}${tag}`);
 
   if (node.cycle) return;
 

package/src/commands/dry-run.js

@@ -28,6 +28,10 @@ function printDryRun(manifest) {
   if (manifest.globalDeps.length) {
     logger.info(`\nGlobal deps (${manifest.globalDeps.length}):`);
     for (const d of manifest.globalDeps) {
+      if (d.source === 'fungun') {
+        logger.dim(`  [fungun] plugin #${d.id}  (${d.url})`);
+        continue;
+      }
       const src = d.source === 'release' ? 'release' : 'git';
       logger.dim(`  [${src}] ${d.repo}@${d.ref}${d.include_path ? ':' + d.include_path : ''}`);
     }