amxx-builder 1.6.1 → 1.7.1

package/AGENTS.md

@@ -21,6 +21,7 @@ Entry: `index.js` (CLI via `commander`). Action: `action-entry.js` → synthesis
   - 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`)
+  - Local sources — `source: local` resolution and `AMXB_LOCAL_SOURCES` env-override parsing, `_localDir` resolution, `_resolvedRef = 'local'` stamping, `ensureRepoDir` — single source: `src/local-sources.js` (`applyLocalOverrides`, `parseLocalSourcesEnv`, `ensureRepoDir`)
 - 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
@@ -37,6 +38,7 @@ Entry: `index.js` (CLI via `commander`). Action: `action-entry.js` → synthesis
 | `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 init --vscode` | Also create `.vscode/extensions.json` with recommended extensions (alias `--vsc`; merges into an existing file) |
 | `amxb clean` | Clean build/ and clone cache |
 | `amxb clean --all` | Also clean compiler cache |
 | `amxb cache info` | Show cache contents |
@@ -62,9 +64,12 @@ The opencode bridge plugin (`.opencode/plugin/amxb-skills.js`, generated by `amx
 - **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.
+- `ref_ttl` (optional, git `repos[]`/`deps[]` objects only) sets the TTL of the `ref → SHA` resolution cache: `never`, a duration (`30m`/`1h`/`7d`), or an integer number of seconds. Default: a named ref GitHub confirms as a **tag** is cached forever; a branch (including the default branch when no `ref` is given) revalidates after 1 hour. When a ref name exists as both a tag and a branch, the tag wins and the ref is cached as immutable. Because clones are SHA-keyed, an unchanged SHA is never re-downloaded; a force-pushed tag is only picked up via an explicit `ref_ttl` or `amxb clean`. It does not affect `source: release`/`fungun`/`local`, `latest`, or `null` refs, and the string dep form / `DEPS_LIST` cannot express it.
+- Plugin rules (`plugins.rules:`) apply **only to local** `.sma` files, not repo plugins; `plugins.defaults` and `repos[].plugins` apply to all plugins. An effective non-`false` `ini` enables INI generation.
 - 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.
+- `amxmodx.exclude_files` (array of glob patterns, default `[]`, relative to the local `amxmodx.dir`) keeps matching files from the project's own local `amxmodx/` out of `build/amxmodx/` and the archive. It does not touch `repos:` files (those use per-repo `exclude_files`) and does not stop compilation of local `.sma` (use `plugins.rules[].enabled: false` for that); watch ignores excluded local files. Distinct from `deploy.exclude`, which protects server files from being overwritten during deploy/watch.
+- `repos:`/`deps:` entries can be satisfied by a **local directory** instead of GitHub: `source: local` + `path` (relative to the manifest dir, or absolute; optional `name` gives the synthetic id `local/<name>`, defaulting to the path basename). A local repo is collected + its `.sma` compiled and may still set `amxmodx_dir` / `plugins` / `exclude` / `exclude_files` / `deps_override` (`repo`/`ref` forbidden; the deprecated `plugins_ini_postfix` is still accepted with a build warning); a local dep contributes `.inc` to `build/_includes/` (`repo`/`ref`/`id`/`url`/`asset` forbidden; object form only, the `owner/repo@ref[:include_path]` string stays git-only). Local sources are unpinned (the working tree is read as-is) so builds are not reproducible, and watch does not follow dirs outside the manifest's `amxmodx/`/`assets/`.
 
 ## GitHub Action release flow
 ```bash
@@ -101,6 +106,8 @@ This is automated in `.github/workflows/release.yml` on `v*.*.*` tags.
 ## Cache
 - Win: `%LOCALAPPDATA%\amxx-builder`, Unix: `~/.cache/amxx-builder`
 - Override: `AMXX_BUILDER_CACHE`
+- Local source redirects: `AMXB_LOCAL_SOURCES` maps an existing repo/dep id (`owner/repo`) to a path (pairs `id=path` separated by `;`/newlines, or a JSON object), `AMXB_LOCAL_STRICT=1` makes an unmatched id an error (default: warn and ignore). `.env` next to the manifest is honored — see `src/local-sources.js`.
+- Plugin INI debug override: `AMXB_PLUGINS_DEBUG` (read from `.env` next to the manifest, local only — `.env` is gitignored) forces the ` debug` suffix in generated `plugins-*.ini` on/off for every included plugin. `1`/`true`/`yes`/`on` force on, `0`/`false`/`no`/`off` force off, anything else (unset/empty) leaves the manifest in charge. Case-insensitive. Precedence: `AMXB_PLUGINS_DEBUG` > per-rule/per-repo `debug` > `plugins.defaults.debug`; it only affects plugins already in an INI and never enables INI generation by itself.
 - Local per-manifest asset cache: `.amxb-cache/` next to `amxbuild.yml`
 - Separate dirs: `repos/`, `release-deps/`, `amxxpc/` (compiler binaries)
 

package/README.md

@@ -60,6 +60,11 @@ $env:AMXB_VERSION="v1.2.3"; irm https://raw.githubusercontent.com/AmxxModularEco
 
 Расширение для VSCode - [AMXB — AMX Mod X Builder](https://marketplace.visualstudio.com/items?itemName=amxx-modular-ecosystem.amxb-vscode).
 
+Команда `amxb init --vscode` создаёт `.vscode/extensions.json` с рекомендациями расширений
+для AMXX-проекта (`Faktor.amxx-pawn-all-in` + `amxx-modular-ecosystem.amxb-vscode`).
+Существующий файл не перезаписывается: рекомендации проекта сохраняются, недостающие
+добавляются.
+
 ## Использование
 
 ```bash
