@rt-tools/agent-kit 0.8.3 → 0.9.1

package/README.md

@@ -293,6 +293,27 @@ npx agent-kit propose --dry-run   # что уехало бы
 npx agent-kit propose             # отправить груз в приём
 ```
 
+Чтобы грузу было чем представиться, у дерева должен быть токен. Путей завести его два, и
+человек выбирает доводом:
+
+```bash
+npx agent-kit enroll --code <код приглашения>   # обменять приглашение на токен
+npx agent-kit enroll --token <токен>            # положить токен, выданный в админке приёма
+```
+
+**Обмен по коду.** Код одноразовый и годен ограниченное время; имя дерева называет приглашение,
+а не обращение. Адрес приёма без TLS команда отбивает у себя, не доходя до сети: токен уходит
+единственным ответом на обращение.
+
+**Выданный токен.** Владелец приёма выдаёт токен прямо в админке и передаёт его человеку;
+обменивать не на что, и в сеть команда не идёт вовсе — ни адрес приёма, ни TLS этому пути не
+нужны.
+
+Два довода вместе не идут, и ни одного — тоже: отказ называет оба пути. Токен ложится одинаково,
+каким бы путём ни пришёл: файл, названный ключом `token`, правами «читает только владелец файла».
+Лежащий токен команда молча не перезаписывает ни на одном из путей — для этого есть довод
+`--force`.
+
 Груз уезжает при каждом прогоне тремя родами: **сводка наблюдений со снимком надстроек**,
 **предложения** с адресом «пакет» — когда они есть — и **разборы происшествий**. Прогон без
 замечаний тоже говорит, чем пользовались, чем не пользовались ни разу и что дерево

package/assets/checks/board.github.mjs

@@ -203,8 +203,55 @@ export function fetchIssue(number, options) {
     }
 }
 
+/**
+ * Вершина берётся вместе с остальным: спросить её потом значило бы второй вызов на каждый PR,
+ * а судят по ней и папку задачи, и прогон.
+ */
 export function fetchOpenPulls(options) {
-    return ghJson(['pr', 'list', '--state', 'open', '--limit', '200', '--json', 'number,title,headRefName,body'], options);
+    return ghJson(
+        ['pr', 'list', '--state', 'open', '--limit', '200', '--json', 'number,title,headRefName,headRefOid,isDraft,body'],
+        options
+    );
+}
+
+/**
+ * Сколько прогонов завелось на этой вершине.
+ *
+ * Спрашивается вершина, а не ветка: прогон промежуточного коммита о состоянии вершины не
+ * говорит ничего, а список прогонов ветки отдаёт их вперемешку.
+ */
+export function runsOnHead(sha, options) {
+    const answer = gh(['api', `repos/${OWNER}/${REPO}/actions/runs?head_sha=${sha}&per_page=1`, '--jq', '.total_count'], options);
+    return Number(String(answer).trim());
+}
+
+/**
+ * Чем кончились прогоны на этой вершине: `success`, если все завершились успехом, `running`,
+ * если хоть один ещё идёт, `failure` — если хоть один упал. Прогонов нет вовсе — `none`.
+ *
+ * Цвет спрашивается отдельно от факта: факт отвечает на вопрос «событие дошло», цвет — на
+ * вопрос «работу можно отдавать». Второй вопрос задаётся там, где готовое стоит черновиком.
+ */
+export function verdictOnHead(sha, options) {
+    const answer = gh(
+        [
+            'api',
+            `repos/${OWNER}/${REPO}/actions/runs?head_sha=${sha}&per_page=20`,
+            '--jq',
+            '[.workflow_runs[] | {status, conclusion}] | if length == 0 then "none"' +
+                ' elif any(.status != "completed") then "running"' +
+                ' elif any(.conclusion != "success") then "failure"' +
+                ' else "success" end',
+        ],
+        options
+    );
+    return String(answer).trim();
+}
+
+/** Когда вершина легла в ветку — по времени коммита у хостинга, а не по местным часам ветки. */
+export function headCommittedAt(sha, options) {
+    const answer = gh(['api', `repos/${OWNER}/${REPO}/commits/${sha}`, '--jq', '.commit.committer.date'], options);
+    return Date.parse(String(answer).trim());
 }
 
 /** `[<КЛЮЧ>-<номер>]` в начале заголовка — единственная форма номера в названиях */

package/assets/checks/check-board.github.mjs

@@ -19,12 +19,16 @@
  * Момент, когда задачу берут в работу, отсюда не виден вовсе — ветки на борде нет, —
  * и «In progress» здесь не требуется ни от кого.
  *
+ * Прогон на вершине спрашивает тоже она: страница PR без прогона выглядит так же, как
+ * страница с зелёным, — цвета у неё нет ни там, ни там, — и вершина, за которой прогон
+ * не встал, узнаётся только тем, что кто-то открыл список прогонов руками.
+ *
  * Нет сети или нет токена — код возврата ноль: проверка, падающая в самолёте,
  * перестаёт что-либо значить.
  *
  * Ненулевой код возврата и перечень расхождений.
  */
-import { statSync } from 'node:fs';
+import { existsSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
 import {
@@ -39,9 +43,12 @@ import {
     fetchIssues,
     fetchOpenPulls,
     gh,
+    headCommittedAt,
     numberFromTaskDir,
     numberFromTitle,
+    runsOnHead,
     taskDirs,
+    verdictOnHead,
 } from './board.mjs';
 import { CONFIG, ROOT } from './rt-kit-checks.config.mjs';
 
@@ -49,6 +56,17 @@ const IN_REVIEW = STATUS_OPTIONS[IN_REVIEW_STATUS].name;
 const TASKS_DIR = join(ROOT, CONFIG.tasksDir);
 /** Возраст брошенного черновика, после которого он перестаёт выглядеть начатым сегодня. */
 const DRAFT_DAYS = 7;
+/**
+ * Сколько времени вершине даётся на то, чтобы прогон за ней встал. Событие доходит до хостинга
+ * не мгновенно, и сверка, позванная сразу после пуша, иначе краснела бы на здоровой ветке.
+ */
+const RUN_GRACE_MINUTES = 10;
+/**
+ * Конвейер дерева. Прогоны спрашиваются только там, где ему есть откуда взяться: дерево без
+ * конвейера получило бы строку на каждый открытый PR, и не о чём.
+ */
+const PIPELINE = CONFIG.pushGate?.pipelineFile ?? '';
+const HAS_PIPELINE = PIPELINE !== '' && existsSync(join(ROOT, PIPELINE));
 
 const problems = [];
 const report = (message) => problems.push(message);
@@ -104,6 +122,62 @@ function folderInBranch(branch, options) {
     }
 }
 
+/**
+ * Прогон на вершине открытого PR.
+ *
+ * Молчание страницы и зелёный прогон читаются одинаково, а событие до хостинга доходит не
+ * всегда: в час его отказов пуш прошёл, а прогона за ним не встало. Сверка называет такую
+ * вершину, пока PR ещё открыт, — после слияния об этом узнавать поздно.
+ *
+ * Считается сам факт прогона, а не его цвет. Идущий и упавший прогон видны на странице PR оба;
+ * невидимо только отсутствие, и говорит сверка ровно о нём.
+ *
+ * Свежая вершина не судится: между пушем и прогоном проходит время, и красная строка на этом
+ * промежутке значила бы «подожди», а не «чини».
+ */
+function checkHeadRun(pull, options) {
+    if (runsOnHead(pull.headRefOid, options) > 0) {
+        checkReadyDraft(pull, options);
+        return;
+    }
+
+    const minutes = Math.floor((Date.now() - headCommittedAt(pull.headRefOid, options)) / 60000);
+    if (minutes < RUN_GRACE_MINUTES) {
+        return;
+    }
+
+    report(
+        `PR #${pull.number}: на вершине ${pull.headRefOid.slice(0, 8)} прогона нет, а лежит она ${minutes} мин — ` +
+            `конвейер события не получил; верни его новым коммитом либо перезакрытием PR ` +
+            `(gh pr close ${pull.number} && gh pr reopen ${pull.number})`
+    );
+}
+
+/**
+ * Готовая работа, оставленная черновиком.
+ *
+ * У черновика кнопка слияния заблокирована самим хостингом, поэтому зелёная страница PR
+ * владельцу ничего не разрешает: список, в котором всё серое, читается как «работа не сделана».
+ * Гард снятия черновика сюда не достаёт — он судит один ход и молчит, пока ветка везёт папку
+ * своей задачи; сверка же смотрит на состояние очереди целиком.
+ *
+ * Четыре PR так и простояли черновиками двое суток — разбор
+ * `docs/postmortems/2026-08-18-ready-work-left-in-drafts.md`.
+ */
+function checkReadyDraft(pull, options) {
+    if (pull.isDraft !== true) {
+        return;
+    }
+    if (verdictOnHead(pull.headRefOid, options) !== 'success') {
+        return;
+    }
+
+    report(
+        `PR #${pull.number}: прогон на вершине ${pull.headRefOid.slice(0, 8)} зелёный, а PR черновик — ` +
+            `разбери папку задачи и сними черновик (gh pr ready ${pull.number}) либо скажи владельцу, чего ждёшь`
+    );
+}
+
 let checked = { issues: 0, pulls: 0 };
 
 // Черновики судятся по диску и потому проверяются всегда: связи для этого не нужно.
@@ -160,6 +234,10 @@ try {
         // сверка обязана назвать ДО слияния: гард судит её на слиянии, а слияние нажимает
         // человек в браузере, где хуков нет вовсе. Сказанная после, эта строка уже не чинится
         // тем же PR — работа перешла дальше, и на разбор заводится вторая задача.
+        if (HAS_PIPELINE && pull.headRefOid) {
+            checkHeadRun(pull, options);
+        }
+
         if (!FOLDER_SKIP.test(String(pull.body ?? '')) && pull.headRefName) {
             const folder = folderInBranch(pull.headRefName, options);
             if (folder !== null) {
@@ -210,6 +288,11 @@ try {
     }
 }
 
+// Непроверенное называется вслух: молчание о прогонах читалось бы как «прогоны на месте».
+if (!offline && !HAS_PIPELINE) {
+    console.log('check-board: прогоны на вершинах не спрашивались — файла конвейера в дереве нет');
+}
+
 if (problems.length > 0) {
     console.error(`check-board: расхождений ${problems.length}\n`);
     problems.forEach((problem) => console.error(`  ${problem}`));