@bevel-software/platform-core-frontend 0.10.0 → 0.11.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 (36) hide show
  1. package/package.json +2 -2
  2. package/src/core/CoreAppShell.tsx +2 -0
  3. package/src/core/registry.ts +25 -0
  4. package/src/lib/email.ts +25 -0
  5. package/src/modules/access/__tests__/ManageAccessDialog.placement.test.tsx +1 -1
  6. package/src/modules/access/__tests__/ManageAccessDialog.test.tsx +280 -4
  7. package/src/modules/access/api.ts +47 -13
  8. package/src/modules/access/components/ManageAccessDialog.tsx +119 -49
  9. package/src/modules/admin/__tests__/AdminRolesPage.capabilities.test.tsx +281 -0
  10. package/src/modules/admin/__tests__/AdminRolesPage.suggest.test.tsx +4 -4
  11. package/src/modules/admin/__tests__/DirectoryGroupsPage.test.tsx +438 -0
  12. package/src/modules/admin/components/AdminRolesPage.tsx +203 -411
  13. package/src/modules/admin/components/DirectoryGroupsPage.tsx +610 -0
  14. package/src/modules/admin/hooks/useExclusiveRunner.ts +27 -0
  15. package/src/modules/admin/services/groups.api.ts +151 -0
  16. package/src/modules/admin/services/roles.api.ts +57 -31
  17. package/src/modules/library/__tests__/LibraryRoutes.test.tsx +42 -3
  18. package/src/modules/library/__tests__/PluginPage.test.tsx +29 -0
  19. package/src/modules/library/__tests__/ToolPage.test.tsx +22 -0
  20. package/src/modules/library/__tests__/WorkspaceItemRoute.test.tsx +90 -0
  21. package/src/modules/library/components/LibraryPage.tsx +2 -2
  22. package/src/modules/library/components/PersonalPluginPage.tsx +2 -2
  23. package/src/modules/library/components/PluginPage.tsx +2 -2
  24. package/src/modules/library/components/tool-page/ToolPage.tsx +7 -1
  25. package/src/modules/library/routes/LibraryRoutes.tsx +6 -4
  26. package/src/modules/library/routes/WorkspaceItemRoute.tsx +33 -5
  27. package/src/modules/library/routes/library-paths.ts +30 -0
  28. package/src/modules/onboarding/__tests__/onboarding.test.tsx +63 -17
  29. package/src/modules/onboarding/agent-clients.ts +21 -7
  30. package/src/modules/onboarding/components/WelcomePage.tsx +1 -1
  31. package/src/modules/settings/settings-nav-items.tsx +9 -1
  32. package/src/modules/toolbar/components/ExternalAgentAccessPage.tsx +135 -20
  33. package/src/modules/toolbar/components/__tests__/ExternalAgentAccessPage.test.tsx +113 -14
  34. package/src/shared/mcp/__tests__/connect-snippets.test.ts +66 -0
  35. package/src/shared/mcp/connect-snippets.ts +76 -0
  36. package/src/shared/mcp/index.ts +3 -0
