@checkstack/ui 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -1,5 +1,335 @@
 # @checkstack/ui
 
+## 1.8.0
+
+### Minor Changes
+
+- 1ef2e79: feat: hotlinks on incidents/maintenances and additional links on systems
+
+  Users with `manage` access on an incident, maintenance, or system can now
+  attach free-form URL "hotlinks" — Jira tickets, runbooks, dashboards, ticket
+  tools, etc. — alongside the existing fields.
+
+  - **Incidents** & **maintenances**: links live on the entity itself and are
+    surfaced both in the editor dialog and on the public detail page. Two new
+    RPC procedures per plugin (`addLink`, `removeLink`) gated behind the
+    existing `manage` access rule. Links are returned as part of
+    `getIncident` / `getMaintenance` and cache-invalidated on every link
+    mutation.
+  - **Systems**: a parallel `system_links` table with `getSystemLinks`,
+    `addSystemLink`, `removeSystemLink` procedures. Surfaced inside the
+    system editor (next to contacts) and on the read-only system detail
+    sidebar. Cache-scoped per-system so list endpoints remain hot.
+  - **Shared UI**: a `LinksEditor` component in `@checkstack/ui` does the
+    presentation; the three plugins each own their own RPC wiring.
+
+  Database changes ship as additive migrations (new `incident_links`,
+  `maintenance_links`, `system_links` tables, all FK-cascaded on parent
+  delete). No existing columns or rows are touched.
+
+  The system incident and maintenance history pages now sort by relevance:
+  active entries (non-`resolved` incidents, `scheduled` or `in_progress`
+  maintenances) appear at the top, with creation date descending as the
+  tiebreaker.
+
+- aa89bc5: Replace the bespoke `registerInfrastructureTab()` registry with a standard
+  slot-extension contract (`InfrastructureTabsSlot` from
+  `@checkstack/infrastructure-common`). Plugins now contribute infrastructure
+  tabs via `createSlotExtension`, depending only on the slot owner.
+
+  The slot system in `@checkstack/frontend-api` gains a second type parameter
+  on `createSlot<TContext, TMetadata>` so extensions can declare typed static
+  metadata at registration time (label, icon, access rules, ordering for the
+  infrastructure tab bar). A new `useSlotExtensions(slot)` hook returns typed
+  extensions and subscribes to plugin lifecycle changes.
+
+  Each tab body now stacks a **Runtime** sub-section (live state, read-only)
+  on top of a **Configuration** sub-section (settings, gated by `canUpdate`).
+
+  **Queue runtime panel.** Surfaces aggregated counts (pending / processing /
+  completed / failed) plus three sub-tabs of recent jobs: **Active**, **Recent
+  failed** (with the failure message), and **Recent completed** (with
+  duration). Job payloads are deliberately not surfaced — they may carry
+  secrets and need a separate manage-access gate to be shown.
+
+  To support this, `Queue<T>` gains a required `listJobs(opts)` method
+  returning `JobSummary[]` (no payloads), and `QueueStats` gains a
+  `scope: "instance" | "cluster"` field. The in-memory queue keeps rolling
+  ring buffers (200 entries) for completed/failed history and tracks active
+  jobs by id; BullMQ uses native `getJobs`. `QueueManager.listJobs` aggregates
+  across queues and sorts (most-recent-first for terminal states, FIFO for
+  active/waiting/delayed).
+
+  **Cache runtime panel.** Lists the top N entries by size (or by recency) so
+  operators can debug a cache filling up. Values are deliberately omitted —
+  PII / secret risk. Backends opt in via an optional `listEntries?` method on
+  `CacheProvider`; non-supporting backends return `{ supported: false }` and
+  the UI renders a "not supported by this backend" hint. The in-memory cache
+  implements it using its existing per-entry byte tracking.
+
+  `CacheStats` also gains `scope: "instance" | "cluster"`.
+
+  **Multi-instance scope warning.** A new `<InstanceScopeBanner>` component in
+  `@checkstack/ui` renders a yellow banner above any runtime panel whose
+  backend reports `scope: "instance"` — i.e. in-memory queue or cache running
+  in a horizontally scaled deployment. The banner explains the metrics are
+  local to the responding replica and recommends switching to a clustered
+  backend (Redis-backed queue / cache) for cluster-wide visibility.
+
+  **Bug fix — stable cache provider proxy.** `CacheManagerImpl.getProvider()`
+  now returns a single stable proxy that delegates to whatever provider is
+  currently active. Previously, consumers of `createCachedScope` (and any
+  direct `cacheManager.getProvider()` caller) captured the active provider
+  reference at plugin-init time. After any `setActiveBackend` call — including
+  saving the same memory config in the new Cache tab, which reconstructs the
+  in-memory cache — those scopes wrote to an orphaned old provider while the
+  runtime panel read stats from the new (empty) one, making the runtime panel
+  appear to report 0 keys. With the proxy, all consumers share a single stable
+  identity and writes always land in the active provider.
+
+  **Bytes tracking on the in-memory cache.** `InMemoryCache.getStats().sizeBytes`
+  now returns a running approximation (UTF-8 bytes of the key plus
+  `v8.serialize(value).byteLength`, with a JSON fallback) that's kept in sync
+  across all eviction paths. Treat the number as a sanity gauge; it doesn't
+  include `Map` per-entry overhead.
+
+  **Pagination.** Both `Queue<T>.listJobs` and `CacheProvider.listEntries?`
+  are offset-paginated. Inputs gain an `offset: number`; outputs change to
+  `{ items, total: number | null, hasMore: boolean }`. `total` is nullable
+  so backends that can't compute it cheaply still paginate via `hasMore`.
+  The UI uses the existing `<Pagination>` component with a 25-row default
+  page size. `QueueManager.listJobs` aggregates by over-fetching
+  `[0, offset+limit)` per queue, merge-sorting, then slicing the window —
+  optimal for the single-queue case, acceptable for the multi-queue case
+  within the UI's reasonable page-depth bounds. BullMQ uses native offset
+  ranges via `getJobs(types, start, end)` plus `getJobCounts` for `total`.
+
+  **Pending tab.** The Queue runtime panel exposes a virtual `"pending"`
+  state (waiting ∪ delayed, FIFO). It's now the default sub-tab, since
+  "what's queued up?" is the most common question. Per-row state is shown
+  when viewing the combined list.
+
+  **Recurring schedules visible under Pending.** Cron- and interval-based
+  recurring jobs (e.g. healthchecks) are surfaced under Pending/Delayed
+  between fires, with a `nextRunAt` countdown column and a "(recurring)"
+  label. `JobSummary` gains optional `nextRunAt: Date` and `recurring:
+boolean` fields. The in-memory queue synthesises these rows from its
+  `recurringJobs` registry; BullMQ already materialises the next fire of
+  each scheduler as a delayed job and we now surface its trigger time and
+  the `repeatJobKey`-derived `recurring` flag.
+
+  **Bug fix — drop hook emits with no listeners.** `EventBus.emit` no
+  longer enqueues a job when zero listeners (distributed or instance-local)
+  are registered for the hook. Previously, hooks like
+  `core.plugin.initialized` — emitted on every plugin init but subscribed
+  to by nothing in the core repo — accumulated one waiting job per emit
+  forever. The in-memory queue's `processNext` short-circuits when there
+  are zero consumer groups, so its post-loop cleanup never ran for these
+  orphaned jobs. The fix drops the emit at the source and logs a debug
+  line. Note: in distributed deployments using a Redis-backed queue, this
+  means a subscriber on another replica won't receive an event if no
+  replica that emits it has a local listener. Plugins needing cross-process
+  delivery must register their listener on every replica that should
+  receive the hook.
+
+  **Breaking notes (treated as minor under beta semantics)**:
+
+  - `@checkstack/infrastructure-common` removes `registerInfrastructureTab`
+    and `getInfrastructureTabs`; former callers must register an extension
+    into `InfrastructureTabsSlot`.
+  - `@checkstack/queue-api`'s `Queue<T>` interface requires the new
+    `listJobs(opts)` method returning `ListJobsResult` (paginated). Both
+    bundled queue backends (memory, BullMQ) are updated; out-of-tree
+    implementations will need to add it.
+  - `QueueStats` and `CacheStats` add a required `scope` field.
+  - `CacheProvider.listEntries?` (when implemented) now returns
+    `ListEntriesResult` instead of `CacheEntrySummary[]`.
+  - `JobState` adds a `"pending"` variant.
+
+- 3547670: Add `@checkstack/tips-*` — first-run tip and onboarding infrastructure for
+  the frontends.
+
+  Three new packages:
+
+  - `@checkstack/tips-common` — RPC contract (`tipsContract`), `TipsApi`
+    client definition, and zod schemas. Fully-qualified tip IDs have shape
+    `<pluginId>.<localTipId>` and are produced exclusively by
+    `qualifyTipId(plugin, localId)` — plugins never write the namespace
+    themselves, and a local id with a leading or trailing `.` is rejected,
+    so one plugin cannot forge or dismiss a tip in another plugin's
+    namespace.
+  - `@checkstack/tips-backend` — Postgres-backed dismissal store
+    (`user_tip_dismissal` with composite PK on `(user_id, tip_id)`),
+    `listDismissed` / `dismiss` / `reset` endpoints scoped to the
+    requesting user via the auto-auth middleware, and a
+    `auth.userDeleted` hook that cleans up dismissals when a user is
+    deleted.
+  - `@checkstack/tips-frontend` — `<Tip>` (anchored popover) and
+    `<TipBanner>` (inline callout) components plus the `useTipState`
+    hook. All three accept `{ plugin, id }` (where `plugin` is the
+    caller's `pluginMetadata`) and route through `qualifyTipId` so the
+    namespace prefix is enforced at the boundary. Persists per-user on
+    the server when logged in, and per-browser in `localStorage`
+    (`checkstack.tips.dismissed`) when anonymous, with cross-tab sync via
+    the `storage` event.
+
+  `@checkstack/ui`'s `<EmptyState>` gains optional `steps` and `actions`
+  props for richer empty-state coaching (numbered onboarding lists +
+  primary CTA), and accepts `ReactNode` for `description`. Existing
+  callers continue to work unchanged.
+
+  `@checkstack/test-utils-backend`'s `createMockDb` now also mocks
+  `insert().values().onConflictDoNothing()` so routers using upsert-or-skip
+  semantics can be unit-tested.
+
+### Patch Changes
+
+- 3547670: Give `<DialogContent>` real vertical breathing room between its
+  children. The previous `gap-4` on `<DialogContent>` was a no-op because
+  the children were rendered inside a single inner wrapper, so
+  `<DialogHeader>`, the body, and `<DialogFooter>` all stacked tight
+  against each other. The inner wrapper is now a flex column with
+  `gap-6`, so headers/descriptions, body content, and footer buttons sit
+  apart at the dialog level without callers having to add
+  `<div className="space-y-…">` themselves.
+- 950d6ec: Fix mobile UserMenu items rendering at zero height, group menu items by
+  section, and unstack cramped card headers on small viewports.
+
+  - **UserMenu mobile bug**: On mobile, the user-menu Sheet rendered every
+    menu item as a grid row, which combined with `flex-shrink: 1` on each
+    item collapsed the buttons whose internal layout uses `display: flex`
+    (the items registered with `useNavigate` rather than `<Link>`) to zero
+    content height. Switched the mobile container to a flex column with
+    `[&>*]:shrink-0` and added `min-h-0` so the sheet scrolls correctly
+    when the list overflows.
+
+  - **UserMenu grouping**: Slot extensions now accept an optional `group`
+    field. The user menu buckets `UserMenuItemsSlot` extensions by `group`
+    and renders each group under a labeled header (`Workspace`,
+    `Reliability`, `Configuration`, `Documentation`, `Account`). Existing
+    core plugins are tagged with the appropriate group; third-party plugins
+    can pick any of these or supply their own label. Untagged extensions
+    render last with no header. `UserMenuItemsBottomSlot` is unaffected.
+
+  - **Card header responsiveness**: `CardHeaderRow` (the primitive shared by
+    Incident, Maintenance, Auth, Catalog, GitOps and other config cards) now
+    stacks vertically on narrow viewports and only switches to a single row
+    at the `sm` breakpoint, so titles and adjacent filter controls (e.g.
+    status `Select`, "Show resolved" checkbox) no longer cram together on
+    mobile. Refactored the Incident and Maintenance config pages to use the
+    primitive instead of a hand-rolled `flex items-center justify-between`
+    row, and made their `Select` triggers full-width on mobile.
+
+- Updated dependencies [42abfff]
+- Updated dependencies [aa89bc5]
+- Updated dependencies [950d6ec]
+  - @checkstack/common@0.9.0
+  - @checkstack/frontend-api@0.5.0
+
+## 1.7.1
+
+### Patch Changes
+
+- 50e5f5f: Runtime plugin system: install + uninstall plugins from npm, GitHub releases
+  (including private GitHub Enterprise instances), or tarball uploads at
+  runtime, with multi-package bundles, dependency-derived compatibility checks,
+  multi-instance coordination via a Postgres artifact store, and
+  single-coordinator destructive cleanup.
+
+  Highlights:
+
+  - New `PluginSource` discriminated union and `PluginInstaller` /
+    `PluginInstallerRegistry` interfaces in `@checkstack/backend-api`. The
+    GitHub variant accepts an optional `apiBaseUrl` so deployments backed by
+    GitHub Enterprise can install from `https://ghe.example.com/api/v3`
+    instead of `api.github.com`.
+  - New `installPackageMetadataSchema` (Zod) in `@checkstack/common` validates
+    every plugin's `package.json` at install time. Required fields: `name`,
+    `version`, `description`, `author`, `license`, `checkstack.type`,
+    `checkstack.pluginId`. Optional: `checkstack.bundle`,
+    `checkstack.usageInstructions`, `checkstack.allowInstallScripts`.
+  - New `pluginManagerContract` in `@checkstack/pluginmanager-common` with
+    `list`, `previewInstall`, `install`, `previewUninstall`, `uninstall`, and
+    `events` procedures.
+  - New `@checkstack/pluginmanager-frontend` admin UI: installed-plugins list
+    with per-row uninstall (typed-confirmation modal, schema/configs/cascade
+    toggles), install page with NPM / Tarball Upload / GitHub Release tabs
+    (Catalog tab disabled — coming soon), and an events page surfacing the
+    install/uninstall audit log.
+  - New `bunx @checkstack/scripts plugin-pack` CLI for plugin authors —
+    per-package mode produces an npm-shaped tarball; `--bundle` mode produces
+    an outer tarball containing every sibling declared in
+    `package.json#checkstack.bundle`. Published to npm so external authors
+    can `bunx` it directly without a workspace checkout.
+  - Compatibility derived from `package.json#dependencies` ranges
+    (`semver.satisfies` against the platform's loaded `@checkstack/*`
+    versions) — no separate `compatibility` field.
+  - Multi-instance: originator persists artifacts + `plugins` rows + broadcasts
+    install/uninstall; receiving instances do in-process register/unregister
+    only. Destructive ops (drop schema, delete plugin_configs, delete
+    artifacts, delete `plugins` rows) run exactly once on the originator.
+  - Fresh-instance bootstrap: `loadPlugins()` hydrates any
+    `is_uninstallable=true` plugin missing from `node_modules` from the
+    artifact store before normal Phase 1 register.
+  - New schema: `plugin_artifacts` (tarball storage), `plugin_install_events`
+    (audit/error log). `plugins` extended with `version`, `metadata`,
+    `source`, `bundle_id`, `is_primary`. Local plugin sync now writes
+    `version` from each plugin's `package.json` so the admin UI shows real
+    versions instead of `—`.
+  - Tarball-upload endpoint (`POST /api/pluginmanager/upload-tarball`) for
+    the install UI; access-gated by `pluginmanager.plugin.manage`.
+  - Plugin Manager menu link added to the user menu (main grid, alongside
+    Profile / Notification Settings / etc.).
+
+  Cross-cutting changes:
+
+  - Backend request/response logging now flows through `rootLogger` (winston)
+    instead of `hono/logger`. 5xx responses include the response body inline
+    so swallowed early-return errors are visible in the log.
+  - The `/api/:pluginId/*` dispatcher now logs which core service is missing
+    or which `pluginId` had no metadata when it 500s.
+  - New `registerCorePluginMetadata` on `PluginManager` for core routers
+    (like the plugin manager itself) that need their metadata visible to the
+    RPC dispatcher without going through the full plugin lifecycle.
+  - ESLint: `unicorn/no-null` is now disabled globally. Drizzle distinguishes
+    between `null` (writes a real SQL NULL) and `undefined` (skip the column
+    on insert), so treating them as interchangeable produced latent bugs at
+    the persistence boundary. The bulk of the patch-bumped packages above
+    reflect lint-fix touches that landed when this rule was relaxed.
+  - Workspace-wide license normalization to `Elastic-2.0` (matches
+    `LICENSE.md`). Every `package.json` in the workspace now declares the
+    same SPDX identifier; the patch bumps capture this.
+
+  Plugin packages (every `plugins/*`): added a `pack` npm script
+  (`bunx @checkstack/scripts plugin-pack`), mirrored each plugin's
+  `pluginId` from `plugin-metadata.ts` into `package.json#checkstack.pluginId`
+  so install-time validation passes, stubbed any missing required metadata
+  fields (`description`, `author`, `license`), and added
+  `checkstack.bundle` to multi-package plugin primaries (telegram, rcon, ssh,
+  jira, queue-bullmq, queue-memory, cache-memory).
+
+  Breaking changes:
+
+  - The legacy single-method `PluginInstaller` interface (`install(packageName)`)
+    is removed. Callers must use `coreServices.pluginInstallerRegistry`.
+  - The old `pluginAdminContract` and `createPluginAdminRouter` are removed.
+    Replaced by `pluginManagerContract` in `@checkstack/pluginmanager-common`
+    and `createPluginManagerRouter` in `core/backend`.
+  - `@checkstack/test-utils-backend` no longer exports
+    `createMockPluginInstaller` / `MockPluginInstaller` (the legacy interface
+    it shimmed is gone).
+
+  Note: bumps are limited to `minor` (for packages with new public API
+  surface) and `patch` (for downstream consumers, license normalization,
+  and lint fixes). No `major` bumps despite the `PluginInstaller` removal —
+  the legacy interface had no third-party consumers in the wild before this
+  runtime plugin system landed, and the contract surface is the same shape
+  modulo the rename.
+
+- Updated dependencies [50e5f5f]
+  - @checkstack/common@0.8.0
+  - @checkstack/frontend-api@0.4.2
+
 ## 1.7.0
 
 ### Minor Changes

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@checkstack/ui",
-  "version": "1.7.0",
+  "version": "1.8.0",
+  "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
   "dependencies": {
-    "@checkstack/common": "0.7.0",
-    "@checkstack/frontend-api": "0.4.0",
+    "@checkstack/common": "0.8.0",
+    "@checkstack/frontend-api": "0.4.2",
     "@monaco-editor/react": "^4.7.0",
     "@radix-ui/react-accordion": "^1.2.12",
     "@radix-ui/react-dialog": "^1.1.15",
@@ -29,16 +30,16 @@
     "tailwind-merge": "^2.2.0"
   },
   "devDependencies": {
-    "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-frontend": "0.0.4",
-    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/scripts": "0.3.0",
+    "@checkstack/test-utils-frontend": "0.0.5",
+    "@checkstack/tsconfig": "0.0.7",
     "@testing-library/react": "^16.0.0",
     "@types/react": "^18.2.0",
     "@types/react-dom": "^19.2.3",
     "typescript": "^5.0.0"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo -b",
     "lint": "bun run lint:code",
     "lint:code": "eslint . --max-warnings 0",
     "test": "bun test"

package/src/components/Card.tsx

@@ -22,8 +22,9 @@ export const CardHeader = ({
 );
 
 /**
- * A row layout for card headers with title and actions.
- * Provides mobile-friendly defaults with flex-wrap and gap.
+ * Row layout for card headers with title and actions. Stacks vertically on
+ * narrow viewports and switches to a single row at the `sm` breakpoint, so
+ * filters and buttons don't get cramped against the title on mobile.
  */
 export const CardHeaderRow = ({
   className,
@@ -31,7 +32,7 @@ export const CardHeaderRow = ({
 }: React.HTMLAttributes<HTMLDivElement>) => (
   <div
     className={cn(
-      "flex flex-wrap items-center justify-between gap-3",
+      "flex flex-col gap-3 sm:flex-row sm:flex-wrap sm:items-center sm:justify-between",
       className,
     )}
     {...props}

package/src/components/Dialog.tsx

@@ -33,7 +33,7 @@ const DialogOverlay = React.forwardRef<
 DialogOverlay.displayName = DialogPrimitive.Overlay.displayName;
 
 const dialogContentVariants = cva(
-  "w-full gap-4 border border-border bg-background text-foreground p-6 shadow-lg sm:rounded-lg max-h-[85dvh] overflow-y-auto overflow-x-visible",
+  "w-full border border-border bg-background text-foreground p-6 shadow-lg sm:rounded-lg max-h-[85dvh] overflow-y-auto overflow-x-visible",
   {
     variants: {
       size: {
@@ -79,7 +79,7 @@ const DialogContent = React.forwardRef<
           )}
           {...props}
         >
-          <div className="-mx-2 px-2">{children}</div>
+          <div className="-mx-2 px-2 flex flex-col gap-6">{children}</div>
           {!hideCloseButton && (
             <DialogPrimitive.Close
               className="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2"

package/src/components/DynamicForm/MultiTypeEditorField.tsx

@@ -123,7 +123,7 @@ export const MultiTypeEditorField: React.FC<MultiTypeEditorFieldProps> = ({
           obj[pair.key] = pair.value;
         }
         try {
-          // eslint-disable-next-line unicorn/no-null -- JSON.stringify requires null for formatting
+           
           onChange(JSON.stringify(obj, null, 2));
           return;
         } catch {

package/src/components/EmptyState.tsx

@@ -4,27 +4,72 @@ import { cn } from "../utils";
 
 interface EmptyStateProps extends React.HTMLAttributes<HTMLDivElement> {
   title: string;
-  description?: string;
+  description?: React.ReactNode;
   icon?: React.ReactNode;
+  /**
+   * Optional ordered onboarding steps. When supplied, the empty state
+   * renders as a "coaching" card explaining how the user gets started.
+   * Each step is shown with a numbered chip.
+   */
+  steps?: React.ReactNode[];
+  /**
+   * Optional action area (typically a primary CTA button) shown beneath
+   * the description / steps. Use this for "Create your first X" buttons.
+   */
+  actions?: React.ReactNode;
 }
 
 export const EmptyState: React.FC<EmptyStateProps> = ({
   title,
   description,
   icon,
+  steps,
+  actions,
   className,
   ...props
 }) => {
+  const isCoaching = (steps && steps.length > 0) || !!actions;
+
   return (
     <Card
       className={cn("border-dashed border-2 bg-muted/30", className)}
       {...props}
     >
-      <CardContent className="flex flex-col items-center justify-center py-12 text-center">
+      <CardContent
+        className={cn(
+          "flex flex-col items-center text-center",
+          isCoaching ? "py-10" : "py-12 justify-center",
+        )}
+      >
         {icon && <div className="text-muted-foreground/40 mb-4">{icon}</div>}
         <p className="text-foreground font-medium">{title}</p>
         {description && (
-          <p className="text-sm text-muted-foreground mt-1">{description}</p>
+          <div className="text-sm text-muted-foreground mt-1 max-w-prose">
+            {description}
+          </div>
+        )}
+        {steps && steps.length > 0 && (
+          <ol className="mt-6 flex flex-col gap-3 text-left max-w-md w-full">
+            {steps.map((step, index) => (
+              <li
+                key={index}
+                className="flex items-start gap-3 text-sm text-foreground"
+              >
+                <span
+                  className="inline-flex size-6 shrink-0 items-center justify-center rounded-full bg-primary/10 text-primary text-xs font-semibold"
+                  aria-hidden="true"
+                >
+                  {index + 1}
+                </span>
+                <span className="text-muted-foreground">{step}</span>
+              </li>
+            ))}
+          </ol>
+        )}
+        {actions && (
+          <div className="mt-6 flex flex-wrap items-center justify-center gap-2">
+            {actions}
+          </div>
         )}
       </CardContent>
     </Card>

package/src/components/InstanceScopeBanner.tsx

@@ -0,0 +1,46 @@
+import {
+  InfoBanner,
+  InfoBannerIcon,
+  InfoBannerContent,
+  InfoBannerTitle,
+  InfoBannerDescription,
+} from "./InfoBanner";
+import { AlertTriangle } from "lucide-react";
+
+/**
+ * Warns operators that the metrics being displayed reflect a single process
+ * — relevant when the underlying backend is in-memory and the deployment is
+ * (or could become) horizontally scaled.
+ *
+ * Renders nothing when `scope === "cluster"`.
+ */
+export interface InstanceScopeBannerProps {
+  scope: "instance" | "cluster";
+  /** What the metrics are about ("Queue" / "Cache"). Used in the title only. */
+  subject: string;
+  /** Recommendation text — e.g. "switch to a Redis-backed queue". */
+  recommendation: string;
+}
+
+export const InstanceScopeBanner = ({
+  scope,
+  subject,
+  recommendation,
+}: InstanceScopeBannerProps) => {
+  if (scope === "cluster") return null;
+  return (
+    <InfoBanner variant="warning">
+      <InfoBannerIcon>
+        <AlertTriangle className="h-4 w-4" />
+      </InfoBannerIcon>
+      <InfoBannerContent>
+        <InfoBannerTitle>{subject}: instance-local metrics</InfoBannerTitle>
+        <InfoBannerDescription>
+          These figures reflect this server instance only. In a horizontally
+          scaled deployment, each replica reports its own numbers depending on
+          which one your request hit. {recommendation}
+        </InfoBannerDescription>
+      </InfoBannerContent>
+    </InfoBanner>
+  );
+};

package/src/components/LinksEditor.tsx

@@ -0,0 +1,156 @@
+import { useState } from "react";
+import { ExternalLink, Plus, Trash2 } from "lucide-react";
+import { Button } from "./Button";
+import { Input } from "./Input";
+import { Label } from "./Label";
+
+export interface HotLink {
+  id: string;
+  label: string | null;
+  url: string;
+}
+
+export interface LinksEditorProps<T extends HotLink> {
+  /** Currently attached links. */
+  links: T[];
+  /** Whether the current user is allowed to add/remove links. */
+  canManage?: boolean;
+  /** Called when the user submits a new link. Should resolve when persisted. */
+  onAdd: (props: { label?: string; url: string }) => Promise<void> | void;
+  /** Called when the user removes a link. */
+  onRemove: (link: T) => Promise<void> | void;
+  /** Whether an add or remove mutation is currently in flight. */
+  busy?: boolean;
+  /** Heading shown above the list. Defaults to "Hotlinks". */
+  title?: string;
+  /** Help text under the heading. */
+  description?: string;
+}
+
+/**
+ * Inline editor for a list of free-form URL "hotlinks" (e.g. Jira tickets,
+ * dashboards, runbooks). Used by the incident, maintenance, and catalog
+ * plugins — the parent owns the data + mutation wiring; this component is
+ * pure presentation.
+ */
+export function LinksEditor<T extends HotLink>({
+  links,
+  canManage = true,
+  onAdd,
+  onRemove,
+  busy,
+  title = "Hotlinks",
+  description,
+}: LinksEditorProps<T>) {
+  const [label, setLabel] = useState("");
+  const [url, setUrl] = useState("");
+  const [error, setError] = useState<string | undefined>();
+
+  const handleAdd = async () => {
+    const trimmedUrl = url.trim();
+    if (!trimmedUrl) {
+      setError("URL is required");
+      return;
+    }
+    try {
+      // Triggers a synchronous URL parse error early so users get a clear
+      // message instead of waiting for the server validation roundtrip.
+      new URL(trimmedUrl);
+    } catch {
+      setError("Must be a valid URL (include http:// or https://)");
+      return;
+    }
+    setError(undefined);
+    await onAdd({ label: label.trim() || undefined, url: trimmedUrl });
+    setLabel("");
+    setUrl("");
+  };
+
+  return (
+    <div className="space-y-3">
+      <div>
+        <Label>{title}</Label>
+        {description && (
+          <p className="text-xs text-muted-foreground mt-1">{description}</p>
+        )}
+      </div>
+
+      {links.length > 0 ? (
+        <div className="border rounded-lg divide-y">
+          {links.map((link) => (
+            <div
+              key={link.id}
+              className="flex items-center justify-between p-3 gap-2"
+            >
+              <div className="flex items-center gap-2 min-w-0 flex-1">
+                <ExternalLink className="h-4 w-4 text-muted-foreground shrink-0" />
+                <div className="min-w-0">
+                  <a
+                    href={link.url}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="text-sm text-primary hover:underline truncate block"
+                  >
+                    {link.label ?? link.url}
+                  </a>
+                  {link.label && (
+                    <span className="text-xs text-muted-foreground truncate block">
+                      {link.url}
+                    </span>
+                  )}
+                </div>
+              </div>
+              {canManage && (
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  onClick={() => void onRemove(link)}
+                  disabled={busy}
+                  aria-label="Remove link"
+                >
+                  <Trash2 className="h-4 w-4" />
+                </Button>
+              )}
+            </div>
+          ))}
+        </div>
+      ) : (
+        <p className="text-sm text-muted-foreground">No links attached</p>
+      )}
+
+      {canManage && (
+        <div className="border rounded-lg p-4 space-y-3">
+          <div className="grid sm:grid-cols-[1fr_2fr] gap-3">
+            <div className="space-y-1">
+              <Label htmlFor="hotlink-label">Label (optional)</Label>
+              <Input
+                id="hotlink-label"
+                placeholder="e.g. Jira ticket"
+                value={label}
+                onChange={(e) => setLabel(e.target.value)}
+              />
+            </div>
+            <div className="space-y-1">
+              <Label htmlFor="hotlink-url">URL</Label>
+              <Input
+                id="hotlink-url"
+                placeholder="https://example.com/..."
+                value={url}
+                onChange={(e) => setUrl(e.target.value)}
+              />
+            </div>
+          </div>
+          {error && <p className="text-xs text-destructive">{error}</p>}
+          <Button
+            onClick={() => void handleAdd()}
+            disabled={!url.trim() || busy}
+            size="sm"
+          >
+            <Plus className="h-4 w-4 mr-1" />
+            Add Link
+          </Button>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/components/UserMenu.tsx

@@ -94,7 +94,7 @@ export const UserMenu: React.FC<UserMenuProps> = ({
             <SheetHeader className="px-4 py-3 border-b border-border">
               <SheetTitle className="text-base">Menu</SheetTitle>
             </SheetHeader>
-            <div className="flex-1 overflow-y-auto p-2 grid grid-cols-1 gap-2">
+            <div className="flex-1 min-h-0 overflow-y-auto p-2 flex flex-col gap-1 [&>*]:shrink-0">
               {userInfo}
               <DropdownMenuSeparator />
               {children}

package/src/index.ts

@@ -25,6 +25,7 @@ export * from "./components/Toggle";
 export * from "./components/Checkbox";
 export * from "./components/Alert";
 export * from "./components/InfoBanner";
+export * from "./components/InstanceScopeBanner";
 export * from "./components/DynamicForm";
 export * from "./components/PageLayout";
 export * from "./components/PluginConfigForm";
@@ -43,6 +44,7 @@ export * from "./components/DateTimePicker";
 export * from "./components/DateRangeFilter";
 export * from "./components/BackLink";
 export * from "./components/StatusUpdateTimeline";
+export * from "./components/LinksEditor";
 export * from "./components/Slider";
 export * from "./components/DynamicIcon";
 export * from "./components/StrategyConfigCard";

package/tsconfig.json

@@ -2,5 +2,16 @@
   "extends": "@checkstack/tsconfig/frontend.json",
   "include": [
     "src"
+  ],
+  "references": [
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../frontend-api"
+    },
+    {
+      "path": "../test-utils-frontend"
+    }
   ]
-}
+}