@checkstack/gitops-common 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @checkstack/gitops-common
 
+## 0.3.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.
+
+### Patch Changes
+
+- Updated dependencies [42abfff]
+  - @checkstack/common@0.9.0
+
 ## 0.2.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/gitops-common",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -9,14 +9,14 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.7.0",
+    "@checkstack/common": "0.8.0",
     "@orpc/contract": "^1.13.14",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "typescript": "^5.7.2",
-    "@checkstack/tsconfig": "0.0.6",
-    "@checkstack/scripts": "0.1.2"
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.3.0"
   },
   "scripts": {
     "typecheck": "tsgo -b",

package/src/index.ts

@@ -36,3 +36,7 @@ export {
   type DeletionPolicy,
 } from "./provenance-types";
 export { gitopsContract, GitOpsApi, type GitOpsContract } from "./rpc-contract";
+export {
+  deriveSourceUrl,
+  type DeriveSourceUrlInput,
+} from "./source-url";

package/src/provenance-types.ts

@@ -16,6 +16,12 @@ export const provenanceSchema = z.object({
   providerId: z.string(),
   repository: z.string(),
   filePath: z.string(),
+  /**
+   * Browsable web URL pointing to the entity's defining file in its source
+   * provider, derived from the provider type, baseUrl, repository and filePath.
+   * Null when the URL cannot be safely derived (unknown baseUrl shape, etc.).
+   */
+  sourceUrl: z.string().nullable(),
   lastSyncHash: z.string(),
   status: provenanceStatusSchema,
   errorMessage: z.string().nullable(),

package/src/source-url.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, test } from "bun:test";
+import { deriveSourceUrl } from "./source-url";
+
+describe("deriveSourceUrl", () => {
+  test("public github.com", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "github",
+        baseUrl: null,
+        repository: "acme/checkstack",
+        filePath: "catalog/system.yaml",
+      }),
+    ).toBe("https://github.com/acme/checkstack/blob/HEAD/catalog/system.yaml");
+  });
+
+  test("public gitlab.com", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "gitlab",
+        baseUrl: null,
+        repository: "acme/checkstack",
+        filePath: "catalog/system.yaml",
+      }),
+    ).toBe(
+      "https://gitlab.com/acme/checkstack/-/blob/HEAD/catalog/system.yaml",
+    );
+  });
+
+  test("api.github.com baseUrl maps to public host", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "github",
+        baseUrl: "https://api.github.com",
+        repository: "acme/checkstack",
+        filePath: "catalog/system.yaml",
+      }),
+    ).toBe("https://github.com/acme/checkstack/blob/HEAD/catalog/system.yaml");
+  });
+
+  test("github enterprise baseUrl strips /api/v3", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "github",
+        baseUrl: "https://github.example.com/api/v3",
+        repository: "acme/checkstack",
+        filePath: "catalog/system.yaml",
+      }),
+    ).toBe(
+      "https://github.example.com/acme/checkstack/blob/HEAD/catalog/system.yaml",
+    );
+  });
+
+  test("self-hosted gitlab baseUrl strips /api/v4", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "gitlab",
+        baseUrl: "https://gitlab.example.com/api/v4",
+        repository: "team/sub/checkstack",
+        filePath: "catalog/system.yaml",
+      }),
+    ).toBe(
+      "https://gitlab.example.com/team/sub/checkstack/-/blob/HEAD/catalog/system.yaml",
+    );
+  });
+
+  test("nested gitlab namespaces preserved", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "gitlab",
+        baseUrl: null,
+        repository: "group/sub/project",
+        filePath: "a/b.yaml",
+      }),
+    ).toBe("https://gitlab.com/group/sub/project/-/blob/HEAD/a/b.yaml");
+  });
+
+  test("encodes spaces and special characters in path segments", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "github",
+        baseUrl: null,
+        repository: "acme/checkstack",
+        filePath: "catalog/my system.yaml",
+      }),
+    ).toBe(
+      "https://github.com/acme/checkstack/blob/HEAD/catalog/my%20system.yaml",
+    );
+  });
+
+  test("strips leading slashes from filePath", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "github",
+        baseUrl: null,
+        repository: "acme/checkstack",
+        filePath: "/catalog/system.yaml",
+      }),
+    ).toBe("https://github.com/acme/checkstack/blob/HEAD/catalog/system.yaml");
+  });
+
+  test("returns null for unknown self-hosted baseUrl", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "github",
+        baseUrl: "https://github.example.com/some/weird/path",
+        repository: "acme/checkstack",
+        filePath: "catalog/system.yaml",
+      }),
+    ).toBeNull();
+  });
+
+  test("returns null for traversal attempts", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "github",
+        baseUrl: null,
+        repository: "acme/checkstack",
+        filePath: "../etc/passwd",
+      }),
+    ).toBeNull();
+  });
+
+  test("returns null for empty inputs", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "github",
+        baseUrl: null,
+        repository: "",
+        filePath: "x.yaml",
+      }),
+    ).toBeNull();
+    expect(
+      deriveSourceUrl({
+        providerType: "github",
+        baseUrl: null,
+        repository: "a/b",
+        filePath: "",
+      }),
+    ).toBeNull();
+  });
+
+  test("returns null for malformed baseUrl", () => {
+    expect(
+      deriveSourceUrl({
+        providerType: "github",
+        baseUrl: "not a url",
+        repository: "acme/checkstack",
+        filePath: "x.yaml",
+      }),
+    ).toBeNull();
+  });
+});

