@checkstack/integration-backend 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # @checkstack/integration-backend
 
+## 0.4.1
+
+### Patch Changes
+
+- Updated dependencies [13373ce]
+  - @checkstack/common@0.14.0
+  - @checkstack/backend-api@0.21.1
+  - @checkstack/queue-api@0.3.10
+  - @checkstack/command-backend@0.2.1
+  - @checkstack/integration-common@0.7.1
+  - @checkstack/secrets-backend@0.2.1
+  - @checkstack/secrets-common@0.2.1
+  - @checkstack/signal-common@0.2.7
+
+## 0.4.0
+
+### Minor Changes
+
+- 9dcc848: Harden config-versioning so stored configs always migrate-then-validate and broken migration chains fail fast at boot.
+
+  - `@checkstack/backend-api` `Versioned<T>` gains `parseAssumingV1` (migrate-from-v1 then validate leniently, runtime path), `parseStrictAssumingV1` (migrate then validate strictly, editor path), and `validateMigrationChainFromV1()`. A standalone pure helper `assertMigrationChainFromV1({ version, migrations })` is the single shared implementation behind the constructor guard and `validateMigrationChainFromV1`.
+  - `Versioned` now validates its own v1 -> `version` chain in the constructor, which runs at module import / plugin registration. A new `no-restricted-syntax` ESLint rule bans calling `parse` / `safeParse` / `parseAsync` / `strict` directly on a `Versioned`'s `.schema` member.
+  - Auth strategy migration chains are validated at the `betterAuthExtensionPoint.addStrategy` chokepoint (`@checkstack/auth-backend`).
+  - Automation action AND trigger configs migrate-then-validate (lenient at dispatch, strict in the editor validator, recursing into `choose`/`parallel`/`repeat`/`sequence` blocks). The `run_script` / `run_shell` action configs bump to `version: 2` dropping the removed `sandbox` key, fixing the editor's `Unrecognized key: sandbox` error.
+  - Anomaly read path now validates: `getAnomalyConfig` / `getAnomalyAssignmentConfig` run stored records through `Versioned.parseRecord`; `PartialAnomalySettingsSchema` moved to `@checkstack/anomaly-common`. Notification ConfigService reads thread the migrations argument, and per-strategy `userConfig` is migrate-then-validated before `send()`.
+  - gitops-apply migrate-then-validates authored health-check config; integration connection validation routes through `safeValidate`. The latent HTTP health-check `result` schema (at `version: 3` with no migrations) now ships a pass-through v1 -> v2 -> v3 chain.
+
+  BREAKING CHANGES (fail-fast at boot, intended):
+
+  - Any `Versioned` config with `version > 1` and an incomplete or non-contiguous migration chain now throws at construction (boot) instead of failing lazily on first read. This covers every `Versioned` instance repo-wide, including future plugin types. Out-of-tree plugins shipping such a config must add the missing migration step(s); all in-repo strategies already have complete chains.
+  - An auth strategy declaring `configVersion > 1` without a complete chain throws at registration.
+  - A trigger's per-automation config is now a versioned `config: Versioned<TConfig>` instead of a bare `configSchema?`. Plugins registering triggers with `configSchema:` must wrap it: `config: new Versioned({ version: 1, schema })`. The underlying schema stays reachable via `config.schema`; triggers without per-automation config are unaffected.
+
+  State and scale: all affected reads resolve from shared Postgres / in-process registries, so every pod sees the same migrated answer. No new framework-owned current-state store.
+
+  This is a beta minor.
+
+- 9dcc848: Surface integration connection validation errors inline, and fix blank secrets clearing stored credentials on edit.
+
+  `@checkstack/ui` `DynamicForm` gains opt-in, backward-compatible props plus pure DOM-free helpers:
+
+  - `showInlineErrors` (default `false`): renders a concise per-field error under each touched required field; the `onValidChange` validity boolean derives from the same per-field error map.
+  - `fieldErrors`: an externally-supplied `{ [fieldPath]: message }` map (dot-joined for nested fields) for surfacing SERVER validation inline; nested paths flag their parent.
+  - `keepExistingSecretFields`: in EDIT mode, lists `x-secret` keys already stored server-side - a blank input means "keep existing" and is treated as VALID (CREATE mode omits it). New exported helpers: `deriveClientFieldErrors`, `deriveServerFieldErrors`, `parseServerValidationData`, `omitKeepExistingSecrets`, `listSecretFieldKeys`. `DynamicForm` also no longer shows a required (`*`) marker on the child fields of an OPTIONAL nested object while that object is empty (e.g. the OpenAI-compatible `spendCap`); required nested objects are unchanged.
+
+  `@checkstack/integration-backend`: connection-config validation failures attach the structured zod issues to `ORPCError.data` under a `CONFIG_VALIDATION` discriminator; the human-readable message is unchanged.
+
+  `@checkstack/integration-frontend` `ProviderConnectionsPage`: validation failures appear inline on the offending fields (the toast remains a fallback); Create/Save stays disabled while invalid; on edit a blank `x-secret` field is treated as "keep existing" (no required error, omitted from the update so the stored secret is not cleared).
+
+  BREAKING CHANGES: none. The new `DynamicForm` props are optional and default to previous behavior.
+
+  This is a beta minor.
+
+- 9dcc848: Align workspace dependency versions and migrate React Router to v7.
+
+  BREAKING CHANGES (React Router v7): All frontend packages now depend on `react-router-dom@^7.16.0`. Previously the workspace declared four divergent ranges (`^6.20.0`, `^6.22.0`, `^7.1.1`, `^7.14.2`), which resolved both `react-router@6` and `react-router@7` into a single bundle. Everything is now unified on v7. The public imports the app uses (`BrowserRouter`, `Routes`, `Route`, `Link`, `NavLink`, `MemoryRouter`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`) are unchanged between v6 and v7, so no source rewrites were required - but any out-of-tree plugin still on react-router v6 should upgrade to v7 (see the React Router v6 -> v7 upgrade guide) to share the host's single router instance via the import map.
+
+  Other unified ranges (no API change): `react` -> `^18.3.1`, the `@orpc/*` family (`contract`, `server`, `client`, `tanstack-query`, `openapi`, `zod`) -> `^1.14.4`, and `better-auth` -> `^1.6.13`.
+
+  Removed the pre-rename `@orpc/react-query` leftover from `@checkstack/frontend-api`; its `createRouterUtils` / `RouterUtils` / `ProcedureUtils` now come from `@orpc/tanstack-query` (the package already in use).
+
+  Stale in-range runtime deps pulled up to current published versions: `hono` `^4.12.23`, `@tanstack/react-query` (+devtools) `^5.100.14`, `date-fns` `^4.4.0`, `jose` `^6.2.3`, `tar` `^7.5.16`, `semver` `^7.8.1`, `@xyflow/react` `^12.11.0`.
+
+### Patch Changes
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/backend-api@0.21.0
+  - @checkstack/common@0.13.0
+  - @checkstack/command-backend@0.2.0
+  - @checkstack/integration-common@0.7.0
+  - @checkstack/secrets-backend@0.2.0
+  - @checkstack/secrets-common@0.2.0
+  - @checkstack/queue-api@0.3.9
+  - @checkstack/signal-common@0.2.6
+
 ## 0.3.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/integration-backend",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -15,23 +15,23 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@checkstack/integration-common": "0.6.0",
-    "@checkstack/backend-api": "0.18.0",
-    "@checkstack/signal-common": "0.2.5",
-    "@checkstack/queue-api": "0.3.6",
-    "@checkstack/common": "0.12.0",
-    "@checkstack/command-backend": "0.1.31",
-    "@checkstack/secrets-common": "0.0.1",
-    "@checkstack/secrets-backend": "0.0.1",
+    "@checkstack/integration-common": "0.7.0",
+    "@checkstack/backend-api": "0.21.0",
+    "@checkstack/signal-common": "0.2.6",
+    "@checkstack/queue-api": "0.3.9",
+    "@checkstack/common": "0.13.0",
+    "@checkstack/command-backend": "0.2.0",
+    "@checkstack/secrets-common": "0.2.0",
+    "@checkstack/secrets-backend": "0.2.0",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
-    "@orpc/server": "^1.13.2"
+    "@orpc/server": "^1.14.4"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/scripts": "0.3.4",
+    "@checkstack/scripts": "0.4.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/test-utils-backend": "0.1.31",
+    "@checkstack/test-utils-backend": "0.1.34",
     "@types/node": "^20.0.0",
     "drizzle-kit": "^0.31.10",
     "typescript": "^5.0.0"

package/src/connection-validation-error.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+
+import {
+  buildConfigValidationErrorData,
+  CONFIG_VALIDATION_ERROR_CODE,
+} from "./connection-validation-error";
+
+const connectionSchema = z.object({
+  apiKey: z.string().min(1),
+  baseUrl: z.string().url(),
+  spendCap: z.object({ tokenBudget: z.number().positive() }).optional(),
+});
+
+function errorFor(input: unknown): z.ZodError {
+  const result = connectionSchema.safeParse(input);
+  if (result.success) throw new Error("expected validation to fail");
+  return result.error;
+}
+
+describe("buildConfigValidationErrorData", () => {
+  it("tags the payload with the config-validation discriminator", () => {
+    const data = buildConfigValidationErrorData(
+      errorFor({ apiKey: "", baseUrl: "not-a-url" }),
+    );
+    expect(data.code).toBe(CONFIG_VALIDATION_ERROR_CODE);
+    expect(data.issues.length).toBeGreaterThan(0);
+  });
+
+  it("carries top-level field paths and messages", () => {
+    const data = buildConfigValidationErrorData(
+      errorFor({ apiKey: "", baseUrl: "https://x.test" }),
+    );
+    const apiKeyIssue = data.issues.find((i) => i.path[0] === "apiKey");
+    expect(apiKeyIssue).toBeDefined();
+    expect(typeof apiKeyIssue?.message).toBe("string");
+  });
+
+  it("carries nested field paths", () => {
+    const data = buildConfigValidationErrorData(
+      errorFor({
+        apiKey: "sk",
+        baseUrl: "https://x.test",
+        spendCap: { tokenBudget: -1 },
+      }),
+    );
+    const nested = data.issues.find(
+      (i) => i.path[0] === "spendCap" && i.path[1] === "tokenBudget",
+    );
+    expect(nested).toBeDefined();
+  });
+
+  it("yields a JSON-roundtrippable payload (string/number paths only)", () => {
+    const data = buildConfigValidationErrorData(
+      errorFor({ apiKey: "", baseUrl: "bad" }),
+    );
+    const roundtripped: unknown = JSON.parse(JSON.stringify(data));
+    expect(roundtripped).toEqual(data);
+    for (const issue of data.issues) {
+      for (const segment of issue.path) {
+        expect(["string", "number"]).toContain(typeof segment);
+      }
+    }
+  });
+});

package/src/connection-validation-error.ts

@@ -0,0 +1,43 @@
+import type { z } from "zod";
+
+/**
+ * Discriminator placed on the `ORPCError.data` payload so the frontend can
+ * tell a connection-config validation failure apart from any other
+ * structured error data and map each issue onto a form field.
+ */
+export const CONFIG_VALIDATION_ERROR_CODE = "CONFIG_VALIDATION";
+
+/** A single field-scoped validation problem crossing the oRPC boundary. */
+export interface ConfigValidationIssue {
+  /** Field path (string/number segments only; symbols are dropped). */
+  path: (string | number)[];
+  message: string;
+}
+
+/** Structured payload attached to `ORPCError.data` for config validation. */
+export interface ConfigValidationErrorData {
+  code: typeof CONFIG_VALIDATION_ERROR_CODE;
+  issues: ConfigValidationIssue[];
+}
+
+/**
+ * Build the structured `data` payload for a connection-config validation
+ * failure from a zod error. Symbol path segments cannot survive JSON
+ * serialization and never name a form field, so they are filtered out. Kept
+ * pure (no oRPC) so the wire shape can be unit-tested against the frontend
+ * parser without standing up the router.
+ */
+export function buildConfigValidationErrorData(
+  error: z.ZodError,
+): ConfigValidationErrorData {
+  return {
+    code: CONFIG_VALIDATION_ERROR_CODE,
+    issues: error.issues.map((issue) => ({
+      path: issue.path.filter(
+        (segment): segment is string | number =>
+          typeof segment === "string" || typeof segment === "number",
+      ),
+      message: issue.message,
+    })),
+  };
+}

package/src/migration-chain-contract.test.ts

@@ -0,0 +1,53 @@
+/**
+ * Contract test: every integration provider `connectionSchema` (a Versioned)
+ * that is stored UNVERSIONED and read back via assume-v1-on-read MUST have a
+ * COMPLETE, contiguous migration chain from version 1 to its current
+ * `version`. Pure STRUCTURAL check (`validateMigrationChainFromV1` — no
+ * `migrate()` is run), so it carries zero per-config upkeep: the day someone
+ * bumps a connection schema's `version` without shipping a covering migration,
+ * the connection read path would silently fail at runtime on a genuinely-v1
+ * stored connection — this test turns that into a CI failure instead. See the
+ * HTTP plugin's equivalent test for the full rationale.
+ *
+ * Providers are registered by integration plugins (e.g. integration-jira),
+ * NOT by this core package, so there are no built-in providers to enumerate.
+ * This test asserts the enumeration contract holds for whatever a registry is
+ * given (so any future provider's `connectionSchema` is covered automatically)
+ * and exercises it with a representative fixture provider.
+ */
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import { Versioned } from "@checkstack/backend-api";
+import { definePluginMetadata } from "@checkstack/common";
+import { createIntegrationProviderRegistry } from "./provider-registry";
+import type { IntegrationProvider } from "./provider-types";
+
+const meta = definePluginMetadata({ pluginId: "integration-fixture" });
+
+const fixtureProvider: IntegrationProvider<{ baseUrl: string }> = {
+  id: "fixture",
+  displayName: "Fixture Provider",
+  connectionSchema: new Versioned({
+    version: 1,
+    schema: z.object({ baseUrl: z.string() }),
+  }),
+};
+
+describe("integration connectionSchema migration-chain contract", () => {
+  it("every registered provider connectionSchema has a complete v1->version chain", () => {
+    const registry = createIntegrationProviderRegistry();
+    registry.register(fixtureProvider, meta);
+
+    const providers = registry.getProviders();
+    expect(providers.length).toBeGreaterThan(0);
+
+    for (const provider of providers) {
+      if (!provider.connectionSchema) continue;
+      const problem = provider.connectionSchema.validateMigrationChainFromV1();
+      expect(
+        problem,
+        `Provider "${provider.qualifiedId}" connectionSchema (version ${provider.connectionSchema.version}) has a broken migration chain: ${problem}`,
+      ).toBeUndefined();
+    }
+  });
+});

package/src/router.ts

@@ -12,6 +12,7 @@ import { integrationContract } from "@checkstack/integration-common";
 
 import type { IntegrationProviderRegistry } from "./provider-registry";
 import type { ConnectionStore } from "./connection-store";
+import { buildConfigValidationErrorData } from "./connection-validation-error";
 import * as schema from "./schema";
 
 interface RouterDeps {
@@ -147,17 +148,24 @@ export function createIntegrationRouter(deps: RouterDeps) {
         });
       }
 
-      const parseResult = provider.connectionSchema.schema.safeParse(config);
+      const parseResult = provider.connectionSchema.safeValidate(config);
       if (!parseResult.success) {
+        // Attach the structured zod issues (field path + message) on the
+        // error `data` so the frontend can surface each failure INLINE on the
+        // offending connection field. The `code` discriminator lets the
+        // client distinguish this from any other structured error payload.
         throw new ORPCError("BAD_REQUEST", {
           message: `Invalid connection config: ${parseResult.error.message}`,
+          data: buildConfigValidationErrorData(parseResult.error),
         });
       }
 
-      const validatedConfig = parseResult.data as unknown as Record<
-        string,
-        unknown
-      >;
+      // `connectionSchema` is `Versioned<unknown>` once the provider leaves
+      // the registry (the per-provider `TConnection` generic is erased), so
+      // `safeValidate` yields `unknown`. The connection store stores configs
+      // as `Record<string, unknown>`; this validated value is the provider's
+      // own object config, so the narrowing cast is safe.
+      const validatedConfig = parseResult.data as Record<string, unknown>;
 
       const connection = await connectionStore.createConnection({
         providerId,