@@ -0,0 +1,151 @@
1
+ import { authFetch } from '../../../lib/api';
2
+
3
+ /**
4
+ * Typed client for the admin Groups surface (`/api/admin/groups*`, admins
5
+ * only) — the "who you are" half of the roles/groups split. Mirrors the
6
+ * backend shape in `groups-admin.service.ts`; re-declared frontend-local like
7
+ * the rest of the admin feature's clients.
8
+ */
9
+
10
+ /**
11
+ * Where groups come from in this deployment. One source at a time:
12
+ * `manual` — created and edited in-app; `idp` — synced from the identity
13
+ * provider over SCIM, read-only here (every mutation answers 409).
14
+ */
15
+ export type GroupsMode = 'manual' | 'idp';
16
+
17
+ export interface GroupRosterEntry {
18
+ canonical: string;
19
+ displayName: string;
20
+ members: string[];
21
+ /** Every access rule referencing this group — drives the delete warning. */
22
+ referencedBy: { path: string; verb: string }[];
23
+ /**
24
+ * Canonical names of roles carrying an assignment to this group — deleting
25
+ * the group also unassigns it from these roles (they lose the members they
26
+ * inherit through it), which the delete confirm must say. Optional
27
+ * defensively: a skewed server may omit it, and rendering must not throw.
28
+ */
29
+ assignedToRoles?: string[];
30
+ }
31
+
32
+ /**
33
+ * Health of the ACTIVE groups source. `ok: false` means the source file
34
+ * exists but cannot be read/parsed — groups then contribute NOTHING to
35
+ * access resolution until repaired, which the page banners loudly.
36
+ */
37
+ export type GroupsHealth = { ok: true } | { ok: false; file: string; reason: string };
38
+
39
+ export interface GroupsRoster {
40
+ mode: GroupsMode;
41
+ groups: GroupRosterEntry[];
42
+ /** See {@link GroupsHealth}. Defaulted to ok when a skewed server omits it. */
43
+ groupsHealth: GroupsHealth;
44
+ }
45
+
46
+ /**
47
+ * Error carrying the backend's HTTP status and optional `kind` discriminator
48
+ * so callers can branch on the 409 `idp-mode` refusal (mutations attempted
49
+ * while the IdP owns the groups) without string-matching messages.
50
+ */
51
+ export class GroupsApiError extends Error {
52
+ status: number;
53
+ kind?: string;
54
+ /** The broken source file (422 `broken-groups` payloads carry it). */
55
+ file?: string;
56
+ /** The parse/read failure message (422 `broken-groups` payloads carry it). */
57
+ reason?: string;
58
+ constructor(message: string, status: number, kind?: string, extra?: { file?: string; reason?: string }) {
59
+ super(message);
60
+ this.name = 'GroupsApiError';
61
+ this.status = status;
62
+ this.kind = kind;
63
+ this.file = extra?.file;
64
+ this.reason = extra?.reason;
65
+ }
66
+ }
67
+
68
+ async function parseRoster(res: Response): Promise<GroupsRoster> {
69
+ const body = (await res.json().catch(() => ({}))) as Partial<GroupsRoster> & {
70
+ error?: string;
71
+ kind?: string;
72
+ file?: string;
73
+ reason?: string;
74
+ };
75
+ if (!res.ok) {
76
+ throw new GroupsApiError(
77
+ body.error || `Request failed (${res.status})`,
78
+ res.status,
79
+ body.kind,
80
+ { file: body.file, reason: body.reason },
81
+ );
82
+ }
83
+ return {
84
+ mode: body.mode ?? 'manual',
85
+ groups: body.groups ?? [],
86
+ groupsHealth: body.groupsHealth ?? { ok: true },
87
+ };
88
+ }
89
+
90
+ export async function getGroupsRoster(): Promise<GroupsRoster> {
91
+ const res = await authFetch('/api/admin/groups');
92
+ return parseRoster(res);
93
+ }
94
+
95
+ export async function createGroup(displayName: string): Promise<GroupsRoster> {
96
+ const res = await authFetch('/api/admin/groups', {
97
+ method: 'POST',
98
+ headers: { 'Content-Type': 'application/json' },
99
+ body: JSON.stringify({ displayName }),
100
+ });
101
+ return parseRoster(res);
102
+ }
103
+
104
+ /**
105
+ * Rename a group. Canonical-changing renames rewrite every grant reference
106
+ * (and roles.yaml `group:` assignments) atomically server-side.
107
+ */
108
+ export async function renameGroup(
109
+ canonical: string,
110
+ newDisplayName: string,
111
+ ): Promise<GroupsRoster> {
112
+ const res = await authFetch(`/api/admin/groups/${encodeURIComponent(canonical)}`, {
113
+ method: 'PATCH',
114
+ headers: { 'Content-Type': 'application/json' },
115
+ body: JSON.stringify({ newDisplayName }),
116
+ });
117
+ return parseRoster(res);
118
+ }
119
+
120
+ export async function deleteGroup(canonical: string): Promise<GroupsRoster> {
121
+ const res = await authFetch(`/api/admin/groups/${encodeURIComponent(canonical)}`, {
122
+ method: 'DELETE',
123
+ });
124
+ return parseRoster(res);
125
+ }
126
+
127
+ export async function addGroupMember(
128
+ canonical: string,
129
+ email: string,
130
+ ): Promise<GroupsRoster> {
131
+ const res = await authFetch(
132
+ `/api/admin/groups/${encodeURIComponent(canonical)}/members`,
133
+ {
134
+ method: 'POST',
135
+ headers: { 'Content-Type': 'application/json' },
136
+ body: JSON.stringify({ email }),
137
+ },
138
+ );
139
+ return parseRoster(res);
140
+ }
141
+
142
+ export async function removeGroupMember(
143
+ canonical: string,
144
+ email: string,
145
+ ): Promise<GroupsRoster> {
146
+ const res = await authFetch(
147
+ `/api/admin/groups/${encodeURIComponent(canonical)}/members/${encodeURIComponent(email)}`,
148
+ { method: 'DELETE' },
149
+ );
150
+ return parseRoster(res);
151
+ }
@@ -1,16 +1,26 @@
1
1
  import { authFetch } from '../../../lib/api';
