Implement LayeredStore class combining local and remote indexes

richhankins · richhankins · commit 4316cd4ffafc · 2026-02-06T12:16:37.000-08:00
Agent-Id: agent-49ab3e98-e947-4ed1-8796-9454c317bd15
diff --git a/src/stores/index.ts b/src/stores/index.ts
@@ -10,6 +10,7 @@ export type { MemoryStoreConfig } from "./memory.js";
 export { S3Store } from "./s3.js";
 export type { S3StoreConfig } from "./s3.js";
 export { CompositeStoreReader } from "./composite.js";
+export { LayeredStore } from "./layered-store.js";
 export { parseIndexSpec, parseIndexSpecs } from "./index-spec.js";
 export type { IndexSpec } from "./index-spec.js";
 
diff --git a/src/stores/layered-store.test.ts b/src/stores/layered-store.test.ts
@@ -0,0 +1,205 @@
+/**
+ * Tests for LayeredStore
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { LayeredStore } from "./layered-store.js";
+import { FilesystemStore } from "./filesystem.js";
+import { CompositeStoreReader } from "./composite.js";
+import type { IndexState, IndexStateSearchOnly } from "../core/types.js";
+
+const TEST_DIR = "/tmp/context-connectors-test-layered-store";
+
+// Create a minimal mock IndexState for testing
+function createMockState(id: string): {
+  full: IndexState;
+  search: IndexStateSearchOnly;
+} {
+  const source = {
+    type: "github" as const,
+    config: { owner: "test-owner", repo: "test-repo" },
+    syncedAt: new Date().toISOString(),
+  };
+  return {
+    full: {
+      version: 1,
+      contextState: {
+        mode: "full" as const,
+        checkpointId: `checkpoint-${id}`,
+        addedBlobs: ["blob-1", "blob-2"],
+        deletedBlobs: [],
+        blobs: [
+          ["blob-1", "src/file1.ts"],
+          ["blob-2", "src/file2.ts"],
+        ],
+      },
+      source,
+    },
+    search: {
+      version: 1,
+      contextState: {
+        mode: "search-only" as const,
+        checkpointId: `checkpoint-${id}`,
+        addedBlobs: ["blob-1", "blob-2"],
+        deletedBlobs: [],
+      },
+      source,
+    },
+  };
+}
+
+describe("LayeredStore", () => {
+  let localStore: FilesystemStore;
+  let remoteStore: CompositeStoreReader;
+  let layered: LayeredStore;
+
+  beforeEach(async () => {
+    // Clean up test directory before each test
+    await fs.rm(TEST_DIR, { recursive: true, force: true });
+
+    // Create local store
+    localStore = new FilesystemStore({ basePath: TEST_DIR });
+
+    // Create empty remote store (no specs)
+    remoteStore = await CompositeStoreReader.fromSpecs([]);
+
+    // Create layered store
+    layered = new LayeredStore(localStore, remoteStore);
+  });
+
+  afterEach(async () => {
+    // Clean up test directory after each test
+    await fs.rm(TEST_DIR, { recursive: true, force: true });
+  });
+
+  describe("save", () => {
+    it("saves to local store only", async () => {
+      const { full, search } = createMockState("local");
+
+      await layered.save("test-index", full, search);
+
+      // Verify it was saved to local
+      const loaded = await localStore.loadState("test-index");
+      expect(loaded).not.toBeNull();
+      expect(loaded!.contextState.checkpointId).toBe("checkpoint-local");
+    });
+  });
+
+  describe("loadState", () => {
+    it("loads from local store when available", async () => {
+      const { full, search } = createMockState("local");
+      await layered.save("test-index", full, search);
+
+      const loaded = await layered.loadState("test-index");
+
+      expect(loaded).not.toBeNull();
+      expect(loaded!.contextState.checkpointId).toBe("checkpoint-local");
+    });
+
+    it("returns null when index not found in either store", async () => {
+      const loaded = await layered.loadState("nonexistent");
+
+      expect(loaded).toBeNull();
+    });
+  });
+
+  describe("loadSearch", () => {
+    it("loads search state from local store when available", async () => {
+      const { full, search } = createMockState("local");
+      await layered.save("test-index", full, search);
+
+      const loaded = await layered.loadSearch("test-index");
+
+      expect(loaded).not.toBeNull();
+      expect(loaded!.contextState.checkpointId).toBe("checkpoint-local");
+    });
+
+    it("returns null when search index not found", async () => {
+      const loaded = await layered.loadSearch("nonexistent");
+
+      expect(loaded).toBeNull();
+    });
+  });
+
+  describe("list", () => {
+    it("lists indexes from local store", async () => {
+      const { full, search } = createMockState("1");
+      await layered.save("index-1", full, search);
+      await layered.save("index-2", full, search);
+
+      const list = await layered.list();
+
+      expect(list).toContain("index-1");
+      expect(list).toContain("index-2");
+    });
+
+    it("returns sorted list", async () => {
+      const { full, search } = createMockState("1");
+      await layered.save("zebra", full, search);
+      await layered.save("apple", full, search);
+      await layered.save("banana", full, search);
+
+      const list = await layered.list();
+
+      expect(list).toEqual(["apple", "banana", "zebra"]);
+    });
+  });
+
+  describe("delete", () => {
+    it("deletes from local store", async () => {
+      const { full, search } = createMockState("local");
+      await layered.save("test-index", full, search);
+
+      await layered.delete("test-index");
+
+      const loaded = await layered.loadState("test-index");
+      expect(loaded).toBeNull();
+    });
+
+    it("throws error when trying to delete remote-only index", async () => {
+      // Create a remote store with an index
+      const remoteStoreWithIndex = await CompositeStoreReader.fromSpecs([
+        { type: "name", displayName: "remote-index", value: "remote-index" },
+      ]);
+
+      const layeredWithRemote = new LayeredStore(
+        localStore,
+        remoteStoreWithIndex
+      );
+
+      // Try to delete the remote-only index
+      await expect(
+        layeredWithRemote.delete("remote-index")
+      ).rejects.toThrow(
+        "Cannot delete remote index 'remote-index'. Remote indexes are read-only."
+      );
+    });
+
+    it("allows deletion of local index even if it exists in remote", async () => {
+      const { full, search } = createMockState("local");
+
+      // Save to local
+      await layered.save("test-index", full, search);
+
+      // Create a remote store with the same index
+      const remoteStoreWithIndex = await CompositeStoreReader.fromSpecs([
+        { type: "name", displayName: "test-index", value: "test-index" },
+      ]);
+
+      const layeredWithRemote = new LayeredStore(
+        localStore,
+        remoteStoreWithIndex
+      );
+
+      // Delete should succeed (deletes from local)
+      await expect(layeredWithRemote.delete("test-index")).resolves.toBeUndefined();
+
+      // Verify it's deleted from local but still in remote
+      const localLoaded = await localStore.loadState("test-index");
+      expect(localLoaded).toBeNull();
+    });
+  });
+});
+
diff --git a/src/stores/layered-store.ts b/src/stores/layered-store.ts
@@ -0,0 +1,124 @@
+/**
+ * Layered Store - Combines writable local storage with read-only remote indexes.
+ *
+ * Provides a unified interface that:
+ * - Reads from local storage first, then falls back to remote
+ * - Writes only to local storage
+ * - Lists indexes from both sources (deduplicated)
+ * - Prevents deletion of remote-only indexes
+ *
+ * @module stores/layered-store
+ *
+ * @example
+ * ```typescript
+ * import { LayeredStore, FilesystemStore, CompositeStoreReader } from "@augmentcode/context-connectors/stores";
+ *
+ * const localStore = new FilesystemStore();
+ * const remoteStore = await CompositeStoreReader.fromSpecs(specs);
+ * const layered = new LayeredStore(localStore, remoteStore);
+ *
+ * // Read from local first, then remote
+ * const state = await layered.loadState("my-index");
+ *
+ * // Write only to local
+ * await layered.save("my-index", fullState, searchState);
+ *
+ * // List all available indexes
+ * const keys = await layered.list();
+ * ```
+ */
+
+import type { IndexStore, IndexStoreReader } from "./types.js";
+import type { IndexState, IndexStateSearchOnly } from "../core/types.js";
+import type { FilesystemStore } from "./filesystem.js";
+import type { CompositeStoreReader } from "./composite.js";
+
+/**
+ * Layered store that combines a writable local store with a read-only remote store.
+ *
+ * Implements the IndexStore interface by delegating:
+ * - Read operations to local first, then remote
+ * - Write operations to local only
+ * - List operations to both (deduplicated)
+ */
+export class LayeredStore implements IndexStore {
+  private readonly localStore: FilesystemStore;
+  private readonly remoteStore: CompositeStoreReader;
+
+  /**
+   * Create a new LayeredStore.
+   *
+   * @param localStore - Writable local filesystem store
+   * @param remoteStore - Read-only remote composite store
+   */
+  constructor(localStore: FilesystemStore, remoteStore: CompositeStoreReader) {
+    this.localStore = localStore;
+    this.remoteStore = remoteStore;
+  }
+
+  async loadState(key: string): Promise<IndexState | null> {
+    // Try local first
+    const localState = await this.localStore.loadState(key);
+    if (localState !== null) {
+      return localState;
+    }
+
+    // Fall back to remote
+    return this.remoteStore.loadState(key);
+  }
+
+  async loadSearch(key: string): Promise<IndexStateSearchOnly | null> {
+    // Try local first
+    const localSearch = await this.localStore.loadSearch(key);
+    if (localSearch !== null) {
+      return localSearch;
+    }
+
+    // Fall back to remote
+    return this.remoteStore.loadSearch(key);
+  }
+
+  async save(
+    key: string,
+    fullState: IndexState,
+    searchState: IndexStateSearchOnly
+  ): Promise<void> {
+    // Always save to local store only
+    await this.localStore.save(key, fullState, searchState);
+  }
+
+  async delete(key: string): Promise<void> {
+    // Get lists from both stores
+    const localList = await this.localStore.list();
+    const remoteList = await this.remoteStore.list();
+
+    // Check if the key exists in local
+    const existsInLocal = localList.includes(key);
+
+    // Check if the key exists in remote
+    const existsInRemote = remoteList.includes(key);
+
+    // If it only exists in remote, throw an error
+    if (!existsInLocal && existsInRemote) {
+      throw new Error(
+        `Cannot delete remote index '${key}'. Remote indexes are read-only.`
+      );
+    }
+
+    // Delete from local (no-op if doesn't exist)
+    await this.localStore.delete(key);
+  }
+
+  async list(): Promise<string[]> {
+    // Get lists from both stores
+    const [localList, remoteList] = await Promise.all([
+      this.localStore.list(),
+      this.remoteStore.list(),
+    ]);
+
+    // Merge and deduplicate
+    const merged = new Set([...localList, ...remoteList]);
+    return Array.from(merged).sort();
+  }
+}
+
