amxx-builder 1.6.0 → 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.
@@ -40,9 +40,13 @@ Entry: `index.js` (CLI via `commander`). Action: `action-entry.js` → synthesis
 | `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)
@@ -66,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.

package/README.md

@@ -80,11 +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).  
@@ -246,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/      # сохранить конфиги сервера
@@ -257,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
@@ -500,9 +513,45 @@ MCP сервер предоставляет агенту opencode информа
 }
 ```
 
-**Все 13 инструментов** — от просмотра `.inc` файлов до построения дерева зависимостей —
-описаны в [`docs/mcp/INDEX.md`](docs/mcp/INDEX.md) с таблицей и ссылками на полную документацию каждого инструмента.
-Плюс `get_dep_docs` / `list_dep_docs` — агент-доки, которые автор зависимости может приложить через поле `docs` у зависимости (или файлы `docs/API.md` / `API.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
+```
 
 ## Скилл миграции для ИИ-агентов
 
@@ -510,6 +559,11 @@ MCP сервер предоставляет агенту opencode информа
 он переводит репозиторий 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 при необходимости):
 

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: