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
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The per-project tool policy, as the browser half reads and writes it.
|
|
3
|
+
*
|
|
4
|
+
* The host owns the policy: it stores it next to the usage counters, applies it
|
|
5
|
+
* on every request assembly, and answers with the fresh snapshot. This module
|
|
6
|
+
* only shapes what the panel asks for and turns what came back into the two
|
|
7
|
+
* readings the surfaces print — the mode in force and the list the user pinned.
|
|
8
|
+
* Keeping the shapes here (instead of in a component) is what lets a no-DOM test
|
|
9
|
+
* assert the exact body a `Pin` click posts.
|
|
10
|
+
*
|
|
11
|
+
* Nothing here invents a value: a project the host has no policy for follows
|
|
12
|
+
* {@link DEFAULT_TOOL_POLICY}, which is the frozen contract's own default.
|
|
13
|
+
*
|
|
14
|
+
* @module dsh-project-mcp/client/policy
|
|
15
|
+
*/
|
|
16
|
+
|
|
17
|
+
import { ROUTE_ACTIONS, ROUTE_PREFIX } from '../shared.ts'
|
|
18
|
+
import type { ConflictRequest, OperatorRequest, PinRequest, PolicyRequest } from '../shared.ts'
|
|
19
|
+
import { DEFAULT_TOOL_POLICY } from '../types.ts'
|
|
20
|
+
import type { ConflictChoice, ProjectSnapshot, ToolMode, ToolPolicy } from '../types.ts'
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* The project's effective policy.
|
|
24
|
+
*
|
|
25
|
+
* `policy` is absent only from a snapshot a host older than the policy store
|
|
26
|
+
* produced; the contract makes that the shipped default, so the panel reads a
|
|
27
|
+
* bare project correctly instead of guarding for the field everywhere.
|
|
28
|
+
* @param project - one project of the host snapshot.
|
|
29
|
+
* @returns the policy in force, never undefined.
|
|
30
|
+
*/
|
|
31
|
+
export function policyOf(project: Pick<ProjectSnapshot, 'policy'>): ToolPolicy {
|
|
32
|
+
return project.policy ?? DEFAULT_TOOL_POLICY
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** The body the host expects for one pin or unpin, per `PinRequest`. */
|
|
36
|
+
export function pinBody(projectRoot: string, tool: string, pinned: boolean): PinRequest {
|
|
37
|
+
return { projectRoot, tool, pinned }
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** The body the host expects for one mode change, per `PolicyRequest`. */
|
|
41
|
+
export function policyBody(projectRoot: string, mode: ToolMode): PolicyRequest {
|
|
42
|
+
return { projectRoot, mode }
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* The body the host expects for one conflict choice, per `ConflictRequest`.
|
|
47
|
+
*
|
|
48
|
+
* The name travels as the project declared it, never as the local alias: the
|
|
49
|
+
* alias is the host's own computation from its config and the project folder,
|
|
50
|
+
* and a panel that sent one back would disagree with the host the moment either
|
|
51
|
+
* changed.
|
|
52
|
+
* @param projectRoot - the project the contested name belongs to.
|
|
53
|
+
* @param server - the contested `serverName`, as declared.
|
|
54
|
+
* @param choice - the declaration to show.
|
|
55
|
+
* @returns the request body.
|
|
56
|
+
*/
|
|
57
|
+
export function conflictBody(
|
|
58
|
+
projectRoot: string,
|
|
59
|
+
server: string,
|
|
60
|
+
choice: ConflictChoice,
|
|
61
|
+
): ConflictRequest {
|
|
62
|
+
return { projectRoot, server, choice }
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/**
|
|
66
|
+
* The body of one operator request — `Sync`, `Retry`.
|
|
67
|
+
*
|
|
68
|
+
* A surface that shows a single project names it: the host then touches only
|
|
69
|
+
* that project's servers and answers with that project's slice of the snapshot.
|
|
70
|
+
* `full` keeps the answer whole for a surface that lists every project — the
|
|
71
|
+
* settings page — while the action itself still stays inside `projectRoot`.
|
|
72
|
+
* @param projectRoot - the project the action applies to, when the surface has one.
|
|
73
|
+
* @param full - ask for the whole snapshot in the answer.
|
|
74
|
+
* @returns the request body; `{}` when there is no project to name.
|
|
75
|
+
*/
|
|
76
|
+
export function operatorBody(projectRoot: string | undefined, full = false): OperatorRequest {
|
|
77
|
+
if (projectRoot === undefined) return {}
|
|
78
|
+
return full ? { projectRoot, full: true } : { projectRoot }
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Submit one pin or unpin and read the host's answer.
|
|
83
|
+
*
|
|
84
|
+
* The host answers with the fresh snapshot on success and with an explanation
|
|
85
|
+
* otherwise (unknown project, unknown tool). Both are returned rather than
|
|
86
|
+
* thrown, because a refusal is a state the panel shows, not a crash.
|
|
87
|
+
* @param body - the `PinRequest` to post.
|
|
88
|
+
* @returns the fresh snapshot, or the host's refusal.
|
|
89
|
+
*/
|
|
90
|
+
export async function postPin(body: PinRequest): Promise<PolicyAnswer> {
|
|
91
|
+
return postPolicy(ROUTE_ACTIONS.pin, body)
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/**
|
|
95
|
+
* Submit one mode change and read the host's answer.
|
|
96
|
+
* @param body - the `PolicyRequest` to post.
|
|
97
|
+
* @returns the fresh snapshot, or the host's refusal.
|
|
98
|
+
*/
|
|
99
|
+
export async function postPolicyMode(body: PolicyRequest): Promise<PolicyAnswer> {
|
|
100
|
+
return postPolicy(ROUTE_ACTIONS.policy, body)
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Submit one conflict choice and read the host's answer.
|
|
105
|
+
* @param body - the `ConflictRequest` to post.
|
|
106
|
+
* @returns the fresh snapshot, or the host's refusal.
|
|
107
|
+
*/
|
|
108
|
+
export async function postConflict(body: ConflictRequest): Promise<PolicyAnswer> {
|
|
109
|
+
return postPolicy(ROUTE_ACTIONS.conflict, body)
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* A refusal the host answered with: the English prose, plus the wire code and
|
|
114
|
+
* its flat params when the host coded it (F-48). The companions are what the
|
|
115
|
+
* render sites resolve through the host namespace; an old host's refusal
|
|
116
|
+
* carries none and renders its `message` exactly as before.
|
|
117
|
+
*/
|
|
118
|
+
export interface PolicyRefusal {
|
|
119
|
+
/** The host's own English sentence. */
|
|
120
|
+
readonly message: string
|
|
121
|
+
/** Wire code of {@link message} (`projectMcp.host` namespace), when coded. */
|
|
122
|
+
readonly messageCode?: string | undefined
|
|
123
|
+
/** Flat params of {@link messageCode}, when it has any. */
|
|
124
|
+
readonly messageParams?: Record<string, string> | undefined
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** Either the snapshot the host re-read after a write, or the reason it refused. */
|
|
128
|
+
export type PolicyAnswer = { ok: true; snapshot: unknown } | ({ ok: false } & PolicyRefusal)
|
|
129
|
+
|
|
130
|
+
interface PolicyEnvelope {
|
|
131
|
+
ok?: boolean
|
|
132
|
+
value?: unknown
|
|
133
|
+
error?: { code?: string; message?: string; messageCode?: string; messageParams?: Record<string, string> }
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/**
|
|
137
|
+
* `POST` one policy write and unwrap the host's envelope.
|
|
138
|
+
*
|
|
139
|
+
* Both call sites pass the frozen route constant rather than a literal, so a
|
|
140
|
+
* rename cannot leave one of the two routes behind.
|
|
141
|
+
* @param action - route action under `ROUTE_PREFIX`.
|
|
142
|
+
* @param body - the pin or mode request.
|
|
143
|
+
* @returns the fresh snapshot or the refusal message.
|
|
144
|
+
*/
|
|
145
|
+
async function postPolicy(
|
|
146
|
+
action: typeof ROUTE_ACTIONS.pin | typeof ROUTE_ACTIONS.policy | typeof ROUTE_ACTIONS.conflict,
|
|
147
|
+
body: PinRequest | PolicyRequest | ConflictRequest,
|
|
148
|
+
): Promise<PolicyAnswer> {
|
|
149
|
+
try {
|
|
150
|
+
const response = await fetch(`${ROUTE_PREFIX}/${action}`, {
|
|
151
|
+
method: 'POST',
|
|
152
|
+
headers: { 'content-type': 'application/json' },
|
|
153
|
+
body: JSON.stringify(body),
|
|
154
|
+
})
|
|
155
|
+
const payload = (await response.json()) as PolicyEnvelope
|
|
156
|
+
if (payload.ok === true) return { ok: true, snapshot: payload.value }
|
|
157
|
+
return {
|
|
158
|
+
ok: false,
|
|
159
|
+
message: payload.error?.message ?? `request failed (${response.status})`,
|
|
160
|
+
// The coded companions are optional on the wire: an old host's refusal
|
|
161
|
+
// has none, and the render sites fall back to the message.
|
|
162
|
+
...(typeof payload.error?.messageCode === 'string'
|
|
163
|
+
? { messageCode: payload.error.messageCode, messageParams: payload.error.messageParams }
|
|
164
|
+
: {}),
|
|
165
|
+
}
|
|
166
|
+
} catch (error) {
|
|
167
|
+
return { ok: false, message: error instanceof Error ? error.message : String(error) }
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/** Hooks a pin write reports through, so one row can disable and explain. */
|
|
172
|
+
export interface PinWriteHooks {
|
|
173
|
+
/** Called before the request goes out, with the tool it is about. */
|
|
174
|
+
onStart?: (tool: string) => void
|
|
175
|
+
/** Called after it settles, successfully or not. */
|
|
176
|
+
onSettled?: (tool: string) => void
|
|
177
|
+
/**
|
|
178
|
+
* Called only when the host refused, with its own words — and with the
|
|
179
|
+
* refusal's wire code and flat params when the host coded them (F-48).
|
|
180
|
+
*/
|
|
181
|
+
onRefused?: (message: string, messageCode?: string, messageParams?: Record<string, string>) => void
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
/**
|
|
185
|
+
* Write one tool's pin and report what happened.
|
|
186
|
+
*
|
|
187
|
+
* The twin of {@link requestMode} for the other half of the policy: it `POST`s
|
|
188
|
+
* through {@link postPin}, which answers rather than throws, and leaves the
|
|
189
|
+
* pending set and the refusal line to the caller — so one row disables while its
|
|
190
|
+
* own write is in flight and a refusal is shown instead of swallowed.
|
|
191
|
+
* @param body - the project, the public tool name and the wanted pin state.
|
|
192
|
+
* @param hooks - lifecycle callbacks; all optional.
|
|
193
|
+
* @returns the host's answer, for a caller that wants to keep the snapshot.
|
|
194
|
+
*/
|
|
195
|
+
export async function requestPin(
|
|
196
|
+
body: PinRequest,
|
|
197
|
+
hooks: PinWriteHooks = {},
|
|
198
|
+
): Promise<PolicyAnswer> {
|
|
199
|
+
hooks.onStart?.(body.tool)
|
|
200
|
+
const answer = await postPin(body)
|
|
201
|
+
hooks.onSettled?.(body.tool)
|
|
202
|
+
if (!answer.ok) hooks.onRefused?.(answer.message, answer.messageCode, answer.messageParams)
|
|
203
|
+
return answer
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/** Hooks a mode write reports through, so a surface can disable and explain. */
|
|
207
|
+
export interface ModeWriteHooks {
|
|
208
|
+
/** Called before the request goes out. */
|
|
209
|
+
onStart?: (projectRoot: string) => void
|
|
210
|
+
/** Called after it settles, successfully or not. */
|
|
211
|
+
onSettled?: (projectRoot: string) => void
|
|
212
|
+
/**
|
|
213
|
+
* Called only when the host refused, with its own words — and with the
|
|
214
|
+
* refusal's wire code and flat params when the host coded them (F-48).
|
|
215
|
+
*/
|
|
216
|
+
onRefused?: (message: string, messageCode?: string, messageParams?: Record<string, string>) => void
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* Hooks a conflict choice reports through, so one card can disable its buttons.
|
|
221
|
+
*/
|
|
222
|
+
export interface ChoiceWriteHooks {
|
|
223
|
+
/** Called before the request goes out, with the name it is about. */
|
|
224
|
+
onStart?: (server: string) => void
|
|
225
|
+
/** Called after it settles, successfully or not. */
|
|
226
|
+
onSettled?: (server: string) => void
|
|
227
|
+
/**
|
|
228
|
+
* Called only when the host refused, with its own words — and with the
|
|
229
|
+
* refusal's wire code and flat params when the host coded them (F-48).
|
|
230
|
+
*/
|
|
231
|
+
onRefused?: (message: string, messageCode?: string, messageParams?: Record<string, string>) => void
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/**
|
|
235
|
+
* Write one conflict choice and report what happened.
|
|
236
|
+
*
|
|
237
|
+
* The twin of {@link requestPin} for the other durable decision a project
|
|
238
|
+
* carries. A choice is what moves an entry between a conflict report and a
|
|
239
|
+
* mounted server under its local name, so the host answers with the snapshot
|
|
240
|
+
* that already reflects it and the caller can draw the new state at once.
|
|
241
|
+
* @param body - the project, the contested name and the declaration to show.
|
|
242
|
+
* @param hooks - lifecycle callbacks; all optional.
|
|
243
|
+
* @returns the host's answer, for a caller that wants to keep the snapshot.
|
|
244
|
+
*/
|
|
245
|
+
export async function requestConflict(
|
|
246
|
+
body: ConflictRequest,
|
|
247
|
+
hooks: ChoiceWriteHooks = {},
|
|
248
|
+
): Promise<PolicyAnswer> {
|
|
249
|
+
hooks.onStart?.(body.server)
|
|
250
|
+
const answer = await postConflict(body)
|
|
251
|
+
hooks.onSettled?.(body.server)
|
|
252
|
+
if (!answer.ok) hooks.onRefused?.(answer.message, answer.messageCode, answer.messageParams)
|
|
253
|
+
return answer
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
/**
|
|
257
|
+
* Write one project's mode and report what happened.
|
|
258
|
+
*
|
|
259
|
+
* `POST`s through {@link postPolicyMode}, which already answers rather than
|
|
260
|
+
* throws, and is deliberately plain: the caller owns the pending set and the
|
|
261
|
+
* error line, so the whole write is a pure function of the request and three
|
|
262
|
+
* callbacks. That is what makes the disabled and refusal states of the switch
|
|
263
|
+
* testable without a DOM.
|
|
264
|
+
* @param body - the project and mode to store.
|
|
265
|
+
* @param hooks - lifecycle callbacks; all optional.
|
|
266
|
+
* @returns the host's answer, for a caller that wants to keep the snapshot.
|
|
267
|
+
*/
|
|
268
|
+
export async function requestMode(
|
|
269
|
+
body: PolicyRequest,
|
|
270
|
+
hooks: ModeWriteHooks = {},
|
|
271
|
+
): Promise<PolicyAnswer> {
|
|
272
|
+
hooks.onStart?.(body.projectRoot)
|
|
273
|
+
const answer = await postPolicyMode(body)
|
|
274
|
+
hooks.onSettled?.(body.projectRoot)
|
|
275
|
+
if (!answer.ok) hooks.onRefused?.(answer.message, answer.messageCode, answer.messageParams)
|
|
276
|
+
return answer
|
|
277
|
+
}
|