amxx-builder 1.5.1

package/AGENTS.md

@@ -0,0 +1,111 @@
+# amxx-builder — AGENTS.md
+
+## Overview
+CLI + GitHub Action for building/packaging AMX Mod X servers from an `amxbuild.yml` manifest.
+Entry: `index.js` (CLI via `commander`). Action: `action-entry.js` → synthesises `process.argv` → requires `index.js`.
+
+## Tech
+- Node.js 18+, pure **CommonJS** (`require`), no ESM. Exception: `action-entry.js` uses `import * as core from '@actions/core'` because `@actions/core@3.x` is ESM-only — esbuild transpiles it to CJS in the bundle. Do not "fix" that import back to `require`, it fails to resolve.
+- **Node 18+ is a deliberate, genuinely minimal floor.** Write code that works on Node 18 — do not use newer-version-only APIs (stable `node:test` features, `fetch`, `AbortSignal.timeout`, …) unless they exist in 18. If a feature truly requires a newer Node, propose raising the minimum in the PR/discussion first; right now there is no practical benefit in raising it (no feature pressure, no dependency forcing it), and a raised floor would only cut off users stuck on 18. CI tests the matrix 18/24 (floor + newest) to keep this honest.
+- Only dev dep: `esbuild` for bundling the GitHub Action.
+- Tests: `node --test` (built-in node:test, zero deps; discovers `test/*.test.js` automatically — keep fixtures out of `test/`). No linter or type checker configured.
+
+## Architecture: logic lives once in the core
+- All business logic MUST live in `src/` (the core) and be interface-agnostic: no `process.argv`, no `process.stdout` writes, no `commander`, no JSON-RPC/MCP schemas, no CLI rendering.
+- Interfaces are thin adapters that map params → core calls and render core events → their output format.
+  - Current interfaces: CLI (`src/commands/`), MCP (`mcp/`), serve (JSON-RPC over stdio).
+  - **serve** — started via `amxb serve`; uses `src/jsonrpc-transport.js` (generic JSON-RPC 2.0 over stdio, lives in core); methods are thin wrappers over core calls (`manifest.validate`, `build.start`, `include.resolve`, …); build progress is pushed as notifications (`build.stage` / `build.compiled` / `build.done` / `build.error`).
+  - Repo fetching (`source: git`) downloads GitHub tarballs (codeload) instead of `git clone`; system git is only required when `github.ssh: true`.
+- **Never copy a core function into an interface layer.** If two interfaces need the same behavior, it belongs in `src/` — refactor it there instead of duplicating.
+- Interfaces must not do their own resolution/parsing: reuse the core single-source-of-truth helpers instead of reimplementing them. Known ones:
+  - Include-path candidate lists (`['scripting/include', 'amxmodx/scripting/include', 'include', '.']`) — single source: `src/deps-resolver.js` (`resolveIncludePath`)
+  - Dep string parsing (`owner/repo@ref[:include_path]`) — single source: `src/manifest.js` (`parseDepsLines`)
+  - GitHub token resolution — `src/manifest.js` (`resolveGithubToken`); repo key / normalization — `src/deps-resolver.js` (`repoKey`, `normalize`)
+- When touching an interface layer, check whether the logic already exists in `src/` before writing new code. New core exports are cheap; new duplication is debt.
+
+## Commands
+| Command | Description |
+|---------|-------------|
+| `amxb build` | Full build from `amxbuild.yml` |
+| `amxb build --dry-run` | Show plan without executing |
+| `amxb build --set key=value` | Override manifest fields (dot notation for nested, e.g. `output.archive_name=...`) |
+| `amxb build --define DEBUG` | Add compiler define (appends to `amxmodx.defines`) |
+| `amxb build --verbose` | Detailed per-file output |
+| `amxb deploy` | Deploy `build/` to server path |
+| `amxb deploy --build` | Build then deploy |
+| `amxb watch` | Watch local files, incremental build+deploy |
+| `amxb init` | Scaffold manifest and optional files |
+| `amxb init --script` | Also create `build.bat` / `build.sh` quick-build scripts |
+| `amxb clean` | Clean build/ and clone cache |
+| `amxb clean --all` | Also clean compiler cache |
+| `amxb cache info` | Show cache contents |
+| `amxb serve` | Start JSON-RPC server for editor integration (stdio transport) |
+| `npm start` | Alias for `node index.js` |
+
+## Build order (matters)
+1. Parse manifest (deep-merge with `defaults/amxbuild.defaults.yml`)
+2. Fetch compiler (`amxxpc`, auto-resolves latest version)
+3. Resolve refs + clone repos (deduped by `repo@resolved_ref`)
+4. Resolve deps (git or release), collect `.inc` files
+5. **Collect** — copy files from repos + local `amxmodx/` + local `assets/` into `build/`
+6. Fetch remote assets (URLs, GitHub releases)
+7. **Compile** — all `.sma` → `.amxx` in parallel (overwrites pre-built plugins in `build/`)
+8. Generate `plugins-*.ini` into `build/amxmodx/configs/`
+9. Archive → `.zip` or copy to output dir
+
+## Manifest quirks
+- **Arrays are replaced entirely** (repos, deps, assets.sources) — not merged with defaults.
+- `version` **must be a quoted string** in YAML or parsing fails.
+- `ref: latest` resolves to the latest GitHub release tag automatically.
+- Plugin rules (`plugins:`) apply **only to local** `.sma` files, not repo plugins.
+- Local `amxmodx/` always wins over repo files (intentional override layer, no conflict warning).
+- `.sma` files ARE copied during collect (like any other file) and are also compiled; exclude them per-repo via `exclude_files` if sources should not ship.
+
+## GitHub Action release flow
+```bash
+npm ci
+npm run bundle   # esbuild action-entry.js → dist/index.js + scripts/gen-licenses.js → dist/licenses.txt
+node scripts/smoke-test.js   # runs the bundled action with INPUT_* env, asserts GITHUB_OUTPUT name output
+# Commit dist/, update package.json version, push tags, publish to npm (idempotent: re-runs are no-ops)
+```
+This is automated in `.github/workflows/release.yml` on `v*.*.*` tags.
+
+## MCP dep-resolver server
+- Source: `mcp/dep-resolver.js` (reuses `src/repo-fetcher.js`, `src/release-fetcher.js`, `src/cache-dir.js`)
+- Runs directly from source — no bundling needed (installed alongside main package)
+- Started via `amxb mcp` (registered as subcommand in `src/cli.js` → `src/commands/mcp.js`)
+- Uses a custom lightweight `McpServer` from `mcp/mcp-server.js` (no external SDK dependency)
+- Register in any project's `.opencode/opencode.json` via `"command": ["amxb", "mcp"]`
+- Exposes tools: `get_dep_interface`, `list_dep_incs`, `get_dep_tree`, `resolve_manifest`, `validate_manifest`, `get_cache_info`, `list_amxmodx_incs`, `get_amxmodx_include`, `resolve_include`, `list_releases`
+
+## Serve (JSON-RPC)
+- Source: `src/commands/serve.js` — thin adapter; transport: `src/jsonrpc-transport.js` (generic JSON-RPC 2.0 over stdio, in core, no external deps)
+- Started via `amxb serve` (registered as subcommand in `src/cli.js` → `src/commands/serve.js`); stdout stays pure JSON-RPC, logs go to stderr, progress bars disabled
+- Method categories (all thin wrappers over core calls — no domain logic in the adapter):
+  - manifest: `manifest.validate`, `manifest.resolve`
+  - include: `include.resolve`, `include.list`
+  - deps: `deps.tree`
+  - releases: `releases.list`
+  - cache: `cache.info`
+  - build: `build.plan`, `build.start`, `build.cancel`
+  - compile: `compile.single`
+  - watch: `watch.start`, `watch.stop`
+- Lifecycle events are pushed as server→client notifications: `build.stage` / `build.compiled` / `build.progress` / `build.done` / `build.error`, plus `watch.changed`
+- Full API reference (methods, params, results, error codes): `docs/serve/INDEX.md`
+
+## Cache
+- Win: `%LOCALAPPDATA%\amxx-builder`, Unix: `~/.cache/amxx-builder`
+- Override: `AMXX_BUILDER_CACHE`
+- Local per-manifest asset cache: `.amxb-cache/` next to `amxbuild.yml`
+- Separate dirs: `repos/`, `release-deps/`, `amxxpc/` (compiler binaries)
+
+## Watch mode
+- Uses `chokidar` + dep-graph (`src/dep-graph.js`).
+- `.inc` change → recompile only plugins that `#include` it.
+- `.sma` change → recompile that plugin, deploy + RCON.
+- Manifest change → full rebuild.
+- Non-sma/non-inc files → deploy directly if deploy path set.
+
+## DEPS_LIST files
+Repos can contain a `DEPS_LIST` file (one dep per line, `owner/repo@ref[:include_path]`).
+Overridden by `deps_override` on that repo. Global `deps` in manifest win over everything.