2
2
 
3
3
  /**
4
- * Typed client for the admin Roles & Members surface. Mirrors the backend shape
5
- * in `roles-admin.service.ts`. Re-declared here (rather than imported from
6
- * `@bevel-software/platform-shared`) to match the rest of the small admin feature, which
7
- * keeps its types frontend-local.
4
+ * Typed client for the admin Roles & Members surface — MEMBERSHIP editing
5
+ * only (roles are app-defined capabilities; there is no create/rename/delete).
6
+ * Mirrors the backend shape in `roles-admin.service.ts`. Re-declared here
7
+ * (rather than imported from `@bevel-software/platform-shared`) to match the
8
+ * rest of the small admin feature, which keeps its types frontend-local.
8
9
  */
9
10
  export interface RoleRosterEntry {
10
11
  canonical: string;
11
12
  displayName: string;
13
+ /** Individual members — emails only; group assignments live in `groups`. */
12
14
  members: string[];
15
+ /** Canonical names of groups assigned to this role. */
16
+ groups: string[];
13
17
  isAdmin: boolean;
18
+ /**
19
+ * What the role DOES. `null` marks a legacy people-set role (no capability
20
+ * behind it) — those get the "Convert to group" action instead of group
21
+ * assignment being meaningful.
22
+ */
23
+ capability: { description: string; groupAssignable: boolean } | null;
14
24
  referencedBy: { path: string; verb: string }[];
15
25
  }
16
26
 
@@ -79,33 +89,10 @@ export async function recoverRoles(): Promise<RoleRosterEntry[]> {
79
89
  return parseRoster(res);
80
90
  }
81
91
 
82
- export async function createRole(displayName: string): Promise<RoleRosterEntry[]> {
83
- const res = await authFetch('/api/access/roles', {
84
- method: 'POST',
85
- headers: { 'Content-Type': 'application/json' },
86
- body: JSON.stringify({ displayName }),
87
- });
88
- return parseRoster(res);
89
- }
90
-
91
- export async function deleteRole(canonical: string): Promise<RoleRosterEntry[]> {
92
- const res = await authFetch(`/api/access/roles/${encodeURIComponent(canonical)}`, {
93
- method: 'DELETE',
94
- });
95
- return parseRoster(res);
96
- }
97
-
98
- export async function renameRole(
99
- canonical: string,
100
- newDisplayName: string,
101
- ): Promise<RoleRosterEntry[]> {
102
- const res = await authFetch(`/api/access/roles/${encodeURIComponent(canonical)}`, {
103
- method: 'PATCH',
104
- headers: { 'Content-Type': 'application/json' },
105
- body: JSON.stringify({ newDisplayName }),
106
- });
107
- return parseRoster(res);
108
- }
92
+ // NOTE: createRole / renameRole / deleteRole are GONE, matching the backend —
93
+ // roles are app-defined capabilities, not user-editable objects (their routes
94
+ // now 404). Membership (members + group assignments) is what this client edits;
95
+ // legacy people-set roles migrate out via convertRoleToGroup.
109
96
 
110
97
  export async function addMember(
111
98
  canonical: string,
@@ -134,3 +121,42 @@ export async function removeMember(
134
121
  );
135
122
  return parseRoster(res);
136
123
  }
