@danypops/pi-packed 0.21.15 → 0.22.0

package/service/src/packages/deploy-verify.ts

@@ -0,0 +1,151 @@
+/**
+ * deploy-verify.ts — answers "did a publish/install actually land
+ * everywhere it should have" as one deterministic check, instead of the
+ * hand-diffing ceremony repeated after nearly every @danypops/* publish:
+ * comparing a package's on-disk version at every known install location
+ * (Pi's own npm project, Bun's global install cache) against an expected
+ * version, plus scanning for a stale nested node_modules "shadow" copy one
+ * level below another installed package's own node_modules -- exactly the
+ * layout ExecInstaller.reresolveDependencyTree() already fixes for the
+ * install path (see install.ts), surfaced here read-only for diagnosis.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export interface InstallLocation {
+	readonly label: string;
+	readonly packageJsonPath: string;
+}
+
+export interface LocationStatus extends InstallLocation {
+	/** undefined when the location has no readable package.json at all. */
+	readonly version?: string;
+	readonly mtimeMs?: number;
+	readonly present: boolean;
+	/** Only meaningful when present -- false whenever present is false too. */
+	readonly upToDate: boolean;
+}
+
+export interface DeployVerification {
+	readonly packageName: string;
+	readonly expectedVersion?: string;
+	readonly locations: readonly LocationStatus[];
+	readonly shadowCopies: readonly LocationStatus[];
+	/**
+	 * false when expectedVersion is unknown, a *present* known location is
+	 * behind it, or a shadow copy exists at all (a shadow copy is always a
+	 * problem regardless of its own version -- it can shadow the correct
+	 * top-level install for whichever importer's own node_modules walk
+	 * reaches it first). A location simply being absent (e.g. this package
+	 * was never installed via `bun install -g`) never fails this by
+	 * itself -- only a present-but-stale copy does.
+	 */
+	readonly ok: boolean;
+}
+
+function readVersionAndMtime(packageJsonPath: string): { version?: string; mtimeMs?: number } {
+	try {
+		const mtimeMs = statSync(packageJsonPath).mtimeMs;
+		const pkg = JSON.parse(readFileSync(packageJsonPath, "utf8")) as { version?: unknown };
+		return { version: typeof pkg.version === "string" ? pkg.version : undefined, mtimeMs };
+	} catch {
+		return {};
+	}
+}
+
+function statusOf(location: InstallLocation, expectedVersion: string | undefined): LocationStatus {
+	const { version, mtimeMs } = readVersionAndMtime(location.packageJsonPath);
+	return { ...location, version, mtimeMs, present: version !== undefined, upToDate: version !== undefined && version === expectedVersion };
+}
+
+/** Every location Packed itself installs an npm-sourced package into --
+ * Pi's own npm project (piHome/npm) and Bun's own global install cache
+ * (used by `bun install -g`/bunx-adjacent flows, not something Packed
+ * writes to itself, but a real place a stale copy can quietly linger).
+ * `home` defaults to the real home directory; injectable so a test never
+ * has to read or write outside its own tmpdir fixture. */
+export function standardInstallLocations(piHome: string, packageName: string, home: string = homedir()): InstallLocation[] {
+	return [
+		{ label: "Pi npm project", packageJsonPath: join(piHome, "npm", "node_modules", packageName, "package.json") },
+		{
+			label: "Bun global install cache",
+			packageJsonPath: join(home, ".cache", ".bun", "install", "global", "node_modules", packageName, "package.json"),
+		},
+	];
+}
+
+/** Bounded to Pi npm project's own direct children (and one level into a
+ * scope directory) -- the exact shape ExecInstaller.reresolveDependencyTree()
+ * fixes for the install path: a sibling package's own node_modules holding
+ * a nested copy of a shared dependency that a targeted `pi update`/`pi
+ * install` never reaches, only a full-tree `npm install` does. Never
+ * descends into a shadow copy's own node_modules -- one level is the real,
+ * confirmed-live shape; deeper nesting is npm's own problem to dedupe. */
+export function findShadowCopies(piHome: string, packageName: string): InstallLocation[] {
+	const npmNodeModulesDir = join(piHome, "npm", "node_modules");
+	const found: InstallLocation[] = [];
+	let entries: string[];
+	try {
+		entries = readdirSync(npmNodeModulesDir);
+	} catch {
+		return found;
+	}
+	for (const entry of entries) {
+		if (entry === packageName || entry.startsWith(".")) continue;
+		const entryPath = join(npmNodeModulesDir, entry);
+		let isDirectory: boolean;
+		try {
+			isDirectory = statSync(entryPath).isDirectory();
+		} catch {
+			continue;
+		}
+		if (!isDirectory) continue;
+		if (entry.startsWith("@")) {
+			let scoped: string[];
+			try {
+				scoped = readdirSync(entryPath);
+			} catch {
+				continue;
+			}
+			for (const sub of scoped) {
+				const nested = join(entryPath, sub, "node_modules", packageName, "package.json");
+				if (existsSync(nested)) found.push({ label: `shadow copy under ${entry}/${sub}`, packageJsonPath: nested });
+			}
+			continue;
+		}
+		const nested = join(entryPath, "node_modules", packageName, "package.json");
+		if (existsSync(nested)) found.push({ label: `shadow copy under ${entry}`, packageJsonPath: nested });
+	}
+	return found;
+}
+
+/**
+ * `expectedVersion` defaults to whatever's resolved at Pi's own npm
+ * project -- the natural "it was just installed/updated there, does every
+ * OTHER known location and shadow copy agree" question this exists to
+ * answer without a network round-trip. Pass one explicitly (e.g. the
+ * version a publish just produced) to check against that instead.
+ */
+export function verifyDeploy(piHome: string, packageName: string, expectedVersion?: string, home: string = homedir()): DeployVerification {
+	const locations0 = standardInstallLocations(piHome, packageName, home);
+	const resolvedExpected = expectedVersion ?? readVersionAndMtime(locations0[0]!.packageJsonPath).version;
+	const locations = locations0.map((location) => statusOf(location, resolvedExpected));
+	const shadowCopies = findShadowCopies(piHome, packageName).map((location) => statusOf(location, resolvedExpected));
+	const ok = resolvedExpected !== undefined && locations.every((l) => !l.present || l.upToDate) && shadowCopies.length === 0;
+	return { packageName, expectedVersion: resolvedExpected, locations, shadowCopies, ok };
+}
+
+export function formatDeployVerification(report: DeployVerification, json: boolean): string {
+	if (json) return `${JSON.stringify(report)}\n`;
+	let out = `${report.ok ? "PASS" : "FAIL"} — ${report.packageName}${report.expectedVersion ? `@${report.expectedVersion}` : " (version unknown -- not found at the primary location either)"}\n`;
+	for (const location of report.locations) {
+		const state = !location.present ? "MISSING" : location.upToDate ? "ok" : `STALE (${location.version})`;
+		out += `  ${state.padEnd(16)} ${location.label} (${location.packageJsonPath})\n`;
+	}
+	for (const shadow of report.shadowCopies) {
+		out += `  SHADOW COPY      ${shadow.label} at ${shadow.version ?? "unknown version"} (${shadow.packageJsonPath})\n`;
+	}
+	if (report.shadowCopies.length === 0) out += "  no shadow copies found\n";
+	return out;
+}

