@aloud/runner 0.3.0 → 0.3.2

package/src/version.ts

@@ -10,7 +10,62 @@
  * package.json beside it to read, and importing one into the source trips the composite build's
  * rootDir. `version.test.ts` asserts this matches, so the drift this invites cannot survive CI.
  */
-export const RUNNER_VERSION = "0.3.0";
+export const RUNNER_VERSION = "0.3.2";
 
 /** The header the server reads it from. */
 export const RUNNER_VERSION_HEADER = "x-aloud-runner-version";
+
+export interface RunnerVersionPolicy {
+  /** The oldest release that may claim new work. */
+  minimum: string;
+  /** The exact official release a start should move to when it can. */
+  recommended: string;
+}
+
+/** Strict because a server response eventually becomes part of an npm package specifier. */
+function versionParts(value: string): [number, number, number] | null {
+  const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
+  if (!match) return null;
+  const parts = [Number(match[1]), Number(match[2]), Number(match[3])] as [number, number, number];
+  return parts.every(Number.isSafeInteger) ? parts : null;
+}
+
+/** Numeric comparison, so 0.10.0 is newer than 0.9.9 rather than lexicographically smaller. */
+export function compareRunnerVersions(left: string, right: string): number | null {
+  const a = versionParts(left);
+  const b = versionParts(right);
+  if (!a || !b) return null;
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index]! > b[index]!) return 1;
+    if (a[index]! < b[index]!) return -1;
+  }
+  return 0;
+}
+
+/** Parses only a coherent policy. A bad control-plane response never becomes an install command. */
+export function runnerVersionPolicyFrom(value: unknown): RunnerVersionPolicy | null {
+  if (!value || typeof value !== "object") return null;
+  const policy = value as { minimum?: unknown; recommended?: unknown };
+  if (typeof policy.minimum !== "string" || typeof policy.recommended !== "string") return null;
+  const order = compareRunnerVersions(policy.recommended, policy.minimum);
+  if (order === null || order < 0) return null;
+  return { minimum: policy.minimum, recommended: policy.recommended };
+}
+
+export interface RunnerUpdate {
+  target: string;
+  /** Required means the installed release cannot claim work if updating fails. */
+  required: boolean;
+}
+
+/** What this installed runner should do with one valid server policy. Never chooses a downgrade. */
+export function runnerUpdateFor(
+  policy: RunnerVersionPolicy,
+  current: string = RUNNER_VERSION,
+): RunnerUpdate | null {
+  const recommendedOrder = compareRunnerVersions(policy.recommended, current);
+  const minimumOrder = compareRunnerVersions(policy.minimum, current);
+  if (recommendedOrder === null || minimumOrder === null) return null;
+  if (recommendedOrder <= 0) return null;
+  return { target: policy.recommended, required: minimumOrder > 0 };
+}