@checkstack/gitops-frontend 0.3.8 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # @checkstack/gitops-frontend
 
+## 0.4.0
+
+### Minor Changes
+
+- f6f9a5c: Surface the source repository for GitOps-managed entities and gate the
+  system→group remove button on the system's lock state.
+
+  - `provenanceSchema` now carries a `sourceUrl` field, derived on the
+    backend from the provider type, baseUrl, repository and filePath. URLs
+    are constructed for github.com / gitlab.com and self-hosted
+    GitHub/GitLab where the API base ends in `/api/v3` or `/api/v4`. Other
+    baseUrls fall back to `null` so the UI keeps showing the raw path.
+  - New `useProvenanceLocks` hook (bulk variant of `useProvenanceLock`)
+    for views that render many entities and need to look up locks
+    client-side.
+  - New `<GitOpsSourceBadge>` popover component that replaces the bare
+    GitBranch icon on system and group catalog cards. The popover
+    surfaces the repository, file path, and a "View in source provider"
+    deep link.
+  - `<GitOpsLockBanner>` repo line is now a real link when a sourceUrl is
+    available.
+  - The system→group remove button in the catalog now disables itself
+    when the system is GitOps-managed, matching the backend lock that was
+    already in place.
+
+- 3547670: Wire the new tips infrastructure across the frontends:
+
+  **Empty-state coaching.** Replace generic "no items" copy with onboarding
+  guidance — short description, three numbered steps and a primary CTA — on
+  every EmptyState that has a meaningful next action. Affects: catalog
+  (systems + groups), dashboard, health-check page, integrations (subscriptions
+
+  - provider connections), GitOps providers + secrets, GitOps provenance,
+    SLO config + overview, maintenance config, satellites, plugin manager,
+    incident config, announcements. Read-only EmptyStates (incident history,
+    maintenance history, plugin events) get clearer descriptions explaining
+    what would populate them.
+
+  **First-run anchored tips.** Add `<Tip>` popovers to the most important
+  "Create" affordances so first-time users see a one-line explanation of
+  what they're about to make and why it matters: catalog “Add System” /
+  “Add Group”, healthcheck “Create Check”, integrations “New Subscription”,
+  GitOps “Add Provider”, SLO “Create SLO”, maintenance “Create Maintenance”,
+  satellite “Create Satellite”, plugin-manager “Install plugin”, incident
+  “Report Incident”, announcement “New Announcement”. Each tip is dismissed
+  per user (server-backed when signed in, localStorage otherwise) and
+  namespaced through `qualifyTipId(plugin, …)` so it cannot escape the
+  plugin's own namespace.
+
+  **Welcome banner on the dashboard.** A `<TipBanner>` at the top of the
+  dashboard introduces Checkstack's main flow ("add a system, then a health
+  check") with a one-click jump into the catalog.
+
+### Patch Changes
+
+- 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 [3547670]
+- Updated dependencies [f6f9a5c]
+- Updated dependencies [1ef2e79]
+- Updated dependencies [aa89bc5]
+- Updated dependencies [3547670]
+- Updated dependencies [950d6ec]
+- Updated dependencies [3547670]
+  - @checkstack/common@0.9.0
+  - @checkstack/ui@1.8.0
+  - @checkstack/gitops-common@0.3.0
+  - @checkstack/frontend-api@0.5.0
+  - @checkstack/tips-frontend@0.2.0
+
 ## 0.3.8
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/gitops-frontend",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.tsx",
@@ -13,10 +13,11 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/common": "0.7.0",
-    "@checkstack/frontend-api": "0.4.1",
-    "@checkstack/gitops-common": "0.2.1",
-    "@checkstack/ui": "1.7.0",
+    "@checkstack/common": "0.8.0",
+    "@checkstack/frontend-api": "0.4.2",
+    "@checkstack/gitops-common": "0.2.2",
+    "@checkstack/tips-frontend": "0.1.0",
+    "@checkstack/ui": "1.7.1",
     "lucide-react": "^0.344.0",
     "react": "^18.2.0",
     "react-router-dom": "^6.22.0"
@@ -24,7 +25,7 @@
   "devDependencies": {
     "typescript": "^5.0.0",
     "@types/react": "^18.2.0",
-    "@checkstack/tsconfig": "0.0.6",
-    "@checkstack/scripts": "0.1.2"
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.3.0"
   }
 }

package/src/components/GitOpsLockBanner.tsx