@@ -81,6 +86,7 @@ amxb init --plugin <name>           # + создать amxmodx/scripting/<name>.
 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 --vscode                  # + создать .vscode/extensions.json с рекомендациями расширений (алиас: --vsc)
 amxb init --force                   # перезаписать существующие файлы (по умолчанию пропускаются)
 amxb init --force --with-manifest   # + перезаписать и существующий amxbuild.yml (без --with-manifest манифест не трогается)
 
@@ -149,27 +155,97 @@ my-server/
       weapon.wav
 ```
 
-## Управление локальными плагинами
+### Исключение локальных файлов
 
-Поле `plugins:` позволяет фильтровать и распределять плагины из `amxmodx/scripting/` по INI-файлам. Применяется **только к локальным** плагинам; плагины из репо используют `plugins_ini_postfix` своего репо. Первое совпадение побеждает.
+Поле `amxmodx.exclude_files` задаёт массив glob-паттернов. Файлы локальной папки `amxmodx/`, попавшие под паттерн, не копируются в `build/amxmodx/` и не попадают в архив. По умолчанию значение пустое (`[]`), то есть копируется всё. Паттерны считаются от `amxmodx.dir` (по умолчанию `amxmodx`):
 
 ```yaml
-plugins_ini_postfix: myserver   # глобальный постфикс → plugins-myserver.ini
+amxmodx:
+  exclude_files:
+    - configs/*.cfg
+    - "**/*.ini"
+    - scripting/dev.sma
+```
+
+Поле действует только на собственную локальную папку `amxmodx/` рядом с манифестом. Файлов из `repos:` оно не касается. Для них исключение задаётся на самом репо через `repos[].exclude_files`. Компиляцию локальных `.sma` поле не отменяет. Чтобы полностью пропустить локальный плагин, используйте `plugins.rules[].enabled: false` (см. раздел про плагины). В watch-режиме изменения исключённых локальных файлов игнорируются, поэтому они не деплоятся.
+
+Не путайте с `deploy.exclude`. Это поле не даёт `amxb deploy` и `amxb watch` перезаписывать файлы сервера (например, существующие конфиги). А `amxmodx.exclude_files` просто не кладёт файлы в пакет.
+
+## Управление плагинами и INI
 
+Секция `plugins:` описывает, какие плагины попадают в INI-файлы, как эти файлы называются и добавлять ли к строке плагина ` debug`. Она состоит из двух частей:
+
+- `defaults:` — базовый слой, применяется ко **всем** плагинам (локальным и из репо);
+- `rules:` — glob-правила **только для локальных** `.sma` из `amxmodx/scripting/`; первое совпадение побеждает.
+
+```yaml
 plugins:
-  - match: "VipM/*.sma"
-    ini: vipm             # → plugins-vipm.ini
-  - match: "utils/*.sma"
-    ini: false            # компилировать, но не включать ни в один INI
-  - match: "wip/*.sma"
-    enabled: false        # полностью пропустить (не компилировать, не деплоить)
+  defaults:
+    ini: myserver        # базовый INI для всех плагинов → plugins-myserver.ini
+    debug: false         # true → к каждой строке добавляется " debug"
+  rules:
+    - match: "VipM/*.sma"
+      ini: vipm          # → plugins-vipm.ini (переопределяет defaults)
+      debug: true        # vip_core.amxx debug
+    - match: "utils/*.sma"
+      ini: false         # компилировать, но не включать ни в один INI
+    - match: "wip/*.sma"
+      enabled: false     # полностью пропустить (не компилировать, не деплоить)
 ```
 
-| Поле | По умолчанию | Описание |
-| --- | --- | --- |
-| `match` | — | Glob-паттерн относительно `scripting/` |
-| `enabled` | `true` | `false` — пропустить компиляцию и деплой |
-| `ini` | `plugins_ini_postfix` | Постфикс INI, `false` — не включать в INI |
+Плагины из репозитория настраиваются на самом репо:
+
+```yaml
+repos:
+  - repo: Org/VipModular
+    plugins:
+      ini: vip           # → plugins-vip.ini
+      debug: false
+```
+
+**Значения `ini`:**
+
+| Значение | Результат |
+| --- | --- |
+| `false` | Скомпилировать, но не включать ни в один INI |
+| `true` или `""` | Включить в `plugins.ini` |
+| `"<postfix>"` | Включить в `plugins-<postfix>.ini` |
+| не задано | Наследуется у более низкого слоя приоритета |
+
+**Поля:**
+
+| Поле | Где | По умолчанию | Описание |
+| --- | --- | --- | --- |
+| `defaults.ini` | `plugins` | — | Базовый INI для всех плагинов |
+| `defaults.debug` | `plugins` | `false` | `true` — к строке плагина добавляется ` debug` |
+| `rules[].match` | `plugins` | — | Glob-паттерн относительно `scripting/` |
+| `rules[].enabled` | `plugins` | `true` | `false` — пропустить компиляцию и деплой |
+| `rules[].ini` | `plugins` | `defaults.ini` | Значение `ini` для совпавших локальных плагинов |
+| `rules[].debug` | `plugins` | `defaults.debug` | `debug` для совпавших локальных плагинов |
+| `repos[].plugins.ini` | репо | `defaults.ini` | Значение `ini` для плагинов этого репо |
+| `repos[].plugins.debug` | репо | `defaults.debug` | `debug` для плагинов этого репо |
+
+**Приоритет:** `plugins.rules` → `repos[].plugins` → `plugins.defaults` → выключено (без INI). Правила `rules` действуют только на локальные плагины; `defaults` и `repos[].plugins` — на все.
+
+Генерация INI включается сама, как только любое эффективное значение `ini` не `false` (задано в `defaults`, в правиле или на репо). Если `defaults.ini` при этом не задан, а INI включён только правилом или репо, все остальные плагины попадают в `plugins.ini`. Если `ini` не задано нигде — INI-файлы не создаются.
+
+Старая форма `plugins:` — массив правил без `defaults` — ещё принимается. Поля `output.generate_ini`, верхнеуровневый `plugins_ini_postfix` и `repos[].plugins_ini_postfix` устарели: они продолжают работать, но при сборке пишут предупреждение. Используйте вместо них `plugins.defaults.ini` и `repos[].plugins`.
+
+### Локальное переключение `debug` через `.env`
+
+Рядом с манифестом можно положить `.env` (он в `.gitignore` и в репозиторий не попадает). Переменная `AMXB_PLUGINS_DEBUG` в этом файле принудительно включает или выключает суффикс ` debug` **у всех** плагинов в уже сгенерированных `plugins-*.ini`, независимо от манифеста:
+
+```env
+AMXB_PLUGINS_DEBUG=1
+```
+
+| Значение | Результат |
+| --- | --- |
+| `1` / `true` / `yes` / `on` | Принудительно добавить ` debug` каждому плагину в INI |
+| `0` / `false` / `no` / `off` | Принудительно убрать ` debug` |
+| пусто / не задано / другое | Без переопределения, решает манифест |
+
+Значения регистронезависимы. Приоритет: `AMXB_PLUGINS_DEBUG` → `plugins.rules[].debug` / `repos[].plugins.debug` → `plugins.defaults.debug`. Переменная действует только на плагины, которые и так попадают в INI, и **не** включает генерацию INI сама по себе. Удобно для локальной отладки: включите ` debug` в `.env`, не коммитя правку в общий манифест.
 
 ## Удалённые ассеты
 
@@ -304,6 +380,72 @@ github:
 
 Мапа применяется ко всему: репозитории из `repos:`, зависимости (`deps`/`DEPS_LIST`/`deps_override`), GitHub release-ассеты в `assets.sources` и команда `amxb deps-tree`. Для транзитивных зависимостей токен подбирается по владельцу автоматически.
 
+## Локальные источники (repos/deps)
+
+Запись в `repos:` или `deps:` можно взять не с GitHub, а из локальной папки. Содержимое читается как есть, как соседние `amxmodx/` и `assets/`: локальный репозиторий собирается вместе с проектом (его `.sma` компилируются), а локальная зависимость отдаёт свои `.inc` в `build/_includes/`.
+
+**Локальный репозиторий** (полноценная часть сборки):
+
+```yaml
+repos:
+  - source: local
+    path: ../ProjectA          # относительно папки манифеста (или абсолютный)
+    name: projecta             # необязательно; по умолчанию basename пути
+    # также поддерживаются amxmodx_dir, plugins (ini/debug),
+    # exclude, exclude_files, deps_override
+    # устаревший plugins_ini_postfix ещё принимается (с предупреждением)
+```
+
+`path` обязателен, `name` необязателен. Внутренний id такой записи: `local/<name>`, по умолчанию `local/<basename пути>`. Поля `repo` и `ref` указывать нельзя. `DEPS_LIST` и `deps_override` локального репо продолжают работать.
+
+**Локальная зависимость** (только `.inc` для компиляции):
+
+```yaml
+deps:
+  - source: local
+    path: ../Shared
+    name: shared                       # необязательно
+    include_path: scripting/include    # необязательно
+```
+
+`path` обязателен, `name` и `include_path` необязательны. Поля `repo`, `ref`, `id`, `url`, `asset` запрещены. Строковая форма `owner/repo@ref[:include_path]` остаётся только для git, локальный dep задаётся объектом.
+
+Все интерфейсы видят локальные источники одинаково: `amxb build`, `--dry-run`, `deps-tree`, `watch`, serve (`build.plan`) и MCP (`build_plan`, `get_dep_tree`, `validate_manifest`).
+
+### Интеграция проектов через AMXB_LOCAL_SOURCES
+
+Чтобы собрать проект B против локального чекаута проекта A (без релиза), манифест править не нужно. Переменная `AMXB_LOCAL_SOURCES` перенаправляет **уже объявленную** запись (`repos` или `deps`) на локальную папку по её логическому id `owner/repo` (регистр не важен). Новые записи она не создаёт.
+
+```bash
+# один источник
+AMXB_LOCAL_SOURCES='AmxxModularEcosystem/VipModular=../VipModular' amxb build
+
+# несколько: через ; или перевод строки
+AMXB_LOCAL_SOURCES=$'Org/A=../A\nOrg/B=/abs/B' amxb build
+
+# JSON-объект (значение начинается с {)
+AMXB_LOCAL_SOURCES='{"Org/A":"../A","Org/B":"/abs/B"}' amxb build
+```
+
+Пути считаются от папки манифеста (абсолютные тоже принимаются). Так как `.env` рядом с манифестом читается до разбора, редирект можно положить туда и держать в `.gitignore`.
+
+**Приоритет источников:**
+
+| Источник | Приоритет (↑ выше) |
+| --- | --- |
+| `AMXB_LOCAL_SOURCES` (env) | 1 |
+| манифест, `source: local` | 2 |
+| манифест, GitHub (`repo`/`ref`) | 3 |
+
+`AMXB_LOCAL_STRICT=1` (или `true`) делает ошибкой id из env, для которого нет репо/dep в манифесте. Без него такой id просто пишет предупреждение и игнорируется. Каждый применённый редирект пишет предупреждение. Кривой синтаксис env тоже предупреждение, не фатальная ошибка.
+
+### Ограничения локальных источников
+
+- Локальные источники **не версионируются**: рабочее дерево читается как есть, поэтому сборка не воспроизводима. Это годится для разработки и интеграции, но не для релизов.
+- `amxb watch` следит только за `amxmodx/` и `assets/` манифеста и **не** следит за папками локальных зависимостей: правки в локальном dep не запускают пересборку автоматически.
+- Папка должна существовать: отсутствующий `path` или опечатка в нём дают жёсткую ошибку, если для этого id не задан редирект в `AMXB_LOCAL_SOURCES` (редирект имеет приоритет и может перекрыть устаревший `path`).
+- Внутренний id локальной записи должен быть уникальным: если два источника дают одинаковый `local/<name>` (например, у папок совпал basename), сборка останавливается с ошибкой. Задайте разные `name`.
+
 ## GitHub Actions
 
 ```yaml
@@ -463,6 +605,54 @@ repos:
     ref: latest   # автоматически берёт тег последнего GitHub release
 ```
 
+## Кэш резолва `ref`: `ref_ttl`
+
+Поле `ref_ttl` управляет временем жизни кэша резолва `ref → SHA` (файл
+`.ref-heads.json` в кэше сборки). Оно относится только к git-записям `repos[]`
+и `deps[]` и не действует на `source: release`, `source: fungun`,
+`source: local`, `ref: latest` и `ref` без значения (default branch).
+
+Допустимые значения:
+
+| Значение | Смысл |
+| --- | --- |
+| `never` | Кэшировать резолв вечно (регистронезависимо) |
+| `Ns` / `Nm` / `Nh` / `Nd` | Длительность с целым N ≥ 1: секунды, минуты, часы, дни (например, `30m`, `1h`, `7d`) |
+| целое число `N` | То же в секундах (например, `3600` = 1 час) |
+
+Если поле не задано, TTL выводится из типа ref:
+
+- именованный ref, который GitHub подтвердил как **тег** → кэш вечный;
+- ветка, а также default branch при отсутствии `ref` → перепроверка раз в **1 час**.
+
+Если одно и то же имя существует и как тег, и как ветка, приоритет у тега: такой
+ref классифицируется как тег и кэшируется как неизменяемый.
+
+Явный `ref_ttl` переопределяет дефолт для конкретной записи. Протухание TTL
+инвалидирует только связку `ref → SHA`: каталог клона ключуется по SHA, поэтому
+неизменённый SHA ничего не перекачивает. Если тег force-push'нули, вечный кэш
+этого не заметит: обновите явный `ref_ttl` или выполните `amxb clean`.
+
+```yaml
+repos:
+  - repo: Org/VipModular
+    ref: main
+    ref_ttl: 30m           # ветку перепроверять раз в 30 минут
+
+  - repo: Org/Stable
+    ref: v2.1.0
+    ref_ttl: never         # тег: закрепить резолв навсегда
+
+deps:
+  - repo: Org/ParamsController
+    ref: 1.4.2
+    ref_ttl: 7d            # git-dep: перепроверка раз в неделю
+```
+
+Строковая форма deps (`owner/repo@ref[:include_path]`) и файл `DEPS_LIST` поле
+`ref_ttl` не поддерживают: у них нет слота для этого поля. Используйте полную
+(объектную) форму записи.
+
 ## deps: fungun.net
 
 [fungun.net](https://fungun.net) — магазин закрытых AMXX-плагинов. Архивов и
@@ -628,9 +818,10 @@ curl -fsSL https://raw.githubusercontent.com/AmxxModularEcosystem/amxx-builder/m
 
 | Что | Порядок (↑ выше) |
 | --- | --- |
-| плагины `plugins:` | правила применяются по порядку, первое совпадение побеждает |
-| `plugins_ini_postfix` | правило `plugins:` → репо → глобальный |
+| плагины (`plugins.rules`) | правила применяются по порядку, первое совпадение побеждает |
+| INI плагинов | `plugins.rules` → `repos[].plugins` → `plugins.defaults` → выключено |
 | зависимости | `manifest.deps` → `deps_override` → `DEPS_LIST` файл в репо |
+| локальные источники | `AMXB_LOCAL_SOURCES` (env) → манифест `source: local` → GitHub |
 | ассеты | порядок в `sources:` + `on_conflict` |
 | версия компилятора | `amxmodx.version` → последний релиз |
 | значения манифеста | `--set` → манифест проекта → `defaults/amxbuild.defaults.yml` |
@@ -651,3 +842,30 @@ sudo dpkg --add-architecture i386
 sudo apt update
 sudo apt install libc6:i386 libstdc++6:i386
 ```
