amxx-builder 1.6.1 → 1.7.0

package/mcp/registry.js

@@ -135,7 +135,7 @@ const TOOLS = [
             'into sub-dependencies. Detects cycles and handles deps_override.\n\n' +
             'Provide either "manifest" (path to amxbuild.yml) or "deps" (array of dep entries).\n\n' +
             'Each dep entry can be a string ("owner/repo@ref") or an object ' +
-            '({ repo, ref, source?, include_path?, asset? }).',
+            '({ repo, ref, source?, include_path?, asset?, ref_ttl? }).',
           inputSchema: {
             type: 'object',
             properties: {
@@ -161,6 +161,13 @@ const TOOLS = [
                         source: { type: 'string', enum: ['git', 'release'] },
                         include_path: { type: 'string' },
                         asset: { oneOf: [{ type: 'string' }, { type: 'number' }] },
+                        ref_ttl: {
+                          description:
+                            'TTL of the cached ref→SHA resolution for git deps: "never", a duration ' +
+                            'like "30m"/"1h"/"7d", or an integer number of seconds. Default: tags ' +
+                            'cached forever, branches 1h.',
+                          oneOf: [{ type: 'string' }, { type: 'integer' }],
+                        },
                       },
                       required: ['repo', 'ref'],
                     },
@@ -582,6 +589,12 @@ const TOOLS = [
               asset: {
                 description: 'For source=release: asset selector (glob pattern or index).',
               },
+              ref_ttl: {
+                oneOf: [{ type: 'string' }, { type: 'integer' }],
+                description:
+                  'TTL of the cached ref→SHA resolution for git deps: "never", a duration like ' +
+                  '"30m"/"1h"/"7d", or an integer number of seconds. Default: tags cached forever, branches 1h.',
+              },
               pattern: {
                 type: 'string',
                 description: 'Glob pattern, e.g. "**/*.sma", "amxmodx/**", "**/*".',
@@ -640,6 +653,12 @@ const TOOLS = [
               asset: {
                 description: 'For source=release: asset selector (glob pattern or index).',
               },
+              ref_ttl: {
+                oneOf: [{ type: 'string' }, { type: 'integer' }],
+                description:
+                  'TTL of the cached ref→SHA resolution for git deps: "never", a duration like ' +
+                  '"30m"/"1h"/"7d", or an integer number of seconds. Default: tags cached forever, branches 1h.',
+              },
               file: {
                 type: 'string',
                 description: 'Relative path inside the repo/asset root, e.g. "amxmodx/scripting/my_plugin.sma".',
@@ -709,6 +728,12 @@ const TOOLS = [
               asset: {
                 description: 'For source=release: asset selector (glob pattern or index).',
               },
+              ref_ttl: {
+                oneOf: [{ type: 'string' }, { type: 'integer' }],
+                description:
+                  'TTL of the cached ref→SHA resolution for git deps: "never", a duration like ' +
+                  '"30m"/"1h"/"7d", or an integer number of seconds. Default: tags cached forever, branches 1h.',
+              },
               token: {
                 type: 'string',
                 description: 'GitHub PAT override. Defaults to GITHUB_TOKEN env.',
@@ -759,6 +784,12 @@ const TOOLS = [
               asset: {
                 description: 'For source=release: asset selector (glob pattern or index).',
               },
+              ref_ttl: {
+                oneOf: [{ type: 'string' }, { type: 'integer' }],
+                description:
+                  'TTL of the cached ref→SHA resolution for git deps: "never", a duration like ' +
+                  '"30m"/"1h"/"7d", or an integer number of seconds. Default: tags cached forever, branches 1h.',
+              },
               manifest: {
                 type: 'string',
                 description: 'Local mode: path to amxbuild.yml. Auto-detected in cwd when no dep/repo is given.',
@@ -814,6 +845,12 @@ const TOOLS = [
               asset: {
                 description: 'For source=release: asset selector (glob pattern or index).',
               },
+              ref_ttl: {
+                oneOf: [{ type: 'string' }, { type: 'integer' }],
+                description:
+                  'TTL of the cached ref→SHA resolution for git deps: "never", a duration like ' +
+                  '"30m"/"1h"/"7d", or an integer number of seconds. Default: tags cached forever, branches 1h.',
+              },
               manifest: {
                 type: 'string',
                 description: 'Local mode: path to amxbuild.yml. Auto-detected in cwd when no dep/repo is given.',
@@ -894,6 +931,12 @@ const TOOLS = [
               asset: {
                 description: 'For source=release: asset selector (glob pattern or index).',
               },
+              ref_ttl: {
+                oneOf: [{ type: 'string' }, { type: 'integer' }],
+                description:
+                  'TTL of the cached ref→SHA resolution for git deps: "never", a duration like ' +
+                  '"30m"/"1h"/"7d", or an integer number of seconds. Default: tags cached forever, branches 1h.',
+              },
               manifest: {
                 type: 'string',
                 description: 'Local mode: path to amxbuild.yml. Auto-detected in cwd when no dep/repo is given.',
@@ -949,6 +992,12 @@ const TOOLS = [
               asset: {
                 description: 'For source=release: asset selector (glob pattern or index).',
               },
+              ref_ttl: {
+                oneOf: [{ type: 'string' }, { type: 'integer' }],
+                description:
+                  'TTL of the cached ref→SHA resolution for git deps: "never", a duration like ' +
+                  '"30m"/"1h"/"7d", or an integer number of seconds. Default: tags cached forever, branches 1h.',
+              },
               manifest: {
                 type: 'string',
                 description: 'Local mode: path to amxbuild.yml. Auto-detected in cwd when no dep/repo is given.',
@@ -976,7 +1025,17 @@ const TOOLS = [
             'Run amxxpc on a local .sma file without a full build and return the compiler output ' +
             '(status, errors, warnings). Resolves the compiler version and include dirs ' +
             '(stdlib + manifest deps) the same way a real build would. ' +
-            'Use it to iterate on code until it compiles clean.',
+            'Use it to iterate on code until it compiles clean.\n\n' +
+            'WSL / Windows-mounted paths: amxxpc is a 32-bit Linux binary and cannot READ ' +
+            'files on WSL DrvFs/9p mounts (e.g. /mnt/c, /mnt/d, /mnt/j). If sma_file — or any ' +
+            'include dir — lives under /mnt/*, compilation fails with "fatal error 100: ' +
+            'cannot read from file" (a directory used as an include path can abort it with ' +
+            'std::bad_alloc / SIGABRT), even though the file exists and Node can read it. ' +
+            'Writing output to /mnt/* is fine; only reads fail. This is an environment ' +
+            'limitation, not a code error. Alternative: compile from the Linux-native ' +
+            'filesystem — copy the .sma and its local include/ dir to e.g. ~/proj/ (the ' +
+            '~/.cache/amxx-builder cache is shared, nothing re-downloads) and pass that path, ' +
+            'or run the build on Windows.',
           inputSchema: {
             type: 'object',
             properties: {
@@ -1093,6 +1152,13 @@ const TOOLS = [
                         source: { type: 'string', enum: ['git', 'release'] },
                         include_path: { type: 'string' },
                         asset: { oneOf: [{ type: 'string' }, { type: 'number' }] },
+                        ref_ttl: {
+                          description:
+                            'TTL of the cached ref→SHA resolution for git deps: "never", a duration ' +
+                            'like "30m"/"1h"/"7d", or an integer number of seconds. Default: tags ' +
+                            'cached forever, branches 1h.',
+                          oneOf: [{ type: 'string' }, { type: 'integer' }],
+                        },
                       },
                       required: ['repo', 'ref'],
                     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amxx-builder",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "author": {
     "name": "ArKaNeMaN"
   },

package/skills/amxb-migration/SKILL.md

@@ -244,6 +244,13 @@ deps:
   - Owner/Repo@tag
   - Owner/Repo@tag:нестандартный/путь/до/include
 
+  # git-репо полной формой: ref_ttl задаёт TTL кэша резолва ref → SHA
+  # (never | 30m | 1h | 7d | целое число секунд; дефолт: тег — вечно,
+  # ветка/default branch — 1ч). Строковая форма выше ref_ttl не принимает.
+  # - repo: Owner/Repo
+  #   ref: main
+  #   ref_ttl: 30m
+
   # модуль из release-архива; ref: latest резолвится в последний релиз,
   # но в манифест пишем конкретный тег (см. «Выбор версии» ниже)
   - repo: Owner/Repo
@@ -257,8 +264,42 @@ deps:
     id: 106
 ```
 
-Источников у deps три: `git` (по умолчанию), `release` (GitHub release-архив)
-и `fungun` (публичный `.inc` со страницы закрытого плагина на fungun.net).
+Источников у deps четыре: `git` (по умолчанию), `release` (GitHub release-архив),
+`fungun` (публичный `.inc` со страницы закрытого плагина на fungun.net) и
+`local` (папка рядом с манифестом, см. ниже).
+
+### Локальные источники (`source: local`)
+
+Репозиторий или зависимость можно взять не с GitHub, а из локальной папки. Удобно
+для интеграционной сборки вместе с соседним чекаутом.
+
+```yaml
+# зависимость: только .inc для компиляции (объект, строковая форма не поддерживается)
+deps:
+  - source: local
+    path: ../Shared            # относительно папки манифеста (или абсолютный)
+    name: shared               # необязательно, id = local/<name>
+    include_path: scripting/include   # необязательно
+
+# репозиторий: часть сборки, его .sma тоже компилируются
+repos:
+  - source: local
+    path: ../ProjectA
+    name: projecta
+```
+
+`path` обязателен, `name` и `include_path` необязательны. Уже объявленную запись
+можно временно перенаправить на локальную папку без правки манифеста переменной
+`AMXB_LOCAL_SOURCES` по её id `owner/repo`:
+
+```bash
+AMXB_LOCAL_SOURCES='Org/Repo=../Repo' amxb build
+```
+
+Значение: пары `id=path` через `;` или перевод строки, либо JSON-объект
+`{"id":"path"}`. Редирект можно держать в `.env` (он в `.gitignore`). Локальные
+источники не версионируются (рабочее дерево читается как есть), поэтому подходят
+для разработки и интеграции, а не для релизной сборки.
 
 **Что даёт `deps:` и чего не даёт.** `deps:` — это **только заголовочные
 файлы (`.inc`) для компиляции**. amxb **не компилирует и не упаковывает**
@@ -312,7 +353,8 @@ deps:
    #   archive → /abs/path/./{name}.zip
    #   amxmodx path in archive: {name}/addons/amxmodx/
    #   assets path: {name}/
-   #   generate_ini: false  |  on_conflict: last_wins
+   #   plugins ini: enabled  |  default: plugins-core.ini  |  debug: false
+   #   on_conflict: last_wins
    ```
    Вопросы пользователю про структуру задаём **только если** фактическая
    раскладка отличается от дефолтной и это принципиально (серверная сборка,
@@ -347,23 +389,48 @@ deps:
    deps:
      - Owner/Repo@tag
 
-   # plugins-*.ini: по умолчанию НЕ генерируется (generate_ini: false).
-   # Если старой сборке ini не нужен — ничего добавлять не надо.
-   # Если нужен (как в старой сборке) — включить генерацию и постфикс:
-   # plugins_ini_postfix: core        # → plugins-core.ini
-   # output:
-   #   generate_ini: true
+   # INI плагинов (plugins-*.ini) по умолчанию НЕ генерируется: пока нигде
+   # не задано значение ini, файлов нет. Если старой сборке ini не нужен —
+   # ничего добавлять не надо. Если нужен (как в старой сборке) — одна секция:
+   # plugins:
+   #   defaults:
+   #     ini: core           # → plugins-core.ini для всех плагинов
    ```
-6. **Правила `plugins:`** — фильтрация локальных плагинов (к репо-плагинам
-   не применяются). Первое совпадение побеждает. Например, исключить из
-   сборки тестовые/легаси `.sma`:
+6. **Секция `plugins`** — единая настройка INI. `defaults` применяется ко
+   **всем** плагинам (локальным и из репо) как базовый слой; `rules` —
+   glob-правила **только для локальных** `.sma` (`amxmodx/scripting/`),
+   первое совпадение побеждает. Например, исключить тестовые/легаси исходники
+   и развести остальные по INI:
    ```yaml
    plugins:
-     - match: "*Test*.sma"
-       enabled: false
-     - match: "utils/*.sma"
-       ini: false          # компилировать, но не включать ни в один INI
+     defaults:
+       ini: core           # базовый INI → plugins-core.ini
+       debug: false        # true → к строке плагина добавляется " debug"
+     rules:
+       - match: "*Test*.sma"
+         enabled: false    # полностью пропустить (не компилировать, не деплоить)
+       - match: "utils/*.sma"
+         ini: false        # компилировать, но не включать ни в один INI
+       - match: "VipM/*.sma"
+         ini: vipm         # → plugins-vipm.ini
+         debug: true
+   ```
+   Значения `ini`: `false` — не включать в INI; `true` или `""` — `plugins.ini`;
+   `"<postfix>"` — `plugins-<postfix>.ini`. Приоритет:
+   `rules` → `repos[].plugins` → `plugins.defaults` → выключено. У плагинов из
+   `repos:` INI настраивается на самом репо:
+   ```yaml
+   repos:
+     - repo: Owner/Repo
+       plugins:
+         ini: vip          # → plugins-vip.ini
+         debug: false
    ```
+   Генерация INI включается автоматически, как только любое эффективное `ini`
+   не `false`. Старая форма `plugins:` — массив правил без `defaults` — ещё
+   принимается; поля `output.generate_ini`, `plugins_ini_postfix` и
+   `repos[].plugins_ini_postfix` устарели (продолжают работать, но пишут
+   предупреждение при сборке).
 7. Помнить особенности amxb:
    - локальная папка `amxmodx/` всегда выигрывает у файлов из репо
      (намеренный слой переопределения, предупреждений нет);
@@ -375,7 +442,13 @@ deps:
      (файлы) и `skills:` (одиночный файл либо папка с `SKILL.md` +
      справочниками): они читаются агентом через MCP/serve и **не попадают**
      в `build/` и архив, а по умолчанию не отдаётся ничего — только явно
-     объявленные записи.
+     объявленные записи;
+   - `ref_ttl` (только git-записи `repos`/`deps` в объектной форме) задаёт TTL
+     кэша резолва `ref → SHA`: `never` / `30m` / `1h` / `7d` / целое число
+     секунд. По умолчанию тег кэшируется вечно, ветка (и default branch)
+     перепроверяется раз в час; контент ключуется по SHA, поэтому неизменённый
+     SHA не перекачивается. На `source: release`/`fungun`/`local`,
+     `ref: latest` и пустой `ref` поле не действует.
 
 ## Шаг 5. Приватные репозитории
 
@@ -434,7 +507,8 @@ plugins-*.ini
 # инструменты / редактор
 .omo/
 .codegraph/
-.vscode/
+.vscode/*
+!.vscode/extensions.json
 .claude/
 node_modules/
 ```
@@ -450,6 +524,13 @@ node_modules/
   `amxb build`) — только если файлов ещё нет. Если `build.bat`/`build.sh`
   уже существуют — **заменяем их вручную** тонкими (init их не тронет без
   `--force`).
+- `amxb init --vscode` (алиас `--vsc` — сокращение, не отдельный флаг)
+  создаёт `.vscode/extensions.json` с рекомендациями расширений
+  (`Faktor.amxx-pawn-all-in`, `amxx-modular-ecosystem.amxb-vscode`).
+  Существующий файл **не перезаписывается**: рекомендации проекта
+  сохраняются, недостающие amxb-расширения добавляются. Файл коммитим
+  (`extensions.json` — единственный отслеживаемый файл в `.vscode/`,
+  см. Шаг 6).
 - Старые скрипты сборки (`config.bat`, `build-debug.bat`,
   `build-release.bat`, `.build-config`, `deps.txt` после переноса данных в
   манифест, старые `*.zip`, `.build/`) — удаляем.
@@ -526,13 +607,17 @@ amxb build             # полная сборка
   2. файл **не пустой** — пустой `.sma` (0 байт) даёт ровно ту же ошибку.
      Пустые `.sma` не должны попадать в сборку: `amxb init --plugin` создаёт
      пустую заготовку, и если она осталась в `scripting/` — это ложный след.
-     Такие файлы удаляем или исключаем (`plugins:` → `enabled: false`).
+     Такие файлы удаляем или исключаем (`plugins.rules:` → `enabled: false`).
   3. Если файлы на месте и непустые, а ошибка **для всех** файлов при верных
      путях → проблема окружения, не манифеста (например, WSL: amxxpc
-     32-битный и не читает `/mnt/c`).
-- **WSL (`/mnt/c`) — готовый рецепт полной проверки.** В WSL из `/mnt/c`
+     32-битный и не читает `/mnt/*` — DrvFs/9p — хотя Node/bash файл видят;
+     локальная папка `include/` на `/mnt/*` даёт вместо этого
+     `std::bad_alloc`/SIGABRT).
+- **WSL (`/mnt/*`) — готовый рецепт полной проверки.** В WSL из `/mnt/*`
   работают `validate`, `deps-tree`, `--dry-run` (компилятор не запускается),
-  но полный `amxb build` падает на 32-битном amxxpc. Полную сборку выполняем
+  но полный `amxb build` падает на 32-битном amxxpc (не читает исходники;
+  запись `.amxx` на `/mnt/*`, наоборот, работает). Плагины из `repos` не
+  страдают — их исходники amxb кладёт в нативный кэш. Полную сборку выполняем
   из нативной Linux-папки — кэш общий, повторно ничего не качается:
   ```bash
   mkdir -p ~/amxb-build-check && cp -r amxmodx assets amxbuild.yml README.md ~/amxb-build-check/
@@ -556,7 +641,7 @@ amxb build             # полная сборка
 - [ ] Внешние include сопоставлены с источниками; не найденные после разбора CI/скриптов — согласованы с пользователем
 - [ ] При «репо не найден» (404): сначала проверены токены из `.env`, затем у пользователя запрошен токен/уточнение имени — вывод «репо не существует» без подтверждения не делался
 - [ ] Дефолтная раскладка проверена `amxb build --dry-run`; вопросы про структуру — только при отличии от дефолта
-- [ ] `amxbuild.yml`: name, deps, ini/постфикс при необходимости; `amxmodx.version` не указан (последний компилятор), кроме AMXX <= 1.8.3
+- [ ] `amxbuild.yml`: name, deps, INI (`plugins.defaults` / `plugins.rules`, при необходимости); `amxmodx.version` не указан (последний компилятор), кроме AMXX <= 1.8.3
 - [ ] Версии deps: последняя проверена сборкой → иначе версия из проекта/CI → иначе вопрос; в манифесте конкретные теги, не «latest»
 - [ ] Приватные deps: 404 обработан как «приватный/опечатка» → `github.tokens` + `.env` (в .gitignore)
 - [ ] `.gitignore`: шаблон amxb + сохранены специфичные строки проекта