package/service/src/packages/install.ts

@@ -8,8 +8,10 @@ import {
 	type InstallValidationResult,
 	type InstallValidator,
 } from "../adoption/install-validation.ts";
+import { applyEntryFilters, captureEntryFilters, resolveToggleSettingsPath } from "./resources.ts";
 import { createLogger } from "../shared/log.ts";
-import { defaultPiHome, isPinnedNpmSource, readResolvedVersion } from "./installed.ts";
+import { defaultPiHome, isPinnedNpmSource, npmPackageName, readPackageDeclarations, readResolvedVersion } from "./installed.ts";
+import { isNewer } from "./package.ts";
 import type { Installer, UpdateOutcome } from "./package.ts";
 
 function round1(ms: number): number {
@@ -44,6 +46,14 @@ export class ExecInstaller implements Installer {
 		 * against a real daemon instead of guessing from wall-clock totals alone.
 		 */
 		private readonly logger: Logger = createLogger("install"),
+		/**
+		 * Optional real registry-mirror lookup (see daemon/watcher.ts's own
+		 * checkUpdates(), which this shares its cross-check logic with via
+		 * package.ts's isNewer) -- undefined by default so every existing
+		 * caller/test keeps its old "already up to date means nothing to
+		 * report" behavior unless a daemon explicitly wires its own mirror in.
+		 */
+		private readonly latestOf?: (name: string) => string | undefined,
 	) {}
 
 	private async run(args: string[]): Promise<string> {
@@ -141,7 +151,8 @@ export class ExecInstaller implements Installer {
 		return this.run(["remove", ...(options?.local ? ["-l"] : []), source]);
 	}
 
-	async update(source: string, _options?: { approved?: boolean; local?: boolean }): Promise<UpdateOutcome> {
+	async update(source: string, options?: { approved?: boolean; local?: boolean; target?: string }): Promise<UpdateOutcome> {
+		if (options?.target) return this.replace(source, options.target, options);
 		const t0 = performance.now();
 		const pinned = isPinnedNpmSource(source);
 		const previousVersion = readResolvedVersion(this.piHome, source);
@@ -165,6 +176,112 @@ export class ExecInstaller implements Installer {
 		// have changed" signal instead of falsely claiming it didn't.
 		const knowsBoth = previousVersion !== undefined && currentVersion !== undefined;
 		const changed = !knowsBoth || previousVersion !== currentVersion;
-		return { output, reloadRequired: changed, alreadyUpToDate: !changed, pinned, previousVersion, currentVersion };
+		const alreadyUpToDate = !changed;
+		// Only worth cross-checking when there's actually a "nothing changed"
+		// conclusion to double-check, a real mirror lookup was wired in, and
+		// there's a real bare npm name + resolved version to compare against.
+		const name = alreadyUpToDate && this.latestOf ? npmPackageName(source) : undefined;
+		const latest = name && currentVersion ? this.latestOf?.(name) : undefined;
+		const outOfRangeUpdateAvailable = latest && currentVersion && isNewer(latest, currentVersion) ? latest : undefined;
+		return {
+			output,
+			reloadRequired: changed,
+			alreadyUpToDate,
+			pinned,
+			previousVersion,
+			currentVersion,
+			...(outOfRangeUpdateAvailable ? { outOfRangeUpdateAvailable } : {}),
+			// A plain update() with no target can never move an exact pin --
+			// `pi update --extension` itself intentionally skips it (npm's own
+			// documented behavior for a versioned spec). alreadyUpToDate/pinned
+			// above are already an honest, non-"false success" result; this adds
+			// an unambiguous machine-readable nudge toward options.target instead
+			// of a caller having to infer "pinned AND alreadyUpToDate means stuck"
+			// itself. See replace() for the actual supervised pin-move workflow.
+			...(pinned && alreadyUpToDate ? { pinnedSourceRequiresTarget: true } : {}),
+		};
+	}
+
+	/**
+	 * The supervised "move a pin" workflow `pi update --extension` can never
+	 * perform by itself (it intentionally skips an exact pin) -- see the
+	 * linked research doc (pinned-package-update-behavior-and-safe-
+	 * replacement-research): a bare `pi install <newSource>` does not
+	 * rewrite an already-configured entry for the same package, it requires
+	 * an explicit remove-then-install sequence. Reuses install()/remove()
+	 * (the same supported, already-tested primitives) rather than
+	 * hand-rolling new subprocess calls, so validation/reresolve/timing
+	 * behave identically to every other mutation.
+	 *
+	 * Order of operations: identity check (never touches disk on mismatch)
+	 * -> capture `fromSource`'s own filter overrides (extensions/skills/
+	 * prompts/themes) so remove() doesn't silently discard them -> remove
+	 * `fromSource` -> install `toSource`, rolling back to `fromSource` on
+	 * failure -> re-apply the captured filters onto the new entry -> verify
+	 * BOTH postconditions (installed: readResolvedVersion; configured:
+	 * present in settings.json) before reporting success.
+	 */
+	private async replace(fromSource: string, toSource: string, options?: { approved?: boolean; local?: boolean }): Promise<UpdateOutcome> {
+		const fromName = npmPackageName(fromSource);
+		const toName = npmPackageName(toSource);
+		if (!fromName || !toName || fromName !== toName) {
+			throw new Error(`replace target must be the same package as the configured source: ${fromSource} -> ${toSource}`);
+		}
+		const settingsPath = resolveToggleSettingsPath(this.piHome);
+		const before = { source: fromSource, version: readResolvedVersion(this.piHome, fromSource) };
+		const filters = captureEntryFilters(settingsPath, fromSource);
+
+		let removeOutput: string;
+		try {
+			removeOutput = await this.remove(fromSource, options);
+		} catch (e) {
+			throw new Error(`replace failed removing ${fromSource}: ${e instanceof Error ? e.message : String(e)}`);
+		}
+
+		let installOutput: string;
+		try {
+			installOutput = await this.install(toSource, options);
+		} catch (installError) {
+			const installMessage = installError instanceof Error ? installError.message : String(installError);
+			let rollback: NonNullable<UpdateOutcome["rollback"]>;
+			try {
+				await this.install(fromSource, options);
+				rollback = { attempted: true, ok: true };
+			} catch (rollbackError) {
+				rollback = {
+					attempted: true,
+					ok: false,
+					message: rollbackError instanceof Error ? rollbackError.message : String(rollbackError),
+				};
+			}
+			const rollbackNote = rollback.ok
+				? `rolled back to ${fromSource}`
+				: `ROLLBACK TO ${fromSource} ALSO FAILED: ${rollback.message} -- ${fromName} may now be uninstalled entirely, reinstall manually`;
+			throw new Error(`replace failed installing ${toSource}: ${installMessage} (${rollbackNote})`);
+		}
+
+		await applyEntryFilters(settingsPath, toSource, filters);
+
+		const afterVersion = readResolvedVersion(this.piHome, toSource);
+		const configuredAfter = readPackageDeclarations(this.piHome).includes(toSource);
+		if (!configuredAfter) {
+			// install() itself reported success, but settings.json doesn't show
+			// toSource configured -- a real postcondition failure, not merely a
+			// version mismatch. Never claim success on an unverified replace.
+			throw new Error(`replace installed ${toSource} but settings.json does not show it configured -- verify manually before retrying`);
+		}
+		const after = { source: toSource, version: afterVersion };
+		const changed = before.version !== after.version || before.source !== after.source;
+		return {
+			output: `${removeOutput}\n${installOutput}`.trim(),
+			reloadRequired: changed,
+			alreadyUpToDate: !changed,
+			pinned: isPinnedNpmSource(toSource),
+			previousVersion: before.version,
+			currentVersion: after.version,
+			replaced: true,
+			before,
+			after,
+		};
 	}
 }

package/service/src/packages/package.ts

@@ -11,6 +11,27 @@
 // itself stays a pure port: nothing here creates a runtime dependency on install-validation.ts's
 // own npm-pack/tar/subprocess machinery.
 import type { InstallValidationResult } from "../adoption/install-validation.ts";
+import { gt, valid } from "semver";
+
+/**
+ * True drift only: `latest` is a real semver step *ahead* of `have`, never
+ * merely different from it. A plain !== check cannot distinguish "have is
+ * behind latest" from "have is already ahead of a stale/wrong latest" --
+ * confirmed live via the watcher's own version of this bug: an installed
+ * package whose version had already passed the daemon's mirrored
+ * dist-tags.latest kept showing a permanent, un-clearable "update
+ * available" badge pointing at an *older* version. Falls back to the old
+ * inequality only when either side isn't parseable semver (a git ref, a
+ * literal "latest" tag, etc.) -- those aren't comparable at all, so
+ * "different" is the only signal left. Lives here (not watcher.ts, its
+ * original home) so both the daemon's watcher and ExecInstaller.update()'s
+ * own out-of-range check share one implementation without packages/
+ * reaching into daemon/ (the dependency already runs the other way).
+ */
+export function isNewer(latest: string, have: string): boolean {
+	if (valid(latest, { loose: true }) && valid(have, { loose: true })) return gt(latest, have, { loose: true });
+	return latest !== have;
+}
 
 export type PackageVerification = "keyword-only" | "manifest" | "conventional";
 
@@ -108,13 +129,58 @@ export interface UpdateOutcome {
 	pinned: boolean;
 	previousVersion?: string;
 	currentVersion?: string;
+	/**
+	 * Set only when alreadyUpToDate is true AND a real registry version
+	 * newer than currentVersion exists outside the source's own declared
+	 * caret/range -- confirmed live: a 0.x package (e.g. ^0.9.8) that
+	 * crossed its own minor boundary (0.10.0 published) reported a bare
+	 * "already up to date" with no clue a newer version existed at all.
+	 * `pi update --extension` is itself bound by the declared range, so
+	 * "nothing changed" alone can't distinguish "genuinely current" from
+	 * "current within a range that's now stale" -- this cross-checks
+	 * against the same registry-mirror source of truth checkUpdates()
+	 * already uses, independent of the declared range.
+	 */
+	outOfRangeUpdateAvailable?: string;
+	/**
+	 * True only when update() was called on an exact npm pin with no
+	 * options.target -- `pi update --extension` intentionally leaves an
+	 * exact pin unchanged (npm's own documented behavior for a versioned
+	 * spec), so alreadyUpToDate/pinned above are already an honest,
+	 * non-"false success" result. This is an additional stable,
+	 * unambiguous machine-readable signal (kept alongside those existing
+	 * fields for back-compat) that a caller wanting to actually MOVE the
+	 * pin should retry with options.target set -- see replaced/before/
+	 * after/rollback below.
+	 */
+	pinnedSourceRequiresTarget?: boolean;
+	/**
+	 * True when options.target was given and update() routed to the
+	 * supervised replace workflow (remove the old exact source, install
+	 * the new one, verify both configured and installed postconditions,
+	 * attempt rollback on failure) instead of `pi update --extension`.
+	 */
+	replaced?: boolean;
+	before?: { source: string; version?: string };
+	after?: { source: string; version?: string };
+	/** Present only on a replace failure -- whether restoring the original
+	 * source was attempted and whether that restoration itself succeeded. */
+	rollback?: { attempted: boolean; ok: boolean; message?: string };
 }
 
 /** Driven port: pi CLI mutations. */
 export interface Installer {
 	install(source: string, options?: { approved?: boolean; local?: boolean }): Promise<string>;
 	remove(source: string, options?: { approved?: boolean; local?: boolean }): Promise<string>;
-	update(source: string, options?: { approved?: boolean; local?: boolean }): Promise<UpdateOutcome>;
+	/**
+	 * `options.target`, when given, replaces `source` (an exact pin or not)
+	 * with `target` through a supervised remove+install workflow instead of
+	 * `pi update --extension` -- see ExecInstaller.update()'s own doc
+	 * comment and the linked research doc
+	 * (pinned-package-update-behavior-and-safe-replacement-research) for
+	 * why a plain `pi update` can never move an exact pin by itself.
+	 */
+	update(source: string, options?: { approved?: boolean; local?: boolean; target?: string }): Promise<UpdateOutcome>;
 	/**
 	 * Optional batch-oriented split of install(), for a caller installing several packages
 	 * together (see SetupManager.apply()) -- a single ad hoc install() still does all three

package/service/src/packages/resources.ts

@@ -201,3 +201,66 @@ export async function toggleResource(input: ToggleResourceInput): Promise<{ ok:
 	}
 	return { ok: true };
 }
+
+/**
+ * Captures a configured package entry's own filter overrides
+ * (extensions/skills/prompts/themes +/-path arrays -- see toggleResource's
+ * own doc comment) before a replace/update-to-target operation removes it
+ * outright: a bare `pi remove` + `pi install` sequence to bump a pinned
+ * version replaces the WHOLE settings.json entry, silently reverting any
+ * per-resource enable/disable customization the user had configured back
+ * to the freshly-installed package's own defaults. undefined when the
+ * entry has no filter overrides at all (nothing to preserve) or isn't
+ * found (already removed, or never existed as a real entry).
+ */
+export function captureEntryFilters(settingsPath: string, source: string): Partial<Record<ResourceField, string[]>> | undefined {
+	const entry = readSettingsPackages(settingsPath).find((candidate) => candidate.source === source);
+	if (!entry) return undefined;
+	const filters: Partial<Record<ResourceField, string[]>> = {};
+	for (const field of RESOURCE_FIELDS) {
+		const value = entry[field];
+		if (value) filters[field] = value;
+	}
+	return Object.keys(filters).length > 0 ? filters : undefined;
+}
+
+/**
+ * Re-applies a previously captured set of filter overrides onto `source`'s
+ * own freshly-created package entry -- the other half of
+ * captureEntryFilters, restoring what a replace operation's remove step
+ * would otherwise have discarded. A no-op (never throws) when `filters` is
+ * undefined/empty, the settings file is unreadable, or `source`'s entry
+ * doesn't exist yet (e.g. the install step itself failed and never wrote
+ * one) -- there is nothing safe to merge a filter override onto in that
+ * case, and the caller's own install failure is already the real error to
+ * surface.
+ */
+export async function applyEntryFilters(
+	settingsPath: string,
+	source: string,
+	filters: Partial<Record<ResourceField, string[]>> | undefined,
+): Promise<boolean> {
+	if (!filters || Object.keys(filters).length === 0) return true; // nothing to preserve is not a failure
+	let settings: Record<string, unknown>;
+	try {
+		settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+	} catch {
+		return false;
+	}
+	const packages = Array.isArray(settings.packages) ? [...settings.packages] : [];
+	const index = packages.findIndex((raw) => parseEntry(raw)?.source === source);
+	if (index === -1) return false;
+	const merged: Record<string, unknown> =
+		typeof packages[index] === "string" ? { source: packages[index] } : { ...(packages[index] as Record<string, unknown>) };
+	for (const [field, value] of Object.entries(filters)) merged[field] = value;
+	packages[index] = merged;
+	try {
+		await atomicWriteJson(settingsPath, { ...settings, packages });
+		return true;
+	} catch {
+		// best-effort: the replace itself already succeeded, a filter-preservation
+		// write failure here is surfaced to the caller as a non-fatal detail, not
+		// a reason to report the whole replace as failed.
+		return false;
+	}
+}

package/service/src/public/client.ts

@@ -55,7 +55,7 @@ export interface PackedExtensionClient {
 	install(source: string, approved?: boolean): Promise<string>;
 	installService(source: string, approved?: boolean): Promise<{ output: string; spec?: ServiceSpecSummary }>;
 	remove(name: string, approved?: boolean): Promise<string>;
-	update(source: string, approved?: boolean): Promise<UpdateOutcome>;
+	update(source: string, approved?: boolean, target?: string): Promise<UpdateOutcome>;
 	setupPlan(manifestPath: string, prune?: boolean): Promise<SetupPlan>;
 	setupApply(manifestPath: string, approved?: boolean, prune?: boolean): Promise<SetupApplyResult>;
 	listResources(projectRoot?: string): Promise<{ global: PackageResources[]; project: PackageResources[] }>;
@@ -176,8 +176,8 @@ export class PackedClient implements PackedExtensionClient {
 		if (!result.ok) throw new Error(result.output);
 		return result.output;
 	}
-	async update(source: string, approved = false): Promise<UpdateOutcome> {
-		const result = await this.call("package.update", { source, approved });
+	async update(source: string, approved = false, target?: string): Promise<UpdateOutcome> {
+		const result = await this.call("package.update", { source, approved, target });
 		if (!result.ok) throw new Error(result.output);
 		return {
 			output: result.output,
@@ -186,6 +186,12 @@ export class PackedClient implements PackedExtensionClient {
 			pinned: result.pinned ?? false,
 			previousVersion: result.previousVersion,
 			currentVersion: result.currentVersion,
+			outOfRangeUpdateAvailable: result.outOfRangeUpdateAvailable,
+			pinnedSourceRequiresTarget: result.pinnedSourceRequiresTarget,
+			replaced: result.replaced,
+			before: result.before,
+			after: result.after,
+			rollback: result.rollback,
 		};
 	}
 	setupPlan(manifestPath: string, prune = false) {

package/service/src/public/protocol.ts

@@ -53,6 +53,12 @@ export interface UpdateOutcome {
 	pinned: boolean;
 	previousVersion?: string;
 	currentVersion?: string;
+	outOfRangeUpdateAvailable?: string;
+	pinnedSourceRequiresTarget?: boolean;
+	replaced?: boolean;
+	before?: { source: string; version?: string };
+	after?: { source: string; version?: string };
+	rollback?: { attempted: boolean; ok: boolean; message?: string };
 }
 export interface Diagnostic {
 	code: string;
@@ -141,7 +147,7 @@ export interface ExtensionOperationInputs {
 	"package.install": { source: string; approved?: boolean };
 	"package.install_service": { source: string; approved?: boolean };
 	"package.remove": { name: string; approved?: boolean };
-	"package.update": { source: string; approved?: boolean };
+	"package.update": { source: string; approved?: boolean; target?: string };
 	"setup.plan": { manifestPath: string; prune?: boolean };
 	"setup.apply": { manifestPath: string; approved?: boolean; prune?: boolean };
 	"resources.list": { projectRoot?: string };
@@ -165,6 +171,12 @@ export interface ExtensionOperationOutputs {
 		pinned?: boolean;
 		previousVersion?: string;
 		currentVersion?: string;
+		outOfRangeUpdateAvailable?: string;
+		pinnedSourceRequiresTarget?: boolean;
+		replaced?: boolean;
+		before?: { source: string; version?: string };
+		after?: { source: string; version?: string };
+		rollback?: { attempted: boolean; ok: boolean; message?: string };
 	};
 	"setup.plan": SetupPlan;
 	"setup.apply": SetupApplyResult;

package/service/test/cli.test.ts

@@ -59,9 +59,11 @@ class FakeInstaller implements Installer {
 		this.approved = options?.approved === true;
 		return `Removed ${source}`;
 	}
-	async update(source: string, options?: { approved?: boolean }): Promise<UpdateOutcome> {
+	gotTarget: string | undefined;
+	async update(source: string, options?: { approved?: boolean; target?: string }): Promise<UpdateOutcome> {
 		this.updated = source;
 		this.approved = options?.approved === true;
+		this.gotTarget = options?.target;
 		return {
 			output: `Updated ${source}`,
 			reloadRequired: true,
@@ -594,6 +596,52 @@ describe("CLI", () => {
 		});
 	});
 
+	it("update --to threads the replacement target through to the installer and reports it in both human and JSON output", async () => {
+		const d = deps({
+			inst: (() => {
+				const fake = new FakeInstaller();
+				fake.updateOutcome = {
+					replaced: true,
+					before: { source: "npm:@scope/pkg@1.0.0", version: "1.0.0" },
+					after: { source: "npm:@scope/pkg@2.0.0", version: "2.0.0" },
+				};
+				return fake;
+			})(),
+		});
+
+		const human = await cliRun(["update", "npm:@scope/pkg@1.0.0", "--to", "npm:@scope/pkg@2.0.0", "--approve"], d);
+		expect(human.code).toBe(0);
+		expect(human.out).toContain("replaced npm:@scope/pkg@1.0.0 with npm:@scope/pkg@2.0.0");
+		expect((d.inst as FakeInstaller).gotTarget).toBe("npm:@scope/pkg@2.0.0");
+
+		const json = await cliRun(["update", "npm:@scope/pkg@1.0.0", "--to", "npm:@scope/pkg@2.0.0", "--approve", "--json"], d);
+		const parsed = JSON.parse(json.out);
+		expect(parsed.replaced).toBe(true);
+		expect(parsed.before).toEqual({ source: "npm:@scope/pkg@1.0.0", version: "1.0.0" });
+		expect(parsed.after).toEqual({ source: "npm:@scope/pkg@2.0.0", version: "2.0.0" });
+	});
+
+	it("update --to rejects an invalid target source with a usage error, before ever calling the installer", async () => {
+		const d = deps();
+		const result = await cliRun(["update", "npm:@scope/pkg@1.0.0", "--to", "not a valid source!", "--approve"], d);
+		expect(result.code).toBe(2);
+		expect((d.inst as FakeInstaller).updated).toBe("");
+	});
+
+	it("reports pinnedSourceRequiresTarget and mentions --to in the human-readable pinned message", async () => {
+		const d = deps({
+			inst: (() => {
+				const fake = new FakeInstaller();
+				fake.updateOutcome = { alreadyUpToDate: true, reloadRequired: false, pinned: true, pinnedSourceRequiresTarget: true };
+				return fake;
+			})(),
+		});
+
+		const human = await cliRun(["update", "npm:@scope/pkg@1.0.0", "--approve"], d);
+		expect(human.out).toContain("--to");
+		const json = await cliRun(["update", "npm:@scope/pkg@1.0.0", "--approve", "--json"], d);
+		expect(JSON.parse(json.out).pinnedSourceRequiresTarget).toBe(true);
+	});
 
 	it("update --self requires approval under the guarded default, same as every other mutation", async () => {
 		const d = deps({
@@ -947,6 +995,32 @@ describe("CLI", () => {
 		]);
 	});
 
+	it("verify-deploy runs standalone without a daemon, reporting stale/missing/shadow locations for a real on-disk layout", async () => {
+		const piHome = track(mkdtempSync(join(tmpdir(), "packed-verify-deploy-cli-")));
+		const pkgDir = join(piHome, "npm", "node_modules", "@scope", "pkg");
+		mkdirSync(pkgDir, { recursive: true });
+		writeFileSync(join(pkgDir, "package.json"), JSON.stringify({ name: "@scope/pkg", version: "1.2.3" }));
+		const d = deps({ piHome });
+
+		const jsonResult = await cliRun(["verify-deploy", "@scope/pkg", "--json"], d);
+		expect(jsonResult.code).toBe(0);
+		const parsed = JSON.parse(jsonResult.out);
+		expect(parsed.ok).toBe(true);
+		expect(parsed.packageName).toBe("@scope/pkg");
+		expect(parsed.expectedVersion).toBe("1.2.3");
+
+		const human = await cliRun(["verify-deploy", "@scope/pkg"], d);
+		expect(human.out).toContain("PASS");
+		expect(human.code).toBe(0);
+
+		const stale = await cliRun(["verify-deploy", "@scope/pkg", "--version", "9.9.9"], d);
+		expect(stale.code).toBe(1);
+		expect(stale.out).toContain("FAIL");
+		expect(stale.out).toContain("STALE (1.2.3)");
+
+		expect((await cliRun(["verify-deploy", "not a valid name!"], d)).code).toBe(2);
+	});
+
 	it("advisories runs standalone without a daemon and degrades to zero findings, never a real network call, when nothing is installed", async () => {
 		const d = deps({ piHome: track(mkdtempSync(join(tmpdir(), "packed-advisories-cli-"))) });
 		const result = await cliRun(["advisories", "--json"], d);