@f5-sales-demo/xcsh 22.2.0 → 22.3.1

package/CHANGELOG.md

@@ -42,6 +42,13 @@
 
 ### Changed
 
+- Allowed explicit `xcsh plugin setup <plugin> --force` runs to refresh dynamic setup plans even
+  when the current integration receipt is already ready ([#4516](https://github.com/f5-sales-demo/xcsh/issues/4516)).
+
+- Made standalone executable and schema-v2 receipt updates transactional, canonicalized receipt paths,
+  removed unused adjacent native payloads from standalone installs, and added published installer
+  qualification on Linux, macOS, and Windows ([#4510](https://github.com/f5-sales-demo/xcsh/issues/4510)).
+
 - Standardized executable updates on `xcsh self-update`; `xcsh update` is now reserved for strict manifest resource updates ([#4487](https://github.com/f5-sales-demo/xcsh/issues/4487)).
 
 - Added `power.sleepPrevention` with an `idle` default and cumulative `off`, `idle`, `display`, and

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "22.2.0",
+	"version": "22.3.1",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -67,13 +67,13 @@
 	},
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.4.0",
-		"@f5-sales-demo/pi-agent-core": "22.2.0",
-		"@f5-sales-demo/pi-ai": "22.2.0",
-		"@f5-sales-demo/pi-natives": "22.2.0",
-		"@f5-sales-demo/pi-resource-management": "22.2.0",
-		"@f5-sales-demo/pi-tui": "22.2.0",
-		"@f5-sales-demo/pi-utils": "22.2.0",
-		"@f5-sales-demo/xcsh-stats": "22.2.0",
+		"@f5-sales-demo/pi-agent-core": "22.3.1",
+		"@f5-sales-demo/pi-ai": "22.3.1",
+		"@f5-sales-demo/pi-natives": "22.3.1",
+		"@f5-sales-demo/pi-resource-management": "22.3.1",
+		"@f5-sales-demo/pi-tui": "22.3.1",
+		"@f5-sales-demo/pi-utils": "22.3.1",
+		"@f5-sales-demo/xcsh-stats": "22.3.1",
 		"@mozilla/readability": "^0.6",
 		"@resvg/resvg-wasm": "2.6.2",
 		"@sinclair/typebox": "0.34.52",

package/src/cli/plugin-cli.ts

@@ -28,7 +28,7 @@ import {
 	executeInstallAuthorizedSetup,
 	executeReviewedSetup,
 } from "../integrations/setup";
-import type { IntegrationHandle } from "../integrations/types";
+import type { IntegrationHandle, IntegrationState } from "../integrations/types";
 import { theme } from "../modes/theme/theme";
 import { personProfileService } from "../person-profile/service";
 import { ContextError, ContextService, type XCSHContext } from "../services/xcsh-context";
@@ -336,11 +336,18 @@ async function handleIntegrationStatus(args: string[], flags: { json?: boolean;
 	});
 }
 
-export async function reviewAndExecuteIntegrationSetup(handle: IntegrationHandle<unknown>) {
+export function shouldSkipIntegrationSetup(state: IntegrationState, force = false): boolean {
+	return state === "ready" && !force;
+}
+
+export async function reviewAndExecuteIntegrationSetup(
+	handle: IntegrationHandle<unknown>,
+	options: { force?: boolean } = {},
+) {
 	const plan = handle.setupPlan;
 	if (!plan) throw new Error(`Integration ${handle.id} does not declare setup`);
 	const current = await handle.get();
-	if (current.state === "ready") return current;
+	if (shouldSkipIntegrationSetup(current.state, options.force)) return current;
 	if (plan.guidedAction?.kind === "context_wizard")
 		throw new Error(
 			`Plugin ${handle.plugin ?? handle.id} setup requires interactive xcsh; run /plugin setup ${handle.plugin ?? handle.id} in the xcsh TUI.`,
@@ -358,19 +365,22 @@ export async function reviewAndExecuteIntegrationSetup(handle: IntegrationHandle
 	return result;
 }
 
-async function handleIntegrationSetup(args: string[], flags: { json?: boolean; context?: string }): Promise<void> {
+async function handleIntegrationSetup(
+	args: string[],
+	flags: { json?: boolean; context?: string; force?: boolean },
+): Promise<void> {
 	if (flags.json) throw new CliUsageError("plugin setup is human-only and does not accept --json");
-	if (args.length !== 1) throw new Error(`Usage: ${APP_NAME} plugin setup <plugin> [--context <name>]`);
+	if (args.length !== 1) throw new Error(`Usage: ${APP_NAME} plugin setup <plugin> [--context <name>] [--force]`);
 	if (!process.stdin.isTTY || !process.stdout.isTTY) throw new Error("Plugin setup requires an interactive terminal");
 	const handles = await loadIntegrationHandles();
 	await withPluginContext(flags.context, async () => {
 		const handle = selectSetupIntegration(handles, args[0]);
 		const current = await handle.get();
-		if (current.state === "ready") {
+		if (shouldSkipIntegrationSetup(current.state, flags.force)) {
 			process.stdout.write(`${handle.plugin ?? handle.id}: ready (setup is not required)\n`);
 			return;
 		}
-		const result = await reviewAndExecuteIntegrationSetup(handle);
+		const result = await reviewAndExecuteIntegrationSetup(handle, { force: flags.force });
 		process.stdout.write(
 			`${handle.plugin ?? handle.id}: ${result.state}${result.reason ? ` (${result.reason})` : ""}\n`,
 		);

package/src/cli/update-cli.ts

@@ -1,10 +1,12 @@
 /** Context-aware executable update policy and standalone replacement. */
 import * as fs from "node:fs";
 import { realpath } from "node:fs/promises";
+import path from "node:path";
 import { pipeline } from "node:stream/promises";
 import { APP_NAME, isEnoent, VERSION } from "@f5-sales-demo/pi-utils";
 import chalk from "chalk";
 import {
+	createInstallReceipt,
 	defaultInstallChannelDependencies,
 	formatUpdateRecommendation,
 	resolveInstallChannel,
@@ -70,23 +72,49 @@ export interface StandaloneReplacementOptions {
 	arch?: NodeJS.Architecture;
 	fetchImpl?(input: string | URL | Request, init?: RequestInit): Promise<Response>;
 	rename?(source: string, destination: string): Promise<void>;
+	readFile?(file: string): Promise<string>;
+	writeFile?(file: string, contents: string): Promise<void>;
+	unlink?(file: string): Promise<void>;
 	validate?(executable: string, expectedVersion: string): Promise<void>;
 }
 
-/** Atomically replace one proven standalone executable, restoring it on every failure. */
+async function ignoreMissing(unlink: (file: string) => Promise<void>, file: string): Promise<void> {
+	try {
+		await unlink(file);
+	} catch (error) {
+		if (!isEnoent(error)) throw error;
+	}
+}
+
+/** Replace a proven standalone executable and receipt as one rollback-safe transaction. */
 export async function replaceStandaloneExecutable(
 	expectedVersion: string,
 	options: StandaloneReplacementOptions,
 ): Promise<void> {
 	const targetPath = options.targetPath;
-	const binaryName = getBinaryName(options.platform, options.arch);
+	const platform = options.platform ?? process.platform;
+	const arch = options.arch ?? process.arch;
+	const binaryName = getBinaryName(platform, arch);
 	const url = `https://github.com/${REPO}/releases/download/v${expectedVersion}/${binaryName}`;
 	const tempPath = `${targetPath}.new-${process.pid}`;
-	const backupPath = `${targetPath}.bak`;
+	const receiptPath = path.join(path.dirname(targetPath), "xcsh-install.json");
+	const tempReceiptPath = `${receiptPath}.new-${process.pid}`;
+	const backupPath = `${targetPath}.bak-${process.pid}`;
+	const backupReceiptPath = `${receiptPath}.bak-${process.pid}`;
 	const fetchImpl = options.fetchImpl ?? fetch;
 	const rename = options.rename ?? fs.promises.rename;
+	const readFile = options.readFile ?? (file => fs.promises.readFile(file, "utf8"));
+	const writeFile =
+		options.writeFile ??
+		(async (file, contents) => fs.promises.writeFile(file, contents, { flag: "wx", mode: 0o644 }));
+	const unlink = options.unlink ?? fs.promises.unlink;
 	const validate = options.validate ?? validateExecutableVersion;
-	let originalMoved = false;
+	const receiptContents = `${JSON.stringify(createInstallReceipt("standalone", expectedVersion, targetPath, platform, arch))}\n`;
+	let originalBinaryMoved = false;
+	let originalReceiptMoved = false;
+	let replacementBinaryInstalled = false;
+	let replacementReceiptInstalled = false;
+	let committed = false;
 
 	try {
 		const response = await fetchImpl(url, { redirect: "follow" });
@@ -94,33 +122,69 @@ export async function replaceStandaloneExecutable(
 		await pipeline(response.body, fs.createWriteStream(tempPath, { mode: 0o755, flags: "wx" }));
 		await fs.promises.chmod(tempPath, 0o755);
 		await validate(tempPath, expectedVersion);
+		await writeFile(tempReceiptPath, receiptContents);
+		if ((await readFile(tempReceiptPath)) !== receiptContents)
+			throw new Error("Staged install receipt validation failed");
 
-		try {
-			await fs.promises.unlink(backupPath);
-		} catch (error) {
-			if (!isEnoent(error)) throw error;
-		}
 		await rename(targetPath, backupPath);
-		originalMoved = true;
+		originalBinaryMoved = true;
+		await rename(receiptPath, backupReceiptPath);
+		originalReceiptMoved = true;
 		await rename(tempPath, targetPath);
+		replacementBinaryInstalled = true;
+		await rename(tempReceiptPath, receiptPath);
+		replacementReceiptInstalled = true;
 		await validate(targetPath, expectedVersion);
-		await fs.promises.unlink(backupPath);
-		originalMoved = false;
+		if ((await readFile(receiptPath)) !== receiptContents) throw new Error("Installed receipt validation failed");
+		committed = true;
+		await ignoreMissing(unlink, backupPath).catch(() => {});
+		originalBinaryMoved = false;
+		await ignoreMissing(unlink, backupReceiptPath).catch(() => {});
+		originalReceiptMoved = false;
 	} catch (error) {
-		if (originalMoved) {
+		const rollbackErrors: unknown[] = [];
+		if (replacementReceiptInstalled) {
+			try {
+				await ignoreMissing(unlink, receiptPath);
+				replacementReceiptInstalled = false;
+			} catch (rollbackError) {
+				rollbackErrors.push(rollbackError);
+			}
+		}
+		if (originalReceiptMoved) {
+			try {
+				await rename(backupReceiptPath, receiptPath);
+				originalReceiptMoved = false;
+			} catch (rollbackError) {
+				rollbackErrors.push(rollbackError);
+			}
+		}
+		if (replacementBinaryInstalled) {
 			try {
-				await fs.promises.unlink(targetPath);
-			} catch (unlinkError) {
-				if (!isEnoent(unlinkError)) throw unlinkError;
+				await ignoreMissing(unlink, targetPath);
+				replacementBinaryInstalled = false;
+			} catch (rollbackError) {
+				rollbackErrors.push(rollbackError);
 			}
-			await rename(backupPath, targetPath);
-			originalMoved = false;
 		}
+		if (originalBinaryMoved) {
+			try {
+				await rename(backupPath, targetPath);
+				originalBinaryMoved = false;
+			} catch (rollbackError) {
+				rollbackErrors.push(rollbackError);
+			}
+		}
+		if (rollbackErrors.length > 0)
+			throw new AggregateError([error, ...rollbackErrors], "Self-update rollback failed");
 		throw error;
 	} finally {
-		try {
-			await fs.promises.unlink(tempPath);
-		} catch {}
+		await ignoreMissing(unlink, tempPath).catch(() => {});
+		await ignoreMissing(unlink, tempReceiptPath).catch(() => {});
+		if (committed) {
+			await ignoreMissing(unlink, backupPath).catch(() => {});
+			await ignoreMissing(unlink, backupReceiptPath).catch(() => {});
+		}
 	}
 }
 

package/src/cli/update-recommendation.ts

@@ -37,8 +37,10 @@ export interface InstallChannelDependencies {
 	run(command: string, args: string[]): Promise<CommandResult>;
 }
 
-interface InstallReceipt {
-	schemaVersion: 1;
+export const INSTALL_RECEIPT_SCHEMA_VERSION = 2;
+
+export interface InstallReceipt {
+	schemaVersion: typeof INSTALL_RECEIPT_SCHEMA_VERSION;
 	channel: "standalone" | "windows-installer";
 	version: string;
 	executablePath: string;
@@ -46,6 +48,8 @@ interface InstallReceipt {
 	arch: string;
 }
 
+const INSTALL_RECEIPT_KEYS = ["arch", "channel", "executablePath", "platform", "schemaVersion", "version"];
+
 function platformPath(platform: NodeJS.Platform): typeof path.posix | typeof path.win32 {
 	return platform === "win32" ? path.win32 : path.posix;
 }
@@ -55,6 +59,25 @@ function comparablePath(value: string, platform: NodeJS.Platform): string {
 	return platform === "win32" ? normalized.toLowerCase() : normalized;
 }
 
+export function createInstallReceipt(
+	channel: InstallReceipt["channel"],
+	version: string,
+	executablePath: string,
+	platform: NodeJS.Platform,
+	arch: string,
+): InstallReceipt {
+	const pathApi = platformPath(platform);
+	if (!pathApi.isAbsolute(executablePath)) throw new Error("Install receipt executable path must be absolute");
+	return {
+		schemaVersion: INSTALL_RECEIPT_SCHEMA_VERSION,
+		channel,
+		version,
+		executablePath: pathApi.normalize(executablePath),
+		platform,
+		arch,
+	};
+}
+
 function releaseAsset(platform: NodeJS.Platform, arch: string): string | undefined {
 	if (platform === "linux" && (arch === "x64" || arch === "arm64")) return `xcsh-linux-${arch}`;
 	if (platform === "darwin" && (arch === "x64" || arch === "arm64")) return `xcsh-darwin-${arch}`;
@@ -82,24 +105,21 @@ function receiptIsValid(
 	if (!value || typeof value !== "object") return false;
 	const receipt = value as Partial<InstallReceipt>;
 	if (
-		receipt.schemaVersion !== 1 ||
+		JSON.stringify(Object.keys(receipt).sort()) !== JSON.stringify(INSTALL_RECEIPT_KEYS) ||
+		receipt.schemaVersion !== INSTALL_RECEIPT_SCHEMA_VERSION ||
 		(receipt.channel !== "standalone" && receipt.channel !== "windows-installer") ||
 		receipt.version !== deps.version ||
 		receipt.platform !== deps.platform ||
 		receipt.arch !== deps.arch ||
 		typeof receipt.executablePath !== "string" ||
+		!platformPath(deps.platform).isAbsolute(receipt.executablePath) ||
+		platformPath(deps.platform).normalize(receipt.executablePath) !== receipt.executablePath ||
 		comparablePath(receipt.executablePath, deps.platform) !== comparablePath(resolvedExecPath, deps.platform)
 	) {
 		return false;
 	}
 	if (receipt.channel === "standalone") return deps.platform !== "win32";
-	if (deps.platform !== "win32") return false;
-	const localAppData = deps.env.LOCALAPPDATA;
-	if (!localAppData) return false;
-	return (
-		comparablePath(resolvedExecPath, deps.platform) ===
-		comparablePath(path.win32.join(localAppData, "xcsh", "xcsh.exe"), deps.platform)
-	);
+	return deps.platform === "win32";
 }
 
 async function defaultRun(command: string, args: string[]): Promise<CommandResult> {
@@ -233,7 +253,7 @@ export async function resolveInstallChannel(deps: InstallChannelDependencies): P
 		if (receiptIsValid(parsed, deps, resolvedExecPath)) {
 			signals.push({
 				channel: parsed.channel,
-				evidence: `valid schema-v1 ${parsed.channel} receipt at ${receiptPath}`,
+				evidence: `valid schema-v2 ${parsed.channel} receipt at ${receiptPath}`,
 			});
 		} else {
 			diagnostics.push(`invalid or stale install receipt at ${receiptPath}`);