@f5-sales-demo/xcsh 19.51.2

package/scripts/generate-build-info.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+
+import * as path from "node:path";
+import { $ } from "bun";
+import {
+	type EnvLike,
+	resolveBranch,
+	resolveCommit,
+	resolveDirty,
+	resolvePrNumber,
+	resolveTag,
+} from "./build-info/resolvers";
+
+const repoRoot = path.resolve(import.meta.dir, "../../..");
+const outputPath = path.resolve(import.meta.dir, "../src/internal-urls/build-info.generated.ts");
+const utilsPackageJsonPath = path.resolve(repoRoot, "packages/utils/package.json");
+
+const REPO_SLUG = "f5xc-salesdemos/xcsh";
+const REPO_URL = `https://github.com/${REPO_SLUG}`;
+
+async function git(args: string[]): Promise<string> {
+	try {
+		const result = await $`git ${args}`.cwd(repoRoot).quiet();
+		return result.stdout.toString().trim();
+	} catch {
+		return "";
+	}
+}
+
+async function ghPrForSha(sha: string): Promise<string> {
+	try {
+		const result =
+			await $`gh pr list --search ${sha} --state merged --json number --limit 1 --jq ${".[0].number // empty"}`
+				.cwd(repoRoot)
+				.quiet();
+		return result.stdout.toString().trim();
+	} catch {
+		return "";
+	}
+}
+
+async function resolveCommitDate(sha: string): Promise<string> {
+	if (!sha) return "";
+	return await git(["log", "-1", "--format=%cI", sha]);
+}
+
+const env = process.env as EnvLike;
+
+const utilsPackageJson = (await Bun.file(utilsPackageJsonPath).json()) as { version: string };
+const version = utilsPackageJson.version;
+const commit = await resolveCommit(env, git);
+const shortCommit = commit ? commit.slice(0, 7) : "";
+const branch = await resolveBranch(env, git);
+const tag = await resolveTag(env, git);
+const commitDate = await resolveCommitDate(commit);
+const dirty = await resolveDirty(env, git);
+const prNumber = await resolvePrNumber(commit, env, ghPrForSha);
+const buildDate = new Date().toISOString();
+const releaseUrl = `${REPO_URL}/releases/tag/v${version}`;
+const commitUrl = commit ? `${REPO_URL}/commit/${commit}` : REPO_URL;
+
+const output = [
+	"// Auto-generated by scripts/generate-build-info.ts - DO NOT EDIT",
+	"",
+	"export interface BuildInfo {",
+	"\treadonly version: string;",
+	"\treadonly commit: string;",
+	"\treadonly shortCommit: string;",
+	"\treadonly branch: string;",
+	"\treadonly tag: string;",
+	"\treadonly commitDate: string;",
+	"\treadonly buildDate: string;",
+	"\treadonly dirty: boolean;",
+	"\treadonly prNumber: string;",
+	"\treadonly repoUrl: string;",
+	"\treadonly repoSlug: string;",
+	"\treadonly commitUrl: string;",
+	"\treadonly releaseUrl: string;",
+	"}",
+	"",
+	`export const BUILD_INFO: BuildInfo = ${JSON.stringify(
+		{
+			version,
+			commit,
+			shortCommit,
+			branch,
+			tag,
+			commitDate,
+			buildDate,
+			dirty,
+			prNumber,
+			repoUrl: REPO_URL,
+			repoSlug: REPO_SLUG,
+			commitUrl,
+			releaseUrl,
+		},
+		null,
+		"\t",
+	)};`,
+	"",
+].join("\n");
+
+await Bun.write(outputPath, output);
+console.log(
+	`Generated ${path.relative(process.cwd(), outputPath)} (v${version}, ${shortCommit || "no-commit"}, branch=${branch}${tag ? `, tag=${tag}` : ""}${dirty ? ", dirty" : ""})`,
+);

package/scripts/generate-console-catalog.ts

