@f5-sales-demo/xcsh 19.62.13 → 19.63.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5-sales-demo/xcsh",
-	"version": "19.62.13",
+	"version": "19.63.0",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5-sales-demo/xcsh",
 	"author": "Can Boluk",
@@ -56,13 +56,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5-sales-demo/xcsh-stats": "19.62.13",
-		"@f5-sales-demo/pi-agent-core": "19.62.13",
-		"@f5-sales-demo/pi-ai": "19.62.13",
-		"@f5-sales-demo/pi-natives": "19.62.13",
-		"@f5-sales-demo/pi-resource-management": "19.62.13",
-		"@f5-sales-demo/pi-tui": "19.62.13",
-		"@f5-sales-demo/pi-utils": "19.62.13",
+		"@f5-sales-demo/xcsh-stats": "19.63.0",
+		"@f5-sales-demo/pi-agent-core": "19.63.0",
+		"@f5-sales-demo/pi-ai": "19.63.0",
+		"@f5-sales-demo/pi-natives": "19.63.0",
+		"@f5-sales-demo/pi-resource-management": "19.63.0",
+		"@f5-sales-demo/pi-tui": "19.63.0",
+		"@f5-sales-demo/pi-utils": "19.63.0",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

package/src/deprecations.ts

@@ -0,0 +1,87 @@
+// Behavioral deprecation guardrails, derived from the single source of truth
+// (api-specs-enriched/config/branding.yaml → branding-index.generated.ts).
+//
+// This module is the ONE seam every surface consumes so deprecation facts are
+// authored once and never hand-duplicated:
+//   - the always-on system prompt (renderDeprecationGuardrails)
+//   - the xcsh://branding/* protocol (via xcsh-protocol.ts, same generated data)
+//   - the CLI-Quick-Start renderer (isDisallowedCliCommand / getDeprecatedClis)
+
+import { BRANDING_DEPRECATIONS } from "./internal-urls/branding-index.generated";
+
+interface DeprecationEntry {
+	deprecated: Record<string, string>;
+	canonical: Record<string, string>;
+}
+
+const DEPRECATIONS = BRANDING_DEPRECATIONS as unknown as Record<string, DeprecationEntry>;
+
+/** Markers that identify a command as targeting the F5 XC API. */
+const F5XC_API_MARKERS = [
+	"f5xc_api_url",
+	"f5xc_api_token",
+	"apitoken",
+	".volterra.io",
+	".volterra.us",
+	"console.ves",
+	"/api/config/",
+	"/api/data/",
+	"/api/web/",
+	"/api/shape/",
+	"/api/ml/",
+	"/api/register/",
+];
+
+// xcsh-native guidance substituted wherever a deprecated command would appear.
+// Intentionally does NOT echo the deprecated tool name — the substitution exists
+// precisely so that name never reaches the user through this surface.
+export const XCSH_NATIVE_API_GUIDANCE =
+	"Use the `xcsh_api` tool for F5 Distributed Cloud API calls — the spec's legacy CLI example is not supported in xcsh.";
+
+/** Deprecated CLI commands, sourced from branding deprecation data (e.g. ["vesctl"]). */
+export function getDeprecatedClis(): string[] {
+	const clis = new Set<string>();
+	for (const entry of Object.values(DEPRECATIONS)) {
+		const command = entry.deprecated?.command;
+		if (command) clis.add(command.trim().toLowerCase());
+	}
+	return [...clis];
+}
+
+/**
+ * True if a command must never be surfaced as an instruction: it invokes a
+ * deprecated CLI (e.g. vesctl), or it is a raw `curl` against the F5 XC API.
+ */
+export function isDisallowedCliCommand(command: string): boolean {
+	const lower = command.trim().toLowerCase();
+	if (!lower) return false;
+	const leadingToken = lower.split(/\s+/)[0] ?? "";
+	if (getDeprecatedClis().includes(leadingToken)) return true;
+	if (leadingToken === "curl" && F5XC_API_MARKERS.some(marker => lower.includes(marker))) return true;
+	return false;
+}
+
+/**
+ * Concise, always-on deprecation block for the system prompt. Concrete values
+ * come from the embedded branding data; the behavioral rules are stable prose.
+ */
+export function renderDeprecationGuardrails(): string {
+	const cli = DEPRECATIONS.cli;
+	const apiDocs = DEPRECATIONS.api_documentation;
+	const brand = DEPRECATIONS.product_brand;
+
+	const vesctl = cli?.deprecated.command ?? "vesctl";
+	const xcshCmd = cli?.canonical.command ?? "xcsh";
+	const legacyApiUrl = apiDocs?.deprecated.url ?? "https://docs.cloud.f5.com/docs-v2/api";
+	const enrichedUrl = apiDocs?.canonical.url ?? "https://f5-sales-demo.github.io/api-specs-enriched/en/";
+	const deadBrand = brand?.deprecated.name ?? "Volterra";
+	const currentBrand = brand?.canonical.name ?? "F5 Distributed Cloud";
+
+	return [
+		"These deprecations are non-negotiable. Full detail lives at `xcsh://branding` and `xcsh://branding/volterra`, but the rules below apply even when that protocol is never consulted.",
+		"",
+		`- **Never use \`${vesctl}\`.** It is the abandoned, unsupported legacy CLI; \`${xcshCmd}\` is its modern replacement. Never propose, generate, or run \`${vesctl}\`. For F5 XC API calls use the \`xcsh_api\` tool (never raw \`curl\`); for console automation use \`catalog_workflow_runner\`.`,
+		`- **The legacy API docs are deprecated.** Never link or fetch \`${legacyApiUrl}\`. The canonical API reference is \`${enrichedUrl}\`, and the enriched specs are already embedded in this binary — prefer \`xcsh://api-catalog/\` and \`xcsh://api-spec/\` before fetching anything.`,
+		`- **"${deadBrand}" is a retired brand name.** The product is **${currentBrand}**; never write "${deadBrand}" as a product name or recommend ${deadBrand}-labeled tooling. BUT \`volterra_*\` API keys, \`*.volterra.io\`/\`*.volterra.us\` hostnames, and schema identifiers are **required functional identifiers** — use them verbatim, exactly as the API expects. Only the brand name is dead, not the identifiers.`,
+	].join("\n");
+}

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

