mandrel 2.125.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.
@@ -18,6 +18,16 @@ the printed URL in a browser on the same machine. It needs what
18
18
  `mandrel dispatch` needs: a GitHub token (`GITHUB_TOKEN`/`GH_TOKEN` or
19
19
  `gh auth login`) and, for the default environment command, the `claude` CLI.
20
20
 
21
+ Run it from your project's root. The board reads the `.agentrc.json` of the
22
+ directory it starts in, and refuses to start (exit 1) when that config names
23
+ no `github.owner` and `github.repo`, printing the directory it looked in.
24
+
25
+ When a state read fails later, the page shows a short message and the
26
+ terminal running `mandrel ui` prints the cause
27
+ (`mandrel ui: board state read failed: …`). The API answers `503` with
28
+ `no-github-repo`, `config-invalid` or `state-unavailable`, never the cause
29
+ itself.
30
+
21
31
  The server stores nothing. Every state read is recomputed from GitHub
22
32
  through the `mandrel dispatch --status` read model, joined with the delivery
23
33
  stage a running delivery publishes on its Story. A read is reused for at
@@ -77,8 +87,14 @@ Columns, in order: **Backlog**, **Planning**, **Ready**, **Delivering**,
77
87
  **Blocked**, **Done**. Delivering holds one lane per configured environment,
78
88
  headed by its name, target and `load/capacity` (or `offline`), plus an
79
89
  `untracked` lane for in-flight Stories that carry no `env::` label. A card
80
- shows the Story id, title, pull request with its check summary, unmet
81
- dependencies and environment.
90
+ shows the Story id, title, the Epic it belongs to, pull request with its
91
+ check summary, unmet dependencies and environment.
92
+
93
+ The board shows every open issue, whoever it is assigned to, plus the most
94
+ recently closed Stories. Epics are not cards: a Story an open Epic lists
95
+ (as a `- [ ] #<id>` checklist item or a native sub-issue) names that Epic
96
+ on its card, linked to its GitHub issue. Assignees and labels stay off the
97
+ card, in the Story detail.
82
98
 
83
99
  A card in Delivering or Blocked also shows a status row:
84
100
 
@@ -93,8 +109,17 @@ A card in Delivering or Blocked also shows a status row:
93
109
 
94
110
  ## The header
95
111
 
96
- The board is always the main view. The header's right side holds three icon
97
- buttons:
112
+ The board is always the main view. The header's right side holds the
113
+ **People** filter and three icon buttons.
114
+
115
+ **People** chooses whose Stories the columns show. Its menu lists
116
+ **Unassigned** and every login assigned to a Story on the board; check any
117
+ number of them, or choose **Everyone** to clear the filter. Its button
118
+ reads `Everyone`, the one choice, or `<n> selected`, and is tinted while a
119
+ filter is on. The choice is saved in this browser. Hidden Stories still
120
+ count as dependencies, so a card can wait on one you have filtered out.
121
+
122
+ The icon buttons:
98
123
 
99
124
  - **Environments** (server-stack icon): a badge shows how many environments
100
125
  are offline, when any are.
@@ -119,7 +144,7 @@ card's **⋯** button. Esc, the × button or opening the same card again
119
144
  closes it. While open it refreshes on the board's poll.
120
145
 
121
146
  The Story detail view shows the GitHub issue link, the pull request and its