124
+
125
+ /** Assign a GROUP to a role — everyone in the group gets the capability. */
126
+ export async function assignGroup(
127
+ canonical: string,
128
+ group: string,
129
+ ): Promise<RoleRosterEntry[]> {
130
+ const res = await authFetch(
131
+ `/api/access/roles/${encodeURIComponent(canonical)}/groups`,
132
+ {
133
+ method: 'POST',
134
+ headers: { 'Content-Type': 'application/json' },
135
+ body: JSON.stringify({ group }),
136
+ },
137
+ );
138
+ return parseRoster(res);
139
+ }
140
+
141
+ export async function unassignGroup(
142
+ canonical: string,
143
+ group: string,
144
+ ): Promise<RoleRosterEntry[]> {
145
+ const res = await authFetch(
146
+ `/api/access/roles/${encodeURIComponent(canonical)}/groups/${encodeURIComponent(group)}`,
147
+ { method: 'DELETE' },
148
+ );
149
+ return parseRoster(res);
150
+ }
151
+
152
+ /**
153
+ * Convert a legacy people-set role into a manual group. Grants keep working —
154
+ * the name is unchanged; it just moves to the groups file.
155
+ */
156
+ export async function convertRoleToGroup(canonical: string): Promise<RoleRosterEntry[]> {
157
+ const res = await authFetch(
158
+ `/api/access/roles/${encodeURIComponent(canonical)}/convert-to-group`,
159
+ { method: 'POST' },
160
+ );
161
+ return parseRoster(res);
162
+ }
@@ -127,9 +127,9 @@ const TOOL_PAGE_STATE: ToolPageState = {
127
127
  /** Exposes the router's current pathname without a testid. */
128
128
  function LocationProbe() {
129
129
  const location = useLocation();
130
- // Hash included so the OAuth-fragment redirect below is assertable; it is
131
- // the empty string everywhere else.
132
- return <div aria-label="pathname">{location.pathname}{location.hash}</div>;
130
+ // Search and hash included so the `?server=` and OAuth-fragment redirects
131
+ // below are assertable; both are the empty string everywhere else.
132
+ return <div aria-label="pathname">{location.pathname}{location.search}{location.hash}</div>;
133
133
  }
134
134
 
135
135
  /**
@@ -366,6 +366,25 @@ describe('LibraryRoutes', () => {
366
366
  );
367
367
  });
368
368
 
369
+ it('redirects an mcp-declared tool to its mcp.json URL with `?server=`, hash intact', async () => {
370
+ // One mcp.json declares several servers, so the redirect must carry the
371
+ // slug in the query — the bare file URL is ambiguous and would bounce to
372
+ // the plugin page, swallowing the OAuth outcome fragment with it.
373
+ dataMock.useLibraryData.mockReturnValue({
374
+ ...CATALOG,
375
+ tools: [
376
+ tool({ slug: 'granola', name: 'granola', path: 'Plugins/Everyone/mcp.json', type: 'mcp' }),
377
+ tool({ slug: 'linear', name: 'linear', path: 'Plugins/Everyone/mcp.json', type: 'mcp' }),
378
+ ],
379
+ });
380
+ renderAt('/skills-and-tools/tools/granola#authorized=granola_KEY');
381
+ await waitFor(() =>
382
+ expect(pathname()).toBe(
383
+ `/workspace/${DEFAULT_BRANCH}/knowledge-base/Plugins/Everyone/mcp.json?server=granola#authorized=granola_KEY`,
384
+ ),
385
+ );
386
+ });
387
+
369
388
  it("/skills-and-tools/skills/:name redirects to the skill's canonical workspace URL", async () => {
370
389
  renderAt('/skills-and-tools/skills/outreach');
371
390
  await waitFor(() =>
@@ -385,6 +404,26 @@ describe('LibraryRoutes', () => {
385
404
  expect(screen.queryByRole('dialog')).toBeNull();
386
405
  });
387
406
 
407
+ it('an mcp-declared integration card navigates to the `?server=` URL', async () => {
408
+ // The declaring file is shared with sibling servers, so the card cannot
409
+ // navigate to the bare file URL — that address is ambiguous and redirects
410
+ // to the plugin page, which is exactly the round-trip bug this pins.
411
+ dataMock.useLibraryData.mockReturnValue({
412
+ ...CATALOG,
413
+ tools: [
414
+ tool({ slug: 'granola', name: 'granola', path: 'Plugins/Everyone/mcp.json', type: 'mcp' }),
415
+ tool({ slug: 'linear', name: 'linear', path: 'Plugins/Everyone/mcp.json', type: 'mcp' }),
416
+ ],
417
+ });
418
+ renderAt('/skills-and-tools/everything');
419
+ fireEvent.click(await screen.findByRole('button', { name: /^granola/ }));
420
+ await waitFor(() =>
421
+ expect(pathname()).toBe(
422
+ `/workspace/${DEFAULT_BRANCH}/knowledge-base/Plugins/Everyone/mcp.json?server=granola`,
423
+ ),
424
+ );
425
+ });
426
+
388
427
  it('an unknown subpath redirects home', async () => {
389
428
  renderAt('/skills-and-tools/nope');
390
429
  await waitFor(() => expect(pathname()).toBe('/skills-and-tools'));
@@ -1,4 +1,5 @@
1
1
  import { describe, it, expect, vi, beforeEach } from 'vitest';
2
+ import { DEFAULT_BRANCH } from '@bevel-software/platform-shared';
2
3
  import { render, screen, act, fireEvent, waitFor } from '@testing-library/react';
3
4
  import { MemoryRouter, Route, Routes, useLocation } from 'react-router-dom';
4
5
  import type { ReactNode } from 'react';
@@ -228,6 +229,34 @@ describe('PluginPage', () => {
228
229
  expect(screen.getByRole('heading', { name: 'Tools' })).toBeInTheDocument();
229
230
  });
230
231
 
232
+ it('opens an mcp-declared tool card at its `?server=` URL, not the bare file URL', async () => {
233
+ // Several servers share one declaring mcp.json, so the bare file URL is
234
+ // ambiguous — navigating there bounced the click straight back to this
235
+ // plugin page. The query param names which server's page to open.
236
+ dataMock.useLibraryData.mockReturnValue({
237
+ ...CATALOG,
238
+ tools: [
239
+ connectedTool(),
240
+ connectedTool({ slug: 'granola', name: 'granola', path: 'Plugins/GTM/mcp.json', type: 'mcp' }),
241
+ ],
242
+ });
243
+ renderPlugin('GTM');
244
+ fireEvent.click(await screen.findByRole('button', { name: /^granola/ }));
245
+ await waitFor(() =>
246
+ expect(href()).toBe(
247
+ `/workspace/${DEFAULT_BRANCH}/knowledge-base/Plugins/GTM/mcp.json?server=granola`,
248
+ ),
249
+ );
250
+ });
251
+
252
+ it('opens a `.tool`-declared card at its bare canonical file URL — unchanged', async () => {
253
+ renderPlugin('GTM');
254
+ fireEvent.click(await screen.findByRole('button', { name: /^heyreach/ }));
255
+ await waitFor(() =>
256
+ expect(href()).toBe(`/workspace/${DEFAULT_BRANCH}/knowledge-base/Plugins/GTM/heyreach.tool`),
257
+ );
258
+ });
259
+
231
260
  it('leads with the plugin, not with who runs it', async () => {
232
261
  renderPlugin('GTM');
233
262
  expect(await screen.findByRole('heading', { name: 'GTM', level: 1 })).toBeInTheDocument();
@@ -341,4 +341,26 @@ describe('ToolPage: OAuth round-trip', () => {
341
341
  expect(await screen.findByRole('alert')).toHaveTextContent('Access denied 100%');
342
342
  await waitFor(() => expect(window.location.hash).toBe(''));
343
343
  });
344
+
345
+ /**
346
+ * The fragment-consumption navigation must keep the QUERY string: on an
347
+ * mcp-declared tool `?server=<slug>` is the page's identity, and stripping
348
+ * it left a refresh (or a copied URL) on the ambiguous bare mcp.json
349
+ * address, which bounces to the plugin page.
350
+ */
351
+ it('keeps the search string when consuming the fragment, so `?server=` survives a refresh', async () => {
352
+ window.history.replaceState(
353
+ null,
354
+ '',
355
+ '/workspace/main/knowledge-base/Plugins/Everyone/mcp.json?server=heyreach#authorized=sec_1',
356
+ );
357
+ renderPage();
358
+
359
+ expect(await screen.findByRole('status')).toHaveTextContent('Signed in to heyreach.');
360
+ await waitFor(() => expect(window.location.hash).toBe(''));
361
+ expect(window.location.search).toBe('?server=heyreach');
362
+ expect(window.location.pathname).toBe(
363
+ '/workspace/main/knowledge-base/Plugins/Everyone/mcp.json',
364
+ );
365
+ });
344
366
  });
