@blackbelt-technology/pi-agent-dashboard 0.4.1 → 0.4.2

package/packages/server/src/__tests__/package-manager-wrapper-move.test.ts

@@ -0,0 +1,414 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import {
+	PackageManagerWrapper,
+	AlreadyAtDestinationError,
+	InvalidMoveRequestError,
+	UnsupportedSourceForDestinationError,
+} from "../package-manager-wrapper.js";
+import {
+	ToolRegistry,
+	OverridesStore,
+} from "@blackbelt-technology/pi-dashboard-shared/tool-registry/index.js";
+import { registerDefaultTools } from "@blackbelt-technology/pi-dashboard-shared/tool-registry/definitions.js";
+import os from "node:os";
+import path from "node:path";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+
+// ──────────────────────────────────────────────────────────────────
+// Fake pi.DefaultPackageManager + fake settingsManager that share
+// in-memory state so we can verify the wrapper's `move()` end-to-end.
+// ──────────────────────────────────────────────────────────────────
+
+interface FakeState {
+	globalPackages: any[];
+	projectPackages: any[];
+}
+
+function makeFakePm(state: FakeState) {
+	const settingsManager = {
+		getGlobalSettings: () => ({ packages: [...state.globalPackages] }),
+		getProjectSettings: () => ({ packages: [...state.projectPackages] }),
+		setPackages: vi.fn((p: any[]) => {
+			state.globalPackages = [...p];
+		}),
+		setProjectPackages: vi.fn((p: any[]) => {
+			state.projectPackages = [...p];
+		}),
+	};
+	const pm: any = {
+		settingsManager,
+		setProgressCallback: vi.fn(),
+		installAndPersist: vi.fn(async (source: string, { local }: { local: boolean }) => {
+			// Simulate pi: append a bare-string entry to the relevant array.
+			if (local) state.projectPackages.push(source);
+			else state.globalPackages.push(source);
+		}),
+		removeAndPersist: vi.fn(async (source: string, { local }: { local: boolean }) => {
+			const arr = local ? state.projectPackages : state.globalPackages;
+			const idx = arr.findIndex((e: any) =>
+				typeof e === "string" ? e === source : e?.source === source,
+			);
+			if (idx >= 0) arr.splice(idx, 1);
+			return idx >= 0;
+		}),
+		update: vi.fn(async () => {}),
+		listConfiguredPackages: () => [
+			...state.globalPackages.map((s) => ({
+				source: typeof s === "string" ? s : s.source,
+				scope: "user",
+				filtered: false,
+			})),
+			...state.projectPackages.map((s) => ({
+				source: typeof s === "string" ? s : s.source,
+				scope: "project",
+				filtered: false,
+			})),
+		],
+	};
+	return { pm, settingsManager };
+}
+
+let currentState: FakeState;
+let currentFakePm: ReturnType<typeof makeFakePm>;
+
+function makeFakePiModule() {
+	return {
+		DefaultPackageManager: function () {
+			// Return the SAME shared fake pm so test assertions can inspect it.
+			return currentFakePm.pm;
+		},
+		SettingsManager: { create: () => ({}) },
+	};
+}
+
+function makeTestRegistry(): ToolRegistry {
+	const tmpDir = mkdtempSync(path.join(os.tmpdir(), "pmw-move-"));
+	const overrides = new OverridesStore({
+		filePath: path.join(tmpDir, "tool-overrides.json"),
+	});
+	const stubDir = path.join(tmpDir, "pi-coding-agent", "dist");
+	mkdirSync(stubDir, { recursive: true });
+	const stubPath = path.join(stubDir, "index.js");
+	writeFileSync(stubPath, "// test stub\n");
+	overrides.set("pi-coding-agent", stubPath);
+
+	const registry = new ToolRegistry({
+		overrides,
+		importModule: async () => makeFakePiModule(),
+	});
+	registerDefaultTools(registry);
+	return registry;
+}
+
+describe("PackageManagerWrapper.move()", () => {
+	let wrapper: PackageManagerWrapper;
+
+	beforeEach(() => {
+		currentState = { globalPackages: [], projectPackages: [] };
+		currentFakePm = makeFakePm(currentState);
+		wrapper = new PackageManagerWrapper(makeTestRegistry());
+	});
+
+	// ── Synchronous validation throws ──────────────────────────────────────
+
+	it("throws InvalidMoveRequestError when fromScope === toScope", async () => {
+		await expect(
+			wrapper.move({
+				entry: "npm:foo",
+				fromScope: "global",
+				toScope: "global",
+			}),
+		).rejects.toThrow(InvalidMoveRequestError);
+	});
+
+	it("throws InvalidMoveRequestError when fromCwd missing for local fromScope", async () => {
+		await expect(
+			wrapper.move({
+				entry: "npm:foo",
+				fromScope: "local",
+				toScope: "global",
+			}),
+		).rejects.toThrow(InvalidMoveRequestError);
+	});
+
+	it("throws InvalidMoveRequestError when toCwd missing for local toScope", async () => {
+		await expect(
+			wrapper.move({
+				entry: "npm:foo",
+				fromScope: "global",
+				toScope: "local",
+			}),
+		).rejects.toThrow(InvalidMoveRequestError);
+	});
+
+	it("throws InvalidMoveRequestError on empty entry source", async () => {
+		await expect(
+			wrapper.move({
+				entry: "",
+				fromScope: "global",
+				toScope: "local",
+				toCwd: "/p",
+			}),
+		).rejects.toThrow(InvalidMoveRequestError);
+	});
+
+	it("throws UnsupportedSourceForDestinationError for relative path without fromCwd (local origin)", async () => {
+		// fromScope=local needs fromCwd anyway, but the rel-path check
+		// adds a more specific error code. The wrapper checks
+		// InvalidMoveRequestError first; this guards the secondary check.
+		// The current invariant is: rel-path without fromCwd while origin
+		// is local. We can validate that path explicitly when local
+		// fromScope+fromCwd is missing — let's just confirm the local
+		// invariant fires.
+		await expect(
+			wrapper.move({
+				entry: "..",
+				fromScope: "local",
+				toScope: "global",
+			}),
+		).rejects.toThrow(InvalidMoveRequestError);
+	});
+
+	// ── Happy path: npm move (global → local) ──────────────────────────────
+
+	it("moves npm package from global to local: install + remove with shared moveId", async () => {
+		currentState.globalPackages = ["npm:pi-flows"];
+
+		const completions: any[] = [];
+		const reloadFn = vi.fn().mockResolvedValue(2);
+		wrapper.setCompleteListener((r) => completions.push(r));
+		wrapper.setReloadSessions(reloadFn);
+
+		const moveId = await wrapper.move({
+			entry: "npm:pi-flows",
+			fromScope: "global",
+			toScope: "local",
+			toCwd: "/proj",
+		});
+
+		expect(moveId).toMatch(/^[0-9a-f-]+$/);
+		await vi.waitFor(() => expect(wrapper.isBusy()).toBe(false));
+
+		// Two pi calls (install at dest, remove from origin).
+		expect(currentFakePm.pm.installAndPersist).toHaveBeenCalledWith("npm:pi-flows", { local: true });
+		expect(currentFakePm.pm.removeAndPersist).toHaveBeenCalledWith("npm:pi-flows", { local: false });
+
+		// Final state: removed from global, present in local.
+		expect(currentState.globalPackages).toEqual([]);
+		expect(currentState.projectPackages).toEqual(["npm:pi-flows"]);
+
+		// Exactly ONE reload (coalesced), not two.
+		expect(reloadFn).toHaveBeenCalledOnce();
+
+		// Exactly ONE complete event, action=move, with moveId.
+		expect(completions).toHaveLength(1);
+		expect(completions[0].action).toBe("move");
+		expect(completions[0].success).toBe(true);
+		expect(completions[0].moveId).toBe(moveId);
+		expect(completions[0].sessionsReloaded).toBe(2);
+	});
+
+	// ── Happy path: git move (local → global) ──────────────────────────────
+
+	it("moves git package preserving pin in source string", async () => {
+		currentState.projectPackages = ["git:github.com/x/y@v1.2.3"];
+
+		await wrapper.move({
+			entry: "git:github.com/x/y@v1.2.3",
+			fromScope: "local",
+			fromCwd: "/proj",
+			toScope: "global",
+		});
+		await vi.waitFor(() => expect(wrapper.isBusy()).toBe(false));
+
+		// Install at global with the pinned source verbatim.
+		expect(currentFakePm.pm.installAndPersist).toHaveBeenCalledWith(
+			"git:github.com/x/y@v1.2.3",
+			{ local: false },
+		);
+		expect(currentState.globalPackages).toContain("git:github.com/x/y@v1.2.3");
+		expect(currentState.projectPackages).toEqual([]);
+	});
+
+	// ── Identity preflight ──────────────────────────────────────────────────
+
+	it("AlreadyAtDestinationError surfaces via complete listener (already at target identity)", async () => {
+		// Already installed in BOTH scopes — different version pins, but
+		// pi dedup identity is the bare name.
+		currentState.globalPackages = ["npm:pi-flows@1.0.0"];
+		currentState.projectPackages = ["npm:pi-flows@2.0.0"];
+
+		const completions: any[] = [];
+		wrapper.setCompleteListener((r) => completions.push(r));
+
+		await wrapper.move({
+			entry: "npm:pi-flows@1.0.0",
+			fromScope: "global",
+			toScope: "local",
+			toCwd: "/proj",
+		});
+		await vi.waitFor(() => expect(wrapper.isBusy()).toBe(false));
+
+		expect(completions).toHaveLength(1);
+		expect(completions[0].success).toBe(false);
+		expect(completions[0].error).toMatch(/already installed/i);
+		// State unchanged.
+		expect(currentState.globalPackages).toEqual(["npm:pi-flows@1.0.0"]);
+		expect(currentState.projectPackages).toEqual(["npm:pi-flows@2.0.0"]);
+		// pi was NOT called.
+		expect(currentFakePm.pm.installAndPersist).not.toHaveBeenCalled();
+		expect(currentFakePm.pm.removeAndPersist).not.toHaveBeenCalled();
+	});
+
+	// ── Path arm: settings-only edit (rel-path → global) ───────────────────
+
+	it("path source moves are settings-only — no install/remove called", async () => {
+		// Origin: local with relative path "..".
+		currentState.projectPackages = [".."];
+
+		await wrapper.move({
+			entry: "..",
+			fromScope: "local",
+			fromCwd: "/proj",
+			toScope: "global",
+		});
+		await vi.waitFor(() => expect(wrapper.isBusy()).toBe(false));
+
+		// pi was NOT called (settings-edit arm).
+		expect(currentFakePm.pm.installAndPersist).not.toHaveBeenCalled();
+		expect(currentFakePm.pm.removeAndPersist).not.toHaveBeenCalled();
+
+		// Origin scope cleared; destination has the resolved abs path.
+		expect(currentState.projectPackages).toEqual([]);
+		expect(currentState.globalPackages.length).toBe(1);
+		const newSource = currentState.globalPackages[0];
+		// ".." resolved against /proj/.pi → /proj
+		expect(typeof newSource === "string" ? newSource : newSource.source).toBe("/proj");
+	});
+
+	// ── Filter preservation ─────────────────────────────────────────────────
+
+	it("preserves filter object when moving npm package with filters", async () => {
+		const entry = {
+			source: "npm:pi-flows",
+			extensions: ["a.ts"],
+			skills: [],
+		};
+		currentState.globalPackages = [entry];
+
+		await wrapper.move({
+			entry,
+			fromScope: "global",
+			toScope: "local",
+			toCwd: "/proj",
+		});
+		await vi.waitFor(() => expect(wrapper.isBusy()).toBe(false));
+
+		// Destination should have the FULL object form, not just the bare string
+		// pi's installer wrote.
+		const destEntry = currentState.projectPackages[0];
+		expect(typeof destEntry).toBe("object");
+		expect(destEntry).toMatchObject({
+			source: "npm:pi-flows",
+			extensions: ["a.ts"],
+			skills: [],
+		});
+	});
+
+	it("preserves filter object on path-source move", async () => {
+		const entry = { source: "..", extensions: ["foo.ts"] };
+		currentState.projectPackages = [entry];
+
+		await wrapper.move({
+			entry,
+			fromScope: "local",
+			fromCwd: "/proj",
+			toScope: "global",
+		});
+		await vi.waitFor(() => expect(wrapper.isBusy()).toBe(false));
+
+		const destEntry = currentState.globalPackages[0];
+		expect(destEntry).toMatchObject({
+			source: "/proj",
+			extensions: ["foo.ts"],
+		});
+	});
+
+	// ── Partial-success: install OK, remove fails ──────────────────────────
+
+	it("partial success when install succeeds but remove from origin throws", async () => {
+		currentState.globalPackages = ["npm:pi-flows"];
+		currentFakePm.pm.removeAndPersist.mockRejectedValueOnce(new Error("remove blew up"));
+
+		const completions: any[] = [];
+		wrapper.setCompleteListener((r) => completions.push(r));
+
+		await wrapper.move({
+			entry: "npm:pi-flows",
+			fromScope: "global",
+			toScope: "local",
+			toCwd: "/proj",
+		});
+		await vi.waitFor(() => expect(wrapper.isBusy()).toBe(false));
+
+		const result = completions[0];
+		expect(result.success).toBe(true);
+		expect(result.action).toBe("move");
+		expect(result.partialSuccess).toBeDefined();
+		expect(result.partialSuccess.installed).toBe(true);
+		expect(result.partialSuccess.removed).toBe(false);
+		expect(result.partialSuccess.removeError).toMatch(/remove blew up/);
+	});
+
+	// ── Task 3.4: moveId propagation through progress events ───────────────
+
+	it("emits progress events tagged with the same moveId across both phases", async () => {
+		currentState.globalPackages = ["npm:pi-flows"];
+
+		const progressEvents: Array<{ opId: string; event: any; moveId?: string }> = [];
+		wrapper.setProgressListener((opId, event, moveId) => {
+			progressEvents.push({ opId, event, moveId });
+		});
+
+		// pi's setProgressCallback captures the wrapper's callback. Fire some
+		// progress events from the install phase via the captured callback.
+		let progressCb: any;
+		currentFakePm.pm.setProgressCallback.mockImplementation((cb: any) => {
+			progressCb = cb;
+		});
+		currentFakePm.pm.installAndPersist.mockImplementation(
+			async (source: string, { local }: { local: boolean }) => {
+				progressCb?.({ type: "start", action: "install", source });
+				progressCb?.({ type: "complete", action: "install", source });
+				if (local) currentState.projectPackages.push(source);
+				else currentState.globalPackages.push(source);
+			},
+		);
+		currentFakePm.pm.removeAndPersist.mockImplementation(
+			async (source: string, { local }: { local: boolean }) => {
+				progressCb?.({ type: "start", action: "remove", source });
+				progressCb?.({ type: "complete", action: "remove", source });
+				const arr = local ? currentState.projectPackages : currentState.globalPackages;
+				const idx = arr.findIndex((e: any) =>
+					typeof e === "string" ? e === source : e?.source === source,
+				);
+				if (idx >= 0) arr.splice(idx, 1);
+				return idx >= 0;
+			},
+		);
+
+		const moveId = await wrapper.move({
+			entry: "npm:pi-flows",
+			fromScope: "global",
+			toScope: "local",
+			toCwd: "/proj",
+		});
+		await vi.waitFor(() => expect(wrapper.isBusy()).toBe(false));
+
+		// All emitted progress events must carry the same moveId.
+		expect(progressEvents.length).toBeGreaterThanOrEqual(2);
+		for (const ev of progressEvents) {
+			expect(ev.moveId).toBe(moveId);
+		}
+	});
+});

