@f5-sales-demo/xcsh 19.101.0 → 19.101.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.101.0",
+	"version": "19.101.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",
@@ -57,13 +57,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "1.3.0",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.101.0",
-		"@f5-sales-demo/pi-agent-core": "19.101.0",
-		"@f5-sales-demo/pi-ai": "19.101.0",
-		"@f5-sales-demo/pi-natives": "19.101.0",
-		"@f5-sales-demo/pi-resource-management": "19.101.0",
-		"@f5-sales-demo/pi-tui": "19.101.0",
-		"@f5-sales-demo/pi-utils": "19.101.0",
+		"@f5-sales-demo/xcsh-stats": "19.101.1",
+		"@f5-sales-demo/pi-agent-core": "19.101.1",
+		"@f5-sales-demo/pi-ai": "19.101.1",
+		"@f5-sales-demo/pi-natives": "19.101.1",
+		"@f5-sales-demo/pi-resource-management": "19.101.1",
+		"@f5-sales-demo/pi-tui": "19.101.1",
+		"@f5-sales-demo/pi-utils": "19.101.1",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/scripts/generate-extension-capabilities.ts

@@ -20,55 +20,182 @@ const here = import.meta.dir; // packages/coding-agent/scripts
 const vendoredPath = path.resolve(here, "../src/browser/capabilities.json");
 const generatedPath = path.resolve(here, "../src/browser/capabilities.generated.ts");
 
