@checkstack/gitops-backend 0.1.2 → 0.2.0

package/drizzle/meta/_journal.json

@@ -8,6 +8,20 @@
       "when": 1776797758378,
       "tag": "0000_tense_stryfe",
       "breakpoints": true
+    },
+    {
+      "idx": 1,
+      "version": "7",
+      "when": 1776929187262,
+      "tag": "0001_wandering_leech",
+      "breakpoints": true
+    },
+    {
+      "idx": 2,
+      "version": "7",
+      "when": 1776931984135,
+      "tag": "0002_far_lady_vermin",
+      "breakpoints": true
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/gitops-backend",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,7 +14,7 @@
   },
   "dependencies": {
     "@checkstack/backend-api": "0.12.0",
-    "@checkstack/gitops-common": "0.1.0",
+    "@checkstack/gitops-common": "0.1.1",
     "@checkstack/common": "0.6.5",
     "@checkstack/command-backend": "0.1.19",
     "@checkstack/queue-api": "0.2.13",

package/src/index.ts

@@ -72,6 +72,9 @@ export default createBackendPlugin({
       ) {
         kindRegistry.registerKindExtension(definition);
       },
+      registerSpecSchemaDocumentation(params) {
+        kindRegistry.registerSpecSchemaDocumentation(params);
+      },
     });
 
     env.registerInit({

package/src/kind-registry.test.ts

@@ -207,6 +207,7 @@ describe("EntityKindRegistry", () => {
       const sys = described[0];
       expect(sys.apiVersion).toBe(CHECKSTACK_API_VERSION);
       expect(sys.kind).toBe("System");
+      expect(sys.metadataSchema).toBeDefined();
       expect(sys.specSchema).toBeDefined();
       expect(sys.extensions).toHaveLength(0);
 
@@ -259,4 +260,99 @@ describe("EntityKindRegistry", () => {
       expect(described).toHaveLength(0);
     });
   });
+
+  describe("registerSpecSchemaDocumentation", () => {
+    it("allows registering documentation for different field paths and multiple entries per path", () => {
+      const registry = createEntityKindRegistry();
+
+      registry.registerKind({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        specSchema: z.object({ config: z.unknown(), collectors: z.array(z.unknown()) }),
+        reconcile: async () => ({ entityId: "test-id" }),
+      });
+
+      // Register two strategies for the 'config' field
+      registry.registerSpecSchemaDocumentation({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        fieldPath: "config",
+        variantId: "http-strat",
+        label: "HTTP Strategy",
+        description: "Configure HTTP health check",
+        schema: z.object({ url: z.string() }),
+      });
+
+      registry.registerSpecSchemaDocumentation({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        fieldPath: "config",
+        variantId: "dns-strat",
+        label: "DNS Strategy",
+        schema: z.object({ hostname: z.string() }), // no description
+      });
+
+      // Register a collector for 'collectors[].config'
+      registry.registerSpecSchemaDocumentation({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        fieldPath: "collectors[].config",
+        label: "Ping Collector",
+        description: "Ping something",
+        schema: z.object({ count: z.number() }),
+        conditions: [{
+          fieldPath: "config",
+          variantIds: ["http-strat", "dns-strat"],
+        }],
+      });
+
+      const described = registry.describeKinds();
+      expect(described).toHaveLength(1);
+      
+      const docs = described[0].specSchemaDocumentation;
+      expect(docs).toHaveLength(3);
+
+      const configDocs = docs.filter(d => d.fieldPath === "config");
+      expect(configDocs).toHaveLength(2);
+      expect(configDocs[0].label).toBe("HTTP Strategy");
+      expect(configDocs[0].variantId).toBe("http-strat");
+      expect(configDocs[0].description).toBe("Configure HTTP health check");
+      expect(configDocs[1].label).toBe("DNS Strategy");
+      expect(configDocs[1].variantId).toBe("dns-strat");
+      expect(configDocs[1].description).toBeUndefined();
+
+      const collectorDocs = docs.filter(d => d.fieldPath === "collectors[].config");
+      expect(collectorDocs).toHaveLength(1);
+      expect(collectorDocs[0].label).toBe("Ping Collector");
+      expect(collectorDocs[0].conditions).toBeDefined();
+      expect(collectorDocs[0].conditions?.[0].variantIds).toEqual(["http-strat", "dns-strat"]);
+    });
+
+    it("allows registering docs before the kind itself is registered", () => {
+      const registry = createEntityKindRegistry();
+
+      registry.registerSpecSchemaDocumentation({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        fieldPath: "config",
+        label: "HTTP Strategy",
+        schema: z.object({ url: z.string() }),
+      });
+
+      // Base kind is missing, so describeKinds should skip it
+      expect(registry.describeKinds()).toHaveLength(0);
+
+      registry.registerKind({
+        apiVersion: CHECKSTACK_API_VERSION,
+        kind: "Healthcheck",
+        specSchema: z.object({ config: z.unknown() }),
+        reconcile: async () => ({ entityId: "test-id" }),
+      });
+
+      // Now it should be included
+      const described = registry.describeKinds();
+      expect(described).toHaveLength(1);
+      expect(described[0].specSchemaDocumentation).toHaveLength(1);
+    });
+  });
 });

