@f5xc-salesdemos/xcsh 19.42.0 → 19.42.2

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@f5xc-salesdemos/xcsh",
-	"version": "19.42.0",
+	"version": "19.42.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/f5xc-salesdemos/xcsh",
 	"author": "Can Boluk",
@@ -39,6 +39,7 @@
 		"fix": "biome check --write --unsafe . && bun run format-prompts && bun run generate-docs-index && bun run generate-api-spec-index && bun run generate-build-info",
 		"fmt": "biome format --write . && bun run format-prompts",
 		"format-prompts": "bun scripts/format-prompts.ts",
+		"mermaid:gallery": "bun scripts/mermaid-gallery.ts",
 		"generate-docs-index": "bun scripts/generate-docs-index.ts",
 		"generate-api-spec-index": "bun scripts/generate-api-spec-index.ts",
 		"generate-branding-index": "bun scripts/generate-branding-index.ts",
@@ -51,13 +52,13 @@
 	"dependencies": {
 		"@agentclientprotocol/sdk": "0.16.1",
 		"@mozilla/readability": "^0.6",
-		"@f5xc-salesdemos/xcsh-stats": "19.42.0",
-		"@f5xc-salesdemos/pi-agent-core": "19.42.0",
-		"@f5xc-salesdemos/pi-ai": "19.42.0",
-		"@f5xc-salesdemos/pi-natives": "19.42.0",
-		"@f5xc-salesdemos/pi-resource-management": "19.42.0",
-		"@f5xc-salesdemos/pi-tui": "19.42.0",
-		"@f5xc-salesdemos/pi-utils": "19.42.0",
+		"@f5xc-salesdemos/xcsh-stats": "19.42.2",
+		"@f5xc-salesdemos/pi-agent-core": "19.42.2",
+		"@f5xc-salesdemos/pi-ai": "19.42.2",
+		"@f5xc-salesdemos/pi-natives": "19.42.2",
+		"@f5xc-salesdemos/pi-resource-management": "19.42.2",
+		"@f5xc-salesdemos/pi-tui": "19.42.2",
+		"@f5xc-salesdemos/pi-utils": "19.42.2",
 		"@sinclair/typebox": "^0.34",
 		"@xterm/headless": "^6.0",
 		"ajv": "^8.20",

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();

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

@@ -17,17 +17,17 @@ export interface BuildInfo {
 }
 
 export const BUILD_INFO: BuildInfo = {
-	"version": "19.42.0",
-	"commit": "5959e8371dc1aaa802e7a5b3bc51642328816b2a",
-	"shortCommit": "5959e83",
+	"version": "19.42.2",
+	"commit": "a018af25c2adec4357b1aa63213417ef9331ef18",
+	"shortCommit": "a018af2",
 	"branch": "main",
-	"tag": "v19.42.0",
-	"commitDate": "2026-06-24T01:36:24Z",
-	"buildDate": "2026-06-24T02:03:24.964Z",
+	"tag": "v19.42.2",
+	"commitDate": "2026-06-24T03:15:55Z",
+	"buildDate": "2026-06-24T03:45:49.205Z",
 	"dirty": true,
 	"prNumber": "",
 	"repoUrl": "https://github.com/f5xc-salesdemos/xcsh",
 	"repoSlug": "f5xc-salesdemos/xcsh",
-	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/5959e8371dc1aaa802e7a5b3bc51642328816b2a",
-	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v19.42.0"
+	"commitUrl": "https://github.com/f5xc-salesdemos/xcsh/commit/a018af25c2adec4357b1aa63213417ef9331ef18",
+	"releaseUrl": "https://github.com/f5xc-salesdemos/xcsh/releases/tag/v19.42.2"
 };

package/src/modes/theme/mermaid-cache.ts

@@ -3,6 +3,7 @@ import {
 	logger,
 	type MermaidAsciiRenderOptions,
 	type MermaidColorMode,
+	mermaidSourceExceedsLimit,
 	pickColorMode,
 	renderMermaidAsciiSafe,
 	tintMermaidNodes,
@@ -48,13 +49,30 @@ export interface RenderMermaidThemedOptions {
  * Result is memoized per (source, theme, colorMode). Returns null on parse failure.
  */
 export function renderMermaidThemed(source: string, theme: Theme, opts?: RenderMermaidThemedOptions): string | null {
+	// Oversized graphs can hang the synchronous pathfinder for tens of seconds; skip
+	// them so the display falls back to the raw code block instead of freezing the UI.
+	if (mermaidSourceExceedsLimit(source)) return null;
+
 	const mode = colorModeFor(theme, opts?.colorMode);
-	const key = `${Bun.hash(source.trim())}|${mode}:${paletteSignature(theme)}`;
+	// Layout options (useAscii, padding, …) change the output, so they must be part
+	// of the key. Omitted when absent so the key matches mermaidThemeSignature() —
+	// the no-options form used by the inline-markdown prerender/lookup path.
+	const optsSig = opts?.render && Object.keys(opts.render).length > 0 ? `|${JSON.stringify(opts.render)}` : "";
+	const key = `${Bun.hash(source.trim())}|${mode}:${paletteSignature(theme)}${optsSig}`;
 	const cached = cache.get(key);
 	if (cached !== undefined) return cached;
 
 	const asciiTheme = buildMermaidAsciiTheme(theme);
-	const colored = renderMermaidAsciiSafe(source, { ...opts?.render, colorMode: mode, theme: asciiTheme });
+	// Compact defaults: beautiful-mermaid's paddingX/paddingY of 5 spreads nodes far
+	// apart and bloats the diagram. Tighter spacing reads more elegantly and helps it
+	// fit the transcript width. Callers can still override via opts.render.
+	const colored = renderMermaidAsciiSafe(source, {
+		paddingX: 2,
+		paddingY: 1,
+		...opts?.render,
+		colorMode: mode,
+		theme: asciiTheme,
+	});
 	if (colored == null) {
 		cache.set(key, null);
 		return null;

package/src/tools/mermaid-renderer.ts

@@ -10,7 +10,6 @@ import type { RenderMermaidToolDetails } from "./render-mermaid";
 import { addSection, formatErrorMessage, replaceTabs } from "./render-utils";
 
 const TOOL_TITLE = "Mermaid";
-const MAX_DIAGRAM_LINES = 40;
 
 /** Human-friendly caption for the diagram-type badge in the block header. */
 function diagramTypeLabel(type: MermaidDiagramType): string {
@@ -77,8 +76,9 @@ export const mermaidRenderer = {
 		const caption = source ? diagramTypeLabel(detectDiagramType(source)) : "diagram";
 
 		// Keep the diagram's own colors — do NOT recolor each line a flat tool color.
+		// Show the FULL diagram: truncating a diagram with "… N more lines" defeats the purpose.
 		const diagramLines = diagramText.split("\n").map(line => replaceTabs(line));
-		addSection(sections, "Diagram", diagramLines, uiTheme, MAX_DIAGRAM_LINES);
+		addSection(sections, "Diagram", diagramLines, uiTheme);
 
 		if (result.details?.artifactId) {
 			meta.push(uiTheme.fg("dim", `artifact:${result.details.artifactId.slice(0, 8)}`));
@@ -98,7 +98,12 @@ export const mermaidRenderer = {
 		return {
 			render(width: number): string[] {
 				const state = options.isPartial ? "pending" : "success";
-				return outputBlock.render({ header, state, sections, width, borderColor: F5_TOOL_BORDER_COLOR }, uiTheme);
+				return outputBlock.render(
+					// Clip, don't wrap: a diagram is a fixed grid — word-wrapping reflows it
+					// and breaks alignment. Wide diagrams are truncated to the block width.
+					{ header, state, sections, width, borderColor: F5_TOOL_BORDER_COLOR, wrapContent: false },
+					uiTheme,
+				);
 			},
 			invalidate() {
 				outputBlock.invalidate();

package/src/tools/render-mermaid.ts

@@ -4,7 +4,12 @@ import type {
 	AgentToolResult,
 	AgentToolUpdateCallback,
 } from "@f5xc-salesdemos/pi-agent-core";
-import { type MermaidAsciiRenderOptions, prompt, renderMermaidAscii } from "@f5xc-salesdemos/pi-utils";
+import {
+	type MermaidAsciiRenderOptions,
+	mermaidSourceExceedsLimit,
+	prompt,
+	renderMermaidAsciiSafe,
+} from "@f5xc-salesdemos/pi-utils";
 import { type Static, Type } from "@sinclair/typebox";
 import renderMermaidDescription from "../prompts/tools/render-mermaid.md" with { type: "text" };
 import type { ToolSession } from "./index";
@@ -55,7 +60,24 @@ export class RenderMermaidTool implements AgentTool<typeof renderMermaidSchema,
 		_onUpdate?: AgentToolUpdateCallback<RenderMermaidToolDetails>,
 		_context?: AgentToolContext,
 	): Promise<AgentToolResult<RenderMermaidToolDetails>> {
-		const ascii = renderMermaidAscii(params.mermaid, sanitizeRenderConfig(params.config));
+		// Reject oversized graphs up front: beautiful-mermaid's pathfinder can hang
+		// for tens of seconds and then throw `RangeError: Out of memory` on them.
+		// Throwing here (fast) surfaces a clean tool error the agent can recover from.
+		if (mermaidSourceExceedsLimit(params.mermaid)) {
+			throw new Error(
+				"Mermaid diagram is too large to render safely. Reduce the number of nodes/edges and try again.",
+			);
+		}
+
+		// Safe variant: a parse failure or memory blow-up becomes null rather than a
+		// raw RangeError, so we can throw a clear, actionable message instead.
+		const ascii = renderMermaidAsciiSafe(params.mermaid, sanitizeRenderConfig(params.config));
+		if (ascii == null || ascii.trim() === "") {
+			throw new Error(
+				"Failed to render the Mermaid diagram — the syntax may be unsupported or too complex. Use newline-separated statements (no ';') and try a simpler diagram.",
+			);
+		}
+
 		const { path: artifactPath, id: artifactId } =
 			(await this.session.allocateOutputArtifact?.("render_mermaid")) ?? {};
 		if (artifactPath) {

package/src/tui/output-block.ts

@@ -6,7 +6,7 @@ import type { Theme, ThemeColor } from "../modes/theme/theme";
 import { getImageLineMask } from "../utils/image-passthrough";
 import type { State } from "./types";
 import type { RenderCache } from "./utils";
-import { getStateBgColor, Hasher, padToWidth, truncateToWidth } from "./utils";
+import { Ellipsis, getStateBgColor, Hasher, padToWidth, truncateToWidth } from "./utils";
 
 /**
  * Border color override for F5-branded tool renderers.
@@ -23,6 +23,12 @@ export interface OutputBlockOptions {
 	applyBg?: boolean;
 	/** Override the state-derived border color. Always takes precedence, including on error. Use for branded core tools. */
 	borderColor?: ThemeColor;
+	/**
+	 * Word-wrap content lines to fit the inner width (default). Set false to CLIP
+	 * (truncate) instead — required for pre-formatted grid content like mermaid
+	 * diagrams, where wrapping reflows characters and destroys alignment.
+	 */
+	wrapContent?: boolean;
 }
 
 export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): string[] {
@@ -34,6 +40,7 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 		width,
 		applyBg = true,
 		borderColor: borderColorOverride,
+		wrapContent = true,
 	} = options;
 	const h = theme.boxSharp.horizontal;
 	const v = theme.boxSharp.vertical;
@@ -100,7 +107,11 @@ export function renderOutputBlock(options: OutputBlockOptions, theme: Theme): st
 				lines.push(line);
 				continue;
 			}
-			const wrappedLines = wrapTextWithAnsi(line.trimEnd(), contentWidth);
+			const wrappedLines = wrapContent
+				? wrapTextWithAnsi(line.trimEnd(), contentWidth)
+				: // Clip cleanly with no trailing ellipsis — a column of "…" down the
+					// right edge of a clipped diagram is clutter, not information.
+					[truncateToWidth(line.trimEnd(), contentWidth, Ellipsis.Omit)];
 			for (const wrappedLine of wrappedLines) {
 				const innerPadding = padding(Math.max(0, contentWidth - visibleWidth(wrappedLine)));
 				const fullLine = `${contentPrefix}${wrappedLine}${innerPadding}${contentSuffix}`;
@@ -150,6 +161,7 @@ export class CachedOutputBlock {
 		h.optional(options.state);
 		h.bool(options.applyBg ?? true);
 		h.optional(options.borderColor);
+		h.bool(options.wrapContent ?? true);
 		if (options.sections) {
 			for (const s of options.sections) {
 				h.optional(s.label);