@checkstack/satellite-common 0.5.3 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # @checkstack/satellite-common
 
+## 0.7.0
+
+### Minor Changes
+
+- 270ef29: Extend the satellite protocol for script-package distribution: the
+  `authenticated` / `config_updated` payloads now carry an optional
+  `scriptPackagesLockfileHash` (the durable convergence backstop), a new
+  `refresh_script_packages { lockfileHash }` core->satellite control push,
+  and a new `script_package_sync_state` satellite->core report message. All
+  additions are optional / additive, so existing satellites and protocol
+  tests are unaffected.
+- 270ef29: Satellite-side script-package reconciliation over the WS channel.
+
+  - `satellite-common`: WS request/reply messages for pulling the manifest +
+    blobs from core (`request_script_package_manifest` /
+    `request_script_package_blob` -> `script_package_manifest` /
+    `script_package_blob`).
+  - `satellite-backend`: the WS handler answers those requests from the
+    script-packages store (satellites pull from core, never the registry).
+  - `@checkstack/satellite`: the client gains request/reply plumbing + a
+    `SatelliteScriptPackages` manager that reuses the Phase 2 reconciler
+    (`reconcileToHash` + `createReconcileFsDeps`) over the WS transport. It
+    reconciles on a `refresh_script_packages` push and on the
+    assignment-carried hash (startup / reconnect backstop), pulls only missing
+    blobs (delta), materializes via `bun install --offline`, atomically flips
+    `current`, reports sync state back, and degrades cleanly (error state, no
+    stale tree, no registry access) when a blob can't be fetched. Reconciles
+    are serialized + coalesced + idempotent.
+
+- 270ef29: Secrets platform Phase 3: just-in-time secret delivery to satellites + source-side masking, and central-execution injection for healthcheck collectors.
+
+  - New satellite WS messages `request_run_secrets` / `run_secrets`: just
+    before a satellite runs a collector that declares a `secretEnv`, it asks
+    core for that collector's resolved env; core resolves ONLY the secrets the
+    collector's OWN persisted assignment declares (least-privilege — the
+    satellite cannot choose) and replies with the env map (or a clear error).
+    The satellite injects it memory-only for the run and drops it on
+    completion. Secrets never ride the persisted assignment and never touch
+    disk.
+  - Source-side masking: the satellite runs `maskSecrets` over the collector's
+    stdout/stderr/result/error using the run's delivered values BEFORE the
+    result leaves the satellite (defense in depth).
+  - `CollectorStrategy.execute` gains an optional `secretEnv`. The
+    inline-script and shell collectors inject it into the runner
+    (`process.env` / `$VAR`) and mask the values out of their output.
+  - Healthcheck collectors running centrally (the queue executor) also resolve
+    - inject `secretEnv` via `secretResolverRef`, closing the gap where a
+      centrally-run secretEnv collector got no secrets. A missing required
+      secret fails the run clearly in all paths.
+
+### Patch Changes
+
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+- Updated dependencies [b995afb]
+- Updated dependencies [b995afb]
+- Updated dependencies [270ef29]
+- Updated dependencies [270ef29]
+  - @checkstack/healthcheck-common@1.4.0
+
+## 0.6.0
+
+### Minor Changes
+
+- 35bc682: feat(healthcheck): expose check + system run-context to script collectors
+
+  Script health checks can now read which check and system a run is for.
+  Previously shell scripts got only a curated env whitelist and inline
+  scripts only `context.config`, so a script had no built-in way to know
+  its own check name or the system it was checking.
+
+  - `@checkstack/backend-api`: new `CollectorRunContext` type
+    (`{ check: { id, name, intervalSeconds }, system: { id, name } }`) and
+    an optional `runContext` param on `CollectorStrategy.execute`. Optional,
+    so existing collector implementations are unaffected.
+  - Shell-script collector: injects reserved `CHECKSTACK_CHECK_ID`,
+    `CHECKSTACK_CHECK_NAME`, `CHECKSTACK_CHECK_INTERVAL_SECONDS`,
+    `CHECKSTACK_SYSTEM_ID`, `CHECKSTACK_SYSTEM_NAME` env vars (user-supplied
+    `env` still wins on collision).
+  - Inline-script collector: exposes `context.check` and `context.system`
+    alongside `context.config`; the inline-script editor now types them for
+    autocomplete.
+  - Shell editors (health-check collectors and automation shell actions) now
+    also suggest the user's own `env` (JSON) keys as `$NAME` completions, via
+    the new exported `customShellEnvVars` helper. Keys that aren't valid shell
+    identifiers are omitted.
+  - Fix: the Typefox `CodeEditor` captured a stale `onChange` at editor start,
+    so editing one `DynamicForm` field reverted sibling fields changed since
+    mount (e.g. typing in a shell `script` field wiped an unsaved `env` value,
+    or deleted a sibling automation action added after mount). The change
+    handler now routes through a ref to the current `onChange`.
+  - Fix: focusing a JSON editor threw "LanguageStatusService.addStatus is not
+    supported" because the standalone service set omitted `ILanguageStatusService`.
+    That one service is now registered via `serviceOverrides`.
+  - Fix: the automation trigger card nested a `<Badge>` (a `<div>`) inside a
+    `<p>`, producing a `validateDOMNesting` warning. Switched the wrapper to a
+    `<div>`.
+  - Local runs (`queue-executor`) and satellite runs both populate the
+    context. `SatelliteAssignment` (and the `getAssignmentsForSatellite`
+    RPC output) gained optional `configName` / `systemName` so the metadata
+    reaches satellite-side execution; `HealthCheckService` resolves the
+    system name via the catalog client.
+
+  BREAKING CHANGE: `createHealthCheckRouter` now requires a `catalogClient`
+  option (used to resolve system names for satellite assignments). Update
+  call sites to pass the catalog RPC client.
+
+### Patch Changes
+
+- Updated dependencies [6d52276]
+- Updated dependencies [35bc682]
+  - @checkstack/common@0.12.0
+  - @checkstack/healthcheck-common@1.3.0
+  - @checkstack/signal-common@0.2.5
+
 ## 0.5.3
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/satellite-common",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -9,16 +9,16 @@
     }
   },
   "dependencies": {
-    "@checkstack/common": "0.11.0",
-    "@checkstack/healthcheck-common": "1.1.2",
-    "@checkstack/signal-common": "0.2.4",
+    "@checkstack/common": "0.12.0",
+    "@checkstack/healthcheck-common": "1.3.0",
+    "@checkstack/signal-common": "0.2.5",
     "@orpc/contract": "^1.13.14",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "typescript": "^5.7.2",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.3"
+    "@checkstack/scripts": "0.3.4"
   },
   "scripts": {
     "typecheck": "tsgo -b",

package/src/index.ts

@@ -29,6 +29,14 @@ export {
   type AuthFailedMessage,
   type ConfigUpdatedMessage,
   type ShutdownMessage,
+  type ScriptPackageSyncStateMessage,
+  type RefreshScriptPackagesMessage,
+  type ScriptPackageManifestMessage,
+  type ScriptPackageBlobMessage,
+  type RequestScriptPackageManifestMessage,
+  type RequestScriptPackageBlobMessage,
+  type RequestRunSecretsMessage,
+  type RunSecretsMessage,
 } from "./protocol";
 export {
   SATELLITE_STATUS_CHANGED,

package/src/protocol.test.ts

@@ -0,0 +1,150 @@
+import { describe, test, expect } from "bun:test";
+import {
+  SatelliteAssignmentSchema,
+  CoreToSatelliteMessageSchema,
+  SatelliteToCoreMessageSchema,
+} from "./protocol";
+
+describe("SatelliteAssignmentSchema", () => {
+  const base = {
+    configId: "config-1",
+    systemId: "system-1",
+    strategyId: "http",
+    config: {},
+    intervalSeconds: 60,
+  };
+
+  test("parses an assignment WITH configName and systemName", () => {
+    const parsed = SatelliteAssignmentSchema.parse({
+      ...base,
+      configName: "API health",
+      systemName: "Production API",
+    });
+
+    expect(parsed.configName).toBe("API health");
+    expect(parsed.systemName).toBe("Production API");
+  });
+
+  test("parses an assignment WITHOUT configName and systemName (optional)", () => {
+    const parsed = SatelliteAssignmentSchema.parse(base);
+
+    expect(parsed.configName).toBeUndefined();
+    expect(parsed.systemName).toBeUndefined();
+  });
+});
+
+describe("script-packages protocol extensions", () => {
+  test("authenticated carries an optional scriptPackagesLockfileHash", () => {
+    const withHash = CoreToSatelliteMessageSchema.parse({
+      type: "authenticated",
+      satelliteId: "sat-1",
+      assignments: [],
+      scriptPackagesLockfileHash: "abc123",
+    });
+    expect(withHash.type).toBe("authenticated");
+    if (withHash.type === "authenticated") {
+      expect(withHash.scriptPackagesLockfileHash).toBe("abc123");
+    }
+  });
+
+  test("authenticated WITHOUT the hash still parses (version-skew safe)", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "authenticated",
+      satelliteId: "sat-1",
+      assignments: [],
+    });
+    expect(parsed.type).toBe("authenticated");
+    if (parsed.type === "authenticated") {
+      expect(parsed.scriptPackagesLockfileHash).toBeUndefined();
+    }
+  });
+
+  test("config_updated carries the optional hash", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "config_updated",
+      assignments: [],
+      scriptPackagesLockfileHash: null,
+    });
+    if (parsed.type === "config_updated") {
+      expect(parsed.scriptPackagesLockfileHash).toBeNull();
+    }
+  });
+
+  test("refresh_script_packages round-trips", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "refresh_script_packages",
+      lockfileHash: "deadbeef",
+    });
+    expect(parsed.type).toBe("refresh_script_packages");
+    if (parsed.type === "refresh_script_packages") {
+      expect(parsed.lockfileHash).toBe("deadbeef");
+    }
+  });
+
+  test("script_package_sync_state round-trips (satellite -> core)", () => {
+    const parsed = SatelliteToCoreMessageSchema.parse({
+      type: "script_package_sync_state",
+      lockfileHash: "abc",
+      status: "ready",
+    });
+    expect(parsed.type).toBe("script_package_sync_state");
+    if (parsed.type === "script_package_sync_state") {
+      expect(parsed.status).toBe("ready");
+      expect(parsed.lockfileHash).toBe("abc");
+    }
+  });
+
+  test("script_package_sync_state carries an error", () => {
+    const parsed = SatelliteToCoreMessageSchema.parse({
+      type: "script_package_sync_state",
+      lockfileHash: null,
+      status: "error",
+      errorMessage: "blob fetch failed",
+    });
+    if (parsed.type === "script_package_sync_state") {
+      expect(parsed.status).toBe("error");
+      expect(parsed.errorMessage).toBe("blob fetch failed");
+    }
+  });
+});
+
+describe("run-secrets request/reply (Phase 3 JIT delivery)", () => {
+  test("parses request_run_secrets", () => {
+    const parsed = SatelliteToCoreMessageSchema.parse({
+      type: "request_run_secrets",
+      requestId: "req-1",
+      configId: "config-1",
+      collectorId: "inline-script",
+      runId: "run-1",
+    });
+    expect(parsed.type).toBe("request_run_secrets");
+    if (parsed.type === "request_run_secrets") {
+      expect(parsed.requestId).toBe("req-1");
+      expect(parsed.collectorId).toBe("inline-script");
+    }
+  });
+
+  test("parses run_secrets reply with env", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "run_secrets",
+      requestId: "req-1",
+      env: { API_TOKEN: "resolved-value" },
+    });
+    if (parsed.type === "run_secrets") {
+      expect(parsed.env).toEqual({ API_TOKEN: "resolved-value" });
+      expect(parsed.error).toBeUndefined();
+    }
+  });
+
+  test("parses run_secrets reply with error (no env)", () => {
+    const parsed = CoreToSatelliteMessageSchema.parse({
+      type: "run_secrets",
+      requestId: "req-1",
+      error: "required secret not available",
+    });
+    if (parsed.type === "run_secrets") {
+      expect(parsed.error).toBe("required secret not available");
+      expect(parsed.env).toBeUndefined();
+    }
+  });
+});