package/src/kind-registry.ts

@@ -4,12 +4,15 @@ import type {
   EntityKindDefinition,
   EntityKindExtensionDefinition,
   EntityKindRegistry,
+  SpecSchemaDocumentation,
 } from "@checkstack/gitops-common";
+import { entityMetadataSchema } from "@checkstack/gitops-common";
 
 /** Internal storage for a registered kind with its extensions. */
 interface RegisteredKind {
   definition: EntityKindDefinition<unknown> | undefined;
   extensions: Map<string, EntityKindExtensionDefinition<unknown>>;
+  specSchemaDocumentation: SpecSchemaDocumentation[];
 }
 
 /** Composite key for looking up kinds by apiVersion + kind. */
@@ -46,11 +49,23 @@ export function createEntityKindRegistry() {
     describeKinds: () => Array<{
       apiVersion: string;
       kind: string;
+      metadataSchema: Record<string, unknown>;
       specSchema: Record<string, unknown>;
       extensions: Array<{
         namespace: string;
         specSchema: Record<string, unknown>;
       }>;
+      specSchemaDocumentation: Array<{
+        fieldPath: string;
+        variantId?: string;
+        label: string;
+        description?: string;
+        specSchema: Record<string, unknown>;
+        conditions?: Array<{
+          fieldPath: string;
+          variantIds: string[];
+        }>;
+      }>;
     }>;
   } = {
     registerKind<TSpec>(definition: EntityKindDefinition<TSpec>) {
@@ -70,6 +85,7 @@ export function createEntityKindRegistry() {
         kinds.set(key, {
           definition: definition as EntityKindDefinition<unknown>,
           extensions: new Map(),
+          specSchemaDocumentation: [],
         });
       }
     },
@@ -91,6 +107,7 @@ export function createEntityKindRegistry() {
               definition as EntityKindExtensionDefinition<unknown>,
             ],
           ]),
+          specSchemaDocumentation: [],
         });
         return;
       }
@@ -107,6 +124,30 @@ export function createEntityKindRegistry() {
       );
     },
 
+    registerSpecSchemaDocumentation(params) {
+      const key = kindKey(params);
+      let registered = kinds.get(key);
+
+      if (!registered) {
+        // Allow registering docs before the kind itself
+        registered = {
+          definition: undefined,
+          extensions: new Map(),
+          specSchemaDocumentation: [],
+        };
+        kinds.set(key, registered);
+      }
+
+      registered.specSchemaDocumentation.push({
+        fieldPath: params.fieldPath,
+        variantId: params.variantId,
+        label: params.label,
+        description: params.description,
+        schema: params.schema,
+        conditions: params.conditions,
+      });
+    },
+
     getKind(params) {
       return kinds.get(kindKey(params))?.definition;
     },
