@checkstack/healthcheck-script-backend 0.3.16 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,129 @@
 # @checkstack/healthcheck-script-backend
 
+## 0.4.0
+
+### Minor Changes
+
+- a06b899: Overhaul shell + inline-script health checks with real shell semantics, real ESM execution, and upstream Node/Bun IntelliSense.
+
+  **BREAKING CHANGES**
+
+  - **Shell collector** — the `Execute Script` collector now takes a single `script` string instead of `{ command, args }`. Existing configs are auto-migrated to v2: `command` + `args` are joined with POSIX single-quote escaping into the new `script` field, so behaviour is preserved. Custom UIs that hard-coded `command`/`args` field names need to switch to `script`.
+  - **Inline collector** — scripts are now executed as real ES modules in a Bun subprocess (was: `new Function()` inside a Web Worker). The legacy `return X;` style still works (it's auto-wrapped in an async IIFE), but mixed scripts that `import` _and_ `return` at the top level need to use `export default` for their result.
+
+  **FIXES**
+
+  - Shell scripts containing pipes, redirects, `awk`, command substitution, conditionals etc. no longer fail with `ENOENT`. The collector now runs through `sh -c <script>` instead of passing the full expression as `Bun.spawn`'s argv[0]. This was the original `awk … failed with ENOENT` regression.
+  - Inline scripts can now `import { loadavg } from "node:os"` (and any other `node:*` or `bun` import). They could not before, because the executor wrapped user code inside `new Function(...)` and ran it in a Web Worker that had no Node module access; the wrapper also made top-level `import` syntactically invalid (`Unexpected token '{'`).
+  - Healthcheck editor fields no longer reset while you're editing. The page was re-running its form-state init `useEffect` on every refetch of the configuration query — and that query is invalidated on every realtime `HEALTH_CHECK_RUN_COMPLETED` signal across the platform, so in-progress edits got wiped within seconds. Replaced the naive `useEffect([existingConfig])` with a new `useInitOnceForKey` hook from `@checkstack/ui` that initialises the form only on first load per healthcheck id and ignores background refetches. The hook's decision logic is a pure function (`shouldInitForKey`) and is unit-tested in `useInitOnceForKey.test.ts`.
+  - Switching between healthcheck collectors no longer mis-applies the previous collector's tokenizer / language service to the new editor. `MultiTypeEditorField` was reusing the same React instance across collector switches (same `key="script"` in both `DynamicForm` renders) and `selectedType` was initialised from `useState` only once on first mount. After a shell→typescript switch the new collector's TS content rendered through the shell branch (no TS highlighting, no IntelliSense); the reverse direction tokenised shell content through TS and surfaced nonsense errors like `2304 "Cannot find name 'and'"` on shell comments. Now a `useEffect` re-derives `selectedType` whenever `editorTypes` changes to a set that doesn't contain the current selection.
+  - Monaco workers are now bundled locally via Vite `?worker` imports and wired up through `MonacoEnvironment.getWorker` in a new `monacoWorkers.ts` module. The default `@monaco-editor/loader` CDN path silently failed CORS on worker scripts in some browsers, leaving Monaco's TS service with only the generic `editorWorkerService` — which is enough for tokenizer-only languages like shell but breaks TypeScript's semantic features entirely. Same module configures the TS service singleton (compiler options, eager-model-sync, diagnostics-options-ignore-1108) at module load instead of inside per-editor `onMount`, so the service starts pre-configured regardless of which language opens first. Migrated from the deprecated `monaco.languages.typescript.*` path to `monaco.typescript.*` (the old path is marked `{ deprecated: true }` in monaco-editor 0.55).
+  - `defineIntegration` / `defineHealthCheck` callback parameters are now typed against the schema. Previously the virtual module declared them as `(ctx: unknown) => …`, so writing `defineIntegration(async (context) => { console.log(context.event.eventId) })` produced `'context' is of type 'unknown'. (18046)`. The result type and the shared `IntegrationScriptContext` / `HealthCheckScriptContext` interfaces are now generated together in `scriptContext.ts`, so both the function-arg form and the ambient `declare const context` reference the same schema-typed shape.
+  - The shell starter template no longer uses Linux-only `/proc/loadavg` (which fails on macOS satellites with `awk: can't open file /proc/loadavg`). It now reads the 1-minute load average via `uptime` and parses both the Linux (`load average: 0.00, 0.01, 0.05`) and macOS (`load averages: 0.45 0.55 0.65`) output formats with a portable `sed`/`awk`/`tr` pipeline.
+  - Starter-template seeding is now self-healing. `DynamicForm`'s schema-defaults `useEffect` fires AFTER child seed effects in React's child-before-parent order, so the previous one-shot seed got clobbered back to `""` by the defaults call on first mount and never re-fired. Replaced the `[]`-deps effect with a two-effect pattern: an observer that latches `hasSeededRef = true` the first time `value` is observed non-empty, and a seed effect that keeps re-installing the starter while the latch is open. Once the seed sticks the latch closes; subsequent edits and realtime refetches don't re-trigger.
+
+  **NEW**
+
+  - The Monaco editor for inline scripts now mounts the real upstream `@types/node` + `bun-types` declarations as a virtual filesystem (lazy-loaded as its own JS chunk), so IntelliSense covers the full Node/Bun stdlib, the `Bun` global, `process.env`, `Buffer`, etc. DOM types are deliberately excluded so suggestions stay focused on the backend surface. `context.config` is typed from the collector's own JSON Schema.
+  - New `healthcheckScriptContext` / `integrationScriptContext` helpers (exported from `@checkstack/ui`) build a complete editor bundle in one call: TS declarations (`context.config` / `context.event.payload` + the virtual `@checkstack/healthcheck` / `@checkstack/integration` result-type modules), starter templates per language, and the shell env-var list (with platform-injected `EVENT_ID` / `DELIVERY_ID` / `PAYLOAD_*` for integrations). Both call sites — `CollectorSection.tsx` and `CreateSubscriptionDialog.tsx` — were rewired to use them, fixing a long-standing wiring gap where IntelliSense for injected values silently never reached the editor.
+  - Inline scripts can now `import { defineHealthCheck } from "@checkstack/healthcheck"` (or `defineIntegration` for integrations) for a typed return-shape assertion. The editor catches `{ success: "yes" }` as a type error against `HealthCheckScriptResult`. The runtime is just an identity function — the collector rewrites the import to a sibling helper file in the temp dir before executing.
+  - Shell editors now autocomplete env-vars after `$` and `${`. The completion list is supplied by `healthcheckScriptContext` (safe-vars whitelist) and `integrationScriptContext` (whitelist + `EVENT_ID` etc. + `PAYLOAD_*` flattened from the event's payload schema). The matcher is pure and unit-tested in `shellEnvVarMatcher.test.ts` so regex regressions are caught locally.
+  - Empty editor fields are now seeded with a working starter template per language (inline TS uses `defineHealthCheck`, inline shell does the `awk` load-average check, integration TS shows `defineIntegration` with `context.event`, integration shell lists the `$EVENT_ID` / `$PAYLOAD_*` env vars). Users see a runnable example instead of a blank canvas; once they edit, we leave their content alone.
+  - Hardened concurrency + cleanup model documented and tested: each invocation gets its own `mkdtemp` directory + UUID result marker; the `finally` block clears the timeout handle, kills any surviving subprocess (idempotent), and removes the temp directory on success, throw, _and_ timeout. New `concurrency.test.ts` proves 20 parallel inline scripts don't cross wires and that the temp-dir count returns to baseline after throws and timeouts.
+
+  **TESTING**
+
+  Tight unit tests added so changes to the editor surface don't need smoke testing:
+
+  - `scriptContext.test.ts` — 18 tests covering the generated type declarations (including explicit regression guards for `defineIntegration` / `defineHealthCheck` callback params being typed against the shared context interface rather than `unknown`), starter templates (including a guard that the shell starter doesn't depend on Linux-only `/proc/loadavg`), shell env-vars for both healthcheck + integration flavours, plus the schema-flattening utility.
+  - `shellEnvVarMatcher.test.ts` — 12 tests covering the bare `$` / braced `${` / partial-name / case-insensitive matching logic that powers Monaco's shell completion.
+  - `inline-script-normaliser.test.ts` — 13 tests covering the legacy `return X;` → IIFE wrap path, the ESM-passthrough path, and the `@checkstack/healthcheck` import rewriter.
+  - `inline-script-collector.test.ts` — 18 tests including ones that actually execute a script importing `defineHealthCheck` (named-import form) AND using the global `defineHealthCheck` (no import) to prove both code paths resolve at runtime.
+  - `concurrency.test.ts` — 4 tests proving 20 parallel runs don't collide and that the temp-dir count returns to baseline after success, throw, and timeout.
+  - `useInitOnceForKey.test.ts` — 10 tests proving the healthcheck-editor form state isn't reset when react-query refetches in the background (the original "fields reset while I'm typing" regression).
+  - `starterTemplateSelector.test.ts` — 7 tests for the pure decision function powering empty-field seeding.
+  - `security.test.ts` — added an integration test that actually executes the portable load-average pipeline through `Bun.spawn` on the current OS, catching `/proc/loadavg`-style regressions at CI time on macOS runners.
+
+  **SECURITY**
+
+  - Same env-var whitelist as before (`PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `LC_CTYPE`, `TZ`, `TMPDIR`, `HOSTNAME`, `SHELL`). Backend secrets in the satellite process's environment remain invisible to user scripts.
+
+  See `docs/src/content/docs/backend/script-healthchecks.md` for the full user-facing guide.
+
+### Patch Changes
+
+- a06b899: Dead-code audit cleanup and a small platform of shared notification helpers.
+
+  **Removed (dead code)**
+
+  - `core/backend/src/plugin-manager/deregistration-guard.ts` deleted. The exported `assertCanDeregister()` was never called and was a less-complete version of the dependents+isUninstallable checks already done inline by `previewUninstallOriginator` / `uninstallOriginator` in `plugin-manager-orchestrator.ts`.
+  - `createMockQueueFactory` deprecated alias removed from `@checkstack/test-utils-backend`. Use `createMockQueueManager` directly.
+
+  **New shared helpers**
+
+  - `@checkstack/backend-api` now exports `requestTimeoutMs()` — a Zod field builder for outbound HTTP request timeouts (1s..60s, default 10s). Replaces hand-rolled `configNumber({}).min(1000).max(60_000).default(10_000)` in `integration-webhook-backend`, `integration-script-backend`, and `healthcheck-script-backend`'s inline collector.
+  - `@checkstack/notification-common` now exports `SubjectStatusSchema` / `SubjectStatus`, mirroring the existing `ImportanceSchema`.
+  - `@checkstack/notification-backend` now exports:
+    - `SUBJECT_STATUS_EMOJI` / `IMPORTANCE_EMOJI` — the shared status / importance emoji maps that Discord, Slack, Teams, Webex and Telegram previously each redefined inline.
+    - `postJson(opts)` — a timeout-bounded `fetch` wrapper that handles non-2xx logging and error mapping for webhook-style POSTs. Returns `{ ok: true, response } | { ok: false, error }`.
+
+  **Migrated to shared helpers**
+
+  - Discord, Slack, Gotify, Pushover notification backends now use `postJson`. Outer try/catch + per-plugin error mapping deleted (~140 LOC).
+  - Discord, Slack, Teams, Telegram, Webex notification backends now use `IMPORTANCE_EMOJI`. Discord, Slack, Teams use `SUBJECT_STATUS_EMOJI`.
+  - Teams, Webex, Backstage, Telegram kept their inline fetch/Bot logic: their error strings surface server response bodies to operators, or the transport isn't raw `fetch` (Telegram uses `grammy`'s `Bot`).
+
+  **API surface tightening**
+
+  - Per-plugin test-only re-exports in 6 notification backends (Pushover, Gotify, Backstage, Slack, Discord, Teams) and the `CertificateInfo` interface in `healthcheck-tls-backend/strategy.ts` are now JSDoc-tagged `@internal`. No behaviour change; signals that downstream consumers must not depend on them.
+
+- a06b899: Extract shared `EsmScriptRunner` + `ShellScriptRunner` utilities, fix HIGH-severity privilege amplification in the integration TS provider, and harden the integration shell setupGuide example.
+
+  **SECURITY FIX (HIGH)**
+
+  The integration TS provider (`@checkstack/integration-script-backend` → `scriptProvider`) previously executed user scripts via `new Function(script)` in the satellite's main V8 isolate. A user with `integrationAccess.manage` could read `globalThis.process.env` directly (`DATABASE_URL`, `JWT_SECRET`, queue credentials, signing keys, …) and exfiltrate them through `result.id` — which round-trips into `delivery_logs.externalId` and is readable via the `getDeliveryLog` ORPC procedure. The same permission grants no legitimate API to those secrets; this was a privilege amplification.
+
+  The provider now runs user scripts in a fresh Bun subprocess (matching the healthcheck inline-script collector model). The subprocess receives only a curated `SAFE_ENV_VARS` whitelist (`PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `LC_CTYPE`, `TZ`, `TMPDIR`, `HOSTNAME`, `SHELL`) — backend secrets are no longer visible to user code. Filesystem reads, network calls (`fetch`), and the rest of the Node/Bun standard library continue to work, just in an isolated process.
+
+  **BREAKING CHANGE (`@checkstack/integration-script-backend`)**
+
+  User scripts can no longer read the satellite process's environment variables (`process.env.DATABASE_URL` etc. return `undefined`). Scripts that legitimately need configuration should accept it via the provider's `script` field input, not by introspecting the host environment. The full Node/Bun stdlib remains available; only the env scrub is new.
+
+  **REFACTOR — new shared utilities in `@checkstack/backend-api`**
+
+  Both the healthcheck and integration plugins had near-identical inline implementations of "run a user script in a subprocess sandbox" (ESM path) and "run a user shell script through `sh -c`" (shell path). These are now canonical, single-source-of-truth utilities:
+
+  - **`defaultEsmScriptRunner.run({ script, context, timeoutMs, helperModuleName?, helperFunctionName? })`** — writes the user module to a fresh `mkdtemp` directory along with a generated runner module, spawns a Bun subprocess with `pickSafeEnv()`, parses the result back through a UUID-tagged stderr marker, and tears everything down in `finally` (`clearTimeout` + `proc.kill()` + recursive `rm`). The optional `helperModuleName` / `helperFunctionName` pair drops a sibling `_helpers.mjs` file and rewrites `import { <fn> } from "<module>"` to point at it (this is the trick that makes `@checkstack/healthcheck` / `@checkstack/integration` resolve at runtime even though they're not real npm packages).
+  - **`defaultShellScriptRunner.run({ script, timeoutMs, cwd?, env? })`** — invokes `sh -c <script>` via `Bun.spawn` with `SAFE_ENV_VARS` (user-supplied `env` merged on top), `Promise.race` timeout with `proc.kill()` on expiry, and the same `clearTimeout` + `proc.kill()` cleanup in `finally`.
+
+  Both runners expose `EsmScriptRunner` / `ShellScriptRunner` interfaces so tests can inject mocks without touching the spawn path. The four call sites (`plugins/healthcheck-script-backend/src/inline-script-collector.ts`, `strategy.ts` and `plugins/integration-script-backend/src/provider.ts`, `shell-provider.ts`) collapse from full inline implementations to ~8-line adapters.
+
+  **FIXES**
+
+  - Integration shell provider's `setupGuide` example replaced the unsafe `curl -d "{\"title\": \"$PAYLOAD_TITLE\"}"` JSON interpolation with a `jq -n --arg title "$PAYLOAD_TITLE" '{title: $title}'` pattern. The previous example demonstrated a shell-injection vulnerability whenever event payload values contained shell-special or JSON-special characters (which they can, since payloads come from other plugins / events / GitOps reconciles).
+  - The shared shell runner adds `clearTimeout` + idempotent `proc?.kill()` in `finally`, fixing a leaked event-loop timer in the integration shell provider's previous inline implementation.
+
+  **TESTS**
+
+  - New `core/backend-api/src/esm-script-runner.test.ts` covering `normaliseUserScript` + `rewriteHelperImports` across both healthcheck and integration helper-module names, including regex-metacharacter escape coverage.
+  - The plugin-local `inline-script-normaliser.test.ts` was deleted; the same coverage (plus more) lives at the canonical location with the utility.
+  - Integration TS provider console-logging tests updated: in the subprocess model, `console.warn` and `console.error` both write to stderr (Bun matches Node), so the provider forwards every stderr line to `logger.error`. `console.log({…})` uses Bun's native `util.inspect` format rather than `JSON.stringify`, so the JSON-logging test now asserts on substring presence instead of strict serialisation.
+
+  2047 tests pass, lint + typecheck clean.
+
+- Updated dependencies [a06b899]
+- Updated dependencies [a06b899]
+  - @checkstack/backend-api@0.16.0
+  - @checkstack/healthcheck-common@1.1.1
+
+## 0.3.17
+
+### Patch Changes
+
+- Updated dependencies [1909a61]
+- Updated dependencies [b33fb4d]
+  - @checkstack/backend-api@0.15.3
+
 ## 0.3.16
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-script-backend",
-  "version": "0.3.16",
+  "version": "0.4.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -14,15 +14,15 @@
     "pack": "bunx @checkstack/scripts plugin-pack"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.15.1",
-    "@checkstack/common": "0.9.0",
-    "@checkstack/healthcheck-common": "1.0.2"
+    "@checkstack/backend-api": "0.15.3",
+    "@checkstack/common": "0.10.0",
+    "@checkstack/healthcheck-common": "1.1.0"
   },
   "devDependencies": {
     "@types/bun": "^1.0.0",
     "typescript": "^5.0.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.1"
+    "@checkstack/scripts": "0.3.2"
   },
   "description": "Checkstack healthcheck-script-backend plugin",
   "author": {

package/src/concurrency.test.ts

@@ -0,0 +1,147 @@
+import { describe, expect, it } from "bun:test";
+import { readdir } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { InlineScriptCollector } from "./inline-script-collector";
+import { ScriptHealthCheckStrategy } from "./strategy";
+import type { ScriptTransportClient } from "./transport-client";
+
+/**
+ * Concurrency + cleanup guarantees.
+ *
+ * These tests are slower than the unit tests (each spawns 20+ subprocesses)
+ * but they're the only place where we exercise the actual isolation
+ * properties — that two parallel inline scripts can't read each other's
+ * temp files, and that the temp-dir count returns to baseline once
+ * everything completes (i.e. nothing leaks on success, failure, or timeout).
+ */
+
+const PARALLELISM = 20;
+const TMP_PREFIX = "checkstack-script-";
+
+async function countLeakedTmpDirs(): Promise<number> {
+  const entries = await readdir(tmpdir());
+  return entries.filter((name) => name.startsWith(TMP_PREFIX)).length;
+}
+
+const mockClient: ScriptTransportClient = {
+  exec: async () => ({
+    exitCode: 0,
+    stdout: "",
+    stderr: "",
+    timedOut: false,
+  }),
+};
+
+describe("inline-script concurrency", () => {
+  it("isolates parallel runs — each sees its own `context.config`", async () => {
+    // Each script reads its own config.value via `context.config.value` and
+    // returns it. If isolation is broken (two scripts share a tmp dir, env,
+    // or the same runner file by accident), we'd see crossed values here.
+    const collector = new InlineScriptCollector();
+
+    const runs = Array.from({ length: PARALLELISM }, (_, i) => i);
+
+    const results = await Promise.all(
+      runs.map(async (i) => {
+        const res = await collector.execute({
+          // The config carries the index; the script returns it via `value`.
+          config: {
+            // @ts-expect-error — we deliberately pass an extra prop the
+            // schema doesn't know about; the runner serialises the whole
+            // config object as `context.config`, so the script can read it.
+            value: i,
+            script: `
+              // @ts-ignore — context is injected at runtime
+              export default { success: true, value: context.config.value };
+            `,
+            timeout: 30_000,
+          },
+          client: mockClient,
+          pluginId: "concurrency-test",
+        });
+        return res.result.value;
+      }),
+    );
+
+    // Each run should have returned its own index — no crossed wires.
+    expect(results.sort((a, b) => (a ?? 0) - (b ?? 0))).toEqual(runs);
+  }, 60_000);
+
+  it("cleans up temp dirs even when scripts throw", async () => {
+    const collector = new InlineScriptCollector();
+    const before = await countLeakedTmpDirs();
+
+    await Promise.all(
+      Array.from({ length: PARALLELISM }, () =>
+        collector.execute({
+          config: {
+            // Mix of throwing and successful scripts to exercise both paths.
+            script: `
+              if (Math.random() > 0.5) throw new Error("boom");
+              export default { success: true };
+            `,
+            timeout: 30_000,
+          },
+          client: mockClient,
+          pluginId: "concurrency-test",
+        }),
+      ),
+    );
+
+    const after = await countLeakedTmpDirs();
+    expect(after).toBe(before);
+  }, 60_000);
+
+  it("cleans up temp dirs when scripts time out", async () => {
+    const collector = new InlineScriptCollector();
+    const before = await countLeakedTmpDirs();
+
+    await Promise.all(
+      Array.from({ length: 5 }, () =>
+        collector.execute({
+          config: {
+            script: `await new Promise((r) => setTimeout(r, 60_000));`,
+            timeout: 1000,
+          },
+          client: mockClient,
+          pluginId: "concurrency-test",
+        }),
+      ),
+    );
+
+    // Give the OS a moment to actually reap the killed subprocesses before
+    // we check; rm runs synchronously after each .execute() resolves, but
+    // the kernel can be slow to drop fds on macOS.
+    await new Promise((r) => setTimeout(r, 100));
+
+    const after = await countLeakedTmpDirs();
+    expect(after).toBe(before);
+  }, 30_000);
+});
+
+describe("shell-script concurrency", () => {
+  it("isolates parallel runs — each sees its own arguments via env", async () => {
+    // No temp file involvement on the shell path, so this test just
+    // exercises the spawn-per-call guarantee. Each script echoes the
+    // value of its own MY_RUN env var; we check no crossed values.
+    const strategy = new ScriptHealthCheckStrategy();
+    const connected = await strategy.createClient({ timeout: 5000 });
+
+    const runs = Array.from({ length: PARALLELISM }, (_, i) => i);
+
+    const results = await Promise.all(
+      runs.map((i) =>
+        connected.client.exec({
+          script: 'printf "%s" "$MY_RUN"',
+          env: { MY_RUN: String(i) },
+          timeout: 5000,
+        }),
+      ),
+    );
+
+    connected.close();
+
+    const seen = results.map((r) => Number.parseInt(r.stdout, 10));
+    expect(seen.sort((a, b) => a - b)).toEqual(runs);
+  }, 60_000);
+});

package/src/execute-collector.test.ts

@@ -28,8 +28,13 @@ describe("ExecuteCollector", () => {
       const collector = new ExecuteCollector();
       const client = createMockClient({ exitCode: 0, stdout: "Hello World" });
 
+      const config: ExecuteConfig = {
+        script: "echo 'Hello World'",
+        timeout: 5000,
+      };
+
       const result = await collector.execute({
-        config: { command: "echo", args: ["Hello", "World"], timeout: 5000 },
+        config,
         client,
         pluginId: "test",
       });
@@ -50,7 +55,7 @@ describe("ExecuteCollector", () => {
       });
 
       const result = await collector.execute({
-        config: { command: "nonexistent", args: [], timeout: 5000 },
+        config: { script: "exit 1", timeout: 5000 },
         client,
         pluginId: "test",
       });
@@ -65,7 +70,7 @@ describe("ExecuteCollector", () => {
       const client = createMockClient({ timedOut: true, exitCode: -1 });
 
       const result = await collector.execute({
-        config: { command: "sleep", args: ["999"], timeout: 100 },
+        config: { script: "sleep 999", timeout: 100 },
         client,
         pluginId: "test",
       });
@@ -74,14 +79,13 @@ describe("ExecuteCollector", () => {
       expect(result.result.success).toBe(false);
     });
 
-    it("should pass correct parameters to client", async () => {
+    it("should pass the script, cwd and env through to the client", async () => {
       const collector = new ExecuteCollector();
       const client = createMockClient();
 
       await collector.execute({
         config: {
-          command: "/usr/bin/check",
-          args: ["--verbose"],
+          script: "awk '/load/ {print $1}' /proc/loadavg | head -1",
           cwd: "/tmp",
           env: { MY_VAR: "value" },
           timeout: 3000,
@@ -91,8 +95,7 @@ describe("ExecuteCollector", () => {
       });
 
       expect(client.exec).toHaveBeenCalledWith({
-        command: "/usr/bin/check",
-        args: ["--verbose"],
+        script: "awk '/load/ {print $1}' /proc/loadavg | head -1",
         cwd: "/tmp",
         env: { MY_VAR: "value" },
         timeout: 3000,
@@ -100,6 +103,41 @@ describe("ExecuteCollector", () => {
     });
   });
 
+  describe("migration", () => {
+    it("collapses legacy {command, args} into a single shell script", async () => {
+      const collector = new ExecuteCollector();
+      const v1 = {
+        command: "echo",
+        args: ["Hello", "World"],
+        timeout: 5000,
+      };
+
+      // Versioned.parse() applies migrations transparently when the stored
+      // value declares an older version. Mirror what storage does:
+      const migrated = await collector.config.parse({ version: 1, data: v1 });
+
+      expect(migrated.script).toBe("echo Hello World");
+      expect(migrated.timeout).toBe(5000);
+    });
+
+    it("quotes args that contain shell metacharacters", async () => {
+      const collector = new ExecuteCollector();
+      const v1 = {
+        command: "/bin/sh",
+        args: ["-c", "echo 'hi there'"],
+        timeout: 5000,
+      };
+
+      const migrated = await collector.config.parse({ version: 1, data: v1 });
+
+      // The script should re-quote args so re-execution via `sh -c` is safe.
+      expect(migrated.script).toContain("/bin/sh");
+      expect(migrated.script).toContain("-c");
+      // The embedded quotes must be preserved (single-quoted form).
+      expect(migrated.script).toMatch(/echo/);
+    });
+  });
+
   describe("mergeResult", () => {
     it("should calculate average execution time and success rate", () => {
       const collector = new ExecuteCollector();
@@ -190,7 +228,7 @@ describe("ExecuteCollector", () => {
       const collector = new ExecuteCollector();
 
       expect(collector.id).toBe("execute");
-      expect(collector.displayName).toBe("Execute Script");
+      expect(collector.displayName).toBe("Shell Script");
       expect(collector.allowMultiple).toBe(true);
       expect(collector.supportedPlugins).toHaveLength(1);
     });

package/src/execute-collector.ts

@@ -22,27 +22,59 @@ import { pluginMetadata } from "./plugin-metadata";
 import type { ScriptTransportClient } from "./transport-client";
 
 // ============================================================================
-// CONFIGURATION SCHEMA
+// LEGACY CONFIG (v1) — kept for migration
 // ============================================================================
 
-const executeConfigSchema = z.object({
-  command: configString({
+interface ExecuteConfigV1 {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  timeout: number;
+}
+
+/**
+ * Quote an arg for the shell when migrating a v1 command+args pair into a
+ * single v2 script. Bare identifiers are passed through untouched; anything
+ * else gets single-quoted with embedded quotes escaped.
+ */
+function shellQuote(arg: string): string {
+  if (arg === "") return "''";
+  if (/^[A-Za-z0-9_\-./=:@%+]+$/.test(arg)) return arg;
+  // POSIX single-quote escape: close, emit an escaped quote, reopen.
+  return `'${arg.replaceAll("'", String.raw`'\''`)}'`;
+}
+
+// ============================================================================
+// CONFIGURATION SCHEMA (v2)
+// ============================================================================
+
+const executeConfigSchemaV2 = z.object({
+  script: configString({
     "x-editor-types": ["shell"],
-  }).describe("Shell command or script to execute"),
-  args: z.array(z.string()).default([]).describe("Command arguments"),
-  cwd: z.string().optional().describe("Working directory"),
+  }).describe(
+    "Shell script source. Executed via `sh -c`, so pipes, redirects, `if`/`for`/`while`, variable expansion, command substitution etc. all work. Exit non-zero to fail the check.",
+  ),
+  cwd: z
+    .string()
+    .optional()
+    .describe("Working directory for the script (defaults to the satellite's CWD)"),
   env: z
     .record(z.string(), z.string())
     .optional()
-    .describe("Environment variables"),
+    .describe(
+      "Extra environment variables to expose to the script. Merged on top of the safe-vars whitelist (PATH, HOME, ...).",
+    ),
   timeout: z
     .number()
+    .int()
     .min(100)
+    .max(300_000)
     .default(30_000)
-    .describe("Timeout in milliseconds"),
+    .describe("Maximum execution time in milliseconds"),
 });
 
-export type ExecuteConfig = z.infer<typeof executeConfigSchema>;
+export type ExecuteConfig = z.infer<typeof executeConfigSchemaV2>;
 
 // ============================================================================
 // RESULT SCHEMAS
@@ -120,8 +152,19 @@ export type ExecuteAggregatedResult = InferAggregatedResult<
 // ============================================================================
 
 /**
- * Built-in Script execute collector.
- * Runs commands and checks results.
+ * Shell-script execute collector.
+ *
+ * The user provides a shell script as a single string; we run it through
+ * `sh -c`. That means anything POSIX `sh` accepts works as expected:
+ *
+ * ```sh
+ * # Fail when 1-minute load average exceeds 0.60 (portable: Linux + macOS).
+ * load=$(uptime | sed 's/.*load average[s]*: //' | awk '{print $1}' | tr -d ',')
+ * awk -v l="$load" 'BEGIN { exit (l+0 > 0.60) ? 1 : 0 }'
+ * ```
+ *
+ * Exit code 0 = healthy, anything else = unhealthy. stdout / stderr are
+ * captured and reported with the run.
  */
 export class ExecuteCollector implements CollectorStrategy<
   ScriptTransportClient,
@@ -130,14 +173,36 @@ export class ExecuteCollector implements CollectorStrategy<
   ExecuteAggregatedResult
 > {
   id = "execute";
-  displayName = "Execute Script";
-  description = "Execute a command or script and check the result";
+  displayName = "Shell Script";
+  description = "Run a shell script and treat exit code 0 as healthy";
 
   supportedPlugins = [pluginMetadata];
 
   allowMultiple = true;
 
-  config = new Versioned({ version: 1, schema: executeConfigSchema });
+  config = new Versioned({
+    version: 2,
+    schema: executeConfigSchemaV2,
+    migrations: [
+      {
+        fromVersion: 1,
+        toVersion: 2,
+        description:
+          "Collapse {command, args} into a single shell script executed via `sh -c`",
+        migrate: (data: ExecuteConfigV1): ExecuteConfig => {
+          const parts = [data.command, ...(data.args ?? [])].map((arg) =>
+            shellQuote(arg),
+          );
+          return {
+            script: parts.join(" "),
+            cwd: data.cwd,
+            env: data.env,
+            timeout: data.timeout,
+          };
+        },
+      },
+    ],
+  });
   result = new Versioned({ version: 1, schema: executeResultSchema });
   aggregatedResult = new VersionedAggregated({
     version: 1,
@@ -155,8 +220,7 @@ export class ExecuteCollector implements CollectorStrategy<
     const startTime = Date.now();
 
     const response = await client.exec({
-      command: config.command,
-      args: config.args,
+      script: config.script,
       cwd: config.cwd,
       env: config.env,
       timeout: config.timeout,