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.
package/src/logs.ts ADDED
@@ -0,0 +1,184 @@
1
+ /**
2
+ * The plugin's own event ring, and its only owner.
3
+ *
4
+ * The Logs tab of the sidebar panel answers "what happened to this project's
5
+ * servers" from the plugin's own lifecycle events — mounting, `is up`, stall,
6
+ * unmount, failure — and from nothing else. The DSH log is deliberately not a
7
+ * source: no foreign line can be attributed to one project, and attribution is
8
+ * exactly what the tab promises (contract C1, decision 2 of the review).
9
+ *
10
+ * The ring is per project root and bounded by {@link LOG_RING_LIMIT}, the oldest
11
+ * event evicted first. It is written from the single runtime point that already
12
+ * writes the matching lifecycle line to the DSH log, so both readers see the
13
+ * same facts and there is no second write path to keep in sync. The newest
14
+ * {@link LOG_PAGE_SIZE} events travel inside the snapshot the tab is drawn from;
15
+ * {@link page} is what "show older" asks for the rest.
16
+ *
17
+ * Nothing here touches the disk, and the clock belongs to the caller. A module
18
+ * map rather than runtime state on purpose: the route handler ({@link module:dsh-project-mcp/ui})
19
+ * answers `GET logs` without a runtime, and the panel and the runtime must read
20
+ * one buffer. {@link record} never throws — a ring write must not fail the pass
21
+ * that reported the event.
22
+ *
23
+ * @module dsh-project-mcp/logs
24
+ */
25
+
26
+ import type { LogEvent } from './types.ts'
27
+
28
+ /** Events one project's ring holds; the oldest is evicted past it. */
29
+ export const LOG_RING_LIMIT = 200
30
+
31
+ /** Events one page carries: the snapshot's tail, and {@link page}'s default window. */
32
+ export const LOG_PAGE_SIZE = 50
33
+
34
+ /**
35
+ * One ring per project root, oldest event first.
36
+ *
37
+ * Kept per root because two projects of one host are two histories; the history
38
+ * lives exactly as long as the process, since the panel's `Clear` is client-side
39
+ * and there is no `Clear` route (contract C1).
40
+ */
41
+ const rings = new Map<string, LogEvent[]>()
42
+
43
+ /**
44
+ * Add one event to its project's ring.
45
+ *
46
+ * Called from the runtime points that write the lifecycle line to the DSH log,
47
+ * in addition to it. An event identical to one already held is dropped, so a
48
+ * repeated pass can never make the tab show the same line twice. Total: a
49
+ * malformed event or a ring bug is swallowed rather than thrown into the pass
50
+ * that reported it.
51
+ * @param event - the event to record; `message` is folded onto one line.
52
+ */
53
+ export function record(event: LogEvent): void {
54
+ try {
55
+ if (typeof event.projectRoot !== 'string' || event.projectRoot === '') return
56
+ const ring = ringOf(event.projectRoot)
57
+ if (ring.some((existing) => sameEvent(existing, event))) return
58
+ ring.push({ ...event, message: oneLine(event.message) })
59
+ if (ring.length > LOG_RING_LIMIT) ring.splice(0, ring.length - LOG_RING_LIMIT)
60
+ } catch {
61
+ // Nothing a ring write can raise is worth failing the pass for.
62
+ }
63
+ }
64
+
65
+ /**
66
+ * The newest events of one project, oldest first.
67
+ *
68
+ * This is what a snapshot carries, and it hands out a copy: a reader that kept
69
+ * the array could otherwise watch it change under a later pass.
70
+ * @param projectRoot - project whose ring is read.
71
+ * @param limit - how many of the newest events to return; clamped to
72
+ * `1…{@link LOG_RING_LIMIT}`, {@link LOG_PAGE_SIZE} when omitted.
73
+ * @returns the events, oldest first; empty for a project with no history.
74
+ */
75
+ export function latest(projectRoot: string, limit: number = LOG_PAGE_SIZE): LogEvent[] {
76
+ const ring = rings.get(projectRoot)
77
+ if (ring === undefined) return []
78
+ const size = clampLimit(limit)
79
+ return ring.slice(Math.max(0, ring.length - size))
80
+ }
81
+
82
+ /**
83
+ * One page of a project's history, for "show older".
84
+ *
85
+ * Without `before` the page is the newest `limit` events — the same window a
86
+ * snapshot carries, which is what the tab asks for on a refresh. With `before`
87
+ * it is the newest `limit` events strictly older than that instant: the cursor
88
+ * is the `at` of the oldest event already on screen, so consecutive pages do
89
+ * not overlap.
90
+ * @param input - the project to read, and the optional window.
91
+ * @param input.projectRoot - project whose ring is read.
92
+ * @param input.before - exclusive cursor in epoch ms; `at < before` only.
93
+ * @param input.limit - page size; clamped to `1…{@link LOG_RING_LIMIT}`,
94
+ * {@link LOG_PAGE_SIZE} when omitted.
95
+ * @returns the page, the ring's total size, and whether older events remain
96
+ * beyond the page — `more` is true when the window had to cut the history short.
97
+ */
98
+ export function page(input: { projectRoot: string; before?: number; limit?: number }): {
99
+ events: LogEvent[]
100
+ total: number
101
+ more: boolean
102
+ } {
103
+ const ring = rings.get(input.projectRoot) ?? []
104
+ const older = input.before === undefined ? ring : ring.filter((event) => event.at < (input.before as number))
105
+ const events = older.slice(Math.max(0, older.length - clampLimit(input.limit)))
106
+ return { events, total: ring.length, more: older.length > events.length }
107
+ }
108
+
109
+ /**
110
+ * How many events one project's ring holds right now.
111
+ * @param projectRoot - project whose ring is read.
112
+ * @returns the count, `0` for a project with no history.
113
+ */
114
+ export function countOf(projectRoot: string): number {
115
+ return rings.get(projectRoot)?.length ?? 0
116
+ }
117
+
118
+ /**
119
+ * How many events of one project's ring belong to one session.
120
+ *
121
+ * Events the lifecycle line itself attributes to a session — `mounting`, `is up`,
122
+ * a stall — are counted here; a project-level event (a shared instance's unmount)
123
+ * carries no session and is counted by no session.
124
+ * @param projectRoot - project whose ring is read.
125
+ * @param sessionId - agent (session) id to count.
126
+ * @returns the count, `0` for a session that produced nothing.
127
+ */
128
+ export function countForSession(projectRoot: string, sessionId: string): number {
129
+ return (rings.get(projectRoot) ?? []).filter((event) => event.sessionId === sessionId).length
130
+ }
131
+
132
+ /**
133
+ * Drop one project's history, or every project's, for tests.
134
+ *
135
+ * Not a route: the panel's `Clear` is client-side (contract C1), so nothing in
136
+ * the product calls this — a test that asserts on a ring starts from no history.
137
+ * @param projectRoot - project to forget; omitted forgets every project.
138
+ */
139
+ export function clear(projectRoot?: string): void {
140
+ if (projectRoot === undefined) rings.clear()
141
+ else rings.delete(projectRoot)
142
+ }
143
+
144
+ /** The ring of one root, created empty on first use. */
145
+ function ringOf(projectRoot: string): LogEvent[] {
146
+ const existing = rings.get(projectRoot)
147
+ if (existing !== undefined) return existing
148
+ const ring: LogEvent[] = []
149
+ rings.set(projectRoot, ring)
150
+ return ring
151
+ }
152
+
153
+ /**
154
+ * Whether two events are the same event, field by field. The project is the ring
155
+ * they share, so it is the one field not compared here.
156
+ */
157
+ function sameEvent(left: LogEvent, right: LogEvent): boolean {
158
+ return (
159
+ left.at === right.at &&
160
+ left.level === right.level &&
161
+ left.sessionId === right.sessionId &&
162
+ left.server === right.server &&
163
+ left.message === right.message &&
164
+ left.detail === right.detail
165
+ )
166
+ }
167
+
168
+ /**
169
+ * Fold a message onto one line, as {@link LogEvent.message} promises: the tab
170
+ * renders a row per event, and a newline inside one would break the column.
171
+ */
172
+ function oneLine(message: string): string {
173
+ return message.replace(/\s*\n\s*/g, ' ').trim()
174
+ }
175
+
176
+ /**
177
+ * A page size clamped to what the ring can serve: a caller cannot ask for more
178
+ * than {@link LOG_RING_LIMIT} events, and a zero or a negative size is raised to
179
+ * the one event every page is at least worth.
180
+ */
181
+ function clampLimit(limit: number | undefined): number {
182
+ if (limit === undefined || !Number.isFinite(limit)) return LOG_PAGE_SIZE
183
+ return Math.min(LOG_RING_LIMIT, Math.max(1, Math.trunc(limit)))
184
+ }
package/src/naming.ts ADDED
@@ -0,0 +1,134 @@
1
+ /**
2
+ * The local namespace of a project-declared MCP server.
3
+ *
4
+ * A profile-level `mcp-client` instance and a project document can declare the
5
+ * same `serverName`. `dsh-mcp-client` reserves that name per scope, so only one
6
+ * of them can mount — which is a lost server, not a bad declaration. This module
7
+ * is the pure rule that gives the project's entry a second, local name instead
8
+ * (`grafana-dev` → `p-grafana-dev`), so both toolsets stay in the model's hands
9
+ * under names nobody has to guess at.
10
+ *
11
+ * The rule is a total function of the declared name, the prefix and the names
12
+ * already taken, and it is the *only* place the alias is computed: the pass that
13
+ * mounts the server, the row that reports it and the tool prefix the model sees
14
+ * all read this answer, so they cannot drift apart.
15
+ *
16
+ * @module dsh-project-mcp/naming
17
+ */
18
+
19
+ /** The five characters a local prefix may carry, config or derived. */
20
+ export const MAX_LOCAL_PREFIX_LENGTH = 5
21
+
22
+ /** The `serverName` cap `@deepseek-ai/dsh-mcp-client` enforces. */
23
+ const MAX_SERVER_NAME_LENGTH = 32
24
+
25
+ /** A local prefix is a valid `serverName` head or it is nothing. */
26
+ const PREFIX_SHAPE = /^[A-Za-z0-9_-]+$/
27
+
28
+ /**
29
+ * Whether a value may serve as a local prefix.
30
+ *
31
+ * The routes and the loader schema both read an untrusted string, so the shape
32
+ * is checked here rather than trusted: a prefix that carries a character
33
+ * `serverName` does not allow would produce a server the registry rejects, and
34
+ * an empty prefix is a request for the derived one, not an error.
35
+ *
36
+ * @param value - candidate prefix.
37
+ * @returns `true` when it is empty or a valid prefix of at most five characters.
38
+ */
39
+ export function isValidLocalPrefix(value: string): boolean {
40
+ if (value === '') return true
41
+ return value.length <= MAX_LOCAL_PREFIX_LENGTH && PREFIX_SHAPE.test(value)
42
+ }
43
+
44
+ /**
45
+ * The prefix a project brings by itself: its own folder name.
46
+ *
47
+ * Used when the config names no prefix, so a conflict has an answer without a
48
+ * setting. A folder that yields nothing usable — `/`, dots, digits only — has no
49
+ * answer, and such a project keeps today's behaviour rather than a made-up name.
50
+ *
51
+ * @param projectRoot - absolute project root.
52
+ * @returns up to five characters, or `undefined` when the folder yields none.
53
+ */
54
+ export function deriveLocalPrefix(projectRoot: string): string | undefined {
55
+ const folder = projectRoot.split(/[\\/]/).filter((part) => part !== '').pop()
56
+ if (folder === undefined) return undefined
57
+ const cleaned = folder
58
+ .toLowerCase()
59
+ .replace(/[^A-Za-z0-9_-]+/g, '-')
60
+ // A `serverName` may not open with a digit, and neither may the prefix: a
61
+ // folder `2fast-service` contributes `fast`, not `2fast`.
62
+ .replace(/^[0-9]+-*/, '')
63
+ .slice(0, MAX_LOCAL_PREFIX_LENGTH)
64
+ // Trimmed after the cap as well, so a cut at a separator (`2fast-service`
65
+ // capped to five) never leaves the trailing dash the cap exposed.
66
+ .replace(/^-+|-+$/g, '')
67
+ return cleaned || undefined
68
+ }
69
+
70
+ /**
71
+ * The local name of one declaration: the prefix, then the declared name,
72
+ * trimmed so the result fits the `serverName` cap.
73
+ *
74
+ * The declared name is what gets trimmed, never the prefix, because a truncated
75
+ * prefix would collide across servers the user meant to tell apart.
76
+ *
77
+ * @param name - declared `serverName`.
78
+ * @param prefix - local prefix, already known to be valid.
79
+ * @returns a `serverName` of at most 32 characters.
80
+ */
81
+ export function aliasOf(name: string, prefix: string): string {
82
+ const head = `${prefix}-`
83
+ return `${head}${name.slice(0, Math.max(1, MAX_SERVER_NAME_LENGTH - head.length))}`
84
+ }
85
+
86
+ /** One declaration considered for a local name. */
87
+ export interface ConflictNameInput {
88
+ /** Declared `serverName`. */
89
+ readonly name: string
90
+ /** `true` when a live profile-level instance already owns that name. */
91
+ readonly reserved: boolean
92
+ }
93
+
94
+ /** What {@link resolveConflictNames} is asked to name. */
95
+ export interface ResolveNamesInput {
96
+ /** Every declaration of the project, in document order. */
97
+ readonly entries: readonly ConflictNameInput[]
98
+ /** Explicit local prefix; empty asks for the one derived from the project. */
99
+ readonly prefix: string
100
+ /** Project root, read only when `prefix` is empty. */
101
+ readonly projectRoot?: string
102
+ }
103
+
104
+ /**
105
+ * The local name of every declaration a profile-level instance shadows.
106
+ *
107
+ * Aliases are handed out in name order so the answer never depends on which
108
+ * document was read first, and a candidate that is already owned — by another
109
+ * declaration of this project, by the profile, or by an alias handed out a
110
+ * moment ago — gets a numeric tail (`p-grafana-dev-2`) rather than stealing the
111
+ * name. Names that conflict with nothing are absent from the map: the absence is
112
+ * the honest answer "this one mounts under the name it declared".
113
+ *
114
+ * @param input - declarations, prefix and project root.
115
+ * @returns declared name → local name, in name order; empty when nothing is shadowed.
116
+ */
117
+ export function resolveConflictNames(input: ResolveNamesInput): Map<string, string> {
118
+ const prefix = input.prefix !== '' ? input.prefix : deriveLocalPrefix(input.projectRoot ?? '')
119
+ const aliases = new Map<string, string>()
120
+ if (prefix === undefined || !isValidLocalPrefix(prefix) || prefix === '') return aliases
121
+ const taken = new Set(input.entries.map((entry) => entry.name))
122
+ const shadowed = input.entries.filter((entry) => entry.reserved).map((entry) => entry.name)
123
+ // Sorted, so the numeric tail always lands on the same declaration.
124
+ shadowed.sort()
125
+ for (const name of shadowed) {
126
+ let candidate = aliasOf(name, prefix)
127
+ for (let tail = 2; taken.has(candidate); tail += 1) {
128
+ candidate = aliasOf(`${name}-${tail}`, prefix)
129
+ }
130
+ taken.add(candidate)
131
+ aliases.set(name, candidate)
132
+ }
133
+ return aliases
134
+ }
@@ -0,0 +1,254 @@
1
+ /**
2
+ * The plugin's event service: one publication point, and its consumers.
3
+ *
4
+ * A lifecycle fact used to be written three times by the runtime — a line in the
5
+ * DSH log, the same fact into the ring (`src/logs.ts`), and the snapshot
6
+ * announcement the panel watches. Three writes that had to agree. Here they are
7
+ * one: the runtime publishes a {@link PluginEvent} through {@link emitEvent}, and
8
+ * every reader is a subscriber —
9
+ *
10
+ * 1. the ring, subscribed here against {@link module:dsh-project-mcp/logs}
11
+ * `record`, so the tab and the log are fed by one publication;
12
+ * 2. the DSH log, subscribed by the runtime's own
13
+ * {@link module:dsh-project-mcp/runtime} wiring through {@link logConsumer},
14
+ * because only the runtime holds the host `ctx`;
15
+ * 3. anything else a test or a later surface attaches through
16
+ * {@link subscribeEvent}.
17
+ *
18
+ * Publication is synchronous and total: listeners run in subscription order, a
19
+ * listener that throws is swallowed rather than failing the pass that reported
20
+ * the event, and {@link emitEvent} never throws into its caller. The clock
21
+ * belongs to the caller ({@link PluginEvent.at}), as it does in the ring, so a
22
+ * test can pin an event to a moment.
23
+ *
24
+ * @module dsh-project-mcp/notifications
25
+ */
26
+
27
+ import { record } from './logs.ts'
28
+ import type { LogLevel } from './types.ts'
29
+
30
+ /**
31
+ * One lifecycle event, as every consumer reads it.
32
+ *
33
+ * The same fields the ring keeps, because the ring is a subscriber — the tab
34
+ * draws exactly the event this service published. The one field with two
35
+ * readers is {@link PluginEvent.level}: the ring colours the row with it, and
36
+ * the DSH log writes the line through the matching level method.
37
+ */
38
+ export interface PluginEvent {
39
+ /** When the event happened, epoch ms. */
40
+ readonly at: number
41
+ /** How serious it is, as the Logs tab colours it. */
42
+ readonly level: LogLevel
43
+ /** Project root the event belongs to; the ring is keyed by it. */
44
+ readonly projectRoot: string
45
+ /**
46
+ * Session the event is attributed to. Set exactly when the lifecycle line it
47
+ * mirrors names one — `mounting`, `is up`, a stall — and absent on a
48
+ * project-level event such as a shared instance's unmount.
49
+ */
50
+ readonly sessionId?: string
51
+ /** `serverName` the event is about; absent for an event with no server. */
52
+ readonly server?: string
53
+ /** One line, without the `project-mcp:` prefix the log line carries. */
54
+ readonly message: string
55
+ /** The three facts an error carries — the failure, the endpoint, the document. */
56
+ readonly detail?: string
57
+ /**
58
+ * Wire code of {@link PluginEvent.message} (F-48), into the client's
59
+ * `projectMcp.host` namespace. The prose fields stay byte-identical English
60
+ * and remain the fallback: a consumer that never resolves codes — the DSH
61
+ * log is one — reads exactly what it read before the code existed.
62
+ */
63
+ readonly code?: string
64
+ /**
65
+ * Flat params of {@link PluginEvent.code}; numbers stringify at emission. A
66
+ * param whose name ends in `Code` (`reasonCode`, `sharingCode`) is itself a
67
+ * wire code the client resolves two-level, substituting it under the plain
68
+ * name.
69
+ */
70
+ readonly params?: Record<string, string>
71
+ /** Wire code of {@link PluginEvent.detail}, the same additive companion. */
72
+ readonly detailCode?: string
73
+ /** Flat params of {@link PluginEvent.detailCode}. */
74
+ readonly detailParams?: Record<string, string>
75
+ /**
76
+ * The DSH log line, when it says more than {@link PluginEvent.message}.
77
+ *
78
+ * `message` is what the tab lists one row per event; the line is what an
79
+ * operator reads in the host log, and for two events it names what the row's
80
+ * own columns already carry — the declaring path and the endpoint of a failed
81
+ * mount, the server and the root of a release. The runtime passes the very
82
+ * text the line had before the event existed, so the log is unchanged; absent
83
+ * means `message` is the line.
84
+ */
85
+ readonly line?: string
86
+ /**
87
+ * Severity the DSH log writes this event under, when it differs from
88
+ * {@link PluginEvent.level}.
89
+ *
90
+ * The tab's level is about the row — a release is a warning there, a failed
91
+ * mount is an error — while the host log keeps the level the line always had
92
+ * (`info` for the whole lifecycle except a failure or a stall, which are
93
+ * `warn`). Two readers, two vocabularies: without this field, wiring the log
94
+ * through the event would silently promote `unmounting` to `warn` and
95
+ * `mount failed` to `error` in the operator's log. Absent means the host log
96
+ * follows {@link PluginEvent.level}.
97
+ */
98
+ readonly logLevel?: LogLevel
99
+ }
100
+
101
+ /** One subscriber, told the whole event at publication time. */
102
+ export type PluginEventListener = (event: PluginEvent) => void
103
+
104
+ /**
105
+ * The one level method this module calls on a host logger.
106
+ *
107
+ * Structural on purpose: the runtime's `ctx.logger` satisfies it, and so does a
108
+ * test double with no error method.
109
+ */
110
+ export type LoggerMethod = (format: unknown, ...parameters: unknown[]) => void
111
+
112
+ /**
113
+ * The host logger as this module needs it: the level methods, and nothing else.
114
+ *
115
+ * Deliberately not `LoggerService` — the service has a call signature and a
116
+ * `debug` method this module never uses, so declaring only the three makes a
117
+ * partial double (`{ warn }`) a valid logger.
118
+ */
119
+ export interface PluginLoggerLike {
120
+ error?: LoggerMethod
121
+ info?: LoggerMethod
122
+ warn?: LoggerMethod
123
+ }
124
+
125
+ /** Listeners in subscription order; publication walks a copy of it. */
126
+ const listeners = new Set<PluginEventListener>()
127
+
128
+ /**
129
+ * Publish one plugin event to every subscriber, and swallow what they raise.
130
+ *
131
+ * Called from the runtime points that used to write the DSH log and the ring by
132
+ * hand, and the only publication point there is. Listeners run synchronously in
133
+ * subscription order — so a consumer registered first sees the event first —
134
+ * over a snapshot of the set, which keeps a listener that unsubscribes itself
135
+ * (or subscribes another) during the walk from corrupting it.
136
+ * @param event - the event to publish.
137
+ */
138
+ export function emitEvent(event: PluginEvent): void {
139
+ for (const listener of [...listeners]) {
140
+ try {
141
+ listener(event)
142
+ } catch {
143
+ // A consumer's failure is not the reporting pass's failure: the ring
144
+ // already promises the same, and one broken reader must not cost the
145
+ // others the event.
146
+ }
147
+ }
148
+ }
149
+
150
+ /**
151
+ * Subscribe a consumer.
152
+ *
153
+ * The ring is one such consumer, installed here for the life of the module; a
154
+ * host logger and a test are others. Subscribing the same listener twice keeps
155
+ * the one entry it already has, so a wrapper re-registered around the same touch
156
+ * does not make the event arrive twice, and unsubscribing is idempotent:
157
+ * {@link PluginEventListener} is unique in the set, and removing what is absent
158
+ * is a no-op.
159
+ * @param listener - told every event published from now on.
160
+ * @returns the disposer that stops it; safe to call more than once.
161
+ */
162
+ export function subscribeEvent(listener: PluginEventListener): () => void {
163
+ listeners.add(listener)
164
+ return () => {
165
+ listeners.delete(listener)
166
+ }
167
+ }
168
+
169
+ /**
170
+ * Whether a listener is subscribed right now.
171
+ *
172
+ * A diagnostic for the subscription itself: the disposer returns nothing, so
173
+ * this is how a caller — a test proving that a disposer detached its listener,
174
+ * or memory after a re-mount — reads the fact without counting a publication.
175
+ * @param listener - the listener to look up.
176
+ * @returns `true` while it is subscribed.
177
+ */
178
+ export function isSubscribed(listener: PluginEventListener): boolean {
179
+ return listeners.has(listener)
180
+ }
181
+
182
+ /**
183
+ * The DSH log as a consumer: one line per event, under the plugin's own prefix
184
+ * and level.
185
+ *
186
+ * Returns the listener rather than attaching anything itself: the logger lives
187
+ * on the host context, which only the runtime holds, so the runtime owns the
188
+ * subscription (and drops it when it is disposed). The line is `project-mcp: `
189
+ * plus {@link logText}, so the text a reader has seen does not change; the level
190
+ * method is {@link PluginEvent.logLevel} when the event names one, because that
191
+ * is the level the line has always had, and the tab's own level otherwise — and
192
+ * a partial logger gets the nearest method it has ({@link levelMethod}).
193
+ * @param logger - host logger whose level methods carry the line.
194
+ * @returns the listener to subscribe; detach it with the disposer
195
+ * {@link subscribeEvent} returned.
196
+ */
197
+ export function logConsumer(logger: PluginLoggerLike): PluginEventListener {
198
+ return (event) => {
199
+ const method = levelMethod(logger, event.logLevel ?? event.level)
200
+ if (method === undefined) return
201
+ method(`project-mcp: ${logText(event)}`)
202
+ }
203
+ }
204
+
205
+ /**
206
+ * The one line the DSH log writes for an event.
207
+ *
208
+ * An event that named the line it replaces carries it ({@link PluginEvent.line}),
209
+ * so the log is byte-for-byte what it was. The rest compose it: where the
210
+ * lifecycle line named the server in front of the message, the event carries the
211
+ * name as its own field, because the tab draws it as a column and does not repeat
212
+ * it in the message — `mounting`, `is up` and `unmounting` put the name back in
213
+ * here. The stall and the failure already open their message with the name (it is
214
+ * the first line of the row's detail).
215
+ * @param event - the event to render.
216
+ * @returns the line, without the `project-mcp: ` prefix.
217
+ */
218
+ function logText(event: PluginEvent): string {
219
+ if (event.line !== undefined) return event.line
220
+ const server = event.server
221
+ if (server !== undefined) {
222
+ if (event.message.startsWith('mounting ')) return `${server}: ${event.message}`
223
+ if (event.message.startsWith('is up — ')) return `${server} ${event.message}`
224
+ if (event.message.startsWith('unmounting — ')) {
225
+ return `unmounting ${server} in ${event.projectRoot} — ${event.message.slice('unmounting — '.length)}`
226
+ }
227
+ }
228
+ return event.message
229
+ }
230
+
231
+ /**
232
+ * The logger method one level writes through; `up` is an info-level success.
233
+ *
234
+ * A partial logger falls back to the levels it does have — `error`, then `warn`,
235
+ * then `info` — rather than losing the line: the harnesses that publish only
236
+ * `warn` are the reason, and a deployment's logger has all three.
237
+ */
238
+ function levelMethod(logger: PluginLoggerLike, level: LogLevel): LoggerMethod | undefined {
239
+ if (level === 'warn') return logger.warn ?? logger.info
240
+ if (level === 'error') return logger.error ?? logger.warn ?? logger.info
241
+ return logger.info
242
+ }
243
+
244
+ /**
245
+ * The ring as a consumer, installed once for the module.
246
+ *
247
+ * Subscribed here rather than called by the runtime so the runtime has exactly
248
+ * one write path: it publishes, and the tab and the DSH log both read that one
249
+ * publication. {@link record} stays the ring's only writer, and stays total —
250
+ * it is written to be called from an event the pass must not fail over.
251
+ */
252
+ subscribeEvent((event) => {
253
+ record(event)
254
+ })