@@ -1,3 +1,4 @@
+import { isDisallowedCliCommand, XCSH_NATIVE_API_GUIDANCE } from "../deprecations";
 import type {
 	ApiSpecDomainEnrichments,
 	ApiSpecDomainEntry,
@@ -265,16 +266,27 @@ function renderDomainDetail(domain: string, entry: ApiSpecDomainEntry, spec: Ope
 	if (entry.cliMetadata?.quickStart?.command) {
 		const cli = entry.cliMetadata;
 		sections.push("", "## CLI Quick Start", "");
-		sections.push(`\`${cli.quickStart.command}\` — ${cli.quickStart.description}`);
+		// Never surface a deprecated CLI (e.g. vesctl) or raw curl against the F5 XC
+		// API as an instruction — even if the upstream spec carries one. Substitute
+		// xcsh-native guidance instead.
+		if (isDisallowedCliCommand(cli.quickStart.command)) {
+			sections.push(`${cli.quickStart.description} — ${XCSH_NATIVE_API_GUIDANCE}`);
+		} else {
+			sections.push(`\`${cli.quickStart.command}\` — ${cli.quickStart.description}`);
+		}
 		const validWorkflows = cli.commonWorkflows?.filter(wf => wf.name) ?? [];
 		if (validWorkflows.length > 0) {
 			sections.push("", "### Common Workflows");
 			for (const wf of validWorkflows) {
-				if (wf.commands?.length) {
+				const allowedCommands = (wf.commands ?? []).filter(cmd => !isDisallowedCliCommand(cmd));
+				if (allowedCommands.length > 0) {
 					sections.push("", `**${wf.name}:**`);
-					for (const cmd of wf.commands) {
+					for (const cmd of allowedCommands) {
 						sections.push(`- \`${cmd}\``);
 					}
+				} else if (wf.commands?.length) {
+					// Every command in this workflow was deprecated/disallowed.
+					sections.push("", `**${wf.name}:** ${XCSH_NATIVE_API_GUIDANCE}`);
 				} else {
 					sections.push(`- ${wf.name}`);
 				}

package/src/internal-urls/branding-index.generated.ts

@@ -56,6 +56,37 @@ export const BRANDING_DEPRECATIONS = {
 			url: "https://f5-sales-demo.github.io/terraform-provider-xcsh/",
 		},
 	},
+	cli: {
+		deprecated: {
+			command: "vesctl",
+			status: "abandoned",
+			note: "Legacy Volterra CLI, abandoned years ago and unsupported. xcsh must never propose, generate, or run vesctl. High risk of AI model recommendation due to training-data prevalence.\n",
+		},
+		canonical: {
+			command: "xcsh",
+			note: "xcsh is the modern, supported replacement for vesctl. For F5 XC API calls use the xcsh_api tool (never curl); for console automation use the catalog_workflow_runner tool.\n",
+		},
+	},
+	api_documentation: {
+		deprecated: {
+			url: "https://docs.cloud.f5.com/docs-v2/api",
+			note: "Legacy F5 XC API documentation set. Deprecated — never link or fetch it for API references.\n",
+		},
+		canonical: {
+			url: "https://f5-sales-demo.github.io/api-specs-enriched/en/",
+			note: "Enriched API specs are embedded in the xcsh binary — prefer xcsh://api-catalog/ and xcsh://api-spec/ before fetching any URL.\n",
+		},
+	},
+	product_brand: {
+		deprecated: {
+			name: "Volterra",
+			note: 'Volterra was the company F5 acquired; the brand is retired. Never use "Volterra" as a product name in prose or recommend Volterra-labeled tooling.\n',
+		},
+		canonical: {
+			name: "F5 Distributed Cloud",
+			note: "volterra_* API keys, *.volterra.io / *.volterra.us hostnames, and schema identifiers are required functional identifiers — use them verbatim; only the product/brand name is deprecated, not these identifiers.\n",
+		},
+	},
 } as const;
 
 export const BRANDING_GLOSSARY = {

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.62.13",
-	"commit": "d2b79662835d4c9663c10140f8347189603228ee",
-	"shortCommit": "d2b7966",
+	"version": "19.63.0",
+	"commit": "d363d9f8ae94d36d0088aab8932d1952d7f2c4d5",
+	"shortCommit": "d363d9f",
 	"branch": "main",
-	"tag": "v19.62.13",
-	"commitDate": "2026-07-12T14:09:18Z",
-	"buildDate": "2026-07-12T14:32:46.087Z",
+	"tag": "v19.63.0",
+	"commitDate": "2026-07-14T14:23:41Z",
+	"buildDate": "2026-07-14T14:50:44.521Z",
 	"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/d2b79662835d4c9663c10140f8347189603228ee",
-	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.62.13"
+	"commitUrl": "https://github.com/f5-sales-demo/xcsh/commit/d363d9f8ae94d36d0088aab8932d1952d7f2c4d5",
+	"releaseUrl": "https://github.com/f5-sales-demo/xcsh/releases/tag/v19.63.0"
 };

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

@@ -408,7 +408,11 @@ If that also 404s, the product has no documentation — acknowledge this to the
 and answers the question, OR when T3 and T5 have been checked without resolution.
 Only then is web search permitted — label external results as supplementary.
 
-## Terraform Provider Override
+## Deprecation guardrails
+
+%%DEPRECATION_GUARDRAILS%%
+
+### Terraform provider
 
 HARD OVERRIDE — F5 Distributed Cloud Terraform Provider:
 - NEVER reference, recommend, or generate Terraform code using:

package/src/system-prompt.ts

@@ -11,11 +11,15 @@ import { $ } from "bun";
 import { contextFileCapability } from "./capability/context-file";
 import { systemPromptCapability } from "./capability/system-prompt";
 import type { SkillsSettings } from "./config/settings";
+import { renderDeprecationGuardrails } from "./deprecations";
 import { type ContextFile, loadCapability, type SystemPrompt as SystemPromptFile } from "./discovery";
 import { isApplicableToContext, loadSkills, type Skill } from "./extensibility/skills";
 import customSystemPromptTemplate from "./prompts/system/custom-system-prompt.md" with { type: "text" };
 import systemPromptTemplate from "./prompts/system/system-prompt.md" with { type: "text" };
 
+/** Sentinel in system-prompt.md replaced with the rendered deprecation guardrails. */
+const DEPRECATION_GUARDRAILS_MARKER = "%%DEPRECATION_GUARDRAILS%%";
+
 let _buildMeta: { version: string; repoSlug: string } | null = null;
 
 function getBuildMeta(): { version: string; repoSlug: string } {
@@ -694,6 +698,14 @@ export async function buildSystemPrompt(options: BuildSystemPromptOptions = {}):
 	};
 	let rendered = prompt.render(resolvedCustomPrompt ? customSystemPromptTemplate : systemPromptTemplate, data);
 
+	// Deprecation guardrails are always-on: replace the section marker in the default
+	// template, or append when the active template has none (e.g. a fully custom system
+	// prompt), so the rules apply on every code path — not only when xcsh:// is consulted.
+	const deprecationGuardrails = renderDeprecationGuardrails();
+	rendered = rendered.includes(DEPRECATION_GUARDRAILS_MARKER)
+		? rendered.replace(DEPRECATION_GUARDRAILS_MARKER, deprecationGuardrails)
+		: `${rendered}\n\n## Deprecation guardrails\n\n${deprecationGuardrails}`;
+
 	// When autoqa is active the report_tool_issue tool is in the tool set — nudge the agent.
 	if (toolNames.includes("report_tool_issue")) {
 		rendered +=