+
+### Сборка падает на `/mnt/...` в WSL
+
+`amxxpc` — 32-битный Linux-бинарник, но под WSL он **не читает** файлы на
+Windows-дисках, смонтированных в `/mnt/*` (DrvFs/9p: `/mnt/c`, `/mnt/d`, `/mnt/j`, …).
+Node/bash эти файлы видят, поэтому ошибка выглядит «мистической»:
+
+- локальный `.sma` на `/mnt/*` → `fatal error 100: cannot read from file: ".../plugin.sma"`;
+- локальная папка `include/` на `/mnt/*` (идёт как `-i`) → `std::bad_alloc` / `Aborted` (SIGABRT).
+
+Плагины из `repos:` при этом собираются нормально — их исходники amxb кладёт в
+нативный кэш `~/.cache/amxx-builder`. Запись `.amxx` на `/mnt/*`, наоборот, работает.
+
+**Решение:** собирать из нативной Linux-файловой системы. Скопируйте проект в `~` —
+кэш компилятора и зависимостей общий, заново ничего не скачивается:
+
+```bash
+mkdir -p ~/amxb-build && cp -r amxmodx assets amxbuild.yml ~/amxb-build/
+cd ~/amxb-build && amxb build
+```
+
+Альтернативы: выполнять сборку на Windows (`build.bat` или `amxb build` в PowerShell)
+либо в CI. Команды без запуска компилятора (`amxb validate`, `amxb deps-tree`,
+`amxb build --dry-run`) под `/mnt/*` работают.
+
+> `amxb build --build-dir <нативный путь>` **не** решает проблему: локальные `.sma`
+> компилируются по месту, из папки проекта, а не из `build/`.