package/src/protocol.ts

@@ -38,6 +38,9 @@ export const SatelliteAssignmentSchema = z.object({
   config: z.record(z.string(), z.unknown()),
   collectors: z.array(SatelliteCollectorConfigSchema).optional(),
   intervalSeconds: z.number(),
+  /** Curated run-context metadata. Optional for version-skew safety. */
+  configName: z.string().optional(),
+  systemName: z.string().optional(),
 });
 
 export type SatelliteAssignment = z.infer<typeof SatelliteAssignmentSchema>;
@@ -75,6 +78,64 @@ const StrategyErrorMessageSchema = z.object({
   message: z.string(),
 });
 
+/**
+ * Reports the satellite's script-package reconcile state back to the core,
+ * which persists it in `script_package_satellite_state` for the admin UI.
+ * Sent after a reconcile attempt (success or failure).
+ */
+const ScriptPackageSyncStateMessageSchema = z.object({
+  type: z.literal("script_package_sync_state"),
+  /** Active lockfile hash this satellite has materialized, or null. */
+  lockfileHash: z.string().nullable(),
+  /** "pending" | "syncing" | "ready" | "error" */
+  status: z.enum(["pending", "syncing", "ready", "error"]),
+  errorMessage: z.string().optional(),
+});
+
+/**
+ * Satellite -> core request for the manifest of a lockfile hash, so the
+ * satellite can diff against its local cache. The core replies with a
+ * `script_package_manifest` message. Delivered over the existing
+ * authenticated WS channel (no separate satellite HTTP auth surface).
+ */
+const RequestScriptPackageManifestMessageSchema = z.object({
+  type: z.literal("request_script_package_manifest"),
+  lockfileHash: z.string(),
+});
+
+/**
+ * Satellite -> core request for one content-addressed blob by integrity.
+ * The core replies with a `script_package_blob` message (base64 bytes).
+ */
+const RequestScriptPackageBlobMessageSchema = z.object({
+  type: z.literal("request_script_package_blob"),
+  integrity: z.string(),
+});
+
+/**
+ * Satellite -> core just-in-time request for a collector run's resolved
+ * secret env, sent right before the satellite executes a collector that
+ * declares a `secretEnv` mapping. The core resolves ONLY that collector's
+ * declared `secretEnv` (read from the persisted assignment — the satellite
+ * does not get to choose which secrets), and replies with a `run_secrets`
+ * message carrying the env map (or an error).
+ *
+ * Secrets NEVER ride the persisted assignment payload; they are delivered
+ * over this authenticated channel per-run and held in satellite memory only
+ * for the lifetime of the run. `requestId` correlates the reply (a config
+ * can run repeatedly; `runId` is for logging/audit).
+ */
+const RequestRunSecretsMessageSchema = z.object({
+  type: z.literal("request_run_secrets"),
+  /** Correlation id for the reply. */
+  requestId: z.string(),
+  /** The assignment/collector whose declared secretEnv to resolve. */
+  configId: z.string(),
+  collectorId: z.string(),
+  /** Opaque per-run id for audit/logging on the core side. */
+  runId: z.string(),
+});
+
 /**
  * Discriminated union of all messages that a satellite can send to the core.
  */
