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,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
+ }