ci+test: wire vitest into CI + add tests for HelpTooltip + install widget

The frontend test setup (vitest + happy-dom + @testing-library/react +
6 existing test files = 37 passing tests) was already wired up but
NOT running in CI — deploy.yml only invoked ``npm audit`` and
``npm run build``, so the existing tests were gating exactly nothing.
A regression any of them would catch could ship to prod undetected.

Three changes in one commit:

1. Add ``npm test`` to the frontend CI job
   ─────────────────────────────────────────
   New "Run frontend tests (vitest)" step runs BEFORE the build so
   a test-caught regression doesn't get the chance to ship via a
   successful build.  ~10s on CI hardware, no caching needed.

2. New tests/components/HelpTooltip.test.jsx (9 tests)
   ──────────────────────────────────────────────────
   The reusable "?" popover shipped in the contextual-help work.
   Covers: hidden until open, click-toggle, Escape-to-close,
   click-outside-to-close, optional Learn-more link, custom
   aria-label, aria-expanded sync.

   Caught a real interaction bug while writing: the original
   component had ``onMouseEnter={open}`` + ``onFocus={open}`` +
   ``onClick={toggle}`` — userEvent.click synthesises mouseenter →
   focus → click in sequence, so a single click on a closed tooltip
   would open via mouseenter, then immediately re-close via the
   click toggle.  Same bug fires on touch devices where there's no
   real "hover" before the tap.

   Fixed by simplifying the trigger to click-toggle only.  Hover
   no longer auto-opens — keyboard accessibility is preserved
   because Enter/Space on a focused button fires click.

3. New tests/components/InstallCloudNodeCard.test.jsx (6 tests)
   ───────────────────────────────────────────────────────────
   The single highest-stakes UX flow in the app: just signed up,
   empty grid, customer needs to run a CLI command.  A regression
   in this widget = silent loss of every new sign-up.

   Mocks @clerk/clerk-react useAuth + the createNode service helper
   so tests don't need a Clerk provider or a real fetch.  Covers:
     - Initial state shows CTA only, no credentials revealed
     - Does NOT auto-create a node on mount (orphan-node guard)
     - Click → calls createNode + transitions to the tabbed view
     - The displayed Linux/macOS one-liner contains the returned
       credentials (--node-id + --key) — single most-important
       assertion in the file
     - All three OS tabs render after creds load
     - Switching to Windows tab shows the MSI download link
     - API failure surfaces as inline error so the user can retry

Frontend test count went 37 → 52 (+15).  Backend untouched, still 538.
ruff clean.  Build succeeds.

Author: Sbussiso

.github/workflows/deploy.yml

@@ -78,6 +78,21 @@ jobs:
         working-directory: frontend
         run: npm audit --audit-level=high --omit=dev
 
+      # Vitest component tests — run BEFORE the build so a regression
+      # caught by tests doesn't get the chance to ship via a successful
+      # build.  We have ~50 tests today (HelpTooltip, InstallCloudNodeCard,
+      # UpgradeModal, EmptyState, the API service helpers, the docs
+      # page, and a sanity smoke test); the suite runs in <10s on CI
+      # so the speed cost is negligible.
+      #
+      # ``npm test`` is the package.json alias for ``vitest run``
+      # (one-shot, exits with status, no watch).  Vitest auto-discovers
+      # files matching the ``include: ["tests/**/*.test.{js,jsx}"]``
+      # pattern in vite.config.js.
+      - name: Run frontend tests (vitest)
+        working-directory: frontend
+        run: npm test
+
       # Build now so a syntax or type error fails CI here rather than
       # mid-deploy.  Catches the same class of bug as backend pytest.
       - name: Build production bundle

frontend/src/components/HelpTooltip.jsx

