@checkstack/gitops-backend 0.1.0

package/src/secret-resolver.ts

@@ -0,0 +1,54 @@
+import { isSecretRef } from "@checkstack/gitops-common";
+
+/**
+ * Interface for resolving secret names to their decrypted values.
+ */
+export interface SecretStore {
+  resolve: (name: string) => Promise<string>;
+}
+
+/**
+ * Recursively walks a parsed spec object and resolves any `{ secretRef: "name" }`
+ * values by looking them up in the secret store.
+ *
+ * After resolution, all secretRef objects are replaced with plain strings.
+ * This function is called by the reconciliation engine before invoking plugin reconcilers.
+ */
+export async function resolveSecrets(params: {
+  spec: Record<string, unknown>;
+  secretStore: SecretStore;
+}): Promise<Record<string, unknown>> {
+  const { spec, secretStore } = params;
+  return resolveValue(spec, secretStore) as Promise<Record<string, unknown>>;
+}
+
+async function resolveValue(
+  value: unknown,
+  secretStore: SecretStore,
+): Promise<unknown> {
+  if (value === null || value === undefined) {
+    return value;
+  }
+
+  // Check if this value is a secretRef object
+  if (isSecretRef(value)) {
+    return secretStore.resolve(value.secretRef);
+  }
+
+  // Recurse into arrays
+  if (Array.isArray(value)) {
+    return Promise.all(value.map((item) => resolveValue(item, secretStore)));
+  }
+
+  // Recurse into plain objects
+  if (typeof value === "object") {
+    const resolved: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value)) {
+      resolved[key] = await resolveValue(val, secretStore);
+    }
+    return resolved;
+  }
+
+  // Primitives pass through
+  return value;
+}

package/src/sync/document-parser.test.ts

@@ -0,0 +1,116 @@
+import { describe, it, expect } from "bun:test";
+import { parseEntityDocuments, computeHash } from "./document-parser";
+import { CHECKSTACK_API_VERSION } from "@checkstack/gitops-common";
+
+const VALID_SYSTEM_YAML = `apiVersion: ${CHECKSTACK_API_VERSION}
+kind: System
+metadata:
+  name: payment-service
+  title: Payment Service
+  description: Handles payments
+spec:
+  description: A payment processing system`;
+
+const VALID_HEALTHCHECK_YAML = `apiVersion: ${CHECKSTACK_API_VERSION}
+kind: Healthcheck
+metadata:
+  name: payment-db-check
+spec:
+  strategy: postgres`;
+
+describe("parseEntityDocuments", () => {
+  it("parses a single document", () => {
+    const result = parseEntityDocuments({ content: VALID_SYSTEM_YAML });
+    expect(result.errors).toHaveLength(0);
+    expect(result.entities).toHaveLength(1);
+    expect(result.entities[0].entity.kind).toBe("System");
+    expect(result.entities[0].entity.metadata.name).toBe("payment-service");
+    expect(result.entities[0].contentHash).toBeString();
+    expect(result.entities[0].contentHash).toHaveLength(64); // SHA-256 hex
+  });
+
+  it("parses multi-document YAML separated by ---", () => {
+    const content = `${VALID_SYSTEM_YAML}\n---\n${VALID_HEALTHCHECK_YAML}`;
+    const result = parseEntityDocuments({ content });
+    expect(result.errors).toHaveLength(0);
+    expect(result.entities).toHaveLength(2);
+    expect(result.entities[0].entity.kind).toBe("System");
+    expect(result.entities[1].entity.kind).toBe("Healthcheck");
+  });
+
+  it("handles leading --- in multi-doc YAML", () => {
+    const content = `---\n${VALID_SYSTEM_YAML}\n---\n${VALID_HEALTHCHECK_YAML}`;
+    const result = parseEntityDocuments({ content });
+    expect(result.errors).toHaveLength(0);
+    expect(result.entities).toHaveLength(2);
+  });
+
+  it("skips empty documents (trailing ---)", () => {
+    const content = `${VALID_SYSTEM_YAML}\n---\n`;
+    const result = parseEntityDocuments({ content });
+    expect(result.errors).toHaveLength(0);
+    expect(result.entities).toHaveLength(1);
+  });
+
+  it("collects validation errors for invalid envelope", () => {
+    const content = `kind: System
+metadata:
+  name: INVALID-UPPERCASE
+spec: {}`;
+    const result = parseEntityDocuments({ content });
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].documentIndex).toBe(0);
+    expect(result.errors[0].message).toContain("Validation error");
+    expect(result.entities).toHaveLength(0);
+  });
+
+  it("parses valid docs and collects errors for invalid ones in same file", () => {
+    const content = `${VALID_SYSTEM_YAML}\n---\nkind: Bad\nmetadata:\n  name: UPPERCASE\nspec: {}`;
+    const result = parseEntityDocuments({ content });
+    expect(result.entities).toHaveLength(1);
+    expect(result.entities[0].entity.kind).toBe("System");
+    expect(result.errors).toHaveLength(1);
+    expect(result.errors[0].documentIndex).toBe(1);
+  });
+
+  it("returns content hashes that are stable for identical content", () => {
+    const result1 = parseEntityDocuments({ content: VALID_SYSTEM_YAML });
+    const result2 = parseEntityDocuments({ content: VALID_SYSTEM_YAML });
+    expect(result1.entities[0].contentHash).toBe(
+      result2.entities[0].contentHash,
+    );
+  });
+
+  it("returns different hashes for different content", () => {
+    const modified = VALID_SYSTEM_YAML.replace(
+      "Handles payments",
+      "Handles refunds",
+    );
+    const result1 = parseEntityDocuments({ content: VALID_SYSTEM_YAML });
+    const result2 = parseEntityDocuments({ content: modified });
+    expect(result1.entities[0].contentHash).not.toBe(
+      result2.entities[0].contentHash,
+    );
+  });
+
+  it("handles completely invalid YAML gracefully", () => {
+    const content = `{{{not valid yaml at all`;
+    const result = parseEntityDocuments({ content });
+    expect(result.entities).toHaveLength(0);
+    expect(result.errors.length).toBeGreaterThan(0);
+  });
+});
+
+describe("computeHash", () => {
+  it("produces a 64-character hex string", () => {
+    const hash = computeHash({ input: "hello world" });
+    expect(hash).toHaveLength(64);
+    expect(hash).toMatch(/^[\da-f]+$/);
+  });
+
+  it("produces deterministic output", () => {
+    expect(computeHash({ input: "test" })).toBe(
+      computeHash({ input: "test" }),
+    );
+  });
+});

