@checkstack/gitops-common 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# @checkstack/gitops-common
+
+## 0.1.0
+
+### Minor Changes
+
+- 6c40b5b: feat: add GitOps Entity System foundation — entity envelope schema, Entity Kind Registry extension point, secret field utility, secret resolution engine, provenance tracking, and RPC contract
+- 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: ### GitOps Ecosystem: Healthcheck Kind Registration (Phase 5)
+
+  **gitops-common**: Added required `resolveEntityRef` to `ReconcileContext`, enabling extension reconcilers to resolve cross-kind entity references (e.g., healthcheck refs in System extensions).
+
+  **gitops-backend**: Updated reconciler to populate `resolveEntityRef` by querying local provenance — no RPC round-trip needed.
+
+  **healthcheck-backend**: Registered `kind: Healthcheck` and `System → healthchecks` extension with the EntityKindRegistry:
+
+  - Validates strategy configs against registered strategy schemas at reconcile time
+  - Validates collector configs against registered collector schemas at reconcile time
+  - Manages system ↔ healthcheck associations with automatic stale removal
+
+  **healthcheck-frontend**: Added GitOps provenance locking to the HealthCheck IDE editor — GitOps-managed health checks show a lock banner and disable editing.
+
+  **catalog-backend**: Updated test fixtures for new required `resolveEntityRef` context field.
+
+- 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`

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@checkstack/gitops-common",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "0.6.5",
+    "@orpc/contract": "^1.13.14",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/scripts": "0.1.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/access.ts

@@ -0,0 +1,47 @@
+import { access, accessPair } from "@checkstack/common";
+
+/**
+ * Access rules for the GitOps plugin.
+ */
+export const gitopsAccess = {
+  /** Provider management (add/edit/remove Git providers). */
+  provider: accessPair("provider", {
+    read: {
+      description: "View GitOps providers and sync status",
+      isDefault: true,
+    },
+    manage: {
+      description: "Add, edit, and remove GitOps providers",
+    },
+  }),
+
+  /** Secret management for secretRef values. */
+  secret: accessPair("secret", {
+    read: {
+      description: "View secret names (not values)",
+      isDefault: true,
+    },
+    manage: {
+      description: "Create, rotate, and delete secrets",
+    },
+  }),
+
+  /** Kind registry browsing. */
+  kinds: {
+    read: access("kinds", "read", "View entity kind definitions and schemas", {
+      isDefault: true,
+    }),
+  },
+};
+
+/**
+ * All access rules for registration with the plugin system.
+ */
+export const gitopsAccessRules = [
+  gitopsAccess.provider.read,
+  gitopsAccess.provider.manage,
+  gitopsAccess.secret.read,
+  gitopsAccess.secret.manage,
+  gitopsAccess.kinds.read,
+];
+

package/src/entity-envelope.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from "bun:test";
+import {
+  entityEnvelopeSchema,
+  CHECKSTACK_API_VERSION,
+} from "./entity-envelope";
+
+describe("entityEnvelopeSchema", () => {
+  it("accepts a valid entity envelope", () => {
+    const result = entityEnvelopeSchema.safeParse({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      metadata: {
+        name: "payment-service",
+        title: "Payment Service",
+        description: "Handles payments",
+        labels: { team: "platform" },
+        annotations: { "pagerduty.com/service-id": "PD123" },
+        tags: ["production"],
+      },
+      spec: { description: "test" },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("accepts a minimal entity envelope (only required fields)", () => {
+    const result = entityEnvelopeSchema.safeParse({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      metadata: { name: "my-system" },
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects metadata.name with uppercase characters", () => {
+    const result = entityEnvelopeSchema.safeParse({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      metadata: { name: "MySystem" },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects metadata.name exceeding 63 characters", () => {
+    const result = entityEnvelopeSchema.safeParse({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      metadata: { name: "a".repeat(64) },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects metadata.name starting with a hyphen", () => {
+    const result = entityEnvelopeSchema.safeParse({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      metadata: { name: "-invalid" },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects missing apiVersion", () => {
+    const result = entityEnvelopeSchema.safeParse({
+      kind: "System",
+      metadata: { name: "test" },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects invalid apiVersion format", () => {
+    const result = entityEnvelopeSchema.safeParse({
+      apiVersion: "invalid",
+      kind: "System",
+      metadata: { name: "test" },
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects empty kind", () => {
+    const result = entityEnvelopeSchema.safeParse({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "",
+      metadata: { name: "test" },
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/entity-envelope.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+
+/**
+ * The current Checkstack API version for entity descriptors.
+ */
+export const CHECKSTACK_API_VERSION = "checkstack.io/v1alpha1";
+
+/**
+ * Regex for valid entity names.
+ * Must start with a lowercase letter or digit, followed by lowercase letters, digits, or hyphens.
+ * Maximum 63 characters (aligned with Backstage/Kubernetes conventions).
+ */
+const entityNameRegex = /^[a-z0-9][a-z0-9-]*$/;
+
+/**
+ * Schema for the entity metadata block.
+ * These fields are common to ALL entity kinds.
+ */
+export const entityMetadataSchema = z.object({
+  /** URL-safe unique identifier. Lowercase alphanumeric + hyphens, max 63 chars. */
+  name: z
+    .string()
+    .regex(
+      entityNameRegex,
+      "Must be lowercase alphanumeric with hyphens, starting with a letter or digit",
+    )
+    .max(63, "Entity name must not exceed 63 characters"),
+
+  /** Optional human-readable display name. */
+  title: z.string().optional(),
+
+  /** Optional description. */
+  description: z.string().optional(),
+
+  /** Optional key-value pairs for filtering and organizing. */
+  labels: z.record(z.string(), z.string()).optional(),
+
+  /** Optional key-value pairs for machine-readable metadata. */
+  annotations: z.record(z.string(), z.string()).optional(),
+
+  /** Optional string tags for categorization. */
+  tags: z.array(z.string()).optional(),
+});
+
+export type EntityMetadata = z.infer<typeof entityMetadataSchema>;
+
+/**
+ * Schema for the base entity envelope.
+ * All YAML descriptors must conform to this shape.
+ * The `spec` field is validated per-kind by the Entity Kind Registry.
+ */
+export const entityEnvelopeSchema = z.object({
+  /** Versioned API identifier (e.g., "checkstack.io/v1alpha1"). */
+  apiVersion: z
+    .string()
+    .regex(
+      /^[\w.-]+\/v[\w.]+$/,
+      "Must follow format: domain/version (e.g., checkstack.io/v1alpha1)",
+    ),
+
+  /** The entity kind (e.g., "System", "Healthcheck"). Must be registered. */
+  kind: z.string().min(1, "Kind must not be empty"),
+
+  /** Common metadata fields. */
+  metadata: entityMetadataSchema,
+
+  /** Kind-specific specification. Validated by the kind's registered schema. */
+  spec: z.record(z.string(), z.unknown()).optional(),
+});
+
+export type EntityEnvelope = z.infer<typeof entityEnvelopeSchema>;

package/src/entity-kind-registry.ts

@@ -0,0 +1,116 @@
+import { z } from "zod";
+import type { EntityEnvelope } from "./entity-envelope";
+
+/**
+ * Context passed to reconcile/delete functions.
+ * Extended by gitops-backend with concrete service references.
+ */
+export interface ReconcileContext {
+  /** Logger scoped to this reconciliation */
+  logger: {
+    debug: (msg: string) => void;
+    info: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+  };
+
+  /**
+   * Resolve a GitOps entity reference to its plugin-specific entity ID.
+   * Used by extension reconcilers to look up cross-kind references
+   * (e.g., a System extension resolving a Healthcheck ref name → config UUID).
+   *
+   * Returns `undefined` if the entity is not found in provenance.
+   */
+  resolveEntityRef: (params: {
+    kind: string;
+    entityName: string;
+  }) => Promise<string | undefined>;
+}
+
+/**
+ * Definition for registering a new entity kind.
+ * The owning plugin provides the base spec schema and reconciliation logic.
+ */
+export interface EntityKindDefinition<TSpec = unknown> {
+  /** The API version this kind belongs to (e.g., "checkstack.io/v1alpha1"). */
+  apiVersion: string;
+
+  /** The kind name (e.g., "System", "Healthcheck"). Must be unique per apiVersion. */
+  kind: string;
+
+  /** Zod schema for validating the `spec` section of descriptors of this kind. */
+  specSchema: z.ZodType<TSpec>;
+
+  /**
+   * Called when an entity of this kind is discovered or updated via GitOps.
+   * The entity's spec is fully validated and all secretRef values are resolved.
+   *
+   * Must return the plugin-specific entity ID (e.g., the catalog system UUID).
+   * The reconciler engine stores this in provenance for generic frontend lookups.
+   */
+  reconcile: (params: {
+    entity: EntityEnvelope & { spec: TSpec };
+    /** The plugin-specific entity ID from a previous reconcile, if this entity was reconciled before. */
+    existingEntityId?: string;
+    context: ReconcileContext;
+  }) => Promise<{ entityId: string }>;
+
+  /**
+   * Called when an entity of this kind is removed from git (deletion policy: "auto")
+   * or when an orphan is manually confirmed for deletion.
+   */
+  delete?: (params: {
+    entityName: string;
+    /** The plugin-specific entity ID from provenance, if available. */
+    entityId?: string;
+    context: ReconcileContext;
+  }) => Promise<void>;
+}
+
+/**
+ * Definition for extending an existing entity kind's spec.
+ * The extending plugin adds namespaced fields to another kind's spec schema.
+ */
+export interface EntityKindExtensionDefinition<TExtensionSpec = unknown> {
+  /** The API version of the kind being extended. */
+  apiVersion: string;
+
+  /** The kind being extended (e.g., "System"). */
+  kind: string;
+
+  /**
+   * Namespace for this extension's spec fields.
+   * The extension's spec is placed under `spec.<namespace>` in the descriptor.
+   * Must be unique per kind. Convention: use your plugin ID (e.g., "healthcheck").
+   */
+  namespace: string;
+
+  /** Zod schema for validating the extension's spec fields. Should be `.optional()`. */
+  specSchema: z.ZodType<TExtensionSpec>;
+
+  /**
+   * Called when an entity with this extension's namespace is reconciled.
+   * Only called if the extension's namespace is present in the spec.
+   */
+  reconcile: (params: {
+    entity: EntityEnvelope;
+    extensionSpec: TExtensionSpec;
+    /** The plugin-specific entity ID returned by the base kind's reconciler. */
+    entityId: string;
+    context: ReconcileContext;
+  }) => Promise<void>;
+}
+
+/**
+ * The registry interface exposed via the Extension Point.
+ * Plugins call these methods during their `register()` phase.
+ */
+export interface EntityKindRegistry {
+  /** Register a new entity kind (e.g., catalog registers "System"). */
+  registerKind<TSpec>(definition: EntityKindDefinition<TSpec>): void;
+
+  /** Extend an existing kind's spec (e.g., healthcheck extends "System"). */
+  registerKindExtension<TExtensionSpec>(
+    definition: EntityKindExtensionDefinition<TExtensionSpec>,
+  ): void;
+}

package/src/entity-ref.test.ts

@@ -0,0 +1,126 @@
+import { describe, expect, it } from "bun:test";
+import {
+  entityRefSchema,
+  extractEntityRefs,
+  type EntityRef,
+} from "./entity-ref";
+
+describe("entityRefSchema", () => {
+  it("validates a well-formed entity ref", () => {
+    const result = entityRefSchema.safeParse({
+      kind: "Healthcheck",
+      name: "payment-db-check",
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it("rejects missing kind", () => {
+    const result = entityRefSchema.safeParse({ name: "foo" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects missing name", () => {
+    const result = entityRefSchema.safeParse({ kind: "System" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects empty kind", () => {
+    const result = entityRefSchema.safeParse({ kind: "", name: "foo" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects empty name", () => {
+    const result = entityRefSchema.safeParse({ kind: "System", name: "" });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("extractEntityRefs", () => {
+  it("extracts a single ref from a flat object", () => {
+    const spec = {
+      ref: { kind: "Healthcheck", name: "db-check" },
+    };
+    const refs = extractEntityRefs(spec);
+    expect(refs).toEqual([{ kind: "Healthcheck", name: "db-check" }]);
+  });
+
+  it("extracts multiple refs from an array", () => {
+    const spec = {
+      healthchecks: [
+        { ref: { kind: "Healthcheck", name: "db-check" } },
+        { ref: { kind: "Healthcheck", name: "api-check" } },
+      ],
+    };
+    const refs = extractEntityRefs(spec);
+    expect(refs).toEqual([
+      { kind: "Healthcheck", name: "db-check" },
+      { kind: "Healthcheck", name: "api-check" },
+    ]);
+  });
+
+  it("extracts refs from deeply nested structures", () => {
+    const spec = {
+      level1: {
+        level2: {
+          level3: { kind: "System", name: "nested-sys" },
+        },
+      },
+    };
+    const refs = extractEntityRefs(spec);
+    expect(refs).toEqual([{ kind: "System", name: "nested-sys" }]);
+  });
+
+  it("ignores objects with non-string kind or name", () => {
+    const spec = {
+      notARef1: { kind: 123, name: "foo" },
+      notARef2: { kind: "System", name: 456 },
+      notARef3: { kind: true, name: false },
+    };
+    const refs = extractEntityRefs(spec);
+    expect(refs).toEqual([]);
+  });
+
+  it("ignores objects with empty kind or name", () => {
+    const spec = {
+      emptyKind: { kind: "", name: "foo" },
+      emptyName: { kind: "System", name: "" },
+    };
+    const refs = extractEntityRefs(spec);
+    expect(refs).toEqual([]);
+  });
+
+  it("ignores primitives, nulls, and strings", () => {
+    const spec = {
+      str: "just a string",
+      num: 42,
+      bool: true,
+      nil: null,
+    };
+    const refs = extractEntityRefs(spec);
+    expect(refs).toEqual([]);
+  });
+
+  it("does not recurse into matched refs (no double-counting)", () => {
+    const ref: EntityRef = { kind: "Healthcheck", name: "db-check" };
+    const spec = { ref };
+    const refs = extractEntityRefs(spec);
+    // Should find exactly one ref, not recurse into it
+    expect(refs).toHaveLength(1);
+  });
+
+  it("handles mixed valid and invalid entries", () => {
+    const spec = {
+      items: [
+        { ref: { kind: "Healthcheck", name: "valid" } },
+        { ref: "invalid-string" },
+        { ref: { kind: "System", name: "also-valid" } },
+        { ref: null },
+      ],
+    };
+    const refs = extractEntityRefs(spec);
+    expect(refs).toEqual([
+      { kind: "Healthcheck", name: "valid" },
+      { kind: "System", name: "also-valid" },
+    ]);
+  });
+});

package/src/entity-ref.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+
+/**
+ * K8s-style structured entity reference.
+ * Used in YAML specs to reference other GitOps-managed entities.
+ *
+ * @example
+ * ```yaml
+ * healthchecks:
+ *   - ref:
+ *       kind: Healthcheck
+ *       name: payment-db-check
+ * ```
+ */
+export const entityRefSchema = z.object({
+  kind: z.string().min(1),
+  name: z.string().min(1),
+});
+
+export type EntityRef = z.infer<typeof entityRefSchema>;
+
+/**
+ * Check if a value is a valid EntityRef shape (object with string `kind` and `name`).
+ */
+function isEntityRef(value: unknown): value is EntityRef {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const obj = value as Record<string, unknown>;
+  return (
+    typeof obj.kind === "string" &&
+    obj.kind.length > 0 &&
+    typeof obj.name === "string" &&
+    obj.name.length > 0
+  );
+}
+
+/**
+ * Recursively extract all entity refs from a spec value.
+ *
+ * Walks objects and arrays, collecting objects that have both
+ * a `kind` (non-empty string) and `name` (non-empty string) property.
+ * Matched refs are not recursed into (no double-counting).
+ */
+export function extractEntityRefs(value: unknown): EntityRef[] {
+  const refs: EntityRef[] = [];
+  walk(value, refs);
+  return refs;
+}
+
+function walk(value: unknown, refs: EntityRef[]): void {
+  if (typeof value !== "object" || value === null) {
+    return;
+  }
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      walk(item, refs);
+    }
+    return;
+  }
+
+  // Check if this object IS a ref — collect it and stop recursing
+  if (isEntityRef(value)) {
+    refs.push({ kind: value.kind, name: value.name });
+    return;
+  }
+
+  // Otherwise recurse into child values
+  for (const child of Object.values(value as Record<string, unknown>)) {
+    walk(child, refs);
+  }
+}

package/src/index.ts

@@ -0,0 +1,37 @@
+export { pluginMetadata } from "./plugin-metadata";
+export {
+  entityEnvelopeSchema,
+  entityMetadataSchema,
+  CHECKSTACK_API_VERSION,
+  type EntityEnvelope,
+  type EntityMetadata,
+} from "./entity-envelope";
+export {
+  secretField,
+  secretRefSchema,
+  isSecretRef,
+  type SecretRef,
+  type ResolvedSecretField,
+} from "./secret-field";
+export {
+  entityRefSchema,
+  extractEntityRefs,
+  type EntityRef,
+} from "./entity-ref";
+export {
+  type EntityKindDefinition,
+  type EntityKindExtensionDefinition,
+  type EntityKindRegistry,
+  type ReconcileContext,
+} from "./entity-kind-registry";
+export { gitopsAccess, gitopsAccessRules } from "./access";
+export { gitopsRoutes } from "./routes";
+export {
+  provenanceSchema,
+  provenanceStatusSchema,
+  deletionPolicySchema,
+  type Provenance,
+  type ProvenanceStatus,
+  type DeletionPolicy,
+} from "./provenance-types";
+export { gitopsContract, GitOpsApi, type GitOpsContract } from "./rpc-contract";

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+/**
+ * Plugin metadata for the GitOps plugin.
+ * Exported from the common package so both backend and frontend can reference it.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "gitops",
+});

package/src/provenance-types.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+export const provenanceStatusSchema = z.enum(["synced", "error", "orphaned"]);
+export type ProvenanceStatus = z.infer<typeof provenanceStatusSchema>;
+
+export const deletionPolicySchema = z.enum(["orphan", "auto"]);
+export type DeletionPolicy = z.infer<typeof deletionPolicySchema>;
+
+export const provenanceSchema = z.object({
+  id: z.string(),
+  apiVersion: z.string(),
+  kind: z.string(),
+  entityName: z.string(),
+  /** Plugin-specific entity ID (e.g., catalog system UUID). Set by the reconciler engine. */
+  entityId: z.string(),
+  providerId: z.string(),
+  repository: z.string(),
+  filePath: z.string(),
+  lastSyncHash: z.string(),
+  status: provenanceStatusSchema,
+  errorMessage: z.string().nullable(),
+  lastSyncedAt: z.date(),
+  createdAt: z.date(),
+});
+
+export type Provenance = z.infer<typeof provenanceSchema>;

package/src/routes.ts

@@ -0,0 +1,12 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the GitOps plugin.
+ */
+export const gitopsRoutes = createRoutes("gitops", {
+  home: "/",
+  providers: "/providers",
+  secrets: "/secrets",
+  status: "/status",
+  kinds: "/kinds",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,250 @@
+import { createClientDefinition, proc } from "@checkstack/common";
+import { pluginMetadata } from "./plugin-metadata";
+import { gitopsAccess } from "./access";
+import {
+  provenanceSchema,
+  provenanceStatusSchema,
+  deletionPolicySchema,
+} from "./provenance-types";
+import { z } from "zod";
+
+export const gitopsContract = {
+  // ═══════════════════════════════════════════════════════════════════════════
+  // PROVENANCE QUERIES (public read access)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /** Check if an entity is GitOps-managed. Used by frontends to lock editors. */
+  getProvenance: proc({
+    operationType: "query",
+    userType: "public",
+    access: [gitopsAccess.provider.read],
+  })
+    .input(z.object({
+      kind: z.string(),
+      /** Look up by envelope entity name. */
+      entityName: z.string().optional(),
+      /** Look up by plugin-specific entity ID (e.g., catalog system UUID). */
+      entityId: z.string().optional(),
+    }))
+    .output(provenanceSchema.nullable()),
+
+  /** List all provenance entries, optionally filtered by status. */
+  listProvenance: proc({
+    operationType: "query",
+    userType: "public",
+    access: [gitopsAccess.provider.read],
+  })
+    .input(
+      z
+        .object({
+          status: provenanceStatusSchema.optional(),
+          providerId: z.string().optional(),
+        })
+        .optional(),
+    )
+    .output(z.array(provenanceSchema)),
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // PROVIDER MANAGEMENT (admin)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /** List all configured providers. */
+  listProviders: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [gitopsAccess.provider.read],
+  }).output(
+    z.array(
+      z.object({
+        id: z.string(),
+        type: z.enum(["github", "gitlab"]),
+        target: z.string(),
+        pathPattern: z.string(),
+        baseUrl: z.string().nullable(),
+        syncInterval: z.number(),
+        deletionPolicy: deletionPolicySchema,
+        lastSyncAt: z.date().nullable(),
+        lastSyncError: z.string().nullable(),
+        createdAt: z.date(),
+      }),
+    ),
+  ),
+
+  /** Create a new GitOps provider. */
+  createProvider: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [gitopsAccess.provider.manage],
+  })
+    .input(
+      z.object({
+        type: z.enum(["github", "gitlab"]),
+        target: z.string().min(1),
+        pathPattern: z.string().min(1),
+        baseUrl: z.string().optional(),
+        authToken: z.string().optional(),
+        syncInterval: z.number().int().min(60).optional(),
+        deletionPolicy: deletionPolicySchema.optional(),
+      }),
+    )
+    .output(z.object({ id: z.string() })),
+
+  /** Update an existing provider. */
+  updateProvider: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [gitopsAccess.provider.manage],
+  })
+    .input(
+      z.object({
+        id: z.string(),
+        data: z.object({
+          target: z.string().min(1).optional(),
+          pathPattern: z.string().min(1).optional(),
+          baseUrl: z.string().nullable().optional(),
+          authToken: z.string().optional(),
+          syncInterval: z.number().int().min(60).optional(),
+          deletionPolicy: deletionPolicySchema.optional(),
+        }),
+      }),
+    )
+    .output(z.object({ success: z.boolean() })),
+
+  /** Delete a provider and all its provenance entries. */
+  deleteProvider: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [gitopsAccess.provider.manage],
+  })
+    .input(z.object({ id: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+
+  /** Trigger a manual sync for a provider. */
+  triggerSync: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [gitopsAccess.provider.manage],
+  })
+    .input(z.object({ providerId: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+
+  /** Confirm deletion of an orphaned entity. */
+  confirmOrphanDeletion: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [gitopsAccess.provider.manage],
+  })
+    .input(z.object({ provenanceId: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+
+  /** Dismiss orphan status (keep entity, remove provenance tracking). */
+  dismissOrphan: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [gitopsAccess.provider.manage],
+  })
+    .input(z.object({ provenanceId: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SECRET MANAGEMENT
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /** List secret names (never values). */
+  listSecrets: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [gitopsAccess.secret.read],
+  }).output(
+    z.array(
+      z.object({
+        id: z.string(),
+        name: z.string(),
+        description: z.string().nullable(),
+        createdAt: z.date(),
+        updatedAt: z.date(),
+      }),
+    ),
+  ),
+
+  /** Create a new secret. */
+  createSecret: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [gitopsAccess.secret.manage],
+  })
+    .input(
+      z.object({
+        name: z.string().min(1).max(63),
+        value: z.string().min(1),
+        description: z.string().optional(),
+      }),
+    )
+    .output(z.object({ id: z.string(), name: z.string() })),
+
+  /** Rotate (update) a secret's value. */
+  rotateSecret: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [gitopsAccess.secret.manage],
+  })
+    .input(
+      z.object({
+        id: z.string(),
+        value: z.string().min(1),
+      }),
+    )
+    .output(z.object({ success: z.boolean() })),
+
+  /** Delete a secret. */
+  deleteSecret: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [gitopsAccess.secret.manage],
+  })
+    .input(z.object({ id: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // SERVICE INTERFACE (backend-to-backend)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /** Resolve a secret by name. Used internally by the reconciliation engine. */
+  resolveSecret: proc({
+    operationType: "query",
+    userType: "service",
+    access: [],
+  })
+    .input(z.object({ name: z.string() }))
+    .output(z.object({ value: z.string() })),
+
+  // ═══════════════════════════════════════════════════════════════════════════
+  // KIND REGISTRY (browsing)
+  // ═══════════════════════════════════════════════════════════════════════════
+
+  /** List all registered entity kinds with their spec schemas and extensions. */
+  listKinds: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [gitopsAccess.kinds.read],
+  }).output(
+    z.array(
+      z.object({
+        apiVersion: z.string(),
+        kind: z.string(),
+        specSchema: z.record(z.string(), z.unknown()),
+        extensions: z.array(
+          z.object({
+            namespace: z.string(),
+            specSchema: z.record(z.string(), z.unknown()),
+          }),
+        ),
+      }),
+    ),
+  ),
+};
+
+export type GitOpsContract = typeof gitopsContract;
+
+/** Export client definition for type-safe forPlugin usage. */
+export const GitOpsApi = createClientDefinition(gitopsContract, pluginMetadata);

package/src/secret-field.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "bun:test";
+import { secretField, isSecretRef, type SecretRef } from "./secret-field";
+
+describe("secretField", () => {
+  const schema = secretField();
+
+  it("accepts a plain string value", () => {
+    const result = schema.safeParse("my-password");
+    expect(result.success).toBe(true);
+    if (result.success) expect(result.data).toBe("my-password");
+  });
+
+  it("accepts a secretRef object", () => {
+    const result = schema.safeParse({ secretRef: "prod-db-password" });
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data).toEqual({ secretRef: "prod-db-password" });
+    }
+  });
+
+  it("rejects a number", () => {
+    const result = schema.safeParse(42);
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects an object without secretRef", () => {
+    const result = schema.safeParse({ key: "value" });
+    expect(result.success).toBe(false);
+  });
+
+  it("rejects secretRef with empty name", () => {
+    const result = schema.safeParse({ secretRef: "" });
+    expect(result.success).toBe(false);
+  });
+});
+
+describe("isSecretRef", () => {
+  it("returns true for a SecretRef object", () => {
+    const ref: SecretRef = { secretRef: "my-secret" };
+    expect(isSecretRef(ref)).toBe(true);
+  });
+
+  it("returns false for a plain string", () => {
+    expect(isSecretRef("plain")).toBe(false);
+  });
+
+  it("returns false for null", () => {
+    expect(isSecretRef(null)).toBe(false);
+  });
+});

package/src/secret-field.ts

@@ -0,0 +1,47 @@
+import { z } from "zod";
+
+/**
+ * Schema for a secret reference object.
+ * Used in YAML descriptors to reference secrets stored in the Checkstack secret store.
+ */
+export const secretRefSchema = z.object({
+  secretRef: z.string().min(1, "Secret reference name must not be empty"),
+});
+
+export type SecretRef = z.infer<typeof secretRefSchema>;
+
+/**
+ * Type guard to check if a value is a SecretRef object.
+ */
+export function isSecretRef(value: unknown): value is SecretRef {
+  if (value === null || value === undefined || typeof value !== "object") {
+    return false;
+  }
+  return (
+    "secretRef" in value &&
+    typeof (value as SecretRef).secretRef === "string"
+  );
+}
+
+/**
+ * Creates a Zod schema for fields that accept either a plain string or a secret reference.
+ *
+ * In YAML descriptors, users can write either:
+ * ```yaml
+ * password: "dev-password"              # plain string
+ * password:
+ *   secretRef: production-db-creds      # reference to secret store
+ * ```
+ *
+ * The GitOps reconciliation engine resolves all secretRef values before calling
+ * plugin reconcilers, so plugins always receive plain strings.
+ */
+export function secretField() {
+  return z.union([z.string(), secretRefSchema]);
+}
+
+/**
+ * The resolved type of a secret field is always a string.
+ * After the reconciliation engine resolves secretRefs, all values are plain strings.
+ */
+export type ResolvedSecretField = string;

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "@checkstack/tsconfig/common.json",
+  "include": ["src"]
+}