@zapier/zapier-sdk 0.8.2 → 0.9.0

package/dist/plugins/manifest/index.test.js

@@ -1,17 +1,16 @@
 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";
-// 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";
-const mockReadFileSync = vi.mocked(readFileSync);
+import { readFile, resolve } from "../../utils/file-utils";
+const mockReadFile = vi.mocked(readFile);
 const mockResolve = vi.mocked(resolve);
+const mockResolveAppKeys = vi.fn();
 describe("manifestPlugin", () => {
     const mockManifest = {
         apps: {
@@ -32,57 +31,91 @@ describe("manifestPlugin", () => {
         vi.clearAllMocks();
         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, options) => {
+                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: [] });
             }),
         };
         mockSdk = {
@@ -117,53 +150,38 @@ describe("manifestPlugin", () => {
         },
     });
     function createTestSdk(options = {}) {
-        return createSdk(options)
-            .addPlugin(apiPlugin)
-            .addPlugin(listAppsMockPlugin)
-            .addPlugin(manifestPlugin);
+        return createSdk(options).addPlugin(apiPlugin).addPlugin(manifestPlugin);
     }
     describe("plugin initialization", () => {
         it("should provide helper functions with direct manifest", () => {
             const sdk = createTestSdk({ manifest: mockManifest });
             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", () => {
             const sdk = createTestSdk();
             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('{"apps": {"other": {"implementationName": "Other", "version": "1.0.0"}}}');
-            const sdk = createTestSdk({
+            mockReadFile.mockResolvedValue('{"apps": {"other": {"implementationName": "Other", "version": "1.0.0"}}}');
+            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();
         });
     });
     describe("getVersionedImplementationId function", () => {
@@ -189,43 +207,10 @@ describe("manifestPlugin", () => {
             expect(result).toBeNull();
         });
     });
-    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();
-            // Verify manifest content is accessible through helper functions
-            const manifestEntry = context.getManifestEntry("slack");
-            expect(manifestEntry).toEqual(mockManifest.apps.slack);
+            createTestSdk({ manifest: mockManifest });
+            // Verify manifest is parsed correctly for other functions to use
         });
         it("should handle manifest with missing version", () => {
             const manifestWithoutVersion = {
@@ -235,66 +220,51 @@ describe("manifestPlugin", () => {
                     },
                 },
             };
-            const sdk = createTestSdk({ manifest: manifestWithoutVersion });
-            const context = sdk.getContext();
-            // Verify manifest entry is accessible and matches expected structure
-            const manifestEntry = context.getManifestEntry("slack");
-            expect(manifestEntry).toEqual(manifestWithoutVersion.apps.slack);
+            createTestSdk({ manifest: manifestWithoutVersion });
+            // Verify manifest with missing version is handled correctly
         });
         it("should handle empty manifest", () => {
-            const sdk = createTestSdk({ manifest: {} });
-            const context = sdk.getContext();
-            // Verify that no manifest entry is found for any app
-            const manifestEntry = context.getManifestEntry("slack");
-            expect(manifestEntry).toBeNull();
+            createTestSdk({ manifest: {} });
+            // 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();
-            expect(console.warn).toHaveBeenCalledWith(expect.stringContaining("Failed to load manifest from nonexistent.json"));
+            // 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 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"), expect.any(SyntaxError));
         });
         it("should handle JSON without apps property", () => {
-            mockReadFileSync.mockReturnValue('{"other": "data"}');
-            const sdk = createTestSdk({ manifestPath: "no-apps.json" });
-            const context = sdk.getContext();
-            // Verify that no manifest entry is found when apps property is missing
-            const manifestEntry = context.getManifestEntry("slack");
-            expect(manifestEntry).toBeNull();
+            mockReadFile.mockResolvedValue('{"other": "data"}');
+            createTestSdk({ manifestPath: "no-apps.json" });
+            // Verify missing apps property is handled correctly
         });
         it("should handle JSON with invalid apps format", () => {
-            mockReadFileSync.mockReturnValue('{"apps": "not an object"}');
-            const sdk = createTestSdk({ manifestPath: "invalid-apps.json" });
-            const context = sdk.getContext();
-            // Verify that no manifest entry is found when apps format is invalid
-            const manifestEntry = context.getManifestEntry("slack");
-            expect(manifestEntry).toBeNull();
+            mockReadFile.mockResolvedValue('{"apps": "not an object"}');
+            createTestSdk({ manifestPath: "invalid-apps.json" });
+            // Verify invalid apps format is handled correctly
         });
     });
     describe("integration with SDK", () => {
@@ -304,15 +274,246 @@ describe("manifestPlugin", () => {
                 .addPlugin(listAppsMockPlugin)
                 .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: {
@@ -328,11 +529,11 @@ describe("loadManifestFromFile", () => {
     beforeEach(() => {
         vi.clearAllMocks();
     });
-    it("should load and parse manifest from file", () => {
-        mockReadFileSync.mockReturnValue(mockManifestContent);
-        const result = loadManifestFromFile("manifest.json");
+    it("should read and parse manifest from file", async () => {
+        mockReadFile.mockResolvedValue(mockManifestContent);
+        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: {
@@ -346,16 +547,70 @@ describe("loadManifestFromFile", () => {
             },
         });
     });
-    it("should handle file read errors", () => {
-        mockReadFileSync.mockImplementation(() => {
-            throw new Error("File not found");
-        });
-        const result = loadManifestFromFile("nonexistent.json");
+    it("should handle file read errors", async () => {
+        mockReadFile.mockRejectedValue(new Error("File not found"));
+        const result = await readManifestFromFile("nonexistent.json");
         expect(result).toBeNull();
     });
-    it("should handle invalid JSON content", () => {
-        mockReadFileSync.mockReturnValue("invalid json");
-        const result = loadManifestFromFile("invalid.json");
+    it("should handle invalid JSON content", async () => {
+        mockReadFile.mockResolvedValue("invalid json");
+        const result = await readManifestFromFile("invalid.json");
         expect(result).toBeNull();
     });
+    describe("getPreferredManifestEntryKey", () => {
+        let mockApi;
+        beforeEach(() => {
+            mockApi = {
+                get: vi.fn(),
+            };
+        });
+        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");
+        });
+    });
 });