@rozenite/storage-plugin 1.13.0 → 2.1.0

package/src/react-native/useStorageAgentTools.ts

@@ -1,16 +1,19 @@
-import { useCallback } from 'react';
 import { useRozenitePluginAgentTool } from '@rozenite/agent-bridge';
+import { DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT } from '@rozenite/agent-shared';
 import {
   STORAGE_AGENT_PLUGIN_ID,
   storageToolDefinitions,
+  type StorageListEntriesArgs,
 } from '../shared/agent-tools';
-import type { StorageEntry, StorageEntryType, StorageEntryValue } from '../shared/types';
+import type {
+  StorageEntry,
+  StorageEntryType,
+  StorageEntryValue,
+  StorageTarget,
+} from '../shared/types';
 import type { StorageView } from './storage-view';
 
-const parseValueForType = (
-  type: StorageEntryType,
-  value: unknown
-): StorageEntryValue => {
+const parseValueForType = (type: StorageEntryType, value: unknown): StorageEntryValue => {
   if (type === 'string') {
     if (typeof value !== 'string') {
       throw new Error('Expected string value for type=string');
@@ -39,118 +42,220 @@ const parseValueForType = (
   return value as number[];
 };
 
-const formatViewRef = (view: StorageView) =>
-  `${view.target.adapterId}/${view.target.storageId}`;
+const formatViewRef = (view: StorageView) => `${view.target.adapterId}/${view.target.storageId}`;
 
-export const useStorageAgentTools = (views: StorageView[]) => {
-  const resolveStorage = useCallback(
-    (adapterId?: string, storageId?: string) => {
-      if (views.length === 0) {
-        throw new Error('No storages are registered.');
-      }
+const isSameTarget = (left: StorageTarget, right: StorageTarget) =>
+  left.adapterId === right.adapterId && left.storageId === right.storageId;
 
-      if (adapterId !== undefined || storageId !== undefined) {
-        const selected = views.find(
-          (view) =>
-            (adapterId === undefined || view.target.adapterId === adapterId) &&
-            (storageId === undefined || view.target.storageId === storageId)
-        );
+type ListEntriesCursor = {
+  version: 1;
+  target: StorageTarget;
+  offset: number;
+};
 
-        if (!selected) {
-          const qualifier = [
-            adapterId && `adapterId="${adapterId}"`,
-            storageId && `storageId="${storageId}"`,
-          ]
-            .filter(Boolean)
-            .join(', ');
-          throw new Error(
-            `No storage matched ${qualifier}. Available: ${views.map(formatViewRef).join(', ')}`
-          );
-        }
-
-        return selected;
-      }
+const encodeCursor = (cursor: ListEntriesCursor) =>
+  btoa(encodeURIComponent(JSON.stringify(cursor)));
 
-      if (views.length > 1) {
-        throw new Error(
-          `Multiple storages detected. Provide adapterId and/or storageId. Available: ${views.map(formatViewRef).join(', ')}`
-        );
-      }
+const decodeCursor = (value: string): ListEntriesCursor => {
+  try {
+    const cursor: unknown = JSON.parse(decodeURIComponent(atob(value)));
+    if (
+      typeof cursor !== 'object' ||
+      cursor == null ||
+      Array.isArray(cursor) ||
+      (cursor as { version?: unknown }).version !== 1 ||
+      typeof (cursor as { target?: { adapterId?: unknown } }).target?.adapterId !== 'string' ||
+      typeof (cursor as { target?: { storageId?: unknown } }).target?.storageId !== 'string' ||
+      !Number.isSafeInteger((cursor as { offset?: unknown }).offset) ||
+      (cursor as { offset: number }).offset < 0
+    ) {
+      throw new Error('Invalid cursor');
+    }
+
+    return cursor as ListEntriesCursor;
+  } catch {
+    throw new Error(
+      'Invalid cursor. Run list-entries again without a cursor to restart pagination.',
+    );
+  }
+};
+
+const sanitizeLimit = (limit: number | undefined) => {
+  if (
+    typeof limit !== 'number' ||
+    !Number.isFinite(limit) ||
+    !Number.isInteger(limit) ||
+    limit < 1
+  ) {
+    return DEFAULT_PAGE_LIMIT;
+  }
+
+  return Math.min(limit, MAX_PAGE_LIMIT);
+};
 
-      return views[0];
+const sanitizeOffset = (offset: number | undefined) => {
+  if (
+    typeof offset !== 'number' ||
+    !Number.isFinite(offset) ||
+    !Number.isSafeInteger(offset) ||
+    offset < 0
+  ) {
+    return 0;
+  }
+
+  return offset;
+};
+
+const resolveStorage = (views: readonly StorageView[], adapterId?: string, storageId?: string) => {
+  if (views.length === 0) {
+    throw new Error('No storages are registered.');
+  }
+
+  if (adapterId !== undefined || storageId !== undefined) {
+    const matches = views.filter(
+      (view) =>
+        (adapterId === undefined || view.target.adapterId === adapterId) &&
+        (storageId === undefined || view.target.storageId === storageId),
+    );
+    const qualifier = [
+      adapterId !== undefined && `adapterId="${adapterId}"`,
+      storageId !== undefined && `storageId="${storageId}"`,
+    ]
+      .filter(Boolean)
+      .join(', ');
+
+    if (matches.length === 0) {
+      throw new Error(
+        `No storage matched ${qualifier}. Available: ${views.map(formatViewRef).join(', ')}`,
+      );
+    }
+
+    if (matches.length > 1) {
+      throw new Error(
+        `Multiple storages matched ${qualifier}. Provide both adapterId and storageId. Available: ${matches.map(formatViewRef).join(', ')}`,
+      );
+    }
+
+    return matches[0]!;
+  }
+
+  if (views.length > 1) {
+    throw new Error(
+      `Multiple storages detected. Provide adapterId and/or storageId. Available: ${views.map(formatViewRef).join(', ')}`,
+    );
+  }
+
+  return views[0]!;
+};
+
+const listStorageKeys = async (view: StorageView, input: StorageListEntriesArgs) => {
+  const limit = sanitizeLimit(input.limit);
+  if (input.cursor !== undefined && input.offset !== undefined) {
+    throw new Error('Provide either cursor or offset, not both.');
+  }
+  const cursor = input.cursor === undefined ? undefined : decodeCursor(input.cursor);
+  if (cursor && !isSameTarget(cursor.target, view.target)) {
+    throw new Error(
+      'Cursor does not match the requested storage. Run list-entries again without a cursor to restart pagination.',
+    );
+  }
+
+  const allKeys = await view.getAllKeys();
+  const offset = cursor?.offset ?? sanitizeOffset(input.offset);
+  const end = Math.min(offset + limit, allKeys.length);
+
+  return {
+    adapterId: view.target.adapterId,
+    storageId: view.target.storageId,
+    total: allKeys.length,
+    items: allKeys.slice(offset, end).map((key) => ({ key })),
+    page: {
+      limit,
+      hasMore: end < allKeys.length,
+      ...(end < allKeys.length
+        ? {
+            nextCursor: encodeCursor({
+              version: 1,
+              target: view.target,
+              offset: end,
+            }),
+          }
+        : {}),
     },
-    [views]
-  );
+  };
+};
+
+export const createStorageAgentHandlers = (views: readonly StorageView[]) => ({
+  listStorages: async () => ({
+    storages: views.map((view) => ({
+      adapterId: view.target.adapterId,
+      storageId: view.target.storageId,
+      adapterName: view.adapterName,
+      storageName: view.storageName,
+      supportedTypes: view.capabilities.supportedTypes,
+    })),
+  }),
+
+  listEntries: async (input: StorageListEntriesArgs) => {
+    const view = resolveStorage(views, input.adapterId, input.storageId);
+    return listStorageKeys(view, input);
+  },
+
+  readEntry: async ({
+    adapterId,
+    storageId,
+    key,
+  }: {
+    adapterId?: string;
+    storageId?: string;
+    key: string;
+  }) => {
+    const view = resolveStorage(views, adapterId, storageId);
+    const entry = await view.get(key);
+
+    if (!entry) {
+      throw new Error(`Key "${key}" not found in storage "${formatViewRef(view)}".`);
+    }
+
+    return {
+      adapterId: view.target.adapterId,
+      storageId: view.target.storageId,
+      entry,
+    };
+  },
+});
+
+export const useStorageAgentTools = (views: StorageView[]) => {
+  const handlers = createStorageAgentHandlers(views);
 
   useRozenitePluginAgentTool({
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.listStorages,
-    handler: async () => ({
-      storages: await Promise.all(
-        views.map(async (view) => ({
-          adapterId: view.target.adapterId,
-          storageId: view.target.storageId,
-          adapterName: view.adapterName,
-          storageName: view.storageName,
-          supportedTypes: view.capabilities.supportedTypes,
-          entryCount: (await view.getAllKeys()).length,
-        }))
-      ),
-    }),
+    handler: handlers.listStorages,
   });
 
   useRozenitePluginAgentTool({
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.listEntries,
-    handler: async ({ adapterId, storageId, offset = 0, limit = 100 }) => {
-      const view = resolveStorage(adapterId, storageId);
-      const allKeys = await view.getAllKeys();
-      const safeOffset = Math.max(0, Math.floor(offset));
-      const safeLimit = Math.max(1, Math.floor(limit));
-      const keys = allKeys.slice(safeOffset, safeOffset + safeLimit);
-
-      return {
-        adapterId: view.target.adapterId,
-        storageId: view.target.storageId,
-        total: allKeys.length,
-        offset: safeOffset,
-        limit: safeLimit,
-        keys,
-      };
-    },
+    handler: handlers.listEntries,
   });
 
   useRozenitePluginAgentTool({
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.readEntry,
-    handler: async ({ adapterId, storageId, key }) => {
-      const view = resolveStorage(adapterId, storageId);
-      const entry = await view.get(key);
-
-      if (!entry) {
-        throw new Error(
-          `Key "${key}" not found in storage "${formatViewRef(view)}".`
-        );
-      }
-
-      return {
-        adapterId: view.target.adapterId,
-        storageId: view.target.storageId,
-        entry,
-      };
-    },
+    handler: handlers.readEntry,
   });
 
   useRozenitePluginAgentTool({
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.createEntry,
     handler: async ({ adapterId, storageId, key, type, value }) => {
-      const view = resolveStorage(adapterId, storageId);
+      const view = resolveStorage(views, adapterId, storageId);
       const existing = await view.get(key);
 
       if (existing) {
         throw new Error(
-          `Key "${key}" already exists in storage "${formatViewRef(view)}". Use edit-entry instead.`
+          `Key "${key}" already exists in storage "${formatViewRef(view)}". Use edit-entry instead.`,
         );
       }
 
@@ -170,12 +275,12 @@ export const useStorageAgentTools = (views: StorageView[]) => {
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.editEntry,
     handler: async ({ adapterId, storageId, key, type, value }) => {
-      const view = resolveStorage(adapterId, storageId);
+      const view = resolveStorage(views, adapterId, storageId);
       const existing = await view.get(key);
 
       if (!existing) {
         throw new Error(
-          `Key "${key}" not found in storage "${formatViewRef(view)}". Use create-entry instead.`
+          `Key "${key}" not found in storage "${formatViewRef(view)}". Use create-entry instead.`,
         );
       }
 
@@ -195,7 +300,7 @@ export const useStorageAgentTools = (views: StorageView[]) => {
     pluginId: STORAGE_AGENT_PLUGIN_ID,
     tool: storageToolDefinitions.removeEntry,
     handler: async ({ adapterId, storageId, key }) => {
-      const view = resolveStorage(adapterId, storageId);
+      const view = resolveStorage(views, adapterId, storageId);
       const existed = !!(await view.get(key));
       await view.delete(key);
 

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

@@ -0,0 +1,99 @@
+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

@@ -1,19 +1,8 @@
 import { describe, expect, it } from 'vitest';
-import {
-  buildSnapshot,
-  computePreview,
-  parseSnapshot,
-  type StorageSnapshotV1,
-} from '../snapshot';
-import type {
-  StorageCapabilities,
-  StorageEntry,
-  StorageTarget,
-} from '../types';
-
-const validSnapshot = (
-  overrides: Partial<StorageSnapshotV1> = {},
-): StorageSnapshotV1 => ({
+import { buildSnapshot, computePreview, parseSnapshot, type StorageSnapshotV1 } from '../snapshot';
+import type { StorageCapabilities, StorageEntry, StorageTarget } from '../types';
+
+const validSnapshot = (overrides: Partial<StorageSnapshotV1> = {}): StorageSnapshotV1 => ({
   version: 1,
   plugin: '@rozenite/storage-plugin',
   createdAt: '2026-05-11T12:00:00.000Z',
@@ -125,16 +114,13 @@ describe('parseSnapshot', () => {
       const result = parseSnapshot(input);
       expect(result.ok).toBe(false);
       if (!result.ok) {
-        expect(result.error.path).toBe(
-          'storage.capabilities.supportedTypes[1]',
-        );
+        expect(result.error.path).toBe('storage.capabilities.supportedTypes[1]');
       }
     });
   });
 
   describe('per-entry rejections', () => {
-    const withEntry = (entry: unknown) =>
-      parseSnapshot({ ...validSnapshot(), entries: [entry] });
+    const withEntry = (entry: unknown) => parseSnapshot({ ...validSnapshot(), entries: [entry] });
 
     it('rejects entry missing key', () => {
       const result = withEntry({ type: 'string', value: 'x' });
@@ -217,9 +203,7 @@ describe('buildSnapshot', () => {
     const capabilities: StorageCapabilities = {
       supportedTypes: ['string', 'number'],
     };
-    const entries: StorageEntry[] = [
-      { key: 'token', type: 'string', value: 'abc' },
-    ];
+    const entries: StorageEntry[] = [{ key: 'token', type: 'string', value: 'abc' }];
 
     const result = buildSnapshot({
       target,
@@ -280,9 +264,7 @@ describe('computePreview', () => {
       entryKeys: new Set(),
       isBlacklisted: (key) => key.startsWith('__'),
     });
-    expect(preview.skippedKeys).toEqual([
-      { key: '__internal', reason: 'blacklist' },
-    ]);
+    expect(preview.skippedKeys).toEqual([{ key: '__internal', reason: 'blacklist' }]);
     expect(preview.newKeys).toEqual(['visible']);
   });
 
@@ -320,12 +302,8 @@ describe('computePreview', () => {
       entryKeys: new Set(['existing']),
       isBlacklisted: (key) => key.startsWith('__'),
     });
-    expect(preview.unsupportedTypes).toEqual([
-      { key: '__blocked', type: 'buffer' },
-    ]);
-    expect(preview.skippedKeys).toEqual([
-      { key: '__skipped', reason: 'blacklist' },
-    ]);
+    expect(preview.unsupportedTypes).toEqual([{ key: '__blocked', type: 'buffer' }]);
+    expect(preview.skippedKeys).toEqual([{ key: '__skipped', reason: 'blacklist' }]);
     expect(preview.overwriteKeys).toEqual(['existing']);
     expect(preview.newKeys).toEqual(['fresh']);
   });
@@ -358,4 +336,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]);
+  });
 });