@checkstack/gitops-frontend 0.3.7 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,208 @@
 # @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
+
+- 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/gitops-common@0.2.2
+  - @checkstack/ui@1.7.1
+  - @checkstack/frontend-api@0.4.2
+
 ## 0.3.7
 
 ### Patch Changes

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "@checkstack/gitops-frontend",
-  "version": "0.3.7",
+  "version": "0.4.0",
+  "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.tsx",
   "checkstack": {
     "type": "frontend"
   },
   "scripts": {
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsgo -b",
     "lint": "bun run lint:code",
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/common": "0.7.0",
-    "@checkstack/frontend-api": "0.4.0",
-    "@checkstack/gitops-common": "0.2.1",
-    "@checkstack/ui": "1.6.1",
+    "@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"
@@ -23,7 +25,7 @@
   "devDependencies": {
     "typescript": "^5.0.0",
     "@types/react": "^18.2.0",
-    "@checkstack/tsconfig": "0.0.5",
-    "@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/ProviderEditor.tsx

@@ -79,7 +79,7 @@ export const ProviderEditor: React.FC<ProviderEditorProps> = ({
     // - empty string → undefined (keep current)
     let authTokenValue: string | null | undefined;
     if (clearToken) {
-      // eslint-disable-next-line unicorn/no-null
+       
       authTokenValue = null;
     } else if (authToken.trim()) {
       authTokenValue = authToken.trim();

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

@@ -2,5 +2,22 @@
   "extends": "@checkstack/tsconfig/frontend.json",
   "include": [
     "src"
+  ],
+  "references": [
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../frontend-api"
+    },
+    {
+      "path": "../gitops-common"
+    },
+    {
+      "path": "../tips-frontend"
+    },
+    {
+      "path": "../ui"
+    }
   ]
 }