-// Co-build refresh: prefer the sibling extension's freshly-built contract.
-const siblingPath =
-	process.env.XCSH_EXTENSION_CAPABILITIES ?? path.resolve(here, "../../../../xcsh-chrome-extension/capabilities.json");
-if (fs.existsSync(siblingPath) && path.resolve(siblingPath) !== vendoredPath) {
-	fs.copyFileSync(siblingPath, vendoredPath);
+// Guarded so the regression checks below can be imported by tests without regenerating files.
+// Importing this module used to run the whole generator as a side effect (#2578).
+if (import.meta.main) {
+	// Co-build refresh: adopt the sibling extension's freshly-built contract — but only when it really is
+	// fresher. "The directory exists" is not evidence of that, and treating it as evidence silently rewrote a
+	// committed contract from whatever happened to be on the developer's disk (#2578).
+	//
+	// Measured on a real machine: a sibling checkout left at contractVersion 1.8.0 overwrote the committed
+	// 1.12.0 and deleted the whole `handshake` feature block, on every `bun run check`, `bun test` and
+	// `bun run build`. `release.ts` runs `git commit -a`, so the downgrade was one release away from shipping.
+	// The guard applies to the path found by *proximity*, which is the accidental one. An explicitly set
+	// XCSH_EXTENSION_CAPABILITIES is a deliberate statement about which manifest to compile in — including a
+	// major-version co-build that removes tools on purpose — so it is honoured and merely announced.
+	const explicitPath = process.env.XCSH_EXTENSION_CAPABILITIES;
+	const siblingPath = explicitPath ?? path.resolve(here, "../../../../xcsh-chrome-extension/capabilities.json");
+	if (explicitPath !== undefined && fs.existsSync(explicitPath) && path.resolve(explicitPath) !== vendoredPath) {
+		console.log(`Adopting ${explicitPath} (XCSH_EXTENSION_CAPABILITIES set explicitly).`);
+		fs.copyFileSync(explicitPath, vendoredPath);
+	} else if (explicitPath === undefined && fs.existsSync(siblingPath) && path.resolve(siblingPath) !== vendoredPath) {
+		adoptSiblingIfNotARegression(siblingPath, vendoredPath);
+	}
+
+	const manifest = JSON.parse(fs.readFileSync(vendoredPath, "utf8")) as {
+		contractVersion: string;
+		tools: Array<{ name: string }>;
+	};
+	const toolNames = manifest.tools.map(t => t.name);
+
+	const output = [
+		"// Auto-generated by scripts/generate-extension-capabilities.ts - DO NOT EDIT",
+		"// Source: src/browser/capabilities.json (the Chrome extension's published contract).",
+		"",
+		"export interface ExtensionToolFlags {",
+		"\treadonly readOnly?: boolean;",
+		"\treadonly mutates?: boolean;",
+		"\treadonly requiresExplainMode?: boolean;",
+		"}",
+		"",
+		"export interface ExtensionToolDef {",
+		"\treadonly name: string;",
+		"\treadonly summary: string;",
+		"\treadonly category: string;",
+		"\treadonly params: Record<string, unknown>;",
+		"\treadonly flags?: ExtensionToolFlags;",
+		"}",
+		"",
+		"export interface ExtensionCapabilities {",
+		"\treadonly version: string;",
+		"\treadonly contractVersion: string;",
+		"\treadonly multiPortDiscovery?: boolean;",
+		"\treadonly protocol: string;",
+		"\treadonly tools: readonly ExtensionToolDef[];",
+		"\treadonly features: Record<string, unknown>;",
+		"}",
+		"",
+		`export const EXTENSION_CAPABILITIES: ExtensionCapabilities = ${JSON.stringify(manifest, null, "\t")};`,
+		"",
+		`export const EXTENSION_CONTRACT_VERSION = ${JSON.stringify(manifest.contractVersion)};`,
+		"",
+		`export const EXTENSION_TOOL_NAMES: readonly string[] = ${JSON.stringify(toolNames)};`,
+		"",
+	].join("\n");
+
+	await Bun.write(generatedPath, output);
+	console.log(
+		`Generated ${path.relative(process.cwd(), generatedPath)} (${toolNames.length} tools, contract ${manifest.contractVersion})`,
+	);
+}
+
+/** A capability manifest, as far as the regression check needs to understand one. */
+interface CapabilityManifest {
+	contractVersion?: string;
+	tools?: Array<{ name?: string }>;
+	features?: Record<string, unknown>;
+}
+
+/**
+ * Decide whether a sibling manifest may replace the committed one.
+ *
+ * Exported for tests. Returns the reason to refuse, or undefined when adoption is safe.
+ *
+ * Two independent guards, because they catch different mistakes:
+ *  - a lower `contractVersion` is a stale checkout, the case that actually happened;
+ *  - a missing tool or feature key at the same-or-higher version is a broken build, which a version
+ *    comparison alone would wave through.
+ */
+export function regressionReason(sibling: CapabilityManifest, vendored: CapabilityManifest): string | undefined {
+	const siblingVersion = sibling.contractVersion ?? "";
+	const vendoredVersion = vendored.contractVersion ?? "";
+	const versionOrder = compareContractVersions(siblingVersion, vendoredVersion);
+	if (versionOrder < 0) {
+		return `contractVersion would go backwards, ${vendoredVersion} -> ${siblingVersion}`;
+	}
+
+	const lostTools = missingKeys(
+		(vendored.tools ?? []).map(tool => tool.name ?? ""),
+		(sibling.tools ?? []).map(tool => tool.name ?? ""),
+	);
+	if (lostTools.length > 0) return `tools would be lost: ${lostTools.join(", ")}`;
+
+	const lostFeatures = missingKeys(Object.keys(vendored.features ?? {}), Object.keys(sibling.features ?? {}));
+	if (lostFeatures.length > 0) return `features would be lost: ${lostFeatures.join(", ")}`;
+
+	// Equal versions with different content mean one side changed without bumping, so the version says
+	// nothing about which is fresher. That is not hypothetical: a tool was once added while contractVersion
+	// stayed put, which is exactly how a stale same-version sibling could regress nested tool params or
+	// feature internals past a check that only compares names. Refuse and let the operator decide, via
+	// XCSH_EXTENSION_CAPABILITIES if they mean it.
+	if (versionOrder === 0 && !sameContent(sibling, vendored)) {
+		return `contractVersion is unchanged at ${vendoredVersion} but the content differs, so neither copy is provably fresher`;
+	}
+
+	return undefined;
 }
 
-const manifest = JSON.parse(fs.readFileSync(vendoredPath, "utf8")) as {
-	contractVersion: string;
-	tools: Array<{ name: string }>;
-};
-const toolNames = manifest.tools.map(t => t.name);
-
-const output = [
-	"// Auto-generated by scripts/generate-extension-capabilities.ts - DO NOT EDIT",
-	"// Source: src/browser/capabilities.json (the Chrome extension's published contract).",
-	"",
-	"export interface ExtensionToolFlags {",
-	"\treadonly readOnly?: boolean;",
-	"\treadonly mutates?: boolean;",
-	"\treadonly requiresExplainMode?: boolean;",
-	"}",
-	"",
-	"export interface ExtensionToolDef {",
-	"\treadonly name: string;",
-	"\treadonly summary: string;",
-	"\treadonly category: string;",
-	"\treadonly params: Record<string, unknown>;",
-	"\treadonly flags?: ExtensionToolFlags;",
-	"}",
-	"",
-	"export interface ExtensionCapabilities {",
-	"\treadonly version: string;",
-	"\treadonly contractVersion: string;",
-	"\treadonly multiPortDiscovery?: boolean;",
-	"\treadonly protocol: string;",
-	"\treadonly tools: readonly ExtensionToolDef[];",
-	"\treadonly features: Record<string, unknown>;",
-	"}",
-	"",
-	`export const EXTENSION_CAPABILITIES: ExtensionCapabilities = ${JSON.stringify(manifest, null, "\t")};`,
-	"",
-	`export const EXTENSION_CONTRACT_VERSION = ${JSON.stringify(manifest.contractVersion)};`,
-	"",
-	`export const EXTENSION_TOOL_NAMES: readonly string[] = ${JSON.stringify(toolNames)};`,
-	"",
-].join("\n");
-
-await Bun.write(generatedPath, output);
-console.log(
-	`Generated ${path.relative(process.cwd(), generatedPath)} (${toolNames.length} tools, contract ${manifest.contractVersion})`,
-);
+/**
+ * Whole-manifest equality, by canonical JSON.
+ *
+ * Deliberately not a deep field-by-field comparison: the question is only "are these the same document",
+ * and any difference at an equal version is enough to refuse.
+ */
+function sameContent(left: CapabilityManifest, right: CapabilityManifest): boolean {
+	return canonicalJson(left) === canonicalJson(right);
+}
+
+/** JSON with object keys sorted, so key order alone does not read as a difference. */
+function canonicalJson(value: unknown): string {
+	if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+	if (value !== null && typeof value === "object") {
+		const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+		return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${canonicalJson(entry)}`).join(",")}}`;
+	}
+	return JSON.stringify(value) ?? "null";
+}
+
+function missingKeys(expected: readonly string[], actual: readonly string[]): string[] {
+	const present = new Set(actual.filter(Boolean));
+	return expected.filter(key => key !== "" && !present.has(key));
+}
+
+/** Numeric-segment comparison. Enough for a dotted contract version, and no dependency. */
+export function compareContractVersions(left: string, right: string): number {
+	const parse = (value: string): number[] => value.split(".").map(part => Number.parseInt(part, 10) || 0);
+	const a = parse(left);
+	const b = parse(right);
+	for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+		const diff = (a[index] ?? 0) - (b[index] ?? 0);
+		if (diff !== 0) return diff < 0 ? -1 : 1;
+	}
+	return 0;
+}
+
+function adoptSiblingIfNotARegression(from: string, to: string): void {
+	let sibling: CapabilityManifest;
+	let vendored: CapabilityManifest;
+	try {
+		sibling = JSON.parse(fs.readFileSync(from, "utf8")) as CapabilityManifest;
+		vendored = JSON.parse(fs.readFileSync(to, "utf8")) as CapabilityManifest;
+	} catch (error) {
+		// Unreadable input must not silently leave the committed copy in place either — say so.
+		console.warn(`Keeping the committed capabilities: could not compare with ${from} (${String(error)}).`);
+		return;
+	}
+
+	const reason = regressionReason(sibling, vendored);
+	if (reason === undefined) {
+		fs.copyFileSync(from, to);
+		return;
+	}
+
+	// Refused rather than fatal: this generator runs from `check:types`, `test` and `build`, so failing
+	// here would block every command on any machine with a stale sibling checkout. Skipping keeps the
+	// committed contract — the correct one — and names what was ignored so it is fixable.
+	console.warn(
+		`Ignoring ${from}: ${reason}.\n` +
+			"  The committed capabilities.json is being kept. Update or remove that checkout, or set\n" +
+			"  XCSH_EXTENSION_CAPABILITIES to the manifest you actually want compiled in.",
+	);
+}

package/src/internal-urls/build-info.generated.ts

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.101.0",
-	"commit": "389279d7ee7ae16a82af6b03d9f6ea3920e8925e",
-	"shortCommit": "389279d",
+	"version": "19.101.1",
+	"commit": "fbb716396d667153d37600b5c654893f7cdb3385",
+	"shortCommit": "fbb7163",
 	"branch": "main",
-	"tag": "v19.101.0",
-	"commitDate": "2026-07-29T21:37:59Z",
-	"buildDate": "2026-07-29T22:01:44.081Z",
+	"tag": "v19.101.1",
+	"commitDate": "2026-07-30T02:09:00Z",
+	"buildDate": "2026-07-30T02:36:13.835Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5-sales-demo/xcsh",
 	"repoSlug": "f5-sales-demo/xcsh",
-	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/389279d7ee7ae16a82af6b03d9f6ea3920e8925e",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.101.0"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/fbb716396d667153d37600b5c654893f7cdb3385",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.101.1"
 };