@@ -0,0 +1,88 @@
+#!/usr/bin/env bun
+// scripts/generate-console-catalog.ts
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const repoRoot = path.resolve(import.meta.dir, "..");
+const outputPath = path.join(repoRoot, "src/internal-urls/console-catalog.generated.ts");
+
+function resolveCatalogRoot(): string | null {
+	const fromEnv = process.env.CONSOLE_CATALOG_DIR;
+	if (fromEnv && fs.existsSync(path.join(fromEnv, "catalog"))) return fromEnv;
+	// Local sibling checkout: <workspace>/console
+	const sibling = path.resolve(repoRoot, "../../../console");
+	if (fs.existsSync(path.join(sibling, "catalog"))) return sibling;
+	// TODO(P2): add release-artifact download mirroring generate-api-spec-index.ts.
+	return null;
+}
+
+function readYamlDir(dir: string, keyFn: (rel: string) => string): Record<string, string> {
+	const out: Record<string, string> = {};
+	if (!fs.existsSync(dir)) return out;
+	const walk = (d: string) => {
+		for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+			const full = path.join(d, entry.name);
+			if (entry.isDirectory()) walk(full);
+			else if (entry.name.endsWith(".yaml")) {
+				const rel = path.relative(dir, full).replace(/\.yaml$/, "");
+				out[keyFn(rel)] = fs.readFileSync(full, "utf-8");
+			}
+		}
+	};
+	walk(dir);
+	// Sort keys for deterministic output regardless of readdir order.
+	return Object.fromEntries(
+		Object.keys(out)
+			.sort()
+			.map(k => [k, out[k]]),
+	);
+}
+
+function build(): {
+	version: string;
+	workflows: Record<string, string>;
+	resources: Record<string, string>;
+	routes: Record<string, string>;
+	navigation: string | null;
+} {
+	const root = resolveCatalogRoot();
+	if (!root) {
+		console.warn("console catalogue source not found; emitting empty catalogue");
+		return { version: "unavailable", workflows: {}, resources: {}, routes: {}, navigation: null };
+	}
+	const catalog = path.join(root, "catalog");
+	// workflows keyed "<resource>/<operation>" (directory/file)
+	const workflows = readYamlDir(path.join(catalog, "workflows"), rel => rel.split(path.sep).join("/"));
+	// resources/routes keyed by basename id
+	const resources = readYamlDir(path.join(catalog, "resources"), rel => path.basename(rel));
+	const routes = readYamlDir(path.join(catalog, "routes"), rel => path.basename(rel));
+	const navPath = path.join(catalog, "navigation/console-tree.yaml");
+	const navigation = fs.existsSync(navPath) ? fs.readFileSync(navPath, "utf-8") : null;
+	const version = process.env.CONSOLE_CATALOG_VERSION ?? "local";
+	return { version, workflows, resources, routes, navigation };
+}
+
+const data = build();
+
+// Fix A: when the source was not found AND the output file already exists,
+// keep the committed catalogue rather than overwriting it with empty data.
+if (data.version === "unavailable" && fs.existsSync(outputPath)) {
+	console.log("console catalogue source not found; keeping existing generated module");
+	process.exit(0);
+}
+
+const output = [
+	"// Auto-generated by scripts/generate-console-catalog.ts - DO NOT EDIT",
+	"",
+	`import type { ConsoleCatalogData } from "./console-catalog-types";`,
+	"",
+	`export const CONSOLE_CATALOG_VERSION = ${JSON.stringify(data.version)};`,
+	"",
+	`export const CONSOLE_CATALOG_DATA: ConsoleCatalogData = ${JSON.stringify(data, null, 2)};`,
+	"",
+].join("\n");
+
+await Bun.write(outputPath, output);
+console.log(
+	`Wrote ${outputPath} (workflows=${Object.keys(data.workflows).length}, resources=${Object.keys(data.resources).length})`,
+);

package/scripts/generate-console-field-metadata.ts

