devcontour-harness-ui 0.0.0-stage → 0.1.0-alpha.2

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.
Files changed (58) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +143 -2
  3. package/dist/app/assets/index-Det9VYJC.css +1 -0
  4. package/dist/app/assets/index-veveke8K.js +9 -0
  5. package/dist/app/index.html +13 -0
  6. package/dist/demo/ru/view.sample.json +483 -0
  7. package/dist/demo/ru/work.accepted.sample.json +187 -0
  8. package/dist/demo/ru/work.sample.json +171 -0
  9. package/dist/demo/view.sample.json +483 -0
  10. package/dist/demo/work.accepted.sample.json +187 -0
  11. package/dist/demo/work.sample.json +171 -0
  12. package/dist/lib/cli.d.ts +2 -0
  13. package/dist/lib/cli.js +160 -0
  14. package/dist/lib/components/Activity.d.ts +13 -0
  15. package/dist/lib/components/Activity.js +19 -0
  16. package/dist/lib/components/Decisions.d.ts +6 -0
  17. package/dist/lib/components/Decisions.js +19 -0
  18. package/dist/lib/components/Health.d.ts +8 -0
  19. package/dist/lib/components/Health.js +24 -0
  20. package/dist/lib/components/History.d.ts +32 -0
  21. package/dist/lib/components/History.js +129 -0
  22. package/dist/lib/components/Overview.d.ts +19 -0
  23. package/dist/lib/components/Overview.js +54 -0
  24. package/dist/lib/components/Reviews.d.ts +23 -0
  25. package/dist/lib/components/Reviews.js +22 -0
  26. package/dist/lib/components/Settings.d.ts +21 -0
  27. package/dist/lib/components/Settings.js +77 -0
  28. package/dist/lib/components/WorkDetail.d.ts +18 -0
  29. package/dist/lib/components/WorkDetail.js +96 -0
  30. package/dist/lib/components/common.d.ts +71 -0
  31. package/dist/lib/components/common.js +85 -0
  32. package/dist/lib/index.d.ts +10 -0
  33. package/dist/lib/index.js +12 -0
  34. package/dist/lib/model/compat.d.ts +36 -0
  35. package/dist/lib/model/compat.js +365 -0
  36. package/dist/lib/model/dict.d.ts +387 -0
  37. package/dist/lib/model/dict.js +1119 -0
  38. package/dist/lib/model/format.d.ts +34 -0
  39. package/dist/lib/model/format.js +88 -0
  40. package/dist/lib/model/i18n.d.ts +44 -0
  41. package/dist/lib/model/i18n.js +109 -0
  42. package/dist/lib/model/index.d.ts +6 -0
  43. package/dist/lib/model/index.js +8 -0
  44. package/dist/lib/model/source.d.ts +16 -0
  45. package/dist/lib/model/source.js +57 -0
  46. package/dist/lib/model/view.d.ts +474 -0
  47. package/dist/lib/model/view.js +10 -0
  48. package/dist/lib/server/harness.d.ts +44 -0
  49. package/dist/lib/server/harness.js +172 -0
  50. package/dist/lib/server/serve.d.ts +62 -0
  51. package/dist/lib/server/serve.js +302 -0
  52. package/dist/lib/styles.css +485 -0
  53. package/docs/design.md +1689 -0
  54. package/docs/harness-proposals.md +560 -0
  55. package/docs/release-notes/0.1.0-alpha.1.md +96 -0
  56. package/docs/release-notes/0.1.0-alpha.2.md +218 -0
  57. package/package.json +75 -4
  58. package/skills/harness-ui/SKILL.md +246 -0
