@danypops/pi-packed 0.21.15 → 0.22.0

package/service/test/deploy-verify.test.ts

@@ -0,0 +1,168 @@
+/**
+ * deploy-verify.test.ts — the exact hand-diffing ceremony this module
+ * replaces: comparing a package's on-disk version at every known install
+ * location plus stale shadow copies, against an expected version.
+ */
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { findShadowCopies, formatDeployVerification, verifyDeploy } from "../src/packages/deploy-verify.ts";
+
+const roots: string[] = [];
+afterEach(() => {
+	for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function track(dir: string): string {
+	roots.push(dir);
+	return dir;
+}
+
+function writePackageAt(packageJsonPath: string, version: string): void {
+	mkdirSync(join(packageJsonPath, ".."), { recursive: true });
+	writeFileSync(packageJsonPath, JSON.stringify({ version }));
+}
+
+function piHomeWith(name: string, version: string | undefined): string {
+	const dir = track(mkdtempSync(join(tmpdir(), "packed-deploy-verify-")));
+	if (version !== undefined) writePackageAt(join(dir, "npm", "node_modules", name, "package.json"), version);
+	else mkdirSync(join(dir, "npm", "node_modules"), { recursive: true });
+	return dir;
+}
+
+describe("verifyDeploy", () => {
+	it("reports ok when the only known location matches the expected version and no shadow copy exists", () => {
+		const piHome = piHomeWith("@scope/pkg", "1.2.3");
+
+		const report = verifyDeploy(piHome, "@scope/pkg", "1.2.3");
+
+		expect(report.ok).toBe(true);
+		expect(report.expectedVersion).toBe("1.2.3");
+		expect(report.locations[0]!.upToDate).toBe(true);
+		expect(report.shadowCopies).toEqual([]);
+	});
+
+	it("defaults expectedVersion to whatever's resolved at the primary (Pi npm project) location when none is given", () => {
+		const piHome = piHomeWith("@scope/pkg", "2.0.0");
+
+		const report = verifyDeploy(piHome, "@scope/pkg");
+
+		expect(report.expectedVersion).toBe("2.0.0");
+		expect(report.ok).toBe(true);
+	});
+
+	it("reports not-ok and version-unknown when the package isn't found anywhere and no expected version was given", () => {
+		const piHome = piHomeWith("@scope/pkg", undefined);
+
+		const report = verifyDeploy(piHome, "@scope/other-pkg");
+
+		expect(report.expectedVersion).toBeUndefined();
+		expect(report.ok).toBe(false);
+	});
+
+	it("flags a location still on an older version as stale, not just missing", () => {
+		const piHome = piHomeWith("@scope/pkg", "1.0.0");
+		const fakeHome = track(mkdtempSync(join(tmpdir(), "packed-deploy-verify-home-")));
+		writePackageAt(join(fakeHome, ".cache", ".bun", "install", "global", "node_modules", "@scope/pkg", "package.json"), "0.9.0");
+
+		const report = verifyDeploy(piHome, "@scope/pkg", "1.0.0", fakeHome);
+
+		const bunLocation = report.locations.find((l) => l.label === "Bun global install cache")!;
+		expect(bunLocation.present).toBe(true);
+		expect(bunLocation.upToDate).toBe(false);
+		expect(bunLocation.version).toBe("0.9.0");
+		expect(report.ok).toBe(false);
+	});
+});
+
+describe("findShadowCopies — the exact layout ExecInstaller.reresolveDependencyTree() already fixes for the install path", () => {
+	it("finds a nested copy under an unscoped sibling package's own node_modules", () => {
+		const piHome = piHomeWith("shared", "2.0.0");
+		writePackageAt(join(piHome, "npm", "node_modules", "leaf", "node_modules", "shared", "package.json"), "1.0.0");
+
+		const shadows = findShadowCopies(piHome, "shared");
+
+		expect(shadows).toHaveLength(1);
+		expect(shadows[0]!.label).toBe("shadow copy under leaf");
+		expect(shadows[0]!.packageJsonPath).toBe(join(piHome, "npm", "node_modules", "leaf", "node_modules", "shared", "package.json"));
+	});
+
+	it("finds a nested copy one level under a scoped sibling package", () => {
+		const piHome = piHomeWith("shared", "2.0.0");
+		writePackageAt(join(piHome, "npm", "node_modules", "@scope", "leaf", "node_modules", "shared", "package.json"), "1.0.0");
+
+		const shadows = findShadowCopies(piHome, "shared");
+
+		expect(shadows).toHaveLength(1);
+		expect(shadows[0]!.label).toBe("shadow copy under @scope/leaf");
+	});
+
+	it("finds nothing when the tree is clean", () => {
+		const piHome = piHomeWith("shared", "2.0.0");
+		mkdirSync(join(piHome, "npm", "node_modules", "unrelated"), { recursive: true });
+
+		expect(findShadowCopies(piHome, "shared")).toEqual([]);
+	});
+
+	it("never descends into a shadow copy's own node_modules", () => {
+		const piHome = piHomeWith("shared", "2.0.0");
+		writePackageAt(join(piHome, "npm", "node_modules", "leaf", "node_modules", "shared", "package.json"), "1.0.0");
+		// A second-level nested copy inside the shadow copy itself -- out of scope.
+		writePackageAt(
+			join(piHome, "npm", "node_modules", "leaf", "node_modules", "shared", "node_modules", "shared", "package.json"),
+			"0.5.0",
+		);
+
+		const shadows = findShadowCopies(piHome, "shared");
+
+		expect(shadows).toHaveLength(1);
+	});
+
+	it("reports every shadow copy in verifyDeploy's own report, making the overall result not-ok regardless of the shadow's own version", () => {
+		const piHome = piHomeWith("shared", "2.0.0");
+		// The shadow copy itself happens to already match the expected version --
+		// still a real problem: two copies existing at all is what matters, not
+		// whether this particular one happens to agree right now.
+		writePackageAt(join(piHome, "npm", "node_modules", "leaf", "node_modules", "shared", "package.json"), "2.0.0");
+
+		const report = verifyDeploy(piHome, "shared", "2.0.0");
+
+		expect(report.shadowCopies).toHaveLength(1);
+		expect(report.shadowCopies[0]!.upToDate).toBe(true);
+		expect(report.ok).toBe(false);
+	});
+});
+
+describe("formatDeployVerification", () => {
+	it("renders a human-readable PASS report with no shadow copies", () => {
+		const piHome = piHomeWith("@scope/pkg", "1.2.3");
+		const report = verifyDeploy(piHome, "@scope/pkg", "1.2.3");
+
+		const text = formatDeployVerification(report, false);
+
+		expect(text).toContain("PASS");
+		expect(text).toContain("@scope/pkg@1.2.3");
+		expect(text).toContain("no shadow copies found");
+	});
+
+	it("renders valid JSON when json is true", () => {
+		const piHome = piHomeWith("@scope/pkg", "1.2.3");
+		const report = verifyDeploy(piHome, "@scope/pkg", "1.2.3");
+
+		const parsed = JSON.parse(formatDeployVerification(report, true));
+
+		expect(parsed.ok).toBe(true);
+		expect(parsed.packageName).toBe("@scope/pkg");
+	});
+
+	it("renders a human-readable FAIL report listing a stale location", () => {
+		const piHome = piHomeWith("@scope/pkg", "1.0.0");
+		const report = verifyDeploy(piHome, "@scope/pkg", "9.9.9");
+
+		const text = formatDeployVerification(report, false);
+
+		expect(text).toContain("FAIL");
+		expect(text).toContain("STALE (1.0.0)");
+	});
+});

package/service/test/doctor.test.ts

@@ -4,7 +4,7 @@ import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { AuthenticatedRpcClient } from "@danypops/vehicle-client/rpc-client";
-import { runDoctor } from "../src/adoption/doctor.ts";
+import { formatDoctorReport, runDoctor } from "../src/adoption/doctor.ts";
 import { createApp, type OperationInputs, type OperationName, type OperationOutputs } from "../src/daemon/service.ts";
 import type { Installer, PkgInfo, Registry, SearchPage } from "../src/packages/package.ts";
 
@@ -237,3 +237,106 @@ describeIfSandboxed("doctor.run (daemon RPC wiring)", () => {
 		expect(result.conflicts).toHaveLength(1);
 	});
 });
