@checkstack/healthcheck-ssh-backend 0.4.3 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,77 @@
 # @checkstack/healthcheck-ssh-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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-ssh-backend",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -17,9 +17,9 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.31.0",
+    "@checkstack/backend-api": "0.31.1",
     "@checkstack/common": "0.22.0",
-    "@checkstack/healthcheck-common": "1.15.0",
+    "@checkstack/healthcheck-common": "1.16.0",
     "@checkstack/healthcheck-ssh-common": "0.1.29",
     "ssh2": "1.16.0"
   },

package/src/command-collector.test.ts

@@ -67,6 +67,26 @@ describe("CommandCollector", () => {
 
       expect(client.exec).toHaveBeenCalledWith("ls -la /tmp");
     });
+
+    // A templatable `command` that renders to empty (e.g. `{{ environment.command }}`
+    // with no environment) is a config error - it must fail as a transport
+    // failure (populated `error`) and never invoke the client.
+    it("should return a transport error when the rendered command is empty", async () => {
+      const collector = new CommandCollector();
+      const client = createMockClient();
+
+      const result = await collector.execute({
+        config: { command: "   " },
+        client,
+        pluginId: "test",
+      });
+
+      expect(result.error).toMatch(/Rendered command is empty/);
+      expect(result.result.exitCode).toBe(0);
+      expect(result.result.stdout).toBe("");
+      expect(result.result.stderr).toBe("");
+      expect(client.exec).not.toHaveBeenCalled();
+    });
   });
 
   describe("mergeResult", () => {

package/src/command-collector.ts

@@ -1,6 +1,7 @@
 import {
   Versioned,
   z,
+  configString,
   type HealthCheckRunForAggregation,
   type CollectorResult,
   type CollectorStrategy,
@@ -24,11 +25,27 @@ import type { SshTransportClient } from "@checkstack/healthcheck-ssh-common";
 // ============================================================================
 
 const commandConfigSchema = z.object({
-  command: z.string().min(1).describe("Shell command to execute"),
+  // Templatable: supports `{{ environment.command }}` so one config covers N
+  // environments. `.min(1)` still guards the STORED value (a `{{ }}` template is
+  // non-empty); the CONCRETE rendered command is re-checked POST-RENDER in
+  // `execute` because an empty render must not run as a successful command.
+  command: configString({ "x-templatable": true })
+    .min(1)
+    .describe(
+      "Shell command to execute. Supports templating, e.g. {{ environment.command }}",
+    ),
 });
 
 export type CommandConfig = z.infer<typeof commandConfigSchema>;
 
+/**
+ * Post-render validator for the rendered `command`. An empty render (e.g. an
+ * env-less run resolving `{{ environment.command }}` to "") is a config error
+ * that prevents the probe - transport-failure semantics - not a healthy empty
+ * command.
+ */
+const renderedCommandSchema = z.string().trim().min(1);
+
 // ============================================================================
 // RESULT SCHEMAS
 // ============================================================================
@@ -152,7 +169,27 @@ export class CommandCollector implements CollectorStrategy<
     pluginId: string;
   }): Promise<CollectorResult<CommandResult>> {
     const startTime = Date.now();
-    const result = await client.exec(config.command);
+
+    // Post-render guard: `command` 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 command.
+    const command = renderedCommandSchema.safeParse(config.command);
+    if (!command.success) {
+      return {
+        result: {
+          exitCode: 0,
+          stdout: "",
+          stderr: "",
+          executionTimeMs: Date.now() - startTime,
+        },
+        error:
+          `Rendered command is empty: ${JSON.stringify(config.command)}. ` +
+          `Check the {{ environment.* }} templating for this environment.`,
+      };
+    }
+
+    const result = await client.exec(command.data);
     const executionTimeMs = Date.now() - startTime;
 
     return {

package/src/strategy.test.ts

@@ -66,6 +66,63 @@ describe("SshHealthCheckStrategy", () => {
         }),
       ).rejects.toThrow("Connection refused");
     });
