@frockbot/plugin-computer 0.2.2 → 0.2.4

package/src/protocol.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ComputerProtocolDecodeError,
+  decodeComputerProjectionV1,
+  type ComputerProgressViewV1,
+  type ComputerProjectionV1,
+} from "./protocol.js";
+
+const projection: ComputerProjectionV1 & { progress: ComputerProgressViewV1 } =
+  {
+    version: 1,
+    botId: "scout",
+    providerLabel: "Fake Computer",
+    phase: "provisioning",
+    message: "Starting the desktop…",
+    progress: {
+      version: 1,
+      kind: "connect",
+      startedAt: "2026-09-03T00:00:00.000Z",
+      updatedAt: "2026-09-03T00:00:02.000Z",
+      index: 2,
+      total: 3,
+      steps: [
+        {
+          version: 1,
+          id: "waking",
+          label: "Waking the Computer",
+          status: "complete",
+        },
+        {
+          version: 1,
+          id: "starting-desktop",
+          label: "Starting the desktop",
+          status: "active",
+        },
+        {
+          version: 1,
+          id: "minting-viewer",
+          label: "Minting the viewer",
+          status: "pending",
+        },
+      ],
+    },
+    screenshots: [],
+  };
+
+describe("Computer projection progress", () => {
+  test("decodes the exact ordered V1 progress shape", () => {
+    expect(decodeComputerProjectionV1(projection).progress).toEqual(
+      projection.progress,
+    );
+  });
+
+  test("refuses malformed or extended progress at the client seam", () => {
+    expect(() =>
+      decodeComputerProjectionV1({
+        ...projection,
+        progress: {
+          ...projection.progress,
+          secret: "must not cross",
+        },
+      }),
+    ).toThrow(ComputerProtocolDecodeError);
+    expect(() =>
+      decodeComputerProjectionV1({
+        ...projection,
+        progress: {
+          ...projection.progress,
+          steps: projection.progress.steps.map((step) => ({
+            ...step,
+            status: "working",
+          })),
+        },
+      }),
+    ).toThrow(ComputerProtocolDecodeError);
+  });
+});

package/src/protocol.ts

@@ -61,6 +61,26 @@ export interface ComputerDoctorViewV1 {
   checks: ComputerDoctorCheckViewV1[];
 }
 
+export type ComputerProgressStepStatusV1 = "pending" | "active" | "complete";
+
+export interface ComputerProgressStepViewV1 {
+  version: 1;
+  id: string;
+  label: string;
+  status: ComputerProgressStepStatusV1;
+}
+
+/** Durable progress projected from the Bot authority; it contains no secrets. */
+export interface ComputerProgressViewV1 {
+  version: 1;
+  kind: "connect" | "update";
+  startedAt: string;
+  updatedAt: string;
+  index: number;
+  total: number;
+  steps: ComputerProgressStepViewV1[];
+}
+
 export const COMPUTER_PHASES = [
   "unconfigured",
   "idle",
@@ -92,6 +112,7 @@ export interface ComputerProjectionV1 {
   providerLabel: string;
   phase: ComputerPhase;
   message: string;
+  progress?: ComputerProgressViewV1;
   viewerSession?: ComputerViewerSessionViewV1;
   controlLease?: ComputerControlLeaseViewV1;
   screenshots: ComputerScreenshotViewV1[];
@@ -176,6 +197,95 @@ function phase(value: unknown): ComputerPhase {
   return decoded;
 }
 
+function boundedInteger(
+  value: unknown,
+  minimum: number,
+  maximum: number,
+  label: string,
+): number {
+  if (
+    typeof value !== "number" ||
+    !Number.isSafeInteger(value) ||
+    value < minimum ||
+    value > maximum
+  ) {
+    throw new ComputerProtocolDecodeError(`${label} is invalid`);
+  }
+  return value;
+}
+
+function decodeProgressStepV1(value: unknown): ComputerProgressStepViewV1 {
+  const candidate = record(value, "Computer progress step");
+  exactKeys(
+    candidate,
+    ["version", "id", "label", "status"],
+    [],
+    "Computer progress step",
+  );
+  if (
+    candidate.version !== 1 ||
+    (candidate.status !== "pending" &&
+      candidate.status !== "active" &&
+      candidate.status !== "complete")
+  ) {
+    throw new ComputerProtocolDecodeError("Computer progress step is invalid");
+  }
+  return {
+    version: 1,
+    id: text(candidate.id, "Computer progress step id"),
+    label: text(candidate.label, "Computer progress step label"),
+    status: candidate.status,
+  };
+}
+
+export function decodeComputerProgressViewV1(
+  value: unknown,
+): ComputerProgressViewV1 {
+  const candidate = record(value, "Computer progress");
+  exactKeys(
+    candidate,
+    ["version", "kind", "startedAt", "updatedAt", "index", "total", "steps"],
+    [],
+    "Computer progress",
+  );
+  if (
+    candidate.version !== 1 ||
+    (candidate.kind !== "connect" && candidate.kind !== "update") ||
+    !Array.isArray(candidate.steps) ||
+    candidate.steps.length === 0 ||
+    candidate.steps.length > 20
+  ) {
+    throw new ComputerProtocolDecodeError("Computer progress is invalid");
+  }
+  const total = boundedInteger(
+    candidate.total,
+    1,
+    1_000,
+    "Computer progress total",
+  );
+  const index = boundedInteger(
+    candidate.index,
+    0,
+    total,
+    "Computer progress index",
+  );
+  const steps = candidate.steps.map(decodeProgressStepV1);
+  if (steps.filter((step) => step.status === "active").length > 1) {
+    throw new ComputerProtocolDecodeError(
+      "Computer progress has multiple active steps",
+    );
+  }
+  return {
+    version: 1,
+    kind: candidate.kind,
+    startedAt: timestamp(candidate.startedAt, "Computer progress startedAt"),
+    updatedAt: timestamp(candidate.updatedAt, "Computer progress updatedAt"),
+    index,
+    total,
+    steps,
+  };
+}
+
 export function decodeComputerCommandV1(value: unknown): ComputerCommandV1 {
   const candidate = record(value, "Computer command");
   exactKeys(
@@ -328,7 +438,7 @@ export function decodeComputerProjectionV1(
   exactKeys(
     candidate,
     ["version", "botId", "providerLabel", "phase", "message", "screenshots"],
-    ["viewerSession", "controlLease", "doctor"],
+    ["viewerSession", "controlLease", "doctor", "progress"],
     "Computer projection",
   );
   if (candidate.version !== 1 || !Array.isArray(candidate.screenshots)) {
@@ -343,6 +453,9 @@ export function decodeComputerProjectionV1(
     ),
     phase: phase(candidate.phase),
     message: text(candidate.message, "Computer projection message"),
+    ...(candidate.progress === undefined
+      ? {}
+      : { progress: decodeComputerProgressViewV1(candidate.progress) }),
     ...(candidate.viewerSession === undefined
       ? {}
       : { viewerSession: decodeViewerSessionV1(candidate.viewerSession) }),

package/src/shared.ts

@@ -2,6 +2,7 @@ import type { InjectionKey, Ref } from "vue";
 import type {
   ComputerDoctorViewV1,
   ComputerPhase,
+  ComputerProgressViewV1,
   ComputerScreenshotViewV1,
 } from "./protocol.js";
 
@@ -30,6 +31,7 @@ export interface ComputerState {
   botId: string;
   providerLabel: string;
   message: string;
+  progress?: ComputerProgressViewV1;
   viewerUrl?: string;
   /** Whether the one live viewer is open over the hosted shell. */
   expanded: boolean;