@f5-sales-demo/xcsh 19.51.2

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

@@ -0,0 +1,239 @@
+/**
+ * Types for the embedded API specification index and domain specs.
+ *
+ * These types define the shape of data generated at build time by
+ * scripts/generate-api-spec-index.ts from the api-specs-enriched repository.
+ */
+
+export interface ApiSpecDomainResource {
+	readonly name: string;
+	readonly description: string;
+	readonly schemaComponents?: readonly string[];
+	readonly apiPaths?: readonly string[];
+	readonly tier?: string;
+	readonly icon?: string;
+	readonly descriptionShort?: string;
+	readonly supportsLogs?: boolean;
+	readonly supportsMetrics?: boolean;
+	readonly dependencies?: {
+		readonly required: readonly string[];
+		readonly optional: readonly string[];
+	};
+	readonly relationshipHints?: readonly string[];
+	readonly catalogCategories?: readonly string[];
+}
+
+export interface ApiSpecCliMetadata {
+	readonly quickStart: {
+		readonly command: string;
+		readonly description: string;
+		readonly expectedOutput: string;
+	};
+	readonly commonWorkflows: readonly {
+		readonly name: string;
+		readonly commands?: readonly string[];
+	}[];
+	readonly troubleshooting: readonly {
+		readonly symptom?: string;
+		readonly fix?: string;
+	}[];
+	readonly icon?: string;
+}
+
+export interface ApiSpecBestPractices {
+	readonly commonErrors: readonly {
+		readonly code: number;
+		readonly message: string;
+		readonly resolution: string;
+		readonly prevention: string;
+	}[];
+	readonly securityNotes: readonly string[];
+	readonly performanceTips: readonly string[];
+}
+
+export interface ApiSpecDomainEntry {
+	readonly domain: string;
+	readonly title: string;
+	readonly description: string;
+	readonly descriptionShort: string;
+	readonly category: string;
+	readonly pathCount: number;
+	readonly schemaCount: number;
+	readonly complexity: string;
+	readonly resources: readonly ApiSpecDomainResource[];
+	readonly useCases?: readonly string[];
+	readonly relatedDomains?: readonly string[];
+	readonly icon?: string;
+	readonly descriptionMedium?: string;
+	readonly isPreview?: boolean;
+	readonly requiresTier?: string;
+	readonly descriptionLong?: string;
+	readonly summary?: string;
+	readonly logoSvg?: string;
+	readonly cliDomain?: string;
+	readonly cliMetadata?: ApiSpecCliMetadata;
+	readonly bestPractices?: ApiSpecBestPractices;
+}
+
+export interface ApiSpecGuidedWorkflows {
+	readonly version: string;
+	readonly total_workflows: number;
+	readonly domains: readonly string[];
+	readonly workflows: readonly ApiSpecGuidedWorkflow[];
+}
+
+export interface ApiSpecGuidedWorkflow {
+	readonly id: string;
+	readonly name: string;
+	readonly description: string;
+	readonly complexity: string;
+	readonly estimated_steps: number;
+	readonly prerequisites: readonly string[];
+	readonly steps: readonly ApiSpecGuidedWorkflowStep[];
+	readonly domain: string;
+}
+
+export interface ApiSpecGuidedWorkflowStep {
+	readonly order: number;
+	readonly action: string;
+	readonly name: string;
+	readonly description: string;
+	readonly resource?: string;
+	readonly required_fields?: readonly string[];
+	readonly tips?: readonly string[];
+	readonly optional?: boolean;
+	readonly depends_on?: readonly number[];
+	readonly verification?: readonly string[];
+}
+
+export interface ApiSpecHttpError {
+	readonly code: number;
+	readonly name: string;
+	readonly description: string;
+	readonly common_causes: readonly string[];
+	readonly diagnostic_steps: readonly {
+		readonly step: number;
+		readonly action: string;
+		readonly description: string;
+		readonly command?: string;
+	}[];
+	readonly prevention: readonly string[];
+	readonly related_errors?: readonly number[];
+}
+
+export interface ApiSpecResourceErrorEntry {
+	readonly error_code: number;
+	readonly pattern: string;
+	readonly resolution: string;
+}
+
+export interface ApiSpecErrorResolution {
+	readonly version: string;
+	readonly http_errors: Record<string, ApiSpecHttpError>;
+	readonly resource_errors: Record<string, readonly ApiSpecResourceErrorEntry[]>;
+}
+
+export interface ApiSpecAcronym {
+	readonly acronym: string;
+	readonly expansion: string;
+	readonly category: string;
+}
+
+export interface ApiSpecAcronyms {
+	readonly version: string;
+	readonly categories: readonly string[];
+	readonly acronyms: readonly ApiSpecAcronym[];
+}
+
+export interface ApiSpecOperationEnrichment {
+	readonly dangerLevel?: "low" | "medium" | "high";
+	readonly confirmationRequired?: boolean;
+	readonly sideEffects?: {
+		readonly creates?: readonly string[];
+		readonly deletes?: readonly string[];
+		readonly modifies?: readonly string[];
+	};
+	readonly discoveredResponseTime?: {
+		readonly p50Ms: number;
+		readonly p95Ms: number;
+		readonly p99Ms: number;
+		readonly sampleCount: number;
+		readonly source: string;
+	};
+	readonly requiredFields?: readonly string[];
+	readonly operationMetadata?: {
+		readonly purpose: string;
+		readonly prerequisites?: readonly string[];
+		readonly postconditions?: readonly string[];
+		readonly commonErrors?: readonly {
+			readonly code: number;
+			readonly message: string;
+			readonly resolution: string;
+		}[];
+		readonly performanceImpact?: {
+			readonly latency: string;
+			readonly resourceUsage: string;
+		};
+	};
+}
+
+export interface ApiSpecMinimumConfiguration {
+	readonly required_fields: readonly string[];
+	readonly example_yaml?: string;
+	readonly example_json?: string;
+	readonly example_curl?: string;
+	readonly description?: string;
+	readonly mutually_exclusive_groups?: readonly unknown[];
+	readonly [key: string]: unknown;
+}
+
+export interface ApiSpecSchemaEnrichment {
+	readonly recommendedOneofVariant?: Readonly<Record<string, string>>;
+	readonly minimumConfiguration?: ApiSpecMinimumConfiguration;
+}
+
+export interface ApiSpecDomainEnrichments {
+	readonly operationMeta: Readonly<Record<string, ApiSpecOperationEnrichment>>;
+	readonly schemaEnrichments: Readonly<Record<string, ApiSpecSchemaEnrichment>>;
+}
+
+export interface ApiSpecValidationResourceEntry {
+	readonly create?: readonly string[];
+	readonly update?: readonly string[];
+	readonly minimum_config?: readonly string[];
+	readonly [key: string]: unknown;
+}
+
+export interface ApiSpecIndex {
+	readonly version: string;
+	readonly timestamp: string;
+	readonly domains: readonly ApiSpecDomainEntry[];
+	readonly criticalResources?: readonly string[];
+	readonly guidedWorkflows?: ApiSpecGuidedWorkflows;
+	readonly errorResolution?: ApiSpecErrorResolution;
+	readonly acronyms?: ApiSpecAcronyms;
+}
+
+export interface OpenAPIPathOperation {
+	readonly summary?: string;
+	readonly description?: string;
+	readonly operationId?: string;
+	readonly parameters?: readonly Record<string, unknown>[];
+	readonly requestBody?: Record<string, unknown>;
+	readonly responses?: Record<string, unknown>;
+	readonly [key: string]: unknown;
+}
+
+export interface OpenAPISpec {
+	readonly info: {
+		readonly title: string;
+		readonly version: string;
+		readonly [key: string]: unknown;
+	};
+	readonly paths: Record<string, Record<string, OpenAPIPathOperation>>;
+	readonly components?: {
+		readonly schemas?: Record<string, Record<string, unknown>>;
+		readonly [key: string]: unknown;
+	};
+	readonly [key: string]: unknown;
+}

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