+
+    it("should connect with a concrete rendered host and username", async () => {
+      const mockClient = createMockClient();
+      const strategy = new SshHealthCheckStrategy(mockClient);
+
+      const connectedClient = await strategy.createClient({
+        host: "ssh.prod.example.com",
+        port: 22,
+        username: "deploy",
+        password: "secret",
+        timeout: 5000,
+      });
+
+      expect(mockClient.connect).toHaveBeenCalledWith(
+        expect.objectContaining({
+          host: "ssh.prod.example.com",
+          username: "deploy",
+        }),
+      );
+
+      connectedClient.close();
+    });
+
+    // A required templatable field (host/username) that renders to empty (e.g.
+    // `{{ environment.host }}` with no environment) is a config error - it must
+    // fail as a transport failure, never attempt an empty connection.
+    it("should throw when the rendered host is empty", async () => {
+      const mockClient = createMockClient();
+      const strategy = new SshHealthCheckStrategy(mockClient);
+
+      await expect(
+        strategy.createClient({
+          host: "",
+          port: 22,
+          username: "user",
+          password: "secret",
+          timeout: 5000,
+        }),
+      ).rejects.toThrow(/Rendered SSH connection fields are empty/);
+      expect(mockClient.connect).not.toHaveBeenCalled();
+    });
+
+    it("should throw when the rendered username is empty/whitespace", async () => {
+      const mockClient = createMockClient();
+      const strategy = new SshHealthCheckStrategy(mockClient);
+
+      await expect(
+        strategy.createClient({
+          host: "localhost",
+          port: 22,
+          username: "   ",
+          password: "secret",
+          timeout: 5000,
+        }),
+      ).rejects.toThrow(/Rendered SSH connection fields are empty/);
+      expect(mockClient.connect).not.toHaveBeenCalled();
+    });
   });
 
   describe("client.exec", () => {

package/src/strategy.ts

@@ -13,6 +13,7 @@ import {
   mergeCounter,
   mergeMinMax,
   z,
+  configString,
   configSecret,
   type ConnectedClient,
   type TransportTimings,
@@ -36,9 +37,16 @@ import type { SshTransportClient, SshCommandResult } from "./transport-client";
  * Configuration schema for SSH health checks.
  */
 export const sshConfigSchema = baseStrategyConfigSchema.extend({
-  host: z.string().describe("SSH server hostname"),
+  // Templatable connection fields: support `{{ environment.host }}` etc. so one
+  // config covers N environments. Presence is enforced POST-RENDER in
+  // `createClient`. The auth secrets stay `configSecret` (never templatable).
+  host: configString({ "x-templatable": true }).describe(
+    "SSH server hostname. Supports templating, e.g. {{ environment.host }}",
+  ),
   port: z.number().int().min(1).max(65_535).default(22).describe("SSH port"),
-  username: z.string().describe("SSH username"),
+  username: configString({ "x-templatable": true }).describe(
+    "SSH username. Supports templating, e.g. {{ environment.user }}",
+  ),
   password: configSecret({ id: "password" })
     .describe("Password for authentication")
     .optional(),
@@ -53,6 +61,15 @@ export const sshConfigSchema = baseStrategyConfigSchema.extend({
 export type SshConfig = z.infer<typeof sshConfigSchema>;
 export type SshConfigInput = z.input<typeof sshConfigSchema>;
 
+/**
+ * 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/username is a config
+ * error that prevents the probe - transport-failure semantics.
+ */
+const renderedRequiredSchema = z.string().trim().min(1);
+
 /**
  * Per-run result metadata.
  */
@@ -293,14 +310,31 @@ export class SshHealthCheckStrategy implements HealthCheckStrategy<
   ): Promise<ConnectedClient<SshTransportClient>> {
     const validatedConfig = this.config.validate(config);
 
+    // Post-render guard: `host`/`username` 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, username: renderedRequiredSchema })
+      .safeParse({
+        host: validatedConfig.host,
+        username: validatedConfig.username,
+      });
+    if (!rendered.success) {
+      throw new Error(
+        `Rendered SSH connection fields are empty (host/username). ` +
+          `Check the {{ environment.* }} templating for this environment.`,
+      );
+    }
+
     // The SSH handshake (TCP connect + auth + channel ready) is a single
     // measurable phase up front; record it as connectMs. The per-command exec
     // time is filled in below as processingMs (last-command-wins).
     const connectStart = performance.now();
     const connection = await this.sshClient.connect({
-      host: validatedConfig.host,
+      host: rendered.data.host,
       port: validatedConfig.port,
-      username: validatedConfig.username,
+      username: rendered.data.username,
       password: validatedConfig.password,
       privateKey: validatedConfig.privateKey,
       passphrase: validatedConfig.passphrase,