@7n/rules 1.84.0 → 1.85.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [1.85.0] - 2026-08-05
+
+### Added
+
+- Контракт плагінів `n-rules:plugin` — мінор `3.1.0`: новий host-імпорт `exec-tool`
+(`run-tool` плюс `cwd`, накладені змінні середовища й двобічний scratch-обмін
+файлами) і слот `scratch-dir@1` на чинному `host-context`. Зміна additive:
+плагін, зібраний під v3.0, лінкується й працює без повторної збірки.
+
+Резолв тулів у `manifest.tools` навчився схем (рішення В спеки v3.1):
+`path:<name>` резолвиться по PATH замість github-релізу; відсутність схеми —
+як було (`pinned:`).
+
+Перший концерн на новій поверхні — `bun/licensee`: детекція ліцензій
+npm-залежностей переїхала з JS у wasm-компонент `lang-js/wasm-concerns`
+(T0-фікс лишається JS). Спавнений тул виконується з правами хоста, поза
+wasm-пісочницею — межа довіри плагіна це його пін, не пісочниця.
+
+### Fixed
+
+- регенерує `.cursor/rules/n-rust.mdc` (дрейф із каноном після #392) і піднімає `KNOWN_PLUGIN_RANGES['@7n/rules-lang-rust']` до `^0.16` слідом за релізом плагіна
+
 ## [1.84.0] - 2026-08-05
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7n/rules",
-  "version": "1.84.0",
+  "version": "1.85.0",
   "description": "CLI еталонних правил і skills (префікс n-): синк у репозиторій, дельта-lint, конформність",
   "keywords": [
     "cli",

package/schemas/v8r-catalog.json

@@ -208,7 +208,7 @@
     },
     {
       "name": "n-rules plugin manifest",
-      "description": "plugin.toml — маніфест wasm-плагіна n-rules:plugin@3.0.0 (crates/<guest>/plugin.toml); офіційної JSON Schema поки нема (schemars-схема rules_contract::manifest::Manifest ще не публікується як окремий файл), тому permissive any.json",
+      "description": "plugin.toml — маніфест wasm-плагіна n-rules:plugin@3.1.0 (crates/<guest>/plugin.toml); офіційної JSON Schema поки нема (schemars-схема rules_contract::manifest::Manifest ще не публікується як окремий файл), тому permissive any.json",
       "url": "any.json",
       "fileMatch": [
         "plugin.toml",

package/scripts/lib/lint-surface/wasm-plugins.mjs

@@ -7,7 +7,9 @@
  * (значення — НЕ голий рядок шляху, доккомент [`buildWasmConcernMap`] нижче).
  *
  * **Run-tool контур (задача N1, рішення Д спеки)**: `manifest.tools` —
- * задекларовані зовнішні tool-залежності плагіна (напр. `"shellcheck@^0.9"`).
+ * задекларовані зовнішні tool-залежності плагіна (напр. `"shellcheck@^0.9"`,
+ * `"path:bun"` — схеми резолву, рішення В спеки
+ * `docs/specs/2026-08-01-plugin-contract-v31-surfaces.md`, [`parseToolRef`]).
  * Для кожного запису резолвер кличе ensure-tool контур (`ensureToolAsync`,
  * `../ensure-tool.mjs`, injectable через `opts.ensureToolFn`) — будує мапу
  * «ім'я тула (без semver-суфікса декларації) → абсолютний шлях», яку
@@ -114,6 +116,7 @@ import { fileURLToPath } from 'node:url'
 
 import { ensureToolAsync } from '../ensure-tool.mjs'
 import { loadNative } from '../native.mjs'
+import { resolveCmd } from '../../utils/resolve-cmd.mjs'
 
 /**
  * Абсолютний шлях до `npm/wasm-plugins/` — тека, куди `build-wasm-plugins.mjs`
@@ -431,16 +434,39 @@ async function resolveEntryPath(entry, ctx) {
 }
 
 /**
- * Ім'я тула без semver-суфікса декларації (`"shellcheck@^0.9"` → `"shellcheck"`)
- * — той самий парсинг, що host-бік `ToolResolver::run`
- * (`crates/rules-plugin-host/src/tool_resolver.rs`, доккомент модуля
- * пояснює версійну політику — вона НЕ тут, ensure-tool ставить канонічну
- * закріплену версію).
+ * Схеми резолву тула в рядку `manifest.tools` (рішення В спеки
+ * `docs/specs/2026-08-01-plugin-contract-v31-surfaces.md`). Дзеркало
+ * Rust-боку (`rules_contract::validators::tool::ToolScheme`) — і саме
+ * ДЗЕРКАЛО, а не незалежний список: розбіжність означала б, що маніфест,
+ * прийнятий хостом, мовчки не резолвиться оркестрацією.
+ */
+const TOOL_SCHEMES = {
+  /** Github-реліз із закріпленою версією (`TOOLS` + `tool-pins.json`) — дефолт за відсутності схеми. */
+  PINNED: 'pinned',
+  /** Резолв по `PATH` (`bun`, `bunx` — ensure-tool не вміє і не має їх завантажувати). */
+  PATH: 'path'
+}
+
+/**
+ * Розбирає запис `manifest.tools` у `{ scheme, name }`: відрізає схему
+ * (якщо є), потім semver-суфікс декларації (`"path:bun@^1.2"` →
+ * `{ scheme: 'path', name: 'bun' }`). Порт
+ * `rules_contract::validators::tool::parse_tool_ref` — дзеркальний тест
+ * конвенції: `tests/wasm-plugins.test.mjs`.
+ *
+ * Невідома схема НЕ інтерпретується як частина імені: [`ensureDeclaredTools`]
+ * пропускає такий запис із warn, бо резолвити його однаково нема чим (та
+ * сама поведінка, що host-валідатор `validate_tool_ref`).
  * @param {string} declared запис із `manifest.tools`
- * @returns {string} ім'я тула
+ * @returns {{ scheme: string | null, name: string }} схема (`null` — невідома) й ім'я тула
  */
-function toolName(declared) {
-  return declared.split('@', 1)[0]
+function parseToolRef(declared) {
+  const separator = declared.indexOf(':')
+  if (separator === -1) return { scheme: TOOL_SCHEMES.PINNED, name: declared.split('@', 1)[0] }
+  const prefix = declared.slice(0, separator)
+  const rest = declared.slice(separator + 1)
+  if (prefix !== TOOL_SCHEMES.PINNED && prefix !== TOOL_SCHEMES.PATH) return { scheme: null, name: declared }
+  return { scheme: prefix, name: rest.split('@', 1)[0] }
 }
 
 /**
@@ -456,14 +482,26 @@ function toolName(declared) {
  * @param {string} pluginName ім'я плагіна (лише для diagnostics-повідомлень)
  * @param {string[]} declaredTools `manifest.tools` — рядки виду `"shellcheck@^0.9"`
  * @param {(toolId: string) => Promise<string>} ensureToolFn ін'єкція `ensureToolAsync` (тести підміняють)
+ * @param {(cmd: string) => string | null} resolveCmdFn ін'єкція `resolveCmd` для схеми `path:` (тести підміняють — інакше результат залежав би від PATH машини)
  * @returns {Promise<Record<string, string>>} ім'я тула (без semver-суфікса) → абсолютний шлях
  */
-async function ensureDeclaredTools(pluginName, declaredTools, ensureToolFn) {
+async function ensureDeclaredTools(pluginName, declaredTools, ensureToolFn, resolveCmdFn) {
   /** @type {Record<string, string>} */
   const toolPaths = {}
   for (const declared of declaredTools) {
-    const name = toolName(declared)
+    const { scheme, name } = parseToolRef(declared)
     try {
+      if (scheme === null)
+        throw new Error(`невідома схема резолву (відомі "${TOOL_SCHEMES.PINNED}:", "${TOOL_SCHEMES.PATH}:")`)
+      if (scheme === TOOL_SCHEMES.PATH) {
+        // `path:` НЕ йде в ensure-tool контур узагалі: той уміє лише
+        // github-релізи, а `bun`/`bunx` встановлює користувач. Відсутність —
+        // не помилка резолву плагіна, а звичайний skip одного тула.
+        const fromPath = resolveCmdFn(name)
+        if (!fromPath) throw new Error('не знайдено в PATH')
+        toolPaths[name] = fromPath
+        continue
+      }
       toolPaths[name] = await ensureToolFn(name)
     } catch (error) {
       console.warn(
@@ -484,7 +522,7 @@ async function ensureDeclaredTools(pluginName, declaredTools, ensureToolFn) {
  * запис у мапу для кожного `manifest.concerns`. Усі кроки — skip-not-crash
  * (доккомент модуля).
  * @param {string} cwd абсолютний корінь consumer-репо
- * @param {{fetchFn: typeof fetch, cacheDir: string, env: Record<string, string | undefined>, ensureToolFn: (toolId: string) => Promise<string>, nativeFn: typeof loadNative, builtinPinsDir: string}} ctx ін'єктовані залежності
+ * @param {{fetchFn: typeof fetch, cacheDir: string, env: Record<string, string | undefined>, ensureToolFn: (toolId: string) => Promise<string>, resolveCmdFn: (cmd: string) => string | null, nativeFn: typeof loadNative, builtinPinsDir: string}} ctx ін'єктовані залежності
  * @returns {Promise<Map<string, WasmConcernMapEntry>>} ключ концерну → `{ wasmPath, toolPaths }`
  */
 async function buildWasmConcernMap(cwd, ctx) {
@@ -500,7 +538,7 @@ async function buildWasmConcernMap(cwd, ctx) {
       console.warn(`⚠️ wasm-плагін "${entry.name}" пропущено: не вдалось завантажити (${error.message})`)
       continue
     }
-    const toolPaths = await ensureDeclaredTools(entry.name, manifest.tools ?? [], ctx.ensureToolFn)
+    const toolPaths = await ensureDeclaredTools(entry.name, manifest.tools ?? [], ctx.ensureToolFn, ctx.resolveCmdFn)
     // `manifest.concerns` — масив структурованих контрибуцій `{ key, scope, glob }`
     // (задача N2, передумова full-scope мосту, доккомент `wit/world.wit`
     // `record concern-contribution`), не голі рядки — мапа концернів індексується
@@ -521,9 +559,10 @@ async function buildWasmConcernMap(cwd, ctx) {
  * неминуче асинхронні; єдиний виклик-сайт (`detect.mjs`) вже `async`,
  * контракт виклику не ламається.
  * @param {string} cwd абсолютний корінь consumer-репо (звідки читається `.n-rules.json`)
- * @param {{fetchFn?: typeof fetch, cacheDir?: string, env?: Record<string, string | undefined>, ensureToolFn?: (toolId: string) => Promise<string>, nativeFn?: typeof loadNative, builtinPinsDir?: string}} [opts] ін'єкції для тестів:
+ * @param {{fetchFn?: typeof fetch, cacheDir?: string, env?: Record<string, string | undefined>, ensureToolFn?: (toolId: string) => Promise<string>, resolveCmdFn?: (cmd: string) => string | null, nativeFn?: typeof loadNative, builtinPinsDir?: string}} [opts] ін'єкції для тестів:
  *   `fetchFn` (дефолт — глобальний `fetch`), `cacheDir` (дефолт — `resolvePluginCacheDir`), `env` (дефолт — `process.env`),
- *   `ensureToolFn` (дефолт — `ensureToolAsync`), `nativeFn` (дефолт — `loadNative`, wiring-тести підміняють фейковим addon-ом),
+ *   `ensureToolFn` (дефолт — `ensureToolAsync`), `resolveCmdFn` (дефолт — `resolveCmd`; тести підміняють, бо інакше
+ *   `path:`-схема давала б різний `toolPaths` залежно від PATH машини), `nativeFn` (дефолт — `loadNative`, wiring-тести підміняють фейковим addon-ом),
  *   `builtinPinsDir` (дефолт — [`WASM_PLUGINS_DIR`], реальна `npm/wasm-plugins/`; тести ізолюють неіснуючим каталогом,
  *   щоб локальна wasm-збірка в робочому дереві не підмішувала builtin-контрибуції в контрольовані сценарії)
  * @returns {Promise<Map<string, WasmConcernMapEntry>>} ключ концерну (`ruleId/concernId`) → `{ wasmPath, toolPaths }`
@@ -536,6 +575,7 @@ export function resolveWasmConcernMap(cwd, opts = {}) {
     cacheDir: opts.cacheDir ?? resolvePluginCacheDir(env),
     env,
     ensureToolFn: opts.ensureToolFn ?? ensureToolAsync,
+    resolveCmdFn: opts.resolveCmdFn ?? resolveCmd,
     nativeFn: opts.nativeFn ?? loadNative,
     builtinPinsDir: opts.builtinPinsDir ?? WASM_PLUGINS_DIR
   }

package/scripts/lib/resolve-plugins.mjs

@@ -283,7 +283,7 @@ export const KNOWN_PLUGIN_RANGES = Object.freeze({
   '@7n/rules-ci-azure': '^2',
   '@7n/rules-lang-js': '^0.26',
   '@7n/rules-lang-python': '^0.12',
-  '@7n/rules-lang-rust': '^0.15',
+  '@7n/rules-lang-rust': '^0.16',
   '@7n/rules-lang-php': '^0.3'
 })
 

package/skills/wasm-plugin/SKILL.md

@@ -441,6 +441,49 @@ per-file: пиши `detect_whole_batch(files: &[SourceFile]) -> Vec<Diagnostic>`
     фейковий бінарник (shell-скрипт у tempdir) у `ToolResolver::new(map)`
     (зразок — `run_tool_reaches_resolved_fake_tool_binary`
     `crates/rules-plugin-host/tests/contract_test_kit.rs`).
+- **`exec-tool`** (зріз 5 контракту v3.1, спека
+  `docs/specs/2026-08-01-plugin-contract-v31-surfaces.md`, рішення А/Б/В/З) —
+  `run-tool` ПЛЮС виконавчий контекст. Бери його, якщо тулу потрібне бодай
+  щось із трьох:
+  - **`cwd`** (posix-relative від кореня репо; `none` — сам корінь). Без
+    нього процес успадковує cwd ХОСТ-процесу, який збігається з коренем репо
+    випадково. Обгортка, що читає `node_modules`/конфіги відносно себе, без
+    цього поля перевіряє не той каталог;
+  - **`env`** — пари НАКЛАДАЮТЬСЯ поверх успадкованого середовища, не
+    заміщують його;
+  - **scratch-обмін**: `scratch-in` хост матеріалізує у тимчасовому каталозі
+    ПЕРЕД спавном (вшиті в компонент конфіги/політики), `scratch-out` —
+    глоби файлів, які хост зчитує ПІСЛЯ виходу процесу (звіти тула).
+    Абсолютний шлях каталогу гість бере зі слоту `scratch-dir@1`
+    (`host-context`) і САМ кладе його в `args` — placeholder-підстановки в
+    аргументах контракт свідомо не має. Каталог живе РІВНО один
+    `detect`/`fix`-виклик, тож шлях не можна кешувати між викликами;
+    відсутній `scratch-out`-файл — не помилка, а «звіту немає».
+
+  Помилки — та сама форма, що в `run-tool`: `status: none` + людиночитний
+  `stderr`, ніколи не паніка. `exec-tool` виконує ВЖЕ зарезолвлений тул і
+  нічого не добуває — провізіонінг живе в окремій команді `tools ensure`.
+
+  **Схеми `manifest.tools`** (рішення В): `pinned:` (дефолт за відсутності
+  схеми — github-реліз із закріпленою версією) і `path:` (резолв по `PATH`:
+  `path:bun`, `path:bunx` — те, що ensure-tool завантажити не може й не має).
+
+  > **Trust boundary — прочитай ДО того, як напишеш перший `exec-tool`.**
+  > Спавнений тул виконується **з правами хоста, ПОЗА wasm-пісочницею**, і
+  > **МОЖЕ писати в репо**. Ані `fs_read`, ані `network` до нього не
+  > застосовуються: пісочниця обмежує wasm-код гостя, а не процес, який гість
+  > попросив запустити. Хост звужує лише ЯКИЙ бінарник (задекларований),
+  > ЗВІДКИ він стартує (`cwd` — безпечний repo-relative) і ЩО потрапляє у
+  > scratch (без `..`, з лімітами). Тобто **межа довіри плагіна — його пін
+  > (`url` + `sha256`), а не пісочниця**: ревʼю піна = ревʼю прав.
+  > Enforcement не додається свідомо (потрібен був би власний sandbox-шар
+  > навколо спавна на трьох ОС).
+
+  Живий зразок — `bun/licensee` (`crates/plugin-lang-js/src/lib.rs`, секція
+  «Зріз 5»); golden-тести з фейковим `bun` —
+  `crates/rules-plugin-host/tests/plugin_lang_js.rs`; повний контекст разом
+  (cwd + env + scratch) — `test/guest-exec-tool`
+  у `crates/test-plugin-guest`.
 - **`ci_artifacts`** (слот `ci.artifact@1`): типізовані записи
   `n-rules:slots` (`crates/rules-contract/src/slots/ci_artifact.rs`) —
   семантичні перевірки (safe-path, id-regex) живуть у

package/wasm-plugins/builtin-pins.json

@@ -1,6 +0,0 @@
-{
-  "lang-js": {
-    "file": "plugin-lang-js.wasm",
-    "sha256": "e25eb9efbb70dabf95d39dcaba9f3394f0e3db31bb2154016e86431552173722"
-  }
-}