122
- checks, the column, environment, stage and labels, the stage timeline (the
147
+ checks, the column, environment, stage, assignees, Epic and labels, the stage timeline (the
123
148
  last 10 stage changes), the dispatch record (pid, start time, session id or
124
149
  URL, command), the last 50 lines of the log summarized one line per event,
125
150
  and the resume command `claude --resume <sessionId>` with a **Copy**
@@ -393,6 +393,17 @@ export async function runDispatch(argv, overrides = {}) {
393
393
  return result.code;
394
394
  }
395
395
 
396
+ /**
397
+ * `runDispatch` with the caller's working directory as the default `cwd`:
398
+ * the `mandrel dispatch` entry, whose package root is not the project.
399
+ *
400
+ * @param {string[]} argv
401
+ * @param {Parameters<typeof runDispatch>[1]} [overrides]
402
+ */
403
+ export function runDispatchFromCwd(argv, overrides = {}) {
404
+ return runDispatch(argv, { cwd: process.cwd(), ...overrides });
405
+ }
406
+
396
407
  runAsCli(import.meta.url, () => runDispatch(process.argv.slice(2)), {
397
408
  source: 'dispatch',
398
409
  usage: DISPATCH_USAGE,
@@ -121,6 +121,8 @@ function storyRow(ticket, column, ctx) {
121
121
  column,
122
122
  state: agentStateOf(ticket.labels),
123
123
  labels: ticket.labels ?? [],
124
+ assignees: ticket.assignees ?? [],
125
+ epic: ctx.epicOf.get(ticket.id) ?? null,
124
126
  environment: environmentOf(ticket.labels),
125
127
  pr: prFor(ticket.id, ctx.prs),
126
128
  dependsOn: parseBlockedBy(ticket.body ?? ''),
@@ -130,6 +132,18 @@ function storyRow(ticket, column, ctx) {
130
132
 
131
133
  const isEpic = (ticket) => (ticket.labels ?? []).includes(TYPE_LABELS.EPIC);
132
134
 
135
+ /** Each child Story id mapped to the open Epic that lists it; the first Epic wins. */
136
+ function epicIndex(epics) {
137
+ const index = new Map();
138
+ for (const epic of epics ?? []) {
139
+ for (const child of epic.children) {
140
+ if (!index.has(child))
141
+ index.set(child, { id: epic.id, title: epic.title });
142
+ }
143
+ }
144
+ return index;
145
+ }
146
+
133
147
  /**
134
148
  * @param {{
135
149
  * environments: import('./environments.js').Environment[],
@@ -139,6 +153,7 @@ const isEpic = (ticket) => (ticket.labels ?? []).includes(TYPE_LABELS.EPIC);
139
153
  * operator?: string|null,
140
154
  * doneLimit?: number,
141
155
  * closedTotal?: number|null,
156
+ * epics?: Array<{ id: number, title: string, children: number[] }>,
142
157
  * }} board
143
158
  * @returns {{ environments: object[], stories: object[], doneShown: number,
144
159
  * doneTotal: number|null }}
@@ -151,6 +166,7 @@ export function buildStatus({
151
166
  operator = null,
152
167
  doneLimit = DEFAULT_DONE_LIMIT,
153
168
  closedTotal = null,
169
+ epics = [],
154
170
  }) {
155
171
  const loads = computeLoads(environments, openTickets);
156
172
  const ctx = {
@@ -159,6 +175,7 @@ export function buildStatus({
159
175
  operator,
160
176
  prs: prs ?? [],
161
177
  openIds: new Set(openTickets.map((t) => t.id)),
178
+ epicOf: epicIndex(epics),
162
179
  };
163
180
  const open = openTickets
164
181
  .filter((t) => !isEpic(t))
@@ -221,15 +238,42 @@ function closedStoryTotal(gh, repoPath) {
221
238
  .catch(() => null);
222
239
  }
223
240
 
241
+ /** Child ids an Epic's body lists as `- [ ] #<id>` checklist items. */
242
+ const checklistChildren = (body) =>
243
+ [...String(body ?? '').matchAll(/-\s*\[[ xX]\]\s+#(\d+)/g)].map((m) =>
244
+ Number(m[1]),
245
+ );
246
+
247
+ /** An open Epic with its children: checklist items plus native sub-issues. */
248
+ async function epicWithChildren(provider, epic) {
249
+ const native = await Promise.resolve(
250
+ provider.getNativeSubIssues?.(epic.nodeId, epic.id),
251
+ ).catch(() => null);
252
+ const children = new Set([
253
+ ...checklistChildren(epic.body),
254
+ ...(native ?? []),
255
+ ]);
256
+ return { id: epic.id, title: epic.title, children: [...children] };
257
+ }
258
+
259
+ /** The open tickets and, for each open Epic among them, its children. */
260
+ async function openTicketsWithEpics(provider) {
261
+ const openTickets = await provider.listTicketsByLabel({ state: 'open' });
262
+ const epics = await Promise.all(
263
+ openTickets.filter(isEpic).map((e) => epicWithChildren(provider, e)),
264
+ );
265
+ return { openTickets, epics };
266
+ }
267
+
224
268
  /**
225
- * Live board data: every open issue, the most recently updated closed
269
+ * Live board data: every open issue (with each open Epic's children), the most recently updated closed
226
270
  * Stories (one page of up to 100, sorted by `closedAt` in
227
271
  * {@link buildStatus}), their total count, and the open pull requests with
228
272
  * their checks.
229
273
  *
230
274
  * @param {{ provider: object, gh: object, config: object, doneLimit?: number }} deps
231
- * @returns {Promise<{ openTickets: object[], closedStories: object[],
232
- * closedTotal: number|null, prs: object[] }>}
275
+ * @returns {Promise<{ openTickets: object[], epics: object[],
276
+ * closedStories: object[], closedTotal: number|null, prs: object[] }>}
233
277
  */
234
278
  export async function fetchBoard({
235
279
  provider,
@@ -238,8 +282,8 @@ export async function fetchBoard({
238
282
  doneLimit = DEFAULT_DONE_LIMIT,
239
283
  }) {
240
284
  const repoPath = `${config?.github?.owner ?? '{owner}'}/${config?.github?.repo ?? '{repo}'}`;
241
- const [openTickets, closedStories, closedTotal, prs] = await Promise.all([
242
- provider.listTicketsByLabel({ state: 'open' }),
285
+ const [open, closedStories, closedTotal, prs] = await Promise.all([
286
+ openTicketsWithEpics(provider),
243
287
  closedPage(gh, repoPath, doneLimit),
244
288
  closedStoryTotal(gh, repoPath),
245
289
  gh.pr.list(
@@ -248,7 +292,7 @@ export async function fetchBoard({
248
292
  ),
249
293
  ]);
250
294
  return {
251
- openTickets,
295
+ ...open,
252
296
  closedStories,
253
297
  closedTotal,
254
298
  prs: Array.isArray(prs) ? prs : [],
@@ -125,7 +125,7 @@ const WIDE_MARKER_LINE_RE = /^>\s*\*\*Wide:\*\*/;
125
125
  const AUTHORED_MARKER_LINE_RE = /^\s*>\s*🏷️\s+Authored with Mandrel\b/;
126
126
  const META_BLOCK_RE = /<!--\s*meta:[\s\S]*?-->/;
127
127
  // Provenance and plan-story markers persist appends after the last section
128
- // can land in a path list; a whole-line comment is never a path bullet.
128
+ // can land in any list; a whole-line comment is never a list entry.
129
129
  const WHOLE_LINE_COMMENT_RE = /^\s*<!--.*-->\s*$/;
130
130
 
131
131
  /**
@@ -447,7 +447,10 @@ function parsePathEntrySection(lines, warnings) {
447
447
  * @returns {string[]}
448
448
  */
449
449
  function parseTextListSection(lines) {
450
- return lines.map((l) => stripListMarker(l)).filter(Boolean);
450
+ return lines
451
+ .filter(isNotCommentLine)
452
+ .map((l) => stripListMarker(l))
453
+ .filter(Boolean);
451
454
  }
452
455
 
453
456
  /**
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,19 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.126.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.125.0...mandrel-v2.126.0) (2026-11-19)
19
+
20
+
21
+ ### Added
22
+
23
+ * dispatch board: (1) a header multi-select assignee filter (named users… ([#6133](https://github.com/dsj1984/mandrel/issues/6133)) ([#6134](https://github.com/dsj1984/mandrel/issues/6134)) ([9335a90](https://github.com/dsj1984/mandrel/commit/9335a904d120f7b87792709514336d4092474c2a))
24
+
25
+
26
+ ### Fixed
27
+
28
+ * fix mandrel dispatch CLI resolving config from the package dir in consu… ([#6128](https://github.com/dsj1984/mandrel/issues/6128)) ([#6129](https://github.com/dsj1984/mandrel/issues/6129)) ([04d85d9](https://github.com/dsj1984/mandrel/commit/04d85d96ff7de50819bbea0db8eddad18379b3c8))
29
+ * fix story-body parser so whole-line HTML comments (the plan-story finge… ([#6131](https://github.com/dsj1984/mandrel/issues/6131)) ([#6132](https://github.com/dsj1984/mandrel/issues/6132)) ([3aa4a97](https://github.com/dsj1984/mandrel/commit/3aa4a97bbd3f6755b327be282b50de0ecae5ac00))
30
+
18
31
  ## [2.125.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.124.0...mandrel-v2.125.0) (2026-11-19)
19
32
 
20
33
 
@@ -3,13 +3,14 @@
3
3
  * `mandrel dispatch` subcommand: the operator-facing face of
4
4
  * `.agents/scripts/dispatch.js`. Both call `runDispatch`, so they share one
5
5
  * envelope and one set of exit codes; this module only maps the code onto
6
- * the process.
6
+ * the process. Config resolves from the operator's directory, not the
7
+ * package root, which in a consumer install sits under `node_modules/`.
7
8
  *
8
9
  * Injectable seams (used by tests): `exit` replaces setting
9
10
  * `process.exitCode`; every other key is passed to `runDispatch`.
10
11
  */
11
12
 
12
- import { runDispatch } from '../../.agents/scripts/dispatch.js';
13
+ import { runDispatchFromCwd as runDispatch } from '../../.agents/scripts/dispatch.js';
13
14
 
14
15
  /**
15
16
  * @param {string[]} argv
@@ -0,0 +1,91 @@
1
+ // lib/cli/ui/assignee-filter.js
2
+ /**
3
+ * The board's assignee filter: which people's Stories the columns show.
4
+ * The selection is a list of GitHub logins plus `UNASSIGNED`; an empty list
5
+ * shows everyone. It is saved per browser, apart from Settings, because its
6
+ * choices come from the board rather than a fixed set. Pure apart from the
7
+ * storage handed in, so it runs in the browser and under `node --test`.
8
+ *
9
+ * @module cli/ui/assignee-filter
10
+ */
11
+
12
+ const FILTER_KEY = 'mandrel-board-assignees';
13
+
14
+ /** The selection value for Stories with no assignee. */
15
+ const UNASSIGNED = ':unassigned';
16
+
17
+ /**
18
+ * The filter's choices: Unassigned first, then every login assigned to a
19
+ * Story on the board, plus any still selected, sorted case-insensitively.
20
+ *
21
+ * @param {Array<{ assignees?: string[] }>} stories
22
+ * @param {string[]} [selected]
23
+ * @returns {Array<{ value: string, text: string, checked: boolean }>}
24
+ */
25
+ export function assigneeOptions(stories, selected = []) {
26
+ const logins = new Set(selected.filter((v) => v !== UNASSIGNED));
27
+ for (const story of stories ?? []) {
28
+ for (const login of story.assignees ?? []) logins.add(login);
29
+ }
30
+ const sorted = [...logins].sort((a, b) =>
31
+ a.localeCompare(b, undefined, { sensitivity: 'base' }),
32
+ );
33
+ return [
34
+ { value: UNASSIGNED, text: 'Unassigned' },
35
+ ...sorted.map((login) => ({ value: login, text: login })),
36
+ ].map((option) => ({ ...option, checked: selected.includes(option.value) }));
37
+ }
38
+
39
+ /**
40
+ * Whether `story` shows under `selected`: everyone when nothing is
41
+ * selected, else a Story assigned to a selected login, or an unassigned
42
+ * Story when Unassigned is selected.
43
+ *
44
+ * @param {{ assignees?: string[] }} story
45
+ * @param {string[]} selected
46
+ */
47
+ export function matchesAssignees(story, selected) {
48
+ if (selected.length === 0) return true;
49
+ const assignees = story.assignees ?? [];
50
+ if (assignees.length === 0) return selected.includes(UNASSIGNED);
51
+ return assignees.some((login) => selected.includes(login));
52
+ }
53
+
54
+ /** The filter button's text: `Everyone`, the one choice, or a count. */
55
+ export function filterSummary(selected) {
56
+ if (selected.length === 0) return 'Everyone';
57
+ if (selected.length > 1) return `${selected.length} selected`;
58
+ return selected[0] === UNASSIGNED ? 'Unassigned' : selected[0];
59
+ }
60
+
61
+ /** `selected` with `value` added or removed. */
62
+ export function toggleAssignee(selected, value, checked) {
63
+ const rest = selected.filter((v) => v !== value);
64
+ return checked ? [...rest, value] : rest;
65
+ }
66
+
67
+ /**
68
+ * The saved selection; anything missing or malformed is everyone.
69
+ *
70
+ * @param {Storage|null} storage
71
+ * @returns {string[]}
72
+ */
73
+ export function loadAssigneeFilter(storage) {
74
+ try {
75
+ const parsed = JSON.parse(storage.getItem(FILTER_KEY));
76
+ return Array.isArray(parsed)
77
+ ? parsed.filter((v) => typeof v === 'string')
78
+ : [];
79
+ } catch {
80
+ return [];
81
+ }
82
+ }
83
+
84
+ /** Save `selected`; a blocked store keeps it for this page only. */
85
+ export function saveAssigneeFilter(storage, selected) {
86
+ try {
87
+ storage.setItem(FILTER_KEY, JSON.stringify(selected));
88
+ } catch {
89
+ // Nothing to recover: everyone shows on the next load.
90
+ }
91
+ }
@@ -142,17 +142,29 @@ function unmetOf(story, openIds) {
142
142
  return (story.dependsOn ?? []).filter((id) => openIds.has(id));
143
143
  }
144
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
+
145
156
  /**
146
157
  * The fields a card shows.
147
158
  *
148
159
  * @param {object} story A read-model Story row.
149
- * @param {Set<number>} openIds
160
+ * @param {{ openIds: Set<number>, repository?: string|null }} board
150
161
  * @param {number} now Epoch milliseconds.
151
162
  */
152
- function cardView(story, openIds, now) {
163
+ function cardView(story, { openIds, repository }, now) {
153
164
  return {
154
165
  id: story.id,
155
166
  title: story.title ?? '',
167
+ epic: epicView(story.epic, repository),
156
168
  stage: story.stage ?? null,
157
169
  environment: story.environment ?? null,
158
170
  pr: prView(story.pr),
@@ -191,11 +203,18 @@ function laneOf(env, online) {
191
203
  * Columns with their cards; Delivering also carries one lane per
192
204
  * environment plus the `untracked` lane.
193
205
  *
194
- * @param {{ environments?: object[], stories?: object[] }} state
206
+ * @param {{ environments?: object[], stories?: object[], repository?: string|null }} state
195
207
  * @param {{ environments?: object[] }|null} [connections]
196
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.
197
211
  */
198
- export function buildBoard(state, connections = null, now = Date.now()) {
212
+ export function buildBoard(
213
+ state,
214
+ connections = null,
215
+ now = Date.now(),
216
+ shows = () => true,
217
+ ) {
199
218
  const stories = state?.stories ?? [];
200
219
  const openIds = new Set(
201
220
  stories.filter((s) => s.column !== 'done').map((s) => s.id),
@@ -215,10 +234,11 @@ export function buildBoard(state, connections = null, now = Date.now()) {
215
234
  const columns = COLUMNS.map((c) => ({ ...c, cards: [], lanes: null }));
216
235
  const byId = new Map(columns.map((c) => [c.id, c]));
217
236
  byId.get('delivering').lanes = [...lanes, untracked];
218
- for (const story of stories) {
237
+ const board = { openIds, repository: state?.repository ?? null };
238
+ for (const story of stories.filter(shows)) {
219
239
  const column = byId.get(story.column);
220
240
  if (!column) continue;
221
- const card = cardView(story, openIds, now);
241
+ const card = cardView(story, board, now);
222
242
  if (column.lanes) {
223
243
  const lane =
224
244
  column.lanes.find((l) => l.name === story.environment) ?? untracked;
@@ -253,12 +273,19 @@ function processText(proc, now) {
253
273
  return running ? `${text}, ${running}` : text;
254
274
  }
255
275
 
276
+ const assigneesText = (assignees) =>
277
+ (assignees ?? []).join(', ') || 'unassigned';
278
+
279
+ const epicText = (epic) => (epic ? `#${epic.id} ${epic.title}` : 'none');
280
+
256
281
  function factRows(detail, now) {
257
282
  return [
258
283
  ['Column', detail.column],
259
284
  ['Environment', detail.environment ?? 'none'],
260
285
  ['Stage', detail.stage ?? 'none'],
261
286
  ['Process', processText(detail.process, now)],
287
+ ['Assignees', assigneesText(detail.assignees)],
288
+ ['Epic', epicText(detail.epic)],
262
289
  ['Labels', (detail.labels ?? []).join(', ') || 'none'],
263
290
  ];
264
291
  }
@@ -132,6 +132,48 @@ button.danger {
132
132
  align-items: center;
133
133
  gap: 8px;
134
134
  }
135
+ .assignee-filter {
136
+ position: relative;
137
+ font-size: 13px;
138
+ }
139
+ .assignee-filter summary {
140
+ cursor: pointer;
141
+ list-style: none;
142
+ padding: 4px 8px;
143
+ border: 1px solid var(--line);
144
+ border-radius: 6px;
145
+ }
146
+ .assignee-filter summary::-webkit-details-marker {
147
+ display: none;
148
+ }
149
+ .assignee-filter.active summary {
150
+ background: var(--accent-soft);
151
+ border-color: var(--accent);
152
+ }
153
+ .filter-label {
154
+ color: var(--muted);
155
+ }
156
+ .filter-menu {
157
+ position: absolute;
158
+ right: 0;
159
+ top: calc(100% + 4px);
160
+ z-index: 20;
161
+ display: flex;
162
+ flex-direction: column;
163
+ gap: 6px;
164
+ min-width: 180px;
165
+ max-height: 60vh;
166
+ overflow-y: auto;
167
+ padding: 8px;
168
+ background: var(--surface);
169
+ border: 1px solid var(--line);
170
+ border-radius: var(--radius-panel);
171
+ }
172
+ .filter-menu label {
173
+ display: flex;
174
+ align-items: center;
175
+ gap: 6px;
176
+ }
135
177
  .icon-button {
136
178
  position: relative;
137
179
  display: inline-flex;
@@ -267,6 +309,17 @@ main {
267
309
  margin: 2px 0 4px;
268
310
  font-size: 14px;
269
311
  }
312
+ .card-epic {
313
+ margin: 0 0 4px;
314
+ font-size: 11px;
315
+ color: var(--muted);
316
+ overflow: hidden;
317
+ text-overflow: ellipsis;
318
+ white-space: nowrap;
319
+ }
320
+ .card-epic a {
321
+ color: inherit;
322
+ }
270
323
  .card-meta {
271
324
  font-size: 11px;
272
325
  color: var(--muted);
@@ -15,6 +15,10 @@
15
15
  <span class="repo mono" id="repository"></span>
16
16
  </div>
17
17
  <div class="actions">
18
+ <details class="assignee-filter" id="assignee-filter" data-testid="assignee-filter">
19
+ <summary title="Show Stories assigned to"><span class="filter-label">People:</span> <span id="assignee-filter-summary" data-testid="assignee-filter-summary">Everyone</span></summary>
20
+ <div class="filter-menu" id="assignee-filter-menu" data-testid="assignee-filter-menu"></div>
21
+ </details>
18
22
  <button type="button" class="icon-button" id="panel-environments-button" data-testid="panel-environments-button" aria-label="Environments" title="Environments" aria-controls="side-panel" aria-expanded="false">
19
23
  <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false"><rect x="3" y="4" width="18" height="7" rx="1.5"/><rect x="3" y="13" width="18" height="7" rx="1.5"/><path d="M7 7.5h.01M7 16.5h.01"/></svg>
20
24
  <span class="badge" id="panel-environments-offline-count" data-testid="panel-environments-offline-count" hidden></span>
@@ -7,6 +7,14 @@
7
7
  * action a drop or the Move menu chose. It implements no dispatch rule.
8
8
  */
9
9
 
10
+ import {
11
+ assigneeOptions,
12
+ filterSummary,
13
+ loadAssigneeFilter,
14
+ matchesAssignees,
15
+ saveAssigneeFilter,
16
+ toggleAssignee,
17
+ } from './assignee-filter.js';
10
18
  import {
11
19
  buildBoard,
12
20
  dropZones,
@@ -43,6 +51,8 @@ const ui = {
43
51
  offline: 0,
44
52
  prefs: { ...DEFAULT_PREFERENCES },
45
53
  timer: null,
54
+ assignees: [],
55
+ filterKey: null,
46
56
  };
47
57
 
48
58
  /** Browser storage, or `null` where reading it throws. */
@@ -355,6 +365,20 @@ function bindDetailTriggers(node, id) {
355
365
  });
356
366
  }
357
367
 
368
+ /** The card's Epic line, linked when its issue URL is known; none without one. */
369
+ function epicLine(card) {
370
+ if (!card.epic) return [];
371
+ const testId = `card-epic-${card.id}`;
372
+ const text = card.epic.url
373
+ ? link(card.epic.url, card.epic.text, testId)
374
+ : card.epic.text;
375
+ const attrs = {
376
+ class: 'card-epic',
377
+ 'data-testid': card.epic.url ? null : testId,
378
+ };
379
+ return [el('p', attrs, text)];
380
+ }
381
+
358
382
  function cardElement(card) {
359
383
  const story = storyById(card.id);
360
384
  const node = el('article', {
@@ -392,6 +416,7 @@ function cardElement(card) {
392
416
  node.append(
393
417
  el('div', { class: 'card-id' }, `#${card.id}`),
394
418
  el('p', { class: 'card-title' }, card.title),
419
+ ...epicLine(card),
395
420
  ...(card.status ? [statusRow(card)] : []),
396
421
  cardMeta(card),
397
422
  el('div', { class: 'card-actions' }, move, details),
@@ -425,8 +450,48 @@ function laneElement(lane) {
425
450
  return node;
426
451
  }
427
452
 
453
+ function setAssignees(selected) {
454
+ ui.assignees = selected;
455
+ saveAssigneeFilter(storage, selected);
456
+ render();
457
+ }
458
+
459
+ function assigneeOption(option) {
460
+ const box = el('input', {
461
+ type: 'checkbox',
462
+ value: option.value,
463
+ 'data-testid': `assignee-option-${option.value}`,
464
+ });
465
+ box.checked = option.checked;
466
+ box.addEventListener('change', () =>
467
+ setAssignees(toggleAssignee(ui.assignees, option.value, box.checked)),
468
+ );
469
+ return el('label', {}, box, option.text);
470
+ }
471
+
472
+ /** The filter's menu, rebuilt only when its choices or selection change. */
473
+ function renderFilter() {
474
+ const options = assigneeOptions(ui.state.stories, ui.assignees);
475
+ $('assignee-filter-summary').textContent = filterSummary(ui.assignees);
476
+ $('assignee-filter').classList.toggle('active', ui.assignees.length > 0);
477
+ const key = JSON.stringify(options);
478
+ if (key === ui.filterKey) return;
479
+ ui.filterKey = key;
480
+ const everyone = button(
481
+ { 'data-testid': 'assignee-filter-everyone' },
482
+ 'Everyone',
483
+ () => setAssignees([]),
484
+ );
485
+ $('assignee-filter-menu').replaceChildren(
486
+ everyone,
487
+ ...options.map(assigneeOption),
488
+ );
489
+ }
490
+
428
491
  function renderBoard() {
429
- const board = buildBoard(ui.state, ui.connections);
492
+ const board = buildBoard(ui.state, ui.connections, Date.now(), (story) =>
493
+ matchesAssignees(story, ui.assignees),
494
+ );
430
495
  for (const column of board.columns) {
431
496
  const section = document.querySelector(
432
497
  `[data-testid="column-${column.id}"]`,
@@ -558,6 +623,7 @@ function render() {
558
623
  if (ui.state) {
559
624
  $('repository').textContent = ui.state.repository ?? '';
560
625
  $('done-count').textContent = doneHeader(ui.state);
626
+ renderFilter();
561
627
  renderBoard();
562
628
  }
563
629
  renderHeader(ui.offline);
@@ -608,14 +674,26 @@ function bindZone(node) {
608
674
  });
609
675
  }
610
676
 
677
+ /** What the page says for each state-read failure code the server sends. */
678
+ const STATE_ERRORS = {
679
+ 'no-github-repo':
680
+ 'No GitHub repository is configured here. Start mandrel ui from the project root.',
681
+ 'config-invalid':
682
+ 'The project configuration could not be read. See the mandrel ui terminal.',
683
+ };
684
+
611
685
  async function refresh() {
612
686
  try {
613
687
  const { status, json } = await api(`/api/state?done=${ui.prefs.doneLimit}`);
614
- if (status !== 200) throw new Error(json.error);
688
+ if (status !== 200) throw new Error(json?.error);
615
689
  ui.state = json;
616
690
  render();
617
- } catch {
618
- toast('Could not read the board state.', true);
691
+ } catch (err) {
692
+ toast(
693
+ STATE_ERRORS[err.message] ??
694
+ 'Could not read the board state. See the mandrel ui terminal for the cause.',
695
+ true,
696
+ );
619
697
  }
620
698
  await refreshDetail();
621
699
  }
@@ -670,6 +748,7 @@ function wire() {
670
748
  }
671
749
 
672
750
  ui.prefs = loadPreferences(storage);
751
+ ui.assignees = loadAssigneeFilter(storage);
673
752
  applyPreferences();
674
753
  wire();
675
754
  refresh();
@@ -4,7 +4,9 @@
4
4
  * state read is recomputed through `sources.readState` (reused for at most
5
5
  * `cacheMs` to coalesce polls), and an action runs through
6
6
  * `sources.runAction`. Every response carries the security headers; every
7
- * error body is `{ "error": "<code>" }`.
7
+ * error body is `{ "error": "<code>" }`. A failed state read answers 503
8
+ * with the source's safe code and logs its cause to the operator's
9
+ * terminal, never to the page.
8
10
  *
9
11
  * @module cli/ui/server
10
12
  */
@@ -42,6 +44,7 @@ const STATIC_FILES = Object.freeze({
42
44
  '/board-model.js': 'text/javascript; charset=utf-8',
43
45
  '/panel-model.js': 'text/javascript; charset=utf-8',
44
46
  '/preferences.js': 'text/javascript; charset=utf-8',
47
+ '/assignee-filter.js': 'text/javascript; charset=utf-8',
45
48
  '/board.css': 'text/css; charset=utf-8',
46
49
  });
47
50
 
@@ -50,6 +53,13 @@ const TOKEN_PLACEHOLDER = '__MANDREL_TOKEN__';
50
53
  /** HTTP status for a dispatch exit code: success, refusal, failure. */
51
54
  const ACTION_STATUS = { 0: 200, 2: 409 };
52
55
 
56
+ /** State-read failure codes the page may see; any other is `state-unavailable`. */
57
+ const STATE_CODES = new Set([
58
+ 'config-invalid',
59
+ 'no-github-repo',
60
+ 'state-unavailable',
61
+ ]);
62
+
53
63
  function send(res, status, contentType, body) {
54
64
  res.writeHead(status, { ...SECURITY_HEADERS, 'Content-Type': contentType });
55
65
  res.end(body);
@@ -102,6 +112,7 @@ async function readJsonBody(req) {
102
112
  * },
103
113
  * cacheMs?: number,
104
114
  * now?: () => number,
115
+ * log?: (s: string) => void,
105
116
  * uiDir?: string,
106
117
  * }} options
107
118
  * @returns {import('node:http').Server} Not yet listening.
@@ -111,6 +122,7 @@ export function createUiServer({
111
122
  sources,
112
123
  cacheMs = 5000,
113
124
  now = Date.now,
125
+ log = process.stderr.write.bind(process.stderr),
114
126
  uiDir = UI_DIR,
115
127
  }) {
116
128
  /** One cached read per Done limit. */
@@ -123,7 +135,14 @@ export function createUiServer({
123
135
  function readState(doneLimit) {
124
136
  const hit = cached.get(doneLimit);
125
137
  if (isFresh(hit)) return hit.promise;
126
- const entry = { at: now(), promise: sources.readState(doneLimit) };
138
+ const promise = sources.readState(doneLimit).catch((err) => {
139
+ log(
140
+ `mandrel ui: board state read failed: ${err?.detail ?? err?.message}\n`,
141
+ );
142
+ const code = STATE_CODES.has(err?.code) ? err.code : 'state-unavailable';
143
+ throw new RequestError(503, code);
144
+ });
145
+ const entry = { at: now(), promise };
127
146
  cached.set(doneLimit, entry);
128
147
  entry.promise.catch(() => evict(doneLimit, entry));
129
148
  return entry.promise;
@@ -24,6 +24,26 @@ import { runGithubToken } from '../doctor-checks/toolchain.js';
24
24
  import { createAccountProbe } from './accounts.js';
25
25
  import { readStoryDetail, stageOf } from './story-detail.js';
26
26
 
27
+ /**
28
+ * A state read that failed, with a code safe to send to the page (`code`)
29
+ * and the cause for the operator's terminal only (`detail`).
30
+ */
31
+ class StateError extends Error {
32
+ constructor(code, detail = code) {
33
+ super(detail);
34
+ this.code = code;
35
+ this.detail = detail;
36
+ }
37
+ }
38
+
39
+ /** The error for a `dispatch --status` run that exited non-zero. */
40
+ function statusFailure(code, envelope) {
41
+ return new StateError(
42
+ 'state-unavailable',
43
+ envelope?.error ?? `dispatch --status exited ${code}`,
44
+ );
45
+ }
46
+
27
47
  /** Columns whose Stories are in flight and may carry a published stage. */
28
48
  const IN_FLIGHT = new Set(['delivering', 'blocked']);
29
49
 
@@ -109,8 +129,35 @@ export function createSources({
109
129
  return { code, envelope: JSON.parse(out) };
110
130
  }
111
131
 
132
+ /**
133
+ * Why this directory cannot back a board, or `null` when it can: the
134
+ * board reads one GitHub repository, named by `github.owner`/`repo`.
135
+ *
136
+ * @returns {{ code: string, detail: string }|null}
137
+ */
138
+ function projectProblem() {
139
+ let resolved;
140
+ try {
141
+ resolved = config();
142
+ } catch (err) {
143
+ return { code: 'config-invalid', detail: err.message };
144
+ }
145
+ const { owner, repo } = resolved?.github ?? {};
146
+ if (owner && repo) return null;
147
+ return {
148
+ code: 'no-github-repo',
149
+ detail: `no GitHub repository configured in ${cwd}: run mandrel ui from a project root whose .agentrc.json sets github.owner and github.repo`,
150
+ };
151
+ }
152
+
153
+ function assertProject() {
154
+ const problem = projectProblem();
155
+ if (problem) throw new StateError(problem.code, problem.detail);
156
+ }
157
+
112
158
  /** @param {number} [doneLimit] One of `dispatch --done-limit`'s values. */
113
159
  async function readState(doneLimit = DEFAULT_DONE_LIMIT) {
160
+ assertProject();
114
161
  const resolved = config();
115
162
  const provider = createProviderImpl(resolved);
116
163
  const { code, envelope } = await invoke(
@@ -118,7 +165,7 @@ export function createSources({
118
165
  provider,
119
166
  resolved,
120
167
  );
121
- if (code !== 0) throw new Error('state-unavailable');
168
+ if (code !== 0) throw statusFailure(code, envelope);
122
169
  const stories = await Promise.all(
123
170
  envelope.stories.map((story) =>
124
171
  IN_FLIGHT.has(story.column)
@@ -126,9 +173,8 @@ export function createSources({
126
173
  : story,
127
174
  ),
128
175
  );
129
- const { owner, repo } = resolved?.github ?? {};
130
- const repository = owner && repo ? `${owner}/${repo}` : null;
131
- return { ...envelope, repository, stories };
176
+ const { owner, repo } = resolved.github;
177
+ return { ...envelope, repository: `${owner}/${repo}`, stories };
132
178
  }
133
179
 
134
180
  /** The detail for a Story on `state`'s board, or `null` when it is not there. */
@@ -193,6 +239,7 @@ export function createSources({
193
239
  }
194
240
 
195
241
  return {
242
+ projectProblem,
196
243
  readState,
197
244
  readStory,
198
245
  runAction,
@@ -200,3 +247,12 @@ export function createSources({
200
247
  environmentNames: () => resolveEnvironments(config()).map((e) => e.name),
201
248
  };
202
249
  }
250
+
251
+ /** The board's sources, or `null` after saying why this project cannot back one. */
252
+ export function projectSources(sources = createSources(), errOut, exit) {
253
+ const problem = sources.projectProblem();
254
+ if (!problem) return sources;
255
+ errOut(`mandrel ui: ${problem.detail}\n`);
256
+ exit(1);
257
+ return null;
258
+ }
@@ -58,6 +58,13 @@ function resumeCommandOf(record) {
58
58
  return sessionId ? `claude --resume ${sessionId}` : null;
59
59
  }
60
60
 
61
+ /** The row's labels, assignees and Epic, as the detail metadata shows them. */
62
+ const ticketMeta = (row) => ({
63
+ labels: row.labels ?? [],
64
+ assignees: row.assignees ?? [],
65
+ epic: row.epic ?? null,
66
+ });
67
+
61
68
  /**
62
69
  * @param {{ row: object, record: object|null, liveness: object,
63
70
  * provider: object, config: object, repository: string|null }} parts
@@ -77,7 +84,7 @@ export async function readStoryDetail({
77
84
  title: row.title ?? '',
78
85
  column: row.column,
79
86
  environment: row.environment ?? null,
80
- labels: row.labels ?? [],
87
+ ...ticketMeta(row),
81
88
  issueUrl: repository
82
89
  ? `https://github.com/${repository}/issues/${row.id}`
83
90
  : null,
package/lib/cli/ui.js CHANGED
@@ -1,7 +1,8 @@
1
1
  // lib/cli/ui.js
2
2
  /**
3
3
  * `mandrel ui` subcommand: start the local dispatch board on 127.0.0.1,
4
- * print its URL, and run until interrupted. The server stores nothing; a
4
+ * print its URL, and run until interrupted. It refuses to start where no
5
+ * GitHub repository is configured, since every board read needs one. The server stores nothing; a
5
6
  * random per-process token, embedded in the served page, guards the API.
6
7
  *
7
8
  * Usage:
@@ -15,7 +16,7 @@
15
16
  import { randomBytes } from 'node:crypto';
16
17
 
17
18
  import { createUiServer } from './ui/server.js';
18
- import { createSources } from './ui/sources.js';
19
+ import { projectSources } from './ui/sources.js';
19
20
 
20
21
  export const DEFAULT_PORT = 4319;
21
22
 
@@ -57,7 +58,7 @@ function parsePort(value) {
57
58
  * errOut?: (s: string) => void,
58
59
  * exit?: (code: number) => void,
59
60
  * token?: string,
60
- * sources?: ReturnType<typeof createSources>,
61
+ * sources?: ReturnType<typeof import('./ui/sources.js').createSources>,
61
62
  * createServer?: typeof createUiServer,
62
63
  * }} [deps]
63
64
  * @returns {Promise<import('node:http').Server|null>} The listening server.
@@ -85,17 +86,26 @@ export async function runUi(
85
86
  write(UI_USAGE);
86
87
  return null;
87
88
  }
88
- const server = createServer({
89
- token,
90
- sources: sources ?? createSources(),
91
- });
89
+ const io = { write, errOut, exit };
90
+ return serveBoard(args.port, { sources, token, createServer }, io);
91
+ }
92
+
93
+ /** Start the board where this project can back one; `null` after saying why not. */
94
+ function serveBoard(port, { sources, token, createServer }, io) {
95
+ const boardSources = projectSources(sources, io.errOut, io.exit);
96
+ if (!boardSources) return null;
97
+ return listenOn(createServer({ token, sources: boardSources }), port, io);
98
+ }
99
+
100
+ /** Listen on 127.0.0.1 and print the URL; resolves `null` when the port is taken. */
101
+ function listenOn(server, port, { write, errOut, exit }) {
92
102
  return new Promise((resolve) => {
93
103
  server.once('error', (err) => {
94
- errOut(`mandrel ui: cannot listen on port ${args.port}: ${err.code}\n`);
104
+ errOut(`mandrel ui: cannot listen on port ${port}: ${err.code}\n`);
95
105
  exit(1);
96
106
  resolve(null);
97
107
  });
98
- server.listen(args.port, '127.0.0.1', () => {
108
+ server.listen(port, '127.0.0.1', () => {
99
109
  write(`mandrel ui: http://127.0.0.1:${server.address().port}/\n`);
100
110
  resolve(server);
101
111
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mandrel",
3
- "version": "2.125.0",
3
+ "version": "2.126.0",
4
4
  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
5
5
  "files": [
6
6
  ".agents/",