@f5xc-salesdemos/xcsh 18.32.0 → 18.32.1

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.32.0",
+	"version": "18.32.1",
 	"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.32.0",
-		"@f5xc-salesdemos/pi-agent-core": "18.32.0",
-		"@f5xc-salesdemos/pi-ai": "18.32.0",
-		"@f5xc-salesdemos/pi-natives": "18.32.0",
-		"@f5xc-salesdemos/pi-tui": "18.32.0",
-		"@f5xc-salesdemos/pi-utils": "18.32.0",
+		"@f5xc-salesdemos/xcsh-stats": "18.32.1",
+		"@f5xc-salesdemos/pi-agent-core": "18.32.1",
+		"@f5xc-salesdemos/pi-ai": "18.32.1",
+		"@f5xc-salesdemos/pi-natives": "18.32.1",
+		"@f5xc-salesdemos/pi-tui": "18.32.1",
+		"@f5xc-salesdemos/pi-utils": "18.32.1",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.18",

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

@@ -187,6 +187,21 @@ if (!fs.existsSync(indexPath)) {
 
 const rawIndex: RawIndex = JSON.parse(fs.readFileSync(indexPath, "utf-8"));
 
+const catalog = await downloadCatalog(specsDir);
+
+const pathToCatalogCategories = new Map<string, string[]>();
+if (catalog) {
+	const cats = (catalog.categories ?? []) as Array<{ name: string; operations: Array<{ path: string }> }>;
+	for (const cat of cats) {
+		for (const op of cat.operations ?? []) {
+			if (!op.path) continue;
+			const existing = pathToCatalogCategories.get(op.path) ?? [];
+			existing.push(cat.name);
+			pathToCatalogCategories.set(op.path, existing);
+		}
+	}
+}
+
 const domainEntries: string[] = [];
 const blobEntries: string[] = [];
 let processedCount = 0;
@@ -224,6 +239,13 @@ for (const entry of rawIndex.specifications) {
 			fields.push(`dependencies: ${JSON.stringify(r.dependencies)}`);
 		}
 		if (r.relationship_hints?.length) fields.push(`relationshipHints: ${JSON.stringify(r.relationship_hints)}`);
+		const catalogCats = new Set<string>();
+		for (const ap of r.api_paths ?? []) {
+			for (const cat of pathToCatalogCategories.get(ap) ?? []) {
+				catalogCats.add(cat);
+			}
+		}
+		if (catalogCats.size > 0) fields.push(`catalogCategories: ${JSON.stringify([...catalogCats])}`);
 		return `\t\t\t{ ${fields.join(", ")} },`;
 	});
 
@@ -304,7 +326,6 @@ console.log(
 );
 
 // 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[] = [];

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

@@ -1,10 +1,15 @@
 import { gunzipSync } from "node:zlib";
 import { LRUCache } from "lru-cache";
 import type { ApiCatalogCategory, ApiCatalogCategorySummary, ApiCatalogIndex } from "./api-catalog-types";
+import type { ApiSpecIndex } from "./api-spec-types";
 import type { InternalResource, InternalUrl } from "./types";
 
 const LRU_CAPACITY = 5;
 
+function normalizeSearchTerm(s: string): string {
+	return s.toLowerCase().replace(/_/g, "-");
+}
+
 export interface ApiCatalogResolver {
 	resolve(url: InternalUrl): Promise<InternalResource>;
 }
