mandrel 2.124.0 → 2.126.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 (56) hide show
  1. package/.agents/docs/agentrc-reference.json +1 -0
  2. package/.agents/docs/configuration.md +2 -0
  3. package/.agents/docs/runbooks/dispatch-board.md +199 -0
  4. package/.agents/docs/runbooks/dispatch.md +219 -0
  5. package/.agents/docs/runbooks/session-titles.md +52 -0
  6. package/.agents/schemas/agentrc.schema.json +60 -0
  7. package/.agents/scripts/acceptance-eval.js +11 -2
  8. package/.agents/scripts/dispatch.js +411 -0
  9. package/.agents/scripts/lib/child-detached.js +48 -0
  10. package/.agents/scripts/lib/child-exec.js +11 -0
  11. package/.agents/scripts/lib/config/delivery-routing.js +15 -12
  12. package/.agents/scripts/lib/config/temp-paths.js +26 -0
  13. package/.agents/scripts/lib/config-settings-schema-delivery.js +45 -0
  14. package/.agents/scripts/lib/dispatch/environments.js +135 -0
  15. package/.agents/scripts/lib/dispatch/launch-cloud.js +164 -0
  16. package/.agents/scripts/lib/dispatch/launch-local.js +77 -0
  17. package/.agents/scripts/lib/dispatch/liveness.js +21 -0
  18. package/.agents/scripts/lib/dispatch/record.js +54 -0
  19. package/.agents/scripts/lib/dispatch/status.js +329 -0
  20. package/.agents/scripts/lib/dispatch/targets.js +101 -0
  21. package/.agents/scripts/lib/dispatch/verdict.js +207 -0
  22. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  23. package/.agents/scripts/lib/observability/source-classifier.js +2 -0
  24. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +2 -0
  25. package/.agents/scripts/lib/orchestration/story-handoff.js +6 -0
  26. package/.agents/scripts/lib/orchestration/story-stage-publish.js +147 -0
  27. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  28. package/.agents/scripts/lib/story-body/story-body.js +5 -2
  29. package/.agents/scripts/session-title.js +187 -0
  30. package/.agents/scripts/single-story-confirm-merge.js +7 -0
  31. package/.agents/scripts/single-story-init.js +3 -0
  32. package/.agents/workflows/helpers/audit-lens-core.md +4 -0
  33. package/.agents/workflows/helpers/deliver-light.md +4 -1
  34. package/.agents/workflows/helpers/qa-core.md +2 -0
  35. package/.agents/workflows/mandrel-deliver.md +7 -3
  36. package/.agents/workflows/mandrel-orchestrate.md +2 -0
  37. package/.agents/workflows/mandrel-plan.md +4 -0
  38. package/README.md +8 -0
  39. package/bin/mandrel.js +35 -13
  40. package/docs/CHANGELOG.md +27 -0
  41. package/lib/cli/dispatch.js +28 -0
  42. package/lib/cli/ui/accounts.js +81 -0
  43. package/lib/cli/ui/assignee-filter.js +91 -0
  44. package/lib/cli/ui/board-model.js +399 -0
  45. package/lib/cli/ui/board.css +578 -0
  46. package/lib/cli/ui/board.html +84 -0
  47. package/lib/cli/ui/board.js +755 -0
  48. package/lib/cli/ui/log-tail.js +89 -0
  49. package/lib/cli/ui/panel-model.js +100 -0
  50. package/lib/cli/ui/preferences.js +136 -0
  51. package/lib/cli/ui/request-guard.js +108 -0
  52. package/lib/cli/ui/server.js +230 -0
  53. package/lib/cli/ui/sources.js +258 -0
  54. package/lib/cli/ui/story-detail.js +99 -0
  55. package/lib/cli/ui.js +124 -0
  56. package/package.json +1 -1
