mandrel 2.123.0 → 2.125.0

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 (105) hide show
  1. package/.agents/README.md +1 -1
  2. package/.agents/docs/agentrc-reference.json +2 -0
  3. package/.agents/docs/configuration.md +6 -3
  4. package/.agents/docs/runbooks/dispatch-board.md +174 -0
  5. package/.agents/docs/runbooks/dispatch.md +219 -0
  6. package/.agents/docs/runbooks/session-titles.md +52 -0
  7. package/.agents/runtime-deps.json +2 -2
  8. package/.agents/schemas/agentrc.schema.json +85 -3
  9. package/.agents/schemas/audit-rules.schema.json +1 -1
  10. package/.agents/schemas/story-deliver-terminal.schema.json +7 -2
  11. package/.agents/scripts/acceptance-eval.js +11 -2
  12. package/.agents/scripts/check-doc-links.js +4 -4
  13. package/.agents/scripts/dispatch.js +400 -0
  14. package/.agents/scripts/lib/audit-baselines/surface-entry.js +2 -2
  15. package/.agents/scripts/lib/audit-exceptions/globs.js +2 -2
  16. package/.agents/scripts/lib/audit-exceptions/scope.js +2 -2
  17. package/.agents/scripts/lib/audit-suite/selector.js +3 -3
  18. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +3 -3
  19. package/.agents/scripts/lib/baselines/components.js +2 -2
  20. package/.agents/scripts/lib/baselines/kinds/_crap-new-method-gate.js +2 -2
  21. package/.agents/scripts/lib/bdd-runner-detect.js +3 -4
  22. package/.agents/scripts/lib/child-detached.js +48 -0
  23. package/.agents/scripts/lib/child-exec.js +11 -0
  24. package/.agents/scripts/lib/close-validation/base-sync-revalidation.js +2 -2
  25. package/.agents/scripts/lib/config/delivery-routing.js +15 -12
  26. package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
  27. package/.agents/scripts/lib/config/handoff.js +21 -6
  28. package/.agents/scripts/lib/config/temp-paths.js +26 -0
  29. package/.agents/scripts/lib/config-settings-schema-delivery.js +64 -10
  30. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  31. package/.agents/scripts/lib/coverage-baseline.js +3 -3
  32. package/.agents/scripts/lib/coverage-capture-delta.js +2 -2
  33. package/.agents/scripts/lib/coverage-capture-own-fix.js +2 -2
  34. package/.agents/scripts/lib/dispatch/environments.js +135 -0
  35. package/.agents/scripts/lib/dispatch/launch-cloud.js +164 -0
  36. package/.agents/scripts/lib/dispatch/launch-local.js +77 -0
  37. package/.agents/scripts/lib/dispatch/liveness.js +21 -0
  38. package/.agents/scripts/lib/dispatch/record.js +54 -0
  39. package/.agents/scripts/lib/dispatch/status.js +285 -0
  40. package/.agents/scripts/lib/dispatch/targets.js +101 -0
  41. package/.agents/scripts/lib/dispatch/verdict.js +207 -0
  42. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  43. package/.agents/scripts/lib/git-test-guard.js +119 -0
  44. package/.agents/scripts/lib/git-utils.js +3 -0
  45. package/.agents/scripts/lib/maintainability-utils.js +4 -4
  46. package/.agents/scripts/lib/observability/handoff-telemetry.js +2 -0
  47. package/.agents/scripts/lib/observability/source-classifier.js +2 -0
  48. package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js +3 -2
  49. package/.agents/scripts/lib/orchestration/block-class-recovery.js +44 -0
  50. package/.agents/scripts/lib/orchestration/code-review.js +35 -19
  51. package/.agents/scripts/lib/orchestration/diff-magnitude.js +1 -1
  52. package/.agents/scripts/lib/orchestration/git-cleanup/phases/filters.js +3 -3
  53. package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +3 -4
  54. package/.agents/scripts/lib/orchestration/review-history.js +9 -10
  55. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +9 -2
  56. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +8 -5
  57. package/.agents/scripts/lib/orchestration/review-providers/codex.js +3 -11
  58. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  59. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +22 -0
  60. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +10 -2
  61. package/.agents/scripts/lib/orchestration/review-providers/types.js +2 -0
  62. package/.agents/scripts/lib/orchestration/review-providers/ultrareview.js +13 -2
  63. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +40 -15
  64. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +2 -0
  65. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +8 -1
  66. package/.agents/scripts/lib/orchestration/story-handoff.js +222 -54
  67. package/.agents/scripts/lib/orchestration/story-stage-publish.js +147 -0
  68. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  69. package/.agents/scripts/lib/test-temp.js +5 -5
  70. package/.agents/scripts/lib/test-tiers.js +3 -3
  71. package/.agents/scripts/lib/util/glob-match.js +64 -0
  72. package/.agents/scripts/lib/wave-runner/footprint.js +3 -3
  73. package/.agents/scripts/run-tests.js +2 -1
  74. package/.agents/scripts/session-title.js +187 -0
  75. package/.agents/scripts/single-story-confirm-merge.js +7 -0
  76. package/.agents/scripts/single-story-init.js +6 -3
  77. package/.agents/workflows/helpers/audit-lens-core.md +4 -0
  78. package/.agents/workflows/helpers/code-review.md +8 -1
  79. package/.agents/workflows/helpers/deliver-digest.md +22 -23
  80. package/.agents/workflows/helpers/deliver-light.md +4 -1
  81. package/.agents/workflows/helpers/deliver-reference.md +55 -24
  82. package/.agents/workflows/helpers/deliver-story-reference.md +10 -3
  83. package/.agents/workflows/helpers/deliver-story.md +27 -7
  84. package/.agents/workflows/helpers/qa-core.md +2 -0
  85. package/.agents/workflows/mandrel-deliver.md +14 -4
  86. package/.agents/workflows/mandrel-orchestrate.md +2 -0
  87. package/.agents/workflows/mandrel-plan.md +4 -0
  88. package/README.md +8 -0
  89. package/bin/mandrel.js +35 -13
  90. package/docs/CHANGELOG.md +29 -0
  91. package/lib/cli/dispatch.js +27 -0
  92. package/lib/cli/ui/accounts.js +81 -0
  93. package/lib/cli/ui/board-model.js +372 -0
  94. package/lib/cli/ui/board.css +525 -0
  95. package/lib/cli/ui/board.html +80 -0
  96. package/lib/cli/ui/board.js +676 -0
  97. package/lib/cli/ui/log-tail.js +89 -0
  98. package/lib/cli/ui/panel-model.js +100 -0
  99. package/lib/cli/ui/preferences.js +136 -0
  100. package/lib/cli/ui/request-guard.js +108 -0
  101. package/lib/cli/ui/server.js +211 -0
  102. package/lib/cli/ui/sources.js +202 -0
  103. package/lib/cli/ui/story-detail.js +92 -0
  104. package/lib/cli/ui.js +114 -0
  105. package/package.json +2 -2
