@bevel-software/platform-core-frontend 0.7.5 → 0.9.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 (132) 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/core/registry.ts +16 -4
  9. package/src/css-side-effect-imports.d.ts +7 -7
  10. package/src/modules/access/__tests__/ManageAccessDialog.placement.test.tsx +1 -1
  11. package/src/modules/access/__tests__/ManageAccessDialog.test.tsx +5 -5
  12. package/src/modules/access/api.ts +5 -5
  13. package/src/modules/access/components/ManageAccessDialog.tsx +21 -20
  14. package/src/modules/admin/__tests__/AdminRolesPage.suggest.test.tsx +1 -1
  15. package/src/modules/admin/components/AdminRolesPage.tsx +1 -1
  16. package/src/modules/admin/state/admin.context.tsx +15 -0
  17. package/src/modules/change-requests/__tests__/useFileOnBranch.test.tsx +2 -2
  18. package/src/modules/change-requests/components/ChangeRequestDialog.tsx +1 -1
  19. package/src/modules/change-requests/hooks/useApplyChangeRequest.ts +1 -1
  20. package/src/modules/layout/__tests__/SidebarFrameResponsive.test.tsx +4 -4
  21. package/src/modules/layout/__tests__/SidebarToggle.test.tsx +4 -4
  22. package/src/modules/layout/__tests__/breakpoints.test.ts +1 -1
  23. package/src/modules/layout/components/SidebarFrame.tsx +2 -2
  24. package/src/modules/library/__tests__/{AddToGroupDialog.test.tsx → AddToPluginDialog.test.tsx} +34 -34
  25. package/src/modules/library/__tests__/LibraryCard.test.tsx +30 -11
  26. package/src/modules/library/__tests__/LibraryRoutes.test.tsx +84 -59
  27. package/src/modules/library/__tests__/LibrarySidebarMenu.test.tsx +51 -51
  28. package/src/modules/library/__tests__/{LockedGroupView.test.tsx → LockedPluginView.test.tsx} +33 -33
  29. package/src/modules/library/__tests__/McpServerSection.test.tsx +138 -0
  30. package/src/modules/library/__tests__/{NewGroupDialog.test.tsx → NewPluginDialog.test.tsx} +22 -22
  31. package/src/modules/library/__tests__/PersonalAddDialog.test.tsx +7 -7
  32. package/src/modules/library/__tests__/PluginExtras.test.tsx +131 -0
  33. package/src/modules/library/__tests__/{GroupJoinRequests.test.tsx → PluginJoinRequests.test.tsx} +24 -24
  34. package/src/modules/library/__tests__/{GroupPage.test.tsx → PluginPage.test.tsx} +197 -106
  35. package/src/modules/library/__tests__/PluginsIndexPage.test.tsx +363 -0
  36. package/src/modules/library/__tests__/{GroupsSidebar.contextmenu.test.tsx → PluginsSidebar.contextmenu.test.tsx} +32 -31
  37. package/src/modules/library/__tests__/{GroupsSidebar.locked.test.tsx → PluginsSidebar.locked.test.tsx} +29 -28
  38. package/src/modules/library/__tests__/PluginsSidebar.test.tsx +171 -0
  39. package/src/modules/library/__tests__/{GroupsSidebarMenu.test.tsx → PluginsSidebarMenu.test.tsx} +18 -18
  40. package/src/modules/library/__tests__/SkillPage.test.tsx +8 -8
  41. package/src/modules/library/__tests__/ToolConnectionSection.test.tsx +2 -2
  42. package/src/modules/library/__tests__/ToolPage.test.tsx +41 -12
  43. package/src/modules/library/__tests__/ToolSharePanel.test.tsx +1 -1
  44. package/src/modules/library/__tests__/WorkspaceItemRoute.test.tsx +57 -57
  45. package/src/modules/library/__tests__/auth-harness.tsx +4 -4
  46. package/src/modules/library/__tests__/library-data.test.ts +82 -0
  47. package/src/modules/library/__tests__/status.test.ts +19 -19
  48. package/src/modules/library/__tests__/tools.api.test.ts +70 -0
  49. package/src/modules/library/__tests__/useToolPage.test.tsx +4 -4
  50. package/src/modules/library/components/AccessRequestsBanner.tsx +8 -8
  51. package/src/modules/library/components/{AddToGroupDialog.tsx → AddToPluginDialog.tsx} +11 -11
  52. package/src/modules/library/components/ChangeRequestDock.tsx +1 -1
  53. package/src/modules/library/components/{DeleteGroupDialog.tsx → DeletePluginDialog.tsx} +9 -9
  54. package/src/modules/library/components/LibraryCard.tsx +26 -2
  55. package/src/modules/library/components/LibraryLayout.tsx +80 -71
  56. package/src/modules/library/components/LibraryPage.tsx +8 -8
  57. package/src/modules/library/components/LockGlyph.tsx +1 -1
  58. package/src/modules/library/components/{LockedGroupView.tsx → LockedPluginView.tsx} +35 -35
  59. package/src/modules/library/components/{ManagedGroupRequests.tsx → ManagedPluginRequests.tsx} +13 -13
  60. package/src/modules/library/components/{NewGroupDialog.tsx → NewPluginDialog.tsx} +24 -24
  61. package/src/modules/library/components/NewSkillPanel.tsx +23 -5
  62. package/src/modules/library/components/PageActions.tsx +34 -11
  63. package/src/modules/library/components/PersonalAddDialog.tsx +5 -5
  64. package/src/modules/library/components/{PersonalGroupPage.tsx → PersonalPluginPage.tsx} +29 -19
  65. package/src/modules/library/components/PluginExtras.tsx +195 -0
  66. package/src/modules/library/components/{GroupIndexRow.tsx → PluginIndexRow.tsx} +6 -6
  67. package/src/modules/library/components/PluginJoinRequests.tsx +77 -0
  68. package/src/modules/library/components/{GroupPage.tsx → PluginPage.tsx} +112 -72
  69. package/src/modules/library/components/{GroupsIndexPage.tsx → PluginsIndexPage.tsx} +91 -48
  70. package/src/modules/library/components/{GroupsSidebar.tsx → PluginsSidebar.tsx} +105 -55
  71. package/src/modules/library/components/{GroupsSidebarMenu.tsx → PluginsSidebarMenu.tsx} +15 -15
  72. package/src/modules/library/components/{group-page-parts.tsx → plugin-page-parts.tsx} +218 -27
  73. package/src/modules/library/components/skill-page/SkillPage.tsx +12 -12
  74. package/src/modules/library/components/tool-page/McpServerSection.tsx +380 -0
  75. package/src/modules/library/components/tool-page/ToolPage.tsx +22 -5
  76. package/src/modules/library/hooks/useJoinRequests.ts +8 -8
  77. package/src/modules/library/routes/LibraryRoutes.tsx +32 -19
  78. package/src/modules/library/routes/WorkspaceItemRoute.tsx +24 -24
  79. package/src/modules/library/routes/library-paths.ts +36 -36
  80. package/src/modules/library/services/library.api.ts +9 -9
  81. package/src/modules/library/services/{groups.api.ts → plugins.api.ts} +43 -43
  82. package/src/modules/library/services/tools.api.ts +54 -0
  83. package/src/modules/library/state/library-data.tsx +67 -46
  84. package/src/modules/library/utils/names.ts +1 -1
  85. package/src/modules/library/utils/{personal-group.ts → personal-plugin.ts} +8 -8
  86. package/src/modules/library/utils/{group-summary.ts → plugin-summary.ts} +14 -14
  87. package/src/modules/library/utils/status.ts +17 -17
  88. package/src/modules/onboarding/__tests__/creator-welcome.test.tsx +318 -0
  89. package/src/modules/onboarding/__tests__/onboarding.test.tsx +86 -8
  90. package/src/modules/onboarding/agent-clients.ts +18 -14
  91. package/src/modules/onboarding/components/CreatorWelcomePage.tsx +143 -0
  92. package/src/modules/onboarding/components/WelcomePage.tsx +30 -22
  93. package/src/modules/onboarding/components/WelcomeRoute.tsx +57 -0
  94. package/src/modules/onboarding/welcome-state.ts +36 -0
  95. package/src/modules/review/components/MarkdownDiffViewer.tsx +1 -1
  96. package/src/modules/review/components/ReviewPanel.tsx +11 -11
  97. package/src/modules/review/components/__tests__/{isGroupItemPath.test.ts → isPluginItemPath.test.ts} +24 -24
  98. package/src/modules/secrets-vault/components/ToolSecretsPanel.tsx +3 -3
  99. package/src/modules/secrets-vault/components/__tests__/SecretsPage.test.tsx +1 -1
  100. package/src/modules/settings/components/SettingsLayout.tsx +1 -1
  101. package/src/modules/settings/components/SettingsNav.tsx +5 -5
  102. package/src/modules/setup/__tests__/setup.test.tsx +203 -0
  103. package/src/modules/setup/components/SetupScreen.tsx +235 -68
  104. package/src/modules/toolbar/components/ExternalAgentAccessPage.tsx +29 -107
  105. package/src/modules/toolbar/components/__tests__/AppSwitcher.test.tsx +1 -1
  106. package/src/modules/toolbar/components/__tests__/ExternalAgentAccessPage.test.tsx +228 -0
  107. package/src/modules/toolbar/components/__tests__/Toolbar.test.tsx +3 -3
  108. package/src/modules/workspace/components/FileExplorer.tsx +12 -12
  109. package/src/modules/workspace/components/FileRoute.tsx +8 -1
  110. package/src/modules/workspace/components/FileViewer.tsx +95 -38
  111. package/src/modules/workspace/components/__tests__/FileExplorer.test.tsx +14 -14
  112. package/src/modules/workspace/components/__tests__/FileRoute.test.tsx +20 -0
  113. package/src/modules/workspace/components/__tests__/FileViewer.test.tsx +227 -18
  114. package/src/modules/workspace/components/renderers/ToolRenderer.tsx +7 -2
  115. package/src/modules/workspace/routing/__tests__/kb-routes.test.tsx +25 -0
  116. package/src/modules/workspace/routing/kb-routes.ts +23 -1
  117. package/src/modules/workspace/utils/__tests__/diff.test.ts +1 -1
  118. package/src/modules/workspace/utils/fileTree.ts +54 -3
  119. package/src/shared/components/Surface.tsx +15 -0
  120. package/src/shared/mcp/ClaudeInstallLink.tsx +88 -0
  121. package/src/shared/mcp/ConnectionInstructions.tsx +51 -0
  122. package/src/shared/mcp/CopyBlock.tsx +42 -0
  123. package/src/shared/mcp/__tests__/ClaudeInstallLink.test.tsx +40 -0
  124. package/src/shared/mcp/__tests__/connect-snippets.test.ts +431 -0
  125. package/src/shared/mcp/__tests__/useCopyFeedback.test.ts +112 -0
  126. package/src/shared/mcp/connect-snippets.ts +353 -0
  127. package/src/shared/mcp/index.ts +28 -0
  128. package/src/shared/mcp/useCopyFeedback.ts +46 -0
  129. package/src/test-setup.ts +11 -0
  130. package/src/modules/library/__tests__/GroupsIndexPage.test.tsx +0 -283
  131. package/src/modules/library/__tests__/GroupsSidebar.test.tsx +0 -142
  132. package/src/modules/library/components/GroupJoinRequests.tsx +0 -56
