@f5-sales-demo/xcsh 22.5.2 → 22.7.0

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

@@ -73,6 +73,8 @@ import { createFleetResolver, type FleetDeps, type FleetResolver } from "./fleet
 import { createPluginResolver, type GetPluginRoots, type PluginResolver } from "./plugin-resolve";
 import { createRegistryResolver, type RegistryResolver, type RegistryResolverDeps } from "./registry-resolve";
 import { createSourceResolver, type SourceResolver } from "./source-resolve";
+import { TerraformDocumentationRepository } from "./terraform-documentation";
+import { EMBEDDED_TERRAFORM_DOCUMENTATION } from "./terraform-documentation-assets.generated";
 import { createTerraformResolver, type TerraformResolver } from "./terraform-resolve";
 import type { TerraformIndex } from "./terraform-types";
 import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
@@ -82,6 +84,7 @@ const ABOUT_ROUTE = "about";
 const API_SPEC_HOST = "api-spec";
 const API_CATALOG_HOST = "api-catalog";
 const DOCUMENTATION_HOST = "documentation";
+const TERRAFORM_DOCUMENTATION_HOST = "terraform-documentation";
 const BRANDING_HOST = "branding";
 const TERRAFORM_HOST = "terraform";
 const REGISTRY_HOST = "registry";
@@ -365,6 +368,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 	#apiSpecResolver: ApiSpecResolver | null;
 	#apiCatalogResolver: ApiCatalogResolver | null;
 	#documentationResolver: DocumentationResolver | null;
+	#terraformDocumentation: TerraformDocumentationRepository | null;
 	#terraformResolver: TerraformResolver | null;
 	#registryResolver: RegistryResolver | null = null;
 	#consoleResolver: ConsoleResolver | null = null;
@@ -400,6 +404,12 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 		if (documentationRepository && "prime" in documentationRepository) {
 			void (documentationRepository as EmbeddedDocumentationRepository).prime().catch(() => undefined);
 		}
+		this.#terraformDocumentation = EMBEDDED_TERRAFORM_DOCUMENTATION
+			? new TerraformDocumentationRepository(
+					EMBEDDED_TERRAFORM_DOCUMENTATION,
+					path.join(os.homedir(), ".xcsh", "cache", "terraform-documentation"),
+				)
+			: null;
 		this.#terraformResolver = null;
 		this.#getPluginRoots = options.getPluginRoots;
 		this.#fleetDeps = options.fleetDeps;
@@ -529,6 +539,12 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			return this.#getApiCatalogResolver().resolve(url);
 		}
 
