@checkstack/gitops-frontend 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @checkstack/gitops-frontend
+
+## 0.2.0
+
+### Minor Changes
+
+- 6c40b5b: Generalized provenance system and GitOps frontend plugin
+
+  **Breaking**: `EntityKindDefinition.reconcile()` now returns `{ entityId: string }` instead of `void`. Plugins must return the plugin-specific entity ID (e.g., catalog system UUID) so the engine can store it in provenance.
+
+  - Added `entityId` column to the provenance table (non-nullable)
+  - Reconciler engine passes `existingEntityId` to plugins for updates
+  - `getProvenance` now supports lookup by `entityId` in addition to `entityName`
+  - Added provider CRUD endpoints: `createProvider`, `updateProvider`, `deleteProvider`
+  - Created `gitops-frontend` plugin with provider management, secret management, and sync status dashboard
+  - Removed `gitops_entity_name` metadata markers from catalog entities
+  - Removed `findSystemByGitOpsName`, `deleteSystemByGitOpsName` (and Group equivalents) from EntityService
+  - Added provenance-based UI locking in catalog-frontend: edit/delete/drag disabled for GitOps-managed systems and groups
+
+- 6c40b5b: Add Kind Registry browser and developer documentation
+
+  - Added `gitopsAccess.kinds.read` access rule for standalone Kind Registry access
+  - Added `describeKinds()` method to the internal entity kind registry, serializing Zod schemas to JSON Schema
+  - Added `listKinds` RPC endpoint gated by the new access rule
+  - Created standalone Kind Registry page with schema visualization, extension listing, and auto-generated YAML examples
+  - Added Kind Registry link to the user menu
+  - Created developer documentation for entity kind and extension registration in `docs/backend/gitops-entity-kinds.md`
+
+### Patch Changes
+
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+- Updated dependencies [6c40b5b]
+- Updated dependencies [4b0934d]
+  - @checkstack/gitops-common@0.1.0
+  - @checkstack/ui@1.3.6

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@checkstack/gitops-frontend",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "src/index.tsx",
+  "checkstack": {
+    "type": "frontend"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "dependencies": {
+    "@checkstack/common": "0.6.5",
+    "@checkstack/frontend-api": "0.3.9",
+    "@checkstack/gitops-common": "0.0.1",
+    "@checkstack/ui": "1.3.5",
+    "lucide-react": "^0.344.0",
+    "react": "^18.2.0",
+    "react-router-dom": "^6.22.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/react": "^18.2.0",
+    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/scripts": "0.1.2"
+  }
+}

package/src/components/GitOpsLockBanner.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+import { GitBranch, ExternalLink } from "lucide-react";
+import type { Provenance } from "@checkstack/gitops-common";
+
+interface GitOpsLockBannerProps {
+  provenance: Provenance;
+}
+
+/**
+ * Banner displayed on entity detail pages when the entity is managed by GitOps.
+ * Informs the user that manual edits are disabled and shows the Git source.
+ */
+export const GitOpsLockBanner: React.FC<GitOpsLockBannerProps> = ({
+  provenance,
+}) => {
+  return (
+    <div className="flex items-center gap-3 p-3 rounded-lg border border-primary/20 bg-primary/5 text-sm">
+      <GitBranch className="w-5 h-5 text-primary shrink-0" />
+      <div className="min-w-0 flex-1">
+        <span className="font-medium text-foreground">
+          Managed by GitOps
+        </span>
+        <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.repository}/{provenance.filePath}
+          </span>
+          <ExternalLink className="w-3 h-3 shrink-0" />
+        </div>
+      </div>
+    </div>
+  );
+};

package/src/components/GitOpsMenuItem.tsx