@@ -0,0 +1,318 @@
1
+ import { beforeEach, describe, expect, it, vi } from 'vitest';
2
+ import { render, renderHook, screen, waitFor } from '@testing-library/react';
3
+ import userEvent from '@testing-library/user-event';
4
+ import { MemoryRouter, Route, Routes, useLocation } from 'react-router-dom';
5
+ import type { ReactNode } from 'react';
6
+ import { AdminContext, type AdminContextValue } from '../../admin/state/admin.context';
7
+ import { AuthContext } from '../../auth/state/auth.context';
8
+ import { authValue } from '../../library/__tests__/auth-harness';
9
+ import { LibraryContext } from '../../library/state/library-context';
10
+ import type { LibraryContextValue } from '../../library/state/library-data';
11
+ import { LibraryToastProvider } from '../../library/state/toast';
12
+ import { setSidebarCollapsed, useSidebar } from '../../layout/state/sidebar';
13
+ import { WelcomeRoute } from '../components/WelcomeRoute';
14
+ import { WELCOME_PATH } from '../paths';
15
+ import { resetOnboardingForTests } from '../state/onboarding';
16
+
17
+ const serviceMocks = vi.hoisted(() => ({
18
+ createPlugin: vi.fn(),
19
+ createEmptySkill: vi.fn(),
20
+ }));
21
+
22
+ vi.mock('../../library/services/plugins.api', async (importOriginal) => {
23
+ const actual = await importOriginal<typeof import('../../library/services/plugins.api')>();
24
+ return { ...actual, createPlugin: serviceMocks.createPlugin };
25
+ });
26
+
27
+ vi.mock('../../library/services/library.api', async (importOriginal) => {
28
+ const actual = await importOriginal<typeof import('../../library/services/library.api')>();
29
+ return { ...actual, createEmptySkill: serviceMocks.createEmptySkill };
30
+ });
31
+
32
+ function library(over: Partial<LibraryContextValue> = {}): LibraryContextValue {
33
+ return {
34
+ loading: false,
35
+ error: null,
36
+ skills: [],
37
+ pendingSkills: [],
38
+ tools: [],
39
+ ownedSkills: new Set(),
40
+ allowedToolsBySkill: new Map(),
41
+ crs: [],
42
+ myCrNumbers: new Set(),
43
+ reload: vi.fn(),
44
+ items: [],
45
+ pluginSummaries: [],
46
+ pluginsLoading: false,
47
+ pluginsError: null,
48
+ reloadPlugins: vi.fn(),
49
+ ...over,
50
+ };
51
+ }
52
+
53
+ function admin(over: Partial<AdminContextValue> = {}): AdminContextValue {
54
+ return {
55
+ isAdmin: true,
56
+ isAdminLoading: false,
57
+ unreadCount: 0,
58
+ lastSeen: null,
59
+ markSeen: vi.fn(),
60
+ refresh: vi.fn(),
61
+ rolesConfigCorrupted: false,
62
+ rolesConfigErrors: [],
63
+ runRolesRecovery: vi.fn(),
64
+ ...over,
65
+ };
66
+ }
67
+
68
+ function LocationProbe() {
69
+ return <div aria-label="pathname">{useLocation().pathname}</div>;
70
+ }
71
+
72
+ function providers(
73
+ children: ReactNode,
74
+ options: { admin?: Partial<AdminContextValue>; library?: Partial<LibraryContextValue> } = {},
75
+ ) {
76
+ return (
77
+ <AuthContext.Provider
78
+ value={authValue({
79
+ user: {
80
+ id: 'u1',
81
+ email: 'juan@bevel.software',
82
+ name: 'Juan Viera',
83
+ onboardingDone: false,
84
+ },
85
+ })}
86
+ >
87
+ <AdminContext.Provider value={admin(options.admin)}>
88
+ <LibraryContext.Provider value={library(options.library)}>
89
+ <LibraryToastProvider>{children}</LibraryToastProvider>
90
+ </LibraryContext.Provider>
91
+ </AdminContext.Provider>
92
+ </AuthContext.Provider>
93
+ );
94
+ }
95
+
96
+ interface WelcomeOptions {
97
+ greeted?: boolean;
98
+ /** Overrides the greeting arrival's route state — e.g. to carry `returnTo`. */
99
+ routeState?: Record<string, unknown>;
100
+ admin?: Partial<AdminContextValue>;
101
+ library?: Partial<LibraryContextValue>;
102
+ }
103
+
104
+ /**
105
+ * The whole tree, as one builder — so a test that re-renders with different
106
+ * options reuses the exact router + provider composition instead of
107
+ * hand-assembling a second copy that can drift from this one.
108
+ */
109
+ function welcomeUi(options: WelcomeOptions = {}) {
110
+ const entry = options.greeted === false
111
+ ? WELCOME_PATH
112
+ : { pathname: WELCOME_PATH, state: options.routeState ?? { greeting: true } };
113
+
114
+ return (
115
+ <MemoryRouter initialEntries={[entry]}>
116
+ {providers(
117
+ <>
118
+ <Routes>
119
+ <Route path={WELCOME_PATH} element={<WelcomeRoute />} />
120
+ <Route path="/skills-and-tools/plugins/:plugin" element={<div>plugin page</div>} />
121
+ <Route path="/skills-and-tools/skills/:skill" element={<div>skill page</div>} />
122
+ </Routes>
123
+ <LocationProbe />
124
+ </>,
125
+ options,
126
+ )}
127
+ </MemoryRouter>
128
+ );
129
+ }
130
+
131
+ function renderWelcome(options: WelcomeOptions = {}) {
132
+ return render(welcomeUi(options));
133
+ }
134
+
135
+ beforeEach(() => {
136
+ resetOnboardingForTests();
137
+ setSidebarCollapsed(false, true);
138
+ serviceMocks.createPlugin.mockReset();
139
+ serviceMocks.createPlugin.mockResolvedValue({ folder: 'Design' });
140
+ serviceMocks.createEmptySkill.mockReset();
141
+ serviceMocks.createEmptySkill.mockResolvedValue({
142
+ repoRelativePath: 'Plugins/personal-u1/weekly-report/SKILL.md',
143
+ workspacePath: 'knowledge-base/Plugins/personal-u1/weekly-report/SKILL.md',
144
+ branch: 'dev',
145
+ direct: true,
146
+ });
147
+ });
148
+
149
+ describe('creator welcome routing', () => {
150
+ it('welcomes an admin to build a truly empty library', () => {
151
+ renderWelcome();
152
+
153
+ expect(screen.getByRole('heading', { name: 'Welcome, Juan' })).toBeInTheDocument();
154
+ expect(screen.getByText(/Build the shared library/)).toBeInTheDocument();
155
+ expect(screen.getByRole('button', { name: 'Create a plugin' })).toBeInTheDocument();
156
+ expect(screen.getByRole('button', { name: 'Create a skill' })).toBeInTheDocument();
157
+ expect(screen.queryByRole('radiogroup', { name: 'Your agent' })).toBeNull();
158
+ });
159
+
160
+ it('keeps the external-agent welcome for non-admin users', () => {
161
+ renderWelcome({ admin: { isAdmin: false } });
162
+
163
+ expect(screen.getByRole('radiogroup', { name: 'Your agent' })).toBeInTheDocument();
164
+ expect(screen.queryByRole('button', { name: 'Create a plugin' })).toBeNull();
165
+ });
166
+
167
+ it('keeps the external-agent welcome when the admin already has content', () => {
168
+ renderWelcome({
169
+ library: {
170
+ items: [
171
+ {
172
+ kind: 'skill',
173
+ id: 'roadmap',
174
+ name: 'roadmap',
175
+ description: 'Keeps the roadmap current.',
176
+ owned: true,
177
+ status: { state: 'ok', text: 'Ready' },
178
+ plugin: null,
179
+ path: 'Skills/roadmap',
180
+ },
181
+ ],
182
+ },
183
+ });
184
+
185
+ expect(screen.getByRole('radiogroup', { name: 'Your agent' })).toBeInTheDocument();
186
+ expect(screen.queryByRole('button', { name: 'Create a plugin' })).toBeNull();
187
+ });
188
+
189
+ it('does not mistake loading or failed plugin data for an empty library', () => {
190
+ // While the ADMIN verdict is unknown the hold says nothing about a
191
+ // library — the reader may be headed for the agent welcome, where theirs
192
+ // is beside the point.
193
+ const { rerender } = renderWelcome({ admin: { isAdminLoading: true } });
194
+ expect(screen.getByText('One moment…')).toBeInTheDocument();
195
+
196
+ rerender(welcomeUi({ library: { pluginsError: "Couldn't load plugins." } }));
197
+
198
+ expect(screen.getByRole('radiogroup', { name: 'Your agent' })).toBeInTheDocument();
199
+ });
200
+
201
+ it("names the wait truthfully once the verdict says admin — it IS their library loading", () => {
202
+ renderWelcome({ library: { loading: true } });
203
+ expect(screen.getByText('Preparing your library…')).toBeInTheDocument();
204
+ });
205
+
206
+ it('keeps a carried deep link out of the creator welcome', () => {
207
+ // Only `WelcomePage` has the exit that honors `returnTo`. An empty-library
208
+ // admin would otherwise be routed to the creator page — and lose the page
209
+ // their SSO round-trip was carrying them to.
210
+ renderWelcome({
211
+ routeState: {
212
+ greeting: true,
213
+ returnTo: '/workspace/main/knowledge-base/KnowledgeBase/Start here.md',
214
+ },
215
+ });
216
+ expect(screen.getByRole('radiogroup', { name: 'Your agent' })).toBeInTheDocument();
217
+ expect(screen.getByRole('button', { name: /Continue to your link/ })).toBeInTheDocument();
218
+ expect(screen.queryByText(/Build the shared library/)).toBeNull();
219
+ });
220
+
221
+ it('uses the external-agent welcome for later visits from its reminder', () => {
222
+ renderWelcome({ greeted: false });
223
+
224
+ expect(screen.getByRole('radiogroup', { name: 'Your agent' })).toBeInTheDocument();
225
+ expect(screen.queryByRole('button', { name: 'Create a plugin' })).toBeNull();
226
+ });
227
+
228
+ it('collapses the sidebar before the creator welcome is shown', () => {
229
+ renderWelcome();
230
+ expect(renderHook(() => useSidebar()).result.current).toMatchObject({
231
+ collapsed: true,
232
+ instant: true,
233
+ });
234
+ });
235
+ });
236
+
237
+ describe('creator welcome actions', () => {
238
+ it('creates a plugin through the shared dialog and refreshes both indexes', async () => {
239
+ const data = library();
240
+ const user = userEvent.setup();
241
+ renderWelcome({ library: data });
242
+
243
+ await user.click(screen.getByRole('button', { name: 'Create a plugin' }));
244
+ await user.type(screen.getByRole('textbox', { name: 'Plugin name' }), 'Design');
245
+ await user.click(screen.getByRole('button', { name: 'Create plugin' }));
246
+
247
+ await waitFor(() => expect(serviceMocks.createPlugin).toHaveBeenCalledWith('Design'));
248
+ expect(data.reload).toHaveBeenCalledOnce();
249
+ expect(data.reloadPlugins).toHaveBeenCalledOnce();
250
+ expect(screen.getByLabelText('pathname')).toHaveTextContent(
251
+ '/skills-and-tools/plugins/Design',
252
+ );
253
+ });
254
+
255
+ it('creates a personal skill and opens its skill page', async () => {
256
+ const data = library();
257
+ const user = userEvent.setup();
258
+ renderWelcome({ library: data });
259
+
260
+ await user.click(screen.getByRole('button', { name: 'Create a skill' }));
261
+ expect(screen.getByRole('dialog', { name: 'New skill' })).toBeInTheDocument();
262
+ await user.type(screen.getByRole('textbox', { name: 'Skill name' }), 'weekly-report');
263
+ await user.click(screen.getByRole('button', { name: 'Create' }));
264
+
265
+ await waitFor(() =>
266
+ expect(serviceMocks.createEmptySkill).toHaveBeenCalledWith({
267
+ personal: true,
268
+ name: 'weekly-report',
269
+ userEmail: 'juan@bevel.software',
270
+ userName: 'Juan Viera',
271
+ }),
272
+ );
273
+ expect(data.reload).toHaveBeenCalledOnce();
274
+ // The skill's canonical address is its workspace FILE url, not the legacy
275
+ // `skills/:name` route — that one survives only as a redirect. The dialog
276
+ // owns this navigation, so the welcome page inherits whatever the rest of
277
+ // the Library does, which is the point of routing through it.
278
+ expect(screen.getByLabelText('pathname')).toHaveTextContent(
279
+ '/workspace/target-company-state/knowledge-base/Plugins/personal-u1/weekly-report/SKILL.md',
280
+ );
281
+ });
282
+
283
+ it('holds the New skill dialog open while creation is pending', async () => {
284
+ // A create that has started finishes even if the dialog goes away — and
285
+ // then NAVIGATES. Every way out must be barred until it settles, or a
286
+ // dismissal turns into being carried to a page you closed the door on.
287
+ let release!: () => void;
288
+ serviceMocks.createEmptySkill.mockImplementation(
289
+ () =>
290
+ new Promise((resolve) => {
291
+ release = () =>
292
+ resolve({
293
+ repoRelativePath: 'Plugins/personal-u1/weekly-report/SKILL.md',
294
+ workspacePath: 'knowledge-base/Plugins/personal-u1/weekly-report/SKILL.md',
295
+ branch: 'dev',
296
+ direct: true,
297
+ });
298
+ }),
299
+ );
300
+ const user = userEvent.setup();
301
+ renderWelcome();
302
+
303
+ await user.click(screen.getByRole('button', { name: 'Create a skill' }));
304
+ await user.type(screen.getByRole('textbox', { name: 'Skill name' }), 'weekly-report');
305
+ await user.click(screen.getByRole('button', { name: 'Create' }));
306
+
307
+ for (const door of screen.getAllByRole('button', { name: /close/i })) {
308
+ expect(door).toBeDisabled();
309
+ }
310
+
311
+ release();
312
+ await waitFor(() =>
313
+ expect(screen.getByLabelText('pathname')).toHaveTextContent(
314
+ '/workspace/target-company-state/knowledge-base/Plugins/personal-u1/weekly-report/SKILL.md',
315
+ ),
316
+ );
317
+ });
318
+ });
@@ -12,6 +12,7 @@ import { RootLanding } from '../components/RootLanding';
12
12
  import { POST_LOGIN_REDIRECT_KEY } from '../../auth/services/sso';