@@ -339,6 +339,96 @@ describe('WorkspaceItemRoute', () => {
339
339
  });
340
340
  });
341
341
 
342
+ /**
343
+ * MCP servers declared in a plugin's `mcp.json` — one FILE, several tools, so
344
+ * the file URL alone cannot name a page: `?server=<slug>` disambiguates (a
345
+ * query param, never the hash — the `#…` fragment is the OAuth callback's
346
+ * outcome channel). Before the branch existed, `mcp.json` fell through to the
347
+ * direct-file rule and every mcp-declared tool card bounced to its plugin.
348
+ */
349
+ describe('a server declared in a plugin mcp.json', () => {
350
+ const mcpTool = (slug: string, path: string) => ({
351
+ slug,
352
+ name: slug,
353
+ path,
354
+ type: 'mcp' as const,
355
+ setup: null,
356
+ canWrite: false,
357
+ variables: [],
358
+ });
359
+ const MCP: LibraryData = {
360
+ ...CATALOG,
361
+ tools: [
362
+ // Two servers sharing one declaring file — the ambiguous case.
363
+ mcpTool('granola', 'Plugins/Everyone/mcp.json'),
364
+ mcpTool('linear', 'Plugins/Everyone/mcp.json'),
365
+ // A file declaring exactly one server — resolvable without the param.
366
+ mcpTool('local_toolbox', 'Plugins/LocalLab/mcp.json'),
367
+ ],
368
+ };
369
+
370
+ beforeEach(() => {
371
+ dataMock.useLibraryData.mockReturnValue(MCP);
372
+ });
373
+
374
+ it('renders the tool page the `?server=` param names', async () => {
375
+ renderAt(`${itemUrl('Plugins/Everyone/mcp.json')}?server=granola`);
376
+ expect(await screen.findByLabelText('tool-page')).toHaveTextContent('granola');
377
+ });
378
+
379
+ it('renders the named tool page before the catalog has loaded — the param needs no catalog', async () => {
380
+ dataMock.useLibraryData.mockReturnValue({ ...CATALOG, loading: true, skills: [], tools: [] });
381
+ renderAt(`${itemUrl('Plugins/Everyone/mcp.json')}?server=granola`);
382
+ expect(await screen.findByLabelText('tool-page')).toHaveTextContent('granola');
383
+ });
384
+
385
+ it('resolves a bare mcp.json URL when the catalog knows exactly one server for it', async () => {
386
+ renderAt(itemUrl('Plugins/LocalLab/mcp.json'));
387
+ expect(await screen.findByLabelText('tool-page')).toHaveTextContent('local_toolbox');
388
+ });
389
+
390
+ it('sends a bare mcp.json URL with SEVERAL servers to the plugin page — ambiguous, no page', async () => {
391
+ renderAt(itemUrl('Plugins/Everyone/mcp.json'));
392
+ await waitFor(() =>
393
+ expect(screen.getByLabelText('pathname')).toHaveTextContent(
394
+ '/skills-and-tools/plugins/Everyone',
395
+ ),
396
+ );
397
+ expect(screen.queryByLabelText('tool-page')).toBeNull();
398
+ });
399
+
400
+ it('waits for the catalog on a bare mcp.json URL rather than guessing', async () => {
401
+ dataMock.useLibraryData.mockReturnValue({ ...CATALOG, loading: true, skills: [], tools: [] });
402
+ renderAt(itemUrl('Plugins/LocalLab/mcp.json'));
403
+ expect(await screen.findByRole('button', { name: /^All plugins/ })).toBeInTheDocument();
404
+ expect(screen.queryByLabelText('tool-page')).toBeNull();
405
+ // …and it has not been bounced away either: the URL is still the file's.
406
+ expect(screen.getByLabelText('pathname')).toHaveTextContent('/Plugins/LocalLab/mcp.json');
407
+ });
408
+
409
+ /**
410
+ * Only the plugin's DIRECT child is the declaring file — the backend reads
411
+ * exactly `Plugins/<plugin>/mcp.json`. An `mcp.json` bundled INSIDE a
412
+ * skill (an example, a template) is that skill's file, and rendering it as
413
+ * a tool page would 404 a perfectly real skill asset.
414
+ */
415
+ it("keeps a skill-bundled mcp.json as that skill's file, not a tool page", async () => {
416
+ renderAt(itemUrl('Plugins/Sales/create-sales-deck/mcp.json'));
417
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent(
418
+ 'create-sales-deck::mcp.json',
419
+ );
420
+ expect(screen.queryByLabelText('tool-page')).toBeNull();
421
+ });
422
+
423
+ it('a `?server=` param cannot turn a nested mcp.json into a tool page either', async () => {
424
+ renderAt(`${itemUrl('Plugins/Sales/create-sales-deck/examples/mcp.json')}?server=granola`);
425
+ expect(await screen.findByLabelText('skill-page')).toHaveTextContent(
426
+ 'create-sales-deck::examples/mcp.json',
427
+ );
428
+ expect(screen.queryByLabelText('tool-page')).toBeNull();
429
+ });
430
+ });
431
+
342
432
  /**
343
433
  * A skill's id is its frontmatter `id`/`name`, and only FALLS BACK to the
344
434
  * folder name — so the URL cannot be trusted to spell it. The catalog can.
@@ -2,7 +2,7 @@ import { useMemo, useState } from 'react';
2
2
  import { useNavigate } from 'react-router-dom';
3
3
  import '../library.css';
4
4
  import { useLibrary, type LibraryItem } from '../state/library-data';
5
- import { urlForItemFile } from '../routes/library-paths';
5
+ import { urlForLibraryItem } from '../routes/library-paths';
6
6
  import { useWorkspace } from '../../workspace/state/workspace.context';
7
7
  import { emptyMessageFor, filterLibraryItems, type LibraryFilter } from '../utils/status';
8
8
  import { Banner, TextField } from '../../../shared/components';
@@ -67,7 +67,7 @@ export function LibraryPage({ filter }: { filter: LibraryFilter }) {
67
67
  setReviewing(item);
68
68
  return;
69
69
  }
70
- if (kbDirName) navigate(urlForItemFile(kbDirName, item.path));
70
+ if (kbDirName) navigate(urlForLibraryItem(kbDirName, item));
71
71
  }
72
72
 
73
73
  return (
@@ -3,7 +3,7 @@ import { useNavigate } from 'react-router-dom';
3
3
  import { useAuth } from '../../auth/state/auth.context';
4
4
  import { useLibrary, type LibraryItem } from '../state/library-data';
5
5
  import { useLibraryToast } from '../state/toast.context';
6
- import { urlForItemFile } from '../routes/library-paths';
6
+ import { urlForLibraryItem } from '../routes/library-paths';
7
7
  import { useWorkspace } from '../../workspace/state/workspace.context';
8
8
  import { personalPluginName } from '../utils/personal-plugin';
9
9
  import { EmptySkillsNudge, PluginBreadcrumb, PluginItemSections, PageNote,
@@ -61,7 +61,7 @@ export function PersonalPluginPage() {
61
61
 
62
62
  /** Identical to the gallery's and the plugin page's — one behaviour per card. */