package/src/sync/document-parser.ts

@@ -0,0 +1,124 @@
+import { parseAllDocuments } from "yaml";
+import { entityEnvelopeSchema } from "@checkstack/gitops-common";
+import { extractErrorMessage } from "@checkstack/common";
+import type { EntityEnvelope } from "@checkstack/gitops-common";
+
+/**
+ * A successfully parsed entity with its content hash for diffing.
+ */
+export interface ParsedEntity {
+  /** The validated entity envelope. */
+  entity: EntityEnvelope;
+  /** SHA-256 hex hash of the raw YAML source for this entity. */
+  contentHash: string;
+}
+
+/**
+ * An error encountered during parsing or validation.
+ */
+export interface ParseError {
+  /** 0-based document index within the YAML file. */
+  documentIndex: number;
+  /** Human-readable error message. */
+  message: string;
+}
+
+/**
+ * Result of parsing a YAML file containing one or more entity documents.
+ */
+export interface ParseResult {
+  entities: ParsedEntity[];
+  errors: ParseError[];
+}
+
+/**
+ * Parses a YAML string (potentially multi-document) into entity envelopes.
+ * Never throws — all parse/validation errors are collected in `errors`.
+ *
+ * @param content - Raw YAML content (may contain multiple docs separated by `---`)
+ * @returns Parsed entities and any errors encountered
+ */
+export function parseEntityDocuments(params: { content: string }): ParseResult {
+  const { content } = params;
+  const entities: ParsedEntity[] = [];
+  const errors: ParseError[] = [];
+
+  let docs: ReturnType<typeof parseAllDocuments>;
+  try {
+    docs = parseAllDocuments(content);
+  } catch (error) {
+    errors.push({
+      documentIndex: 0,
+      message: `Failed to parse YAML: ${extractErrorMessage(error, "Unknown error")}`,
+    });
+    return { entities, errors };
+  }
+
+  for (const [i, doc] of docs.entries()) {
+    // Check for YAML-level parse errors
+    if (doc.errors.length > 0) {
+      errors.push({
+        documentIndex: i,
+        message: `YAML parse error: ${doc.errors.map((e) => e.message).join("; ")}`,
+      });
+      continue;
+    }
+
+    const raw = doc.toJSON();
+
+    // Skip null/empty documents (e.g., trailing `---`)
+    if (raw === null || raw === undefined) {
+      continue;
+    }
+
+    // Validate against entity envelope schema
+    const result = entityEnvelopeSchema.safeParse(raw);
+    if (!result.success) {
+      const issues = result.error.issues
+        .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+        .join("; ");
+      errors.push({
+        documentIndex: i,
+        message: `Validation error: ${issues}`,
+      });
+      continue;
+    }
+
+    // Compute content hash from the raw YAML source for this document
+    const docSource = extractDocumentSource({ content, documentIndex: i });
+    const contentHash = computeHash({ input: docSource });
+
+    entities.push({ entity: result.data, contentHash });
+  }
+
+  return { entities, errors };
+}
+
+/**
+ * Extracts the raw YAML source for a single document from a multi-doc string.
+ * Uses `---` as the separator.
+ */
+function extractDocumentSource(params: {
+  content: string;
+  documentIndex: number;
+}): string {
+  const { content, documentIndex } = params;
+  // Split on document separators, handling leading `---`
+  const parts = content.split(/^---$/m);
+
+  // If the content starts with `---`, the first part is empty
+  const nonEmptyParts = parts[0].trim() === "" ? parts.slice(1) : parts;
+
+  return (nonEmptyParts[documentIndex] ?? "").trim();
+}
+
+/**
+ * Computes a SHA-256 hex hash of a string.
+ */
+function computeHash(params: { input: string }): string {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(params.input);
+  return hasher.digest("hex");
+}
+
+export { computeHash };