@@ -0,0 +1,28 @@
+import { useNavigate } from "react-router-dom";
+import { GitBranch } from "lucide-react";
+import { DropdownMenuItem } from "@checkstack/ui";
+import type { UserMenuItemsContext } from "@checkstack/frontend-api";
+import { resolveRoute } from "@checkstack/common";
+import { pluginMetadata, gitopsAccess, gitopsRoutes } from "@checkstack/gitops-common";
+import React from "react";
+
+const REQUIRED_ACCESS_RULE = `${pluginMetadata.pluginId}.${gitopsAccess.provider.read.id}`;
+
+export function GitOpsMenuItem({
+  accessRules: userPerms,
+}: UserMenuItemsContext) {
+  const navigate = useNavigate();
+  const canView =
+    userPerms.includes("*") || userPerms.includes(REQUIRED_ACCESS_RULE);
+
+  if (!canView) return <React.Fragment />;
+
+  return (
+    <DropdownMenuItem
+      onClick={() => navigate(resolveRoute(gitopsRoutes.routes.home))}
+      icon={<GitBranch className="h-4 w-4" />}
+    >
+      GitOps
+    </DropdownMenuItem>
+  );
+}

package/src/components/KindRegistryMenuItem.tsx

@@ -0,0 +1,28 @@
+import { useNavigate } from "react-router-dom";
+import { Blocks } from "lucide-react";
+import { DropdownMenuItem } from "@checkstack/ui";
+import type { UserMenuItemsContext } from "@checkstack/frontend-api";
+import { resolveRoute } from "@checkstack/common";
+import { pluginMetadata, gitopsAccess, gitopsRoutes } from "@checkstack/gitops-common";
+import React from "react";
+
+const REQUIRED_ACCESS_RULE = `${pluginMetadata.pluginId}.${gitopsAccess.kinds.read.id}`;
+
+export function KindRegistryMenuItem({
+  accessRules: userPerms,
+}: UserMenuItemsContext) {
+  const navigate = useNavigate();
+  const canView =
+    userPerms.includes("*") || userPerms.includes(REQUIRED_ACCESS_RULE);
+
+  if (!canView) return <React.Fragment />;
+
+  return (
+    <DropdownMenuItem
+      onClick={() => navigate(resolveRoute(gitopsRoutes.routes.kinds))}
+      icon={<Blocks className="h-4 w-4" />}
+    >
+      Kind Registry
+    </DropdownMenuItem>
+  );
+}

package/src/components/ProvenanceStatus.tsx