package/action.yml

@@ -34,7 +34,7 @@ inputs:
       Override any manifest field. One entry per line:
         version=1.2.3
         output.archive_name={name}-{version}.zip
-        output.generate_ini=false
+        plugins.defaults.ini=myserver
         github.tokens.MyOrg=GITHUB_TOKEN_MYORG
     required: false
   github-token:

package/defaults/amxbuild.defaults.yml

@@ -7,6 +7,7 @@ version: "1.0.0"
 amxmodx:
   dir: amxmodx
   defines: []
+  exclude_files: []
 
 github:
   token_env: GITHUB_TOKEN
@@ -21,7 +22,6 @@ output:
   amxmodx_path: "{name}/addons/amxmodx"
   assets_path: "{name}"
   readme: true
-  generate_ini: false
   pack: true
   on_conflict: last_wins
 

package/mcp/handlers.js

@@ -9,12 +9,13 @@ const { resolveRefIfLatest }   = require('../src/repo-fetcher');
 const { fetchDepRoot, collectDepIncludeDirs } = require('../src/deps-resolver');
 const { resolveAssets, readAssets, readDepManifest, collectDepAssets, collectLocalAssets } = require('../src/agent-assets');
 const { getCompilerInfo, resolveStdlibVersion } = require('../src/compiler-fetcher');