+
+describe("doctor.run — module freshness (a long-running daemon process's own stale in-memory dependency, see module-freshness.ts)", () => {
+	it("merges in moduleFreshness and flips ok:false when the injected checker reports a stale dependency", async () => {
+		const home = piHome([]);
+		const app = createApp({
+			reg: new NoopRegistry(),
+			inst: new NoopInstaller(),
+			token: "test-token",
+			stateDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-state-"))),
+			dataDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-data-"))),
+			piHome: home,
+			moduleFreshness: () => [
+				{ name: "stale-dep", loadedVersion: "1.0.0", currentVersion: "2.0.0", stale: true },
+				{ name: "fresh-dep", loadedVersion: "1.0.0", currentVersion: "1.0.0", stale: false },
+			],
+		});
+		const client = new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>("http://packed.test", "test-token", {
+			label: "Packed",
+			transport: (request) => app.fetch(request),
+		});
+
+		const result = await client.call("doctor.run", {});
+
+		expect(result.moduleFreshness).toEqual([
+			{ name: "stale-dep", loadedVersion: "1.0.0", currentVersion: "2.0.0", stale: true },
+			{ name: "fresh-dep", loadedVersion: "1.0.0", currentVersion: "1.0.0", stale: false },
+		]);
+		// The base doctor report (no extensions installed) would otherwise be ok:true.
+		expect(result.ok).toBe(false);
+	});
+
+	it("stays ok:true and reports no stale entries when the injected checker finds nothing stale", async () => {
+		const home = piHome([]);
+		const app = createApp({
+			reg: new NoopRegistry(),
+			inst: new NoopInstaller(),
+			token: "test-token",
+			stateDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-state-"))),
+			dataDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-data-"))),
+			piHome: home,
+			moduleFreshness: () => [{ name: "fresh-dep", loadedVersion: "1.0.0", currentVersion: "1.0.0", stale: false }],
+		});
+		const client = new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>("http://packed.test", "test-token", {
+			label: "Packed",
+			transport: (request) => app.fetch(request),
+		});
+
+		const result = await client.call("doctor.run", {});
+
+		expect(result.moduleFreshness).toEqual([{ name: "fresh-dep", loadedVersion: "1.0.0", currentVersion: "1.0.0", stale: false }]);
+		expect(result.ok).toBe(true);
+	});
+
+	it("omits moduleFreshness entirely when nothing injects it -- a standalone runDoctor() call has no snapshot to compare against", async () => {
+		const home = piHome([]);
+		const app = createApp({
+			reg: new NoopRegistry(),
+			inst: new NoopInstaller(),
+			token: "test-token",
+			stateDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-state-"))),
+			dataDir: track(mkdtempSync(join(tmpdir(), "packed-doctor-data-"))),
+			piHome: home,
+		});
+		const client = new AuthenticatedRpcClient<OperationName, OperationInputs, OperationOutputs>("http://packed.test", "test-token", {
+			label: "Packed",
+			transport: (request) => app.fetch(request),
+		});
+
+		const result = await client.call("doctor.run", {});
+
+		expect(result.moduleFreshness).toBeUndefined();
+		expect(result.ok).toBe(true);
+	});
+});
+
+describe("formatDoctorReport — module freshness rendering", () => {
+	const base = { ok: true, conflicts: [], extensions: [], scanned: 0, truncated: false, serviceUnits: [] };
+
+	it("prints a STALE_MODULE_CACHE line with an actionable restart hint for each stale entry, and nothing for a fresh one", () => {
+		const text = formatDoctorReport(
+			{
+				...base,
+				ok: false,
+				moduleFreshness: [
+					{ name: "stale-dep", loadedVersion: "1.0.0", currentVersion: "2.0.0", stale: true },
+					{ name: "fresh-dep", loadedVersion: "1.0.0", currentVersion: "1.0.0", stale: false },
+				],
+			},
+			false,
+		);
+
+		expect(text).toContain("STALE_MODULE_CACHE stale-dep");
+		expect(text).toContain("loaded 1.0.0 at startup");
+		expect(text).toContain("2.0.0 is now on disk");
+		expect(text).toContain("systemctl --user restart pi-packed.service");
+		expect(text).not.toContain("fresh-dep");
+	});
+
+	it("prints nothing extra when moduleFreshness is absent or empty", () => {
+		expect(formatDoctorReport(base, false)).not.toContain("STALE_MODULE_CACHE");
+		expect(formatDoctorReport({ ...base, moduleFreshness: [] }, false)).not.toContain("STALE_MODULE_CACHE");
+	});
+});