package/src/sync/reconciler-delete.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { z } from "zod";
+import { CHECKSTACK_API_VERSION } from "@checkstack/gitops-common";
+import { createEntityKindRegistry } from "../kind-registry";
+
+/**
+ * Tests that the `detectOrphans` logic in the reconciler properly invokes
+ * the kind's `delete()` reconciler before removing provenance entries.
+ *
+ * These tests verify the delete wiring in isolation by directly testing
+ * the kind registry's delete behavior, which the reconciler calls.
+ */
+
+describe("Kind delete reconciler wiring", () => {
+  it("calls the registered delete function when available", async () => {
+    const deleteHandler = mock(async (_params: { entityName: string; entityId?: string }) => {});
+    const registry = createEntityKindRegistry();
+
+    registry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+      specSchema: z.object({ description: z.string().optional() }),
+      reconcile: async () => ({ entityId: "test-id" }),
+      delete: deleteHandler,
+    });
+
+    const kindDef = registry.getKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "System",
+    });
+
+    expect(kindDef?.delete).toBeDefined();
+
+    await kindDef!.delete!({
+      entityName: "payment-service",
+      entityId: "sys-123",
+      context: {
+        logger: {
+          debug: () => {},
+          info: () => {},
+          warn: () => {},
+          error: () => {},
+        },
+        resolveEntityRef: async () => undefined,
+      },
+    });
+
+    expect(deleteHandler).toHaveBeenCalledTimes(1);
+    expect(deleteHandler).toHaveBeenCalledWith({
+      entityName: "payment-service",
+      entityId: "sys-123",
+      context: expect.objectContaining({
+        logger: expect.any(Object),
+      }),
+    });
+  });
+
+  it("handles kinds with no delete handler gracefully", () => {
+    const registry = createEntityKindRegistry();
+
+    registry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "ReadOnlyKind",
+      specSchema: z.object({}),
+      reconcile: async () => ({ entityId: "test-id" }),
+      // No delete handler
+    });
+
+    const kindDef = registry.getKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "ReadOnlyKind",
+    });
+
+    expect(kindDef).toBeDefined();
+    expect(kindDef?.delete).toBeUndefined();
+  });
+
+  it("propagates errors from the delete handler", async () => {
+    const registry = createEntityKindRegistry();
+
+    registry.registerKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "FailingKind",
+      specSchema: z.object({}),
+      reconcile: async () => ({ entityId: "test-id" }),
+      delete: async () => {
+        throw new Error("DB connection failed");
+      },
+    });
+
+    const kindDef = registry.getKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "FailingKind",
+    });
+
+    expect(
+      kindDef!.delete!({
+        entityName: "broken-entity",
+        entityId: "broken-id",
+        context: {
+          logger: {
+            debug: () => {},
+            info: () => {},
+            warn: () => {},
+            error: () => {},
+          },
+          resolveEntityRef: async () => undefined,
+        },
+      }),
+    ).rejects.toThrow("DB connection failed");
+  });
+
+  it("returns undefined for unknown kind lookups (delete not called)", () => {
+    const registry = createEntityKindRegistry();
+
+    const kindDef = registry.getKind({
+      apiVersion: CHECKSTACK_API_VERSION,
+      kind: "NonExistent",
+    });
+
+    expect(kindDef).toBeUndefined();
+  });
+});