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/LICENSE +21 -0
- package/README.md +983 -0
- package/cordis.patch.yml +7 -0
- package/locale/en.json +6 -0
- package/locale/ru.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +106 -0
- package/src/activation.ts +1632 -0
- package/src/bridge.ts +486 -0
- package/src/client/design-fixtures.ts +399 -0
- package/src/client/design.ts +410 -0
- package/src/client/index.ts +255 -0
- package/src/client/locales/host.ts +570 -0
- package/src/client/locales/ui.ts +914 -0
- package/src/client/plugin-config.ts +721 -0
- package/src/client/policy.ts +277 -0
- package/src/client/settings-tools.ts +1136 -0
- package/src/client/settings.ts +3603 -0
- package/src/client/tab-locale.ts +94 -0
- package/src/client/toasts.ts +553 -0
- package/src/client/usage-view.ts +190 -0
- package/src/client/view.ts +4120 -0
- package/src/discovery.ts +211 -0
- package/src/guidance.ts +415 -0
- package/src/index.ts +685 -0
- package/src/logs.ts +184 -0
- package/src/naming.ts +134 -0
- package/src/notifications.ts +254 -0
- package/src/parse.ts +637 -0
- package/src/policy.ts +425 -0
- package/src/runtime.ts +4222 -0
- package/src/shared.ts +130 -0
- package/src/types.ts +662 -0
- package/src/ui.ts +579 -0
- package/src/usage.ts +442 -0
- package/src/write.ts +447 -0
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
|
+
})
|