63
63
  function openItem(item: LibraryItem) {
64
- if (kbDirName) navigate(urlForItemFile(kbDirName, item.path));
64
+ if (kbDirName) navigate(urlForLibraryItem(kbDirName, item));
65
65
  }
66
66
 
67
67
  if (items.length === 0 && data.loading) {
@@ -6,7 +6,7 @@ import { useLibraryToast } from '../state/toast.context';
6
6
  import {
7
7
  decodePluginSegment,
8
8
  pathForPluginsIndex,
9
- urlForItemFile,
9
+ urlForLibraryItem,
10
10
  } from '../routes/library-paths';
11
11
  import { primaryFolderOf } from '../utils/plugin-summary';
12
12
  import { PluginJoinRequests } from './PluginJoinRequests';
@@ -149,7 +149,7 @@ export function PluginPage() {
149
149
  setReviewing(item);
150
150
  return;
151
151
  }
152
- if (kbDirName) navigate(urlForItemFile(kbDirName, item.path));
152
+ if (kbDirName) navigate(urlForLibraryItem(kbDirName, item));
153
153
  }
154
154
 
155
155
  /**
@@ -49,7 +49,13 @@ export function ToolPage({
49
49
  const [actionError, setActionError] = useState<string | null>(null);
50
50
 
51
51
  useEffect(() => {
52
- if (oauthOutcome) window.history.replaceState(null, '', window.location.pathname);
52
+ // Consume the OAuth `#…` fragment, KEEPING the query string: on an
53
+ // mcp-declared tool the `?server=<slug>` param is the page's identity, and
54
+ // replacing with the bare pathname stranded a refresh (or any URL copy) on
55
+ // the ambiguous mcp.json address, which bounces to the plugin page.
56
+ if (oauthOutcome) {
57
+ window.history.replaceState(null, '', window.location.pathname + window.location.search);
58
+ }
53
59
  }, [oauthOutcome]);
54
60
 
55
61
  // Same rule as the skill page: back goes to the page the tool LIVES on —
@@ -9,7 +9,7 @@ import { PluginsIndexPage } from '../components/PluginsIndexPage';
9
9
  import { PersonalPluginPage } from '../components/PersonalPluginPage';
10
10
  import { WelcomeRoute } from '../../onboarding/components/WelcomeRoute';
11
11
  import { WorkspaceItemRoute } from './WorkspaceItemRoute';
12
- import { decodePluginSegment, LIBRARY_ROOT, pathForPlugin, urlForItemFile, urlForSkillFile } from './library-paths';
12
+ import { decodePluginSegment, LIBRARY_ROOT, pathForPlugin, urlForLibraryItem, urlForSkillFile } from './library-paths';
13
13
 
14
14
  /**
15
15
  * The Skills & Tools surface — everything under `/skills-and-tools/*`.
@@ -138,9 +138,11 @@ function LegacyToolRedirect() {
138
138
  const tool = data.items.find((i) => i.kind === 'integration' && i.id === decoded);
139
139
  if (kbDirName === null) return null;
140
140
  if (tool) {
141
- return (
142
- <Navigate to={{ pathname: urlForItemFile(kbDirName, tool.path), hash: location.hash }} replace />
143
- );
141
+ // `urlForLibraryItem` adds `?server=<slug>` for an mcp.json-declared tool —
142
+ // several servers share the declaring file, so the file URL alone would
143
+ // bounce to the plugin page. The `#…` fragment rides AFTER the query, so
144
+ // the OAuth outcome and the disambiguator coexist on the one URL.
145
+ return <Navigate to={`${urlForLibraryItem(kbDirName, tool)}${location.hash}`} replace />;
144
146
  }
145
147
  if (data.loading) return null;
146
148
  return <Navigate to={LIBRARY_ROOT} replace />;
@@ -1,4 +1,4 @@
1
- import { Navigate, useParams } from 'react-router-dom';
1
+ import { Navigate, useParams, useSearchParams } from 'react-router-dom';
2
2
  import { DEFAULT_BRANCH, PLUGINS_DIR } from '@bevel-software/platform-shared';
3
3
  import { useWorkspace } from '../../workspace/state/workspace.context';
4
4
  import { useLibrary } from '../state/library-data';
@@ -13,10 +13,12 @@ import { LIBRARY_ROOT, pathForPlugin } from './library-paths';
13
13
  * is the one the reader already had and nothing remounts on the way in.
14
14
  *
15
15
  * Resolution is STRUCTURAL, not a catalog lookup: under `Plugins/<plugin>/`, a
16
- * `*.tool` file is a tool page, any other direct FILE (an extension, no
17
- * segments below it — `access.md`) belongs to the plugin page, and everything
18
- * else is a skill FOLDER whose name is the skill's id — the same identity the
19
- * old name-based route used. That is what makes a skill created a moment ago
16
+ * `*.tool` file is a tool page, the plugin's `mcp.json` is a tool page too
17
+ * (which of its servers is named by `?server=`, or by the catalog when the file
18
+ * declares only one), any other direct FILE (an extension, no segments below
19
+ * it — `access.md`) belongs to the plugin page, and everything else is a skill
20
+ * FOLDER whose name is the skill's id — the same identity the old name-based
21
+ * route used. That is what makes a skill created a moment ago
20
22
  * open instantly: its URL says everything the page needs, and `SkillPage`
21
23
  * fetches the skill by name itself. Waiting on the catalog here raced every
22
24
  * reload and lost (the just-created skill bounced to its plugin's page).
@@ -27,6 +29,7 @@ import { LIBRARY_ROOT, pathForPlugin } from './library-paths';
27
29
  */