-const { resolveManifest, resolveGithubToken, parseDepString, parseDepObject, parseDocEntries, parseSkillEntries } = require('../src/manifest');
+const { resolveManifest, resolveGithubToken, parseDepString, parseDepObject, parseRefTtl, parseDocEntries, parseSkillEntries } = require('../src/manifest');
 const { parseManifest }         = require('../src/manifest');
 const { validateManifestFile }  = require('../src/validate');
 const { getManifestSchema }     = require('../src/schema');
 const { getCacheInfo }          = require('../src/cache-info');
 const { buildDepTree, assembleRootDeps } = require('../src/deps-tree');
+const { isLocal, resolveLocalEntry } = require('../src/local-sources');
 const { buildIncludeTree, fetchDepIncludeDir, parseIncludeDirective, searchIncludeFile, collectIncFiles } = require('../src/include-tree');
 const { listReleases, listTags } = require('../src/release-lister');
 const { buildPlanData }         = require('../src/build-plan');
@@ -80,7 +81,21 @@ function parseDep(raw) {
   throw new Error('Dep must be a string or an object');
 }
 
+// A local dep's declared `path` is relative to the manifest dir when one is in
+// scope, else the process cwd.
+function depBaseDir(args) {
+  return args?.manifest ? path.dirname(path.resolve(args.manifest)) : process.cwd();
+}
+
+// Materialize a user-supplied `source: local` dep (parsed to `_localPathRaw`)
+// into an absolute `_localDir` via the core helper — no path logic in adapters.
+function resolveUserDep(dep, args) {
+  return resolveLocalEntry(dep, depBaseDir(args));
+}
+
 function resolveDepRef(dep, token) {
+  // Local sources have no remote ref to resolve — never touch the network.
+  if (isLocal(dep)) return 'local';
   return resolveRefIfLatest(dep.ref, dep.repo, token);
 }
 