@@ -0,0 +1,74 @@
+#!/usr/bin/env bun
+// scripts/generate-console-field-metadata.ts
+//
+// Embeds the console field-requirements registry from the authoritative source
+// (api-specs-enriched/config/console_field_metadata.yaml) into
+// src/internal-urls/console-field-metadata.generated.ts. Mirrors the source
+// resolution of generate-api-spec-index.ts (env override → sibling checkout).
+// The registry is what `xcsh://console/<resource>` surfaces so the agent knows
+// each form's required fields + constraints before driving a create workflow.
+//
+// If api-specs-enriched is missing/incorrect field metadata, fix it UPSTREAM
+// there and re-run this — never hand-edit the generated file or patch downstream.
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parse as parseYaml } from "yaml";
+
+const repoRoot = path.resolve(import.meta.dir, "..");
+const outputPath = path.join(repoRoot, "src/internal-urls/console-field-metadata.generated.ts");
+
+/** Resolve the console_field_metadata.yaml path from api-specs-enriched. */
+function resolveMetadataFile(): string | null {
+	const candidates = [
+		process.env.API_SPECS_ENRICHED_DIR &&
+			path.join(process.env.API_SPECS_ENRICHED_DIR, "config/console_field_metadata.yaml"),
+		// Local sibling checkout: <workspace>/api-specs-enriched
+		path.resolve(repoRoot, "../../../api-specs-enriched/config/console_field_metadata.yaml"),
+		path.resolve(repoRoot, "../../../../api-specs-enriched/config/console_field_metadata.yaml"),
+	].filter(Boolean) as string[];
+	for (const c of candidates) {
+		if (fs.existsSync(c)) return c;
+	}
+	return null;
+}
+
+function build(): { version: string; resources: Record<string, Record<string, unknown>> } {
+	const file = resolveMetadataFile();
+	if (!file) {
+		console.warn("api-specs-enriched console_field_metadata.yaml not found; emitting empty registry");
+		return { version: "unavailable", resources: {} };
+	}
+	const doc = (parseYaml(fs.readFileSync(file, "utf-8")) ?? {}) as {
+		version?: string;
+		resources?: Record<string, Record<string, unknown> | null>;
+	};
+	const resources: Record<string, Record<string, unknown>> = {};
+	for (const [kind, fields] of Object.entries(doc.resources ?? {})) {
+		if (fields && typeof fields === "object") resources[kind] = fields as Record<string, unknown>;
+	}
+	const version = process.env.API_SPECS_ENRICHED_VERSION ?? doc.version ?? "local";
+	return { version, resources };
+}
+
+const data = build();
+
+// Keep the committed registry if the source wasn't found and a file already exists.
+if (data.version === "unavailable" && fs.existsSync(outputPath)) {
+	console.log("console field metadata source not found; keeping existing generated module");
+	process.exit(0);
+}
+
+const output = [
+	"// Auto-generated by scripts/generate-console-field-metadata.ts - DO NOT EDIT",
+	"// Source of truth: api-specs-enriched/config/console_field_metadata.yaml",
+	"",
+	`import type { ConsoleFieldMetadataData } from "./console-field-metadata-types";`,
+	"",
+	`export const CONSOLE_FIELD_METADATA: ConsoleFieldMetadataData = ${JSON.stringify(data, null, 2)};`,
+	"",
+].join("\n");
+
+await Bun.write(outputPath, output);
+const total = Object.values(data.resources).reduce((n, f) => n + Object.keys(f).length, 0);
+console.log(`Wrote ${outputPath} (resources=${Object.keys(data.resources).length}, fields=${total})`);

package/scripts/generate-docs-index.ts

