@bevel-software/platform-core-frontend 0.7.4 → 0.8.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.
Files changed (113) hide show
  1. package/LICENSE +202 -202
  2. package/THIRD-PARTY-NOTICES.md +344 -988
  3. package/package.json +5 -5
  4. package/src/core/CoreAppShell.tsx +4 -4
  5. package/src/core/__tests__/ShellRoutes.test.tsx +1 -1
  6. package/src/core/__tests__/bootstrap.test.ts +47 -2
  7. package/src/core/bootstrap.ts +20 -0
  8. package/src/css-side-effect-imports.d.ts +7 -7
  9. package/src/modules/access/__tests__/ManageAccessDialog.placement.test.tsx +1 -1
  10. package/src/modules/access/__tests__/ManageAccessDialog.test.tsx +5 -5
  11. package/src/modules/access/api.ts +5 -5
  12. package/src/modules/access/components/ManageAccessDialog.tsx +21 -20
  13. package/src/modules/admin/__tests__/AdminRolesPage.suggest.test.tsx +1 -1
  14. package/src/modules/admin/components/AdminRolesPage.tsx +1 -1
  15. package/src/modules/change-requests/__tests__/useFileOnBranch.test.tsx +2 -2
  16. package/src/modules/change-requests/components/ChangeRequestDialog.tsx +1 -1
  17. package/src/modules/change-requests/hooks/useApplyChangeRequest.ts +1 -1
  18. package/src/modules/layout/__tests__/SidebarFrameResponsive.test.tsx +4 -4
  19. package/src/modules/layout/__tests__/SidebarToggle.test.tsx +4 -4
  20. package/src/modules/layout/__tests__/breakpoints.test.ts +1 -1
  21. package/src/modules/layout/components/SidebarFrame.tsx +2 -2
  22. package/src/modules/library/__tests__/{AddToGroupDialog.test.tsx → AddToPluginDialog.test.tsx} +34 -34
  23. package/src/modules/library/__tests__/LibraryCard.test.tsx +30 -11
  24. package/src/modules/library/__tests__/LibraryRoutes.test.tsx +84 -59
  25. package/src/modules/library/__tests__/LibrarySidebarMenu.test.tsx +51 -51
  26. package/src/modules/library/__tests__/{LockedGroupView.test.tsx → LockedPluginView.test.tsx} +33 -33
  27. package/src/modules/library/__tests__/McpServerSection.test.tsx +138 -0
  28. package/src/modules/library/__tests__/{NewGroupDialog.test.tsx → NewPluginDialog.test.tsx} +22 -22
  29. package/src/modules/library/__tests__/PersonalAddDialog.test.tsx +7 -7
  30. package/src/modules/library/__tests__/PluginExtras.test.tsx +131 -0
  31. package/src/modules/library/__tests__/{GroupJoinRequests.test.tsx → PluginJoinRequests.test.tsx} +24 -24
  32. package/src/modules/library/__tests__/{GroupPage.test.tsx → PluginPage.test.tsx} +101 -101
  33. package/src/modules/library/__tests__/{GroupsIndexPage.test.tsx → PluginsIndexPage.test.tsx} +57 -57
  34. package/src/modules/library/__tests__/{GroupsSidebar.contextmenu.test.tsx → PluginsSidebar.contextmenu.test.tsx} +31 -31
  35. package/src/modules/library/__tests__/{GroupsSidebar.locked.test.tsx → PluginsSidebar.locked.test.tsx} +28 -28
  36. package/src/modules/library/__tests__/{GroupsSidebar.test.tsx → PluginsSidebar.test.tsx} +39 -39
  37. package/src/modules/library/__tests__/{GroupsSidebarMenu.test.tsx → PluginsSidebarMenu.test.tsx} +18 -18
  38. package/src/modules/library/__tests__/SkillPage.test.tsx +8 -8
  39. package/src/modules/library/__tests__/ToolConnectionSection.test.tsx +2 -2
  40. package/src/modules/library/__tests__/ToolPage.test.tsx +41 -12
  41. package/src/modules/library/__tests__/ToolSharePanel.test.tsx +1 -1
  42. package/src/modules/library/__tests__/WorkspaceItemRoute.test.tsx +57 -57
  43. package/src/modules/library/__tests__/auth-harness.tsx +4 -4
  44. package/src/modules/library/__tests__/status.test.ts +19 -19
  45. package/src/modules/library/__tests__/tools.api.test.ts +70 -0
  46. package/src/modules/library/__tests__/useToolPage.test.tsx +4 -4
  47. package/src/modules/library/components/AccessRequestsBanner.tsx +8 -8
  48. package/src/modules/library/components/{AddToGroupDialog.tsx → AddToPluginDialog.tsx} +11 -11
  49. package/src/modules/library/components/ChangeRequestDock.tsx +1 -1
  50. package/src/modules/library/components/{DeleteGroupDialog.tsx → DeletePluginDialog.tsx} +9 -9
  51. package/src/modules/library/components/LibraryCard.tsx +26 -2
  52. package/src/modules/library/components/LibraryLayout.tsx +70 -70
  53. package/src/modules/library/components/LibraryPage.tsx +8 -8
  54. package/src/modules/library/components/LockGlyph.tsx +1 -1
  55. package/src/modules/library/components/{LockedGroupView.tsx → LockedPluginView.tsx} +35 -35
  56. package/src/modules/library/components/{ManagedGroupRequests.tsx → ManagedPluginRequests.tsx} +13 -13
  57. package/src/modules/library/components/{NewGroupDialog.tsx → NewPluginDialog.tsx} +24 -24
  58. package/src/modules/library/components/NewSkillPanel.tsx +5 -5
  59. package/src/modules/library/components/PageActions.tsx +3 -3
  60. package/src/modules/library/components/PersonalAddDialog.tsx +5 -5
  61. package/src/modules/library/components/{PersonalGroupPage.tsx → PersonalPluginPage.tsx} +17 -17
  62. package/src/modules/library/components/PluginExtras.tsx +195 -0
  63. package/src/modules/library/components/{GroupIndexRow.tsx → PluginIndexRow.tsx} +6 -6
  64. package/src/modules/library/components/{GroupJoinRequests.tsx → PluginJoinRequests.tsx} +12 -12
  65. package/src/modules/library/components/{GroupPage.tsx → PluginPage.tsx} +72 -69
  66. package/src/modules/library/components/{GroupsIndexPage.tsx → PluginsIndexPage.tsx} +46 -46
  67. package/src/modules/library/components/{GroupsSidebar.tsx → PluginsSidebar.tsx} +55 -55
  68. package/src/modules/library/components/{GroupsSidebarMenu.tsx → PluginsSidebarMenu.tsx} +15 -15
  69. package/src/modules/library/components/{group-page-parts.tsx → plugin-page-parts.tsx} +35 -24
  70. package/src/modules/library/components/skill-page/SkillPage.tsx +12 -12
  71. package/src/modules/library/components/tool-page/McpServerSection.tsx +380 -0
  72. package/src/modules/library/components/tool-page/ToolPage.tsx +22 -5
  73. package/src/modules/library/hooks/useJoinRequests.ts +8 -8
  74. package/src/modules/library/routes/LibraryRoutes.tsx +30 -17
  75. package/src/modules/library/routes/WorkspaceItemRoute.tsx +24 -24
  76. package/src/modules/library/routes/library-paths.ts +36 -36
  77. package/src/modules/library/services/library.api.ts +9 -9
  78. package/src/modules/library/services/{groups.api.ts → plugins.api.ts} +43 -43
  79. package/src/modules/library/services/tools.api.ts +54 -0
  80. package/src/modules/library/state/library-data.tsx +46 -46
  81. package/src/modules/library/utils/names.ts +1 -1
  82. package/src/modules/library/utils/{personal-group.ts → personal-plugin.ts} +8 -8
  83. package/src/modules/library/utils/{group-summary.ts → plugin-summary.ts} +14 -14
  84. package/src/modules/library/utils/status.ts +17 -17
  85. package/src/modules/onboarding/__tests__/onboarding.test.tsx +86 -8
  86. package/src/modules/onboarding/agent-clients.ts +18 -14
  87. package/src/modules/onboarding/components/WelcomePage.tsx +19 -8
  88. package/src/modules/review/components/MarkdownDiffViewer.tsx +1 -1
  89. package/src/modules/review/components/ReviewPanel.tsx +11 -11
  90. package/src/modules/review/components/__tests__/{isGroupItemPath.test.ts → isPluginItemPath.test.ts} +24 -24
  91. package/src/modules/secrets-vault/components/ToolSecretsPanel.tsx +3 -3
  92. package/src/modules/secrets-vault/components/__tests__/SecretsPage.test.tsx +1 -1
  93. package/src/modules/settings/components/SettingsLayout.tsx +1 -1
  94. package/src/modules/settings/components/SettingsNav.tsx +5 -5
  95. package/src/modules/toolbar/components/ExternalAgentAccessPage.tsx +29 -107
  96. package/src/modules/toolbar/components/__tests__/AppSwitcher.test.tsx +1 -1
  97. package/src/modules/toolbar/components/__tests__/ExternalAgentAccessPage.test.tsx +228 -0
  98. package/src/modules/toolbar/components/__tests__/Toolbar.test.tsx +3 -3
  99. package/src/modules/workspace/components/FileExplorer.tsx +12 -12
  100. package/src/modules/workspace/components/__tests__/FileExplorer.test.tsx +14 -14
  101. package/src/modules/workspace/components/renderers/ToolRenderer.tsx +7 -2
  102. package/src/modules/workspace/utils/__tests__/diff.test.ts +1 -1
  103. package/src/modules/workspace/utils/fileTree.ts +3 -3
  104. package/src/shared/mcp/ClaudeInstallLink.tsx +88 -0
  105. package/src/shared/mcp/ConnectionInstructions.tsx +51 -0
  106. package/src/shared/mcp/CopyBlock.tsx +42 -0
  107. package/src/shared/mcp/__tests__/ClaudeInstallLink.test.tsx +40 -0
  108. package/src/shared/mcp/__tests__/connect-snippets.test.ts +431 -0
  109. package/src/shared/mcp/__tests__/useCopyFeedback.test.ts +112 -0
  110. package/src/shared/mcp/connect-snippets.ts +353 -0
  111. package/src/shared/mcp/index.ts +28 -0
  112. package/src/shared/mcp/useCopyFeedback.ts +46 -0
  113. package/src/test-setup.ts +11 -0
