@bevel-software/platform-core-frontend 0.26.0 → 0.28.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 (206) hide show
  1. package/package.json +2 -2
  2. package/src/core/CoreAppShell.tsx +87 -25
  3. package/src/core/ProductName.tsx +49 -0
  4. package/src/core/__tests__/ProductName.test.tsx +46 -0
  5. package/src/core/__tests__/ShellRoutes.test.tsx +22 -0
  6. package/src/core/__tests__/core-contributions.test.ts +16 -0
  7. package/src/core/core-contributions.ts +17 -0
  8. package/src/core/maker-url.ts +30 -0
  9. package/src/core/registry.ts +78 -1
  10. package/src/index.css +23 -5
  11. package/src/index.ts +5 -0
  12. package/src/lib/__tests__/latest-request.test.ts +48 -0
  13. package/src/lib/latest-request.ts +45 -0
  14. package/src/modules/access/__tests__/ManageAccessDialog.no-sso-invite.test.tsx +222 -0
  15. package/src/modules/access/__tests__/ManageAccessDialog.proposal.test.tsx +1 -1
  16. package/src/modules/access/api.ts +19 -3
  17. package/src/modules/access/components/ManageAccessDialog.tsx +61 -8
  18. package/src/modules/admin/__tests__/AdminRolesPage.fixed-admin.test.tsx +16 -1
  19. package/src/modules/admin/__tests__/RolesCorruptedBanner.test.tsx +70 -0
  20. package/src/modules/admin/__tests__/UserAccountsPage.test.tsx +284 -39
  21. package/src/modules/admin/components/AdminRolesPage.tsx +13 -14
  22. package/src/modules/admin/components/RolesCorruptedBanner.tsx +9 -4
  23. package/src/modules/admin/components/UserAccountsPage.tsx +91 -107
  24. package/src/modules/admin/services/roles.api.ts +14 -1
  25. package/src/modules/auth/__tests__/LoginScreen.test.tsx +80 -5
  26. package/src/modules/auth/__tests__/sso-strict-probe.test.ts +66 -0
  27. package/src/modules/auth/components/LoginScreen.tsx +101 -73
  28. package/src/modules/auth/services/account.api.ts +59 -3
  29. package/src/modules/auth/services/sso.ts +30 -10
  30. package/src/modules/auth/state/use-sign-in-methods.ts +41 -0
  31. package/src/modules/change-requests/__tests__/ChangeRequestDialog.sync-banner.test.tsx +176 -0
  32. package/src/modules/change-requests/__tests__/ChangeRequestDialog.unreadable.test.tsx +68 -0
  33. package/src/modules/change-requests/__tests__/ChangeRequestLink.test.tsx +182 -0
  34. package/src/modules/change-requests/__tests__/FileChangeBoxes.test.tsx +1 -1
  35. package/src/modules/change-requests/__tests__/readFileOnBranch.test.ts +79 -0
  36. package/src/modules/change-requests/components/ChangeBox.tsx +6 -1
  37. package/src/modules/change-requests/components/ChangeRequestDialog.tsx +45 -15
  38. package/src/modules/change-requests/components/ChangeRequestLink.tsx +151 -0
  39. package/src/modules/change-requests/components/CrFileTree.tsx +2 -1
  40. package/src/modules/change-requests/components/FileChangeBoxes.tsx +4 -2
  41. package/src/modules/change-requests/hooks/useApplyChangeRequest.ts +6 -3
  42. package/src/modules/change-requests/services/change-requests.api.ts +15 -2
  43. package/src/modules/change-requests/utils/readFailure.ts +22 -0
  44. package/src/modules/embed/__tests__/EmbedLinkPage.test.tsx +74 -0
  45. package/src/modules/embed/__tests__/EmbedView.test.tsx +473 -0
  46. package/src/modules/embed/__tests__/embed-config.test.ts +128 -0
  47. package/src/modules/embed/__tests__/embed-host.test.ts +111 -0
  48. package/src/modules/embed/__tests__/mcp-app-view.test.ts +295 -0
  49. package/src/modules/embed/__tests__/mount.test.tsx +157 -0
  50. package/src/modules/embed/components/EmbedLinkPage.tsx +109 -0
  51. package/src/modules/embed/components/EmbedView.tsx +545 -0
  52. package/src/modules/embed/embed-config.ts +132 -0
  53. package/src/modules/embed/embed-host.ts +120 -0
  54. package/src/modules/embed/mount.tsx +80 -0
  55. package/src/modules/embed/services/embed-token.ts +22 -0
  56. package/src/modules/embed/services/embed.api.ts +158 -0
  57. package/src/modules/git/__tests__/BranchSwitcher.test.tsx +202 -4
  58. package/src/modules/git/__tests__/GitSyncFailedBanner.test.tsx +59 -1
  59. package/src/modules/git/__tests__/PullNeededBanner.test.tsx +39 -22
  60. package/src/modules/git/__tests__/useAutoPullUpdates.test.tsx +7 -2
  61. package/src/modules/git/branch-delete-menu-item.tsx +24 -0
  62. package/src/modules/git/components/BranchSwitcher.tsx +29 -5
  63. package/src/modules/git/components/GitSyncFailedBanner.tsx +53 -15
  64. package/src/modules/git/components/HistoryVersionPreview.tsx +5 -3
  65. package/src/modules/git/components/PullNeededBanner.tsx +15 -49
  66. package/src/modules/git/hooks/useAutoPullUpdates.ts +9 -5
  67. package/src/modules/git/index.ts +15 -0
  68. package/src/modules/git/services/__tests__/error-messages.test.ts +67 -0
  69. package/src/modules/git/services/__tests__/pull-failure.test.ts +36 -0
  70. package/src/modules/git/services/error-messages.ts +58 -1
  71. package/src/modules/git/services/pull-failure.ts +68 -0
  72. package/src/modules/git/state/branch-delete-confirm.ts +46 -0
  73. package/src/modules/layout/__tests__/HeaderAlignment.test.tsx +1 -0
  74. package/src/modules/layout/__tests__/breakpoints.test.ts +7 -1
  75. package/src/modules/layout/breakpoints.ts +8 -0
  76. package/src/modules/library/__tests__/PluginExtras.test.tsx +9 -9
  77. package/src/modules/library/__tests__/PluginPage.test.tsx +8 -1
  78. package/src/modules/library/__tests__/SkillsTree.test.tsx +13 -4
  79. package/src/modules/library/components/LibraryPage.tsx +22 -0
  80. package/src/modules/library/components/PluginExtras.tsx +23 -6
  81. package/src/modules/library/components/PluginPage.tsx +6 -1
  82. package/src/modules/library/routes/LibraryRoutes.tsx +8 -7
  83. package/src/modules/library/services/plugins.api.ts +4 -1
  84. package/src/modules/library/state/plugins-revision.ts +28 -0
  85. package/src/modules/onboarding/__tests__/InviteButton.test.tsx +214 -0
  86. package/src/modules/onboarding/__tests__/agent-connection-api.test.ts +55 -0
  87. package/src/modules/onboarding/__tests__/creator-welcome.test.tsx +87 -82
  88. package/src/modules/onboarding/__tests__/first-page-prompt.test.ts +164 -0
  89. package/src/modules/onboarding/__tests__/get-started-column.test.tsx +1458 -0
  90. package/src/modules/onboarding/__tests__/invite-dialog.test.tsx +811 -0
  91. package/src/modules/onboarding/__tests__/invite-emails.test.ts +247 -0
  92. package/src/modules/onboarding/__tests__/onboarding.test.tsx +226 -193
  93. package/src/modules/onboarding/__tests__/starter-pack-card.test.tsx +136 -0
  94. package/src/modules/onboarding/components/CreatorWelcomePage.tsx +7 -11
  95. package/src/modules/onboarding/components/EmailChipsInput.tsx +138 -0
  96. package/src/modules/onboarding/components/GetStartedColumn.tsx +670 -0
  97. package/src/modules/onboarding/components/InviteButton.tsx +139 -0
  98. package/src/modules/onboarding/components/InviteDialog.tsx +741 -0
  99. package/src/modules/onboarding/components/RootLanding.tsx +8 -24
  100. package/src/modules/onboarding/components/StarterPackCard.tsx +98 -0
  101. package/src/modules/onboarding/components/WelcomePage.tsx +65 -154
  102. package/src/modules/onboarding/first-page-prompt.ts +123 -0
  103. package/src/modules/onboarding/invite-emails.ts +313 -0
  104. package/src/modules/onboarding/services/agent-connection.api.ts +53 -0
  105. package/src/modules/onboarding/services/starter-packs.api.ts +83 -0
  106. package/src/modules/onboarding/state/agent-connection.ts +167 -0
  107. package/src/modules/onboarding/state/invite-dialog.context.ts +35 -0
  108. package/src/modules/onboarding/state/invite-dialog.tsx +39 -0
  109. package/src/modules/onboarding/state/onboarding.ts +133 -59
  110. package/src/modules/onboarding/state/starter-packs.ts +169 -0
  111. package/src/modules/settings/settings-nav-items.tsx +8 -3
  112. package/src/modules/setup/__tests__/setup.first-run-storage.test.tsx +389 -0
  113. package/src/modules/setup/__tests__/setup.github.test.tsx +5 -5
  114. package/src/modules/setup/__tests__/setup.kept-draft.test.tsx +1 -1
  115. package/src/modules/setup/__tests__/setup.repository-change.test.tsx +1 -1
  116. package/src/modules/setup/__tests__/setup.repository.test.tsx +21 -21
  117. package/src/modules/setup/__tests__/setup.test.tsx +56 -15
  118. package/src/modules/setup/__tests__/useConnectionProbe.test.tsx +123 -0
  119. package/src/modules/setup/components/FirstRunStorage.tsx +560 -0
  120. package/src/modules/setup/components/SetupGate.tsx +46 -1
  121. package/src/modules/setup/components/SetupScreen.tsx +81 -84
  122. package/src/modules/setup/hooks/useConnectionProbe.ts +93 -0
  123. package/src/modules/setup/services/setup.api.ts +3 -3
  124. package/src/modules/setup/utils/suggested-branch.ts +27 -0
  125. package/src/modules/toolbar/commands/__tests__/actions.test.tsx +210 -0
  126. package/src/modules/toolbar/commands/actions.tsx +330 -0
  127. package/src/modules/toolbar/commands/command-menu.ts +44 -0
  128. package/src/modules/toolbar/commands/useCommandActions.ts +71 -0
  129. package/src/modules/toolbar/commands/useCommandShortcuts.ts +121 -0
  130. package/src/modules/toolbar/components/AppSwitcher.tsx +125 -22
  131. package/src/modules/toolbar/components/ExternalAgentAccessPage.tsx +1 -1
  132. package/src/modules/toolbar/components/ProfileMenu.tsx +9 -4
  133. package/src/modules/toolbar/components/SearchPalette.tsx +540 -0
  134. package/src/modules/toolbar/components/Toolbar.tsx +10 -0
  135. package/src/modules/toolbar/components/__tests__/AppSwitcher.test.tsx +230 -52
  136. package/src/modules/toolbar/components/__tests__/ProfileMenu.test.tsx +64 -0
  137. package/src/modules/toolbar/components/__tests__/SearchPalette.test.tsx +864 -0
  138. package/src/modules/toolbar/components/__tests__/Toolbar.test.tsx +57 -2
  139. package/src/modules/toolbar/search/__tests__/rank.test.ts +93 -0
  140. package/src/modules/toolbar/search/__tests__/sources.test.ts +131 -0
  141. package/src/modules/toolbar/search/rank.ts +111 -0
  142. package/src/modules/toolbar/search/sources.ts +169 -0
  143. package/src/modules/workflow/hooks/useFileLock.ts +10 -7
  144. package/src/modules/workflow/services/__tests__/lock.api.test.ts +41 -0
  145. package/src/modules/workflow/services/lock.api.ts +17 -2
  146. package/src/modules/workspace/__tests__/useWorkspaceState.test.ts +49 -1
  147. package/src/modules/workspace/components/EditorTabs.tsx +39 -15
  148. package/src/modules/workspace/components/FileExplorer.tsx +39 -6
  149. package/src/modules/workspace/components/FilePaneCard.tsx +6 -2
  150. package/src/modules/workspace/components/FileRoute.tsx +12 -7
  151. package/src/modules/workspace/components/FileViewer.tsx +271 -74
  152. package/src/modules/workspace/components/KbPageHeader.tsx +13 -6
  153. package/src/modules/workspace/components/__tests__/EditorTabs.test.tsx +88 -21
  154. package/src/modules/workspace/components/__tests__/FileExplorer.test.tsx +92 -4
  155. package/src/modules/workspace/components/__tests__/FileRoute.test.tsx +23 -3
  156. package/src/modules/workspace/components/__tests__/FileViewer.test.tsx +330 -6
  157. package/src/modules/workspace/components/__tests__/KbPageHeader.test.tsx +17 -2
  158. package/src/modules/workspace/components/renderers/DocxRenderer.tsx +11 -16
  159. package/src/modules/workspace/components/renderers/DownloadFileButton.tsx +6 -0
  160. package/src/modules/workspace/components/renderers/EmailRenderer.tsx +23 -21
  161. package/src/modules/workspace/components/renderers/ImageRenderer.tsx +13 -29
  162. package/src/modules/workspace/components/renderers/KbMarkdownView.tsx +9 -2
  163. package/src/modules/workspace/components/renderers/MarkdownRenderer.tsx +8 -0
  164. package/src/modules/workspace/components/renderers/PdfRenderer.tsx +14 -19
  165. package/src/modules/workspace/components/renderers/PptxRenderer.tsx +11 -17
  166. package/src/modules/workspace/components/renderers/ToolRenderer.tsx +35 -7
  167. package/src/modules/workspace/components/renderers/XlsxRenderer.tsx +11 -17
  168. package/src/modules/workspace/components/renderers/__tests__/EmailRenderer.links.test.tsx +73 -0
  169. package/src/modules/workspace/components/renderers/__tests__/ToolRenderer.scaffold.test.tsx +64 -0
  170. package/src/modules/workspace/components/renderers/__tests__/ToolRenderer.surface.test.tsx +82 -0
  171. package/src/modules/workspace/components/renderers/__tests__/bridgeHarness.ts +99 -0
  172. package/src/modules/workspace/components/renderers/__tests__/htmlSandbox.test.ts +129 -35
  173. package/src/modules/workspace/components/renderers/__tests__/htmlViewsGuide.test.ts +149 -0
  174. package/src/modules/workspace/components/renderers/__tests__/kbMarkdownLinkPolicy.test.tsx +100 -0
  175. package/src/modules/workspace/components/renderers/htmlSandbox.ts +76 -20
  176. package/src/modules/workspace/components/renderers/index.ts +26 -0
  177. package/src/modules/workspace/components/renderers/kbMarkdownPipeline.tsx +51 -1
  178. package/src/modules/workspace/components/renderers/rendererRawRead.ts +53 -0
  179. package/src/modules/workspace/components/renderers/rendererSurface.ts +109 -0
  180. package/src/modules/workspace/components/renderers/rendererWorkspace.ts +8 -2
  181. package/src/modules/workspace/hooks/__tests__/useCreatePage.test.ts +137 -0
  182. package/src/modules/workspace/hooks/__tests__/useKnowledgeWriteTarget.test.ts +302 -0
  183. package/src/modules/workspace/hooks/__tests__/useWorkspaceState.test.tsx +126 -21
  184. package/src/modules/workspace/hooks/useCreatePage.ts +206 -0
  185. package/src/modules/workspace/hooks/useKnowledgeWriteTarget.ts +238 -0
  186. package/src/modules/workspace/hooks/useWorkspaceImageResolver.ts +24 -7
  187. package/src/modules/workspace/hooks/useWorkspaceState.ts +42 -8
  188. package/src/modules/workspace/routing/__tests__/kb-routes.test.tsx +10 -0
  189. package/src/modules/workspace/routing/__tests__/md-links-parity.test.tsx +113 -0
  190. package/src/modules/workspace/routing/kb-routes.ts +66 -12
  191. package/src/modules/workspace/state/editable-page.ts +42 -0
  192. package/src/modules/workspace/state/workspace.context.ts +13 -4
  193. package/src/modules/workspace/utils/__tests__/display-file-name.test.ts +60 -0
  194. package/src/modules/workspace/utils/__tests__/fileTree.test.ts +75 -0
  195. package/src/modules/workspace/utils/__tests__/treeConfirm.test.ts +16 -0
  196. package/src/modules/workspace/utils/display-file-name.ts +102 -0
  197. package/src/modules/workspace/utils/fileTree.ts +49 -14
  198. package/src/modules/workspace/utils/treeConfirm.ts +15 -0
  199. package/src/shared/__tests__/no-builtin-confirm.test.ts +102 -0
  200. package/src/shared/components/ConfirmProvider.tsx +156 -0
  201. package/src/shared/components/Dialog.tsx +7 -0
  202. package/src/shared/components/__tests__/ConfirmProvider.test.tsx +198 -0
  203. package/src/shared/components/confirm-context.ts +94 -0
  204. package/src/shared/components/index.ts +3 -0
  205. package/src/modules/onboarding/components/WelcomeRoute.tsx +0 -57
  206. package/src/modules/onboarding/welcome-state.ts +0 -36