13
13
  import { WELCOME_PATH } from '../paths';
14
14
  import { resetOnboardingForTests } from '../state/onboarding';
15
+ import { configureMcpUrl } from '../../../shared/mcp';
15
16
  import { setSidebarCollapsed, useSidebar } from '../../layout/state/sidebar';
16
17
 
17
18
  /**
@@ -214,7 +215,7 @@ describe('WelcomePage', () => {
214
215
  <Routes>
215
216
  <Route path={WELCOME_PATH} element={<WelcomePage />} />
216
217
  <Route path="/skills-and-tools" element={<div>library</div>} />
217
- <Route path="/skills-and-tools/yours" element={<div>your group</div>} />
218
+ <Route path="/skills-and-tools/yours" element={<div>your plugin</div>} />
218
219
  </Routes>,
219
220
  auth,
220
221
  route,
@@ -287,7 +288,7 @@ describe('WelcomePage', () => {
287
288
  expect(sidebarState()).toMatchObject({ collapsed: true, instant: true });
288
289
  });
289
290
 
290
- it('leaves it collapsed when you go to your own group', async () => {
291
+ it('leaves it collapsed when you go to your own plugin', async () => {
291
292
  setSidebarCollapsed(false);
292
293
  mountPage(newUser(), greeted);
293
294
  await userEvent.click(screen.getByRole('button', { name: /Go to your skills/ }));
@@ -343,6 +344,83 @@ describe('WelcomePage', () => {
343
344
  expect(screen.getByText(/mcpServers/)).toBeInTheDocument();
344
345
  });
345
346
 
347
+ /**
348
+ * One click instead of a menu path. It is Claude-only because Claude is the
349
+ * only client with a documented install link, and it appears only when
350
+ * Anthropic could actually reach this deployment — see `canDeepLink`. The
351
+ * copy block stays either way; it is the route that always works.
352
+ */
353
+ describe('the Add to Claude link', () => {
354
+ it('offers one-click connect on a reachable deployment', () => {
355
+ configureMcpUrl('https://kb.acme.com/api/mcp');
356
+ mountPage();
357
+ const link = screen.getByRole('link', { name: 'Add to Claude' });
358
+ const href = new URL(link.getAttribute('href')!);
359
+ expect(href.origin + href.pathname).toBe('https://claude.ai/customize/connectors');
360
+ expect(href.searchParams.get('connectorUrl')).toBe('https://kb.acme.com/api/mcp');
361
+ expect(href.searchParams.get('connectorName')).toBe('Hexis — kb.acme.com');
362
+ });
363
+
364
+ /**
365
+ * The default install: `PUBLIC_BACKEND_URL` unset means localhost, which
366
+ * claude.ai cannot reach. A dead button on the first screen a self-hoster
367
+ * sees reads as a broken product.
368
+ */
369
+ it('offers nothing to click on a localhost deployment', () => {
370
+ configureMcpUrl('http://localhost:3001/api/mcp');
371
+ mountPage();
372
+ expect(screen.queryByRole('link', { name: 'Add to Claude' })).toBeNull();
373
+ // …and the route that always works is still there.
374
+ expect(screen.getByText('http://localhost:3001/api/mcp')).toBeInTheDocument();
375
+ });
376
+
377
+ /**
378
+ * No `PUBLIC_BACKEND_URL` hint on THIS surface. The reader is a new
379
+ * employee who cannot change deployment config; naming an env var at them
380
+ * is noise. The settings page, whose reader plausibly can, says it there.
381
+ */
382
+ it('does not lecture a new employee about deployment config', () => {
383
+ configureMcpUrl('http://localhost:3001/api/mcp');
384
+ mountPage();
385
+ expect(screen.queryByText(/PUBLIC_BACKEND_URL/)).toBeNull();
386
+ });
387
+
388
+ it('belongs to Claude alone', async () => {
389
+ configureMcpUrl('https://kb.acme.com/api/mcp');
390
+ mountPage();
391
+ expect(screen.getByRole('link', { name: 'Add to Claude' })).toBeInTheDocument();
392
+ await userEvent.click(screen.getByRole('radio', { name: 'ChatGPT' }));
393
+ expect(screen.queryByRole('link', { name: 'Add to Claude' })).toBeNull();
394
+ await userEvent.click(screen.getByRole('radio', { name: 'Cursor & Others' }));
395
+ expect(screen.queryByRole('link', { name: 'Add to Claude' })).toBeNull();
396
+ });
397
+
398
+ // Opening claude.ai must not hand it a handle on this window.
399
+ it('opens in a new tab safely', () => {
400
+ configureMcpUrl('https://kb.acme.com/api/mcp');
401
+ mountPage();
402
+ const link = screen.getByRole('link', { name: 'Add to Claude' });
403
+ expect(link).toHaveAttribute('target', '_blank');
404
+ expect(link).toHaveAttribute('rel', 'noopener noreferrer');
405
+ });
406
+
407
+ /**
408
+ * The whole point of the canonical URL: what the button hands Claude and
409
+ * what the copy block shows a human must be the same string, or one of
410
+ * them is lying.
411
+ */
412
+ it('hands Claude exactly the URL the copy block shows', () => {
413
+ configureMcpUrl('https://kb.acme.com/api/mcp');
414
+ mountPage();
415
+ const href = new URL(
416
+ screen.getByRole('link', { name: 'Add to Claude' }).getAttribute('href')!,
417
+ );
418
+ expect(href.searchParams.get('connectorUrl')).toBe(
419
+ screen.getByText(/\/api\/mcp$/).textContent,
420
+ );
421
+ });
422
+ });
423
+
346
424
  it('copies the visible snippet without concluding anything', async () => {
347
425
  const writeText = stubClipboard();
348
426
  mountPage();
@@ -354,9 +432,9 @@ describe('WelcomePage', () => {
354
432
  });
355
433
 
356
434
  // Exact, not a substring: `/skills-and-tools` is a PREFIX of the personal
357
- // group's path, so a loose match would pass even if Done dropped someone in
435
+ // plugin's path, so a loose match would pass even if Done dropped someone in
358
436
  // the whole company's catalog instead of their own shelf.
359
- it('Done concludes: server write + landing in your own group', async () => {
437
+ it('Done concludes: server write + landing in your own plugin', async () => {
360
438
  mountPage();
361
439
  await userEvent.click(screen.getByRole('button', { name: 'Done' }));
362
440
  expect(authFetchMock).toHaveBeenCalledWith(
@@ -397,7 +475,7 @@ describe('WelcomePage', () => {
397
475
 
398
476
  /**
399
477
  * `role="radiogroup"` is a promise about the keyboard, not just a label for
400
- * a screen reader: arrows select, and selection follows focus. The group
478
+ * a screen reader: arrows select, and selection follows focus. The plugin
401
479
  * wraps, because three options in a row have no edge worth stopping at.
402
480
  */
403
481
  it('drives the picker with the arrow keys, wrapping at both ends', async () => {
@@ -429,9 +507,9 @@ describe('WelcomePage', () => {
429
507
  ]);
430
508
  });
431
509
 
432
- // Into the person's OWN group, not the whole catalog — the same place the
510
+ // Into the person's OWN plugin, not the whole catalog — the same place the
433
511
  // sidebar's personal row goes.
434
- it('the skip link leaves for your own group, without concluding', async () => {
512
+ it('the skip link leaves for your own plugin, without concluding', async () => {
435
513
  mountPage();
436
514
  await userEvent.click(screen.getByRole('button', { name: /Go to your skills/ }));
437
515
  expect(authFetchMock).not.toHaveBeenCalled();
@@ -478,7 +556,7 @@ describe('WelcomePage', () => {
478
556
  <AppRegistryContext.Provider value={{ ...EMPTY_REGISTRY, welcomeExit }}>
479
557
  <Routes>
480
558
  <Route path={WELCOME_PATH} element={<WelcomePage />} />
481
- <Route path="/skills-and-tools/yours" element={<div>your group</div>} />
559
+ <Route path="/skills-and-tools/yours" element={<div>your plugin</div>} />
482
560
  <Route path="/workspace" element={<div>knowledge</div>} />
483
561
  </Routes>
484
562
  </AppRegistryContext.Provider>,
@@ -1,12 +1,22 @@
1
+ import { jsonConfigSnippet } from '../../shared/mcp';
2
+
1
3
  /**
2
4
  * The three ways an agent connects, named by PRODUCT rather than surface —
3
5
  * someone knows which assistant they use before they know which build of it
4
6
  * they are in (prototype `AGENT_CLIENTS`).
5
7
  *
6
- * The endpoint is derived from the page's own origin, exactly as the
7
- * External agent access page derives it (`ExternalAgentAccessPage.tsx`), so
8
- * the welcome page and the settings page can never hand out different URLs.
9
- * Passed in rather than read from `window` here, so tests can pin it.
8
+ * This file is now the welcome page's PICKER and nothing else: which clients
9
+ * to offer, what to call them, and how to say where the snippet goes. The
10
+ * snippets themselves, and the endpoint they are built from, live in
11
+ * `shared/mcp` — which is what makes the welcome page and the External agent
12
+ * access page agree.
13
+ *
14
+ * They did not, before. The docstring here used to claim the two surfaces
15
+ * "can never hand out different URLs" because the settings page derived the
16
+ * endpoint "exactly as" this file did. It never imported this file. It
17
+ * hand-built the same address in six places, and the two agreed by convention
18
+ * rather than by construction — which held only as long as nobody edited
19
+ * either one.
10
20
  */
11
21
 
12
22
  export interface AgentClient {
@@ -28,21 +38,15 @@ export const AGENT_CLIENTS: AgentClient[] = [
28
38
  {
29
39
  id: 'chatgpt',
30
40
  label: 'ChatGPT',
31
- hint: 'Settings → Connectors → Create, then paste this.',
41
+ // Developer mode first: it is off by default, and every "Create" button
42
+ // someone hunts for is behind it.
43
+ hint: 'Settings → Apps & Connectors → Advanced → turn on Developer mode, then Create and paste this.',
32
44
  snip: (url) => url,
33
45
  },
34
46
  {
35
47
  id: 'other',
36
48
  label: 'Cursor & Others',
37
49
  hint: 'For clients that read their servers from a JSON config, like Cursor, Windsurf and Cline.',
38
- snip: (url) =>
39
- JSON.stringify({ mcpServers: { 'knowledge-base': { type: 'http', url } } }, null, 2),
50
+ snip: (url) => jsonConfigSnippet(url),
40
51
  },
41
52
  ];
42
-
43
- /**
44
- * The MCP endpoint for a given page origin — the one URL every snippet above
45
- * is built from. Derived rather than configured, so a deployment on any host
46
- * hands out its own address without anyone remembering to update a constant.
47
- */
48
- export const mcpUrlFromOrigin = (origin: string): string => `${origin}/api/mcp`;
@@ -0,0 +1,143 @@
1
+ import { useEffect, useMemo, useState } from 'react';
2
+ import { Sparkles, Users } from 'lucide-react';
3
+ import { Button, Dialog, Surface } from '../../../shared/components';
4
+ import { useAuth } from '../../auth/state/auth.context';
5
+ import { NewPluginDialog } from '../../library/components/NewPluginDialog';
6
+ import { NewSkillPanel } from '../../library/components/NewSkillPanel';
7
+ import { useLibrary } from '../../library/state/library-data';
8
+ import { displayFirstName } from '../../library/utils/personal-plugin';
9
+ import { useOnboarding } from '../state/onboarding';
10
+
11
+ /**
12
+ * The first useful screen in an empty deployment.
13
+ *
14
+ * A regular account needs to connect an agent before the library becomes
15
+ * useful. The first admin has a different job: make the shared structure that
16
+ * everyone else will find. This page offers the two smallest real beginnings,
17
+ * using the same plugin and skill creation flows available everywhere else.
18
+ */
19
+ export function CreatorWelcomePage() {
20
+ const { user } = useAuth();
21
+ const onboarding = useOnboarding();
22
+ const data = useLibrary();
23
+ const [newPluginOpen, setNewPluginOpen] = useState(false);
24
+ const [newSkillOpen, setNewSkillOpen] = useState(false);
25
+ /**
26
+ * The skill panel's in-flight state, lifted. A create that has started
27
+ * finishes even if the dialog goes away — and then navigates. Holding the
28
+ * dialog's close doors shut while it runs (`Dialog.busy` + the footer
29
+ * button) is what keeps "dismiss" from turning into "get carried to a page
30
+ * you closed the door on".
31
+ */
32
+ const [newSkillBusy, setNewSkillBusy] = useState(false);
33
+
34
+ const { markWelcomed } = onboarding;
35
+ useEffect(() => {
36
+ markWelcomed();
37
+ // eslint-disable-next-line react-hooks/exhaustive-deps -- one idempotent welcome record per mount
38
+ }, []);
39
+
40
+ const pluginNames = useMemo(
41
+ () => [
42
+ ...new Set([
43
+ ...data.pluginSummaries.map((plugin) => plugin.name),
44
+ ...data.items.flatMap((item) => (item.plugin ? [item.plugin] : [])),
45
+ ]),
46
+ ],
47
+ [data.pluginSummaries, data.items],
48
+ );
49
+ const skillNames = useMemo(
50
+ () => data.items.filter((item) => item.kind === 'skill').map((item) => item.name),
51
+ [data.items],
52
+ );
53
+ const firstName = displayFirstName(user?.name) || 'there';
54
+
55
+ return (
56
+ <div className="mx-auto mt-[9vh] max-w-[580px] pb-14">
57
+ <h1 className="text-display font-bold">Welcome, {firstName}</h1>
58
+ <p className="mt-3 max-w-[54ch] text-lede text-ink-muted">
59
+ Build the shared library your team and AI agents work from. Start with a plugin for a
60
+ team or project, or create a skill in your own space.
61
+ </p>
62
+
63
+ <div className="mt-9 text-label uppercase text-ink-faint">Choose where to start</div>
64
+ <div className="mt-2.5 grid gap-3 sm:grid-cols-2">
65
+ <Surface as="section" elevation="none" padded className="flex min-h-48 flex-col">
66
+ <Users size={19} className="text-accent" aria-hidden="true" />
67
+ <h2 className="mt-3 text-strong font-semibold text-ink">Create a plugin</h2>
68
+ <p className="mt-1 text-ui text-ink-muted">
69
+ Organize skills and tools for a team, then invite the people who need them.
70
+ </p>
71
+ <Button
72
+ variant="primary"
73
+ className="mt-auto self-start"
74
+ onClick={() => setNewPluginOpen(true)}
75
+ >
76
+ Create a plugin
77
+ </Button>
78
+ </Surface>
79
+
80
+ <Surface as="section" elevation="none" padded className="flex min-h-48 flex-col">
81
+ <Sparkles size={19} className="text-accent" aria-hidden="true" />
82
+ <h2 className="mt-3 text-strong font-semibold text-ink">Create a skill</h2>
83
+ <p className="mt-1 text-ui text-ink-muted">
84
+ Capture repeatable instructions for an AI agent. You can add the skill to a plugin
85
+ later.
86
+ </p>
87
+ <Button
88
+ variant="outline"
89
+ className="mt-auto self-start"
90
+ onClick={() => setNewSkillOpen(true)}
91
+ >
92
+ Create a skill
93
+ </Button>
94
+ </Surface>
95
+ </div>
96
+
97
+ {newPluginOpen && (
98
+ <NewPluginDialog
99
+ existing={pluginNames}
100
+ onClose={() => setNewPluginOpen(false)}
101
+ onCreated={() => {
102
+ data.reload();
103
+ data.reloadPlugins();
104
+ }}
105
+ />
106
+ )}
107
+
108
+ {newSkillOpen && (
109
+ <Dialog
110
+ open
111
+ busy={newSkillBusy}
112
+ onClose={() => setNewSkillOpen(false)}
113
+ title="New skill"
114
+ footer={
115
+ <Button
116
+ variant="quiet"
117
+ disabled={newSkillBusy}
118
+ onClick={() => setNewSkillOpen(false)}
119
+ >
120
+ Close
121
+ </Button>
122
+ }
123
+ >
124
+ <p className="text-ui text-ink-muted">
125
+ Start in your own space. You can move the skill into a shared plugin when it is ready.
126
+ </p>
127
+ <NewSkillPanel
128
+ destination={{ personal: true }}
129
+ existingSkills={skillNames}
130
+ onBusyChange={setNewSkillBusy}
131
+ onCreated={() => {
132
+ // Belt and braces on the lifted flag: the panel clears it
133
+ // itself, and clearing it again as the dialog closes means a
134
+ // later open can never inherit a stale busy state.
135
+ setNewSkillOpen(false);
136
+ setNewSkillBusy(false);
137
+ }}
138
+ />
139
+ </Dialog>
140
+ )}
141
+ </div>
142
+ );
143
+ }