@rozenite/storage-plugin 1.13.0 → 2.0.0

package/src/shared/__tests__/entry-preview.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from 'vitest';
+import {
+  MAX_BUFFER_PREVIEW_BYTES,
+  MAX_STRING_PREVIEW_CODE_POINTS,
+  toStorageEntryPreview,
+} from '../entry-preview';
+
+describe('toStorageEntryPreview', () => {
+  it('represents empty and boundary-sized strings completely', () => {
+    expect(
+      toStorageEntryPreview({ key: 'empty', type: 'string', value: '' }),
+    ).toEqual({
+      key: 'empty',
+      type: 'string',
+      preview: '',
+      valueSize: 0,
+      isTruncated: false,
+    });
+
+    const value = 'a'.repeat(MAX_STRING_PREVIEW_CODE_POINTS);
+    expect(
+      toStorageEntryPreview({ key: 'boundary', type: 'string', value }),
+    ).toEqual({
+      key: 'boundary',
+      type: 'string',
+      preview: value,
+      valueSize: MAX_STRING_PREVIEW_CODE_POINTS,
+      isTruncated: false,
+    });
+  });
+
+  it('truncates an oversized string at the fixed code-point boundary', () => {
+    const value = `${'a'.repeat(MAX_STRING_PREVIEW_CODE_POINTS)}z`;
+
+    expect(
+      toStorageEntryPreview({ key: 'long', type: 'string', value }),
+    ).toEqual({
+      key: 'long',
+      type: 'string',
+      preview: 'a'.repeat(MAX_STRING_PREVIEW_CODE_POINTS),
+      valueSize: MAX_STRING_PREVIEW_CODE_POINTS + 1,
+      isTruncated: true,
+    });
+  });
+
+  it('does not split Unicode code points while preserving string length', () => {
+    const value = `${'😀'.repeat(MAX_STRING_PREVIEW_CODE_POINTS)}!`;
+
+    expect(
+      toStorageEntryPreview({ key: 'emoji', type: 'string', value }),
+    ).toEqual({
+      key: 'emoji',
+      type: 'string',
+      preview: '😀'.repeat(MAX_STRING_PREVIEW_CODE_POINTS),
+      valueSize: value.length,
+      isTruncated: true,
+    });
+  });
+
+  it('formats primitive values completely', () => {
+    expect(
+      toStorageEntryPreview({ key: 'count', type: 'number', value: 42 }),
+    ).toEqual({
+      key: 'count',
+      type: 'number',
+      preview: '42',
+      valueSize: 2,
+      isTruncated: false,
+    });
+    expect(
+      toStorageEntryPreview({ key: 'enabled', type: 'boolean', value: false }),
+    ).toEqual({
+      key: 'enabled',
+      type: 'boolean',
+      preview: 'false',
+      valueSize: 5,
+      isTruncated: false,
+    });
+  });
+
+  it('formats empty and boundary-sized buffers as hexadecimal', () => {
+    expect(
+      toStorageEntryPreview({ key: 'empty', type: 'buffer', value: [] }),
+    ).toEqual({
+      key: 'empty',
+      type: 'buffer',
+      preview: '',
+      valueSize: 0,
+      isTruncated: false,
+    });
+
+    const value = new Array(MAX_BUFFER_PREVIEW_BYTES).fill(0xab);
+    expect(
+      toStorageEntryPreview({ key: 'boundary', type: 'buffer', value }),
+    ).toEqual({
+      key: 'boundary',
+      type: 'buffer',
+      preview: new Array(MAX_BUFFER_PREVIEW_BYTES).fill('AB').join(' '),
+      valueSize: MAX_BUFFER_PREVIEW_BYTES,
+      isTruncated: false,
+    });
+  });
+
+  it('truncates oversized buffers at the fixed byte boundary', () => {
+    const value = [...new Array(MAX_BUFFER_PREVIEW_BYTES).fill(0xab), 0xcd];
+
+    expect(
+      toStorageEntryPreview({ key: 'long', type: 'buffer', value }),
+    ).toEqual({
+      key: 'long',
+      type: 'buffer',
+      preview: new Array(MAX_BUFFER_PREVIEW_BYTES).fill('AB').join(' '),
+      valueSize: MAX_BUFFER_PREVIEW_BYTES + 1,
+      isTruncated: true,
+    });
+  });
+});

package/src/shared/__tests__/snapshot.test.ts