package/README.md

@@ -0,0 +1,485 @@
+# amxx-builder
+
+CLI-инструмент для сборки AMX Mod X серверов. Читает `amxbuild.yml`, клонирует плагины с GitHub, компилирует `.sma → .amxx` и упаковывает всё в готовый `.zip`.
+
+## Установка
+
+**Windows** (PowerShell):
+
+```powershell
+irm https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/install.ps1 | iex
+```
+
+**Linux / macOS**:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/install.sh | bash
+```
+
+Для приватных репозиториев передайте GitHub PAT:
+
+```powershell
+$env:GITHUB_TOKEN="ghp_xxx"; irm .../install.ps1 | iex
+```
+
+Конкретная версия (тэг, ветка, коммит):
+
+```bash
+# По умолчанию — последний релиз
+curl -fsSL https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/install.sh | bash
+
+# Конкретная версия
+AMXB_VERSION=v1.2.3 curl -fsSL https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/install.sh | bash
+```
+
+```powershell
+# По умолчанию — последний релиз
+irm https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/install.ps1 | iex
+
+# Конкретная версия
+$env:AMXB_VERSION="v1.2.3"; irm https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/install.ps1 | iex
+```
+
+Требования: **Node.js 18+**. git не требуется для установки и сборки — нужен только если манифест использует `github.ssh: true` (приватные репозитории по SSH-ключам).
+
+## Использование
+
+```bash
+amxb build                          # amxbuild.yml в текущей папке
+amxb build --manifest path/to.yml   # явный путь
+amxb build --dry-run                # показать план без выполнения
+amxb build --no-fetch               # использовать кэш, без клонирования
+amxb build --no-archive             # только скомпилировать, без .zip
+
+amxb deploy                         # задеплоить build/ на сервер
+amxb deploy --build                 # сначала собрать, потом задеплоить
+
+amxb watch                          # следить за изменениями и деплоить
+amxb watch --no-deploy              # только пересобирать, без деплоя
+
+amxb init                           # создать amxbuild.yml в текущей папке
+amxb init --deploy                  # + создать .env с заготовками для деплоя
+amxb init --plugin <name>           # + создать amxmodx/scripting/<name>.sma
+amxb init --workflow                # + создать .github/workflows/ci.yml
+amxb init --script                  # + создать build.bat / build.sh для быстрого запуска amxb build
+
+amxb clean                          # очистить build/ и кэш клонов
+amxb clean --all                    # + кэш компилятора
+amxb cache info                     # показать содержимое кэша
+```
+
+Кэш хранится в `%LOCALAPPDATA%\amxx-builder` (Windows) или `~/.cache/amxx-builder` (Unix).  
+Переопределить: `AMXX_BUILDER_CACHE=/path amxb build`.
+
+## Манифест
+
+Минимальный — только имя и список репо:
+
+```yaml
+name: MyServer
+repos:
+  - AmxxModularEcosystem/VipModular
+  - AmxxModularEcosystem/CustomWeaponsAPI
+```
+
+Это автоматически:
+
+- берёт последнюю версию компилятора
+- клонирует default branch каждого репо
+- берёт всё содержимое папки `amxmodx/` из каждого репо
+- компилирует все `.sma` из `amxmodx/scripting/`
+- упаковывает в `{name}/addons/amxmodx/` внутри архива
+
+## Структура репо плагина
+
+Инструмент ожидает папку `amxmodx/` в корне каждого репо:
+
+```text
+amxmodx/
+  scripting/
+    my_plugin.sma        ← компилируется в plugins/my_plugin.amxx
+    SubDir/
+      other.sma          ← компилируется в plugins/SubDir/other.amxx
+    include/             ← используется компилятором
+  configs/
+    my_plugin.cfg        ← копируется как есть
+  lang/
+    my_plugin.txt        ← копируется как есть
+```
+
+Имя папки переопределяется через `amxmodx.dir` (глобально) или `amxmodx_dir` (на репо).
+
+## Локальные файлы
+
+Рядом с `amxbuild.yml` можно положить:
+
+```text
+my-server/
+  amxbuild.yml
+  amxmodx/               ← мержится в addons/amxmodx/ (конфиги, доп. файлы)
+    configs/
+      server.cfg
+  assets/                ← включается по умолчанию (source: local)
+    models/
+      weapon.mdl
+    sound/
+      weapon.wav
+```
+
+## Управление локальными плагинами
+
+Поле `plugins:` позволяет фильтровать и распределять плагины из `amxmodx/scripting/` по INI-файлам. Применяется **только к локальным** плагинам; плагины из репо используют `plugins_ini_postfix` своего репо. Первое совпадение побеждает.
+
+```yaml
+plugins_ini_postfix: myserver   # глобальный постфикс → plugins-myserver.ini
+
+plugins:
+  - match: "VipM/*.sma"
+    ini: vipm             # → plugins-vipm.ini
+  - match: "utils/*.sma"
+    ini: false            # компилировать, но не включать ни в один INI
+  - match: "wip/*.sma"
+    enabled: false        # полностью пропустить (не компилировать, не деплоить)
+```
+
+| Поле | По умолчанию | Описание |
+| --- | --- | --- |
+| `match` | — | Glob-паттерн относительно `scripting/` |
+| `enabled` | `true` | `false` — пропустить компиляцию и деплой |
+| `ini` | `plugins_ini_postfix` | Постфикс INI, `false` — не включать в INI |
+
+## Удалённые ассеты
+
+Поле `assets.sources` позволяет добавлять файлы из разных источников. По умолчанию источником является локальная папка `assets/` (`source: local`).
+
+При явном указании `sources:` нужно включить `source: local` явно, если нужны локальные ассеты:
+
+```yaml
+assets:
+  # on_conflict: last_wins   # last_wins (default) / first_wins
+
+  sources:
+    - source: local           # assets/ рядом с манифестом
+
+    # Базовый amxmodx (modules, plugins и т.д.)
+    - source: amxmodx
+      map:
+        - from: addons/amxmodx/modules/
+          to: addons/amxmodx/modules/
+
+    # Архив — всё содержимое в корень ассетов
+    - url: https://cdn.example.com/pack.zip
+      cache: local           # none (default) / local (.amxb-cache/) / global (~/.cache/)
+
+    # Архив — несколько правил из одного источника
+    - url: https://cdn.example.com/full-pack.zip
+      map:
+        - from: resource/models/   # содержимое папки → models/
+          to: models/
+        - from: resource/sound/
+          to: sound/
+
+    # Одиночный файл
+    - url: https://cdn.example.com/weapon.wav
+      to: sound/weapons/
+
+    # Одиночный файл с переименованием (to без trailing slash)
+    - url: https://cdn.example.com/pistol_v2.mdl
+      to: models/v_pistol.mdl
+
+    # GitHub release asset — использует тот же кэш, что и deps
+    - source: release
+      repo: org/weapon-pack
+      ref: v2.0.0
+      asset: "weapon-models.zip"
+      map:
+        - from: models/
+          to: models/
+        - from: sound/
+          to: sound/
+```
+
+**Семантика `from` / `to` (trailing slash = содержимое папки):**
+
+| `from` | `to` | Результат |
+| --- | --- | --- |
+| *(нет)* | *(нет)* | весь архив / файл → корень ассетов |
+| `models/` | `models/` | содержимое `models/` → `assets/models/` |
+| `models` | `models/` | папка целиком → `assets/models/models/` |
+| `sound/gun.wav` | `sound/` | файл → `assets/sound/gun.wav` |
+| `sound/gun.wav` | `sound/pistol.wav` | файл с переименованием |
+
+## Деплой и watch
+
+Создайте `.env` рядом с манифестом (`amxb init --deploy`):
+
+```env
+AMXB_DEPLOY_PATH=/home/user/hlds/cstrike
+AMXB_DEPLOY_RCON_HOST=127.0.0.1
+AMXB_DEPLOY_RCON_PORT=27015
+AMXB_DEPLOY_RCON_PASSWORD=secret
+AMXB_DEPLOY_RCON_CMD=amxx load {plugin}
+```
+
+Или задайте прямо в манифесте (поддерживается `${VAR}` интерполяция):
+
+```yaml
+deploy:
+  path: /home/user/hlds/cstrike    # корень сервера (где лежат addons/, models/)
+  amxmodx_path: addons/amxmodx     # default: addons/amxmodx
+  watch_debounce_ms: 500           # мс стабильности файла перед ребилдом (default: 500)
+  exclude:                         # пути от deploy.path, которые не перезаписываются
+    - addons/amxmodx/configs/      # сохранить конфиги сервера
+    - addons/amxmodx/configs/amxx.cfg
+  rcon:
+    host: 127.0.0.1
+    port: 27015
+    password: ${RCON_PASSWORD}
+    command: "amxx load {plugin}"  # {plugin} = имя без .amxx; пусто = не слать
+```
+
+`amxb watch` отслеживает изменения в `amxmodx/` и `assets/`:
+
+- `.sma` → пересобрать плагин, задеплоить `.amxx`, послать RCON
+- `.inc` → пересобрать только плагины, зависящие от этого инклюда (по `#include`/`#tryinclude`)
+- остальные файлы → задеплоить напрямую
+- манифест → полная пересборка
+
+## Несколько GitHub токенов
+
+Если репозитории, зависимости или release-ассеты разнесены по разным организациям, а один fine-grained PAT не может охватывать несколько организаций — укажи мапу `github.tokens` (владелец → имя env-переменной с токеном этой организации):
+
+```env
+# .env рядом с amxbuild.yml
+GITHUB_TOKEN=ghp_fallback_xxx          # fallback для всех остальных
+GITHUB_TOKEN_ORGA=github_pat_111_...
+GITHUB_TOKEN_ORGB=github_pat_222_...
+```
+
+```yaml
+github:
+  token_env: GITHUB_TOKEN          # необязательно, по умолчанию GITHUB_TOKEN
+  tokens:                          # необязательно — owner → env-переменная
+    AmxxModularEcosystem: GITHUB_TOKEN_ORGA
+    Next21Team:            GITHUB_TOKEN_ORGB
+```
+
+Резолвер для каждого `owner/repo`:
+
+1. `github.tokens[owner]` — токен организации (если owner есть в мапе);
+2. `github.token_env` (по умолчанию `GITHUB_TOKEN`) — глобальный токен;
+3. иначе — анонимный доступ (публичные репо).
+
+Мапа применяется ко всему: репозитории из `repos:`, зависимости (`deps`/`DEPS_LIST`/`deps_override`), GitHub release-ассеты в `assets.sources` и команда `amxb deps-tree`. Для транзитивных зависимостей токен подбирается по владельцу автоматически.
+
+## GitHub Actions
+
+```yaml
+uses: AmxxModularEcosystem/amxx-builder@v1
+```
+
+### Инпуты
+
+| Инпут | По умолчанию | Описание |
+| --- | --- | --- |
+| `manifest` | `./amxbuild.yml` | Путь к манифесту |
+| `build-dir` | `./build` | Директория сборки |
+| `version` | — | Переопределяет `manifest.version` |
+| `archive-name` | — | Переопределяет `output.archive_name` |
+| `set` | — | Переопределить любое поле манифеста (multiline, `key=value`) |
+| `no-fetch` | `false` | Пропустить клонирование (использовать кэш раннера) |
+| `no-archive` | `false` | Только компиляция, без упаковки |
+| `github-token` | `${{ github.token }}` | GitHub токен для приватных репо |
+
+### Выходы
+
+| Выход | Описание |
+| --- | --- |
+| `name` | Имя проекта из манифеста (`manifest.name`) |
+
+### Полный пример воркфлоу
+
+Манифест плагина (`amxbuild.yml`):
+
+```yaml
+name: MyPlugin
+
+amxmodx:
+  version: "1.10.5428"
+
+deps:
+  - AmxxModularEcosystem/ParamsController@1.4.2
+```
+
+Воркфлоу (`.github/workflows/ci.yml`):
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [master, feature/**, fix/**]
+    paths-ignore:
+      - "**.md"
+  pull_request:
+    types: [opened, reopened, synchronize]
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    outputs:
+      sha:  ${{ steps.sha.outputs.SHORT }}
+      name: ${{ steps.build.outputs.name }}
+    steps:
+      - uses: actions/checkout@v5
+
+      - id: sha
+        run: echo "SHORT=$(git rev-parse --short HEAD)" >> $GITHUB_OUTPUT
+
+      - id: build
+        uses: AmxxModularEcosystem/amxx-builder@v1
+        with:
+          set: |
+            output.pack=false
+            output.dir=./artifact
+
+      - uses: actions/upload-artifact@v5
+        with:
+          name: ${{ steps.build.outputs.name }}-${{ steps.sha.outputs.SHORT }}-dev
+          path: artifact/
+
+  publish:
+    name: Publish release
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: |
+      github.event_name == 'release' &&
+      github.event.action == 'published' &&
+      startsWith(github.ref, 'refs/tags/')
+    steps:
+      - uses: actions/download-artifact@v5
+        with:
+          name: ${{ needs.build.outputs.name }}-${{ needs.build.outputs.sha }}-dev
+          path: artifact/
+
+      - name: Package for release
+        run: |
+          cd artifact
+          zip -r "../${{ needs.build.outputs.name }}-${{ github.ref_name }}.zip" .
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: "${{ needs.build.outputs.name }}-*.zip"
+```
+
+Для приватных репо и зависимостей передай PAT:
+
+```yaml
+      - id: build
+        uses: AmxxModularEcosystem/amxx-builder@v1
+        with:
+          github-token: ${{ secrets.MY_PAT }}
+```
+
+Несколько организаций — передай секреты через `env:` и пропиши мапу через инпут `set`:
+
+```yaml
+      - id: build
+        uses: AmxxModularEcosystem/amxx-builder@v1
+        env:
+          GITHUB_TOKEN_ORGA: ${{ secrets.TOKEN_ORGA }}
+          GITHUB_TOKEN_ORGB: ${{ secrets.TOKEN_ORGB }}
+        with:
+          set: |
+            github.tokens.AmxxModularEcosystem=GITHUB_TOKEN_ORGA
+            github.tokens.Next21Team=GITHUB_TOKEN_ORGB
+```
+
+## Локальная сборка (замена build.bat)
+
+`repos:` не обязателен. Если не указан — инструмент работает только с локальными файлами.
+Чтобы архив начинался с имени пакета (как при дистрибуции плагина), используй шаблон `{name}` в путях — это уже поведение по умолчанию:
+
+```yaml
+name: VipModular
+version: "5.0.0"
+```
+
+Результат:
+
+```text
+VipModular.zip
+  VipModular/
+    addons/amxmodx/
+      plugins/vip_core.amxx
+      configs/...
+      lang/...
+    models/...
+  README.md
+```
+
+Полный пример: [`example/amxbuild.local.yml`](example/amxbuild.local.yml).
+
+## ref: latest
+
+```yaml
+repos:
+  - repo: AmxxModularEcosystem/VipModular
+    ref: latest   # автоматически берёт тег последнего GitHub release
+```
+
+## Полный пример
+
+Все доступные опции: [`example/amxbuild.yml`](example/amxbuild.yml).
+
+## MCP сервер
+
+MCP сервер предоставляет агенту opencode информацию о публичном интерфейсе зависимостей AMX Mod X и стандартной библиотеки. Подробная документация — в [`docs/mcp/INDEX.md`](docs/mcp/INDEX.md).
+
+Подключение в opencode:
+
+```json
+{
+  "mcp": {
+    "amxx-dep-resolver": {
+      "type": "local",
+      "command": ["amxb", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+**Все 11 инструментов** — от просмотра `.inc` файлов до построения дерева зависимостей —
+описаны в [`docs/mcp/INDEX.md`](docs/mcp/INDEX.md) с таблицей и ссылками на полную документацию каждого инструмента.
+
+## Приоритеты
+
+| Что | Порядок (↑ выше) |
+| --- | --- |
+| плагины `plugins:` | правила применяются по порядку, первое совпадение побеждает |
+| `plugins_ini_postfix` | правило `plugins:` → репо → глобальный |
+| зависимости | `manifest.deps` → `deps_override` → `DEPS_LIST` файл в репо |
+| ассеты | порядок в `sources:` + `on_conflict` |
+| версия компилятора | `amxmodx.version` → последний релиз |
+| значения манифеста | `--set` → манифест проекта → `defaults/amxbuild.defaults.yml` |
+
+## Устранение неполадок
+
+### `no such file or directory: ./amxxpc`
+
+Если файл `./amxxpc` существует и имеет права на исполнение (`chmod +x amxxpc`), но вы всё равно получаете ошибку **"No such file or directory"** при его запуске, скорее всего, в вашей 64-битной системе Linux отсутствуют 32-битные библиотеки.
+`amxxpc` — это 32-битный исполняемый файл, которому требуется поддержка 32-битной архитектуры (`i386`).
+
+#### Решение: Установите поддержку 32-битной архитектуры
+
+**Ubuntu / Debian / WSL:**
+
+```bash
+sudo dpkg --add-architecture i386
+sudo apt update
+sudo apt install libc6:i386 libstdc++6:i386
+```

package/action-entry.js

@@ -0,0 +1,42 @@
+'use strict';
+
+import * as core from '@actions/core';
+const fs   = require('fs');
+const yaml = require('js-yaml');
+
+const manifest     = core.getInput('manifest')     || './amxbuild.yml';
+const buildDir     = core.getInput('build-dir')    || './build';
+
+// Expose manifest name as output before the build runs
+try {
+  const raw = yaml.load(fs.readFileSync(manifest, 'utf8'));
+  if (raw && raw.name) core.setOutput('name', raw.name);
+} catch (_) {}
+const version      = core.getInput('version');
+const archiveName  = core.getInput('archive-name');
+const setRaw       = core.getInput('set');
+const noFetch      = core.getInput('no-fetch')     === 'true';
+const noArchive    = core.getInput('no-archive')   === 'true';
+const githubToken  = core.getInput('github-token');
+
+if (githubToken) process.env.GITHUB_TOKEN = githubToken;
+
+// Collect all --set pairs: shorthands first, then raw multiline block
+const setPairs = [];
+if (version)     setPairs.push(`version=${version}`);
+if (archiveName) setPairs.push(`output.archive_name=${archiveName}`);
+if (setRaw)      setPairs.push(...setRaw.split(/\r?\n/).map(s => s.trim()).filter(Boolean));
+
+// Synthesise argv so Commander in index.js parses our inputs
+process.argv = [
+  process.execPath,
+  'amxx-builder',
+  'build',
+  '--manifest', manifest,
+  '--build-dir', buildDir,
+  ...setPairs.flatMap(p => ['--set', p]),
+  ...(noFetch   ? ['--no-fetch']   : []),
+  ...(noArchive ? ['--no-archive'] : []),
+];
+
+require('./index.js');