@@ -0,0 +1,670 @@
1
+ import { useEffect, useRef, useState, type ReactNode } from 'react';
2
+ import { useLocation, useNavigate } from 'react-router-dom';
3
+ import { Check, Copy, X } from 'lucide-react';
4
+ import {
5
+ KNOWLEDGE_BASE_DIR,
6
+ currentBranchModel,
7
+ currentKbLayout,
8
+ isPersonalPluginDir,
9
+ type FileTreeEntry,
10
+ } from '@bevel-software/platform-shared';
11
+ import { Button, IconButton, buttonClasses } from '../../../shared/components';
12
+ import { cn } from '../../../lib/utils';
13
+ import { copyToClipboard } from '../../../lib/clipboard';
14
+ import { useAdmin } from '../../admin/state/admin.context';
15
+ import { listAccounts } from '../../auth/services/account.api';
16
+ import { listPlugins, type PluginSummary } from '../../library/services/plugins.api';
17
+ import { LIBRARY_ROOT, isLibraryLocation } from '../../library/routes/library-paths';
18
+ import { usePluginsRevision } from '../../library/state/plugins-revision';
19
+ import { useMediaQuery } from '../../layout/hooks/useMediaQuery';
20
+ import { SETUP_COLUMN_HIDDEN_QUERY } from '../../layout/breakpoints';
21
+ import { useWorkspace } from '../../workspace/state/workspace.context';
22
+ import { useMergedWorkspaceTree } from '../../workspace/hooks/useMergedWorkspaceTree';
23
+ import { useFileNav } from '../../workspace/routing/kb-routes';
24
+ import { useCreatePage } from '../../workspace/hooks/useCreatePage';
25
+ import { findEntryByPath, pathExistsInTree } from '../../workspace/utils/fileTree';
26
+ import { useOnboarding, useSetupChecklist } from '../state/onboarding';
27
+ import { useAgentConnection } from '../state/agent-connection';
28
+ import {
29
+ chatGptPromptUrl,
30
+ claudePromptUrl,
31
+ firstPagePromptFor,
32
+ firstPagePromptInFolder,
33
+ firstPageRoute,
34
+ } from '../first-page-prompt';
35
+ import { useStarterPacks } from '../state/starter-packs';
36
+ import { useInviteDialog } from '../state/invite-dialog.context';
37
+ import { WELCOME_PATH } from '../paths';
38
+ import { COMMAND_MENU_SHORTCUT_LABEL, openCommandMenu } from '../../toolbar/commands/command-menu';
39
+
40
+ /** The starter page every new knowledge base is seeded with (`kb-template/`). */
41
+ const GUIDE_FILE = 'How to get started.md';
42
+
43
+ interface SetupAction {
44
+ label: string;
45
+ onClick(): void;
46
+ primary?: boolean;
47
+ disabled?: boolean;
48
+ }
49
+
50
+ interface SetupItem {
51
+ id: string;
52
+ title: string;
53
+ done: boolean;
54
+ hint?: string;
55
+ action?: SetupAction;
56
+ /** Anything the step offers beyond one button, under it. */
57
+ extra?: ReactNode;
58
+ /** Why the step's action just failed, said on the step itself. */
59
+ error?: string | null;
60
+ }
61
+
62
+ /**
63
+ * Whether the Knowledge folder holds anything a person put there: any file
64
+ * other than the starter guide, the repository's dot-files and the folder
65
+ * access rules. A dropped PDF counts — "write your first page" is about the
66
+ * knowledge base having the team's content in it, not about Markdown. A
67
+ * starter pack's page still as the pack wrote it (`placeholders`) is a task
68
+ * to fill in, not content, so it does not count either.
69
+ */
70
+ function hasOwnContent(
71
+ entry: FileTreeEntry | null | undefined,
72
+ guidePath: string,
73
+ placeholders: ReadonlySet<string> = new Set(),
74
+ ): boolean {
75
+ if (!entry) return false;
76
+ for (const child of entry.children ?? []) {
77
+ if (child.name.startsWith('.')) continue;
78
+ if (child.type === 'directory') {
79
+ if (hasOwnContent(child, guidePath, placeholders)) return true;
80
+ continue;
81
+ }
82
+ // Exactly `access.md`: the platform reserves that name and no other
83
+ // spelling, so an `Access.md` someone wrote is a page like any other.
84
+ if (child.relativePath === guidePath || child.name === 'access.md') continue;
85
+ if (placeholders.has(child.relativePath)) continue;
86
+ return true;
87
+ }
88
+ return false;
89
+ }
90
+
91
+ /** A plugin for a team, not somebody's personal shelf. */
92
+ function isTeamPlugin(plugin: PluginSummary): boolean {
93
+ const layout = currentKbLayout();
94
+ return plugin.folders.some((folder) => !isPersonalPluginDir(folder, layout));
95
+ }
96
+
97
+ /**
98
+ * "Is there a team plugin yet?", asked of `GET /api/plugins` — the same
99
+ * catalog the Library reads, fetched here on its own because the Library's
100
+ * provider only exists under its routes and this column sits beside both
101
+ * apps. Asked again whenever `refreshKey` moves — on entering Skills & Tools,
102
+ * and when this tab creates a plugin — and never again once the answer is
103
+ * yes.
104
+ */
105
+ function useTeamPluginExists(enabled: boolean, refreshKey: string): { found: boolean; settled: boolean } {
106
+ const [found, setFound] = useState(false);
107
+ const [settled, setSettled] = useState(false);
108
+ useEffect(() => {
109
+ if (!enabled || found) return;
110
+ let cancelled = false;
111
+ listPlugins()
112
+ .then((plugins) => {
113
+ if (!cancelled && plugins.some(isTeamPlugin)) setFound(true);
114
+ })
115
+ .catch(() => {
116
+ /* unanswered is "not yet": the step stays open, nothing breaks */
117
+ })
118
+ .finally(() => {
119
+ if (!cancelled) setSettled(true);
120
+ });
121
+ return () => {
122
+ cancelled = true;
123
+ };
124
+ }, [enabled, found, refreshKey]);
125
+ // A yes is an answer. Finding it re-runs the effect, whose cleanup cancels
126
+ // the `finally` that would have settled, so `found` settles by itself.
127
+ return { found, settled: settled || found };
128
+ }
129
+
130
+ /**
131
+ * "Is anybody else here yet?" — more than one account a person signs in
132
+ * with. The platform's own machine accounts (`isSystem`) are not a team, and
133
+ * a switched-off account is nobody who can join. An invited account that has
134
+ * not signed in yet DOES count: the step is "Invite your team", and inviting
135
+ * is what the admin can do — when each person first signs in is theirs.
136
+ * Re-asked whenever the invite dialog created somebody.
137
+ */
138
+ function useHasTeammate(enabled: boolean, revision: number): { found: boolean; settled: boolean } {
139
+ const [found, setFound] = useState(false);
140
+ const [settled, setSettled] = useState(false);
141
+ useEffect(() => {
142
+ if (!enabled || found) return;
143
+ let cancelled = false;
144
+ listAccounts()
145
+ .then((accounts) => {
146
+ if (!cancelled && accounts.filter((a) => !a.isSystem && !a.deactivatedAt).length > 1) setFound(true);
147
+ })
148
+ .catch(() => {
149
+ /* as above: unknown leaves the step open */
150
+ })
151
+ .finally(() => {
152
+ if (!cancelled) setSettled(true);
153
+ });
154
+ return () => {
155
+ cancelled = true;
156
+ };
157
+ }, [enabled, found, revision]);
158
+ // Settled by a yes, as above.
159
+ return { found, settled: settled || found };
160
+ }
161
+
162
+ /**
163
+ * The "Get set up" column: a short checklist beside both apps that ticks
164
+ * itself off from what the app already knows, rather than from clicks on it.
165
+ *
166
+ * Every tick is DERIVED — the server's onboarding flag, the file tree, the
167
+ * plugin catalog, the account list — so doing a step anywhere in the app
168
+ * counts, and the column never claims something the workspace does not show.
169
+ * Only "read the guide" and "open the command menu" have no server fact
170
+ * behind them; those two, and the two ways of closing the column, are
171
+ * per-browser notes (see `useSetupChecklist`).
172
+ *
173
+ * It gets out of the way on its own terms: on the welcome page (which is the
174
+ * same instructions, full-size), below the width where a 288px column still
175
+ * leaves a readable page, and for good once closed. Finishing every step does
176
+ * not make it vanish mid-sentence: it says "You're set up" first, and goes
177
+ * once that is closed.
178
+ * The admin-only steps (storage, plugin, invite) are hidden from members,
179
+ * whose checklist is about using the workspace, not setting it up.
180
+ */
181
+ export function GetStartedColumn() {
182
+ const { pathname } = useLocation();
183
+ const navigate = useNavigate();
184
+ const tooNarrow = useMediaQuery(SETUP_COLUMN_HIDDEN_QUERY);
185
+ const onboarding = useOnboarding();
186
+ const checklist = useSetupChecklist();
187
+ const { isAdmin, isAdminLoading = false } = useAdmin();
188
+ const { kbDirName, openFilePath, workspaceBranch } = useWorkspace();
189
+ const { tree } = useMergedWorkspaceTree();
190
+ const { openWorkspacePath } = useFileNav();
191
+ const { createPage, pageFolder, pageFolderSettled } = useCreatePage();
192
+ const invite = useInviteDialog();
193
+
194
+ /**
195
+ * Whether the person's agent has reached the platform — told by the
196
+ * server's `agent-connected` event, and asked on mount and again when the
197
+ * person comes back to the tab, never on a timer — so someone who
198
+ * connected without ever opening the welcome page still gets the tick.
199
+ * Connecting is what the onboarding asked for, so it concludes it too: the
200
+ * pill goes. Once per mount, for the reason the welcome page gives.
201
+ */
202
+ const gone = checklist.dismissed || checklist.completionClosed;
203
+ const agent = useAgentConnection({ enabled: !gone });
204
+ const concluded = useRef(false);
205
+ const { showPill, markDone } = onboarding;
206
+ useEffect(() => {
207
+ if (!agent.connected || !showPill || concluded.current) return;
208
+ concluded.current = true;
209
+ markDone();
210
+ }, [agent.connected, showPill, markDone]);
211
+
212
+ const onWelcome = pathname === WELCOME_PATH;
213
+ const askServer = isAdmin && !gone;
214
+ /**
215
+ * The plugin question's refresh: once per ENTRY into Skills & Tools (that
216
+ * is where a plugin gets made), and whenever this tab creates one — not on
217
+ * every move between its pages, which for a new workspace is the same
218
+ * empty catalog asked for over and over. Counted in state, adjusted while
219
+ * rendering, so the count moves in the same render as the path.
220
+ */
221
+ const inLibrary = isLibraryLocation(pathname);
222
+ const [libraryEntries, setLibraryEntries] = useState({ inLibrary, count: 0 });
223
+ if (libraryEntries.inLibrary !== inLibrary) {
224
+ setLibraryEntries({ inLibrary, count: libraryEntries.count + (inLibrary ? 1 : 0) });
225
+ }
226
+ const pluginsCreated = usePluginsRevision();
227
+ const plugin = useTeamPluginExists(askServer, `${libraryEntries.count}:${pluginsCreated}`);
228
+ const teammate = useHasTeammate(askServer, invite?.invitedRevision ?? 0);
229
+
230
+ const knowledgeRoot = kbDirName ? `${kbDirName}/${KNOWLEDGE_BASE_DIR}` : null;
231
+ const guidePath = knowledgeRoot ? `${knowledgeRoot}/${GUIDE_FILE}` : null;
232
+ const guideExists = guidePath !== null && pathExistsInTree(tree, guidePath);
233
+ // Where New page writes, below the top of Knowledge (`Sales`), or null at
234
+ // the top itself — what the agent's request has to name.
235
+ const pageSubfolder =
236
+ pageFolder && knowledgeRoot && pageFolder.startsWith(`${knowledgeRoot}/`)
237
+ ? pageFolder.slice(knowledgeRoot.length + 1)
238
+ : null;
239
+
240
+ /**
241
+ * The starter pack the team chose, if any: its first-page request replaces
242
+ * the generic one, and its pages stay placeholders — not a first page —
243
+ * until someone fills one in. Which are still untouched is the server's
244
+ * answer (it compares them with the pack), asked again whenever the tree
245
+ * changes while any are left. That answer describes the DEFAULT branch,
246
+ * where the pack landed; the tree here is the branch on screen, so on any
247
+ * other branch the step reads that tree alone rather than apply the
248
+ * default branch's placeholders to pages that may well be filled in there.
249
+ */
250
+ const starter = useStarterPacks({ enabled: !gone });
251
+ const chosenPack = starter.answer?.chosenPack ?? null;
252
+ const onDefaultBranch = workspaceBranch !== null && workspaceBranch === currentBranchModel().defaultBranch;
253
+ const placeholders = new Set(onDefaultBranch ? (chosenPack?.starterPages ?? []) : []);
254
+ const { reload: reloadStarter } = starter;
255
+ const waitingOnPlaceholders = placeholders.size > 0;
256
+ const firstTree = useRef(tree);
257
+ useEffect(() => {
258
+ if (!waitingOnPlaceholders || tree === firstTree.current) return;
259
+ void reloadStarter();
260
+ }, [tree, waitingOnPlaceholders, reloadStarter]);
261
+
262
+ /**
263
+ * "New page": create a Markdown page in a Knowledge folder the person may
264
+ * write and open it already in the editor (`useCreatePage`, shared with the
265
+ * command menu). A refused write never reaches here: `useCreatePage`
266
+ * takes every 403 quietly, moving to the next folder the person may write
267
+ * or withdrawing New page, and resolves null. Any other failure is kept
268
+ * here and shown on the step, because nothing else would say it — toasts
269
+ * only speak inside the Library.
270
+ */
271
+ const [newPage, setNewPage] = useState<{ busy: boolean; error: string | null }>({ busy: false, error: null });
272
+ const createFirstPage = async () => {
273
+ if (!knowledgeRoot || newPage.busy) return;
274
+ setNewPage({ busy: true, error: null });
275
+ try {
276
+ // The step ticks itself from the refreshed tree (any page but the guide
277
+ // counts); the page opens in the editor with the cursor in it.
278
+ await createPage();
279
+ setNewPage({ busy: false, error: null });
280
+ } catch (err) {
281
+ setNewPage({ busy: false, error: err instanceof Error ? err.message : String(err) });
282
+ }
283
+ };
284
+
285
+ // Opening the guide by any route counts — the tree, a link, this column.
286
+ const { readGuide, markGuideRead } = checklist;
287
+ useEffect(() => {
288
+ if (guidePath && openFilePath === guidePath && !readGuide) markGuideRead();
289
+ }, [guidePath, openFilePath, readGuide, markGuideRead]);
290
+
291
+ const items: SetupItem[] = [
292
+ { id: 'workspace', title: 'Create your workspace', done: true },
293
+ ];
294
+ if (isAdmin) {
295
+ // Reaching this column at all means the setup gate let you through, and
296
+ // the gate's last question is where the knowledge lives.
297
+ items.push({ id: 'storage', title: 'Choose where your knowledge lives', done: true });
298
+ }
299
+ items.push({
300
+ id: 'agent',
301
+ title: 'Connect your agent',
302
+ done: !showPill || agent.connected,
303
+ hint: 'So it can read and write this knowledge base.',
304
+ action: { label: 'Connect', onClick: () => navigate(WELCOME_PATH), primary: true },
305
+ });
306
+ if (guideExists && guidePath) {
307
+ items.push({
308
+ id: 'guide',
309
+ title: 'Read “How to get started”',
310
+ done: readGuide,
311
+ hint: 'Two minutes on how pages, plugins and change requests fit together.',
312
+ action: {
313
+ label: 'Open it',
314
+ onClick: () => {
315
+ markGuideRead();
316
+ openWorkspacePath(guidePath);
317
+ },
318
+ },
319
+ });
320
+ }
321
+ const newPageAction: SetupAction | undefined = knowledgeRoot
322
+ ? {
323
+ label: newPage.busy ? 'Creating…' : 'New page',
324
+ onClick: () => void createFirstPage(),
325
+ disabled: newPage.busy,
326
+ }
327
+ : undefined;
328
+ /**
329
+ * With an agent connected, the quickest first page is one it writes: a new
330
+ * chat with the request already typed (or the request to paste, for an
331
+ * agent no link can open), and the tick arrives by itself when the page
332
+ * lands in the tree. Before then that button would open a chat
333
+ * that cannot reach this knowledge base, so the step says what connecting
334
+ * would add instead.
335
+ *
336
+ * Not ticked before the starter-pack answer is in: until then a pack's
337
+ * untouched pages would read as content, and a fast tree could complete
338
+ * the whole list — and let it be closed — on the strength of placeholders.
339
+ * A failed request settles too, and the pages count as the app counted
340
+ * them before there were packs.
341
+ *
342
+ * Only for someone who may write a Knowledge folder: nobody else is shown
343
+ * the step, and the list counts and completes without it.
344
+ */
345
+ if (pageFolder) items.push({
346
+ id: 'page',
347
+ title: 'Write your first page',
348
+ done:
349
+ knowledgeRoot !== null &&
350
+ guidePath !== null &&
351
+ starter.settled &&
352
+ hasOwnContent(findEntryByPath(tree, knowledgeRoot), guidePath, placeholders),
353
+ ...(agent.connected
354
+ ? {
355
+ hint: 'Have your agent write it, or start one here.',
356
+ extra: (
357
+ <FirstPagePromptActions
358
+ client={agent.client}
359
+ kind={agent.kind}
360
+ prompt={firstPagePromptInFolder(firstPagePromptFor(chosenPack), pageSubfolder)}
361
+ newPage={newPageAction}
362
+ />
363
+ ),
364
+ }
365
+ : {
366
+ hint: 'Start one here, or drop files into the file tree.',
367
+ action: newPageAction,
368
+ extra: <span className="text-meta text-ink-faint">Connect your agent and it can write pages for you.</span>,
369
+ }),
370
+ error: newPage.error,
371
+ });
372
+ /**
373
+ * The command menu is how anything else gets found or done, so the list
374
+ * teaches it — by having it opened, which is the whole lesson. The tick is
375
+ * raised by the palette itself on ANY open (the box, the shortcut, this
376
+ * button), so someone who already knew the shortcut is never asked to.
377
+ */
378
+ items.push({
379
+ id: 'command-menu',
380
+ title: `Find or do anything with ${COMMAND_MENU_SHORTCUT_LABEL}`,
381
+ done: checklist.openedCommandMenu,
382
+ hint: 'Type what you want: a page, a skill, or an action like Invite people.',
383
+ action: { label: 'Try it', onClick: openCommandMenu },
384
+ });
385
+ if (isAdmin) {
386
+ items.push({
387
+ id: 'plugin',
388
+ title: 'Create a plugin for your team',
389
+ done: plugin.found,
390
+ hint: 'A shared place for your team’s skills and tools.',
391
+ action: { label: 'Open Skills & Tools', onClick: () => navigate(LIBRARY_ROOT) },
392
+ });
393
+ items.push({
394
+ id: 'invite',
395
+ title: 'Invite your team',
396
+ done: teammate.found,
397
+ hint: 'They sign in with their work account.',
398
+ action: invite ? { label: 'Invite people', onClick: invite.open } : undefined,
399
+ });
400
+ }
401
+
402
+ const doneCount = items.filter((i) => i.done).length;
403
+ // Until the admin verdict and its two questions are answered, the list is
404
+ // not known — and showing a half-ticked list for a moment to an admin who
405
+ // has done everything would be a column that flashes on every load. The
406
+ // same for where a page may be written: the step must not show and vanish.
407
+ const settled =
408
+ pageFolderSettled && !isAdminLoading && (!isAdmin || (plugin.settled && teammate.settled));
409
+ const allDone = doneCount === items.length;
410
+ // The completion line says whether the agent can reach the knowledge base,
411
+ // so it waits for that answer rather than rewriting itself under the reader.
412
+ // So does the list for the file tree: before it loads, the guide reads as
413
+ // absent and the first page as unwritten — a shorter list, falsely open.
414
+ if (onWelcome || tooNarrow || gone || tree === null || !settled || (allDone && !agent.settled)) {
415
+ return null;
416
+ }
417
+
418
+ if (allDone) {
419
+ return (
420
+ <SetupComplete agentConnected={agent.connected} team={isAdmin} onClose={checklist.closeCompletion} />
421
+ );
422
+ }
423
+
424
+ return (
425
+ <aside
426
+ aria-label="Get set up"
427
+ className="w-72 flex-none overflow-y-auto border-l border-line bg-canvas px-4.5 py-4"
428
+ >
429
+ <div className="flex h-8 items-center gap-2">
430
+ <h2 className="text-strong font-semibold text-ink">Get set up</h2>
431
+ <span className="ml-auto text-meta text-ink-faint tabular-nums">
432
+ {doneCount} of {items.length}
433
+ </span>
434
+ <IconButton size={24} aria-label="Dismiss Get set up" title="Dismiss" onClick={checklist.dismiss}>
435
+ <X size={14} aria-hidden />
436
+ </IconButton>
437
+ </div>
438
+ <div
439
+ role="progressbar"
440
+ aria-label="Setup progress"
441
+ aria-valuemin={0}
442
+ aria-valuemax={items.length}
443
+ aria-valuenow={doneCount}
444
+ className="mt-1.5 mb-1 h-1 overflow-hidden rounded-full bg-line"
445
+ >
446
+ <div
447
+ className="h-full bg-ok transition-[width] duration-300 motion-reduce:transition-none"
448
+ style={{ width: `${(doneCount / items.length) * 100}%` }}
449
+ />
450
+ </div>
451
+ <ul>
452
+ {items.map((item) => (
453
+ <li
454
+ key={item.id}
455
+ className="grid grid-cols-[18px_minmax(0,1fr)] gap-2.5 border-t border-line py-2.5 first:border-t-0"
456
+ >
457
+ <span
458
+ aria-hidden
459
+ className={cn(
460
+ 'mt-0.5 flex size-4 items-center justify-center rounded-full border-[1.5px]',
461
+ item.done ? 'border-ok bg-ok text-white' : 'border-line-strong',
462
+ )}
463
+ >
464
+ {item.done && <Check size={10} strokeWidth={3} />}
465
+ </span>
466
+ <div className="min-w-0">
467
+ <div
468
+ className={cn(
469
+ 'text-ui',
470
+ item.done ? 'font-medium text-ink-faint line-through' : 'font-semibold text-ink',
471
+ )}
472
+ >
473
+ {item.title}
474
+ {item.done && <span className="sr-only"> (done)</span>}
475
+ </div>
476
+ {!item.done && (item.hint || item.action || item.extra) && (
477
+ <div className="mt-1 grid justify-items-start gap-2 text-detail text-ink-muted">
478
+ {item.hint && <span>{item.hint}</span>}
479
+ {item.action && (
480
+ <Button
481
+ size="sm"
482
+ variant={item.action.primary ? 'primary' : 'outline'}
483
+ onClick={item.action.onClick}
484
+ disabled={item.action.disabled}
485
+ >
486
+ {item.action.label}
487
+ </Button>
488
+ )}
489
+ {item.extra}
490
+ {item.error && (
491
+ <span role="alert" className="text-danger">
492
+ {item.error}
493
+ </span>
494
+ )}
495
+ </div>
496
+ )}
497
+ </div>
498
+ </li>
499
+ ))}
500
+ </ul>
501
+ </aside>
502
+ );
503
+ }
504
+
505
+ /**
506
+ * The column's last state: every step is done. Shown when the last tick lands
507
+ * — or on arrival, for a list finished elsewhere and never celebrated — and
508
+ * kept until Close, which retires the column for good on this browser.
509
+ *
510
+ * The line says only what is true: "Connect your agent" also ticks when the
511
+ * onboarding was concluded without an agent ever calling in, and members
512
+ * have no team step. A status region, so the change is announced without
513
+ * moving anyone's focus; the entrance is the welcome page's own, motion-safe.
514
+ */
515
+ function SetupComplete({
516
+ agentConnected,
517
+ team,
518
+ onClose,
519
+ }: {
520
+ agentConnected: boolean;
521
+ team: boolean;
522
+ onClose(): void;
523
+ }) {
524
+ const ready = agentConnected
525
+ ? 'Your agent can read and write your knowledge base'
526
+ : 'Your knowledge base is ready';
527
+ return (
528
+ <aside
529
+ aria-label="Get set up"
530
+ className="w-72 flex-none overflow-y-auto border-l border-line bg-canvas px-4.5 py-4"
531
+ >
532
+ <div role="status" className="grid justify-items-start gap-2 motion-safe:animate-onboarding-greeting">
533
+ <span aria-hidden className="flex size-8 items-center justify-center rounded-full bg-ok text-white">
534
+ <Check size={16} strokeWidth={3} />
535
+ </span>
536
+ <h2 className="text-strong font-semibold text-ink">You’re set up</h2>
537
+ <p className="text-detail text-ink-muted">
538
+ {ready}
539
+ {team ? ', and your team can join you.' : '.'}
540
+ </p>
541
+ <Button size="sm" variant="outline" onClick={onClose}>
542
+ Close
543
+ </Button>
544
+ </div>
545
+ </aside>
546
+ );
547
+ }
548
+
549
+ /** The prompt opened in a new chat, as a real link (see `FirstPagePromptActions`). */
550
+ function PromptLink({ href, primary, children }: { href: string; primary?: boolean; children: ReactNode }) {
551
+ return (
552
+ <a
553
+ href={href}
554
+ target="_blank"
555
+ rel="noopener noreferrer"
556
+ className={
557
+ primary
558
+ ? buttonClasses({ variant: 'primary', size: 'sm' })
559
+ : 'text-ink-muted transition-colors hover:text-ink'
560
+ }
561
+ >
562
+ {children}
563
+ </a>
564
+ );
565
+ }
566
+
567
+ /**
568
+ * The agent's way to the first-page prompt, led by the one that suits the
569
+ * agent that connected (`firstPageRoute`), with the others quiet beneath it.
570
+ *
571
+ * Claude's and ChatGPT's connectors get "Ask … to write it", a new chat with
572
+ * the prompt typed. Every other agent — Claude Code, Cursor, anything on the
573
+ * local server, a connection key, an unknown name — has no link that would
574
+ * reach it, so Copy prompt leads there and says where to paste; the two web
575
+ * links stay as quiet extras for someone who uses those too.
576
+ *
577
+ * Real links rather than buttons that call `window.open`: a new tab is what
578
+ * they are, so they should say so to the browser — middle-click, "copy link",
579
+ * and the status-bar preview of where they go all work.
580
+ *
581
+ * Copying answers on the button itself and in a live region; there is no
582
+ * toast to fall back on out here (toasts speak inside the Library only).
583
+ */
584
+ function FirstPagePromptActions({
585
+ client,
586
+ kind,
587
+ prompt,
588
+ newPage,
589
+ }: {
590
+ client?: string;
591
+ kind?: 'agent' | 'key';
592
+ /** The request: the chosen starter pack's, or the generic one. */
593
+ prompt: string;
594
+ newPage?: SetupAction;
595
+ }) {
596
+ const [copied, setCopied] = useState<'idle' | 'ok' | 'fail'>('idle');
597
+ const resetTimer = useRef<number | undefined>(undefined);
598
+ useEffect(() => () => window.clearTimeout(resetTimer.current), []);
599
+ const { primary, agentName } = firstPageRoute(client, kind);
600
+
601
+ async function copy() {
602
+ const ok = await copyToClipboard(prompt);
603
+ window.clearTimeout(resetTimer.current);
604
+ setCopied(ok ? 'ok' : 'fail');
605
+ resetTimer.current = window.setTimeout(() => setCopied('idle'), 1500);
606
+ }
607
+
608
+ const copyButton = (lead: boolean) => (
609
+ <Button
610
+ size={lead ? 'sm' : 'tiny'}
611
+ variant={lead ? 'primary' : 'quiet'}
612
+ onClick={() => void copy()}
613
+ leadingIcon={
614
+ copied === 'ok' ? (
615
+ <Check size={12} aria-hidden className={lead ? undefined : 'text-ok'} />
616
+ ) : copied === 'fail' ? (
617
+ <X size={12} aria-hidden className={lead ? undefined : 'text-danger'} />
618
+ ) : (
619
+ <Copy size={12} aria-hidden />
620
+ )
621
+ }
622
+ >
623
+ Copy prompt
624
+ </Button>
625
+ );
626
+ const claudeLink = (lead: boolean) => (
627
+ <PromptLink href={claudePromptUrl(prompt)} primary={lead}>
628
+ {lead ? 'Ask Claude to write it' : 'Open in Claude'}
629
+ </PromptLink>
630
+ );
631
+ const chatGptLink = (lead: boolean) => (
632
+ <PromptLink href={chatGptPromptUrl(prompt)} primary={lead}>
633
+ {lead ? 'Ask ChatGPT to write it' : 'Open in ChatGPT'}
634
+ </PromptLink>
635
+ );
636
+
637
+ const lead = primary === 'claude' ? claudeLink(true) : primary === 'chatgpt' ? chatGptLink(true) : copyButton(true);
638
+ const quiet =
639
+ primary === 'claude'
640
+ ? [chatGptLink(false), copyButton(false)]
641
+ : primary === 'chatgpt'
642
+ ? [claudeLink(false), copyButton(false)]
643
+ : [claudeLink(false), chatGptLink(false)];
644
+
645
+ return (
646
+ <div className="grid justify-items-start gap-1.5">
647
+ <div className="flex flex-wrap items-center gap-2">
648
+ {lead}
649
+ {newPage && (
650
+ <Button size="sm" variant="outline" onClick={newPage.onClick} disabled={newPage.disabled}>
651
+ {newPage.label}
652
+ </Button>
653
+ )}
654
+ </div>
655
+ {primary === 'copy' && (
656
+ <span className="text-meta text-ink-faint">Paste it into {agentName ?? 'your agent'}.</span>
657
+ )}
658
+ <div className="flex items-center gap-1 text-meta">
659
+ {quiet[0]}
660
+ <span aria-hidden className="text-ink-faint">
661
+ ·
662
+ </span>
663
+ {quiet[1]}
664
+ <span role="status" aria-live="polite" className="sr-only">
665
+ {copied === 'ok' ? 'Prompt copied' : copied === 'fail' ? 'Couldn’t copy the prompt' : ''}
666
+ </span>
667
+ </div>
668
+ </div>
669
+ );
670
+ }