@f5-sales-demo/xcsh 22.1.2 → 22.2.1

package/CHANGELOG.md

@@ -42,6 +42,10 @@
 
 ### Changed
 
+- 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.1.2",
+	"version": "22.2.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.1.2",
-		"@f5-sales-demo/pi-ai": "22.1.2",
-		"@f5-sales-demo/pi-natives": "22.1.2",
-		"@f5-sales-demo/pi-resource-management": "22.1.2",
-		"@f5-sales-demo/pi-tui": "22.1.2",
-		"@f5-sales-demo/pi-utils": "22.1.2",
-		"@f5-sales-demo/xcsh-stats": "22.1.2",
+		"@f5-sales-demo/pi-agent-core": "22.2.1",
+		"@f5-sales-demo/pi-ai": "22.2.1",
+		"@f5-sales-demo/pi-natives": "22.2.1",
+		"@f5-sales-demo/pi-resource-management": "22.2.1",
+		"@f5-sales-demo/pi-tui": "22.2.1",
+		"@f5-sales-demo/pi-utils": "22.2.1",
+		"@f5-sales-demo/xcsh-stats": "22.2.1",
 		"@mozilla/readability": "^0.6",
 		"@resvg/resvg-wasm": "2.6.2",
 		"@sinclair/typebox": "0.34.52",

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,12 +105,15 @@ 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;
@@ -233,7 +259,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}`);

package/src/internal-urls/api-catalog-discovery.ts

@@ -95,6 +95,48 @@ export function matchesBaselineCatalogDiscoveryTerm(term: string, values: readon
 	return values.some(value => normalizeApiCatalogDiscoveryTerm(value).includes(normalized));
 }
 
+function categoryDocuments(category: ApiCatalogCategory): ApiCatalogDiscoveryDocument[] {
+	const destination = `xcsh://api-catalog/${category.name}`;
+	if (category.operations.length === 0) {
+		return [
+			{
+				id: `category:${category.name}`,
+				categoryName: category.name,
+				markdown: [
+					`# ${category.displayName}`,
+					"",
+					`- Category: ${category.name}`,
+					`- Destination: ${destination}`,
+					"",
+					"## Operations",
+					"- None",
+					"",
+				].join("\n"),
+			},
+		];
+	}
+	return category.operations
+		.slice()
+		.sort((left, right) => left.operationId.localeCompare(right.operationId))
+		.map(operation => ({
+			id: `operation:${category.name}:${operation.operationId}`,
+			categoryName: category.name,
+			markdown: [
+				`# ${category.displayName}: ${operation.name}`,
+				"",
+				`- Category: ${category.name}`,
+				`- Destination: ${destination}`,
+				`- Operation: ${operation.name}`,
+				`- Alias: ${(operation.operationAliases ?? []).join(", ")}`,
+				`- Description: ${operation.description}`,
+				`- Method: ${operation.method.toUpperCase()}`,
+				`- Path: ${operation.path}`,
+				`- Operation ID: ${operation.operationId}`,
+				"",
+			].join("\n"),
+		}));
+}
+
 function categoryDocument(category: ApiCatalogCategory): ApiCatalogDiscoveryDocument {
 	const destination = `xcsh://api-catalog/${category.name}`;
 	const operations = category.operations.flatMap(operation => [
@@ -105,7 +147,6 @@ function categoryDocument(category: ApiCatalogCategory): ApiCatalogDiscoveryDocu
 		`  - Path: ${operation.path}`,
 		`  - Operation ID: ${operation.operationId}`,
 	]);
-
 	return {
 		id: `category:${category.name}`,
 		categoryName: category.name,
@@ -139,6 +180,20 @@ export function buildApiCatalogDiscoveryCorpus(
 	};
 }
 
+/** Candidate-only operation granularity; authoritative results remain category URLs. */
+export function buildApiOperationDiscoveryCorpus(
+	index: ApiCatalogIndex,
+	data: Readonly<Record<string, ApiCatalogCategory>>,
+): ApiCatalogDiscoveryCorpus {
+	return {
+		catalogVersion: index.version,
+		documents: Object.values(data)
+			.slice()
+			.sort((left, right) => left.name.localeCompare(right.name))
+			.flatMap(categoryDocuments),
+	};
+}
+
 export function fingerprintApiCatalogDiscoveryCorpus(
 	corpus: ApiCatalogDiscoveryCorpus,
 	sourceSha: string,

package/src/internal-urls/api-catalog-preflight.ts

@@ -3,18 +3,20 @@ import path from "node:path";
 import { rankQmdBm25CatalogDiscovery } from "./api-catalog-discovery";
 import { QMD_API_CATALOG_PREBUILT_INDEX } from "./api-catalog-qmd-index.generated";
 import type { ApiSpecIndex } from "./api-spec-types";
+import {
+	buildKnowledgeSearchPlan,
+	classifyKnowledgeRequest,
+	type KnowledgeClassifierResource,
+	type KnowledgeSearchPlan,
+} from "./knowledge-classifier";
 
-export interface ApiCatalogPreflightResource {
-	readonly name: string;
-	readonly aliases: readonly string[];
-	readonly domain: string;
-	readonly categories: readonly string[];
-}
+export interface ApiCatalogPreflightResource extends KnowledgeClassifierResource {}
 
 export interface ApiCatalogPreflightIntent {
 	readonly resource: string;
 	readonly domain: string;
 	readonly queries: readonly string[];
+	readonly structuredQuery?: KnowledgeSearchPlan;
 }
 
 export interface ApiCatalogPreflightDestination {
@@ -45,16 +47,6 @@ interface RunApiCatalogPreflightOptions extends ApiCatalogPreflightOptions {
 	readonly rank?: (query: string) => Promise<readonly string[]>;
 }
 
-const EXCLUDED_INTENT =
-	/\b(?:troubleshoot|debug|not working|returning\s+\d{3}|pricing|price|quote|licen[cs]ing|sales)\b/i;
-const THIRD_PARTY_SCOPE = /\b(?:aws|amazon|azure|gcp|google cloud|kubernetes)\b/i;
-const F5_XC_SCOPE = /\b(?:f5(?:\s+distributed\s+cloud)?|xc)\b/i;
-const ANAPHORIC_RESOURCE = /\b(?:its|it|that|this)\b/i;
-const DOCUMENTATION_ROUTE = /xcsh:\/\/documentation(?:\/|\?)/i;
-const API_METADATA_INTENT =
-	/\b(?:endpoint|api\s+path|http\s+method|method|payload|request\s+body|required\s+fields?|enum|allowed\s+values?|constraints?|limits?|maximum|max(?:imum)?|minimum|min(?:imum)?|how\s+many|create|creates|creating|get|gets|list|lists|update|updates|replace|replaces|delete|deletes|clone|import)\b/i;
-const EXPLICIT_API_INTENT = /\b(?:api|endpoint|method|payload|schema)\b/i;
-
 let generatedResources: readonly ApiCatalogPreflightResource[] | undefined;
 let generatedCatalogVersion: string | undefined;
 
@@ -67,10 +59,6 @@ function normalizedPhrase(value: string): string {
 		.replace(/\s+/g, " ");
 }
 
-function preferredAlias(resource: { name: string; aliases: readonly string[] }): string {
-	return normalizedPhrase(resource.aliases[0] ?? resource.name);
-}
-
 function defaultAliases(name: string, descriptionShort?: string): string[] {
 	const canonical = normalizedPhrase(name);
 	const aliases = [normalizedPhrase(descriptionShort ?? ""), canonical].filter(Boolean);
@@ -97,56 +85,40 @@ function loadGeneratedMetadata(): { resources: readonly ApiCatalogPreflightResou
 	return { resources: generatedResources, catalogVersion: generatedCatalogVersion };
 }
 
-function crudVerb(prompt: string): string | undefined {
-	const value = normalizedPhrase(prompt);
-	if (/\b(?:create|creates|creating)\b/.test(value)) return "create";
-	if (/\b(?:get|gets|read|fetch)\b/.test(value)) return "get";
-	if (/\b(?:list|lists)\b/.test(value)) return "list";
-	if (/\b(?:update|updates)\b/.test(value)) return "update";
-	if (/\b(?:replace|replaces)\b/.test(value)) return "replace";
-	if (/\b(?:delete|deletes|remove)\b/.test(value)) return "delete";
-	if (/\bclone\b/.test(value)) return "clone";
-	if (/\bimport\b/.test(value)) return "import";
-	return undefined;
-}
-
 export function classifyApiCatalogPreflight(
 	prompt: string,
 	options: ApiCatalogPreflightOptions,
 ): ApiCatalogPreflightIntent | null {
-	if (!options.toolsEnabled || DOCUMENTATION_ROUTE.test(prompt) || EXCLUDED_INTENT.test(prompt)) return null;
-	if (THIRD_PARTY_SCOPE.test(prompt) && !F5_XC_SCOPE.test(prompt)) return null;
-	if (/\bterraform\b/i.test(prompt) && !EXPLICIT_API_INTENT.test(prompt)) return null;
-	if (!API_METADATA_INTENT.test(prompt)) return null;
-
 	const resources = options.resources ?? loadGeneratedMetadata().resources;
-	const normalizedPrompt = ` ${normalizedPhrase(prompt)} `;
-	const matches = resources
-		.flatMap(resource =>
-			resource.aliases
-				.map(alias => normalizedPhrase(alias))
-				.filter(alias => alias && normalizedPrompt.includes(` ${alias} `))
-				.map(alias => ({ resource, alias })),
-		)
-		.sort(
-			(left, right) =>
-				right.alias.length - left.alias.length ||
-				right.resource.categories.length - left.resource.categories.length ||
-				left.resource.name.localeCompare(right.resource.name) ||
-				left.resource.domain.localeCompare(right.resource.domain),
-		);
-	const selected = matches[0]?.resource;
-	if (!selected) {
-		if (ANAPHORIC_RESOURCE.test(prompt) && options.previousResource) return options.previousResource;
-		return null;
+	const previous = options.previousResource
+		? {
+				route: "api" as const,
+				confidence: 0.99,
+				resource: options.previousResource.resource,
+				domain: options.previousResource.domain,
+				constraints: { domain: options.previousResource.domain },
+				query:
+					options.previousResource.structuredQuery ??
+					buildKnowledgeSearchPlan(
+						"api",
+						options.previousResource.queries[0] ?? options.previousResource.resource,
+					),
+			}
+		: undefined;
+	const classified = classifyKnowledgeRequest(prompt, { toolsEnabled: options.toolsEnabled, resources, previous });
+	if (classified.route !== "api" || !classified.resource || !classified.domain) return null;
+	if (
+		options.previousResource &&
+		classified.resource === options.previousResource.resource &&
+		/\b(?:its|it|that|this|those|them|the same)\b/i.test(prompt)
+	) {
+		return options.previousResource;
 	}
-
-	const alias = preferredAlias(selected);
-	const verb = crudVerb(prompt);
 	return {
-		resource: selected.name,
-		domain: selected.domain,
-		queries: verb ? [alias, `${verb} ${alias}`] : [alias],
+		resource: classified.resource,
+		domain: classified.domain,
+		queries: classified.query.lex,
+		structuredQuery: classified.query,
 	};
 }