@@ -23,12 +23,23 @@ export const GitOpsLockBanner: React.FC<GitOpsLockBannerProps> = ({
         <span className="text-muted-foreground ml-1">
           — edits are disabled. Changes must be made in Git.
         </span>
-        <div className="text-xs text-muted-foreground mt-0.5 flex items-center gap-1">
-          <span className="truncate">
+        {provenance.sourceUrl ? (
+          <a
+            href={provenance.sourceUrl}
+            target="_blank"
+            rel="noreferrer noopener"
+            className="text-xs text-primary hover:underline mt-0.5 flex items-center gap-1"
+          >
+            <span className="truncate">
+              {provenance.repository}/{provenance.filePath}
+            </span>
+            <ExternalLink className="w-3 h-3 shrink-0" />
+          </a>
+        ) : (
+          <div className="text-xs text-muted-foreground mt-0.5 truncate">
             {provenance.repository}/{provenance.filePath}
-          </span>
-          <ExternalLink className="w-3 h-3 shrink-0" />
-        </div>
+          </div>
+        )}
       </div>
     </div>
   );

package/src/components/GitOpsSourceBadge.tsx

@@ -0,0 +1,77 @@
+import React from "react";
+import { GitBranch, ExternalLink } from "lucide-react";
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@checkstack/ui";
+import type { Provenance } from "@checkstack/gitops-common";
+
+interface GitOpsSourceBadgeProps {
+  provenance: Provenance;
+  iconClassName?: string;
+}
+
+/**
+ * Badge that signals an entity is GitOps-managed and, on click, surfaces the
+ * source repository, file path, and (when derivable) a "View in <provider>"
+ * deep link. Used on catalog cards alongside disabled controls so users can
+ * jump straight to the file that owns the entity.
+ */
+export const GitOpsSourceBadge: React.FC<GitOpsSourceBadgeProps> = ({
+  provenance,
+  iconClassName,
+}) => {
+  const { repository, filePath, sourceUrl } = provenance;
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          aria-label="View GitOps source"
+          title="View GitOps source"
+          className="shrink-0 inline-flex items-center justify-center rounded hover:bg-muted/60 focus:outline-none focus-visible:ring-2 focus-visible:ring-primary/40 p-0.5"
+        >
+          <GitBranch
+            className={iconClassName ?? "w-4 h-4 text-primary"}
+          />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent className="w-80 p-3 space-y-2 text-sm">
+        <div className="flex items-center gap-2 font-medium text-foreground">
+          <GitBranch className="w-4 h-4 text-primary shrink-0" />
+          Managed by GitOps
+        </div>
+        <div className="space-y-1 text-xs">
+          <div>
+            <div className="text-muted-foreground">Repository</div>
+            <div className="font-mono text-foreground break-all">
+              {repository}
+            </div>
+          </div>
+          <div>
+            <div className="text-muted-foreground">File</div>
+            <div className="font-mono text-foreground break-all">
+              {filePath}
+            </div>
+          </div>
+        </div>
+        {sourceUrl ? (
+          <a
+            href={sourceUrl}
+            target="_blank"
+            rel="noreferrer noopener"
+            className="inline-flex items-center gap-1.5 text-xs font-medium text-primary hover:underline"
+          >
+            <ExternalLink className="w-3.5 h-3.5" />
+            View in source provider
+          </a>
+        ) : (
+          <p className="text-xs text-muted-foreground">
+            Open this file in your Git provider to make changes.
+          </p>
+        )}
+      </PopoverContent>
+    </Popover>
+  );
+};

package/src/components/ProvenanceStatus.tsx