@@ -149,20 +190,30 @@ export function createEntityKindRegistry() {
       const result: Array<{
         apiVersion: string;
         kind: string;
+        metadataSchema: Record<string, unknown>;
         specSchema: Record<string, unknown>;
         extensions: Array<{
           namespace: string;
           specSchema: Record<string, unknown>;
         }>;
+        specSchemaDocumentation: Array<{
+          fieldPath: string;
+          variantId?: string;
+          label: string;
+          description?: string;
+          specSchema: Record<string, unknown>;
+          conditions?: Array<{
+            fieldPath: string;
+            variantIds: string[];
+          }>;
+        }>;
       }> = [];
 
       for (const registered of kinds.values()) {
         if (!registered.definition) continue;
 
         const def = registered.definition;
-        const baseSchema = toJsonSchema(
-          def.specSchema as z.ZodTypeAny,
-        );
+        const baseSchema = toJsonSchema(def.specSchema as z.ZodTypeAny);
 
         const extensions = [...registered.extensions.entries()].map(
           ([namespace, ext]) => ({
@@ -171,11 +222,24 @@ export function createEntityKindRegistry() {
           }),
         );
 
+        const specSchemaDocumentation = registered.specSchemaDocumentation.map(
+          (doc) => ({
+            fieldPath: doc.fieldPath,
+            variantId: doc.variantId,
+            label: doc.label,
+            description: doc.description,
+            specSchema: toJsonSchema(doc.schema),
+            conditions: doc.conditions,
+          }),
+        );
+
         result.push({
           apiVersion: def.apiVersion,
           kind: def.kind,
+          metadataSchema: toJsonSchema(entityMetadataSchema),
           specSchema: baseSchema,
           extensions,
+          specSchemaDocumentation,
         });
       }
 

package/src/router.ts

@@ -1,4 +1,5 @@
 import { implement, ORPCError } from "@orpc/server";
+import { z } from "zod";
 import { autoAuthMiddleware, type RpcContext } from "@checkstack/backend-api";
 import { encrypt, decrypt } from "@checkstack/backend-api";
 import { gitopsContract } from "@checkstack/gitops-common";
@@ -7,7 +8,7 @@ import type { QueueManager } from "@checkstack/queue-api";
 import type { InternalEntityKindRegistry } from "./kind-registry";
 import { triggerSyncForProvider, scheduleSyncForProvider, cancelSyncForProvider } from "./sync/sync-worker";
 import * as schema from "./schema";
-import { eq, and } from "drizzle-orm";
+import { eq, and, sql } from "drizzle-orm";
 import { v4 as uuidv4 } from "uuid";
 
 /**
@@ -47,12 +48,15 @@ export const createGitOpsRouter = ({
       .select()
       .from(schema.provenance)
       .where(and(...conditions));
+    const row = result[0];
     // eslint-disable-next-line unicorn/no-null
-    return result[0] ?? null;
+    return row ? { ...row, warnings: row.warnings ?? [] } : null;
   });
 
   const listProvenance = os.listProvenance.handler(async ({ input }) => {
-    const rows = await db.select().from(schema.provenance);
+    const rawRows = await db.select().from(schema.provenance);
+    // Normalize: ensure warnings is always a string[] (Drizzle may return null for pre-migration rows)
+    const rows = rawRows.map((row) => ({ ...row, warnings: row.warnings ?? [] }));
     if (!input) return rows;
 
     return rows.filter((row) => {
@@ -236,6 +240,8 @@ export const createGitOpsRouter = ({
                 // eslint-disable-next-line unicorn/no-useless-undefined
                 return undefined;
               },
+              resolveSecretsBySchema: async <T>(params: { value: T; schema: z.ZodTypeAny }): Promise<{ resolved: T; warnings: string[] }> =>
+                ({ resolved: params.value, warnings: [] }),
             },
           });
         } catch (deleteError) {
@@ -327,6 +333,16 @@ export const createGitOpsRouter = ({
       .set({ encryptedValue, updatedAt: new Date() })
       .where(eq(schema.secrets.id, input.id));
 
+    // Invalidate provenance for all entities referencing this secret
+    // so the next sync cycle re-reconciles them with the updated value
+    const secretName = existing[0].name;
+    await db
+      .update(schema.provenance)
+      .set({ lastSyncHash: "" })
+      .where(
+        sql`${secretName} = ANY(${schema.provenance.secretRefs})`,
+      );
+
     return { success: true };
   });
 
@@ -352,6 +368,22 @@ export const createGitOpsRouter = ({
     return { value: decrypt(secret.encryptedValue) };
   });
 
+  const getSecretUsage = os.getSecretUsage.handler(async ({ input }) => {
+    const rows = await db
+      .select({
+        kind: schema.provenance.kind,
+        entityName: schema.provenance.entityName,
+        repository: schema.provenance.repository,
+        filePath: schema.provenance.filePath,
+      })
+      .from(schema.provenance)
+      .where(
+        sql`${input.secretName} = ANY(${schema.provenance.secretRefs})`,
+      );
+
+    return rows;
+  });
+
   // ─── Kind Registry ────────────────────────────────────────────────────
 
   const listKinds = os.listKinds.handler(async () => {
@@ -375,6 +407,7 @@ export const createGitOpsRouter = ({
     rotateSecret,
     deleteSecret,
     resolveSecret,
+    getSecretUsage,
     listKinds,
   });
 };

package/src/schema.ts

@@ -57,16 +57,20 @@ export const provenance = pgTable("provenance", {
   repository: text("repository").notNull(),
   filePath: text("file_path").notNull(),
   lastSyncHash: text("last_sync_hash").notNull(),
+  /** Secret names referenced via ${{ secrets.NAME }} in this entity's spec. */
+  secretRefs: text("secret_refs").array().default([]),
   status: provenanceStatusEnum("status").notNull().default("synced"),
   errorMessage: text("error_message"),
+  /** Warnings about unresolved secret templates in non-secret fields. */
+  warnings: text("warnings").array().default([]),
   lastSyncedAt: timestamp("last_synced_at").defaultNow().notNull(),
   createdAt: timestamp("created_at").defaultNow().notNull(),
 });
 
-/** Secret store for secretRef values in YAML descriptors. */
+/** Secret store for ${{ secrets.NAME }} template values in YAML descriptors. */
 export const secrets = pgTable("secrets", {
   id: text("id").primaryKey(),
-  /** Unique name referenced by secretRef in descriptors. */
+  /** Unique name referenced via ${{ secrets.NAME }} in descriptors. */
   name: text("name").notNull().unique(),
   /** AES-256-GCM encrypted value (format: iv:authTag:ciphertext). */
   encryptedValue: text("encrypted_value").notNull(),