28
30
  export function WorkspaceItemRoute() {
29
31
  const params = useParams<{ branch: string; '*': string }>();
32
+ const [searchParams] = useSearchParams();
30
33
  const splat = params['*'] ?? '';
31
34
  const branch = safeDecode(params.branch ?? '');
32
35
  const { kbDirName } = useWorkspace();
@@ -71,6 +74,31 @@ export function WorkspaceItemRoute() {
71
74
  return <ToolPage slug={catalogSlug ?? last.slice(0, -'.tool'.length)} />;
72
75
  }
73
76
 
77
+ // A plugin's `mcp.json` declares tools too — SEVERAL per file, so the file
78
+ // URL alone cannot name a page and `?server=<slug>` disambiguates (a QUERY
79
+ // param, never the hash: the `#…` fragment on tool URLs is the OAuth
80
+ // callback's outcome channel — see `urlForMcpServer`). Before this branch
81
+ // existed, the file fell through to the direct-file rule below and every
82
+ // mcp-declared tool card bounced straight back to its plugin page.
83
+ //
84
+ // Only the plugin's DIRECT child qualifies (`tail.length === 1`): the
85
+ // backend's discovery reads exactly `Plugins/<plugin>/mcp.json`, so an
86
+ // `mcp.json` nested deeper is a skill's bundled file — an example, a
87
+ // template — and must render as that skill's file, not as a tool page.
88
+ if (last === 'mcp.json' && tail.length === 1) {
89
+ const fromParam = searchParams.get('server');
90
+ // A named server renders directly — ToolPage's own not-found handles a bad
91
+ // slug once the secrets listing settles, exactly as it does for a typo.
92
+ if (fromParam) return <ToolPage slug={fromParam} />;
93
+ const declared = data.items.filter((i) => i.kind === 'integration' && i.path === repoRel);
94
+ if (declared.length === 1) return <ToolPage slug={declared[0]!.id} />;
95
+ // Several servers and nothing naming one: the bare URL is ambiguous and
96
+ // has no page — its plugin does. With NONE known, wait for the catalog
97
+ // (same wait-don't-guess posture as below) before drawing that inference.
98
+ if (declared.length === 0 && data.loading) return null;
99
+ return <Navigate to={pathForPlugin(plugin)} replace />;
100
+ }
101
+
74
102
  // THE CATALOG IS THE AUTHORITY on which folder is a skill and what its id
75
103
  // is. Plugins may nest (`Plugins/Engineering/coding/create-ticket/SKILL.md`),
76
104
  // and a skill's id is its frontmatter `id`/`name` — only FALLING BACK to the