@checkstack/gitops-common 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @checkstack/gitops-common
 
+## 0.4.0
+
+### Minor Changes
+
+- 9016526: Add a `/rest/:pluginId/*` HTTP mount that serves every plugin's oRPC contract
+  through the REST/OpenAPI shape described by `/api/openapi.json`. Queries are
+  `GET` with query parameters, mutations are `POST` with the input as the raw
+  JSON body. The existing `/api/:pluginId/*` mount continues to serve oRPC's
+  native wire protocol unchanged, so existing clients are not affected.
+
+  The OpenAPI spec at `/api/openapi.json` now reflects the real mount: every
+  `paths` entry is prefixed with `/rest` instead of `/api`.
+
+  Also fixes a SPA-fallback bug: the backend's `/api-docs` route previously
+  returned 404 on production deployments because the static-file middleware
+  skipped any path starting with `/api`, capturing `/api-docs` along with real
+  API routes. The skip now requires a trailing slash (`/api/`, `/rest/`).
+
+  Required access rules are now visible in the API Docs UI. The OpenAPI spec
+  generator was reading a non-existent `accessRules` field on procedure
+  metadata; the real field is `access: AccessRule[]`. Each procedure's access
+  rules are now flattened to fully-qualified IDs (e.g. `catalog.system.read`)
+  and emitted under `x-orpc-meta.accessRules`, which the existing
+  `Required Access Rules` section in the docs UI already knew how to render.
+
+  The API Docs schema renderer now handles record types (zod `z.record`),
+  `$ref`s into `components.schemas`, `oneOf`/`anyOf`/`allOf`, nullable union
+  types (`type: ["string", "null"]`), and `format` qualifiers. Previously
+  record outputs like `{ statuses: object }` masked the actual value type;
+  they now render as `{ [key]: <ResolvedType> { ... } }` with the inner
+  schema expanded, capped at 12 levels with cycle detection.
+
+  **REST method conventions.** `proc()` now defaults to `GET` for queries and
+  `POST` for mutations on the `/rest` mount, using bracket-notation query
+  params (`?filter[status]=active&ids[0]=a`) for GET inputs. Existing
+  procedures were updated to follow REST semantics:
+
+  - `update*` mutations → `PATCH`
+  - `delete*` / `remove*` mutations → `DELETE`
+  - `getBulk*` queries and any query taking a large array input → `POST`
+    (because `@orpc/openapi@1.13.x` has no GET→POST URL-length fallback)
+
+  GET endpoints require an `object` input — bare scalars like
+  `.input(z.string())` are not valid on GET. `getSystemConfigurations` was
+  refactored from `.input(z.string())` to `.input(z.object({ systemId: ... }))`
+  to fit the GET shape; the only call-site update was the in-process router
+  unpacking `input.systemId` instead of passing `input` directly.
+
+  The API Docs UI now renders query parameters (path/query/header/cookie) in a
+  dedicated table for GET endpoints, and the fetch example shows them in the
+  URL with `<required>` / `<optional>` placeholders.
+
+### Patch Changes
+
+- Updated dependencies [9016526]
+  - @checkstack/common@0.10.0
+
+## 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.4.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -9,14 +9,14 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.7.0",
+    "@checkstack/common": "0.9.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.1"
   },
   "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/rpc-contract.ts

@@ -96,6 +96,7 @@ export const gitopsContract = {
     userType: "authenticated",
     access: [gitopsAccess.provider.manage],
   })
+    .route({ method: "PATCH" })
     .input(
       z.object({
         id: z.string(),
@@ -117,6 +118,7 @@ export const gitopsContract = {
     userType: "authenticated",
     access: [gitopsAccess.provider.manage],
   })
+    .route({ method: "DELETE" })
     .input(z.object({ id: z.string() }))
     .output(z.object({ success: z.boolean() })),
 
@@ -203,6 +205,7 @@ export const gitopsContract = {
     userType: "authenticated",
     access: [gitopsAccess.secret.manage],
   })
+    .route({ method: "DELETE" })
     .input(z.object({ id: z.string() }))
     .output(z.object({ success: z.boolean() })),
 

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}`;
+};