@f5xc-salesdemos/xcsh 18.32.0 → 18.33.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "18.32.0",
+	"version": "18.33.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.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.33.0",
+		"@f5xc-salesdemos/pi-agent-core": "18.33.0",
+		"@f5xc-salesdemos/pi-ai": "18.33.0",
+		"@f5xc-salesdemos/pi-natives": "18.33.0",
+		"@f5xc-salesdemos/pi-tui": "18.33.0",
+		"@f5xc-salesdemos/pi-utils": "18.33.0",
 		"@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) {
@@ -117,6 +142,39 @@ function renderCatalogSearch(
 	].join("\n");
 }
 
+function formatConstraints(constraints: Record<string, unknown> | undefined): string {
+	if (!constraints) return "--";
+	const parts: string[] = [];
+	if (constraints.pattern) parts.push(`pattern: \`${constraints.pattern}\``);
+	if (constraints.maxLength != null) parts.push(`maxLength: ${constraints.maxLength}`);
+	if (constraints.minLength != null) parts.push(`minLength: ${constraints.minLength}`);
+	if (constraints.minimum != null) parts.push(`min: ${constraints.minimum}`);
+	if (constraints.maximum != null) parts.push(`max: ${constraints.maximum}`);
+	if (constraints.minItems != null) parts.push(`minItems: ${constraints.minItems}`);
+	if (constraints.maxItems != null) parts.push(`maxItems: ${constraints.maxItems}`);
+	if (constraints.format) parts.push(`format: ${constraints.format}`);
+	if (Array.isArray(constraints.enum)) parts.push(`enum: ${constraints.enum.join(", ")}`);
+	return parts.length > 0 ? parts.join(", ") : "--";
+}
+
+function formatRequiredFor(
+	reqFor: { minimum_config?: boolean; create?: boolean; update?: boolean; read?: boolean } | undefined,
+): string {
+	if (!reqFor) return "--";
+	const ops: string[] = [];
+	if (reqFor.minimum_config) ops.push("minimum_config");
+	if (reqFor.create) ops.push("create");
+	if (reqFor.update) ops.push("update");
+	if (reqFor.read) ops.push("read");
+	return ops.length > 0 ? ops.join(", ") : "--";
+}
+
+function formatDefault(defaultVal: unknown, serverDefault: boolean | undefined): string {
+	if (defaultVal == null && !serverDefault) return "--";
+	const val = defaultVal != null ? String(defaultVal) : "--";
+	return serverDefault ? `${val} (server)` : val;
+}
+
 function renderCatalogDetail(cat: ApiCatalogCategory, index: ApiCatalogIndex): string {
 	const sections: string[] = [`# ${cat.displayName}`, "", `${cat.operations.length} operations.`];
 
@@ -134,7 +192,7 @@ function renderCatalogDetail(cat: ApiCatalogCategory, index: ApiCatalogIndex): s
 			}
 		}
 
