feat(desktop): clarify inspector readability path

Co-Authored-By: Paperclip <noreply@paperclip.ing>
2026-03-31 08:23:13 +00:00
parent bf6f8bc0bf
commit 969744733f
8 changed files with 679 additions and 27 deletions
--- a/apps/desktop/src/lib/inspector-readability.test.ts
+++ b/apps/desktop/src/lib/inspector-readability.test.ts
@@ -0,0 +1,183 @@
+import { describe, expect, it } from "vitest";
+import { buildInspectorReadabilitySummary } from "./inspector-readability";
+
+describe("inspector readability summary", () => {
+  it("guides the operator when no key is selected", () => {
+    expect(
+      buildInspectorReadabilitySummary({
+        databaseLabel: "db4",
+        runtimeMode: "live",
+        selectedKey: null,
+        record: null,
+        isLoading: false,
+        isEditable: false,
+        ttlWriteSupported: false,
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        status: "awaiting selection",
+        surfaceTitle: "No key selected",
+        actionTitle: "Next step",
+        facts: expect.arrayContaining([
+          { label: "Scope", value: "db4" },
+          { label: "Type", value: "unknown" },
+        ]),
+      }),
+    );
+  });
+
+  it("describes editable live strings with explicit write semantics", () => {
+    expect(
+      buildInspectorReadabilitySummary({
+        databaseLabel: "db0",
+        runtimeMode: "live",
+        selectedKey: {
+          name: "cache:homepage",
+          type: "string",
+          ttl: "48s",
+        },
+        record: {
+          metadata: {
+            key_type: "string",
+            ttl: { kind: "expires_in_millis", value: 48_000 },
+          },
+          data: {
+            kind: "string",
+            value: { kind: "string", value: "payload" },
+          },
+        },
+        isLoading: false,
+        isEditable: true,
+        ttlWriteSupported: true,
+      }),
+    ).toEqual({
+      status: "editable string",
+      surfaceTitle: "String value",
+      surfaceDescription:
+        "The full live string payload is loaded in the inspector. Saving replaces the entire string value and preserves the active TTL boundary.",
+      actionTitle: "Operator path",
+      actionDescription:
+        "Review the full payload, make bounded edits, and use Save string value when you are ready to replace the current value.",
+      facts: [
+        { label: "Scope", value: "db0" },
+        { label: "Type", value: "string" },
+        { label: "TTL state", value: "48s" },
+        { label: "Value shape", value: "string payload" },
+        { label: "Write path", value: "replace full string" },
+        { label: "TTL control", value: "available" },
+      ],
+    });
+  });
+
+  it("describes structured live values as readable inspection-only surfaces", () => {
+    expect(
+      buildInspectorReadabilitySummary({
+        databaseLabel: "db0",
+        runtimeMode: "live",
+        selectedKey: {
+          name: "session:42",
+          type: "hash",
+          ttl: "13m",
+        },
+        record: {
+          metadata: {
+            key_type: "hash",
+            ttl: { kind: "expires_in_millis", value: 780_000 },
+          },
+          data: {
+            kind: "hash",
+            entries: [
+              {
+                field: { kind: "string", value: "region" },
+                value: { kind: "string", value: "eu-west-1" },
+              },
+              {
+                field: { kind: "string", value: "role" },
+                value: { kind: "string", value: "editor" },
+              },
+            ],
+          },
+        },
+        isLoading: false,
+        isEditable: false,
+        ttlWriteSupported: true,
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        status: "structured read only",
+        surfaceTitle: "Hash fields",
+        facts: [
+          { label: "Scope", value: "db0" },
+          { label: "Type", value: "hash" },
+          { label: "TTL state", value: "13m" },
+          { label: "Value shape", value: "2 fields" },
+          { label: "Write path", value: "inspection only" },
+          { label: "TTL control", value: "available" },
+        ],
+      }),
+    );
+  });
+
+  it("keeps demo mode explicit so shell review is not confused with live evidence", () => {
+    expect(
+      buildInspectorReadabilitySummary({
+        databaseLabel: "db0",
+        runtimeMode: "demo",
+        selectedKey: {
+          name: "cache:homepage",
+          type: "string",
+          ttl: "48s",
+        },
+        record: null,
+        isLoading: false,
+        isEditable: true,
+        ttlWriteSupported: true,
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        status: "demo editable",
+        surfaceTitle: "String value",
+        facts: expect.arrayContaining([
+          { label: "Write path", value: "session-local string save" },
+          { label: "TTL control", value: "available" },
+        ]),
+      }),
+    );
+  });
+
+  it("makes stale browse-to-read gaps explicit when the key disappears", () => {
+    expect(
+      buildInspectorReadabilitySummary({
+        databaseLabel: "db2",
+        runtimeMode: "live",
+        selectedKey: {
+          name: "jobs:failed",
+          type: "list",
+          ttl: "persistent",
+        },
+        record: {
+          metadata: {
+            key_type: "list",
+            ttl: { kind: "missing" },
+          },
+          data: {
+            kind: "missing",
+          },
+        },
+        isLoading: false,
+        isEditable: false,
+        ttlWriteSupported: false,
+      }),
+    ).toEqual(
+      expect.objectContaining({
+        status: "missing key",
+        surfaceTitle: "Key disappeared after browse",
+        facts: expect.arrayContaining([
+          { label: "Scope", value: "db2" },
+          { label: "TTL state", value: "missing" },
+          { label: "Write path", value: "not available" },
+        ]),
+      }),
+    );
+  });
+});