@rt-tools/agent-kit 0.15.0 → 0.16.1

package/assets/checks/archive-age.mjs

@@ -0,0 +1,107 @@
+/**
+ * Возраст записей описания прошлого.
+ *
+ * Каталог набирает по записи на каждую закрытую работу и не отдаёт обратно ничего: папку
+ * задачи разбирает паттерн закрытия работы, и запись оттуда переживает всё дерево. Срок
+ * назначает дерево ключом настройки; пакет умолчания не даёт — установка новой версии не
+ * вправе начать сносить чужой архив, а снимается там разбор просьбы, которого нет больше нигде.
+ *
+ * Отбор живёт здесь один на двоих: команда чистки снимает по нему, проверка по нему же
+ * краснеет. Разойдясь, они говорили бы о каталоге разное, а заметить это нечем — чистка молча
+ * оставляла бы то, на что проверка молча не смотрит.
+ *
+ * Возраст меряется датой последнего коммита файла. Время файла на диске не годится: свежий
+ * чекаут делает все записи одновременными, и чистка на чужой машине не сняла бы ни одной.
+ * Шапка записи не годится тоже — день слияния стоит в ней не всегда и не всюду одинаково.
+ *
+ * Запись, которой в истории ещё нет, считается сегодняшней: она приехала этой же веткой и
+ * перестоять не могла.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CONFIG } from './rt-kit-checks.config.mjs';
+
+/** Каталог описания прошлого — без завершающей косой черты: её несёт настройка. */
+export const ARCHIVE_DIR = CONFIG.archiveDir.replace(/\/$/, '');
+
+/**
+ * Срок хранения записи в сутках. `null` — срок не назначен, и тогда молчат обе стороны:
+ * проверка не краснеет, чистка не снимает. Дерево называет своё число ключом настройки.
+ */
+export const RETENTION_DAYS = CONFIG.archiveRetentionDays ?? null;
+
+/** Сутки в миллисекундах — считать возраст удобнее в них. */
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Дата последнего коммита у каждой записи каталога.
+ *
+ * Один проход по истории вместо вызова на файл: на трёх сотнях записей это разница между
+ * секундой и полуминутой. Лог идёт новыми вперёд, поэтому первая встреченная дата файла и есть
+ * последняя.
+ */
+function lastCommitDates(root) {
+    const log = execFileSync('git', ['log', '--format=%cI', '--name-only', '--', ARCHIVE_DIR], {
+        cwd: root,
+        encoding: 'utf8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+
+    const dates = new Map();
+    let current = null;
+
+    for (const line of log.split('\n')) {
+        if (line === '') {
+            continue;
+        }
+
+        if (line.startsWith(`${ARCHIVE_DIR}/`)) {
+            if (current !== null && !dates.has(line)) {
+                dates.set(line, current);
+            }
+
+            continue;
+        }
+
+        current = line;
+    }
+
+    return dates;
+}
+
+/**
+ * Записи каталога с их возрастом в сутках.
+ *
+ * @param root Корень дерева.
+ * @param now Момент отсчёта — передаётся, чтобы проверка и чистка судили по одному времени.
+ * @returns Записи: путь, дата последнего коммита и возраст в сутках.
+ */
+export function archiveRecords(root, now = new Date()) {
+    if (!existsSync(join(root, ARCHIVE_DIR))) {
+        return [];
+    }
+
+    const dates = lastCommitDates(root);
+
+    return readdirSync(join(root, ARCHIVE_DIR))
+        .filter((name) => name.endsWith('.md'))
+        .map((name) => {
+            const path = `${ARCHIVE_DIR}/${name}`;
+            const committed = dates.get(path);
+            const ageDays = committed === undefined ? 0 : (now.getTime() - new Date(committed).getTime()) / DAY_MS;
+
+            return { path, name, committed, ageDays };
+        })
+        .sort((one, other) => other.ageDays - one.ageDays);
+}
+
+/** Записи, перестоявшие срок. Срок не назначен — перестоявших нет ни одной. */
+export function staleRecords(root, now = new Date()) {
+    if (RETENTION_DAYS === null) {
+        return [];
+    }
+
+    return archiveRecords(root, now).filter((record) => record.ageDays > RETENTION_DAYS);
+}

package/assets/checks/archive-prune.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * Чистка описания прошлого по сроку.
+ *
+ * Запись живёт назначенный деревом срок, дальше снимается из дерева и остаётся в истории
+ * системы контроля версий — достать её оттуда можно по имени файла, оно же единственный
+ * указатель каталога.
+ *
+ * Сухой прогон — умолчание. Команда сносит разбор просьбы — единственную запись слов
+ * владельца, — и снос называется явно: `--apply`. Перечень снимаемого печатается в обоих
+ * случаях одинаково, чтобы решение принималось по тому же списку, который потом уедет.
+ *
+ * Срок и отбор берутся у `archive-age.mjs` — того же модуля, по которому краснеет проверка.
+ */
+import { execFileSync } from 'node:child_process';
+
+import { RETENTION_DAYS, archiveRecords, staleRecords } from './archive-age.mjs';
+import { ROOT } from './rt-kit-checks.config.mjs';
+
+if (RETENTION_DAYS === null) {
+    console.log('archive-prune: срок хранения описания прошлого деревом не назначен — снимать нечего');
+    process.exit(0);
+}
+
+const apply = process.argv.includes('--apply');
+const stale = staleRecords(ROOT);
+const total = archiveRecords(ROOT).length;
+
+if (stale.length === 0) {
+    console.log(`archive-prune: записей ${total}, перестоявших срок в ${RETENTION_DAYS} суток нет`);
+    process.exit(0);
+}
+
+console.log(`archive-prune: перестояло ${stale.length} из ${total} при сроке в ${RETENTION_DAYS} суток`);
+
+for (const record of stale) {
+    console.log(`  ${record.name} — ${Math.floor(record.ageDays)} суток, последний коммит ${record.committed.slice(0, 10)}`);
+}
+
+if (!apply) {
+    console.log('\nЭто сухой прогон: не снято ничего. Снос идёт доводом --apply.');
+    process.exit(0);
+}
+
+execFileSync('git', ['rm', '--quiet', '--', ...stale.map((record) => record.path)], { cwd: ROOT, stdio: 'inherit' });
+console.log(`\nСнято записей: ${stale.length}. Они остаются в истории — найти их можно по имени файла.`);

package/assets/checks/check-archive-age.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+/**
+ * Сверка срока хранения описания прошлого.
+ *
+ * Одной чистки хватает ровно на срок: каталог набирает по записи на каждую закрытую работу, и
+ * первая уцелевшая перестаивает снова. Без сверки срок держался бы памятью того, кто помнит
+ * про команду чистки, — то есть не держался бы вовсе.
+ *
+ * Сверка не чистит: снос — решение, а не следствие проверки. Она называет перестоявшие записи
+ * и команду, которой их снимают.
+ *
+ * FAIL-OPEN: срок деревом не назначен — сверять нечего, нулевой код. Умолчания у срока нет
+ * намеренно: пакет, назначивший его за дерево, начал бы сносить чужой архив в день установки.
+ * Каталога нет — то же самое. Пустой каталог отказом не считается: он означает, что всё снято
+ * по сроку.
+ *
+ * Ненулевой код возврата и перечень перестоявших записей.
+ */
+import { ARCHIVE_DIR, RETENTION_DAYS, archiveRecords, staleRecords } from './archive-age.mjs';
+import { ROOT } from './rt-kit-checks.config.mjs';
+
+if (RETENTION_DAYS === null) {
+    console.log('check-archive-age: срок хранения описания прошлого деревом не назначен — сверять нечего');
+    process.exit(0);
+}
+
+const total = archiveRecords(ROOT).length;
+const stale = staleRecords(ROOT);
+
+if (stale.length > 0) {
+    console.error(`check-archive-age: расхождений ${stale.length}`);
+
+    for (const record of stale) {
+        console.error(`  ${record.path}: ${Math.floor(record.ageDays)} суток при сроке в ${RETENTION_DAYS}`);
+    }
+
+    console.error(`\nЗапись живёт ${RETENTION_DAYS} суток и снимается: \`node tools/archive-prune.mjs --apply\`.`);
+    console.error('Снятая остаётся в истории — найти её можно по имени файла.');
+    process.exit(1);
+}
+
+console.log(`check-archive-age: записей ${total} в ${ARCHIVE_DIR}, ни одна не перестояла срок в ${RETENTION_DAYS} суток`);

package/assets/checks/rt-kit-checks.config.mjs

@@ -36,6 +36,13 @@ const DEFAULTS = {
     docsDir: 'docs',
     /** Отложенное: про него проверки молчат — оно описывает прошлое, а не дерево. */
     archiveDir: 'docs/archive/',
+    /**
+     * Сколько суток живёт запись описания прошлого. `null` — срок не назначен, и тогда молчат
+     * обе стороны: сверка не краснеет, чистка не снимает. Умолчания у срока нет намеренно —
+     * пакет, назначивший его за дерево, начал бы сносить чужой архив в день установки, а
+     * снимается там разбор просьбы, которого нет больше нигде.
+     */
+    archiveRetentionDays: null,
     /**
      * Каталоги, чей указатель сверяется с содержимым: обзорный документ в них перечисляет
      * записи таблицей, и читатель ищет по ней, а не обходом. Пусто — сверки указателя нет.

package/assets/defaults/project.sh

@@ -88,7 +88,7 @@ rt_push_checks_default() {
 
     for check in check-doc-paths check-specs check-file-size check-dupes check-styles \
         check-lib-layers check-reuse check-schema-drift check-states check-state-next \
-        check-turn-map check-push-gate; do
+        check-turn-map check-archive-age check-push-gate; do
         [ -f "$root/$RT_CHECKS_DIR/$check.mjs" ] && printf '%s\n' "node $RT_CHECKS_DIR/$check.mjs"
     done
 

package/assets/hooks/proposal-guard.sh

@@ -82,11 +82,27 @@ verdict="$(tail -n 400 "$transcript" 2>/dev/null | jq -s -r --arg asked "$asked_
 
 [ "$verdict" = "owe" ] || exit 0
 
+# Команда отправки называется той, которая в этом дереве исполняется. Дерево, поставившее пакет
+# зависимостью, зовёт бинарь из зависимостей; дерево, где пакет живёт исходниками, бинаря не
+# имеет вовсе — там зовут собранный bin. Названная наугад команда стоит исполнителю хода: отказ
+# читается как указание, и вызов `npx agent-kit` отвечает в таком дереве отказом установки.
+root="${CLAUDE_PROJECT_DIR:-.}"
+if [ -x "$root/node_modules/.bin/agent-kit" ]; then
+    propose_cmd="npx agent-kit propose"
+else
+    built="$(ls "$root"/dist/*/bin/agent-kit.js 2>/dev/null | head -1)"
+    if [ -n "$built" ]; then
+        propose_cmd="node ${built#"$root"/} propose"
+    else
+        propose_cmd="npx agent-kit propose"
+    fi
+fi
+
 reason="BLOCKED by proposal-guard: владелец сказал завести или отправить предложение слою правил, а отправки в этом ходе не было. Написанное и не отправленное лежит в дереве неотличимо от отправленного: своей записи в слое правил у него нет, и владелец читает работу сделанной, пока не спросит прямо.
 
 Предложение пишется файлом в \`$proposals_dir/\` и уезжает в тот же ход:
 
-    npx agent-kit propose
+    $propose_cmd
 
 Сухой прогон отправкой не является: он показывает, что уехало бы, и следа наружу не оставляет. Отправка пишет отметки в файлы предложений и делает дерево грязным — при открытом PR они ложатся вторым коммитом в ту же ветку, и это их место, а не повод отложить.
 

package/assets/rules/doc-style.md

@@ -125,6 +125,17 @@ flowchart TD
   пишется способом её спросить: команда и то, с чем сверять ответ, вместо снимка ответа.
   <!-- rt-when: *.md -->
 
+- **У записи описания прошлого есть срок, и после него запись снимается.** Каталог набирает по
+  записи на каждую закрытую работу и не отдаёт обратно ничего. Снятая остаётся в истории —
+  достают её тем же именем файла, которым ищут живую. Срок называет дерево ключом настройки;
+  умолчания у него нет, потому что снимается там разбор просьбы, которого нет больше нигде.
+  <!-- rt-when: *.md -->
+
+- **Ссылка на запись описания прошлого в живом тексте живёт ровно до её срока.** Проверка
+  адресов архив не читает вовсе, поэтому мёртвая ссылка краснеет не в нём, а в том тексте,
+  который сослался. Живой текст называет решение словами, а не адресом записи.
+  <!-- rt-when: *.md -->
+
 ## Чего из закона здесь нет
 
 Ни одна из формулировочных договорённостей не проверяется: одна фраза на правило, простые

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rt-tools/agent-kit",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "Переносимый слой правил для агента: законы, хуки, проверки и агенты, раскладываемые в репозиторий одной командой",
   "author": "RT Team",
   "license": "Apache-2.0",