@@ -83,6 +144,10 @@ export const SatelliteToCoreMessageSchema = z.discriminatedUnion("type", [
   HeartbeatMessageSchema,
   ResultMessageSchema,
   StrategyErrorMessageSchema,
+  ScriptPackageSyncStateMessageSchema,
+  RequestScriptPackageManifestMessageSchema,
+  RequestScriptPackageBlobMessageSchema,
+  RequestRunSecretsMessageSchema,
 ]);
 
 export type SatelliteToCoreMessage = z.infer<
@@ -94,6 +159,18 @@ export type AuthenticateMessage = z.infer<typeof AuthenticateMessageSchema>;
 export type HeartbeatMessage = z.infer<typeof HeartbeatMessageSchema>;
 export type ResultMessage = z.infer<typeof ResultMessageSchema>;
 export type StrategyErrorMessage = z.infer<typeof StrategyErrorMessageSchema>;
+export type ScriptPackageSyncStateMessage = z.infer<
+  typeof ScriptPackageSyncStateMessageSchema
+>;
+export type RequestScriptPackageManifestMessage = z.infer<
+  typeof RequestScriptPackageManifestMessageSchema
+>;
+export type RequestScriptPackageBlobMessage = z.infer<
+  typeof RequestScriptPackageBlobMessageSchema
+>;
+export type RequestRunSecretsMessage = z.infer<
+  typeof RequestRunSecretsMessageSchema
+>;
 
 // =============================================================================
 // CORE → SATELLITE MESSAGES