@@ -0,0 +1,353 @@
1
+ /**
2
+ * Everything this app knows about handing its MCP endpoint to an agent: where
3
+ * the endpoint is, what a given client needs pasted into it, and whether the
4
+ * endpoint is in a state where a one-click connector link could possibly work.
5
+ *
6
+ * It lives in `shared/` rather than under `modules/onboarding/` on purpose.
7
+ * The welcome page and the External agent access page both need this, and
8
+ * some of it (the bearer-token variants) is settings-only, secret-bearing
9
+ * output that has no business being filed under the first-run experience —
10
+ * a folder name is a claim about who owns the code, and the next person
11
+ * auditing credential handling will not go looking in onboarding.
12
+ *
13
+ * PUBLIC_BACKEND_URL ─► config.publicBackendUrl ─┬─► OAuth resourceServerUrl
14
+ * (env) core-config.ts:326 │ (the authority)
15
+ * └─► GET /api/config { mcpUrl }
16
+ * │
17
+ * configureMcpUrl() ◄─────────────────┘
18
+ * │ loadServerConfig()
19
+ * ▼
20
+ * mcpEndpointUrl()
21
+ * │ │
22
+ * canDeepLink() ─┘ └─► claudeCodeCommand / jsonConfigSnippet / …
23
+ * │
24
+ * ▼
25
+ * claudeInstallUrl(url, connectorName(url))
26
+ */
27
+
28
+ /** Where `/api/mcp` hangs off a given origin. The one place that path is spelled. */
29
+ const MCP_PATH = '/api/mcp';
30
+
31
+ /**
32
+ * The deployment's own answer, from `GET /api/config`. Module-global because
33
+ * it is a property of the deployment rather than of any component, and it is
34
+ * settled once during boot — the same shape as the branch model next door.
35
+ *
36
+ * A FUNCTION rather than an exported constant: a module-scope constant would
37
+ * capture whatever was true at import time, and this module is imported by
38
+ * components that load before the boot fetch resolves (see the same warning
39
+ * on `library.api.ts`).
40
+ */
41
+ let configured: string | null = null;
42
+
43
+ /**
44
+ * Record what the server said. Tolerates absence and nonsense on purpose: an
45
+ * older server that predates the field, or a payload we cannot parse, must
46
+ * leave the app booting normally rather than take the whole page down for a
47
+ * connect snippet. Both cases fall back to the origin, which is what every
48
+ * surface used before this existed.
49
+ */
50
+ export function configureMcpUrl(url: unknown): void {
51
+ // Absent is the expected older-server case, not a problem — say nothing.
52
+ if (url === undefined || url === null || url === '') {
53
+ configured = null;
54
+ return;
55
+ }
56
+ configured = parseEndpoint(url);
57
+ if (configured === null) {
58
+ // A value WAS sent and we refused it. Without this the app silently shows
59
+ // the origin instead, and an operator who typo'd PUBLIC_BACKEND_URL has no
60
+ // signal anywhere — the snippets just quietly name the wrong server.
61
+ console.warn('[mcp] ignoring an unusable mcpUrl from /api/config:', url);
62
+ }
63
+ }
64
+
65
+ /**
66
+ * `null` unless this is a string holding an absolute http(s) URL.
67
+ *
68
+ * The scheme check is deliberate rather than incidental. `new URL()` happily
69
+ * parses `javascript:alert(1)` — nothing renders this value as an `href`
70
+ * today, and `canDeepLink` would refuse it anyway, but a value that reaches
71
+ * the UI from over the network should not be ABLE to carry a script scheme
72
+ * waiting for the next consumer to use it less carefully.
73
+ */
74
+ function parseEndpoint(url: unknown): string | null {
75
+ if (typeof url !== 'string' || url.trim() === '') return null;
76
+ try {
77
+ const parsed = new URL(url);
78
+ if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') return null;
79
+ /**
80
+ * Credentials are STRIPPED, not preserved and not rejected.
81
+ *
82
+ * A `PUBLIC_BACKEND_URL` of `https://user:hunter2@kb.acme.com` is a
83
+ * misconfiguration, but every surface downstream would have published the
84
+ * password: the copy blocks render this string on screen and put it on the
85
+ * clipboard, and the install link hands it to claude.ai. Rejecting outright
86
+ * would take the whole connect page down over a credential nobody needs —
87
+ * MCP authenticates over OAuth, so the userinfo is dead weight even when
88
+ * someone sets it.
89
+ *
90
+ * So: drop the secret, keep the address, and say so.
91
+ */
92
+ if (parsed.username !== '' || parsed.password !== '') {
93
+ console.warn(
94
+ '[mcp] stripped credentials from the configured mcpUrl — PUBLIC_BACKEND_URL should not carry a username or password',
95
+ );
96
+ parsed.username = '';
97
+ parsed.password = '';
98
+ }
99
+ return parsed.toString();
100
+ } catch {
101
+ return null;
102
+ }
103
+ }
104
+
105
+ /**
106
+ * The MCP endpoint to show people. The server's answer when we have one;
107
+ * otherwise the browser's origin, which is right on the common deployment and
108
+ * was the only behaviour before `mcpUrl` existed.
109
+ */
110
+ export function mcpEndpointUrl(): string {
111
+ return configured ?? `${window.location.origin}${MCP_PATH}`;
112
+ }
113
+
114
+ /** Drop any configured value. For tests — module-global state must not leak between them. */
115
+ export function resetMcpUrlForTests(): void {
116
+ configured = null;
117
+ }
118
+
119
+ /**
120
+ * Could claude.ai possibly reach this endpoint?
121
+ *
122
+ * Read the name literally. This answers "is this certainly dead", not "will
123
+ * this work" — claude.ai fetches the MCP server from Anthropic's
124
+ * infrastructure, and nothing we can compute from inside your network proves
125
+ * anything about that vantage point. An https URL on a hostname that only
126
+ * resolves inside a corporate network passes this check and still fails.
127
+ *
128
+ * It is worth having anyway, because the cases it DOES catch are the default
129
+ * configuration rather than an edge case: `publicBackendUrl` falls back to
130
+ * `http://localhost:3001` when `PUBLIC_BACKEND_URL` is unset, and
131
+ * `.env.example` ships it commented out. Every dev machine and every
132
+ * quickstart Docker deploy lands there. Offering a one-click button that
133
+ * cannot work on the first screen a self-hoster sees is worse than not
134
+ * offering one.
135
+ */
136
+ export function canDeepLink(url: string): boolean {
137
+ let parsed: URL;
138
+ try {
139
+ parsed = new URL(url);
140
+ } catch {
141
+ return false;
142
+ }
143
+ // Anthropic will not fetch plaintext http, whatever the host.
144
+ if (parsed.protocol !== 'https:') return false;
145
+
146
+ // Never hand a third party a URL carrying credentials. `parseEndpoint`
147
+ // already strips them on the way in; this is the second lock, because
148
+ // `canDeepLink` is exported and a future caller may not have gone through it.
149
+ if (parsed.username !== '' || parsed.password !== '') return false;
150
+
151
+ const host = parsed.hostname.toLowerCase();
152
+
153
+ // Bracketed IPv6 literal, e.g. `https://[2001:db8::1]/`.
154
+ if (host.startsWith('[')) return !isPrivateIpv6(host);
155
+
156
+ // Names that are private by definition.
157
+ if (host === 'localhost' || host.endsWith('.localhost')) return false;
158
+ if (host.endsWith('.local') || host.endsWith('.internal')) return false;
159
+
160
+ if (isDottedQuad(host)) return !isPrivateIpv4(host);
161
+
162
+ // A single-label DNS name (`https://hexis/`) has no public DNS to resolve.
163
+ return host.includes('.');
164
+ }
165
+
166
+ /** Four dot-separated decimal octets, each 0-255. */
167
+ function isDottedQuad(host: string): boolean {
168
+ const parts = host.split('.');
169
+ return (
170
+ parts.length === 4 &&
171
+ parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255)
172
+ );
173
+ }
174
+
175
+ /**
176
+ * Every IPv4 block that is not routable on the public internet.
177
+ *
178
+ * Broader than RFC 1918 on purpose. The gate's job is "could Anthropic reach
179
+ * this at all", and carrier-grade NAT (100.64/10) and the benchmark range
180
+ * (198.18/15) are just as unreachable as 10/8 while looking like ordinary
181
+ * public addresses. Only meaningful for a dotted-quad host — see `isDottedQuad`.
182
+ */
183
+ function isPrivateIpv4(host: string): boolean {
184
+ const [a, b, c] = host.split('.').map(Number) as [number, number, number, number];
185
+ if (a === 0) return true; // 0.0.0.0/8 this network
186
+ if (a === 10) return true; // 10.0.0.0/8 private
187
+ if (a === 127) return true; // 127.0.0.0/8 loopback
188
+ if (a === 100 && b >= 64 && b <= 127) return true; // 100.64.0.0/10 carrier-grade NAT
189
+ if (a === 169 && b === 254) return true; // 169.254.0.0/16 link-local
190
+ if (a === 172 && b >= 16 && b <= 31) return true; // 172.16.0.0/12 private
191
+ if (a === 192 && b === 0 && c === 0) return true; // 192.0.0.0/24 IETF protocol assignments
192
+ if (a === 192 && b === 0 && c === 2) return true; // 192.0.2.0/24 TEST-NET-1
193
+ if (a === 192 && b === 168) return true; // 192.168.0.0/16 private
194
+ if (a === 198 && (b === 18 || b === 19)) return true; // 198.18.0.0/15 benchmarking
195
+ if (a === 198 && b === 51 && c === 100) return true; // 198.51.100.0/24 TEST-NET-2
196
+ if (a === 203 && b === 0 && c === 113) return true; // 203.0.113.0/24 TEST-NET-3
197
+ if (a >= 224) return true; // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved
198
+ return false;
199
+ }
200
+
201
+ /**
202
+ * Whether an IPv6 literal is something Anthropic could never reach.
203
+ *
204
+ * Stated as an allowlist, unlike its v4 counterpart, because v6 hands us one:
205
+ * globally routable unicast is `2000::/3` and nothing else is. Naming the
206
+ * unreachable blocks instead — loopback, ULA, link-local — reads fine and
207
+ * leaks, because the unreachable set is most of a 128-bit space and a list of
208
+ * it is never finished. Refusing everything outside `2000::/3` closes
209
+ * multicast, the discard prefix, the `::`-compressed reserved forms and every
210
+ * block IANA has not allocated yet, in one line that cannot fall behind.
211
+ *
212
+ * Takes the host WITH its brackets, the form `URL.hostname` returns.
213
+ */
214
+ function isPrivateIpv6(bracketed: string): boolean {
215
+ const addr = bracketed.slice(1, -1).toLowerCase();
216
+
217
+ /**
218
+ * IPv4-mapped (`::ffff:10.0.0.1`) — an IPv4 address wearing a v6 hat, and
219
+ * exactly as unreachable as the address it wraps.
220
+ *
221
+ * The readable dotted form never gets here: `new URL()` normalizes
222
+ * `[::ffff:10.0.0.1]` to `[::ffff:a00:1]`, so the v4 address has to be
223
+ * decoded back out of the last two hextets. The dotted branch is kept
224
+ * anyway for a raw string that never went through the parser.
225
+ */
226
+ if (addr.startsWith('::ffff:')) {
227
+ const tail = addr.slice('::ffff:'.length);
228
+ if (tail.includes('.')) return isDottedQuad(tail) ? isPrivateIpv4(tail) : true;
229
+ const [hi, lo] = tail.split(':').map((h) => Number.parseInt(h, 16));
230
+ // Anything else wearing an `::ffff:` prefix is a shape we cannot read —
231
+ // refuse rather than guess it is public.
232
+ if (tail.split(':').length !== 2 || Number.isNaN(hi!) || Number.isNaN(lo!)) return true;
233
+ return isPrivateIpv4([hi! >> 8, hi! & 0xff, lo! >> 8, lo! & 0xff].join('.'));
234
+ }
235
+
236
+ const parts = addr.split(':');
237
+ const first = Number.parseInt(parts[0] ?? '', 16);
238
+
239
+ /**
240
+ * Outside global unicast — so loopback, the unspecified address, ULA
241
+ * (fc00::/7), link-local (fe80::/10), multicast (ff00::/8) and the
242
+ * discard-only prefix (100::/64) all land here without needing a rule each.
243
+ *
244
+ * A first hextet we cannot read fails this test too, which is the right way
245
+ * round: `::2` splits to an empty leading field and parses as NaN, and an
246
+ * address we cannot parse must not be advertised as reachable. Nothing
247
+ * legitimate is caught by that — `2000::/3` never starts with elided zeros.
248
+ */
249
+ if (!(first >= 0x2000 && first <= 0x3fff)) return true;
250
+
251
+ /**
252
+ * Allocated inside `2000::/3`, still not somewhere you can deploy. The v4
253
+ * gate already refuses its documentation and benchmark ranges; these are the
254
+ * same ranges, and leaving them out is what let `2001:db8::1` read as public.
255
+ *
256
+ * `2001:db8::1` splits to ['2001','db8','','1'], but `2001::1` gives
257
+ * ['2001','','1'] — an empty field is elided zeros, so it reads as 0.
258
+ */
259
+ const second = parts[1] === '' ? 0 : Number.parseInt(parts[1] ?? '', 16);
260
+ if (Number.isNaN(second)) return true;
261
+ if (first === 0x2001 && second <= 0x01ff) return true; // 2001::/23 IETF protocol assignments
262
+ if (first === 0x2001 && second === 0x0db8) return true; // 2001:db8::/32 documentation (RFC 3849)
263
+ if (first === 0x3fff && second <= 0x0fff) return true; // 3fff::/20 documentation (RFC 9637)
264
+ return false;
265
+ }
266
+
267
+ /**
268
+ * What this deployment is called in someone's Claude connector list.
269
+ *
270
+ * The host is in it because there is no deployment-identity concept in this
271
+ * product, and something has to disambiguate: the public demo and a
272
+ * self-hosted instance are the same product at different addresses, and two
273
+ * identically-named connectors pointing at different servers is a list nobody
274
+ * can clean up. The product name is in it because a bare domain sitting
275
+ * between "Gmail" and "Google Drive" says where it is but not what it is.
276
+ *
277
+ * `host`, not `hostname`, so a non-default port survives — two instances on
278
+ * one machine are still telling apart.
279
+ */
280
+ export function connectorName(mcpUrl: string): string {
281
+ try {
282
+ return `Hexis — ${new URL(mcpUrl).host}`;
283
+ } catch {
284
+ return 'Hexis';
285
+ }
286
+ }
287
+
288
+ /** Anthropic's documented install-link target for a connector not in the directory. */
289
+ const CLAUDE_ADD_CONNECTOR = 'https://claude.ai/customize/connectors';
290
+
291
+ /**
292
+ * A link that opens claude.ai's "Add custom connector" dialog with the name
293
+ * and URL already filled in. It only prefills — the person still reviews and
294
+ * confirms, and Claude tells them the values came from an external link.
295
+ *
296
+ * Encoded with `encodeURIComponent` rather than `URLSearchParams`, which is
297
+ * the one place being explicit earns its keep: `URLSearchParams` serializes a
298
+ * space as `+`, and `+` means "space" only to a decoder that applies form
299
+ * rules. `%20` is unambiguous under both, and the connector name always
300
+ * contains spaces.
301
+ */
302
+ export function claudeInstallUrl(mcpUrl: string, name: string): string {
303
+ const params = [
304
+ 'modal=add-custom-connector',
305
+ `connectorName=${encodeURIComponent(name)}`,
306
+ `connectorUrl=${encodeURIComponent(mcpUrl)}`,
307
+ ].join('&');
308
+ return `${CLAUDE_ADD_CONNECTOR}?${params}`;
309
+ }
310
+
311
+ /* ------------------------------------------------------------------ *
312
+ * The snippets themselves. One builder per client, each taking the URL
313
+ * so no caller ever re-derives it, and an optional bearer token for the
314
+ * autonomous-agent variants that carry an external API key.
315
+ * ------------------------------------------------------------------ */
316
+
317
+ /**
318
+ * Escape a value for interpolation inside a double-quoted POSIX shell string.
319
+ * Backslash, `"`, `$` and backtick are the four characters the shell still
320
+ * reads there — a token carrying any of them would otherwise cut the pasted
321
+ * command short or expand into it.
322
+ */
323
+ function escapeForDoubleQuotes(value: string): string {
324
+ return value.replace(/[\\"$`]/g, (c) => `\\${c}`);
325
+ }
326
+
327
+ /** The `claude mcp add` one-liner, with the key appended when there is one. */
328
+ export function claudeCodeCommand(mcpUrl: string, bearer?: string): string {
329
+ const base = `claude mcp add --transport http knowledge-base ${mcpUrl}`;
330
+ return bearer ? `${base} --header "Authorization: Bearer ${escapeForDoubleQuotes(bearer)}"` : base;
331
+ }
332
+
333
+ /** The JSON block for clients that read their servers from a config file. */
334
+ export function jsonConfigSnippet(mcpUrl: string, bearer?: string): string {
335
+ return JSON.stringify(
336
+ {
337
+ mcpServers: {
338
+ 'knowledge-base': {
339
+ type: 'http',
340
+ url: mcpUrl,
341
+ ...(bearer ? { headers: { Authorization: `Bearer ${bearer}` } } : {}),
342
+ },
343
+ },
344
+ },
345
+ null,
346
+ 2,
347
+ );
348
+ }
349
+
350
+ /** Langdock wants the URL and the header spelled out as separate fields. */
351
+ export function langdockSnippet(mcpUrl: string, bearer: string): string {
352
+ return `URL: ${mcpUrl}\nHeader name: Authorization\nHeader value: Bearer ${bearer}`;
353
+ }
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Connecting an agent to this workspace over MCP — the endpoint, the snippets
3
+ * each client needs, and the one-click Claude install link.
4
+ *
5
+ * Import from this barrel, the same convention `shared/components` follows.
6
+ */
7
+
8
+ /*
9
+ * `resetMcpUrlForTests` is deliberately NOT re-exported. It mutates
10
+ * module-global state, and putting it on the public surface invites
11
+ * production code to import something that only makes sense in a test.
12
+ * Tests import it straight from `./connect-snippets`, as `test-setup.ts` does.
13
+ */
14
+ export {
15
+ canDeepLink,
16
+ claudeCodeCommand,
17
+ claudeInstallUrl,
18
+ configureMcpUrl,
19
+ connectorName,
20
+ jsonConfigSnippet,
21
+ langdockSnippet,
22
+ mcpEndpointUrl,
23
+ } from './connect-snippets';
24
+
25
+ export { ClaudeInstallLink } from './ClaudeInstallLink';
26
+ export { ConnectionInstructions } from './ConnectionInstructions';
27
+ export { CopyBlock } from './CopyBlock';
28
+ export { useCopyFeedback } from './useCopyFeedback';
@@ -0,0 +1,46 @@
1
+ import { useCallback, useEffect, useState } from 'react';
2
+
3
+ /**
4
+ * "Copied" affordance with a 1500ms auto-reset. Owns the timer + its teardown
5
+ * (so an unmounting page can't fire a stale setState), shared by the reveal
6
+ * modal and every CopyBlock. `copy(text)` writes to the clipboard and flags
7
+ * copied; a rejected write (insecure context / denied permission) leaves the
8
+ * textarea selectable for manual copy and shows no false "Copied".
9
+ *
10
+ * Its own file rather than sitting beside `CopyBlock`: a module that exports
11
+ * both a component and a plain function breaks React Fast Refresh, which
12
+ * lints as `react-refresh/only-export-components`.
13
+ */
14
+ export function useCopyFeedback(): { copied: boolean; copy: (text: string) => void } {
15
+ // A counter, not a boolean: `setState(true)` on an already-true boolean
16
+ // bails out of the render, so a second copy inside the 1500ms window would
17
+ // never restart the timer and its checkmark would vanish almost at once.
18
+ // Each success bumps the counter, which re-arms the effect below.
19
+ const [copyCount, setCopyCount] = useState(0);
20
+ useEffect(() => {
21
+ if (copyCount === 0) return;
22
+ const timerId = window.setTimeout(() => setCopyCount(0), 1500);
23
+ return () => window.clearTimeout(timerId);
24
+ }, [copyCount]);
25
+ const copy = useCallback((text: string) => {
26
+ /**
27
+ * `navigator.clipboard` is absent in an insecure context — which this app
28
+ * routinely runs in, since the default deployment is plain http on
29
+ * localhost. Reaching for `.writeText` there throws a TypeError
30
+ * SYNCHRONOUSLY, before any promise exists, so `void` swallows nothing and
31
+ * the click errors instead of failing quietly.
32
+ */
33
+ if (!navigator.clipboard?.writeText) {
34
+ setCopyCount(0);
35
+ return;
36
+ }
37
+ void navigator.clipboard
38
+ .writeText(text)
39
+ .then(() => setCopyCount((n) => n + 1))
40
+ // Clear rather than ignore: a failure inside the 1500ms window of an
41
+ // earlier success would otherwise leave the checkmark up, reporting that
42
+ // this copy worked when it did not.
43
+ .catch(() => setCopyCount(0));
44
+ }, []);
45
+ return { copied: copyCount > 0, copy };
46
+ }
package/src/test-setup.ts CHANGED
@@ -2,6 +2,10 @@ import '@testing-library/jest-dom/vitest';
2
2
  import { cleanup } from '@testing-library/react';
3
3
  import { afterEach, beforeEach } from 'vitest';
4
4
  import { configureBranchModel } from '@bevel-software/platform-shared';
5
+ // The pure module, NOT the `shared/mcp` barrel: this file runs before every
6
+ // test file, and the barrel would drag React components and their icon
7
+ // imports into the setup of suites that never touch them.
8
+ import { resetMcpUrlForTests } from './shared/mcp/connect-snippets';
5
9
 
6
10
  // The branch model is applied during boot now, not read from the environment
7
11
  // at import. In the browser that is `loadServerConfig()`; here it is this,
@@ -61,6 +65,13 @@ if (typeof window !== 'undefined' && window.localStorage !== globalThis.localSto
61
65
 
62
66
  beforeEach(() => {
63
67
  globalThis.localStorage?.clear?.();
68
+ /**
69
+ * The MCP endpoint is module-global, the way the branch model is. In the
70
+ * browser it is set once by `loadServerConfig()`; here nothing calls that,
71
+ * so tests start from the origin fallback and any suite that configures a
72
+ * real address cannot leak it into the next one.
73
+ */
74
+ resetMcpUrlForTests();
64
75
  });
65
76
 
66
77
  afterEach(() => {