package/service/test/fixtures/install-validation/convention-only-package/extensions/index.ts

@@ -0,0 +1,3 @@
+export default function conventionOnlyFixtureExtension(pi: { registerCommand: (name: string, def: unknown) => void }) {
+	pi.registerCommand("convention-only-fixture", { description: "registers cleanly", handler: async () => {} });
+}

package/service/test/fixtures/install-validation/convention-only-package/package.json

@@ -0,0 +1,5 @@
+{
+	"name": "packed-install-validation-fixture-convention-only",
+	"version": "1.0.0",
+	"private": true
+}

package/service/test/install-validation.test.ts

@@ -21,6 +21,7 @@ const FIXTURES = join(__dirname, "fixtures/install-validation");
 const HEALTHY = join(FIXTURES, "healthy-package");
 const BROKEN = join(FIXTURES, "broken-package");
 const NO_MANIFEST = join(FIXTURES, "no-manifest-package");
+const CONVENTION_ONLY = join(FIXTURES, "convention-only-package");
 const DEP_PACKAGE = join(FIXTURES, "dep-package");
 
 const roots: string[] = [];
@@ -96,10 +97,22 @@ describe("HeadlessInstallValidator (real npm pack + tar extraction, no mocking)"
 		expect(result).toEqual({ ok: true, source: "git:github.com/u/r@main", extensions: [] });
 	});
 
