@f5xc-salesdemos/xcsh 18.30.2 → 18.31.0

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## [Unreleased]
 
+## [18.30.4] - 2026-05-01
+
+### Added
+
+- `/context <name>` direct switch -- type a context name as a positional argument to switch without the `activate` verb, following `kubectx <name>` convention. ([#380](https://github.com/f5xc-salesdemos/xcsh/issues/380))
+- `/context -` previous context switching -- switch back to the last active context, following the `cd -` / `kubectx -` convention. Session-scoped, in-memory only. Calling `/context -` twice returns to the original context. ([#380](https://github.com/f5xc-salesdemos/xcsh/issues/380))
+- Mixed tab completion for `/context <Tab>` -- shows context names first, then `-` (when a previous context exists), then subcommand names. Context names display tenant URL hints. ([#380](https://github.com/f5xc-salesdemos/xcsh/issues/380))
+- Reserved subcommand name guard -- prevents creating, renaming, or importing contexts with names that collide with `/context` subcommands (19 reserved names including `list`, `create`, `delete`, `help`). Case-insensitive. ([#378](https://github.com/f5xc-salesdemos/xcsh/issues/378))
+- Previous context tracking in `ContextService` -- `previousContextName` getter, `activatePrevious()` method, automatic pointer maintenance on delete (cleared) and rename (updated). ([#379](https://github.com/f5xc-salesdemos/xcsh/issues/379))
+
 ## [18.18.4] - 2026-04-26
 
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.30.2",
+	"version": "18.31.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -48,12 +48,12 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "18.30.2",
-		"@f5xc-salesdemos/pi-agent-core": "18.30.2",
-		"@f5xc-salesdemos/pi-ai": "18.30.2",
-		"@f5xc-salesdemos/pi-natives": "18.30.2",
-		"@f5xc-salesdemos/pi-tui": "18.30.2",
-		"@f5xc-salesdemos/pi-utils": "18.30.2",
+		"@f5xc-salesdemos/xcsh-stats": "18.31.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.31.0",
+		"@f5xc-salesdemos/pi-ai": "18.31.0",
+		"@f5xc-salesdemos/pi-natives": "18.31.0",
+		"@f5xc-salesdemos/pi-tui": "18.31.0",
+		"@f5xc-salesdemos/pi-utils": "18.31.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

package/scripts/generate-api-spec-index.ts

@@ -11,10 +11,6 @@ interface SpecPathOperation {
 	[key: string]: unknown;
 }
 
-/**
- * Finds the operationId schema components (e.g., 'dns_zone', 'views.forward_proxy_policy')
- * that correspond to a given resource name by matching path segments.
- */
 function findResourceSchemaComponents(
 	resourceName: string,
 	paths: Record<string, Record<string, SpecPathOperation>>,
@@ -38,11 +34,29 @@ function findResourceSchemaComponents(
 	return [...found];
 }
 
+interface IndexEntryResource {
+	name: string;
+	description: string;
+	description_short?: string;
+	tier?: string;
+	icon?: string;
+	supports_logs?: boolean;
+	supports_metrics?: boolean;
+	dependencies?: { required: string[]; optional: string[] };
+	relationship_hints?: string[];
+	schema_components?: string[];
+	api_paths?: string[];
+}
+
 interface IndexEntry {
 	domain: string;
 	title: string;
 	description: string;
 	"x-f5xc-description-short": string;
+	"x-f5xc-description-medium"?: string;
+	"x-f5xc-icon"?: string;
+	"x-f5xc-is-preview"?: boolean;
+	"x-f5xc-requires-tier"?: string;
 	file: string;
 	path_count: number;
 	schema_count: number;
@@ -50,18 +64,23 @@ interface IndexEntry {
 	"x-f5xc-category": string;
 	"x-f5xc-use-cases"?: string[];
 	"x-f5xc-related-domains"?: string[];
-	"x-f5xc-primary-resources"?: Array<{ name: string; description: string }>;
+	"x-f5xc-primary-resources"?: IndexEntryResource[];
 }
 
 interface RawIndex {
 	version: string;
 	timestamp: string;
 	specifications: IndexEntry[];
+	"x-f5xc-critical-resources"?: string[];
+	"x-f5xc-guided-workflows"?: Record<string, unknown>;
+	"x-f5xc-error-resolution"?: Record<string, unknown>;
+	"x-f5xc-acronyms"?: Record<string, unknown>;
 }
 
 const REPO = "f5xc-salesdemos/api-specs-enriched";
-const PINNED_TAG = "v2.1.62";
+const PINNED_TAG = "v2.1.63";
 const outputPath = path.resolve(import.meta.dir, "../src/internal-urls/api-spec-index.generated.ts");
+const catalogOutputPath = path.resolve(import.meta.dir, "../src/internal-urls/api-catalog-index.generated.ts");
 
 async function downloadFromRelease(): Promise<string> {
 	const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "api-specs-"));
@@ -114,6 +133,34 @@ async function findSpecsDir(): Promise<string> {
 	return downloadFromRelease();
 }
 
+async function downloadCatalog(specsDir: string): Promise<Record<string, unknown> | null> {
+	const catalogPath = path.join(specsDir, "api-catalog.json");
+	if (fs.existsSync(catalogPath)) {
+		return JSON.parse(fs.readFileSync(catalogPath, "utf-8"));
+	}
+
+	const tag = process.env.API_SPECS_TAG ?? PINNED_TAG;
+	const catalogUrl = `https://github.com/${REPO}/releases/download/${tag}/api-catalog.json`;
+	console.log(`Downloading API catalog from ${catalogUrl}...`);
+	try {
+		const response = await fetch(catalogUrl, { redirect: "follow" });
+		if (!response.ok) {
+			console.warn(`api-catalog.json not found (${response.status}), skipping catalog generation`);
+			return null;
+		}
+		const text = await response.text();
+		return JSON.parse(text);
+	} catch (err) {
+		console.warn(`Failed to download api-catalog.json: ${err instanceof Error ? err.message : err}`);
+		return null;
+	}
+}
+
+function serializeEnrichment(key: string, value: unknown): string | undefined {
+	if (!value) return undefined;
+	return `\t${key}: ${JSON.stringify(value)},`;
+}
+
 let downloadedTmpDir: string | null = null;
 
 const specsDir = await findSpecsDir();
@@ -149,9 +196,22 @@ for (const entry of rawIndex.specifications) {
 	const b64 = compressed.toString("base64");
 
 	const resources = (entry["x-f5xc-primary-resources"] ?? []).map(r => {
-		const schemaComponents = findResourceSchemaComponents(r.name, specJson.paths ?? {});
-		const scStr = schemaComponents.length > 0 ? `, schemaComponents: ${JSON.stringify(schemaComponents)}` : "";
-		return `\t\t\t{ name: ${JSON.stringify(r.name)}, description: ${JSON.stringify(r.description)}${scStr} },`;
+		const upstreamSc = r.schema_components ?? [];
+		const schemaComponents =
+			upstreamSc.length > 0 ? upstreamSc : findResourceSchemaComponents(r.name, specJson.paths ?? {});
+		const fields: string[] = [`name: ${JSON.stringify(r.name)}`, `description: ${JSON.stringify(r.description)}`];
+		if (schemaComponents.length > 0) fields.push(`schemaComponents: ${JSON.stringify(schemaComponents)}`);
+		if (r.api_paths?.length) fields.push(`apiPaths: ${JSON.stringify(r.api_paths)}`);
+		if (r.tier) fields.push(`tier: ${JSON.stringify(r.tier)}`);
+		if (r.icon) fields.push(`icon: ${JSON.stringify(r.icon)}`);
+		if (r.description_short) fields.push(`descriptionShort: ${JSON.stringify(r.description_short)}`);
+		if (r.supports_logs != null) fields.push(`supportsLogs: ${r.supports_logs}`);
+		if (r.supports_metrics != null) fields.push(`supportsMetrics: ${r.supports_metrics}`);
+		if (r.dependencies && (r.dependencies.required.length > 0 || r.dependencies.optional.length > 0)) {
+			fields.push(`dependencies: ${JSON.stringify(r.dependencies)}`);
+		}
+		if (r.relationship_hints?.length) fields.push(`relationshipHints: ${JSON.stringify(r.relationship_hints)}`);
+		return `\t\t\t{ ${fields.join(", ")} },`;
 	});
 
 	const useCases = entry["x-f5xc-use-cases"];
@@ -173,6 +233,14 @@ for (const entry of rawIndex.specifications) {
 			`\t\t\t],`,
 			useCases ? `\t\t\tuseCases: ${JSON.stringify(useCases)},` : undefined,
 			relatedDomains?.length ? `\t\t\trelatedDomains: ${JSON.stringify(relatedDomains)},` : undefined,
+			entry["x-f5xc-icon"] ? `\t\t\ticon: ${JSON.stringify(entry["x-f5xc-icon"])},` : undefined,
+			entry["x-f5xc-description-medium"]
+				? `\t\t\tdescriptionMedium: ${JSON.stringify(entry["x-f5xc-description-medium"])},`
+				: undefined,
+			entry["x-f5xc-is-preview"] ? `\t\t\tisPreview: true,` : undefined,
+			entry["x-f5xc-requires-tier"]
+				? `\t\t\trequiresTier: ${JSON.stringify(entry["x-f5xc-requires-tier"])},`
+				: undefined,
 			"\t\t},",
 		]
 			.filter(Boolean)
@@ -183,6 +251,11 @@ for (const entry of rawIndex.specifications) {
 	processedCount++;
 }
 
+const criticalResources = rawIndex["x-f5xc-critical-resources"];
+const guidedWorkflows = rawIndex["x-f5xc-guided-workflows"];
+const errorResolution = rawIndex["x-f5xc-error-resolution"];
+const acronyms = rawIndex["x-f5xc-acronyms"];
+
 const output = [
 	"// Auto-generated by scripts/generate-api-spec-index.ts - DO NOT EDIT",
 	"",
@@ -196,13 +269,19 @@ const output = [
 	`\tdomains: [`,
 	...domainEntries,
 	`\t],`,
+	serializeEnrichment("criticalResources", criticalResources),
+	serializeEnrichment("guidedWorkflows", guidedWorkflows),
+	serializeEnrichment("errorResolution", errorResolution),
+	serializeEnrichment("acronyms", acronyms),
 	`};`,
 	"",
 	`export const API_SPEC_BLOBS: Readonly<Record<string, string>> = {`,
 	...blobEntries,
 	`};`,
 	"",
-].join("\n");
+]
+	.filter(l => l !== undefined)
+	.join("\n");
 
 await Bun.write(outputPath, output);
 
@@ -211,6 +290,53 @@ console.log(
 	`Generated ${path.relative(process.cwd(), outputPath)} (${processedCount} domains, ${skippedCount} skipped, ${outputSize} MB)`,
 );
 
+// Generate API catalog index
+const catalog = await downloadCatalog(specsDir);
+if (catalog) {
+	const categories = (catalog.categories ?? []) as Array<{ name: string; displayName: string; operations: unknown[] }>;
+	const catalogBlobEntries: string[] = [];
+	const catalogIndexEntries: string[] = [];
+
+	for (const cat of categories) {
+		const catJson = JSON.stringify(cat);
+		const catCompressed = gzipSync(Buffer.from(catJson));
+		catalogBlobEntries.push(`\t${JSON.stringify(cat.name)}: ${JSON.stringify(catCompressed.toString("base64"))},`);
+		catalogIndexEntries.push(
+			`\t\t{ name: ${JSON.stringify(cat.name)}, displayName: ${JSON.stringify(cat.displayName)}, operationCount: ${cat.operations?.length ?? 0} },`,
+		);
+	}
+
+	const catalogOutput = [
+		"// Auto-generated by scripts/generate-api-spec-index.ts - DO NOT EDIT",
+		"",
+		`import type { ApiCatalogCategorySummary, ApiCatalogIndex } from "./api-catalog-types";`,
+		"",
+		`export const API_CATALOG_INDEX: ApiCatalogIndex = {`,
+		`\tversion: ${JSON.stringify(catalog.version ?? "unknown")},`,
+		`\tdisplayName: ${JSON.stringify(catalog.displayName ?? "F5 Distributed Cloud")},`,
+		`\tservice: ${JSON.stringify(catalog.service ?? "f5xc")},`,
+		`\tcategoryCount: ${categories.length},`,
+		`\tauth: ${JSON.stringify(catalog.auth ?? {})},`,
+		`\tdefaults: ${JSON.stringify(catalog.defaults ?? {})},`,
+		`};`,
+		"",
+		`export const API_CATALOG_CATEGORY_SUMMARIES: ReadonlyArray<ApiCatalogCategorySummary> = [`,
+		...catalogIndexEntries,
+		`];`,
+		"",
+		`export const API_CATALOG_BLOBS: Readonly<Record<string, string>> = {`,
+		...catalogBlobEntries,
+		`};`,
+		"",
+	].join("\n");
+
+	await Bun.write(catalogOutputPath, catalogOutput);
+	const catalogSize = (Buffer.byteLength(catalogOutput) / 1024 / 1024).toFixed(1);
+	console.log(
+		`Generated ${path.relative(process.cwd(), catalogOutputPath)} (${categories.length} categories, ${catalogSize} MB)`,
+	);
+}
+
 if (downloadedTmpDir) {
 	fs.rmSync(downloadedTmpDir, { recursive: true, force: true });
 }

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

@@ -0,0 +1,177 @@
+import { gunzipSync } from "node:zlib";
+import { LRUCache } from "lru-cache";
+import type { ApiCatalogCategory, ApiCatalogCategorySummary, ApiCatalogIndex } from "./api-catalog-types";
+import type { InternalResource, InternalUrl } from "./types";
+
+const LRU_CAPACITY = 5;
+
+export interface ApiCatalogResolver {
+	resolve(url: InternalUrl): Promise<InternalResource>;
+}
+
+export function createApiCatalogResolver(
+	index: ApiCatalogIndex,
+	categorySummaries: readonly ApiCatalogCategorySummary[],
+	blobs: Record<string, string>,
+): ApiCatalogResolver {
+	const cache = new LRUCache<string, ApiCatalogCategory>({ max: LRU_CAPACITY });
+
+	function decompress(category: string): ApiCatalogCategory {
+		const cached = cache.get(category);
+		if (cached) return cached;
+
+		const blob = blobs[category];
+		if (!blob) throw new Error(`No catalog blob for category: ${category}`);
+
+		const buffer = Buffer.from(blob, "base64");
+		const decompressed = gunzipSync(buffer);
+		const cat = JSON.parse(decompressed.toString("utf-8")) as ApiCatalogCategory;
+		cache.set(category, cat);
+		return cat;
+	}
+
+	return {
+		async resolve(url: InternalUrl): Promise<InternalResource> {
+			const pathname = url.rawPathname ?? url.pathname;
+			const category = pathname.replace(/^\//, "").replace(/\/$/, "");
+			const search = url.searchParams.get("search");
+
+			if (!category) {
+				const content = search
+					? renderCatalogSearch(index, categorySummaries, search)
+					: renderCatalogIndex(index, categorySummaries);
+				return makeResource(url, content);
+			}
+
+			const summary = categorySummaries.find(c => c.name === category);
+			if (!summary) {
+				return makeResource(url, renderUnknownCategory(category, categorySummaries));
+			}
+
+			try {
+				const cat = decompress(category);
+				return makeResource(url, renderCatalogDetail(cat, index));
+			} catch (err) {
+				const message = err instanceof Error ? err.message : String(err);
+				return makeResource(url, `# Error loading ${category}\n\n${message}\n`);
+			}
+		},
+	};
+}
+
+function makeResource(url: InternalUrl, content: string): InternalResource {
+	return {
+		url: url.href,
+		content,
+		contentType: "text/markdown",
+		size: Buffer.byteLength(content, "utf-8"),
+		sourcePath: `xcsh://${url.rawHost}${url.rawPathname ?? "/"}`,
+	};
+}
+
+function renderCatalogIndex(index: ApiCatalogIndex, summaries: readonly ApiCatalogCategorySummary[]): string {
+	const rows = summaries.map(c => `| ${c.name} | ${c.displayName} | ${c.operationCount} |`);
+
+	return [
+		`# F5 XC API Catalog (v${index.version})`,
+		"",
+		`${summaries.length} categories. Read \`xcsh://api-catalog/{category}\` for operation details.`,
+		"",
+		"| Category | Display Name | Operations |",
+		"|----------|--------------|------------|",
+		...rows,
+		"",
+	].join("\n");
+}
+
+function renderCatalogSearch(
+	_index: ApiCatalogIndex,
+	summaries: readonly ApiCatalogCategorySummary[],
+	term: string,
+): string {
+	const lower = term.toLowerCase();
+	const matches = summaries.filter(
+		c => c.name.toLowerCase().includes(lower) || c.displayName.toLowerCase().includes(lower),
+	);
+
+	if (matches.length === 0) {
+		return [
+			`# No categories matching "${term}"`,
+			"",
+			`Use \`xcsh://api-catalog/\` to see all ${summaries.length} categories.`,
+			"",
+		].join("\n");
+	}
+
+	const rows = matches.map(c => `| ${c.name} | ${c.displayName} | ${c.operationCount} |`);
+
+	return [
+		`# API Catalog — search: "${term}"`,
+		"",
+		`${matches.length} matching categories.`,
+		"",
+		"| Category | Display Name | Operations |",
+		"|----------|--------------|------------|",
+		...rows,
+		"",
+	].join("\n");
+}
+
+function renderCatalogDetail(cat: ApiCatalogCategory, index: ApiCatalogIndex): string {
+	const sections: string[] = [`# ${cat.displayName}`, "", `${cat.operations.length} operations.`];
+
+	for (const op of cat.operations) {
+		sections.push("", `## ${op.method.toUpperCase()} ${op.path}`, "");
+		sections.push(op.description);
+		sections.push(`Danger level: ${op.dangerLevel}`);
+
+		if (op.parameters.length > 0) {
+			sections.push("", "### Parameters", "");
+			sections.push("| Name | In | Required | Type | Default |");
+			sections.push("|------|-----|----------|------|---------|");
+			for (const p of op.parameters) {
+				sections.push(`| ${p.name} | ${p.in} | ${p.required ? "yes" : "no"} | ${p.type} | ${p.default ?? ""} |`);
+			}
+		}
+
+		if (op.bodySchema) {
+			const minConfig = (op.bodySchema as Record<string, unknown>)["x-f5xc-minimum-configuration"] as
+				| Record<string, unknown>
+				| undefined;
+			if (minConfig?.required_fields) {
+				sections.push("", "### Minimum Configuration");
+				sections.push(`Required fields: ${(minConfig.required_fields as string[]).join(", ")}`);
+			}
+		}
+
+		sections.push("", "### Curl Example", "", "```bash");
+		const tokenVar = `$${index.auth.tokenSource}`;
+		const authHeader = `${index.auth.headerName}: ${index.auth.headerTemplate.replace("$TOKEN", tokenVar).replace("{token}", tokenVar)}`;
+		sections.push(`curl -X ${op.method.toUpperCase()} "$${index.auth.baseUrlSource}${op.path}" \\`);
+		sections.push(`  -H "${authHeader}" \\`);
+		if (op.method.toUpperCase() !== "GET" && op.method.toUpperCase() !== "DELETE") {
+			sections.push('  -H "Content-Type: application/json" \\');
+			sections.push("  -d @payload.json");
+		} else {
+			const lastLine = sections[sections.length - 1];
+			sections[sections.length - 1] = lastLine.replace(/ \\$/, "");
+		}
+		sections.push("```");
+	}
+
+	sections.push("");
+	return sections.join("\n");
+}
+
+function renderUnknownCategory(requested: string, summaries: readonly ApiCatalogCategorySummary[]): string {
+	const suggestions = summaries
+		.filter(c => c.name.includes(requested) || requested.includes(c.name.slice(0, 4)))
+		.slice(0, 5);
+
+	const sections = [`# Category not found: ${requested}`, ""];
+	if (suggestions.length > 0) {
+		sections.push("Did you mean:", ...suggestions.map(c => `- \`${c.name}\` — ${c.displayName}`), "");
+	}
+	sections.push("Use `xcsh://api-catalog/` to see all categories.", "");
+	return sections.join("\n");
+}

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

@@ -0,0 +1,54 @@
+/**
+ * Types for the embedded API catalog index.
+ *
+ * The catalog provides pre-built curl templates and operation metadata
+ * generated at build time from api-catalog.json in the api-specs-enriched repository.
+ */
+
+export interface ApiCatalogParameter {
+	readonly name: string;
+	readonly in: string;
+	readonly required: boolean;
+	readonly type: string;
+	readonly default?: string;
+}
+
+export interface ApiCatalogOperation {
+	readonly name: string;
+	readonly description: string;
+	readonly method: string;
+	readonly path: string;
+	readonly dangerLevel: string;
+	readonly parameters: readonly ApiCatalogParameter[];
+	readonly bodySchema?: Record<string, unknown>;
+	readonly responseSchema?: Record<string, unknown>;
+}
+
+export interface ApiCatalogCategory {
+	readonly name: string;
+	readonly displayName: string;
+	readonly operations: readonly ApiCatalogOperation[];
+}
+
+export interface ApiCatalogAuth {
+	readonly type: string;
+	readonly headerName: string;
+	readonly headerTemplate: string;
+	readonly tokenSource: string;
+	readonly baseUrlSource: string;
+}
+
+export interface ApiCatalogIndex {
+	readonly version: string;
+	readonly displayName: string;
+	readonly service: string;
+	readonly categoryCount: number;
+	readonly auth: ApiCatalogAuth;
+	readonly defaults: Record<string, { readonly source: string }>;
+}
+
+export interface ApiCatalogCategorySummary {
+	readonly name: string;
+	readonly displayName: string;
+	readonly operationCount: number;
+}