@@ -0,0 +1,246 @@
+import { usePluginClient, useApi, accessApiRef } from "@checkstack/frontend-api";
+import { GitOpsApi, gitopsAccess } from "@checkstack/gitops-common";
+import type { Provenance } from "@checkstack/gitops-common";
+import {
+  Card,
+  CardHeader,
+  CardHeaderRow,
+  CardTitle,
+  CardContent,
+  Button,
+  Badge,
+  EmptyState,
+  ConfirmationModal,
+  useToast,
+} from "@checkstack/ui";
+import { useState } from "react";
+import { CheckCircle, AlertTriangle, XCircle, Trash2, X } from "lucide-react";
+import { extractErrorMessage } from "@checkstack/common";
+
+export const ProvenanceStatus = () => {
+  const client = usePluginClient(GitOpsApi);
+  const accessApi = useApi(accessApiRef);
+  const toast = useToast();
+
+  const { allowed: canManage } = accessApi.useAccess(gitopsAccess.provider.manage);
+
+  const [confirmModal, setConfirmModal] = useState<{
+    isOpen: boolean;
+    provenanceId: string;
+    entityName: string;
+  }>({ isOpen: false, provenanceId: "", entityName: "" });
+
+  const {
+    data: provenanceEntries,
+    isLoading,
+    refetch,
+  } = client.listProvenance.useQuery({});
+
+  const confirmDeleteMutation = client.confirmOrphanDeletion.useMutation({
+    onSuccess: () => {
+      toast.success("Orphan deleted successfully");
+      setConfirmModal({ isOpen: false, provenanceId: "", entityName: "" });
+      void refetch();
+    },
+    onError: (error) => {
+      toast.error(extractErrorMessage(error, "Failed to delete orphan"));
+    },
+  });
+
+  const dismissMutation = client.dismissOrphan.useMutation({
+    onSuccess: () => {
+      toast.success("Orphan dismissed — entity is no longer tracked by GitOps");
+      void refetch();
+    },
+    onError: (error) => {
+      toast.error(extractErrorMessage(error, "Failed to dismiss orphan"));
+    },
+  });
+
+  const entries = provenanceEntries ?? [];
+  const synced = entries.filter((e) => e.status === "synced");
+  const errors = entries.filter((e) => e.status === "error");
+  const orphaned = entries.filter((e) => e.status === "orphaned");
+
+  const statusIcon = (status: Provenance["status"]) => {
+    switch (status) {
+      case "synced": {
+        return <CheckCircle className="w-4 h-4 text-emerald-500" />;
+      }
+      case "error": {
+        return <XCircle className="w-4 h-4 text-destructive" />;
+      }
+      case "orphaned": {
+        return <AlertTriangle className="w-4 h-4 text-amber-500" />;
+      }
+    }
+  };
+
+  const statusBadge = (status: Provenance["status"]) => {
+    const variants: Record<Provenance["status"], "default" | "destructive" | "outline"> = {
+      synced: "default",
+      error: "destructive",
+      orphaned: "outline",
+    };
+    return <Badge variant={variants[status]}>{status}</Badge>;
+  };
+
+  const renderEntryList = (list: Provenance[], showOrphanActions: boolean) => (
+    <div className="space-y-2">
+      {list.map((entry) => (
+        <div
+          key={entry.id}
+          className="flex items-center justify-between p-3 rounded-lg border border-border bg-background/50"
+        >
+          <div className="flex items-center gap-3 min-w-0">
+            {statusIcon(entry.status)}
+            <div className="min-w-0">
+              <div className="text-sm font-medium">
+                <span className="text-muted-foreground">{entry.kind}/</span>
+                {entry.entityName}
+              </div>
+              <div className="text-xs text-muted-foreground mt-0.5 truncate">
+                {entry.repository}/{entry.filePath}
+              </div>
+              {entry.errorMessage && (
+                <div className="text-xs text-destructive mt-0.5 truncate">
+                  {entry.errorMessage}
+                </div>
+              )}
+            </div>
+          </div>
+
+          <div className="flex items-center gap-2 shrink-0">
+            {statusBadge(entry.status)}
+            {showOrphanActions && canManage && (
+              <>
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  onClick={() =>
+                    setConfirmModal({
+                      isOpen: true,
+                      provenanceId: entry.id,
+                      entityName: `${entry.kind}/${entry.entityName}`,
+                    })
+                  }
+                  title="Confirm deletion"
+                >
+                  <Trash2 className="w-4 h-4" />
+                </Button>
+                <Button
+                  variant="ghost"
+                  size="icon"
+                  onClick={() => dismissMutation.mutate({ provenanceId: entry.id })}
+                  title="Dismiss orphan"
+                >
+                  <X className="w-4 h-4" />
+                </Button>
+              </>
+            )}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+
+  return (
+    <>
+      <div className="space-y-6">
+        {/* Summary */}
+        <div className="grid grid-cols-3 gap-4">
+          <Card>
+            <CardContent className="pt-6">
+              <div className="flex items-center gap-2">
+                <CheckCircle className="w-5 h-5 text-emerald-500" />
+                <span className="text-2xl font-bold">{synced.length}</span>
+                <span className="text-sm text-muted-foreground">Synced</span>
+              </div>
+            </CardContent>
+          </Card>
+          <Card>
+            <CardContent className="pt-6">
+              <div className="flex items-center gap-2">
+                <XCircle className="w-5 h-5 text-destructive" />
+                <span className="text-2xl font-bold">{errors.length}</span>
+                <span className="text-sm text-muted-foreground">Errors</span>
+              </div>
+            </CardContent>
+          </Card>
+          <Card>
+            <CardContent className="pt-6">
+              <div className="flex items-center gap-2">
+                <AlertTriangle className="w-5 h-5 text-amber-500" />
+                <span className="text-2xl font-bold">{orphaned.length}</span>
+                <span className="text-sm text-muted-foreground">Orphaned</span>
+              </div>
+            </CardContent>
+          </Card>
+        </div>
+
+        {/* Orphaned entities — shown first if any */}
+        {orphaned.length > 0 && (
+          <Card>
+            <CardHeader>
+              <CardHeaderRow>
+                <CardTitle className="flex items-center gap-2">
+                  <AlertTriangle className="w-5 h-5 text-amber-500" />
+                  Orphaned Entities
+                </CardTitle>
+              </CardHeaderRow>
+              <p className="text-xs text-muted-foreground mt-1">
+                These entities were removed from Git. Confirm deletion or dismiss to keep the entity.
+              </p>
+            </CardHeader>
+            <CardContent>{renderEntryList(orphaned, true)}</CardContent>
+          </Card>
+        )}
+
+        {/* Errors */}
+        {errors.length > 0 && (
+          <Card>
+            <CardHeader>
+              <CardTitle className="flex items-center gap-2">
+                <XCircle className="w-5 h-5 text-destructive" />
+                Sync Errors
+              </CardTitle>
+            </CardHeader>
+            <CardContent>{renderEntryList(errors, false)}</CardContent>
+          </Card>
+        )}
+
+        {/* Synced entities */}
+        <Card>
+          <CardHeader>
+            <CardTitle className="flex items-center gap-2">
+              <CheckCircle className="w-5 h-5 text-emerald-500" />
+              Synced Entities
+            </CardTitle>
+          </CardHeader>
+          <CardContent>
+            {isLoading ? (
+              <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."
+              />
+            ) : (
+              renderEntryList(synced, false)
+            )}
+          </CardContent>
+        </Card>
+      </div>
+
+      <ConfirmationModal
+        isOpen={confirmModal.isOpen}
+        onClose={() => setConfirmModal({ isOpen: false, provenanceId: "", entityName: "" })}
+        onConfirm={() => confirmDeleteMutation.mutate({ provenanceId: confirmModal.provenanceId })}
+        title="Confirm Orphan Deletion"
+        message={`Are you sure you want to permanently delete "${confirmModal.entityName}"? This will remove the entity from the system.`}
+        confirmText="Delete"
+        variant="danger"
+      />
+    </>
+  );
+};

package/src/components/ProviderEditor.tsx

@@ -0,0 +1,214 @@
+import React, { useState, useEffect } from "react";
+import {
+  Button,
+  Input,
+  Label,
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogHeader,
+  DialogTitle,
+  DialogFooter,
+} from "@checkstack/ui";
+
+interface ProviderEditorProps {
+  open: boolean;
+  onClose: () => void;
+  onSave: (data: {
+    type: "github" | "gitlab";
+    target: string;
+    pathPattern: string;
+    baseUrl?: string;
+    authToken?: string;
+    syncInterval?: number;
+    deletionPolicy?: "orphan" | "auto";
+  }) => void;
+  initialData?: {
+    id: string;
+    type: "github" | "gitlab";
+    target: string;
+    pathPattern: string;
+    baseUrl?: string;
+    syncInterval: number;
+    deletionPolicy: "orphan" | "auto";
+  };
+}
+
+export const ProviderEditor: React.FC<ProviderEditorProps> = ({
+  open,
+  onClose,
+  onSave,
+  initialData,
+}) => {
+  const [type, setType] = useState<"github" | "gitlab">(initialData?.type ?? "github");
+  const [target, setTarget] = useState(initialData?.target ?? "");
+  const [pathPattern, setPathPattern] = useState(initialData?.pathPattern ?? ".checkstack/**/*.yaml");
+  const [baseUrl, setBaseUrl] = useState(initialData?.baseUrl ?? "");
+  const [authToken, setAuthToken] = useState("");
+  const [syncInterval, setSyncInterval] = useState(String(initialData?.syncInterval ?? 300));
+  const [deletionPolicy, setDeletionPolicy] = useState<"orphan" | "auto">(
+    initialData?.deletionPolicy ?? "orphan",
+  );
+
+  useEffect(() => {
+    if (open) {
+      setType(initialData?.type ?? "github");
+      setTarget(initialData?.target ?? "");
+      setPathPattern(initialData?.pathPattern ?? ".checkstack/**/*.yaml");
+      setBaseUrl(initialData?.baseUrl ?? "");
+      setAuthToken("");
+      setSyncInterval(String(initialData?.syncInterval ?? 300));
+      setDeletionPolicy(initialData?.deletionPolicy ?? "orphan");
+    }
+  }, [open, initialData]);
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!target.trim() || !pathPattern.trim()) return;
+
+    onSave({
+      type,
+      target: target.trim(),
+      pathPattern: pathPattern.trim(),
+      baseUrl: baseUrl.trim() || undefined,
+      authToken: authToken.trim() || undefined,
+      syncInterval: Number(syncInterval) || 300,
+      deletionPolicy,
+    });
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={(isOpen) => !isOpen && onClose()}>
+      <DialogContent size="default">
+        <form onSubmit={handleSubmit}>
+          <DialogHeader>
+            <DialogTitle>
+              {initialData ? "Edit Provider" : "Add Provider"}
+            </DialogTitle>
+            <DialogDescription className="sr-only">
+              {initialData
+                ? "Modify the settings for this Git provider"
+                : "Configure a new Git provider for GitOps syncing"}
+            </DialogDescription>
+          </DialogHeader>
+
+          <div className="space-y-4 py-4">
+            <div className="space-y-2">
+              <Label htmlFor="provider-type">Provider Type</Label>
+              <Select
+                value={type}
+                onValueChange={(v) => setType(v as "github" | "gitlab")}
+                disabled={!!initialData}
+              >
+                <SelectTrigger id="provider-type">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="github">GitHub</SelectItem>
+                  <SelectItem value="gitlab">GitLab</SelectItem>
+                </SelectContent>
+              </Select>
+            </div>
+
+            <div className="space-y-2">
+              <Label htmlFor="provider-target">Target</Label>
+              <Input
+                id="provider-target"
+                placeholder="e.g. my-org or my-org/my-repo"
+                value={target}
+                onChange={(e) => setTarget(e.target.value)}
+                required
+              />
+              <p className="text-xs text-muted-foreground">
+                Organization name for org-wide scanning, or owner/repo for a single repository.
+              </p>
+            </div>
+
+            <div className="space-y-2">
+              <Label htmlFor="provider-path">Path Pattern</Label>
+              <Input
+                id="provider-path"
+                placeholder=".checkstack/**/*.yaml"
+                value={pathPattern}
+                onChange={(e) => setPathPattern(e.target.value)}
+                required
+              />
+              <p className="text-xs text-muted-foreground">
+                Glob pattern for matching descriptor files in repositories.
+              </p>
+            </div>
+
+            <div className="space-y-2">
+              <Label htmlFor="provider-base-url">Base URL (optional)</Label>
+              <Input
+                id="provider-base-url"
+                placeholder="https://github.example.com/api/v3"
+                value={baseUrl}
+                onChange={(e) => setBaseUrl(e.target.value)}
+              />
+              <p className="text-xs text-muted-foreground">
+                For GitHub Enterprise or self-hosted GitLab instances.
+              </p>
+            </div>
+
+            <div className="space-y-2">
+              <Label htmlFor="provider-auth-token">
+                Auth Token {initialData ? "(leave empty to keep current)" : "(optional)"}
+              </Label>
+              <Input
+                id="provider-auth-token"
+                type="password"
+                placeholder="ghp_xxxx..."
+                value={authToken}
+                onChange={(e) => setAuthToken(e.target.value)}
+              />
+            </div>
+
+            <div className="grid grid-cols-2 gap-4">
+              <div className="space-y-2">
+                <Label htmlFor="provider-interval">Sync Interval (seconds)</Label>
+                <Input
+                  id="provider-interval"
+                  type="number"
+                  min={60}
+                  value={syncInterval}
+                  onChange={(e) => setSyncInterval(e.target.value)}
+                />
+              </div>
+
+              <div className="space-y-2">
+                <Label htmlFor="provider-deletion">Deletion Policy</Label>
+                <Select
+                  value={deletionPolicy}
+                  onValueChange={(v) => setDeletionPolicy(v as "orphan" | "auto")}
+                >
+                  <SelectTrigger id="provider-deletion">
+                    <SelectValue />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="orphan">Orphan (manual review)</SelectItem>
+                    <SelectItem value="auto">Auto-delete</SelectItem>
+                  </SelectContent>
+                </Select>
+              </div>
+            </div>
+          </div>
+
+          <DialogFooter>
+            <Button type="button" variant="outline" onClick={onClose}>
+              Cancel
+            </Button>
+            <Button type="submit" disabled={!target.trim() || !pathPattern.trim()}>
+              {initialData ? "Save Changes" : "Add Provider"}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+};