package/src/source-url.ts

@@ -0,0 +1,89 @@
+/**
+ * Derive a human-browsable source URL for a GitOps-managed entity.
+ *
+ * Returns null when we don't have enough information to construct a stable URL
+ * (e.g., unknown provider type or a malformed `repository` value). Callers
+ * should fall back to displaying the raw `repository`/`filePath` text.
+ *
+ * The URL points at the file on the default branch via the `HEAD` ref so we
+ * don't need to know the branch name. Both GitHub and GitLab resolve `HEAD`
+ * server-side for blob URLs.
+ */
+export interface DeriveSourceUrlInput {
+  providerType: "github" | "gitlab";
+  /** The provider's `baseUrl` (API base) — null for public github.com/gitlab.com. */
+  baseUrl: string | null;
+  /** GitHub: `owner/repo`. GitLab: `group/project` (or nested `group/sub/project`). */
+  repository: string;
+  filePath: string;
+}
+
+const GITHUB_PUBLIC_HOST = "https://github.com";
+const GITLAB_PUBLIC_HOST = "https://gitlab.com";
+
+const stripApiSuffix = ({
+  providerType,
+  baseUrl,
+}: {
+  providerType: "github" | "gitlab";
+  baseUrl: string;
+}): string | null => {
+  // We only know how to strip the well-known API path suffixes. Anything else
+  // we treat as untrusted and bail out — better to fall back to text than to
+  // construct a broken link.
+  try {
+    const url = new URL(baseUrl);
+    if (providerType === "github") {
+      // api.github.com → github.com (public host has no API path component)
+      if (url.host === "api.github.com") return GITHUB_PUBLIC_HOST;
+      // GitHub Enterprise: https://github.example.com/api/v3
+      if (url.pathname.replace(/\/$/, "") === "/api/v3") {
+        return `${url.protocol}//${url.host}`;
+      }
+      return null;
+    }
+    // GitLab: https://gitlab.example.com/api/v4
+    if (url.pathname.replace(/\/$/, "") === "/api/v4") {
+      return `${url.protocol}//${url.host}`;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
+
+const encodeFilePath = (filePath: string) =>
+  filePath
+    .replace(/^\/+/, "")
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+
+export const deriveSourceUrl = ({
+  providerType,
+  baseUrl,
+  repository,
+  filePath,
+}: DeriveSourceUrlInput): string | null => {
+  if (!repository || !filePath) return null;
+  // Reject backslashes and absolute-looking paths to keep things tidy.
+  if (repository.includes("..") || filePath.includes("..")) return null;
+
+  const host = baseUrl
+    ? stripApiSuffix({ providerType, baseUrl })
+    : providerType === "github"
+      ? GITHUB_PUBLIC_HOST
+      : GITLAB_PUBLIC_HOST;
+  if (!host) return null;
+
+  const repoPath = repository
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+  const encodedFile = encodeFilePath(filePath);
+
+  if (providerType === "github") {
+    return `${host}/${repoPath}/blob/HEAD/${encodedFile}`;
+  }
+  return `${host}/${repoPath}/-/blob/HEAD/${encodedFile}`;
+};