@checkstack/healthcheck-postgres-backend 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # @checkstack/healthcheck-postgres-backend
 
+## 0.5.0
+
+### Minor Changes
+
+- 43e4484: Extend `{{ … }}` environment templating across every built-in health-check type
+  and add editor UX for it, so one check config can cover N environments (mirrors
+  the existing HTTP `url` pattern).
+
+  Templatable connection/target fields now marked `x-templatable`:
+
+  - TLS: `host`, `servername`; TCP: `host`; Ping: `host`; gRPC: `host`, `service`.
+  - MySQL / Postgres: `host`, `database`, `user`, `query`.
+  - SSH: `host`, `username`, `command`; Redis: `host`, `args`; RCON: `host`,
+    `command`.
+  - DNS: `hostname`, `nameserver`; Jenkins: `url` (`baseUrl`), `jobName`;
+    Container: `endpoint`, `container`.
+  - SNMP: `host` (strategy), `oid` (collector).
+  - Script (shell): `cwd` (working directory).
+
+  This closes the last gaps so the coverage is now truly every built-in
+  health-check type. The Script collectors' `script` bodies are deliberately NOT
+  templatable: rendering `{{ … }}` into shell/TypeScript source would splice env
+  values into executed code. Per-environment data reaches those scripts safely via
+  the reserved `CHECKSTACK_ENV_*` shell vars (shell collector) and
+  `globalThis.context.environment` (inline collector) instead.
+
+  Because templating strips `{{ }}` and renders an undefined variable to an empty
+  string, every REQUIRED templatable field now has a post-render config-error
+  guard so an empty/invalid render is treated as a transport failure instead of a
+  silent "healthy" empty probe. Strategy connection fields (host, database, user,
+  endpoint, container, Jenkins base URL, SNMP host) throw from `createClient`;
+  collector target fields (query, command, hostname, jobName, SNMP oid) return a
+  `CollectorResult` with an `error`. Jenkins `baseUrl` moves its `.url()` validation to post-render.
+  Secret fields (passwords/tokens/keys) are never templatable; optional fields
+  (SNI `servername`, gRPC `service`, DNS `nameserver`, Redis `args`, Script `cwd`)
+  are templatable but not non-empty-guarded, since an empty render is a legitimate
+  "unset". SSRF/egress guards continue to run on the rendered host (rendering
+  happens before `createClient`).
+
+  Editor UX (`@checkstack/ui` + `@checkstack/healthcheck-frontend`):
+
+  - The environment "Preview as" picker + live preview line now also apply to the
+    strategy (connection) form, not just collector forms, so host/port templates
+    preview too.
+  - A single-line templatable field shows a small "Templating" badge next to its
+    label and, when a completion provider is supplied, renders a
+    `TemplateValueInput` with `{{ … }}` autocomplete. The health-check editor
+    seeds the provider with the fixed `environment.* / check.* / system.*`
+    namespace (`createReferenceCompletionProvider`, new `@checkstack/ui` export),
+    and `DynamicForm` gains a `templatableFieldsOnly` prop so only `x-templatable`
+    fields become template inputs (automation keeps templating every string field).
+
+  BREAKING CHANGE: none. Existing non-templatable configs and stored values are
+  unaffected; only fields explicitly marked `x-templatable` change behavior.
+
+  The `@checkstack/ai-backend` bump reflects the regenerated docs index for the
+  updated health-check collector and config-schema templating documentation.
+
+  Thanks to [@stuajnht](https://github.com/stuajnht) for the valuable feedback.
+
+### Patch Changes
+
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+- Updated dependencies [43e4484]
+  - @checkstack/healthcheck-common@1.16.0
+  - @checkstack/backend-api@0.31.1
+
+## 0.4.3
+
+### Patch Changes
+
+- Updated dependencies [8aae4e2]
+- Updated dependencies [f93ee7a]
+- Updated dependencies [f93ee7a]
+- Updated dependencies [f93ee7a]
+- Updated dependencies [d0eddc9]
+- Updated dependencies [d0eddc9]
+- Updated dependencies [8aae4e2]
+- Updated dependencies [d0eddc9]
+- Updated dependencies [f93ee7a]
+  - @checkstack/healthcheck-common@1.15.0
+  - @checkstack/common@0.22.0
+  - @checkstack/backend-api@0.31.0
+
 ## 0.4.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-postgres-backend",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,9 +14,9 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.30.0",
-    "@checkstack/common": "0.21.0",
-    "@checkstack/healthcheck-common": "1.14.0",
+    "@checkstack/backend-api": "0.31.1",
+    "@checkstack/common": "0.22.0",
+    "@checkstack/healthcheck-common": "1.16.0",
     "pg": "^8.11.0"
   },
   "devDependencies": {
@@ -24,7 +24,7 @@
     "@types/pg": "^8.11.0",
     "typescript": "^5.0.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.7.2"
+    "@checkstack/scripts": "0.7.3"
   },
   "description": "Checkstack healthcheck-postgres-backend plugin",
   "author": {

package/src/query-collector.ts

@@ -1,6 +1,7 @@
 import {
   Versioned,
   z,
+  configString,
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
@@ -24,11 +25,28 @@ import type { PostgresTransportClient } from "./transport-client";
 // ============================================================================
 
 const queryConfigSchema = z.object({
-  query: z.string().min(1).default("SELECT 1").describe("SQL query to execute"),
+  // Templatable: supports `{{ environment.query }}` so one config covers N
+  // environments. `.min(1)` still guards the STORED value (a `{{ }}` template is
+  // non-empty); the CONCRETE rendered query is re-checked POST-RENDER in
+  // `execute` because an empty render must not run as a successful query.
+  query: configString({ "x-templatable": true })
+    .min(1)
+    .default("SELECT 1")
+    .describe(
+      "SQL query to execute. Supports templating, e.g. {{ environment.query }}",
+    ),
 });
 
 export type QueryConfig = z.infer<typeof queryConfigSchema>;
 
+/**
+ * Post-render validator for the rendered `query`. An empty render (e.g. an
+ * env-less run resolving `{{ environment.query }}` to "") is a config error
+ * that prevents the probe - transport-failure semantics - not a healthy empty
+ * query.
+ */
+const renderedQuerySchema = z.string().trim().min(1);
+
 // ============================================================================
 // RESULT SCHEMAS
 // ============================================================================
@@ -143,7 +161,24 @@ export class QueryCollector implements CollectorStrategy<
   }): Promise<CollectorResult<QueryResult>> {
     const startTime = Date.now();
 
-    const response = await client.exec({ query: config.query });
+    // Post-render guard: `query` is a templatable string, so the concrete value
+    // is re-validated here after the executor rendered `{{ environment.* }}`.
+    // An empty render is a config error - fail as a transport failure rather
+    // than running (and "succeeding" at) an empty query.
+    const query = renderedQuerySchema.safeParse(config.query);
+    if (!query.success) {
+      return {
+        result: {
+          rowCount: 0,
+          executionTimeMs: Date.now() - startTime,
+          success: false,
+        },
+        error: `Rendered query is empty: ${JSON.stringify(config.query)}. ` +
+          `Check the {{ environment.* }} templating for this environment.`,
+      };
+    }
+
+    const response = await client.exec({ query: query.data });
     const executionTimeMs = Date.now() - startTime;
 
     return {

package/src/strategy.ts

@@ -44,15 +44,24 @@ import { extractErrorMessage } from "@checkstack/common";
  * Configuration schema for PostgreSQL health checks.
  */
 export const postgresConfigSchema = baseStrategyConfigSchema.extend({
-  host: configString({}).describe("PostgreSQL server hostname"),
+  // Templatable connection fields: support `{{ environment.host }}` etc. so one
+  // config covers N environments. Presence is enforced POST-RENDER in
+  // `createClient`. `password` stays a secret (never templatable).
+  host: configString({ "x-templatable": true }).describe(
+    "PostgreSQL server hostname. Supports templating, e.g. {{ environment.host }}",
+  ),
   port: configNumber({})
     .int()
     .min(1)
     .max(65_535)
     .default(5432)
     .describe("PostgreSQL port"),
-  database: configString({}).describe("Database name"),
-  user: configString({}).describe("Database user"),
+  database: configString({ "x-templatable": true }).describe(
+    "Database name. Supports templating, e.g. {{ environment.database }}",
+  ),
+  user: configString({ "x-templatable": true }).describe(
+    "Database user. Supports templating, e.g. {{ environment.user }}",
+  ),
   password: configSecret({ id: "password" }).describe("Database password"),
   ssl: configBoolean({}).default(false).describe("Use SSL connection"),
 });
@@ -60,6 +69,15 @@ export const postgresConfigSchema = baseStrategyConfigSchema.extend({
 export type PostgresConfig = z.infer<typeof postgresConfigSchema>;
 export type PostgresConfigInput = z.input<typeof postgresConfigSchema>;
 
+/**
+ * Post-render validator for required connection fields. The stored values are
+ * plain templatable strings, so presence cannot be checked at store time; the
+ * executor renders `{{ environment.* }}` per environment, then this rejects a
+ * render that collapsed to empty/whitespace. An empty host/database/user is a
+ * config error that prevents the probe - transport-failure semantics.
+ */
+const renderedRequiredSchema = z.string().trim().min(1);
+
 /**
  * Per-run result metadata.
  */
@@ -263,12 +281,35 @@ export class PostgresHealthCheckStrategy implements HealthCheckStrategy<
   ): Promise<ConnectedClient<PostgresTransportClient>> {
     const validatedConfig = this.config.validate(config);
 
+    // Post-render guard: the connection fields are templatable strings, so their
+    // presence cannot be checked at store time. The executor has already
+    // rendered `{{ environment.* }}`; reject a render that collapsed to empty so
+    // the run fails clearly instead of attempting an empty connection.
+    const rendered = z
+      .object({
+        host: renderedRequiredSchema,
+        database: renderedRequiredSchema,
+        user: renderedRequiredSchema,
+      })
+      .safeParse({
+        host: validatedConfig.host,
+        database: validatedConfig.database,
+        user: validatedConfig.user,
+      });
+    if (!rendered.success) {
+      throw new Error(
+        `Rendered PostgreSQL connection fields are empty ` +
+          `(host/database/user). Check the {{ environment.* }} templating ` +
+          `for this environment.`,
+      );
+    }
+
     const connectStart = performance.now();
     const connection = await this.dbClient.connect({
-      host: validatedConfig.host,
+      host: rendered.data.host,
       port: validatedConfig.port,
-      database: validatedConfig.database,
-      user: validatedConfig.user,
+      database: rendered.data.database,
+      user: rendered.data.user,
       password: validatedConfig.password,
       ssl: validatedConfig.ssl ? { rejectUnauthorized: false } : undefined,
       connectionTimeoutMillis: validatedConfig.timeout,