@@ -0,0 +1,97 @@
+/**
+ * Protocol handler for artifact:// URLs.
+ *
+ * Resolves artifact IDs to files in the session artifacts directory.
+ * Unlike agent://, artifacts are raw text with no JSON extraction.
+ *
+ * URL form:
+ * - artifact://<id> - Full artifact content
+ *
+ * Pagination is handled by the read tool via offset/limit parameters.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { isEnoent } from "@f5xc-salesdemos/pi-utils";
+import type { InternalResource, InternalUrl, ProtocolHandler } from "./types";
+
+export interface ArtifactProtocolOptions {
+	/**
+	 * Returns the artifacts directory path, or null if no session.
+	 */
+	getArtifactsDir: () => string | null;
+}
+
+/**
+ * List available artifact IDs in the directory.
+ */
+async function listAvailableArtifacts(artifactsDir: string): Promise<string[]> {
+	try {
+		const files = await fs.readdir(artifactsDir);
+		return files
+			.filter(f => /^\d+\./.test(f))
+			.map(f => f.split(".")[0])
+			.sort((a, b) => Number(a) - Number(b));
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * Handler for artifact:// URLs.
+ *
+ * Resolves numeric artifact IDs to their text content.
+ * Artifacts are created by tools when output is truncated.
+ */
+export class ArtifactProtocolHandler implements ProtocolHandler {
+	readonly scheme = "artifact";
+
+	constructor(private readonly options: ArtifactProtocolOptions) {}
+
+	async resolve(url: InternalUrl): Promise<InternalResource> {
+		const artifactsDir = this.options.getArtifactsDir();
+		if (!artifactsDir) {
+			throw new Error("No session - artifacts unavailable");
+		}
+
+		// Extract artifact ID from host
+		const id = url.rawHost || url.hostname;
+		if (!id) {
+			throw new Error("artifact:// URL requires a numeric ID: artifact://0");
+		}
+
+		// Validate ID is numeric
+		if (!/^\d+$/.test(id)) {
+			throw new Error(`artifact:// ID must be numeric, got: ${id}`);
+		}
+
+		// Check directory exists and find file matching ID prefix
+		let files: string[];
+		try {
+			files = await fs.readdir(artifactsDir);
+		} catch (err) {
+			if (isEnoent(err)) {
+				throw new Error("No artifacts directory found");
+			}
+			throw err;
+		}
+
+		const match = files.find(f => f.startsWith(`${id}.`));
+
+		if (!match) {
+			const available = await listAvailableArtifacts(artifactsDir);
+			const availableStr = available.length > 0 ? available.join(", ") : "none";
+			throw new Error(`Artifact ${id} not found. Available: ${availableStr}`);
+		}
+
+		const filePath = path.join(artifactsDir, match);
+		const content = await Bun.file(filePath).text();
+
+		return {
+			url: url.href,
+			content,
+			contentType: "text/plain",
+			size: Buffer.byteLength(content, "utf-8"),
+			sourcePath: filePath,
+		};
+	}
+}

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

@@ -0,0 +1,88 @@
+// AUTO-GENERATED — do not edit. Run `bun generate-branding-index` to regenerate.
+
+export const BRANDING_VERSION = "2.0.0";
+
+export const BRANDING_CANONICAL = {
+	managed_kubernetes: {
+		long_form: "Managed Kubernetes",
+		description:
+			"Enterprise-grade Kubernetes cluster management. Full cluster control with RBAC, pod security, and container registry management.\n",
+		legacy_names: ["AppStack", "VoltStack", "voltstack_site"],
+		comparable_to: ["AWS EKS", "Azure AKS", "Google GKE"],
+	},
+	virtual_kubernetes: {
+		long_form: "Virtual Kubernetes",
+		description:
+			"Simplified, multi-tenant container orchestration. Optimized for distributed edge deployments with restricted Kubernetes capabilities.\n",
+		legacy_names: ["vK8s", "virtual_k8s"],
+		comparable_to: ["AWS ECS", "Azure Container Services", "Cloud Run"],
+	},
+} as const;
+
+export const BRANDING_DEPRECATIONS = {
+	terraform_provider: {
+		deprecated: {
+			registry: "registry.terraform.io/providers/volterraedge/volterra",
+			source: "volterraedge/volterra",
+			github: "github.com/volterraedge/terraform-provider-volterra",
+			status: "active-but-deprecated",
+			last_version: "0.11.49",
+			downloads: "1M+",
+			note: "Still live on registry with no deprecation notice. High risk of AI model recommendation due to training data prevalence.\n",
+		},
+		canonical: {
+			registry: "registry.terraform.io/providers/f5xc-salesdemos/xcsh",
+			source: "f5xc-salesdemos/xcsh",
+			github: "github.com/f5xc-salesdemos/terraform-provider-xcsh",
+			docs: "https://f5xc-salesdemos.github.io/terraform-provider-xcsh/",
+			llms_txt: "https://f5xc-salesdemos.github.io/terraform-provider-xcsh/llms.txt",
+		},
+		required_providers_block:
+			'terraform {\n  required_providers {\n    xcsh = {\n      source = "f5xc-salesdemos/xcsh"\n    }\n  }\n}\n',
+	},
+	api_endpoint: {
+		deprecated: {
+			url: "console.ves.volterra.io",
+		},
+		canonical: {
+			note: "Tenant-specific. No hardcoded default. Require XCSH_API_URL env var.",
+		},
+	},
+	documentation: {
+		deprecated: {
+			note: "docs.cloud.f5.com references to Volterra provider point to the deprecated volterraedge/volterra registry.\n",
+		},
+		canonical: {
+			url: "https://f5xc-salesdemos.github.io/terraform-provider-xcsh/",
+		},
+	},
+} as const;
+
+export const BRANDING_GLOSSARY = {
+	CE: {
+		term: "Customer Edge",
+		definition: "F5 XC edge deployment infrastructure for distributed applications",
+	},
+	RE: {
+		term: "Regional Edge",
+		definition: "F5 XC globally distributed edge network infrastructure",
+	},
+} as const;
+
+export const BRANDING_DOMAIN = {
+	virtual_kubernetes: {
+		title: "Virtual Kubernetes",
+		description:
+			'Virtual Kubernetes provides simplified, multi-tenant container orchestration optimized for distributed edge deployments. Formerly known as "vK8s".\n',
+	},
+	managed_kubernetes: {
+		title: "Managed Kubernetes",
+		description:
+			'Managed Kubernetes provides enterprise-grade cluster management with full RBAC, pod security, and container registry support. Formerly known as "AppStack".\n',
+	},
+	sites: {
+		title: "Customer Edge Sites",
+		description:
+			"Site deployment and management across cloud providers (AWS VPC, Azure VNET, GCP VPC), Managed Kubernetes deployments (formerly AppStack), and Secure Mesh deployments for networking-focused edge sites.\n",
+	},
+} as const;