@@ -0,0 +1,40 @@
+#!/usr/bin/env bun
+
+import * as path from "node:path";
+import { Glob } from "bun";
+
+const docsDir = path.resolve(import.meta.dir, "../../../docs");
+const outputPath = path.resolve(import.meta.dir, "../src/internal-urls/docs-index.generated.ts");
+
+const glob = new Glob("**/*.md");
+const entries: string[] = [];
+for await (const relativePath of glob.scan(docsDir)) {
+	entries.push(relativePath.split(path.sep).join("/"));
+}
+entries.sort();
+
+const docsWithContent = await Promise.all(
+	entries.map(async relativePath => ({
+		relativePath,
+		content: await Bun.file(path.join(docsDir, relativePath)).text(),
+	})),
+);
+
+const filenamesLiteral = JSON.stringify(entries);
+
+const mapEntries = docsWithContent
+	.map(({ relativePath, content }) => `\t${JSON.stringify(relativePath)}: ${JSON.stringify(content)},`)
+	.join("\n");
+const output = [
+	"// Auto-generated by scripts/generate-docs-index.ts - DO NOT EDIT",
+	"",
+	`export const EMBEDDED_DOC_FILENAMES: readonly string[] = ${filenamesLiteral};`,
+	"",
+	`export const EMBEDDED_DOCS: Readonly<Record<string, string>> = {`,
+	`${mapEntries}`,
+	`};`,
+	"",
+].join("\n");
+
+await Bun.write(outputPath, output);
+console.log(`Generated ${path.relative(process.cwd(), outputPath)} (${entries.length} docs)`);