@@ -358,4 +358,25 @@ describe('computePreview', () => {
     });
     expect(preview.metadataMismatch).toBe(false);
   });
+
+  it('treats accepted duplicate keys as sequential overwrites', () => {
+    const preview = computePreview(
+      validSnapshot({
+        entries: [
+          { key: 'duplicate', type: 'string', value: 'first' },
+          { key: 'duplicate', type: 'string', value: 'second' },
+        ],
+      }),
+      {
+        target,
+        capabilities: allTypes,
+        entryKeys: new Set(),
+        isBlacklisted: noBlacklist,
+      },
+    );
+
+    expect(preview.newKeys).toEqual(['duplicate']);
+    expect(preview.overwriteKeys).toEqual(['duplicate']);
+    expect(preview.acceptedEntryIndexes).toEqual([0, 1]);
+  });
 });

package/src/shared/agent-tools.ts

@@ -1,5 +1,6 @@
 import {
   defineAgentToolContract,
+  definePaginatedAgentToolContract,
   type AgentToolContract,
 } from '@rozenite/agent-shared';
 
@@ -36,7 +37,6 @@ export type StorageListStoragesItem = {
   storageId: string;
   adapterName: string;
   storageName: string;
-  entryCount: number;
   supportedTypes: StorageEntryType[];
 };
 