@@ -0,0 +1,399 @@
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
+ /** The Epic a card names, linked to its issue when the repository is known. */
146
+ function epicView(epic, repository) {
147
+ if (!epic) return null;
148
+ return {
149
+ text: `Epic #${epic.id} · ${epic.title ?? ''}`.trim(),
150
+ url: repository
151
+ ? githubUrl(`https://github.com/${repository}/issues/${epic.id}`)
152
+ : null,
153
+ };
154
+ }
155
+
156
+ /**
157
+ * The fields a card shows.
158
+ *
159
+ * @param {object} story A read-model Story row.
160
+ * @param {{ openIds: Set<number>, repository?: string|null }} board
161
+ * @param {number} now Epoch milliseconds.
162
+ */
163
+ function cardView(story, { openIds, repository }, now) {
164
+ return {
165
+ id: story.id,
166
+ title: story.title ?? '',
167
+ epic: epicView(story.epic, repository),
168
+ stage: story.stage ?? null,
169
+ environment: story.environment ?? null,
170
+ pr: prView(story.pr),
171
+ unmet: unmetOf(story, openIds),
172
+ status: statusView(story, now),
173
+ };
174
+ }
175
+
176
+ /**
177
+ * Online state per environment name from `/api/connections`; an
178
+ * environment the connections report does not name is taken as online.
179
+ */
180
+ function onlineMap(connections) {
181
+ const map = new Map();
182
+ for (const env of connections?.environments ?? []) {
183
+ map.set(env.name, { online: env.online, reason: env.reason ?? null });
184
+ }
185
+ return map;
186
+ }
187
+
188
+ function laneOf(env, online) {
189
+ const status = online.get(env.name) ?? { online: true, reason: null };
190
+ return {
191
+ name: env.name,
192
+ target: env.target,
193
+ load: env.load,
194
+ capacity: env.capacity,
195
+ online: status.online,
196
+ reason: status.reason,
197
+ header: status.online ? `${env.load}/${env.capacity}` : 'offline',
198
+ cards: [],
199
+ };
200
+ }
201
+
202
+ /**
203
+ * Columns with their cards; Delivering also carries one lane per
204
+ * environment plus the `untracked` lane.
205
+ *
206
+ * @param {{ environments?: object[], stories?: object[], repository?: string|null }} state
207
+ * @param {{ environments?: object[] }|null} [connections]
208
+ * @param {number} [now] Epoch milliseconds the relative times count to.
209
+ * @param {(story: object) => boolean} [shows] Which Stories get a card;
210
+ * dependencies still count every Story on the board.
211
+ */
212
+ export function buildBoard(
213
+ state,
214
+ connections = null,
215
+ now = Date.now(),
216
+ shows = () => true,
217
+ ) {
218
+ const stories = state?.stories ?? [];
219
+ const openIds = new Set(
220
+ stories.filter((s) => s.column !== 'done').map((s) => s.id),
221
+ );
222
+ const online = onlineMap(connections);
223
+ const lanes = (state?.environments ?? []).map((e) => laneOf(e, online));
224
+ const untracked = {
225
+ name: UNTRACKED,
226
+ target: null,
227
+ load: null,
228
+ capacity: null,
229
+ online: true,
230
+ reason: null,
231
+ header: '',
232
+ cards: [],
233
+ };
234
+ const columns = COLUMNS.map((c) => ({ ...c, cards: [], lanes: null }));
235
+ const byId = new Map(columns.map((c) => [c.id, c]));
236
+ byId.get('delivering').lanes = [...lanes, untracked];
237
+ const board = { openIds, repository: state?.repository ?? null };
238
+ for (const story of stories.filter(shows)) {
239
+ const column = byId.get(story.column);
240
+ if (!column) continue;
241
+ const card = cardView(story, board, now);
242
+ if (column.lanes) {
243
+ const lane =
244
+ column.lanes.find((l) => l.name === story.environment) ?? untracked;
245
+ lane.cards.push(card);
246
+ } else {
247
+ column.cards.push(card);
248
+ }
249
+ }
250
+ return { columns, offline: lanes.filter((l) => !l.online).length };
251
+ }
252
+
253
+ const stamp = (iso) => `${String(iso).replace('T', ' ').slice(0, 16)} UTC`;
254
+
255
+ function recordRows(record) {
256
+ if (!record) return [];
257
+ return [
258
+ ['pid', record.pid],
259
+ ['Started', record.startedAt && stamp(record.startedAt)],
260
+ ['Session', record.sessionId],
261
+ ['Session URL', record.sessionUrl],
262
+ ['Command', record.argv?.join(' ')],
263
+ ].filter(([, value]) => value !== null && value !== undefined);
264
+ }
265
+
266
+ function timelineLine(entry, now) {
267
+ return `${entry.stage}: ${stamp(entry.at)} (${elapsed(entry.at, now) ?? '?'} ago)`;
268
+ }
269
+
270
+ function processText(proc, now) {
271
+ const { text } = livenessView(proc, null);
272
+ const running = since('running', proc?.startedAt, now);
273
+ return running ? `${text}, ${running}` : text;
274
+ }
275
+
276
+ const assigneesText = (assignees) =>
277
+ (assignees ?? []).join(', ') || 'unassigned';
278
+
279
+ const epicText = (epic) => (epic ? `#${epic.id} ${epic.title}` : 'none');
280
+
281
+ function factRows(detail, now) {
282
+ return [
283
+ ['Column', detail.column],
284
+ ['Environment', detail.environment ?? 'none'],
285
+ ['Stage', detail.stage ?? 'none'],
286
+ ['Process', processText(detail.process, now)],
287
+ ['Assignees', assigneesText(detail.assignees)],
288
+ ['Epic', epicText(detail.epic)],
289
+ ['Labels', (detail.labels ?? []).join(', ') || 'none'],
290
+ ];
291
+ }
292
+
293
+ /**
294
+ * The Story detail view's sections from a `/api/story` response.
295
+ *
296
+ * @param {object} detail
297
+ * @param {number} [now] Epoch milliseconds.
298
+ */
299
+ export function storyDetailView(detail, now = Date.now()) {
300
+ return {
301
+ heading: `#${detail.id} ${detail.title ?? ''}`.trim(),
302
+ issueUrl: githubUrl(detail.issueUrl),
303
+ pr: prView(detail.pr),
304
+ facts: factRows(detail, now),
305
+ timeline: (detail.history ?? []).map((entry) => timelineLine(entry, now)),
306
+ record: recordRows(detail.record),
307
+ resumeCommand: detail.resumeCommand ?? null,
308
+ log: (detail.logTail ?? []).join('\n') || 'No log output yet.',
309
+ };
310
+ }
311
+
312
+ /**
313
+ * The text a verdict reads as: what the drop would do, or why not.
314
+ *
315
+ * @param {{ ok: boolean, action: string, environment?: string, reason?: string, detail?: string }} verdict
316
+ * @returns {string}
317
+ */
318
+ function verdictText(verdict) {
319
+ if (!verdict.ok) return verdict.detail || verdict.reason || 'Refused';
320
+ return ACTION_TEXT[verdict.action](verdict.environment);
321
+ }
322
+
323
+ /**
324
+ * What dropping `story` on `zone` (a column id or an environment name)
325
+ * would do. `kind` is `action` (run it), `confirm` (ask first, then run),
326
+ * `copy` (copy `text`'s command), `refused` or `none`.
327
+ *
328
+ * @param {object} story A read-model Story row.
329
+ * @param {string} zone
330
+ * @returns {{ kind: string, text: string, action?: string, environment?: string }}
331
+ */
332
+ export function zoneVerdict(story, zone) {
333
+ if (zone === story.column || zone === UNTRACKED) {
334
+ return { kind: 'none', text: 'No change' };
335
+ }
336
+ if (zone === 'planning' && story.column === 'backlog') {
337
+ return { kind: 'copy', text: `/mandrel-plan ${story.id}` };
338
+ }
339
+ const verdict = story.drops?.[zone] ?? null;
340
+ if (!verdict) return { kind: 'none', text: 'No action here' };
341
+ if (!verdict.ok) return { kind: 'refused', text: verdictText(verdict) };
342
+ return {
343
+ kind: verdict.action === 'stop' ? 'confirm' : 'action',
344
+ text: verdictText(verdict),
345
+ action: verdict.action,
346
+ environment: verdict.environment,
347
+ };
348
+ }
349
+
350
+ /**
351
+ * Every allowed move for a Story — the Move menu, so no action needs a drag.
352
+ *
353
+ * @param {object} story
354
+ * @param {string[]} zones Column ids and environment names, in board order.
355
+ */
356
+ export function moveOptions(story, zones) {
357
+ return zones
358
+ .map((zone) => ({ zone, ...zoneVerdict(story, zone) }))
359
+ .filter((v) => ['action', 'confirm', 'copy'].includes(v.kind));
360
+ }
361
+
362
+ /**
363
+ * Every drop zone in board order: the columns, then each environment lane.
364
+ *
365
+ * @param {{ environments?: object[] }} state
366
+ * @returns {string[]}
367
+ */
368
+ export function dropZones(state) {
369
+ return [
370
+ ...COLUMNS.map((c) => c.id),
371
+ ...(state?.environments ?? []).map((e) => e.name),
372
+ ];
373
+ }
374
+
375
+ /**
376
+ * The Environments panel view: one card per environment.
377
+ *
378
+ * @param {{ environments?: object[], stories?: object[] }} state
379
+ * @param {{ environments?: object[] }|null} [connections]
380
+ */
381
+ export function environmentCards(state, connections = null) {
382
+ const details = new Map(
383
+ (connections?.environments ?? []).map((e) => [e.name, e]),
384
+ );
385
+ return (state?.environments ?? []).map((env) => {
386
+ const detail = details.get(env.name);
387
+ return {
388
+ name: env.name,
389
+ target: env.target,
390
+ load: `${env.load}/${env.capacity}`,
391
+ online: detail ? detail.online : true,
392
+ reason: detail?.reason ?? null,
393
+ definedIn: detail?.definedIn ?? 'unknown',
394
+ stories: (state.stories ?? [])
395
+ .filter((s) => s.environment === env.name && s.column !== 'done')
396
+ .map((s) => s.id),
397
+ };
398
+ });
399
+ }