devcontour-harness 0.1.0-alpha.28 → 0.1.0-alpha.30
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +36 -2
- package/docs/architecture.md +80 -0
- package/docs/compatibility.md +15 -14
- package/docs/contracts.md +244 -26
- package/docs/release-notes/0.1.0-alpha.29.md +32 -0
- package/docs/release-notes/0.1.0-alpha.30.md +40 -0
- package/docs/review-probes.md +23 -20
- package/docs/toolchains.md +12 -1
- package/docs/upgrade.md +124 -0
- package/lib/agents/review-probe.d.ts +1 -0
- package/lib/agents/review-probe.js +38 -0
- package/lib/cli.js +57 -1
- package/lib/contracts/cli.d.ts +1150 -22
- package/lib/contracts/cli.js +129 -4
- package/lib/contracts/events.d.ts +642 -3
- package/lib/contracts/events.js +48 -0
- package/lib/contracts/index.d.ts +1 -0
- package/lib/contracts/index.js +1 -0
- package/lib/contracts/ports.d.ts +5 -1
- package/lib/contracts/published.d.ts +559 -2
- package/lib/contracts/published.js +2 -0
- package/lib/contracts/report.d.ts +1149 -0
- package/lib/contracts/report.js +401 -0
- package/lib/control/harness.d.ts +454 -1
- package/lib/control/harness.js +83 -1
- package/lib/control/report-file.d.ts +19 -0
- package/lib/control/report-file.js +85 -0
- package/lib/control/report.d.ts +9 -0
- package/lib/control/report.js +27 -0
- package/lib/engine/engine.d.ts +5 -1
- package/lib/engine/engine.js +49 -7
- package/lib/engine/runner.js +5 -2
- package/lib/environment/dependency-network.d.ts +42 -0
- package/lib/environment/dependency-network.js +413 -0
- package/lib/environment/isolation.d.ts +23 -1
- package/lib/environment/isolation.js +61 -2
- package/lib/environment/lifecycle.d.ts +3 -1
- package/lib/environment/lifecycle.js +22 -4
- package/lib/environment/os-tools.d.ts +3 -1
- package/lib/environment/os-tools.js +3 -1
- package/lib/environment/process.d.ts +11 -0
- package/lib/environment/process.js +42 -2
- package/lib/explain/state.d.ts +38 -0
- package/lib/explain/state.js +19 -11
- package/lib/index.d.ts +2 -0
- package/lib/index.js +2 -0
- package/lib/projections/attempt.d.ts +101 -0
- package/lib/projections/attempt.js +64 -0
- package/lib/projections/index.d.ts +2 -1
- package/lib/projections/index.js +2 -1
- package/lib/projections/stop.d.ts +19 -0
- package/lib/projections/stop.js +33 -27
- package/lib/report/compute.d.ts +72 -0
- package/lib/report/compute.js +1219 -0
- package/lib/report/document.d.ts +27 -0
- package/lib/report/document.js +206 -0
- package/lib/report/format.d.ts +23 -0
- package/lib/report/format.js +53 -0
- package/lib/report/html.d.ts +7 -0
- package/lib/report/html.js +109 -0
- package/lib/report/index.d.ts +4 -0
- package/lib/report/index.js +7 -0
- package/lib/report/markdown.d.ts +7 -0
- package/lib/report/markdown.js +112 -0
- package/lib/storage/sqlite.d.ts +19 -0
- package/lib/storage/sqlite.js +61 -6
- package/lib/verification/dependency-store.d.ts +13 -1
- package/lib/verification/dependency-store.js +99 -25
- package/lib/verification/file-digests.d.ts +33 -0
- package/lib/verification/file-digests.js +121 -0
- package/lib/verification/gates.d.ts +34 -4
- package/lib/verification/gates.js +113 -11
- package/package.json +5 -1
- package/schemas/run-event.schema.json +95 -0
- package/schemas/value-report.schema.json +2541 -0
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# devcontour-harness 0.1.0-alpha.29
|
|
2
|
+
|
|
3
|
+
Проверки в песочнице ОС больше не срываются под нагрузкой машины, а копия
|
|
4
|
+
хранилища зависимостей готовится примерно в 4 раза быстрее. Обязательные gates,
|
|
5
|
+
fencing, привязка доказательств к SHA и граница доверия хранилища не меняются.
|
|
6
|
+
|
|
7
|
+
## Изменения
|
|
8
|
+
|
|
9
|
+
- **Старт песочницы под нагрузкой.** sandbox-runtime искал shell через `which`
|
|
10
|
+
с таймаутом в секунду на каждый запуск; под нагрузкой проверка не стартовала
|
|
11
|
+
с ошибкой «Shell 'bash' not found in PATH», похожей на провал проекта. Теперь
|
|
12
|
+
shell находится без дочернего процесса и только в абсолютных каталогах PATH.
|
|
13
|
+
- **Доказанный старт.** Обёртка печатает в stderr случайный токен перед `exec`;
|
|
14
|
+
он ищется в сыром потоке до маски секретов. Команда, стёршая свою метку
|
|
15
|
+
старта, больше не считается не запущенной и не повторяется.
|
|
16
|
+
- **Отказ среды вместо провала проекта.** Если песочница так и не запустила
|
|
17
|
+
команду, а stderr состоит только из известных строк отказа запуска, gate
|
|
18
|
+
получает класс `environment` с понятным сообщением; probe reviewer —
|
|
19
|
+
`error`/`environment`. Прочие отказы до старта остаются провалом проверки.
|
|
20
|
+
На Linux классификация не проверялась.
|
|
21
|
+
- **Хранилище зависимостей быстрее.** На macOS копия seed делается одним
|
|
22
|
+
`clonefile(2)` каталога (при отказе — прежними порциями `cp -c`), байты и права
|
|
23
|
+
копии сверяются с закреплённым манифестом в пуле потоков. Seed 433 МБ /
|
|
24
|
+
36 690 файлов: подготовка копии 2,35 с вместо 9,2 с.
|
|
25
|
+
- **Новый отказ.** Файл seed с setuid, setgid или sticky отклоняется (pnpm таких
|
|
26
|
+
не создаёт); удаление копий снимает BSD-флаги вроде `uchg`.
|
|
27
|
+
|
|
28
|
+
## Обновление
|
|
29
|
+
|
|
30
|
+
Пакет alpha.28 остаётся неизменным. Форматы состояния, политики и манифест seed
|
|
31
|
+
прежние; seeds и копии подходят обеим версиям. Откат возвращает прежний поиск
|
|
32
|
+
shell и прежнюю классификацию отказов запуска (`gate`).
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# devcontour-harness 0.1.0-alpha.30
|
|
2
|
+
|
|
3
|
+
Видно, что дал harness и что он делает сейчас: отчёт об эффекте по истории
|
|
4
|
+
работы, события стадий попытки и подробный `status`. Сетевые отказы установки
|
|
5
|
+
зависимостей больше не считаются дефектами проекта. Обязательные gates,
|
|
6
|
+
fencing и привязка доказательств к SHA не меняются; формат состояния прежний.
|
|
7
|
+
|
|
8
|
+
## Изменения
|
|
9
|
+
|
|
10
|
+
- **`harness report`.** Отчёт по каталогу состояния в JSON, Markdown или
|
|
11
|
+
одном HTML-файле без внешних ресурсов: принятые поручения и первая попытка,
|
|
12
|
+
возвраты проверками и ревью до merge, срок от согласования до приёмки,
|
|
13
|
+
расход на поручение, отказы окружения, недели и ограничения. Неизвестное
|
|
14
|
+
показано как «≥», «≤», диапазон или «неизвестно», а не ноль; на малых
|
|
15
|
+
выборках — «N из M» без процентов. Тот же отчёт — функция `valueReport`
|
|
16
|
+
(`devcontour-harness/report`, без `node:*`) для хоста. Отчёт только читает:
|
|
17
|
+
однократное чтение не оставляет файлов в каталоге состояния.
|
|
18
|
+
- **События стадий.** `attempt.stage` (`started`/`finished`) для каждой
|
|
19
|
+
измеряемой стадии попытки: хранилище зависимостей, подготовка, реализация,
|
|
20
|
+
каждый gate, ревью, интеграция. Пишутся в тех же fenced-транзакциях, что и
|
|
21
|
+
тайминги; стадия попытки, потерявшей lease, остаётся открытой до события
|
|
22
|
+
завершения попытки.
|
|
23
|
+
- **`status --detail`.** Текущая стадия и время активных попыток, свежесть
|
|
24
|
+
lease, счёт обязательных gates текущей фазы и вид остановки очереди — тем же
|
|
25
|
+
рассуждением, что и `explain`. Проекция `attemptView` для хостов.
|
|
26
|
+
- **Чтение незнакомых событий.** События неизвестного типа читаются как
|
|
27
|
+
`unknown`, а не ломают `events`. Тип `RunEvent` включает этот вариант: код,
|
|
28
|
+
читающий `payload`, сужает по `type` или использует `KnownRunEvent`.
|
|
29
|
+
- **Сеть и реестр при установке зависимостей.** Упавшая установка — отказ
|
|
30
|
+
среды с причиной `dependency-network`, только если команда — установка из
|
|
31
|
+
политики, входы менеджера пакетов совпадают с базой попытки, база не
|
|
32
|
+
исполняет кода при установке, менеджер вышел сам и назвал только сетевые
|
|
33
|
+
коды. Всё, что изменил кандидат, остаётся провалом проверки.
|
|
34
|
+
|
|
35
|
+
## Обновление
|
|
36
|
+
|
|
37
|
+
Пакет alpha.29 остаётся неизменным. Формат состояния (`stateVersion: 1`) и
|
|
38
|
+
политики прежний. Откат ниже этой версии не прочитает страницу событий с
|
|
39
|
+
`attempt.stage`: откатывайтесь вместе с копией состояния, снятой до
|
|
40
|
+
обновления. Подробнее — `docs/upgrade.md`.
|
package/docs/review-probes.md
CHANGED
|
@@ -75,14 +75,14 @@ To run a declared gate, call run_check with exactly {"gate":"domain"}, {"gate":"
|
|
|
75
75
|
|
|
76
76
|
## Статусы
|
|
77
77
|
|
|
78
|
-
| `status` | `failure` | Смысл
|
|
79
|
-
| ------------------------------ | ------------- |
|
|
80
|
-
| `passed` | — | код 0 и (для gate с отчётом) свежий JUnit без failures и skips
|
|
81
|
-
| `failed` | — | код ≠ 0 или упали testcases: наблюдение о коде
|
|
82
|
-
| `failed` | `report` | код 0, но отчёт `missing`/`stale`/`corrupt`/`unsafe`: не прохождение и не находка в коде
|
|
83
|
-
| `error` | `environment` | путь отчёта зашит в argv, отказ записи (EPERM/EACCES) мимо `HARNESS_REPORT_PATH`, отказ scratch, сеть закрыта песочницей, нет
|
|
84
|
-
| `timeout`, `cancelled` | — | команда остановлена вместе с потомками
|
|
85
|
-
| `budget-exhausted`, `rejected` | — | команда не запускалась
|
|
78
|
+
| `status` | `failure` | Смысл |
|
|
79
|
+
| ------------------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
80
|
+
| `passed` | — | код 0 и (для gate с отчётом) свежий JUnit без failures и skips |
|
|
81
|
+
| `failed` | — | код ≠ 0 или упали testcases: наблюдение о коде |
|
|
82
|
+
| `failed` | `report` | код 0, но отчёт `missing`/`stale`/`corrupt`/`unsafe`: не прохождение и не находка в коде |
|
|
83
|
+
| `error` | `environment` | путь отчёта зашит в argv, отказ записи (EPERM/EACCES) мимо `HARNESS_REPORT_PATH`, отказ scratch, сеть закрыта песочницей, установка зависимостей упала на сети или реестре (`dependency-network`), нет песочницы, песочница не запустила команду |
|
|
84
|
+
| `timeout`, `cancelled` | — | команда остановлена вместе с потомками |
|
|
85
|
+
| `budget-exhausted`, `rejected` | — | команда не запускалась |
|
|
86
86
|
|
|
87
87
|
Ошибка среды и ошибка отчёта — не находка в коде; находка, сославшаяся на запуск с
|
|
88
88
|
`failure: environment`, не получает `observed`.
|
|
@@ -109,18 +109,21 @@ target ref.
|
|
|
109
109
|
### Граница старта
|
|
110
110
|
|
|
111
111
|
Запуск probe засчитывается по признаку `started` из `runCheck`: без песочницы — процесс порождён
|
|
112
|
-
(событие `spawn`), в песочнице — обёртка
|
|
113
|
-
не считается). Признак отмечается на границе и переживает исключение
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
|
119
|
-
|
|
|
120
|
-
|
|
|
121
|
-
|
|
|
122
|
-
|
|
|
123
|
-
|
|
|
112
|
+
(событие `spawn`), в песочнице — обёртка напечатала токен старта в stderr или создала метку перед
|
|
113
|
+
`exec` (запуск самой обёртки не считается). Признак отмечается на границе и переживает исключение
|
|
114
|
+
после неё. Без токена и метки запуск повторяется (до трёх попыток); песочница, так и не запустившая
|
|
115
|
+
команду, когда весь stderr — только строки известного отказа запуска srt (`Error: Shell '…' not
|
|
116
|
+
found in PATH`, `Failed to execute command: …`), даёт `error`/`environment`.
|
|
117
|
+
|
|
118
|
+
| Событие | В `commands` |
|
|
119
|
+
| --------------------------------------------------------------------------------------------------------------- | ------------ |
|
|
120
|
+
| Команда завершилась с любым кодом | да |
|
|
121
|
+
| `timeout`/`cancelled` после старта (код `null`, частичный вывод) | да |
|
|
122
|
+
| `error`/`environment` после старта (сеть закрыта песочницей, `dependency-network`, EPERM, сбой записи evidence) | да |
|
|
123
|
+
| `failed`/`report`: код 0, JUnit отсутствует или испорчен | да |
|
|
124
|
+
| Неизвестный gate, бюджет исчерпан, нет executable, отказ песочницы или scratch до старта | нет |
|
|
125
|
+
| Вызов отменён до запуска (`cancelled`, команда не исполнялась) | нет |
|
|
126
|
+
| Только резерв `start`, `abandoned`, битая строка, объект без формы исхода | нет |
|
|
124
127
|
|
|
125
128
|
Незасчитанные записи перечислены в `inspection.excluded` с причиной; полная диагностика — в
|
|
126
129
|
`review.json.probes` и журнале.
|
package/docs/toolchains.md
CHANGED
|
@@ -150,6 +150,10 @@ Isolation `os` пишет только в worktree и временный кат
|
|
|
150
150
|
2. Seed клонируется в `<checkout>/.pnpm-store` (копия-при-записи на APFS и reflink-томах, иначе
|
|
151
151
|
обычная копия, если хватает места), копия сверяется с манифестом, менеджер получает путь через
|
|
152
152
|
`npm_config_store_dir`. Каталог скрыт от git собственным `.gitignore`.
|
|
153
|
+
На macOS клон делается одним `clonefile(2)` всего каталога (через `/usr/bin/osascript`;
|
|
154
|
+
если вызов не удался — `cp -c` порциями), а сверка читает и хэширует файлы копии в
|
|
155
|
+
нескольких потоках: seed из 37 тысяч файлов и 430 МБ на APFS разворачивается и сверяется
|
|
156
|
+
примерно за 2–3 с, а не за 8–9.
|
|
153
157
|
3. Gate установки — обычный `pnpm install --frozen-lockfile`. Он берёт пакеты из копии, а чего нет,
|
|
154
158
|
скачивает через прокси песочницы.
|
|
155
159
|
|
|
@@ -178,7 +182,14 @@ Isolation `os` пишет только в worktree и временный кат
|
|
|
178
182
|
кандидата не исполняют. `doctor` предупреждает о `dependencyStore` рядом с непустым `prepare`.
|
|
179
183
|
- Seeds лежат под корнем рабочих деревьев или в каталоге состояния, закрытых песочницей на чтение
|
|
180
184
|
и запись. Манифест закреплён digest в базе ресурсов, вне дерева seed.
|
|
181
|
-
- Проверяются байты копии, а не источника: те, что прочитает менеджер.
|
|
185
|
+
- Проверяются байты копии, а не источника: те, что прочитает менеджер. Ускорение этого не
|
|
186
|
+
меняет: каждый файл копии открывается с `O_NOFOLLOW`, а хэш, права и тип берутся с того же
|
|
187
|
+
дескриптора, что и байты; ссылка, каталог или канал на месте файла — отказ. `O_NOFOLLOW`
|
|
188
|
+
защищает только последний компонент пути: каталог по пути к файлу, подменённый ссылкой между
|
|
189
|
+
обходом и чтением, не обнаруживается. Такая подмена требует процесса, который пишет в checkout
|
|
190
|
+
во время развёртывания, то есть до `prepare` и gates этого checkout; это вне модели угроз,
|
|
191
|
+
как и прежде (прежние `lstat` и `readFile` следовали и по последнему компоненту). Setuid, setgid и sticky у файлов seed — отказ, BSD-флаги вроде `uchg`
|
|
192
|
+
копия наследует, как и при `cp -c`, а удаление копии и seed их снимает.
|
|
182
193
|
- Копия принадлежит своему checkout, в seed ничего не возвращается. Integration и следующая попытка
|
|
183
194
|
получают новую копию. Поэтому байты seed проверены всегда, а докачанные байты и всё, что
|
|
184
195
|
исполнитель изменил в своём дереве, доверены не больше, чем его `node_modules`: они не выходят
|
package/docs/upgrade.md
CHANGED
|
@@ -189,6 +189,130 @@ gate и в записи совместной проверки прежние в
|
|
|
189
189
|
Подробнее — [заметки выпуска](release-notes/0.1.0-alpha.28.md) и
|
|
190
190
|
[договоры](contracts.md#executionpolicy).
|
|
191
191
|
|
|
192
|
+
### alpha.29: запуск песочницы проверок
|
|
193
|
+
|
|
194
|
+
Форматы состояния, политики и публичные поля API прежние. sandbox-runtime
|
|
195
|
+
искал shell через `which` с таймаутом в секунду на каждый запуск проверки; под
|
|
196
|
+
нагрузкой машины поиск не успевал, и проверка не стартовала с ошибкой
|
|
197
|
+
«Shell 'bash' not found in PATH». Теперь процесс srt находит shell по PATH сам,
|
|
198
|
+
без порождения `which`, и только в абсолютных каталогах PATH; не найденный
|
|
199
|
+
shell по-прежнему ищет `which`. Старт команды доказывает токен, который обёртка
|
|
200
|
+
печатает в stderr перед `exec`; он ищется и вырезается в сыром потоке до маски
|
|
201
|
+
секретов: стёртая командой
|
|
202
|
+
метка-файл больше не выдаёт стартовавшую команду за не запущенную, и такая
|
|
203
|
+
команда не повторяется. Если песочница не запустила команду и после повторов
|
|
204
|
+
(до трёх попыток, только пока нет ни метки, ни токена), а весь stderr — только
|
|
205
|
+
строки известного отказа запуска srt (`Error: Shell '…' not found in PATH`,
|
|
206
|
+
`Failed to execute command: …`), gate не
|
|
207
|
+
проходит с классом `environment` и сообщением «песочница ОС не запустила
|
|
208
|
+
команду проверки», а не как провал проекта с кодом выхода; probe reviewer в
|
|
209
|
+
этом случае — `error`/`environment`. Прочие отказы srt до старта остаются
|
|
210
|
+
провалом проверки (`gate`). При откате возвращается прежний поиск shell и
|
|
211
|
+
прежняя классификация (`gate`).
|
|
212
|
+
|
|
213
|
+
### alpha.29: быстрее копия хранилища зависимостей
|
|
214
|
+
|
|
215
|
+
Форматы состояния, манифест seed, политика и граница доверия прежние: сверяются
|
|
216
|
+
те же байты и права копии по тому же закреплённому манифесту. На macOS копия
|
|
217
|
+
делается одним `clonefile(2)` каталога через `/usr/bin/osascript`, при его отказе —
|
|
218
|
+
прежними порциями `cp -c`; сверка идёт в потоках. Новое: файл seed с setuid,
|
|
219
|
+
setgid или sticky — отказ (pnpm таких не создаёт). Откат — установка прежней
|
|
220
|
+
версии, seeds и копии подходят обеим. Подробнее —
|
|
221
|
+
[хранилище зависимостей](toolchains.md#хранилище-зависимостей).
|
|
222
|
+
|
|
223
|
+
### alpha.30: события стадий
|
|
224
|
+
|
|
225
|
+
Форматы состояния (`stateVersion: 1`), политики и её digest прежние: в
|
|
226
|
+
документ состояния не добавлено ни одного поля. Новое в журнале и в CLI:
|
|
227
|
+
|
|
228
|
+
- **Терпимое чтение событий.** Событие типа, которого версия не знает
|
|
229
|
+
(записанное более новой версией), `events` и `ExecutionStore.events`
|
|
230
|
+
возвращают непрозрачным: конверт без нагрузки, `type: 'unknown'` и исходный
|
|
231
|
+
тип в `original` — а не обрывают список отказом. Писатель строгий: событие
|
|
232
|
+
`unknown` не записывается. Известный тип с нарушенной нагрузкой — по-прежнему
|
|
233
|
+
отказ. Хост, который сам разбирает сохранённые события, использует
|
|
234
|
+
`readRunEvent`. В TypeScript `RunEvent` теперь включает `UnknownRunEvent`:
|
|
235
|
+
код, читающий `payload` без сужения по `type`, перестаёт компилироваться —
|
|
236
|
+
сузить (`e.type !== 'unknown'` или конкретный тип) либо взять
|
|
237
|
+
`KnownRunEvent`. Тип `ExecutionStore.events()` прежний: хранилища хоста не
|
|
238
|
+
меняются.
|
|
239
|
+
- **Событие `attempt.stage`.** На каждую стадию попытки (замер
|
|
240
|
+
`AttemptState.timings`) — одно `started` и не больше одного `finished` с
|
|
241
|
+
`durationMs` и исходом, в той же транзакции под fencing, что и замер.
|
|
242
|
+
Стадия попытки, утратившей владение или упавшей, остаётся открытой; её
|
|
243
|
+
конец — событие конца попытки.
|
|
244
|
+
- **`status --detail`.** Поле `detail`: почему стоит выдача и активные
|
|
245
|
+
попытки — стадия и её длительность, владение и его свежесть, счёт gates.
|
|
246
|
+
Без флага ответ `status` прежний.
|
|
247
|
+
|
|
248
|
+
**Откат.** Прежние версии (alpha.29 и ниже) разбирают каждое событие строго:
|
|
249
|
+
терпимое чтение появляется только с этой версией. После отката ниже неё
|
|
250
|
+
`harness events` и чтение журнала хостом через прежний `ExecutionStore.events`
|
|
251
|
+
отказывают на первой странице, где есть `attempt.stage`; документ состояния,
|
|
252
|
+
`status`, `result` и работа очереди читаются как прежде. Рекомендуемый путь —
|
|
253
|
+
строка «Новая версия уже изменила формат» таблицы [«Откат»](#откат): остановить
|
|
254
|
+
writers и восстановить копию каталога состояния, снятую до обновления, вместе
|
|
255
|
+
с прежней версией пакета. Без копии прежняя версия продолжает работу очереди,
|
|
256
|
+
но журнал после первого `attempt.stage` ей не прочитать; удалять или
|
|
257
|
+
переписывать события ради неё нельзя.
|
|
258
|
+
|
|
259
|
+
### alpha.30: отчёт об эффекте
|
|
260
|
+
|
|
261
|
+
Форматы состояния (`stateVersion: 1`), политики, событий и их схем прежние:
|
|
262
|
+
отчёт только читает. Новое — аддитивно:
|
|
263
|
+
|
|
264
|
+
- **`harness report`.** Отчёт по каталогу состояния: принятые поручения и
|
|
265
|
+
первая попытка, возвраты проверками и ревью, действия человека (нижняя
|
|
266
|
+
граница), срок от согласования до приёмки, расход (неизвестная цена —
|
|
267
|
+
«≥», а не ноль), отказы окружения, недели и ограничения. `--format
|
|
268
|
+
json|md|html`, `--out F`, окно `--since/--until`, `--as-of`, `--no-titles`.
|
|
269
|
+
База открывается только для чтения; `binding.json` не нужен.
|
|
270
|
+
- **Библиотека.** `devcontour-harness/report` (`valueReport`,
|
|
271
|
+
`reportMarkdown`, `reportHtml`; без `node:*`), в корне — те же функции,
|
|
272
|
+
`collectReportInput(store)` и `Harness.report()`.
|
|
273
|
+
- **Чтение без файлов.** `report` читает состояние однократно: база без
|
|
274
|
+
журнала открывается неизменяемой и в каталоге состояния не появляется
|
|
275
|
+
служебных `-wal`/`-shm`; если писатель начал работу во время чтения,
|
|
276
|
+
оно повторяется обычным открытием. Прочие читающие команды не менялись.
|
|
277
|
+
- **Схема.** `value-report` (`schemas/value-report.schema.json`,
|
|
278
|
+
`reportVersion: 1`) и данные `report` в `cliDataSchemas`.
|
|
279
|
+
|
|
280
|
+
Определения, правила малых выборок и приватности — [ValueReport](contracts.md#valuereport).
|
|
281
|
+
Отчёт строится из истории как она записана: попытки прежних версий без класса
|
|
282
|
+
отказа показаны `unclassified`, без `wait` — с запасным началом срока, без
|
|
283
|
+
учёта вызовов — с неизвестным расходом; история не переписывается.
|
|
284
|
+
|
|
285
|
+
**Откат.** Ниже этой версии команды `report` нет; состояние она не меняла,
|
|
286
|
+
поэтому откат пакета копии не требует.
|
|
287
|
+
|
|
288
|
+
### alpha.30: сетевой отказ установки зависимостей
|
|
289
|
+
|
|
290
|
+
Форматы состояния и политики прежние; нового поля в состоянии нет. В
|
|
291
|
+
описании reviewer probe (`probe.json`) — необязательное поле `trustedBase`.
|
|
292
|
+
Установка зависимостей, упавшая на сети или реестре пакетов, теперь отказ
|
|
293
|
+
`environment`, а не `gate`; сообщение начинается с `dependency-network:`.
|
|
294
|
+
Условия:
|
|
295
|
+
|
|
296
|
+
- argv gate попытки или шага `prepare` сам вызывает `npm install|ci`, `pnpm
|
|
297
|
+
install|fetch` или `yarn install`;
|
|
298
|
+
- входы менеджера в дереве (`.npmrc`, `.yarnrc*`, pnpmfile, lockfiles, поля
|
|
299
|
+
зависимостей и скрипты установки `package.json`) совпадают с базой попытки;
|
|
300
|
+
- база не исполняет кода при установке;
|
|
301
|
+
- менеджер вышел сам с кодом 1–127;
|
|
302
|
+
- его отчёт называет только сетевые коды: HTTP 403/407/408/429/5xx реестра,
|
|
303
|
+
обрыв соединения, DNS, TLS.
|
|
304
|
+
|
|
305
|
+
Такой отказ не тратит попытку поручения и ставит паузу очереди `runtime`, как
|
|
306
|
+
любой отказ окружения. Повтор берёт того же кандидата, работу ограничивает
|
|
307
|
+
`MAX_NEUTRAL_FAILURES`. Отказ после правки кандидатом реестра, зависимостей
|
|
308
|
+
или скриптов установки, ошибки lockfile, 404, peer-зависимости и упавший скрипт
|
|
309
|
+
остаются `gate`. Прежде такой отказ gate давал класс `gate`, а шаг `prepare` —
|
|
310
|
+
`unknown`. Хосту, который считает «дефекты, найденные проверками» по
|
|
311
|
+
`failureKind`, новых действий не нужно: эти отказы уходят из счёта сами.
|
|
312
|
+
Правило — [архитектура](architecture.md#что-гарантируется). При откате
|
|
313
|
+
возвращается прежняя классификация; уже записанные попытки сохраняют свой
|
|
314
|
+
класс.
|
|
315
|
+
|
|
192
316
|
## Перед обновлением
|
|
193
317
|
|
|
194
318
|
1. **Остановить записывающих.** Запретить новые выдачи (`harness pause`),
|
|
@@ -75,6 +75,7 @@ export declare const probeSpec: z.ZodObject<{
|
|
|
75
75
|
}, z.core.$strict>>>;
|
|
76
76
|
phase: z.ZodOptional<z.ZodString>;
|
|
77
77
|
sha: z.ZodOptional<z.ZodString>;
|
|
78
|
+
trustedBase: z.ZodOptional<z.ZodString>;
|
|
78
79
|
scope: z.ZodOptional<z.ZodObject<{
|
|
79
80
|
attempt: z.ZodString;
|
|
80
81
|
phase: z.ZodString;
|
|
@@ -8,6 +8,7 @@ import { createInterface } from 'node:readline';
|
|
|
8
8
|
import { fileURLToPath } from 'node:url';
|
|
9
9
|
import { z } from 'zod';
|
|
10
10
|
import { idSchema, relativePathSchema, sha256, TaskFailure, } from "../contracts/index.js";
|
|
11
|
+
import { dependencyNetworkFailure, dependencyNetworkMessage, } from "../environment/dependency-network.js";
|
|
11
12
|
import { osToolEnv } from "../environment/os-tools.js";
|
|
12
13
|
import { redactor } from "../environment/redaction.js";
|
|
13
14
|
import { completedCheck, freshnessEnv, propertyReportEnv, junitSummary, runCheck, sandboxBlockedHosts, } from "../verification/gates.js";
|
|
@@ -75,6 +76,8 @@ export const probeSpec = z.object({
|
|
|
75
76
|
/** Фаза и SHA ревью: записываются в каждый запуск gate. */
|
|
76
77
|
phase: z.string().optional(),
|
|
77
78
|
sha: z.string().optional(),
|
|
79
|
+
/** SHA базы попытки: только с ним gate установки может стать `dependency-network`. */
|
|
80
|
+
trustedBase: z.string().optional(),
|
|
78
81
|
/**
|
|
79
82
|
* Вызов reviewer, которому принадлежит журнал: попытка harness, фаза, SHA
|
|
80
83
|
* и номер вызова. Записывается в каждый исход — по нему итог ревью не
|
|
@@ -408,6 +411,16 @@ export class ReviewProbes {
|
|
|
408
411
|
...(gate ? { failure: 'environment' } : {}),
|
|
409
412
|
}
|
|
410
413
|
: {};
|
|
414
|
+
// Песочница так и не запустила команду: исполнять было нечего.
|
|
415
|
+
if (r.launchFailed && !r.timedOut && !signal.aborted)
|
|
416
|
+
return {
|
|
417
|
+
status: 'error',
|
|
418
|
+
failure: 'environment',
|
|
419
|
+
exitCode: r.code,
|
|
420
|
+
stdout: tail(r.stdout),
|
|
421
|
+
stderr: tail(r.stderr),
|
|
422
|
+
note: `Песочница ОС не запустила команду (попыток: ${r.attempts}): команда не исполнялась. Это ошибка среды, а не находка в коде.`,
|
|
423
|
+
};
|
|
411
424
|
return {
|
|
412
425
|
...hint,
|
|
413
426
|
status: signal.aborted
|
|
@@ -555,6 +568,15 @@ export class ReviewProbes {
|
|
|
555
568
|
const blocked = this.spec.isolation.mode === 'os' && r.code !== 0
|
|
556
569
|
? sandboxBlockedHosts(output, this.spec.isolation.domains)
|
|
557
570
|
: [];
|
|
571
|
+
const network = r.code !== 0 && !r.timedOut && !signal.aborted
|
|
572
|
+
? await dependencyNetworkFailure({
|
|
573
|
+
argv: gate.command,
|
|
574
|
+
code: r.code,
|
|
575
|
+
output,
|
|
576
|
+
root,
|
|
577
|
+
...(this.spec.trustedBase ? { base: this.spec.trustedBase } : {}),
|
|
578
|
+
})
|
|
579
|
+
: undefined;
|
|
558
580
|
if (signal.aborted)
|
|
559
581
|
outcome = {
|
|
560
582
|
...base,
|
|
@@ -569,6 +591,14 @@ export class ReviewProbes {
|
|
|
569
591
|
status: 'timeout',
|
|
570
592
|
note: `Gate не завершился за ${limitMs} мс и остановлен вместе с потомками; это наблюдение, а не доказанный дефект. ${observation}`,
|
|
571
593
|
};
|
|
594
|
+
else if (r.launchFailed)
|
|
595
|
+
outcome = {
|
|
596
|
+
...base,
|
|
597
|
+
...streams,
|
|
598
|
+
status: 'error',
|
|
599
|
+
failure: 'environment',
|
|
600
|
+
note: `Песочница ОС не запустила gate (попыток: ${r.attempts}): команда не исполнялась. Это ошибка среды, а не находка в коде.`,
|
|
601
|
+
};
|
|
572
602
|
else if (blocked.length)
|
|
573
603
|
outcome = {
|
|
574
604
|
...base,
|
|
@@ -577,6 +607,14 @@ export class ReviewProbes {
|
|
|
577
607
|
failure: 'environment',
|
|
578
608
|
note: `Песочница закрыла сеть к ${blocked.join(', ')} (нет в isolation.domains): ошибка среды, не находка в коде.`,
|
|
579
609
|
};
|
|
610
|
+
else if (network)
|
|
611
|
+
outcome = {
|
|
612
|
+
...base,
|
|
613
|
+
...streams,
|
|
614
|
+
status: 'error',
|
|
615
|
+
failure: 'environment',
|
|
616
|
+
note: dependencyNetworkMessage(redact(network), 'Это ошибка среды, а не находка в коде.'),
|
|
617
|
+
};
|
|
580
618
|
else if (r.code !== 0 && report?.status !== 'fresh' && writeDenied.test(output))
|
|
581
619
|
// Отчёта нет, а проверка получила отказ записи: она писала мимо
|
|
582
620
|
// HARNESS_REPORT_PATH — в дерево, которое здесь только для чтения.
|
package/lib/cli.js
CHANGED
|
@@ -21,6 +21,10 @@ import { isSharedOperation, sharedOperations } from "./catalog/shared.js";
|
|
|
21
21
|
import { harnessCapabilities } from "./catalog/harness.js";
|
|
22
22
|
import { hostGitArgs } from "./environment/process.js";
|
|
23
23
|
import { FileContextSource, FileResultSink, FileWorkSource } from "./connectors/files.js";
|
|
24
|
+
import { SqliteExecutionStore } from "./storage/sqlite.js";
|
|
25
|
+
import { collectReportInput } from "./control/report.js";
|
|
26
|
+
import { writeReportFile } from "./control/report-file.js";
|
|
27
|
+
import { valueReport, reportHtml, reportMarkdown } from "./report/index.js";
|
|
24
28
|
const usage = `harness ${HARNESS_VERSION}
|
|
25
29
|
|
|
26
30
|
Использование: harness <команда> [параметры]
|
|
@@ -211,6 +215,12 @@ const options = {
|
|
|
211
215
|
contracts: { type: 'string' },
|
|
212
216
|
requirements: { type: 'string', multiple: true },
|
|
213
217
|
'dry-run': { type: 'boolean' },
|
|
218
|
+
detail: { type: 'boolean' },
|
|
219
|
+
since: { type: 'string' },
|
|
220
|
+
until: { type: 'string' },
|
|
221
|
+
'as-of': { type: 'string' },
|
|
222
|
+
format: { type: 'string' },
|
|
223
|
+
'no-titles': { type: 'boolean' },
|
|
214
224
|
};
|
|
215
225
|
/** Новые флаги H1 допустимы только у своих команд; прежние команды их не принимают. */
|
|
216
226
|
const flagOwners = {
|
|
@@ -223,6 +233,12 @@ const flagOwners = {
|
|
|
223
233
|
contracts: ['plan-request', 'plan-check'],
|
|
224
234
|
requirements: ['plan-request'],
|
|
225
235
|
'dry-run': ['worktree-cleanup'],
|
|
236
|
+
detail: ['status'],
|
|
237
|
+
since: ['report'],
|
|
238
|
+
until: ['report'],
|
|
239
|
+
'as-of': ['report'],
|
|
240
|
+
format: ['report'],
|
|
241
|
+
'no-titles': ['report'],
|
|
226
242
|
};
|
|
227
243
|
/** Явное человеческое представление успешного ответа (`--human`). */
|
|
228
244
|
const presenters = {
|
|
@@ -272,6 +288,7 @@ const readText = (path, what) => {
|
|
|
272
288
|
throw new HarnessError('INVALID_INPUT', `${what}: не прочитан ${path}: ${error.message}`);
|
|
273
289
|
}
|
|
274
290
|
};
|
|
291
|
+
const reportFormats = ['json', 'md', 'html'];
|
|
275
292
|
async function run(argv) {
|
|
276
293
|
const [name, ...rest] = argv;
|
|
277
294
|
if (name === '--version' || name === 'version') {
|
|
@@ -430,7 +447,7 @@ async function run(argv) {
|
|
|
430
447
|
const h = open(need('state'), binding(need('state')), 'state');
|
|
431
448
|
try {
|
|
432
449
|
if (command === 'status')
|
|
433
|
-
return { command, data: h.status(v.graph) };
|
|
450
|
+
return { command, data: h.status(v.graph, { detail: Boolean(v.detail) }) };
|
|
434
451
|
if (command === 'events')
|
|
435
452
|
return { command, data: h.events(Number(v.after ?? 0), Number(v.limit ?? 100)) };
|
|
436
453
|
return { command, data: h.result(need('work')) };
|
|
@@ -576,6 +593,42 @@ async function run(argv) {
|
|
|
576
593
|
}),
|
|
577
594
|
};
|
|
578
595
|
}
|
|
596
|
+
case 'report': {
|
|
597
|
+
const state = need('state');
|
|
598
|
+
const format = (v.format ?? 'json');
|
|
599
|
+
if (!reportFormats.includes(format))
|
|
600
|
+
throw new HarnessError('INVALID_INPUT', '--format: ожидается json, md или html', [
|
|
601
|
+
{ path: ['--format'], message: String(v.format) },
|
|
602
|
+
]);
|
|
603
|
+
const file = join(resolve(state), 'state.sqlite');
|
|
604
|
+
if (!existsSync(file))
|
|
605
|
+
throw new HarnessError('NOT_FOUND', 'Каталог состояния не найден: ' + state);
|
|
606
|
+
// Однократное чтение без записи и без файлов в каталоге состояния
|
|
607
|
+
// (неизменяемое открытие с проверкой после чтения, `readOnce`).
|
|
608
|
+
const report = SqliteExecutionStore.readOnce(file, 'devcontour-harness@' + HARNESS_VERSION, (store) => valueReport(collectReportInput(store), {
|
|
609
|
+
...optional('since', v.since),
|
|
610
|
+
...optional('until', v.until),
|
|
611
|
+
...optional('asOf', v['as-of']),
|
|
612
|
+
...(v['no-titles'] ? { noTitles: true } : {}),
|
|
613
|
+
label: basename(resolve(state)),
|
|
614
|
+
stateDir: resolve(state),
|
|
615
|
+
harnessVersion: HARNESS_VERSION,
|
|
616
|
+
}));
|
|
617
|
+
if (format === 'json' && !v.out)
|
|
618
|
+
return { command, data: report };
|
|
619
|
+
const text = format === 'json'
|
|
620
|
+
? JSON.stringify(report, null, 2) + '\n'
|
|
621
|
+
: format === 'md'
|
|
622
|
+
? reportMarkdown(report)
|
|
623
|
+
: reportHtml(report);
|
|
624
|
+
if (!v.out)
|
|
625
|
+
return { command, data: report, text };
|
|
626
|
+
writeReportFile(v.out, state, text);
|
|
627
|
+
return {
|
|
628
|
+
command,
|
|
629
|
+
data: { out: v.out, format, bytes: Buffer.byteLength(text), asOf: report.window.asOf },
|
|
630
|
+
};
|
|
631
|
+
}
|
|
579
632
|
case 'plan-request': {
|
|
580
633
|
const b = loadPolicy(need('policy'));
|
|
581
634
|
const first = b.policy.repositories[0]?.id ?? 'main';
|
|
@@ -658,6 +711,9 @@ try {
|
|
|
658
711
|
const present = result.command !== 'version' ? presenters[result.command] : undefined;
|
|
659
712
|
if (present && argv.includes('--human'))
|
|
660
713
|
text = present(envelope.data);
|
|
714
|
+
// report --format md|html: проверенные данные печатаются текстом, без конверта.
|
|
715
|
+
if (result.text !== undefined)
|
|
716
|
+
text = result.text;
|
|
661
717
|
}
|
|
662
718
|
catch (error) {
|
|
663
719
|
const known = error instanceof HarnessError
|