@f5-sales-demo/pi-utils 19.51.2

package/src/i18n.test.ts

@@ -0,0 +1,213 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import {
+	getLocale,
+	getLocaleDisplayName,
+	initI18n,
+	LOCALE_DISPLAY_NAMES,
+	mapToSupportedLocale,
+	registerLocales,
+	setLocale,
+	t,
+} from "./i18n";
+
+const EN = {
+	greeting: "Hello",
+	"greeting.with.name": "Hello, {name}!",
+	"items.count.one": "{count} item",
+	"items.count.other": "{count} items",
+	"error.notFound": "File not found: {path}",
+};
+
+const JA = {
+	greeting: "こんにちは",
+	"greeting.with.name": "こんにちは、{name}さん！",
+	"items.count.one": "{count}個のアイテム",
+	"items.count.other": "{count}個のアイテム",
+	"error.notFound": "ファイルが見つかりません: {path}",
+};
+
+describe("i18n", () => {
+	beforeEach(() => {
+		registerLocales({ en: EN, ja: JA });
+		setLocale("en");
+	});
+
+	test("t() returns English string by key", () => {
+		expect(t("greeting")).toBe("Hello");
+	});
+
+	test("t() interpolates parameters", () => {
+		expect(t("greeting.with.name", { name: "World" })).toBe("Hello, World!");
+	});
+
+	test("t() falls back to key when key is missing", () => {
+		expect(t("nonexistent.key")).toBe("nonexistent.key");
+	});
+
+	test("t() handles plural: one", () => {
+		expect(t("items.count", { count: 1 })).toBe("1 item");
+	});
+
+	test("t() handles plural: other", () => {
+		expect(t("items.count", { count: 5 })).toBe("5 items");
+	});
+
+	test("setLocale() switches to Japanese", () => {
+		setLocale("ja");
+		expect(t("greeting")).toBe("こんにちは");
+		expect(t("greeting.with.name", { name: "太郎" })).toBe("こんにちは、太郎さん！");
+	});
+
+	test("getLocale() returns current locale", () => {
+		expect(getLocale()).toBe("en");
+		setLocale("ja");
+		expect(getLocale()).toBe("ja");
+	});
+
+	test("falls back to base locale (ja-jp -> ja)", () => {
+		setLocale("ja-jp");
+		expect(t("greeting")).toBe("こんにちは");
+	});
+
+	test("falls back to English for unknown locale", () => {
+		setLocale("xx");
+		expect(t("greeting")).toBe("Hello");
+	});
+
+	test("normalizes locale with underscores", () => {
+		setLocale("ja_JP");
+		expect(getLocale()).toBe("ja");
+		expect(t("greeting")).toBe("こんにちは");
+	});
+
+	test("handles locale with encoding suffix", () => {
+		setLocale("ja_JP.UTF-8");
+		expect(getLocale()).toBe("ja");
+		expect(t("greeting")).toBe("こんにちは");
+	});
+
+	test("interpolation leaves unmatched placeholders", () => {
+		expect(t("error.notFound", { path: "/foo" })).toBe("File not found: /foo");
+		expect(t("greeting.with.name", {})).toBe("Hello, {name}!");
+	});
+
+	test("initI18n() defaults to en when no env vars set", () => {
+		const oldLang = Bun.env.LANG;
+		const oldXcsh = Bun.env.XCSH_LOCALE;
+		delete Bun.env.LANG;
+		delete Bun.env.XCSH_LOCALE;
+		initI18n();
+		expect(getLocale()).toBe("en");
+		if (oldLang) Bun.env.LANG = oldLang;
+		if (oldXcsh) Bun.env.XCSH_LOCALE = oldXcsh;
+	});
+
+	test("initI18n() reads XCSH_LOCALE env var", () => {
+		Bun.env.XCSH_LOCALE = "ja";
+		initI18n();
+		expect(getLocale()).toBe("ja");
+		delete Bun.env.XCSH_LOCALE;
+		setLocale("en");
+	});
+
+	test("initI18n() prefers explicit locale argument", () => {
+		Bun.env.XCSH_LOCALE = "ja";
+		initI18n("en");
+		expect(getLocale()).toBe("en");
+		delete Bun.env.XCSH_LOCALE;
+	});
+});
+
+describe("LOCALE_DISPLAY_NAMES", () => {
+	test("has entries for all 13 supported locales", () => {
+		const expected = ["ar", "de", "en", "es", "fr", "hi", "it", "ja", "ko", "pt-br", "th", "zh-cn", "zh-tw"];
+		for (const code of expected) {
+			expect(LOCALE_DISPLAY_NAMES[code]).toBeDefined();
+			expect(typeof LOCALE_DISPLAY_NAMES[code]).toBe("string");
+		}
+	});
+
+	test("returns correct names for key locales", () => {
+		expect(LOCALE_DISPLAY_NAMES.ko).toBe("Korean");
+		expect(LOCALE_DISPLAY_NAMES.ja).toBe("Japanese");
+		expect(LOCALE_DISPLAY_NAMES.en).toBe("English");
+		expect(LOCALE_DISPLAY_NAMES["zh-cn"]).toBe("Simplified Chinese");
+	});
+});
+
+describe("getLocaleDisplayName", () => {
+	beforeEach(() => {
+		registerLocales({ en: EN, ja: JA, "zh-cn": {}, "zh-tw": {}, "pt-br": {}, fr: {}, de: {} });
+		setLocale("en");
+	});
+
+	test("returns display name for known locale", () => {
+		expect(getLocaleDisplayName("ko")).toBe("Korean");
+		expect(getLocaleDisplayName("ja")).toBe("Japanese");
+		expect(getLocaleDisplayName("fr")).toBe("French");
+	});
+
+	test("returns display name for regional variant", () => {
+		expect(getLocaleDisplayName("pt-br")).toBe("Brazilian Portuguese");
+		expect(getLocaleDisplayName("zh-cn")).toBe("Simplified Chinese");
+	});
+
+	test("returns undefined for unknown locale", () => {
+		expect(getLocaleDisplayName("xx")).toBeUndefined();
+		expect(getLocaleDisplayName("sv")).toBeUndefined();
+	});
+
+	test("returns 'English' for 'en'", () => {
+		expect(getLocaleDisplayName("en")).toBe("English");
+	});
+
+	test("normalizes case", () => {
+		expect(getLocaleDisplayName("KO")).toBe("Korean");
+		expect(getLocaleDisplayName("zh-CN")).toBe("Simplified Chinese");
+	});
+});
+
+describe("mapToSupportedLocale", () => {
+	beforeEach(() => {
+		registerLocales({ en: EN, ja: JA, "zh-cn": {}, "zh-tw": {}, "pt-br": {}, fr: {}, de: {} });
+		setLocale("en");
+	});
+
+	test("exact match", () => {
+		expect(mapToSupportedLocale("ja")).toBe("ja");
+		expect(mapToSupportedLocale("en")).toBe("en");
+	});
+
+	test("regional variant maps to base", () => {
+		expect(mapToSupportedLocale("en-US")).toBe("en");
+		expect(mapToSupportedLocale("ja-JP")).toBe("ja");
+		expect(mapToSupportedLocale("fr-FR")).toBe("fr");
+		expect(mapToSupportedLocale("de-DE")).toBe("de");
+	});
+
+	test("regional variant with exact match", () => {
+		expect(mapToSupportedLocale("pt-BR")).toBe("pt-br");
+		expect(mapToSupportedLocale("zh-CN")).toBe("zh-cn");
+		expect(mapToSupportedLocale("zh-TW")).toBe("zh-tw");
+	});
+
+	test("Apple zh-Hans maps to zh-cn", () => {
+		expect(mapToSupportedLocale("zh-Hans")).toBe("zh-cn");
+		expect(mapToSupportedLocale("zh-Hans-CN")).toBe("zh-cn");
+	});
+
+	test("Apple zh-Hant maps to zh-tw", () => {
+		expect(mapToSupportedLocale("zh-Hant")).toBe("zh-tw");
+		expect(mapToSupportedLocale("zh-Hant-TW")).toBe("zh-tw");
+	});
+
+	test("underscore format", () => {
+		expect(mapToSupportedLocale("pt_BR")).toBe("pt-br");
+		expect(mapToSupportedLocale("ja_JP.UTF-8")).toBe("ja");
+	});
+
+	test("unsupported locale returns undefined", () => {
+		expect(mapToSupportedLocale("xx")).toBeUndefined();
+		expect(mapToSupportedLocale("sv-SE")).toBeUndefined();
+	});
+});

