@rozenite/storage-plugin 1.13.0 → 2.1.0

package/src/shared/agent-tools.ts

@@ -1,5 +1,6 @@
 import {
   defineAgentToolContract,
+  definePaginatedAgentToolContract,
   type AgentToolContract,
 } from '@rozenite/agent-shared';
 
@@ -10,8 +11,7 @@ type StorageSelection = Partial<StorageTarget>;
 const sharedStorageProperties = {
   adapterId: {
     type: 'string',
-    description:
-      'Storage adapter ID. Required when multiple adapters are configured.',
+    description: 'Storage adapter ID. Required when multiple adapters are configured.',
   },
   storageId: {
     type: 'string',
@@ -36,7 +36,6 @@ export type StorageListStoragesItem = {
   storageId: string;
   adapterName: string;
   storageName: string;
-  entryCount: number;
   supportedTypes: StorageEntryType[];
 };
 
@@ -45,17 +44,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 & {
@@ -100,19 +104,13 @@ export type StorageRemoveEntryResult = {
 };
 
 export const storageToolDefinitions = {
-  listStorages: defineAgentToolContract<
-    StorageListStoragesArgs,
-    StorageListStoragesResult
-  >({
+  listStorages: defineAgentToolContract<StorageListStoragesArgs, StorageListStoragesResult>({
     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<
-    StorageListEntriesArgs,
-    StorageListEntriesResult
-  >({
+  listEntries: definePaginatedAgentToolContract<StorageListEntriesArgs, StorageListEntriesResult>({
     name: 'list-entries',
     description:
       'List keys in a storage. This call intentionally does not return entry values to keep responses token-efficient.',
@@ -120,21 +118,28 @@ 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,
-    StorageReadEntryResult
-  >({
+  readEntry: defineAgentToolContract<StorageReadEntryArgs, StorageReadEntryResult>({
     name: 'read-entry',
     description: 'Read a single storage entry value by key.',
     inputSchema: {
@@ -146,10 +151,7 @@ export const storageToolDefinitions = {
       required: ['key'],
     },
   }),
-  createEntry: defineAgentToolContract<
-    StorageCreateEntryArgs,
-    StorageCreateEntryResult
-  >({
+  createEntry: defineAgentToolContract<StorageCreateEntryArgs, StorageCreateEntryResult>({
     name: 'create-entry',
     description: 'Create a new storage entry. Fails if the key already exists.',
     inputSchema: {
@@ -170,13 +172,9 @@ export const storageToolDefinitions = {
       required: ['key', 'type', 'value'],
     },
   }),
-  editEntry: defineAgentToolContract<
-    StorageEditEntryArgs,
-    StorageEditEntryResult
-  >({
+  editEntry: defineAgentToolContract<StorageEditEntryArgs, StorageEditEntryResult>({
     name: 'edit-entry',
-    description:
-      'Edit an existing storage entry. Fails if the key does not exist.',
+    description: 'Edit an existing storage entry. Fails if the key does not exist.',
     inputSchema: {
       type: 'object',
       properties: {
@@ -195,10 +193,7 @@ export const storageToolDefinitions = {
       required: ['key', 'type', 'value'],
     },
   }),
-  removeEntry: defineAgentToolContract<
-    StorageRemoveEntryArgs,
-    StorageRemoveEntryResult
-  >({
+  removeEntry: defineAgentToolContract<StorageRemoveEntryArgs, StorageRemoveEntryResult>({
     name: 'remove-entry',
     description: 'Remove a storage entry by key.',
     inputSchema: {

package/src/shared/entry-preview.ts

@@ -0,0 +1,54 @@
+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,5 @@
-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 +13,139 @@ 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;
+  /** Updated entry count for the storage after the invalidation. */
+  entryCount: number;
+};
+
+/**
+ * Announced by the device once it is listening for panel requests. The panel is
+ * recreated on every app reload and asks for storages immediately, which can
+ * land before the app's React tree has mounted the plugin; this lets the panel
+ * ask again instead of waiting forever on a dropped request.
+ */
+export type StorageDeviceReadyEvent = {
+  type: 'device-ready';
+};
+
+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 +155,24 @@ export type StorageImportResultEvent = {
 };
 
 export type StorageEvent =
-  | StorageSnapshotEvent
   | StorageSetEntryEvent
   | StorageDeleteEntryEvent
-  | StorageGetSnapshotEvent
+  | StoragePurgeEvent
+  | StorageInvalidatedEvent
+  | StorageDeviceReadyEvent
+  | StorageDiscoverStoragesRequestEvent
+  | StorageDiscoverStoragesResponseEvent
+  | StorageListEntryPreviewsRequestEvent
+  | StorageListEntryPreviewsResponseEvent
+  | StorageGetEntryRequestEvent
+  | StorageGetEntryResponseEvent
+  | StorageExportSnapshotRequestEvent
+  | StorageExportSnapshotResponseEvent
+  | StorageImportPreviewRequestEvent
+  | StorageImportPreviewResponseEvent
+  | StorageRequestErrorEvent
   | StorageImportEntriesEvent
+  | StorageImportProgressEvent
   | StorageImportResultEvent;
 
 export type StorageEventMap = {

package/src/shared/snapshot.ts

@@ -48,10 +48,7 @@ const describe = (value: unknown): string => {
 const isPlainObject = (value: unknown): value is Record<string, unknown> =>
   typeof value === 'object' && value !== null && !Array.isArray(value);
 
-const expectObject = (
-  value: unknown,
-  path: string,
-): Record<string, unknown> => {
+const expectObject = (value: unknown, path: string): Record<string, unknown> => {
   if (!isPlainObject(value)) {
     throw new ParseException(path, `Expected object, got ${describe(value)}`);
   }
@@ -73,10 +70,7 @@ const expectArray = (value: unknown, path: string): unknown[] => {
 };
 
 const expectEntryType = (value: unknown, path: string): StorageEntryType => {
-  if (
-    typeof value !== 'string' ||
-    !DEFAULT_SUPPORTED_TYPES.includes(value as StorageEntryType)
-  ) {
+  if (typeof value !== 'string' || !DEFAULT_SUPPORTED_TYPES.includes(value as StorageEntryType)) {
     throw new ParseException(
       path,
       `Expected one of ${DEFAULT_SUPPORTED_TYPES.join(', ')}, got ${describe(value)}`,
@@ -151,12 +145,7 @@ const parseEntry = (raw: unknown, path: string): StorageEntry => {
         );
       }
       const bytes = value.map((byte, index) => {
-        if (
-          typeof byte !== 'number' ||
-          !Number.isInteger(byte) ||
-          byte < 0 ||
-          byte > 255
-        ) {
+        if (typeof byte !== 'number' || !Number.isInteger(byte) || byte < 0 || byte > 255) {
           throw new ParseException(
             `${valuePath}[${index}]`,
             `Expected uint8 (integer 0-255), got ${describe(byte)}`,
@@ -183,9 +172,7 @@ export const parseSnapshot = (raw: unknown): ParseResult => {
     const createdAt = expectString(root.createdAt, 'createdAt');
     const storage = parseStorageMeta(root.storage);
     const rawEntries = expectArray(root.entries, 'entries');
-    const entries = rawEntries.map((entry, index) =>
-      parseEntry(entry, `entries[${index}]`),
-    );
+    const entries = rawEntries.map((entry, index) => parseEntry(entry, `entries[${index}]`));
     return {
       ok: true,
       snapshot: {
@@ -229,6 +216,7 @@ export type ImportPreview = {
   overwriteKeys: string[];
   skippedKeys: { key: string; reason: 'blacklist' }[];
   unsupportedTypes: { key: string; type: StorageEntryType }[];
+  acceptedEntryIndexes: number[];
   metadataMismatch: boolean;
 };
 
@@ -245,8 +233,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 +249,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 +264,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;
 };
 
@@ -61,7 +80,5 @@ export const DEFAULT_SUPPORTED_TYPES: StorageEntryType[] = [
 export const getStorageViewId = ({ adapterId, storageId }: StorageTarget) =>
   `${adapterId}:${storageId}`;
 
-export const supportsType = (
-  capabilities: StorageCapabilities,
-  type: StorageEntryType
-) => capabilities.supportedTypes.includes(type);
+export const supportsType = (capabilities: StorageCapabilities, type: StorageEntryType) =>
+  capabilities.supportedTypes.includes(type);

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

@@ -1,10 +1,5 @@
 import { describe, expect, it } from 'vitest';
-import {
-  initialState,
-  reduce,
-  validate,
-  type EditorState,
-} from '../binary-value-editor-state';
+import { initialState, reduce, validate, type EditorState } from '../binary-value-editor-state';
 
 const hexState = (bytes?: number[]): EditorState =>
   initialState({ initialBytes: bytes, mode: 'hex' });
@@ -29,9 +24,7 @@ describe('initialState', () => {
   });
 
   it('encodes initial bytes as base64 when mode is base64', () => {
-    expect(
-      initialState({ initialBytes: [0x48, 0x69], mode: 'base64' }),
-    ).toEqual({
+    expect(initialState({ initialBytes: [0x48, 0x69], mode: 'base64' })).toEqual({
       mode: 'base64',
       text: 'SGk=',
       bytes: [0x48, 0x69],
@@ -101,13 +94,12 @@ describe('reduce: set-text', () => {
 
 describe('reduce: normalize-paste', () => {
   it('rewrites pasted hexdump into canonical grouped hex', () => {
-    const pasted =
-      '00000000  89 50 4E 47 0D 0A 1A 0A  00 00 00 0D 49 48 44 52  |.PNG........IHDR|';
+    const pasted = '00000000  89 50 4E 47 0D 0A 1A 0A  00 00 00 0D 49 48 44 52  |.PNG........IHDR|';
     const next = reduce(hexState(), { type: 'normalize-paste', text: pasted });
     expect(next.text).toBe('89 50 4E 47 0D 0A 1A 0A  00 00 00 0D 49 48 44 52');
     expect(next.bytes).toEqual([
-      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d,
-      0x49, 0x48, 0x44, 0x52,
+      0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44,
+      0x52,
     ]);
     expect(next.error).toBeNull();
   });
@@ -176,6 +168,17 @@ 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' });