@@ -263,8 +263,8 @@ export const ProvenanceStatus = () => {
               <div className="text-center py-8 text-muted-foreground">Loading...</div>
             ) : synced.length === 0 ? (
               <EmptyState
-                title="No synced entities"
-                description="Entities will appear here after a successful sync."
+                title="Nothing synced from Git yet"
+                description="Once a sync run finds and applies YAML descriptors from your Git providers, the resulting Checkstack entities (systems, groups, health checks, …) appear here with provenance — what file they came from and which commit. That's how you know which resources are managed in Git versus created in the UI."
               />
             ) : (
               renderEntryList(synced, false)

package/src/components/ProviderList.tsx

@@ -4,7 +4,12 @@ import {
   useApi,
   accessApiRef,
 } from "@checkstack/frontend-api";
-import { GitOpsApi, gitopsAccess } from "@checkstack/gitops-common";
+import {
+  GitOpsApi,
+  gitopsAccess,
+  pluginMetadata as gitopsPluginMetadata,
+} from "@checkstack/gitops-common";
+import { Tip } from "@checkstack/tips-frontend";
 import {
   Card,
   CardHeader,
@@ -151,10 +156,19 @@ export const ProviderList = () => {
           <CardHeaderRow>
             <CardTitle>Git Providers</CardTitle>
             {canManage && (
-              <Button size="sm" onClick={() => setIsEditorOpen(true)}>
-                <Plus className="w-4 h-4 mr-2" />
-                Add Provider
-              </Button>
+              <Tip
+                plugin={gitopsPluginMetadata}
+                id="providers.create"
+                title="Manage Checkstack from Git"
+                description="Connect a GitHub or GitLab repository and Checkstack will sync your YAML descriptors — systems, groups, health checks — into the platform. Reviews happen as PRs, history lives in commits, and rollbacks are a `git revert` away."
+                side="bottom"
+                align="end"
+              >
+                <Button size="sm" onClick={() => setIsEditorOpen(true)}>
+                  <Plus className="w-4 h-4 mr-2" />
+                  Add Provider
+                </Button>
+              </Tip>
             )}
           </CardHeaderRow>
         </CardHeader>
@@ -165,8 +179,22 @@ export const ProviderList = () => {
             </div>
           ) : !providers || providers.length === 0 ? (
             <EmptyState
+              icon={<Github className="size-10" />}
               title="No providers configured"
-              description="Add a GitHub or GitLab provider to start syncing infrastructure definitions."
+              description="GitOps lets you keep your Checkstack infrastructure (systems, groups, health checks, secrets) in a Git repository and sync it into the platform automatically — pull-request reviews, audit trail, rollbacks, all included."
+              steps={[
+                "Add a GitHub or GitLab provider with a token that can read the repository.",
+                "Create a sync target that points at a path in that repo containing your YAML descriptors.",
+                "Push a change and watch Checkstack apply it — provenance is tracked per resource.",
+              ]}
+              actions={
+                canManage ? (
+                  <Button onClick={() => setIsEditorOpen(true)}>
+                    <Plus className="w-4 h-4 mr-2" />
+                    Add Git provider
+                  </Button>
+                ) : undefined
+              }
             />
           ) : (
             <div className="space-y-3">

package/src/components/SecretList.tsx

@@ -160,8 +160,29 @@ export const SecretList = () => {
             </div>
           ) : !secrets || secrets.length === 0 ? (
             <EmptyState
-              title="No secrets created"
-              description="Create secrets to securely reference sensitive values in your YAML descriptors."
+              icon={<KeyRound className="size-10" />}
+              title="No secrets yet"
+              description={
+                <>
+                  Secrets keep credentials, tokens and API keys out of your
+                  YAML descriptors and out of Git. Reference them from any
+                  GitOps file with{" "}
+                  <code className="text-xs">{"${{ secrets.NAME }}"}</code>.
+                </>
+              }
+              steps={[
+                "Add a secret with a recognisable name (e.g. PROD_API_TOKEN).",
+                "Reference it in any descriptor with the ${{ secrets.NAME }} syntax — values are resolved server-side at apply time.",
+                "Rotate by editing the secret here; descriptors don't have to change.",
+              ]}
+              actions={
+                canManage ? (
+                  <Button onClick={() => setIsEditorOpen(true)}>
+                    <Plus className="w-4 h-4 mr-2" />
+                    Add your first secret
+                  </Button>
+                ) : undefined
+              }
             />
           ) : (
             <div className="space-y-3">

package/src/hooks/useProvenanceLocks.ts

@@ -0,0 +1,43 @@
+import { useMemo } from "react";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { GitOpsApi, type Provenance } from "@checkstack/gitops-common";
+
+export interface ProvenanceLock {
+  isLocked: boolean;
+  provenance: Provenance | null;
+}
+
+const lockKey = ({ kind, entityId }: { kind: string; entityId: string }) =>
+  `${kind}::${entityId}`;
+
+/**
+ * Bulk variant of `useProvenanceLock`. Issues a single `listProvenance` query
+ * for the whole tenant and returns a `getLock(kind, entityId)` lookup, so
+ * callers rendering many rows can avoid an N-query fan-out.
+ */
+export const useProvenanceLocks = () => {
+  const gitopsClient = usePluginClient(GitOpsApi);
+
+  const { data: provenances, isLoading } =
+    gitopsClient.listProvenance.useQuery();
+
+  const lockMap = useMemo(() => {
+    const map = new Map<string, Provenance>();
+    for (const p of provenances ?? []) {
+      if (p.status !== "synced") continue;
+      map.set(lockKey({ kind: p.kind, entityId: p.entityId }), p);
+    }
+    return map;
+  }, [provenances]);
+
+  const getLock = (params: {
+    kind: string;
+    entityId: string | undefined;
+  }): ProvenanceLock => {
+    if (!params.entityId) return { isLocked: false, provenance: null };
+    const provenance = lockMap.get(lockKey({ kind: params.kind, entityId: params.entityId })) ?? null;
+    return { isLocked: !!provenance, provenance };
+  };
+
+  return { getLock, isLoading };
+};

package/src/index.tsx

@@ -33,14 +33,19 @@ export const gitopsPlugin = createFrontendPlugin({
     createSlotExtension(UserMenuItemsSlot, {
       id: "gitops.user-menu.link",
       component: GitOpsMenuItem,
+      metadata: { group: "Configuration" },
     }),
     createSlotExtension(UserMenuItemsSlot, {
       id: "gitops.user-menu.kind-registry",
       component: KindRegistryMenuItem,
+      metadata: { group: "Documentation" },
     }),
   ],
 });
 
 // Public API for other frontend plugins
 export { useProvenanceLock } from "./hooks/useProvenanceLock";
+export { useProvenanceLocks } from "./hooks/useProvenanceLocks";
+export type { ProvenanceLock } from "./hooks/useProvenanceLocks";
 export { GitOpsLockBanner } from "./components/GitOpsLockBanner";
+export { GitOpsSourceBadge } from "./components/GitOpsSourceBadge";

package/tsconfig.json

@@ -13,6 +13,9 @@
     {
       "path": "../gitops-common"
     },
+    {
+      "path": "../tips-frontend"
+    },
     {
       "path": "../ui"
     }