package/src/i18n.ts

@@ -0,0 +1,90 @@
+import {
+	getLocaleDisplayName,
+	LOCALE_DISPLAY_NAMES,
+	mapToSupportedLocale,
+	normalizeLocale,
+} from "@f5xc-salesdemos/i18n-core";
+import { $pickenv } from "./env";
+
+export { getLocaleDisplayName, LOCALE_DISPLAY_NAMES, mapToSupportedLocale };
+
+type LocaleMap = Record<string, string>;
+type LocaleBundle = Record<string, LocaleMap>;
+
+let currentLocale = "en";
+let bundles: LocaleBundle = {};
+let active: LocaleMap = {};
+
+/**
+ * Register all locale bundles. Call once at startup before any t() calls.
+ * Keys are locale codes ("en", "ja", "zh-cn"), values are flat key→string maps.
+ */
+export function registerLocales(localeBundle: LocaleBundle): void {
+	bundles = localeBundle;
+	active = resolveBundle(currentLocale);
+}
+
+/**
+ * Initialize i18n from environment / config.
+ * Priority: explicit locale arg > XCSH_LOCALE env > PI_LOCALE env > LANG env > "en"
+ */
+export function initI18n(locale?: string): void {
+	const resolved =
+		locale || $pickenv("XCSH_LOCALE", "PI_LOCALE") || parseSystemLocale($pickenv("LANG", "LC_MESSAGES")) || "en";
+	setLocale(resolved);
+}
+
+export function setLocale(locale: string): void {
+	currentLocale = mapToSupportedLocale(locale) ?? normalizeLocale(locale);
+	active = resolveBundle(currentLocale);
+}
+
+export function getLocale(): string {
+	return currentLocale;
+}
+
+/**
+ * Translate a key with optional parameter interpolation.
+ * Falls back to the English string, then to the key itself.
+ *
+ * Usage:
+ *   t("cli.error.patternRequired")
+ *   t("cli.error.fileNotFound", { path: "/foo" })
+ *   t("items.count", { count: 5 })  // uses ".one" / ".other" suffixes
+ */
+export function t(key: string, params?: Record<string, string | number>): string {
+	let template = active[key];
+
+	if (template === undefined && params && typeof params.count === "number") {
+		const pluralSuffix = params.count === 1 ? ".one" : ".other";
+		template = active[key + pluralSuffix];
+		if (template === undefined) {
+			template = bundles.en?.[key + pluralSuffix] ?? bundles.en?.[key];
+		}
+	}
+
+	if (template === undefined) {
+		template = bundles.en?.[key] ?? key;
+	}
+
+	if (!params) return template;
+
+	return template.replace(/\{(\w+)\}/g, (match, name: string) => {
+		const val = params[name];
+		return val !== undefined ? String(val) : match;
+	});
+}
+
+function parseSystemLocale(raw: string | undefined): string | undefined {
+	if (!raw) return undefined;
+	const normalized = normalizeLocale(raw);
+	if (normalized === "c" || normalized === "posix") return "en";
+	return normalized;
+}
+
+function resolveBundle(locale: string): LocaleMap {
+	if (bundles[locale]) return bundles[locale];
+	const base = locale.split("-")[0];
+	if (bundles[base]) return bundles[base];
+	return bundles.en ?? {};
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+export { abortableSleep, createAbortableStream, once, untilAborted } from "./abortable";
+export * from "./async";
+export * from "./color";
+export * from "./dirs";
+export * from "./env";
+export * from "./format";
+export * from "./frontmatter";
+export * from "./fs-error";
+export * from "./glob";
+export * from "./hook-fetch";
+export {
+	getLocale,
+	getLocaleDisplayName,
+	initI18n,
+	LOCALE_DISPLAY_NAMES,
+	mapToSupportedLocale,
+	registerLocales,
+	setLocale,
+	t,
+} from "./i18n";
+export * from "./json";
+export * as logger from "./logger";
+export * from "./mermaid-ascii";
+export * from "./mermaid-color";
+export * from "./mime";
+export * from "./models-yml";
+export * from "./peek-file";
+export * as postmortem from "./postmortem";
+export * as procmgr from "./procmgr";
+export { setNativeKillTree } from "./procmgr";
+export * as prompt from "./prompt";
+export * as ptree from "./ptree";
+export { AbortError, ChildProcess, Exception, NonZeroExitError } from "./ptree";
+export * from "./snowflake";
+export * from "./stream";
+export * from "./tab-spacing";
+export * from "./temp";
+export * from "./type-guards";
+export * from "./which";
+export * from "./xcsh-context-paths";
+export * from "./xcsh-context-resolver";
+export * from "./xcsh-env-names";
+
+function isPlainObject(val: object): val is Record<string, unknown> {
+	return Object.getPrototypeOf(val) === Object.prototype || Array.isArray(val);
+}
+
+export function structuredCloneJSON<T>(value: T): T {
+	// primitives|null|undefined, copy
+	if (!value || typeof value !== "object") {
+		return value;
+	}
+
+	// deep clone
+	if (isPlainObject(value)) {
+		try {
+			return structuredClone(value);
+		} catch {
+			// might still fail due to nested structures
+		}
+	}
+	return JSON.parse(JSON.stringify(value)) as T;
+}

package/src/json.ts

@@ -0,0 +1,10 @@
+/**
+ * Try to parse JSON, returning null on failure.
+ */
+export function tryParseJson<T = unknown>(content: string): T | null {
+	try {
+		return JSON.parse(content) as T;
+	} catch {
+		return null;
+	}
+}

package/src/logger.ts

@@ -0,0 +1,204 @@
+/**
+ * Centralized file logger for xcsh.
+ *
+ * Logs to ~/.xcsh/logs/ with size-based rotation, supporting concurrent xcsh instances.
+ * Each log entry includes process.pid for traceability.
+ */
+import * as fs from "node:fs";
+import winston from "winston";
+import DailyRotateFile from "winston-daily-rotate-file";
+import { getLogsDir } from "./dirs";
+
+/** Ensure logs directory exists */
+function ensureLogsDir(): string {
+	const logsDir = getLogsDir();
+	if (!fs.existsSync(logsDir)) {
+		fs.mkdirSync(logsDir, { recursive: true });
+	}
+	return logsDir;
+}
+
+/** Custom format that includes pid and flattens metadata */
+const logFormat = winston.format.combine(
+	winston.format.timestamp({ format: "YYYY-MM-DDTHH:mm:ss.SSSZ" }),
+	winston.format.printf(({ timestamp, level, message, ...meta }) => {
+		const entry: Record<string, unknown> = {
+			timestamp,
+			level,
+			pid: process.pid,
+			message,
+		};
+		// Flatten metadata into entry
+		for (const [key, value] of Object.entries(meta)) {
+			if (key !== "level" && key !== "timestamp" && key !== "message") {
+				entry[key] = value;
+			}
+		}
+		return JSON.stringify(entry);
+	}),
+);
+
+/** Size-based rotating file transport */
+const fileTransport = new DailyRotateFile({
+	dirname: ensureLogsDir(),
+	filename: "xcsh.%DATE%.log",
+	datePattern: "YYYY-MM-DD",
+	maxSize: "10m",
+	maxFiles: 5,
+	zippedArchive: true,
+});
+
+/** The winston logger instance */
+const winstonLogger = winston.createLogger({
+	level: "debug",
+	format: logFormat,
+	transports: [fileTransport],
+	// Don't exit on error - logging failures shouldn't crash the app
+	exitOnError: false,
+});
+
+/**
+ * Log an error message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export function error(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.error(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+/**
+ * Log a warning message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export function warn(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.warn(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+/**
+ * Log a debug message.
+ * @param message - The message to log.
+ * @param context - The context to log.
+ */
+export function debug(message: string, context?: Record<string, unknown>): void {
+	try {
+		winstonLogger.debug(message, context);
+	} catch {
+		// Silently ignore logging failures
+	}
+}
+
+const LOGGED_TIMING_THRESHOLD_MS = 5;
+
+/** Sequential wall-clock markers (next marker closes the previous segment). */
+let gTimings: [op: string, ts: number][] = [];
+
+/** Await-accurate durations (safe for parallel work; sums can overlap). */
+let gAsyncSpans: [op: string, durationMs: number][] = [];
+
+/** Whether to record timings. */
+let gRecordTimings = false;
+
+/**
+ * Print collected timings to stderr.
+ * Wall segments are gaps between consecutive {@link time} markers only; they are wrong when
+ * concurrent code also calls {@link time} (e.g. parallel capability loads). Use {@link timeAsync}
+ * for those awaits instead.
+ */
+export function printTimings(): void {
+	if (!gRecordTimings || gTimings.length === 0) {
+		console.error("\n--- Startup Timings ---\n(no markers)\n");
+		return;
+	}
+
+	const endTs = performance.now();
+	gTimings.push(["(end)", endTs]);
+
+	console.error("\n--- Startup timings (wall segments between time() markers) ---");
+	const firstTs = gTimings[0][1];
+	for (let i = 0; i < gTimings.length - 1; i++) {
+		const [op, ts] = gTimings[i];
+		const [, nextTs] = gTimings[i + 1];
+		const dur = nextTs - ts;
+		if (dur > LOGGED_TIMING_THRESHOLD_MS) {
+			console.error(`  ${op}: ${dur}ms`);
+		}
+	}
+	console.error(`  span (first marker → end): ${endTs - firstTs}ms`);
+
+	if (gAsyncSpans.length > 0) {
+		console.error("\n--- Async (await-accurate; parallel spans may overlap) ---");
+		for (const [op, dur] of gAsyncSpans) {
+			if (dur > LOGGED_TIMING_THRESHOLD_MS) {
+				console.error(`  ${op}: ${dur}ms`);
+			}
+		}
+	}
+
+	console.error("------------------------\n");
+
+	gTimings.pop();
+}
+
+/**
+ * Begin recording startup timings. Seeds the timeline so the first segment is meaningful.
+ */
+export function startTiming(): void {
+	gTimings = [["(startup)", performance.now()]];
+	gAsyncSpans = [];
+	gRecordTimings = true;
+}
+
+/**
+ * End timing window and clear buffers.
+ */
+export function endTiming(): void {
+	gTimings = [];
+	gAsyncSpans = [];
+	gRecordTimings = false;
+}
+
+function recordAsyncSpan(op: string, start: number): void {
+	const dur = performance.now() - start;
+	if (dur > LOGGED_TIMING_THRESHOLD_MS) {
+		gAsyncSpans.push([op, dur]);
+	}
+}
+
+/**
+ * Wall-clock segment boundary: duration for this label runs until the next {@link time} call.
+ * Do not use across `await` when other tasks may call {@link time}; use {@link timeAsync} for the awaited work.
+ */
+export function time(op: string): void;
+export function time<T, A extends unknown[]>(op: string, fn: (...args: A) => T, ...args: A): T;
+export function time<T, A extends unknown[]>(op: string, fn?: (...args: A) => T, ...args: A): T | undefined {
+	if (fn === undefined) {
+		if (gRecordTimings) {
+			gTimings.push([op, performance.now()]);
+		}
+		return undefined as T;
+	} else if (gRecordTimings) {
+		const start = performance.now();
+		try {
+			const result = fn(...args);
+			if (result instanceof Promise) {
+				return result.finally(recordAsyncSpan.bind(null, op, start)) as T;
+			}
+			recordAsyncSpan(op, start);
+			return result;
+		} catch (error) {
+			recordAsyncSpan(op, start);
+			throw error;
+		}
+	} else {
+		return fn(...args);
+	}
+}

package/src/mermaid-ascii.ts

@@ -0,0 +1,31 @@
+import { type AsciiRenderOptions, renderMermaidASCII } from "beautiful-mermaid";
+
+export type { AsciiRenderOptions as MermaidAsciiRenderOptions };
+
+export function renderMermaidAscii(source: string, options?: AsciiRenderOptions): string {
+	return renderMermaidASCII(source, options);
+}
+
+export function renderMermaidAsciiSafe(source: string, options?: AsciiRenderOptions): string | null {
+	try {
+		return renderMermaidASCII(source, options);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Extract mermaid code blocks from markdown text.
+ */
+export function extractMermaidBlocks(markdown: string): { source: string; hash: bigint | number }[] {
+	const blocks: { source: string; hash: bigint | number }[] = [];
+	const regex = /```mermaid\s*\n([\s\S]*?)```/g;
+
+	for (let match = regex.exec(markdown); match !== null; match = regex.exec(markdown)) {
+		const source = match[1].trim();
+		const hash = Bun.hash(source);
+		blocks.push({ source, hash });
+	}
+
+	return blocks;
+}