-		if (op.bodySchema) {
+		if (!op.minimumPayload && op.bodySchema) {
 			const minConfig = (op.bodySchema as Record<string, unknown>)["x-f5xc-minimum-configuration"] as
 				| Record<string, unknown>
 				| undefined;
@@ -157,6 +215,47 @@ function renderCatalogDetail(cat: ApiCatalogCategory, index: ApiCatalogIndex): s
 			sections[sections.length - 1] = lastLine.replace(/ \\$/, "");
 		}
 		sections.push("```");
+
+		// Minimum Configuration (Tier 1)
+		if (op.minimumPayload) {
+			sections.push("", "### Minimum Configuration", "");
+			sections.push(`Required fields: ${op.minimumPayload.requiredFields.join(", ")}`);
+			sections.push("", "```json", JSON.stringify(op.minimumPayload.json, null, 2), "```");
+		}
+
+		// Field Constraints (Tier 2)
+		if (op.fieldMetadata && Object.keys(op.fieldMetadata).length > 0) {
+			sections.push("", "### Field Constraints", "");
+			sections.push("| Field | Type | Description | Constraint | Required For | Default |");
+			sections.push("|-------|------|-------------|-----------|--------------|---------|");
+			for (const [field, meta] of Object.entries(op.fieldMetadata)) {
+				const desc = meta.description ?? "";
+				const constraint = formatConstraints(meta.constraints);
+				const reqFor = formatRequiredFor(meta.required_for);
+				const def = formatDefault(meta.default, meta.serverDefault);
+				sections.push(`| ${field} | ${meta.type} | ${desc} | ${constraint} | ${reqFor} | ${def} |`);
+			}
+		}
+
+		// OneOf Recommendations
+		if (op.oneOfRecommendations && Object.keys(op.oneOfRecommendations).length > 0) {
+			sections.push("", "### OneOf Recommendations", "");
+			sections.push("| Path | Recommended Variant |");
+			sections.push("|------|-------------------|");
+			for (const [path, variant] of Object.entries(op.oneOfRecommendations)) {
+				sections.push(`| ${path} | ${variant} |`);
+			}
+		}
+
+		// Response Summary
+		if (op.responseSummary && op.responseSummary.length > 0) {
+			sections.push("", "### Response", "");
+			sections.push("| Field | Type | Description |");
+			sections.push("|-------|------|-------------|");
+			for (const f of op.responseSummary) {
+				sections.push(`| ${f.field} | ${f.type} | ${f.description} |`);
+			}
+		}
 	}
 
 	sections.push("");
@@ -165,7 +264,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-catalog-types.ts

@@ -13,6 +13,34 @@ export interface ApiCatalogParameter {
 	readonly default?: string;
 }
 
+export interface ApiCatalogMinimumPayload {
+	readonly json: Record<string, unknown>;
+	readonly requiredFields: readonly string[];
+	readonly description: string;
+}
+
+export interface ApiCatalogFieldMeta {
+	readonly type: string;
+	readonly description?: string;
+	readonly required_for?: {
+		readonly minimum_config?: boolean;
+		readonly create?: boolean;
+		readonly update?: boolean;
+		readonly read?: boolean;
+	};
+	readonly serverDefault?: boolean;
+	readonly default?: unknown;
+	readonly recommendedValue?: unknown;
+	readonly constraints?: Record<string, unknown>;
+	readonly conflictsWith?: readonly string[];
+}
+
+export interface ApiCatalogResponseField {
+	readonly field: string;
+	readonly type: string;
+	readonly description: string;
+}
+
 export interface ApiCatalogOperation {
 	readonly name: string;
 	readonly description: string;
@@ -22,6 +50,10 @@ export interface ApiCatalogOperation {
 	readonly parameters: readonly ApiCatalogParameter[];
 	readonly bodySchema?: Record<string, unknown>;
 	readonly responseSchema?: Record<string, unknown>;
+	readonly minimumPayload?: ApiCatalogMinimumPayload;
+	readonly fieldMetadata?: Readonly<Record<string, ApiCatalogFieldMeta>>;
+	readonly oneOfRecommendations?: Readonly<Record<string, string>>;
+	readonly responseSummary?: readonly ApiCatalogResponseField[];
 }
 
 export interface ApiCatalogCategory {

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.33.0",
+	"commit": "4c91daabbadd70bca20cf37d69efd0ef0f52a8bf",
+	"shortCommit": "4c91daa",
 	"branch": "main",
-	"tag": "v18.32.0",
-	"commitDate": "2026-05-02T02:44:42Z",
-	"buildDate": "2026-05-02T03:10:54.675Z",
+	"tag": "v18.33.0",
+	"commitDate": "2026-05-02T21:09:17Z",
+	"buildDate": "2026-05-02T21:28:48.472Z",
 	"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/4c91daabbadd70bca20cf37d69efd0ef0f52a8bf",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v18.33.0"
 };

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,31 @@ 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 curl template, minimum payload,
+     field constraints, OneOf recommendations, and response summary
+
+  For POST/PUT operations, the catalog includes a ready-to-use JSON payload.
+  Customize the payload with user-specified values (name, namespace, etc.),
+  substitute path parameters (`{namespace}`, `{name}`) with actual values,
+  insert the payload as the `-d` body in the curl template, and execute.
+
+  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`).