@@ -161,7 +176,7 @@ async function handleGetDepInterface(args, token, noFetch) {
   token = fallbackToken(token);
   let dep;
   try {
-    dep = parseDep(args?.dep || args);
+    dep = resolveUserDep(parseDep(args?.dep || args), args);
   } catch (parseErr) {
     return errorResult(parseErr.message);
   }
@@ -206,7 +221,7 @@ async function handleListDepIncs(args, token, noFetch) {
   token = fallbackToken(token);
   let dep;
   try {
-    dep = parseDep(args?.dep || args);
+    dep = resolveUserDep(parseDep(args?.dep || args), args);
   } catch (parseErr) {
     return errorResult(parseErr.message);
   }
@@ -238,7 +253,9 @@ async function handleGetDepTree(args, token, noFetch) {
   let tokenFor = null;
 
   if (args?.manifest) {
-    const manifest = parseManifest(path.resolve(args.manifest));
+    const manifestPath = path.resolve(args.manifest);
+    loadEnv(manifestPath, { quiet: true });
+    const manifest = parseManifest(manifestPath);
     tokenFor = (repo) => resolveGithubToken(manifest, repo);
     const assembled = assembleRootDeps(manifest);
     rootDeps = assembled.rootDeps;
@@ -249,7 +266,15 @@ async function handleGetDepTree(args, token, noFetch) {
         const parsed = parseDep(entry);
         return { repo: parsed.repo, ref: parsed.ref, source: parsed.source, include_path: parsed.include_path, asset: parsed.asset };
       }
-      return { repo: entry.repo, ref: entry.ref, source: entry.source || 'git', include_path: entry.include_path || null, asset: entry.asset != null ? entry.asset : null };
+      return {
+        repo: entry.repo,
+        ref: entry.ref,
+        source: entry.source || 'git',
+        include_path: entry.include_path || null,
+        asset: entry.asset != null ? entry.asset : null,
+        _localDir: entry._localDir || null,
+        ...(entry.ref_ttl != null ? { ref_ttl: parseRefTtl(entry.ref_ttl, `deps entry ${entry.repo}`) } : {}),
+      };
     });
   } else {
     return errorResult('Provide either "manifest" or "deps"', -32602);
@@ -345,6 +370,7 @@ async function resolveStdlibState(args, noFetch) {
   if (!args?.version) {
     const manifestPath = resolveManifestPath(args?.manifest || undefined).path;
     if (fs.existsSync(manifestPath)) {
+      loadEnv(manifestPath, { quiet: true });
       try {
         manifest = parseManifest(manifestPath);
       } catch (err) {
@@ -468,6 +494,7 @@ async function handleResolveInclude(args, token, noFetch) {
   const manifestPath = resolveManifestPath(args?.manifest || undefined).path;
   const depErrors = [];
   if (fs.existsSync(manifestPath)) {
+    loadEnv(manifestPath, { quiet: true });
     let manifest = null;
     try {
       manifest = parseManifest(manifestPath);
@@ -543,7 +570,7 @@ async function handleBuildPlan(args) {
 
 /**
  * Build a parsed dep object from MCP tool args: either a full `dep` string/object
- * or explicit { repo, ref?, source?, include_path?, asset? } fields.
+ * or explicit { repo, ref?, source?, include_path?, asset?, ref_ttl? } fields.
  * Preserves the arg-shape handling of the former inline fetchDepRoot.
  */
 function depFromArgs(args) {
@@ -555,12 +582,19 @@ function depFromArgs(args) {
     const source = args.source || 'git';
     // Release deps need a ref — default to 'latest' when omitted.
     const ref = args.ref || (source === 'release' ? 'latest' : null);
-    dep = { repo: args.repo, ref, source, include_path: args.include_path || null, asset: args.asset ?? null };
+    dep = {
+      repo: args.repo,
+      ref,
+      source,
+      include_path: args.include_path || null,
+      asset: args.asset ?? null,
+      ...(args.ref_ttl != null ? { ref_ttl: parseRefTtl(args.ref_ttl, `deps entry ${args.repo}`) } : {}),
+    };
   }
   if (args?.source)        dep.source = args.source;
   if (args?.include_path)  dep.include_path = args.include_path;
   if (args?.asset != null) dep.asset = args.asset;
-  return dep;
+  return resolveUserDep(dep, args);
 }
 
 async function handleListRepoFiles(args, token, noFetch) {
@@ -654,7 +688,9 @@ function isDepMode(args) {
 
 // Local-mode assets come from the current project's own manifest `docs:`/`skills:`.
 function resolveLocalAssets(args) {
-  return collectLocalAssets(parseManifest(resolveManifestPath(args?.manifest).path));
+  const manifestPath = resolveManifestPath(args?.manifest).path;
+  loadEnv(manifestPath, { quiet: true });
+  return collectLocalAssets(parseManifest(manifestPath));
 }
 
 // Shared empty-state text for the list/get handlers (never an error).
@@ -889,6 +925,7 @@ async function handleCompileSma(args, token, noFetch) {
   const depErrors = [];
   const manifestPath = resolveManifestPath(args?.manifest || undefined).path;
   if (fs.existsSync(manifestPath)) {
+    loadEnv(manifestPath, { quiet: true });
     let manifest = null;
     try {
       manifest = parseManifest(manifestPath);
@@ -952,6 +989,7 @@ async function handleCompileSma(args, token, noFetch) {
 async function handleResolveAssets(args) {
   const manifestPath = resolveManifestPath(args?.manifest).path;
   const fullPath = path.resolve(manifestPath);
+  loadEnv(fullPath, { quiet: true });
 
   let manifest;
   try {
@@ -1008,6 +1046,7 @@ async function handleSearchSymbol(args, token, noFetch) {
   const manifestPath = resolveManifestPath(args?.manifest || undefined).path;
   let manifest = null;
   if (fs.existsSync(manifestPath)) {
+    loadEnv(manifestPath, { quiet: true });
     try {
       manifest = parseManifest(manifestPath);
     } catch (err) {
@@ -1038,7 +1077,9 @@ async function handleSearchSymbol(args, token, noFetch) {
   // canonical core helper (sequential, ssh-aware); user deps stay individual
   // parallel jobs.
   const manifestDeps = manifest?.globalDeps?.length ? manifest.globalDeps : [];
-  const userDeps = manifest?.globalDeps?.length ? [] : (args?.deps || []).map(parseDep);
+  const userDeps = manifest?.globalDeps?.length
+    ? []
+    : (args?.deps || []).map((entry) => resolveUserDep(parseDep(entry), args));
   if (scope === 'all' || scope === 'deps') {
     const ssh = manifest?.github?.ssh === true;
     if (manifestDeps.length) {