amxx-builder 1.5.2 → 1.6.1

package/AGENTS.md

@@ -8,7 +8,7 @@ Entry: `index.js` (CLI via `commander`). Action: `action-entry.js` → synthesis
 - 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.
+- Tests: `node --test` (built-in node:test, zero deps; discovers `test/*.test.js`). Keep fixtures out of `test/`, and do NOT name non-test scripts `*-test.js` — the runner's default glob (`**/*-test.js`) would execute them as tests. The bundler smoke script is `scripts/smoke.js` (needs a bundled `dist/` + compiler cache, so it is run explicitly, never by the test runner). 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.
@@ -35,13 +35,18 @@ Entry: `index.js` (CLI via `commander`). Action: `action-entry.js` → synthesis
 | `amxb deploy --build` | Build then deploy |
 | `amxb watch` | Watch local files, incremental build+deploy |
 | `amxb init` | Scaffold manifest and optional files |
+| `amxb init --force` | Scaffold, overwriting existing files (default: skip) |
 | `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 skills-dir` | Print absolute path to the bundled `skills/` dir (used by the opencode bridge plugin) |
+| `amxb opencode-skills` | Print container path(s) of materialized skills (bundled + current project + deps/repos) for the opencode bridge |
 | `amxb serve` | Start JSON-RPC server for editor integration (stdio transport) |
 | `npm start` | Alias for `node index.js` |
 
+The opencode bridge plugin (`.opencode/plugin/amxb-skills.js`, generated by `amxb init --opencode`) registers skills from three sources: the builder's bundled `skills/` (`amxb skills-dir`), the current project's own `skills:`, and all `deps`/`repos` skills read from their manifests (`amxb opencode-skills`; missing ones fetched from the network on demand).
+
 ## Build order (matters)
 1. Parse manifest (deep-merge with `defaults/amxbuild.defaults.yml`)
 2. Fetch compiler (`amxxpc`, auto-resolves latest version)
@@ -65,7 +70,7 @@ Entry: `index.js` (CLI via `commander`). Action: `action-entry.js` → synthesis
 ```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
+node scripts/smoke.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.
@@ -109,3 +114,8 @@ This is automated in `.github/workflows/release.yml` on `v*.*.*` tags.
 ## 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.
+
+## AI skill: migration (`skills/`)
+- `skills/amxb-migration/SKILL.md` is a standalone agent skill for migrating existing AMXX projects onto amxb. It ships in the npm package (`files` includes `skills/`) and is referenced by direct raw URL from the README.
+- The skill MUST stay self-contained: it may reference only public docs/URLs and amxb CLI behavior, never local repo files (`templates/`, `defaults/`, `src/`, …) — it runs inside third-party projects before amxb is installed.
+- It can bootstrap amxb itself (step 0: global install via npm/install scripts or `npx --yes amxx-builder@latest`). When changing the CLI surface (commands, flags, manifest fields), keep this file in sync.

package/README.md

@@ -56,6 +56,10 @@ $env:AMXB_VERSION="v1.2.3"; irm https://raw.githubusercontent.com/AmxxModularEco
 
 Требования: **Node.js 18+**. git не требуется для установки и сборки — нужен только если манифест использует `github.ssh: true` (приватные репозитории по SSH-ключам).
 
+**Visual Studio Code**
+
+Расширение для VSCode - [AMXB — AMX Mod X Builder](https://marketplace.visualstudio.com/items?itemName=amxx-modular-ecosystem.amxb-vscode).
+
 ## Использование
 
 ```bash
@@ -76,10 +80,15 @@ 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 init --opencode                # + создать .opencode/ (opencode.json с MCP-конфигом + мост скиллов)
+amxb init --force                   # перезаписать существующие файлы (по умолчанию пропускаются)
+amxb init --force --with-manifest   # + перезаписать и существующий amxbuild.yml (без --with-manifest манифест не трогается)
 
 amxb clean                          # очистить build/ и кэш клонов
 amxb clean --all                    # + кэш компилятора
 amxb cache info                     # показать содержимое кэша
+
+amxb opencode-skills                # пути к материализованным скиллам (bundled + проект + deps/repos) для моста opencode
 ```
 
 Кэш хранится в `%LOCALAPPDATA%\amxx-builder` (Windows) или `~/.cache/amxx-builder` (Unix).  
@@ -241,6 +250,8 @@ AMXB_DEPLOY_RCON_CMD=amxx load {plugin}
 deploy:
   path: /home/user/hlds/cstrike    # корень сервера (где лежат addons/, models/)
   amxmodx_path: addons/amxmodx     # default: addons/amxmodx
+  assets_path: ""                  # default: "" = корень deploy.path (assets/models, assets/sound → models/, sound/)
+                                   # Задайте, например, "{name}", чтобы зеркалировать layout архива
   watch_debounce_ms: 500           # мс стабильности файла перед ребилдом (default: 500)
   exclude:                         # пути от deploy.path, которые не перезаписываются
     - addons/amxmodx/configs/      # сохранить конфиги сервера
@@ -252,6 +263,13 @@ deploy:
     command: "amxx load {plugin}"  # {plugin} = имя без .amxx; пусто = не слать
 ```
 
