@rt-tools/agent-kit 0.3.0 → 0.5.0

package/lib/catalog.js

@@ -5,25 +5,52 @@
  * `init` спрашивает, какие законы взять, а `list` показывает и то, от чего проект отказался.
  * И там и там нужен полный набор, а `collectAssets` по устройству отдаёт уже отобранный.
  */
-import { readdirSync, readFileSync } from 'node:fs';
+import { accessSync, constants, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { KINDS } from './config.js';
+import { matchesVariant, readAxes, variantOf, withoutVariant } from './variants.js';
 const TITLE = /^#\s+(\S.*)$/m;
+/** Запускается ли файл сам по себе. Спрашиваем систему, а не разбираем биты режима руками. */
+function isExecutable(path) {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Заголовок нужен человеку, который выбирает: имена законов ему ни о чём не говорят. */
 export function titleOf(text, fallback) {
     const found = text.match(TITLE);
     return found ? found[1].trim() : fallback;
 }
-function filesOf(dir) {
+/**
+ * Файлы рода — вместе с теми, что лежат в подкаталогах.
+ *
+ * Обход рекурсивный потому, что у законов два слоя: общий закон верен любому приложению этого
+ * класса, а закон приложения — только такому, где есть деньги, локали или владеющая сущность.
+ * Слой отражён каталогом, и путь внутри рода едет в идентификатор целиком, чтобы разложенное
+ * повторяло раскладку пакета.
+ */
+function filesOf(dir, prefix = '') {
+    let entries;
     try {
-        return readdirSync(dir, { withFileTypes: true })
-            .filter((entry) => entry.isFile())
-            .map((entry) => entry.name)
-            .sort();
+        entries = readdirSync(dir, { withFileTypes: true });
     }
     catch {
         return [];
     }
+    const files = [];
+    for (const entry of [...entries].sort((one, two) => one.name.localeCompare(two.name))) {
+        if (entry.isFile()) {
+            files.push(`${prefix}${entry.name}`);
+        }
+        else if (entry.isDirectory()) {
+            files.push(...filesOf(join(dir, entry.name), `${prefix}${entry.name}/`));
+        }
+    }
+    return files;
 }
 /**
  * Всё, что лежит в ресурсах пакета. Список не выписан руками, а читается из каталога:
@@ -31,12 +58,16 @@ function filesOf(dir) {
  * нечем — ресурс просто не приезжал бы к проекту.
  */
 export function readCatalog(assetsDir) {
+    const axes = readAxes(assetsDir);
     const entries = [];
     for (const kind of KINDS) {
         for (const file of filesOf(join(assetsDir, kind))) {
-            const text = readFileSync(join(assetsDir, kind, file), 'utf8');
-            const name = file.replace(/\.[^.]+$/, '');
-            entries.push({ id: `${kind}/${file}`, kind, name, title: titleOf(text, name), text });
+            const path = join(assetsDir, kind, file);
+            const text = readFileSync(path, 'utf8');
+            const variant = variantOf(file, axes);
+            const name = withoutVariant(file, variant).replace(/\.[^./]+$/, '');
+            const executable = isExecutable(path);
+            entries.push({ id: `${kind}/${file}`, kind, name, title: titleOf(text, name), variant, text, executable });
         }
     }
     return entries;
@@ -51,21 +82,78 @@ export function readCatalog(assetsDir) {
  *
  * `skip` вычитает из выбранного. Отказ от одного закона не должен требовать переписать
  * список из пятнадцати, а точечное исключение остаётся точечным.
+ *
+ * Вид отбирается раньше обоих: ресурс чужого хостинга не «не выбран» — его в этом дереве не
+ * существует вовсе, и называть его в `skip` проекту незачем.
  */
-export function isChosen(entry, only, skip) {
-    if (skip.includes(entry.id)) {
+export function isChosen(entry, selection) {
+    if (!matchesVariant(entry.variant, selection.variants)) {
         return false;
     }
-    const restricted = only.some((id) => id.startsWith(`${entry.kind}/`));
-    return !restricted || only.includes(entry.id);
+    if (selection.skip.includes(entry.id)) {
+        return false;
+    }
+    const restricted = selection.only.some((id) => id.startsWith(`${entry.kind}/`));
+    return !restricted || selection.only.includes(entry.id);
+}
+/**
+ * Ресурсы, оставшиеся без вида под выбор дерева.
+ *
+ * Молчаливый пропуск такого ресурса — худший из исходов. Правило поставки едет тремя видами, а
+ * команды заведения задачи и сверки очереди — одним: дерево, выбравшее чужой хостинг, получает
+ * правило, которое зовёт три команды, и ни одного скрипта под ними. Отказа при этом не бывает —
+ * ресурс просто не приезжает, и узнают об этом, когда команда из правила не находится.
+ *
+ * Отсюда правило: **ресурс с видами, ни один из которых не совпал, — отказ, а не пропуск.**
+ * Снимается он двумя способами, и оба явные: завести недостающий вид в пакете либо назвать
+ * существующие в `skip` — дерево тем самым говорит, что обходится без этого ресурса.
+ */
+export function variantGaps(catalog, selection) {
+    const groups = new Map();
+    for (const entry of catalog) {
+        if (entry.variant === null) {
+            continue;
+        }
+        const key = `${entry.kind}/${entry.name}`;
+        groups.set(key, [...(groups.get(key) ?? []), entry]);
+    }
+    const gaps = [];
+    for (const entries of groups.values()) {
+        const axis = entries[0].variant?.axis ?? '';
+        if (entries.some((entry) => matchesVariant(entry.variant, selection.variants))) {
+            continue;
+        }
+        // Отказ от ресурса — законный ответ, и повторять его отказом раскладки незачем: дерево
+        // уже сказало, что обходится без него.
+        if (entries.every((entry) => selection.skip.includes(entry.id))) {
+            continue;
+        }
+        // Род, суженный через `only`, отбирает ресурсы поимённо: не названный в нём ресурс не
+        // пропал — его не просили.
+        const restricted = selection.only.some((id) => id.startsWith(`${entries[0].kind}/`));
+        if (restricted && !entries.some((entry) => selection.only.includes(entry.id))) {
+            continue;
+        }
+        gaps.push({
+            kind: entries[0].kind,
+            name: entries[0].name,
+            axis,
+            chosen: selection.variants[axis] ?? '',
+            available: entries.map((entry) => entry.variant?.value ?? ''),
+            ids: entries.map((entry) => entry.id),
+        });
+    }
+    return gaps;
 }
 /**
- * Идентификатор по тому, как ресурс назвали в строке запуска. Принимаются все три формы,
- * которыми его называют вслух: `access`, `access.md` и `laws/access.md`.
+ * Идентификатор по тому, как ресурс назвали в строке запуска. Принимаются все формы, которыми
+ * его называют вслух: `money`, `application/money`, `money.md` и `laws/application/money.md`.
  */
 export function idOf(spoken, kind, catalog) {
     const wanted = spoken.trim();
-    const found = catalog.find((entry) => entry.kind === kind && (entry.id === wanted || entry.name === wanted || entry.id.endsWith(`/${wanted}`)));
+    const shortOf = (entry) => entry.name.split('/').pop() ?? entry.name;
+    const found = catalog.find((entry) => entry.kind === kind &&
+        (entry.id === wanted || entry.name === wanted || shortOf(entry) === wanted || entry.id.endsWith(`/${wanted}`)));
     return found ? found.id : null;
 }
 /** Разбор `--laws access,delivery`: имя без ответа — промах, и молчать о нём нельзя. */

package/lib/catalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../../projects/agent-kit/src/lib/catalog.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Что пакет везёт — прочитанное с диска, до всякого выбора проекта.\n *\n * Каталог нужен отдельно от раскладки, потому что выбирать приходится раньше, чем раскладывать:\n * `init` спрашивает, какие законы взять, а `list` показывает и то, от чего проект отказался.\n * И там и там нужен полный набор, а `collectAssets` по устройству отдаёт уже отобранный.\n */\nimport { Dirent, readdirSync, readFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\nimport { KINDS, TKind } from './config.js';\n\nexport interface IEntryOfCatalog {\n    /** Идентификатор: `laws/delivery.md`. Он же путь надстройки и ключ в `only` и `skip`. */\n    readonly id: string;\n    readonly kind: TKind;\n    /** Имя без рода и расширения: `delivery`. Им ресурс называют в строке запуска. */\n    readonly name: string;\n    /** Заголовок первой строки файла; у файла без заголовка — его имя. */\n    readonly title: string;\n    readonly text: string;\n}\n\nconst TITLE: RegExp = /^#\\s+(\\S.*)$/m;\n\n/** Заголовок нужен человеку, который выбирает: имена законов ему ни о чём не говорят. */\nexport function titleOf(text: string, fallback: string): string {\n    const found: RegExpMatchArray | null = text.match(TITLE);\n\n    return found ? found[1].trim() : fallback;\n}\n\nfunction filesOf(dir: string): readonly string[] {\n    try {\n        return readdirSync(dir, { withFileTypes: true })\n            .filter((entry: Dirent): boolean => entry.isFile())\n            .map((entry: Dirent): string => entry.name)\n            .sort();\n    } catch {\n        return [];\n    }\n}\n\n/**\n * Всё, что лежит в ресурсах пакета. Список не выписан руками, а читается из каталога:\n * выписанный разошёлся бы с ним на первом же добавленном законе, и заметить это было бы\n * нечем — ресурс просто не приезжал бы к проекту.\n */\nexport function readCatalog(assetsDir: string): readonly IEntryOfCatalog[] {\n    const entries: IEntryOfCatalog[] = [];\n    for (const kind of KINDS) {\n        for (const file of filesOf(join(assetsDir, kind))) {\n            const text: string = readFileSync(join(assetsDir, kind, file), 'utf8');\n            const name: string = file.replace(/\\.[^.]+$/, '');\n            entries.push({ id: `${kind}/${file}`, kind, name, title: titleOf(text, name), text });\n        }\n    }\n\n    return entries;\n}\n\n/**\n * Взят ли ресурс при этом выборе.\n *\n * `only` ограничивает **только те роды, которые сам называет**. Проект, выбравший девять\n * законов из пятнадцати, шаблоны при этом не терял бы: перечисляя законы, он говорит о\n * законах, а не обо всём, что пакет везёт. Обратное правило читалось бы как «выбрал законы —\n * остался без шаблонов», и заметил бы это только тот, кто пошёл за шаблоном.\n *\n * `skip` вычитает из выбранного. Отказ от одного закона не должен требовать переписать\n * список из пятнадцати, а точечное исключение остаётся точечным.\n */\nexport function isChosen(entry: IEntryOfCatalog, only: readonly string[], skip: readonly string[]): boolean {\n    if (skip.includes(entry.id)) {\n        return false;\n    }\n    const restricted: boolean = only.some((id: string): boolean => id.startsWith(`${entry.kind}/`));\n\n    return !restricted || only.includes(entry.id);\n}\n\n/**\n * Идентификатор по тому, как ресурс назвали в строке запуска. Принимаются все три формы,\n * которыми его называют вслух: `access`, `access.md` и `laws/access.md`.\n */\nexport function idOf(spoken: string, kind: TKind, catalog: readonly IEntryOfCatalog[]): string | null {\n    const wanted: string = spoken.trim();\n    const found: IEntryOfCatalog | undefined = catalog.find(\n        (entry: IEntryOfCatalog): boolean =>\n            entry.kind === kind && (entry.id === wanted || entry.name === wanted || entry.id.endsWith(`/${wanted}`))\n    );\n\n    return found ? found.id : null;\n}\n\nexport interface IResolvedSelection {\n    readonly ids: readonly string[];\n    /** Имена, которым в каталоге ничего не отвечает: промах в строке запуска, а не выбор. */\n    readonly unknown: readonly string[];\n}\n\n/** Разбор `--laws access,delivery`: имя без ответа — промах, и молчать о нём нельзя. */\nexport function resolveSelection(spoken: readonly string[], kind: TKind, catalog: readonly IEntryOfCatalog[]): IResolvedSelection {\n    const ids: string[] = [];\n    const unknown: string[] = [];\n\n    for (const name of spoken) {\n        const id: string | null = idOf(name, kind, catalog);\n        if (id === null) {\n            unknown.push(name.trim());\n        } else if (!ids.includes(id)) {\n            ids.push(id);\n        }\n    }\n\n    return { ids, unknown };\n}\n"]}
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../../../projects/agent-kit/src/lib/catalog.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,UAAU,EAAE,SAAS,EAAU,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnF,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,KAAK,EAAS,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAmB,cAAc,EAAE,QAAQ,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAwBrG,MAAM,KAAK,GAAW,eAAe,CAAC;AAEtC,8FAA8F;AAC9F,SAAS,YAAY,CAAC,IAAY;IAC9B,IAAI,CAAC;QACD,UAAU,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QAEjC,OAAO,IAAI,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,KAAK,CAAC;IACjB,CAAC;AACL,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,QAAgB;IAClD,MAAM,KAAK,GAA4B,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAEzD,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC9C,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,OAAO,CAAC,GAAW,EAAE,SAAiB,EAAE;IAC7C,IAAI,OAA0B,CAAC;IAC/B,IAAI,CAAC;QACD,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,EAAE,CAAC;IACd,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,GAAW,EAAE,GAAW,EAAU,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QAC5G,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACjB,KAAK,CAAC,IAAI,CAAC,GAAG,MAAM,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QACzC,CAAC;aAAM,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;QAC7E,CAAC;IACL,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,SAAiB;IACzC,MAAM,IAAI,GAAqB,QAAQ,CAAC,SAAS,CAAC,CAAC;IACnD,MAAM,OAAO,GAAsB,EAAE,CAAC;IAEtC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACvB,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,GAAW,IAAI,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;YACjD,MAAM,IAAI,GAAW,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;YAChD,MAAM,OAAO,GAAoB,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACvD,MAAM,IAAI,GAAW,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;YAC5E,MAAM,UAAU,GAAY,YAAY,CAAC,IAAI,CAAC,CAAC;YAC/C,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,GAAG,IAAI,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;QAC/G,CAAC;IACL,CAAC;IAED,OAAO,OAAO,CAAC;AACnB,CAAC;AASD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAsB,EAAE,SAAqB;IAClE,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,QAAQ,CAAC,EAAE,CAAC;QACrD,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;QACpC,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,UAAU,GAAY,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAU,EAAW,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;IAE1G,OAAO,CAAC,UAAU,IAAI,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC5D,CAAC;AAgBD;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CAAC,OAAmC,EAAE,SAAqB;IAClF,MAAM,MAAM,GAAmC,IAAI,GAAG,EAAE,CAAC;IACzD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC1B,IAAI,KAAK,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;YACzB,SAAS;QACb,CAAC;QACD,MAAM,GAAG,GAAW,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;QAClD,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,MAAM,IAAI,GAAoB,EAAE,CAAC;IACjC,KAAK,MAAM,OAAO,IAAI,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;QACpC,MAAM,IAAI,GAAW,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,IAAI,IAAI,EAAE,CAAC;QACpD,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,KAAsB,EAAW,EAAE,CAAC,cAAc,CAAC,KAAK,CAAC,OAAO,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;YACvG,SAAS;QACb,CAAC;QACD,uFAAuF;QACvF,uCAAuC;QACvC,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,KAAsB,EAAW,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YACxF,SAAS;QACb,CAAC;QACD,sFAAsF;QACtF,2BAA2B;QAC3B,MAAM,UAAU,GAAY,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAU,EAAW,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;QAC/G,IAAI,UAAU,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAsB,EAAW,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;YACtG,SAAS;QACb,CAAC;QACD,IAAI,CAAC,IAAI,CAAC;YACN,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI;YACrB,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI;YACrB,IAAI;YACJ,MAAM,EAAE,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE;YACtC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAsB,EAAU,EAAE,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;YACtF,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,KAAsB,EAAU,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC;SACjE,CAAC,CAAC;IACP,CAAC;IAED,OAAO,IAAI,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,IAAI,CAAC,MAAc,EAAE,IAAW,EAAE,OAAmC;IACjF,MAAM,MAAM,GAAW,MAAM,CAAC,IAAI,EAAE,CAAC;IACrC,MAAM,OAAO,GAAuC,CAAC,KAAsB,EAAU,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC;IAClI,MAAM,KAAK,GAAgC,OAAO,CAAC,IAAI,CACnD,CAAC,KAAsB,EAAW,EAAE,CAChC,KAAK,CAAC,IAAI,KAAK,IAAI;QACnB,CAAC,KAAK,CAAC,EAAE,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,KAAK,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC,CACrH,CAAC;IAEF,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACnC,CAAC;AAQD,wFAAwF;AACxF,MAAM,UAAU,gBAAgB,CAAC,MAAyB,EAAE,IAAW,EAAE,OAAmC;IACxG,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,OAAO,GAAa,EAAE,CAAC;IAE7B,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QACxB,MAAM,EAAE,GAAkB,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QACpD,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9B,CAAC;aAAM,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC;YAC3B,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACL,CAAC;IAED,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC","sourcesContent":["/**\n * Что пакет везёт — прочитанное с диска, до всякого выбора проекта.\n *\n * Каталог нужен отдельно от раскладки, потому что выбирать приходится раньше, чем раскладывать:\n * `init` спрашивает, какие законы взять, а `list` показывает и то, от чего проект отказался.\n * И там и там нужен полный набор, а `collectAssets` по устройству отдаёт уже отобранный.\n */\nimport { accessSync, constants, Dirent, readdirSync, readFileSync } from 'node:fs';\nimport { join } from 'node:path';\n\nimport { KINDS, TKind } from './config.js';\nimport { IAxis, IVariant, matchesVariant, readAxes, variantOf, withoutVariant } from './variants.js';\n\nexport interface IEntryOfCatalog {\n    /** Идентификатор: `laws/application/money.md`. Он же путь надстройки и ключ в `only` и `skip`. */\n    readonly id: string;\n    readonly kind: TKind;\n    /**\n     * Имя без рода, вида и расширения: `delivery`, `application/money`. Им ресурс называют в\n     * строке запуска, и им же он ложится в дерево проекта.\n     */\n    readonly name: string;\n    /** Заголовок первой строки файла; у файла без заголовка — его имя. */\n    readonly title: string;\n    /** Вид ресурса, если он лежит в пакете в нескольких: `git-workflow.github.md`. */\n    readonly variant: IVariant | null;\n    readonly text: string;\n    /**\n     * Запускается ли файл сам по себе. Гард зовут по пути, а не через оболочку, и файл без\n     * права на запуск отвечает отказом доступа — то есть ненулевым кодом, который читается как\n     * «правка отбита». Признак берётся с файла в пакете и переносится на разложенный.\n     */\n    readonly executable: boolean;\n}\n\nconst TITLE: RegExp = /^#\\s+(\\S.*)$/m;\n\n/** Запускается ли файл сам по себе. Спрашиваем систему, а не разбираем биты режима руками. */\nfunction isExecutable(path: string): boolean {\n    try {\n        accessSync(path, constants.X_OK);\n\n        return true;\n    } catch {\n        return false;\n    }\n}\n\n/** Заголовок нужен человеку, который выбирает: имена законов ему ни о чём не говорят. */\nexport function titleOf(text: string, fallback: string): string {\n    const found: RegExpMatchArray | null = text.match(TITLE);\n\n    return found ? found[1].trim() : fallback;\n}\n\n/**\n * Файлы рода — вместе с теми, что лежат в подкаталогах.\n *\n * Обход рекурсивный потому, что у законов два слоя: общий закон верен любому приложению этого\n * класса, а закон приложения — только такому, где есть деньги, локали или владеющая сущность.\n * Слой отражён каталогом, и путь внутри рода едет в идентификатор целиком, чтобы разложенное\n * повторяло раскладку пакета.\n */\nfunction filesOf(dir: string, prefix: string = ''): readonly string[] {\n    let entries: readonly Dirent[];\n    try {\n        entries = readdirSync(dir, { withFileTypes: true });\n    } catch {\n        return [];\n    }\n\n    const files: string[] = [];\n    for (const entry of [...entries].sort((one: Dirent, two: Dirent): number => one.name.localeCompare(two.name))) {\n        if (entry.isFile()) {\n            files.push(`${prefix}${entry.name}`);\n        } else if (entry.isDirectory()) {\n            files.push(...filesOf(join(dir, entry.name), `${prefix}${entry.name}/`));\n        }\n    }\n\n    return files;\n}\n\n/**\n * Всё, что лежит в ресурсах пакета. Список не выписан руками, а читается из каталога:\n * выписанный разошёлся бы с ним на первом же добавленном законе, и заметить это было бы\n * нечем — ресурс просто не приезжал бы к проекту.\n */\nexport function readCatalog(assetsDir: string): readonly IEntryOfCatalog[] {\n    const axes: readonly IAxis[] = readAxes(assetsDir);\n    const entries: IEntryOfCatalog[] = [];\n\n    for (const kind of KINDS) {\n        for (const file of filesOf(join(assetsDir, kind))) {\n            const path: string = join(assetsDir, kind, file);\n            const text: string = readFileSync(path, 'utf8');\n            const variant: IVariant | null = variantOf(file, axes);\n            const name: string = withoutVariant(file, variant).replace(/\\.[^./]+$/, '');\n            const executable: boolean = isExecutable(path);\n            entries.push({ id: `${kind}/${file}`, kind, name, title: titleOf(text, name), variant, text, executable });\n        }\n    }\n\n    return entries;\n}\n\n/** Чем проект ограничил раскладку: выбором, отказом и видами, которые он назвал. */\nexport interface ISelection {\n    readonly only: readonly string[];\n    readonly skip: readonly string[];\n    readonly variants: Readonly<Record<string, string>>;\n}\n\n/**\n * Взят ли ресурс при этом выборе.\n *\n * `only` ограничивает **только те роды, которые сам называет**. Проект, выбравший девять\n * законов из пятнадцати, шаблоны при этом не терял бы: перечисляя законы, он говорит о\n * законах, а не обо всём, что пакет везёт. Обратное правило читалось бы как «выбрал законы —\n * остался без шаблонов», и заметил бы это только тот, кто пошёл за шаблоном.\n *\n * `skip` вычитает из выбранного. Отказ от одного закона не должен требовать переписать\n * список из пятнадцати, а точечное исключение остаётся точечным.\n *\n * Вид отбирается раньше обоих: ресурс чужого хостинга не «не выбран» — его в этом дереве не\n * существует вовсе, и называть его в `skip` проекту незачем.\n */\nexport function isChosen(entry: IEntryOfCatalog, selection: ISelection): boolean {\n    if (!matchesVariant(entry.variant, selection.variants)) {\n        return false;\n    }\n    if (selection.skip.includes(entry.id)) {\n        return false;\n    }\n    const restricted: boolean = selection.only.some((id: string): boolean => id.startsWith(`${entry.kind}/`));\n\n    return !restricted || selection.only.includes(entry.id);\n}\n\n/** Ресурс, у которого виды есть, но ни один не отвечает тому, что выбрало дерево. */\nexport interface IGapOfVariant {\n    readonly kind: TKind;\n    /** Имя без вида — под ним ресурс лёг бы в дерево. */\n    readonly name: string;\n    readonly axis: string;\n    /** Что выбрало дерево по этой оси. */\n    readonly chosen: string;\n    /** Виды, которые у ресурса есть на самом деле. */\n    readonly available: readonly string[];\n    /** Идентификаторы этих видов: ими же пробел и снимается через `skip`. */\n    readonly ids: readonly string[];\n}\n\n/**\n * Ресурсы, оставшиеся без вида под выбор дерева.\n *\n * Молчаливый пропуск такого ресурса — худший из исходов. Правило поставки едет тремя видами, а\n * команды заведения задачи и сверки очереди — одним: дерево, выбравшее чужой хостинг, получает\n * правило, которое зовёт три команды, и ни одного скрипта под ними. Отказа при этом не бывает —\n * ресурс просто не приезжает, и узнают об этом, когда команда из правила не находится.\n *\n * Отсюда правило: **ресурс с видами, ни один из которых не совпал, — отказ, а не пропуск.**\n * Снимается он двумя способами, и оба явные: завести недостающий вид в пакете либо назвать\n * существующие в `skip` — дерево тем самым говорит, что обходится без этого ресурса.\n */\nexport function variantGaps(catalog: readonly IEntryOfCatalog[], selection: ISelection): readonly IGapOfVariant[] {\n    const groups: Map<string, IEntryOfCatalog[]> = new Map();\n    for (const entry of catalog) {\n        if (entry.variant === null) {\n            continue;\n        }\n        const key: string = `${entry.kind}/${entry.name}`;\n        groups.set(key, [...(groups.get(key) ?? []), entry]);\n    }\n\n    const gaps: IGapOfVariant[] = [];\n    for (const entries of groups.values()) {\n        const axis: string = entries[0].variant?.axis ?? '';\n        if (entries.some((entry: IEntryOfCatalog): boolean => matchesVariant(entry.variant, selection.variants))) {\n            continue;\n        }\n        // Отказ от ресурса — законный ответ, и повторять его отказом раскладки незачем: дерево\n        // уже сказало, что обходится без него.\n        if (entries.every((entry: IEntryOfCatalog): boolean => selection.skip.includes(entry.id))) {\n            continue;\n        }\n        // Род, суженный через `only`, отбирает ресурсы поимённо: не названный в нём ресурс не\n        // пропал — его не просили.\n        const restricted: boolean = selection.only.some((id: string): boolean => id.startsWith(`${entries[0].kind}/`));\n        if (restricted && !entries.some((entry: IEntryOfCatalog): boolean => selection.only.includes(entry.id))) {\n            continue;\n        }\n        gaps.push({\n            kind: entries[0].kind,\n            name: entries[0].name,\n            axis,\n            chosen: selection.variants[axis] ?? '',\n            available: entries.map((entry: IEntryOfCatalog): string => entry.variant?.value ?? ''),\n            ids: entries.map((entry: IEntryOfCatalog): string => entry.id),\n        });\n    }\n\n    return gaps;\n}\n\n/**\n * Идентификатор по тому, как ресурс назвали в строке запуска. Принимаются все формы, которыми\n * его называют вслух: `money`, `application/money`, `money.md` и `laws/application/money.md`.\n */\nexport function idOf(spoken: string, kind: TKind, catalog: readonly IEntryOfCatalog[]): string | null {\n    const wanted: string = spoken.trim();\n    const shortOf: (entry: IEntryOfCatalog) => string = (entry: IEntryOfCatalog): string => entry.name.split('/').pop() ?? entry.name;\n    const found: IEntryOfCatalog | undefined = catalog.find(\n        (entry: IEntryOfCatalog): boolean =>\n            entry.kind === kind &&\n            (entry.id === wanted || entry.name === wanted || shortOf(entry) === wanted || entry.id.endsWith(`/${wanted}`))\n    );\n\n    return found ? found.id : null;\n}\n\nexport interface IResolvedSelection {\n    readonly ids: readonly string[];\n    /** Имена, которым в каталоге ничего не отвечает: промах в строке запуска, а не выбор. */\n    readonly unknown: readonly string[];\n}\n\n/** Разбор `--laws access,delivery`: имя без ответа — промах, и молчать о нём нельзя. */\nexport function resolveSelection(spoken: readonly string[], kind: TKind, catalog: readonly IEntryOfCatalog[]): IResolvedSelection {\n    const ids: string[] = [];\n    const unknown: string[] = [];\n\n    for (const name of spoken) {\n        const id: string | null = idOf(name, kind, catalog);\n        if (id === null) {\n            unknown.push(name.trim());\n        } else if (!ids.includes(id)) {\n            ids.push(id);\n        }\n    }\n\n    return { ids, unknown };\n}\n"]}

package/lib/commands.d.ts

@@ -1,3 +1,4 @@
+import { IStaleBuild } from './freshness.js';
 export interface IOutcomeOfCommand {
     readonly code: number;
     readonly lines: readonly string[];
@@ -7,14 +8,34 @@ export interface IEnvironment {
     readonly root: string;
     readonly version: string;
     readonly assetsDir: string;
+    /**
+     * Ресурсы правлены позже, чем собран пакет, из которого идёт раскладка; `null` — сверять не с
+     * чем. Считается на краю, где пакет знает своё расположение: библиотечные модули работают с
+     * тем каталогом ресурсов, который им дали, и о существовании исходников не знают.
+     */
+    readonly stale?: IStaleBuild | null;
 }
+/** Куда уезжает прежнее содержимое файла, отданного пакету. */
+export declare const KEPT_SUFFIX: string;
 /**
  * Что проект выбрал при заведении конфига. Пустой список — весь набор; выбор приходит сюда
  * готовым, потому что взять его негде, кроме края: у строки запуска флаг, у терминала вопрос,
  * а у неинтерактивного прогона нет ни того ни другого — и решать это команде не по чину.
  */
-export declare function init(root: string, only?: readonly string[]): IOutcomeOfCommand;
+export declare function init(root: string, only?: readonly string[], variants?: Readonly<Record<string, string>>, assetsDir?: string): IOutcomeOfCommand;
 export declare function sync(env: IEnvironment, check: boolean): IOutcomeOfCommand;
+/**
+ * Отдать пакету файл, который лежит в дереве не от него.
+ *
+ * Пока команды не было, `sync` отказывал на такой файл поимённо и предлагал «перенести правку в
+ * надстройку или снять» — то есть работу, которую делают руками, и до неё же сводилась вся
+ * установка в живое дерево. При этом один чужой файл останавливал раскладку целиком.
+ *
+ * Молчаливой перезаписи здесь нет и быть не может: в файле лежит то, чего в дереве больше нигде
+ * нет. Поэтому переход — это переименование прежнего содержимого рядом и повторный `sync`:
+ * пакет кладёт своё, а прежнее остаётся на диске под именем с пометкой и ждёт разбора.
+ */
+export declare function adopt(env: IEnvironment, names: readonly string[]): IOutcomeOfCommand;
 export declare function doctor(env: IEnvironment): IOutcomeOfCommand;
 /**
  * Что пакет везёт и что из этого взято здесь.

package/lib/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../projects/agent-kit/src/lib/commands.ts"],"names":[],"mappings":"AAeA,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC9B;AA+DD;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,SAAS,MAAM,EAAO,GAAG,iBAAiB,CAoBlF;AAED,wBAAgB,IAAI,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAgDzE;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,iBAAiB,CAyB3D;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,YAAY,GAAG,iBAAiB,CA+CzD"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../projects/agent-kit/src/lib/commands.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAO7C,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED,2FAA2F;AAC3F,MAAM,WAAW,YAAY;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACvC;AAoDD,+DAA+D;AAC/D,eAAO,MAAM,WAAW,EAAE,MAAyB,CAAC;AAyFpD;;;;GAIG;AACH,wBAAgB,IAAI,CAChB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,SAAS,MAAM,EAAO,EAC5B,QAAQ,GAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAM,EAC/C,SAAS,GAAE,MAAW,GACvB,iBAAiB,CAgCnB;AAgBD,wBAAgB,IAAI,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,OAAO,GAAG,iBAAiB,CA2EzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB,CA+CpF;AAED,wBAAgB,MAAM,CAAC,GAAG,EAAE,YAAY,GAAG,iBAAiB,CA2C3D;AAED;;;;;GAKG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,YAAY,GAAG,iBAAiB,CAkDzD"}

package/lib/commands.js

@@ -3,14 +3,17 @@
  * а `process.exit` зовёт только точка входа — иначе ни одну из них нельзя было бы проверить
  * спекой, не перехватывая поток вывода.
  */
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { collectAssets } from './assets.js';
 import { isChosen, readCatalog } from './catalog.js';
 import { isUnfilled } from './companion.js';
 import { CONFIG_PATH, DEFAULT_LAYOUT, KINDS, OVERRIDES_DIR, readConfig } from './config.js';
+import { hooksSection, SETTINGS_PATH } from './hooks-map.js';
 import { isRefusal } from './plan.js';
 import { pendingOf, planSync, runSync } from './sync.js';
+import { placeholdersOf } from './vars.js';
+import { readAxes, unansweredAxes } from './variants.js';
 /** Что с файлом сделала раскладка. Прошедшее время здесь правда: `sync` уже записал. */
 const DONE_WORD = {
     create: 'положен',
@@ -33,11 +36,15 @@ const STATE_WORD = {
 };
 const NOT_CHOSEN = 'не выбран';
 const SKIPPED = 'пропущен';
+/** Ресурс чужого вида: в этом дереве его не существует, а не «от него отказались». */
+const OTHER_VARIANT = 'другой вид';
 const KIND_TITLE = {
     laws: 'ЗАКОНЫ',
     rules: 'ПРАВИЛА',
     patterns: 'ПАТТЕРНЫ',
+    skills: 'СКИЛЫ',
     hooks: 'ХУКИ',
+    defaults: 'УМОЛЧАНИЯ',
     checks: 'ПРОВЕРКИ',
     agents: 'АГЕНТЫ',
     commands: 'КОМАНДЫ',
@@ -51,56 +58,152 @@ const COMPANION_WORD = {
     filled: 'заполнен',
 };
 const NO_CONFIG = `нет \`${CONFIG_PATH}\` — начни с \`agent-kit init\``;
+/** Куда уезжает прежнее содержимое файла, отданного пакету. */
+export const KEPT_SUFFIX = '.before-rt-kit';
 const holes = (result) => [...result.missing].map(([asset, names]) => `  ${asset}: нет значений для ${names.map((name) => `{{${name}}}`).join(', ')}`);
 const unfilled = (result) => result.companions.filter(isUnfilled);
+/** Ось без ответа: чем её спрашивают и из чего выбирают. */
+const axisLines = (axes) => axes.flatMap((axis) => [
+    `  ${axis.name} — ${axis.question}`,
+    ...axis.options.map((option) => `      ${option.value.padEnd(8)} ${option.title}`),
+    `  выбор пишется в \`variants\` конфига: {"${axis.name}": "${axis.options[0]?.value ?? ''}"}`,
+]);
+/**
+ * Брошенное: файл лежит, а ресурс за ним больше не берут. Печатается отдельным списком и с
+ * подсказкой — стереть его пакет не вправе, а промолчать не может: агент читает такой файл как
+ * действующее правило.
+ */
+const abandonedLines = (result) => result.abandoned.length
+    ? [
+        `лежит от ресурсов, которые больше не берутся: ${result.abandoned.length}`,
+        ...result.abandoned.map((path) => `  ${path}`),
+        '  их не стирает никто: рядом может лежать написанное проектом — убирать вручную',
+    ]
+    : [];
+/**
+ * Ресурс, у которого нет вида под выбор дерева. Называется и то, чего не хватает, и оба способа
+ * это снять: отказ без действия обходят, а не исполняют.
+ */
+const gapLines = (result) => result.gaps.flatMap((gap) => [
+    `  ${gap.kind}/${gap.name} — есть только под ${gap.axis}: ${gap.available.join(', ')}, а выбран «${gap.chosen}»`,
+    `      либо заведи вид под «${gap.chosen}», либо назови в skip: ${gap.ids.join(', ')}`,
+]);
+/**
+ * Гарды, которых нет в настройке агента, и готовый кусок для неё.
+ *
+ * Кусок печатается целиком, а не одними именами: правку в свою настройку делает проект, и
+ * список «не хватает трёх» заставляет собирать JSON по памяти — там и теряется образец вызова.
+ */
+const unboundLines = (result) => result.unbound.length
+    ? [
+        `гарды разложены, но в \`${SETTINGS_PATH}\` их не зовёт никто: ${result.unbound.length}`,
+        ...result.unbound.map((binding) => `  ${binding.path} — ${binding.event}${binding.matcher ? ` ${binding.matcher}` : ''}`),
+        `  вставь в \`${SETTINGS_PATH}\` раздел \`hooks\` — готовый кусок ниже:`,
+        ...JSON.stringify({ hooks: hooksSection(result.unbound) }, null, 4)
+            .split('\n')
+            .map((line) => `  ${line}`),
+    ]
+    : [];
 const describe = (result) => [
     ...holes(result),
+    ...gapLines(result),
+    ...unboundLines(result),
     ...pendingOf(result).map((entry) => `  ${entry.path} — ${STATE_WORD[entry.outcome]}`),
     ...unfilled(result).map((entry) => `  ${entry.path} — ${COMPANION_WORD[entry.state]}`),
+    ...abandonedLines(result),
 ];
+/** Имена дырок во всех ресурсах, которые дерево берёт. Без конфига — ни одной: выбор неизвестен. */
+function placeholdersIn(config, assetsDir) {
+    if (!config) {
+        return [];
+    }
+    const names = [];
+    for (const asset of collectAssets(config, assetsDir)) {
+        for (const name of placeholdersOf(asset.text)) {
+            if (!names.includes(name)) {
+                names.push(name);
+            }
+        }
+    }
+    return names.sort();
+}
 /**
  * Что проект выбрал при заведении конфига. Пустой список — весь набор; выбор приходит сюда
  * готовым, потому что взять его негде, кроме края: у строки запуска флаг, у терминала вопрос,
  * а у неинтерактивного прогона нет ни того ни другого — и решать это команде не по чину.
  */
-export function init(root, only = []) {
+export function init(root, only = [], variants = {}, assetsDir = '') {
     const path = join(root, CONFIG_PATH);
     if (existsSync(path)) {
         return { code: 0, lines: [`${CONFIG_PATH} уже есть — оставлен как есть`] };
     }
-    const config = { vars: {}, layout: DEFAULT_LAYOUT, only, skip: [] };
+    const config = { vars: {}, layout: DEFAULT_LAYOUT, variants, only, skip: [] };
     mkdirSync(join(root, OVERRIDES_DIR), { recursive: true });
     mkdirSync(join(root, CONFIG_PATH, '..'), { recursive: true });
     writeFileSync(path, `${JSON.stringify(config, null, 4)}\n`, 'utf8');
+    // Значения, которых пакет ждёт от дерева, называются здесь, а не отказом раскладки: узнать
+    // о них на первом же `sync` значит начать установку с ошибки, притом что список известен
+    // сразу — он вычитывается из текстов выбранных ресурсов.
+    const wanted = assetsDir ? placeholdersIn(readConfig(root), assetsDir) : [];
     return {
         code: 0,
         lines: [
             `заведён ${CONFIG_PATH}`,
             only.length ? `выбрано ресурсов: ${only.length}` : 'выбрано всё, что везёт пакет',
+            ...Object.entries(variants).map(([axis, value]) => `${axis}: ${value}`),
             `заведён ${OVERRIDES_DIR}/ — надстройки проекта кладутся сюда путём ресурса`,
-            'дальше: заполни `vars` и запусти `agent-kit sync`',
+            ...(wanted.length
+                ? [
+                    `значения, которых ждут ресурсы, — впиши их в \`vars\` конфига: ${wanted.length}`,
+                    ...wanted.map((name) => `  {{${name}}}`),
+                ]
+                : []),
+            'дальше: `agent-kit sync`, а своё дописывается в `.claude/rt-kit/gate-map.sh` и `project.sh`',
         ],
     };
 }
+/**
+ * Отказ на устаревшей сборке. Раскладка из неё положила бы прежнюю редакцию ресурса и назвала
+ * это сделанным: неправда дороже отказа — её замечают, когда правленое правило не действует.
+ */
+const staleRefusal = (stale) => ({
+    code: 1,
+    lines: [
+        'раскладка не начата: строка запуска читает собранное, а ресурсы правлены позже',
+        `  правлено: ${stale.newest}`,
+        `  исходные ресурсы: ${stale.source}`,
+        '  собери пакет и повтори',
+    ],
+});
 export function sync(env, check) {
     const { root, version, assetsDir } = env;
     const config = readConfig(root);
     if (!config) {
         return { code: 1, lines: [NO_CONFIG] };
     }
+    if (env.stale) {
+        return staleRefusal(env.stale);
+    }
+    // Ось без ответа отбивает раскладку целиком, а не пропускает свои ресурсы молча: правило
+    // поставки бывает в трёх видах, и дерево, не назвавшее свой, осталось бы вовсе без правила
+    // поставки — заметить это можно было бы только по тому, что гейт перестал его требовать.
+    const unanswered = unansweredAxes(readAxes(assetsDir), config.variants);
+    if (unanswered.length) {
+        return { code: 1, lines: ['раскладка не начата: не выбран вид', ...axisLines(unanswered)] };
+    }
     if (check) {
         const result = planSync(config, root, version, assetsDir);
         const pending = pendingOf(result);
         // Незаполненный компаньон — такое же расхождение, как отставший файл: правило разложено,
         // а имён этого дерева при нём нет, и агент читает указание, которому некуда примениться.
         const empty = unfilled(result);
-        if (!result.missing.size && !pending.length && !empty.length) {
+        // Гард, которого не зовёт настройка агента, — такое же расхождение, как отставший файл:
+        // он разложен, он коммитится, и по дереву его не отличить от работающего.
+        const count = result.missing.size + result.gaps.length + pending.length + empty.length + result.unbound.length;
+        if (!count) {
             return { code: 0, lines: [`sync --check: разложенное сходится с пакетом v${version}`] };
         }
-        return {
-            code: 1,
-            lines: [`sync --check: расхождений ${result.missing.size + pending.length + empty.length}`, ...describe(result)],
-        };
+        return { code: 1, lines: [`sync --check: расхождений ${count}`, ...describe(result)] };
     }
     const result = runSync(config, root, version, assetsDir);
     // Перечисляются только дырки: раскладка не начата, и назвать файл «положенным» значило бы
@@ -108,6 +211,14 @@ export function sync(env, check) {
     if (result.missing.size) {
         return { code: 1, lines: ['раскладка не начата: нечего подставить в дырки', ...holes(result)] };
     }
+    // Ресурс без вида под выбор дерева отбивает раскладку целиком, а не выпадает из неё молча:
+    // правило, разложенное без инструмента, который оно зовёт, читается как действующее.
+    if (result.gaps.length) {
+        return {
+            code: 1,
+            lines: ['раскладка не начата: у этих ресурсов нет вида под выбор дерева', ...gapLines(result)],
+        };
+    }
     const refused = result.planned.filter((entry) => isRefusal(entry.outcome));
     if (refused.length) {
         return {
@@ -116,14 +227,74 @@ export function sync(env, check) {
                 'раскладка не начата: эти файлы пакет переписывать не станет',
                 ...refused.map((entry) => `  ${entry.path} — ${DONE_WORD[entry.outcome]}`),
                 'правку надо либо перенести в надстройку, либо снять — и повторить',
+                `положенное не пакетом отдаётся ему командой \`agent-kit adopt\`: прежнее содержимое ляжет рядом с пометкой \`${KEPT_SUFFIX}\``,
             ],
         };
     }
+    // Раскладка удалась, а гарды могут остаться неподключёнными: настройка агента принадлежит
+    // дереву, и пакет в неё не пишет. Код возврата остаётся нулевым — файлы легли, — но молчать
+    // об этом нельзя: узнают иначе, когда что-нибудь пройдёт мимо гарда.
     return {
         code: 0,
-        lines: result.written.length
-            ? [`разложено файлов: ${result.written.length}`, ...result.written.map((path) => `  ${path}`)]
-            : ['всё уже разложено'],
+        lines: [
+            ...(result.written.length
+                ? [`разложено файлов: ${result.written.length}`, ...result.written.map((path) => `  ${path}`)]
+                : ['всё уже разложено']),
+            ...unboundLines(result),
+        ],
+    };
+}
+/**
+ * Отдать пакету файл, который лежит в дереве не от него.
+ *
+ * Пока команды не было, `sync` отказывал на такой файл поимённо и предлагал «перенести правку в
+ * надстройку или снять» — то есть работу, которую делают руками, и до неё же сводилась вся
+ * установка в живое дерево. При этом один чужой файл останавливал раскладку целиком.
+ *
+ * Молчаливой перезаписи здесь нет и быть не может: в файле лежит то, чего в дереве больше нигде
+ * нет. Поэтому переход — это переименование прежнего содержимого рядом и повторный `sync`:
+ * пакет кладёт своё, а прежнее остаётся на диске под именем с пометкой и ждёт разбора.
+ */
+export function adopt(env, names) {
+    const { root, version, assetsDir } = env;
+    const config = readConfig(root);
+    if (!config) {
+        return { code: 1, lines: [NO_CONFIG] };
+    }
+    const foreign = planSync(config, root, version, assetsDir).planned.filter((entry) => entry.outcome === 'foreign');
+    if (!foreign.length) {
+        return { code: 0, lines: ['чужих файлов на путях пакета нет'] };
+    }
+    // Имена принимаются как их печатает `sync`: путём в дереве. Без имён отдаются все — на
+    // свежей установке их бывает столько же, сколько ресурсов, и перечислять их руками значит
+    // делать ту же работу, ради которой команда заведена.
+    const wanted = names.length
+        ? foreign.filter((entry) => names.some((name) => entry.path.endsWith(name)))
+        : foreign;
+    if (!wanted.length) {
+        return {
+            code: 1,
+            lines: ['ни одно имя не отвечает чужому файлу; чужие сейчас такие:', ...foreign.map((e) => `  ${e.path}`)],
+        };
+    }
+    const moved = [];
+    const blocked = [];
+    for (const entry of wanted) {
+        const path = join(root, entry.path);
+        const kept = `${path}${KEPT_SUFFIX}`;
+        if (existsSync(kept)) {
+            blocked.push(`  ${entry.path}${KEPT_SUFFIX} — уже лежит, разбери его прежде`);
+            continue;
+        }
+        renameSync(path, kept);
+        moved.push(`  ${entry.path} → ${entry.path}${KEPT_SUFFIX}`);
+    }
+    return {
+        code: blocked.length ? 1 : 0,
+        lines: [
+            ...(moved.length ? [`прежнее содержимое отложено: ${moved.length}`, ...moved, 'дальше: `agent-kit sync`'] : []),
+            ...(blocked.length ? ['не тронуто:', ...blocked] : []),
+        ],
     };
 }
 export function doctor(env) {
@@ -139,12 +310,26 @@ export function doctor(env) {
     }
     const catalog = readCatalog(assetsDir);
     const taken = collectAssets(config, assetsDir).length;
+    const unanswered = unansweredAxes(readAxes(assetsDir), config.variants);
+    const chosen = Object.entries(config.variants).map(([axis, value]) => `${axis}: ${value}`);
+    // Ресурс чужого вида в «не выбрано» не идёт: проект от него не отказывался — его в этом
+    // дереве не существует, как не существует второго правила поставки.
+    const foreignVariant = catalog.filter((entry) => entry.variant !== null && config.variants[entry.variant.axis] !== entry.variant.value);
+    const other = foreignVariant.length;
+    // Ресурс, названный и в отказе, и чужим видом, считается один раз — иначе «не выбрано»
+    // уходит в минус, а минус в отчёте читается как поломка счёта, а не как двойной счёт.
+    const skipped = config.skip.filter((id) => foreignVariant.every((entry) => entry.id !== id)).length;
     const lines = [
         `пакет v${version}, везёт ресурсов ${catalog.length}, взято ${taken}`,
-        `не выбрано: ${catalog.length - taken - config.skip.length}, пропущено: ${config.skip.length}`,
+        `не выбрано: ${catalog.length - taken - skipped - other}, пропущено: ${skipped}, другой вид: ${other}`,
         `значений в конфиге: ${Object.keys(config.vars).length}`,
+        ...chosen,
         ...[...counted].map(([outcome, count]) => `${STATE_WORD[outcome]}: ${count}`),
         ...describe(result),
+        ...(unanswered.length ? ['не выбран вид — раскладка не начнётся:', ...axisLines(unanswered)] : []),
+        // Про устаревшую сборку `doctor` говорит, но отказом её не считает: он ничего не пишет,
+        // и прочитать состояние дерева можно и из вчерашней сборки — знать бы, что она вчерашняя.
+        ...(env.stale ? ['собранное отстало от исходников — раскладка откажет:', `  правлено: ${env.stale.newest}`] : []),
     ];
     return { code: 0, lines };
 }
@@ -168,10 +353,13 @@ export function list(env) {
         if (!config) {
             return 'везёт пакет';
         }
+        if (entry.variant && config.variants[entry.variant.axis] !== entry.variant.value) {
+            return OTHER_VARIANT;
+        }
         if (config.skip.includes(entry.id)) {
             return SKIPPED;
         }
-        if (!isChosen(entry, config.only, config.skip)) {
+        if (!isChosen(entry, config)) {
             return NOT_CHOSEN;
         }
         const outcome = planned.get(entry.id);