@zapier/zapier-sdk 0.8.3 → 0.10.0

package/src/plugins/manifest/index.test.ts

@@ -1,23 +1,26 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { manifestPlugin, loadManifestFromFile } from "./index";
+import {
+  manifestPlugin,
+  readManifestFromFile,
+  findManifestEntry,
+  getPreferredManifestEntryKey,
+} from "./index";
 import { createSdk } from "../../sdk";
 import type { Manifest } from "./schemas";
 
-// Mock fs and path modules
-vi.mock("fs", () => ({
-  readFileSync: vi.fn(),
+// Mock file-utils module
+vi.mock("../../utils/file-utils", () => ({
+  readFile: vi.fn(),
+  writeFile: vi.fn(),
+  resolve: vi.fn((path) => Promise.resolve(`/resolved/${path}`)),
 }));
 
-vi.mock("path", () => ({
-  resolve: vi.fn((path) => `/resolved/${path}`),
-}));
-
-import { readFileSync } from "fs";
-import { resolve } from "path";
+import { readFile, resolve } from "../../utils/file-utils";
 import type { ApiClient } from "../../api";
 
-const mockReadFileSync = vi.mocked(readFileSync);
+const mockReadFile = vi.mocked(readFile);
 const mockResolve = vi.mocked(resolve);
+const mockResolveAppKeys = vi.fn();
 
 describe("manifestPlugin", () => {
   const mockManifest = {
@@ -43,63 +46,100 @@ describe("manifestPlugin", () => {
     vi.spyOn(console, "warn").mockImplementation(() => {});
 
     mockApiClient = {
-      get: vi.fn().mockResolvedValue({
-        count: 1,
-        next: null,
-        previous: null,
-        results: [
-          {
-            selected_api: "SlackCLIAPI@1.29.0",
-            app_id: null,
-            service_id: null,
-            auth_type: "oauth",
-            auth_fields: [
+      get: vi.fn().mockImplementation((url: string, options?: any) => {
+        if (url === "/api/v4/implementations/") {
+          // Mock for manifest entries (versioned)
+          return Promise.resolve({
+            count: 1,
+            next: null,
+            previous: null,
+            results: [
               {
-                key: "access_token",
-                required: true,
-                type: "unicode",
-                computed: true,
+                selected_api: "SlackCLIAPI@1.29.0",
+                app_id: null,
+                service_id: null,
+                auth_type: "oauth",
+                auth_fields: [
+                  {
+                    key: "access_token",
+                    required: true,
+                    type: "unicode",
+                    computed: true,
+                  },
+                ],
+                is_deprecated: false,
+                is_private_only: false,
+                is_invite_only: false,
+                is_beta: false,
+                is_premium: false,
+                is_hidden: false,
+                name: "Slack (1.29.0)",
+                name_clean: "Slack",
+                version: "1.29.0",
+                slug: null,
+                images: {
+                  url_16x16:
+                    "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=16&ixlib=python-3.0.0&q=50&w=16",
+                  url_32x32:
+                    "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=32&ixlib=python-3.0.0&q=50&w=32",
+                  url_64x64:
+                    "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=64&ixlib=python-3.0.0&q=50&w=64",
+                  url_128x128:
+                    "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=128&ixlib=python-3.0.0&q=50&w=128",
+                },
+                primary_color: null,
+                secondary_color: null,
+                classification: "third-party",
+                current_implementation: "SlackCLIAPI@1.30.0",
+                is_adoptable: true,
+                is_usable: true,
+                update_cta_level: "info",
+                update_cta_message:
+                  "This version is legacy. Consider updating to the latest version for better support.",
+                badges: [
+                  {
+                    label: "Legacy",
+                    color: "primary",
+                    tooltip_markdown:
+                      "This version is legacy. Consider updating to the latest version for better support.",
+                  },
+                ],
               },
             ],
-            is_deprecated: false,
-            is_private_only: false,
-            is_invite_only: false,
-            is_beta: false,
-            is_premium: false,
-            is_hidden: false,
-            name: "Slack (1.29.0)",
-            name_clean: "Slack",
-            version: "1.29.0",
-            slug: null,
-            images: {
-              url_16x16:
-                "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=16&ixlib=python-3.0.0&q=50&w=16",
-              url_32x32:
-                "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=32&ixlib=python-3.0.0&q=50&w=32",
-              url_64x64:
-                "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=64&ixlib=python-3.0.0&q=50&w=64",
-              url_128x128:
-                "https://zapier-images.imgix.net/storage/services/6cf3f5a461feadfba7abc93c4c395b33_2.png?auto=format%2Ccompress&fit=crop&h=128&ixlib=python-3.0.0&q=50&w=128",
-            },
-            primary_color: null,
-            secondary_color: null,
-            classification: "third-party",
-            current_implementation: "SlackCLIAPI@1.30.0",
-            is_adoptable: true,
-            is_usable: true,
-            update_cta_level: "info",
-            update_cta_message:
-              "This version is legacy. Consider updating to the latest version for better support.",
-            badges: [
+          });
+        } else if (url === "/api/v4/implementations-meta/lookup/") {
+          // Mock for implementations-meta/lookup fallback
+          const searchParams = options?.searchParams || {};
+
+          // Check if we're looking for a nonexistent app
+          if (
+            searchParams.slugs?.includes("nonexistent") ||
+            searchParams.selected_apis?.includes("nonexistent")
+          ) {
+            return Promise.resolve({
+              count: 0,
+              next: null,
+              previous: null,
+              results: [],
+            });
+          }
+
+          // Return successful response for known apps (like slack)
+          return Promise.resolve({
+            count: 1,
+            next: null,
+            previous: null,
+            results: [
               {
-                label: "Legacy",
-                color: "primary",
-                tooltip_markdown:
-                  "This version is legacy. Consider updating to the latest version for better support.",
+                id: "SlackCLIAPI@1.30.0",
+                name: "Slack",
+                slug: "slack",
+                images: {},
               },
             ],
-          },
-        ],
+          });
+        }
+        return Promise.resolve({ count: 0, results: [] });
       }),
     } as Partial<ApiClient> as ApiClient;
 
@@ -141,10 +181,7 @@ describe("manifestPlugin", () => {
   });
 
   function createTestSdk(options: any = {}) {
-    return createSdk(options)
-      .addPlugin(apiPlugin)
-      .addPlugin(listAppsMockPlugin)
-      .addPlugin(manifestPlugin);
+    return createSdk(options).addPlugin(apiPlugin).addPlugin(manifestPlugin);
   }
 
   describe("plugin initialization", () => {
@@ -153,28 +190,20 @@ describe("manifestPlugin", () => {
       const context = sdk.getContext();
 
       expect(context.getVersionedImplementationId).toBeInstanceOf(Function);
-      expect(context.getImplementation).toBeInstanceOf(Function);
-      expect(context.getManifestEntry).toBeInstanceOf(Function);
     });
 
-    it("should provide helper functions with manifestPath", () => {
-      mockReadFileSync.mockReturnValue(mockManifestContent);
+    it("should provide helper functions with manifestPath", async () => {
+      mockReadFile.mockResolvedValue(mockManifestContent);
 
       const sdk = createTestSdk({ manifestPath: "manifest.json" });
       const context = sdk.getContext();
 
       expect(context.getVersionedImplementationId).toBeInstanceOf(Function);
-      expect(context.getImplementation).toBeInstanceOf(Function);
-      expect(context.getManifestEntry).toBeInstanceOf(Function);
 
       // Verify file operations happen when functions are called
-      const manifestEntry = context.getManifestEntry("slack");
+      await context.getVersionedImplementationId("slack");
       expect(mockResolve).toHaveBeenCalledWith("manifest.json");
-      expect(mockReadFileSync).toHaveBeenCalledWith(
-        "/resolved/manifest.json",
-        "utf8",
-      );
-      expect(manifestEntry).toEqual(mockManifest.apps.slack);
+      expect(mockReadFile).toHaveBeenCalledWith("/resolved/manifest.json");
     });
 
     it("should provide helper functions when no manifest or path provided", () => {
@@ -182,29 +211,22 @@ describe("manifestPlugin", () => {
       const context = sdk.getContext();
 
       expect(context.getVersionedImplementationId).toBeInstanceOf(Function);
-      expect(context.getImplementation).toBeInstanceOf(Function);
-      expect(context.getManifestEntry).toBeInstanceOf(Function);
 
-      // Verify that no manifest entry is found
-      const manifestEntry = context.getManifestEntry("slack");
-      expect(manifestEntry).toBeNull();
+      // Manifest functions are available even when no manifest is provided
     });
 
     it("should prioritize direct manifest over manifestPath", () => {
-      mockReadFileSync.mockReturnValue(
+      mockReadFile.mockResolvedValue(
         '{"apps": {"other": {"implementationName": "Other", "version": "1.0.0"}}}',
       );
 
-      const sdk = createTestSdk({
+      createTestSdk({
         manifest: mockManifest,
         manifestPath: "manifest.json",
       });
-      const context = sdk.getContext();
 
-      // Verify that direct manifest is used (should find slack app)
-      const manifestEntry = context.getManifestEntry("slack");
-      expect(manifestEntry).toEqual(mockManifest.apps.slack);
-      expect(mockReadFileSync).not.toHaveBeenCalled();
+      // Verify that direct manifest is used and file loading is not needed
+      expect(mockReadFile).not.toHaveBeenCalled();
     });
   });
 
@@ -238,54 +260,11 @@ describe("manifestPlugin", () => {
     });
   });
 
-  describe("getImplementation function", () => {
-    it("should return app from manifest when available", async () => {
-      const sdk = createTestSdk({ manifest: mockManifest });
-      const context = sdk.getContext();
-
-      const result = await context.getImplementation("slack");
-      expect(result).toBeDefined();
-      expect(mockApiClient.get).toHaveBeenCalledWith(
-        "/api/v4/implementations/",
-        {
-          searchParams: {
-            selected_apis: "SlackCLIAPI@1.21.1",
-          },
-        },
-      );
-    });
-
-    it("should fetch app from API when not in manifest", async () => {
-      const sdk = createTestSdk();
-      const context = sdk.getContext();
-
-      const result = await context.getImplementation("slack");
-      expect(result).toBeDefined();
-      expect(result?.title).toBe("Slack");
-      expect(result?.current_implementation_id).toBe("SlackCLIAPI@1.30.0");
-    });
-
-    it("should return null when app cannot be fetched", async () => {
-      mockSdk.listApps = vi.fn().mockReturnValue({
-        items: vi.fn().mockReturnValue([][Symbol.iterator]()),
-      });
-
-      const sdk = createTestSdk();
-      const context = sdk.getContext();
-
-      const result = await context.getImplementation("nonexistent");
-      expect(result).toBeNull();
-    });
-  });
-
   describe("manifest parsing", () => {
     it("should parse valid manifest content", () => {
-      const sdk = createTestSdk({ manifest: mockManifest });
-      const context = sdk.getContext();
+      createTestSdk({ manifest: mockManifest });
 
-      // Verify manifest content is accessible through helper functions
-      const manifestEntry = context.getManifestEntry("slack");
-      expect(manifestEntry).toEqual(mockManifest.apps.slack);
+      // Verify manifest is parsed correctly for other functions to use
     });
 
     it("should handle manifest with missing version", () => {
@@ -297,68 +276,58 @@ describe("manifestPlugin", () => {
         },
       };
 
-      const sdk = createTestSdk({ manifest: manifestWithoutVersion });
-      const context = sdk.getContext();
+      createTestSdk({ manifest: manifestWithoutVersion });
 
-      // Verify manifest entry is accessible and matches expected structure
-      const manifestEntry = context.getManifestEntry("slack");
-      expect(manifestEntry).toEqual(manifestWithoutVersion.apps.slack);
+      // Verify manifest with missing version is handled correctly
     });
 
     it("should handle empty manifest", () => {
-      const sdk = createTestSdk({ manifest: {} });
-      const context = sdk.getContext();
+      createTestSdk({ manifest: {} });
 
-      // Verify that no manifest entry is found for any app
-      const manifestEntry = context.getManifestEntry("slack");
-      expect(manifestEntry).toBeNull();
+      // Verify empty manifest is handled correctly
     });
   });
 
   describe("file loading", () => {
-    it("should load manifest from file successfully", () => {
-      mockReadFileSync.mockReturnValue(mockManifestContent);
+    it("should load manifest from file successfully", async () => {
+      mockReadFile.mockResolvedValue(mockManifestContent);
 
       const sdk = createTestSdk({ manifestPath: "manifest.json" });
       const context = sdk.getContext();
 
       // Verify that file operations happen when functions are called
-      const manifestEntry = context.getManifestEntry("slack");
+      await context.getVersionedImplementationId("slack");
       expect(mockResolve).toHaveBeenCalledWith("manifest.json");
-      expect(mockReadFileSync).toHaveBeenCalledWith(
-        "/resolved/manifest.json",
-        "utf8",
-      );
-      expect(manifestEntry).toEqual(mockManifest.apps.slack);
+      expect(mockReadFile).toHaveBeenCalledWith("/resolved/manifest.json");
     });
 
-    it("should handle file read errors gracefully", () => {
-      mockReadFileSync.mockImplementation(() => {
-        throw new Error("File not found");
-      });
+    it("should handle file read errors gracefully", async () => {
+      mockReadFile.mockRejectedValue(new Error("File not found"));
 
       const sdk = createTestSdk({ manifestPath: "nonexistent.json" });
       const context = sdk.getContext();
 
-      // Verify that no manifest entry is found when file loading fails
-      const manifestEntry = context.getManifestEntry("slack");
-      expect(manifestEntry).toBeNull();
+      // Trigger file loading by calling a function
+      await context.getVersionedImplementationId("slack");
+
+      // Verify file loading errors are handled gracefully
       expect(console.warn).toHaveBeenCalledWith(
         expect.stringContaining(
-          "Failed to load manifest from nonexistent.json",
+          "Failed to read manifest from nonexistent.json",
         ),
       );
     });
 
-    it("should handle invalid JSON gracefully", () => {
-      mockReadFileSync.mockReturnValue("invalid json content");
+    it("should handle invalid JSON gracefully", async () => {
+      mockReadFile.mockResolvedValue("invalid json content");
 
       const sdk = createTestSdk({ manifestPath: "invalid.json" });
       const context = sdk.getContext();
 
-      // Verify that no manifest entry is found when JSON parsing fails
-      const manifestEntry = context.getManifestEntry("slack");
-      expect(manifestEntry).toBeNull();
+      // Trigger file loading by calling a function
+      await context.getVersionedImplementationId("slack");
+
+      // Verify JSON parsing errors are handled gracefully
       expect(console.warn).toHaveBeenCalledWith(
         expect.stringContaining(
           "Failed to parse manifest from /resolved/invalid.json",
@@ -368,25 +337,19 @@ describe("manifestPlugin", () => {
     });
 
     it("should handle JSON without apps property", () => {
-      mockReadFileSync.mockReturnValue('{"other": "data"}');
+      mockReadFile.mockResolvedValue('{"other": "data"}');
 
-      const sdk = createTestSdk({ manifestPath: "no-apps.json" });
-      const context = sdk.getContext();
+      createTestSdk({ manifestPath: "no-apps.json" });
 
-      // Verify that no manifest entry is found when apps property is missing
-      const manifestEntry = context.getManifestEntry("slack");
-      expect(manifestEntry).toBeNull();
+      // Verify missing apps property is handled correctly
     });
 
     it("should handle JSON with invalid apps format", () => {
-      mockReadFileSync.mockReturnValue('{"apps": "not an object"}');
+      mockReadFile.mockResolvedValue('{"apps": "not an object"}');
 
-      const sdk = createTestSdk({ manifestPath: "invalid-apps.json" });
-      const context = sdk.getContext();
+      createTestSdk({ manifestPath: "invalid-apps.json" });
 
-      // Verify that no manifest entry is found when apps format is invalid
-      const manifestEntry = context.getManifestEntry("slack");
-      expect(manifestEntry).toBeNull();
+      // Verify invalid apps format is handled correctly
     });
   });
 
@@ -398,17 +361,294 @@ describe("manifestPlugin", () => {
         .addPlugin(manifestPlugin);
       const context = sdk.getContext();
 
-      // Verify that the manifest data is used correctly
-      const manifestEntry = context.getManifestEntry("slack");
-      expect(manifestEntry).toEqual(mockManifest.apps.slack);
+      // Verify that the manifest data is used correctly by other functions
 
       const versionedId = await context.getVersionedImplementationId("slack");
       expect(versionedId).toBe("SlackCLIAPI@1.21.1");
     });
   });
+
+  describe("findManifestEntry function", () => {
+    it("should find entry by direct key match", () => {
+      const manifest = {
+        apps: {
+          slack: { implementationName: "SlackCLIAPI", version: "1.21.1" },
+          gmail: { implementationName: "GmailCLIAPI", version: "2.0.0" },
+        },
+      };
+
+      const result = findManifestEntry({ appKey: "slack", manifest });
+
+      expect(result).toEqual([
+        "slack",
+        { implementationName: "SlackCLIAPI", version: "1.21.1" },
+      ]);
+    });
+
+    it("should find entry by implementation name match", () => {
+      const manifest = {
+        apps: {
+          SlackCLIAPI: { implementationName: "SlackCLIAPI", version: "1.21.1" },
+          GmailCLIAPI: { implementationName: "GmailCLIAPI", version: "2.0.0" },
+        },
+      };
+
+      const result = findManifestEntry({ appKey: "SlackCLIAPI", manifest });
+
+      expect(result).toEqual([
+        "SlackCLIAPI",
+        { implementationName: "SlackCLIAPI", version: "1.21.1" },
+      ]);
+    });
+
+    it("should find existing key when searching by implementation name", () => {
+      const manifest = {
+        apps: {
+          SlackCLIAPI: { implementationName: "SlackCLIAPI", version: "1.21.1" },
+        },
+      };
+
+      // This is the key test: searching by implementation name should find existing entry
+      const result = findManifestEntry({ appKey: "SlackCLIAPI", manifest });
+
+      expect(result).toEqual([
+        "SlackCLIAPI",
+        { implementationName: "SlackCLIAPI", version: "1.21.1" },
+      ]);
+    });
+
+    it("should return null when no match found", () => {
+      const manifest = {
+        apps: {
+          gmail: { implementationName: "GmailCLIAPI", version: "2.0.0" },
+        },
+      };
+
+      const result = findManifestEntry({ appKey: "slack", manifest });
+
+      expect(result).toBeNull();
+    });
+
+    it("should handle snake-cased slugs", () => {
+      const manifest = {
+        apps: {
+          "google-sheets": {
+            implementationName: "GoogleSheetsCLIAPI",
+            version: "1.0.0",
+          },
+        },
+      };
+
+      const result = findManifestEntry({ appKey: "google_sheets", manifest });
+
+      expect(result).toEqual([
+        "google-sheets",
+        { implementationName: "GoogleSheetsCLIAPI", version: "1.0.0" },
+      ]);
+    });
+
+    it("should NOT find entry when searching slug against implementation name key (current limitation)", () => {
+      const manifest = {
+        apps: {
+          SlackCLIAPI: { implementationName: "SlackCLIAPI", version: "1.21.1" },
+        },
+      };
+
+      // This will fail - we search by "slack" but can't find "SlackCLIAPI" entry
+      // This is the core issue we need to solve
+      const result = findManifestEntry({ appKey: "slack", manifest });
+
+      expect(result).toBeNull(); // Current behavior - doesn't find it
+      // We need to fix this so it CAN find existing implementation name entries
+    });
+  });
+
+  describe("updateManifestEntry with slug-to-implementation matching", () => {
+    it("should find existing implementation name entry when input is slug", async () => {
+      // Mock existing manifest with implementation name as key
+      mockReadFile.mockResolvedValue(
+        JSON.stringify({
+          apps: {
+            SlackCLIAPI: {
+              implementationName: "SlackCLIAPI",
+              version: "1.21.1",
+            },
+          },
+        }),
+      );
+
+      // Mock resolveAppKeys to resolve "slack" to "SlackCLIAPI"
+      mockResolveAppKeys.mockResolvedValue([
+        {
+          slug: "slack",
+          implementationName: "SlackCLIAPI",
+          version: "1.30.0",
+          lookupAppKey: "slack",
+        },
+      ]);
+
+      const sdk = createTestSdk();
+      const context = sdk.getContext();
+
+      // This should now find the existing "SlackCLIAPI" entry
+      const [manifestKey] = await context.updateManifestEntry(
+        "slack", // Input is slug
+        { implementationName: "SlackCLIAPI", version: "1.30.0" },
+      );
+
+      // Should return the existing key, not create a new one
+      expect(manifestKey).toBe("SlackCLIAPI");
+    });
+  });
+
+  describe("resolveAppKeys function", () => {
+    it("should resolve slug to manifest entry even when manifest uses implementation name as key", async () => {
+      const manifest = {
+        apps: {
+          SlackCLIAPI: { implementationName: "SlackCLIAPI", version: "1.21.1" },
+        },
+      };
+
+      // Mock API to return slack app data when looking up "slack"
+      mockApiClient.get = vi.fn().mockResolvedValue({
+        count: 1,
+        next: null,
+        previous: null,
+        results: [
+          {
+            id: "SlackCLIAPI@1.30.0",
+            name: "Slack",
+            slug: "slack",
+            key: "SlackCLIAPI", // This is the implementation name
+            version: "1.30.0",
+          },
+        ],
+      });
+
+      // Test resolveAppKeys directly using the manifest plugin
+      const sdk = createSdk({ manifest })
+        .addPlugin(apiPlugin)
+        .addPlugin(manifestPlugin);
+      const context = sdk.getContext();
+
+      const resolved = await context.resolveAppKeys({ appKeys: ["slack"] });
+
+      // Should find the manifest entry and use its version (1.21.1) instead of latest (1.30.0)
+      expect(resolved).toHaveLength(1);
+      expect(resolved[0]).toEqual({
+        slug: "slack",
+        implementationName: "SlackCLIAPI",
+        version: "1.21.1", // Should use manifest version, not API version
+        lookupAppKey: "slack",
+      });
+    });
+
+    it("should fall back to API version when no manifest entry found", async () => {
+      const manifest = { apps: {} }; // Empty manifest
+
+      // Mock API to return slack app data
+      mockApiClient.get = vi.fn().mockResolvedValue({
+        count: 1,
+        next: null,
+        previous: null,
+        results: [
+          {
+            id: "SlackCLIAPI@1.30.0",
+            name: "Slack",
+            slug: "slack",
+            key: "SlackCLIAPI",
+            version: "1.30.0",
+          },
+        ],
+      });
+
+      const sdk = createSdk({ manifest })
+        .addPlugin(apiPlugin)
+        .addPlugin(manifestPlugin);
+      const context = sdk.getContext();
+
+      const resolved = await context.resolveAppKeys({ appKeys: ["slack"] });
+
+      // Should use API version since no manifest entry found
+      expect(resolved).toHaveLength(1);
+      expect(resolved[0]).toEqual({
+        slug: "slack",
+        implementationName: "SlackCLIAPI",
+        version: "1.30.0", // Should use API version
+        lookupAppKey: "slack",
+      });
+    });
+
+    it("should always use version from input when specified (slug@version)", async () => {
+      const manifest = {
+        apps: {
+          SlackCLIAPI: { implementationName: "SlackCLIAPI", version: "1.21.1" },
+        },
+      };
+
+      // Mock API to return slack app data
+      mockApiClient.get = vi.fn().mockResolvedValue({
+        count: 1,
+        next: null,
+        previous: null,
+        results: [
+          {
+            id: "SlackCLIAPI@1.30.0",
+            name: "Slack",
+            slug: "slack",
+            key: "SlackCLIAPI",
+            version: "1.30.0",
+          },
+        ],
+      });
+
+      const sdk = createSdk({ manifest })
+        .addPlugin(apiPlugin)
+        .addPlugin(manifestPlugin);
+      const context = sdk.getContext();
+
+      // Input version should take precedence over both manifest (1.21.1) and API (1.30.0)
+      const resolved = await context.resolveAppKeys({
+        appKeys: ["slack@1.2.3"],
+      });
+
+      expect(resolved).toHaveLength(1);
+      expect(resolved[0]).toEqual({
+        slug: "slack",
+        implementationName: "SlackCLIAPI",
+        version: "1.2.3", // Should use input version, not manifest or API
+        lookupAppKey: "slack",
+      });
+    });
+
+    it("should always use version from input when specified (implementationName@version)", async () => {
+      const manifest = {
+        apps: {
+          SlackCLIAPI: { implementationName: "SlackCLIAPI", version: "1.21.1" },
+        },
+      };
+
+      const sdk = createSdk({ manifest })
+        .addPlugin(apiPlugin)
+        .addPlugin(manifestPlugin);
+      const context = sdk.getContext();
+
+      // Input version should take precedence over manifest version
+      const resolved = await context.resolveAppKeys({
+        appKeys: ["SlackCLIAPI@1.2.3"],
+      });
+
+      expect(resolved).toHaveLength(1);
+      expect(resolved[0]).toEqual({
+        implementationName: "SlackCLIAPI",
+        version: "1.2.3", // Should use input version, not manifest version
+        lookupAppKey: "SlackCLIAPI",
+      });
+    });
+  });
 });
 
-describe("loadManifestFromFile", () => {
+describe("readManifestFromFile", () => {
   const mockManifestContent = JSON.stringify({
     apps: {
       slack: {
@@ -426,16 +666,13 @@ describe("loadManifestFromFile", () => {
     vi.clearAllMocks();
   });
 
-  it("should load and parse manifest from file", () => {
-    mockReadFileSync.mockReturnValue(mockManifestContent);
+  it("should read and parse manifest from file", async () => {
+    mockReadFile.mockResolvedValue(mockManifestContent);
 
-    const result = loadManifestFromFile("manifest.json");
+    const result = await readManifestFromFile("manifest.json");
 
     expect(mockResolve).toHaveBeenCalledWith("manifest.json");
-    expect(mockReadFileSync).toHaveBeenCalledWith(
-      "/resolved/manifest.json",
-      "utf8",
-    );
+    expect(mockReadFile).toHaveBeenCalledWith("/resolved/manifest.json");
     expect(result).toEqual({
       apps: {
         slack: {
@@ -450,21 +687,90 @@ describe("loadManifestFromFile", () => {
     });
   });
 
-  it("should handle file read errors", () => {
-    mockReadFileSync.mockImplementation(() => {
-      throw new Error("File not found");
-    });
+  it("should handle file read errors", async () => {
+    mockReadFile.mockRejectedValue(new Error("File not found"));
 
-    const result = loadManifestFromFile("nonexistent.json");
+    const result = await readManifestFromFile("nonexistent.json");
 
     expect(result).toBeNull();
   });
 
-  it("should handle invalid JSON content", () => {
-    mockReadFileSync.mockReturnValue("invalid json");
+  it("should handle invalid JSON content", async () => {
+    mockReadFile.mockResolvedValue("invalid json");
 
-    const result = loadManifestFromFile("invalid.json");
+    const result = await readManifestFromFile("invalid.json");
 
     expect(result).toBeNull();
   });
+
+  describe("getPreferredManifestEntryKey", () => {
+    let mockApi: ApiClient;
+
+    beforeEach(() => {
+      mockApi = {
+        get: vi.fn(),
+      } as any;
+    });
+
+    it("should prefer slug when available", async () => {
+      const result = await getPreferredManifestEntryKey({
+        appKey: "slack",
+        api: mockApi,
+      });
+
+      expect(result).toBe("slack");
+    });
+
+    it("should look up slug for implementation name", async () => {
+      // Mock API response for implementation name lookup
+      mockApi.get = vi.fn().mockResolvedValueOnce({
+        results: [
+          {
+            key: "SlackCLIAPI",
+            slug: "slack",
+            version: "1.0.0",
+            current_implementation_id: "SlackCLIAPI@1.0.0",
+          },
+        ],
+        next: null,
+      });
+
+      const result = await getPreferredManifestEntryKey({
+        appKey: "SlackCLIAPI",
+        api: mockApi,
+      });
+
+      expect(result).toBe("slack");
+      expect(mockApi.get).toHaveBeenCalledWith(
+        "/api/v4/implementations-meta/lookup/",
+        {
+          searchParams: { selected_apis: "SlackCLIAPI" },
+        },
+      );
+    });
+
+    it("should fall back to implementation name if slug lookup fails", async () => {
+      // Mock API to return empty results
+      mockApi.get = vi.fn().mockResolvedValueOnce({
+        results: [],
+        next: null,
+      });
+
+      const result = await getPreferredManifestEntryKey({
+        appKey: "SlackCLIAPI",
+        api: mockApi,
+      });
+
+      expect(result).toBe("SlackCLIAPI");
+    });
+
+    it("should fall back to original key if no slug or implementation name", async () => {
+      const result = await getPreferredManifestEntryKey({
+        appKey: "some-random-key",
+        api: mockApi,
+      });
+
+      expect(result).toBe("some-random-key");
+    });
+  });
 });