@@ -13,6 +18,7 @@ export function createApiCatalogResolver(
 	index: ApiCatalogIndex,
 	categorySummaries: readonly ApiCatalogCategorySummary[],
 	blobs: Record<string, string>,
+	specIndex?: ApiSpecIndex,
 ): ApiCatalogResolver {
 	const cache = new LRUCache<string, ApiCatalogCategory>({ max: LRU_CAPACITY });
 
@@ -35,8 +41,27 @@ export function createApiCatalogResolver(
 			const pathname = url.rawPathname ?? url.pathname;
 			const category = pathname.replace(/^\//, "").replace(/\/$/, "");
 			const search = url.searchParams.get("search");
+			const resourceName = url.searchParams.get("resource");
 
 			if (!category) {
+				if (resourceName && specIndex) {
+					for (const domain of specIndex.domains) {
+						const res = domain.resources.find(r => r.name === resourceName);
+						if (res?.catalogCategories?.length) {
+							const catName = res.catalogCategories[0];
+							if (categorySummaries.some(c => c.name === catName)) {
+								try {
+									const cat = decompress(catName);
+									return makeResource(url, renderCatalogDetail(cat, index));
+								} catch {
+									break;
+								}
+							}
+						}
+					}
+					return makeResource(url, renderCatalogSearch(index, categorySummaries, resourceName));
+				}
+
 				const content = search
 					? renderCatalogSearch(index, categorySummaries, search)
 					: renderCatalogIndex(index, categorySummaries);
@@ -89,9 +114,9 @@ function renderCatalogSearch(
 	summaries: readonly ApiCatalogCategorySummary[],
 	term: string,
 ): string {
-	const lower = term.toLowerCase();
+	const normalized = normalizeSearchTerm(term);
 	const matches = summaries.filter(
-		c => c.name.toLowerCase().includes(lower) || c.displayName.toLowerCase().includes(lower),
+		c => normalizeSearchTerm(c.name).includes(normalized) || normalizeSearchTerm(c.displayName).includes(normalized),
 	);
 
 	if (matches.length === 0) {
@@ -165,7 +190,11 @@ function renderCatalogDetail(cat: ApiCatalogCategory, index: ApiCatalogIndex): s
 
 function renderUnknownCategory(requested: string, summaries: readonly ApiCatalogCategorySummary[]): string {
 	const suggestions = summaries
-		.filter(c => c.name.includes(requested) || requested.includes(c.name.slice(0, 4)))
+		.filter(c => {
+			const norm = normalizeSearchTerm(requested);
+			const normName = normalizeSearchTerm(c.name);
+			return normName.includes(norm) || norm.includes(normName.slice(0, 4));
+		})
 		.slice(0, 5);
 
 	const sections = [`# Category not found: ${requested}`, ""];

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

@@ -5,6 +5,7 @@ import type { InternalResource, InternalUrl } from "./types";
 
 const LRU_CAPACITY = 5;
 const SCHEMA_RENDER_MAX_DEPTH = 3;
+const CRUD_OPERATION_SUFFIXES = [".API.Create", ".API.Replace", ".API.Get", ".API.List", ".API.Delete"];
 
 const groupsCache = new WeakMap<OpenAPISpec, Map<string, Record<string, Record<string, OpenAPIPathOperation>>>>();
 
@@ -78,12 +79,13 @@ export function createApiSpecResolver(index: ApiSpecIndex, blobs: Record<string,
 				const pathFilter = url.searchParams.get("path");
 
 				if (resource) {
+					const crud = url.searchParams.get("crud") === "true";
 					const spec = decompress(domain);
 					const matchingPaths = filterPathsByResource(spec, resource, entry);
 					if (Object.keys(matchingPaths).length === 0) {
 						return makeResource(url, renderUnknownResource(resource, entry, spec));
 					}
-					return makeResource(url, renderResourceSpec(domain, resource, spec, entry));
+					return makeResource(url, renderResourceSpec(domain, resource, spec, entry, { crudOnly: crud }));
 				}
 
 				if (pathFilter) {
@@ -306,13 +308,24 @@ function filterPathsByResource(
 	return result;
 }
 
-function renderResourceSpec(_domain: string, resource: string, spec: OpenAPISpec, entry?: ApiSpecDomainEntry): string {
+function renderResourceSpec(
+	_domain: string,
+	resource: string,
+	spec: OpenAPISpec,
+	entry?: ApiSpecDomainEntry,
+	options?: { crudOnly?: boolean },
+): string {
 	const matchingPaths = filterPathsByResource(spec, resource, entry);
-	const sections = [`# ${resource} — Full API Specification`, ""];
+	const label = options?.crudOnly ? "CRUD Operations" : "Full API Specification";
+	const sections = [`# ${resource} — ${label}`, ""];
 
 	for (const [pathKey, methods] of Object.entries(matchingPaths)) {
 		for (const [method, op] of Object.entries(methods)) {
 			if (typeof op !== "object" || !op) continue;
+			if (options?.crudOnly) {
+				const opId = op.operationId ?? "";
+				if (!CRUD_OPERATION_SUFFIXES.some(s => opId.endsWith(s))) continue;
+			}
 			const operation = op;
 			sections.push(`## ${method.toUpperCase()} ${pathKey}`, "");
 			if (operation.summary) sections.push(String(operation.summary), "");

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

@@ -20,6 +20,7 @@ export interface ApiSpecDomainResource {
 		readonly optional: readonly string[];
 	};
 	readonly relationshipHints?: readonly string[];
+	readonly catalogCategories?: readonly string[];
 }
 
 export interface ApiSpecDomainEntry {

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "18.32.0",
-	"commit": "c5505c8b32a0441554d88d83cded48c25b110135",
-	"shortCommit": "c5505c8",
+	"version": "18.32.1",
+	"commit": "be6f85d9f84378312f0a305e6bf9ace1ea232b6b",
+	"shortCommit": "be6f85d",
 	"branch": "main",
-	"tag": "v18.32.0",
-	"commitDate": "2026-05-02T02:44:42Z",
-	"buildDate": "2026-05-02T03:10:54.675Z",
+	"tag": "v18.32.1",
+	"commitDate": "2026-05-02T14:48:30Z",
+	"buildDate": "2026-05-02T15:13:51.949Z",
 	"dirty": false,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/c5505c8b32a0441554d88d83cded48c25b110135",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.32.0"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/be6f85d9f84378312f0a305e6bf9ace1ea232b6b",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.32.1"
 };

package/src/internal-urls/xcsh-protocol.ts

@@ -141,7 +141,13 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 	#getApiCatalogResolver(): ApiCatalogResolver {
 		if (!this.#apiCatalogResolver) {
 			const catalog = loadApiCatalog();
-			this.#apiCatalogResolver = createApiCatalogResolver(catalog.index, catalog.summaries, catalog.blobs);
+			const specs = loadApiSpecs();
+			this.#apiCatalogResolver = createApiCatalogResolver(
+				catalog.index,
+				catalog.summaries,
+				catalog.blobs,
+				specs.index,
+			);
 		}
 		return this.#apiCatalogResolver;
 	}

package/src/prompts/system/system-prompt.md

@@ -191,20 +191,25 @@ Most tools resolve custom protocol URLs to internal resources (not web URLs):
   - `xcsh://about` — Identity, version, build fingerprint, architecture, self-improvement. **MUST** read for any question about xcsh before exploring `~/.xcsh/`.
     This document contains the authoritative repository URL, issues URL, and source location.
     For identity questions (source code, repo, version, who built this) — answer from `xcsh://about` alone. Do not call external GitHub tools.
-- `xcsh://api-spec/` — F5 XC API specifications.
-  **MUST NOT** read proactively. When the user needs to interact with the F5 XC API:
-  1. Read `xcsh://api-spec/` to identify the correct domain
-  2. Read `xcsh://api-spec/{domain}` to find the resource and operations
-  3. Read `xcsh://api-spec/{domain}?resource={name}` for full endpoint specification
+- `xcsh://api-spec/` — F5 XC API specifications (schema introspection, field types, validation).
+- `xcsh://api-catalog/` — F5 XC API operations with curl templates (CRUD execution).
+
+  When the user needs to **make an API call** (create, read, update, delete):
+
+  1. `xcsh://api-catalog/?search={term}` → find the operation
+  2. `xcsh://api-catalog/{category}` → get path, method, parameters, curl template
+
+  When the user needs to **understand a schema** (field types, nested objects, request body structure):
+
+  1. `xcsh://api-spec/{domain}?resource={name}` → full OpenAPI specification
+  If the domain is unknown, read `xcsh://api-spec/` first to identify it.
+
+  **MUST NOT** read proactively.
+  Never start at `xcsh://api-spec/` for CRUD operations — it returns the full schema (~40K tokens)
+  when the catalog provides the same endpoint with curl template (~700 tokens).
   Never guess API paths or request schemas.
   Also available: `xcsh://api-spec/workflows/` (step-by-step guides),
-  `xcsh://api-spec/errors/{code}` (error resolution),
-  `xcsh://api-spec/glossary/` (acronym reference).
-
-- `xcsh://api-catalog/` — Pre-built API operation catalog with curl templates.
-  **MUST NOT** read proactively. When building API requests:
-  1. Read `xcsh://api-catalog/?search={term}` to find the right operation
-  2. Read `xcsh://api-catalog/{category}` for full operation details and curl template
+  `xcsh://api-spec/errors/{code}` (error resolution), `xcsh://api-spec/glossary/` (acronym reference).
 
 In `bash`, URIs auto-resolve to filesystem paths (e.g., `python skill://my-skill/scripts/init.py`).