@@ -63,12 +63,14 @@ export default function HelpTooltip({ children, docHref, label = "Help" }) {
       <button
         type="button"
         className="help-tooltip-trigger"
+        // Click-toggle only.  Avoids a subtle interaction bug where
+        // hover-to-open + click-to-toggle would race on touch devices
+        // (the synthesized mouseenter fires immediately before the
+        // click, opening then immediately re-closing the popover on
+        // a single tap).  Keyboard users activate via Enter/Space
+        // which fires click, so they get the same toggle behaviour
+        // — accessibility preserved.
         onClick={() => setOpen((v) => !v)}
-        onMouseEnter={() => setOpen(true)}
-        onFocus={() => setOpen(true)}
-        // Don't blur-close — losing focus to the popover content
-        // (e.g. clicking the "Learn more" link) shouldn't dismiss
-        // the popover before the click registers.
         aria-label={label}
         aria-expanded={open}
         aria-controls={popoverId}
@@ -80,10 +82,6 @@ export default function HelpTooltip({ children, docHref, label = "Help" }) {
           id={popoverId}
           className="help-tooltip-popover"
           role="tooltip"
-          // Mouse-leave on the popover wrapper closes — the trigger
-          // also gets re-rendered with onMouseEnter so a tight back-
-          // and-forth between trigger and popover stays open.
-          onMouseLeave={() => setOpen(false)}
         >
           <div className="help-tooltip-body">{children}</div>
           {docHref && (

frontend/tests/components/HelpTooltip.test.jsx

@@ -0,0 +1,135 @@
+// Smoke tests for HelpTooltip — the reusable "?" icon + popover used
+// next to confusing setting labels (recording policy, MCP scope picker,
+// motion-email default-OFF rationale).
+//
+// What we're pinning here:
+//
+//   - The popover is hidden until the user opens it (avoids
+//     accidentally surfacing copy on every render).
+//   - Click toggles open AND close — important because hover-only
+//     popovers don't work on touch devices.
+//   - Escape and click-outside close the popover (both are universal
+//     dismissal patterns; both must work or the popover sticks open
+//     and obscures the page).
+//   - The optional ``docHref`` renders a "Learn more →" link only
+//     when present (caller-controlled).
+//   - Accessibility: the trigger gets aria-expanded that flips
+//     true/false in sync with the popover's visibility.
+
+import { describe, it, expect } from 'vitest'
+import { render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+import HelpTooltip from '../../src/components/HelpTooltip.jsx'
+
+describe('HelpTooltip', () => {
+  it('does not render the popover until the user opens it', () => {
+    render(<HelpTooltip>helpful info</HelpTooltip>)
+
+    // The trigger is always visible.
+    expect(screen.getByRole('button')).toBeInTheDocument()
+    // The body copy is gated behind the open state.
+    expect(screen.queryByRole('tooltip')).not.toBeInTheDocument()
+    expect(screen.queryByText('helpful info')).not.toBeInTheDocument()
+  })
+
+  it('opens on click and shows the body copy', async () => {
+    const user = userEvent.setup()
+    render(<HelpTooltip>helpful info</HelpTooltip>)
+
+    await user.click(screen.getByRole('button'))
+
+    expect(screen.getByRole('tooltip')).toBeInTheDocument()
+    expect(screen.getByText('helpful info')).toBeInTheDocument()
+  })
+
+  it('toggles closed on a second click', async () => {
+    const user = userEvent.setup()
+    render(<HelpTooltip>helpful info</HelpTooltip>)
+
+    const trigger = screen.getByRole('button')
+    await user.click(trigger)
+    expect(screen.getByRole('tooltip')).toBeInTheDocument()
+
+    await user.click(trigger)
+    expect(screen.queryByRole('tooltip')).not.toBeInTheDocument()
+  })
+
+  it('closes on Escape', async () => {
+    const user = userEvent.setup()
+    render(<HelpTooltip>helpful info</HelpTooltip>)
+
+    await user.click(screen.getByRole('button'))
+    expect(screen.getByRole('tooltip')).toBeInTheDocument()
+
+    await user.keyboard('{Escape}')
+    expect(screen.queryByRole('tooltip')).not.toBeInTheDocument()
+  })
+
+  it('closes on click-outside', async () => {
+    const user = userEvent.setup()
+    render(
+      <div>
+        <HelpTooltip>helpful info</HelpTooltip>
+        <button type="button">elsewhere</button>
+      </div>,
+    )
+
+    // Open the tooltip by name so the click-outside button doesn't
+    // get matched.
+    await user.click(screen.getByRole('button', { name: /help/i }))
+    expect(screen.getByRole('tooltip')).toBeInTheDocument()
+
+    // Click a sibling button → tooltip closes.
+    await user.click(screen.getByText('elsewhere'))
+    expect(screen.queryByRole('tooltip')).not.toBeInTheDocument()
+  })
+
+  it('renders a "Learn more" link when docHref is provided', async () => {
+    const user = userEvent.setup()
+    render(
+      <HelpTooltip docHref="https://example.test/docs">
+        gist
+      </HelpTooltip>,
+    )
+
+    await user.click(screen.getByRole('button'))
+
+    const link = screen.getByRole('link', { name: /learn more/i })
+    expect(link).toBeInTheDocument()
+    expect(link).toHaveAttribute('href', 'https://example.test/docs')
+  })
+
+  it('omits the "Learn more" link when docHref is not provided', async () => {
+    const user = userEvent.setup()
+    render(<HelpTooltip>just gist</HelpTooltip>)
+
+    await user.click(screen.getByRole('button'))
+
+    expect(screen.queryByRole('link', { name: /learn more/i })).not.toBeInTheDocument()
+  })
+
+  it('uses the provided aria-label on the trigger', () => {
+    render(
+      <HelpTooltip label="Help: recording policy">explanation</HelpTooltip>,
+    )
+
+    expect(
+      screen.getByRole('button', { name: 'Help: recording policy' }),
+    ).toBeInTheDocument()
+  })
+
+  it('flips aria-expanded as the popover opens and closes', async () => {
+    const user = userEvent.setup()
+    render(<HelpTooltip>info</HelpTooltip>)
+
+    const trigger = screen.getByRole('button')
+    expect(trigger).toHaveAttribute('aria-expanded', 'false')
+
+    await user.click(trigger)
+    expect(trigger).toHaveAttribute('aria-expanded', 'true')
+
+    await user.click(trigger)
+    expect(trigger).toHaveAttribute('aria-expanded', 'false')
+  })
+})

frontend/tests/components/InstallCloudNodeCard.test.jsx

@@ -0,0 +1,182 @@
+// Smoke tests for InstallCloudNodeCard — the in-app CloudNode install
+// widget that replaced the "click out to GitHub README" flow on the
+// empty-state dashboard.
+//
+// The single biggest moment of customer drop-off lives in this
+// component: just signed up, empty grid, need to run a CLI command.
+// A regression that broke the click → POST /api/nodes → display
+// credentialed one-liner flow would silently lose every new sign-up.
+//
+// What's pinned:
+//
+//   - Initial state shows the "Get my install command →" CTA with no
+//     credentials revealed (catches the orphan-node bug — auto-creating
+//     on mount would spam the org with unused nodes).
+//   - Click → calls createNode + transitions to the tabbed install view.
+//   - The displayed Linux/macOS one-liner contains the returned
+//     credentials (node_id + api_key).  This is the single most-
+//     important assertion — without these in the command, the install
+//     wouldn't work end-to-end.
+//   - OS tabs render and the user can switch between them.
+//   - API failure surfaces as an inline error (e.g. plan limit hit
+//     would otherwise silently leave the button disabled).
+
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+
+// Mock Clerk's useAuth so the component doesn't need a ClerkProvider
+// wrapper.  The widget's only Clerk usage is `getToken()`, which
+// passes through to our createNode service helper — we mock that
+// helper too.
+vi.mock('@clerk/clerk-react', () => ({
+  useAuth: () => ({
+    getToken: () => Promise.resolve('test-jwt'),
+  }),
+}))
+
+// Mock the API helper so tests don't actually fetch.  Override per
+// test by reassigning the .mockResolvedValueOnce / .mockRejectedValueOnce
+// stub.
+const mockCreateNode = vi.fn()
+vi.mock('../../src/services/api', () => ({
+  createNode: (...args) => mockCreateNode(...args),
+}))
+
+import InstallCloudNodeCard from '../../src/components/InstallCloudNodeCard.jsx'
+
+
+beforeEach(() => {
+  mockCreateNode.mockReset()
+})
+
+
+describe('InstallCloudNodeCard', () => {
+  it('renders the initial CTA without revealing credentials', () => {
+    render(<InstallCloudNodeCard />)
+
+    expect(
+      screen.getByRole('button', { name: /Get my install command/i }),
+    ).toBeInTheDocument()
+    // No credential or command bytes leak before the user clicks.
+    expect(screen.queryByText(/install\.sh/)).not.toBeInTheDocument()
+    expect(screen.queryByText(/--node-id/)).not.toBeInTheDocument()
+  })
+
+  it('does NOT auto-create a node on mount (orphan-node guard)', () => {
+    // The widget previously considered auto-creating but explicitly
+    // doesn't — a hot reload during dev or a user reloading the
+    // dashboard repeatedly while troubleshooting their network
+    // would otherwise burn through the plan's max_nodes limit.
+    // Pin "no API call without an explicit click".
+    render(<InstallCloudNodeCard />)
+    expect(mockCreateNode).not.toHaveBeenCalled()
+  })
+
+  it('calls createNode and reveals the credentialed one-liner on click', async () => {
+    mockCreateNode.mockResolvedValueOnce({
+      node_id: 'abc123',
+      api_key: 'secret-key-xyz',
+    })
+    const user = userEvent.setup()
+    render(<InstallCloudNodeCard />)
+
+    await user.click(
+      screen.getByRole('button', { name: /Get my install command/i }),
+    )
+
+    // createNode invoked exactly once with our auto-name.
+    await waitFor(() => expect(mockCreateNode).toHaveBeenCalledTimes(1))
+    expect(mockCreateNode).toHaveBeenCalledWith(
+      expect.any(Function),  // getToken
+      'First CloudNode',
+    )
+
+    // Wait for the post-creds state to render.
+    await waitFor(() =>
+      expect(screen.getByRole('tablist')).toBeInTheDocument(),
+    )
+
+    // The displayed command MUST contain the returned credentials —
+    // without these, the install command is useless.  This is the
+    // single highest-impact assertion in the file.
+    const codeEl = document.querySelector('.install-command code')
+    expect(codeEl).toBeInTheDocument()
+    expect(codeEl.textContent).toContain('--node-id abc123')
+    expect(codeEl.textContent).toContain('--key secret-key-xyz')
+  })
+
+  it('renders all three OS tabs after credentials are loaded', async () => {
+    mockCreateNode.mockResolvedValueOnce({
+      node_id: 'n1', api_key: 'k1',
+    })
+    const user = userEvent.setup()
+    render(<InstallCloudNodeCard />)
+
+    await user.click(
+      screen.getByRole('button', { name: /Get my install command/i }),
+    )
+    await waitFor(() =>
+      expect(screen.getByRole('tablist')).toBeInTheDocument(),
+    )
+
+    // All three tabs render — Linux, macOS, Windows.  Catches a
+    // regression where someone simplified the tab loop and dropped one.
+    expect(screen.getByRole('tab', { name: /Linux/i })).toBeInTheDocument()
+    expect(screen.getByRole('tab', { name: /macOS/i })).toBeInTheDocument()
+    expect(screen.getByRole('tab', { name: /Windows/i })).toBeInTheDocument()
+  })
+
+  it('switches to the Windows tab and shows the MSI download path', async () => {
+    mockCreateNode.mockResolvedValueOnce({
+      node_id: 'n1', api_key: 'k1',
+    })
+    const user = userEvent.setup()
+    render(<InstallCloudNodeCard />)
+
+    await user.click(
+      screen.getByRole('button', { name: /Get my install command/i }),
+    )
+    await waitFor(() =>
+      expect(screen.getByRole('tab', { name: /Windows/i })).toBeInTheDocument(),
+    )
+
+    await user.click(screen.getByRole('tab', { name: /Windows/i }))
+
+    // Windows tab uses an MSI download (different from Linux/macOS
+    // curl-pipe-bash).  The download anchor must point at our
+    // backend's redirect endpoint.
+    const downloadLink = screen.getByRole('link', {
+      name: /Download CloudNode for Windows/i,
+    })
+    expect(downloadLink).toBeInTheDocument()
+    expect(downloadLink.getAttribute('href')).toMatch(
+      /\/downloads\/windows\/x64$/,
+    )
+  })
+
+  it('surfaces API errors inline so the user knows what went wrong', async () => {
+    // Simulate "Node limit reached on the Free plan" or similar.
+    mockCreateNode.mockRejectedValueOnce(
+      new Error('Node limit reached (3 on Free plan). Upgrade your plan.'),
+    )
+    const user = userEvent.setup()
+    render(<InstallCloudNodeCard />)
+
+    await user.click(
+      screen.getByRole('button', { name: /Get my install command/i }),
+    )
+
+    await waitFor(() =>
+      expect(screen.getByRole('alert')).toBeInTheDocument(),
+    )
+    expect(screen.getByRole('alert')).toHaveTextContent(/Node limit reached/)
+
+    // Still in the initial state (CTA visible, tabs not rendered)
+    // so the user can retry.
+    expect(
+      screen.getByRole('button', { name: /Get my install command/i }),
+    ).toBeInTheDocument()
+    expect(screen.queryByRole('tablist')).not.toBeInTheDocument()
+  })
+})