-	it("passes a package with no pi.extensions -- most npm packages, nothing to validate", async () => {
+	it("refuses a package with no pi manifest and no convention resource directory -- not a Pi package (the is-number/is-buffer shape)", async () => {
 		const validator = new HeadlessInstallValidator();
 		const result = await validator.validate(`npm:${NO_MANIFEST}`);
+		expect(result.ok).toBe(false);
+		expect(result.extensions).toEqual([]);
+		expect(result.message).toContain("not a Pi package");
+	}, 20_000);
+
+	it("passes a package with no pi manifest but a real convention extensions/ directory", async () => {
+		const validator = new HeadlessInstallValidator();
+		const result = await validator.validate(`npm:${CONVENTION_ONLY}`);
 		expect(result.ok).toBe(true);
+		// Convention-discovered extensions (no pi.extensions manifest entry) are
+		// not headless load-checked here -- only presence gates admission; the
+		// per-extension mock-pi-cli check only ever runs against manifest-
+		// declared pi.extensions entries.
 		expect(result.extensions).toEqual([]);
 	}, 20_000);
 

package/service/test/install.test.ts

@@ -159,6 +159,235 @@ describe("ExecInstaller.update() — honest reloadRequired despite pi's ambiguou
 	});
 });
 
+describe("ExecInstaller.update() — out-of-range update detection (confirmed live: a 0.x package past its own caret boundary reported a bare 'already up to date')", () => {
+	it("alreadyUpToDate but a real newer version exists outside the declared range: reports outOfRangeUpdateAvailable", async () => {
+		const scriptDir = track(mkdtempSync(join(tmpdir(), "packed-exec-bin-")));
+		const bin = writeFakePi(scriptDir); // no rewrite: `pi update` genuinely no-ops, bound by ^0.9.8
+		const npmBin = writeFakeNpm(scriptDir, join(scriptDir, "npm.log"));
+		const piHome = writePiHome({ "@scope/pkg": "0.9.8" });
+		const installer = new ExecInstaller(bin, piHome, undefined, npmBin, undefined, (name) =>
+			name === "@scope/pkg" ? "0.10.0" : undefined,
+		);
+
+		const outcome = await installer.update("npm:@scope/pkg@0.9.8");
+
+		expect(outcome.alreadyUpToDate).toBe(true);
+		expect(outcome.reloadRequired).toBe(false);
+		expect(outcome.outOfRangeUpdateAvailable).toBe("0.10.0");
+	});
+
+	it("alreadyUpToDate and genuinely current against the mirror too: no outOfRangeUpdateAvailable", async () => {
+		const scriptDir = track(mkdtempSync(join(tmpdir(), "packed-exec-bin-")));
+		const bin = writeFakePi(scriptDir);
+		const npmBin = writeFakeNpm(scriptDir, join(scriptDir, "npm.log"));
+		const piHome = writePiHome({ plain: "0.5.0" });
+		const installer = new ExecInstaller(bin, piHome, undefined, npmBin, undefined, () => "0.5.0");
+
+		const outcome = await installer.update("npm:plain");
+
+		expect(outcome.alreadyUpToDate).toBe(true);
+		expect(outcome.outOfRangeUpdateAvailable).toBeUndefined();
+	});
+
+	it("no latestOf wired in at all: behaves exactly as before (no cross-check attempted)", async () => {
+		const scriptDir = track(mkdtempSync(join(tmpdir(), "packed-exec-bin-")));
+		const bin = writeFakePi(scriptDir);
+		const npmBin = writeFakeNpm(scriptDir, join(scriptDir, "npm.log"));
+		const piHome = writePiHome({ "@scope/pkg": "0.9.8" });
+		const installer = new ExecInstaller(bin, piHome, undefined, npmBin);
+
+		const outcome = await installer.update("npm:@scope/pkg@0.9.8");
+
+		expect(outcome.alreadyUpToDate).toBe(true);
+		expect(outcome.outOfRangeUpdateAvailable).toBeUndefined();
+	});
+
+	it("a real version change happened: never reports outOfRangeUpdateAvailable even if the mirror knows a still-newer version", async () => {
+		const scriptDir = track(mkdtempSync(join(tmpdir(), "packed-exec-bin-")));
+		const piHome = writePiHome({ plain: "0.5.0" });
+		const bin = writeFakePi(scriptDir, { piHome, name: "plain", newVersion: "0.6.0" });
+		const npmBin = writeFakeNpm(scriptDir, join(scriptDir, "npm.log"));
+		const installer = new ExecInstaller(bin, piHome, undefined, npmBin, undefined, () => "0.7.0");
+
+		const outcome = await installer.update("npm:plain");
+
+		expect(outcome.alreadyUpToDate).toBe(false);
+		expect(outcome.reloadRequired).toBe(true);
+		expect(outcome.outOfRangeUpdateAvailable).toBeUndefined();
+	});
+});
+
+/**
+ * A real, general-purpose fake `pi` binary for replace() tests -- unlike
+ * writeFakePi/writeFakeNpm above (each tailored to one specific pre-baked
+ * rewrite), this one genuinely implements `install <source>`/`remove
+ * <source>` against a real piHome: writes/removes the real
+ * node_modules/<name>/package.json entry AND the real settings.json
+ * packages[] entry, exactly like the two-step remove+install sequence
+ * replace() actually drives. A plain bun script (not bash) so exact-pin
+ * name/version parsing (scoped packages, the LAST "@" only) is real JS,
+ * not fragile shell string splitting.
+ */
+function writeFakeReplacePi(dir: string, piHome: string, options: { failInstallFor?: string } = {}): string {
+	const script = join(dir, "fake-replace-pi");
+	const body = `
+const piHome = ${JSON.stringify(piHome)};
+const failInstallFor = ${JSON.stringify(options.failInstallFor ?? null)};
+const fs = require("node:fs");
+const path = require("node:path");
+
+function bareName(source) {
+	const spec = source.startsWith("npm:") ? source.slice(4) : source;
+	const at = spec.lastIndexOf("@");
+	return at > 0 ? spec.slice(0, at) : spec;
+}
+function versionOf(source) {
+	const spec = source.startsWith("npm:") ? source.slice(4) : source;
+	const at = spec.lastIndexOf("@");
+	return at > 0 ? spec.slice(at + 1) : undefined;
+}
+function readSettings() {
+	try {
+		return JSON.parse(fs.readFileSync(path.join(piHome, "settings.json"), "utf8"));
+	} catch {
+		return { packages: [] };
+	}
+}
+function writeSettings(settings) {
+	fs.writeFileSync(path.join(piHome, "settings.json"), JSON.stringify(settings, null, 2));
+}
+function entrySource(entry) {
+	return typeof entry === "string" ? entry : entry && typeof entry === "object" ? entry.source : undefined;
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+const args = rest.filter((a) => a !== "-l");
+const source = args[args.length - 1];
+const name = bareName(source);
+
+if (cmd === "install") {
+	if (failInstallFor && source === failInstallFor) {
+		process.stderr.write("simulated install failure for " + source + "\\n");
+		process.exit(1);
+	}
+	const version = versionOf(source) ?? "0.0.0";
+	const pkgDir = path.join(piHome, "npm", "node_modules", name);
+	fs.mkdirSync(pkgDir, { recursive: true });
+	fs.writeFileSync(path.join(pkgDir, "package.json"), JSON.stringify({ name, version }));
+	const settings = readSettings();
+	const packages = (settings.packages ?? []).filter((e) => bareName(entrySource(e) ?? "") !== name);
+	packages.push(source);
+	writeSettings({ ...settings, packages });
+	process.stdout.write("Installed " + source + "\\n");
+	process.exit(0);
+}
+if (cmd === "remove") {
+	const pkgDir = path.join(piHome, "npm", "node_modules", name);
+	fs.rmSync(pkgDir, { recursive: true, force: true });
+	const settings = readSettings();
+	const packages = (settings.packages ?? []).filter((e) => bareName(entrySource(e) ?? "") !== name);
+	writeSettings({ ...settings, packages });
+	process.stdout.write("Removed " + source + "\\n");
+	process.exit(0);
+}
+process.stderr.write("unsupported command: " + cmd + "\\n");
+process.exit(1);
+`;
+	writeFileSync(script, `#!/usr/bin/env bun\n${body}`);
+	chmodSync(script, 0o755);
+	return script;
+}
+
+describe("ExecInstaller.update({ target }) — the supervised replace() workflow for moving an exact pin", () => {
+	function setup(options: { failInstallFor?: string } = {}) {
+		const scriptDir = track(mkdtempSync(join(tmpdir(), "packed-replace-bin-")));
+		const piHome = writePiHome();
+		mkdirSync(piHome, { recursive: true });
+		writeFileSync(join(piHome, "settings.json"), JSON.stringify({ packages: [] }));
+		const bin = writeFakeReplacePi(scriptDir, piHome, options);
+		const npmBin = writeFakeNpm(scriptDir, join(scriptDir, "npm.log"));
+		const validator = { validate: async (source: string) => ({ ok: true as const, source, extensions: [] }) };
+		const installer = new ExecInstaller(bin, piHome, validator, npmBin);
+		return { piHome, installer };
+	}
+
+	function configurePinned(piHome: string, entry: unknown): void {
+		writeFileSync(join(piHome, "settings.json"), JSON.stringify({ packages: [entry] }));
+	}
+
+	it("replaces an exact pin end to end: removes the old entry, installs the new one, verifies both postconditions", async () => {
+		const { piHome, installer } = setup();
+		configurePinned(piHome, "npm:@scope/pkg@1.0.0");
+		mkdirSync(join(piHome, "npm", "node_modules", "@scope", "pkg"), { recursive: true });
+		writeFileSync(join(piHome, "npm", "node_modules", "@scope", "pkg", "package.json"), JSON.stringify({ version: "1.0.0" }));
+
+		const outcome = await installer.update("npm:@scope/pkg@1.0.0", { target: "npm:@scope/pkg@2.0.0" });
+
+		expect(outcome.replaced).toBe(true);
+		expect(outcome.before).toEqual({ source: "npm:@scope/pkg@1.0.0", version: "1.0.0" });
+		expect(outcome.after).toEqual({ source: "npm:@scope/pkg@2.0.0", version: "2.0.0" });
+		expect(outcome.reloadRequired).toBe(true);
+		expect(outcome.alreadyUpToDate).toBe(false);
+		expect(outcome.currentVersion).toBe("2.0.0");
+		const settings = JSON.parse(readFileSync(join(piHome, "settings.json"), "utf8"));
+		expect(settings.packages).toEqual(["npm:@scope/pkg@2.0.0"]);
+	});
+
+	it("rejects a target that names a different package, before mutating anything", async () => {
+		const { piHome, installer } = setup();
+		configurePinned(piHome, "npm:@scope/pkg@1.0.0");
+
+		await expect(installer.update("npm:@scope/pkg@1.0.0", { target: "npm:@scope/other@1.0.0" })).rejects.toThrow(
+			/same package/,
+		);
+		const settings = JSON.parse(readFileSync(join(piHome, "settings.json"), "utf8"));
+		expect(settings.packages).toEqual(["npm:@scope/pkg@1.0.0"]);
+	});
+
+	it("rolls back to the original pin when installing the new target fails", async () => {
+		const { piHome, installer } = setup({ failInstallFor: "npm:@scope/pkg@2.0.0" });
+		configurePinned(piHome, "npm:@scope/pkg@1.0.0");
+		mkdirSync(join(piHome, "npm", "node_modules", "@scope", "pkg"), { recursive: true });
+		writeFileSync(join(piHome, "npm", "node_modules", "@scope", "pkg", "package.json"), JSON.stringify({ version: "1.0.0" }));
+
+		await expect(installer.update("npm:@scope/pkg@1.0.0", { target: "npm:@scope/pkg@2.0.0" })).rejects.toThrow(
+			/rolled back to npm:@scope\/pkg@1\.0\.0/,
+		);
+		const settings = JSON.parse(readFileSync(join(piHome, "settings.json"), "utf8"));
+		expect(settings.packages).toEqual(["npm:@scope/pkg@1.0.0"]);
+		expect(JSON.parse(readFileSync(join(piHome, "npm", "node_modules", "@scope", "pkg", "package.json"), "utf8")).version).toBe("1.0.0");
+	});
+
+	it("preserves the old entry's own filter overrides onto the freshly-installed replacement entry", async () => {
+		const { piHome, installer } = setup();
+		configurePinned(piHome, { source: "npm:@scope/pkg@1.0.0", extensions: ["-extensions/one.ts"] });
+		mkdirSync(join(piHome, "npm", "node_modules", "@scope", "pkg"), { recursive: true });
+		writeFileSync(join(piHome, "npm", "node_modules", "@scope", "pkg", "package.json"), JSON.stringify({ version: "1.0.0" }));
+
+		await installer.update("npm:@scope/pkg@1.0.0", { target: "npm:@scope/pkg@2.0.0" });
+
+		const settings = JSON.parse(readFileSync(join(piHome, "settings.json"), "utf8"));
+		expect(settings.packages).toEqual([{ source: "npm:@scope/pkg@2.0.0", extensions: ["-extensions/one.ts"] }]);
+	});
+
+	it("reports pinnedSourceRequiresTarget on a plain update() call against an unchanged exact pin, with no target given", async () => {
+		// This scenario needs the ORIGINAL "always prints Updated, changes
+		// nothing for a pin" fake pi -- writeFakeReplacePi only implements
+		// install/remove, not update --extension.
+		const scriptDir = track(mkdtempSync(join(tmpdir(), "packed-replace-bin-")));
+		const piHome = writePiHome({ "@scope/pkg": "1.0.0" });
+		const bin = writeFakePi(scriptDir);
+		const npmBin = writeFakeNpm(scriptDir, join(scriptDir, "npm.log"));
+		const plainInstaller = new ExecInstaller(bin, piHome, undefined, npmBin);
+
+		const outcome = await plainInstaller.update("npm:@scope/pkg@1.0.0");
+
+		expect(outcome.pinned).toBe(true);
+		expect(outcome.alreadyUpToDate).toBe(true);
+		expect(outcome.pinnedSourceRequiresTarget).toBe(true);
+	});
+});
+
 describe("ExecInstaller — forces full dependency re-resolution, not just the target's own subtree", () => {
 	it("update() fixes a stale root-level sibling that the targeted pi update never touched", async () => {
 		const scriptDir = track(mkdtempSync(join(tmpdir(), "packed-exec-bin-")));