package/packages/server/src/__tests__/package-routes.test.ts

@@ -5,7 +5,12 @@ import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import Fastify from "fastify";
 import type { FastifyInstance } from "fastify";
 import { registerPackageRoutes } from "../routes/package-routes.js";
-import { PackageOperationBusyError } from "../package-manager-wrapper.js";
+import {
+  PackageOperationBusyError,
+  AlreadyAtDestinationError,
+  InvalidMoveRequestError,
+  UnsupportedSourceForDestinationError,
+} from "../package-manager-wrapper.js";
 
 // Mock pi dependency (pulled transitively by package-manager-wrapper)
 vi.mock("@mariozechner/pi-coding-agent", () => ({
@@ -27,6 +32,7 @@ import { searchPackages, fetchReadme, PackageNotFoundError } from "../npm-search
 function createMockWrapper() {
   return {
     run: vi.fn().mockResolvedValue("op-123"),
+    move: vi.fn().mockResolvedValue("move-456"),
     listInstalled: vi.fn().mockReturnValue([{ source: "npm:pi-doom", scope: "user", filtered: false }]),
     checkUpdates: vi.fn().mockResolvedValue([]),
     isBusy: vi.fn().mockReturnValue(false),
@@ -88,11 +94,43 @@ describe("package-routes", () => {
   });
 
   describe("GET /api/packages/installed", () => {
-    it("returns installed packages", async () => {
+    it("returns installed packages with enrichment fields", async () => {
       const res = await app.inject({ method: "GET", url: "/api/packages/installed?scope=global" });
       expect(res.statusCode).toBe(200);
       const body = JSON.parse(res.body);
-      expect(body.data[0].source).toBe("npm:pi-doom");
+      const row = body.data[0];
+      expect(row.source).toBe("npm:pi-doom");
+      // Enrichment fields are present on every row.
+      expect(row).toHaveProperty("displayName");
+      expect(row).toHaveProperty("isRecommended");
+      expect(row).toHaveProperty("isBundled");
+      // pi-doom is not in RECOMMENDED_EXTENSIONS — falls back to basename.
+      expect(row.displayName).toBe("pi-doom");
+      expect(row.isRecommended).toBe(false);
+      expect(row.isBundled).toBe(false);
+    });
+
+    it("matches a row to RECOMMENDED_EXTENSIONS by source", async () => {
+      wrapper.listInstalled.mockReturnValueOnce([
+        { source: "npm:@tintinweb/pi-subagents", scope: "user", filtered: false },
+      ]);
+      const res = await app.inject({ method: "GET", url: "/api/packages/installed?scope=global" });
+      const body = JSON.parse(res.body);
+      const row = body.data[0];
+      expect(row.isRecommended).toBe(true);
+      // displayName comes from the recommended manifest.
+      expect(row.displayName).toBe("@tintinweb/pi-subagents");
+    });
+
+    it("missing installedPath does not break enrichment", async () => {
+      wrapper.listInstalled.mockReturnValueOnce([
+        { source: "npm:weirdpkg", scope: "user", filtered: false },
+      ]);
+      const res = await app.inject({ method: "GET", url: "/api/packages/installed?scope=global" });
+      expect(res.statusCode).toBe(200);
+      const body = JSON.parse(res.body);
+      expect(body.data[0].version).toBeUndefined();
+      expect(body.data[0].displayName).toBe("weirdpkg");
     });
   });
 
@@ -169,4 +207,99 @@ describe("package-routes", () => {
       expect(body.data[0].source).toBe("npm:pi-doom");
     });
   });
+
+  describe("POST /api/packages/move", () => {
+    it("returns 202 with moveId + phases for npm source", async () => {
+      const res = await app.inject({
+        method: "POST",
+        url: "/api/packages/move",
+        payload: { entry: "npm:pi-doom", fromScope: "global", toScope: "local", toCwd: "/proj" },
+      });
+      expect(res.statusCode).toBe(202);
+      const body = JSON.parse(res.body);
+      expect(body.success).toBe(true);
+      expect(body.data.moveId).toBe("move-456");
+      expect(body.data.phases).toEqual(["install", "remove"]);
+      expect(wrapper.move).toHaveBeenCalledWith({
+        entry: "npm:pi-doom",
+        fromScope: "global",
+        fromCwd: undefined,
+        toScope: "local",
+        toCwd: "/proj",
+      });
+    });
+
+    it("returns settings-edit phase for relative-path source", async () => {
+      const res = await app.inject({
+        method: "POST",
+        url: "/api/packages/move",
+        payload: { entry: { source: "./vendor/x" }, fromScope: "local", fromCwd: "/proj", toScope: "global" },
+      });
+      expect(res.statusCode).toBe(202);
+      expect(JSON.parse(res.body).data.phases).toEqual(["settings-edit"]);
+    });
+
+    it("returns 400 when entry is missing", async () => {
+      const res = await app.inject({
+        method: "POST",
+        url: "/api/packages/move",
+        payload: { fromScope: "global", toScope: "local", toCwd: "/proj" },
+      });
+      expect(res.statusCode).toBe(400);
+      expect(JSON.parse(res.body).error).toMatch(/entry is required/);
+    });
+
+    it("returns 400 when fromScope/toScope missing", async () => {
+      const res = await app.inject({
+        method: "POST",
+        url: "/api/packages/move",
+        payload: { entry: "npm:foo" },
+      });
+      expect(res.statusCode).toBe(400);
+    });
+
+    it("returns 400 invalid_request from InvalidMoveRequestError", async () => {
+      wrapper.move = vi.fn().mockRejectedValue(new InvalidMoveRequestError("same scope"));
+      const res = await app.inject({
+        method: "POST",
+        url: "/api/packages/move",
+        payload: { entry: "npm:foo", fromScope: "global", toScope: "global" },
+      });
+      expect(res.statusCode).toBe(400);
+      expect(JSON.parse(res.body).code).toBe("invalid_request");
+    });
+
+    it("returns 400 unsupported_source_for_destination", async () => {
+      wrapper.move = vi.fn().mockRejectedValue(new UnsupportedSourceForDestinationError("need fromCwd"));
+      const res = await app.inject({
+        method: "POST",
+        url: "/api/packages/move",
+        payload: { entry: "..", fromScope: "local", toScope: "global" },
+      });
+      expect(res.statusCode).toBe(400);
+      expect(JSON.parse(res.body).code).toBe("unsupported_source_for_destination");
+    });
+
+    it("returns 409 already_at_destination", async () => {
+      wrapper.move = vi.fn().mockRejectedValue(new AlreadyAtDestinationError("npm:foo", "global"));
+      const res = await app.inject({
+        method: "POST",
+        url: "/api/packages/move",
+        payload: { entry: "npm:foo", fromScope: "local", fromCwd: "/p", toScope: "global" },
+      });
+      expect(res.statusCode).toBe(409);
+      expect(JSON.parse(res.body).code).toBe("already_at_destination");
+    });
+
+    it("returns 409 operation_in_flight", async () => {
+      wrapper.move = vi.fn().mockRejectedValue(new PackageOperationBusyError());
+      const res = await app.inject({
+        method: "POST",
+        url: "/api/packages/move",
+        payload: { entry: "npm:foo", fromScope: "global", toScope: "local", toCwd: "/p" },
+      });
+      expect(res.statusCode).toBe(409);
+      expect(JSON.parse(res.body).code).toBe("operation_in_flight");
+    });
+  });
 });

package/packages/server/src/__tests__/package-source-helpers.test.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from "vitest";
+import path from "node:path";
+import { parseSourceKind, computeIdentity } from "../package-source-helpers.js";
+
+describe("parseSourceKind", () => {
+	it.each([
+		["npm:foo", "npm"],
+		["npm:@scope/pkg", "npm"],
+		["npm:@scope/pkg@1.2.3", "npm"],
+		["npm:foo@^1.0.0", "npm"],
+	])("npm:* → npm  (%s)", (s, expected) => {
+		expect(parseSourceKind(s)).toBe(expected);
+	});
+
+	it.each([
+		["git:github.com/x/y", "git"],
+		["git:github.com/x/y@v1", "git"],
+		["git:git@github.com:x/y", "git"],
+		["git:git@github.com:x/y@v1.0.0", "git"],
+	])("git:* → git  (%s)", (s, expected) => {
+		expect(parseSourceKind(s)).toBe(expected);
+	});
+
+	it.each([
+		["https://github.com/x/y", "https"],
+		["https://github.com/x/y@v1", "https"],
+		["http://example.com/repo", "https"],
+		["ssh://git@github.com/x/y", "https"],
+		["git://github.com/x/y", "https"],
+	])("protocol url → https  (%s)", (s, expected) => {
+		expect(parseSourceKind(s)).toBe(expected);
+	});
+
+	it("/abs → abs-path", () => {
+		expect(parseSourceKind("/abs/path")).toBe("abs-path");
+	});
+
+	it.each([".", "..", "./foo", "../foo", "./foo/bar"])(
+		"%s → rel-path",
+		(s) => {
+			expect(parseSourceKind(s)).toBe("rel-path");
+		},
+	);
+
+	it("Windows abs path → abs-path", () => {
+		expect(parseSourceKind("C:\\abs\\path")).toBe("abs-path");
+		expect(parseSourceKind("C:/abs/path")).toBe("abs-path");
+	});
+});
+
+describe("computeIdentity", () => {
+	it("npm: identity = bare package name without version", () => {
+		expect(computeIdentity("npm:foo")).toBe("npm:foo");
+		expect(computeIdentity("npm:foo@1.2.3")).toBe("npm:foo");
+		expect(computeIdentity("npm:@scope/pkg")).toBe("npm:@scope/pkg");
+		expect(computeIdentity("npm:@scope/pkg@1.2.3")).toBe("npm:@scope/pkg");
+		expect(computeIdentity("npm:@scope/pkg@^1.0.0")).toBe("npm:@scope/pkg");
+	});
+
+	it("git: identity = repo url without ref", () => {
+		expect(computeIdentity("git:github.com/x/y")).toBe(
+			"git:github.com/x/y",
+		);
+		expect(computeIdentity("git:github.com/x/y@v1.2.3")).toBe(
+			"git:github.com/x/y",
+		);
+		expect(computeIdentity("git:git@github.com:x/y@v1")).toBe(
+			"git:git@github.com:x/y",
+		);
+	});
+
+	it("https/ssh url identity strips trailing @ref", () => {
+		expect(computeIdentity("https://github.com/x/y")).toBe(
+			"https://github.com/x/y",
+		);
+		expect(computeIdentity("https://github.com/x/y@v1")).toBe(
+			"https://github.com/x/y",
+		);
+		expect(computeIdentity("ssh://git@github.com/x/y@v1")).toBe(
+			"ssh://git@github.com/x/y",
+		);
+	});
+
+	it("absolute-path identity = the path itself", () => {
+		expect(computeIdentity("/abs/path")).toBe("/abs/path");
+	});
+
+	it("relative-path identity = path resolved against settingsDir", () => {
+		const cwd = "/proj/.pi";
+		expect(computeIdentity("..", cwd)).toBe(path.resolve("/proj/.pi/.."));
+		expect(computeIdentity("./foo", cwd)).toBe(
+			path.resolve("/proj/.pi/foo"),
+		);
+	});
+
+	it("relative-path without settingsDir falls back to literal", () => {
+		// Defensive: if we don't know the anchor, return a stable string
+		// that won't accidentally match any other entry's identity.
+		expect(computeIdentity("..")).toBe("..");
+	});
+});