@@ -0,0 +1,372 @@
1
+ // lib/cli/ui/board-model.js
2
+ /**
3
+ * The `mandrel ui` view model: pure functions from the dispatch status read
4
+ * model to columns, lanes, cards and drop-zone verdict text. It runs in the
5
+ * browser (served as a module) and under `node --test`, so it imports
6
+ * nothing. It evaluates no dispatch rule: every verdict it shows is one the
7
+ * read model already computed into the Story's `drops`.
8
+ *
9
+ * @module cli/ui/board-model
10
+ */
11
+
12
+ const COLUMNS = Object.freeze([
13
+ { id: 'backlog', title: 'Backlog' },
14
+ { id: 'planning', title: 'Planning' },
15
+ { id: 'ready', title: 'Ready' },
16
+ { id: 'delivering', title: 'Delivering' },
17
+ { id: 'blocked', title: 'Blocked' },
18
+ { id: 'done', title: 'Done' },
19
+ ]);
20
+
21
+ /** The Delivering lane for in-flight Stories that name no environment. */
22
+ const UNTRACKED = 'untracked';
23
+
24
+ /** The published delivery stages, in order. */
25
+ const STAGES = Object.freeze(['build', 'check', 'handoff', 'close', 'merge']);
26
+
27
+ /** A step before, at and after the current stage. */
28
+ const STEP_STATES = ['done', 'current', 'todo'];
29
+
30
+ /** Columns whose cards show the delivery status row. */
31
+ const IN_FLIGHT = new Set(['delivering', 'blocked']);
32
+
33
+ const LIVENESS_TEXT = {
34
+ working: 'working',
35
+ exited: 'process exited',
36
+ unknown: 'unknown',
37
+ };
38
+
39
+ const ACTION_TEXT = {
40
+ dispatch: (env) => `Dispatch to ${env}`,
41
+ resume: (env) => `Resume in ${env}`,
42
+ stop: () => 'Stop and return to Ready',
43
+ };
44
+
45
+ /**
46
+ * @param {{ total: number, passed: number, failed: number, pending: number }|null|undefined} checks
47
+ * @returns {string}
48
+ */
49
+ function checksText(checks) {
50
+ if (!checks || checks.total === 0) return 'no checks';
51
+ const parts = [`${checks.passed}/${checks.total} passed`];
52
+ if (checks.failed > 0) parts.push(`${checks.failed} failed`);
53
+ if (checks.pending > 0) parts.push(`${checks.pending} pending`);
54
+ return parts.join(', ');
55
+ }
56
+
57
+ /** `url` when it is a GitHub page, else `null`: no other link is rendered. */
58
+ function githubUrl(url) {
59
+ return typeof url === 'string' && url.startsWith('https://github.com/')
60
+ ? url
61
+ : null;
62
+ }
63
+
64
+ function prView(pr) {
65
+ if (!pr) return null;
66
+ return {
67
+ number: pr.number,
68
+ url: githubUrl(pr.url),
69
+ checks: checksText(pr.checks),
70
+ };
71
+ }
72
+
73
+ /**
74
+ * Time from `iso` to `now` as `Nm` or `Nh Mm`; `null` when `iso` is not a date.
75
+ *
76
+ * @param {string|null|undefined} iso
77
+ * @param {number} now Epoch milliseconds.
78
+ * @returns {string|null}
79
+ */
80
+ function elapsed(iso, now) {
81
+ const ms = now - Date.parse(iso ?? '');
82
+ return Number.isFinite(ms) ? minutesText(Math.floor(ms / 60_000)) : null;
83
+ }
84
+
85
+ function minutesText(minutes) {
86
+ if (minutes < 60) return `${Math.max(0, minutes)}m`;
87
+ return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
88
+ }
89
+
90
+ /** Each stage marked `done`, `current` or `todo` against `stage`. */
91
+ function stepper(stage) {
92
+ const at = STAGES.indexOf(stage);
93
+ return STAGES.map((name, i) => ({
94
+ name,
95
+ state: STEP_STATES[Math.sign(i - at) + 1],
96
+ }));
97
+ }
98
+
99
+ /**
100
+ * The liveness badge; `warning` flags a process gone while the Story still
101
+ * reads as executing.
102
+ *
103
+ * @param {{ state?: string }|null|undefined} proc
104
+ * @param {string|null|undefined} agentState
105
+ */
106
+ function livenessView(proc, agentState) {
107
+ const state = LIVENESS_TEXT[proc?.state] ? proc.state : 'unknown';
108
+ return {
109
+ state,
110
+ text: LIVENESS_TEXT[state],
111
+ warning: state === 'exited' && agentState === 'agent::executing',
112
+ };
113
+ }
114
+
115
+ /** `<label> <elapsed><suffix>`, or `null` when `iso` is not a date. */
116
+ function since(label, iso, now, suffix = '') {
117
+ const time = elapsed(iso, now);
118
+ return time && `${label} ${time}${suffix}`;
119
+ }
120
+
121
+ /** The in-flight status row, or `null` for a card that is not in flight. */
122
+ function statusView(story, now) {
123
+ if (!IN_FLIGHT.has(story.column)) return null;
124
+ return {
125
+ stage: story.stage ?? 'no stage yet',
126
+ steps: stepper(story.stage),
127
+ liveness: livenessView(story.process, story.state),
128
+ running: since('running', story.process?.startedAt, now),
129
+ updated: since('updated', story.stageUpdatedAt, now, ' ago'),
130
+ };
131
+ }
132
+
133
+ /**
134
+ * Dependencies still open on the board: named by the Story and present in a
135
+ * column other than Done.
136
+ *
137
+ * @param {{ dependsOn?: number[] }} story
138
+ * @param {Set<number>} openIds
139
+ * @returns {number[]}
140
+ */
141
+ function unmetOf(story, openIds) {
142
+ return (story.dependsOn ?? []).filter((id) => openIds.has(id));
143
+ }
144
+
145
+ /**
146
+ * The fields a card shows.
147
+ *
148
+ * @param {object} story A read-model Story row.
149
+ * @param {Set<number>} openIds
150
+ * @param {number} now Epoch milliseconds.
151
+ */
152
+ function cardView(story, openIds, now) {
153
+ return {
154
+ id: story.id,
155
+ title: story.title ?? '',
156
+ stage: story.stage ?? null,
157
+ environment: story.environment ?? null,
158
+ pr: prView(story.pr),
159
+ unmet: unmetOf(story, openIds),
160
+ status: statusView(story, now),
161
+ };
162
+ }
163
+
164
+ /**
165
+ * Online state per environment name from `/api/connections`; an
166
+ * environment the connections report does not name is taken as online.
167
+ */
168
+ function onlineMap(connections) {
169
+ const map = new Map();
170
+ for (const env of connections?.environments ?? []) {
171
+ map.set(env.name, { online: env.online, reason: env.reason ?? null });
172
+ }
173
+ return map;
174
+ }
175
+
176
+ function laneOf(env, online) {
177
+ const status = online.get(env.name) ?? { online: true, reason: null };
178
+ return {
179
+ name: env.name,
180
+ target: env.target,
181
+ load: env.load,
182
+ capacity: env.capacity,
183
+ online: status.online,
184
+ reason: status.reason,
185
+ header: status.online ? `${env.load}/${env.capacity}` : 'offline',
186
+ cards: [],
187
+ };
188
+ }
189
+
190
+ /**
191
+ * Columns with their cards; Delivering also carries one lane per
192
+ * environment plus the `untracked` lane.
193
+ *
194
+ * @param {{ environments?: object[], stories?: object[] }} state
195
+ * @param {{ environments?: object[] }|null} [connections]
196
+ * @param {number} [now] Epoch milliseconds the relative times count to.
197
+ */
198
+ export function buildBoard(state, connections = null, now = Date.now()) {
199
+ const stories = state?.stories ?? [];
200
+ const openIds = new Set(
201
+ stories.filter((s) => s.column !== 'done').map((s) => s.id),
202
+ );
203
+ const online = onlineMap(connections);
204
+ const lanes = (state?.environments ?? []).map((e) => laneOf(e, online));
205
+ const untracked = {
206
+ name: UNTRACKED,
207
+ target: null,
208
+ load: null,
209
+ capacity: null,
210
+ online: true,
211
+ reason: null,
212
+ header: '',
213
+ cards: [],
214
+ };
215
+ const columns = COLUMNS.map((c) => ({ ...c, cards: [], lanes: null }));
216
+ const byId = new Map(columns.map((c) => [c.id, c]));
217
+ byId.get('delivering').lanes = [...lanes, untracked];
218
+ for (const story of stories) {
219
+ const column = byId.get(story.column);
220
+ if (!column) continue;
221
+ const card = cardView(story, openIds, now);
222
+ if (column.lanes) {
223
+ const lane =
224
+ column.lanes.find((l) => l.name === story.environment) ?? untracked;
225
+ lane.cards.push(card);
226
+ } else {
227
+ column.cards.push(card);
228
+ }
229
+ }
230
+ return { columns, offline: lanes.filter((l) => !l.online).length };
231
+ }
232
+
233
+ const stamp = (iso) => `${String(iso).replace('T', ' ').slice(0, 16)} UTC`;
234
+
235
+ function recordRows(record) {
236
+ if (!record) return [];
237
+ return [
238
+ ['pid', record.pid],
239
+ ['Started', record.startedAt && stamp(record.startedAt)],
240
+ ['Session', record.sessionId],
241
+ ['Session URL', record.sessionUrl],
242
+ ['Command', record.argv?.join(' ')],
243
+ ].filter(([, value]) => value !== null && value !== undefined);
244
+ }
245
+
246
+ function timelineLine(entry, now) {
247
+ return `${entry.stage}: ${stamp(entry.at)} (${elapsed(entry.at, now) ?? '?'} ago)`;
248
+ }
249
+
250
+ function processText(proc, now) {
251
+ const { text } = livenessView(proc, null);
252
+ const running = since('running', proc?.startedAt, now);
253
+ return running ? `${text}, ${running}` : text;
254
+ }
255
+
256
+ function factRows(detail, now) {
257
+ return [
258
+ ['Column', detail.column],
259
+ ['Environment', detail.environment ?? 'none'],
260
+ ['Stage', detail.stage ?? 'none'],
261
+ ['Process', processText(detail.process, now)],
262
+ ['Labels', (detail.labels ?? []).join(', ') || 'none'],
263
+ ];
264
+ }
265
+
266
+ /**
267
+ * The Story detail view's sections from a `/api/story` response.
268
+ *
269
+ * @param {object} detail
270
+ * @param {number} [now] Epoch milliseconds.
271
+ */
272
+ export function storyDetailView(detail, now = Date.now()) {
273
+ return {
274
+ heading: `#${detail.id} ${detail.title ?? ''}`.trim(),
275
+ issueUrl: githubUrl(detail.issueUrl),
276
+ pr: prView(detail.pr),
277
+ facts: factRows(detail, now),
278
+ timeline: (detail.history ?? []).map((entry) => timelineLine(entry, now)),
279
+ record: recordRows(detail.record),
280
+ resumeCommand: detail.resumeCommand ?? null,
281
+ log: (detail.logTail ?? []).join('\n') || 'No log output yet.',
282
+ };
283
+ }
284
+
285
+ /**
286
+ * The text a verdict reads as: what the drop would do, or why not.
287
+ *
288
+ * @param {{ ok: boolean, action: string, environment?: string, reason?: string, detail?: string }} verdict
289
+ * @returns {string}
290
+ */
291
+ function verdictText(verdict) {
292
+ if (!verdict.ok) return verdict.detail || verdict.reason || 'Refused';
293
+ return ACTION_TEXT[verdict.action](verdict.environment);
294
+ }
295
+
296
+ /**
297
+ * What dropping `story` on `zone` (a column id or an environment name)
298
+ * would do. `kind` is `action` (run it), `confirm` (ask first, then run),
299
+ * `copy` (copy `text`'s command), `refused` or `none`.
300
+ *
301
+ * @param {object} story A read-model Story row.
302
+ * @param {string} zone
303
+ * @returns {{ kind: string, text: string, action?: string, environment?: string }}
304
+ */
305
+ export function zoneVerdict(story, zone) {
306
+ if (zone === story.column || zone === UNTRACKED) {
307
+ return { kind: 'none', text: 'No change' };
308
+ }
309
+ if (zone === 'planning' && story.column === 'backlog') {
310
+ return { kind: 'copy', text: `/mandrel-plan ${story.id}` };
311
+ }
312
+ const verdict = story.drops?.[zone] ?? null;
313
+ if (!verdict) return { kind: 'none', text: 'No action here' };
314
+ if (!verdict.ok) return { kind: 'refused', text: verdictText(verdict) };
315
+ return {
316
+ kind: verdict.action === 'stop' ? 'confirm' : 'action',
317
+ text: verdictText(verdict),
318
+ action: verdict.action,
319
+ environment: verdict.environment,
320
+ };
321
+ }
322
+
323
+ /**
324
+ * Every allowed move for a Story — the Move menu, so no action needs a drag.
325
+ *
326
+ * @param {object} story
327
+ * @param {string[]} zones Column ids and environment names, in board order.
328
+ */
329
+ export function moveOptions(story, zones) {
330
+ return zones
331
+ .map((zone) => ({ zone, ...zoneVerdict(story, zone) }))
332
+ .filter((v) => ['action', 'confirm', 'copy'].includes(v.kind));
333
+ }
334
+
335
+ /**
336
+ * Every drop zone in board order: the columns, then each environment lane.
337
+ *
338
+ * @param {{ environments?: object[] }} state
339
+ * @returns {string[]}
340
+ */
341
+ export function dropZones(state) {
342
+ return [
343
+ ...COLUMNS.map((c) => c.id),
344
+ ...(state?.environments ?? []).map((e) => e.name),
345
+ ];
346
+ }
347
+
348
+ /**
349
+ * The Environments panel view: one card per environment.
350
+ *
351
+ * @param {{ environments?: object[], stories?: object[] }} state
352
+ * @param {{ environments?: object[] }|null} [connections]
353
+ */
354
+ export function environmentCards(state, connections = null) {
355
+ const details = new Map(
356
+ (connections?.environments ?? []).map((e) => [e.name, e]),
357
+ );
358
+ return (state?.environments ?? []).map((env) => {
359
+ const detail = details.get(env.name);
360
+ return {
361
+ name: env.name,
362
+ target: env.target,
363
+ load: `${env.load}/${env.capacity}`,
364
+ online: detail ? detail.online : true,
365
+ reason: detail?.reason ?? null,
366
+ definedIn: detail?.definedIn ?? 'unknown',
367
+ stories: (state.stories ?? [])
368
+ .filter((s) => s.environment === env.name && s.column !== 'done')
369
+ .map((s) => s.id),
370
+ };
371
+ });
372
+ }