@@ -103,6 +180,13 @@ const AuthenticatedMessageSchema = z.object({
   type: z.literal("authenticated"),
   satelliteId: z.string(),
   assignments: z.array(SatelliteAssignmentSchema),
+  /**
+   * Desired script-package lockfile hash. Carried alongside assignments as
+   * the durable convergence backstop: a satellite that booted after (or
+   * missed) a `refresh_script_packages` push still converges on connect.
+   * Optional for version-skew safety; null means "no packages installed".
+   */
+  scriptPackagesLockfileHash: z.string().nullable().optional(),
 });
 
 const AuthFailedMessageSchema = z.object({
@@ -113,6 +197,8 @@ const AuthFailedMessageSchema = z.object({
 const ConfigUpdatedMessageSchema = z.object({
   type: z.literal("config_updated"),
   assignments: z.array(SatelliteAssignmentSchema),
+  /** See {@link AuthenticatedMessageSchema.scriptPackagesLockfileHash}. */
+  scriptPackagesLockfileHash: z.string().nullable().optional(),
 });
 
 const ShutdownMessageSchema = z.object({
@@ -120,6 +206,60 @@ const ShutdownMessageSchema = z.object({
   reason: z.string(),
 });
 
+/**
+ * Control push telling the satellite to reconcile its script packages to a
+ * new lockfile hash. Sent by each core instance's `script-packages.changed`
+ * broadcast handler to its currently-connected satellites. Best-effort
+ * liveness; the assignment-carried `scriptPackagesLockfileHash` is the
+ * durable backstop.
+ */
+const RefreshScriptPackagesMessageSchema = z.object({
+  type: z.literal("refresh_script_packages"),
+  lockfileHash: z.string(),
+});
+
+/** One resolved package in a manifest reply. */
+const ManifestEntryWireSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  integrity: z.string(),
+});
+
+/** Core reply to `request_script_package_manifest`. */
+const ScriptPackageManifestMessageSchema = z.object({
+  type: z.literal("script_package_manifest"),
+  lockfileHash: z.string(),
+  entries: z.array(ManifestEntryWireSchema),
+});
+
+/** Core reply to `request_script_package_blob` (base64 compressed bytes). */
+const ScriptPackageBlobMessageSchema = z.object({
+  type: z.literal("script_package_blob"),
+  integrity: z.string(),
+  /** base64-encoded compressed blob bytes, or null if not found. */
+  data: z.string().nullable(),
+});
+
+/**
+ * Core reply to `request_run_secrets`. Carries the resolved env map on
+ * success, or an `error` when a required secret could not be resolved /
+ * the collector was not found. The satellite injects `env` memory-only for
+ * the run and drops it on completion; on `error` it fails the run clearly
+ * rather than running without the secret.
+ *
+ * The env map never persists on the core side and is never written to disk
+ * on the satellite.
+ */
+const RunSecretsMessageSchema = z.object({
+  type: z.literal("run_secrets"),
+  /** Correlates with the originating `request_run_secrets`. */
+  requestId: z.string(),
+  /** Resolved env, present only on success. */
+  env: z.record(z.string(), z.string()).optional(),
+  /** Set when resolution failed; `env` is then absent. */
+  error: z.string().optional(),
+});
+
 /**
  * Discriminated union of all messages that the core can send to a satellite.
  */
@@ -128,6 +268,10 @@ export const CoreToSatelliteMessageSchema = z.discriminatedUnion("type", [
   AuthFailedMessageSchema,
   ConfigUpdatedMessageSchema,
   ShutdownMessageSchema,
+  RefreshScriptPackagesMessageSchema,
+  ScriptPackageManifestMessageSchema,
+  ScriptPackageBlobMessageSchema,
+  RunSecretsMessageSchema,
 ]);
 
 export type CoreToSatelliteMessage = z.infer<
@@ -139,3 +283,13 @@ export type AuthenticatedMessage = z.infer<typeof AuthenticatedMessageSchema>;
 export type AuthFailedMessage = z.infer<typeof AuthFailedMessageSchema>;
 export type ConfigUpdatedMessage = z.infer<typeof ConfigUpdatedMessageSchema>;
 export type ShutdownMessage = z.infer<typeof ShutdownMessageSchema>;
+export type RefreshScriptPackagesMessage = z.infer<
+  typeof RefreshScriptPackagesMessageSchema
+>;
+export type ScriptPackageManifestMessage = z.infer<
+  typeof ScriptPackageManifestMessageSchema
+>;
+export type ScriptPackageBlobMessage = z.infer<
+  typeof ScriptPackageBlobMessageSchema
+>;
+export type RunSecretsMessage = z.infer<typeof RunSecretsMessageSchema>;