@@ -0,0 +1,246 @@
1
+ ---
2
+ name: harness-ui
3
+ description: Запустить панель оператора devcontour-harness (только чтение) для текущего проекта на локальном порту, дать пользователю URL и простыми словами объяснить, что он видит, — что ждёт его ответа, что идёт сейчас, что и как проверено, решения, кто что делал, настройки, история и здоровье. Используй, когда пользователь хочет следить за работой harness в браузере, спрашивает «что делает harness», хочет dashboard попыток, вопросов, бюджетов или ревью, или когда начинается долгий запуск harness. Никогда не открывает панель за пределы локальной машины и никогда не отвечает на вопросы оператора за пользователя.
4
+ ---
5
+
6
+ # Панель harness
7
+
8
+ `devcontour-harness-ui` показывает состояние harness в браузере. Панель
9
+ только читает: она не может запустить, остановить, повторить или ответить
10
+ на что-либо. Она слушает только локальную машину (`127.0.0.1`).
11
+
12
+ Панель показывает данные harness, а не твой пересказ. Пересказывай то, что
13
+ показывает панель, и никогда не подменяй панель своим пересказом: если
14
+ пользователь спрашивает «готово ли», «проверено ли», «почему опять» — веди
15
+ его к соответствующему разделу панели и читай оттуда.
16
+
17
+ Ниже `$H` — CLI harness проекта (`<tooldir>/node_modules/.bin/harness`, см.
18
+ skill `harness`), а `$UI` — CLI панели
19
+ (`<tooldir>/node_modules/.bin/devcontour-harness-ui` или
20
+ `npx devcontour-harness-ui@<точная версия>`).
21
+
22
+ ## Жёсткие правила
23
+
24
+ - **Никогда** не передавай `--host 0.0.0.0`, `::` или адрес локальной сети и
25
+ никогда не ставь панель за туннель, прокси или проброс портов. CLI
26
+ отклоняет не-loopback адреса. Не обходи это.
27
+ - **Никогда не отвечай на вопросы оператора за пользователя.** Панель
28
+ помечает такие вопросы «Ответить можете только вы» (по-английски «Only
29
+ you can answer this question»). Скажи пользователю, о чём спрашивают, и точную команду или
30
+ место для ответа. Не запускай `harness input-answer --actor operator` сам.
31
+ - Технические вопросы ведущий может решать сам только тогда, когда в
32
+ настройках панели написано «Технические вопросы решает ведущий: да», и
33
+ по правилам skill `harness`. Вопросы, меняющие результат для
34
+ пользователя, — всегда пользователю, при любой настройке.
35
+ - Не правь каталог состояния, политику или файл представления, чтобы
36
+ «исправить» то, что показывает панель. Панель показывает harness.
37
+ Неверное число — находка для harness, сообщи о ней.
38
+ - Не говори «проверено», «готово» или «заблокировано» без того, как, кем и
39
+ почему, — так же, как этого не делает панель.
40
+
41
+ ## 0. Предложить панель в начале долгого запуска
42
+
43
+ Когда начинается долгий запуск harness (несколько поручений или работа,
44
+ которая займёт больше нескольких минут), сразу предложи пользователю панель:
45
+ запусти её (шаги 1–4) и дай URL. Если панель недоступна, предложи текстовое
46
+ наблюдение `$H status --state <state> --human --watch` (шаг 6).
47
+
48
+ ## 1. Найти пути
49
+
50
+ 1. Корень репозитория: `git rev-parse --show-toplevel`.
51
+ 2. Политика: `<repo>/.harness/policy.json`.
52
+ 3. Состояние: `paths.state` в `<repo>/.harness/project.json`. Оно лежит вне
53
+ репозитория. Если его ещё нет, ничего не запускалось: скажи об этом и
54
+ предложи `--demo`, чтобы показать панель на примере.
55
+ 4. Если `.harness/` нет, проект не настроен. Сначала используй skill
56
+ `harness-setup` и не выдумывай пути.
57
+
58
+ ## 2. Проверить версии
59
+
60
+ ```sh
61
+ VIEW_DIR=$(mktemp -d) # рабочий каталог этой панели, вне репозитория
62
+ $H --version
63
+ $UI --version
64
+ ```
65
+
66
+ Панель читает операторское представление harness (`viewVersion`). Каждый
67
+ выпуск панели поддерживает одну мажорную версию представления. Расхождение
68
+ не мешает работе пользователя: панель показывает
69
+ `View version N is not supported` с подсказкой. Установи подходящую версию
70
+ панели.
71
+
72
+ Живым данным нужен harness с операцией `view`. Проверь каталог операций, а
73
+ не угадывай по ошибке:
74
+
75
+ ```sh
76
+ $H capabilities > "$VIEW_DIR/caps.json" # только чтение
77
+ ```
78
+
79
+ `view` поддерживается, если `data` в этом конверте содержит операцию с
80
+ именем `view`. Если её нет, harness старее. Не запускай `$H view`. Используй
81
+ демо или текстовый статус (шаг 6) и скажи пользователю, что живым данным
82
+ панели нужен более новый harness.
83
+
84
+ ## 3. Запустить панель в фоне
85
+
86
+ Если `$UI --help` перечисляет `--check`, сначала проверь совместимость (только
87
+ чтение):
88
+
89
+ ```sh
90
+ $UI --check --harness <путь к $H> --state <state> --policy .harness/policy.json > "$VIEW_DIR/check.json"
91
+ ```
92
+
93
+ `"compatible": true` — можно запускать. `false` — прочитай `fix` и скажи
94
+ пользователю, какую версию панели или harness поставить; не запускай панель
95
+ вслепую.
96
+
97
+ Предпочитай живой маршрут: панель сама вызывает harness, а открытая страница
98
+ обновляется сама (строка «Данные на HH:MM · обновляются сами»). Пока
99
+ страница закрыта или вкладка скрыта, панель harness не запускает.
100
+
101
+ ```sh
102
+ $UI --state <state> --policy .harness/policy.json --harness <путь к $H> \
103
+ > "$VIEW_DIR/panel.out" 2> "$VIEW_DIR/panel.err" &
104
+ echo $! > "$VIEW_DIR/panel.pid"
105
+ ```
106
+
107
+ `--harness` нужен, когда `$H` — не одна команда из PATH (например, `npx …`):
108
+ передай `<repo>/node_modules/.bin/harness` или путь из skill `harness`.
109
+ Окно истории — `--window 24h` (по умолчанию) или `--window 7d`, если
110
+ пользователь спрашивает о неделе.
111
+
112
+ Если `$UI --help` не перечисляет `--state` (старая панель), запиши снимок
113
+ вне репозитория и раздай его. Панель принимает конверт harness как есть;
114
+ повторная запись файла обновляет открытую страницу.
115
+
116
+ ```sh
117
+ $H view --state <state> --policy .harness/policy.json > "$VIEW_DIR/view.json"
118
+ $UI --view "$VIEW_DIR/view.json" > "$VIEW_DIR/panel.out" 2> "$VIEW_DIR/panel.err" &
119
+ echo $! > "$VIEW_DIR/panel.pid"
120
+ ```
121
+
122
+ Если `$H view` завершился с ненулевым кодом, прочитай его конверт ошибки
123
+ (`error.code`) и сообщи пользователю. `POLICY_REQUIRED` значит, что путь к
124
+ политике неверен. Не раздавай устаревший файл.
125
+
126
+ Язык: у CLI есть `--lang ru|en` (по умолчанию — из системной локали), а у
127
+ страницы — `?lang=ru|en` и переключатель в навигации. Если пользователь
128
+ говорит по-русски, передай `--lang ru`. Разделы панели — hash-адреса:
129
+ `#/` (обзор), `#/work/<id>`, `#/reviews`, `#/decisions`, `#/activity`,
130
+ `#/settings`, `#/history`, `#/health`; давай пользователю ссылку прямо на
131
+ нужный раздел.
132
+
133
+ Без `view`: `$UI --demo` раздаёт встроенный пример. Ясно скажи, что это
134
+ демонстрационные данные, а не их проект.
135
+
136
+ Порт: не указывай `--port`. CLI перебирает 4790–4809 и берёт первый
137
+ свободный. Передавай `--port N`, только если пользователь просит конкретный
138
+ порт.
139
+
140
+ ## 4. Дать URL
141
+
142
+ Первая строка stdout — JSON:
143
+
144
+ ```json
145
+ { "ok": true, "url": "http://127.0.0.1:4790/", "port": 4790, "readOnly": true }
146
+ ```
147
+
148
+ Дождись этой строки в `panel.out` (опрашивай с таймаутом в несколько
149
+ секунд), затем дай пользователю `url` в точности. Если в строке
150
+ `"ok": false`, переходи к разделу «Неполадки» с её `error.code`.
151
+
152
+ ## 5. Рассказать пользователю, что он увидит
153
+
154
+ Коротко и простыми словами, по тому, что на экране:
155
+
156
+ - **Шапка.** Начни с фразы в шапке Overview «Сейчас… От вас: …» и прочитай
157
+ её пользователю как есть: что идёт сейчас и что нужно от него. Если «От
158
+ вас» пусто — от него ничего не нужно.
159
+ - **Нужен ваш ответ**: вопросы, которые ждут именно его, насколько каждый
160
+ серьёзен и может ли ответить только он. Вопросы, которые уже отвечены или
161
+ ждут применения ответа, перечислены отдельно — с тем, кто действует
162
+ дальше. Чтобы прочитать вопрос целиком, используй
163
+ `harness input-show --state <state> --request <id>`. Покажи пользователю
164
+ текст. Не отвечай на него.
165
+ - **Сейчас в работе**: какая задача идёт, на каком этапе (подготовка,
166
+ написание, проверки, ревью, интеграция), сколько времени и сколько
167
+ попыток израсходовано и осталось.
168
+ - **Ждут решения**: работа, которая стоит, пока кто-то (вы, ведущий или
169
+ внешний участник) не примет решение; панель называет, кто и что.
170
+ - **Ждут очереди / Остановлены**: «ждёт очереди» значит «просто ждёт
171
+ очереди — ничего не нужно». «Остановлено» — с причиной простыми словами
172
+ и тем, кто действует дальше.
173
+ - **Карточка работы**:
174
+ - «Что проверено» — как сделана каждая проверка: выполнена, переиспользован
175
+ прежний результат, прочитана ревьюером без запуска, не проверялась.
176
+ Никогда не говори «проверено» или «готово», не назвав, как и кем.
177
+ - «Почему повтор» — простыми словами, чем закончилась прошлая попытка
178
+ (например, «окружение — порт занят»).
179
+ - «Принято локально / в удалённой ветке». Состояние удалённой ветки
180
+ harness читает из её копии на этой машине (remote-tracking ref) без
181
+ `fetch` и без сети, то есть «по последним сведениям git здесь»; рядом
182
+ — когда git последний раз обновил эту копию. С harness `0.1.0-alpha.57`
183
+ панель пишет состояние словами harness («принято локально; в удалённой
184
+ ветке origin/main ещё нет»). Harness `0.1.0-alpha.55` и `.56` ветку не читают и
185
+ всегда пишут «неизвестно» с причиной: не говори «отправлено» или «не
186
+ отправлено» по такому состоянию. Если результат принят только локально,
187
+ предложи push, но не делай его без просьбы пользователя.
188
+ - **Решения**: какие решения приняты (ведущим или пользователем), включая
189
+ временные — с условием, когда их пересмотреть.
190
+ - **Кто что делал**: кто — контроллер harness, исполнитель, reviewer,
191
+ ведущий, вы или хост — что и когда сделал, фразами harness, новые сверху,
192
+ за окно истории. «За окно ничего не происходило» — пустая лента; «harness
193
+ этой версии не ведёт ленту» — производитель ленту не прислал (например,
194
+ harness старше `0.1.0-alpha.57`); это не «ничего не было».
195
+ - **Здоровье**: потрачено против бюджета (`≥` значит «не меньше», потому что
196
+ часть цен неизвестна; `unknown` никогда не ноль), жив ли контроллер,
197
+ зависшие попытки и принятые результаты, которые потом изменились.
198
+ - **Строка свежести** над экраном: «Данные на HH:MM · обновляются сами»
199
+ (живой маршрут), «· снимок…» (файл) или «· проверка раз в 5 секунд»
200
+ (запасной опрос). Если над ней «Не удалось обновить данные с HH:MM: …»,
201
+ на экране устаревшие данные: так и скажи, назови причину и не выдавай
202
+ их за текущие.
203
+ - **Подвал** «Данные harness на HH:MM; панель ничего не меняет»: время
204
+ снимка и напоминание, что нажатия ничего не меняют в работе.
205
+ - У каждого термина есть «что это значит» — предложи раскрыть его, а не
206
+ объясняй своими словами вместо панели. Неизвестное панель никогда не
207
+ показывает как ноль или «в порядке»; не делай этого и ты.
208
+ - Со снимком (`--view`) страница показывает момент снимка. Предложи
209
+ обновить его, повторив строки `$H view`.
210
+
211
+ Если в разделе «Решения» или «Кто что делал» написано «нет данных в этой
212
+ версии harness», так и скажи: это не значит, что решений или событий не
213
+ было. Называй то, что реально видно на экране.
214
+
215
+ ## 6. Остановить
216
+
217
+ ```sh
218
+ kill "$(cat "$VIEW_DIR/panel.pid")"
219
+ ```
220
+
221
+ Ctrl-C тоже останавливает панель, если она работает на переднем плане.
222
+ Остановка панели не влияет на работу harness.
223
+
224
+ Для текстового вида вместо панели запусти
225
+ `$H status --state <state> --human`. Добавляй `--watch`, только если
226
+ `$H --version` — `0.1.0-alpha.54` или новее: старые выпуски отклоняют этот
227
+ флаг. Чтобы обновить, повтори простую команду.
228
+
229
+ ## Неполадки
230
+
231
+ Сообщения об отказах ниже — английские: их пишет сервер панели и harness,
232
+ а не словарь интерфейса.
233
+
234
+ | Симптом (`error.code` или текст страницы) | Что значит | Что делать |
235
+ | ----------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
236
+ | `PORT_BUSY` | заданный порт или все порты 4790–4809 заняты | убери `--port` или выбери свободный; возможно, другая панель уже запущена: проверь файлы `panel.pid` |
237
+ | `HOST_NOT_LOOPBACK` | передан не локальный `--host` | убери `--host`; никогда не открывай панель наружу |
238
+ | `View version N is not supported` | мажорные версии harness и панели различаются | установи версию панели, подходящую к harness; сообщи обе версии |
239
+ | "newer data, update the panel" | harness добавил поля, которые эта панель пропускает | панель работает; предложи обновить её |
240
+ | `VIEW_UNAVAILABLE` / "not readable yet" | файла представления нет | повтори строки `$H view` |
241
+ | `HARNESS_VIEW_UNAVAILABLE` | `--state` использован с панелью или harness без него | проверь `--harness`; иначе используй маршрут через снимок (шаг 3) |
242
+ | `NOT_A_VIEW` "malformed: …" | файл не представление или конверт ошибки | создай его заново через `$H view`; если есть ошибка harness, сообщи её |
243
+ | пустая панель, "No state yet" | в этом каталоге состояния ничего не запускалось | нормально до первого `harness run` |
244
+ | "The app bundle is not built" | запуск из исходного checkout | `npm run build` в checkout панели |
245
+ | «Не удалось обновить данные с HH:MM» | harness отказал, упал или не ответил за 30 с | прочитай причину в строке; проверь `$H status`; на экране последние удачные данные |
246
+ | `"compatible": false` от `--check` | версии панели и harness не подходят друг другу | сделай то, что написано в `fix`; сообщи обе версии |