+> **Деплой аддитивен.** `amxb deploy` только копирует файлы из `build/` в `deploy.path` и
+> никогда не удаляет на сервере то, чего нет в источнике — на сервере могут жить и другие
+> плагины/файлы, не управляемые этим манифестом. Удаление с сервера происходит только в
+> watch-режиме для файлов, удалённых локально во время слежения. Если нужно «вычистить»
+> осиротевшие файлы (например, после переименования плагина) — удалите их вручную или
+> очистите каталог перед `amxb deploy`.
+
 `amxb watch` отслеживает изменения в `amxmodx/` и `assets/`:
 
 - `.sma` → пересобрать плагин, задеплоить `.amxx`, послать RCON
@@ -332,7 +350,7 @@ name: CI
 
 on:
   push:
-    branches: [master, feature/**, fix/**]
+    branches: [master, main, feature/**, fix/**]
     paths-ignore:
       - "**.md"
   pull_request:
@@ -445,6 +463,34 @@ repos:
     ref: latest   # автоматически берёт тег последнего GitHub release
 ```
 
+## deps: fungun.net
+
+[fungun.net](https://fungun.net) — магазин закрытых AMXX-плагинов. Архивов и
+GitHub-репозиториев у плагинов нет, но файлы `.inc` публично видны на странице
+плагина без покупки. Указать такой инклюд как зависимость можно полной формой
+записи `deps` через `source: fungun` — id плагина из ссылки магазина
+(`.../?p=show&id=106` → `106`), либо сразу полную ссылку на страницу:
+
+```yaml
+deps:
+  # id плагина из адреса страницы магазина
+  - source: fungun
+    id: 106
+
+  # или полная ссылка на страницу плагина
+  - source: fungun
+    url: https://fungun.net/shop/?p=show&id=106
+```
+
+amxb открывает страницу, находит модалку с файлом `.inc` и кладёт его в
+`build/_includes/`. Страница кэшируется в `<cache>/fungun/<id>/` на сутки: раз в
+день кэш устаревает и перечитывается, чтобы подхватывать обновления `.inc` у
+продавца (в отличие от git/release-кэшей, которые неизменяемы — у fungun нет
+версии, которую можно запинить). `--no-fetch` использует кэш как есть, а если
+очередное обновление страницы не удалось — сборка продолжается на прошлой
+рабочей копии. Если на странице плагина нет `.inc` вовсе — сборка остановится
+с понятной ошибкой.
+
 ## Полный пример
 
 Все доступные опции: [`example/amxbuild.yml`](example/amxbuild.yml).
@@ -467,8 +513,116 @@ MCP сервер предоставляет агенту opencode информа
 }
 ```
 
-**Все 11 инструментов** — от просмотра `.inc` файлов до построения дерева зависимостей —
-описаны в [`docs/mcp/INDEX.md`](docs/mcp/INDEX.md) с таблицей и ссылками на полную документацию каждого инструмента.
+Автоматически это настраивается командой `amxb init --opencode`: она создаёт
+`.opencode/opencode.json` с этим MCP-конфигом и файл `.opencode/plugin/amxb-skills.js`,
+тонкий мост, который при каждом старте opencode регистрирует скиллы из трёх источников:
+собственные bundled-скиллы сборщика (`amxb skills-dir`), скиллы текущего проекта из его
+`amxbuild.yml` (`skills:`) и скиллы всех `deps`/`repos`, прочитанные из их манифестов
+(`amxb opencode-skills`; отсутствующие зависимости докачиваются из сети по требованию).
+Абсолютных путей в `opencode.json` нет. Повторный запуск пропускает существующие файлы
+(мержит конфиг), `--force` перезаписывает.
+
+> Существующие файлы `.opencode/plugin/amxb-skills.js` автоматически не обновляются:
+> чтобы получить версию с тремя источниками, пересоздайте плагин командой
+> `amxb init --opencode --force` (или создайте файл заново).
+
+**23 инструмента** — от просмотра `.inc` файлов до построения дерева зависимостей —
+доступны через MCP. Каталог задокументированных инструментов (включая агент-доки и
+скиллы) — в [`docs/mcp/INDEX.md`](docs/mcp/INDEX.md).
+
+Агент-доки и скиллы теперь объявляются в самом манифесте: верхнеуровневые `docs:`
+(справочная документация) и `skills:` (инструкции для агента). Они предназначены
+**только агенту** — не попадают в `build/` и архив, и ничего не отдаётся по умолчанию,
+пока автор не объявил запись явно. Пять инструментов обслуживают их: `get_dep_manifest`
+возвращает сырой `amxbuild.yml` зависимости вместе со сводкой её `docs:`/`skills:`;
+`list_agent_docs` / `get_agent_docs` и `list_agent_skills` / `get_agent_skills` читают
+объявления как текущего проекта, так и зависимости (`dep`/`repo`). Содержимое,
+полученное из зависимости, считается предоставленным её автором и непроверенным:
+источник правды по API — `.inc` файлы. Подробнее — в
+[`docs/mcp/INDEX.md`](docs/mcp/INDEX.md).
+
+```yaml
+docs:
+  - file: docs/API.md            # путь внутри репо
+    name: API                     # по умолчанию — имя файла без расширения
+    description: Публичный API плагина
+skills:
+  - file: skills/config.md        # одиночный скилл-файл
+    name: config
+  - dir: skills/deep-config       # скилл-папка (SKILL.md + references)
+    name: deep-config
+```
+
+## Скилл миграции для ИИ-агентов
+
+Для проектов, которые ещё не используют amxb, есть готовый скилл **amxb-migration**:
+он переводит репозиторий AMXX-плагинов на `amxbuild.yml`, подключает `deps`,
+настраивает `.gitignore` / CI / MCP и заменяет старые скрипты сборки.
+
+В проекте, созданном через `amxb init --opencode`, скиллы amxb (включая
+`amxb-migration`) подхватываются opencode автоматически: мост-плагин
+`.opencode/plugin/amxb-skills.js` при каждом старте регистрирует не только
+bundled-скиллы сборщика, но и скиллы текущего проекта и его `deps`/`repos`.
+
+Канонический файл скилла (можно подключать по прямой ссылке до установки самого amxb —
+шаг 0 скилла ставит amxb при необходимости):
+
+- `skills/amxb-migration/SKILL.md` в этом репозитории
+- Прямая ссылка: <https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/skills/amxb-migration/SKILL.md>
+
+### Использование без установки (по ссылке)
+
+Установка нужна только для **авто-подхвата** скилла (агент сам находит его по
+`description` в frontmatter) и для работы **без доступа в сеть**. Но скилл —
+это просто самодостаточный markdown: агенту достаточно явно дать ссылку на
+файл, и он сам прочитает инструкции и будет им следовать.
+
+Пример промпта агенту (opencode, Claude Code и т.п.):
+
+> Мигрируй проект на amxb. Прочитай и следуй: https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/skills/amxb-migration/SKILL.md
+
+Условия работоспособности этого способа:
+
+- у агента есть доступ в сеть (разрешён `webfetch` / `curl`); в песочнице
+  без сети остаётся только установка или вставка текста файла в промпт;
+- давать **raw-ссылку** (`raw.githubusercontent.com`), а не страницу
+  репозитория — иначе агент получит HTML-обёртку GitHub;
+- скилл надо явно упоминать в каждом запросе — авто-триггер по описанию
+  работает только у установленного скилла;
+- файл должен быть запушен в `master` (пока правки не в репозитории,
+  ссылка вернёт 404).
+
+Для разовой миграции достаточно ссылки. Для регулярного использования —
+установите скилл один раз глобально, дальше он будет подхватываться сам.
+
+### Установка в сторонний проект
+
+**opencode** (в проект):
+
+```bash
+mkdir -p .opencode/skills/amxb-migration
+curl -fsSL https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/skills/amxb-migration/SKILL.md \
+  -o .opencode/skills/amxb-migration/SKILL.md
+```
+
+**opencode** (глобально, во все проекты):
+
+```bash
+mkdir -p ~/.config/opencode/skills/amxb-migration
+curl -fsSL https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/skills/amxb-migration/SKILL.md \
+  -o ~/.config/opencode/skills/amxb-migration/SKILL.md
+```
+
+**Claude Code** (в проект или глобально):
+
+```bash
+mkdir -p .claude/skills/amxb-migration      # или ~/.claude/skills/amxb-migration
+curl -fsSL https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/master/skills/amxb-migration/SKILL.md \
+  -o .claude/skills/amxb-migration/SKILL.md
+```
+
+После установки перезапустите агента, чтобы скилл подхватился. Скилл сам подскажет
+установку amxb, если тот ещё не установлен в окружении.
 
 ## Приоритеты
 

package/defaults/amxbuild.defaults.yml

@@ -27,6 +27,9 @@ output:
 
 plugins: []
 
+docs: []
+skills: []
+
 assets:
   on_conflict: last_wins
   sources:
@@ -34,6 +37,10 @@ assets:
 
 deploy:
   amxmodx_path: addons/amxmodx
+  # Empty assets path = deploy root (server root), matching the schema default:
+  # local assets/ land where the game reads them, NOT under a {name}/ subfolder
+  # (output.assets_path '{name}' only shapes the distribution archive).
+  assets_path: ""
   watch_debounce_ms: 500
   exclude: []
   rcon: