@oh-my-pi-zen/pi-utils 16.3.6-zen.1

package/src/vendor/mermaid-ascii/xychart/colors.ts

@@ -0,0 +1,140 @@
+// ============================================================================
+// XY Chart — shared color palette
+//
+// Generates monochromatic shades from the theme accent color.
+// Series 0 = accent (or blue fallback). Series 1+ are darker/lighter
+// shades of the same hue with subtle hue drift to stay in the same
+// color family (like navy ↔ cyan from blue).
+//
+// Used by both the SVG and ASCII renderers.
+// ============================================================================
+
+/** Default accent for charts when the theme doesn't provide one. */
+export const CHART_ACCENT_FALLBACK = '#3b82f6' // blue-500
+
+// ---------------------------------------------------------------------------
+// HSL ↔ Hex conversion
+// ---------------------------------------------------------------------------
+
+function hexToHsl(hex: string): [number, number, number] {
+  const h = hex.replace('#', '')
+  const ri = parseInt(h.substring(0, 2), 16) / 255
+  const gi = parseInt(h.substring(2, 4), 16) / 255
+  const bi = parseInt(h.substring(4, 6), 16) / 255
+
+  const max = Math.max(ri, gi, bi)
+  const min = Math.min(ri, gi, bi)
+  const l = (max + min) / 2
+
+  if (max === min) return [0, 0, l * 100]
+
+  const d = max - min
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+
+  let hue: number
+  if (max === ri) hue = ((gi - bi) / d + (gi < bi ? 6 : 0)) / 6
+  else if (max === gi) hue = ((bi - ri) / d + 2) / 6
+  else hue = ((ri - gi) / d + 4) / 6
+
+  return [hue * 360, s * 100, l * 100]
+}
+
+function hslToHex(h: number, s: number, l: number): string {
+  const si = s / 100
+  const li = l / 100
+
+  const c = (1 - Math.abs(2 * li - 1)) * si
+  const x = c * (1 - Math.abs(((h / 60) % 2) - 1))
+  const m = li - c / 2
+
+  let r: number, g: number, b: number
+  if (h < 60) { r = c; g = x; b = 0 }
+  else if (h < 120) { r = x; g = c; b = 0 }
+  else if (h < 180) { r = 0; g = c; b = x }
+  else if (h < 240) { r = 0; g = x; b = c }
+  else if (h < 300) { r = x; g = 0; b = c }
+  else { r = c; g = 0; b = x }
+
+  const toHex = (v: number) => Math.round((v + m) * 255).toString(16).padStart(2, '0')
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`
+}
+
+// ---------------------------------------------------------------------------
+// Hex ↔ RGB conversion
+// ---------------------------------------------------------------------------
+
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace('#', '')
+  return [
+    parseInt(h.substring(0, 2), 16),
+    parseInt(h.substring(2, 4), 16),
+    parseInt(h.substring(4, 6), 16),
+  ]
+}
+
+function rgbToHex(r: number, g: number, b: number): string {
+  const toHex = (v: number) => Math.round(Math.max(0, Math.min(255, v))).toString(16).padStart(2, '0')
+  return `#${toHex(r)}${toHex(g)}${toHex(b)}`
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/** Check whether a string is a valid 6-digit hex color (e.g. "#3b82f6"). */
+export function isValidHex(color: string): boolean {
+  return /^#[0-9a-fA-F]{6}$/.test(color)
+}
+
+/**
+ * Detect whether a background color is dark (lightness < 50%).
+ */
+export function isDarkBackground(bgHex: string): boolean {
+  return hexToHsl(bgHex)[2] < 50
+}
+
+/**
+ * Mix two hex colors in RGB space.
+ * `ratio` controls how much of `fgHex` shows: 0 = pure bg, 1 = pure fg.
+ * Equivalent to alpha-compositing fg over bg at the given opacity.
+ */
+export function mixHexColors(bgHex: string, fgHex: string, ratio: number): string {
+  const [br, bg, bb] = hexToRgb(bgHex)
+  const [fr, fg, fb] = hexToRgb(fgHex)
+  const inv = 1 - ratio
+  return rgbToHex(br * inv + fr * ratio, bg * inv + fg * ratio, bb * inv + fb * ratio)
+}
+
+/**
+ * Get the hex color for a series index.
+ * Index 0 returns the accent color as-is.
+ * Index 1+ alternate between darker and lighter shades of the same hue
+ * with subtle hue drift (±8-12° per tier) to stay in the same family.
+ *
+ * When `bgColor` is provided, shade direction adapts to the background:
+ *   - Light bg: odd = darker, even = lighter (default)
+ *   - Dark bg:  odd = lighter, even = darker (so shades stay visible)
+ */
+export function getSeriesColor(index: number, accentColor: string, bgColor?: string): string {
+  if (index === 0) return accentColor
+  // Fall back to defaults when inputs aren't valid hex (e.g. CSS variable refs like "var(--accent)")
+  const safeAccent = isValidHex(accentColor) ? accentColor : CHART_ACCENT_FALLBACK
+  const safeBg = bgColor && isValidHex(bgColor) ? bgColor : undefined
+  const [h, s] = hexToHsl(safeAccent)
+  const chartS = Math.max(55, Math.min(85, s))
+
+  const tier = Math.ceil(index / 2)
+  const oddIndex = index % 2 === 1
+
+  // On dark backgrounds, flip: odd = lighter, even = darker
+  const dark = safeBg && isDarkBackground(safeBg) ? !oddIndex : oddIndex
+  const l = dark
+    ? Math.max(25, 48 - tier * 13)
+    : Math.min(78, 55 + tier * 11)
+
+  // Subtle hue drift: darker shades shift slightly negative, lighter shift positive
+  const hShift = (dark ? -8 : 12) * tier
+  const newH = ((h + hShift) % 360 + 360) % 360
+
+  return hslToHex(newH, chartS, l)
+}

package/src/vendor/mermaid-ascii/xychart/parser.ts

@@ -0,0 +1,115 @@
+import type { XYChart, XYAxis, XYChartSeries } from './types'
+
+// ============================================================================
+// XY Chart parser
+//
+// Parses Mermaid xychart-beta syntax into a typed XYChart structure.
+//
+// Supported directives:
+//   xychart-beta [horizontal]
+//   title "Chart Title"
+//   x-axis [label1, label2, ...]          — categorical
+//   x-axis min --> max                     — numeric range
+//   x-axis "Axis Title" [label1, ...]      — with title
+//   x-axis "Axis Title" min --> max        — with title
+//   y-axis (same patterns)
+//   bar [val1, val2, ...]
+//   line [val1, val2, ...]
+// ============================================================================
+
+/**
+ * Parse a Mermaid xychart-beta diagram from preprocessed lines.
+ * Lines should already be trimmed and comment-stripped.
+ */
+export function parseXYChart(lines: string[]): XYChart {
+  const xAxis: XYAxis = {}
+  const yAxis: XYAxis = {}
+  const series: XYChartSeries[] = []
+  let title: string | undefined
+  let horizontal = false
+
+  for (const line of lines) {
+    // Header line — detect horizontal
+    if (/^xychart(-beta)?\b/i.test(line)) {
+      if (/\bhorizontal\b/i.test(line)) horizontal = true
+      continue
+    }
+
+    // Title
+    const titleMatch = line.match(/^title\s+"([^"]+)"/)
+    if (titleMatch) {
+      title = titleMatch[1]
+      continue
+    }
+
+    // x-axis with categories: x-axis "Title" [a, b, c] or x-axis [a, b, c]
+    const xCatMatch = line.match(/^x-axis\s+(?:"([^"]*)"\s*)?\[([^\]]+)\]/)
+    if (xCatMatch) {
+      if (xCatMatch[1]) xAxis.title = xCatMatch[1]
+      xAxis.categories = xCatMatch[2]!.split(',').map(s => s.trim())
+      continue
+    }
+
+    // x-axis with range: x-axis "Title" min --> max or x-axis min --> max
+    const xRangeMatch = line.match(/^x-axis\s+(?:"([^"]*)"\s+)?(-?\d+(?:\.\d+)?)\s*-->\s*(-?\d+(?:\.\d+)?)/)
+    if (xRangeMatch) {
+      if (xRangeMatch[1]) xAxis.title = xRangeMatch[1]
+      xAxis.range = { min: parseFloat(xRangeMatch[2]!), max: parseFloat(xRangeMatch[3]!) }
+      continue
+    }
+
+    // y-axis with range: y-axis "Title" min --> max or y-axis min --> max
+    const yRangeMatch = line.match(/^y-axis\s+(?:"([^"]*)"\s+)?(-?\d+(?:\.\d+)?)\s*-->\s*(-?\d+(?:\.\d+)?)/)
+    if (yRangeMatch) {
+      if (yRangeMatch[1]) yAxis.title = yRangeMatch[1]
+      yAxis.range = { min: parseFloat(yRangeMatch[2]!), max: parseFloat(yRangeMatch[3]!) }
+      continue
+    }
+
+    // y-axis with just title (no range)
+    const yTitleOnly = line.match(/^y-axis\s+"([^"]+)"\s*$/)
+    if (yTitleOnly) {
+      yAxis.title = yTitleOnly[1]
+      continue
+    }
+
+    // bar [...]
+    const barMatch = line.match(/^bar\s+\[([^\]]+)\]/)
+    if (barMatch) {
+      series.push({ type: 'bar', data: parseNumericArray(barMatch[1]!) })
+      continue
+    }
+
+    // line [...]
+    const lineMatch = line.match(/^line\s+\[([^\]]+)\]/)
+    if (lineMatch) {
+      series.push({ type: 'line', data: parseNumericArray(lineMatch[1]!) })
+      continue
+    }
+  }
+
+  // Auto-derive y-axis range from data if not specified
+  if (!yAxis.range && series.length > 0) {
+    const allValues = series.flatMap(s => s.data)
+    let min = Math.min(...allValues)
+    let max = Math.max(...allValues)
+    const span = max - min || 1
+    // Add 10% padding
+    min = min - span * 0.1
+    max = max + span * 0.1
+    // Floor to 0 if all values are positive and min is close to 0
+    if (min > 0 && min < span * 0.5) min = 0
+    yAxis.range = { min, max }
+  }
+
+  // Fallback y-axis range
+  if (!yAxis.range) {
+    yAxis.range = { min: 0, max: 100 }
+  }
+
+  return { title, horizontal, xAxis, yAxis, series }
+}
+
+function parseNumericArray(str: string): number[] {
+  return str.split(',').map(s => parseFloat(s.trim()))
+}

package/src/vendor/mermaid-ascii/xychart/types.ts

@@ -0,0 +1,150 @@
+// ============================================================================
+// XY Chart types
+//
+// Models the parsed and positioned representations of a Mermaid xychart-beta
+// diagram. Supports bar charts, line charts, and combinations with categorical
+// or numeric x-axes.
+// ============================================================================
+
+/** Parsed XY chart — logical structure from mermaid text */
+export interface XYChart {
+  /** Optional chart title */
+  title?: string
+  /** Chart orientation: vertical (default) or horizontal */
+  horizontal: boolean
+  /** X-axis configuration */
+  xAxis: XYAxis
+  /** Y-axis configuration */
+  yAxis: XYAxis
+  /** Data series (bar and/or line) */
+  series: XYChartSeries[]
+}
+
+/** Axis configuration — categorical (labels) or numeric (range) */
+export interface XYAxis {
+  /** Optional axis title/label */
+  title?: string
+  /** Categorical labels (e.g., ["jan", "feb", "mar"]) — mutually exclusive with range */
+  categories?: string[]
+  /** Numeric range — mutually exclusive with categories */
+  range?: { min: number; max: number }
+}
+
+/** A single data series (bar or line) */
+export interface XYChartSeries {
+  /** Series type */
+  type: 'bar' | 'line'
+  /** Data values — one per category, or evenly spaced across numeric range */
+  data: number[]
+}
+
+// ============================================================================
+// Positioned XY chart — ready for SVG rendering
+// ============================================================================
+
+export interface PositionedXYChart {
+  width: number
+  height: number
+  /** Whether this is a horizontal (rotated) chart */
+  horizontal?: boolean
+  /** Title text and position (if present) */
+  title?: PositionedTitle
+  /** Positioned x-axis with tick marks and labels */
+  xAxis: PositionedAxis
+  /** Positioned y-axis with tick marks and labels */
+  yAxis: PositionedAxis
+  /** The plot area bounds (inside axes) */
+  plotArea: PlotArea
+  /** Positioned bar groups */
+  bars: PositionedBar[]
+  /** Positioned line polylines */
+  lines: PositionedLine[]
+  /** Horizontal grid lines for readability */
+  gridLines: GridLine[]
+  /** Legend items (shown when multiple series) */
+  legend: LegendItem[]
+}
+
+export interface LegendItem {
+  /** Display label */
+  label: string
+  /** Position of the swatch/icon */
+  x: number
+  y: number
+  /** Series type determines swatch shape (rect for bar, line+dot for line) */
+  type: 'bar' | 'line'
+  /** Series index within its type (for layout grouping) */
+  seriesIndex: number
+  /** Global color index across all series (for unified color assignment) */
+  colorIndex: number
+}
+
+export interface PositionedTitle {
+  text: string
+  x: number
+  y: number
+}
+
+export interface PositionedAxis {
+  /** Optional axis title text and position */
+  title?: { text: string; x: number; y: number; rotate?: number }
+  /** Tick positions along the axis */
+  ticks: AxisTick[]
+  /** Axis line: start and end coordinates */
+  line: { x1: number; y1: number; x2: number; y2: number }
+}
+
+export interface AxisTick {
+  /** Label text for this tick */
+  label: string
+  /** Position of the tick mark on the axis */
+  x: number
+  y: number
+  /** End of the tick mark (short perpendicular line) */
+  tx: number
+  ty: number
+  /** Label anchor position */
+  labelX: number
+  labelY: number
+  /** Text anchor for label */
+  textAnchor: 'start' | 'middle' | 'end'
+}
+
+export interface PlotArea {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface PositionedBar {
+  /** Bar rectangle in SVG coordinates */
+  x: number
+  y: number
+  width: number
+  height: number
+  /** Original data value */
+  value: number
+  /** Category label for this bar (e.g. "Jan") */
+  label?: string
+  /** Series index within bar type (for layout grouping) */
+  seriesIndex: number
+  /** Global color index across all series */
+  colorIndex: number
+}
+
+export interface PositionedLine {
+  /** Polyline points */
+  points: Array<{ x: number; y: number; value: number; label?: string }>
+  /** Series index within line type (for layout grouping) */
+  seriesIndex: number
+  /** Global color index across all series */
+  colorIndex: number
+}
+
+export interface GridLine {
+  x1: number
+  y1: number
+  x2: number
+  y2: number
+}

package/src/which.ts

@@ -0,0 +1,232 @@
+// OS-agnostic "which" helper with robust macOS toolchain lookup and flexible cache control.
+//
+// - Falls back to macOS Xcode/CLT toolchain directories if standard `Bun.which()` fails on Darwin.
+//   Resolves the active developer directory via $DEVELOPER_DIR / /var/db/xcode_select_link symlink
+//   to avoid spawning xcrun subprocesses.
+// - Supports four cache modes (`none`, `fresh`, `ro`, `cached`) for control over discovery cost and determinism.
+// - Computes a stable cache key from command + options to avoid redundant lookups within a process.
+// - Returns path to resolved binary or null if not found.
+//
+
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+type CacheKey = string | bigint | number;
+
+// Tools shipped by Xcode / Command Line Tools that callers actually look up.
+// Keeps the set small so darwinWhich can fast-reject non-Xcode commands without
+// touching the filesystem.  Only needs entries for binaries that live *exclusively*
+// in toolchain dirs (not on a typical $PATH).
+const XCODE_BINS = new Set([
+	// Compilers & driver aliases
+	"clang",
+	"clang++",
+	"gcc",
+	"g++",
+	"cc",
+	"c++",
+	"cpp",
+	"c89",
+	"c99",
+	"swift",
+	"swiftc",
+	"swift-frontend",
+	// Language servers (LSP)
+	"clangd",
+	"sourcekit-lsp",
+	// Linker & archive tools
+	"ld",
+	"ld-classic",
+	"ar",
+	"ranlib",
+	"libtool",
+	"as",
+	"lipo",
+	"install_name_tool",
+	"codesign_allocate",
+	// Build utilities
+	"make",
+	"gnumake",
+	"m4",
+	"flex",
+	"bison",
+	"yacc",
+	"lex",
+	// VCS (CLT ships git)
+	"git",
+	"git-receive-pack",
+	"git-upload-pack",
+	"git-upload-archive",
+	"git-shell",
+	"scalar",
+	// Debugger
+	"lldb",
+	"lldb-dap",
+	// Binary inspection
+	"nm",
+	"otool",
+	"objdump",
+	"strings",
+	"strip",
+	"size",
+	"dsymutil",
+	"dwarfdump",
+	"lipo",
+	"vtool",
+	// Clang tooling
+	"clang-format",
+	"swift-format",
+]);
+
+// Prefixes for versioned binaries (e.g. python3.9, pip3.12, pydoc3.9, 2to3-3.9)
+const XCODE_BIN_PREFIXES = ["python", "pip", "pydoc", "2to3"];
+
+function isXcodeBin(command: string): boolean {
+	if (XCODE_BINS.has(command)) return true;
+	for (const prefix of XCODE_BIN_PREFIXES) {
+		if (command.startsWith(prefix)) return true;
+	}
+	return false;
+}
+
+// Resolve the active Xcode developer directory once, without spawning any process.
+// Priority: $DEVELOPER_DIR env → /var/db/xcode_select_link symlink → common fallback paths.
+function getDeveloperDirs(): string | null {
+	// 1. Explicit env override
+	const envDir = process.env.DEVELOPER_DIR;
+	if (envDir && fs.existsSync(envDir)) {
+		return envDir;
+	}
+
+	// 2. xcode-select stores the active path as a symlink
+	try {
+		return fs.readlinkSync("/var/db/xcode_select_link");
+	} catch {
+		// symlink may not exist on minimal installs
+	}
+	// 3. Common locations
+	for (const candidate of ["/Applications/Xcode.app/Contents/Developer", "/Library/Developer/CommandLineTools"]) {
+		if (fs.existsSync(candidate)) {
+			return candidate;
+		}
+	}
+	return null;
+}
+
+// Build the list of extra toolchain bin directories to check on macOS.
+// Computed lazily once from the resolved developer directory.
+let macosToolPaths: Map<string, string> | undefined;
+function getMacosToolPaths(): Map<string, string> {
+	if (macosToolPaths) return macosToolPaths;
+	const paths: string[] = [
+		// Always check Command Line Tools (may be independent of Xcode)
+		"/Library/Developer/CommandLineTools/usr/bin",
+	];
+	const devDir = getDeveloperDirs();
+	if (devDir) {
+		paths.push(path.join(devDir, "usr/bin"), path.join(devDir, "Toolchains/XcodeDefault.xctoolchain/usr/bin"));
+	}
+
+	// Deduplicate (e.g. devDir may already be CommandLineTools)
+	macosToolPaths = new Map<string, string>();
+	for (const dir of Array.from(new Set(paths))) {
+		try {
+			for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+				if (entry.isFile() || entry.isSymbolicLink()) {
+					if (macosToolPaths.has(entry.name)) {
+						continue;
+					}
+					macosToolPaths.set(entry.name, path.join(dir, entry.name));
+				}
+			}
+		} catch {
+			// dir doesn't exist or isn't readable
+		}
+	}
+	return macosToolPaths;
+}
+
+// Map: cache key -> resolved binary path or null (not found)
+const toolCache = new Map<CacheKey, string | null>();
+
+/**
+ * Cache policy for which lookups.
+ */
+export const enum WhichCachePolicy {
+	/**
+	 * Use cached result if available.
+	 */
+	Cached = 0,
+	/**
+	 * Bypass cache and perform a new lookup.
+	 */
+	Bypass,
+	/**
+	 * Always update cache.
+	 */
+	Fresh,
+	/**
+	 * Read-only, serves from cache if present, but doesn't write.
+	 */
+	ReadOnly,
+}
+
+// Extension: additional cache policy for tool path lookup
+export interface WhichOptions extends Bun.WhichOptions {
+	/**
+	 * Cache policy for the lookup.
+	 * Defaults to `WhichCachePolicy.Fresh`.
+	 */
+	cache?: WhichCachePolicy;
+}
+
+// Darwin-specific "which" shim: consult Xcode/CLT toolchain directories after $PATH.
+// Uses cached directory listings instead of per-command existsSync or xcrun subprocesses.
+function darwinWhich(command: string, _options?: Bun.WhichOptions): string | null {
+	const regular = Bun.which(command);
+	if (regular) return regular;
+	if (isXcodeBin(command)) {
+		return getMacosToolPaths().get(command) ?? null;
+	}
+	return null;
+}
+
+// Which function that incorporates Darwin Xcode logic if platform reports as 'darwin'
+export const whichFresh = os.platform() === "darwin" ? darwinWhich : Bun.which;
+
+// Derive stable cache key from command and lookup options
+function cacheKey(command: string, options?: Bun.WhichOptions): CacheKey {
+	if (!options) return command;
+	if (!options.cwd && !options.PATH) return command;
+	let h = Bun.hash(command);
+	if (options.cwd) h = Bun.hash(options.cwd, h);
+	if (options.PATH) h = Bun.hash(options.PATH, h);
+	return h;
+}
+
+/**
+ * Locate binary on PATH (with flexible caching).
+ *
+ * @param command - Binary name to resolve
+ * @param options - Bun.WhichOptions plus `cache` control
+ * @returns Filesystem path if found, else null
+ */
+export function $which(command: string, options?: WhichOptions): string | null {
+	const cachePolicy = options?.cache ?? WhichCachePolicy.Cached;
+	let key: CacheKey | undefined;
+
+	if (cachePolicy !== WhichCachePolicy.Bypass) {
+		key = cacheKey(command, options);
+		if (cachePolicy !== WhichCachePolicy.Fresh) {
+			const cached = toolCache.get(key);
+			if (cached !== undefined) return cached;
+		}
+	}
+
+	const result = whichFresh(command, options);
+	if (key != null && cachePolicy !== WhichCachePolicy.ReadOnly) {
+		toolCache.set(key, result);
+	}
+	return result;
+}