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/shared.ts ADDED
@@ -0,0 +1,130 @@
1
+ /**
2
+ * Contract shared by the host half and the browser half of the panel.
3
+ *
4
+ * Import-free on purpose: the client bundle must not pull host code in, and
5
+ * `ctx.betterSidebar` exists only in the browser, so the two halves meet at
6
+ * these routes over HTTP.
7
+ *
8
+ * @module dsh-project-mcp/shared
9
+ */
10
+
11
+ import type { ConflictChoice, EntrySnapshot, ToolMode } from './types.ts'
12
+
13
+ /** Route prefix the host serves and the sidebar panel fetches. */
14
+ export const ROUTE_PREFIX = '/project-mcp'
15
+
16
+ /** Sidebar tab id; also the `SidebarTab.type` the panel opens as. */
17
+ export const TAB_ID = 'dsh-project-mcp:servers'
18
+
19
+ /** Plugin name, shared by both halves. */
20
+ export const PACKAGE_NAME = 'dsh-project-mcp'
21
+
22
+ /** Actions the host serves under {@link ROUTE_PREFIX}, and the panel fetches. */
23
+ export const ROUTE_ACTIONS = {
24
+ /** `GET`: the current snapshot. */
25
+ snapshot: 'snapshot',
26
+ /** `POST`: ask for a rescan; answers as soon as the request is accepted. */
27
+ sync: 'sync',
28
+ /** `POST`: drop this project's failed mounts and re-mount them; answers once they are dropped. */
29
+ retry: 'retry',
30
+ /** `GET`: the status channel — one pushed frame per change, held open. */
31
+ events: 'events',
32
+ /** `GET`: one page of a project's log ring, oldest first, for "show older". */
33
+ logs: 'logs',
34
+ /** `POST`: release this session's mounts. */
35
+ release: 'release',
36
+ /** `POST`: write one edited entry back to its declaring document. */
37
+ save: 'save',
38
+ /** `POST`: pin or unpin one tool of one project. */
39
+ pin: 'pin',
40
+ /** `POST`: set one project's tool mode. */
41
+ policy: 'policy',
42
+ /** `POST`: choose which declaration of a contested `serverName` shows. */
43
+ conflict: 'conflict',
44
+ } as const
45
+
46
+ /**
47
+ * One operator request: the body of `POST sync` and `POST retry`.
48
+ *
49
+ * `projectRoot` scopes the action, so a surface that shows one project never
50
+ * starts or restarts a server for another. `full` is the answer shape: a
51
+ * single-project surface leaves it out and gets that project's slice back, while
52
+ * a surface that lists every project — the settings page — asks for the whole
53
+ * snapshot, since narrowing would empty the list it renders.
54
+ */
55
+ export interface OperatorRequest {
56
+ /** Project the action applies to; omitted covers every project. */
57
+ readonly projectRoot?: string
58
+ /** Answer with the whole snapshot rather than `projectRoot`'s slice. */
59
+ readonly full?: boolean
60
+ }
61
+
62
+ /** Pin or unpin one tool of one project. */
63
+ export interface PinRequest {
64
+ /** Project root the tool belongs to. */
65
+ readonly projectRoot: string
66
+ /** Public registry name, eg `mcp__tglider__workspace`. */
67
+ readonly tool: string
68
+ /** `true` pins it, `false` unpins it. */
69
+ readonly pinned: boolean
70
+ }
71
+
72
+ /** Set one project's tool mode. Pins travel in their own request. */
73
+ export interface PolicyRequest {
74
+ /** Project root the mode applies to. */
75
+ readonly projectRoot: string
76
+ /** The mode to store. */
77
+ readonly mode: ToolMode
78
+ }
79
+
80
+ /**
81
+ * Choose which declaration of one contested `serverName` a project shows.
82
+ *
83
+ * The name stays the profile's either way; the answer decides whether the
84
+ * project's own entry mounts beside it under a local namespace. The name is
85
+ * carried as declared — the sanitized `mcpServers` key — because that is what
86
+ * the conflict report names, and the local name is the plugin's to compute.
87
+ */
88
+ export interface ConflictRequest {
89
+ /** Project root the name belongs to. */
90
+ readonly projectRoot: string
91
+ /** Contested `serverName`, as the project declared it. */
92
+ readonly server: string
93
+ /** The declaration to show. */
94
+ readonly choice: ConflictChoice
95
+ }
96
+
97
+ /**
98
+ * One entry a save writes.
99
+ *
100
+ * The panel submits the {@link EntrySnapshot} it was given, with the fields the
101
+ * user changed. A masked `env`/`headers` key submitted without a `value` keeps
102
+ * whatever the document declares for it; a key the submission omits is removed.
103
+ */
104
+ export interface SaveRequest {
105
+ /** Project root the edited row belongs to. */
106
+ readonly projectRoot: string
107
+ /** `serverName` being edited. */
108
+ readonly server: string
109
+ /** Absolute path of the document the entry came from. */
110
+ readonly document: string
111
+ /** `documentRevision` the edit was built from; a mismatch refuses the write. */
112
+ readonly revision: string
113
+ /** `true` acknowledges a write to the global tier; required only there. */
114
+ readonly consent?: boolean
115
+ /** The entry body to write. */
116
+ readonly entry: EntrySnapshot
117
+ }
118
+
119
+ /** Error codes a save answers with, each with its own sentence in the panel. */
120
+ export type SaveErrorCode =
121
+ /** The entry is not one this plugin would mount; nothing was written. */
122
+ | 'invalid'
123
+ /** The document may not be written: profile, `<DSH_HOME>`, or no consent. */
124
+ | 'blocked'
125
+ /** The document changed since the snapshot was taken; nothing was written. */
126
+ | 'conflict'
127
+ /** The document or the server is no longer there. */
128
+ | 'not-found'
129
+ /** The write itself failed; the document is left as it was. */
130
+ | 'failed'