package/scripts/generate-template.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env bun
+/**
+ * Pre-compute the HTML template at publish time.
+ * This avoids the Bun macro restriction in node_modules.
+ */
+
+const dir = new URL("../src/export/html/", import.meta.url).pathname;
+
+// Read all files
+const html = await Bun.file(`${dir}template.html`).text();
+const css = await Bun.file(`${dir}template.css`).text();
+const js = await Bun.file(`${dir}template.js`).text();
+
+// Minify CSS
+const minifiedCss = css
+	.replace(/\/\*[\s\S]*?\*\//g, "")
+	.replace(/\s+/g, " ")
+	.replace(/\s*([{}:;,])\s*/g, "$1")
+	.trim();
+
+// Inline everything
+const template = html
+	.replace("<template-css/>", `<style>${minifiedCss}</style>`)
+	.replace("<template-js/>", `<script>${js}</script>`);
+
+// Write generated file
+const output = `// Auto-generated by scripts/generate-template.ts - DO NOT EDIT
+export const TEMPLATE = ${JSON.stringify(template)};
+`;
+
+await Bun.write(`${dir}template.generated.ts`, output);
+console.log("Generated template.generated.ts");

package/scripts/generate-terraform-index.ts

@@ -0,0 +1,81 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+const OUTPUT_FILE = path.join(import.meta.dir, "..", "src", "internal-urls", "terraform-index.generated.ts");
+
+const LOCAL_JSON_PATH = path.resolve(
+	import.meta.dir,
+	"..",
+	"..",
+	"..",
+	"..",
+	"terraform-provider-xcsh",
+	"docs",
+	"terraform-llms-index.json",
+);
+
+const GITHUB_RAW_URL =
+	"https://raw.githubusercontent.com/f5xc-salesdemos/terraform-provider-xcsh/main/docs/terraform-llms-index.json";
+
+async function loadTerraformIndex(): Promise<unknown> {
+	const localFile = Bun.file(LOCAL_JSON_PATH);
+	if (await localFile.exists()) {
+		console.log(`Reading from local checkout: ${LOCAL_JSON_PATH}`);
+		return localFile.json();
+	}
+
+	console.log(`Local not found, fetching from ${GITHUB_RAW_URL}`);
+	const headers: Record<string, string> = {};
+	const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+	if (token) {
+		headers.Authorization = `token ${token}`;
+	}
+
+	const response = await fetch(GITHUB_RAW_URL, { headers });
+	if (!response.ok) {
+		throw new Error(`Failed to fetch terraform-llms-index.json: ${response.status} ${response.statusText}`);
+	}
+	return response.json();
+}
+
+// Backfill provider fields that older terraform-llms-index.json revisions lack, so the
+// generated index always satisfies TerraformProvider regardless of which provider-repo
+// revision it was fetched from (the source repo is the authority once it ships them).
+const DEFAULT_CONFIG_BLOCK = 'provider "xcsh" {}';
+const DEFAULT_AUTH_METHODS = [
+	'REQUIRED: every .tf must contain a `provider "xcsh" {}` block. Without it Terraform errors: "Provider requires explicit configuration. Add a provider block".',
+	"Configure exactly ONE auth method, via environment variables (preferred) or explicit arguments in the provider block:",
+	"api_token (env XCSH_API_TOKEN) — API token authentication.",
+	"api_p12_file + p12_password (env XCSH_P12_FILE + XCSH_P12_PASSWORD) — PKCS#12 certificate authentication.",
+	"api_cert + api_key (env XCSH_CERT + XCSH_KEY) — PEM certificate authentication.",
+	"api_url (env XCSH_API_URL) — tenant base URL without /api suffix, e.g. https://your-tenant.console.ves.volterra.io.",
+];
+
+function normalizeProvider(data: unknown): unknown {
+	if (data && typeof data === "object" && "provider" in data) {
+		const provider = (data as { provider: Record<string, unknown> }).provider;
+		if (provider && typeof provider === "object") {
+			if (typeof provider.config_block !== "string") provider.config_block = DEFAULT_CONFIG_BLOCK;
+			if (!Array.isArray(provider.auth_methods)) provider.auth_methods = DEFAULT_AUTH_METHODS;
+		}
+	}
+	return data;
+}
+
+function generateTypeScript(data: unknown): string {
+	const lines = [
+		"// AUTO-GENERATED — do not edit. Run `bun generate-terraform-index` to regenerate.",
+		"",
+		'import type { TerraformIndex } from "./terraform-types";',
+		"",
+		`export const TERRAFORM_INDEX: TerraformIndex = ${JSON.stringify(data, null, "\t")} as const;`,
+		"",
+	];
+	return lines.join("\n");
+}
+
+const data = normalizeProvider(await loadTerraformIndex());
+const output = generateTypeScript(data);
+await fs.writeFile(OUTPUT_FILE, output, "utf-8");
+await Bun.$`bunx biome format --write ${OUTPUT_FILE}`.quiet();
+console.log(`Generated ${OUTPUT_FILE}`);

package/scripts/mermaid-gallery.ts

@@ -0,0 +1,132 @@
+#!/usr/bin/env bun
+/**
+ * F5 XC Mermaid — visual gallery harness for human UAT.
+ *
+ * Renders the F5 Distributed Cloud mermaid sample library through the real
+ * display pipeline (themed per-role palette + per-node tint) so you can visually
+ * inspect the colorized output in your own terminal and give feedback.
+ *
+ * Usage:
+ *   bun scripts/mermaid-gallery.ts                       # all samples, dark theme, truecolor
+ *   bun scripts/mermaid-gallery.ts --theme light
+ *   bun scripts/mermaid-gallery.ts --color ansi256       # none | ansi256 | truecolor
+ *   bun scripts/mermaid-gallery.ts --ascii               # ASCII box chars instead of Unicode
+ *   bun scripts/mermaid-gallery.ts --type flowchart      # filter by diagram type
+ *   bun scripts/mermaid-gallery.ts --filter waf          # regex over id/category/prompt
+ *   bun scripts/mermaid-gallery.ts --list                # list samples, don't render
+ *
+ * Tip: pipe through `less -R` to page while keeping color.
+ */
+import type { MermaidColorMode } from "@f5xc-salesdemos/pi-utils";
+import { renderMermaidThemed } from "../src/modes/theme/mermaid-cache";
+import { getThemeByName } from "../src/modes/theme/theme";
+import { XC_MERMAID_SAMPLES, type XcMermaidSample } from "../test/fixtures/xc-mermaid-samples";
+
+interface Args {
+	theme: string;
+	color: MermaidColorMode;
+	ascii: boolean;
+	type?: string;
+	filter?: RegExp;
+	list: boolean;
+}
+
+function parseArgs(argv: string[]): Args {
+	const args: Args = { theme: "xcsh-dark", color: "truecolor", ascii: false, list: false };
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		const next = () => argv[++i] ?? "";
+		switch (a) {
+			case "--theme":
+				args.theme = next() === "light" ? "xcsh-light" : "xcsh-dark";
+				break;
+			case "--color":
+				args.color = next() as MermaidColorMode;
+				break;
+			case "--ascii":
+				args.ascii = true;
+				break;
+			case "--type":
+				args.type = next();
+				break;
+			case "--filter":
+				args.filter = new RegExp(next(), "i");
+				break;
+			case "--list":
+				args.list = true;
+				break;
+			case "--help":
+			case "-h":
+				console.log(
+					"bun scripts/mermaid-gallery.ts [--theme dark|light] [--color none|ansi256|truecolor] [--ascii] [--type <t>] [--filter <regex>] [--list]",
+				);
+				process.exit(0);
+		}
+	}
+	return args;
+}
+
+function selectSamples(args: Args): XcMermaidSample[] {
+	return XC_MERMAID_SAMPLES.filter(s => {
+		if (args.type && s.type !== args.type) return false;
+		if (args.filter && !args.filter.test(`${s.id} ${s.category} ${s.prompt}`)) return false;
+		return true;
+	});
+}
+
+async function main(): Promise<void> {
+	const args = parseArgs(process.argv.slice(2));
+	const theme = await getThemeByName(args.theme);
+	if (!theme) {
+		console.error(`Unknown theme: ${args.theme}`);
+		process.exit(1);
+	}
+	const samples = selectSamples(args);
+	const width = Math.min(process.stdout.columns ?? 100, 110);
+	const rule = (ch: string) => theme.fg("accent", ch.repeat(width));
+
+	console.log(`\n${rule("━")}`);
+	console.log(
+		theme.fg("mdHeading", "  F5 XC Mermaid Gallery") +
+			theme.fg(
+				"muted",
+				`   theme=${args.theme}  color=${args.color}  ascii=${args.ascii}  samples=${samples.length}`,
+			),
+	);
+	console.log(rule("━"));
+
+	if (args.list) {
+		for (const [i, s] of samples.entries()) {
+			console.log(
+				`  ${theme.fg("dim", String(i + 1).padStart(2, "0"))}  ` +
+					`${theme.fg("accent", s.type.padEnd(10))} ${theme.fg("mdHeading", s.id.padEnd(28))} ${theme.fg("muted", s.category)}`,
+			);
+		}
+		console.log("");
+		return;
+	}
+
+	for (const [i, s] of samples.entries()) {
+		console.log(
+			`\n${theme.fg("accent", "━━━")} ${theme.fg("dim", `[${i + 1}/${samples.length}]`)} ${theme.fg("mdHeading", s.category)} ${theme.fg("muted", "·")} ${theme.fg("success", s.type)} ${theme.fg("accent", "━".repeat(Math.max(0, width - s.category.length - s.type.length - 18)))}`,
+		);
+		console.log(`  ${theme.fg("dim", "▸")} ${theme.fg("mdLink", s.id)}`);
+		console.log(`  ${theme.fg("muted", `"${s.prompt}"`)}\n`);
+
+		const out = renderMermaidThemed(s.source, theme, { colorMode: args.color, render: { useAscii: args.ascii } });
+		if (out == null) {
+			console.log(`  ${theme.fg("error", "⚠ failed to render")}\n`);
+			continue;
+		}
+		for (const line of out.split("\n")) console.log(`  ${line}`);
+	}
+
+	console.log(`\n${rule("━")}`);
+	console.log(
+		theme.fg("muted", `  Rendered ${samples.length} sample(s). Inspect the colors above and note anything to tune `) +
+			theme.fg("dim", "(borders, labels, edges, arrows, per-node tints, contrast)."),
+	);
+	console.log(rule("━") + "\n");
+}
+
+await main();