dsh-project-mcp 0.2.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.
@@ -0,0 +1,399 @@
1
+ /**
2
+ * The pictures the design surfaces draw.
3
+ *
4
+ * `./design.ts` mounts the three browser surfaces with **no host half at all**:
5
+ * nothing is mounted, no route is called, and the sidebar tab, its settings
6
+ * popover and the settings page are rendered from the fixtures below. That keeps
7
+ * the interface reviewable on a machine with no live project and no MCP server,
8
+ * which is the whole point of the mode.
9
+ *
10
+ * Every field here is the shape the host really publishes (`src/types.ts`), and
11
+ * the `full` picture is the same one the parity gate feeds the live panel
12
+ * (`scripts/design-parity.mjs`): seven servers covering all four status tones, a
13
+ * session that disagrees with its project, a failure with its detail, four
14
+ * events in the ring and a tool offer with pinned, disclosed and hidden names.
15
+ * The other pictures isolate one state each, so a designer can look at it alone.
16
+ *
17
+ * @module dsh-project-mcp/client/design-fixtures
18
+ */
19
+
20
+ import type {
21
+ LogEvent,
22
+ McpSnapshot,
23
+ ProjectSnapshot,
24
+ ServerRow,
25
+ ServerStatus,
26
+ ServerUsage,
27
+ SessionSnapshot,
28
+ SessionTools,
29
+ ToolPolicy,
30
+ } from '../types.ts'
31
+ import type { ToastDraft } from './toasts.ts'
32
+ import { STATUS_HINT } from './view.ts'
33
+
34
+ /** Session the fixtures belong to; `shortSessionId` renders it as `8fce1c`. */
35
+ export const DESIGN_SESSION = 'session-8fce1c-4a3f-4d0b-9c11-2f6a7b8c9d10'
36
+
37
+ /** Neutral placeholder project, as the repository's conventions require. */
38
+ export const DESIGN_PROJECT_ROOT = '/example/service'
39
+
40
+ /** The declaring document of every fixture row. */
41
+ export const DESIGN_DOCUMENT = `${DESIGN_PROJECT_ROOT}/.dsh/mcp.json`
42
+
43
+ /** The detail a failed mount carries: three facts, no advice (`F-03`). */
44
+ export const DESIGN_FAILURE =
45
+ `no tool appeared within 60.2s; endpoint stdio docker; declared in ${DESIGN_DOCUMENT}`
46
+
47
+ /** How long the quiet fixture server has been unused, as the stand shows it. */
48
+ const DESIGN_IDLE_MS = 3 * 24 * 60 * 60 * 1000
49
+
50
+ /**
51
+ * The host's usage counters for the picture (`ProjectSnapshot.usage`).
52
+ *
53
+ * The three states the panel can draw are all here, because a stand that shows
54
+ * only the happy one hides the rule that matters: `tglider` has counts for both
55
+ * its tools, `grafana-local` has a record whose `tools` came back empty — the
56
+ * row prints `never called` rather than a zero nobody counted — and every other
57
+ * server has no record at all, so its rows carry no figure. `graph` is quiet
58
+ * with a three-day-old date, which is the one row that draws `idle 3d`; the
59
+ * figure is computed at module load so the stand always shows the same reading.
60
+ *
61
+ * The split is the other half of the rule (F-34): this session called
62
+ * `workspace` 3 times while the project counted 182, so the row shows both, and
63
+ * it never called `catalog`, so that row reads `never called · 96 in the
64
+ * project`. A project whose host publishes no split draws one number, which is
65
+ * what the other pictures show.
66
+ */
67
+ export const DESIGN_USAGE: Record<string, ServerUsage> = {
68
+ tglider: {
69
+ calls: 182,
70
+ errors: 0,
71
+ lastUsedAt: new Date(Date.now() - DESIGN_IDLE_MS / 3).toISOString(),
72
+ tools: { workspace: 182, catalog: 96 },
73
+ sessions: {
74
+ [DESIGN_SESSION]: {
75
+ calls: 3,
76
+ errors: 0,
77
+ lastUsedAt: new Date(Date.now() - DESIGN_IDLE_MS / 3).toISOString(),
78
+ tools: { workspace: 3 },
79
+ },
80
+ },
81
+ },
82
+ 'grafana-local': {
83
+ calls: 0,
84
+ errors: 0,
85
+ lastUsedAt: new Date(Date.now() - DESIGN_IDLE_MS).toISOString(),
86
+ tools: {},
87
+ },
88
+ context7: {
89
+ calls: 12,
90
+ errors: 1,
91
+ lastUsedAt: new Date(Date.now() - DESIGN_IDLE_MS * 2).toISOString(),
92
+ tools: { docs: 12 },
93
+ },
94
+ }
95
+
96
+ /** One lifecycle event, as the ring stores it. */
97
+ function event(
98
+ at: number,
99
+ level: LogEvent['level'],
100
+ server: string,
101
+ message: string,
102
+ detail?: string,
103
+ ): LogEvent {
104
+ return detail === undefined
105
+ ? { at, level, projectRoot: DESIGN_PROJECT_ROOT, sessionId: DESIGN_SESSION, server, message }
106
+ : { at, level, projectRoot: DESIGN_PROJECT_ROOT, sessionId: DESIGN_SESSION, server, message, detail }
107
+ }
108
+
109
+ /** The four events the `full` picture holds, oldest first. */
110
+ export const DESIGN_EVENTS: readonly LogEvent[] = [
111
+ event(1_789_000_000_000, 'info', 'tglider', `mounting for session ${DESIGN_SESSION} (trigger: turn)`),
112
+ event(1_789_000_001_000, 'up', 'tglider', `is up — tools visible to session ${DESIGN_SESSION} after 812ms`),
113
+ event(1_789_000_002_000, 'warn', 'grafana-local', 'unmounting — the session went idle (it ran for 8m 03s)'),
114
+ event(1_789_000_003_000, 'error', 'gateway', 'no tool appeared in 4m 27s', `endpoint: stdio docker · declared in ${DESIGN_DOCUMENT}`),
115
+ ]
116
+
117
+ /** The one event the `tools-absent` picture holds: a declaration waiting for a turn. */
118
+ export const DESIGN_PENDING_EVENT: readonly LogEvent[] = [
119
+ event(1_789_000_030_000, 'info', 'tglider', 'declared, waiting for the session’s first step'),
120
+ ]
121
+
122
+ /** One row of a picture. */
123
+ function row(
124
+ name: string,
125
+ status: ServerStatus,
126
+ transport: 'stdio' | 'streamable-http',
127
+ detail?: string,
128
+ ): ServerRow {
129
+ return detail === undefined
130
+ ? { name, status, projectRoot: DESIGN_PROJECT_ROOT, source: DESIGN_DOCUMENT, transport }
131
+ : { name, status, projectRoot: DESIGN_PROJECT_ROOT, source: DESIGN_DOCUMENT, transport, detail }
132
+ }
133
+
134
+ /**
135
+ * Every picture the design mode can draw.
136
+ *
137
+ * `full` is the default and the one the docs' own mock (`mockups/harness.html`)
138
+ * mirrors; the rest isolate a single state so it can be reviewed on its own.
139
+ */
140
+ export type DesignVariant =
141
+ /** All states at once: four tones, a disagreement, a failure, a full tool offer. */
142
+ | 'full'
143
+ /** The quiet project: sessions agree, nothing failed, the ring is empty. */
144
+ | 'quiet'
145
+ /** The project declares nothing. */
146
+ | 'empty'
147
+ /** The session declares one server and the host published no offer yet. */
148
+ | 'tools-absent'
149
+ /** The tools page is switched off for this project. */
150
+ | 'off'
151
+ /** Nothing is deferred: every mounted tool goes into the request. */
152
+ | 'direct'
153
+ /** The session's folder is not inside a project. */
154
+ | 'no-project'
155
+ /** No session is attached to the tab. */
156
+ | 'no-session'
157
+
158
+ /** The variants, in the order the docs present them. */
159
+ export const DESIGN_VARIANTS: readonly DesignVariant[] = [
160
+ 'full',
161
+ 'quiet',
162
+ 'empty',
163
+ 'tools-absent',
164
+ 'off',
165
+ 'direct',
166
+ 'no-project',
167
+ 'no-session',
168
+ ]
169
+
170
+ /** Narrow `unknown` to a variant, so a stored string can never switch the mode blind. */
171
+ export function isDesignVariant(value: unknown): value is DesignVariant {
172
+ return typeof value === 'string' && (DESIGN_VARIANTS as readonly string[]).includes(value)
173
+ }
174
+
175
+ /** The merged rows of the project, per picture. */
176
+ function mergedRows(variant: DesignVariant): ServerRow[] {
177
+ switch (variant) {
178
+ case 'full':
179
+ return [
180
+ row('tglider', 'active', 'streamable-http'),
181
+ row('grafana-local', 'active', 'streamable-http'),
182
+ row('gateway', 'error', 'stdio', DESIGN_FAILURE),
183
+ row('playwright', 'connecting', 'stdio'),
184
+ row('context7', 'conflict', 'streamable-http', 'the name is taken by a live profile-level instance'),
185
+ row('rider', 'idle', 'stdio', 'not mounted yet — this session has not started a turn (lazy mounting is on)'),
186
+ row('legacy-gh', 'disabled', 'stdio'),
187
+ ]
188
+ case 'quiet':
189
+ case 'off':
190
+ return [row('tglider', 'active', 'streamable-http'), row('grafana-local', 'active', 'streamable-http')]
191
+ case 'direct':
192
+ return [row('tglider', 'active', 'streamable-http')]
193
+ case 'tools-absent':
194
+ return [row('tglider', 'idle', 'streamable-http', 'not mounted yet — this session has not started a turn (lazy mounting is on)')]
195
+ case 'empty':
196
+ case 'no-project':
197
+ case 'no-session':
198
+ return []
199
+ }
200
+ }
201
+
202
+ /**
203
+ * This session's own rows.
204
+ *
205
+ * The `full` picture is the one the panel's project-first view exists for: the
206
+ * project merges `grafana-local` as `active`, while this session — whose ring
207
+ * says it went idle — reads it as `idle`. Every other picture agrees with its
208
+ * project, so the panel draws no `sessions` section at all.
209
+ */
210
+ function sessionOwnRows(variant: DesignVariant): ServerRow[] {
211
+ const rows = mergedRows(variant)
212
+ if (variant !== 'full') return rows
213
+ return rows.map((entry) =>
214
+ entry.name === 'grafana-local' ? { ...entry, status: 'idle' as const } : entry,
215
+ )
216
+ }
217
+
218
+ /** The tool policy in force for the picture. */
219
+ export function designPolicy(variant: DesignVariant): ToolPolicy {
220
+ switch (variant) {
221
+ case 'off':
222
+ return { mode: 'off', pins: [] }
223
+ case 'direct':
224
+ return { mode: 'direct', pins: ['mcp__tglider__workspace'] }
225
+ case 'quiet':
226
+ return { mode: 'disclosure', pins: ['mcp__tglider__workspace', 'mcp__grafana-local__query'] }
227
+ default:
228
+ return { mode: 'disclosure', pins: ['mcp__tglider__workspace'] }
229
+ }
230
+ }
231
+
232
+ /**
233
+ * One session's tool offer, or `undefined` for the pictures where the host has
234
+ * published none.
235
+ *
236
+ * `undefined` is the host's only "not mounted yet" signal, and it is a different
237
+ * state from an offer whose counters are real zeroes — the panel prints two
238
+ * different blocks for the two.
239
+ */
240
+ export function designTools(variant: DesignVariant): SessionTools | undefined {
241
+ const base = { sessionId: DESIGN_SESSION, mounted: 5, budgetChars: 20_000, deferring: false }
242
+ switch (variant) {
243
+ case 'full':
244
+ return {
245
+ ...base,
246
+ baseline: ['mcp__tglider__workspace', 'mcp__tglider__catalog'],
247
+ activated: [{ name: 'mcp__grafana-local__query', via: 'session', at: 1_789_000_004_000, step: 3 }],
248
+ context: [{ name: 'mcp__context7__docs', via: 'context' }],
249
+ deferred: ['mcp__playwright__navigate', 'mcp__rider__open'],
250
+ surfaceChars: 12_800,
251
+ visibleChars: 4_200,
252
+ deferredChars: 8_600,
253
+ deferring: true,
254
+ }
255
+ case 'quiet':
256
+ return {
257
+ ...base,
258
+ mounted: 2,
259
+ baseline: ['mcp__tglider__workspace', 'mcp__grafana-local__query'],
260
+ activated: [],
261
+ context: [],
262
+ deferred: [],
263
+ surfaceChars: 6_400,
264
+ visibleChars: 6_400,
265
+ deferredChars: 0,
266
+ }
267
+ case 'off':
268
+ return {
269
+ ...base,
270
+ mounted: 1,
271
+ baseline: [],
272
+ activated: [],
273
+ context: [],
274
+ deferred: ['mcp__tglider__workspace'],
275
+ surfaceChars: 3_200,
276
+ visibleChars: 0,
277
+ deferredChars: 3_200,
278
+ }
279
+ case 'direct':
280
+ return {
281
+ ...base,
282
+ mounted: 1,
283
+ baseline: ['mcp__tglider__workspace'],
284
+ activated: [],
285
+ context: [],
286
+ deferred: [],
287
+ surfaceChars: 3_200,
288
+ visibleChars: 3_200,
289
+ deferredChars: 0,
290
+ }
291
+ case 'empty':
292
+ case 'tools-absent':
293
+ case 'no-project':
294
+ case 'no-session':
295
+ return undefined
296
+ }
297
+ }
298
+
299
+ /** One session of the picture, or `undefined` when the picture has no session. */
300
+ function sessionOf(variant: DesignVariant): SessionSnapshot[] {
301
+ if (variant === 'no-project' || variant === 'no-session') return []
302
+ const rows = sessionOwnRows(variant)
303
+ const tools = designTools(variant)
304
+ const logs = variant === 'full' ? DESIGN_EVENTS : variant === 'tools-absent' ? DESIGN_PENDING_EVENT : []
305
+ const session: SessionSnapshot = {
306
+ id: DESIGN_SESSION,
307
+ rows,
308
+ issues: [],
309
+ logCount: logs.length,
310
+ ...(tools === undefined ? {} : { tools }),
311
+ }
312
+ return [session]
313
+ }
314
+
315
+ /**
316
+ * The one project of the picture, or `undefined` for the two that resolve to
317
+ * none — a folder that is not inside a project, and a tab with no session at
318
+ * all (the panel reads the project of the session it is open in, so neither
319
+ * resolves).
320
+ */
321
+ export function designProject(variant: DesignVariant): ProjectSnapshot | undefined {
322
+ if (variant === 'no-project' || variant === 'no-session') return undefined
323
+ const rows = mergedRows(variant)
324
+ const logs = variant === 'full' ? DESIGN_EVENTS : variant === 'tools-absent' ? DESIGN_PENDING_EVENT : []
325
+ const sessions = sessionOf(variant)
326
+ return {
327
+ projectRoot: DESIGN_PROJECT_ROOT,
328
+ policy: designPolicy(variant),
329
+ sessionIds: [DESIGN_SESSION],
330
+ // The read order of this deployment, as the host publishes it: the fixture
331
+ // project is declared in the DSH document, and no global document is read.
332
+ files: [{ path: DESIGN_DOCUMENT, scope: 'project' }],
333
+ rows,
334
+ issues: [],
335
+ sessions,
336
+ conflicts: [],
337
+ ...(logs.length === 0 ? {} : { logs, logCount: logs.length }),
338
+ // The counters belong to the two pictures that publish a tool offer: a
339
+ // project the host never counted (every other picture) draws no figures at
340
+ // all, which is a state worth being able to look at.
341
+ ...(variant === 'full' || variant === 'quiet' ? { usage: DESIGN_USAGE } : {}),
342
+ }
343
+ }
344
+
345
+ /** The whole picture, in the envelope's own shape. */
346
+ export function designPicture(variant: DesignVariant): McpSnapshot {
347
+ const project = designProject(variant)
348
+ return {
349
+ ready: true,
350
+ projects: project === undefined ? [] : [project],
351
+ sources: { local: ['.dsh/mcp.json'], global: [] },
352
+ watchedFiles: project === undefined ? [] : [DESIGN_DOCUMENT],
353
+ }
354
+ }
355
+
356
+ /**
357
+ * The session id the tab should read for this picture.
358
+ *
359
+ * `no-session` is the state the shell itself can be in — a tab with no session
360
+ * attached — and the one the panel answers with its own empty state.
361
+ * @param variant - the picture on screen.
362
+ * @returns the fixture session id, or `undefined` for `no-session`.
363
+ */
364
+ export function designSessionId(variant: DesignVariant): string | undefined {
365
+ return variant === 'no-session' ? undefined : DESIGN_SESSION
366
+ }
367
+
368
+ /**
369
+ * The banners the design toast stack shows, one per lifecycle moment. Keyed
370
+ * like the real drafts (`src/client/toasts.ts`), so the stand repaints its
371
+ * banners in the shell's active language the same way the product does.
372
+ */
373
+ export const DESIGN_TOASTS: readonly ToastDraft[] = [
374
+ {
375
+ level: 'up',
376
+ server: 'playwright',
377
+ project: 'service',
378
+ textKey: 'toastUp',
379
+ textParams: { server: 'playwright' },
380
+ detail: 'service',
381
+ },
382
+ {
383
+ level: 'error',
384
+ server: 'gateway',
385
+ project: 'service',
386
+ textKey: 'toastFailed',
387
+ textParams: { server: 'gateway' },
388
+ detailKey: STATUS_HINT.error,
389
+ detail: DESIGN_FAILURE,
390
+ },
391
+ {
392
+ level: 'released',
393
+ server: 'rider',
394
+ project: 'service',
395
+ textKey: 'toastReleased',
396
+ textParams: { server: 'rider' },
397
+ detailKey: STATUS_HINT.idle,
398
+ },
399
+ ]