+		if (host === TERRAFORM_DOCUMENTATION_HOST) {
+			if (!this.#terraformDocumentation)
+				throw new Error("Embedded Terraform documentation is unavailable in this build");
+			return this.#terraformDocumentation.resolve(url);
+		}
+
 		if (host === DOCUMENTATION_HOST) {
 			if (!this.#documentationResolver) throw new Error("Embedded documentation is unavailable in this build");
 			return this.#documentationResolver.resolve(url);
@@ -625,6 +641,7 @@ export class InternalDocsProtocolHandler implements ProtocolHandler {
 			apiSpecEntry,
 			apiCatalogEntry,
 			documentationEntry,
+			`- [terraform-documentation/](xcsh://terraform-documentation/) — pinned offline Terraform provider documentation and HCL guidance`,
 			brandingEntry,
 			terraformEntry,
 			registryEntry,

package/src/npm-binary-bootstrap.ts

@@ -57,6 +57,7 @@ export function getDefaultReleaseCacheRoot(platform: NodeJS.Platform = process.p
 export function releaseValidationEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
 	const validationEnvironment = { ...environment };
 	delete validationEnvironment.XCSH_SMOKE_TEST_QMD;
+	delete validationEnvironment.XCSH_SMOKE_TEST_TERRAFORM_DOCUMENTATION;
 	delete validationEnvironment.XCSH_SMOKE_TEST_SPECS;
 	delete validationEnvironment.XCSH_SMOKE_TEST_VERTEX_AUTH;
 	return validationEnvironment;

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

@@ -107,3 +107,7 @@ Active F5 XC context: tenant {{context.tenant}}, namespace {{context.namespace}}
 %%DEPRECATION_GUARDRAILS%%
 
 {{appendPrompt}}
+
+For explicit Terraform/provider/HCL guidance, search `xcsh://terraform-documentation/` and read relevant fundamentals, properties, lifecycle, and examples. Cite exact document URIs and the bundled provider version; distinguish documented validation from live apply evidence.
+
+For short or vague Terraform questions, translate the user's everyday wording into a documentation search; users need not supply internal URIs, provider names, filters, or schema paths. Use the returned documentation trail and child sections to find required configuration context and exact leaf constraints. Follow continuation links when needed. Cite only URIs and anchors returned by reads. When several resource types or configuration choices fit, explain the documented alternatives or ask one focused clarification instead of silently choosing an owner. Keep Terraform selection explicit and leave ordinary product/API discovery unchanged.

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

@@ -540,6 +540,8 @@ only after exhausting the disclosed live fallback hierarchy.
 
 ### Terraform provider
 
+For explicit Terraform, xcsh provider, or HCL requests, read `xcsh://terraform-documentation/`, search that namespace, and read relevant fundamentals, property sections, lifecycle/import guidance, and examples before answering or drafting HCL. Cite exact document URIs and the bundled provider version. Follow continuation links for complete references. Distinguish documented schema validation from observed live Terraform apply evidence.
+
 **ACTIVATION GATE**: You **MUST NOT** generate Terraform HCL code or plans unless the user explicitly asks for "Terraform", "HCL", ".tf" files, or Terraform CLI commands. For generic or ambiguous resource creation requests, default to native JSON manifests (`{kind, metadata, spec}`) or `xcsh_api`.
 
 Before referencing an external Terraform provider or module, resolve its exact source metadata through
@@ -846,3 +848,5 @@ Today is '{{date}}', and your work begins now. Get it right.
 - You **MUST** verify the effect. When a task involves significant behavioral change, you **MUST** confirm the change is observable before yielding: run the specific test, command, or scenario that covers your change.
 - You **MUST NOT** reverse a correct claim because the user restated their disagreement without new evidence. See `<epistemic-integrity>`.
 </critical>
+
+For short or vague Terraform questions, translate the user's everyday wording into a documentation search; users need not supply internal URIs, provider names, filters, or schema paths. Use the returned documentation trail and child sections to find required configuration context and exact leaf constraints. Follow continuation links when needed. Cite only URIs and anchors returned by reads. When several resource types or configuration choices fit, explain the documented alternatives or ask one focused clarification instead of silently choosing an owner. Keep Terraform selection explicit and leave ordinary product/API discovery unchanged.

package/src/session/agent-session.ts

@@ -51,6 +51,7 @@ import {
 	getSupportedEfforts,
 	isAnthropicPermanentErrorMessage,
 	isContextOverflow,
+	isTransportClosureError,
 	isUsageLimitError,
 	modelsAreEqual,
 	parseRateLimitReason,
@@ -6747,8 +6748,11 @@ export class AgentSession {
 	#isTransientTransportErrorMessage(errorMessage: string): boolean {
 		// Match: overloaded_error, provider returned error, rate limit, 429, 500, 502, 503, 504,
 		// service unavailable, network/connection errors, fetch failed, terminated, retry delay exceeded
-		return /overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|timed? out|timeout|terminated|retry delay|stream stall/i.test(
-			errorMessage,
+		return (
+			isTransportClosureError({ message: errorMessage }) ||
+			/overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|timed? out|timeout|terminated|retry delay|stream stall/i.test(
+				errorMessage,
+			)
 		);
 	}
 

package/src/terraform-documentation-smoke.ts

@@ -0,0 +1,54 @@
+import os from "node:os";
+import path from "node:path";
+import { TerraformDocumentationRepository } from "./internal-urls/terraform-documentation";
+import { EMBEDDED_TERRAFORM_DOCUMENTATION } from "./internal-urls/terraform-documentation-assets.generated";
+import type { InternalUrl } from "./internal-urls/types";
+
+export async function runTerraformDocumentationSmoke(): Promise<string> {
+	if (!EMBEDDED_TERRAFORM_DOCUMENTATION) throw new Error("Terraform smoke requires embedded assets");
+	const repository = new TerraformDocumentationRepository(
+		EMBEDDED_TERRAFORM_DOCUMENTATION,
+		path.join(os.homedir(), ".xcsh/cache/terraform-documentation"),
+	);
+	const trace: Array<Record<string, unknown>> = [];
+	async function read(uri: string): Promise<string> {
+		const url = Object.assign(new URL(uri), { rawHost: "terraform-documentation" }) as InternalUrl;
+		return (await repository.resolve(url)).content;
+	}
+	const inventory = await read("xcsh://terraform-documentation/");
+	if (!inventory.includes(EMBEDDED_TERRAFORM_DOCUMENTATION.pin.source_commit))
+		throw new Error("Terraform provenance smoke failed");
+	trace.push({
+		event: "terraform-inventory",
+		providerVersion: EMBEDDED_TERRAFORM_DOCUMENTATION.pin.provider_version,
+		sourceCommit: EMBEDDED_TERRAFORM_DOCUMENTATION.pin.source_commit,
+		documentCount: EMBEDDED_TERRAFORM_DOCUMENTATION.pin.document_count,
+	});
+	const search = await read(
+		"xcsh://terraform-documentation/?search=http_loadbalancer&provider_type=resources&provider_name=http_loadbalancer&role=fundamentals&limit=5",
+	);
+	if (!search.includes("Document: documentation/resources/http_loadbalancer/index.md"))
+		throw new Error("Terraform filtered search smoke failed");
+	trace.push({ event: "terraform-filtered-search", outcome: "top-five" });
+	const section = await read(
+		"xcsh://terraform-documentation/documentation/resources/http_loadbalancer/properties/https/index.md#schema-https--port",
+	);
+	if (!section.includes("### port") || !section.includes("Validators"))
+		throw new Error("Terraform explicit-anchor smoke failed");
+	trace.push({ event: "terraform-explicit-anchor", outcome: "complete-property" });
+	const database = await repository.database();
+	const leaf =
+		"documentation/resources/http_loadbalancer/properties/bot_defense/policy/protected_app_endpoints/flow_label/authentication/login/transaction_result/success_conditions/index.md";
+	const complete = await read(`xcsh://terraform-documentation/${leaf}`);
+	if (
+		!complete.includes("regex_values") ||
+		!complete.includes("xcsh://terraform-documentation/documentation/resources/")
+	)
+		throw new Error("Canonical deep leaf navigation smoke failed");
+	trace.push({ event: "terraform-deep-leaf", path: leaf, outcome: "read-and-navigation" });
+	const missing = await read("xcsh://terraform-documentation/?search=nonexistent_xyz_4649");
+	if (!missing.includes("No results.")) throw new Error("Terraform missing smoke failed");
+	trace.push({ event: "terraform-missing", outcome: "no-match-no-fetch" });
+	database.close();
+	return `${trace.map(entry => JSON.stringify(entry)).join("\n")}\nXCSH_TERRAFORM_DOCUMENTATION_SMOKE_OK`;
+}