@@ -45,17 +45,22 @@ export type StorageListStoragesResult = {
 };
 
 export type StorageListEntriesArgs = StorageSelection & {
-  offset?: number;
   limit?: number;
+  cursor?: string;
+  /** @deprecated Use the opaque cursor returned by a previous page. */
+  offset?: number;
 };
 
 export type StorageListEntriesResult = {
   adapterId: string;
   storageId: string;
   total: number;
-  offset: number;
-  limit: number;
-  keys: string[];
+  items: Array<{ key: string }>;
+  page: {
+    limit: number;
+    hasMore: boolean;
+    nextCursor?: string;
+  };
 };
 
 export type StorageReadEntryArgs = StorageSelection & {
@@ -106,10 +111,10 @@ export const storageToolDefinitions = {
   >({
     name: 'list-storages',
     description:
-      'List all storage adapters and their storage nodes currently available on the device, including supported entry types and entry counts.',
+      'List all storage adapters and their storage nodes currently available on the device, including supported entry types. Entry counts are omitted to avoid enumerating every storage.',
     inputSchema: { type: 'object', properties: {} },
   }),
-  listEntries: defineAgentToolContract<
+  listEntries: definePaginatedAgentToolContract<
     StorageListEntriesArgs,
     StorageListEntriesResult
   >({
@@ -120,16 +125,27 @@ export const storageToolDefinitions = {
       type: 'object',
       properties: {
         ...sharedStorageProperties,
-        offset: {
+        limit: {
           type: 'number',
-          description: 'Pagination offset. Defaults to 0.',
+          description: 'Pagination size. Defaults to 20 and is capped at 100.',
         },
-        limit: {
+        cursor: {
+          type: 'string',
+          description:
+            'Opaque pagination cursor from a previous list-entries call.',
+        },
+        offset: {
           type: 'number',
-          description: 'Pagination size. Defaults to 100.',
+          description:
+            'Deprecated initial pagination offset. Must be a non-negative integer and cannot be combined with cursor.',
         },
       },
     },
+    pagination: {
+      kind: 'cursor',
+      fields: ['key'],
+      defaultFields: ['key'],
+    },
   }),
   readEntry: defineAgentToolContract<
     StorageReadEntryArgs,

package/src/shared/entry-preview.ts

@@ -0,0 +1,59 @@
+import type { StorageEntry, StorageEntryPreview } from './types';
+
+export const MAX_STRING_PREVIEW_CODE_POINTS = 256;
+export const MAX_BUFFER_PREVIEW_BYTES = 16;
+
+const toHexPair = (byte: number): string =>
+  byte.toString(16).toUpperCase().padStart(2, '0');
+
+const truncateString = (
+  value: string,
+): Pick<StorageEntryPreview, 'preview' | 'isTruncated'> => {
+  let preview = '';
+  let codePointCount = 0;
+
+  for (const codePoint of value) {
+    if (codePointCount === MAX_STRING_PREVIEW_CODE_POINTS) {
+      return { preview, isTruncated: true };
+    }
+
+    preview += codePoint;
+    codePointCount += 1;
+  }
+
+  return { preview, isTruncated: false };
+};
+
+export const toStorageEntryPreview = (
+  entry: StorageEntry,
+): StorageEntryPreview => {
+  if (entry.type === 'string') {
+    return {
+      key: entry.key,
+      type: entry.type,
+      ...truncateString(entry.value),
+      // JavaScript strings expose their length in UTF-16 code units.
+      valueSize: entry.value.length,
+    };
+  }
+
+  if (entry.type === 'buffer') {
+    const shownBytes = entry.value.slice(0, MAX_BUFFER_PREVIEW_BYTES);
+    return {
+      key: entry.key,
+      type: entry.type,
+      preview: shownBytes.map(toHexPair).join(' '),
+      valueSize: entry.value.length,
+      isTruncated: entry.value.length > MAX_BUFFER_PREVIEW_BYTES,
+    };
+  }
+
+  const preview = String(entry.value);
+  return {
+    key: entry.key,
+    type: entry.type,
+    preview,
+    valueSize: preview.length,
+    isTruncated: false,
+  };
+};

package/src/shared/messaging.ts

@@ -1,19 +1,10 @@
-import type { StorageCapabilities, StorageEntry, StorageTarget } from './types';
-
-export type SerializedBlacklist = {
-  source: string;
-  flags: string;
-};
-
-export type StorageSnapshotEvent = {
-  type: 'snapshot';
-  target: StorageTarget;
-  adapterName: string;
-  storageName: string;
-  capabilities: StorageCapabilities;
-  blacklist?: SerializedBlacklist;
-  entries: StorageEntry[];
-};
+import type {
+  StorageDescriptor,
+  StorageEntry,
+  StorageEntryPreview,
+  StorageTarget,
+} from './types';
+import type { ImportPreview, StorageSnapshotV1 } from './snapshot';
 
 export type StorageSetEntryEvent = {
   type: 'set-entry';
@@ -27,19 +18,131 @@ export type StorageDeleteEntryEvent = {
   key: string;
 };
 
-export type StorageGetSnapshotEvent = {
-  type: 'get-snapshot';
-  target: StorageTarget | 'all';
+export type StoragePurgeEvent = {
+  type: 'purge-storage';
+  target: StorageTarget;
+};
+
+export type StorageInvalidationOperation =
+  | 'set'
+  | 'delete'
+  | 'import'
+  | 'purge';
+
+export type StorageInvalidatedEvent = {
+  type: 'storage-invalidated';
+  target: StorageTarget;
+  /** Native subscriptions only expose a key, not the operation. */
+  key?: string;
+  operation?: StorageInvalidationOperation;
+};
+
+export type StorageDiscoverStoragesRequestEvent = {
+  type: 'discover-storages';
+  requestId: string;
+};
+
+export type StorageDiscoverStoragesResponseEvent = {
+  type: 'storage-descriptors';
+  requestId: string;
+  storages: StorageDescriptor[];
+};
+
+export type StorageListEntryPreviewsRequestEvent = {
+  type: 'list-entry-previews';
+  requestId: string;
+  target: StorageTarget;
+  search?: string;
+  keySortDirection?: 'ascending' | 'descending';
+  cursor?: string;
+  limit: number;
+};
+
+export type StorageListEntryPreviewsResponseEvent = {
+  type: 'entry-previews';
+  requestId: string;
+  target: StorageTarget;
+  items: StorageEntryPreview[];
+  nextCursor?: string;
+  previousCursor?: string;
+};
+
+export type StorageGetEntryRequestEvent = {
+  type: 'get-entry';
+  requestId: string;
+  target: StorageTarget;
+  key: string;
+};
+
+export type StorageGetEntryResponseEvent = {
+  type: 'entry';
+  requestId: string;
+  target: StorageTarget;
+  entry: StorageEntry;
+};
+
+export type StorageExportSnapshotRequestEvent = {
+  type: 'export-snapshot';
+  requestId: string;
+  target: StorageTarget;
+};
+
+export type StorageExportSnapshotResponseEvent = {
+  type: 'export-snapshot-result';
+  requestId: string;
+  target: StorageTarget;
+  snapshot: StorageSnapshotV1;
+};
+
+export type StorageImportPreviewRequestEvent = {
+  type: 'preview-import';
+  requestId: string;
+  target: StorageTarget;
+  snapshot: StorageSnapshotV1;
+};
+
+export type StorageImportPreviewResponseEvent = {
+  type: 'import-preview';
+  requestId: string;
+  target: StorageTarget;
+  preview: ImportPreview;
+};
+
+export type StorageRequestError = {
+  requestId: string;
+  code:
+    | 'TARGET_NOT_FOUND'
+    | 'ENTRY_NOT_FOUND'
+    | 'INVALID_CURSOR'
+    | 'INVALID_REQUEST'
+    | 'READ_FAILED'
+    | 'WRITE_FAILED';
+  message: string;
+  resetPagination?: boolean;
+};
+
+export type StorageRequestErrorEvent = StorageRequestError & {
+  type: 'storage-request-error';
 };
 
 export type StorageImportEntriesEvent = {
   type: 'import-entries';
+  requestId: string;
   target: StorageTarget;
   entries: StorageEntry[];
 };
 
+export type StorageImportProgressEvent = {
+  type: 'import-progress';
+  requestId: string;
+  target: StorageTarget;
+  written: number;
+  total: number;
+};
+
 export type StorageImportResultEvent = {
   type: 'import-result';
+  requestId: string;
   target: StorageTarget;
   ok: boolean;
   written: number;
@@ -49,11 +152,23 @@ export type StorageImportResultEvent = {
 };
 
 export type StorageEvent =
-  | StorageSnapshotEvent
   | StorageSetEntryEvent
   | StorageDeleteEntryEvent
-  | StorageGetSnapshotEvent
+  | StoragePurgeEvent
+  | StorageInvalidatedEvent
+  | StorageDiscoverStoragesRequestEvent
+  | StorageDiscoverStoragesResponseEvent
+  | StorageListEntryPreviewsRequestEvent
+  | StorageListEntryPreviewsResponseEvent
+  | StorageGetEntryRequestEvent
+  | StorageGetEntryResponseEvent
+  | StorageExportSnapshotRequestEvent
+  | StorageExportSnapshotResponseEvent
+  | StorageImportPreviewRequestEvent
+  | StorageImportPreviewResponseEvent
+  | StorageRequestErrorEvent
   | StorageImportEntriesEvent
+  | StorageImportProgressEvent
   | StorageImportResultEvent;
 
 export type StorageEventMap = {

package/src/shared/snapshot.ts

@@ -229,6 +229,7 @@ export type ImportPreview = {
   overwriteKeys: string[];
   skippedKeys: { key: string; reason: 'blacklist' }[];
   unsupportedTypes: { key: string; type: StorageEntryType }[];
+  acceptedEntryIndexes: number[];
   metadataMismatch: boolean;
 };
 
@@ -245,8 +246,9 @@ export const computePreview = (
   const overwriteKeys: string[] = [];
   const skippedKeys: { key: string; reason: 'blacklist' }[] = [];
   const unsupportedTypes: { key: string; type: StorageEntryType }[] = [];
+  const acceptedEntryIndexes: number[] = [];
 
-  for (const entry of snapshot.entries) {
+  for (const [index, entry] of snapshot.entries.entries()) {
     if (!supportsType(current.capabilities, entry.type)) {
       unsupportedTypes.push({ key: entry.key, type: entry.type });
       continue;
@@ -260,6 +262,10 @@ export const computePreview = (
     } else {
       newKeys.push(entry.key);
     }
+    acceptedEntryIndexes.push(index);
+    // Duplicate keys are applied in source order, so every accepted duplicate
+    // after the first overwrites the value that preceded it in this import.
+    current.entryKeys.add(entry.key);
   }
 
   const metadataMismatch =
@@ -271,6 +277,7 @@ export const computePreview = (
     overwriteKeys,
     skippedKeys,
     unsupportedTypes,
+    acceptedEntryIndexes,
     metadataMismatch,
   };
 };

package/src/shared/types.ts

@@ -7,10 +7,27 @@ export type StorageEntry =
 export type StorageEntryType = StorageEntry['type'];
 export type StorageEntryValue = StorageEntry['value'];
 
+export type StorageEntryPreview = {
+  key: string;
+  type: StorageEntryType;
+  preview: string;
+  valueSize: number;
+  isTruncated: boolean;
+};
+
 export type StorageCapabilities = {
   supportedTypes: StorageEntryType[];
 };
 
+export type StorageDescriptor = {
+  target: StorageTarget;
+  adapterName: string;
+  storageName: string;
+  entryCount: number;
+  capabilities: StorageCapabilities;
+  supportsSubscriptions: boolean;
+};
+
 export type StorageSubscription = { remove: () => void };
 
 export type SyncStorage = {
@@ -19,6 +36,7 @@ export type SyncStorage = {
   get: (key: string) => StorageEntry | undefined;
   set: (entry: StorageEntry) => void;
   delete: (key: string) => void;
+  clear: () => void;
   subscribe?: (callback: (key: string) => void) => StorageSubscription;
 };
 
@@ -28,6 +46,7 @@ export type AsyncStorage = {
   get: (key: string) => Promise<StorageEntry | undefined>;
   set: (entry: StorageEntry) => Promise<void>;
   delete: (key: string) => Promise<void>;
+  clear: () => Promise<void>;
   subscribe?: (callback: (key: string) => void) => StorageSubscription;
 };
 
@@ -63,5 +82,5 @@ export const getStorageViewId = ({ adapterId, storageId }: StorageTarget) =>
 
 export const supportsType = (
   capabilities: StorageCapabilities,
-  type: StorageEntryType
+  type: StorageEntryType,
 ) => capabilities.supportedTypes.includes(type);

package/src/ui/__tests__/binary-value-editor-state.test.ts

@@ -176,6 +176,19 @@ describe('reduce: switch-mode', () => {
   });
 });
 
+describe('reduce: replace-bytes', () => {
+  it('formats fetched bytes after the editor has had a chance to paint', () => {
+    expect(
+      reduce(hexState(), { type: 'replace-bytes', bytes: [0x48, 0x69] }),
+    ).toEqual({
+      mode: 'hex',
+      text: '48 69',
+      bytes: [0x48, 0x69],
+      error: null,
+    });
+  });
+});
+
 describe('validate', () => {
   it('passes when bytes are valid and non-empty', () => {
     const state = reduce(hexState(), { type: 'set-text', text: '89 50' });

package/src/ui/__tests__/binary.test.ts

@@ -5,7 +5,9 @@ import {
   bytesToBase64,
   bytesToGroupedHex,
   bytesToHexdump,
+  compactAsciiPreview,
   compactBufferPreview,
+  formatHexdumpRow,
   hexInputToBytes,
 } from '../binary';
 
@@ -80,6 +82,16 @@ describe('bytesToHexdump', () => {
   });
 });
 
+describe('formatHexdumpRow', () => {
+  it('formats one requested row without requiring a complete hexdump', () => {
+    expect(formatHexdumpRow(new Array(32).fill(0x41), 16)).toEqual({
+      offset: '00000010',
+      hex: '41 41 41 41 41 41 41 41  41 41 41 41 41 41 41 41',
+      ascii: 'AAAAAAAAAAAAAAAA',
+    });
+  });
+});
+
 describe('bytesToAsciiPreview', () => {
   it('maps printable bytes to characters', () => {
     expect(bytesToAsciiPreview([0x48, 0x69])).toBe('Hi');
@@ -94,6 +106,12 @@ describe('bytesToAsciiPreview', () => {
   });
 });
 
+describe('compactAsciiPreview', () => {
+  it('only converts the visible prefix of a large buffer', () => {
+    expect(compactAsciiPreview(new Array(128).fill(0x41), 4)).toBe('AAAA…');
+  });
+});
+
 describe('bytesToBase64 / base64ToBytes round-trip', () => {
   it('encodes simple ASCII to base64 and back', () => {
     const bytes = [0x48, 0x65, 0x6c, 0x6c, 0x6f]; // "Hello"

package/src/ui/__tests__/large-value-viewer-state.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { TEXT_CHUNK_SIZE, textRowRanges } from '../large-value-viewer-state';
+
+describe('textRowRanges', () => {
+  it('indexes chunks without splitting a pathological single line', () => {
+    const value = 'x'.repeat(TEXT_CHUNK_SIZE * 2 + 7);
+
+    expect(textRowRanges(value)).toEqual([
+      [0, TEXT_CHUNK_SIZE],
+      [TEXT_CHUNK_SIZE, TEXT_CHUNK_SIZE * 2],
+      [TEXT_CHUNK_SIZE * 2, value.length],
+    ]);
+  });
+
+  it('keeps newline boundaries in their displayed row', () => {
+    expect(textRowRanges('first\nsecond')).toEqual([
+      [0, 6],
+      [6, 12],
+    ]);
+  });
+});